[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
www/software/perl perl.html manual/index.html m...
|
From: |
karl |
|
Subject: |
www/software/perl perl.html manual/index.html m... |
|
Date: |
Sat, 28 May 2016 15:55:23 +0000 (UTC) |
CVSROOT: /web/www
Module name: www
Changes by: karl <karl> 16/05/28 15:55:22
Modified files:
software/perl : perl.html
Removed files:
software/perl/manual: index.html perldoc-all.dvi.gz
perldoc-all.html perldoc-all.html.gz
perldoc-all.html_chapter.tar.gz
perldoc-all.info.tar.gz perldoc-all.pdf
perldoc-all.texi.tar.gz
Log message:
remove manual/ subdir entry (and link), no evidence of interest
CVSWeb URLs:
http://web.cvs.savannah.gnu.org/viewcvs/www/software/perl/perl.html?cvsroot=www&r1=1.5&r2=1.6
http://web.cvs.savannah.gnu.org/viewcvs/www/software/perl/manual/index.html?cvsroot=www&r1=1.11&r2=0
http://web.cvs.savannah.gnu.org/viewcvs/www/software/perl/manual/perldoc-all.dvi.gz?cvsroot=www&r1=1.10&r2=0
http://web.cvs.savannah.gnu.org/viewcvs/www/software/perl/manual/perldoc-all.html?cvsroot=www&r1=1.10&r2=0
http://web.cvs.savannah.gnu.org/viewcvs/www/software/perl/manual/perldoc-all.html.gz?cvsroot=www&r1=1.10&r2=0
http://web.cvs.savannah.gnu.org/viewcvs/www/software/perl/manual/perldoc-all.html_chapter.tar.gz?cvsroot=www&r1=1.10&r2=0
http://web.cvs.savannah.gnu.org/viewcvs/www/software/perl/manual/perldoc-all.info.tar.gz?cvsroot=www&r1=1.10&r2=0
http://web.cvs.savannah.gnu.org/viewcvs/www/software/perl/manual/perldoc-all.pdf?cvsroot=www&rev=0
http://web.cvs.savannah.gnu.org/viewcvs/www/software/perl/manual/perldoc-all.texi.tar.gz?cvsroot=www&r1=1.10&r2=0
Patches:
Index: perl.html
===================================================================
RCS file: /web/www/www/software/perl/perl.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- perl.html 7 Sep 2013 21:31:43 -0000 1.5
+++ perl.html 28 May 2016 15:54:42 -0000 1.6
@@ -11,9 +11,5 @@
<p>For more information and to download the software, please see the <a
href="http://www.perl.org";>perl.org home page</a>.
-<p>We do make use of this directory on www.gnu.org to make available a <a
-href="manual/">Texinfo translation of the Perl documentation</a> for the
-latest stable Perl release.
-
</body>
</html>
Index: manual/index.html
===================================================================
RCS file: manual/index.html
diff -N manual/index.html
--- manual/index.html 21 Jan 2016 00:18:58 -0000 1.11
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,76 +0,0 @@
-<!--#include virtual="/server/header.html" -->
-<title>Perl documentation in Texinfo - GNU Project - Free Software Foundation
(FSF)</title>
-<!--#include virtual="/server/banner.html" -->
-<h2>Perl documentation in Texinfo</h2>
-
-<address>GNU Project</address>
-<address>last updated January 20, 2016</address>
-
-<p>This translation of the <a href="http://perldoc.perl.org/";>Perl
-documentation</a> from POD to Texinfo is not official, and not endorsed
-by the Perl developers (indeed, they haven't seen it). It was created
-by the GNU Texinfo developers because they found it useful to have the
-core Perl documentation available in Info and other formats, and thought
-they would share the results. Suggestions welcome.</p>
-
-<p>This output is created entirely by the Texinfo tools; see the <a
-href="http://cvs.savannah.gnu.org/viewvc/texinfo/contrib/perldoc-all/?root=texinfo";>contrib/perldoc-all</a>
-directory in the Texinfo sources for the procedure used.</p>
-
-<p>This documentation (perldoc-all) is available in the following formats:</p>
-
-<ul>
-<li><a href="perldoc-all.html">HTML
- (5608K bytes)</a> - entirely on one web page.</li>
-<li><a href="html_chapter/index.html">HTML</a> - with one web page per
- chapter.</li>
-<li><a href="perldoc-all.html.gz">HTML compressed
- (1360K gzipped characters)</a> - entirely on
- one web page.</li>
-<li><a href="perldoc-all.html_chapter.tar.gz">HTML compressed
- (1820K gzipped tar file)</a> -
- with one web page per chapter.</li>
-<li><a href="perldoc-all.info.tar.gz">Info document
- (1220K bytes gzipped tar file)</a>.</li>
-<li><a href="perldoc-all.dvi.gz">TeX dvi file
- (1812K bytes gzipped)</a>.</li>
-<li><a href="perldoc-all.pdf">PDF file
- (4120K bytes)</a>.</li>
-<li><a href="perldoc-all.texi.tar.gz">Texinfo source
- (1164K bytes gzipped tar file).</a></li>
-</ul>
-
-<p>You can <a href="http://shop.fsf.org/";>buy printed copies of
-some manuals</a> (among other items) from the Free Software Foundation;
-this helps support FSF activities.</p>
-
-<p>(This page generated by the <a
href="http://git.savannah.gnu.org/cgit/gnulib.git/plain/build-aux/gendocs.sh";>gendocs.sh
-script</a>.)</p>
-
-<!-- If needed, change the copyright block at the bottom. In general,
- all pages on the GNU web server should have the section about
- verbatim copying. Please do NOT remove this without talking
- with the webmasters first.
- Please make sure the copyright date is consistent with the document
- and that it is like this: "2001, 2002", not this: "2001-2002". -->
-</div><!-- for id="content", starts in the include above -->
-<!--#include virtual="/server/footer.html" -->
-<div id="footer">
-
-<p>Please send general FSF & GNU inquiries to
-<a href="mailto:address@hidden";><address@hidden></a>.
-There are also <a href="/contact/">other ways to contact</a>
-the FSF.<br />
-Please send broken links and other corrections or suggestions to
-<a href="mailto:address@hidden";><address@hidden></a>.</p>
-
-<p>Copyright © 2013 Free Software Foundation, Inc.</p>
-
-<p>This page is licensed under a <a rel="license"
-href="http://creativecommons.org/licenses/by-nd/3.0/us/";>Creative
-Commons Attribution-NoDerivs 3.0 United States License</a>.</p>
-
-</div>
-</div>
-</body>
-</html>
Index: manual/perldoc-all.dvi.gz
===================================================================
RCS file: manual/perldoc-all.dvi.gz
diff -N manual/perldoc-all.dvi.gz
Binary files /tmp/cvs26h3g6 and /dev/null differ
Index: manual/perldoc-all.html
===================================================================
RCS file: manual/perldoc-all.html
diff -N manual/perldoc-all.html
--- manual/perldoc-all.html 21 Jan 2016 00:19:00 -0000 1.10
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,111287 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
-<html>
-<!-- Created by Texinfo 6.0.91+dev, http://www.gnu.org/software/texinfo/ -->
-<head>
-<title>Perl pod documentation</title>
-
-<meta name="description" content="Perl pod documentation">
-<meta name="keywords" content="Perl pod documentation">
-<meta name="resource-type" content="document">
-<meta name="distribution" content="global">
-<meta name="Generator" content="texi2any">
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
-<link href="#Top" rel="start" title="Top">
-<link href="#SEC_Contents" rel="contents" title="Table of Contents">
-<link href="dir.html#Top" rel="up" title="(dir)">
-<style type="text/css">
-<!--
-a.summary-letter {text-decoration: none}
-blockquote.indentedblock {margin-right: 0em}
-blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
-blockquote.smallquotation {font-size: smaller}
-div.display {margin-left: 3.2em}
-div.example {margin-left: 3.2em}
-div.lisp {margin-left: 3.2em}
-div.smalldisplay {margin-left: 3.2em}
-div.smallexample {margin-left: 3.2em}
-div.smalllisp {margin-left: 3.2em}
-kbd {font-style: oblique}
-pre.display {font-family: inherit}
-pre.format {font-family: inherit}
-pre.menu-comment {font-family: serif}
-pre.menu-preformatted {font-family: serif}
-pre.smalldisplay {font-family: inherit; font-size: smaller}
-pre.smallexample {font-size: smaller}
-pre.smallformat {font-family: inherit; font-size: smaller}
-pre.smalllisp {font-size: smaller}
-span.nocodebreak {white-space: nowrap}
-span.nolinebreak {white-space: nowrap}
-span.roman {font-family: initial; font-weight: normal}
-span.sansserif {font-family: sans-serif; font-weight: normal}
-ul.no-bullet {list-style: none}
--->
-</style>
-<link rel="stylesheet" type="text/css" href="/software/gnulib/manual.css">
-
-
-</head>
-
-<body lang="en">
-<h1 class="settitle" align="center">Perl pod documentation</h1>
-
-<a name="SEC_Overview"></a>
-<h2 class="shortcontents-heading">Short Table of Contents</h2>
-
-<div class="shortcontents">
-<ul class="no-bullet">
-<li><a name="stoc-perl-1" href="#toc-perl-1">1 perl</a></li>
-<li><a name="stoc-perlapio-1" href="#toc-perlapio-1">2 perlapio</a></li>
-<li><a name="stoc-perlartistic-1" href="#toc-perlartistic-1">3
perlartistic</a></li>
-<li><a name="stoc-perlbook-1" href="#toc-perlbook-1">4 perlbook</a></li>
-<li><a name="stoc-perlboot-1" href="#toc-perlboot-1">5 perlboot</a></li>
-<li><a name="stoc-perlbot-1" href="#toc-perlbot-1">6 perlbot</a></li>
-<li><a name="stoc-perlcall-1" href="#toc-perlcall-1">7 perlcall</a></li>
-<li><a name="stoc-perlcheat-1" href="#toc-perlcheat-1">8 perlcheat</a></li>
-<li><a name="stoc-perlclib-1" href="#toc-perlclib-1">9 perlclib</a></li>
-<li><a name="stoc-perlcommunity-1" href="#toc-perlcommunity-1">10
perlcommunity</a></li>
-<li><a name="stoc-perldata-1" href="#toc-perldata-1">11 perldata</a></li>
-<li><a name="stoc-perldbmfilter-1" href="#toc-perldbmfilter-1">12
perldbmfilter</a></li>
-<li><a name="stoc-perldebguts-1" href="#toc-perldebguts-1">13
perldebguts</a></li>
-<li><a name="stoc-perldebtut-1" href="#toc-perldebtut-1">14 perldebtut</a></li>
-<li><a name="stoc-perldebug-1" href="#toc-perldebug-1">15 perldebug</a></li>
-<li><a name="stoc-perldiag-1" href="#toc-perldiag-1">16 perldiag</a></li>
-<li><a name="stoc-perldsc-1" href="#toc-perldsc-1">17 perldsc</a></li>
-<li><a name="stoc-perldtrace-1" href="#toc-perldtrace-1">18 perldtrace</a></li>
-<li><a name="stoc-perlebcdic-1" href="#toc-perlebcdic-1">19 perlebcdic</a></li>
-<li><a name="stoc-perlembed-1" href="#toc-perlembed-1">20 perlembed</a></li>
-<li><a name="stoc-perlexperiment-1" href="#toc-perlexperiment-1">21
perlexperiment</a></li>
-<li><a name="stoc-perlfilter-1" href="#toc-perlfilter-1">22 perlfilter</a></li>
-<li><a name="stoc-perlfork-1" href="#toc-perlfork-1">23 perlfork</a></li>
-<li><a name="stoc-perlform-1" href="#toc-perlform-1">24 perlform</a></li>
-<li><a name="stoc-perlfunc-1" href="#toc-perlfunc-1">25 perlfunc</a></li>
-<li><a name="stoc-perlgit-1" href="#toc-perlgit-1">26 perlgit</a></li>
-<li><a name="stoc-perlgpl-1" href="#toc-perlgpl-1">27 perlgpl</a></li>
-<li><a name="stoc-perlguts-1" href="#toc-perlguts-1">28 perlguts</a></li>
-<li><a name="stoc-perlhack-1" href="#toc-perlhack-1">29 perlhack</a></li>
-<li><a name="stoc-perlhacktips-1" href="#toc-perlhacktips-1">30
perlhacktips</a></li>
-<li><a name="stoc-perlhacktut-1" href="#toc-perlhacktut-1">31
perlhacktut</a></li>
-<li><a name="stoc-perlhist-1" href="#toc-perlhist-1">32 perlhist</a></li>
-<li><a name="stoc-perlinterp-1" href="#toc-perlinterp-1">33 perlinterp</a></li>
-<li><a name="stoc-perlintro-1" href="#toc-perlintro-1">34 perlintro</a></li>
-<li><a name="stoc-perliol-1" href="#toc-perliol-1">35 perliol</a></li>
-<li><a name="stoc-perlipc-1" href="#toc-perlipc-1">36 perlipc</a></li>
-<li><a name="stoc-perllexwarn-1" href="#toc-perllexwarn-1">37
perllexwarn</a></li>
-<li><a name="stoc-perllocale-1" href="#toc-perllocale-1">38 perllocale</a></li>
-<li><a name="stoc-perllol-1" href="#toc-perllol-1">39 perllol</a></li>
-<li><a name="stoc-perlmod-2" href="#toc-perlmod-2">40 perlmod</a></li>
-<li><a name="stoc-perlmodinstall-1" href="#toc-perlmodinstall-1">41
perlmodinstall</a></li>
-<li><a name="stoc-perlmodstyle-1" href="#toc-perlmodstyle-1">42
perlmodstyle</a></li>
-<li><a name="stoc-perlmroapi-1" href="#toc-perlmroapi-1">43 perlmroapi</a></li>
-<li><a name="stoc-perlnewmod-1" href="#toc-perlnewmod-1">44 perlnewmod</a></li>
-<li><a name="stoc-perlnumber-1" href="#toc-perlnumber-1">45 perlnumber</a></li>
-<li><a name="stoc-perlobj-2" href="#toc-perlobj-2">46 perlobj</a></li>
-<li><a name="stoc-perlootut-1" href="#toc-perlootut-1">47 perlootut</a></li>
-<li><a name="stoc-perlop-2" href="#toc-perlop-2">48 perlop</a></li>
-<li><a name="stoc-perlopentut-1" href="#toc-perlopentut-1">49
perlopentut</a></li>
-<li><a name="stoc-perlpacktut-1" href="#toc-perlpacktut-1">50
perlpacktut</a></li>
-<li><a name="stoc-perlperf-1" href="#toc-perlperf-1">51 perlperf</a></li>
-<li><a name="stoc-perlpod-1" href="#toc-perlpod-1">52 perlpod</a></li>
-<li><a name="stoc-perlpodspec-1" href="#toc-perlpodspec-1">53
perlpodspec</a></li>
-<li><a name="stoc-perlpodstyle-1" href="#toc-perlpodstyle-1">54
perlpodstyle</a></li>
-<li><a name="stoc-perlpolicy-1" href="#toc-perlpolicy-1">55 perlpolicy</a></li>
-<li><a name="stoc-perlport-1" href="#toc-perlport-1">56 perlport</a></li>
-<li><a name="stoc-perlpragma-1" href="#toc-perlpragma-1">57 perlpragma</a></li>
-<li><a name="stoc-perlre-1" href="#toc-perlre-1">58 perlre</a></li>
-<li><a name="stoc-perlreapi-1" href="#toc-perlreapi-1">59 perlreapi</a></li>
-<li><a name="stoc-perlrebackslash-1" href="#toc-perlrebackslash-1">60
perlrebackslash</a></li>
-<li><a name="stoc-perlrecharclass-1" href="#toc-perlrecharclass-1">61
perlrecharclass</a></li>
-<li><a name="stoc-perlref-1" href="#toc-perlref-1">62 perlref</a></li>
-<li><a name="stoc-perlreftut-1" href="#toc-perlreftut-1">63 perlreftut</a></li>
-<li><a name="stoc-perlreguts-1" href="#toc-perlreguts-1">64 perlreguts</a></li>
-<li><a name="stoc-perlrepository-1" href="#toc-perlrepository-1">65
perlrepository</a></li>
-<li><a name="stoc-perlrequick-1" href="#toc-perlrequick-1">66
perlrequick</a></li>
-<li><a name="stoc-perlreref-1" href="#toc-perlreref-1">67 perlreref</a></li>
-<li><a name="stoc-perlretut-10" href="#toc-perlretut-10">68 perlretut</a></li>
-<li><a name="stoc-perlrun-1" href="#toc-perlrun-1">69 perlrun</a></li>
-<li><a name="stoc-perlsec-1" href="#toc-perlsec-1">70 perlsec</a></li>
-<li><a name="stoc-perlsource-1" href="#toc-perlsource-1">71 perlsource</a></li>
-<li><a name="stoc-perlstyle-1" href="#toc-perlstyle-1">72 perlstyle</a></li>
-<li><a name="stoc-perlsub-2" href="#toc-perlsub-2">73 perlsub</a></li>
-<li><a name="stoc-perlsyn-2" href="#toc-perlsyn-2">74 perlsyn</a></li>
-<li><a name="stoc-perlthrtut-1" href="#toc-perlthrtut-1">75 perlthrtut</a></li>
-<li><a name="stoc-perltie-1" href="#toc-perltie-1">76 perltie</a></li>
-<li><a name="stoc-perltodo-1" href="#toc-perltodo-1">77 perltodo</a></li>
-<li><a name="stoc-perltooc-1" href="#toc-perltooc-1">78 perltooc</a></li>
-<li><a name="stoc-perltoot-1" href="#toc-perltoot-1">79 perltoot</a></li>
-<li><a name="stoc-perltrap-1" href="#toc-perltrap-1">80 perltrap</a></li>
-<li><a name="stoc-perlunicode-1" href="#toc-perlunicode-1">81
perlunicode</a></li>
-<li><a name="stoc-perlunifaq-1" href="#toc-perlunifaq-1">82 perlunifaq</a></li>
-<li><a name="stoc-perluniintro-1" href="#toc-perluniintro-1">83
perluniintro</a></li>
-<li><a name="stoc-perlunitut-1" href="#toc-perlunitut-1">84 perlunitut</a></li>
-<li><a name="stoc-perlutil-1" href="#toc-perlutil-1">85 perlutil</a></li>
-<li><a name="stoc-perlvar-1" href="#toc-perlvar-1">86 perlvar</a></li>
-<li><a name="stoc-perlvms-1" href="#toc-perlvms-1">87 perlvms</a></li>
-</ul>
-</div>
-
-<a name="SEC_Contents"></a>
-<h2 class="contents-heading">Table of Contents</h2>
-
-<div class="contents">
-
-<ul class="no-bullet">
- <li><a name="toc-perl-1" href="#perl">1 perl</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME" href="#perl-NAME">1.1 NAME</a></li>
- <li><a name="toc-SYNOPSIS" href="#perl-SYNOPSIS">1.2 SYNOPSIS</a></li>
- <li><a name="toc-GETTING-HELP" href="#perl-GETTING-HELP">1.3 GETTING
HELP</a>
- <ul class="no-bullet">
- <li><a name="toc-Overview" href="#perl-Overview">1.3.1 Overview</a></li>
- <li><a name="toc-Tutorials" href="#perl-Tutorials">1.3.2
Tutorials</a></li>
- <li><a name="toc-Reference-Manual" href="#perl-Reference-Manual">1.3.3
Reference Manual</a></li>
- <li><a name="toc-Internals-and-C-Language-Interface"
href="#perl-Internals-and-C-Language-Interface">1.3.4 Internals and C Language
Interface</a></li>
- <li><a name="toc-Miscellaneous" href="#perl-Miscellaneous">1.3.5
Miscellaneous</a></li>
- <li><a name="toc-Language_002dSpecific"
href="#perl-Language_002dSpecific">1.3.6 Language-Specific</a></li>
- <li><a name="toc-Platform_002dSpecific"
href="#perl-Platform_002dSpecific">1.3.7 Platform-Specific</a></li>
- <li><a name="toc-Stubs-for-Deleted-Documents"
href="#perl-Stubs-for-Deleted-Documents">1.3.8 Stubs for Deleted
Documents</a></li>
- </ul></li>
- <li><a name="toc-DESCRIPTION" href="#perl-DESCRIPTION">1.4
DESCRIPTION</a></li>
- <li><a name="toc-AVAILABILITY" href="#perl-AVAILABILITY">1.5
AVAILABILITY</a></li>
- <li><a name="toc-ENVIRONMENT" href="#perl-ENVIRONMENT">1.6
ENVIRONMENT</a></li>
- <li><a name="toc-AUTHOR" href="#perl-AUTHOR">1.7 AUTHOR</a></li>
- <li><a name="toc-FILES" href="#perl-FILES">1.8 FILES</a></li>
- <li><a name="toc-SEE-ALSO" href="#perl-SEE-ALSO">1.9 SEE ALSO</a></li>
- <li><a name="toc-DIAGNOSTICS" href="#perl-DIAGNOSTICS">1.10
DIAGNOSTICS</a></li>
- <li><a name="toc-BUGS" href="#perl-BUGS">1.11 BUGS</a></li>
- <li><a name="toc-NOTES" href="#perl-NOTES">1.12 NOTES</a></li>
- </ul></li>
- <li><a name="toc-perlapio-1" href="#perlapio">2 perlapio</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-1" href="#perlapio-NAME">2.1 NAME</a></li>
- <li><a name="toc-SYNOPSIS-1" href="#perlapio-SYNOPSIS">2.2
SYNOPSIS</a></li>
- <li><a name="toc-DESCRIPTION-1" href="#perlapio-DESCRIPTION">2.3
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Co_002dexistence-with-stdio"
href="#perlapio-Co_002dexistence-with-stdio">2.3.1 Co-existence with
stdio</a></li>
- <li><a name="toc-_0022Fast-gets_0022-Functions"
href="#perlapio-_0022Fast-gets_0022-Functions">2.3.2 "Fast gets"
Functions</a></li>
- <li><a name="toc-Other-Functions" href="#perlapio-Other-Functions">2.3.3
Other Functions</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlartistic-1" href="#perlartistic">3 perlartistic</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-2" href="#perlartistic-NAME">3.1 NAME</a></li>
- <li><a name="toc-SYNOPSIS-2" href="#perlartistic-SYNOPSIS">3.2
SYNOPSIS</a></li>
- <li><a name="toc-DESCRIPTION-2" href="#perlartistic-DESCRIPTION">3.3
DESCRIPTION</a></li>
- <li><a name="toc-The-_0022Artistic-License_0022"
href="#perlartistic-The-_0022Artistic-License_0022">3.4 The "Artistic
License"</a>
- <ul class="no-bullet">
- <li><a name="toc-Preamble" href="#perlartistic-Preamble">3.4.1
Preamble</a></li>
- <li><a name="toc-Definitions" href="#perlartistic-Definitions">3.4.2
Definitions</a></li>
- <li><a name="toc-Conditions" href="#perlartistic-Conditions">3.4.3
Conditions</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlbook-1" href="#perlbook">4 perlbook</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-3" href="#perlbook-NAME">4.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-3" href="#perlbook-DESCRIPTION">4.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-The-most-popular-books"
href="#perlbook-The-most-popular-books">4.2.1 The most popular books</a></li>
- <li><a name="toc-References" href="#perlbook-References">4.2.2
References</a></li>
- <li><a name="toc-Tutorials-1" href="#perlbook-Tutorials">4.2.3
Tutorials</a></li>
- <li><a name="toc-Task_002dOriented"
href="#perlbook-Task_002dOriented">4.2.4 Task-Oriented</a></li>
- <li><a name="toc-Special-Topics" href="#perlbook-Special-Topics">4.2.5
Special Topics</a></li>
- <li><a name="toc-Free-_0028as-in-beer_0029-books"
href="#perlbook-Free-_0028as-in-beer_0029-books">4.2.6 Free (as in beer)
books</a></li>
- <li><a name="toc-Other-interesting_002c-non_002dPerl-books"
href="#perlbook-Other-interesting_002c-non_002dPerl-books">4.2.7 Other
interesting, non-Perl books</a></li>
- <li><a name="toc-A-note-on-freshness"
href="#perlbook-A-note-on-freshness">4.2.8 A note on freshness</a></li>
- <li><a name="toc-Get-your-book-listed"
href="#perlbook-Get-your-book-listed">4.2.9 Get your book listed</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlboot-1" href="#perlboot">5 perlboot</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-4" href="#perlboot-NAME">5.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-4" href="#perlboot-DESCRIPTION">5.2
DESCRIPTION</a></li>
- </ul></li>
- <li><a name="toc-perlbot-1" href="#perlbot">6 perlbot</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-5" href="#perlbot-NAME">6.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-5" href="#perlbot-DESCRIPTION">6.2
DESCRIPTION</a></li>
- </ul></li>
- <li><a name="toc-perlcall-1" href="#perlcall">7 perlcall</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-6" href="#perlcall-NAME">7.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-6" href="#perlcall-DESCRIPTION">7.2
DESCRIPTION</a></li>
- <li><a name="toc-THE-CALL_005f-FUNCTIONS"
href="#perlcall-THE-CALL_005f-FUNCTIONS">7.3 THE CALL_ FUNCTIONS</a></li>
- <li><a name="toc-FLAG-VALUES" href="#perlcall-FLAG-VALUES">7.4 FLAG
VALUES</a>
- <ul class="no-bullet">
- <li><a name="toc-G_005fVOID" href="#perlcall-G_005fVOID">7.4.1
G_VOID</a></li>
- <li><a name="toc-G_005fSCALAR" href="#perlcall-G_005fSCALAR">7.4.2
G_SCALAR</a></li>
- <li><a name="toc-G_005fARRAY" href="#perlcall-G_005fARRAY">7.4.3
G_ARRAY</a></li>
- <li><a name="toc-G_005fDISCARD" href="#perlcall-G_005fDISCARD">7.4.4
G_DISCARD</a></li>
- <li><a name="toc-G_005fNOARGS" href="#perlcall-G_005fNOARGS">7.4.5
G_NOARGS</a></li>
- <li><a name="toc-G_005fEVAL" href="#perlcall-G_005fEVAL">7.4.6
G_EVAL</a></li>
- <li><a name="toc-G_005fKEEPERR" href="#perlcall-G_005fKEEPERR">7.4.7
G_KEEPERR</a></li>
- <li><a name="toc-Determining-the-Context"
href="#perlcall-Determining-the-Context">7.4.8 Determining the Context</a></li>
- </ul></li>
- <li><a name="toc-EXAMPLES" href="#perlcall-EXAMPLES">7.5 EXAMPLES</a>
- <ul class="no-bullet">
- <li><a name="toc-No-Parameters_002c-Nothing-Returned"
href="#perlcall-No-Parameters_002c-Nothing-Returned">7.5.1 No Parameters,
Nothing Returned</a></li>
- <li><a name="toc-Passing-Parameters"
href="#perlcall-Passing-Parameters">7.5.2 Passing Parameters</a></li>
- <li><a name="toc-Returning-a-Scalar"
href="#perlcall-Returning-a-Scalar">7.5.3 Returning a Scalar</a></li>
- <li><a name="toc-Returning-a-List-of-Values"
href="#perlcall-Returning-a-List-of-Values">7.5.4 Returning a List of
Values</a></li>
- <li><a name="toc-Returning-a-List-in-a-Scalar-Context"
href="#perlcall-Returning-a-List-in-a-Scalar-Context">7.5.5 Returning a List in
a Scalar Context</a></li>
- <li><a name="toc-Returning-Data-from-Perl-via-the-Parameter-List"
href="#perlcall-Returning-Data-from-Perl-via-the-Parameter-List">7.5.6
Returning Data from Perl via the Parameter List</a></li>
- <li><a name="toc-Using-G_005fEVAL"
href="#perlcall-Using-G_005fEVAL">7.5.7 Using G_EVAL</a></li>
- <li><a name="toc-Using-G_005fKEEPERR"
href="#perlcall-Using-G_005fKEEPERR">7.5.8 Using G_KEEPERR</a></li>
- <li><a name="toc-Using-call_005fsv"
href="#perlcall-Using-call_005fsv">7.5.9 Using call_sv</a></li>
- <li><a name="toc-Using-call_005fargv"
href="#perlcall-Using-call_005fargv">7.5.10 Using call_argv</a></li>
- <li><a name="toc-Using-call_005fmethod"
href="#perlcall-Using-call_005fmethod">7.5.11 Using call_method</a></li>
- <li><a name="toc-Using-GIMME_005fV"
href="#perlcall-Using-GIMME_005fV">7.5.12 Using GIMME_V</a></li>
- <li><a name="toc-Using-Perl-to-Dispose-of-Temporaries"
href="#perlcall-Using-Perl-to-Dispose-of-Temporaries">7.5.13 Using Perl to
Dispose of Temporaries</a></li>
- <li><a name="toc-Strategies-for-Storing-Callback-Context-Information"
href="#perlcall-Strategies-for-Storing-Callback-Context-Information">7.5.14
Strategies for Storing Callback Context Information</a></li>
- <li><a name="toc-Alternate-Stack-Manipulation"
href="#perlcall-Alternate-Stack-Manipulation">7.5.15 Alternate Stack
Manipulation</a></li>
- <li><a name="toc-Creating-and-Calling-an-Anonymous-Subroutine-in-C"
href="#perlcall-Creating-and-Calling-an-Anonymous-Subroutine-in-C">7.5.16
Creating and Calling an Anonymous Subroutine in C</a></li>
- </ul></li>
- <li><a name="toc-LIGHTWEIGHT-CALLBACKS"
href="#perlcall-LIGHTWEIGHT-CALLBACKS">7.6 LIGHTWEIGHT CALLBACKS</a></li>
- <li><a name="toc-SEE-ALSO-1" href="#perlcall-SEE-ALSO">7.7 SEE
ALSO</a></li>
- <li><a name="toc-AUTHOR-1" href="#perlcall-AUTHOR">7.8 AUTHOR</a></li>
- <li><a name="toc-DATE" href="#perlcall-DATE">7.9 DATE</a></li>
- </ul></li>
- <li><a name="toc-perlcheat-1" href="#perlcheat">8 perlcheat</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-7" href="#perlcheat-NAME">8.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-7" href="#perlcheat-DESCRIPTION">8.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-The-sheet" href="#perlcheat-The-sheet">8.2.1 The
sheet</a></li>
- </ul></li>
- <li><a name="toc-ACKNOWLEDGEMENTS" href="#perlcheat-ACKNOWLEDGEMENTS">8.3
ACKNOWLEDGEMENTS</a></li>
- <li><a name="toc-AUTHOR-2" href="#perlcheat-AUTHOR">8.4 AUTHOR</a></li>
- <li><a name="toc-SEE-ALSO-2" href="#perlcheat-SEE-ALSO">8.5 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlclib-1" href="#perlclib">9 perlclib</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-8" href="#perlclib-NAME">9.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-8" href="#perlclib-DESCRIPTION">9.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Conventions" href="#perlclib-Conventions">9.2.1
Conventions</a></li>
- <li><a name="toc-File-Operations" href="#perlclib-File-Operations">9.2.2
File Operations</a></li>
- <li><a name="toc-File-Input-and-Output"
href="#perlclib-File-Input-and-Output">9.2.3 File Input and Output</a></li>
- <li><a name="toc-File-Positioning"
href="#perlclib-File-Positioning">9.2.4 File Positioning</a></li>
- <li><a name="toc-Memory-Management-and-String-Handling"
href="#perlclib-Memory-Management-and-String-Handling">9.2.5 Memory Management
and String Handling</a></li>
- <li><a name="toc-Character-Class-Tests"
href="#perlclib-Character-Class-Tests">9.2.6 Character Class Tests</a></li>
- <li><a name="toc-stdlib_002eh-functions"
href="#perlclib-stdlib_002eh-functions">9.2.7 <samp>stdlib.h</samp>
functions</a></li>
- <li><a name="toc-Miscellaneous-functions"
href="#perlclib-Miscellaneous-functions">9.2.8 Miscellaneous functions</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-3" href="#perlclib-SEE-ALSO">9.3 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlcommunity-1" href="#perlcommunity">10 perlcommunity</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-9" href="#perlcommunity-NAME">10.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-9" href="#perlcommunity-DESCRIPTION">10.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Where-to-Find-the-Community"
href="#perlcommunity-Where-to-Find-the-Community">10.2.1 Where to Find the
Community</a></li>
- <li><a name="toc-Mailing-Lists-and-Newsgroups"
href="#perlcommunity-Mailing-Lists-and-Newsgroups">10.2.2 Mailing Lists and
Newsgroups</a></li>
- <li><a name="toc-IRC" href="#perlcommunity-IRC">10.2.3 IRC</a></li>
- <li><a name="toc-Websites" href="#perlcommunity-Websites">10.2.4
Websites</a>
- <ul class="no-bullet">
- <li><a name="toc-News-sites" href="#perlcommunity-News-sites">10.2.4.1
News sites</a></li>
- <li><a name="toc-Forums" href="#perlcommunity-Forums">10.2.4.2
Forums</a></li>
- </ul></li>
- <li><a name="toc-User-Groups" href="#perlcommunity-User-Groups">10.2.5
User Groups</a></li>
- <li><a name="toc-Workshops" href="#perlcommunity-Workshops">10.2.6
Workshops</a></li>
- <li><a name="toc-Hackathons" href="#perlcommunity-Hackathons">10.2.7
Hackathons</a></li>
- <li><a name="toc-Conventions-1" href="#perlcommunity-Conventions">10.2.8
Conventions</a></li>
- <li><a name="toc-Calendar-of-Perl-Events"
href="#perlcommunity-Calendar-of-Perl-Events">10.2.9 Calendar of Perl
Events</a></li>
- </ul></li>
- <li><a name="toc-AUTHOR-3" href="#perlcommunity-AUTHOR">10.3
AUTHOR</a></li>
- </ul></li>
- <li><a name="toc-perldata-1" href="#perldata">11 perldata</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-10" href="#perldata-NAME">11.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-10" href="#perldata-DESCRIPTION">11.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Variable-names" href="#perldata-Variable-names">11.2.1
Variable names</a></li>
- <li><a name="toc-Identifier-parsing"
href="#perldata-Identifier-parsing">11.2.2 Identifier parsing</a></li>
- <li><a name="toc-Context" href="#perldata-Context">11.2.3
Context</a></li>
- <li><a name="toc-Scalar-values" href="#perldata-Scalar-values">11.2.4
Scalar values</a></li>
- <li><a name="toc-Scalar-value-constructors"
href="#perldata-Scalar-value-constructors">11.2.5 Scalar value constructors</a>
- <ul class="no-bullet">
- <li><a
name="toc-Special-floating-point_003a-infinity-_0028Inf_0029-and-not_002da_002dnumber-_0028NaN_0029"
href="#perldata-Special-floating-point_003a-infinity-_0028Inf_0029-and-not_002da_002dnumber-_0028NaN_0029">11.2.5.1
Special floating point: infinity (Inf) and not-a-number (NaN)</a></li>
- <li><a name="toc-Version-Strings"
href="#perldata-Version-Strings">11.2.5.2 Version Strings</a></li>
- <li><a name="toc-Special-Literals"
href="#perldata-Special-Literals">11.2.5.3 Special Literals</a></li>
- <li><a name="toc-Barewords" href="#perldata-Barewords">11.2.5.4
Barewords</a></li>
- <li><a name="toc-Array-Interpolation"
href="#perldata-Array-Interpolation">11.2.5.5 Array Interpolation</a></li>
- </ul></li>
- <li><a name="toc-List-value-constructors"
href="#perldata-List-value-constructors">11.2.6 List value constructors</a></li>
- <li><a name="toc-Subscripts" href="#perldata-Subscripts">11.2.7
Subscripts</a></li>
- <li><a name="toc-Multi_002ddimensional-array-emulation"
href="#perldata-Multi_002ddimensional-array-emulation">11.2.8 Multi-dimensional
array emulation</a></li>
- <li><a name="toc-Slices" href="#perldata-Slices">11.2.9 Slices</a>
- <ul class="no-bullet">
- <li><a name="toc-Key_002fValue-Hash-Slices"
href="#perldata-Key_002fValue-Hash-Slices">11.2.9.1 Key/Value Hash
Slices</a></li>
- <li><a name="toc-Index_002fValue-Array-Slices"
href="#perldata-Index_002fValue-Array-Slices">11.2.9.2 Index/Value Array
Slices</a></li>
- </ul></li>
- <li><a name="toc-Typeglobs-and-Filehandles"
href="#perldata-Typeglobs-and-Filehandles">11.2.10 Typeglobs and
Filehandles</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-4" href="#perldata-SEE-ALSO">11.3 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perldbmfilter-1" href="#perldbmfilter">12 perldbmfilter</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-11" href="#perldbmfilter-NAME">12.1 NAME</a></li>
- <li><a name="toc-SYNOPSIS-3" href="#perldbmfilter-SYNOPSIS">12.2
SYNOPSIS</a></li>
- <li><a name="toc-DESCRIPTION-11" href="#perldbmfilter-DESCRIPTION">12.3
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-The-Filter" href="#perldbmfilter-The-Filter">12.3.1 The
Filter</a></li>
- <li><a name="toc-An-Example_003a-the-NULL-termination-problem_002e"
href="#perldbmfilter-An-Example_003a-the-NULL-termination-problem_002e">12.3.2
An Example: the NULL termination problem.</a></li>
- <li><a name="toc-Another-Example_003a-Key-is-a-C-int_002e"
href="#perldbmfilter-Another-Example_003a-Key-is-a-C-int_002e">12.3.3 Another
Example: Key is a C int.</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-5" href="#perldbmfilter-SEE-ALSO">12.4 SEE
ALSO</a></li>
- <li><a name="toc-AUTHOR-4" href="#perldbmfilter-AUTHOR">12.5
AUTHOR</a></li>
- </ul></li>
- <li><a name="toc-perldebguts-1" href="#perldebguts">13 perldebguts</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-12" href="#perldebguts-NAME">13.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-12" href="#perldebguts-DESCRIPTION">13.2
DESCRIPTION</a></li>
- <li><a name="toc-Debugger-Internals"
href="#perldebguts-Debugger-Internals">13.3 Debugger Internals</a>
- <ul class="no-bullet">
- <li><a name="toc-Writing-Your-Own-Debugger"
href="#perldebguts-Writing-Your-Own-Debugger">13.3.1 Writing Your Own
Debugger</a>
- <ul class="no-bullet">
- <li><a name="toc-Environment-Variables"
href="#perldebguts-Environment-Variables">13.3.1.1 Environment
Variables</a></li>
- <li><a name="toc-Debugger-Internal-Variables"
href="#perldebguts-Debugger-Internal-Variables">13.3.1.2 Debugger Internal
Variables</a></li>
- <li><a name="toc-Debugger-Customization-Functions"
href="#perldebguts-Debugger-Customization-Functions">13.3.1.3 Debugger
Customization Functions</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-Frame-Listing-Output-Examples"
href="#perldebguts-Frame-Listing-Output-Examples">13.4 Frame Listing Output
Examples</a></li>
- <li><a name="toc-Debugging-Regular-Expressions"
href="#perldebguts-Debugging-Regular-Expressions">13.5 Debugging Regular
Expressions</a>
- <ul class="no-bullet">
- <li><a name="toc-Compile_002dtime-Output"
href="#perldebguts-Compile_002dtime-Output">13.5.1 Compile-time Output</a></li>
- <li><a name="toc-Types-of-Nodes"
href="#perldebguts-Types-of-Nodes">13.5.2 Types of Nodes</a></li>
- <li><a name="toc-Run_002dtime-Output"
href="#perldebguts-Run_002dtime-Output">13.5.3 Run-time Output</a></li>
- </ul></li>
- <li><a name="toc-Debugging-Perl-Memory-Usage"
href="#perldebguts-Debugging-Perl-Memory-Usage">13.6 Debugging Perl Memory
Usage</a>
- <ul class="no-bullet">
- <li><a name="toc-Using-_0024ENV_007bPERL_005fDEBUG_005fMSTATS_007d"
href="#perldebguts-Using-_0024ENV_007bPERL_005fDEBUG_005fMSTATS_007d">13.6.1
Using <code>$ENV{PERL_DEBUG_MSTATS}</code></a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-6" href="#perldebguts-SEE-ALSO">13.7 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perldebtut-1" href="#perldebtut">14 perldebtut</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-13" href="#perldebtut-NAME">14.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-13" href="#perldebtut-DESCRIPTION">14.2
DESCRIPTION</a></li>
- <li><a name="toc-use-strict" href="#perldebtut-use-strict">14.3 use
strict</a></li>
- <li><a name="toc-Looking-at-data-and-_002dw-and-v"
href="#perldebtut-Looking-at-data-and-_002dw-and-v">14.4 Looking at data and -w
and v</a></li>
- <li><a name="toc-help" href="#perldebtut-help">14.5 help</a></li>
- <li><a name="toc-Stepping-through-code"
href="#perldebtut-Stepping-through-code">14.6 Stepping through code</a></li>
- <li><a name="toc-Placeholder-for-a_002c-w_002c-t_002c-T"
href="#perldebtut-Placeholder-for-a_002c-w_002c-t_002c-T">14.7 Placeholder for
a, w, t, T</a></li>
- <li><a name="toc-REGULAR-EXPRESSIONS"
href="#perldebtut-REGULAR-EXPRESSIONS">14.8 REGULAR EXPRESSIONS</a></li>
- <li><a name="toc-OUTPUT-TIPS" href="#perldebtut-OUTPUT-TIPS">14.9 OUTPUT
TIPS</a></li>
- <li><a name="toc-CGI" href="#perldebtut-CGI">14.10 CGI</a></li>
- <li><a name="toc-GUIs" href="#perldebtut-GUIs">14.11 GUIs</a></li>
- <li><a name="toc-SUMMARY" href="#perldebtut-SUMMARY">14.12 SUMMARY</a></li>
- <li><a name="toc-SEE-ALSO-7" href="#perldebtut-SEE-ALSO">14.13 SEE
ALSO</a></li>
- <li><a name="toc-AUTHOR-5" href="#perldebtut-AUTHOR">14.14 AUTHOR</a></li>
- <li><a name="toc-CONTRIBUTORS" href="#perldebtut-CONTRIBUTORS">14.15
CONTRIBUTORS</a></li>
- </ul></li>
- <li><a name="toc-perldebug-1" href="#perldebug">15 perldebug</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-14" href="#perldebug-NAME">15.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-14" href="#perldebug-DESCRIPTION">15.2
DESCRIPTION</a></li>
- <li><a name="toc-The-Perl-Debugger"
href="#perldebug-The-Perl-Debugger">15.3 The Perl Debugger</a>
- <ul class="no-bullet">
- <li><a name="toc-Calling-the-Debugger"
href="#perldebug-Calling-the-Debugger">15.3.1 Calling the Debugger</a></li>
- <li><a name="toc-Debugger-Commands"
href="#perldebug-Debugger-Commands">15.3.2 Debugger Commands</a></li>
- <li><a name="toc-Configurable-Options"
href="#perldebug-Configurable-Options">15.3.3 Configurable Options</a></li>
- <li><a name="toc-Debugger-Input_002fOutput"
href="#perldebug-Debugger-Input_002fOutput">15.3.4 Debugger
Input/Output</a></li>
- <li><a name="toc-Debugging-Compile_002dTime-Statements"
href="#perldebug-Debugging-Compile_002dTime-Statements">15.3.5 Debugging
Compile-Time Statements</a></li>
- <li><a name="toc-Debugger-Customization"
href="#perldebug-Debugger-Customization">15.3.6 Debugger Customization</a></li>
- <li><a name="toc-Readline-Support-_002f-History-in-the-Debugger"
href="#perldebug-Readline-Support-_002f-History-in-the-Debugger">15.3.7
Readline Support / History in the Debugger</a></li>
- <li><a name="toc-Editor-Support-for-Debugging"
href="#perldebug-Editor-Support-for-Debugging">15.3.8 Editor Support for
Debugging</a></li>
- <li><a name="toc-The-Perl-Profiler"
href="#perldebug-The-Perl-Profiler">15.3.9 The Perl Profiler</a></li>
- </ul></li>
- <li><a name="toc-Debugging-Regular-Expressions-1"
href="#perldebug-Debugging-Regular-Expressions">15.4 Debugging Regular
Expressions</a></li>
- <li><a name="toc-Debugging-Memory-Usage"
href="#perldebug-Debugging-Memory-Usage">15.5 Debugging Memory Usage</a></li>
- <li><a name="toc-SEE-ALSO-8" href="#perldebug-SEE-ALSO">15.6 SEE
ALSO</a></li>
- <li><a name="toc-BUGS-1" href="#perldebug-BUGS">15.7 BUGS</a></li>
- </ul></li>
- <li><a name="toc-perldiag-1" href="#perldiag">16 perldiag</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-15" href="#perldiag-NAME">16.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-15" href="#perldiag-DESCRIPTION">16.2
DESCRIPTION</a></li>
- <li><a name="toc-SEE-ALSO-9" href="#perldiag-SEE-ALSO">16.3 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perldsc-1" href="#perldsc">17 perldsc</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-16" href="#perldsc-NAME">17.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-16" href="#perldsc-DESCRIPTION">17.2
DESCRIPTION</a></li>
- <li><a name="toc-REFERENCES" href="#perldsc-REFERENCES">17.3
REFERENCES</a></li>
- <li><a name="toc-COMMON-MISTAKES" href="#perldsc-COMMON-MISTAKES">17.4
COMMON MISTAKES</a></li>
- <li><a name="toc-CAVEAT-ON-PRECEDENCE"
href="#perldsc-CAVEAT-ON-PRECEDENCE">17.5 CAVEAT ON PRECEDENCE</a></li>
- <li><a name="toc-WHY-YOU-SHOULD-ALWAYS-use-strict"
href="#perldsc-WHY-YOU-SHOULD-ALWAYS-use-strict">17.6 WHY YOU SHOULD ALWAYS
<code>use strict</code></a></li>
- <li><a name="toc-DEBUGGING" href="#perldsc-DEBUGGING">17.7
DEBUGGING</a></li>
- <li><a name="toc-CODE-EXAMPLES" href="#perldsc-CODE-EXAMPLES">17.8 CODE
EXAMPLES</a></li>
- <li><a name="toc-ARRAYS-OF-ARRAYS" href="#perldsc-ARRAYS-OF-ARRAYS">17.9
ARRAYS OF ARRAYS</a>
- <ul class="no-bullet">
- <li><a name="toc-Declaration-of-an-ARRAY-OF-ARRAYS"
href="#perldsc-Declaration-of-an-ARRAY-OF-ARRAYS">17.9.1 Declaration of an
ARRAY OF ARRAYS</a></li>
- <li><a name="toc-Generation-of-an-ARRAY-OF-ARRAYS"
href="#perldsc-Generation-of-an-ARRAY-OF-ARRAYS">17.9.2 Generation of an ARRAY
OF ARRAYS</a></li>
- <li><a name="toc-Access-and-Printing-of-an-ARRAY-OF-ARRAYS"
href="#perldsc-Access-and-Printing-of-an-ARRAY-OF-ARRAYS">17.9.3 Access and
Printing of an ARRAY OF ARRAYS</a></li>
- </ul></li>
- <li><a name="toc-HASHES-OF-ARRAYS" href="#perldsc-HASHES-OF-ARRAYS">17.10
HASHES OF ARRAYS</a>
- <ul class="no-bullet">
- <li><a name="toc-Declaration-of-a-HASH-OF-ARRAYS"
href="#perldsc-Declaration-of-a-HASH-OF-ARRAYS">17.10.1 Declaration of a HASH
OF ARRAYS</a></li>
- <li><a name="toc-Generation-of-a-HASH-OF-ARRAYS"
href="#perldsc-Generation-of-a-HASH-OF-ARRAYS">17.10.2 Generation of a HASH OF
ARRAYS</a></li>
- <li><a name="toc-Access-and-Printing-of-a-HASH-OF-ARRAYS"
href="#perldsc-Access-and-Printing-of-a-HASH-OF-ARRAYS">17.10.3 Access and
Printing of a HASH OF ARRAYS</a></li>
- </ul></li>
- <li><a name="toc-ARRAYS-OF-HASHES" href="#perldsc-ARRAYS-OF-HASHES">17.11
ARRAYS OF HASHES</a>
- <ul class="no-bullet">
- <li><a name="toc-Declaration-of-an-ARRAY-OF-HASHES"
href="#perldsc-Declaration-of-an-ARRAY-OF-HASHES">17.11.1 Declaration of an
ARRAY OF HASHES</a></li>
- <li><a name="toc-Generation-of-an-ARRAY-OF-HASHES"
href="#perldsc-Generation-of-an-ARRAY-OF-HASHES">17.11.2 Generation of an ARRAY
OF HASHES</a></li>
- <li><a name="toc-Access-and-Printing-of-an-ARRAY-OF-HASHES"
href="#perldsc-Access-and-Printing-of-an-ARRAY-OF-HASHES">17.11.3 Access and
Printing of an ARRAY OF HASHES</a></li>
- </ul></li>
- <li><a name="toc-HASHES-OF-HASHES" href="#perldsc-HASHES-OF-HASHES">17.12
HASHES OF HASHES</a>
- <ul class="no-bullet">
- <li><a name="toc-Declaration-of-a-HASH-OF-HASHES"
href="#perldsc-Declaration-of-a-HASH-OF-HASHES">17.12.1 Declaration of a HASH
OF HASHES</a></li>
- <li><a name="toc-Generation-of-a-HASH-OF-HASHES"
href="#perldsc-Generation-of-a-HASH-OF-HASHES">17.12.2 Generation of a HASH OF
HASHES</a></li>
- <li><a name="toc-Access-and-Printing-of-a-HASH-OF-HASHES"
href="#perldsc-Access-and-Printing-of-a-HASH-OF-HASHES">17.12.3 Access and
Printing of a HASH OF HASHES</a></li>
- </ul></li>
- <li><a name="toc-MORE-ELABORATE-RECORDS"
href="#perldsc-MORE-ELABORATE-RECORDS">17.13 MORE ELABORATE RECORDS</a>
- <ul class="no-bullet">
- <li><a name="toc-Declaration-of-MORE-ELABORATE-RECORDS"
href="#perldsc-Declaration-of-MORE-ELABORATE-RECORDS">17.13.1 Declaration of
MORE ELABORATE RECORDS</a></li>
- <li><a name="toc-Declaration-of-a-HASH-OF-COMPLEX-RECORDS"
href="#perldsc-Declaration-of-a-HASH-OF-COMPLEX-RECORDS">17.13.2 Declaration of
a HASH OF COMPLEX RECORDS</a></li>
- <li><a name="toc-Generation-of-a-HASH-OF-COMPLEX-RECORDS"
href="#perldsc-Generation-of-a-HASH-OF-COMPLEX-RECORDS">17.13.3 Generation of a
HASH OF COMPLEX RECORDS</a></li>
- </ul></li>
- <li><a name="toc-Database-Ties" href="#perldsc-Database-Ties">17.14
Database Ties</a></li>
- <li><a name="toc-SEE-ALSO-10" href="#perldsc-SEE-ALSO">17.15 SEE
ALSO</a></li>
- <li><a name="toc-AUTHOR-6" href="#perldsc-AUTHOR">17.16 AUTHOR</a></li>
- </ul></li>
- <li><a name="toc-perldtrace-1" href="#perldtrace">18 perldtrace</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-17" href="#perldtrace-NAME">18.1 NAME</a></li>
- <li><a name="toc-SYNOPSIS-4" href="#perldtrace-SYNOPSIS">18.2
SYNOPSIS</a></li>
- <li><a name="toc-DESCRIPTION-17" href="#perldtrace-DESCRIPTION">18.3
DESCRIPTION</a></li>
- <li><a name="toc-HISTORY" href="#perldtrace-HISTORY">18.4 HISTORY</a></li>
- <li><a name="toc-PROBES" href="#perldtrace-PROBES">18.5 PROBES</a></li>
- <li><a name="toc-EXAMPLES-1" href="#perldtrace-EXAMPLES">18.6
EXAMPLES</a></li>
- <li><a name="toc-REFERENCES-1" href="#perldtrace-REFERENCES">18.7
REFERENCES</a></li>
- <li><a name="toc-SEE-ALSO-11" href="#perldtrace-SEE-ALSO">18.8 SEE
ALSO</a></li>
- <li><a name="toc-AUTHORS" href="#perldtrace-AUTHORS">18.9 AUTHORS</a></li>
- </ul></li>
- <li><a name="toc-perlebcdic-1" href="#perlebcdic">19 perlebcdic</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-18" href="#perlebcdic-NAME">19.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-18" href="#perlebcdic-DESCRIPTION">19.2
DESCRIPTION</a></li>
- <li><a name="toc-COMMON-CHARACTER-CODE-SETS"
href="#perlebcdic-COMMON-CHARACTER-CODE-SETS">19.3 COMMON CHARACTER CODE
SETS</a>
- <ul class="no-bullet">
- <li><a name="toc-ASCII" href="#perlebcdic-ASCII">19.3.1 ASCII</a></li>
- <li><a name="toc-ISO-8859" href="#perlebcdic-ISO-8859">19.3.2 ISO
8859</a></li>
- <li><a name="toc-Latin-1-_0028ISO-8859_002d1_0029"
href="#perlebcdic-Latin-1-_0028ISO-8859_002d1_0029">19.3.3 Latin 1 (ISO
8859-1)</a></li>
- <li><a name="toc-EBCDIC" href="#perlebcdic-EBCDIC">19.3.4 EBCDIC</a>
- <ul class="no-bullet">
- <li><a name="toc-The-13-variant-characters"
href="#perlebcdic-The-13-variant-characters">19.3.4.1 The 13 variant
characters</a></li>
- <li><a name="toc-EBCDIC-code-sets-recognized-by-Perl"
href="#perlebcdic-EBCDIC-code-sets-recognized-by-Perl">19.3.4.2 EBCDIC code
sets recognized by Perl</a></li>
- </ul></li>
- <li><a name="toc-Unicode-code-points-versus-EBCDIC-code-points"
href="#perlebcdic-Unicode-code-points-versus-EBCDIC-code-points">19.3.5 Unicode
code points versus EBCDIC code points</a></li>
- <li><a name="toc-Unicode-and-UTF"
href="#perlebcdic-Unicode-and-UTF">19.3.6 Unicode and UTF</a></li>
- <li><a name="toc-Using-Encode" href="#perlebcdic-Using-Encode">19.3.7
Using Encode</a></li>
- </ul></li>
- <li><a name="toc-SINGLE-OCTET-TABLES"
href="#perlebcdic-SINGLE-OCTET-TABLES">19.4 SINGLE OCTET TABLES</a>
- <ul class="no-bullet">
- <li><a name="toc-Table-in-hex_002c-sorted-in-1047-order"
href="#perlebcdic-Table-in-hex_002c-sorted-in-1047-order">19.4.1 Table in hex,
sorted in 1047 order</a></li>
- </ul></li>
- <li><a name="toc-IDENTIFYING-CHARACTER-CODE-SETS"
href="#perlebcdic-IDENTIFYING-CHARACTER-CODE-SETS">19.5 IDENTIFYING CHARACTER
CODE SETS</a></li>
- <li><a name="toc-CONVERSIONS" href="#perlebcdic-CONVERSIONS">19.6
CONVERSIONS</a>
- <ul class="no-bullet">
- <li><a
name="toc-utf8_003a_003aunicode_005fto_005fnative_0028_0029-and-utf8_003a_003anative_005fto_005funicode_0028_0029"
href="#perlebcdic-utf8_003a_003aunicode_005fto_005fnative_0028_0029-and-utf8_003a_003anative_005fto_005funicode_0028_0029">19.6.1
<code>utf8::unicode_to_native()</code> and
<code>utf8::native_to_unicode()</code></a></li>
- <li><a name="toc-tr_002f_002f_002f"
href="#perlebcdic-tr_002f_002f_002f">19.6.2 tr///</a></li>
- <li><a name="toc-iconv" href="#perlebcdic-iconv">19.6.3 iconv</a></li>
- <li><a name="toc-C-RTL" href="#perlebcdic-C-RTL">19.6.4 C RTL</a></li>
- </ul></li>
- <li><a name="toc-OPERATOR-DIFFERENCES"
href="#perlebcdic-OPERATOR-DIFFERENCES">19.7 OPERATOR DIFFERENCES</a></li>
- <li><a name="toc-FUNCTION-DIFFERENCES"
href="#perlebcdic-FUNCTION-DIFFERENCES">19.8 FUNCTION DIFFERENCES</a></li>
- <li><a name="toc-REGULAR-EXPRESSION-DIFFERENCES"
href="#perlebcdic-REGULAR-EXPRESSION-DIFFERENCES">19.9 REGULAR EXPRESSION
DIFFERENCES</a></li>
- <li><a name="toc-SOCKETS" href="#perlebcdic-SOCKETS">19.10 SOCKETS</a></li>
- <li><a name="toc-SORTING" href="#perlebcdic-SORTING">19.11 SORTING</a>
- <ul class="no-bullet">
- <li><a name="toc-Ignore-ASCII-vs_002e-EBCDIC-sort-differences_002e"
href="#perlebcdic-Ignore-ASCII-vs_002e-EBCDIC-sort-differences_002e">19.11.1
Ignore ASCII vs. EBCDIC sort differences.</a></li>
- <li><a name="toc-Use-a-sort-helper-function"
href="#perlebcdic-Use-a-sort-helper-function">19.11.2 Use a sort helper
function</a></li>
- <li><a
name="toc-MONO-CASE-then-sort-data-_0028for-non_002ddigits_002c-non_002dunderscore_0029"
href="#perlebcdic-MONO-CASE-then-sort-data-_0028for-non_002ddigits_002c-non_002dunderscore_0029">19.11.3
MONO CASE then sort data (for non-digits, non-underscore)</a></li>
- <li><a name="toc-Perform-sorting-on-one-type-of-platform-only_002e"
href="#perlebcdic-Perform-sorting-on-one-type-of-platform-only_002e">19.11.4
Perform sorting on one type of platform only.</a></li>
- </ul></li>
- <li><a name="toc-TRANSFORMATION-FORMATS"
href="#perlebcdic-TRANSFORMATION-FORMATS">19.12 TRANSFORMATION FORMATS</a>
- <ul class="no-bullet">
- <li><a name="toc-URL-decoding-and-encoding"
href="#perlebcdic-URL-decoding-and-encoding">19.12.1 URL decoding and
encoding</a></li>
- <li><a name="toc-uu-encoding-and-decoding"
href="#perlebcdic-uu-encoding-and-decoding">19.12.2 uu encoding and
decoding</a></li>
- <li><a name="toc-Quoted_002dPrintable-encoding-and-decoding"
href="#perlebcdic-Quoted_002dPrintable-encoding-and-decoding">19.12.3
Quoted-Printable encoding and decoding</a></li>
- <li><a name="toc-Caesarean-ciphers"
href="#perlebcdic-Caesarean-ciphers">19.12.4 Caesarean ciphers</a></li>
- </ul></li>
- <li><a name="toc-Hashing-order-and-checksums"
href="#perlebcdic-Hashing-order-and-checksums">19.13 Hashing order and
checksums</a></li>
- <li><a name="toc-I18N-AND-L10N" href="#perlebcdic-I18N-AND-L10N">19.14
I18N AND L10N</a></li>
- <li><a name="toc-MULTI_002dOCTET-CHARACTER-SETS"
href="#perlebcdic-MULTI_002dOCTET-CHARACTER-SETS">19.15 MULTI-OCTET CHARACTER
SETS</a></li>
- <li><a name="toc-OS-ISSUES" href="#perlebcdic-OS-ISSUES">19.16 OS
ISSUES</a>
- <ul class="no-bullet">
- <li><a name="toc-OS_002f400" href="#perlebcdic-OS_002f400">19.16.1
OS/400</a></li>
- <li><a name="toc-OS_002f390_002c-z_002fOS"
href="#perlebcdic-OS_002f390_002c-z_002fOS">19.16.2 OS/390, z/OS</a></li>
- <li><a name="toc-POSIX_002dBC_003f"
href="#perlebcdic-POSIX_002dBC_003f">19.16.3 POSIX-BC?</a></li>
- </ul></li>
- <li><a name="toc-BUGS-2" href="#perlebcdic-BUGS">19.17 BUGS</a></li>
- <li><a name="toc-SEE-ALSO-12" href="#perlebcdic-SEE-ALSO">19.18 SEE
ALSO</a></li>
- <li><a name="toc-REFERENCES-2" href="#perlebcdic-REFERENCES">19.19
REFERENCES</a></li>
- <li><a name="toc-HISTORY-1" href="#perlebcdic-HISTORY">19.20
HISTORY</a></li>
- <li><a name="toc-AUTHOR-7" href="#perlebcdic-AUTHOR">19.21 AUTHOR</a></li>
- </ul></li>
- <li><a name="toc-perlembed-1" href="#perlembed">20 perlembed</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-19" href="#perlembed-NAME">20.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-19" href="#perlembed-DESCRIPTION">20.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-PREAMBLE" href="#perlembed-PREAMBLE">20.2.1
PREAMBLE</a></li>
- <li><a name="toc-ROADMAP" href="#perlembed-ROADMAP">20.2.2
ROADMAP</a></li>
- <li><a name="toc-Compiling-your-C-program"
href="#perlembed-Compiling-your-C-program">20.2.3 Compiling your C
program</a></li>
- <li><a name="toc-Adding-a-Perl-interpreter-to-your-C-program"
href="#perlembed-Adding-a-Perl-interpreter-to-your-C-program">20.2.4 Adding a
Perl interpreter to your C program</a></li>
- <li><a name="toc-Calling-a-Perl-subroutine-from-your-C-program"
href="#perlembed-Calling-a-Perl-subroutine-from-your-C-program">20.2.5 Calling
a Perl subroutine from your C program</a></li>
- <li><a name="toc-Evaluating-a-Perl-statement-from-your-C-program"
href="#perlembed-Evaluating-a-Perl-statement-from-your-C-program">20.2.6
Evaluating a Perl statement from your C program</a></li>
- <li><a
name="toc-Performing-Perl-pattern-matches-and-substitutions-from-your-C-program"
href="#perlembed-Performing-Perl-pattern-matches-and-substitutions-from-your-C-program">20.2.7
Performing Perl pattern matches and substitutions from your C program</a></li>
- <li><a name="toc-Fiddling-with-the-Perl-stack-from-your-C-program"
href="#perlembed-Fiddling-with-the-Perl-stack-from-your-C-program">20.2.8
Fiddling with the Perl stack from your C program</a></li>
- <li><a name="toc-Maintaining-a-persistent-interpreter"
href="#perlembed-Maintaining-a-persistent-interpreter">20.2.9 Maintaining a
persistent interpreter</a></li>
- <li><a name="toc-Execution-of-END-blocks"
href="#perlembed-Execution-of-END-blocks">20.2.10 Execution of END
blocks</a></li>
- <li><a name="toc-_00240-assignments"
href="#perlembed-_00240-assignments">20.2.11 $0 assignments</a></li>
- <li><a name="toc-Maintaining-multiple-interpreter-instances"
href="#perlembed-Maintaining-multiple-interpreter-instances">20.2.12
Maintaining multiple interpreter instances</a></li>
- <li><a
name="toc-Using-Perl-modules_002c-which-themselves-use-C-libraries_002c-from-your-C-program"
href="#perlembed-Using-Perl-modules_002c-which-themselves-use-C-libraries_002c-from-your-C-program">20.2.13
Using Perl modules, which themselves use C libraries, from your C
program</a></li>
- <li><a name="toc-Using-embedded-Perl-with-POSIX-locales"
href="#perlembed-Using-embedded-Perl-with-POSIX-locales">20.2.14 Using embedded
Perl with POSIX locales</a></li>
- </ul></li>
- <li><a name="toc-Hiding-Perl_005f" href="#perlembed-Hiding-Perl_005f">20.3
Hiding Perl_</a></li>
- <li><a name="toc-MORAL" href="#perlembed-MORAL">20.4 MORAL</a></li>
- <li><a name="toc-AUTHOR-8" href="#perlembed-AUTHOR">20.5 AUTHOR</a></li>
- <li><a name="toc-COPYRIGHT" href="#perlembed-COPYRIGHT">20.6
COPYRIGHT</a></li>
- </ul></li>
- <li><a name="toc-perlexperiment-1" href="#perlexperiment">21
perlexperiment</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-20" href="#perlexperiment-NAME">21.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-20" href="#perlexperiment-DESCRIPTION">21.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Current-experiments"
href="#perlexperiment-Current-experiments">21.2.1 Current experiments</a></li>
- <li><a name="toc-Accepted-features"
href="#perlexperiment-Accepted-features">21.2.2 Accepted features</a></li>
- <li><a name="toc-Removed-features"
href="#perlexperiment-Removed-features">21.2.3 Removed features</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-13" href="#perlexperiment-SEE-ALSO">21.3 SEE
ALSO</a></li>
- <li><a name="toc-AUTHORS-1" href="#perlexperiment-AUTHORS">21.4
AUTHORS</a></li>
- <li><a name="toc-COPYRIGHT-1" href="#perlexperiment-COPYRIGHT">21.5
COPYRIGHT</a></li>
- <li><a name="toc-LICENSE" href="#perlexperiment-LICENSE">21.6
LICENSE</a></li>
- </ul></li>
- <li><a name="toc-perlfilter-1" href="#perlfilter">22 perlfilter</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-21" href="#perlfilter-NAME">22.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-21" href="#perlfilter-DESCRIPTION">22.2
DESCRIPTION</a></li>
- <li><a name="toc-CONCEPTS" href="#perlfilter-CONCEPTS">22.3
CONCEPTS</a></li>
- <li><a name="toc-USING-FILTERS" href="#perlfilter-USING-FILTERS">22.4
USING FILTERS</a></li>
- <li><a name="toc-WRITING-A-SOURCE-FILTER"
href="#perlfilter-WRITING-A-SOURCE-FILTER">22.5 WRITING A SOURCE FILTER</a></li>
- <li><a name="toc-WRITING-A-SOURCE-FILTER-IN-C"
href="#perlfilter-WRITING-A-SOURCE-FILTER-IN-C">22.6 WRITING A SOURCE FILTER IN
C</a></li>
- <li><a name="toc-CREATING-A-SOURCE-FILTER-AS-A-SEPARATE-EXECUTABLE"
href="#perlfilter-CREATING-A-SOURCE-FILTER-AS-A-SEPARATE-EXECUTABLE">22.7
CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE</a></li>
- <li><a name="toc-WRITING-A-SOURCE-FILTER-IN-PERL"
href="#perlfilter-WRITING-A-SOURCE-FILTER-IN-PERL">22.8 WRITING A SOURCE FILTER
IN PERL</a></li>
- <li><a name="toc-USING-CONTEXT_003a-THE-DEBUG-FILTER"
href="#perlfilter-USING-CONTEXT_003a-THE-DEBUG-FILTER">22.9 USING CONTEXT: THE
DEBUG FILTER</a></li>
- <li><a name="toc-CONCLUSION" href="#perlfilter-CONCLUSION">22.10
CONCLUSION</a></li>
- <li><a name="toc-LIMITATIONS" href="#perlfilter-LIMITATIONS">22.11
LIMITATIONS</a></li>
- <li><a name="toc-THINGS-TO-LOOK-OUT-FOR"
href="#perlfilter-THINGS-TO-LOOK-OUT-FOR">22.12 THINGS TO LOOK OUT FOR</a></li>
- <li><a name="toc-REQUIREMENTS" href="#perlfilter-REQUIREMENTS">22.13
REQUIREMENTS</a></li>
- <li><a name="toc-AUTHOR-9" href="#perlfilter-AUTHOR">22.14 AUTHOR</a></li>
- <li><a name="toc-Copyrights" href="#perlfilter-Copyrights">22.15
Copyrights</a></li>
- </ul></li>
- <li><a name="toc-perlfork-1" href="#perlfork">23 perlfork</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-22" href="#perlfork-NAME">23.1 NAME</a></li>
- <li><a name="toc-SYNOPSIS-5" href="#perlfork-SYNOPSIS">23.2
SYNOPSIS</a></li>
- <li><a name="toc-DESCRIPTION-22" href="#perlfork-DESCRIPTION">23.3
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a
name="toc-Behavior-of-other-Perl-features-in-forked-pseudo_002dprocesses"
href="#perlfork-Behavior-of-other-Perl-features-in-forked-pseudo_002dprocesses">23.3.1
Behavior of other Perl features in forked pseudo-processes</a></li>
- <li><a name="toc-Resource-limits"
href="#perlfork-Resource-limits">23.3.2 Resource limits</a></li>
- <li><a name="toc-Killing-the-parent-process"
href="#perlfork-Killing-the-parent-process">23.3.3 Killing the parent
process</a></li>
- <li><a
name="toc-Lifetime-of-the-parent-process-and-pseudo_002dprocesses"
href="#perlfork-Lifetime-of-the-parent-process-and-pseudo_002dprocesses">23.3.4
Lifetime of the parent process and pseudo-processes</a></li>
- </ul></li>
- <li><a name="toc-CAVEATS-AND-LIMITATIONS"
href="#perlfork-CAVEATS-AND-LIMITATIONS">23.4 CAVEATS AND LIMITATIONS</a></li>
- <li><a name="toc-PORTABILITY-CAVEATS"
href="#perlfork-PORTABILITY-CAVEATS">23.5 PORTABILITY CAVEATS</a></li>
- <li><a name="toc-BUGS-3" href="#perlfork-BUGS">23.6 BUGS</a></li>
- <li><a name="toc-AUTHOR-10" href="#perlfork-AUTHOR">23.7 AUTHOR</a></li>
- <li><a name="toc-SEE-ALSO-14" href="#perlfork-SEE-ALSO">23.8 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlform-1" href="#perlform">24 perlform</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-23" href="#perlform-NAME">24.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-23" href="#perlform-DESCRIPTION">24.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Text-Fields" href="#perlform-Text-Fields">24.2.1 Text
Fields</a></li>
- <li><a name="toc-Numeric-Fields" href="#perlform-Numeric-Fields">24.2.2
Numeric Fields</a></li>
- <li><a
name="toc-The-Field-_0040_002a-for-Variable_002dWidth-Multi_002dLine-Text"
href="#perlform-The-Field-_0040_002a-for-Variable_002dWidth-Multi_002dLine-Text">24.2.3
The Field @* for Variable-Width Multi-Line Text</a></li>
- <li><a
name="toc-The-Field-_005e_002a-for-Variable_002dWidth-One_002dline_002dat_002da_002dtime-Text"
href="#perlform-The-Field-_005e_002a-for-Variable_002dWidth-One_002dline_002dat_002da_002dtime-Text">24.2.4
The Field ^* for Variable-Width One-line-at-a-time Text</a></li>
- <li><a name="toc-Specifying-Values"
href="#perlform-Specifying-Values">24.2.5 Specifying Values</a></li>
- <li><a name="toc-Using-Fill-Mode"
href="#perlform-Using-Fill-Mode">24.2.6 Using Fill Mode</a></li>
- <li><a name="toc-Suppressing-Lines-Where-All-Fields-Are-Void"
href="#perlform-Suppressing-Lines-Where-All-Fields-Are-Void">24.2.7 Suppressing
Lines Where All Fields Are Void</a></li>
- <li><a name="toc-Repeating-Format-Lines"
href="#perlform-Repeating-Format-Lines">24.2.8 Repeating Format Lines</a></li>
- <li><a name="toc-Top-of-Form-Processing"
href="#perlform-Top-of-Form-Processing">24.2.9 Top of Form Processing</a></li>
- <li><a name="toc-Format-Variables"
href="#perlform-Format-Variables">24.2.10 Format Variables</a></li>
- </ul></li>
- <li><a name="toc-NOTES-1" href="#perlform-NOTES">24.3 NOTES</a>
- <ul class="no-bullet">
- <li><a name="toc-Footers" href="#perlform-Footers">24.3.1
Footers</a></li>
- <li><a name="toc-Accessing-Formatting-Internals"
href="#perlform-Accessing-Formatting-Internals">24.3.2 Accessing Formatting
Internals</a></li>
- </ul></li>
- <li><a name="toc-WARNINGS" href="#perlform-WARNINGS">24.4 WARNINGS</a></li>
- </ul></li>
- <li><a name="toc-perlfunc-1" href="#perlfunc">25 perlfunc</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-24" href="#perlfunc-NAME">25.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-24" href="#perlfunc-DESCRIPTION">25.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Perl-Functions-by-Category"
href="#perlfunc-Perl-Functions-by-Category">25.2.1 Perl Functions by
Category</a></li>
- <li><a name="toc-Portability" href="#perlfunc-Portability">25.2.2
Portability</a></li>
- <li><a name="toc-Alphabetical-Listing-of-Perl-Functions"
href="#perlfunc-Alphabetical-Listing-of-Perl-Functions">25.2.3 Alphabetical
Listing of Perl Functions</a></li>
- <li><a name="toc-Non_002dfunction-Keywords-by-Cross_002dreference"
href="#perlfunc-Non_002dfunction-Keywords-by-Cross_002dreference">25.2.4
Non-function Keywords by Cross-reference</a>
- <ul class="no-bullet">
- <li><a name="toc-perldata-2" href="#perlfunc-perldata">25.2.4.1
perldata</a></li>
- <li><a name="toc-perlmod-1" href="#perlfunc-perlmod">25.2.4.2
perlmod</a></li>
- <li><a name="toc-perlobj-1" href="#perlfunc-perlobj">25.2.4.3
perlobj</a></li>
- <li><a name="toc-perlop-1" href="#perlfunc-perlop">25.2.4.4
perlop</a></li>
- <li><a name="toc-perlsub-1" href="#perlfunc-perlsub">25.2.4.5
perlsub</a></li>
- <li><a name="toc-perlsyn-1" href="#perlfunc-perlsyn">25.2.4.6
perlsyn</a></li>
- </ul></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlgit-1" href="#perlgit">26 perlgit</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-25" href="#perlgit-NAME">26.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-25" href="#perlgit-DESCRIPTION">26.2
DESCRIPTION</a></li>
- <li><a name="toc-CLONING-THE-REPOSITORY"
href="#perlgit-CLONING-THE-REPOSITORY">26.3 CLONING THE REPOSITORY</a></li>
- <li><a name="toc-WORKING-WITH-THE-REPOSITORY"
href="#perlgit-WORKING-WITH-THE-REPOSITORY">26.4 WORKING WITH THE REPOSITORY</a>
- <ul class="no-bullet">
- <li><a name="toc-Finding-out-your-status"
href="#perlgit-Finding-out-your-status">26.4.1 Finding out your status</a></li>
- <li><a name="toc-Patch-workflow" href="#perlgit-Patch-workflow">26.4.2
Patch workflow</a></li>
- <li><a name="toc-Committing-your-changes"
href="#perlgit-Committing-your-changes">26.4.3 Committing your changes</a></li>
- <li><a name="toc-Sending-patch-emails"
href="#perlgit-Sending-patch-emails">26.4.4 Sending patch emails</a></li>
- <li><a name="toc-A-note-on-derived-files"
href="#perlgit-A-note-on-derived-files">26.4.5 A note on derived files</a></li>
- <li><a name="toc-Cleaning-a-working-directory"
href="#perlgit-Cleaning-a-working-directory">26.4.6 Cleaning a working
directory</a></li>
- <li><a name="toc-Bisecting" href="#perlgit-Bisecting">26.4.7
Bisecting</a></li>
- <li><a name="toc-Topic-branches-and-rewriting-history"
href="#perlgit-Topic-branches-and-rewriting-history">26.4.8 Topic branches and
rewriting history</a></li>
- <li><a name="toc-Grafts" href="#perlgit-Grafts">26.4.9 Grafts</a></li>
- </ul></li>
- <li><a name="toc-WRITE-ACCESS-TO-THE-GIT-REPOSITORY"
href="#perlgit-WRITE-ACCESS-TO-THE-GIT-REPOSITORY">26.5 WRITE ACCESS TO THE GIT
REPOSITORY</a>
- <ul class="no-bullet">
- <li><a name="toc-Accepting-a-patch"
href="#perlgit-Accepting-a-patch">26.5.1 Accepting a patch</a></li>
- <li><a name="toc-Committing-to-blead"
href="#perlgit-Committing-to-blead">26.5.2 Committing to blead</a></li>
- <li><a name="toc-On-merging-and-rebasing"
href="#perlgit-On-merging-and-rebasing">26.5.3 On merging and rebasing</a></li>
- <li><a name="toc-Committing-to-maintenance-versions"
href="#perlgit-Committing-to-maintenance-versions">26.5.4 Committing to
maintenance versions</a></li>
- <li><a name="toc-Merging-from-a-branch-via-GitHub"
href="#perlgit-Merging-from-a-branch-via-GitHub">26.5.5 Merging from a branch
via GitHub</a></li>
- <li><a name="toc-Using-a-smoke_002dme-branch-to-test-changes"
href="#perlgit-Using-a-smoke_002dme-branch-to-test-changes">26.5.6 Using a
smoke-me branch to test changes</a></li>
- <li><a name="toc-A-note-on-camel-and-dromedary"
href="#perlgit-A-note-on-camel-and-dromedary">26.5.7 A note on camel and
dromedary</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlgpl-1" href="#perlgpl">27 perlgpl</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-26" href="#perlgpl-NAME">27.1 NAME</a></li>
- <li><a name="toc-SYNOPSIS-6" href="#perlgpl-SYNOPSIS">27.2
SYNOPSIS</a></li>
- <li><a name="toc-DESCRIPTION-26" href="#perlgpl-DESCRIPTION">27.3
DESCRIPTION</a></li>
- <li><a name="toc-GNU-GENERAL-PUBLIC-LICENSE"
href="#perlgpl-GNU-GENERAL-PUBLIC-LICENSE">27.4 GNU GENERAL PUBLIC
LICENSE</a></li>
- </ul></li>
- <li><a name="toc-perlguts-1" href="#perlguts">28 perlguts</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-27" href="#perlguts-NAME">28.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-27" href="#perlguts-DESCRIPTION">28.2
DESCRIPTION</a></li>
- <li><a name="toc-Variables" href="#perlguts-Variables">28.3 Variables</a>
- <ul class="no-bullet">
- <li><a name="toc-Datatypes" href="#perlguts-Datatypes">28.3.1
Datatypes</a></li>
- <li><a name="toc-What-is-an-_0022IV_0022_003f"
href="#perlguts-What-is-an-_0022IV_0022_003f">28.3.2 What is an
"IV"?</a></li>
- <li><a name="toc-Working-with-SVs"
href="#perlguts-Working-with-SVs">28.3.3 Working with SVs</a></li>
- <li><a name="toc-Offsets" href="#perlguts-Offsets">28.3.4
Offsets</a></li>
- <li><a name="toc-What_0027s-Really-Stored-in-an-SV_003f"
href="#perlguts-What_0027s-Really-Stored-in-an-SV_003f">28.3.5 What’s
Really Stored in an SV?</a></li>
- <li><a name="toc-Working-with-AVs"
href="#perlguts-Working-with-AVs">28.3.6 Working with AVs</a></li>
- <li><a name="toc-Working-with-HVs"
href="#perlguts-Working-with-HVs">28.3.7 Working with HVs</a></li>
- <li><a name="toc-Hash-API-Extensions"
href="#perlguts-Hash-API-Extensions">28.3.8 Hash API Extensions</a></li>
- <li><a name="toc-AVs_002c-HVs-and-undefined-values"
href="#perlguts-AVs_002c-HVs-and-undefined-values">28.3.9 AVs, HVs and
undefined values</a></li>
- <li><a name="toc-References-1" href="#perlguts-References">28.3.10
References</a></li>
- <li><a name="toc-Blessed-References-and-Class-Objects"
href="#perlguts-Blessed-References-and-Class-Objects">28.3.11 Blessed
References and Class Objects</a></li>
- <li><a name="toc-Creating-New-Variables"
href="#perlguts-Creating-New-Variables">28.3.12 Creating New Variables</a></li>
- <li><a name="toc-Reference-Counts-and-Mortality"
href="#perlguts-Reference-Counts-and-Mortality">28.3.13 Reference Counts and
Mortality</a></li>
- <li><a name="toc-Stashes-and-Globs"
href="#perlguts-Stashes-and-Globs">28.3.14 Stashes and Globs</a></li>
- <li><a name="toc-Double_002dTyped-SVs"
href="#perlguts-Double_002dTyped-SVs">28.3.15 Double-Typed SVs</a></li>
- <li><a name="toc-Read_002dOnly-Values"
href="#perlguts-Read_002dOnly-Values">28.3.16 Read-Only Values</a></li>
- <li><a name="toc-Copy-on-Write" href="#perlguts-Copy-on-Write">28.3.17
Copy on Write</a></li>
- <li><a name="toc-Magic-Variables"
href="#perlguts-Magic-Variables">28.3.18 Magic Variables</a></li>
- <li><a name="toc-Assigning-Magic"
href="#perlguts-Assigning-Magic">28.3.19 Assigning Magic</a></li>
- <li><a name="toc-Magic-Virtual-Tables"
href="#perlguts-Magic-Virtual-Tables">28.3.20 Magic Virtual Tables</a></li>
- <li><a name="toc-Finding-Magic" href="#perlguts-Finding-Magic">28.3.21
Finding Magic</a></li>
- <li><a name="toc-Understanding-the-Magic-of-Tied-Hashes-and-Arrays"
href="#perlguts-Understanding-the-Magic-of-Tied-Hashes-and-Arrays">28.3.22
Understanding the Magic of Tied Hashes and Arrays</a></li>
- <li><a name="toc-Localizing-changes"
href="#perlguts-Localizing-changes">28.3.23 Localizing changes</a></li>
- </ul></li>
- <li><a name="toc-Subroutines" href="#perlguts-Subroutines">28.4
Subroutines</a>
- <ul class="no-bullet">
- <li><a name="toc-XSUBs-and-the-Argument-Stack"
href="#perlguts-XSUBs-and-the-Argument-Stack">28.4.1 XSUBs and the Argument
Stack</a></li>
- <li><a name="toc-Autoloading-with-XSUBs"
href="#perlguts-Autoloading-with-XSUBs">28.4.2 Autoloading with XSUBs</a></li>
- <li><a name="toc-Calling-Perl-Routines-from-within-C-Programs"
href="#perlguts-Calling-Perl-Routines-from-within-C-Programs">28.4.3 Calling
Perl Routines from within C Programs</a></li>
- <li><a name="toc-Putting-a-C-value-on-Perl-stack"
href="#perlguts-Putting-a-C-value-on-Perl-stack">28.4.4 Putting a C value on
Perl stack</a></li>
- <li><a name="toc-Scratchpads" href="#perlguts-Scratchpads">28.4.5
Scratchpads</a></li>
- <li><a name="toc-Scratchpads-and-recursion"
href="#perlguts-Scratchpads-and-recursion">28.4.6 Scratchpads and
recursion</a></li>
- </ul></li>
- <li><a name="toc-Memory-Allocation"
href="#perlguts-Memory-Allocation">28.5 Memory Allocation</a>
- <ul class="no-bullet">
- <li><a name="toc-Allocation" href="#perlguts-Allocation">28.5.1
Allocation</a></li>
- <li><a name="toc-Reallocation" href="#perlguts-Reallocation">28.5.2
Reallocation</a></li>
- <li><a name="toc-Moving" href="#perlguts-Moving">28.5.3 Moving</a></li>
- </ul></li>
- <li><a name="toc-PerlIO" href="#perlguts-PerlIO">28.6 PerlIO</a></li>
- <li><a name="toc-Compiled-code" href="#perlguts-Compiled-code">28.7
Compiled code</a>
- <ul class="no-bullet">
- <li><a name="toc-Code-tree" href="#perlguts-Code-tree">28.7.1 Code
tree</a></li>
- <li><a name="toc-Examining-the-tree"
href="#perlguts-Examining-the-tree">28.7.2 Examining the tree</a></li>
- <li><a name="toc-Compile-pass-1_003a-check-routines"
href="#perlguts-Compile-pass-1_003a-check-routines">28.7.3 Compile pass 1:
check routines</a></li>
- <li><a name="toc-Compile-pass-1a_003a-constant-folding"
href="#perlguts-Compile-pass-1a_003a-constant-folding">28.7.4 Compile pass 1a:
constant folding</a></li>
- <li><a name="toc-Compile-pass-2_003a-context-propagation"
href="#perlguts-Compile-pass-2_003a-context-propagation">28.7.5 Compile pass 2:
context propagation</a></li>
- <li><a name="toc-Compile-pass-3_003a-peephole-optimization"
href="#perlguts-Compile-pass-3_003a-peephole-optimization">28.7.6 Compile pass
3: peephole optimization</a></li>
- <li><a name="toc-Pluggable-runops"
href="#perlguts-Pluggable-runops">28.7.7 Pluggable runops</a></li>
- <li><a name="toc-Compile_002dtime-scope-hooks"
href="#perlguts-Compile_002dtime-scope-hooks">28.7.8 Compile-time scope
hooks</a></li>
- </ul></li>
- <li><a
name="toc-Examining-internal-data-structures-with-the-dump-functions"
href="#perlguts-Examining-internal-data-structures-with-the-dump-functions">28.8
Examining internal data structures with the <code>dump</code>
functions</a></li>
- <li><a name="toc-How-multiple-interpreters-and-concurrency-are-supported"
href="#perlguts-How-multiple-interpreters-and-concurrency-are-supported">28.9
How multiple interpreters and concurrency are supported</a>
- <ul class="no-bullet">
- <li><a name="toc-Background-and-PERL_005fIMPLICIT_005fCONTEXT"
href="#perlguts-Background-and-PERL_005fIMPLICIT_005fCONTEXT">28.9.1 Background
and PERL_IMPLICIT_CONTEXT</a></li>
- <li><a name="toc-So-what-happened-to-dTHR_003f"
href="#perlguts-So-what-happened-to-dTHR_003f">28.9.2 So what happened to
dTHR?</a></li>
- <li><a name="toc-How-do-I-use-all-this-in-extensions_003f"
href="#perlguts-How-do-I-use-all-this-in-extensions_003f">28.9.3 How do I use
all this in extensions?</a></li>
- <li><a
name="toc-Should-I-do-anything-special-if-I-call-perl-from-multiple-threads_003f"
href="#perlguts-Should-I-do-anything-special-if-I-call-perl-from-multiple-threads_003f">28.9.4
Should I do anything special if I call perl from multiple threads?</a></li>
- <li><a name="toc-Future-Plans-and-PERL_005fIMPLICIT_005fSYS"
href="#perlguts-Future-Plans-and-PERL_005fIMPLICIT_005fSYS">28.9.5 Future Plans
and PERL_IMPLICIT_SYS</a></li>
- </ul></li>
- <li><a name="toc-Internal-Functions"
href="#perlguts-Internal-Functions">28.10 Internal Functions</a>
- <ul class="no-bullet">
- <li><a name="toc-Formatted-Printing-of-IVs_002c-UVs_002c-and-NVs"
href="#perlguts-Formatted-Printing-of-IVs_002c-UVs_002c-and-NVs">28.10.1
Formatted Printing of IVs, UVs, and NVs</a></li>
- <li><a
name="toc-Pointer_002dTo_002dInteger-and-Integer_002dTo_002dPointer"
href="#perlguts-Pointer_002dTo_002dInteger-and-Integer_002dTo_002dPointer">28.10.2
Pointer-To-Integer and Integer-To-Pointer</a></li>
- <li><a name="toc-Exception-Handling"
href="#perlguts-Exception-Handling">28.10.3 Exception Handling</a></li>
- <li><a name="toc-Source-Documentation"
href="#perlguts-Source-Documentation">28.10.4 Source Documentation</a></li>
- <li><a name="toc-Backwards-compatibility"
href="#perlguts-Backwards-compatibility">28.10.5 Backwards
compatibility</a></li>
- </ul></li>
- <li><a name="toc-Unicode-Support" href="#perlguts-Unicode-Support">28.11
Unicode Support</a>
- <ul class="no-bullet">
- <li><a name="toc-What-is-Unicode_002c-anyway_003f"
href="#perlguts-What-is-Unicode_002c-anyway_003f">28.11.1 What
<strong>is</strong> Unicode, anyway?</a></li>
- <li><a name="toc-How-can-I-recognise-a-UTF_002d8-string_003f"
href="#perlguts-How-can-I-recognise-a-UTF_002d8-string_003f">28.11.2 How can I
recognise a UTF-8 string?</a></li>
- <li><a name="toc-How-does-UTF_002d8-represent-Unicode-characters_003f"
href="#perlguts-How-does-UTF_002d8-represent-Unicode-characters_003f">28.11.3
How does UTF-8 represent Unicode characters?</a></li>
- <li><a name="toc-How-does-Perl-store-UTF_002d8-strings_003f"
href="#perlguts-How-does-Perl-store-UTF_002d8-strings_003f">28.11.4 How does
Perl store UTF-8 strings?</a></li>
- <li><a name="toc-How-do-I-convert-a-string-to-UTF_002d8_003f"
href="#perlguts-How-do-I-convert-a-string-to-UTF_002d8_003f">28.11.5 How do I
convert a string to UTF-8?</a></li>
- <li><a name="toc-How-do-I-compare-strings_003f"
href="#perlguts-How-do-I-compare-strings_003f">28.11.6 How do I compare
strings?</a></li>
- <li><a name="toc-Is-there-anything-else-I-need-to-know_003f"
href="#perlguts-Is-there-anything-else-I-need-to-know_003f">28.11.7 Is there
anything else I need to know?</a></li>
- </ul></li>
- <li><a name="toc-Custom-Operators" href="#perlguts-Custom-Operators">28.12
Custom Operators</a></li>
- <li><a name="toc-AUTHORS-2" href="#perlguts-AUTHORS">28.13 AUTHORS</a></li>
- <li><a name="toc-SEE-ALSO-15" href="#perlguts-SEE-ALSO">28.14 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlhack-1" href="#perlhack">29 perlhack</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-28" href="#perlhack-NAME">29.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-28" href="#perlhack-DESCRIPTION">29.2
DESCRIPTION</a></li>
- <li><a name="toc-SUPER-QUICK-PATCH-GUIDE"
href="#perlhack-SUPER-QUICK-PATCH-GUIDE">29.3 SUPER QUICK PATCH GUIDE</a></li>
- <li><a name="toc-BUG-REPORTING" href="#perlhack-BUG-REPORTING">29.4 BUG
REPORTING</a></li>
- <li><a name="toc-PERL-5-PORTERS" href="#perlhack-PERL-5-PORTERS">29.5 PERL
5 PORTERS</a>
- <ul class="no-bullet">
- <li><a name="toc-perl_002dchanges-mailing-list"
href="#perlhack-perl_002dchanges-mailing-list">29.5.1 perl-changes mailing
list</a></li>
- <li><a name="toc-_0023p5p-on-IRC"
href="#perlhack-_0023p5p-on-IRC">29.5.2 #p5p on IRC</a></li>
- </ul></li>
- <li><a name="toc-GETTING-THE-PERL-SOURCE"
href="#perlhack-GETTING-THE-PERL-SOURCE">29.6 GETTING THE PERL SOURCE</a>
- <ul class="no-bullet">
- <li><a name="toc-Read-access-via-Git"
href="#perlhack-Read-access-via-Git">29.6.1 Read access via Git</a></li>
- <li><a name="toc-Read-access-via-the-web"
href="#perlhack-Read-access-via-the-web">29.6.2 Read access via the web</a></li>
- <li><a name="toc-Read-access-via-rsync"
href="#perlhack-Read-access-via-rsync">29.6.3 Read access via rsync</a></li>
- <li><a name="toc-Write-access-via-git"
href="#perlhack-Write-access-via-git">29.6.4 Write access via git</a></li>
- </ul></li>
- <li><a name="toc-PATCHING-PERL" href="#perlhack-PATCHING-PERL">29.7
PATCHING PERL</a>
- <ul class="no-bullet">
- <li><a name="toc-Submitting-patches"
href="#perlhack-Submitting-patches">29.7.1 Submitting patches</a></li>
- <li><a name="toc-Getting-your-patch-accepted"
href="#perlhack-Getting-your-patch-accepted">29.7.2 Getting your patch
accepted</a>
- <ul class="no-bullet">
- <li><a name="toc-Patch-style" href="#perlhack-Patch-style">29.7.2.1
Patch style</a></li>
- <li><a name="toc-Commit-message"
href="#perlhack-Commit-message">29.7.2.2 Commit message</a></li>
- <li><a name="toc-Comments_002c-Comments_002c-Comments"
href="#perlhack-Comments_002c-Comments_002c-Comments">29.7.2.3 Comments,
Comments, Comments</a></li>
- <li><a name="toc-Style" href="#perlhack-Style">29.7.2.4 Style</a></li>
- <li><a name="toc-Test-suite" href="#perlhack-Test-suite">29.7.2.5 Test
suite</a></li>
- </ul></li>
- <li><a name="toc-Patching-a-core-module"
href="#perlhack-Patching-a-core-module">29.7.3 Patching a core module</a></li>
- <li><a name="toc-Updating-perldelta"
href="#perlhack-Updating-perldelta">29.7.4 Updating perldelta</a></li>
- <li><a name="toc-What-makes-for-a-good-patch_003f"
href="#perlhack-What-makes-for-a-good-patch_003f">29.7.5 What makes for a good
patch?</a>
- <ul class="no-bullet">
- <li><a
name="toc-Does-the-concept-match-the-general-goals-of-Perl_003f"
href="#perlhack-Does-the-concept-match-the-general-goals-of-Perl_003f">29.7.5.1
Does the concept match the general goals of Perl?</a></li>
- <li><a name="toc-Where-is-the-implementation_003f"
href="#perlhack-Where-is-the-implementation_003f">29.7.5.2 Where is the
implementation?</a></li>
- <li><a name="toc-Backwards-compatibility-1"
href="#perlhack-Backwards-compatibility">29.7.5.3 Backwards
compatibility</a></li>
- <li><a name="toc-Could-it-be-a-module-instead_003f"
href="#perlhack-Could-it-be-a-module-instead_003f">29.7.5.4 Could it be a
module instead?</a></li>
- <li><a name="toc-Is-the-feature-generic-enough_003f"
href="#perlhack-Is-the-feature-generic-enough_003f">29.7.5.5 Is the feature
generic enough?</a></li>
- <li><a name="toc-Does-it-potentially-introduce-new-bugs_003f"
href="#perlhack-Does-it-potentially-introduce-new-bugs_003f">29.7.5.6 Does it
potentially introduce new bugs?</a></li>
- <li><a name="toc-How-big-is-it_003f"
href="#perlhack-How-big-is-it_003f">29.7.5.7 How big is it?</a></li>
- <li><a name="toc-Does-it-preclude-other-desirable-features_003f"
href="#perlhack-Does-it-preclude-other-desirable-features_003f">29.7.5.8 Does
it preclude other desirable features?</a></li>
- <li><a name="toc-Is-the-implementation-robust_003f"
href="#perlhack-Is-the-implementation-robust_003f">29.7.5.9 Is the
implementation robust?</a></li>
- <li><a
name="toc-Is-the-implementation-generic-enough-to-be-portable_003f"
href="#perlhack-Is-the-implementation-generic-enough-to-be-portable_003f">29.7.5.10
Is the implementation generic enough to be portable?</a></li>
- <li><a name="toc-Is-the-implementation-tested_003f"
href="#perlhack-Is-the-implementation-tested_003f">29.7.5.11 Is the
implementation tested?</a></li>
- <li><a name="toc-Is-there-enough-documentation_003f"
href="#perlhack-Is-there-enough-documentation_003f">29.7.5.12 Is there enough
documentation?</a></li>
- <li><a name="toc-Is-there-another-way-to-do-it_003f"
href="#perlhack-Is-there-another-way-to-do-it_003f">29.7.5.13 Is there another
way to do it?</a></li>
- <li><a name="toc-Does-it-create-too-much-work_003f"
href="#perlhack-Does-it-create-too-much-work_003f">29.7.5.14 Does it create too
much work?</a></li>
- <li><a name="toc-Patches-speak-louder-than-words"
href="#perlhack-Patches-speak-louder-than-words">29.7.5.15 Patches speak louder
than words</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-TESTING" href="#perlhack-TESTING">29.8 TESTING</a>
- <ul class="no-bullet">
- <li><a name="toc-Special-make-test-targets"
href="#perlhack-Special-make-test-targets">29.8.1 Special <code>make
test</code> targets</a></li>
- <li><a name="toc-Parallel-tests" href="#perlhack-Parallel-tests">29.8.2
Parallel tests</a></li>
- <li><a name="toc-Running-tests-by-hand"
href="#perlhack-Running-tests-by-hand">29.8.3 Running tests by hand</a></li>
- <li><a name="toc-Using-t_002fharness-for-testing"
href="#perlhack-Using-t_002fharness-for-testing">29.8.4 Using
<samp>t/harness</samp> for testing</a>
- <ul class="no-bullet">
- <li><a name="toc-Other-environment-variables-that-may-influence-tests"
href="#perlhack-Other-environment-variables-that-may-influence-tests">29.8.4.1
Other environment variables that may influence tests</a></li>
- </ul></li>
- <li><a name="toc-Performance-testing"
href="#perlhack-Performance-testing">29.8.5 Performance testing</a></li>
- </ul></li>
- <li><a name="toc-MORE-READING-FOR-GUTS-HACKERS"
href="#perlhack-MORE-READING-FOR-GUTS-HACKERS">29.9 MORE READING FOR GUTS
HACKERS</a></li>
- <li><a name="toc-CPAN-TESTERS-AND-PERL-SMOKERS"
href="#perlhack-CPAN-TESTERS-AND-PERL-SMOKERS">29.10 CPAN TESTERS AND PERL
SMOKERS</a></li>
- <li><a name="toc-WHAT-NEXT_003f" href="#perlhack-WHAT-NEXT_003f">29.11
WHAT NEXT?</a>
- <ul class="no-bullet">
- <li><a
name="toc-_0022The-Road-goes-ever-on-and-on_002c-down-from-the-door-where-it-began_002e_0022"
href="#perlhack-_0022The-Road-goes-ever-on-and-on_002c-down-from-the-door-where-it-began_002e_0022">29.11.1
"The Road goes ever on and on, down from the door where it
began."</a></li>
- <li><a name="toc-Metaphoric-Quotations"
href="#perlhack-Metaphoric-Quotations">29.11.2 Metaphoric Quotations</a></li>
- </ul></li>
- <li><a name="toc-AUTHOR-11" href="#perlhack-AUTHOR">29.12 AUTHOR</a></li>
- </ul></li>
- <li><a name="toc-perlhacktips-1" href="#perlhacktips">30 perlhacktips</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-29" href="#perlhacktips-NAME">30.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-29" href="#perlhacktips-DESCRIPTION">30.2
DESCRIPTION</a></li>
- <li><a name="toc-COMMON-PROBLEMS"
href="#perlhacktips-COMMON-PROBLEMS">30.3 COMMON PROBLEMS</a>
- <ul class="no-bullet">
- <li><a name="toc-Perl-environment-problems"
href="#perlhacktips-Perl-environment-problems">30.3.1 Perl environment
problems</a></li>
- <li><a name="toc-Portability-problems"
href="#perlhacktips-Portability-problems">30.3.2 Portability problems</a></li>
- <li><a name="toc-Problematic-System-Interfaces"
href="#perlhacktips-Problematic-System-Interfaces">30.3.3 Problematic System
Interfaces</a></li>
- <li><a name="toc-Security-problems"
href="#perlhacktips-Security-problems">30.3.4 Security problems</a></li>
- </ul></li>
- <li><a name="toc-DEBUGGING-1" href="#perlhacktips-DEBUGGING">30.4
DEBUGGING</a>
- <ul class="no-bullet">
- <li><a name="toc-Poking-at-Perl"
href="#perlhacktips-Poking-at-Perl">30.4.1 Poking at Perl</a></li>
- <li><a name="toc-Using-a-source_002dlevel-debugger"
href="#perlhacktips-Using-a-source_002dlevel-debugger">30.4.2 Using a
source-level debugger</a></li>
- <li><a name="toc-gdb-macro-support"
href="#perlhacktips-gdb-macro-support">30.4.3 gdb macro support</a></li>
- <li><a name="toc-Dumping-Perl-Data-Structures"
href="#perlhacktips-Dumping-Perl-Data-Structures">30.4.4 Dumping Perl Data
Structures</a></li>
- <li><a name="toc-Using-gdb-to-look-at-specific-parts-of-a-program"
href="#perlhacktips-Using-gdb-to-look-at-specific-parts-of-a-program">30.4.5
Using gdb to look at specific parts of a program</a></li>
- <li><a
name="toc-Using-gdb-to-look-at-what-the-parser_002flexer-are-doing"
href="#perlhacktips-Using-gdb-to-look-at-what-the-parser_002flexer-are-doing">30.4.6
Using gdb to look at what the parser/lexer are doing</a></li>
- </ul></li>
- <li><a name="toc-SOURCE-CODE-STATIC-ANALYSIS"
href="#perlhacktips-SOURCE-CODE-STATIC-ANALYSIS">30.5 SOURCE CODE STATIC
ANALYSIS</a>
- <ul class="no-bullet">
- <li><a name="toc-lint_002c-splint"
href="#perlhacktips-lint_002c-splint">30.5.1 lint, splint</a></li>
- <li><a name="toc-Coverity" href="#perlhacktips-Coverity">30.5.2
Coverity</a></li>
- <li><a name="toc-cpd-_0028cut_002dand_002dpaste-detector_0029"
href="#perlhacktips-cpd-_0028cut_002dand_002dpaste-detector_0029">30.5.3 cpd
(cut-and-paste detector)</a></li>
- <li><a name="toc-gcc-warnings" href="#perlhacktips-gcc-warnings">30.5.4
gcc warnings</a></li>
- <li><a name="toc-Warnings-of-other-C-compilers"
href="#perlhacktips-Warnings-of-other-C-compilers">30.5.5 Warnings of other C
compilers</a></li>
- </ul></li>
- <li><a name="toc-MEMORY-DEBUGGERS"
href="#perlhacktips-MEMORY-DEBUGGERS">30.6 MEMORY DEBUGGERS</a>
- <ul class="no-bullet">
- <li><a name="toc-valgrind" href="#perlhacktips-valgrind">30.6.1
valgrind</a></li>
- <li><a name="toc-AddressSanitizer"
href="#perlhacktips-AddressSanitizer">30.6.2 AddressSanitizer</a></li>
- </ul></li>
- <li><a name="toc-PROFILING" href="#perlhacktips-PROFILING">30.7
PROFILING</a>
- <ul class="no-bullet">
- <li><a name="toc-Gprof-Profiling"
href="#perlhacktips-Gprof-Profiling">30.7.1 Gprof Profiling</a></li>
- <li><a name="toc-GCC-gcov-Profiling"
href="#perlhacktips-GCC-gcov-Profiling">30.7.2 GCC gcov Profiling</a></li>
- </ul></li>
- <li><a name="toc-MISCELLANEOUS-TRICKS"
href="#perlhacktips-MISCELLANEOUS-TRICKS">30.8 MISCELLANEOUS TRICKS</a>
- <ul class="no-bullet">
- <li><a name="toc-PERL_005fDESTRUCT_005fLEVEL"
href="#perlhacktips-PERL_005fDESTRUCT_005fLEVEL">30.8.1
PERL_DESTRUCT_LEVEL</a></li>
- <li><a name="toc-PERL_005fMEM_005fLOG"
href="#perlhacktips-PERL_005fMEM_005fLOG">30.8.2 PERL_MEM_LOG</a></li>
- <li><a name="toc-DDD-over-gdb" href="#perlhacktips-DDD-over-gdb">30.8.3
DDD over gdb</a></li>
- <li><a name="toc-C-backtrace" href="#perlhacktips-C-backtrace">30.8.4 C
backtrace</a></li>
- <li><a name="toc-Poison" href="#perlhacktips-Poison">30.8.5
Poison</a></li>
- <li><a name="toc-Read_002donly-optrees"
href="#perlhacktips-Read_002donly-optrees">30.8.6 Read-only optrees</a></li>
- <li><a name="toc-When-is-a-bool-not-a-bool_003f"
href="#perlhacktips-When-is-a-bool-not-a-bool_003f">30.8.7 When is a bool not a
bool?</a></li>
- <li><a name="toc-The-_002ei-Targets"
href="#perlhacktips-The-_002ei-Targets">30.8.8 The .i Targets</a></li>
- </ul></li>
- <li><a name="toc-AUTHOR-12" href="#perlhacktips-AUTHOR">30.9
AUTHOR</a></li>
- </ul></li>
- <li><a name="toc-perlhacktut-1" href="#perlhacktut">31 perlhacktut</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-30" href="#perlhacktut-NAME">31.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-30" href="#perlhacktut-DESCRIPTION">31.2
DESCRIPTION</a></li>
- <li><a name="toc-EXAMPLE-OF-A-SIMPLE-PATCH"
href="#perlhacktut-EXAMPLE-OF-A-SIMPLE-PATCH">31.3 EXAMPLE OF A SIMPLE PATCH</a>
- <ul class="no-bullet">
- <li><a name="toc-Writing-the-patch"
href="#perlhacktut-Writing-the-patch">31.3.1 Writing the patch</a></li>
- <li><a name="toc-Testing-the-patch"
href="#perlhacktut-Testing-the-patch">31.3.2 Testing the patch</a></li>
- <li><a name="toc-Documenting-the-patch"
href="#perlhacktut-Documenting-the-patch">31.3.3 Documenting the patch</a></li>
- <li><a name="toc-Submit" href="#perlhacktut-Submit">31.3.4
Submit</a></li>
- </ul></li>
- <li><a name="toc-AUTHOR-13" href="#perlhacktut-AUTHOR">31.4 AUTHOR</a></li>
- </ul></li>
- <li><a name="toc-perlhist-1" href="#perlhist">32 perlhist</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-31" href="#perlhist-NAME">32.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-31" href="#perlhist-DESCRIPTION">32.2
DESCRIPTION</a></li>
- <li><a name="toc-INTRODUCTION" href="#perlhist-INTRODUCTION">32.3
INTRODUCTION</a></li>
- <li><a name="toc-THE-KEEPERS-OF-THE-PUMPKIN"
href="#perlhist-THE-KEEPERS-OF-THE-PUMPKIN">32.4 THE KEEPERS OF THE PUMPKIN</a>
- <ul class="no-bullet">
- <li><a name="toc-PUMPKIN_003f" href="#perlhist-PUMPKIN_003f">32.4.1
PUMPKIN?</a></li>
- </ul></li>
- <li><a name="toc-THE-RECORDS" href="#perlhist-THE-RECORDS">32.5 THE
RECORDS</a>
- <ul class="no-bullet">
- <li><a name="toc-SELECTED-RELEASE-SIZES"
href="#perlhist-SELECTED-RELEASE-SIZES">32.5.1 SELECTED RELEASE SIZES</a></li>
- <li><a name="toc-SELECTED-PATCH-SIZES"
href="#perlhist-SELECTED-PATCH-SIZES">32.5.2 SELECTED PATCH SIZES</a>
- <ul class="no-bullet">
- <li><a name="toc-The-patch_002dfree-era"
href="#perlhist-The-patch_002dfree-era">32.5.2.1 The patch-free era</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-THE-KEEPERS-OF-THE-RECORDS"
href="#perlhist-THE-KEEPERS-OF-THE-RECORDS">32.6 THE KEEPERS OF THE
RECORDS</a></li>
- </ul></li>
- <li><a name="toc-perlinterp-1" href="#perlinterp">33 perlinterp</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-32" href="#perlinterp-NAME">33.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-32" href="#perlinterp-DESCRIPTION">33.2
DESCRIPTION</a></li>
- <li><a name="toc-ELEMENTS-OF-THE-INTERPRETER"
href="#perlinterp-ELEMENTS-OF-THE-INTERPRETER">33.3 ELEMENTS OF THE
INTERPRETER</a>
- <ul class="no-bullet">
- <li><a name="toc-Startup" href="#perlinterp-Startup">33.3.1
Startup</a></li>
- <li><a name="toc-Parsing" href="#perlinterp-Parsing">33.3.2
Parsing</a></li>
- <li><a name="toc-Optimization" href="#perlinterp-Optimization">33.3.3
Optimization</a></li>
- <li><a name="toc-Running" href="#perlinterp-Running">33.3.4
Running</a></li>
- <li><a name="toc-Exception-handing"
href="#perlinterp-Exception-handing">33.3.5 Exception handing</a></li>
- <li><a name="toc-INTERNAL-VARIABLE-TYPES"
href="#perlinterp-INTERNAL-VARIABLE-TYPES">33.3.6 INTERNAL VARIABLE
TYPES</a></li>
- </ul></li>
- <li><a name="toc-OP-TREES" href="#perlinterp-OP-TREES">33.4 OP
TREES</a></li>
- <li><a name="toc-STACKS" href="#perlinterp-STACKS">33.5 STACKS</a>
- <ul class="no-bullet">
- <li><a name="toc-Argument-stack"
href="#perlinterp-Argument-stack">33.5.1 Argument stack</a></li>
- <li><a name="toc-Mark-stack" href="#perlinterp-Mark-stack">33.5.2 Mark
stack</a></li>
- <li><a name="toc-Save-stack" href="#perlinterp-Save-stack">33.5.3 Save
stack</a></li>
- </ul></li>
- <li><a name="toc-MILLIONS-OF-MACROS"
href="#perlinterp-MILLIONS-OF-MACROS">33.6 MILLIONS OF MACROS</a></li>
- <li><a name="toc-FURTHER-READING" href="#perlinterp-FURTHER-READING">33.7
FURTHER READING</a></li>
- </ul></li>
- <li><a name="toc-perlintro-1" href="#perlintro">34 perlintro</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-33" href="#perlintro-NAME">34.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-33" href="#perlintro-DESCRIPTION">34.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-What-is-Perl_003f"
href="#perlintro-What-is-Perl_003f">34.2.1 What is Perl?</a></li>
- <li><a name="toc-Running-Perl-programs"
href="#perlintro-Running-Perl-programs">34.2.2 Running Perl programs</a></li>
- <li><a name="toc-Safety-net" href="#perlintro-Safety-net">34.2.3 Safety
net</a></li>
- <li><a name="toc-Basic-syntax-overview"
href="#perlintro-Basic-syntax-overview">34.2.4 Basic syntax overview</a></li>
- <li><a name="toc-Perl-variable-types"
href="#perlintro-Perl-variable-types">34.2.5 Perl variable types</a></li>
- <li><a name="toc-Variable-scoping"
href="#perlintro-Variable-scoping">34.2.6 Variable scoping</a></li>
- <li><a name="toc-Conditional-and-looping-constructs"
href="#perlintro-Conditional-and-looping-constructs">34.2.7 Conditional and
looping constructs</a></li>
- <li><a name="toc-Builtin-operators-and-functions"
href="#perlintro-Builtin-operators-and-functions">34.2.8 Builtin operators and
functions</a></li>
- <li><a name="toc-Files-and-I_002fO"
href="#perlintro-Files-and-I_002fO">34.2.9 Files and I/O</a></li>
- <li><a name="toc-Regular-expressions"
href="#perlintro-Regular-expressions">34.2.10 Regular expressions</a></li>
- <li><a name="toc-Writing-subroutines"
href="#perlintro-Writing-subroutines">34.2.11 Writing subroutines</a></li>
- <li><a name="toc-OO-Perl" href="#perlintro-OO-Perl">34.2.12 OO
Perl</a></li>
- <li><a name="toc-Using-Perl-modules"
href="#perlintro-Using-Perl-modules">34.2.13 Using Perl modules</a></li>
- </ul></li>
- <li><a name="toc-AUTHOR-14" href="#perlintro-AUTHOR">34.3 AUTHOR</a></li>
- </ul></li>
- <li><a name="toc-perliol-1" href="#perliol">35 perliol</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-34" href="#perliol-NAME">35.1 NAME</a></li>
- <li><a name="toc-SYNOPSIS-7" href="#perliol-SYNOPSIS">35.2
SYNOPSIS</a></li>
- <li><a name="toc-DESCRIPTION-34" href="#perliol-DESCRIPTION">35.3
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-History-and-Background"
href="#perliol-History-and-Background">35.3.1 History and Background</a></li>
- <li><a name="toc-Basic-Structure" href="#perliol-Basic-Structure">35.3.2
Basic Structure</a></li>
- <li><a name="toc-Layers-vs-Disciplines"
href="#perliol-Layers-vs-Disciplines">35.3.3 Layers vs Disciplines</a></li>
- <li><a name="toc-Data-Structures" href="#perliol-Data-Structures">35.3.4
Data Structures</a></li>
- <li><a name="toc-Functions-and-Attributes"
href="#perliol-Functions-and-Attributes">35.3.5 Functions and
Attributes</a></li>
- <li><a name="toc-Per_002dinstance-Data"
href="#perliol-Per_002dinstance-Data">35.3.6 Per-instance Data</a></li>
- <li><a name="toc-Layers-in-action_002e"
href="#perliol-Layers-in-action_002e">35.3.7 Layers in action.</a></li>
- <li><a name="toc-Per_002dinstance-flag-bits"
href="#perliol-Per_002dinstance-flag-bits">35.3.8 Per-instance flag
bits</a></li>
- <li><a name="toc-Methods-in-Detail"
href="#perliol-Methods-in-Detail">35.3.9 Methods in Detail</a></li>
- <li><a name="toc-Utilities" href="#perliol-Utilities">35.3.10
Utilities</a></li>
- <li><a name="toc-Implementing-PerlIO-Layers"
href="#perliol-Implementing-PerlIO-Layers">35.3.11 Implementing PerlIO
Layers</a></li>
- <li><a name="toc-Core-Layers" href="#perliol-Core-Layers">35.3.12 Core
Layers</a></li>
- <li><a name="toc-Extension-Layers"
href="#perliol-Extension-Layers">35.3.13 Extension Layers</a></li>
- </ul></li>
- <li><a name="toc-TODO" href="#perliol-TODO">35.4 TODO</a></li>
- </ul></li>
- <li><a name="toc-perlipc-1" href="#perlipc">36 perlipc</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-35" href="#perlipc-NAME">36.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-35" href="#perlipc-DESCRIPTION">36.2
DESCRIPTION</a></li>
- <li><a name="toc-Signals" href="#perlipc-Signals">36.3 Signals</a>
- <ul class="no-bullet">
- <li><a name="toc-Handling-the-SIGHUP-Signal-in-Daemons"
href="#perlipc-Handling-the-SIGHUP-Signal-in-Daemons">36.3.1 Handling the
SIGHUP Signal in Daemons</a></li>
- <li><a name="toc-Deferred-Signals-_0028Safe-Signals_0029"
href="#perlipc-Deferred-Signals-_0028Safe-Signals_0029">36.3.2 Deferred Signals
(Safe Signals)</a></li>
- </ul></li>
- <li><a name="toc-Named-Pipes" href="#perlipc-Named-Pipes">36.4 Named
Pipes</a></li>
- <li><a name="toc-Using-open_0028_0029-for-IPC"
href="#perlipc-Using-open_0028_0029-for-IPC">36.5 Using open() for IPC</a>
- <ul class="no-bullet">
- <li><a name="toc-Filehandles" href="#perlipc-Filehandles">36.5.1
Filehandles</a></li>
- <li><a name="toc-Background-Processes"
href="#perlipc-Background-Processes">36.5.2 Background Processes</a></li>
- <li><a name="toc-Complete-Dissociation-of-Child-from-Parent"
href="#perlipc-Complete-Dissociation-of-Child-from-Parent">36.5.3 Complete
Dissociation of Child from Parent</a></li>
- <li><a name="toc-Safe-Pipe-Opens" href="#perlipc-Safe-Pipe-Opens">36.5.4
Safe Pipe Opens</a></li>
- <li><a name="toc-Avoiding-Pipe-Deadlocks"
href="#perlipc-Avoiding-Pipe-Deadlocks">36.5.5 Avoiding Pipe Deadlocks</a></li>
- <li><a name="toc-Bidirectional-Communication-with-Another-Process"
href="#perlipc-Bidirectional-Communication-with-Another-Process">36.5.6
Bidirectional Communication with Another Process</a></li>
- <li><a name="toc-Bidirectional-Communication-with-Yourself"
href="#perlipc-Bidirectional-Communication-with-Yourself">36.5.7 Bidirectional
Communication with Yourself</a></li>
- </ul></li>
- <li><a name="toc-Sockets_003a-Client_002fServer-Communication"
href="#perlipc-Sockets_003a-Client_002fServer-Communication">36.6 Sockets:
Client/Server Communication</a>
- <ul class="no-bullet">
- <li><a name="toc-Internet-Line-Terminators"
href="#perlipc-Internet-Line-Terminators">36.6.1 Internet Line
Terminators</a></li>
- <li><a name="toc-Internet-TCP-Clients-and-Servers"
href="#perlipc-Internet-TCP-Clients-and-Servers">36.6.2 Internet TCP Clients
and Servers</a></li>
- <li><a name="toc-Unix_002dDomain-TCP-Clients-and-Servers"
href="#perlipc-Unix_002dDomain-TCP-Clients-and-Servers">36.6.3 Unix-Domain TCP
Clients and Servers</a></li>
- </ul></li>
- <li><a name="toc-TCP-Clients-with-IO_003a_003aSocket"
href="#perlipc-TCP-Clients-with-IO_003a_003aSocket">36.7 TCP Clients with
IO::Socket</a>
- <ul class="no-bullet">
- <li><a name="toc-A-Simple-Client" href="#perlipc-A-Simple-Client">36.7.1
A Simple Client</a></li>
- <li><a name="toc-A-Webget-Client" href="#perlipc-A-Webget-Client">36.7.2
A Webget Client</a></li>
- <li><a name="toc-Interactive-Client-with-IO_003a_003aSocket"
href="#perlipc-Interactive-Client-with-IO_003a_003aSocket">36.7.3 Interactive
Client with IO::Socket</a></li>
- </ul></li>
- <li><a name="toc-TCP-Servers-with-IO_003a_003aSocket"
href="#perlipc-TCP-Servers-with-IO_003a_003aSocket">36.8 TCP Servers with
IO::Socket</a></li>
- <li><a name="toc-UDP_003a-Message-Passing"
href="#perlipc-UDP_003a-Message-Passing">36.9 UDP: Message Passing</a></li>
- <li><a name="toc-SysV-IPC" href="#perlipc-SysV-IPC">36.10 SysV IPC</a></li>
- <li><a name="toc-NOTES-2" href="#perlipc-NOTES">36.11 NOTES</a></li>
- <li><a name="toc-BUGS-4" href="#perlipc-BUGS">36.12 BUGS</a></li>
- <li><a name="toc-AUTHOR-15" href="#perlipc-AUTHOR">36.13 AUTHOR</a></li>
- <li><a name="toc-SEE-ALSO-16" href="#perlipc-SEE-ALSO">36.14 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perllexwarn-1" href="#perllexwarn">37 perllexwarn</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-36" href="#perllexwarn-NAME">37.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-36" href="#perllexwarn-DESCRIPTION">37.2
DESCRIPTION</a></li>
- </ul></li>
- <li><a name="toc-perllocale-1" href="#perllocale">38 perllocale</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-37" href="#perllocale-NAME">38.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-37" href="#perllocale-DESCRIPTION">38.2
DESCRIPTION</a></li>
- <li><a name="toc-WHAT-IS-A-LOCALE"
href="#perllocale-WHAT-IS-A-LOCALE">38.3 WHAT IS A LOCALE</a></li>
- <li><a name="toc-PREPARING-TO-USE-LOCALES"
href="#perllocale-PREPARING-TO-USE-LOCALES">38.4 PREPARING TO USE
LOCALES</a></li>
- <li><a name="toc-USING-LOCALES" href="#perllocale-USING-LOCALES">38.5
USING LOCALES</a>
- <ul class="no-bullet">
- <li><a name="toc-The-_0022use-locale_0022-pragma"
href="#perllocale-The-_0022use-locale_0022-pragma">38.5.1 The <code>"use
locale"</code> pragma</a></li>
- <li><a name="toc-The-setlocale-function"
href="#perllocale-The-setlocale-function">38.5.2 The setlocale function</a></li>
- <li><a name="toc-Finding-locales"
href="#perllocale-Finding-locales">38.5.3 Finding locales</a></li>
- <li><a name="toc-LOCALE-PROBLEMS"
href="#perllocale-LOCALE-PROBLEMS">38.5.4 LOCALE PROBLEMS</a></li>
- <li><a name="toc-Testing-for-broken-locales"
href="#perllocale-Testing-for-broken-locales">38.5.5 Testing for broken
locales</a></li>
- <li><a name="toc-Temporarily-fixing-locale-problems"
href="#perllocale-Temporarily-fixing-locale-problems">38.5.6 Temporarily fixing
locale problems</a></li>
- <li><a name="toc-Permanently-fixing-locale-problems"
href="#perllocale-Permanently-fixing-locale-problems">38.5.7 Permanently fixing
locale problems</a></li>
- <li><a
name="toc-Permanently-fixing-your-system_0027s-locale-configuration"
href="#perllocale-Permanently-fixing-your-system_0027s-locale-configuration">38.5.8
Permanently fixing your system’s locale configuration</a></li>
- <li><a name="toc-Fixing-system-locale-configuration"
href="#perllocale-Fixing-system-locale-configuration">38.5.9 Fixing system
locale configuration</a></li>
- <li><a name="toc-The-localeconv-function"
href="#perllocale-The-localeconv-function">38.5.10 The localeconv
function</a></li>
- <li><a name="toc-I18N_003a_003aLanginfo"
href="#perllocale-I18N_003a_003aLanginfo">38.5.11 I18N::Langinfo</a></li>
- </ul></li>
- <li><a name="toc-LOCALE-CATEGORIES"
href="#perllocale-LOCALE-CATEGORIES">38.6 LOCALE CATEGORIES</a>
- <ul class="no-bullet">
- <li><a name="toc-Category-LC_005fCOLLATE_003a-Collation"
href="#perllocale-Category-LC_005fCOLLATE_003a-Collation-1">38.6.1 Category
<code>LC_COLLATE</code>: Collation</a></li>
- <li><a name="toc-Category-LC_005fCTYPE_003a-Character-Types"
href="#perllocale-Category-LC_005fCTYPE_003a-Character-Types-1">38.6.2 Category
<code>LC_CTYPE</code>: Character Types</a></li>
- <li><a name="toc-Category-LC_005fNUMERIC_003a-Numeric-Formatting"
href="#perllocale-Category-LC_005fNUMERIC_003a-Numeric-Formatting">38.6.3
Category <code>LC_NUMERIC</code>: Numeric Formatting</a></li>
- <li><a
name="toc-Category-LC_005fMONETARY_003a-Formatting-of-monetary-amounts"
href="#perllocale-Category-LC_005fMONETARY_003a-Formatting-of-monetary-amounts-1">38.6.4
Category <code>LC_MONETARY</code>: Formatting of monetary amounts</a></li>
- <li><a name="toc-LC_005fTIME" href="#perllocale-LC_005fTIME">38.6.5
<code>LC_TIME</code></a></li>
- <li><a name="toc-Other-categories"
href="#perllocale-Other-categories-1">38.6.6 Other categories</a></li>
- </ul></li>
- <li><a name="toc-SECURITY" href="#perllocale-SECURITY">38.7
SECURITY</a></li>
- <li><a name="toc-ENVIRONMENT-1" href="#perllocale-ENVIRONMENT">38.8
ENVIRONMENT</a>
- <ul class="no-bullet">
- <li><a name="toc-Examples" href="#perllocale-Examples">38.8.1
Examples</a></li>
- </ul></li>
- <li><a name="toc-NOTES-3" href="#perllocale-NOTES">38.9 NOTES</a>
- <ul class="no-bullet">
- <li><a name="toc-String-eval-and-LC_005fNUMERIC"
href="#perllocale-String-eval-and-LC_005fNUMERIC">38.9.1 String
<code>eval</code> and <code>LC_NUMERIC</code></a></li>
- <li><a name="toc-Backward-compatibility"
href="#perllocale-Backward-compatibility">38.9.2 Backward compatibility</a></li>
- <li><a name="toc-I18N_003aCollate-obsolete"
href="#perllocale-I18N_003aCollate-obsolete">38.9.3 I18N:Collate
obsolete</a></li>
- <li><a name="toc-Sort-speed-and-memory-use-impacts"
href="#perllocale-Sort-speed-and-memory-use-impacts">38.9.4 Sort speed and
memory use impacts</a></li>
- <li><a name="toc-Freely-available-locale-definitions"
href="#perllocale-Freely-available-locale-definitions">38.9.5 Freely available
locale definitions</a></li>
- <li><a name="toc-I18n-and-l10n" href="#perllocale-I18n-and-l10n">38.9.6
I18n and l10n</a></li>
- <li><a name="toc-An-imperfect-standard"
href="#perllocale-An-imperfect-standard">38.9.7 An imperfect standard</a></li>
- </ul></li>
- <li><a name="toc-Unicode-and-UTF_002d8"
href="#perllocale-Unicode-and-UTF_002d8">38.10 Unicode and UTF-8</a></li>
- <li><a name="toc-BUGS-5" href="#perllocale-BUGS">38.11 BUGS</a>
- <ul class="no-bullet">
- <li><a name="toc-Broken-systems"
href="#perllocale-Broken-systems">38.11.1 Broken systems</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-17" href="#perllocale-SEE-ALSO">38.12 SEE
ALSO</a></li>
- <li><a name="toc-HISTORY-2" href="#perllocale-HISTORY">38.13
HISTORY</a></li>
- </ul></li>
- <li><a name="toc-perllol-1" href="#perllol">39 perllol</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-38" href="#perllol-NAME">39.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-38" href="#perllol-DESCRIPTION">39.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Declaration-and-Access-of-Arrays-of-Arrays"
href="#perllol-Declaration-and-Access-of-Arrays-of-Arrays">39.2.1 Declaration
and Access of Arrays of Arrays</a></li>
- <li><a name="toc-Growing-Your-Own"
href="#perllol-Growing-Your-Own">39.2.2 Growing Your Own</a></li>
- <li><a name="toc-Access-and-Printing"
href="#perllol-Access-and-Printing">39.2.3 Access and Printing</a></li>
- <li><a name="toc-Slices-1" href="#perllol-Slices">39.2.4 Slices</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-18" href="#perllol-SEE-ALSO">39.3 SEE
ALSO</a></li>
- <li><a name="toc-AUTHOR-16" href="#perllol-AUTHOR">39.4 AUTHOR</a></li>
- </ul></li>
- <li><a name="toc-perlmod-2" href="#perlmod">40 perlmod</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-39" href="#perlmod-NAME">40.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-39" href="#perlmod-DESCRIPTION">40.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Is-this-the-document-you-were-after_003f"
href="#perlmod-Is-this-the-document-you-were-after_003f">40.2.1 Is this the
document you were after?</a></li>
- <li><a name="toc-Packages" href="#perlmod-Packages">40.2.2
Packages</a></li>
- <li><a name="toc-Symbol-Tables" href="#perlmod-Symbol-Tables">40.2.3
Symbol Tables</a></li>
- <li><a name="toc-BEGIN_002c-UNITCHECK_002c-CHECK_002c-INIT-and-END"
href="#perlmod-BEGIN_002c-UNITCHECK_002c-CHECK_002c-INIT-and-END">40.2.4 BEGIN,
UNITCHECK, CHECK, INIT and END</a></li>
- <li><a name="toc-Perl-Classes" href="#perlmod-Perl-Classes">40.2.5 Perl
Classes</a></li>
- <li><a name="toc-Perl-Modules" href="#perlmod-Perl-Modules">40.2.6 Perl
Modules</a></li>
- <li><a name="toc-Making-your-module-threadsafe"
href="#perlmod-Making-your-module-threadsafe">40.2.7 Making your module
threadsafe</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-19" href="#perlmod-SEE-ALSO">40.3 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlmodinstall-1" href="#perlmodinstall">41
perlmodinstall</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-40" href="#perlmodinstall-NAME">41.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-40" href="#perlmodinstall-DESCRIPTION">41.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-PREAMBLE-1" href="#perlmodinstall-PREAMBLE">41.2.1
PREAMBLE</a></li>
- </ul></li>
- <li><a name="toc-PORTABILITY" href="#perlmodinstall-PORTABILITY">41.3
PORTABILITY</a></li>
- <li><a name="toc-HEY" href="#perlmodinstall-HEY">41.4 HEY</a></li>
- <li><a name="toc-AUTHOR-17" href="#perlmodinstall-AUTHOR">41.5
AUTHOR</a></li>
- <li><a name="toc-COPYRIGHT-2" href="#perlmodinstall-COPYRIGHT">41.6
COPYRIGHT</a></li>
- </ul></li>
- <li><a name="toc-perlmodstyle-1" href="#perlmodstyle">42 perlmodstyle</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-41" href="#perlmodstyle-NAME">42.1 NAME</a></li>
- <li><a name="toc-INTRODUCTION-1" href="#perlmodstyle-INTRODUCTION">42.2
INTRODUCTION</a></li>
- <li><a name="toc-QUICK-CHECKLIST"
href="#perlmodstyle-QUICK-CHECKLIST">42.3 QUICK CHECKLIST</a>
- <ul class="no-bullet">
- <li><a name="toc-Before-you-start"
href="#perlmodstyle-Before-you-start">42.3.1 Before you start</a></li>
- <li><a name="toc-The-API" href="#perlmodstyle-The-API">42.3.2 The
API</a></li>
- <li><a name="toc-Stability" href="#perlmodstyle-Stability">42.3.3
Stability</a></li>
- <li><a name="toc-Documentation"
href="#perlmodstyle-Documentation">42.3.4 Documentation</a></li>
- <li><a name="toc-Release-considerations"
href="#perlmodstyle-Release-considerations">42.3.5 Release
considerations</a></li>
- </ul></li>
- <li><a name="toc-BEFORE-YOU-START-WRITING-A-MODULE"
href="#perlmodstyle-BEFORE-YOU-START-WRITING-A-MODULE">42.4 BEFORE YOU START
WRITING A MODULE</a>
- <ul class="no-bullet">
- <li><a name="toc-Has-it-been-done-before_003f"
href="#perlmodstyle-Has-it-been-done-before_003f">42.4.1 Has it been done
before?</a></li>
- <li><a name="toc-Do-one-thing-and-do-it-well"
href="#perlmodstyle-Do-one-thing-and-do-it-well">42.4.2 Do one thing and do it
well</a></li>
- <li><a name="toc-What_0027s-in-a-name_003f"
href="#perlmodstyle-What_0027s-in-a-name_003f">42.4.3 What’s in a
name?</a></li>
- <li><a name="toc-Get-feedback-before-publishing"
href="#perlmodstyle-Get-feedback-before-publishing">42.4.4 Get feedback before
publishing</a></li>
- </ul></li>
- <li><a name="toc-DESIGNING-AND-WRITING-YOUR-MODULE"
href="#perlmodstyle-DESIGNING-AND-WRITING-YOUR-MODULE">42.5 DESIGNING AND
WRITING YOUR MODULE</a>
- <ul class="no-bullet">
- <li><a name="toc-To-OO-or-not-to-OO_003f"
href="#perlmodstyle-To-OO-or-not-to-OO_003f">42.5.1 To OO or not to OO?</a></li>
- <li><a name="toc-Designing-your-API"
href="#perlmodstyle-Designing-your-API">42.5.2 Designing your API</a></li>
- <li><a name="toc-Strictness-and-warnings"
href="#perlmodstyle-Strictness-and-warnings">42.5.3 Strictness and
warnings</a></li>
- <li><a name="toc-Backwards-compatibility-2"
href="#perlmodstyle-Backwards-compatibility">42.5.4 Backwards
compatibility</a></li>
- <li><a name="toc-Error-handling-and-messages"
href="#perlmodstyle-Error-handling-and-messages">42.5.5 Error handling and
messages</a></li>
- </ul></li>
- <li><a name="toc-DOCUMENTING-YOUR-MODULE"
href="#perlmodstyle-DOCUMENTING-YOUR-MODULE">42.6 DOCUMENTING YOUR MODULE</a>
- <ul class="no-bullet">
- <li><a name="toc-POD" href="#perlmodstyle-POD">42.6.1 POD</a></li>
- <li><a name="toc-README_002c-INSTALL_002c-release-notes_002c-changelogs"
href="#perlmodstyle-README_002c-INSTALL_002c-release-notes_002c-changelogs">42.6.2
README, INSTALL, release notes, changelogs</a></li>
- </ul></li>
- <li><a name="toc-RELEASE-CONSIDERATIONS"
href="#perlmodstyle-RELEASE-CONSIDERATIONS">42.7 RELEASE CONSIDERATIONS</a>
- <ul class="no-bullet">
- <li><a name="toc-Version-numbering"
href="#perlmodstyle-Version-numbering">42.7.1 Version numbering</a></li>
- <li><a name="toc-Pre_002drequisites"
href="#perlmodstyle-Pre_002drequisites">42.7.2 Pre-requisites</a></li>
- <li><a name="toc-Testing" href="#perlmodstyle-Testing">42.7.3
Testing</a></li>
- <li><a name="toc-Packaging" href="#perlmodstyle-Packaging">42.7.4
Packaging</a></li>
- <li><a name="toc-Licensing" href="#perlmodstyle-Licensing">42.7.5
Licensing</a></li>
- </ul></li>
- <li><a name="toc-COMMON-PITFALLS"
href="#perlmodstyle-COMMON-PITFALLS">42.8 COMMON PITFALLS</a>
- <ul class="no-bullet">
- <li><a name="toc-Reinventing-the-wheel"
href="#perlmodstyle-Reinventing-the-wheel">42.8.1 Reinventing the wheel</a></li>
- <li><a name="toc-Trying-to-do-too-much"
href="#perlmodstyle-Trying-to-do-too-much">42.8.2 Trying to do too much</a></li>
- <li><a name="toc-Inappropriate-documentation"
href="#perlmodstyle-Inappropriate-documentation">42.8.3 Inappropriate
documentation</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-20" href="#perlmodstyle-SEE-ALSO">42.9 SEE
ALSO</a></li>
- <li><a name="toc-AUTHOR-18" href="#perlmodstyle-AUTHOR">42.10
AUTHOR</a></li>
- </ul></li>
- <li><a name="toc-perlmroapi-1" href="#perlmroapi">43 perlmroapi</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-42" href="#perlmroapi-NAME">43.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-41" href="#perlmroapi-DESCRIPTION">43.2
DESCRIPTION</a></li>
- <li><a name="toc-Callbacks" href="#perlmroapi-Callbacks">43.3
Callbacks</a></li>
- <li><a name="toc-Caching" href="#perlmroapi-Caching">43.4 Caching</a></li>
- <li><a name="toc-Examples-1" href="#perlmroapi-Examples">43.5
Examples</a></li>
- <li><a name="toc-AUTHORS-3" href="#perlmroapi-AUTHORS">43.6
AUTHORS</a></li>
- </ul></li>
- <li><a name="toc-perlnewmod-1" href="#perlnewmod">44 perlnewmod</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-43" href="#perlnewmod-NAME">44.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-42" href="#perlnewmod-DESCRIPTION">44.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Warning" href="#perlnewmod-Warning">44.2.1
Warning</a></li>
- <li><a name="toc-What-should-I-make-into-a-module_003f"
href="#perlnewmod-What-should-I-make-into-a-module_003f">44.2.2 What should I
make into a module?</a></li>
- <li><a name="toc-Step_002dby_002dstep_003a-Preparing-the-ground"
href="#perlnewmod-Step_002dby_002dstep_003a-Preparing-the-ground">44.2.3
Step-by-step: Preparing the ground</a></li>
- <li><a name="toc-Step_002dby_002dstep_003a-Making-the-module"
href="#perlnewmod-Step_002dby_002dstep_003a-Making-the-module">44.2.4
Step-by-step: Making the module</a></li>
- <li><a name="toc-Step_002dby_002dstep_003a-Distributing-your-module"
href="#perlnewmod-Step_002dby_002dstep_003a-Distributing-your-module">44.2.5
Step-by-step: Distributing your module</a></li>
- </ul></li>
- <li><a name="toc-AUTHOR-19" href="#perlnewmod-AUTHOR">44.3 AUTHOR</a></li>
- <li><a name="toc-SEE-ALSO-21" href="#perlnewmod-SEE-ALSO">44.4 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlnumber-1" href="#perlnumber">45 perlnumber</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-44" href="#perlnumber-NAME">45.1 NAME</a></li>
- <li><a name="toc-SYNOPSIS-8" href="#perlnumber-SYNOPSIS">45.2
SYNOPSIS</a></li>
- <li><a name="toc-DESCRIPTION-43" href="#perlnumber-DESCRIPTION">45.3
DESCRIPTION</a></li>
- <li><a name="toc-Storing-numbers" href="#perlnumber-Storing-numbers">45.4
Storing numbers</a></li>
- <li><a name="toc-Numeric-operators-and-numeric-conversions"
href="#perlnumber-Numeric-operators-and-numeric-conversions">45.5 Numeric
operators and numeric conversions</a></li>
- <li><a name="toc-Flavors-of-Perl-numeric-operations"
href="#perlnumber-Flavors-of-Perl-numeric-operations">45.6 Flavors of Perl
numeric operations</a></li>
- <li><a name="toc-AUTHOR-20" href="#perlnumber-AUTHOR">45.7 AUTHOR</a></li>
- <li><a name="toc-SEE-ALSO-22" href="#perlnumber-SEE-ALSO">45.8 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlobj-2" href="#perlobj">46 perlobj</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-45" href="#perlobj-NAME">46.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-44" href="#perlobj-DESCRIPTION">46.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-An-Object-is-Simply-a-Data-Structure"
href="#perlobj-An-Object-is-Simply-a-Data-Structure">46.2.1 An Object is Simply
a Data Structure</a>
- <ul class="no-bullet">
- <li><a name="toc-Objects-Are-Blessed_003b-Variables-Are-Not"
href="#perlobj-Objects-Are-Blessed_003b-Variables-Are-Not">46.2.1.1 Objects Are
Blessed; Variables Are Not</a></li>
- </ul></li>
- <li><a name="toc-A-Class-is-Simply-a-Package"
href="#perlobj-A-Class-is-Simply-a-Package">46.2.2 A Class is Simply a
Package</a></li>
- <li><a name="toc-A-Method-is-Simply-a-Subroutine"
href="#perlobj-A-Method-is-Simply-a-Subroutine">46.2.3 A Method is Simply a
Subroutine</a></li>
- <li><a name="toc-Method-Invocation-_003e_003e"
href="#perlobj-Method-Invocation-_003e_003e">46.2.4 Method Invocation
>></a></li>
- <li><a name="toc-Inheritance" href="#perlobj-Inheritance">46.2.5
Inheritance</a>
- <ul class="no-bullet">
- <li><a name="toc-How-SUPER-is-Resolved"
href="#perlobj-How-SUPER-is-Resolved">46.2.5.1 How SUPER is Resolved</a></li>
- <li><a name="toc-Multiple-Inheritance"
href="#perlobj-Multiple-Inheritance">46.2.5.2 Multiple Inheritance</a></li>
- <li><a name="toc-Method-Resolution-Order"
href="#perlobj-Method-Resolution-Order">46.2.5.3 Method Resolution
Order</a></li>
- <li><a name="toc-Method-Resolution-Caching"
href="#perlobj-Method-Resolution-Caching">46.2.5.4 Method Resolution
Caching</a></li>
- </ul></li>
- <li><a name="toc-Writing-Constructors"
href="#perlobj-Writing-Constructors">46.2.6 Writing Constructors</a></li>
- <li><a name="toc-Attributes" href="#perlobj-Attributes">46.2.7
Attributes</a>
- <ul class="no-bullet">
- <li><a name="toc-Writing-Accessors"
href="#perlobj-Writing-Accessors">46.2.7.1 Writing Accessors</a></li>
- </ul></li>
- <li><a name="toc-An-Aside-About-Smarter-and-Safer-Code"
href="#perlobj-An-Aside-About-Smarter-and-Safer-Code">46.2.8 An Aside About
Smarter and Safer Code</a></li>
- <li><a name="toc-Method-Call-Variations"
href="#perlobj-Method-Call-Variations">46.2.9 Method Call Variations</a>
- <ul class="no-bullet">
- <li><a name="toc-Method-Names-as-Strings"
href="#perlobj-Method-Names-as-Strings">46.2.9.1 Method Names as
Strings</a></li>
- <li><a name="toc-Class-Names-as-Strings"
href="#perlobj-Class-Names-as-Strings">46.2.9.2 Class Names as Strings</a></li>
- <li><a name="toc-Subroutine-References-as-Methods"
href="#perlobj-Subroutine-References-as-Methods">46.2.9.3 Subroutine References
as Methods</a></li>
- <li><a name="toc-Deferencing-Method-Call"
href="#perlobj-Deferencing-Method-Call">46.2.9.4 Deferencing Method
Call</a></li>
- <li><a name="toc-Method-Calls-on-Filehandles"
href="#perlobj-Method-Calls-on-Filehandles">46.2.9.5 Method Calls on
Filehandles</a></li>
- </ul></li>
- <li><a name="toc-Invoking-Class-Methods"
href="#perlobj-Invoking-Class-Methods">46.2.10 Invoking Class Methods</a>
- <ul class="no-bullet">
- <li><a name="toc-Indirect-Object-Syntax"
href="#perlobj-Indirect-Object-Syntax">46.2.10.1 Indirect Object Syntax</a></li>
- </ul></li>
- <li><a name="toc-bless_002c-blessed_002c-and-ref"
href="#perlobj-bless_002c-blessed_002c-and-ref">46.2.11 <code>bless</code>,
<code>blessed</code>, and <code>ref</code></a></li>
- <li><a name="toc-The-UNIVERSAL-Class"
href="#perlobj-The-UNIVERSAL-Class">46.2.12 The UNIVERSAL Class</a></li>
- <li><a name="toc-AUTOLOAD" href="#perlobj-AUTOLOAD">46.2.13
AUTOLOAD</a></li>
- <li><a name="toc-Destructors" href="#perlobj-Destructors">46.2.14
Destructors</a>
- <ul class="no-bullet">
- <li><a name="toc-Global-Destruction"
href="#perlobj-Global-Destruction">46.2.14.1 Global Destruction</a></li>
- </ul></li>
- <li><a name="toc-Non_002dHash-Objects"
href="#perlobj-Non_002dHash-Objects">46.2.15 Non-Hash Objects</a></li>
- <li><a name="toc-Inside_002dOut-objects"
href="#perlobj-Inside_002dOut-objects">46.2.16 Inside-Out objects</a></li>
- <li><a name="toc-Pseudo_002dhashes"
href="#perlobj-Pseudo_002dhashes">46.2.17 Pseudo-hashes</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-23" href="#perlobj-SEE-ALSO">46.3 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlootut-1" href="#perlootut">47 perlootut</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-46" href="#perlootut-NAME">47.1 NAME</a></li>
- <li><a name="toc-DATE-1" href="#perlootut-DATE">47.2 DATE</a></li>
- <li><a name="toc-DESCRIPTION-45" href="#perlootut-DESCRIPTION">47.3
DESCRIPTION</a></li>
- <li><a name="toc-OBJECT_002dORIENTED-FUNDAMENTALS"
href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS">47.4 OBJECT-ORIENTED
FUNDAMENTALS</a>
- <ul class="no-bullet">
- <li><a name="toc-Object" href="#perlootut-Object">47.4.1 Object</a></li>
- <li><a name="toc-Class" href="#perlootut-Class">47.4.2 Class</a>
- <ul class="no-bullet">
- <li><a name="toc-Blessing" href="#perlootut-Blessing">47.4.2.1
Blessing</a></li>
- <li><a name="toc-Constructor" href="#perlootut-Constructor">47.4.2.2
Constructor</a></li>
- </ul></li>
- <li><a name="toc-Methods" href="#perlootut-Methods">47.4.3
Methods</a></li>
- <li><a name="toc-Attributes-1" href="#perlootut-Attributes">47.4.4
Attributes</a></li>
- <li><a name="toc-Polymorphism" href="#perlootut-Polymorphism">47.4.5
Polymorphism</a></li>
- <li><a name="toc-Inheritance-1" href="#perlootut-Inheritance">47.4.6
Inheritance</a>
- <ul class="no-bullet">
- <li><a name="toc-Overriding-methods-and-method-resolution"
href="#perlootut-Overriding-methods-and-method-resolution">47.4.6.1 Overriding
methods and method resolution</a></li>
- </ul></li>
- <li><a name="toc-Encapsulation" href="#perlootut-Encapsulation">47.4.7
Encapsulation</a></li>
- <li><a name="toc-Composition" href="#perlootut-Composition">47.4.8
Composition</a></li>
- <li><a name="toc-Roles" href="#perlootut-Roles">47.4.9 Roles</a></li>
- <li><a name="toc-When-to-Use-OO"
href="#perlootut-When-to-Use-OO">47.4.10 When to Use OO</a></li>
- </ul></li>
- <li><a name="toc-PERL-OO-SYSTEMS" href="#perlootut-PERL-OO-SYSTEMS">47.5
PERL OO SYSTEMS</a>
- <ul class="no-bullet">
- <li><a name="toc-Moose" href="#perlootut-Moose">47.5.1 Moose</a>
- <ul class="no-bullet">
- <li><a name="toc-Moo" href="#perlootut-Moo">47.5.1.1 Moo</a></li>
- </ul></li>
- <li><a name="toc-Class_003a_003aAccessor"
href="#perlootut-Class_003a_003aAccessor">47.5.2 Class::Accessor</a></li>
- <li><a name="toc-Class_003a_003aTiny"
href="#perlootut-Class_003a_003aTiny">47.5.3 Class::Tiny</a></li>
- <li><a name="toc-Role_003a_003aTiny"
href="#perlootut-Role_003a_003aTiny">47.5.4 Role::Tiny</a></li>
- <li><a name="toc-OO-System-Summary"
href="#perlootut-OO-System-Summary">47.5.5 OO System Summary</a></li>
- <li><a name="toc-Other-OO-Systems"
href="#perlootut-Other-OO-Systems">47.5.6 Other OO Systems</a></li>
- </ul></li>
- <li><a name="toc-CONCLUSION-1" href="#perlootut-CONCLUSION">47.6
CONCLUSION</a></li>
- </ul></li>
- <li><a name="toc-perlop-2" href="#perlop">48 perlop</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-47" href="#perlop-NAME">48.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-46" href="#perlop-DESCRIPTION">48.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Operator-Precedence-and-Associativity"
href="#perlop-Operator-Precedence-and-Associativity">48.2.1 Operator Precedence
and Associativity</a></li>
- <li><a name="toc-Terms-and-List-Operators-_0028Leftward_0029"
href="#perlop-Terms-and-List-Operators-_0028Leftward_0029">48.2.2 Terms and
List Operators (Leftward)</a></li>
- <li><a name="toc-The-Arrow-Operator-_003e_003e"
href="#perlop-The-Arrow-Operator-_003e_003e">48.2.3 The Arrow Operator
>></a></li>
- <li><a name="toc-Auto_002dincrement-and-Auto_002ddecrement"
href="#perlop-Auto_002dincrement-and-Auto_002ddecrement">48.2.4 Auto-increment
and Auto-decrement</a></li>
- <li><a name="toc-Exponentiation" href="#perlop-Exponentiation">48.2.5
Exponentiation</a></li>
- <li><a name="toc-Symbolic-Unary-Operators"
href="#perlop-Symbolic-Unary-Operators">48.2.6 Symbolic Unary Operators</a></li>
- <li><a name="toc-Binding-Operators"
href="#perlop-Binding-Operators">48.2.7 Binding Operators</a></li>
- <li><a name="toc-Multiplicative-Operators"
href="#perlop-Multiplicative-Operators">48.2.8 Multiplicative Operators</a></li>
- <li><a name="toc-Additive-Operators"
href="#perlop-Additive-Operators">48.2.9 Additive Operators</a></li>
- <li><a name="toc-Shift-Operators-_003e-_003e_003e_003e"
href="#perlop-Shift-Operators-_003e-_003e_003e_003e">48.2.10 Shift Operators
> >>></a></li>
- <li><a name="toc-Named-Unary-Operators"
href="#perlop-Named-Unary-Operators">48.2.11 Named Unary Operators</a></li>
- <li><a name="toc-Relational-Operators"
href="#perlop-Relational-Operators">48.2.12 Relational Operators</a></li>
- <li><a name="toc-Equality-Operators"
href="#perlop-Equality-Operators">48.2.13 Equality Operators</a></li>
- <li><a name="toc-Smartmatch-Operator"
href="#perlop-Smartmatch-Operator">48.2.14 Smartmatch Operator</a>
- <ul class="no-bullet">
- <li><a name="toc-Smartmatching-of-Objects"
href="#perlop-Smartmatching-of-Objects">48.2.14.1 Smartmatching of
Objects</a></li>
- </ul></li>
- <li><a name="toc-Bitwise-And" href="#perlop-Bitwise-And">48.2.15 Bitwise
And</a></li>
- <li><a name="toc-Bitwise-Or-and-Exclusive-Or"
href="#perlop-Bitwise-Or-and-Exclusive-Or">48.2.16 Bitwise Or and Exclusive
Or</a></li>
- <li><a name="toc-C_002dstyle-Logical-And"
href="#perlop-C_002dstyle-Logical-And">48.2.17 C-style Logical And</a></li>
- <li><a name="toc-C_002dstyle-Logical-Or"
href="#perlop-C_002dstyle-Logical-Or">48.2.18 C-style Logical Or</a></li>
- <li><a name="toc-Logical-Defined_002dOr"
href="#perlop-Logical-Defined_002dOr">48.2.19 Logical Defined-Or</a></li>
- <li><a name="toc-Range-Operators" href="#perlop-Range-Operators">48.2.20
Range Operators</a></li>
- <li><a name="toc-Conditional-Operator"
href="#perlop-Conditional-Operator">48.2.21 Conditional Operator</a></li>
- <li><a name="toc-Assignment-Operators"
href="#perlop-Assignment-Operators">48.2.22 Assignment Operators</a></li>
- <li><a name="toc-Comma-Operator" href="#perlop-Comma-Operator">48.2.23
Comma Operator</a></li>
- <li><a name="toc-List-Operators-_0028Rightward_0029"
href="#perlop-List-Operators-_0028Rightward_0029">48.2.24 List Operators
(Rightward)</a></li>
- <li><a name="toc-Logical-Not" href="#perlop-Logical-Not">48.2.25 Logical
Not</a></li>
- <li><a name="toc-Logical-And" href="#perlop-Logical-And">48.2.26 Logical
And</a></li>
- <li><a name="toc-Logical-or-and-Exclusive-Or"
href="#perlop-Logical-or-and-Exclusive-Or">48.2.27 Logical or and Exclusive
Or</a></li>
- <li><a name="toc-C-Operators-Missing-From-Perl"
href="#perlop-C-Operators-Missing-From-Perl">48.2.28 C Operators Missing From
Perl</a></li>
- <li><a name="toc-Quote-and-Quote_002dlike-Operators"
href="#perlop-Quote-and-Quote_002dlike-Operators">48.2.29 Quote and Quote-like
Operators</a></li>
- <li><a name="toc-Regexp-Quote_002dLike-Operators"
href="#perlop-Regexp-Quote_002dLike-Operators">48.2.30 Regexp Quote-Like
Operators</a></li>
- <li><a name="toc-Quote_002dLike-Operators"
href="#perlop-Quote_002dLike-Operators">48.2.31 Quote-Like Operators</a></li>
- <li><a name="toc-Gory-details-of-parsing-quoted-constructs"
href="#perlop-Gory-details-of-parsing-quoted-constructs">48.2.32 Gory details
of parsing quoted constructs</a></li>
- <li><a name="toc-I_002fO-Operators"
href="#perlop-I_002fO-Operators">48.2.33 I/O Operators</a></li>
- <li><a name="toc-Constant-Folding"
href="#perlop-Constant-Folding">48.2.34 Constant Folding</a></li>
- <li><a name="toc-No_002dops" href="#perlop-No_002dops">48.2.35
No-ops</a></li>
- <li><a name="toc-Bitwise-String-Operators"
href="#perlop-Bitwise-String-Operators">48.2.36 Bitwise String
Operators</a></li>
- <li><a name="toc-Integer-Arithmetic"
href="#perlop-Integer-Arithmetic">48.2.37 Integer Arithmetic</a></li>
- <li><a name="toc-Floating_002dpoint-Arithmetic"
href="#perlop-Floating_002dpoint-Arithmetic">48.2.38 Floating-point
Arithmetic</a></li>
- <li><a name="toc-Bigger-Numbers" href="#perlop-Bigger-Numbers">48.2.39
Bigger Numbers</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlopentut-1" href="#perlopentut">49 perlopentut</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-48" href="#perlopentut-NAME">49.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-47" href="#perlopentut-DESCRIPTION">49.2
DESCRIPTION</a></li>
- <li><a name="toc-Opening-Text-Files"
href="#perlopentut-Opening-Text-Files">49.3 Opening Text Files</a>
- <ul class="no-bullet">
- <li><a name="toc-Opening-Text-Files-for-Reading"
href="#perlopentut-Opening-Text-Files-for-Reading">49.3.1 Opening Text Files
for Reading</a></li>
- <li><a name="toc-Opening-Text-Files-for-Writing"
href="#perlopentut-Opening-Text-Files-for-Writing">49.3.2 Opening Text Files
for Writing</a></li>
- </ul></li>
- <li><a name="toc-Opening-Binary-Files"
href="#perlopentut-Opening-Binary-Files">49.4 Opening Binary Files</a></li>
- <li><a name="toc-Opening-Pipes" href="#perlopentut-Opening-Pipes">49.5
Opening Pipes</a></li>
- <li><a name="toc-Low_002dlevel-File-Opens-via-sysopen"
href="#perlopentut-Low_002dlevel-File-Opens-via-sysopen">49.6 Low-level File
Opens via sysopen</a></li>
- <li><a name="toc-SEE-ALSO-24" href="#perlopentut-SEE-ALSO">49.7 SEE
ALSO</a></li>
- <li><a name="toc-AUTHOR-and-COPYRIGHT"
href="#perlopentut-AUTHOR-and-COPYRIGHT">49.8 AUTHOR and COPYRIGHT</a></li>
- </ul></li>
- <li><a name="toc-perlpacktut-1" href="#perlpacktut">50 perlpacktut</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-49" href="#perlpacktut-NAME">50.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-48" href="#perlpacktut-DESCRIPTION">50.2
DESCRIPTION</a></li>
- <li><a name="toc-The-Basic-Principle"
href="#perlpacktut-The-Basic-Principle">50.3 The Basic Principle</a></li>
- <li><a name="toc-Packing-Text" href="#perlpacktut-Packing-Text">50.4
Packing Text</a></li>
- <li><a name="toc-Packing-Numbers" href="#perlpacktut-Packing-Numbers">50.5
Packing Numbers</a>
- <ul class="no-bullet">
- <li><a name="toc-Integers" href="#perlpacktut-Integers">50.5.1
Integers</a></li>
- <li><a name="toc-Unpacking-a-Stack-Frame"
href="#perlpacktut-Unpacking-a-Stack-Frame">50.5.2 Unpacking a Stack
Frame</a></li>
- <li><a name="toc-How-to-Eat-an-Egg-on-a-Net"
href="#perlpacktut-How-to-Eat-an-Egg-on-a-Net">50.5.3 How to Eat an Egg on a
Net</a></li>
- <li><a name="toc-Byte_002dorder-modifiers"
href="#perlpacktut-Byte_002dorder-modifiers">50.5.4 Byte-order
modifiers</a></li>
- <li><a name="toc-Floating-point-Numbers"
href="#perlpacktut-Floating-point-Numbers">50.5.5 Floating point
Numbers</a></li>
- </ul></li>
- <li><a name="toc-Exotic-Templates"
href="#perlpacktut-Exotic-Templates">50.6 Exotic Templates</a>
- <ul class="no-bullet">
- <li><a name="toc-Bit-Strings" href="#perlpacktut-Bit-Strings">50.6.1 Bit
Strings</a></li>
- <li><a name="toc-Uuencoding" href="#perlpacktut-Uuencoding">50.6.2
Uuencoding</a></li>
- <li><a name="toc-Doing-Sums" href="#perlpacktut-Doing-Sums">50.6.3 Doing
Sums</a></li>
- <li><a name="toc-Unicode" href="#perlpacktut-Unicode">50.6.4
Unicode</a></li>
- <li><a name="toc-Another-Portable-Binary-Encoding"
href="#perlpacktut-Another-Portable-Binary-Encoding">50.6.5 Another Portable
Binary Encoding</a></li>
- </ul></li>
- <li><a name="toc-Template-Grouping"
href="#perlpacktut-Template-Grouping">50.7 Template Grouping</a></li>
- <li><a name="toc-Lengths-and-Widths"
href="#perlpacktut-Lengths-and-Widths">50.8 Lengths and Widths</a>
- <ul class="no-bullet">
- <li><a name="toc-String-Lengths"
href="#perlpacktut-String-Lengths">50.8.1 String Lengths</a></li>
- <li><a name="toc-Dynamic-Templates"
href="#perlpacktut-Dynamic-Templates">50.8.2 Dynamic Templates</a></li>
- <li><a name="toc-Counting-Repetitions"
href="#perlpacktut-Counting-Repetitions">50.8.3 Counting Repetitions</a></li>
- <li><a name="toc-Intel-HEX" href="#perlpacktut-Intel-HEX">50.8.4 Intel
HEX</a></li>
- </ul></li>
- <li><a name="toc-Packing-and-Unpacking-C-Structures"
href="#perlpacktut-Packing-and-Unpacking-C-Structures">50.9 Packing and
Unpacking C Structures</a>
- <ul class="no-bullet">
- <li><a name="toc-The-Alignment-Pit"
href="#perlpacktut-The-Alignment-Pit">50.9.1 The Alignment Pit</a></li>
- <li><a name="toc-Dealing-with-Endian_002dness"
href="#perlpacktut-Dealing-with-Endian_002dness">50.9.2 Dealing with
Endian-ness</a></li>
- <li><a name="toc-Alignment_002c-Take-2"
href="#perlpacktut-Alignment_002c-Take-2">50.9.3 Alignment, Take 2</a></li>
- <li><a name="toc-Alignment_002c-Take-3"
href="#perlpacktut-Alignment_002c-Take-3">50.9.4 Alignment, Take 3</a></li>
- <li><a name="toc-Pointers-for-How-to-Use-Them"
href="#perlpacktut-Pointers-for-How-to-Use-Them">50.9.5 Pointers for How to Use
Them</a></li>
- </ul></li>
- <li><a name="toc-Pack-Recipes" href="#perlpacktut-Pack-Recipes">50.10 Pack
Recipes</a></li>
- <li><a name="toc-Funnies-Section"
href="#perlpacktut-Funnies-Section">50.11 Funnies Section</a></li>
- <li><a name="toc-Authors" href="#perlpacktut-Authors">50.12
Authors</a></li>
- </ul></li>
- <li><a name="toc-perlperf-1" href="#perlperf">51 perlperf</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-50" href="#perlperf-NAME">51.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-49" href="#perlperf-DESCRIPTION">51.2
DESCRIPTION</a></li>
- <li><a name="toc-OVERVIEW" href="#perlperf-OVERVIEW">51.3 OVERVIEW</a>
- <ul class="no-bullet">
- <li><a name="toc-ONE-STEP-SIDEWAYS"
href="#perlperf-ONE-STEP-SIDEWAYS">51.3.1 ONE STEP SIDEWAYS</a></li>
- <li><a name="toc-ONE-STEP-FORWARD"
href="#perlperf-ONE-STEP-FORWARD">51.3.2 ONE STEP FORWARD</a></li>
- <li><a name="toc-ANOTHER-STEP-SIDEWAYS"
href="#perlperf-ANOTHER-STEP-SIDEWAYS">51.3.3 ANOTHER STEP SIDEWAYS</a></li>
- </ul></li>
- <li><a name="toc-GENERAL-GUIDELINES"
href="#perlperf-GENERAL-GUIDELINES">51.4 GENERAL GUIDELINES</a></li>
- <li><a name="toc-BENCHMARKS" href="#perlperf-BENCHMARKS">51.5
BENCHMARKS</a>
- <ul class="no-bullet">
- <li><a name="toc-Assigning-and-Dereferencing-Variables_002e"
href="#perlperf-Assigning-and-Dereferencing-Variables_002e">51.5.1 Assigning
and Dereferencing Variables.</a></li>
- <li><a name="toc-Search-and-replace-or-tr"
href="#perlperf-Search-and-replace-or-tr">51.5.2 Search and replace or
tr</a></li>
- </ul></li>
- <li><a name="toc-PROFILING-TOOLS" href="#perlperf-PROFILING-TOOLS">51.6
PROFILING TOOLS</a>
- <ul class="no-bullet">
- <li><a name="toc-Devel_003a_003aDProf"
href="#perlperf-Devel_003a_003aDProf">51.6.1 Devel::DProf</a></li>
- <li><a name="toc-Devel_003a_003aProfiler"
href="#perlperf-Devel_003a_003aProfiler">51.6.2 Devel::Profiler</a></li>
- <li><a name="toc-Devel_003a_003aSmallProf"
href="#perlperf-Devel_003a_003aSmallProf">51.6.3 Devel::SmallProf</a></li>
- <li><a name="toc-Devel_003a_003aFastProf"
href="#perlperf-Devel_003a_003aFastProf">51.6.4 Devel::FastProf</a></li>
- <li><a name="toc-Devel_003a_003aNYTProf"
href="#perlperf-Devel_003a_003aNYTProf">51.6.5 Devel::NYTProf</a></li>
- </ul></li>
- <li><a name="toc-SORTING-1" href="#perlperf-SORTING">51.7 SORTING</a></li>
- <li><a name="toc-LOGGING" href="#perlperf-LOGGING">51.8 LOGGING</a>
- <ul class="no-bullet">
- <li><a name="toc-Logging-if-DEBUG-_0028constant_0029"
href="#perlperf-Logging-if-DEBUG-_0028constant_0029">51.8.1 Logging if DEBUG
(constant)</a></li>
- </ul></li>
- <li><a name="toc-POSTSCRIPT" href="#perlperf-POSTSCRIPT">51.9
POSTSCRIPT</a></li>
- <li><a name="toc-SEE-ALSO-25" href="#perlperf-SEE-ALSO">51.10 SEE ALSO</a>
- <ul class="no-bullet">
- <li><a name="toc-PERLDOCS" href="#perlperf-PERLDOCS">51.10.1
PERLDOCS</a></li>
- <li><a name="toc-MAN-PAGES" href="#perlperf-MAN-PAGES">51.10.2 MAN
PAGES</a></li>
- <li><a name="toc-MODULES" href="#perlperf-MODULES">51.10.3
MODULES</a></li>
- <li><a name="toc-URLS" href="#perlperf-URLS">51.10.4 URLS</a></li>
- </ul></li>
- <li><a name="toc-AUTHOR-21" href="#perlperf-AUTHOR">51.11 AUTHOR</a></li>
- </ul></li>
- <li><a name="toc-perlpod-1" href="#perlpod">52 perlpod</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-51" href="#perlpod-NAME">52.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-50" href="#perlpod-DESCRIPTION">52.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Ordinary-Paragraph"
href="#perlpod-Ordinary-Paragraph">52.2.1 Ordinary Paragraph</a></li>
- <li><a name="toc-Verbatim-Paragraph"
href="#perlpod-Verbatim-Paragraph">52.2.2 Verbatim Paragraph</a></li>
- <li><a name="toc-Command-Paragraph"
href="#perlpod-Command-Paragraph">52.2.3 Command Paragraph</a></li>
- <li><a name="toc-Formatting-Codes"
href="#perlpod-Formatting-Codes">52.2.4 Formatting Codes</a></li>
- <li><a name="toc-The-Intent" href="#perlpod-The-Intent">52.2.5 The
Intent</a></li>
- <li><a name="toc-Embedding-Pods-in-Perl-Modules"
href="#perlpod-Embedding-Pods-in-Perl-Modules">52.2.6 Embedding Pods in Perl
Modules</a></li>
- <li><a name="toc-Hints-for-Writing-Pod"
href="#perlpod-Hints-for-Writing-Pod">52.2.7 Hints for Writing Pod</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-26" href="#perlpod-SEE-ALSO">52.3 SEE
ALSO</a></li>
- <li><a name="toc-AUTHOR-22" href="#perlpod-AUTHOR">52.4 AUTHOR</a></li>
- </ul></li>
- <li><a name="toc-perlpodspec-1" href="#perlpodspec">53 perlpodspec</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-52" href="#perlpodspec-NAME">53.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-51" href="#perlpodspec-DESCRIPTION">53.2
DESCRIPTION</a></li>
- <li><a name="toc-Pod-Definitions" href="#perlpodspec-Pod-Definitions">53.3
Pod Definitions</a></li>
- <li><a name="toc-Pod-Commands" href="#perlpodspec-Pod-Commands">53.4 Pod
Commands</a></li>
- <li><a name="toc-Pod-Formatting-Codes"
href="#perlpodspec-Pod-Formatting-Codes">53.5 Pod Formatting Codes</a></li>
- <li><a name="toc-Notes-on-Implementing-Pod-Processors"
href="#perlpodspec-Notes-on-Implementing-Pod-Processors">53.6 Notes on
Implementing Pod Processors</a></li>
- <li><a name="toc-About-L_003c_002e_002e_002e_003e-Codes"
href="#perlpodspec-About-L_003c_002e_002e_002e_003e-Codes">53.7 About
L<...> Codes</a></li>
- <li><a name="toc-About-_003dover_002e_002e_002e_003dback-Regions"
href="#perlpodspec-About-_003dover_002e_002e_002e_003dback-Regions">53.8 About
=over...=back Regions</a></li>
- <li><a
name="toc-About-Data-Paragraphs-and-_0022_003dbegin_002f_003dend_0022-Regions"
href="#perlpodspec-About-Data-Paragraphs-and-_0022_003dbegin_002f_003dend_0022-Regions">53.9
About Data Paragraphs and "=begin/=end" Regions</a></li>
- <li><a name="toc-SEE-ALSO-27" href="#perlpodspec-SEE-ALSO">53.10 SEE
ALSO</a></li>
- <li><a name="toc-AUTHOR-23" href="#perlpodspec-AUTHOR">53.11
AUTHOR</a></li>
- </ul></li>
- <li><a name="toc-perlpodstyle-1" href="#perlpodstyle">54 perlpodstyle</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-53" href="#perlpodstyle-NAME">54.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-52" href="#perlpodstyle-DESCRIPTION">54.2
DESCRIPTION</a></li>
- <li><a name="toc-SEE-ALSO-28" href="#perlpodstyle-SEE-ALSO-1">54.3 SEE
ALSO</a></li>
- <li><a name="toc-AUTHOR-24" href="#perlpodstyle-AUTHOR-1">54.4
AUTHOR</a></li>
- <li><a name="toc-COPYRIGHT-AND-LICENSE"
href="#perlpodstyle-COPYRIGHT-AND-LICENSE-1">54.5 COPYRIGHT AND LICENSE</a></li>
- </ul></li>
- <li><a name="toc-perlpolicy-1" href="#perlpolicy">55 perlpolicy</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-54" href="#perlpolicy-NAME">55.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-53" href="#perlpolicy-DESCRIPTION">55.2
DESCRIPTION</a></li>
- <li><a name="toc-GOVERNANCE" href="#perlpolicy-GOVERNANCE">55.3
GOVERNANCE</a>
- <ul class="no-bullet">
- <li><a name="toc-Perl-5-Porters"
href="#perlpolicy-Perl-5-Porters">55.3.1 Perl 5 Porters</a></li>
- </ul></li>
- <li><a name="toc-MAINTENANCE-AND-SUPPORT"
href="#perlpolicy-MAINTENANCE-AND-SUPPORT">55.4 MAINTENANCE AND SUPPORT</a></li>
- <li><a name="toc-BACKWARD-COMPATIBILITY-AND-DEPRECATION"
href="#perlpolicy-BACKWARD-COMPATIBILITY-AND-DEPRECATION">55.5 BACKWARD
COMPATIBILITY AND DEPRECATION</a>
- <ul class="no-bullet">
- <li><a name="toc-Terminology" href="#perlpolicy-Terminology">55.5.1
Terminology</a></li>
- </ul></li>
- <li><a name="toc-MAINTENANCE-BRANCHES"
href="#perlpolicy-MAINTENANCE-BRANCHES">55.6 MAINTENANCE BRANCHES</a>
- <ul class="no-bullet">
- <li><a name="toc-Getting-changes-into-a-maint-branch"
href="#perlpolicy-Getting-changes-into-a-maint-branch">55.6.1 Getting changes
into a maint branch</a></li>
- </ul></li>
- <li><a name="toc-CONTRIBUTED-MODULES"
href="#perlpolicy-CONTRIBUTED-MODULES">55.7 CONTRIBUTED MODULES</a>
- <ul class="no-bullet">
- <li><a name="toc-A-Social-Contract-about-Artistic-Control"
href="#perlpolicy-A-Social-Contract-about-Artistic-Control">55.7.1 A Social
Contract about Artistic Control</a></li>
- </ul></li>
- <li><a name="toc-DOCUMENTATION" href="#perlpolicy-DOCUMENTATION">55.8
DOCUMENTATION</a></li>
- <li><a name="toc-STANDARDS-OF-CONDUCT"
href="#perlpolicy-STANDARDS-OF-CONDUCT">55.9 STANDARDS OF CONDUCT</a></li>
- <li><a name="toc-CREDITS" href="#perlpolicy-CREDITS">55.10 CREDITS</a></li>
- </ul></li>
- <li><a name="toc-perlport-1" href="#perlport">56 perlport</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-55" href="#perlport-NAME">56.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-54" href="#perlport-DESCRIPTION">56.2
DESCRIPTION</a></li>
- <li><a name="toc-ISSUES" href="#perlport-ISSUES">56.3 ISSUES</a>
- <ul class="no-bullet">
- <li><a name="toc-Newlines" href="#perlport-Newlines">56.3.1
Newlines</a></li>
- <li><a name="toc-Numbers-endianness-and-Width"
href="#perlport-Numbers-endianness-and-Width">56.3.2 Numbers endianness and
Width</a></li>
- <li><a name="toc-Files-and-Filesystems"
href="#perlport-Files-and-Filesystems">56.3.3 Files and Filesystems</a></li>
- <li><a name="toc-System-Interaction"
href="#perlport-System-Interaction">56.3.4 System Interaction</a></li>
- <li><a name="toc-Command-names-versus-file-pathnames"
href="#perlport-Command-names-versus-file-pathnames">56.3.5 Command names
versus file pathnames</a></li>
- <li><a name="toc-Networking" href="#perlport-Networking">56.3.6
Networking</a></li>
- <li><a name="toc-Interprocess-Communication-_0028IPC_0029"
href="#perlport-Interprocess-Communication-_0028IPC_0029">56.3.7 Interprocess
Communication (IPC)</a></li>
- <li><a name="toc-External-Subroutines-_0028XS_0029"
href="#perlport-External-Subroutines-_0028XS_0029">56.3.8 External Subroutines
(XS)</a></li>
- <li><a name="toc-Standard-Modules"
href="#perlport-Standard-Modules">56.3.9 Standard Modules</a></li>
- <li><a name="toc-Time-and-Date" href="#perlport-Time-and-Date">56.3.10
Time and Date</a></li>
- <li><a name="toc-Character-sets-and-character-encoding"
href="#perlport-Character-sets-and-character-encoding">56.3.11 Character sets
and character encoding</a></li>
- <li><a name="toc-Internationalisation"
href="#perlport-Internationalisation">56.3.12 Internationalisation</a></li>
- <li><a name="toc-System-Resources"
href="#perlport-System-Resources">56.3.13 System Resources</a></li>
- <li><a name="toc-Security" href="#perlport-Security">56.3.14
Security</a></li>
- <li><a name="toc-Style-1" href="#perlport-Style">56.3.15 Style</a></li>
- </ul></li>
- <li><a name="toc-CPAN-Testers" href="#perlport-CPAN-Testers">56.4 CPAN
Testers</a></li>
- <li><a name="toc-PLATFORMS" href="#perlport-PLATFORMS">56.5 PLATFORMS</a>
- <ul class="no-bullet">
- <li><a name="toc-Unix" href="#perlport-Unix">56.5.1 Unix</a></li>
- <li><a name="toc-DOS-and-Derivatives"
href="#perlport-DOS-and-Derivatives">56.5.2 DOS and Derivatives</a></li>
- <li><a name="toc-VMS" href="#perlport-VMS">56.5.3 VMS</a></li>
- <li><a name="toc-VOS" href="#perlport-VOS">56.5.4 VOS</a></li>
- <li><a name="toc-EBCDIC-Platforms"
href="#perlport-EBCDIC-Platforms">56.5.5 EBCDIC Platforms</a></li>
- <li><a name="toc-Acorn-RISC-OS" href="#perlport-Acorn-RISC-OS">56.5.6
Acorn RISC OS</a></li>
- <li><a name="toc-Other-perls" href="#perlport-Other-perls">56.5.7 Other
perls</a></li>
- </ul></li>
- <li><a name="toc-FUNCTION-IMPLEMENTATIONS"
href="#perlport-FUNCTION-IMPLEMENTATIONS">56.6 FUNCTION IMPLEMENTATIONS</a>
- <ul class="no-bullet">
- <li><a name="toc-Alphabetical-Listing-of-Perl-Functions-1"
href="#perlport-Alphabetical-Listing-of-Perl-Functions">56.6.1 Alphabetical
Listing of Perl Functions</a></li>
- </ul></li>
- <li><a name="toc-Supported-Platforms"
href="#perlport-Supported-Platforms">56.7 Supported Platforms</a></li>
- <li><a name="toc-EOL-Platforms" href="#perlport-EOL-Platforms">56.8 EOL
Platforms</a>
- <ul class="no-bullet">
- <li><a name="toc-_0028Perl-5_002e20_0029"
href="#perlport-_0028Perl-5_002e20_0029">56.8.1 (Perl 5.20)</a></li>
- <li><a name="toc-_0028Perl-5_002e14_0029"
href="#perlport-_0028Perl-5_002e14_0029">56.8.2 (Perl 5.14)</a></li>
- <li><a name="toc-_0028Perl-5_002e12_0029"
href="#perlport-_0028Perl-5_002e12_0029">56.8.3 (Perl 5.12)</a></li>
- </ul></li>
- <li><a name="toc-Supported-Platforms-_0028Perl-5_002e8_0029"
href="#perlport-Supported-Platforms-_0028Perl-5_002e8_0029">56.9 Supported
Platforms (Perl 5.8)</a></li>
- <li><a name="toc-SEE-ALSO-29" href="#perlport-SEE-ALSO">56.10 SEE
ALSO</a></li>
- <li><a name="toc-AUTHORS-_002f-CONTRIBUTORS"
href="#perlport-AUTHORS-_002f-CONTRIBUTORS">56.11 AUTHORS /
CONTRIBUTORS</a></li>
- </ul></li>
- <li><a name="toc-perlpragma-1" href="#perlpragma">57 perlpragma</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-56" href="#perlpragma-NAME">57.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-55" href="#perlpragma-DESCRIPTION">57.2
DESCRIPTION</a></li>
- <li><a name="toc-A-basic-example" href="#perlpragma-A-basic-example">57.3
A basic example</a></li>
- <li><a name="toc-Key-naming" href="#perlpragma-Key-naming">57.4 Key
naming</a></li>
- <li><a name="toc-Implementation-details"
href="#perlpragma-Implementation-details">57.5 Implementation details</a></li>
- </ul></li>
- <li><a name="toc-perlre-1" href="#perlre">58 perlre</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-57" href="#perlre-NAME">58.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-56" href="#perlre-DESCRIPTION">58.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Modifiers" href="#perlre-Modifiers">58.2.1 Modifiers</a>
- <ul class="no-bullet">
- <li><a name="toc-Overview-1" href="#perlre-Overview">58.2.1.1
Overview</a></li>
- <li><a name="toc-Details-on-some-modifiers"
href="#perlre-Details-on-some-modifiers">58.2.1.2 Details on some
modifiers</a></li>
- <li><a name="toc-_002fx" href="#perlre-_002fx">58.2.1.3 /x</a></li>
- <li><a name="toc-Character-set-modifiers"
href="#perlre-Character-set-modifiers">58.2.1.4 Character set modifiers</a></li>
- <li><a name="toc-_002fl" href="#perlre-_002fl">58.2.1.5 /l</a></li>
- <li><a name="toc-_002fu" href="#perlre-_002fu">58.2.1.6 /u</a></li>
- <li><a name="toc-_002fd" href="#perlre-_002fd">58.2.1.7 /d</a></li>
- <li><a name="toc-_002fa-_0028and-_002faa_0029"
href="#perlre-_002fa-_0028and-_002faa_0029">58.2.1.8 /a (and /aa)</a></li>
- <li><a name="toc-Which-character-set-modifier-is-in-effect_003f"
href="#perlre-Which-character-set-modifier-is-in-effect_003f">58.2.1.9 Which
character set modifier is in effect?</a></li>
- <li><a
name="toc-Character-set-modifier-behavior-prior-to-Perl-5_002e14"
href="#perlre-Character-set-modifier-behavior-prior-to-Perl-5_002e14">58.2.1.10
Character set modifier behavior prior to Perl 5.14</a></li>
- </ul></li>
- <li><a name="toc-Regular-Expressions"
href="#perlre-Regular-Expressions">58.2.2 Regular Expressions</a>
- <ul class="no-bullet">
- <li><a name="toc-Metacharacters"
href="#perlre-Metacharacters">58.2.2.1 Metacharacters</a></li>
- <li><a name="toc-Quantifiers" href="#perlre-Quantifiers">58.2.2.2
Quantifiers</a></li>
- <li><a name="toc-Escape-sequences"
href="#perlre-Escape-sequences">58.2.2.3 Escape sequences</a></li>
- <li><a name="toc-Character-Classes-and-other-Special-Escapes"
href="#perlre-Character-Classes-and-other-Special-Escapes">58.2.2.4 Character
Classes and other Special Escapes</a></li>
- <li><a name="toc-Assertions" href="#perlre-Assertions">58.2.2.5
Assertions</a></li>
- <li><a name="toc-Capture-groups"
href="#perlre-Capture-groups">58.2.2.6 Capture groups</a></li>
- </ul></li>
- <li><a name="toc-Quoting-metacharacters"
href="#perlre-Quoting-metacharacters">58.2.3 Quoting metacharacters</a></li>
- <li><a name="toc-Extended-Patterns"
href="#perlre-Extended-Patterns">58.2.4 Extended Patterns</a></li>
- <li><a name="toc-Special-Backtracking-Control-Verbs"
href="#perlre-Special-Backtracking-Control-Verbs">58.2.5 Special Backtracking
Control Verbs</a></li>
- <li><a name="toc-Backtracking" href="#perlre-Backtracking">58.2.6
Backtracking</a></li>
- <li><a name="toc-Version-8-Regular-Expressions"
href="#perlre-Version-8-Regular-Expressions">58.2.7 Version 8 Regular
Expressions</a></li>
- <li><a name="toc-Warning-on-_005c1-Instead-of-_00241"
href="#perlre-Warning-on-_005c1-Instead-of-_00241">58.2.8 Warning on \1 Instead
of $1</a></li>
- <li><a name="toc-Repeated-Patterns-Matching-a-Zero_002dlength-Substring"
href="#perlre-Repeated-Patterns-Matching-a-Zero_002dlength-Substring">58.2.9
Repeated Patterns Matching a Zero-length Substring</a></li>
- <li><a name="toc-Combining-RE-Pieces"
href="#perlre-Combining-RE-Pieces">58.2.10 Combining RE Pieces</a></li>
- <li><a name="toc-Creating-Custom-RE-Engines"
href="#perlre-Creating-Custom-RE-Engines">58.2.11 Creating Custom RE
Engines</a></li>
- <li><a name="toc-Embedded-Code-Execution-Frequency"
href="#perlre-Embedded-Code-Execution-Frequency">58.2.12 Embedded Code
Execution Frequency</a></li>
- <li><a name="toc-PCRE_002fPython-Support"
href="#perlre-PCRE_002fPython-Support">58.2.13 PCRE/Python Support</a></li>
- </ul></li>
- <li><a name="toc-BUGS-6" href="#perlre-BUGS">58.3 BUGS</a></li>
- <li><a name="toc-SEE-ALSO-30" href="#perlre-SEE-ALSO">58.4 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlreapi-1" href="#perlreapi">59 perlreapi</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-58" href="#perlreapi-NAME">59.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-57" href="#perlreapi-DESCRIPTION">59.2
DESCRIPTION</a></li>
- <li><a name="toc-Callbacks-1" href="#perlreapi-Callbacks">59.3
Callbacks</a>
- <ul class="no-bullet">
- <li><a name="toc-comp" href="#perlreapi-comp">59.3.1 comp</a></li>
- <li><a name="toc-exec" href="#perlreapi-exec">59.3.2 exec</a></li>
- <li><a name="toc-intuit" href="#perlreapi-intuit">59.3.3 intuit</a></li>
- <li><a name="toc-checkstr" href="#perlreapi-checkstr">59.3.4
checkstr</a></li>
- <li><a name="toc-free" href="#perlreapi-free">59.3.5 free</a></li>
- <li><a name="toc-Numbered-capture-callbacks"
href="#perlreapi-Numbered-capture-callbacks">59.3.6 Numbered capture
callbacks</a>
- <ul class="no-bullet">
- <li><a name="toc-numbered_005fbuff_005fFETCH"
href="#perlreapi-numbered_005fbuff_005fFETCH">59.3.6.1
numbered_buff_FETCH</a></li>
- <li><a name="toc-numbered_005fbuff_005fSTORE"
href="#perlreapi-numbered_005fbuff_005fSTORE">59.3.6.2
numbered_buff_STORE</a></li>
- <li><a name="toc-numbered_005fbuff_005fLENGTH"
href="#perlreapi-numbered_005fbuff_005fLENGTH">59.3.6.3
numbered_buff_LENGTH</a></li>
- </ul></li>
- <li><a name="toc-Named-capture-callbacks"
href="#perlreapi-Named-capture-callbacks">59.3.7 Named capture callbacks</a>
- <ul class="no-bullet">
- <li><a name="toc-named_005fbuff"
href="#perlreapi-named_005fbuff">59.3.7.1 named_buff</a></li>
- <li><a name="toc-named_005fbuff_005fiter"
href="#perlreapi-named_005fbuff_005fiter">59.3.7.2 named_buff_iter</a></li>
- </ul></li>
- <li><a name="toc-qr_005fpackage" href="#perlreapi-qr_005fpackage">59.3.8
qr_package</a></li>
- <li><a name="toc-dupe" href="#perlreapi-dupe">59.3.9 dupe</a></li>
- <li><a name="toc-op_005fcomp" href="#perlreapi-op_005fcomp">59.3.10
op_comp</a></li>
- </ul></li>
- <li><a name="toc-The-REGEXP-structure"
href="#perlreapi-The-REGEXP-structure">59.4 The REGEXP structure</a>
- <ul class="no-bullet">
- <li><a name="toc-engine" href="#perlreapi-engine">59.4.1
<code>engine</code></a></li>
- <li><a name="toc-mother_005fre" href="#perlreapi-mother_005fre">59.4.2
<code>mother_re</code></a></li>
- <li><a name="toc-extflags" href="#perlreapi-extflags">59.4.3
<code>extflags</code></a></li>
- <li><a name="toc-minlen-minlenret"
href="#perlreapi-minlen-minlenret">59.4.4 <code>minlen</code>
<code>minlenret</code></a></li>
- <li><a name="toc-gofs" href="#perlreapi-gofs">59.4.5
<code>gofs</code></a></li>
- <li><a name="toc-substrs" href="#perlreapi-substrs">59.4.6
<code>substrs</code></a></li>
- <li><a name="toc-nparens_002c-lastparen_002c-and-lastcloseparen"
href="#perlreapi-nparens_002c-lastparen_002c-and-lastcloseparen">59.4.7
<code>nparens</code>, <code>lastparen</code>, and
<code>lastcloseparen</code></a></li>
- <li><a name="toc-intflags" href="#perlreapi-intflags">59.4.8
<code>intflags</code></a></li>
- <li><a name="toc-pprivate" href="#perlreapi-pprivate">59.4.9
<code>pprivate</code></a></li>
- <li><a name="toc-swap" href="#perlreapi-swap">59.4.10
<code>swap</code></a></li>
- <li><a name="toc-offs" href="#perlreapi-offs">59.4.11
<code>offs</code></a></li>
- <li><a name="toc-precomp-prelen"
href="#perlreapi-precomp-prelen">59.4.12 <code>precomp</code>
<code>prelen</code></a></li>
- <li><a name="toc-paren_005fnames"
href="#perlreapi-paren_005fnames">59.4.13 <code>paren_names</code></a></li>
- <li><a name="toc-substrs-1" href="#perlreapi-substrs-1">59.4.14
<code>substrs</code></a></li>
- <li><a name="toc-subbeg-sublen-saved_005fcopy-suboffset-subcoffset"
href="#perlreapi-subbeg-sublen-saved_005fcopy-suboffset-subcoffset">59.4.15
<code>subbeg</code> <code>sublen</code> <code>saved_copy</code>
<code>suboffset</code> <code>subcoffset</code></a></li>
- <li><a name="toc-wrapped-wraplen"
href="#perlreapi-wrapped-wraplen">59.4.16 <code>wrapped</code>
<code>wraplen</code></a></li>
- <li><a name="toc-seen_005fevals"
href="#perlreapi-seen_005fevals">59.4.17 <code>seen_evals</code></a></li>
- <li><a name="toc-refcnt" href="#perlreapi-refcnt">59.4.18
<code>refcnt</code></a></li>
- </ul></li>
- <li><a name="toc-HISTORY-3" href="#perlreapi-HISTORY">59.5 HISTORY</a></li>
- <li><a name="toc-AUTHORS-4" href="#perlreapi-AUTHORS">59.6 AUTHORS</a></li>
- <li><a name="toc-LICENSE-1" href="#perlreapi-LICENSE">59.7 LICENSE</a></li>
- </ul></li>
- <li><a name="toc-perlrebackslash-1" href="#perlrebackslash">60
perlrebackslash</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-59" href="#perlrebackslash-NAME">60.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-58" href="#perlrebackslash-DESCRIPTION">60.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-The-backslash"
href="#perlrebackslash-The-backslash">60.2.1 The backslash</a></li>
- <li><a name="toc-All-the-sequences-and-escapes"
href="#perlrebackslash-All-the-sequences-and-escapes">60.2.2 All the sequences
and escapes</a></li>
- <li><a name="toc-Character-Escapes"
href="#perlrebackslash-Character-Escapes">60.2.3 Character Escapes</a>
- <ul class="no-bullet">
- <li><a name="toc-Fixed-characters"
href="#perlrebackslash-Fixed-characters">60.2.3.1 Fixed characters</a></li>
- <li><a name="toc-Example" href="#perlrebackslash-Example">60.2.3.2
Example</a></li>
- <li><a name="toc-Control-characters"
href="#perlrebackslash-Control-characters">60.2.3.3 Control characters</a></li>
- <li><a name="toc-Example-1" href="#perlrebackslash-Example-1">60.2.3.4
Example</a></li>
- <li><a name="toc-Named-or-numbered-characters-and-character-sequences"
href="#perlrebackslash-Named-or-numbered-characters-and-character-sequences">60.2.3.5
Named or numbered characters and character sequences</a></li>
- <li><a name="toc-Example-2" href="#perlrebackslash-Example-2">60.2.3.6
Example</a></li>
- <li><a name="toc-Octal-escapes"
href="#perlrebackslash-Octal-escapes">60.2.3.7 Octal escapes</a></li>
- <li><a name="toc-Examples-_0028assuming-an-ASCII-platform_0029"
href="#perlrebackslash-Examples-_0028assuming-an-ASCII-platform_0029">60.2.3.8
Examples (assuming an ASCII platform)</a></li>
- <li><a
name="toc-Disambiguation-rules-between-old_002dstyle-octal-escapes-and-backreferences"
href="#perlrebackslash-Disambiguation-rules-between-old_002dstyle-octal-escapes-and-backreferences">60.2.3.9
Disambiguation rules between old-style octal escapes and
backreferences</a></li>
- <li><a name="toc-Hexadecimal-escapes"
href="#perlrebackslash-Hexadecimal-escapes">60.2.3.10 Hexadecimal
escapes</a></li>
- <li><a name="toc-Examples-_0028assuming-an-ASCII-platform_0029-1"
href="#perlrebackslash-Examples-_0028assuming-an-ASCII-platform_0029-1">60.2.3.11
Examples (assuming an ASCII platform)</a></li>
- </ul></li>
- <li><a name="toc-Modifiers-1" href="#perlrebackslash-Modifiers">60.2.4
Modifiers</a>
- <ul class="no-bullet">
- <li><a name="toc-Examples-2" href="#perlrebackslash-Examples">60.2.4.1
Examples</a></li>
- </ul></li>
- <li><a name="toc-Character-classes"
href="#perlrebackslash-Character-classes">60.2.5 Character classes</a>
- <ul class="no-bullet">
- <li><a name="toc-Unicode-classes"
href="#perlrebackslash-Unicode-classes">60.2.5.1 Unicode classes</a></li>
- </ul></li>
- <li><a name="toc-Referencing" href="#perlrebackslash-Referencing">60.2.6
Referencing</a>
- <ul class="no-bullet">
- <li><a name="toc-Absolute-referencing"
href="#perlrebackslash-Absolute-referencing">60.2.6.1 Absolute
referencing</a></li>
- <li><a name="toc-Examples-3"
href="#perlrebackslash-Examples-1">60.2.6.2 Examples</a></li>
- <li><a name="toc-Relative-referencing"
href="#perlrebackslash-Relative-referencing">60.2.6.3 Relative
referencing</a></li>
- <li><a name="toc-Examples-4"
href="#perlrebackslash-Examples-2">60.2.6.4 Examples</a></li>
- <li><a name="toc-Named-referencing"
href="#perlrebackslash-Named-referencing">60.2.6.5 Named referencing</a></li>
- <li><a name="toc-Examples-5"
href="#perlrebackslash-Examples-3">60.2.6.6 Examples</a></li>
- </ul></li>
- <li><a name="toc-Assertions-1" href="#perlrebackslash-Assertions">60.2.7
Assertions</a>
- <ul class="no-bullet">
- <li><a name="toc-Examples-6"
href="#perlrebackslash-Examples-4">60.2.7.1 Examples</a></li>
- </ul></li>
- <li><a name="toc-Misc" href="#perlrebackslash-Misc">60.2.8 Misc</a>
- <ul class="no-bullet">
- <li><a name="toc-Examples-7"
href="#perlrebackslash-Examples-5">60.2.8.1 Examples</a></li>
- </ul></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlrecharclass-1" href="#perlrecharclass">61
perlrecharclass</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-60" href="#perlrecharclass-NAME">61.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-59" href="#perlrecharclass-DESCRIPTION">61.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-The-dot" href="#perlrecharclass-The-dot">61.2.1 The
dot</a></li>
- <li><a name="toc-Backslash-sequences"
href="#perlrecharclass-Backslash-sequences">61.2.2 Backslash sequences</a>
- <ul class="no-bullet">
- <li><a name="toc-_005cN" href="#perlrecharclass-_005cN">61.2.2.1
\N</a></li>
- <li><a name="toc-Digits" href="#perlrecharclass-Digits">61.2.2.2
Digits</a></li>
- <li><a name="toc-Word-characters"
href="#perlrecharclass-Word-characters">61.2.2.3 Word characters</a></li>
- <li><a name="toc-Whitespace"
href="#perlrecharclass-Whitespace">61.2.2.4 Whitespace</a></li>
- <li><a name="toc-Unicode-Properties"
href="#perlrecharclass-Unicode-Properties">61.2.2.5 Unicode Properties</a></li>
- <li><a name="toc-Examples-8" href="#perlrecharclass-Examples">61.2.2.6
Examples</a></li>
- </ul></li>
- <li><a name="toc-Bracketed-Character-Classes"
href="#perlrecharclass-Bracketed-Character-Classes">61.2.3 Bracketed Character
Classes</a>
- <ul class="no-bullet">
- <li><a
name="toc-Special-Characters-Inside-a-Bracketed-Character-Class"
href="#perlrecharclass-Special-Characters-Inside-a-Bracketed-Character-Class">61.2.3.1
Special Characters Inside a Bracketed Character Class</a></li>
- <li><a name="toc-Character-Ranges"
href="#perlrecharclass-Character-Ranges">61.2.3.2 Character Ranges</a></li>
- <li><a name="toc-Negation" href="#perlrecharclass-Negation">61.2.3.3
Negation</a></li>
- <li><a name="toc-Backslash-Sequences"
href="#perlrecharclass-Backslash-Sequences">61.2.3.4 Backslash
Sequences</a></li>
- <li><a name="toc-POSIX-Character-Classes"
href="#perlrecharclass-POSIX-Character-Classes">61.2.3.5 POSIX Character
Classes</a></li>
- <li><a name="toc-Negation-of-POSIX-character-classes"
href="#perlrecharclass-Negation-of-POSIX-character-classes">61.2.3.6 Negation
of POSIX character classes</a></li>
- <li><a name="toc-_005b_003d-_003d_005d-and-_005b_002e-_002e_005d"
href="#perlrecharclass-_005b_003d-_003d_005d-and-_005b_002e-_002e_005d">61.2.3.7
[= =] and [. .]</a></li>
- <li><a name="toc-Examples-9"
href="#perlrecharclass-Examples-1">61.2.3.8 Examples</a></li>
- <li><a name="toc-Extended-Bracketed-Character-Classes"
href="#perlrecharclass-Extended-Bracketed-Character-Classes">61.2.3.9 Extended
Bracketed Character Classes</a></li>
- </ul></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlref-1" href="#perlref">62 perlref</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-61" href="#perlref-NAME">62.1 NAME</a></li>
- <li><a name="toc-NOTE" href="#perlref-NOTE">62.2 NOTE</a></li>
- <li><a name="toc-DESCRIPTION-60" href="#perlref-DESCRIPTION">62.3
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Making-References"
href="#perlref-Making-References">62.3.1 Making References</a></li>
- <li><a name="toc-Using-References"
href="#perlref-Using-References">62.3.2 Using References</a></li>
- <li><a name="toc-Circular-References"
href="#perlref-Circular-References">62.3.3 Circular References</a></li>
- <li><a name="toc-Symbolic-references"
href="#perlref-Symbolic-references">62.3.4 Symbolic references</a></li>
- <li><a name="toc-Not_002dso_002dsymbolic-references"
href="#perlref-Not_002dso_002dsymbolic-references">62.3.5 Not-so-symbolic
references</a></li>
- <li><a name="toc-Pseudo_002dhashes_003a-Using-an-array-as-a-hash"
href="#perlref-Pseudo_002dhashes_003a-Using-an-array-as-a-hash">62.3.6
Pseudo-hashes: Using an array as a hash</a></li>
- <li><a name="toc-Function-Templates"
href="#perlref-Function-Templates">62.3.7 Function Templates</a></li>
- </ul></li>
- <li><a name="toc-WARNING" href="#perlref-WARNING">62.4 WARNING</a></li>
- <li><a name="toc-Postfix-Dereference-Syntax"
href="#perlref-Postfix-Dereference-Syntax">62.5 Postfix Dereference Syntax</a>
- <ul class="no-bullet">
- <li><a name="toc-Postfix-Reference-Slicing"
href="#perlref-Postfix-Reference-Slicing">62.5.1 Postfix Reference
Slicing</a></li>
- </ul></li>
- <li><a name="toc-Assigning-to-References"
href="#perlref-Assigning-to-References">62.6 Assigning to References</a></li>
- <li><a name="toc-SEE-ALSO-31" href="#perlref-SEE-ALSO">62.7 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlreftut-1" href="#perlreftut">63 perlreftut</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-62" href="#perlreftut-NAME">63.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-61" href="#perlreftut-DESCRIPTION">63.2
DESCRIPTION</a></li>
- <li><a name="toc-Who-Needs-Complicated-Data-Structures_003f"
href="#perlreftut-Who-Needs-Complicated-Data-Structures_003f">63.3 Who Needs
Complicated Data Structures?</a></li>
- <li><a name="toc-The-Solution" href="#perlreftut-The-Solution">63.4 The
Solution</a></li>
- <li><a name="toc-Syntax" href="#perlreftut-Syntax">63.5 Syntax</a>
- <ul class="no-bullet">
- <li><a name="toc-Making-References-1"
href="#perlreftut-Making-References">63.5.1 Making References</a>
- <ul class="no-bullet">
- <li><a name="toc-Make-Rule-1" href="#perlreftut-Make-Rule-1">63.5.1.1
<strong>Make Rule 1</strong></a></li>
- </ul></li>
- <li><a name="toc-Using-References-1"
href="#perlreftut-Using-References">63.5.2 Using References</a>
- <ul class="no-bullet">
- <li><a name="toc-Use-Rule-1" href="#perlreftut-Use-Rule-1">63.5.2.1
<strong>Use Rule 1</strong></a></li>
- <li><a name="toc-Use-Rule-2" href="#perlreftut-Use-Rule-2">63.5.2.2
<strong>Use Rule 2</strong></a></li>
- </ul></li>
- <li><a name="toc-An-Example" href="#perlreftut-An-Example">63.5.3 An
Example</a></li>
- <li><a name="toc-Arrow-Rule" href="#perlreftut-Arrow-Rule">63.5.4 Arrow
Rule</a></li>
- </ul></li>
- <li><a name="toc-Solution" href="#perlreftut-Solution">63.6
Solution</a></li>
- <li><a name="toc-The-Rest" href="#perlreftut-The-Rest">63.7 The
Rest</a></li>
- <li><a name="toc-Summary" href="#perlreftut-Summary">63.8 Summary</a></li>
- <li><a name="toc-Credits" href="#perlreftut-Credits">63.9 Credits</a>
- <ul class="no-bullet">
- <li><a name="toc-Distribution-Conditions"
href="#perlreftut-Distribution-Conditions">63.9.1 Distribution
Conditions</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlreguts-1" href="#perlreguts">64 perlreguts</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-63" href="#perlreguts-NAME">64.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-62" href="#perlreguts-DESCRIPTION">64.2
DESCRIPTION</a></li>
- <li><a name="toc-OVERVIEW-1" href="#perlreguts-OVERVIEW">64.3 OVERVIEW</a>
- <ul class="no-bullet">
- <li><a name="toc-A-quick-note-on-terms"
href="#perlreguts-A-quick-note-on-terms">64.3.1 A quick note on terms</a></li>
- <li><a name="toc-What-is-a-regular-expression-engine_003f"
href="#perlreguts-What-is-a-regular-expression-engine_003f">64.3.2 What is a
regular expression engine?</a></li>
- <li><a name="toc-Structure-of-a-Regexp-Program"
href="#perlreguts-Structure-of-a-Regexp-Program">64.3.3 Structure of a Regexp
Program</a>
- <ul class="no-bullet">
- <li><a name="toc-High-Level" href="#perlreguts-High-Level">64.3.3.1
High Level</a></li>
- <li><a name="toc-Regops" href="#perlreguts-Regops">64.3.3.2
Regops</a></li>
- <li><a name="toc-What-regop-is-next_003f"
href="#perlreguts-What-regop-is-next_003f">64.3.3.3 What regop is next?</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-Process-Overview"
href="#perlreguts-Process-Overview">64.4 Process Overview</a>
- <ul class="no-bullet">
- <li><a name="toc-Compilation" href="#perlreguts-Compilation">64.4.1
Compilation</a>
- <ul class="no-bullet">
- <li><a name="toc-Parsing-for-size"
href="#perlreguts-Parsing-for-size">64.4.1.1 Parsing for size</a></li>
- <li><a name="toc-Parsing-for-construction"
href="#perlreguts-Parsing-for-construction">64.4.1.2 Parsing for
construction</a></li>
- <li><a name="toc-Parse-Call-Graph-and-a-Grammar"
href="#perlreguts-Parse-Call-Graph-and-a-Grammar">64.4.1.3 Parse Call Graph and
a Grammar</a></li>
- <li><a name="toc-Parsing-complications"
href="#perlreguts-Parsing-complications">64.4.1.4 Parsing complications</a></li>
- <li><a name="toc-Debug-Output"
href="#perlreguts-Debug-Output">64.4.1.5 Debug Output</a></li>
- <li><a name="toc-Peep_002dhole-Optimisation-and-Analysis"
href="#perlreguts-Peep_002dhole-Optimisation-and-Analysis">64.4.1.6 Peep-hole
Optimisation and Analysis</a></li>
- </ul></li>
- <li><a name="toc-Execution" href="#perlreguts-Execution">64.4.2
Execution</a>
- <ul class="no-bullet">
- <li><a name="toc-Start-position-and-no_002dmatch-optimisations"
href="#perlreguts-Start-position-and-no_002dmatch-optimisations">64.4.2.1 Start
position and no-match optimisations</a></li>
- <li><a name="toc-Program-execution"
href="#perlreguts-Program-execution">64.4.2.2 Program execution</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-MISCELLANEOUS" href="#perlreguts-MISCELLANEOUS">64.5
MISCELLANEOUS</a>
- <ul class="no-bullet">
- <li><a name="toc-Unicode-and-Localisation-Support"
href="#perlreguts-Unicode-and-Localisation-Support">64.5.1 Unicode and
Localisation Support</a></li>
- <li><a name="toc-Base-Structures"
href="#perlreguts-Base-Structures">64.5.2 Base Structures</a>
- <ul class="no-bullet">
- <li><a name="toc-Perl_0027s-pprivate-structure"
href="#perlreguts-Perl_0027s-pprivate-structure">64.5.2.1 Perl’s
<code>pprivate</code> structure</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-32" href="#perlreguts-SEE-ALSO">64.6 SEE
ALSO</a></li>
- <li><a name="toc-AUTHOR-25" href="#perlreguts-AUTHOR">64.7 AUTHOR</a></li>
- <li><a name="toc-LICENCE" href="#perlreguts-LICENCE">64.8 LICENCE</a></li>
- <li><a name="toc-REFERENCES-3" href="#perlreguts-REFERENCES">64.9
REFERENCES</a></li>
- </ul></li>
- <li><a name="toc-perlrepository-1" href="#perlrepository">65
perlrepository</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-64" href="#perlrepository-NAME">65.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-63" href="#perlrepository-DESCRIPTION">65.2
DESCRIPTION</a></li>
- </ul></li>
- <li><a name="toc-perlrequick-1" href="#perlrequick">66 perlrequick</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-65" href="#perlrequick-NAME">66.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-64" href="#perlrequick-DESCRIPTION">66.2
DESCRIPTION</a></li>
- <li><a name="toc-The-Guide" href="#perlrequick-The-Guide">66.3 The
Guide</a>
- <ul class="no-bullet">
- <li><a name="toc-Simple-word-matching"
href="#perlrequick-Simple-word-matching">66.3.1 Simple word matching</a></li>
- <li><a name="toc-Using-character-classes"
href="#perlrequick-Using-character-classes">66.3.2 Using character
classes</a></li>
- <li><a name="toc-Matching-this-or-that"
href="#perlrequick-Matching-this-or-that">66.3.3 Matching this or that</a></li>
- <li><a name="toc-Grouping-things-and-hierarchical-matching"
href="#perlrequick-Grouping-things-and-hierarchical-matching">66.3.4 Grouping
things and hierarchical matching</a></li>
- <li><a name="toc-Extracting-matches"
href="#perlrequick-Extracting-matches">66.3.5 Extracting matches</a></li>
- <li><a name="toc-Matching-repetitions"
href="#perlrequick-Matching-repetitions">66.3.6 Matching repetitions</a></li>
- <li><a name="toc-More-matching" href="#perlrequick-More-matching">66.3.7
More matching</a></li>
- <li><a name="toc-Search-and-replace"
href="#perlrequick-Search-and-replace">66.3.8 Search and replace</a></li>
- <li><a name="toc-The-split-operator"
href="#perlrequick-The-split-operator">66.3.9 The split operator</a></li>
- <li><a name="toc-use-re-_0027strict_0027"
href="#perlrequick-use-re-_0027strict_0027">66.3.10 <code>use re
'strict'</code></a></li>
- </ul></li>
- <li><a name="toc-BUGS-7" href="#perlrequick-BUGS">66.4 BUGS</a></li>
- <li><a name="toc-SEE-ALSO-33" href="#perlrequick-SEE-ALSO">66.5 SEE
ALSO</a></li>
- <li><a name="toc-AUTHOR-AND-COPYRIGHT"
href="#perlrequick-AUTHOR-AND-COPYRIGHT">66.6 AUTHOR AND COPYRIGHT</a>
- <ul class="no-bullet">
- <li><a name="toc-Acknowledgments"
href="#perlrequick-Acknowledgments">66.6.1 Acknowledgments</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlreref-1" href="#perlreref">67 perlreref</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-66" href="#perlreref-NAME">67.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-65" href="#perlreref-DESCRIPTION">67.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-OPERATORS" href="#perlreref-OPERATORS">67.2.1
OPERATORS</a></li>
- <li><a name="toc-SYNTAX" href="#perlreref-SYNTAX">67.2.2 SYNTAX</a></li>
- <li><a name="toc-ESCAPE-SEQUENCES"
href="#perlreref-ESCAPE-SEQUENCES">67.2.3 ESCAPE SEQUENCES</a></li>
- <li><a name="toc-CHARACTER-CLASSES"
href="#perlreref-CHARACTER-CLASSES">67.2.4 CHARACTER CLASSES</a></li>
- <li><a name="toc-ANCHORS" href="#perlreref-ANCHORS">67.2.5
ANCHORS</a></li>
- <li><a name="toc-QUANTIFIERS" href="#perlreref-QUANTIFIERS">67.2.6
QUANTIFIERS</a></li>
- <li><a name="toc-EXTENDED-CONSTRUCTS"
href="#perlreref-EXTENDED-CONSTRUCTS">67.2.7 EXTENDED CONSTRUCTS</a></li>
- <li><a name="toc-VARIABLES" href="#perlreref-VARIABLES">67.2.8
VARIABLES</a></li>
- <li><a name="toc-FUNCTIONS" href="#perlreref-FUNCTIONS">67.2.9
FUNCTIONS</a></li>
- <li><a name="toc-TERMINOLOGY" href="#perlreref-TERMINOLOGY">67.2.10
TERMINOLOGY</a>
- <ul class="no-bullet">
- <li><a name="toc-Titlecase" href="#perlreref-Titlecase">67.2.10.1
Titlecase</a></li>
- <li><a name="toc-Foldcase" href="#perlreref-Foldcase">67.2.10.2
Foldcase</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-AUTHOR-26" href="#perlreref-AUTHOR">67.3 AUTHOR</a></li>
- <li><a name="toc-SEE-ALSO-34" href="#perlreref-SEE-ALSO">67.4 SEE
ALSO</a></li>
- <li><a name="toc-THANKS" href="#perlreref-THANKS">67.5 THANKS</a></li>
- </ul></li>
- <li><a name="toc-perlretut-10" href="#perlretut">68 perlretut</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-67" href="#perlretut-NAME">68.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-66" href="#perlretut-DESCRIPTION">68.2
DESCRIPTION</a></li>
- <li><a name="toc-Part-1_003a-The-basics"
href="#perlretut-Part-1_003a-The-basics">68.3 Part 1: The basics</a>
- <ul class="no-bullet">
- <li><a name="toc-Simple-word-matching-1"
href="#perlretut-Simple-word-matching">68.3.1 Simple word matching</a></li>
- <li><a name="toc-Using-character-classes-1"
href="#perlretut-Using-character-classes">68.3.2 Using character
classes</a></li>
- <li><a name="toc-Matching-this-or-that-1"
href="#perlretut-Matching-this-or-that">68.3.3 Matching this or that</a></li>
- <li><a name="toc-Grouping-things-and-hierarchical-matching-1"
href="#perlretut-Grouping-things-and-hierarchical-matching">68.3.4 Grouping
things and hierarchical matching</a></li>
- <li><a name="toc-Extracting-matches-1"
href="#perlretut-Extracting-matches">68.3.5 Extracting matches</a></li>
- <li><a name="toc-Backreferences" href="#perlretut-Backreferences">68.3.6
Backreferences</a></li>
- <li><a name="toc-Relative-backreferences"
href="#perlretut-Relative-backreferences">68.3.7 Relative
backreferences</a></li>
- <li><a name="toc-Named-backreferences"
href="#perlretut-Named-backreferences">68.3.8 Named backreferences</a></li>
- <li><a name="toc-Alternative-capture-group-numbering"
href="#perlretut-Alternative-capture-group-numbering">68.3.9 Alternative
capture group numbering</a></li>
- <li><a name="toc-Position-information"
href="#perlretut-Position-information">68.3.10 Position information</a></li>
- <li><a name="toc-Non_002dcapturing-groupings"
href="#perlretut-Non_002dcapturing-groupings">68.3.11 Non-capturing
groupings</a></li>
- <li><a name="toc-Matching-repetitions-1"
href="#perlretut-Matching-repetitions">68.3.12 Matching repetitions</a></li>
- <li><a name="toc-Possessive-quantifiers"
href="#perlretut-Possessive-quantifiers">68.3.13 Possessive quantifiers</a></li>
- <li><a name="toc-Building-a-regexp"
href="#perlretut-Building-a-regexp">68.3.14 Building a regexp</a></li>
- <li><a name="toc-Using-regular-expressions-in-Perl"
href="#perlretut-Using-regular-expressions-in-Perl">68.3.15 Using regular
expressions in Perl</a>
- <ul class="no-bullet">
- <li><a name="toc-Prohibiting-substitution"
href="#perlretut-Prohibiting-substitution">68.3.15.1 Prohibiting
substitution</a></li>
- <li><a name="toc-Global-matching"
href="#perlretut-Global-matching">68.3.15.2 Global matching</a></li>
- <li><a name="toc-Search-and-replace-1"
href="#perlretut-Search-and-replace">68.3.15.3 Search and replace</a></li>
- <li><a name="toc-The-split-function"
href="#perlretut-The-split-function">68.3.15.4 The split function</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-Part-2_003a-Power-tools"
href="#perlretut-Part-2_003a-Power-tools">68.4 Part 2: Power tools</a>
- <ul class="no-bullet">
- <li><a
name="toc-More-on-characters_002c-strings_002c-and-character-classes"
href="#perlretut-More-on-characters_002c-strings_002c-and-character-classes">68.4.1
More on characters, strings, and character classes</a></li>
- <li><a name="toc-Compiling-and-saving-regular-expressions"
href="#perlretut-Compiling-and-saving-regular-expressions">68.4.2 Compiling and
saving regular expressions</a></li>
- <li><a name="toc-Composing-regular-expressions-at-runtime"
href="#perlretut-Composing-regular-expressions-at-runtime">68.4.3 Composing
regular expressions at runtime</a></li>
- <li><a
name="toc-Embedding-comments-and-modifiers-in-a-regular-expression"
href="#perlretut-Embedding-comments-and-modifiers-in-a-regular-expression">68.4.4
Embedding comments and modifiers in a regular expression</a></li>
- <li><a name="toc-Looking-ahead-and-looking-behind"
href="#perlretut-Looking-ahead-and-looking-behind">68.4.5 Looking ahead and
looking behind</a></li>
- <li><a
name="toc-Using-independent-subexpressions-to-prevent-backtracking"
href="#perlretut-Using-independent-subexpressions-to-prevent-backtracking">68.4.6
Using independent subexpressions to prevent backtracking</a></li>
- <li><a name="toc-Conditional-expressions"
href="#perlretut-Conditional-expressions">68.4.7 Conditional
expressions</a></li>
- <li><a name="toc-Defining-named-patterns"
href="#perlretut-Defining-named-patterns">68.4.8 Defining named
patterns</a></li>
- <li><a name="toc-Recursive-patterns"
href="#perlretut-Recursive-patterns">68.4.9 Recursive patterns</a></li>
- <li><a
name="toc-A-bit-of-magic_003a-executing-Perl-code-in-a-regular-expression"
href="#perlretut-A-bit-of-magic_003a-executing-Perl-code-in-a-regular-expression">68.4.10
A bit of magic: executing Perl code in a regular expression</a></li>
- <li><a name="toc-Backtracking-control-verbs"
href="#perlretut-Backtracking-control-verbs">68.4.11 Backtracking control
verbs</a></li>
- <li><a name="toc-Pragmas-and-debugging"
href="#perlretut-Pragmas-and-debugging">68.4.12 Pragmas and debugging</a></li>
- </ul></li>
- <li><a name="toc-BUGS-8" href="#perlretut-BUGS">68.5 BUGS</a></li>
- <li><a name="toc-SEE-ALSO-35" href="#perlretut-SEE-ALSO">68.6 SEE
ALSO</a></li>
- <li><a name="toc-AUTHOR-AND-COPYRIGHT-1"
href="#perlretut-AUTHOR-AND-COPYRIGHT">68.7 AUTHOR AND COPYRIGHT</a>
- <ul class="no-bullet">
- <li><a name="toc-Acknowledgments-1"
href="#perlretut-Acknowledgments">68.7.1 Acknowledgments</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlrun-1" href="#perlrun">69 perlrun</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-68" href="#perlrun-NAME">69.1 NAME</a></li>
- <li><a name="toc-SYNOPSIS-9" href="#perlrun-SYNOPSIS">69.2
SYNOPSIS</a></li>
- <li><a name="toc-DESCRIPTION-67" href="#perlrun-DESCRIPTION">69.3
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-_0023_0021-and-quoting-on-non_002dUnix-systems"
href="#perlrun-_0023_0021-and-quoting-on-non_002dUnix-systems">69.3.1 #! and
quoting on non-Unix systems</a></li>
- <li><a name="toc-Location-of-Perl"
href="#perlrun-Location-of-Perl">69.3.2 Location of Perl</a></li>
- <li><a name="toc-Command-Switches"
href="#perlrun-Command-Switches">69.3.3 Command Switches</a></li>
- </ul></li>
- <li><a name="toc-ENVIRONMENT-2" href="#perlrun-ENVIRONMENT">69.4
ENVIRONMENT</a></li>
- </ul></li>
- <li><a name="toc-perlsec-1" href="#perlsec">70 perlsec</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-69" href="#perlsec-NAME">70.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-68" href="#perlsec-DESCRIPTION">70.2
DESCRIPTION</a></li>
- <li><a name="toc-SECURITY-VULNERABILITY-CONTACT-INFORMATION"
href="#perlsec-SECURITY-VULNERABILITY-CONTACT-INFORMATION">70.3 SECURITY
VULNERABILITY CONTACT INFORMATION</a></li>
- <li><a name="toc-SECURITY-MECHANISMS-AND-CONCERNS"
href="#perlsec-SECURITY-MECHANISMS-AND-CONCERNS">70.4 SECURITY MECHANISMS AND
CONCERNS</a>
- <ul class="no-bullet">
- <li><a name="toc-Taint-mode" href="#perlsec-Taint-mode">70.4.1 Taint
mode</a></li>
- <li><a name="toc-Laundering-and-Detecting-Tainted-Data"
href="#perlsec-Laundering-and-Detecting-Tainted-Data">70.4.2 Laundering and
Detecting Tainted Data</a></li>
- <li><a name="toc-Switches-On-the-_0022_0023_0021_0022-Line"
href="#perlsec-Switches-On-the-_0022_0023_0021_0022-Line">70.4.3 Switches On
the "#!" Line</a></li>
- <li><a name="toc-Taint-mode-and-_0040INC"
href="#perlsec-Taint-mode-and-_0040INC">70.4.4 Taint mode and @INC</a></li>
- <li><a name="toc-Cleaning-Up-Your-Path"
href="#perlsec-Cleaning-Up-Your-Path">70.4.5 Cleaning Up Your Path</a></li>
- <li><a name="toc-Security-Bugs" href="#perlsec-Security-Bugs">70.4.6
Security Bugs</a></li>
- <li><a name="toc-Protecting-Your-Programs"
href="#perlsec-Protecting-Your-Programs">70.4.7 Protecting Your
Programs</a></li>
- <li><a name="toc-Unicode-1" href="#perlsec-Unicode">70.4.8
Unicode</a></li>
- <li><a name="toc-Algorithmic-Complexity-Attacks"
href="#perlsec-Algorithmic-Complexity-Attacks">70.4.9 Algorithmic Complexity
Attacks</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-36" href="#perlsec-SEE-ALSO">70.5 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlsource-1" href="#perlsource">71 perlsource</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-70" href="#perlsource-NAME">71.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-69" href="#perlsource-DESCRIPTION">71.2
DESCRIPTION</a></li>
- <li><a name="toc-FINDING-YOUR-WAY-AROUND"
href="#perlsource-FINDING-YOUR-WAY-AROUND">71.3 FINDING YOUR WAY AROUND</a>
- <ul class="no-bullet">
- <li><a name="toc-C-code" href="#perlsource-C-code">71.3.1 C code</a></li>
- <li><a name="toc-Core-modules" href="#perlsource-Core-modules">71.3.2
Core modules</a></li>
- <li><a name="toc-Tests" href="#perlsource-Tests">71.3.3 Tests</a></li>
- <li><a name="toc-Documentation-1"
href="#perlsource-Documentation">71.3.4 Documentation</a></li>
- <li><a name="toc-Hacking-tools-and-documentation"
href="#perlsource-Hacking-tools-and-documentation">71.3.5 Hacking tools and
documentation</a></li>
- <li><a name="toc-Build-system" href="#perlsource-Build-system">71.3.6
Build system</a></li>
- <li><a name="toc-AUTHORS-5" href="#perlsource-AUTHORS">71.3.7
<samp>AUTHORS</samp></a></li>
- <li><a name="toc-MANIFEST" href="#perlsource-MANIFEST">71.3.8
<samp>MANIFEST</samp></a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlstyle-1" href="#perlstyle">72 perlstyle</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-71" href="#perlstyle-NAME">72.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-70" href="#perlstyle-DESCRIPTION">72.2
DESCRIPTION</a></li>
- </ul></li>
- <li><a name="toc-perlsub-2" href="#perlsub">73 perlsub</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-72" href="#perlsub-NAME">73.1 NAME</a></li>
- <li><a name="toc-SYNOPSIS-10" href="#perlsub-SYNOPSIS">73.2
SYNOPSIS</a></li>
- <li><a name="toc-DESCRIPTION-71" href="#perlsub-DESCRIPTION">73.3
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Signatures" href="#perlsub-Signatures">73.3.1
Signatures</a></li>
- <li><a name="toc-Private-Variables-via-my_0028_0029"
href="#perlsub-Private-Variables-via-my_0028_0029">73.3.2 Private Variables via
my()</a></li>
- <li><a name="toc-Persistent-Private-Variables"
href="#perlsub-Persistent-Private-Variables">73.3.3 Persistent Private
Variables</a>
- <ul class="no-bullet">
- <li><a name="toc-Persistent-variables-via-state_0028_0029"
href="#perlsub-Persistent-variables-via-state_0028_0029">73.3.3.1 Persistent
variables via state()</a></li>
- <li><a name="toc-Persistent-variables-with-closures"
href="#perlsub-Persistent-variables-with-closures">73.3.3.2 Persistent
variables with closures</a></li>
- </ul></li>
- <li><a name="toc-Temporary-Values-via-local_0028_0029"
href="#perlsub-Temporary-Values-via-local_0028_0029">73.3.4 Temporary Values
via local()</a>
- <ul class="no-bullet">
- <li><a name="toc-Grammatical-note-on-local_0028_0029"
href="#perlsub-Grammatical-note-on-local_0028_0029">73.3.4.1 Grammatical note
on local()</a></li>
- <li><a name="toc-Localization-of-special-variables"
href="#perlsub-Localization-of-special-variables">73.3.4.2 Localization of
special variables</a></li>
- <li><a name="toc-Localization-of-globs"
href="#perlsub-Localization-of-globs">73.3.4.3 Localization of globs</a></li>
- <li><a name="toc-Localization-of-elements-of-composite-types"
href="#perlsub-Localization-of-elements-of-composite-types">73.3.4.4
Localization of elements of composite types</a></li>
- <li><a name="toc-Localized-deletion-of-elements-of-composite-types"
href="#perlsub-Localized-deletion-of-elements-of-composite-types">73.3.4.5
Localized deletion of elements of composite types</a></li>
- </ul></li>
- <li><a name="toc-Lvalue-subroutines"
href="#perlsub-Lvalue-subroutines">73.3.5 Lvalue subroutines</a></li>
- <li><a name="toc-Lexical-Subroutines"
href="#perlsub-Lexical-Subroutines">73.3.6 Lexical Subroutines</a>
- <ul class="no-bullet">
- <li><a name="toc-state-sub-vs-my-sub"
href="#perlsub-state-sub-vs-my-sub">73.3.6.1 <code>state sub</code> vs <code>my
sub</code></a></li>
- <li><a name="toc-our-subroutines"
href="#perlsub-our-subroutines">73.3.6.2 <code>our</code> subroutines</a></li>
- </ul></li>
- <li><a name="toc-Passing-Symbol-Table-Entries-_0028typeglobs_0029"
href="#perlsub-Passing-Symbol-Table-Entries-_0028typeglobs_0029">73.3.7 Passing
Symbol Table Entries (typeglobs)</a></li>
- <li><a name="toc-When-to-Still-Use-local_0028_0029"
href="#perlsub-When-to-Still-Use-local_0028_0029">73.3.8 When to Still Use
local()</a></li>
- <li><a name="toc-Pass-by-Reference"
href="#perlsub-Pass-by-Reference">73.3.9 Pass by Reference</a></li>
- <li><a name="toc-Prototypes" href="#perlsub-Prototypes">73.3.10
Prototypes</a></li>
- <li><a name="toc-Constant-Functions"
href="#perlsub-Constant-Functions">73.3.11 Constant Functions</a></li>
- <li><a name="toc-Overriding-Built_002din-Functions"
href="#perlsub-Overriding-Built_002din-Functions">73.3.12 Overriding Built-in
Functions</a></li>
- <li><a name="toc-Autoloading" href="#perlsub-Autoloading">73.3.13
Autoloading</a></li>
- <li><a name="toc-Subroutine-Attributes"
href="#perlsub-Subroutine-Attributes">73.3.14 Subroutine Attributes</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-37" href="#perlsub-SEE-ALSO">73.4 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlsyn-2" href="#perlsyn">74 perlsyn</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-73" href="#perlsyn-NAME">74.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-72" href="#perlsyn-DESCRIPTION">74.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Declarations" href="#perlsyn-Declarations">74.2.1
Declarations</a></li>
- <li><a name="toc-Comments" href="#perlsyn-Comments">74.2.2
Comments</a></li>
- <li><a name="toc-Simple-Statements"
href="#perlsyn-Simple-Statements">74.2.3 Simple Statements</a></li>
- <li><a name="toc-Truth-and-Falsehood"
href="#perlsyn-Truth-and-Falsehood">74.2.4 Truth and Falsehood</a></li>
- <li><a name="toc-Statement-Modifiers"
href="#perlsyn-Statement-Modifiers">74.2.5 Statement Modifiers</a></li>
- <li><a name="toc-Compound-Statements"
href="#perlsyn-Compound-Statements">74.2.6 Compound Statements</a></li>
- <li><a name="toc-Loop-Control" href="#perlsyn-Loop-Control">74.2.7 Loop
Control</a></li>
- <li><a name="toc-For-Loops" href="#perlsyn-For-Loops">74.2.8 For
Loops</a></li>
- <li><a name="toc-Foreach-Loops" href="#perlsyn-Foreach-Loops">74.2.9
Foreach Loops</a></li>
- <li><a name="toc-Basic-BLOCKs" href="#perlsyn-Basic-BLOCKs">74.2.10
Basic BLOCKs</a></li>
- <li><a name="toc-Switch-Statements"
href="#perlsyn-Switch-Statements">74.2.11 Switch Statements</a></li>
- <li><a name="toc-Goto" href="#perlsyn-Goto">74.2.12 Goto</a></li>
- <li><a name="toc-The-Ellipsis-Statement"
href="#perlsyn-The-Ellipsis-Statement">74.2.13 The Ellipsis Statement</a></li>
- <li><a name="toc-PODs_003a-Embedded-Documentation"
href="#perlsyn-PODs_003a-Embedded-Documentation">74.2.14 PODs: Embedded
Documentation</a></li>
- <li><a name="toc-Plain-Old-Comments-_0028Not_0021_0029"
href="#perlsyn-Plain-Old-Comments-_0028Not_0021_0029">74.2.15 Plain Old
Comments (Not!)</a></li>
- <li><a name="toc-Experimental-Details-on-given-and-when"
href="#perlsyn-Experimental-Details-on-given-and-when">74.2.16 Experimental
Details on given and when</a>
- <ul class="no-bullet">
- <li><a name="toc-Breaking-out" href="#perlsyn-Breaking-out">74.2.16.1
Breaking out</a></li>
- <li><a name="toc-Fall_002dthrough"
href="#perlsyn-Fall_002dthrough">74.2.16.2 Fall-through</a></li>
- <li><a name="toc-Return-value" href="#perlsyn-Return-value">74.2.16.3
Return value</a></li>
- <li><a name="toc-Switching-in-a-loop"
href="#perlsyn-Switching-in-a-loop">74.2.16.4 Switching in a loop</a></li>
- <li><a name="toc-Differences-from-Perl-6"
href="#perlsyn-Differences-from-Perl-6">74.2.16.5 Differences from Perl
6</a></li>
- </ul></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlthrtut-1" href="#perlthrtut">75 perlthrtut</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-74" href="#perlthrtut-NAME">75.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-73" href="#perlthrtut-DESCRIPTION">75.2
DESCRIPTION</a></li>
- <li><a name="toc-What-Is-A-Thread-Anyway_003f"
href="#perlthrtut-What-Is-A-Thread-Anyway_003f">75.3 What Is A Thread
Anyway?</a></li>
- <li><a name="toc-Threaded-Program-Models"
href="#perlthrtut-Threaded-Program-Models">75.4 Threaded Program Models</a>
- <ul class="no-bullet">
- <li><a name="toc-Boss_002fWorker"
href="#perlthrtut-Boss_002fWorker">75.4.1 Boss/Worker</a></li>
- <li><a name="toc-Work-Crew" href="#perlthrtut-Work-Crew">75.4.2 Work
Crew</a></li>
- <li><a name="toc-Pipeline" href="#perlthrtut-Pipeline">75.4.3
Pipeline</a></li>
- </ul></li>
- <li><a name="toc-What-kind-of-threads-are-Perl-threads_003f"
href="#perlthrtut-What-kind-of-threads-are-Perl-threads_003f">75.5 What kind of
threads are Perl threads?</a></li>
- <li><a name="toc-Thread_002dSafe-Modules"
href="#perlthrtut-Thread_002dSafe-Modules">75.6 Thread-Safe Modules</a></li>
- <li><a name="toc-Thread-Basics" href="#perlthrtut-Thread-Basics">75.7
Thread Basics</a>
- <ul class="no-bullet">
- <li><a name="toc-Basic-Thread-Support"
href="#perlthrtut-Basic-Thread-Support">75.7.1 Basic Thread Support</a></li>
- <li><a name="toc-A-Note-about-the-Examples"
href="#perlthrtut-A-Note-about-the-Examples">75.7.2 A Note about the
Examples</a></li>
- <li><a name="toc-Creating-Threads"
href="#perlthrtut-Creating-Threads">75.7.3 Creating Threads</a></li>
- <li><a name="toc-Waiting-For-A-Thread-To-Exit"
href="#perlthrtut-Waiting-For-A-Thread-To-Exit">75.7.4 Waiting For A Thread To
Exit</a></li>
- <li><a name="toc-Ignoring-A-Thread"
href="#perlthrtut-Ignoring-A-Thread">75.7.5 Ignoring A Thread</a></li>
- <li><a name="toc-Process-and-Thread-Termination"
href="#perlthrtut-Process-and-Thread-Termination">75.7.6 Process and Thread
Termination</a></li>
- </ul></li>
- <li><a name="toc-Threads-And-Data"
href="#perlthrtut-Threads-And-Data">75.8 Threads And Data</a>
- <ul class="no-bullet">
- <li><a name="toc-Shared-And-Unshared-Data"
href="#perlthrtut-Shared-And-Unshared-Data">75.8.1 Shared And Unshared
Data</a></li>
- <li><a name="toc-Thread-Pitfalls_003a-Races"
href="#perlthrtut-Thread-Pitfalls_003a-Races">75.8.2 Thread Pitfalls:
Races</a></li>
- </ul></li>
- <li><a name="toc-Synchronization-and-control"
href="#perlthrtut-Synchronization-and-control">75.9 Synchronization and
control</a>
- <ul class="no-bullet">
- <li><a name="toc-Controlling-access_003a-lock_0028_0029"
href="#perlthrtut-Controlling-access_003a-lock_0028_0029">75.9.1 Controlling
access: lock()</a></li>
- <li><a name="toc-A-Thread-Pitfall_003a-Deadlocks"
href="#perlthrtut-A-Thread-Pitfall_003a-Deadlocks">75.9.2 A Thread Pitfall:
Deadlocks</a></li>
- <li><a name="toc-Queues_003a-Passing-Data-Around"
href="#perlthrtut-Queues_003a-Passing-Data-Around">75.9.3 Queues: Passing Data
Around</a></li>
- <li><a name="toc-Semaphores_003a-Synchronizing-Data-Access"
href="#perlthrtut-Semaphores_003a-Synchronizing-Data-Access">75.9.4 Semaphores:
Synchronizing Data Access</a></li>
- <li><a name="toc-Basic-semaphores"
href="#perlthrtut-Basic-semaphores">75.9.5 Basic semaphores</a></li>
- <li><a name="toc-Advanced-Semaphores"
href="#perlthrtut-Advanced-Semaphores">75.9.6 Advanced Semaphores</a></li>
- <li><a name="toc-Waiting-for-a-Condition"
href="#perlthrtut-Waiting-for-a-Condition">75.9.7 Waiting for a
Condition</a></li>
- <li><a name="toc-Giving-up-control"
href="#perlthrtut-Giving-up-control">75.9.8 Giving up control</a></li>
- </ul></li>
- <li><a name="toc-General-Thread-Utility-Routines"
href="#perlthrtut-General-Thread-Utility-Routines">75.10 General Thread Utility
Routines</a>
- <ul class="no-bullet">
- <li><a name="toc-What-Thread-Am-I-In_003f"
href="#perlthrtut-What-Thread-Am-I-In_003f">75.10.1 What Thread Am I
In?</a></li>
- <li><a name="toc-Thread-IDs" href="#perlthrtut-Thread-IDs">75.10.2
Thread IDs</a></li>
- <li><a name="toc-Are-These-Threads-The-Same_003f"
href="#perlthrtut-Are-These-Threads-The-Same_003f">75.10.3 Are These Threads
The Same?</a></li>
- <li><a name="toc-What-Threads-Are-Running_003f"
href="#perlthrtut-What-Threads-Are-Running_003f">75.10.4 What Threads Are
Running?</a></li>
- </ul></li>
- <li><a name="toc-A-Complete-Example"
href="#perlthrtut-A-Complete-Example">75.11 A Complete Example</a></li>
- <li><a name="toc-Different-implementations-of-threads"
href="#perlthrtut-Different-implementations-of-threads">75.12 Different
implementations of threads</a></li>
- <li><a name="toc-Performance-considerations"
href="#perlthrtut-Performance-considerations">75.13 Performance
considerations</a></li>
- <li><a name="toc-Process_002dscope-Changes"
href="#perlthrtut-Process_002dscope-Changes">75.14 Process-scope
Changes</a></li>
- <li><a name="toc-Thread_002dSafety-of-System-Libraries"
href="#perlthrtut-Thread_002dSafety-of-System-Libraries">75.15 Thread-Safety of
System Libraries</a></li>
- <li><a name="toc-Conclusion" href="#perlthrtut-Conclusion">75.16
Conclusion</a></li>
- <li><a name="toc-SEE-ALSO-38" href="#perlthrtut-SEE-ALSO">75.17 SEE
ALSO</a></li>
- <li><a name="toc-Bibliography" href="#perlthrtut-Bibliography">75.18
Bibliography</a>
- <ul class="no-bullet">
- <li><a name="toc-Introductory-Texts"
href="#perlthrtut-Introductory-Texts">75.18.1 Introductory Texts</a></li>
- <li><a name="toc-OS_002dRelated-References"
href="#perlthrtut-OS_002dRelated-References">75.18.2 OS-Related
References</a></li>
- <li><a name="toc-Other-References"
href="#perlthrtut-Other-References">75.18.3 Other References</a></li>
- </ul></li>
- <li><a name="toc-Acknowledgements"
href="#perlthrtut-Acknowledgements">75.19 Acknowledgements</a></li>
- <li><a name="toc-AUTHOR-27" href="#perlthrtut-AUTHOR">75.20 AUTHOR</a></li>
- <li><a name="toc-Copyrights-1" href="#perlthrtut-Copyrights">75.21
Copyrights</a></li>
- </ul></li>
- <li><a name="toc-perltie-1" href="#perltie">76 perltie</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-75" href="#perltie-NAME">76.1 NAME</a></li>
- <li><a name="toc-SYNOPSIS-11" href="#perltie-SYNOPSIS">76.2
SYNOPSIS</a></li>
- <li><a name="toc-DESCRIPTION-74" href="#perltie-DESCRIPTION">76.3
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Tying-Scalars" href="#perltie-Tying-Scalars">76.3.1
Tying Scalars</a></li>
- <li><a name="toc-Tying-Arrays" href="#perltie-Tying-Arrays">76.3.2 Tying
Arrays</a></li>
- <li><a name="toc-Tying-Hashes" href="#perltie-Tying-Hashes">76.3.3 Tying
Hashes</a></li>
- <li><a name="toc-Tying-FileHandles"
href="#perltie-Tying-FileHandles">76.3.4 Tying FileHandles</a></li>
- <li><a name="toc-UNTIE-this" href="#perltie-UNTIE-this-4">76.3.5 UNTIE
this</a></li>
- <li><a name="toc-The-untie-Gotcha"
href="#perltie-The-untie-Gotcha">76.3.6 The <code>untie</code> Gotcha</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-39" href="#perltie-SEE-ALSO">76.4 SEE
ALSO</a></li>
- <li><a name="toc-BUGS-9" href="#perltie-BUGS">76.5 BUGS</a></li>
- <li><a name="toc-AUTHOR-28" href="#perltie-AUTHOR">76.6 AUTHOR</a></li>
- </ul></li>
- <li><a name="toc-perltodo-1" href="#perltodo">77 perltodo</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-76" href="#perltodo-NAME">77.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-75" href="#perltodo-DESCRIPTION">77.2
DESCRIPTION</a></li>
- </ul></li>
- <li><a name="toc-perltooc-1" href="#perltooc">78 perltooc</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-77" href="#perltooc-NAME">78.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-76" href="#perltooc-DESCRIPTION">78.2
DESCRIPTION</a></li>
- </ul></li>
- <li><a name="toc-perltoot-1" href="#perltoot">79 perltoot</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-78" href="#perltoot-NAME">79.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-77" href="#perltoot-DESCRIPTION">79.2
DESCRIPTION</a></li>
- </ul></li>
- <li><a name="toc-perltrap-1" href="#perltrap">80 perltrap</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-79" href="#perltrap-NAME">80.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-78" href="#perltrap-DESCRIPTION">80.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Awk-Traps" href="#perltrap-Awk-Traps">80.2.1 Awk
Traps</a></li>
- <li><a name="toc-C_002fC_002b_002b-Traps"
href="#perltrap-C_002fC_002b_002b-Traps">80.2.2 C/C++ Traps</a></li>
- <li><a name="toc-JavaScript-Traps"
href="#perltrap-JavaScript-Traps">80.2.3 JavaScript Traps</a></li>
- <li><a name="toc-Sed-Traps" href="#perltrap-Sed-Traps">80.2.4 Sed
Traps</a></li>
- <li><a name="toc-Shell-Traps" href="#perltrap-Shell-Traps">80.2.5 Shell
Traps</a></li>
- <li><a name="toc-Perl-Traps" href="#perltrap-Perl-Traps">80.2.6 Perl
Traps</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlunicode-1" href="#perlunicode">81 perlunicode</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-80" href="#perlunicode-NAME">81.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-79" href="#perlunicode-DESCRIPTION">81.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Important-Caveats"
href="#perlunicode-Important-Caveats">81.2.1 Important Caveats</a></li>
- <li><a name="toc-Byte-and-Character-Semantics"
href="#perlunicode-Byte-and-Character-Semantics">81.2.2 Byte and Character
Semantics</a></li>
- <li><a name="toc-ASCII-Rules-versus-Unicode-Rules"
href="#perlunicode-ASCII-Rules-versus-Unicode-Rules">81.2.3 ASCII Rules versus
Unicode Rules</a></li>
- <li><a
name="toc-Extended-Grapheme-Clusters-_0028Logical-characters_0029"
href="#perlunicode-Extended-Grapheme-Clusters-_0028Logical-characters_0029">81.2.4
Extended Grapheme Clusters (Logical characters)</a></li>
- <li><a name="toc-Unicode-Character-Properties"
href="#perlunicode-Unicode-Character-Properties">81.2.5 Unicode Character
Properties</a>
- <ul class="no-bullet">
- <li><a name="toc-General_005fCategory"
href="#perlunicode-General_005fCategory">81.2.5.1
<strong>General_Category</strong></a></li>
- <li><a name="toc-Bidirectional-Character-Types"
href="#perlunicode-Bidirectional-Character-Types">81.2.5.2
<strong>Bidirectional Character Types</strong></a></li>
- <li><a name="toc-Scripts" href="#perlunicode-Scripts">81.2.5.3
<strong>Scripts</strong></a></li>
- <li><a name="toc-Use-of-the-_0022Is_0022-Prefix"
href="#perlunicode-Use-of-the-_0022Is_0022-Prefix">81.2.5.4 <strong>Use of the
<code>"Is"</code> Prefix</strong></a></li>
- <li><a name="toc-Blocks" href="#perlunicode-Blocks">81.2.5.5
<strong>Blocks</strong></a></li>
- <li><a name="toc-Other-Properties"
href="#perlunicode-Other-Properties">81.2.5.6 <strong>Other
Properties</strong></a></li>
- </ul></li>
- <li><a name="toc-User_002dDefined-Character-Properties"
href="#perlunicode-User_002dDefined-Character-Properties">81.2.6 User-Defined
Character Properties</a></li>
- <li><a
name="toc-User_002dDefined-Case-Mappings-_0028for-serious-hackers-only_0029"
href="#perlunicode-User_002dDefined-Case-Mappings-_0028for-serious-hackers-only_0029">81.2.7
User-Defined Case Mappings (for serious hackers only)</a></li>
- <li><a name="toc-Character-Encodings-for-Input-and-Output"
href="#perlunicode-Character-Encodings-for-Input-and-Output">81.2.8 Character
Encodings for Input and Output</a></li>
- <li><a name="toc-Unicode-Regular-Expression-Support-Level"
href="#perlunicode-Unicode-Regular-Expression-Support-Level">81.2.9 Unicode
Regular Expression Support Level</a></li>
- <li><a name="toc-Unicode-Encodings"
href="#perlunicode-Unicode-Encodings">81.2.10 Unicode Encodings</a></li>
- <li><a name="toc-Noncharacter-code-points"
href="#perlunicode-Noncharacter-code-points">81.2.11 Noncharacter code
points</a></li>
- <li><a name="toc-Beyond-Unicode-code-points"
href="#perlunicode-Beyond-Unicode-code-points">81.2.12 Beyond Unicode code
points</a></li>
- <li><a name="toc-Security-Implications-of-Unicode"
href="#perlunicode-Security-Implications-of-Unicode">81.2.13 Security
Implications of Unicode</a></li>
- <li><a name="toc-Unicode-in-Perl-on-EBCDIC"
href="#perlunicode-Unicode-in-Perl-on-EBCDIC">81.2.14 Unicode in Perl on
EBCDIC</a></li>
- <li><a name="toc-Locales" href="#perlunicode-Locales">81.2.15
Locales</a></li>
- <li><a name="toc-When-Unicode-Does-Not-Happen"
href="#perlunicode-When-Unicode-Does-Not-Happen">81.2.16 When Unicode Does Not
Happen</a></li>
- <li><a name="toc-The-_0022Unicode-Bug_0022"
href="#perlunicode-The-_0022Unicode-Bug_0022">81.2.17 The "Unicode
Bug"</a></li>
- <li><a
name="toc-Forcing-Unicode-in-Perl-_0028Or-Unforcing-Unicode-in-Perl_0029"
href="#perlunicode-Forcing-Unicode-in-Perl-_0028Or-Unforcing-Unicode-in-Perl_0029">81.2.18
Forcing Unicode in Perl (Or Unforcing Unicode in Perl)</a></li>
- <li><a name="toc-Using-Unicode-in-XS"
href="#perlunicode-Using-Unicode-in-XS">81.2.19 Using Unicode in XS</a></li>
- <li><a
name="toc-Hacking-Perl-to-work-on-earlier-Unicode-versions-_0028for-very-serious-hackers-only_0029"
href="#perlunicode-Hacking-Perl-to-work-on-earlier-Unicode-versions-_0028for-very-serious-hackers-only_0029">81.2.20
Hacking Perl to work on earlier Unicode versions (for very serious hackers
only)</a></li>
- <li><a name="toc-Porting-code-from-perl_002d5_002e6_002eX"
href="#perlunicode-Porting-code-from-perl_002d5_002e6_002eX">81.2.21 Porting
code from perl-5.6.X</a></li>
- </ul></li>
- <li><a name="toc-BUGS-10" href="#perlunicode-BUGS">81.3 BUGS</a>
- <ul class="no-bullet">
- <li><a name="toc-Interaction-with-Extensions"
href="#perlunicode-Interaction-with-Extensions">81.3.1 Interaction with
Extensions</a></li>
- <li><a name="toc-Speed" href="#perlunicode-Speed">81.3.2 Speed</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-40" href="#perlunicode-SEE-ALSO">81.4 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlunifaq-1" href="#perlunifaq">82 perlunifaq</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-81" href="#perlunifaq-NAME">82.1 NAME</a></li>
- <li><a name="toc-Q-and-A" href="#perlunifaq-Q-and-A">82.2 Q and A</a>
- <ul class="no-bullet">
- <li><a
name="toc-perlunitut-isn_0027t-really-a-Unicode-tutorial_002c-is-it_003f"
href="#perlunifaq-perlunitut-isn_0027t-really-a-Unicode-tutorial_002c-is-it_003f">82.2.1
perlunitut isn’t really a Unicode tutorial, is it?</a></li>
- <li><a name="toc-What-character-encodings-does-Perl-support_003f"
href="#perlunifaq-What-character-encodings-does-Perl-support_003f">82.2.2 What
character encodings does Perl support?</a></li>
- <li><a name="toc-Which-version-of-perl-should-I-use_003f"
href="#perlunifaq-Which-version-of-perl-should-I-use_003f">82.2.3 Which version
of perl should I use?</a></li>
- <li><a name="toc-What-about-binary-data_002c-like-images_003f"
href="#perlunifaq-What-about-binary-data_002c-like-images_003f">82.2.4 What
about binary data, like images?</a></li>
- <li><a name="toc-When-should-I-decode-or-encode_003f"
href="#perlunifaq-When-should-I-decode-or-encode_003f">82.2.5 When should I
decode or encode?</a></li>
- <li><a name="toc-What-if-I-don_0027t-decode_003f"
href="#perlunifaq-What-if-I-don_0027t-decode_003f">82.2.6 What if I don’t
decode?</a></li>
- <li><a name="toc-What-if-I-don_0027t-encode_003f"
href="#perlunifaq-What-if-I-don_0027t-encode_003f">82.2.7 What if I don’t
encode?</a></li>
- <li><a name="toc-Is-there-a-way-to-automatically-decode-or-encode_003f"
href="#perlunifaq-Is-there-a-way-to-automatically-decode-or-encode_003f">82.2.8
Is there a way to automatically decode or encode?</a></li>
- <li><a name="toc-What-if-I-don_0027t-know-which-encoding-was-used_003f"
href="#perlunifaq-What-if-I-don_0027t-know-which-encoding-was-used_003f">82.2.9
What if I don’t know which encoding was used?</a></li>
- <li><a name="toc-Can-I-use-Unicode-in-my-Perl-sources_003f"
href="#perlunifaq-Can-I-use-Unicode-in-my-Perl-sources_003f">82.2.10 Can I use
Unicode in my Perl sources?</a></li>
- <li><a
name="toc-Data_003a_003aDumper-doesn_0027t-restore-the-UTF8-flag_003b-is-it-broken_003f"
href="#perlunifaq-Data_003a_003aDumper-doesn_0027t-restore-the-UTF8-flag_003b-is-it-broken_003f">82.2.11
Data::Dumper doesn’t restore the UTF8 flag; is it broken?</a></li>
- <li><a
name="toc-Why-do-regex-character-classes-sometimes-match-only-in-the-ASCII-range_003f"
href="#perlunifaq-Why-do-regex-character-classes-sometimes-match-only-in-the-ASCII-range_003f">82.2.12
Why do regex character classes sometimes match only in the ASCII
range?</a></li>
- <li><a
name="toc-Why-do-some-characters-not-uppercase-or-lowercase-correctly_003f"
href="#perlunifaq-Why-do-some-characters-not-uppercase-or-lowercase-correctly_003f">82.2.13
Why do some characters not uppercase or lowercase correctly?</a></li>
- <li><a
name="toc-How-can-I-determine-if-a-string-is-a-text-string-or-a-binary-string_003f"
href="#perlunifaq-How-can-I-determine-if-a-string-is-a-text-string-or-a-binary-string_003f">82.2.14
How can I determine if a string is a text string or a binary string?</a></li>
- <li><a
name="toc-How-do-I-convert-from-encoding-FOO-to-encoding-BAR_003f"
href="#perlunifaq-How-do-I-convert-from-encoding-FOO-to-encoding-BAR_003f">82.2.15
How do I convert from encoding FOO to encoding BAR?</a></li>
- <li><a name="toc-What-are-decode_005futf8-and-encode_005futf8_003f"
href="#perlunifaq-What-are-decode_005futf8-and-encode_005futf8_003f">82.2.16
What are <code>decode_utf8</code> and <code>encode_utf8</code>?</a></li>
- <li><a name="toc-What-is-a-_0022wide-character_0022_003f"
href="#perlunifaq-What-is-a-_0022wide-character_0022_003f">82.2.17 What is a
"wide character"?</a></li>
- </ul></li>
- <li><a name="toc-INTERNALS" href="#perlunifaq-INTERNALS">82.3 INTERNALS</a>
- <ul class="no-bullet">
- <li><a name="toc-What-is-_0022the-UTF8-flag_0022_003f"
href="#perlunifaq-What-is-_0022the-UTF8-flag_0022_003f">82.3.1 What is
"the UTF8 flag"?</a></li>
- <li><a name="toc-What-about-the-use-bytes-pragma_003f"
href="#perlunifaq-What-about-the-use-bytes-pragma_003f">82.3.2 What about the
<code>use bytes</code> pragma?</a></li>
- <li><a name="toc-What-about-the-use-encoding-pragma_003f"
href="#perlunifaq-What-about-the-use-encoding-pragma_003f">82.3.3 What about
the <code>use encoding</code> pragma?</a></li>
- <li><a
name="toc-What-is-the-difference-between-_003aencoding-and-_003autf8_003f"
href="#perlunifaq-What-is-the-difference-between-_003aencoding-and-_003autf8_003f">82.3.4
What is the difference between <code>:encoding</code> and
<code>:utf8</code>?</a></li>
- <li><a
name="toc-What_0027s-the-difference-between-UTF_002d8-and-utf8_003f"
href="#perlunifaq-What_0027s-the-difference-between-UTF_002d8-and-utf8_003f">82.3.5
What’s the difference between <code>UTF-8</code> and
<code>utf8</code>?</a></li>
- <li><a
name="toc-I-lost-track_003b-what-encoding-is-the-internal-format-really_003f"
href="#perlunifaq-I-lost-track_003b-what-encoding-is-the-internal-format-really_003f">82.3.6
I lost track; what encoding is the internal format really?</a></li>
- </ul></li>
- <li><a name="toc-AUTHOR-29" href="#perlunifaq-AUTHOR">82.4 AUTHOR</a></li>
- <li><a name="toc-SEE-ALSO-41" href="#perlunifaq-SEE-ALSO">82.5 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perluniintro-1" href="#perluniintro">83 perluniintro</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-82" href="#perluniintro-NAME">83.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-80" href="#perluniintro-DESCRIPTION">83.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Unicode-2" href="#perluniintro-Unicode">83.2.1
Unicode</a></li>
- <li><a name="toc-Perl_0027s-Unicode-Support"
href="#perluniintro-Perl_0027s-Unicode-Support">83.2.2 Perl’s Unicode
Support</a></li>
- <li><a name="toc-Perl_0027s-Unicode-Model"
href="#perluniintro-Perl_0027s-Unicode-Model">83.2.3 Perl’s Unicode
Model</a></li>
- <li><a name="toc-Unicode-and-EBCDIC"
href="#perluniintro-Unicode-and-EBCDIC">83.2.4 Unicode and EBCDIC</a></li>
- <li><a name="toc-Creating-Unicode"
href="#perluniintro-Creating-Unicode">83.2.5 Creating Unicode</a>
- <ul class="no-bullet">
- <li><a name="toc-Earlier-releases-caveats"
href="#perluniintro-Earlier-releases-caveats">83.2.5.1 Earlier releases
caveats</a></li>
- </ul></li>
- <li><a name="toc-Handling-Unicode"
href="#perluniintro-Handling-Unicode">83.2.6 Handling Unicode</a></li>
- <li><a name="toc-Legacy-Encodings"
href="#perluniintro-Legacy-Encodings">83.2.7 Legacy Encodings</a></li>
- <li><a name="toc-Unicode-I_002fO"
href="#perluniintro-Unicode-I_002fO">83.2.8 Unicode I/O</a></li>
- <li><a name="toc-Displaying-Unicode-As-Text"
href="#perluniintro-Displaying-Unicode-As-Text">83.2.9 Displaying Unicode As
Text</a></li>
- <li><a name="toc-Special-Cases"
href="#perluniintro-Special-Cases">83.2.10 Special Cases</a></li>
- <li><a name="toc-Advanced-Topics"
href="#perluniintro-Advanced-Topics">83.2.11 Advanced Topics</a></li>
- <li><a name="toc-Miscellaneous-1"
href="#perluniintro-Miscellaneous">83.2.12 Miscellaneous</a></li>
- <li><a name="toc-Questions-With-Answers"
href="#perluniintro-Questions-With-Answers">83.2.13 Questions With
Answers</a></li>
- <li><a name="toc-Hexadecimal-Notation"
href="#perluniintro-Hexadecimal-Notation">83.2.14 Hexadecimal Notation</a></li>
- <li><a name="toc-Further-Resources"
href="#perluniintro-Further-Resources">83.2.15 Further Resources</a></li>
- </ul></li>
- <li><a name="toc-UNICODE-IN-OLDER-PERLS"
href="#perluniintro-UNICODE-IN-OLDER-PERLS">83.3 UNICODE IN OLDER PERLS</a></li>
- <li><a name="toc-SEE-ALSO-42" href="#perluniintro-SEE-ALSO">83.4 SEE
ALSO</a></li>
- <li><a name="toc-ACKNOWLEDGMENTS"
href="#perluniintro-ACKNOWLEDGMENTS">83.5 ACKNOWLEDGMENTS</a></li>
- <li><a name="toc-AUTHOR_002c-COPYRIGHT_002c-AND-LICENSE"
href="#perluniintro-AUTHOR_002c-COPYRIGHT_002c-AND-LICENSE">83.6 AUTHOR,
COPYRIGHT, AND LICENSE</a></li>
- </ul></li>
- <li><a name="toc-perlunitut-1" href="#perlunitut">84 perlunitut</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-83" href="#perlunitut-NAME">84.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-81" href="#perlunitut-DESCRIPTION">84.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-Definitions-1" href="#perlunitut-Definitions">84.2.1
Definitions</a>
- <ul class="no-bullet">
- <li><a name="toc-Unicode-3" href="#perlunitut-Unicode">84.2.1.1
Unicode</a></li>
- <li><a name="toc-UTF_002d8" href="#perlunitut-UTF_002d8">84.2.1.2
UTF-8</a></li>
- <li><a name="toc-Text-strings-_0028character-strings_0029"
href="#perlunitut-Text-strings-_0028character-strings_0029">84.2.1.3 Text
strings (character strings)</a></li>
- <li><a name="toc-Binary-strings-_0028byte-strings_0029"
href="#perlunitut-Binary-strings-_0028byte-strings_0029">84.2.1.4 Binary
strings (byte strings)</a></li>
- <li><a name="toc-Encoding" href="#perlunitut-Encoding">84.2.1.5
Encoding</a></li>
- <li><a name="toc-Decoding" href="#perlunitut-Decoding">84.2.1.6
Decoding</a></li>
- <li><a name="toc-Internal-format"
href="#perlunitut-Internal-format">84.2.1.7 Internal format</a></li>
- </ul></li>
- <li><a name="toc-Your-new-toolkit"
href="#perlunitut-Your-new-toolkit">84.2.2 Your new toolkit</a></li>
- <li><a name="toc-I_002fO-flow-_0028the-actual-5-minute-tutorial_0029"
href="#perlunitut-I_002fO-flow-_0028the-actual-5-minute-tutorial_0029">84.2.3
I/O flow (the actual 5 minute tutorial)</a></li>
- </ul></li>
- <li><a name="toc-SUMMARY-1" href="#perlunitut-SUMMARY">84.3
SUMMARY</a></li>
- <li><a name="toc-Q-and-A-_0028or-FAQ_0029"
href="#perlunitut-Q-and-A-_0028or-FAQ_0029">84.4 Q and A (or FAQ)</a></li>
- <li><a name="toc-ACKNOWLEDGEMENTS-1"
href="#perlunitut-ACKNOWLEDGEMENTS">84.5 ACKNOWLEDGEMENTS</a></li>
- <li><a name="toc-AUTHOR-30" href="#perlunitut-AUTHOR">84.6 AUTHOR</a></li>
- <li><a name="toc-SEE-ALSO-43" href="#perlunitut-SEE-ALSO">84.7 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlutil-1" href="#perlutil">85 perlutil</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-84" href="#perlutil-NAME">85.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-82" href="#perlutil-DESCRIPTION">85.2
DESCRIPTION</a></li>
- <li><a name="toc-LIST-OF-UTILITIES"
href="#perlutil-LIST-OF-UTILITIES">85.3 LIST OF UTILITIES</a>
- <ul class="no-bullet">
- <li><a name="toc-Documentation-2" href="#perlutil-Documentation">85.3.1
Documentation</a></li>
- <li><a name="toc-Converters" href="#perlutil-Converters">85.3.2
Converters</a></li>
- <li><a name="toc-Administration" href="#perlutil-Administration">85.3.3
Administration</a></li>
- <li><a name="toc-Development" href="#perlutil-Development">85.3.4
Development</a></li>
- <li><a name="toc-General-tools" href="#perlutil-General-tools">85.3.5
General tools</a></li>
- <li><a name="toc-Installation" href="#perlutil-Installation">85.3.6
Installation</a></li>
- </ul></li>
- <li><a name="toc-SEE-ALSO-44" href="#perlutil-SEE-ALSO">85.4 SEE
ALSO</a></li>
- </ul></li>
- <li><a name="toc-perlvar-1" href="#perlvar">86 perlvar</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-85" href="#perlvar-NAME">86.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-83" href="#perlvar-DESCRIPTION">86.2
DESCRIPTION</a>
- <ul class="no-bullet">
- <li><a name="toc-The-Syntax-of-Variable-Names"
href="#perlvar-The-Syntax-of-Variable-Names">86.2.1 The Syntax of Variable
Names</a></li>
- </ul></li>
- <li><a name="toc-SPECIAL-VARIABLES" href="#perlvar-SPECIAL-VARIABLES">86.3
SPECIAL VARIABLES</a>
- <ul class="no-bullet">
- <li><a name="toc-General-Variables"
href="#perlvar-General-Variables">86.3.1 General Variables</a></li>
- <li><a name="toc-Variables-related-to-regular-expressions"
href="#perlvar-Variables-related-to-regular-expressions">86.3.2 Variables
related to regular expressions</a>
- <ul class="no-bullet">
- <li><a name="toc-Performance-issues"
href="#perlvar-Performance-issues">86.3.2.1 Performance issues</a></li>
- </ul></li>
- <li><a name="toc-Variables-related-to-filehandles"
href="#perlvar-Variables-related-to-filehandles">86.3.3 Variables related to
filehandles</a>
- <ul class="no-bullet">
- <li><a name="toc-Variables-related-to-formats"
href="#perlvar-Variables-related-to-formats">86.3.3.1 Variables related to
formats</a></li>
- </ul></li>
- <li><a name="toc-Error-Variables" href="#perlvar-Error-Variables">86.3.4
Error Variables</a></li>
- <li><a name="toc-Variables-related-to-the-interpreter-state"
href="#perlvar-Variables-related-to-the-interpreter-state">86.3.5 Variables
related to the interpreter state</a></li>
- <li><a name="toc-Deprecated-and-removed-variables"
href="#perlvar-Deprecated-and-removed-variables">86.3.6 Deprecated and removed
variables</a></li>
- </ul></li>
- </ul></li>
- <li><a name="toc-perlvms-1" href="#perlvms">87 perlvms</a>
- <ul class="no-bullet">
- <li><a name="toc-NAME-86" href="#perlvms-NAME">87.1 NAME</a></li>
- <li><a name="toc-DESCRIPTION-84" href="#perlvms-DESCRIPTION">87.2
DESCRIPTION</a></li>
- <li><a name="toc-Installation-1" href="#perlvms-Installation">87.3
Installation</a></li>
- <li><a name="toc-Organization-of-Perl-Images"
href="#perlvms-Organization-of-Perl-Images">87.4 Organization of Perl Images</a>
- <ul class="no-bullet">
- <li><a name="toc-Core-Images" href="#perlvms-Core-Images">87.4.1 Core
Images</a></li>
- <li><a name="toc-Perl-Extensions" href="#perlvms-Perl-Extensions">87.4.2
Perl Extensions</a></li>
- <li><a name="toc-Installing-static-extensions"
href="#perlvms-Installing-static-extensions">87.4.3 Installing static
extensions</a></li>
- <li><a name="toc-Installing-dynamic-extensions"
href="#perlvms-Installing-dynamic-extensions">87.4.4 Installing dynamic
extensions</a></li>
- </ul></li>
- <li><a name="toc-File-specifications"
href="#perlvms-File-specifications">87.5 File specifications</a>
- <ul class="no-bullet">
- <li><a name="toc-Syntax-1" href="#perlvms-Syntax">87.5.1 Syntax</a></li>
- <li><a name="toc-Filename-Case" href="#perlvms-Filename-Case">87.5.2
Filename Case</a></li>
- <li><a name="toc-Symbolic-Links" href="#perlvms-Symbolic-Links">87.5.3
Symbolic Links</a></li>
- <li><a name="toc-Wildcard-expansion"
href="#perlvms-Wildcard-expansion">87.5.4 Wildcard expansion</a></li>
- <li><a name="toc-Pipes" href="#perlvms-Pipes">87.5.5 Pipes</a></li>
- </ul></li>
- <li><a name="toc-PERL5LIB-and-PERLLIB"
href="#perlvms-PERL5LIB-and-PERLLIB">87.6 PERL5LIB and PERLLIB</a></li>
- <li><a name="toc-The-Perl-Forked-Debugger"
href="#perlvms-The-Perl-Forked-Debugger">87.7 The Perl Forked Debugger</a></li>
- <li><a name="toc-PERL_005fVMS_005fEXCEPTION_005fDEBUG"
href="#perlvms-PERL_005fVMS_005fEXCEPTION_005fDEBUG">87.8
PERL_VMS_EXCEPTION_DEBUG</a></li>
- <li><a name="toc-Command-line" href="#perlvms-Command-line">87.9 Command
line</a>
- <ul class="no-bullet">
- <li><a name="toc-I_002fO-redirection-and-backgrounding"
href="#perlvms-I_002fO-redirection-and-backgrounding">87.9.1 I/O redirection
and backgrounding</a></li>
- <li><a name="toc-Command-line-switches"
href="#perlvms-Command-line-switches">87.9.2 Command line switches</a></li>
- </ul></li>
- <li><a name="toc-Perl-functions" href="#perlvms-Perl-functions">87.10 Perl
functions</a></li>
- <li><a name="toc-Perl-variables" href="#perlvms-Perl-variables">87.11 Perl
variables</a></li>
- <li><a name="toc-Standard-modules-with-VMS_002dspecific-differences"
href="#perlvms-Standard-modules-with-VMS_002dspecific-differences">87.12
Standard modules with VMS-specific differences</a>
- <ul class="no-bullet">
- <li><a name="toc-SDBM_005fFile" href="#perlvms-SDBM_005fFile">87.12.1
SDBM_File</a></li>
- </ul></li>
- <li><a name="toc-Revision-date" href="#perlvms-Revision-date">87.13
Revision date</a></li>
- <li><a name="toc-AUTHOR-31" href="#perlvms-AUTHOR">87.14 AUTHOR</a></li>
- </ul></li>
-</ul>
-</div>
-
-
-<a name="Top"></a>
-<div class="header">
-<p>
-Next: <a href="#perl" accesskey="n" rel="next">perl</a>, Up: <a
href="dir.html#Top" accesskey="u" rel="up">(dir)</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Perl-pod-documentation"></a>
-<h1 class="top">Perl pod documentation</h1>
-
-<p>This translation of the Perl documentation
-(<a href="http://perldoc.perl.org";>http://perldoc.perl.org</a>) from POD to
Texinfo is not official,
-and not endorsed by the Perl developers (indeed, they haven’t seen
-it). It was created by the GNU Texinfo developers because they found
-it useful to have the Perl documentation available in Info and other
-formats, and thought they would share the results. Suggestions welcome.
-</p>
-<p>This is created entirely by the Texinfo tools; see the
-<a
href="http://svn.savannah.gnu.org/viewvc/trunk/contrib/perldoc-all/?root=texinfo";><samp>contrib/perldoc-all</samp></a>
directory in the Texinfo sources for the
-procedure used. The output is available at
-<a
href="http://www.gnu.org/software/perl/manual";>http://www.gnu.org/software/perl/manual</a>.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perl"
accesskey="1">perl</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlapio"
accesskey="2">perlapio</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlartistic"
accesskey="3">perlartistic</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlbook"
accesskey="4">perlbook</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlboot"
accesskey="5">perlboot</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlbot"
accesskey="6">perlbot</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall"
accesskey="7">perlcall</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcheat"
accesskey="8">perlcheat</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlclib"
accesskey="9">perlclib</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcommunity">perlcommunity</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata">perldata</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldbmfilter">perldbmfilter</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts">perldebguts</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut">perldebtut</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug">perldebug</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldiag">perldiag</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc">perldsc</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldtrace">perldtrace</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic">perlebcdic</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed">perlembed</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlexperiment">perlexperiment</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter">perlfilter</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfork">perlfork</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform">perlform</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfunc">perlfunc</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit">perlgit</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgpl">perlgpl</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts">perlguts</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack">perlhack</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips">perlhacktips</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktut">perlhacktut</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhist">perlhist</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp">perlinterp</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro">perlintro</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol">perliol</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc">perlipc</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllexwarn">perllexwarn</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale">perllocale</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllol">perllol</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmod">perlmod</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodinstall">perlmodinstall</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle">perlmodstyle</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmroapi">perlmroapi</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnewmod">perlnewmod</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnumber">perlnumber</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj">perlobj</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut">perlootut</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop">perlop</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlopentut">perlopentut</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut">perlpacktut</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf">perlperf</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpod">perlpod</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec">perlpodspec</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodstyle">perlpodstyle</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy">perlpolicy</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport">perlport</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpragma">perlpragma</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre">perlre</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi">perlreapi</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash">perlrebackslash</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass">perlrecharclass</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref">perlref</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut">perlreftut</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts">perlreguts</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrepository">perlrepository</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick">perlrequick</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref">perlreref</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut">perlretut</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrun">perlrun</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec">perlsec</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsource">perlsource</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlstyle">perlstyle</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub">perlsub</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn">perlsyn</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut">perlthrtut</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltie">perltie</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltodo">perltodo</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltooc">perltooc</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltoot">perltoot</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltrap">perltrap</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode">perlunicode</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq">perlunifaq</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro">perluniintro</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut">perlunitut</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlutil">perlutil</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvar">perlvar</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms">perlvms</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-</pre></th></tr><tr><th colspan="3" align="left" valign="top"><pre
class="menu-comment"> — The Detailed Node Listing —
-
-perl
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perl-NAME">perl NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-SYNOPSIS">perl
SYNOPSIS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-GETTING-HELP">perl
GETTING HELP</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-DESCRIPTION">perl
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-AVAILABILITY">perl
AVAILABILITY</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-ENVIRONMENT">perl
ENVIRONMENT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-AUTHOR">perl
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-FILES">perl
FILES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-SEE-ALSO">perl SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-DIAGNOSTICS">perl
DIAGNOSTICS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-BUGS">perl
BUGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-NOTES">perl
NOTES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-GETTING HELP
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perl-Overview">perl Overview</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-Tutorials">perl
Tutorials</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-Reference-Manual">perl
Reference Manual</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perl-Internals-and-C-Language-Interface">perl Internals and C Language
Interface</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-Miscellaneous">perl
Miscellaneous</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perl-Language_002dSpecific">perl
Language-Specific</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perl-Platform_002dSpecific">perl
Platform-Specific</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perl-Stubs-for-Deleted-Documents">perl Stubs for Deleted
Documents</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlapio
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlapio-NAME">perlapio NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlapio-SYNOPSIS">perlapio
SYNOPSIS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlapio-DESCRIPTION">perlapio
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlapio-Co_002dexistence-with-stdio">perlapio Co-existence with
stdio</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlapio-_0022Fast-gets_0022-Functions">perlapio "Fast gets"
Functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlapio-Other-Functions">perlapio Other
Functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlartistic
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlartistic-NAME">perlartistic NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlartistic-SYNOPSIS">perlartistic
SYNOPSIS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlartistic-DESCRIPTION">perlartistic
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlartistic-The-_0022Artistic-License_0022">perlartistic The
"Artistic License"</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-The "Artistic License"
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlartistic-Preamble">perlartistic
Preamble</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlartistic-Definitions">perlartistic
Definitions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlartistic-Conditions">perlartistic
Conditions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlbook
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlbook-NAME">perlbook NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlbook-DESCRIPTION">perlbook
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlbook-The-most-popular-books">perlbook The most popular
books</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlbook-References">perlbook
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlbook-Tutorials">perlbook Tutorials</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlbook-Task_002dOriented">perlbook
Task-Oriented</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlbook-Special-Topics">perlbook Special
Topics</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlbook-Free-_0028as-in-beer_0029-books">perlbook Free (as in beer)
books</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlbook-Other-interesting_002c-non_002dPerl-books">perlbook Other
interesting, non-Perl books</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlbook-A-note-on-freshness">perlbook A note on
freshness</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlbook-Get-your-book-listed">perlbook Get your book
listed</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlboot
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlboot-NAME">perlboot NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlboot-DESCRIPTION">perlboot
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlbot
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlbot-NAME">perlbot NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlbot-DESCRIPTION">perlbot
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlcall
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlcall-NAME">perlcall NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-DESCRIPTION">perlcall
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-THE-CALL_005f-FUNCTIONS">perlcall THE CALL_
FUNCTIONS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-FLAG-VALUES">perlcall FLAG
VALUES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-EXAMPLES">perlcall
EXAMPLES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-LIGHTWEIGHT-CALLBACKS">perlcall LIGHTWEIGHT
CALLBACKS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-SEE-ALSO">perlcall
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-AUTHOR">perlcall
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-DATE">perlcall
DATE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-FLAG VALUES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlcall-G_005fVOID">perlcall G_VOID</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-G_005fSCALAR">perlcall
G_SCALAR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-G_005fARRAY">perlcall G_ARRAY</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-G_005fDISCARD">perlcall
G_DISCARD</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-G_005fNOARGS">perlcall
G_NOARGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-G_005fEVAL">perlcall G_EVAL</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-G_005fKEEPERR">perlcall
G_KEEPERR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Determining-the-Context">perlcall Determining the
Context</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-EXAMPLES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlcall-No-Parameters_002c-Nothing-Returned">perlcall No Parameters,
Nothing Returned</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Passing-Parameters">perlcall Passing
Parameters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Returning-a-Scalar">perlcall Returning a
Scalar</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Returning-a-List-of-Values">perlcall Returning a List of
Values</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Returning-a-List-in-a-Scalar-Context">perlcall Returning a List
in a Scalar Context</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Returning-Data-from-Perl-via-the-Parameter-List">perlcall
Returning Data from Perl via the Parameter
List</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Using-G_005fEVAL">perlcall Using
G_EVAL</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Using-G_005fKEEPERR">perlcall Using
G_KEEPERR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Using-call_005fsv">perlcall Using
call_sv</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Using-call_005fargv">perlcall Using
call_argv</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Using-call_005fmethod">perlcall Using
call_method</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Using-GIMME_005fV">perlcall Using
GIMME_V</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Using-Perl-to-Dispose-of-Temporaries">perlcall Using Perl to
Dispose of Temporaries</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Strategies-for-Storing-Callback-Context-Information">perlcall
Strategies for Storing Callback Context
Information</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Alternate-Stack-Manipulation">perlcall Alternate Stack
Manipulation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Creating-and-Calling-an-Anonymous-Subroutine-in-C">perlcall
Creating and Calling an Anonymous Subroutine in
C</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlcheat
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlcheat-NAME">perlcheat NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcheat-DESCRIPTION">perlcheat
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcheat-ACKNOWLEDGEMENTS">perlcheat
ACKNOWLEDGEMENTS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcheat-AUTHOR">perlcheat
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcheat-SEE-ALSO">perlcheat SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlcheat-The-sheet">perlcheat The
sheet</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlclib
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlclib-NAME">perlclib NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlclib-DESCRIPTION">perlclib
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlclib-SEE-ALSO">perlclib
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlclib-Conventions">perlclib
Conventions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlclib-File-Operations">perlclib File
Operations</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlclib-File-Input-and-Output">perlclib File Input and
Output</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlclib-File-Positioning">perlclib File
Positioning</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlclib-Memory-Management-and-String-Handling">perlclib Memory
Management and String Handling</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlclib-Character-Class-Tests">perlclib Character Class
Tests</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlclib-stdlib_002eh-functions">perlclib <samp>stdlib.h</samp>
functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlclib-Miscellaneous-functions">perlclib Miscellaneous
functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlcommunity
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlcommunity-NAME">perlcommunity NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcommunity-DESCRIPTION">perlcommunity
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcommunity-AUTHOR">perlcommunity
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlcommunity-Where-to-Find-the-Community">perlcommunity Where to Find
the Community</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcommunity-Mailing-Lists-and-Newsgroups">perlcommunity Mailing Lists
and Newsgroups</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcommunity-IRC">perlcommunity IRC</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcommunity-Websites">perlcommunity
Websites</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcommunity-User-Groups">perlcommunity User
Groups</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcommunity-Workshops">perlcommunity
Workshops</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcommunity-Hackathons">perlcommunity
Hackathons</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcommunity-Conventions">perlcommunity
Conventions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcommunity-Calendar-of-Perl-Events">perlcommunity Calendar of Perl
Events</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Websites
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlcommunity-News-sites">perlcommunity News
sites</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcommunity-Forums">perlcommunity
Forums</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perldata
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldata-NAME">perldata NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-DESCRIPTION">perldata
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldata-SEE-ALSO">perldata
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldata-Variable-names">perldata Variable
names</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Identifier-parsing">perldata Identifier
parsing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldata-Context">perldata
Context</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Scalar-values">perldata Scalar
values</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Scalar-value-constructors">perldata Scalar value
constructors</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-List-value-constructors">perldata List value
constructors</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Subscripts">perldata
Subscripts</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Multi_002ddimensional-array-emulation">perldata
Multi-dimensional array emulation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldata-Slices">perldata
Slices</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Typeglobs-and-Filehandles">perldata Typeglobs and
Filehandles</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Scalar value constructors
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldata-Special-floating-point_003a-infinity-_0028Inf_0029-and-not_002da_002dnumber-_0028NaN_0029">perldata
Special floating point: infinity (Inf) and not-a-number
(NaN)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Version-Strings">perldata Version
Strings</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Special-Literals">perldata Special
Literals</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Barewords">perldata Barewords</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Array-Interpolation">perldata Array
Interpolation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Slices
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldata-Key_002fValue-Hash-Slices">perldata Key/Value Hash
Slices</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Index_002fValue-Array-Slices">perldata Index/Value Array
Slices</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perldbmfilter
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldbmfilter-NAME">perldbmfilter NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldbmfilter-SYNOPSIS">perldbmfilter
SYNOPSIS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldbmfilter-DESCRIPTION">perldbmfilter
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldbmfilter-SEE-ALSO">perldbmfilter SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldbmfilter-AUTHOR">perldbmfilter
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldbmfilter-The-Filter">perldbmfilter The
Filter</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldbmfilter-An-Example_003a-the-NULL-termination-problem_002e">perldbmfilter
An Example: the NULL termination problem.</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldbmfilter-Another-Example_003a-Key-is-a-C-int_002e">perldbmfilter
Another Example: Key is a C int.</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perldebguts
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldebguts-NAME">perldebguts NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-DESCRIPTION">perldebguts
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Debugger-Internals">perldebguts Debugger
Internals</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Frame-Listing-Output-Examples">perldebguts Frame Listing
Output Examples</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Debugging-Regular-Expressions">perldebguts Debugging Regular
Expressions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Debugging-Perl-Memory-Usage">perldebguts Debugging Perl
Memory Usage</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-SEE-ALSO">perldebguts SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Debugger Internals
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldebguts-Writing-Your-Own-Debugger">perldebguts Writing Your Own
Debugger</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Writing Your Own Debugger
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldebguts-Environment-Variables">perldebguts Environment
Variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Debugger-Internal-Variables">perldebguts Debugger Internal
Variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Debugger-Customization-Functions">perldebguts Debugger
Customization Functions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Debugging Regular Expressions
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldebguts-Compile_002dtime-Output">perldebguts Compile-time
Output</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Types-of-Nodes">perldebguts Types of
Nodes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Run_002dtime-Output">perldebguts Run-time
Output</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Debugging Perl Memory Usage
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldebguts-Using-_0024ENV_007bPERL_005fDEBUG_005fMSTATS_007d">perldebguts
Using <code>$ENV{PERL_DEBUG_MSTATS}</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perldebtut
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldebtut-NAME">perldebtut NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-DESCRIPTION">perldebtut
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-use-strict">perldebtut use
strict</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-Looking-at-data-and-_002dw-and-v">perldebtut Looking at data
and -w and v</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebtut-help">perldebtut
help</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-Stepping-through-code">perldebtut Stepping through
code</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-Placeholder-for-a_002c-w_002c-t_002c-T">perldebtut
Placeholder for a, w, t, T</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-REGULAR-EXPRESSIONS">perldebtut REGULAR
EXPRESSIONS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-OUTPUT-TIPS">perldebtut OUTPUT
TIPS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebtut-CGI">perldebtut
CGI</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebtut-GUIs">perldebtut
GUIs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-SUMMARY">perldebtut SUMMARY</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-SEE-ALSO">perldebtut SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-AUTHOR">perldebtut AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-CONTRIBUTORS">perldebtut
CONTRIBUTORS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perldebug
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldebug-NAME">perldebug NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-DESCRIPTION">perldebug
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-The-Perl-Debugger">perldebug The Perl
Debugger</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Debugging-Regular-Expressions">perldebug Debugging Regular
Expressions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Debugging-Memory-Usage">perldebug Debugging Memory
Usage</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-SEE-ALSO">perldebug SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebug-BUGS">perldebug
BUGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-The Perl Debugger
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldebug-Calling-the-Debugger">perldebug Calling the
Debugger</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Debugger-Commands">perldebug Debugger
Commands</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Configurable-Options">perldebug Configurable
Options</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Debugger-Input_002fOutput">perldebug Debugger
Input/Output</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Debugging-Compile_002dTime-Statements">perldebug Debugging
Compile-Time Statements</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Debugger-Customization">perldebug Debugger
Customization</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Readline-Support-_002f-History-in-the-Debugger">perldebug
Readline Support / History in the Debugger</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Editor-Support-for-Debugging">perldebug Editor Support for
Debugging</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-The-Perl-Profiler">perldebug The Perl
Profiler</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perldiag
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldiag-NAME">perldiag NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldiag-DESCRIPTION">perldiag
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldiag-SEE-ALSO">perldiag
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perldsc
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldsc-NAME">perldsc NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-DESCRIPTION">perldsc
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldsc-REFERENCES">perldsc
REFERENCES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-COMMON-MISTAKES">perldsc COMMON
MISTAKES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-CAVEAT-ON-PRECEDENCE">perldsc CAVEAT ON
PRECEDENCE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-WHY-YOU-SHOULD-ALWAYS-use-strict">perldsc WHY YOU SHOULD ALWAYS
<code>use strict</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldsc-DEBUGGING">perldsc
DEBUGGING</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-CODE-EXAMPLES">perldsc CODE
EXAMPLES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-ARRAYS-OF-ARRAYS">perldsc ARRAYS OF
ARRAYS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-HASHES-OF-ARRAYS">perldsc HASHES OF
ARRAYS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-ARRAYS-OF-HASHES">perldsc ARRAYS OF
HASHES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-HASHES-OF-HASHES">perldsc HASHES OF
HASHES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-MORE-ELABORATE-RECORDS">perldsc MORE ELABORATE
RECORDS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Database-Ties">perldsc Database
Ties</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldsc-SEE-ALSO">perldsc
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldsc-AUTHOR">perldsc
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-ARRAYS OF ARRAYS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldsc-Declaration-of-an-ARRAY-OF-ARRAYS">perldsc Declaration of an
ARRAY OF ARRAYS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Generation-of-an-ARRAY-OF-ARRAYS">perldsc Generation of an ARRAY
OF ARRAYS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Access-and-Printing-of-an-ARRAY-OF-ARRAYS">perldsc Access and
Printing of an ARRAY OF ARRAYS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-HASHES OF ARRAYS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldsc-Declaration-of-a-HASH-OF-ARRAYS">perldsc Declaration of a HASH
OF ARRAYS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Generation-of-a-HASH-OF-ARRAYS">perldsc Generation of a HASH OF
ARRAYS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Access-and-Printing-of-a-HASH-OF-ARRAYS">perldsc Access and
Printing of a HASH OF ARRAYS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-ARRAYS OF HASHES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldsc-Declaration-of-an-ARRAY-OF-HASHES">perldsc Declaration of an
ARRAY OF HASHES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Generation-of-an-ARRAY-OF-HASHES">perldsc Generation of an ARRAY
OF HASHES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Access-and-Printing-of-an-ARRAY-OF-HASHES">perldsc Access and
Printing of an ARRAY OF HASHES</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-HASHES OF HASHES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldsc-Declaration-of-a-HASH-OF-HASHES">perldsc Declaration of a HASH
OF HASHES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Generation-of-a-HASH-OF-HASHES">perldsc Generation of a HASH OF
HASHES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Access-and-Printing-of-a-HASH-OF-HASHES">perldsc Access and
Printing of a HASH OF HASHES</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-MORE ELABORATE RECORDS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldsc-Declaration-of-MORE-ELABORATE-RECORDS">perldsc Declaration of
MORE ELABORATE RECORDS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Declaration-of-a-HASH-OF-COMPLEX-RECORDS">perldsc Declaration of
a HASH OF COMPLEX RECORDS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Generation-of-a-HASH-OF-COMPLEX-RECORDS">perldsc Generation of a
HASH OF COMPLEX RECORDS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perldtrace
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perldtrace-NAME">perldtrace NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldtrace-SYNOPSIS">perldtrace
SYNOPSIS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldtrace-DESCRIPTION">perldtrace
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldtrace-HISTORY">perldtrace HISTORY</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldtrace-PROBES">perldtrace PROBES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldtrace-EXAMPLES">perldtrace
EXAMPLES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldtrace-REFERENCES">perldtrace
REFERENCES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldtrace-SEE-ALSO">perldtrace SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldtrace-AUTHORS">perldtrace AUTHORS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlebcdic
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlebcdic-NAME">perlebcdic NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-DESCRIPTION">perlebcdic
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-COMMON-CHARACTER-CODE-SETS">perlebcdic COMMON CHARACTER CODE
SETS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-SINGLE-OCTET-TABLES">perlebcdic SINGLE OCTET
TABLES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-IDENTIFYING-CHARACTER-CODE-SETS">perlebcdic IDENTIFYING
CHARACTER CODE SETS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-CONVERSIONS">perlebcdic
CONVERSIONS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-OPERATOR-DIFFERENCES">perlebcdic OPERATOR
DIFFERENCES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-FUNCTION-DIFFERENCES">perlebcdic FUNCTION
DIFFERENCES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-REGULAR-EXPRESSION-DIFFERENCES">perlebcdic REGULAR EXPRESSION
DIFFERENCES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-SOCKETS">perlebcdic SOCKETS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-SORTING">perlebcdic SORTING</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-TRANSFORMATION-FORMATS">perlebcdic TRANSFORMATION
FORMATS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Hashing-order-and-checksums">perlebcdic Hashing order and
checksums</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-I18N-AND-L10N">perlebcdic I18N AND
L10N</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-MULTI_002dOCTET-CHARACTER-SETS">perlebcdic MULTI-OCTET
CHARACTER SETS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-OS-ISSUES">perlebcdic OS
ISSUES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlebcdic-BUGS">perlebcdic
BUGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-SEE-ALSO">perlebcdic SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-REFERENCES">perlebcdic
REFERENCES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-HISTORY">perlebcdic HISTORY</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-AUTHOR">perlebcdic AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-COMMON CHARACTER CODE SETS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlebcdic-ASCII">perlebcdic ASCII</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-ISO-8859">perlebcdic ISO
8859</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Latin-1-_0028ISO-8859_002d1_0029">perlebcdic Latin 1 (ISO
8859-1)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-EBCDIC">perlebcdic EBCDIC</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Unicode-code-points-versus-EBCDIC-code-points">perlebcdic
Unicode code points versus EBCDIC code points</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Unicode-and-UTF">perlebcdic Unicode and
UTF</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Using-Encode">perlebcdic Using
Encode</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-EBCDIC
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlebcdic-The-13-variant-characters">perlebcdic The 13 variant
characters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-EBCDIC-code-sets-recognized-by-Perl">perlebcdic EBCDIC code
sets recognized by Perl</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-SINGLE OCTET TABLES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlebcdic-Table-in-hex_002c-sorted-in-1047-order">perlebcdic Table in
hex, sorted in 1047 order</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-CONVERSIONS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlebcdic-utf8_003a_003aunicode_005fto_005fnative_0028_0029-and-utf8_003a_003anative_005fto_005funicode_0028_0029">perlebcdic
<code>utf8::unicode_to_native()</code> and
<code>utf8::native_to_unicode()</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-tr_002f_002f_002f">perlebcdic
tr///</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-iconv">perlebcdic iconv</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-C-RTL">perlebcdic C RTL</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-SORTING
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlebcdic-Ignore-ASCII-vs_002e-EBCDIC-sort-differences_002e">perlebcdic
Ignore ASCII vs. EBCDIC sort differences.</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Use-a-sort-helper-function">perlebcdic Use a sort helper
function</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-MONO-CASE-then-sort-data-_0028for-non_002ddigits_002c-non_002dunderscore_0029">perlebcdic
MONO CASE then sort data (for non-digits,
non-underscore)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Perform-sorting-on-one-type-of-platform-only_002e">perlebcdic
Perform sorting on one type of platform only.</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-TRANSFORMATION FORMATS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlebcdic-URL-decoding-and-encoding">perlebcdic URL decoding and
encoding</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-uu-encoding-and-decoding">perlebcdic uu encoding and
decoding</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Quoted_002dPrintable-encoding-and-decoding">perlebcdic
Quoted-Printable encoding and decoding</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Caesarean-ciphers">perlebcdic Caesarean
ciphers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-OS ISSUES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlebcdic-OS_002f400">perlebcdic
OS/400</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-OS_002f390_002c-z_002fOS">perlebcdic OS/390,
z/OS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-POSIX_002dBC_003f">perlebcdic
POSIX-BC?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlembed
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlembed-NAME">perlembed NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-DESCRIPTION">perlembed
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Hiding-Perl_005f">perlembed Hiding
Perl_</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlembed-MORAL">perlembed
MORAL</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlembed-AUTHOR">perlembed
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-COPYRIGHT">perlembed
COPYRIGHT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlembed-PREAMBLE">perlembed PREAMBLE</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-ROADMAP">perlembed ROADMAP</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Compiling-your-C-program">perlembed Compiling your C
program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Adding-a-Perl-interpreter-to-your-C-program">perlembed Adding
a Perl interpreter to your C program</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Calling-a-Perl-subroutine-from-your-C-program">perlembed
Calling a Perl subroutine from your C program</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Evaluating-a-Perl-statement-from-your-C-program">perlembed
Evaluating a Perl statement from your C
program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Performing-Perl-pattern-matches-and-substitutions-from-your-C-program">perlembed
Performing Perl pattern matches and substitutions from your C
program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Fiddling-with-the-Perl-stack-from-your-C-program">perlembed
Fiddling with the Perl stack from your C
program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Maintaining-a-persistent-interpreter">perlembed Maintaining a
persistent interpreter</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Execution-of-END-blocks">perlembed Execution of END
blocks</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-_00240-assignments">perlembed $0
assignments</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Maintaining-multiple-interpreter-instances">perlembed
Maintaining multiple interpreter instances</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Using-Perl-modules_002c-which-themselves-use-C-libraries_002c-from-your-C-program">perlembed
Using Perl modules, which themselves use C libraries, from your C
program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Using-embedded-Perl-with-POSIX-locales">perlembed Using
embedded Perl with POSIX locales</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlexperiment
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlexperiment-NAME">perlexperiment
NAME</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlexperiment-DESCRIPTION">perlexperiment
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlexperiment-SEE-ALSO">perlexperiment SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlexperiment-AUTHORS">perlexperiment
AUTHORS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlexperiment-COPYRIGHT">perlexperiment
COPYRIGHT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlexperiment-LICENSE">perlexperiment
LICENSE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlexperiment-Current-experiments">perlexperiment Current
experiments</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlexperiment-Accepted-features">perlexperiment Accepted
features</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlexperiment-Removed-features">perlexperiment Removed
features</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlfilter
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlfilter-NAME">perlfilter NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-DESCRIPTION">perlfilter
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-CONCEPTS">perlfilter
CONCEPTS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-USING-FILTERS">perlfilter USING
FILTERS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-WRITING-A-SOURCE-FILTER">perlfilter WRITING A SOURCE
FILTER</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-WRITING-A-SOURCE-FILTER-IN-C">perlfilter WRITING A SOURCE
FILTER IN C</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-CREATING-A-SOURCE-FILTER-AS-A-SEPARATE-EXECUTABLE">perlfilter
CREATING A SOURCE FILTER AS A SEPARATE
EXECUTABLE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-WRITING-A-SOURCE-FILTER-IN-PERL">perlfilter WRITING A SOURCE
FILTER IN PERL</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-USING-CONTEXT_003a-THE-DEBUG-FILTER">perlfilter USING
CONTEXT: THE DEBUG FILTER</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-CONCLUSION">perlfilter
CONCLUSION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-LIMITATIONS">perlfilter
LIMITATIONS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-THINGS-TO-LOOK-OUT-FOR">perlfilter THINGS TO LOOK OUT
FOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-REQUIREMENTS">perlfilter
REQUIREMENTS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-AUTHOR">perlfilter AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-Copyrights">perlfilter
Copyrights</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlfork
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlfork-NAME">perlfork NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfork-SYNOPSIS">perlfork
SYNOPSIS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfork-DESCRIPTION">perlfork
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfork-CAVEATS-AND-LIMITATIONS">perlfork CAVEATS AND
LIMITATIONS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfork-PORTABILITY-CAVEATS">perlfork PORTABILITY
CAVEATS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfork-BUGS">perlfork
BUGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfork-AUTHOR">perlfork
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfork-SEE-ALSO">perlfork
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlfork-Behavior-of-other-Perl-features-in-forked-pseudo_002dprocesses">perlfork
Behavior of other Perl features in forked
pseudo-processes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfork-Resource-limits">perlfork Resource
limits</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfork-Killing-the-parent-process">perlfork Killing the parent
process</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfork-Lifetime-of-the-parent-process-and-pseudo_002dprocesses">perlfork
Lifetime of the parent process and
pseudo-processes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlform
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlform-NAME">perlform NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-DESCRIPTION">perlform
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlform-NOTES">perlform
NOTES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlform-WARNINGS">perlform
WARNINGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlform-Text-Fields">perlform Text
Fields</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-Numeric-Fields">perlform Numeric
Fields</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-The-Field-_0040_002a-for-Variable_002dWidth-Multi_002dLine-Text">perlform
The Field @* for Variable-Width Multi-Line
Text</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-The-Field-_005e_002a-for-Variable_002dWidth-One_002dline_002dat_002da_002dtime-Text">perlform
The Field ^* for Variable-Width One-line-at-a-time
Text</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-Specifying-Values">perlform Specifying
Values</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-Using-Fill-Mode">perlform Using Fill
Mode</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-Suppressing-Lines-Where-All-Fields-Are-Void">perlform
Suppressing Lines Where All Fields Are Void</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-Repeating-Format-Lines">perlform Repeating Format
Lines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-Top-of-Form-Processing">perlform Top of Form
Processing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-Format-Variables">perlform Format
Variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-NOTES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlform-Footers">perlform Footers</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-Accessing-Formatting-Internals">perlform Accessing Formatting
Internals</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlfunc
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlfunc-NAME">perlfunc NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfunc-DESCRIPTION">perlfunc
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlfunc-Perl-Functions-by-Category">perlfunc Perl Functions by
Category</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfunc-Portability">perlfunc
Portability</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfunc-Alphabetical-Listing-of-Perl-Functions">perlfunc Alphabetical
Listing of Perl Functions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfunc-Non_002dfunction-Keywords-by-Cross_002dreference">perlfunc
Non-function Keywords by Cross-reference</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Non-function Keywords by Cross-reference
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlfunc-perldata">perlfunc perldata</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfunc-perlmod">perlfunc
perlmod</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfunc-perlobj">perlfunc
perlobj</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfunc-perlop">perlfunc
perlop</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfunc-perlsub">perlfunc
perlsub</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfunc-perlsyn">perlfunc
perlsyn</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlgit
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlgit-NAME">perlgit NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-DESCRIPTION">perlgit
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-CLONING-THE-REPOSITORY">perlgit CLONING THE
REPOSITORY</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-WORKING-WITH-THE-REPOSITORY">perlgit WORKING WITH THE
REPOSITORY</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-WRITE-ACCESS-TO-THE-GIT-REPOSITORY">perlgit WRITE ACCESS TO THE
GIT REPOSITORY</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-WORKING WITH THE REPOSITORY
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlgit-Finding-out-your-status">perlgit Finding out your
status</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Patch-workflow">perlgit Patch
workflow</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Committing-your-changes">perlgit Committing your
changes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Sending-patch-emails">perlgit Sending patch
emails</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-A-note-on-derived-files">perlgit A note on derived
files</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Cleaning-a-working-directory">perlgit Cleaning a working
directory</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlgit-Bisecting">perlgit
Bisecting</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Topic-branches-and-rewriting-history">perlgit Topic branches and
rewriting history</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlgit-Grafts">perlgit
Grafts</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-WRITE ACCESS TO THE GIT REPOSITORY
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlgit-Accepting-a-patch">perlgit Accepting a
patch</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Committing-to-blead">perlgit Committing to
blead</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-On-merging-and-rebasing">perlgit On merging and
rebasing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Committing-to-maintenance-versions">perlgit Committing to
maintenance versions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Merging-from-a-branch-via-GitHub">perlgit Merging from a branch
via GitHub</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Using-a-smoke_002dme-branch-to-test-changes">perlgit Using a
smoke-me branch to test changes</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-A-note-on-camel-and-dromedary">perlgit A note on camel and
dromedary</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlgpl
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlgpl-NAME">perlgpl NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlgpl-SYNOPSIS">perlgpl
SYNOPSIS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgpl-DESCRIPTION">perlgpl
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgpl-GNU-GENERAL-PUBLIC-LICENSE">perlgpl GNU GENERAL PUBLIC
LICENSE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlguts
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlguts-NAME">perlguts NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-DESCRIPTION">perlguts
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Variables">perlguts Variables</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Subroutines">perlguts
Subroutines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Memory-Allocation">perlguts Memory
Allocation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-PerlIO">perlguts
PerlIO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Compiled-code">perlguts Compiled
code</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Examining-internal-data-structures-with-the-dump-functions">perlguts
Examining internal data structures with the <code>dump</code>
functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-How-multiple-interpreters-and-concurrency-are-supported">perlguts
How multiple interpreters and concurrency are
supported</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Internal-Functions">perlguts Internal
Functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Unicode-Support">perlguts Unicode
Support</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Custom-Operators">perlguts Custom
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-AUTHORS">perlguts
AUTHORS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-SEE-ALSO">perlguts
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Variables
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlguts-Datatypes">perlguts Datatypes</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-What-is-an-_0022IV_0022_003f">perlguts What is an
"IV"?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Working-with-SVs">perlguts Working with
SVs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-Offsets">perlguts
Offsets</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-What_0027s-Really-Stored-in-an-SV_003f">perlguts What's Really
Stored in an SV?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Working-with-AVs">perlguts Working with
AVs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Working-with-HVs">perlguts Working with
HVs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Hash-API-Extensions">perlguts Hash API
Extensions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-AVs_002c-HVs-and-undefined-values">perlguts AVs, HVs and
undefined values</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-References">perlguts
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Blessed-References-and-Class-Objects">perlguts Blessed
References and Class Objects</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Creating-New-Variables">perlguts Creating New
Variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Reference-Counts-and-Mortality">perlguts Reference Counts and
Mortality</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Stashes-and-Globs">perlguts Stashes and
Globs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Double_002dTyped-SVs">perlguts Double-Typed
SVs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Read_002dOnly-Values">perlguts Read-Only
Values</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Copy-on-Write">perlguts Copy on
Write</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Magic-Variables">perlguts Magic
Variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Assigning-Magic">perlguts Assigning
Magic</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Magic-Virtual-Tables">perlguts Magic Virtual
Tables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Finding-Magic">perlguts Finding
Magic</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Understanding-the-Magic-of-Tied-Hashes-and-Arrays">perlguts
Understanding the Magic of Tied Hashes and
Arrays</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Localizing-changes">perlguts Localizing
changes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Subroutines
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlguts-XSUBs-and-the-Argument-Stack">perlguts XSUBs and the Argument
Stack</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Autoloading-with-XSUBs">perlguts Autoloading with
XSUBs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Calling-Perl-Routines-from-within-C-Programs">perlguts Calling
Perl Routines from within C Programs</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Putting-a-C-value-on-Perl-stack">perlguts Putting a C value on
Perl stack</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Scratchpads">perlguts
Scratchpads</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Scratchpads-and-recursion">perlguts Scratchpads and
recursion</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Memory Allocation
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlguts-Allocation">perlguts
Allocation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Reallocation">perlguts
Reallocation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-Moving">perlguts
Moving</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Compiled code
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlguts-Code-tree">perlguts Code tree</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Examining-the-tree">perlguts Examining the
tree</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Compile-pass-1_003a-check-routines">perlguts Compile pass 1:
check routines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Compile-pass-1a_003a-constant-folding">perlguts Compile pass
1a: constant folding</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Compile-pass-2_003a-context-propagation">perlguts Compile pass
2: context propagation</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Compile-pass-3_003a-peephole-optimization">perlguts Compile
pass 3: peephole optimization</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Pluggable-runops">perlguts Pluggable
runops</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Compile_002dtime-scope-hooks">perlguts Compile-time scope
hooks</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-How multiple interpreters and concurrency are supported
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlguts-Background-and-PERL_005fIMPLICIT_005fCONTEXT">perlguts
Background and PERL_IMPLICIT_CONTEXT</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-So-what-happened-to-dTHR_003f">perlguts So what happened to
dTHR?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-How-do-I-use-all-this-in-extensions_003f">perlguts How do I use
all this in extensions?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Should-I-do-anything-special-if-I-call-perl-from-multiple-threads_003f">perlguts
Should I do anything special if I call perl from multiple
threads?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Future-Plans-and-PERL_005fIMPLICIT_005fSYS">perlguts Future
Plans and PERL_IMPLICIT_SYS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Internal Functions
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlguts-Formatted-Printing-of-IVs_002c-UVs_002c-and-NVs">perlguts
Formatted Printing of IVs, UVs, and NVs</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Pointer_002dTo_002dInteger-and-Integer_002dTo_002dPointer">perlguts
Pointer-To-Integer and Integer-To-Pointer</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Exception-Handling">perlguts Exception
Handling</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Source-Documentation">perlguts Source
Documentation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Backwards-compatibility">perlguts Backwards
compatibility</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Unicode Support
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlguts-What-is-Unicode_002c-anyway_003f">perlguts What
<strong>is</strong> Unicode, anyway?</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-How-can-I-recognise-a-UTF_002d8-string_003f">perlguts How can I
recognise a UTF-8 string?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-How-does-UTF_002d8-represent-Unicode-characters_003f">perlguts
How does UTF-8 represent Unicode characters?</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-How-does-Perl-store-UTF_002d8-strings_003f">perlguts How does
Perl store UTF-8 strings?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-How-do-I-convert-a-string-to-UTF_002d8_003f">perlguts How do I
convert a string to UTF-8?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-How-do-I-compare-strings_003f">perlguts How do I compare
strings?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Is-there-anything-else-I-need-to-know_003f">perlguts Is there
anything else I need to know?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlhack
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhack-NAME">perlhack NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-DESCRIPTION">perlhack
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-SUPER-QUICK-PATCH-GUIDE">perlhack SUPER QUICK PATCH
GUIDE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-BUG-REPORTING">perlhack BUG
REPORTING</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-PERL-5-PORTERS">perlhack PERL 5
PORTERS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-GETTING-THE-PERL-SOURCE">perlhack GETTING THE PERL
SOURCE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-PATCHING-PERL">perlhack PATCHING
PERL</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhack-TESTING">perlhack
TESTING</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-MORE-READING-FOR-GUTS-HACKERS">perlhack MORE READING FOR GUTS
HACKERS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-CPAN-TESTERS-AND-PERL-SMOKERS">perlhack CPAN TESTERS AND PERL
SMOKERS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-WHAT-NEXT_003f">perlhack WHAT
NEXT?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhack-AUTHOR">perlhack
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-PERL 5 PORTERS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhack-perl_002dchanges-mailing-list">perlhack perl-changes mailing
list</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-_0023p5p-on-IRC">perlhack #p5p on
IRC</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-GETTING THE PERL SOURCE
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhack-Read-access-via-Git">perlhack Read access via
Git</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Read-access-via-the-web">perlhack Read access via the
web</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Read-access-via-rsync">perlhack Read access via
rsync</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Write-access-via-git">perlhack Write access via
git</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-PATCHING PERL
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhack-Submitting-patches">perlhack Submitting
patches</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Getting-your-patch-accepted">perlhack Getting your patch
accepted</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Patching-a-core-module">perlhack Patching a core
module</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Updating-perldelta">perlhack Updating
perldelta</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-What-makes-for-a-good-patch_003f">perlhack What makes for a
good patch?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Getting your patch accepted
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhack-Patch-style">perlhack Patch
style</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Commit-message">perlhack Commit
message</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Comments_002c-Comments_002c-Comments">perlhack Comments,
Comments, Comments</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhack-Style">perlhack
Style</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Test-suite">perlhack Test
suite</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-What makes for a good patch?
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhack-Does-the-concept-match-the-general-goals-of-Perl_003f">perlhack
Does the concept match the general goals of
Perl?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Where-is-the-implementation_003f">perlhack Where is the
implementation?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Backwards-compatibility">perlhack Backwards
compatibility</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Could-it-be-a-module-instead_003f">perlhack Could it be a
module instead?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Is-the-feature-generic-enough_003f">perlhack Is the feature
generic enough?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Does-it-potentially-introduce-new-bugs_003f">perlhack Does it
potentially introduce new bugs?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-How-big-is-it_003f">perlhack How big is
it?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Does-it-preclude-other-desirable-features_003f">perlhack Does
it preclude other desirable features?</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Is-the-implementation-robust_003f">perlhack Is the
implementation robust?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Is-the-implementation-generic-enough-to-be-portable_003f">perlhack
Is the implementation generic enough to be
portable?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Is-the-implementation-tested_003f">perlhack Is the
implementation tested?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Is-there-enough-documentation_003f">perlhack Is there enough
documentation?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Is-there-another-way-to-do-it_003f">perlhack Is there another
way to do it?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Does-it-create-too-much-work_003f">perlhack Does it create too
much work?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Patches-speak-louder-than-words">perlhack Patches speak louder
than words</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-TESTING
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhack-Special-make-test-targets">perlhack Special <code>make
test</code> targets</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Parallel-tests">perlhack Parallel
tests</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Running-tests-by-hand">perlhack Running tests by
hand</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Using-t_002fharness-for-testing">perlhack Using
<samp>t/harness</samp> for testing</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Performance-testing">perlhack Performance
testing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Using <samp>t/harness</samp> for testing
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhack-Other-environment-variables-that-may-influence-tests">perlhack
Other environment variables that may influence
tests</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-WHAT NEXT?
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhack-_0022The-Road-goes-ever-on-and-on_002c-down-from-the-door-where-it-began_002e_0022">perlhack
"The Road goes ever on and on, down from the door where it
began."</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Metaphoric-Quotations">perlhack Metaphoric
Quotations</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlhacktips
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhacktips-NAME">perlhacktips NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-DESCRIPTION">perlhacktips
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-COMMON-PROBLEMS">perlhacktips COMMON
PROBLEMS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-DEBUGGING">perlhacktips
DEBUGGING</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-SOURCE-CODE-STATIC-ANALYSIS">perlhacktips SOURCE CODE
STATIC ANALYSIS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-MEMORY-DEBUGGERS">perlhacktips MEMORY
DEBUGGERS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-PROFILING">perlhacktips
PROFILING</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-MISCELLANEOUS-TRICKS">perlhacktips MISCELLANEOUS
TRICKS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-AUTHOR">perlhacktips
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-COMMON PROBLEMS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhacktips-Perl-environment-problems">perlhacktips Perl environment
problems</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Portability-problems">perlhacktips Portability
problems</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Problematic-System-Interfaces">perlhacktips Problematic
System Interfaces</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Security-problems">perlhacktips Security
problems</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DEBUGGING
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhacktips-Poking-at-Perl">perlhacktips Poking at
Perl</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Using-a-source_002dlevel-debugger">perlhacktips Using a
source-level debugger</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-gdb-macro-support">perlhacktips gdb macro
support</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Dumping-Perl-Data-Structures">perlhacktips Dumping Perl
Data Structures</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Using-gdb-to-look-at-specific-parts-of-a-program">perlhacktips
Using gdb to look at specific parts of a
program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Using-gdb-to-look-at-what-the-parser_002flexer-are-doing">perlhacktips
Using gdb to look at what the parser/lexer are
doing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-SOURCE CODE STATIC ANALYSIS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhacktips-lint_002c-splint">perlhacktips lint,
splint</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Coverity">perlhacktips
Coverity</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-cpd-_0028cut_002dand_002dpaste-detector_0029">perlhacktips
cpd (cut-and-paste detector)</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-gcc-warnings">perlhacktips gcc
warnings</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Warnings-of-other-C-compilers">perlhacktips Warnings of
other C compilers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-MEMORY DEBUGGERS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhacktips-valgrind">perlhacktips
valgrind</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-AddressSanitizer">perlhacktips
AddressSanitizer</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-PROFILING
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhacktips-Gprof-Profiling">perlhacktips Gprof
Profiling</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-GCC-gcov-Profiling">perlhacktips GCC gcov
Profiling</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-MISCELLANEOUS TRICKS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhacktips-PERL_005fDESTRUCT_005fLEVEL">perlhacktips
PERL_DESTRUCT_LEVEL</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-PERL_005fMEM_005fLOG">perlhacktips
PERL_MEM_LOG</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-DDD-over-gdb">perlhacktips DDD over
gdb</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-C-backtrace">perlhacktips C
backtrace</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Poison">perlhacktips
Poison</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Read_002donly-optrees">perlhacktips Read-only
optrees</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-When-is-a-bool-not-a-bool_003f">perlhacktips When is a bool
not a bool?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-The-_002ei-Targets">perlhacktips The .i
Targets</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlhacktut
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhacktut-NAME">perlhacktut NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktut-DESCRIPTION">perlhacktut
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktut-EXAMPLE-OF-A-SIMPLE-PATCH">perlhacktut EXAMPLE OF A SIMPLE
PATCH</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktut-AUTHOR">perlhacktut AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-EXAMPLE OF A SIMPLE PATCH
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhacktut-Writing-the-patch">perlhacktut Writing the
patch</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktut-Testing-the-patch">perlhacktut Testing the
patch</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktut-Documenting-the-patch">perlhacktut Documenting the
patch</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktut-Submit">perlhacktut Submit</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlhist
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhist-NAME">perlhist NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhist-DESCRIPTION">perlhist
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhist-INTRODUCTION">perlhist
INTRODUCTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhist-THE-KEEPERS-OF-THE-PUMPKIN">perlhist THE KEEPERS OF THE
PUMPKIN</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhist-THE-RECORDS">perlhist THE
RECORDS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhist-THE-KEEPERS-OF-THE-RECORDS">perlhist THE KEEPERS OF THE
RECORDS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-THE KEEPERS OF THE PUMPKIN
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhist-PUMPKIN_003f">perlhist
PUMPKIN?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-THE RECORDS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhist-SELECTED-RELEASE-SIZES">perlhist SELECTED RELEASE
SIZES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhist-SELECTED-PATCH-SIZES">perlhist SELECTED PATCH
SIZES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-SELECTED PATCH SIZES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlhist-The-patch_002dfree-era">perlhist The patch-free
era</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlinterp
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlinterp-NAME">perlinterp NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-DESCRIPTION">perlinterp
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-ELEMENTS-OF-THE-INTERPRETER">perlinterp ELEMENTS OF THE
INTERPRETER</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-OP-TREES">perlinterp OP
TREES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-STACKS">perlinterp STACKS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-MILLIONS-OF-MACROS">perlinterp MILLIONS OF
MACROS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-FURTHER-READING">perlinterp FURTHER
READING</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-ELEMENTS OF THE INTERPRETER
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlinterp-Startup">perlinterp Startup</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-Parsing">perlinterp Parsing</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-Optimization">perlinterp
Optimization</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-Running">perlinterp Running</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-Exception-handing">perlinterp Exception
handing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-INTERNAL-VARIABLE-TYPES">perlinterp INTERNAL VARIABLE
TYPES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-STACKS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlinterp-Argument-stack">perlinterp Argument
stack</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-Mark-stack">perlinterp Mark
stack</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-Save-stack">perlinterp Save
stack</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlintro
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlintro-NAME">perlintro NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-DESCRIPTION">perlintro
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlintro-AUTHOR">perlintro
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlintro-What-is-Perl_003f">perlintro What is
Perl?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Running-Perl-programs">perlintro Running Perl
programs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Safety-net">perlintro Safety
net</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Basic-syntax-overview">perlintro Basic syntax
overview</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Perl-variable-types">perlintro Perl variable
types</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Variable-scoping">perlintro Variable
scoping</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Conditional-and-looping-constructs">perlintro Conditional and
looping constructs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Builtin-operators-and-functions">perlintro Builtin operators
and functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Files-and-I_002fO">perlintro Files and
I/O</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Regular-expressions">perlintro Regular
expressions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Writing-subroutines">perlintro Writing
subroutines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-OO-Perl">perlintro OO Perl</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Using-Perl-modules">perlintro Using Perl
modules</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perliol
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perliol-NAME">perliol NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perliol-SYNOPSIS">perliol
SYNOPSIS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-DESCRIPTION">perliol
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perliol-TODO">perliol
TODO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perliol-History-and-Background">perliol History and
Background</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Basic-Structure">perliol Basic
Structure</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Layers-vs-Disciplines">perliol Layers vs
Disciplines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Data-Structures">perliol Data
Structures</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Functions-and-Attributes">perliol Functions and
Attributes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Per_002dinstance-Data">perliol Per-instance
Data</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Layers-in-action_002e">perliol Layers in
action.</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Per_002dinstance-flag-bits">perliol Per-instance flag
bits</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Methods-in-Detail">perliol Methods in
Detail</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perliol-Utilities">perliol
Utilities</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Implementing-PerlIO-Layers">perliol Implementing PerlIO
Layers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Core-Layers">perliol Core
Layers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Extension-Layers">perliol Extension
Layers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlipc
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlipc-NAME">perlipc NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-DESCRIPTION">perlipc
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-Signals">perlipc
Signals</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Named-Pipes">perlipc Named
Pipes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Using-open_0028_0029-for-IPC">perlipc Using open() for
IPC</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Sockets_003a-Client_002fServer-Communication">perlipc Sockets:
Client/Server Communication</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-TCP-Clients-with-IO_003a_003aSocket">perlipc TCP Clients with
IO::Socket</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-TCP-Servers-with-IO_003a_003aSocket">perlipc TCP Servers with
IO::Socket</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-UDP_003a-Message-Passing">perlipc UDP: Message
Passing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-SysV-IPC">perlipc
SysV IPC</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-NOTES">perlipc
NOTES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-BUGS">perlipc
BUGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-AUTHOR">perlipc
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-SEE-ALSO">perlipc
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Signals
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlipc-Handling-the-SIGHUP-Signal-in-Daemons">perlipc Handling the
SIGHUP Signal in Daemons</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Deferred-Signals-_0028Safe-Signals_0029">perlipc Deferred
Signals (Safe Signals)</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Using open() for IPC
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlipc-Filehandles">perlipc
Filehandles</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Background-Processes">perlipc Background
Processes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Complete-Dissociation-of-Child-from-Parent">perlipc Complete
Dissociation of Child from Parent</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Safe-Pipe-Opens">perlipc Safe Pipe
Opens</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Avoiding-Pipe-Deadlocks">perlipc Avoiding Pipe
Deadlocks</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Bidirectional-Communication-with-Another-Process">perlipc
Bidirectional Communication with Another
Process</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Bidirectional-Communication-with-Yourself">perlipc Bidirectional
Communication with Yourself</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Sockets: Client/Server Communication
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlipc-Internet-Line-Terminators">perlipc Internet Line
Terminators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Internet-TCP-Clients-and-Servers">perlipc Internet TCP Clients
and Servers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Unix_002dDomain-TCP-Clients-and-Servers">perlipc Unix-Domain TCP
Clients and Servers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-TCP Clients with IO::Socket
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlipc-A-Simple-Client">perlipc A Simple
Client</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-A-Webget-Client">perlipc A Webget
Client</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Interactive-Client-with-IO_003a_003aSocket">perlipc Interactive
Client with IO::Socket</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perllexwarn
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perllexwarn-NAME">perllexwarn NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllexwarn-DESCRIPTION">perllexwarn
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perllocale
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perllocale-NAME">perllocale NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-DESCRIPTION">perllocale
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-WHAT-IS-A-LOCALE">perllocale WHAT IS A
LOCALE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-PREPARING-TO-USE-LOCALES">perllocale PREPARING TO USE
LOCALES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-USING-LOCALES">perllocale USING
LOCALES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-LOCALE-CATEGORIES">perllocale LOCALE
CATEGORIES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-SECURITY">perllocale
SECURITY</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-ENVIRONMENT">perllocale
ENVIRONMENT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-NOTES">perllocale NOTES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Unicode-and-UTF_002d8">perllocale Unicode and
UTF-8</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllocale-BUGS">perllocale
BUGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-SEE-ALSO">perllocale SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-HISTORY">perllocale HISTORY</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-USING LOCALES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perllocale-The-_0022use-locale_0022-pragma">perllocale The
<code>"use locale"</code> pragma</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-The-setlocale-function">perllocale The setlocale
function</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Finding-locales">perllocale Finding
locales</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-LOCALE-PROBLEMS">perllocale LOCALE
PROBLEMS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Testing-for-broken-locales">perllocale Testing for broken
locales</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Temporarily-fixing-locale-problems">perllocale Temporarily
fixing locale problems</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Permanently-fixing-locale-problems">perllocale Permanently
fixing locale problems</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Permanently-fixing-your-system_0027s-locale-configuration">perllocale
Permanently fixing your system's locale
configuration</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Fixing-system-locale-configuration">perllocale Fixing system
locale configuration</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-The-localeconv-function">perllocale The localeconv
function</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-I18N_003a_003aLanginfo">perllocale
I18N::Langinfo</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-LOCALE CATEGORIES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perllocale-Category-LC_005fCOLLATE_003a-Collation-1">perllocale Category
<code>LC_COLLATE</code>: Collation 1</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Category-LC_005fCTYPE_003a-Character-Types-1">perllocale
Category <code>LC_CTYPE</code>: Character Types
1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Category-LC_005fNUMERIC_003a-Numeric-Formatting">perllocale
Category <code>LC_NUMERIC</code>: Numeric
Formatting</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Category-LC_005fMONETARY_003a-Formatting-of-monetary-amounts-1">perllocale
Category <code>LC_MONETARY</code>: Formatting of monetary amounts
1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-LC_005fTIME">perllocale
<code>LC_TIME</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Other-categories-1">perllocale Other categories
1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-ENVIRONMENT
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perllocale-Examples">perllocale
Examples</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-NOTES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perllocale-String-eval-and-LC_005fNUMERIC">perllocale String
<code>eval</code> and <code>LC_NUMERIC</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Backward-compatibility">perllocale Backward
compatibility</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-I18N_003aCollate-obsolete">perllocale I18N:Collate
obsolete</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Sort-speed-and-memory-use-impacts">perllocale Sort speed and
memory use impacts</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Freely-available-locale-definitions">perllocale Freely
available locale definitions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-I18n-and-l10n">perllocale I18n and
l10n</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-An-imperfect-standard">perllocale An imperfect
standard</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-BUGS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perllocale-Broken-systems">perllocale Broken
systems</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perllol
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perllol-NAME">perllol NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllol-DESCRIPTION">perllol
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllol-SEE-ALSO">perllol
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllol-AUTHOR">perllol
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perllol-Declaration-and-Access-of-Arrays-of-Arrays">perllol Declaration
and Access of Arrays of Arrays</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllol-Growing-Your-Own">perllol Growing Your
Own</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllol-Access-and-Printing">perllol Access and
Printing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllol-Slices">perllol
Slices</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlmod
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlmod-NAME">perlmod NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmod-DESCRIPTION">perlmod
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmod-SEE-ALSO">perlmod
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlmod-Is-this-the-document-you-were-after_003f">perlmod Is this the
document you were after?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmod-Packages">perlmod
Packages</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmod-Symbol-Tables">perlmod Symbol
Tables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmod-BEGIN_002c-UNITCHECK_002c-CHECK_002c-INIT-and-END">perlmod
BEGIN, UNITCHECK, CHECK, INIT and END</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmod-Perl-Classes">perlmod Perl
Classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmod-Perl-Modules">perlmod Perl
Modules</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmod-Making-your-module-threadsafe">perlmod Making your module
threadsafe</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlmodinstall
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlmodinstall-NAME">perlmodinstall
NAME</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodinstall-DESCRIPTION">perlmodinstall
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodinstall-PORTABILITY">perlmodinstall
PORTABILITY</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodinstall-HEY">perlmodinstall HEY</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodinstall-AUTHOR">perlmodinstall
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodinstall-COPYRIGHT">perlmodinstall
COPYRIGHT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlmodinstall-PREAMBLE">perlmodinstall
PREAMBLE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlmodstyle
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlmodstyle-NAME">perlmodstyle NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-INTRODUCTION">perlmodstyle
INTRODUCTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-QUICK-CHECKLIST">perlmodstyle QUICK
CHECKLIST</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-BEFORE-YOU-START-WRITING-A-MODULE">perlmodstyle BEFORE YOU
START WRITING A MODULE</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-DESIGNING-AND-WRITING-YOUR-MODULE">perlmodstyle DESIGNING
AND WRITING YOUR MODULE</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-DOCUMENTING-YOUR-MODULE">perlmodstyle DOCUMENTING YOUR
MODULE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-RELEASE-CONSIDERATIONS">perlmodstyle RELEASE
CONSIDERATIONS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-COMMON-PITFALLS">perlmodstyle COMMON
PITFALLS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-SEE-ALSO">perlmodstyle SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-AUTHOR">perlmodstyle
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-QUICK CHECKLIST
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlmodstyle-Before-you-start">perlmodstyle Before you
start</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-The-API">perlmodstyle The
API</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Stability">perlmodstyle
Stability</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Documentation">perlmodstyle
Documentation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Release-considerations">perlmodstyle Release
considerations</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-BEFORE YOU START WRITING A MODULE
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlmodstyle-Has-it-been-done-before_003f">perlmodstyle Has it been done
before?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Do-one-thing-and-do-it-well">perlmodstyle Do one thing and
do it well</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-What_0027s-in-a-name_003f">perlmodstyle What's in a
name?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Get-feedback-before-publishing">perlmodstyle Get feedback
before publishing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESIGNING AND WRITING YOUR MODULE
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlmodstyle-To-OO-or-not-to-OO_003f">perlmodstyle To OO or not to
OO?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Designing-your-API">perlmodstyle Designing your
API</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Strictness-and-warnings">perlmodstyle Strictness and
warnings</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Backwards-compatibility">perlmodstyle Backwards
compatibility</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Error-handling-and-messages">perlmodstyle Error handling
and messages</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DOCUMENTING YOUR MODULE
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlmodstyle-POD">perlmodstyle POD</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-README_002c-INSTALL_002c-release-notes_002c-changelogs">perlmodstyle
README, INSTALL, release notes, changelogs</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-RELEASE CONSIDERATIONS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlmodstyle-Version-numbering">perlmodstyle Version
numbering</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Pre_002drequisites">perlmodstyle
Pre-requisites</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Testing">perlmodstyle
Testing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Packaging">perlmodstyle
Packaging</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Licensing">perlmodstyle
Licensing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-COMMON PITFALLS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlmodstyle-Reinventing-the-wheel">perlmodstyle Reinventing the
wheel</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Trying-to-do-too-much">perlmodstyle Trying to do too
much</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Inappropriate-documentation">perlmodstyle Inappropriate
documentation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlmroapi
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlmroapi-NAME">perlmroapi NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmroapi-DESCRIPTION">perlmroapi
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmroapi-Callbacks">perlmroapi
Callbacks</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmroapi-Caching">perlmroapi Caching</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmroapi-Examples">perlmroapi
Examples</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmroapi-AUTHORS">perlmroapi AUTHORS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlnewmod
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlnewmod-NAME">perlnewmod NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnewmod-DESCRIPTION">perlnewmod
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnewmod-AUTHOR">perlnewmod AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnewmod-SEE-ALSO">perlnewmod SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlnewmod-Warning">perlnewmod Warning</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnewmod-What-should-I-make-into-a-module_003f">perlnewmod What should
I make into a module?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnewmod-Step_002dby_002dstep_003a-Preparing-the-ground">perlnewmod
Step-by-step: Preparing the ground</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnewmod-Step_002dby_002dstep_003a-Making-the-module">perlnewmod
Step-by-step: Making the module</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnewmod-Step_002dby_002dstep_003a-Distributing-your-module">perlnewmod
Step-by-step: Distributing your module</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlnumber
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlnumber-NAME">perlnumber NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnumber-SYNOPSIS">perlnumber
SYNOPSIS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnumber-DESCRIPTION">perlnumber
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnumber-Storing-numbers">perlnumber Storing
numbers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnumber-Numeric-operators-and-numeric-conversions">perlnumber Numeric
operators and numeric conversions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnumber-Flavors-of-Perl-numeric-operations">perlnumber Flavors of
Perl numeric operations</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnumber-AUTHOR">perlnumber AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnumber-SEE-ALSO">perlnumber SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlobj
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlobj-NAME">perlobj NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-DESCRIPTION">perlobj
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlobj-SEE-ALSO">perlobj
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlobj-An-Object-is-Simply-a-Data-Structure">perlobj An Object is
Simply a Data Structure</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-A-Class-is-Simply-a-Package">perlobj A Class is Simply a
Package</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-A-Method-is-Simply-a-Subroutine">perlobj A Method is Simply a
Subroutine</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Method-Invocation-_003e_003e">perlobj Method Invocation
>></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Inheritance">perlobj
Inheritance</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Writing-Constructors">perlobj Writing
Constructors</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlobj-Attributes">perlobj
Attributes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-An-Aside-About-Smarter-and-Safer-Code">perlobj An Aside About
Smarter and Safer Code</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Method-Call-Variations">perlobj Method Call
Variations</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Invoking-Class-Methods">perlobj Invoking Class
Methods</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-bless_002c-blessed_002c-and-ref">perlobj <code>bless</code>,
<code>blessed</code>, and <code>ref</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-The-UNIVERSAL-Class">perlobj The UNIVERSAL
Class</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlobj-AUTOLOAD">perlobj
AUTOLOAD</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Destructors">perlobj
Destructors</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Non_002dHash-Objects">perlobj Non-Hash
Objects</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Inside_002dOut-objects">perlobj Inside-Out
objects</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Pseudo_002dhashes">perlobj
Pseudo-hashes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-An Object is Simply a Data Structure
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlobj-Objects-Are-Blessed_003b-Variables-Are-Not">perlobj Objects Are
Blessed; Variables Are Not</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Inheritance
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlobj-How-SUPER-is-Resolved">perlobj How SUPER is
Resolved</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Multiple-Inheritance">perlobj Multiple
Inheritance</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Method-Resolution-Order">perlobj Method Resolution
Order</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Method-Resolution-Caching">perlobj Method Resolution
Caching</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Attributes
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlobj-Writing-Accessors">perlobj Writing
Accessors</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Method Call Variations
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlobj-Method-Names-as-Strings">perlobj Method Names as
Strings</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Class-Names-as-Strings">perlobj Class Names as
Strings</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Subroutine-References-as-Methods">perlobj Subroutine References
as Methods</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Deferencing-Method-Call">perlobj Deferencing Method
Call</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Method-Calls-on-Filehandles">perlobj Method Calls on
Filehandles</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Invoking Class Methods
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlobj-Indirect-Object-Syntax">perlobj Indirect Object
Syntax</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Destructors
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlobj-Global-Destruction">perlobj Global
Destruction</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlootut
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlootut-NAME">perlootut NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-DATE">perlootut
DATE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-DESCRIPTION">perlootut
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS">perlootut OBJECT-ORIENTED
FUNDAMENTALS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-PERL-OO-SYSTEMS">perlootut PERL OO
SYSTEMS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-CONCLUSION">perlootut
CONCLUSION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-OBJECT-ORIENTED FUNDAMENTALS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlootut-Object">perlootut Object</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-Class">perlootut
Class</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-Methods">perlootut Methods</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-Attributes">perlootut
Attributes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-Polymorphism">perlootut
Polymorphism</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-Inheritance">perlootut
Inheritance</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-Encapsulation">perlootut
Encapsulation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-Composition">perlootut
Composition</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-Roles">perlootut
Roles</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-When-to-Use-OO">perlootut When to Use
OO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Class
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlootut-Blessing">perlootut Blessing</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-Constructor">perlootut
Constructor</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Inheritance
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlootut-Overriding-methods-and-method-resolution">perlootut Overriding
methods and method resolution</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-PERL OO SYSTEMS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlootut-Moose">perlootut Moose</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-Class_003a_003aAccessor">perlootut
Class::Accessor</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-Class_003a_003aTiny">perlootut
Class::Tiny</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-Role_003a_003aTiny">perlootut
Role::Tiny</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-OO-System-Summary">perlootut OO System
Summary</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-Other-OO-Systems">perlootut Other OO
Systems</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Moose
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlootut-Moo">perlootut Moo</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlop
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlop-NAME">perlop NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlop-DESCRIPTION">perlop
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlop-Operator-Precedence-and-Associativity">perlop Operator Precedence
and Associativity</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Terms-and-List-Operators-_0028Leftward_0029">perlop Terms and
List Operators (Leftward)</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-The-Arrow-Operator-_003e_003e">perlop The Arrow Operator
>></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Auto_002dincrement-and-Auto_002ddecrement">perlop Auto-increment
and Auto-decrement</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Exponentiation">perlop
Exponentiation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Symbolic-Unary-Operators">perlop Symbolic Unary
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Binding-Operators">perlop Binding
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Multiplicative-Operators">perlop Multiplicative
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Additive-Operators">perlop Additive
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Shift-Operators-_003e-_003e_003e_003e">perlop Shift Operators
> >>></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Named-Unary-Operators">perlop Named Unary
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Relational-Operators">perlop Relational
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Equality-Operators">perlop Equality
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Smartmatch-Operator">perlop Smartmatch
Operator</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlop-Bitwise-And">perlop
Bitwise And</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Bitwise-Or-and-Exclusive-Or">perlop Bitwise Or and Exclusive
Or</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-C_002dstyle-Logical-And">perlop C-style Logical
And</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-C_002dstyle-Logical-Or">perlop C-style Logical
Or</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Logical-Defined_002dOr">perlop Logical
Defined-Or</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Range-Operators">perlop Range
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Conditional-Operator">perlop Conditional
Operator</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Assignment-Operators">perlop Assignment
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Comma-Operator">perlop Comma
Operator</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-List-Operators-_0028Rightward_0029">perlop List Operators
(Rightward)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlop-Logical-Not">perlop
Logical Not</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlop-Logical-And">perlop
Logical And</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Logical-or-and-Exclusive-Or">perlop Logical or and Exclusive
Or</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-C-Operators-Missing-From-Perl">perlop C Operators Missing From
Perl</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Quote-and-Quote_002dlike-Operators">perlop Quote and Quote-like
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Regexp-Quote_002dLike-Operators">perlop Regexp Quote-Like
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Quote_002dLike-Operators">perlop Quote-Like
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Gory-details-of-parsing-quoted-constructs">perlop Gory details of
parsing quoted constructs</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-I_002fO-Operators">perlop I/O
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Constant-Folding">perlop Constant
Folding</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlop-No_002dops">perlop
No-ops</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Bitwise-String-Operators">perlop Bitwise String
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Integer-Arithmetic">perlop Integer
Arithmetic</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Floating_002dpoint-Arithmetic">perlop Floating-point
Arithmetic</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Bigger-Numbers">perlop Bigger
Numbers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Smartmatch Operator
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlop-Smartmatching-of-Objects">perlop Smartmatching of
Objects</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlopentut
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlopentut-NAME">perlopentut NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlopentut-DESCRIPTION">perlopentut
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlopentut-Opening-Text-Files">perlopentut Opening Text
Files</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlopentut-Opening-Binary-Files">perlopentut Opening Binary
Files</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlopentut-Opening-Pipes">perlopentut Opening
Pipes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlopentut-Low_002dlevel-File-Opens-via-sysopen">perlopentut Low-level
File Opens via sysopen</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlopentut-SEE-ALSO">perlopentut SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlopentut-AUTHOR-and-COPYRIGHT">perlopentut AUTHOR and
COPYRIGHT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Opening Text Files
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlopentut-Opening-Text-Files-for-Reading">perlopentut Opening Text
Files for Reading</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlopentut-Opening-Text-Files-for-Writing">perlopentut Opening Text
Files for Writing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlpacktut
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpacktut-NAME">perlpacktut NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-DESCRIPTION">perlpacktut
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-The-Basic-Principle">perlpacktut The Basic
Principle</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Packing-Text">perlpacktut Packing
Text</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Packing-Numbers">perlpacktut Packing
Numbers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Exotic-Templates">perlpacktut Exotic
Templates</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Template-Grouping">perlpacktut Template
Grouping</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Lengths-and-Widths">perlpacktut Lengths and
Widths</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Packing-and-Unpacking-C-Structures">perlpacktut Packing and
Unpacking C Structures</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Pack-Recipes">perlpacktut Pack
Recipes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Funnies-Section">perlpacktut Funnies
Section</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Authors">perlpacktut
Authors</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Packing Numbers
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpacktut-Integers">perlpacktut
Integers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Unpacking-a-Stack-Frame">perlpacktut Unpacking a Stack
Frame</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-How-to-Eat-an-Egg-on-a-Net">perlpacktut How to Eat an Egg on
a Net</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Byte_002dorder-modifiers">perlpacktut Byte-order
modifiers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Floating-point-Numbers">perlpacktut Floating point
Numbers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Exotic Templates
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpacktut-Bit-Strings">perlpacktut Bit
Strings</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Uuencoding">perlpacktut
Uuencoding</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Doing-Sums">perlpacktut Doing
Sums</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Unicode">perlpacktut
Unicode</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Another-Portable-Binary-Encoding">perlpacktut Another
Portable Binary Encoding</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Lengths and Widths
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpacktut-String-Lengths">perlpacktut String
Lengths</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Dynamic-Templates">perlpacktut Dynamic
Templates</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Counting-Repetitions">perlpacktut Counting
Repetitions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Intel-HEX">perlpacktut Intel
HEX</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Packing and Unpacking C Structures
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpacktut-The-Alignment-Pit">perlpacktut The Alignment
Pit</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Dealing-with-Endian_002dness">perlpacktut Dealing with
Endian-ness</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Alignment_002c-Take-2">perlpacktut Alignment, Take
2</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Alignment_002c-Take-3">perlpacktut Alignment, Take
3</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Pointers-for-How-to-Use-Them">perlpacktut Pointers for How
to Use Them</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlperf
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlperf-NAME">perlperf NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-DESCRIPTION">perlperf
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-OVERVIEW">perlperf
OVERVIEW</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-GENERAL-GUIDELINES">perlperf GENERAL
GUIDELINES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-BENCHMARKS">perlperf
BENCHMARKS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-PROFILING-TOOLS">perlperf PROFILING
TOOLS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-SORTING">perlperf
SORTING</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-LOGGING">perlperf
LOGGING</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-POSTSCRIPT">perlperf
POSTSCRIPT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-SEE-ALSO">perlperf
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-AUTHOR">perlperf
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-OVERVIEW
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlperf-ONE-STEP-SIDEWAYS">perlperf ONE STEP
SIDEWAYS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-ONE-STEP-FORWARD">perlperf ONE STEP
FORWARD</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-ANOTHER-STEP-SIDEWAYS">perlperf ANOTHER STEP
SIDEWAYS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-BENCHMARKS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlperf-Assigning-and-Dereferencing-Variables_002e">perlperf Assigning
and Dereferencing Variables.</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-Search-and-replace-or-tr">perlperf Search and replace or
tr</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-PROFILING TOOLS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlperf-Devel_003a_003aDProf">perlperf
Devel::DProf</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-Devel_003a_003aProfiler">perlperf
Devel::Profiler</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-Devel_003a_003aSmallProf">perlperf
Devel::SmallProf</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-Devel_003a_003aFastProf">perlperf
Devel::FastProf</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-Devel_003a_003aNYTProf">perlperf
Devel::NYTProf</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-LOGGING
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlperf-Logging-if-DEBUG-_0028constant_0029">perlperf Logging if DEBUG
(constant)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-SEE ALSO
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlperf-PERLDOCS">perlperf PERLDOCS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-MAN-PAGES">perlperf MAN PAGES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-MODULES">perlperf
MODULES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-URLS">perlperf
URLS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlpod
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpod-NAME">perlpod NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpod-DESCRIPTION">perlpod
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpod-SEE-ALSO">perlpod
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpod-AUTHOR">perlpod
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpod-Ordinary-Paragraph">perlpod Ordinary
Paragraph</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpod-Verbatim-Paragraph">perlpod Verbatim
Paragraph</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpod-Command-Paragraph">perlpod Command
Paragraph</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpod-Formatting-Codes">perlpod Formatting
Codes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpod-The-Intent">perlpod
The Intent</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpod-Embedding-Pods-in-Perl-Modules">perlpod Embedding Pods in Perl
Modules</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpod-Hints-for-Writing-Pod">perlpod Hints for Writing
Pod</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlpodspec
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpodspec-NAME">perlpodspec NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-DESCRIPTION">perlpodspec
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-Pod-Definitions">perlpodspec Pod
Definitions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-Pod-Commands">perlpodspec Pod
Commands</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-Pod-Formatting-Codes">perlpodspec Pod Formatting
Codes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-Notes-on-Implementing-Pod-Processors">perlpodspec Notes on
Implementing Pod Processors</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-About-L_003c_002e_002e_002e_003e-Codes">perlpodspec About
L<...> Codes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-About-_003dover_002e_002e_002e_003dback-Regions">perlpodspec
About =over...=back Regions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-About-Data-Paragraphs-and-_0022_003dbegin_002f_003dend_0022-Regions">perlpodspec
About Data Paragraphs and "=begin/=end"
Regions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-SEE-ALSO">perlpodspec SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-AUTHOR">perlpodspec AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlpodstyle
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpodstyle-NAME">perlpodstyle NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodstyle-DESCRIPTION">perlpodstyle
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodstyle-SEE-ALSO-1">perlpodstyle SEE ALSO
1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodstyle-AUTHOR-1">perlpodstyle AUTHOR
1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodstyle-COPYRIGHT-AND-LICENSE-1">perlpodstyle COPYRIGHT AND LICENSE
1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlpolicy
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpolicy-NAME">perlpolicy NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-DESCRIPTION">perlpolicy
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-GOVERNANCE">perlpolicy
GOVERNANCE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-MAINTENANCE-AND-SUPPORT">perlpolicy MAINTENANCE AND
SUPPORT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-BACKWARD-COMPATIBILITY-AND-DEPRECATION">perlpolicy BACKWARD
COMPATIBILITY AND DEPRECATION</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-MAINTENANCE-BRANCHES">perlpolicy MAINTENANCE
BRANCHES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-CONTRIBUTED-MODULES">perlpolicy CONTRIBUTED
MODULES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-DOCUMENTATION">perlpolicy
DOCUMENTATION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-STANDARDS-OF-CONDUCT">perlpolicy STANDARDS OF
CONDUCT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-CREDITS">perlpolicy CREDITS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-GOVERNANCE
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpolicy-Perl-5-Porters">perlpolicy Perl 5
Porters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-BACKWARD COMPATIBILITY AND DEPRECATION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpolicy-Terminology">perlpolicy
Terminology</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-MAINTENANCE BRANCHES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpolicy-Getting-changes-into-a-maint-branch">perlpolicy Getting
changes into a maint branch</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-CONTRIBUTED MODULES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpolicy-A-Social-Contract-about-Artistic-Control">perlpolicy A Social
Contract about Artistic Control</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlport
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlport-NAME">perlport NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-DESCRIPTION">perlport
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-ISSUES">perlport
ISSUES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-CPAN-Testers">perlport CPAN
Testers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-PLATFORMS">perlport PLATFORMS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-FUNCTION-IMPLEMENTATIONS">perlport FUNCTION
IMPLEMENTATIONS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Supported-Platforms">perlport Supported
Platforms</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-EOL-Platforms">perlport EOL
Platforms</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Supported-Platforms-_0028Perl-5_002e8_0029">perlport Supported
Platforms (Perl 5.8)</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-SEE-ALSO">perlport
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-AUTHORS-_002f-CONTRIBUTORS">perlport AUTHORS /
CONTRIBUTORS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-ISSUES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlport-Newlines">perlport Newlines</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Numbers-endianness-and-Width">perlport Numbers endianness and
Width</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Files-and-Filesystems">perlport Files and
Filesystems</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-System-Interaction">perlport System
Interaction</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Command-names-versus-file-pathnames">perlport Command names
versus file pathnames</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Networking">perlport
Networking</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Interprocess-Communication-_0028IPC_0029">perlport Interprocess
Communication (IPC)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-External-Subroutines-_0028XS_0029">perlport External
Subroutines (XS)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Standard-Modules">perlport Standard
Modules</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Time-and-Date">perlport Time and
Date</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Character-sets-and-character-encoding">perlport Character sets
and character encoding</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Internationalisation">perlport
Internationalisation</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-System-Resources">perlport System
Resources</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-Security">perlport
Security</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-Style">perlport
Style</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-PLATFORMS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlport-Unix">perlport Unix</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-DOS-and-Derivatives">perlport DOS and
Derivatives</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-VMS">perlport
VMS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-VOS">perlport
VOS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-EBCDIC-Platforms">perlport EBCDIC
Platforms</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Acorn-RISC-OS">perlport Acorn RISC
OS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Other-perls">perlport Other
perls</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-FUNCTION IMPLEMENTATIONS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlport-Alphabetical-Listing-of-Perl-Functions">perlport Alphabetical
Listing of Perl Functions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-EOL Platforms
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlport-_0028Perl-5_002e20_0029">perlport (Perl
5.20)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-_0028Perl-5_002e14_0029">perlport (Perl
5.14)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-_0028Perl-5_002e12_0029">perlport (Perl
5.12)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlpragma
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlpragma-NAME">perlpragma NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpragma-DESCRIPTION">perlpragma
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpragma-A-basic-example">perlpragma A basic
example</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpragma-Key-naming">perlpragma Key
naming</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpragma-Implementation-details">perlpragma Implementation
details</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlre
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlre-NAME">perlre NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-DESCRIPTION">perlre
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-BUGS">perlre
BUGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-SEE-ALSO">perlre SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlre-Modifiers">perlre Modifiers</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Regular-Expressions">perlre Regular
Expressions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Quoting-metacharacters">perlre Quoting
metacharacters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Extended-Patterns">perlre Extended
Patterns</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Special-Backtracking-Control-Verbs">perlre Special Backtracking
Control Verbs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-Backtracking">perlre
Backtracking</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Version-8-Regular-Expressions">perlre Version 8 Regular
Expressions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Warning-on-_005c1-Instead-of-_00241">perlre Warning on \1 Instead
of $1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Repeated-Patterns-Matching-a-Zero_002dlength-Substring">perlre
Repeated Patterns Matching a Zero-length
Substring</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Combining-RE-Pieces">perlre Combining RE
Pieces</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Creating-Custom-RE-Engines">perlre Creating Custom RE
Engines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Embedded-Code-Execution-Frequency">perlre Embedded Code Execution
Frequency</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-PCRE_002fPython-Support">perlre PCRE/Python
Support</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Modifiers
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlre-Overview">perlre Overview</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Details-on-some-modifiers">perlre Details on some
modifiers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-_002fx">perlre
/x</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Character-set-modifiers">perlre Character set
modifiers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-_002fl">perlre
/l</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-_002fu">perlre
/u</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-_002fd">perlre
/d</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-_002fa-_0028and-_002faa_0029">perlre /a (and
/aa)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Which-character-set-modifier-is-in-effect_003f">perlre Which
character set modifier is in effect?</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Character-set-modifier-behavior-prior-to-Perl-5_002e14">perlre
Character set modifier behavior prior to Perl
5.14</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Regular Expressions
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlre-Metacharacters">perlre
Metacharacters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-Quantifiers">perlre
Quantifiers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Escape-sequences">perlre Escape
sequences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Character-Classes-and-other-Special-Escapes">perlre Character
Classes and other Special Escapes</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-Assertions">perlre
Assertions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Capture-groups">perlre Capture
groups</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlreapi
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreapi-NAME">perlreapi NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-DESCRIPTION">perlreapi
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-Callbacks">perlreapi
Callbacks</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-The-REGEXP-structure">perlreapi The REGEXP
structure</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-HISTORY">perlreapi HISTORY</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-AUTHORS">perlreapi AUTHORS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-LICENSE">perlreapi LICENSE</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Callbacks
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreapi-comp">perlreapi comp</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-exec">perlreapi
exec</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-intuit">perlreapi
intuit</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-checkstr">perlreapi checkstr</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-free">perlreapi
free</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-Numbered-capture-callbacks">perlreapi Numbered capture
callbacks</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-Named-capture-callbacks">perlreapi Named capture
callbacks</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-qr_005fpackage">perlreapi
qr_package</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-dupe">perlreapi
dupe</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-op_005fcomp">perlreapi
op_comp</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Numbered capture callbacks
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreapi-numbered_005fbuff_005fFETCH">perlreapi
numbered_buff_FETCH</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-numbered_005fbuff_005fSTORE">perlreapi
numbered_buff_STORE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-numbered_005fbuff_005fLENGTH">perlreapi
numbered_buff_LENGTH</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Named capture callbacks
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreapi-named_005fbuff">perlreapi
named_buff</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-named_005fbuff_005fiter">perlreapi
named_buff_iter</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-The REGEXP structure
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreapi-engine">perlreapi
<code>engine</code></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-mother_005fre">perlreapi
<code>mother_re</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-extflags">perlreapi
<code>extflags</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-minlen-minlenret">perlreapi <code>minlen</code>
<code>minlenret</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-gofs">perlreapi
<code>gofs</code></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-substrs">perlreapi
<code>substrs</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-nparens_002c-lastparen_002c-and-lastcloseparen">perlreapi
<code>nparens</code>, <code>lastparen</code>, and
<code>lastcloseparen</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-intflags">perlreapi
<code>intflags</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-pprivate">perlreapi
<code>pprivate</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-swap">perlreapi
<code>swap</code></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-offs">perlreapi
<code>offs</code></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-precomp-prelen">perlreapi <code>precomp</code>
<code>prelen</code></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-paren_005fnames">perlreapi
<code>paren_names</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-substrs-1">perlreapi <code>substrs</code>
1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-subbeg-sublen-saved_005fcopy-suboffset-subcoffset">perlreapi
<code>subbeg</code> <code>sublen</code> <code>saved_copy</code>
<code>suboffset</code>
<code>subcoffset</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-wrapped-wraplen">perlreapi <code>wrapped</code>
<code>wraplen</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-seen_005fevals">perlreapi
<code>seen_evals</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-refcnt">perlreapi
<code>refcnt</code></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlrebackslash
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrebackslash-NAME">perlrebackslash
NAME</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-DESCRIPTION">perlrebackslash
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrebackslash-The-backslash">perlrebackslash The
backslash</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-All-the-sequences-and-escapes">perlrebackslash All the
sequences and escapes</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Character-Escapes">perlrebackslash Character
Escapes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Modifiers">perlrebackslash
Modifiers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Character-classes">perlrebackslash Character
classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Referencing">perlrebackslash
Referencing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Assertions">perlrebackslash
Assertions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Misc">perlrebackslash
Misc</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Character Escapes
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrebackslash-Fixed-characters">perlrebackslash Fixed
characters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Example">perlrebackslash
Example</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Control-characters">perlrebackslash Control
characters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Example-1">perlrebackslash Example
1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Named-or-numbered-characters-and-character-sequences">perlrebackslash
Named or numbered characters and character
sequences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Example-2">perlrebackslash Example
2</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Octal-escapes">perlrebackslash Octal
escapes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Examples-_0028assuming-an-ASCII-platform_0029">perlrebackslash
Examples (assuming an ASCII platform)</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Disambiguation-rules-between-old_002dstyle-octal-escapes-and-backreferences">perlrebackslash
Disambiguation rules between old-style octal escapes and
backreferences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Hexadecimal-escapes">perlrebackslash Hexadecimal
escapes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Examples-_0028assuming-an-ASCII-platform_0029-1">perlrebackslash
Examples (assuming an ASCII platform) 1</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Modifiers
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrebackslash-Examples">perlrebackslash
Examples</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Character classes
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrebackslash-Unicode-classes">perlrebackslash Unicode
classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Referencing
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrebackslash-Absolute-referencing">perlrebackslash Absolute
referencing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Examples-1">perlrebackslash Examples
1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Relative-referencing">perlrebackslash Relative
referencing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Examples-2">perlrebackslash Examples
2</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Named-referencing">perlrebackslash Named
referencing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Examples-3">perlrebackslash Examples
3</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Assertions
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrebackslash-Examples-4">perlrebackslash Examples
4</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Misc
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrebackslash-Examples-5">perlrebackslash Examples
5</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlrecharclass
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrecharclass-NAME">perlrecharclass
NAME</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-DESCRIPTION">perlrecharclass
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrecharclass-The-dot">perlrecharclass The
dot</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Backslash-sequences">perlrecharclass Backslash
sequences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Bracketed-Character-Classes">perlrecharclass Bracketed
Character Classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Backslash sequences
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrecharclass-_005cN">perlrecharclass
\N</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Digits">perlrecharclass
Digits</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Word-characters">perlrecharclass Word
characters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Whitespace">perlrecharclass
Whitespace</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Unicode-Properties">perlrecharclass Unicode
Properties</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Examples">perlrecharclass
Examples</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Bracketed Character Classes
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrecharclass-Special-Characters-Inside-a-Bracketed-Character-Class">perlrecharclass
Special Characters Inside a Bracketed Character
Class</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Character-Ranges">perlrecharclass Character
Ranges</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Negation">perlrecharclass
Negation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Backslash-Sequences">perlrecharclass Backslash
Sequences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-POSIX-Character-Classes">perlrecharclass POSIX Character
Classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Negation-of-POSIX-character-classes">perlrecharclass
Negation of POSIX character classes</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-_005b_003d-_003d_005d-and-_005b_002e-_002e_005d">perlrecharclass
[= =] and [. .]</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Examples-1">perlrecharclass Examples
1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Extended-Bracketed-Character-Classes">perlrecharclass
Extended Bracketed Character Classes</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlref
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlref-NAME">perlref NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlref-NOTE">perlref
NOTE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-DESCRIPTION">perlref
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlref-WARNING">perlref
WARNING</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-Postfix-Dereference-Syntax">perlref Postfix Dereference
Syntax</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-Assigning-to-References">perlref Assigning to
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlref-SEE-ALSO">perlref
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlref-Making-References">perlref Making
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-Using-References">perlref Using
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-Circular-References">perlref Circular
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-Symbolic-references">perlref Symbolic
references</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-Not_002dso_002dsymbolic-references">perlref Not-so-symbolic
references</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-Pseudo_002dhashes_003a-Using-an-array-as-a-hash">perlref
Pseudo-hashes: Using an array as a hash</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-Function-Templates">perlref Function
Templates</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Postfix Dereference Syntax
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlref-Postfix-Reference-Slicing">perlref Postfix Reference
Slicing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlreftut
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreftut-NAME">perlreftut NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut-DESCRIPTION">perlreftut
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut-Who-Needs-Complicated-Data-Structures_003f">perlreftut Who
Needs Complicated Data Structures?</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut-The-Solution">perlreftut The
Solution</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut-Syntax">perlreftut Syntax</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut-Solution">perlreftut
Solution</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut-The-Rest">perlreftut The
Rest</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut-Summary">perlreftut Summary</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut-Credits">perlreftut Credits</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Syntax
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreftut-Making-References">perlreftut Making
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut-Using-References">perlreftut Using
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut-An-Example">perlreftut An
Example</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut-Arrow-Rule">perlreftut Arrow
Rule</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Making References
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreftut-Make-Rule-1">perlreftut <strong>Make Rule
1</strong></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Using References
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreftut-Use-Rule-1">perlreftut <strong>Use Rule
1</strong></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut-Use-Rule-2">perlreftut <strong>Use Rule
2</strong></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Credits
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreftut-Distribution-Conditions">perlreftut Distribution
Conditions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlreguts
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreguts-NAME">perlreguts NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-DESCRIPTION">perlreguts
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-OVERVIEW">perlreguts
OVERVIEW</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Process-Overview">perlreguts Process
Overview</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-MISCELLANEOUS">perlreguts
MISCELLANEOUS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-SEE-ALSO">perlreguts SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-AUTHOR">perlreguts AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-LICENCE">perlreguts LICENCE</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-REFERENCES">perlreguts
REFERENCES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-OVERVIEW
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreguts-A-quick-note-on-terms">perlreguts A quick note on
terms</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-What-is-a-regular-expression-engine_003f">perlreguts What is
a regular expression engine?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Structure-of-a-Regexp-Program">perlreguts Structure of a
Regexp Program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Structure of a Regexp Program
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreguts-High-Level">perlreguts High
Level</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Regops">perlreguts Regops</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-What-regop-is-next_003f">perlreguts What regop is
next?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Process Overview
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreguts-Compilation">perlreguts
Compilation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Execution">perlreguts
Execution</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Compilation
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreguts-Parsing-for-size">perlreguts Parsing for
size</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Parsing-for-construction">perlreguts Parsing for
construction</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Parse-Call-Graph-and-a-Grammar">perlreguts Parse Call Graph
and a Grammar</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Parsing-complications">perlreguts Parsing
complications</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Debug-Output">perlreguts Debug
Output</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Peep_002dhole-Optimisation-and-Analysis">perlreguts Peep-hole
Optimisation and Analysis</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Execution
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreguts-Start-position-and-no_002dmatch-optimisations">perlreguts
Start position and no-match optimisations</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Program-execution">perlreguts Program
execution</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-MISCELLANEOUS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreguts-Unicode-and-Localisation-Support">perlreguts Unicode and
Localisation Support</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Base-Structures">perlreguts Base
Structures</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Base Structures
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreguts-Perl_0027s-pprivate-structure">perlreguts Perl's
<code>pprivate</code> structure</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlrepository
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrepository-NAME">perlrepository
NAME</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrepository-DESCRIPTION">perlrepository
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlrequick
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrequick-NAME">perlrequick NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-DESCRIPTION">perlrequick
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-The-Guide">perlrequick The
Guide</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-BUGS">perlrequick BUGS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-SEE-ALSO">perlrequick SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-AUTHOR-AND-COPYRIGHT">perlrequick AUTHOR AND
COPYRIGHT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-The Guide
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrequick-Simple-word-matching">perlrequick Simple word
matching</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-Using-character-classes">perlrequick Using character
classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-Matching-this-or-that">perlrequick Matching this or
that</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-Grouping-things-and-hierarchical-matching">perlrequick
Grouping things and hierarchical matching</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-Extracting-matches">perlrequick Extracting
matches</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-Matching-repetitions">perlrequick Matching
repetitions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-More-matching">perlrequick More
matching</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-Search-and-replace">perlrequick Search and
replace</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-The-split-operator">perlrequick The split
operator</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-use-re-_0027strict_0027">perlrequick <code>use re
'strict'</code></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-AUTHOR AND COPYRIGHT
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrequick-Acknowledgments">perlrequick
Acknowledgments</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlreref
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreref-NAME">perlreref NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref-DESCRIPTION">perlreref
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreref-AUTHOR">perlreref
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref-SEE-ALSO">perlreref SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreref-THANKS">perlreref
THANKS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreref-OPERATORS">perlreref
OPERATORS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreref-SYNTAX">perlreref
SYNTAX</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref-ESCAPE-SEQUENCES">perlreref ESCAPE
SEQUENCES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref-CHARACTER-CLASSES">perlreref CHARACTER
CLASSES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref-ANCHORS">perlreref ANCHORS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref-QUANTIFIERS">perlreref
QUANTIFIERS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref-EXTENDED-CONSTRUCTS">perlreref EXTENDED
CONSTRUCTS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref-VARIABLES">perlreref
VARIABLES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref-FUNCTIONS">perlreref
FUNCTIONS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref-TERMINOLOGY">perlreref
TERMINOLOGY</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-TERMINOLOGY
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlreref-Titlecase">perlreref
Titlecase</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref-Foldcase">perlreref Foldcase</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlretut
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlretut-NAME">perlretut NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-DESCRIPTION">perlretut
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Part-1_003a-The-basics">perlretut Part 1: The
basics</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Part-2_003a-Power-tools">perlretut Part 2: Power
tools</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlretut-BUGS">perlretut
BUGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-SEE-ALSO">perlretut SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-AUTHOR-AND-COPYRIGHT">perlretut AUTHOR AND
COPYRIGHT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Part 1: The basics
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlretut-Simple-word-matching">perlretut Simple word
matching</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Using-character-classes">perlretut Using character
classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Matching-this-or-that">perlretut Matching this or
that</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Grouping-things-and-hierarchical-matching">perlretut Grouping
things and hierarchical matching</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Extracting-matches">perlretut Extracting
matches</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Backreferences">perlretut
Backreferences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Relative-backreferences">perlretut Relative
backreferences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Named-backreferences">perlretut Named
backreferences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Alternative-capture-group-numbering">perlretut Alternative
capture group numbering</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Position-information">perlretut Position
information</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Non_002dcapturing-groupings">perlretut Non-capturing
groupings</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Matching-repetitions">perlretut Matching
repetitions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Possessive-quantifiers">perlretut Possessive
quantifiers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Building-a-regexp">perlretut Building a
regexp</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Using-regular-expressions-in-Perl">perlretut Using regular
expressions in Perl</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Using regular expressions in Perl
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlretut-Prohibiting-substitution">perlretut Prohibiting
substitution</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Global-matching">perlretut Global
matching</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Search-and-replace">perlretut Search and
replace</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-The-split-function">perlretut The split
function</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Part 2: Power tools
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlretut-More-on-characters_002c-strings_002c-and-character-classes">perlretut
More on characters, strings, and character
classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Compiling-and-saving-regular-expressions">perlretut Compiling
and saving regular expressions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Composing-regular-expressions-at-runtime">perlretut Composing
regular expressions at runtime</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Embedding-comments-and-modifiers-in-a-regular-expression">perlretut
Embedding comments and modifiers in a regular
expression</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Looking-ahead-and-looking-behind">perlretut Looking ahead and
looking behind</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Using-independent-subexpressions-to-prevent-backtracking">perlretut
Using independent subexpressions to prevent
backtracking</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Conditional-expressions">perlretut Conditional
expressions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Defining-named-patterns">perlretut Defining named
patterns</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Recursive-patterns">perlretut Recursive
patterns</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-A-bit-of-magic_003a-executing-Perl-code-in-a-regular-expression">perlretut
A bit of magic: executing Perl code in a regular
expression</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Backtracking-control-verbs">perlretut Backtracking control
verbs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Pragmas-and-debugging">perlretut Pragmas and
debugging</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-AUTHOR AND COPYRIGHT
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlretut-Acknowledgments">perlretut
Acknowledgments</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlrun
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrun-NAME">perlrun NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrun-SYNOPSIS">perlrun
SYNOPSIS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrun-DESCRIPTION">perlrun
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrun-ENVIRONMENT">perlrun
ENVIRONMENT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlrun-_0023_0021-and-quoting-on-non_002dUnix-systems">perlrun #! and
quoting on non-Unix systems</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrun-Location-of-Perl">perlrun Location of
Perl</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrun-Command-Switches">perlrun Command
Switches</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlsec
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlsec-NAME">perlsec NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-DESCRIPTION">perlsec
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-SECURITY-VULNERABILITY-CONTACT-INFORMATION">perlsec SECURITY
VULNERABILITY CONTACT INFORMATION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-SECURITY-MECHANISMS-AND-CONCERNS">perlsec SECURITY MECHANISMS
AND CONCERNS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsec-SEE-ALSO">perlsec
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-SECURITY MECHANISMS AND CONCERNS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlsec-Taint-mode">perlsec Taint mode</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-Laundering-and-Detecting-Tainted-Data">perlsec Laundering and
Detecting Tainted Data</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-Switches-On-the-_0022_0023_0021_0022-Line">perlsec Switches On
the "#!" Line</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-Taint-mode-and-_0040INC">perlsec Taint mode and
@INC</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-Cleaning-Up-Your-Path">perlsec Cleaning Up Your
Path</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-Security-Bugs">perlsec Security
Bugs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-Protecting-Your-Programs">perlsec Protecting Your
Programs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsec-Unicode">perlsec
Unicode</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-Algorithmic-Complexity-Attacks">perlsec Algorithmic Complexity
Attacks</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlsource
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlsource-NAME">perlsource NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsource-DESCRIPTION">perlsource
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsource-FINDING-YOUR-WAY-AROUND">perlsource FINDING YOUR WAY
AROUND</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-FINDING YOUR WAY AROUND
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlsource-C-code">perlsource C code</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsource-Core-modules">perlsource Core
modules</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsource-Tests">perlsource Tests</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsource-Documentation">perlsource
Documentation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsource-Hacking-tools-and-documentation">perlsource Hacking tools and
documentation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsource-Build-system">perlsource Build
system</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsource-AUTHORS">perlsource
<samp>AUTHORS</samp></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsource-MANIFEST">perlsource
<samp>MANIFEST</samp></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlstyle
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlstyle-NAME">perlstyle NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlstyle-DESCRIPTION">perlstyle
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlsub
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlsub-NAME">perlsub NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsub-SYNOPSIS">perlsub
SYNOPSIS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-DESCRIPTION">perlsub
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsub-SEE-ALSO">perlsub
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlsub-Signatures">perlsub Signatures</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Private-Variables-via-my_0028_0029">perlsub Private Variables
via my()</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Persistent-Private-Variables">perlsub Persistent Private
Variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Temporary-Values-via-local_0028_0029">perlsub Temporary Values
via local()</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Lvalue-subroutines">perlsub Lvalue
subroutines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Lexical-Subroutines">perlsub Lexical
Subroutines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Passing-Symbol-Table-Entries-_0028typeglobs_0029">perlsub
Passing Symbol Table Entries (typeglobs)</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-When-to-Still-Use-local_0028_0029">perlsub When to Still Use
local()</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Pass-by-Reference">perlsub Pass by
Reference</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsub-Prototypes">perlsub
Prototypes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Constant-Functions">perlsub Constant
Functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Overriding-Built_002din-Functions">perlsub Overriding Built-in
Functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Autoloading">perlsub
Autoloading</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Subroutine-Attributes">perlsub Subroutine
Attributes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Persistent Private Variables
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlsub-Persistent-variables-via-state_0028_0029">perlsub Persistent
variables via state()</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Persistent-variables-with-closures">perlsub Persistent variables
with closures</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Temporary Values via local()
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlsub-Grammatical-note-on-local_0028_0029">perlsub Grammatical note on
local()</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Localization-of-special-variables">perlsub Localization of
special variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Localization-of-globs">perlsub Localization of
globs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Localization-of-elements-of-composite-types">perlsub
Localization of elements of composite types</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Localized-deletion-of-elements-of-composite-types">perlsub
Localized deletion of elements of composite
types</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Lexical Subroutines
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlsub-state-sub-vs-my-sub">perlsub <code>state sub</code> vs <code>my
sub</code></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-our-subroutines">perlsub <code>our</code>
subroutines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlsyn
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlsyn-NAME">perlsyn NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-DESCRIPTION">perlsyn
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlsyn-Declarations">perlsyn
Declarations</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsyn-Comments">perlsyn
Comments</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Simple-Statements">perlsyn Simple
Statements</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Truth-and-Falsehood">perlsyn Truth and
Falsehood</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Statement-Modifiers">perlsyn Statement
Modifiers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Compound-Statements">perlsyn Compound
Statements</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Loop-Control">perlsyn Loop
Control</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsyn-For-Loops">perlsyn
For Loops</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Foreach-Loops">perlsyn Foreach
Loops</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Basic-BLOCKs">perlsyn Basic
BLOCKs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Switch-Statements">perlsyn Switch
Statements</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsyn-Goto">perlsyn
Goto</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-The-Ellipsis-Statement">perlsyn The Ellipsis
Statement</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-PODs_003a-Embedded-Documentation">perlsyn PODs: Embedded
Documentation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Plain-Old-Comments-_0028Not_0021_0029">perlsyn Plain Old
Comments (Not!)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Experimental-Details-on-given-and-when">perlsyn Experimental
Details on given and when</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Experimental Details on given and when
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlsyn-Breaking-out">perlsyn Breaking
out</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Fall_002dthrough">perlsyn
Fall-through</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Return-value">perlsyn Return
value</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Switching-in-a-loop">perlsyn Switching in a
loop</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Differences-from-Perl-6">perlsyn Differences from Perl
6</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlthrtut
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlthrtut-NAME">perlthrtut NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-DESCRIPTION">perlthrtut
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-What-Is-A-Thread-Anyway_003f">perlthrtut What Is A Thread
Anyway?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Threaded-Program-Models">perlthrtut Threaded Program
Models</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-What-kind-of-threads-are-Perl-threads_003f">perlthrtut What
kind of threads are Perl threads?</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Thread_002dSafe-Modules">perlthrtut Thread-Safe
Modules</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Thread-Basics">perlthrtut Thread
Basics</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Threads-And-Data">perlthrtut Threads And
Data</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Synchronization-and-control">perlthrtut Synchronization and
control</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-General-Thread-Utility-Routines">perlthrtut General Thread
Utility Routines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-A-Complete-Example">perlthrtut A Complete
Example</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Different-implementations-of-threads">perlthrtut Different
implementations of threads</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Performance-considerations">perlthrtut Performance
considerations</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Process_002dscope-Changes">perlthrtut Process-scope
Changes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Thread_002dSafety-of-System-Libraries">perlthrtut
Thread-Safety of System Libraries</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Conclusion">perlthrtut
Conclusion</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-SEE-ALSO">perlthrtut SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Bibliography">perlthrtut
Bibliography</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Acknowledgements">perlthrtut
Acknowledgements</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-AUTHOR">perlthrtut AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Copyrights">perlthrtut
Copyrights</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Threaded Program Models
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlthrtut-Boss_002fWorker">perlthrtut
Boss/Worker</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Work-Crew">perlthrtut Work
Crew</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Pipeline">perlthrtut
Pipeline</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Thread Basics
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlthrtut-Basic-Thread-Support">perlthrtut Basic Thread
Support</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-A-Note-about-the-Examples">perlthrtut A Note about the
Examples</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Creating-Threads">perlthrtut Creating
Threads</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Waiting-For-A-Thread-To-Exit">perlthrtut Waiting For A Thread
To Exit</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Ignoring-A-Thread">perlthrtut Ignoring A
Thread</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Process-and-Thread-Termination">perlthrtut Process and Thread
Termination</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Threads And Data
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlthrtut-Shared-And-Unshared-Data">perlthrtut Shared And Unshared
Data</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Thread-Pitfalls_003a-Races">perlthrtut Thread Pitfalls:
Races</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Synchronization and control
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlthrtut-Controlling-access_003a-lock_0028_0029">perlthrtut
Controlling access: lock()</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-A-Thread-Pitfall_003a-Deadlocks">perlthrtut A Thread Pitfall:
Deadlocks</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Queues_003a-Passing-Data-Around">perlthrtut Queues: Passing
Data Around</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Semaphores_003a-Synchronizing-Data-Access">perlthrtut
Semaphores: Synchronizing Data Access</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Basic-semaphores">perlthrtut Basic
semaphores</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Advanced-Semaphores">perlthrtut Advanced
Semaphores</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Waiting-for-a-Condition">perlthrtut Waiting for a
Condition</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Giving-up-control">perlthrtut Giving up
control</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-General Thread Utility Routines
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlthrtut-What-Thread-Am-I-In_003f">perlthrtut What Thread Am I
In?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Thread-IDs">perlthrtut Thread
IDs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Are-These-Threads-The-Same_003f">perlthrtut Are These Threads
The Same?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-What-Threads-Are-Running_003f">perlthrtut What Threads Are
Running?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Bibliography
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlthrtut-Introductory-Texts">perlthrtut Introductory
Texts</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-OS_002dRelated-References">perlthrtut OS-Related
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Other-References">perlthrtut Other
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perltie
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perltie-NAME">perltie NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltie-SYNOPSIS">perltie
SYNOPSIS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltie-DESCRIPTION">perltie
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltie-SEE-ALSO">perltie
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltie-BUGS">perltie
BUGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltie-AUTHOR">perltie
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perltie-Tying-Scalars">perltie Tying
Scalars</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltie-Tying-Arrays">perltie Tying
Arrays</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltie-Tying-Hashes">perltie Tying
Hashes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltie-Tying-FileHandles">perltie Tying
FileHandles</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltie-UNTIE-this-4">perltie UNTIE this
4</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltie-The-untie-Gotcha">perltie The <code>untie</code>
Gotcha</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perltodo
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perltodo-NAME">perltodo NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltodo-DESCRIPTION">perltodo
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perltooc
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perltooc-NAME">perltooc NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltooc-DESCRIPTION">perltooc
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perltoot
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perltoot-NAME">perltoot NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltoot-DESCRIPTION">perltoot
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perltrap
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perltrap-NAME">perltrap NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltrap-DESCRIPTION">perltrap
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perltrap-Awk-Traps">perltrap Awk Traps</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltrap-C_002fC_002b_002b-Traps">perltrap C/C++
Traps</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltrap-JavaScript-Traps">perltrap JavaScript
Traps</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltrap-Sed-Traps">perltrap Sed Traps</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltrap-Shell-Traps">perltrap Shell
Traps</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltrap-Perl-Traps">perltrap Perl
Traps</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlunicode
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlunicode-NAME">perlunicode NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-DESCRIPTION">perlunicode
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-BUGS">perlunicode BUGS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-SEE-ALSO">perlunicode SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlunicode-Important-Caveats">perlunicode Important
Caveats</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Byte-and-Character-Semantics">perlunicode Byte and Character
Semantics</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-ASCII-Rules-versus-Unicode-Rules">perlunicode ASCII Rules
versus Unicode Rules</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Extended-Grapheme-Clusters-_0028Logical-characters_0029">perlunicode
Extended Grapheme Clusters (Logical
characters)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Unicode-Character-Properties">perlunicode Unicode Character
Properties</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-User_002dDefined-Character-Properties">perlunicode
User-Defined Character Properties</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-User_002dDefined-Case-Mappings-_0028for-serious-hackers-only_0029">perlunicode
User-Defined Case Mappings (for serious hackers
only)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Character-Encodings-for-Input-and-Output">perlunicode
Character Encodings for Input and Output</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Unicode-Regular-Expression-Support-Level">perlunicode
Unicode Regular Expression Support Level</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Unicode-Encodings">perlunicode Unicode
Encodings</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Noncharacter-code-points">perlunicode Noncharacter code
points</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Beyond-Unicode-code-points">perlunicode Beyond Unicode code
points</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Security-Implications-of-Unicode">perlunicode Security
Implications of Unicode</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Unicode-in-Perl-on-EBCDIC">perlunicode Unicode in Perl on
EBCDIC</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Locales">perlunicode
Locales</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-When-Unicode-Does-Not-Happen">perlunicode When Unicode Does
Not Happen</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-The-_0022Unicode-Bug_0022">perlunicode The "Unicode
Bug"</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Forcing-Unicode-in-Perl-_0028Or-Unforcing-Unicode-in-Perl_0029">perlunicode
Forcing Unicode in Perl (Or Unforcing Unicode in
Perl)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Using-Unicode-in-XS">perlunicode Using Unicode in
XS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Hacking-Perl-to-work-on-earlier-Unicode-versions-_0028for-very-serious-hackers-only_0029">perlunicode
Hacking Perl to work on earlier Unicode versions (for very serious hackers
only)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Porting-code-from-perl_002d5_002e6_002eX">perlunicode
Porting code from perl-5.6.X</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Unicode Character Properties
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlunicode-General_005fCategory">perlunicode
<strong>General_Category</strong></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Bidirectional-Character-Types">perlunicode
<strong>Bidirectional Character
Types</strong></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Scripts">perlunicode
<strong>Scripts</strong></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Use-of-the-_0022Is_0022-Prefix">perlunicode <strong>Use of
the <code>"Is"</code>
Prefix</strong></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Blocks">perlunicode
<strong>Blocks</strong></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Other-Properties">perlunicode <strong>Other
Properties</strong></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-BUGS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlunicode-Interaction-with-Extensions">perlunicode Interaction with
Extensions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Speed">perlunicode Speed</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlunifaq
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlunifaq-NAME">perlunifaq NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-Q-and-A">perlunifaq Q and A</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-INTERNALS">perlunifaq
INTERNALS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-AUTHOR">perlunifaq AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-SEE-ALSO">perlunifaq SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Q and A
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlunifaq-perlunitut-isn_0027t-really-a-Unicode-tutorial_002c-is-it_003f">perlunifaq
perlunitut isn't really a Unicode tutorial, is
it?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-character-encodings-does-Perl-support_003f">perlunifaq
What character encodings does Perl support?</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-Which-version-of-perl-should-I-use_003f">perlunifaq Which
version of perl should I use?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-about-binary-data_002c-like-images_003f">perlunifaq What
about binary data, like images?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-When-should-I-decode-or-encode_003f">perlunifaq When should I
decode or encode?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-if-I-don_0027t-decode_003f">perlunifaq What if I don't
decode?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-if-I-don_0027t-encode_003f">perlunifaq What if I don't
encode?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-Is-there-a-way-to-automatically-decode-or-encode_003f">perlunifaq
Is there a way to automatically decode or
encode?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-if-I-don_0027t-know-which-encoding-was-used_003f">perlunifaq
What if I don't know which encoding was
used?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-Can-I-use-Unicode-in-my-Perl-sources_003f">perlunifaq Can I
use Unicode in my Perl sources?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-Data_003a_003aDumper-doesn_0027t-restore-the-UTF8-flag_003b-is-it-broken_003f">perlunifaq
Data::Dumper doesn't restore the UTF8 flag; is it
broken?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-Why-do-regex-character-classes-sometimes-match-only-in-the-ASCII-range_003f">perlunifaq
Why do regex character classes sometimes match only in the ASCII
range?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-Why-do-some-characters-not-uppercase-or-lowercase-correctly_003f">perlunifaq
Why do some characters not uppercase or lowercase
correctly?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-How-can-I-determine-if-a-string-is-a-text-string-or-a-binary-string_003f">perlunifaq
How can I determine if a string is a text string or a binary
string?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-How-do-I-convert-from-encoding-FOO-to-encoding-BAR_003f">perlunifaq
How do I convert from encoding FOO to encoding
BAR?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-are-decode_005futf8-and-encode_005futf8_003f">perlunifaq
What are <code>decode_utf8</code> and
<code>encode_utf8</code>?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-is-a-_0022wide-character_0022_003f">perlunifaq What is a
"wide character"?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-INTERNALS
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlunifaq-What-is-_0022the-UTF8-flag_0022_003f">perlunifaq What is
"the UTF8 flag"?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-about-the-use-bytes-pragma_003f">perlunifaq What about
the <code>use bytes</code> pragma?</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-about-the-use-encoding-pragma_003f">perlunifaq What
about the <code>use encoding</code> pragma?</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-is-the-difference-between-_003aencoding-and-_003autf8_003f">perlunifaq
What is the difference between <code>:encoding</code> and
<code>:utf8</code>?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What_0027s-the-difference-between-UTF_002d8-and-utf8_003f">perlunifaq
What's the difference between <code>UTF-8</code> and
<code>utf8</code>?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-I-lost-track_003b-what-encoding-is-the-internal-format-really_003f">perlunifaq
I lost track; what encoding is the internal format
really?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perluniintro
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perluniintro-NAME">perluniintro NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-DESCRIPTION">perluniintro
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-UNICODE-IN-OLDER-PERLS">perluniintro UNICODE IN OLDER
PERLS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-SEE-ALSO">perluniintro SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-ACKNOWLEDGMENTS">perluniintro
ACKNOWLEDGMENTS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-AUTHOR_002c-COPYRIGHT_002c-AND-LICENSE">perluniintro
AUTHOR, COPYRIGHT, AND LICENSE</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perluniintro-Unicode">perluniintro
Unicode</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Perl_0027s-Unicode-Support">perluniintro Perl's Unicode
Support</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Perl_0027s-Unicode-Model">perluniintro Perl's Unicode
Model</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Unicode-and-EBCDIC">perluniintro Unicode and
EBCDIC</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Creating-Unicode">perluniintro Creating
Unicode</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Handling-Unicode">perluniintro Handling
Unicode</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Legacy-Encodings">perluniintro Legacy
Encodings</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Unicode-I_002fO">perluniintro Unicode
I/O</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Displaying-Unicode-As-Text">perluniintro Displaying Unicode
As Text</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Special-Cases">perluniintro Special
Cases</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Advanced-Topics">perluniintro Advanced
Topics</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Miscellaneous">perluniintro
Miscellaneous</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Questions-With-Answers">perluniintro Questions With
Answers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Hexadecimal-Notation">perluniintro Hexadecimal
Notation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Further-Resources">perluniintro Further
Resources</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Creating Unicode
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perluniintro-Earlier-releases-caveats">perluniintro Earlier releases
caveats</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlunitut
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlunitut-NAME">perlunitut NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-DESCRIPTION">perlunitut
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-SUMMARY">perlunitut SUMMARY</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-Q-and-A-_0028or-FAQ_0029">perlunitut Q and A (or
FAQ)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-ACKNOWLEDGEMENTS">perlunitut
ACKNOWLEDGEMENTS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-AUTHOR">perlunitut AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-SEE-ALSO">perlunitut SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlunitut-Definitions">perlunitut
Definitions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-Your-new-toolkit">perlunitut Your new
toolkit</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-I_002fO-flow-_0028the-actual-5-minute-tutorial_0029">perlunitut
I/O flow (the actual 5 minute tutorial)</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Definitions
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlunitut-Unicode">perlunitut Unicode</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-UTF_002d8">perlunitut UTF-8</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-Text-strings-_0028character-strings_0029">perlunitut Text
strings (character strings)</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-Binary-strings-_0028byte-strings_0029">perlunitut Binary
strings (byte strings)</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-Encoding">perlunitut
Encoding</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-Decoding">perlunitut
Decoding</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-Internal-format">perlunitut Internal
format</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlutil
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlutil-NAME">perlutil NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlutil-DESCRIPTION">perlutil
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlutil-LIST-OF-UTILITIES">perlutil LIST OF
UTILITIES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlutil-SEE-ALSO">perlutil
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-LIST OF UTILITIES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlutil-Documentation">perlutil
Documentation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlutil-Converters">perlutil
Converters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlutil-Administration">perlutil
Administration</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlutil-Development">perlutil
Development</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlutil-General-tools">perlutil General
tools</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlutil-Installation">perlutil
Installation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlvar
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlvar-NAME">perlvar NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvar-DESCRIPTION">perlvar
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvar-SPECIAL-VARIABLES">perlvar SPECIAL
VARIABLES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-DESCRIPTION
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlvar-The-Syntax-of-Variable-Names">perlvar The Syntax of Variable
Names</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-SPECIAL VARIABLES
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlvar-General-Variables">perlvar General
Variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvar-Variables-related-to-regular-expressions">perlvar Variables
related to regular expressions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvar-Variables-related-to-filehandles">perlvar Variables related to
filehandles</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvar-Error-Variables">perlvar Error
Variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvar-Variables-related-to-the-interpreter-state">perlvar Variables
related to the interpreter state</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvar-Deprecated-and-removed-variables">perlvar Deprecated and removed
variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Variables related to regular expressions
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlvar-Performance-issues">perlvar Performance
issues</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Variables related to filehandles
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlvar-Variables-related-to-formats">perlvar Variables related to
formats</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-perlvms
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlvms-NAME">perlvms NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-DESCRIPTION">perlvms
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Installation">perlvms
Installation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Organization-of-Perl-Images">perlvms Organization of Perl
Images</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-File-specifications">perlvms File
specifications</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-PERL5LIB-and-PERLLIB">perlvms PERL5LIB and
PERLLIB</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-The-Perl-Forked-Debugger">perlvms The Perl Forked
Debugger</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-PERL_005fVMS_005fEXCEPTION_005fDEBUG">perlvms
PERL_VMS_EXCEPTION_DEBUG</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Command-line">perlvms Command
line</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Perl-functions">perlvms Perl
functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Perl-variables">perlvms Perl
variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Standard-modules-with-VMS_002dspecific-differences">perlvms
Standard modules with VMS-specific
differences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Revision-date">perlvms Revision
date</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlvms-AUTHOR">perlvms
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Organization of Perl Images
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlvms-Core-Images">perlvms Core
Images</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Perl-Extensions">perlvms Perl
Extensions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Installing-static-extensions">perlvms Installing static
extensions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Installing-dynamic-extensions">perlvms Installing dynamic
extensions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-File specifications
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlvms-Syntax">perlvms Syntax</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Filename-Case">perlvms Filename
Case</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Symbolic-Links">perlvms Symbolic
Links</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Wildcard-expansion">perlvms Wildcard
expansion</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlvms-Pipes">perlvms
Pipes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Command line
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlvms-I_002fO-redirection-and-backgrounding">perlvms I/O redirection
and backgrounding</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Command-line-switches">perlvms Command line
switches</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
-
-Standard modules with VMS-specific differences
-
-</pre></th></tr><tr><td align="left" valign="top">• <a
href="#perlvms-SDBM_005fFile">perlvms
SDBM_File</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perl"></a>
-<div class="header">
-<p>
-Next: <a href="#perlapio" accesskey="n" rel="next">perlapio</a>, Previous: <a
href="#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="#Top" accesskey="u"
rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="perl-1"></a>
-<h2 class="chapter">1 perl</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perl-NAME"
accesskey="1">perl NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-SYNOPSIS"
accesskey="2">perl SYNOPSIS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-GETTING-HELP"
accesskey="3">perl GETTING HELP</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-DESCRIPTION"
accesskey="4">perl DESCRIPTION</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-AVAILABILITY"
accesskey="5">perl AVAILABILITY</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-ENVIRONMENT"
accesskey="6">perl ENVIRONMENT</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-AUTHOR"
accesskey="7">perl AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-FILES"
accesskey="8">perl FILES</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-SEE-ALSO"
accesskey="9">perl SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-DIAGNOSTICS">perl
DIAGNOSTICS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-BUGS">perl
BUGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-NOTES">perl
NOTES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perl-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-SYNOPSIS" accesskey="n" rel="next">perl SYNOPSIS</a>, Up:
<a href="#perl" accesskey="u" rel="up">perl</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME"></a>
-<h3 class="section">1.1 NAME</h3>
-
-<p>perl - The Perl 5 language interpreter
-</p>
-<hr>
-<a name="perl-SYNOPSIS"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-GETTING-HELP" accesskey="n" rel="next">perl GETTING
HELP</a>, Previous: <a href="#perl-NAME" accesskey="p" rel="prev">perl
NAME</a>, Up: <a href="#perl" accesskey="u" rel="up">perl</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SYNOPSIS"></a>
-<h3 class="section">1.2 SYNOPSIS</h3>
-
-<p><strong>perl</strong> [ <strong><span
class="nolinebreak">-sTtuUWX</span></strong> ]<!-- /@w -->
- [ <strong><span
class="nolinebreak">-hv</span></strong> ] [ <strong><span
class="nolinebreak">-V</span></strong>[:<em>configvar</em>] ]<!-- /@w -->
- [ <strong><span
class="nolinebreak">-cw</span></strong> ] [ <strong><span
class="nolinebreak">-d</span></strong>[<strong>t</strong>][:<em>debugger</em>] ] [ <strong><span
class="nolinebreak">-D</span></strong>[<em>number/list</em>] ]<!-- /@w -->
- [ <strong><span
class="nolinebreak">-pna</span></strong> ] [ <strong><span
class="nolinebreak">-F</span></strong><em>pattern</em> ] [ <strong><span
class="nolinebreak">-l</span></strong>[<em>octal</em>] ] [ <strong><span
class="nolinebreak">-0</span></strong>[<em>octal/hexadecimal</em>] ]<!--
/@w -->
- [ <strong><span
class="nolinebreak">-I</span></strong><em>dir</em> ] [ <strong><span
class="nolinebreak">-m</span></strong>[<strong><span
class="nolinebreak">-</span></strong>]<em>module</em> ] [ <strong><span
class="nolinebreak">-M</span></strong>[<strong><span
class="nolinebreak">-</span></strong>]<em>’module...’</em> ] [ <strong><span
class="nolinebreak">-f</span></strong> ]<!-- /@w -->
- [ <strong><span
class="nolinebreak">-C</span> [<em>number/list</em>] </strong>]<!--
/@w -->
- [ <strong><span class="nolinebreak">-S</span></strong> ]<!--
/@w -->
- [ <strong><span
class="nolinebreak">-x</span></strong>[<em>dir</em>] ]<!-- /@w -->
- [ <strong><span
class="nolinebreak">-i</span></strong>[<em>extension</em>] ]<!-- /@w -->
- [ [<strong><span
class="nolinebreak">-e</span></strong>|<strong><span
class="nolinebreak">-E</span></strong>] <em>’command’</em> ] [ <strong>–</strong> ] [ <em>programfile</em> ] [ <em>argument</em> ]...<!--
/@w -->
-</p>
-<p>For more information on these options, you can run <code>perldoc
perlrun</code>.
-</p>
-<hr>
-<a name="perl-GETTING-HELP"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-DESCRIPTION" accesskey="n" rel="next">perl
DESCRIPTION</a>, Previous: <a href="#perl-SYNOPSIS" accesskey="p"
rel="prev">perl SYNOPSIS</a>, Up: <a href="#perl" accesskey="u"
rel="up">perl</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="GETTING-HELP"></a>
-<h3 class="section">1.3 GETTING HELP</h3>
-
-<p>The <samp>perldoc</samp> program gives you access to all the documentation
that comes
-with Perl. You can get more documentation, tutorials and community support
-online at <a href="http://www.perl.org/";>http://www.perl.org/</a>.
-</p>
-<p>If you’re new to Perl, you should start by running <code>perldoc
perlintro</code>,
-which is a general intro for beginners and provides some background to help
-you navigate the rest of Perl’s extensive documentation. Run
<code>perldoc
-perldoc</code> to learn more things you can do with <samp>perldoc</samp>.
-</p>
-<p>For ease of access, the Perl manual has been split up into several sections.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perl-Overview"
accesskey="1">perl Overview</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-Tutorials"
accesskey="2">perl Tutorials</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-Reference-Manual"
accesskey="3">perl Reference Manual</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perl-Internals-and-C-Language-Interface" accesskey="4">perl Internals
and C Language Interface</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-Miscellaneous"
accesskey="5">perl Miscellaneous</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-Language_002dSpecific"
accesskey="6">perl Language-Specific</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perl-Platform_002dSpecific"
accesskey="7">perl Platform-Specific</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perl-Stubs-for-Deleted-Documents" accesskey="8">perl Stubs for Deleted
Documents</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perl-Overview"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-Tutorials" accesskey="n" rel="next">perl Tutorials</a>,
Up: <a href="#perl-GETTING-HELP" accesskey="u" rel="up">perl GETTING HELP</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Overview"></a>
-<h4 class="subsection">1.3.1 Overview</h4>
-
-<pre class="verbatim"> perl Perl overview (this section)
- perlintro Perl introduction for beginners
- perlrun Perl execution and options
- perltoc Perl documentation table of contents
-</pre>
-<hr>
-<a name="perl-Tutorials"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-Reference-Manual" accesskey="n" rel="next">perl Reference
Manual</a>, Previous: <a href="#perl-Overview" accesskey="p" rel="prev">perl
Overview</a>, Up: <a href="#perl-GETTING-HELP" accesskey="u" rel="up">perl
GETTING HELP</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Tutorials"></a>
-<h4 class="subsection">1.3.2 Tutorials</h4>
-
-<pre class="verbatim"> perlreftut Perl references short
introduction
- perldsc Perl data structures intro
- perllol Perl data structures: arrays of arrays
-
- perlrequick Perl regular expressions quick start
- perlretut Perl regular expressions tutorial
-
- perlootut Perl OO tutorial for beginners
-
- perlperf Perl Performance and Optimization Techniques
-
- perlstyle Perl style guide
-
- perlcheat Perl cheat sheet
- perltrap Perl traps for the unwary
- perldebtut Perl debugging tutorial
-
- perlfaq Perl frequently asked questions
- perlfaq1 General Questions About Perl
- perlfaq2 Obtaining and Learning about Perl
- perlfaq3 Programming Tools
- perlfaq4 Data Manipulation
- perlfaq5 Files and Formats
- perlfaq6 Regexes
- perlfaq7 Perl Language Issues
- perlfaq8 System Interaction
- perlfaq9 Networking
-</pre>
-<hr>
-<a name="perl-Reference-Manual"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-Internals-and-C-Language-Interface" accesskey="n"
rel="next">perl Internals and C Language Interface</a>, Previous: <a
href="#perl-Tutorials" accesskey="p" rel="prev">perl Tutorials</a>, Up: <a
href="#perl-GETTING-HELP" accesskey="u" rel="up">perl GETTING HELP</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Reference-Manual"></a>
-<h4 class="subsection">1.3.3 Reference Manual</h4>
-
-<pre class="verbatim"> perlsyn Perl syntax
- perldata Perl data structures
- perlop Perl operators and precedence
- perlsub Perl subroutines
- perlfunc Perl built-in functions
- perlopentut Perl open() tutorial
- perlpacktut Perl pack() and unpack() tutorial
- perlpod Perl plain old documentation
- perlpodspec Perl plain old documentation format specification
- perlpodstyle Perl POD style guide
- perldiag Perl diagnostic messages
- perllexwarn Perl warnings and their control
- perldebug Perl debugging
- perlvar Perl predefined variables
- perlre Perl regular expressions, the rest of the story
- perlrebackslash Perl regular expression backslash sequences
- perlrecharclass Perl regular expression character classes
- perlreref Perl regular expressions quick reference
- perlref Perl references, the rest of the story
- perlform Perl formats
- perlobj Perl objects
- perltie Perl objects hidden behind simple variables
- perldbmfilter Perl DBM filters
-
- perlipc Perl interprocess communication
- perlfork Perl fork() information
- perlnumber Perl number semantics
-
- perlthrtut Perl threads tutorial
-
- perlport Perl portability guide
- perllocale Perl locale support
- perluniintro Perl Unicode introduction
- perlunicode Perl Unicode support
- perlunicook Perl Unicode cookbook
- perlunifaq Perl Unicode FAQ
- perluniprops Index of Unicode properties in Perl
- perlunitut Perl Unicode tutorial
- perlebcdic Considerations for running Perl on EBCDIC platforms
-
- perlsec Perl security
-
- perlmod Perl modules: how they work
- perlmodlib Perl modules: how to write and use
- perlmodstyle Perl modules: how to write modules with style
- perlmodinstall Perl modules: how to install from CPAN
- perlnewmod Perl modules: preparing a new module for distribution
- perlpragma Perl modules: writing a user pragma
-
- perlutil utilities packaged with the Perl distribution
-
- perlfilter Perl source filters
-
- perldtrace Perl's support for DTrace
-
- perlglossary Perl Glossary
-</pre>
-<hr>
-<a name="perl-Internals-and-C-Language-Interface"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-Miscellaneous" accesskey="n" rel="next">perl
Miscellaneous</a>, Previous: <a href="#perl-Reference-Manual" accesskey="p"
rel="prev">perl Reference Manual</a>, Up: <a href="#perl-GETTING-HELP"
accesskey="u" rel="up">perl GETTING HELP</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Internals-and-C-Language-Interface"></a>
-<h4 class="subsection">1.3.4 Internals and C Language Interface</h4>
-
-<pre class="verbatim"> perlembed Perl ways to embed perl in your
C or C++ application
- perldebguts Perl debugging guts and tips
- perlxstut Perl XS tutorial
- perlxs Perl XS application programming interface
- perlxstypemap Perl XS C/Perl type conversion tools
- perlclib Internal replacements for standard C library functions
- perlguts Perl internal functions for those doing extensions
- perlcall Perl calling conventions from C
- perlmroapi Perl method resolution plugin interface
- perlreapi Perl regular expression plugin interface
- perlreguts Perl regular expression engine internals
-
- perlapi Perl API listing (autogenerated)
- perlintern Perl internal functions (autogenerated)
- perliol C API for Perl's implementation of IO in Layers
- perlapio Perl internal IO abstraction interface
-
- perlhack Perl hackers guide
- perlsource Guide to the Perl source tree
- perlinterp Overview of the Perl interpreter source and how it
works
- perlhacktut Walk through the creation of a simple C code patch
- perlhacktips Tips for Perl core C code hacking
- perlpolicy Perl development policies
- perlgit Using git with the Perl repository
-</pre>
-<hr>
-<a name="perl-Miscellaneous"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-Language_002dSpecific" accesskey="n" rel="next">perl
Language-Specific</a>, Previous: <a
href="#perl-Internals-and-C-Language-Interface" accesskey="p" rel="prev">perl
Internals and C Language Interface</a>, Up: <a href="#perl-GETTING-HELP"
accesskey="u" rel="up">perl GETTING HELP</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Miscellaneous"></a>
-<h4 class="subsection">1.3.5 Miscellaneous</h4>
-
-<pre class="verbatim"> perlbook Perl book information
- perlcommunity Perl community information
-
- perldoc Look up Perl documentation in Pod format
-
- perlhist Perl history records
- perldelta Perl changes since previous version
- perl5221delta Perl changes in version 5.22.1
- perl5220delta Perl changes in version 5.22.0
- perl5203delta Perl changes in version 5.20.3
- perl5202delta Perl changes in version 5.20.2
- perl5201delta Perl changes in version 5.20.1
- perl5200delta Perl changes in version 5.20.0
- perl5184delta Perl changes in version 5.18.4
- perl5182delta Perl changes in version 5.18.2
- perl5181delta Perl changes in version 5.18.1
- perl5180delta Perl changes in version 5.18.0
- perl5163delta Perl changes in version 5.16.3
- perl5162delta Perl changes in version 5.16.2
- perl5161delta Perl changes in version 5.16.1
- perl5160delta Perl changes in version 5.16.0
- perl5144delta Perl changes in version 5.14.4
- perl5143delta Perl changes in version 5.14.3
- perl5142delta Perl changes in version 5.14.2
- perl5141delta Perl changes in version 5.14.1
- perl5140delta Perl changes in version 5.14.0
- perl5125delta Perl changes in version 5.12.5
- perl5124delta Perl changes in version 5.12.4
- perl5123delta Perl changes in version 5.12.3
- perl5122delta Perl changes in version 5.12.2
- perl5121delta Perl changes in version 5.12.1
- perl5120delta Perl changes in version 5.12.0
- perl5101delta Perl changes in version 5.10.1
- perl5100delta Perl changes in version 5.10.0
- perl589delta Perl changes in version 5.8.9
- perl588delta Perl changes in version 5.8.8
- perl587delta Perl changes in version 5.8.7
- perl586delta Perl changes in version 5.8.6
- perl585delta Perl changes in version 5.8.5
- perl584delta Perl changes in version 5.8.4
- perl583delta Perl changes in version 5.8.3
- perl582delta Perl changes in version 5.8.2
- perl581delta Perl changes in version 5.8.1
- perl58delta Perl changes in version 5.8.0
- perl561delta Perl changes in version 5.6.1
- perl56delta Perl changes in version 5.6
- perl5005delta Perl changes in version 5.005
- perl5004delta Perl changes in version 5.004
-
- perlexperiment A listing of experimental features in Perl
-
- perlartistic Perl Artistic License
- perlgpl GNU General Public License
-</pre>
-<hr>
-<a name="perl-Language_002dSpecific"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-Platform_002dSpecific" accesskey="n" rel="next">perl
Platform-Specific</a>, Previous: <a href="#perl-Miscellaneous" accesskey="p"
rel="prev">perl Miscellaneous</a>, Up: <a href="#perl-GETTING-HELP"
accesskey="u" rel="up">perl GETTING HELP</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Language_002dSpecific"></a>
-<h4 class="subsection">1.3.6 Language-Specific</h4>
-
-<pre class="verbatim"> perlcn Perl for Simplified Chinese (in
EUC-CN)
- perljp Perl for Japanese (in EUC-JP)
- perlko Perl for Korean (in EUC-KR)
- perltw Perl for Traditional Chinese (in Big5)
-</pre>
-<hr>
-<a name="perl-Platform_002dSpecific"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-Stubs-for-Deleted-Documents" accesskey="n"
rel="next">perl Stubs for Deleted Documents</a>, Previous: <a
href="#perl-Language_002dSpecific" accesskey="p" rel="prev">perl
Language-Specific</a>, Up: <a href="#perl-GETTING-HELP" accesskey="u"
rel="up">perl GETTING HELP</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Platform_002dSpecific"></a>
-<h4 class="subsection">1.3.7 Platform-Specific</h4>
-
-<pre class="verbatim"> perlaix Perl notes for AIX
- perlamiga Perl notes for AmigaOS
- perlandroid Perl notes for Android
- perlbs2000 Perl notes for POSIX-BC BS2000
- perlce Perl notes for WinCE
- perlcygwin Perl notes for Cygwin
- perldos Perl notes for DOS
- perlfreebsd Perl notes for FreeBSD
- perlhaiku Perl notes for Haiku
- perlhpux Perl notes for HP-UX
- perlhurd Perl notes for Hurd
- perlirix Perl notes for Irix
- perllinux Perl notes for Linux
- perlmacos Perl notes for Mac OS (Classic)
- perlmacosx Perl notes for Mac OS X
- perlnetware Perl notes for NetWare
- perlopenbsd Perl notes for OpenBSD
- perlos2 Perl notes for OS/2
- perlos390 Perl notes for OS/390
- perlos400 Perl notes for OS/400
- perlplan9 Perl notes for Plan 9
- perlqnx Perl notes for QNX
- perlriscos Perl notes for RISC OS
- perlsolaris Perl notes for Solaris
- perlsymbian Perl notes for Symbian
- perlsynology Perl notes for Synology
- perltru64 Perl notes for Tru64
- perlvms Perl notes for VMS
- perlvos Perl notes for Stratus VOS
- perlwin32 Perl notes for Windows
-</pre>
-<hr>
-<a name="perl-Stubs-for-Deleted-Documents"></a>
-<div class="header">
-<p>
-Previous: <a href="#perl-Platform_002dSpecific" accesskey="p" rel="prev">perl
Platform-Specific</a>, Up: <a href="#perl-GETTING-HELP" accesskey="u"
rel="up">perl GETTING HELP</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Stubs-for-Deleted-Documents"></a>
-<h4 class="subsection">1.3.8 Stubs for Deleted Documents</h4>
-
-<pre class="verbatim"> perlboot
- perlbot
- perlrepository
- perltodo
- perltooc
- perltoot
-</pre>
-<p>On a Unix-like system, these documentation files will usually also be
-available as manpages for use with the <samp>man</samp> program.
-</p>
-<p>Some documentation is not available as man pages, so if a
-cross-reference is not found by man, try it with <a
href="perldoc.html#Top">(perldoc)</a>. Perldoc can
-also take you directly to documentation for functions (with the
<strong>-f</strong>
-switch). See <code>perldoc --help</code> (or <code>perldoc perldoc</code> or
<code>man perldoc</code>)
-for other helpful options <a href="perldoc.html#Top">(perldoc)</a> has to
offer.
-</p>
-<p>In general, if something strange has gone wrong with your program and
you’re
-not sure where you should look for help, try making your code comply with
-<strong>use strict</strong> and <strong>use warnings</strong>. These will
often point out exactly
-where the trouble is.
-</p>
-<hr>
-<a name="perl-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-AVAILABILITY" accesskey="n" rel="next">perl
AVAILABILITY</a>, Previous: <a href="#perl-GETTING-HELP" accesskey="p"
rel="prev">perl GETTING HELP</a>, Up: <a href="#perl" accesskey="u"
rel="up">perl</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION"></a>
-<h3 class="section">1.4 DESCRIPTION</h3>
-
-<p>Perl officially stands for Practical Extraction and Report Language,
-except when it doesn’t.
-</p>
-<p>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 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.
-</p>
-<p>The language is intended to be practical (easy to use, efficient,
-complete) rather than beautiful (tiny, elegant, minimal). It combines
-(in the author’s opinion, anyway) some of the best features of
<strong>sed</strong>,
-<strong>awk</strong>, and <strong>sh</strong>, making it familiar and easy to
use for Unix users to
-whip up quick solutions to annoying problems. Its general-purpose
-programming facilities support procedural, functional, and
-object-oriented programming paradigms, making Perl a comfortable
-language for the long haul on major projects, whatever your bent.
-</p>
-<p>Perl’s roots in text processing haven’t been forgotten over the
years.
-It still boasts some of the most powerful regular expressions to be
-found anywhere, and its support for Unicode text is world-class. It
-handles all kinds of structured text, too, through an extensive
-collection of extensions. Those libraries, collected in the CPAN,
-provide ready-made solutions to an astounding array of problems. When
-they haven’t set the standard themselves, they steal from the best
-– just like Perl itself.
-</p>
-<hr>
-<a name="perl-AVAILABILITY"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-ENVIRONMENT" accesskey="n" rel="next">perl
ENVIRONMENT</a>, Previous: <a href="#perl-DESCRIPTION" accesskey="p"
rel="prev">perl DESCRIPTION</a>, Up: <a href="#perl" accesskey="u"
rel="up">perl</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AVAILABILITY"></a>
-<h3 class="section">1.5 AVAILABILITY</h3>
-
-<p>Perl is available for most operating systems, including virtually
-all Unix-like platforms. See <a href="#perlport-Supported-Platforms">perlport
Supported Platforms</a>
-for a listing.
-</p>
-<hr>
-<a name="perl-ENVIRONMENT"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-AUTHOR" accesskey="n" rel="next">perl AUTHOR</a>,
Previous: <a href="#perl-AVAILABILITY" accesskey="p" rel="prev">perl
AVAILABILITY</a>, Up: <a href="#perl" accesskey="u" rel="up">perl</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="ENVIRONMENT"></a>
-<h3 class="section">1.6 ENVIRONMENT</h3>
-
-<p>See <a href="#perlrun-NAME">perlrun NAME</a>.
-</p>
-<hr>
-<a name="perl-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-FILES" accesskey="n" rel="next">perl FILES</a>, Previous:
<a href="#perl-ENVIRONMENT" accesskey="p" rel="prev">perl ENVIRONMENT</a>, Up:
<a href="#perl" accesskey="u" rel="up">perl</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR"></a>
-<h3 class="section">1.7 AUTHOR</h3>
-
-<p>Larry Wall <address@hidden>, with the help of oodles of other folks.
-</p>
-<p>If your Perl success stories and testimonials may be of help to others
-who wish to advocate the use of Perl in their applications,
-or if you wish to simply express your gratitude to Larry and the
-Perl developers, please write to address@hidden .
-</p>
-<hr>
-<a name="perl-FILES"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-SEE-ALSO" accesskey="n" rel="next">perl SEE ALSO</a>,
Previous: <a href="#perl-AUTHOR" accesskey="p" rel="prev">perl AUTHOR</a>, Up:
<a href="#perl" accesskey="u" rel="up">perl</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="FILES"></a>
-<h3 class="section">1.8 FILES</h3>
-
-<pre class="verbatim"> "@INC" locations of perl
libraries
-</pre>
-<hr>
-<a name="perl-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-DIAGNOSTICS" accesskey="n" rel="next">perl
DIAGNOSTICS</a>, Previous: <a href="#perl-FILES" accesskey="p" rel="prev">perl
FILES</a>, Up: <a href="#perl" accesskey="u" rel="up">perl</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO"></a>
-<h3 class="section">1.9 SEE ALSO</h3>
-
-<pre class="verbatim"> http://www.perl.org/ the Perl homepage
- http://www.perl.com/ Perl articles (O'Reilly)
- http://www.cpan.org/ the Comprehensive Perl Archive
- http://www.pm.org/ the Perl Mongers
-</pre>
-<hr>
-<a name="perl-DIAGNOSTICS"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-BUGS" accesskey="n" rel="next">perl BUGS</a>, Previous:
<a href="#perl-SEE-ALSO" accesskey="p" rel="prev">perl SEE ALSO</a>, Up: <a
href="#perl" accesskey="u" rel="up">perl</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DIAGNOSTICS"></a>
-<h3 class="section">1.10 DIAGNOSTICS</h3>
-
-<p>Using the <code>use strict</code> pragma ensures that all variables are
properly
-declared and prevents other misuses of legacy Perl features.
-</p>
-<p>The <code>use warnings</code> pragma produces some lovely diagnostics. One
can
-also use the <strong>-w</strong> flag, but its use is normally discouraged,
because
-it gets applied to all executed Perl code, including that not under
-your control.
-</p>
-<p>See <a href="#perldiag-NAME">perldiag NAME</a> for explanations of all
Perl’s diagnostics. The <code>use
-diagnostics</code> pragma automatically turns Perl’s normally terse
warnings
-and errors into these longer forms.
-</p>
-<p>Compilation errors will tell you the line number of the error, with an
-indication of the next token or token type that was to be examined.
-(In a script passed to Perl via <strong>-e</strong> switches, each
-<strong>-e</strong> is counted as one line.)
-</p>
-<p>Setuid scripts have additional constraints that can produce error
-messages such as "Insecure dependency". See <a
href="#perlsec-NAME">perlsec NAME</a>.
-</p>
-<p>Did we mention that you should definitely consider using the <strong>use
warnings</strong>
-pragma?
-</p>
-<hr>
-<a name="perl-BUGS"></a>
-<div class="header">
-<p>
-Next: <a href="#perl-NOTES" accesskey="n" rel="next">perl NOTES</a>, Previous:
<a href="#perl-DIAGNOSTICS" accesskey="p" rel="prev">perl DIAGNOSTICS</a>, Up:
<a href="#perl" accesskey="u" rel="up">perl</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="BUGS"></a>
-<h3 class="section">1.11 BUGS</h3>
-
-<p>The behavior implied by the <strong>use warnings</strong> pragma is not
mandatory.
-</p>
-<p>Perl is at the mercy of your machine’s definitions of various
-operations such as type casting, atof(), and floating-point
-output with sprintf().
-</p>
-<p>If your stdio requires a seek or eof between reads and writes on a
-particular stream, so does Perl. (This doesn’t apply to sysread()
-and syswrite().)
-</p>
-<p>While none of the built-in data types have any arbitrary size limits
-(apart from memory size), there are still a few arbitrary limits: a
-given variable name may not be longer than 251 characters. Line numbers
-displayed by diagnostics are internally stored as short integers,
-so they are limited to a maximum of 65535 (higher numbers usually being
-affected by wraparound).
-</p>
-<p>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 <code>perl -V</code>) to address@hidden . If you’ve
succeeded
-in compiling perl, the <a href="perlbug.html#Top">(perlbug)</a> script in the
<samp>utils/</samp> subdirectory
-can be used to help mail in a bug report.
-</p>
-<p>Perl actually stands for Pathologically Eclectic Rubbish Lister, but
-don’t tell anyone I said that.
-</p>
-<hr>
-<a name="perl-NOTES"></a>
-<div class="header">
-<p>
-Previous: <a href="#perl-BUGS" accesskey="p" rel="prev">perl BUGS</a>, Up: <a
href="#perl" accesskey="u" rel="up">perl</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NOTES"></a>
-<h3 class="section">1.12 NOTES</h3>
-
-<p>The Perl motto is "There’s more than one way to do it."
Divining
-how many more is left as an exercise to the reader.
-</p>
-<p>The three principal virtues of a programmer are Laziness,
-Impatience, and Hubris. See the Camel Book for why.
-</p>
-<hr>
-<a name="perlapio"></a>
-<div class="header">
-<p>
-Next: <a href="#perlartistic" accesskey="n" rel="next">perlartistic</a>,
Previous: <a href="#perl" accesskey="p" rel="prev">perl</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlapio-1"></a>
-<h2 class="chapter">2 perlapio</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlapio-NAME"
accesskey="1">perlapio NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlapio-SYNOPSIS"
accesskey="2">perlapio SYNOPSIS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlapio-DESCRIPTION"
accesskey="3">perlapio DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlapio-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlapio-SYNOPSIS" accesskey="n" rel="next">perlapio
SYNOPSIS</a>, Up: <a href="#perlapio" accesskey="u" rel="up">perlapio</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-1"></a>
-<h3 class="section">2.1 NAME</h3>
-
-<p>perlapio - perl’s IO abstraction interface.
-</p>
-<hr>
-<a name="perlapio-SYNOPSIS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlapio-DESCRIPTION" accesskey="n" rel="next">perlapio
DESCRIPTION</a>, Previous: <a href="#perlapio-NAME" accesskey="p"
rel="prev">perlapio NAME</a>, Up: <a href="#perlapio" accesskey="u"
rel="up">perlapio</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SYNOPSIS-1"></a>
-<h3 class="section">2.2 SYNOPSIS</h3>
-
-<pre class="verbatim"> #define PERLIO_NOT_STDIO 0 /* For co-existence
with stdio only */
- #include <perlio.h> /* Usually via #include <perl.h>
*/
-
- PerlIO *PerlIO_stdin(void);
- PerlIO *PerlIO_stdout(void);
- PerlIO *PerlIO_stderr(void);
-
- PerlIO *PerlIO_open(const char *path,const char *mode);
- PerlIO *PerlIO_fdopen(int fd, const char *mode);
- PerlIO *PerlIO_reopen(const char *path, const char *mode, PerlIO *old);
/* deprecated */
- int PerlIO_close(PerlIO *f);
-
- int PerlIO_stdoutf(const char *fmt,...)
- int PerlIO_puts(PerlIO *f,const char *string);
- int PerlIO_putc(PerlIO *f,int ch);
- SSize_t PerlIO_write(PerlIO *f,const void *buf,size_t numbytes);
- int PerlIO_printf(PerlIO *f, const char *fmt,...);
- int PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args);
- int PerlIO_flush(PerlIO *f);
-
- int PerlIO_eof(PerlIO *f);
- int PerlIO_error(PerlIO *f);
- void PerlIO_clearerr(PerlIO *f);
-
- int PerlIO_getc(PerlIO *d);
- int PerlIO_ungetc(PerlIO *f,int ch);
- SSize_t PerlIO_read(PerlIO *f, void *buf, size_t numbytes);
-
- int PerlIO_fileno(PerlIO *f);
-
- void PerlIO_setlinebuf(PerlIO *f);
-
- Off_t PerlIO_tell(PerlIO *f);
- int PerlIO_seek(PerlIO *f, Off_t offset, int whence);
- void PerlIO_rewind(PerlIO *f);
-
- int PerlIO_getpos(PerlIO *f, SV *save); /* prototype changed */
- int PerlIO_setpos(PerlIO *f, SV *saved); /* prototype changed */
-
- int PerlIO_fast_gets(PerlIO *f);
- int PerlIO_has_cntptr(PerlIO *f);
- SSize_t PerlIO_get_cnt(PerlIO *f);
- char *PerlIO_get_ptr(PerlIO *f);
- void PerlIO_set_ptrcnt(PerlIO *f, char *ptr, SSize_t count);
-
- int PerlIO_canset_cnt(PerlIO *f); /* deprecated */
- void PerlIO_set_cnt(PerlIO *f, int count); /* deprecated */
-
- int PerlIO_has_base(PerlIO *f);
- char *PerlIO_get_base(PerlIO *f);
- SSize_t PerlIO_get_bufsiz(PerlIO *f);
-
- PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode);
- FILE *PerlIO_exportFILE(PerlIO *f, int flags);
- FILE *PerlIO_findFILE(PerlIO *f);
- void PerlIO_releaseFILE(PerlIO *f,FILE *stdio);
-
- int PerlIO_apply_layers(PerlIO *f, const char *mode, const char
*layers);
- int PerlIO_binmode(PerlIO *f, int ptype, int imode, const char
*layers);
- void PerlIO_debug(const char *fmt,...)
-</pre>
-<hr>
-<a name="perlapio-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlapio-SYNOPSIS" accesskey="p" rel="prev">perlapio
SYNOPSIS</a>, Up: <a href="#perlapio" accesskey="u" rel="up">perlapio</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-1"></a>
-<h3 class="section">2.3 DESCRIPTION</h3>
-
-<p>Perl’s source code, and extensions that want maximum portability,
-should use the above functions instead of those defined in ANSI C’s
-<em>stdio.h</em>. The perl headers (in particular "perlio.h") will
-<code>#define</code> them to the I/O mechanism selected at Configure time.
-</p>
-<p>The functions are modeled on those in <em>stdio.h</em>, but parameter order
-has been "tidied up a little".
-</p>
-<p><code>PerlIO *</code> takes the place of FILE *. Like FILE * it should be
-treated as opaque (it is probably safe to assume it is a pointer to
-something).
-</p>
-<p>There are currently three implementations:
-</p>
-<dl compact="compact">
-<dt>1. USE_STDIO</dt>
-<dd><a name="perlapio-1_002e-USE_005fSTDIO"></a>
-<p>All above are #define’d to stdio functions or are trivial wrapper
-functions which call stdio. In this case <em>only</em> PerlIO * is a FILE *.
-This has been the default implementation since the abstraction was
-introduced in perl5.003_02.
-</p>
-</dd>
-<dt>2. USE_PERLIO</dt>
-<dd><a name="perlapio-2_002e-USE_005fPERLIO"></a>
-<p>Introduced just after perl5.7.0, this is a re-implementation of the
-above abstraction which allows perl more control over how IO is done
-as it decouples IO from the way the operating system and C library
-choose to do things. For USE_PERLIO PerlIO * has an extra layer of
-indirection - it is a pointer-to-a-pointer. This allows the PerlIO *
-to remain with a known value while swapping the implementation around
-underneath <em>at run time</em>. In this case all the above are true (but
-very simple) functions which call the underlying implementation.
-</p>
-<p>This is the only implementation for which <code>PerlIO_apply_layers()</code>
-does anything "interesting".
-</p>
-<p>The USE_PERLIO implementation is described in <a
href="#perliol-NAME">perliol NAME</a>.
-</p>
-</dd>
-</dl>
-
-<p>Because "perlio.h" is a thin layer (for efficiency) the semantics
of
-these functions are somewhat dependent on the underlying implementation.
-Where these variations are understood they are noted below.
-</p>
-<p>Unless otherwise noted, functions return 0 on success, or a negative
-value (usually <code>EOF</code> which is usually -1) and set
<code>errno</code> on error.
-</p>
-<dl compact="compact">
-<dt><strong>PerlIO_stdin()</strong>, <strong>PerlIO_stdout()</strong>,
<strong>PerlIO_stderr()</strong></dt>
-<dd><a
name="perlapio-PerlIO_005fstdin_0028_0029_002c-PerlIO_005fstdout_0028_0029_002c-PerlIO_005fstderr_0028_0029"></a>
-<p>Use these rather than <code>stdin</code>, <code>stdout</code>,
<code>stderr</code>. They are written
-to look like "function calls" rather than variables because this
makes
-it easier to <em>make them</em> function calls if platform cannot export data
-to loaded modules, or if (say) different "threads" might have
different
-values.
-</p>
-</dd>
-<dt><strong>PerlIO_open(path, mode)</strong>,
<strong>PerlIO_fdopen(fd,mode)</strong></dt>
-<dd><a
name="perlapio-PerlIO_005fopen_0028path_002c-mode_0029_002c-PerlIO_005ffdopen_0028fd_002cmode_0029"></a>
-<p>These correspond to fopen()/fdopen() and the arguments are the same.
-Return <code>NULL</code> and set <code>errno</code> if there is an error.
There may be an
-implementation limit on the number of open handles, which may be lower
-than the limit on the number of open files - <code>errno</code> may not be set
-when <code>NULL</code> is returned if this limit is exceeded.
-</p>
-</dd>
-<dt><strong>PerlIO_reopen(path,mode,f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005freopen_0028path_002cmode_002cf_0029"></a>
-<p>While this currently exists in all three implementations perl itself
-does not use it. <em>As perl does not use it, it is not well tested.</em>
-</p>
-<p>Perl prefers to <code>dup</code> the new low-level descriptor to the
descriptor
-used by the existing PerlIO. This may become the behaviour of this
-function in the future.
-</p>
-</dd>
-<dt><strong>PerlIO_printf(f,fmt,...)</strong>,
<strong>PerlIO_vprintf(f,fmt,a)</strong></dt>
-<dd><a
name="perlapio-PerlIO_005fprintf_0028f_002cfmt_002c_002e_002e_002e_0029_002c-PerlIO_005fvprintf_0028f_002cfmt_002ca_0029"></a>
-<p>These are fprintf()/vfprintf() equivalents.
-</p>
-</dd>
-<dt><strong>PerlIO_stdoutf(fmt,...)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fstdoutf_0028fmt_002c_002e_002e_002e_0029"></a>
-<p>This is printf() equivalent. printf is #defined to this function,
-so it is (currently) legal to use <code>printf(fmt,...)</code> in perl sources.
-</p>
-</dd>
-<dt><strong>PerlIO_read(f,buf,count)</strong>,
<strong>PerlIO_write(f,buf,count)</strong></dt>
-<dd><a
name="perlapio-PerlIO_005fread_0028f_002cbuf_002ccount_0029_002c-PerlIO_005fwrite_0028f_002cbuf_002ccount_0029"></a>
-<p>These correspond functionally to fread() and fwrite() but the
-arguments and return values are different. The PerlIO_read() and
-PerlIO_write() signatures have been modeled on the more sane low level
-read() and write() functions instead: The "file" argument is passed
-first, there is only one "count", and the return value can
distinguish
-between error and <code>EOF</code>.
-</p>
-<p>Returns a byte count if successful (which may be zero or
-positive), returns negative value and sets <code>errno</code> on error.
-Depending on implementation <code>errno</code> may be <code>EINTR</code> if
operation was
-interrupted by a signal.
-</p>
-</dd>
-<dt><strong>PerlIO_close(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fclose_0028f_0029"></a>
-<p>Depending on implementation <code>errno</code> may be <code>EINTR</code> if
operation was
-interrupted by a signal.
-</p>
-</dd>
-<dt><strong>PerlIO_puts(f,s)</strong>, <strong>PerlIO_putc(f,c)</strong></dt>
-<dd><a
name="perlapio-PerlIO_005fputs_0028f_002cs_0029_002c-PerlIO_005fputc_0028f_002cc_0029"></a>
-<p>These correspond to fputs() and fputc().
-Note that arguments have been revised to have "file" first.
-</p>
-</dd>
-<dt><strong>PerlIO_ungetc(f,c)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fungetc_0028f_002cc_0029"></a>
-<p>This corresponds to ungetc(). Note that arguments have been revised
-to have "file" first. Arranges that next read operation will return
-the byte <strong>c</strong>. Despite the implied "character" in the
name only
-values in the range 0..0xFF are defined. Returns the byte <strong>c</strong> on
-success or -1 (<code>EOF</code>) on error. The number of bytes that can be
-"pushed back" may vary, only 1 character is certain, and then only if
-it is the last character that was read from the handle.
-</p>
-</dd>
-<dt><strong>PerlIO_getc(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fgetc_0028f_0029"></a>
-<p>This corresponds to getc().
-Despite the c in the name only byte range 0..0xFF is supported.
-Returns the character read or -1 (<code>EOF</code>) on error.
-</p>
-</dd>
-<dt><strong>PerlIO_eof(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005feof_0028f_0029"></a>
-<p>This corresponds to feof(). Returns a true/false indication of
-whether the handle is at end of file. For terminal devices this may
-or may not be "sticky" depending on the implementation. The flag is
-cleared by PerlIO_seek(), or PerlIO_rewind().
-</p>
-</dd>
-<dt><strong>PerlIO_error(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005ferror_0028f_0029"></a>
-<p>This corresponds to ferror(). Returns a true/false indication of
-whether there has been an IO error on the handle.
-</p>
-</dd>
-<dt><strong>PerlIO_fileno(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005ffileno_0028f_0029"></a>
-<p>This corresponds to fileno(), note that on some platforms, the meaning
-of "fileno" may not match Unix. Returns -1 if the handle has no open
-descriptor associated with it.
-</p>
-</dd>
-<dt><strong>PerlIO_clearerr(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fclearerr_0028f_0029"></a>
-<p>This corresponds to clearerr(), i.e., clears ’error’ and
(usually)
-’eof’ flags for the "stream". Does not return a value.
-</p>
-</dd>
-<dt><strong>PerlIO_flush(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fflush_0028f_0029"></a>
-<p>This corresponds to fflush(). Sends any buffered write data to the
-underlying file. If called with <code>NULL</code> this may flush all open
-streams (or core dump with some USE_STDIO implementations). Calling
-on a handle open for read only, or on which last operation was a read
-of some kind may lead to undefined behaviour on some USE_STDIO
-implementations. The USE_PERLIO (layers) implementation tries to
-behave better: it flushes all open streams when passed <code>NULL</code>, and
-attempts to retain data on read streams either in the buffer or by
-seeking the handle to the current logical position.
-</p>
-</dd>
-<dt><strong>PerlIO_seek(f,offset,whence)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fseek_0028f_002coffset_002cwhence_0029"></a>
-<p>This corresponds to fseek(). Sends buffered write data to the
-underlying file, or discards any buffered read data, then positions
-the file descriptor as specified by <strong>offset</strong> and
<strong>whence</strong> (sic).
-This is the correct thing to do when switching between read and write
-on the same handle (see issues with PerlIO_flush() above). Offset is
-of type <code>Off_t</code> which is a perl Configure value which may not be
same
-as stdio’s <code>off_t</code>.
-</p>
-</dd>
-<dt><strong>PerlIO_tell(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005ftell_0028f_0029"></a>
-<p>This corresponds to ftell(). Returns the current file position, or
-(Off_t) -1 on error. May just return value system "knows" without
-making a system call or checking the underlying file descriptor (so
-use on shared file descriptors is not safe without a
-PerlIO_seek()). Return value is of type <code>Off_t</code> which is a perl
-Configure value which may not be same as stdio’s <code>off_t</code>.
-</p>
-</dd>
-<dt><strong>PerlIO_getpos(f,p)</strong>,
<strong>PerlIO_setpos(f,p)</strong></dt>
-<dd><a
name="perlapio-PerlIO_005fgetpos_0028f_002cp_0029_002c-PerlIO_005fsetpos_0028f_002cp_0029"></a>
-<p>These correspond (loosely) to fgetpos() and fsetpos(). Rather than
-stdio’s Fpos_t they expect a "Perl Scalar Value" to be passed.
What is
-stored there should be considered opaque. The layout of the data may
-vary from handle to handle. When not using stdio or if platform does
-not have the stdio calls then they are implemented in terms of
-PerlIO_tell() and PerlIO_seek().
-</p>
-</dd>
-<dt><strong>PerlIO_rewind(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005frewind_0028f_0029"></a>
-<p>This corresponds to rewind(). It is usually defined as being
-</p>
-<pre class="verbatim"> PerlIO_seek(f,(Off_t)0L, SEEK_SET);
- PerlIO_clearerr(f);
-</pre>
-</dd>
-<dt><strong>PerlIO_tmpfile()</strong></dt>
-<dd><a name="perlapio-PerlIO_005ftmpfile_0028_0029"></a>
-<p>This corresponds to tmpfile(), i.e., returns an anonymous PerlIO or
-NULL on error. The system will attempt to automatically delete the
-file when closed. On Unix the file is usually <code>unlink</code>-ed just
after
-it is created so it does not matter how it gets closed. On other
-systems the file may only be deleted if closed via PerlIO_close()
-and/or the program exits via <code>exit</code>. Depending on the
implementation
-there may be "race conditions" which allow other processes access to
-the file, though in general it will be safer in this regard than
-ad. hoc. schemes.
-</p>
-</dd>
-<dt><strong>PerlIO_setlinebuf(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fsetlinebuf_0028f_0029"></a>
-<p>This corresponds to setlinebuf(). Does not return a value. What
-constitutes a "line" is implementation dependent but usually means
-that writing "\n" flushes the buffer. What happens with things like
-"this\nthat" is uncertain. (Perl core uses it <em>only</em> when
"dumping";
-it has nothing to do with $| auto-flush.)
-</p>
-</dd>
-</dl>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlapio-Co_002dexistence-with-stdio" accesskey="1">perlapio
Co-existence with stdio</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlapio-_0022Fast-gets_0022-Functions" accesskey="2">perlapio
"Fast gets" Functions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlapio-Other-Functions"
accesskey="3">perlapio Other Functions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlapio-Co_002dexistence-with-stdio"></a>
-<div class="header">
-<p>
-Next: <a href="#perlapio-_0022Fast-gets_0022-Functions" accesskey="n"
rel="next">perlapio "Fast gets" Functions</a>, Up: <a
href="#perlapio-DESCRIPTION" accesskey="u" rel="up">perlapio DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Co_002dexistence-with-stdio"></a>
-<h4 class="subsection">2.3.1 Co-existence with stdio</h4>
-
-<p>There is outline support for co-existence of PerlIO with stdio.
-Obviously if PerlIO is implemented in terms of stdio there is no
-problem. However in other cases then mechanisms must exist to create a
-FILE * which can be passed to library code which is going to use stdio
-calls.
-</p>
-<p>The first step is to add this line:
-</p>
-<pre class="verbatim"> #define PERLIO_NOT_STDIO 0
-</pre>
-<p><em>before</em> including any perl header files. (This will probably become
-the default at some point). That prevents "perlio.h" from attempting
-to #define stdio functions onto PerlIO functions.
-</p>
-<p>XS code is probably better using "typemap" if it expects FILE *
-arguments. The standard typemap will be adjusted to comprehend any
-changes in this area.
-</p>
-<dl compact="compact">
-<dt><strong>PerlIO_importFILE(f,mode)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fimportFILE_0028f_002cmode_0029"></a>
-<p>Used to get a PerlIO * from a FILE *.
-</p>
-<p>The mode argument should be a string as would be passed to
-fopen/PerlIO_open. If it is NULL then - for legacy support - the code
-will (depending upon the platform and the implementation) either
-attempt to empirically determine the mode in which <em>f</em> is open, or
-use "r+" to indicate a read/write stream.
-</p>
-<p>Once called the FILE * should <em>ONLY</em> be closed by calling
-<code>PerlIO_close()</code> on the returned PerlIO *.
-</p>
-<p>The PerlIO is set to textmode. Use PerlIO_binmode if this is
-not the desired mode.
-</p>
-<p>This is <strong>not</strong> the reverse of PerlIO_exportFILE().
-</p>
-</dd>
-<dt><strong>PerlIO_exportFILE(f,mode)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fexportFILE_0028f_002cmode_0029"></a>
-<p>Given a PerlIO * create a ’native’ FILE * suitable for passing
to code
-expecting to be compiled and linked with ANSI C <em>stdio.h</em>. The mode
-argument should be a string as would be passed to fopen/PerlIO_open.
-If it is NULL then - for legacy support - the FILE * is opened in same
-mode as the PerlIO *.
-</p>
-<p>The fact that such a FILE * has been ’exported’ is recorded,
(normally
-by pushing a new :stdio "layer" onto the PerlIO *), which may affect
-future PerlIO operations on the original PerlIO *. You should not
-call <code>fclose()</code> on the file unless you call
<code>PerlIO_releaseFILE()</code>
-to disassociate it from the PerlIO *. (Do not use PerlIO_importFILE()
-for doing the disassociation.)
-</p>
-<p>Calling this function repeatedly will create a FILE * on each call
-(and will push an :stdio layer each time as well).
-</p>
-</dd>
-<dt><strong>PerlIO_releaseFILE(p,f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005freleaseFILE_0028p_002cf_0029"></a>
-<p>Calling PerlIO_releaseFILE informs PerlIO that all use of FILE * is
-complete. It is removed from the list of ’exported’ FILE *s, and
the
-associated PerlIO * should revert to its original behaviour.
-</p>
-<p>Use this to disassociate a file from a PerlIO * that was associated
-using PerlIO_exportFILE().
-</p>
-</dd>
-<dt><strong>PerlIO_findFILE(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005ffindFILE_0028f_0029"></a>
-<p>Returns a native FILE * used by a stdio layer. If there is none, it
-will create one with PerlIO_exportFILE. In either case the FILE *
-should be considered as belonging to PerlIO subsystem and should
-only be closed by calling <code>PerlIO_close()</code>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlapio-_0022Fast-gets_0022-Functions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlapio-Other-Functions" accesskey="n" rel="next">perlapio
Other Functions</a>, Previous: <a href="#perlapio-Co_002dexistence-with-stdio"
accesskey="p" rel="prev">perlapio Co-existence with stdio</a>, Up: <a
href="#perlapio-DESCRIPTION" accesskey="u" rel="up">perlapio DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="g_t_0022Fast-gets_0022-Functions"></a>
-<h4 class="subsection">2.3.2 "Fast gets" Functions</h4>
-
-<p>In addition to standard-like API defined so far above there is an
-"implementation" interface which allows perl to get at internals of
-PerlIO. The following calls correspond to the various FILE_xxx macros
-determined by Configure - or their equivalent in other
-implementations. This section is really of interest to only those
-concerned with detailed perl-core behaviour, implementing a PerlIO
-mapping or writing code which can make use of the "read ahead" that
-has been done by the IO system in the same way perl does. Note that
-any code that uses these interfaces must be prepared to do things the
-traditional way if a handle does not support them.
-</p>
-<dl compact="compact">
-<dt><strong>PerlIO_fast_gets(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005ffast_005fgets_0028f_0029"></a>
-<p>Returns true if implementation has all the interfaces required to
-allow perl’s <code>sv_gets</code> to "bypass" normal IO
mechanism. This can
-vary from handle to handle.
-</p>
-<pre class="verbatim"> PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
- PerlIO_canset_cnt(f) && \
- 'Can set pointer into buffer'
-</pre>
-</dd>
-<dt><strong>PerlIO_has_cntptr(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fhas_005fcntptr_0028f_0029"></a>
-<p>Implementation can return pointer to current position in the
"buffer"
-and a count of bytes available in the buffer. Do not use this - use
-PerlIO_fast_gets.
-</p>
-</dd>
-<dt><strong>PerlIO_get_cnt(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fget_005fcnt_0028f_0029"></a>
-<p>Return count of readable bytes in the buffer. Zero or negative return
-means no more bytes available.
-</p>
-</dd>
-<dt><strong>PerlIO_get_ptr(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fget_005fptr_0028f_0029"></a>
-<p>Return pointer to next readable byte in buffer, accessing via the
-pointer (dereferencing) is only safe if PerlIO_get_cnt() has returned
-a positive value. Only positive offsets up to value returned by
-PerlIO_get_cnt() are allowed.
-</p>
-</dd>
-<dt><strong>PerlIO_set_ptrcnt(f,p,c)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fset_005fptrcnt_0028f_002cp_002cc_0029"></a>
-<p>Set pointer into buffer, and a count of bytes still in the
-buffer. Should be used only to set pointer to within range implied by
-previous calls to <code>PerlIO_get_ptr</code> and <code>PerlIO_get_cnt</code>.
The two
-values <em>must</em> be consistent with each other (implementation may only
-use one or the other or may require both).
-</p>
-</dd>
-<dt><strong>PerlIO_canset_cnt(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fcanset_005fcnt_0028f_0029"></a>
-<p>Implementation can adjust its idea of number of bytes in the buffer.
-Do not use this - use PerlIO_fast_gets.
-</p>
-</dd>
-<dt><strong>PerlIO_set_cnt(f,c)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fset_005fcnt_0028f_002cc_0029"></a>
-<p>Obscure - set count of bytes in the buffer. Deprecated. Only usable
-if PerlIO_canset_cnt() returns true. Currently used in only doio.c to
-force count less than -1 to -1. Perhaps should be PerlIO_set_empty or
-similar. This call may actually do nothing if "count" is deduced
from
-pointer and a "limit". Do not use this - use PerlIO_set_ptrcnt().
-</p>
-</dd>
-<dt><strong>PerlIO_has_base(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fhas_005fbase_0028f_0029"></a>
-<p>Returns true if implementation has a buffer, and can return pointer
-to whole buffer and its size. Used by perl for <strong>-T</strong> /
<strong>-B</strong> tests.
-Other uses would be very obscure...
-</p>
-</dd>
-<dt><strong>PerlIO_get_base(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fget_005fbase_0028f_0029"></a>
-<p>Return <em>start</em> of buffer. Access only positive offsets in the buffer
-up to the value returned by PerlIO_get_bufsiz().
-</p>
-</dd>
-<dt><strong>PerlIO_get_bufsiz(f)</strong></dt>
-<dd><a name="perlapio-PerlIO_005fget_005fbufsiz_0028f_0029"></a>
-<p>Return the <em>total number of bytes</em> in the buffer, this is neither the
-number that can be read, nor the amount of memory allocated to the
-buffer. Rather it is what the operating system and/or implementation
-happened to <code>read()</code> (or whatever) last time IO was requested.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlapio-Other-Functions"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlapio-_0022Fast-gets_0022-Functions" accesskey="p"
rel="prev">perlapio "Fast gets" Functions</a>, Up: <a
href="#perlapio-DESCRIPTION" accesskey="u" rel="up">perlapio DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Other-Functions"></a>
-<h4 class="subsection">2.3.3 Other Functions</h4>
-
-<dl compact="compact">
-<dt>PerlIO_apply_layers(f,mode,layers)</dt>
-<dd><a
name="perlapio-PerlIO_005fapply_005flayers_0028f_002cmode_002clayers_0029"></a>
-<p>The new interface to the USE_PERLIO implementation. The layers
":crlf"
-and ":raw" are only ones allowed for other implementations and those
-are silently ignored. (As of perl5.8 ":raw" is deprecated.) Use
-PerlIO_binmode() below for the portable case.
-</p>
-</dd>
-<dt>PerlIO_binmode(f,ptype,imode,layers)</dt>
-<dd><a
name="perlapio-PerlIO_005fbinmode_0028f_002cptype_002cimode_002clayers_0029"></a>
-<p>The hook used by perl’s <code>binmode</code> operator.
-<strong>ptype</strong> is perl’s character for the kind of IO:
-</p>
-<dl compact="compact">
-<dt>’<’ read</dt>
-<dd><a name="perlapio-_0027_003c_0027-read"></a>
-</dd>
-<dt>’>’ write</dt>
-<dd><a name="perlapio-_0027_003e_0027-write"></a>
-</dd>
-<dt>’+’ read/write</dt>
-<dd><a name="perlapio-_0027_002b_0027-read_002fwrite"></a>
-</dd>
-</dl>
-
-<p><strong>imode</strong> is <code>O_BINARY</code> or <code>O_TEXT</code>.
-</p>
-<p><strong>layers</strong> is a string of layers to apply, only
":crlf" makes sense in
-the non USE_PERLIO case. (As of perl5.8 ":raw" is deprecated in
favour
-of passing NULL.)
-</p>
-<p>Portable cases are:
-</p>
-<pre class="verbatim"> PerlIO_binmode(f,ptype,O_BINARY,NULL);
-and
- PerlIO_binmode(f,ptype,O_TEXT,":crlf");
-</pre>
-<p>On Unix these calls probably have no effect whatsoever. Elsewhere
-they alter "\n" to CR,LF translation and possibly cause a special
text
-"end of file" indicator to be written or honoured on read. The effect
-of making the call after doing any IO to the handle depends on the
-implementation. (It may be ignored, affect any data which is already
-buffered as well, or only apply to subsequent data.)
-</p>
-</dd>
-<dt>PerlIO_debug(fmt,...)</dt>
-<dd><a name="perlapio-PerlIO_005fdebug_0028fmt_002c_002e_002e_002e_0029"></a>
-<p>PerlIO_debug is a printf()-like function which can be used for
-debugging. No return value. Its main use is inside PerlIO where using
-real printf, warn() etc. would recursively call PerlIO and be a
-problem.
-</p>
-<p>PerlIO_debug writes to the file named by $ENV{’PERLIO_DEBUG’}
typical
-use might be
-</p>
-<pre class="verbatim"> Bourne shells (sh, ksh, bash, zsh, ash, ...):
- PERLIO_DEBUG=/dev/tty ./perl somescript some args
-
- Csh/Tcsh:
- setenv PERLIO_DEBUG /dev/tty
- ./perl somescript some args
-
- If you have the "env" utility:
- env PERLIO_DEBUG=/dev/tty ./perl somescript some args
-
- Win32:
- set PERLIO_DEBUG=CON
- perl somescript some args
-</pre>
-<p>If $ENV{’PERLIO_DEBUG’} is not set PerlIO_debug() is a no-op.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlartistic"></a>
-<div class="header">
-<p>
-Next: <a href="#perlbook" accesskey="n" rel="next">perlbook</a>, Previous: <a
href="#perlapio" accesskey="p" rel="prev">perlapio</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlartistic-1"></a>
-<h2 class="chapter">3 perlartistic</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlartistic-NAME"
accesskey="1">perlartistic NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlartistic-SYNOPSIS"
accesskey="2">perlartistic SYNOPSIS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlartistic-DESCRIPTION"
accesskey="3">perlartistic DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlartistic-The-_0022Artistic-License_0022" accesskey="4">perlartistic
The "Artistic License"</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlartistic-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlartistic-SYNOPSIS" accesskey="n" rel="next">perlartistic
SYNOPSIS</a>, Up: <a href="#perlartistic" accesskey="u"
rel="up">perlartistic</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-2"></a>
-<h3 class="section">3.1 NAME</h3>
-
-<p>perlartistic - the Perl Artistic License
-</p>
-<hr>
-<a name="perlartistic-SYNOPSIS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlartistic-DESCRIPTION" accesskey="n"
rel="next">perlartistic DESCRIPTION</a>, Previous: <a href="#perlartistic-NAME"
accesskey="p" rel="prev">perlartistic NAME</a>, Up: <a href="#perlartistic"
accesskey="u" rel="up">perlartistic</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SYNOPSIS-2"></a>
-<h3 class="section">3.2 SYNOPSIS</h3>
-
-<pre class="verbatim"> You can refer to this document in Pod via
"L<perlartistic>"
- Or you can see this document by entering "perldoc perlartistic"
-</pre>
-<hr>
-<a name="perlartistic-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlartistic-The-_0022Artistic-License_0022" accesskey="n"
rel="next">perlartistic The "Artistic License"</a>, Previous: <a
href="#perlartistic-SYNOPSIS" accesskey="p" rel="prev">perlartistic
SYNOPSIS</a>, Up: <a href="#perlartistic" accesskey="u"
rel="up">perlartistic</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-2"></a>
-<h3 class="section">3.3 DESCRIPTION</h3>
-
-<p>Perl is free software; you can redistribute it and/or modify
-it under the terms of either:
-</p>
-<pre class="verbatim"> a) the GNU General Public License as published
by the Free
- Software Foundation; either version 1, or (at your option) any
- later version, or
-
- b) the "Artistic License" which comes with this Kit.
-</pre>
-<p>This is <strong>"The Artistic License"</strong>.
-It’s here so that modules, programs, etc., that want to declare
-this as their distribution license can link to it.
-</p>
-<p>For the GNU General Public License, see <a href="#perlgpl-NAME">perlgpl
NAME</a>.
-</p>
-<hr>
-<a name="perlartistic-The-_0022Artistic-License_0022"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlartistic-DESCRIPTION" accesskey="p"
rel="prev">perlartistic DESCRIPTION</a>, Up: <a href="#perlartistic"
accesskey="u" rel="up">perlartistic</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-_0022Artistic-License_0022"></a>
-<h3 class="section">3.4 The "Artistic License"</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlartistic-Preamble"
accesskey="1">perlartistic Preamble</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlartistic-Definitions"
accesskey="2">perlartistic Definitions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlartistic-Conditions"
accesskey="3">perlartistic Conditions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlartistic-Preamble"></a>
-<div class="header">
-<p>
-Next: <a href="#perlartistic-Definitions" accesskey="n"
rel="next">perlartistic Definitions</a>, Up: <a
href="#perlartistic-The-_0022Artistic-License_0022" accesskey="u"
rel="up">perlartistic The "Artistic License"</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Preamble"></a>
-<h4 class="subsection">3.4.1 Preamble</h4>
-
-<p>The intent of this document is to state the conditions under which a
-Package may be copied, such that the Copyright Holder maintains some
-semblance of artistic control over the development of the package,
-while giving the users of the package the right to use and distribute
-the Package in a more-or-less customary fashion, plus the right to make
-reasonable modifications.
-</p>
-<hr>
-<a name="perlartistic-Definitions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlartistic-Conditions" accesskey="n" rel="next">perlartistic
Conditions</a>, Previous: <a href="#perlartistic-Preamble" accesskey="p"
rel="prev">perlartistic Preamble</a>, Up: <a
href="#perlartistic-The-_0022Artistic-License_0022" accesskey="u"
rel="up">perlartistic The "Artistic License"</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Definitions"></a>
-<h4 class="subsection">3.4.2 Definitions</h4>
-
-<dl compact="compact">
-<dt>"Package"</dt>
-<dd><a name="perlartistic-_0022Package_0022"></a>
-<p>refers to the collection of files distributed by the
-Copyright Holder, and derivatives of that collection of files created
-through textual modification.
-</p>
-</dd>
-<dt>"Standard Version"</dt>
-<dd><a name="perlartistic-_0022Standard-Version_0022"></a>
-<p>refers to such a Package if it has not been
-modified, or has been modified in accordance with the wishes of the
-Copyright Holder as specified below.
-</p>
-</dd>
-<dt>"Copyright Holder"</dt>
-<dd><a name="perlartistic-_0022Copyright-Holder_0022"></a>
-<p>is whoever is named in the copyright or
-copyrights for the package.
-</p>
-</dd>
-<dt>"You"</dt>
-<dd><a name="perlartistic-_0022You_0022"></a>
-<p>is you, if you’re thinking about copying or distributing this Package.
-</p>
-</dd>
-<dt>"Reasonable copying fee"</dt>
-<dd><a name="perlartistic-_0022Reasonable-copying-fee_0022"></a>
-<p>is whatever you can justify on the basis
-of media cost, duplication charges, time of people involved, and so on.
-(You will not be required to justify it to the Copyright Holder, but
-only to the computing community at large as a market that must bear the
-fee.)
-</p>
-</dd>
-<dt>"Freely Available"</dt>
-<dd><a name="perlartistic-_0022Freely-Available_0022"></a>
-<p>means that no fee is charged for the item
-itself, though there may be fees involved in handling the item. It also
-means that recipients of the item may redistribute it under the same
-conditions they received it.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlartistic-Conditions"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlartistic-Definitions" accesskey="p"
rel="prev">perlartistic Definitions</a>, Up: <a
href="#perlartistic-The-_0022Artistic-License_0022" accesskey="u"
rel="up">perlartistic The "Artistic License"</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Conditions"></a>
-<h4 class="subsection">3.4.3 Conditions</h4>
-
-<ol>
-<li> You may make and give away verbatim copies of the source form of the
-Standard Version of this Package without restriction, provided that you
-duplicate all of the original copyright notices and associated disclaimers.
-
-</li><li> You may apply bug fixes, portability fixes and other modifications
-derived from the Public Domain or from the Copyright Holder. A Package
-modified in such a way shall still be considered the Standard Version.
-
-</li><li> You may otherwise modify your copy of this Package in any way,
provided
-that you insert a prominent notice in each changed file stating how and
-when you changed that file, and provided that you do at least ONE of the
-following:
-
-<dl compact="compact">
-<dt>a)</dt>
-<dd><a name="perlartistic-a_0029"></a>
-<p>place your modifications in the Public Domain or otherwise make them
-Freely Available, such as by posting said modifications to Usenet or an
-equivalent medium, or placing the modifications on a major archive site
-such as uunet.uu.net, or by allowing the Copyright Holder to include
-your modifications in the Standard Version of the Package.
-</p>
-</dd>
-<dt>b)</dt>
-<dd><a name="perlartistic-b_0029"></a>
-<p>use the modified Package only within your corporation or organization.
-</p>
-</dd>
-<dt>c)</dt>
-<dd><a name="perlartistic-c_0029"></a>
-<p>rename any non-standard executables so the names do not conflict with
-standard executables, which must also be provided, and provide a
-separate manual page for each non-standard executable that clearly
-documents how it differs from the Standard Version.
-</p>
-</dd>
-<dt>d)</dt>
-<dd><a name="perlartistic-d_0029"></a>
-<p>make other distribution arrangements with the Copyright Holder.
-</p>
-</dd>
-</dl>
-
-</li><li> You may distribute the programs of this Package in object code or
-executable form, provided that you do at least ONE of the following:
-
-<dl compact="compact">
-<dt>a)</dt>
-<dd><a name="perlartistic-a_0029-1"></a>
-<p>distribute a Standard Version of the executables and library files,
-together with instructions (in the manual page or equivalent) on where
-to get the Standard Version.
-</p>
-</dd>
-<dt>b)</dt>
-<dd><a name="perlartistic-b_0029-1"></a>
-<p>accompany the distribution with the machine-readable source of the
-Package with your modifications.
-</p>
-</dd>
-<dt>c)</dt>
-<dd><a name="perlartistic-c_0029-1"></a>
-<p>give non-standard executables non-standard names, and clearly
-document the differences in manual pages (or equivalent), together with
-instructions on where to get the Standard Version.
-</p>
-</dd>
-<dt>d)</dt>
-<dd><a name="perlartistic-d_0029-1"></a>
-<p>make other distribution arrangements with the Copyright Holder.
-</p>
-</dd>
-</dl>
-
-</li><li> You may charge a reasonable copying fee for any distribution of this
-Package. You may charge any fee you choose for support of this
-Package. You may not charge a fee for this Package itself. However,
-you may distribute this Package in aggregate with other (possibly
-commercial) programs as part of a larger (possibly commercial) software
-distribution provided that you do not advertise this Package as a
-product of your own. You may embed this Package’s interpreter within
-an executable of yours (by linking); this shall be construed as a mere
-form of aggregation, provided that the complete Standard Version of the
-interpreter is so embedded.
-
-</li><li> The scripts and library files supplied as input to or produced as
-output from the programs of this Package do not automatically fall
-under the copyright of this Package, but belong to whoever generated
-them, and may be sold commercially, and may be aggregated with this
-Package. If such scripts or library files are aggregated with this
-Package via the so-called "undump" or "unexec" methods of
producing a
-binary executable image, then distribution of such an image shall
-neither be construed as a distribution of this Package nor shall it
-fall under the restrictions of Paragraphs 3 and 4, provided that you do
-not represent such an executable image as a Standard Version of this
-Package.
-
-</li><li> C subroutines (or comparably compiled subroutines in other
-languages) supplied by you and linked into this Package in order to
-emulate subroutines and variables of the language defined by this
-Package shall not be considered part of this Package, but are the
-equivalent of input as in Paragraph 6, provided these subroutines do
-not change the language in any way that would cause it to fail the
-regression tests for the language.
-
-</li><li> Aggregation of this Package with a commercial distribution is always
-permitted provided that the use of this Package is embedded; that is,
-when no overt attempt is made to make this Package’s interfaces visible
-to the end user of the commercial distribution. Such use shall not be
-construed as a distribution of this Package.
-
-</li><li> The name of the Copyright Holder may not be used to endorse or
promote
-products derived from this software without specific prior written permission.
-
-</li><li> THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
-IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
-WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
-
-</li></ol>
-
-<p>The End
-</p>
-<hr>
-<a name="perlbook"></a>
-<div class="header">
-<p>
-Next: <a href="#perlboot" accesskey="n" rel="next">perlboot</a>, Previous: <a
href="#perlartistic" accesskey="p" rel="prev">perlartistic</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlbook-1"></a>
-<h2 class="chapter">4 perlbook</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlbook-NAME"
accesskey="1">perlbook NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlbook-DESCRIPTION"
accesskey="2">perlbook DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlbook-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlbook-DESCRIPTION" accesskey="n" rel="next">perlbook
DESCRIPTION</a>, Up: <a href="#perlbook" accesskey="u" rel="up">perlbook</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-3"></a>
-<h3 class="section">4.1 NAME</h3>
-
-<p>perlbook - Books about and related to Perl
-</p>
-<hr>
-<a name="perlbook-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlbook-NAME" accesskey="p" rel="prev">perlbook NAME</a>,
Up: <a href="#perlbook" accesskey="u" rel="up">perlbook</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-3"></a>
-<h3 class="section">4.2 DESCRIPTION</h3>
-
-<p>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.
-</p>
-<p>Most of these books are available online through Safari Books Online
-( http://safaribooksonline.com/ ).
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlbook-The-most-popular-books" accesskey="1">perlbook The most popular
books</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlbook-References"
accesskey="2">perlbook References</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlbook-Tutorials"
accesskey="3">perlbook Tutorials</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlbook-Task_002dOriented"
accesskey="4">perlbook Task-Oriented</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlbook-Special-Topics"
accesskey="5">perlbook Special Topics</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlbook-Free-_0028as-in-beer_0029-books" accesskey="6">perlbook Free
(as in beer) books</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlbook-Other-interesting_002c-non_002dPerl-books"
accesskey="7">perlbook Other interesting, non-Perl
books</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlbook-A-note-on-freshness" accesskey="8">perlbook A note on
freshness</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlbook-Get-your-book-listed" accesskey="9">perlbook Get your book
listed</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlbook-The-most-popular-books"></a>
-<div class="header">
-<p>
-Next: <a href="#perlbook-References" accesskey="n" rel="next">perlbook
References</a>, Up: <a href="#perlbook-DESCRIPTION" accesskey="u"
rel="up">perlbook DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-most-popular-books"></a>
-<h4 class="subsection">4.2.1 The most popular books</h4>
-
-<p>The major reference book on Perl, written by the creator of Perl, is
-<em>Programming Perl</em>:
-</p>
-<dl compact="compact">
-<dt><em>Programming Perl</em> (the "Camel Book"):</dt>
-<dd><a
name="perlbook-Programming-Perl-_0028the-_0022Camel-Book_0022_0029_003a"></a>
-<pre class="verbatim"> by Tom Christiansen, brian d foy, Larry Wall
with Jon Orwant
- ISBN 978-0-596-00492-7 [4th edition February 2012]
- ISBN 978-1-4493-9890-3 [ebook]
- http://oreilly.com/catalog/9780596004927
-</pre>
-</dd>
-</dl>
-
-<p>The Ram is a cookbook with hundreds of examples of using Perl to
-accomplish specific tasks:
-</p>
-<dl compact="compact">
-<dt><em>The Perl Cookbook</em> (the "Ram Book"):</dt>
-<dd><a
name="perlbook-The-Perl-Cookbook-_0028the-_0022Ram-Book_0022_0029_003a"></a>
-<pre class="verbatim"> by Tom Christiansen and Nathan Torkington,
- with Foreword by Larry Wall
- ISBN 978-0-596-00313-5 [2nd Edition August 2003]
- ISBN 978-0-596-15888-0 [ebook]
- http://oreilly.com/catalog/9780596003135/
-</pre>
-</dd>
-</dl>
-
-<p>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:
-</p>
-<dl compact="compact">
-<dt><em>Learning Perl</em> (the "Llama Book")</dt>
-<dd><a name="perlbook-Learning-Perl-_0028the-_0022Llama-Book_0022_0029"></a>
-<pre class="verbatim"> by Randal L. Schwartz, Tom Phoenix, and brian d
foy
- ISBN 978-1-4493-0358-7 [6th edition June 2011]
- ISBN 978-1-4493-0458-4 [ebook]
- http://www.learning-perl.com/
-</pre>
-</dd>
-</dl>
-
-<p>The tutorial started in the Llama continues in the Alpaca, which
-introduces the intermediate features of references, data structures,
-object-oriented programming, and modules:
-</p>
-<dl compact="compact">
-<dt><em>Intermediate Perl</em> (the "Alpaca Book")</dt>
-<dd><a
name="perlbook-Intermediate-Perl-_0028the-_0022Alpaca-Book_0022_0029"></a>
-<pre class="verbatim"> by Randal L. Schwartz and brian d foy, with Tom
Phoenix
- foreword by Damian Conway
- ISBN 978-1-4493-9309-0 [2nd edition August 2012]
- ISBN 978-1-4493-0459-1 [ebook]
- http://www.intermediateperl.com/
-</pre>
-</dd>
-</dl>
-
-<hr>
-<a name="perlbook-References"></a>
-<div class="header">
-<p>
-Next: <a href="#perlbook-Tutorials" accesskey="n" rel="next">perlbook
Tutorials</a>, Previous: <a href="#perlbook-The-most-popular-books"
accesskey="p" rel="prev">perlbook The most popular books</a>, Up: <a
href="#perlbook-DESCRIPTION" accesskey="u" rel="up">perlbook DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="References"></a>
-<h4 class="subsection">4.2.2 References</h4>
-
-<p>You might want to keep these desktop references close by your keyboard:
-</p>
-<dl compact="compact">
-<dt><em>Perl 5 Pocket Reference</em></dt>
-<dd><a name="perlbook-Perl-5-Pocket-Reference"></a>
-<pre class="verbatim"> by Johan Vromans
- ISBN 978-1-4493-0370-9 [5th edition July 2011]
- ISBN 978-1-4493-0813-1 [ebook]
- http://oreilly.com/catalog/0636920018476/
-</pre>
-</dd>
-<dt><em>Perl Debugger Pocket Reference</em></dt>
-<dd><a name="perlbook-Perl-Debugger-Pocket-Reference"></a>
-<pre class="verbatim"> by Richard Foley
- ISBN 978-0-596-00503-0 [1st edition January 2004]
- ISBN 978-0-596-55625-9 [ebook]
- http://oreilly.com/catalog/9780596005030/
-</pre>
-</dd>
-<dt><em>Regular Expression Pocket Reference</em></dt>
-<dd><a name="perlbook-Regular-Expression-Pocket-Reference"></a>
-<pre class="verbatim"> by Tony Stubblebine
- ISBN 978-0-596-51427-3 [2nd edition July 2007]
- ISBN 978-0-596-55782-9 [ebook]
- http://oreilly.com/catalog/9780596514273/
-</pre>
-</dd>
-</dl>
-
-<hr>
-<a name="perlbook-Tutorials"></a>
-<div class="header">
-<p>
-Next: <a href="#perlbook-Task_002dOriented" accesskey="n" rel="next">perlbook
Task-Oriented</a>, Previous: <a href="#perlbook-References" accesskey="p"
rel="prev">perlbook References</a>, Up: <a href="#perlbook-DESCRIPTION"
accesskey="u" rel="up">perlbook DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Tutorials-1"></a>
-<h4 class="subsection">4.2.3 Tutorials</h4>
-
-<dl compact="compact">
-<dt><em>Beginning Perl</em></dt>
-<dd><a name="perlbook-Beginning-Perl"></a>
-<pre class="verbatim"> by James Lee
- ISBN 1-59059-391-X [3rd edition April 2010 & ebook]
- http://www.apress.com/9781430227939
-</pre>
-</dd>
-<dt><em>Learning Perl</em> (the "Llama Book")</dt>
-<dd><a name="perlbook-Learning-Perl-_0028the-_0022Llama-Book_0022_0029-1"></a>
-<pre class="verbatim"> by Randal L. Schwartz, Tom Phoenix, and brian d
foy
- ISBN 978-1-4493-0358-7 [6th edition June 2011]
- ISBN 978-1-4493-0458-4 [ebook]
- http://www.learning-perl.com/
-</pre>
-</dd>
-<dt><em>Intermediate Perl</em> (the "Alpaca Book")</dt>
-<dd><a
name="perlbook-Intermediate-Perl-_0028the-_0022Alpaca-Book_0022_0029-1"></a>
-<pre class="verbatim"> by Randal L. Schwartz and brian d foy, with Tom
Phoenix
- foreword by Damian Conway
- ISBN 978-1-4493-9309-0 [2nd edition August 2012]
- ISBN 978-1-4493-0459-1 [ebook]
- http://www.intermediateperl.com/
-</pre>
-</dd>
-<dt><em>Mastering Perl</em></dt>
-<dd><a name="perlbook-Mastering-Perl"></a>
-<pre class="verbatim"> by brian d foy
- ISBN 9978-1-4493-9311-3 [2st edition January 2014]
- ISBN 978-1-4493-6487-8 [ebook]
- http://www.masteringperl.org/
-</pre>
-</dd>
-<dt><em>Effective Perl Programming</em></dt>
-<dd><a name="perlbook-Effective-Perl-Programming"></a>
-<pre class="verbatim"> by Joseph N. Hall, Joshua A. McAdams, brian d foy
- ISBN 0-321-49694-9 [2nd edition 2010]
- http://www.effectiveperlprogramming.com/
-</pre>
-</dd>
-</dl>
-
-<hr>
-<a name="perlbook-Task_002dOriented"></a>
-<div class="header">
-<p>
-Next: <a href="#perlbook-Special-Topics" accesskey="n" rel="next">perlbook
Special Topics</a>, Previous: <a href="#perlbook-Tutorials" accesskey="p"
rel="prev">perlbook Tutorials</a>, Up: <a href="#perlbook-DESCRIPTION"
accesskey="u" rel="up">perlbook DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Task_002dOriented"></a>
-<h4 class="subsection">4.2.4 Task-Oriented</h4>
-
-<dl compact="compact">
-<dt><em>Writing Perl Modules for CPAN</em></dt>
-<dd><a name="perlbook-Writing-Perl-Modules-for-CPAN"></a>
-<pre class="verbatim"> by Sam Tregar
- ISBN 1-59059-018-X [1st edition August 2002 & ebook]
- http://www.apress.com/9781590590188
-</pre>
-</dd>
-<dt><em>The Perl Cookbook</em></dt>
-<dd><a name="perlbook-The-Perl-Cookbook"></a>
-<pre class="verbatim"> by Tom Christiansen and Nathan Torkington,
- with Foreword by Larry Wall
- ISBN 978-0-596-00313-5 [2nd Edition August 2003]
- ISBN 978-0-596-15888-0 [ebook]
- http://oreilly.com/catalog/9780596003135/
-</pre>
-</dd>
-<dt><em>Automating System Administration with Perl</em></dt>
-<dd><a name="perlbook-Automating-System-Administration-with-Perl"></a>
-<pre class="verbatim"> by David N. Blank-Edelman
- ISBN 978-0-596-00639-6 [2nd edition May 2009]
- ISBN 978-0-596-80251-6 [ebook]
- http://oreilly.com/catalog/9780596006396
-</pre>
-</dd>
-<dt><em>Real World SQL Server Administration with Perl</em></dt>
-<dd><a name="perlbook-Real-World-SQL-Server-Administration-with-Perl"></a>
-<pre class="verbatim"> by Linchi Shea
- ISBN 1-59059-097-X [1st edition July 2003 & ebook]
- http://www.apress.com/9781590590973
-</pre>
-</dd>
-</dl>
-
-<hr>
-<a name="perlbook-Special-Topics"></a>
-<div class="header">
-<p>
-Next: <a href="#perlbook-Free-_0028as-in-beer_0029-books" accesskey="n"
rel="next">perlbook Free (as in beer) books</a>, Previous: <a
href="#perlbook-Task_002dOriented" accesskey="p" rel="prev">perlbook
Task-Oriented</a>, Up: <a href="#perlbook-DESCRIPTION" accesskey="u"
rel="up">perlbook DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Special-Topics"></a>
-<h4 class="subsection">4.2.5 Special Topics</h4>
-
-<dl compact="compact">
-<dt><em>Regular Expressions Cookbook</em></dt>
-<dd><a name="perlbook-Regular-Expressions-Cookbook"></a>
-<pre class="verbatim"> by Jan Goyvaerts and Steven Levithan
- ISBN 978-1-4493-1943-4 [2nd edition August 2012]
- ISBN 978-1-4493-2747-7 [ebook]
- http://shop.oreilly.com/product/0636920023630.do
-</pre>
-</dd>
-<dt><em>Programming the Perl DBI</em></dt>
-<dd><a name="perlbook-Programming-the-Perl-DBI"></a>
-<pre class="verbatim"> by Tim Bunce and Alligator Descartes
- ISBN 978-1-56592-699-8 [February 2000]
- ISBN 978-1-4493-8670-2 [ebook]
- http://oreilly.com/catalog/9781565926998
-</pre>
-</dd>
-<dt><em>Perl Best Practices</em></dt>
-<dd><a name="perlbook-Perl-Best-Practices"></a>
-<pre class="verbatim"> by Damian Conway
- ISBN 978-0-596-00173-5 [1st edition July 2005]
- ISBN 978-0-596-15900-9 [ebook]
- http://oreilly.com/catalog/9780596001735
-</pre>
-</dd>
-<dt><em>Higher-Order Perl</em></dt>
-<dd><a name="perlbook-Higher_002dOrder-Perl"></a>
-<pre class="verbatim"> by Mark-Jason Dominus
- ISBN 1-55860-701-3 [1st edition March 2005]
- free ebook http://hop.perl.plover.com/book/
- http://hop.perl.plover.com/
-</pre>
-</dd>
-<dt><em>Mastering Regular Expressions</em></dt>
-<dd><a name="perlbook-Mastering-Regular-Expressions"></a>
-<pre class="verbatim"> by Jeffrey E. F. Friedl
- ISBN 978-0-596-52812-6 [3rd edition August 2006]
- ISBN 978-0-596-55899-4 [ebook]
- http://oreilly.com/catalog/9780596528126
-</pre>
-</dd>
-<dt><em>Network Programming with Perl</em></dt>
-<dd><a name="perlbook-Network-Programming-with-Perl"></a>
-<pre class="verbatim"> by Lincoln Stein
- ISBN 0-201-61571-1 [1st edition 2001]
-
http://www.pearsonhighered.com/educator/product/Network-Programming-with-Perl/9780201615715.page
-</pre>
-</dd>
-<dt><em>Perl Template Toolkit</em></dt>
-<dd><a name="perlbook-Perl-Template-Toolkit"></a>
-<pre class="verbatim"> by Darren Chamberlain, Dave Cross, and Andy
Wardley
- ISBN 978-0-596-00476-7 [December 2003]
- ISBN 978-1-4493-8647-4 [ebook]
- http://oreilly.com/catalog/9780596004767
-</pre>
-</dd>
-<dt><em>Object Oriented Perl</em></dt>
-<dd><a name="perlbook-Object-Oriented-Perl"></a>
-<pre class="verbatim"> by Damian Conway
- with foreword by Randal L. Schwartz
- ISBN 1-884777-79-1 [1st edition August 1999 & ebook]
- http://www.manning.com/conway/
-</pre>
-</dd>
-<dt><em>Data Munging with Perl</em></dt>
-<dd><a name="perlbook-Data-Munging-with-Perl"></a>
-<pre class="verbatim"> by Dave Cross
- ISBN 1-930110-00-6 [1st edition 2001 & ebook]
- http://www.manning.com/cross
-</pre>
-</dd>
-<dt><em>Mastering Perl/Tk</em></dt>
-<dd><a name="perlbook-Mastering-Perl_002fTk"></a>
-<pre class="verbatim"> by Steve Lidie and Nancy Walsh
- ISBN 978-1-56592-716-2 [1st edition January 2002]
- ISBN 978-0-596-10344-6 [ebook]
- http://oreilly.com/catalog/9781565927162
-</pre>
-</dd>
-<dt><em>Extending and Embedding Perl</em></dt>
-<dd><a name="perlbook-Extending-and-Embedding-Perl"></a>
-<pre class="verbatim"> by Tim Jenness and Simon Cozens
- ISBN 1-930110-82-0 [1st edition August 2002 & ebook]
- http://www.manning.com/jenness
-</pre>
-</dd>
-<dt><em>Pro Perl Debugging</em></dt>
-<dd><a name="perlbook-Pro-Perl-Debugging"></a>
-<pre class="verbatim"> by Richard Foley with Andy Lester
- ISBN 1-59059-454-1 [1st edition July 2005 & ebook]
- http://www.apress.com/9781590594544
-</pre>
-</dd>
-</dl>
-
-<hr>
-<a name="perlbook-Free-_0028as-in-beer_0029-books"></a>
-<div class="header">
-<p>
-Next: <a href="#perlbook-Other-interesting_002c-non_002dPerl-books"
accesskey="n" rel="next">perlbook Other interesting, non-Perl books</a>,
Previous: <a href="#perlbook-Special-Topics" accesskey="p" rel="prev">perlbook
Special Topics</a>, Up: <a href="#perlbook-DESCRIPTION" accesskey="u"
rel="up">perlbook DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Free-_0028as-in-beer_0029-books"></a>
-<h4 class="subsection">4.2.6 Free (as in beer) books</h4>
-
-<p>Some of these books are available as free downloads.
-</p>
-<p><em>Higher-Order Perl</em>: http://hop.perl.plover.com/
-</p>
-<hr>
-<a name="perlbook-Other-interesting_002c-non_002dPerl-books"></a>
-<div class="header">
-<p>
-Next: <a href="#perlbook-A-note-on-freshness" accesskey="n"
rel="next">perlbook A note on freshness</a>, Previous: <a
href="#perlbook-Free-_0028as-in-beer_0029-books" accesskey="p"
rel="prev">perlbook Free (as in beer) books</a>, Up: <a
href="#perlbook-DESCRIPTION" accesskey="u" rel="up">perlbook DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Other-interesting_002c-non_002dPerl-books"></a>
-<h4 class="subsection">4.2.7 Other interesting, non-Perl books</h4>
-
-<p>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:
-</p>
-<dl compact="compact">
-<dt><em>Programming Pearls</em></dt>
-<dd><a name="perlbook-Programming-Pearls"></a>
-<pre class="verbatim"> by Jon Bentley
- ISBN 978-0-201-65788-3 [2 edition, October 1999]
-</pre>
-</dd>
-<dt><em>More Programming Pearls</em></dt>
-<dd><a name="perlbook-More-Programming-Pearls"></a>
-<pre class="verbatim"> by Jon Bentley
- ISBN 0-201-11889-0 [January 1988]
-</pre>
-</dd>
-</dl>
-
-<hr>
-<a name="perlbook-A-note-on-freshness"></a>
-<div class="header">
-<p>
-Next: <a href="#perlbook-Get-your-book-listed" accesskey="n"
rel="next">perlbook Get your book listed</a>, Previous: <a
href="#perlbook-Other-interesting_002c-non_002dPerl-books" accesskey="p"
rel="prev">perlbook Other interesting, non-Perl books</a>, Up: <a
href="#perlbook-DESCRIPTION" accesskey="u" rel="up">perlbook DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="A-note-on-freshness"></a>
-<h4 class="subsection">4.2.8 A note on freshness</h4>
-
-<p>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 .
-</p>
-<p>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.
-</p>
-<hr>
-<a name="perlbook-Get-your-book-listed"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlbook-A-note-on-freshness" accesskey="p"
rel="prev">perlbook A note on freshness</a>, Up: <a
href="#perlbook-DESCRIPTION" accesskey="u" rel="up">perlbook DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Get-your-book-listed"></a>
-<h4 class="subsection">4.2.9 Get your book listed</h4>
-
-<p>If your Perl book isn’t listed and you think it should be, let us
know.
-</p>
-<hr>
-<a name="perlboot"></a>
-<div class="header">
-<p>
-Next: <a href="#perlbot" accesskey="n" rel="next">perlbot</a>, Previous: <a
href="#perlbook" accesskey="p" rel="prev">perlbook</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlboot-1"></a>
-<h2 class="chapter">5 perlboot</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlboot-NAME"
accesskey="1">perlboot NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlboot-DESCRIPTION"
accesskey="2">perlboot DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlboot-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlboot-DESCRIPTION" accesskey="n" rel="next">perlboot
DESCRIPTION</a>, Up: <a href="#perlboot" accesskey="u" rel="up">perlboot</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-4"></a>
-<h3 class="section">5.1 NAME</h3>
-
-<p>perlboot - Links to information on object-oriented programming in Perl
-</p>
-<hr>
-<a name="perlboot-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlboot-NAME" accesskey="p" rel="prev">perlboot NAME</a>,
Up: <a href="#perlboot" accesskey="u" rel="up">perlboot</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-4"></a>
-<h3 class="section">5.2 DESCRIPTION</h3>
-
-<p>For information on OO programming with Perl, please see <a
href="#perlootut-NAME">perlootut NAME</a>
-and <a href="#perlobj-NAME">perlobj NAME</a>.
-</p>
-<p>(The above documents supersede the tutorial that was formerly here in
-perlboot.)
-</p>
-<hr>
-<a name="perlbot"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall" accesskey="n" rel="next">perlcall</a>, Previous: <a
href="#perlboot" accesskey="p" rel="prev">perlboot</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlbot-1"></a>
-<h2 class="chapter">6 perlbot</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlbot-NAME"
accesskey="1">perlbot NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlbot-DESCRIPTION"
accesskey="2">perlbot DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlbot-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlbot-DESCRIPTION" accesskey="n" rel="next">perlbot
DESCRIPTION</a>, Up: <a href="#perlbot" accesskey="u" rel="up">perlbot</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-5"></a>
-<h3 class="section">6.1 NAME</h3>
-
-<p>perlbot - Links to information on object-oriented programming in Perl
-</p>
-<hr>
-<a name="perlbot-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlbot-NAME" accesskey="p" rel="prev">perlbot NAME</a>,
Up: <a href="#perlbot" accesskey="u" rel="up">perlbot</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-5"></a>
-<h3 class="section">6.2 DESCRIPTION</h3>
-
-<p>For information on OO programming with Perl, please see <a
href="#perlootut-NAME">perlootut NAME</a>
-and <a href="#perlobj-NAME">perlobj NAME</a>.
-</p>
-<p>(The above documents supersede the collection of tricks that was formerly
here
-in perlbot.)
-</p>
-<hr>
-<a name="perlcall"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcheat" accesskey="n" rel="next">perlcheat</a>, Previous:
<a href="#perlbot" accesskey="p" rel="prev">perlbot</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlcall-1"></a>
-<h2 class="chapter">7 perlcall</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlcall-NAME"
accesskey="1">perlcall NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-DESCRIPTION"
accesskey="2">perlcall DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-THE-CALL_005f-FUNCTIONS" accesskey="3">perlcall THE CALL_
FUNCTIONS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-FLAG-VALUES"
accesskey="4">perlcall FLAG VALUES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-EXAMPLES"
accesskey="5">perlcall EXAMPLES</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-LIGHTWEIGHT-CALLBACKS" accesskey="6">perlcall LIGHTWEIGHT
CALLBACKS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-SEE-ALSO"
accesskey="7">perlcall SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-AUTHOR"
accesskey="8">perlcall AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-DATE"
accesskey="9">perlcall DATE</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlcall-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-DESCRIPTION" accesskey="n" rel="next">perlcall
DESCRIPTION</a>, Up: <a href="#perlcall" accesskey="u" rel="up">perlcall</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-6"></a>
-<h3 class="section">7.1 NAME</h3>
-
-<p>perlcall - Perl calling conventions from C
-</p>
-<hr>
-<a name="perlcall-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-THE-CALL_005f-FUNCTIONS" accesskey="n"
rel="next">perlcall THE CALL_ FUNCTIONS</a>, Previous: <a href="#perlcall-NAME"
accesskey="p" rel="prev">perlcall NAME</a>, Up: <a href="#perlcall"
accesskey="u" rel="up">perlcall</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-6"></a>
-<h3 class="section">7.2 DESCRIPTION</h3>
-
-<p>The purpose of this document is to show you how to call Perl subroutines
-directly from C, i.e., how to write <em>callbacks</em>.
-</p>
-<p>Apart from discussing the C interface provided by Perl for writing
-callbacks the document uses a series of examples to show how the
-interface actually works in practice. In addition some techniques for
-coding callbacks are covered.
-</p>
-<p>Examples where callbacks are necessary include
-</p>
-<ul>
-<li> An Error Handler
-
-<p>You have created an XSUB interface to an application’s C API.
-</p>
-<p>A fairly common feature in applications is to allow you to define a C
-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.
-</p>
-</li><li> An Event-Driven Program
-
-<p>The classic example of where callbacks are used is when writing an
-event driven program, such as for an X11 application. In this case
-you register functions to be called whenever specific events occur,
-e.g., a mouse button is pressed, the cursor moves into a window or a
-menu item is selected.
-</p>
-</li></ul>
-
-<p>Although the techniques described here are applicable when embedding
-Perl in a C program, this is not the primary goal of this document.
-There are other details that must be considered and are specific to
-embedding Perl. For details on embedding Perl in C refer to
-<a href="#perlembed-NAME">perlembed NAME</a>.
-</p>
-<p>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–<a
href="perlxs.html#Top">(perlxs)</a>
-and <a href="#perlguts-NAME">perlguts NAME</a>.
-</p>
-<hr>
-<a name="perlcall-THE-CALL_005f-FUNCTIONS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-FLAG-VALUES" accesskey="n" rel="next">perlcall FLAG
VALUES</a>, Previous: <a href="#perlcall-DESCRIPTION" accesskey="p"
rel="prev">perlcall DESCRIPTION</a>, Up: <a href="#perlcall" accesskey="u"
rel="up">perlcall</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="THE-CALL_005f-FUNCTIONS"></a>
-<h3 class="section">7.3 THE CALL_ FUNCTIONS</h3>
-
-<p>Although this stuff is easier to explain using examples, you first need
-be aware of a few important definitions.
-</p>
-<p>Perl has a number of C functions that allow you to call Perl
-subroutines. They are
-</p>
-<pre class="verbatim"> I32 call_sv(SV* sv, I32 flags);
- I32 call_pv(char *subname, I32 flags);
- I32 call_method(char *methname, I32 flags);
- I32 call_argv(char *subname, I32 flags, char **argv);
-</pre>
-<p>The key function is <em>call_sv</em>. All the other functions are
-fairly simple wrappers which make it easier to call Perl subroutines in
-special cases. At the end of the day they will all call <em>call_sv</em>
-to invoke the Perl subroutine.
-</p>
-<p>All the <em>call_*</em> functions have a <code>flags</code> parameter which
is
-used to pass a bit mask of options to Perl. This bit mask operates
-identically for each of the functions. The settings available in the
-bit mask are discussed in <a href="#perlcall-FLAG-VALUES">FLAG VALUES</a>.
-</p>
-<p>Each of the functions will now be discussed in turn.
-</p>
-<dl compact="compact">
-<dt>call_sv</dt>
-<dd><a name="perlcall-call_005fsv"></a>
-<p><em>call_sv</em> takes two parameters. The first, <code>sv</code>, 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, <em>Using call_sv</em>, shows how you can make
-use of <em>call_sv</em>.
-</p>
-</dd>
-<dt>call_pv</dt>
-<dd><a name="perlcall-call_005fpv"></a>
-<p>The function, <em>call_pv</em>, is similar to <em>call_sv</em> except it
-expects its first parameter to be a C char* which identifies the Perl
-subroutine you want to call, e.g., <code>call_pv("fred", 0)</code>.
If the
-subroutine you want to call is in another package, just include the
-package name in the string, e.g., <code>"pkg::fred"</code>.
-</p>
-</dd>
-<dt>call_method</dt>
-<dd><a name="perlcall-call_005fmethod"></a>
-<p>The function <em>call_method</em> is used to call a method from a Perl
-class. The parameter <code>methname</code> corresponds to the name of the
method
-to be called. Note that the class that the method belongs to is passed
-on the Perl stack rather than in the parameter list. This class can be
-either the name of the class (for a static method) or a reference to an
-object (for a virtual method). See <a href="#perlobj-NAME">perlobj NAME</a>
for more information on
-static and virtual methods and <a href="#perlcall-Using-call_005fmethod">Using
call_method</a> for an example
-of using <em>call_method</em>.
-</p>
-</dd>
-<dt>call_argv</dt>
-<dd><a name="perlcall-call_005fargv"></a>
-<p><em>call_argv</em> calls the Perl subroutine specified by the C string
-stored in the <code>subname</code> parameter. It also takes the usual
<code>flags</code>
-parameter. The final parameter, <code>argv</code>, consists of a
NULL-terminated
-list of C strings to be passed as parameters to the Perl subroutine.
-See <em>Using call_argv</em>.
-</p>
-</dd>
-</dl>
-
-<p>All the functions return an integer. This is a count of the number of
-items returned by the Perl subroutine. The actual items returned by the
-subroutine are stored on the Perl stack.
-</p>
-<p>As a general rule you should <em>always</em> check the return value from
-these functions. Even if you are expecting only a particular number of
-values to be returned from the Perl subroutine, there is nothing to
-stop someone from doing something unexpected–don’t say you
haven’t
-been warned.
-</p>
-<hr>
-<a name="perlcall-FLAG-VALUES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-EXAMPLES" accesskey="n" rel="next">perlcall
EXAMPLES</a>, Previous: <a href="#perlcall-THE-CALL_005f-FUNCTIONS"
accesskey="p" rel="prev">perlcall THE CALL_ FUNCTIONS</a>, Up: <a
href="#perlcall" accesskey="u" rel="up">perlcall</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="FLAG-VALUES"></a>
-<h3 class="section">7.4 FLAG VALUES</h3>
-
-<p>The <code>flags</code> parameter in all the <em>call_*</em> 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.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlcall-G_005fVOID"
accesskey="1">perlcall G_VOID</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-G_005fSCALAR"
accesskey="2">perlcall G_SCALAR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-G_005fARRAY"
accesskey="3">perlcall G_ARRAY</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-G_005fDISCARD"
accesskey="4">perlcall G_DISCARD</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-G_005fNOARGS"
accesskey="5">perlcall G_NOARGS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-G_005fEVAL"
accesskey="6">perlcall G_EVAL</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-G_005fKEEPERR"
accesskey="7">perlcall G_KEEPERR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Determining-the-Context" accesskey="8">perlcall Determining the
Context</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlcall-G_005fVOID"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-G_005fSCALAR" accesskey="n" rel="next">perlcall
G_SCALAR</a>, Up: <a href="#perlcall-FLAG-VALUES" accesskey="u"
rel="up">perlcall FLAG VALUES</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="G_005fVOID"></a>
-<h4 class="subsection">7.4.1 G_VOID</h4>
-
-<p>Calls the Perl subroutine in a void context.
-</p>
-<p>This flag has 2 effects:
-</p>
-<ol>
-<li> It indicates to the subroutine being called that it is executing in
-a void context (if it executes <em>wantarray</em> the result will be the
-undefined value).
-
-</li><li> It ensures that nothing is actually returned from the subroutine.
-
-</li></ol>
-
-<p>The value returned by the <em>call_*</em> function indicates how many
-items have been returned by the Perl subroutine–in this case it will
-be 0.
-</p>
-<hr>
-<a name="perlcall-G_005fSCALAR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-G_005fARRAY" accesskey="n" rel="next">perlcall
G_ARRAY</a>, Previous: <a href="#perlcall-G_005fVOID" accesskey="p"
rel="prev">perlcall G_VOID</a>, Up: <a href="#perlcall-FLAG-VALUES"
accesskey="u" rel="up">perlcall FLAG VALUES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="G_005fSCALAR"></a>
-<h4 class="subsection">7.4.2 G_SCALAR</h4>
-
-<p>Calls the Perl subroutine in a scalar context. This is the default
-context flag setting for all the <em>call_*</em> functions.
-</p>
-<p>This flag has 2 effects:
-</p>
-<ol>
-<li> It indicates to the subroutine being called that it is executing in a
-scalar context (if it executes <em>wantarray</em> the result will be false).
-
-</li><li> It ensures that only a scalar is actually returned from the
subroutine.
-The subroutine can, of course, ignore the <em>wantarray</em> and return a
-list anyway. If so, then only the last element of the list will be
-returned.
-
-</li></ol>
-
-<p>The value returned by the <em>call_*</em> function indicates how many
-items have been returned by the Perl subroutine - in this case it will
-be either 0 or 1.
-</p>
-<p>If 0, then you have specified the G_DISCARD flag.
-</p>
-<p>If 1, then the item actually returned by the Perl subroutine will be
-stored on the Perl stack - the section <em>Returning a Scalar</em> shows how
-to access this value on the stack. Remember that regardless of how
-many items the Perl subroutine returns, only the last one will be
-accessible from the stack - think of the case where only one value is
-returned as being a list with only one element. Any other items that
-were returned will not exist by the time control returns from the
-<em>call_*</em> function. The section <em>Returning a list in a scalar
-context</em> shows an example of this behavior.
-</p>
-<hr>
-<a name="perlcall-G_005fARRAY"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-G_005fDISCARD" accesskey="n" rel="next">perlcall
G_DISCARD</a>, Previous: <a href="#perlcall-G_005fSCALAR" accesskey="p"
rel="prev">perlcall G_SCALAR</a>, Up: <a href="#perlcall-FLAG-VALUES"
accesskey="u" rel="up">perlcall FLAG VALUES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="G_005fARRAY"></a>
-<h4 class="subsection">7.4.3 G_ARRAY</h4>
-
-<p>Calls the Perl subroutine in a list context.
-</p>
-<p>As with G_SCALAR, this flag has 2 effects:
-</p>
-<ol>
-<li> It indicates to the subroutine being called that it is executing in a
-list context (if it executes <em>wantarray</em> the result will be true).
-
-</li><li> It ensures that all items returned from the subroutine will be
-accessible when control returns from the <em>call_*</em> function.
-
-</li></ol>
-
-<p>The value returned by the <em>call_*</em> function indicates how many
-items have been returned by the Perl subroutine.
-</p>
-<p>If 0, then you have specified the G_DISCARD flag.
-</p>
-<p>If not 0, then it will be a count of the number of items returned by
-the subroutine. These items will be stored on the Perl stack. The
-section <em>Returning a list of values</em> gives an example of using the
-G_ARRAY flag and the mechanics of accessing the returned items from the
-Perl stack.
-</p>
-<hr>
-<a name="perlcall-G_005fDISCARD"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-G_005fNOARGS" accesskey="n" rel="next">perlcall
G_NOARGS</a>, Previous: <a href="#perlcall-G_005fARRAY" accesskey="p"
rel="prev">perlcall G_ARRAY</a>, Up: <a href="#perlcall-FLAG-VALUES"
accesskey="u" rel="up">perlcall FLAG VALUES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="G_005fDISCARD"></a>
-<h4 class="subsection">7.4.4 G_DISCARD</h4>
-
-<p>By default, the <em>call_*</em> functions place the items returned from
-by the Perl subroutine on the stack. If you are not interested in
-these items, then setting this flag will make Perl get rid of them
-automatically for you. Note that it is still possible to indicate a
-context to the Perl subroutine by using either G_SCALAR or G_ARRAY.
-</p>
-<p>If you do not set this flag then it is <em>very</em> important that you make
-sure that any temporaries (i.e., parameters passed to the Perl
-subroutine and values returned from the subroutine) are disposed of
-yourself. The section <em>Returning a Scalar</em> gives details of how to
-dispose of these temporaries explicitly and the section <em>Using Perl to
-dispose of temporaries</em> discusses the specific circumstances where you
-can ignore the problem and let Perl deal with it for you.
-</p>
-<hr>
-<a name="perlcall-G_005fNOARGS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-G_005fEVAL" accesskey="n" rel="next">perlcall
G_EVAL</a>, Previous: <a href="#perlcall-G_005fDISCARD" accesskey="p"
rel="prev">perlcall G_DISCARD</a>, Up: <a href="#perlcall-FLAG-VALUES"
accesskey="u" rel="up">perlcall FLAG VALUES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="G_005fNOARGS"></a>
-<h4 class="subsection">7.4.5 G_NOARGS</h4>
-
-<p>Whenever a Perl subroutine is called using one of the <em>call_*</em>
-functions, it is assumed by default that parameters are to be passed to
-the subroutine. If you are not passing any parameters to the Perl
-subroutine, you can save a bit of time by setting this flag. It has
-the effect of not creating the <code>@_</code> array for the Perl subroutine.
-</p>
-<p>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
-the G_NOARGS flag, it is still possible for the Perl subroutine that
-has been called to think that you have passed it parameters.
-</p>
-<p>In fact, what can happen is that the Perl subroutine you have called
-can access the <code>@_</code> array from a previous Perl subroutine. This
will
-occur when the code that is executing the <em>call_*</em> function has
-itself been called from another Perl subroutine. The code below
-illustrates this
-</p>
-<pre class="verbatim"> sub fred
- { print "@_\n" }
-
- sub joe
- { &fred }
-
- &joe(1,2,3);
-</pre>
-<p>This will print
-</p>
-<pre class="verbatim"> 1 2 3
-</pre>
-<p>What has happened is that <code>fred</code> accesses the <code>@_</code>
array which
-belongs to <code>joe</code>.
-</p>
-<hr>
-<a name="perlcall-G_005fEVAL"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-G_005fKEEPERR" accesskey="n" rel="next">perlcall
G_KEEPERR</a>, Previous: <a href="#perlcall-G_005fNOARGS" accesskey="p"
rel="prev">perlcall G_NOARGS</a>, Up: <a href="#perlcall-FLAG-VALUES"
accesskey="u" rel="up">perlcall FLAG VALUES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="G_005fEVAL"></a>
-<h4 class="subsection">7.4.6 G_EVAL</h4>
-
-<p>It is possible for the Perl subroutine you are calling to terminate
-abnormally, e.g., by calling <em>die</em> explicitly or by not actually
-existing. By default, when either of these events occurs, the
-process will terminate immediately. If you want to trap this
-type of event, specify the G_EVAL flag. It will put an <em>eval { }</em>
-around the subroutine call.
-</p>
-<p>Whenever control returns from the <em>call_*</em> function you need to
-check the <code>$@</code> variable as you would in a normal Perl script.
-</p>
-<p>The value returned from the <em>call_*</em> function is dependent on
-what other flags have been specified and whether an error has
-occurred. Here are all the different cases that can occur:
-</p>
-<ul>
-<li> If the <em>call_*</em> function returns normally, then the value
-returned is as specified in the previous sections.
-
-</li><li> If G_DISCARD is specified, the return value will always be 0.
-
-</li><li> If G_ARRAY is specified <em>and</em> an error has occurred, the
return value
-will always be 0.
-
-</li><li> If G_SCALAR is specified <em>and</em> an error has occurred, the
return value
-will be 1 and the value on the top of the stack will be <em>undef</em>. This
-means that if you have already detected the error by checking <code>$@</code>
and
-you want the program to continue, you must remember to pop the <em>undef</em>
-from the stack.
-
-</li></ul>
-
-<p>See <em>Using G_EVAL</em> for details on using G_EVAL.
-</p>
-<hr>
-<a name="perlcall-G_005fKEEPERR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Determining-the-Context" accesskey="n"
rel="next">perlcall Determining the Context</a>, Previous: <a
href="#perlcall-G_005fEVAL" accesskey="p" rel="prev">perlcall G_EVAL</a>, Up:
<a href="#perlcall-FLAG-VALUES" accesskey="u" rel="up">perlcall FLAG VALUES</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="G_005fKEEPERR"></a>
-<h4 class="subsection">7.4.7 G_KEEPERR</h4>
-
-<p>Using the G_EVAL flag described above will always set <code>$@</code>:
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.
-</p>
-<p>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 <code>__DIE__</code> or
<code>__WARN__</code>
-hooks, and <code>tie</code> functions.
-</p>
-<p>The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
-<em>call_*</em> functions that are used to implement such code, or with
-<code>eval_sv</code>. This flag has no effect on the <code>call_*</code>
functions when
-G_EVAL is not used.
-</p>
-<p>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 <code>$@</code>. Instead the error will
be
-converted into a warning, prefixed with the string "\t(in cleanup)".
-This can be disabled using <code>no warnings 'misc'</code>. If there is no
error,
-<code>$@</code> will not be cleared.
-</p>
-<p>Note that the G_KEEPERR flag does not propagate into inner evals; these
-may still set <code>$@</code>.
-</p>
-<p>The G_KEEPERR flag was introduced in Perl version 5.002.
-</p>
-<p>See <em>Using G_KEEPERR</em> for an example of a situation that warrants the
-use of this flag.
-</p>
-<hr>
-<a name="perlcall-Determining-the-Context"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlcall-G_005fKEEPERR" accesskey="p" rel="prev">perlcall
G_KEEPERR</a>, Up: <a href="#perlcall-FLAG-VALUES" accesskey="u"
rel="up">perlcall FLAG VALUES</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Determining-the-Context"></a>
-<h4 class="subsection">7.4.8 Determining the Context</h4>
-
-<p>As mentioned above, you can determine the context of the currently
-executing subroutine in Perl with <em>wantarray</em>. The equivalent test
-can be made in C by using the <code>GIMME_V</code> macro, which returns
-<code>G_ARRAY</code> if you have been called in a list context,
<code>G_SCALAR</code> if
-in a scalar context, or <code>G_VOID</code> if in a void context (i.e., the
-return value will not be used). An older version of this macro is
-called <code>GIMME</code>; in a void context it returns <code>G_SCALAR</code>
instead of
-<code>G_VOID</code>. An example of using the <code>GIMME_V</code> macro is
shown in
-section <em>Using GIMME_V</em>.
-</p>
-<hr>
-<a name="perlcall-EXAMPLES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-LIGHTWEIGHT-CALLBACKS" accesskey="n"
rel="next">perlcall LIGHTWEIGHT CALLBACKS</a>, Previous: <a
href="#perlcall-FLAG-VALUES" accesskey="p" rel="prev">perlcall FLAG VALUES</a>,
Up: <a href="#perlcall" accesskey="u" rel="up">perlcall</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="EXAMPLES"></a>
-<h3 class="section">7.5 EXAMPLES</h3>
-
-<p>Enough of the definition talk! Let’s have a few examples.
-</p>
-<p>Perl provides many macros to assist in accessing the Perl stack.
-Wherever possible, these macros should always be used when interfacing
-to Perl internals. We hope this should make the code less vulnerable
-to any changes made to Perl in the future.
-</p>
-<p>Another point worth noting is that in the first series of examples I
-have made use of only the <em>call_pv</em> function. This has been done
-to keep the code simpler and ease you into the topic. Wherever
-possible, if the choice is between using <em>call_pv</em> and
-<em>call_sv</em>, you should always try to use <em>call_sv</em>. See
-<em>Using call_sv</em> for details.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlcall-No-Parameters_002c-Nothing-Returned" accesskey="1">perlcall No
Parameters, Nothing Returned</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Passing-Parameters" accesskey="2">perlcall Passing
Parameters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Returning-a-Scalar" accesskey="3">perlcall Returning a
Scalar</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Returning-a-List-of-Values" accesskey="4">perlcall Returning a
List of Values</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Returning-a-List-in-a-Scalar-Context" accesskey="5">perlcall
Returning a List in a Scalar Context</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Returning-Data-from-Perl-via-the-Parameter-List"
accesskey="6">perlcall Returning Data from Perl via the Parameter
List</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-Using-G_005fEVAL"
accesskey="7">perlcall Using G_EVAL</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Using-G_005fKEEPERR" accesskey="8">perlcall Using
G_KEEPERR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcall-Using-call_005fsv"
accesskey="9">perlcall Using call_sv</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Using-call_005fargv">perlcall Using
call_argv</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Using-call_005fmethod">perlcall Using
call_method</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Using-GIMME_005fV">perlcall Using
GIMME_V</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Using-Perl-to-Dispose-of-Temporaries">perlcall Using Perl to
Dispose of Temporaries</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Strategies-for-Storing-Callback-Context-Information">perlcall
Strategies for Storing Callback Context
Information</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Alternate-Stack-Manipulation">perlcall Alternate Stack
Manipulation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcall-Creating-and-Calling-an-Anonymous-Subroutine-in-C">perlcall
Creating and Calling an Anonymous Subroutine in
C</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlcall-No-Parameters_002c-Nothing-Returned"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Passing-Parameters" accesskey="n" rel="next">perlcall
Passing Parameters</a>, Up: <a href="#perlcall-EXAMPLES" accesskey="u"
rel="up">perlcall EXAMPLES</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="No-Parameters_002c-Nothing-Returned"></a>
-<h4 class="subsection">7.5.1 No Parameters, Nothing Returned</h4>
-
-<p>This first trivial example will call a Perl subroutine, <em>PrintUID</em>,
to
-print out the UID of the process.
-</p>
-<pre class="verbatim"> sub PrintUID
- {
- print "UID is $<\n";
- }
-</pre>
-<p>and here is a C function to call it
-</p>
-<pre class="verbatim"> static void
- call_PrintUID()
- {
- dSP;
-
- PUSHMARK(SP);
- call_pv("PrintUID", G_DISCARD|G_NOARGS);
- }
-</pre>
-<p>Simple, eh?
-</p>
-<p>A few points to note about this example:
-</p>
-<ol>
-<li> Ignore <code>dSP</code> and <code>PUSHMARK(SP)</code> for now. They will
be discussed in
-the next example.
-
-</li><li> We aren’t passing any parameters to <em>PrintUID</em> so
G_NOARGS can be
-specified.
-
-</li><li> We aren’t interested in anything returned from
<em>PrintUID</em>, so
-G_DISCARD is specified. Even if <em>PrintUID</em> was changed to
-return some value(s), having specified G_DISCARD will mean that they
-will be wiped by the time control returns from <em>call_pv</em>.
-
-</li><li> As <em>call_pv</em> is being used, the Perl subroutine is specified
as a
-C string. In this case the subroutine name has been ’hard-wired’
into the
-code.
-
-</li><li> Because we specified G_DISCARD, it is not necessary to check the
value
-returned from <em>call_pv</em>. It will always be 0.
-
-</li></ol>
-
-<hr>
-<a name="perlcall-Passing-Parameters"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Returning-a-Scalar" accesskey="n" rel="next">perlcall
Returning a Scalar</a>, Previous: <a
href="#perlcall-No-Parameters_002c-Nothing-Returned" accesskey="p"
rel="prev">perlcall No Parameters, Nothing Returned</a>, Up: <a
href="#perlcall-EXAMPLES" accesskey="u" rel="up">perlcall EXAMPLES</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Passing-Parameters"></a>
-<h4 class="subsection">7.5.2 Passing Parameters</h4>
-
-<p>Now let’s make a slightly more complex example. This time we want to
-call a Perl subroutine, <code>LeftString</code>, which will take 2
parameters–a
-string ($s) and an integer ($n). The subroutine will simply
-print the first $n characters of the string.
-</p>
-<p>So the Perl subroutine would look like this:
-</p>
-<pre class="verbatim"> sub LeftString
- {
- my($s, $n) = @_;
- print substr($s, 0, $n), "\n";
- }
-</pre>
-<p>The C function required to call <em>LeftString</em> would look like this:
-</p>
-<pre class="verbatim"> static void
- call_LeftString(a, b)
- char * a;
- int b;
- {
- dSP;
-
- ENTER;
- SAVETMPS;
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSVpv(a, 0)));
- XPUSHs(sv_2mortal(newSViv(b)));
- PUTBACK;
-
- call_pv("LeftString", G_DISCARD);
-
- FREETMPS;
- LEAVE;
- }
-</pre>
-<p>Here are a few notes on the C function <em>call_LeftString</em>.
-</p>
-<ol>
-<li> Parameters are passed to the Perl subroutine using the Perl stack.
-This is the purpose of the code beginning with the line <code>dSP</code> and
-ending with the line <code>PUTBACK</code>. The <code>dSP</code> declares a
local copy
-of the stack pointer. This local copy should <strong>always</strong> be
accessed
-as <code>SP</code>.
-
-</li><li> If you are going to put something onto the Perl stack, you need to
know
-where to put it. This is the purpose of the macro <code>dSP</code>–it
declares
-and initializes a <em>local</em> copy of the Perl stack pointer.
-
-<p>All the other macros which will be used in this example require you to
-have used this macro.
-</p>
-<p>The exception to this rule is if you are calling a Perl subroutine
-directly from an XSUB function. In this case it is not necessary to
-use the <code>dSP</code> macro explicitly–it will be declared for you
-automatically.
-</p>
-</li><li> Any parameters to be pushed onto the stack should be bracketed by the
-<code>PUSHMARK</code> and <code>PUTBACK</code> macros. The purpose of these
two macros, in
-this context, is to count the number of parameters you are
-pushing automatically. Then whenever Perl is creating the <code>@_</code>
array for the
-subroutine, it knows how big to make it.
-
-<p>The <code>PUSHMARK</code> 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 <em>No Parameters, Nothing Returned</em>) you
-must still call the <code>PUSHMARK</code> macro before you can call any of the
-<em>call_*</em> functions–Perl still needs to know that there are no
-parameters.
-</p>
-<p>The <code>PUTBACK</code> macro sets the global copy of the stack pointer to
be
-the same as our local copy. If we didn’t do this, <em>call_pv</em>
-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, <em>not</em> the global copy.
-</p>
-</li><li> Next, we come to XPUSHs. This is where the parameters actually get
-pushed onto the stack. In this case we are pushing a string and an
-integer.
-
-<p>See <a href="#perlguts-XSUBs-and-the-Argument-Stack">perlguts XSUBs and the
Argument Stack</a> for details
-on how the XPUSH macros work.
-</p>
-</li><li> Because we created temporary values (by means of sv_2mortal() calls)
-we will have to tidy up the Perl stack and dispose of mortal SVs.
-
-<p>This is the purpose of
-</p>
-<pre class="verbatim"> ENTER;
- SAVETMPS;
-</pre>
-<p>at the start of the function, and
-</p>
-<pre class="verbatim"> FREETMPS;
- LEAVE;
-</pre>
-<p>at the end. The <code>ENTER</code>/<code>SAVETMPS</code> pair creates a
boundary for any
-temporaries we create. This means that the temporaries we get rid of
-will be limited to those which were created after these calls.
-</p>
-<p>The <code>FREETMPS</code>/<code>LEAVE</code> pair will get rid of any
values returned by
-the Perl subroutine (see next example), plus it will also dump the
-mortal SVs we have created. Having <code>ENTER</code>/<code>SAVETMPS</code>
at the
-beginning of the code makes sure that no other mortals are destroyed.
-</p>
-<p>Think of these macros as working a bit like <code>{</code> and
<code>}</code> in Perl
-to limit the scope of local variables.
-</p>
-<p>See the section <em>Using Perl to Dispose of Temporaries</em> for details of
-an alternative to using these macros.
-</p>
-</li><li> Finally, <em>LeftString</em> can now be called via the
<em>call_pv</em> function.
-The only flag specified this time is G_DISCARD. Because we are passing
-2 parameters to the Perl subroutine this time, we have not specified
-G_NOARGS.
-
-</li></ol>
-
-<hr>
-<a name="perlcall-Returning-a-Scalar"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Returning-a-List-of-Values" accesskey="n"
rel="next">perlcall Returning a List of Values</a>, Previous: <a
href="#perlcall-Passing-Parameters" accesskey="p" rel="prev">perlcall Passing
Parameters</a>, Up: <a href="#perlcall-EXAMPLES" accesskey="u"
rel="up">perlcall EXAMPLES</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Returning-a-Scalar"></a>
-<h4 class="subsection">7.5.3 Returning a Scalar</h4>
-
-<p>Now for an example of dealing with the items returned from a Perl
-subroutine.
-</p>
-<p>Here is a Perl subroutine, <em>Adder</em>, that takes 2 integer parameters
-and simply returns their sum.
-</p>
-<pre class="verbatim"> sub Adder
- {
- my($a, $b) = @_;
- $a + $b;
- }
-</pre>
-<p>Because we are now concerned with the return value from <em>Adder</em>, the
C
-function required to call it is now a bit more complex.
-</p>
-<pre class="verbatim"> static void
- call_Adder(a, b)
- int a;
- int b;
- {
- dSP;
- int count;
-
- ENTER;
- SAVETMPS;
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSViv(a)));
- XPUSHs(sv_2mortal(newSViv(b)));
- PUTBACK;
-
- count = call_pv("Adder", G_SCALAR);
-
- SPAGAIN;
-
- if (count != 1)
- croak("Big trouble\n");
-
- printf ("The sum of %d and %d is %d\n", a, b, POPi);
-
- PUTBACK;
- FREETMPS;
- LEAVE;
- }
-</pre>
-<p>Points to note this time are
-</p>
-<ol>
-<li> The only flag specified this time was G_SCALAR. That means that the
<code>@_</code>
-array will be created and that the value returned by <em>Adder</em> will
-still exist after the call to <em>call_pv</em>.
-
-</li><li> The purpose of the macro <code>SPAGAIN</code> 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 during the
-<em>call_pv</em> call.
-
-<p>If you are making use of the Perl stack pointer in your code you must
-always refresh the local copy using SPAGAIN whenever you make use
-of the <em>call_*</em> functions or any other Perl internal function.
-</p>
-</li><li> Although only a single value was expected to be returned from
<em>Adder</em>,
-it is still good practice to check the return code from <em>call_pv</em>
-anyway.
-
-<p>Expecting a single value is not quite the same as knowing that there
-will be one. If someone modified <em>Adder</em> to return a list and we
-didn’t check for that possibility and take appropriate action the Perl
-stack would end up in an inconsistent state. That is something you
-<em>really</em> don’t want to happen ever.
-</p>
-</li><li> The <code>POPi</code> macro is used here to pop the return value
from the stack.
-In this case we wanted an integer, so <code>POPi</code> was used.
-
-<p>Here is the complete list of POP macros available, along with the types
-they return.
-</p>
-<pre class="verbatim"> POPs SV
- POPp pointer
- POPn double
- POPi integer
- POPl long
-</pre>
-</li><li> The final <code>PUTBACK</code> is used to leave the Perl stack in a
consistent
-state before exiting the function. This is necessary because when we
-popped the return value from the stack with <code>POPi</code> it updated only
our
-local copy of the stack pointer. Remember, <code>PUTBACK</code> sets the
global
-stack pointer to be the same as our local copy.
-
-</li></ol>
-
-<hr>
-<a name="perlcall-Returning-a-List-of-Values"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Returning-a-List-in-a-Scalar-Context" accesskey="n"
rel="next">perlcall Returning a List in a Scalar Context</a>, Previous: <a
href="#perlcall-Returning-a-Scalar" accesskey="p" rel="prev">perlcall Returning
a Scalar</a>, Up: <a href="#perlcall-EXAMPLES" accesskey="u" rel="up">perlcall
EXAMPLES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Returning-a-List-of-Values"></a>
-<h4 class="subsection">7.5.4 Returning a List of Values</h4>
-
-<p>Now, let’s extend the previous example to return both the sum of the
-parameters and the difference.
-</p>
-<p>Here is the Perl subroutine
-</p>
-<pre class="verbatim"> sub AddSubtract
- {
- my($a, $b) = @_;
- ($a+$b, $a-$b);
- }
-</pre>
-<p>and this is the C function
-</p>
-<pre class="verbatim"> static void
- call_AddSubtract(a, b)
- int a;
- int b;
- {
- dSP;
- int count;
-
- ENTER;
- SAVETMPS;
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSViv(a)));
- XPUSHs(sv_2mortal(newSViv(b)));
- PUTBACK;
-
- count = call_pv("AddSubtract", G_ARRAY);
-
- SPAGAIN;
-
- if (count != 2)
- croak("Big trouble\n");
-
- printf ("%d - %d = %d\n", a, b, POPi);
- printf ("%d + %d = %d\n", a, b, POPi);
-
- PUTBACK;
- FREETMPS;
- LEAVE;
- }
-</pre>
-<p>If <em>call_AddSubtract</em> is called like this
-</p>
-<pre class="verbatim"> call_AddSubtract(7, 4);
-</pre>
-<p>then here is the output
-</p>
-<pre class="verbatim"> 7 - 4 = 3
- 7 + 4 = 11
-</pre>
-<p>Notes
-</p>
-<ol>
-<li> We wanted list context, so G_ARRAY was used.
-
-</li><li> Not surprisingly <code>POPi</code> is used twice this time because
we were
-retrieving 2 values from the stack. The important thing to note is that
-when using the <code>POP*</code> macros they come off the stack in
<em>reverse</em>
-order.
-
-</li></ol>
-
-<hr>
-<a name="perlcall-Returning-a-List-in-a-Scalar-Context"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Returning-Data-from-Perl-via-the-Parameter-List"
accesskey="n" rel="next">perlcall Returning Data from Perl via the Parameter
List</a>, Previous: <a href="#perlcall-Returning-a-List-of-Values"
accesskey="p" rel="prev">perlcall Returning a List of Values</a>, Up: <a
href="#perlcall-EXAMPLES" accesskey="u" rel="up">perlcall EXAMPLES</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Returning-a-List-in-a-Scalar-Context"></a>
-<h4 class="subsection">7.5.5 Returning a List in a Scalar Context</h4>
-
-<p>Say the Perl subroutine in the previous section was called in a scalar
-context, like this
-</p>
-<pre class="verbatim"> static void
- call_AddSubScalar(a, b)
- int a;
- int b;
- {
- dSP;
- int count;
- int i;
-
- ENTER;
- SAVETMPS;
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSViv(a)));
- XPUSHs(sv_2mortal(newSViv(b)));
- PUTBACK;
-
- count = call_pv("AddSubtract", G_SCALAR);
-
- SPAGAIN;
-
- printf ("Items Returned = %d\n", count);
-
- for (i = 1; i <= count; ++i)
- printf ("Value %d = %d\n", i, POPi);
-
- PUTBACK;
- FREETMPS;
- LEAVE;
- }
-</pre>
-<p>The other modification made is that <em>call_AddSubScalar</em> will print
the
-number of items returned from the Perl subroutine and their value (for
-simplicity it assumes that they are integer). So if
-<em>call_AddSubScalar</em> is called
-</p>
-<pre class="verbatim"> call_AddSubScalar(7, 4);
-</pre>
-<p>then the output will be
-</p>
-<pre class="verbatim"> Items Returned = 1
- Value 1 = 3
-</pre>
-<p>In this case the main point to note is that only the last item in the
-list is returned from the subroutine. <em>AddSubtract</em> actually made it
back to
-<em>call_AddSubScalar</em>.
-</p>
-<hr>
-<a name="perlcall-Returning-Data-from-Perl-via-the-Parameter-List"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Using-G_005fEVAL" accesskey="n" rel="next">perlcall
Using G_EVAL</a>, Previous: <a
href="#perlcall-Returning-a-List-in-a-Scalar-Context" accesskey="p"
rel="prev">perlcall Returning a List in a Scalar Context</a>, Up: <a
href="#perlcall-EXAMPLES" accesskey="u" rel="up">perlcall EXAMPLES</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Returning-Data-from-Perl-via-the-Parameter-List"></a>
-<h4 class="subsection">7.5.6 Returning Data from Perl via the Parameter
List</h4>
-
-<p>It is also possible to return values directly via the parameter
-list–whether it is actually desirable to do it is another matter
entirely.
-</p>
-<p>The Perl subroutine, <em>Inc</em>, below takes 2 parameters and increments
-each directly.
-</p>
-<pre class="verbatim"> sub Inc
- {
- ++ $_[0];
- ++ $_[1];
- }
-</pre>
-<p>and here is a C function to call it.
-</p>
-<pre class="verbatim"> static void
- call_Inc(a, b)
- int a;
- int b;
- {
- dSP;
- int count;
- SV * sva;
- SV * svb;
-
- ENTER;
- SAVETMPS;
-
- sva = sv_2mortal(newSViv(a));
- svb = sv_2mortal(newSViv(b));
-
- PUSHMARK(SP);
- XPUSHs(sva);
- XPUSHs(svb);
- PUTBACK;
-
- count = call_pv("Inc", G_DISCARD);
-
- if (count != 0)
- croak ("call_Inc: expected 0 values from 'Inc', got
%d\n",
- count);
-
- printf ("%d + 1 = %d\n", a, SvIV(sva));
- printf ("%d + 1 = %d\n", b, SvIV(svb));
-
- FREETMPS;
- LEAVE;
- }
-</pre>
-<p>To be able to access the two parameters that were pushed onto the stack
-after they return from <em>call_pv</em> it is necessary to make a note
-of their addresses–thus the two variables <code>sva</code> and
<code>svb</code>.
-</p>
-<p>The reason this is necessary is that the area of the Perl stack which
-held them will very likely have been overwritten by something else by
-the time control returns from <em>call_pv</em>.
-</p>
-<hr>
-<a name="perlcall-Using-G_005fEVAL"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Using-G_005fKEEPERR" accesskey="n"
rel="next">perlcall Using G_KEEPERR</a>, Previous: <a
href="#perlcall-Returning-Data-from-Perl-via-the-Parameter-List" accesskey="p"
rel="prev">perlcall Returning Data from Perl via the Parameter List</a>, Up: <a
href="#perlcall-EXAMPLES" accesskey="u" rel="up">perlcall EXAMPLES</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-G_005fEVAL"></a>
-<h4 class="subsection">7.5.7 Using G_EVAL</h4>
-
-<p>Now an example using G_EVAL. Below is a Perl subroutine which computes
-the difference of its 2 parameters. If this would result in a negative
-result, the subroutine calls <em>die</em>.
-</p>
-<pre class="verbatim"> sub Subtract
- {
- my ($a, $b) = @_;
-
- die "death can be fatal\n" if $a < $b;
-
- $a - $b;
- }
-</pre>
-<p>and some C to call it
-</p>
-<pre class="verbatim"> static void
- call_Subtract(a, b)
- int a;
- int b;
- {
- dSP;
- int count;
-
- ENTER;
- SAVETMPS;
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSViv(a)));
- XPUSHs(sv_2mortal(newSViv(b)));
- PUTBACK;
-
- count = call_pv("Subtract", G_EVAL|G_SCALAR);
-
- SPAGAIN;
-
- /* Check the eval first */
- if (SvTRUE(ERRSV))
- {
- printf ("Uh oh - %s\n", SvPV_nolen(ERRSV));
- POPs;
- }
- else
- {
- if (count != 1)
- croak("call_Subtract: wanted 1 value from 'Subtract', got
%d\n",
- count);
-
- printf ("%d - %d = %d\n", a, b, POPi);
- }
-
- PUTBACK;
- FREETMPS;
- LEAVE;
- }
-</pre>
-<p>If <em>call_Subtract</em> is called thus
-</p>
-<pre class="verbatim"> call_Subtract(4, 5)
-</pre>
-<p>the following will be printed
-</p>
-<pre class="verbatim"> Uh oh - death can be fatal
-</pre>
-<p>Notes
-</p>
-<ol>
-<li> We want to be able to catch the <em>die</em> so we have used the G_EVAL
-flag. Not specifying this flag would mean that the program would
-terminate immediately at the <em>die</em> statement in the subroutine
-<em>Subtract</em>.
-
-</li><li> The code
-
-<pre class="verbatim"> if (SvTRUE(ERRSV))
- {
- printf ("Uh oh - %s\n", SvPV_nolen(ERRSV));
- POPs;
- }
-</pre>
-<p>is the direct equivalent of this bit of Perl
-</p>
-<pre class="verbatim"> print "Uh oh - address@hidden" if $@;
-</pre>
-<p><code>PL_errgv</code> is a perl global of type <code>GV *</code> that
points to the
-symbol table entry containing the error. <code>ERRSV</code> therefore
-refers to the C equivalent of <code>$@</code>.
-</p>
-</li><li> Note that the stack is popped using <code>POPs</code> in the block
where
-<code>SvTRUE(ERRSV)</code> is true. This is necessary because whenever a
-<em>call_*</em> function invoked with G_EVAL|G_SCALAR returns an error,
-the top of the stack holds the value <em>undef</em>. Because we want the
-program to continue after detecting this error, it is essential that
-the stack be tidied up by removing the <em>undef</em>.
-
-</li></ol>
-
-<hr>
-<a name="perlcall-Using-G_005fKEEPERR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Using-call_005fsv" accesskey="n" rel="next">perlcall
Using call_sv</a>, Previous: <a href="#perlcall-Using-G_005fEVAL" accesskey="p"
rel="prev">perlcall Using G_EVAL</a>, Up: <a href="#perlcall-EXAMPLES"
accesskey="u" rel="up">perlcall EXAMPLES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-G_005fKEEPERR"></a>
-<h4 class="subsection">7.5.8 Using G_KEEPERR</h4>
-
-<p>Consider this rather facetious example, where we have used an XS
-version of the call_Subtract example above inside a destructor:
-</p>
-<pre class="verbatim"> package Foo;
- sub new { bless {}, $_[0] }
- sub Subtract {
- my($a,$b) = @_;
- die "death can be fatal" if $a < $b;
- $a - $b;
- }
- sub DESTROY { call_Subtract(5, 4); }
- sub foo { die "foo dies"; }
-
- package main;
- {
- my $foo = Foo->new;
- eval { $foo->foo };
- }
- print "Saw: $@" if $@; # should be, but isn't
-</pre>
-<p>This example will fail to recognize that an error occurred inside the
-<code>eval {}</code>. Here’s why: the call_Subtract code got executed
while perl
-was cleaning up temporaries when exiting the outer braced block, and because
-call_Subtract is implemented with <em>call_pv</em> using the G_EVAL
-flag, it promptly reset <code>$@</code>. This results in the failure of the
-outermost test for <code>$@</code>, and thereby the failure of the error trap.
-</p>
-<p>Appending the G_KEEPERR flag, so that the <em>call_pv</em> call in
-call_Subtract reads:
-</p>
-<pre class="verbatim"> count = call_pv("Subtract",
G_EVAL|G_SCALAR|G_KEEPERR);
-</pre>
-<p>will preserve the error and restore reliable error handling.
-</p>
-<hr>
-<a name="perlcall-Using-call_005fsv"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Using-call_005fargv" accesskey="n"
rel="next">perlcall Using call_argv</a>, Previous: <a
href="#perlcall-Using-G_005fKEEPERR" accesskey="p" rel="prev">perlcall Using
G_KEEPERR</a>, Up: <a href="#perlcall-EXAMPLES" accesskey="u" rel="up">perlcall
EXAMPLES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-call_005fsv"></a>
-<h4 class="subsection">7.5.9 Using call_sv</h4>
-
-<p>In all the previous examples I have ’hard-wired’ the name of
the Perl
-subroutine to be called from C. Most of the time though, it is more
-convenient to be able to specify the name of the Perl subroutine from
-within the Perl script.
-</p>
-<p>Consider the Perl code below
-</p>
-<pre class="verbatim"> sub fred
- {
- print "Hello there\n";
- }
-
- CallSubPV("fred");
-</pre>
-<p>Here is a snippet of XSUB which defines <em>CallSubPV</em>.
-</p>
-<pre class="verbatim"> void
- CallSubPV(name)
- char * name
- CODE:
- PUSHMARK(SP);
- call_pv(name, G_DISCARD|G_NOARGS);
-</pre>
-<p>That is fine as far as it goes. The thing is, the Perl subroutine
-can be specified as only a string, however, Perl allows references
-to subroutines and anonymous subroutines.
-This is where <em>call_sv</em> is useful.
-</p>
-<p>The code below for <em>CallSubSV</em> is identical to <em>CallSubPV</em>
except
-that the <code>name</code> parameter is now defined as an SV* and we use
-<em>call_sv</em> instead of <em>call_pv</em>.
-</p>
-<pre class="verbatim"> void
- CallSubSV(name)
- SV * name
- CODE:
- PUSHMARK(SP);
- call_sv(name, G_DISCARD|G_NOARGS);
-</pre>
-<p>Because we are using an SV to call <em>fred</em> the following can all be
used:
-</p>
-<pre class="verbatim"> CallSubSV("fred");
- CallSubSV(\&fred);
- $ref = \&fred;
- CallSubSV($ref);
- CallSubSV( sub { print "Hello there\n" } );
-</pre>
-<p>As you can see, <em>call_sv</em> gives you much greater flexibility in
-how you can specify the Perl subroutine.
-</p>
-<p>You should note that, if it is necessary to store the SV (<code>name</code>
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:
-</p>
-<pre class="verbatim"> static SV * rememberSub;
-
- void
- SaveSub1(name)
- SV * name
- CODE:
- rememberSub = name;
-
- void
- CallSavedSub1()
- CODE:
- PUSHMARK(SP);
- call_sv(rememberSub, G_DISCARD|G_NOARGS);
-</pre>
-<p>The reason this is wrong is that, by the time you come to use the
-pointer <code>rememberSub</code> in <code>CallSavedSub1</code>, it may or may
not still refer
-to the Perl subroutine that was recorded in <code>SaveSub1</code>. This is
-particularly true for these cases:
-</p>
-<pre class="verbatim"> SaveSub1(\&fred);
- CallSavedSub1();
-
- SaveSub1( sub { print "Hello there\n" } );
- CallSavedSub1();
-</pre>
-<p>By the time each of the <code>SaveSub1</code> 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
-</p>
-<pre class="verbatim"> Can't use an undefined value as a subroutine
reference at ...
-</pre>
-<p>for each of the <code>CallSavedSub1</code> lines.
-</p>
-<p>Similarly, with this code
-</p>
-<pre class="verbatim"> $ref = \&fred;
- SaveSub1($ref);
- $ref = 47;
- CallSavedSub1();
-</pre>
-<p>you can expect one of these messages (which you actually get is dependent on
-the version of Perl you are using)
-</p>
-<pre class="verbatim"> Not a CODE reference at ...
- Undefined subroutine &main::47 called ...
-</pre>
-<p>The variable $ref may have referred to the subroutine <code>fred</code>
-whenever the call to <code>SaveSub1</code> was made but by the time
-<code>CallSavedSub1</code> gets called it now holds the number
<code>47</code>. Because we
-saved only a pointer to the original SV in <code>SaveSub1</code>, any changes
to
-$ref will be tracked by the pointer <code>rememberSub</code>. This means that
-whenever <code>CallSavedSub1</code> gets called, it will attempt to execute the
-code which is referenced by the SV* <code>rememberSub</code>. In this case
-though, it now refers to the integer <code>47</code>, so expect Perl to
complain
-loudly.
-</p>
-<p>A similar but more subtle problem is illustrated with this code:
-</p>
-<pre class="verbatim"> $ref = \&fred;
- SaveSub1($ref);
- $ref = \&joe;
- CallSavedSub1();
-</pre>
-<p>This time whenever <code>CallSavedSub1</code> gets called it will execute
the Perl
-subroutine <code>joe</code> (assuming it exists) rather than <code>fred</code>
as was
-originally requested in the call to <code>SaveSub1</code>.
-</p>
-<p>To get around these problems it is necessary to take a full copy of the
-SV. The code below shows <code>SaveSub2</code> modified to do that.
-</p>
-<pre class="verbatim"> static SV * keepSub = (SV*)NULL;
-
- void
- SaveSub2(name)
- SV * name
- CODE:
- /* Take a copy of the callback */
- if (keepSub == (SV*)NULL)
- /* First time, so create a new SV */
- keepSub = newSVsv(name);
- else
- /* Been here before, so overwrite */
- SvSetSV(keepSub, name);
-
- void
- CallSavedSub2()
- CODE:
- PUSHMARK(SP);
- call_sv(keepSub, G_DISCARD|G_NOARGS);
-</pre>
-<p>To avoid creating a new SV every time <code>SaveSub2</code> 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 <code>name</code> is copied to the variable <code>keepSub</code> in
one
-operation using <code>newSVsv</code>. Thereafter, whenever
<code>SaveSub2</code> is called,
-the existing SV, <code>keepSub</code>, is overwritten with the new value using
-<code>SvSetSV</code>.
-</p>
-<hr>
-<a name="perlcall-Using-call_005fargv"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Using-call_005fmethod" accesskey="n"
rel="next">perlcall Using call_method</a>, Previous: <a
href="#perlcall-Using-call_005fsv" accesskey="p" rel="prev">perlcall Using
call_sv</a>, Up: <a href="#perlcall-EXAMPLES" accesskey="u" rel="up">perlcall
EXAMPLES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-call_005fargv"></a>
-<h4 class="subsection">7.5.10 Using call_argv</h4>
-
-<p>Here is a Perl subroutine which prints whatever parameters are passed
-to it.
-</p>
-<pre class="verbatim"> sub PrintList
- {
- my(@list) = @_;
-
- foreach (@list) { print "$_\n" }
- }
-</pre>
-<p>And here is an example of <em>call_argv</em> which will call
-<em>PrintList</em>.
-</p>
-<pre class="verbatim"> static char * words[] = {"alpha",
"beta", "gamma", "delta", NULL};
-
- static void
- call_PrintList()
- {
- dSP;
-
- call_argv("PrintList", G_DISCARD, words);
- }
-</pre>
-<p>Note that it is not necessary to call <code>PUSHMARK</code> in this
instance.
-This is because <em>call_argv</em> will do it for you.
-</p>
-<hr>
-<a name="perlcall-Using-call_005fmethod"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Using-GIMME_005fV" accesskey="n" rel="next">perlcall
Using GIMME_V</a>, Previous: <a href="#perlcall-Using-call_005fargv"
accesskey="p" rel="prev">perlcall Using call_argv</a>, Up: <a
href="#perlcall-EXAMPLES" accesskey="u" rel="up">perlcall EXAMPLES</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-call_005fmethod"></a>
-<h4 class="subsection">7.5.11 Using call_method</h4>
-
-<p>Consider the following Perl code:
-</p>
-<pre class="verbatim"> {
- package Mine;
-
- sub new
- {
- my($type) = shift;
- bless address@hidden
- }
-
- sub Display
- {
- my ($self, $index) = @_;
- print "$index: $$self[$index]\n";
- }
-
- sub PrintID
- {
- my($class) = @_;
- print "This is Class $class version 1.0\n";
- }
- }
-</pre>
-<p>It implements just a very simple class to manage an array. Apart from
-the constructor, <code>new</code>, it declares methods, one static and one
-virtual. The static method, <code>PrintID</code>, prints out simply the class
-name and a version number. The virtual method, <code>Display</code>, prints
out a
-single element of the array. Here is an all-Perl example of using it.
-</p>
-<pre class="verbatim"> $a = Mine->new('red', 'green', 'blue');
- $a->Display(1);
- Mine->PrintID;
-</pre>
-<p>will print
-</p>
-<pre class="verbatim"> 1: green
- This is Class Mine version 1.0
-</pre>
-<p>Calling a Perl method from C is fairly straightforward. The following
-things are required:
-</p>
-<ul>
-<li> A reference to the object for a virtual method or the name of the class
-for a static method
-
-</li><li> The name of the method
-
-</li><li> Any other parameters specific to the method
-
-</li></ul>
-
-<p>Here is a simple XSUB which illustrates the mechanics of calling both
-the <code>PrintID</code> and <code>Display</code> methods from C.
-</p>
-<pre class="verbatim"> void
- call_Method(ref, method, index)
- SV * ref
- char * method
- int index
- CODE:
- PUSHMARK(SP);
- XPUSHs(ref);
- XPUSHs(sv_2mortal(newSViv(index)));
- PUTBACK;
-
- call_method(method, G_DISCARD);
-
- void
- call_PrintID(class, method)
- char * class
- char * method
- CODE:
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSVpv(class, 0)));
- PUTBACK;
-
- call_method(method, G_DISCARD);
-</pre>
-<p>So the methods <code>PrintID</code> and <code>Display</code> can be invoked
like this:
-</p>
-<pre class="verbatim"> $a = Mine->new('red', 'green', 'blue');
- call_Method($a, 'Display', 1);
- call_PrintID('Mine', 'PrintID');
-</pre>
-<p>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 <em>call_method</em>.
-</p>
-<hr>
-<a name="perlcall-Using-GIMME_005fV"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Using-Perl-to-Dispose-of-Temporaries" accesskey="n"
rel="next">perlcall Using Perl to Dispose of Temporaries</a>, Previous: <a
href="#perlcall-Using-call_005fmethod" accesskey="p" rel="prev">perlcall Using
call_method</a>, Up: <a href="#perlcall-EXAMPLES" accesskey="u"
rel="up">perlcall EXAMPLES</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-GIMME_005fV"></a>
-<h4 class="subsection">7.5.12 Using GIMME_V</h4>
-
-<p>Here is a trivial XSUB which prints the context in which it is
-currently executing.
-</p>
-<pre class="verbatim"> void
- PrintContext()
- CODE:
- I32 gimme = GIMME_V;
- if (gimme == G_VOID)
- printf ("Context is Void\n");
- else if (gimme == G_SCALAR)
- printf ("Context is Scalar\n");
- else
- printf ("Context is Array\n");
-</pre>
-<p>And here is some Perl to test it.
-</p>
-<pre class="verbatim"> PrintContext;
- $a = PrintContext;
- @a = PrintContext;
-</pre>
-<p>The output from that will be
-</p>
-<pre class="verbatim"> Context is Void
- Context is Scalar
- Context is Array
-</pre>
-<hr>
-<a name="perlcall-Using-Perl-to-Dispose-of-Temporaries"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Strategies-for-Storing-Callback-Context-Information"
accesskey="n" rel="next">perlcall Strategies for Storing Callback Context
Information</a>, Previous: <a href="#perlcall-Using-GIMME_005fV" accesskey="p"
rel="prev">perlcall Using GIMME_V</a>, Up: <a href="#perlcall-EXAMPLES"
accesskey="u" rel="up">perlcall EXAMPLES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-Perl-to-Dispose-of-Temporaries"></a>
-<h4 class="subsection">7.5.13 Using Perl to Dispose of Temporaries</h4>
-
-<p>In the examples given to date, any temporaries created in the callback
-(i.e., parameters passed on the stack to the <em>call_*</em> function or
-values returned via the stack) have been freed by one of these methods:
-</p>
-<ul>
-<li> Specifying the G_DISCARD flag with <em>call_*</em>
-
-</li><li> Explicitly using the
<code>ENTER</code>/<code>SAVETMPS</code>–<code>FREETMPS</code>/<code>LEAVE</code>
pairing
-
-</li></ul>
-
-<p>There is another method which can be used, namely letting Perl do it
-for you automatically whenever it regains control after the callback
-has terminated. This is done by simply not using the
-</p>
-<pre class="verbatim"> ENTER;
- SAVETMPS;
- ...
- FREETMPS;
- LEAVE;
-</pre>
-<p>sequence in the callback (and not, of course, specifying the G_DISCARD
-flag).
-</p>
-<p>If you are going to use this method you have to be aware of a possible
-memory leak which can arise under very specific circumstances. To
-explain these circumstances you need to know a bit about the flow of
-control between Perl and the callback routine.
-</p>
-<p>The examples given at the start of the document (an error handler and
-an event driven program) are typical of the two main sorts of flow
-control that you are likely to encounter with callbacks. There is a
-very important distinction between them, so pay attention.
-</p>
-<p>In the first example, an error handler, the flow of control could be as
-follows. You have created an interface to an external library.
-Control can reach the external library like this
-</p>
-<pre class="verbatim"> perl --> XSUB --> external library
-</pre>
-<p>Whilst control is in the library, an error condition occurs. You have
-previously set up a Perl callback to handle this situation, so it will
-get executed. Once the callback has finished, control will drop back to
-Perl again. Here is what the flow of control will be like in that
-situation
-</p>
-<pre class="verbatim"> perl --> XSUB --> external library
- ...
- error occurs
- ...
- external library --> call_* --> perl
- |
- perl <-- XSUB <-- external library <-- call_* <----+
-</pre>
-<p>After processing of the error using <em>call_*</em> is completed,
-control reverts back to Perl more or less immediately.
-</p>
-<p>In the diagram, the further right you go the more deeply nested the
-scope is. It is only when control is back with perl on the extreme
-left of the diagram that you will have dropped back to the enclosing
-scope and any temporaries you have left hanging around will be freed.
-</p>
-<p>In the second example, an event driven program, the flow of control
-will be more like this
-</p>
-<pre class="verbatim"> perl --> XSUB --> event handler
- ...
- event handler --> call_* --> perl
- |
- event handler <-- call_* <----+
- ...
- event handler --> call_* --> perl
- |
- event handler <-- call_* <----+
- ...
- event handler --> call_* --> perl
- |
- event handler <-- call_* <----+
-</pre>
-<p>In this case the flow of control can consist of only the repeated
-sequence
-</p>
-<pre class="verbatim"> event handler --> call_* --> perl
-</pre>
-<p>for practically the complete duration of the program. This means that
-control may <em>never</em> drop back to the surrounding scope in Perl at the
-extreme left.
-</p>
-<p>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
-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!
-</p>
-<p>So here is the bottom line–if you are sure that control will revert
-back to the enclosing Perl scope fairly quickly after the end of your
-callback, then it isn’t absolutely necessary to dispose explicitly of
-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.
-</p>
-<hr>
-<a name="perlcall-Strategies-for-Storing-Callback-Context-Information"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Alternate-Stack-Manipulation" accesskey="n"
rel="next">perlcall Alternate Stack Manipulation</a>, Previous: <a
href="#perlcall-Using-Perl-to-Dispose-of-Temporaries" accesskey="p"
rel="prev">perlcall Using Perl to Dispose of Temporaries</a>, Up: <a
href="#perlcall-EXAMPLES" accesskey="u" rel="up">perlcall EXAMPLES</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Strategies-for-Storing-Callback-Context-Information"></a>
-<h4 class="subsection">7.5.14 Strategies for Storing Callback Context
Information</h4>
-
-<p>Potentially one of the trickiest problems to overcome when designing a
-callback interface can be figuring out how to store the mapping between
-the C callback function and the Perl equivalent.
-</p>
-<p>To help understand why this can be a real problem first consider how a
-callback is set up in an all C environment. Typically a C API will
-provide a function to register a callback. This will expect a pointer
-to a function as one of its parameters. Below is a call to a
-hypothetical function <code>register_fatal</code> which registers the C
function
-to get called when a fatal error occurs.
-</p>
-<pre class="verbatim"> register_fatal(cb1);
-</pre>
-<p>The single parameter <code>cb1</code> is a pointer to a function, so you
must
-have defined <code>cb1</code> in your code, say something like this
-</p>
-<pre class="verbatim"> static void
- cb1()
- {
- printf ("Fatal Error\n");
- exit(1);
- }
-</pre>
-<p>Now change that to call a Perl subroutine instead
-</p>
-<pre class="verbatim"> static SV * callback = (SV*)NULL;
-
- static void
- cb1()
- {
- dSP;
-
- PUSHMARK(SP);
-
- /* Call the Perl sub to process the callback */
- call_sv(callback, G_DISCARD);
- }
-
-
- void
- register_fatal(fn)
- SV * fn
- CODE:
- /* Remember the Perl sub */
- if (callback == (SV*)NULL)
- callback = newSVsv(fn);
- else
- SvSetSV(callback, fn);
-
- /* register the callback with the external library */
- register_fatal(cb1);
-</pre>
-<p>where the Perl equivalent of <code>register_fatal</code> and the callback it
-registers, <code>pcb1</code>, might look like this
-</p>
-<pre class="verbatim"> # Register the sub pcb1
- register_fatal(\&pcb1);
-
- sub pcb1
- {
- die "I'm dying...\n";
- }
-</pre>
-<p>The mapping between the C callback and the Perl equivalent is stored in
-the global variable <code>callback</code>.
-</p>
-<p>This will be adequate if you ever need to have only one callback
-registered at any time. An example could be an error handler like the
-code sketched out above. Remember though, repeated calls to
-<code>register_fatal</code> will replace the previously registered callback
-function with the new one.
-</p>
-<p>Say for example you want to interface to a library which allows asynchronous
-file i/o. In this case you may be able to register a callback whenever
-a read operation has completed. To be of any use we want to be able to
-call separate Perl subroutines for each file that is opened. As it
-stands, the error handler example above would not be adequate as it
-allows only a single callback to be defined at any time. What we
-require is a means of storing the mapping between the opened file and
-the Perl subroutine we want to be called for that file.
-</p>
-<p>Say the i/o library has a function <code>asynch_read</code> which
associates a C
-function <code>ProcessRead</code> with a file handle
<code>fh</code>–this assumes that it
-has also provided some routine to open the file and so obtain the file
-handle.
-</p>
-<pre class="verbatim"> asynch_read(fh, ProcessRead)
-</pre>
-<p>This may expect the C <em>ProcessRead</em> function of this form
-</p>
-<pre class="verbatim"> void
- ProcessRead(fh, buffer)
- int fh;
- char * buffer;
- {
- ...
- }
-</pre>
-<p>To provide a Perl interface to this library we need to be able to map
-between the <code>fh</code> parameter and the Perl subroutine we want called.
A
-hash is a convenient mechanism for storing this mapping. The code
-below shows a possible implementation
-</p>
-<pre class="verbatim"> static HV * Mapping = (HV*)NULL;
-
- void
- asynch_read(fh, callback)
- int fh
- SV * callback
- CODE:
- /* If the hash doesn't already exist, create it */
- if (Mapping == (HV*)NULL)
- Mapping = newHV();
-
- /* Save the fh -> callback mapping */
- hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0);
-
- /* Register with the C Library */
- asynch_read(fh, asynch_read_if);
-</pre>
-<p>and <code>asynch_read_if</code> could look like this
-</p>
-<pre class="verbatim"> static void
- asynch_read_if(fh, buffer)
- int fh;
- char * buffer;
- {
- dSP;
- SV ** sv;
-
- /* Get the callback associated with fh */
- sv = hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE);
- if (sv == (SV**)NULL)
- croak("Internal error...\n");
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSViv(fh)));
- XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
- PUTBACK;
-
- /* Call the Perl sub */
- call_sv(*sv, G_DISCARD);
- }
-</pre>
-<p>For completeness, here is <code>asynch_close</code>. This shows how to
remove
-the entry from the hash <code>Mapping</code>.
-</p>
-<pre class="verbatim"> void
- asynch_close(fh)
- int fh
- CODE:
- /* Remove the entry from the hash */
- (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD);
-
- /* Now call the real asynch_close */
- asynch_close(fh);
-</pre>
-<p>So the Perl interface would look like this
-</p>
-<pre class="verbatim"> sub callback1
- {
- my($handle, $buffer) = @_;
- }
-
- # Register the Perl callback
- asynch_read($fh, \&callback1);
-
- asynch_close($fh);
-</pre>
-<p>The mapping between the C callback and Perl is stored in the global
-hash <code>Mapping</code> this time. Using a hash has the distinct advantage
that
-it allows an unlimited number of callbacks to be registered.
-</p>
-<p>What if the interface provided by the C callback doesn’t contain a
-parameter which allows the file handle to Perl subroutine mapping? Say
-in the asynchronous i/o package, the callback function gets passed only
-the <code>buffer</code> parameter like this
-</p>
-<pre class="verbatim"> void
- ProcessRead(buffer)
- char * buffer;
- {
- ...
- }
-</pre>
-<p>Without the file handle there is no straightforward way to map from the
-C callback to the Perl subroutine.
-</p>
-<p>In this case a possible way around this problem is to predefine a
-series of C functions to act as the interface to Perl, thus
-</p>
-<pre class="verbatim"> #define MAX_CB 3
- #define NULL_HANDLE -1
- typedef void (*FnMap)();
-
- struct MapStruct {
- FnMap Function;
- SV * PerlSub;
- int Handle;
- };
-
- static void fn1();
- static void fn2();
- static void fn3();
-
- static struct MapStruct Map [MAX_CB] =
- {
- { fn1, NULL, NULL_HANDLE },
- { fn2, NULL, NULL_HANDLE },
- { fn3, NULL, NULL_HANDLE }
- };
-
- static void
- Pcb(index, buffer)
- int index;
- char * buffer;
- {
- dSP;
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
- PUTBACK;
-
- /* Call the Perl sub */
- call_sv(Map[index].PerlSub, G_DISCARD);
- }
-
- static void
- fn1(buffer)
- char * buffer;
- {
- Pcb(0, buffer);
- }
-
- static void
- fn2(buffer)
- char * buffer;
- {
- Pcb(1, buffer);
- }
-
- static void
- fn3(buffer)
- char * buffer;
- {
- Pcb(2, buffer);
- }
-
- void
- array_asynch_read(fh, callback)
- int fh
- SV * callback
- CODE:
- int index;
- int null_index = MAX_CB;
-
- /* Find the same handle or an empty entry */
- for (index = 0; index < MAX_CB; ++index)
- {
- if (Map[index].Handle == fh)
- break;
-
- if (Map[index].Handle == NULL_HANDLE)
- null_index = index;
- }
-
- if (index == MAX_CB && null_index == MAX_CB)
- croak ("Too many callback functions registered\n");
-
- if (index == MAX_CB)
- index = null_index;
-
- /* Save the file handle */
- Map[index].Handle = fh;
-
- /* Remember the Perl sub */
- if (Map[index].PerlSub == (SV*)NULL)
- Map[index].PerlSub = newSVsv(callback);
- else
- SvSetSV(Map[index].PerlSub, callback);
-
- asynch_read(fh, Map[index].Function);
-
- void
- array_asynch_close(fh)
- int fh
- CODE:
- int index;
-
- /* Find the file handle */
- for (index = 0; index < MAX_CB; ++ index)
- if (Map[index].Handle == fh)
- break;
-
- if (index == MAX_CB)
- croak ("could not close fh %d\n", fh);
-
- Map[index].Handle = NULL_HANDLE;
- SvREFCNT_dec(Map[index].PerlSub);
- Map[index].PerlSub = (SV*)NULL;
-
- asynch_close(fh);
-</pre>
-<p>In this case the functions <code>fn1</code>, <code>fn2</code>, and
<code>fn3</code> are used to
-remember the Perl subroutine to be called. Each of the functions holds
-a separate hard-wired index which is used in the function <code>Pcb</code> to
-access the <code>Map</code> array and actually call the Perl subroutine.
-</p>
-<p>There are some obvious disadvantages with this technique.
-</p>
-<p>Firstly, the code is considerably more complex than with the previous
-example.
-</p>
-<p>Secondly, there is a hard-wired limit (in this case 3) to the number of
-callbacks that can exist simultaneously. The only way to increase the
-limit is by modifying the code to add more functions and then
-recompiling. None the less, as long as the number of functions is
-chosen with some care, it is still a workable solution and in some
-cases is the only one available.
-</p>
-<p>To summarize, here are a number of possible methods for you to consider
-for storing the mapping between C and the Perl callback
-</p>
-<dl compact="compact">
-<dt>1. Ignore the problem - Allow only 1 callback</dt>
-<dd><a
name="perlcall-1_002e-Ignore-the-problem-_002d-Allow-only-1-callback"></a>
-<p>For a lot of situations, like interfacing to an error handler, this may
-be a perfectly adequate solution.
-</p>
-</dd>
-<dt>2. Create a sequence of callbacks - hard wired limit</dt>
-<dd><a
name="perlcall-2_002e-Create-a-sequence-of-callbacks-_002d-hard-wired-limit"></a>
-<p>If it is impossible to tell from the parameters passed back from the C
-callback what the context is, then you may need to create a sequence of C
-callback interface functions, and store pointers to each in an array.
-</p>
-</dd>
-<dt>3. Use a parameter to map to the Perl callback</dt>
-<dd><a name="perlcall-3_002e-Use-a-parameter-to-map-to-the-Perl-callback"></a>
-<p>A hash is an ideal mechanism to store the mapping between C and Perl.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlcall-Alternate-Stack-Manipulation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-Creating-and-Calling-an-Anonymous-Subroutine-in-C"
accesskey="n" rel="next">perlcall Creating and Calling an Anonymous Subroutine
in C</a>, Previous: <a
href="#perlcall-Strategies-for-Storing-Callback-Context-Information"
accesskey="p" rel="prev">perlcall Strategies for Storing Callback Context
Information</a>, Up: <a href="#perlcall-EXAMPLES" accesskey="u"
rel="up">perlcall EXAMPLES</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Alternate-Stack-Manipulation"></a>
-<h4 class="subsection">7.5.15 Alternate Stack Manipulation</h4>
-
-<p>Although I have made use of only the <code>POP*</code> macros to access
values
-returned from Perl subroutines, it is also possible to bypass these
-macros and read the stack using the <code>ST</code> macro (See <a
href="perlxs.html#Top">(perlxs)</a> for a
-full description of the <code>ST</code> macro).
-</p>
-<p>Most of the time the <code>POP*</code> 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 <code>ST</code> macro as used when coding an XSUB is ideal
-for this purpose.
-</p>
-<p>The code below is the example given in the section <em>Returning a List
-of Values</em> recoded to use <code>ST</code> instead of <code>POP*</code>.
-</p>
-<pre class="verbatim"> static void
- call_AddSubtract2(a, b)
- int a;
- int b;
- {
- dSP;
- I32 ax;
- int count;
-
- ENTER;
- SAVETMPS;
-
- PUSHMARK(SP);
- XPUSHs(sv_2mortal(newSViv(a)));
- XPUSHs(sv_2mortal(newSViv(b)));
- PUTBACK;
-
- count = call_pv("AddSubtract", G_ARRAY);
-
- SPAGAIN;
- SP -= count;
- ax = (SP - PL_stack_base) + 1;
-
- if (count != 2)
- croak("Big trouble\n");
-
- printf ("%d + %d = %d\n", a, b, SvIV(ST(0)));
- printf ("%d - %d = %d\n", a, b, SvIV(ST(1)));
-
- PUTBACK;
- FREETMPS;
- LEAVE;
- }
-</pre>
-<p>Notes
-</p>
-<ol>
-<li> Notice that it was necessary to define the variable <code>ax</code>.
This is
-because the <code>ST</code> macro expects it to exist. If we were in an XSUB
it
-would not be necessary to define <code>ax</code> as it is already defined for
-us.
-
-</li><li> The code
-
-<pre class="verbatim"> SPAGAIN;
- SP -= count;
- ax = (SP - PL_stack_base) + 1;
-</pre>
-<p>sets the stack up so that we can use the <code>ST</code> macro.
-</p>
-</li><li> Unlike the original coding of this example, the returned
-values are not accessed in reverse order. So <code>ST(0)</code> refers to the
-first value returned by the Perl subroutine and <code>ST(count-1)</code>
-refers to the last.
-
-</li></ol>
-
-<hr>
-<a name="perlcall-Creating-and-Calling-an-Anonymous-Subroutine-in-C"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlcall-Alternate-Stack-Manipulation" accesskey="p"
rel="prev">perlcall Alternate Stack Manipulation</a>, Up: <a
href="#perlcall-EXAMPLES" accesskey="u" rel="up">perlcall EXAMPLES</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Creating-and-Calling-an-Anonymous-Subroutine-in-C"></a>
-<h4 class="subsection">7.5.16 Creating and Calling an Anonymous Subroutine in
C</h4>
-
-<p>As we’ve already shown, <code>call_sv</code> can be used to invoke an
-anonymous subroutine. However, our example showed a Perl script
-invoking an XSUB to perform this operation. Let’s see how it can be
-done inside our C code:
-</p>
-<pre class="verbatim"> ...
-
- SV *cvrv = eval_pv("sub { print 'You will not find me cluttering any
namespace!' }", TRUE);
-
- ...
-
- call_sv(cvrv, G_VOID|G_NOARGS);
-</pre>
-<p><code>eval_pv</code> is used to compile the anonymous subroutine, which
-will be the return value as well (read more about <code>eval_pv</code> in
-<a href="perlapi.html#eval_005fpv">(perlapi)eval_pv</a>). Once this code
reference is in hand, it
-can be mixed in with all the previous examples we’ve shown.
-</p>
-<hr>
-<a name="perlcall-LIGHTWEIGHT-CALLBACKS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-SEE-ALSO" accesskey="n" rel="next">perlcall SEE
ALSO</a>, Previous: <a href="#perlcall-EXAMPLES" accesskey="p"
rel="prev">perlcall EXAMPLES</a>, Up: <a href="#perlcall" accesskey="u"
rel="up">perlcall</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="LIGHTWEIGHT-CALLBACKS"></a>
-<h3 class="section">7.6 LIGHTWEIGHT CALLBACKS</h3>
-
-<p>Sometimes you need to invoke the same subroutine repeatedly.
-This usually happens with a function that acts on a list of
-values, such as Perl’s built-in sort(). You can pass a
-comparison function to sort(), which will then be invoked
-for every pair of values that needs to be compared. The first()
-and reduce() functions from <a href="List-Util.html#Top">(List-Util)</a>
follow a similar
-pattern.
-</p>
-<p>In this case it is possible to speed up the routine (often
-quite substantially) by using the lightweight callback API.
-The idea is that the calling context only needs to be
-created and destroyed once, and the sub can be called
-arbitrarily many times in between.
-</p>
-<p>It is usual to pass parameters using global variables (typically
-$_ for one parameter, or $a and $b for two parameters) rather
-than via @_. (It is possible to use the @_ mechanism if you know
-what you’re doing, though there is as yet no supported API for
-it. It’s also inherently slower.)
-</p>
-<p>The pattern of macro calls is like this:
-</p>
-<pre class="verbatim"> dMULTICALL; /* Declare local
variables */
- I32 gimme = G_SCALAR; /* context of the call: G_SCALAR,
- * G_ARRAY, or G_VOID */
-
- PUSH_MULTICALL(cv); /* Set up the context for calling cv,
- and set local vars appropriately */
-
- /* loop */ {
- /* set the value(s) af your parameter variables */
- MULTICALL; /* Make the actual call */
- } /* end of loop */
-
- POP_MULTICALL; /* Tear down the calling context */
-</pre>
-<p>For some concrete examples, see the implementation of the
-first() and reduce() functions of List::Util 1.18. There you
-will also find a header file that emulates the multicall API
-on older versions of perl.
-</p>
-<hr>
-<a name="perlcall-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-AUTHOR" accesskey="n" rel="next">perlcall AUTHOR</a>,
Previous: <a href="#perlcall-LIGHTWEIGHT-CALLBACKS" accesskey="p"
rel="prev">perlcall LIGHTWEIGHT CALLBACKS</a>, Up: <a href="#perlcall"
accesskey="u" rel="up">perlcall</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-1"></a>
-<h3 class="section">7.7 SEE ALSO</h3>
-
-<p><a href="perlxs.html#Top">(perlxs)</a>, <a href="#perlguts-NAME">perlguts
NAME</a>, <a href="#perlembed-NAME">perlembed NAME</a>
-</p>
-<hr>
-<a name="perlcall-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcall-DATE" accesskey="n" rel="next">perlcall DATE</a>,
Previous: <a href="#perlcall-SEE-ALSO" accesskey="p" rel="prev">perlcall SEE
ALSO</a>, Up: <a href="#perlcall" accesskey="u" rel="up">perlcall</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-1"></a>
-<h3 class="section">7.8 AUTHOR</h3>
-
-<p>Paul Marquess
-</p>
-<p>Special thanks to the following people who assisted in the creation of
-the document.
-</p>
-<p>Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem, Gurusamy Sarathy
-and Larry Wall.
-</p>
-<hr>
-<a name="perlcall-DATE"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlcall-AUTHOR" accesskey="p" rel="prev">perlcall
AUTHOR</a>, Up: <a href="#perlcall" accesskey="u" rel="up">perlcall</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DATE"></a>
-<h3 class="section">7.9 DATE</h3>
-
-<p>Version 1.3, 14th Apr 1997
-</p>
-<hr>
-<a name="perlcheat"></a>
-<div class="header">
-<p>
-Next: <a href="#perlclib" accesskey="n" rel="next">perlclib</a>, Previous: <a
href="#perlcall" accesskey="p" rel="prev">perlcall</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlcheat-1"></a>
-<h2 class="chapter">8 perlcheat</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlcheat-NAME"
accesskey="1">perlcheat NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcheat-DESCRIPTION"
accesskey="2">perlcheat DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcheat-ACKNOWLEDGEMENTS"
accesskey="3">perlcheat ACKNOWLEDGEMENTS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcheat-AUTHOR"
accesskey="4">perlcheat AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcheat-SEE-ALSO"
accesskey="5">perlcheat SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlcheat-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcheat-DESCRIPTION" accesskey="n" rel="next">perlcheat
DESCRIPTION</a>, Up: <a href="#perlcheat" accesskey="u" rel="up">perlcheat</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-7"></a>
-<h3 class="section">8.1 NAME</h3>
-
-<p>perlcheat - Perl 5 Cheat Sheet
-</p>
-<hr>
-<a name="perlcheat-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcheat-ACKNOWLEDGEMENTS" accesskey="n" rel="next">perlcheat
ACKNOWLEDGEMENTS</a>, Previous: <a href="#perlcheat-NAME" accesskey="p"
rel="prev">perlcheat NAME</a>, Up: <a href="#perlcheat" accesskey="u"
rel="up">perlcheat</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-7"></a>
-<h3 class="section">8.2 DESCRIPTION</h3>
-
-<p>This ’cheat sheet’ is a handy reference, meant for beginning
Perl
-programmers. Not everything is mentioned, but 195 features may
-already be overwhelming.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlcheat-The-sheet"
accesskey="1">perlcheat The sheet</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlcheat-The-sheet"></a>
-<div class="header">
-<p>
-Up: <a href="#perlcheat-DESCRIPTION" accesskey="u" rel="up">perlcheat
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-sheet"></a>
-<h4 class="subsection">8.2.1 The sheet</h4>
-
-<pre class="verbatim"> CONTEXTS SIGILS ref ARRAYS HASHES
- void $scalar SCALAR @array %hash
- scalar @array ARRAY @array[0, 2] @hash{'a', 'b'}
- list %hash HASH $array[0] $hash{'a'}
- &sub CODE
- *glob GLOB SCALAR VALUES
- FORMAT number, string, ref, glob, undef
- REFERENCES
- \ reference $$foo[1] aka $foo->[1]
- address@hidden&* dereference $$foo{bar} aka $foo->{bar}
- [] anon. arrayref ${$$foo[1]}[2] aka $foo->[1]->[2]
- {} anon. hashref ${$$foo[1]}[2] aka $foo->[1][2]
- \() list of refs
- SYNTAX
- OPERATOR PRECEDENCE foreach (LIST) { } for (a;b;c) { }
- -> while (e) { } until (e) { }
- ++ -- if (e) { } elsif (e) { } else { }
- ** unless (e) { } elsif (e) { } else { }
- ! ~ \ u+ u- given (e) { when (e) {} default {} }
- =~ !~
- * / % x NUMBERS vs STRINGS FALSE vs TRUE
- + - . = = undef, "", 0,
"0"
- << >> + . anything else
- named uops == != eq ne
- < > <= >= lt gt le ge < > <= >= lt gt le ge
- == != <=> eq ne cmp ~~ <=> cmp
- &
- | ^ REGEX MODIFIERS REGEX METACHARS
- && /i case insensitive ^ string begin
- || // /m line based ^$ $ str end (bfr \n)
- .. ... /s . includes \n + one or more
- ?: /x ignore wh.space * zero or more
- = += last goto /p preserve ? zero or one
- , => /a ASCII /aa safe {3,7} repeat in range
- list ops /l locale /d dual | alternation
- not /u Unicode [] character class
- and /e evaluate /ee rpts \b boundary
- or xor /g global \z string end
- /o compile pat once () capture
- DEBUG (?:p) no capture
- -MO=Deparse REGEX CHARCLASSES (?#t) comment
- -MO=Terse . [^\n] (?=p) ZW pos ahead
- -D## \s whitespace (?!p) ZW neg ahead
- -d:Trace \w word chars (?<=p) ZW pos behind \K
- \d digits (?<!p) ZW neg behind
- CONFIGURATION \pP named property (?>p) no backtrack
- perl -V:ivsize \h horiz.wh.space (?|p|p)branch reset
- \R linebreak (?<n>p)named capture
- \S \W \D \H negate \g{n} ref to named cap
- \K keep left part
- FUNCTION RETURN LISTS
- stat localtime caller SPECIAL VARIABLES
- 0 dev 0 second 0 package $_ default variable
- 1 ino 1 minute 1 filename $0 program name
- 2 mode 2 hour 2 line $/ input separator
- 3 nlink 3 day 3 subroutine $\ output separator
- 4 uid 4 month-1 4 hasargs $| autoflush
- 5 gid 5 year-1900 5 wantarray $! sys/libcall error
- 6 rdev 6 weekday 6 evaltext $@ eval error
- 7 size 7 yearday 7 is_require $$ process ID
- 8 atime 8 is_dst 8 hints $. line number
- 9 mtime 9 bitmask @ARGV command line args
- 10 ctime 10 hinthash @INC include paths
- 11 blksz 3..10 only @_ subroutine args
- 12 blcks with EXPR %ENV environment
-</pre>
-<hr>
-<a name="perlcheat-ACKNOWLEDGEMENTS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcheat-AUTHOR" accesskey="n" rel="next">perlcheat
AUTHOR</a>, Previous: <a href="#perlcheat-DESCRIPTION" accesskey="p"
rel="prev">perlcheat DESCRIPTION</a>, Up: <a href="#perlcheat" accesskey="u"
rel="up">perlcheat</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="ACKNOWLEDGEMENTS"></a>
-<h3 class="section">8.3 ACKNOWLEDGEMENTS</h3>
-
-<p>The first version of this document appeared on Perl Monks, where several
-people had useful suggestions. Thank you, Perl Monks.
-</p>
-<p>A special thanks to Damian Conway, who didn’t only suggest important
changes,
-but also took the time to count the number of listed features and make a
-Perl 6 version to show that Perl will stay Perl.
-</p>
-<hr>
-<a name="perlcheat-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcheat-SEE-ALSO" accesskey="n" rel="next">perlcheat SEE
ALSO</a>, Previous: <a href="#perlcheat-ACKNOWLEDGEMENTS" accesskey="p"
rel="prev">perlcheat ACKNOWLEDGEMENTS</a>, Up: <a href="#perlcheat"
accesskey="u" rel="up">perlcheat</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-2"></a>
-<h3 class="section">8.4 AUTHOR</h3>
-
-<p>Juerd Waalboer <address@hidden>, with the help of many Perl Monks.
-</p>
-<hr>
-<a name="perlcheat-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlcheat-AUTHOR" accesskey="p" rel="prev">perlcheat
AUTHOR</a>, Up: <a href="#perlcheat" accesskey="u" rel="up">perlcheat</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-2"></a>
-<h3 class="section">8.5 SEE ALSO</h3>
-
-<ul>
-<li> <a
href="http://perlmonks.org/?node_id=216602";>http://perlmonks.org/?node_id=216602</a>
- the original PM post
-
-</li><li> <a
href="http://perlmonks.org/?node_id=238031";>http://perlmonks.org/?node_id=238031</a>
- Damian Conway’s Perl 6 version
-
-</li><li> <a
href="http://juerd.nl/site.plp/perlcheat";>http://juerd.nl/site.plp/perlcheat</a>
- home of the Perl Cheat Sheet
-
-</li></ul>
-
-<hr>
-<a name="perlclib"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcommunity" accesskey="n" rel="next">perlcommunity</a>,
Previous: <a href="#perlcheat" accesskey="p" rel="prev">perlcheat</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlclib-1"></a>
-<h2 class="chapter">9 perlclib</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlclib-NAME"
accesskey="1">perlclib NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlclib-DESCRIPTION"
accesskey="2">perlclib DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlclib-SEE-ALSO"
accesskey="3">perlclib SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlclib-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlclib-DESCRIPTION" accesskey="n" rel="next">perlclib
DESCRIPTION</a>, Up: <a href="#perlclib" accesskey="u" rel="up">perlclib</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-8"></a>
-<h3 class="section">9.1 NAME</h3>
-
-<p>perlclib - Internal replacements for standard C library functions
-</p>
-<hr>
-<a name="perlclib-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlclib-SEE-ALSO" accesskey="n" rel="next">perlclib SEE
ALSO</a>, Previous: <a href="#perlclib-NAME" accesskey="p" rel="prev">perlclib
NAME</a>, Up: <a href="#perlclib" accesskey="u" rel="up">perlclib</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-8"></a>
-<h3 class="section">9.2 DESCRIPTION</h3>
-
-<p>One thing Perl porters should note is that <samp>perl</samp> doesn’t
tend to use that
-much of the C standard library internally; you’ll see very little use
of,
-for example, the <samp>ctype.h</samp> functions in there. This is because Perl
-tends to reimplement or abstract standard library functions, so that we
-know exactly how they’re going to operate.
-</p>
-<p>This is a reference card for people who are familiar with the C library
-and who want to do things the Perl way; to tell them which functions
-they ought to use instead of the more normal C functions.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlclib-Conventions"
accesskey="1">perlclib Conventions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlclib-File-Operations"
accesskey="2">perlclib File Operations</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlclib-File-Input-and-Output" accesskey="3">perlclib File Input and
Output</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlclib-File-Positioning"
accesskey="4">perlclib File Positioning</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlclib-Memory-Management-and-String-Handling" accesskey="5">perlclib
Memory Management and String Handling</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlclib-Character-Class-Tests" accesskey="6">perlclib Character Class
Tests</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlclib-stdlib_002eh-functions" accesskey="7">perlclib
<samp>stdlib.h</samp> functions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlclib-Miscellaneous-functions" accesskey="8">perlclib Miscellaneous
functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlclib-Conventions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlclib-File-Operations" accesskey="n" rel="next">perlclib
File Operations</a>, Up: <a href="#perlclib-DESCRIPTION" accesskey="u"
rel="up">perlclib DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Conventions"></a>
-<h4 class="subsection">9.2.1 Conventions</h4>
-
-<p>In the following tables:
-</p>
-<dl compact="compact">
-<dt><code>t</code></dt>
-<dd><a name="perlclib-t"></a>
-<p>is a type.
-</p>
-</dd>
-<dt><code>p</code></dt>
-<dd><a name="perlclib-p"></a>
-<p>is a pointer.
-</p>
-</dd>
-<dt><code>n</code></dt>
-<dd><a name="perlclib-n"></a>
-<p>is a number.
-</p>
-</dd>
-<dt><code>s</code></dt>
-<dd><a name="perlclib-s"></a>
-<p>is a string.
-</p>
-</dd>
-</dl>
-
-<p><code>sv</code>, <code>av</code>, <code>hv</code>, etc. represent variables
of their respective types.
-</p>
-<hr>
-<a name="perlclib-File-Operations"></a>
-<div class="header">
-<p>
-Next: <a href="#perlclib-File-Input-and-Output" accesskey="n"
rel="next">perlclib File Input and Output</a>, Previous: <a
href="#perlclib-Conventions" accesskey="p" rel="prev">perlclib Conventions</a>,
Up: <a href="#perlclib-DESCRIPTION" accesskey="u" rel="up">perlclib
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="File-Operations"></a>
-<h4 class="subsection">9.2.2 File Operations</h4>
-
-<p>Instead of the <samp>stdio.h</samp> functions, you should use the Perl
abstraction
-layer. Instead of <code>FILE*</code> types, you need to be handling
<code>PerlIO*</code>
-types. Don’t forget that with the new PerlIO layered I/O abstraction
-<code>FILE*</code> types may not even be available. See also the
<code>perlapio</code>
-documentation for more information about the following functions:
-</p>
-<pre class="verbatim"> Instead Of: Use:
-
- stdin PerlIO_stdin()
- stdout PerlIO_stdout()
- stderr PerlIO_stderr()
-
- fopen(fn, mode) PerlIO_open(fn, mode)
- freopen(fn, mode, stream) PerlIO_reopen(fn, mode, perlio) (Dep-
- recated)
- fflush(stream) PerlIO_flush(perlio)
- fclose(stream) PerlIO_close(perlio)
-</pre>
-<hr>
-<a name="perlclib-File-Input-and-Output"></a>
-<div class="header">
-<p>
-Next: <a href="#perlclib-File-Positioning" accesskey="n" rel="next">perlclib
File Positioning</a>, Previous: <a href="#perlclib-File-Operations"
accesskey="p" rel="prev">perlclib File Operations</a>, Up: <a
href="#perlclib-DESCRIPTION" accesskey="u" rel="up">perlclib DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="File-Input-and-Output"></a>
-<h4 class="subsection">9.2.3 File Input and Output</h4>
-
-<pre class="verbatim"> Instead Of: Use:
-
- fprintf(stream, fmt, ...) PerlIO_printf(perlio, fmt, ...)
-
- [f]getc(stream) PerlIO_getc(perlio)
- [f]putc(stream, n) PerlIO_putc(perlio, n)
- ungetc(n, stream) PerlIO_ungetc(perlio, n)
-</pre>
-<p>Note that the PerlIO equivalents of <code>fread</code> and
<code>fwrite</code> are slightly
-different from their C library counterparts:
-</p>
-<pre class="verbatim"> fread(p, size, n, stream) PerlIO_read(perlio, buf,
numbytes)
- fwrite(p, size, n, stream) PerlIO_write(perlio, buf, numbytes)
-
- fputs(s, stream) PerlIO_puts(perlio, s)
-</pre>
-<p>There is no equivalent to <code>fgets</code>; one should use
<code>sv_gets</code> instead:
-</p>
-<pre class="verbatim"> fgets(s, n, stream) sv_gets(sv, perlio, append)
-</pre>
-<hr>
-<a name="perlclib-File-Positioning"></a>
-<div class="header">
-<p>
-Next: <a href="#perlclib-Memory-Management-and-String-Handling" accesskey="n"
rel="next">perlclib Memory Management and String Handling</a>, Previous: <a
href="#perlclib-File-Input-and-Output" accesskey="p" rel="prev">perlclib File
Input and Output</a>, Up: <a href="#perlclib-DESCRIPTION" accesskey="u"
rel="up">perlclib DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="File-Positioning"></a>
-<h4 class="subsection">9.2.4 File Positioning</h4>
-
-<pre class="verbatim"> Instead Of: Use:
-
- feof(stream) PerlIO_eof(perlio)
- fseek(stream, n, whence) PerlIO_seek(perlio, n, whence)
- rewind(stream) PerlIO_rewind(perlio)
-
- fgetpos(stream, p) PerlIO_getpos(perlio, sv)
- fsetpos(stream, p) PerlIO_setpos(perlio, sv)
-
- ferror(stream) PerlIO_error(perlio)
- clearerr(stream) PerlIO_clearerr(perlio)
-</pre>
-<hr>
-<a name="perlclib-Memory-Management-and-String-Handling"></a>
-<div class="header">
-<p>
-Next: <a href="#perlclib-Character-Class-Tests" accesskey="n"
rel="next">perlclib Character Class Tests</a>, Previous: <a
href="#perlclib-File-Positioning" accesskey="p" rel="prev">perlclib File
Positioning</a>, Up: <a href="#perlclib-DESCRIPTION" accesskey="u"
rel="up">perlclib DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Memory-Management-and-String-Handling"></a>
-<h4 class="subsection">9.2.5 Memory Management and String Handling</h4>
-
-<pre class="verbatim"> Instead Of: Use:
-
- t* p = malloc(n) Newx(p, n, t)
- t* p = calloc(n, s) Newxz(p, n, t)
- p = realloc(p, n) Renew(p, n, t)
- memcpy(dst, src, n) Copy(src, dst, n, t)
- memmove(dst, src, n) Move(src, dst, n, t)
- memcpy(dst, src, sizeof(t)) StructCopy(src, dst, t)
- memset(dst, 0, n * sizeof(t)) Zero(dst, n, t)
- memzero(dst, 0) Zero(dst, n, char)
- free(p) Safefree(p)
-
- strdup(p) savepv(p)
- strndup(p, n) savepvn(p, n) (Hey, strndup doesn't
- exist!)
-
- strstr(big, little) instr(big, little)
- strcmp(s1, s2) strLE(s1, s2) / strEQ(s1, s2)
- / strGT(s1,s2)
- strncmp(s1, s2, n) strnNE(s1, s2, n) / strnEQ(s1, s2, n)
-
- memcmp(p1, p2, n) memNE(p1, p2, n)
- !memcmp(p1, p2, n) memEQ(p1, p2, n)
-</pre>
-<p>Notice the different order of arguments to <code>Copy</code> and
<code>Move</code> than used
-in <code>memcpy</code> and <code>memmove</code>.
-</p>
-<p>Most of the time, though, you’ll want to be dealing with SVs
internally
-instead of raw <code>char *</code> strings:
-</p>
-<pre class="verbatim"> strlen(s) sv_len(sv)
- strcpy(dt, src) sv_setpv(sv, s)
- strncpy(dt, src, n) sv_setpvn(sv, s, n)
- strcat(dt, src) sv_catpv(sv, s)
- strncat(dt, src) sv_catpvn(sv, s)
- sprintf(s, fmt, ...) sv_setpvf(sv, fmt, ...)
-</pre>
-<p>Note also the existence of <code>sv_catpvf</code> and
<code>sv_vcatpvfn</code>, combining
-concatenation with formatting.
-</p>
-<p>Sometimes instead of zeroing the allocated heap by using Newxz() you
-should consider "poisoning" the data. This means writing a bit
-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 to Zero():
-</p>
-<pre class="verbatim"> PoisonWith(dst, n, t, b) scribble memory with byte b
- PoisonNew(dst, n, t) equal to PoisonWith(dst, n, t, 0xAB)
- PoisonFree(dst, n, t) equal to PoisonWith(dst, n, t, 0xEF)
- Poison(dst, n, t) equal to PoisonFree(dst, n, t)
-</pre>
-<hr>
-<a name="perlclib-Character-Class-Tests"></a>
-<div class="header">
-<p>
-Next: <a href="#perlclib-stdlib_002eh-functions" accesskey="n"
rel="next">perlclib <samp>stdlib.h</samp> functions</a>, Previous: <a
href="#perlclib-Memory-Management-and-String-Handling" accesskey="p"
rel="prev">perlclib Memory Management and String Handling</a>, Up: <a
href="#perlclib-DESCRIPTION" accesskey="u" rel="up">perlclib DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Character-Class-Tests"></a>
-<h4 class="subsection">9.2.6 Character Class Tests</h4>
-
-<p>There are several types of character class tests that Perl implements.
-The only ones described here are those that directly correspond to C
-library functions that operate on 8-bit characters, but there are
-equivalents that operate on wide characters, and UTF-8 encoded strings.
-All are more fully described in <a
href="perlapi.html#Character-classification">(perlapi)Character
classification</a> and
-<a href="perlapi.html#Character-case-changing">(perlapi)Character case
changing</a>.
-</p>
-<p>The C library routines listed in the table below return values based on
-the current locale. Use the entries in the final column for that
-functionality. The other two columns always assume a POSIX (or C)
-locale. The entries in the ASCII column are only meaningful for ASCII
-inputs, returning FALSE for anything else. Use these only when you
-<strong>know</strong> that is what you want. The entries in the Latin1 column
assume
-that the non-ASCII 8-bit characters are as Unicode defines, them, the
-same as ISO-8859-1, often called Latin 1.
-</p>
-<pre class="verbatim"> Instead Of: Use for ASCII: Use for Latin1: Use
for locale:
-
- isalnum(c) isALPHANUMERIC(c) isALPHANUMERIC_L1(c) isALPHANUMERIC_LC(c)
- isalpha(c) isALPHA(c) isALPHA_L1(c) isALPHA_LC(u )
- isascii(c) isASCII(c) isASCII_LC(c)
- isblank(c) isBLANK(c) isBLANK_L1(c) isBLANK_LC(c)
- iscntrl(c) isCNTRL(c) isCNTRL_L1(c) isCNTRL_LC(c)
- isdigit(c) isDIGIT(c) isDIGIT_L1(c) isDIGIT_LC(c)
- isgraph(c) isGRAPH(c) isGRAPH_L1(c) isGRAPH_LC(c)
- islower(c) isLOWER(c) isLOWER_L1(c) isLOWER_LC(c)
- isprint(c) isPRINT(c) isPRINT_L1(c) isPRINT_LC(c)
- ispunct(c) isPUNCT(c) isPUNCT_L1(c) isPUNCT_LC(c)
- isspace(c) isSPACE(c) isSPACE_L1(c) isSPACE_LC(c)
- isupper(c) isUPPER(c) isUPPER_L1(c) isUPPER_LC(c)
- isxdigit(c) isXDIGIT(c) isXDIGIT_L1(c) isXDIGIT_LC(c)
-
- tolower(c) toLOWER(c) toLOWER_L1(c) toLOWER_LC(c)
- toupper(c) toUPPER(c) toUPPER_LC(c)
-</pre>
-<p>To emphasize that you are operating only on ASCII characters, you can
-append <code>_A</code> to each of the macros in the ASCII column:
<code>isALPHA_A</code>,
-<code>isDIGIT_A</code>, and so on.
-</p>
-<p>(There is no entry in the Latin1 column for <code>isascii</code> even
though there
-is an <code>isASCII_L1</code>, which is identical to <code>isASCII</code>; the
-latter name is clearer. There is no entry in the Latin1 column for
-<code>toupper</code> because the result can be non-Latin1. You have to use
-<code>toUPPER_uni</code>, as described in <a
href="perlapi.html#Character-case-changing">(perlapi)Character case
changing</a>.)
-</p>
-<hr>
-<a name="perlclib-stdlib_002eh-functions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlclib-Miscellaneous-functions" accesskey="n"
rel="next">perlclib Miscellaneous functions</a>, Previous: <a
href="#perlclib-Character-Class-Tests" accesskey="p" rel="prev">perlclib
Character Class Tests</a>, Up: <a href="#perlclib-DESCRIPTION" accesskey="u"
rel="up">perlclib DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="stdlib_002eh-functions"></a>
-<h4 class="subsection">9.2.7 <samp>stdlib.h</samp> functions</h4>
-
-<pre class="verbatim"> Instead Of: Use:
-
- atof(s) Atof(s)
- atoi(s) grok_atoUV(s, &uv, &e)
- atol(s) grok_atoUV(s, &uv, &e)
- strtod(s, &p) Nothing. Just don't use it.
- strtol(s, &p, n) grok_atoUV(s, &uv, &e)
- strtoul(s, &p, n) grok_atoUV(s, &uv, &e)
-</pre>
-<p>Typical use is to do range checks on <code>uv</code> before casting:
-</p>
-<pre class="verbatim"> int i; UV uv; char* end_ptr;
- if (grok_atoUV(input, &uv, &end_ptr)
- && uv <= INT_MAX)
- i = (int)uv;
- ... /* continue parsing from end_ptr */
- } else {
- ... /* parse error: not a decimal integer in range 0 .. MAX_IV */
- }
-</pre>
-<p>Notice also the <code>grok_bin</code>, <code>grok_hex</code>, and
<code>grok_oct</code> functions in
-<samp>numeric.c</samp> for converting strings representing numbers in the
respective
-bases into <code>NV</code>s. Note that grok_atoUV() doesn’t handle
negative inputs,
-or leading whitespace (being purposefully strict).
-</p>
-<p>Note that strtol() and strtoul() may be disguised as Strtol(), Strtoul(),
-Atol(), Atoul(). Avoid those, too.
-</p>
-<p>In theory <code>Strtol</code> and <code>Strtoul</code> may not be defined
if the machine perl is
-built on doesn’t actually have strtol and strtoul. But as those 2
-functions are part of the 1989 ANSI C spec we suspect you’ll find them
-everywhere by now.
-</p>
-<pre class="verbatim"> int rand() double Drand01()
- srand(n) { seedDrand01((Rand_seed_t)n);
- PL_srand_called = TRUE; }
-
- exit(n) my_exit(n)
- system(s) Don't. Look at pp_system or use my_popen.
-
- getenv(s) PerlEnv_getenv(s)
- setenv(s, val) my_setenv(s, val)
-</pre>
-<hr>
-<a name="perlclib-Miscellaneous-functions"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlclib-stdlib_002eh-functions" accesskey="p"
rel="prev">perlclib <samp>stdlib.h</samp> functions</a>, Up: <a
href="#perlclib-DESCRIPTION" accesskey="u" rel="up">perlclib DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Miscellaneous-functions"></a>
-<h4 class="subsection">9.2.8 Miscellaneous functions</h4>
-
-<p>You should not even <strong>want</strong> to use <samp>setjmp.h</samp>
functions, but if you
-think you do, use the <code>JMPENV</code> stack in <samp>scope.h</samp>
instead.
-</p>
-<p>For <code>signal</code>/<code>sigaction</code>, use <code>rsignal(signo,
handler)</code>.
-</p>
-<hr>
-<a name="perlclib-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlclib-DESCRIPTION" accesskey="p" rel="prev">perlclib
DESCRIPTION</a>, Up: <a href="#perlclib" accesskey="u" rel="up">perlclib</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-3"></a>
-<h3 class="section">9.3 SEE ALSO</h3>
-
-<p><a href="perlapi.html#Top">(perlapi)</a>, <a href="#perlapio-NAME">perlapio
NAME</a>, <a href="#perlguts-NAME">perlguts NAME</a>
-</p>
-<hr>
-<a name="perlcommunity"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata" accesskey="n" rel="next">perldata</a>, Previous: <a
href="#perlclib" accesskey="p" rel="prev">perlclib</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlcommunity-1"></a>
-<h2 class="chapter">10 perlcommunity</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlcommunity-NAME"
accesskey="1">perlcommunity NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcommunity-DESCRIPTION"
accesskey="2">perlcommunity DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcommunity-AUTHOR"
accesskey="3">perlcommunity AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlcommunity-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcommunity-DESCRIPTION" accesskey="n"
rel="next">perlcommunity DESCRIPTION</a>, Up: <a href="#perlcommunity"
accesskey="u" rel="up">perlcommunity</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-9"></a>
-<h3 class="section">10.1 NAME</h3>
-
-<p>perlcommunity - a brief overview of the Perl community
-</p>
-<hr>
-<a name="perlcommunity-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcommunity-AUTHOR" accesskey="n" rel="next">perlcommunity
AUTHOR</a>, Previous: <a href="#perlcommunity-NAME" accesskey="p"
rel="prev">perlcommunity NAME</a>, Up: <a href="#perlcommunity" accesskey="u"
rel="up">perlcommunity</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-9"></a>
-<h3 class="section">10.2 DESCRIPTION</h3>
-
-<p>This document aims to provide an overview of the vast perl community, which
is
-far too large and diverse to provide a detailed listing. If any specific niche
-has been forgotten, it is not meant as an insult but an omission for the sake
-of brevity.
-</p>
-<p>The Perl community is as diverse as Perl, and there is a large amount of
-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.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlcommunity-Where-to-Find-the-Community" accesskey="1">perlcommunity
Where to Find the Community</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcommunity-Mailing-Lists-and-Newsgroups" accesskey="2">perlcommunity
Mailing Lists and Newsgroups</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcommunity-IRC"
accesskey="3">perlcommunity IRC</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcommunity-Websites"
accesskey="4">perlcommunity Websites</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcommunity-User-Groups"
accesskey="5">perlcommunity User Groups</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcommunity-Workshops"
accesskey="6">perlcommunity Workshops</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcommunity-Hackathons"
accesskey="7">perlcommunity Hackathons</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcommunity-Conventions"
accesskey="8">perlcommunity Conventions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlcommunity-Calendar-of-Perl-Events" accesskey="9">perlcommunity
Calendar of Perl Events</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlcommunity-Where-to-Find-the-Community"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcommunity-Mailing-Lists-and-Newsgroups" accesskey="n"
rel="next">perlcommunity Mailing Lists and Newsgroups</a>, Up: <a
href="#perlcommunity-DESCRIPTION" accesskey="u" rel="up">perlcommunity
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Where-to-Find-the-Community"></a>
-<h4 class="subsection">10.2.1 Where to Find the Community</h4>
-
-<p>There is a central directory for the Perl community: <a
href="http://perl.org";>http://perl.org</a>
-maintained by the Perl Foundation (<a
href="http://www.perlfoundation.org/";>http://www.perlfoundation.org/</a>),
-which tracks and provides services for a variety of other community sites.
-</p>
-<hr>
-<a name="perlcommunity-Mailing-Lists-and-Newsgroups"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcommunity-IRC" accesskey="n" rel="next">perlcommunity
IRC</a>, Previous: <a href="#perlcommunity-Where-to-Find-the-Community"
accesskey="p" rel="prev">perlcommunity Where to Find the Community</a>, Up: <a
href="#perlcommunity-DESCRIPTION" accesskey="u" rel="up">perlcommunity
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Mailing-Lists-and-Newsgroups"></a>
-<h4 class="subsection">10.2.2 Mailing Lists and Newsgroups</h4>
-
-<p>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
-<a href="http://lists.perl.org";>http://lists.perl.org</a>.
-</p>
-<p>Most Perl-related projects set up mailing lists for both users and
-contributors. If you don’t see a certain project listed at
-<a href="http://lists.perl.org";>http://lists.perl.org</a>, check the
particular website for that project.
-Most mailing lists are archived at <a
href="http://nntp.perl.org/";>http://nntp.perl.org/</a>.
-</p>
-<p>There are also plenty of Perl related newsgroups located under
-<code>comp.lang.perl.*</code>.
-</p>
-<hr>
-<a name="perlcommunity-IRC"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcommunity-Websites" accesskey="n" rel="next">perlcommunity
Websites</a>, Previous: <a href="#perlcommunity-Mailing-Lists-and-Newsgroups"
accesskey="p" rel="prev">perlcommunity Mailing Lists and Newsgroups</a>, Up: <a
href="#perlcommunity-DESCRIPTION" accesskey="u" rel="up">perlcommunity
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="IRC"></a>
-<h4 class="subsection">10.2.3 IRC</h4>
-
-<p>The Perl community has a rather large IRC presence. For starters, it has its
-own IRC network, <a href="irc://irc.perl.org">irc://irc.perl.org</a>. General
(not help-oriented) chat can be
-found at <a href="irc://irc.perl.org/#perl">irc://irc.perl.org/#perl</a>. Many
other more specific chats are also
-hosted on the network. Information about irc.perl.org is located on the
-network’s website: <a
href="http://www.irc.perl.org";>http://www.irc.perl.org</a>. For a more
help-oriented #perl,
-check out <a
href="irc://irc.freenode.net/#perl">irc://irc.freenode.net/#perl</a>. Perl 6
development also has a
-presence in <a
href="irc://irc.freenode.net/#perl6">irc://irc.freenode.net/#perl6</a>. Most
Perl-related channels will
-be kind enough to point you in the right direction if you ask nicely.
-</p>
-<p>Any large IRC network (Dalnet, EFnet) is also likely to have a #perl
channel,
-with varying activity levels.
-</p>
-<hr>
-<a name="perlcommunity-Websites"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcommunity-User-Groups" accesskey="n"
rel="next">perlcommunity User Groups</a>, Previous: <a
href="#perlcommunity-IRC" accesskey="p" rel="prev">perlcommunity IRC</a>, Up:
<a href="#perlcommunity-DESCRIPTION" accesskey="u" rel="up">perlcommunity
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Websites"></a>
-<h4 class="subsection">10.2.4 Websites</h4>
-
-<p>Perl websites come in a variety of forms, but they fit into two large
-categories: forums and news websites. There are many Perl-related
-websites, so only a few of the community’s largest are mentioned here.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlcommunity-News-sites"
accesskey="1">perlcommunity News sites</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlcommunity-Forums"
accesskey="2">perlcommunity Forums</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlcommunity-News-sites"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcommunity-Forums" accesskey="n" rel="next">perlcommunity
Forums</a>, Up: <a href="#perlcommunity-Websites" accesskey="u"
rel="up">perlcommunity Websites</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="News-sites"></a>
-<h4 class="subsubsection">10.2.4.1 News sites</h4>
-
-<dl compact="compact">
-<dt><a href="http://perl.com/";>http://perl.com/</a></dt>
-<dd><a name="perlcommunity-http_003a_002f_002fperl_002ecom_002f"></a>
-<p>Originally run by O’Reilly Media (the publisher of <a
href="#perlbook-NAME">the Camel Book</a>,
-this site provides quality articles mostly about technical details of Perl.
-</p>
-</dd>
-<dt><a href="http://blogs.perl.org/";>http://blogs.perl.org/</a></dt>
-<dd><a name="perlcommunity-http_003a_002f_002fblogs_002eperl_002eorg_002f"></a>
-<p>Many members of the community have a Perl-related blog on this site. If
-you’d like to join them, you can sign up for free.
-</p>
-</dd>
-<dt><a href="http://perlsphere.net/";>http://perlsphere.net/</a></dt>
-<dd><a name="perlcommunity-http_003a_002f_002fperlsphere_002enet_002f"></a>
-<p>Perlsphere is one of several aggregators of Perl-related blog feeds.
-</p>
-</dd>
-<dt><a href="http://perlweekly.com/";>http://perlweekly.com/</a></dt>
-<dd><a name="perlcommunity-http_003a_002f_002fperlweekly_002ecom_002f"></a>
-<p>Perl Weekly is a weekly mailing list that keeps you up to date on
conferences,
-releases and notable blog posts.
-</p>
-</dd>
-<dt><a href="http://use.perl.org/";>http://use.perl.org/</a></dt>
-<dd><a name="perlcommunity-http_003a_002f_002fuse_002eperl_002eorg_002f"></a>
-<p>use Perl; used to provide a slashdot-style news/blog website covering all
-things Perl, from minutes of the meetings of the Perl 6 Design team to
-conference announcements with (ir)relevant discussion. It no longer accepts
-updates, but you can still use the site to read old entries and comments.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlcommunity-Forums"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlcommunity-News-sites" accesskey="p"
rel="prev">perlcommunity News sites</a>, Up: <a href="#perlcommunity-Websites"
accesskey="u" rel="up">perlcommunity Websites</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Forums"></a>
-<h4 class="subsubsection">10.2.4.2 Forums</h4>
-
-<dl compact="compact">
-<dt><a href="http://www.perlmonks.org/";>http://www.perlmonks.org/</a></dt>
-<dd><a
name="perlcommunity-http_003a_002f_002fwww_002eperlmonks_002eorg_002f"></a>
-<p>PerlMonks is one of the largest Perl forums, and describes itself as
"A place
-for individuals to polish, improve, and showcase their Perl skills." and
"A
-community which allows everyone to grow and learn from each other."
-</p>
-</dd>
-<dt><a href="http://stackoverflow.com/";>http://stackoverflow.com/</a></dt>
-<dd><a name="perlcommunity-http_003a_002f_002fstackoverflow_002ecom_002f"></a>
-<p>Stack Overflow is a free question-and-answer site for programmers.
It’s not
-focussed solely on Perl, but it does have an active group of users who do
-their best to help people with their Perl programming questions.
-</p>
-</dd>
-<dt><a href="http://prepan.org/";>http://prepan.org/</a></dt>
-<dd><a name="perlcommunity-http_003a_002f_002fprepan_002eorg_002f"></a>
-<p>PrePAN is used as a place to discuss modules that you’re considering
uploading
-to the CPAN. You can get feedback on their design before you upload.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlcommunity-User-Groups"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcommunity-Workshops" accesskey="n"
rel="next">perlcommunity Workshops</a>, Previous: <a
href="#perlcommunity-Websites" accesskey="p" rel="prev">perlcommunity
Websites</a>, Up: <a href="#perlcommunity-DESCRIPTION" accesskey="u"
rel="up">perlcommunity DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="User-Groups"></a>
-<h4 class="subsection">10.2.5 User Groups</h4>
-
-<p>Many cities around the world have local Perl Mongers chapters. A Perl
Mongers
-chapter is a local user group which typically holds regular in-person meetings,
-both social and technical; helps organize local conferences, workshops, and
-hackathons; and provides a mailing list or other continual contact method for
-its members to keep in touch.
-</p>
-<p>To find your local Perl Mongers (or PM as they’re commonly
abbreviated) group
-check the international Perl Mongers directory at <a
href="http://www.pm.org/";>http://www.pm.org/</a>.
-</p>
-<hr>
-<a name="perlcommunity-Workshops"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcommunity-Hackathons" accesskey="n"
rel="next">perlcommunity Hackathons</a>, Previous: <a
href="#perlcommunity-User-Groups" accesskey="p" rel="prev">perlcommunity User
Groups</a>, Up: <a href="#perlcommunity-DESCRIPTION" accesskey="u"
rel="up">perlcommunity DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Workshops"></a>
-<h4 class="subsection">10.2.6 Workshops</h4>
-
-<p>Perl workshops are, as the name might suggest, workshops where Perl is
taught
-in a variety of ways. At the workshops, subjects range from a beginner’s
-introduction (such as the Pittsburgh Perl Workshop’s "Zero To
Perl") to much
-more advanced subjects.
-</p>
-<p>There are several great resources for locating workshops: the
-<a href="#perlcommunity-Websites">websites</a> mentioned above, the
-<a href="#perlcommunity-Calendar-of-Perl-Events">calendar</a> mentioned below,
and the YAPC Europe
-website, <a href="http://www.yapceurope.org/";>http://www.yapceurope.org/</a>,
which is probably the best resource for
-European Perl events.
-</p>
-<hr>
-<a name="perlcommunity-Hackathons"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcommunity-Conventions" accesskey="n"
rel="next">perlcommunity Conventions</a>, Previous: <a
href="#perlcommunity-Workshops" accesskey="p" rel="prev">perlcommunity
Workshops</a>, Up: <a href="#perlcommunity-DESCRIPTION" accesskey="u"
rel="up">perlcommunity DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Hackathons"></a>
-<h4 class="subsection">10.2.7 Hackathons</h4>
-
-<p>Hackathons are a very different kind of gathering where Perl hackers gather
to
-do just that, hack nonstop for an extended (several day) period on a specific
-project or projects. Information about hackathons can be located in the same
-place as information about <a href="#perlcommunity-Workshops">workshops</a> as
well as in
-<a href="irc://irc.perl.org/#perl">irc://irc.perl.org/#perl</a>.
-</p>
-<p>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 beforehand; have the necessary version control client;
-and bring backup equipment (an extra LAN cable, additional power strips, etc.)
-because someone will forget.
-</p>
-<hr>
-<a name="perlcommunity-Conventions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlcommunity-Calendar-of-Perl-Events" accesskey="n"
rel="next">perlcommunity Calendar of Perl Events</a>, Previous: <a
href="#perlcommunity-Hackathons" accesskey="p" rel="prev">perlcommunity
Hackathons</a>, Up: <a href="#perlcommunity-DESCRIPTION" accesskey="u"
rel="up">perlcommunity DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Conventions-1"></a>
-<h4 class="subsection">10.2.8 Conventions</h4>
-
-<p>Perl has two major annual conventions: The Perl Conference (now part of
OSCON),
-put on by O’Reilly, and Yet Another Perl Conference or YAPC (pronounced
-yap-see), which is localized into several regional YAPCs (North America,
-Europe, Asia) in a stunning grassroots display by the Perl community. For more
-information about either conference, check out their respective web pages:
-OSCON <a
href="http://conferences.oreillynet.com/";>http://conferences.oreillynet.com/</a>;
YAPC <a href="http://www.yapc.org";>http://www.yapc.org</a>.
-</p>
-<p>A relatively new conference franchise with a large Perl portion is the
-Open Source Developers Conference or OSDC. First held in Australia it has
-recently also spread to Israel and France. More information can be found at:
-<a href="http://www.osdc.com.au/";>http://www.osdc.com.au/</a> for Australia,
<a href="http://www.osdc.org.il";>http://www.osdc.org.il</a>
-for Israel, and <a href="http://www.osdc.fr/";>http://www.osdc.fr/</a> for
France.
-</p>
-<hr>
-<a name="perlcommunity-Calendar-of-Perl-Events"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlcommunity-Conventions" accesskey="p"
rel="prev">perlcommunity Conventions</a>, Up: <a
href="#perlcommunity-DESCRIPTION" accesskey="u" rel="up">perlcommunity
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Calendar-of-Perl-Events"></a>
-<h4 class="subsection">10.2.9 Calendar of Perl Events</h4>
-
-<p>The Perl Review, <a
href="http://www.theperlreview.com";>http://www.theperlreview.com</a> maintains
a website
-and Google calendar
-(<a
href="http://www.theperlreview.com/community_calendar";>http://www.theperlreview.com/community_calendar</a>)
for tracking
-workshops, hackathons, Perl Mongers meetings, and other events. Views
-of this calendar are at <a
href="http://www.perl.org/events.html";>http://www.perl.org/events.html</a> and
-<a href="http://www.yapc.org";>http://www.yapc.org</a>.
-</p>
-<p>Not every event or Perl Mongers group is on that calendar, so don’t
lose
-heart if you don’t see yours posted. To have your event or group listed,
-contact brian d foy (address@hidden).
-</p>
-<hr>
-<a name="perlcommunity-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlcommunity-DESCRIPTION" accesskey="p"
rel="prev">perlcommunity DESCRIPTION</a>, Up: <a href="#perlcommunity"
accesskey="u" rel="up">perlcommunity</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-3"></a>
-<h3 class="section">10.3 AUTHOR</h3>
-
-<p>Edgar "Trizor" Bering <address@hidden>
-</p>
-<hr>
-<a name="perldata"></a>
-<div class="header">
-<p>
-Next: <a href="#perldbmfilter" accesskey="n" rel="next">perldbmfilter</a>,
Previous: <a href="#perlcommunity" accesskey="p" rel="prev">perlcommunity</a>,
Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perldata-1"></a>
-<h2 class="chapter">11 perldata</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perldata-NAME"
accesskey="1">perldata NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldata-DESCRIPTION"
accesskey="2">perldata DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldata-SEE-ALSO"
accesskey="3">perldata SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldata-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-DESCRIPTION" accesskey="n" rel="next">perldata
DESCRIPTION</a>, Up: <a href="#perldata" accesskey="u" rel="up">perldata</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-10"></a>
-<h3 class="section">11.1 NAME</h3>
-
-<p>perldata - Perl data types
-</p>
-<hr>
-<a name="perldata-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-SEE-ALSO" accesskey="n" rel="next">perldata SEE
ALSO</a>, Previous: <a href="#perldata-NAME" accesskey="p" rel="prev">perldata
NAME</a>, Up: <a href="#perldata" accesskey="u" rel="up">perldata</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-10"></a>
-<h3 class="section">11.2 DESCRIPTION</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perldata-Variable-names"
accesskey="1">perldata Variable names</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Identifier-parsing" accesskey="2">perldata Identifier
parsing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldata-Context"
accesskey="3">perldata Context</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldata-Scalar-values"
accesskey="4">perldata Scalar values</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Scalar-value-constructors" accesskey="5">perldata Scalar value
constructors</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-List-value-constructors" accesskey="6">perldata List value
constructors</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldata-Subscripts"
accesskey="7">perldata Subscripts</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Multi_002ddimensional-array-emulation" accesskey="8">perldata
Multi-dimensional array emulation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldata-Slices"
accesskey="9">perldata Slices</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Typeglobs-and-Filehandles">perldata Typeglobs and
Filehandles</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldata-Variable-names"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-Identifier-parsing" accesskey="n" rel="next">perldata
Identifier parsing</a>, Up: <a href="#perldata-DESCRIPTION" accesskey="u"
rel="up">perldata DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Variable-names"></a>
-<h4 class="subsection">11.2.1 Variable names</h4>
-
-<p>Perl has three built-in data types: scalars, arrays of scalars, and
-associative arrays of scalars, known as "hashes". A scalar is a
-single string (of any size, limited only by the available memory),
-number, or a reference to something (which will be discussed
-in <a href="#perlref-NAME">perlref NAME</a>). Normal arrays are ordered lists
of scalars indexed
-by number, starting with 0. Hashes are unordered collections of scalar
-values indexed by their associated string key.
-</p>
-<p>Values are usually referred to by name, or through a named reference.
-The first character of the name tells you to what sort of data
-structure it refers. The rest of the name tells you the particular
-value to which it refers. Usually this name is a single <em>identifier</em>,
-that is, a string beginning with a letter or underscore, and
-containing letters, underscores, and digits. In some cases, it may
-be a chain of identifiers, separated by <code>::</code> (or by the slightly
-archaic <code>'</code>); all but the last are interpreted as names of packages,
-to locate the namespace in which to look up the final identifier
-(see <a href="#perlmod-Packages">perlmod Packages</a> for details). For a
more in-depth discussion
-on identifiers, see <a href="#perldata-Identifier-parsing">Identifier
parsing</a>. It’s possible to
-substitute for a simple identifier, an expression that produces a reference
-to the value at runtime. This is described in more detail below
-and in <a href="#perlref-NAME">perlref NAME</a>.
-</p>
-<p>Perl also has its own built-in variables whose names don’t follow
-these rules. They have strange names so they don’t accidentally
-collide with one of your normal variables. Strings that match
-parenthesized parts of a regular expression are saved under names
-containing only digits after the <code>$</code> (see <a
href="#perlop-NAME">perlop NAME</a> and <a href="#perlre-NAME">perlre NAME</a>).
-In addition, several special variables that provide windows into
-the inner working of Perl have names containing punctuation characters
-and control characters. These are documented in <a
href="#perlvar-NAME">perlvar NAME</a>.
-</p>
-<p>Scalar values are always named with ’$’, even when referring to
a
-scalar that is part of an array or a hash. The ’$’ symbol works
-semantically like the English word "the" in that it indicates a
-single value is expected.
-</p>
-<pre class="verbatim"> $days # the simple scalar value
"days"
- $days[28] # the 29th element of array @days
- $days{'Feb'} # the 'Feb' value from hash %days
- $#days # the last index of array @days
-</pre>
-<p>Entire arrays (and slices of arrays and hashes) are denoted by
’@’,
-which works much as the word "these" or "those" does in
English,
-in that it indicates multiple values are expected.
-</p>
-<pre class="verbatim"> @days # ($days[0], $days[1],...
$days[n])
- @days[3,4,5] # same as ($days[3],$days[4],$days[5])
- @days{'a','c'} # same as ($days{'a'},$days{'c'})
-</pre>
-<p>Entire hashes are denoted by ’%’:
-</p>
-<pre class="verbatim"> %days # (key1, val1, key2, val2 ...)
-</pre>
-<p>In addition, subroutines are named with an initial ’&’,
though this
-is optional when unambiguous, just as the word "do" is often
redundant
-in English. Symbol table entries can be named with an initial ’*’,
-but you don’t really care about that yet (if ever :-).
-</p>
-<p>Every variable type has its own namespace, as do several
-non-variable identifiers. This means that you can, without fear
-of conflict, use the same name for a scalar variable, an array, or
-a hash–or, for that matter, for a filehandle, a directory handle, a
-subroutine name, a format name, or a label. This means that $foo
-and @foo are two different variables. It also means that <code>$foo[1]</code>
-is a part of @foo, not a part of $foo. This may seem a bit weird,
-but that’s okay, because it is weird.
-</p>
-<p>Because variable references always start with ’$’,
’@’, or ’%’, the
-"reserved" words aren’t in fact reserved with respect to
variable
-names. They <em>are</em> reserved with respect to labels and filehandles,
-however, which don’t have an initial special character. You can’t
-have a filehandle named "log", for instance. Hint: you could say
-<code>open(LOG,'logfile')</code> rather than <code>open(log,'logfile')</code>.
Using
-uppercase filehandles also improves readability and protects you
-from conflict with future reserved words. Case <em>is</em>
significant–"FOO",
-"Foo", and "foo" are all different names. Names that
start with a
-letter or underscore may also contain digits and underscores.
-</p>
-<p>It is possible to replace such an alphanumeric name with an expression
-that returns a reference to the appropriate type. For a description
-of this, see <a href="#perlref-NAME">perlref NAME</a>.
-</p>
-<p>Names that start with a digit may contain only more digits. Names
-that do not start with a letter, underscore, digit or a caret (i.e.
-a control character) are limited to one character, e.g., <code>$%</code> or
-<code>$$</code>. (Most of these one character names have a predefined
-significance to Perl. For instance, <code>$$</code> is the current process
-id.)
-</p>
-<hr>
-<a name="perldata-Identifier-parsing"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-Context" accesskey="n" rel="next">perldata
Context</a>, Previous: <a href="#perldata-Variable-names" accesskey="p"
rel="prev">perldata Variable names</a>, Up: <a href="#perldata-DESCRIPTION"
accesskey="u" rel="up">perldata DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Identifier-parsing"></a>
-<h4 class="subsection">11.2.2 Identifier parsing</h4>
-
-<p>Up until Perl 5.18, the actual rules of what a valid identifier
-was were a bit fuzzy. However, in general, anything defined here should
-work on previous versions of Perl, while the opposite – edge cases
-that work in previous versions, but aren’t defined here – probably
-won’t work on newer versions.
-As an important side note, please note that the following only applies
-to bareword identifiers as found in Perl source code, not identifiers
-introduced through symbolic references, which have much fewer
-restrictions.
-If working under the effect of the <code>use utf8;</code> pragma, the following
-rules apply:
-</p>
-<pre class="verbatim"> / (?[ ( \p{Word} & \p{XID_Start} ) + [_] ])
- (?[ ( \p{Word} & \p{XID_Continue} ) ]) * /x
-</pre>
-<p>That is, a "start" character followed by any number of
"continue"
-characters. Perl requires every character in an identifier to also
-match <code>\w</code> (this prevents some problematic cases); and Perl
-additionally accepts identfier names beginning with an underscore.
-</p>
-<p>If not under <code>use utf8</code>, the source is treated as ASCII + 128
extra
-controls, and identifiers should match
-</p>
-<pre class="verbatim"> / (?aa) (?!\d) \w+ /x
-</pre>
-<p>That is, any word character in the ASCII range, as long as the first
-character is not a digit.
-</p>
-<p>There are two package separators in Perl: A double colon (<code>::</code>)
and a single
-quote (<code>'</code>). Normal identifiers can start or end with a double
colon, and
-can contain several parts delimited by double colons.
-Single quotes have similar rules, but with the exception that they are not
-legal at the end of an identifier: That is, <code>$'foo</code> and
<code>$foo'bar</code> are
-legal, but <code>$foo'bar'</code> is not.
-</p>
-<p>Additionally, if the identifier is preceded by a sigil –
-that is, if the identifier is part of a variable name – it
-may optionally be enclosed in braces.
-</p>
-<p>While you can mix double colons with singles quotes, the quotes must come
-after the colons: <code>$::::'foo</code> and <code>$foo::'bar</code> are
legal, but <code>$::'::foo</code>
-and <code>$foo'::bar</code> are not.
-</p>
-<p>Put together, a grammar to match a basic identifier becomes
-</p>
-<pre class="verbatim"> /
- (?(DEFINE)
- (?<variable>
- (?&sigil)
- (?:
- (?&normal_identifier)
- | \{ \s* (?&normal_identifier) \s* \}
- )
- )
- (?<normal_identifier>
- (?: :: )* '?
- (?&basic_identifier)
- (?: (?= (?: :: )+ '? | (?: :: )* ' ) (?&normal_identifier) )?
- (?: :: )*
- )
- (?<basic_identifier>
- # is use utf8 on?
- (?(?{ (caller(0))[8] & $utf8::hint_bits })
- (?&Perl_XIDS) (?&Perl_XIDC)*
- | (?aa) (?!\d) \w+
- )
- )
- (?<sigil> [&address@hidden)
- (?<Perl_XIDS> (?[ ( \p{Word} & \p{XID_Start} ) + [_] ]) )
- (?<Perl_XIDC> (?[ \p{Word} & \p{XID_Continue} ]) )
- )
- /x
-</pre>
-<p>Meanwhile, special identifiers don’t follow the above rules; For the
most
-part, all of the identifiers in this category have a special meaning given
-by Perl. Because they have special parsing rules, these generally can’t
be
-fully-qualified. They come in four forms:
-</p>
-<ul>
-<li> A sigil, followed solely by digits matching <code>\p{POSIX_Digit}</code>,
like
-<code>$0</code>, <code>$1</code>, or <code>$10000</code>.
-
-</li><li> A sigil, followed by a caret and any one of the characters
-<code>[][A-Z^_?\]</code>, like <code>$^V</code> or <code>$^]</code>, or a
sigil followed by a literal non-space,
-non-<code>NUL</code> control character matching the
<code>\p{POSIX_Cntrl}</code> property.
-Due to a historical oddity, if not running under <code>use utf8</code>, the 128
-characters in the <code>[0x80-0xff]</code> range are considered to be controls,
-and may also be used in length-one variables. However, the use of
-non-graphical characters is deprecated as of v5.22, and support for them
-will be removed in a future version of perl. ASCII space characters and
-<code>NUL</code> already aren’t allowed, so this means that a
single-character
-variable name with that name being any other C0 control
<code>[0x01-0x1F]</code>,
-or <code>DEL</code> will generate a deprecated warning. Already, under
<code>"use
-utf8"</code>, non-ASCII characters must match <code>Perl_XIDS</code>. As
of v5.22, when
-not under <code>"use utf8"</code> C1 controls
<code>[0x80-0x9F]</code>, NO BREAK SPACE, and
-SOFT HYPHEN (<code>SHY</code>)) generate a deprecated warning.
-
-</li><li> Similar to the above, a sigil, followed by bareword text in braces,
-where the first character is either a caret followed by any one of
-the characters <code>[][A-Z^_?\]</code>, like <code>${^GLOBAL_PHASE}</code>,
or a non-<code>NUL</code>,
-non-space literal
-control like <code>${\7LOBAL_PHASE}</code>. Like the above, when not under
-<code>"use utf8"</code>, the characters in <code>[0x80-0xFF]</code>
are considered controls, but as
-of v5.22, the use of any that are non-graphical are deprecated, and as
-of v5.20 the use of any ASCII-range literal control is deprecated.
-Support for these will be removed in a future version of perl.
-
-</li><li> A sigil followed by a single character matching the
<code>\p{POSIX_Punct}</code>
-property, like <code>$!</code> or <code>%+</code>, except the character
<code>"{"</code> doesn’t work.
-
-</li></ul>
-
-<p>Note that as of Perl 5.20, literal control characters in variable names
-are deprecated; and as of Perl 5.22, any other non-graphic characters
-are also deprecated.
-</p>
-<hr>
-<a name="perldata-Context"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-Scalar-values" accesskey="n" rel="next">perldata
Scalar values</a>, Previous: <a href="#perldata-Identifier-parsing"
accesskey="p" rel="prev">perldata Identifier parsing</a>, Up: <a
href="#perldata-DESCRIPTION" accesskey="u" rel="up">perldata DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Context"></a>
-<h4 class="subsection">11.2.3 Context</h4>
-
-<p>The interpretation of operations and values in Perl sometimes depends
-on the requirements of the context around the operation or value.
-There are two major contexts: list and scalar. Certain operations
-return list values in contexts wanting a list, and scalar values
-otherwise. If this is true of an operation it will be mentioned in
-the documentation for that operation. In other words, Perl overloads
-certain operations based on whether the expected return value is
-singular or plural. Some words in English work this way, like "fish"
-and "sheep".
-</p>
-<p>In a reciprocal fashion, an operation provides either a scalar or a
-list context to each of its arguments. For example, if you say
-</p>
-<pre class="verbatim"> int( <STDIN> )
-</pre>
-<p>the integer operation provides scalar context for the <>
-operator, which responds by reading one line from STDIN and passing it
-back to the integer operation, which will then find the integer value
-of that line and return that. If, on the other hand, you say
-</p>
-<pre class="verbatim"> sort( <STDIN> )
-</pre>
-<p>then the sort operation provides list context for <>, which
-will proceed to read every line available up to the end of file, and
-pass that list of lines back to the sort routine, which will then
-sort those lines and return them as a list to whatever the context
-of the sort was.
-</p>
-<p>Assignment is a little bit special in that it uses its left argument
-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 right-hand side in list context.
-</p>
-<p>When you use the <code>use warnings</code> pragma or Perl’s
<strong>-w</strong> command-line
-option, you may see warnings
-about useless uses of constants or functions in "void context".
-Void context just means the value has been discarded, such as a
-statement containing only <code>"fred";</code> or
<code>getpwuid(0);</code>. It still
-counts as scalar context for functions that care whether or not
-they’re being called in list context.
-</p>
-<p>User-defined subroutines may choose to care whether they are being
-called in a void, scalar, or list context. Most subroutines do not
-need to bother, though. That’s because both scalars and lists are
-automatically interpolated into lists. See <a
href="#perlfunc-wantarray">perlfunc wantarray</a>
-for how you would dynamically discern your function’s calling
-context.
-</p>
-<hr>
-<a name="perldata-Scalar-values"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-Scalar-value-constructors" accesskey="n"
rel="next">perldata Scalar value constructors</a>, Previous: <a
href="#perldata-Context" accesskey="p" rel="prev">perldata Context</a>, Up: <a
href="#perldata-DESCRIPTION" accesskey="u" rel="up">perldata DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Scalar-values"></a>
-<h4 class="subsection">11.2.4 Scalar values</h4>
-
-<p>All data in Perl is a scalar, an array of scalars, or a hash of
-scalars. A scalar may contain one single value in any of three
-different flavors: a number, a string, or a reference. In general,
-conversion from one form to another is transparent. Although a
-scalar may not directly hold multiple values, it may contain a
-reference to an array or hash which in turn contains multiple values.
-</p>
-<p>Scalars aren’t necessarily one thing or another. There’s no
place
-to declare a scalar variable to be of type "string", type
"number",
-type "reference", or anything else. Because of the automatic
-conversion of scalars, operations that return scalars don’t need
-to care (and in fact, cannot care) whether their caller is looking
-for a string, a number, or a reference. Perl is a contextually
-polymorphic language whose scalars can be strings, numbers, or
-references (which includes objects). Although strings and numbers
-are considered pretty much the same thing for nearly all purposes,
-references are strongly-typed, uncastable pointers with builtin
-reference-counting and destructor invocation.
-</p>
-<p>A scalar value is interpreted as FALSE in the Boolean sense
-if it is undefined, the null string or the number 0 (or its
-string equivalent, "0"), and TRUE if it is anything else. The
-Boolean context is just a special kind of scalar context where no
-conversion to a string or a number is ever performed.
-</p>
-<p>There are actually two varieties of null strings (sometimes referred
-to as "empty" strings), a defined one and an undefined one. The
-defined version is just a string of length zero, such as
<code>""</code>.
-The undefined version is the value that indicates that there is
-no real value for something, such as when there was an error, or
-at end of file, or when you refer to an uninitialized variable or
-element of an array or hash. Although in early versions of Perl,
-an undefined scalar could become defined when first used in a
-place expecting a defined value, this no longer happens except for
-rare cases of autovivification as explained in <a href="#perlref-NAME">perlref
NAME</a>. You can
-use the defined() operator to determine whether a scalar value is
-defined (this has no meaning on arrays or hashes), and the undef()
-operator to produce an undefined value.
-</p>
-<p>To find out whether a given string is a valid non-zero number, it’s
-sometimes enough to test it against both numeric 0 and also lexical
-"0" (although this will cause noises if warnings are on).
That’s
-because strings that aren’t numbers count as 0, just as they do in
<strong>awk</strong>:
-</p>
-<pre class="verbatim"> if ($str == 0 && $str ne "0") {
- warn "That doesn't look like a number";
- }
-</pre>
-<p>That method may be best because otherwise you won’t treat IEEE
-notations like <code>NaN</code> or <code>Infinity</code> properly. At other
times, you
-might prefer to determine whether string data can be used numerically
-by calling the POSIX::strtod() function or by inspecting your string
-with a regular expression (as documented in <a href="#perlre-NAME">perlre
NAME</a>).
-</p>
-<pre class="verbatim"> warn "has nondigits" if /\D/;
- warn "not a natural number" unless /^\d+$/; #
rejects -3
- warn "not an integer" unless /^-?\d+$/; #
rejects +3
- warn "not an integer" unless /^[+-]?\d+$/;
- warn "not a decimal number" unless /^-?\d+\.?\d*$/; #
rejects .2
- warn "not a decimal number" unless /^-?(?:\d+(?:\.\d*)?|\.\d+)$/;
- warn "not a C float"
- unless /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/;
-</pre>
-<p>The length of an array is a scalar value. You may find the length
-of array @days by evaluating <code>$#days</code>, as in <strong>csh</strong>.
However, this
-isn’t the length of the array; it’s the subscript of the last
element,
-which is a different value since there is ordinarily a 0th element.
-Assigning to <code>$#days</code> actually changes the length of the array.
-Shortening an array this way destroys intervening values. Lengthening
-an array that was previously shortened does not recover values
-that were in those elements.
-</p>
-<p>You can also gain some minuscule measure of efficiency by pre-extending
-an array that is going to get big. You can also extend an array
-by assigning to an element that is off the end of the array. You
-can truncate an array down to nothing by assigning the null list
-() to it. The following are equivalent:
-</p>
-<pre class="verbatim"> @whatever = ();
- $#whatever = -1;
-</pre>
-<p>If you evaluate an array in scalar context, it returns the length
-of the array. (Note that this is not true of lists, which return
-the last value, like the C comma operator, nor of built-in functions,
-which return whatever they feel like returning.) The following is
-always true:
-</p>
-<pre class="verbatim"> scalar(@whatever) == $#whatever + 1;
-</pre>
-<p>Some programmers choose to use an explicit conversion so as to
-leave nothing to doubt:
-</p>
-<pre class="verbatim"> $element_count = scalar(@whatever);
-</pre>
-<p>If you evaluate a hash in scalar context, it returns false if the
-hash is empty. If there are any key/value pairs, it returns true;
-more precisely, the value returned is a string consisting of the
-number of used buckets and the number of allocated buckets, separated
-by a slash. This is pretty much useful only to find out whether
-Perl’s internal hashing algorithm is performing poorly on your data
-set. For example, you stick 10,000 things in a hash, but evaluating
-%HASH in scalar context reveals <code>"1/16"</code>, 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, the <code>SCALAR</code> method is called (with
a
-fallback to <code>FIRSTKEY</code>).
-</p>
-<p>You can preallocate space for a hash by assigning to the keys() function.
-This rounds up the allocated buckets to the next power of two:
-</p>
-<pre class="verbatim"> keys(%users) = 1000; # allocate 1024
buckets
-</pre>
-<hr>
-<a name="perldata-Scalar-value-constructors"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-List-value-constructors" accesskey="n"
rel="next">perldata List value constructors</a>, Previous: <a
href="#perldata-Scalar-values" accesskey="p" rel="prev">perldata Scalar
values</a>, Up: <a href="#perldata-DESCRIPTION" accesskey="u" rel="up">perldata
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Scalar-value-constructors"></a>
-<h4 class="subsection">11.2.5 Scalar value constructors</h4>
-
-<p>Numeric literals are specified in any of the following floating point or
-integer formats:
-</p>
-<pre class="verbatim"> 12345
- 12345.67
- .23E-10 # a very small number
- 3.14_15_92 # a very important number
- 4_294_967_296 # underscore for legibility
- 0xff # hex
- 0xdead_beef # more hex
- 0377 # octal (only numbers, begins with 0)
- 0b011011 # binary
- 0x1.999ap-4 # hexadecimal floating point (the 'p' is required)
-</pre>
-<p>You are allowed to use underscores (underbars) in numeric literals
-between digits for legibility (but not multiple underscores in a row:
-<code>23__500</code> is not legal; <code>23_500</code> is).
-You could, for example, group binary
-digits by threes (as for a Unix-style mode argument such as 0b110_100_100)
-or by fours (to represent nibbles, as in 0b1010_0110) or in other groups.
-</p>
-<p>String literals are usually delimited by either single or double
-quotes. They work much like quotes in the standard Unix shells:
-double-quoted string literals are subject to backslash and variable
-substitution; single-quoted strings are not (except for <code>\'</code> and
-<code>\\</code>). The usual C-style backslash rules apply for making
-characters such as newline, tab, etc., as well as some more exotic
-forms. See <a href="#perlop-Quote-and-Quote_002dlike-Operators">perlop Quote
and Quote-like Operators</a> for a list.
-</p>
-<p>Hexadecimal, octal, or binary, representations in string literals
-(e.g. ’0xff’) are not automatically converted to their integer
-representation. The hex() and oct() functions make these conversions
-for you. See <a href="#perlfunc-hex">perlfunc hex</a> and <a
href="#perlfunc-oct">perlfunc oct</a> for more details.
-</p>
-<p>Hexadecimal floating point can start just like a hexadecimal literal,
-and it can be followed by an optional fractional hexadecimal part,
-but it must be followed by <code>p</code>, an optional sign, and a power of
two.
-The format is useful for accurately presenting floating point values,
-avoiding conversions to or from decimal floating point, and therefore
-avoiding possible loss in precision. Notice that while most current
-platforms use the 64-bit IEEE 754 floating point, not all do. Another
-potential source of (low-order) differences are the floating point
-rounding modes, which can differ between CPUs, operating systems,
-and compilers, and which Perl doesn’t control.
-</p>
-<p>You can also embed newlines directly in your strings, i.e., they can end
-on a different line than they begin. This is nice, but if you forget
-your trailing quote, the error will not be reported until Perl finds
-another line containing the quote character, which may be much further
-on in the script. Variable substitution inside strings is limited to
-scalar variables, arrays, and array or hash slices. (In other words,
-names beginning with $ or @, followed by an optional bracketed
-expression as a subscript.) The following code segment prints out "The
-price is $100."
-</p>
-<pre class="verbatim"> $Price = '$100'; # not interpolated
- print "The price is $Price.\n"; # interpolated
-</pre>
-<p>There is no double interpolation in Perl, so the <code>$100</code> is left
as is.
-</p>
-<p>By default floating point numbers substituted inside strings use the
-dot (".") as the decimal separator. If <code>use locale</code> is
in effect,
-and POSIX::setlocale() has been called, the character used for the
-decimal separator is affected by the LC_NUMERIC locale.
-See <a href="#perllocale-NAME">perllocale NAME</a> and <a
href="POSIX.html#Top">(POSIX)</a>.
-</p>
-<p>As in some shells, you can enclose the variable name in braces to
-disambiguate it from following alphanumerics (and underscores).
-You must also do
-this when interpolating a variable into a string to separate the
-variable name from a following double-colon or an apostrophe, since
-these would be otherwise treated as a package separator:
-</p>
-<pre class="verbatim"> $who = "Larry";
- print PASSWD "${who}::0:0:Superuser:/:/bin/perl\n";
- print "We use ${who}speak when ${who}'s here.\n";
-</pre>
-<p>Without the braces, Perl would have looked for a $whospeak, a
-<code>$who::0</code>, and a <code>$who's</code> variable. The last two would
be the
-$0 and the $s variables in the (presumably) non-existent package
-<code>who</code>.
-</p>
-<p>In fact, a simple identifier within such curlies is forced to be
-a string, and likewise within a hash subscript. Neither need
-quoting. Our earlier example, <code>$days{'Feb'}</code> can be written as
-<code>$days{Feb}</code> and the quotes will be assumed automatically. But
-anything more complicated in the subscript will be interpreted as an
-expression. This means for example that <code>$version{2.0}++</code> is
-equivalent to <code>$version{2}++</code>, not to
<code>$version{'2.0'}++</code>.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perldata-Special-floating-point_003a-infinity-_0028Inf_0029-and-not_002da_002dnumber-_0028NaN_0029"
accesskey="1">perldata Special floating point: infinity (Inf) and not-a-number
(NaN)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldata-Version-Strings"
accesskey="2">perldata Version Strings</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldata-Special-Literals"
accesskey="3">perldata Special Literals</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldata-Barewords"
accesskey="4">perldata Barewords</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Array-Interpolation" accesskey="5">perldata Array
Interpolation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a
name="perldata-Special-floating-point_003a-infinity-_0028Inf_0029-and-not_002da_002dnumber-_0028NaN_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-Version-Strings" accesskey="n" rel="next">perldata
Version Strings</a>, Up: <a href="#perldata-Scalar-value-constructors"
accesskey="u" rel="up">perldata Scalar value constructors</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a
name="Special-floating-point_003a-infinity-_0028Inf_0029-and-not_002da_002dnumber-_0028NaN_0029"></a>
-<h4 class="subsubsection">11.2.5.1 Special floating point: infinity (Inf) and
not-a-number (NaN)</h4>
-
-<p>Floating point values include the special values <code>Inf</code> and
<code>NaN</code>,
-for infinity and not-a-number. The infinity can be also negative.
-</p>
-<p>The infinity is the result of certain math operations that overflow
-the floating point range, like 9**9**9. The not-a-number is the
-result when the result is undefined or unrepresentable. Though note
-that you cannot get <code>NaN</code> from some common "undefined" or
-"out-of-range" operations like dividing by zero, or square root of
-a negative number, since Perl generates fatal errors for those.
-</p>
-<p>The infinity and not-a-number have their own special arithmetic rules.
-The general rule is that they are "contagious": <code>Inf</code>
plus one is
-<code>Inf</code>, and <code>NaN</code> plus one is <code>NaN</code>. Where
things get interesting
-is when you combine infinities and not-a-numbers: <code>Inf</code> minus
<code>Inf</code>
-and <code>Inf</code> divided by <code>INf</code> are <code>NaN</code> (while
<code>Inf</code> plus <code>Inf</code> is
-<code>Inf</code> and <code>Inf</code> times <code>Inf</code> is
<code>Inf</code>). <code>NaN</code> is also curious
-in that it does not equal any number, <em>including</em> itself:
-<code>NaN</code> != <code>NaN</code>.
-</p>
-<p>Perl doesn’t understand <code>Inf</code> and <code>NaN</code> as
numeric literals, but
-you can have them as strings, and Perl will convert them as needed:
-"Inf" + 1. (You can, however, import them from the POSIX extension;
-<code>use POSIX qw(Inf NaN);</code> and then use them as literals.)
-</p>
-<p>Note that on input (string to number) Perl accepts <code>Inf</code> and
<code>NaN</code>
-in many forms. Case is ignored, and the Win32-specific forms like
-<code>1.#INF</code> are understood, but on output the values are normalized to
-<code>Inf</code> and <code>NaN</code>.
-</p>
-<hr>
-<a name="perldata-Version-Strings"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-Special-Literals" accesskey="n" rel="next">perldata
Special Literals</a>, Previous: <a
href="#perldata-Special-floating-point_003a-infinity-_0028Inf_0029-and-not_002da_002dnumber-_0028NaN_0029"
accesskey="p" rel="prev">perldata Special floating point: infinity (Inf) and
not-a-number (NaN)</a>, Up: <a href="#perldata-Scalar-value-constructors"
accesskey="u" rel="up">perldata Scalar value constructors</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Version-Strings"></a>
-<h4 class="subsubsection">11.2.5.2 Version Strings</h4>
-
-<p>A literal of the form <code>v1.20.300.4000</code> is parsed as a string
composed
-of characters with the specified ordinals. This form, known as
-v-strings, provides an alternative, more readable way to construct
-strings, rather than use the somewhat less readable interpolation form
-<code>"\x{1}\x{14}\x{12c}\x{fa0}"</code>. This is useful for
representing
-Unicode strings, and for comparing version "numbers" using the string
-comparison operators, <code>cmp</code>, <code>gt</code>, <code>lt</code> etc.
If there are two or
-more dots in the literal, the leading <code>v</code> may be omitted.
-</p>
-<pre class="verbatim"> print v9786; # prints SMILEY,
"\x{263a}"
- print v102.111.111; # prints "foo"
- print 102.111.111; # same
-</pre>
-<p>Such literals are accepted by both <code>require</code> and
<code>use</code> for
-doing a version check. Note that using the v-strings for IPv4
-addresses is not portable unless you also use the
-inet_aton()/inet_ntoa() routines of the Socket package.
-</p>
-<p>Note that since Perl 5.8.1 the single-number v-strings (like
<code>v65</code>)
-are not v-strings before the <code>=></code> operator (which is usually used
-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 <code>v65.66</code> and <code>65.66.67</code>
continue to
-be v-strings always.
-</p>
-<hr>
-<a name="perldata-Special-Literals"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-Barewords" accesskey="n" rel="next">perldata
Barewords</a>, Previous: <a href="#perldata-Version-Strings" accesskey="p"
rel="prev">perldata Version Strings</a>, Up: <a
href="#perldata-Scalar-value-constructors" accesskey="u" rel="up">perldata
Scalar value constructors</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Special-Literals"></a>
-<h4 class="subsubsection">11.2.5.3 Special Literals</h4>
-
-<p>The special literals __FILE__, __LINE__, and __PACKAGE__
-represent the current filename, line number, and package name at that
-point in your program. __SUB__ gives a reference to the current
-subroutine. They may be used only as separate tokens; they
-will not be interpolated into strings. If there is no current package
-(due to an empty <code>package;</code> directive), __PACKAGE__ is the undefined
-value. (But the empty <code>package;</code> is no longer supported, as of
version
-5.10.) Outside of a subroutine, __SUB__ is the undefined value. __SUB__
-is only available in 5.16 or higher, and only with a <code>use v5.16</code> or
-<code>use feature "current_sub"</code> declaration.
-</p>
-<p>The two control characters ^D and ^Z, and the tokens __END__ and __DATA__
-may be used to indicate the logical end of the script before the actual
-end of file. Any following text is ignored.
-</p>
-<p>Text after __DATA__ may be read via the filehandle
<code>PACKNAME::DATA</code>,
-where <code>PACKNAME</code> is the package that was current when the __DATA__
-token was encountered. The filehandle is left open pointing to the
-line after __DATA__. The program should <code>close DATA</code> when it is
done
-reading from it. (Leaving it open leaks filehandles if the module is
-reloaded for any reason, so it’s a safer practice to close it.) For
-compatibility with older scripts written before __DATA__ was
-introduced, __END__ behaves like __DATA__ in the top level script (but
-not in files loaded with <code>require</code> or <code>do</code>) and leaves
the remaining
-contents of the file accessible via <code>main::DATA</code>.
-</p>
-<p>See <a href="SelfLoader.html#Top">(SelfLoader)</a> for more description of
__DATA__, and
-an example of its use. Note that you cannot read from the DATA
-filehandle in a BEGIN block: the BEGIN block is executed as soon
-as it is seen (during compilation), at which point the corresponding
-__DATA__ (or __END__) token has not yet been seen.
-</p>
-<hr>
-<a name="perldata-Barewords"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-Array-Interpolation" accesskey="n"
rel="next">perldata Array Interpolation</a>, Previous: <a
href="#perldata-Special-Literals" accesskey="p" rel="prev">perldata Special
Literals</a>, Up: <a href="#perldata-Scalar-value-constructors" accesskey="u"
rel="up">perldata Scalar value constructors</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Barewords"></a>
-<h4 class="subsubsection">11.2.5.4 Barewords</h4>
-
-<p>A word that has no other interpretation in the grammar will
-be treated as if it were a quoted string. These are known as
-"barewords". As with filehandles and labels, a bareword that
consists
-entirely of lowercase letters risks conflict with future reserved
-words, and if you use the <code>use warnings</code> pragma or the
<strong>-w</strong> switch,
-Perl will warn you about any such words. Perl limits barewords (like
-identifiers) to about 250 characters. Future versions of Perl are likely
-to eliminate these arbitrary limitations.
-</p>
-<p>Some people may wish to outlaw barewords entirely. If you
-say
-</p>
-<pre class="verbatim"> use strict 'subs';
-</pre>
-<p>then any bareword that would NOT be interpreted as a subroutine call
-produces a compile-time error instead. The restriction lasts to the
-end of the enclosing block. An inner block may countermand this
-by saying <code>no strict 'subs'</code>.
-</p>
-<hr>
-<a name="perldata-Array-Interpolation"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldata-Barewords" accesskey="p" rel="prev">perldata
Barewords</a>, Up: <a href="#perldata-Scalar-value-constructors" accesskey="u"
rel="up">perldata Scalar value constructors</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Array-Interpolation"></a>
-<h4 class="subsubsection">11.2.5.5 Array Interpolation</h4>
-
-<p>Arrays and slices are interpolated into double-quoted strings
-by joining the elements with the delimiter specified in the
<code>$"</code>
-variable (<code>$LIST_SEPARATOR</code> if "use English;" is
specified),
-space by default. The following are equivalent:
-</p>
-<pre class="verbatim"> $temp = join($", @ARGV);
- system "echo $temp";
-
- system "echo @ARGV";
-</pre>
-<p>Within search patterns (which also undergo double-quotish substitution)
-there is an unfortunate ambiguity: Is <code>/$foo[bar]/</code> to be
interpreted as
-<code>/${foo}[bar]/</code> (where <code>[bar]</code> is a character class for
the regular
-expression) or as <code>/${foo[bar]}/</code> (where <code>[bar]</code> is the
subscript to array
address@hidden)? If @foo doesn’t otherwise exist, then it’s
obviously a
-character class. If @foo exists, Perl takes a good guess about
<code>[bar]</code>,
-and is almost always right. If it does guess wrong, or if you’re just
-plain paranoid, you can force the correct interpretation with curly
-braces as above.
-</p>
-<p>If you’re looking for the information on how to use here-documents,
-which used to be here, that’s been moved to
-<a href="#perlop-Quote-and-Quote_002dlike-Operators">perlop Quote and
Quote-like Operators</a>.
-</p>
-<hr>
-<a name="perldata-List-value-constructors"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-Subscripts" accesskey="n" rel="next">perldata
Subscripts</a>, Previous: <a href="#perldata-Scalar-value-constructors"
accesskey="p" rel="prev">perldata Scalar value constructors</a>, Up: <a
href="#perldata-DESCRIPTION" accesskey="u" rel="up">perldata DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="List-value-constructors"></a>
-<h4 class="subsection">11.2.6 List value constructors</h4>
-
-<p>List values are denoted by separating individual values by commas
-(and enclosing the list in parentheses where precedence requires it):
-</p>
-<pre class="verbatim"> (LIST)
-</pre>
-<p>In a context not requiring a list value, the value of what appears
-to be a list literal is simply the value of the final element, as
-with the C comma operator. For example,
-</p>
-<pre class="verbatim"> @foo = ('cc', '-E', $bar);
-</pre>
-<p>assigns the entire list value to array @foo, but
-</p>
-<pre class="verbatim"> $foo = ('cc', '-E', $bar);
-</pre>
-<p>assigns the value of variable $bar to the scalar variable $foo.
-Note that the value of an actual array in scalar context is the
-length of the array; the following assigns the value 3 to $foo:
-</p>
-<pre class="verbatim"> @foo = ('cc', '-E', $bar);
- $foo = @foo; # $foo gets 3
-</pre>
-<p>You may have an optional comma before the closing parenthesis of a
-list literal, so that you can say:
-</p>
-<pre class="verbatim"> @foo = (
- 1,
- 2,
- 3,
- );
-</pre>
-<p>To use a here-document to assign an array, one line per element,
-you might use an approach like this:
-</p>
-<pre class="verbatim"> @sauces = <<End_Lines =~ m/(\S.*\S)/g;
- normal tomato
- spicy tomato
- green chile
- pesto
- white wine
- End_Lines
-</pre>
-<p>LISTs do automatic interpolation of sublists. That is, when a LIST is
-evaluated, each element of the list is evaluated in list context, and
-the resulting list value is interpolated into LIST just as if each
-individual element were a member of LIST. Thus arrays and hashes lose their
-identity in a LIST–the list
-</p>
-<pre class="verbatim"> (@foo,@bar,&SomeSub,%glarch)
-</pre>
-<p>contains all the elements of @foo followed by all the elements of @bar,
-followed by all the elements returned by the subroutine named SomeSub
-called in list context, followed by the key/value pairs of %glarch.
-To make a list reference that does <em>NOT</em> interpolate, see <a
href="#perlref-NAME">perlref NAME</a>.
-</p>
-<p>The null list is represented by (). Interpolating it in a list
-has no effect. Thus ((),(),()) is equivalent to (). Similarly,
-interpolating an array with no elements is the same as if no
-array had been interpolated at that point.
-</p>
-<p>This interpolation combines with the facts that the opening
-and closing parentheses are optional (except when necessary for
-precedence) and lists may end with an optional comma to mean that
-multiple commas within lists are legal syntax. The list <code>1,,3</code> is a
-concatenation of two lists, <code>1,</code> and <code>3</code>, the first of
which ends
-with that optional comma. <code>1,,3</code> is <code>(1,),(3)</code> is
<code>1,3</code> (And
-similarly for <code>1,,,3</code> is <code>(1,),(,),3</code> is
<code>1,3</code> and so on.) Not that
-we’d advise you to use this obfuscation.
-</p>
-<p>A list value may also be subscripted like a normal array. You must
-put the list in parentheses to avoid ambiguity. For example:
-</p>
-<pre class="verbatim"> # Stat returns list value.
- $time = (stat($file))[8];
-
- # SYNTAX ERROR HERE.
- $time = stat($file)[8]; # OOPS, FORGOT PARENTHESES
-
- # Find a hex digit.
- $hexdigit = ('a','b','c','d','e','f')[$digit-10];
-
- # A "reverse comma operator".
- return (pop(@foo),pop(@foo))[0];
-</pre>
-<p>Lists may be assigned to only when each element of the list
-is itself legal to assign to:
-</p>
-<pre class="verbatim"> ($a, $b, $c) = (1, 2, 3);
-
- ($map{'red'}, $map{'blue'}, $map{'green'}) = (0x00f, 0x0f0, 0xf00);
-</pre>
-<p>An exception to this is that you may assign to <code>undef</code> in a list.
-This is useful for throwing away some of the return values of a
-function:
-</p>
-<pre class="verbatim"> ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
-</pre>
-<p>As of Perl 5.22, you can also use <code>(undef)x2</code> instead of
<code>undef, undef</code>.
-(You can also do <code>($x) x 2</code>, which is less useful, because it
assigns to
-the same variable twice, clobbering the first value assigned.)
-</p>
-<p>List assignment in scalar context returns the number of elements
-produced by the expression on the right side of the assignment:
-</p>
-<pre class="verbatim"> $x = (($foo,$bar) = (3,2,1)); # set $x to 3,
not 2
- $x = (($foo,$bar) = f()); # set $x to f()'s return count
-</pre>
-<p>This is handy when you want to do a list assignment in a Boolean
-context, because most list functions return a null list when finished,
-which when assigned produces a 0, which is interpreted as FALSE.
-</p>
-<p>It’s also the source of a useful idiom for executing a function or
-performing an operation in list context and then counting the number of
-return values, by assigning to an empty list and then using that
-assignment in scalar context. For example, this code:
-</p>
-<pre class="verbatim"> $count = () = $string =~ /\d+/g;
-</pre>
-<p>will place into $count the number of digit groups found in $string.
-This happens because the pattern match is in list context (since it
-is being assigned to the empty list), and will therefore return a list
-of all matching parts of the string. The list assignment in scalar
-context will translate that into the number of elements (here, the
-number of times the pattern matched) and assign that to $count. Note
-that simply using
-</p>
-<pre class="verbatim"> $count = $string =~ /\d+/g;
-</pre>
-<p>would not have worked, since a pattern match in scalar context will
-only return true or false, rather than a count of matches.
-</p>
-<p>The final element of a list assignment may be an array or a hash:
-</p>
-<pre class="verbatim"> ($a, $b, @rest) = split;
- my($a, $b, %rest) = @_;
-</pre>
-<p>You can actually put an array or hash anywhere in the list, but the first
one
-in the list will soak up all the values, and anything after it will become
-undefined. This may be useful in a my() or local().
-</p>
-<p>A hash can be initialized using a literal list holding pairs of
-items to be interpreted as a key and a value:
-</p>
-<pre class="verbatim"> # same as map assignment above
- %map = ('red',0x00f,'blue',0x0f0,'green',0xf00);
-</pre>
-<p>While literal lists and named arrays are often interchangeable, that’s
-not the case for hashes. Just because you can subscript a list value like
-a normal array does not mean that you can subscript a list value as a
-hash. Likewise, hashes included as parts of other lists (including
-parameters lists and return lists from functions) always flatten out into
-key/value pairs. That’s why it’s good to use references sometimes.
-</p>
-<p>It is often more readable to use the <code>=></code> operator between
key/value
-pairs. The <code>=></code> operator is mostly just a more visually
distinctive
-synonym for a comma, but it also arranges for its left-hand operand to be
-interpreted as a string if it’s a bareword that would be a legal simple
-identifier. <code>=></code> doesn’t quote compound identifiers, that
contain
-double colons. This makes it nice for initializing hashes:
-</p>
-<pre class="verbatim"> %map = (
- red => 0x00f,
- blue => 0x0f0,
- green => 0xf00,
- );
-</pre>
-<p>or for initializing hash references to be used as records:
-</p>
-<pre class="verbatim"> $rec = {
- witch => 'Mable the Merciless',
- cat => 'Fluffy the Ferocious',
- date => '10/31/1776',
- };
-</pre>
-<p>or for using call-by-named-parameter to complicated functions:
-</p>
-<pre class="verbatim"> $field = $query->radio_group(
- name => 'group_name',
- values => ['eenie','meenie','minie'],
- default => 'meenie',
- linebreak => 'true',
- labels => \%labels
- );
-</pre>
-<p>Note that just because a hash is initialized in that order doesn’t
-mean that it comes out in that order. See ‘perlfunc sort’ for
examples
-of how to arrange for an output ordering.
-</p>
-<p>If a key appears more than once in the initializer list of a hash, the last
-occurrence wins:
-</p>
-<pre class="verbatim"> %circle = (
- center => [5, 10],
- center => [27, 9],
- radius => 100,
- color => [0xDF, 0xFF, 0x00],
- radius => 54,
- );
-
- # same as
- %circle = (
- center => [27, 9],
- color => [0xDF, 0xFF, 0x00],
- radius => 54,
- );
-</pre>
-<p>This can be used to provide overridable configuration defaults:
-</p>
-<pre class="verbatim"> # values in %args take priority over %config_defaults
- %config = (%config_defaults, %args);
-</pre>
-<hr>
-<a name="perldata-Subscripts"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-Multi_002ddimensional-array-emulation" accesskey="n"
rel="next">perldata Multi-dimensional array emulation</a>, Previous: <a
href="#perldata-List-value-constructors" accesskey="p" rel="prev">perldata List
value constructors</a>, Up: <a href="#perldata-DESCRIPTION" accesskey="u"
rel="up">perldata DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Subscripts"></a>
-<h4 class="subsection">11.2.7 Subscripts</h4>
-
-<p>An array can be accessed one scalar at a
-time by specifying a dollar sign (<code>$</code>), then the
-name of the array (without the leading <code>@</code>), then the subscript
inside
-square brackets. For example:
-</p>
-<pre class="verbatim"> @myarray = (5, 50, 500, 5000);
- print "The Third Element is", $myarray[2], "\n";
-</pre>
-<p>The array indices start with 0. A negative subscript retrieves its
-value from the end. In our example, <code>$myarray[-1]</code> would have been
-5000, and <code>$myarray[-2]</code> would have been 500.
-</p>
-<p>Hash subscripts are similar, only instead of square brackets curly brackets
-are used. For example:
-</p>
-<pre class="verbatim"> %scientists =
- (
- "Newton" => "Isaac",
- "Einstein" => "Albert",
- "Darwin" => "Charles",
- "Feynman" => "Richard",
- );
-
- print "Darwin's First Name is ",
$scientists{"Darwin"}, "\n";
-</pre>
-<p>You can also subscript a list to get a single element from it:
-</p>
-<pre class="verbatim"> $dir = (getpwnam("daemon"))[7];
-</pre>
-<hr>
-<a name="perldata-Multi_002ddimensional-array-emulation"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-Slices" accesskey="n" rel="next">perldata Slices</a>,
Previous: <a href="#perldata-Subscripts" accesskey="p" rel="prev">perldata
Subscripts</a>, Up: <a href="#perldata-DESCRIPTION" accesskey="u"
rel="up">perldata DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Multi_002ddimensional-array-emulation"></a>
-<h4 class="subsection">11.2.8 Multi-dimensional array emulation</h4>
-
-<p>Multidimensional arrays may be emulated by subscripting a hash with a
-list. The elements of the list are joined with the subscript separator
-(see <a href="#perlvar-_0024_003b">perlvar $;</a>).
-</p>
-<pre class="verbatim"> $foo{$a,$b,$c}
-</pre>
-<p>is equivalent to
-</p>
-<pre class="verbatim"> $foo{join($;, $a, $b, $c)}
-</pre>
-<p>The default subscript separator is "\034", the same as SUBSEP in
<strong>awk</strong>.
-</p>
-<hr>
-<a name="perldata-Slices"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-Typeglobs-and-Filehandles" accesskey="n"
rel="next">perldata Typeglobs and Filehandles</a>, Previous: <a
href="#perldata-Multi_002ddimensional-array-emulation" accesskey="p"
rel="prev">perldata Multi-dimensional array emulation</a>, Up: <a
href="#perldata-DESCRIPTION" accesskey="u" rel="up">perldata DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Slices"></a>
-<h4 class="subsection">11.2.9 Slices</h4>
-
-<p>A slice accesses several elements of a list, an array, or a hash
-simultaneously using a list of subscripts. It’s more convenient
-than writing out the individual elements as a list of separate
-scalar values.
-</p>
-<pre class="verbatim"> ($him, $her) = @folks[0,-1]; # array
slice
- @them = @folks[0 .. 3]; # array slice
- ($who, $home) = @ENV{"USER", "HOME"}; # hash
slice
- ($uid, $dir) = (getpwnam("daemon"))[2,7]; # list slice
-</pre>
-<p>Since you can assign to a list of variables, you can also assign to
-an array or hash slice.
-</p>
-<pre class="verbatim"> @days[3..5] = qw/Wed Thu Fri/;
- @colors{'red','blue','green'}
- = (0xff0000, 0x0000ff, 0x00ff00);
- @folks[0, -1] = @folks[-1, 0];
-</pre>
-<p>The previous assignments are exactly equivalent to
-</p>
-<pre class="verbatim"> ($days[3], $days[4], $days[5]) = qw/Wed Thu Fri/;
- ($colors{'red'}, $colors{'blue'}, $colors{'green'})
- = (0xff0000, 0x0000ff, 0x00ff00);
- ($folks[0], $folks[-1]) = ($folks[-1], $folks[0]);
-</pre>
-<p>Since changing a slice changes the original array or hash that it’s
-slicing, a <code>foreach</code> construct will alter some–or even
all–of the
-values of the array or hash.
-</p>
-<pre class="verbatim"> foreach (@array[ 4 .. 10 ]) { s/peter/paul/ }
-
- foreach (@hash{qw[key1 key2]}) {
- s/^\s+//; # trim leading whitespace
- s/\s+$//; # trim trailing whitespace
- s/(\w+)/\u\L$1/g; # "titlecase" words
- }
-</pre>
-<p>As a special exception, when you slice a list (but not an array or a hash),
-if the list evaluates to empty, then taking a slice of that empty list will
-always yield the empty list in turn. Thus:
-</p>
-<pre class="verbatim"> @a = ()[0,1]; # @a has no elements
- @b = (@a)[0,1]; # @b has no elements
- @c = (sub{}->())[0,1]; # @c has no elements
- @d = ('a','b')[0,1]; # @d has two elements
- @e = (@d)[0,1,8,9]; # @e has four elements
- @f = (@d)[8,9]; # @f has two elements
-</pre>
-<p>This makes it easy to write loops that terminate when a null list
-is returned:
-</p>
-<pre class="verbatim"> while ( ($home, $user) = (getpwent)[7,0] ) {
- printf "%-8s %s\n", $user, $home;
- }
-</pre>
-<p>As noted earlier in this document, the scalar sense of list assignment
-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.
-</p>
-<p>Slices in scalar context return the last item of the slice.
-</p>
-<pre class="verbatim"> @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'
-</pre>
-<p>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.
-On the other hand, the leading symbol (’$’ or ’@’) on
the array or
-hash indicates whether you are getting back a singular value (a
-scalar) or a plural one (a list).
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perldata-Key_002fValue-Hash-Slices" accesskey="1">perldata Key/Value
Hash Slices</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldata-Index_002fValue-Array-Slices" accesskey="2">perldata
Index/Value Array Slices</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldata-Key_002fValue-Hash-Slices"></a>
-<div class="header">
-<p>
-Next: <a href="#perldata-Index_002fValue-Array-Slices" accesskey="n"
rel="next">perldata Index/Value Array Slices</a>, Up: <a
href="#perldata-Slices" accesskey="u" rel="up">perldata Slices</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Key_002fValue-Hash-Slices"></a>
-<h4 class="subsubsection">11.2.9.1 Key/Value Hash Slices</h4>
-
-<p>Starting in Perl 5.20, a hash slice operation
-with the % symbol is a variant of slice operation
-returning a list of key/value pairs rather than just values:
-</p>
-<pre class="verbatim"> %h = (blonk => 2, foo => 3, squink => 5,
bar => 8);
- %subset = %h{'foo', 'bar'}; # key/value hash slice
- # %subset is now (foo => 3, bar => 8)
-</pre>
-<p>However, the result of such a slice cannot be localized, deleted or used
-in assignment. These are otherwise very much consistent with hash slices
-using the @ symbol.
-</p>
-<hr>
-<a name="perldata-Index_002fValue-Array-Slices"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldata-Key_002fValue-Hash-Slices" accesskey="p"
rel="prev">perldata Key/Value Hash Slices</a>, Up: <a href="#perldata-Slices"
accesskey="u" rel="up">perldata Slices</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Index_002fValue-Array-Slices"></a>
-<h4 class="subsubsection">11.2.9.2 Index/Value Array Slices</h4>
-
-<p>Similar to key/value hash slices (and also introduced
-in Perl 5.20), the % array slice syntax returns a list
-of index/value pairs:
-</p>
-<pre class="verbatim"> @a = "a".."z";
- @list = %a[3,4,6];
- # @list is now (3, "d", 4, "e", 6, "g")
-</pre>
-<hr>
-<a name="perldata-Typeglobs-and-Filehandles"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldata-Slices" accesskey="p" rel="prev">perldata
Slices</a>, Up: <a href="#perldata-DESCRIPTION" accesskey="u" rel="up">perldata
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Typeglobs-and-Filehandles"></a>
-<h4 class="subsection">11.2.10 Typeglobs and Filehandles</h4>
-
-<p>Perl uses an internal type called a <em>typeglob</em> to hold an entire
-symbol table entry. The type prefix of a typeglob is a <code>*</code>, because
-it represents all types. This used to be the preferred way to
-pass arrays and hashes by reference into a function, but now that
-we have real references, this is seldom needed.
-</p>
-<p>The main use of typeglobs in modern Perl is create symbol table aliases.
-This assignment:
-</p>
-<pre class="verbatim"> *this = *that;
-</pre>
-<p>makes $this an alias for $that, @this an alias for @that, %this an alias
-for %that, &this an alias for &that, etc. Much safer is to use a
reference.
-This:
-</p>
-<pre class="verbatim"> local *Here::blue = \$There::green;
-</pre>
-<p>temporarily makes $Here::blue an alias for $There::green, but doesn’t
-make @Here::blue an alias for @There::green, or %Here::blue an alias for
-%There::green, etc. See <a href="#perlmod-Symbol-Tables">perlmod Symbol
Tables</a> for more examples
-of this. Strange though this may seem, this is the basis for the whole
-module import/export system.
-</p>
-<p>Another use for typeglobs is to pass filehandles into a function or
-to create new filehandles. If you need to use a typeglob to save away
-a filehandle, do it this way:
-</p>
-<pre class="verbatim"> $fh = *STDOUT;
-</pre>
-<p>or perhaps as a real reference, like this:
-</p>
-<pre class="verbatim"> $fh = \*STDOUT;
-</pre>
-<p>See <a href="#perlsub-NAME">perlsub NAME</a> for examples of using these as
indirect filehandles
-in functions.
-</p>
-<p>Typeglobs are also a way to create a local filehandle using the local()
-operator. These last until their block is exited, but may be passed back.
-For example:
-</p>
-<pre class="verbatim"> sub newopen {
- my $path = shift;
- local *FH; # not my!
- open (FH, $path) or return undef;
- return *FH;
- }
- $fh = newopen('/etc/passwd');
-</pre>
-<p>Now that we have the <code>*foo{THING}</code> notation, typeglobs
aren’t used as much
-for filehandle manipulations, although they’re still needed to pass brand
-new file and directory handles into or out of functions. That’s because
-<code>*HANDLE{IO}</code> only works if HANDLE has already been used as a
handle.
-In other words, <code>*FH</code> must be used to create new symbol table
entries;
-<code>*foo{THING}</code> cannot. When in doubt, use <code>*FH</code>.
-</p>
-<p>All functions that are capable of creating filehandles (open(),
-opendir(), pipe(), socketpair(), sysopen(), socket(), and accept())
-automatically create an anonymous filehandle if the handle passed to
-them is an uninitialized scalar variable. This allows the constructs
-such as <code>open(my $fh, ...)</code> and <code>open(local $fh,...)</code> to
be used to
-create filehandles that will conveniently be closed automatically when
-the scope ends, provided there are no other references to them. This
-largely eliminates the need for typeglobs when opening filehandles
-that must be passed around, as in the following example:
-</p>
-<pre class="verbatim"> sub myopen {
- open my $fh, "@_"
- or die "Can't open '@_': $!";
- return $fh;
- }
-
- {
- my $f = myopen("</etc/motd");
- print <$f>;
- # $f implicitly closed here
- }
-</pre>
-<p>Note that if an initialized scalar variable is used instead the
-result is different: <code>my $fh='zzz'; open($fh, ...)</code> is equivalent
-to <code>open( *{'zzz'}, ...)</code>.
-<code>use strict 'refs'</code> forbids such practice.
-</p>
-<p>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 ‘perlfunc open’ for an
-example.
-</p>
-<hr>
-<a name="perldata-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldata-DESCRIPTION" accesskey="p" rel="prev">perldata
DESCRIPTION</a>, Up: <a href="#perldata" accesskey="u" rel="up">perldata</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-4"></a>
-<h3 class="section">11.3 SEE ALSO</h3>
-
-<p>See <a href="#perlvar-NAME">perlvar NAME</a> for a description of
Perl’s built-in variables and
-a discussion of legal variable names. See <a href="#perlref-NAME">perlref
NAME</a>, <a href="#perlsub-NAME">perlsub NAME</a>,
-and <a href="#perlmod-Symbol-Tables">perlmod Symbol Tables</a> for more
discussion on typeglobs and
-the <code>*foo{THING}</code> syntax.
-</p>
-<hr>
-<a name="perldbmfilter"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebguts" accesskey="n" rel="next">perldebguts</a>,
Previous: <a href="#perldata" accesskey="p" rel="prev">perldata</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perldbmfilter-1"></a>
-<h2 class="chapter">12 perldbmfilter</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perldbmfilter-NAME"
accesskey="1">perldbmfilter NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldbmfilter-SYNOPSIS"
accesskey="2">perldbmfilter SYNOPSIS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldbmfilter-DESCRIPTION"
accesskey="3">perldbmfilter DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldbmfilter-SEE-ALSO"
accesskey="4">perldbmfilter SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldbmfilter-AUTHOR"
accesskey="5">perldbmfilter AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldbmfilter-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perldbmfilter-SYNOPSIS" accesskey="n" rel="next">perldbmfilter
SYNOPSIS</a>, Up: <a href="#perldbmfilter" accesskey="u"
rel="up">perldbmfilter</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-11"></a>
-<h3 class="section">12.1 NAME</h3>
-
-<p>perldbmfilter - Perl DBM Filters
-</p>
-<hr>
-<a name="perldbmfilter-SYNOPSIS"></a>
-<div class="header">
-<p>
-Next: <a href="#perldbmfilter-DESCRIPTION" accesskey="n"
rel="next">perldbmfilter DESCRIPTION</a>, Previous: <a
href="#perldbmfilter-NAME" accesskey="p" rel="prev">perldbmfilter NAME</a>, Up:
<a href="#perldbmfilter" accesskey="u" rel="up">perldbmfilter</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SYNOPSIS-3"></a>
-<h3 class="section">12.2 SYNOPSIS</h3>
-
-<pre class="verbatim"> $db = tie %hash, 'DBM', ...
-
- $old_filter = $db->filter_store_key ( sub { ... } );
- $old_filter = $db->filter_store_value( sub { ... } );
- $old_filter = $db->filter_fetch_key ( sub { ... } );
- $old_filter = $db->filter_fetch_value( sub { ... } );
-</pre>
-<hr>
-<a name="perldbmfilter-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perldbmfilter-SEE-ALSO" accesskey="n" rel="next">perldbmfilter
SEE ALSO</a>, Previous: <a href="#perldbmfilter-SYNOPSIS" accesskey="p"
rel="prev">perldbmfilter SYNOPSIS</a>, Up: <a href="#perldbmfilter"
accesskey="u" rel="up">perldbmfilter</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-11"></a>
-<h3 class="section">12.3 DESCRIPTION</h3>
-
-<p>The four <code>filter_*</code> 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.
-</p>
-<p>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.
-</p>
-<p>To summarise:
-</p>
-<dl compact="compact">
-<dt><strong>filter_store_key</strong></dt>
-<dd><a name="perldbmfilter-filter_005fstore_005fkey"></a>
-<p>If a filter has been installed with this method, it will be invoked
-every time you write a key to a DBM database.
-</p>
-</dd>
-<dt><strong>filter_store_value</strong></dt>
-<dd><a name="perldbmfilter-filter_005fstore_005fvalue"></a>
-<p>If a filter has been installed with this method, it will be invoked
-every time you write a value to a DBM database.
-</p>
-</dd>
-<dt><strong>filter_fetch_key</strong></dt>
-<dd><a name="perldbmfilter-filter_005ffetch_005fkey"></a>
-<p>If a filter has been installed with this method, it will be invoked
-every time you read a key from a DBM database.
-</p>
-</dd>
-<dt><strong>filter_fetch_value</strong></dt>
-<dd><a name="perldbmfilter-filter_005ffetch_005fvalue"></a>
-<p>If a filter has been installed with this method, it will be invoked
-every time you read a value from a DBM database.
-</p>
-</dd>
-</dl>
-
-<p>You can use any combination of the methods from none to all four.
-</p>
-<p>All filter methods return the existing filter, if present, or
<code>undef</code>
-if not.
-</p>
-<p>To delete a filter pass <code>undef</code> to it.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perldbmfilter-The-Filter"
accesskey="1">perldbmfilter The Filter</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldbmfilter-An-Example_003a-the-NULL-termination-problem_002e"
accesskey="2">perldbmfilter An Example: the NULL termination
problem.</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldbmfilter-Another-Example_003a-Key-is-a-C-int_002e"
accesskey="3">perldbmfilter Another Example: Key is a C
int.</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldbmfilter-The-Filter"></a>
-<div class="header">
-<p>
-Next: <a
href="#perldbmfilter-An-Example_003a-the-NULL-termination-problem_002e"
accesskey="n" rel="next">perldbmfilter An Example: the NULL termination
problem.</a>, Up: <a href="#perldbmfilter-DESCRIPTION" accesskey="u"
rel="up">perldbmfilter DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-Filter"></a>
-<h4 class="subsection">12.3.1 The Filter</h4>
-
-<p>When each filter is called by Perl, a local copy of <code>$_</code> will
contain
-the key or value to be filtered. Filtering is achieved by modifying
-the contents of <code>$_</code>. The return code from the filter is ignored.
-</p>
-<hr>
-<a name="perldbmfilter-An-Example_003a-the-NULL-termination-problem_002e"></a>
-<div class="header">
-<p>
-Next: <a href="#perldbmfilter-Another-Example_003a-Key-is-a-C-int_002e"
accesskey="n" rel="next">perldbmfilter Another Example: Key is a C int.</a>,
Previous: <a href="#perldbmfilter-The-Filter" accesskey="p"
rel="prev">perldbmfilter The Filter</a>, Up: <a
href="#perldbmfilter-DESCRIPTION" accesskey="u" rel="up">perldbmfilter
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="An-Example_003a-the-NULL-termination-problem_002e"></a>
-<h4 class="subsection">12.3.2 An Example: the NULL termination problem.</h4>
-
-<p>DBM Filters are useful for a class of problems where you <em>always</em>
-want to make the same transformation to all keys, all values or both.
-</p>
-<p>For example, consider the following scenario. You have a DBM database
-that you need to share with a third-party C application. The C application
-assumes that <em>all</em> keys and values are NULL terminated. Unfortunately
-when Perl writes to DBM databases it doesn’t use NULL termination, so
-your Perl application will have to manage NULL termination itself. When
-you write to the database you will have to use something like this:
-</p>
-<pre class="verbatim"> $hash{"$key\0"} = "$value\0";
-</pre>
-<p>Similarly the NULL needs to be taken into account when you are considering
-the length of existing keys/values.
-</p>
-<p>It would be much better if you could ignore the NULL terminations issue
-in the main application code and have a mechanism that automatically
-added the terminating NULL to all keys and values whenever you write to
-the database and have them removed when you read from the database. As
I’m
-sure you have already guessed, this is a problem that DBM Filters can
-fix very easily.
-</p>
-<pre class="verbatim"> use strict;
- use warnings;
- use SDBM_File;
- use Fcntl;
-
- my %hash;
- my $filename = "filt";
- unlink $filename;
-
- my $db = tie(%hash, 'SDBM_File', $filename, O_RDWR|O_CREAT, 0640)
- or die "Cannot open $filename: $!\n";
-
- # Install DBM Filters
- $db->filter_fetch_key ( sub { s/\0$// } );
- $db->filter_store_key ( sub { $_ .= "\0" } );
- $db->filter_fetch_value(
- sub { no warnings 'uninitialized'; s/\0$// } );
- $db->filter_store_value( sub { $_ .= "\0" } );
-
- $hash{"abc"} = "def";
- my $a = $hash{"ABC"};
- # ...
- undef $db;
- untie %hash;
-</pre>
-<p>The code above uses SDBM_File, but it will work with any of the DBM
-modules.
-</p>
-<p>Hopefully the contents of each of the filters should be
-self-explanatory. Both "fetch" filters remove the terminating NULL,
-and both "store" filters add a terminating NULL.
-</p>
-<hr>
-<a name="perldbmfilter-Another-Example_003a-Key-is-a-C-int_002e"></a>
-<div class="header">
-<p>
-Previous: <a
href="#perldbmfilter-An-Example_003a-the-NULL-termination-problem_002e"
accesskey="p" rel="prev">perldbmfilter An Example: the NULL termination
problem.</a>, Up: <a href="#perldbmfilter-DESCRIPTION" accesskey="u"
rel="up">perldbmfilter DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Another-Example_003a-Key-is-a-C-int_002e"></a>
-<h4 class="subsection">12.3.3 Another Example: Key is a C int.</h4>
-
-<p>Here is another real-life example. By default, whenever Perl writes to
-a DBM database it always writes the key and value as strings. So when
-you use this:
-</p>
-<pre class="verbatim"> $hash{12345} = "something";
-</pre>
-<p>the key 12345 will get stored in the DBM database as the 5 byte string
-"12345". If you actually want the key to be stored in the DBM
database
-as a C int, you will have to use <code>pack</code> when writing, and
<code>unpack</code>
-when reading.
-</p>
-<p>Here is a DBM Filter that does it:
-</p>
-<pre class="verbatim"> use strict;
- use warnings;
- use DB_File;
- my %hash;
- my $filename = "filt";
- unlink $filename;
-
-
- my $db = tie %hash, 'DB_File', $filename, O_CREAT|O_RDWR, 0666,
- $DB_HASH or die "Cannot open $filename: $!\n";
-
- $db->filter_fetch_key ( sub { $_ = unpack("i", $_) } );
- $db->filter_store_key ( sub { $_ = pack ("i", $_) } );
- $hash{123} = "def";
- # ...
- undef $db;
- untie %hash;
-</pre>
-<p>The code above uses DB_File, but again it will work with any of the
-DBM modules.
-</p>
-<p>This time only two filters have been used; we only need to manipulate
-the contents of the key, so it wasn’t necessary to install any value
-filters.
-</p>
-<hr>
-<a name="perldbmfilter-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perldbmfilter-AUTHOR" accesskey="n" rel="next">perldbmfilter
AUTHOR</a>, Previous: <a href="#perldbmfilter-DESCRIPTION" accesskey="p"
rel="prev">perldbmfilter DESCRIPTION</a>, Up: <a href="#perldbmfilter"
accesskey="u" rel="up">perldbmfilter</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-5"></a>
-<h3 class="section">12.4 SEE ALSO</h3>
-
-<p><a href="DB_File.html#Top">(DB_File)</a>, <a
href="GDBM_File.html#Top">(GDBM_File)</a>, <a
href="NDBM_File.html#Top">(NDBM_File)</a>, <a
href="ODBM_File.html#Top">(ODBM_File)</a> and <a
href="SDBM_File.html#Top">(SDBM_File)</a>.
-</p>
-<hr>
-<a name="perldbmfilter-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldbmfilter-SEE-ALSO" accesskey="p"
rel="prev">perldbmfilter SEE ALSO</a>, Up: <a href="#perldbmfilter"
accesskey="u" rel="up">perldbmfilter</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-4"></a>
-<h3 class="section">12.5 AUTHOR</h3>
-
-<p>Paul Marquess
-</p>
-<hr>
-<a name="perldebguts"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut" accesskey="n" rel="next">perldebtut</a>, Previous:
<a href="#perldbmfilter" accesskey="p" rel="prev">perldbmfilter</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perldebguts-1"></a>
-<h2 class="chapter">13 perldebguts</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perldebguts-NAME"
accesskey="1">perldebguts NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebguts-DESCRIPTION"
accesskey="2">perldebguts DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Debugger-Internals" accesskey="3">perldebguts Debugger
Internals</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Frame-Listing-Output-Examples" accesskey="4">perldebguts
Frame Listing Output Examples</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Debugging-Regular-Expressions" accesskey="5">perldebguts
Debugging Regular Expressions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Debugging-Perl-Memory-Usage" accesskey="6">perldebguts
Debugging Perl Memory Usage</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebguts-SEE-ALSO"
accesskey="7">perldebguts SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldebguts-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebguts-DESCRIPTION" accesskey="n" rel="next">perldebguts
DESCRIPTION</a>, Up: <a href="#perldebguts" accesskey="u"
rel="up">perldebguts</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-12"></a>
-<h3 class="section">13.1 NAME</h3>
-
-<p>perldebguts - Guts of Perl debugging
-</p>
-<hr>
-<a name="perldebguts-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebguts-Debugger-Internals" accesskey="n"
rel="next">perldebguts Debugger Internals</a>, Previous: <a
href="#perldebguts-NAME" accesskey="p" rel="prev">perldebguts NAME</a>, Up: <a
href="#perldebguts" accesskey="u" rel="up">perldebguts</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-12"></a>
-<h3 class="section">13.2 DESCRIPTION</h3>
-
-<p>This is not <a href="#perldebug-NAME">perldebug NAME</a>, which tells you
how to use
-the debugger. This manpage describes low-level details concerning
-the debugger’s internals, which range from difficult to impossible
-to understand for anyone who isn’t incredibly intimate with Perl’s
guts.
-Caveat lector.
-</p>
-<hr>
-<a name="perldebguts-Debugger-Internals"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebguts-Frame-Listing-Output-Examples" accesskey="n"
rel="next">perldebguts Frame Listing Output Examples</a>, Previous: <a
href="#perldebguts-DESCRIPTION" accesskey="p" rel="prev">perldebguts
DESCRIPTION</a>, Up: <a href="#perldebguts" accesskey="u"
rel="up">perldebguts</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Debugger-Internals"></a>
-<h3 class="section">13.3 Debugger Internals</h3>
-
-<p>Perl has special debugging hooks at compile-time and run-time used
-to create debugging environments. These hooks are not to be confused
-with the <em>perl -Dxxx</em> command described in <a
href="#perlrun-NAME">perlrun NAME</a>, which is
-usable only if a special Perl is built per the instructions in the
-<samp>INSTALL</samp> podpage in the Perl source tree.
-</p>
-<p>For example, whenever you call Perl’s built-in <code>caller</code>
function
-from the package <code>DB</code>, the arguments that the corresponding stack
-frame was called with are copied to the <code>@DB::args</code> array. These
-mechanisms are enabled by calling Perl with the <strong>-d</strong> switch.
-Specifically, the following additional features are enabled
-(cf. <a href="#perlvar-_0024_005eP">perlvar $^P</a>):
-</p>
-<ul>
-<li> Perl inserts the contents of <code>$ENV{PERL5DB}</code> (or <code>BEGIN
{require
-'perl5db.pl'}</code> if not present) before the first line of your program.
-
-</li><li> Each array <code>@{"_<$filename"}</code> holds the
lines of $filename for a
-file compiled by Perl. The same is also true for <code>eval</code>ed strings
-that contain subroutines, or which are currently being executed.
-The $filename for <code>eval</code>ed strings looks like <code>(eval
34)</code>.
-
-<p>Values in this array are magical in numeric context: they compare
-equal to zero only if the line is not breakable.
-</p>
-</li><li> Each hash <code>%{"_<$filename"}</code> contains
breakpoints and actions keyed
-by line number. Individual entries (as opposed to the whole hash)
-are settable. Perl only cares about Boolean true here, although
-the values used by <samp>perl5db.pl</samp> have the form
-<code>"$break_condition\0$action"</code>.
-
-<p>The same holds for evaluated strings that contain subroutines, or
-which are currently being executed. The $filename for <code>eval</code>ed
strings
-looks like <code>(eval 34)</code>.
-</p>
-</li><li> Each scalar <code>${"_<$filename"}</code> contains
<code>"_<$filename"</code>. This is
-also the case for evaluated strings that contain subroutines, or
-which are currently being executed. The $filename for <code>eval</code>ed
-strings looks like <code>(eval 34)</code>.
-
-</li><li> After each <code>require</code>d file is compiled, but before it is
executed,
-<code>DB::postponed(*{"_<$filename"})</code> is called if the
subroutine
-<code>DB::postponed</code> exists. Here, the $filename is the expanded name of
-the <code>require</code>d file, as found in the values of %INC.
-
-</li><li> After each subroutine <code>subname</code> is compiled, the
existence of
-<code>$DB::postponed{subname}</code> is checked. If this key exists,
-<code>DB::postponed(subname)</code> is called if the
<code>DB::postponed</code> subroutine
-also exists.
-
-</li><li> A hash <code>%DB::sub</code> is maintained, whose keys are
subroutine names
-and whose values have the form <code>filename:startline-endline</code>.
-<code>filename</code> has the form <code>(eval 34)</code> for subroutines
defined inside
-<code>eval</code>s.
-
-</li><li> When the execution of your program reaches a point that can hold a
-breakpoint, the <code>DB::DB()</code> subroutine is called if any of the
variables
-<code>$DB::trace</code>, <code>$DB::single</code>, or <code>$DB::signal</code>
is true. These variables
-are not <code>local</code>izable. This feature is disabled when executing
-inside <code>DB::DB()</code>, including functions called from it
-unless <code>$^D & (1<<30)</code> is true.
-
-</li><li> When execution of the program reaches a subroutine call, a call to
-<code>&DB::sub</code>(<em>args</em>) is made instead, with
<code>$DB::sub</code> holding the
-name of the called subroutine. (This doesn’t happen if the subroutine
-was compiled in the <code>DB</code> package.)
-
-<p>If the call is to an lvalue subroutine, and <code>&DB::lsub</code>
-is defined <code>&DB::lsub</code>(<em>args</em>) is called instead,
otherwise falling
-back to <code>&DB::sub</code>(<em>args</em>).
-</p>
-</li><li> When execution of the program uses <code>goto</code> to enter a
non-XS
-subroutine and the 0x80 bit is set in <code>$^P</code>, a call to
<code>&DB::goto</code>
-is made, with <code>$DB::sub</code> holding the name of the subroutine being
-entered.
-
-</li></ul>
-
-<p>Note that if <code>&DB::sub</code> needs external data for it to work,
no
-subroutine call is possible without it. As an example, the standard
-debugger’s <code>&DB::sub</code> depends on the
<code>$DB::deep</code> variable
-(it defines how many levels of recursion deep into the debugger you can go
-before a mandatory break). If <code>$DB::deep</code> is not defined,
subroutine
-calls are not possible, even though <code>&DB::sub</code> exists.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Writing-Your-Own-Debugger" accesskey="1">perldebguts Writing
Your Own Debugger</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldebguts-Writing-Your-Own-Debugger"></a>
-<div class="header">
-<p>
-Up: <a href="#perldebguts-Debugger-Internals" accesskey="u"
rel="up">perldebguts Debugger Internals</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Writing-Your-Own-Debugger"></a>
-<h4 class="subsection">13.3.1 Writing Your Own Debugger</h4>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Environment-Variables" accesskey="1">perldebguts Environment
Variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Debugger-Internal-Variables" accesskey="2">perldebguts
Debugger Internal Variables</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Debugger-Customization-Functions" accesskey="3">perldebguts
Debugger Customization Functions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldebguts-Environment-Variables"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebguts-Debugger-Internal-Variables" accesskey="n"
rel="next">perldebguts Debugger Internal Variables</a>, Up: <a
href="#perldebguts-Writing-Your-Own-Debugger" accesskey="u"
rel="up">perldebguts Writing Your Own Debugger</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Environment-Variables"></a>
-<h4 class="subsubsection">13.3.1.1 Environment Variables</h4>
-
-<p>The <code>PERL5DB</code> environment variable can be used to define a
debugger.
-For example, the minimal "working" debugger (it actually
doesn’t do anything)
-consists of one line:
-</p>
-<pre class="verbatim"> sub DB::DB {}
-</pre>
-<p>It can easily be defined like this:
-</p>
-<pre class="verbatim"> $ PERL5DB="sub DB::DB {}" perl -d your-script
-</pre>
-<p>Another brief debugger, slightly more useful, can be created
-with only the line:
-</p>
-<pre class="verbatim"> sub DB::DB {print ++$i; scalar <STDIN>}
-</pre>
-<p>This debugger prints a number which increments for each statement
-encountered and waits for you to hit a newline before continuing
-to the next statement.
-</p>
-<p>The following debugger is actually useful:
-</p>
-<pre class="verbatim"> {
- package DB;
- sub DB {}
- sub sub {print ++$i, " $sub\n"; &$sub}
- }
-</pre>
-<p>It prints the sequence number of each subroutine call and the name of the
-called subroutine. Note that <code>&DB::sub</code> is being compiled into
the
-package <code>DB</code> through the use of the <code>package</code> directive.
-</p>
-<p>When it starts, the debugger reads your rc file (<samp>./.perldb</samp> or
-<samp>~/.perldb</samp> under Unix), which can set important options.
-(A subroutine (<code>&afterinit</code>) can be defined here as well; it is
executed
-after the debugger completes its own initialization.)
-</p>
-<p>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 <code>o ...</code> debugger command (q.v. in <a
href="#perldebug-Configurable-Options">perldebug Configurable Options</a>).
-</p>
-<hr>
-<a name="perldebguts-Debugger-Internal-Variables"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebguts-Debugger-Customization-Functions" accesskey="n"
rel="next">perldebguts Debugger Customization Functions</a>, Previous: <a
href="#perldebguts-Environment-Variables" accesskey="p" rel="prev">perldebguts
Environment Variables</a>, Up: <a href="#perldebguts-Writing-Your-Own-Debugger"
accesskey="u" rel="up">perldebguts Writing Your Own Debugger</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Debugger-Internal-Variables"></a>
-<h4 class="subsubsection">13.3.1.2 Debugger Internal Variables</h4>
-
-<p>In addition to the file and subroutine-related variables mentioned above,
-the debugger also maintains various magical internal variables.
-</p>
-<ul>
-<li> <code>@DB::dbline</code> is an alias for
<code>@{"::_<current_file"}</code>, which
-holds the lines of the currently-selected file (compiled by Perl), either
-explicitly chosen with the debugger’s <code>f</code> command, or
implicitly by flow
-of execution.
-
-<p>Values in this array are magical in numeric context: they compare
-equal to zero only if the line is not breakable.
-</p>
-</li><li> <code>%DB::dbline</code> is an alias for
<code>%{"::_<current_file"}</code>, which
-contains breakpoints and actions keyed by line number in
-the currently-selected file, either explicitly chosen with the
-debugger’s <code>f</code> command, or implicitly by flow of execution.
-
-<p>As previously noted, individual entries (as opposed to the whole hash)
-are settable. Perl only cares about Boolean true here, although
-the values used by <samp>perl5db.pl</samp> have the form
-<code>"$break_condition\0$action"</code>.
-</p>
-</li></ul>
-
-<hr>
-<a name="perldebguts-Debugger-Customization-Functions"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldebguts-Debugger-Internal-Variables" accesskey="p"
rel="prev">perldebguts Debugger Internal Variables</a>, Up: <a
href="#perldebguts-Writing-Your-Own-Debugger" accesskey="u"
rel="up">perldebguts Writing Your Own Debugger</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Debugger-Customization-Functions"></a>
-<h4 class="subsubsection">13.3.1.3 Debugger Customization Functions</h4>
-
-<p>Some functions are provided to simplify customization.
-</p>
-<ul>
-<li> See <a href="#perldebug-Configurable-Options">perldebug Configurable
Options</a> for a description of options parsed by
-<code>DB::parse_options(string)</code>.
-
-</li><li> <code>DB::dump_trace(skip[,count])</code> skips the specified number
of frames
-and returns a list containing information about the calling frames (all
-of them, if <code>count</code> is missing). Each entry is reference to a hash
-with keys <code>context</code> (either <code>.</code>, <code>$</code>, or
<code>@</code>), <code>sub</code> (subroutine
-name, or info about <code>eval</code>), <code>args</code> (<code>undef</code>
or a reference to
-an array), <code>file</code>, and <code>line</code>.
-
-</li><li> <code>DB::print_trace(FH, skip[, count[, short]])</code> prints
-formatted info about caller frames. The last two functions may be
-convenient as arguments to <code><</code>, <code><<</code> commands.
-
-</li></ul>
-
-<p>Note that any variables and functions that are not documented in
-this manpages (or in <a href="#perldebug-NAME">perldebug NAME</a>) are
considered for internal
-use only, and as such are subject to change without notice.
-</p>
-<hr>
-<a name="perldebguts-Frame-Listing-Output-Examples"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebguts-Debugging-Regular-Expressions" accesskey="n"
rel="next">perldebguts Debugging Regular Expressions</a>, Previous: <a
href="#perldebguts-Debugger-Internals" accesskey="p" rel="prev">perldebguts
Debugger Internals</a>, Up: <a href="#perldebguts" accesskey="u"
rel="up">perldebguts</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Frame-Listing-Output-Examples"></a>
-<h3 class="section">13.4 Frame Listing Output Examples</h3>
-
-<p>The <code>frame</code> option can be used to control the output of frame
-information. For example, contrast this expression trace:
-</p>
-<pre class="verbatim"> $ perl -de 42
- Stack dump during die enabled outside of evals.
-
- Loading DB routines from perl5db.pl patch level 0.94
- Emacs support available.
-
- Enter h or 'h h' for help.
-
- main::(-e:1): 0
- DB<1> sub foo { 14 }
-
- DB<2> sub bar { 3 }
-
- DB<3> t print foo() * bar()
- main::((eval 172):3): print foo() + bar();
- main::foo((eval 168):2):
- main::bar((eval 170):2):
- 42
-</pre>
-<p>with this one, once the <code>o</code>ption <code>frame=2</code> has been
set:
-</p>
-<pre class="verbatim"> DB<4> o f=2
- frame = '2'
- DB<5> t print foo() * bar()
- 3: foo() * bar()
- entering main::foo
- 2: sub foo { 14 };
- exited main::foo
- entering main::bar
- 2: sub bar { 3 };
- exited main::bar
- 42
-</pre>
-<p>By way of demonstration, we present below a laborious listing
-resulting from setting your <code>PERLDB_OPTS</code> environment variable to
-the value <code>f=n N</code>, and running <em>perl -d -V</em> from the command
line.
-Examples using various values of <code>n</code> 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.
-</p>
-<ol>
-<li>
-<pre class="verbatim"> entering main::BEGIN
- entering Config::BEGIN
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- Package lib/Config.pm.
- entering Config::TIEHASH
- entering Exporter::import
- entering Exporter::export
- entering Config::myconfig
- entering Config::FETCH
- entering Config::FETCH
- entering Config::FETCH
- entering Config::FETCH
-</pre>
-</li><li>
-<pre class="verbatim"> entering main::BEGIN
- entering Config::BEGIN
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- exited Config::BEGIN
- Package lib/Config.pm.
- entering Config::TIEHASH
- exited Config::TIEHASH
- entering Exporter::import
- entering Exporter::export
- exited Exporter::export
- exited Exporter::import
- exited main::BEGIN
- entering Config::myconfig
- entering Config::FETCH
- exited Config::FETCH
- entering Config::FETCH
- exited Config::FETCH
- entering Config::FETCH
-</pre>
-</li><li>
-<pre class="verbatim"> in $=main::BEGIN() from /dev/null:0
- in $=Config::BEGIN() from lib/Config.pm:2
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- Package lib/Config.pm.
- in $=Config::TIEHASH('Config') from lib/Config.pm:644
- in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
- in @=Config::myconfig() from /dev/null:0
- in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574
-</pre>
-</li><li>
-<pre class="verbatim"> in $=main::BEGIN() from /dev/null:0
- in $=Config::BEGIN() from lib/Config.pm:2
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- out $=Config::BEGIN() from lib/Config.pm:0
- Package lib/Config.pm.
- in $=Config::TIEHASH('Config') from lib/Config.pm:644
- out $=Config::TIEHASH('Config') from lib/Config.pm:644
- in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from
lib/
- out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from
lib/
- out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- out $=main::BEGIN() from /dev/null:0
- in @=Config::myconfig() from /dev/null:0
- in $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
- out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
- out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
- out $=Config::FETCH(ref(Config), 'PERL_VERSION') from lib/Config.pm:574
- in $=Config::FETCH(ref(Config), 'PERL_SUBVERSION') from lib/Config.pm:574
-</pre>
-</li><li>
-<pre class="verbatim"> in $=main::BEGIN() from /dev/null:0
- in $=Config::BEGIN() from lib/Config.pm:2
- Package lib/Exporter.pm.
- Package lib/Carp.pm.
- out $=Config::BEGIN() from lib/Config.pm:0
- Package lib/Config.pm.
- in $=Config::TIEHASH('Config') from lib/Config.pm:644
- out $=Config::TIEHASH('Config') from lib/Config.pm:644
- in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from
lib/E
- out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from
lib/E
- out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- out $=main::BEGIN() from /dev/null:0
- in @=Config::myconfig() from /dev/null:0
- in $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from
lib/Config.pm:574
- out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from
lib/Config.pm:574
- in $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from
lib/Config.pm:574
- out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from
lib/Config.pm:574
-</pre>
-</li><li>
-<pre class="verbatim"> in $=CODE(0x15eca4)() from /dev/null:0
- in $=CODE(0x182528)() from lib/Config.pm:2
- Package lib/Exporter.pm.
- out $=CODE(0x182528)() from lib/Config.pm:0
- scalar context return from CODE(0x182528): undef
- Package lib/Config.pm.
- in $=Config::TIEHASH('Config') from lib/Config.pm:628
- out $=Config::TIEHASH('Config') from lib/Config.pm:628
- scalar context return from Config::TIEHASH: empty hash
- in $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- in $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from
lib/Exporter.pm:171
- out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from
lib/Exporter.pm:171
- scalar context return from Exporter::export: ''
- out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/null:0
- scalar context return from Exporter::import: ''
-</pre>
-</li></ol>
-
-<p>In all cases shown above, the line indentation shows the call tree.
-If bit 2 of <code>frame</code> is set, a line is printed on exit from a
-subroutine as well. If bit 4 is set, the arguments are printed
-along with the caller info. If bit 8 is set, the arguments are
-printed even if they are tied or references. If bit 16 is set, the
-return value is printed, too.
-</p>
-<p>When a package is compiled, a line like this
-</p>
-<pre class="verbatim"> Package lib/Carp.pm.
-</pre>
-<p>is printed with proper indentation.
-</p>
-<hr>
-<a name="perldebguts-Debugging-Regular-Expressions"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebguts-Debugging-Perl-Memory-Usage" accesskey="n"
rel="next">perldebguts Debugging Perl Memory Usage</a>, Previous: <a
href="#perldebguts-Frame-Listing-Output-Examples" accesskey="p"
rel="prev">perldebguts Frame Listing Output Examples</a>, Up: <a
href="#perldebguts" accesskey="u" rel="up">perldebguts</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Debugging-Regular-Expressions"></a>
-<h3 class="section">13.5 Debugging Regular Expressions</h3>
-
-<p>There are two ways to enable debugging output for regular expressions.
-</p>
-<p>If your perl is compiled with <code>-DDEBUGGING</code>, you may use the
-<strong>-Dr</strong> flag on the command line.
-</p>
-<p>Otherwise, one can <code>use re 'debug'</code>, which has effects at
-compile time and run time. Since Perl 5.9.5, this pragma is lexically
-scoped.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Compile_002dtime-Output" accesskey="1">perldebguts
Compile-time Output</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebguts-Types-of-Nodes"
accesskey="2">perldebguts Types of Nodes</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Run_002dtime-Output" accesskey="3">perldebguts Run-time
Output</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldebguts-Compile_002dtime-Output"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebguts-Types-of-Nodes" accesskey="n"
rel="next">perldebguts Types of Nodes</a>, Up: <a
href="#perldebguts-Debugging-Regular-Expressions" accesskey="u"
rel="up">perldebguts Debugging Regular Expressions</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Compile_002dtime-Output"></a>
-<h4 class="subsection">13.5.1 Compile-time Output</h4>
-
-<p>The debugging output at compile time looks like this:
-</p>
-<pre class="verbatim"> Compiling REx '[bc]d(ef*g)+h[ij]k$'
- size 45 Got 364 bytes for offset annotations.
- first at 1
- rarest char g at 0
- rarest char d at 0
- 1: ANYOF[bc](12)
- 12: EXACT <d>(14)
- 14: CURLYX[0] {1,32767}(28)
- 16: OPEN1(18)
- 18: EXACT <e>(20)
- 20: STAR(23)
- 21: EXACT <f>(0)
- 23: EXACT <g>(25)
- 25: CLOSE1(27)
- 27: WHILEM[1/1](0)
- 28: NOTHING(29)
- 29: EXACT <h>(31)
- 31: ANYOF[ij](42)
- 42: EXACT <k>(44)
- 44: EOL(45)
- 45: END(0)
- anchored 'de' at 1 floating 'gh' at 3..2147483647 (checking floating)
- stclass 'ANYOF[bc]' minlen 7
- Offsets: [45]
- 1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
- 0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
- 11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
- 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
- Omitting $` $& $' support.
-</pre>
-<p>The first line shows the pre-compiled form of the regex. The second
-shows the size of the compiled form (in arbitrary units, usually
-4-byte words) and the total number of bytes allocated for the
-offset/length table, usually 4+<code>size</code>*8. The next line shows the
-label <em>id</em> of the first node that does a match.
-</p>
-<p>The
-</p>
-<pre class="verbatim"> anchored 'de' at 1 floating 'gh' at 3..2147483647
(checking floating)
- stclass 'ANYOF[bc]' minlen 7
-</pre>
-<p>line (split into two lines above) contains optimizer
-information. In the example shown, the optimizer found that the match
-should contain a substring <code>de</code> at offset 1, plus substring
<code>gh</code>
-at some offset between 3 and infinity. Moreover, when checking for
-these substrings (to abandon impossible matches quickly), Perl will check
-for the substring <code>gh</code> before checking for the substring
<code>de</code>. The
-optimizer may also use the knowledge that the match starts (at the
-<code>first</code> <em>id</em>) with a character class, and no string
-shorter than 7 characters can possibly match.
-</p>
-<p>The fields of interest which may appear in this line are
-</p>
-<dl compact="compact">
-<dt><code>anchored</code> <em>STRING</em> <code>at</code> <em>POS</em></dt>
-<dd><a name="perldebguts-anchored-STRING-at-POS"></a>
-</dd>
-<dt><code>floating</code> <em>STRING</em> <code>at</code>
<em>POS1..POS2</em></dt>
-<dd><a name="perldebguts-floating-STRING-at-POS1_002e_002ePOS2"></a>
-<p>See above.
-</p>
-</dd>
-<dt><code>matching floating/anchored</code></dt>
-<dd><a name="perldebguts-matching-floating_002fanchored"></a>
-<p>Which substring to check first.
-</p>
-</dd>
-<dt><code>minlen</code></dt>
-<dd><a name="perldebguts-minlen"></a>
-<p>The minimal length of the match.
-</p>
-</dd>
-<dt><code>stclass</code> <em>TYPE</em></dt>
-<dd><a name="perldebguts-stclass-TYPE"></a>
-<p>Type of first matching node.
-</p>
-</dd>
-<dt><code>noscan</code></dt>
-<dd><a name="perldebguts-noscan"></a>
-<p>Don’t scan for the found substrings.
-</p>
-</dd>
-<dt><code>isall</code></dt>
-<dd><a name="perldebguts-isall"></a>
-<p>Means that the optimizer information is all that the regular
-expression contains, and thus one does not need to enter the regex engine at
-all.
-</p>
-</dd>
-<dt><code>GPOS</code></dt>
-<dd><a name="perldebguts-GPOS"></a>
-<p>Set if the pattern contains <code>\G</code>.
-</p>
-</dd>
-<dt><code>plus</code></dt>
-<dd><a name="perldebguts-plus"></a>
-<p>Set if the pattern starts with a repeated char (as in <code>x+y</code>).
-</p>
-</dd>
-<dt><code>implicit</code></dt>
-<dd><a name="perldebguts-implicit"></a>
-<p>Set if the pattern starts with <code>.*</code>.
-</p>
-</dd>
-<dt><code>with eval</code></dt>
-<dd><a name="perldebguts-with-eval"></a>
-<p>Set if the pattern contain eval-groups, such as <code>(?{ code })</code> and
-<code>(??{ code })</code>.
-</p>
-</dd>
-<dt><code>anchored(TYPE)</code></dt>
-<dd><a name="perldebguts-anchored_0028TYPE_0029"></a>
-<p>If the pattern may match only at a handful of places, with <code>TYPE</code>
-being <code>SBOL</code>, <code>MBOL</code>, or <code>GPOS</code>. See the
table below.
-</p>
-</dd>
-</dl>
-
-<p>If a substring is known to match at end-of-line only, it may be
-followed by <code>$</code>, as in <code>floating 'k'$</code>.
-</p>
-<p>The optimizer-specific information is used to avoid entering (a slow) regex
-engine on strings that will not definitely match. If the <code>isall</code>
flag
-is set, a call to the regex engine may be avoided even when the optimizer
-found an appropriate place for the match.
-</p>
-<p>Above the optimizer section is the list of <em>nodes</em> of the compiled
-form of the regex. Each line has format
-</p>
-<p><code> </code><em>id</em>: <em>TYPE</em> <em>OPTIONAL-INFO</em>
(<em>next-id</em>)
-</p>
-<hr>
-<a name="perldebguts-Types-of-Nodes"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebguts-Run_002dtime-Output" accesskey="n"
rel="next">perldebguts Run-time Output</a>, Previous: <a
href="#perldebguts-Compile_002dtime-Output" accesskey="p"
rel="prev">perldebguts Compile-time Output</a>, Up: <a
href="#perldebguts-Debugging-Regular-Expressions" accesskey="u"
rel="up">perldebguts Debugging Regular Expressions</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Types-of-Nodes"></a>
-<h4 class="subsection">13.5.2 Types of Nodes</h4>
-
-<p>Here are the current possible types, with short descriptions:
-</p>
-<pre class="verbatim"> # TYPE arg-description [num-args] [longjump-len]
DESCRIPTION
-
- # Exit points
-
- END no End of program.
- SUCCEED no Return from a subroutine, basically.
-
- # Line Start Anchors:
- SBOL no Match "" at beginning of line: /^/, /\A/
- MBOL no Same, assuming multiline: /^/m
-
- # Line End Anchors:
- SEOL no Match "" at end of line: /$/
- MEOL no Same, assuming multiline: /$/m
- EOS no Match "" at end of string: /\z/
-
- # Match Start Anchors:
- GPOS no Matches where last m//g left off.
-
- # Word Boundary Opcodes:
- BOUND no Like BOUNDA for non-utf8, otherwise match
""
- between any Unicode \w\W or \W\w
- BOUNDL no Like BOUND/BOUNDU, but \w and \W are defined
- by current locale
- BOUNDU no Match "" at any boundary of a given type
- using Unicode rules
- BOUNDA no Match "" at any boundary between \w\W or
- \W\w, where \w is [_a-zA-Z0-9]
- NBOUND no Like NBOUNDA for non-utf8, otherwise match
- "" between any Unicode \w\w or \W\W
- NBOUNDL no Like NBOUND/NBOUNDU, but \w and \W are
- defined by current locale
- NBOUNDU no Match "" at any non-boundary of a given
type
- using using Unicode rules
- NBOUNDA no Match "" betweeen any \w\w or \W\W,
where \w
- is [_a-zA-Z0-9]
-
- # [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 1 Match character in (or not in) this class,
- single char match only
- ANYOFL sv 1 Like ANYOF, but /l is in effect
-
- # POSIX Character Classes:
- POSIXD none Some [[:class:]] under /d; the FLAGS field
- gives which one
- POSIXL none Some [[:class:]] under /l; the FLAGS field
- gives which one
- POSIXU none Some [[:class:]] under /u; the FLAGS field
- gives which one
- POSIXA none Some [[:class:]] under /a; the FLAGS field
- gives which one
- NPOSIXD none complement of POSIXD, [[:^class:]]
- NPOSIXL none complement of POSIXL, [[:^class:]]
- NPOSIXU none complement of POSIXU, [[:^class:]]
- NPOSIXA none complement of POSIXA, [[:^class:]]
-
- CLUMP no Match any extended grapheme cluster sequence
-
- # Alternation
-
- # BRANCH The set of branches constituting a single choice are
- # hooked together with their "next" pointers, since
- # precedence prevents anything being concatenated to
- # any individual branch. The "next" pointer of the
last
- # BRANCH in a choice points to the thing following the
- # whole choice. This is also where the final "next"
- # pointer of each individual branch points; each branch
- # starts with the operand node of a BRANCH node.
- #
- BRANCH node Match this alternative, or the next...
-
- # Literals
-
- EXACT str Match this string (preceded by length).
- EXACTL str Like EXACT, but /l is in effect.
- EXACTF str Match this non-UTF-8 string (not guaranteed
- to be folded) using /id rules (w/len).
- EXACTFL str Match this string (not guaranteed to be
- folded) using /il rules (w/len).
- EXACTFU str Match this string (folded iff in UTF-8,
- length in folding doesn't change if not in
- UTF-8) using /iu rules (w/len).
- EXACTFA str Match this string (not guaranteed to be
- folded) using /iaa rules (w/len).
-
- EXACTFU_SS str Match this string (folded iff in UTF-8,
- length in folding may change even if not in
- UTF-8) using /iu rules (w/len).
- EXACTFLU8 str Rare cirucmstances: like EXACTFU, but is
- under /l, UTF-8, folded, and everything in
- it is above 255.
- EXACTFA_NO_TRIE str Match this string (which is not trie-able;
- not guaranteed to be folded) using /iaa
- rules (w/len).
-
- # 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. 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 rules for non-utf8
- REFFL num 1 Match already matched string, folded in loc.
- REFFU num 1 Match already matched string, folded using
- unicode rules for non-utf8
- REFFA num 1 Match already matched string, folded using
- unicode rules 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 rules for non-utf8
- NREFFL no-sv 1 Match already matched string, folded in loc.
- NREFFU num 1 Match already matched string, folded using
- unicode rules for non-utf8
- NREFFA num 1 Match already matched string, folded using
- unicode rules for non-utf8, no mixing ASCII,
- non-ASCII
-
- # Support for long RE
- LONGJMP off 1 1 Jump far away.
- BRANCHJ off 1 1 BRANCH with long offset.
-
- # Special Case Regops
- 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.
-
- # The heavy worker
-
- EVAL evl/flags Execute some Perl code.
- 2L
-
- # 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.
-
- TRIE trie 1 Match many EXACT(F[ALU]?)? at once.
- flags==type
- TRIEC trie Same as TRIE, but with embedded charclass
- charclass data
-
- AHOCORASICK trie 1 Aho Corasick stclass. flags==type
- AHOCORASICKC trie Same as AHOCORASICK, but with embedded
- charclass charclass data
-
- # Regex Subroutines
- GOSUB num/ofs 2L recurse to paren arg1 at (signed) ofs arg2
- GOSTART no recurse to start of pattern
-
- # 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
-
- # 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.
-</pre>
-<p>Following the optimizer information is a dump of the offset/length
-table, here split across several lines:
-</p>
-<pre class="verbatim"> Offsets: [45]
- 1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
- 0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
- 11[1] 0[0] 12[0] 12[0] 13[1] 0[0] 14[4] 0[0] 0[0] 0[0] 0[0]
- 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 18[1] 0[0] 19[1] 20[0]
-</pre>
-<p>The first line here indicates that the offset/length table contains 45
-entries. Each entry is a pair of integers, denoted by
<code>offset[length]</code>.
-Entries are numbered starting with 1, so entry #1 here is <code>1[4]</code> and
-entry #12 is <code>5[1]</code>. <code>1[4]</code> indicates that the node
labeled <code>1:</code>
-(the <code>1: ANYOF[bc]</code>) begins at character position 1 in the
-pre-compiled form of the regex, and has a length of 4 characters.
-<code>5[1]</code> in position 12
-indicates that the node labeled <code>12:</code>
-(the <code>12: EXACT <d></code>) begins at character position 5 in the
-pre-compiled form of the regex, and has a length of 1 character.
-<code>12[1]</code> in position 14
-indicates that the node labeled <code>14:</code>
-(the <code>14: CURLYX[0] {1,32767}</code>) begins at character position 12 in
the
-pre-compiled form of the regex, and has a length of 1 character—that
-is, it corresponds to the <code>+</code> symbol in the precompiled regex.
-</p>
-<p><code>0[0]</code> items indicate that there is no corresponding node.
-</p>
-<hr>
-<a name="perldebguts-Run_002dtime-Output"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldebguts-Types-of-Nodes" accesskey="p"
rel="prev">perldebguts Types of Nodes</a>, Up: <a
href="#perldebguts-Debugging-Regular-Expressions" accesskey="u"
rel="up">perldebguts Debugging Regular Expressions</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Run_002dtime-Output"></a>
-<h4 class="subsection">13.5.3 Run-time Output</h4>
-
-<p>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
-entered and that all of the job was therefore done by the optimizer.
-</p>
-<p>If the regex engine was entered, the output may look like this:
-</p>
-<pre class="verbatim"> Matching '[bc]d(ef*g)+h[ij]k$' against 'abcdefg__gh__'
- Setting an EVAL scope, savestack=3
- 2 <ab> <cdefg__gh_> | 1: ANYOF
- 3 <abc> <defg__gh_> | 11: EXACT <d>
- 4 <abcd> <efg__gh_> | 13: CURLYX {1,32767}
- 4 <abcd> <efg__gh_> | 26: WHILEM
- 0 out of 1..32767 cc=effff31c
- 4 <abcd> <efg__gh_> | 15: OPEN1
- 4 <abcd> <efg__gh_> | 17: EXACT <e>
- 5 <abcde> <fg__gh_> | 19: STAR
- EXACT <f> can match 1 times out of 32767...
- Setting an EVAL scope, savestack=3
- 6 <bcdef> <g__gh__> | 22: EXACT <g>
- 7 <bcdefg> <__gh__> | 24: CLOSE1
- 7 <bcdefg> <__gh__> | 26: WHILEM
- 1 out of 1..32767 cc=effff31c
- Setting an EVAL scope, savestack=12
- 7 <bcdefg> <__gh__> | 15: OPEN1
- 7 <bcdefg> <__gh__> | 17: EXACT <e>
- restoring \1 to 4(4)..7
- failed, try continuation...
- 7 <bcdefg> <__gh__> | 27: NOTHING
- 7 <bcdefg> <__gh__> | 28: EXACT <h>
- failed...
- failed...
-</pre>
-<p>The most significant information in the output is about the particular
<em>node</em>
-of the compiled regex that is currently being tested against the target string.
-The format of these lines is
-</p>
-<p><code> </code><em>STRING-OFFSET</em> <<em>PRE-STRING</em>>
<<em>POST-STRING</em>> |<em>ID</em>: <em>TYPE</em>
-</p>
-<p>The <em>TYPE</em> info is indented with respect to the backtracking level.
-Other incidental information appears interspersed within.
-</p>
-<hr>
-<a name="perldebguts-Debugging-Perl-Memory-Usage"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebguts-SEE-ALSO" accesskey="n" rel="next">perldebguts SEE
ALSO</a>, Previous: <a href="#perldebguts-Debugging-Regular-Expressions"
accesskey="p" rel="prev">perldebguts Debugging Regular Expressions</a>, Up: <a
href="#perldebguts" accesskey="u" rel="up">perldebguts</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Debugging-Perl-Memory-Usage"></a>
-<h3 class="section">13.6 Debugging Perl Memory Usage</h3>
-
-<p>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
-algorithm for memory allocation, multiply that estimate by 10, and
-while you still may miss the mark, at least you won’t be quite so
-astonished. This is not absolutely true, but may provide a good
-grasp of what happens.
-</p>
-<p>Assume that an integer cannot take less than 20 bytes of memory, a
-float cannot take less than 24 bytes, a string cannot take less
-than 32 bytes (all these examples assume 32-bit architectures, the
-result are quite a bit worse on 64-bit architectures). If a variable
-is accessed in two of three different ways (which require an integer,
-a float, or a string), the memory footprint may increase yet another
-20 bytes. A sloppy malloc(3) implementation can inflate these
-numbers dramatically.
-</p>
-<p>On the opposite end of the scale, a declaration like
-</p>
-<pre class="verbatim"> sub foo;
-</pre>
-<p>may take up to 500 bytes of memory, depending on which release of Perl
-you’re running.
-</p>
-<p>Anecdotal estimates of source-to-compiled code bloat suggest an
-eightfold increase. This means that the compiled form of reasonable
-(normally commented, properly indented etc.) code will take
-about eight times more space in memory than the code took
-on disk.
-</p>
-<p>The <strong>-DL</strong> command-line switch is obsolete since circa Perl
5.6.0
-(it was available only if Perl was built with <code>-DDEBUGGING</code>).
-The switch was used to track Perl’s memory allocations and possible
-memory leaks. These days the use of malloc debugging tools like
-<samp>Purify</samp> or <samp>valgrind</samp> is suggested instead. See also
-<a href="#perlhacktips-PERL_005fMEM_005fLOG">perlhacktips PERL_MEM_LOG</a>.
-</p>
-<p>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
-you the minimum number of bytes required to store a particular data
-structure. Please be mindful of the difference between the size()
-and total_size().
-</p>
-<p>If Perl has been compiled using Perl’s malloc you can analyze Perl
-memory usage by setting $ENV{PERL_DEBUG_MSTATS}.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perldebguts-Using-_0024ENV_007bPERL_005fDEBUG_005fMSTATS_007d"
accesskey="1">perldebguts Using
<code>$ENV{PERL_DEBUG_MSTATS}</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldebguts-Using-_0024ENV_007bPERL_005fDEBUG_005fMSTATS_007d"></a>
-<div class="header">
-<p>
-Up: <a href="#perldebguts-Debugging-Perl-Memory-Usage" accesskey="u"
rel="up">perldebguts Debugging Perl Memory Usage</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-_0024ENV_007bPERL_005fDEBUG_005fMSTATS_007d"></a>
-<h4 class="subsection">13.6.1 Using <code>$ENV{PERL_DEBUG_MSTATS}</code></h4>
-
-<p>If your perl is using Perl’s malloc() and was compiled with the
-necessary switches (this is the default), then it will print memory
-usage statistics after compiling your code when <code>$ENV{PERL_DEBUG_MSTATS}
-> 1</code>, and before termination of the program when
<code>$ENV{PERL_DEBUG_MSTATS} >= 1</code>. The report format is similar to
-the following example:
-</p>
-<pre class="verbatim"> $ PERL_DEBUG_MSTATS=2 perl -e "require Carp"
- Memory allocation statistics after compilation: (buckets 4(4)..8188(8192)
- 14216 free: 130 117 28 7 9 0 2 2 1 0 0
- 437 61 36 0 5
- 60924 used: 125 137 161 55 7 8 6 16 2 0 1
- 74 109 304 84 20
- Total sbrk(): 77824/21:119. Odd ends: pad+heads+chain+tail: 0+636+0+2048.
- Memory allocation statistics after execution: (buckets 4(4)..8188(8192)
- 30888 free: 245 78 85 13 6 2 1 3 2 0 1
- 315 162 39 42 11
- 175816 used: 265 176 1112 111 26 22 11 27 2 1 1
- 196 178 1066 798 39
- Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144.
-</pre>
-<p>It is possible to ask for such a statistic at arbitrary points in
-your execution using the mstat() function out of the standard
-Devel::Peek module.
-</p>
-<p>Here is some explanation of that format:
-</p>
-<dl compact="compact">
-<dt><code>buckets SMALLEST(APPROX)..GREATEST(APPROX)</code></dt>
-<dd><a
name="perldebguts-buckets-SMALLEST_0028APPROX_0029_002e_002eGREATEST_0028APPROX_0029"></a>
-<p>Perl’s malloc() uses bucketed allocations. Every request is rounded
-up to the closest bucket size available, and a bucket is taken from
-the pool of buckets of that size.
-</p>
-<p>The line above describes the limits of buckets currently in use.
-Each bucket has two sizes: memory footprint and the maximal size
-of user data that can fit into this bucket. Suppose in the above
-example that the smallest bucket were size 4. The biggest bucket
-would have usable size 8188, and the memory footprint would be 8192.
-</p>
-<p>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, the corresponding power of two is
-printed in the <code>APPROX</code> field above.
-</p>
-</dd>
-<dt>Free/Used</dt>
-<dd><a name="perldebguts-Free_002fUsed"></a>
-<p>The 1 or 2 rows of numbers following that correspond to the number
-of buckets of each size between <code>SMALLEST</code> and
<code>GREATEST</code>. In
-the first row, the sizes (memory footprints) of buckets are powers
-of two–or possibly one page greater. In the second row, if present,
-the memory footprints of the buckets are between the memory footprints
-of two buckets "above".
-</p>
-<p>For example, suppose under the previous example, the memory footprints
-were
-</p>
-<pre class="verbatim"> free: 8 16 32 64 128 256 512 1024
2048 4096 8192
- 4 12 24 48 80
-</pre>
-<p>With a non-<code>DEBUGGING</code> perl, the buckets starting from
<code>128</code> have
-a 4-byte overhead, and thus an 8192-long bucket may take up to
-8188-byte allocations.
-</p>
-</dd>
-<dt><code>Total sbrk(): SBRKed/SBRKs:CONTINUOUS</code></dt>
-<dd><a
name="perldebguts-Total-sbrk_0028_0029_003a-SBRKed_002fSBRKs_003aCONTINUOUS"></a>
-<p>The first two fields give the total amount of memory perl sbrk(2)ed
-(ess-broken? :-) and number of sbrk(2)s used. The third number is
-what perl thinks about continuity of returned chunks. So long as
-this number is positive, malloc() will assume that it is probable
-that sbrk(2) will provide continuous memory.
-</p>
-<p>Memory allocated by external libraries is not counted.
-</p>
-</dd>
-<dt><code>pad: 0</code></dt>
-<dd><a name="perldebguts-pad_003a-0"></a>
-<p>The amount of sbrk(2)ed memory needed to keep buckets aligned.
-</p>
-</dd>
-<dt><code>heads: 2192</code></dt>
-<dd><a name="perldebguts-heads_003a-2192"></a>
-<p>Although memory overhead of bigger buckets is kept inside the bucket, for
-smaller buckets, it is kept in separate areas. This field gives the
-total size of these areas.
-</p>
-</dd>
-<dt><code>chain: 0</code></dt>
-<dd><a name="perldebguts-chain_003a-0"></a>
-<p>malloc() may want to subdivide a bigger bucket into smaller buckets.
-If only a part of the deceased bucket is left unsubdivided, the rest
-is kept as an element of a linked list. This field gives the total
-size of these chunks.
-</p>
-</dd>
-<dt><code>tail: 6144</code></dt>
-<dd><a name="perldebguts-tail_003a-6144"></a>
-<p>To minimize the number of sbrk(2)s, malloc() asks for more memory. This
-field gives the size of the yet unused part, which is sbrk(2)ed, but
-never touched.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perldebguts-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldebguts-Debugging-Perl-Memory-Usage" accesskey="p"
rel="prev">perldebguts Debugging Perl Memory Usage</a>, Up: <a
href="#perldebguts" accesskey="u" rel="up">perldebguts</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-6"></a>
-<h3 class="section">13.7 SEE ALSO</h3>
-
-<p><a href="#perldebug-NAME">perldebug NAME</a>,
-<a href="#perlguts-NAME">perlguts NAME</a>,
-<a href="#perlrun-NAME">perlrun NAME</a>
-<a href="re.html#Top">(re)</a>,
-and
-<a href="Devel-DProf.html#Top">(Devel-DProf)</a>.
-</p>
-<hr>
-<a name="perldebtut"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug" accesskey="n" rel="next">perldebug</a>, Previous:
<a href="#perldebguts" accesskey="p" rel="prev">perldebguts</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perldebtut-1"></a>
-<h2 class="chapter">14 perldebtut</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perldebtut-NAME"
accesskey="1">perldebtut NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebtut-DESCRIPTION"
accesskey="2">perldebtut DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebtut-use-strict"
accesskey="3">perldebtut use strict</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-Looking-at-data-and-_002dw-and-v" accesskey="4">perldebtut
Looking at data and -w and v</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebtut-help"
accesskey="5">perldebtut help</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-Stepping-through-code" accesskey="6">perldebtut Stepping
through code</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-Placeholder-for-a_002c-w_002c-t_002c-T"
accesskey="7">perldebtut Placeholder for a, w, t,
T</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-REGULAR-EXPRESSIONS" accesskey="8">perldebtut REGULAR
EXPRESSIONS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebtut-OUTPUT-TIPS"
accesskey="9">perldebtut OUTPUT TIPS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebtut-CGI">perldebtut
CGI</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebtut-GUIs">perldebtut
GUIs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-SUMMARY">perldebtut SUMMARY</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-SEE-ALSO">perldebtut SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-AUTHOR">perldebtut AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebtut-CONTRIBUTORS">perldebtut
CONTRIBUTORS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldebtut-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut-DESCRIPTION" accesskey="n" rel="next">perldebtut
DESCRIPTION</a>, Up: <a href="#perldebtut" accesskey="u"
rel="up">perldebtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-13"></a>
-<h3 class="section">14.1 NAME</h3>
-
-<p>perldebtut - Perl debugging tutorial
-</p>
-<hr>
-<a name="perldebtut-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut-use-strict" accesskey="n" rel="next">perldebtut use
strict</a>, Previous: <a href="#perldebtut-NAME" accesskey="p"
rel="prev">perldebtut NAME</a>, Up: <a href="#perldebtut" accesskey="u"
rel="up">perldebtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-13"></a>
-<h3 class="section">14.2 DESCRIPTION</h3>
-
-<p>A (very) lightweight introduction in the use of the perl debugger, and a
-pointer to existing, deeper sources of information on the subject of debugging
-perl programs.
-</p>
-<p>There’s an extraordinary number of people out there who don’t
appear to know
-anything about using the perl debugger, though they use the language every
-day.
-This is for them.
-</p>
-<hr>
-<a name="perldebtut-use-strict"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut-Looking-at-data-and-_002dw-and-v" accesskey="n"
rel="next">perldebtut Looking at data and -w and v</a>, Previous: <a
href="#perldebtut-DESCRIPTION" accesskey="p" rel="prev">perldebtut
DESCRIPTION</a>, Up: <a href="#perldebtut" accesskey="u"
rel="up">perldebtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="use-strict"></a>
-<h3 class="section">14.3 use strict</h3>
-
-<p>First of all, there’s a few things you can do to make your life a lot
more
-straightforward when it comes to debugging perl programs, without using the
-debugger at all. To demonstrate, here’s a simple script, named
"hello", with
-a problem:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
-
- $var1 = 'Hello World'; # always wanted to do that :-)
- $var2 = "$varl\n";
-
- print $var2;
- exit;
-</pre>
-<p>While this compiles and runs happily, it probably won’t do
what’s expected,
-namely it doesn’t print "Hello World\n" at all; It will on
the other hand do
-exactly what it was told to do, computers being a bit that way inclined. That
-is, it will print out a newline character, and you’ll get what looks
like a
-blank line. It looks like there’s 2 variables when (because of the typo)
-there’s really 3:
-</p>
-<pre class="verbatim"> $var1 = 'Hello World';
- $varl = undef;
- $var2 = "\n";
-</pre>
-<p>To catch this kind of problem, we can force each variable to be declared
-before use by pulling in the strict module, by putting ’use
strict;’ after the
-first line of the script.
-</p>
-<p>Now when you run it, perl complains about the 3 undeclared variables and we
-get four error messages because one variable is referenced twice:
-</p>
-<pre class="verbatim"> Global symbol "$var1" requires explicit
package name at ./t1 line 4.
- Global symbol "$var2" requires explicit package name at ./t1 line 5.
- Global symbol "$varl" requires explicit package name at ./t1 line 5.
- Global symbol "$var2" requires explicit package name at ./t1 line 7.
- Execution of ./hello aborted due to compilation errors.
-</pre>
-<p>Luvverly! and to fix this we declare all variables explicitly and now our
-script looks like this:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
- use strict;
-
- my $var1 = 'Hello World';
- my $varl = undef;
- my $var2 = "$varl\n";
-
- print $var2;
- exit;
-</pre>
-<p>We then do (always a good idea) a syntax check before we try to run it
again:
-</p>
-<pre class="verbatim"> > perl -c hello
- hello syntax OK
-</pre>
-<p>And now when we run it, we get "\n" still, but at least we know
why. Just
-getting this script to compile has exposed the ’$varl’ (with the
letter ’l’)
-variable, and simply changing $varl to $var1 solves the problem.
-</p>
-<hr>
-<a name="perldebtut-Looking-at-data-and-_002dw-and-v"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut-help" accesskey="n" rel="next">perldebtut help</a>,
Previous: <a href="#perldebtut-use-strict" accesskey="p" rel="prev">perldebtut
use strict</a>, Up: <a href="#perldebtut" accesskey="u" rel="up">perldebtut</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Looking-at-data-and-_002dw-and-v"></a>
-<h3 class="section">14.4 Looking at data and -w and v</h3>
-
-<p>Ok, but how about when you want to really see your data, what’s in
that
-dynamic variable, just before using it?
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
- use strict;
-
- my $key = 'welcome';
- my %data = (
- 'this' => qw(that),
- 'tom' => qw(and jerry),
- 'welcome' => q(Hello World),
- 'zip' => q(welcome),
- );
- my @data = keys %data;
-
- print "$data{$key}\n";
- exit;
-</pre>
-<p>Looks OK, after it’s been through the syntax check (perl -c
scriptname), we
-run it and all we get is a blank line again! Hmmmm.
-</p>
-<p>One common debugging approach here, would be to liberally sprinkle a few
print
-statements, to add a check just before we print out our data, and another just
-after:
-</p>
-<pre class="verbatim"> print "All OK\n" if grep($key, keys
%data);
- print "$data{$key}\n";
- print "done: '$data{$key}'\n";
-</pre>
-<p>And try again:
-</p>
-<pre class="verbatim"> > perl data
- All OK
-
- done: ''
-</pre>
-<p>After much staring at the same piece of code and not seeing the wood for the
-trees for some time, we get a cup of coffee and try another approach. That
-is, we bring in the cavalry by giving perl the
’<strong>-d</strong>’ switch on the command
-line:
-</p>
-<pre class="verbatim"> > perl -d data
- Default die handler restored.
-
- Loading DB routines from perl5db.pl version 1.07
- Editor support available.
-
- Enter h or `h h' for help, or `man perldebug' for more help.
-
- main::(./data:4): my $key = 'welcome';
-</pre>
-<p>Now, what we’ve done here is to launch the built-in perl debugger on
our
-script. It’s stopped at the first line of executable code and is
waiting for
-input.
-</p>
-<p>Before we go any further, you’ll want to know how to quit the
debugger: use
-just the letter ’<strong>q</strong>’, not the words
’quit’ or ’exit’:
-</p>
-<pre class="verbatim"> DB<1> q
- >
-</pre>
-<p>That’s it, you’re back on home turf again.
-</p>
-<hr>
-<a name="perldebtut-help"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut-Stepping-through-code" accesskey="n"
rel="next">perldebtut Stepping through code</a>, Previous: <a
href="#perldebtut-Looking-at-data-and-_002dw-and-v" accesskey="p"
rel="prev">perldebtut Looking at data and -w and v</a>, Up: <a
href="#perldebtut" accesskey="u" rel="up">perldebtut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="help"></a>
-<h3 class="section">14.5 help</h3>
-
-<p>Fire the debugger up again on your script and we’ll look at the help
menu.
-There’s a couple of ways of calling help: a simple
’<strong>h</strong>’ will get the summary
-help list, ’<strong>|h</strong>’ (pipe-h) will pipe the help
through your pager (which is
-(probably ’more’ or ’less’), and finally,
’<strong>h h</strong>’ (h-space-h) will give you
-the entire help screen. Here is the summary page:
-</p>
-<p>D<strong>1</strong>h
-</p>
-<pre class="verbatim"> List/search source lines: Control script
execution:
- l [ln|sub] List source code T Stack trace
- - or . List previous/current line s [expr] Single step [in expr]
- v [line] View around line n [expr] Next, steps over subs
- f filename View source in file <CR/Enter> Repeat last n or s
- /pattern/ ?patt? Search forw/backw r Return from subroutine
- M Show module versions c [ln|sub] Continue until position
- Debugger controls: L List break/watch/actions
- o [...] Set debugger options t [expr] Toggle trace [trace expr]
- <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd]
Set breakpoint
- ! [N|pat] Redo a previous command B ln|* Delete a/all breakpoints
- H [-num] Display last num commands a [ln] cmd Do cmd before line
- = [a val] Define/list an alias A ln|* Delete a/all actions
- h [db_cmd] Get help on command w expr Add a watch expression
- h h Complete help page W expr|* Delete a/all watch exprs
- |[|]db_cmd Send output to pager ![!] syscmd Run cmd in a subprocess
- q or ^D Quit R Attempt a restart
- Data Examination: expr Execute perl code, also see: s,n,t expr
- x|m expr Evals expr in list context, dumps the result or lists methods.
- p expr Print expression (uses script's current package).
- S [[!]pat] List subroutine names [not] matching pattern
- V [Pk [Vars]] List Variables in Package. Vars can be ~pattern or !pattern.
- X [Vars] Same as "V current_package [Vars]".
- y [n [Vars]] List lexicals in higher scope <n>. Vars same as V.
- For more help, type h cmd_letter, or run man perldebug for all docs.
-</pre>
-<p>More confusing options than you can shake a big stick at! It’s not
as bad as
-it looks and it’s very useful to know more about all of it, and fun too!
-</p>
-<p>There’s a couple of useful ones to know about straight away. You
wouldn’t
-think we’re using any libraries at all at the moment, but
’<strong>M</strong>’ will show
-which modules are currently loaded, and their version number, while
’<strong>m</strong>’
-will show the methods, and ’<strong>S</strong>’ shows all
subroutines (by pattern) as
-shown below. ’<strong>V</strong>’ and
’<strong>X</strong>’ show variables in the program by package
-scope and can be constrained by pattern.
-</p>
-<pre class="verbatim"> DB<2>S str
- dumpvar::stringify
- strict::bits
- strict::import
- strict::unimport
-</pre>
-<p>Using ’X’ and cousins requires you not to use the type
identifiers (address@hidden), just
-the ’name’:
-</p>
-<pre class="verbatim"> DM<3>X ~err
- FileHandle(stderr) => fileno(2)
-</pre>
-<p>Remember we’re in our tiny program with a problem, we should have a
look at
-where we are, and what our data looks like. First of all let’s view some
code
-at our present position (the first line of code in this case), via
’<strong>v</strong>’:
-</p>
-<pre class="verbatim"> DB<4> v
- 1 #!/usr/bin/perl
- 2: use strict;
- 3
- 4==> my $key = 'welcome';
- 5: my %data = (
- 6 'this' => qw(that),
- 7 'tom' => qw(and jerry),
- 8 'welcome' => q(Hello World),
- 9 'zip' => q(welcome),
- 10 );
-</pre>
-<p>At line number 4 is a helpful pointer, that tells you where you are now. To
-see more code, type ’v’ again:
-</p>
-<pre class="verbatim"> DB<4> v
- 8 'welcome' => q(Hello World),
- 9 'zip' => q(welcome),
- 10 );
- 11: my @data = keys %data;
- 12: print "All OK\n" if grep($key, keys %data);
- 13: print "$data{$key}\n";
- 14: print "done: '$data{$key}'\n";
- 15: exit;
-</pre>
-<p>And if you wanted to list line 5 again, type ’l 5’, (note the
space):
-</p>
-<pre class="verbatim"> DB<4> l 5
- 5: my %data = (
-</pre>
-<p>In this case, there’s not much to see, but of course normally
there’s pages of
-stuff to wade through, and ’l’ can be very useful. To reset your
view to the
-line we’re about to execute, type a lone period ’.’:
-</p>
-<pre class="verbatim"> DB<5> .
- main::(./data_a:4): my $key = 'welcome';
-</pre>
-<p>The line shown is the one that is about to be executed
<strong>next</strong>, it hasn’t
-happened yet. So while we can print a variable with the letter
’<strong>p</strong>’, at
-this point all we’d get is an empty (undefined) value back. What we
need to
-do is to step through the next executable statement with an
’<strong>s</strong>’:
-</p>
-<pre class="verbatim"> DB<6> s
- main::(./data_a:5): my %data = (
- main::(./data_a:6): 'this' => qw(that),
- main::(./data_a:7): 'tom' => qw(and jerry),
- main::(./data_a:8): 'welcome' => q(Hello World),
- main::(./data_a:9): 'zip' => q(welcome),
- main::(./data_a:10): );
-</pre>
-<p>Now we can have a look at that first ($key) variable:
-</p>
-<pre class="verbatim"> DB<7> p $key
- welcome
-</pre>
-<p>line 13 is where the action is, so let’s continue down to there via
the letter
-’<strong>c</strong>’, which by the way, inserts a
’one-time-only’ breakpoint at the given
-line or sub routine:
-</p>
-<pre class="verbatim"> DB<8> c 13
- All OK
- main::(./data_a:13): print "$data{$key}\n";
-</pre>
-<p>We’ve gone past our check (where ’All OK’ was printed)
and have stopped just
-before the meat of our task. We could try to print out a couple of variables
-to see what is happening:
-</p>
-<pre class="verbatim"> DB<9> p $data{$key}
-</pre>
-<p>Not much in there, lets have a look at our hash:
-</p>
-<pre class="verbatim"> DB<10> p %data
- Hello Worldziptomandwelcomejerrywelcomethisthat
-
- DB<11> p keys %data
- Hello Worldtomwelcomejerrythis
-</pre>
-<p>Well, this isn’t very easy to read, and using the helpful manual
(<strong>h h</strong>), the
-’<strong>x</strong>’ command looks promising:
-</p>
-<pre class="verbatim"> DB<12> x %data
- 0 'Hello World'
- 1 'zip'
- 2 'tom'
- 3 'and'
- 4 'welcome'
- 5 undef
- 6 'jerry'
- 7 'welcome'
- 8 'this'
- 9 'that'
-</pre>
-<p>That’s not much help, a couple of welcomes in there, but no
indication of
-which are keys, and which are values, it’s just a listed array dump and,
in
-this case, not particularly helpful. The trick here, is to use a
<strong>reference</strong>
-to the data structure:
-</p>
-<pre class="verbatim"> DB<13> x \%data
- 0 HASH(0x8194bc4)
- 'Hello World' => 'zip'
- 'jerry' => 'welcome'
- 'this' => 'that'
- 'tom' => 'and'
- 'welcome' => undef
-</pre>
-<p>The reference is truly dumped and we can finally see what we’re
dealing with.
-Our quoting was perfectly valid but wrong for our purposes, with ’and
jerry’
-being treated as 2 separate words rather than a phrase, thus throwing the
-evenly paired hash structure out of alignment.
-</p>
-<p>The ’<strong>-w</strong>’ switch would have told us about this,
had we used it at the start,
-and saved us a lot of trouble:
-</p>
-<pre class="verbatim"> > perl -w data
- Odd number of elements in hash assignment at ./data line 5.
-</pre>
-<p>We fix our quoting: ’tom’ => q(and jerry), and run it again,
this time we get
-our expected output:
-</p>
-<pre class="verbatim"> > perl -w data
- Hello World
-</pre>
-<p>While we’re here, take a closer look at the
’<strong>x</strong>’ command, it’s really useful
-and will merrily dump out nested references, complete objects, partial objects
-- just about whatever you throw at it:
-</p>
-<p>Let’s make a quick object and x-plode it, first we’ll start the
debugger:
-it wants some form of input from STDIN, so we give it something non-committal,
-a zero:
-</p>
-<pre class="verbatim"> > perl -de 0
- Default die handler restored.
-
- Loading DB routines from perl5db.pl version 1.07
- Editor support available.
-
- Enter h or `h h' for help, or `man perldebug' for more help.
-
- main::(-e:1): 0
-</pre>
-<p>Now build an on-the-fly object over a couple of lines (note the backslash):
-</p>
-<pre class="verbatim"> DB<1> $obj = bless({'unique_id'=>'123',
'attr'=> \
- cont: {'col' => 'black', 'things' => [qw(this that etc)]}},
'MY_class')
-</pre>
-<p>And let’s have a look at it:
-</p>
-<pre class="verbatim"> DB<2> x $obj
- 0 MY_class=HASH(0x828ad98)
- 'attr' => HASH(0x828ad68)
- 'col' => 'black'
- 'things' => ARRAY(0x828abb8)
- 0 'this'
- 1 'that'
- 2 'etc'
- 'unique_id' => 123
- DB<3>
-</pre>
-<p>Useful, huh? You can eval nearly anything in there, and experiment with
bits
-of code or regexes until the cows come home:
-</p>
-<pre class="verbatim"> DB<3> @data = qw(this that the other
atheism leather theory scythe)
-
- DB<4> p 'saw -> '.($cnt += map { print "\t:\t$_\n"
} grep(/the/, sort @data))
- atheism
- leather
- other
- scythe
- the
- theory
- saw -> 6
-</pre>
-<p>If you want to see the command History, type an
’<strong>H</strong>’:
-</p>
-<pre class="verbatim"> DB<5> H
- 4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" }
grep(/the/, sort @data))
- 3: @data = qw(this that the other atheism leather theory scythe)
- 2: x $obj
- 1: $obj = bless({'unique_id'=>'123', 'attr'=>
- {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
- DB<5>
-</pre>
-<p>And if you want to repeat any previous command, use the exclamation:
’<strong>!</strong>’:
-</p>
-<pre class="verbatim"> DB<5> !4
- p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/,
sort @data))
- atheism
- leather
- other
- scythe
- the
- theory
- saw -> 12
-</pre>
-<p>For more on references see <a href="#perlref-NAME">perlref NAME</a> and <a
href="#perlreftut-NAME">perlreftut NAME</a>
-</p>
-<hr>
-<a name="perldebtut-Stepping-through-code"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut-Placeholder-for-a_002c-w_002c-t_002c-T"
accesskey="n" rel="next">perldebtut Placeholder for a, w, t, T</a>, Previous:
<a href="#perldebtut-help" accesskey="p" rel="prev">perldebtut help</a>, Up: <a
href="#perldebtut" accesskey="u" rel="up">perldebtut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Stepping-through-code"></a>
-<h3 class="section">14.6 Stepping through code</h3>
-
-<p>Here’s a simple program which converts between Celsius and
Fahrenheit, it too
-has a problem:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -w
- use strict;
-
- my $arg = $ARGV[0] || '-c20';
-
- if ($arg =~ /^\-(c|f)((\-|\+)*\d+(\.\d+)*)$/) {
- my ($deg, $num) = ($1, $2);
- my ($in, $out) = ($num, $num);
- if ($deg eq 'c') {
- $deg = 'f';
- $out = &c2f($num);
- } else {
- $deg = 'c';
- $out = &f2c($num);
- }
- $out = sprintf('%0.2f', $out);
- $out =~ s/^((\-|\+)*\d+)\.0+$/$1/;
- print "$out $deg\n";
- } else {
- print "Usage: $0 -[c|f] num\n";
- }
- exit;
-
- sub f2c {
- my $f = shift;
- my $c = 5 * $f - 32 / 9;
- return $c;
- }
-
- sub c2f {
- my $c = shift;
- my $f = 9 * $c / 5 + 32;
- return $f;
- }
-</pre>
-<p>For some reason, the Fahrenheit to Celsius conversion fails to return the
-expected output. This is what it does:
-</p>
-<pre class="verbatim"> > temp -c0.72
- 33.30 f
-
- > temp -f33.3
- 162.94 c
-</pre>
-<p>Not very consistent! We’ll set a breakpoint in the code manually and
run it
-under the debugger to see what’s going on. A breakpoint is a flag, to
which
-the debugger will run without interruption, when it reaches the breakpoint, it
-will stop execution and offer a prompt for further interaction. In normal
-use, these debugger commands are completely ignored, and they are safe - if a
-little messy, to leave in production code.
-</p>
-<pre class="verbatim"> my ($in, $out) = ($num, $num);
- $DB::single=2; # insert at line 9!
- if ($deg eq 'c')
- ...
-
- > perl -d temp -f33.3
- Default die handler restored.
-
- Loading DB routines from perl5db.pl version 1.07
- Editor support available.
-
- Enter h or `h h' for help, or `man perldebug' for more help.
-
- main::(temp:4): my $arg = $ARGV[0] || '-c100';
-</pre>
-<p>We’ll simply continue down to our pre-set breakpoint with a
’<strong>c</strong>’:
-</p>
-<pre class="verbatim"> DB<1> c
- main::(temp:10): if ($deg eq 'c') {
-</pre>
-<p>Followed by a view command to see where we are:
-</p>
-<pre class="verbatim"> DB<1> v
- 7: my ($deg, $num) = ($1, $2);
- 8: my ($in, $out) = ($num, $num);
- 9: $DB::single=2;
- 10==> if ($deg eq 'c') {
- 11: $deg = 'f';
- 12: $out = &c2f($num);
- 13 } else {
- 14: $deg = 'c';
- 15: $out = &f2c($num);
- 16 }
-</pre>
-<p>And a print to show what values we’re currently using:
-</p>
-<pre class="verbatim"> DB<1> p $deg, $num
- f33.3
-</pre>
-<p>We can put another break point on any line beginning with a colon,
we’ll use
-line 17 as that’s just as we come out of the subroutine, and we’d
like to
-pause there later on:
-</p>
-<pre class="verbatim"> DB<2> b 17
-</pre>
-<p>There’s no feedback from this, but you can see what breakpoints are
set by
-using the list ’L’ command:
-</p>
-<pre class="verbatim"> DB<3> L
- temp:
- 17: print "$out $deg\n";
- break if (1)
-</pre>
-<p>Note that to delete a breakpoint you use ’B’.
-</p>
-<p>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’:
-</p>
-<pre class="verbatim"> DB<3> c f2c
- main::f2c(temp:30): my $f = shift;
-
- DB<4> v
- 24: exit;
- 25
- 26 sub f2c {
- 27==> my $f = shift;
- 28: my $c = 5 * $f - 32 / 9;
- 29: return $c;
- 30 }
- 31
- 32 sub c2f {
- 33: my $c = shift;
-</pre>
-<p>Note that if there was a subroutine call between us and line 29, and we
wanted
-to <strong>single-step</strong> through it, we could use the
’<strong>s</strong>’ command, and to step
-over it we would use ’<strong>n</strong>’ which would execute the
sub, but not descend into
-it for inspection. In this case though, we simply continue down to line 29:
-</p>
-<pre class="verbatim"> DB<4> c 29
- main::f2c(temp:29): return $c;
-</pre>
-<p>And have a look at the return value:
-</p>
-<pre class="verbatim"> DB<5> p $c
- 162.944444444444
-</pre>
-<p>This is not the right answer at all, but the sum looks correct. I wonder if
-it’s anything to do with operator precedence? We’ll try a couple
of other
-possibilities with our sum:
-</p>
-<pre class="verbatim"> DB<6> p (5 * $f - 32 / 9)
- 162.944444444444
-
- DB<7> p 5 * $f - (32 / 9)
- 162.944444444444
-
- DB<8> p (5 * $f) - 32 / 9
- 162.944444444444
-
- DB<9> p 5 * ($f - 32) / 9
- 0.722222222222221
-</pre>
-<p>:-) that’s more like it! Ok, now we can set our return variable and
we’ll
-return out of the sub with an ’r’:
-</p>
-<pre class="verbatim"> DB<10> $c = 5 * ($f - 32) / 9
-
- DB<11> r
- scalar context return from main::f2c: 0.722222222222221
-</pre>
-<p>Looks good, let’s just continue off the end of the script:
-</p>
-<pre class="verbatim"> DB<12> c
- 0.72 c
- Debugged program terminated. Use q to quit or R to restart,
- use O inhibit_exit to avoid stopping after program termination,
- h q, h R or h O to get additional info.
-</pre>
-<p>A quick fix to the offending line (insert the missing parentheses) in the
-actual program and we’re finished.
-</p>
-<hr>
-<a name="perldebtut-Placeholder-for-a_002c-w_002c-t_002c-T"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut-REGULAR-EXPRESSIONS" accesskey="n"
rel="next">perldebtut REGULAR EXPRESSIONS</a>, Previous: <a
href="#perldebtut-Stepping-through-code" accesskey="p" rel="prev">perldebtut
Stepping through code</a>, Up: <a href="#perldebtut" accesskey="u"
rel="up">perldebtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Placeholder-for-a_002c-w_002c-t_002c-T"></a>
-<h3 class="section">14.7 Placeholder for a, w, t, T</h3>
-
-<p>Actions, watch variables, stack traces etc.: on the TODO list.
-</p>
-<pre class="verbatim"> a
-
- w
-
- t
-
- T
-</pre>
-<hr>
-<a name="perldebtut-REGULAR-EXPRESSIONS"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut-OUTPUT-TIPS" accesskey="n" rel="next">perldebtut
OUTPUT TIPS</a>, Previous: <a
href="#perldebtut-Placeholder-for-a_002c-w_002c-t_002c-T" accesskey="p"
rel="prev">perldebtut Placeholder for a, w, t, T</a>, Up: <a href="#perldebtut"
accesskey="u" rel="up">perldebtut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="REGULAR-EXPRESSIONS"></a>
-<h3 class="section">14.8 REGULAR EXPRESSIONS</h3>
-
-<p>Ever wanted to know what a regex looked like? You’ll need perl
compiled with
-the DEBUGGING flag for this one:
-</p>
-<pre class="verbatim"> > perl -Dr -e '/^pe(a)*rl$/i'
- Compiling REx `^pe(a)*rl$'
- size 17 first at 2
- rarest char
- at 0
- 1: BOL(2)
- 2: EXACTF <pe>(4)
- 4: CURLYN[1] {0,32767}(14)
- 6: NOTHING(8)
- 8: EXACTF <a>(0)
- 12: WHILEM(0)
- 13: NOTHING(14)
- 14: EXACTF <rl>(16)
- 16: EOL(17)
- 17: END(0)
- floating `'$ at 4..2147483647 (checking floating) stclass `EXACTF
<pe>'
-anchored(BOL) minlen 4
- Omitting $` $& $' support.
-
- EXECUTING...
-
- Freeing REx: `^pe(a)*rl$'
-</pre>
-<p>Did you really want to know? :-)
-For more gory details on getting regular expressions to work, have a look at
-<a href="#perlre-NAME">perlre NAME</a>, <a href="#perlretut-NAME">perlretut
NAME</a>, and to decode the mysterious labels (BOL and CURLYN,
-etc. above), see <a href="#perldebguts-NAME">perldebguts NAME</a>.
-</p>
-<hr>
-<a name="perldebtut-OUTPUT-TIPS"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut-CGI" accesskey="n" rel="next">perldebtut CGI</a>,
Previous: <a href="#perldebtut-REGULAR-EXPRESSIONS" accesskey="p"
rel="prev">perldebtut REGULAR EXPRESSIONS</a>, Up: <a href="#perldebtut"
accesskey="u" rel="up">perldebtut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="OUTPUT-TIPS"></a>
-<h3 class="section">14.9 OUTPUT TIPS</h3>
-
-<p>To get all the output from your error log, and not miss any messages via
-helpful operating system buffering, insert a line like this, at the start of
-your script:
-</p>
-<pre class="verbatim"> $|=1;
-</pre>
-<p>To watch the tail of a dynamically growing logfile, (from the command line):
-</p>
-<pre class="verbatim"> tail -f $error_log
-</pre>
-<p>Wrapping all die calls in a handler routine can be useful to see how, and
from
-where, they’re being called, <a href="#perlvar-NAME">perlvar NAME</a>
has more information:
-</p>
-<pre class="verbatim"> BEGIN { $SIG{__DIE__} = sub { require Carp;
Carp::confess(@_) } }
-</pre>
-<p>Various useful techniques for the redirection of STDOUT and STDERR
filehandles
-are explained in <a href="#perlopentut-NAME">perlopentut NAME</a> and <a
href="perlfaq8.html#Top">(perlfaq8)</a>.
-</p>
-<hr>
-<a name="perldebtut-CGI"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut-GUIs" accesskey="n" rel="next">perldebtut GUIs</a>,
Previous: <a href="#perldebtut-OUTPUT-TIPS" accesskey="p" rel="prev">perldebtut
OUTPUT TIPS</a>, Up: <a href="#perldebtut" accesskey="u"
rel="up">perldebtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="CGI"></a>
-<h3 class="section">14.10 CGI</h3>
-
-<p>Just a quick hint here for all those CGI programmers who can’t figure
out how
-on earth to get past that ’waiting for input’ prompt, when running
their CGI
-script from the command-line, try something like this:
-</p>
-<pre class="verbatim"> > perl -d my_cgi.pl -nodebug
-</pre>
-<p>Of course <a href="CGI.html#Top">(CGI)</a> and <a
href="perlfaq9.html#Top">(perlfaq9)</a> will tell you more.
-</p>
-<hr>
-<a name="perldebtut-GUIs"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut-SUMMARY" accesskey="n" rel="next">perldebtut
SUMMARY</a>, Previous: <a href="#perldebtut-CGI" accesskey="p"
rel="prev">perldebtut CGI</a>, Up: <a href="#perldebtut" accesskey="u"
rel="up">perldebtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="GUIs"></a>
-<h3 class="section">14.11 GUIs</h3>
-
-<p>The command line interface is tightly integrated with an
<strong>emacs</strong> extension
-and there’s a <strong>vi</strong> interface too.
-</p>
-<p>You don’t have to do this all on the command line, though, there are
a few GUI
-options out there. The nice thing about these is you can wave a mouse over a
-variable and a dump of its data will appear in an appropriate window, or in a
-popup balloon, no more tiresome typing of ’x $varname’ :-)
-</p>
-<p>In particular have a hunt around for the following:
-</p>
-<p><strong>ptkdb</strong> perlTK based wrapper for the built-in debugger
-</p>
-<p><strong>ddd</strong> data display debugger
-</p>
-<p><strong>PerlDevKit</strong> and <strong>PerlBuilder</strong> are NT specific
-</p>
-<p>NB. (more info on these and others would be appreciated).
-</p>
-<hr>
-<a name="perldebtut-SUMMARY"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut-SEE-ALSO" accesskey="n" rel="next">perldebtut SEE
ALSO</a>, Previous: <a href="#perldebtut-GUIs" accesskey="p"
rel="prev">perldebtut GUIs</a>, Up: <a href="#perldebtut" accesskey="u"
rel="up">perldebtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SUMMARY"></a>
-<h3 class="section">14.12 SUMMARY</h3>
-
-<p>We’ve seen how to encourage good coding practices with <strong>use
strict</strong> and
-<strong>-w</strong>. We can run the perl debugger <strong>perl -d
scriptname</strong> to inspect your
-data from within the perl debugger with the <strong>p</strong> and
<strong>x</strong> commands. You can
-walk through your code, set breakpoints with <strong>b</strong> and step
through that code
-with <strong>s</strong> or <strong>n</strong>, continue with
<strong>c</strong> and return from a sub with <strong>r</strong>. Fairly
-intuitive stuff when you get down to it.
-</p>
-<p>There is of course lots more to find out about, this has just scratched the
-surface. The best way to learn more is to use perldoc to find out more about
-the language, to read the on-line help (<a href="#perldebug-NAME">perldebug
NAME</a> is probably the next
-place to go), and of course, experiment.
-</p>
-<hr>
-<a name="perldebtut-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut-AUTHOR" accesskey="n" rel="next">perldebtut
AUTHOR</a>, Previous: <a href="#perldebtut-SUMMARY" accesskey="p"
rel="prev">perldebtut SUMMARY</a>, Up: <a href="#perldebtut" accesskey="u"
rel="up">perldebtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-7"></a>
-<h3 class="section">14.13 SEE ALSO</h3>
-
-<p><a href="#perldebug-NAME">perldebug NAME</a>,
-<a href="#perldebguts-NAME">perldebguts NAME</a>,
-<a href="#perldiag-NAME">perldiag NAME</a>,
-<a href="#perlrun-NAME">perlrun NAME</a>
-</p>
-<hr>
-<a name="perldebtut-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebtut-CONTRIBUTORS" accesskey="n" rel="next">perldebtut
CONTRIBUTORS</a>, Previous: <a href="#perldebtut-SEE-ALSO" accesskey="p"
rel="prev">perldebtut SEE ALSO</a>, Up: <a href="#perldebtut" accesskey="u"
rel="up">perldebtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-5"></a>
-<h3 class="section">14.14 AUTHOR</h3>
-
-<p>Richard Foley <address@hidden> Copyright (c) 2000
-</p>
-<hr>
-<a name="perldebtut-CONTRIBUTORS"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldebtut-AUTHOR" accesskey="p" rel="prev">perldebtut
AUTHOR</a>, Up: <a href="#perldebtut" accesskey="u" rel="up">perldebtut</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="CONTRIBUTORS"></a>
-<h3 class="section">14.15 CONTRIBUTORS</h3>
-
-<p>Various people have made helpful suggestions and contributions, in
particular:
-</p>
-<p>Ronald J Kimball <address@hidden>
-</p>
-<p>Hugo van der Sanden <address@hidden>
-</p>
-<p>Peter Scott <address@hidden>
-</p>
-<hr>
-<a name="perldebug"></a>
-<div class="header">
-<p>
-Next: <a href="#perldiag" accesskey="n" rel="next">perldiag</a>, Previous: <a
href="#perldebtut" accesskey="p" rel="prev">perldebtut</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perldebug-1"></a>
-<h2 class="chapter">15 perldebug</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perldebug-NAME"
accesskey="1">perldebug NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebug-DESCRIPTION"
accesskey="2">perldebug DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-The-Perl-Debugger" accesskey="3">perldebug The Perl
Debugger</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Debugging-Regular-Expressions" accesskey="4">perldebug
Debugging Regular Expressions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Debugging-Memory-Usage" accesskey="5">perldebug Debugging
Memory Usage</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebug-SEE-ALSO"
accesskey="6">perldebug SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldebug-BUGS"
accesskey="7">perldebug BUGS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldebug-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug-DESCRIPTION" accesskey="n" rel="next">perldebug
DESCRIPTION</a>, Up: <a href="#perldebug" accesskey="u" rel="up">perldebug</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-14"></a>
-<h3 class="section">15.1 NAME</h3>
-
-<p>perldebug - Perl debugging
-</p>
-<hr>
-<a name="perldebug-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug-The-Perl-Debugger" accesskey="n"
rel="next">perldebug The Perl Debugger</a>, Previous: <a href="#perldebug-NAME"
accesskey="p" rel="prev">perldebug NAME</a>, Up: <a href="#perldebug"
accesskey="u" rel="up">perldebug</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-14"></a>
-<h3 class="section">15.2 DESCRIPTION</h3>
-
-<p>First of all, have you tried using the <strong>-w</strong> switch?
-</p>
-<p>If you’re new to the Perl debugger, you may prefer to read
-<a href="#perldebtut-NAME">perldebtut NAME</a>, which is a tutorial
introduction to the debugger.
-</p>
-<hr>
-<a name="perldebug-The-Perl-Debugger"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug-Debugging-Regular-Expressions" accesskey="n"
rel="next">perldebug Debugging Regular Expressions</a>, Previous: <a
href="#perldebug-DESCRIPTION" accesskey="p" rel="prev">perldebug
DESCRIPTION</a>, Up: <a href="#perldebug" accesskey="u" rel="up">perldebug</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-Perl-Debugger"></a>
-<h3 class="section">15.3 The Perl Debugger</h3>
-
-<p>If you invoke Perl with the <strong>-d</strong> switch, your script runs
under the
-Perl source debugger. This works like an interactive Perl
-environment, prompting for debugger commands that let you examine
-source code, set breakpoints, get stack backtraces, change the values of
-variables, etc. This is so convenient that you often fire up
-the debugger all by itself just to test out Perl constructs
-interactively to see what they do. For example:
-</p>
-<pre class="verbatim"> $ perl -d -e 42
-</pre>
-<p>In Perl, the debugger is not a separate program the way it usually is in the
-typical compiled environment. Instead, the <strong>-d</strong> flag tells the
compiler
-to insert source information into the parse trees it’s about to hand off
-to the interpreter. That means your code must first compile correctly
-for the debugger to work on it. Then when the interpreter starts up, it
-preloads a special Perl library file containing the debugger.
-</p>
-<p>The program will halt <em>right before</em> the first run-time executable
-statement (but see below regarding compile-time statements) and ask you
-to enter a debugger command. Contrary to popular expectations, whenever
-the debugger halts and shows you a line of code, it always displays the
-line it’s <em>about</em> to execute, rather than the one it has just
executed.
-</p>
-<p>Any command not recognized by the debugger is directly executed
-(<code>eval</code>’d) as Perl code in the current package. (The debugger
-uses the DB package for keeping its own state information.)
-</p>
-<p>Note that the said <code>eval</code> is bound by an implicit scope. As a
-result any newly introduced lexical variable or any modified
-capture buffer content is lost after the eval. The debugger is a
-nice environment to learn Perl, but if you interactively experiment using
-material which should be in the same scope, stuff it in one line.
-</p>
-<p>For any text entered at the debugger prompt, leading and trailing whitespace
-is first stripped before further processing. If a debugger command
-coincides with some function in your own program, merely precede the
-function with something that doesn’t look like a debugger command, such
-as a leading <code>;</code> or perhaps a <code>+</code>, or by wrapping it
with parentheses
-or braces.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perldebug-Calling-the-Debugger" accesskey="1">perldebug Calling the
Debugger</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Debugger-Commands" accesskey="2">perldebug Debugger
Commands</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Configurable-Options" accesskey="3">perldebug Configurable
Options</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Debugger-Input_002fOutput" accesskey="4">perldebug Debugger
Input/Output</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Debugging-Compile_002dTime-Statements" accesskey="5">perldebug
Debugging Compile-Time Statements</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Debugger-Customization" accesskey="6">perldebug Debugger
Customization</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Readline-Support-_002f-History-in-the-Debugger"
accesskey="7">perldebug Readline Support / History in the
Debugger</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-Editor-Support-for-Debugging" accesskey="8">perldebug Editor
Support for Debugging</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldebug-The-Perl-Profiler" accesskey="9">perldebug The Perl
Profiler</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldebug-Calling-the-Debugger"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug-Debugger-Commands" accesskey="n"
rel="next">perldebug Debugger Commands</a>, Up: <a
href="#perldebug-The-Perl-Debugger" accesskey="u" rel="up">perldebug The Perl
Debugger</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Calling-the-Debugger"></a>
-<h4 class="subsection">15.3.1 Calling the Debugger</h4>
-
-<p>There are several ways to call the debugger:
-</p>
-<dl compact="compact">
-<dt>perl -d program_name</dt>
-<dd><a name="perldebug-perl-_002dd-program_005fname"></a>
-<p>On the given program identified by <code>program_name</code>.
-</p>
-</dd>
-<dt>perl -d -e 0</dt>
-<dd><a name="perldebug-perl-_002dd-_002de-0"></a>
-<p>Interactively supply an arbitrary <code>expression</code> using
<code>-e</code>.
-</p>
-</dd>
-<dt>perl -d:ptkdb program_name</dt>
-<dd><a name="perldebug-perl-_002dd_003aptkdb-program_005fname"></a>
-<p>Debug a given program via the <code>Devel::ptkdb</code> GUI.
-</p>
-</dd>
-<dt>perl -dt threaded_program_name</dt>
-<dd><a name="perldebug-perl-_002ddt-threaded_005fprogram_005fname"></a>
-<p>Debug a given program using threads (experimental).
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perldebug-Debugger-Commands"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug-Configurable-Options" accesskey="n"
rel="next">perldebug Configurable Options</a>, Previous: <a
href="#perldebug-Calling-the-Debugger" accesskey="p" rel="prev">perldebug
Calling the Debugger</a>, Up: <a href="#perldebug-The-Perl-Debugger"
accesskey="u" rel="up">perldebug The Perl Debugger</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Debugger-Commands"></a>
-<h4 class="subsection">15.3.2 Debugger Commands</h4>
-
-<p>The interactive debugger understands the following commands:
-</p>
-<dl compact="compact">
-<dt>h</dt>
-<dd><a name="perldebug-h"></a>
-<p>Prints out a summary help message
-</p>
-</dd>
-<dt>h [command]</dt>
-<dd><a name="perldebug-h-_005bcommand_005d"></a>
-<p>Prints out a help message for the given debugger command.
-</p>
-</dd>
-<dt>h h</dt>
-<dd><a name="perldebug-h-h"></a>
-<p>The special argument of <code>h h</code> produces the entire help page,
which is quite long.
-</p>
-<p>If the output of the <code>h h</code> command (or any command, for that
matter) scrolls
-past your screen, precede the command with a leading pipe symbol so
-that it’s run through your pager, as in
-</p>
-<pre class="verbatim"> DB> |h h
-</pre>
-<p>You may change the pager which is used via <code>o pager=...</code> command.
-</p>
-</dd>
-<dt>p expr</dt>
-<dd><a name="perldebug-p-expr"></a>
-<p>Same as <code>print {$DB::OUT} expr</code> in the current package. In
particular,
-because this is just Perl’s own <code>print</code> function, this means
that nested
-data structures and objects are not dumped, unlike with the <code>x</code>
command.
-</p>
-<p>The <code>DB::OUT</code> filehandle is opened to <samp>/dev/tty</samp>,
regardless of
-where STDOUT may be redirected to.
-</p>
-</dd>
-<dt>x [maxdepth] expr</dt>
-<dd><a name="perldebug-x-_005bmaxdepth_005d-expr"></a>
-<p>Evaluates its expression in list context and dumps out the result in a
-pretty-printed fashion. Nested data structures are printed out
-recursively, unlike the real <code>print</code> function in Perl. When dumping
-hashes, you’ll probably prefer ’x \%h’ rather than ’x
%h’.
-See <a href="Dumpvalue.html#Top">(Dumpvalue)</a> if you’d like to do
this yourself.
-</p>
-<p>The output format is governed by multiple options described under
-<a href="#perldebug-Configurable-Options">Configurable Options</a>.
-</p>
-<p>If the <code>maxdepth</code> is included, it must be a numeral <em>N</em>;
the value is
-dumped only <em>N</em> levels deep, as if the <code>dumpDepth</code> option
had been
-temporarily set to <em>N</em>.
-</p>
-</dd>
-<dt>V [pkg [vars]]</dt>
-<dd><a name="perldebug-V-_005bpkg-_005bvars_005d_005d"></a>
-<p>Display all (or some) variables in package (defaulting to <code>main</code>)
-using a data pretty-printer (hashes show their keys and values so
-you see what’s what, control characters are made printable, etc.).
-Make sure you don’t put the type specifier (like <code>$</code>) there,
just
-the symbol names, like this:
-</p>
-<pre class="verbatim"> V DB filename line
-</pre>
-<p>Use <code>~pattern</code> and <code>!pattern</code> for positive and
negative regexes.
-</p>
-<p>This is similar to calling the <code>x</code> command on each applicable
var.
-</p>
-</dd>
-<dt>X [vars]</dt>
-<dd><a name="perldebug-X-_005bvars_005d"></a>
-<p>Same as <code>V currentpackage [vars]</code>.
-</p>
-</dd>
-<dt>y [level [vars]]</dt>
-<dd><a name="perldebug-y-_005blevel-_005bvars_005d_005d"></a>
-<p>Display all (or some) lexical variables (mnemonic: <code>mY</code>
variables)
-in the current scope or <em>level</em> scopes higher. You can limit the
-variables that you see with <em>vars</em> which works exactly as it does
-for the <code>V</code> and <code>X</code> commands. Requires the
<code>PadWalker</code> module
-version 0.08 or higher; will warn if this isn’t installed. Output
-is pretty-printed in the same style as for <code>V</code> and the format is
-controlled by the same options.
-</p>
-</dd>
-<dt>T</dt>
-<dd><a name="perldebug-T"></a>
-<p>Produce a stack backtrace. See below for details on its output.
-</p>
-</dd>
-<dt>s [expr]</dt>
-<dd><a name="perldebug-s-_005bexpr_005d"></a>
-<p>Single step. Executes until the beginning of another
-statement, descending into subroutine calls. If an expression is
-supplied that includes function calls, it too will be single-stepped.
-</p>
-</dd>
-<dt>n [expr]</dt>
-<dd><a name="perldebug-n-_005bexpr_005d"></a>
-<p>Next. Executes over subroutine calls, until the beginning
-of the next statement. If an expression is supplied that includes
-function calls, those functions will be executed with stops before
-each statement.
-</p>
-</dd>
-<dt>r</dt>
-<dd><a name="perldebug-r"></a>
-<p>Continue until the return from the current subroutine.
-Dump the return value if the <code>PrintRet</code> option is set (default).
-</p>
-</dd>
-<dt><CR></dt>
-<dd><a name="perldebug-_003cCR_003e"></a>
-<p>Repeat last <code>n</code> or <code>s</code> command.
-</p>
-</dd>
-<dt>c [line|sub]</dt>
-<dd><a name="perldebug-c-_005bline_007csub_005d"></a>
-<p>Continue, optionally inserting a one-time-only breakpoint
-at the specified line or subroutine.
-</p>
-</dd>
-<dt>l</dt>
-<dd><a name="perldebug-l"></a>
-<p>List next window of lines.
-</p>
-</dd>
-<dt>l min+incr</dt>
-<dd><a name="perldebug-l-min_002bincr"></a>
-<p>List <code>incr+1</code> lines starting at <code>min</code>.
-</p>
-</dd>
-<dt>l min-max</dt>
-<dd><a name="perldebug-l-min_002dmax"></a>
-<p>List lines <code>min</code> through <code>max</code>. <code>l -</code> is
synonymous to <code>-</code>.
-</p>
-</dd>
-<dt>l line</dt>
-<dd><a name="perldebug-l-line"></a>
-<p>List a single line.
-</p>
-</dd>
-<dt>l subname</dt>
-<dd><a name="perldebug-l-subname"></a>
-<p>List first window of lines from subroutine. <em>subname</em> may
-be a variable that contains a code reference.
-</p>
-</dd>
-<dt>-</dt>
-<dd><a name="perldebug-_002d"></a>
-<p>List previous window of lines.
-</p>
-</dd>
-<dt>v [line]</dt>
-<dd><a name="perldebug-v-_005bline_005d"></a>
-<p>View a few lines of code around the current line.
-</p>
-</dd>
-<dt>.</dt>
-<dd><a name="perldebug-_002e"></a>
-<p>Return the internal debugger pointer to the line last
-executed, and print out that line.
-</p>
-</dd>
-<dt>f filename</dt>
-<dd><a name="perldebug-f-filename"></a>
-<p>Switch to viewing a different file or <code>eval</code> statement. If
<em>filename</em>
-is not a full pathname found in the values of %INC, it is considered
-a regex.
-</p>
-<p><code>eval</code>ed strings (when accessible) are considered to be
filenames:
-<code>f (eval 7)</code> and <code>f eval 7\b</code> access the body of the 7th
<code>eval</code>ed string
-(in the order of execution). The bodies of the currently executed
<code>eval</code>
-and of <code>eval</code>ed strings that define subroutines are saved and thus
-accessible.
-</p>
-</dd>
-<dt>/pattern/</dt>
-<dd><a name="perldebug-_002fpattern_002f"></a>
-<p>Search forwards for pattern (a Perl regex); final / is optional.
-The search is case-insensitive by default.
-</p>
-</dd>
-<dt>?pattern?</dt>
-<dd><a name="perldebug-_003fpattern_003f"></a>
-<p>Search backwards for pattern; final ? is optional.
-The search is case-insensitive by default.
-</p>
-</dd>
-<dt>L [abw]</dt>
-<dd><a name="perldebug-L-_005babw_005d"></a>
-<p>List (default all) actions, breakpoints and watch expressions
-</p>
-</dd>
-<dt>S [[!]regex]</dt>
-<dd><a name="perldebug-S-_005b_005b_0021_005dregex_005d"></a>
-<p>List subroutine names [not] matching the regex.
-</p>
-</dd>
-<dt>t [n]</dt>
-<dd><a name="perldebug-t-_005bn_005d"></a>
-<p>Toggle trace mode (see also the <code>AutoTrace</code> option).
-Optional argument is the maximum number of levels to trace below
-the current one; anything deeper than that will be silent.
-</p>
-</dd>
-<dt>t [n] expr</dt>
-<dd><a name="perldebug-t-_005bn_005d-expr"></a>
-<p>Trace through execution of <code>expr</code>.
-Optional first argument is the maximum number of levels to trace below
-the current one; anything deeper than that will be silent.
-See <a href="#perldebguts-Frame-Listing-Output-Examples">perldebguts Frame
Listing Output Examples</a> for examples.
-</p>
-</dd>
-<dt>b</dt>
-<dd><a name="perldebug-b"></a>
-<p>Sets breakpoint on current line
-</p>
-</dd>
-<dt>b [line] [condition]</dt>
-<dd><a name="perldebug-b-_005bline_005d-_005bcondition_005d"></a>
-<p>Set a breakpoint before the given line. If a condition
-is specified, it’s evaluated each time the statement is reached: a
-breakpoint is taken only if the condition is true. Breakpoints may
-only be set on lines that begin an executable statement. Conditions
-don’t use <code>if</code>:
-</p>
-<pre class="verbatim"> b 237 $x > 30
- b 237 ++$count237 < 11
- b 33 /pattern/i
-</pre>
-<p>If the line number is <code>.</code>, sets a breakpoint on the current line:
-</p>
-<pre class="verbatim"> b . $n > 100
-</pre>
-</dd>
-<dt>b [file]:[line] [condition]</dt>
-<dd><a
name="perldebug-b-_005bfile_005d_003a_005bline_005d-_005bcondition_005d"></a>
-<p>Set a breakpoint before the given line in a (possibly different) file. If a
-condition is specified, it’s evaluated each time the statement is
reached: a
-breakpoint is taken only if the condition is true. Breakpoints may only be set
-on lines that begin an executable statement. Conditions don’t use
<code>if</code>:
-</p>
-<pre class="verbatim"> b lib/MyModule.pm:237 $x > 30
- b /usr/lib/perl5/site_perl/CGI.pm:100 ++$count100 < 11
-</pre>
-</dd>
-<dt>b subname [condition]</dt>
-<dd><a name="perldebug-b-subname-_005bcondition_005d"></a>
-<p>Set a breakpoint before the first line of the named subroutine.
<em>subname</em> may
-be a variable containing a code reference (in this case <em>condition</em>
-is not supported).
-</p>
-</dd>
-<dt>b postpone subname [condition]</dt>
-<dd><a name="perldebug-b-postpone-subname-_005bcondition_005d"></a>
-<p>Set a breakpoint at first line of subroutine after it is compiled.
-</p>
-</dd>
-<dt>b load filename</dt>
-<dd><a name="perldebug-b-load-filename"></a>
-<p>Set a breakpoint before the first executed line of the <em>filename</em>,
-which should be a full pathname found amongst the %INC values.
-</p>
-</dd>
-<dt>b compile subname</dt>
-<dd><a name="perldebug-b-compile-subname"></a>
-<p>Sets a breakpoint before the first statement executed after the specified
-subroutine is compiled.
-</p>
-</dd>
-<dt>B line</dt>
-<dd><a name="perldebug-B-line"></a>
-<p>Delete a breakpoint from the specified <em>line</em>.
-</p>
-</dd>
-<dt>B *</dt>
-<dd><a name="perldebug-B-_002a"></a>
-<p>Delete all installed breakpoints.
-</p>
-</dd>
-<dt>disable [file]:[line]</dt>
-<dd><a name="perldebug-disable-_005bfile_005d_003a_005bline_005d"></a>
-<p>Disable the breakpoint so it won’t stop the execution of the program.
-Breakpoints are enabled by default and can be re-enabled using the
<code>enable</code>
-command.
-</p>
-</dd>
-<dt>disable [line]</dt>
-<dd><a name="perldebug-disable-_005bline_005d"></a>
-<p>Disable the breakpoint so it won’t stop the execution of the program.
-Breakpoints are enabled by default and can be re-enabled using the
<code>enable</code>
-command.
-</p>
-<p>This is done for a breakpoint in the current file.
-</p>
-</dd>
-<dt>enable [file]:[line]</dt>
-<dd><a name="perldebug-enable-_005bfile_005d_003a_005bline_005d"></a>
-<p>Enable the breakpoint so it will stop the execution of the program.
-</p>
-</dd>
-<dt>enable [line]</dt>
-<dd><a name="perldebug-enable-_005bline_005d"></a>
-<p>Enable the breakpoint so it will stop the execution of the program.
-</p>
-<p>This is done for a breakpoint in the current file.
-</p>
-</dd>
-<dt>a [line] command</dt>
-<dd><a name="perldebug-a-_005bline_005d-command"></a>
-<p>Set an action to be done before the line is executed. If <em>line</em> is
-omitted, set an action on the line about to be executed.
-The sequence of steps taken by the debugger is
-</p>
-<pre class="verbatim"> 1. check for a breakpoint at this line
- 2. print the line if necessary (tracing)
- 3. do any actions associated with that line
- 4. prompt user if at a breakpoint or in single-step
- 5. evaluate line
-</pre>
-<p>For example, this will print out $foo every time line
-53 is passed:
-</p>
-<pre class="verbatim"> a 53 print "DB FOUND $foo\n"
-</pre>
-</dd>
-<dt>A line</dt>
-<dd><a name="perldebug-A-line"></a>
-<p>Delete an action from the specified line.
-</p>
-</dd>
-<dt>A *</dt>
-<dd><a name="perldebug-A-_002a"></a>
-<p>Delete all installed actions.
-</p>
-</dd>
-<dt>w expr</dt>
-<dd><a name="perldebug-w-expr"></a>
-<p>Add a global watch-expression. Whenever a watched global changes the
-debugger will stop and display the old and new values.
-</p>
-</dd>
-<dt>W expr</dt>
-<dd><a name="perldebug-W-expr"></a>
-<p>Delete watch-expression
-</p>
-</dd>
-<dt>W *</dt>
-<dd><a name="perldebug-W-_002a"></a>
-<p>Delete all watch-expressions.
-</p>
-</dd>
-<dt>o</dt>
-<dd><a name="perldebug-o"></a>
-<p>Display all options.
-</p>
-</dd>
-<dt>o booloption ...</dt>
-<dd><a name="perldebug-o-booloption-_002e_002e_002e"></a>
-<p>Set each listed Boolean option to the value <code>1</code>.
-</p>
-</dd>
-<dt>o anyoption? ...</dt>
-<dd><a name="perldebug-o-anyoption_003f-_002e_002e_002e"></a>
-<p>Print out the value of one or more options.
-</p>
-</dd>
-<dt>o option=value ...</dt>
-<dd><a name="perldebug-o-option_003dvalue-_002e_002e_002e"></a>
-<p>Set the value of one or more options. If the value has internal
-whitespace, it should be quoted. For example, you could set <code>o
-pager="less -MQeicsNfr"</code> to call <strong>less</strong> with
those specific options.
-You may use either single or double quotes, but if you do, you must
-escape any embedded instances of same sort of quote you began with,
-as well as any escaping any escapes that immediately precede that
-quote but which are not meant to escape the quote itself. In other
-words, you follow single-quoting rules irrespective of the quote;
-eg: <code>o option='this isn\'t bad'</code> or <code>o option="She said,
\"Isn't
-it?\""</code>.
-</p>
-<p>For historical reasons, the <code>=value</code> is optional, but defaults to
-1 only where it is safe to do so–that is, mostly for Boolean
-options. It is always better to assign a specific value using <code>=</code>.
-The <code>option</code> can be abbreviated, but for clarity probably should
-not be. Several options can be set together. See <a
href="#perldebug-Configurable-Options">Configurable Options</a>
-for a list of these.
-</p>
-</dd>
-<dt>< ?</dt>
-<dd><a name="perldebug-_003c-_003f"></a>
-<p>List out all pre-prompt Perl command actions.
-</p>
-</dd>
-<dt>< [ command ]</dt>
-<dd><a name="perldebug-_003c-_005b-command-_005d"></a>
-<p>Set an action (Perl command) to happen before every debugger prompt.
-A multi-line command may be entered by backslashing the newlines.
-</p>
-</dd>
-<dt>< *</dt>
-<dd><a name="perldebug-_003c-_002a"></a>
-<p>Delete all pre-prompt Perl command actions.
-</p>
-</dd>
-<dt><< command</dt>
-<dd><a name="perldebug-_003c_003c-command"></a>
-<p>Add an action (Perl command) to happen before every debugger prompt.
-A multi-line command may be entered by backwhacking the newlines.
-</p>
-</dd>
-<dt>> ? >></dt>
-<dd><a name="perldebug-_003e-_003f-_003e_003e"></a>
-<p>List out post-prompt Perl command actions.
-</p>
-</dd>
-<dt>> command >></dt>
-<dd><a name="perldebug-_003e-command-_003e_003e"></a>
-<p>Set an action (Perl command) to happen after the prompt when you’ve
-just given a command to return to executing the script. A multi-line
-command may be entered by backslashing the newlines (we bet you
-couldn’t have guessed this by now).
-</p>
-</dd>
-<dt>> * >></dt>
-<dd><a name="perldebug-_003e-_002a-_003e_003e"></a>
-<p>Delete all post-prompt Perl command actions.
-</p>
-</dd>
-<dt>>> command >>></dt>
-<dd><a name="perldebug-_003e_003e-command-_003e_003e_003e"></a>
-<p>Adds an action (Perl command) to happen after the prompt when you’ve
-just given a command to return to executing the script. A multi-line
-command may be entered by backslashing the newlines.
-</p>
-</dd>
-<dt>{ ?</dt>
-<dd><a name="perldebug-_007b-_003f"></a>
-<p>List out pre-prompt debugger commands.
-</p>
-</dd>
-<dt>{ [ command ]</dt>
-<dd><a name="perldebug-_007b-_005b-command-_005d"></a>
-<p>Set an action (debugger command) to happen before every debugger prompt.
-A multi-line command may be entered in the customary fashion.
-</p>
-<p>Because this command is in some senses new, a warning is issued if
-you appear to have accidentally entered a block instead. If that’s
-what you mean to do, write it as with <code>;{ ... }</code> or even
-<code>do { ... }</code>.
-</p>
-</dd>
-<dt>{ *</dt>
-<dd><a name="perldebug-_007b-_002a"></a>
-<p>Delete all pre-prompt debugger commands.
-</p>
-</dd>
-<dt>{{ command</dt>
-<dd><a name="perldebug-_007b_007b-command"></a>
-<p>Add an action (debugger command) to happen before every debugger prompt.
-A multi-line command may be entered, if you can guess how: see above.
-</p>
-</dd>
-<dt>! number</dt>
-<dd><a name="perldebug-_0021-number"></a>
-<p>Redo a previous command (defaults to the previous command).
-</p>
-</dd>
-<dt>! -number</dt>
-<dd><a name="perldebug-_0021-_002dnumber"></a>
-<p>Redo number’th previous command.
-</p>
-</dd>
-<dt>! pattern</dt>
-<dd><a name="perldebug-_0021-pattern"></a>
-<p>Redo last command that started with pattern.
-See <code>o recallCommand</code>, too.
-</p>
-</dd>
-<dt>!! cmd</dt>
-<dd><a name="perldebug-_0021_0021-cmd"></a>
-<p>Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See
-<code>o shellBang</code>, also. Note that the user’s current shell
(well,
-their <code>$ENV{SHELL}</code> variable) will be used, which can interfere
-with proper interpretation of exit status or signal and coredump
-information.
-</p>
-</dd>
-<dt>source file</dt>
-<dd><a name="perldebug-source-file"></a>
-<p>Read and execute debugger commands from <em>file</em>.
-<em>file</em> may itself contain <code>source</code> commands.
-</p>
-</dd>
-<dt>H -number</dt>
-<dd><a name="perldebug-H-_002dnumber"></a>
-<p>Display last n commands. Only commands longer than one character are
-listed. If <em>number</em> is omitted, list them all.
-</p>
-</dd>
-<dt>q or ^D</dt>
-<dd><a name="perldebug-q-or-_005eD"></a>
-<p>Quit. ("quit" doesn’t work for this, unless you’ve
made an alias)
-This is the only supported way to exit the debugger, though typing
-<code>exit</code> twice might work.
-</p>
-<p>Set the <code>inhibit_exit</code> option to 0 if you want to be able to step
-off the end the script. You may also need to set $finished to 0
-if you want to step through global destruction.
-</p>
-</dd>
-<dt>R</dt>
-<dd><a name="perldebug-R"></a>
-<p>Restart the debugger by <code>exec()</code>ing a new session. We try to
maintain
-your history across this, but internal settings and command-line options
-may be lost.
-</p>
-<p>The following setting are currently preserved: history, breakpoints,
-actions, debugger options, and the Perl command-line
-options <strong>-w</strong>, <strong>-I</strong>, and <strong>-e</strong>.
-</p>
-</dd>
-<dt>|dbcmd</dt>
-<dd><a name="perldebug-_007cdbcmd"></a>
-<p>Run the debugger command, piping DB::OUT into your current pager.
-</p>
-</dd>
-<dt>||dbcmd</dt>
-<dd><a name="perldebug-_007c_007cdbcmd"></a>
-<p>Same as <code>|dbcmd</code> but DB::OUT is temporarily
<code>select</code>ed as well.
-</p>
-</dd>
-<dt>= [alias value]</dt>
-<dd><a name="perldebug-_003d-_005balias-value_005d"></a>
-<p>Define a command alias, like
-</p>
-<pre class="verbatim"> = quit q
-</pre>
-<p>or list current aliases.
-</p>
-</dd>
-<dt>command</dt>
-<dd><a name="perldebug-command"></a>
-<p>Execute command as a Perl statement. A trailing semicolon will be
-supplied. If the Perl statement would otherwise be confused for a
-Perl debugger, use a leading semicolon, too.
-</p>
-</dd>
-<dt>m expr</dt>
-<dd><a name="perldebug-m-expr"></a>
-<p>List which methods may be called on the result of the evaluated
-expression. The expression may evaluated to a reference to a
-blessed object, or to a package name.
-</p>
-</dd>
-<dt>M</dt>
-<dd><a name="perldebug-M"></a>
-<p>Display all loaded modules and their versions.
-</p>
-</dd>
-<dt>man [manpage]</dt>
-<dd><a name="perldebug-man-_005bmanpage_005d"></a>
-<p>Despite its name, this calls your system’s default documentation
-viewer on the given page, or on the viewer itself if <em>manpage</em> is
-omitted. If that viewer is <strong>man</strong>, the current
<code>Config</code> information
-is used to invoke <strong>man</strong> using the proper MANPATH or
<strong><span class="nolinebreak">-M</span></strong> <em>manpath</em><!--
/@w --> option. Failed lookups of the form <code>XXX</code> that match
-known manpages of the form <em>perlXXX</em> will be retried. This lets
-you type <code>man debug</code> or <code>man op</code> from the debugger.
-</p>
-<p>On systems traditionally bereft of a usable <strong>man</strong> command,
the
-debugger invokes <strong>perldoc</strong>. Occasionally this determination is
-incorrect due to recalcitrant vendors or rather more felicitously,
-to enterprising users. If you fall into either category, just
-manually set the $DB::doccmd variable to whatever viewer to view
-the Perl documentation on your system. This may be set in an rc
-file, or through direct assignment. We’re still waiting for a
-working example of something along the lines of:
-</p>
-<pre class="verbatim"> $DB::doccmd = 'netscape -remote
http://something.here/';
-</pre>
-</dd>
-</dl>
-
-<hr>
-<a name="perldebug-Configurable-Options"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug-Debugger-Input_002fOutput" accesskey="n"
rel="next">perldebug Debugger Input/Output</a>, Previous: <a
href="#perldebug-Debugger-Commands" accesskey="p" rel="prev">perldebug Debugger
Commands</a>, Up: <a href="#perldebug-The-Perl-Debugger" accesskey="u"
rel="up">perldebug The Perl Debugger</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Configurable-Options"></a>
-<h4 class="subsection">15.3.3 Configurable Options</h4>
-
-<p>The debugger has numerous options settable using the <code>o</code> command,
-either interactively or from the environment or an rc file.
-(./.perldb or ~/.perldb under Unix.)
-</p>
-<dl compact="compact">
-<dt><code>recallCommand</code>, <code>ShellBang</code></dt>
-<dd><a name="perldebug-recallCommand_002c-ShellBang"></a>
-<p>The characters used to recall a command or spawn a shell. By
-default, both are set to <code>!</code>, which is unfortunate.
-</p>
-</dd>
-<dt><code>pager</code></dt>
-<dd><a name="perldebug-pager"></a>
-<p>Program to use for output of pager-piped commands (those beginning
-with a <code>|</code> character.) By default, <code>$ENV{PAGER}</code> will
be used.
-Because the debugger uses your current terminal characteristics
-for bold and underlining, if the chosen pager does not pass escape
-sequences through unchanged, the output of some debugger commands
-will not be readable when sent through the pager.
-</p>
-</dd>
-<dt><code>tkRunning</code></dt>
-<dd><a name="perldebug-tkRunning"></a>
-<p>Run Tk while prompting (with ReadLine).
-</p>
-</dd>
-<dt><code>signalLevel</code>, <code>warnLevel</code>,
<code>dieLevel</code></dt>
-<dd><a name="perldebug-signalLevel_002c-warnLevel_002c-dieLevel"></a>
-<p>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 <a
href="#perldebug-BUGS">BUGS</a> below.)
-</p>
-<p>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
-of warning (this is often annoying) or exception (this is
-often valuable). Unfortunately, the debugger cannot discern fatal
-exceptions from non-fatal ones. If <code>dieLevel</code> is even 1, then your
-non-fatal exceptions are also traced and unceremoniously altered if they
-came from <code>eval'ed</code> strings or from any kind of <code>eval</code>
within modules
-you’re attempting to load. If <code>dieLevel</code> is 2, the debugger
doesn’t
-care where they came from: It usurps your exception handler and prints
-out a trace, then modifies all exceptions with its own embellishments.
-This may perhaps be useful for some tracing purposes, but tends to hopelessly
-destroy any program that takes its exception handling seriously.
-</p>
-</dd>
-<dt><code>AutoTrace</code></dt>
-<dd><a name="perldebug-AutoTrace"></a>
-<p>Trace mode (similar to <code>t</code> command, but can be put into
-<code>PERLDB_OPTS</code>).
-</p>
-</dd>
-<dt><code>LineInfo</code></dt>
-<dd><a name="perldebug-LineInfo"></a>
-<p>File or pipe to print line number info to. If it is a pipe (say,
-<code>|visual_perl_db</code>), then a short message is used. This is the
-mechanism used to interact with a slave editor or visual debugger,
-such as the special <code>vi</code> or <code>emacs</code> hooks, or the
<code>ddd</code> graphical
-debugger.
-</p>
-</dd>
-<dt><code>inhibit_exit</code></dt>
-<dd><a name="perldebug-inhibit_005fexit"></a>
-<p>If 0, allows <em>stepping off</em> the end of the script.
-</p>
-</dd>
-<dt><code>PrintRet</code></dt>
-<dd><a name="perldebug-PrintRet"></a>
-<p>Print return value after <code>r</code> command if set (default).
-</p>
-</dd>
-<dt><code>ornaments</code></dt>
-<dd><a name="perldebug-ornaments"></a>
-<p>Affects screen appearance of the command line (see <a
href="Term-ReadLine.html#Top">(Term-ReadLine)</a>).
-There is currently no way to disable these, which can render
-some output illegible on some displays, or with some pagers.
-This is considered a bug.
-</p>
-</dd>
-<dt><code>frame</code></dt>
-<dd><a name="perldebug-frame"></a>
-<p>Affects the printing of messages upon entry and exit from subroutines. If
-<code>frame & 2</code> is false, messages are printed on entry only.
(Printing
-on exit might be useful if interspersed with other messages.)
-</p>
-<p>If <code>frame & 4</code>, arguments to functions are printed, plus
context
-and caller info. If <code>frame & 8</code>, overloaded
<code>stringify</code> and
-<code>tie</code>d <code>FETCH</code> is enabled on the printed arguments. If
<code>frame
-& 16</code>, the return value from the subroutine is printed.
-</p>
-<p>The length at which the argument list is truncated is governed by the
-next option:
-</p>
-</dd>
-<dt><code>maxTraceLen</code></dt>
-<dd><a name="perldebug-maxTraceLen"></a>
-<p>Length to truncate the argument list when the <code>frame</code>
option’s
-bit 4 is set.
-</p>
-</dd>
-<dt><code>windowSize</code></dt>
-<dd><a name="perldebug-windowSize"></a>
-<p>Change the size of code list window (default is 10 lines).
-</p>
-</dd>
-</dl>
-
-<p>The following options affect what happens with <code>V</code>,
<code>X</code>, and <code>x</code>
-commands:
-</p>
-<dl compact="compact">
-<dt><code>arrayDepth</code>, <code>hashDepth</code></dt>
-<dd><a name="perldebug-arrayDepth_002c-hashDepth"></a>
-<p>Print only first N elements (” for all).
-</p>
-</dd>
-<dt><code>dumpDepth</code></dt>
-<dd><a name="perldebug-dumpDepth"></a>
-<p>Limit recursion depth to N levels when dumping structures.
-Negative values are interpreted as infinity. Default: infinity.
-</p>
-</dd>
-<dt><code>compactDump</code>, <code>veryCompact</code></dt>
-<dd><a name="perldebug-compactDump_002c-veryCompact"></a>
-<p>Change the style of array and hash output. If <code>compactDump</code>,
short array
-may be printed on one line.
-</p>
-</dd>
-<dt><code>globPrint</code></dt>
-<dd><a name="perldebug-globPrint"></a>
-<p>Whether to print contents of globs.
-</p>
-</dd>
-<dt><code>DumpDBFiles</code></dt>
-<dd><a name="perldebug-DumpDBFiles"></a>
-<p>Dump arrays holding debugged files.
-</p>
-</dd>
-<dt><code>DumpPackages</code></dt>
-<dd><a name="perldebug-DumpPackages"></a>
-<p>Dump symbol tables of packages.
-</p>
-</dd>
-<dt><code>DumpReused</code></dt>
-<dd><a name="perldebug-DumpReused"></a>
-<p>Dump contents of "reused" addresses.
-</p>
-</dd>
-<dt><code>quote</code>, <code>HighBit</code>, <code>undefPrint</code></dt>
-<dd><a name="perldebug-quote_002c-HighBit_002c-undefPrint"></a>
-<p>Change the style of string dump. The default value for <code>quote</code>
-is <code>auto</code>; one can enable double-quotish or single-quotish format
-by setting it to <code>"</code> or <code>'</code>, respectively. By
default, characters
-with their high bit set are printed verbatim.
-</p>
-</dd>
-<dt><code>UsageOnly</code></dt>
-<dd><a name="perldebug-UsageOnly"></a>
-<p>Rudimentary per-package memory usage dump. Calculates total
-size of strings found in variables in the package. This does not
-include lexicals in a module’s file scope, or lost in closures.
-</p>
-</dd>
-<dt><code>HistFile</code></dt>
-<dd><a name="perldebug-HistFile"></a>
-<p>The path of the file from which the history (assuming a usable
-Term::ReadLine backend) will be read on the debugger’s startup, and to
which
-it will be saved on shutdown (for persistence across sessions). Similar in
-concept to Bash’s <code>.bash_history</code> file.
-</p>
-</dd>
-<dt><code>HistSize</code></dt>
-<dd><a name="perldebug-HistSize"></a>
-<p>The count of the saved lines in the history (assuming <code>HistFile</code>
above).
-</p>
-</dd>
-</dl>
-
-<p>After the rc file is read, the debugger reads the
<code>$ENV{PERLDB_OPTS}</code>
-environment variable and parses this as the remainder of a "O ..."
-line as one might enter at the debugger prompt. You may place the
-initialization options <code>TTY</code>, <code>noTTY</code>,
<code>ReadLine</code>, and <code>NonStop</code>
-there.
-</p>
-<p>If your rc file contains:
-</p>
-<pre class="verbatim"> parse_options("NonStop=1 LineInfo=db.out
AutoTrace");
-</pre>
-<p>then your script will run without human intervention, putting trace
-information into the file <em>db.out</em>. (If you interrupt it, you’d
-better reset <code>LineInfo</code> to <samp>/dev/tty</samp> if you expect to
see anything.)
-</p>
-<dl compact="compact">
-<dt><code>TTY</code></dt>
-<dd><a name="perldebug-TTY"></a>
-<p>The TTY to use for debugging I/O.
-</p>
-</dd>
-<dt><code>noTTY</code></dt>
-<dd><a name="perldebug-noTTY"></a>
-<p>If set, the debugger goes into <code>NonStop</code> mode and will not
connect to a TTY. If
-interrupted (or if control goes to the debugger via explicit setting of
-$DB::signal or $DB::single from the Perl script), it connects to a TTY
-specified in the <code>TTY</code> option at startup, or to a tty found at
-runtime using the <code>Term::Rendezvous</code> module of your choice.
-</p>
-<p>This module should implement a method named <code>new</code> that returns
an object
-with two methods: <code>IN</code> and <code>OUT</code>. These should return
filehandles to use
-for debugging input and output correspondingly. The <code>new</code> method
should
-inspect an argument containing the value of <code>$ENV{PERLDB_NOTTY}</code> at
-startup, or <code>"$ENV{HOME}/.perldbtty$$"</code> otherwise. This
file is not
-inspected for proper ownership, so security hazards are theoretically
-possible.
-</p>
-</dd>
-<dt><code>ReadLine</code></dt>
-<dd><a name="perldebug-ReadLine"></a>
-<p>If false, readline support in the debugger is disabled in order
-to debug applications that themselves use ReadLine.
-</p>
-</dd>
-<dt><code>NonStop</code></dt>
-<dd><a name="perldebug-NonStop"></a>
-<p>If set, the debugger goes into non-interactive mode until interrupted, or
-programmatically by setting $DB::signal or $DB::single.
-</p>
-</dd>
-</dl>
-
-<p>Here’s an example of using the <code>$ENV{PERLDB_OPTS}</code>
variable:
-</p>
-<pre class="verbatim"> $ PERLDB_OPTS="NonStop frame=2" perl -d
myprogram
-</pre>
-<p>That will run the script <strong>myprogram</strong> without human
intervention,
-printing out the call tree with entry and exit points. Note that
-<code>NonStop=1 frame=2</code> is equivalent to <code>N f=2</code>, and that
originally,
-options could be uniquely abbreviated by the first letter (modulo
-the <code>Dump*</code> options). It is nevertheless recommended that you
-always spell them out in full for legibility and future compatibility.
-</p>
-<p>Other examples include
-</p>
-<pre class="verbatim"> $ PERLDB_OPTS="NonStop LineInfo=listing
frame=2" perl -d myprogram
-</pre>
-<p>which runs script non-interactively, printing info on each entry
-into a subroutine and each executed line into the file named
<samp>listing</samp>.
-(If you interrupt it, you would better reset <code>LineInfo</code> to something
-"interactive"!)
-</p>
-<p>Other examples include (using standard shell syntax to show environment
-variable settings):
-</p>
-<pre class="verbatim"> $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace
LineInfo=tperl.out"
- perl -d myprogram )
-</pre>
-<p>which may be useful for debugging a program that uses
<code>Term::ReadLine</code>
-itself. Do not forget to detach your shell from the TTY in the window that
-corresponds to <samp>/dev/ttyXX</samp>, say, by issuing a command like
-</p>
-<pre class="verbatim"> $ sleep 1000000
-</pre>
-<p>See <a href="#perldebguts-Debugger-Internals">perldebguts Debugger
Internals</a> for details.
-</p>
-<hr>
-<a name="perldebug-Debugger-Input_002fOutput"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug-Debugging-Compile_002dTime-Statements" accesskey="n"
rel="next">perldebug Debugging Compile-Time Statements</a>, Previous: <a
href="#perldebug-Configurable-Options" accesskey="p" rel="prev">perldebug
Configurable Options</a>, Up: <a href="#perldebug-The-Perl-Debugger"
accesskey="u" rel="up">perldebug The Perl Debugger</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Debugger-Input_002fOutput"></a>
-<h4 class="subsection">15.3.4 Debugger Input/Output</h4>
-
-<dl compact="compact">
-<dt>Prompt</dt>
-<dd><a name="perldebug-Prompt"></a>
-<p>The debugger prompt is something like
-</p>
-<pre class="verbatim"> DB<8>
-</pre>
-<p>or even
-</p>
-<pre class="verbatim"> DB<<17>>
-</pre>
-<p>where that number is the command number, and which you’d use to
-access with the built-in <strong>csh</strong>-like history mechanism. For
example,
-<code>!17</code> would repeat command number 17. The depth of the angle
-brackets indicates the nesting depth of the debugger. You could
-get more than one set of brackets, for example, if you’d already
-at a breakpoint and then printed the result of a function call that
-itself has a breakpoint, or you step into an expression via <code>s/n/t
-expression</code> command.
-</p>
-</dd>
-<dt>Multiline commands</dt>
-<dd><a name="perldebug-Multiline-commands"></a>
-<p>If you want to enter a multi-line command, such as a subroutine
-definition with several statements or a format, escape the newline
-that would normally end the debugger command with a backslash.
-Here’s an example:
-</p>
-<pre class="verbatim"> DB<1> for (1..4) { \
- cont: print "ok\n"; \
- cont: }
- ok
- ok
- ok
- ok
-</pre>
-<p>Note that this business of escaping a newline is specific to interactive
-commands typed into the debugger.
-</p>
-</dd>
-<dt>Stack backtrace</dt>
-<dd><a name="perldebug-Stack-backtrace"></a>
-<p>Here’s an example of what a stack backtrace via <code>T</code>
command might
-look like:
-</p>
-<pre class="verbatim"> $ = main::infested called from file 'Ambulation.pm'
line 10
- @ = Ambulation::legs(1, 2, 3, 4) called from file 'camel_flea' line 7
- $ = main::pests('bactrian', 4) called from file 'camel_flea' line 4
-</pre>
-<p>The left-hand character up there indicates the context in which the
-function was called, with <code>$</code> and <code>@</code> meaning scalar or
list
-contexts respectively, and <code>.</code> meaning void context (which is
-actually a sort of scalar context). The display above says
-that you were in the function <code>main::infested</code> when you ran the
-stack dump, and that it was called in scalar context from line
-10 of the file <em>Ambulation.pm</em>, but without any arguments at all,
-meaning it was called as <code>&infested</code>. The next stack frame
shows
-that the function <code>Ambulation::legs</code> was called in list context
-from the <em>camel_flea</em> file with four arguments. The last stack
-frame shows that <code>main::pests</code> was called in scalar context,
-also from <em>camel_flea</em>, but from line 4.
-</p>
-<p>If you execute the <code>T</code> command from inside an active
<code>use</code>
-statement, the backtrace will contain both a <code>require</code> frame and
-an <code>eval</code> frame.
-</p>
-</dd>
-<dt>Line Listing Format</dt>
-<dd><a name="perldebug-Line-Listing-Format"></a>
-<p>This shows the sorts of output the <code>l</code> command can produce:
-</p>
-<pre class="verbatim"> DB<<13>> l
- 101: @address@hidden = ();
- 102:b @address@hidden,$pack} = ()
- 103 if(exists $i{$prevpack} || exists $isa{$pack});
- 104 }
- 105
- 106 next
- 107==> if(exists $isa{$pack});
- 108
- 109:a if ($extra-- > 0) {
- 110: %isa = ($pack,1);
-</pre>
-<p>Breakable lines are marked with <code>:</code>. Lines with breakpoints are
-marked by <code>b</code> and those with actions by <code>a</code>. The line
that’s
-about to be executed is marked by <code>==></code>.
-</p>
-<p>Please be aware that code in debugger listings may not look the same
-as your original source code. Line directives and external source
-filters can alter the code before Perl sees it, causing code to move
-from its original positions or take on entirely different forms.
-</p>
-</dd>
-<dt>Frame listing</dt>
-<dd><a name="perldebug-Frame-listing"></a>
-<p>When the <code>frame</code> option is set, the debugger would print entered
(and
-optionally exited) subroutines in different styles. See <a
href="#perldebguts-NAME">perldebguts NAME</a>
-for incredibly long examples of these.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perldebug-Debugging-Compile_002dTime-Statements"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug-Debugger-Customization" accesskey="n"
rel="next">perldebug Debugger Customization</a>, Previous: <a
href="#perldebug-Debugger-Input_002fOutput" accesskey="p" rel="prev">perldebug
Debugger Input/Output</a>, Up: <a href="#perldebug-The-Perl-Debugger"
accesskey="u" rel="up">perldebug The Perl Debugger</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Debugging-Compile_002dTime-Statements"></a>
-<h4 class="subsection">15.3.5 Debugging Compile-Time Statements</h4>
-
-<p>If you have compile-time executable statements (such as code within
-BEGIN, UNITCHECK and CHECK blocks or <code>use</code> statements), these will
-<em>not</em> be stopped by debugger, although <code>require</code>s and INIT
blocks
-will, and compile-time statements can be traced with the <code>AutoTrace</code>
-option set in <code>PERLDB_OPTS</code>). 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:
-</p>
-<pre class="verbatim"> $DB::single = 1;
-</pre>
-<p>If you set <code>$DB::single</code> to 2, it’s equivalent to having
-just typed the <code>n</code> command, whereas a value of 1 means the
<code>s</code>
-command. The <code>$DB::trace</code> variable should be set to 1 to simulate
-having typed the <code>t</code> command.
-</p>
-<p>Another way to debug compile-time code is to start the debugger, set a
-breakpoint on the <em>load</em> of some module:
-</p>
-<pre class="verbatim"> DB<7> b load f:/perllib/lib/Carp.pm
- Will stop on load of 'f:/perllib/lib/Carp.pm'.
-</pre>
-<p>and then restart the debugger using the <code>R</code> command (if
possible). One can use <code>b
-compile subname</code> for the same purpose.
-</p>
-<hr>
-<a name="perldebug-Debugger-Customization"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug-Readline-Support-_002f-History-in-the-Debugger"
accesskey="n" rel="next">perldebug Readline Support / History in the
Debugger</a>, Previous: <a
href="#perldebug-Debugging-Compile_002dTime-Statements" accesskey="p"
rel="prev">perldebug Debugging Compile-Time Statements</a>, Up: <a
href="#perldebug-The-Perl-Debugger" accesskey="u" rel="up">perldebug The Perl
Debugger</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Debugger-Customization"></a>
-<h4 class="subsection">15.3.6 Debugger Customization</h4>
-
-<p>The debugger probably contains enough configuration hooks that you
-won’t ever have to modify it yourself. You may change the behaviour
-of the debugger from within the debugger using its <code>o</code> command, from
-the command line via the <code>PERLDB_OPTS</code> environment variable, and
-from customization files.
-</p>
-<p>You can do some customization by setting up a <samp>.perldb</samp> file,
which
-contains initialization code. For instance, you could make aliases
-like these (the last one is one people expect to be there):
-</p>
-<pre class="verbatim"> $DB::alias{'len'} = 's/^len(.*)/p length($1)/';
- $DB::alias{'stop'} = 's/^stop (at|in)/b/';
- $DB::alias{'ps'} = 's/^ps\b/p scalar /';
- $DB::alias{'quit'} = 's/^quit(\s*)/exit/';
-</pre>
-<p>You can change options from <samp>.perldb</samp> by using calls like this
one;
-</p>
-<pre class="verbatim"> parse_options("NonStop=1 LineInfo=db.out
AutoTrace=1 frame=2");
-</pre>
-<p>The code is executed in the package <code>DB</code>. Note that
<samp>.perldb</samp> is
-processed before processing <code>PERLDB_OPTS</code>. If <samp>.perldb</samp>
defines the
-subroutine <code>afterinit</code>, that function is called after debugger
-initialization ends. <samp>.perldb</samp> may be contained in the current
-directory, or in the home directory. Because this file is sourced
-in by Perl and may contain arbitrary commands, for security reasons,
-it must be owned by the superuser or the current user, and writable
-by no one but its owner.
-</p>
-<p>You can mock TTY input to debugger by adding arbitrary commands to
address@hidden::typeahead. For example, your <samp>.perldb</samp> file might
contain:
-</p>
-<pre class="verbatim"> sub afterinit { push @DB::typeahead, "b
4", "b 6"; }
-</pre>
-<p>Which would attempt to set breakpoints on lines 4 and 6 immediately
-after debugger initialization. Note that @DB::typeahead is not a supported
-interface and is subject to change in future releases.
-</p>
-<p>If you want to modify the debugger, copy <samp>perl5db.pl</samp> from the
-Perl library to another name and hack it to your heart’s content.
-You’ll then want to set your <code>PERL5DB</code> environment variable
to say
-something like this:
-</p>
-<pre class="verbatim"> BEGIN { require "myperl5db.pl" }
-</pre>
-<p>As a last resort, you could also use <code>PERL5DB</code> to customize the
debugger
-by directly setting internal variables or calling debugger functions.
-</p>
-<p>Note that any variables and functions that are not documented in
-this document (or in <a href="#perldebguts-NAME">perldebguts NAME</a>) are
considered for internal
-use only, and as such are subject to change without notice.
-</p>
-<hr>
-<a name="perldebug-Readline-Support-_002f-History-in-the-Debugger"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug-Editor-Support-for-Debugging" accesskey="n"
rel="next">perldebug Editor Support for Debugging</a>, Previous: <a
href="#perldebug-Debugger-Customization" accesskey="p" rel="prev">perldebug
Debugger Customization</a>, Up: <a href="#perldebug-The-Perl-Debugger"
accesskey="u" rel="up">perldebug The Perl Debugger</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Readline-Support-_002f-History-in-the-Debugger"></a>
-<h4 class="subsection">15.3.7 Readline Support / History in the Debugger</h4>
-
-<p>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 those GNU <em>readline</em>(3)
provides.
-Look for these in the <samp>modules/by-module/Term</samp> directory on CPAN.
-These do not support normal <strong>vi</strong> command-line editing, however.
-</p>
-<p>A rudimentary command-line completion is also available, including
-lexical variables in the current scope if the <code>PadWalker</code> module
-is installed.
-</p>
-<p>Without Readline support you may see the symbols "^[[A",
"^[[C", "^[[B",
-"^[[D"", "^H", ... when using the arrow keys and/or
the backspace key.
-</p>
-<hr>
-<a name="perldebug-Editor-Support-for-Debugging"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug-The-Perl-Profiler" accesskey="n"
rel="next">perldebug The Perl Profiler</a>, Previous: <a
href="#perldebug-Readline-Support-_002f-History-in-the-Debugger" accesskey="p"
rel="prev">perldebug Readline Support / History in the Debugger</a>, Up: <a
href="#perldebug-The-Perl-Debugger" accesskey="u" rel="up">perldebug The Perl
Debugger</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Editor-Support-for-Debugging"></a>
-<h4 class="subsection">15.3.8 Editor Support for Debugging</h4>
-
-<p>If you have the GNU’s version of <strong>emacs</strong> installed on
your system,
-it can interact with the Perl debugger to provide an integrated
-software development environment reminiscent of its interactions
-with C debuggers.
-</p>
-<p>Recent versions of Emacs come with a
-start file for making <strong>emacs</strong> act like a
-syntax-directed editor that understands (some of) Perl’s syntax.
-See <a href="perlfaq3.html#Top">(perlfaq3)</a>.
-</p>
-<p>Users of <strong>vi</strong> should also look into <strong>vim</strong> and
<strong>gvim</strong>, the mousey
-and windy version, for coloring of Perl keywords.
-</p>
-<p>Note that only perl can truly parse Perl, so all such CASE tools
-fall somewhat short of the mark, especially if you don’t program
-your Perl as a C programmer might.
-</p>
-<hr>
-<a name="perldebug-The-Perl-Profiler"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldebug-Editor-Support-for-Debugging" accesskey="p"
rel="prev">perldebug Editor Support for Debugging</a>, Up: <a
href="#perldebug-The-Perl-Debugger" accesskey="u" rel="up">perldebug The Perl
Debugger</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-Perl-Profiler"></a>
-<h4 class="subsection">15.3.9 The Perl Profiler</h4>
-
-<p>If you wish to supply an alternative debugger for Perl to run,
-invoke your script with a colon and a package argument given to the
-<strong>-d</strong> flag. Perl’s alternative debuggers include a Perl
profiler,
-<a href="Devel-NYTProf.html#Top">(Devel-NYTProf)</a>, which is available
separately as a CPAN
-distribution. To profile your Perl program in the file <samp>mycode.pl</samp>,
-just type:
-</p>
-<pre class="verbatim"> $ perl -d:NYTProf mycode.pl
-</pre>
-<p>When the script terminates the profiler will create a database of the
-profile information that you can turn into reports using the profiler’s
-tools. See <perlperf> for details.
-</p>
-<hr>
-<a name="perldebug-Debugging-Regular-Expressions"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug-Debugging-Memory-Usage" accesskey="n"
rel="next">perldebug Debugging Memory Usage</a>, Previous: <a
href="#perldebug-The-Perl-Debugger" accesskey="p" rel="prev">perldebug The Perl
Debugger</a>, Up: <a href="#perldebug" accesskey="u" rel="up">perldebug</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Debugging-Regular-Expressions-1"></a>
-<h3 class="section">15.4 Debugging Regular Expressions</h3>
-
-<p><code>use re 'debug'</code> enables you to see the gory details of how the
Perl
-regular expression engine works. In order to understand this typically
-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
-<a href="#perldebguts-Debugging-Regular-Expressions">perldebguts Debugging
Regular Expressions</a>.
-</p>
-<hr>
-<a name="perldebug-Debugging-Memory-Usage"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug-SEE-ALSO" accesskey="n" rel="next">perldebug SEE
ALSO</a>, Previous: <a href="#perldebug-Debugging-Regular-Expressions"
accesskey="p" rel="prev">perldebug Debugging Regular Expressions</a>, Up: <a
href="#perldebug" accesskey="u" rel="up">perldebug</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Debugging-Memory-Usage"></a>
-<h3 class="section">15.5 Debugging Memory Usage</h3>
-
-<p>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 <a href="#perldebguts-Debugging-Perl-Memory-Usage">perldebguts Debugging
Perl Memory Usage</a> for the details.
-</p>
-<hr>
-<a name="perldebug-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perldebug-BUGS" accesskey="n" rel="next">perldebug BUGS</a>,
Previous: <a href="#perldebug-Debugging-Memory-Usage" accesskey="p"
rel="prev">perldebug Debugging Memory Usage</a>, Up: <a href="#perldebug"
accesskey="u" rel="up">perldebug</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-8"></a>
-<h3 class="section">15.6 SEE ALSO</h3>
-
-<p>You did try the <strong>-w</strong> switch, didn’t you?
-</p>
-<p><a href="#perldebtut-NAME">perldebtut NAME</a>,
-<a href="#perldebguts-NAME">perldebguts NAME</a>,
-<a href="re.html#Top">(re)</a>,
-<a href="DB.html#Top">(DB)</a>,
-<a href="Devel-NYTProf.html#Top">(Devel-NYTProf)</a>,
-<a href="Dumpvalue.html#Top">(Dumpvalue)</a>,
-and
-<a href="#perlrun-NAME">perlrun NAME</a>.
-</p>
-<p>When debugging a script that uses #! and is thus normally found in
-$PATH, the -S option causes perl to search $PATH for it, so you don’t
-have to type the path or <code>which $scriptname</code>.
-</p>
-<pre class="verbatim"> $ perl -Sd foo.pl
-</pre>
-<hr>
-<a name="perldebug-BUGS"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldebug-SEE-ALSO" accesskey="p" rel="prev">perldebug SEE
ALSO</a>, Up: <a href="#perldebug" accesskey="u" rel="up">perldebug</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="BUGS-1"></a>
-<h3 class="section">15.7 BUGS</h3>
-
-<p>You cannot get stack frame information or in any fashion debug functions
-that were not compiled by Perl, such as those from C or C++ extensions.
-</p>
-<p>If you alter your @_ arguments in a subroutine (such as with
<code>shift</code>
-or <code>pop</code>), the stack backtrace will not show the original values.
-</p>
-<p>The debugger does not currently work in conjunction with the
<strong>-W</strong>
-command-line switch, because it itself is not free of warnings.
-</p>
-<p>If you’re in a slow syscall (like <code>wait</code>ing,
<code>accept</code>ing, or <code>read</code>ing
-from your keyboard or a socket) and haven’t set up your own
<code>$SIG{INT}</code>
-handler, then you won’t be able to CTRL-C your way back to the debugger,
-because the debugger’s own <code>$SIG{INT}</code> handler doesn’t
understand that
-it needs to raise an exception to longjmp(3) out of slow syscalls.
-</p>
-<hr>
-<a name="perldiag"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc" accesskey="n" rel="next">perldsc</a>, Previous: <a
href="#perldebug" accesskey="p" rel="prev">perldebug</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perldiag-1"></a>
-<h2 class="chapter">16 perldiag</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perldiag-NAME"
accesskey="1">perldiag NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldiag-DESCRIPTION"
accesskey="2">perldiag DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldiag-SEE-ALSO"
accesskey="3">perldiag SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldiag-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perldiag-DESCRIPTION" accesskey="n" rel="next">perldiag
DESCRIPTION</a>, Up: <a href="#perldiag" accesskey="u" rel="up">perldiag</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-15"></a>
-<h3 class="section">16.1 NAME</h3>
-
-<p>perldiag - various Perl diagnostics
-</p>
-<hr>
-<a name="perldiag-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perldiag-SEE-ALSO" accesskey="n" rel="next">perldiag SEE
ALSO</a>, Previous: <a href="#perldiag-NAME" accesskey="p" rel="prev">perldiag
NAME</a>, Up: <a href="#perldiag" accesskey="u" rel="up">perldiag</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-15"></a>
-<h3 class="section">16.2 DESCRIPTION</h3>
-
-<p>These messages are classified as follows (listed in increasing order of
-desperation):
-</p>
-<pre class="verbatim"> (W) A warning (optional).
- (D) A deprecation (enabled by default).
- (S) A severe warning (enabled by default).
- (F) A fatal error (trappable).
- (P) An internal error you should never see (trappable).
- (X) A very fatal error (nontrappable).
- (A) An alien error message (not generated by Perl).
-</pre>
-<p>The majority of messages from the first three classifications above
-(W, D & S) can be controlled using the <code>warnings</code> pragma.
-</p>
-<p>If a message can be controlled by the <code>warnings</code> pragma, its
warning
-category is included with the classification letter in the description
-below. E.g. <code>(W closed)</code> means a warning in the
<code>closed</code> category.
-</p>
-<p>Optional warnings are enabled by using the <code>warnings</code> pragma or
the <strong>-w</strong>
-and <strong>-W</strong> switches. Warnings may be captured by setting
<code>$SIG{__WARN__}</code>
-to a reference to a routine that will be called on each warning instead
-of printing it. See <a href="#perlvar-NAME">perlvar NAME</a>.
-</p>
-<p>Severe warnings are always enabled, unless they are explicitly disabled
-with the <code>warnings</code> pragma or the <strong>-X</strong> switch.
-</p>
-<p>Trappable errors may be trapped using the eval operator. See
-<a href="#perlfunc-eval">perlfunc eval</a>. In almost all cases, warnings may
be selectively
-disabled or promoted to fatal errors using the <code>warnings</code> pragma.
-See <a href="warnings.html#Top">(warnings)</a>.
-</p>
-<p>The messages are in alphabetical order, without regard to upper or
-lower-case. Some of these messages are generic. Spots that vary are
-denoted with a %s or other printf-style escape. These escapes are
-ignored by the alphabetical order, as are all characters other than
-letters. To look up your message, just ignore anything that is not a
-letter.
-</p>
-<dl compact="compact">
-<dt>accept() on closed socket %s</dt>
-<dd><a name="perldiag-accept_0028_0029-on-closed-socket-_0025s"></a>
-<p>(W closed) You tried to do an accept on a closed socket. Did you forget
-to check the return value of your socket() call? See
-‘perlfunc accept’.
-</p>
-</dd>
-<dt>Aliasing via reference is experimental</dt>
-<dd><a name="perldiag-Aliasing-via-reference-is-experimental"></a>
-<p>(S experimental::refaliasing) This warning is emitted if you use
-a reference constructor on the left-hand side of an assignment to
-alias one variable to another. Simply suppress the warning if you
-want to use the feature, but know that in doing so you are taking
-the risk of using an experimental feature which may change or be
-removed in a future Perl version:
-</p>
-<pre class="verbatim"> no warnings "experimental::refaliasing";
- use feature "refaliasing";
- \$x = \$y;
-</pre>
-</dd>
-<dt>Allocation too large: %x</dt>
-<dd><a name="perldiag-Allocation-too-large_003a-_0025x"></a>
-<p>(X) You can’t allocate more than 64K on an MS-DOS machine.
-</p>
-</dd>
-<dt>’%c’ allowed only after types %s in %s</dt>
-<dd><a
name="perldiag-_0027_0025c_0027-allowed-only-after-types-_0025s-in-_0025s"></a>
-<p>(F) The modifiers ’!’, ’<’ and
’>’ are allowed in pack() or unpack() only
-after certain types. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>Ambiguous call resolved as CORE::%s(), qualify as such or use &</dt>
-<dd><a
name="perldiag-Ambiguous-call-resolved-as-CORE_003a_003a_0025s_0028_0029_002c-qualify-as-such-or-use-_0026"></a>
-<p>(W ambiguous) A subroutine you have declared has the same name as a Perl
-keyword, and you have used the name without qualification for calling
-one or the other. Perl decided to call the builtin because the
-subroutine is not imported.
-</p>
-<p>To force interpretation as a subroutine call, either put an ampersand
-before the subroutine name, or qualify the name with its package.
-Alternatively, you can import the subroutine (or pretend that it’s
-imported with the <code>use subs</code> pragma).
-</p>
-<p>To silently interpret it as the Perl operator, use the <code>CORE::</code>
prefix
-on the operator (e.g. <code>CORE::log($x)</code>) or declare the subroutine
-to be an object method (see <a href="#perlsub-Subroutine-Attributes">perlsub
Subroutine Attributes</a> or
-<a href="attributes.html#Top">(attributes)</a>).
-</p>
-</dd>
-<dt>Ambiguous range in transliteration operator</dt>
-<dd><a name="perldiag-Ambiguous-range-in-transliteration-operator"></a>
-<p>(F) You wrote something like <code>tr/a-z-0//</code> which doesn’t
mean anything at
-all. To include a <code>-</code> character in a transliteration, put it either
-first or last. (In the past, <code>tr/a-z-0//</code> was synonymous with
-<code>tr/a-y//</code>, which was probably not what you would have expected.)
-</p>
-</dd>
-<dt>Ambiguous use of %s resolved as %s</dt>
-<dd><a name="perldiag-Ambiguous-use-of-_0025s-resolved-as-_0025s"></a>
-<p>(S ambiguous) You said something that may not be interpreted the way
-you thought. Normally it’s pretty easy to disambiguate it by supplying
-a missing quote, operator, parenthesis pair or declaration.
-</p>
-</dd>
-<dt>Ambiguous use of -%s resolved as -&%s()</dt>
-<dd><a
name="perldiag-Ambiguous-use-of-_002d_0025s-resolved-as-_002d_0026_0025s_0028_0029"></a>
-<p>(S ambiguous) You wrote something like <code>-foo</code>, which might be the
-string <code>"-foo"</code>, or a call to the function
<code>foo</code>, negated. If you meant
-the string, just write <code>"-foo"</code>. If you meant the
function call,
-write <code>-foo()</code>.
-</p>
-</dd>
-<dt>Ambiguous use of %c resolved as operator %c</dt>
-<dd><a name="perldiag-Ambiguous-use-of-_0025c-resolved-as-operator-_0025c"></a>
-<p>(S ambiguous) <code>%</code>, <code>&</code>, and <code>*</code> are
both infix operators (modulus,
-bitwise and, and multiplication) <em>and</em> initial special characters
-(denoting hashes, subroutines and typeglobs), and you said something
-like <code>*foo * foo</code> 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 <code>*foo * foo()</code>
if you
-really meant to multiply a glob by the result of calling a function.
-</p>
-</dd>
-<dt>Ambiguous use of %c{%s} resolved to %c%s</dt>
-<dd><a
name="perldiag-Ambiguous-use-of-_0025c_007b_0025s_007d-resolved-to-_0025c_0025s"></a>
-<p>(W ambiguous) You wrote something like <code>@{foo}</code>, which might be
-asking for the variable <code>@foo</code>, or it might be calling a function
-named foo, and dereferencing it as an array reference. If you wanted
-the variable, you can just write <code>@foo</code>. If you wanted to call the
-function, write <code>@{foo()}</code> ... or you could just not have a variable
-and a function with the same name, and save yourself a lot of trouble.
-</p>
-</dd>
-<dt>Ambiguous use of %c{%s[...]} resolved to %c%s[...]</dt>
-<dd><a
name="perldiag-Ambiguous-use-of-_0025c_007b_0025s_005b_002e_002e_002e_005d_007d-resolved-to-_0025c_0025s_005b_002e_002e_002e_005d"></a>
-</dd>
-<dt>Ambiguous use of %c{%s{...}} resolved to %c%s{...}</dt>
-<dd><a
name="perldiag-Ambiguous-use-of-_0025c_007b_0025s_007b_002e_002e_002e_007d_007d-resolved-to-_0025c_0025s_007b_002e_002e_002e_007d"></a>
-<p>(W ambiguous) You wrote something like <code>${foo[2]}</code> (where foo
represents
-the name of a Perl keyword), which might be looking for element number
-2 of the array named <code>@foo</code>, in which case please write
<code>$foo[2]</code>, 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 <code>${foo([2])}</code>.
-</p>
-<p>In regular expressions, the <code>${foo[2]}</code> syntax is sometimes
necessary
-to disambiguate between array subscripts and character classes.
-<code>/$length[2345]/</code>, for instance, will be interpreted as
<code>$length</code> followed
-by the character class <code>[2345]</code>. If an array subscript is what you
-want, you can avoid the warning by changing <code>/${length[2345]}/</code> to
the
-unsightly <code>/${\$length[2345]}/</code>, by renaming your array to something
-that does not coincide with a built-in keyword, or by simply turning
-off warnings with <code>no warnings 'ambiguous';</code>.
-</p>
-</dd>
-<dt>’|’ and ’<’ may not both be specified on
command line</dt>
-<dd><a
name="perldiag-_0027_007c_0027-and-_0027_003c_0027-may-not-both-be-specified-on-command-line"></a>
-<p>(F) An error peculiar to VMS. Perl does its own command line
-redirection, and found that STDIN was a pipe, and that you also tried to
-redirect STDIN using ’<’. Only one STDIN stream to a customer,
please.
-</p>
-</dd>
-<dt>’|’ and ’>’ may not both be specified on
command line</dt>
-<dd><a
name="perldiag-_0027_007c_0027-and-_0027_003e_0027-may-not-both-be-specified-on-command-line"></a>
-<p>(F) An error peculiar to VMS. Perl does its own command line
-redirection, and thinks you tried to redirect stdout both to a file and
-into a pipe to another command. You need to choose one or the other,
-though nothing’s stopping you from piping into a program or Perl script
-which ’splits’ output into two streams, such as
-</p>
-<pre class="verbatim"> open(OUT,">$ARGV[0]") or die
"Can't write to $ARGV[0]: $!";
- while (<STDIN>) {
- print;
- print OUT;
- }
- close OUT;
-</pre>
-</dd>
-<dt>Applying %s to %s will act on scalar(%s)</dt>
-<dd><a
name="perldiag-Applying-_0025s-to-_0025s-will-act-on-scalar_0028_0025s_0029"></a>
-<p>(W misc) The pattern match (<code>//</code>), substitution
(<code>s///</code>), and
-transliteration (<code>tr///</code>) operators work on scalar values. If you
apply
-one of them to an array or a hash, it will convert the array or hash to
-a scalar value (the length of an array, or the population info of a
-hash) and then work on that scalar value. This is probably not what
-you meant to do. See ‘perlfunc grep’ and ‘perlfunc
map’ for
-alternatives.
-</p>
-</dd>
-<dt>Arg too short for msgsnd</dt>
-<dd><a name="perldiag-Arg-too-short-for-msgsnd"></a>
-<p>(F) msgsnd() requires a string at least as long as sizeof(long).
-</p>
-</dd>
-<dt>Argument "%s" isn’t numeric%s</dt>
-<dd><a name="perldiag-Argument-_0022_0025s_0022-isn_0027t-numeric_0025s"></a>
-<p>(W numeric) The indicated string was fed as an argument to an operator
-that expected a numeric value instead. If you’re fortunate the message
-will identify which operator was so unfortunate.
-</p>
-<p>Note that for the <code>Inf</code> and <code>NaN</code> (infinity and
not-a-number) the
-definition of "numeric" is somewhat unusual: the strings themselves
-(like "Inf") are considered numeric, and anything following them is
-considered non-numeric.
-</p>
-</dd>
-<dt>Argument list not closed for PerlIO layer "%s"</dt>
-<dd><a
name="perldiag-Argument-list-not-closed-for-PerlIO-layer-_0022_0025s_0022"></a>
-<p>(W layer) When pushing a layer with arguments onto the Perl I/O
-system you forgot the ) that closes the argument list. (Layers
-take care of transforming data between external and internal
-representations.) Perl stopped parsing the layer list at this
-point and did not attempt to push this layer. If your program
-didn’t explicitly request the failing operation, it may be the
-result of the value of the environment variable PERLIO.
-</p>
-</dd>
-<dt>Argument "%s" treated as 0 in increment (++)</dt>
-<dd><a
name="perldiag-Argument-_0022_0025s_0022-treated-as-0-in-increment-_0028_002b_002b_0029"></a>
-<p>(W numeric) The indicated string was fed as an argument to the
<code>++</code>
-operator which expects either a number or a string matching
-<code>/^[a-zA-Z]*[0-9]*\z/</code>. See <a
href="#perlop-Auto_002dincrement-and-Auto_002ddecrement">perlop Auto-increment
and Auto-decrement</a> for details.
-</p>
-</dd>
-<dt>assertion botched: %s</dt>
-<dd><a name="perldiag-assertion-botched_003a-_0025s"></a>
-<p>(X) The malloc package that comes with Perl had an internal failure.
-</p>
-</dd>
-<dt>Assertion %s failed: file "%s", line %d</dt>
-<dd><a
name="perldiag-Assertion-_0025s-failed_003a-file-_0022_0025s_0022_002c-line-_0025d"></a>
-<p>(X) A general assertion failed. The file in question must be examined.
-</p>
-</dd>
-<dt>Assigned value is not a reference</dt>
-<dd><a name="perldiag-Assigned-value-is-not-a-reference"></a>
-<p>(F) You tried to assign something that was not a reference to an lvalue
-reference (e.g., <code>\$x = $y</code>). If you meant to make $x an alias to
$y, use
-<code>\$x = \$y</code>.
-</p>
-</dd>
-<dt>Assigned value is not %s reference</dt>
-<dd><a name="perldiag-Assigned-value-is-not-_0025s-reference"></a>
-<p>(F) You tried to assign a reference to a reference constructor, but the
-two references were not of the same type. You cannot alias a scalar to
-an array, or an array to a hash; the two types must match.
-</p>
-<pre class="verbatim"> \$x = address@hidden; # error
- address@hidden = \%y; # error
- $y = [];
- \$x = $y; # error; did you mean \$y?
-</pre>
-</dd>
-<dt>Assigning non-zero to $[ is no longer possible</dt>
-<dd><a
name="perldiag-Assigning-non_002dzero-to-_0024_005b-is-no-longer-possible"></a>
-<p>(F) When the "array_base" feature is disabled (e.g., under
<code>use v5.16;</code>)
-the special variable <code>$[</code>, which is deprecated, is now a fixed zero
value.
-</p>
-</dd>
-<dt>Assignment to both a list and a scalar</dt>
-<dd><a name="perldiag-Assignment-to-both-a-list-and-a-scalar"></a>
-<p>(F) If you assign to a conditional operator, the 2nd and 3rd arguments
-must either both be scalars or both be lists. Otherwise Perl won’t
-know which context to supply to the right side.
-</p>
-</dd>
-<dt><> at require-statement should be quotes</dt>
-<dd><a
name="perldiag-_003c_003e-at-require_002dstatement-should-be-quotes"></a>
-<p>(F) You wrote <code>require <file></code> when you should have written
-<code>require 'file'</code>.
-</p>
-</dd>
-<dt>Attempt to access disallowed key ’%s’ in a restricted hash</dt>
-<dd><a
name="perldiag-Attempt-to-access-disallowed-key-_0027_0025s_0027-in-a-restricted-hash"></a>
-<p>(F) The failing code has attempted to get or set a key which is not in
-the current set of allowed keys of a restricted hash.
-</p>
-</dd>
-<dt>Attempt to bless into a freed package</dt>
-<dd><a name="perldiag-Attempt-to-bless-into-a-freed-package"></a>
-<p>(F) You wrote <code>bless $foo</code> with one argument after somehow
causing
-the current package to be freed. Perl cannot figure out what to
-do, so it throws up in hands in despair.
-</p>
-</dd>
-<dt>Attempt to bless into a reference</dt>
-<dd><a name="perldiag-Attempt-to-bless-into-a-reference"></a>
-<p>(F) The CLASSNAME argument to the bless() operator is expected to be
-the name of the package to bless the resulting object into. You’ve
-supplied instead a reference to something: perhaps you wrote
-</p>
-<pre class="verbatim"> bless $self, $proto;
-</pre>
-<p>when you intended
-</p>
-<pre class="verbatim"> bless $self, ref($proto) || $proto;
-</pre>
-<p>If you actually want to bless into the stringified version
-of the reference supplied, you need to stringify it yourself, for
-example by:
-</p>
-<pre class="verbatim"> bless $self, "$proto";
-</pre>
-</dd>
-<dt>Attempt to clear deleted array</dt>
-<dd><a name="perldiag-Attempt-to-clear-deleted-array"></a>
-<p>(S debugging) An array was assigned to when it was being freed.
-Freed values are not supposed to be visible to Perl code. This
-can also happen if XS code calls <code>av_clear</code> from a custom magic
-callback on the array.
-</p>
-</dd>
-<dt>Attempt to delete disallowed key ’%s’ from a restricted
hash</dt>
-<dd><a
name="perldiag-Attempt-to-delete-disallowed-key-_0027_0025s_0027-from-a-restricted-hash"></a>
-<p>(F) The failing code attempted to delete from a restricted hash a key
-which is not in its key set.
-</p>
-</dd>
-<dt>Attempt to delete readonly key ’%s’ from a restricted hash</dt>
-<dd><a
name="perldiag-Attempt-to-delete-readonly-key-_0027_0025s_0027-from-a-restricted-hash"></a>
-<p>(F) The failing code attempted to delete a key whose value has been
-declared readonly from a restricted hash.
-</p>
-</dd>
-<dt>Attempt to free non-arena SV: 0x%x</dt>
-<dd><a name="perldiag-Attempt-to-free-non_002darena-SV_003a-0x_0025x"></a>
-<p>(S internal) All SV objects are supposed to be allocated from arenas
-that will be garbage collected on exit. An SV was discovered to be
-outside any of those arenas.
-</p>
-</dd>
-<dt>Attempt to free nonexistent shared string ’%s’%s</dt>
-<dd><a
name="perldiag-Attempt-to-free-nonexistent-shared-string-_0027_0025s_0027_0025s"></a>
-<p>(S internal) Perl maintains a reference-counted internal table of
-strings to optimize the storage and access of hash keys and other
-strings. This indicates someone tried to decrement the reference count
-of a string that can no longer be found in the table.
-</p>
-</dd>
-<dt>Attempt to free temp prematurely: SV 0x%x</dt>
-<dd><a name="perldiag-Attempt-to-free-temp-prematurely_003a-SV-0x_0025x"></a>
-<p>(S debugging) Mortalized values are supposed to be freed by the
-free_tmps() routine. This indicates that something else is freeing the
-SV before the free_tmps() routine gets a chance, which means that the
-free_tmps() routine will be freeing an unreferenced scalar when it does
-try to free it.
-</p>
-</dd>
-<dt>Attempt to free unreferenced glob pointers</dt>
-<dd><a name="perldiag-Attempt-to-free-unreferenced-glob-pointers"></a>
-<p>(S internal) The reference counts got screwed up on symbol aliases.
-</p>
-</dd>
-<dt>Attempt to free unreferenced scalar: SV 0x%x</dt>
-<dd><a
name="perldiag-Attempt-to-free-unreferenced-scalar_003a-SV-0x_0025x"></a>
-<p>(S internal) Perl went to decrement the reference count of a scalar to
-see if it would go to 0, and discovered that it had already gone to 0
-earlier, and should have been freed, and in fact, probably was freed.
-This could indicate that SvREFCNT_dec() was called too many times, or
-that SvREFCNT_inc() was called too few times, or that the SV was
-mortalized when it shouldn’t have been, or that memory has been
-corrupted.
-</p>
-</dd>
-<dt>Attempt to pack pointer to temporary value</dt>
-<dd><a name="perldiag-Attempt-to-pack-pointer-to-temporary-value"></a>
-<p>(W pack) You tried to pass a temporary value (like the result of a
-function, or a computed expression) to the "p" pack() template. This
-means the result contains a pointer to a location that could become
-invalid anytime, even before the end of the current statement. Use
-literals or global values as arguments to the "p" pack() template to
-avoid this warning.
-</p>
-</dd>
-<dt>Attempt to reload %s aborted.</dt>
-<dd><a name="perldiag-Attempt-to-reload-_0025s-aborted_002e"></a>
-<p>(F) You tried to load a file with <code>use</code> or <code>require</code>
that failed to
-compile once already. Perl will not try to compile this file again
-unless you delete its entry from %INC. See <a
href="#perlfunc-require">perlfunc require</a> and
-<a href="#perlvar-_0025INC">perlvar %INC</a>.
-</p>
-</dd>
-<dt>Attempt to set length of freed array</dt>
-<dd><a name="perldiag-Attempt-to-set-length-of-freed-array"></a>
-<p>(W misc) You tried to set the length of an array which has
-been freed. You can do this by storing a reference to the
-scalar representing the last index of an array and later
-assigning through that reference. For example
-</p>
-<pre class="verbatim"> $r = do {my @a; \$#a};
- $$r = 503
-</pre>
-</dd>
-<dt>Attempt to use reference as lvalue in substr</dt>
-<dd><a name="perldiag-Attempt-to-use-reference-as-lvalue-in-substr"></a>
-<p>(W substr) You supplied a reference as the first argument to substr()
-used as an lvalue, which is pretty strange. Perhaps you forgot to
-dereference it first. See ‘perlfunc substr’.
-</p>
-</dd>
-<dt>Attribute "locked" is deprecated</dt>
-<dd><a name="perldiag-Attribute-_0022locked_0022-is-deprecated"></a>
-<p>(D deprecated) You have used the attributes pragma to modify the
-"locked" attribute on a code reference. The :locked attribute is
-obsolete, has had no effect since 5005 threads were removed, and
-will be removed in a future release of Perl 5.
-</p>
-</dd>
-<dt>Attribute prototype(%s) discards earlier prototype attribute in same
sub</dt>
-<dd><a
name="perldiag-Attribute-prototype_0028_0025s_0029-discards-earlier-prototype-attribute-in-same-sub"></a>
-<p>(W misc) A sub was declared as sub foo : prototype(A) : prototype(B) {}, for
-example. Since each sub can only have one prototype, the earlier
-declaration(s) are discarded while the last one is applied.
-</p>
-</dd>
-<dt>Attribute "unique" is deprecated</dt>
-<dd><a name="perldiag-Attribute-_0022unique_0022-is-deprecated"></a>
-<p>(D deprecated) You have used the attributes pragma to modify
-the "unique" attribute on an array, hash or scalar reference.
-The :unique attribute has had no effect since Perl 5.8.8, and
-will be removed in a future release of Perl 5.
-</p>
-</dd>
-<dt>av_reify called on tied array</dt>
-<dd><a name="perldiag-av_005freify-called-on-tied-array"></a>
-<p>(S debugging) This indicates that something went wrong and Perl got
<em>very</em>
-confused about <code>@_</code> or <code>@DB::args</code> being tied.
-</p>
-</dd>
-<dt>Bad arg length for %s, is %u, should be %d</dt>
-<dd><a
name="perldiag-Bad-arg-length-for-_0025s_002c-is-_0025u_002c-should-be-_0025d"></a>
-<p>(F) You passed a buffer of the wrong size to one of msgctl(), semctl()
-or shmctl(). In C parlance, the correct sizes are, respectively,
-sizeof(struct <span class="nolinebreak">msqid_ds</span> *)<!-- /@w
-->, sizeof(struct <span class="nolinebreak">semid_ds</span> *)<!--
/@w -->, and
-sizeof(struct <span class="nolinebreak">shmid_ds</span> *)<!-- /@w
-->.
-</p>
-</dd>
-<dt>Bad evalled substitution pattern</dt>
-<dd><a name="perldiag-Bad-evalled-substitution-pattern"></a>
-<p>(F) You’ve used the <code>/e</code> switch to evaluate the
replacement for a
-substitution, but perl found a syntax error in the code to evaluate,
-most likely an unexpected right brace ’}’.
-</p>
-</dd>
-<dt>Bad filehandle: %s</dt>
-<dd><a name="perldiag-Bad-filehandle_003a-_0025s"></a>
-<p>(F) A symbol was passed to something wanting a filehandle, but the
-symbol has no filehandle associated with it. Perhaps you didn’t do an
-open(), or did it in another package.
-</p>
-</dd>
-<dt>Bad free() ignored</dt>
-<dd><a name="perldiag-Bad-free_0028_0029-ignored"></a>
-<p>(S malloc) An internal routine called free() on something that had never
-been malloc()ed in the first place. Mandatory, but can be disabled by
-setting environment variable <code>PERL_BADFREE</code> to 0.
-</p>
-<p>This message can be seen quite often with DB_File on systems with
"hard"
-dynamic linking, like <code>AIX</code> and <code>OS/2</code>. It is a bug of
<code>Berkeley DB</code>
-which is left unnoticed if <code>DB</code> uses <em>forgiving</em> system
malloc().
-</p>
-</dd>
-<dt>Bad hash</dt>
-<dd><a name="perldiag-Bad-hash"></a>
-<p>(P) One of the internal hash routines was passed a null HV pointer.
-</p>
-</dd>
-<dt>Badly placed ()’s</dt>
-<dd><a name="perldiag-Badly-placed-_0028_0029_0027s"></a>
-<p>(A) You’ve accidentally run your script through <strong>csh</strong>
instead
-of Perl. Check the #! line, or manually feed your script into
-Perl yourself.
-</p>
-</dd>
-<dt>Bad name after %s</dt>
-<dd><a name="perldiag-Bad-name-after-_0025s"></a>
-<p>(F) You started to name a symbol by using a package prefix, and then
-didn’t finish the symbol. In particular, you can’t interpolate
outside
-of quotes, so
-</p>
-<pre class="verbatim"> $var = 'myvar';
- $sym = mypack::$var;
-</pre>
-<p>is not the same as
-</p>
-<pre class="verbatim"> $var = 'myvar';
- $sym = "mypack::$var";
-</pre>
-</dd>
-<dt>Bad plugin affecting keyword ’%s’</dt>
-<dd><a name="perldiag-Bad-plugin-affecting-keyword-_0027_0025s_0027"></a>
-<p>(F) An extension using the keyword plugin mechanism violated the
-plugin API.
-</p>
-</dd>
-<dt>Bad realloc() ignored</dt>
-<dd><a name="perldiag-Bad-realloc_0028_0029-ignored"></a>
-<p>(S malloc) An internal routine called realloc() on something that
-had never been malloc()ed in the first place. Mandatory, but can
-be disabled by setting the environment variable <code>PERL_BADFREE</code> to 1.
-</p>
-</dd>
-<dt>Bad symbol for array</dt>
-<dd><a name="perldiag-Bad-symbol-for-array"></a>
-<p>(P) An internal request asked to add an array entry to something that
-wasn’t a symbol table entry.
-</p>
-</dd>
-<dt>Bad symbol for dirhandle</dt>
-<dd><a name="perldiag-Bad-symbol-for-dirhandle"></a>
-<p>(P) An internal request asked to add a dirhandle entry to something
-that wasn’t a symbol table entry.
-</p>
-</dd>
-<dt>Bad symbol for filehandle</dt>
-<dd><a name="perldiag-Bad-symbol-for-filehandle"></a>
-<p>(P) An internal request asked to add a filehandle entry to something
-that wasn’t a symbol table entry.
-</p>
-</dd>
-<dt>Bad symbol for hash</dt>
-<dd><a name="perldiag-Bad-symbol-for-hash"></a>
-<p>(P) An internal request asked to add a hash entry to something that
-wasn’t a symbol table entry.
-</p>
-</dd>
-<dt>Bad symbol for scalar</dt>
-<dd><a name="perldiag-Bad-symbol-for-scalar"></a>
-<p>(P) An internal request asked to add a scalar entry to something that
-wasn’t a symbol table entry.
-</p>
-</dd>
-<dt>Bareword found in conditional</dt>
-<dd><a name="perldiag-Bareword-found-in-conditional"></a>
-<p>(W bareword) The compiler found a bareword where it expected a
-conditional, which often indicates that an || or && was parsed as part
-of the last argument of the previous construct, for example:
-</p>
-<pre class="verbatim"> open FOO || die;
-</pre>
-<p>It may also indicate a misspelled constant that has been interpreted as
-a bareword:
-</p>
-<pre class="verbatim"> use constant TYPO => 1;
- if (TYOP) { print "foo" }
-</pre>
-<p>The <code>strict</code> pragma is useful in avoiding such errors.
-</p>
-</dd>
-<dt>Bareword "%s" not allowed while "strict subs" in
use</dt>
-<dd><a
name="perldiag-Bareword-_0022_0025s_0022-not-allowed-while-_0022strict-subs_0022-in-use"></a>
-<p>(F) With "strict subs" in use, a bareword is only allowed as a
-subroutine identifier, in curly brackets or to the left of the
"=>"
-symbol. Perhaps you need to predeclare a subroutine?
-</p>
-</dd>
-<dt>Bareword "%s" refers to nonexistent package</dt>
-<dd><a
name="perldiag-Bareword-_0022_0025s_0022-refers-to-nonexistent-package"></a>
-<p>(W bareword) You used a qualified bareword of the form <code>Foo::</code>,
but the
-compiler saw no other uses of that namespace before that point. Perhaps
-you need to predeclare a package?
-</p>
-</dd>
-<dt>BEGIN failed–compilation aborted</dt>
-<dd><a name="perldiag-BEGIN-failed_002d_002dcompilation-aborted"></a>
-<p>(F) An untrapped exception was raised while executing a BEGIN
-subroutine. Compilation stops immediately and the interpreter is
-exited.
-</p>
-</dd>
-<dt>BEGIN not safe after errors–compilation aborted</dt>
-<dd><a
name="perldiag-BEGIN-not-safe-after-errors_002d_002dcompilation-aborted"></a>
-<p>(F) Perl found a <code>BEGIN {}</code> subroutine (or a <code>use</code>
directive, which
-implies a <code>BEGIN {}</code>) after one or more compilation errors had
already
-occurred. Since the intended environment for the <code>BEGIN {}</code> could
not
-be guaranteed (due to the errors), and since subsequent code likely
-depends on its correct operation, Perl just gave up.
-</p>
-</dd>
-<dt>\%d better written as $%d</dt>
-<dd><a name="perldiag-_005c_0025d-better-written-as-_0024_0025d"></a>
-<p>(W syntax) Outside of patterns, backreferences live on as variables.
-The use of backslashes is grandfathered on the right-hand side of a
-substitution, but stylistically it’s better to use the variable form
-because other Perl programmers will expect it, and it works better if
-there are more than 9 backreferences.
-</p>
-</dd>
-<dt>Binary number > 0b11111111111111111111111111111111 non-portable</dt>
-<dd><a
name="perldiag-Binary-number-_003e-0b11111111111111111111111111111111-non_002dportable"></a>
-<p>(W portable) The binary number you specified is larger than 2**32-1
-(4294967295) and therefore non-portable between systems. See
-<a href="#perlport-NAME">perlport NAME</a> for more on portability concerns.
-</p>
-</dd>
-<dt>bind() on closed socket %s</dt>
-<dd><a name="perldiag-bind_0028_0029-on-closed-socket-_0025s"></a>
-<p>(W closed) You tried to do a bind on a closed socket. Did you forget to
-check the return value of your socket() call? See ‘perlfunc bind’.
-</p>
-</dd>
-<dt>binmode() on closed filehandle %s</dt>
-<dd><a name="perldiag-binmode_0028_0029-on-closed-filehandle-_0025s"></a>
-<p>(W unopened) You tried binmode() on a filehandle that was never opened.
-Check your control flow and number of arguments.
-</p>
-</dd>
-<dt>Bit vector size > 32 non-portable</dt>
-<dd><a name="perldiag-Bit-vector-size-_003e-32-non_002dportable"></a>
-<p>(W portable) Using bit vector sizes larger than 32 is non-portable.
-</p>
-</dd>
-<dt>Bizarre copy of %s</dt>
-<dd><a name="perldiag-Bizarre-copy-of-_0025s"></a>
-<p>(P) Perl detected an attempt to copy an internal value that is not
-copiable.
-</p>
-</dd>
-<dt>Bizarre SvTYPE [%d]</dt>
-<dd><a name="perldiag-Bizarre-SvTYPE-_005b_0025d_005d"></a>
-<p>(P) When starting a new thread or returning values from a thread, Perl
-encountered an invalid data type.
-</p>
-</dd>
-<dt>Both or neither range ends should be Unicode in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Both-or-neither-range-ends-should-be-Unicode-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) (only under <code>use re 'strict'<!-- /@w --></code>
or within <code>(?[...])</code>)
-</p>
-<p>In a bracketed character class in a regular expression pattern, you
-had a range which has exactly one end of it specified using <code>\N{}</code>,
and
-the other end is specified using a non-portable mechanism. Perl treats
-the range as a Unicode range, that is, all the characters in it are
-considered to be the Unicode characters, and which may be different code
-points on some platforms Perl runs on. For example,
<code>[\N{U+06}-\x08]</code>
-is treated as if you had instead said <code>[\N{U+06}-\N{U+08}]</code>, that
is it
-matches the characters whose code points in Unicode are 6, 7, and 8.
-But that <code>\x08</code> might indicate that you meant something different,
so
-the warning gets raised.
-</p>
-</dd>
-<dt>Buffer overflow in prime_env_iter: %s</dt>
-<dd><a
name="perldiag-Buffer-overflow-in-prime_005fenv_005fiter_003a-_0025s"></a>
-<p>(W internal) A warning peculiar to VMS. While Perl was preparing to
-iterate over %ENV, it encountered a logical name or symbol definition
-which was too long, so it was truncated to the string shown.
-</p>
-</dd>
-<dt>Callback called exit</dt>
-<dd><a name="perldiag-Callback-called-exit"></a>
-<p>(F) A subroutine invoked from an external package via call_sv()
-exited by calling exit.
-</p>
-</dd>
-<dt>%s() called too early to check prototype</dt>
-<dd><a
name="perldiag-_0025s_0028_0029-called-too-early-to-check-prototype"></a>
-<p>(W prototype) You’ve called a function that has a prototype before the
-parser saw a definition or declaration for it, and Perl could not check
-that the call conforms to the prototype. You need to either add an
-early prototype declaration for the subroutine in question, or move the
-subroutine definition ahead of the call to get proper prototype
-checking. Alternatively, if you are certain that you’re calling the
-function correctly, you may put an ampersand before the name to avoid
-the warning. See <a href="#perlsub-NAME">perlsub NAME</a>.
-</p>
-</dd>
-<dt>Calling POSIX::%s() is deprecated</dt>
-<dd><a
name="perldiag-Calling-POSIX_003a_003a_0025s_0028_0029-is-deprecated"></a>
-<p>(D deprecated) You called a function whose use is deprecated. See
-the function’s name in <a href="POSIX.html#Top">(POSIX)</a> for details.
-</p>
-</dd>
-<dt>Cannot chr %f</dt>
-<dd><a name="perldiag-Cannot-chr-_0025f"></a>
-<p>(F) You passed an invalid number (like an infinity or not-a-number) to
<code>chr</code>.
-</p>
-</dd>
-<dt>Cannot compress %f in pack</dt>
-<dd><a name="perldiag-Cannot-compress-_0025f-in-pack"></a>
-<p>(F) You tried compressing an infinity or not-a-number as an unsigned
-integer with BER, which makes no sense.
-</p>
-</dd>
-<dt>Cannot compress integer in pack</dt>
-<dd><a name="perldiag-Cannot-compress-integer-in-pack"></a>
-<p>(F) An argument to pack("w",...) was too large to compress.
-The BER compressed integer format can only be used with positive
-integers, and you attempted to compress a very large number (> 1e308).
-See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>Cannot compress negative numbers in pack</dt>
-<dd><a name="perldiag-Cannot-compress-negative-numbers-in-pack"></a>
-<p>(F) An argument to pack("w",...) was negative. The BER
compressed integer
-format can only be used with positive integers. See ‘perlfunc
pack’.
-</p>
-</dd>
-<dt>Cannot convert a reference to %s to typeglob</dt>
-<dd><a name="perldiag-Cannot-convert-a-reference-to-_0025s-to-typeglob"></a>
-<p>(F) You manipulated Perl’s symbol table directly, stored a reference
-in it, then tried to access that symbol via conventional Perl syntax.
-The access triggers Perl to autovivify that typeglob, but it there is
-no legal conversion from that type of reference to a typeglob.
-</p>
-</dd>
-<dt>Cannot copy to %s</dt>
-<dd><a name="perldiag-Cannot-copy-to-_0025s"></a>
-<p>(P) Perl detected an attempt to copy a value to an internal type that cannot
-be directly assigned to.
-</p>
-</dd>
-<dt>Cannot find encoding "%s"</dt>
-<dd><a name="perldiag-Cannot-find-encoding-_0022_0025s_0022"></a>
-<p>(S io) You tried to apply an encoding that did not exist to a filehandle,
-either with open() or binmode().
-</p>
-</dd>
-<dt>Cannot pack %f with ’%c’</dt>
-<dd><a name="perldiag-Cannot-pack-_0025f-with-_0027_0025c_0027"></a>
-<p>(F) You tried converting an infinity or not-a-number to an integer,
-which makes no sense.
-</p>
-</dd>
-<dt>Cannot printf %f with ’%c’</dt>
-<dd><a name="perldiag-Cannot-printf-_0025f-with-_0027_0025c_0027"></a>
-<p>(F) You tried printing an infinity or not-a-number as a character (%c),
-which makes no sense. Maybe you meant ’%s’, or just stringifying
it?
-</p>
-</dd>
-<dt>Cannot set tied @DB::args</dt>
-<dd><a name="perldiag-Cannot-set-tied-_0040DB_003a_003aargs"></a>
-<p>(F) <code>caller</code> tried to set <code>@DB::args</code>, but found it
tied. Tying <code>@DB::args</code>
-is not supported. (Before this error was added, it used to crash.)
-</p>
-</dd>
-<dt>Cannot tie unreifiable array</dt>
-<dd><a name="perldiag-Cannot-tie-unreifiable-array"></a>
-<p>(P) You somehow managed to call <code>tie</code> on an array that does not
-keep a reference count on its arguments and cannot be made to
-do so. Such arrays are not even supposed to be accessible to
-Perl code, but are only used internally.
-</p>
-</dd>
-<dt>Can only compress unsigned integers in pack</dt>
-<dd><a name="perldiag-Can-only-compress-unsigned-integers-in-pack"></a>
-<p>(F) An argument to pack("w",...) was not an integer. The BER
compressed
-integer format can only be used with positive integers, and you attempted
-to compress something else. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>Can’t bless non-reference value</dt>
-<dd><a name="perldiag-Can_0027t-bless-non_002dreference-value"></a>
-<p>(F) Only hard references may be blessed. This is how Perl
"enforces"
-encapsulation of objects. See <a href="#perlobj-NAME">perlobj NAME</a>.
-</p>
-</dd>
-<dt>Can’t "break" in a loop topicalizer</dt>
-<dd><a name="perldiag-Can_0027t-_0022break_0022-in-a-loop-topicalizer"></a>
-<p>(F) You called <code>break</code>, but you’re in a
<code>foreach</code> block rather than
-a <code>given</code> block. You probably meant to use <code>next</code> or
<code>last</code>.
-</p>
-</dd>
-<dt>Can’t "break" outside a given block</dt>
-<dd><a name="perldiag-Can_0027t-_0022break_0022-outside-a-given-block"></a>
-<p>(F) You called <code>break</code>, but you’re not inside a
<code>given</code> block.
-</p>
-</dd>
-<dt>Can’t call method "%s" on an undefined value</dt>
-<dd><a
name="perldiag-Can_0027t-call-method-_0022_0025s_0022-on-an-undefined-value"></a>
-<p>(F) You used the syntax of a method call, but the slot filled by the
-object reference or package name contains an undefined value. Something
-like this will reproduce the error:
-</p>
-<pre class="verbatim"> $BADREF = undef;
- process $BADREF 1,2,3;
- $BADREF->process(1,2,3);
-</pre>
-</dd>
-<dt>Can’t call method "%s" on unblessed reference</dt>
-<dd><a
name="perldiag-Can_0027t-call-method-_0022_0025s_0022-on-unblessed-reference"></a>
-<p>(F) A method call must know in what package it’s supposed to run. It
-ordinarily finds this out from the object reference you supply, but you
-didn’t supply an object reference in this case. A reference isn’t
an
-object reference until it has been blessed. See <a
href="#perlobj-NAME">perlobj NAME</a>.
-</p>
-</dd>
-<dt>Can’t call method "%s" without a package or object
reference</dt>
-<dd><a
name="perldiag-Can_0027t-call-method-_0022_0025s_0022-without-a-package-or-object-reference"></a>
-<p>(F) You used the syntax of a method call, but the slot filled by the
-object reference or package name contains an expression that returns a
-defined value which is neither an object reference nor a package name.
-Something like this will reproduce the error:
-</p>
-<pre class="verbatim"> $BADREF = 42;
- process $BADREF 1,2,3;
- $BADREF->process(1,2,3);
-</pre>
-</dd>
-<dt>Can’t call mro_isa_changed_in() on anonymous symbol table</dt>
-<dd><a
name="perldiag-Can_0027t-call-mro_005fisa_005fchanged_005fin_0028_0029-on-anonymous-symbol-table"></a>
-<p>(P) Perl got confused as to whether a hash was a plain hash or a
-symbol table hash when trying to update @ISA caches.
-</p>
-</dd>
-<dt>Can’t call mro_method_changed_in() on anonymous symbol table</dt>
-<dd><a
name="perldiag-Can_0027t-call-mro_005fmethod_005fchanged_005fin_0028_0029-on-anonymous-symbol-table"></a>
-<p>(F) An XS module tried to call <code>mro_method_changed_in</code> on a hash
that was
-not attached to the symbol table.
-</p>
-</dd>
-<dt>Can’t chdir to %s</dt>
-<dd><a name="perldiag-Can_0027t-chdir-to-_0025s"></a>
-<p>(F) You called <code>perl -x/foo/bar</code>, but <samp>/foo/bar</samp> is
not a directory
-that you can chdir to, possibly because it doesn’t exist.
-</p>
-</dd>
-<dt>Can’t check filesystem of script "%s" for nosuid</dt>
-<dd><a
name="perldiag-Can_0027t-check-filesystem-of-script-_0022_0025s_0022-for-nosuid"></a>
-<p>(P) For some reason you can’t check the filesystem of the script for
-nosuid.
-</p>
-</dd>
-<dt>Can’t coerce %s to %s in %s</dt>
-<dd><a name="perldiag-Can_0027t-coerce-_0025s-to-_0025s-in-_0025s"></a>
-<p>(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
-say things like:
-</p>
-<pre class="verbatim"> *foo += 1;
-</pre>
-<p>You CAN say
-</p>
-<pre class="verbatim"> $foo = *foo;
- $foo += 1;
-</pre>
-<p>but then $foo no longer contains a glob.
-</p>
-</dd>
-<dt>Can’t "continue" outside a when block</dt>
-<dd><a name="perldiag-Can_0027t-_0022continue_0022-outside-a-when-block"></a>
-<p>(F) You called <code>continue</code>, but you’re not inside a
<code>when</code>
-or <code>default</code> block.
-</p>
-</dd>
-<dt>Can’t create pipe mailbox</dt>
-<dd><a name="perldiag-Can_0027t-create-pipe-mailbox"></a>
-<p>(P) An error peculiar to VMS. The process is suffering from exhausted
-quotas or other plumbing problems.
-</p>
-</dd>
-<dt>Can’t declare %s in "%s"</dt>
-<dd><a name="perldiag-Can_0027t-declare-_0025s-in-_0022_0025s_0022"></a>
-<p>(F) Only scalar, array, and hash variables may be declared as
"my", "our" or
-"state" variables. They must have ordinary identifiers as names.
-</p>
-</dd>
-<dt>Can’t "default" outside a topicalizer</dt>
-<dd><a name="perldiag-Can_0027t-_0022default_0022-outside-a-topicalizer"></a>
-<p>(F) You have used a <code>default</code> block that is neither inside a
-<code>foreach</code> loop nor a <code>given</code> block. (Note that this
error is
-issued on exit from the <code>default</code> block, so you won’t get the
-error if you use an explicit <code>continue</code>.)
-</p>
-</dd>
-<dt>Can’t do inplace edit: %s is not a regular file</dt>
-<dd><a
name="perldiag-Can_0027t-do-inplace-edit_003a-_0025s-is-not-a-regular-file"></a>
-<p>(S inplace) You tried to use the <strong>-i</strong> switch on a special
file, such as
-a file in /dev, a FIFO or an uneditable directory. The file was ignored.
-</p>
-</dd>
-<dt>Can’t do inplace edit on %s: %s</dt>
-<dd><a name="perldiag-Can_0027t-do-inplace-edit-on-_0025s_003a-_0025s"></a>
-<p>(S inplace) The creation of the new file failed for the indicated
-reason.
-</p>
-</dd>
-<dt>Can’t do inplace edit without backup</dt>
-<dd><a name="perldiag-Can_0027t-do-inplace-edit-without-backup"></a>
-<p>(F) You’re on a system such as MS-DOS that gets confused if you try
-reading from a deleted (but still opened) file. You have to say
-<code>-i.bak</code>, or some such.
-</p>
-</dd>
-<dt>Can’t do inplace edit: %s would not be unique</dt>
-<dd><a
name="perldiag-Can_0027t-do-inplace-edit_003a-_0025s-would-not-be-unique"></a>
-<p>(S inplace) Your filesystem does not support filenames longer than 14
-characters and Perl was unable to create a unique filename during
-inplace editing with the <strong>-i</strong> switch. The file was ignored.
-</p>
-</dd>
-<dt>Can’t do %s("%s") on non-UTF-8 locale; resolved to
"%s".</dt>
-<dd><a
name="perldiag-Can_0027t-do-_0025s_0028_0022_0025s_0022_0029-on-non_002dUTF_002d8-locale_003b-resolved-to-_0022_0025s_0022_002e"></a>
-<p>(W locale) You are 1) running under "<code>use locale</code>"; 2)
the current
-locale is not a UTF-8 one; 3) you tried to do the designated case-change
-operation on the specified Unicode character; and 4) the result of this
-operation would mix Unicode and locale rules, which likely conflict.
-Mixing of different rule types is forbidden, so the operation was not
-done; instead the result is the indicated value, which is the best
-available that uses entirely Unicode rules. That turns out to almost
-always be the original character, unchanged.
-</p>
-<p>It is generally a bad idea to mix non-UTF-8 locales and Unicode, and
-this issue is one of the reasons why. This warning is raised when
-Unicode rules would normally cause the result of this operation to
-contain a character that is in the range specified by the locale,
-0..255, and hence is subject to the locale’s rules, not Unicode’s.
-</p>
-<p>If you are using locale purely for its characteristics related to things
-like its numeric and time formatting (and not <code>LC_CTYPE</code>), consider
-using a restricted form of the locale pragma (see <a
href="#perllocale-The-_0022use-locale_0022-pragma">perllocale The
<code>"use locale"</code> pragma</a>) like
"<code>use locale <span
class="nolinebreak">':not_characters'</span></code><!-- /@w -->".
-</p>
-<p>Note that failed case-changing operations done as a result of
-case-insensitive <code>/i</code> regular expression matching will show up in
this
-warning as having the <code>fc</code> operation (as that is what the regular
-expression engine calls behind the scenes.)
-</p>
-</dd>
-<dt>Can’t do waitpid with flags</dt>
-<dd><a name="perldiag-Can_0027t-do-waitpid-with-flags"></a>
-<p>(F) This machine doesn’t have either waitpid() or wait4(), so only
-waitpid() without flags is emulated.
-</p>
-</dd>
-<dt>Can’t emulate -%s on #! line</dt>
-<dd><a name="perldiag-Can_0027t-emulate-_002d_0025s-on-_0023_0021-line"></a>
-<p>(F) The #! line specifies a switch that doesn’t make sense at this
-point. For example, it’d be kind of silly to put a <strong>-x</strong>
on the #!
-line.
-</p>
-</dd>
-<dt>Can’t %s %s-endian %ss on this platform</dt>
-<dd><a
name="perldiag-Can_0027t-_0025s-_0025s_002dendian-_0025ss-on-this-platform"></a>
-<p>(F) Your platform’s byte-order is neither big-endian nor
little-endian,
-or it has a very strange pointer size. Packing and unpacking big- or
-little-endian floating point values and pointers may not be possible.
-See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>Can’t exec "%s": %s</dt>
-<dd><a name="perldiag-Can_0027t-exec-_0022_0025s_0022_003a-_0025s"></a>
-<p>(W exec) A system(), exec(), or piped open call could not execute the
-named program for the indicated reason. Typical reasons include: the
-permissions were wrong on the file, the file wasn’t found in
-<code>$ENV{PATH}</code>, the executable in question was compiled for another
-architecture, or the #! line in a script points to an interpreter that
-can’t be run for similar reasons. (Or maybe your system doesn’t
support
-#! at all.)
-</p>
-</dd>
-<dt>Can’t exec %s</dt>
-<dd><a name="perldiag-Can_0027t-exec-_0025s"></a>
-<p>(F) Perl was trying to execute the indicated program for you because
-that’s what the #! line said. If that’s not what you wanted, you
may
-need to mention "perl" on the #! line somewhere.
-</p>
-</dd>
-<dt>Can’t execute %s</dt>
-<dd><a name="perldiag-Can_0027t-execute-_0025s"></a>
-<p>(F) You used the <strong>-S</strong> switch, but the copies of the script
to execute
-found in the PATH did not have correct permissions.
-</p>
-</dd>
-<dt>Can’t find an opnumber for "%s"</dt>
-<dd><a name="perldiag-Can_0027t-find-an-opnumber-for-_0022_0025s_0022"></a>
-<p>(F) A string of a form <code>CORE::word</code> was given to prototype(),
but there
-is no builtin with the name <code>word</code>.
-</p>
-</dd>
-<dt>Can’t find %s character property "%s"</dt>
-<dd><a
name="perldiag-Can_0027t-find-_0025s-character-property-_0022_0025s_0022"></a>
-<p>(F) You used <code>\p{}</code> or <code>\P{}</code> but the character
property by that name
-could not be found. Maybe you misspelled the name of the property?
-See <a
href="perluniprops.html#Properties-accessible-through-_005cp_007b_007d-and-_005cP_007b_007d">(perluniprops)Properties
accessible through \p{} and \P{}</a>
-for a complete list of available official properties.
-</p>
-</dd>
-<dt>Can’t find label %s</dt>
-<dd><a name="perldiag-Can_0027t-find-label-_0025s"></a>
-<p>(F) You said to goto a label that isn’t mentioned anywhere that
it’s
-possible for us to go to. See ‘perlfunc goto’.
-</p>
-</dd>
-<dt>Can’t find %s on PATH</dt>
-<dd><a name="perldiag-Can_0027t-find-_0025s-on-PATH"></a>
-<p>(F) You used the <strong>-S</strong> switch, but the script to execute
could not be
-found in the PATH.
-</p>
-</dd>
-<dt>Can’t find %s on PATH, ’.’ not in PATH</dt>
-<dd><a
name="perldiag-Can_0027t-find-_0025s-on-PATH_002c-_0027_002e_0027-not-in-PATH"></a>
-<p>(F) You used the <strong>-S</strong> switch, but the script to execute
could not be
-found in the PATH, or at least not with the correct permissions. The
-script exists in the current directory, but PATH prohibits running it.
-</p>
-</dd>
-<dt>Can’t find string terminator %s anywhere before EOF</dt>
-<dd><a
name="perldiag-Can_0027t-find-string-terminator-_0025s-anywhere-before-EOF"></a>
-<p>(F) Perl strings can stretch over multiple lines. This message means
-that the closing delimiter was omitted. Because bracketed quotes count
-nesting levels, the following is missing its final parenthesis:
-</p>
-<pre class="verbatim"> print q(The character '(' starts a side comment.);
-</pre>
-<p>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
-<a href="#perlop-NAME">perlop NAME</a> for the full details on here-documents.
-</p>
-</dd>
-<dt>Can’t find Unicode property definition "%s"</dt>
-<dd><a
name="perldiag-Can_0027t-find-Unicode-property-definition-_0022_0025s_0022"></a>
-<p>(F) You may have tried to use <code>\p</code> which means a Unicode
-property (for example <code>\p{Lu}</code> matches all uppercase
-letters). If you did mean to use a Unicode property, see
-<a
href="perluniprops.html#Properties-accessible-through-_005cp_007b_007d-and-_005cP_007b_007d">(perluniprops)Properties
accessible through \p{} and \P{}</a>
-for a complete list of available properties. If you didn’t
-mean to use a Unicode property, escape the <code>\p</code>, either by
-<code>\\p</code> (just the <code>\p</code>) or by <code>\Q\p</code> (the rest
of the string, or
-until <code>\E</code>).
-</p>
-</dd>
-<dt>Can’t fork: %s</dt>
-<dd><a name="perldiag-Can_0027t-fork_003a-_0025s"></a>
-<p>(F) A fatal error occurred while trying to fork while opening a
-pipeline.
-</p>
-</dd>
-<dt>Can’t fork, trying again in 5 seconds</dt>
-<dd><a name="perldiag-Can_0027t-fork_002c-trying-again-in-5-seconds"></a>
-<p>(W pipe) A fork in a piped open failed with EAGAIN and will be retried
-after five seconds.
-</p>
-</dd>
-<dt>Can’t get filespec - stale stat buffer?</dt>
-<dd><a name="perldiag-Can_0027t-get-filespec-_002d-stale-stat-buffer_003f"></a>
-<p>(S) A warning peculiar to VMS. This arises because of the difference
-between access checks under VMS and under the Unix model Perl assumes.
-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 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
-routine knows about the Perl <code>stat</code> 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.)
-</p>
-</dd>
-<dt>Can’t get pipe mailbox device name</dt>
-<dd><a name="perldiag-Can_0027t-get-pipe-mailbox-device-name"></a>
-<p>(P) An error peculiar to VMS. After creating a mailbox to act as a
-pipe, Perl can’t retrieve its name for later use.
-</p>
-</dd>
-<dt>Can’t get SYSGEN parameter value for MAXBUF</dt>
-<dd><a name="perldiag-Can_0027t-get-SYSGEN-parameter-value-for-MAXBUF"></a>
-<p>(P) An error peculiar to VMS. Perl asked $GETSYI how big you want your
-mailbox buffers to be, and didn’t get an answer.
-</p>
-</dd>
-<dt>Can’t "goto" into the middle of a foreach loop</dt>
-<dd><a
name="perldiag-Can_0027t-_0022goto_0022-into-the-middle-of-a-foreach-loop"></a>
-<p>(F) A "goto" statement was executed to jump into the middle of a
foreach
-loop. You can’t get there from here. See ‘perlfunc goto’.
-</p>
-</dd>
-<dt>Can’t "goto" out of a pseudo block</dt>
-<dd><a name="perldiag-Can_0027t-_0022goto_0022-out-of-a-pseudo-block"></a>
-<p>(F) A "goto" statement was executed to jump out of what might
look like
-a block, except that it isn’t a proper block. This usually occurs if
-you tried to jump out of a sort() block or subroutine, which is a no-no.
-See ‘perlfunc goto’.
-</p>
-</dd>
-<dt>Can’t goto subroutine from an eval-%s</dt>
-<dd><a name="perldiag-Can_0027t-goto-subroutine-from-an-eval_002d_0025s"></a>
-<p>(F) The "goto subroutine" call can’t be used to jump out of
an eval
-"string" or block.
-</p>
-</dd>
-<dt>Can’t goto subroutine from a sort sub (or similar callback)</dt>
-<dd><a
name="perldiag-Can_0027t-goto-subroutine-from-a-sort-sub-_0028or-similar-callback_0029"></a>
-<p>(F) The "goto subroutine" call can’t be used to jump out of
the
-comparison sub for a sort(), or from a similar callback (such
-as the reduce() function in List::Util).
-</p>
-</dd>
-<dt>Can’t goto subroutine outside a subroutine</dt>
-<dd><a name="perldiag-Can_0027t-goto-subroutine-outside-a-subroutine"></a>
-<p>(F) The deeply magical "goto subroutine" call can only replace one
-subroutine call for another. It can’t manufacture one out of whole
-cloth. In general you should be calling it out of only an AUTOLOAD
-routine anyway. See ‘perlfunc goto’.
-</p>
-</dd>
-<dt>Can’t ignore signal CHLD, forcing to default</dt>
-<dd><a
name="perldiag-Can_0027t-ignore-signal-CHLD_002c-forcing-to-default"></a>
-<p>(W signal) Perl has detected that it is being run with the SIGCHLD
-signal (sometimes known as SIGCLD) disabled. Since disabling this
-signal will interfere with proper determination of exit status of child
-processes, Perl has reset the signal to its default value. This
-situation typically indicates that the parent program under which Perl
-may be running (e.g. cron) is being very careless.
-</p>
-</dd>
-<dt>Can’t kill a non-numeric process ID</dt>
-<dd><a name="perldiag-Can_0027t-kill-a-non_002dnumeric-process-ID"></a>
-<p>(F) Process identifiers must be (signed) integers. It is a fatal error to
-attempt to kill() an undefined, empty-string or otherwise non-numeric
-process identifier.
-</p>
-</dd>
-<dt>Can’t "last" outside a loop block</dt>
-<dd><a name="perldiag-Can_0027t-_0022last_0022-outside-a-loop-block"></a>
-<p>(F) A "last" statement was executed to break out of the current
block,
-except that there’s this itty bitty problem called there isn’t a
current
-block. Note that an "if" or "else" block doesn’t
count as a "loopish"
-block, as doesn’t a block given to sort(), map() or grep(). You can
-usually double the curlies to get the same effect though, because the
-inner curlies will be considered a block that loops once. See
-<a href="#perlfunc-last">perlfunc last</a>.
-</p>
-</dd>
-<dt>Can’t linearize anonymous symbol table</dt>
-<dd><a name="perldiag-Can_0027t-linearize-anonymous-symbol-table"></a>
-<p>(F) Perl tried to calculate the method resolution order (MRO) of a
-package, but failed because the package stash has no name.
-</p>
-</dd>
-<dt>Can’t load ’%s’ for module %s</dt>
-<dd><a name="perldiag-Can_0027t-load-_0027_0025s_0027-for-module-_0025s"></a>
-<p>(F) The module you tried to load failed to load a dynamic extension.
-This may either mean that you upgraded your version of perl to one
-that is incompatible with your old dynamic extensions (which is known
-to happen between major versions of perl), or (more likely) that your
-dynamic extension was built against an older version of the library
-that is installed on your system. You may need to rebuild your old
-dynamic extensions.
-</p>
-</dd>
-<dt>Can’t localize lexical variable %s</dt>
-<dd><a name="perldiag-Can_0027t-localize-lexical-variable-_0025s"></a>
-<p>(F) You used local on a variable name that was previously declared as a
-lexical variable using "my" or "state". This is not
allowed. If you
-want to localize a package variable of the same name, qualify it with
-the package name.
-</p>
-</dd>
-<dt>Can’t localize through a reference</dt>
-<dd><a name="perldiag-Can_0027t-localize-through-a-reference"></a>
-<p>(F) You said something like <code>local $$ref</code>, which Perl
can’t currently
-handle, because when it goes to restore the old value of whatever $ref
-pointed to after the scope of the local() is finished, it can’t be sure
-that $ref will still be a reference.
-</p>
-</dd>
-<dt>Can’t locate %s</dt>
-<dd><a name="perldiag-Can_0027t-locate-_0025s"></a>
-<p>(F) You said to <code>do</code> (or <code>require</code>, or
<code>use</code>) a file that couldn’t be found.
-Perl looks for the file in all the locations mentioned in @INC, unless
-the file name included the full path to the file. Perhaps you need
-to set the PERL5LIB or PERL5OPT environment variable to say where the
-extra library is, or maybe the script needs to add the library name
-to @INC. Or maybe you just misspelled the name of the file. See
-<a href="#perlfunc-require">perlfunc require</a> and <a
href="lib.html#Top">(lib)</a>.
-</p>
-</dd>
-<dt>Can’t locate auto/%s.al in @INC</dt>
-<dd><a name="perldiag-Can_0027t-locate-auto_002f_0025s_002eal-in-_0040INC"></a>
-<p>(F) A function (or method) was called in a package which allows
-autoload, but there is no function to autoload. Most probable causes
-are a misprint in a function/method name or a failure to <code>AutoSplit</code>
-the file, say, by doing <code>make install</code>.
-</p>
-</dd>
-<dt>Can’t locate loadable object for module %s in @INC</dt>
-<dd><a
name="perldiag-Can_0027t-locate-loadable-object-for-module-_0025s-in-_0040INC"></a>
-<p>(F) The module you loaded is trying to load an external library, like
-for example, <samp>foo.so</samp> or <samp>bar.dll</samp>, but the <a
href="DynaLoader.html#Top">(DynaLoader)</a> module was
-unable to locate this library. See <a
href="DynaLoader.html#Top">(DynaLoader)</a>.
-</p>
-</dd>
-<dt>Can’t locate object method "%s" via package
"%s"</dt>
-<dd><a
name="perldiag-Can_0027t-locate-object-method-_0022_0025s_0022-via-package-_0022_0025s_0022"></a>
-<p>(F) You called a method correctly, and it correctly indicated a package
-functioning as a class, but that package doesn’t define that particular
-method, nor does any of its base classes. See <a href="#perlobj-NAME">perlobj
NAME</a>.
-</p>
-</dd>
-<dt>Can’t locate object method "%s" via package "%s"
(perhaps you forgot to load "%s"?)</dt>
-<dd><a
name="perldiag-Can_0027t-locate-object-method-_0022_0025s_0022-via-package-_0022_0025s_0022-_0028perhaps-you-forgot-to-load-_0022_0025s_0022_003f_0029"></a>
-<p>(F) You called a method on a class that did not exist, and the method
-could not be found in UNIVERSAL. This often means that a method
-requires a package that has not been loaded.
-</p>
-</dd>
-<dt>Can’t locate package %s for @%s::ISA</dt>
-<dd><a
name="perldiag-Can_0027t-locate-package-_0025s-for-_0040_0025s_003a_003aISA"></a>
-<p>(W syntax) The @ISA array contained the name of another package that
-doesn’t seem to exist.
-</p>
-</dd>
-<dt>Can’t locate PerlIO%s</dt>
-<dd><a name="perldiag-Can_0027t-locate-PerlIO_0025s"></a>
-<p>(F) You tried to use in open() a PerlIO layer that does not exist,
-e.g. open(FH, ">:nosuchlayer", "somefile").
-</p>
-</dd>
-<dt>Can’t make list assignment to %ENV on this system</dt>
-<dd><a
name="perldiag-Can_0027t-make-list-assignment-to-_0025ENV-on-this-system"></a>
-<p>(F) List assignment to %ENV is not supported on some systems, notably
-VMS.
-</p>
-</dd>
-<dt>Can’t make loaded symbols global on this platform while loading
%s</dt>
-<dd><a
name="perldiag-Can_0027t-make-loaded-symbols-global-on-this-platform-while-loading-_0025s"></a>
-<p>(S) A module passed the flag 0x01 to DynaLoader::dl_load_file() to request
-that symbols from the stated file are made available globally within the
-process, but that functionality is not available on this platform. Whilst
-the module likely will still work, this may prevent the perl interpreter
-from loading other XS-based extensions which need to link directly to
-functions defined in the C or XS code in the stated file.
-</p>
-</dd>
-<dt>Can’t modify %s in %s</dt>
-<dd><a name="perldiag-Can_0027t-modify-_0025s-in-_0025s"></a>
-<p>(F) You aren’t allowed to assign to the item indicated, or otherwise
try
-to change it, such as with an auto-increment.
-</p>
-</dd>
-<dt>Can’t modify nonexistent substring</dt>
-<dd><a name="perldiag-Can_0027t-modify-nonexistent-substring"></a>
-<p>(P) The internal routine that does assignment to a substr() was handed
-a NULL.
-</p>
-</dd>
-<dt>Can’t modify non-lvalue subroutine call</dt>
-<dd><a name="perldiag-Can_0027t-modify-non_002dlvalue-subroutine-call"></a>
-<p>(F) Subroutines meant to be used in lvalue context should be declared as
-such. See <a href="#perlsub-Lvalue-subroutines">perlsub Lvalue
subroutines</a>.
-</p>
-</dd>
-<dt>Can’t modify reference to %s in %s assignment</dt>
-<dd><a
name="perldiag-Can_0027t-modify-reference-to-_0025s-in-_0025s-assignment"></a>
-<p>(F) Only a limited number of constructs can be used as the argument to a
-reference constructor on the left-hand side of an assignment, and what
-you used was not one of them. See <a
href="#perlref-Assigning-to-References">perlref Assigning to References</a>.
-</p>
-</dd>
-<dt>Can’t modify reference to localized parenthesized array in list
assignment</dt>
-<dd><a
name="perldiag-Can_0027t-modify-reference-to-localized-parenthesized-array-in-list-assignment"></a>
-<p>(F) Assigning to <code>\local(@array)</code> or <code>\(local
@array)</code> is not supported, as
-it is not clear exactly what it should do. If you meant to make @array
-refer to some other array, use <code>address@hidden = address@hidden</code>.
If you want to
-make the elements of @array aliases of the scalars referenced on the
-right-hand side, use <code>\(@array) = @scalar_refs</code>.
-</p>
-</dd>
-<dt>Can’t modify reference to parenthesized hash in list assignment</dt>
-<dd><a
name="perldiag-Can_0027t-modify-reference-to-parenthesized-hash-in-list-assignment"></a>
-<p>(F) Assigning to <code>\(%hash)</code> is not supported. If you meant to
make %hash
-refer to some other hash, use <code>\%hash = \%other_hash</code>. If you want
to
-make the elements of %hash into aliases of the scalars referenced on the
-right-hand side, use a hash slice: <code>address@hidden@keys} =
@those_scalar_refs</code>.
-</p>
-</dd>
-<dt>Can’t msgrcv to read-only var</dt>
-<dd><a name="perldiag-Can_0027t-msgrcv-to-read_002donly-var"></a>
-<p>(F) The target of a msgrcv must be modifiable to be used as a receive
-buffer.
-</p>
-</dd>
-<dt>Can’t "next" outside a loop block</dt>
-<dd><a name="perldiag-Can_0027t-_0022next_0022-outside-a-loop-block"></a>
-<p>(F) A "next" statement was executed to reiterate the current
block, but
-there isn’t a current block. Note that an "if" or
"else" block doesn’t
-count as a "loopish" block, as doesn’t a block given to
sort(), map() or
-grep(). You can usually double the curlies to get the same effect
-though, because the inner curlies will be considered a block that loops
-once. See <a href="#perlfunc-next">perlfunc next</a>.
-</p>
-</dd>
-<dt>Can’t open %s: %s</dt>
-<dd><a name="perldiag-Can_0027t-open-_0025s_003a-_0025s"></a>
-<p>(S inplace) The implicit opening of a file through use of the
<code><></code>
-filehandle, either implicitly under the <code>-n</code> or <code>-p</code>
command-line
-switches, or explicitly, failed for the indicated reason. Usually
-this is because you don’t have read permission for a file which
-you named on the command line.
-</p>
-<p>(F) You tried to call perl with the <strong>-e</strong> switch, but
<samp>/dev/null</samp> (or
-your operating system’s equivalent) could not be opened.
-</p>
-</dd>
-<dt>Can’t open a reference</dt>
-<dd><a name="perldiag-Can_0027t-open-a-reference"></a>
-<p>(W io) You tried to open a scalar reference for reading or writing,
-using the 3-arg open() syntax:
-</p>
-<pre class="verbatim"> open FH, '>', $ref;
-</pre>
-<p>but your version of perl is compiled without perlio, and this form of
-open is not supported.
-</p>
-</dd>
-<dt>Can’t open bidirectional pipe</dt>
-<dd><a name="perldiag-Can_0027t-open-bidirectional-pipe"></a>
-<p>(W pipe) You tried to say <code>open(CMD, "|cmd|")</code>, which
is not supported.
-You can try any of several modules in the Perl library to do this, such
-as IPC::Open2. Alternately, direct the pipe’s output to a file using
-">", and then read it in under a different file handle.
-</p>
-</dd>
-<dt>Can’t open error file %s as stderr</dt>
-<dd><a name="perldiag-Can_0027t-open-error-file-_0025s-as-stderr"></a>
-<p>(F) An error peculiar to VMS. Perl does its own command line
-redirection, and couldn’t open the file specified after
’2>’ or ’2>>’ on
-the command line for writing.
-</p>
-</dd>
-<dt>Can’t open input file %s as stdin</dt>
-<dd><a name="perldiag-Can_0027t-open-input-file-_0025s-as-stdin"></a>
-<p>(F) An error peculiar to VMS. Perl does its own command line
-redirection, and couldn’t open the file specified after
’<’ on the
-command line for reading.
-</p>
-</dd>
-<dt>Can’t open output file %s as stdout</dt>
-<dd><a name="perldiag-Can_0027t-open-output-file-_0025s-as-stdout"></a>
-<p>(F) An error peculiar to VMS. Perl does its own command line
-redirection, and couldn’t open the file specified after
’>’ or ’>>’ on
-the command line for writing.
-</p>
-</dd>
-<dt>Can’t open output pipe (name: %s)</dt>
-<dd><a
name="perldiag-Can_0027t-open-output-pipe-_0028name_003a-_0025s_0029"></a>
-<p>(P) An error peculiar to VMS. Perl does its own command line
-redirection, and couldn’t open the pipe into which to send data destined
-for stdout.
-</p>
-</dd>
-<dt>Can’t open perl script "%s": %s</dt>
-<dd><a
name="perldiag-Can_0027t-open-perl-script-_0022_0025s_0022_003a-_0025s"></a>
-<p>(F) The script you specified can’t be opened for the indicated reason.
-</p>
-<p>If you’re debugging a script that uses #!, and normally relies on the
-shell’s $PATH search, the -S option causes perl to do that search, so
-you don’t have to type the path or <code>`which $scriptname`</code>.
-</p>
-</dd>
-<dt>Can’t read CRTL environ</dt>
-<dd><a name="perldiag-Can_0027t-read-CRTL-environ"></a>
-<p>(S) A warning peculiar to VMS. Perl tried to read an element of %ENV
-from the CRTL’s internal environment array and discovered the array was
-missing. You need to figure out where your CRTL misplaced its environ
-or define <samp>PERL_ENV_TABLES</samp> (see <a href="#perlvms-NAME">perlvms
NAME</a>) so that environ is not
-searched.
-</p>
-</dd>
-<dt>Can’t "redo" outside a loop block</dt>
-<dd><a name="perldiag-Can_0027t-_0022redo_0022-outside-a-loop-block"></a>
-<p>(F) A "redo" statement was executed to restart the current block,
but
-there isn’t a current block. Note that an "if" or
"else" block doesn’t
-count as a "loopish" block, as doesn’t a block given to
sort(), map()
-or grep(). You can usually double the curlies to get the same effect
-though, because the inner curlies will be considered a block that
-loops once. See <a href="#perlfunc-redo">perlfunc redo</a>.
-</p>
-</dd>
-<dt>Can’t remove %s: %s, skipping file</dt>
-<dd><a
name="perldiag-Can_0027t-remove-_0025s_003a-_0025s_002c-skipping-file"></a>
-<p>(S inplace) You requested an inplace edit without creating a backup
-file. Perl was unable to remove the original file to replace it with
-the modified file. The file was left unmodified.
-</p>
-</dd>
-<dt>Can’t rename %s to %s: %s, skipping file</dt>
-<dd><a
name="perldiag-Can_0027t-rename-_0025s-to-_0025s_003a-_0025s_002c-skipping-file"></a>
-<p>(S inplace) The rename done by the <strong>-i</strong> switch failed for
some reason,
-probably because you don’t have write permission to the directory.
-</p>
-</dd>
-<dt>Can’t reopen input pipe (name: %s) in binary mode</dt>
-<dd><a
name="perldiag-Can_0027t-reopen-input-pipe-_0028name_003a-_0025s_0029-in-binary-mode"></a>
-<p>(P) An error peculiar to VMS. Perl thought stdin was a pipe, and tried
-to reopen it to accept binary data. Alas, it failed.
-</p>
-</dd>
-<dt>Can’t represent character for Ox%X on this platform</dt>
-<dd><a
name="perldiag-Can_0027t-represent-character-for-Ox_0025X-on-this-platform"></a>
-<p>(F) There is a hard limit to how big a character code point can be due
-to the fundamental properties of UTF-8, especially on EBCDIC
-platforms. The given code point exceeds that. The only work-around is
-to not use such a large code point.
-</p>
-</dd>
-<dt>Can’t reset %ENV on this system</dt>
-<dd><a name="perldiag-Can_0027t-reset-_0025ENV-on-this-system"></a>
-<p>(F) You called <code>reset('E')</code> or similar, which tried to reset
-all variables in the current package beginning with "E". In
-the main package, that includes %ENV. Resetting %ENV is not
-supported on some systems, notably VMS.
-</p>
-</dd>
-<dt>Can’t resolve method "%s" overloading "%s" in
package "%s"</dt>
-<dd><a
name="perldiag-Can_0027t-resolve-method-_0022_0025s_0022-overloading-_0022_0025s_0022-in-package-_0022_0025s_0022"></a>
-<p>(F)(P) Error resolving overloading specified by a method name (as
-opposed to a subroutine reference): no such method callable via the
-package. If the method name is <code>???</code>, this is an internal error.
-</p>
-</dd>
-<dt>Can’t return %s from lvalue subroutine</dt>
-<dd><a name="perldiag-Can_0027t-return-_0025s-from-lvalue-subroutine"></a>
-<p>(F) Perl detected an attempt to return illegal lvalues (such as
-temporary or readonly values) from a subroutine used as an lvalue. This
-is not allowed.
-</p>
-</dd>
-<dt>Can’t return outside a subroutine</dt>
-<dd><a name="perldiag-Can_0027t-return-outside-a-subroutine"></a>
-<p>(F) The return statement was executed in mainline code, that is, where
-there was no subroutine call to return out of. See <a
href="#perlsub-NAME">perlsub NAME</a>.
-</p>
-</dd>
-<dt>Can’t return %s to lvalue scalar context</dt>
-<dd><a name="perldiag-Can_0027t-return-_0025s-to-lvalue-scalar-context"></a>
-<p>(F) You tried to return a complete array or hash from an lvalue
-subroutine, but you called the subroutine in a way that made Perl
-think you meant to return only one value. You probably meant to
-write parentheses around the call to the subroutine, which tell
-Perl that the call should be in list context.
-</p>
-</dd>
-<dt>Can’t stat script "%s"</dt>
-<dd><a name="perldiag-Can_0027t-stat-script-_0022_0025s_0022"></a>
-<p>(P) For some reason you can’t fstat() the script even though you have
it
-open already. Bizarre.
-</p>
-</dd>
-<dt>Can’t take log of %g</dt>
-<dd><a name="perldiag-Can_0027t-take-log-of-_0025g"></a>
-<p>(F) For ordinary real numbers, you can’t take the logarithm of a
-negative number or zero. There’s a Math::Complex package that comes
-standard with Perl, though, if you really want to do that for the
-negative numbers.
-</p>
-</dd>
-<dt>Can’t take sqrt of %g</dt>
-<dd><a name="perldiag-Can_0027t-take-sqrt-of-_0025g"></a>
-<p>(F) For ordinary real numbers, you can’t take the square root of a
-negative number. There’s a Math::Complex package that comes standard
-with Perl, though, if you really want to do that.
-</p>
-</dd>
-<dt>Can’t undef active subroutine</dt>
-<dd><a name="perldiag-Can_0027t-undef-active-subroutine"></a>
-<p>(F) You can’t undefine a routine that’s currently running. You
can,
-however, redefine it while it’s running, and you can even undef the
-redefined subroutine while the old routine is running. Go figure.
-</p>
-</dd>
-<dt>Can’t upgrade %s (%d) to %d</dt>
-<dd><a name="perldiag-Can_0027t-upgrade-_0025s-_0028_0025d_0029-to-_0025d"></a>
-<p>(P) The internal sv_upgrade routine adds "members" to an SV,
making it
-into a more specialized kind of SV. The top several SV types are so
-specialized, however, that they cannot be interconverted. This message
-indicates that such a conversion was attempted.
-</p>
-</dd>
-<dt>Can’t use ’%c’ after -mname</dt>
-<dd><a name="perldiag-Can_0027t-use-_0027_0025c_0027-after-_002dmname"></a>
-<p>(F) You tried to call perl with the <strong>-m</strong> switch, but you put
something
-other than "=" after the module name.
-</p>
-</dd>
-<dt>Can’t use a hash as a reference</dt>
-<dd><a name="perldiag-Can_0027t-use-a-hash-as-a-reference"></a>
-<p>(F) You tried to use a hash as a reference, as in
-<code>%foo->{"bar"}</code> or
<code>%$ref->{"hello"}</code>. Versions of perl
-<= 5.22.0 used to allow this syntax, but shouldn’t
-have. This was deprecated in perl 5.6.1.
-</p>
-</dd>
-<dt>Can’t use an array as a reference</dt>
-<dd><a name="perldiag-Can_0027t-use-an-array-as-a-reference"></a>
-<p>(F) You tried to use an array as a reference, as in
-<code>@foo->[23]</code> or <code>@$ref->[99]</code>. Versions of perl
<= 5.22.0
-used to allow this syntax, but shouldn’t have. This
-was deprecated in perl 5.6.1.
-</p>
-</dd>
-<dt>Can’t use anonymous symbol table for method lookup</dt>
-<dd><a
name="perldiag-Can_0027t-use-anonymous-symbol-table-for-method-lookup"></a>
-<p>(F) The internal routine that does method lookup was handed a symbol
-table that doesn’t have a name. Symbol tables can become anonymous
-for example by undefining stashes: <code>undef %Some::Package::</code>.
-</p>
-</dd>
-<dt>Can’t use an undefined value as %s reference</dt>
-<dd><a
name="perldiag-Can_0027t-use-an-undefined-value-as-_0025s-reference"></a>
-<p>(F) A value used as either a hard reference or a symbolic reference must
-be a defined value. This helps to delurk some insidious errors.
-</p>
-</dd>
-<dt>Can’t use bareword ("%s") as %s ref while "strict
refs" in use</dt>
-<dd><a
name="perldiag-Can_0027t-use-bareword-_0028_0022_0025s_0022_0029-as-_0025s-ref-while-_0022strict-refs_0022-in-use"></a>
-<p>(F) Only hard references are allowed by "strict refs". Symbolic
-references are disallowed. See <a href="#perlref-NAME">perlref NAME</a>.
-</p>
-</dd>
-<dt>Can’t use %! because Errno.pm is not available</dt>
-<dd><a
name="perldiag-Can_0027t-use-_0025_0021-because-Errno_002epm-is-not-available"></a>
-<p>(F) The first time the <code>%!</code> hash is used, perl automatically
loads the
-Errno.pm module. The Errno module is expected to tie the %! hash to
-provide symbolic names for <code>$!</code> errno values.
-</p>
-</dd>
-<dt>Can’t use both ’<’ and ’>’ after type
’%c’ in %s</dt>
-<dd><a
name="perldiag-Can_0027t-use-both-_0027_003c_0027-and-_0027_003e_0027-after-type-_0027_0025c_0027-in-_0025s"></a>
-<p>(F) A type cannot be forced to have both big-endian and little-endian
-byte-order at the same time, so this combination of modifiers is not
-allowed. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>Can’t use ’defined(@array)’ (Maybe you should just omit
the defined()?)</dt>
-<dd><a
name="perldiag-Can_0027t-use-_0027defined_0028_0040array_0029_0027-_0028Maybe-you-should-just-omit-the-defined_0028_0029_003f_0029"></a>
-<p>(F) defined() is not useful on arrays because it
-checks for an undefined <em>scalar</em> value. If you want to see if the
-array is empty, just use <code>if (@array) { # not empty }</code> for example.
-</p>
-</dd>
-<dt>Can’t use ’defined(%hash)’ (Maybe you should just omit
the defined()?)</dt>
-<dd><a
name="perldiag-Can_0027t-use-_0027defined_0028_0025hash_0029_0027-_0028Maybe-you-should-just-omit-the-defined_0028_0029_003f_0029"></a>
-<p>(F) <code>defined()</code> is not usually right on hashes.
-</p>
-<p>Although <code>defined %hash</code> is false on a plain not-yet-used hash,
it
-becomes true in several non-obvious circumstances, including iterators,
-weak references, stash names, even remaining true after <code>undef
%hash</code>.
-These things make <code>defined %hash</code> fairly useless in practice, so it
now
-generates a fatal error.
-</p>
-<p>If a check for non-empty is what you wanted then just put it in boolean
-context (see <a href="#perldata-Scalar-values">perldata Scalar values</a>):
-</p>
-<pre class="verbatim"> if (%hash) {
- # not empty
- }
-</pre>
-<p>If you had <code>defined %Foo::Bar::QUUX</code> to check whether such a
package
-variable exists then that’s never really been reliable, and isn’t
-a good way to enquire about the features of a package, or whether
-it’s loaded, etc.
-</p>
-</dd>
-<dt>Can’t use %s for loop variable</dt>
-<dd><a name="perldiag-Can_0027t-use-_0025s-for-loop-variable"></a>
-<p>(P) The parser got confused when trying to parse a <code>foreach</code>
loop.
-</p>
-</dd>
-<dt>Can’t use global %s in "%s"</dt>
-<dd><a name="perldiag-Can_0027t-use-global-_0025s-in-_0022_0025s_0022"></a>
-<p>(F) You tried to declare a magical variable as a lexical variable. This
-is not allowed, because the magic can be tied to only one location
-(namely the global variable) and it would be incredibly confusing to
-have variables in your program that looked like magical variables but
-weren’t.
-</p>
-</dd>
-<dt>Can’t use ’%c’ in a group with different byte-order in
%s</dt>
-<dd><a
name="perldiag-Can_0027t-use-_0027_0025c_0027-in-a-group-with-different-byte_002dorder-in-_0025s"></a>
-<p>(F) You attempted to force a different byte-order on a type
-that is already inside a group with a byte-order modifier.
-For example you cannot force little-endianness on a type that
-is inside a big-endian group.
-</p>
-</dd>
-<dt>Can’t use "my %s" in sort comparison</dt>
-<dd><a
name="perldiag-Can_0027t-use-_0022my-_0025s_0022-in-sort-comparison"></a>
-<p>(F) The global variables $a and $b are reserved for sort comparisons.
-You mentioned $a or $b in the same line as the <=> or cmp operator,
-and the variable had earlier been declared as a lexical variable.
-Either qualify the sort variable with the package name, or rename the
-lexical variable.
-</p>
-</dd>
-<dt>Can’t use %s ref as %s ref</dt>
-<dd><a name="perldiag-Can_0027t-use-_0025s-ref-as-_0025s-ref"></a>
-<p>(F) You’ve mixed up your reference types. You have to dereference a
-reference of the type needed. You can use the ref() function to
-test the type of the reference, if need be.
-</p>
-</dd>
-<dt>Can’t use string ("%s") as %s ref while "strict
refs" in use</dt>
-<dd><a
name="perldiag-Can_0027t-use-string-_0028_0022_0025s_0022_0029-as-_0025s-ref-while-_0022strict-refs_0022-in-use"></a>
-</dd>
-<dt>Can’t use string ("%s"...) as %s ref while "strict
refs" in use</dt>
-<dd><a
name="perldiag-Can_0027t-use-string-_0028_0022_0025s_0022_002e_002e_002e_0029-as-_0025s-ref-while-_0022strict-refs_0022-in-use"></a>
-<p>(F) You’ve told Perl to dereference a string, something which
-<code>use strict</code> blocks to prevent it happening accidentally. See
-<a href="#perlref-Symbolic-references">perlref Symbolic references</a>. This
can be triggered by an <code>@</code> or <code>$</code>
-in a double-quoted string immediately before interpolating a variable,
-for example in <code>"user @$twitter_id"</code>, which says to treat
the contents
-of <code>$twitter_id</code> as an array reference; use a <code>\</code> to
have a literal <code>@</code>
-symbol followed by the contents of <code>$twitter_id</code>: <code>"user
address@hidden"</code>.
-</p>
-</dd>
-<dt>Can’t use subscript on %s</dt>
-<dd><a name="perldiag-Can_0027t-use-subscript-on-_0025s"></a>
-<p>(F) The compiler tried to interpret a bracketed expression as a
-subscript. But to the left of the brackets was an expression that
-didn’t look like a hash or array reference, or anything else
subscriptable.
-</p>
-</dd>
-<dt>Can’t use \%c to mean $%c in expression</dt>
-<dd><a
name="perldiag-Can_0027t-use-_005c_0025c-to-mean-_0024_0025c-in-expression"></a>
-<p>(W syntax) In an ordinary expression, backslash is a unary operator that
-creates a reference to its argument. The use of backslash to indicate a
-backreference to a matched substring is valid only as part of a regular
-expression pattern. Trying to do this in ordinary Perl code produces a
-value that prints out looking like SCALAR(0xdecaf). Use the $1 form
-instead.
-</p>
-</dd>
-<dt>Can’t weaken a nonreference</dt>
-<dd><a name="perldiag-Can_0027t-weaken-a-nonreference"></a>
-<p>(F) You attempted to weaken something that was not a reference. Only
-references can be weakened.
-</p>
-</dd>
-<dt>Can’t "when" outside a topicalizer</dt>
-<dd><a name="perldiag-Can_0027t-_0022when_0022-outside-a-topicalizer"></a>
-<p>(F) You have used a when() block that is neither inside a
<code>foreach</code>
-loop nor a <code>given</code> block. (Note that this error is issued on exit
-from the <code>when</code> block, so you won’t get the error if the
match fails,
-or if you use an explicit <code>continue</code>.)
-</p>
-</dd>
-<dt>Can’t x= to read-only value</dt>
-<dd><a name="perldiag-Can_0027t-x_003d-to-read_002donly-value"></a>
-<p>(F) You tried to repeat a constant value (often the undefined value)
-with an assignment operator, which implies modifying the value itself.
-Perhaps you need to copy the value to a temporary, and repeat that.
-</p>
-</dd>
-<dt>Character following "\c" must be printable ASCII</dt>
-<dd><a
name="perldiag-Character-following-_0022_005cc_0022-must-be-printable-ASCII"></a>
-<p>(F) In <code>\c<em>X</em></code>, <em>X</em> must be a printable
(non-control) ASCII character.
-</p>
-<p>Note that ASCII characters that don’t map to control characters are
-discouraged, and will generate the warning (when enabled)
-<a
href="#perldiag-_0022_005cc_0025c_0022-is-more-clearly-written-simply-as-_0022_0025s_0022">"\c%c"
is more clearly written simply as "%s"</a>.
-</p>
-</dd>
-<dt>Character in ’C’ format wrapped in pack</dt>
-<dd><a name="perldiag-Character-in-_0027C_0027-format-wrapped-in-pack"></a>
-<p>(W pack) You said
-</p>
-<pre class="verbatim"> pack("C", $x)
-</pre>
-<p>where $x is either less than 0 or more than 255; the
<code>"C"</code> format is
-only for encoding native operating system characters (ASCII, EBCDIC,
-and so on) and not for Unicode characters, so Perl behaved as if you meant
-</p>
-<pre class="verbatim"> pack("C", $x & 255)
-</pre>
-<p>If you actually want to pack Unicode codepoints, use the
<code>"U"</code> format
-instead.
-</p>
-</dd>
-<dt>Character in ’c’ format wrapped in pack</dt>
-<dd><a name="perldiag-Character-in-_0027c_0027-format-wrapped-in-pack"></a>
-<p>(W pack) You said
-</p>
-<pre class="verbatim"> pack("c", $x)
-</pre>
-<p>where $x is either less than -128 or more than 127; the
<code>"c"</code> format
-is only for encoding native operating system characters (ASCII, EBCDIC,
-and so on) and not for Unicode characters, so Perl behaved as if you meant
-</p>
-<pre class="verbatim"> pack("c", $x & 255);
-</pre>
-<p>If you actually want to pack Unicode codepoints, use the
<code>"U"</code> format
-instead.
-</p>
-</dd>
-<dt>Character in ’%c’ format wrapped in unpack</dt>
-<dd><a
name="perldiag-Character-in-_0027_0025c_0027-format-wrapped-in-unpack"></a>
-<p>(W unpack) You tried something like
-</p>
-<pre class="verbatim"> unpack("H", "\x{2a1}")
-</pre>
-<p>where the format expects to process a byte (a character with a value
-below 256), but a higher value was provided instead. Perl uses the
-value modulus 256 instead, as if you had provided:
-</p>
-<pre class="verbatim"> unpack("H", "\x{a1}")
-</pre>
-</dd>
-<dt>Character in ’W’ format wrapped in pack</dt>
-<dd><a name="perldiag-Character-in-_0027W_0027-format-wrapped-in-pack"></a>
-<p>(W pack) You said
-</p>
-<pre class="verbatim"> pack("U0W", $x)
-</pre>
-<p>where $x is either less than 0 or more than 255. However,
<code>U0</code>-mode
-expects all values to fall in the interval [0, 255], so Perl behaved
-as if you meant:
-</p>
-<pre class="verbatim"> pack("U0W", $x & 255)
-</pre>
-</dd>
-<dt>Character(s) in ’%c’ format wrapped in pack</dt>
-<dd><a
name="perldiag-Character_0028s_0029-in-_0027_0025c_0027-format-wrapped-in-pack"></a>
-<p>(W pack) You tried something like
-</p>
-<pre class="verbatim"> pack("u", "\x{1f3}b")
-</pre>
-<p>where the format expects to process a sequence of bytes (character with a
-value below 256), but some of the characters had a higher value. Perl
-uses the character values modulus 256 instead, as if you had provided:
-</p>
-<pre class="verbatim"> pack("u", "\x{f3}b")
-</pre>
-</dd>
-<dt>Character(s) in ’%c’ format wrapped in unpack</dt>
-<dd><a
name="perldiag-Character_0028s_0029-in-_0027_0025c_0027-format-wrapped-in-unpack"></a>
-<p>(W unpack) You tried something like
-</p>
-<pre class="verbatim"> unpack("s", "\x{1f3}b")
-</pre>
-<p>where the format expects to process a sequence of bytes (character with a
-value below 256), but some of the characters had a higher value. Perl
-uses the character values modulus 256 instead, as if you had provided:
-</p>
-<pre class="verbatim"> unpack("s", "\x{f3}b")
-</pre>
-</dd>
-<dt>charnames alias definitions may not contain a sequence of multiple
spaces</dt>
-<dd><a
name="perldiag-charnames-alias-definitions-may-not-contain-a-sequence-of-multiple-spaces"></a>
-<p>(F) You defined a character name which had multiple space characters
-in a row. Change them to single spaces. Usually these names are
-defined in the <code>:alias</code> import argument to <code>use
charnames</code>, but they
-could be defined by a translator installed into <code>$^H{charnames}</code>.
See
-<a href="charnames.html#CUSTOM-ALIASES">(charnames)CUSTOM ALIASES</a>.
-</p>
-</dd>
-<dt>charnames alias definitions may not contain trailing white-space</dt>
-<dd><a
name="perldiag-charnames-alias-definitions-may-not-contain-trailing-white_002dspace"></a>
-<p>(F) You defined a character name which ended in a space
-character. Remove the trailing space(s). Usually these names are
-defined in the <code>:alias</code> import argument to <code>use
charnames</code>, but they
-could be defined by a translator installed into <code>$^H{charnames}</code>.
-See <a href="charnames.html#CUSTOM-ALIASES">(charnames)CUSTOM ALIASES</a>.
-</p>
-</dd>
-<dt>\C is deprecated in regex; marked by <– HERE<!-- /@w --> in
m/%s/</dt>
-<dd><a
name="perldiag-_005cC-is-deprecated-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(D deprecated, regexp) The \C character class is deprecated, and will
-become a compile-time error in a future release of perl (tentatively
-v5.24). This construct allows you to match a single byte of what makes
-up a multi-byte single UTF8 character, and breaks encapsulation. It is
-currently also very buggy. If you really need to process the individual
-bytes, you probably want to convert your string to one where each
-underlying byte is stored as a character, with utf8::encode().
-</p>
-</dd>
-<dt>"\c%c" is more clearly written simply as "%s"</dt>
-<dd><a
name="perldiag-_0022_005cc_0025c_0022-is-more-clearly-written-simply-as-_0022_0025s_0022"></a>
-<p>(W syntax) The <code>\c<em>X</em></code> 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. Doing it the way you did is not portable
-between ASCII and EBCDIC platforms.
-</p>
-</dd>
-<dt>Cloning substitution context is unimplemented</dt>
-<dd><a name="perldiag-Cloning-substitution-context-is-unimplemented"></a>
-<p>(F) Creating a new thread inside the <code>s///</code> operator is not
supported.
-</p>
-</dd>
-<dt>closedir() attempted on invalid dirhandle %s</dt>
-<dd><a
name="perldiag-closedir_0028_0029-attempted-on-invalid-dirhandle-_0025s"></a>
-<p>(W io) The dirhandle you tried to close is either closed or not really
-a dirhandle. Check your control flow.
-</p>
-</dd>
-<dt>close() on unopened filehandle %s</dt>
-<dd><a name="perldiag-close_0028_0029-on-unopened-filehandle-_0025s"></a>
-<p>(W unopened) You tried to close a filehandle that was never opened.
-</p>
-</dd>
-<dt>Closure prototype called</dt>
-<dd><a name="perldiag-Closure-prototype-called"></a>
-<p>(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.
-</p>
-</dd>
-<dt>Code missing after ’/’</dt>
-<dd><a name="perldiag-Code-missing-after-_0027_002f_0027"></a>
-<p>(F) You had a (sub-)template that ends with a ’/’. There must
be
-another template code following the slash. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>Code point 0x%X is not Unicode, may not be portable</dt>
-<dd><a
name="perldiag-Code-point-0x_0025X-is-not-Unicode_002c-may-not-be-portable"></a>
-<p>(S non_unicode) You had a code point above the Unicode maximum
-of U+10FFFF.
-</p>
-<p>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.
-</p>
-</dd>
-<dt>%s: Command not found</dt>
-<dd><a name="perldiag-_0025s_003a-Command-not-found"></a>
-<p>(A) You’ve accidentally run your script through <strong>csh</strong>
or another shell
-instead of Perl. Check the #! line, or manually feed your script into
-Perl yourself. The #! line at the top of your file could look like
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -w
-</pre>
-</dd>
-<dt>Compilation failed in require</dt>
-<dd><a name="perldiag-Compilation-failed-in-require"></a>
-<p>(F) Perl could not compile a file specified in a <code>require</code>
statement.
-Perl uses this generic message when none of the errors that it
-encountered were severe enough to halt compilation immediately.
-</p>
-</dd>
-<dt>Complex regular subexpression recursion limit (%d) exceeded</dt>
-<dd><a
name="perldiag-Complex-regular-subexpression-recursion-limit-_0028_0025d_0029-exceeded"></a>
-<p>(W regexp) The regular expression engine uses recursion in complex
-situations where back-tracking is required. Recursion depth is limited
-to 32766, or perhaps less in architectures where the stack cannot grow
-arbitrarily. ("Simple" and "medium" situations are
handled without
-recursion and are not subject to a limit.) Try shortening the string
-under examination; looping in Perl code (e.g. with <code>while</code>) rather
than
-in the regular expression engine; or rewriting the regular expression so
-that it is simpler or backtracks less. (See <a
href="perlfaq2.html#Top">(perlfaq2)</a> for information
-on <em>Mastering Regular Expressions</em>.)
-</p>
-</dd>
-<dt>connect() on closed socket %s</dt>
-<dd><a name="perldiag-connect_0028_0029-on-closed-socket-_0025s"></a>
-<p>(W closed) You tried to do a connect on a closed socket. Did you forget
-to check the return value of your socket() call? See
-‘perlfunc connect’.
-</p>
-</dd>
-<dt>Constant(%s): Call to &{$^H{%s}} did not return a defined value</dt>
-<dd><a
name="perldiag-Constant_0028_0025s_0029_003a-Call-to-_0026_007b_0024_005eH_007b_0025s_007d_007d-did-not-return-a-defined-value"></a>
-<p>(F) The subroutine registered to handle constant overloading
-(see <a href="overload.html#Top">(overload)</a>) or a custom charnames handler
(see
-<a href="charnames.html#CUSTOM-TRANSLATORS">(charnames)CUSTOM TRANSLATORS</a>)
returned an undefined value.
-</p>
-</dd>
-<dt>Constant(%s): $^H{%s} is not defined</dt>
-<dd><a
name="perldiag-Constant_0028_0025s_0029_003a-_0024_005eH_007b_0025s_007d-is-not-defined"></a>
-<p>(F) The parser found inconsistencies while attempting to define an
-overloaded constant. Perhaps you forgot to load the corresponding
-<a href="overload.html#Top">(overload)</a> pragma?
-</p>
-</dd>
-<dt>Constant is not %s reference</dt>
-<dd><a name="perldiag-Constant-is-not-_0025s-reference"></a>
-<p>(F) A constant value (perhaps declared using the <code>use constant</code>
pragma)
-is being dereferenced, but it amounts to the wrong type of reference.
-The message indicates the type of reference that was expected. This
-usually indicates a syntax error in dereferencing the constant value.
-See <a href="#perlsub-Constant-Functions">perlsub Constant Functions</a> and
<a href="constant.html#Top">(constant)</a>.
-</p>
-</dd>
-<dt>Constants from lexical variables potentially modified elsewhere are
deprecated</dt>
-<dd><a
name="perldiag-Constants-from-lexical-variables-potentially-modified-elsewhere-are-deprecated"></a>
-<p>(D deprecated) You wrote something like
-</p>
-<pre class="verbatim"> my $var;
- $sub = sub () { $var };
-</pre>
-<p>but $var is referenced elsewhere and could be modified after the
<code>sub</code>
-expression is evaluated. Either it is explicitly modified elsewhere
-(<code>$var = 3</code>) or it is passed to a subroutine or to an operator like
-<code>printf</code> or <code>map</code>, which may or may not modify the
variable.
-</p>
-<p>Traditionally, Perl has captured the value of the variable at that
-point and turned the subroutine into a constant eligible for inlining.
-In those cases where the variable can be modified elsewhere, this
-breaks the behavior of closures, in which the subroutine captures
-the variable itself, rather than its value, so future changes to the
-variable are reflected in the subroutine’s return value.
-</p>
-<p>This usage is deprecated, because the behavior is likely to change
-in a future version of Perl.
-</p>
-<p>If you intended for the subroutine to be eligible for inlining, then
-make sure the variable is not referenced elsewhere, possibly by
-copying it:
-</p>
-<pre class="verbatim"> my $var2 = $var;
- $sub = sub () { $var2 };
-</pre>
-<p>If you do want this subroutine to be a closure that reflects future
-changes to the variable that it closes over, add an explicit
<code>return</code>:
-</p>
-<pre class="verbatim"> my $var;
- $sub = sub () { return $var };
-</pre>
-</dd>
-<dt>Constant subroutine %s redefined</dt>
-<dd><a name="perldiag-Constant-subroutine-_0025s-redefined"></a>
-<p>(W redefine)(S) You redefined a subroutine which had previously
-been eligible for inlining. See <a href="#perlsub-Constant-Functions">perlsub
Constant Functions</a>
-for commentary and workarounds.
-</p>
-</dd>
-<dt>Constant subroutine %s undefined</dt>
-<dd><a name="perldiag-Constant-subroutine-_0025s-undefined"></a>
-<p>(W misc) You undefined a subroutine which had previously been eligible
-for inlining. See <a href="#perlsub-Constant-Functions">perlsub Constant
Functions</a> for commentary and
-workarounds.
-</p>
-</dd>
-<dt>Constant(%s) unknown</dt>
-<dd><a name="perldiag-Constant_0028_0025s_0029-unknown"></a>
-<p>(F) The parser found inconsistencies either while attempting
-to define an overloaded constant, or when trying to find the
-character name specified in the <code>\N{...}</code> escape. Perhaps you
-forgot to load the corresponding <a href="overload.html#Top">(overload)</a>
pragma?
-</p>
-</dd>
-<dt>:const is experimental</dt>
-<dd><a name="perldiag-_003aconst-is-experimental"></a>
-<p>(S experimental::const_attr) The "const" attribute is
experimental.
-If you want to use the feature, disable the warning with <code>no warnings
-'experimental::const_attr'</code>, but know that in doing so you are taking
-the risk that your code may break in a future Perl version.
-</p>
-</dd>
-<dt>:const is not permitted on named subroutines</dt>
-<dd><a name="perldiag-_003aconst-is-not-permitted-on-named-subroutines"></a>
-<p>(F) The "const" attribute causes an anonymous subroutine to be
run and
-its value captured at the time that it is cloned. Named subroutines are
-not cloned like this, so the attribute does not make sense on them.
-</p>
-</dd>
-<dt>Copy method did not return a reference</dt>
-<dd><a name="perldiag-Copy-method-did-not-return-a-reference"></a>
-<p>(F) The method which overloads "=" is buggy. See
-<a href="overload.html#Copy-Constructor">(overload)Copy Constructor</a>.
-</p>
-</dd>
-<dt>&CORE::%s cannot be called directly</dt>
-<dd><a name="perldiag-_0026CORE_003a_003a_0025s-cannot-be-called-directly"></a>
-<p>(F) You tried to call a subroutine in the <code>CORE::</code> namespace
-with <code>&foo</code> syntax or through a reference. Some subroutines
-in this package cannot yet be called that way, but must be
-called as barewords. Something like this will work:
-</p>
-<pre class="verbatim"> BEGIN { *shove = \&CORE::push; }
- shove @array, 1,2,3; # pushes on to @array
-</pre>
-</dd>
-<dt>CORE::%s is not a keyword</dt>
-<dd><a name="perldiag-CORE_003a_003a_0025s-is-not-a-keyword"></a>
-<p>(F) The CORE:: namespace is reserved for Perl keywords.
-</p>
-</dd>
-<dt>Corrupted regexp opcode %d > %d</dt>
-<dd><a name="perldiag-Corrupted-regexp-opcode-_0025d-_003e-_0025d"></a>
-<p>(P) This is either an error in Perl, or, if you’re using
-one, your <a href="#perlreapi-NAME">custom regular expression engine</a>. If
not the
-latter, report the problem through the <a
href="perlbug.html#Top">(perlbug)</a> utility.
-</p>
-</dd>
-<dt>corrupted regexp pointers</dt>
-<dd><a name="perldiag-corrupted-regexp-pointers"></a>
-<p>(P) The regular expression engine got confused by what the regular
-expression compiler gave it.
-</p>
-</dd>
-<dt>corrupted regexp program</dt>
-<dd><a name="perldiag-corrupted-regexp-program"></a>
-<p>(P) The regular expression engine got passed a regexp program without a
-valid magic number.
-</p>
-</dd>
-<dt>Corrupt malloc ptr 0x%x at 0x%x</dt>
-<dd><a name="perldiag-Corrupt-malloc-ptr-0x_0025x-at-0x_0025x"></a>
-<p>(P) The malloc package that comes with Perl had an internal failure.
-</p>
-</dd>
-<dt>Count after length/code in unpack</dt>
-<dd><a name="perldiag-Count-after-length_002fcode-in-unpack"></a>
-<p>(F) You had an unpack template indicating a counted-length string, but
-you have also specified an explicit size for the string. See
-‘perlfunc pack’.
-</p>
-</dd>
-<dt>Deep recursion on anonymous subroutine</dt>
-<dd><a name="perldiag-Deep-recursion-on-anonymous-subroutine"></a>
-</dd>
-<dt>Deep recursion on subroutine "%s"</dt>
-<dd><a name="perldiag-Deep-recursion-on-subroutine-_0022_0025s_0022"></a>
-<p>(W recursion) This subroutine has called itself (directly or indirectly)
-100 times more than it has returned. This probably indicates an
-infinite recursion, unless you’re writing strange benchmark programs, in
-which case it indicates something else.
-</p>
-<p>This threshold can be changed from 100, by recompiling the
<samp>perl</samp> binary,
-setting the C pre-processor macro <code>PERL_SUB_DEPTH_WARN</code> to the
desired value.
-</p>
-</dd>
-<dt>(?(DEFINE)....) does not allow branches in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-_0028_003f_0028DEFINE_0029_002e_002e_002e_002e_0029-does-not-allow-branches-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You used something like <code>(?(DEFINE)...|..)</code> which is
illegal. The
-most likely cause of this error is that you left out a parenthesis inside
-of the <code>....</code> part.
-</p>
-<p>The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the problem was
-discovered.
-</p>
-</dd>
-<dt>%s defines neither package nor VERSION–version check failed</dt>
-<dd><a
name="perldiag-_0025s-defines-neither-package-nor-VERSION_002d_002dversion-check-failed"></a>
-<p>(F) You said something like "use Module 42" but in the Module file
-there are neither package declarations nor a <code>$VERSION</code>.
-</p>
-</dd>
-<dt>delete argument is index/value array slice, use array slice</dt>
-<dd><a
name="perldiag-delete-argument-is-index_002fvalue-array-slice_002c-use-array-slice"></a>
-<p>(F) You used index/value array slice syntax (<code>%array[...]</code>) as
-the argument to <code>delete</code>. You probably meant
<code>@array[...]</code> with
-an @ symbol instead.
-</p>
-</dd>
-<dt>delete argument is key/value hash slice, use hash slice</dt>
-<dd><a
name="perldiag-delete-argument-is-key_002fvalue-hash-slice_002c-use-hash-slice"></a>
-<p>(F) You used key/value hash slice syntax (<code>%hash{...}</code>) as the
argument to
-<code>delete</code>. You probably meant <code>@hash{...}</code> with an @
symbol instead.
-</p>
-</dd>
-<dt>delete argument is not a HASH or ARRAY element or slice</dt>
-<dd><a
name="perldiag-delete-argument-is-not-a-HASH-or-ARRAY-element-or-slice"></a>
-<p>(F) The argument to <code>delete</code> must be either a hash or array
element,
-such as:
-</p>
-<pre class="verbatim"> $foo{$bar}
- $ref->{"susie"}[12]
-</pre>
-<p>or a hash or array slice, such as:
-</p>
-<pre class="verbatim"> @foo[$bar, $baz, $xyzzy]
- @{$ref->[12]}{"susie", "queue"}
-</pre>
-</dd>
-<dt>Delimiter for here document is too long</dt>
-<dd><a name="perldiag-Delimiter-for-here-document-is-too-long"></a>
-<p>(F) In a here document construct like <code><<FOO</code>, the label
<code>FOO</code> is too
-long for Perl to handle. You have to be seriously twisted to write code
-that triggers this error.
-</p>
-</dd>
-<dt>Deprecated use of my() in false conditional</dt>
-<dd><a name="perldiag-Deprecated-use-of-my_0028_0029-in-false-conditional"></a>
-<p>(D deprecated) You used a declaration similar to <code>my $x if 0</code>.
There
-has been a long-standing bug in Perl that causes a lexical variable
-not to be cleared at scope exit when its declaration includes a false
-conditional. Some people have exploited this bug to achieve a kind of
-static variable. Since we intend to fix this bug, we don’t want people
-relying on this behavior. You can achieve a similar static effect by
-declaring the variable in a separate block outside the function, eg
-</p>
-<pre class="verbatim"> sub f { my $x if 0; return $x++ }
-</pre>
-<p>becomes
-</p>
-<pre class="verbatim"> { my $x; sub f { return $x++ } }
-</pre>
-<p>Beginning with perl 5.10.0, you can also use <code>state</code> variables
to have
-lexicals that are initialized only once (see <a
href="feature.html#Top">(feature)</a>):
-</p>
-<pre class="verbatim"> sub f { state $x; return $x++ }
-</pre>
-</dd>
-<dt>DESTROY created new reference to dead object ’%s’</dt>
-<dd><a
name="perldiag-DESTROY-created-new-reference-to-dead-object-_0027_0025s_0027"></a>
-<p>(F) A DESTROY() method created a new reference to the object which is
-just being DESTROYed. Perl is confused, and prefers to abort rather
-than to create a dangling reference.
-</p>
-</dd>
-<dt>Did not produce a valid header</dt>
-<dd><a name="perldiag-Did-not-produce-a-valid-header"></a>
-<p>See Server error.
-</p>
-</dd>
-<dt>%s did not return a true value</dt>
-<dd><a name="perldiag-_0025s-did-not-return-a-true-value"></a>
-<p>(F) A required (or used) file must return a true value to indicate that
-it compiled correctly and ran its initialization code correctly. It’s
-traditional to end such a file with a "1;", though any true value
would
-do. See <a href="#perlfunc-require">perlfunc require</a>.
-</p>
-</dd>
-<dt>(Did you mean &%s instead?)</dt>
-<dd><a name="perldiag-_0028Did-you-mean-_0026_0025s-instead_003f_0029"></a>
-<p>(W misc) You probably referred to an imported subroutine &FOO as $FOO or
-some such.
-</p>
-</dd>
-<dt>(Did you mean "local" instead of "our"?)</dt>
-<dd><a
name="perldiag-_0028Did-you-mean-_0022local_0022-instead-of-_0022our_0022_003f_0029"></a>
-<p>(W misc) Remember that "our" does not localize the declared global
-variable. You have declared it again in the same lexical scope, which
-seems superfluous.
-</p>
-</dd>
-<dt>(Did you mean $ or @ instead of %?)</dt>
-<dd><a
name="perldiag-_0028Did-you-mean-_0024-or-_0040-instead-of-_0025_003f_0029"></a>
-<p>(W) You probably said %hash{$key} when you meant $hash{$key} or
address@hidden@keys}. On the other hand, maybe you just meant %hash and got
-carried away.
-</p>
-</dd>
-<dt>Died</dt>
-<dd><a name="perldiag-Died"></a>
-<p>(F) You passed die() an empty string (the equivalent of <code>die
""</code>) or
-you called it with no args and <code>$@</code> was empty.
-</p>
-</dd>
-<dt>Document contains no data</dt>
-<dd><a name="perldiag-Document-contains-no-data"></a>
-<p>See Server error.
-</p>
-</dd>
-<dt>%s does not define %s::VERSION–version check failed</dt>
-<dd><a
name="perldiag-_0025s-does-not-define-_0025s_003a_003aVERSION_002d_002dversion-check-failed"></a>
-<p>(F) You said something like "use Module 42" but the Module did not
-define a <code>$VERSION</code>.
-</p>
-</dd>
-<dt>’/’ does not take a repeat count</dt>
-<dd><a name="perldiag-_0027_002f_0027-does-not-take-a-repeat-count"></a>
-<p>(F) You cannot put a repeat count of any kind right after the
’/’ code.
-See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>Don’t know how to get file name</dt>
-<dd><a name="perldiag-Don_0027t-know-how-to-get-file-name"></a>
-<p>(P) <code>PerlIO_getname</code>, a perl internal I/O function specific to
VMS, was
-somehow called on another platform. This should not happen.
-</p>
-</dd>
-<dt>Don’t know how to handle magic of type \%o</dt>
-<dd><a
name="perldiag-Don_0027t-know-how-to-handle-magic-of-type-_005c_0025o"></a>
-<p>(P) The internal handling of magical variables has been cursed.
-</p>
-</dd>
-<dt>do_study: out of memory</dt>
-<dd><a name="perldiag-do_005fstudy_003a-out-of-memory"></a>
-<p>(P) This should have been caught by safemalloc() instead.
-</p>
-</dd>
-<dt>(Do you need to predeclare %s?)</dt>
-<dd><a name="perldiag-_0028Do-you-need-to-predeclare-_0025s_003f_0029"></a>
-<p>(S syntax) This is an educated guess made in conjunction with the message
-"%s found where operator expected". It often means a subroutine or
module
-name is being referenced that hasn’t been declared yet. This may be
-because of ordering problems in your file, or because of a missing
-"sub", "package", "require", or "use"
statement. If you’re referencing
-something that isn’t defined yet, you don’t actually have to
define the
-subroutine or package before the current location. You can use an empty
-"sub foo;" or "package FOO;" to enter a
"forward" declaration.
-</p>
-</dd>
-<dt>dump() better written as CORE::dump()</dt>
-<dd><a
name="perldiag-dump_0028_0029-better-written-as-CORE_003a_003adump_0028_0029"></a>
-<p>(W misc) You used the obsolescent <code>dump()</code> built-in function,
without fully
-qualifying it as <code>CORE::dump()</code>. Maybe it’s a typo. See <a
href="#perlfunc-dump">perlfunc dump</a>.
-</p>
-</dd>
-<dt>dump is not supported</dt>
-<dd><a name="perldiag-dump-is-not-supported"></a>
-<p>(F) Your machine doesn’t support dump/undump.
-</p>
-</dd>
-<dt>Duplicate free() ignored</dt>
-<dd><a name="perldiag-Duplicate-free_0028_0029-ignored"></a>
-<p>(S malloc) An internal routine called free() on something that had
-already been freed.
-</p>
-</dd>
-<dt>Duplicate modifier ’%c’ after ’%c’ in %s</dt>
-<dd><a
name="perldiag-Duplicate-modifier-_0027_0025c_0027-after-_0027_0025c_0027-in-_0025s"></a>
-<p>(W unpack) You have applied the same modifier more than once after a
-type in a pack template. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>each on reference is experimental</dt>
-<dd><a name="perldiag-each-on-reference-is-experimental"></a>
-<p>(S experimental::autoderef) <code>each</code> with a scalar argument is
experimental
-and may change or be removed in a future Perl version. If you want to
-take the risk of using this feature, simply disable this warning:
-</p>
-<pre class="verbatim"> no warnings "experimental::autoderef";
-</pre>
-</dd>
-<dt>elseif should be elsif</dt>
-<dd><a name="perldiag-elseif-should-be-elsif"></a>
-<p>(S syntax) There is no keyword "elseif" in Perl because Larry
thinks
-it’s ugly. Your code will be interpreted as an attempt to call a method
-named "elseif" for the class returned by the following block. This
is
-unlikely to be what you want.
-</p>
-</dd>
-<dt>Empty \%c{} in regex; marked by <– HERE<!-- /@w --> in
m/%s/</dt>
-<dd><a
name="perldiag-Empty-_005c_0025c_007b_007d-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) <code>\p</code> and <code>\P</code> are used to introduce a named
Unicode property, as
-described in <a href="#perlunicode-NAME">perlunicode NAME</a> and <a
href="#perlre-NAME">perlre NAME</a>. You used <code>\p</code> or
<code>\P</code> in
-a regular expression without specifying the property name.
-</p>
-</dd>
-<dt>entering effective %s failed</dt>
-<dd><a name="perldiag-entering-effective-_0025s-failed"></a>
-<p>(F) While under the <code>use filetest</code> pragma, switching the real and
-effective uids or gids failed.
-</p>
-</dd>
-<dt>%ENV is aliased to %s</dt>
-<dd><a name="perldiag-_0025ENV-is-aliased-to-_0025s"></a>
-<p>(F) You’re running under taint mode, and the <code>%ENV</code>
variable has been
-aliased to another hash, so it doesn’t reflect anymore the state of the
-program’s environment. This is potentially insecure.
-</p>
-</dd>
-<dt>Error converting file specification %s</dt>
-<dd><a name="perldiag-Error-converting-file-specification-_0025s"></a>
-<p>(F) An error peculiar to VMS. Because Perl may have to deal with file
-specifications in either VMS or Unix syntax, it converts them to a
-single form when it must operate on them directly. Either you’ve passed
-an invalid file specification to Perl, or you’ve found a case the
-conversion routines don’t handle. Drat.
-</p>
-</dd>
-<dt>Eval-group in insecure regular expression</dt>
-<dd><a name="perldiag-Eval_002dgroup-in-insecure-regular-expression"></a>
-<p>(F) Perl detected tainted data when trying to compile a regular
-expression that contains the <code>(?{ ... })</code> zero-width assertion,
which
-is unsafe. See <a href="#perlre-_0028_003f_007b-code-_007d_0029">perlre
<code>(?{ code })</code></a>, and <a href="#perlsec-NAME">perlsec NAME</a>.
-</p>
-</dd>
-<dt>Eval-group not allowed at runtime, use re ’eval’ in regex
m/%s/</dt>
-<dd><a
name="perldiag-Eval_002dgroup-not-allowed-at-runtime_002c-use-re-_0027eval_0027-in-regex-m_002f_0025s_002f"></a>
-<p>(F) Perl tried to compile a regular expression containing the
-<code>(?{ ... })</code> 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 using the
-<code>re 'eval'</code> pragma or by explicitly building the pattern from an
-interpolated string at run time and using that in an eval(). See
-<a href="#perlre-_0028_003f_007b-code-_007d_0029">perlre <code>(?{ code
})</code></a>.
-</p>
-</dd>
-<dt>Eval-group not allowed, use re ’eval’ in regex m/%s/</dt>
-<dd><a
name="perldiag-Eval_002dgroup-not-allowed_002c-use-re-_0027eval_0027-in-regex-m_002f_0025s_002f"></a>
-<p>(F) A regular expression contained the <code>(?{ ... })</code> zero-width
-assertion, but that construct is only allowed when the <code>use re
'eval'</code>
-pragma is in effect. See <a
href="#perlre-_0028_003f_007b-code-_007d_0029">perlre <code>(?{ code
})</code></a>.
-</p>
-</dd>
-<dt>EVAL without pos change exceeded limit in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-EVAL-without-pos-change-exceeded-limit-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You used a pattern that nested too many EVAL calls without consuming
-any text. Restructure the pattern so that text is consumed.
-</p>
-<p>The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the problem was
-discovered.
-</p>
-</dd>
-<dt>Excessively long <> operator</dt>
-<dd><a name="perldiag-Excessively-long-_003c_003e-operator"></a>
-<p>(F) The contents of a <> operator may not exceed the maximum size of a
-Perl identifier. If you’re just trying to glob a long list of
-filenames, try using the glob() operator, or put the filenames into a
-variable and glob that.
-</p>
-</dd>
-<dt>exec? I’m not *that* kind of operating system</dt>
-<dd><a
name="perldiag-exec_003f-I_0027m-not-_002athat_002a-kind-of-operating-system"></a>
-<p>(F) The <code>exec</code> function is not implemented on some systems,
e.g., Symbian
-OS. See <a href="#perlport-NAME">perlport NAME</a>.
-</p>
-</dd>
-<dt>Execution of %s aborted due to compilation errors.</dt>
-<dd><a
name="perldiag-Execution-of-_0025s-aborted-due-to-compilation-errors_002e"></a>
-<p>(F) The final summary message when a Perl compilation fails.
-</p>
-</dd>
-<dt>exists argument is not a HASH or ARRAY element or a subroutine</dt>
-<dd><a
name="perldiag-exists-argument-is-not-a-HASH-or-ARRAY-element-or-a-subroutine"></a>
-<p>(F) The argument to <code>exists</code> must be a hash or array element or a
-subroutine with an ampersand, such as:
-</p>
-<pre class="verbatim"> $foo{$bar}
- $ref->{"susie"}[12]
- &do_something
-</pre>
-</dd>
-<dt>exists argument is not a subroutine name</dt>
-<dd><a name="perldiag-exists-argument-is-not-a-subroutine-name"></a>
-<p>(F) The argument to <code>exists</code> for <code>exists &sub</code>
must be a subroutine name,
-and not a subroutine call. <code>exists &sub()</code> will generate this
error.
-</p>
-</dd>
-<dt>Exiting eval via %s</dt>
-<dd><a name="perldiag-Exiting-eval-via-_0025s"></a>
-<p>(W exiting) You are exiting an eval by unconventional means, such as a
-goto, or a loop control statement.
-</p>
-</dd>
-<dt>Exiting format via %s</dt>
-<dd><a name="perldiag-Exiting-format-via-_0025s"></a>
-<p>(W exiting) You are exiting a format by unconventional means, such as a
-goto, or a loop control statement.
-</p>
-</dd>
-<dt>Exiting pseudo-block via %s</dt>
-<dd><a name="perldiag-Exiting-pseudo_002dblock-via-_0025s"></a>
-<p>(W exiting) You are exiting a rather special block construct (like a
-sort block or subroutine) by unconventional means, such as a goto, or a
-loop control statement. See ‘perlfunc sort’.
-</p>
-</dd>
-<dt>Exiting subroutine via %s</dt>
-<dd><a name="perldiag-Exiting-subroutine-via-_0025s"></a>
-<p>(W exiting) You are exiting a subroutine by unconventional means, such
-as a goto, or a loop control statement.
-</p>
-</dd>
-<dt>Exiting substitution via %s</dt>
-<dd><a name="perldiag-Exiting-substitution-via-_0025s"></a>
-<p>(W exiting) You are exiting a substitution by unconventional means, such
-as a return, a goto, or a loop control statement.
-</p>
-</dd>
-<dt>Expecting close bracket in regex; marked by <– HERE<!-- /@w
--> in m/%s/</dt>
-<dd><a
name="perldiag-Expecting-close-bracket-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You wrote something like
-</p>
-<pre class="verbatim"> (?13
-</pre>
-<p>to denote a capturing group of the form
-<a
href="#perlre-_0028_003fPARNO_0029-_0028_003f_002dPARNO_0029-_0028_003f_002bPARNO_0029-_0028_003fR_0029-_0028_003f0_0029"><code>(?<em>PARNO</em>)</code></a>,
-but omitted the <code>")"</code>.
-</p>
-</dd>
-<dt>Expecting ’(?flags:(?[...’ in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Expecting-_0027_0028_003fflags_003a_0028_003f_005b_002e_002e_002e_0027-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The <code>(?[...])</code> extended character class regular expression
construct
-only allows character classes (including character class escapes like
-<code>\d</code>), operators, and parentheses. The one exception is
<code>(?flags:...)</code>
-containing at least one flag and exactly one <code>(?[...])</code> construct.
-This allows a regular expression containing just <code>(?[...])</code> to be
-interpolated. If you see this error message, then you probably
-have some other <code>(?...)</code> construct inside your character class. See
-<a
href="#perlrecharclass-Extended-Bracketed-Character-Classes">perlrecharclass
Extended Bracketed Character Classes</a>.
-</p>
-</dd>
-<dt>Experimental aliasing via reference not enabled</dt>
-<dd><a name="perldiag-Experimental-aliasing-via-reference-not-enabled"></a>
-<p>(F) To do aliasing via references, you must first enable the feature:
-</p>
-<pre class="verbatim"> no warnings "experimental::refaliasing";
- use feature "refaliasing";
- \$x = \$y;
-</pre>
-</dd>
-<dt>Experimental subroutine signatures not enabled</dt>
-<dd><a name="perldiag-Experimental-subroutine-signatures-not-enabled"></a>
-<p>(F) To use subroutine signatures, you must first enable them:
-</p>
-<pre class="verbatim"> no warnings "experimental::signatures";
- use feature "signatures";
- sub foo ($left, $right) { ... }
-</pre>
-</dd>
-<dt>Experimental "%s" subs not enabled</dt>
-<dd><a name="perldiag-Experimental-_0022_0025s_0022-subs-not-enabled"></a>
-<p>(F) To use lexical subs, you must first enable them:
-</p>
-<pre class="verbatim"> no warnings 'experimental::lexical_subs';
- use feature 'lexical_subs';
- my sub foo { ... }
-</pre>
-</dd>
-<dt>Explicit blessing to ” (assuming package main)</dt>
-<dd><a
name="perldiag-Explicit-blessing-to-_0027_0027-_0028assuming-package-main_0029"></a>
-<p>(W misc) You are blessing a reference to a zero length string. This has
-the effect of blessing the reference into the package main. This is
-usually not what you want. Consider providing a default target package,
-e.g. bless($ref, $p || ’MyPackage’);
-</p>
-</dd>
-<dt>%s: Expression syntax</dt>
-<dd><a name="perldiag-_0025s_003a-Expression-syntax"></a>
-<p>(A) You’ve accidentally run your script through <strong>csh</strong>
instead of Perl.
-Check the #! line, or manually feed your script into Perl yourself.
-</p>
-</dd>
-<dt>%s failed–call queue aborted</dt>
-<dd><a name="perldiag-_0025s-failed_002d_002dcall-queue-aborted"></a>
-<p>(F) An untrapped exception was raised while executing a UNITCHECK,
-CHECK, INIT, or END subroutine. Processing of the remainder of the
-queue of such routines has been prematurely ended.
-</p>
-</dd>
-<dt>False [] range "%s" in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-False-_005b_005d-range-_0022_0025s_0022-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp)(F) A character class range must start and end at a literal
-character, not another character class like <code>\d</code> or
<code>[:alpha:]</code>. The "-"
-in your false range is interpreted as a literal "-". In a
<code>(?[...])</code>
-construct, this is an error, rather than a warning. Consider quoting
-the "-", "\-". The <– HERE<!-- /@w -->
shows whereabouts in the regular expression
-the problem was discovered. See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Fatal VMS error (status=%d) at %s, line %d</dt>
-<dd><a
name="perldiag-Fatal-VMS-error-_0028status_003d_0025d_0029-at-_0025s_002c-line-_0025d"></a>
-<p>(P) An error peculiar to VMS. Something untoward happened in a VMS
-system service or RTL routine; Perl’s exit status should provide more
-details. The filename in "at %s" and the line number in "line
%d" tell
-you which section of the Perl source code is distressed.
-</p>
-</dd>
-<dt>fcntl is not implemented</dt>
-<dd><a name="perldiag-fcntl-is-not-implemented"></a>
-<p>(F) Your machine apparently doesn’t implement fcntl(). What is this,
a
-PDP-11 or something?
-</p>
-</dd>
-<dt>FETCHSIZE returned a negative value</dt>
-<dd><a name="perldiag-FETCHSIZE-returned-a-negative-value"></a>
-<p>(F) A tied array claimed to have a negative number of elements, which
-is not possible.
-</p>
-</dd>
-<dt>Field too wide in ’u’ format in pack</dt>
-<dd><a name="perldiag-Field-too-wide-in-_0027u_0027-format-in-pack"></a>
-<p>(W pack) Each line in an uuencoded string starts with a length indicator
-which can’t encode values above 63. So there is no point in asking for
-a line length bigger than that. Perl will behave as if you specified
-<code>u63</code> as the format.
-</p>
-</dd>
-<dt>Filehandle %s opened only for input</dt>
-<dd><a name="perldiag-Filehandle-_0025s-opened-only-for-input"></a>
-<p>(W io) You tried to write on a read-only filehandle. 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
-write the file, use ">" or ">>". See
‘perlfunc open’.
-</p>
-</dd>
-<dt>Filehandle %s opened only for output</dt>
-<dd><a name="perldiag-Filehandle-_0025s-opened-only-for-output"></a>
-<p>(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 ">". If you intended only to
-read from the file, use "<". See ‘perlfunc open’.
Another possibility
-is that you attempted to open filedescriptor 0 (also known as STDIN) for
-output (maybe you closed STDIN earlier?).
-</p>
-</dd>
-<dt>Filehandle %s reopened as %s only for input</dt>
-<dd><a name="perldiag-Filehandle-_0025s-reopened-as-_0025s-only-for-input"></a>
-<p>(W io) You opened for reading a filehandle that got the same filehandle id
-as STDOUT or STDERR. This occurred because you closed STDOUT or STDERR
-previously.
-</p>
-</dd>
-<dt>Filehandle STDIN reopened as %s only for output</dt>
-<dd><a name="perldiag-Filehandle-STDIN-reopened-as-_0025s-only-for-output"></a>
-<p>(W io) You opened for writing a filehandle that got the same filehandle id
-as STDIN. This occurred because you closed STDIN previously.
-</p>
-</dd>
-<dt>Final $ should be \$ or $name</dt>
-<dd><a name="perldiag-Final-_0024-should-be-_005c_0024-or-_0024name"></a>
-<p>(F) You must now decide whether the final $ in a string was meant to be
-a literal dollar sign, or was meant to introduce a variable name that
-happens to be missing. So you have to put either the backslash or the
-name.
-</p>
-</dd>
-<dt>flock() on closed filehandle %s</dt>
-<dd><a name="perldiag-flock_0028_0029-on-closed-filehandle-_0025s"></a>
-<p>(W closed) The filehandle you’re attempting to flock() got itself
closed
-some time before now. Check your control flow. flock() operates on
-filehandles. Are you attempting to call flock() on a dirhandle by the
-same name?
-</p>
-</dd>
-<dt>Format not terminated</dt>
-<dd><a name="perldiag-Format-not-terminated"></a>
-<p>(F) A format must be terminated by a line with a solitary dot. Perl got
-to the end of your file without finding such a line.
-</p>
-</dd>
-<dt>Format %s redefined</dt>
-<dd><a name="perldiag-Format-_0025s-redefined"></a>
-<p>(W redefine) You redefined a format. To suppress this warning, say
-</p>
-<pre class="verbatim"> {
- no warnings 'redefine';
- eval "format NAME =...";
- }
-</pre>
-</dd>
-<dt>Found = in conditional, should be ==</dt>
-<dd><a
name="perldiag-Found-_003d-in-conditional_002c-should-be-_003d_003d"></a>
-<p>(W syntax) You said
-</p>
-<pre class="verbatim"> if ($foo = 123)
-</pre>
-<p>when you meant
-</p>
-<pre class="verbatim"> if ($foo == 123)
-</pre>
-<p>(or something like that).
-</p>
-</dd>
-<dt>%s found where operator expected</dt>
-<dd><a name="perldiag-_0025s-found-where-operator-expected"></a>
-<p>(S syntax) The Perl lexer knows whether to expect a term or an operator.
-If it sees what it knows to be a term when it was expecting to see an
-operator, it gives you this warning. Usually it indicates that an
-operator or delimiter was omitted, such as a semicolon.
-</p>
-</dd>
-<dt>gdbm store returned %d, errno %d, key "%s"</dt>
-<dd><a
name="perldiag-gdbm-store-returned-_0025d_002c-errno-_0025d_002c-key-_0022_0025s_0022"></a>
-<p>(S) A warning from the GDBM_File extension that a store failed.
-</p>
-</dd>
-<dt>gethostent not implemented</dt>
-<dd><a name="perldiag-gethostent-not-implemented"></a>
-<p>(F) Your C library apparently doesn’t implement gethostent(), probably
-because if it did, it’d feel morally obligated to return every hostname
-on the Internet.
-</p>
-</dd>
-<dt>get%sname() on closed socket %s</dt>
-<dd><a name="perldiag-get_0025sname_0028_0029-on-closed-socket-_0025s"></a>
-<p>(W closed) You tried to get a socket or peer socket name on a closed
-socket. Did you forget to check the return value of your socket() call?
-</p>
-</dd>
-<dt>getpwnam returned invalid UIC %#o for user "%s"</dt>
-<dd><a
name="perldiag-getpwnam-returned-invalid-UIC-_0025_0023o-for-user-_0022_0025s_0022"></a>
-<p>(S) A warning peculiar to VMS. The call to <code>sys$getuai</code>
underlying the
-<code>getpwnam</code> operator returned an invalid UIC.
-</p>
-</dd>
-<dt>getsockopt() on closed socket %s</dt>
-<dd><a name="perldiag-getsockopt_0028_0029-on-closed-socket-_0025s"></a>
-<p>(W closed) You tried to get a socket option on a closed socket. Did you
-forget to check the return value of your socket() call? See
-‘perlfunc getsockopt’.
-</p>
-</dd>
-<dt>given is experimental</dt>
-<dd><a name="perldiag-given-is-experimental"></a>
-<p>(S experimental::smartmatch) <code>given</code> depends on smartmatch, which
-is experimental, so its behavior may change or even be removed
-in any future release of perl. See the explanation under
-<a href="#perlsyn-Experimental-Details-on-given-and-when">perlsyn Experimental
Details on given and when</a>.
-</p>
-</dd>
-<dt>Global symbol "%s" requires explicit package name (did you
forget to declare "my %s"?)</dt>
-<dd><a
name="perldiag-Global-symbol-_0022_0025s_0022-requires-explicit-package-name-_0028did-you-forget-to-declare-_0022my-_0025s_0022_003f_0029"></a>
-<p>(F) You’ve said "use strict" or "use strict
vars", which indicates
-that all variables must either be lexically scoped (using "my" or
"state"),
-declared beforehand using "our", or explicitly qualified to say
-which package the global variable is in (using "::").
-</p>
-</dd>
-<dt>glob failed (%s)</dt>
-<dd><a name="perldiag-glob-failed-_0028_0025s_0029"></a>
-<p>(S glob) Something went wrong with the external program(s) used
-for <code>glob</code> and <code><*.c></code>. Usually, this means that
you supplied a <code>glob</code>
-pattern that caused the external program to fail and exit with a
-nonzero status. If the message indicates that the abnormal exit
-resulted in a coredump, this may also mean that your csh (C shell)
-is broken. If so, you should change all of the csh-related variables
-in config.sh: If you have tcsh, make the variables refer to it as
-if it were csh (e.g. <code>full_csh='/usr/bin/tcsh'</code>); otherwise, make
them
-all empty (except that <code>d_csh</code> should be <code>'undef'</code>) so
that Perl will
-think csh is missing. In either case, after editing config.sh, run
-<code>./Configure -S</code> and rebuild Perl.
-</p>
-</dd>
-<dt>Glob not terminated</dt>
-<dd><a name="perldiag-Glob-not-terminated"></a>
-<p>(F) The lexer saw a left angle bracket in a place where it was expecting
-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".
-</p>
-</dd>
-<dt>gmtime(%f) failed</dt>
-<dd><a name="perldiag-gmtime_0028_0025f_0029-failed"></a>
-<p>(W overflow) You called <code>gmtime</code> with a number that it could not
handle:
-too large, too small, or NaN. The returned value is <code>undef</code>.
-</p>
-</dd>
-<dt>gmtime(%f) too large</dt>
-<dd><a name="perldiag-gmtime_0028_0025f_0029-too-large"></a>
-<p>(W overflow) You called <code>gmtime</code> with a number that was larger
than
-it can reliably handle and <code>gmtime</code> probably returned the wrong
-date. This warning is also triggered with NaN (the special
-not-a-number value).
-</p>
-</dd>
-<dt>gmtime(%f) too small</dt>
-<dd><a name="perldiag-gmtime_0028_0025f_0029-too-small"></a>
-<p>(W overflow) You called <code>gmtime</code> with a number that was smaller
than
-it can reliably handle and <code>gmtime</code> probably returned the wrong
date.
-</p>
-</dd>
-<dt>Got an error from DosAllocMem</dt>
-<dd><a name="perldiag-Got-an-error-from-DosAllocMem"></a>
-<p>(P) An error peculiar to OS/2. Most probably you’re using an obsolete
-version of Perl, and this should not happen anyway.
-</p>
-</dd>
-<dt>goto must have label</dt>
-<dd><a name="perldiag-goto-must-have-label"></a>
-<p>(F) Unlike with "next" or "last", you’re not
allowed to goto an
-unspecified destination. See ‘perlfunc goto’.
-</p>
-</dd>
-<dt>Goto undefined subroutine%s</dt>
-<dd><a name="perldiag-Goto-undefined-subroutine_0025s"></a>
-<p>(F) You tried to call a subroutine with <code>goto &sub</code> syntax,
but
-the indicated subroutine hasn’t been defined, or if it was, it
-has since been undefined.
-</p>
-</dd>
-<dt>Group name must start with a non-digit word character in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Group-name-must-start-with-a-non_002ddigit-word-character-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) Group names must follow the rules for perl identifiers, meaning
-they must start with a non-digit word character. A common cause of
-this error is using (?&0) instead of (?0). See <a
href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>()-group starts with a count</dt>
-<dd><a name="perldiag-_0028_0029_002dgroup-starts-with-a-count"></a>
-<p>(F) A ()-group started with a count. A count is supposed to follow
-something: a template character or a ()-group. See ‘perlfunc
pack’.
-</p>
-</dd>
-<dt>%s had compilation errors.</dt>
-<dd><a name="perldiag-_0025s-had-compilation-errors_002e"></a>
-<p>(F) The final summary message when a <code>perl -c</code> fails.
-</p>
-</dd>
-<dt>Had to create %s unexpectedly</dt>
-<dd><a name="perldiag-Had-to-create-_0025s-unexpectedly"></a>
-<p>(S internal) A routine asked for a symbol from a symbol table that ought
-to have existed already, but for some reason it didn’t, and had to be
-created on an emergency basis to prevent a core dump.
-</p>
-</dd>
-<dt>%s has too many errors</dt>
-<dd><a name="perldiag-_0025s-has-too-many-errors"></a>
-<p>(F) The parser has given up trying to parse the program after 10 errors.
-Further error messages would likely be uninformative.
-</p>
-</dd>
-<dt>Having more than one /%c regexp modifier is deprecated</dt>
-<dd><a
name="perldiag-Having-more-than-one-_002f_0025c-regexp-modifier-is-deprecated"></a>
-<p>(D deprecated, regexp) You used the indicated regular expression pattern
-modifier at least twice in a string of modifiers. It is deprecated to
-do this with this particular modifier, to allow future extensions to the
-Perl language.
-</p>
-</dd>
-<dt>Hexadecimal float: exponent overflow</dt>
-<dd><a name="perldiag-Hexadecimal-float_003a-exponent-overflow"></a>
-<p>(W overflow) The hexadecimal floating point has a larger exponent
-than the floating point supports.
-</p>
-</dd>
-<dt>Hexadecimal float: exponent underflow</dt>
-<dd><a name="perldiag-Hexadecimal-float_003a-exponent-underflow"></a>
-<p>(W overflow) The hexadecimal floating point has a smaller exponent
-than the floating point supports.
-</p>
-</dd>
-<dt>Hexadecimal float: internal error (%s)</dt>
-<dd><a
name="perldiag-Hexadecimal-float_003a-internal-error-_0028_0025s_0029"></a>
-<p>(F) Something went horribly bad in hexadecimal float handling.
-</p>
-</dd>
-<dt>Hexadecimal float: mantissa overflow</dt>
-<dd><a name="perldiag-Hexadecimal-float_003a-mantissa-overflow"></a>
-<p>(W overflow) The hexadecimal floating point literal had more bits in
-the mantissa (the part between the 0x and the exponent, also known as
-the fraction or the significand) than the floating point supports.
-</p>
-</dd>
-<dt>Hexadecimal float: precision loss</dt>
-<dd><a name="perldiag-Hexadecimal-float_003a-precision-loss"></a>
-<p>(W overflow) The hexadecimal floating point had internally more
-digits than could be output. This can be caused by unsupported
-long double formats, or by 64-bit integers not being available
-(needed to retrieve the digits under some configurations).
-</p>
-</dd>
-<dt>Hexadecimal float: unsupported long double format</dt>
-<dd><a
name="perldiag-Hexadecimal-float_003a-unsupported-long-double-format"></a>
-<p>(F) You have configured Perl to use long doubles but
-the internals of the long double format are unknown;
-therefore the hexadecimal float output is impossible.
-</p>
-</dd>
-<dt>Hexadecimal number > 0xffffffff non-portable</dt>
-<dd><a
name="perldiag-Hexadecimal-number-_003e-0xffffffff-non_002dportable"></a>
-<p>(W portable) The hexadecimal number you specified is larger than 2**32-1
-(4294967295) and therefore non-portable between systems. See
-<a href="#perlport-NAME">perlport NAME</a> for more on portability concerns.
-</p>
-</dd>
-<dt>Identifier too long</dt>
-<dd><a name="perldiag-Identifier-too-long"></a>
-<p>(F) Perl limits identifiers (names for variables, functions, etc.) to
-about 250 characters for simple names, and somewhat more for compound
-names (like <code>$A::B</code>). You’ve exceeded Perl’s limits.
Future versions
-of Perl are likely to eliminate these arbitrary limitations.
-</p>
-</dd>
-<dt>Ignoring zero length \N{} in character class in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Ignoring-zero-length-_005cN_007b_007d-in-character-class-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) Named Unicode character escapes (<code>\N{...}</code>) may
return a
-zero-length sequence. When such an escape is used in a character
-class its behavior is not well defined. Check that the correct
-escape has been used, and the correct charname handler is in scope.
-</p>
-</dd>
-<dt>Illegal binary digit %s</dt>
-<dd><a name="perldiag-Illegal-binary-digit-_0025s"></a>
-<p>(F) You used a digit other than 0 or 1 in a binary number.
-</p>
-</dd>
-<dt>Illegal binary digit %s ignored</dt>
-<dd><a name="perldiag-Illegal-binary-digit-_0025s-ignored"></a>
-<p>(W digit) You may have tried to use a digit other than 0 or 1 in a
-binary number. Interpretation of the binary number stopped before the
-offending digit.
-</p>
-</dd>
-<dt>Illegal character after ’_’ in prototype for %s : %s</dt>
-<dd><a
name="perldiag-Illegal-character-after-_0027_005f_0027-in-prototype-for-_0025s-_003a-_0025s"></a>
-<p>(W illegalproto) An illegal character was found in a prototype
-declaration. The ’_’ in a prototype must be followed by a
’;’,
-indicating the rest of the parameters are optional, or one of ’@’
-or ’%’, since those two will accept 0 or more final parameters.
-</p>
-</dd>
-<dt>Illegal character \%o (carriage return)</dt>
-<dd><a
name="perldiag-Illegal-character-_005c_0025o-_0028carriage-return_0029"></a>
-<p>(F) Perl normally treats carriage returns in the program text as it
-would any other whitespace, which means you should never see this error
-when Perl was built using standard options. For some reason, your
-version of Perl appears to have been built without this support. Talk
-to your Perl administrator.
-</p>
-</dd>
-<dt>Illegal character in prototype for %s : %s</dt>
-<dd><a
name="perldiag-Illegal-character-in-prototype-for-_0025s-_003a-_0025s"></a>
-<p>(W illegalproto) An illegal character was found in a prototype declaration.
-Legal characters in prototypes are $, @, %, *, ;, [, ], &, \, and +.
-Perhaps you were trying to write a subroutine signature but didn’t enable
-that feature first (<code>use feature 'signatures'</code>), so your signature
was
-instead interpreted as a bad prototype.
-</p>
-</dd>
-<dt>Illegal declaration of anonymous subroutine</dt>
-<dd><a name="perldiag-Illegal-declaration-of-anonymous-subroutine"></a>
-<p>(F) When using the <code>sub</code> keyword to construct an anonymous
subroutine,
-you must always specify a block of code. See <a href="#perlsub-NAME">perlsub
NAME</a>.
-</p>
-</dd>
-<dt>Illegal declaration of subroutine %s</dt>
-<dd><a name="perldiag-Illegal-declaration-of-subroutine-_0025s"></a>
-<p>(F) A subroutine was not declared correctly. See <a
href="#perlsub-NAME">perlsub NAME</a>.
-</p>
-</dd>
-<dt>Illegal division by zero</dt>
-<dd><a name="perldiag-Illegal-division-by-zero"></a>
-<p>(F) You tried to divide a number by 0. Either something was wrong in
-your logic, or you need to put a conditional in to guard against
-meaningless input.
-</p>
-</dd>
-<dt>Illegal hexadecimal digit %s ignored</dt>
-<dd><a name="perldiag-Illegal-hexadecimal-digit-_0025s-ignored"></a>
-<p>(W digit) You may have tried to use a character other than 0 - 9 or
-A - F, a - f in a hexadecimal number. Interpretation of the hexadecimal
-number stopped before the illegal character.
-</p>
-</dd>
-<dt>Illegal modulus zero</dt>
-<dd><a name="perldiag-Illegal-modulus-zero"></a>
-<p>(F) You tried to divide a number by 0 to get the remainder. Most
-numbers don’t take to this kindly.
-</p>
-</dd>
-<dt>Illegal number of bits in vec</dt>
-<dd><a name="perldiag-Illegal-number-of-bits-in-vec"></a>
-<p>(F) The number of bits in vec() (the third argument) must be a power of
-two from 1 to 32 (or 64, if your platform supports that).
-</p>
-</dd>
-<dt>Illegal octal digit %s</dt>
-<dd><a name="perldiag-Illegal-octal-digit-_0025s"></a>
-<p>(F) You used an 8 or 9 in an octal number.
-</p>
-</dd>
-<dt>Illegal octal digit %s ignored</dt>
-<dd><a name="perldiag-Illegal-octal-digit-_0025s-ignored"></a>
-<p>(W digit) You may have tried to use an 8 or 9 in an octal number.
-Interpretation of the octal number stopped before the 8 or 9.
-</p>
-</dd>
-<dt>Illegal pattern in regex; marked by <– HERE<!-- /@w --> in
m/%s/</dt>
-<dd><a
name="perldiag-Illegal-pattern-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You wrote something like
-</p>
-<pre class="verbatim"> (?+foo)
-</pre>
-<p>The <code>"+"</code> is valid only when followed by digits,
indicating a
-capturing group. See
-<a
href="#perlre-_0028_003fPARNO_0029-_0028_003f_002dPARNO_0029-_0028_003f_002bPARNO_0029-_0028_003fR_0029-_0028_003f0_0029"><code>(?<em>PARNO</em>)</code></a>.
-</p>
-</dd>
-<dt>Illegal suidscript</dt>
-<dd><a name="perldiag-Illegal-suidscript"></a>
-<p>(F) The script run under suidperl was somehow illegal.
-</p>
-</dd>
-<dt>Illegal switch in PERL5OPT: -%c</dt>
-<dd><a name="perldiag-Illegal-switch-in-PERL5OPT_003a-_002d_0025c"></a>
-<p>(X) The PERL5OPT environment variable may only be used to set the
-following switches: <strong>-[CDIMUdmtw]</strong>.
-</p>
-</dd>
-<dt>Ill-formed CRTL environ value "%s"</dt>
-<dd><a name="perldiag-Ill_002dformed-CRTL-environ-value-_0022_0025s_0022"></a>
-<p>(W internal) A warning peculiar to VMS. Perl tried to read the CRTL’s
-internal environ array, and encountered an element without the <code>=</code>
-delimiter used to separate keys from values. The element is ignored.
-</p>
-</dd>
-<dt>Ill-formed message in prime_env_iter: |%s|</dt>
-<dd><a
name="perldiag-Ill_002dformed-message-in-prime_005fenv_005fiter_003a-_007c_0025s_007c"></a>
-<p>(W internal) A warning peculiar to VMS. Perl tried to read a logical
-name or CLI symbol definition when preparing to iterate over %ENV, and
-didn’t see the expected delimiter between key and value, so the line was
-ignored.
-</p>
-</dd>
-<dt>(in cleanup) %s</dt>
-<dd><a name="perldiag-_0028in-cleanup_0029-_0025s"></a>
-<p>(W misc) This prefix usually indicates that a DESTROY() method raised
-the indicated exception. Since destructors are usually called by the
-system at arbitrary points during execution, and often a vast number of
-times, the warning is issued only once for any number of failures that
-would otherwise result in the same message being repeated.
-</p>
-<p>Failure of user callbacks dispatched using the <code>G_KEEPERR</code> flag
could
-also result in this warning. See <a href="#perlcall-G_005fKEEPERR">perlcall
G_KEEPERR</a>.
-</p>
-</dd>
-<dt>Incomplete expression within ’(?[ ])’ in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Incomplete-expression-within-_0027_0028_003f_005b-_005d_0029_0027-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) There was a syntax error within the <code>(?[ ])</code>. This can
happen if the
-expression inside the construct was completely empty, or if there are
-too many or few operands for the number of operators. Perl is not smart
-enough to give you a more precise indication as to what is wrong.
-</p>
-</dd>
-<dt>Inconsistent hierarchy during C3 merge of class ’%s’: merging
failed on parent ’%s’</dt>
-<dd><a
name="perldiag-Inconsistent-hierarchy-during-C3-merge-of-class-_0027_0025s_0027_003a-merging-failed-on-parent-_0027_0025s_0027"></a>
-<p>(F) The method resolution order (MRO) of the given class is not
-C3-consistent, and you have enabled the C3 MRO for this class. See the C3
-documentation in <a href="mro.html#Top">(mro)</a> for more information.
-</p>
-</dd>
-<dt>In EBCDIC the v-string components cannot exceed 2147483647</dt>
-<dd><a
name="perldiag-In-EBCDIC-the-v_002dstring-components-cannot-exceed-2147483647"></a>
-<p>(F) An error peculiar to EBCDIC. Internally, v-strings are stored as
-Unicode code points, and encoded in EBCDIC as UTF-EBCDIC. The UTF-EBCDIC
-encoding is limited to code points no larger than 2147483647 (0x7FFFFFFF).
-</p>
-</dd>
-<dt>Infinite recursion in regex</dt>
-<dd><a name="perldiag-Infinite-recursion-in-regex"></a>
-<p>(F) You used a pattern that references itself without consuming any input
-text. You should check the pattern to ensure that recursive patterns
-either consume text or fail.
-</p>
-</dd>
-<dt>Initialization of state variables in list context currently forbidden</dt>
-<dd><a
name="perldiag-Initialization-of-state-variables-in-list-context-currently-forbidden"></a>
-<p>(F) Currently the implementation of "state" only permits the
-initialization of scalar variables in scalar context. Re-write
-<code>state ($a) = 42</code> as <code>state $a = 42</code> to change from list
to scalar
-context. Constructions such as <code>state (@a) = foo()</code> will be
-supported in a future perl release.
-</p>
-</dd>
-<dt>%%s[%s] in scalar context better written as $%s[%s]</dt>
-<dd><a
name="perldiag-_0025_0025s_005b_0025s_005d-in-scalar-context-better-written-as-_0024_0025s_005b_0025s_005d"></a>
-<p>(W syntax) In scalar context, you’ve used an array index/value slice
-(indicated by %) to select a single element of an array. Generally
-it’s better to ask for a scalar value (indicated by $). The difference
-is that <code>$foo[&bar]</code> always behaves like a scalar, both in the
value it
-returns and when evaluating its argument, while <code>%foo[&bar]</code>
provides
-a list context to its subscript, which can do weird things if you’re
-expecting only one subscript. When called in list context, it also
-returns the index (what <code>&bar</code> returns) in addition to the
value.
-</p>
-</dd>
-<dt>%%s{%s} in scalar context better written as $%s{%s}</dt>
-<dd><a
name="perldiag-_0025_0025s_007b_0025s_007d-in-scalar-context-better-written-as-_0024_0025s_007b_0025s_007d"></a>
-<p>(W syntax) In scalar context, you’ve used a hash key/value slice
-(indicated by %) to select a single element of a hash. Generally it’s
-better to ask for a scalar value (indicated by $). The difference
-is that <code>$foo{&bar}</code> always behaves like a scalar, both in the
value
-it returns and when evaluating its argument, while <code>@foo{&bar}</code>
and
-provides a list context to its subscript, which can do weird things
-if you’re expecting only one subscript. When called in list context,
-it also returns the key in addition to the value.
-</p>
-</dd>
-<dt>Insecure dependency in %s</dt>
-<dd><a name="perldiag-Insecure-dependency-in-_0025s"></a>
-<p>(F) You tried to do something that the tainting mechanism didn’t like.
-The tainting mechanism is turned on when you’re running setuid or
-setgid, or when you specify <strong>-T</strong> to turn it on explicitly. The
-tainting mechanism labels all data that’s derived directly or indirectly
-from the user, who is considered to be unworthy of your trust. If any
-such data is used in a "dangerous" operation, you get this error.
See
-<a href="#perlsec-NAME">perlsec NAME</a> for more information.
-</p>
-</dd>
-<dt>Insecure directory in %s</dt>
-<dd><a name="perldiag-Insecure-directory-in-_0025s"></a>
-<p>(F) You can’t use system(), exec(), or a piped open in a setuid or
-setgid script if <code>$ENV{PATH}</code> contains a directory that is writable
by
-the world. Also, the PATH must not contain any relative directory.
-See <a href="#perlsec-NAME">perlsec NAME</a>.
-</p>
-</dd>
-<dt>Insecure $ENV{%s} while running %s</dt>
-<dd><a
name="perldiag-Insecure-_0024ENV_007b_0025s_007d-while-running-_0025s"></a>
-<p>(F) You can’t use system(), exec(), or a piped open in a setuid or
-setgid script if any of <code>$ENV{PATH}</code>, <code>$ENV{IFS}</code>,
<code>$ENV{CDPATH}</code>,
-<code>$ENV{ENV}</code>, <code>$ENV{BASH_ENV}</code> or <code>$ENV{TERM}</code>
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 <a
href="#perlsec-NAME">perlsec NAME</a>.
-</p>
-</dd>
-<dt>Insecure user-defined property %s</dt>
-<dd><a name="perldiag-Insecure-user_002ddefined-property-_0025s"></a>
-<p>(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. <code>\p{IsFoo}</code> or <code>\p{InFoo}</code>.
-See <a href="#perlunicode-User_002dDefined-Character-Properties">perlunicode
User-Defined Character Properties</a> and <a href="#perlsec-NAME">perlsec
NAME</a>.
-</p>
-</dd>
-<dt>Integer overflow in format string for %s</dt>
-<dd><a name="perldiag-Integer-overflow-in-format-string-for-_0025s"></a>
-<p>(F) The indexes and widths specified in the format string of
<code>printf()</code>
-or <code>sprintf()</code> are too large. The numbers must not overflow the
size of
-integers for your architecture.
-</p>
-</dd>
-<dt>Integer overflow in %s number</dt>
-<dd><a name="perldiag-Integer-overflow-in-_0025s-number"></a>
-<p>(S overflow) The hexadecimal, octal or binary number you have specified
-either as a literal or as an argument to hex() or oct() is too big for
-your architecture, and has been converted to a floating point number.
-On a 32-bit architecture the largest hexadecimal, octal or binary number
-representable without overflow is 0xFFFFFFFF, 037777777777, or
-0b11111111111111111111111111111111 respectively. Note that Perl
-transparently promotes all numbers to a floating point representation
-internally–subject to loss of precision errors in subsequent
-operations.
-</p>
-</dd>
-<dt>Integer overflow in srand</dt>
-<dd><a name="perldiag-Integer-overflow-in-srand"></a>
-<p>(S overflow) The number you have passed to srand is too big to fit
-in your architecture’s integer representation. The number has been
-replaced with the largest integer supported (0xFFFFFFFF on 32-bit
-architectures). This means you may be getting less randomness than
-you expect, because different random seeds above the maximum will
-return the same sequence of random numbers.
-</p>
-</dd>
-<dt>Integer overflow in version</dt>
-<dd><a name="perldiag-Integer-overflow-in-version"></a>
-</dd>
-<dt>Integer overflow in version %d</dt>
-<dd><a name="perldiag-Integer-overflow-in-version-_0025d"></a>
-<p>(W overflow) Some portion of a version initialization is too large for
-the size of integers for your architecture. This is not a warning
-because there is no rational reason for a version to try and use an
-element larger than typically 2**32. This is usually caused by trying
-to use some odd mathematical operation as a version, like 100/9.
-</p>
-</dd>
-<dt>Internal disaster in regex; marked by <– HERE<!-- /@w --> in
m/%s/</dt>
-<dd><a
name="perldiag-Internal-disaster-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(P) Something went badly wrong in the regular expression parser.
-The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the problem was
-discovered.
-</p>
-</dd>
-<dt>Internal inconsistency in tracking vforks</dt>
-<dd><a name="perldiag-Internal-inconsistency-in-tracking-vforks"></a>
-<p>(S) A warning peculiar to VMS. Perl keeps track of the number of times
-you’ve called <code>fork</code> and <code>exec</code>, to determine
whether the current call
-to <code>exec</code> should affect the current script or a subprocess (see
-<a href="#perlvms-exec-LIST">perlvms exec LIST</a>). Somehow, this count has
become scrambled, so
-Perl is making a guess and treating this <code>exec</code> as a request to
-terminate the Perl script and execute the specified command.
-</p>
-</dd>
-<dt>internal %<num>p might conflict with future printf extensions</dt>
-<dd><a
name="perldiag-internal-_0025_003cnum_003ep-might-conflict-with-future-printf-extensions"></a>
-<p>(S internal) Perl’s internal routine that handles <code>printf</code>
and <code>sprintf</code>
-formatting follows a slightly different set of rules when called from
-C or XS code. Specifically, formats consisting of digits followed
-by "p" (e.g., "%7p") are reserved for future use. If you
see this
-message, then an XS module tried to call that routine with one such
-reserved format.
-</p>
-</dd>
-<dt>Internal urp in regex; marked by <– HERE<!-- /@w --> in
m/%s/</dt>
-<dd><a
name="perldiag-Internal-urp-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(P) Something went badly awry in the regular expression parser. The
-<– HERE<!-- /@w --> shows whereabouts in the regular expression
the problem was
-discovered.
-</p>
-</dd>
-<dt>%s (...) interpreted as function</dt>
-<dd><a
name="perldiag-_0025s-_0028_002e_002e_002e_0029-interpreted-as-function"></a>
-<p>(W syntax) You’ve run afoul of the rule that says that any list
operator
-followed by parentheses turns into a function, with all the list
-operators arguments found inside the parentheses. See
-<a href="#perlop-Terms-and-List-Operators-_0028Leftward_0029">perlop Terms and
List Operators (Leftward)</a>.
-</p>
-</dd>
-<dt>In ’(?...)’, the ’(’ and ’?’ must be
adjacent in regex; marked by <– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-In-_0027_0028_003f_002e_002e_002e_0029_0027_002c-the-_0027_0028_0027-and-_0027_003f_0027-must-be-adjacent-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The two-character sequence <code>"(?"</code> in this context
in a regular
-expression pattern should be an indivisible token, with nothing
-intervening between the <code>"("</code> and the
<code>"?"</code>, but you separated them
-with whitespace.
-</p>
-</dd>
-<dt>Invalid %s attribute: %s</dt>
-<dd><a name="perldiag-Invalid-_0025s-attribute_003a-_0025s"></a>
-<p>(F) The indicated attribute for a subroutine or variable was not recognized
-by Perl or by a user-supplied handler. See <a
href="attributes.html#Top">(attributes)</a>.
-</p>
-</dd>
-<dt>Invalid %s attributes: %s</dt>
-<dd><a name="perldiag-Invalid-_0025s-attributes_003a-_0025s"></a>
-<p>(F) The indicated attributes for a subroutine or variable were not
-recognized by Perl or by a user-supplied handler. See <a
href="attributes.html#Top">(attributes)</a>.
-</p>
-</dd>
-<dt>Invalid character in charnames alias definition; marked by
<– HERE<!-- /@w --> in ’%s</dt>
-<dd><a
name="perldiag-Invalid-character-in-charnames-alias-definition_003b-marked-by-_003c_002d_002d-HERE-in-_0027_0025s"></a>
-<p>(F) You tried to create a custom alias for a character name, with
-the <code>:alias</code> option to <code>use charnames</code> and the specified
character in
-the indicated name isn’t valid. See <a
href="charnames.html#CUSTOM-ALIASES">(charnames)CUSTOM ALIASES</a>.
-</p>
-</dd>
-<dt>Invalid \0 character in %s for %s: %s\0%s</dt>
-<dd><a
name="perldiag-Invalid-_005c0-character-in-_0025s-for-_0025s_003a-_0025s_005c0_0025s"></a>
-<p>(W syscalls) Embedded \0 characters in pathnames or other system call
-arguments produce a warning as of 5.20. The parts after the \0 were
-formerly ignored by system calls.
-</p>
-</dd>
-<dt>Invalid character in \N{...}; marked by <– HERE<!-- /@w -->
in \N{%s}</dt>
-<dd><a
name="perldiag-Invalid-character-in-_005cN_007b_002e_002e_002e_007d_003b-marked-by-_003c_002d_002d-HERE-in-_005cN_007b_0025s_007d"></a>
-<p>(F) Only certain characters are valid for character names. The
-indicated one isn’t. See <a
href="charnames.html#CUSTOM-ALIASES">(charnames)CUSTOM ALIASES</a>.
-</p>
-</dd>
-<dt>Invalid conversion in %s: "%s"</dt>
-<dd><a name="perldiag-Invalid-conversion-in-_0025s_003a-_0022_0025s_0022"></a>
-<p>(W printf) Perl does not understand the given format conversion. See
-‘perlfunc sprintf’.
-</p>
-</dd>
-<dt>Invalid escape in the specified encoding in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Invalid-escape-in-the-specified-encoding-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp)(F) The numeric escape (for example <code>\xHH</code>) of value
< 256
-didn’t correspond to a single character through the conversion
-from the encoding specified by the encoding pragma.
-The escape was replaced with REPLACEMENT CHARACTER (U+FFFD)
-instead, except within <code>(?[ ])</code><!-- /@w -->, where
it is a fatal error.
-The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the
-escape was discovered.
-</p>
-</dd>
-<dt>Invalid hexadecimal number in \N{U+...}</dt>
-<dd><a
name="perldiag-Invalid-hexadecimal-number-in-_005cN_007bU_002b_002e_002e_002e_007d"></a>
-</dd>
-<dt>Invalid hexadecimal number in \N{U+...} in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Invalid-hexadecimal-number-in-_005cN_007bU_002b_002e_002e_002e_007d-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The character constant represented by <code>...</code> 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.
-</p>
-</dd>
-<dt>Invalid module name %s with -%c option: contains single
’:’</dt>
-<dd><a
name="perldiag-Invalid-module-name-_0025s-with-_002d_0025c-option_003a-contains-single-_0027_003a_0027"></a>
-<p>(F) The module argument to perl’s <strong>-m</strong> and
<strong>-M</strong> command-line options
-cannot contain single colons in the module name, but only in the
-arguments after "=". In other words,
<strong>-MFoo::Bar=:baz</strong> is ok, but
-<strong>-MFoo:Bar=baz</strong> is not.
-</p>
-</dd>
-<dt>Invalid mro name: ’%s’</dt>
-<dd><a name="perldiag-Invalid-mro-name_003a-_0027_0025s_0027"></a>
-<p>(F) You tried to <code>mro::set_mro("classname",
"foo")</code> or <code>use mro 'foo'</code>,
-where <code>foo</code> is not a valid method resolution order (MRO).
Currently,
-the only valid ones supported are <code>dfs</code> and <code>c3</code>, unless
you have loaded
-a module that is a MRO plugin. See <a href="mro.html#Top">(mro)</a> and <a
href="#perlmroapi-NAME">perlmroapi NAME</a>.
-</p>
-</dd>
-<dt>Invalid negative number (%s) in chr</dt>
-<dd><a name="perldiag-Invalid-negative-number-_0028_0025s_0029-in-chr"></a>
-<p>(W utf8) You passed a negative number to <code>chr</code>. Negative
numbers are
-not valid character numbers, so it returns the Unicode replacement
-character (U+FFFD).
-</p>
-</dd>
-<dt>invalid option -D%c, use -D” to see choices</dt>
-<dd><a
name="perldiag-invalid-option-_002dD_0025c_002c-use-_002dD_0027_0027-to-see-choices"></a>
-<p>(S debugging) Perl was called with invalid debugger flags. Call perl
-with the <strong>-D</strong> option with no flags to see the list of
acceptable values.
-See also <a href="#perlrun-_002dDletters">perlrun
<strong>-D</strong><em>letters</em></a>.
-</p>
-</dd>
-<dt>Invalid quantifier in {,} in regex; marked by <– HERE<!--
/@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Invalid-quantifier-in-_007b_002c_007d-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The pattern looks like a {min,max} quantifier, but the min or max
-could not be parsed as a valid number - either it has leading zeroes,
-or it represents too big a number to cope with. The <– HERE<!--
/@w --> shows
-where in the regular expression the problem was discovered. See <a
href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Invalid [] range "%s" in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Invalid-_005b_005d-range-_0022_0025s_0022-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The range specified in a character class had a minimum character
-greater than the maximum character. One possibility is that you forgot the
-<code>{}</code> from your ending <code>\x{}</code> - <code>\x</code> without
the curly braces can go only
-up to <code>ff</code>. The <– HERE<!-- /@w --> shows
whereabouts in the regular expression the
-problem was discovered. See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Invalid range "%s" in transliteration operator</dt>
-<dd><a
name="perldiag-Invalid-range-_0022_0025s_0022-in-transliteration-operator"></a>
-<p>(F) The range specified in the tr/// or y/// operator had a minimum
-character greater than the maximum character. See <a
href="#perlop-NAME">perlop NAME</a>.
-</p>
-</dd>
-<dt>Invalid separator character %s in attribute list</dt>
-<dd><a
name="perldiag-Invalid-separator-character-_0025s-in-attribute-list"></a>
-<p>(F) Something other than a colon or whitespace was seen between the
-elements of an attribute list. If the previous attribute had a
-parenthesised parameter list, perhaps that list was terminated too soon.
-See <a href="attributes.html#Top">(attributes)</a>.
-</p>
-</dd>
-<dt>Invalid separator character %s in PerlIO layer specification %s</dt>
-<dd><a
name="perldiag-Invalid-separator-character-_0025s-in-PerlIO-layer-specification-_0025s"></a>
-<p>(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.
-</p>
-</dd>
-<dt>Invalid strict version format (%s)</dt>
-<dd><a name="perldiag-Invalid-strict-version-format-_0028_0025s_0029"></a>
-<p>(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 <a href="version.html#Top">(version)</a> module for more details on
allowed version formats.
-</p>
-</dd>
-<dt>Invalid type ’%s’ in %s</dt>
-<dd><a name="perldiag-Invalid-type-_0027_0025s_0027-in-_0025s"></a>
-<p>(F) The given character is not a valid pack or unpack type.
-See ‘perlfunc pack’.
-</p>
-<p>(W) The given character is not a valid pack or unpack type but used to be
-silently ignored.
-</p>
-</dd>
-<dt>Invalid version format (%s)</dt>
-<dd><a name="perldiag-Invalid-version-format-_0028_0025s_0029"></a>
-<p>(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 <a
href="version.html#Top">(version)</a> module
-for more details on allowed version formats.
-</p>
-</dd>
-<dt>Invalid version object</dt>
-<dd><a name="perldiag-Invalid-version-object"></a>
-<p>(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.
-</p>
-</dd>
-<dt>In ’(*VERB...)’, the ’(’ and ’*’ must
be adjacent in regex; marked by <– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-In-_0027_0028_002aVERB_002e_002e_002e_0029_0027_002c-the-_0027_0028_0027-and-_0027_002a_0027-must-be-adjacent-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The two-character sequence <code>"(*"</code> in
-this context in a regular expression pattern should be an
-indivisible token, with nothing intervening between the
<code>"("</code>
-and the <code>"*"</code>, but you separated them.
-</p>
-</dd>
-<dt>ioctl is not implemented</dt>
-<dd><a name="perldiag-ioctl-is-not-implemented"></a>
-<p>(F) Your machine apparently doesn’t implement ioctl(), which is pretty
-strange for a machine that supports C.
-</p>
-</dd>
-<dt>ioctl() on unopened %s</dt>
-<dd><a name="perldiag-ioctl_0028_0029-on-unopened-_0025s"></a>
-<p>(W unopened) You tried ioctl() on a filehandle that was never opened.
-Check your control flow and number of arguments.
-</p>
-</dd>
-<dt>IO layers (like ’%s’) unavailable</dt>
-<dd><a
name="perldiag-IO-layers-_0028like-_0027_0025s_0027_0029-unavailable"></a>
-<p>(F) Your Perl has not been configured to have PerlIO, and therefore
-you cannot use IO layers. To have PerlIO, Perl must be configured
-with ’useperlio’.
-</p>
-</dd>
-<dt>IO::Socket::atmark not implemented on this architecture</dt>
-<dd><a
name="perldiag-IO_003a_003aSocket_003a_003aatmark-not-implemented-on-this-architecture"></a>
-<p>(F) Your machine doesn’t implement the sockatmark() functionality,
-neither as a system call nor an ioctl call (SIOCATMARK).
-</p>
-</dd>
-<dt>’%s’ is an unknown bound type in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-_0027_0025s_0027-is-an-unknown-bound-type-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You used <code>\b{...}</code> or <code>\B{...}</code> and the
<code>...</code> is not known to
-Perl. The current valid ones are given in
-<a
href="#perlrebackslash-_005cb_007b_007d_002c-_005cb_002c-_005cB_007b_007d_002c-_005cB">perlrebackslash
\b{}, \b, \B{}, \B</a>.
-</p>
-</dd>
-<dt>"%s" is more clearly written simply as "%s" in regex;
marked by <– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-_0022_0025s_0022-is-more-clearly-written-simply-as-_0022_0025s_0022-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) (only under <code>use re 'strict'<!-- /@w --></code>
or within <code>(?[...])</code>)
-</p>
-<p>You specified a character that has the given plainer way of writing it,
-and which is also portable to platforms running with different character
-sets.
-</p>
-</dd>
-<dt>$* is no longer supported</dt>
-<dd><a name="perldiag-_0024_002a-is-no-longer-supported"></a>
-<p>(D deprecated, syntax) The special variable <code>$*</code>, deprecated in
older
-perls, has been removed as of 5.10.0 and is no longer supported. In
-previous versions of perl the use of <code>$*</code> enabled or disabled
multi-line
-matching within a string.
-</p>
-<p>Instead of using <code>$*</code> you should use the <code>/m</code> (and
maybe <code>/s</code>) regexp
-modifiers. You can enable <code>/m</code> for a lexical scope (even a whole
file)
-with <code>use re '/m'</code>. (In older versions: when <code>$*</code> was
set to a true value
-then all regular expressions behaved as if they were written using
<code>/m</code>.)
-</p>
-</dd>
-<dt>$# is no longer supported</dt>
-<dd><a name="perldiag-_0024_0023-is-no-longer-supported"></a>
-<p>(D deprecated, syntax) The special variable <code>$#</code>, deprecated in
older
-perls, has been removed as of 5.10.0 and is no longer supported. You
-should use the printf/sprintf functions instead.
-</p>
-</dd>
-<dt>’%s’ is not a code reference</dt>
-<dd><a name="perldiag-_0027_0025s_0027-is-not-a-code-reference"></a>
-<p>(W overload) The second (fourth, sixth, ...) argument of
-overload::constant needs to be a code reference. Either
-an anonymous subroutine, or a reference to a subroutine.
-</p>
-</dd>
-<dt>’%s’ is not an overloadable type</dt>
-<dd><a name="perldiag-_0027_0025s_0027-is-not-an-overloadable-type"></a>
-<p>(W overload) You tried to overload a constant type the overload package is
-unaware of.
-</p>
-</dd>
-<dt>-i used with no filenames on the command line, reading from STDIN</dt>
-<dd><a
name="perldiag-_002di-used-with-no-filenames-on-the-command-line_002c-reading-from-STDIN"></a>
-<p>(S inplace) The <code>-i</code> option was passed on the command line,
indicating
-that the script is intended to edit files in place, but no files were
-given. This is usually a mistake, since editing STDIN in place doesn’t
-make sense, and can be confusing because it can make perl look like
-it is hanging when it is really just trying to read from STDIN. You
-should either pass a filename to edit, or remove <code>-i</code> from the
command
-line. See <a href="#perlrun-NAME">perlrun NAME</a> for more details.
-</p>
-</dd>
-<dt>Junk on end of regexp in regex m/%s/</dt>
-<dd><a name="perldiag-Junk-on-end-of-regexp-in-regex-m_002f_0025s_002f"></a>
-<p>(P) The regular expression parser is confused.
-</p>
-</dd>
-<dt>keys on reference is experimental</dt>
-<dd><a name="perldiag-keys-on-reference-is-experimental"></a>
-<p>(S experimental::autoderef) <code>keys</code> with a scalar argument is
experimental
-and may change or be removed in a future Perl version. If you want to
-take the risk of using this feature, simply disable this warning:
-</p>
-<pre class="verbatim"> no warnings "experimental::autoderef";
-</pre>
-</dd>
-<dt>Label not found for "last %s"</dt>
-<dd><a name="perldiag-Label-not-found-for-_0022last-_0025s_0022"></a>
-<p>(F) You named a loop to break out of, but you’re not currently in a
loop
-of that name, not even if you count where you were called from. See
-<a href="#perlfunc-last">perlfunc last</a>.
-</p>
-</dd>
-<dt>Label not found for "next %s"</dt>
-<dd><a name="perldiag-Label-not-found-for-_0022next-_0025s_0022"></a>
-<p>(F) You named a loop to continue, but you’re not currently in a loop
of
-that name, not even if you count where you were called from. See
-<a href="#perlfunc-last">perlfunc last</a>.
-</p>
-</dd>
-<dt>Label not found for "redo %s"</dt>
-<dd><a name="perldiag-Label-not-found-for-_0022redo-_0025s_0022"></a>
-<p>(F) You named a loop to restart, but you’re not currently in a loop of
-that name, not even if you count where you were called from. See
-<a href="#perlfunc-last">perlfunc last</a>.
-</p>
-</dd>
-<dt>leaving effective %s failed</dt>
-<dd><a name="perldiag-leaving-effective-_0025s-failed"></a>
-<p>(F) While under the <code>use filetest</code> pragma, switching the real and
-effective uids or gids failed.
-</p>
-</dd>
-<dt>length/code after end of string in unpack</dt>
-<dd><a name="perldiag-length_002fcode-after-end-of-string-in-unpack"></a>
-<p>(F) While unpacking, the string buffer was already used up when an unpack
-length/code combination tried to obtain more data. This results in
-an undefined value for the length. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>length() used on %s (did you mean "scalar(%s)"?)</dt>
-<dd><a
name="perldiag-length_0028_0029-used-on-_0025s-_0028did-you-mean-_0022scalar_0028_0025s_0029_0022_003f_0029"></a>
-<p>(W syntax) You used length() on either an array or a hash when you
-probably wanted a count of the items.
-</p>
-<p>Array size can be obtained by doing:
-</p>
-<pre class="verbatim"> scalar(@array);
-</pre>
-<p>The number of items in a hash can be obtained by doing:
-</p>
-<pre class="verbatim"> scalar(keys %hash);
-</pre>
-</dd>
-<dt>Lexing code attempted to stuff non-Latin-1 character into Latin-1
input</dt>
-<dd><a
name="perldiag-Lexing-code-attempted-to-stuff-non_002dLatin_002d1-character-into-Latin_002d1-input"></a>
-<p>(F) An extension is attempting to insert text into the current parse
-(using <a href="perlapi.html#lex_005fstuff_005fpvn">(perlapi)lex_stuff_pvn</a>
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.
-</p>
-</dd>
-<dt>Lexing code internal error (%s)</dt>
-<dd><a name="perldiag-Lexing-code-internal-error-_0028_0025s_0029"></a>
-<p>(F) Lexing code supplied by an extension violated the lexer’s API in a
-detectable way.
-</p>
-</dd>
-<dt>listen() on closed socket %s</dt>
-<dd><a name="perldiag-listen_0028_0029-on-closed-socket-_0025s"></a>
-<p>(W closed) You tried to do a listen on a closed socket. Did you forget
-to check the return value of your socket() call? See
-‘perlfunc listen’.
-</p>
-</dd>
-<dt>List form of piped open not implemented</dt>
-<dd><a name="perldiag-List-form-of-piped-open-not-implemented"></a>
-<p>(F) On some platforms, notably Windows, the three-or-more-arguments
-form of <code>open</code> does not support pipes, such as <code>open($pipe,
'|-', @args)</code>.
-Use the two-argument <code>open($pipe, '|prog arg1 arg2...')</code> form
instead.
-</p>
-</dd>
-<dt>%s: loadable library and perl binaries are mismatched (got handshake key
%p, needed %p)</dt>
-<dd><a
name="perldiag-_0025s_003a-loadable-library-and-perl-binaries-are-mismatched-_0028got-handshake-key-_0025p_002c-needed-_0025p_0029"></a>
-<p>(P) A dynamic loading library <code>.so</code> or <code>.dll</code> was
being loaded into the
-process that was built against a different build of perl than the
-said library was compiled against. Reinstalling the XS module will
-likely fix this error.
-</p>
-</dd>
-<dt>Locale ’%s’ may not work well.%s</dt>
-<dd><a
name="perldiag-Locale-_0027_0025s_0027-may-not-work-well_002e_0025s"></a>
-<p>(W locale) You are using the named locale, which is a non-UTF-8 one, and
-which perl has determined is not fully compatible with what it can
-handle. The second <code>%s</code> gives a reason.
-</p>
-<p>By far the most common reason is that the locale has characters in it
-that are represented by more than one byte. The only such locales that
-Perl can handle are the UTF-8 locales. Most likely the specified locale
-is a non-UTF-8 one for an East Asian language such as Chinese or
-Japanese. If the locale is a superset of ASCII, the ASCII portion of it
-may work in Perl.
-</p>
-<p>Some essentially obsolete locales that aren’t supersets of ASCII,
mainly
-those in ISO 646 or other 7-bit locales, such as ASMO 449, can also have
-problems, depending on what portions of the ASCII character set get
-changed by the locale and are also used by the program.
-The warning message lists the determinable conflicting characters.
-</p>
-<p>Note that not all incompatibilities are found.
-</p>
-<p>If this happens to you, there’s not much you can do except switch to
use a
-different locale or use <a href="Encode.html#Top">(Encode)</a> to translate
from the locale into
-UTF-8; if that’s impracticable, you have been warned that some things
-may break.
-</p>
-<p>This message is output once each time a bad locale is switched into
-within the scope of <code>use locale<!-- /@w --></code>, or on the first
possibly-affected
-operation if the <code>use locale<!-- /@w --></code> inherits a bad one.
It is not raised
-for any operations from the <a href="POSIX.html#Top">(POSIX)</a> module.
-</p>
-</dd>
-<dt>localtime(%f) failed</dt>
-<dd><a name="perldiag-localtime_0028_0025f_0029-failed"></a>
-<p>(W overflow) You called <code>localtime</code> with a number that it could
not handle:
-too large, too small, or NaN. The returned value is <code>undef</code>.
-</p>
-</dd>
-<dt>localtime(%f) too large</dt>
-<dd><a name="perldiag-localtime_0028_0025f_0029-too-large"></a>
-<p>(W overflow) You called <code>localtime</code> with a number that was larger
-than it can reliably handle and <code>localtime</code> probably returned the
-wrong date. This warning is also triggered with NaN (the special
-not-a-number value).
-</p>
-</dd>
-<dt>localtime(%f) too small</dt>
-<dd><a name="perldiag-localtime_0028_0025f_0029-too-small"></a>
-<p>(W overflow) You called <code>localtime</code> with a number that was
smaller
-than it can reliably handle and <code>localtime</code> probably returned the
-wrong date.
-</p>
-</dd>
-<dt>Lookbehind longer than %d not implemented in regex m/%s/</dt>
-<dd><a
name="perldiag-Lookbehind-longer-than-_0025d-not-implemented-in-regex-m_002f_0025s_002f"></a>
-<p>(F) There is currently a limit on the length of string which lookbehind can
-handle. This restriction may be eased in a future release.
-</p>
-</dd>
-<dt>Lost precision when %s %f by 1</dt>
-<dd><a name="perldiag-Lost-precision-when-_0025s-_0025f-by-1"></a>
-<p>(W imprecision) The value you attempted to increment or decrement by one
-is too large for the underlying floating point representation to store
-accurately, hence the target of <code>++</code> or <code>--</code> is
unchanged. Perl issues this
-warning because it has already switched from integers to floating point
-when values are too large for integers, and now even floating point is
-insufficient. You may wish to switch to using <a
href="Math-BigInt.html#Top">(Math-BigInt)</a> explicitly.
-</p>
-</dd>
-<dt>lstat() on filehandle%s</dt>
-<dd><a name="perldiag-lstat_0028_0029-on-filehandle_0025s"></a>
-<p>(W io) You tried to do an lstat on a filehandle. What did you mean
-by that? lstat() makes sense only on filenames. (Perl did a fstat()
-instead on the filehandle.)
-</p>
-</dd>
-<dt>lvalue attribute %s already-defined subroutine</dt>
-<dd><a
name="perldiag-lvalue-attribute-_0025s-already_002ddefined-subroutine"></a>
-<p>(W misc) Although <a
href="attributes.html#Top">(attributes)attributes.pm</a> allows this, turning
the lvalue
-attribute on or off on a Perl subroutine that is already defined
-does not always work properly. It may or may not do what you
-want, depending on what code is inside the subroutine, with exact
-details subject to change between Perl versions. Only do this
-if you really know what you are doing.
-</p>
-</dd>
-<dt>lvalue attribute ignored after the subroutine has been defined</dt>
-<dd><a
name="perldiag-lvalue-attribute-ignored-after-the-subroutine-has-been-defined"></a>
-<p>(W misc) Using the <code>:lvalue</code> declarative syntax to make a Perl
-subroutine an lvalue subroutine after it has been defined is
-not permitted. To make the subroutine an lvalue subroutine,
-add the lvalue attribute to the definition, or put the <code>sub
-foo :lvalue;</code> declaration before the definition.
-</p>
-<p>See also <a href="attributes.html#Top">(attributes)attributes.pm</a>.
-</p>
-</dd>
-<dt>Magical list constants are not supported</dt>
-<dd><a name="perldiag-Magical-list-constants-are-not-supported"></a>
-<p>(F) You assigned a magical array to a stash element, and then tried
-to use the subroutine from the same slot. You are asking Perl to do
-something it cannot do, details subject to change between Perl versions.
-</p>
-</dd>
-<dt>Malformed integer in [] in pack</dt>
-<dd><a name="perldiag-Malformed-integer-in-_005b_005d-in-pack"></a>
-<p>(F) Between the brackets enclosing a numeric repeat count only digits
-are permitted. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>Malformed integer in [] in unpack</dt>
-<dd><a name="perldiag-Malformed-integer-in-_005b_005d-in-unpack"></a>
-<p>(F) Between the brackets enclosing a numeric repeat count only digits
-are permitted. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>Malformed PERLLIB_PREFIX</dt>
-<dd><a name="perldiag-Malformed-PERLLIB_005fPREFIX"></a>
-<p>(F) An error peculiar to OS/2. PERLLIB_PREFIX should be of the form
-</p>
-<pre class="verbatim"> prefix1;prefix2
-</pre>
-<p>or
- prefix1 prefix2
-</p>
-<p>with nonempty prefix1 and prefix2. If <code>prefix1</code> is indeed a
prefix of
-a builtin library search path, prefix2 is substituted. The error may
-appear if components are not found, or are too long. See
-"PERLLIB_PREFIX" in <a href="perlos2.html#Top">(perlos2)</a>.
-</p>
-</dd>
-<dt>Malformed prototype for %s: %s</dt>
-<dd><a name="perldiag-Malformed-prototype-for-_0025s_003a-_0025s"></a>
-<p>(F) You tried to use a function with a malformed prototype. The
-syntax of function prototypes is given a brief compile-time check for
-obvious errors like invalid characters. A more rigorous check is run
-when the function is called.
-Perhaps the function’s author was trying to write a subroutine signature
-but didn’t enable that feature first (<code>use feature
'signatures'</code>),
-so the signature was instead interpreted as a bad prototype.
-</p>
-</dd>
-<dt>Malformed UTF-8 character (%s)</dt>
-<dd><a name="perldiag-Malformed-UTF_002d8-character-_0028_0025s_0029"></a>
-<p>(S utf8)(F) Perl detected a string that didn’t comply with UTF-8
-encoding rules, even though it had the UTF8 flag on.
-</p>
-<p>One possible cause is that you set the UTF8 flag yourself for data that
-you thought to be in UTF-8 but it wasn’t (it was for example legacy
-8-bit data). To guard against this, you can use Encode::decode_utf8.
-</p>
-<p>If you use the <code>:encoding(UTF-8)</code> PerlIO layer for input,
invalid byte
-sequences are handled gracefully, but if you use <code>:utf8</code>, the flag
is
-set without validating the data, possibly resulting in this error
-message.
-</p>
-<p>See also <a href="Encode.html#Handling-Malformed-Data">(Encode)Handling
Malformed Data</a>.
-</p>
-</dd>
-<dt>Malformed UTF-8 character immediately after ’%s’</dt>
-<dd><a
name="perldiag-Malformed-UTF_002d8-character-immediately-after-_0027_0025s_0027"></a>
-<p>(F) You said <code>use utf8</code>, but the program file doesn’t
comply with UTF-8
-encoding rules. The message prints out the properly encoded characters
-just before the first bad one. If <code>utf8</code> warnings are enabled, a
-warning is generated that gives more details about the type of
-malformation.
-</p>
-</dd>
-<dt>Malformed UTF-8 returned by \N{%s} immediately after ’%s’</dt>
-<dd><a
name="perldiag-Malformed-UTF_002d8-returned-by-_005cN_007b_0025s_007d-immediately-after-_0027_0025s_0027"></a>
-<p>(F) The charnames handler returned malformed UTF-8.
-</p>
-</dd>
-<dt>Malformed UTF-8 string in ’%c’ format in unpack</dt>
-<dd><a
name="perldiag-Malformed-UTF_002d8-string-in-_0027_0025c_0027-format-in-unpack"></a>
-<p>(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.
-</p>
-</dd>
-<dt>Malformed UTF-8 string in pack</dt>
-<dd><a name="perldiag-Malformed-UTF_002d8-string-in-pack"></a>
-<p>(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.
-</p>
-</dd>
-<dt>Malformed UTF-8 string in unpack</dt>
-<dd><a name="perldiag-Malformed-UTF_002d8-string-in-unpack"></a>
-<p>(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.
-</p>
-</dd>
-<dt>Malformed UTF-16 surrogate</dt>
-<dd><a name="perldiag-Malformed-UTF_002d16-surrogate"></a>
-<p>(F) Perl thought it was reading UTF-16 encoded character data but while
-doing it Perl met a malformed Unicode surrogate.
-</p>
-</dd>
-<dt>Mandatory parameter follows optional parameter</dt>
-<dd><a name="perldiag-Mandatory-parameter-follows-optional-parameter"></a>
-<p>(F) In a subroutine signature, you wrote something like "$a = undef,
-$b", making an earlier parameter optional and a later one mandatory.
-Parameters are filled from left to right, so it’s impossible for the
-caller to omit an earlier one and pass a later one. If you want to act
-as if the parameters are filled from right to left, declare the rightmost
-optional and then shuffle the parameters around in the subroutine’s body.
-</p>
-</dd>
-<dt>Matched non-Unicode code point 0x%X against Unicode property; may not be
portable</dt>
-<dd><a
name="perldiag-Matched-non_002dUnicode-code-point-0x_0025X-against-Unicode-property_003b-may-not-be-portable"></a>
-<p>(S non_unicode) Perl allows strings to contain a superset of
-Unicode code points; each code point may be as large as what is storable
-in an unsigned integer on your system, but these may not be accepted by
-other languages/systems. This message occurs when you matched a string
-containing such a code point against a regular expression pattern, and
-the code point was matched against a Unicode property, <code>\p{...}</code> or
-<code>\P{...}</code>. Unicode properties are only defined on Unicode code
points,
-so the result of this match is undefined by Unicode, but Perl (starting
-in v5.20) treats non-Unicode code points as if they were typical
-unassigned Unicode ones, and matched this one accordingly. Whether a
-given property matches these code points or not is specified in
-<a
href="perluniprops.html#Properties-accessible-through-_005cp_007b_007d-and-_005cP_007b_007d">(perluniprops)Properties
accessible through \p{} and \P{}</a>.
-</p>
-<p>This message is suppressed (unless it has been made fatal) if it is
-immaterial to the results of the match if the code point is Unicode or
-not. For example, the property <code>\p{ASCII_Hex_Digit}</code> only can match
-the 22 characters <code>[0-9A-Fa-f]</code>, so obviously all other code points,
-Unicode or not, won’t match it. (And <code>\P{ASCII_Hex_Digit}</code>
will match
-every code point except these 22.)
-</p>
-<p>Getting this message indicates that the outcome of the match arguably
-should have been the opposite of what actually happened. If you think
-that is the case, you may wish to make the <code>non_unicode</code> warnings
-category fatal; if you agree with Perl’s decision, you may wish to turn
-off this category.
-</p>
-<p>See <a href="#perlunicode-Beyond-Unicode-code-points">perlunicode Beyond
Unicode code points</a> for more information.
-</p>
-</dd>
-<dt>%s matches null string many times in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-_0025s-matches-null-string-many-times-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) The pattern you’ve specified would be an infinite loop if
the
-regular expression engine didn’t specifically check for that. The
<– HERE<!-- /@w -->
-shows whereabouts in the regular expression the problem was discovered.
-See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Maximal count of pending signals (%u) exceeded</dt>
-<dd><a
name="perldiag-Maximal-count-of-pending-signals-_0028_0025u_0029-exceeded"></a>
-<p>(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 <a
href="#perlipc-Deferred-Signals-_0028Safe-Signals_0029">perlipc Deferred
Signals (Safe Signals)</a>.)
-</p>
-</dd>
-<dt>"%s" may clash with future reserved word</dt>
-<dd><a
name="perldiag-_0022_0025s_0022-may-clash-with-future-reserved-word"></a>
-<p>(W) This warning may be due to running a perl5 script through a perl4
-interpreter, especially if the word that is being warned about is
-"use" or "my".
-</p>
-</dd>
-<dt>’%’ may not be used in pack</dt>
-<dd><a name="perldiag-_0027_0025_0027-may-not-be-used-in-pack"></a>
-<p>(F) You can’t pack a string by supplying a checksum, because the
-checksumming process loses information, and you can’t go the other way.
-See ‘perlfunc unpack’.
-</p>
-</dd>
-<dt>Method for operation %s not found in package %s during blessing</dt>
-<dd><a
name="perldiag-Method-for-operation-_0025s-not-found-in-package-_0025s-during-blessing"></a>
-<p>(F) An attempt was made to specify an entry in an overloading table that
-doesn’t resolve to a valid subroutine. See <a
href="overload.html#Top">(overload)</a>.
-</p>
-</dd>
-<dt>Method %s not permitted</dt>
-<dd><a name="perldiag-Method-_0025s-not-permitted"></a>
-<p>See Server error.
-</p>
-</dd>
-<dt>Might be a runaway multi-line %s string starting on line %d</dt>
-<dd><a
name="perldiag-Might-be-a-runaway-multi_002dline-_0025s-string-starting-on-line-_0025d"></a>
-<p>(S) An advisory indicating that the previous error may have been caused
-by a missing delimiter on a string or pattern, because it eventually
-ended earlier on the current line.
-</p>
-</dd>
-<dt>Misplaced _ in number</dt>
-<dd><a name="perldiag-Misplaced-_005f-in-number"></a>
-<p>(W syntax) An underscore (underbar) in a numeric constant did not
-separate two digits.
-</p>
-</dd>
-<dt>Missing argument in %s</dt>
-<dd><a name="perldiag-Missing-argument-in-_0025s"></a>
-<p>(W missing) You called a function with fewer arguments than other
-arguments you supplied indicated would be needed.
-</p>
-<p>Currently only emitted when a printf-type format required more
-arguments than were supplied, but might be used in the future for
-other cases where we can statically determine that arguments to
-functions are missing, e.g. for the ‘perlfunc pack’ function.
-</p>
-</dd>
-<dt>Missing argument to -%c</dt>
-<dd><a name="perldiag-Missing-argument-to-_002d_0025c"></a>
-<p>(F) The argument to the indicated command line switch must follow
-immediately after the switch, without intervening spaces.
-</p>
-</dd>
-<dt>Missing braces on \N{}</dt>
-<dd><a name="perldiag-Missing-braces-on-_005cN_007b_007d"></a>
-</dd>
-<dt>Missing braces on \N{} in regex; marked by <– HERE<!-- /@w
--> in m/%s/</dt>
-<dd><a
name="perldiag-Missing-braces-on-_005cN_007b_007d-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) Wrong syntax of character name literal <code>\N{charname}</code> within
-double-quotish context. This can also happen when there is a space
-(or comment) between the <code>\N</code> and the <code>{</code> in a regex
with the <code>/x</code> modifier.
-This modifier does not change the requirement that the brace immediately
-follow the <code>\N</code>.
-</p>
-</dd>
-<dt>Missing braces on \o{}</dt>
-<dd><a name="perldiag-Missing-braces-on-_005co_007b_007d"></a>
-<p>(F) A <code>\o</code> must be followed immediately by a <code>{</code> in
double-quotish context.
-</p>
-</dd>
-<dt>Missing comma after first argument to %s function</dt>
-<dd><a
name="perldiag-Missing-comma-after-first-argument-to-_0025s-function"></a>
-<p>(F) While certain functions allow you to specify a filehandle or an
-"indirect object" before the argument list, this ain’t one of
them.
-</p>
-</dd>
-<dt>Missing command in piped open</dt>
-<dd><a name="perldiag-Missing-command-in-piped-open"></a>
-<p>(W pipe) You used the <code>open(FH, "| command")</code> or
-<code>open(FH, "command |")</code> construction, but the command was
missing or
-blank.
-</p>
-</dd>
-<dt>Missing control char name in \c</dt>
-<dd><a name="perldiag-Missing-control-char-name-in-_005cc"></a>
-<p>(F) A double-quoted string ended with "\c", without the required
control
-character name.
-</p>
-</dd>
-<dt>Missing ’]’ in prototype for %s : %s</dt>
-<dd><a
name="perldiag-Missing-_0027_005d_0027-in-prototype-for-_0025s-_003a-_0025s"></a>
-<p>(W illegalproto) A grouping was started with <code>[</code> but never
closed with <code>]</code>.
-</p>
-</dd>
-<dt>Missing name in "%s sub"</dt>
-<dd><a name="perldiag-Missing-name-in-_0022_0025s-sub_0022"></a>
-<p>(F) The syntax for lexically scoped subroutines requires that
-they have a name with which they can be found.
-</p>
-</dd>
-<dt>Missing $ on loop variable</dt>
-<dd><a name="perldiag-Missing-_0024-on-loop-variable"></a>
-<p>(F) Apparently you’ve been programming in <strong>csh</strong> too
much. Variables
-are always mentioned with the $ in Perl, unlike in the shells, where it
-can vary from one line to the next.
-</p>
-</dd>
-<dt>(Missing operator before %s?)</dt>
-<dd><a name="perldiag-_0028Missing-operator-before-_0025s_003f_0029"></a>
-<p>(S syntax) This is an educated guess made in conjunction with the message
-"%s found where operator expected". Often the missing operator is a
comma.
-</p>
-</dd>
-<dt>Missing or undefined argument to require</dt>
-<dd><a name="perldiag-Missing-or-undefined-argument-to-require"></a>
-<p>(F) You tried to call require with no argument or with an undefined
-value as an argument. Require expects either a package name or a
-file-specification as an argument. See <a href="#perlfunc-require">perlfunc
require</a>.
-</p>
-</dd>
-<dt>Missing right brace on \%c{} in regex; marked by <– HERE<!--
/@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Missing-right-brace-on-_005c_0025c_007b_007d-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) Missing right brace in <code>\x{...}</code>, <code>\p{...}</code>,
<code>\P{...}</code>, or <code>\N{...}</code>.
-</p>
-</dd>
-<dt>Missing right brace on \N{}</dt>
-<dd><a name="perldiag-Missing-right-brace-on-_005cN_007b_007d"></a>
-</dd>
-<dt>Missing right brace on \N{} or unescaped left brace after \N</dt>
-<dd><a
name="perldiag-Missing-right-brace-on-_005cN_007b_007d-or-unescaped-left-brace-after-_005cN"></a>
-<p>(F) <code>\N</code> has two meanings.
-</p>
-<p>The traditional one has it followed by a name enclosed in braces,
-meaning the character (or sequence of characters) given by that
-name. Thus <code>\N{ASTERISK}</code> is another way of writing
<code>*</code>, valid in both
-double-quoted strings and regular expression patterns. In patterns,
-it doesn’t have the meaning an unescaped <code>*</code> does.
-</p>
-<p>Starting in Perl 5.12.0, <code>\N</code> also can have an additional
meaning (only)
-in patterns, namely to match a non-newline character. (This is short
-for <code>[^\n]</code>, and like <code>.</code> but is not affected by the
<code>/s</code> regex modifier.)
-</p>
-<p>This can lead to some ambiguities. When <code>\N</code> is not followed
immediately
-by a left brace, Perl assumes the <code>[^\n]</code> meaning. Also, if the
braces
-form a valid quantifier such as <code>\N{3}</code> or <code>\N{5,}</code>,
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
-<code>\N{</code> and a matching <code>}</code>, Perl assumes that a character
name is desired.
-</p>
-<p>However, if there is no matching <code>}</code>, Perl doesn’t know if
it was
-mistakenly omitted, or if <code>[^\n]{</code> 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: <code>\N\{</code>
-</p>
-</dd>
-<dt>Missing right curly or square bracket</dt>
-<dd><a name="perldiag-Missing-right-curly-or-square-bracket"></a>
-<p>(F) The lexer counted more opening curly or square brackets than closing
-ones. As a general rule, you’ll find it’s missing near the place
you
-were last editing.
-</p>
-</dd>
-<dt>(Missing semicolon on previous line?)</dt>
-<dd><a name="perldiag-_0028Missing-semicolon-on-previous-line_003f_0029"></a>
-<p>(S syntax) This is an educated guess made in conjunction with the message
-"%s found where operator expected". Don’t automatically put a
semicolon on
-the previous line just because you saw this message.
-</p>
-</dd>
-<dt>Modification of a read-only value attempted</dt>
-<dd><a name="perldiag-Modification-of-a-read_002donly-value-attempted"></a>
-<p>(F) You tried, directly or indirectly, to change the value of a
-constant. You didn’t, of course, try "2 = 1", because the
compiler
-catches that. But an easy way to do the same thing is:
-</p>
-<pre class="verbatim"> sub mod { $_[0] = 1 }
- mod(2);
-</pre>
-<p>Another way is to assign to a substr() that’s off the end of the
string.
-</p>
-<p>Yet another way is to assign to a <code>foreach</code> loop <em>VAR</em>
when <em>VAR</em>
-is aliased to a constant in the look <em>LIST</em>:
-</p>
-<pre class="verbatim"> $x = 1;
- foreach my $n ($x, 2) {
- $n *= 2; # modifies the $x, but fails on attempt to
- } # modify the 2
-</pre>
-</dd>
-<dt>Modification of non-creatable array value attempted, %s</dt>
-<dd><a
name="perldiag-Modification-of-non_002dcreatable-array-value-attempted_002c-_0025s"></a>
-<p>(F) You tried to make an array value spring into existence, and the
-subscript was probably negative, even counting from end of the array
-backwards.
-</p>
-</dd>
-<dt>Modification of non-creatable hash value attempted, %s</dt>
-<dd><a
name="perldiag-Modification-of-non_002dcreatable-hash-value-attempted_002c-_0025s"></a>
-<p>(P) You tried to make a hash value spring into existence, and it
-couldn’t be created for some peculiar reason.
-</p>
-</dd>
-<dt>Module name must be constant</dt>
-<dd><a name="perldiag-Module-name-must-be-constant"></a>
-<p>(F) Only a bare module name is allowed as the first argument to a
"use".
-</p>
-</dd>
-<dt>Module name required with -%c option</dt>
-<dd><a name="perldiag-Module-name-required-with-_002d_0025c-option"></a>
-<p>(F) The <code>-M</code> or <code>-m</code> options say that Perl should
load some module, but
-you omitted the name of the module. Consult <a href="#perlrun-NAME">perlrun
NAME</a> for full details
-about <code>-M</code> and <code>-m</code>.
-</p>
-</dd>
-<dt>More than one argument to ’%s’ open</dt>
-<dd><a name="perldiag-More-than-one-argument-to-_0027_0025s_0027-open"></a>
-<p>(F) The <code>open</code> function has been asked to open multiple files.
This
-can happen if you are trying to open a pipe to a command that takes a
-list of arguments, but have forgotten to specify a piped open mode.
-See ‘perlfunc open’ for details.
-</p>
-</dd>
-<dt>mprotect for COW string %p %u failed with %d</dt>
-<dd><a
name="perldiag-mprotect-for-COW-string-_0025p-_0025u-failed-with-_0025d"></a>
-<p>(S) You compiled perl with <strong>-D</strong>PERL_DEBUG_READONLY_COW (see
-<a href="#perlguts-Copy-on-Write">perlguts Copy on Write</a>), but a shared
string buffer
-could not be made read-only.
-</p>
-</dd>
-<dt>mprotect for %p %u failed with %d</dt>
-<dd><a name="perldiag-mprotect-for-_0025p-_0025u-failed-with-_0025d"></a>
-<p>(S) You compiled perl with <strong>-D</strong>PERL_DEBUG_READONLY_OPS (see
<a href="#perlhacktips-NAME">perlhacktips NAME</a>),
-but an op tree could not be made read-only.
-</p>
-</dd>
-<dt>mprotect RW for COW string %p %u failed with %d</dt>
-<dd><a
name="perldiag-mprotect-RW-for-COW-string-_0025p-_0025u-failed-with-_0025d"></a>
-<p>(S) You compiled perl with <strong>-D</strong>PERL_DEBUG_READONLY_COW (see
-<a href="#perlguts-Copy-on-Write">perlguts Copy on Write</a>), but a read-only
shared string
-buffer could not be made mutable.
-</p>
-</dd>
-<dt>mprotect RW for %p %u failed with %d</dt>
-<dd><a name="perldiag-mprotect-RW-for-_0025p-_0025u-failed-with-_0025d"></a>
-<p>(S) You compiled perl with <strong>-D</strong>PERL_DEBUG_READONLY_OPS (see
-<a href="#perlhacktips-NAME">perlhacktips NAME</a>), but a read-only op tree
could not be made
-mutable before freeing the ops.
-</p>
-</dd>
-<dt>msg%s not implemented</dt>
-<dd><a name="perldiag-msg_0025s-not-implemented"></a>
-<p>(F) You don’t have System V message IPC on your system.
-</p>
-</dd>
-<dt>Multidimensional syntax %s not supported</dt>
-<dd><a name="perldiag-Multidimensional-syntax-_0025s-not-supported"></a>
-<p>(W syntax) Multidimensional arrays aren’t written like
<code>$foo[1,2,3]</code>.
-They’re written like <code>$foo[1][2][3]</code>, as in C.
-</p>
-</dd>
-<dt>’/’ must follow a numeric type in unpack</dt>
-<dd><a
name="perldiag-_0027_002f_0027-must-follow-a-numeric-type-in-unpack"></a>
-<p>(F) You had an unpack template that contained a ’/’, but this
did not
-follow some unpack specification producing a numeric value.
-See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>"my sub" not yet implemented</dt>
-<dd><a name="perldiag-_0022my-sub_0022-not-yet-implemented"></a>
-<p>(F) Lexically scoped subroutines are not yet implemented. Don’t try
-that yet.
-</p>
-</dd>
-<dt>"my" subroutine %s can’t be in a package</dt>
-<dd><a
name="perldiag-_0022my_0022-subroutine-_0025s-can_0027t-be-in-a-package"></a>
-<p>(F) Lexically scoped subroutines aren’t in a package, so it
doesn’t make
-sense to try to declare one with a package qualifier on the front.
-</p>
-</dd>
-<dt>"my %s" used in sort comparison</dt>
-<dd><a name="perldiag-_0022my-_0025s_0022-used-in-sort-comparison"></a>
-<p>(W syntax) The package variables $a and $b are used for sort comparisons.
-You used $a or $b in as an operand to the <code><=></code> or
<code>cmp</code> operator inside a
-sort comparison block, and the variable had earlier been declared as a
-lexical variable. Either qualify the sort variable with the package
-name, or rename the lexical variable.
-</p>
-</dd>
-<dt>"my" variable %s can’t be in a package</dt>
-<dd><a
name="perldiag-_0022my_0022-variable-_0025s-can_0027t-be-in-a-package"></a>
-<p>(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.
-</p>
-</dd>
-<dt>Name "%s::%s" used only once: possible typo</dt>
-<dd><a
name="perldiag-Name-_0022_0025s_003a_003a_0025s_0022-used-only-once_003a-possible-typo"></a>
-<p>(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 <code>our</code>
-declaration is also provided for this purpose.
-</p>
-<p>NOTE: This warning detects package symbols that have been used
-only once. This means lexical variables will never trigger this
-warning. It also means that all of the package variables $c, @c,
-%c, as well as *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.
-Symbols beginning with an underscore and symbols using special
-identifiers (q.v. <a href="#perldata-NAME">perldata NAME</a>) are exempt from
this warning.
-</p>
-</dd>
-<dt>Need exactly 3 octal digits in regex; marked by <– HERE<!--
/@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Need-exactly-3-octal-digits-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) Within <code>(?[ ])</code><!-- /@w -->, all constants
interpreted as octal need to be
-exactly 3 digits long. This helps catch some ambiguities. If your
-constant is too short, add leading zeros, like
-</p>
-<pre class="verbatim"> (?[ [ \078 ] ]) # Syntax error!
- (?[ [ \0078 ] ]) # Works
- (?[ [ \007 8 ] ]) # Clearer
-</pre>
-<p>The maximum number this construct can express is <code>\777</code>. If you
-need a larger one, you need to use <a
href="#perlrebackslash-Octal-escapes">\o{}</a> instead. If you meant
-two separate things, you need to separate them:
-</p>
-<pre class="verbatim"> (?[ [ \7776 ] ]) # Syntax error!
- (?[ [ \o{7776} ] ]) # One meaning
- (?[ [ \777 6 ] ]) # Another meaning
- (?[ [ \777 \006 ] ]) # Still another
-</pre>
-</dd>
-<dt>Negative ’/’ count in unpack</dt>
-<dd><a name="perldiag-Negative-_0027_002f_0027-count-in-unpack"></a>
-<p>(F) The length count obtained from a length/code unpack operation was
-negative. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>Negative length</dt>
-<dd><a name="perldiag-Negative-length"></a>
-<p>(F) You tried to do a read/write/send/recv operation with a buffer
-length that is less than 0. This is difficult to imagine.
-</p>
-</dd>
-<dt>Negative offset to vec in lvalue context</dt>
-<dd><a name="perldiag-Negative-offset-to-vec-in-lvalue-context"></a>
-<p>(F) When <code>vec</code> is called in an lvalue context, the second
argument must be
-greater than or equal to zero.
-</p>
-</dd>
-<dt>Negative repeat count does nothing</dt>
-<dd><a name="perldiag-Negative-repeat-count-does-nothing"></a>
-<p>(W numeric) You tried to execute the
-<a href="#perlop-Multiplicative-Operators"><code>x</code></a> repetition
operator fewer than 0
-times, which doesn’t make sense.
-</p>
-</dd>
-<dt>Nested quantifiers in regex; marked by <– HERE<!-- /@w -->
in m/%s/</dt>
-<dd><a
name="perldiag-Nested-quantifiers-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You can’t quantify a quantifier without intervening parentheses.
-So things like ** or +* or ?* are illegal. The <– HERE<!-- /@w
--> shows
-whereabouts in the regular expression the problem was discovered.
-</p>
-<p>Note that the minimal matching quantifiers, <code>*?</code>,
<code>+?</code>, and
-<code>??</code> appear to be nested quantifiers, but aren’t. See <a
href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>%s never introduced</dt>
-<dd><a name="perldiag-_0025s-never-introduced"></a>
-<p>(S internal) The symbol in question was declared but somehow went out of
-scope before it could possibly have been used.
-</p>
-</dd>
-<dt>next::method/next::can/maybe::next::method cannot find enclosing
method</dt>
-<dd><a
name="perldiag-next_003a_003amethod_002fnext_003a_003acan_002fmaybe_003a_003anext_003a_003amethod-cannot-find-enclosing-method"></a>
-<p>(F) <code>next::method</code> needs to be called within the context of a
-real method in a real package, and it could not find such a context.
-See <a href="mro.html#Top">(mro)</a>.
-</p>
-</dd>
-<dt>\N in a character class must be a named character: \N{...} in regex;
marked by <– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-_005cN-in-a-character-class-must-be-a-named-character_003a-_005cN_007b_002e_002e_002e_007d-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The new (as of Perl 5.12) meaning of <code>\N</code> as
<code>[^\n]</code> is not valid in a
-bracketed character class, for the same reason that <code>.</code> in a
character
-class loses its specialness: it matches almost everything, which is
-probably not what you want.
-</p>
-</dd>
-<dt>\N{} in inverted character class or as a range end-point is restricted to
one character in regex; marked by <– HERE in m/%s/</dt>
-<dd><a
name="perldiag-_005cN_007b_007d-in-inverted-character-class-or-as-a-range-end_002dpoint-is-restricted-to-one-character-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) Named Unicode character escapes (<code>\N{...}</code>) may return a
-multi-character sequence. Even though a character class is
-supposed to match just one character of input, perl will match the
-whole thing correctly, except when the class is inverted (<code>[^...]</code>),
-or the escape is the beginning or final end point of a range. The
-mathematically logical behavior for what matches when inverting
-is very different from what people expect, so we have decided to
-forbid it. Similarly unclear is what should be generated when the
-<code>\N{...}</code> is used as one of the end points of the range, such as in
-</p>
-<pre class="verbatim"> [\x{41}-\N{ARABIC SEQUENCE YEH WITH HAMZA ABOVE WITH
AE}]
-</pre>
-<p>What is meant here is unclear, as the <code>\N{...}</code> escape is a
sequence
-of code points, so this is made an error.
-</p>
-</dd>
-<dt>\N{NAME} must be resolved by the lexer in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-_005cN_007bNAME_007d-must-be-resolved-by-the-lexer-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(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:
-</p>
-<pre class="verbatim"> $re = '\N{SPACE}'; # Wrong!
- $re = "\\N{SPACE}"; # Wrong!
- /$re/;
-</pre>
-<p>Instead, use double-quotes with a single backslash:
-</p>
-<pre class="verbatim"> $re = "\N{SPACE}"; # ok
- /$re/;
-</pre>
-<p>The lexer can be bypassed as well by creating the pattern from smaller
-components:
-</p>
-<pre class="verbatim"> $re = '\N';
- /${re}{SPACE}/; # Wrong!
-</pre>
-<p>It’s not a good idea to split a construct in the middle like this, and
-it doesn’t work here. Instead use the solution above.
-</p>
-<p>Finally, the message also can happen under the <code>/x</code> regex
modifier when the
-<code>\N</code> is separated by spaces from the <code>{</code>, in which case,
remove the spaces.
-</p>
-<pre class="verbatim"> /\N {SPACE}/x; # Wrong!
- /\N{SPACE}/x; # ok
-</pre>
-</dd>
-<dt>No %s allowed while running setuid</dt>
-<dd><a name="perldiag-No-_0025s-allowed-while-running-setuid"></a>
-<p>(F) Certain operations are deemed to be too insecure for a setuid or
-setgid script to even be allowed to attempt. Generally speaking there
-will be another way to do what you want that is, if not secure, at least
-securable. See <a href="#perlsec-NAME">perlsec NAME</a>.
-</p>
-</dd>
-<dt>NO-BREAK SPACE in a charnames alias definition is deprecated</dt>
-<dd><a
name="perldiag-NO_002dBREAK-SPACE-in-a-charnames-alias-definition-is-deprecated"></a>
-<p>(D deprecated) You defined a character name which contained a no-break
-space character. Change it to a regular space. Usually these names are
-defined in the <code>:alias</code> import argument to <code>use
charnames</code>, but they
-could be defined by a translator installed into <code>$^H{charnames}</code>.
See
-<a href="charnames.html#CUSTOM-ALIASES">(charnames)CUSTOM ALIASES</a>.
-</p>
-</dd>
-<dt>No code specified for -%c</dt>
-<dd><a name="perldiag-No-code-specified-for-_002d_0025c"></a>
-<p>(F) Perl’s <strong>-e</strong> and <strong>-E</strong> command-line
options require an argument. If
-you want to run an empty program, pass the empty string as a separate
-argument or run a program consisting of a single 0 or 1:
-</p>
-<pre class="verbatim"> perl -e ""
- perl -e0
- perl -e1
-</pre>
-</dd>
-<dt>No comma allowed after %s</dt>
-<dd><a name="perldiag-No-comma-allowed-after-_0025s"></a>
-<p>(F) A list operator that has a filehandle or "indirect object" is
-not allowed to have a comma between that and the following arguments.
-Otherwise it’d be just another one of the arguments.
-</p>
-<p>One possible cause for this is that you expected to have imported
-a constant to your name space with <strong>use</strong> or
<strong>import</strong> 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 ‘perlfunc use’ and ‘perlfunc import’.
While an
-explicit import list would probably have caught this error earlier
-it naturally does not remedy the fact that your operating system
-still does not support that constant. Maybe you have a typo in
-the constants of the symbol import list of <strong>use</strong> or
<strong>import</strong> or in the
-constant name at the line where this error was triggered?
-</p>
-</dd>
-<dt>No command into which to pipe on command line</dt>
-<dd><a name="perldiag-No-command-into-which-to-pipe-on-command-line"></a>
-<p>(F) An error peculiar to VMS. Perl handles its own command line
-redirection, and found a ’|’ at the end of the command line, so it
-doesn’t know where you want to pipe the output from this command.
-</p>
-</dd>
-<dt>No DB::DB routine defined</dt>
-<dd><a name="perldiag-No-DB_003a_003aDB-routine-defined"></a>
-<p>(F) The currently executing code was compiled with the <strong>-d</strong>
switch, but
-for some reason the current debugger (e.g. <samp>perl5db.pl</samp> or a
<code>Devel::</code>
-module) didn’t define a routine to be called at the beginning of each
-statement.
-</p>
-</dd>
-<dt>No dbm on this machine</dt>
-<dd><a name="perldiag-No-dbm-on-this-machine"></a>
-<p>(P) This is counted as an internal error, because every machine should
-supply dbm nowadays, because Perl comes with SDBM. See <a
href="SDBM_File.html#Top">(SDBM_File)</a>.
-</p>
-</dd>
-<dt>No DB::sub routine defined</dt>
-<dd><a name="perldiag-No-DB_003a_003asub-routine-defined"></a>
-<p>(F) The currently executing code was compiled with the <strong>-d</strong>
switch, but
-for some reason the current debugger (e.g. <samp>perl5db.pl</samp> or a
<code>Devel::</code>
-module) didn’t define a <code>DB::sub</code> routine to be called at the
beginning
-of each ordinary subroutine call.
-</p>
-</dd>
-<dt>No directory specified for -I</dt>
-<dd><a name="perldiag-No-directory-specified-for-_002dI"></a>
-<p>(F) The <strong>-I</strong> command-line switch requires a directory name
as part of the
-<em>same</em> argument. Use <strong>-Ilib</strong>, for instance. <strong>-I
lib</strong> won’t work.
-</p>
-</dd>
-<dt>No error file after 2> or 2>> on command line</dt>
-<dd><a
name="perldiag-No-error-file-after-2_003e-or-2_003e_003e-on-command-line"></a>
-<p>(F) An error peculiar to VMS. Perl handles its own command line
-redirection, and found a ’2>’ or a ’2>>’ on
the command line, but can’t
-find the name of the file to which to write data destined for stderr.
-</p>
-</dd>
-<dt>No group ending character ’%c’ found in template</dt>
-<dd><a
name="perldiag-No-group-ending-character-_0027_0025c_0027-found-in-template"></a>
-<p>(F) A pack or unpack template has an opening ’(’ or
’[’ without its
-matching counterpart. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>No input file after < on command line</dt>
-<dd><a name="perldiag-No-input-file-after-_003c-on-command-line"></a>
-<p>(F) An error peculiar to VMS. Perl handles its own command line
-redirection, and found a ’<’ on the command line, but
can’t find the
-name of the file from which to read data for stdin.
-</p>
-</dd>
-<dt>No next::method ’%s’ found for %s</dt>
-<dd><a
name="perldiag-No-next_003a_003amethod-_0027_0025s_0027-found-for-_0025s"></a>
-<p>(F) <code>next::method</code> found no further instances of this method name
-in the remaining packages of the MRO of this class. If you don’t want
-it throwing an exception, use <code>maybe::next::method</code>
-or <code>next::can</code>. See <a href="mro.html#Top">(mro)</a>.
-</p>
-</dd>
-<dt>Non-finite repeat count does nothing</dt>
-<dd><a name="perldiag-Non_002dfinite-repeat-count-does-nothing"></a>
-<p>(W numeric) You tried to execute the
-<a href="#perlop-Multiplicative-Operators"><code>x</code></a> repetition
operator <code>Inf</code> (or
-<code>-Inf</code>) or <code>NaN</code> times, which doesn’t make sense.
-</p>
-</dd>
-<dt>Non-hex character in regex; marked by <– HERE<!-- /@w --> in
m/%s/</dt>
-<dd><a
name="perldiag-Non_002dhex-character-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) In a regular expression, there was a non-hexadecimal character where
-a hex one was expected, like
-</p>
-<pre class="verbatim"> (?[ [ \xDG ] ])
- (?[ [ \x{DEKA} ] ])
-</pre>
-</dd>
-<dt>Non-octal character in regex; marked by <– HERE<!-- /@w -->
in m/%s/</dt>
-<dd><a
name="perldiag-Non_002doctal-character-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) In a regular expression, there was a non-octal character where
-an octal one was expected, like
-</p>
-<pre class="verbatim"> (?[ [ \o{1278} ] ])
-</pre>
-</dd>
-<dt>Non-octal character ’%c’. Resolved as "%s"</dt>
-<dd><a
name="perldiag-Non_002doctal-character-_0027_0025c_0027_002e-Resolved-as-_0022_0025s_0022"></a>
-<p>(W digit) In parsing an octal numeric constant, a character was
-unexpectedly encountered that isn’t octal. The resulting value
-is as indicated.
-</p>
-</dd>
-<dt>"no" not allowed in expression</dt>
-<dd><a name="perldiag-_0022no_0022-not-allowed-in-expression"></a>
-<p>(F) The "no" keyword is recognized and executed at compile time,
and
-returns no useful value. See <a href="#perlmod-NAME">perlmod NAME</a>.
-</p>
-</dd>
-<dt>Non-string passed as bitmask</dt>
-<dd><a name="perldiag-Non_002dstring-passed-as-bitmask"></a>
-<p>(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 <a href="#perlfunc-select">perlfunc select</a>.
-</p>
-</dd>
-<dt>No output file after > on command line</dt>
-<dd><a name="perldiag-No-output-file-after-_003e-on-command-line"></a>
-<p>(F) An error peculiar to VMS. Perl handles its own command line
-redirection, and found a lone ’>’ at the end of the command
line, so it
-doesn’t know where you wanted to redirect stdout.
-</p>
-</dd>
-<dt>No output file after > or >> on command line</dt>
-<dd><a
name="perldiag-No-output-file-after-_003e-or-_003e_003e-on-command-line"></a>
-<p>(F) An error peculiar to VMS. Perl handles its own command line
-redirection, and found a ’>’ or a ’>>’ on the
command line, but can’t
-find the name of the file to which to write data destined for stdout.
-</p>
-</dd>
-<dt>No package name allowed for variable %s in "our"</dt>
-<dd><a
name="perldiag-No-package-name-allowed-for-variable-_0025s-in-_0022our_0022"></a>
-<p>(F) Fully qualified variable names are not allowed in "our"
-declarations, because that doesn’t make much sense under existing
-rules. Such syntax is reserved for future extensions.
-</p>
-</dd>
-<dt>No Perl script found in input</dt>
-<dd><a name="perldiag-No-Perl-script-found-in-input"></a>
-<p>(F) You called <code>perl -x</code>, but no line was found in the file
beginning
-with #! and containing the word "perl".
-</p>
-</dd>
-<dt>No setregid available</dt>
-<dd><a name="perldiag-No-setregid-available"></a>
-<p>(F) Configure didn’t find anything resembling the setregid() call for
-your system.
-</p>
-</dd>
-<dt>No setreuid available</dt>
-<dd><a name="perldiag-No-setreuid-available"></a>
-<p>(F) Configure didn’t find anything resembling the setreuid() call for
-your system.
-</p>
-</dd>
-<dt>No such class %s</dt>
-<dd><a name="perldiag-No-such-class-_0025s"></a>
-<p>(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.
-</p>
-</dd>
-<dt>No such class field "%s" in variable %s of type %s</dt>
-<dd><a
name="perldiag-No-such-class-field-_0022_0025s_0022-in-variable-_0025s-of-type-_0025s"></a>
-<p>(F) You tried to access a key from a hash through the indicated typed
-variable but that key is not allowed by the package of the same type.
-The indicated package has restricted the set of allowed keys using the
-<a href="fields.html#Top">(fields)</a> pragma.
-</p>
-</dd>
-<dt>No such hook: %s</dt>
-<dd><a name="perldiag-No-such-hook_003a-_0025s"></a>
-<p>(F) You specified a signal hook that was not recognized by Perl.
-Currently, Perl accepts <code>__DIE__</code> and <code>__WARN__</code> as
valid signal hooks.
-</p>
-</dd>
-<dt>No such pipe open</dt>
-<dd><a name="perldiag-No-such-pipe-open"></a>
-<p>(P) An error peculiar to VMS. The internal routine my_pclose() tried to
-close a pipe which hadn’t been opened. This should have been caught
-earlier as an attempt to close an unopened filehandle.
-</p>
-</dd>
-<dt>No such signal: SIG%s</dt>
-<dd><a name="perldiag-No-such-signal_003a-SIG_0025s"></a>
-<p>(W signal) You specified a signal name as a subscript to %SIG that was
-not recognized. Say <code>kill -l</code> in your shell to see the valid signal
-names on your system.
-</p>
-</dd>
-<dt>Not a CODE reference</dt>
-<dd><a name="perldiag-Not-a-CODE-reference"></a>
-<p>(F) Perl was trying to evaluate a reference to a code value (that is, a
-subroutine), but found a reference to something else instead. You can
-use the ref() function to find out what kind of ref it really was. See
-also <a href="#perlref-NAME">perlref NAME</a>.
-</p>
-</dd>
-<dt>Not a GLOB reference</dt>
-<dd><a name="perldiag-Not-a-GLOB-reference"></a>
-<p>(F) Perl was trying to evaluate a reference to a "typeglob" (that
is, a
-symbol table entry that looks like <code>*foo</code>), but found a reference to
-something else instead. You can use the ref() function to find out what
-kind of ref it really was. See <a href="#perlref-NAME">perlref NAME</a>.
-</p>
-</dd>
-<dt>Not a HASH reference</dt>
-<dd><a name="perldiag-Not-a-HASH-reference"></a>
-<p>(F) Perl was trying to evaluate a reference to a hash value, but found a
-reference to something else instead. You can use the ref() function to
-find out what kind of ref it really was. See <a href="#perlref-NAME">perlref
NAME</a>.
-</p>
-</dd>
-<dt>Not an ARRAY reference</dt>
-<dd><a name="perldiag-Not-an-ARRAY-reference"></a>
-<p>(F) Perl was trying to evaluate a reference to an array value, but found
-a reference to something else instead. You can use the ref() function
-to find out what kind of ref it really was. See <a
href="#perlref-NAME">perlref NAME</a>.
-</p>
-</dd>
-<dt>Not an unblessed ARRAY reference</dt>
-<dd><a name="perldiag-Not-an-unblessed-ARRAY-reference"></a>
-<p>(F) You passed a reference to a blessed array to <code>push</code>,
<code>shift</code> or
-another array function. These only accept unblessed array references
-or arrays beginning explicitly with <code>@</code>.
-</p>
-</dd>
-<dt>Not a SCALAR reference</dt>
-<dd><a name="perldiag-Not-a-SCALAR-reference"></a>
-<p>(F) Perl was trying to evaluate a reference to a scalar value, but found
-a reference to something else instead. You can use the ref() function
-to find out what kind of ref it really was. See <a
href="#perlref-NAME">perlref NAME</a>.
-</p>
-</dd>
-<dt>Not a subroutine reference</dt>
-<dd><a name="perldiag-Not-a-subroutine-reference"></a>
-<p>(F) Perl was trying to evaluate a reference to a code value (that is, a
-subroutine), but found a reference to something else instead. You can
-use the ref() function to find out what kind of ref it really was. See
-also <a href="#perlref-NAME">perlref NAME</a>.
-</p>
-</dd>
-<dt>Not a subroutine reference in overload table</dt>
-<dd><a name="perldiag-Not-a-subroutine-reference-in-overload-table"></a>
-<p>(F) An attempt was made to specify an entry in an overloading table that
-doesn’t somehow point to a valid subroutine. See <a
href="overload.html#Top">(overload)</a>.
-</p>
-</dd>
-<dt>Not enough arguments for %s</dt>
-<dd><a name="perldiag-Not-enough-arguments-for-_0025s"></a>
-<p>(F) The function requires more arguments than you specified.
-</p>
-</dd>
-<dt>Not enough format arguments</dt>
-<dd><a name="perldiag-Not-enough-format-arguments"></a>
-<p>(W syntax) A format specified more picture fields than the next line
-supplied. See <a href="#perlform-NAME">perlform NAME</a>.
-</p>
-</dd>
-<dt>%s: not found</dt>
-<dd><a name="perldiag-_0025s_003a-not-found"></a>
-<p>(A) You’ve accidentally run your script through the Bourne shell
instead
-of Perl. Check the #! line, or manually feed your script into Perl
-yourself.
-</p>
-</dd>
-<dt>(?[...]) not valid in locale in regex; marked by <– HERE<!--
/@w --> in m/%s/</dt>
-<dd><a
name="perldiag-_0028_003f_005b_002e_002e_002e_005d_0029-not-valid-in-locale-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) <code>(?[...])</code> cannot be used within the scope of a
<code>use locale<!-- /@w --></code> or with
-an <code>/l</code> regular expression modifier, as that would require deferring
-to run-time the calculation of what it should evaluate to, and it is
-regex compile-time only.
-</p>
-</dd>
-<dt>no UTC offset information; assuming local time is UTC</dt>
-<dd><a
name="perldiag-no-UTC-offset-information_003b-assuming-local-time-is-UTC"></a>
-<p>(S) A warning peculiar to VMS. Perl was unable to find the local
-timezone offset, so it’s assuming that local system time is equivalent
-to UTC. If it’s not, define the logical name
-<samp>SYS$TIMEZONE_DIFFERENTIAL</samp> to translate to the number of seconds
which
-need to be added to UTC to get local time.
-</p>
-</dd>
-<dt>NULL OP IN RUN</dt>
-<dd><a name="perldiag-NULL-OP-IN-RUN"></a>
-<p>(S debugging) Some internal routine called run() with a null opcode
-pointer.
-</p>
-</dd>
-<dt>Null picture in formline</dt>
-<dd><a name="perldiag-Null-picture-in-formline"></a>
-<p>(F) The first argument to formline must be a valid format picture
-specification. It was found to be empty, which probably means you
-supplied it an uninitialized value. See <a href="#perlform-NAME">perlform
NAME</a>.
-</p>
-</dd>
-<dt>Null realloc</dt>
-<dd><a name="perldiag-Null-realloc"></a>
-<p>(P) An attempt was made to realloc NULL.
-</p>
-</dd>
-<dt>NULL regexp argument</dt>
-<dd><a name="perldiag-NULL-regexp-argument"></a>
-<p>(P) The internal pattern matching routines blew it big time.
-</p>
-</dd>
-<dt>NULL regexp parameter</dt>
-<dd><a name="perldiag-NULL-regexp-parameter"></a>
-<p>(P) The internal pattern matching routines are out of their gourd.
-</p>
-</dd>
-<dt>Number too long</dt>
-<dd><a name="perldiag-Number-too-long"></a>
-<p>(F) Perl limits the representation of decimal numbers in programs to
-about 250 characters. You’ve exceeded that length. Future
-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").
-</p>
-</dd>
-<dt>Number with no digits</dt>
-<dd><a name="perldiag-Number-with-no-digits"></a>
-<p>(F) Perl was looking for a number but found nothing that looked like
-a number. This happens, for example with <code>\o{}</code>, with no number
between
-the braces.
-</p>
-</dd>
-<dt>Octal number > 037777777777 non-portable</dt>
-<dd><a name="perldiag-Octal-number-_003e-037777777777-non_002dportable"></a>
-<p>(W portable) The octal number you specified is larger than 2**32-1
-(4294967295) and therefore non-portable between systems. See
-<a href="#perlport-NAME">perlport NAME</a> for more on portability concerns.
-</p>
-</dd>
-<dt>Odd name/value argument for subroutine</dt>
-<dd><a name="perldiag-Odd-name_002fvalue-argument-for-subroutine"></a>
-<p>(F) A subroutine using a slurpy hash parameter in its signature
-received an odd number of arguments to populate the hash. It requires
-the arguments to be paired, with the same number of keys as values.
-The caller of the subroutine is presumably at fault. Inconveniently,
-this error will be reported at the location of the subroutine, not that
-of the caller.
-</p>
-</dd>
-<dt>Odd number of arguments for overload::constant</dt>
-<dd><a
name="perldiag-Odd-number-of-arguments-for-overload_003a_003aconstant"></a>
-<p>(W overload) The call to overload::constant contained an odd number of
-arguments. The arguments should come in pairs.
-</p>
-</dd>
-<dt>Odd number of elements in anonymous hash</dt>
-<dd><a name="perldiag-Odd-number-of-elements-in-anonymous-hash"></a>
-<p>(W misc) You specified an odd number of elements to initialize a hash,
-which is odd, because hashes come in key/value pairs.
-</p>
-</dd>
-<dt>Odd number of elements in hash assignment</dt>
-<dd><a name="perldiag-Odd-number-of-elements-in-hash-assignment"></a>
-<p>(W misc) You specified an odd number of elements to initialize a hash,
-which is odd, because hashes come in key/value pairs.
-</p>
-</dd>
-<dt>Offset outside string</dt>
-<dd><a name="perldiag-Offset-outside-string"></a>
-<p>(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
-<code>sysread()</code>ing a file, or when seeking past the end of a scalar
opened
-for I/O (in anticipation of future reads and to imitate the behavior
-with real files).
-</p>
-</dd>
-<dt>%s() on unopened %s</dt>
-<dd><a name="perldiag-_0025s_0028_0029-on-unopened-_0025s"></a>
-<p>(W unopened) An I/O operation was attempted on a filehandle that was
-never initialized. You need to do an open(), a sysopen(), or a socket()
-call, or call a constructor from the FileHandle package.
-</p>
-</dd>
-<dt>-%s on unopened filehandle %s</dt>
-<dd><a name="perldiag-_002d_0025s-on-unopened-filehandle-_0025s"></a>
-<p>(W unopened) You tried to invoke a file test operator on a filehandle
-that isn’t open. Check your control flow. See also <a
href="#perlfunc-_002dX">perlfunc -X</a>.
-</p>
-</dd>
-<dt>oops: oopsAV</dt>
-<dd><a name="perldiag-oops_003a-oopsAV"></a>
-<p>(S internal) An internal warning that the grammar is screwed up.
-</p>
-</dd>
-<dt>oops: oopsHV</dt>
-<dd><a name="perldiag-oops_003a-oopsHV"></a>
-<p>(S internal) An internal warning that the grammar is screwed up.
-</p>
-</dd>
-<dt>Opening dirhandle %s also as a file</dt>
-<dd><a name="perldiag-Opening-dirhandle-_0025s-also-as-a-file"></a>
-<p>(D io, deprecated) You used open() to associate a filehandle to
-a symbol (glob or scalar) that already holds a dirhandle.
-Although legal, this idiom might render your code confusing
-and is deprecated.
-</p>
-</dd>
-<dt>Opening filehandle %s also as a directory</dt>
-<dd><a name="perldiag-Opening-filehandle-_0025s-also-as-a-directory"></a>
-<p>(D io, deprecated) You used opendir() to associate a dirhandle to
-a symbol (glob or scalar) that already holds a filehandle.
-Although legal, this idiom might render your code confusing
-and is deprecated.
-</p>
-</dd>
-<dt>Operand with no preceding operator in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Operand-with-no-preceding-operator-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You wrote something like
-</p>
-<pre class="verbatim"> (?[ \p{Digit} \p{Thai} ])
-</pre>
-<p>There are two operands, but no operator giving how you want to combine
-them.
-</p>
-</dd>
-<dt>Operation "%s": no method found, %s</dt>
-<dd><a
name="perldiag-Operation-_0022_0025s_0022_003a-no-method-found_002c-_0025s"></a>
-<p>(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
-the <code>fallback</code> overloading key is specified to be true. See <a
href="overload.html#Top">(overload)</a>.
-</p>
-</dd>
-<dt>Operation "%s" returns its argument for non-Unicode code point
0x%X</dt>
-<dd><a
name="perldiag-Operation-_0022_0025s_0022-returns-its-argument-for-non_002dUnicode-code-point-0x_0025X"></a>
-<p>(S non_unicode) You performed an operation requiring Unicode rules
-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.
-</p>
-<p>If the operation shown is "ToFold", it means that case-insensitive
-matching in a regular expression was done on the code point.
-</p>
-<p>If you know what you are doing you can turn off this warning by
-<code>no warnings 'non_unicode';</code>.
-</p>
-</dd>
-<dt>Operation "%s" returns its argument for UTF-16 surrogate
U+%X</dt>
-<dd><a
name="perldiag-Operation-_0022_0025s_0022-returns-its-argument-for-UTF_002d16-surrogate-U_002b_0025X"></a>
-<p>(S surrogate) You performed an operation requiring Unicode
-rules on a Unicode surrogate. Unicode frowns upon the use
-of surrogates for anything but storing strings in UTF-16, but
-rules 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.
-</p>
-<p>If the operation shown is "ToFold", it means that case-insensitive
-matching in a regular expression was done on the code point.
-</p>
-<p>If you know what you are doing you can turn off this warning by
-<code>no warnings 'surrogate';</code>.
-</p>
-</dd>
-<dt>Operator or semicolon missing before %s</dt>
-<dd><a name="perldiag-Operator-or-semicolon-missing-before-_0025s"></a>
-<p>(S ambiguous) You used a variable or subroutine call where the parser
-was expecting an operator. The parser has assumed you really meant to
-use an operator, but this is highly likely to be incorrect. For
-example, if you say "*foo *foo" it will be interpreted as if you said
-"*foo * ’foo’".
-</p>
-</dd>
-<dt>Optional parameter lacks default expression</dt>
-<dd><a name="perldiag-Optional-parameter-lacks-default-expression"></a>
-<p>(F) In a subroutine signature, you wrote something like "$a =",
making a
-named optional parameter without a default value. A nameless optional
-parameter is permitted to have no default value, but a named one must
-have a specific default. You probably want "$a = undef".
-</p>
-</dd>
-<dt>"our" variable %s redeclared</dt>
-<dd><a name="perldiag-_0022our_0022-variable-_0025s-redeclared"></a>
-<p>(W misc) You seem to have already declared the same global once before
-in the current lexical scope.
-</p>
-</dd>
-<dt>Out of memory!</dt>
-<dd><a name="perldiag-Out-of-memory_0021"></a>
-<p>(X) The malloc() function returned 0, indicating there was insufficient
-remaining memory (or virtual memory) to satisfy the request. Perl has
-no option but to exit immediately.
-</p>
-<p>At least in Unix you may be able to get past this by increasing your
-process datasize limits: in csh/tcsh use <code>limit</code> and
-<code>limit datasize n</code> (where <code>n</code> is the number of
kilobytes) to check
-the current limits and change them, and in ksh/bash/zsh use <code>ulimit
-a</code>
-and <code>ulimit -d n</code>, respectively.
-</p>
-</dd>
-<dt>Out of memory during %s extend</dt>
-<dd><a name="perldiag-Out-of-memory-during-_0025s-extend"></a>
-<p>(X) An attempt was made to extend an array, a list, or a string beyond
-the largest possible memory allocation.
-</p>
-</dd>
-<dt>Out of memory during "large" request for %s</dt>
-<dd><a
name="perldiag-Out-of-memory-during-_0022large_0022-request-for-_0025s"></a>
-<p>(F) The malloc() function returned 0, indicating there was insufficient
-remaining memory (or virtual memory) to satisfy the request. However,
-the request was judged large enough (compile-time default is 64K), so a
-possibility to shut down by trapping this error is granted.
-</p>
-</dd>
-<dt>Out of memory during request for %s</dt>
-<dd><a name="perldiag-Out-of-memory-during-request-for-_0025s"></a>
-<p>(X)(F) The malloc() function returned 0, indicating there was
-insufficient remaining memory (or virtual memory) to satisfy the
-request.
-</p>
-<p>The request was judged to be small, so the possibility to trap it
-depends on the way perl was compiled. By default it is not trappable.
-However, if compiled for this, Perl may use the contents of <code>$^M</code>
as an
-emergency pool after die()ing with this message. In this case the error
-is trappable <em>once</em>, and the error message will include the line and
file
-where the failed request happened.
-</p>
-</dd>
-<dt>Out of memory during ridiculously large request</dt>
-<dd><a name="perldiag-Out-of-memory-during-ridiculously-large-request"></a>
-<p>(F) You can’t allocate more than 2^31+"small amount" bytes.
This error
-is most likely to be caused by a typo in the Perl program. e.g.,
-<code>$arr[time]</code> instead of <code>$arr[$time]</code>.
-</p>
-</dd>
-<dt>Out of memory for yacc stack</dt>
-<dd><a name="perldiag-Out-of-memory-for-yacc-stack"></a>
-<p>(F) The yacc parser wanted to grow its stack so it could continue
-parsing, but realloc() wouldn’t give it more memory, virtual or
-otherwise.
-</p>
-</dd>
-<dt>’.’ outside of string in pack</dt>
-<dd><a name="perldiag-_0027_002e_0027-outside-of-string-in-pack"></a>
-<p>(F) The argument to a ’.’ in your template tried to move the
working
-position to before the start of the packed string being built.
-</p>
-</dd>
-<dt>’@’ outside of string in unpack</dt>
-<dd><a name="perldiag-_0027_0040_0027-outside-of-string-in-unpack"></a>
-<p>(F) You had a template that specified an absolute position outside
-the string being unpacked. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>’@’ outside of string with malformed UTF-8 in unpack</dt>
-<dd><a
name="perldiag-_0027_0040_0027-outside-of-string-with-malformed-UTF_002d8-in-unpack"></a>
-<p>(F) You had a template that specified an absolute position outside
-the string being unpacked. The string being unpacked was also invalid
-UTF-8. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>overload arg ’%s’ is invalid</dt>
-<dd><a name="perldiag-overload-arg-_0027_0025s_0027-is-invalid"></a>
-<p>(W overload) The <a href="overload.html#Top">(overload)</a> pragma was
passed an argument it did not
-recognize. Did you mistype an operator?
-</p>
-</dd>
-<dt>Overloaded dereference did not return a reference</dt>
-<dd><a name="perldiag-Overloaded-dereference-did-not-return-a-reference"></a>
-<p>(F) An object with an overloaded dereference operator was dereferenced,
-but the overloaded operation did not return a reference. See
-<a href="overload.html#Top">(overload)</a>.
-</p>
-</dd>
-<dt>Overloaded qr did not return a REGEXP</dt>
-<dd><a name="perldiag-Overloaded-qr-did-not-return-a-REGEXP"></a>
-<p>(F) An object with a <code>qr</code> overload was used as part of a match,
but the
-overloaded operation didn’t return a compiled regexp. See <a
href="overload.html#Top">(overload)</a>.
-</p>
-</dd>
-<dt>%s package attribute may clash with future reserved word: %s</dt>
-<dd><a
name="perldiag-_0025s-package-attribute-may-clash-with-future-reserved-word_003a-_0025s"></a>
-<p>(W reserved) A lowercase attribute name was used that had a
-package-specific handler. That name might have a meaning to Perl itself
-some day, even though it doesn’t yet. Perhaps you should use a
-mixed-case attribute name, instead. See <a
href="attributes.html#Top">(attributes)</a>.
-</p>
-</dd>
-<dt>pack/unpack repeat count overflow</dt>
-<dd><a name="perldiag-pack_002funpack-repeat-count-overflow"></a>
-<p>(F) You can’t specify a repeat count so large that it overflows your
-signed integers. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>page overflow</dt>
-<dd><a name="perldiag-page-overflow"></a>
-<p>(W io) A single call to write() produced more lines than can fit on a
-page. See <a href="#perlform-NAME">perlform NAME</a>.
-</p>
-</dd>
-<dt>panic: %s</dt>
-<dd><a name="perldiag-panic_003a-_0025s"></a>
-<p>(P) An internal error.
-</p>
-</dd>
-<dt>panic: attempt to call %s in %s</dt>
-<dd><a name="perldiag-panic_003a-attempt-to-call-_0025s-in-_0025s"></a>
-<p>(P) One of the file test operators entered a code branch that calls
-an ACL related-function, but that function is not available on this
-platform. Earlier checks mean that it should not be possible to
-enter this branch on this platform.
-</p>
-</dd>
-<dt>panic: child pseudo-process was never scheduled</dt>
-<dd><a
name="perldiag-panic_003a-child-pseudo_002dprocess-was-never-scheduled"></a>
-<p>(P) A child pseudo-process in the ithreads implementation on Windows
-was not scheduled within the time period allowed and therefore was not
-able to initialize properly.
-</p>
-</dd>
-<dt>panic: ck_grep, type=%u</dt>
-<dd><a name="perldiag-panic_003a-ck_005fgrep_002c-type_003d_0025u"></a>
-<p>(P) Failed an internal consistency check trying to compile a grep.
-</p>
-</dd>
-<dt>panic: ck_split, type=%u</dt>
-<dd><a name="perldiag-panic_003a-ck_005fsplit_002c-type_003d_0025u"></a>
-<p>(P) Failed an internal consistency check trying to compile a split.
-</p>
-</dd>
-<dt>panic: corrupt saved stack index %ld</dt>
-<dd><a name="perldiag-panic_003a-corrupt-saved-stack-index-_0025ld"></a>
-<p>(P) The savestack was requested to restore more localized values than
-there are in the savestack.
-</p>
-</dd>
-<dt>panic: del_backref</dt>
-<dd><a name="perldiag-panic_003a-del_005fbackref"></a>
-<p>(P) Failed an internal consistency check while trying to reset a weak
-reference.
-</p>
-</dd>
-<dt>panic: die %s</dt>
-<dd><a name="perldiag-panic_003a-die-_0025s"></a>
-<p>(P) We popped the context stack to an eval context, and then discovered
-it wasn’t an eval context.
-</p>
-</dd>
-<dt>panic: do_subst</dt>
-<dd><a name="perldiag-panic_003a-do_005fsubst"></a>
-<p>(P) The internal pp_subst() routine was called with invalid operational
-data.
-</p>
-</dd>
-<dt>panic: do_trans_%s</dt>
-<dd><a name="perldiag-panic_003a-do_005ftrans_005f_0025s"></a>
-<p>(P) The internal do_trans routines were called with invalid operational
-data.
-</p>
-</dd>
-<dt>panic: fold_constants JMPENV_PUSH returned %d</dt>
-<dd><a
name="perldiag-panic_003a-fold_005fconstants-JMPENV_005fPUSH-returned-_0025d"></a>
-<p>(P) While attempting folding constants an exception other than an
<code>eval</code>
-failure was caught.
-</p>
-</dd>
-<dt>panic: frexp: %f</dt>
-<dd><a name="perldiag-panic_003a-frexp_003a-_0025f"></a>
-<p>(P) The library function frexp() failed, making printf("%f")
impossible.
-</p>
-</dd>
-<dt>panic: goto, type=%u, ix=%ld</dt>
-<dd><a
name="perldiag-panic_003a-goto_002c-type_003d_0025u_002c-ix_003d_0025ld"></a>
-<p>(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.
-</p>
-</dd>
-<dt>panic: gp_free failed to free glob pointer</dt>
-<dd><a name="perldiag-panic_003a-gp_005ffree-failed-to-free-glob-pointer"></a>
-<p>(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.
-</p>
-</dd>
-<dt>panic: INTERPCASEMOD, %s</dt>
-<dd><a name="perldiag-panic_003a-INTERPCASEMOD_002c-_0025s"></a>
-<p>(P) The lexer got into a bad state at a case modifier.
-</p>
-</dd>
-<dt>panic: INTERPCONCAT, %s</dt>
-<dd><a name="perldiag-panic_003a-INTERPCONCAT_002c-_0025s"></a>
-<p>(P) The lexer got into a bad state parsing a string with brackets.
-</p>
-</dd>
-<dt>panic: kid popen errno read</dt>
-<dd><a name="perldiag-panic_003a-kid-popen-errno-read"></a>
-<p>(F) A forked child returned an incomprehensible message about its errno.
-</p>
-</dd>
-<dt>panic: last, type=%u</dt>
-<dd><a name="perldiag-panic_003a-last_002c-type_003d_0025u"></a>
-<p>(P) We popped the context stack to a block context, and then discovered
-it wasn’t a block context.
-</p>
-</dd>
-<dt>panic: leave_scope clearsv</dt>
-<dd><a name="perldiag-panic_003a-leave_005fscope-clearsv"></a>
-<p>(P) A writable lexical variable became read-only somehow within the
-scope.
-</p>
-</dd>
-<dt>panic: leave_scope inconsistency %u</dt>
-<dd><a name="perldiag-panic_003a-leave_005fscope-inconsistency-_0025u"></a>
-<p>(P) The savestack probably got out of sync. At least, there was an
-invalid enum on the top of it.
-</p>
-</dd>
-<dt>panic: magic_killbackrefs</dt>
-<dd><a name="perldiag-panic_003a-magic_005fkillbackrefs"></a>
-<p>(P) Failed an internal consistency check while trying to reset all weak
-references to an object.
-</p>
-</dd>
-<dt>panic: malloc, %s</dt>
-<dd><a name="perldiag-panic_003a-malloc_002c-_0025s"></a>
-<p>(P) Something requested a negative number of bytes of malloc.
-</p>
-</dd>
-<dt>panic: memory wrap</dt>
-<dd><a name="perldiag-panic_003a-memory-wrap"></a>
-<p>(P) Something tried to allocate either more memory than possible or a
-negative amount.
-</p>
-</dd>
-<dt>panic: pad_alloc, %p!=%p</dt>
-<dd><a
name="perldiag-panic_003a-pad_005falloc_002c-_0025p_0021_003d_0025p"></a>
-<p>(P) The compiler got confused about which scratch pad it was allocating
-and freeing temporaries and lexicals from.
-</p>
-</dd>
-<dt>panic: pad_free curpad, %p!=%p</dt>
-<dd><a
name="perldiag-panic_003a-pad_005ffree-curpad_002c-_0025p_0021_003d_0025p"></a>
-<p>(P) The compiler got confused about which scratch pad it was allocating
-and freeing temporaries and lexicals from.
-</p>
-</dd>
-<dt>panic: pad_free po</dt>
-<dd><a name="perldiag-panic_003a-pad_005ffree-po"></a>
-<p>(P) A zero scratch pad offset was detected internally. An attempt was
-made to free a target that had not been allocated to begin with.
-</p>
-</dd>
-<dt>panic: pad_reset curpad, %p!=%p</dt>
-<dd><a
name="perldiag-panic_003a-pad_005freset-curpad_002c-_0025p_0021_003d_0025p"></a>
-<p>(P) The compiler got confused about which scratch pad it was allocating
-and freeing temporaries and lexicals from.
-</p>
-</dd>
-<dt>panic: pad_sv po</dt>
-<dd><a name="perldiag-panic_003a-pad_005fsv-po"></a>
-<p>(P) A zero scratch pad offset was detected internally. Most likely
-an operator needed a target but that target had not been allocated
-for whatever reason.
-</p>
-</dd>
-<dt>panic: pad_swipe curpad, %p!=%p</dt>
-<dd><a
name="perldiag-panic_003a-pad_005fswipe-curpad_002c-_0025p_0021_003d_0025p"></a>
-<p>(P) The compiler got confused about which scratch pad it was allocating
-and freeing temporaries and lexicals from.
-</p>
-</dd>
-<dt>panic: pad_swipe po</dt>
-<dd><a name="perldiag-panic_003a-pad_005fswipe-po"></a>
-<p>(P) An invalid scratch pad offset was detected internally.
-</p>
-</dd>
-<dt>panic: pp_iter, type=%u</dt>
-<dd><a name="perldiag-panic_003a-pp_005fiter_002c-type_003d_0025u"></a>
-<p>(P) The foreach iterator got called in a non-loop context frame.
-</p>
-</dd>
-<dt>panic: pp_match%s</dt>
-<dd><a name="perldiag-panic_003a-pp_005fmatch_0025s"></a>
-<p>(P) The internal pp_match() routine was called with invalid operational
-data.
-</p>
-</dd>
-<dt>panic: pp_split, pm=%p, s=%p</dt>
-<dd><a
name="perldiag-panic_003a-pp_005fsplit_002c-pm_003d_0025p_002c-s_003d_0025p"></a>
-<p>(P) Something terrible went wrong in setting up for the split.
-</p>
-</dd>
-<dt>panic: realloc, %s</dt>
-<dd><a name="perldiag-panic_003a-realloc_002c-_0025s"></a>
-<p>(P) Something requested a negative number of bytes of realloc.
-</p>
-</dd>
-<dt>panic: reference miscount on nsv in sv_replace() (%d != 1)</dt>
-<dd><a
name="perldiag-panic_003a-reference-miscount-on-nsv-in-sv_005freplace_0028_0029-_0028_0025d-_0021_003d-1_0029"></a>
-<p>(P) The internal sv_replace() function was handed a new SV with a
-reference count other than 1.
-</p>
-</dd>
-<dt>panic: restartop in %s</dt>
-<dd><a name="perldiag-panic_003a-restartop-in-_0025s"></a>
-<p>(P) Some internal routine requested a goto (or something like it), and
-didn’t supply the destination.
-</p>
-</dd>
-<dt>panic: return, type=%u</dt>
-<dd><a name="perldiag-panic_003a-return_002c-type_003d_0025u"></a>
-<p>(P) We popped the context stack to a subroutine or eval context, and
-then discovered it wasn’t a subroutine or eval context.
-</p>
-</dd>
-<dt>panic: scan_num, %s</dt>
-<dd><a name="perldiag-panic_003a-scan_005fnum_002c-_0025s"></a>
-<p>(P) scan_num() got called on something that wasn’t a number.
-</p>
-</dd>
-<dt>panic: Sequence (?{...}): no code block found in regex m/%s/</dt>
-<dd><a
name="perldiag-panic_003a-Sequence-_0028_003f_007b_002e_002e_002e_007d_0029_003a-no-code-block-found-in-regex-m_002f_0025s_002f"></a>
-<p>(P) While compiling a pattern that has embedded (?{}) or (??{}) code
-blocks, perl couldn’t locate the code block that should have already been
-seen and compiled by perl before control passed to the regex compiler.
-</p>
-</dd>
-<dt>panic: strxfrm() gets absurd - a => %u, ab => %u</dt>
-<dd><a
name="perldiag-panic_003a-strxfrm_0028_0029-gets-absurd-_002d-a-_003d_003e-_0025u_002c-ab-_003d_003e-_0025u"></a>
-<p>(P) The interpreter’s sanity check of the C function strxfrm() failed.
-In your current locale the returned transformation of the string "ab"
-is shorter than that of the string "a", which makes no sense.
-</p>
-</dd>
-<dt>panic: sv_chop %s</dt>
-<dd><a name="perldiag-panic_003a-sv_005fchop-_0025s"></a>
-<p>(P) The sv_chop() routine was passed a position that is not within the
-scalar’s string buffer.
-</p>
-</dd>
-<dt>panic: sv_insert, midend=%p, bigend=%p</dt>
-<dd><a
name="perldiag-panic_003a-sv_005finsert_002c-midend_003d_0025p_002c-bigend_003d_0025p"></a>
-<p>(P) The sv_insert() routine was told to remove more string than there
-was string.
-</p>
-</dd>
-<dt>panic: top_env</dt>
-<dd><a name="perldiag-panic_003a-top_005fenv"></a>
-<p>(P) The compiler attempted to do a goto, or something weird like that.
-</p>
-</dd>
-<dt>panic: unimplemented op %s (#%d) called</dt>
-<dd><a
name="perldiag-panic_003a-unimplemented-op-_0025s-_0028_0023_0025d_0029-called"></a>
-<p>(P) The compiler is screwed up and attempted to use an op that isn’t
-permitted at run time.
-</p>
-</dd>
-<dt>panic: utf16_to_utf8: odd bytelen</dt>
-<dd><a name="perldiag-panic_003a-utf16_005fto_005futf8_003a-odd-bytelen"></a>
-<p>(P) Something tried to call utf16_to_utf8 with an odd (as opposed
-to even) byte length.
-</p>
-</dd>
-<dt>panic: utf16_to_utf8_reversed: odd bytelen</dt>
-<dd><a
name="perldiag-panic_003a-utf16_005fto_005futf8_005freversed_003a-odd-bytelen"></a>
-<p>(P) Something tried to call utf16_to_utf8_reversed with an odd (as opposed
-to even) byte length.
-</p>
-</dd>
-<dt>panic: yylex, %s</dt>
-<dd><a name="perldiag-panic_003a-yylex_002c-_0025s"></a>
-<p>(P) The lexer got into a bad state while processing a case modifier.
-</p>
-</dd>
-<dt>Parentheses missing around "%s" list</dt>
-<dd><a name="perldiag-Parentheses-missing-around-_0022_0025s_0022-list"></a>
-<p>(W parenthesis) You said something like
-</p>
-<pre class="verbatim"> my $foo, $bar = @_;
-</pre>
-<p>when you meant
-</p>
-<pre class="verbatim"> my ($foo, $bar) = @_;
-</pre>
-<p>Remember that "my", "our", "local" and
"state" bind tighter than comma.
-</p>
-</dd>
-<dt>Parsing code internal error (%s)</dt>
-<dd><a name="perldiag-Parsing-code-internal-error-_0028_0025s_0029"></a>
-<p>(F) Parsing code supplied by an extension violated the parser’s API in
-a detectable way.
-</p>
-</dd>
-<dt>Passing malformed UTF-8 to "%s" is deprecated</dt>
-<dd><a
name="perldiag-Passing-malformed-UTF_002d8-to-_0022_0025s_0022-is-deprecated"></a>
-<p>(D deprecated, utf8) This message indicates a bug either in the Perl
-core or in XS code. Such code was trying to find out if a character,
-allegedly stored internally encoded as UTF-8, was of a given type, such
-as being punctuation or a digit. But the character was not encoded in
-legal UTF-8. The <code>%s</code> is replaced by a string that can be used by
-knowledgeable people to determine what the type being checked against
-was. If <code>utf8</code> warnings are enabled, a further message is raised,
-giving details of the malformation.
-</p>
-</dd>
-<dt>Pattern subroutine nesting without pos change exceeded limit in regex</dt>
-<dd><a
name="perldiag-Pattern-subroutine-nesting-without-pos-change-exceeded-limit-in-regex"></a>
-<p>(F) You used a pattern that uses too many nested subpattern calls without
-consuming any text. Restructure the pattern so text is consumed before
-the nesting limit is exceeded.
-</p>
-</dd>
-<dt><code>-p</code> destination: %s</dt>
-<dd><a name="perldiag-_002dp-destination_003a-_0025s"></a>
-<p>(F) An error occurred during the implicit output invoked by the
<code>-p</code>
-command-line switch. (This output goes to STDOUT unless you’ve
-redirected it with select().)
-</p>
-</dd>
-<dt>Perl API version %s of %s does not match %s</dt>
-<dd><a
name="perldiag-Perl-API-version-_0025s-of-_0025s-does-not-match-_0025s"></a>
-<p>(F) The XS module in question was compiled against a different incompatible
-version of Perl than the one that has loaded the XS module.
-</p>
-</dd>
-<dt>Perl folding rules are not up-to-date for 0x%X; please use the perlbug
utility to report; in regex; marked by <– HERE<!-- /@w --> in
m/%s/</dt>
-<dd><a
name="perldiag-Perl-folding-rules-are-not-up_002dto_002ddate-for-0x_0025X_003b-please-use-the-perlbug-utility-to-report_003b-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(S regexp) 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 <a href="perlbug.html#Top">(perlbug)</a>
utility.
-</p>
-</dd>
-<dt>PerlIO layer ’:win32’ is experimental</dt>
-<dd><a name="perldiag-PerlIO-layer-_0027_003awin32_0027-is-experimental"></a>
-<p>(S experimental::win32_perlio) The <code>:win32</code> PerlIO layer is
-experimental. If you want to take the risk of using this layer,
-simply disable this warning:
-</p>
-<pre class="verbatim"> no warnings "experimental::win32_perlio";
-</pre>
-</dd>
-<dt>Perl_my_%s() not available</dt>
-<dd><a name="perldiag-Perl_005fmy_005f_0025s_0028_0029-not-available"></a>
-<p>(F) Your platform has very uncommon byte-order and integer size,
-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
‘perlfunc pack’.
-</p>
-</dd>
-<dt>Perl %s required (did you mean %s?)–this is only %s, stopped</dt>
-<dd><a
name="perldiag-Perl-_0025s-required-_0028did-you-mean-_0025s_003f_0029_002d_002dthis-is-only-_0025s_002c-stopped"></a>
-<p>(F) The code you are trying to run has asked for a newer version of
-Perl than you are running. Perhaps <code>use 5.10</code> was written instead
-of <code>use 5.010</code> or <code>use v5.10</code>. Without the leading
<code>v</code>, the number is
-interpreted as a decimal, with every three digits after the
-decimal point representing a part of the version number. So 5.10
-is equivalent to v5.100.
-</p>
-</dd>
-<dt>Perl %s required–this is only %s, stopped</dt>
-<dd><a
name="perldiag-Perl-_0025s-required_002d_002dthis-is-only-_0025s_002c-stopped"></a>
-<p>(F) The module in question uses features of a version of Perl more
-recent than the currently running version. How long has it been since
-you upgraded, anyway? See <a href="#perlfunc-require">perlfunc require</a>.
-</p>
-</dd>
-<dt>PERL_SH_DIR too long</dt>
-<dd><a name="perldiag-PERL_005fSH_005fDIR-too-long"></a>
-<p>(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the
-<code>sh</code>-shell in. See "PERL_SH_DIR" in <a
href="perlos2.html#Top">(perlos2)</a>.
-</p>
-</dd>
-<dt>PERL_SIGNALS illegal: "%s"</dt>
-<dd><a name="perldiag-PERL_005fSIGNALS-illegal_003a-_0022_0025s_0022"></a>
-<p>(X) See <a href="#perlrun-PERL_005fSIGNALS">perlrun PERL_SIGNALS</a> for
legal values.
-</p>
-</dd>
-<dt>Perls since %s too modern–this is %s, stopped</dt>
-<dd><a
name="perldiag-Perls-since-_0025s-too-modern_002d_002dthis-is-_0025s_002c-stopped"></a>
-<p>(F) The code you are trying to run claims it will not run
-on the version of Perl you are using because it is too new.
-Maybe the code needs to be updated, or maybe it is simply
-wrong and the version check should just be removed.
-</p>
-</dd>
-<dt>perl: warning: Non hex character in ’$ENV{PERL_HASH_SEED}’,
seed only partially set</dt>
-<dd><a
name="perldiag-perl_003a-warning_003a-Non-hex-character-in-_0027_0024ENV_007bPERL_005fHASH_005fSEED_007d_0027_002c-seed-only-partially-set"></a>
-<p>(S) PERL_HASH_SEED should match /^\s*(?:0x)?[0-9a-fA-F]+\s*\z/ but it
-contained a non hex character. This could mean you are not using the
-hash seed you think you are.
-</p>
-</dd>
-<dt>perl: warning: Setting locale failed.</dt>
-<dd><a name="perldiag-perl_003a-warning_003a-Setting-locale-failed_002e"></a>
-<p>(S) The whole warning message will look something like:
-</p>
-<pre class="verbatim"> perl: warning: Setting locale failed.
- perl: warning: Please check that your locale settings:
- LC_ALL = "En_US",
- LANG = (unset)
- are supported and installed on your system.
- perl: warning: Falling back to the standard locale ("C").
-</pre>
-<p>Exactly what were the failed locale settings varies. In the above the
-settings were that the LC_ALL was "En_US" and the LANG had no value.
-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, 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
-<a href="#perllocale-NAME">perllocale NAME</a> section <strong>LOCALE
PROBLEMS</strong>.
-</p>
-</dd>
-<dt>perl: warning: strange setting in ’$ENV{PERL_PERTURB_KEYS}’:
’%s’</dt>
-<dd><a
name="perldiag-perl_003a-warning_003a-strange-setting-in-_0027_0024ENV_007bPERL_005fPERTURB_005fKEYS_007d_0027_003a-_0027_0025s_0027"></a>
-<p>(S) Perl was run with the environment variable PERL_PERTURB_KEYS defined
-but containing an unexpected value. The legal values of this setting
-are as follows.
-</p>
-<pre class="verbatim"> Numeric | String | Result
- --------+---------------+-----------------------------------------
- 0 | NO | Disables key traversal randomization
- 1 | RANDOM | Enables full key traversal randomization
- 2 | DETERMINISTIC | Enables repeatable key traversal
- | | randomization
-</pre>
-<p>Both numeric and string values are accepted, but note that string values are
-case sensitive. The default for this setting is "RANDOM" or 1.
-</p>
-</dd>
-<dt>pid %x not a child</dt>
-<dd><a name="perldiag-pid-_0025x-not-a-child"></a>
-<p>(W exec) A warning peculiar to VMS. Waitpid() was asked to wait for a
-process which isn’t a subprocess of the current process. While this is
-fine from VMS’ perspective, it’s probably not what you intended.
-</p>
-</dd>
-<dt>’P’ must have an explicit size in unpack</dt>
-<dd><a name="perldiag-_0027P_0027-must-have-an-explicit-size-in-unpack"></a>
-<p>(F) The unpack format P must have an explicit size, not "*".
-</p>
-</dd>
-<dt>pop on reference is experimental</dt>
-<dd><a name="perldiag-pop-on-reference-is-experimental"></a>
-<p>(S experimental::autoderef) <code>pop</code> with a scalar argument is
experimental
-and may change or be removed in a future Perl version. If you want to
-take the risk of using this feature, simply disable this warning:
-</p>
-<pre class="verbatim"> no warnings "experimental::autoderef";
-</pre>
-</dd>
-<dt>POSIX class [:%s:] unknown in regex; marked by <– HERE<!--
/@w --> in m/%s/</dt>
-<dd><a
name="perldiag-POSIX-class-_005b_003a_0025s_003a_005d-unknown-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The class in the character class [: :] syntax is unknown. The
<– HERE<!-- /@w -->
-shows whereabouts in the regular expression the problem was discovered.
-Note that the POSIX character classes do <strong>not</strong> have the
<code>is</code> prefix
-the corresponding C interfaces have: in other words, it’s
<code>[[:print:]]</code>,
-not <code>isprint</code>. See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>POSIX getpgrp can’t take an argument</dt>
-<dd><a name="perldiag-POSIX-getpgrp-can_0027t-take-an-argument"></a>
-<p>(F) Your system has POSIX getpgrp(), which takes no argument, unlike
-the BSD version, which takes a pid.
-</p>
-</dd>
-<dt>POSIX syntax [%c %c] belongs inside character classes in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-POSIX-syntax-_005b_0025c-_0025c_005d-belongs-inside-character-classes-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) The character class constructs [: :], [= =], and [. .] go
-<em>inside</em> character classes, the [] are part of the construct, for
example:
-/[012[:alpha:]345]/. Note that [= =] and [. .] are not currently
-implemented; they are simply placeholders for future extensions and
-will cause fatal errors. The <– HERE<!-- /@w --> shows
whereabouts in the regular
-expression the problem was discovered. See <a href="#perlre-NAME">perlre
NAME</a>.
-</p>
-</dd>
-<dt>POSIX syntax [. .] is reserved for future extensions in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-POSIX-syntax-_005b_002e-_002e_005d-is-reserved-for-future-extensions-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) Within regular expression character classes ([]) the syntax beginning
-with "[." and ending with ".]" is reserved for future
extensions. If you
-need to represent those character sequences inside a regular expression
-character class, just quote the square brackets with the backslash:
"\[."
-and ".\]". The <– HERE<!-- /@w --> shows whereabouts
in the regular expression the
-problem was discovered. See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>POSIX syntax [= =] is reserved for future extensions in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-POSIX-syntax-_005b_003d-_003d_005d-is-reserved-for-future-extensions-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) Within regular expression character classes ([]) the syntax beginning
-with "[=" and ending with "=]" is reserved for future
extensions. If you
-need to represent those character sequences inside a regular expression
-character class, just quote the square brackets with the backslash:
"\[="
-and "=\]". The <– HERE<!-- /@w --> shows whereabouts
in the regular expression the
-problem was discovered. See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Possible attempt to put comments in qw() list</dt>
-<dd><a
name="perldiag-Possible-attempt-to-put-comments-in-qw_0028_0029-list"></a>
-<p>(W qw) qw() lists contain items separated by whitespace; as with literal
-strings, comment characters are not ignored, but are instead treated as
-literal data. (You may have used different delimiters than the
-parentheses shown here; braces are also frequently used.)
-</p>
-<p>You probably wrote something like this:
-</p>
-<pre class="verbatim"> @list = qw(
- a # a comment
- b # another comment
- );
-</pre>
-<p>when you should have written this:
-</p>
-<pre class="verbatim"> @list = qw(
- a
- b
- );
-</pre>
-<p>If you really want comments, build your list the
-old-fashioned way, with quotes and commas:
-</p>
-<pre class="verbatim"> @list = (
- 'a', # a comment
- 'b', # another comment
- );
-</pre>
-</dd>
-<dt>Possible attempt to separate words with commas</dt>
-<dd><a name="perldiag-Possible-attempt-to-separate-words-with-commas"></a>
-<p>(W qw) qw() lists contain items separated by whitespace; therefore
-commas aren’t needed to separate the items. (You may have used
-different delimiters than the parentheses shown here; braces are also
-frequently used.)
-</p>
-<p>You probably wrote something like this:
-</p>
-<pre class="verbatim"> qw! a, b, c !;
-</pre>
-<p>which puts literal commas into some of the list items. Write it without
-commas if you don’t want them to appear in your data:
-</p>
-<pre class="verbatim"> qw! a b c !;
-</pre>
-</dd>
-<dt>Possible memory corruption: %s overflowed 3rd argument</dt>
-<dd><a
name="perldiag-Possible-memory-corruption_003a-_0025s-overflowed-3rd-argument"></a>
-<p>(F) An ioctl() or fcntl() returned more than Perl was bargaining for.
-Perl guesses a reasonable buffer size, but puts a sentinel byte at the
-end of the buffer just in case. This sentinel byte got clobbered, and
-Perl assumes that memory is now corrupted. See ‘perlfunc ioctl’.
-</p>
-</dd>
-<dt>Possible precedence issue with control flow operator</dt>
-<dd><a
name="perldiag-Possible-precedence-issue-with-control-flow-operator"></a>
-<p>(W syntax) There is a possible problem with the mixing of a control
-flow operator (e.g. <code>return</code>) and a low-precedence operator like
-<code>or</code>. Consider:
-</p>
-<pre class="verbatim"> sub { return $a or $b; }
-</pre>
-<p>This is parsed as:
-</p>
-<pre class="verbatim"> sub { (return $a) or $b; }
-</pre>
-<p>Which is effectively just:
-</p>
-<pre class="verbatim"> sub { return $a; }
-</pre>
-<p>Either use parentheses or the high-precedence variant of the operator.
-</p>
-<p>Note this may be also triggered for constructs like:
-</p>
-<pre class="verbatim"> sub { 1 if die; }
-</pre>
-</dd>
-<dt>Possible precedence problem on bitwise %s operator</dt>
-<dd><a
name="perldiag-Possible-precedence-problem-on-bitwise-_0025s-operator"></a>
-<p>(W precedence) Your program uses a bitwise logical operator in conjunction
-with a numeric comparison operator, like this :
-</p>
-<pre class="verbatim"> if ($x & $y == 0) { ... }
-</pre>
-<p>This expression is actually equivalent to <code>$x & ($y == 0)</code>,
due to the
-higher precedence of <code>==</code>. 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 <code>$x & ($y == 0)</code>).
-</p>
-</dd>
-<dt>Possible unintended interpolation of $\ in regex</dt>
-<dd><a
name="perldiag-Possible-unintended-interpolation-of-_0024_005c-in-regex"></a>
-<p>(W ambiguous) You said something like <code>m/$\/</code> in a regex.
-The regex <code>m/foo$\s+bar/m</code> translates to: match the word
’foo’, the output
-record separator (see <a href="#perlvar-_0024_005c">perlvar $\</a>) and the
letter ’s’ (one time or more)
-followed by the word ’bar’.
-</p>
-<p>If this is what you intended then you can silence the warning by using
-<code>m/${\}/</code> (for example: <code>m/foo${\}s+bar/</code>).
-</p>
-<p>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
-<code>m/$(?)\/</code> (for example: <code>m/foo$(?)\s+bar/</code>).
-</p>
-</dd>
-<dt>Possible unintended interpolation of %s in string</dt>
-<dd><a
name="perldiag-Possible-unintended-interpolation-of-_0025s-in-string"></a>
-<p>(W ambiguous) You said something like ’@foo’ in a double-quoted
string
-but there was no array <code>@foo</code> in scope at the time. If you wanted a
-literal @foo, then write it as address@hidden; otherwise find out what happened
-to the array you apparently lost track of.
-</p>
-</dd>
-<dt>Postfix dereference is experimental</dt>
-<dd><a name="perldiag-Postfix-dereference-is-experimental"></a>
-<p>(S experimental::postderef) This warning is emitted if you use
-the experimental postfix dereference syntax. Simply suppress the
-warning if you want to use the feature, but know that in doing
-so you are taking the risk of using an experimental feature which
-may change or be removed in a future Perl version:
-</p>
-<pre class="verbatim"> no warnings "experimental::postderef";
- use feature "postderef", "postderef_qq";
- $ref->$*;
- $aref->@*;
- $aref->@address@hidden;
- ... etc ...
-</pre>
-</dd>
-<dt>Precedence problem: open %s should be open(%s)</dt>
-<dd><a
name="perldiag-Precedence-problem_003a-open-_0025s-should-be-open_0028_0025s_0029"></a>
-<p>(S precedence) The old irregular construct
-</p>
-<pre class="verbatim"> open FOO || die;
-</pre>
-<p>is now misinterpreted as
-</p>
-<pre class="verbatim"> open(FOO || die);
-</pre>
-<p>because of the strict regularization of Perl 5’s grammar into unary
and
-list operators. (The old open was a little of both.) You must put
-parentheses around the filehandle, or use the new "or" operator
instead
-of "||".
-</p>
-</dd>
-<dt>Premature end of script headers</dt>
-<dd><a name="perldiag-Premature-end-of-script-headers"></a>
-<p>See Server error.
-</p>
-</dd>
-<dt>printf() on closed filehandle %s</dt>
-<dd><a name="perldiag-printf_0028_0029-on-closed-filehandle-_0025s"></a>
-<p>(W closed) The filehandle you’re writing to got itself closed sometime
-before now. Check your control flow.
-</p>
-</dd>
-<dt>print() on closed filehandle %s</dt>
-<dd><a name="perldiag-print_0028_0029-on-closed-filehandle-_0025s"></a>
-<p>(W closed) The filehandle you’re printing on got itself closed
sometime
-before now. Check your control flow.
-</p>
-</dd>
-<dt>Process terminated by SIG%s</dt>
-<dd><a name="perldiag-Process-terminated-by-SIG_0025s"></a>
-<p>(W) This is a standard message issued by OS/2 applications, while *nix
-applications die in silence. It is considered a feature of the OS/2
-port. One can easily disable this by appropriate sighandlers, see
-<a href="#perlipc-Signals">perlipc Signals</a>. See also "Process
terminated by SIGTERM/SIGINT"
-in <a href="perlos2.html#Top">(perlos2)</a>.
-</p>
-</dd>
-<dt>Property ’%s’ is unknown in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Property-_0027_0025s_0027-is-unknown-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The named property which you specified via <code>\p</code> or
<code>\P</code> is not one
-known to Perl. Perhaps you misspelled the name? See
-<a
href="perluniprops.html#Properties-accessible-through-_005cp_007b_007d-and-_005cP_007b_007d">(perluniprops)Properties
accessible through \p{} and \P{}</a>
-for a complete list of available official
-properties. If it is a <a
href="#perlunicode-User_002dDefined-Character-Properties">user-defined
property</a>
-it must have been defined by the time the regular expression is
-compiled.
-</p>
-</dd>
-<dt>Prototype after ’%c’ for %s : %s</dt>
-<dd><a
name="perldiag-Prototype-after-_0027_0025c_0027-for-_0025s-_003a-_0025s"></a>
-<p>(W illegalproto) A character follows % or @ in a prototype. This is
-useless, since % and @ gobble the rest of the subroutine arguments.
-</p>
-</dd>
-<dt>Prototype mismatch: %s vs %s</dt>
-<dd><a name="perldiag-Prototype-mismatch_003a-_0025s-vs-_0025s"></a>
-<p>(S prototype) The subroutine being declared or defined had previously been
-declared or defined with a different function prototype.
-</p>
-</dd>
-<dt>Prototype not terminated</dt>
-<dd><a name="perldiag-Prototype-not-terminated"></a>
-<p>(F) You’ve omitted the closing parenthesis in a function prototype
-definition.
-</p>
-</dd>
-<dt>Prototype ’%s’ overridden by attribute
’prototype(%s)’ in %s</dt>
-<dd><a
name="perldiag-Prototype-_0027_0025s_0027-overridden-by-attribute-_0027prototype_0028_0025s_0029_0027-in-_0025s"></a>
-<p>(W prototype) A prototype was declared in both the parentheses after
-the sub name and via the prototype attribute. The prototype in
-parentheses is useless, since it will be replaced by the prototype
-from the attribute before it’s ever used.
-</p>
-</dd>
-<dt>push on reference is experimental</dt>
-<dd><a name="perldiag-push-on-reference-is-experimental"></a>
-<p>(S experimental::autoderef) <code>push</code> with a scalar argument is
experimental
-and may change or be removed in a future Perl version. If you want to
-take the risk of using this feature, simply disable this warning:
-</p>
-<pre class="verbatim"> no warnings "experimental::autoderef";
-</pre>
-</dd>
-<dt>Quantifier follows nothing in regex; marked by <– HERE<!--
/@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Quantifier-follows-nothing-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You started a regular expression with a quantifier. Backslash it if
-you meant it literally. The <– HERE<!-- /@w --> shows
whereabouts in the regular
-expression the problem was discovered. See <a href="#perlre-NAME">perlre
NAME</a>.
-</p>
-</dd>
-<dt>Quantifier in {,} bigger than %d in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Quantifier-in-_007b_002c_007d-bigger-than-_0025d-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) There is currently a limit to the size of the min and max values of
-the {min,max} construct. The <– HERE<!-- /@w --> shows
whereabouts in the regular
-expression the problem was discovered. See <a href="#perlre-NAME">perlre
NAME</a>.
-</p>
-</dd>
-<dt>Quantifier {n,m} with n > m can’t match in regex</dt>
-<dd><a
name="perldiag-Quantifier-_007bn_002cm_007d-with-n-_003e-m-can_0027t-match-in-regex"></a>
-</dd>
-<dt>Quantifier {n,m} with n > m can’t match in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Quantifier-_007bn_002cm_007d-with-n-_003e-m-can_0027t-match-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) Minima should be less than or equal to maxima. If you really
-want your regexp to match something 0 times, just put {0}.
-</p>
-</dd>
-<dt>Quantifier unexpected on zero-length expression in regex m/%s/</dt>
-<dd><a
name="perldiag-Quantifier-unexpected-on-zero_002dlength-expression-in-regex-m_002f_0025s_002f"></a>
-<p>(W regexp) You applied a regular expression quantifier in a place where
-it makes no sense, such as on a zero-width assertion. Try putting the
-quantifier inside the assertion instead. For example, the way to match
-"abc" provided that it is followed by three repetitions of
"xyz" is
-<code>/abc(?=(?:xyz){3})/</code>, not <code>/abc(?=xyz){3}/</code>.
-</p>
-</dd>
-<dt>Range iterator outside integer range</dt>
-<dd><a name="perldiag-Range-iterator-outside-integer-range"></a>
-<p>(F) One (or both) of the numeric arguments to the range operator
".."
-are outside the range which can be represented by integers internally.
-One possible workaround is to force Perl to use magical string increment
-by prepending "0" to your numbers.
-</p>
-</dd>
-<dt>Ranges of ASCII printables should be some subset of "0-9",
"A-Z", or "a-z" in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Ranges-of-ASCII-printables-should-be-some-subset-of-_00220_002d9_0022_002c-_0022A_002dZ_0022_002c-or-_0022a_002dz_0022-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) (only under <code>use re 'strict'<!-- /@w --></code>
or within <code>(?[...])</code>)
-</p>
-<p>Stricter rules help to find typos and other errors. Perhaps you
didn’t
-even intend a range here, if the <code>"-"</code> was meant to be
some other
-character, or should have been escaped (like <code>"\-"</code>). If
you did
-intend a range, the one that was used is not portable between ASCII and
-EBCDIC platforms, and doesn’t have an obvious meaning to a casual
-reader.
-</p>
-<pre class="verbatim"> [3-7] # OK; Obvious and portable
- [d-g] # OK; Obvious and portable
- [A-Y] # OK; Obvious and portable
- [A-z] # WRONG; Not portable; not clear what is meant
- [a-Z] # WRONG; Not portable; not clear what is meant
- [%-.] # WRONG; Not portable; not clear what is meant
- [\x41-Z] # WRONG; Not portable; not obvious to non-geek
-</pre>
-<p>(You can force portability by specifying a Unicode range, which means that
-the endpoints are specified by
-<a href="#perlrecharclass-Character-Ranges"><code>\N{...}</code></a>, but the
meaning may
-still not be obvious.)
-The stricter rules require that ranges that start or stop with an ASCII
-character that is not a control have all their endpoints be the literal
-character, and not some escape sequence (like <code>"\x41"</code>),
and the ranges
-must be all digits, or all uppercase letters, or all lowercase letters.
-</p>
-</dd>
-<dt>Ranges of digits should be from the same group in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Ranges-of-digits-should-be-from-the-same-group-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) (only under <code>use re 'strict'<!-- /@w --></code>
or within <code>(?[...])</code>)
-</p>
-<p>Stricter rules help to find typos and other errors. You included a
-range, and at least one of the end points is a decimal digit. Under the
-stricter rules, when this happens, both end points should be digits in
-the same group of 10 consecutive digits.
-</p>
-</dd>
-<dt>readdir() attempted on invalid dirhandle %s</dt>
-<dd><a
name="perldiag-readdir_0028_0029-attempted-on-invalid-dirhandle-_0025s"></a>
-<p>(W io) The dirhandle you’re reading from is either closed or not
really
-a dirhandle. Check your control flow.
-</p>
-</dd>
-<dt>readline() on closed filehandle %s</dt>
-<dd><a name="perldiag-readline_0028_0029-on-closed-filehandle-_0025s"></a>
-<p>(W closed) The filehandle you’re reading from got itself closed
sometime
-before now. Check your control flow.
-</p>
-</dd>
-<dt>read() on closed filehandle %s</dt>
-<dd><a name="perldiag-read_0028_0029-on-closed-filehandle-_0025s"></a>
-<p>(W closed) You tried to read from a closed filehandle.
-</p>
-</dd>
-<dt>read() on unopened filehandle %s</dt>
-<dd><a name="perldiag-read_0028_0029-on-unopened-filehandle-_0025s"></a>
-<p>(W unopened) You tried to read from a filehandle that was never opened.
-</p>
-</dd>
-<dt>Reallocation too large: %x</dt>
-<dd><a name="perldiag-Reallocation-too-large_003a-_0025x"></a>
-<p>(F) You can’t allocate more than 64K on an MS-DOS machine.
-</p>
-</dd>
-<dt>realloc() of freed memory ignored</dt>
-<dd><a name="perldiag-realloc_0028_0029-of-freed-memory-ignored"></a>
-<p>(S malloc) An internal routine called realloc() on something that had
-already been freed.
-</p>
-</dd>
-<dt>Recompile perl with <strong>-D</strong>DEBUGGING to use
<strong>-D</strong> switch</dt>
-<dd><a
name="perldiag-Recompile-perl-with-_002dDDEBUGGING-to-use-_002dD-switch"></a>
-<p>(S debugging) You can’t use the <strong>-D</strong> option unless the
code to produce
-the desired output is compiled into Perl, which entails some overhead,
-which is why it’s currently left out of your copy.
-</p>
-</dd>
-<dt>Recursive call to Perl_load_module in PerlIO_find_layer</dt>
-<dd><a
name="perldiag-Recursive-call-to-Perl_005fload_005fmodule-in-PerlIO_005ffind_005flayer"></a>
-<p>(P) It is currently not permitted to load modules when creating
-a filehandle inside an %INC hook. This can happen with <code>open my
-$fh, '<', \$scalar</code>, which implicitly loads PerlIO::scalar. Try
-loading PerlIO::scalar explicitly first.
-</p>
-</dd>
-<dt>Recursive inheritance detected in package ’%s’</dt>
-<dd><a
name="perldiag-Recursive-inheritance-detected-in-package-_0027_0025s_0027"></a>
-<p>(F) While calculating the method resolution order (MRO) of a package, Perl
-believes it found an infinite loop in the <code>@ISA</code> hierarchy. This
is a
-crude check that bails out after 100 levels of <code>@ISA</code> depth.
-</p>
-</dd>
-<dt>Redundant argument in %s</dt>
-<dd><a name="perldiag-Redundant-argument-in-_0025s"></a>
-<p>(W redundant) You called a function with more arguments than other
-arguments you supplied indicated would be needed. Currently only
-emitted when a printf-type format required fewer arguments than were
-supplied, but might be used in the future for e.g. ‘perlfunc pack’.
-</p>
-</dd>
-<dt>refcnt_dec: fd %d%s</dt>
-<dd><a name="perldiag-refcnt_005fdec_003a-fd-_0025d_0025s"></a>
-</dd>
-<dt>refcnt: fd %d%s</dt>
-<dd><a name="perldiag-refcnt_003a-fd-_0025d_0025s"></a>
-</dd>
-<dt>refcnt_inc: fd %d%s</dt>
-<dd><a name="perldiag-refcnt_005finc_003a-fd-_0025d_0025s"></a>
-<p>(P) Perl’s I/O implementation failed an internal consistency check.
If
-you see this message, something is very wrong.
-</p>
-</dd>
-<dt>Reference found where even-sized list expected</dt>
-<dd><a name="perldiag-Reference-found-where-even_002dsized-list-expected"></a>
-<p>(W misc) You gave a single reference where Perl was expecting a list
-with an even number of elements (for assignment to a hash). This
-usually means that you used the anon hash constructor when you meant
-to use parens. In any case, a hash requires key/value <strong>pairs</strong>.
-</p>
-<pre class="verbatim"> %hash = { one => 1, two => 2, }; # WRONG
- %hash = [ qw/ an anon array / ]; # WRONG
- %hash = ( one => 1, two => 2, ); # right
- %hash = qw( one 1 two 2 ); # also fine
-</pre>
-</dd>
-<dt>Reference is already weak</dt>
-<dd><a name="perldiag-Reference-is-already-weak"></a>
-<p>(W misc) You have attempted to weaken a reference that is already weak.
-Doing so has no effect.
-</p>
-</dd>
-<dt>Reference to invalid group 0 in regex; marked by <– HERE<!--
/@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Reference-to-invalid-group-0-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You used <code>\g0</code> or similar in a regular expression. You may
refer
-to capturing parentheses only with strictly positive integers
-(normal backreferences) or with strictly negative integers (relative
-backreferences). Using 0 does not make sense.
-</p>
-</dd>
-<dt>Reference to nonexistent group in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Reference-to-nonexistent-group-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You used something like <code>\7</code> 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 ordinal 7 inserted into the regular
-expression, prepend zeroes to make it three digits long: <code>\007</code>
-</p>
-<p>The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the problem was
-discovered.
-</p>
-</dd>
-<dt>Reference to nonexistent named group in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Reference-to-nonexistent-named-group-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You used something like <code>\k'NAME'</code> or
<code>\k<NAME></code> in your regular
-expression, but there is no corresponding named capturing parentheses
-such as <code>(?'NAME'...)</code> or <code>(?<NAME>...)</code>. Check
if the name has been
-spelled correctly both in the backreference and the declaration.
-</p>
-<p>The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the problem was
-discovered.
-</p>
-</dd>
-<dt>Reference to nonexistent or unclosed group in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Reference-to-nonexistent-or-unclosed-group-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You used something like <code>\g{-7}</code> in your regular expression,
but there
-are not at least seven sets of closed capturing parentheses in the
-expression before where the <code>\g{-7}</code> was located.
-</p>
-<p>The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the problem was
-discovered.
-</p>
-</dd>
-<dt>regexp memory corruption</dt>
-<dd><a name="perldiag-regexp-memory-corruption"></a>
-<p>(P) The regular expression engine got confused by what the regular
-expression compiler gave it.
-</p>
-</dd>
-<dt>Regexp modifier "/%c" may appear a maximum of twice</dt>
-<dd><a
name="perldiag-Regexp-modifier-_0022_002f_0025c_0022-may-appear-a-maximum-of-twice"></a>
-</dd>
-<dt>Regexp modifier "%c" may appear a maximum of twice in regex;
marked by <– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Regexp-modifier-_0022_0025c_0022-may-appear-a-maximum-of-twice-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The regular expression pattern had too many occurrences
-of the specified modifier. Remove the extraneous ones.
-</p>
-</dd>
-<dt>Regexp modifier "%c" may not appear after the "-" in
regex; marked by <– HERE in m/%s/</dt>
-<dd><a
name="perldiag-Regexp-modifier-_0022_0025c_0022-may-not-appear-after-the-_0022_002d_0022-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) Turning off the given modifier has the side effect of turning on
-another one. Perl currently doesn’t allow this. Reword the regular
-expression to use the modifier you want to turn on (and place it before
-the minus), instead of the one you want to turn off.
-</p>
-</dd>
-<dt>Regexp modifier "/%c" may not appear twice</dt>
-<dd><a
name="perldiag-Regexp-modifier-_0022_002f_0025c_0022-may-not-appear-twice"></a>
-</dd>
-<dt>Regexp modifier "%c" may not appear twice in regex; marked by
<– HERE in m/%s/</dt>
-<dd><a
name="perldiag-Regexp-modifier-_0022_0025c_0022-may-not-appear-twice-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The regular expression pattern had too many occurrences
-of the specified modifier. Remove the extraneous ones.
-</p>
-</dd>
-<dt>Regexp modifiers "/%c" and "/%c" are mutually
exclusive</dt>
-<dd><a
name="perldiag-Regexp-modifiers-_0022_002f_0025c_0022-and-_0022_002f_0025c_0022-are-mutually-exclusive"></a>
-</dd>
-<dt>Regexp modifiers "%c" and "%c" are mutually exclusive
in regex; marked by <– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Regexp-modifiers-_0022_0025c_0022-and-_0022_0025c_0022-are-mutually-exclusive-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The regular expression pattern had more than one of these
-mutually exclusive modifiers. Retain only the modifier that is
-supposed to be there.
-</p>
-</dd>
-<dt>Regexp out of space in regex m/%s/</dt>
-<dd><a name="perldiag-Regexp-out-of-space-in-regex-m_002f_0025s_002f"></a>
-<p>(P) A "can’t happen" error, because safemalloc() should
have caught it
-earlier.
-</p>
-</dd>
-<dt>Repeated format line will never terminate (~~ and @#)</dt>
-<dd><a
name="perldiag-Repeated-format-line-will-never-terminate-_0028_007e_007e-and-_0040_0023_0029"></a>
-<p>(F) Your format contains the ~~ repeat-until-blank sequence and a
-numeric field that will never go blank so that the repetition never
-terminates. You might use ^# instead. See <a href="#perlform-NAME">perlform
NAME</a>.
-</p>
-</dd>
-<dt>Replacement list is longer than search list</dt>
-<dd><a name="perldiag-Replacement-list-is-longer-than-search-list"></a>
-<p>(W misc) You have used a replacement list that is longer than the
-search list. So the additional elements in the replacement list
-are meaningless.
-</p>
-</dd>
-<dt>’%s’ resolved to ’\o{%s}%d’</dt>
-<dd><a
name="perldiag-_0027_0025s_0027-resolved-to-_0027_005co_007b_0025s_007d_0025d_0027"></a>
-<p>(W misc, regexp) You wrote something like <code>\08</code>, or
<code>\179</code> in a
-double-quotish string. All but the last digit is treated as a single
-character, specified in octal. The last digit is the next character in
-the string. To tell Perl that this is indeed what you want, you can use
-the <code>\o{ }</code> syntax, or use exactly three digits to specify the octal
-for the character.
-</p>
-</dd>
-<dt>Reversed %s= operator</dt>
-<dd><a name="perldiag-Reversed-_0025s_003d-operator"></a>
-<p>(W syntax) You wrote your assignment operator backwards. The = must
-always come last, to avoid ambiguity with subsequent unary operators.
-</p>
-</dd>
-<dt>rewinddir() attempted on invalid dirhandle %s</dt>
-<dd><a
name="perldiag-rewinddir_0028_0029-attempted-on-invalid-dirhandle-_0025s"></a>
-<p>(W io) The dirhandle you tried to do a rewinddir() on is either closed
-or not really a dirhandle. Check your control flow.
-</p>
-</dd>
-<dt>Scalars leaked: %d</dt>
-<dd><a name="perldiag-Scalars-leaked_003a-_0025d"></a>
-<p>(S internal) Something went wrong in Perl’s internal bookkeeping
-of scalars: not all scalar variables were deallocated by the time
-Perl exited. What this usually indicates is a memory leak, which
-is of course bad, especially if the Perl program is intended to be
-long-running.
-</p>
-</dd>
-<dt>Scalar value @%s[%s] better written as $%s[%s]</dt>
-<dd><a
name="perldiag-Scalar-value-_0040_0025s_005b_0025s_005d-better-written-as-_0024_0025s_005b_0025s_005d"></a>
-<p>(W syntax) You’ve used an array slice (indicated by @) to select a
-single element of an array. Generally it’s better to ask for a scalar
-value (indicated by $). The difference is that <code>$foo[&bar]</code>
always
-behaves like a scalar, both when assigning to it and when evaluating its
-argument, while <code>@foo[&bar]</code> behaves like a list when you
assign to it,
-and provides a list context to its subscript, which can do weird things
-if you’re expecting only one subscript.
-</p>
-<p>On the other hand, if you were actually hoping to treat the array
-element as a list, you need to look into how references work, because
-Perl will not magically convert between scalars and lists for you. See
-<a href="#perlref-NAME">perlref NAME</a>.
-</p>
-</dd>
-<dt>Scalar value @%s{%s} better written as $%s{%s}</dt>
-<dd><a
name="perldiag-Scalar-value-_0040_0025s_007b_0025s_007d-better-written-as-_0024_0025s_007b_0025s_007d"></a>
-<p>(W syntax) You’ve used a hash slice (indicated by @) to select a
single
-element of a hash. Generally it’s better to ask for a scalar value
-(indicated by $). The difference is that <code>$foo{&bar}</code> always
behaves
-like a scalar, both when assigning to it and when evaluating its
-argument, while <code>@foo{&bar}</code> behaves like a list when you
assign to it,
-and provides a list context to its subscript, which can do weird things
-if you’re expecting only one subscript.
-</p>
-<p>On the other hand, if you were actually hoping to treat the hash element
-as a list, you need to look into how references work, because Perl will
-not magically convert between scalars and lists for you. See
-<a href="#perlref-NAME">perlref NAME</a>.
-</p>
-</dd>
-<dt>Search pattern not terminated</dt>
-<dd><a name="perldiag-Search-pattern-not-terminated"></a>
-<p>(F) The lexer couldn’t find the final delimiter of a // or m{}
-construct. Remember that bracketing delimiters count nesting level.
-Missing the leading <code>$</code> from a variable <code>$m</code> may cause
this error.
-</p>
-<p>Note that since Perl 5.10.0 a // can also be the <em>defined-or</em>
-construct, not just the empty search pattern. Therefore code written
-in Perl 5.10.0 or later that uses the // as the <em>defined-or</em> can be
-misparsed by pre-5.10.0 Perls as a non-terminated search pattern.
-</p>
-</dd>
-<dt>seekdir() attempted on invalid dirhandle %s</dt>
-<dd><a
name="perldiag-seekdir_0028_0029-attempted-on-invalid-dirhandle-_0025s"></a>
-<p>(W io) The dirhandle you are doing a seekdir() on is either closed or not
-really a dirhandle. Check your control flow.
-</p>
-</dd>
-<dt>%sseek() on unopened filehandle</dt>
-<dd><a name="perldiag-_0025sseek_0028_0029-on-unopened-filehandle"></a>
-<p>(W unopened) You tried to use the seek() or sysseek() function on a
-filehandle that was either never opened or has since been closed.
-</p>
-</dd>
-<dt>select not implemented</dt>
-<dd><a name="perldiag-select-not-implemented"></a>
-<p>(F) This machine doesn’t implement the select() system call.
-</p>
-</dd>
-<dt>Self-ties of arrays and hashes are not supported</dt>
-<dd><a
name="perldiag-Self_002dties-of-arrays-and-hashes-are-not-supported"></a>
-<p>(F) Self-ties are of arrays and hashes are not supported in
-the current implementation.
-</p>
-</dd>
-<dt>Semicolon seems to be missing</dt>
-<dd><a name="perldiag-Semicolon-seems-to-be-missing"></a>
-<p>(W semicolon) A nearby syntax error was probably caused by a missing
-semicolon, or possibly some other missing operator, such as a comma.
-</p>
-</dd>
-<dt>semi-panic: attempt to dup freed string</dt>
-<dd><a name="perldiag-semi_002dpanic_003a-attempt-to-dup-freed-string"></a>
-<p>(S internal) The internal newSVsv() routine was called to duplicate a
-scalar that had previously been marked as free.
-</p>
-</dd>
-<dt>sem%s not implemented</dt>
-<dd><a name="perldiag-sem_0025s-not-implemented"></a>
-<p>(F) You don’t have System V semaphore IPC on your system.
-</p>
-</dd>
-<dt>send() on closed socket %s</dt>
-<dd><a name="perldiag-send_0028_0029-on-closed-socket-_0025s"></a>
-<p>(W closed) The socket you’re sending to got itself closed sometime
-before now. Check your control flow.
-</p>
-</dd>
-<dt>Sequence "\c{" invalid</dt>
-<dd><a name="perldiag-Sequence-_0022_005cc_007b_0022-invalid"></a>
-<p>(F) These three characters may not appear in sequence in a
-double-quotish context. This message is raised only on non-ASCII
-platforms (a different error message is output on ASCII ones). If you
-were intending to specify a control character with this sequence, you’ll
-have to use a different way to specify it.
-</p>
-</dd>
-<dt>Sequence (? incomplete in regex; marked by <– HERE<!-- /@w
--> in m/%s/</dt>
-<dd><a
name="perldiag-Sequence-_0028_003f-incomplete-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) A regular expression ended with an incomplete extension (?. The
-<– HERE<!-- /@w --> shows whereabouts in the regular expression
the problem was
-discovered. See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Sequence (?%c...) not implemented in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Sequence-_0028_003f_0025c_002e_002e_002e_0029-not-implemented-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) A proposed regular expression extension has the character reserved
-but has not yet been written. The <– HERE<!-- /@w --> shows
whereabouts in the
-regular expression the problem was discovered. See <a
href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Sequence (?%s...) not recognized in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Sequence-_0028_003f_0025s_002e_002e_002e_0029-not-recognized-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You used a regular expression extension that doesn’t make sense.
-The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the problem was
-discovered. This may happen when using the <code>(?^...)</code> construct to
tell
-Perl to use the default regular expression modifiers, and you
-redundantly specify a default modifier. For other
-causes, see <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Sequence (?#... not terminated in regex m/%s/</dt>
-<dd><a
name="perldiag-Sequence-_0028_003f_0023_002e_002e_002e-not-terminated-in-regex-m_002f_0025s_002f"></a>
-<p>(F) A regular expression comment must be terminated by a closing
-parenthesis. Embedded parentheses aren’t allowed. See
-<a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Sequence (?&... not terminated in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Sequence-_0028_003f_0026_002e_002e_002e-not-terminated-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) A named reference of the form <code>(?&...)</code> was missing the
final
-closing parenthesis after the name. The <– HERE<!-- /@w -->
shows whereabouts
-in the regular expression the problem was discovered.
-</p>
-</dd>
-<dt>Sequence (?%c... not terminated in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Sequence-_0028_003f_0025c_002e_002e_002e-not-terminated-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) A named group of the form <code>(?'...')</code> or
<code>(?<...>)</code> was missing the final
-closing quote or angle bracket. The <– HERE<!-- /@w --> shows
whereabouts in the
-regular expression the problem was discovered.
-</p>
-</dd>
-<dt>Sequence (?(%c... not terminated in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Sequence-_0028_003f_0028_0025c_002e_002e_002e-not-terminated-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) A named reference of the form <code>(?('...')...)</code> or
<code>(?(<...>)...)</code> was
-missing the final closing quote or angle bracket after the name. The
-<– HERE<!-- /@w --> shows whereabouts in the regular expression
the problem was
-discovered.
-</p>
-</dd>
-<dt>Sequence (?... not terminated in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Sequence-_0028_003f_002e_002e_002e-not-terminated-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) There was no matching closing parenthesis for the ’(’. The
-<– HERE<!-- /@w --> shows whereabouts in the regular expression
the problem was
-discovered.
-</p>
-</dd>
-<dt>Sequence \%s... not terminated in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Sequence-_005c_0025s_002e_002e_002e-not-terminated-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The regular expression expects a mandatory argument following the escape
-sequence and this has been omitted or incorrectly written.
-</p>
-</dd>
-<dt>Sequence (?{...}) not terminated with ’)’</dt>
-<dd><a
name="perldiag-Sequence-_0028_003f_007b_002e_002e_002e_007d_0029-not-terminated-with-_0027_0029_0027"></a>
-<p>(F) The end of the perl code contained within the {...} must be
-followed immediately by a ’)’.
-</p>
-</dd>
-<dt>Sequence ?P=... not terminated in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Sequence-_003fP_003d_002e_002e_002e-not-terminated-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) A named reference of the form <code>(?P=...)</code> was missing the
final
-closing parenthesis after the name. The <– HERE<!-- /@w -->
shows whereabouts
-in the regular expression the problem was discovered.
-</p>
-</dd>
-<dt>Sequence (?R) not terminated in regex m/%s/</dt>
-<dd><a
name="perldiag-Sequence-_0028_003fR_0029-not-terminated-in-regex-m_002f_0025s_002f"></a>
-<p>(F) An <code>(?R)</code> or <code>(?0)</code> sequence in a regular
expression was missing the
-final parenthesis.
-</p>
-</dd>
-<dt>Server error (a.k.a. "500 Server error")</dt>
-<dd><a
name="perldiag-Server-error-_0028a_002ek_002ea_002e-_0022500-Server-error_0022_0029"></a>
-<p>(A) This is the error message generally seen in a browser window
-when trying to run a CGI program (including SSI) over the web. The
-actual error text varies widely from server to server. The most
-frequently-seen variants are "500 Server error", "Method
(something)
-not permitted", "Document contains no data", "Premature
end of script
-headers", and "Did not produce a valid header".
-</p>
-<p><strong>This is a CGI error, not a Perl error</strong>.
-</p>
-<p>You need to make sure your script is executable, is accessible by
-the user CGI is running the script under (which is probably not the
-user account you tested it under), does not rely on any environment
-variables (like PATH) from the user it isn’t running under, and
isn’t
-in a location where the CGI server can’t find it, basically, more or
-less. Please see the following for more information:
-</p>
-<pre class="verbatim"> http://www.perl.org/CGI_MetaFAQ.html
- http://www.htmlhelp.org/faq/cgifaq.html
- http://www.w3.org/Security/Faq/
-</pre>
-<p>You should also look at <a href="perlfaq9.html#Top">(perlfaq9)</a>.
-</p>
-</dd>
-<dt>setegid() not implemented</dt>
-<dd><a name="perldiag-setegid_0028_0029-not-implemented"></a>
-<p>(F) You tried to assign to <code>$)</code>, and your operating system
doesn’t
-support the setegid() system call (or equivalent), or at least Configure
-didn’t think so.
-</p>
-</dd>
-<dt>seteuid() not implemented</dt>
-<dd><a name="perldiag-seteuid_0028_0029-not-implemented"></a>
-<p>(F) You tried to assign to <code>$></code>, and your operating system
doesn’t
-support the seteuid() system call (or equivalent), or at least Configure
-didn’t think so.
-</p>
-</dd>
-<dt>setpgrp can’t take arguments</dt>
-<dd><a name="perldiag-setpgrp-can_0027t-take-arguments"></a>
-<p>(F) Your system has the setpgrp() from BSD 4.2, which takes no
-arguments, unlike POSIX setpgid(), which takes a process ID and process
-group ID.
-</p>
-</dd>
-<dt>setrgid() not implemented</dt>
-<dd><a name="perldiag-setrgid_0028_0029-not-implemented"></a>
-<p>(F) You tried to assign to <code>$(</code>, and your operating system
doesn’t
-support the setrgid() system call (or equivalent), or at least Configure
-didn’t think so.
-</p>
-</dd>
-<dt>setruid() not implemented</dt>
-<dd><a name="perldiag-setruid_0028_0029-not-implemented"></a>
-<p>(F) You tried to assign to <code>$<</code>, and your operating system
doesn’t
-support the setruid() system call (or equivalent), or at least Configure
-didn’t think so.
-</p>
-</dd>
-<dt>setsockopt() on closed socket %s</dt>
-<dd><a name="perldiag-setsockopt_0028_0029-on-closed-socket-_0025s"></a>
-<p>(W closed) You tried to set a socket option on a closed socket. Did you
-forget to check the return value of your socket() call? See
-‘perlfunc setsockopt’.
-</p>
-</dd>
-<dt>Setting ${^ENCODING} is deprecated</dt>
-<dd><a name="perldiag-Setting-_0024_007b_005eENCODING_007d-is-deprecated"></a>
-<p>(D deprecated) You assigned a non-<code>undef</code> value to
<code>${^ENCODING}</code>.
-This is deprecated; see <code><a
href="#perlvar-_0024_007b_005eENCODING_007d">perlvar ${^ENCODING}</a></code>
for details.
-</p>
-</dd>
-<dt>Setting $/ to a reference to %s as a form of slurp is deprecated, treating
as undef</dt>
-<dd><a
name="perldiag-Setting-_0024_002f-to-a-reference-to-_0025s-as-a-form-of-slurp-is-deprecated_002c-treating-as-undef"></a>
-<p>(D deprecated) You assigned a reference to a scalar to <code>$/</code>
where the
-referenced item is not a positive integer. In older perls this
<strong>appeared</strong>
-to work the same as setting it to <code>undef</code> but was in fact internally
-different, less efficient and with very bad luck could have resulted in
-your file being split by a stringified form of the reference.
-</p>
-<p>In Perl 5.20.0 this was changed so that it would be
<strong>exactly</strong> the same as
-setting <code>$/</code> to undef, with the exception that this warning would be
-thrown.
-</p>
-<p>You are recommended to change your code to set <code>$/</code> to
<code>undef</code> explicitly
-if you wish to slurp the file. In future versions of Perl assigning
-a reference to will throw a fatal error.
-</p>
-</dd>
-<dt>Setting $/ to %s reference is forbidden</dt>
-<dd><a name="perldiag-Setting-_0024_002f-to-_0025s-reference-is-forbidden"></a>
-<p>(F) You tried to assign a reference to a non integer to <code>$/</code>.
In older
-Perls this would have behaved similarly to setting it to a reference to
-a positive integer, where the integer was the address of the reference.
-As of Perl 5.20.0 this is a fatal error, to allow future versions of Perl
-to use non-integer refs for more interesting purposes.
-</p>
-</dd>
-<dt>shift on reference is experimental</dt>
-<dd><a name="perldiag-shift-on-reference-is-experimental"></a>
-<p>(S experimental::autoderef) <code>shift</code> with a scalar argument is
experimental
-and may change or be removed in a future Perl version. If you want to
-take the risk of using this feature, simply disable this warning:
-</p>
-<pre class="verbatim"> no warnings "experimental::autoderef";
-</pre>
-</dd>
-<dt>shm%s not implemented</dt>
-<dd><a name="perldiag-shm_0025s-not-implemented"></a>
-<p>(F) You don’t have System V shared memory IPC on your system.
-</p>
-</dd>
-<dt>!=~ should be !~</dt>
-<dd><a name="perldiag-_0021_003d_007e-should-be-_0021_007e"></a>
-<p>(W syntax) The non-matching operator is !~, not !=~. !=~ will be
-interpreted as the != (numeric not equal) and ~ (1’s complement)
-operators: probably not what you intended.
-</p>
-</dd>
-<dt>/%s/ should probably be written as "%s"</dt>
-<dd><a
name="perldiag-_002f_0025s_002f-should-probably-be-written-as-_0022_0025s_0022"></a>
-<p>(W syntax) You have used a pattern where Perl expected to find a string,
-as in the first argument to <code>join</code>. Perl will treat the true or
false
-result of matching the pattern against $_ as the string, which is
-probably not what you had in mind.
-</p>
-</dd>
-<dt>shutdown() on closed socket %s</dt>
-<dd><a name="perldiag-shutdown_0028_0029-on-closed-socket-_0025s"></a>
-<p>(W closed) You tried to do a shutdown on a closed socket. Seems a bit
-superfluous.
-</p>
-</dd>
-<dt>SIG%s handler "%s" not defined</dt>
-<dd><a name="perldiag-SIG_0025s-handler-_0022_0025s_0022-not-defined"></a>
-<p>(W signal) The signal handler named in %SIG doesn’t, in fact, exist.
-Perhaps you put it into the wrong package?
-</p>
-</dd>
-<dt>Slab leaked from cv %p</dt>
-<dd><a name="perldiag-Slab-leaked-from-cv-_0025p"></a>
-<p>(S) If you see this message, then something is seriously wrong with the
-internal bookkeeping of op trees. An op tree needed to be freed after
-a compilation error, but could not be found, so it was leaked instead.
-</p>
-</dd>
-<dt>sleep(%u) too large</dt>
-<dd><a name="perldiag-sleep_0028_0025u_0029-too-large"></a>
-<p>(W overflow) You called <code>sleep</code> with a number that was larger
than
-it can reliably handle and <code>sleep</code> probably slept for less time than
-requested.
-</p>
-</dd>
-<dt>Slurpy parameter not last</dt>
-<dd><a name="perldiag-Slurpy-parameter-not-last"></a>
-<p>(F) In a subroutine signature, you put something after a slurpy (array or
-hash) parameter. The slurpy parameter takes all the available arguments,
-so there can’t be any left to fill later parameters.
-</p>
-</dd>
-<dt>Smart matching a non-overloaded object breaks encapsulation</dt>
-<dd><a
name="perldiag-Smart-matching-a-non_002doverloaded-object-breaks-encapsulation"></a>
-<p>(F) You should not use the <code>~~</code> operator on an object that does
not
-overload it: Perl refuses to use the object’s underlying structure
-for the smart match.
-</p>
-</dd>
-<dt>Smartmatch is experimental</dt>
-<dd><a name="perldiag-Smartmatch-is-experimental"></a>
-<p>(S experimental::smartmatch) This warning is emitted if you
-use the smartmatch (<code>~~</code>) operator. This is currently an
experimental
-feature, and its details are subject to change in future releases of
-Perl. Particularly, its current behavior is noticed for being
-unnecessarily complex and unintuitive, and is very likely to be
-overhauled.
-</p>
-</dd>
-<dt>sort is now a reserved word</dt>
-<dd><a name="perldiag-sort-is-now-a-reserved-word"></a>
-<p>(F) An ancient error message that almost nobody ever runs into anymore.
-But before sort was a keyword, people sometimes used it as a filehandle.
-</p>
-</dd>
-<dt>Sort subroutine didn’t return single value</dt>
-<dd><a name="perldiag-Sort-subroutine-didn_0027t-return-single-value"></a>
-<p>(F) A sort comparison subroutine written in XS must return exactly one
-item. See ‘perlfunc sort’.
-</p>
-</dd>
-<dt>Source filters apply only to byte streams</dt>
-<dd><a name="perldiag-Source-filters-apply-only-to-byte-streams"></a>
-<p>(F) You tried to activate a source filter (usually by loading a
-source filter module) within a string passed to <code>eval</code>. This is
-not permitted under the <code>unicode_eval</code> feature. Consider using
-<code>evalbytes</code> instead. See <a href="feature.html#Top">(feature)</a>.
-</p>
-</dd>
-<dt>splice() offset past end of array</dt>
-<dd><a name="perldiag-splice_0028_0029-offset-past-end-of-array"></a>
-<p>(W misc) You attempted to specify an offset that was past the end of
-the array passed to splice(). Splicing will instead commence at the
-end of the array, rather than past it. If this isn’t what you want,
-try explicitly pre-extending the array by assigning $#array = $offset.
-See ‘perlfunc splice’.
-</p>
-</dd>
-<dt>splice on reference is experimental</dt>
-<dd><a name="perldiag-splice-on-reference-is-experimental"></a>
-<p>(S experimental::autoderef) <code>splice</code> with a scalar argument
-is experimental and may change or be removed in a future
-Perl version. If you want to take the risk of using this
-feature, simply disable this warning:
-</p>
-<pre class="verbatim"> no warnings "experimental::autoderef";
-</pre>
-</dd>
-<dt>Split loop</dt>
-<dd><a name="perldiag-Split-loop"></a>
-<p>(P) The split was looping infinitely. (Obviously, a split shouldn’t
-iterate more times than there are characters of input, which is what
-happened.) See <a href="#perlfunc-split">perlfunc split</a>.
-</p>
-</dd>
-<dt>Statement unlikely to be reached</dt>
-<dd><a name="perldiag-Statement-unlikely-to-be-reached"></a>
-<p>(W exec) You did an exec() with some statement after it other than a
-die(). This is almost always an error, because exec() never returns
-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.
-</p>
-</dd>
-<dt>"state" subroutine %s can’t be in a package</dt>
-<dd><a
name="perldiag-_0022state_0022-subroutine-_0025s-can_0027t-be-in-a-package"></a>
-<p>(F) Lexically scoped subroutines aren’t in a package, so it
doesn’t make
-sense to try to declare one with a package qualifier on the front.
-</p>
-</dd>
-<dt>"state %s" used in sort comparison</dt>
-<dd><a name="perldiag-_0022state-_0025s_0022-used-in-sort-comparison"></a>
-<p>(W syntax) The package variables $a and $b are used for sort comparisons.
-You used $a or $b in as an operand to the <code><=></code> or
<code>cmp</code> operator inside a
-sort comparison block, and the variable had earlier been declared as a
-lexical variable. Either qualify the sort variable with the package
-name, or rename the lexical variable.
-</p>
-</dd>
-<dt>"state" variable %s can’t be in a package</dt>
-<dd><a
name="perldiag-_0022state_0022-variable-_0025s-can_0027t-be-in-a-package"></a>
-<p>(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.
-</p>
-</dd>
-<dt>stat() on unopened filehandle %s</dt>
-<dd><a name="perldiag-stat_0028_0029-on-unopened-filehandle-_0025s"></a>
-<p>(W unopened) You tried to use the stat() function on a filehandle that
-was either never opened or has since been closed.
-</p>
-</dd>
-<dt>Strings with code points over 0xFF may not be mapped into in-memory file
handles</dt>
-<dd><a
name="perldiag-Strings-with-code-points-over-0xFF-may-not-be-mapped-into-in_002dmemory-file-handles"></a>
-<p>(W utf8) You tried to open a reference to a scalar for read or append
-where the scalar contained code points over 0xFF. In-memory files
-model on-disk files and can only contain bytes.
-</p>
-</dd>
-<dt>Stub found while resolving method "%s" overloading
"%s" in package "%s"</dt>
-<dd><a
name="perldiag-Stub-found-while-resolving-method-_0022_0025s_0022-overloading-_0022_0025s_0022-in-package-_0022_0025s_0022"></a>
-<p>(P) Overloading resolution over @ISA tree may be broken by importation
-stubs. Stubs should never be implicitly created, but explicit calls to
-<code>can</code> may break this.
-</p>
-</dd>
-<dt>Subroutine "&%s" is not available</dt>
-<dd><a name="perldiag-Subroutine-_0022_0026_0025s_0022-is-not-available"></a>
-<p>(W closure) During compilation, an inner named subroutine or eval is
-attempting to capture an outer lexical subroutine that is not currently
-available. This can happen for one of two reasons. First, the lexical
-subroutine may be declared in an outer anonymous subroutine that has
-not yet been created. (Remember that named subs are created at compile
-time, while anonymous subs are created at run-time.) For example,
-</p>
-<pre class="verbatim"> sub { my sub a {...} sub f { \&a } }
-</pre>
-<p>At the time that f is created, it can’t capture the current
"a" sub,
-since the anonymous subroutine hasn’t been created yet. Conversely, the
-following won’t give a warning since the anonymous subroutine has by now
-been created and is live:
-</p>
-<pre class="verbatim"> sub { my sub a {...} eval 'sub f { \&a }'
}->();
-</pre>
-<p>The second situation is caused by an eval accessing a lexical subroutine
-that has gone out of scope, for example,
-</p>
-<pre class="verbatim"> sub f {
- my sub a {...}
- sub { eval '\&a' }
- }
- f()->();
-</pre>
-<p>Here, when the ’\&a’ in the eval is being compiled, f() is
not currently
-being executed, so its &a is not available for capture.
-</p>
-</dd>
-<dt>"%s" subroutine &%s masks earlier declaration in same %s</dt>
-<dd><a
name="perldiag-_0022_0025s_0022-subroutine-_0026_0025s-masks-earlier-declaration-in-same-_0025s"></a>
-<p>(W misc) A "my" or "state" subroutine has been
redeclared in the
-current scope or statement, effectively eliminating all access to
-the previous instance. This is almost always a typographical error.
-Note that the earlier subroutine will still exist until the end of
-the scope or until all closure references to it are destroyed.
-</p>
-</dd>
-<dt>Subroutine %s redefined</dt>
-<dd><a name="perldiag-Subroutine-_0025s-redefined"></a>
-<p>(W redefine) You redefined a subroutine. To suppress this warning, say
-</p>
-<pre class="verbatim"> {
- no warnings 'redefine';
- eval "sub name { ... }";
- }
-</pre>
-</dd>
-<dt>Subroutine "%s" will not stay shared</dt>
-<dd><a name="perldiag-Subroutine-_0022_0025s_0022-will-not-stay-shared"></a>
-<p>(W closure) An inner (nested) <em>named</em> subroutine is referencing a
"my"
-subroutine defined in an outer named subroutine.
-</p>
-<p>When the inner subroutine is called, it will see the value of the outer
-subroutine’s lexical subroutine as it was before and during the *first*
-call to the outer subroutine; in this case, after the first call to the
-outer subroutine is complete, the inner and outer subroutines will no
-longer share a common value for the lexical subroutine. In other words,
-it will no longer be shared. This will especially make a difference
-if the lexical subroutines accesses lexical variables declared in its
-surrounding scope.
-</p>
-<p>This problem can usually be solved by making the inner subroutine
-anonymous, using the <code>sub {}</code> syntax. When inner anonymous subs
that
-reference lexical subroutines in outer subroutines are created, they
-are automatically rebound to the current values of such lexical subs.
-</p>
-</dd>
-<dt>Substitution loop</dt>
-<dd><a name="perldiag-Substitution-loop"></a>
-<p>(P) The substitution was looping infinitely. (Obviously, a substitution
-shouldn’t iterate more times than there are characters of input, which
-is what happened.) See the discussion of substitution in
-<a href="#perlop-Regexp-Quote_002dLike-Operators">perlop Regexp Quote-Like
Operators</a>.
-</p>
-</dd>
-<dt>Substitution pattern not terminated</dt>
-<dd><a name="perldiag-Substitution-pattern-not-terminated"></a>
-<p>(F) The lexer couldn’t find the interior delimiter of an s/// or s{}{}
-construct. Remember that bracketing delimiters count nesting level.
-Missing the leading <code>$</code> from variable <code>$s</code> may cause
this error.
-</p>
-</dd>
-<dt>Substitution replacement not terminated</dt>
-<dd><a name="perldiag-Substitution-replacement-not-terminated"></a>
-<p>(F) The lexer couldn’t find the final delimiter of an s/// or s{}{}
-construct. Remember that bracketing delimiters count nesting level.
-Missing the leading <code>$</code> from variable <code>$s</code> may cause
this error.
-</p>
-</dd>
-<dt>substr outside of string</dt>
-<dd><a name="perldiag-substr-outside-of-string"></a>
-<p>(W substr)(F) You tried to reference a substr() that pointed outside of
-a string. That is, the absolute value of the offset was larger than the
-length of the string. See ‘perlfunc substr’. This warning is
fatal if
-substr is used in an lvalue context (as the left hand side of an
-assignment or as a subroutine argument for example).
-</p>
-</dd>
-<dt>sv_upgrade from type %d down to type %d</dt>
-<dd><a name="perldiag-sv_005fupgrade-from-type-_0025d-down-to-type-_0025d"></a>
-<p>(P) Perl tried to force the upgrade of an SV to a type which was actually
-inferior to its current type.
-</p>
-</dd>
-<dt>SWASHNEW didn’t return an HV ref</dt>
-<dd><a name="perldiag-SWASHNEW-didn_0027t-return-an-HV-ref"></a>
-<p>(P) Something went wrong internally when Perl was trying to look up
-Unicode characters.
-</p>
-</dd>
-<dt>Switch (?(condition)... contains too many branches in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Switch-_0028_003f_0028condition_0029_002e_002e_002e-contains-too-many-branches-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) A (?(condition)if-clause|else-clause) construct can have at most
-two branches (the if-clause and the else-clause). If you want one or
-both to contain alternation, such as using <code>this|that|other</code>,
enclose
-it in clustering parentheses:
-</p>
-<pre class="verbatim"> (?(condition)(?:this|that|other)|else-clause)
-</pre>
-<p>The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the problem
-was discovered. See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Switch condition not recognized in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Switch-condition-not-recognized-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The condition part of a (?(condition)if-clause|else-clause) construct
-is not known. The condition must be one of the following:
-</p>
-<pre class="verbatim"> (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
-</pre>
-<p>The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the problem was
-discovered. See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Switch (?(condition)... not terminated in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Switch-_0028_003f_0028condition_0029_002e_002e_002e-not-terminated-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You omitted to close a (?(condition)...) block somewhere
-in the pattern. Add a closing parenthesis in the appropriate
-position. See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>switching effective %s is not implemented</dt>
-<dd><a name="perldiag-switching-effective-_0025s-is-not-implemented"></a>
-<p>(F) While under the <code>use filetest</code> pragma, we cannot switch the
real
-and effective uids or gids.
-</p>
-</dd>
-<dt>syntax error</dt>
-<dd><a name="perldiag-syntax-error"></a>
-<p>(F) Probably means you had a syntax error. Common reasons include:
-</p>
-<pre class="verbatim"> A keyword is misspelled.
- A semicolon is missing.
- A comma is missing.
- An opening or closing parenthesis is missing.
- An opening or closing brace is missing.
- A closing quote is missing.
-</pre>
-<p>Often there will be another error message associated with the syntax
-error giving more information. (Sometimes it helps to turn on
<strong>-w</strong>.)
-The error message itself often tells you where it was in the line when
-it decided to give up. Sometimes the actual error is several tokens
-before this, because Perl is good at understanding random input.
-Occasionally the line number may be misleading, and once in a blue moon
-the only way to figure out what’s triggering the error is to call
-<code>perl -c</code> repeatedly, chopping away half the program each time to
see
-if the error went away. Sort of the cybernetic version of
20 questions<!-- /@w -->.
-</p>
-</dd>
-<dt>syntax error at line %d: ’%s’ unexpected</dt>
-<dd><a
name="perldiag-syntax-error-at-line-_0025d_003a-_0027_0025s_0027-unexpected"></a>
-<p>(A) You’ve accidentally run your script through the Bourne shell
instead
-of Perl. Check the #! line, or manually feed your script into Perl
-yourself.
-</p>
-</dd>
-<dt>syntax error in file %s at line %d, next 2 tokens "%s"</dt>
-<dd><a
name="perldiag-syntax-error-in-file-_0025s-at-line-_0025d_002c-next-2-tokens-_0022_0025s_0022"></a>
-<p>(F) This error is likely to occur if you run a perl5 script through
-a perl4 interpreter, especially if the next 2 tokens are "use strict"
-or "my $var" or "our $var".
-</p>
-</dd>
-<dt>Syntax error in (?[...]) in regex m/%s/</dt>
-<dd><a
name="perldiag-Syntax-error-in-_0028_003f_005b_002e_002e_002e_005d_0029-in-regex-m_002f_0025s_002f"></a>
-<p>(F) Perl could not figure out what you meant inside this construct; this
-notifies you that it is giving up trying.
-</p>
-</dd>
-<dt>%s syntax OK</dt>
-<dd><a name="perldiag-_0025s-syntax-OK"></a>
-<p>(F) The final summary message when a <code>perl -c</code> succeeds.
-</p>
-</dd>
-<dt>sysread() on closed filehandle %s</dt>
-<dd><a name="perldiag-sysread_0028_0029-on-closed-filehandle-_0025s"></a>
-<p>(W closed) You tried to read from a closed filehandle.
-</p>
-</dd>
-<dt>sysread() on unopened filehandle %s</dt>
-<dd><a name="perldiag-sysread_0028_0029-on-unopened-filehandle-_0025s"></a>
-<p>(W unopened) You tried to read from a filehandle that was never opened.
-</p>
-</dd>
-<dt>System V %s is not implemented on this machine</dt>
-<dd><a name="perldiag-System-V-_0025s-is-not-implemented-on-this-machine"></a>
-<p>(F) You tried to do something with a function beginning with
"sem",
-"shm", or "msg" but that System V IPC is not implemented
in your
-machine. In some machines the functionality can exist but be
-unconfigured. Consult your system support.
-</p>
-</dd>
-<dt>syswrite() on closed filehandle %s</dt>
-<dd><a name="perldiag-syswrite_0028_0029-on-closed-filehandle-_0025s"></a>
-<p>(W closed) The filehandle you’re writing to got itself closed sometime
-before now. Check your control flow.
-</p>
-</dd>
-<dt><code>-T</code> and <code>-B</code> not implemented on filehandles</dt>
-<dd><a name="perldiag-_002dT-and-_002dB-not-implemented-on-filehandles"></a>
-<p>(F) Perl can’t peek at the stdio buffer of filehandles when it
doesn’t
-know about your kind of stdio. You’ll have to use a filename instead.
-</p>
-</dd>
-<dt>Target of goto is too deeply nested</dt>
-<dd><a name="perldiag-Target-of-goto-is-too-deeply-nested"></a>
-<p>(F) You tried to use <code>goto</code> to reach a label that was too deeply
nested
-for Perl to reach. Perl is doing you a favor by refusing.
-</p>
-</dd>
-<dt>telldir() attempted on invalid dirhandle %s</dt>
-<dd><a
name="perldiag-telldir_0028_0029-attempted-on-invalid-dirhandle-_0025s"></a>
-<p>(W io) The dirhandle you tried to telldir() is either closed or not really
-a dirhandle. Check your control flow.
-</p>
-</dd>
-<dt>tell() on unopened filehandle</dt>
-<dd><a name="perldiag-tell_0028_0029-on-unopened-filehandle"></a>
-<p>(W unopened) You tried to use the tell() function on a filehandle that
-was either never opened or has since been closed.
-</p>
-</dd>
-<dt>That use of $[ is unsupported</dt>
-<dd><a name="perldiag-That-use-of-_0024_005b-is-unsupported"></a>
-<p>(F) Assignment to <code>$[</code> is now strictly circumscribed, and
interpreted
-as a compiler directive. You may say only one of
-</p>
-<pre class="verbatim"> $[ = 0;
- $[ = 1;
- ...
- local $[ = 0;
- local $[ = 1;
- ...
-</pre>
-<p>This is to prevent the problem of one module changing the array base out
-from under another module inadvertently. See <a
href="#perlvar-_0024_005b">perlvar $[</a> and <a
href="arybase.html#Top">(arybase)</a>.
-</p>
-</dd>
-<dt>The bitwise feature is experimental</dt>
-<dd><a name="perldiag-The-bitwise-feature-is-experimental"></a>
-<p>(S experimental::bitwise) This warning is emitted if you use bitwise
-operators (<code>& | ^ ~ &. |. ^. ~.</code>) with the
"bitwise" feature enabled.
-Simply suppress the warning if you want to use the feature, but know
-that in doing so you are taking the risk of using an experimental
-feature which may change or be removed in a future Perl version:
-</p>
-<pre class="verbatim"> no warnings "experimental::bitwise";
- use feature "bitwise";
- $x |.= $y;
-</pre>
-</dd>
-<dt>The crypt() function is unimplemented due to excessive paranoia.</dt>
-<dd><a
name="perldiag-The-crypt_0028_0029-function-is-unimplemented-due-to-excessive-paranoia_002e"></a>
-<p>(F) Configure couldn’t find the crypt() function on your machine,
-probably because your vendor didn’t supply it, probably because they
-think the U.S. Government thinks it’s a secret, or at least that they
-will continue to pretend that it is. And if you quote me on that, I
-will deny it.
-</p>
-</dd>
-<dt>The %s function is unimplemented</dt>
-<dd><a name="perldiag-The-_0025s-function-is-unimplemented"></a>
-<p>(F) The function indicated isn’t implemented on this architecture,
-according to the probings of Configure.
-</p>
-</dd>
-<dt>The lexical_subs feature is experimental</dt>
-<dd><a name="perldiag-The-lexical_005fsubs-feature-is-experimental"></a>
-<p>(S experimental::lexical_subs) This warning is emitted if you
-declare a sub with <code>my</code> or <code>state</code>. Simply suppress the
warning
-if you want to use the feature, but know that in doing so you
-are taking the risk of using an experimental feature which may
-change or be removed in a future Perl version:
-</p>
-<pre class="verbatim"> no warnings "experimental::lexical_subs";
- use feature "lexical_subs";
- my sub foo { ... }
-</pre>
-</dd>
-<dt>The regex_sets feature is experimental</dt>
-<dd><a name="perldiag-The-regex_005fsets-feature-is-experimental"></a>
-<p>(S experimental::regex_sets) This warning is emitted if you
-use the syntax <code>(?[ ])</code><!-- /@w --> in a regular
expression.
-The details of this feature are subject to change.
-if you want to use it, but know that in doing so you
-are taking the risk of using an experimental feature which may
-change in a future Perl version, you can do this to silence the
-warning:
-</p>
-<pre class="verbatim"> no warnings "experimental::regex_sets";
-</pre>
-</dd>
-<dt>The signatures feature is experimental</dt>
-<dd><a name="perldiag-The-signatures-feature-is-experimental"></a>
-<p>(S experimental::signatures) This warning is emitted if you unwrap a
-subroutine’s arguments using a signature. Simply suppress the warning
-if you want to use the feature, but know that in doing so you are taking
-the risk of using an experimental feature which may change or be removed
-in a future Perl version:
-</p>
-<pre class="verbatim"> no warnings "experimental::signatures";
- use feature "signatures";
- sub foo ($left, $right) { ... }
-</pre>
-</dd>
-<dt>The stat preceding %s wasn’t an lstat</dt>
-<dd><a name="perldiag-The-stat-preceding-_0025s-wasn_0027t-an-lstat"></a>
-<p>(F) It makes no sense to test the current stat buffer for symbolic
-linkhood if the last stat that wrote to the stat buffer already went
-past the symlink to get to the real file. Use an actual filename
-instead.
-</p>
-</dd>
-<dt>The ’unique’ attribute may only be applied to
’our’ variables</dt>
-<dd><a
name="perldiag-The-_0027unique_0027-attribute-may-only-be-applied-to-_0027our_0027-variables"></a>
-<p>(F) This attribute was never supported on <code>my</code> or
<code>sub</code> declarations.
-</p>
-</dd>
-<dt>This Perl can’t reset CRTL environ elements (%s)</dt>
-<dd><a
name="perldiag-This-Perl-can_0027t-reset-CRTL-environ-elements-_0028_0025s_0029"></a>
-</dd>
-<dt>This Perl can’t set CRTL environ elements (%s=%s)</dt>
-<dd><a
name="perldiag-This-Perl-can_0027t-set-CRTL-environ-elements-_0028_0025s_003d_0025s_0029"></a>
-<p>(W internal) Warnings peculiar to VMS. You tried to change or delete an
-element of the CRTL’s internal environ array, but your copy of Perl
-wasn’t built with a CRTL that contained the setenv() function.
You’ll
-need to rebuild Perl with a CRTL that does, or redefine
-<samp>PERL_ENV_TABLES</samp> (see <a href="#perlvms-NAME">perlvms NAME</a>) so
that the environ array isn’t the
-target of the change to
-%ENV which produced the warning.
-</p>
-</dd>
-<dt>This Perl has not been built with support for randomized hash key
traversal but something called Perl_hv_rand_set().</dt>
-<dd><a
name="perldiag-This-Perl-has-not-been-built-with-support-for-randomized-hash-key-traversal-but-something-called-Perl_005fhv_005frand_005fset_0028_0029_002e"></a>
-<p>(F) Something has attempted to use an internal API call which
-depends on Perl being compiled with the default support for randomized hash
-key traversal, but this Perl has been compiled without it. You should
-report this warning to the relevant upstream party, or recompile perl
-with default options.
-</p>
-</dd>
-<dt>times not implemented</dt>
-<dd><a name="perldiag-times-not-implemented"></a>
-<p>(F) Your version of the C library apparently doesn’t do times(). I
-suspect you’re not running on Unix.
-</p>
-</dd>
-<dt>"-T" is on the #! line, it must also be used on the command
line</dt>
-<dd><a
name="perldiag-_0022_002dT_0022-is-on-the-_0023_0021-line_002c-it-must-also-be-used-on-the-command-line"></a>
-<p>(X) The #! line (or local equivalent) in a Perl script contains
-the <strong>-T</strong> option (or the <strong>-t</strong> option), but Perl
was not invoked with
-<strong>-T</strong> in its command line. This is an error because, by the time
-Perl discovers a <strong>-T</strong> in a script, it’s too late to
properly taint
-everything from the environment. So Perl gives up.
-</p>
-<p>If the Perl script is being executed as a command using the #!
-mechanism (or its local equivalent), this error can usually be
-fixed by editing the #! line so that the <strong>-%c</strong> option is a part
of
-Perl’s first argument: e.g. change <code>perl -n -%c</code> to
<code>perl -%c -n</code>.
-</p>
-<p>If the Perl script is being executed as <code>perl scriptname</code>, then
the
-<strong>-%c</strong> option must appear on the command line: <code>perl -%c
scriptname</code>.
-</p>
-</dd>
-<dt>To%s: illegal mapping ’%s’</dt>
-<dd><a name="perldiag-To_0025s_003a-illegal-mapping-_0027_0025s_0027"></a>
-<p>(F) You tried to define a customized To-mapping for lc(), lcfirst,
-uc(), or ucfirst() (or their string-inlined versions), but you
-specified an illegal mapping.
-See <a href="#perlunicode-User_002dDefined-Character-Properties">perlunicode
User-Defined Character Properties</a>.
-</p>
-</dd>
-<dt>Too deeply nested ()-groups</dt>
-<dd><a name="perldiag-Too-deeply-nested-_0028_0029_002dgroups"></a>
-<p>(F) Your template contains ()-groups with a ridiculously deep nesting level.
-</p>
-</dd>
-<dt>Too few args to syscall</dt>
-<dd><a name="perldiag-Too-few-args-to-syscall"></a>
-<p>(F) There has to be at least one argument to syscall() to specify the
-system call to call, silly dilly.
-</p>
-</dd>
-<dt>Too few arguments for subroutine</dt>
-<dd><a name="perldiag-Too-few-arguments-for-subroutine"></a>
-<p>(F) A subroutine using a signature received fewer arguments than required
-by the signature. The caller of the subroutine is presumably at fault.
-Inconveniently, this error will be reported at the location of the
-subroutine, not that of the caller.
-</p>
-</dd>
-<dt>Too late for "-%s" option</dt>
-<dd><a name="perldiag-Too-late-for-_0022_002d_0025s_0022-option"></a>
-<p>(X) The #! line (or local equivalent) in a Perl script contains the
-<strong>-M</strong>, <strong>-m</strong> or <strong>-C</strong> option.
-</p>
-<p>In the case of <strong>-M</strong> and <strong>-m</strong>, this is an
error because those options
-are not intended for use inside scripts. Use the <code>use</code> pragma
instead.
-</p>
-<p>The <strong>-C</strong> option only works if it is specified on the command
line as
-well (with the same sequence of letters or numbers following). Either
-specify this option on the command line, or, if your system supports
-it, make your script executable and run it directly instead of passing
-it to perl.
-</p>
-</dd>
-<dt>Too late to run %s block</dt>
-<dd><a name="perldiag-Too-late-to-run-_0025s-block"></a>
-<p>(W void) A CHECK or INIT block is being defined during run time proper,
-when the opportunity to run them has already passed. Perhaps you are
-loading a file with <code>require</code> or <code>do</code> when you should be
using <code>use</code>
-instead. Or perhaps you should put the <code>require</code> or
<code>do</code> inside a
-BEGIN block.
-</p>
-</dd>
-<dt>Too many args to syscall</dt>
-<dd><a name="perldiag-Too-many-args-to-syscall"></a>
-<p>(F) Perl supports a maximum of only 14 args to syscall().
-</p>
-</dd>
-<dt>Too many arguments for %s</dt>
-<dd><a name="perldiag-Too-many-arguments-for-_0025s"></a>
-<p>(F) The function requires fewer arguments than you specified.
-</p>
-</dd>
-<dt>Too many arguments for subroutine</dt>
-<dd><a name="perldiag-Too-many-arguments-for-subroutine"></a>
-<p>(F) A subroutine using a signature received more arguments than required
-by the signature. The caller of the subroutine is presumably at fault.
-Inconveniently, this error will be reported at the location of the
-subroutine, not that of the caller.
-</p>
-</dd>
-<dt>Too many )’s</dt>
-<dd><a name="perldiag-Too-many-_0029_0027s"></a>
-<p>(A) You’ve accidentally run your script through <strong>csh</strong>
instead of Perl.
-Check the #! line, or manually feed your script into Perl yourself.
-</p>
-</dd>
-<dt>Too many (’s</dt>
-<dd><a name="perldiag-Too-many-_0028_0027s"></a>
-<p>(A) You’ve accidentally run your script through <strong>csh</strong>
instead of Perl.
-Check the #! line, or manually feed your script into Perl yourself.
-</p>
-</dd>
-<dt>Trailing \ in regex m/%s/</dt>
-<dd><a name="perldiag-Trailing-_005c-in-regex-m_002f_0025s_002f"></a>
-<p>(F) The regular expression ends with an unbackslashed backslash.
-Backslash it. See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Transliteration pattern not terminated</dt>
-<dd><a name="perldiag-Transliteration-pattern-not-terminated"></a>
-<p>(F) The lexer couldn’t find the interior delimiter of a tr/// or
tr[][]
-or y/// or y[][] construct. Missing the leading <code>$</code> from variables
-<code>$tr</code> or <code>$y</code> may cause this error.
-</p>
-</dd>
-<dt>Transliteration replacement not terminated</dt>
-<dd><a name="perldiag-Transliteration-replacement-not-terminated"></a>
-<p>(F) The lexer couldn’t find the final delimiter of a tr///, tr[][],
-y/// or y[][] construct.
-</p>
-</dd>
-<dt>’%s’ trapped by operation mask</dt>
-<dd><a name="perldiag-_0027_0025s_0027-trapped-by-operation-mask"></a>
-<p>(F) You tried to use an operator from a Safe compartment in which it’s
-disallowed. See <a href="Safe.html#Top">(Safe)</a>.
-</p>
-</dd>
-<dt>truncate not implemented</dt>
-<dd><a name="perldiag-truncate-not-implemented"></a>
-<p>(F) Your machine doesn’t implement a file truncation mechanism that
-Configure knows about.
-</p>
-</dd>
-<dt>Type of arg %d to &CORE::%s must be %s</dt>
-<dd><a
name="perldiag-Type-of-arg-_0025d-to-_0026CORE_003a_003a_0025s-must-be-_0025s"></a>
-<p>(F) The subroutine in question in the CORE package requires its argument
-to be a hard reference to data of the specified type. Overloading is
-ignored, so a reference to an object that is not the specified type, but
-nonetheless has overloading to handle it, will still not be accepted.
-</p>
-</dd>
-<dt>Type of arg %d to %s must be %s (not %s)</dt>
-<dd><a
name="perldiag-Type-of-arg-_0025d-to-_0025s-must-be-_0025s-_0028not-_0025s_0029"></a>
-<p>(F) This function requires the argument in that position to be of a
-certain type. Arrays must be @NAME or <code>@{EXPR}</code>. Hashes must be
-%NAME or <code>%{EXPR}</code>. No implicit dereferencing is allowed–use
the
-{EXPR} forms as an explicit dereference. See <a href="#perlref-NAME">perlref
NAME</a>.
-</p>
-</dd>
-<dt>Type of argument to %s must be unblessed hashref or arrayref</dt>
-<dd><a
name="perldiag-Type-of-argument-to-_0025s-must-be-unblessed-hashref-or-arrayref"></a>
-<p>(F) You called <code>keys</code>, <code>values</code> or <code>each</code>
with a scalar argument that
-was not a reference to an unblessed hash or array.
-</p>
-</dd>
-<dt>umask not implemented</dt>
-<dd><a name="perldiag-umask-not-implemented"></a>
-<p>(F) Your machine doesn’t implement the umask function and you tried to
-use it to restrict permissions for yourself (EXPR & 0700).
-</p>
-</dd>
-<dt>Unbalanced context: %d more PUSHes than POPs</dt>
-<dd><a
name="perldiag-Unbalanced-context_003a-_0025d-more-PUSHes-than-POPs"></a>
-<p>(S internal) The exit code detected an internal inconsistency in how
-many execution contexts were entered and left.
-</p>
-</dd>
-<dt>Unbalanced saves: %d more saves than restores</dt>
-<dd><a
name="perldiag-Unbalanced-saves_003a-_0025d-more-saves-than-restores"></a>
-<p>(S internal) The exit code detected an internal inconsistency in how
-many values were temporarily localized.
-</p>
-</dd>
-<dt>Unbalanced scopes: %d more ENTERs than LEAVEs</dt>
-<dd><a
name="perldiag-Unbalanced-scopes_003a-_0025d-more-ENTERs-than-LEAVEs"></a>
-<p>(S internal) The exit code detected an internal inconsistency in how
-many blocks were entered and left.
-</p>
-</dd>
-<dt>Unbalanced string table refcount: (%d) for "%s"</dt>
-<dd><a
name="perldiag-Unbalanced-string-table-refcount_003a-_0028_0025d_0029-for-_0022_0025s_0022"></a>
-<p>(S internal) On exit, Perl found some strings remaining in the shared
-string table used for copy on write and for hash keys. The entries
-should have been freed, so this indicates a bug somewhere.
-</p>
-</dd>
-<dt>Unbalanced tmps: %d more allocs than frees</dt>
-<dd><a name="perldiag-Unbalanced-tmps_003a-_0025d-more-allocs-than-frees"></a>
-<p>(S internal) The exit code detected an internal inconsistency in how
-many mortal scalars were allocated and freed.
-</p>
-</dd>
-<dt>Undefined format "%s" called</dt>
-<dd><a name="perldiag-Undefined-format-_0022_0025s_0022-called"></a>
-<p>(F) The format indicated doesn’t seem to exist. Perhaps it’s
really in
-another package? See <a href="#perlform-NAME">perlform NAME</a>.
-</p>
-</dd>
-<dt>Undefined sort subroutine "%s" called</dt>
-<dd><a name="perldiag-Undefined-sort-subroutine-_0022_0025s_0022-called"></a>
-<p>(F) The sort comparison routine specified doesn’t seem to exist.
-Perhaps it’s in a different package? See ‘perlfunc sort’.
-</p>
-</dd>
-<dt>Undefined subroutine &%s called</dt>
-<dd><a name="perldiag-Undefined-subroutine-_0026_0025s-called"></a>
-<p>(F) The subroutine indicated hasn’t been defined, or if it was, it has
-since been undefined.
-</p>
-</dd>
-<dt>Undefined subroutine called</dt>
-<dd><a name="perldiag-Undefined-subroutine-called"></a>
-<p>(F) The anonymous subroutine you’re trying to call hasn’t been
defined,
-or if it was, it has since been undefined.
-</p>
-</dd>
-<dt>Undefined subroutine in sort</dt>
-<dd><a name="perldiag-Undefined-subroutine-in-sort"></a>
-<p>(F) The sort comparison routine specified is declared but doesn’t seem
-to have been defined yet. See ‘perlfunc sort’.
-</p>
-</dd>
-<dt>Undefined top format "%s" called</dt>
-<dd><a name="perldiag-Undefined-top-format-_0022_0025s_0022-called"></a>
-<p>(F) The format indicated doesn’t seem to exist. Perhaps it’s
really in
-another package? See <a href="#perlform-NAME">perlform NAME</a>.
-</p>
-</dd>
-<dt>Undefined value assigned to typeglob</dt>
-<dd><a name="perldiag-Undefined-value-assigned-to-typeglob"></a>
-<p>(W misc) An undefined value was assigned to a typeglob, a la
-<code>*foo = undef</code>. This does nothing. It’s possible that you
really mean
-<code>undef *foo</code>.
-</p>
-</dd>
-<dt>%s: Undefined variable</dt>
-<dd><a name="perldiag-_0025s_003a-Undefined-variable"></a>
-<p>(A) You’ve accidentally run your script through <strong>csh</strong>
instead of Perl.
-Check the #! line, or manually feed your script into Perl yourself.
-</p>
-</dd>
-<dt>Unescaped left brace in regex is deprecated, passed through in regex;
marked by <– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unescaped-left-brace-in-regex-is-deprecated_002c-passed-through-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(D deprecated, regexp) You used a literal <code>"{"</code>
character in a regular
-expression pattern. You should change to use <code>"\{"</code>
instead, because a
-future version of Perl (tentatively v5.26) will consider this to be a
-syntax error. If the pattern delimiters are also braces, any matching
-right brace (<code>"}"</code>) should also be escaped to avoid
confusing the parser,
-for example,
-</p>
-<pre class="verbatim"> qr{abc\{def\}ghi}
-</pre>
-</dd>
-<dt>unexec of %s into %s failed!</dt>
-<dd><a name="perldiag-unexec-of-_0025s-into-_0025s-failed_0021"></a>
-<p>(F) The unexec() routine failed for some reason. See your local FSF
-representative, who probably put it there in the first place.
-</p>
-</dd>
-<dt>Unexpected binary operator ’%c’ with no preceding operand in
regex; marked by <– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unexpected-binary-operator-_0027_0025c_0027-with-no-preceding-operand-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You had something like this:
-</p>
-<pre class="verbatim"> (?[ | \p{Digit} ])
-</pre>
-<p>where the <code>"|"</code> is a binary operator with an operand
on the right, but
-no operand on the left.
-</p>
-</dd>
-<dt>Unexpected character in regex; marked by <– HERE<!-- /@w -->
in m/%s/</dt>
-<dd><a
name="perldiag-Unexpected-character-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You had something like this:
-</p>
-<pre class="verbatim"> (?[ z ])
-</pre>
-<p>Within <code>(?[ ])</code>, no literal characters are allowed unless they
are
-within an inner pair of square brackets, like
-</p>
-<pre class="verbatim"> (?[ [ z ] ])
-</pre>
-<p>Another possibility is that you forgot a backslash. Perl isn’t smart
-enough to figure out what you really meant.
-</p>
-</dd>
-<dt>Unexpected constant lvalue entersub entry via type/targ %d:%d</dt>
-<dd><a
name="perldiag-Unexpected-constant-lvalue-entersub-entry-via-type_002ftarg-_0025d_003a_0025d"></a>
-<p>(P) When compiling a subroutine call in lvalue context, Perl failed an
-internal consistency check. It encountered a malformed op tree.
-</p>
-</dd>
-<dt>Unexpected exit %u</dt>
-<dd><a name="perldiag-Unexpected-exit-_0025u"></a>
-<p>(S) exit() was called or the script otherwise finished gracefully when
-<code>PERL_EXIT_WARN</code> was set in <code>PL_exit_flags</code>.
-</p>
-</dd>
-<dt>Unexpected exit failure %d</dt>
-<dd><a name="perldiag-Unexpected-exit-failure-_0025d"></a>
-<p>(S) An uncaught die() was called when <code>PERL_EXIT_WARN</code> was set in
-<code>PL_exit_flags</code>.
-</p>
-</dd>
-<dt>Unexpected ’)’ in regex; marked by <– HERE<!--
/@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unexpected-_0027_0029_0027-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You had something like this:
-</p>
-<pre class="verbatim"> (?[ ( \p{Digit} + ) ])
-</pre>
-<p>The <code>")"</code> is out-of-place. Something apparently was
supposed to
-be combined with the digits, or the <code>"+"</code> shouldn’t
be there, or
-something like that. Perl can’t figure out what was intended.
-</p>
-</dd>
-<dt>Unexpected ’(’ with no preceding operator in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unexpected-_0027_0028_0027-with-no-preceding-operator-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You had something like this:
-</p>
-<pre class="verbatim"> (?[ \p{Digit} ( \p{Lao} + \p{Thai} ) ])
-</pre>
-<p>There should be an operator before the <code>"("</code>, as
there’s
-no indication as to how the digits are to be combined
-with the characters in the Lao and Thai scripts.
-</p>
-</dd>
-<dt>Unicode non-character U+%X is illegal for open interchange</dt>
-<dd><a
name="perldiag-Unicode-non_002dcharacter-U_002b_0025X-is-illegal-for-open-interchange"></a>
-<p>(S 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. An application
-may not be expecting any of these characters at all, and receiving
-them may lead to bugs. If you know what you are doing you can
-turn off this warning by <code>no warnings 'nonchar';</code>.
-</p>
-<p>This is not really a "severe" error, but it is supposed to be
-raised by default even if warnings are not enabled, and currently
-the only way to do that in Perl is to mark it as serious.
-</p>
-</dd>
-<dt>Unicode surrogate U+%X is illegal in UTF-8</dt>
-<dd><a
name="perldiag-Unicode-surrogate-U_002b_0025X-is-illegal-in-UTF_002d8"></a>
-<p>(S 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 <code>no warnings 'surrogate';</code>.
-</p>
-</dd>
-<dt>Unknown charname ’%s’</dt>
-<dd><a name="perldiag-Unknown-charname-_0027_0025s_0027"></a>
-<p>(F) The name you used inside <code>\N{}</code> is unknown to Perl. Check
the
-spelling. You can say <code>use charnames ":loose"</code> to not
have to be
-so precise about spaces, hyphens, and capitalization on standard Unicode
-names. (Any custom aliases that have been created must be specified
-exactly, regardless of whether <code>:loose</code> is used or not.) This
error may
-also happen if the <code>\N{}</code> is not in the scope of the corresponding
-<code>use charnames<!-- /@w --></code>.
-</p>
-</dd>
-<dt>Unknown error</dt>
-<dd><a name="perldiag-Unknown-error"></a>
-<p>(P) Perl was about to print an error message in <code>$@</code>, but the
<code>$@</code> variable
-did not exist, even after an attempt to create it.
-</p>
-</dd>
-<dt>Unknown open() mode ’%s’</dt>
-<dd><a name="perldiag-Unknown-open_0028_0029-mode-_0027_0025s_0027"></a>
-<p>(F) The second argument of 3-argument open() is not among the list
-of valid modes: <code><</code>, <code>></code>, <code>>></code>,
<code>+<</code>,
-<code>+></code>, <code>+>></code>, <code>-|</code>, <code>|-</code>,
<code><&</code>, <code>>&</code>.
-</p>
-</dd>
-<dt>Unknown PerlIO layer "%s"</dt>
-<dd><a name="perldiag-Unknown-PerlIO-layer-_0022_0025s_0022"></a>
-<p>(W layer) An attempt was made to push an unknown layer onto the Perl I/O
-system. (Layers take care of transforming data between external and
-internal representations.) Note that some layers, such as <code>mmap</code>,
-are not supported in all environments. If your program didn’t
-explicitly request the failing operation, it may be the result of the
-value of the environment variable PERLIO.
-</p>
-</dd>
-<dt>Unknown process %x sent message to prime_env_iter: %s</dt>
-<dd><a
name="perldiag-Unknown-process-_0025x-sent-message-to-prime_005fenv_005fiter_003a-_0025s"></a>
-<p>(P) An error peculiar to VMS. Perl was reading values for %ENV before
-iterating over it, and someone else stuck a message in the stream of
-data Perl expected. Someone’s very confused, or perhaps trying to
-subvert Perl’s population of %ENV for nefarious purposes.
-</p>
-</dd>
-<dt>Unknown regex modifier "%s"</dt>
-<dd><a name="perldiag-Unknown-regex-modifier-_0022_0025s_0022"></a>
-<p>(F) Alphanumerics immediately following the closing delimiter
-of a regular expression pattern are interpreted by Perl as modifier
-flags for the regex. One of the ones you specified is invalid. One way
-this can happen is if you didn’t put in white space between the end of
-the regex and a following alphanumeric operator:
-</p>
-<pre class="verbatim"> if ($a =~ /foo/and $bar == 3) { ... }
-</pre>
-<p>The <code>"a"</code> is a valid modifier flag, but the
<code>"n"</code> is not, and raises
-this error. Likely what was meant instead was:
-</p>
-<pre class="verbatim"> if ($a =~ /foo/ and $bar == 3) { ... }
-</pre>
-</dd>
-<dt>Unknown "re" subpragma ’%s’ (known ones are: %s)</dt>
-<dd><a
name="perldiag-Unknown-_0022re_0022-subpragma-_0027_0025s_0027-_0028known-ones-are_003a-_0025s_0029"></a>
-<p>(W) You tried to use an unknown subpragma of the "re" pragma.
-</p>
-</dd>
-<dt>Unknown switch condition (?(...)) in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unknown-switch-condition-_0028_003f_0028_002e_002e_002e_0029_0029-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The condition part of a (?(condition)if-clause|else-clause) construct
-is not known. The condition must be one of the following:
-</p>
-<pre class="verbatim"> (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
-</pre>
-<p>The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the problem was
-discovered. See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Unknown Unicode option letter ’%c’</dt>
-<dd><a name="perldiag-Unknown-Unicode-option-letter-_0027_0025c_0027"></a>
-<p>(F) You specified an unknown Unicode option. See <a
href="#perlrun-NAME">perlrun NAME</a> documentation
-of the <code>-C</code> switch for the list of known options.
-</p>
-</dd>
-<dt>Unknown Unicode option value %d</dt>
-<dd><a name="perldiag-Unknown-Unicode-option-value-_0025d"></a>
-<p>(F) You specified an unknown Unicode option. See <a
href="#perlrun-NAME">perlrun NAME</a> documentation
-of the <code>-C</code> switch for the list of known options.
-</p>
-</dd>
-<dt>Unknown verb pattern ’%s’ in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unknown-verb-pattern-_0027_0025s_0027-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You either made a typo or have incorrectly put a <code>*</code>
quantifier
-after an open brace in your pattern. Check the pattern and review
-<a href="#perlre-NAME">perlre NAME</a> for details on legal verb patterns.
-</p>
-</dd>
-<dt>Unknown warnings category ’%s’</dt>
-<dd><a name="perldiag-Unknown-warnings-category-_0027_0025s_0027"></a>
-<p>(F) An error issued by the <code>warnings</code> pragma. You specified a
warnings
-category that is unknown to perl at this point.
-</p>
-<p>Note that if you want to enable a warnings category registered by a
-module (e.g. <code>use warnings 'File::Find'</code>), you must have loaded this
-module first.
-</p>
-</dd>
-<dt>Unmatched ’[’ in POSIX class in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unmatched-_0027_005b_0027-in-POSIX-class-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You had something like this:
-</p>
-<pre class="verbatim"> (?[ [:digit: ])
-</pre>
-<p>That should be written:
-</p>
-<pre class="verbatim"> (?[ [:digit:] ])
-</pre>
-</dd>
-<dt>Unmatched ’%c’ in POSIX class in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unmatched-_0027_0025c_0027-in-POSIX-class-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You had something like this:
-</p>
-<pre class="verbatim"> (?[ [:alnum] ])
-</pre>
-<p>There should be a second <code>":"</code>, like this:
-</p>
-<pre class="verbatim"> (?[ [:alnum:] ])
-</pre>
-</dd>
-<dt>Unmatched [ in regex; marked by <– HERE<!-- /@w --> in
m/%s/</dt>
-<dd><a
name="perldiag-Unmatched-_005b-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) The brackets around a character class must match. If you wish to
-include a closing bracket in a character class, backslash it or put it
-first. The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the
-problem was discovered. See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Unmatched ( in regex; marked by <– HERE<!-- /@w --> in
m/%s/</dt>
-<dd><a
name="perldiag-Unmatched-_0028-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-</dd>
-<dt>Unmatched ) in regex; marked by <– HERE<!-- /@w --> in
m/%s/</dt>
-<dd><a
name="perldiag-Unmatched-_0029-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) Unbackslashed parentheses must always be balanced in regular
-expressions. If you’re a vi user, the % key is valuable for finding
-the matching parenthesis. The <– HERE<!-- /@w --> shows
whereabouts in the
-regular expression the problem was discovered. See <a
href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Unmatched right %s bracket</dt>
-<dd><a name="perldiag-Unmatched-right-_0025s-bracket"></a>
-<p>(F) The lexer counted more closing curly or square brackets than opening
-ones, so you’re probably missing a matching opening bracket. As a
-general rule, you’ll find the missing one (so to speak) near the place
-you were last editing.
-</p>
-</dd>
-<dt>Unquoted string "%s" may clash with future reserved word</dt>
-<dd><a
name="perldiag-Unquoted-string-_0022_0025s_0022-may-clash-with-future-reserved-word"></a>
-<p>(W reserved) You used a bareword that might someday be claimed as a
-reserved word. It’s best to put such a word in quotes, or capitalize it
-somehow, or insert an underbar into it. You might also declare it as a
-subroutine.
-</p>
-</dd>
-<dt>Unrecognized character %s; marked by <– HERE<!-- /@w -->
after %s near column %d</dt>
-<dd><a
name="perldiag-Unrecognized-character-_0025s_003b-marked-by-_003c_002d_002d-HERE-after-_0025s-near-column-_0025d"></a>
-<p>(F) The Perl parser has no idea what to do with the specified character
-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.
-</p>
-</dd>
-<dt>Unrecognized escape \%c in character class in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unrecognized-escape-_005c_0025c-in-character-class-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You used a backslash-character combination which is not
-recognized by Perl inside character classes. This is a fatal
-error when the character class is used within <code>(?[ ])</code>.
-</p>
-</dd>
-<dt>Unrecognized escape \%c in character class passed through in regex;
marked by <– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unrecognized-escape-_005c_0025c-in-character-class-passed-through-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) You used a backslash-character combination which is not
-recognized by Perl inside character classes. The character was
-understood literally, but this may change in a future version of Perl.
-The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the
-escape was discovered.
-</p>
-</dd>
-<dt>Unrecognized escape \%c passed through</dt>
-<dd><a name="perldiag-Unrecognized-escape-_005c_0025c-passed-through"></a>
-<p>(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.
-</p>
-</dd>
-<dt>Unrecognized escape \%s passed through in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unrecognized-escape-_005c_0025s-passed-through-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) You used a backslash-character combination which is not
-recognized by Perl. The character(s) were understood literally, but
-this may change in a future version of Perl. The <– HERE<!--
/@w --> shows
-whereabouts in the regular expression the escape was discovered.
-</p>
-</dd>
-<dt>Unrecognized signal name "%s"</dt>
-<dd><a name="perldiag-Unrecognized-signal-name-_0022_0025s_0022"></a>
-<p>(F) You specified a signal name to the kill() function that was not
-recognized. Say <code>kill -l</code> in your shell to see the valid signal
names
-on your system.
-</p>
-</dd>
-<dt>Unrecognized switch: -%s (-h will show valid options)</dt>
-<dd><a
name="perldiag-Unrecognized-switch_003a-_002d_0025s-_0028_002dh-will-show-valid-options_0029"></a>
-<p>(F) You specified an illegal option to Perl. Don’t do that. (If you
-think you didn’t do that, check the #! line to see if it’s
supplying the
-bad switch on your behalf.)
-</p>
-</dd>
-<dt>unshift on reference is experimental</dt>
-<dd><a name="perldiag-unshift-on-reference-is-experimental"></a>
-<p>(S experimental::autoderef) <code>unshift</code> with a scalar argument
-is experimental and may change or be removed in a future
-Perl version. If you want to take the risk of using this
-feature, simply disable this warning:
-</p>
-<pre class="verbatim"> no warnings "experimental::autoderef";
-</pre>
-</dd>
-<dt>Unsuccessful %s on filename containing newline</dt>
-<dd><a name="perldiag-Unsuccessful-_0025s-on-filename-containing-newline"></a>
-<p>(W newline) A file operation was attempted on a filename, and that
-operation failed, PROBABLY because the filename contained a newline,
-PROBABLY because you forgot to chomp() it off. See <a
href="#perlfunc-chomp">perlfunc chomp</a>.
-</p>
-</dd>
-<dt>Unsupported directory function "%s" called</dt>
-<dd><a
name="perldiag-Unsupported-directory-function-_0022_0025s_0022-called"></a>
-<p>(F) Your machine doesn’t support opendir() and readdir().
-</p>
-</dd>
-<dt>Unsupported function %s</dt>
-<dd><a name="perldiag-Unsupported-function-_0025s"></a>
-<p>(F) This machine doesn’t implement the indicated function, apparently.
-At least, Configure doesn’t think so.
-</p>
-</dd>
-<dt>Unsupported function fork</dt>
-<dd><a name="perldiag-Unsupported-function-fork"></a>
-<p>(F) Your version of executable does not support forking.
-</p>
-<p>Note that under some systems, like OS/2, there may be different flavors
-of Perl executables, some of which may support fork, some not. Try
-changing the name you call Perl by to <code>perl_</code>, <code>perl__</code>,
and so on.
-</p>
-</dd>
-<dt>Unsupported script encoding %s</dt>
-<dd><a name="perldiag-Unsupported-script-encoding-_0025s"></a>
-<p>(F) Your program file begins with a Unicode Byte Order Mark (BOM) which
-declares it to be in a Unicode encoding that Perl cannot read.
-</p>
-</dd>
-<dt>Unsupported socket function "%s" called</dt>
-<dd><a name="perldiag-Unsupported-socket-function-_0022_0025s_0022-called"></a>
-<p>(F) Your machine doesn’t support the Berkeley socket mechanism, or at
-least that’s what Configure thought.
-</p>
-</dd>
-<dt>Unterminated attribute list</dt>
-<dd><a name="perldiag-Unterminated-attribute-list"></a>
-<p>(F) The lexer found something other than a simple identifier at the
-start of an attribute, and it wasn’t a semicolon or the start of a
-block. Perhaps you terminated the parameter list of the previous
-attribute too soon. See <a href="attributes.html#Top">(attributes)</a>.
-</p>
-</dd>
-<dt>Unterminated attribute parameter in attribute list</dt>
-<dd><a name="perldiag-Unterminated-attribute-parameter-in-attribute-list"></a>
-<p>(F) The lexer saw an opening (left) parenthesis character while parsing
-an attribute list, but the matching closing (right) parenthesis
-character was not found. You may need to add (or remove) a backslash
-character to get your parentheses to balance. See <a
href="attributes.html#Top">(attributes)</a>.
-</p>
-</dd>
-<dt>Unterminated compressed integer</dt>
-<dd><a name="perldiag-Unterminated-compressed-integer"></a>
-<p>(F) An argument to unpack("w",...) was incompatible with the BER
-compressed integer format and could not be converted to an integer.
-See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>Unterminated delimiter for here document</dt>
-<dd><a name="perldiag-Unterminated-delimiter-for-here-document"></a>
-<p>(F) This message occurs when a here document label has an initial
-quotation mark but the final quotation mark is missing. Perhaps
-you wrote:
-</p>
-<pre class="verbatim"> <<"foo
-</pre>
-<p>instead of:
-</p>
-<pre class="verbatim"> <<"foo"
-</pre>
-</dd>
-<dt>Unterminated \g... pattern in regex; marked by <– HERE<!--
/@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unterminated-_005cg_002e_002e_002e-pattern-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-</dd>
-<dt>Unterminated \g{...} pattern in regex; marked by <– HERE<!--
/@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unterminated-_005cg_007b_002e_002e_002e_007d-pattern-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) In a regular expression, you had a <code>\g</code> that wasn’t
followed by a
-proper group reference. In the case of <code>\g{</code>, the closing brace is
-missing; otherwise the <code>\g</code> must be followed by an integer. Fix the
-pattern and retry.
-</p>
-</dd>
-<dt>Unterminated <> operator</dt>
-<dd><a name="perldiag-Unterminated-_003c_003e-operator"></a>
-<p>(F) The lexer saw a left angle bracket in a place where it was expecting
-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".
-</p>
-</dd>
-<dt>Unterminated verb pattern argument in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unterminated-verb-pattern-argument-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You used a pattern of the form <code>(*VERB:ARG)</code> but did not
terminate
-the pattern with a <code>)</code>. Fix the pattern and retry.
-</p>
-</dd>
-<dt>Unterminated verb pattern in regex; marked by <– HERE<!--
/@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Unterminated-verb-pattern-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You used a pattern of the form <code>(*VERB)</code> but did not
terminate
-the pattern with a <code>)</code>. Fix the pattern and retry.
-</p>
-</dd>
-<dt>untie attempted while %d inner references still exist</dt>
-<dd><a
name="perldiag-untie-attempted-while-_0025d-inner-references-still-exist"></a>
-<p>(W untie) A copy of the object returned from <code>tie</code> (or
<code>tied</code>) was
-still valid when <code>untie</code> was called.
-</p>
-</dd>
-<dt>Usage: POSIX::%s(%s)</dt>
-<dd><a name="perldiag-Usage_003a-POSIX_003a_003a_0025s_0028_0025s_0029"></a>
-<p>(F) You called a POSIX function with incorrect arguments.
-See <a href="POSIX.html#FUNCTIONS">(POSIX)FUNCTIONS</a> for more information.
-</p>
-</dd>
-<dt>Usage: Win32::%s(%s)</dt>
-<dd><a name="perldiag-Usage_003a-Win32_003a_003a_0025s_0028_0025s_0029"></a>
-<p>(F) You called a Win32 function with incorrect arguments.
-See <a href="Win32.html#Top">(Win32)</a> for more information.
-</p>
-</dd>
-<dt>$[ used in %s (did you mean $] ?)</dt>
-<dd><a
name="perldiag-_0024_005b-used-in-_0025s-_0028did-you-mean-_0024_005d-_003f_0029"></a>
-<p>(W syntax) You used <code>$[</code> in a comparison, such as:
-</p>
-<pre class="verbatim"> if ($[ > 5.006) {
- ...
- }
-</pre>
-<p>You probably meant to use <code>$]</code> instead. <code>$[</code> is the
base for indexing
-arrays. <code>$]</code> is the Perl version number in decimal.
-</p>
-</dd>
-<dt>Use "%s" instead of "%s"</dt>
-<dd><a name="perldiag-Use-_0022_0025s_0022-instead-of-_0022_0025s_0022"></a>
-<p>(F) The second listed construct is no longer legal. Use the first one
-instead.
-</p>
-</dd>
-<dt>Useless assignment to a temporary</dt>
-<dd><a name="perldiag-Useless-assignment-to-a-temporary"></a>
-<p>(W misc) You assigned to an lvalue subroutine, but what
-the subroutine returned was a temporary scalar about to
-be discarded, so the assignment had no effect.
-</p>
-</dd>
-<dt>Useless (?-%s) - don’t use /%s modifier in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Useless-_0028_003f_002d_0025s_0029-_002d-don_0027t-use-_002f_0025s-modifier-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) You have used an internal modifier such as (?-o) that has no
-meaning unless removed from the entire regexp:
-</p>
-<pre class="verbatim"> if ($string =~ /(?-o)$pattern/o) { ... }
-</pre>
-<p>must be written as
-</p>
-<pre class="verbatim"> if ($string =~ /$pattern/) { ... }
-</pre>
-<p>The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the problem was
-discovered. See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Useless localization of %s</dt>
-<dd><a name="perldiag-Useless-localization-of-_0025s"></a>
-<p>(W syntax) The localization of lvalues such as <code>local($x=10)</code> is
legal,
-but in fact the local() currently has no effect. This may change at
-some point in the future, but in the meantime such code is discouraged.
-</p>
-</dd>
-<dt>Useless (?%s) - use /%s modifier in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Useless-_0028_003f_0025s_0029-_002d-use-_002f_0025s-modifier-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) You have used an internal modifier such as (?o) that has no
-meaning unless applied to the entire regexp:
-</p>
-<pre class="verbatim"> if ($string =~ /(?o)$pattern/) { ... }
-</pre>
-<p>must be written as
-</p>
-<pre class="verbatim"> if ($string =~ /$pattern/o) { ... }
-</pre>
-<p>The <– HERE<!-- /@w --> shows whereabouts in the regular
expression the problem was
-discovered. See <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-<dt>Useless use of attribute "const"</dt>
-<dd><a name="perldiag-Useless-use-of-attribute-_0022const_0022"></a>
-<p>(W misc) The "const" attribute has no effect except
-on anonymous closure prototypes. You applied it to
-a subroutine via <a href="attributes.html#Top">(attributes)attributes.pm</a>.
This is only useful
-inside an attribute handler for an anonymous subroutine.
-</p>
-</dd>
-<dt>Useless use of /d modifier in transliteration operator</dt>
-<dd><a
name="perldiag-Useless-use-of-_002fd-modifier-in-transliteration-operator"></a>
-<p>(W misc) You have used the /d modifier where the searchlist has the
-same length as the replacelist. See <a href="#perlop-NAME">perlop NAME</a>
for more information
-about the /d modifier.
-</p>
-</dd>
-<dt>Useless use of \E</dt>
-<dd><a name="perldiag-Useless-use-of-_005cE"></a>
-<p>(W misc) You have a \E in a double-quotish string without a <code>\U</code>,
-<code>\L</code> or <code>\Q</code> preceding it.
-</p>
-</dd>
-<dt>Useless use of greediness modifier ’%c’ in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Useless-use-of-greediness-modifier-_0027_0025c_0027-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) You specified something like these:
-</p>
-<pre class="verbatim"> qr/a{3}?/
- qr/b{1,1}+/
-</pre>
-<p>The <code>"?"</code> and <code>"+"</code> don’t
have any effect, as they modify whether to
-match more or fewer when there is a choice, and by specifying to match
-exactly a given numer, there is no room left for a choice.
-</p>
-</dd>
-<dt>Useless use of %s in void context</dt>
-<dd><a name="perldiag-Useless-use-of-_0025s-in-void-context"></a>
-<p>(W void) You did something without a side effect in a context that does
-nothing with the return value, such as a statement that doesn’t return a
-value from a block, or the left side of a scalar comma operator. Very
-often this points not to stupidity on your part, but a failure of Perl
-to parse your program the way you thought it would. For example, you’d
-get this if you mixed up your C precedence with Python precedence and
-said
-</p>
-<pre class="verbatim"> $one, $two = 1, 2;
-</pre>
-<p>when you meant to say
-</p>
-<pre class="verbatim"> ($one, $two) = (1, 2);
-</pre>
-<p>Another common error is to use ordinary parentheses to construct a list
-reference when you should be using square or curly brackets, for
-example, if you say
-</p>
-<pre class="verbatim"> $array = (1,2);
-</pre>
-<p>when you should have said
-</p>
-<pre class="verbatim"> $array = [1,2];
-</pre>
-<p>The square brackets explicitly turn a list value into a scalar value,
-while parentheses do not. So when a parenthesized list is evaluated in
-a scalar context, the comma is treated like C’s comma operator, which
-throws away the left argument, which is not what you want. See
-<a href="#perlref-NAME">perlref NAME</a> for more on this.
-</p>
-<p>This warning will not be issued for numerical constants equal to 0 or 1
-since they are often used in statements like
-</p>
-<pre class="verbatim"> 1 while sub_with_side_effects();
-</pre>
-<p>String constants that would normally evaluate to 0 or 1 are warned
-about.
-</p>
-</dd>
-<dt>Useless use of (?-p) in regex; marked by <– HERE<!-- /@w -->
in m/%s/</dt>
-<dd><a
name="perldiag-Useless-use-of-_0028_003f_002dp_0029-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) The <code>p</code> modifier cannot be turned off once set.
Trying to do
-so is futile.
-</p>
-</dd>
-<dt>Useless use of "re" pragma</dt>
-<dd><a name="perldiag-Useless-use-of-_0022re_0022-pragma"></a>
-<p>(W) You did <code>use re;</code> without any arguments. That isn’t
very useful.
-</p>
-</dd>
-<dt>Useless use of sort in scalar context</dt>
-<dd><a name="perldiag-Useless-use-of-sort-in-scalar-context"></a>
-<p>(W void) You used sort in scalar context, as in :
-</p>
-<pre class="verbatim"> my $x = sort @y;
-</pre>
-<p>This is not very useful, and perl currently optimizes this away.
-</p>
-</dd>
-<dt>Useless use of %s with no values</dt>
-<dd><a name="perldiag-Useless-use-of-_0025s-with-no-values"></a>
-<p>(W syntax) You used the push() or unshift() function with no arguments
-apart from the array, like <code>push(@x)</code> or
<code>unshift(@foo)</code>. That won’t
-usually have any effect on the array, so is completely useless. It’s
-possible in principle that push(@tied_array) could have some effect
-if the array is tied to a class which implements a PUSH method. If so,
-you can write it as <code>push(@tied_array,())</code> to avoid this warning.
-</p>
-</dd>
-<dt>"use" not allowed in expression</dt>
-<dd><a name="perldiag-_0022use_0022-not-allowed-in-expression"></a>
-<p>(F) The "use" keyword is recognized and executed at compile time,
and
-returns no useful value. See <a href="#perlmod-NAME">perlmod NAME</a>.
-</p>
-</dd>
-<dt>Use of assignment to $[ is deprecated</dt>
-<dd><a name="perldiag-Use-of-assignment-to-_0024_005b-is-deprecated"></a>
-<p>(D deprecated) The <code>$[</code> variable (index of the first element in
an array)
-is deprecated. See <a href="#perlvar-_0024_005b">perlvar $[</a>.
-</p>
-</dd>
-<dt>Use of bare << to mean <<"" is deprecated</dt>
-<dd><a
name="perldiag-Use-of-bare-_003c_003c-to-mean-_003c_003c_0022_0022-is-deprecated"></a>
-<p>(D deprecated) You are now encouraged to use the explicitly quoted
-form if you wish to use an empty line as the terminator of the
-here-document.
-</p>
-</dd>
-<dt>Use of \b{} for non-UTF-8 locale is wrong. Assuming a UTF-8 locale</dt>
-<dd><a
name="perldiag-Use-of-_005cb_007b_007d-for-non_002dUTF_002d8-locale-is-wrong_002e-Assuming-a-UTF_002d8-locale"></a>
-<p>(W locale) You are matching a regular expression using locale rules,
-and a Unicode boundary is being matched, but the locale is not a Unicode
-one. This doesn’t make sense. Perl will continue, assuming a Unicode
-(UTF-8) locale, but the results could well be wrong except if the locale
-happens to be ISO-8859-1 (Latin1) where this message is spurious and can
-be ignored.
-</p>
-</dd>
-<dt>Use of chdir(”) or chdir(undef) as chdir() deprecated</dt>
-<dd><a
name="perldiag-Use-of-chdir_0028_0027_0027_0029-or-chdir_0028undef_0029-as-chdir_0028_0029-deprecated"></a>
-<p>(D deprecated) chdir() with no arguments is documented to change to
-$ENV{HOME} or $ENV{LOGDIR}. chdir(undef) and chdir(”) share this
-behavior, but that has been deprecated. In future versions they
-will simply fail.
-</p>
-<p>Be careful to check that what you pass to chdir() is defined and not
-blank, else you might find yourself in your home directory.
-</p>
-</dd>
-<dt>Use of /c modifier is meaningless in s///</dt>
-<dd><a
name="perldiag-Use-of-_002fc-modifier-is-meaningless-in-s_002f_002f_002f"></a>
-<p>(W regexp) You used the /c modifier in a substitution. The /c
-modifier is not presently meaningful in substitutions.
-</p>
-</dd>
-<dt>Use of /c modifier is meaningless without /g</dt>
-<dd><a
name="perldiag-Use-of-_002fc-modifier-is-meaningless-without-_002fg"></a>
-<p>(W regexp) You used the /c modifier with a regex operand, but didn’t
-use the /g modifier. Currently, /c is meaningful only when /g is
-used. (This may change in the future.)
-</p>
-</dd>
-<dt>Use of comma-less variable list is deprecated</dt>
-<dd><a name="perldiag-Use-of-comma_002dless-variable-list-is-deprecated"></a>
-<p>(D deprecated) The values you give to a format should be
-separated by commas, not just aligned on a line.
-</p>
-</dd>
-<dt>Use of each() on hash after insertion without resetting hash iterator
results in undefined behavior</dt>
-<dd><a
name="perldiag-Use-of-each_0028_0029-on-hash-after-insertion-without-resetting-hash-iterator-results-in-undefined-behavior"></a>
-<p>(S internal) The behavior of <code>each()</code> after insertion is
undefined;
-it may skip items, or visit items more than once. Consider using
-<code>keys()</code> instead of <code>each()</code>.
-</p>
-</dd>
-<dt>Use of := for an empty attribute list is not allowed</dt>
-<dd><a
name="perldiag-Use-of-_003a_003d-for-an-empty-attribute-list-is-not-allowed"></a>
-<p>(F) The construction <code>my $x := 42</code> used to parse as equivalent to
-<code>my $x : = 42</code> (applying an empty attribute list to
<code>$x</code>).
-This construct was deprecated in 5.12.0, and has now been made a syntax
-error, so <code>:=</code> can be reclaimed as a new operator in the future.
-</p>
-<p>If you need an empty attribute list, for example in a code generator, add
-a space before the <code>=</code>.
-</p>
-</dd>
-<dt>Use of freed value in iteration</dt>
-<dd><a name="perldiag-Use-of-freed-value-in-iteration"></a>
-<p>(F) Perhaps you modified the iterated array within the loop?
-This error is typically caused by code like the following:
-</p>
-<pre class="verbatim"> @a = (3,4);
- @a = () for (1,2,@a);
-</pre>
-<p>You are not supposed to modify arrays while they are being iterated over.
-For speed and efficiency reasons, Perl internally does not do full
-reference-counting of iterated items, hence deleting such an item in the
-middle of an iteration causes Perl to see a freed value.
-</p>
-</dd>
-<dt>Use of *glob{FILEHANDLE} is deprecated</dt>
-<dd><a name="perldiag-Use-of-_002aglob_007bFILEHANDLE_007d-is-deprecated"></a>
-<p>(D deprecated) You are now encouraged to use the shorter *glob{IO} form
-to access the filehandle slot within a typeglob.
-</p>
-</dd>
-<dt>Use of /g modifier is meaningless in split</dt>
-<dd><a name="perldiag-Use-of-_002fg-modifier-is-meaningless-in-split"></a>
-<p>(W regexp) You used the /g modifier on the pattern for a <code>split</code>
-operator. Since <code>split</code> always tries to match the pattern
-repeatedly, the <code>/g</code> has no effect.
-</p>
-</dd>
-<dt>Use of "goto" to jump into a construct is deprecated</dt>
-<dd><a
name="perldiag-Use-of-_0022goto_0022-to-jump-into-a-construct-is-deprecated"></a>
-<p>(D deprecated) Using <code>goto</code> to jump from an outer scope into an
inner
-scope is deprecated and should be avoided.
-</p>
-</dd>
-<dt>Use of inherited AUTOLOAD for non-method %s() is deprecated</dt>
-<dd><a
name="perldiag-Use-of-inherited-AUTOLOAD-for-non_002dmethod-_0025s_0028_0029-is-deprecated"></a>
-<p>(D deprecated) As an (ahem) accidental feature, <code>AUTOLOAD</code>
-subroutines are looked up as methods (using the <code>@ISA</code> hierarchy)
-even when the subroutines to be autoloaded were called as plain
-functions (e.g. <code>Foo::bar()</code>), not as methods (e.g.
<code>Foo->bar()</code> or
-<code>$obj->bar()</code>).
-</p>
-<p>This bug will be rectified in future by using method lookup only for
-methods’ <code>AUTOLOAD</code>s. However, there is a significant base
of existing
-code that may be using the old behavior. So, as an interim step, Perl
-currently issues an optional warning when non-methods use inherited
-<code>AUTOLOAD</code>s.
-</p>
-<p>The simple rule is: Inheritance will not work when autoloading
-non-methods. The simple fix for old code is: In any module that used
-to depend on inheriting <code>AUTOLOAD</code> for non-methods from a base class
-named <code>BaseClass</code>, execute <code>*AUTOLOAD =
\&BaseClass::AUTOLOAD</code> during
-startup.
-</p>
-<p>In code that currently says <code>use AutoLoader; @ISA =
qw(AutoLoader);</code>
-you should remove AutoLoader from @ISA and change <code>use AutoLoader;</code>
to
-<code>use AutoLoader 'AUTOLOAD';</code>.
-</p>
-</dd>
-<dt>Use of %s in printf format not supported</dt>
-<dd><a name="perldiag-Use-of-_0025s-in-printf-format-not-supported"></a>
-<p>(F) You attempted to use a feature of printf that is accessible from
-only C. This usually means there’s a better way to do it in Perl.
-</p>
-</dd>
-<dt>Use of %s is deprecated</dt>
-<dd><a name="perldiag-Use-of-_0025s-is-deprecated"></a>
-<p>(D deprecated) The construct indicated is no longer recommended for use,
-generally because there’s a better way to do it, and also because the
-old way has bad side effects.
-</p>
-</dd>
-<dt>Use of literal control characters in variable names is deprecated</dt>
-<dd><a
name="perldiag-Use-of-literal-control-characters-in-variable-names-is-deprecated"></a>
-</dd>
-<dt>Use of literal non-graphic characters in variable names is deprecated</dt>
-<dd><a
name="perldiag-Use-of-literal-non_002dgraphic-characters-in-variable-names-is-deprecated"></a>
-<p>(D deprecated) Using literal non-graphic (including control)
-characters in the source to refer to the ^FOO variables, like <code>$^X</code>
and
-<code>${^GLOBAL_PHASE}</code> is now deprecated. (We use <code>^X</code> and
<code>^G</code> here for
-legibility. They actually represent the non-printable control
-characters, code points 0x18 and 0x07, respectively; <code>^A</code> would mean
-the control character whose code point is 0x01.) This only affects
-code like <code>$\cT</code>, where <code>\cT</code> is a control in the source
code; <code>${"\cT"}</code> and
-<code>$^T</code> remain valid. Things that are non-controls and also not
graphic
-are NO-BREAK SPACE and SOFT HYPHEN, which were previously only allowed
-for historical reasons.
-</p>
-</dd>
-<dt>Use of -l on filehandle%s</dt>
-<dd><a name="perldiag-Use-of-_002dl-on-filehandle_0025s"></a>
-<p>(W io) A filehandle represents an opened file, and when you opened the file
-it already went past any symlink you are presumably trying to look for.
-The operation returned <code>undef</code>. Use a filename instead.
-</p>
-</dd>
-<dt>Use of my $_ is experimental</dt>
-<dd><a name="perldiag-Use-of-my-_0024_005f-is-experimental"></a>
-<p>(S experimental::lexical_topic) Lexical $_ is an experimental feature and
-its behavior may change or even be removed in any future release of perl.
-See the explanation under <a href="#perlvar-_0024_005f">perlvar $_</a>.
-</p>
-</dd>
-<dt>Use of %s on a handle without * is deprecated</dt>
-<dd><a
name="perldiag-Use-of-_0025s-on-a-handle-without-_002a-is-deprecated"></a>
-<p>(D deprecated) You used <code>tie</code>, <code>tied</code> or
<code>untie</code> 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 <code>tie *$handle</code>.
-</p>
-<p>This was a long-standing bug that was removed in Perl 5.16, as there was
-no way to tie the scalar itself when it held a typeglob, and no way to
-untie a scalar that had had a typeglob assigned to it. If you see this
-message, you must be using an older version.
-</p>
-</dd>
-<dt>Use of reference "%s" as array index</dt>
-<dd><a name="perldiag-Use-of-reference-_0022_0025s_0022-as-array-index"></a>
-<p>(W misc) You tried to use a reference as an array index; this probably
-isn’t what you mean, because references in numerical context tend
-to be huge numbers, and so usually indicates programmer error.
-</p>
-<p>If you really do mean it, explicitly numify your reference, like so:
-<code>$array[0+$ref]</code>. This warning is not given for overloaded objects,
-however, because you can overload the numification and stringification
-operators and then you presumably know what you are doing.
-</p>
-</dd>
-<dt>Use of state $_ is experimental</dt>
-<dd><a name="perldiag-Use-of-state-_0024_005f-is-experimental"></a>
-<p>(S experimental::lexical_topic) Lexical $_ is an experimental feature and
-its behavior may change or even be removed in any future release of perl.
-See the explanation under <a href="#perlvar-_0024_005f">perlvar $_</a>.
-</p>
-</dd>
-<dt>Use of tainted arguments in %s is deprecated</dt>
-<dd><a name="perldiag-Use-of-tainted-arguments-in-_0025s-is-deprecated"></a>
-<p>(W taint, deprecated) You have supplied <code>system()</code> or
<code>exec()</code> with multiple
-arguments and at least one of them is tainted. This used to be allowed
-but will become a fatal error in a future version of perl. Untaint your
-arguments. See <a href="#perlsec-NAME">perlsec NAME</a>.
-</p>
-</dd>
-<dt>Use of uninitialized value%s</dt>
-<dd><a name="perldiag-Use-of-uninitialized-value_0025s"></a>
-<p>(W uninitialized) An undefined value was used as if it were already
-defined. It was interpreted as a "" or a 0, but maybe it was a
mistake.
-To suppress this warning assign a defined value to your variables.
-</p>
-<p>To help you figure out what was undefined, perl will try to tell you
-the name of the variable (if any) that was undefined. In some cases
-it cannot do this, so it also tells you what operation you used the
-undefined value in. Note, however, that perl optimizes your program
-and the operation displayed in the warning may not necessarily appear
-literally in your program. For example, <code>"that $foo"</code> is
usually
-optimized into <code>"that " . $foo</code>, and the warning will
refer to the
-<code>concatenation (.)</code> operator, even though there is no
<code>.</code> in
-your program.
-</p>
-</dd>
-<dt>"use re ’strict’" is experimental</dt>
-<dd><a name="perldiag-_0022use-re-_0027strict_0027_0022-is-experimental"></a>
-<p>(S experimental::re_strict) The things that are different when a regular
-expression pattern is compiled under <code>'strict'</code> are subject to
change
-in future Perl releases in incompatible ways. This means that a pattern
-that compiles today may not in a future Perl release. This warning is
-to alert you to that risk.
-</p>
-</dd>
-<dt>Use \x{...} for more than two hex characters in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Use-_005cx_007b_002e_002e_002e_007d-for-more-than-two-hex-characters-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) In a regular expression, you said something like
-</p>
-<pre class="verbatim"> (?[ [ \xBEEF ] ])
-</pre>
-<p>Perl isn’t sure if you meant this
-</p>
-<pre class="verbatim"> (?[ [ \x{BEEF} ] ])
-</pre>
-<p>or if you meant this
-</p>
-<pre class="verbatim"> (?[ [ \x{BE} E F ] ])
-</pre>
-<p>You need to add either braces or blanks to disambiguate.
-</p>
-</dd>
-<dt>Using just the first character returned by \N{} in character class in
regex; marked by <– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Using-just-the-first-character-returned-by-_005cN_007b_007d-in-character-class-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) Named Unicode character escapes <code>(\N{...})</code> may return
-a multi-character sequence. Even though a character class is
-supposed to match just one character of input, perl will match
-the whole thing correctly, except when the class is inverted
-(<code>[^...]</code>), or the escape is the beginning or final end point of
-a range. For these, what should happen isn’t clear at all. In
-these circumstances, Perl discards all but the first character
-of the returned sequence, which is not likely what you want.
-</p>
-</dd>
-<dt>Using /u for ’%s’ instead of /%s in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Using-_002fu-for-_0027_0025s_0027-instead-of-_002f_0025s-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(W regexp) You used a Unicode boundary (<code>\b{...}</code> or
<code>\B{...}</code>) in a
-portion of a regular expression where the character set modifiers
<code>/a</code>
-or <code>/aa</code> are in effect. These two modifiers indicate an ASCII
-interpretation, and this doesn’t make sense for a Unicode defintion.
-The generated regular expression will compile so that the boundary uses
-all of Unicode. No other portion of the regular expression is affected.
-</p>
-</dd>
-<dt>Using !~ with %s doesn’t make sense</dt>
-<dd><a name="perldiag-Using-_0021_007e-with-_0025s-doesn_0027t-make-sense"></a>
-<p>(F) Using the <code>!~</code> operator with <code>s///r</code>,
<code>tr///r</code> or <code>y///r</code> is
-currently reserved for future use, as the exact behavior has not
-been decided. (Simply returning the boolean opposite of the
-modified string is usually not particularly useful.)
-</p>
-</dd>
-<dt>UTF-16 surrogate U+%X</dt>
-<dd><a name="perldiag-UTF_002d16-surrogate-U_002b_0025X"></a>
-<p>(S 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 <code>no warnings 'surrogate';</code>.
-</p>
-</dd>
-<dt>Value of %s can be "0"; test with defined()</dt>
-<dd><a
name="perldiag-Value-of-_0025s-can-be-_00220_0022_003b-test-with-defined_0028_0029"></a>
-<p>(W misc) In a conditional expression, you used <HANDLE>, <*>
(glob),
-<code>each()</code>, or <code>readdir()</code> as a boolean value. Each of
these constructs
-can return a value of "0"; that would make the conditional expression
-false, which is probably not what you intended. When using these
-constructs in conditional expressions, test their values with the
-<code>defined</code> operator.
-</p>
-</dd>
-<dt>Value of CLI symbol "%s" too long</dt>
-<dd><a name="perldiag-Value-of-CLI-symbol-_0022_0025s_0022-too-long"></a>
-<p>(W misc) A warning peculiar to VMS. Perl tried to read the value of an
-%ENV element from a CLI symbol table, and found a resultant string
-longer than 1024 characters. The return value has been truncated to
-1024 characters.
-</p>
-</dd>
-<dt>values on reference is experimental</dt>
-<dd><a name="perldiag-values-on-reference-is-experimental"></a>
-<p>(S experimental::autoderef) <code>values</code> with a scalar argument
-is experimental and may change or be removed in a future
-Perl version. If you want to take the risk of using this
-feature, simply disable this warning:
-</p>
-<pre class="verbatim"> no warnings "experimental::autoderef";
-</pre>
-</dd>
-<dt>Variable "%s" is not available</dt>
-<dd><a name="perldiag-Variable-_0022_0025s_0022-is-not-available"></a>
-<p>(W closure) During compilation, an inner named subroutine or eval is
-attempting to capture an outer lexical that is not currently available.
-This can happen for one of two reasons. First, the outer lexical may be
-declared in an outer anonymous subroutine that has not yet been created.
-(Remember that named subs are created at compile time, while anonymous
-subs are created at run-time.) For example,
-</p>
-<pre class="verbatim"> sub { my $a; sub f { $a } }
-</pre>
-<p>At the time that f is created, it can’t capture the current value of
$a,
-since the anonymous subroutine hasn’t been created yet. Conversely,
-the following won’t give a warning since the anonymous subroutine has by
-now been created and is live:
-</p>
-<pre class="verbatim"> sub { my $a; eval 'sub f { $a }' }->();
-</pre>
-<p>The second situation is caused by an eval accessing a variable that has
-gone out of scope, for example,
-</p>
-<pre class="verbatim"> sub f {
- my $a;
- sub { eval '$a' }
- }
- f()->();
-</pre>
-<p>Here, when the ’$a’ in the eval is being compiled, f() is not
currently
-being executed, so its $a is not available for capture.
-</p>
-</dd>
-<dt>Variable "%s" is not imported%s</dt>
-<dd><a name="perldiag-Variable-_0022_0025s_0022-is-not-imported_0025s"></a>
-<p>(S misc) With "use strict" in effect, you referred to a global
variable
-that you apparently thought was imported from another module, because
-something else of the same name (usually a subroutine) is exported by
-that module. It usually means you put the wrong funny character on the
-front of your variable.
-</p>
-</dd>
-<dt>Variable length lookbehind not implemented in regex m/%s/</dt>
-<dd><a
name="perldiag-Variable-length-lookbehind-not-implemented-in-regex-m_002f_0025s_002f"></a>
-<p>(F) Lookbehind is allowed only for subexpressions whose length is fixed and
-known at compile time. For positive lookbehind, you can use the
<code>\K</code>
-regex construct as a way to get the equivalent functionality. See
-<a href="#perlre-_0028_003f_003c_003dpattern_0029-_005cK">perlre
<code>(?<=pattern)</code> <code>\K</code></a>.
-</p>
-<p>There are non-obvious Unicode rules under <code>/i</code> that can match
variably,
-but which you might not think could. For example, the substring
<code>"ss"</code>
-can match the single character LATIN SMALL LETTER SHARP S. There are
-other sequences of ASCII characters that can match single ligature
-characters, such as LATIN SMALL LIGATURE FFI matching <code>qr/ffi/i</code>.
-Starting in Perl v5.16, if you only care about ASCII matches, adding the
-<code>/aa</code> modifier to the regex will exclude all these non-obvious
matches,
-thus getting rid of this message. You can also say
<code>use re qw(/aa)<!-- /@w --></code>
-to apply <code>/aa</code> to all regular expressions compiled within its scope.
-See <a href="re.html#Top">(re)</a>.
-</p>
-</dd>
-<dt>"%s" variable %s masks earlier declaration in same %s</dt>
-<dd><a
name="perldiag-_0022_0025s_0022-variable-_0025s-masks-earlier-declaration-in-same-_0025s"></a>
-<p>(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 references to it are destroyed.
-</p>
-</dd>
-<dt>Variable syntax</dt>
-<dd><a name="perldiag-Variable-syntax"></a>
-<p>(A) You’ve accidentally run your script through <strong>csh</strong>
instead
-of Perl. Check the #! line, or manually feed your script into
-Perl yourself.
-</p>
-</dd>
-<dt>Variable "%s" will not stay shared</dt>
-<dd><a name="perldiag-Variable-_0022_0025s_0022-will-not-stay-shared"></a>
-<p>(W closure) An inner (nested) <em>named</em> subroutine is referencing a
-lexical variable defined in an outer named subroutine.
-</p>
-<p>When the inner subroutine is called, it will see the value of
-the outer subroutine’s variable as it was before and during the *first*
-call to the outer subroutine; in this case, after the first call to the
-outer subroutine is complete, the inner and outer subroutines will no
-longer share a common value for the variable. In other words, the
-variable will no longer be shared.
-</p>
-<p>This problem can usually be solved by making the inner subroutine
-anonymous, using the <code>sub {}</code> syntax. When inner anonymous subs
that
-reference variables in outer subroutines are created, they
-are automatically rebound to the current values of such variables.
-</p>
-</dd>
-<dt>vector argument not supported with alpha versions</dt>
-<dd><a name="perldiag-vector-argument-not-supported-with-alpha-versions"></a>
-<p>(S printf) The %vd (s)printf format does not support version objects
-with alpha parts.
-</p>
-</dd>
-<dt>Verb pattern ’%s’ has a mandatory argument in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Verb-pattern-_0027_0025s_0027-has-a-mandatory-argument-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You used a verb pattern that requires an argument. Supply an
-argument or check that you are using the right verb.
-</p>
-</dd>
-<dt>Verb pattern ’%s’ may not have an argument in regex; marked by
<– HERE<!-- /@w --> in m/%s/</dt>
-<dd><a
name="perldiag-Verb-pattern-_0027_0025s_0027-may-not-have-an-argument-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) You used a verb pattern that is not allowed an argument. Remove the
-argument or check that you are using the right verb.
-</p>
-</dd>
-<dt>Version number must be a constant number</dt>
-<dd><a name="perldiag-Version-number-must-be-a-constant-number"></a>
-<p>(P) The attempt to translate a <code>use Module n.n LIST</code> statement
into
-its equivalent <code>BEGIN</code> block found an internal inconsistency with
-the version number.
-</p>
-</dd>
-<dt>Version string ’%s’ contains invalid data; ignoring:
’%s’</dt>
-<dd><a
name="perldiag-Version-string-_0027_0025s_0027-contains-invalid-data_003b-ignoring_003a-_0027_0025s_0027"></a>
-<p>(W misc) The version string contains invalid characters at the end, which
-are being ignored.
-</p>
-</dd>
-<dt>Warning: something’s wrong</dt>
-<dd><a name="perldiag-Warning_003a-something_0027s-wrong"></a>
-<p>(W) You passed warn() an empty string (the equivalent of <code>warn
""</code>) or
-you called it with no args and <code>$@</code> was empty.
-</p>
-</dd>
-<dt>Warning: unable to close filehandle %s properly</dt>
-<dd><a
name="perldiag-Warning_003a-unable-to-close-filehandle-_0025s-properly"></a>
-<p>(S) The implicit close() done by an open() got an error indication on
-the close(). This usually indicates your file system ran out of disk
-space.
-</p>
-</dd>
-<dt>Warning: unable to close filehandle properly: %s</dt>
-<dd><a
name="perldiag-Warning_003a-unable-to-close-filehandle-properly_003a-_0025s"></a>
-</dd>
-<dt>Warning: unable to close filehandle %s properly: %s</dt>
-<dd><a
name="perldiag-Warning_003a-unable-to-close-filehandle-_0025s-properly_003a-_0025s"></a>
-<p>(S io) An error occurred when Perl implicitly closed a filehandle. This
-usually indicates your file system ran out of disk space.
-</p>
-</dd>
-<dt>Warning: Use of "%s" without parentheses is ambiguous</dt>
-<dd><a
name="perldiag-Warning_003a-Use-of-_0022_0025s_0022-without-parentheses-is-ambiguous"></a>
-<p>(S ambiguous) You wrote a unary operator followed by something that
-looks like a binary operator that could also have been interpreted as a
-term or unary operator. For instance, if you know that the rand
-function has a default argument of 1.0, and you write
-</p>
-<pre class="verbatim"> rand + 5;
-</pre>
-<p>you may THINK you wrote the same thing as
-</p>
-<pre class="verbatim"> rand() + 5;
-</pre>
-<p>but in actual fact, you got
-</p>
-<pre class="verbatim"> rand(+5);
-</pre>
-<p>So put in parentheses to say what you really mean.
-</p>
-</dd>
-<dt>when is experimental</dt>
-<dd><a name="perldiag-when-is-experimental"></a>
-<p>(S experimental::smartmatch) <code>when</code> depends on smartmatch, which
is
-experimental. Additionally, it has several special cases that may
-not be immediately obvious, and their behavior may change or
-even be removed in any future release of perl. See the explanation
-under <a href="#perlsyn-Experimental-Details-on-given-and-when">perlsyn
Experimental Details on given and when</a>.
-</p>
-</dd>
-<dt>Wide character in %s</dt>
-<dd><a name="perldiag-Wide-character-in-_0025s"></a>
-<p>(S utf8) Perl met a wide character (>255) when it wasn’t expecting
-one. This warning is by default on for I/O (like print). The easiest
-way to quiet this warning is simply to add the <code>:utf8</code> layer to the
-output, e.g. <code>binmode STDOUT, ':utf8'</code>. Another way to turn off the
-warning is to add <code>no warnings 'utf8';</code> but that is often closer to
-cheating. In general, you are supposed to explicitly mark the
-filehandle with an encoding, see <a href="open.html#Top">(open)</a> and
‘perlfunc binmode’.
-</p>
-</dd>
-<dt>Wide character (U+%X) in %s</dt>
-<dd><a name="perldiag-Wide-character-_0028U_002b_0025X_0029-in-_0025s"></a>
-<p>(W locale) While in a single-byte locale (<em>i.e.</em>, a non-UTF-8
-one), a multi-byte character was encountered. Perl considers this
-character to be the specified Unicode code point. Combining non-UTF-8
-locales and Unicode is dangerous. Almost certainly some characters
-will have two different representations. For example, in the ISO 8859-7
-(Greek) locale, the code point 0xC3 represents a Capital Gamma. But so
-also does 0x393. This will make string comparisons unreliable.
-</p>
-<p>You likely need to figure out how this multi-byte character got mixed up
-with your single-byte locale (or perhaps you thought you had a UTF-8
-locale, but Perl disagrees).
-</p>
-</dd>
-<dt>Within []-length ’%c’ not allowed</dt>
-<dd><a
name="perldiag-Within-_005b_005d_002dlength-_0027_0025c_0027-not-allowed"></a>
-<p>(F) The count in the (un)pack template may be replaced by
<code>[TEMPLATE]</code>
-only if <code>TEMPLATE</code> always matches the same amount of packed bytes
that
-can be determined from the template alone. This is not possible if
-it contains any of the codes @, /, U, u, w or a *-length. Redesign
-the template.
-</p>
-</dd>
-<dt>write() on closed filehandle %s</dt>
-<dd><a name="perldiag-write_0028_0029-on-closed-filehandle-_0025s"></a>
-<p>(W closed) The filehandle you’re writing to got itself closed sometime
-before now. Check your control flow.
-</p>
-</dd>
-<dt>%s "\x%X" does not map to Unicode</dt>
-<dd><a
name="perldiag-_0025s-_0022_005cx_0025X_0022-does-not-map-to-Unicode"></a>
-<p>(S utf8) 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
-</p>
-<pre class="verbatim"> utf8 "\xE4" does not map to Unicode
-</pre>
-<p>if you try to read in the a-diaereses Latin-1 as UTF-8.
-</p>
-</dd>
-<dt>’X’ outside of string</dt>
-<dd><a name="perldiag-_0027X_0027-outside-of-string"></a>
-<p>(F) You had a (un)pack template that specified a relative position before
-the beginning of the string being (un)packed. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>’x’ outside of string in unpack</dt>
-<dd><a name="perldiag-_0027x_0027-outside-of-string-in-unpack"></a>
-<p>(F) You had a pack template that specified a relative position after
-the end of the string being unpacked. See ‘perlfunc pack’.
-</p>
-</dd>
-<dt>YOU HAVEN’T DISABLED SET-ID SCRIPTS IN THE KERNEL YET!</dt>
-<dd><a
name="perldiag-YOU-HAVEN_0027T-DISABLED-SET_002dID-SCRIPTS-IN-THE-KERNEL-YET_0021"></a>
-<p>(F) And you probably never will, because you probably don’t have the
-sources to your kernel, and your vendor probably doesn’t give a rip
-about what you want. Your best bet is to put a setuid C wrapper around
-your script.
-</p>
-</dd>
-<dt>You need to quote "%s"</dt>
-<dd><a name="perldiag-You-need-to-quote-_0022_0025s_0022"></a>
-<p>(W syntax) You assigned a bareword as a signal handler name.
-Unfortunately, you already have a subroutine of that name declared,
-which means that Perl 5 will try to call the subroutine when the
-assignment is executed, which is probably not what you want. (If it IS
-what you want, put an & in front.)
-</p>
-</dd>
-<dt>Your random numbers are not that random</dt>
-<dd><a name="perldiag-Your-random-numbers-are-not-that-random"></a>
-<p>(F) When trying to initialize the random seed for hashes, Perl could
-not get any randomness out of your system. This usually indicates
-Something Very Wrong.
-</p>
-</dd>
-<dt>Zero length \N{} in regex; marked by <– HERE<!-- /@w --> in
m/%s/</dt>
-<dd><a
name="perldiag-Zero-length-_005cN_007b_007d-in-regex_003b-marked-by-_003c_002d_002d-HERE-in-m_002f_0025s_002f"></a>
-<p>(F) Named Unicode character escapes (<code>\N{...}</code>) may return a
zero-length
-sequence. Such an escape was used in an extended character class, i.e.
-<code>(?[...])</code>, which is not permitted. Check that the correct escape
has
-been used, and the correct charnames handler is in scope. The
<– HERE<!-- /@w -->
-shows whereabouts in the regular expression the problem was discovered.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perldiag-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldiag-DESCRIPTION" accesskey="p" rel="prev">perldiag
DESCRIPTION</a>, Up: <a href="#perldiag" accesskey="u" rel="up">perldiag</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-9"></a>
-<h3 class="section">16.3 SEE ALSO</h3>
-
-<p><a href="warnings.html#Top">(warnings)</a>, <a
href="diagnostics.html#Top">(diagnostics)</a>.
-</p>
-<hr>
-<a name="perldsc"></a>
-<div class="header">
-<p>
-Next: <a href="#perldtrace" accesskey="n" rel="next">perldtrace</a>, Previous:
<a href="#perldiag" accesskey="p" rel="prev">perldiag</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perldsc-1"></a>
-<h2 class="chapter">17 perldsc</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perldsc-NAME"
accesskey="1">perldsc NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldsc-DESCRIPTION"
accesskey="2">perldsc DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldsc-REFERENCES"
accesskey="3">perldsc REFERENCES</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldsc-COMMON-MISTAKES"
accesskey="4">perldsc COMMON MISTAKES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-CAVEAT-ON-PRECEDENCE" accesskey="5">perldsc CAVEAT ON
PRECEDENCE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-WHY-YOU-SHOULD-ALWAYS-use-strict" accesskey="6">perldsc WHY YOU
SHOULD ALWAYS <code>use strict</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldsc-DEBUGGING"
accesskey="7">perldsc DEBUGGING</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldsc-CODE-EXAMPLES"
accesskey="8">perldsc CODE EXAMPLES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldsc-ARRAYS-OF-ARRAYS"
accesskey="9">perldsc ARRAYS OF ARRAYS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-HASHES-OF-ARRAYS">perldsc HASHES OF
ARRAYS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-ARRAYS-OF-HASHES">perldsc ARRAYS OF
HASHES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-HASHES-OF-HASHES">perldsc HASHES OF
HASHES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-MORE-ELABORATE-RECORDS">perldsc MORE ELABORATE
RECORDS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Database-Ties">perldsc Database
Ties</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldsc-SEE-ALSO">perldsc
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldsc-AUTHOR">perldsc
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldsc-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-DESCRIPTION" accesskey="n" rel="next">perldsc
DESCRIPTION</a>, Up: <a href="#perldsc" accesskey="u" rel="up">perldsc</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-16"></a>
-<h3 class="section">17.1 NAME</h3>
-
-<p>perldsc - Perl Data Structures Cookbook
-</p>
-<hr>
-<a name="perldsc-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-REFERENCES" accesskey="n" rel="next">perldsc
REFERENCES</a>, Previous: <a href="#perldsc-NAME" accesskey="p"
rel="prev">perldsc NAME</a>, Up: <a href="#perldsc" accesskey="u"
rel="up">perldsc</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-16"></a>
-<h3 class="section">17.2 DESCRIPTION</h3>
-
-<p>Perl lets us have complex data structures. You can write something like
-this and all of a sudden, you’d have an array with three dimensions!
-</p>
-<pre class="verbatim"> for my $x (1 .. 10) {
- for my $y (1 .. 10) {
- for my $z (1 .. 10) {
- $AoA[$x][$y][$z] =
- $x ** $y + $z;
- }
- }
- }
-</pre>
-<p>Alas, however simple this may appear, underneath it’s a much more
-elaborate construct than meets the eye!
-</p>
-<p>How do you print it out? Why can’t you say just <code>print
@AoA</code>? How do
-you sort it? How can you pass it to a function or get one of these back
-from a function? Is it an object? Can you save it to disk to read
-back later? How do you access whole rows or columns of that matrix? Do
-all the values have to be numeric?
-</p>
-<p>As you see, it’s quite easy to become confused. While some small
portion
-of the blame for this can be attributed to the reference-based
-implementation, it’s really more due to a lack of existing documentation
with
-examples designed for the beginner.
-</p>
-<p>This document is meant to be a detailed but understandable treatment of the
-many different sorts of data structures you might want to develop. It
-should also serve as a cookbook of examples. That way, when you need to
-create one of these complex data structures, you can just pinch, pilfer, or
-purloin a drop-in example from here.
-</p>
-<p>Let’s look at each of these possible constructs in detail. There are
separate
-sections on each of the following:
-</p>
-<ul>
-<li> arrays of arrays
-
-</li><li> hashes of arrays
-
-</li><li> arrays of hashes
-
-</li><li> hashes of hashes
-
-</li><li> more elaborate constructs
-
-</li></ul>
-
-<p>But for now, let’s look at general issues common to all
-these types of data structures.
-</p>
-<hr>
-<a name="perldsc-REFERENCES"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-COMMON-MISTAKES" accesskey="n" rel="next">perldsc
COMMON MISTAKES</a>, Previous: <a href="#perldsc-DESCRIPTION" accesskey="p"
rel="prev">perldsc DESCRIPTION</a>, Up: <a href="#perldsc" accesskey="u"
rel="up">perldsc</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="REFERENCES"></a>
-<h3 class="section">17.3 REFERENCES</h3>
-
-<p>The most important thing to understand about all data structures in
-Perl–including multidimensional arrays–is that even though they
might
-appear otherwise, Perl <code>@ARRAY</code>s and <code>%HASH</code>es are all
internally
-one-dimensional. They can hold only scalar values (meaning a string,
-number, or a reference). They cannot directly contain other arrays or
-hashes, but instead contain <em>references</em> to other arrays or hashes.
-</p>
-<p>You can’t use a reference to an array or hash in quite the same way
that you
-would a real array or hash. For C or C++ programmers unused to
-distinguishing between arrays and pointers to the same, this can be
-confusing. If so, just think of it as the difference between a structure
-and a pointer to a structure.
-</p>
-<p>You can (and should) read more about references in <a
href="#perlref-NAME">perlref NAME</a>.
-Briefly, references are rather like pointers that know what they
-point to. (Objects are also a kind of reference, but we won’t be needing
-them right away–if ever.) This means that when you have something which
-looks to you like an access to a two-or-more-dimensional array and/or hash,
-what’s really going on is that the base type is
-merely a one-dimensional entity that contains references to the next
-level. It’s just that you can <em>use</em> it as though it were a
-two-dimensional one. This is actually the way almost all C
-multidimensional arrays work as well.
-</p>
-<pre class="verbatim"> $array[7][12] # array of arrays
- $array[7]{string} # array of hashes
- $hash{string}[7] # hash of arrays
- $hash{string}{'another string'} # hash of hashes
-</pre>
-<p>Now, because the top level contains only references, if you try to print
-out your array in with a simple print() function, you’ll get something
-that doesn’t look very nice, like this:
-</p>
-<pre class="verbatim"> my @AoA = ( [2, 3], [4, 5, 7], [0] );
- print $AoA[1][2];
- 7
- print @AoA;
- ARRAY(0x83c38)ARRAY(0x8b194)ARRAY(0x8b1d0)
-</pre>
-<p>That’s because Perl doesn’t (ever) implicitly dereference your
variables.
-If you want to get at the thing a reference is referring to, then you have
-to do this yourself using either prefix typing indicators, like
-<code>${$blah}</code>, <code>@{$blah}</code>, <code>@{$blah[$i]}</code>, or
else postfix pointer arrows,
-like <code>$a->[3]</code>, <code>$h->{fred}</code>, or even
<code>$ob->method()->[3]</code>.
-</p>
-<hr>
-<a name="perldsc-COMMON-MISTAKES"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-CAVEAT-ON-PRECEDENCE" accesskey="n" rel="next">perldsc
CAVEAT ON PRECEDENCE</a>, Previous: <a href="#perldsc-REFERENCES" accesskey="p"
rel="prev">perldsc REFERENCES</a>, Up: <a href="#perldsc" accesskey="u"
rel="up">perldsc</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="COMMON-MISTAKES"></a>
-<h3 class="section">17.4 COMMON MISTAKES</h3>
-
-<p>The two most common mistakes made in constructing something like
-an array of arrays is either accidentally counting the number of
-elements or else taking a reference to the same memory location
-repeatedly. Here’s the case where you just get the count instead
-of a nested array:
-</p>
-<pre class="verbatim"> for my $i (1..10) {
- my @array = somefunc($i);
- $AoA[$i] = @array; # WRONG!
- }
-</pre>
-<p>That’s just the simple case of assigning an array to a scalar and
getting
-its element count. If that’s what you really and truly want, then you
-might do well to consider being a tad more explicit about it, like this:
-</p>
-<pre class="verbatim"> for my $i (1..10) {
- my @array = somefunc($i);
- $counts[$i] = scalar @array;
- }
-</pre>
-<p>Here’s the case of taking a reference to the same memory location
-again and again:
-</p>
-<pre class="verbatim"> # Either without strict or having an outer-scope my
@array;
- # declaration.
-
- for my $i (1..10) {
- @array = somefunc($i);
- $AoA[$i] = address@hidden; # WRONG!
- }
-</pre>
-<p>So, what’s the big problem with that? It looks right, doesn’t
it?
-After all, I just told you that you need an array of references, so by
-golly, you’ve made me one!
-</p>
-<p>Unfortunately, while this is true, it’s still broken. All the
references
-in @AoA refer to the <em>very same place</em>, and they will therefore all hold
-whatever was last in @array! It’s similar to the problem demonstrated in
-the following C program:
-</p>
-<pre class="verbatim"> #include <pwd.h>
- main() {
- struct passwd *getpwnam(), *rp, *dp;
- rp = getpwnam("root");
- dp = getpwnam("daemon");
-
- printf("daemon name is %s\nroot name is %s\n",
- dp->pw_name, rp->pw_name);
- }
-</pre>
-<p>Which will print
-</p>
-<pre class="verbatim"> daemon name is daemon
- root name is daemon
-</pre>
-<p>The problem is that both <code>rp</code> and <code>dp</code> are pointers
to the same location
-in memory! In C, you’d have to remember to malloc() yourself some new
-memory. In Perl, you’ll want to use the array constructor
<code>[]</code> or the
-hash constructor <code>{}</code> instead. Here’s the right way to do
the preceding
-broken code fragments:
-</p>
-<pre class="verbatim"> # Either without strict or having an outer-scope my
@array;
- # declaration.
-
- for my $i (1..10) {
- @array = somefunc($i);
- $AoA[$i] = [ @array ];
- }
-</pre>
-<p>The square brackets make a reference to a new array with a <em>copy</em>
-of what’s in @array at the time of the assignment. This is what
-you want.
-</p>
-<p>Note that this will produce something similar, but it’s
-much harder to read:
-</p>
-<pre class="verbatim"> # Either without strict or having an outer-scope my
@array;
- # declaration.
- for my $i (1..10) {
- @array = 0 .. $i;
- @{$AoA[$i]} = @array;
- }
-</pre>
-<p>Is it the same? Well, maybe so–and maybe not. The subtle difference
-is that when you assign something in square brackets, you know for sure
-it’s always a brand new reference with a new <em>copy</em> of the data.
-Something else could be going on in this new case with the
<code>@{$AoA[$i]}</code>
-dereference on the left-hand-side of the assignment. It all depends on
-whether <code>$AoA[$i]</code> had been undefined to start with, or whether it
-already contained a reference. If you had already populated @AoA with
-references, as in
-</p>
-<pre class="verbatim"> $AoA[3] = address@hidden;
-</pre>
-<p>Then the assignment with the indirection on the left-hand-side would
-use the existing reference that was already there:
-</p>
-<pre class="verbatim"> @{$AoA[3]} = @array;
-</pre>
-<p>Of course, this <em>would</em> have the "interesting" effect of
clobbering
address@hidden (Have you ever noticed how when a programmer says
-something is "interesting", that rather than meaning
"intriguing",
-they’re disturbingly more apt to mean that it’s
"annoying",
-"difficult", or both? :-)
-</p>
-<p>So just remember always to use the array or hash constructors with
<code>[]</code>
-or <code>{}</code>, and you’ll be fine, although it’s not always
optimally
-efficient.
-</p>
-<p>Surprisingly, the following dangerous-looking construct will
-actually work out fine:
-</p>
-<pre class="verbatim"> for my $i (1..10) {
- my @array = somefunc($i);
- $AoA[$i] = address@hidden;
- }
-</pre>
-<p>That’s because my() is more of a run-time statement than it is a
-compile-time declaration <em>per se</em>. This means that the my() variable is
-remade afresh each time through the loop. So even though it <em>looks</em> as
-though you stored the same variable reference each time, you actually did
-not! This is a subtle distinction that can produce more efficient code at
-the risk of misleading all but the most experienced of programmers. So I
-usually advise against teaching it to beginners. In fact, except for
-passing arguments to functions, I seldom like to see the gimme-a-reference
-operator (backslash) used much at all in code. Instead, I advise
-beginners that they (and most of the rest of us) should try to use the
-much more easily understood constructors <code>[]</code> and <code>{}</code>
instead of
-relying upon lexical (or dynamic) scoping and hidden reference-counting to
-do the right thing behind the scenes.
-</p>
-<p>In summary:
-</p>
-<pre class="verbatim"> $AoA[$i] = [ @array ]; # usually best
- $AoA[$i] = address@hidden; # perilous; just how my() was that array?
- @{ $AoA[$i] } = @array; # way too tricky for most programmers
-</pre>
-<hr>
-<a name="perldsc-CAVEAT-ON-PRECEDENCE"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-WHY-YOU-SHOULD-ALWAYS-use-strict" accesskey="n"
rel="next">perldsc WHY YOU SHOULD ALWAYS <code>use strict</code></a>, Previous:
<a href="#perldsc-COMMON-MISTAKES" accesskey="p" rel="prev">perldsc COMMON
MISTAKES</a>, Up: <a href="#perldsc" accesskey="u" rel="up">perldsc</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="CAVEAT-ON-PRECEDENCE"></a>
-<h3 class="section">17.5 CAVEAT ON PRECEDENCE</h3>
-
-<p>Speaking of things like <code>@{$AoA[$i]}</code>, the following are
actually the
-same thing:
- >>
-</p>
-<pre class="verbatim"> $aref->[2][2] # clear
- $$aref[2][2] # confusing
-</pre>
-<p>That’s because Perl’s precedence rules on its five prefix
dereferencers
-(which look like someone swearing: <code>$ @ * % &</code>) make them bind
more
-tightly than the postfix subscripting brackets or braces! This will no
-doubt come as a great shock to the C or C++ programmer, who is quite
-accustomed to using <code>*a[i]</code> to mean what’s pointed to by the
<em>i’th</em>
-element of <code>a</code>. That is, they first take the subscript, and only
then
-dereference the thing at that subscript. That’s fine in C, but this
isn’t C.
-</p>
-<p>The seemingly equivalent construct in Perl, <code>$$aref[$i]</code> first
does
-the deref of $aref, making it take $aref as a reference to an
-array, and then dereference that, and finally tell you the <em>i’th</em>
value
-of the array pointed to by $AoA. If you wanted the C notion, you’d have
to
-write <code>${$AoA[$i]}</code> to force the <code>$AoA[$i]</code> to get
evaluated first
-before the leading <code>$</code> dereferencer.
-</p>
-<hr>
-<a name="perldsc-WHY-YOU-SHOULD-ALWAYS-use-strict"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-DEBUGGING" accesskey="n" rel="next">perldsc
DEBUGGING</a>, Previous: <a href="#perldsc-CAVEAT-ON-PRECEDENCE" accesskey="p"
rel="prev">perldsc CAVEAT ON PRECEDENCE</a>, Up: <a href="#perldsc"
accesskey="u" rel="up">perldsc</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="WHY-YOU-SHOULD-ALWAYS-use-strict"></a>
-<h3 class="section">17.6 WHY YOU SHOULD ALWAYS <code>use strict</code></h3>
-
-<p>If this is starting to sound scarier than it’s worth, relax. Perl has
-some features to help you avoid its most common pitfalls. The best
-way to avoid getting confused is to start every program like this:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -w
- use strict;
-</pre>
-<p>This way, you’ll be forced to declare all your variables with my() and
-also disallow accidental "symbolic dereferencing". Therefore if
you’d done
-this:
-</p>
-<pre class="verbatim"> my $aref = [
- [ "fred", "barney", "pebbles",
"bambam", "dino", ],
- [ "homer", "bart", "marge",
"maggie", ],
- [ "george", "jane", "elroy",
"judy", ],
- ];
-
- print $aref[2][2];
-</pre>
-<p>The compiler would immediately flag that as an error <em>at compile
time</em>,
-because you were accidentally accessing <code>@aref</code>, an undeclared
-variable, and it would thereby remind you to write instead:
-</p>
-<pre class="verbatim"> print $aref->[2][2]
-</pre>
-<hr>
-<a name="perldsc-DEBUGGING"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-CODE-EXAMPLES" accesskey="n" rel="next">perldsc CODE
EXAMPLES</a>, Previous: <a href="#perldsc-WHY-YOU-SHOULD-ALWAYS-use-strict"
accesskey="p" rel="prev">perldsc WHY YOU SHOULD ALWAYS <code>use
strict</code></a>, Up: <a href="#perldsc" accesskey="u" rel="up">perldsc</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DEBUGGING"></a>
-<h3 class="section">17.7 DEBUGGING</h3>
-
-<p>You can use the debugger’s <code>x</code> command to dump out complex
data structures.
-For example, given the assignment to $AoA above, here’s the debugger
output:
-</p>
-<pre class="verbatim"> DB<1> x $AoA
- $AoA = ARRAY(0x13b5a0)
- 0 ARRAY(0x1f0a24)
- 0 'fred'
- 1 'barney'
- 2 'pebbles'
- 3 'bambam'
- 4 'dino'
- 1 ARRAY(0x13b558)
- 0 'homer'
- 1 'bart'
- 2 'marge'
- 3 'maggie'
- 2 ARRAY(0x13b540)
- 0 'george'
- 1 'jane'
- 2 'elroy'
- 3 'judy'
-</pre>
-<hr>
-<a name="perldsc-CODE-EXAMPLES"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-ARRAYS-OF-ARRAYS" accesskey="n" rel="next">perldsc
ARRAYS OF ARRAYS</a>, Previous: <a href="#perldsc-DEBUGGING" accesskey="p"
rel="prev">perldsc DEBUGGING</a>, Up: <a href="#perldsc" accesskey="u"
rel="up">perldsc</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="CODE-EXAMPLES"></a>
-<h3 class="section">17.8 CODE EXAMPLES</h3>
-
-<p>Presented with little comment (these will get their own manpages someday)
-here are short code examples illustrating access of various
-types of data structures.
-</p>
-<hr>
-<a name="perldsc-ARRAYS-OF-ARRAYS"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-HASHES-OF-ARRAYS" accesskey="n" rel="next">perldsc
HASHES OF ARRAYS</a>, Previous: <a href="#perldsc-CODE-EXAMPLES" accesskey="p"
rel="prev">perldsc CODE EXAMPLES</a>, Up: <a href="#perldsc" accesskey="u"
rel="up">perldsc</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="ARRAYS-OF-ARRAYS"></a>
-<h3 class="section">17.9 ARRAYS OF ARRAYS</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perldsc-Declaration-of-an-ARRAY-OF-ARRAYS" accesskey="1">perldsc
Declaration of an ARRAY OF ARRAYS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Generation-of-an-ARRAY-OF-ARRAYS" accesskey="2">perldsc
Generation of an ARRAY OF ARRAYS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Access-and-Printing-of-an-ARRAY-OF-ARRAYS" accesskey="3">perldsc
Access and Printing of an ARRAY OF ARRAYS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldsc-Declaration-of-an-ARRAY-OF-ARRAYS"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-Generation-of-an-ARRAY-OF-ARRAYS" accesskey="n"
rel="next">perldsc Generation of an ARRAY OF ARRAYS</a>, Up: <a
href="#perldsc-ARRAYS-OF-ARRAYS" accesskey="u" rel="up">perldsc ARRAYS OF
ARRAYS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Declaration-of-an-ARRAY-OF-ARRAYS"></a>
-<h4 class="subsection">17.9.1 Declaration of an ARRAY OF ARRAYS</h4>
-
-<pre class="verbatim"> @AoA = (
- [ "fred", "barney" ],
- [ "george", "jane", "elroy" ],
- [ "homer", "marge", "bart" ],
- );
-</pre>
-<hr>
-<a name="perldsc-Generation-of-an-ARRAY-OF-ARRAYS"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-Access-and-Printing-of-an-ARRAY-OF-ARRAYS"
accesskey="n" rel="next">perldsc Access and Printing of an ARRAY OF ARRAYS</a>,
Previous: <a href="#perldsc-Declaration-of-an-ARRAY-OF-ARRAYS" accesskey="p"
rel="prev">perldsc Declaration of an ARRAY OF ARRAYS</a>, Up: <a
href="#perldsc-ARRAYS-OF-ARRAYS" accesskey="u" rel="up">perldsc ARRAYS OF
ARRAYS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Generation-of-an-ARRAY-OF-ARRAYS"></a>
-<h4 class="subsection">17.9.2 Generation of an ARRAY OF ARRAYS</h4>
-
-<pre class="verbatim"> # reading from file
- while ( <> ) {
- push @AoA, [ split ];
- }
-
- # calling a function
- for $i ( 1 .. 10 ) {
- $AoA[$i] = [ somefunc($i) ];
- }
-
- # using temp vars
- for $i ( 1 .. 10 ) {
- @tmp = somefunc($i);
- $AoA[$i] = [ @tmp ];
- }
-
- # add to an existing row
- push @{ $AoA[0] }, "wilma", "betty";
-</pre>
-<hr>
-<a name="perldsc-Access-and-Printing-of-an-ARRAY-OF-ARRAYS"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldsc-Generation-of-an-ARRAY-OF-ARRAYS" accesskey="p"
rel="prev">perldsc Generation of an ARRAY OF ARRAYS</a>, Up: <a
href="#perldsc-ARRAYS-OF-ARRAYS" accesskey="u" rel="up">perldsc ARRAYS OF
ARRAYS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Access-and-Printing-of-an-ARRAY-OF-ARRAYS"></a>
-<h4 class="subsection">17.9.3 Access and Printing of an ARRAY OF ARRAYS</h4>
-
-<pre class="verbatim"> # one element
- $AoA[0][0] = "Fred";
-
- # another element
- $AoA[1][1] =~ s/(\w)/\u$1/;
-
- # print the whole thing with refs
- for $aref ( @AoA ) {
- print "\t [ @$aref ],\n";
- }
-
- # print the whole thing with indices
- for $i ( 0 .. $#AoA ) {
- print "\t [ @{$AoA[$i]} ],\n";
- }
-
- # print the whole thing one at a time
- for $i ( 0 .. $#AoA ) {
- for $j ( 0 .. $#{ $AoA[$i] } ) {
- print "elt $i $j is $AoA[$i][$j]\n";
- }
- }
-</pre>
-<hr>
-<a name="perldsc-HASHES-OF-ARRAYS"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-ARRAYS-OF-HASHES" accesskey="n" rel="next">perldsc
ARRAYS OF HASHES</a>, Previous: <a href="#perldsc-ARRAYS-OF-ARRAYS"
accesskey="p" rel="prev">perldsc ARRAYS OF ARRAYS</a>, Up: <a href="#perldsc"
accesskey="u" rel="up">perldsc</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="HASHES-OF-ARRAYS"></a>
-<h3 class="section">17.10 HASHES OF ARRAYS</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perldsc-Declaration-of-a-HASH-OF-ARRAYS" accesskey="1">perldsc
Declaration of a HASH OF ARRAYS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Generation-of-a-HASH-OF-ARRAYS" accesskey="2">perldsc Generation
of a HASH OF ARRAYS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Access-and-Printing-of-a-HASH-OF-ARRAYS" accesskey="3">perldsc
Access and Printing of a HASH OF ARRAYS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldsc-Declaration-of-a-HASH-OF-ARRAYS"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-Generation-of-a-HASH-OF-ARRAYS" accesskey="n"
rel="next">perldsc Generation of a HASH OF ARRAYS</a>, Up: <a
href="#perldsc-HASHES-OF-ARRAYS" accesskey="u" rel="up">perldsc HASHES OF
ARRAYS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Declaration-of-a-HASH-OF-ARRAYS"></a>
-<h4 class="subsection">17.10.1 Declaration of a HASH OF ARRAYS</h4>
-
-<pre class="verbatim"> %HoA = (
- flintstones => [ "fred", "barney" ],
- jetsons => [ "george", "jane",
"elroy" ],
- simpsons => [ "homer", "marge",
"bart" ],
- );
-</pre>
-<hr>
-<a name="perldsc-Generation-of-a-HASH-OF-ARRAYS"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-Access-and-Printing-of-a-HASH-OF-ARRAYS" accesskey="n"
rel="next">perldsc Access and Printing of a HASH OF ARRAYS</a>, Previous: <a
href="#perldsc-Declaration-of-a-HASH-OF-ARRAYS" accesskey="p"
rel="prev">perldsc Declaration of a HASH OF ARRAYS</a>, Up: <a
href="#perldsc-HASHES-OF-ARRAYS" accesskey="u" rel="up">perldsc HASHES OF
ARRAYS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Generation-of-a-HASH-OF-ARRAYS"></a>
-<h4 class="subsection">17.10.2 Generation of a HASH OF ARRAYS</h4>
-
-<pre class="verbatim"> # reading from file
- # flintstones: fred barney wilma dino
- while ( <> ) {
- next unless s/^(.*?):\s*//;
- $HoA{$1} = [ split ];
- }
-
- # reading from file; more temps
- # flintstones: fred barney wilma dino
- while ( $line = <> ) {
- ($who, $rest) = split /:\s*/, $line, 2;
- @fields = split ' ', $rest;
- $HoA{$who} = [ @fields ];
- }
-
- # calling a function that returns a list
- for $group ( "simpsons", "jetsons",
"flintstones" ) {
- $HoA{$group} = [ get_family($group) ];
- }
-
- # likewise, but using temps
- for $group ( "simpsons", "jetsons",
"flintstones" ) {
- @members = get_family($group);
- $HoA{$group} = [ @members ];
- }
-
- # append new members to an existing family
- push @{ $HoA{"flintstones"} }, "wilma", "betty";
-</pre>
-<hr>
-<a name="perldsc-Access-and-Printing-of-a-HASH-OF-ARRAYS"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldsc-Generation-of-a-HASH-OF-ARRAYS" accesskey="p"
rel="prev">perldsc Generation of a HASH OF ARRAYS</a>, Up: <a
href="#perldsc-HASHES-OF-ARRAYS" accesskey="u" rel="up">perldsc HASHES OF
ARRAYS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Access-and-Printing-of-a-HASH-OF-ARRAYS"></a>
-<h4 class="subsection">17.10.3 Access and Printing of a HASH OF ARRAYS</h4>
-
-<pre class="verbatim"> # one element
- $HoA{flintstones}[0] = "Fred";
-
- # another element
- $HoA{simpsons}[1] =~ s/(\w)/\u$1/;
-
- # print the whole thing
- foreach $family ( keys %HoA ) {
- print "$family: @{ $HoA{$family} }\n"
- }
-
- # print the whole thing with indices
- foreach $family ( keys %HoA ) {
- print "family: ";
- foreach $i ( 0 .. $#{ $HoA{$family} } ) {
- print " $i = $HoA{$family}[$i]";
- }
- print "\n";
- }
-
- # print the whole thing sorted by number of members
- foreach $family ( sort { @{$HoA{$b}} <=> @{$HoA{$a}} } keys %HoA ) {
- print "$family: @{ $HoA{$family} }\n"
- }
-
- # print the whole thing sorted by number of members and name
- foreach $family ( sort {
- @{$HoA{$b}} <=> @{$HoA{$a}}
- ||
- $a cmp $b
- } keys %HoA )
- {
- print "$family: ", join(", ", sort @{ $HoA{$family}
}), "\n";
- }
-</pre>
-<hr>
-<a name="perldsc-ARRAYS-OF-HASHES"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-HASHES-OF-HASHES" accesskey="n" rel="next">perldsc
HASHES OF HASHES</a>, Previous: <a href="#perldsc-HASHES-OF-ARRAYS"
accesskey="p" rel="prev">perldsc HASHES OF ARRAYS</a>, Up: <a href="#perldsc"
accesskey="u" rel="up">perldsc</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="ARRAYS-OF-HASHES"></a>
-<h3 class="section">17.11 ARRAYS OF HASHES</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perldsc-Declaration-of-an-ARRAY-OF-HASHES" accesskey="1">perldsc
Declaration of an ARRAY OF HASHES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Generation-of-an-ARRAY-OF-HASHES" accesskey="2">perldsc
Generation of an ARRAY OF HASHES</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Access-and-Printing-of-an-ARRAY-OF-HASHES" accesskey="3">perldsc
Access and Printing of an ARRAY OF HASHES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldsc-Declaration-of-an-ARRAY-OF-HASHES"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-Generation-of-an-ARRAY-OF-HASHES" accesskey="n"
rel="next">perldsc Generation of an ARRAY OF HASHES</a>, Up: <a
href="#perldsc-ARRAYS-OF-HASHES" accesskey="u" rel="up">perldsc ARRAYS OF
HASHES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Declaration-of-an-ARRAY-OF-HASHES"></a>
-<h4 class="subsection">17.11.1 Declaration of an ARRAY OF HASHES</h4>
-
-<pre class="verbatim"> @AoH = (
- {
- Lead => "fred",
- Friend => "barney",
- },
- {
- Lead => "george",
- Wife => "jane",
- Son => "elroy",
- },
- {
- Lead => "homer",
- Wife => "marge",
- Son => "bart",
- }
- );
-</pre>
-<hr>
-<a name="perldsc-Generation-of-an-ARRAY-OF-HASHES"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-Access-and-Printing-of-an-ARRAY-OF-HASHES"
accesskey="n" rel="next">perldsc Access and Printing of an ARRAY OF HASHES</a>,
Previous: <a href="#perldsc-Declaration-of-an-ARRAY-OF-HASHES" accesskey="p"
rel="prev">perldsc Declaration of an ARRAY OF HASHES</a>, Up: <a
href="#perldsc-ARRAYS-OF-HASHES" accesskey="u" rel="up">perldsc ARRAYS OF
HASHES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Generation-of-an-ARRAY-OF-HASHES"></a>
-<h4 class="subsection">17.11.2 Generation of an ARRAY OF HASHES</h4>
-
-<pre class="verbatim"> # reading from file
- # format: LEAD=fred FRIEND=barney
- while ( <> ) {
- $rec = {};
- for $field ( split ) {
- ($key, $value) = split /=/, $field;
- $rec->{$key} = $value;
- }
- push @AoH, $rec;
- }
-
-
- # reading from file
- # format: LEAD=fred FRIEND=barney
- # no temp
- while ( <> ) {
- push @AoH, { split /[\s+=]/ };
- }
-
- # calling a function that returns a key/value pair list, like
- # "lead","fred","daughter","pebbles"
- while ( %fields = getnextpairset() ) {
- push @AoH, { %fields };
- }
-
- # likewise, but using no temp vars
- while (<>) {
- push @AoH, { parsepairs($_) };
- }
-
- # add key/value to an element
- $AoH[0]{pet} = "dino";
- $AoH[2]{pet} = "santa's little helper";
-</pre>
-<hr>
-<a name="perldsc-Access-and-Printing-of-an-ARRAY-OF-HASHES"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldsc-Generation-of-an-ARRAY-OF-HASHES" accesskey="p"
rel="prev">perldsc Generation of an ARRAY OF HASHES</a>, Up: <a
href="#perldsc-ARRAYS-OF-HASHES" accesskey="u" rel="up">perldsc ARRAYS OF
HASHES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Access-and-Printing-of-an-ARRAY-OF-HASHES"></a>
-<h4 class="subsection">17.11.3 Access and Printing of an ARRAY OF HASHES</h4>
-
-<pre class="verbatim"> # one element
- $AoH[0]{lead} = "fred";
-
- # another element
- $AoH[1]{lead} =~ s/(\w)/\u$1/;
-
- # print the whole thing with refs
- for $href ( @AoH ) {
- print "{ ";
- for $role ( keys %$href ) {
- print "$role=$href->{$role} ";
- }
- print "}\n";
- }
-
- # print the whole thing with indices
- for $i ( 0 .. $#AoH ) {
- print "$i is { ";
- for $role ( keys %{ $AoH[$i] } ) {
- print "$role=$AoH[$i]{$role} ";
- }
- print "}\n";
- }
-
- # print the whole thing one at a time
- for $i ( 0 .. $#AoH ) {
- for $role ( keys %{ $AoH[$i] } ) {
- print "elt $i $role is $AoH[$i]{$role}\n";
- }
- }
-</pre>
-<hr>
-<a name="perldsc-HASHES-OF-HASHES"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-MORE-ELABORATE-RECORDS" accesskey="n"
rel="next">perldsc MORE ELABORATE RECORDS</a>, Previous: <a
href="#perldsc-ARRAYS-OF-HASHES" accesskey="p" rel="prev">perldsc ARRAYS OF
HASHES</a>, Up: <a href="#perldsc" accesskey="u" rel="up">perldsc</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="HASHES-OF-HASHES"></a>
-<h3 class="section">17.12 HASHES OF HASHES</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perldsc-Declaration-of-a-HASH-OF-HASHES" accesskey="1">perldsc
Declaration of a HASH OF HASHES</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Generation-of-a-HASH-OF-HASHES" accesskey="2">perldsc Generation
of a HASH OF HASHES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Access-and-Printing-of-a-HASH-OF-HASHES" accesskey="3">perldsc
Access and Printing of a HASH OF HASHES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldsc-Declaration-of-a-HASH-OF-HASHES"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-Generation-of-a-HASH-OF-HASHES" accesskey="n"
rel="next">perldsc Generation of a HASH OF HASHES</a>, Up: <a
href="#perldsc-HASHES-OF-HASHES" accesskey="u" rel="up">perldsc HASHES OF
HASHES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Declaration-of-a-HASH-OF-HASHES"></a>
-<h4 class="subsection">17.12.1 Declaration of a HASH OF HASHES</h4>
-
-<pre class="verbatim"> %HoH = (
- flintstones => {
- lead => "fred",
- pal => "barney",
- },
- jetsons => {
- lead => "george",
- wife => "jane",
- "his boy" => "elroy",
- },
- simpsons => {
- lead => "homer",
- wife => "marge",
- kid => "bart",
- },
- );
-</pre>
-<hr>
-<a name="perldsc-Generation-of-a-HASH-OF-HASHES"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-Access-and-Printing-of-a-HASH-OF-HASHES" accesskey="n"
rel="next">perldsc Access and Printing of a HASH OF HASHES</a>, Previous: <a
href="#perldsc-Declaration-of-a-HASH-OF-HASHES" accesskey="p"
rel="prev">perldsc Declaration of a HASH OF HASHES</a>, Up: <a
href="#perldsc-HASHES-OF-HASHES" accesskey="u" rel="up">perldsc HASHES OF
HASHES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Generation-of-a-HASH-OF-HASHES"></a>
-<h4 class="subsection">17.12.2 Generation of a HASH OF HASHES</h4>
-
-<pre class="verbatim"> # reading from file
- # flintstones: lead=fred pal=barney wife=wilma pet=dino
- while ( <> ) {
- next unless s/^(.*?):\s*//;
- $who = $1;
- for $field ( split ) {
- ($key, $value) = split /=/, $field;
- $HoH{$who}{$key} = $value;
- }
-
-
- # reading from file; more temps
- while ( <> ) {
- next unless s/^(.*?):\s*//;
- $who = $1;
- $rec = {};
- $HoH{$who} = $rec;
- for $field ( split ) {
- ($key, $value) = split /=/, $field;
- $rec->{$key} = $value;
- }
- }
-
- # calling a function that returns a key,value hash
- for $group ( "simpsons", "jetsons",
"flintstones" ) {
- $HoH{$group} = { get_family($group) };
- }
-
- # likewise, but using temps
- for $group ( "simpsons", "jetsons",
"flintstones" ) {
- %members = get_family($group);
- $HoH{$group} = { %members };
- }
-
- # append new members to an existing family
- %new_folks = (
- wife => "wilma",
- pet => "dino",
- );
-
- for $what (keys %new_folks) {
- $HoH{flintstones}{$what} = $new_folks{$what};
- }
-</pre>
-<hr>
-<a name="perldsc-Access-and-Printing-of-a-HASH-OF-HASHES"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldsc-Generation-of-a-HASH-OF-HASHES" accesskey="p"
rel="prev">perldsc Generation of a HASH OF HASHES</a>, Up: <a
href="#perldsc-HASHES-OF-HASHES" accesskey="u" rel="up">perldsc HASHES OF
HASHES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Access-and-Printing-of-a-HASH-OF-HASHES"></a>
-<h4 class="subsection">17.12.3 Access and Printing of a HASH OF HASHES</h4>
-
-<pre class="verbatim"> # one element
- $HoH{flintstones}{wife} = "wilma";
-
- # another element
- $HoH{simpsons}{lead} =~ s/(\w)/\u$1/;
-
- # print the whole thing
- foreach $family ( keys %HoH ) {
- print "$family: { ";
- for $role ( keys %{ $HoH{$family} } ) {
- print "$role=$HoH{$family}{$role} ";
- }
- print "}\n";
- }
-
- # print the whole thing somewhat sorted
- foreach $family ( sort keys %HoH ) {
- print "$family: { ";
- for $role ( sort keys %{ $HoH{$family} } ) {
- print "$role=$HoH{$family}{$role} ";
- }
- print "}\n";
- }
-
-
- # print the whole thing sorted by number of members
- foreach $family ( sort { keys %{$HoH{$b}} <=> keys %{$HoH{$a}} }
- keys %HoH )
- {
- print "$family: { ";
- for $role ( sort keys %{ $HoH{$family} } ) {
- print "$role=$HoH{$family}{$role} ";
- }
- print "}\n";
- }
-
- # establish a sort order (rank) for each role
- $i = 0;
- for ( qw(lead wife son daughter pal pet) ) { $rank{$_} = ++$i }
-
- # now print the whole thing sorted by number of members
- foreach $family ( sort { keys %{ $HoH{$b} } <=> keys %{ $HoH{$a} } }
- keys %HoH )
- {
- print "$family: { ";
- # and print these according to rank order
- for $role ( sort { $rank{$a} <=> $rank{$b} }
- keys %{ $HoH{$family} } )
- {
- print "$role=$HoH{$family}{$role} ";
- }
- print "}\n";
- }
-</pre>
-<hr>
-<a name="perldsc-MORE-ELABORATE-RECORDS"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-Database-Ties" accesskey="n" rel="next">perldsc
Database Ties</a>, Previous: <a href="#perldsc-HASHES-OF-HASHES" accesskey="p"
rel="prev">perldsc HASHES OF HASHES</a>, Up: <a href="#perldsc" accesskey="u"
rel="up">perldsc</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="MORE-ELABORATE-RECORDS"></a>
-<h3 class="section">17.13 MORE ELABORATE RECORDS</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perldsc-Declaration-of-MORE-ELABORATE-RECORDS" accesskey="1">perldsc
Declaration of MORE ELABORATE RECORDS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Declaration-of-a-HASH-OF-COMPLEX-RECORDS" accesskey="2">perldsc
Declaration of a HASH OF COMPLEX RECORDS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perldsc-Generation-of-a-HASH-OF-COMPLEX-RECORDS" accesskey="3">perldsc
Generation of a HASH OF COMPLEX RECORDS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldsc-Declaration-of-MORE-ELABORATE-RECORDS"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-Declaration-of-a-HASH-OF-COMPLEX-RECORDS"
accesskey="n" rel="next">perldsc Declaration of a HASH OF COMPLEX RECORDS</a>,
Up: <a href="#perldsc-MORE-ELABORATE-RECORDS" accesskey="u" rel="up">perldsc
MORE ELABORATE RECORDS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Declaration-of-MORE-ELABORATE-RECORDS"></a>
-<h4 class="subsection">17.13.1 Declaration of MORE ELABORATE RECORDS</h4>
-
-<p>Here’s a sample showing how to create and use a record whose fields
are of
-many different sorts:
-</p>
-<pre class="verbatim"> $rec = {
- TEXT => $string,
- SEQUENCE => [ @old_values ],
- LOOKUP => { %some_table },
- THATCODE => \&some_function,
- THISCODE => sub { $_[0] ** $_[1] },
- HANDLE => \*STDOUT,
- };
-
- print $rec->{TEXT};
-
- print $rec->{SEQUENCE}[0];
- $last = pop @ { $rec->{SEQUENCE} };
-
- print $rec->{LOOKUP}{"key"};
- ($first_k, $first_v) = each %{ $rec->{LOOKUP} };
-
- $answer = $rec->{THATCODE}->($arg);
- $answer = $rec->{THISCODE}->($arg1, $arg2);
-
- # careful of extra block braces on fh ref
- print { $rec->{HANDLE} } "a string\n";
-
- use FileHandle;
- $rec->{HANDLE}->autoflush(1);
- $rec->{HANDLE}->print(" a string\n");
-</pre>
-<hr>
-<a name="perldsc-Declaration-of-a-HASH-OF-COMPLEX-RECORDS"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-Generation-of-a-HASH-OF-COMPLEX-RECORDS" accesskey="n"
rel="next">perldsc Generation of a HASH OF COMPLEX RECORDS</a>, Previous: <a
href="#perldsc-Declaration-of-MORE-ELABORATE-RECORDS" accesskey="p"
rel="prev">perldsc Declaration of MORE ELABORATE RECORDS</a>, Up: <a
href="#perldsc-MORE-ELABORATE-RECORDS" accesskey="u" rel="up">perldsc MORE
ELABORATE RECORDS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Declaration-of-a-HASH-OF-COMPLEX-RECORDS"></a>
-<h4 class="subsection">17.13.2 Declaration of a HASH OF COMPLEX RECORDS</h4>
-
-<pre class="verbatim"> %TV = (
- flintstones => {
- series => "flintstones",
- nights => [ qw(monday thursday friday) ],
- members => [
- { name => "fred", role => "lead",
age => 36, },
- { name => "wilma", role => "wife",
age => 31, },
- { name => "pebbles", role => "kid",
age => 4, },
- ],
- },
-
- jetsons => {
- series => "jetsons",
- nights => [ qw(wednesday saturday) ],
- members => [
- { name => "george", role => "lead",
age => 41, },
- { name => "jane", role => "wife",
age => 39, },
- { name => "elroy", role => "kid",
age => 9, },
- ],
- },
-
- simpsons => {
- series => "simpsons",
- nights => [ qw(monday) ],
- members => [
- { name => "homer", role => "lead",
age => 34, },
- { name => "marge", role => "wife",
age => 37, },
- { name => "bart", role => "kid",
age => 11, },
- ],
- },
- );
-</pre>
-<hr>
-<a name="perldsc-Generation-of-a-HASH-OF-COMPLEX-RECORDS"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldsc-Declaration-of-a-HASH-OF-COMPLEX-RECORDS"
accesskey="p" rel="prev">perldsc Declaration of a HASH OF COMPLEX RECORDS</a>,
Up: <a href="#perldsc-MORE-ELABORATE-RECORDS" accesskey="u" rel="up">perldsc
MORE ELABORATE RECORDS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Generation-of-a-HASH-OF-COMPLEX-RECORDS"></a>
-<h4 class="subsection">17.13.3 Generation of a HASH OF COMPLEX RECORDS</h4>
-
-<pre class="verbatim"> # reading from file
- # this is most easily done by having the file itself be
- # in the raw data format as shown above. perl is happy
- # to parse complex data structures if declared as data, so
- # sometimes it's easiest to do that
-
- # here's a piece by piece build up
- $rec = {};
- $rec->{series} = "flintstones";
- $rec->{nights} = [ find_days() ];
-
- @members = ();
- # assume this file in field=value syntax
- while (<>) {
- %fields = split /[\s=]+/;
- push @members, { %fields };
- }
- $rec->{members} = [ @members ];
-
- # now remember the whole thing
- $TV{ $rec->{series} } = $rec;
-
- ###########################################################
- # now, you might want to make interesting extra fields that
- # include pointers back into the same data structure so if
- # change one piece, it changes everywhere, like for example
- # if you wanted a {kids} field that was a reference
- # to an array of the kids' records without having duplicate
- # records and thus update problems.
- ###########################################################
- foreach $family (keys %TV) {
- $rec = $TV{$family}; # temp pointer
- @kids = ();
- for $person ( @{ $rec->{members} } ) {
- if ($person->{role} =~ /kid|son|daughter/) {
- push @kids, $person;
- }
- }
- # REMEMBER: $rec and $TV{$family} point to same data!!
- $rec->{kids} = [ @kids ];
- }
-
- # you copied the array, but the array itself contains pointers
- # to uncopied objects. this means that if you make bart get
- # older via
-
- $TV{simpsons}{kids}[0]{age}++;
-
- # then this would also change in
- print $TV{simpsons}{members}[2]{age};
-
- # because $TV{simpsons}{kids}[0] and $TV{simpsons}{members}[2]
- # both point to the same underlying anonymous hash table
-
- # print the whole thing
- foreach $family ( keys %TV ) {
- print "the $family";
- print " is on during @{ $TV{$family}{nights} }\n";
- print "its members are:\n";
- for $who ( @{ $TV{$family}{members} } ) {
- print " $who->{name} ($who->{role}), age
$who->{age}\n";
- }
- print "it turns out that $TV{$family}{lead} has ";
- print scalar ( @{ $TV{$family}{kids} } ), " kids named ";
- print join (", ", map { $_->{name} } @{
$TV{$family}{kids} } );
- print "\n";
- }
-</pre>
-<hr>
-<a name="perldsc-Database-Ties"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-SEE-ALSO" accesskey="n" rel="next">perldsc SEE
ALSO</a>, Previous: <a href="#perldsc-MORE-ELABORATE-RECORDS" accesskey="p"
rel="prev">perldsc MORE ELABORATE RECORDS</a>, Up: <a href="#perldsc"
accesskey="u" rel="up">perldsc</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Database-Ties"></a>
-<h3 class="section">17.14 Database Ties</h3>
-
-<p>You cannot easily tie a multilevel data structure (such as a hash of
-hashes) to a dbm file. The first problem is that all but GDBM and
-Berkeley DB have size limitations, but beyond that, you also have problems
-with how references are to be represented on disk. One experimental
-module that does partially attempt to address this need is the MLDBM
-module. Check your nearest CPAN site as described in <a
href="perlmodlib.html#Top">(perlmodlib)</a> for
-source code to MLDBM.
-</p>
-<hr>
-<a name="perldsc-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perldsc-AUTHOR" accesskey="n" rel="next">perldsc AUTHOR</a>,
Previous: <a href="#perldsc-Database-Ties" accesskey="p" rel="prev">perldsc
Database Ties</a>, Up: <a href="#perldsc" accesskey="u" rel="up">perldsc</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-10"></a>
-<h3 class="section">17.15 SEE ALSO</h3>
-
-<p><a href="#perlref-NAME">perlref NAME</a>, <a href="#perllol-NAME">perllol
NAME</a>, <a href="#perldata-NAME">perldata NAME</a>, <a
href="#perlobj-NAME">perlobj NAME</a>
-</p>
-<hr>
-<a name="perldsc-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldsc-SEE-ALSO" accesskey="p" rel="prev">perldsc SEE
ALSO</a>, Up: <a href="#perldsc" accesskey="u" rel="up">perldsc</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-6"></a>
-<h3 class="section">17.16 AUTHOR</h3>
-
-<p>Tom Christiansen <<samp>address@hidden</samp>>
-</p>
-<hr>
-<a name="perldtrace"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic" accesskey="n" rel="next">perlebcdic</a>, Previous:
<a href="#perldsc" accesskey="p" rel="prev">perldsc</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perldtrace-1"></a>
-<h2 class="chapter">18 perldtrace</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perldtrace-NAME"
accesskey="1">perldtrace NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldtrace-SYNOPSIS"
accesskey="2">perldtrace SYNOPSIS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldtrace-DESCRIPTION"
accesskey="3">perldtrace DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldtrace-HISTORY"
accesskey="4">perldtrace HISTORY</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldtrace-PROBES"
accesskey="5">perldtrace PROBES</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldtrace-EXAMPLES"
accesskey="6">perldtrace EXAMPLES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldtrace-REFERENCES"
accesskey="7">perldtrace REFERENCES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldtrace-SEE-ALSO"
accesskey="8">perldtrace SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perldtrace-AUTHORS"
accesskey="9">perldtrace AUTHORS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perldtrace-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perldtrace-SYNOPSIS" accesskey="n" rel="next">perldtrace
SYNOPSIS</a>, Up: <a href="#perldtrace" accesskey="u" rel="up">perldtrace</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-17"></a>
-<h3 class="section">18.1 NAME</h3>
-
-<p>perldtrace - Perl’s support for DTrace
-</p>
-<hr>
-<a name="perldtrace-SYNOPSIS"></a>
-<div class="header">
-<p>
-Next: <a href="#perldtrace-DESCRIPTION" accesskey="n" rel="next">perldtrace
DESCRIPTION</a>, Previous: <a href="#perldtrace-NAME" accesskey="p"
rel="prev">perldtrace NAME</a>, Up: <a href="#perldtrace" accesskey="u"
rel="up">perldtrace</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SYNOPSIS-4"></a>
-<h3 class="section">18.2 SYNOPSIS</h3>
-
-<pre class="verbatim"> # dtrace -Zn 'perl::sub-entry, perl::sub-return {
trace(copyinstr(arg0)) }'
- dtrace: description 'perl::sub-entry, perl::sub-return ' matched 10 probes
-
- # perl -E 'sub outer { inner(@_) } sub inner { say shift }
outer("hello")'
- hello
-
- (dtrace output)
- CPU ID FUNCTION:NAME
- 0 75915 Perl_pp_entersub:sub-entry BEGIN
- 0 75915 Perl_pp_entersub:sub-entry import
- 0 75922 Perl_pp_leavesub:sub-return import
- 0 75922 Perl_pp_leavesub:sub-return BEGIN
- 0 75915 Perl_pp_entersub:sub-entry outer
- 0 75915 Perl_pp_entersub:sub-entry inner
- 0 75922 Perl_pp_leavesub:sub-return inner
- 0 75922 Perl_pp_leavesub:sub-return outer
-</pre>
-<hr>
-<a name="perldtrace-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perldtrace-HISTORY" accesskey="n" rel="next">perldtrace
HISTORY</a>, Previous: <a href="#perldtrace-SYNOPSIS" accesskey="p"
rel="prev">perldtrace SYNOPSIS</a>, Up: <a href="#perldtrace" accesskey="u"
rel="up">perldtrace</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-17"></a>
-<h3 class="section">18.3 DESCRIPTION</h3>
-
-<p>DTrace is a framework for comprehensive system- and application-level
-tracing. Perl is a DTrace <em>provider</em>, meaning it exposes several
-<em>probes</em> for instrumentation. You can use these in conjunction
-with kernel-level probes, as well as probes from other providers
-such as MySQL, in order to diagnose software defects, or even just
-your application’s bottlenecks.
-</p>
-<p>Perl must be compiled with the <code>-Dusedtrace</code> option in order to
-make use of the provided probes. While DTrace aims to have no
-overhead when its instrumentation is not active, Perl’s support
-itself cannot uphold that guarantee, so it is built without DTrace
-probes under most systems. One notable exception is that Mac OS X
-ships a <samp>/usr/bin/perl</samp> with DTrace support enabled.
-</p>
-<hr>
-<a name="perldtrace-HISTORY"></a>
-<div class="header">
-<p>
-Next: <a href="#perldtrace-PROBES" accesskey="n" rel="next">perldtrace
PROBES</a>, Previous: <a href="#perldtrace-DESCRIPTION" accesskey="p"
rel="prev">perldtrace DESCRIPTION</a>, Up: <a href="#perldtrace" accesskey="u"
rel="up">perldtrace</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="HISTORY"></a>
-<h3 class="section">18.4 HISTORY</h3>
-
-<dl compact="compact">
-<dt>5.10.1</dt>
-<dd><a name="perldtrace-5_002e10_002e1"></a>
-<p>Perl’s initial DTrace support was added, providing
<code>sub-entry</code> and
-<code>sub-return</code> probes.
-</p>
-</dd>
-<dt>5.14.0</dt>
-<dd><a name="perldtrace-5_002e14_002e0"></a>
-<p>The <code>sub-entry</code> and <code>sub-return</code> probes gain a fourth
argument: the
-package name of the function.
-</p>
-</dd>
-<dt>5.16.0</dt>
-<dd><a name="perldtrace-5_002e16_002e0"></a>
-<p>The <code>phase-change</code> probe was added.
-</p>
-</dd>
-<dt>5.18.0</dt>
-<dd><a name="perldtrace-5_002e18_002e0"></a>
-<p>The <code>op-entry</code>, <code>loading-file</code>, and
<code>loaded-file</code> probes were added.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perldtrace-PROBES"></a>
-<div class="header">
-<p>
-Next: <a href="#perldtrace-EXAMPLES" accesskey="n" rel="next">perldtrace
EXAMPLES</a>, Previous: <a href="#perldtrace-HISTORY" accesskey="p"
rel="prev">perldtrace HISTORY</a>, Up: <a href="#perldtrace" accesskey="u"
rel="up">perldtrace</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PROBES"></a>
-<h3 class="section">18.5 PROBES</h3>
-
-<dl compact="compact">
-<dt>sub-entry(SUBNAME, FILE, LINE, PACKAGE)</dt>
-<dd><a
name="perldtrace-sub_002dentry_0028SUBNAME_002c-FILE_002c-LINE_002c-PACKAGE_0029"></a>
-<p>Traces the entry of any subroutine. Note that all of the variables
-refer to the subroutine that is being invoked; there is currently
-no way to get ahold of any information about the subroutine’s
-<em>caller</em> from a DTrace action.
-</p>
-<pre class="verbatim"> :*perl*::sub-entry {
- printf("%s::%s entered at %s line %d\n",
- copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
- }
-</pre>
-</dd>
-<dt>sub-return(SUBNAME, FILE, LINE, PACKAGE)</dt>
-<dd><a
name="perldtrace-sub_002dreturn_0028SUBNAME_002c-FILE_002c-LINE_002c-PACKAGE_0029"></a>
-<p>Traces the exit of any subroutine. Note that all of the variables
-refer to the subroutine that is returning; there is currently no
-way to get ahold of any information about the subroutine’s
<em>caller</em>
-from a DTrace action.
-</p>
-<pre class="verbatim"> :*perl*::sub-return {
- printf("%s::%s returned at %s line %d\n",
- copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
- }
-</pre>
-</dd>
-<dt>phase-change(NEWPHASE, OLDPHASE)</dt>
-<dd><a name="perldtrace-phase_002dchange_0028NEWPHASE_002c-OLDPHASE_0029"></a>
-<p>Traces changes to Perl’s interpreter state. You can internalize this
-as tracing changes to Perl’s <code>${^GLOBAL_PHASE}</code> variable,
especially
-since the values for <code>NEWPHASE</code> and <code>OLDPHASE</code> are the
strings that
-<code>${^GLOBAL_PHASE}</code> reports.
-</p>
-<pre class="verbatim"> :*perl*::phase-change {
- printf("Phase changed from %s to %s\n",
- copyinstr(arg1), copyinstr(arg0));
- }
-</pre>
-</dd>
-<dt>op-entry(OPNAME)</dt>
-<dd><a name="perldtrace-op_002dentry_0028OPNAME_0029"></a>
-<p>Traces the execution of each opcode in the Perl runloop. This probe
-is fired before the opcode is executed. When the Perl debugger is
-enabled, the DTrace probe is fired <em>after</em> the debugger hooks (but
-still before the opcode itself is executed).
-</p>
-<pre class="verbatim"> :*perl*::op-entry {
- printf("About to execute opcode %s\n", copyinstr(arg0));
- }
-</pre>
-</dd>
-<dt>loading-file(FILENAME)</dt>
-<dd><a name="perldtrace-loading_002dfile_0028FILENAME_0029"></a>
-<p>Fires when Perl is about to load an individual file, whether from
-<code>use</code>, <code>require</code>, or <code>do</code>. This probe fires
before the file is
-read from disk. The filename argument is converted to local filesystem
-paths instead of providing <code>Module::Name</code>-style names.
-</p>
-<pre class="verbatim"> :*perl*:loading-file {
- printf("About to load %s\n", copyinstr(arg0));
- }
-</pre>
-</dd>
-<dt>loaded-file(FILENAME)</dt>
-<dd><a name="perldtrace-loaded_002dfile_0028FILENAME_0029"></a>
-<p>Fires when Perl has successfully loaded an individual file, whether
-from <code>use</code>, <code>require</code>, or <code>do</code>. This probe
fires after the file
-is read from disk and its contents evaluated. The filename argument
-is converted to local filesystem paths instead of providing
-<code>Module::Name</code>-style names.
-</p>
-<pre class="verbatim"> :*perl*:loaded-file {
- printf("Successfully loaded %s\n", copyinstr(arg0));
- }
-</pre>
-</dd>
-</dl>
-
-<hr>
-<a name="perldtrace-EXAMPLES"></a>
-<div class="header">
-<p>
-Next: <a href="#perldtrace-REFERENCES" accesskey="n" rel="next">perldtrace
REFERENCES</a>, Previous: <a href="#perldtrace-PROBES" accesskey="p"
rel="prev">perldtrace PROBES</a>, Up: <a href="#perldtrace" accesskey="u"
rel="up">perldtrace</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="EXAMPLES-1"></a>
-<h3 class="section">18.6 EXAMPLES</h3>
-
-<dl compact="compact">
-<dt>Most frequently called functions</dt>
-<dd><a name="perldtrace-Most-frequently-called-functions"></a>
-<pre class="verbatim"> # dtrace -qZn 'sub-entry {
@[strjoin(strjoin(copyinstr(arg3),"::"),copyinstr(arg0))] = count() }
END {trunc(@, 10)}'
-
- Class::MOP::Attribute::slots 400
- Try::Tiny::catch 411
- Try::Tiny::try 411
- Class::MOP::Instance::inline_slot_access 451
- Class::MOP::Class::Immutable::Trait:::around 472
- Class::MOP::Mixin::AttributeCore::has_initializer 496
- Class::MOP::Method::Wrapped::__ANON__ 544
- Class::MOP::Package::_package_stash 737
- Class::MOP::Class::initialize 1128
- Class::MOP::get_metaclass_by_name 1204
-</pre>
-</dd>
-<dt>Trace function calls</dt>
-<dd><a name="perldtrace-Trace-function-calls"></a>
-<pre class="verbatim"> # dtrace -qFZn 'sub-entry, sub-return {
trace(copyinstr(arg0)) }'
-
- 0 -> Perl_pp_entersub BEGIN
- 0 <- Perl_pp_leavesub BEGIN
- 0 -> Perl_pp_entersub BEGIN
- 0 -> Perl_pp_entersub import
- 0 <- Perl_pp_leavesub import
- 0 <- Perl_pp_leavesub BEGIN
- 0 -> Perl_pp_entersub BEGIN
- 0 -> Perl_pp_entersub dress
- 0 <- Perl_pp_leavesub dress
- 0 -> Perl_pp_entersub dirty
- 0 <- Perl_pp_leavesub dirty
- 0 -> Perl_pp_entersub whiten
- 0 <- Perl_pp_leavesub whiten
- 0 <- Perl_dounwind BEGIN
-</pre>
-</dd>
-<dt>Function calls during interpreter cleanup</dt>
-<dd><a name="perldtrace-Function-calls-during-interpreter-cleanup"></a>
-<pre class="verbatim"> # dtrace -Zn 'phase-change /copyinstr(arg0) ==
"END"/ { self->ending = 1 } sub-entry /self->ending/ {
trace(copyinstr(arg0)) }'
-
- CPU ID FUNCTION:NAME
- 1 77214 Perl_pp_entersub:sub-entry END
- 1 77214 Perl_pp_entersub:sub-entry END
- 1 77214 Perl_pp_entersub:sub-entry cleanup
- 1 77214 Perl_pp_entersub:sub-entry _force_writable
- 1 77214 Perl_pp_entersub:sub-entry _force_writable
-</pre>
-</dd>
-<dt>System calls at compile time</dt>
-<dd><a name="perldtrace-System-calls-at-compile-time"></a>
-<pre class="verbatim"> # dtrace -qZn 'phase-change /copyinstr(arg0) ==
"START"/ { self->interesting = 1 } phase-change /copyinstr(arg0)
== "RUN"/ { self->interesting = 0 } syscall:::
/self->interesting/ { @[probefunc] = count() } END { trunc(@, 3) }'
-
- lseek 310
- read 374
- stat64 1056
-</pre>
-</dd>
-<dt>Perl functions that execute the most opcodes</dt>
-<dd><a name="perldtrace-Perl-functions-that-execute-the-most-opcodes"></a>
-<pre class="verbatim"> # dtrace -qZn 'sub-entry { self->fqn =
strjoin(copyinstr(arg3), strjoin("::", copyinstr(arg0))) } op-entry
/self->fqn != ""/ { @[self->fqn] = count() } END { trunc(@, 3)
}'
-
- warnings::unimport 4589
- Exporter::Heavy::_rebuild_cache 5039
- Exporter::import 14578
-</pre>
-</dd>
-</dl>
-
-<hr>
-<a name="perldtrace-REFERENCES"></a>
-<div class="header">
-<p>
-Next: <a href="#perldtrace-SEE-ALSO" accesskey="n" rel="next">perldtrace SEE
ALSO</a>, Previous: <a href="#perldtrace-EXAMPLES" accesskey="p"
rel="prev">perldtrace EXAMPLES</a>, Up: <a href="#perldtrace" accesskey="u"
rel="up">perldtrace</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="REFERENCES-1"></a>
-<h3 class="section">18.7 REFERENCES</h3>
-
-<dl compact="compact">
-<dt>DTrace Dynamic Tracing Guide</dt>
-<dd><a name="perldtrace-DTrace-Dynamic-Tracing-Guide"></a>
-<p><a
href="http://dtrace.org/guide/preface.html";>http://dtrace.org/guide/preface.html</a>
-</p>
-</dd>
-<dt>DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD</dt>
-<dd><a
name="perldtrace-DTrace_003a-Dynamic-Tracing-in-Oracle-Solaris_002c-Mac-OS-X-and-FreeBSD"></a>
-<p><a
href="http://www.amazon.com/DTrace-Dynamic-Tracing-Solaris-FreeBSD/dp/0132091518/";>http://www.amazon.com/DTrace-Dynamic-Tracing-Solaris-FreeBSD/dp/0132091518/</a>
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perldtrace-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perldtrace-AUTHORS" accesskey="n" rel="next">perldtrace
AUTHORS</a>, Previous: <a href="#perldtrace-REFERENCES" accesskey="p"
rel="prev">perldtrace REFERENCES</a>, Up: <a href="#perldtrace" accesskey="u"
rel="up">perldtrace</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-11"></a>
-<h3 class="section">18.8 SEE ALSO</h3>
-
-<dl compact="compact">
-<dt><a href="Devel-DTrace-Provider.html#Top">(Devel-DTrace-Provider)</a></dt>
-<dd><a name="perldtrace-Devel_002dDTrace_002dProvider"></a>
-<p>This CPAN module lets you create application-level DTrace probes written in
-Perl.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perldtrace-AUTHORS"></a>
-<div class="header">
-<p>
-Previous: <a href="#perldtrace-SEE-ALSO" accesskey="p" rel="prev">perldtrace
SEE ALSO</a>, Up: <a href="#perldtrace" accesskey="u" rel="up">perldtrace</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHORS"></a>
-<h3 class="section">18.9 AUTHORS</h3>
-
-<p>Shawn M Moore <code>address@hidden</code>
-</p>
-<hr>
-<a name="perlebcdic"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed" accesskey="n" rel="next">perlembed</a>, Previous:
<a href="#perldtrace" accesskey="p" rel="prev">perldtrace</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlebcdic-1"></a>
-<h2 class="chapter">19 perlebcdic</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlebcdic-NAME"
accesskey="1">perlebcdic NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlebcdic-DESCRIPTION"
accesskey="2">perlebcdic DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-COMMON-CHARACTER-CODE-SETS" accesskey="3">perlebcdic COMMON
CHARACTER CODE SETS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-SINGLE-OCTET-TABLES" accesskey="4">perlebcdic SINGLE OCTET
TABLES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-IDENTIFYING-CHARACTER-CODE-SETS" accesskey="5">perlebcdic
IDENTIFYING CHARACTER CODE SETS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlebcdic-CONVERSIONS"
accesskey="6">perlebcdic CONVERSIONS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-OPERATOR-DIFFERENCES" accesskey="7">perlebcdic OPERATOR
DIFFERENCES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-FUNCTION-DIFFERENCES" accesskey="8">perlebcdic FUNCTION
DIFFERENCES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-REGULAR-EXPRESSION-DIFFERENCES" accesskey="9">perlebcdic
REGULAR EXPRESSION DIFFERENCES</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-SOCKETS">perlebcdic SOCKETS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-SORTING">perlebcdic SORTING</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-TRANSFORMATION-FORMATS">perlebcdic TRANSFORMATION
FORMATS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Hashing-order-and-checksums">perlebcdic Hashing order and
checksums</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-I18N-AND-L10N">perlebcdic I18N AND
L10N</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-MULTI_002dOCTET-CHARACTER-SETS">perlebcdic MULTI-OCTET
CHARACTER SETS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-OS-ISSUES">perlebcdic OS
ISSUES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlebcdic-BUGS">perlebcdic
BUGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-SEE-ALSO">perlebcdic SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-REFERENCES">perlebcdic
REFERENCES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-HISTORY">perlebcdic HISTORY</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-AUTHOR">perlebcdic AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlebcdic-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-DESCRIPTION" accesskey="n" rel="next">perlebcdic
DESCRIPTION</a>, Up: <a href="#perlebcdic" accesskey="u"
rel="up">perlebcdic</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-18"></a>
-<h3 class="section">19.1 NAME</h3>
-
-<p>perlebcdic - Considerations for running Perl on EBCDIC platforms
-</p>
-<hr>
-<a name="perlebcdic-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-COMMON-CHARACTER-CODE-SETS" accesskey="n"
rel="next">perlebcdic COMMON CHARACTER CODE SETS</a>, Previous: <a
href="#perlebcdic-NAME" accesskey="p" rel="prev">perlebcdic NAME</a>, Up: <a
href="#perlebcdic" accesskey="u" rel="up">perlebcdic</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-18"></a>
-<h3 class="section">19.2 DESCRIPTION</h3>
-
-<p>An exploration of some of the issues facing Perl programmers
-on EBCDIC based computers.
-</p>
-<p>Portions of this document that are still incomplete are marked with XXX.
-</p>
-<p>Early Perl versions worked on some EBCDIC machines, but the last known
-version that ran on EBCDIC was v5.8.7, until v5.22, when the Perl core
-again works on z/OS. Theoretically, it could work on OS/400 or Siemens’
-BS2000 (or their successors), but this is untested. In v5.22, not all
-the modules found on CPAN but shipped with core Perl work on z/OS.
-</p>
-<p>If you want to use Perl on a non-z/OS EBCDIC machine, please let us know
-by sending mail to address@hidden
-</p>
-<p>Writing Perl on an EBCDIC platform is really no different than writing
-on an <a href="#perlebcdic-ASCII">ASCII</a> one, but with different underlying
numbers, as we’ll see
-shortly. You’ll have to know something about those <a
href="#perlebcdic-ASCII">ASCII</a> platforms
-because the documentation is biased and will frequently use example
-numbers that don’t apply to EBCDIC. There are also very few CPAN
-modules that are written for EBCDIC and which don’t work on ASCII;
-instead the vast majority of CPAN modules are written for ASCII, and
-some may happen to work on EBCDIC, while a few have been designed to
-portably work on both.
-</p>
-<p>If your code just uses the 52 letters A-Z and a-z, plus SPACE, the
-digits 0-9, and the punctuation characters that Perl uses, plus a few
-controls that are denoted by escape sequences like <code>\n</code> and
<code>\t</code>, then
-there’s nothing special about using Perl, and your code may very well
-work on an ASCII machine without change.
-</p>
-<p>But if you write code that uses <code>\005</code> to mean a TAB or
<code>\xC1</code> to mean
-an "A", or <code>\xDF</code> to mean a "ÿ" (small
<code>"y"</code> with a diaeresis),
-then your code may well work on your EBCDIC platform, but not on an
-ASCII one. That’s fine to do if no one will ever want to run your code
-on an ASCII platform; but the bias in this document will be in writing
-code portable between EBCDIC and ASCII systems. Again, if every
-character you care about is easily enterable from your keyboard, you
-don’t have to know anything about ASCII, but many keyboards don’t
easily
-allow you to directly enter, say, the character <code>\xDF</code>, so you have
to
-specify it indirectly, such as by using the <code>"\xDF"</code>
escape sequence.
-In those cases it’s easiest to know something about the ASCII/Unicode
-character sets. If you know that the small "ÿ" is
<code>U+00FF</code>, then
-you can instead specify it as <code>"\N{U+FF}"</code>, and have the
computer
-automatically translate it to <code>\xDF</code> on your platform, and leave it
as
-<code>\xFF</code> on ASCII ones. Or you could specify it by name,
<code>\N{LATIN
-SMALL LETTER Y WITH DIAERESIS</code> and not have to know the numbers.
-Either way works, but require familiarity with Unicode.
-</p>
-<hr>
-<a name="perlebcdic-COMMON-CHARACTER-CODE-SETS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-SINGLE-OCTET-TABLES" accesskey="n"
rel="next">perlebcdic SINGLE OCTET TABLES</a>, Previous: <a
href="#perlebcdic-DESCRIPTION" accesskey="p" rel="prev">perlebcdic
DESCRIPTION</a>, Up: <a href="#perlebcdic" accesskey="u"
rel="up">perlebcdic</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="COMMON-CHARACTER-CODE-SETS"></a>
-<h3 class="section">19.3 COMMON CHARACTER CODE SETS</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlebcdic-ASCII"
accesskey="1">perlebcdic ASCII</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlebcdic-ISO-8859"
accesskey="2">perlebcdic ISO 8859</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Latin-1-_0028ISO-8859_002d1_0029" accesskey="3">perlebcdic
Latin 1 (ISO 8859-1)</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlebcdic-EBCDIC"
accesskey="4">perlebcdic EBCDIC</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Unicode-code-points-versus-EBCDIC-code-points"
accesskey="5">perlebcdic Unicode code points versus EBCDIC code
points</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlebcdic-Unicode-and-UTF"
accesskey="6">perlebcdic Unicode and UTF</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlebcdic-Using-Encode"
accesskey="7">perlebcdic Using Encode</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlebcdic-ASCII"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-ISO-8859" accesskey="n" rel="next">perlebcdic ISO
8859</a>, Up: <a href="#perlebcdic-COMMON-CHARACTER-CODE-SETS" accesskey="u"
rel="up">perlebcdic COMMON CHARACTER CODE SETS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="ASCII"></a>
-<h4 class="subsection">19.3.1 ASCII</h4>
-
-<p>The American Standard Code for Information Interchange (ASCII or
-US-ASCII) is a set of
-integers running from 0 to 127 (decimal) that have standardized
-interpretations by the computers which use ASCII. For example, 65 means
-the letter "A".
-The range 0..127 can be covered by setting the bits in a 7-bit binary
-digit, hence the set is sometimes referred to as "7-bit ASCII".
-ASCII was described by the American National Standards Institute
-document ANSI X3.4-1986. It was also described by ISO 646:1991
-(with localization for currency symbols). The full ASCII set is
-given in the table <a href="#perlebcdic-recipe-3">below</a> as the first 128
elements.
-Languages that
-can be written adequately with the characters in ASCII include
-English, Hawaiian, Indonesian, Swahili and some Native American
-languages.
-</p>
-<p>Most non-EBCDIC character sets are supersets of ASCII. That is the
-integers 0-127 mean what ASCII says they mean. But integers 128 and
-above are specific to the character set.
-</p>
-<p>Many of these fit entirely into 8 bits, using ASCII as 0-127, while
-specifying what 128-255 mean, and not using anything above 255.
-Thus, these are single-byte (or octet if you prefer) character sets.
-One important one (since Unicode is a superset of it) is the ISO 8859-1
-character set.
-</p>
-<hr>
-<a name="perlebcdic-ISO-8859"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-Latin-1-_0028ISO-8859_002d1_0029" accesskey="n"
rel="next">perlebcdic Latin 1 (ISO 8859-1)</a>, Previous: <a
href="#perlebcdic-ASCII" accesskey="p" rel="prev">perlebcdic ASCII</a>, Up: <a
href="#perlebcdic-COMMON-CHARACTER-CODE-SETS" accesskey="u" rel="up">perlebcdic
COMMON CHARACTER CODE SETS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="ISO-8859"></a>
-<h4 class="subsection">19.3.2 ISO 8859</h4>
-
-<p>The ISO 8859-<em><strong>$n</strong></em> are a collection of character
code sets from the
-International Organization for Standardization (ISO), each of which adds
-characters to the ASCII set that are typically found in various
-languages, many of which are based on the Roman, or Latin, alphabet.
-Most are for European languages, but there are also ones for Arabic,
-Greek, Hebrew, and Thai. There are good references on the web about
-all these.
-</p>
-<hr>
-<a name="perlebcdic-Latin-1-_0028ISO-8859_002d1_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-EBCDIC" accesskey="n" rel="next">perlebcdic
EBCDIC</a>, Previous: <a href="#perlebcdic-ISO-8859" accesskey="p"
rel="prev">perlebcdic ISO 8859</a>, Up: <a
href="#perlebcdic-COMMON-CHARACTER-CODE-SETS" accesskey="u" rel="up">perlebcdic
COMMON CHARACTER CODE SETS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Latin-1-_0028ISO-8859_002d1_0029"></a>
-<h4 class="subsection">19.3.3 Latin 1 (ISO 8859-1)</h4>
-
-<p>A particular 8-bit extension to ASCII that includes grave and acute
-accented Latin characters. Languages that can employ ISO 8859-1
-include all the languages covered by ASCII as well as Afrikaans,
-Albanian, Basque, Catalan, Danish, Faroese, Finnish, Norwegian,
-Portuguese, Spanish, and Swedish. Dutch is covered albeit without
-the ij ligature. French is covered too but without the oe ligature.
-German can use ISO 8859-1 but must do so without German-style
-quotation marks. This set is based on Western European extensions
-to ASCII and is commonly encountered in world wide web work.
-In IBM character code set identification terminology, ISO 8859-1 is
-also known as CCSID 819 (or sometimes 0819 or even 00819).
-</p>
-<hr>
-<a name="perlebcdic-EBCDIC"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-Unicode-code-points-versus-EBCDIC-code-points"
accesskey="n" rel="next">perlebcdic Unicode code points versus EBCDIC code
points</a>, Previous: <a href="#perlebcdic-Latin-1-_0028ISO-8859_002d1_0029"
accesskey="p" rel="prev">perlebcdic Latin 1 (ISO 8859-1)</a>, Up: <a
href="#perlebcdic-COMMON-CHARACTER-CODE-SETS" accesskey="u" rel="up">perlebcdic
COMMON CHARACTER CODE SETS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="EBCDIC"></a>
-<h4 class="subsection">19.3.4 EBCDIC</h4>
-
-<p>The Extended Binary Coded Decimal Interchange Code refers to a
-large collection of single- and multi-byte coded character sets that are
-quite different from ASCII and 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, which long predate ASCII. The layout on the
-cards was such that high bits were set for the upper and lower case
-alphabetic
-characters <code>[a-z]</code> and <code>[A-Z]</code>, but there were gaps
within each Latin
-alphabet range, visible in the table <a href="#perlebcdic-recipe-3">below</a>.
These gaps can
-cause complications.
-</p>
-<p>Some IBM EBCDIC character sets may be known by character code set
-identification numbers (CCSID numbers) or code page numbers.
-</p>
-<p>Perl can be compiled on platforms that run any of three commonly used EBCDIC
-character sets, listed below.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-The-13-variant-characters" accesskey="1">perlebcdic The 13
variant characters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-EBCDIC-code-sets-recognized-by-Perl" accesskey="2">perlebcdic
EBCDIC code sets recognized by Perl</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlebcdic-The-13-variant-characters"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-EBCDIC-code-sets-recognized-by-Perl" accesskey="n"
rel="next">perlebcdic EBCDIC code sets recognized by Perl</a>, Up: <a
href="#perlebcdic-EBCDIC" accesskey="u" rel="up">perlebcdic EBCDIC</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-13-variant-characters"></a>
-<h4 class="subsubsection">19.3.4.1 The 13 variant characters</h4>
-
-<p>Among IBM EBCDIC character code sets there are 13 characters that
-are often mapped to different integer values. Those characters
-are known as the 13 "variant" characters and are:
-</p>
-<pre class="verbatim"> \ [ ] { } ^ ~ ! # | $ @ `
-</pre>
-<p>When Perl is compiled for a platform, it looks at all of these characters to
-guess which EBCDIC character set the platform uses, and adapts itself
-accordingly to that platform. If the platform uses a character set that is not
-one of the three Perl knows about, Perl will either fail to compile, or
-mistakenly and silently choose one of the three.
-</p>
-<hr>
-<a name="perlebcdic-EBCDIC-code-sets-recognized-by-Perl"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlebcdic-The-13-variant-characters" accesskey="p"
rel="prev">perlebcdic The 13 variant characters</a>, Up: <a
href="#perlebcdic-EBCDIC" accesskey="u" rel="up">perlebcdic EBCDIC</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="EBCDIC-code-sets-recognized-by-Perl"></a>
-<h4 class="subsubsection">19.3.4.2 EBCDIC code sets recognized by Perl</h4>
-
-<dl compact="compact">
-<dt><strong>0037</strong></dt>
-<dd><a name="perlebcdic-0037"></a>
-<p>Character code set ID 0037 is a mapping of the ASCII plus Latin-1
-characters (i.e. ISO 8859-1) to an EBCDIC set. 0037 is used
-in North American English locales on the OS/400 operating system
-that runs on AS/400 computers. CCSID 0037 differs from ISO 8859-1
-in 236 places; in other words they agree on only 20 code point values.
-</p>
-</dd>
-<dt><strong>1047</strong></dt>
-<dd><a name="perlebcdic-1047"></a>
-<p>Character code set ID 1047 is also a mapping of the ASCII plus
-Latin-1 characters (i.e. ISO 8859-1) to an EBCDIC set. 1047 is
-used under Unix System Services for OS/390 or z/OS, and OpenEdition
-for VM/ESA. CCSID 1047 differs from CCSID 0037 in eight places,
-and from ISO 8859-1 in 236.
-</p>
-</dd>
-<dt><strong>POSIX-BC</strong></dt>
-<dd><a name="perlebcdic-POSIX_002dBC"></a>
-<p>The EBCDIC code page in use on Siemens’ BS2000 system is distinct from
-1047 and 0037. It is identified below as the POSIX-BC set.
-Like 0037 and 1047, it is the same as ISO 8859-1 in 20 code point
-values.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlebcdic-Unicode-code-points-versus-EBCDIC-code-points"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-Unicode-and-UTF" accesskey="n"
rel="next">perlebcdic Unicode and UTF</a>, Previous: <a
href="#perlebcdic-EBCDIC" accesskey="p" rel="prev">perlebcdic EBCDIC</a>, Up:
<a href="#perlebcdic-COMMON-CHARACTER-CODE-SETS" accesskey="u"
rel="up">perlebcdic COMMON CHARACTER CODE SETS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-code-points-versus-EBCDIC-code-points"></a>
-<h4 class="subsection">19.3.5 Unicode code points versus EBCDIC code
points</h4>
-
-<p>In Unicode terminology a <em>code point</em> is the number assigned to a
-character: for example, in EBCDIC the character "A" is usually
assigned
-the number 193. In Unicode, the character "A" is assigned the
number 65.
-All the code points in ASCII and Latin-1 (ISO 8859-1) have the same
-meaning in Unicode. All three of the recognized EBCDIC code sets have
-256 code points, and in each code set, all 256 code points are mapped to
-equivalent Latin1 code points. Obviously, "A" will map to
"A", "B" =>
-"B", "%" => "%", etc., for all printable
characters in Latin1 and these
-code pages.
-</p>
-<p>It also turns out that EBCDIC has nearly precise equivalents for the
-ASCII/Latin1 C0 controls and the DELETE control. (The C0 controls are
-those whose ASCII code points are 0..0x1F; things like TAB, ACK, BEL,
-etc.) A mapping is set up between these ASCII/EBCDIC controls. There
-isn’t such a precise mapping between the C1 controls on ASCII platforms
-and the remaining EBCDIC controls. What has been done is to map these
-controls, mostly arbitrarily, to some otherwise unmatched character in
-the other character set. Most of these are very very rarely used
-nowadays in EBCDIC anyway, and their names have been dropped, without
-much complaint. For example the EO (Eight Ones) EBCDIC control
-(consisting of eight one bits = 0xFF) is mapped to the C1 APC control
-(0x9F), and you can’t use the name "EO".
-</p>
-<p>The EBCDIC controls provide three possible line terminator characters,
-CR (0x0D), LF (0x25), and NL (0x15). On ASCII platforms, the symbols
-"NL" and "LF" refer to the same character, but in strict
EBCDIC
-terminology they are different ones. The EBCDIC NL is mapped to the C1
-control called "NEL" ("Next Line"; here’s a case
where the mapping makes
-quite a bit of sense, and hence isn’t just arbitrary). On some EBCDIC
-platforms, this NL or NEL is the typical line terminator. This is true
-of z/OS and BS2000. In these platforms, the C compilers will swap the
-LF and NEL code points, so that <code>"\n"</code> is 0x15, and
refers to NL. Perl
-does that too; you can see it in the code chart <a
href="#perlebcdic-recipe-3">below</a>.
-This makes things generally "just work" without you even having to be
-aware that there is a swap.
-</p>
-<hr>
-<a name="perlebcdic-Unicode-and-UTF"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-Using-Encode" accesskey="n" rel="next">perlebcdic
Using Encode</a>, Previous: <a
href="#perlebcdic-Unicode-code-points-versus-EBCDIC-code-points" accesskey="p"
rel="prev">perlebcdic Unicode code points versus EBCDIC code points</a>, Up: <a
href="#perlebcdic-COMMON-CHARACTER-CODE-SETS" accesskey="u" rel="up">perlebcdic
COMMON CHARACTER CODE SETS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-and-UTF"></a>
-<h4 class="subsection">19.3.6 Unicode and UTF</h4>
-
-<p>UTF stands for "Unicode Transformation Format".
-UTF-8 is an encoding of Unicode into a sequence of 8-bit byte chunks, based on
-ASCII and Latin-1.
-The length of a sequence required to represent a Unicode code point
-depends on the ordinal number of that code point,
-with larger numbers requiring more bytes.
-UTF-EBCDIC is like UTF-8, but based on EBCDIC.
-They are enough alike that often, casual usage will conflate the two
-terms, and use "UTF-8" to mean both the UTF-8 found on ASCII
platforms,
-and the UTF-EBCDIC found on EBCDIC ones.
-</p>
-<p>You may see the term "invariant" character or code point.
-This simply means that the character has the same numeric
-value and representation when encoded in UTF-8 (or UTF-EBCDIC) as when
-not. (Note that this is a very different concept from <a
href="#perlebcdic-The-13-variant-characters">The 13 variant
-characters</a> mentioned above. Careful prose will use the term "UTF-8
-invariant" instead of just "invariant", but most often
you’ll see just
-"invariant".) For example, the ordinal value of "A" is 193
in most
-EBCDIC code pages, and also is 193 when encoded in UTF-EBCDIC. All
-UTF-8 (or UTF-EBCDIC) variant code points occupy at least two bytes when
-encoded in UTF-8 (or UTF-EBCDIC); by definition, the UTF-8 (or
-UTF-EBCDIC) invariant code points are exactly one byte whether encoded
-in UTF-8 (or UTF-EBCDIC), or not. (By now you see why people typically
-just say "UTF-8" when they also mean "UTF-EBCDIC". For
the rest of this
-document, we’ll mostly be casual about it too.)
-In ASCII UTF-8, the code points corresponding to the lowest 128
-ordinal numbers (0 - 127: the ASCII characters) are invariant.
-In UTF-EBCDIC, there are 160 invariant characters.
-(If you care, the EBCDIC invariants are those characters
-which have ASCII equivalents, plus those that correspond to
-the C1 controls (128 - 159 on ASCII platforms).)
-</p>
-<p>A string encoded in UTF-EBCDIC may be longer (but never shorter) than
-one encoded in UTF-8. Perl extends UTF-8 so that it can encode code
-points above the Unicode maximum of U+10FFFF. It extends UTF-EBCDIC as
-well, but due to the inherent limitations in UTF-EBCDIC, the maximum
-code point expressible is U+7FFF_FFFF, even if the word size is more
-than 32 bits.
-</p>
-<p>UTF-EBCDIC is defined by
-<a href="http://www.unicode.org/reports/tr16";>Unicode Technical Report #16</a>.
-It is defined based on CCSID 1047, not allowing for the differences for
-other code pages. This allows for easy interchange of text between
-computers running different code pages, but makes it unusable, without
-adaptation, for Perl on those other code pages.
-</p>
-<p>The reason for this unusability is that a fundamental assumption of Perl
-is that the characters it cares about for parsing and lexical analysis
-are the same whether or not the text is in UTF-8. For example, Perl
-expects the character <code>"["</code> to have the same
representation, no matter
-if the string containing it (or program text) is UTF-8 encoded or not.
-To ensure this, Perl adapts UTF-EBCDIC to the particular code page so
-that all characters it expects to be UTF-8 invariant are in fact UTF-8
-invariant. This means that text generated on a computer running one
-version of Perl’s UTF-EBCDIC has to be translated to be intelligible to
-a computer running another.
-</p>
-<hr>
-<a name="perlebcdic-Using-Encode"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlebcdic-Unicode-and-UTF" accesskey="p"
rel="prev">perlebcdic Unicode and UTF</a>, Up: <a
href="#perlebcdic-COMMON-CHARACTER-CODE-SETS" accesskey="u" rel="up">perlebcdic
COMMON CHARACTER CODE SETS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-Encode"></a>
-<h4 class="subsection">19.3.7 Using Encode</h4>
-
-<p>Starting from Perl 5.8 you can use the standard module Encode
-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.
-</p>
-<pre class="verbatim"> use Encode 'from_to';
-
- 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
-</pre>
-<p>and from Latin-1 code points to EBCDIC code points
-</p>
-<pre class="verbatim"> use Encode 'from_to';
-
- 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
-</pre>
-<p>For doing I/O it is suggested that you use the autotranslating features
-of PerlIO, see <a href="#perluniintro-NAME">perluniintro NAME</a>.
-</p>
-<p>Since version 5.8 Perl uses the PerlIO I/O library. This enables
-you to use different encodings per IO channel. For example you may use
-</p>
-<pre class="verbatim"> use Encode;
- open($f, ">:encoding(ascii)", "test.ascii");
- print $f "Hello World!\n";
- open($f, ">:encoding(cp37)", "test.ebcdic");
- print $f "Hello World!\n";
- open($f, ">:encoding(latin1)", "test.latin1");
- print $f "Hello World!\n";
- open($f, ">:encoding(utf8)", "test.utf8");
- print $f "Hello World!\n";
-</pre>
-<p>to get four files containing "Hello World!\n" in ASCII, CP 0037
EBCDIC,
-ISO 8859-1 (Latin-1) (in this example identical to ASCII since only ASCII
-characters were printed), and
-UTF-EBCDIC (in this example identical to normal EBCDIC since only characters
-that don’t differ between EBCDIC and UTF-EBCDIC were printed). See the
-documentation of <a href="Encode-PerlIO.html#Top">(Encode-PerlIO)</a> for
details.
-</p>
-<p>As the PerlIO layer uses raw IO (bytes) internally, all this totally
-ignores things like the type of your filesystem (ASCII or EBCDIC).
-</p>
-<hr>
-<a name="perlebcdic-SINGLE-OCTET-TABLES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-IDENTIFYING-CHARACTER-CODE-SETS" accesskey="n"
rel="next">perlebcdic IDENTIFYING CHARACTER CODE SETS</a>, Previous: <a
href="#perlebcdic-COMMON-CHARACTER-CODE-SETS" accesskey="p"
rel="prev">perlebcdic COMMON CHARACTER CODE SETS</a>, Up: <a href="#perlebcdic"
accesskey="u" rel="up">perlebcdic</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SINGLE-OCTET-TABLES"></a>
-<h3 class="section">19.4 SINGLE OCTET TABLES</h3>
-
-<p>The following tables list the ASCII and Latin 1 ordered sets including
-the subsets: C0 controls (0..31), ASCII graphics (32..7e), delete (7f),
-C1 controls (80..9f), and Latin-1 (a.k.a. ISO 8859-1) (a0..ff). In the
-table names of the Latin 1
-extensions to ASCII have been labelled with character names roughly
-corresponding to <em>The Unicode Standard, Version 6.1</em> albeit with
-substitutions such as <code>s/LATIN//</code> and <code>s/VULGAR//</code> in
all cases;
-<code>s/CAPITAL LETTER//</code><!-- /@w --> in some cases; and
-<code>s/SMALL LETTER <span
class="nolinebreak">([A-Z])/\l$1/</span></code><!-- /@w --> in some other
-cases. Controls are listed using their Unicode 6.2 abbreviations.
-The differences between the 0037 and 1047 sets are
-flagged with <code>**</code>. The differences between the 1047 and POSIX-BC
sets
-are flagged with <code>##.</code> All <code>ord()</code> numbers listed are
decimal. If you
-would rather see this table listing octal values, then run the table
-(that is, the pod source text of this document, since this recipe may not
-work with a pod2_other_format translation) through:
-</p>
-<dl compact="compact">
-<dt>recipe 0</dt>
-<dd><a name="perlebcdic-recipe-0"></a>
-</dd>
-</dl>
-
-<pre class="verbatim"> perl -ne
'if(/(.{29})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)/)' \
- -e '{printf("%s%-5.03o%-5.03o%-5.03o%.03o\n",$1,$2,$3,$4,$5)}' \
- perlebcdic.pod
-</pre>
-<p>If you want to retain the UTF-x code points then in script form you
-might want to write:
-</p>
-<dl compact="compact">
-<dt>recipe 1</dt>
-<dd><a name="perlebcdic-recipe-1"></a>
-</dd>
-</dl>
-
-<pre class="verbatim"> open(FH,"<perlebcdic.pod") or die
"Could not open perlebcdic.pod: $!";
- while (<FH>) {
- if (/(.{29})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\.?(\d*)
- \s+(\d+)\.?(\d*)/x)
- {
- if ($7 ne '' && $9 ne '') {
- printf(
-
"%s%-5.03o%-5.03o%-5.03o%-5.03o%-3o.%-5o%-3o.%.03o\n",
- $1,$2,$3,$4,$5,$6,$7,$8,$9);
- }
- elsif ($7 ne '') {
- printf("%s%-5.03o%-5.03o%-5.03o%-5.03o%-3o.%-5o%.03o\n",
- $1,$2,$3,$4,$5,$6,$7,$8);
- }
- else {
- printf("%s%-5.03o%-5.03o%-5.03o%-5.03o%-5.03o%.03o\n",
- $1,$2,$3,$4,$5,$6,$8);
- }
- }
- }
-</pre>
-<p>If you would rather see this table listing hexadecimal values then
-run the table through:
-</p>
-<dl compact="compact">
-<dt>recipe 2</dt>
-<dd><a name="perlebcdic-recipe-2"></a>
-</dd>
-</dl>
-
-<pre class="verbatim"> perl -ne
'if(/(.{29})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)/)' \
- -e '{printf("%s%-5.02X%-5.02X%-5.02X%.02X\n",$1,$2,$3,$4,$5)}' \
- perlebcdic.pod
-</pre>
-<p>Or, in order to retain the UTF-x code points in hexadecimal:
-</p>
-<dl compact="compact">
-<dt>recipe 3</dt>
-<dd><a name="perlebcdic-recipe-3"></a>
-</dd>
-</dl>
-
-<pre class="verbatim"> open(FH,"<perlebcdic.pod") or die
"Could not open perlebcdic.pod: $!";
- while (<FH>) {
- if (/(.{29})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\.?(\d*)
- \s+(\d+)\.?(\d*)/x)
- {
- if ($7 ne '' && $9 ne '') {
- printf(
-
"%s%-5.02X%-5.02X%-5.02X%-5.02X%-2X.%-6.02X%02X.%02X\n",
- $1,$2,$3,$4,$5,$6,$7,$8,$9);
- }
- elsif ($7 ne '') {
-
printf("%s%-5.02X%-5.02X%-5.02X%-5.02X%-2X.%-6.02X%02X\n",
- $1,$2,$3,$4,$5,$6,$7,$8);
- }
- else {
- printf("%s%-5.02X%-5.02X%-5.02X%-5.02X%-5.02X%02X\n",
- $1,$2,$3,$4,$5,$6,$8);
- }
- }
- }
-
-
- ISO
- 8859-1 POS- CCSID
- CCSID CCSID CCSID IX- 1047
- chr 0819 0037 1047 BC UTF-8 UTF-EBCDIC
- ---------------------------------------------------------------------
- <NUL> 0 0 0 0 0 0
- <SOH> 1 1 1 1 1 1
- <STX> 2 2 2 2 2 2
- <ETX> 3 3 3 3 3 3
- <EOT> 4 55 55 55 4 55
- <ENQ> 5 45 45 45 5 45
- <ACK> 6 46 46 46 6 46
- <BEL> 7 47 47 47 7 47
- <BS> 8 22 22 22 8 22
- <HT> 9 5 5 5 9 5
- <LF> 10 37 21 21 10 21 **
- <VT> 11 11 11 11 11 11
- <FF> 12 12 12 12 12 12
- <CR> 13 13 13 13 13 13
- <SO> 14 14 14 14 14 14
- <SI> 15 15 15 15 15 15
- <DLE> 16 16 16 16 16 16
- <DC1> 17 17 17 17 17 17
- <DC2> 18 18 18 18 18 18
- <DC3> 19 19 19 19 19 19
- <DC4> 20 60 60 60 20 60
- <NAK> 21 61 61 61 21 61
- <SYN> 22 50 50 50 22 50
- <ETB> 23 38 38 38 23 38
- <CAN> 24 24 24 24 24 24
- <EOM> 25 25 25 25 25 25
- <SUB> 26 63 63 63 26 63
- <ESC> 27 39 39 39 27 39
- <FS> 28 28 28 28 28 28
- <GS> 29 29 29 29 29 29
- <RS> 30 30 30 30 30 30
- <US> 31 31 31 31 31 31
- <SPACE> 32 64 64 64 32 64
- ! 33 90 90 90 33 90
- " 34 127 127 127 34 127
- # 35 123 123 123 35 123
- $ 36 91 91 91 36 91
- % 37 108 108 108 37 108
- & 38 80 80 80 38 80
- ' 39 125 125 125 39 125
- ( 40 77 77 77 40 77
- ) 41 93 93 93 41 93
- * 42 92 92 92 42 92
- + 43 78 78 78 43 78
- , 44 107 107 107 44 107
- - 45 96 96 96 45 96
- . 46 75 75 75 46 75
- / 47 97 97 97 47 97
- 0 48 240 240 240 48 240
- 1 49 241 241 241 49 241
- 2 50 242 242 242 50 242
- 3 51 243 243 243 51 243
- 4 52 244 244 244 52 244
- 5 53 245 245 245 53 245
- 6 54 246 246 246 54 246
- 7 55 247 247 247 55 247
- 8 56 248 248 248 56 248
- 9 57 249 249 249 57 249
- : 58 122 122 122 58 122
- ; 59 94 94 94 59 94
- < 60 76 76 76 60 76
- = 61 126 126 126 61 126
- > 62 110 110 110 62 110
- ? 63 111 111 111 63 111
- @ 64 124 124 124 64 124
- A 65 193 193 193 65 193
- B 66 194 194 194 66 194
- C 67 195 195 195 67 195
- D 68 196 196 196 68 196
- E 69 197 197 197 69 197
- F 70 198 198 198 70 198
- G 71 199 199 199 71 199
- H 72 200 200 200 72 200
- I 73 201 201 201 73 201
- J 74 209 209 209 74 209
- K 75 210 210 210 75 210
- L 76 211 211 211 76 211
- M 77 212 212 212 77 212
- N 78 213 213 213 78 213
- O 79 214 214 214 79 214
- P 80 215 215 215 80 215
- Q 81 216 216 216 81 216
- R 82 217 217 217 82 217
- S 83 226 226 226 83 226
- T 84 227 227 227 84 227
- U 85 228 228 228 85 228
- V 86 229 229 229 86 229
- W 87 230 230 230 87 230
- X 88 231 231 231 88 231
- Y 89 232 232 232 89 232
- Z 90 233 233 233 90 233
- [ 91 186 173 187 91 173 ** ##
- \ 92 224 224 188 92 224 ##
- ] 93 187 189 189 93 189 **
- ^ 94 176 95 106 94 95 ** ##
- _ 95 109 109 109 95 109
- ` 96 121 121 74 96 121 ##
- a 97 129 129 129 97 129
- b 98 130 130 130 98 130
- c 99 131 131 131 99 131
- d 100 132 132 132 100 132
- e 101 133 133 133 101 133
- f 102 134 134 134 102 134
- g 103 135 135 135 103 135
- h 104 136 136 136 104 136
- i 105 137 137 137 105 137
- j 106 145 145 145 106 145
- k 107 146 146 146 107 146
- l 108 147 147 147 108 147
- m 109 148 148 148 109 148
- n 110 149 149 149 110 149
- o 111 150 150 150 111 150
- p 112 151 151 151 112 151
- q 113 152 152 152 113 152
- r 114 153 153 153 114 153
- s 115 162 162 162 115 162
- t 116 163 163 163 116 163
- u 117 164 164 164 117 164
- v 118 165 165 165 118 165
- w 119 166 166 166 119 166
- x 120 167 167 167 120 167
- y 121 168 168 168 121 168
- z 122 169 169 169 122 169
- { 123 192 192 251 123 192 ##
- | 124 79 79 79 124 79
- } 125 208 208 253 125 208 ##
- ~ 126 161 161 255 126 161 ##
- <DEL> 127 7 7 7 127 7
- <PAD> 128 32 32 32 194.128 32
- <HOP> 129 33 33 33 194.129 33
- <BPH> 130 34 34 34 194.130 34
- <NBH> 131 35 35 35 194.131 35
- <IND> 132 36 36 36 194.132 36
- <NEL> 133 21 37 37 194.133 37 **
- <SSA> 134 6 6 6 194.134 6
- <ESA> 135 23 23 23 194.135 23
- <HTS> 136 40 40 40 194.136 40
- <HTJ> 137 41 41 41 194.137 41
- <VTS> 138 42 42 42 194.138 42
- <PLD> 139 43 43 43 194.139 43
- <PLU> 140 44 44 44 194.140 44
- <RI> 141 9 9 9 194.141 9
- <SS2> 142 10 10 10 194.142 10
- <SS3> 143 27 27 27 194.143 27
- <DCS> 144 48 48 48 194.144 48
- <PU1> 145 49 49 49 194.145 49
- <PU2> 146 26 26 26 194.146 26
- <STS> 147 51 51 51 194.147 51
- <CCH> 148 52 52 52 194.148 52
- <MW> 149 53 53 53 194.149 53
- <SPA> 150 54 54 54 194.150 54
- <EPA> 151 8 8 8 194.151 8
- <SOS> 152 56 56 56 194.152 56
- <SGC> 153 57 57 57 194.153 57
- <SCI> 154 58 58 58 194.154 58
- <CSI> 155 59 59 59 194.155 59
- <ST> 156 4 4 4 194.156 4
- <OSC> 157 20 20 20 194.157 20
- <PM> 158 62 62 62 194.158 62
- <APC> 159 255 255 95 194.159 255 ##
- <NON-BREAKING SPACE> 160 65 65 65 194.160 128.65
- <INVERTED "!" > 161 170 170 170 194.161
128.66
- <CENT SIGN> 162 74 74 176 194.162 128.67 ##
- <POUND SIGN> 163 177 177 177 194.163 128.68
- <CURRENCY SIGN> 164 159 159 159 194.164 128.69
- <YEN SIGN> 165 178 178 178 194.165 128.70
- <BROKEN BAR> 166 106 106 208 194.166 128.71 ##
- <SECTION SIGN> 167 181 181 181 194.167 128.72
- <DIAERESIS> 168 189 187 121 194.168 128.73 ** ##
- <COPYRIGHT SIGN> 169 180 180 180 194.169 128.74
- <FEMININE ORDINAL> 170 154 154 154 194.170 128.81
- <LEFT POINTING GUILLEMET> 171 138 138 138 194.171 128.82
- <NOT SIGN> 172 95 176 186 194.172 128.83 ** ##
- <SOFT HYPHEN> 173 202 202 202 194.173 128.84
- <REGISTERED TRADE MARK> 174 175 175 175 194.174 128.85
- <MACRON> 175 188 188 161 194.175 128.86 ##
- <DEGREE SIGN> 176 144 144 144 194.176 128.87
- <PLUS-OR-MINUS SIGN> 177 143 143 143 194.177 128.88
- <SUPERSCRIPT TWO> 178 234 234 234 194.178 128.89
- <SUPERSCRIPT THREE> 179 250 250 250 194.179 128.98
- <ACUTE ACCENT> 180 190 190 190 194.180 128.99
- <MICRO SIGN> 181 160 160 160 194.181 128.100
- <PARAGRAPH SIGN> 182 182 182 182 194.182 128.101
- <MIDDLE DOT> 183 179 179 179 194.183 128.102
- <CEDILLA> 184 157 157 157 194.184 128.103
- <SUPERSCRIPT ONE> 185 218 218 218 194.185 128.104
- <MASC. ORDINAL INDICATOR> 186 155 155 155 194.186 128.105
- <RIGHT POINTING GUILLEMET> 187 139 139 139 194.187 128.106
- <FRACTION ONE QUARTER> 188 183 183 183 194.188 128.112
- <FRACTION ONE HALF> 189 184 184 184 194.189 128.113
- <FRACTION THREE QUARTERS> 190 185 185 185 194.190 128.114
- <INVERTED QUESTION MARK> 191 171 171 171 194.191 128.115
- <A WITH GRAVE> 192 100 100 100 195.128 138.65
- <A WITH ACUTE> 193 101 101 101 195.129 138.66
- <A WITH CIRCUMFLEX> 194 98 98 98 195.130 138.67
- <A WITH TILDE> 195 102 102 102 195.131 138.68
- <A WITH DIAERESIS> 196 99 99 99 195.132 138.69
- <A WITH RING ABOVE> 197 103 103 103 195.133 138.70
- <CAPITAL LIGATURE AE> 198 158 158 158 195.134 138.71
- <C WITH CEDILLA> 199 104 104 104 195.135 138.72
- <E WITH GRAVE> 200 116 116 116 195.136 138.73
- <E WITH ACUTE> 201 113 113 113 195.137 138.74
- <E WITH CIRCUMFLEX> 202 114 114 114 195.138 138.81
- <E WITH DIAERESIS> 203 115 115 115 195.139 138.82
- <I WITH GRAVE> 204 120 120 120 195.140 138.83
- <I WITH ACUTE> 205 117 117 117 195.141 138.84
- <I WITH CIRCUMFLEX> 206 118 118 118 195.142 138.85
- <I WITH DIAERESIS> 207 119 119 119 195.143 138.86
- <CAPITAL LETTER ETH> 208 172 172 172 195.144 138.87
- <N WITH TILDE> 209 105 105 105 195.145 138.88
- <O WITH GRAVE> 210 237 237 237 195.146 138.89
- <O WITH ACUTE> 211 238 238 238 195.147 138.98
- <O WITH CIRCUMFLEX> 212 235 235 235 195.148 138.99
- <O WITH TILDE> 213 239 239 239 195.149 138.100
- <O WITH DIAERESIS> 214 236 236 236 195.150 138.101
- <MULTIPLICATION SIGN> 215 191 191 191 195.151 138.102
- <O WITH STROKE> 216 128 128 128 195.152 138.103
- <U WITH GRAVE> 217 253 253 224 195.153 138.104 ##
- <U WITH ACUTE> 218 254 254 254 195.154 138.105
- <U WITH CIRCUMFLEX> 219 251 251 221 195.155 138.106 ##
- <U WITH DIAERESIS> 220 252 252 252 195.156 138.112
- <Y WITH ACUTE> 221 173 186 173 195.157 138.113 ** ##
- <CAPITAL LETTER THORN> 222 174 174 174 195.158 138.114
- <SMALL LETTER SHARP S> 223 89 89 89 195.159 138.115
- <a WITH GRAVE> 224 68 68 68 195.160 139.65
- <a WITH ACUTE> 225 69 69 69 195.161 139.66
- <a WITH CIRCUMFLEX> 226 66 66 66 195.162 139.67
- <a WITH TILDE> 227 70 70 70 195.163 139.68
- <a WITH DIAERESIS> 228 67 67 67 195.164 139.69
- <a WITH RING ABOVE> 229 71 71 71 195.165 139.70
- <SMALL LIGATURE ae> 230 156 156 156 195.166 139.71
- <c WITH CEDILLA> 231 72 72 72 195.167 139.72
- <e WITH GRAVE> 232 84 84 84 195.168 139.73
- <e WITH ACUTE> 233 81 81 81 195.169 139.74
- <e WITH CIRCUMFLEX> 234 82 82 82 195.170 139.81
- <e WITH DIAERESIS> 235 83 83 83 195.171 139.82
- <i WITH GRAVE> 236 88 88 88 195.172 139.83
- <i WITH ACUTE> 237 85 85 85 195.173 139.84
- <i WITH CIRCUMFLEX> 238 86 86 86 195.174 139.85
- <i WITH DIAERESIS> 239 87 87 87 195.175 139.86
- <SMALL LETTER eth> 240 140 140 140 195.176 139.87
- <n WITH TILDE> 241 73 73 73 195.177 139.88
- <o WITH GRAVE> 242 205 205 205 195.178 139.89
- <o WITH ACUTE> 243 206 206 206 195.179 139.98
- <o WITH CIRCUMFLEX> 244 203 203 203 195.180 139.99
- <o WITH TILDE> 245 207 207 207 195.181 139.100
- <o WITH DIAERESIS> 246 204 204 204 195.182 139.101
- <DIVISION SIGN> 247 225 225 225 195.183 139.102
- <o WITH STROKE> 248 112 112 112 195.184 139.103
- <u WITH GRAVE> 249 221 221 192 195.185 139.104 ##
- <u WITH ACUTE> 250 222 222 222 195.186 139.105
- <u WITH CIRCUMFLEX> 251 219 219 219 195.187 139.106
- <u WITH DIAERESIS> 252 220 220 220 195.188 139.112
- <y WITH ACUTE> 253 141 141 141 195.189 139.113
- <SMALL LETTER thorn> 254 142 142 142 195.190 139.114
- <y WITH DIAERESIS> 255 223 223 223 195.191 139.115
-</pre>
-<p>If you would rather see the above table in CCSID 0037 order rather than
-ASCII + Latin-1 order then run the table through:
-</p>
-<dl compact="compact">
-<dt>recipe 4</dt>
-<dd><a name="perlebcdic-recipe-4"></a>
-</dd>
-</dl>
-
-<pre class="verbatim"> perl \
- -ne 'if(/.{29}\d{1,3}\s{2,4}\d{1,3}\s{2,4}\d{1,3}\s{2,4}\d{1,3}/)'\
- -e '{push(@l,$_)}' \
- -e 'END{print map{$_->[0]}' \
- -e ' sort{$a->[1] <=> $b->[1]}' \
- -e ' map{[$_,substr($_,34,3)address@hidden;}' perlebcdic.pod
-</pre>
-<p>If you would rather see it in CCSID 1047 order then change the number
-34 in the last line to 39, like this:
-</p>
-<dl compact="compact">
-<dt>recipe 5</dt>
-<dd><a name="perlebcdic-recipe-5"></a>
-</dd>
-</dl>
-
-<pre class="verbatim"> perl \
- -ne 'if(/.{29}\d{1,3}\s{2,4}\d{1,3}\s{2,4}\d{1,3}\s{2,4}\d{1,3}/)'\
- -e '{push(@l,$_)}' \
- -e 'END{print map{$_->[0]}' \
- -e ' sort{$a->[1] <=> $b->[1]}' \
- -e ' map{[$_,substr($_,39,3)address@hidden;}' perlebcdic.pod
-</pre>
-<p>If you would rather see it in POSIX-BC order then change the number
-34 in the last line to 44, like this:
-</p>
-<dl compact="compact">
-<dt>recipe 6</dt>
-<dd><a name="perlebcdic-recipe-6"></a>
-</dd>
-</dl>
-
-<pre class="verbatim"> perl \
- -ne 'if(/.{29}\d{1,3}\s{2,4}\d{1,3}\s{2,4}\d{1,3}\s{2,4}\d{1,3}/)'\
- -e '{push(@l,$_)}' \
- -e 'END{print map{$_->[0]}' \
- -e ' sort{$a->[1] <=> $b->[1]}' \
- -e ' map{[$_,substr($_,44,3)address@hidden;}' perlebcdic.pod
-</pre>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Table-in-hex_002c-sorted-in-1047-order"
accesskey="1">perlebcdic Table in hex, sorted in 1047
order</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlebcdic-Table-in-hex_002c-sorted-in-1047-order"></a>
-<div class="header">
-<p>
-Up: <a href="#perlebcdic-SINGLE-OCTET-TABLES" accesskey="u"
rel="up">perlebcdic SINGLE OCTET TABLES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Table-in-hex_002c-sorted-in-1047-order"></a>
-<h4 class="subsection">19.4.1 Table in hex, sorted in 1047 order</h4>
-
-<p>Since this document was first written, the convention has become more
-and more to use hexadecimal notation for code points. To do this with
-the recipes and to also sort is a multi-step process, so here, for
-convenience, is the table from above, re-sorted to be in Code Page 1047
-order, and using hex notation.
-</p>
-<pre class="verbatim"> ISO
- 8859-1 POS- CCSID
- CCSID CCSID CCSID IX- 1047
- chr 0819 0037 1047 BC UTF-8 UTF-EBCDIC
- ---------------------------------------------------------------------
- <NUL> 00 00 00 00 00 00
- <SOH> 01 01 01 01 01 01
- <STX> 02 02 02 02 02 02
- <ETX> 03 03 03 03 03 03
- <ST> 9C 04 04 04 C2.9C 04
- <HT> 09 05 05 05 09 05
- <SSA> 86 06 06 06 C2.86 06
- <DEL> 7F 07 07 07 7F 07
- <EPA> 97 08 08 08 C2.97 08
- <RI> 8D 09 09 09 C2.8D 09
- <SS2> 8E 0A 0A 0A C2.8E 0A
- <VT> 0B 0B 0B 0B 0B 0B
- <FF> 0C 0C 0C 0C 0C 0C
- <CR> 0D 0D 0D 0D 0D 0D
- <SO> 0E 0E 0E 0E 0E 0E
- <SI> 0F 0F 0F 0F 0F 0F
- <DLE> 10 10 10 10 10 10
- <DC1> 11 11 11 11 11 11
- <DC2> 12 12 12 12 12 12
- <DC3> 13 13 13 13 13 13
- <OSC> 9D 14 14 14 C2.9D 14
- <LF> 0A 25 15 15 0A 15 **
- <BS> 08 16 16 16 08 16
- <ESA> 87 17 17 17 C2.87 17
- <CAN> 18 18 18 18 18 18
- <EOM> 19 19 19 19 19 19
- <PU2> 92 1A 1A 1A C2.92 1A
- <SS3> 8F 1B 1B 1B C2.8F 1B
- <FS> 1C 1C 1C 1C 1C 1C
- <GS> 1D 1D 1D 1D 1D 1D
- <RS> 1E 1E 1E 1E 1E 1E
- <US> 1F 1F 1F 1F 1F 1F
- <PAD> 80 20 20 20 C2.80 20
- <HOP> 81 21 21 21 C2.81 21
- <BPH> 82 22 22 22 C2.82 22
- <NBH> 83 23 23 23 C2.83 23
- <IND> 84 24 24 24 C2.84 24
- <NEL> 85 15 25 25 C2.85 25 **
- <ETB> 17 26 26 26 17 26
- <ESC> 1B 27 27 27 1B 27
- <HTS> 88 28 28 28 C2.88 28
- <HTJ> 89 29 29 29 C2.89 29
- <VTS> 8A 2A 2A 2A C2.8A 2A
- <PLD> 8B 2B 2B 2B C2.8B 2B
- <PLU> 8C 2C 2C 2C C2.8C 2C
- <ENQ> 05 2D 2D 2D 05 2D
- <ACK> 06 2E 2E 2E 06 2E
- <BEL> 07 2F 2F 2F 07 2F
- <DCS> 90 30 30 30 C2.90 30
- <PU1> 91 31 31 31 C2.91 31
- <SYN> 16 32 32 32 16 32
- <STS> 93 33 33 33 C2.93 33
- <CCH> 94 34 34 34 C2.94 34
- <MW> 95 35 35 35 C2.95 35
- <SPA> 96 36 36 36 C2.96 36
- <EOT> 04 37 37 37 04 37
- <SOS> 98 38 38 38 C2.98 38
- <SGC> 99 39 39 39 C2.99 39
- <SCI> 9A 3A 3A 3A C2.9A 3A
- <CSI> 9B 3B 3B 3B C2.9B 3B
- <DC4> 14 3C 3C 3C 14 3C
- <NAK> 15 3D 3D 3D 15 3D
- <PM> 9E 3E 3E 3E C2.9E 3E
- <SUB> 1A 3F 3F 3F 1A 3F
- <SPACE> 20 40 40 40 20 40
- <NON-BREAKING SPACE> A0 41 41 41 C2.A0 80.41
- <a WITH CIRCUMFLEX> E2 42 42 42 C3.A2 8B.43
- <a WITH DIAERESIS> E4 43 43 43 C3.A4 8B.45
- <a WITH GRAVE> E0 44 44 44 C3.A0 8B.41
- <a WITH ACUTE> E1 45 45 45 C3.A1 8B.42
- <a WITH TILDE> E3 46 46 46 C3.A3 8B.44
- <a WITH RING ABOVE> E5 47 47 47 C3.A5 8B.46
- <c WITH CEDILLA> E7 48 48 48 C3.A7 8B.48
- <n WITH TILDE> F1 49 49 49 C3.B1 8B.58
- <CENT SIGN> A2 4A 4A B0 C2.A2 80.43 ##
- . 2E 4B 4B 4B 2E 4B
- < 3C 4C 4C 4C 3C 4C
- ( 28 4D 4D 4D 28 4D
- + 2B 4E 4E 4E 2B 4E
- | 7C 4F 4F 4F 7C 4F
- & 26 50 50 50 26 50
- <e WITH ACUTE> E9 51 51 51 C3.A9 8B.4A
- <e WITH CIRCUMFLEX> EA 52 52 52 C3.AA 8B.51
- <e WITH DIAERESIS> EB 53 53 53 C3.AB 8B.52
- <e WITH GRAVE> E8 54 54 54 C3.A8 8B.49
- <i WITH ACUTE> ED 55 55 55 C3.AD 8B.54
- <i WITH CIRCUMFLEX> EE 56 56 56 C3.AE 8B.55
- <i WITH DIAERESIS> EF 57 57 57 C3.AF 8B.56
- <i WITH GRAVE> EC 58 58 58 C3.AC 8B.53
- <SMALL LETTER SHARP S> DF 59 59 59 C3.9F 8A.73
- ! 21 5A 5A 5A 21 5A
- $ 24 5B 5B 5B 24 5B
- * 2A 5C 5C 5C 2A 5C
- ) 29 5D 5D 5D 29 5D
- ; 3B 5E 5E 5E 3B 5E
- ^ 5E B0 5F 6A 5E 5F ** ##
- - 2D 60 60 60 2D 60
- / 2F 61 61 61 2F 61
- <A WITH CIRCUMFLEX> C2 62 62 62 C3.82 8A.43
- <A WITH DIAERESIS> C4 63 63 63 C3.84 8A.45
- <A WITH GRAVE> C0 64 64 64 C3.80 8A.41
- <A WITH ACUTE> C1 65 65 65 C3.81 8A.42
- <A WITH TILDE> C3 66 66 66 C3.83 8A.44
- <A WITH RING ABOVE> C5 67 67 67 C3.85 8A.46
- <C WITH CEDILLA> C7 68 68 68 C3.87 8A.48
- <N WITH TILDE> D1 69 69 69 C3.91 8A.58
- <BROKEN BAR> A6 6A 6A D0 C2.A6 80.47 ##
- , 2C 6B 6B 6B 2C 6B
- % 25 6C 6C 6C 25 6C
- _ 5F 6D 6D 6D 5F 6D
- > 3E 6E 6E 6E 3E 6E
- ? 3F 6F 6F 6F 3F 6F
- <o WITH STROKE> F8 70 70 70 C3.B8 8B.67
- <E WITH ACUTE> C9 71 71 71 C3.89 8A.4A
- <E WITH CIRCUMFLEX> CA 72 72 72 C3.8A 8A.51
- <E WITH DIAERESIS> CB 73 73 73 C3.8B 8A.52
- <E WITH GRAVE> C8 74 74 74 C3.88 8A.49
- <I WITH ACUTE> CD 75 75 75 C3.8D 8A.54
- <I WITH CIRCUMFLEX> CE 76 76 76 C3.8E 8A.55
- <I WITH DIAERESIS> CF 77 77 77 C3.8F 8A.56
- <I WITH GRAVE> CC 78 78 78 C3.8C 8A.53
- ` 60 79 79 4A 60 79 ##
- : 3A 7A 7A 7A 3A 7A
- # 23 7B 7B 7B 23 7B
- @ 40 7C 7C 7C 40 7C
- ' 27 7D 7D 7D 27 7D
- = 3D 7E 7E 7E 3D 7E
- " 22 7F 7F 7F 22 7F
- <O WITH STROKE> D8 80 80 80 C3.98 8A.67
- a 61 81 81 81 61 81
- b 62 82 82 82 62 82
- c 63 83 83 83 63 83
- d 64 84 84 84 64 84
- e 65 85 85 85 65 85
- f 66 86 86 86 66 86
- g 67 87 87 87 67 87
- h 68 88 88 88 68 88
- i 69 89 89 89 69 89
- <LEFT POINTING GUILLEMET> AB 8A 8A 8A C2.AB 80.52
- <RIGHT POINTING GUILLEMET> BB 8B 8B 8B C2.BB 80.6A
- <SMALL LETTER eth> F0 8C 8C 8C C3.B0 8B.57
- <y WITH ACUTE> FD 8D 8D 8D C3.BD 8B.71
- <SMALL LETTER thorn> FE 8E 8E 8E C3.BE 8B.72
- <PLUS-OR-MINUS SIGN> B1 8F 8F 8F C2.B1 80.58
- <DEGREE SIGN> B0 90 90 90 C2.B0 80.57
- j 6A 91 91 91 6A 91
- k 6B 92 92 92 6B 92
- l 6C 93 93 93 6C 93
- m 6D 94 94 94 6D 94
- n 6E 95 95 95 6E 95
- o 6F 96 96 96 6F 96
- p 70 97 97 97 70 97
- q 71 98 98 98 71 98
- r 72 99 99 99 72 99
- <FEMININE ORDINAL> AA 9A 9A 9A C2.AA 80.51
- <MASC. ORDINAL INDICATOR> BA 9B 9B 9B C2.BA 80.69
- <SMALL LIGATURE ae> E6 9C 9C 9C C3.A6 8B.47
- <CEDILLA> B8 9D 9D 9D C2.B8 80.67
- <CAPITAL LIGATURE AE> C6 9E 9E 9E C3.86 8A.47
- <CURRENCY SIGN> A4 9F 9F 9F C2.A4 80.45
- <MICRO SIGN> B5 A0 A0 A0 C2.B5 80.64
- ~ 7E A1 A1 FF 7E A1 ##
- s 73 A2 A2 A2 73 A2
- t 74 A3 A3 A3 74 A3
- u 75 A4 A4 A4 75 A4
- v 76 A5 A5 A5 76 A5
- w 77 A6 A6 A6 77 A6
- x 78 A7 A7 A7 78 A7
- y 79 A8 A8 A8 79 A8
- z 7A A9 A9 A9 7A A9
- <INVERTED "!" > A1 AA AA AA C2.A1 80.42
- <INVERTED QUESTION MARK> BF AB AB AB C2.BF 80.73
- <CAPITAL LETTER ETH> D0 AC AC AC C3.90 8A.57
- [ 5B BA AD BB 5B AD ** ##
- <CAPITAL LETTER THORN> DE AE AE AE C3.9E 8A.72
- <REGISTERED TRADE MARK> AE AF AF AF C2.AE 80.55
- <NOT SIGN> AC 5F B0 BA C2.AC 80.53 ** ##
- <POUND SIGN> A3 B1 B1 B1 C2.A3 80.44
- <YEN SIGN> A5 B2 B2 B2 C2.A5 80.46
- <MIDDLE DOT> B7 B3 B3 B3 C2.B7 80.66
- <COPYRIGHT SIGN> A9 B4 B4 B4 C2.A9 80.4A
- <SECTION SIGN> A7 B5 B5 B5 C2.A7 80.48
- <PARAGRAPH SIGN> B6 B6 B6 B6 C2.B6 80.65
- <FRACTION ONE QUARTER> BC B7 B7 B7 C2.BC 80.70
- <FRACTION ONE HALF> BD B8 B8 B8 C2.BD 80.71
- <FRACTION THREE QUARTERS> BE B9 B9 B9 C2.BE 80.72
- <Y WITH ACUTE> DD AD BA AD C3.9D 8A.71 ** ##
- <DIAERESIS> A8 BD BB 79 C2.A8 80.49 ** ##
- <MACRON> AF BC BC A1 C2.AF 80.56 ##
- ] 5D BB BD BD 5D BD **
- <ACUTE ACCENT> B4 BE BE BE C2.B4 80.63
- <MULTIPLICATION SIGN> D7 BF BF BF C3.97 8A.66
- { 7B C0 C0 FB 7B C0 ##
- A 41 C1 C1 C1 41 C1
- B 42 C2 C2 C2 42 C2
- C 43 C3 C3 C3 43 C3
- D 44 C4 C4 C4 44 C4
- E 45 C5 C5 C5 45 C5
- F 46 C6 C6 C6 46 C6
- G 47 C7 C7 C7 47 C7
- H 48 C8 C8 C8 48 C8
- I 49 C9 C9 C9 49 C9
- <SOFT HYPHEN> AD CA CA CA C2.AD 80.54
- <o WITH CIRCUMFLEX> F4 CB CB CB C3.B4 8B.63
- <o WITH DIAERESIS> F6 CC CC CC C3.B6 8B.65
- <o WITH GRAVE> F2 CD CD CD C3.B2 8B.59
- <o WITH ACUTE> F3 CE CE CE C3.B3 8B.62
- <o WITH TILDE> F5 CF CF CF C3.B5 8B.64
- } 7D D0 D0 FD 7D D0 ##
- J 4A D1 D1 D1 4A D1
- K 4B D2 D2 D2 4B D2
- L 4C D3 D3 D3 4C D3
- M 4D D4 D4 D4 4D D4
- N 4E D5 D5 D5 4E D5
- O 4F D6 D6 D6 4F D6
- P 50 D7 D7 D7 50 D7
- Q 51 D8 D8 D8 51 D8
- R 52 D9 D9 D9 52 D9
- <SUPERSCRIPT ONE> B9 DA DA DA C2.B9 80.68
- <u WITH CIRCUMFLEX> FB DB DB DB C3.BB 8B.6A
- <u WITH DIAERESIS> FC DC DC DC C3.BC 8B.70
- <u WITH GRAVE> F9 DD DD C0 C3.B9 8B.68 ##
- <u WITH ACUTE> FA DE DE DE C3.BA 8B.69
- <y WITH DIAERESIS> FF DF DF DF C3.BF 8B.73
- \ 5C E0 E0 BC 5C E0 ##
- <DIVISION SIGN> F7 E1 E1 E1 C3.B7 8B.66
- S 53 E2 E2 E2 53 E2
- T 54 E3 E3 E3 54 E3
- U 55 E4 E4 E4 55 E4
- V 56 E5 E5 E5 56 E5
- W 57 E6 E6 E6 57 E6
- X 58 E7 E7 E7 58 E7
- Y 59 E8 E8 E8 59 E8
- Z 5A E9 E9 E9 5A E9
- <SUPERSCRIPT TWO> B2 EA EA EA C2.B2 80.59
- <O WITH CIRCUMFLEX> D4 EB EB EB C3.94 8A.63
- <O WITH DIAERESIS> D6 EC EC EC C3.96 8A.65
- <O WITH GRAVE> D2 ED ED ED C3.92 8A.59
- <O WITH ACUTE> D3 EE EE EE C3.93 8A.62
- <O WITH TILDE> D5 EF EF EF C3.95 8A.64
- 0 30 F0 F0 F0 30 F0
- 1 31 F1 F1 F1 31 F1
- 2 32 F2 F2 F2 32 F2
- 3 33 F3 F3 F3 33 F3
- 4 34 F4 F4 F4 34 F4
- 5 35 F5 F5 F5 35 F5
- 6 36 F6 F6 F6 36 F6
- 7 37 F7 F7 F7 37 F7
- 8 38 F8 F8 F8 38 F8
- 9 39 F9 F9 F9 39 F9
- <SUPERSCRIPT THREE> B3 FA FA FA C2.B3 80.62
- <U WITH CIRCUMFLEX> DB FB FB DD C3.9B 8A.6A ##
- <U WITH DIAERESIS> DC FC FC FC C3.9C 8A.70
- <U WITH GRAVE> D9 FD FD E0 C3.99 8A.68 ##
- <U WITH ACUTE> DA FE FE FE C3.9A 8A.69
- <APC> 9F FF FF 5F C2.9F FF ##
-</pre>
-<hr>
-<a name="perlebcdic-IDENTIFYING-CHARACTER-CODE-SETS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-CONVERSIONS" accesskey="n" rel="next">perlebcdic
CONVERSIONS</a>, Previous: <a href="#perlebcdic-SINGLE-OCTET-TABLES"
accesskey="p" rel="prev">perlebcdic SINGLE OCTET TABLES</a>, Up: <a
href="#perlebcdic" accesskey="u" rel="up">perlebcdic</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="IDENTIFYING-CHARACTER-CODE-SETS"></a>
-<h3 class="section">19.5 IDENTIFYING CHARACTER CODE SETS</h3>
-
-<p>It is possible to determine which character set you are operating under.
-But first you need to be really really sure you need to do this. Your
-code will be simpler and probably just as portable if you don’t have
-to test the character set and do different things, depending. There are
-actually only very few circumstances where it’s not easy to write
-straight-line code portable to all character sets. See
-<a href="#perluniintro-Unicode-and-EBCDIC">perluniintro Unicode and EBCDIC</a>
for how to portably specify
-characters.
-</p>
-<p>But there are some cases where you may want to know which character set
-you are running under. One possible example is doing
-<a href="#perlebcdic-SORTING">sorting</a> in inner loops where performance is
critical.
-</p>
-<p>To determine if you are running under ASCII or EBCDIC, you can use the
-return value of <code>ord()</code> or <code>chr()</code> to test one or more
character
-values. For example:
-</p>
-<pre class="verbatim"> $is_ascii = "A" eq chr(65);
- $is_ebcdic = "A" eq chr(193);
- $is_ascii = ord("A") == 65;
- $is_ebcdic = ord("A") == 193;
-</pre>
-<p>There’s even less need to distinguish between EBCDIC code pages, but
to
-do so try looking at one or more of the characters that differ between
-them.
-</p>
-<pre class="verbatim"> $is_ascii = ord('[') == 91;
- $is_ebcdic_37 = ord('[') == 186;
- $is_ebcdic_1047 = ord('[') == 173;
- $is_ebcdic_POSIX_BC = ord('[') == 187;
-</pre>
-<p>However, it would be unwise to write tests such as:
-</p>
-<pre class="verbatim"> $is_ascii = "\r" ne chr(13); # WRONG
- $is_ascii = "\n" ne chr(10); # ILL ADVISED
-</pre>
-<p>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 <code>"\r" eq chr(13)</code><!-- /@w -->
under all of those coded character
-sets. But note too that because <code>"\n"</code> is
<code>chr(13)</code> and <code>"\r"</code> is
-<code>chr(10)</code> on old Macintosh (which is an ASCII platform) the second
-<code>$is_ascii</code> test will lead to trouble there.
-</p>
-<p>To determine whether or not perl was built under an EBCDIC
-code page you can use the Config module like so:
-</p>
-<pre class="verbatim"> use Config;
- $is_ebcdic = $Config{'ebcdic'} eq 'define';
-</pre>
-<hr>
-<a name="perlebcdic-CONVERSIONS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-OPERATOR-DIFFERENCES" accesskey="n"
rel="next">perlebcdic OPERATOR DIFFERENCES</a>, Previous: <a
href="#perlebcdic-IDENTIFYING-CHARACTER-CODE-SETS" accesskey="p"
rel="prev">perlebcdic IDENTIFYING CHARACTER CODE SETS</a>, Up: <a
href="#perlebcdic" accesskey="u" rel="up">perlebcdic</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="CONVERSIONS"></a>
-<h3 class="section">19.6 CONVERSIONS</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-utf8_003a_003aunicode_005fto_005fnative_0028_0029-and-utf8_003a_003anative_005fto_005funicode_0028_0029"
accesskey="1">perlebcdic <code>utf8::unicode_to_native()</code> and
<code>utf8::native_to_unicode()</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-tr_002f_002f_002f" accesskey="2">perlebcdic
tr///</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlebcdic-iconv"
accesskey="3">perlebcdic iconv</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlebcdic-C-RTL"
accesskey="4">perlebcdic C RTL</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a
name="perlebcdic-utf8_003a_003aunicode_005fto_005fnative_0028_0029-and-utf8_003a_003anative_005fto_005funicode_0028_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-tr_002f_002f_002f" accesskey="n"
rel="next">perlebcdic tr///</a>, Up: <a href="#perlebcdic-CONVERSIONS"
accesskey="u" rel="up">perlebcdic CONVERSIONS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a
name="utf8_003a_003aunicode_005fto_005fnative_0028_0029-and-utf8_003a_003anative_005fto_005funicode_0028_0029"></a>
-<h4 class="subsection">19.6.1 <code>utf8::unicode_to_native()</code> and
<code>utf8::native_to_unicode()</code></h4>
-
-<p>These functions take an input numeric code point in one encoding and
-return what its equivalent value is in the other.
-</p>
-<p>See <a href="utf8.html#Top">(utf8)</a>.
-</p>
-<hr>
-<a name="perlebcdic-tr_002f_002f_002f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-iconv" accesskey="n" rel="next">perlebcdic
iconv</a>, Previous: <a
href="#perlebcdic-utf8_003a_003aunicode_005fto_005fnative_0028_0029-and-utf8_003a_003anative_005fto_005funicode_0028_0029"
accesskey="p" rel="prev">perlebcdic <code>utf8::unicode_to_native()</code> and
<code>utf8::native_to_unicode()</code></a>, Up: <a
href="#perlebcdic-CONVERSIONS" accesskey="u" rel="up">perlebcdic
CONVERSIONS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="tr_002f_002f_002f"></a>
-<h4 class="subsection">19.6.2 tr///</h4>
-
-<p>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 <code>tr///</code> operator is all that
is needed.
-The data in the table are in ASCII/Latin1 order, hence the EBCDIC columns
-provide easy-to-use ASCII/Latin1 to EBCDIC operations that are also easily
-reversed.
-</p>
-<p>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
-<code>"\"</code> characters), and use it in <code>tr///</code> like
so:
-</p>
-<pre class="verbatim"> $cp_037 =
- '\x00\x01\x02\x03\x37\x2D\x2E\x2F\x16\x05\x25\x0B\x0C\x0D\x0E\x0F' .
- '\x10\x11\x12\x13\x3C\x3D\x32\x26\x18\x19\x3F\x27\x1C\x1D\x1E\x1F' .
- '\x40\x5A\x7F\x7B\x5B\x6C\x50\x7D\x4D\x5D\x5C\x4E\x6B\x60\x4B\x61' .
- '\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/\000-\377/' . $cp_037 . '/';
-</pre>
-<p>To convert from EBCDIC 037 to ASCII just reverse the order of the tr///
-arguments like so:
-</p>
-<pre class="verbatim"> my $ascii_string = $ebcdic_string;
- eval '$ascii_string =~ tr/' . $cp_037 . '/\000-\377/';
-</pre>
-<p>Similarly one could take the output of the third numbers column from recipe
2
-to obtain a <code>$cp_1047</code> table. The fourth numbers column of the
output from
-recipe 2 could provide a <code>$cp_posix_bc</code> table suitable for
transcoding as
-well.
-</p>
-<p>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.
-</p>
-<hr>
-<a name="perlebcdic-iconv"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-C-RTL" accesskey="n" rel="next">perlebcdic C
RTL</a>, Previous: <a href="#perlebcdic-tr_002f_002f_002f" accesskey="p"
rel="prev">perlebcdic tr///</a>, Up: <a href="#perlebcdic-CONVERSIONS"
accesskey="u" rel="up">perlebcdic CONVERSIONS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="iconv"></a>
-<h4 class="subsection">19.6.3 iconv</h4>
-
-<p>XPG operability often implies the presence of an <em>iconv</em> utility
-available from the shell or from the C library. Consult your system’s
-documentation for information on iconv.
-</p>
-<p>On OS/390 or z/OS see the <a
href="http://man.he.net/man1/iconv";>iconv(1)</a> manpage. One way to invoke
the <code>iconv</code>
-shell utility from within perl would be to:
-</p>
-<pre class="verbatim"> # OS/390 or z/OS example
- $ascii_data = `echo '$ebcdic_data'| iconv -f IBM-1047 -t ISO8859-1`
-</pre>
-<p>or the inverse map:
-</p>
-<pre class="verbatim"> # OS/390 or z/OS example
- $ebcdic_data = `echo '$ascii_data'| iconv -f ISO8859-1 -t IBM-1047`
-</pre>
-<p>For other Perl-based conversion options see the <code>Convert::*</code>
modules on CPAN.
-</p>
-<hr>
-<a name="perlebcdic-C-RTL"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlebcdic-iconv" accesskey="p" rel="prev">perlebcdic
iconv</a>, Up: <a href="#perlebcdic-CONVERSIONS" accesskey="u"
rel="up">perlebcdic CONVERSIONS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="C-RTL"></a>
-<h4 class="subsection">19.6.4 C RTL</h4>
-
-<p>The OS/390 and z/OS C run-time libraries provide <code>_atoe()</code> and
<code>_etoa()</code> functions.
-</p>
-<hr>
-<a name="perlebcdic-OPERATOR-DIFFERENCES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-FUNCTION-DIFFERENCES" accesskey="n"
rel="next">perlebcdic FUNCTION DIFFERENCES</a>, Previous: <a
href="#perlebcdic-CONVERSIONS" accesskey="p" rel="prev">perlebcdic
CONVERSIONS</a>, Up: <a href="#perlebcdic" accesskey="u"
rel="up">perlebcdic</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="OPERATOR-DIFFERENCES"></a>
-<h3 class="section">19.7 OPERATOR DIFFERENCES</h3>
-
-<p>The <code>..</code> range operator treats certain character ranges with
-care on EBCDIC platforms. For example the following array
-will have twenty six elements on either an EBCDIC platform
-or an ASCII platform:
-</p>
-<pre class="verbatim"> @alphabet = ('A'..'Z'); # $#alphabet == 25
-</pre>
-<p>The bitwise operators such as & ^ | may return different results
-when operating on string or character data in a Perl program running
-on an EBCDIC platform than when run on an ASCII platform. Here is
-an example adapted from the one in <a href="#perlop-NAME">perlop NAME</a>:
-</p>
-<pre class="verbatim"> # EBCDIC-based examples
- print "j p \n" ^ " a h"; # prints
"JAPH\n"
- print "JA" | " ph\n"; # prints
"japh\n"
- print "JAPH\nJunk" & "\277\277\277\277\277"; #
prints "japh\n";
- print 'p N$' ^ " E<H\n"; # prints
"Perl\n";
-</pre>
-<p>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. <code>(chr(0)</code> eq
<code>\c@</code>)>
-<code>(chr(1)</code> eq <code>\cA</code>)>, and so on. Perl on EBCDIC
platforms has been
-ported to take <code>\c@</code> to <code>chr(0)</code> and <code>\cA</code> to
<code>chr(1)</code>, etc. as well, but the
-characters that result depend on which code page you are
-using. The table below uses the standard acronyms for the controls.
-The POSIX-BC and 1047 sets are
-identical throughout this range and differ from the 0037 set at only
-one spot (21 decimal). Note that the line terminator character
-may be generated by <code>\cJ</code> on ASCII platforms but by
<code>\cU</code> on 1047 or POSIX-BC
-platforms and cannot be generated as a <code>"\c.letter."</code>
control character on
-0037 platforms. Note also that <code>\c\</code> cannot be the final element
in a string
-or regex, as it will absorb the terminator. But <code>\c\<em>X</em></code>
is a <code>FILE
-SEPARATOR</code> concatenated with <em>X</em> for all <em>X</em>.
-The outlier <code>\c?</code> on ASCII, which yields a non-C0 control
<code>DEL</code>,
-yields the outlier control <code>APC</code> on EBCDIC, the one that
isn’t in the
-block of contiguous controls. Note that a subtlety of this is that
-<code>\c?</code> on ASCII platforms is an ASCII character, while it isn’t
-equivalent to any ASCII character in EBCDIC platforms.
-</p>
-<pre class="verbatim"> chr ord 8859-1 0037 1047 && POSIX-BC
- -----------------------------------------------------------------------
- \c@ 0 <NUL> <NUL> <NUL>
- \cA 1 <SOH> <SOH> <SOH>
- \cB 2 <STX> <STX> <STX>
- \cC 3 <ETX> <ETX> <ETX>
- \cD 4 <EOT> <ST> <ST>
- \cE 5 <ENQ> <HT> <HT>
- \cF 6 <ACK> <SSA> <SSA>
- \cG 7 <BEL> <DEL> <DEL>
- \cH 8 <BS> <EPA> <EPA>
- \cI 9 <HT> <RI> <RI>
- \cJ 10 <LF> <SS2> <SS2>
- \cK 11 <VT> <VT> <VT>
- \cL 12 <FF> <FF> <FF>
- \cM 13 <CR> <CR> <CR>
- \cN 14 <SO> <SO> <SO>
- \cO 15 <SI> <SI> <SI>
- \cP 16 <DLE> <DLE> <DLE>
- \cQ 17 <DC1> <DC1> <DC1>
- \cR 18 <DC2> <DC2> <DC2>
- \cS 19 <DC3> <DC3> <DC3>
- \cT 20 <DC4> <OSC> <OSC>
- \cU 21 <NAK> <NEL> <LF> **
- \cV 22 <SYN> <BS> <BS>
- \cW 23 <ETB> <ESA> <ESA>
- \cX 24 <CAN> <CAN> <CAN>
- \cY 25 <EOM> <EOM> <EOM>
- \cZ 26 <SUB> <PU2> <PU2>
- \c[ 27 <ESC> <SS3> <SS3>
- \c\X 28 <FS>X <FS>X <FS>X
- \c] 29 <GS> <GS> <GS>
- \c^ 30 <RS> <RS> <RS>
- \c_ 31 <US> <US> <US>
- \c? * <DEL> <APC> <APC>
-</pre>
-<p><code>*</code> Note: <code>\c?</code> maps to ordinal 127
(<code>DEL</code>) on ASCII platforms, but
-since ordinal 127 is a not a control character on EBCDIC machines,
-<code>\c?</code> instead maps on them to <code>APC</code>, which is 255 in
0037 and 1047,
-and 95 in POSIX-BC.
-</p>
-<hr>
-<a name="perlebcdic-FUNCTION-DIFFERENCES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-REGULAR-EXPRESSION-DIFFERENCES" accesskey="n"
rel="next">perlebcdic REGULAR EXPRESSION DIFFERENCES</a>, Previous: <a
href="#perlebcdic-OPERATOR-DIFFERENCES" accesskey="p" rel="prev">perlebcdic
OPERATOR DIFFERENCES</a>, Up: <a href="#perlebcdic" accesskey="u"
rel="up">perlebcdic</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="FUNCTION-DIFFERENCES"></a>
-<h3 class="section">19.8 FUNCTION DIFFERENCES</h3>
-
-<dl compact="compact">
-<dt><code>chr()</code></dt>
-<dd><a name="perlebcdic-chr_0028_0029"></a>
-<p><code>chr()</code> must be given an EBCDIC code number argument to yield a
desired
-character return value on an EBCDIC platform. For example:
-</p>
-<pre class="verbatim"> $CAPITAL_LETTER_A = chr(193);
-</pre>
-<p>The largest code point that is representable in UTF-EBCDIC is
-U+7FFF_FFFF. If you do <code>chr()</code> on a larger value, a runtime error
-(similar to division by 0) will happen.
-</p>
-</dd>
-<dt><code>ord()</code></dt>
-<dd><a name="perlebcdic-ord_0028_0029"></a>
-<p><code>ord()</code> will return EBCDIC code number values on an EBCDIC
platform.
-For example:
-</p>
-<pre class="verbatim"> $the_number_193 = ord("A");
-</pre>
-</dd>
-<dt><code>pack()</code></dt>
-<dd><a name="perlebcdic-pack_0028_0029"></a>
-<p>The <code>"c"</code> and <code>"C"</code> templates for
<code>pack()</code> are dependent upon character set
-encoding. Examples of usage on EBCDIC include:
-</p>
-<pre class="verbatim"> $foo = pack("CCCC",193,194,195,196);
- # $foo eq "ABCD"
- $foo = pack("C4",193,194,195,196);
- # same thing
-
- $foo = pack("ccxxcc",193,194,195,196);
- # $foo eq "AB\0\0CD"
-</pre>
-<p>The <code>"U"</code> template has been ported to mean
"Unicode" on all platforms so
-that
-</p>
-<pre class="verbatim"> pack("U", 65) eq 'A'
-</pre>
-<p>is true on all platforms. If you want native code points for the low
-256, use the <code>"W"</code> template. This means that the
equivalences
-</p>
-<pre class="verbatim"> pack("W", ord($character)) eq $character
- unpack("W", $character) == ord $character
-</pre>
-<p>will hold.
-</p>
-<p>The largest code point that is representable in UTF-EBCDIC is
-U+7FFF_FFFF. If you try to pack a larger value into a character, a
-runtime error (similar to division by 0) will happen.
-</p>
-</dd>
-<dt><code>print()</code></dt>
-<dd><a name="perlebcdic-print_0028_0029"></a>
-<p>One must be careful with scalars and strings that are passed to
-print that contain ASCII encodings. One common place
-for this to occur is in the output of the MIME type header for
-CGI script writing. For example, many Perl programming guides
-recommend something similar to:
-</p>
-<pre class="verbatim"> print
"Content-type:\ttext/html\015\012\015\012";
- # this may be wrong on EBCDIC
-</pre>
-<p>You can instead write
-</p>
-<pre class="verbatim"> print "Content-type:\ttext/html\r\n\r\n";
# OK for DGW et al
-</pre>
-<p>and have it work portably.
-</p>
-<p>That is because the translation from EBCDIC to ASCII is done
-by the web server in this case. Consult your web server’s documentation
for
-further details.
-</p>
-</dd>
-<dt><code>printf()</code></dt>
-<dd><a name="perlebcdic-printf_0028_0029"></a>
-<p>The formats that can convert characters to numbers and vice versa
-will be different from their ASCII counterparts when executed
-on an EBCDIC platform. Examples include:
-</p>
-<pre class="verbatim"> printf("%c%c%c",193,194,195); # prints ABC
-</pre>
-</dd>
-<dt><code>sort()</code></dt>
-<dd><a name="perlebcdic-sort_0028_0029"></a>
-<p>EBCDIC sort results may differ from ASCII sort results especially for
-mixed case strings. This is discussed in more detail <a
href="#perlebcdic-SORTING">below</a>.
-</p>
-</dd>
-<dt><code>sprintf()</code></dt>
-<dd><a name="perlebcdic-sprintf_0028_0029"></a>
-<p>See the discussion of <code><a
href="#perlebcdic-printf_0028_0029">printf()</a></code> above. An example of
the use
-of sprintf would be:
-</p>
-<pre class="verbatim"> $CAPITAL_LETTER_A = sprintf("%c",193);
-</pre>
-</dd>
-<dt><code>unpack()</code></dt>
-<dd><a name="perlebcdic-unpack_0028_0029"></a>
-<p>See the discussion of <code><a
href="#perlebcdic-pack_0028_0029">pack()</a></code> above.
-</p>
-</dd>
-</dl>
-
-<p>Note that it is possible to write portable code for these by specifying
-things in Unicode numbers, and using a conversion function:
-</p>
-<pre class="verbatim"> printf("%c",utf8::unicode_to_native(65));
# prints A on all
- # platforms
- print utf8::native_to_unicode(ord("A")); # Likewise, prints 65
-</pre>
-<p>See <a href="#perluniintro-Unicode-and-EBCDIC">perluniintro Unicode and
EBCDIC</a> and <a href="#perlebcdic-CONVERSIONS">CONVERSIONS</a>
-for other options.
-</p>
-<hr>
-<a name="perlebcdic-REGULAR-EXPRESSION-DIFFERENCES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-SOCKETS" accesskey="n" rel="next">perlebcdic
SOCKETS</a>, Previous: <a href="#perlebcdic-FUNCTION-DIFFERENCES" accesskey="p"
rel="prev">perlebcdic FUNCTION DIFFERENCES</a>, Up: <a href="#perlebcdic"
accesskey="u" rel="up">perlebcdic</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="REGULAR-EXPRESSION-DIFFERENCES"></a>
-<h3 class="section">19.9 REGULAR EXPRESSION DIFFERENCES</h3>
-
-<p>You can write your regular expressions just like someone on an ASCII
-platform would do. But keep in mind that using octal or hex notation to
-specify a particular code point will give you the character that the
-EBCDIC code page natively maps to it. (This is also true of all
-double-quoted strings.) If you want to write portably, just use the
-<code>\N{U+...}</code> notation everywhere where you would have used
<code>\x{...}</code>,
-and don’t use octal notation at all.
-</p>
-<p>Starting in Perl v5.22, this applies to ranges in bracketed character
-classes. If you say, for example, <code>qr/[\N{U+20}-\N{U+7F}]/</code>, it
means
-the characters <code>\N{U+20}</code>, <code>\N{U+21}</code>, ...,
<code>\N{U+7F}</code>. This range
-is all the printable characters that the ASCII character set contains.
-</p>
-<p>Prior to v5.22, you couldn’t specify any ranges portably, except
-(starting in Perl v5.5.3) all subsets of the <code>[A-Z]</code> and
<code>[a-z]</code>
-ranges are specially coded to not pick up gap characters. For example,
-characters such as "ô" (<code>o WITH CIRCUMFLEX</code>) that lie
between
-"I" and "J" would not be matched by the regular expression
range
-<code>/[H-K]/</code>. But if either of the range end points is explicitly
numeric
-(and neither is specified by <code>\N{U+...}</code>), the gap characters are
-matched:
-</p>
-<pre class="verbatim"> /[\x89-\x91]/
-</pre>
-<p>will match <code>\x8e</code>, even though <code>\x89</code> is
"i" and <code>\x91 </code> is "j",
-and <code>\x8e</code> is a gap character, from the alphabetic viewpoint.
-</p>
-<p>Another construct to be wary of is the inappropriate use of hex (unless
-you use <code>\N{U+...}</code>) or
-octal constants in regular expressions. Consider the following
-set of subs:
-</p>
-<pre class="verbatim"> sub is_c0 {
- my $char = substr(shift,0,1);
- $char =~ /[\000-\037]/;
- }
-
- sub is_print_ascii {
- my $char = substr(shift,0,1);
- $char =~ /[\040-\176]/;
- }
-
- sub is_delete {
- my $char = substr(shift,0,1);
- $char eq "\177";
- }
-
- sub is_c1 {
- my $char = substr(shift,0,1);
- $char =~ /[\200-\237]/;
- }
-
- sub is_latin_1 { # But not ASCII; not C1
- my $char = substr(shift,0,1);
- $char =~ /[\240-\377]/;
- }
-</pre>
-<p>These are valid only on ASCII platforms. Starting in Perl v5.22, simply
-changing the octal constants to equivalent <code>\N{U+...}</code> values makes
-them portable:
-</p>
-<pre class="verbatim"> sub is_c0 {
- my $char = substr(shift,0,1);
- $char =~ /[\N{U+00}-\N{U+1F}]/;
- }
-
- sub is_print_ascii {
- my $char = substr(shift,0,1);
- $char =~ /[\N{U+20}-\N{U+7E}]/;
- }
-
- sub is_delete {
- my $char = substr(shift,0,1);
- $char eq "\N{U+7F}";
- }
-
- sub is_c1 {
- my $char = substr(shift,0,1);
- $char =~ /[\N{U+80}-\N{U+9F}]/;
- }
-
- sub is_latin_1 { # But not ASCII; not C1
- my $char = substr(shift,0,1);
- $char =~ /[\N{U+A0}-\N{U+FF}]/;
- }
-</pre>
-<p>And here are some alternative portable ways to write them:
-</p>
-<pre class="verbatim"> sub Is_c0 {
- my $char = substr(shift,0,1);
- return $char =~ /[[:cntrl:]]/a && ! Is_delete($char);
-
- # Alternatively:
- # return $char =~ /[[:cntrl:]]/
- # && $char =~ /[[:ascii:]]/
- # && ! Is_delete($char);
- }
-
- sub Is_print_ascii {
- my $char = substr(shift,0,1);
-
- return $char =~ /[[:print:]]/a;
-
- # Alternatively:
- # return $char =~ /[[:print:]]/ && $char =~ /[[:ascii:]]/;
-
- # Or
- # return $char
- # =~ /[
!"\#\$%&'()*+,\-.\/0-9:;<=>address@hidden|}~]/;
- }
-
- sub Is_delete {
- my $char = substr(shift,0,1);
- return utf8::native_to_unicode(ord $char) == 0x7F;
- }
-
- sub Is_c1 {
- use feature 'unicode_strings';
- my $char = substr(shift,0,1);
- return $char =~ /[[:cntrl:]]/ && $char !~ /[[:ascii:]]/;
- }
-
- sub Is_latin_1 { # But not ASCII; not C1
- use feature 'unicode_strings';
- my $char = substr(shift,0,1);
- return ord($char) < 256
- && $char !~ /[[:ascii:]]/
- && $char !~ /[[:cntrl:]]/;
- }
-</pre>
-<p>Another way to write <code>Is_latin_1()</code> would be
-to use the characters in the range explicitly:
-</p>
-<pre class="verbatim"> sub Is_latin_1 {
- my $char = substr(shift,0,1);
- $char =~ /[ÃÂ
áâãäÃ¥æçèéêëìÃÂîïðñòóôõö÷øùúûüýþÿÃÂÃÂÃÂÃÂÃÂÃÂ
ÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂ]
-
[ÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂ
áâãäÃ¥æçèéêëìÃÂîïðñòóôõö÷øùúûüýþÿ]/x;
- }
-</pre>
-<p>Although that form may run into trouble in network transit (due to the
-presence of 8 bit characters) or on non ISO-Latin character sets. But
-it does allow <code>Is_c1</code> to be rewritten so it works on Perls that
don’t
-have <code>'unicode_strings'</code> (earlier than v5.14):
-</p>
-<pre class="verbatim"> sub Is_latin_1 { # But not ASCII; not C1
- my $char = substr(shift,0,1);
- return ord($char) < 256
- && $char !~ /[[:ascii:]]/
- && ! Is_latin1($char);
- }
-</pre>
-<hr>
-<a name="perlebcdic-SOCKETS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-SORTING" accesskey="n" rel="next">perlebcdic
SORTING</a>, Previous: <a href="#perlebcdic-REGULAR-EXPRESSION-DIFFERENCES"
accesskey="p" rel="prev">perlebcdic REGULAR EXPRESSION DIFFERENCES</a>, Up: <a
href="#perlebcdic" accesskey="u" rel="up">perlebcdic</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SOCKETS"></a>
-<h3 class="section">19.10 SOCKETS</h3>
-
-<p>Most socket programming assumes ASCII character encodings in network
-byte order. Exceptions can include CGI script writing under a
-host web server where the server may take care of translation for you.
-Most host web servers convert EBCDIC data to ISO-8859-1 or Unicode on
-output.
-</p>
-<hr>
-<a name="perlebcdic-SORTING"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-TRANSFORMATION-FORMATS" accesskey="n"
rel="next">perlebcdic TRANSFORMATION FORMATS</a>, Previous: <a
href="#perlebcdic-SOCKETS" accesskey="p" rel="prev">perlebcdic SOCKETS</a>, Up:
<a href="#perlebcdic" accesskey="u" rel="up">perlebcdic</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SORTING"></a>
-<h3 class="section">19.11 SORTING</h3>
-
-<p>One big difference between ASCII-based character sets and EBCDIC ones
-are the relative positions of the characters when sorted in native
-order. Of most concern are the upper- and lowercase letters, the
-digits, and the underscore (<code>"_"</code>). On ASCII platforms
the native sort
-order has the digits come before the uppercase letters which come before
-the underscore which comes before the lowercase letters. On EBCDIC, the
-underscore comes first, then the lowercase letters, then the uppercase
-ones, and the digits last. If sorted on an ASCII-based platform, the
-two-letter abbreviation for a physician comes before the two letter
-abbreviation for drive; that is:
-</p>
-<pre class="verbatim"> @sorted = sort(qw(Dr. dr.)); # @sorted holds
('Dr.','dr.') on ASCII,
- # but ('dr.','Dr.') on EBCDIC
-</pre>
-<p>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 "ÃÂ" (<code>E WITH DIAERESIS</code>, 203)
comes
-before "ë" (<code>e WITH DIAERESIS</code>, 235) on an ASCII
platform, but
-the latter (83) comes before the former (115) on an EBCDIC platform.
-(Astute readers will note that the uppercase version of "ÃÂ"
-<code>SMALL LETTER SHARP S</code> is simply "SS" and that the upper
case versions
-of "ÿ" (small <code>y WITH DIAERESIS</code>) and "õ"
(<code>MICRO SIGN</code>)
-are not in the 0..255 range but are in Unicode, in a Unicode enabled
-Perl).
-</p>
-<p>The sort order will cause differences between results obtained on
-ASCII platforms versus EBCDIC platforms. What follows are some suggestions
-on how to deal with these differences.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Ignore-ASCII-vs_002e-EBCDIC-sort-differences_002e"
accesskey="1">perlebcdic Ignore ASCII vs. EBCDIC sort
differences.</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Use-a-sort-helper-function" accesskey="2">perlebcdic Use a
sort helper function</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-MONO-CASE-then-sort-data-_0028for-non_002ddigits_002c-non_002dunderscore_0029"
accesskey="3">perlebcdic MONO CASE then sort data (for non-digits,
non-underscore)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Perform-sorting-on-one-type-of-platform-only_002e"
accesskey="4">perlebcdic Perform sorting on one type of platform
only.</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlebcdic-Ignore-ASCII-vs_002e-EBCDIC-sort-differences_002e"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-Use-a-sort-helper-function" accesskey="n"
rel="next">perlebcdic Use a sort helper function</a>, Up: <a
href="#perlebcdic-SORTING" accesskey="u" rel="up">perlebcdic SORTING</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Ignore-ASCII-vs_002e-EBCDIC-sort-differences_002e"></a>
-<h4 class="subsection">19.11.1 Ignore ASCII vs. EBCDIC sort differences.</h4>
-
-<p>This is the least computationally expensive strategy. It may require
-some user education.
-</p>
-<hr>
-<a name="perlebcdic-Use-a-sort-helper-function"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlebcdic-MONO-CASE-then-sort-data-_0028for-non_002ddigits_002c-non_002dunderscore_0029"
accesskey="n" rel="next">perlebcdic MONO CASE then sort data (for non-digits,
non-underscore)</a>, Previous: <a
href="#perlebcdic-Ignore-ASCII-vs_002e-EBCDIC-sort-differences_002e"
accesskey="p" rel="prev">perlebcdic Ignore ASCII vs. EBCDIC sort
differences.</a>, Up: <a href="#perlebcdic-SORTING" accesskey="u"
rel="up">perlebcdic SORTING</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Use-a-sort-helper-function"></a>
-<h4 class="subsection">19.11.2 Use a sort helper function</h4>
-
-<p>This is completely general, but the most computationally expensive
-strategy. Choose one or the other character set and transform to that
-for every sort comparision. Here’s a complete example that transforms
-to ASCII sort order:
-</p>
-<pre class="verbatim"> sub native_to_uni($) {
- my $string = shift;
-
- # Saves time on an ASCII platform
- return $string if ord 'A' == 65;
-
- my $output = "";
- for my $i (0 .. length($string) - 1) {
- $output
- .= chr(utf8::native_to_unicode(ord(substr($string, $i, 1))));
- }
-
- # Preserve utf8ness of input onto the output, even if it didn't need
- # to be utf8
- utf8::upgrade($output) if utf8::is_utf8($string);
-
- return $output;
- }
-
- sub ascii_order { # Sort helper
- return native_to_uni($a) cmp native_to_uni($b);
- }
-
- sort ascii_order @list;
-</pre>
-<hr>
-<a
name="perlebcdic-MONO-CASE-then-sort-data-_0028for-non_002ddigits_002c-non_002dunderscore_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-Perform-sorting-on-one-type-of-platform-only_002e"
accesskey="n" rel="next">perlebcdic Perform sorting on one type of platform
only.</a>, Previous: <a href="#perlebcdic-Use-a-sort-helper-function"
accesskey="p" rel="prev">perlebcdic Use a sort helper function</a>, Up: <a
href="#perlebcdic-SORTING" accesskey="u" rel="up">perlebcdic SORTING</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a
name="MONO-CASE-then-sort-data-_0028for-non_002ddigits_002c-non_002dunderscore_0029"></a>
-<h4 class="subsection">19.11.3 MONO CASE then sort data (for non-digits,
non-underscore)</h4>
-
-<p>If you don’t care about where digits and underscore sort to, you can
do
-something like this
-</p>
-<pre class="verbatim"> sub case_insensitive_order { # Sort helper
- return lc($a) cmp lc($b)
- }
-
- sort case_insensitive_order @list;
-</pre>
-<p>If performance is an issue, and you don’t care if the output is in the
-same case as the input, Use <code>tr///</code> to transform to the case most
-employed within the data. If the data are primarily UPPERCASE
-non-Latin1, then apply <code>tr/[a-z]/[A-Z]/</code>, and then
<code>sort()</code>. If the
-data are primarily lowercase non Latin1 then apply <code>tr/[A-Z]/[a-z]/</code>
-before sorting. If the data are primarily UPPERCASE and include Latin-1
-characters then apply:
-</p>
-<pre class="verbatim"> tr/[a-z]/[A-Z]/;
- tr/[ÃÂ
áâãäÃ¥æçèéêëìÃÂîïðñòóôõöøùúûüýþ]/[ÃÂÃÂÃÂÃÂÃÂÃÂ
ÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂÃÂ/;
- s/ÃÂ/SS/g;
-</pre>
-<p>then <code>sort()</code>. If you have a choice, it’s better to
lowercase things
-to avoid the problems of the two Latin-1 characters whose uppercase is
-outside Latin-1: "ÿ" (small <code>y WITH DIAERESIS</code>) and
"õ"
-(<code>MICRO SIGN</code>). If you do need to upppercase, you can; with a
-Unicode-enabled Perl, do:
-</p>
-<pre class="verbatim"> tr/ÿ/\x{178}/;
- tr/õ/\x{39C}/;
-</pre>
-<hr>
-<a name="perlebcdic-Perform-sorting-on-one-type-of-platform-only_002e"></a>
-<div class="header">
-<p>
-Previous: <a
href="#perlebcdic-MONO-CASE-then-sort-data-_0028for-non_002ddigits_002c-non_002dunderscore_0029"
accesskey="p" rel="prev">perlebcdic MONO CASE then sort data (for non-digits,
non-underscore)</a>, Up: <a href="#perlebcdic-SORTING" accesskey="u"
rel="up">perlebcdic SORTING</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Perform-sorting-on-one-type-of-platform-only_002e"></a>
-<h4 class="subsection">19.11.4 Perform sorting on one type of platform
only.</h4>
-
-<p>This strategy can employ a network connection. As such
-it would be computationally expensive.
-</p>
-<hr>
-<a name="perlebcdic-TRANSFORMATION-FORMATS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-Hashing-order-and-checksums" accesskey="n"
rel="next">perlebcdic Hashing order and checksums</a>, Previous: <a
href="#perlebcdic-SORTING" accesskey="p" rel="prev">perlebcdic SORTING</a>, Up:
<a href="#perlebcdic" accesskey="u" rel="up">perlebcdic</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="TRANSFORMATION-FORMATS"></a>
-<h3 class="section">19.12 TRANSFORMATION FORMATS</h3>
-
-<p>There are a variety of ways of transforming data with an intra character set
-mapping that serve a variety of purposes. Sorting was discussed in the
-previous section and a few of the other more popular mapping techniques are
-discussed next.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-URL-decoding-and-encoding" accesskey="1">perlebcdic URL
decoding and encoding</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-uu-encoding-and-decoding" accesskey="2">perlebcdic uu
encoding and decoding</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Quoted_002dPrintable-encoding-and-decoding"
accesskey="3">perlebcdic Quoted-Printable encoding and
decoding</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-Caesarean-ciphers" accesskey="4">perlebcdic Caesarean
ciphers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlebcdic-URL-decoding-and-encoding"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-uu-encoding-and-decoding" accesskey="n"
rel="next">perlebcdic uu encoding and decoding</a>, Up: <a
href="#perlebcdic-TRANSFORMATION-FORMATS" accesskey="u" rel="up">perlebcdic
TRANSFORMATION FORMATS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="URL-decoding-and-encoding"></a>
-<h4 class="subsection">19.12.1 URL decoding and encoding</h4>
-
-<p>Note that some URLs have hexadecimal ASCII code points in them in an
-attempt to overcome character or protocol limitation issues. For example
-the tilde character is not on every keyboard hence a URL of the form:
-</p>
-<pre class="verbatim"> http://www.pvhp.com/~pvhp/
-</pre>
-<p>may also be expressed as either of:
-</p>
-<pre class="verbatim"> http://www.pvhp.com/%7Epvhp/
-
- http://www.pvhp.com/%7epvhp/
-</pre>
-<p>where 7E is the hexadecimal ASCII code point for "~". Here is an
example
-of decoding such a URL in any EBCDIC code page:
-</p>
-<pre class="verbatim"> $url = 'http://www.pvhp.com/%7Epvhp/';
- $url =~ s/%([0-9a-fA-F]{2})/
- pack("c",utf8::unicode_to_native(hex($1)))/xge;
-</pre>
-<p>Conversely, here is a partial solution for the task of encoding such
-a URL in any EBCDIC code page:
-</p>
-<pre class="verbatim"> $url = 'http://www.pvhp.com/~pvhp/';
- # The following regular expression does not address the
- # mappings for: ('.' => '%2E', '/' => '%2F', ':' => '%3A')
- $url =~ s/([\t "#%&\(\),;<=>address@hidden|}~])/
-
sprintf("%%%02X",utf8::native_to_unicode(ord($1)))/xge;
-</pre>
-<p>where a more complete solution would split the URL into components
-and apply a full s/// substitution only to the appropriate parts.
-</p>
-<hr>
-<a name="perlebcdic-uu-encoding-and-decoding"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-Quoted_002dPrintable-encoding-and-decoding"
accesskey="n" rel="next">perlebcdic Quoted-Printable encoding and decoding</a>,
Previous: <a href="#perlebcdic-URL-decoding-and-encoding" accesskey="p"
rel="prev">perlebcdic URL decoding and encoding</a>, Up: <a
href="#perlebcdic-TRANSFORMATION-FORMATS" accesskey="u" rel="up">perlebcdic
TRANSFORMATION FORMATS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="uu-encoding-and-decoding"></a>
-<h4 class="subsection">19.12.2 uu encoding and decoding</h4>
-
-<p>The <code>u</code> template to <code>pack()</code> or <code>unpack()</code>
will render EBCDIC data in
-EBCDIC characters equivalent to their ASCII counterparts. For example,
-the following will print "Yes indeed\n" on either an ASCII or EBCDIC
-computer:
-</p>
-<pre class="verbatim"> $all_byte_chrs = '';
- for (0..255) { $all_byte_chrs .= chr($_); }
- $uuencode_byte_chrs = pack('u', $all_byte_chrs);
- ($uu = <<'ENDOFHEREDOC') =~ s/^\s*//gm;
-
M``$"`P0%!@<("0H+#`T.#Q`1$A,4%187&!D:&QP='A\@(2(C)"4F)address@hidden
- M+2XO,#$R,S0U-C<X.3H[/#T^/T!!0D-$149'2$E*2TQ-3D]045)35%565UA9
-
M6EM<75Y?8&%B8V1E9F=H:6IK;&UN;W!Q<G-T=79W>'EZ>address@hidden(6&
-
MAXB)BHN,C8Z/D)&2DY25EI>8F9J;G)V>GZ"AHJ.DI::GJ*FJJZRMKJ^PL;*S
- MM+6VM[BYNKN\O;Z_P,'"P\3%QL?(R<K+S,W.S]#1TM/4U=;7V-G:V]S=WM_@
- ?X>+CY.7FY^CIZNOL[>[O\/'R\_3U]O?X^?K[_/W^_P``
- ENDOFHEREDOC
- if ($uuencode_byte_chrs eq $uu) {
- print "Yes ";
- }
- $uudecode_byte_chrs = unpack('u', $uuencode_byte_chrs);
- if ($uudecode_byte_chrs eq $all_byte_chrs) {
- print "indeed\n";
- }
-</pre>
-<p>Here is a very spartan uudecoder that will work on EBCDIC:
-</p>
-<pre class="verbatim"> #!/usr/local/bin/perl
- $_ = <> until ($mode,$file) = /^begin\s*(\d*)\s*(\S*)/;
- open(OUT, "> $file") if $file ne "";
- while(<>) {
- last if /^end/;
- next if /[a-z]/;
- next unless int((((utf8::native_to_unicode(ord()) - 32 ) & 077)
- + 2) / 3)
- == int(length() / 4);
- print OUT unpack("u", $_);
- }
- close(OUT);
- chmod oct($mode), $file;
-</pre>
-<hr>
-<a name="perlebcdic-Quoted_002dPrintable-encoding-and-decoding"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-Caesarean-ciphers" accesskey="n"
rel="next">perlebcdic Caesarean ciphers</a>, Previous: <a
href="#perlebcdic-uu-encoding-and-decoding" accesskey="p" rel="prev">perlebcdic
uu encoding and decoding</a>, Up: <a href="#perlebcdic-TRANSFORMATION-FORMATS"
accesskey="u" rel="up">perlebcdic TRANSFORMATION FORMATS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Quoted_002dPrintable-encoding-and-decoding"></a>
-<h4 class="subsection">19.12.3 Quoted-Printable encoding and decoding</h4>
-
-<p>On ASCII-encoded platforms it is possible to strip characters outside of
-the printable set using:
-</p>
-<pre class="verbatim"> # This QP encoder works on ASCII only
- $qp_string =~ s/([=\x00-\x1F\x80-\xFF])/
- sprintf("=%02X",ord($1))/xge;
-</pre>
-<p>Starting in Perl v5.22, this is trivially changeable to work portably on
-both ASCII and EBCDIC platforms.
-</p>
-<pre class="verbatim"> # This QP encoder works on both ASCII and EBCDIC
- $qp_string =~ s/([=\N{U+00}-\N{U+1F}\N{U+80}-\N{U+FF}])/
- sprintf("=%02X",ord($1))/xge;
-</pre>
-<p>For earlier Perls, a QP encoder that works on both ASCII and EBCDIC
-platforms would look somewhat like the following:
-</p>
-<pre class="verbatim"> $delete =
utf8::unicode_to_native(ord("\x7F"));
- $qp_string =~
- s/([^[:print:]$delete])/
- sprintf("=%02X",utf8::native_to_unicode(ord($1)))/xage;
-</pre>
-<p>(although in production code the substitutions might be done
-in the EBCDIC branch with the function call and separately in the
-ASCII branch without the expense of the identity map; in Perl v5.22, the
-identity map is optimized out so there is no expense, but the
-alternative above is simpler and is also available in v5.22).
-</p>
-<p>Such QP strings can be decoded with:
-</p>
-<pre class="verbatim"> # This QP decoder is limited to ASCII only
- $string =~ s/=([[:xdigit:][[:xdigit:])/chr hex $1/ge;
- $string =~ s/=[\n\r]+$//;
-</pre>
-<p>Whereas a QP decoder that works on both ASCII and EBCDIC platforms
-would look somewhat like the following:
-</p>
-<pre class="verbatim"> $string =~ s/=([[:xdigit:][:xdigit:]])/
- chr utf8::native_to_unicode(hex $1)/xge;
- $string =~ s/=[\n\r]+$//;
-</pre>
-<hr>
-<a name="perlebcdic-Caesarean-ciphers"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlebcdic-Quoted_002dPrintable-encoding-and-decoding"
accesskey="p" rel="prev">perlebcdic Quoted-Printable encoding and decoding</a>,
Up: <a href="#perlebcdic-TRANSFORMATION-FORMATS" accesskey="u"
rel="up">perlebcdic TRANSFORMATION FORMATS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Caesarean-ciphers"></a>
-<h4 class="subsection">19.12.4 Caesarean ciphers</h4>
-
-<p>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 <strong>Gallic Wars</strong> text. A single alphabet shift is
sometimes
-referred to as a rotation and the shift amount is given as a number $n after
-the string ’rot’ or "rot$n". Rot0 and rot26 would
designate identity maps
-on the 26-letter English version of the Latin alphabet. Rot13 has the
-interesting property that alternate subsequent invocations are identity maps
-(thus rot13 is its own non-trivial inverse in the group of 26 alphabet
-rotations). Hence the following is a rot13 encoder and decoder that will
-work on ASCII and EBCDIC platforms:
-</p>
-<pre class="verbatim"> #!/usr/local/bin/perl
-
- while(<>){
- tr/n-za-mN-ZA-M/a-zA-Z/;
- print;
- }
-</pre>
-<p>In one-liner form:
-</p>
-<pre class="verbatim"> perl -ne 'tr/n-za-mN-ZA-M/a-zA-Z/;print'
-</pre>
-<hr>
-<a name="perlebcdic-Hashing-order-and-checksums"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-I18N-AND-L10N" accesskey="n" rel="next">perlebcdic
I18N AND L10N</a>, Previous: <a href="#perlebcdic-TRANSFORMATION-FORMATS"
accesskey="p" rel="prev">perlebcdic TRANSFORMATION FORMATS</a>, Up: <a
href="#perlebcdic" accesskey="u" rel="up">perlebcdic</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Hashing-order-and-checksums"></a>
-<h3 class="section">19.13 Hashing order and checksums</h3>
-
-<p>Perl deliberately randomizes hash order for security purposes on both
-ASCII and EBCDIC platforms.
-</p>
-<p>EBCDIC checksums will differ for the same file translated into ASCII
-and vice versa.
-</p>
-<hr>
-<a name="perlebcdic-I18N-AND-L10N"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-MULTI_002dOCTET-CHARACTER-SETS" accesskey="n"
rel="next">perlebcdic MULTI-OCTET CHARACTER SETS</a>, Previous: <a
href="#perlebcdic-Hashing-order-and-checksums" accesskey="p"
rel="prev">perlebcdic Hashing order and checksums</a>, Up: <a
href="#perlebcdic" accesskey="u" rel="up">perlebcdic</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="I18N-AND-L10N"></a>
-<h3 class="section">19.14 I18N AND L10N</h3>
-
-<p>Internationalization (I18N) and localization (L10N) are supported at least
-in principle even on EBCDIC platforms. The details are system-dependent
-and discussed under the <a href="#perlebcdic-OS-ISSUES">OS ISSUES</a> section
below.
-</p>
-<hr>
-<a name="perlebcdic-MULTI_002dOCTET-CHARACTER-SETS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-OS-ISSUES" accesskey="n" rel="next">perlebcdic OS
ISSUES</a>, Previous: <a href="#perlebcdic-I18N-AND-L10N" accesskey="p"
rel="prev">perlebcdic I18N AND L10N</a>, Up: <a href="#perlebcdic"
accesskey="u" rel="up">perlebcdic</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="MULTI_002dOCTET-CHARACTER-SETS"></a>
-<h3 class="section">19.15 MULTI-OCTET CHARACTER SETS</h3>
-
-<p>Perl works with UTF-EBCDIC, a multi-byte encoding. In Perls earlier
-than v5.22, there may be various bugs in this regard.
-</p>
-<p>Legacy multi byte EBCDIC code pages XXX.
-</p>
-<hr>
-<a name="perlebcdic-OS-ISSUES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-BUGS" accesskey="n" rel="next">perlebcdic BUGS</a>,
Previous: <a href="#perlebcdic-MULTI_002dOCTET-CHARACTER-SETS" accesskey="p"
rel="prev">perlebcdic MULTI-OCTET CHARACTER SETS</a>, Up: <a href="#perlebcdic"
accesskey="u" rel="up">perlebcdic</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="OS-ISSUES"></a>
-<h3 class="section">19.16 OS ISSUES</h3>
-
-<p>There may be a few system-dependent issues
-of concern to EBCDIC Perl programmers.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlebcdic-OS_002f400"
accesskey="1">perlebcdic OS/400</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-OS_002f390_002c-z_002fOS" accesskey="2">perlebcdic OS/390,
z/OS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlebcdic-POSIX_002dBC_003f" accesskey="3">perlebcdic
POSIX-BC?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlebcdic-OS_002f400"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-OS_002f390_002c-z_002fOS" accesskey="n"
rel="next">perlebcdic OS/390, z/OS</a>, Up: <a href="#perlebcdic-OS-ISSUES"
accesskey="u" rel="up">perlebcdic OS ISSUES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="OS_002f400"></a>
-<h4 class="subsection">19.16.1 OS/400</h4>
-
-<dl compact="compact">
-<dt>PASE</dt>
-<dd><a name="perlebcdic-PASE"></a>
-<p>The PASE environment is a runtime environment for OS/400 that can run
-executables built for PowerPC AIX in OS/400; see <a
href="perlos400.html#Top">(perlos400)</a>. PASE
-is ASCII-based, not EBCDIC-based as the ILE.
-</p>
-</dd>
-<dt>IFS access</dt>
-<dd><a name="perlebcdic-IFS-access"></a>
-<p>XXX.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlebcdic-OS_002f390_002c-z_002fOS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-POSIX_002dBC_003f" accesskey="n"
rel="next">perlebcdic POSIX-BC?</a>, Previous: <a href="#perlebcdic-OS_002f400"
accesskey="p" rel="prev">perlebcdic OS/400</a>, Up: <a
href="#perlebcdic-OS-ISSUES" accesskey="u" rel="up">perlebcdic OS ISSUES</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="OS_002f390_002c-z_002fOS"></a>
-<h4 class="subsection">19.16.2 OS/390, z/OS</h4>
-
-<p>Perl runs under Unix Systems Services or USS.
-</p>
-<dl compact="compact">
-<dt><code>sigaction</code></dt>
-<dd><a name="perlebcdic-sigaction"></a>
-<p><code>SA_SIGINFO</code> can have segmentation faults.
-</p>
-</dd>
-<dt><code>chcp</code></dt>
-<dd><a name="perlebcdic-chcp"></a>
-<p><strong>chcp</strong> is supported as a shell utility for displaying and
changing
-one’s code page. See also <a
href="http://man.he.net/man1/chcp";>chcp(1)</a>.
-</p>
-</dd>
-<dt>dataset access</dt>
-<dd><a name="perlebcdic-dataset-access"></a>
-<p>For sequential data set access try:
-</p>
-<pre class="verbatim"> my @ds_records = `cat //DSNAME`;
-</pre>
-<p>or:
-</p>
-<pre class="verbatim"> my @ds_records = `cat //'HLQ.DSNAME'`;
-</pre>
-<p>See also the OS390::Stdio module on CPAN.
-</p>
-</dd>
-<dt><code>iconv</code></dt>
-<dd><a name="perlebcdic-iconv-1"></a>
-<p><strong>iconv</strong> is supported as both a shell utility and a C RTL
routine.
-See also the <a href="http://man.he.net/man1/iconv";>iconv(1)</a> and <a
href="http://man.he.net/man3/iconv";>iconv(3)</a> manual pages.
-</p>
-</dd>
-<dt>locales</dt>
-<dd><a name="perlebcdic-locales"></a>
-<p>Locales are supported. There may be glitches when a locale is another
-EBCDIC code page which has some of the
-<a href="#perlebcdic-The-13-variant-characters">code-page variant
characters</a> in other
-positions.
-</p>
-<p>There aren’t currently any real UTF-8 locales, even though some locale
-names contain the string "UTF-8".
-</p>
-<p>See <a href="#perllocale-NAME">perllocale NAME</a> for information on
locales. The L10N files
-are in <samp>/usr/nls/locale</samp>. <code>$Config{d_setlocale}</code> is
<code>'define'</code> on
-OS/390 or z/OS.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlebcdic-POSIX_002dBC_003f"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlebcdic-OS_002f390_002c-z_002fOS" accesskey="p"
rel="prev">perlebcdic OS/390, z/OS</a>, Up: <a href="#perlebcdic-OS-ISSUES"
accesskey="u" rel="up">perlebcdic OS ISSUES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="POSIX_002dBC_003f"></a>
-<h4 class="subsection">19.16.3 POSIX-BC?</h4>
-
-<p>XXX.
-</p>
-<hr>
-<a name="perlebcdic-BUGS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-SEE-ALSO" accesskey="n" rel="next">perlebcdic SEE
ALSO</a>, Previous: <a href="#perlebcdic-OS-ISSUES" accesskey="p"
rel="prev">perlebcdic OS ISSUES</a>, Up: <a href="#perlebcdic" accesskey="u"
rel="up">perlebcdic</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="BUGS-2"></a>
-<h3 class="section">19.17 BUGS</h3>
-
-<ul>
-<li> The <code>cmp</code> (and hence <code>sort</code>) operators do not
necessarily give the
-correct results when both operands are UTF-EBCDIC encoded strings and
-there is a mixture of ASCII and/or control characters, along with other
-characters.
-
-</li><li> Ranges containing <code>\N{...}</code> in the <code>tr///</code>
(and <code>y///</code>)
-transliteration operators are treated differently than the equivalent
-ranges in regular expression patterns. They should, but don’t, cause
-the values in the ranges to all be treated as Unicode code points, and
-not native ones. (<a href="#perlre-Version-8-Regular-Expressions">perlre
Version 8 Regular Expressions</a> gives
-details as to how it should work.)
-
-</li><li> Not all shells will allow multiple <code>-e</code> string arguments
to perl to
-be concatenated together properly as recipes in this document
-0, 2, 4, 5, and 6 might
-seem to imply.
-
-</li><li> There are some bugs in the <code>pack</code>/<code>unpack</code>
<code>"U0"</code> template
-
-</li><li> There are a significant number of test failures in the CPAN modules
-shipped with Perl v5.22. These are only in modules not primarily
-maintained by Perl 5 porters. Some of these are failures in the tests
-only: they don’t realize that it is proper to get different results on
-EBCDIC platforms. And some of the failures are real bugs. If you
-compile and do a <code>make test</code> on Perl, all tests on the
<code>/cpan</code>
-directory are skipped.
-
-<p>In particular, the extensions <a
href="Unicode-Collate.html#Top">(Unicode-Collate)</a> and
-<a href="Unicode-Normalize.html#Top">(Unicode-Normalize)</a> are not supported
under EBCDIC; likewise for the
-(now deprecated) <a href="encoding.html#Top">(encoding)</a> pragma.
-</p>
-<p><a href="Encode.html#Top">(Encode)</a> partially works.
-</p>
-</li><li> In earlier versions, when byte and character data were concatenated,
-the new string was sometimes created by
-decoding the byte strings as <em>ISO 8859-1 (Latin-1)</em>, even if the
-old Unicode string used EBCDIC.
-
-</li></ul>
-
-<hr>
-<a name="perlebcdic-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-REFERENCES" accesskey="n" rel="next">perlebcdic
REFERENCES</a>, Previous: <a href="#perlebcdic-BUGS" accesskey="p"
rel="prev">perlebcdic BUGS</a>, Up: <a href="#perlebcdic" accesskey="u"
rel="up">perlebcdic</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-12"></a>
-<h3 class="section">19.18 SEE ALSO</h3>
-
-<p><a href="#perllocale-NAME">perllocale NAME</a>, <a
href="#perlfunc-NAME">perlfunc NAME</a>, <a
href="#perlunicode-NAME">perlunicode NAME</a>, <a
href="utf8.html#Top">(utf8)</a>.
-</p>
-<hr>
-<a name="perlebcdic-REFERENCES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-HISTORY" accesskey="n" rel="next">perlebcdic
HISTORY</a>, Previous: <a href="#perlebcdic-SEE-ALSO" accesskey="p"
rel="prev">perlebcdic SEE ALSO</a>, Up: <a href="#perlebcdic" accesskey="u"
rel="up">perlebcdic</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="REFERENCES-2"></a>
-<h3 class="section">19.19 REFERENCES</h3>
-
-<p><a
href="http://anubis.dkuug.dk/i18n/charmaps";>http://anubis.dkuug.dk/i18n/charmaps</a>
-</p>
-<p><a href="http://www.unicode.org/";>http://www.unicode.org/</a>
-</p>
-<p><a
href="http://www.unicode.org/unicode/reports/tr16/";>http://www.unicode.org/unicode/reports/tr16/</a>
-</p>
-<p><a
href="http://www.wps.com/projects/codes/";>http://www.wps.com/projects/codes/</a>
-<strong>ASCII: American Standard Code for Information Infiltration</strong>
Tom Jennings,
-September 1999.
-</p>
-<p><strong>The Unicode Standard, Version 3.0</strong> The Unicode Consortium,
Lisa Moore ed.,
-ISBN 0-201-61633-5, Addison Wesley Developers Press, February 2000.
-</p>
-<p><strong>CDRA: IBM - Character Data Representation Architecture -
-Reference and Registry</strong>, IBM SC09-2190-00, December 1996.
-</p>
-<p>"Demystifying Character Sets", Andrea Vine, Multilingual Computing
-& Technology, <strong>#26 Vol. 10 Issue 4</strong>, August/September 1999;
-ISSN 1523-0309; Multilingual Computing Inc. Sandpoint ID, USA.
-</p>
-<p><strong>Codes, Ciphers, and Other Cryptic and Clandestine
Communication</strong>
-Fred B. Wrixon, ISBN 1-57912-040-7, Black Dog & Leventhal Publishers,
-1998.
-</p>
-<p><a
href="http://www.bobbemer.com/P-BIT.HTM";>http://www.bobbemer.com/P-BIT.HTM</a>
-<strong>IBM - EBCDIC and the P-bit; The biggest Computer Goof Ever</strong>
Robert Bemer.
-</p>
-<hr>
-<a name="perlebcdic-HISTORY"></a>
-<div class="header">
-<p>
-Next: <a href="#perlebcdic-AUTHOR" accesskey="n" rel="next">perlebcdic
AUTHOR</a>, Previous: <a href="#perlebcdic-REFERENCES" accesskey="p"
rel="prev">perlebcdic REFERENCES</a>, Up: <a href="#perlebcdic" accesskey="u"
rel="up">perlebcdic</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="HISTORY-1"></a>
-<h3 class="section">19.20 HISTORY</h3>
-
-<p>15 April 2001: added UTF-8 and UTF-EBCDIC to main table, pvhp.
-</p>
-<hr>
-<a name="perlebcdic-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlebcdic-HISTORY" accesskey="p" rel="prev">perlebcdic
HISTORY</a>, Up: <a href="#perlebcdic" accesskey="u" rel="up">perlebcdic</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-7"></a>
-<h3 class="section">19.21 AUTHOR</h3>
-
-<p>Peter Prymmer address@hidden wrote this in 1999 and 2000
-with CCSID 0819 and 0037 help from Chris Leach and
-André Pirard address@hidden as well as POSIX-BC
-help from Thomas Dorner address@hidden
-Thanks also to Vickie Cooper, Philip Newton, William Raffloer, and
-Joe Smith. Trademarks, registered trademarks, service marks and
-registered service marks used in this document are the property of
-their respective owners.
-</p>
-<p>Now maintained by Perl5 Porters.
-</p>
-<hr>
-<a name="perlembed"></a>
-<div class="header">
-<p>
-Next: <a href="#perlexperiment" accesskey="n" rel="next">perlexperiment</a>,
Previous: <a href="#perlebcdic" accesskey="p" rel="prev">perlebcdic</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlembed-1"></a>
-<h2 class="chapter">20 perlembed</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlembed-NAME"
accesskey="1">perlembed NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlembed-DESCRIPTION"
accesskey="2">perlembed DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlembed-Hiding-Perl_005f"
accesskey="3">perlembed Hiding Perl_</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlembed-MORAL"
accesskey="4">perlembed MORAL</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlembed-AUTHOR"
accesskey="5">perlembed AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlembed-COPYRIGHT"
accesskey="6">perlembed COPYRIGHT</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlembed-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-DESCRIPTION" accesskey="n" rel="next">perlembed
DESCRIPTION</a>, Up: <a href="#perlembed" accesskey="u" rel="up">perlembed</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-19"></a>
-<h3 class="section">20.1 NAME</h3>
-
-<p>perlembed - how to embed perl in your C program
-</p>
-<hr>
-<a name="perlembed-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-Hiding-Perl_005f" accesskey="n" rel="next">perlembed
Hiding Perl_</a>, Previous: <a href="#perlembed-NAME" accesskey="p"
rel="prev">perlembed NAME</a>, Up: <a href="#perlembed" accesskey="u"
rel="up">perlembed</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-19"></a>
-<h3 class="section">20.2 DESCRIPTION</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlembed-PREAMBLE"
accesskey="1">perlembed PREAMBLE</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlembed-ROADMAP"
accesskey="2">perlembed ROADMAP</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Compiling-your-C-program" accesskey="3">perlembed Compiling
your C program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Adding-a-Perl-interpreter-to-your-C-program"
accesskey="4">perlembed Adding a Perl interpreter to your C
program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Calling-a-Perl-subroutine-from-your-C-program"
accesskey="5">perlembed Calling a Perl subroutine from your C
program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Evaluating-a-Perl-statement-from-your-C-program"
accesskey="6">perlembed Evaluating a Perl statement from your C
program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Performing-Perl-pattern-matches-and-substitutions-from-your-C-program"
accesskey="7">perlembed Performing Perl pattern matches and substitutions from
your C program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Fiddling-with-the-Perl-stack-from-your-C-program"
accesskey="8">perlembed Fiddling with the Perl stack from your C
program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Maintaining-a-persistent-interpreter" accesskey="9">perlembed
Maintaining a persistent interpreter</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Execution-of-END-blocks">perlembed Execution of END
blocks</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-_00240-assignments">perlembed $0
assignments</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Maintaining-multiple-interpreter-instances">perlembed
Maintaining multiple interpreter instances</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Using-Perl-modules_002c-which-themselves-use-C-libraries_002c-from-your-C-program">perlembed
Using Perl modules, which themselves use C libraries, from your C
program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlembed-Using-embedded-Perl-with-POSIX-locales">perlembed Using
embedded Perl with POSIX locales</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlembed-PREAMBLE"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-ROADMAP" accesskey="n" rel="next">perlembed
ROADMAP</a>, Up: <a href="#perlembed-DESCRIPTION" accesskey="u"
rel="up">perlembed DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PREAMBLE"></a>
-<h4 class="subsection">20.2.1 PREAMBLE</h4>
-
-<p>Do you want to:
-</p>
-<dl compact="compact">
-<dt><strong>Use C from Perl?</strong></dt>
-<dd><a name="perlembed-Use-C-from-Perl_003f"></a>
-<p>Read <a href="perlxstut.html#Top">(perlxstut)</a>, <a
href="perlxs.html#Top">(perlxs)</a>, <a href="h2xs.html#Top">(h2xs)</a>, <a
href="#perlguts-NAME">perlguts NAME</a>, and <a
href="perlapi.html#Top">(perlapi)</a>.
-</p>
-</dd>
-<dt><strong>Use a Unix program from Perl?</strong></dt>
-<dd><a name="perlembed-Use-a-Unix-program-from-Perl_003f"></a>
-<p>Read about back-quotes and about <code>system</code> and <code>exec</code>
in <a href="#perlfunc-NAME">perlfunc NAME</a>.
-</p>
-</dd>
-<dt><strong>Use Perl from Perl?</strong></dt>
-<dd><a name="perlembed-Use-Perl-from-Perl_003f"></a>
-<p>Read about ‘perlfunc do’ and <a href="#perlfunc-eval">perlfunc
eval</a> and <a href="#perlfunc-require">perlfunc require</a>
-and ‘perlfunc use’.
-</p>
-</dd>
-<dt><strong>Use C from C?</strong></dt>
-<dd><a name="perlembed-Use-C-from-C_003f"></a>
-<p>Rethink your design.
-</p>
-</dd>
-<dt><strong>Use Perl from C?</strong></dt>
-<dd><a name="perlembed-Use-Perl-from-C_003f"></a>
-<p>Read on...
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlembed-ROADMAP"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-Compiling-your-C-program" accesskey="n"
rel="next">perlembed Compiling your C program</a>, Previous: <a
href="#perlembed-PREAMBLE" accesskey="p" rel="prev">perlembed PREAMBLE</a>, Up:
<a href="#perlembed-DESCRIPTION" accesskey="u" rel="up">perlembed
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="ROADMAP"></a>
-<h4 class="subsection">20.2.2 ROADMAP</h4>
-
-<ul>
-<li> Compiling your C program
-
-</li><li> Adding a Perl interpreter to your C program
-
-</li><li> Calling a Perl subroutine from your C program
-
-</li><li> Evaluating a Perl statement from your C program
-
-</li><li> Performing Perl pattern matches and substitutions from your C program
-
-</li><li> Fiddling with the Perl stack from your C program
-
-</li><li> Maintaining a persistent interpreter
-
-</li><li> Maintaining multiple interpreter instances
-
-</li><li> Using Perl modules, which themselves use C libraries, from your C
program
-
-</li><li> Embedding Perl under Win32
-
-</li></ul>
-
-<hr>
-<a name="perlembed-Compiling-your-C-program"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-Adding-a-Perl-interpreter-to-your-C-program"
accesskey="n" rel="next">perlembed Adding a Perl interpreter to your C
program</a>, Previous: <a href="#perlembed-ROADMAP" accesskey="p"
rel="prev">perlembed ROADMAP</a>, Up: <a href="#perlembed-DESCRIPTION"
accesskey="u" rel="up">perlembed DESCRIPTION</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Compiling-your-C-program"></a>
-<h4 class="subsection">20.2.3 Compiling your C program</h4>
-
-<p>If you have trouble compiling the scripts in this documentation,
-you’re not alone. The cardinal rule: COMPILE THE PROGRAMS IN EXACTLY
-THE SAME WAY THAT YOUR PERL WAS COMPILED. (Sorry for yelling.)
-</p>
-<p>Also, every C program that uses Perl must link in the <em>perl library</em>.
-What’s that, you ask? Perl is itself written in C; the perl library
-is the collection of compiled C programs that were used to create your
-perl executable (<em>/usr/bin/perl</em> or equivalent). (Corollary: you
-can’t use Perl from your C program unless Perl has been compiled on
-your machine, or installed properly–that’s why you shouldn’t
blithely
-copy Perl executables from machine to machine without also copying the
-<em>lib</em> directory.)
-</p>
-<p>When you use Perl from C, your C program will–usually–allocate,
-"run", and deallocate a <em>PerlInterpreter</em> object, which is
defined by
-the perl library.
-</p>
-<p>If your copy of Perl is recent enough to contain this documentation
-(version 5.002 or later), then the perl library (and <em>EXTERN.h</em> and
-<em>perl.h</em>, which you’ll also need) will reside in a directory
-that looks like this:
-</p>
-<pre class="verbatim"> /usr/local/lib/perl5/your_architecture_here/CORE
-</pre>
-<p>or perhaps just
-</p>
-<pre class="verbatim"> /usr/local/lib/perl5/CORE
-</pre>
-<p>or maybe something like
-</p>
-<pre class="verbatim"> /usr/opt/perl5/CORE
-</pre>
-<p>Execute this statement for a hint about where to find CORE:
-</p>
-<pre class="verbatim"> perl -MConfig -e 'print $Config{archlib}'
-</pre>
-<p>Here’s how you’d compile the example in the next section,
-<a href="#perlembed-Adding-a-Perl-interpreter-to-your-C-program">Adding a Perl
interpreter to your C program</a>, on my Linux box:
-</p>
-<pre class="verbatim"> % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include
- -I/usr/local/lib/perl5/i586-linux/5.003/CORE
- -L/usr/local/lib/perl5/i586-linux/5.003/CORE
- -o interp interp.c -lperl -lm
-</pre>
-<p>(That’s all one line.) On my DEC Alpha running old 5.003_05, the
-incantation is a bit different:
-</p>
-<pre class="verbatim"> % cc -O2 -Olimit 2900 -DSTANDARD_C
-I/usr/local/include
- -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE
- -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib
- -D__LANGUAGE_C__ -D_NO_PROTO -o interp interp.c -lperl -lm
-</pre>
-<p>How can you figure out what to add? Assuming your Perl is post-5.001,
-execute a <code>perl -V</code> command and pay special attention to the
"cc" and
-"ccflags" information.
-</p>
-<p>You’ll have to choose the appropriate compiler (<em>cc</em>,
<em>gcc</em>, et al.) for
-your machine: <code>perl -MConfig -e 'print $Config{cc}'</code> will tell you
what
-to use.
-</p>
-<p>You’ll also have to choose the appropriate library directory
-(<em>/usr/local/lib/...</em>) for your machine. If your compiler complains
-that certain functions are undefined, or that it can’t locate
-<em>-lperl</em>, then you need to change the path following the
<code>-L</code>. If it
-complains that it can’t find <em>EXTERN.h</em> and <em>perl.h</em>, you
need to
-change the path following the <code>-I</code>.
-</p>
-<p>You may have to add extra libraries as well. Which ones?
-Perhaps those printed by
-</p>
-<pre class="verbatim"> perl -MConfig -e 'print $Config{libs}'
-</pre>
-<p>Provided your perl binary was properly configured and installed the
-<strong>ExtUtils::Embed</strong> module will determine all of this information
for
-you:
-</p>
-<pre class="verbatim"> % cc -o interp interp.c `perl -MExtUtils::Embed -e
ccopts -e ldopts`
-</pre>
-<p>If the <strong>ExtUtils::Embed</strong> module isn’t part of your
Perl distribution,
-you can retrieve it from
-http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils/
-(If this documentation came from your Perl distribution, then you’re
-running 5.004 or better and you already have it.)
-</p>
-<p>The <strong>ExtUtils::Embed</strong> kit on CPAN also contains all source
code for
-the examples in this document, tests, additional examples and other
-information you may find useful.
-</p>
-<hr>
-<a name="perlembed-Adding-a-Perl-interpreter-to-your-C-program"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-Calling-a-Perl-subroutine-from-your-C-program"
accesskey="n" rel="next">perlembed Calling a Perl subroutine from your C
program</a>, Previous: <a href="#perlembed-Compiling-your-C-program"
accesskey="p" rel="prev">perlembed Compiling your C program</a>, Up: <a
href="#perlembed-DESCRIPTION" accesskey="u" rel="up">perlembed DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Adding-a-Perl-interpreter-to-your-C-program"></a>
-<h4 class="subsection">20.2.4 Adding a Perl interpreter to your C program</h4>
-
-<p>In a sense, perl (the C program) is a good example of embedding Perl
-(the language), so I’ll demonstrate embedding with
<em>miniperlmain.c</em>,
-included in the source distribution. Here’s a bastardized, non-portable
-version of <em>miniperlmain.c</em> containing the essentials of embedding:
-</p>
-<pre class="verbatim"> #include <EXTERN.h> /* from the
Perl distribution */
- #include <perl.h> /* from the Perl distribution */
-
- static PerlInterpreter *my_perl; /*** The Perl interpreter ***/
-
- int main(int argc, char **argv, char **env)
- {
- PERL_SYS_INIT3(&argc,&argv,&env);
- my_perl = perl_alloc();
- perl_construct(my_perl);
- PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
- perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
- perl_run(my_perl);
- perl_destruct(my_perl);
- perl_free(my_perl);
- PERL_SYS_TERM();
- }
-</pre>
-<p>Notice that we don’t use the <code>env</code> pointer. Normally
handed to
-<code>perl_parse</code> as its final argument, <code>env</code> here is
replaced by
-<code>NULL</code>, which means that the current environment will be used.
-</p>
-<p>The macros PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific
-tune up of the C runtime environment necessary to run Perl interpreters;
-they should only be called once regardless of how many interpreters you
-create or destroy. Call PERL_SYS_INIT3() before you create your first
-interpreter, and PERL_SYS_TERM() after you free your last interpreter.
-</p>
-<p>Since PERL_SYS_INIT3() may change <code>env</code>, it may be more
appropriate to
-provide <code>env</code> as an argument to perl_parse().
-</p>
-<p>Also notice that no matter what arguments you pass to perl_parse(),
-PERL_SYS_INIT3() must be invoked on the C main() argc, argv and env and
-only once.
-</p>
-<p>Now compile this program (I’ll call it <em>interp.c</em>) into an
executable:
-</p>
-<pre class="verbatim"> % cc -o interp interp.c `perl -MExtUtils::Embed -e
ccopts -e ldopts`
-</pre>
-<p>After a successful compilation, you’ll be able to use <em>interp</em>
just
-like perl itself:
-</p>
-<pre class="verbatim"> % interp
- print "Pretty Good Perl \n";
- print "10890 - 9801 is ", 10890 - 9801;
- <CTRL-D>
- Pretty Good Perl
- 10890 - 9801 is 1089
-</pre>
-<p>or
-</p>
-<pre class="verbatim"> % interp -e 'printf("%x", 3735928559)'
- deadbeef
-</pre>
-<p>You can also read and execute Perl statements from a file while in the
-midst of your C program, by placing the filename in <em>argv[1]</em> before
-calling <em>perl_run</em>.
-</p>
-<hr>
-<a name="perlembed-Calling-a-Perl-subroutine-from-your-C-program"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-Evaluating-a-Perl-statement-from-your-C-program"
accesskey="n" rel="next">perlembed Evaluating a Perl statement from your C
program</a>, Previous: <a
href="#perlembed-Adding-a-Perl-interpreter-to-your-C-program" accesskey="p"
rel="prev">perlembed Adding a Perl interpreter to your C program</a>, Up: <a
href="#perlembed-DESCRIPTION" accesskey="u" rel="up">perlembed DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Calling-a-Perl-subroutine-from-your-C-program"></a>
-<h4 class="subsection">20.2.5 Calling a Perl subroutine from your C
program</h4>
-
-<p>To call individual Perl subroutines, you can use any of the
<strong>call_*</strong>
-functions documented in <a href="#perlcall-NAME">perlcall NAME</a>.
-In this example we’ll use <code>call_argv</code>.
-</p>
-<p>That’s shown below, in a program I’ll call <em>showtime.c</em>.
-</p>
-<pre class="verbatim"> #include <EXTERN.h>
- #include <perl.h>
-
- static PerlInterpreter *my_perl;
-
- int main(int argc, char **argv, char **env)
- {
- char *args[] = { NULL };
- PERL_SYS_INIT3(&argc,&argv,&env);
- my_perl = perl_alloc();
- perl_construct(my_perl);
-
- perl_parse(my_perl, NULL, argc, argv, NULL);
- PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
-
- /*** skipping perl_run() ***/
-
- call_argv("showtime", G_DISCARD | G_NOARGS, args);
-
- perl_destruct(my_perl);
- perl_free(my_perl);
- PERL_SYS_TERM();
- }
-</pre>
-<p>where <em>showtime</em> is a Perl subroutine that takes no arguments
(that’s the
-<em>G_NOARGS</em>) and for which I’ll ignore the return value
(that’s the
-<em>G_DISCARD</em>). Those flags, and others, are discussed in <a
href="#perlcall-NAME">perlcall NAME</a>.
-</p>
-<p>I’ll define the <em>showtime</em> subroutine in a file called
<em>showtime.pl</em>:
-</p>
-<pre class="verbatim"> print "I shan't be printed.";
-
- sub showtime {
- print time;
- }
-</pre>
-<p>Simple enough. Now compile and run:
-</p>
-<pre class="verbatim"> % cc -o showtime showtime.c \
- `perl -MExtUtils::Embed -e ccopts -e ldopts`
- % showtime showtime.pl
- 818284590
-</pre>
-<p>yielding the number of seconds that elapsed between January 1, 1970
-(the beginning of the Unix epoch), and the moment I began writing this
-sentence.
-</p>
-<p>In this particular case we don’t have to call <em>perl_run</em>, as
we set
-the PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in
-perl_destruct.
-</p>
-<p>If you want to pass arguments to the Perl subroutine, you can add
-strings to the <code>NULL</code>-terminated <code>args</code> list passed to
-<em>call_argv</em>. For other data types, or to examine return values,
-you’ll need to manipulate the Perl stack. That’s demonstrated in
-<a href="#perlembed-Fiddling-with-the-Perl-stack-from-your-C-program">Fiddling
with the Perl stack from your C program</a>.
-</p>
-<hr>
-<a name="perlembed-Evaluating-a-Perl-statement-from-your-C-program"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlembed-Performing-Perl-pattern-matches-and-substitutions-from-your-C-program"
accesskey="n" rel="next">perlembed Performing Perl pattern matches and
substitutions from your C program</a>, Previous: <a
href="#perlembed-Calling-a-Perl-subroutine-from-your-C-program" accesskey="p"
rel="prev">perlembed Calling a Perl subroutine from your C program</a>, Up: <a
href="#perlembed-DESCRIPTION" accesskey="u" rel="up">perlembed DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Evaluating-a-Perl-statement-from-your-C-program"></a>
-<h4 class="subsection">20.2.6 Evaluating a Perl statement from your C
program</h4>
-
-<p>Perl provides two API functions to evaluate pieces of Perl code.
-These are <a href="perlapi.html#eval_005fsv">(perlapi)eval_sv</a> and <a
href="perlapi.html#eval_005fpv">(perlapi)eval_pv</a>.
-</p>
-<p>Arguably, these are the only routines you’ll ever need to execute
-snippets of Perl code from within your C program. Your code can be as
-long as you wish; it can contain multiple statements; it can employ
-‘perlfunc use’, <a href="#perlfunc-require">perlfunc require</a>,
and ‘perlfunc do’ to
-include external Perl files.
-</p>
-<p><em>eval_pv</em> lets us evaluate individual Perl strings, and then
-extract variables for coercion into C types. The following program,
-<em>string.c</em>, executes three Perl strings, extracting an <code>int</code>
from
-the first, a <code>float</code> from the second, and a <code>char *</code>
from the third.
-</p>
-<pre class="verbatim"> #include <EXTERN.h>
- #include <perl.h>
-
- static PerlInterpreter *my_perl;
-
- main (int argc, char **argv, char **env)
- {
- char *embedding[] = { "", "-e", "0" };
-
- PERL_SYS_INIT3(&argc,&argv,&env);
- my_perl = perl_alloc();
- perl_construct( my_perl );
-
- perl_parse(my_perl, NULL, 3, embedding, NULL);
- PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
- perl_run(my_perl);
-
- /** Treat $a as an integer **/
- eval_pv("$a = 3; $a **= 2", TRUE);
- printf("a = %d\n", SvIV(get_sv("a", 0)));
-
- /** Treat $a as a float **/
- eval_pv("$a = 3.14; $a **= 2", TRUE);
- printf("a = %f\n", SvNV(get_sv("a", 0)));
-
- /** Treat $a as a string **/
- eval_pv(
- "$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
- printf("a = %s\n", SvPV_nolen(get_sv("a", 0)));
-
- perl_destruct(my_perl);
- perl_free(my_perl);
- PERL_SYS_TERM();
- }
-</pre>
-<p>All of those strange functions with <em>sv</em> in their names help convert
Perl
-scalars to C types. They’re described in <a
href="#perlguts-NAME">perlguts NAME</a> and <a
href="perlapi.html#Top">(perlapi)</a>.
-</p>
-<p>If you compile and run <em>string.c</em>, you’ll see the results of
using
-<em>SvIV()</em> to create an <code>int</code>, <em>SvNV()</em> to create a
<code>float</code>, and
-<em>SvPV()</em> to create a string:
-</p>
-<pre class="verbatim"> a = 9
- a = 9.859600
- a = Just Another Perl Hacker
-</pre>
-<p>In the example above, we’ve created a global variable to temporarily
-store the computed value of our eval’ed expression. It is also
-possible and in most cases a better strategy to fetch the return value
-from <em>eval_pv()</em> instead. Example:
-</p>
-<pre class="verbatim"> ...
- SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
- printf("%s\n", SvPV_nolen(val));
- ...
-</pre>
-<p>This way, we avoid namespace pollution by not creating global
-variables and we’ve simplified our code as well.
-</p>
-<hr>
-<a
name="perlembed-Performing-Perl-pattern-matches-and-substitutions-from-your-C-program"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-Fiddling-with-the-Perl-stack-from-your-C-program"
accesskey="n" rel="next">perlembed Fiddling with the Perl stack from your C
program</a>, Previous: <a
href="#perlembed-Evaluating-a-Perl-statement-from-your-C-program" accesskey="p"
rel="prev">perlembed Evaluating a Perl statement from your C program</a>, Up:
<a href="#perlembed-DESCRIPTION" accesskey="u" rel="up">perlembed
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a
name="Performing-Perl-pattern-matches-and-substitutions-from-your-C-program"></a>
-<h4 class="subsection">20.2.7 Performing Perl pattern matches and
substitutions from your C program</h4>
-
-<p>The <em>eval_sv()</em> function lets us evaluate strings of Perl code, so
we can
-define some functions that use it to "specialize" in matches and
-substitutions: <em>match()</em>, <em>substitute()</em>, and <em>matches()</em>.
-</p>
-<pre class="verbatim"> I32 match(SV *string, char *pattern);
-</pre>
-<p>Given a string and a pattern (e.g., <code>m/clasp/</code> or
<code>/\b\w*\b/</code>, which
-in your C program might appear as "/\\b\\w*\\b/"), match()
-returns 1 if the string matches the pattern and 0 otherwise.
-</p>
-<pre class="verbatim"> int substitute(SV **string, char *pattern);
-</pre>
-<p>Given a pointer to an <code>SV</code> and an <code>=~</code> operation
(e.g.,
-<code>s/bob/robert/g</code> or <code>tr[A-Z][a-z]</code>), substitute()
modifies the string
-within the <code>SV</code> as according to the operation, returning the number
of
-substitutions made.
-</p>
-<pre class="verbatim"> SSize_t matches(SV *string, char *pattern, AV
**matches);
-</pre>
-<p>Given an <code>SV</code>, a pattern, and a pointer to an empty
<code>AV</code>,
-matches() evaluates <code>$string =~ $pattern</code> in a list context, and
-fills in <em>matches</em> with the array elements, returning the number of
matches
-found.
-</p>
-<p>Here’s a sample program, <em>match.c</em>, that uses all three (long
lines have
-been wrapped here):
-</p>
-<pre class="verbatim"> #include <EXTERN.h>
- #include <perl.h>
-
- static PerlInterpreter *my_perl;
-
- /** my_eval_sv(code, error_check)
- ** kinda like eval_sv(),
- ** but we pop the return value off the stack
- **/
- SV* my_eval_sv(SV *sv, I32 croak_on_error)
- {
- dSP;
- SV* retval;
-
-
- PUSHMARK(SP);
- eval_sv(sv, G_SCALAR);
-
- SPAGAIN;
- retval = POPs;
- PUTBACK;
-
- if (croak_on_error && SvTRUE(ERRSV))
- croak(SvPVx_nolen(ERRSV));
-
- return retval;
- }
-
- /** match(string, pattern)
- **
- ** Used for matches in a scalar context.
- **
- ** Returns 1 if the match was successful; 0 otherwise.
- **/
-
- I32 match(SV *string, char *pattern)
- {
- SV *command = newSV(0), *retval;
-
- sv_setpvf(command, "my $string = '%s'; $string =~ %s",
- SvPV_nolen(string), pattern);
-
- retval = my_eval_sv(command, TRUE);
- SvREFCNT_dec(command);
-
- return SvIV(retval);
- }
-
- /** substitute(string, pattern)
- **
- ** Used for =~ operations that
- ** modify their left-hand side (s/// and tr///)
- **
- ** Returns the number of successful matches, and
- ** modifies the input string if there were any.
- **/
-
- I32 substitute(SV **string, char *pattern)
- {
- SV *command = newSV(0), *retval;
-
- sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
- SvPV_nolen(*string), pattern);
-
- retval = my_eval_sv(command, TRUE);
- SvREFCNT_dec(command);
-
- *string = get_sv("string", 0);
- return SvIV(retval);
- }
-
- /** matches(string, pattern, matches)
- **
- ** Used for matches in a list context.
- **
- ** Returns the number of matches,
- ** and fills in **matches with the matching substrings
- **/
-
- SSize_t matches(SV *string, char *pattern, AV **match_list)
- {
- SV *command = newSV(0);
- SSize_t num_matches;
-
- sv_setpvf(command, "my $string = '%s'; @array = ($string =~
%s)",
- SvPV_nolen(string), pattern);
-
- my_eval_sv(command, TRUE);
- SvREFCNT_dec(command);
-
- *match_list = get_av("array", 0);
- num_matches = av_top_index(*match_list) + 1;
-
- return num_matches;
- }
-
- main (int argc, char **argv, char **env)
- {
- char *embedding[] = { "", "-e", "0" };
- AV *match_list;
- I32 num_matches, i;
- SV *text;
-
- PERL_SYS_INIT3(&argc,&argv,&env);
- my_perl = perl_alloc();
- perl_construct(my_perl);
- perl_parse(my_perl, NULL, 3, embedding, NULL);
- PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
-
- text = newSV(0);
- sv_setpv(text, "When he is at a convenience store and the "
- "bill comes to some amount like 76 cents, Maynard is "
- "aware that there is something he *should* do, something "
- "that will enable him to get back a quarter, but he has "
- "no idea *what*. He fumbles through his red squeezey "
- "changepurse and gives the boy three extra pennies with "
- "his dollar, hoping that he might luck into the correct "
- "amount. The boy gives him back two of his own pennies "
- "and then the big shiny quarter that is his prize. "
- "-RICHH");
-
- if (match(text, "m/quarter/")) /** Does text contain 'quarter'?
**/
- printf("match: Text contains the word 'quarter'.\n\n");
- else
- printf("match: Text doesn't contain the word
'quarter'.\n\n");
-
- if (match(text, "m/eighth/")) /** Does text contain 'eighth'?
**/
- printf("match: Text contains the word 'eighth'.\n\n");
- else
- printf("match: Text doesn't contain the word 'eighth'.\n\n");
-
- /** Match all occurrences of /wi../ **/
- num_matches = matches(text, "m/(wi..)/g", &match_list);
- printf("matches: m/(wi..)/g found %d matches...\n",
num_matches);
-
- for (i = 0; i < num_matches; i++)
- printf("match: %s\n",
- SvPV_nolen(*av_fetch(match_list, i, FALSE)));
- printf("\n");
-
- /** Remove all vowels from text **/
- num_matches = substitute(&text, "s/[aeiou]//gi");
- if (num_matches) {
- printf("substitute: s/[aeiou]//gi...%lu substitutions
made.\n",
- (unsigned long)num_matches);
- printf("Now text is: %s\n\n", SvPV_nolen(text));
- }
-
- /** Attempt a substitution **/
- if (!substitute(&text, "s/Perl/C/")) {
- printf("substitute: s/Perl/C...No substitution made.\n\n");
- }
-
- SvREFCNT_dec(text);
- PL_perl_destruct_level = 1;
- perl_destruct(my_perl);
- perl_free(my_perl);
- PERL_SYS_TERM();
- }
-</pre>
-<p>which produces the output (again, long lines have been wrapped here)
-</p>
-<pre class="verbatim"> match: Text contains the word 'quarter'.
-
- match: Text doesn't contain the word 'eighth'.
-
- matches: m/(wi..)/g found 2 matches...
- match: will
- match: with
-
- substitute: s/[aeiou]//gi...139 substitutions made.
- Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
- Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt
- bck qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd
- gvs th by thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct
- mnt. Th by gvs hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s
- hs prz. -RCHH
-
- substitute: s/Perl/C...No substitution made.
-</pre>
-<hr>
-<a name="perlembed-Fiddling-with-the-Perl-stack-from-your-C-program"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-Maintaining-a-persistent-interpreter" accesskey="n"
rel="next">perlembed Maintaining a persistent interpreter</a>, Previous: <a
href="#perlembed-Performing-Perl-pattern-matches-and-substitutions-from-your-C-program"
accesskey="p" rel="prev">perlembed Performing Perl pattern matches and
substitutions from your C program</a>, Up: <a href="#perlembed-DESCRIPTION"
accesskey="u" rel="up">perlembed DESCRIPTION</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Fiddling-with-the-Perl-stack-from-your-C-program"></a>
-<h4 class="subsection">20.2.8 Fiddling with the Perl stack from your C
program</h4>
-
-<p>When trying to explain stacks, most computer science textbooks mumble
-something about spring-loaded columns of cafeteria plates: the last
-thing you pushed on the stack is the first thing you pop off. That’ll
-do for our purposes: your C program will push some arguments onto "the
Perl
-stack", shut its eyes while some magic happens, and then pop the
-results–the return value of your Perl subroutine–off the stack.
-</p>
-<p>First you’ll need to know how to convert between C types and Perl
-types, with newSViv() and sv_setnv() and newAV() and all their
-friends. They’re described in <a href="#perlguts-NAME">perlguts
NAME</a> and <a href="perlapi.html#Top">(perlapi)</a>.
-</p>
-<p>Then you’ll need to know how to manipulate the Perl stack.
That’s
-described in <a href="#perlcall-NAME">perlcall NAME</a>.
-</p>
-<p>Once you’ve understood those, embedding Perl in C is easy.
-</p>
-<p>Because C has no builtin function for integer exponentiation, let’s
-make Perl’s ** operator available to it (this is less useful than it
-sounds, because Perl implements ** with C’s <em>pow()</em> function).
First
-I’ll create a stub exponentiation function in <em>power.pl</em>:
-</p>
-<pre class="verbatim"> sub expo {
- my ($a, $b) = @_;
- return $a ** $b;
- }
-</pre>
-<p>Now I’ll create a C program, <em>power.c</em>, with a function
-<em>PerlPower()</em> that contains all the perlguts necessary to push the
-two arguments into <em>expo()</em> and to pop the return value out. Take a
-deep breath...
-</p>
-<pre class="verbatim"> #include <EXTERN.h>
- #include <perl.h>
-
- static PerlInterpreter *my_perl;
-
- static void
- PerlPower(int a, int b)
- {
- dSP; /* initialize stack pointer */
- ENTER; /* everything created after here */
- SAVETMPS; /* ...is a temporary variable. */
- PUSHMARK(SP); /* remember the stack pointer */
- XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */
- XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */
- PUTBACK; /* make local stack pointer global */
- call_pv("expo", G_SCALAR); /* call the function
*/
- SPAGAIN; /* refresh stack pointer */
- /* pop the return value from stack */
- printf ("%d to the %dth power is %d.\n", a, b, POPi);
- PUTBACK;
- FREETMPS; /* free that return value */
- LEAVE; /* ...and the XPUSHed "mortal"
args.*/
- }
-
- int main (int argc, char **argv, char **env)
- {
- char *my_argv[] = { "", "power.pl" };
-
- PERL_SYS_INIT3(&argc,&argv,&env);
- my_perl = perl_alloc();
- perl_construct( my_perl );
-
- perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
- PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
- perl_run(my_perl);
-
- PerlPower(3, 4); /*** Compute 3 ** 4 ***/
-
- perl_destruct(my_perl);
- perl_free(my_perl);
- PERL_SYS_TERM();
- }
-</pre>
-<p>Compile and run:
-</p>
-<pre class="verbatim"> % cc -o power power.c `perl -MExtUtils::Embed -e
ccopts -e ldopts`
-
- % power
- 3 to the 4th power is 81.
-</pre>
-<hr>
-<a name="perlembed-Maintaining-a-persistent-interpreter"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-Execution-of-END-blocks" accesskey="n"
rel="next">perlembed Execution of END blocks</a>, Previous: <a
href="#perlembed-Fiddling-with-the-Perl-stack-from-your-C-program"
accesskey="p" rel="prev">perlembed Fiddling with the Perl stack from your C
program</a>, Up: <a href="#perlembed-DESCRIPTION" accesskey="u"
rel="up">perlembed DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Maintaining-a-persistent-interpreter"></a>
-<h4 class="subsection">20.2.9 Maintaining a persistent interpreter</h4>
-
-<p>When developing interactive and/or potentially long-running
-applications, it’s a good idea to maintain a persistent interpreter
-rather than allocating and constructing a new interpreter multiple
-times. The major reason is speed: since Perl will only be loaded into
-memory once.
-</p>
-<p>However, you have to be more cautious with namespace and variable
-scoping when using a persistent interpreter. In previous examples
-we’ve been using global variables in the default package
<code>main</code>. We
-knew exactly what code would be run, and assumed we could avoid
-variable collisions and outrageous symbol table growth.
-</p>
-<p>Let’s say your application is a server that will occasionally run Perl
-code from some arbitrary file. Your server has no way of knowing what
-code it’s going to run. Very dangerous.
-</p>
-<p>If the file is pulled in by <code>perl_parse()</code>, compiled into a newly
-constructed interpreter, and subsequently cleaned out with
-<code>perl_destruct()</code> afterwards, you’re shielded from most
namespace
-troubles.
-</p>
-<p>One way to avoid namespace collisions in this scenario is to translate
-the filename into a guaranteed-unique package name, and then compile
-the code into that package using <a href="#perlfunc-eval">perlfunc eval</a>.
In the example
-below, each file will only be compiled once. Or, the application
-might choose to clean out the symbol table associated with the file
-after it’s no longer needed. Using <a
href="perlapi.html#call_005fargv">(perlapi)call_argv</a>, We’ll
-call the subroutine <code>Embed::Persistent::eval_file</code> which lives in
the
-file <code>persistent.pl</code> and pass the filename and boolean cleanup/cache
-flag as arguments.
-</p>
-<p>Note that the process will continue to grow for each file that it
-uses. In addition, there might be <code>AUTOLOAD</code>ed subroutines and
other
-conditions that cause Perl’s symbol table to grow. You might want to
-add some logic that keeps track of the process size, or restarts
-itself after a certain number of requests, to ensure that memory
-consumption is minimized. You’ll also want to scope your variables
-with ‘perlfunc my’ whenever possible.
-</p>
-<pre class="verbatim"> package Embed::Persistent;
- #persistent.pl
-
- use strict;
- our %Cache;
- use Symbol qw(delete_package);
-
- sub valid_package_name {
- my($string) = @_;
- $string =~
s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg;
- # second pass only for words starting with a digit
- $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg;
-
- # Dress it up as a real package name
- $string =~ s|/|::|g;
- return "Embed" . $string;
- }
-
- sub eval_file {
- my($filename, $delete) = @_;
- my $package = valid_package_name($filename);
- my $mtime = -M $filename;
- if(defined $Cache{$package}{mtime}
- &&
- $Cache{$package}{mtime} <= $mtime)
- {
- # we have compiled this subroutine already,
- # it has not been updated on disk, nothing left to do
- print STDERR "already compiled $package->handler\n";
- }
- else {
- local *FH;
- open FH, $filename or die "open '$filename' $!";
- local($/) = undef;
- my $sub = <FH>;
- close FH;
-
- #wrap the code into a subroutine inside our unique package
- my $eval = qq{package $package; sub handler { $sub; }};
- {
- # hide our variables within this block
- my($filename,$mtime,$package,$sub);
- eval $eval;
- }
- die $@ if $@;
-
- #cache it unless we're cleaning out each time
- $Cache{$package}{mtime} = $mtime unless $delete;
- }
-
- eval {$package->handler;};
- die $@ if $@;
-
- delete_package($package) if $delete;
-
- #take a look if you want
- #print Devel::Symdump->rnew($package)->as_string, $/;
- }
-
- 1;
-
- __END__
-
- /* persistent.c */
- #include <EXTERN.h>
- #include <perl.h>
-
- /* 1 = clean out filename's symbol table after each request,
- 0 = don't
- */
- #ifndef DO_CLEAN
- #define DO_CLEAN 0
- #endif
-
- #define BUFFER_SIZE 1024
-
- static PerlInterpreter *my_perl = NULL;
-
- int
- main(int argc, char **argv, char **env)
- {
- char *embedding[] = { "", "persistent.pl" };
- char *args[] = { "", DO_CLEAN, NULL };
- char filename[BUFFER_SIZE];
- int exitstatus = 0;
-
- PERL_SYS_INIT3(&argc,&argv,&env);
- if((my_perl = perl_alloc()) == NULL) {
- fprintf(stderr, "no memory!");
- exit(1);
- }
- perl_construct(my_perl);
-
- PL_origalen = 1; /* don't let $0 assignment update the
- proctitle or embedding[0] */
- exitstatus = perl_parse(my_perl, NULL, 2, embedding, NULL);
- PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
- if(!exitstatus) {
- exitstatus = perl_run(my_perl);
-
- while(printf("Enter file name: ") &&
- fgets(filename, BUFFER_SIZE, stdin)) {
-
- filename[strlen(filename)-1] = '\0'; /* strip \n */
- /* call the subroutine,
- passing it the filename as an argument */
- args[0] = filename;
- call_argv("Embed::Persistent::eval_file",
- G_DISCARD | G_EVAL, args);
-
- /* check $@ */
- if(SvTRUE(ERRSV))
- fprintf(stderr, "eval error: %s\n",
SvPV_nolen(ERRSV));
- }
- }
-
- PL_perl_destruct_level = 0;
- perl_destruct(my_perl);
- perl_free(my_perl);
- PERL_SYS_TERM();
- exit(exitstatus);
- }
-</pre>
-<p>Now compile:
-</p>
-<pre class="verbatim"> % cc -o persistent persistent.c \
- `perl -MExtUtils::Embed -e ccopts -e ldopts`
-</pre>
-<p>Here’s an example script file:
-</p>
-<pre class="verbatim"> #test.pl
- my $string = "hello";
- foo($string);
-
- sub foo {
- print "foo says: @_\n";
- }
-</pre>
-<p>Now run:
-</p>
-<pre class="verbatim"> % persistent
- Enter file name: test.pl
- foo says: hello
- Enter file name: test.pl
- already compiled Embed::test_2epl->handler
- foo says: hello
- Enter file name: ^C
-</pre>
-<hr>
-<a name="perlembed-Execution-of-END-blocks"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-_00240-assignments" accesskey="n"
rel="next">perlembed $0 assignments</a>, Previous: <a
href="#perlembed-Maintaining-a-persistent-interpreter" accesskey="p"
rel="prev">perlembed Maintaining a persistent interpreter</a>, Up: <a
href="#perlembed-DESCRIPTION" accesskey="u" rel="up">perlembed DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Execution-of-END-blocks"></a>
-<h4 class="subsection">20.2.10 Execution of END blocks</h4>
-
-<p>Traditionally END blocks have been executed at the end of the perl_run.
-This causes problems for applications that never call perl_run. Since
-perl 5.7.2 you can specify <code>PL_exit_flags |= PERL_EXIT_DESTRUCT_END</code>
-to get the new behaviour. This also enables the running of END blocks if
-the perl_parse fails and <code>perl_destruct</code> will return the exit value.
-</p>
-<hr>
-<a name="perlembed-_00240-assignments"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-Maintaining-multiple-interpreter-instances"
accesskey="n" rel="next">perlembed Maintaining multiple interpreter
instances</a>, Previous: <a href="#perlembed-Execution-of-END-blocks"
accesskey="p" rel="prev">perlembed Execution of END blocks</a>, Up: <a
href="#perlembed-DESCRIPTION" accesskey="u" rel="up">perlembed DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="g_t_00240-assignments"></a>
-<h4 class="subsection">20.2.11 $0 assignments</h4>
-
-<p>When a perl script assigns a value to $0 then the perl runtime will
-try to make this value show up as the program name reported by "ps"
by
-updating the memory pointed to by the argv passed to perl_parse() and
-also calling API functions like setproctitle() where available. This
-behaviour might not be appropriate when embedding perl and can be
-disabled by assigning the value <code>1</code> to the variable
<code>PL_origalen</code>
-before perl_parse() is called.
-</p>
-<p>The <samp>persistent.c</samp> example above is for instance likely to
segfault
-when $0 is assigned to if the <code>PL_origalen = 1;</code> assignment is
-removed. This because perl will try to write to the read only memory
-of the <code>embedding[]</code> strings.
-</p>
-<hr>
-<a name="perlembed-Maintaining-multiple-interpreter-instances"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlembed-Using-Perl-modules_002c-which-themselves-use-C-libraries_002c-from-your-C-program"
accesskey="n" rel="next">perlembed Using Perl modules, which themselves use C
libraries, from your C program</a>, Previous: <a
href="#perlembed-_00240-assignments" accesskey="p" rel="prev">perlembed $0
assignments</a>, Up: <a href="#perlembed-DESCRIPTION" accesskey="u"
rel="up">perlembed DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Maintaining-multiple-interpreter-instances"></a>
-<h4 class="subsection">20.2.12 Maintaining multiple interpreter instances</h4>
-
-<p>Some rare applications will need to create more than one interpreter
-during a session. Such an application might sporadically decide to
-release any resources associated with the interpreter.
-</p>
-<p>The program must take care to ensure that this takes place <em>before</em>
-the next interpreter is constructed. By default, when perl is not
-built with any special options, the global variable
-<code>PL_perl_destruct_level</code> is set to <code>0</code>, since extra
cleaning isn’t
-usually needed when a program only ever creates a single interpreter
-in its entire lifetime.
-</p>
-<p>Setting <code>PL_perl_destruct_level</code> to <code>1</code> makes
everything squeaky clean:
-</p>
-<pre class="verbatim"> while(1) {
- ...
- /* reset global variables here with PL_perl_destruct_level = 1 */
- PL_perl_destruct_level = 1;
- perl_construct(my_perl);
- ...
- /* clean and reset _everything_ during perl_destruct */
- PL_perl_destruct_level = 1;
- perl_destruct(my_perl);
- perl_free(my_perl);
- ...
- /* let's go do it again! */
- }
-</pre>
-<p>When <em>perl_destruct()</em> is called, the interpreter’s syntax
parse tree
-and symbol tables are cleaned up, and global variables are reset. The
-second assignment to <code>PL_perl_destruct_level</code> is needed because
-perl_construct resets it to <code>0</code>.
-</p>
-<p>Now suppose we have more than one interpreter instance running at the
-same time. This is feasible, but only if you used the Configure option
-<code>-Dusemultiplicity</code> or the options <code>-Dusethreads
-Duseithreads</code> when
-building perl. By default, enabling one of these Configure options
-sets the per-interpreter global variable <code>PL_perl_destruct_level</code> to
-<code>1</code>, so that thorough cleaning is automatic and interpreter
variables
-are initialized correctly. Even if you don’t intend to run two or
-more interpreters at the same time, but to run them sequentially, like
-in the above example, it is recommended to build perl with the
-<code>-Dusemultiplicity</code> option otherwise some interpreter variables may
-not be initialized correctly between consecutive runs and your
-application may crash.
-</p>
-<p>See also <a
href="perlxs.html#Thread_002daware-system-interfaces">(perlxs)Thread-aware
system interfaces</a>.
-</p>
-<p>Using <code>-Dusethreads -Duseithreads</code> rather than
<code>-Dusemultiplicity</code>
-is more appropriate if you intend to run multiple interpreters
-concurrently in different threads, because it enables support for
-linking in the thread libraries of your system with the interpreter.
-</p>
-<p>Let’s give it a try:
-</p>
-<pre class="verbatim"> #include <EXTERN.h>
- #include <perl.h>
-
- /* we're going to embed two interpreters */
-
- #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)"
-
- int main(int argc, char **argv, char **env)
- {
- PerlInterpreter *one_perl, *two_perl;
- char *one_args[] = { "one_perl", SAY_HELLO };
- char *two_args[] = { "two_perl", SAY_HELLO };
-
- PERL_SYS_INIT3(&argc,&argv,&env);
- one_perl = perl_alloc();
- two_perl = perl_alloc();
-
- PERL_SET_CONTEXT(one_perl);
- perl_construct(one_perl);
- PERL_SET_CONTEXT(two_perl);
- perl_construct(two_perl);
-
- PERL_SET_CONTEXT(one_perl);
- perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
- PERL_SET_CONTEXT(two_perl);
- perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
-
- PERL_SET_CONTEXT(one_perl);
- perl_run(one_perl);
- PERL_SET_CONTEXT(two_perl);
- perl_run(two_perl);
-
- PERL_SET_CONTEXT(one_perl);
- perl_destruct(one_perl);
- PERL_SET_CONTEXT(two_perl);
- perl_destruct(two_perl);
-
- PERL_SET_CONTEXT(one_perl);
- perl_free(one_perl);
- PERL_SET_CONTEXT(two_perl);
- perl_free(two_perl);
- PERL_SYS_TERM();
- }
-</pre>
-<p>Note the calls to PERL_SET_CONTEXT(). These are necessary to initialize
-the global state that tracks which interpreter is the "current" one
on
-the particular process or thread that may be running it. It should
-always be used if you have more than one interpreter and are making
-perl API calls on both interpreters in an interleaved fashion.
-</p>
-<p>PERL_SET_CONTEXT(interp) should also be called whenever <code>interp</code>
is
-used by a thread that did not create it (using either perl_alloc(), or
-the more esoteric perl_clone()).
-</p>
-<p>Compile as usual:
-</p>
-<pre class="verbatim"> % cc -o multiplicity multiplicity.c \
- `perl -MExtUtils::Embed -e ccopts -e ldopts`
-</pre>
-<p>Run it, Run it:
-</p>
-<pre class="verbatim"> % multiplicity
- Hi, I'm one_perl
- Hi, I'm two_perl
-</pre>
-<hr>
-<a
name="perlembed-Using-Perl-modules_002c-which-themselves-use-C-libraries_002c-from-your-C-program"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-Using-embedded-Perl-with-POSIX-locales"
accesskey="n" rel="next">perlembed Using embedded Perl with POSIX locales</a>,
Previous: <a href="#perlembed-Maintaining-multiple-interpreter-instances"
accesskey="p" rel="prev">perlembed Maintaining multiple interpreter
instances</a>, Up: <a href="#perlembed-DESCRIPTION" accesskey="u"
rel="up">perlembed DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a
name="Using-Perl-modules_002c-which-themselves-use-C-libraries_002c-from-your-C-program"></a>
-<h4 class="subsection">20.2.13 Using Perl modules, which themselves use C
libraries, from your C program</h4>
-
-<p>If you’ve played with the examples above and tried to embed a script
-that <em>use()</em>s a Perl module (such as <em>Socket</em>) which itself uses
a C or C++
-library, this probably happened:
-</p>
-<pre class="verbatim"> Can't load module Socket, dynamic loading not available
in this perl.
- (You may need to build a new perl executable which either supports
- dynamic loading or has the Socket module statically linked into it.)
-</pre>
-<p>What’s wrong?
-</p>
-<p>Your interpreter doesn’t know how to communicate with these extensions
-on its own. A little glue will help. Up until now you’ve been
-calling <em>perl_parse()</em>, handing it NULL for the second argument:
-</p>
-<pre class="verbatim"> perl_parse(my_perl, NULL, argc, my_argv, NULL);
-</pre>
-<p>That’s where the glue code can be inserted to create the initial
contact
-between Perl and linked C/C++ routines. Let’s take a look some pieces of
-<em>perlmain.c</em> to see how Perl does this:
-</p>
-<pre class="verbatim"> static void xs_init (pTHX);
-
- EXTERN_C void boot_DynaLoader (pTHX_ CV* cv);
- EXTERN_C void boot_Socket (pTHX_ CV* cv);
-
-
- EXTERN_C void
- xs_init(pTHX)
- {
- char *file = __FILE__;
- /* DynaLoader is a special case */
- newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
- newXS("Socket::bootstrap", boot_Socket, file);
- }
-</pre>
-<p>Simply put: for each extension linked with your Perl executable
-(determined during its initial configuration on your
-computer or when adding a new extension),
-a Perl subroutine is created to incorporate the extension’s
-routines. Normally, that subroutine is named
-<em>Module::bootstrap()</em> and is invoked when you say <em>use Module</em>.
In
-turn, this hooks into an XSUB, <em>boot_Module</em>, which creates a Perl
-counterpart for each of the extension’s XSUBs. Don’t worry about
this
-part; leave that to the <em>xsubpp</em> and extension authors. If your
-extension is dynamically loaded, DynaLoader creates
<em>Module::bootstrap()</em>
-for you on the fly. In fact, if you have a working DynaLoader then there
-is rarely any need to link in any other extensions statically.
-</p>
-<p>Once you have this code, slap it into the second argument of
<em>perl_parse()</em>:
-</p>
-<pre class="verbatim"> perl_parse(my_perl, xs_init, argc, my_argv, NULL);
-</pre>
-<p>Then compile:
-</p>
-<pre class="verbatim"> % cc -o interp interp.c `perl -MExtUtils::Embed -e
ccopts -e ldopts`
-
- % interp
- use Socket;
- use SomeDynamicallyLoadedModule;
-
- print "Now I can use extensions!\n"'
-</pre>
-<p><strong>ExtUtils::Embed</strong> can also automate writing the
<em>xs_init</em> glue code.
-</p>
-<pre class="verbatim"> % perl -MExtUtils::Embed -e xsinit -- -o perlxsi.c
- % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
- % cc -c interp.c `perl -MExtUtils::Embed -e ccopts`
- % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`
-</pre>
-<p>Consult <a href="perlxs.html#Top">(perlxs)</a>, <a
href="#perlguts-NAME">perlguts NAME</a>, and <a
href="perlapi.html#Top">(perlapi)</a> for more details.
-</p>
-<hr>
-<a name="perlembed-Using-embedded-Perl-with-POSIX-locales"></a>
-<div class="header">
-<p>
-Previous: <a
href="#perlembed-Using-Perl-modules_002c-which-themselves-use-C-libraries_002c-from-your-C-program"
accesskey="p" rel="prev">perlembed Using Perl modules, which themselves use C
libraries, from your C program</a>, Up: <a href="#perlembed-DESCRIPTION"
accesskey="u" rel="up">perlembed DESCRIPTION</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-embedded-Perl-with-POSIX-locales"></a>
-<h4 class="subsection">20.2.14 Using embedded Perl with POSIX locales</h4>
-
-<p>(See <a href="#perllocale-NAME">perllocale NAME</a> for information about
these.)
-When a Perl interpreter normally starts up, it tells the system it wants
-to use the system’s default locale. This is often, but not necessarily,
-the "C" or "POSIX" locale. Absent a
<code>"use locale"</code><!-- /@w --> within the perl
-code, this mostly has no effect (but see <a
href="#perllocale-Not-within-the-scope-of-_0022use-locale_0022">perllocale
<strong>Not within the scope of <code>"use
locale"</code></strong></a>). Also, there is not a problem if the
-locale you want to use in your embedded Perl is the same as the system
-default. However, this doesn’t work if you have set up and want to use
-a locale that isn’t the system default one. Starting in Perl v5.20, you
-can tell the embedded Perl interpreter that the locale is already
-properly set up, and to skip doing its own normal initialization. It
-skips if the environment variable <code>PERL_SKIP_LOCALE_INIT</code> is set
(even
-if set to 0 or <code>""</code>). A Perl that has this capability
will define the
-C pre-processor symbol <code>HAS_SKIP_LOCALE_INIT</code>. This allows code
that
-has to work with multiple Perl versions to do some sort of work-around
-when confronted with an earlier Perl.
-</p>
-<hr>
-<a name="perlembed-Hiding-Perl_005f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-MORAL" accesskey="n" rel="next">perlembed MORAL</a>,
Previous: <a href="#perlembed-DESCRIPTION" accesskey="p" rel="prev">perlembed
DESCRIPTION</a>, Up: <a href="#perlembed" accesskey="u" rel="up">perlembed</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Hiding-Perl_005f"></a>
-<h3 class="section">20.3 Hiding Perl_</h3>
-
-<p>If you completely hide the short forms of the Perl public API,
-add -DPERL_NO_SHORT_NAMES to the compilation flags. This means that
-for example instead of writing
-</p>
-<pre class="verbatim"> warn("%d bottles of beer on the wall",
bottlecount);
-</pre>
-<p>you will have to write the explicit full form
-</p>
-<pre class="verbatim"> Perl_warn(aTHX_ "%d bottles of beer on the
wall", bottlecount);
-</pre>
-<p>(See <a
href="#perlguts-Background-and-PERL_005fIMPLICIT_005fCONTEXT">perlguts
Background and PERL_IMPLICIT_CONTEXT</a> for the explanation
-of the <code>aTHX_</code>. ) 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.)
-</p>
-<hr>
-<a name="perlembed-MORAL"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-AUTHOR" accesskey="n" rel="next">perlembed
AUTHOR</a>, Previous: <a href="#perlembed-Hiding-Perl_005f" accesskey="p"
rel="prev">perlembed Hiding Perl_</a>, Up: <a href="#perlembed" accesskey="u"
rel="up">perlembed</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="MORAL"></a>
-<h3 class="section">20.4 MORAL</h3>
-
-<p>You can sometimes <em>write faster code</em> in C, but
-you can always <em>write code faster</em> in Perl. Because you can use
-each from the other, combine them as you wish.
-</p>
-<hr>
-<a name="perlembed-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlembed-COPYRIGHT" accesskey="n" rel="next">perlembed
COPYRIGHT</a>, Previous: <a href="#perlembed-MORAL" accesskey="p"
rel="prev">perlembed MORAL</a>, Up: <a href="#perlembed" accesskey="u"
rel="up">perlembed</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-8"></a>
-<h3 class="section">20.5 AUTHOR</h3>
-
-<p>Jon Orwant <<samp>address@hidden</samp>> and Doug MacEachern
-<<samp>address@hidden</samp>>, with small contributions from Tim Bunce,
Tom
-Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
-Zakharevich.
-</p>
-<p>Doug MacEachern has an article on embedding in Volume 1, Issue 4 of
-The Perl Journal ( http://www.tpj.com/ ). Doug is also the developer of the
-most widely-used Perl embedding: the mod_perl system
-(perl.apache.org), which embeds Perl in the Apache web server.
-Oracle, Binary Evolution, ActiveState, and Ben Sugars’s nsapi_perl
-have used this model for Oracle, Netscape and Internet Information
-Server Perl plugins.
-</p>
-<hr>
-<a name="perlembed-COPYRIGHT"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlembed-AUTHOR" accesskey="p" rel="prev">perlembed
AUTHOR</a>, Up: <a href="#perlembed" accesskey="u" rel="up">perlembed</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="COPYRIGHT"></a>
-<h3 class="section">20.6 COPYRIGHT</h3>
-
-<p>Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant. All
-Rights Reserved.
-</p>
-<p>This document may be distributed under the same terms as Perl itself.
-</p>
-<hr>
-<a name="perlexperiment"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter" accesskey="n" rel="next">perlfilter</a>, Previous:
<a href="#perlembed" accesskey="p" rel="prev">perlembed</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlexperiment-1"></a>
-<h2 class="chapter">21 perlexperiment</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlexperiment-NAME"
accesskey="1">perlexperiment NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlexperiment-DESCRIPTION"
accesskey="2">perlexperiment DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlexperiment-SEE-ALSO"
accesskey="3">perlexperiment SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlexperiment-AUTHORS"
accesskey="4">perlexperiment AUTHORS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlexperiment-COPYRIGHT"
accesskey="5">perlexperiment COPYRIGHT</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlexperiment-LICENSE"
accesskey="6">perlexperiment LICENSE</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlexperiment-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlexperiment-DESCRIPTION" accesskey="n"
rel="next">perlexperiment DESCRIPTION</a>, Up: <a href="#perlexperiment"
accesskey="u" rel="up">perlexperiment</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-20"></a>
-<h3 class="section">21.1 NAME</h3>
-
-<p>perlexperiment - A listing of experimental features in Perl
-</p>
-<hr>
-<a name="perlexperiment-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlexperiment-SEE-ALSO" accesskey="n"
rel="next">perlexperiment SEE ALSO</a>, Previous: <a
href="#perlexperiment-NAME" accesskey="p" rel="prev">perlexperiment NAME</a>,
Up: <a href="#perlexperiment" accesskey="u" rel="up">perlexperiment</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-20"></a>
-<h3 class="section">21.2 DESCRIPTION</h3>
-
-<p>This document lists the current and past experimental features in the perl
-core. Although all of these are documented with their appropriate topics,
-this succinct listing gives you an overview and basic facts about their
-status.
-</p>
-<p>So far we’ve merely tried to find and list the experimental features
and infer
-their inception, versions, etc. There’s a lot of speculation here.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlexperiment-Current-experiments" accesskey="1">perlexperiment Current
experiments</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlexperiment-Accepted-features" accesskey="2">perlexperiment Accepted
features</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlexperiment-Removed-features" accesskey="3">perlexperiment Removed
features</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlexperiment-Current-experiments"></a>
-<div class="header">
-<p>
-Next: <a href="#perlexperiment-Accepted-features" accesskey="n"
rel="next">perlexperiment Accepted features</a>, Up: <a
href="#perlexperiment-DESCRIPTION" accesskey="u" rel="up">perlexperiment
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Current-experiments"></a>
-<h4 class="subsection">21.2.1 Current experiments</h4>
-
-<dl compact="compact">
-<dt><code>our</code> can now have an experimental optional attribute
<code>unique</code></dt>
-<dd><a
name="perlexperiment-our-can-now-have-an-experimental-optional-attribute-unique"></a>
-<p>Introduced in Perl 5.8.0
-</p>
-<p>Deprecated in Perl 5.10.0
-</p>
-<p>The ticket for this feature is
-<a href="https://rt.perl.org/rt3/Ticket/Display.html?id=119313";>[perl
#119313]</a>.
-</p>
-</dd>
-<dt>Smart match (<code>~~</code>)</dt>
-<dd><a name="perlexperiment-Smart-match-_0028_007e_007e_0029"></a>
-<p>Introduced in Perl 5.10.0
-</p>
-<p>Modified in Perl 5.10.1, 5.12.0
-</p>
-<p>Using this feature triggers warnings in the category
-<code>experimental::smartmatch</code>.
-</p>
-<p>The ticket for this feature is
-<a href="https://rt.perl.org/rt3/Ticket/Display.html?id=119317";>[perl
#119317]</a>.
-</p>
-</dd>
-<dt>Lexical <code>$_</code></dt>
-<dd><a name="perlexperiment-Lexical-_0024_005f"></a>
-<p>Introduced in Perl 5.10.0
-</p>
-<p>Using this feature triggers warnings in the category
-<code>experimental::lexical_topic</code>.
-</p>
-<p>The ticket for this feature is
-<a href="https://rt.perl.org/rt3/Ticket/Display.html?id=119315";>[perl
#119315]</a>.
-</p>
-</dd>
-<dt>Pluggable keywords</dt>
-<dd><a name="perlexperiment-Pluggable-keywords"></a>
-<p>The ticket for this feature is
-<a href="https://rt.perl.org/rt3/Ticket/Display.html?id=119455";>[perl
#119455]</a>.
-</p>
-<p>See <a
href="perlapi.html#PL_005fkeyword_005fplugin">(perlapi)PL_keyword_plugin</a>
for the mechanism.
-</p>
-<p>Introduced in: Perl 5.11.2
-</p>
-</dd>
-<dt>Array and hash container functions accept references</dt>
-<dd><a
name="perlexperiment-Array-and-hash-container-functions-accept-references"></a>
-<p>Introduced in Perl 5.14.0
-</p>
-<p>The ticket for this feature is
-<a href="https://rt.perl.org/rt3/Ticket/Display.html?id=119437";>[perl
#119437]</a>.
-</p>
-</dd>
-<dt>Lexical subroutines</dt>
-<dd><a name="perlexperiment-Lexical-subroutines"></a>
-<p>Introduced in: Perl 5.18
-</p>
-<p>See also: <a href="#perlsub-Lexical-Subroutines">perlsub Lexical
Subroutines</a>
-</p>
-<p>Using this feature triggers warnings in the category
-<code>experimental::lexical_subs</code>.
-</p>
-<p>The ticket for this feature is
-<a href="https://rt.perl.org/rt3/Ticket/Display.html?id=120085";>[perl
#120085]</a>.
-</p>
-</dd>
-<dt>Regular Expression Set Operations</dt>
-<dd><a name="perlexperiment-Regular-Expression-Set-Operations"></a>
-<p>Introduced in: Perl 5.18
-</p>
-<p>The ticket for this feature is
-<a href="https://rt.perl.org/rt3/Ticket/Display.html?id=119451";>[perl
#119451]</a>.
-</p>
-<p>See also: <a
href="#perlrecharclass-Extended-Bracketed-Character-Classes">perlrecharclass
Extended Bracketed Character Classes</a>
-</p>
-<p>Using this feature triggers warnings in the category
-<code>experimental::regex_sets</code>.
-</p>
-</dd>
-<dt>Subroutine signatures</dt>
-<dd><a name="perlexperiment-Subroutine-signatures"></a>
-<p>Introduced in Perl 5.20.0
-</p>
-<p>Using this feature triggers warnings in the category
-<code>experimental::signatures</code>.
-</p>
-<p>The ticket for this feature is
-<a href="https://rt.perl.org/Ticket/Display.html?id=121481";>[perl #121481]</a>.
-</p>
-</dd>
-<dt>Postfix dereference syntax</dt>
-<dd><a name="perlexperiment-Postfix-dereference-syntax"></a>
-<p>Introduced in Perl 5.20.0
-</p>
-<p>Using this feature triggers warnings in the category
-<code>experimental::postderef</code>.
-</p>
-<p>The ticket for this feature is
-<a href="https://rt.perl.org:443/rt3/Ticket/Display.html?id=120162";>[perl
#120162]</a>.
-</p>
-</dd>
-<dt>Aliasing via reference</dt>
-<dd><a name="perlexperiment-Aliasing-via-reference"></a>
-<p>Introduced in Perl 5.22.0
-</p>
-<p>Using this feature triggers warnings in the category
-<code>experimental::refaliasing</code>.
-</p>
-<p>The ticket for this feature is
-<a href="https://rt.perl.org/rt3/Ticket/Display.html?id=122947";>[perl
#122947]</a>.
-</p>
-<p>See also: <a href="#perlref-Assigning-to-References">perlref Assigning to
References</a>
-</p>
-</dd>
-<dt>The "const" attribute</dt>
-<dd><a name="perlexperiment-The-_0022const_0022-attribute"></a>
-<p>Introduced in Perl 5.22.0
-</p>
-<p>Using this feature triggers warnings in the category
-<code>experimental::const_attr</code>.
-</p>
-<p>The ticket for this feature is
-<a href="https://rt.perl.org/rt3/Ticket/Display.html?id=123630";>[perl
#123630]</a>.
-</p>
-<p>See also: <a href="#perlsub-Constant-Functions">perlsub Constant
Functions</a>
-</p>
-</dd>
-<dt>use re ’strict’;</dt>
-<dd><a name="perlexperiment-use-re-_0027strict_0027_003b"></a>
-<p>Introduced in Perl 5.22.0
-</p>
-<p>Using this feature triggers warnings in the category
-<code>experimental::re_strict</code>.
-</p>
-<p>See <a href="re.html#g_t_0027strict_0027-mode">(re)'strict' mode</a>
-</p>
-</dd>
-<dt>String- and number-specific bitwise operators</dt>
-<dd><a
name="perlexperiment-String_002d-and-number_002dspecific-bitwise-operators"></a>
-<p>Introduced in: Perl 5.22.0
-</p>
-<p>See also: <a href="#perlop-Bitwise-String-Operators">perlop Bitwise String
Operators</a>
-</p>
-<p>Using this feature triggers warnings in the category
-<code>experimental::bitwise</code>.
-</p>
-<p>The ticket for this feature is
-<a href="https://rt.perl.org/rt3/Ticket/Display.html?id=123707";>[perl
#123707]</a>.
-</p>
-</dd>
-<dt>The <:win32> IO pseudolayer</dt>
-<dd><a name="perlexperiment-The-_003c_003awin32_003e-IO-pseudolayer"></a>
-<p>The ticket for this feature is
-<a href="https://rt.perl.org/rt3/Ticket/Display.html?id=119453";>[perl
#119453]</a>.
-</p>
-<p>See also <a href="#perlrun-NAME">perlrun NAME</a>
-</p>
-</dd>
-<dt>There is an <code>installhtml</code> target in the Makefile.</dt>
-<dd><a
name="perlexperiment-There-is-an-installhtml-target-in-the-Makefile_002e"></a>
-<p>The ticket for this feature is
-<a href="https://rt.perl.org/rt3/Ticket/Display.html?id=116487";>[perl
#116487]</a>.
-</p>
-</dd>
-<dt>Unicode in Perl on EBCDIC</dt>
-<dd><a name="perlexperiment-Unicode-in-Perl-on-EBCDIC"></a>
-</dd>
-</dl>
-
-<hr>
-<a name="perlexperiment-Accepted-features"></a>
-<div class="header">
-<p>
-Next: <a href="#perlexperiment-Removed-features" accesskey="n"
rel="next">perlexperiment Removed features</a>, Previous: <a
href="#perlexperiment-Current-experiments" accesskey="p"
rel="prev">perlexperiment Current experiments</a>, Up: <a
href="#perlexperiment-DESCRIPTION" accesskey="u" rel="up">perlexperiment
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Accepted-features"></a>
-<h4 class="subsection">21.2.2 Accepted features</h4>
-
-<p>These features were so wildly successful and played so well with others that
-we decided to remove their experimental status and admit them as full, stable
-features in the world of Perl, lavishing all the benefits and luxuries thereof.
-They are also awarded +5 Stability and +3 Charisma.
-</p>
-<dl compact="compact">
-<dt>64-bit support</dt>
-<dd><a name="perlexperiment-64_002dbit-support"></a>
-<p>Introduced in Perl 5.005
-</p>
-</dd>
-<dt>die accepts a reference</dt>
-<dd><a name="perlexperiment-die-accepts-a-reference"></a>
-<p>Introduced in Perl 5.005
-</p>
-</dd>
-<dt>DB module</dt>
-<dd><a name="perlexperiment-DB-module"></a>
-<p>Introduced in Perl 5.6.0
-</p>
-<p>See also <a href="#perldebug-NAME">perldebug NAME</a>, <a
href="#perldebtut-NAME">perldebtut NAME</a>
-</p>
-</dd>
-<dt>Weak references</dt>
-<dd><a name="perlexperiment-Weak-references"></a>
-<p>Introduced in Perl 5.6.0
-</p>
-</dd>
-<dt>Internal file glob</dt>
-<dd><a name="perlexperiment-Internal-file-glob"></a>
-<p>Introduced in Perl 5.6.0
-</p>
-</dd>
-<dt>fork() emulation</dt>
-<dd><a name="perlexperiment-fork_0028_0029-emulation"></a>
-<p>Introduced in Perl 5.6.1
-</p>
-<p>See also <a href="#perlfork-NAME">perlfork NAME</a>
-</p>
-</dd>
-<dt>-Dusemultiplicity -Duseithreads</dt>
-<dd><a name="perlexperiment-_002dDusemultiplicity-_002dDuseithreads"></a>
-<p>Introduced in Perl 5.6.0
-</p>
-<p>Accepted in Perl 5.8.0
-</p>
-</dd>
-<dt>Support for long doubles</dt>
-<dd><a name="perlexperiment-Support-for-long-doubles"></a>
-<p>Introduced in Perl 5.6.0
-</p>
-<p>Accepted in Perl 5.8.1
-</p>
-</dd>
-<dt>The <code>\N</code> regex character class</dt>
-<dd><a name="perlexperiment-The-_005cN-regex-character-class"></a>
-<p>The <code>\N</code> character class, not to be confused with the named
character
-sequence <code>\N{NAME}</code>, denotes any non-newline character in a regular
-expression.
-</p>
-<p>Introduced in Perl 5.12
-</p>
-<p>Exact version of acceptance unclear, but no later than Perl 5.18.
-</p>
-</dd>
-<dt><code>(?{code})</code> and <code>(??{ code })</code></dt>
-<dd><a
name="perlexperiment-_0028_003f_007bcode_007d_0029-and-_0028_003f_003f_007b-code-_007d_0029"></a>
-<p>Introduced in Perl 5.6.0
-</p>
-<p>Accepted in Perl 5.20.0
-</p>
-<p>See also <a href="#perlre-NAME">perlre NAME</a>
-</p>
-</dd>
-<dt>Linux abstract Unix domain sockets</dt>
-<dd><a name="perlexperiment-Linux-abstract-Unix-domain-sockets"></a>
-<p>Introduced in Perl 5.9.2
-</p>
-<p>Accepted before Perl 5.20.0. The Socket library is now primarily maintained
-on CPAN, rather than in the perl core.
-</p>
-<p>See also <a href="Socket.html#Top">(Socket)</a>
-</p>
-</dd>
-<dt>Lvalue subroutines</dt>
-<dd><a name="perlexperiment-Lvalue-subroutines"></a>
-<p>Introduced in Perl 5.6.0
-</p>
-<p>Accepted in Perl 5.20.0
-</p>
-<p>See also <a href="#perlsub-NAME">perlsub NAME</a>
-</p>
-</dd>
-<dt>Backtracking control verbs</dt>
-<dd><a name="perlexperiment-Backtracking-control-verbs"></a>
-<p><code>(*ACCEPT)</code>
-</p>
-<p>Introduced in: Perl 5.10
-</p>
-<p>Accepted in Perl 5.20.0
-</p>
-</dd>
-<dt>The <:pop> IO pseudolayer</dt>
-<dd><a name="perlexperiment-The-_003c_003apop_003e-IO-pseudolayer"></a>
-<p>See also <a href="#perlrun-NAME">perlrun NAME</a>
-</p>
-<p>Accepted in Perl 5.20.0
-</p>
-</dd>
-<dt><code>\s</code> in regexp matches vertical tab</dt>
-<dd><a name="perlexperiment-_005cs-in-regexp-matches-vertical-tab"></a>
-<p>Accepted in Perl 5.22.0
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlexperiment-Removed-features"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlexperiment-Accepted-features" accesskey="p"
rel="prev">perlexperiment Accepted features</a>, Up: <a
href="#perlexperiment-DESCRIPTION" accesskey="u" rel="up">perlexperiment
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Removed-features"></a>
-<h4 class="subsection">21.2.3 Removed features</h4>
-
-<p>These features are no longer considered experimental and their functionality
-has disappeared. It’s your own fault if you wrote production programs
using
-these features after we explicitly told you not to (see <a
href="#perlpolicy-NAME">perlpolicy NAME</a>).
-</p>
-<dl compact="compact">
-<dt>5.005-style threading</dt>
-<dd><a name="perlexperiment-5_002e005_002dstyle-threading"></a>
-<p>Introduced in Perl 5.005
-</p>
-<p>Removed in Perl 5.10
-</p>
-</dd>
-<dt>perlcc</dt>
-<dd><a name="perlexperiment-perlcc"></a>
-<p>Introduced in Perl 5.005
-</p>
-<p>Moved from Perl 5.9.0 to CPAN
-</p>
-</dd>
-<dt>The pseudo-hash data type</dt>
-<dd><a name="perlexperiment-The-pseudo_002dhash-data-type"></a>
-<p>Introduced in Perl 5.6.0
-</p>
-<p>Removed in Perl 5.9.0
-</p>
-</dd>
-<dt>GetOpt::Long Options can now take multiple values at once
(experimental)</dt>
-<dd><a
name="perlexperiment-GetOpt_003a_003aLong-Options-can-now-take-multiple-values-at-once-_0028experimental_0029"></a>
-<p><code>Getopt::Long</code> upgraded to version 2.35
-</p>
-<p>Removed in Perl 5.8.8
-</p>
-</dd>
-<dt>Assertions</dt>
-<dd><a name="perlexperiment-Assertions"></a>
-<p>The <code>-A</code> command line switch
-</p>
-<p>Introduced in Perl 5.9.0
-</p>
-<p>Removed in Perl 5.9.5
-</p>
-</dd>
-<dt>Test::Harness::Straps</dt>
-<dd><a name="perlexperiment-Test_003a_003aHarness_003a_003aStraps"></a>
-<p>Moved from Perl 5.10.1 to CPAN
-</p>
-</dd>
-<dt><code>legacy</code></dt>
-<dd><a name="perlexperiment-legacy"></a>
-<p>The experimental <code>legacy</code> pragma was swallowed by the
<code>feature</code> pragma.
-</p>
-<p>Introduced in: 5.11.2
-</p>
-<p>Removed in: 5.11.3
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlexperiment-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlexperiment-AUTHORS" accesskey="n"
rel="next">perlexperiment AUTHORS</a>, Previous: <a
href="#perlexperiment-DESCRIPTION" accesskey="p" rel="prev">perlexperiment
DESCRIPTION</a>, Up: <a href="#perlexperiment" accesskey="u"
rel="up">perlexperiment</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-13"></a>
-<h3 class="section">21.3 SEE ALSO</h3>
-
-<p>For a complete list of features check <a
href="feature.html#Top">(feature)</a>.
-</p>
-<hr>
-<a name="perlexperiment-AUTHORS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlexperiment-COPYRIGHT" accesskey="n"
rel="next">perlexperiment COPYRIGHT</a>, Previous: <a
href="#perlexperiment-SEE-ALSO" accesskey="p" rel="prev">perlexperiment SEE
ALSO</a>, Up: <a href="#perlexperiment" accesskey="u"
rel="up">perlexperiment</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHORS-1"></a>
-<h3 class="section">21.4 AUTHORS</h3>
-
-<p>brian d foy <code><address@hidden></code>
-</p>
-<p>Sébastien Aperghis-Tramoni <code><address@hidden></code>
-</p>
-<hr>
-<a name="perlexperiment-COPYRIGHT"></a>
-<div class="header">
-<p>
-Next: <a href="#perlexperiment-LICENSE" accesskey="n"
rel="next">perlexperiment LICENSE</a>, Previous: <a
href="#perlexperiment-AUTHORS" accesskey="p" rel="prev">perlexperiment
AUTHORS</a>, Up: <a href="#perlexperiment" accesskey="u"
rel="up">perlexperiment</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="COPYRIGHT-1"></a>
-<h3 class="section">21.5 COPYRIGHT</h3>
-
-<p>Copyright 2010, brian d foy <code><address@hidden></code>
-</p>
-<hr>
-<a name="perlexperiment-LICENSE"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlexperiment-COPYRIGHT" accesskey="p"
rel="prev">perlexperiment COPYRIGHT</a>, Up: <a href="#perlexperiment"
accesskey="u" rel="up">perlexperiment</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="LICENSE"></a>
-<h3 class="section">21.6 LICENSE</h3>
-
-<p>You can use and redistribute this document under the same terms as Perl
-itself.
-</p>
-<hr>
-<a name="perlfilter"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfork" accesskey="n" rel="next">perlfork</a>, Previous: <a
href="#perlexperiment" accesskey="p" rel="prev">perlexperiment</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlfilter-1"></a>
-<h2 class="chapter">22 perlfilter</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlfilter-NAME"
accesskey="1">perlfilter NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfilter-DESCRIPTION"
accesskey="2">perlfilter DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfilter-CONCEPTS"
accesskey="3">perlfilter CONCEPTS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfilter-USING-FILTERS"
accesskey="4">perlfilter USING FILTERS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-WRITING-A-SOURCE-FILTER" accesskey="5">perlfilter WRITING A
SOURCE FILTER</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-WRITING-A-SOURCE-FILTER-IN-C" accesskey="6">perlfilter
WRITING A SOURCE FILTER IN C</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-CREATING-A-SOURCE-FILTER-AS-A-SEPARATE-EXECUTABLE"
accesskey="7">perlfilter CREATING A SOURCE FILTER AS A SEPARATE
EXECUTABLE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-WRITING-A-SOURCE-FILTER-IN-PERL" accesskey="8">perlfilter
WRITING A SOURCE FILTER IN PERL</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-USING-CONTEXT_003a-THE-DEBUG-FILTER" accesskey="9">perlfilter
USING CONTEXT: THE DEBUG FILTER</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-CONCLUSION">perlfilter
CONCLUSION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-LIMITATIONS">perlfilter
LIMITATIONS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-THINGS-TO-LOOK-OUT-FOR">perlfilter THINGS TO LOOK OUT
FOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-REQUIREMENTS">perlfilter
REQUIREMENTS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-AUTHOR">perlfilter AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfilter-Copyrights">perlfilter
Copyrights</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlfilter-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter-DESCRIPTION" accesskey="n" rel="next">perlfilter
DESCRIPTION</a>, Up: <a href="#perlfilter" accesskey="u"
rel="up">perlfilter</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-21"></a>
-<h3 class="section">22.1 NAME</h3>
-
-<p>perlfilter - Source Filters
-</p>
-<hr>
-<a name="perlfilter-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter-CONCEPTS" accesskey="n" rel="next">perlfilter
CONCEPTS</a>, Previous: <a href="#perlfilter-NAME" accesskey="p"
rel="prev">perlfilter NAME</a>, Up: <a href="#perlfilter" accesskey="u"
rel="up">perlfilter</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-21"></a>
-<h3 class="section">22.2 DESCRIPTION</h3>
-
-<p>This article is about a little-known feature of Perl called
-<em>source filters</em>. Source filters alter the program text of a module
-before Perl sees it, much as a C preprocessor alters the source text of
-a C program before the compiler sees it. This article tells you more
-about what source filters are, how they work, and how to write your
-own.
-</p>
-<p>The original purpose of source filters was to let you encrypt your
-program source to prevent casual piracy. This isn’t all they can do, as
-you’ll soon learn. But first, the basics.
-</p>
-<hr>
-<a name="perlfilter-CONCEPTS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter-USING-FILTERS" accesskey="n" rel="next">perlfilter
USING FILTERS</a>, Previous: <a href="#perlfilter-DESCRIPTION" accesskey="p"
rel="prev">perlfilter DESCRIPTION</a>, Up: <a href="#perlfilter" accesskey="u"
rel="up">perlfilter</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="CONCEPTS"></a>
-<h3 class="section">22.3 CONCEPTS</h3>
-
-<p>Before the Perl interpreter can execute a Perl script, it must first
-read it from a file into memory for parsing and compilation. If that
-script itself includes other scripts with a <code>use</code> or
<code>require</code>
-statement, then each of those scripts will have to be read from their
-respective files as well.
-</p>
-<p>Now think of each logical connection between the Perl parser and an
-individual file as a <em>source stream</em>. A source stream is created when
-the Perl parser opens a file, it continues to exist as the source code
-is read into memory, and it is destroyed when Perl is finished parsing
-the file. If the parser encounters a <code>require</code> or <code>use</code>
statement in
-a source stream, a new and distinct stream is created just for that
-file.
-</p>
-<p>The diagram below represents a single source stream, with the flow of
-source from a Perl script file on the left into the Perl parser on the
-right. This is how Perl normally operates.
-</p>
-<pre class="verbatim"> file -------> parser
-</pre>
-<p>There are two important points to remember:
-</p>
-<ol>
-<li> Although there can be any number of source streams in existence at any
-given time, only one will be active.
-
-</li><li> Every source stream is associated with only one file.
-
-</li></ol>
-
-<p>A source filter is a special kind of Perl module that intercepts and
-modifies a source stream before it reaches the parser. A source filter
-changes our diagram like this:
-</p>
-<pre class="verbatim"> file ----> filter ----> parser
-</pre>
-<p>If that doesn’t make much sense, consider the analogy of a command
-pipeline. Say you have a shell script stored in the compressed file
-<em>trial.gz</em>. The simple pipeline command below runs the script without
-needing to create a temporary file to hold the uncompressed file.
-</p>
-<pre class="verbatim"> gunzip -c trial.gz | sh
-</pre>
-<p>In this case, the data flow from the pipeline can be represented as follows:
-</p>
-<pre class="verbatim"> trial.gz ----> gunzip ----> sh
-</pre>
-<p>With source filters, you can store the text of your script compressed and
use a source filter to uncompress it for Perl’s parser:
-</p>
-<pre class="verbatim"> compressed gunzip
- Perl program ---> source filter ---> parser
-</pre>
-<hr>
-<a name="perlfilter-USING-FILTERS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter-WRITING-A-SOURCE-FILTER" accesskey="n"
rel="next">perlfilter WRITING A SOURCE FILTER</a>, Previous: <a
href="#perlfilter-CONCEPTS" accesskey="p" rel="prev">perlfilter CONCEPTS</a>,
Up: <a href="#perlfilter" accesskey="u" rel="up">perlfilter</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="USING-FILTERS"></a>
-<h3 class="section">22.4 USING FILTERS</h3>
-
-<p>So how do you use a source filter in a Perl script? Above, I said that
-a source filter is just a special kind of module. Like all Perl
-modules, a source filter is invoked with a use statement.
-</p>
-<p>Say you want to pass your Perl source through the C preprocessor before
-execution. As it happens, the source filters distribution comes with a C
-preprocessor filter module called Filter::cpp.
-</p>
-<p>Below is an example program, <code>cpp_test</code>, which makes use of this
filter.
-Line numbers have been added to allow specific lines to be referenced
-easily.
-</p>
-<pre class="verbatim"> 1: use Filter::cpp;
- 2: #define TRUE 1
- 3: $a = TRUE;
- 4: print "a = $a\n";
-</pre>
-<p>When you execute this script, Perl creates a source stream for the
-file. Before the parser processes any of the lines from the file, the
-source stream looks like this:
-</p>
-<pre class="verbatim"> cpp_test ---------> parser
-</pre>
-<p>Line 1, <code>use Filter::cpp</code>, includes and installs the
<code>cpp</code> filter
-module. All source filters work this way. The use statement is compiled
-and executed at compile time, before any more of the file is read, and
-it attaches the cpp filter to the source stream behind the scenes. Now
-the data flow looks like this:
-</p>
-<pre class="verbatim"> cpp_test ----> cpp filter ----> parser
-</pre>
-<p>As the parser reads the second and subsequent lines from the source
-stream, it feeds those lines through the <code>cpp</code> source filter before
-processing them. The <code>cpp</code> filter simply passes each line through
the
-real C preprocessor. The output from the C preprocessor is then
-inserted back into the source stream by the filter.
-</p>
-<pre class="verbatim"> .-> cpp --.
- | |
- | |
- | <-'
- cpp_test ----> cpp filter ----> parser
-</pre>
-<p>The parser then sees the following code:
-</p>
-<pre class="verbatim"> use Filter::cpp;
- $a = 1;
- print "a = $a\n";
-</pre>
-<p>Let’s consider what happens when the filtered code includes another
-module with use:
-</p>
-<pre class="verbatim"> 1: use Filter::cpp;
- 2: #define TRUE 1
- 3: use Fred;
- 4: $a = TRUE;
- 5: print "a = $a\n";
-</pre>
-<p>The <code>cpp</code> filter does not apply to the text of the Fred module,
only
-to the text of the file that used it (<code>cpp_test</code>). Although the use
-statement on line 3 will pass through the cpp filter, the module that
-gets included (<code>Fred</code>) will not. The source streams look like this
-after line 3 has been parsed and before line 4 is parsed:
-</p>
-<pre class="verbatim"> cpp_test ---> cpp filter ---> parser (INACTIVE)
-
- Fred.pm ----> parser
-</pre>
-<p>As you can see, a new stream has been created for reading the source
-from <code>Fred.pm</code>. This stream will remain active until all of
<code>Fred.pm</code>
-has been parsed. The source stream for <code>cpp_test</code> will still exist,
-but is inactive. Once the parser has finished reading Fred.pm, the
-source stream associated with it will be destroyed. The source stream
-for <code>cpp_test</code> then becomes active again and the parser reads line 4
-and subsequent lines from <code>cpp_test</code>.
-</p>
-<p>You can use more than one source filter on a single file. Similarly,
-you can reuse the same filter in as many files as you like.
-</p>
-<p>For example, if you have a uuencoded and compressed source file, it is
-possible to stack a uudecode filter and an uncompression filter like
-this:
-</p>
-<pre class="verbatim"> use Filter::uudecode; use Filter::uncompress;
-
M'XL(".H<US4''V9I;F%L')Q;>7/;1I;_>_I3=&E=%:F*I"T?22Q/
- M6]9*<IQCO*XFT"0[PL%%'Y+IG?WN^ZYN-$'J.[.JE$,20/?K=_[>
- ...
-</pre>
-<p>Once the first line has been processed, the flow will look like this:
-</p>
-<pre class="verbatim"> file ---> uudecode ---> uncompress --->
parser
- filter filter
-</pre>
-<p>Data flows through filters in the same order they appear in the source
-file. The uudecode filter appeared before the uncompress filter, so the
-source file will be uudecoded before it’s uncompressed.
-</p>
-<hr>
-<a name="perlfilter-WRITING-A-SOURCE-FILTER"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter-WRITING-A-SOURCE-FILTER-IN-C" accesskey="n"
rel="next">perlfilter WRITING A SOURCE FILTER IN C</a>, Previous: <a
href="#perlfilter-USING-FILTERS" accesskey="p" rel="prev">perlfilter USING
FILTERS</a>, Up: <a href="#perlfilter" accesskey="u" rel="up">perlfilter</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="WRITING-A-SOURCE-FILTER"></a>
-<h3 class="section">22.5 WRITING A SOURCE FILTER</h3>
-
-<p>There are three ways to write your own source filter. You can write it
-in C, use an external program as a filter, or write the filter in Perl.
-I won’t cover the first two in any great detail, so I’ll get them
out
-of the way first. Writing the filter in Perl is most convenient, so
-I’ll devote the most space to it.
-</p>
-<hr>
-<a name="perlfilter-WRITING-A-SOURCE-FILTER-IN-C"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter-CREATING-A-SOURCE-FILTER-AS-A-SEPARATE-EXECUTABLE"
accesskey="n" rel="next">perlfilter CREATING A SOURCE FILTER AS A SEPARATE
EXECUTABLE</a>, Previous: <a href="#perlfilter-WRITING-A-SOURCE-FILTER"
accesskey="p" rel="prev">perlfilter WRITING A SOURCE FILTER</a>, Up: <a
href="#perlfilter" accesskey="u" rel="up">perlfilter</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="WRITING-A-SOURCE-FILTER-IN-C"></a>
-<h3 class="section">22.6 WRITING A SOURCE FILTER IN C</h3>
-
-<p>The first of the three available techniques is to write the filter
-completely in C. The external module you create interfaces directly
-with the source filter hooks provided by Perl.
-</p>
-<p>The advantage of this technique is that you have complete control over
-the implementation of your filter. The big disadvantage is the
-increased complexity required to write the filter - not only do you
-need to understand the source filter hooks, but you also need a
-reasonable knowledge of Perl guts. One of the few times it is worth
-going to this trouble is when writing a source scrambler. The
-<code>decrypt</code> filter (which unscrambles the source before Perl parses
it)
-included with the source filter distribution is an example of a C
-source filter (see Decryption Filters, below).
-</p>
-<dl compact="compact">
-<dt><strong>Decryption Filters</strong></dt>
-<dd><a name="perlfilter-Decryption-Filters"></a>
-<p>All decryption filters work on the principle of "security through
-obscurity." Regardless of how well you write a decryption filter and
-how strong your encryption algorithm is, anyone determined enough can
-retrieve the original source code. The reason is quite simple - once
-the decryption filter has decrypted the source back to its original
-form, fragments of it will be stored in the computer’s memory as Perl
-parses it. The source might only be in memory for a short period of
-time, but anyone possessing a debugger, skill, and lots of patience can
-eventually reconstruct your program.
-</p>
-<p>That said, there are a number of steps that can be taken to make life
-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 <em>decrypt.pm</em> in the source filters
-distribution.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlfilter-CREATING-A-SOURCE-FILTER-AS-A-SEPARATE-EXECUTABLE"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter-WRITING-A-SOURCE-FILTER-IN-PERL" accesskey="n"
rel="next">perlfilter WRITING A SOURCE FILTER IN PERL</a>, Previous: <a
href="#perlfilter-WRITING-A-SOURCE-FILTER-IN-C" accesskey="p"
rel="prev">perlfilter WRITING A SOURCE FILTER IN C</a>, Up: <a
href="#perlfilter" accesskey="u" rel="up">perlfilter</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="CREATING-A-SOURCE-FILTER-AS-A-SEPARATE-EXECUTABLE"></a>
-<h3 class="section">22.7 CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE</h3>
-
-<p>An alternative to writing the filter in C is to create a separate
-executable in the language of your choice. The separate executable
-reads from standard input, does whatever processing is necessary, and
-writes the filtered data to standard output. <code>Filter::cpp</code> is an
-example of a source filter implemented as a separate executable - the
-executable is the C preprocessor bundled with your C compiler.
-</p>
-<p>The source filter distribution includes two modules that simplify this
-task: <code>Filter::exec</code> and <code>Filter::sh</code>. 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."
-Addison-Wesley, ISBN 0-210-56317-7, pages 441-445.) The difference
-between them is that <code>Filter::exec</code> spawns the external command
-directly, while <code>Filter::sh</code> spawns a shell to execute the external
-command. (Unix uses the Bourne shell; NT uses the cmd shell.) Spawning
-a shell allows you to make use of the shell metacharacters and
-redirection facilities.
-</p>
-<p>Here is an example script that uses <code>Filter::sh</code>:
-</p>
-<pre class="verbatim"> use Filter::sh 'tr XYZ PQR';
- $a = 1;
- print "XYZ a = $a\n";
-</pre>
-<p>The output you’ll get when the script is executed:
-</p>
-<pre class="verbatim"> PQR a = 1
-</pre>
-<p>Writing a source filter as a separate executable works fine, but a
-small performance penalty is incurred. For example, if you execute the
-small example above, a separate subprocess will be created to run the
-Unix <code>tr</code> command. Each use of the filter requires its own
subprocess.
-If creating subprocesses is expensive on your system, you might want to
-consider one of the other options for creating source filters.
-</p>
-<hr>
-<a name="perlfilter-WRITING-A-SOURCE-FILTER-IN-PERL"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter-USING-CONTEXT_003a-THE-DEBUG-FILTER" accesskey="n"
rel="next">perlfilter USING CONTEXT: THE DEBUG FILTER</a>, Previous: <a
href="#perlfilter-CREATING-A-SOURCE-FILTER-AS-A-SEPARATE-EXECUTABLE"
accesskey="p" rel="prev">perlfilter CREATING A SOURCE FILTER AS A SEPARATE
EXECUTABLE</a>, Up: <a href="#perlfilter" accesskey="u" rel="up">perlfilter</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="WRITING-A-SOURCE-FILTER-IN-PERL"></a>
-<h3 class="section">22.8 WRITING A SOURCE FILTER IN PERL</h3>
-
-<p>The easiest and most portable option available for creating your own
-source filter is to write it completely in Perl. To distinguish this
-from the previous two techniques, I’ll call it a Perl source filter.
-</p>
-<p>To help understand how to write a Perl source filter we need an example
-to study. Here is a complete source filter that performs rot13
-decoding. (Rot13 is a very simple encryption scheme used in Usenet
-postings to hide the contents of offensive posts. It moves every letter
-forward thirteen places, so that A becomes N, B becomes O, and Z
-becomes M.)
-</p>
-<pre class="verbatim"> package Rot13;
-
- use Filter::Util::Call;
-
- sub import {
- my ($type) = @_;
- my ($ref) = [];
- filter_add(bless $ref);
- }
-
- sub filter {
- my ($self) = @_;
- my ($status);
-
- tr/n-za-mN-ZA-M/a-zA-Z/
- if ($status = filter_read()) > 0;
- $status;
- }
-
- 1;
-</pre>
-<p>All Perl source filters are implemented as Perl classes and have the
-same basic structure as the example above.
-</p>
-<p>First, we include the <code>Filter::Util::Call</code> module, which exports
a
-number of functions into your filter’s namespace. The filter shown
-above uses two of these functions, <code>filter_add()</code> and
-<code>filter_read()</code>.
-</p>
-<p>Next, we create the filter object and associate it with the source
-stream by defining the <code>import</code> function. If you know Perl well
-enough, you know that <code>import</code> is called automatically every time a
-module is included with a use statement. This makes <code>import</code> the
ideal
-place to both create and install a filter object.
-</p>
-<p>In the example filter, the object (<code>$ref</code>) is blessed just like
any
-other Perl object. Our example uses an anonymous array, but this isn’t
-a requirement. Because this example doesn’t need to store any context
-information, we could have used a scalar or hash reference just as
-well. The next section demonstrates context data.
-</p>
-<p>The association between the filter object and the source stream is made
-with the <code>filter_add()</code> function. This takes a filter object as a
-parameter (<code>$ref</code> in this case) and installs it in the source
stream.
-</p>
-<p>Finally, there is the code that actually does the filtering. For this
-type of Perl source filter, all the filtering is done in a method
-called <code>filter()</code>. (It is also possible to write a Perl source
filter
-using a closure. See the <code>Filter::Util::Call</code> manual page for more
-details.) It’s called every time the Perl parser needs another line of
-source to process. The <code>filter()</code> method, in turn, reads lines from
-the source stream using the <code>filter_read()</code> function.
-</p>
-<p>If a line was available from the source stream, <code>filter_read()</code>
-returns a status value greater than zero and appends the line to
<code>$_</code>.
-A status value of zero indicates end-of-file, less than zero means an
-error. The filter function itself is expected to return its status in
-the same way, and put the filtered line it wants written to the source
-stream in <code>$_</code>. The use of <code>$_</code> accounts for the brevity
of most Perl
-source filters.
-</p>
-<p>In order to make use of the rot13 filter we need some way of encoding
-the source file in rot13 format. The script below, <code>mkrot13</code>, does
-just that.
-</p>
-<pre class="verbatim"> die "usage mkrot13 filename\n" unless
@ARGV;
- my $in = $ARGV[0];
- my $out = "$in.tmp";
- open(IN, "<$in") or die "Cannot open file $in:
$!\n";
- open(OUT, ">$out") or die "Cannot open file $out:
$!\n";
-
- print OUT "use Rot13;\n";
- while (<IN>) {
- tr/a-zA-Z/n-za-mN-ZA-M/;
- print OUT;
- }
-
- close IN;
- close OUT;
- unlink $in;
- rename $out, $in;
-</pre>
-<p>If we encrypt this with <code>mkrot13</code>:
-</p>
-<pre class="verbatim"> print " hello fred \n";
-</pre>
-<p>the result will be this:
-</p>
-<pre class="verbatim"> use Rot13;
- cevag "uryyb serq\a";
-</pre>
-<p>Running it produces this output:
-</p>
-<pre class="verbatim"> hello fred
-</pre>
-<hr>
-<a name="perlfilter-USING-CONTEXT_003a-THE-DEBUG-FILTER"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter-CONCLUSION" accesskey="n" rel="next">perlfilter
CONCLUSION</a>, Previous: <a href="#perlfilter-WRITING-A-SOURCE-FILTER-IN-PERL"
accesskey="p" rel="prev">perlfilter WRITING A SOURCE FILTER IN PERL</a>, Up: <a
href="#perlfilter" accesskey="u" rel="up">perlfilter</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="USING-CONTEXT_003a-THE-DEBUG-FILTER"></a>
-<h3 class="section">22.9 USING CONTEXT: THE DEBUG FILTER</h3>
-
-<p>The rot13 example was a trivial example. Here’s another demonstration
-that shows off a few more features.
-</p>
-<p>Say you wanted to include a lot of debugging code in your Perl script
-during development, but you didn’t want it available in the released
-product. Source filters offer a solution. In order to keep the example
-simple, let’s say you wanted the debugging output to be controlled by
-an environment variable, <code>DEBUG</code>. Debugging code is enabled if the
-variable exists, otherwise it is disabled.
-</p>
-<p>Two special marker lines will bracket debugging code, like this:
-</p>
-<pre class="verbatim"> ## DEBUG_BEGIN
- if ($year > 1999) {
- warn "Debug: millennium bug in year $year\n";
- }
- ## DEBUG_END
-</pre>
-<p>The filter ensures that Perl parses the code between the <DEBUG_BEGIN>
-and <code>DEBUG_END</code> markers only when the <code>DEBUG</code>
environment variable
-exists. That means that when <code>DEBUG</code> 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 <code>DEBUG</code> isn’t set, we need a way to
disable the
-debug code. A simple way to achieve that is to convert the lines
-between the two markers into comments:
-</p>
-<pre class="verbatim"> ## DEBUG_BEGIN
- #if ($year > 1999) {
- # warn "Debug: millennium bug in year $year\n";
- #}
- ## DEBUG_END
-</pre>
-<p>Here is the complete Debug filter:
-</p>
-<pre class="verbatim"> package Debug;
-
- use strict;
- use warnings;
- use Filter::Util::Call;
-
- use constant TRUE => 1;
- use constant FALSE => 0;
-
- sub import {
- my ($type) = @_;
- my (%context) = (
- Enabled => defined $ENV{DEBUG},
- InTraceBlock => FALSE,
- Filename => (caller)[1],
- LineNo => 0,
- LastBegin => 0,
- );
- filter_add(bless \%context);
- }
-
- sub Die {
- my ($self) = shift;
- my ($message) = shift;
- my ($line_no) = shift || $self->{LastBegin};
- die "$message at $self->{Filename} line $line_no.\n"
- }
-
- sub filter {
- my ($self) = @_;
- my ($status);
- $status = filter_read();
- ++ $self->{LineNo};
-
- # deal with EOF/error first
- if ($status <= 0) {
- $self->Die("DEBUG_BEGIN has no DEBUG_END")
- if $self->{InTraceBlock};
- return $status;
- }
-
- if ($self->{InTraceBlock}) {
- if (/^\s*##\s*DEBUG_BEGIN/ ) {
- $self->Die("Nested DEBUG_BEGIN", $self->{LineNo})
- } elsif (/^\s*##\s*DEBUG_END/) {
- $self->{InTraceBlock} = FALSE;
- }
-
- # comment out the debug lines when the filter is disabled
- s/^/#/ if ! $self->{Enabled};
- } elsif ( /^\s*##\s*DEBUG_BEGIN/ ) {
- $self->{InTraceBlock} = TRUE;
- $self->{LastBegin} = $self->{LineNo};
- } elsif ( /^\s*##\s*DEBUG_END/ ) {
- $self->Die("DEBUG_END has no DEBUG_BEGIN",
$self->{LineNo});
- }
- return $status;
- }
-
- 1;
-</pre>
-<p>The big difference between this filter and the previous example is the
-use of context data in the filter object. The filter object is based on
-a hash reference, and is used to keep various pieces of context
-information between calls to the filter function. All but two of the
-hash fields are used for error reporting. The first of those two,
-Enabled, is used by the filter to determine whether the debugging code
-should be given to the Perl parser. The second, InTraceBlock, is true
-when the filter has encountered a <code>DEBUG_BEGIN</code> line, but has not
yet
-encountered the following <code>DEBUG_END</code> line.
-</p>
-<p>If you ignore all the error checking that most of the code does, the
-essence of the filter is as follows:
-</p>
-<pre class="verbatim"> sub filter {
- my ($self) = @_;
- my ($status);
- $status = filter_read();
-
- # deal with EOF/error first
- return $status if $status <= 0;
- if ($self->{InTraceBlock}) {
- if (/^\s*##\s*DEBUG_END/) {
- $self->{InTraceBlock} = FALSE
- }
-
- # comment out debug lines when the filter is disabled
- s/^/#/ if ! $self->{Enabled};
- } elsif ( /^\s*##\s*DEBUG_BEGIN/ ) {
- $self->{InTraceBlock} = TRUE;
- }
- return $status;
- }
-</pre>
-<p>Be warned: just as the C-preprocessor doesn’t know C, the Debug filter
-doesn’t know Perl. It can be fooled quite easily:
-</p>
-<pre class="verbatim"> print <<EOM;
- ##DEBUG_BEGIN
- EOM
-</pre>
-<p>Such things aside, you can see that a lot can be achieved with a modest
-amount of code.
-</p>
-<hr>
-<a name="perlfilter-CONCLUSION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter-LIMITATIONS" accesskey="n" rel="next">perlfilter
LIMITATIONS</a>, Previous: <a
href="#perlfilter-USING-CONTEXT_003a-THE-DEBUG-FILTER" accesskey="p"
rel="prev">perlfilter USING CONTEXT: THE DEBUG FILTER</a>, Up: <a
href="#perlfilter" accesskey="u" rel="up">perlfilter</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="CONCLUSION"></a>
-<h3 class="section">22.10 CONCLUSION</h3>
-
-<p>You now have better understanding of what a source filter is, and you
-might even have a possible use for them. If you feel like playing with
-source filters but need a bit of inspiration, here are some extra
-features you could add to the Debug filter.
-</p>
-<p>First, an easy one. Rather than having debugging code that is
-all-or-nothing, it would be much more useful to be able to control
-which specific blocks of debugging code get included. Try extending the
-syntax for debug blocks to allow each to be identified. The contents of
-the <code>DEBUG</code> environment variable can then be used to control which
-blocks get included.
-</p>
-<p>Once you can identify individual blocks, try allowing them to be
-nested. That isn’t difficult either.
-</p>
-<p>Here is an interesting idea that doesn’t involve the Debug filter.
-Currently Perl subroutines have fairly limited support for formal
-parameter lists. You can specify the number of parameters and their
-type, but you still have to manually take them out of the <code>@_</code> array
-yourself. Write a source filter that allows you to have a named
-parameter list. Such a filter would turn this:
-</p>
-<pre class="verbatim"> sub MySub ($first, $second, @rest) { ... }
-</pre>
-<p>into this:
-</p>
-<pre class="verbatim"> sub MySub($$@) {
- my ($first) = shift;
- my ($second) = shift;
- my (@rest) = @_;
- ...
- }
-</pre>
-<p>Finally, if you feel like a real challenge, have a go at writing a
-full-blown Perl macro preprocessor as a source filter. Borrow the
-useful features from the C preprocessor and any other macro processors
-you know. The tricky bit will be choosing how much knowledge of Perl’s
-syntax you want your filter to have.
-</p>
-<hr>
-<a name="perlfilter-LIMITATIONS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter-THINGS-TO-LOOK-OUT-FOR" accesskey="n"
rel="next">perlfilter THINGS TO LOOK OUT FOR</a>, Previous: <a
href="#perlfilter-CONCLUSION" accesskey="p" rel="prev">perlfilter
CONCLUSION</a>, Up: <a href="#perlfilter" accesskey="u" rel="up">perlfilter</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="LIMITATIONS"></a>
-<h3 class="section">22.11 LIMITATIONS</h3>
-
-<p>Source filters only work on the string level, thus are highly limited
-in its ability to change source code on the fly. It cannot detect
-comments, quoted strings, heredocs, it is no replacement for a real
-parser.
-The only stable usage for source filters are encryption, compression,
-or the byteloader, to translate binary code back to source code.
-</p>
-<p>See for example the limitations in Switch, which uses source filters,
-and thus is does not work inside a string eval, the presence of
-regexes with embedded newlines that are specified with raw /.../
-delimiters and don’t have a modifier //x are indistinguishable from
-code chunks beginning with the division operator /. As a workaround
-you must use m/.../ or m?...? for such patterns. Also, the presence of
-regexes specified with raw ?...? delimiters may cause mysterious
-errors. The workaround is to use m?...? instead. See
-http://search.cpan.org/perldoc?Switch#LIMITATIONS
-</p>
-<p>Currently internal buffer lengths are limited to 32-bit only.
-</p>
-<hr>
-<a name="perlfilter-THINGS-TO-LOOK-OUT-FOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter-REQUIREMENTS" accesskey="n" rel="next">perlfilter
REQUIREMENTS</a>, Previous: <a href="#perlfilter-LIMITATIONS" accesskey="p"
rel="prev">perlfilter LIMITATIONS</a>, Up: <a href="#perlfilter" accesskey="u"
rel="up">perlfilter</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="THINGS-TO-LOOK-OUT-FOR"></a>
-<h3 class="section">22.12 THINGS TO LOOK OUT FOR</h3>
-
-<dl compact="compact">
-<dt>Some Filters Clobber the <code>DATA</code> Handle</dt>
-<dd><a name="perlfilter-Some-Filters-Clobber-the-DATA-Handle"></a>
-<p>Some source filters use the <code>DATA</code> handle to read the calling
program.
-When using these source filters you cannot rely on this handle, nor expect
-any particular kind of behavior when operating on it. Filters based on
-Filter::Util::Call (and therefore Filter::Simple) do not alter the
<code>DATA</code>
-filehandle.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlfilter-REQUIREMENTS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter-AUTHOR" accesskey="n" rel="next">perlfilter
AUTHOR</a>, Previous: <a href="#perlfilter-THINGS-TO-LOOK-OUT-FOR"
accesskey="p" rel="prev">perlfilter THINGS TO LOOK OUT FOR</a>, Up: <a
href="#perlfilter" accesskey="u" rel="up">perlfilter</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="REQUIREMENTS"></a>
-<h3 class="section">22.13 REQUIREMENTS</h3>
-
-<p>The Source Filters distribution is available on CPAN, in
-</p>
-<pre class="verbatim"> CPAN/modules/by-module/Filter
-</pre>
-<p>Starting from Perl 5.8 Filter::Util::Call (the core part of the
-Source Filters distribution) is part of the standard Perl distribution.
-Also included is a friendlier interface called Filter::Simple, by
-Damian Conway.
-</p>
-<hr>
-<a name="perlfilter-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfilter-Copyrights" accesskey="n" rel="next">perlfilter
Copyrights</a>, Previous: <a href="#perlfilter-REQUIREMENTS" accesskey="p"
rel="prev">perlfilter REQUIREMENTS</a>, Up: <a href="#perlfilter" accesskey="u"
rel="up">perlfilter</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-9"></a>
-<h3 class="section">22.14 AUTHOR</h3>
-
-<p>Paul Marquess <address@hidden>
-</p>
-<hr>
-<a name="perlfilter-Copyrights"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlfilter-AUTHOR" accesskey="p" rel="prev">perlfilter
AUTHOR</a>, Up: <a href="#perlfilter" accesskey="u" rel="up">perlfilter</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Copyrights"></a>
-<h3 class="section">22.15 Copyrights</h3>
-
-<p>This article originally appeared in The Perl Journal #11, and is
-copyright 1998 The Perl Journal. It appears courtesy of Jon Orwant and
-The Perl Journal. This document may be distributed under the same terms
-as Perl itself.
-</p>
-<hr>
-<a name="perlfork"></a>
-<div class="header">
-<p>
-Next: <a href="#perlform" accesskey="n" rel="next">perlform</a>, Previous: <a
href="#perlfilter" accesskey="p" rel="prev">perlfilter</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlfork-1"></a>
-<h2 class="chapter">23 perlfork</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlfork-NAME"
accesskey="1">perlfork NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfork-SYNOPSIS"
accesskey="2">perlfork SYNOPSIS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfork-DESCRIPTION"
accesskey="3">perlfork DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfork-CAVEATS-AND-LIMITATIONS" accesskey="4">perlfork CAVEATS AND
LIMITATIONS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfork-PORTABILITY-CAVEATS" accesskey="5">perlfork PORTABILITY
CAVEATS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfork-BUGS"
accesskey="6">perlfork BUGS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfork-AUTHOR"
accesskey="7">perlfork AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfork-SEE-ALSO"
accesskey="8">perlfork SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlfork-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfork-SYNOPSIS" accesskey="n" rel="next">perlfork
SYNOPSIS</a>, Up: <a href="#perlfork" accesskey="u" rel="up">perlfork</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-22"></a>
-<h3 class="section">23.1 NAME</h3>
-
-<p>perlfork - Perl’s fork() emulation
-</p>
-<hr>
-<a name="perlfork-SYNOPSIS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfork-DESCRIPTION" accesskey="n" rel="next">perlfork
DESCRIPTION</a>, Previous: <a href="#perlfork-NAME" accesskey="p"
rel="prev">perlfork NAME</a>, Up: <a href="#perlfork" accesskey="u"
rel="up">perlfork</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SYNOPSIS-5"></a>
-<h3 class="section">23.2 SYNOPSIS</h3>
-
-<pre class="verbatim"> NOTE: As of the 5.8.0 release, fork() emulation has
considerably
- matured. However, there are still a few known bugs and differences
- from real fork() that might affect you. See the "BUGS" and
- "CAVEATS AND LIMITATIONS" sections below.
-</pre>
-<p>Perl provides a fork() keyword that corresponds to the Unix system call
-of the same name. On most Unix-like platforms where the fork() system
-call is available, Perl’s fork() simply calls it.
-</p>
-<p>On some platforms such as Windows where the fork() system call is not
-available, Perl can be built to emulate fork() at the interpreter level.
-While the emulation is designed to be as compatible as possible with the
-real fork() at the level of the Perl program, there are certain
-important differences that stem from the fact that all the pseudo child
-"processes" created this way live in the same real process as far as
the
-operating system is concerned.
-</p>
-<p>This document provides a general overview of the capabilities and
-limitations of the fork() emulation. Note that the issues discussed here
-are not applicable to platforms where a real fork() is available and Perl
-has been configured to use it.
-</p>
-<hr>
-<a name="perlfork-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfork-CAVEATS-AND-LIMITATIONS" accesskey="n"
rel="next">perlfork CAVEATS AND LIMITATIONS</a>, Previous: <a
href="#perlfork-SYNOPSIS" accesskey="p" rel="prev">perlfork SYNOPSIS</a>, Up:
<a href="#perlfork" accesskey="u" rel="up">perlfork</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-22"></a>
-<h3 class="section">23.3 DESCRIPTION</h3>
-
-<p>The fork() emulation is implemented at the level of the Perl interpreter.
-What this means in general is that running fork() will actually clone the
-running interpreter and all its state, and run the cloned interpreter in
-a separate thread, beginning execution in the new thread just after the
-point where the fork() was called in the parent. We will refer to the
-thread that implements this child "process" as the pseudo-process.
-</p>
-<p>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;
-the child returns from the fork() with a value of <code>0</code> to signify
that
-it is the child pseudo-process.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlfork-Behavior-of-other-Perl-features-in-forked-pseudo_002dprocesses"
accesskey="1">perlfork Behavior of other Perl features in forked
pseudo-processes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfork-Resource-limits"
accesskey="2">perlfork Resource limits</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfork-Killing-the-parent-process" accesskey="3">perlfork Killing the
parent process</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfork-Lifetime-of-the-parent-process-and-pseudo_002dprocesses"
accesskey="4">perlfork Lifetime of the parent process and
pseudo-processes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a
name="perlfork-Behavior-of-other-Perl-features-in-forked-pseudo_002dprocesses"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfork-Resource-limits" accesskey="n" rel="next">perlfork
Resource limits</a>, Up: <a href="#perlfork-DESCRIPTION" accesskey="u"
rel="up">perlfork DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Behavior-of-other-Perl-features-in-forked-pseudo_002dprocesses"></a>
-<h4 class="subsection">23.3.1 Behavior of other Perl features in forked
pseudo-processes</h4>
-
-<p>Most Perl features behave in a natural way within pseudo-processes.
-</p>
-<dl compact="compact">
-<dt>$$ or $PROCESS_ID</dt>
-<dd><a name="perlfork-_0024_0024-or-_0024PROCESS_005fID"></a>
-<p>This special variable is correctly set to the pseudo-process ID.
-It can be used to identify pseudo-processes within a particular
-session. Note that this value is subject to recycling if any
-pseudo-processes are launched after others have been wait()-ed on.
-</p>
-</dd>
-<dt>%ENV</dt>
-<dd><a name="perlfork-_0025ENV"></a>
-<p>Each pseudo-process maintains its own virtual environment. Modifications
-to %ENV affect the virtual environment, and are only visible within that
-pseudo-process, and in any processes (or pseudo-processes) launched from
-it.
-</p>
-</dd>
-<dt>chdir() and all other builtins that accept filenames</dt>
-<dd><a
name="perlfork-chdir_0028_0029-and-all-other-builtins-that-accept-filenames"></a>
-<p>Each pseudo-process maintains its own virtual idea of the current directory.
-Modifications to the current directory using chdir() are only visible within
-that pseudo-process, and in any processes (or pseudo-processes) launched from
-it. All file and directory accesses from the pseudo-process will correctly
-map the virtual working directory to the real working directory appropriately.
-</p>
-</dd>
-<dt>wait() and waitpid()</dt>
-<dd><a name="perlfork-wait_0028_0029-and-waitpid_0028_0029"></a>
-<p>wait() and waitpid() can be passed a pseudo-process ID returned by fork().
-These calls will properly wait for the termination of the pseudo-process
-and return its status.
-</p>
-</dd>
-<dt>kill()</dt>
-<dd><a name="perlfork-kill_0028_0029"></a>
-<p><code>kill('KILL', ...)</code> can be used to terminate a pseudo-process by
-passing it the ID returned by fork(). The outcome of kill on a pseudo-process
-is unpredictable and it should not be used except
-under dire circumstances, because the operating system may not
-guarantee integrity of the process resources when a running thread is
-terminated. The process which implements the pseudo-processes can be blocked
-and the Perl interpreter hangs. Note that using <code>kill('KILL', ...)</code>
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.
-</p>
-<p><code>kill('TERM', ...)</code> 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 <code>kill('TERM', ...)</code> 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.
-</p>
-</dd>
-<dt>exec()</dt>
-<dd><a name="perlfork-exec_0028_0029"></a>
-<p>Calling exec() within a pseudo-process actually spawns the requested
-executable in a separate process and waits for it to complete before
-exiting with the same exit status as that process. This means that the
-process ID reported within the running executable will be different from
-what the earlier Perl fork() might have returned. Similarly, any process
-manipulation functions applied to the ID returned by fork() will affect the
-waiting pseudo-process that called exec(), not the real process it is
-waiting for after the exec().
-</p>
-<p>When exec() is called inside a pseudo-process then DESTROY methods and
-END blocks will still be called after the external process returns.
-</p>
-</dd>
-<dt>exit()</dt>
-<dd><a name="perlfork-exit_0028_0029"></a>
-<p>exit() always exits just the executing pseudo-process, after automatically
-wait()-ing for any outstanding child pseudo-processes. Note that this means
-that the process as a whole will not exit unless all running pseudo-processes
-have exited. See below for some limitations with open filehandles.
-</p>
-</dd>
-<dt>Open handles to files, directories and network sockets</dt>
-<dd><a
name="perlfork-Open-handles-to-files_002c-directories-and-network-sockets"></a>
-<p>All open handles are dup()-ed in pseudo-processes, so that closing
-any handles in one process does not affect the others. See below for
-some limitations.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlfork-Resource-limits"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfork-Killing-the-parent-process" accesskey="n"
rel="next">perlfork Killing the parent process</a>, Previous: <a
href="#perlfork-Behavior-of-other-Perl-features-in-forked-pseudo_002dprocesses"
accesskey="p" rel="prev">perlfork Behavior of other Perl features in forked
pseudo-processes</a>, Up: <a href="#perlfork-DESCRIPTION" accesskey="u"
rel="up">perlfork DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Resource-limits"></a>
-<h4 class="subsection">23.3.2 Resource limits</h4>
-
-<p>In the eyes of the operating system, pseudo-processes created via the fork()
-emulation are simply threads in the same process. This means that any
-process-level limits imposed by the operating system apply to all
-pseudo-processes taken together. This includes any limits imposed by the
-operating system on the number of open file, directory and socket handles,
-limits on disk space usage, limits on memory size, limits on CPU utilization
-etc.
-</p>
-<hr>
-<a name="perlfork-Killing-the-parent-process"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlfork-Lifetime-of-the-parent-process-and-pseudo_002dprocesses"
accesskey="n" rel="next">perlfork Lifetime of the parent process and
pseudo-processes</a>, Previous: <a href="#perlfork-Resource-limits"
accesskey="p" rel="prev">perlfork Resource limits</a>, Up: <a
href="#perlfork-DESCRIPTION" accesskey="u" rel="up">perlfork DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Killing-the-parent-process"></a>
-<h4 class="subsection">23.3.3 Killing the parent process</h4>
-
-<p>If the parent process is killed (either using Perl’s kill() builtin,
or
-using some external means) all the pseudo-processes are killed as well,
-and the whole process exits.
-</p>
-<hr>
-<a name="perlfork-Lifetime-of-the-parent-process-and-pseudo_002dprocesses"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlfork-Killing-the-parent-process" accesskey="p"
rel="prev">perlfork Killing the parent process</a>, Up: <a
href="#perlfork-DESCRIPTION" accesskey="u" rel="up">perlfork DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Lifetime-of-the-parent-process-and-pseudo_002dprocesses"></a>
-<h4 class="subsection">23.3.4 Lifetime of the parent process and
pseudo-processes</h4>
-
-<p>During the normal course of events, the parent process and every
-pseudo-process started by it will wait for their respective pseudo-children
-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.
-</p>
-<p>Starting with Perl 5.14 a parent will not wait() automatically
-for any child that has been signalled with <code>kill('TERM', ...)</code>
-to avoid a deadlock in case the child is blocking on I/O and
-never receives the signal.
-</p>
-<hr>
-<a name="perlfork-CAVEATS-AND-LIMITATIONS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfork-PORTABILITY-CAVEATS" accesskey="n"
rel="next">perlfork PORTABILITY CAVEATS</a>, Previous: <a
href="#perlfork-DESCRIPTION" accesskey="p" rel="prev">perlfork DESCRIPTION</a>,
Up: <a href="#perlfork" accesskey="u" rel="up">perlfork</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="CAVEATS-AND-LIMITATIONS"></a>
-<h3 class="section">23.4 CAVEATS AND LIMITATIONS</h3>
-
-<dl compact="compact">
-<dt>BEGIN blocks</dt>
-<dd><a name="perlfork-BEGIN-blocks"></a>
-<p>The fork() emulation will not work entirely correctly when called from
-within a BEGIN block. The forked copy will run the contents of the
-BEGIN block, but will not continue parsing the source stream after the
-BEGIN block. For example, consider the following code:
-</p>
-<pre class="verbatim"> BEGIN {
- fork and exit; # fork child and exit the parent
- print "inner\n";
- }
- print "outer\n";
-</pre>
-<p>This will print:
-</p>
-<pre class="verbatim"> inner
-</pre>
-<p>rather than the expected:
-</p>
-<pre class="verbatim"> inner
- outer
-</pre>
-<p>This limitation arises from fundamental technical difficulties in
-cloning and restarting the stacks used by the Perl parser in the
-middle of a parse.
-</p>
-</dd>
-<dt>Open filehandles</dt>
-<dd><a name="perlfork-Open-filehandles"></a>
-<p>Any filehandles open at the time of the fork() will be dup()-ed. Thus,
-the files can be closed independently in the parent and child, but beware
-that the dup()-ed handles will still share the same seek pointer. Changing
-the seek position in the parent will change it in the child and vice-versa.
-One can avoid this by opening files that need distinct seek pointers
-separately in the child.
-</p>
-<p>On some operating systems, notably Solaris and Unixware, calling
<code>exit()</code>
-from a child process will flush and close open filehandles in the parent,
-thereby corrupting the filehandles. On these systems, calling
<code>_exit()</code>
-is suggested instead. <code>_exit()</code> is available in Perl through the
-<code>POSIX</code> module. Please consult your system’s manpages for
more information
-on this.
-</p>
-</dd>
-<dt>Open directory handles</dt>
-<dd><a name="perlfork-Open-directory-handles"></a>
-<p>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.
-</p>
-<p>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.
-</p>
-</dd>
-<dt>Forking pipe open() not yet implemented</dt>
-<dd><a name="perlfork-Forking-pipe-open_0028_0029-not-yet-implemented"></a>
-<p>The <code>open(FOO, "|-")</code> and <code>open(BAR,
"-|")</code> constructs are not yet
-implemented. This limitation can be easily worked around in new code
-by creating a pipe explicitly. The following example shows how to
-write to a forked child:
-</p>
-<pre class="verbatim"> # simulate open(FOO, "|-")
- sub pipe_to_fork ($) {
- my $parent = shift;
- pipe my $child, $parent or die;
- my $pid = fork();
- die "fork() failed: $!" unless defined $pid;
- if ($pid) {
- close $child;
- }
- else {
- close $parent;
- open(STDIN, "<&=" . fileno($child)) or die;
- }
- $pid;
- }
-
- if (pipe_to_fork('FOO')) {
- # parent
- print FOO "pipe_to_fork\n";
- close FOO;
- }
- else {
- # child
- while (<STDIN>) { print; }
- exit(0);
- }
-</pre>
-<p>And this one reads from the child:
-</p>
-<pre class="verbatim"> # simulate open(FOO, "-|")
- sub pipe_from_fork ($) {
- my $parent = shift;
- pipe $parent, my $child or die;
- my $pid = fork();
- die "fork() failed: $!" unless defined $pid;
- if ($pid) {
- close $child;
- }
- else {
- close $parent;
- open(STDOUT, ">&=" . fileno($child)) or die;
- }
- $pid;
- }
-
- if (pipe_from_fork('BAR')) {
- # parent
- while (<BAR>) { print; }
- close BAR;
- }
- else {
- # child
- print "pipe_from_fork\n";
- exit(0);
- }
-</pre>
-<p>Forking pipe open() constructs will be supported in future.
-</p>
-</dd>
-<dt>Global state maintained by XSUBs</dt>
-<dd><a name="perlfork-Global-state-maintained-by-XSUBs"></a>
-<p>External subroutines (XSUBs) that maintain their own global state may
-not work correctly. Such XSUBs will either need to maintain locks to
-protect simultaneous access to global data from different pseudo-processes,
-or maintain all their state on the Perl symbol table, which is copied
-naturally when fork() is called. A callback mechanism that provides
-extensions an opportunity to clone their state will be provided in the
-near future.
-</p>
-</dd>
-<dt>Interpreter embedded in larger application</dt>
-<dd><a name="perlfork-Interpreter-embedded-in-larger-application"></a>
-<p>The fork() emulation may not behave as expected when it is executed in an
-application which embeds a Perl interpreter and calls Perl APIs that can
-evaluate bits of Perl code. This stems from the fact that the emulation
-only has knowledge about the Perl interpreter’s own data structures and
-knows nothing about the containing application’s state. For example, any
-state carried on the application’s own call stack is out of reach.
-</p>
-</dd>
-<dt>Thread-safety of extensions</dt>
-<dd><a name="perlfork-Thread_002dsafety-of-extensions"></a>
-<p>Since the fork() emulation runs code in multiple threads, extensions
-calling into non-thread-safe libraries may not work reliably when
-calling fork(). As Perl’s threading support gradually becomes more
-widely adopted even on platforms with a native fork(), such extensions
-are expected to be fixed for thread-safety.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlfork-PORTABILITY-CAVEATS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfork-BUGS" accesskey="n" rel="next">perlfork BUGS</a>,
Previous: <a href="#perlfork-CAVEATS-AND-LIMITATIONS" accesskey="p"
rel="prev">perlfork CAVEATS AND LIMITATIONS</a>, Up: <a href="#perlfork"
accesskey="u" rel="up">perlfork</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PORTABILITY-CAVEATS"></a>
-<h3 class="section">23.5 PORTABILITY CAVEATS</h3>
-
-<p>In portable Perl code, <code>kill(9, $child)</code> must not be used on
forked processes.
-Killing a forked process is unsafe and has unpredictable results.
-See <a href="#perlfork-kill_0028_0029">kill()</a>, above.
-</p>
-<hr>
-<a name="perlfork-BUGS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfork-AUTHOR" accesskey="n" rel="next">perlfork AUTHOR</a>,
Previous: <a href="#perlfork-PORTABILITY-CAVEATS" accesskey="p"
rel="prev">perlfork PORTABILITY CAVEATS</a>, Up: <a href="#perlfork"
accesskey="u" rel="up">perlfork</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="BUGS-3"></a>
-<h3 class="section">23.6 BUGS</h3>
-
-<ul>
-<li> Having pseudo-process IDs be negative integers breaks down for the integer
-<code>-1</code> because the wait() and waitpid() functions treat this number as
-being special. The tacit assumption in the current implementation is that
-the system never allocates a thread ID of <code>1</code> for user threads. A
better
-representation for pseudo-process IDs will be implemented in future.
-
-</li><li> In certain cases, the OS-level handles created by the pipe(),
socket(),
-and accept() operators are apparently not duplicated accurately in
-pseudo-processes. This only happens in some situations, but where it
-does happen, it may result in deadlocks between the read and write ends
-of pipe handles, or inability to send or receive data across socket
-handles.
-
-</li><li> This document may be incomplete in some respects.
-
-</li></ul>
-
-<hr>
-<a name="perlfork-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfork-SEE-ALSO" accesskey="n" rel="next">perlfork SEE
ALSO</a>, Previous: <a href="#perlfork-BUGS" accesskey="p" rel="prev">perlfork
BUGS</a>, Up: <a href="#perlfork" accesskey="u" rel="up">perlfork</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-10"></a>
-<h3 class="section">23.7 AUTHOR</h3>
-
-<p>Support for concurrent interpreters and the fork() emulation was implemented
-by ActiveState, with funding from Microsoft Corporation.
-</p>
-<p>This document is authored and maintained by Gurusamy Sarathy
-<address@hidden>.
-</p>
-<hr>
-<a name="perlfork-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlfork-AUTHOR" accesskey="p" rel="prev">perlfork
AUTHOR</a>, Up: <a href="#perlfork" accesskey="u" rel="up">perlfork</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-14"></a>
-<h3 class="section">23.8 SEE ALSO</h3>
-
-<p><a href="#perlfunc-fork">perlfunc fork</a>, <a href="#perlipc-NAME">perlipc
NAME</a>
-</p>
-<hr>
-<a name="perlform"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfunc" accesskey="n" rel="next">perlfunc</a>, Previous: <a
href="#perlfork" accesskey="p" rel="prev">perlfork</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlform-1"></a>
-<h2 class="chapter">24 perlform</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlform-NAME"
accesskey="1">perlform NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlform-DESCRIPTION"
accesskey="2">perlform DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlform-NOTES"
accesskey="3">perlform NOTES</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlform-WARNINGS"
accesskey="4">perlform WARNINGS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlform-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlform-DESCRIPTION" accesskey="n" rel="next">perlform
DESCRIPTION</a>, Up: <a href="#perlform" accesskey="u" rel="up">perlform</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-23"></a>
-<h3 class="section">24.1 NAME</h3>
-
-<p>perlform - Perl formats
-</p>
-<hr>
-<a name="perlform-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlform-NOTES" accesskey="n" rel="next">perlform NOTES</a>,
Previous: <a href="#perlform-NAME" accesskey="p" rel="prev">perlform NAME</a>,
Up: <a href="#perlform" accesskey="u" rel="up">perlform</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-23"></a>
-<h3 class="section">24.2 DESCRIPTION</h3>
-
-<p>Perl has a mechanism to help you generate simple reports and charts. To
-facilitate this, Perl helps you code up your output page close to how it
-will look when it’s printed. It can keep track of things like how many
-lines are on a page, what page you’re on, when to print page headers,
-etc. Keywords are borrowed from FORTRAN: format() to declare and write()
-to execute; see their entries in <a href="#perlfunc-NAME">perlfunc NAME</a>.
Fortunately, the layout is
-much more legible, more like BASIC’s PRINT USING statement. Think of it
-as a poor man’s nroff(1).
-</p>
-<p>Formats, like packages and subroutines, are declared rather than
-executed, so they may occur at any point in your program. (Usually it’s
-best to keep them all together though.) They have their own namespace
-apart from all the other "types" in Perl. This means that if you
have a
-function named "Foo", it is not the same thing as having a format
named
-"Foo". However, the default name for the format associated with a
given
-filehandle is the same as the name of the filehandle. Thus, the default
-format for STDOUT is named "STDOUT", and the default format for
filehandle
-TEMP is named "TEMP". They just look the same. They aren’t.
-</p>
-<p>Output record formats are declared as follows:
-</p>
-<pre class="verbatim"> format NAME =
- FORMLIST
- .
-</pre>
-<p>If the name is omitted, format "STDOUT" is defined. A single
"." in
-column 1 is used to terminate a format. FORMLIST consists of a sequence
-of lines, each of which may be one of three types:
-</p>
-<ol>
-<li> A comment, indicated by putting a ’#’ in the first column.
-
-</li><li> A "picture" line giving the format for one output line.
-
-</li><li> An argument line supplying values to plug into the previous picture
line.
-
-</li></ol>
-
-<p>Picture lines contain output field definitions, intermingled with
-literal text. These lines do not undergo any kind of variable interpolation.
-Field definitions are made up from a set of characters, for starting and
-extending a field to its desired width. This is the complete set of
-characters for field definitions:
-</p>
-<pre class="verbatim"> >>
-
-
- @ start of regular field
- ^ start of special field
- < pad character for left justification
- | pad character for centering
- > pad character for right justification
- # pad character for a right-justified numeric field
- 0 instead of first #: pad number with leading zeroes
- . decimal point within a numeric field
- ... terminate a text field, show "..." as truncation evidence
- @* variable width field for a multi-line value
- ^* variable width field for next line of a multi-line value
- ~ suppress line with all fields empty
- ~~ repeat line until all fields are exhausted
-</pre>
-<p>Each field in a picture line starts with either "@" (at) or
"^" (caret),
-indicating what we’ll call, respectively, a "regular" or
"special" field.
-The choice of pad characters determines whether a field is textual or
-numeric. The tilde operators are not part of a field. Let’s look at
-the various possibilities in detail.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlform-Text-Fields"
accesskey="1">perlform Text Fields</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlform-Numeric-Fields"
accesskey="2">perlform Numeric Fields</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-The-Field-_0040_002a-for-Variable_002dWidth-Multi_002dLine-Text"
accesskey="3">perlform The Field @* for Variable-Width Multi-Line
Text</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-The-Field-_005e_002a-for-Variable_002dWidth-One_002dline_002dat_002da_002dtime-Text"
accesskey="4">perlform The Field ^* for Variable-Width One-line-at-a-time
Text</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlform-Specifying-Values"
accesskey="5">perlform Specifying Values</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlform-Using-Fill-Mode"
accesskey="6">perlform Using Fill Mode</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-Suppressing-Lines-Where-All-Fields-Are-Void"
accesskey="7">perlform Suppressing Lines Where All Fields Are
Void</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-Repeating-Format-Lines" accesskey="8">perlform Repeating Format
Lines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-Top-of-Form-Processing" accesskey="9">perlform Top of Form
Processing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-Format-Variables">perlform Format
Variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlform-Text-Fields"></a>
-<div class="header">
-<p>
-Next: <a href="#perlform-Numeric-Fields" accesskey="n" rel="next">perlform
Numeric Fields</a>, Up: <a href="#perlform-DESCRIPTION" accesskey="u"
rel="up">perlform DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Text-Fields"></a>
-<h4 class="subsection">24.2.1 Text Fields</h4>
-
-<p>The length of the field is supplied by padding out the field with multiple
-"<", ">", or "|" characters to specify a
non-numeric field with,
-respectively, left justification, right justification, or centering.
-For a regular field, the value (up to the first newline) is taken and
-printed according to the selected justification, truncating excess characters.
-If you terminate a text field with "...", three dots will be shown if
-the value is truncated. A special text field may be used to do rudimentary
-multi-line text block filling; see <a href="#perlform-Using-Fill-Mode">Using
Fill Mode</a> for details.
-</p>
-<pre class="verbatim"> Example:
- format STDOUT =
- @<<<<<< @|||||| @>>>>>>
- "left", "middle", "right"
- .
- Output:
- left middle right
-</pre>
-<hr>
-<a name="perlform-Numeric-Fields"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlform-The-Field-_0040_002a-for-Variable_002dWidth-Multi_002dLine-Text"
accesskey="n" rel="next">perlform The Field @* for Variable-Width Multi-Line
Text</a>, Previous: <a href="#perlform-Text-Fields" accesskey="p"
rel="prev">perlform Text Fields</a>, Up: <a href="#perlform-DESCRIPTION"
accesskey="u" rel="up">perlform DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Numeric-Fields"></a>
-<h4 class="subsection">24.2.2 Numeric Fields</h4>
-
-<p>Using "#" as a padding character specifies a numeric field, with
-right justification. An optional "." defines the position of the
-decimal point. With a "0" (zero) instead of the first "#",
the
-formatted number will be padded with leading zeroes if necessary.
-A special numeric field is blanked out if the value is undefined.
-If the resulting value would exceed the width specified the field is
-filled with "#" as overflow evidence.
-</p>
-<pre class="verbatim"> Example:
- format STDOUT =
- @### @.### @##.### @### @### ^####
- 42, 3.1415, undef, 0, 10000, undef
- .
- Output:
- 42 3.142 0.000 0 ####
-</pre>
-<hr>
-<a
name="perlform-The-Field-_0040_002a-for-Variable_002dWidth-Multi_002dLine-Text"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlform-The-Field-_005e_002a-for-Variable_002dWidth-One_002dline_002dat_002da_002dtime-Text"
accesskey="n" rel="next">perlform The Field ^* for Variable-Width
One-line-at-a-time Text</a>, Previous: <a href="#perlform-Numeric-Fields"
accesskey="p" rel="prev">perlform Numeric Fields</a>, Up: <a
href="#perlform-DESCRIPTION" accesskey="u" rel="up">perlform DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-Field-_0040_002a-for-Variable_002dWidth-Multi_002dLine-Text"></a>
-<h4 class="subsection">24.2.3 The Field @* for Variable-Width Multi-Line
Text</h4>
-
-<p>The field "@*" can be used for printing multi-line, nontruncated
-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.
-</p>
-<hr>
-<a
name="perlform-The-Field-_005e_002a-for-Variable_002dWidth-One_002dline_002dat_002da_002dtime-Text"></a>
-<div class="header">
-<p>
-Next: <a href="#perlform-Specifying-Values" accesskey="n" rel="next">perlform
Specifying Values</a>, Previous: <a
href="#perlform-The-Field-_0040_002a-for-Variable_002dWidth-Multi_002dLine-Text"
accesskey="p" rel="prev">perlform The Field @* for Variable-Width Multi-Line
Text</a>, Up: <a href="#perlform-DESCRIPTION" accesskey="u" rel="up">perlform
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a
name="The-Field-_005e_002a-for-Variable_002dWidth-One_002dline_002dat_002da_002dtime-Text"></a>
-<h4 class="subsection">24.2.4 The Field ^* for Variable-Width
One-line-at-a-time Text</h4>
-
-<p>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.
-The variable will <em>not</em> be restored.
-</p>
-<pre class="verbatim"> Example:
- $text = "line 1\nline 2\nline 3";
- format STDOUT =
- Text: ^*
- $text
- ~~ ^*
- $text
- .
- Output:
- Text: line 1
- line 2
- line 3
-</pre>
-<hr>
-<a name="perlform-Specifying-Values"></a>
-<div class="header">
-<p>
-Next: <a href="#perlform-Using-Fill-Mode" accesskey="n" rel="next">perlform
Using Fill Mode</a>, Previous: <a
href="#perlform-The-Field-_005e_002a-for-Variable_002dWidth-One_002dline_002dat_002da_002dtime-Text"
accesskey="p" rel="prev">perlform The Field ^* for Variable-Width
One-line-at-a-time Text</a>, Up: <a href="#perlform-DESCRIPTION" accesskey="u"
rel="up">perlform DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Specifying-Values"></a>
-<h4 class="subsection">24.2.5 Specifying Values</h4>
-
-<p>The values are specified on the following format line in the same order as
-the picture fields. The expressions providing the values must be
-separated by commas. They are all evaluated in a list context
-before the line is processed, so a single list expression could produce
-multiple list elements. The expressions may be spread out to more than
-one line if enclosed in braces. If so, the opening brace must be the first
-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 <strong>without</strong> an embedded "."), the character
used for the decimal
-point is determined by the current LC_NUMERIC locale if <code>use
locale</code> 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
-<a href="#perllocale-NAME">perllocale NAME</a> and <a
href="#perlform-WARNINGS">WARNINGS</a> for more information.
-</p>
-<hr>
-<a name="perlform-Using-Fill-Mode"></a>
-<div class="header">
-<p>
-Next: <a href="#perlform-Suppressing-Lines-Where-All-Fields-Are-Void"
accesskey="n" rel="next">perlform Suppressing Lines Where All Fields Are
Void</a>, Previous: <a href="#perlform-Specifying-Values" accesskey="p"
rel="prev">perlform Specifying Values</a>, Up: <a href="#perlform-DESCRIPTION"
accesskey="u" rel="up">perlform DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-Fill-Mode"></a>
-<h4 class="subsection">24.2.6 Using Fill Mode</h4>
-
-<p>On text fields the caret enables a kind of fill mode. Instead of an
-arbitrary expression, the value supplied must be a scalar variable
-that contains a text string. Perl puts the next portion 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. (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
-(<code>\r</code>) to force a line break. You can change which characters are
legal
-to break on by changing the variable <code>$:</code> (that’s
-$FORMAT_LINE_BREAK_CHARACTERS if you’re using the English module) to a
-list of the desired characters.
-</p>
-<p>Normally you would use a sequence of fields in a vertical stack associated
-with the same scalar variable to print out a block of text. You might wish
-to end the final field with the text "...", which will appear in the
output
-if the text was too long to appear in its entirety.
-</p>
-<hr>
-<a name="perlform-Suppressing-Lines-Where-All-Fields-Are-Void"></a>
-<div class="header">
-<p>
-Next: <a href="#perlform-Repeating-Format-Lines" accesskey="n"
rel="next">perlform Repeating Format Lines</a>, Previous: <a
href="#perlform-Using-Fill-Mode" accesskey="p" rel="prev">perlform Using Fill
Mode</a>, Up: <a href="#perlform-DESCRIPTION" accesskey="u" rel="up">perlform
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Suppressing-Lines-Where-All-Fields-Are-Void"></a>
-<h4 class="subsection">24.2.7 Suppressing Lines Where All Fields Are Void</h4>
-
-<p>Using caret fields can produce lines where all fields are blank. You can
-suppress such lines by putting a "~" (tilde) character anywhere in
the
-line. The tilde will be translated to a space upon output.
-</p>
-<hr>
-<a name="perlform-Repeating-Format-Lines"></a>
-<div class="header">
-<p>
-Next: <a href="#perlform-Top-of-Form-Processing" accesskey="n"
rel="next">perlform Top of Form Processing</a>, Previous: <a
href="#perlform-Suppressing-Lines-Where-All-Fields-Are-Void" accesskey="p"
rel="prev">perlform Suppressing Lines Where All Fields Are Void</a>, Up: <a
href="#perlform-DESCRIPTION" accesskey="u" rel="up">perlform DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Repeating-Format-Lines"></a>
-<h4 class="subsection">24.2.8 Repeating Format Lines</h4>
-
-<p>If you put two contiguous tilde characters "~~" anywhere into a
line,
-the line will be repeated until all the fields on the line are exhausted,
-i.e. undefined. For special (caret) text fields this will occur sooner or
-later, but if you use a text field of the at variety, the expression you
-supply had better not give the same value every time forever!
(<code>shift(@f)</code>
-is a simple example that would work.) Don’t use a regular (at) numeric
-field in such lines, because it will never go blank.
-</p>
-<hr>
-<a name="perlform-Top-of-Form-Processing"></a>
-<div class="header">
-<p>
-Next: <a href="#perlform-Format-Variables" accesskey="n" rel="next">perlform
Format Variables</a>, Previous: <a href="#perlform-Repeating-Format-Lines"
accesskey="p" rel="prev">perlform Repeating Format Lines</a>, Up: <a
href="#perlform-DESCRIPTION" accesskey="u" rel="up">perlform DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Top-of-Form-Processing"></a>
-<h4 class="subsection">24.2.9 Top of Form Processing</h4>
-
-<p>Top-of-form processing is by default handled by a format with the
-same name as the current filehandle with "_TOP" concatenated to it.
-It’s triggered at the top of each page. See <a
href="#perlfunc-write">perlfunc write</a>.
-</p>
-<p>Examples:
-</p>
-<pre class="verbatim"> # a report on the /etc/passwd file
- format STDOUT_TOP =
- Passwd File
- Name Login Office Uid Gid Home
- ------------------------------------------------------------------
- .
- format STDOUT =
- @<<<<<<<<<<<<<<<<<<
@||||||| @<<<<<<@>>>> @>>>>
@<<<<<<<<<<<<<<<<<
- $name, $login, $office,$uid,$gid, $home
- .
-
-
- # a report from a bug report form
- format STDOUT_TOP =
- Bug Reports
-
@<<<<<<<<<<<<<<<<<<<<<<<
@|||
@>>>>>>>>>>>>>>>>>>>>>>>
- $system, $%, $date
- ------------------------------------------------------------------
- .
- format STDOUT =
- Subject:
@<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $subject
- Index:
@<<<<<<<<<<<<<<<<<<<<<<<<<<<<
^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $index, $description
- Priority: @<<<<<<<<<< Date:
@<<<<<<<
^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $priority, $date, $description
- From:
@<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $from, $description
- Assigned to:
@<<<<<<<<<<<<<<<<<<<<<<
^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $programmer, $description
- ~
^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $description
- ~
^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $description
- ~
^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $description
- ~
^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $description
- ~
^<<<<<<<<<<<<<<<<<<<<<<<...
- $description
- .
-</pre>
-<p>It is possible to intermix print()s with write()s on the same output
-channel, but you’ll have to handle <code>$-</code>
(<code>$FORMAT_LINES_LEFT</code>)
-yourself.
-</p>
-<hr>
-<a name="perlform-Format-Variables"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlform-Top-of-Form-Processing" accesskey="p"
rel="prev">perlform Top of Form Processing</a>, Up: <a
href="#perlform-DESCRIPTION" accesskey="u" rel="up">perlform DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Format-Variables"></a>
-<h4 class="subsection">24.2.10 Format Variables</h4>
-
-<p>The current format name is stored in the variable <code>$~</code>
(<code>$FORMAT_NAME</code>),
-and the current top of form format name is in <code>$^</code>
(<code>$FORMAT_TOP_NAME</code>).
-The current output page number is stored in <code>$%</code>
(<code>$FORMAT_PAGE_NUMBER</code>),
-and the number of lines on the page is in <code>$=</code>
(<code>$FORMAT_LINES_PER_PAGE</code>).
-Whether to autoflush output on this handle is stored in <code>$|</code>
-(<code>$OUTPUT_AUTOFLUSH</code>). The string output before each top of page
(except
-the first) is stored in <code>$^L</code> (<code>$FORMAT_FORMFEED</code>).
These variables are
-set on a per-filehandle basis, so you’ll need to select() into a
different
-one to affect them:
-</p>
-<pre class="verbatim"> select((select(OUTF),
- $~ = "My_Other_Format",
- $^ = "My_Top_Format"
- )[0]);
-</pre>
-<p>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 an intermediary
-stage in the expression to single-step the debugger through):
-</p>
-<pre class="verbatim"> $ofh = select(OUTF);
- $~ = "My_Other_Format";
- $^ = "My_Top_Format";
- select($ofh);
-</pre>
-<p>If you use the English module, you can even read the variable names:
-</p>
-<pre class="verbatim"> use English;
- $ofh = select(OUTF);
- $FORMAT_NAME = "My_Other_Format";
- $FORMAT_TOP_NAME = "My_Top_Format";
- select($ofh);
-</pre>
-<p>But you still have those funny select()s. So just use the FileHandle
-module. Now, you can access these special variables using lowercase
-method names instead:
-</p>
-<pre class="verbatim"> use FileHandle;
- format_name OUTF "My_Other_Format";
- format_top_name OUTF "My_Top_Format";
-</pre>
-<p>Much better!
-</p>
-<hr>
-<a name="perlform-NOTES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlform-WARNINGS" accesskey="n" rel="next">perlform
WARNINGS</a>, Previous: <a href="#perlform-DESCRIPTION" accesskey="p"
rel="prev">perlform DESCRIPTION</a>, Up: <a href="#perlform" accesskey="u"
rel="up">perlform</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NOTES-1"></a>
-<h3 class="section">24.3 NOTES</h3>
-
-<p>Because the values line may contain arbitrary expressions (for at fields,
-not caret fields), you can farm out more sophisticated processing
-to other functions, like sprintf() or one of your own. For example:
-</p>
-<pre class="verbatim"> format Ident =
- @<<<<<<<<<<<<<<<
- &commify($n)
- .
-</pre>
-<p>To get a real at or caret into the field, do this:
-</p>
-<pre class="verbatim"> format Ident =
- I have an @ here.
- "@"
- .
-</pre>
-<p>To center a whole line of text, do something like this:
-</p>
-<pre class="verbatim"> format Ident =
- @|||||||||||||||||||||||||||||||||||||||||||||||
- "Some text line"
- .
-</pre>
-<p>There is no builtin way to say "float this to the right hand side
-of the page, however wide it is." You have to specify where it goes.
-The truly desperate can generate their own format on the fly, based
-on the current number of columns, and then eval() it:
-</p>
-<pre class="verbatim"> $format = "format STDOUT = \n"
- . '^' . '<' x $cols . "\n"
- . '$entry' . "\n"
- . "\t^" . "<" x ($cols-8) .
"~~\n"
- . '$entry' . "\n"
- . ".\n";
- print $format if $Debugging;
- eval $format;
- die $@ if $@;
-</pre>
-<p>Which would generate a format looking something like this:
-</p>
-<pre class="verbatim"> format STDOUT =
-
^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $entry
-
^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
- $entry
- .
-</pre>
-<p>Here’s a little program that’s somewhat like fmt(1):
-</p>
-<pre class="verbatim"> format =
-
^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
~~
- $_
-
- .
-
- $/ = '';
- while (<>) {
- s/\s*\n\s*/ /g;
- write;
- }
-</pre>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlform-Footers"
accesskey="1">perlform Footers</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlform-Accessing-Formatting-Internals" accesskey="2">perlform
Accessing Formatting Internals</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlform-Footers"></a>
-<div class="header">
-<p>
-Next: <a href="#perlform-Accessing-Formatting-Internals" accesskey="n"
rel="next">perlform Accessing Formatting Internals</a>, Up: <a
href="#perlform-NOTES" accesskey="u" rel="up">perlform NOTES</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Footers"></a>
-<h4 class="subsection">24.3.1 Footers</h4>
-
-<p>While $FORMAT_TOP_NAME contains the name of the current header format,
-there is no corresponding mechanism to automatically do the same thing
-for a footer. Not knowing how big a format is going to be until you
-evaluate it is one of the major problems. It’s on the TODO list.
-</p>
-<p>Here’s one strategy: If you have a fixed-size footer, you can get
footers
-by checking $FORMAT_LINES_LEFT before each write() and print the footer
-yourself if necessary.
-</p>
-<p>Here’s another strategy: Open a pipe to yourself, using
<code>open(MYSELF, "|-")</code>
-(see ‘perlfunc open’) and always write() to MYSELF instead of
STDOUT.
-Have your child process massage its STDIN to rearrange headers and footers
-however you like. Not very convenient, but doable.
-</p>
-<hr>
-<a name="perlform-Accessing-Formatting-Internals"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlform-Footers" accesskey="p" rel="prev">perlform
Footers</a>, Up: <a href="#perlform-NOTES" accesskey="u" rel="up">perlform
NOTES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Accessing-Formatting-Internals"></a>
-<h4 class="subsection">24.3.2 Accessing Formatting Internals</h4>
-
-<p>For low-level access to the formatting mechanism, you may use formline()
-and access <code>$^A</code> (the $ACCUMULATOR variable) directly.
-</p>
-<p>For example:
-</p>
-<pre class="verbatim"> $str = formline <<'END', 1,2,3;
- @<<< @||| @>>>
- END
-
- print "Wow, I just stored '$^A' in the accumulator!\n";
-</pre>
-<p>Or to make an swrite() subroutine, which is to write() what sprintf()
-is to printf(), do this:
-</p>
-<pre class="verbatim"> use Carp;
- sub swrite {
- croak "usage: swrite PICTURE ARGS" unless @_;
- my $format = shift;
- $^A = "";
- formline($format,@_);
- return $^A;
- }
-
- $string = swrite(<<'END', 1, 2, 3);
- Check me out
- @<<< @||| @>>>
- END
- print $string;
-</pre>
-<hr>
-<a name="perlform-WARNINGS"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlform-NOTES" accesskey="p" rel="prev">perlform
NOTES</a>, Up: <a href="#perlform" accesskey="u" rel="up">perlform</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="WARNINGS"></a>
-<h3 class="section">24.4 WARNINGS</h3>
-
-<p>The lone dot that ends a format can also prematurely end a mail
-message passing through a misconfigured Internet mailer (and based on
-experience, such misconfiguration is the rule, not the exception). So
-when sending format code through mail, you should indent it so that
-the format-ending dot is not on the left margin; this will prevent
-SMTP cutoff.
-</p>
-<p>Lexical variables (declared with "my") are not visible within a
-format unless the format is declared within the scope of the lexical
-variable.
-</p>
-<p>If a program’s environment specifies an LC_NUMERIC locale and
<code>use
-locale</code> 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 <code>use locale</code> at the time when write()
-is called. See <a href="#perllocale-NAME">perllocale NAME</a> for further
discussion of locale handling.
-</p>
-<p>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 <code>\r</code> when using fill mode.) This is done to avoid
-misalignment when control characters "disappear" on some output
media.
-</p>
-<hr>
-<a name="perlfunc"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit" accesskey="n" rel="next">perlgit</a>, Previous: <a
href="#perlform" accesskey="p" rel="prev">perlform</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlfunc-1"></a>
-<h2 class="chapter">25 perlfunc</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlfunc-NAME"
accesskey="1">perlfunc NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfunc-DESCRIPTION"
accesskey="2">perlfunc DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlfunc-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfunc-DESCRIPTION" accesskey="n" rel="next">perlfunc
DESCRIPTION</a>, Up: <a href="#perlfunc" accesskey="u" rel="up">perlfunc</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-24"></a>
-<h3 class="section">25.1 NAME</h3>
-
-<p>perlfunc - Perl builtin functions
-</p>
-<hr>
-<a name="perlfunc-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlfunc-NAME" accesskey="p" rel="prev">perlfunc NAME</a>,
Up: <a href="#perlfunc" accesskey="u" rel="up">perlfunc</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-24"></a>
-<h3 class="section">25.2 DESCRIPTION</h3>
-
-<p>The functions in this section can serve as terms in an expression.
-They fall into two major categories: list operators and named unary
-operators. These differ in their precedence relationship with a
-following comma. (See the precedence table in <a href="#perlop-NAME">perlop
NAME</a>.) 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 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
-be one such list argument. For instance, splice() has three scalar
-arguments followed by a list, whereas gethostbyname() has four scalar
-arguments.
-</p>
-<p>In the syntax descriptions that follow, list operators that expect a
-list (and provide list context for elements of the list) are shown
-with LIST as an argument. Such a list may consist of any combination
-of scalar arguments or list values; the list values will be included
-in the list as if each individual element were interpolated at that
-point in the list, forming a longer single-dimensional list value.
-Commas should separate literal elements of the LIST.
-</p>
-<p>Any function in the list below may be used either with or without
-parentheses around its arguments. (The syntax descriptions omit the
-parentheses.) If you use parentheses, the simple but occasionally
-surprising rule is this: It <em>looks</em> like a function, therefore it
<em>is</em> a
-function, and precedence doesn’t matter. Otherwise it’s a list
-operator or unary operator, and precedence does matter. Whitespace
-between the function and left parenthesis doesn’t count, so sometimes
-you need to be careful:
-</p>
-<pre class="verbatim"> print 1+2+4; # Prints 7.
- print(1+2) + 4; # Prints 3.
- print (1+2)+4; # Also prints 3!
- print +(1+2)+4; # Prints 7.
- print ((1+2)+4); # Prints 7.
-</pre>
-<p>If you run Perl with the <strong>-w</strong> switch it can warn you about
this. For
-example, the third line above produces:
-</p>
-<pre class="verbatim"> print (...) interpreted as function at - line 1.
- Useless use of integer addition in void context at - line 1.
-</pre>
-<p>A few functions take no arguments at all, and therefore work as neither
-unary nor list operators. These include such functions as <code>time</code>
-and <code>endpwent</code>. For example, <code>time+86_400</code> always means
-<code>time() + 86_400</code>.
-</p>
-<p>For functions that can be used in either a scalar or list context,
-nonabortive failure is generally indicated in scalar context by
-returning the undefined value, and in list context by returning the
-empty list.
-</p>
-<p>Remember the following important rule: There is <strong>no rule</strong>
that relates
-the behavior of an expression in list context to its behavior in scalar
-context, or vice versa. It might do two totally different things.
-Each operator and function decides which sort of value would be most
-appropriate to return in scalar context. Some operators return the
-length of the list that would have been returned in list context. Some
-operators return the first value in the list. Some operators return the
-last value in the list. Some operators return a count of successful
-operations. In general, they do what you want, unless you want
-consistency.
-</p>
-<p>A named array in scalar context is quite different from what would at
-first glance appear to be a list in scalar context. You can’t get a list
-like <code>(1,2,3)</code> into being in scalar context, because the compiler
knows
-the context at compile time. It would generate the scalar comma operator
-there, not the list construction version of the comma. That means it
-was never a list to start with.
-</p>
-<p>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.) return
-true when they succeed and <code>undef</code> otherwise, as is usually
mentioned
-in the descriptions below. This is different from the C interfaces,
-which return <code>-1</code> on failure. Exceptions to this rule include
<code>wait</code>,
-<code>waitpid</code>, and <code>syscall</code>. System calls also set the
special <code>$!</code>
-variable on failure. Other functions do not, except accidentally.
-</p>
-<p>Extension modules can also hook into the Perl parser to define new
-kinds of keyword-headed expression. These may look like functions, but
-may also look completely different. The syntax following the keyword
-is defined entirely by the extension. If you are an implementor, see
-<a
href="perlapi.html#PL_005fkeyword_005fplugin">(perlapi)PL_keyword_plugin</a>
for the mechanism. If you are using such
-a module, see the module’s documentation for details of the syntax that
-it defines.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlfunc-Perl-Functions-by-Category" accesskey="1">perlfunc Perl
Functions by Category</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfunc-Portability"
accesskey="2">perlfunc Portability</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfunc-Alphabetical-Listing-of-Perl-Functions" accesskey="3">perlfunc
Alphabetical Listing of Perl Functions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlfunc-Non_002dfunction-Keywords-by-Cross_002dreference"
accesskey="4">perlfunc Non-function Keywords by
Cross-reference</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlfunc-Perl-Functions-by-Category"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfunc-Portability" accesskey="n" rel="next">perlfunc
Portability</a>, Up: <a href="#perlfunc-DESCRIPTION" accesskey="u"
rel="up">perlfunc DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Perl-Functions-by-Category"></a>
-<h4 class="subsection">25.2.1 Perl Functions by Category</h4>
-
-<p>Here are Perl’s functions (including things that look like
-functions, like some keywords and named operators)
-arranged by category. Some functions appear in more
-than one place.
-</p>
-<dl compact="compact">
-<dt>Functions for SCALARs or strings</dt>
-<dd><a name="perlfunc-Functions-for-SCALARs-or-strings"></a>
-<p><code>chomp</code>, <code>chop</code>, <code>chr</code>,
<code>crypt</code>, <code>fc</code>, <code>hex</code>, <code>index</code>,
<code>lc</code>,
-<code>lcfirst</code>, <code>length</code>, <code>oct</code>, <code>ord</code>,
<code>pack</code>, <code>q//</code>, <code>qq//</code>, <code>reverse</code>,
-<code>rindex</code>, <code>sprintf</code>, <code>substr</code>,
<code>tr///</code>, <code>uc</code>, <code>ucfirst</code>, <code>y///</code>
-</p>
-<p><code>fc</code> is available only if the <code>"fc"</code>
feature is enabled or if it is
-prefixed with <code>CORE::</code>. The <code>"fc"</code> feature is
enabled automatically
-with a <code>use v5.16</code> (or higher) declaration in the current scope.
-</p>
-</dd>
-<dt>Regular expressions and pattern matching</dt>
-<dd><a name="perlfunc-Regular-expressions-and-pattern-matching"></a>
-<p><code>m//</code>, <code>pos</code>, <code>qr//</code>,
<code>quotemeta</code>, <code>s///</code>, <code>split</code>,
<code>study</code>
-</p>
-</dd>
-<dt>Numeric functions</dt>
-<dd><a name="perlfunc-Numeric-functions"></a>
-<p><code>abs</code>, <code>atan2</code>, <code>cos</code>, <code>exp</code>,
<code>hex</code>, <code>int</code>, <code>log</code>, <code>oct</code>,
<code>rand</code>,
-<code>sin</code>, <code>sqrt</code>, <code>srand</code>
-</p>
-</dd>
-<dt>Functions for real @ARRAYs</dt>
-<dd><a name="perlfunc-Functions-for-real-_0040ARRAYs"></a>
-<p><code>each</code>, <code>keys</code>, <code>pop</code>, <code>push</code>,
<code>shift</code>, <code>splice</code>, <code>unshift</code>,
<code>values</code>
-</p>
-</dd>
-<dt>Functions for list data</dt>
-<dd><a name="perlfunc-Functions-for-list-data"></a>
-<p><code>grep</code>, <code>join</code>, <code>map</code>, <code>qw//</code>,
<code>reverse</code>, <code>sort</code>, <code>unpack</code>
-</p>
-</dd>
-<dt>Functions for real %HASHes</dt>
-<dd><a name="perlfunc-Functions-for-real-_0025HASHes"></a>
-<p><code>delete</code>, <code>each</code>, <code>exists</code>,
<code>keys</code>, <code>values</code>
-</p>
-</dd>
-<dt>Input and output functions</dt>
-<dd><a name="perlfunc-Input-and-output-functions"></a>
-<p><code>binmode</code>, <code>close</code>, <code>closedir</code>,
<code>dbmclose</code>, <code>dbmopen</code>, <code>die</code>, <code>eof</code>,
-<code>fileno</code>, <code>flock</code>, <code>format</code>,
<code>getc</code>, <code>print</code>, <code>printf</code>, <code>read</code>,
-<code>readdir</code>, <code>readline</code> <code>rewinddir</code>,
<code>say</code>, <code>seek</code>, <code>seekdir</code>, <code>select</code>,
-<code>syscall</code>, <code>sysread</code>, <code>sysseek</code>,
<code>syswrite</code>, <code>tell</code>, <code>telldir</code>,
-<code>truncate</code>, <code>warn</code>, <code>write</code>
-</p>
-<p><code>say</code> is available only if the <code>"say"</code>
feature is enabled or if it is
-prefixed with <code>CORE::</code>. The <code>"say"</code> feature
is enabled automatically
-with a <code>use v5.10</code> (or higher) declaration in the current scope.
-</p>
-</dd>
-<dt>Functions for fixed-length data or records</dt>
-<dd><a name="perlfunc-Functions-for-fixed_002dlength-data-or-records"></a>
-<p><code>pack</code>, <code>read</code>, <code>syscall</code>,
<code>sysread</code>, <code>sysseek</code>, <code>syswrite</code>,
<code>unpack</code>,
-<code>vec</code>
-</p>
-</dd>
-<dt>Functions for filehandles, files, or directories</dt>
-<dd><a
name="perlfunc-Functions-for-filehandles_002c-files_002c-or-directories"></a>
-<p><code>-<em>X</em></code>, <code>chdir</code>, <code>chmod</code>,
<code>chown</code>, <code>chroot</code>, <code>fcntl</code>, <code>glob</code>,
-<code>ioctl</code>, <code>link</code>, <code>lstat</code>, <code>mkdir</code>,
<code>open</code>, <code>opendir</code>,
-<code>readlink</code>, <code>rename</code>, <code>rmdir</code>,
<code>stat</code>, <code>symlink</code>, <code>sysopen</code>,
-<code>umask</code>, <code>unlink</code>, <code>utime</code>
-</p>
-</dd>
-<dt>Keywords related to the control flow of your Perl program</dt>
-<dd><a
name="perlfunc-Keywords-related-to-the-control-flow-of-your-Perl-program"></a>
-<p><code>break</code>, <code>caller</code>, <code>continue</code>,
<code>die</code>, <code>do</code>,
-<code>dump</code>, <code>eval</code>, <code>evalbytes</code> <code>exit</code>,
-<code>__FILE__</code>, <code>goto</code>, <code>last</code>,
<code>__LINE__</code>, <code>next</code>, <code>__PACKAGE__</code>,
-<code>redo</code>, <code>return</code>, <code>sub</code>,
<code>__SUB__</code>, <code>wantarray</code>
-</p>
-<p><code>break</code> is available only if you enable the experimental
<code>"switch"</code>
-feature or use the <code>CORE::</code> prefix. The
<code>"switch"</code> feature also enables
-the <code>default</code>, <code>given</code> and <code>when</code> statements,
which are documented in
-<a href="#perlsyn-Switch-Statements">perlsyn Switch Statements</a>. The
<code>"switch"</code> feature is enabled
-automatically with a <code>use v5.10</code> (or higher) declaration in the
current
-scope. In Perl v5.14 and earlier, <code>continue</code> required the
<code>"switch"</code>
-feature, like the other keywords.
-</p>
-<p><code>evalbytes</code> is only available with the
<code>"evalbytes"</code> feature (see
-<a href="feature.html#Top">(feature)</a>) or if prefixed with
<code>CORE::</code>. <code>__SUB__</code> is only available
-with the <code>"current_sub"</code> feature or if prefixed with
<code>CORE::</code>. Both
-the <code>"evalbytes"</code> and
<code>"current_sub"</code> features are enabled automatically
-with a <code>use v5.16</code> (or higher) declaration in the current scope.
-</p>
-</dd>
-<dt>Keywords related to scoping</dt>
-<dd><a name="perlfunc-Keywords-related-to-scoping"></a>
-<p><code>caller</code>, <code>import</code>, <code>local</code>,
<code>my</code>, <code>our</code>, <code>package</code>, <code>state</code>,
<code>use</code>
-</p>
-<p><code>state</code> is available only if the <code>"state"</code>
feature is enabled or if it is
-prefixed with <code>CORE::</code>. The <code>"state"</code> feature
is enabled automatically
-with a <code>use v5.10</code> (or higher) declaration in the current scope.
-</p>
-</dd>
-<dt>Miscellaneous functions</dt>
-<dd><a name="perlfunc-Miscellaneous-functions"></a>
-<p><code>defined</code>, <code>formline</code>, <code>lock</code>,
<code>prototype</code>, <code>reset</code>, <code>scalar</code>,
<code>undef</code>
-</p>
-</dd>
-<dt>Functions for processes and process groups</dt>
-<dd><a name="perlfunc-Functions-for-processes-and-process-groups"></a>
-<p><code>alarm</code>, <code>exec</code>, <code>fork</code>,
<code>getpgrp</code>, <code>getppid</code>, <code>getpriority</code>,
<code>kill</code>,
-<code>pipe</code>, <code>qx//</code>, <code>readpipe</code>,
<code>setpgrp</code>,
-<code>setpriority</code>, <code>sleep</code>, <code>system</code>,
-<code>times</code>, <code>wait</code>, <code>waitpid</code>
-</p>
-</dd>
-<dt>Keywords related to Perl modules</dt>
-<dd><a name="perlfunc-Keywords-related-to-Perl-modules"></a>
-<p><code>do</code>, <code>import</code>, <code>no</code>,
<code>package</code>, <code>require</code>, <code>use</code>
-</p>
-</dd>
-<dt>Keywords related to classes and object-orientation</dt>
-<dd><a
name="perlfunc-Keywords-related-to-classes-and-object_002dorientation"></a>
-<p><code>bless</code>, <code>dbmclose</code>, <code>dbmopen</code>,
<code>package</code>, <code>ref</code>, <code>tie</code>, <code>tied</code>,
-<code>untie</code>, <code>use</code>
-</p>
-</dd>
-<dt>Low-level socket functions</dt>
-<dd><a name="perlfunc-Low_002dlevel-socket-functions"></a>
-<p><code>accept</code>, <code>bind</code>, <code>connect</code>,
<code>getpeername</code>, <code>getsockname</code>,
-<code>getsockopt</code>, <code>listen</code>, <code>recv</code>,
<code>send</code>, <code>setsockopt</code>, <code>shutdown</code>,
-<code>socket</code>, <code>socketpair</code>
-</p>
-</dd>
-<dt>System V interprocess communication functions</dt>
-<dd><a name="perlfunc-System-V-interprocess-communication-functions"></a>
-<p><code>msgctl</code>, <code>msgget</code>, <code>msgrcv</code>,
<code>msgsnd</code>, <code>semctl</code>, <code>semget</code>,
<code>semop</code>,
-<code>shmctl</code>, <code>shmget</code>, <code>shmread</code>,
<code>shmwrite</code>
-</p>
-</dd>
-<dt>Fetching user and group info</dt>
-<dd><a name="perlfunc-Fetching-user-and-group-info"></a>
-<p><code>endgrent</code>, <code>endhostent</code>, <code>endnetent</code>,
<code>endpwent</code>, <code>getgrent</code>,
-<code>getgrgid</code>, <code>getgrnam</code>, <code>getlogin</code>,
<code>getpwent</code>, <code>getpwnam</code>,
-<code>getpwuid</code>, <code>setgrent</code>, <code>setpwent</code>
-</p>
-</dd>
-<dt>Fetching network info</dt>
-<dd><a name="perlfunc-Fetching-network-info"></a>
-<p><code>endprotoent</code>, <code>endservent</code>,
<code>gethostbyaddr</code>, <code>gethostbyname</code>,
-<code>gethostent</code>, <code>getnetbyaddr</code>, <code>getnetbyname</code>,
<code>getnetent</code>,
-<code>getprotobyname</code>, <code>getprotobynumber</code>,
<code>getprotoent</code>,
-<code>getservbyname</code>, <code>getservbyport</code>,
<code>getservent</code>, <code>sethostent</code>,
-<code>setnetent</code>, <code>setprotoent</code>, <code>setservent</code>
-</p>
-</dd>
-<dt>Time-related functions</dt>
-<dd><a name="perlfunc-Time_002drelated-functions"></a>
-<p><code>gmtime</code>, <code>localtime</code>, <code>time</code>,
<code>times</code>
-</p>
-</dd>
-<dt>Non-function keywords</dt>
-<dd><a name="perlfunc-Non_002dfunction-keywords"></a>
-<p><code>and</code>, <code>AUTOLOAD</code>, <code>BEGIN</code>,
<code>CHECK</code>, <code>cmp</code>, <code>CORE</code>, <code>__DATA__</code>,
-<code>default</code>, <code>DESTROY</code>, <code>else</code>,
<code>elseif</code>, <code>elsif</code>, <code>END</code>, <code>__END__</code>,
-<code>eq</code>, <code>for</code>, <code>foreach</code>, <code>ge</code>,
<code>given</code>, <code>gt</code>, <code>if</code>, <code>INIT</code>,
<code>le</code>,
-<code>lt</code>, <code>ne</code>, <code>not</code>, <code>or</code>,
<code>UNITCHECK</code>, <code>unless</code>, <code>until</code>,
<code>when</code>,
-<code>while</code>, <code>x</code>, <code>xor</code>
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlfunc-Portability"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfunc-Alphabetical-Listing-of-Perl-Functions" accesskey="n"
rel="next">perlfunc Alphabetical Listing of Perl Functions</a>, Previous: <a
href="#perlfunc-Perl-Functions-by-Category" accesskey="p" rel="prev">perlfunc
Perl Functions by Category</a>, Up: <a href="#perlfunc-DESCRIPTION"
accesskey="u" rel="up">perlfunc DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Portability"></a>
-<h4 class="subsection">25.2.2 Portability</h4>
-
-<p>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
-functionality may differ slightly. The Perl functions affected
-by this are:
-</p>
-<p><code>-X</code>, <code>binmode</code>, <code>chmod</code>,
<code>chown</code>, <code>chroot</code>, <code>crypt</code>,
-<code>dbmclose</code>, <code>dbmopen</code>, <code>dump</code>,
<code>endgrent</code>, <code>endhostent</code>,
-<code>endnetent</code>, <code>endprotoent</code>, <code>endpwent</code>,
<code>endservent</code>, <code>exec</code>,
-<code>fcntl</code>, <code>flock</code>, <code>fork</code>,
<code>getgrent</code>, <code>getgrgid</code>, <code>gethostbyname</code>,
-<code>gethostent</code>, <code>getlogin</code>, <code>getnetbyaddr</code>,
<code>getnetbyname</code>, <code>getnetent</code>,
-<code>getppid</code>, <code>getpgrp</code>, <code>getpriority</code>,
<code>getprotobynumber</code>,
-<code>getprotoent</code>, <code>getpwent</code>, <code>getpwnam</code>,
<code>getpwuid</code>,
-<code>getservbyport</code>, <code>getservent</code>, <code>getsockopt</code>,
<code>glob</code>, <code>ioctl</code>,
-<code>kill</code>, <code>link</code>, <code>lstat</code>, <code>msgctl</code>,
<code>msgget</code>, <code>msgrcv</code>,
-<code>msgsnd</code>, <code>open</code>, <code>pipe</code>,
<code>readlink</code>, <code>rename</code>, <code>select</code>,
<code>semctl</code>,
-<code>semget</code>, <code>semop</code>, <code>setgrent</code>,
<code>sethostent</code>, <code>setnetent</code>,
-<code>setpgrp</code>, <code>setpriority</code>, <code>setprotoent</code>,
<code>setpwent</code>,
-<code>setservent</code>, <code>setsockopt</code>, <code>shmctl</code>,
<code>shmget</code>, <code>shmread</code>,
-<code>shmwrite</code>, <code>socket</code>, <code>socketpair</code>,
-<code>stat</code>, <code>symlink</code>, <code>syscall</code>,
<code>sysopen</code>, <code>system</code>,
-<code>times</code>, <code>truncate</code>, <code>umask</code>,
<code>unlink</code>,
-<code>utime</code>, <code>wait</code>, <code>waitpid</code>
-</p>
-<p>For more information about the portability of these functions, see
-<a href="#perlport-NAME">perlport NAME</a> and other available
platform-specific documentation.
-</p>
-<hr>
-<a name="perlfunc-Alphabetical-Listing-of-Perl-Functions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfunc-Non_002dfunction-Keywords-by-Cross_002dreference"
accesskey="n" rel="next">perlfunc Non-function Keywords by Cross-reference</a>,
Previous: <a href="#perlfunc-Portability" accesskey="p" rel="prev">perlfunc
Portability</a>, Up: <a href="#perlfunc-DESCRIPTION" accesskey="u"
rel="up">perlfunc DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Alphabetical-Listing-of-Perl-Functions"></a>
-<h4 class="subsection">25.2.3 Alphabetical Listing of Perl Functions</h4>
-
-<dl compact="compact">
-<dt>-X FILEHANDLE</dt>
-<dd><a name="perlfunc-_002dX-FILEHANDLE"></a>
-</dd>
-<dt>-X EXPR</dt>
-<dd><a name="perlfunc-_002dX-EXPR"></a>
-</dd>
-<dt>-X DIRHANDLE</dt>
-<dd><a name="perlfunc-_002dX-DIRHANDLE"></a>
-</dd>
-<dt>-X</dt>
-<dd><a name="perlfunc-_002dX"></a>
-<p>A file test, where X is one of the letters listed below. This unary
-operator takes one argument, either a filename, a filehandle, or a dirhandle,
-and tests the associated file to see if something is true about it. If the
-argument is omitted, tests <code>$_</code>, except for <code>-t</code>, which
tests STDIN.
-Unless otherwise documented, it returns <code>1</code> for true and
<code>''</code> for false.
-If the file doesn’t exist or can’t be examined, it returns
<code>undef</code> and
-sets <code>$!</code> (errno). Despite the funny names, precedence is the same
as any
-other named unary operator. The operator may be any of:
-</p>
-<pre class="verbatim"> -r File is readable by effective uid/gid.
- -w File is writable by effective uid/gid.
- -x File is executable by effective uid/gid.
- -o File is owned by effective uid.
-
- -R File is readable by real uid/gid.
- -W File is writable by real uid/gid.
- -X File is executable by real uid/gid.
- -O File is owned by real uid.
-
- -e File exists.
- -z File has zero size (is empty).
- -s File has nonzero size (returns size in bytes).
-
- -f File is a plain file.
- -d File is a directory.
- -l File is a symbolic link (false if symlinks aren't
- supported by the file system).
- -p File is a named pipe (FIFO), or Filehandle is a pipe.
- -S File is a socket.
- -b File is a block special file.
- -c File is a character special file.
- -t Filehandle is opened to a tty.
-
- -u File has setuid bit set.
- -g File has setgid bit set.
- -k File has sticky bit set.
-
- -T File is an ASCII or UTF-8 text file (heuristic guess).
- -B File is a "binary" file (opposite of -T).
-
- -M Script start time minus file modification time, in days.
- -A Same for access time.
- -C Same for inode change time (Unix, may differ for other
- platforms)
-</pre>
-<p>Example:
-</p>
-<pre class="verbatim"> while (<>) {
- chomp;
- next unless -f $_; # ignore specials
- #...
- }
-</pre>
-<p>Note that <code>-s/a/b/</code> does not do a negated substitution. Saying
-<code>-exp($foo)</code> still works as expected, however: only single letters
-following a minus are interpreted as file tests.
-</p>
-<p>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):
-</p>
-<pre class="verbatim"> -s($file) + 1024 # probably wrong; same as
-s($file + 1024)
- (-s $file) + 1024 # correct
-</pre>
-<p>The interpretation of the file permission operators <code>-r</code>,
<code>-R</code>,
-<code>-w</code>, <code>-W</code>, <code>-x</code>, and <code>-X</code> is by
default based solely on the mode
-of the file and the uids and gids of the user. There may be other
-reasons you can’t actually read, write, or execute the file: for
-example network filesystem access controls, ACLs (access control lists),
-read-only filesystems, and unrecognized executable formats. Note
-that the use of these six specific operators to verify if some operation
-is possible is usually a mistake, because it may be open to race
-conditions.
-</p>
-<p>Also note that, for the superuser on the local filesystems, the
<code>-r</code>,
-<code>-R</code>, <code>-w</code>, and <code>-W</code> tests always return 1,
and <code>-x</code> and <code>-X</code> return 1
-if any execute bit is set in the mode. Scripts run by the superuser
-may thus need to do a stat() to determine the actual mode of the file,
-or temporarily set their effective uid to something else.
-</p>
-<p>If you are using ACLs, there is a pragma called <code>filetest</code> that
may
-produce more accurate results than the bare stat() mode bits.
-When under <code>use filetest 'access'</code> the above-mentioned filetests
-test whether the permission can(not) be granted using the
-access(2) family of system calls. Also note that the <code>-x</code> and
<code>-X</code> may
-under this pragma return true even if there are no execute permission
-bits set (nor any extra execute permission ACLs). This strangeness is
-due to the underlying system calls’ definitions. Note also that, due to
-the implementation of <code>use filetest 'access'</code>, the <code>_</code>
special
-filehandle won’t cache the results of the file tests when this pragma is
-in effect. Read the documentation for the <code>filetest</code> pragma for
more
-information.
-</p>
-<p>The <code>-T</code> and <code>-B</code> switches work as follows. The
first block or so of
-the file is examined to see if it is valid UTF-8 that includes non-ASCII
-characters. If, so it’s a <code>-T</code> file. Otherwise, that same
portion of
-the file is examined for odd characters such as strange control codes or
-characters with the high bit set. If more than a third of the
-characters are strange, it’s a <code>-B</code> file; otherwise
it’s a <code>-T</code> file.
-Also, any file containing a zero byte in the examined portion is
-considered a binary file. (If executed within the scope of a <a
href="#perllocale-NAME">use locale<!-- /@w --></a> which includes
<code>LC_CTYPE</code>, odd characters are
-anything that isn’t a printable nor space in the current locale.) If
-<code>-T</code> or <code>-B</code> is used on a filehandle, the current IO
buffer is
-examined
-rather than the first block. Both <code>-T</code> and <code>-B</code> return
true on an empty
-file, or a file at EOF when testing a filehandle. Because you have to
-read a file to do the <code>-T</code> test, on most occasions you want to use
a <code>-f</code>
-against the file first, as in <code>next unless -f $file && -T
$file</code>.
-</p>
-<p>If any of the file tests (or either the <code>stat</code> or
<code>lstat</code> 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 <code>-t</code>, and you need to
remember
-that lstat() and <code>-l</code> leave values in the stat structure for the
-symbolic link, not the real file.) (Also, if the stat buffer was filled by
-an <code>lstat</code> call, <code>-T</code> and <code>-B</code> will reset it
with the results of <code>stat _</code>).
-Example:
-</p>
-<pre class="verbatim"> print "Can do.\n" if -r $a || -w _ || -x _;
-
- stat($filename);
- print "Readable\n" if -r _;
- print "Writable\n" if -w _;
- print "Executable\n" if -x _;
- print "Setuid\n" if -u _;
- print "Setgid\n" if -g _;
- print "Sticky\n" if -k _;
- print "Text\n" if -T _;
- print "Binary\n" if -B _;
-</pre>
-<p>As of Perl 5.10.0, as a form of purely syntactic sugar, you can stack file
-test operators, in a way that <code>-f -w -x $file</code> is equivalent to
-<code>-x $file && -w _ && -f _</code>. (This is only fancy
syntax: if you use
-the return value of <code>-f $file</code> as an argument to another filetest
-operator, no special magic will happen.)
-</p>
-<p>Portability issues: <a href="#perlport-_002dX">perlport -X</a>.
-</p>
-<p>To avoid confusing would-be users of your code with mysterious
-syntax errors, put something like this at the top of your script:
-</p>
-<pre class="verbatim"> use 5.010; # so filetest ops can stack
-</pre>
-</dd>
-<dt>abs VALUE</dt>
-<dd><a name="perlfunc-abs-VALUE"></a>
-</dd>
-<dt>abs</dt>
-<dd><a name="perlfunc-abs"></a>
-<p>Returns the absolute value of its argument.
-If VALUE is omitted, uses <code>$_</code>.
-</p>
-</dd>
-<dt>accept NEWSOCKET,GENERICSOCKET</dt>
-<dd><a name="perlfunc-accept-NEWSOCKET_002cGENERICSOCKET"></a>
-<p>Accepts an incoming socket connect, just as accept(2)
-does. Returns the packed address if it succeeded, false otherwise.
-See the example in <a
href="#perlipc-Sockets_003a-Client_002fServer-Communication">perlipc Sockets:
Client/Server Communication</a>.
-</p>
-<p>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 <a href="#perlvar-_0024_005eF">perlvar $^F</a>.
-</p>
-</dd>
-<dt>alarm SECONDS</dt>
-<dd><a name="perlfunc-alarm-SECONDS"></a>
-</dd>
-<dt>alarm</dt>
-<dd><a name="perlfunc-alarm"></a>
-<p>Arranges to have a SIGALRM delivered to this process after the
-specified number of wallclock seconds has elapsed. If SECONDS is not
-specified, the value stored in <code>$_</code> is used. (On some machines,
-unfortunately, the elapsed time may be up to one second less or more
-than you specified because of how seconds are counted, and process
-scheduling may delay the delivery of the signal even further.)
-</p>
-<p>Only one timer may be counting at once. Each call disables the
-previous timer, and an argument of <code>0</code> may be supplied to cancel the
-previous timer without starting a new one. The returned value is the
-amount of time remaining on the previous timer.
-</p>
-<p>For delays of finer granularity than one second, the Time::HiRes module
-(from CPAN, and starting from Perl 5.8 part of the standard
-distribution) provides ualarm(). You may also use Perl’s four-argument
-version of select() leaving the first three arguments undefined, or you
-might be able to use the <code>syscall</code> interface to access setitimer(2)
if
-your system supports it. See <a href="perlfaq8.html#Top">(perlfaq8)</a> for
details.
-</p>
-<p>It is usually a mistake to intermix <code>alarm</code> and
<code>sleep</code> calls, because
-<code>sleep</code> may be internally implemented on your system with
<code>alarm</code>.
-</p>
-<p>If you want to use <code>alarm</code> to time out a system call you need to
use an
-<code>eval</code>/<code>die</code> pair. You can’t rely on the alarm
causing the system call to
-fail with <code>$!</code> set to <code>EINTR</code> because Perl sets up
signal handlers to
-restart system calls on some systems. Using
<code>eval</code>/<code>die</code> always works,
-modulo the caveats given in <a href="#perlipc-Signals">perlipc Signals</a>.
-</p>
-<pre class="verbatim"> eval {
- local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
- alarm $timeout;
- $nread = sysread SOCKET, $buffer, $size;
- alarm 0;
- };
- if ($@) {
- die unless $@ eq "alarm\n"; # propagate unexpected errors
- # timed out
- }
- else {
- # didn't
- }
-</pre>
-<p>For more information see <a href="#perlipc-NAME">perlipc NAME</a>.
-</p>
-<p>Portability issues: <a href="#perlport-alarm">perlport alarm</a>.
-</p>
-</dd>
-<dt>atan2 Y,X</dt>
-<dd><a name="perlfunc-atan2-Y_002cX"></a>
-<p>Returns the arctangent of Y/X in the range -PI to PI.
-</p>
-<p>For the tangent operation, you may use the <code>Math::Trig::tan</code>
-function, or use the familiar relation:
-</p>
-<pre class="verbatim"> sub tan { sin($_[0]) / cos($_[0]) }
-</pre>
-<p>The return value for <code>atan2(0,0)</code> is implementation-defined;
consult
-your atan2(3) manpage for more information.
-</p>
-<p>Portability issues: <a href="#perlport-atan2">perlport atan2</a>.
-</p>
-</dd>
-<dt>bind SOCKET,NAME</dt>
-<dd><a name="perlfunc-bind-SOCKET_002cNAME"></a>
-<p>Binds a network address to a socket, just as bind(2)
-does. Returns true if it succeeded, false otherwise. NAME should be a
-packed address of the appropriate type for the socket. See the examples in
-<a href="#perlipc-Sockets_003a-Client_002fServer-Communication">perlipc
Sockets: Client/Server Communication</a>.
-</p>
-</dd>
-<dt>binmode FILEHANDLE, LAYER</dt>
-<dd><a name="perlfunc-binmode-FILEHANDLE_002c-LAYER"></a>
-</dd>
-<dt>binmode FILEHANDLE</dt>
-<dd><a name="perlfunc-binmode-FILEHANDLE"></a>
-<p>Arranges for FILEHANDLE to be read or written in "binary" or
"text"
-mode on systems where the run-time libraries distinguish between
-binary and text files. If FILEHANDLE is an expression, the value is
-taken as the name of the filehandle. Returns true on success,
-otherwise it returns <code>undef</code> and sets <code>$!</code> (errno).
-</p>
-<p>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 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.
-</p>
-<p>In other words: regardless of platform, use binmode() on binary data,
-like images, for example.
-</p>
-<p>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.
-</p>
-<p>If LAYER is omitted or specified as <code>:raw</code> the filehandle is made
-suitable for passing binary data. This includes turning off possible CRLF
-translation and marking it as bytes (as opposed to Unicode characters).
-Note that, despite what may be implied in <em>"Programming
Perl"</em> (the
-Camel, 3rd edition) or elsewhere, <code>:raw</code> is <em>not</em> simply the
inverse of <code>:crlf</code>.
-Other layers that would affect the binary nature of the stream are
-<em>also</em> disabled. See <a href="PerlIO.html#Top">(PerlIO)</a>, <a
href="#perlrun-NAME">perlrun NAME</a>, and the discussion about the
-PERLIO environment variable.
-</p>
-<p>The <code>:bytes</code>, <code>:crlf</code>, <code>:utf8</code>, and any
other directives of the
-form <code>:...</code>, are called I/O <em>layers</em>. The <code>open</code>
pragma can be used to
-establish default I/O layers. See <a href="open.html#Top">(open)</a>.
-</p>
-<p><em>The LAYER parameter of the binmode() function is described as
"DISCIPLINE"
-in "Programming Perl, 3rd Edition". However, since the publishing
of this
-book, by many known as "Camel III", the consensus of the naming of
this
-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...</em>
-</p>
-<p>To mark FILEHANDLE as UTF-8, use <code>:utf8</code> or
<code>:encoding(UTF-8)</code>.
-<code>:utf8</code> just marks the data as UTF-8 without further checking,
-while <code>:encoding(UTF-8)</code> checks the data for actually being valid
-UTF-8. More details can be found in <a
href="PerlIO-encoding.html#Top">(PerlIO-encoding)</a>.
-</p>
-<p>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 <code>:encoding</code> layer that
-changes the default character encoding of the handle; see ‘open’.
-The <code>:encoding</code> layer sometimes needs to be called in
-mid-stream, and it doesn’t flush the stream. The <code>:encoding</code>
-also implicitly pushes on top of itself the <code>:utf8</code> layer because
-internally Perl operates on UTF8-encoded Unicode characters.
-</p>
-<p>The operating system, device drivers, C libraries, and Perl run-time
-system all conspire to let the programmer treat a single
-character (<code>\n</code>) 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 <code>\n</code> is made up of more
than
-one character.
-</p>
-<p>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 <code>\n</code> as a simple <code>\cJ</code>, but what’s stored
in text files are the
-two characters <code>\cM\cJ</code>. That means that if you don’t use
binmode() on
-these systems, <code>\cM\cJ</code> sequences on disk will be converted to
<code>\n</code> on
-input, and any <code>\n</code> in your program will be converted back to
<code>\cM\cJ</code> on
-output. This is what you want for text files, but it can be disastrous for
-binary files.
-</p>
-<p>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 contain <code>\cZ</code>, the I/O subsystem will regard it as the end of
-the file, unless you use binmode().
-</p>
-<p>binmode() is important not only for readline() and print() operations,
-but also when using read(), seek(), sysread(), syswrite() and tell()
-(see <a href="#perlport-NAME">perlport NAME</a> for more details). See the
<code>$/</code> and <code>$\</code> variables
-in <a href="#perlvar-NAME">perlvar NAME</a> for how to manually set your input
and output
-line-termination sequences.
-</p>
-<p>Portability issues: <a href="#perlport-binmode">perlport binmode</a>.
-</p>
-</dd>
-<dt>bless REF,CLASSNAME</dt>
-<dd><a name="perlfunc-bless-REF_002cCLASSNAME"></a>
-</dd>
-<dt>bless REF</dt>
-<dd><a name="perlfunc-bless-REF"></a>
-<p>This function tells the thingy referenced by REF that it is now an object
-in the CLASSNAME package. If CLASSNAME is omitted, the current package
-is used. Because a <code>bless</code> is often the last thing in a
constructor,
-it returns the reference for convenience. Always use the two-argument
-version if a derived class might inherit the function doing the blessing.
-See <a href="#perlobj-NAME">perlobj NAME</a> for more about the blessing (and
blessings) of objects.
-</p>
-<p>Consider always blessing objects in CLASSNAMEs that are mixed case.
-Namespaces with all lowercase names are considered reserved for
-Perl pragmata. Builtin types have all uppercase names. To prevent
-confusion, you may wish to avoid such package names as well. Make sure
-that CLASSNAME is a true value.
-</p>
-<p>See <a href="#perlmod-Perl-Modules">perlmod Perl Modules</a>.
-</p>
-</dd>
-<dt>break</dt>
-<dd><a name="perlfunc-break"></a>
-<p>Break out of a <code>given()</code> block.
-</p>
-<p>This keyword is enabled by the <code>"switch"</code> feature; see
<a href="feature.html#Top">(feature)</a> for
-more information on <code>"switch"</code>. You can also access it
by prefixing it
-with <code>CORE::</code>. Alternatively, include a <code>use v5.10</code> or
later to the
-current scope.
-</p>
-</dd>
-<dt>caller EXPR</dt>
-<dd><a name="perlfunc-caller-EXPR"></a>
-</dd>
-<dt>caller</dt>
-<dd><a name="perlfunc-caller"></a>
-<p>Returns the context of the current pure perl subroutine call. In scalar
-context, returns the caller’s package name if there <em>is</em> a caller
(that is, if
-we’re in a subroutine or <code>eval</code> or <code>require</code>) and
the undefined value
-otherwise. caller never returns XS subs and they are skipped. The next pure
-perl sub will appear instead of the XS
-sub in caller’s return values. In list
-context, caller returns
-</p>
-<pre class="verbatim"> # 0 1 2
- ($package, $filename, $line) = caller;
-</pre>
-<p>With EXPR, it returns some extra information that the debugger uses to
-print a stack trace. The value of EXPR indicates how many call frames
-to go back before the current one.
-</p>
-<pre class="verbatim"> # 0 1 2 3 4
- ($package, $filename, $line, $subroutine, $hasargs,
-
- # 5 6 7 8 9 10
- $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
- = caller($i);
-</pre>
-<p>Here, $subroutine is the function that the caller called (rather than the
-function containing the caller). Note that $subroutine may be
<code>(eval)</code> if
-the frame is not a subroutine call, but an <code>eval</code>. In such a case
-additional elements $evaltext and
-<code>$is_require</code> are set: <code>$is_require</code> is true if the
frame is created by a
-<code>require</code> or <code>use</code> statement, $evaltext contains the
text of the
-<code>eval EXPR</code> statement. In particular, for an <code>eval
BLOCK</code> statement,
-$subroutine is <code>(eval)</code>, but $evaltext is undefined. (Note also
that
-each <code>use</code> statement creates a <code>require</code> frame inside an
<code>eval EXPR</code>
-frame.) $subroutine may also be <code>(unknown)</code> if this particular
-subroutine happens to have been deleted from the symbol table.
-<code>$hasargs</code> is true if a new instance of <code>@_</code> was set up
for the frame.
-<code>$hints</code> and <code>$bitmask</code> contain pragmatic hints that the
caller was
-compiled with. <code>$hints</code> corresponds to <code>$^H</code>, and
<code>$bitmask</code>
-corresponds to <code>${^WARNING_BITS}</code>. The
-<code>$hints</code> and <code>$bitmask</code> values are subject
-to change between versions of Perl, and are not meant for external use.
-</p>
-<p><code>$hinthash</code> is a reference to a hash containing the value of
<code>%^H</code> when the
-caller was compiled, or <code>undef</code> if <code>%^H</code> was empty. Do
not modify the values
-of this hash, as they are the actual values stored in the optree.
-</p>
-<p>Furthermore, when called from within the DB package in
-list context, and with an argument, caller returns more
-detailed information: it sets the list variable <code>@DB::args</code> to be
the
-arguments with which the subroutine was invoked.
-</p>
-<p>Be aware that the optimizer might have optimized call frames away before
-<code>caller</code> had a chance to get the information. That means that
<code>caller(N)</code>
-might not return information about the call frame you expect it to, for
-<code>N > 1</code>. In particular, <code>@DB::args</code> might have
information from the
-previous time <code>caller</code> was called.
-</p>
-<p>Be aware that setting <code>@DB::args</code> is <em>best effort</em>,
intended for
-debugging or generating backtraces, and should not be relied upon. In
-particular, as <code>@_</code> contains aliases to the caller’s
arguments, Perl does
-not take a copy of <code>@_</code>, so <code>@DB::args</code> will contain
modifications the
-subroutine makes to <code>@_</code> or its contents, not the original values
at call
-time. <code>@DB::args</code>, like <code>@_</code>, 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 is that the effects of <code>shift @_</code> can
-<em>normally</em> be undone (but not <code>pop @_</code> or other splicing,
<em>and</em> not if a
-reference to <code>@_</code> has been taken, <em>and</em> subject to the
caveat about reallocated
-elements), so <code>@DB::args</code> is actually a hybrid of the current state
and
-initial state of <code>@_</code>. Buyer beware.
-</p>
-</dd>
-<dt>chdir EXPR</dt>
-<dd><a name="perlfunc-chdir-EXPR"></a>
-</dd>
-<dt>chdir FILEHANDLE</dt>
-<dd><a name="perlfunc-chdir-FILEHANDLE"></a>
-</dd>
-<dt>chdir DIRHANDLE</dt>
-<dd><a name="perlfunc-chdir-DIRHANDLE"></a>
-</dd>
-<dt>chdir</dt>
-<dd><a name="perlfunc-chdir"></a>
-<p>Changes the working directory to EXPR, if possible. If EXPR is omitted,
-changes to the directory specified by <code>$ENV{HOME}</code>, if set; if not,
-changes to the directory specified by <code>$ENV{LOGDIR}</code>. (Under VMS,
the
-variable <code>$ENV{SYS$LOGIN}</code> is also checked, and used if it is set.)
If
-neither is set, <code>chdir</code> does nothing. It returns true on success,
-false otherwise. See the example under <code>die</code>.
-</p>
-<p>On systems that support fchdir(2), you may pass a filehandle or
-directory handle as the argument. On systems that don’t support
fchdir(2),
-passing handles raises an exception.
-</p>
-</dd>
-<dt>chmod LIST</dt>
-<dd><a name="perlfunc-chmod-LIST"></a>
-<p>Changes the permissions of a list of files. The first element of the
-list must be the numeric mode, which should probably be an octal
-number, and which definitely should <em>not</em> be a string of octal digits:
-<code>0644</code> is okay, but <code>"0644"</code> is not. Returns
the number of files
-successfully changed. See also <a href="#perlfunc-oct">oct</a> if all you
have is a string.
-</p>
-<pre class="verbatim"> $cnt = chmod 0755, "foo", "bar";
- chmod 0755, @executables;
- $mode = "0644"; chmod $mode, "foo"; # !!! sets
mode to
- # --w----r-T
- $mode = "0644"; chmod oct($mode), "foo"; # this is
better
- $mode = 0644; chmod $mode, "foo"; # this is best
-</pre>
-<p>On systems that support fchmod(2), you may pass filehandles among the
-files. On systems that don’t support fchmod(2), passing filehandles
raises
-an exception. Filehandles must be passed as globs or glob references to be
-recognized; barewords are considered filenames.
-</p>
-<pre class="verbatim"> open(my $fh, "<", "foo");
- my $perm = (stat $fh)[2] & 07777;
- chmod($perm | 0600, $fh);
-</pre>
-<p>You can also import the symbolic <code>S_I*</code> constants from the
<code>Fcntl</code>
-module:
-</p>
-<pre class="verbatim"> use Fcntl qw( :mode );
- chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
- # Identical to the chmod 0755 of the example above.
-</pre>
-<p>Portability issues: <a href="#perlport-chmod">perlport chmod</a>.
-</p>
-</dd>
-<dt>chomp VARIABLE</dt>
-<dd><a name="perlfunc-chomp-VARIABLE"></a>
-</dd>
-<dt>chomp( LIST )</dt>
-<dd><a name="perlfunc-chomp_0028-LIST-_0029"></a>
-</dd>
-<dt>chomp</dt>
-<dd><a name="perlfunc-chomp"></a>
-<p>This safer version of <a href="#perlfunc-chop">chop</a> removes any
trailing string
-that corresponds to the current value of <code>$/</code> (also known as
-$INPUT_RECORD_SEPARATOR in the <code>English</code> module). It returns the
total
-number of characters removed from all its arguments. It’s often used to
-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 (<code>$/ = ''</code>), it removes all trailing newlines from the string.
-When in slurp mode (<code>$/ = undef</code>) or fixed-length record mode
(<code>$/</code> is
-a reference to an integer or the like; see <a href="#perlvar-NAME">perlvar
NAME</a>) chomp() won’t
-remove anything.
-If VARIABLE is omitted, it chomps <code>$_</code>. Example:
-</p>
-<pre class="verbatim"> while (<>) {
- chomp; # avoid \n on last field
- @array = split(/:/);
- # ...
- }
-</pre>
-<p>If VARIABLE is a hash, it chomps the hash’s values, but not its keys,
-resetting the <code>each</code> iterator in the process.
-</p>
-<p>You can actually chomp anything that’s an lvalue, including an
assignment:
-</p>
-<pre class="verbatim"> chomp($cwd = `pwd`);
- chomp($answer = <STDIN>);
-</pre>
-<p>If you chomp a list, each element is chomped, and the total number of
-characters removed is returned.
-</p>
-<p>Note that parentheses are necessary when you’re chomping anything
-that is not a simple variable. This is because <code>chomp $cwd =
`pwd`;</code>
-is interpreted as <code>(chomp $cwd) = `pwd`;</code>, rather than as
-<code>chomp( $cwd = `pwd` )</code> which you might expect. Similarly,
-<code>chomp $a, $b</code> is interpreted as <code>chomp($a), $b</code> rather
than
-as <code>chomp($a, $b)</code>.
-</p>
-</dd>
-<dt>chop VARIABLE</dt>
-<dd><a name="perlfunc-chop-VARIABLE"></a>
-</dd>
-<dt>chop( LIST )</dt>
-<dd><a name="perlfunc-chop_0028-LIST-_0029"></a>
-</dd>
-<dt>chop</dt>
-<dd><a name="perlfunc-chop"></a>
-<p>Chops off the last character of a string and returns the character
-chopped. It is much more efficient than <code>s/.$//s</code> because it
neither
-scans nor copies the string. If VARIABLE is omitted, chops <code>$_</code>.
-If VARIABLE is a hash, it chops the hash’s values, but not its keys,
-resetting the <code>each</code> iterator in the process.
-</p>
-<p>You can actually chop anything that’s an lvalue, including an
assignment.
-</p>
-<p>If you chop a list, each element is chopped. Only the value of the
-last <code>chop</code> is returned.
-</p>
-<p>Note that <code>chop</code> returns the last character. To return all but
the last
-character, use <code>substr($string, 0, -1)</code>.
-</p>
-<p>See also <a href="#perlfunc-chomp">chomp</a>.
-</p>
-</dd>
-<dt>chown LIST</dt>
-<dd><a name="perlfunc-chown-LIST"></a>
-<p>Changes the owner (and group) of a list of files. The first two
-elements of the list must be the <em>numeric</em> uid and gid, in that
-order. A value of -1 in either position is interpreted by most
-systems to leave that value unchanged. Returns the number of files
-successfully changed.
-</p>
-<pre class="verbatim"> $cnt = chown $uid, $gid, 'foo', 'bar';
- chown $uid, $gid, @filenames;
-</pre>
-<p>On systems that support fchown(2), you may pass filehandles among the
-files. On systems that don’t support fchown(2), passing filehandles
raises
-an exception. Filehandles must be passed as globs or glob references to be
-recognized; barewords are considered filenames.
-</p>
-<p>Here’s an example that looks up nonnumeric uids in the passwd file:
-</p>
-<pre class="verbatim"> print "User: ";
- chomp($user = <STDIN>);
- print "Files: ";
- chomp($pattern = <STDIN>);
-
- ($login,$pass,$uid,$gid) = getpwnam($user)
- or die "$user not in passwd file";
-
- @ary = glob($pattern); # expand filenames
- chown $uid, $gid, @ary;
-</pre>
-<p>On most systems, you are not allowed to change the ownership of the
-file unless you’re the superuser, although you should be able to change
-the group to any of your secondary groups. On insecure systems, these
-restrictions may be relaxed, but this is not a portable assumption.
-On POSIX systems, you can detect this condition this way:
-</p>
-<pre class="verbatim"> use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
- $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
-</pre>
-<p>Portability issues: <a href="#perlport-chown">perlport chown</a>.
-</p>
-</dd>
-<dt>chr NUMBER</dt>
-<dd><a name="perlfunc-chr-NUMBER"></a>
-</dd>
-<dt>chr</dt>
-<dd><a name="perlfunc-chr"></a>
-<p>Returns the character represented by that NUMBER in the character set.
-For example, <code>chr(65)</code> is <code>"A"</code> in either
ASCII or Unicode, and
-chr(0x263a) is a Unicode smiley face.
-</p>
-<p>Negative values give the Unicode replacement character (chr(0xfffd)),
-except under the <a href="bytes.html#Top">(bytes)</a> pragma, where the low
eight bits of the value
-(truncated to an integer) are used.
-</p>
-<p>If NUMBER is omitted, uses <code>$_</code>.
-</p>
-<p>For the reverse, use <a href="#perlfunc-ord">ord</a>.
-</p>
-<p>Note that characters from 128 to 255 (inclusive) are by default
-internally not encoded as UTF-8 for backward compatibility reasons.
-</p>
-<p>See <a href="#perlunicode-NAME">perlunicode NAME</a> for more about Unicode.
-</p>
-</dd>
-<dt>chroot FILENAME</dt>
-<dd><a name="perlfunc-chroot-FILENAME"></a>
-</dd>
-<dt>chroot</dt>
-<dd><a name="perlfunc-chroot"></a>
-<p>This function works like the system call by the same name: it makes the
-named directory the new root directory for all further pathnames that
-begin with a <code>/</code> by your process and all its children. (It
doesn’t
-change your current working directory, which is unaffected.) For security
-reasons, this call is restricted to the superuser. If FILENAME is
-omitted, does a <code>chroot</code> to <code>$_</code>.
-</p>
-<p><strong>NOTE:</strong> It is good security practice to do
<code>chdir("/")</code> (to the root
-directory) immediately after a <code>chroot()</code>.
-</p>
-<p>Portability issues: <a href="#perlport-chroot">perlport chroot</a>.
-</p>
-</dd>
-<dt>close FILEHANDLE</dt>
-<dd><a name="perlfunc-close-FILEHANDLE"></a>
-</dd>
-<dt>close</dt>
-<dd><a name="perlfunc-close"></a>
-<p>Closes the file or pipe associated with the filehandle, flushes the IO
-buffers, and closes the system file descriptor. Returns true if those
-operations succeed and if no error was reported by any PerlIO
-layer. Closes the currently selected filehandle if the argument is
-omitted.
-</p>
-<p>You don’t have to close FILEHANDLE if you are immediately going to do
-another <code>open</code> on it, because <code>open</code> closes it for you.
(See
-<a href="#perlfunc-open-FILEHANDLE">open</a>.) However, an explicit
<code>close</code> on an input file resets the line
-counter (<code>$.</code>), while the implicit close done by <code>open</code>
does not.
-</p>
-<p>If the filehandle came from a piped open, <code>close</code> returns false
if one of
-the other syscalls involved fails or if its program exits with non-zero
-status. If the only problem was that the program exited non-zero,
<code>$!</code>
-will be set to <code>0</code>. Closing a pipe also waits for the process
executing
-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
-<code>$?</code> and <code>${^CHILD_ERROR_NATIVE}</code>.
-</p>
-<p>If there are multiple threads running, <code>close</code> 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.
-</p>
-<p>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
-closing the pipe.
-</p>
-<p>Example:
-</p>
-<pre class="verbatim"> open(OUTPUT, '|sort >foo') # pipe to sort
- or die "Can't start sort: $!";
- #... # print stuff to output
- close OUTPUT # wait for sort to finish
- or warn $! ? "Error closing sort pipe: $!"
- : "Exit status $? from sort";
- open(INPUT, 'foo') # get sort's results
- or die "Can't open 'foo' for input: $!";
-</pre>
-<p>FILEHANDLE may be an expression whose value can be used as an indirect
-filehandle, usually the real filehandle name or an autovivified handle.
-</p>
-</dd>
-<dt>closedir DIRHANDLE</dt>
-<dd><a name="perlfunc-closedir-DIRHANDLE"></a>
-<p>Closes a directory opened by <code>opendir</code> and returns the success
of that
-system call.
-</p>
-</dd>
-<dt>connect SOCKET,NAME</dt>
-<dd><a name="perlfunc-connect-SOCKET_002cNAME"></a>
-<p>Attempts to connect to a remote socket, just like connect(2).
-Returns true if it succeeded, false otherwise. NAME should be a
-packed address of the appropriate type for the socket. See the examples in
-<a href="#perlipc-Sockets_003a-Client_002fServer-Communication">perlipc
Sockets: Client/Server Communication</a>.
-</p>
-</dd>
-<dt>continue BLOCK</dt>
-<dd><a name="perlfunc-continue-BLOCK"></a>
-</dd>
-<dt>continue</dt>
-<dd><a name="perlfunc-continue"></a>
-<p>When followed by a BLOCK, <code>continue</code> is actually a
-flow control statement rather than a function. If
-there is a <code>continue</code> BLOCK attached to a BLOCK (typically in a
<code>while</code> or
-<code>foreach</code>), it is always executed just before the conditional is
about to
-be evaluated again, just like the third part of a <code>for</code> loop in C.
Thus
-it can be used to increment a loop variable, even when the loop has been
-continued via the <code>next</code> statement (which is similar to the C
<code>continue</code>
-statement).
-</p>
-<p><code>last</code>, <code>next</code>, or <code>redo</code> may appear
within a <code>continue</code>
-block; <code>last</code> and <code>redo</code> behave as if they had been
executed within
-the main block. So will <code>next</code>, but since it will execute a
<code>continue</code>
-block, it may be more entertaining.
-</p>
-<pre class="verbatim"> while (EXPR) {
- ### redo always comes here
- do_something;
- } continue {
- ### next always comes here
- do_something_else;
- # then back the top to re-check EXPR
- }
- ### last always comes here
-</pre>
-<p>Omitting the <code>continue</code> section is equivalent to using an
-empty one, logically enough, so <code>next</code> goes directly back
-to check the condition at the top of the loop.
-</p>
-<p>When there is no BLOCK, <code>continue</code> is a function that
-falls through the current <code>when</code> or <code>default</code> block
instead of iterating
-a dynamically enclosing <code>foreach</code> or exiting a lexically enclosing
<code>given</code>.
-In Perl 5.14 and earlier, this form of <code>continue</code> was
-only available when the <code>"switch"</code> feature was enabled.
-See <a href="feature.html#Top">(feature)</a> and <a
href="#perlsyn-Switch-Statements">perlsyn Switch Statements</a> for more
-information.
-</p>
-</dd>
-<dt>cos EXPR</dt>
-<dd><a name="perlfunc-cos-EXPR"></a>
-</dd>
-<dt>cos</dt>
-<dd><a name="perlfunc-cos"></a>
-<p>Returns the cosine of EXPR (expressed in radians). If EXPR is omitted,
-takes the cosine of <code>$_</code>.
-</p>
-<p>For the inverse cosine operation, you may use the
<code>Math::Trig::acos()</code>
-function, or use this relation:
-</p>
-<pre class="verbatim"> sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
-</pre>
-</dd>
-<dt>crypt PLAINTEXT,SALT</dt>
-<dd><a name="perlfunc-crypt-PLAINTEXT_002cSALT"></a>
-<p>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).
-</p>
-<p>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
-changes in the PLAINTEXT or SALT will result in large changes in the
-digest.
-</p>
-<p>There is no decrypt function. This function isn’t all that useful for
-cryptography (for that, look for <samp>Crypt</samp> modules on your nearby CPAN
-mirror) and the name "crypt" is a bit of a misnomer. Instead it is
-primarily used to check if two pieces of text are the same without
-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.
-</p>
-<p>When verifying an existing digest string you should use the digest as
-the salt (like <code>crypt($plain, $digest) eq $digest</code>). 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 ‘crypt’ and
-with more exotic implementations. In other words, assume
-nothing about the returned string itself nor about how many bytes
-of SALT may matter.
-</p>
-<p>Traditionally the result is a string of 13 bytes: two first bytes of
-the salt, followed by 11 bytes from the set <code>[./0-9A-Za-z]</code>, and
only
-the first eight bytes of PLAINTEXT mattered. But alternative
-hashing schemes (like MD5), higher level security schemes (like C2),
-and implementations on non-Unix platforms may produce different
-strings.
-</p>
-<p>When choosing a new salt create a random two character string whose
-characters come from the set <code>[./0-9A-Za-z]</code> (like <code>join '',
('.',
-'/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]</code>). This set of
-characters is just a recommendation; the characters allowed in
-the salt depend solely on your system’s crypt library, and Perl
can’t
-restrict what salts <code>crypt()</code> accepts.
-</p>
-<p>Here’s an example that makes sure that whoever runs this program knows
-their password:
-</p>
-<pre class="verbatim"> $pwd = (getpwuid($<))[1];
-
- system "stty -echo";
- print "Password: ";
- chomp($word = <STDIN>);
- print "\n";
- system "stty echo";
-
- if (crypt($word, $pwd) ne $pwd) {
- die "Sorry...\n";
- } else {
- print "ok\n";
- }
-</pre>
-<p>Of course, typing in your own password to whoever asks you
-for it is unwise.
-</p>
-<p>The ‘crypt’ function is unsuitable for hashing large quantities
-of data, not least of all because you can’t get the information
-back. Look at the <a href="Digest.html#Top">(Digest)</a> module for more
robust algorithms.
-</p>
-<p>If using crypt() on a Unicode string (which <em>potentially</em> has
-characters with codepoints above 255), Perl tries to make sense
-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
-<code>Wide character in crypt</code>.
-</p>
-<p>Portability issues: <a href="#perlport-crypt">perlport crypt</a>.
-</p>
-</dd>
-<dt>dbmclose HASH</dt>
-<dd><a name="perlfunc-dbmclose-HASH"></a>
-<p>[This function has been largely superseded by the <code>untie</code>
function.]
-</p>
-<p>Breaks the binding between a DBM file and a hash.
-</p>
-<p>Portability issues: <a href="#perlport-dbmclose">perlport dbmclose</a>.
-</p>
-</dd>
-<dt>dbmopen HASH,DBNAME,MASK</dt>
-<dd><a name="perlfunc-dbmopen-HASH_002cDBNAME_002cMASK"></a>
-<p>[This function has been largely superseded by the
-<a href="#perlfunc-tie-VARIABLE_002cCLASSNAME_002cLIST">tie</a> function.]
-</p>
-<p>This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a
-hash. HASH is the name of the hash. (Unlike normal <code>open</code>, the
first
-argument is <em>not</em> a filehandle, even though it looks like one). DBNAME
-is the name of the database (without the <samp>.dir</samp> or
<samp>.pag</samp> extension if
-any). If the database does not exist, it is created with protection
-specified by MASK (as modified by the <code>umask</code>). To prevent
creation of
-the database if it doesn’t exist, you may specify a MODE
-of 0, and the function will return a false value if it
-can’t find an existing database. If your system supports
-only the older DBM functions, you may make only one <code>dbmopen</code> call
in your
-program. In older versions of Perl, if your system had neither DBM nor
-ndbm, calling <code>dbmopen</code> produced a fatal error; it now falls back to
-sdbm(3).
-</p>
-<p>If you don’t have write access to the DBM file, you can only read hash
-variables, not set them. If you want to test whether you can write,
-either use file tests or try setting a dummy hash entry inside an
<code>eval</code>
-to trap the error.
-</p>
-<p>Note that functions such as <code>keys</code> and <code>values</code> may
return huge lists
-when used on large DBM files. You may prefer to use the <code>each</code>
-function to iterate over large DBM files. Example:
-</p>
-<pre class="verbatim"> # print out history file offsets
- dbmopen(%HIST,'/usr/lib/news/history',0666);
- while (($key,$val) = each %HIST) {
- print $key, ' = ', unpack('L',$val), "\n";
- }
- dbmclose(%HIST);
-</pre>
-<p>See also <a href="AnyDBM_File.html#Top">(AnyDBM_File)</a> for a more
general description of the pros and
-cons of the various dbm approaches, as well as <a
href="DB_File.html#Top">(DB_File)</a> for a particularly
-rich implementation.
-</p>
-<p>You can control which DBM library you use by loading that library
-before you call dbmopen():
-</p>
-<pre class="verbatim"> use DB_File;
- dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
- or die "Can't open netscape history file: $!";
-</pre>
-<p>Portability issues: <a href="#perlport-dbmopen">perlport dbmopen</a>.
-</p>
-</dd>
-<dt>defined EXPR</dt>
-<dd><a name="perlfunc-defined-EXPR"></a>
-</dd>
-<dt>defined</dt>
-<dd><a name="perlfunc-defined"></a>
-<p>Returns a Boolean value telling whether EXPR has a value other than
-the undefined value <code>undef</code>. If EXPR is not present,
<code>$_</code> is
-checked.
-</p>
-<p>Many operations return <code>undef</code> to indicate failure, end of file,
-system error, uninitialized variable, and other exceptional
-conditions. This function allows you to distinguish <code>undef</code> from
-other values. (A simple Boolean test will not distinguish among
-<code>undef</code>, zero, the empty string, and <code>"0"</code>,
which are all equally
-false.) Note that since <code>undef</code> is a valid scalar, its presence
-doesn’t <em>necessarily</em> indicate an exceptional condition:
<code>pop</code>
-returns <code>undef</code> when its argument is an empty array, <em>or</em>
when the
-element to return happens to be <code>undef</code>.
-</p>
-<p>You may also use <code>defined(&func)</code> to check whether
subroutine <code>&func</code>
-has ever been defined. The return value is unaffected by any forward
-declarations of <code>&func</code>. A subroutine that is not defined
-may still be callable: its package may have an <code>AUTOLOAD</code> method
that
-makes it spring into existence the first time that it is called; see
-<a href="#perlsub-NAME">perlsub NAME</a>.
-</p>
-<p>Use of <code>defined</code> on aggregates (hashes and arrays) is
deprecated. It
-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:
-</p>
-<pre class="verbatim"> if (@an_array) { print "has array
elements\n" }
- if (%a_hash) { print "has hash members\n" }
-</pre>
-<p>When used on a hash element, it tells you whether the value is defined,
-not whether the key exists in the hash. Use ‘exists’ for the
latter
-purpose.
-</p>
-<p>Examples:
-</p>
-<pre class="verbatim"> 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;
-</pre>
-<p>Note: Many folks tend to overuse <code>defined</code> and are then
surprised to
-discover that the number <code>0</code> and <code>""</code> (the
zero-length string) are, in fact,
-defined values. For example, if you say
-</p>
-<pre class="verbatim"> "ab" =~ /a(.*)b/;
-</pre>
-<p>The pattern match succeeds and <code>$1</code> is defined, although it
-matched "nothing". It didn’t really fail to match anything.
Rather, it
-matched something that happened to be zero characters long. This is all
-very above-board and honest. When a function returns an undefined value,
-it’s an admission that it couldn’t give you an honest answer. So
you
-should use <code>defined</code> only when questioning the integrity of what
-you’re trying to do. At other times, a simple comparison to
<code>0</code> or <code>""</code> is
-what you want.
-</p>
-<p>See also <a href="#perlfunc-undef">undef</a>, ‘exists’, <a
href="#perlfunc-ref">ref</a>.
-</p>
-</dd>
-<dt>delete EXPR</dt>
-<dd><a name="perlfunc-delete-EXPR"></a>
-<p>Given an expression that specifies an element or slice of a hash,
<code>delete</code>
-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 ‘exists’.
-</p>
-<p>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.
-</p>
-<p>delete() may also be used on arrays and array slices, but its behavior is
less
-straightforward. Although exists() will return false for deleted entries,
-deleting array elements never changes indices of existing values; use shift()
-or splice() for that. However, if any 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. In other words, an
-array won’t have trailing nonexistent elements after a delete.
-</p>
-<p><strong>WARNING:</strong> Calling <code>delete</code> on array values is
strongly discouraged. The
-notion of deleting or checking the existence of Perl array elements is not
-conceptually coherent, and can lead to surprising behavior.
-</p>
-<p>Deleting from <code>%ENV</code> modifies the environment. Deleting from a
hash tied to
-a DBM file deletes the entry from the DBM file. Deleting from a
<code>tied</code> hash
-or array may not necessarily return anything; it depends on the implementation
-of the <code>tied</code> package’s DELETE method, which may do whatever
it pleases.
-</p>
-<p>The <code>delete local EXPR</code> construct localizes the deletion to the
current
-block at run time. Until the block exits, elements locally deleted
-temporarily no longer exist. See <a
href="#perlsub-Localized-deletion-of-elements-of-composite-types">perlsub
Localized deletion of elements of composite types</a>.
-</p>
-<pre class="verbatim"> %hash = (foo => 11, bar => 22, baz => 33);
- $scalar = delete $hash{foo}; # $scalar is 11
- $scalar = delete @hash{qw(foo bar)}; # $scalar is 22
- @array = delete @hash{qw(foo baz)}; # @array is (undef,33)
-</pre>
-<p>The following (inefficiently) deletes all the values of %HASH and @ARRAY:
-</p>
-<pre class="verbatim"> foreach $key (keys %HASH) {
- delete $HASH{$key};
- }
-
- foreach $index (0 .. $#ARRAY) {
- delete $ARRAY[$index];
- }
-</pre>
-<p>And so do these:
-</p>
-<pre class="verbatim"> delete @HASH{keys %HASH};
-
- delete @ARRAY[0 .. $#ARRAY];
-</pre>
-<p>But both are slower than assigning the empty list
-or undefining %HASH or @ARRAY, which is the customary
-way to empty out an aggregate:
-</p>
-<pre class="verbatim"> %HASH = (); # completely empty %HASH
- undef %HASH; # forget %HASH ever existed
-
- @ARRAY = (); # completely empty @ARRAY
- undef @ARRAY; # forget @ARRAY ever existed
-</pre>
-<p>The EXPR can be arbitrarily complicated provided its
-final operation is an element or slice of an aggregate:
-</p>
-<pre class="verbatim"> delete $ref->[$x][$y]{$key};
- delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};
-
- delete $ref->[$x][$y][$index];
- delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
-</pre>
-</dd>
-<dt>die LIST</dt>
-<dd><a name="perlfunc-die-LIST"></a>
-<p><code>die</code> raises an exception. Inside an <code>eval</code> the
error message is stuffed
-into <code>$@</code> and the <code>eval</code> is terminated with the
undefined value.
-If the exception is outside of all enclosing <code>eval</code>s, then the
uncaught
-exception prints LIST to <code>STDERR</code> and exits with a non-zero value.
If you
-need to exit the process with a specific exit code, see <a
href="#perlfunc-exit">exit</a>.
-</p>
-<p>Equivalent examples:
-</p>
-<pre class="verbatim"> die "Can't cd to spool: $!\n" unless chdir
'/usr/spool/news';
- chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
-</pre>
-<p>If the last element of LIST does not end in a newline, the current
-script line number and input line number (if any) are also printed,
-and a newline is supplied. Note that the "input line number" (also
-known as "chunk") is subject to whatever notion of "line"
happens to
-be currently in effect, and is also available as the special variable
-<code>$.</code>. See <a href="#perlvar-_0024_002f">perlvar $/</a> and <a
href="#perlvar-_0024_002e">perlvar $.</a>.
-</p>
-<p>Hint: sometimes appending <code>", stopped"</code> to your
message will cause it
-to make better sense when the string <code>"at foo line 123"</code>
is appended.
-Suppose you are running script "canasta".
-</p>
-<pre class="verbatim"> die "/etc/games is no good";
- die "/etc/games is no good, stopped";
-</pre>
-<p>produce, respectively
-</p>
-<pre class="verbatim"> /etc/games is no good at canasta line 123.
- /etc/games is no good, stopped at canasta line 123.
-</pre>
-<p>If the output is empty and <code>$@</code> already contains a value
(typically from a
-previous eval) that value is reused after appending
<code>"\t...propagated"</code>.
-This is useful for propagating exceptions:
-</p>
-<pre class="verbatim"> eval { ... };
- die unless $@ =~ /Expected exception/;
-</pre>
-<p>If the output is empty and <code>$@</code> contains an object reference
that has a
-<code>PROPAGATE</code> method, that method will be called with additional file
-and line number parameters. The return value replaces the value in
-<code>$@</code>; i.e., as if <code>$@ = eval {
address@hidden>PROPAGATE(__FILE__, __LINE__) };</code>
-were called.
-</p>
-<p>If <code>$@</code> is empty then the string <code>"Died"</code>
is used.
-</p>
-<p>If an uncaught exception results in interpreter exit, the exit code is
-determined from the values of <code>$!</code> and <code>$?</code> with this
pseudocode:
-</p>
-<pre class="verbatim"> exit $! if $!; # errno
- exit $? >> 8 if $? >> 8; # child exit status
- exit 255; # last resort
-</pre>
-<p>The intent is to squeeze as much possible information about the likely cause
-into the limited space of the system exit
-code. However, as <code>$!</code> is the value
-of C’s <code>errno</code>, which can be set by any system call, this
means that the value
-of the exit code used by <code>die</code> can be non-predictable, so should
not be relied
-upon, other than to be non-zero.
-</p>
-<p>You can also call <code>die</code> with a reference argument, and if this
is trapped
-within an <code>eval</code>, <code>$@</code> contains that reference. This
permits more
-elaborate exception handling using objects that maintain arbitrary state
-about the exception. Such a scheme is sometimes preferable to matching
-particular string values of <code>$@</code> with regular expressions. Because
<code>$@</code>
-is a global variable and <code>eval</code> may be used within object
implementations,
-be careful that analyzing the error object doesn’t replace the reference
in
-the global variable. It’s easiest to make a local copy of the reference
-before any manipulations. Here’s an example:
-</p>
-<pre class="verbatim"> use Scalar::Util "blessed";
-
- eval { ... ; die Some::Module::Exception->new( FOO =>
"bar" ) };
- if (my $ev_err = $@) {
- if (blessed($ev_err)
- && $ev_err->isa("Some::Module::Exception")) {
- # handle Some::Module::Exception
- }
- else {
- # handle all other possible exceptions
- }
- }
-</pre>
-<p>Because Perl stringifies uncaught exception messages before display,
-you’ll probably want to overload stringification operations on
-exception objects. See <a href="overload.html#Top">(overload)</a> for details
about that.
-</p>
-<p>You can arrange for a callback to be run just before the <code>die</code>
-does its deed, by setting the <code>$SIG{__DIE__}</code> hook. The associated
-handler is called with the error text and can change the error
-message, if it sees fit, by calling <code>die</code> again. See
-<a href="#perlvar-_0025SIG">perlvar %SIG</a> for details on setting
<code>%SIG</code> entries, and
-<a href="#perlfunc-eval-BLOCK">eval BLOCK</a> for some examples. Although
this feature was
-to be run only right before your program was to exit, this is not
-currently so: the <code>$SIG{__DIE__}</code> hook is currently called
-even inside eval()ed blocks/strings! If one wants the hook to do
-nothing in such situations, put
-</p>
-<pre class="verbatim"> die @_ if $^S;
-</pre>
-<p>as the first line of the handler (see <a
href="#perlvar-_0024_005eS">perlvar $^S</a>). Because
-this promotes strange action at a distance, this counterintuitive
-behavior may be fixed in a future release.
-</p>
-<p>See also exit(), warn(), and the Carp module.
-</p>
-</dd>
-<dt>do BLOCK</dt>
-<dd><a name="perlfunc-do-BLOCK"></a>
-<p>Not really a function. Returns the value of the last command in the
-sequence of commands indicated by BLOCK. When modified by the
<code>while</code> or
-<code>until</code> loop modifier, executes the BLOCK once before testing the
loop
-condition. (On other statements the loop modifiers test the conditional
-first.)
-</p>
-<p><code>do BLOCK</code> does <em>not</em> count as a loop, so the loop
control statements
-<code>next</code>, <code>last</code>, or <code>redo</code> cannot be used to
leave or restart the block.
-See <a href="#perlsyn-NAME">perlsyn NAME</a> for alternative strategies.
-</p>
-</dd>
-<dt>do EXPR</dt>
-<dd><a name="perlfunc-do-EXPR"></a>
-<p>Uses the value of EXPR as a filename and executes the contents of the
-file as a Perl script.
-</p>
-<pre class="verbatim"> do 'stat.pl';
-</pre>
-<p>is largely like
-</p>
-<pre class="verbatim"> eval `cat stat.pl`;
-</pre>
-<p>except that it’s more concise, runs no external processes, keeps
track of
-the current
-filename for error messages, searches the <code>@INC</code> directories, and
updates
-<code>%INC</code> if the file is found. See <a
href="#perlvar-_0040INC">perlvar @INC</a> and <a
href="#perlvar-_0025INC">perlvar %INC</a> for
-these variables. It also differs in that code evaluated with <code>do
FILENAME</code>
-cannot see lexicals in the enclosing scope; <code>eval STRING</code> 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.
-</p>
-<p>If <code>do</code> can read the file but cannot compile it, it returns
<code>undef</code> and sets
-an error message in <code>$@</code>. If <code>do</code> cannot read the file,
it returns undef
-and sets <code>$!</code> to the error. Always check <code>$@</code> first, as
compilation
-could fail in a way that also sets <code>$!</code>. If the file is
successfully
-compiled, <code>do</code> returns the value of the last expression evaluated.
-</p>
-<p>Inclusion of library modules is better done with the
-<code>use</code> and <code>require</code> operators, which also do automatic
error checking
-and raise an exception if there’s a problem.
-</p>
-<p>You might like to use <code>do</code> to read in a program configuration
-file. Manual error checking can be done this way:
-</p>
-<pre class="verbatim"> # read in config files: system first, then user
- for $file ("/share/prog/defaults.rc",
- "$ENV{HOME}/.someprogrc")
- {
- unless ($return = do $file) {
- warn "couldn't parse $file: $@" if $@;
- warn "couldn't do $file: $!" unless defined $return;
- warn "couldn't run $file" unless $return;
- }
- }
-</pre>
-</dd>
-<dt>dump LABEL</dt>
-<dd><a name="perlfunc-dump-LABEL"></a>
-</dd>
-<dt>dump EXPR</dt>
-<dd><a name="perlfunc-dump-EXPR"></a>
-</dd>
-<dt>dump</dt>
-<dd><a name="perlfunc-dump"></a>
-<p>This function causes an immediate core dump. See also the
<strong>-u</strong>
-command-line switch in <a href="#perlrun-NAME">perlrun NAME</a>, which does
the same thing.
-Primarily this is so that you can use the <strong>undump</strong> program (not
-supplied) to turn your core dump into an executable binary after
-having initialized all your variables at the beginning of the
-program. When the new binary is executed it will begin by executing
-a <code>goto LABEL</code> (with all the restrictions that <code>goto</code>
suffers).
-Think of it as a goto with an intervening core dump and reincarnation.
-If <code>LABEL</code> is omitted, restarts the program from the top. The
-<code>dump EXPR</code> form, available starting in Perl 5.18.0, allows a name
to be
-computed at run time, being otherwise identical to <code>dump LABEL</code>.
-</p>
-<p><strong>WARNING</strong>: Any files opened at the time of the dump will
<em>not</em>
-be open any more when the program is reincarnated, with possible
-resulting confusion by Perl.
-</p>
-<p>This function is now largely obsolete, mostly because it’s very hard
to
-convert a core file into an executable. That’s why you should now invoke
-it as <code>CORE::dump()</code>, if you don’t want to be warned against
a possible
-typo.
-</p>
-<p>Unlike most named operators, this has the same precedence as assignment.
-It is also exempt from the looks-like-a-function rule, so
-<code>dump ("foo")."bar"</code> will cause "bar"
to be part of the argument to
-<code>dump</code>.
-</p>
-<p>Portability issues: <a href="#perlport-dump">perlport dump</a>.
-</p>
-</dd>
-<dt>each HASH</dt>
-<dd><a name="perlfunc-each-HASH"></a>
-</dd>
-<dt>each ARRAY</dt>
-<dd><a name="perlfunc-each-ARRAY"></a>
-</dd>
-<dt>each EXPR</dt>
-<dd><a name="perlfunc-each-EXPR"></a>
-<p>When called on a hash in list context, returns a 2-element list
-consisting of the key and value for the next element of a hash. In Perl
-5.12 and later only, it will also return the index and value for the next
-element of an array so that you can iterate over it; older Perls consider
-this a syntax error. When called in scalar context, returns only the key
-(not the value) in a hash, or the index in an array.
-</p>
-<p>Hash entries are returned in an apparently random order. The actual random
-order is specific to a given hash; the exact same series of operations
-on two hashes may result in a different order for each hash. Any insertion
-into the hash may change the order, as will any deletion, with the exception
-that the most recent key returned by <code>each</code> or <code>keys</code>
may be deleted
-without changing the order. So long as a given hash is unmodified you may
-rely on <code>keys</code>, <code>values</code> and <code>each</code> to
repeatedly return the same order
-as each other. See <a href="#perlsec-Algorithmic-Complexity-Attacks">perlsec
Algorithmic Complexity Attacks</a> for
-details on why hash order is randomized. Aside from the guarantees
-provided here the exact details of Perl’s hash algorithm and the hash
-traversal order are subject to change in any release of Perl.
-</p>
-<p>After <code>each</code> has returned all entries from the hash or array,
the next
-call to <code>each</code> returns the empty list in list context and
<code>undef</code> in
-scalar context; the next call following <em>that</em> one restarts iteration.
-Each hash or array has its own internal iterator, accessed by
<code>each</code>,
-<code>keys</code>, and <code>values</code>. The iterator is implicitly reset
when <code>each</code> has
-reached the end as just described; it can be explicitly reset by calling
-<code>keys</code> or <code>values</code> on the hash or array. If you add or
delete a hash’s
-elements while iterating over it, the effect on the iterator is
-unspecified; for example, entries may be skipped or duplicated–so
don’t
-do that. Exception: It is always safe to delete the item most recently
-returned by <code>each()</code>, so the following code works properly:
-</p>
-<pre class="verbatim"> while (($key, $value) = each %hash) {
- print $key, "\n";
- delete $hash{$key}; # This is safe
- }
-</pre>
-<p>Tied hashes may have a different ordering behaviour to perl’s hash
-implementation.
-</p>
-<p>This prints out your environment like the printenv(1) program,
-but in a different order:
-</p>
-<pre class="verbatim"> while (($key,$value) = each %ENV) {
- print "$key=$value\n";
- }
-</pre>
-<p>Starting with Perl 5.14, <code>each</code> 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 <code>each</code> is considered highly
experimental.
-The exact behaviour may change in a future version of Perl.
-</p>
-<pre class="verbatim"> while (($key,$value) = each $hashref) { ... }
-</pre>
-<p>As of Perl 5.18 you can use a bare <code>each</code> in a
<code>while</code> loop,
-which will set <code>$_</code> on every iteration.
-</p>
-<pre class="verbatim"> while(each %ENV) {
- print "$_=$ENV{$_}\n";
- }
-</pre>
-<p>To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work <em>only</em> on Perls
of
-a recent vintage:
-</p>
-<pre class="verbatim"> use 5.012; # so keys/values/each work on arrays
- use 5.014; # so keys/values/each work on scalars (experimental)
- use 5.018; # so each assigns to $_ in a lone while test
-</pre>
-<p>See also <code>keys</code>, <code>values</code>, and <code>sort</code>.
-</p>
-</dd>
-<dt>eof FILEHANDLE</dt>
-<dd><a name="perlfunc-eof-FILEHANDLE"></a>
-</dd>
-<dt>eof ()</dt>
-<dd><a name="perlfunc-eof-_0028_0029"></a>
-</dd>
-<dt>eof</dt>
-<dd><a name="perlfunc-eof"></a>
-<p>Returns 1 if the next read on FILEHANDLE will return end of file
<em>or</em> 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 <code>ungetc</code>s it, so isn’t useful in an
-interactive context.) Do not read from a terminal file (or call
-<code>eof(FILEHANDLE)</code> on it) after end-of-file is reached. File types
such
-as terminals may lose the end-of-file condition if you do.
-</p>
-<p>An <code>eof</code> without an argument uses the last file read. Using
<code>eof()</code>
-with empty parentheses is different. It refers to the pseudo file
-formed from the files listed on the command line and accessed via the
-<code><></code> operator. Since <code><></code> isn’t
explicitly opened,
-as a normal filehandle is, an <code>eof()</code> before <code><></code>
has been
-used will cause <code>@ARGV</code> to be examined to determine if input is
-available. Similarly, an <code>eof()</code> after <code><></code> has
returned
-end-of-file will assume you are processing another <code>@ARGV</code> list,
-and if you haven’t set <code>@ARGV</code>, will read input from
<code>STDIN</code>;
-see <a href="#perlop-I_002fO-Operators">perlop I/O Operators</a>.
-</p>
-<p>In a <code>while (<>)</code> loop, <code>eof</code> or
<code>eof(ARGV)</code> can be used to
-detect the end of each file, whereas <code>eof()</code> will detect the end
-of the very last file only. Examples:
-</p>
-<pre class="verbatim"> # reset line numbering on each input file
- while (<>) {
- next if /^\s*#/; # skip comments
- print "$.\t$_";
- } continue {
- close ARGV if eof; # Not eof()!
- }
-
- # insert dashes just before last line of last file
- while (<>) {
- if (eof()) { # check for end of last file
- print "--------------\n";
- }
- print;
- last if eof(); # needed if we're reading from a terminal
- }
-</pre>
-<p>Practical hint: you almost never need to use <code>eof</code> in Perl,
because the
-input operators typically return <code>undef</code> when they run out of data
or
-encounter an error.
-</p>
-</dd>
-<dt>eval EXPR</dt>
-<dd><a name="perlfunc-eval-EXPR"></a>
-</dd>
-<dt>eval BLOCK</dt>
-<dd><a name="perlfunc-eval-BLOCK"></a>
-</dd>
-<dt>eval</dt>
-<dd><a name="perlfunc-eval"></a>
-<p>In the first form, often referred to as a "string eval", the
return
-value of EXPR is parsed and executed as if it
-were a little Perl program. The value of the expression (which is itself
-determined within scalar context) is first parsed, and if there were no
-errors, executed as a block within the lexical context of the current Perl
-program. This means, that in particular, any outer lexical variables are
-visible to it, and any package variable settings or subroutine and format
-definitions remain afterwards.
-</p>
-<p>Note that the value is parsed every time the <code>eval</code> executes.
-If EXPR is omitted, evaluates <code>$_</code>. This form is typically used to
-delay parsing and subsequent execution of the text of EXPR until run time.
-</p>
-<p>If the <code>unicode_eval</code> feature is enabled (which is the default
under a
-<code>use 5.16</code> or higher declaration), EXPR or <code>$_</code> is
treated as a string of
-characters, so <code>use utf8</code> declarations have no effect, and source
filters
-are forbidden. In the absence of the <code>unicode_eval</code> feature, the
string
-will sometimes be treated as characters and sometimes as bytes, depending
-on the internal encoding, and source filters activated within the
<code>eval</code>
-exhibit the erratic, but historical, behaviour of affecting some outer file
-scope that is still compiling. See also the <a
href="#perlfunc-evalbytes">evalbytes</a> keyword, which
-always treats its input as a byte stream and works properly with source
-filters, and the <a href="feature.html#Top">(feature)</a> pragma.
-</p>
-<p>Problems can arise if the string expands a scalar containing a floating
-point number. That scalar can expand to letters, such as
<code>"NaN"</code> or
-<code>"Infinity"</code>; or, within the scope of a <code>use
locale</code>, the decimal
-point character may be something other than a dot (such as a comma).
-None of these are likely to parse as you are likely expecting.
-</p>
-<p>In the second form, the code within the BLOCK is parsed only once–at
the
-same time the code surrounding the <code>eval</code> itself was
parsed–and executed
-within the context of the current Perl program. This form is typically
-used to trap exceptions more efficiently than the first (see below), while
-also providing the benefit of checking the code within BLOCK at compile
-time.
-</p>
-<p>The final semicolon, if any, may be omitted from the value of EXPR or within
-the BLOCK.
-</p>
-<p>In both forms, the value returned is the value of the last expression
-evaluated inside the mini-program; a return statement may be also used, just
-as with subroutines. The expression providing the return value is evaluated
-in void, scalar, or list context, depending on the context of the
<code>eval</code>
-itself. See <a href="#perlfunc-wantarray">wantarray</a> for more on how the
evaluation context can be
-determined.
-</p>
-<p>If there is a syntax error or runtime error, or a <code>die</code>
statement is
-executed, <code>eval</code> returns <code>undef</code> in scalar context
-or an empty list in list context, and <code>$@</code> is set to the error
-message. (Prior to 5.16, a bug caused <code>undef</code> to be returned
-in list context for syntax errors, but not for runtime errors.)
-If there was no error, <code>$@</code> is set to the empty string. A
-control flow operator like <code>last</code> or <code>goto</code> can bypass
the setting of
-<code>$@</code>. Beware that using <code>eval</code> neither silences Perl
from printing
-warnings to STDERR, nor does it stuff the text of warning messages into
<code>$@</code>.
-To do either of those, you have to use the <code>$SIG{__WARN__}</code>
facility, or
-turn off warnings inside the BLOCK or EXPR using
<code>no warnings 'all'</code><!-- /@w -->.
-See ‘warn’, <a href="#perlvar-NAME">perlvar NAME</a>, and <a
href="warnings.html#Top">(warnings)</a>.
-</p>
-<p>Note that, because <code>eval</code> traps otherwise-fatal errors, it is
useful for
-determining whether a particular feature (such as <code>socket</code> or
<code>symlink</code>)
-is implemented. It is also Perl’s exception-trapping mechanism, where
-the die operator is used to raise exceptions.
-</p>
-<p>If you want to trap errors when loading an XS module, some problems with
-the binary interface (such as Perl version skew) may be fatal even with
-<code>eval</code> unless <code>$ENV{PERL_DL_NONLAZY}</code> is set. See <a
href="#perlrun-NAME">perlrun NAME</a>.
-</p>
-<p>If the code to be executed doesn’t vary, you may use the eval-BLOCK
-form to trap run-time errors without incurring the penalty of
-recompiling each time. The error, if any, is still returned in
<code>$@</code>.
-Examples:
-</p>
-<pre class="verbatim"> # make divide-by-zero nonfatal
- eval { $answer = $a / $b; }; warn $@ if $@;
-
- # same thing, but less efficient
- eval '$answer = $a / $b'; warn $@ if $@;
-
- # a compile-time error
- eval { $answer = }; # WRONG
-
- # a run-time error
- eval '$answer ='; # sets $@
-</pre>
-<p>Using the <code>eval{}</code> form as an exception trap in libraries does
have some
-issues. Due to the current arguably broken state of <code>__DIE__</code>
hooks, you
-may wish not to trigger any <code>__DIE__</code> hooks that user code may have
installed.
-You can use the <code>local $SIG{__DIE__}</code> construct for this purpose,
-as this example shows:
-</p>
-<pre class="verbatim"> # a private exception trap for divide-by-zero
- eval { local $SIG{'__DIE__'}; $answer = $a / $b; };
- warn $@ if $@;
-</pre>
-<p>This is especially significant, given that <code>__DIE__</code> hooks can
call
-<code>die</code> again, which has the effect of changing their error messages:
-</p>
-<pre class="verbatim"> # __DIE__ hooks may modify error messages
- {
- local $SIG{'__DIE__'} =
- sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
- eval { die "foo lives here" };
- print $@ if $@; # prints "bar lives here"
- }
-</pre>
-<p>Because this promotes action at a distance, this counterintuitive behavior
-may be fixed in a future release.
-</p>
-<p>With an <code>eval</code>, you should be especially careful to remember
what’s
-being looked at when:
-</p>
-<pre class="verbatim"> eval $x; # CASE 1
- eval "$x"; # CASE 2
-
- eval '$x'; # CASE 3
- eval { $x }; # CASE 4
-
- eval "\$$x++"; # CASE 5
- $$x++; # CASE 6
-</pre>
-<p>Cases 1 and 2 above behave identically: they run the code contained in
-the variable $x. (Although case 2 has misleading double quotes making
-the reader wonder what else might be happening (nothing is).) Cases 3
-and 4 likewise behave in the same way: they run the code <code>'$x'</code>,
which
-does nothing but return the value of $x. (Case 4 is preferred for
-purely visual reasons, but it also has the advantage of compiling at
-compile-time instead of at run-time.) Case 5 is a place where
-normally you <em>would</em> like to use double quotes, except that in this
-particular situation, you can just use symbolic references instead, as
-in case 6.
-</p>
-<p>Before Perl 5.14, the assignment to <code>$@</code> occurred before
restoration
-of localized variables, which means that for your code to run on older
-versions, a temporary is required if you want to mask some but not all
-errors:
-</p>
-<pre class="verbatim"> # alter $@ on nefarious repugnancy only
- {
- my $e;
- {
- local $@; # protect existing $@
- eval { test_repugnancy() };
- # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only
- $@ =~ /nefarious/ and $e = $@;
- }
- die $e if defined $e
- }
-</pre>
-<p><code>eval BLOCK</code> does <em>not</em> count as a loop, so the loop
control statements
-<code>next</code>, <code>last</code>, or <code>redo</code> cannot be used to
leave or restart the block.
-</p>
-<p>An <code>eval ''</code> executed within a subroutine defined
-in the <code>DB</code> package doesn’t see the usual
-surrounding lexical scope, but rather the scope of the first non-DB piece
-of code that called it. You don’t normally need to worry about this
unless
-you are writing a Perl debugger.
-</p>
-</dd>
-<dt>evalbytes EXPR</dt>
-<dd><a name="perlfunc-evalbytes-EXPR"></a>
-</dd>
-<dt>evalbytes</dt>
-<dd><a name="perlfunc-evalbytes"></a>
-<p>This function is like <a href="#perlfunc-eval">eval</a> with a string
argument, except it always
-parses its argument, or <code>$_</code> if EXPR is omitted, as a string of
bytes. A
-string containing characters whose ordinal value exceeds 255 results in an
-error. Source filters activated within the evaluated code apply to the
-code itself.
-</p>
-<p>This function is only available under the <code>evalbytes</code> feature, a
-<code>use v5.16</code> (or higher) declaration, or with a <code>CORE::</code>
prefix. See
-<a href="feature.html#Top">(feature)</a> for more information.
-</p>
-</dd>
-<dt>exec LIST</dt>
-<dd><a name="perlfunc-exec-LIST"></a>
-</dd>
-<dt>exec PROGRAM LIST</dt>
-<dd><a name="perlfunc-exec-PROGRAM-LIST"></a>
-<p>The <code>exec</code> function executes a system command <em>and never
returns</em>;
-use <code>system</code> instead of <code>exec</code> if you want it to return.
It fails and
-returns false only if the command does not exist <em>and</em> it is executed
-directly instead of via your system’s command shell (see below).
-</p>
-<p>Since it’s a common mistake to use <code>exec</code> instead of
<code>system</code>, Perl
-warns you if <code>exec</code> is called in void context and if there is a
following
-statement that isn’t <code>die</code>, <code>warn</code>, or
<code>exit</code> (if <code>-w</code> is set–but
-you always do that, right?). If you <em>really</em> want to follow an
<code>exec</code>
-with some other statement, you can use one of these styles to avoid the
warning:
-</p>
-<pre class="verbatim"> exec ('foo') or print STDERR "couldn't exec
foo: $!";
- { exec ('foo') }; print STDERR "couldn't exec foo: $!";
-</pre>
-<p>If there is more than one argument in LIST, this calls execvp(3) with the
-arguments in LIST. If there is only one element in LIST, the argument is
-checked for shell metacharacters, and if there are any, the entire
-argument is passed to the system’s command shell for parsing (this is
-<code>/bin/sh -c</code> on Unix platforms, but varies on other platforms). If
-there are no shell metacharacters in the argument, it is split into words
-and passed directly to <code>execvp</code>, which is more efficient. Examples:
-</p>
-<pre class="verbatim"> exec '/bin/echo', 'Your arguments are: ', @ARGV;
- exec "sort $outfile | uniq";
-</pre>
-<p>If you don’t really want to execute the first argument, but want to
lie
-to the program you are executing about its own name, you can specify
-the program you actually want to run as an "indirect object"
(without a
-comma) in front of the LIST, as in <code>exec PROGRAM LIST</code>. (This
always
-forces interpretation of the LIST as a multivalued list, even if there
-is only a single scalar in the list.) Example:
-</p>
-<pre class="verbatim"> $shell = '/bin/csh';
- exec $shell '-sh'; # pretend it's a login shell
-</pre>
-<p>or, more directly,
-</p>
-<pre class="verbatim"> exec {'/bin/csh'} '-sh'; # pretend it's a login
shell
-</pre>
-<p>When the arguments get executed via the system shell, results are
-subject to its quirks and capabilities. See <a
href="#perlop-_0060STRING_0060">perlop <code>`<em>STRING</em>`</code></a>
-for details.
-</p>
-<p>Using an indirect object with <code>exec</code> or <code>system</code> is
also more
-secure. This usage (which also works fine with system()) forces
-interpretation of the arguments as a multivalued list, even if the
-list had just one argument. That way you’re safe from the shell
-expanding wildcards or splitting up words with whitespace in them.
-</p>
-<pre class="verbatim"> @args = ( "echo surprise" );
-
- exec @args; # subject to shell escapes
- # if @args == 1
- exec { $args[0] } @args; # safe even with one-arg list
-</pre>
-<p>The first version, the one without the indirect object, ran the
<em>echo</em>
-program, passing it <code>"surprise"</code> an argument. The second
version didn’t;
-it tried to run a program named <em>"echo surprise"</em>,
didn’t find it, and set
-<code>$?</code> to a non-zero value indicating failure.
-</p>
-<p>On Windows, only the <code>exec PROGRAM LIST</code> indirect object syntax
will
-reliably avoid using the shell; <code>exec LIST</code>, even with more than one
-element, will fall back to the shell if the first spawn fails.
-</p>
-<p>Perl attempts to flush all files opened for output before the exec,
-but this may not be supported on some platforms (see <a
href="#perlport-NAME">perlport NAME</a>).
-To be safe, you may need to set <code>$|</code> ($AUTOFLUSH in English) or
-call the <code>autoflush()</code> method of <code>IO::Handle</code> on any
open handles
-to avoid lost output.
-</p>
-<p>Note that <code>exec</code> will not call your <code>END</code> blocks, nor
will it invoke
-<code>DESTROY</code> methods on your objects.
-</p>
-<p>Portability issues: <a href="#perlport-exec">perlport exec</a>.
-</p>
-</dd>
-<dt>exists EXPR</dt>
-<dd><a name="perlfunc-exists-EXPR"></a>
-<p>Given an expression that specifies an element of a hash, returns true if the
-specified element in the hash has ever been initialized, even if the
-corresponding value is undefined.
-</p>
-<pre class="verbatim"> print "Exists\n" if exists $hash{$key};
- print "Defined\n" if defined $hash{$key};
- print "True\n" if $hash{$key};
-</pre>
-<p>exists may also be called on array elements, but its behavior is much less
-obvious and is strongly tied to the use of ‘delete’ on arrays.
-</p>
-<p><strong>WARNING:</strong> Calling <code>exists</code> on array values is
strongly discouraged. The
-notion of deleting or checking the existence of Perl array elements is not
-conceptually coherent, and can lead to surprising behavior.
-</p>
-<pre class="verbatim"> print "Exists\n" if exists
$array[$index];
- print "Defined\n" if defined $array[$index];
- print "True\n" if $array[$index];
-</pre>
-<p>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.
-</p>
-<p>Given an expression that specifies the name of a subroutine,
-returns true if the specified subroutine has ever been declared, even
-if it is undefined. Mentioning a subroutine name for exists or defined
-does not count as declaring it. Note that a subroutine that does not
-exist may still be callable: its package may have an <code>AUTOLOAD</code>
-method that makes it spring into existence the first time that it is
-called; see <a href="#perlsub-NAME">perlsub NAME</a>.
-</p>
-<pre class="verbatim"> print "Exists\n" if exists
&subroutine;
- print "Defined\n" if defined &subroutine;
-</pre>
-<p>Note that the EXPR can be arbitrarily complicated as long as the final
-operation is a hash or array key lookup or subroutine name:
-</p>
-<pre class="verbatim"> if (exists $ref->{A}->{B}->{$key}) { }
- if (exists $hash{A}{B}{$key}) { }
-
- if (exists $ref->{A}->{B}->[$ix]) { }
- if (exists $hash{A}{B}[$ix]) { }
-
- if (exists &{$ref->{A}{B}{$key}}) { }
-</pre>
-<p>Although the most deeply nested array or hash element will not spring into
-existence just because its existence was tested, any intervening ones will.
-Thus <code>$ref->{"A"}</code> and
<code>$ref->{"A"}->{"B"}</code> will spring
-into existence due to the existence test for the $key element above.
-This happens anywhere the arrow operator is used, including even here:
-</p>
-<pre class="verbatim"> undef $ref;
- if (exists $ref->{"Some key"}) { }
- print $ref; # prints HASH(0x80d3d5c)
-</pre>
-<p>This surprising autovivification in what does not at first–or even
-second–glance appear to be an lvalue context may be fixed in a future
-release.
-</p>
-<p>Use of a subroutine call, rather than a subroutine name, as an argument
-to exists() is an error.
-</p>
-<pre class="verbatim"> exists &sub; # OK
- exists &sub(); # Error
-</pre>
-</dd>
-<dt>exit EXPR</dt>
-<dd><a name="perlfunc-exit-EXPR"></a>
-</dd>
-<dt>exit</dt>
-<dd><a name="perlfunc-exit"></a>
-<p>Evaluates EXPR and exits immediately with that value. Example:
-</p>
-<pre class="verbatim"> $ans = <STDIN>;
- exit 0 if $ans =~ /^[Xx]/;
-</pre>
-<p>See also <code>die</code>. If EXPR is omitted, exits with <code>0</code>
status. The only
-universally recognized values for EXPR are <code>0</code> for success and
<code>1</code>
-for error; other values are subject to interpretation depending on the
-environment in which the Perl program is running. For example, exiting
-69 (EX_UNAVAILABLE) from a <em>sendmail</em> incoming-mail filter will cause
-the mailer to return the item undelivered, but that’s not true
everywhere.
-</p>
-<p>Don’t use <code>exit</code> to abort a subroutine if there’s
any chance that
-someone might want to trap whatever error happened. Use <code>die</code>
instead,
-which can be trapped by an <code>eval</code>.
-</p>
-<p>The exit() function does not always exit immediately. It calls any
-defined <code>END</code> routines first, but these <code>END</code> routines
may not
-themselves abort the exit. Likewise any object destructors that need to
-be called are called before the real exit. <code>END</code> routines and
destructors
-can change the exit status by modifying <code>$?</code>. If this is a
problem, you
-can call <code>POSIX::_exit($status)</code> to avoid END and destructor
processing.
-See <a href="#perlmod-NAME">perlmod NAME</a> for details.
-</p>
-<p>Portability issues: <a href="#perlport-exit">perlport exit</a>.
-</p>
-</dd>
-<dt>exp EXPR</dt>
-<dd><a name="perlfunc-exp-EXPR"></a>
-</dd>
-<dt>exp</dt>
-<dd><a name="perlfunc-exp"></a>
-<p>Returns <em>e</em> (the natural logarithm base) to the power of EXPR.
-If EXPR is omitted, gives <code>exp($_)</code>.
-</p>
-</dd>
-<dt>fc EXPR</dt>
-<dd><a name="perlfunc-fc-EXPR"></a>
-</dd>
-<dt>fc</dt>
-<dd><a name="perlfunc-fc"></a>
-<p>Returns the casefolded version of EXPR. This is the internal function
-implementing the <code>\F</code> escape in double-quoted strings.
-</p>
-<p>Casefolding is the process of mapping strings to a form where case
-differences are erased; comparing two strings in their casefolded
-form is effectively a way of asking if two strings are equal,
-regardless of case.
-</p>
-<p>Roughly, if you ever found yourself writing this
-</p>
-<pre class="verbatim"> lc($this) eq lc($that) # Wrong!
- # or
- uc($this) eq uc($that) # Also wrong!
- # or
- $this =~ /^\Q$that\E\z/i # Right!
-</pre>
-<p>Now you can write
-</p>
-<pre class="verbatim"> fc($this) eq fc($that)
-</pre>
-<p>And get the correct results.
-</p>
-<p>Perl only implements the full form of casefolding,
-but you can access the simple folds using <a
href="Unicode-UCD.html#casefold_0028_0029">(Unicode-UCD)casefold()</a> and
-<a
href="Unicode-UCD.html#prop_005finvmap_0028_0029">(Unicode-UCD)prop_invmap()</a>.
-For further information on casefolding, refer to
-the Unicode Standard, specifically sections 3.13 <code>Default Case
Operations</code>,
-4.2 <code>Case-Normative</code>, and 5.18 <code>Case Mappings</code>,
-available at <a
href="http://www.unicode.org/versions/latest/";>http://www.unicode.org/versions/latest/</a>,
as well as the
-Case Charts available at <a
href="http://www.unicode.org/charts/case/";>http://www.unicode.org/charts/case/</a>.
-</p>
-<p>If EXPR is omitted, uses <code>$_</code>.
-</p>
-<p>This function behaves the same way under various pragma, such as within
-<code>"use feature <span
class="nolinebreak">'unicode_strings"</span></code><!-- /@w -->, as <a
href="#perlfunc-lc">lc</a> does, with the single
-exception of <code>fc</code> of LATIN CAPITAL LETTER SHARP S (U+1E9E) within
the
-scope of <code>use locale</code><!-- /@w -->. The foldcase of this
character would
-normally be <code>"ss"</code>, but as explained in the <a
href="#perlfunc-lc">lc</a> section, case
-changes that cross the 255/256 boundary are problematic under locales,
-and are hence prohibited. Therefore, this function under locale returns
-instead the string <code>"\x{17F}\x{17F}"</code>, which is the LATIN
SMALL LETTER
-LONG S. Since that character itself folds to <code>"s"</code>, the
string of two
-of them together should be equivalent to a single U+1E9E when foldcased.
-</p>
-<p>While the Unicode Standard defines two additional forms of casefolding,
-one for Turkic languages and one that never maps one character into multiple
-characters, these are not provided by the Perl core; However, the CPAN module
-<code>Unicode::Casing</code> may be used to provide an implementation.
-</p>
-<p>This keyword is available only when the <code>"fc"</code> feature
is enabled,
-or when prefixed with <code>CORE::</code>; See <a
href="feature.html#Top">(feature)</a>. Alternately,
-include a <code>use v5.16</code> or later to the current scope.
-</p>
-</dd>
-<dt>fcntl FILEHANDLE,FUNCTION,SCALAR</dt>
-<dd><a name="perlfunc-fcntl-FILEHANDLE_002cFUNCTION_002cSCALAR"></a>
-<p>Implements the fcntl(2) function. You’ll probably have to say
-</p>
-<pre class="verbatim"> use Fcntl;
-</pre>
-<p>first to get the correct constant definitions. Argument processing and
-value returned work just like <code>ioctl</code> below.
-For example:
-</p>
-<pre class="verbatim"> use Fcntl;
- fcntl($filehandle, F_GETFL, $packed_return_buffer)
- or die "can't fcntl F_GETFL: $!";
-</pre>
-<p>You don’t have to check for <code>defined</code> on the return from
<code>fcntl</code>.
-Like <code>ioctl</code>, it maps a <code>0</code> return from the system call
into
-<code>"0 but true"</code> in Perl. This string is true in boolean
context and <code>0</code>
-in numeric context. It is also exempt from the normal <strong>-w</strong>
warnings
-on improper numeric conversions.
-</p>
-<p>Note that <code>fcntl</code> raises an exception if used on a machine that
-doesn’t implement fcntl(2). See the Fcntl module or your fcntl(2)
-manpage to learn what functions are available on your system.
-</p>
-<p>Here’s an example of setting a filehandle named <code>REMOTE</code>
to be
-non-blocking at the system level. You’ll have to negotiate
<code>$|</code>
-on your own, though.
-</p>
-<pre class="verbatim"> use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
-
- $flags = fcntl(REMOTE, F_GETFL, 0)
- or die "Can't get flags for the socket: $!\n";
-
- $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
- or die "Can't set flags for the socket: $!\n";
-</pre>
-<p>Portability issues: <a href="#perlport-fcntl">perlport fcntl</a>.
-</p>
-</dd>
-<dt>__FILE__</dt>
-<dd><a name="perlfunc-_005f_005fFILE_005f_005f"></a>
-<p>A special token that returns the name of the file in which it occurs.
-</p>
-</dd>
-<dt>fileno FILEHANDLE</dt>
-<dd><a name="perlfunc-fileno-FILEHANDLE"></a>
-<p>Returns the file descriptor for a filehandle, or undefined if the
-filehandle is not open. If there is no real file descriptor at the OS
-level, as can happen with filehandles connected to memory objects via
-<code>open</code> with a reference for the third argument, -1 is returned.
-</p>
-<p>This is mainly useful for constructing
-bitmaps for <code>select</code> and low-level POSIX tty-handling operations.
-If FILEHANDLE is an expression, the value is taken as an indirect
-filehandle, generally its name.
-</p>
-<p>You can use this to find out whether two handles refer to the
-same underlying descriptor:
-</p>
-<pre class="verbatim"> if (fileno(THIS) != -1 && fileno(THIS) ==
fileno(THAT)) {
- print "THIS and THAT are dups\n";
- } elsif (fileno(THIS) != -1 && fileno(THAT) != -1) {
- print "THIS and THAT have different " .
- "underlying file descriptors\n";
- } else {
- print "At least one of THIS and THAT does " .
- "not have a real file descriptor\n";
- }
-</pre>
-<p>The behavior of <code>fileno</code> on a directory handle depends on the
operating
-system. On a system with dirfd(3) or similar, <code>fileno</code> on a
directory
-handle returns the underlying file descriptor associated with the
-handle; on systems with no such support, it returns the undefined value,
-and sets <code>$!</code> (errno).
-</p>
-</dd>
-<dt>flock FILEHANDLE,OPERATION</dt>
-<dd><a name="perlfunc-flock-FILEHANDLE_002cOPERATION"></a>
-<p>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).
-<code>flock</code> is Perl’s portable file-locking interface, although
it locks
-entire files only, not records.
-</p>
-<p>Two potentially non-obvious but traditional <code>flock</code> semantics are
-that it waits indefinitely until the lock is granted, and that its locks
-are <strong>merely advisory</strong>. Such discretionary locks are more
flexible, but
-offer fewer guarantees. This means that programs that do not also use
-<code>flock</code> may modify files locked with <code>flock</code>. See <a
href="#perlport-NAME">perlport NAME</a>,
-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
-"features"). Slavish adherence to portability concerns
shouldn’t get
-in the way of your getting your job done.)
-</p>
-<p>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 <a
href="Fcntl.html#Top">(Fcntl)</a> module,
-either individually, or as a group using the <code>:flock</code> 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 <code>flock</code> returns immediately rather than
blocking
-waiting for the lock; check the return status to see if you got it.
-</p>
-<p>To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE
-before locking or unlocking it.
-</p>
-<p>Note that the emulation built with lockf(3) doesn’t provide shared
-locks, and it requires that FILEHANDLE be open with write intent. These
-are the semantics that lockf(3) implements. Most if not all systems
-implement lockf(3) in terms of fcntl(2) locking, though, so the
-differing semantics shouldn’t bite too many people.
-</p>
-<p>Note that the fcntl(2) emulation of flock(3) requires that FILEHANDLE
-be open with read intent to use LOCK_SH and requires that it be open
-with write intent to use LOCK_EX.
-</p>
-<p>Note also that some versions of <code>flock</code> cannot lock things over
the
-network; you would need to use the more system-specific <code>fcntl</code> 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 <code>-Ud_flock</code> to the <samp>Configure</samp> program when
you configure
-and build a new Perl.
-</p>
-<p>Here’s a mailbox appender for BSD systems.
-</p>
-<pre class="verbatim"> # import LOCK_* and SEEK_END constants
- use Fcntl qw(:flock SEEK_END);
-
- sub lock {
- my ($fh) = @_;
- flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n";
-
- # and, in case someone appended while we were waiting...
- seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n";
- }
-
- sub unlock {
- my ($fh) = @_;
- flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n";
- }
-
- open(my $mbox, ">>",
"/usr/spool/mail/$ENV{'USER'}")
- or die "Can't open mailbox: $!";
-
- lock($mbox);
- print $mbox $msg,"\n\n";
- unlock($mbox);
-</pre>
-<p>On systems that support a real flock(2), locks are inherited across fork()
-calls, whereas those that must resort to the more capricious fcntl(2)
-function lose their locks, making it seriously harder to write servers.
-</p>
-<p>See also <a href="DB_File.html#Top">(DB_File)</a> for other flock()
examples.
-</p>
-<p>Portability issues: <a href="#perlport-flock">perlport flock</a>.
-</p>
-</dd>
-<dt>fork</dt>
-<dd><a name="perlfunc-fork"></a>
-<p>Does a fork(2) system call to create a new process running the
-same program at the same point. It returns the child pid to the
-parent process, <code>0</code> to the child process, or <code>undef</code> if
the fork is
-unsuccessful. File descriptors (and sometimes locks on those descriptors)
-are shared, while everything else is copied. On most systems supporting
-fork(), great care has gone into making it extremely efficient (for
-example, using copy-on-write technology on data pages), making it the
-dominant paradigm for multitasking over the last few decades.
-</p>
-<p>Perl attempts to flush all files opened for
-output before forking the child process, but this may not be supported
-on some platforms (see <a href="#perlport-NAME">perlport NAME</a>). To be
safe, you may need to set
-<code>$|</code> ($AUTOFLUSH in English) or call the <code>autoflush()</code>
method of
-<code>IO::Handle</code> on any open handles to avoid duplicate output.
-</p>
-<p>If you <code>fork</code> without ever waiting on your children, you will
-accumulate zombies. On some systems, you can avoid this by setting
-<code>$SIG{CHLD}</code> to <code>"IGNORE"</code>. See also <a
href="#perlipc-NAME">perlipc NAME</a> for more examples of
-forking and reaping moribund children.
-</p>
-<p>Note that if your forked child inherits system file descriptors like
-STDIN and STDOUT that are actually connected by a pipe or socket, even
-if you exit, then the remote server (such as, say, a CGI script or a
-backgrounded job launched from a remote shell) won’t think you’re
done.
-You should reopen those to <samp>/dev/null</samp> if it’s any issue.
-</p>
-<p>On some platforms such as Windows, where the fork() system call is not
available,
-Perl can be built to emulate fork() in the Perl interpreter.
-The emulation is designed, at the level of the Perl program,
-to be as compatible as possible with the "Unix" fork().
-However it has limitations that have to be considered in code intended to be
portable.
-See <a href="#perlfork-NAME">perlfork NAME</a> for more details.
-</p>
-<p>Portability issues: <a href="#perlport-fork">perlport fork</a>.
-</p>
-</dd>
-<dt>format</dt>
-<dd><a name="perlfunc-format"></a>
-<p>Declare a picture format for use by the <code>write</code> function. For
-example:
-</p>
-<pre class="verbatim"> format Something =
- Test: @<<<<<<<< @||||| @>>>>>
- $str, $%, '$' . int($num)
- .
-
- $str = "widget";
- $num = $cost/$quantity;
- $~ = 'Something';
- write;
-</pre>
-<p>See <a href="#perlform-NAME">perlform NAME</a> for many details and
examples.
-</p>
-</dd>
-<dt>formline PICTURE,LIST</dt>
-<dd><a name="perlfunc-formline-PICTURE_002cLIST"></a>
-<p>This is an internal function used by <code>format</code>s, though you may
call it,
-too. It formats (see <a href="#perlform-NAME">perlform NAME</a>) a list of
values according to the
-contents of PICTURE, placing the output into the format output
-accumulator, <code>$^A</code> (or <code>$ACCUMULATOR</code> in English).
-Eventually, when a <code>write</code> is done, the contents of
-<code>$^A</code> are written to some filehandle. You could also read
<code>$^A</code>
-and then set <code>$^A</code> back to <code>""</code>. Note that a
format typically
-does one <code>formline</code> per line of form, but the <code>formline</code>
function itself
-doesn’t care how many newlines are embedded in the PICTURE. This means
-that the <code>~</code> and <code>~~</code> tokens treat the entire PICTURE as
a single line.
-You may therefore need to use multiple formlines to implement a single
-record format, just like the <code>format</code> compiler.
-</p>
-<p>Be careful if you put double quotes around the picture, because an
<code>@</code>
-character may be taken to mean the beginning of an array name.
-<code>formline</code> always returns true. See <a
href="#perlform-NAME">perlform NAME</a> for other examples.
-</p>
-<p>If you are trying to use this instead of <code>write</code> to capture the
output,
-you may find it easier to open a filehandle to a scalar
-(<code>open $fh, ">", \$output</code>) and write to that instead.
-</p>
-</dd>
-<dt>getc FILEHANDLE</dt>
-<dd><a name="perlfunc-getc-FILEHANDLE"></a>
-</dd>
-<dt>getc</dt>
-<dd><a name="perlfunc-getc"></a>
-<p>Returns the next character from the input file attached to FILEHANDLE,
-or the undefined value at end of file or if there was an error (in
-the latter case <code>$!</code> is set). If FILEHANDLE is omitted, reads from
-STDIN. This is not particularly efficient. However, it cannot be
-used by itself to fetch single characters without waiting for the user
-to hit enter. For that, try something more like:
-</p>
-<pre class="verbatim"> if ($BSD_STYLE) {
- system "stty cbreak </dev/tty >/dev/tty 2>&1";
- }
- else {
- system "stty", '-icanon', 'eol', "\001";
- }
-
- $key = getc(STDIN);
-
- if ($BSD_STYLE) {
- system "stty -cbreak </dev/tty >/dev/tty 2>&1";
- }
- else {
- system 'stty', 'icanon', 'eol', '^@'; # ASCII NUL
- }
- print "\n";
-</pre>
-<p>Determination of whether $BSD_STYLE should be set
-is left as an exercise to the reader.
-</p>
-<p>The <code>POSIX::getattr</code> function can do this more portably on
-systems purporting POSIX compliance. See also the <code>Term::ReadKey</code>
-module from your nearest <a href="http://www.cpan.org";>CPAN</a> site.
-</p>
-</dd>
-<dt>getlogin</dt>
-<dd><a name="perlfunc-getlogin"></a>
-<p>This implements the C library function of the same name, which on most
-systems returns the current login from <samp>/etc/utmp</samp>, if any. If it
-returns the empty string, use <code>getpwuid</code>.
-</p>
-<pre class="verbatim"> $login = getlogin || getpwuid($<) ||
"Kilroy";
-</pre>
-<p>Do not consider <code>getlogin</code> for authentication: it is not as
-secure as <code>getpwuid</code>.
-</p>
-<p>Portability issues: <a href="#perlport-getlogin">perlport getlogin</a>.
-</p>
-</dd>
-<dt>getpeername SOCKET</dt>
-<dd><a name="perlfunc-getpeername-SOCKET"></a>
-<p>Returns the packed sockaddr address of the other end of the SOCKET
-connection.
-</p>
-<pre class="verbatim"> use Socket;
- $hersockaddr = getpeername(SOCK);
- ($port, $iaddr) = sockaddr_in($hersockaddr);
- $herhostname = gethostbyaddr($iaddr, AF_INET);
- $herstraddr = inet_ntoa($iaddr);
-</pre>
-</dd>
-<dt>getpgrp PID</dt>
-<dd><a name="perlfunc-getpgrp-PID"></a>
-<p>Returns the current process group for the specified PID. Use
-a PID of <code>0</code> 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 the process
-group of the current process. Note that the POSIX version of
<code>getpgrp</code>
-does not accept a PID argument, so only <code>PID==0</code> is truly portable.
-</p>
-<p>Portability issues: <a href="#perlport-getpgrp">perlport getpgrp</a>.
-</p>
-</dd>
-<dt>getppid</dt>
-<dd><a name="perlfunc-getppid"></a>
-<p>Returns the process id of the parent process.
-</p>
-<p>Note for Linux users: Between v5.8.1 and v5.16.0 Perl would work
-around non-POSIX thread semantics the minority of Linux systems (and
-Debian GNU/kFreeBSD systems) that used LinuxThreads, this emulation
-has since been removed. See the documentation for <a
href="#perlvar-_0024_0024">$$</a> for
-details.
-</p>
-<p>Portability issues: <a href="#perlport-getppid">perlport getppid</a>.
-</p>
-</dd>
-<dt>getpriority WHICH,WHO</dt>
-<dd><a name="perlfunc-getpriority-WHICH_002cWHO"></a>
-<p>Returns the current priority for a process, a process group, or a user.
-(See <a href="http://man.he.net/man2/getpriority";>getpriority(2)</a>.) Will
raise a fatal exception if used on a
-machine that doesn’t implement getpriority(2).
-</p>
-<p>Portability issues: <a href="#perlport-getpriority">perlport
getpriority</a>.
-</p>
-</dd>
-<dt>getpwnam NAME</dt>
-<dd><a name="perlfunc-getpwnam-NAME"></a>
-</dd>
-<dt>getgrnam NAME</dt>
-<dd><a name="perlfunc-getgrnam-NAME"></a>
-</dd>
-<dt>gethostbyname NAME</dt>
-<dd><a name="perlfunc-gethostbyname-NAME"></a>
-</dd>
-<dt>getnetbyname NAME</dt>
-<dd><a name="perlfunc-getnetbyname-NAME"></a>
-</dd>
-<dt>getprotobyname NAME</dt>
-<dd><a name="perlfunc-getprotobyname-NAME"></a>
-</dd>
-<dt>getpwuid UID</dt>
-<dd><a name="perlfunc-getpwuid-UID"></a>
-</dd>
-<dt>getgrgid GID</dt>
-<dd><a name="perlfunc-getgrgid-GID"></a>
-</dd>
-<dt>getservbyname NAME,PROTO</dt>
-<dd><a name="perlfunc-getservbyname-NAME_002cPROTO"></a>
-</dd>
-<dt>gethostbyaddr ADDR,ADDRTYPE</dt>
-<dd><a name="perlfunc-gethostbyaddr-ADDR_002cADDRTYPE"></a>
-</dd>
-<dt>getnetbyaddr ADDR,ADDRTYPE</dt>
-<dd><a name="perlfunc-getnetbyaddr-ADDR_002cADDRTYPE"></a>
-</dd>
-<dt>getprotobynumber NUMBER</dt>
-<dd><a name="perlfunc-getprotobynumber-NUMBER"></a>
-</dd>
-<dt>getservbyport PORT,PROTO</dt>
-<dd><a name="perlfunc-getservbyport-PORT_002cPROTO"></a>
-</dd>
-<dt>getpwent</dt>
-<dd><a name="perlfunc-getpwent"></a>
-</dd>
-<dt>getgrent</dt>
-<dd><a name="perlfunc-getgrent"></a>
-</dd>
-<dt>gethostent</dt>
-<dd><a name="perlfunc-gethostent"></a>
-</dd>
-<dt>getnetent</dt>
-<dd><a name="perlfunc-getnetent"></a>
-</dd>
-<dt>getprotoent</dt>
-<dd><a name="perlfunc-getprotoent"></a>
-</dd>
-<dt>getservent</dt>
-<dd><a name="perlfunc-getservent"></a>
-</dd>
-<dt>setpwent</dt>
-<dd><a name="perlfunc-setpwent"></a>
-</dd>
-<dt>setgrent</dt>
-<dd><a name="perlfunc-setgrent"></a>
-</dd>
-<dt>sethostent STAYOPEN</dt>
-<dd><a name="perlfunc-sethostent-STAYOPEN"></a>
-</dd>
-<dt>setnetent STAYOPEN</dt>
-<dd><a name="perlfunc-setnetent-STAYOPEN"></a>
-</dd>
-<dt>setprotoent STAYOPEN</dt>
-<dd><a name="perlfunc-setprotoent-STAYOPEN"></a>
-</dd>
-<dt>setservent STAYOPEN</dt>
-<dd><a name="perlfunc-setservent-STAYOPEN"></a>
-</dd>
-<dt>endpwent</dt>
-<dd><a name="perlfunc-endpwent"></a>
-</dd>
-<dt>endgrent</dt>
-<dd><a name="perlfunc-endgrent"></a>
-</dd>
-<dt>endhostent</dt>
-<dd><a name="perlfunc-endhostent"></a>
-</dd>
-<dt>endnetent</dt>
-<dd><a name="perlfunc-endnetent"></a>
-</dd>
-<dt>endprotoent</dt>
-<dd><a name="perlfunc-endprotoent"></a>
-</dd>
-<dt>endservent</dt>
-<dd><a name="perlfunc-endservent"></a>
-<p>These routines are the same as their counterparts in the
-system C library. In list context, the return values from the
-various get routines are as follows:
-</p>
-<pre class="verbatim"> # 0 1 2 3 4
- ( $name, $passwd, $gid, $members ) = getgr*
- ( $name, $aliases, $addrtype, $net ) = getnet*
- ( $name, $aliases, $port, $proto ) = getserv*
- ( $name, $aliases, $proto ) = getproto*
- ( $name, $aliases, $addrtype, $length, @addrs ) = gethost*
- ( $name, $passwd, $uid, $gid, $quota,
- $comment, $gcos, $dir, $shell, $expire ) = getpw*
- # 5 6 7 8 9
-</pre>
-<p>(If the entry doesn’t exist, the return value is a single meaningless
true
-value.)
-</p>
-<p>The exact meaning of the $gcos field varies but it usually contains
-the real name of the user (as opposed to the login name) and other
-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
-<a href="#perlsec-NAME">perlsec NAME</a>). The $passwd and $shell,
user’s encrypted password and
-login shell, are also tainted, for the same reason.
-</p>
-<p>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.
-(If the entry doesn’t exist you get the undefined value.) For example:
-</p>
-<pre class="verbatim"> $uid = getpwnam($name);
- $name = getpwuid($num);
- $name = getpwent();
- $gid = getgrnam($name);
- $name = getgrgid($num);
- $name = getgrent();
- #etc.
-</pre>
-<p>In <em>getpw*()</em> the fields $quota, $comment, and $expire are special
-in that they are unsupported on many systems. If the
-$quota is unsupported, it is an empty scalar. If it is supported, it
-usually encodes the disk quota. If the $comment field is unsupported,
-it is an empty scalar. If it is supported it usually encodes some
-administrative comment about the user. In some systems the $quota
-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 getpwnam(3) and your system’s
-<samp>pwd.h</samp> 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 <code>Config</code> module and the values <code>d_pwquota</code>,
<code>d_pwage</code>,
-<code>d_pwchange</code>, <code>d_pwcomment</code>, and
<code>d_pwexpire</code>. Shadow password
-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
-facility are unlikely to be supported.
-</p>
-<p>The $members value returned by <em>getgr*()</em> is a space-separated list
of
-the login names of the members of the group.
-</p>
-<p>For the <em>gethost*()</em> functions, if the <code>h_errno</code> variable
is supported in
-C, it will be returned to you via <code>$?</code> if the function call fails.
The
-<code>@addrs</code> value returned by a successful call is a list of raw
-addresses returned by the corresponding library call. In the
-Internet domain, each address is four bytes long; you can unpack it
-by saying something like:
-</p>
-<pre class="verbatim"> ($a,$b,$c,$d) = unpack('W4',$addr[0]);
-</pre>
-<p>The Socket library makes this slightly easier:
-</p>
-<pre class="verbatim"> use Socket;
- $iaddr = inet_aton("127.1"); # or whatever address
- $name = gethostbyaddr($iaddr, AF_INET);
-
- # or going the other way
- $straddr = inet_ntoa($iaddr);
-</pre>
-<p>In the opposite way, to resolve a hostname to the IP address
-you can write this:
-</p>
-<pre class="verbatim"> use Socket;
- $packed_ip = gethostbyname("www.perl.org");
- if (defined $packed_ip) {
- $ip_address = inet_ntoa($packed_ip);
- }
-</pre>
-<p>Make sure <code>gethostbyname()</code> is called in SCALAR context and that
-its return value is checked for definedness.
-</p>
-<p>The <code>getprotobynumber</code> function, even though it only takes one
argument,
-has the precedence of a list operator, so beware:
-</p>
-<pre class="verbatim"> getprotobynumber $number eq 'icmp' # WRONG
- getprotobynumber($number eq 'icmp') # actually means this
- getprotobynumber($number) eq 'icmp' # better this way
-</pre>
-<p>If you get tired of remembering which element of the return list
-contains which return value, by-name interfaces are provided
-in standard modules: <code>File::stat</code>, <code>Net::hostent</code>,
<code>Net::netent</code>,
-<code>Net::protoent</code>, <code>Net::servent</code>,
<code>Time::gmtime</code>, <code>Time::localtime</code>,
-and <code>User::grent</code>. These override the normal built-ins, supplying
-versions that return objects with the appropriate names
-for each field. For example:
-</p>
-<pre class="verbatim"> use File::stat;
- use User::pwent;
- $is_his = (stat($filename)->uid == pwent($whoever)->uid);
-</pre>
-<p>Even though it looks as though they’re the same method calls (uid),
-they aren’t, because a <code>File::stat</code> object is different from
-a <code>User::pwent</code> object.
-</p>
-<p>Portability issues: <a href="#perlport-getpwnam">perlport getpwnam</a> to
<a href="#perlport-endservent">perlport endservent</a>.
-</p>
-</dd>
-<dt>getsockname SOCKET</dt>
-<dd><a name="perlfunc-getsockname-SOCKET"></a>
-<p>Returns the packed sockaddr address of this end of the SOCKET connection,
-in case you don’t know the address because you have several different
-IPs that the connection might have come in on.
-</p>
-<pre class="verbatim"> use Socket;
- $mysockaddr = getsockname(SOCK);
- ($port, $myaddr) = sockaddr_in($mysockaddr);
- printf "Connect to %s [%s]\n",
- scalar gethostbyaddr($myaddr, AF_INET),
- inet_ntoa($myaddr);
-</pre>
-</dd>
-<dt>getsockopt SOCKET,LEVEL,OPTNAME</dt>
-<dd><a name="perlfunc-getsockopt-SOCKET_002cLEVEL_002cOPTNAME"></a>
-<p>Queries the option named OPTNAME associated with SOCKET at a given LEVEL.
-Options may exist at multiple protocol levels depending on the socket
-type, but at least the uppermost socket level SOL_SOCKET (defined in the
-<code>Socket</code> module) will exist. To query options at another level the
-protocol number of the appropriate protocol controlling the option
-should be supplied. For example, to indicate that an option is to be
-interpreted by the TCP protocol, LEVEL should be set to the protocol
-number of TCP, which you can get using <code>getprotobyname</code>.
-</p>
-<p>The function returns a packed string representing the requested socket
-option, or <code>undef</code> on error, with the reason for the error placed in
-<code>$!</code>. 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 <code>unpack</code> with the <code>i</code> (or <code>I</code>) format.
-</p>
-<p>Here’s an example to test whether Nagle’s algorithm is enabled
on a socket:
-</p>
-<pre class="verbatim"> use Socket qw(:all);
-
- defined(my $tcp = getprotobyname("tcp"))
- or die "Could not determine the protocol number for tcp";
- # my $tcp = IPPROTO_TCP; # Alternative
- my $packed = getsockopt($socket, $tcp, TCP_NODELAY)
- or die "getsockopt TCP_NODELAY: $!";
- my $nodelay = unpack("I", $packed);
- print "Nagle's algorithm is turned ",
- $nodelay ? "off\n" : "on\n";
-</pre>
-<p>Portability issues: ‘perlport getsockopt’.
-</p>
-</dd>
-<dt>glob EXPR</dt>
-<dd><a name="perlfunc-glob-EXPR"></a>
-</dd>
-<dt>glob</dt>
-<dd><a name="perlfunc-glob"></a>
-<p>In list context, returns a (possibly empty) list of filename expansions on
-the value of EXPR such as the standard Unix shell <samp>/bin/csh</samp> would
do. In
-scalar context, glob iterates through such filename expansions, returning
-undef when the list is exhausted. This is the internal function
-implementing the <code><*.c></code> operator, but you can use it
directly. If
-EXPR is omitted, <code>$_</code> is used. The <code><*.c></code>
operator is discussed in
-more detail in <a href="#perlop-I_002fO-Operators">perlop I/O Operators</a>.
-</p>
-<p>Note that <code>glob</code> splits its arguments on whitespace and treats
-each segment as separate pattern. As such, <code>glob("*.c
*.h")</code>
-matches all files with a <samp>.c</samp> or <samp>.h</samp> extension. The
expression
-<code>glob(".* *")</code> matches all files in the current working
directory.
-If you want to glob filenames that might contain whitespace, you’ll
-have to use extra quotes around the spacey filename to protect it.
-For example, to glob filenames that have an <code>e</code> followed by a space
-followed by an <code>f</code>, use either of:
-</p>
-<pre class="verbatim"> @spacies = <"*e f*">;
- @spacies = glob '"*e f*"';
- @spacies = glob q("*e f*");
-</pre>
-<p>If you had to get a variable through, you could do this:
-</p>
-<pre class="verbatim"> @spacies = glob "'*${var}e f*'";
- @spacies = glob qq("*${var}e f*");
-</pre>
-<p>If non-empty braces are the only wildcard characters used in the
-<code>glob</code>, no filenames are matched, but potentially many strings
-are returned. For example, this produces nine strings, one for
-each pairing of fruits and colors:
-</p>
-<pre class="verbatim"> @many = glob
"{apple,tomato,cherry}={green,yellow,red}";
-</pre>
-<p>This operator is implemented using the standard
-<code>File::Glob</code> extension. See <a
href="File-Glob.html#Top">(File-Glob)</a> for details, including
-<code>bsd_glob</code> which does not treat whitespace as a pattern separator.
-</p>
-<p>Portability issues: <a href="#perlport-glob">perlport glob</a>.
-</p>
-</dd>
-<dt>gmtime EXPR</dt>
-<dd><a name="perlfunc-gmtime-EXPR"></a>
-</dd>
-<dt>gmtime</dt>
-<dd><a name="perlfunc-gmtime"></a>
-<p>Works just like <a href="#perlfunc-localtime">localtime</a> but the
returned values are
-localized for the standard Greenwich time zone.
-</p>
-<p>Note: When called in list context, $isdst, the last value
-returned by gmtime, is always <code>0</code>. There is no
-Daylight Saving Time in GMT.
-</p>
-<p>Portability issues: <a href="#perlport-gmtime">perlport gmtime</a>.
-</p>
-</dd>
-<dt>goto LABEL</dt>
-<dd><a name="perlfunc-goto-LABEL"></a>
-</dd>
-<dt>goto EXPR</dt>
-<dd><a name="perlfunc-goto-EXPR"></a>
-</dd>
-<dt>goto &NAME</dt>
-<dd><a name="perlfunc-goto-_0026NAME"></a>
-<p>The <code>goto LABEL</code> form finds the statement labeled with LABEL and
-resumes execution there. It can’t be used to get out of a block or
-subroutine given to <code>sort</code>. It can be used to go almost anywhere
-else within the dynamic scope, including out of subroutines, but it’s
-usually better to use some other construct such as <code>last</code> or
<code>die</code>.
-The author of Perl has never felt the need to use this form of
<code>goto</code>
-(in Perl, that is; C is another matter). (The difference is that C
-does not offer named loops combined with loop control. Perl does, and
-this replaces most structured uses of <code>goto</code> in other languages.)
-</p>
-<p>The <code>goto EXPR</code> form expects to evaluate <code>EXPR</code> to a
code reference or
-a label name. If it evaluates to a code reference, it will be handled
-like <code>goto &NAME</code>, below. This is especially useful for
implementing
-tail recursion via <code>goto __SUB__</code>.
-</p>
-<p>If the expression evaluates to a label name, its scope will be resolved
-dynamically. This allows for computed <code>goto</code>s per FORTRAN, but
isn’t
-necessarily recommended if you’re optimizing for maintainability:
-</p>
-<pre class="verbatim"> goto ("FOO", "BAR",
"GLARCH")[$i];
-</pre>
-<p>As shown in this example, <code>goto EXPR</code> is exempt from the
"looks like a
-function" rule. A pair of parentheses following it does not (necessarily)
-delimit its argument. <code>goto("NE")."XT"</code> is
equivalent to <code>goto NEXT</code>.
-Also, unlike most named operators, this has the same precedence as
-assignment.
-</p>
-<p>Use of <code>goto LABEL</code> or <code>goto EXPR</code> 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
-subroutine or a <code>foreach</code> loop. It also can’t be used to go
into a
-construct that is optimized away.
-</p>
-<p>The <code>goto &NAME</code> form is quite different from the other
forms of
-<code>goto</code>. In fact, it isn’t a goto in the normal sense at all,
and
-doesn’t have the stigma associated with other gotos. Instead, it
-exits the current subroutine (losing any changes set by local()) and
-immediately calls in its place the named subroutine using the current
-value of @_. This is used by <code>AUTOLOAD</code> subroutines that wish to
-load another subroutine and then pretend that the other subroutine had
-been called in the first place (except that any modifications to
<code>@_</code>
-in the current subroutine are propagated to the other subroutine.)
-After the <code>goto</code>, not even <code>caller</code> will be able to tell
that this
-routine was called first.
-</p>
-<p>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
-reference.
-</p>
-</dd>
-<dt>grep BLOCK LIST</dt>
-<dd><a name="perlfunc-grep-BLOCK-LIST"></a>
-</dd>
-<dt>grep EXPR,LIST</dt>
-<dd><a name="perlfunc-grep-EXPR_002cLIST"></a>
-<p>This is similar in spirit to, but not the same as, grep(1) and its
-relatives. In particular, it is not limited to using regular expressions.
-</p>
-<p>Evaluates the BLOCK or EXPR for each element of LIST (locally setting
-<code>$_</code> to each element) and returns the list value consisting of those
-elements for which the expression evaluated to true. In scalar
-context, returns the number of times the expression was true.
-</p>
-<pre class="verbatim"> @foo = grep(!/^#/, @bar); # weed out comments
-</pre>
-<p>or equivalently,
-</p>
-<pre class="verbatim"> @foo = grep {!/^#/} @bar; # weed out comments
-</pre>
-<p>Note that <code>$_</code> is an alias to the list value, so it can be used
to
-modify the elements of the LIST. While this is useful and supported,
-it can cause bizarre results if the elements of LIST are not variables.
-Similarly, grep returns aliases into the original list, much as a for
-loop’s index variable aliases the list elements. That is, modifying an
-element of a list returned by grep (for example, in a <code>foreach</code>,
<code>map</code>
-or another <code>grep</code>) actually modifies the element in the original
list.
-This is usually something to be avoided when writing clear code.
-</p>
-<p>If <code>$_</code> is lexical in the scope where the <code>grep</code>
appears (because it has
-been declared with the deprecated <code>my $_</code> construct)
-then, in addition to being locally aliased to
-the list elements, <code>$_</code> keeps being lexical inside the block; i.e.,
it
-can’t be seen from the outside, avoiding any potential side-effects.
-</p>
-<p>See also ‘map’ for a list composed of the results of the BLOCK
or EXPR.
-</p>
-</dd>
-<dt>hex EXPR</dt>
-<dd><a name="perlfunc-hex-EXPR"></a>
-</dd>
-<dt>hex</dt>
-<dd><a name="perlfunc-hex"></a>
-<p>Interprets EXPR as a hex string and returns the corresponding value.
-(To convert strings that might start with either <code>0</code>,
<code>0x</code>, or <code>0b</code>, see
-<a href="#perlfunc-oct">oct</a>.) If EXPR is omitted, uses <code>$_</code>.
-</p>
-<pre class="verbatim"> print hex '0xAf'; # prints '175'
- print hex 'aF'; # same
-</pre>
-<p>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 <a
href="#perlfunc-printf">printf</a>,
-‘sprintf’, and ‘unpack’.
-</p>
-</dd>
-<dt>import LIST</dt>
-<dd><a name="perlfunc-import-LIST"></a>
-<p>There is no builtin <code>import</code> function. It is just an ordinary
-method (subroutine) defined (or inherited) by modules that wish to export
-names to another module. The <code>use</code> function calls the
<code>import</code> method
-for the package used. See also ‘use’, <a
href="#perlmod-NAME">perlmod NAME</a>, and <a
href="Exporter.html#Top">(Exporter)</a>.
-</p>
-</dd>
-<dt>index STR,SUBSTR,POSITION</dt>
-<dd><a name="perlfunc-index-STR_002cSUBSTR_002cPOSITION"></a>
-</dd>
-<dt>index STR,SUBSTR</dt>
-<dd><a name="perlfunc-index-STR_002cSUBSTR"></a>
-<p>The index function searches for one string within another, but without
-the wildcard-like behavior of a full regular-expression pattern match.
-It returns the position of the first occurrence of SUBSTR in STR at
-or after POSITION. If POSITION is omitted, starts searching from the
-beginning of the string. POSITION before the beginning of the string
-or after its end is treated as if it were the beginning or the end,
-respectively. POSITION and the return value are based at zero.
-If the substring is not found, <code>index</code> returns -1.
-</p>
-</dd>
-<dt>int EXPR</dt>
-<dd><a name="perlfunc-int-EXPR"></a>
-</dd>
-<dt>int</dt>
-<dd><a name="perlfunc-int"></a>
-<p>Returns the integer portion of EXPR. If EXPR is omitted, uses
<code>$_</code>.
-You should not use this function for rounding: one because it truncates
-towards <code>0</code>, and two because machine representations of
floating-point
-numbers can sometimes produce counterintuitive results. For example,
-<code>int(-6.725/0.025)</code> produces -268 rather than the correct -269;
that’s
-because it’s really more like -268.99999999999994315658 instead.
Usually,
-the <code>sprintf</code>, <code>printf</code>, or the
<code>POSIX::floor</code> and <code>POSIX::ceil</code>
-functions will serve you better than will int().
-</p>
-</dd>
-<dt>ioctl FILEHANDLE,FUNCTION,SCALAR</dt>
-<dd><a name="perlfunc-ioctl-FILEHANDLE_002cFUNCTION_002cSCALAR"></a>
-<p>Implements the ioctl(2) function. You’ll probably first have to say
-</p>
-<pre class="verbatim"> require "sys/ioctl.ph"; # probably in
- # $Config{archlib}/sys/ioctl.ph
-</pre>
-<p>to get the correct function definitions. If <samp>sys/ioctl.ph</samp>
doesn’t
-exist or doesn’t have the correct definitions you’ll have to roll
your
-own, based on your C header files such as <samp><sys/ioctl.h></samp>.
-(There is a Perl script called <strong>h2ph</strong> that comes with the Perl
kit that
-may help you in this, but it’s nontrivial.) SCALAR will be read and/or
-written depending on the FUNCTION; a C pointer to the string value of SCALAR
-will be passed as the third argument of the actual <code>ioctl</code> call.
(If SCALAR
-has no string value but does have a numeric value, that value will be
-passed rather than a pointer to the string value. To guarantee this to be
-true, add a <code>0</code> to the scalar before using it.) The
<code>pack</code> and <code>unpack</code>
-functions may be needed to manipulate the values of structures used by
-<code>ioctl</code>.
-</p>
-<p>The return value of <code>ioctl</code> (and <code>fcntl</code>) is as
follows:
-</p>
-<pre class="verbatim"> if OS returns: then Perl returns:
- -1 undefined value
- 0 string "0 but true"
- anything else that number
-</pre>
-<p>Thus Perl returns true on success and false on failure, yet you can
-still easily determine the actual value returned by the operating
-system:
-</p>
-<pre class="verbatim"> $retval = ioctl(...) || -1;
- printf "System returned %d\n", $retval;
-</pre>
-<p>The special string <code>"0 but true"</code> is exempt from
<strong>-w</strong> complaints
-about improper numeric conversions.
-</p>
-<p>Portability issues: ‘perlport ioctl’.
-</p>
-</dd>
-<dt>join EXPR,LIST</dt>
-<dd><a name="perlfunc-join-EXPR_002cLIST"></a>
-<p>Joins the separate strings of LIST into a single string with fields
-separated by the value of EXPR, and returns that new string. Example:
-</p>
-<pre class="verbatim"> $rec = join(':',
$login,$passwd,$uid,$gid,$gcos,$home,$shell);
-</pre>
-<p>Beware that unlike <code>split</code>, <code>join</code> doesn’t take
a pattern as its
-first argument. Compare <a href="#perlfunc-split">split</a>.
-</p>
-</dd>
-<dt>keys HASH</dt>
-<dd><a name="perlfunc-keys-HASH"></a>
-</dd>
-<dt>keys ARRAY</dt>
-<dd><a name="perlfunc-keys-ARRAY"></a>
-</dd>
-<dt>keys EXPR</dt>
-<dd><a name="perlfunc-keys-EXPR"></a>
-<p>Called in list context, returns a list consisting of all the keys of the
-named hash, or in Perl 5.12 or later only, the indices of an array. Perl
-releases prior to 5.12 will produce a syntax error if you try to use an
-array argument. In scalar context, returns the number of keys or indices.
-</p>
-<p>Hash entries are returned in an apparently random order. The actual random
-order is specific to a given hash; the exact same series of operations
-on two hashes may result in a different order for each hash. Any insertion
-into the hash may change the order, as will any deletion, with the exception
-that the most recent key returned by <code>each</code> or <code>keys</code>
may be deleted
-without changing the order. So long as a given hash is unmodified you may
-rely on <code>keys</code>, <code>values</code> and <code>each</code> to
repeatedly return the same order
-as each other. See <a href="#perlsec-Algorithmic-Complexity-Attacks">perlsec
Algorithmic Complexity Attacks</a> for
-details on why hash order is randomized. Aside from the guarantees
-provided here the exact details of Perl’s hash algorithm and the hash
-traversal order are subject to change in any release of Perl. Tied hashes
-may behave differently to Perl’s hashes with respect to changes in order
on
-insertion and deletion of items.
-</p>
-<p>As a side effect, calling keys() resets the internal iterator of the HASH or
-ARRAY (see ‘each’). In particular, calling keys() in void context
resets
-the iterator with no other overhead.
-</p>
-<p>Here is yet another way to print your environment:
-</p>
-<pre class="verbatim"> @keys = keys %ENV;
- @values = values %ENV;
- while (@keys) {
- print pop(@keys), '=', pop(@values), "\n";
- }
-</pre>
-<p>or how about sorted by key:
-</p>
-<pre class="verbatim"> foreach $key (sort(keys %ENV)) {
- print $key, '=', $ENV{$key}, "\n";
- }
-</pre>
-<p>The returned values are copies of the original keys in the hash, so
-modifying them will not affect the original hash. Compare
‘values’.
-</p>
-<p>To sort a hash by value, you’ll need to use a <code>sort</code>
function.
-Here’s a descending numeric sort of a hash by its values:
-</p>
-<pre class="verbatim"> foreach $key (sort { $hash{$b} <=> $hash{$a} }
keys %hash) {
- printf "%4d %s\n", $hash{$key}, $key;
- }
-</pre>
-<p>Used as an lvalue, <code>keys</code> allows you to increase the number of
hash buckets
-allocated for the given hash. This can gain you a measure of efficiency if
-you know the hash is going to get big. (This is similar to pre-extending
-an array by assigning a larger number to $#array.) If you say
-</p>
-<pre class="verbatim"> keys %hash = 200;
-</pre>
-<p>then <code>%hash</code> will have at least 200 buckets allocated for
it–256 of them,
-in fact, since it rounds up to the next power of two. These
-buckets will be retained even if you do <code>%hash = ()</code>, use
<code>undef
-%hash</code> if you want to free the storage while <code>%hash</code> is still
in scope.
-You can’t shrink the number of buckets allocated for the hash using
-<code>keys</code> in this way (but you needn’t worry about doing this by
accident,
-as trying has no effect). <code>keys @array</code> in an lvalue context is a
syntax
-error.
-</p>
-<p>Starting with Perl 5.14, <code>keys</code> 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 <code>keys</code> is considered
highly
-experimental. The exact behaviour may change in a future version of Perl.
-</p>
-<pre class="verbatim"> for (keys $hashref) { ... }
- for (keys $obj->get_arrayref) { ... }
-</pre>
-<p>To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work <em>only</em> on Perls
of
-a recent vintage:
-</p>
-<pre class="verbatim"> use 5.012; # so keys/values/each work on arrays
- use 5.014; # so keys/values/each work on scalars (experimental)
-</pre>
-<p>See also <code>each</code>, <code>values</code>, and <code>sort</code>.
-</p>
-</dd>
-<dt>kill SIGNAL, LIST</dt>
-<dd><a name="perlfunc-kill-SIGNAL_002c-LIST"></a>
-</dd>
-<dt>kill SIGNAL</dt>
-<dd><a name="perlfunc-kill-SIGNAL"></a>
-<p>Sends a signal to a list of processes. Returns the number of arguments
-that were successfully used to signal (which is not necessarily the same
-as the number of processes actually killed, e.g. where a process group is
-killed).
-</p>
-<pre class="verbatim"> $cnt = kill 'HUP', $child1, $child2;
- kill 'KILL', @goners;
-</pre>
-<p>SIGNAL may be either a signal name (a string) or a signal number. A signal
-name may start with a <code>SIG</code> prefix, thus <code>FOO</code> and
<code>SIGFOO</code> refer to the
-same signal. The string form of SIGNAL is recommended for portability because
-the same signal may have different numbers in different operating systems.
-</p>
-<p>A list of signal names supported by the current platform can be found in
-<code>$Config{sig_name}</code>, which is provided by the <code>Config</code>
module. See <a href="Config.html#Top">(Config)</a>
-for more details.
-</p>
-<p>A negative signal name is the same as a negative signal number, killing
process
-groups instead of processes. For example, <code>kill '-KILL', $pgrp</code> and
-<code>kill -9, $pgrp</code> will send <code>SIGKILL</code> to
-the entire process group specified. That
-means you usually want to use positive not negative signals.
-</p>
-<p>If SIGNAL is either the number 0 or the string <code>ZERO</code> (or
<code>SIGZERO</code>),
-no signal is sent to
-the process, but <code>kill</code> checks whether it’s <em>possible</em>
to send a signal to it
-(that means, to be brief, that the process is owned by the same user, or we are
-the super-user). This is useful to check that a child process is still
-alive (even if only as a zombie) and hasn’t changed its UID. See
-<a href="#perlport-NAME">perlport NAME</a> for notes on the portability of
this construct.
-</p>
-<p>The behavior of kill when a <em>PROCESS</em> number is zero or negative
depends on
-the operating system. For example, on POSIX-conforming systems, zero will
-signal the current process group, -1 will signal all processes, and any
-other negative PROCESS number will act as a negative signal number and
-kill the entire process group specified.
-</p>
-<p>If both the SIGNAL and the PROCESS are negative, the results are undefined.
-A warning may be produced in a future version.
-</p>
-<p>See <a href="#perlipc-Signals">perlipc Signals</a> for more details.
-</p>
-<p>On some platforms such as Windows where the fork() system call is not
-available, Perl can be built to emulate fork() at the interpreter level.
-This emulation has limitations related to kill that have to be considered,
-for code running on Windows and in code intended to be portable.
-</p>
-<p>See <a href="#perlfork-NAME">perlfork NAME</a> for more details.
-</p>
-<p>If there is no <em>LIST</em> of processes, no signal is sent, and the return
-value is 0. This form is sometimes used, however, because it causes
-tainting checks to be run. But see
-<a href="#perlsec-Laundering-and-Detecting-Tainted-Data">perlsec Laundering
and Detecting Tainted Data</a>.
-</p>
-<p>Portability issues: <a href="#perlport-kill">perlport kill</a>.
-</p>
-</dd>
-<dt>last LABEL</dt>
-<dd><a name="perlfunc-last-LABEL"></a>
-</dd>
-<dt>last EXPR</dt>
-<dd><a name="perlfunc-last-EXPR"></a>
-</dd>
-<dt>last</dt>
-<dd><a name="perlfunc-last"></a>
-<p>The <code>last</code> command is like the <code>break</code> statement in C
(as used in
-loops); it immediately exits the loop in question. If the LABEL is
-omitted, the command refers to the innermost enclosing
-loop. The <code>last EXPR</code> form, available starting in Perl
-5.18.0, allows a label name to be computed at run time,
-and is otherwise identical to <code>last LABEL</code>. The
-<code>continue</code> block, if any, is not executed:
-</p>
-<pre class="verbatim"> LINE: while (<STDIN>) {
- last LINE if /^$/; # exit when done with header
- #...
- }
-</pre>
-<p><code>last</code> cannot be used to exit a block that returns a value such
as
-<code>eval {}</code>, <code>sub {}</code>, or <code>do {}</code>, and should
not be used to exit
-a grep() or map() operation.
-</p>
-<p>Note that a block by itself is semantically identical to a loop
-that executes once. Thus <code>last</code> can be used to effect an early
-exit out of such a block.
-</p>
-<p>See also <a href="#perlfunc-continue">continue</a> for an illustration of
how <code>last</code>, <code>next</code>, and
-<code>redo</code> work.
-</p>
-<p>Unlike most named operators, this has the same precedence as assignment.
-It is also exempt from the looks-like-a-function rule, so
-<code>last ("foo")."bar"</code> will cause "bar"
to be part of the argument to
-<code>last</code>.
-</p>
-</dd>
-<dt>lc EXPR</dt>
-<dd><a name="perlfunc-lc-EXPR"></a>
-</dd>
-<dt>lc</dt>
-<dd><a name="perlfunc-lc"></a>
-<p>Returns a lowercased version of EXPR. This is the internal function
-implementing the <code>\L</code> escape in double-quoted strings.
-</p>
-<p>If EXPR is omitted, uses <code>$_</code>.
-</p>
-<p>What gets returned depends on several factors:
-</p>
-<dl compact="compact">
-<dt>If <code>use bytes</code> is in effect:</dt>
-<dd><a name="perlfunc-If-use-bytes-is-in-effect_003a"></a>
-<p>The results follow ASCII rules. Only the characters <code>A-Z</code>
change,
-to <code>a-z</code> respectively.
-</p>
-</dd>
-<dt>Otherwise, if <code>use locale</code> for <code>LC_CTYPE</code> is in
effect:</dt>
-<dd><a
name="perlfunc-Otherwise_002c-if-use-locale-for-LC_005fCTYPE-is-in-effect_003a"></a>
-<p>Respects current <code>LC_CTYPE</code> locale for code points < 256; and
uses Unicode
-rules for the remaining code points (this last can only happen if
-the UTF8 flag is also set). See <a href="#perllocale-NAME">perllocale
NAME</a>.
-</p>
-<p>Starting in v5.20, Perl uses full Unicode rules if the locale is
-UTF-8. Otherwise, there is a deficiency in this scheme, which is that
-case changes that cross the 255/256
-boundary are not well-defined. For example, the lower case of LATIN CAPITAL
-LETTER SHARP S (U+1E9E) in Unicode rules is U+00DF (on ASCII
-platforms). But under <code>use locale</code> (prior to v5.20 or not a UTF-8
-locale), the lower case of U+1E9E is
-itself, because 0xDF may not be LATIN SMALL LETTER SHARP S in the
-current locale, and Perl has no way of knowing if that character even
-exists in the locale, much less what code point it is. Perl returns
-a result that is above 255 (almost always the input character unchanged,
-for all instances (and there aren’t many) where the 255/256 boundary
-would otherwise be crossed; and starting in v5.22, it raises a
-<a
href="#perldiag-Can_0027t-do-_0025s_0028_0022_0025s_0022_0029-on-non_002dUTF_002d8-locale_003b-resolved-to-_0022_0025s_0022_002e">locale</a>
warning.
-</p>
-</dd>
-<dt>Otherwise, If EXPR has the UTF8 flag set:</dt>
-<dd><a name="perlfunc-Otherwise_002c-If-EXPR-has-the-UTF8-flag-set_003a"></a>
-<p>Unicode rules are used for the case change.
-</p>
-</dd>
-<dt>Otherwise, if <code>use feature 'unicode_strings'</code> or <code>use
locale ':not_characters'</code> is in effect:</dt>
-<dd><a
name="perlfunc-Otherwise_002c-if-use-feature-_0027unicode_005fstrings_0027-or-use-locale-_0027_003anot_005fcharacters_0027-is-in-effect_003a"></a>
-<p>Unicode rules are used for the case change.
-</p>
-</dd>
-<dt>Otherwise:</dt>
-<dd><a name="perlfunc-Otherwise_003a"></a>
-<p>ASCII rules are used for the case change. The lowercase of any character
-outside the ASCII range is the character itself.
-</p>
-</dd>
-</dl>
-
-</dd>
-<dt>lcfirst EXPR</dt>
-<dd><a name="perlfunc-lcfirst-EXPR"></a>
-</dd>
-<dt>lcfirst</dt>
-<dd><a name="perlfunc-lcfirst"></a>
-<p>Returns the value of EXPR with the first character lowercased. This
-is the internal function implementing the <code>\l</code> escape in
-double-quoted strings.
-</p>
-<p>If EXPR is omitted, uses <code>$_</code>.
-</p>
-<p>This function behaves the same way under various pragmata, such as in a
locale,
-as <a href="#perlfunc-lc">lc</a> does.
-</p>
-</dd>
-<dt>length EXPR</dt>
-<dd><a name="perlfunc-length-EXPR"></a>
-</dd>
-<dt>length</dt>
-<dd><a name="perlfunc-length"></a>
-<p>Returns the length in <em>characters</em> of the value of EXPR. If EXPR is
-omitted, returns the length of <code>$_</code>. If EXPR is undefined, returns
-<code>undef</code>.
-</p>
-<p>This function cannot be used on an entire array or hash to find out how
-many elements these have. For that, use <code>scalar @array</code> and
<code>scalar keys
-%hash</code>, respectively.
-</p>
-<p>Like all Perl character operations, length() normally deals in logical
-characters, not physical bytes. For how many bytes a string encoded as
-UTF-8 would take up, use <code>length(Encode::encode_utf8(EXPR))</code>
(you’ll have
-to <code>use Encode</code> first). See <a href="Encode.html#Top">(Encode)</a>
and <a href="#perlunicode-NAME">perlunicode NAME</a>.
-</p>
-</dd>
-<dt>__LINE__</dt>
-<dd><a name="perlfunc-_005f_005fLINE_005f_005f"></a>
-<p>A special token that compiles to the current line number.
-</p>
-</dd>
-<dt>link OLDFILE,NEWFILE</dt>
-<dd><a name="perlfunc-link-OLDFILE_002cNEWFILE"></a>
-<p>Creates a new filename linked to the old filename. Returns true for
-success, false otherwise.
-</p>
-<p>Portability issues: <a href="#perlport-link">perlport link</a>.
-</p>
-</dd>
-<dt>listen SOCKET,QUEUESIZE</dt>
-<dd><a name="perlfunc-listen-SOCKET_002cQUEUESIZE"></a>
-<p>Does the same thing that the listen(2) system call does. Returns true if
-it succeeded, false otherwise. See the example in
-<a href="#perlipc-Sockets_003a-Client_002fServer-Communication">perlipc
Sockets: Client/Server Communication</a>.
-</p>
-</dd>
-<dt>local EXPR</dt>
-<dd><a name="perlfunc-local-EXPR"></a>
-<p>You really probably want to be using <code>my</code> instead, because
<code>local</code> isn’t
-what most people think of as "local". See
-<a href="#perlsub-Private-Variables-via-my_0028_0029">perlsub Private
Variables via my()</a> for details.
-</p>
-<p>A local modifies the listed variables to be local to the enclosing
-block, file, or eval. If more than one value is listed, the list must
-be placed in parentheses. See <a
href="#perlsub-Temporary-Values-via-local_0028_0029">perlsub Temporary Values
via local()</a>
-for details, including issues with tied arrays and hashes.
-</p>
-<p>The <code>delete local EXPR</code> construct can also be used to localize
the deletion
-of array/hash elements to the current block.
-See <a
href="#perlsub-Localized-deletion-of-elements-of-composite-types">perlsub
Localized deletion of elements of composite types</a>.
-</p>
-</dd>
-<dt>localtime EXPR</dt>
-<dd><a name="perlfunc-localtime-EXPR"></a>
-</dd>
-<dt>localtime</dt>
-<dd><a name="perlfunc-localtime"></a>
-<p>Converts a time as returned by the time function to a 9-element list
-with the time analyzed for the local time zone. Typically used as
-follows:
-</p>
-<pre class="verbatim"> # 0 1 2 3 4 5 6 7 8
- ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
- localtime(time);
-</pre>
-<p>All list elements are numeric and come straight out of the C ‘struct
-tm’. <code>$sec</code>, <code>$min</code>, and <code>$hour</code> are
the seconds, minutes, and hours
-of the specified time.
-</p>
-<p><code>$mday</code> is the day of the month and <code>$mon</code> the month
in
-the range <code>0..11</code>, with 0 indicating January and 11 indicating
December.
-This makes it easy to get a month name from a list:
-</p>
-<pre class="verbatim"> 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"
-</pre>
-<p><code>$year</code> contains the number of years since 1900. To get a
4-digit
-year write:
-</p>
-<pre class="verbatim"> $year += 1900;
-</pre>
-<p>To get the last two digits of the year (e.g., "01" in 2001) do:
-</p>
-<pre class="verbatim"> $year = sprintf("%02d", $year % 100);
-</pre>
-<p><code>$wday</code> is the day of the week, with 0 indicating Sunday and 3
indicating
-Wednesday. <code>$yday</code> is the day of the year, in the range
<code>0..364</code>
-(or <code>0..365</code> in leap years.)
-</p>
-<p><code>$isdst</code> is true if the specified time occurs during Daylight
Saving
-Time, false otherwise.
-</p>
-<p>If EXPR is omitted, <code>localtime()</code> uses the current time (as
returned
-by time(3)).
-</p>
-<p>In scalar context, <code>localtime()</code> returns the ctime(3) value:
-</p>
-<pre class="verbatim"> $now_string = localtime; # e.g., "Thu Oct 13
04:54:34 1994"
-</pre>
-<p>The format of this scalar value is <strong>not</strong> locale-dependent
-but built into Perl. For GMT instead of local
-time use the <a href="#perlfunc-gmtime">gmtime</a> builtin. See also the
-<code>Time::Local</code> module (for converting seconds, minutes, hours, and
such back to
-the integer value returned by time()), and the <a
href="POSIX.html#Top">(POSIX)</a> module’s strftime(3)
-and mktime(3) functions.
-</p>
-<p>To get somewhat similar but locale-dependent date strings, set up your
-locale environment variables appropriately (please see <a
href="#perllocale-NAME">perllocale NAME</a>) and
-try for example:
-</p>
-<pre class="verbatim"> use POSIX qw(strftime);
- $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
- # or for GMT formatted appropriately for your locale:
- $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
-</pre>
-<p>Note that the <code>%a</code> and <code>%b</code>, the short forms of the
day of the week
-and the month of the year, may not necessarily be three characters wide.
-</p>
-<p>The <a href="Time-gmtime.html#Top">(Time-gmtime)</a> and <a
href="Time-localtime.html#Top">(Time-localtime)</a> modules provide a
convenient,
-by-name access mechanism to the gmtime() and localtime() functions,
-respectively.
-</p>
-<p>For a comprehensive date and time representation look at the
-<a href="DateTime.html#Top">(DateTime)</a> module on CPAN.
-</p>
-<p>Portability issues: <a href="#perlport-localtime">perlport localtime</a>.
-</p>
-</dd>
-<dt>lock THING</dt>
-<dd><a name="perlfunc-lock-THING"></a>
-<p>This function places an advisory lock on a shared variable or referenced
-object contained in <em>THING</em> until the lock goes out of scope.
-</p>
-<p>The value returned is the scalar itself, if the argument is a scalar, or a
-reference, if the argument is a hash, array or subroutine.
-</p>
-<p>lock() is a "weak keyword" : this means that if you’ve
defined a function
-by this name (before any calls to it), that function will be called
-instead. If you are not under <code>use threads::shared</code> this does
nothing.
-See <a href="threads-shared.html#Top">(threads-shared)</a>.
-</p>
-</dd>
-<dt>log EXPR</dt>
-<dd><a name="perlfunc-log-EXPR"></a>
-</dd>
-<dt>log</dt>
-<dd><a name="perlfunc-log"></a>
-<p>Returns the natural logarithm (base <em>e</em>) of EXPR. If EXPR is
omitted,
-returns the log of <code>$_</code>. 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:
-</p>
-<pre class="verbatim"> sub log10 {
- my $n = shift;
- return log($n)/log(10);
- }
-</pre>
-<p>See also <a href="#perlfunc-exp">exp</a> for the inverse operation.
-</p>
-</dd>
-<dt>lstat FILEHANDLE</dt>
-<dd><a name="perlfunc-lstat-FILEHANDLE"></a>
-</dd>
-<dt>lstat EXPR</dt>
-<dd><a name="perlfunc-lstat-EXPR"></a>
-</dd>
-<dt>lstat DIRHANDLE</dt>
-<dd><a name="perlfunc-lstat-DIRHANDLE"></a>
-</dd>
-<dt>lstat</dt>
-<dd><a name="perlfunc-lstat"></a>
-<p>Does the same thing as the <code>stat</code> function (including setting the
-special <code>_</code> filehandle) but stats a symbolic link instead of the
file
-the symbolic link points to. If symbolic links are unimplemented on
-your system, a normal <code>stat</code> is done. For much more detailed
-information, please see the documentation for <code>stat</code>.
-</p>
-<p>If EXPR is omitted, stats <code>$_</code>.
-</p>
-<p>Portability issues: <a href="#perlport-lstat">perlport lstat</a>.
-</p>
-</dd>
-<dt>m//</dt>
-<dd><a name="perlfunc-m_002f_002f"></a>
-<p>The match operator. See <a
href="#perlop-Regexp-Quote_002dLike-Operators">perlop Regexp Quote-Like
Operators</a>.
-</p>
-</dd>
-<dt>map BLOCK LIST</dt>
-<dd><a name="perlfunc-map-BLOCK-LIST"></a>
-</dd>
-<dt>map EXPR,LIST</dt>
-<dd><a name="perlfunc-map-EXPR_002cLIST"></a>
-<p>Evaluates the BLOCK or EXPR for each element of LIST (locally setting
-<code>$_</code> to each element) and returns the list value composed of the
-results of each such evaluation. In scalar context, returns the
-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.
-</p>
-<pre class="verbatim"> @chars = map(chr, @numbers);
-</pre>
-<p>translates a list of numbers to the corresponding characters.
-</p>
-<pre class="verbatim"> my @squares = map { $_ * $_ } @numbers;
-</pre>
-<p>translates a list of numbers to their squared values.
-</p>
-<pre class="verbatim"> my @squares = map { $_ > 5 ? ($_ * $_) : () }
@numbers;
-</pre>
-<p>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
-</p>
-<pre class="verbatim"> my @squares = map { $_ * $_ } grep { $_ > 5 }
@numbers;
-</pre>
-<p>which makes the intention more clear.
-</p>
-<p>Map always returns a list, which can be
-assigned to a hash such that the elements
-become key/value pairs. See <a href="#perldata-NAME">perldata NAME</a> for
more details.
-</p>
-<pre class="verbatim"> %hash = map { get_a_key_for($_) => $_ } @array;
-</pre>
-<p>is just a funny way to write
-</p>
-<pre class="verbatim"> %hash = ();
- foreach (@array) {
- $hash{get_a_key_for($_)} = $_;
- }
-</pre>
-<p>Note that <code>$_</code> is an alias to the list value, so it can be used
to
-modify the elements of the LIST. While this is useful and supported,
-it can cause bizarre results if the elements of LIST are not variables.
-Using a regular <code>foreach</code> loop for this purpose would be clearer in
-most cases. See also ‘grep’ for an array composed of those items
of
-the original list for which the BLOCK or EXPR evaluates to true.
-</p>
-<p>If <code>$_</code> is lexical in the scope where the <code>map</code>
appears (because it has
-been declared with the deprecated <code>my $_</code> construct),
-then, in addition to being locally aliased to
-the list elements, <code>$_</code> keeps being lexical inside the block; that
is, it
-can’t be seen from the outside, avoiding any potential side-effects.
-</p>
-<p><code>{</code> starts both hash references and blocks, so <code>map {
...</code> could be either
-the start of map BLOCK LIST or map EXPR, LIST. Because Perl doesn’t look
-ahead for the closing <code>}</code> it has to take a guess at which
it’s dealing with
-based on what it finds just after the
-<code>{</code>. Usually it gets it right, but if it
-doesn’t it won’t realize something is wrong until it gets to the
<code>}</code> and
-encounters the missing (or unexpected) comma. The syntax error will be
-reported close to the <code>}</code>, but you’ll need to change
something near the <code>{</code>
-such as using a unary <code>+</code> or semicolon to give Perl some help:
-</p>
-<pre class="verbatim"> %hash = map { "\L$_" => 1 } @array #
perl guesses EXPR. wrong
- %hash = map { +"\L$_" => 1 } @array # perl guesses BLOCK.
right
- %hash = map {; "\L$_" => 1 } @array # this also works
- %hash = map { ("\L$_" => 1) } @array # as does this
- %hash = map { lc($_) => 1 } @array # and this.
- %hash = map +( lc($_) => 1 ), @array # this is EXPR and works!
-
- %hash = map ( lc($_), 1 ), @array # evaluates to (1, @array)
-</pre>
-<p>or to force an anon hash constructor use <code>+{</code>:
-</p>
-<pre class="verbatim"> @hashes = map +{ lc($_) => 1 }, @array # EXPR, so
needs
- # comma at end
-</pre>
-<p>to get a list of anonymous hashes each with only one entry apiece.
-</p>
-</dd>
-<dt>mkdir FILENAME,MASK</dt>
-<dd><a name="perlfunc-mkdir-FILENAME_002cMASK"></a>
-</dd>
-<dt>mkdir FILENAME</dt>
-<dd><a name="perlfunc-mkdir-FILENAME"></a>
-</dd>
-<dt>mkdir</dt>
-<dd><a name="perlfunc-mkdir"></a>
-<p>Creates the directory specified by FILENAME, with permissions
-specified by MASK (as modified by <code>umask</code>). If it succeeds it
-returns true; otherwise it returns false and sets <code>$!</code> (errno).
-MASK defaults to 0777 if omitted, and FILENAME defaults
-to <code>$_</code> if omitted.
-</p>
-<p>In general, it is better to create directories with a permissive MASK
-and let the user modify that with their <code>umask</code> 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
-<code>umask</code> discusses the choice of MASK in more detail.
-</p>
-<p>Note that according to the POSIX 1003.1-1996 the FILENAME may have any
-number of trailing slashes. Some operating and filesystems do not get
-this right, so Perl automatically removes all trailing slashes to keep
-everyone happy.
-</p>
-<p>To recursively create a directory structure, look at
-the <code>make_path</code> function of the <a
href="File-Path.html#Top">(File-Path)</a> module.
-</p>
-</dd>
-<dt>msgctl ID,CMD,ARG</dt>
-<dd><a name="perlfunc-msgctl-ID_002cCMD_002cARG"></a>
-<p>Calls the System V IPC function msgctl(2). You’ll probably have to
say
-</p>
-<pre class="verbatim"> use IPC::SysV;
-</pre>
-<p>first to get the correct constant definitions. If CMD is
<code>IPC_STAT</code>,
-then ARG must be a variable that will hold the returned <code>msqid_ds</code>
-structure. Returns like <code>ioctl</code>: the undefined value for error,
-<code>"0 but true"</code> for zero, or the actual return value
otherwise. See also
-<a href="#perlipc-SysV-IPC">perlipc SysV IPC</a> and the documentation for
<code>IPC::SysV</code> and
-<code>IPC::Semaphore</code>.
-</p>
-<p>Portability issues: <a href="#perlport-msgctl">perlport msgctl</a>.
-</p>
-</dd>
-<dt>msgget KEY,FLAGS</dt>
-<dd><a name="perlfunc-msgget-KEY_002cFLAGS"></a>
-<p>Calls the System V IPC function msgget(2). Returns the message queue
-id, or <code>undef</code> on error. See also
-<a href="#perlipc-SysV-IPC">perlipc SysV IPC</a> and the documentation for
<code>IPC::SysV</code> and
-<code>IPC::Msg</code>.
-</p>
-<p>Portability issues: <a href="#perlport-msgget">perlport msgget</a>.
-</p>
-</dd>
-<dt>msgrcv ID,VAR,SIZE,TYPE,FLAGS</dt>
-<dd><a name="perlfunc-msgrcv-ID_002cVAR_002cSIZE_002cTYPE_002cFLAGS"></a>
-<p>Calls the System V IPC function msgrcv to receive a message from
-message queue ID into variable VAR with a maximum message size of
-SIZE. Note that when a message is received, the message type as a
-native long integer will be the first thing in VAR, followed by the
-actual message. This packing may be opened with <code>unpack("l!
a*")</code>.
-Taints the variable. Returns true if successful, false
-on error. See also <a href="#perlipc-SysV-IPC">perlipc SysV IPC</a> and the
documentation for
-<code>IPC::SysV</code> and <code>IPC::SysV::Msg</code>.
-</p>
-<p>Portability issues: <a href="#perlport-msgrcv">perlport msgrcv</a>.
-</p>
-</dd>
-<dt>msgsnd ID,MSG,FLAGS</dt>
-<dd><a name="perlfunc-msgsnd-ID_002cMSG_002cFLAGS"></a>
-<p>Calls the System V IPC function msgsnd to send the message MSG to the
-message queue ID. MSG must begin with the native long integer message
-type, be followed by the length of the actual message, and then finally
-the message itself. This kind of packing can be achieved with
-<code>pack("l! a*", $type, $message)</code>. Returns true if
successful,
-false on error. See also the <code>IPC::SysV</code>
-and <code>IPC::SysV::Msg</code> documentation.
-</p>
-<p>Portability issues: <a href="#perlport-msgsnd">perlport msgsnd</a>.
-</p>
-</dd>
-<dt>my VARLIST</dt>
-<dd><a name="perlfunc-my-VARLIST"></a>
-</dd>
-<dt>my TYPE VARLIST</dt>
-<dd><a name="perlfunc-my-TYPE-VARLIST"></a>
-</dd>
-<dt>my VARLIST : ATTRS</dt>
-<dd><a name="perlfunc-my-VARLIST-_003a-ATTRS"></a>
-</dd>
-<dt>my TYPE VARLIST : ATTRS</dt>
-<dd><a name="perlfunc-my-TYPE-VARLIST-_003a-ATTRS"></a>
-<p>A <code>my</code> declares the listed variables to be local (lexically) to
the
-enclosing block, file, or <code>eval</code>. If more than one variable is
listed,
-the list must be placed in parentheses.
-</p>
-<p>The exact semantics and interface of TYPE and ATTRS are still
-evolving. TYPE may be a bareword, a constant declared
-with <code>use constant</code>, or <code>__PACKAGE__</code>. It is
-currently bound to the use of the <code>fields</code> pragma,
-and attributes are handled using the <code>attributes</code> pragma, or
starting
-from Perl 5.8.0 also via the <code>Attribute::Handlers</code> module. See
-<a href="#perlsub-Private-Variables-via-my_0028_0029">perlsub Private
Variables via my()</a> for details, and <a href="fields.html#Top">(fields)</a>,
-<a href="attributes.html#Top">(attributes)</a>, and <a
href="Attribute-Handlers.html#Top">(Attribute-Handlers)</a>.
-</p>
-<p>Note that with a parenthesised list, <code>undef</code> can be used as a
dummy
-placeholder, for example to skip assignment of initial values:
-</p>
-<pre class="verbatim"> my ( undef, $min, $hour ) = localtime;
-</pre>
-</dd>
-<dt>next LABEL</dt>
-<dd><a name="perlfunc-next-LABEL"></a>
-</dd>
-<dt>next EXPR</dt>
-<dd><a name="perlfunc-next-EXPR"></a>
-</dd>
-<dt>next</dt>
-<dd><a name="perlfunc-next"></a>
-<p>The <code>next</code> command is like the <code>continue</code> statement
in C; it starts
-the next iteration of the loop:
-</p>
-<pre class="verbatim"> LINE: while (<STDIN>) {
- next LINE if /^#/; # discard comments
- #...
- }
-</pre>
-<p>Note that if there were a <code>continue</code> block on the above, it
would get
-executed even on discarded lines. If LABEL is omitted, the command
-refers to the innermost enclosing loop. The <code>next EXPR</code> form,
available
-as of Perl 5.18.0, allows a label name to be computed at run time, being
-otherwise identical to <code>next LABEL</code>.
-</p>
-<p><code>next</code> cannot be used to exit a block which returns a value such
as
-<code>eval {}</code>, <code>sub {}</code>, or <code>do {}</code>, and should
not be used to exit
-a grep() or map() operation.
-</p>
-<p>Note that a block by itself is semantically identical to a loop
-that executes once. Thus <code>next</code> will exit such a block early.
-</p>
-<p>See also <a href="#perlfunc-continue">continue</a> for an illustration of
how <code>last</code>, <code>next</code>, and
-<code>redo</code> work.
-</p>
-<p>Unlike most named operators, this has the same precedence as assignment.
-It is also exempt from the looks-like-a-function rule, so
-<code>next ("foo")."bar"</code> will cause "bar"
to be part of the argument to
-<code>next</code>.
-</p>
-</dd>
-<dt>no MODULE VERSION LIST</dt>
-<dd><a name="perlfunc-no-MODULE-VERSION-LIST"></a>
-</dd>
-<dt>no MODULE VERSION</dt>
-<dd><a name="perlfunc-no-MODULE-VERSION"></a>
-</dd>
-<dt>no MODULE LIST</dt>
-<dd><a name="perlfunc-no-MODULE-LIST"></a>
-</dd>
-<dt>no MODULE</dt>
-<dd><a name="perlfunc-no-MODULE"></a>
-</dd>
-<dt>no VERSION</dt>
-<dd><a name="perlfunc-no-VERSION"></a>
-<p>See the <code>use</code> function, of which <code>no</code> is the opposite.
-</p>
-</dd>
-<dt>oct EXPR</dt>
-<dd><a name="perlfunc-oct-EXPR"></a>
-</dd>
-<dt>oct</dt>
-<dd><a name="perlfunc-oct"></a>
-<p>Interprets EXPR as an octal string and returns the corresponding
-value. (If EXPR happens to start off with <code>0x</code>, interprets it as a
-hex string. If EXPR starts off with <code>0b</code>, it is interpreted as a
-binary string. Leading whitespace is ignored in all three cases.)
-The following will handle decimal, binary, octal, and hex in standard
-Perl notation:
-</p>
-<pre class="verbatim"> $val = oct($val) if $val =~ /^0/;
-</pre>
-<p>If EXPR is omitted, uses <code>$_</code>. To go the other way (produce a
number
-in octal), use sprintf() or printf():
-</p>
-<pre class="verbatim"> $dec_perms = (stat("filename"))[2] &
07777;
- $oct_perm_str = sprintf "%o", $perms;
-</pre>
-<p>The oct() function is commonly used when a string such as <code>644</code>
needs
-to be converted into a file mode, for example. Although Perl
-automatically converts strings into numbers as needed, this automatic
-conversion assumes base 10.
-</p>
-<p>Leading white space is ignored without warning, as too are any trailing
-non-digits, such as a decimal point (<code>oct</code> only handles non-negative
-integers, not negative integers or floating point).
-</p>
-</dd>
-<dt>open FILEHANDLE,EXPR</dt>
-<dd><a name="perlfunc-open-FILEHANDLE_002cEXPR"></a>
-</dd>
-<dt>open FILEHANDLE,MODE,EXPR</dt>
-<dd><a name="perlfunc-open-FILEHANDLE_002cMODE_002cEXPR"></a>
-</dd>
-<dt>open FILEHANDLE,MODE,EXPR,LIST</dt>
-<dd><a name="perlfunc-open-FILEHANDLE_002cMODE_002cEXPR_002cLIST"></a>
-</dd>
-<dt>open FILEHANDLE,MODE,REFERENCE</dt>
-<dd><a name="perlfunc-open-FILEHANDLE_002cMODE_002cREFERENCE"></a>
-</dd>
-<dt>open FILEHANDLE</dt>
-<dd><a name="perlfunc-open-FILEHANDLE"></a>
-<p>Opens the file whose filename is given by EXPR, and associates it with
-FILEHANDLE.
-</p>
-<p>Simple examples to open a file for reading:
-</p>
-<pre class="verbatim"> open(my $fh, "<",
"input.txt")
- or die "cannot open < input.txt: $!";
-</pre>
-<p>and for writing:
-</p>
-<pre class="verbatim"> open(my $fh, ">",
"output.txt")
- or die "cannot open > output.txt: $!";
-</pre>
-<p>(The following is a comprehensive reference to open(): for a gentler
-introduction you may consider <a href="#perlopentut-NAME">perlopentut
NAME</a>.)
-</p>
-<p>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 <code>use strict "refs"</code>
should <em>not</em> be
-in effect.)
-</p>
-<p>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 <code><</code> or nothing, the file is opened for
input.
-If MODE is <code>></code>, the file is opened for output, with existing
files
-first being truncated ("clobbered") and nonexisting files newly
created.
-If MODE is <code>>></code>, the file is opened for appending, again being
-created if necessary.
-</p>
-<p>You can put a <code>+</code> in front of the <code>></code> or
<code><</code> to
-indicate that you want both read and write access to the file; thus
-<code>+<</code> is almost always preferred for read/write updates–the
-<code>+></code> mode would clobber the file first. You can’t usually
use
-either read-write mode for updating textfiles, since they have
-variable-length records. See the <strong>-i</strong> switch in <a
href="#perlrun-NAME">perlrun NAME</a> for a
-better approach. The file is created with permissions of <code>0666</code>
-modified by the process’s <code>umask</code> value.
-</p>
-<p>These various prefixes correspond to the fopen(3) modes of <code>r</code>,
-<code>r+</code>, <code>w</code>, <code>w+</code>, <code>a</code>, and
<code>a+</code>.
-</p>
-<p>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 <code><</code>. It is always safe to use the two-argument form of
<code>open</code> if
-the filename argument is a known literal.
-</p>
-<p>For three or more arguments if MODE is <code>|-</code>, the filename is
-interpreted as a command to which output is to be piped, and if MODE
-is <code>-|</code>, the filename is interpreted as a command that pipes
-output to us. In the two-argument (and one-argument) form, one should
-replace dash (<code>-</code>) with the command.
-See <a href="#perlipc-Using-open_0028_0029-for-IPC">perlipc Using open() for
IPC</a> for more examples of this.
-(You are not allowed to <code>open</code> to a command that pipes both in
<em>and</em>
-out, but see <a href="IPC-Open2.html#Top">(IPC-Open2)</a>, <a
href="IPC-Open3.html#Top">(IPC-Open3)</a>, and
-<a href="#perlipc-Bidirectional-Communication-with-Another-Process">perlipc
Bidirectional Communication with Another Process</a> for
-alternatives.)
-</p>
-<p>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
-to the command invoked if the platform supports it. The meaning of
-<code>open</code> with more than three arguments for non-pipe modes is not yet
-defined, but experimental "layers" may give extra LIST arguments
-meaning.
-</p>
-<p>In the two-argument (and one-argument) form, opening <code><-</code>
-or <code>-</code> opens STDIN and opening <code>>-</code> opens STDOUT.
-</p>
-<p>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 <a
href="open.html#Top">(open)</a> and
-<a href="PerlIO.html#Top">(PerlIO)</a> for more details). For example:
-</p>
-<pre class="verbatim"> open(my $fh, "<:encoding(UTF-8)",
"filename")
- || die "can't open UTF-8 encoded filename: $!";
-</pre>
-<p>opens the UTF8-encoded file containing Unicode characters;
-see <a href="#perluniintro-NAME">perluniintro NAME</a>. Note that if layers
are specified in the
-three-argument form, then default layers stored in ${^OPEN} (see <a
href="#perlvar-NAME">perlvar NAME</a>;
-usually set by the <strong>open</strong> pragma or the switch
<strong>-CioD</strong>) are ignored.
-Those layers will also be ignored if you specifying a colon with no name
-following it. In that case the default layer for the operating system
-(:raw on Unix, :crlf on Windows) is used.
-</p>
-<p>Open returns nonzero on success, the undefined value otherwise. If
-the <code>open</code> involved a pipe, the return value happens to be the pid
of
-the subprocess.
-</p>
-<p>If you’re running Perl on a system that distinguishes between text
-files and binary files, then you should check out ‘binmode’ for
tips
-for dealing with this. The key distinction between systems that need
-<code>binmode</code> and those that don’t is their text file formats.
Systems
-like Unix, Mac OS, and Plan 9, that end lines with a single
-character and encode that character in C as <code>"\n"</code> do not
-need <code>binmode</code>. The rest need it.
-</p>
-<p>When opening a file, it’s seldom a good idea to continue
-if the request failed, so <code>open</code> is frequently used with
-<code>die</code>. Even if <code>die</code> won’t do what you want (say,
in a CGI script,
-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.
-</p>
-<p>The filehandle will be closed when its reference count reaches zero.
-If it is a lexically scoped variable declared with <code>my</code>, that
usually
-means the end of the enclosing scope. However, this automatic close
-does not check for errors, so it is better to explicitly close
-filehandles, especially those used for writing:
-</p>
-<pre class="verbatim"> close($handle)
- || warn "close failed: $!";
-</pre>
-<p>An older style is to use a bareword as the filehandle, as
-</p>
-<pre class="verbatim"> open(FH, "<", "input.txt")
- or die "cannot open < input.txt: $!";
-</pre>
-<p>Then you can use <code>FH</code> as the filehandle, in <code>close
FH</code> and <code><FH></code> and so on. Note that it’s a global
variable, so this form is
-not recommended in new code.
-</p>
-<p>As a shortcut a one-argument call takes the filename from the global
-scalar variable of the same name as the filehandle:
-</p>
-<pre class="verbatim"> $ARTICLE = 100;
- open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";
-</pre>
-<p>Here <code>$ARTICLE</code> must be a global (package) scalar variable - not
one
-declared with <code>my</code> or <code>state</code>.
-</p>
-<p>As a special case the three-argument form with a read/write mode and the
third
-argument being <code>undef</code>:
-</p>
-<pre class="verbatim"> open(my $tmp, "+>", undef) or die ...
-</pre>
-<p>opens a filehandle to an anonymous temporary file. Also using
<code>+<</code>
-works for symmetry, but you really should consider writing something
-to the temporary file first. You will need to seek() to do the
-reading.
-</p>
-<p>Perl is built using PerlIO by default; Unless you’ve
-changed this (such as building Perl with <code>Configure -Uuseperlio</code>),
you can
-open filehandles directly to Perl scalars via:
-</p>
-<pre class="verbatim"> open($fh, ">", \$variable) || ..
-</pre>
-<p>To (re)open <code>STDOUT</code> or <code>STDERR</code> as an in-memory
file, close it first:
-</p>
-<pre class="verbatim"> close STDOUT;
- open(STDOUT, ">", \$variable)
- or die "Can't open STDOUT: $!";
-</pre>
-<p>General examples:
-</p>
-<pre class="verbatim"> open(LOG,
">>/usr/spool/news/twitlog"); # (log is reserved)
- # if the open fails, output is discarded
-
- open(my $dbase, "+<", "dbase.mine") # open for
update
- or die "Can't open 'dbase.mine' for update: $!";
-
- open(my $dbase, "+<dbase.mine") # ditto
- or die "Can't open 'dbase.mine' for update: $!";
-
- open(ARTICLE, "-|", "caesar <$article") # decrypt
article
- or die "Can't start caesar: $!";
-
- open(ARTICLE, "caesar <$article |") # ditto
- or die "Can't start caesar: $!";
-
- open(EXTRACT, "|sort >Tmp$$") # $$ is our process
id
- or die "Can't start sort: $!";
-
- # in-memory files
- 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");
- }
-
- sub process {
- my($filename, $input) = @_;
- $input++; # this is a string increment
- unless (open($input, "<", $filename)) {
- print STDERR "Can't open $filename: $!\n";
- return;
- }
-
- local $_;
- while (<$input>) { # note use of indirection
- if (/^#include "(.*)"/) {
- process($1, $input);
- next;
- }
- #... # whatever
- }
- }
-</pre>
-<p>See <a href="#perliol-NAME">perliol NAME</a> for detailed info on PerlIO.
-</p>
-<p>You may also, in the Bourne shell tradition, specify an EXPR beginning
-with <code>>&</code>, 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 <code>dup(2)</code>) and opened. You may use <code>&</code>
after <code>></code>,
-<code>>></code>, <code><</code>, <code>+></code>,
<code>+>></code>, and <code>+<</code>.
-The mode you specify should match the mode of the original filehandle.
-(Duping a filehandle does not take into account any existing contents
-of IO buffers.) If you use the three-argument
-form, then you can pass either a
-number, the name of a filehandle, or the normal "reference to a
glob".
-</p>
-<p>Here is a script that saves, redirects, and restores <code>STDOUT</code> and
-<code>STDERR</code> using various methods:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
- 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: $!";
-
- select STDERR; $| = 1; # make unbuffered
- select STDOUT; $| = 1; # make unbuffered
-
- 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: $!";
-
- print STDOUT "stdout 2\n";
- print STDERR "stderr 2\n";
-</pre>
-<p>If you specify <code>'<&=X'</code>, where <code>X</code> is a file
descriptor number
-or a filehandle, then Perl will do an equivalent of C’s
<code>fdopen</code> of
-that file descriptor (and not call <code>dup(2)</code>); this is more
-parsimonious of file descriptors. For example:
-</p>
-<pre class="verbatim"> # open for input, reusing the fileno of $fd
- open(FILEHANDLE, "<&=$fd")
-</pre>
-<p>or
-</p>
-<pre class="verbatim"> open(FILEHANDLE, "<&=", $fd)
-</pre>
-<p>or
-</p>
-<pre class="verbatim"> # open for append, using the fileno of OLDFH
- open(FH, ">>&=", OLDFH)
-</pre>
-<p>or
-</p>
-<pre class="verbatim"> open(FH, ">>&=OLDFH")
-</pre>
-<p>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
-<code>open(A, ">>&B")</code>, 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 <code>open(A, ">>&=B")</code>, the
filehandles will share
-the same underlying system file descriptor.
-</p>
-<p>Note that under Perls older than 5.8.0, Perl uses the standard C
library’s’
-fdopen() to implement the <code>=</code> 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.
-</p>
-<p>You can see whether your Perl was built with PerlIO by running <code>perl
-V</code>
-and looking for the <code>useperlio=</code> line. If <code>useperlio</code>
is <code>define</code>, you
-have PerlIO; otherwise you don’t.
-</p>
-<p>If you open a pipe on the command <code>-</code> (that is, specify either
<code>|-</code> or <code>-|</code>
-with the one- or two-argument forms of <code>open</code>),
-an implicit <code>fork</code> is done, so <code>open</code> returns twice: in
the parent
-process it returns the pid
-of the child process, and in the child process it returns (a defined)
<code>0</code>.
-Use <code>defined($pid)</code> or <code>//</code> to determine whether the
open was successful.
-</p>
-<p>For example, use either
-</p>
-<pre class="verbatim"> $child_pid = open(FROM_KID, "-|") // die
"can't fork: $!";
-</pre>
-<p>or
-</p>
-<pre class="verbatim"> $child_pid = open(TO_KID, "|-") // die
"can't fork: $!";
-</pre>
-<p>followed by
-</p>
-<pre class="verbatim"> if ($child_pid) {
- # am the parent:
- # either write TO_KID or else read FROM_KID
- ...
- waitpid $child_pid, 0;
- } else {
- # am the child; use STDIN/STDOUT normally
- ...
- exit;
- }
-</pre>
-<p>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
-the new STDOUT/STDIN. Typically this is used like the normal
-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.
-</p>
-<p>The following blocks are more or less equivalent:
-</p>
-<pre class="verbatim"> 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);
-</pre>
-<p>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 a real <code>fork()</code> (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:
-</p>
-<pre class="verbatim"> open(FOO, "|cat -n | expand -4 | lpr")
- // die "Can't open pipeline to lpr: $!";
-</pre>
-<p>See <a href="#perlipc-Safe-Pipe-Opens">perlipc Safe Pipe Opens</a> for more
examples of this.
-</p>
-<p>Perl will attempt to flush all files opened for
-output before any operation that may do a fork, but this may not be
-supported on some platforms (see <a href="#perlport-NAME">perlport NAME</a>).
To be safe, you may need
-to set <code>$|</code> ($AUTOFLUSH in English) or call the
<code>autoflush()</code> method
-of <code>IO::Handle</code> on any open handles.
-</p>
-<p>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 <code>$^F</code>. See <a href="#perlvar-_0024_005eF">perlvar $^F</a>.
-</p>
-<p>Closing any piped filehandle causes the parent process to wait for the
-child to finish, then returns the status value in <code>$?</code> and
-<code>${^CHILD_ERROR_NATIVE}</code>.
-</p>
-<p>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
-<samp>"rsh cat file |"</samp>, or you could change certain filenames
as needed:
-</p>
-<pre class="verbatim"> $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
- open(FH, $filename) or die "Can't open $filename: $!";
-</pre>
-<p>Use the three-argument form to open a file with arbitrary weird characters
in it,
-</p>
-<pre class="verbatim"> open(FOO, "<", $file)
- || die "can't open < $file: $!";
-</pre>
-<p>otherwise it’s necessary to protect any leading and trailing
whitespace:
-</p>
-<pre class="verbatim"> $file =~ s#^(\s)#./$1#;
- open(FOO, "< $file\0")
- || die "open failed: $!";
-</pre>
-<p>(this may not work on some bizarre filesystems). One should
-conscientiously choose between the <em>magic</em> and <em>three-argument</em>
form
-of open():
-</p>
-<pre class="verbatim"> open(IN, $ARGV[0]) || die "can't open $ARGV[0]:
$!";
-</pre>
-<p>will allow the user to specify an argument of the form <code>"rsh cat
file |"</code>,
-but will not work on a filename that happens to have a trailing space, while
-</p>
-<pre class="verbatim"> open(IN, "<", $ARGV[0])
- || die "can't open < $ARGV[0]: $!";
-</pre>
-<p>will have exactly the opposite restrictions.
-</p>
-<p>If you want a "real" C <code>open</code> (see <a
href="http://man.he.net/man2/open";>open(2)</a> on your system), then you
-should use the <code>sysopen</code> 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:
-</p>
-<pre class="verbatim"> use IO::Handle;
- sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL)
- or die "sysopen $path: $!";
- $oldfh = select(HANDLE); $| = 1; select($oldfh);
- print HANDLE "stuff $$\n";
- seek(HANDLE, 0, 0);
- print "File contains: ", <HANDLE>;
-</pre>
-<p>See ‘seek’ for some details about mixing reading and writing.
-</p>
-<p>Portability issues: <a href="#perlport-open">perlport open</a>.
-</p>
-</dd>
-<dt>opendir DIRHANDLE,EXPR</dt>
-<dd><a name="perlfunc-opendir-DIRHANDLE_002cEXPR"></a>
-<p>Opens a directory named EXPR for processing by <code>readdir</code>,
<code>telldir</code>,
-<code>seekdir</code>, <code>rewinddir</code>, and <code>closedir</code>.
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; that is, it’s autovivified.
-DIRHANDLEs have their own namespace separate from FILEHANDLEs.
-</p>
-<p>See the example at <code>readdir</code>.
-</p>
-</dd>
-<dt>ord EXPR</dt>
-<dd><a name="perlfunc-ord-EXPR"></a>
-</dd>
-<dt>ord</dt>
-<dd><a name="perlfunc-ord"></a>
-<p>Returns the numeric value of the first character of EXPR.
-If EXPR is an empty string, returns 0. If EXPR is omitted, uses
<code>$_</code>.
-(Note <em>character</em>, not byte.)
-</p>
-<p>For the reverse, see <a href="#perlfunc-chr">chr</a>.
-See <a href="#perlunicode-NAME">perlunicode NAME</a> for more about Unicode.
-</p>
-</dd>
-<dt>our VARLIST</dt>
-<dd><a name="perlfunc-our-VARLIST"></a>
-</dd>
-<dt>our TYPE VARLIST</dt>
-<dd><a name="perlfunc-our-TYPE-VARLIST"></a>
-</dd>
-<dt>our VARLIST : ATTRS</dt>
-<dd><a name="perlfunc-our-VARLIST-_003a-ATTRS"></a>
-</dd>
-<dt>our TYPE VARLIST : ATTRS</dt>
-<dd><a name="perlfunc-our-TYPE-VARLIST-_003a-ATTRS"></a>
-<p><code>our</code> makes a lexical alias to a package (i.e. global) variable
of the
-same name in the current package for use within the current lexical scope.
-</p>
-<p><code>our</code> has the same scoping rules as <code>my</code> or
<code>state</code>, meaning that it is
-only valid within a lexical scope. Unlike <code>my</code> and
<code>state</code>, which both
-declare new (lexical) variables, <code>our</code> only creates an alias to an
-existing variable: a package variable of the same name.
-</p>
-<p>This means that when <code>use strict 'vars'</code> is in effect,
<code>our</code> lets you use
-a package variable without qualifying it with the package name, but only within
-the lexical scope of the <code>our</code>
-declaration. This applies immediately–even
-within the same statement.
-</p>
-<pre class="verbatim"> package Foo;
- use strict;
-
- $Foo::foo = 23;
-
- {
- our $foo; # alias to $Foo::foo
- print $foo; # prints 23
- }
-
- print $Foo::foo; # prints 23
-
- print $foo; # ERROR: requires explicit package name
-</pre>
-<p>This works even if the package variable has not been used before, as
-package variables spring into existence when first used.
-</p>
-<pre class="verbatim"> package Foo;
- use strict;
-
- our $foo = 23; # just like $Foo::foo = 23
-
- print $Foo::foo; # prints 23
-</pre>
-<p>Because the variable becomes legal immediately under <code>use strict
'vars'</code>, so
-long as there is no variable with that name is already in scope, you can then
-reference the package variable again even within the same statement.
-</p>
-<pre class="verbatim"> package Foo;
- use strict;
-
- my $foo = $foo; # error, undeclared $foo on right-hand side
- our $foo = $foo; # no errors
-</pre>
-<p>If more than one variable is listed, the list must be placed
-in parentheses.
-</p>
-<pre class="verbatim"> our($bar, $baz);
-</pre>
-<p>An <code>our</code> declaration declares an alias for a package variable
that will be visible
-across its entire lexical scope, even across package boundaries. The
-package in which the variable is entered is determined at the point
-of the declaration, not at the point of use. This means the following
-behavior holds:
-</p>
-<pre class="verbatim"> package Foo;
- our $bar; # declares $Foo::bar for rest of lexical scope
- $bar = 20;
-
- package Bar;
- print $bar; # prints 20, as it refers to $Foo::bar
-</pre>
-<p>Multiple <code>our</code> declarations with the same name in the same
lexical
-scope are allowed if they are in different packages. If they happen
-to be in the same package, Perl will emit warnings if you have asked
-for them, just like multiple <code>my</code> declarations. Unlike a second
-<code>my</code> declaration, which will bind the name to a fresh variable, a
-second <code>our</code> declaration in the same package, in the same scope, is
-merely redundant.
-</p>
-<pre class="verbatim"> use warnings;
- package Foo;
- our $bar; # declares $Foo::bar for rest of lexical scope
- $bar = 20;
-
- package Bar;
- our $bar = 30; # declares $Bar::bar for rest of lexical scope
- print $bar; # prints 30
-
- our $bar; # emits warning but has no other effect
- print $bar; # still prints 30
-</pre>
-<p>An <code>our</code> declaration may also have a list of attributes
associated
-with it.
-</p>
-<p>The exact semantics and interface of TYPE and ATTRS are still
-evolving. TYPE is currently bound to the use of the <code>fields</code>
pragma,
-and attributes are handled using the <code>attributes</code> pragma, or,
starting
-from Perl 5.8.0, also via the <code>Attribute::Handlers</code> module. See
-<a href="#perlsub-Private-Variables-via-my_0028_0029">perlsub Private
Variables via my()</a> for details, and <a href="fields.html#Top">(fields)</a>,
-<a href="attributes.html#Top">(attributes)</a>, and <a
href="Attribute-Handlers.html#Top">(Attribute-Handlers)</a>.
-</p>
-<p>Note that with a parenthesised list, <code>undef</code> can be used as a
dummy
-placeholder, for example to skip assignment of initial values:
-</p>
-<pre class="verbatim"> our ( undef, $min, $hour ) = localtime;
-</pre>
-<p><code>our</code> differs from <code>use vars</code>, which allows use of an
unqualified name
-<em>only</em> within the affected package, but across scopes.
-</p>
-</dd>
-<dt>pack TEMPLATE,LIST</dt>
-<dd><a name="perlfunc-pack-TEMPLATE_002cLIST"></a>
-<p>Takes a LIST of values and converts it into a string using the rules
-given by the TEMPLATE. The resulting string is the concatenation of
-the converted values. Typically, each converted value looks
-like its machine-level representation. For example, on 32-bit machines
-an integer may be represented by a sequence of 4 bytes, which will in
-Perl be presented as a string that’s 4 characters long.
-</p>
-<p>See <a href="#perlpacktut-NAME">perlpacktut NAME</a> for an introduction to
this function.
-</p>
-<p>The TEMPLATE is a sequence of characters that give the order and type
-of values, as follows:
-</p>
-<pre class="verbatim"> a A string with arbitrary binary data, will be null
padded.
- A A text (ASCII) string, will be space padded.
- Z A null-terminated (ASCIZ) string, will be null padded.
-
- b A bit string (ascending bit order inside each byte,
- like vec()).
- B A bit string (descending bit order inside each byte).
- h A hex string (low nybble first).
- H A hex string (high nybble first).
-
- c A signed char (8-bit) value.
- C An unsigned char (octet) value.
- W An unsigned char value (can be greater than 255).
-
- s A signed short (16-bit) value.
- S An unsigned short value.
-
- l A signed long (32-bit) value.
- L An unsigned long value.
-
- q A signed quad (64-bit) value.
- Q An unsigned quad value.
- (Quads are available only if your system supports 64-bit
- integer values _and_ if Perl has been compiled to support
- those. Raises an exception otherwise.)
-
- i A signed integer value.
- I A unsigned integer value.
- (This 'integer' is _at_least_ 32 bits wide. Its exact
- size depends on what a local C compiler calls 'int'.)
-
- n An unsigned short (16-bit) in "network" (big-endian) order.
- N An unsigned long (32-bit) in "network" (big-endian) order.
- v An unsigned short (16-bit) in "VAX" (little-endian) order.
- V An unsigned long (32-bit) in "VAX" (little-endian) order.
-
- j A Perl internal signed integer value (IV).
- J A Perl internal unsigned integer value (UV).
-
- f A single-precision float in native format.
- d A double-precision float in native format.
-
- F A Perl internal floating-point value (NV) in native format
- D A float of long-double precision in native format.
- (Long doubles are available only if your system supports
- long double values _and_ if Perl has been compiled to
- support those. Raises an exception otherwise.
- Note that there are different long double formats.)
-
- p A pointer to a null-terminated string.
- P A pointer to a structure (fixed-length string).
-
- u A uuencoded string.
- U A Unicode character number. Encodes to a character in char-
- acter mode and UTF-8 (or UTF-EBCDIC in EBCDIC platforms) in
- byte mode.
-
- w A BER compressed integer (not an ASN.1 BER, see perlpacktut
- for details). Its bytes represent an unsigned integer in
- base 128, most significant digit first, with as few digits
- as possible. Bit eight (the high bit) is set on each byte
- except the last.
-
- x A null byte (a.k.a ASCII NUL, "\000", chr(0))
- X Back up a byte.
- @ Null-fill or truncate to absolute position, counted from the
- start of the innermost ()-group.
- . Null-fill or truncate to absolute position specified by
- the value.
- ( Start of a ()-group.
-</pre>
-<p>One or more modifiers below may optionally follow certain letters in the
-TEMPLATE (the second column lists letters for which the modifier is valid):
-</p>
-<pre class="verbatim"> ! sSlLiI Forces native (short, long, int)
sizes instead
- of fixed (16-/32-bit) sizes.
-
- ! xX Make x and X act as alignment commands.
-
- ! nNvV Treat integers as signed instead of unsigned.
-
- ! @. Specify position as byte offset in the internal
- representation of the packed string. Efficient
- but dangerous.
-
- > sSiIlLqQ Force big-endian byte-order on the type.
- jJfFdDpP (The "big end" touches the construct.)
-
- < sSiIlLqQ Force little-endian byte-order on the type.
- jJfFdDpP (The "little end" touches the construct.)
-</pre>
-<p>The <code>></code> and <code><</code> modifiers can also be used on
<code>()</code> groups
-to force a particular byte-order on all components in that group,
-including all its subgroups.
-</p>
-<p>The following rules apply:
-</p>
-<ul>
-<li> Each letter may optionally be followed by a number indicating the repeat
-count. A numeric repeat count may optionally be enclosed in brackets, as
-in <code>pack("C[80]", @arr)</code>. The repeat count gobbles that
many values from
-the LIST when used with all format types other than <code>a</code>,
<code>A</code>, <code>Z</code>, <code>b</code>,
-<code>B</code>, <code>h</code>, <code>H</code>, <code>@</code>,
<code>.</code>, <code>x</code>, <code>X</code>, and <code>P</code>, where it
means
-something else, described below. Supplying a <code>*</code> for the repeat
count
-instead of a number means to use however many items are left, except for:
-
-<ul>
-<li> <code>@</code>, <code>x</code>, and <code>X</code>, where it is
equivalent to <code>0</code>.
-
-</li><li> <.>, where it means relative to the start of the string.
-
-</li><li> <code>u</code>, where it is equivalent to 1 (or 45, which here is
equivalent).
-
-</li></ul>
-
-<p>One can replace a numeric repeat count with a template letter enclosed in
-brackets to use the packed byte length of the bracketed template for the
-repeat count.
-</p>
-<p>For example, the template <code>x[L]</code> skips as many bytes as in a
packed long,
-and the template <code>"$t X[$t] $t"</code> unpacks twice whatever
$t (when
-variable-expanded) unpacks. If the template in brackets contains alignment
-commands (such as <code>x![d]</code>), its packed length is calculated as if
the
-start of the template had the maximal possible alignment.
-</p>
-<p>When used with <code>Z</code>, a <code>*</code> as the repeat count is
guaranteed to add a
-trailing null byte, so the resulting string is always one byte longer than
-the byte length of the item itself.
-</p>
-<p>When used with <code>@</code>, the repeat count represents an offset from
the start
-of the innermost <code>()</code> group.
-</p>
-<p>When used with <code>.</code>, the repeat count determines the starting
position to
-calculate the value offset as follows:
-</p>
-<ul>
-<li> If the repeat count is <code>0</code>, it’s relative to the current
position.
-
-</li><li> If the repeat count is <code>*</code>, the offset is relative to the
start of the
-packed string.
-
-</li><li> And if it’s an integer <em>n</em>, the offset is relative to
the start of the
-<em>n</em>th innermost <code>( )</code> group, or to the start of the string
if <em>n</em> is
-bigger then the group level.
-
-</li></ul>
-
-<p>The repeat count for <code>u</code> is interpreted as the maximal number of
bytes
-to encode per line of output, with 0, 1 and 2 replaced by 45. The repeat
-count should not be more than 65.
-</p>
-</li><li> The <code>a</code>, <code>A</code>, and <code>Z</code> types gobble
just one value, but pack it as a
-string of length count, padding with nulls or spaces as needed. When
-unpacking, <code>A</code> strips trailing whitespace and nulls, <code>Z</code>
strips everything
-after the first null, and <code>a</code> returns data with no stripping at all.
-
-<p>If the value to pack is too long, the result is truncated. If it’s
too
-long and an explicit count is provided, <code>Z</code> packs only
<code>$count-1</code> bytes,
-followed by a null byte. Thus <code>Z</code> always packs a trailing null,
except
-when the count is 0.
-</p>
-</li><li> Likewise, the <code>b</code> and <code>B</code> formats pack a
string that’s that many bits long.
-Each such format generates 1 bit of the result. These are typically followed
-by a repeat count like <code>B8</code> or <code>B64</code>.
-
-<p>Each result bit is based on the least-significant bit of the corresponding
-input character, i.e., on <code>ord($char)%2</code>. In particular,
characters <code>"0"</code>
-and <code>"1"</code> generate bits 0 and 1, as do characters
<code>"\000"</code> and <code>"\001"</code>.
-</p>
-<p>Starting from the beginning of the input string, each 8-tuple
-of characters is converted to 1 character of output. With format
<code>b</code>,
-the first character of the 8-tuple determines the least-significant bit of a
-character; with format <code>B</code>, it determines the most-significant bit
of
-a character.
-</p>
-<p>If the length of the input string is not evenly divisible by 8, the
-remainder is packed as if the input string were padded by null characters
-at the end. Similarly during unpacking, "extra" bits are ignored.
-</p>
-<p>If the input string is longer than needed, remaining characters are ignored.
-</p>
-<p>A <code>*</code> for the repeat count uses all characters of the input
field.
-On unpacking, bits are converted to a string of <code>0</code>s and
<code>1</code>s.
-</p>
-</li><li> The <code>h</code> and <code>H</code> formats pack a string that
many nybbles (4-bit groups,
-representable as hexadecimal digits, <code>"0".."9"</code>
<code>"a".."f"</code>) long.
-
-<p>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 <code>ord($char)%16</code>. In
particular,
-characters <code>"0"</code> and <code>"1"</code> generate
nybbles 0 and 1, as do bytes
-<code>"\000"</code> and <code>"\001"</code>. For
characters <code>"a".."f"</code> and
<code>"A".."F"</code>, the result
-is compatible with the usual hexadecimal digits, so that
<code>"a"</code> and
-<code>"A"</code> both generate the nybble <code>0xA==10</code>. Use
only these specific hex
-characters with this format.
-</p>
-<p>Starting from the beginning of the template to pack(), each pair
-of characters is converted to 1 character of output. With format
<code>h</code>, the
-first character of the pair determines the least-significant nybble of the
-output character; with format <code>H</code>, it determines the
most-significant
-nybble.
-</p>
-<p>If the length of the input string is not even, it behaves as if padded by
-a null character at the end. Similarly, "extra" nybbles are ignored
during
-unpacking.
-</p>
-<p>If the input string is longer than needed, extra characters are ignored.
-</p>
-<p>A <code>*</code> for the repeat count uses all characters of the input
field. For
-unpack(), nybbles are converted to a string of hexadecimal digits.
-</p>
-</li><li> The <code>p</code> format packs a pointer to a null-terminated
string. You are
-responsible for ensuring that the string is not a temporary value, as that
-could potentially get deallocated before you got around to using the packed
-result. The <code>P</code> format packs a pointer to a structure of the size
indicated
-by the length. A null pointer is created if the corresponding value for
-<code>p</code> or <code>P</code> is <code>undef</code>; similarly with
unpack(), where a null pointer
-unpacks into <code>undef</code>.
-
-<p>If your system has a strange pointer size–meaning a pointer is
neither as
-big as an int nor as big as a long–it may not be possible to pack or
-unpack pointers in big- or little-endian byte order. Attempting to do
-so raises an exception.
-</p>
-</li><li> The <code>/</code> template character allows packing and unpacking
of a sequence of
-items where the packed structure contains a packed item count followed by
-the packed items themselves. This is useful when the structure you’re
-unpacking has encoded the sizes or repeat counts for some of its fields
-within the structure itself as separate fields.
-
-<p>For <code>pack</code>, you write
<em>length-item</em><code>/</code><em>sequence-item</em>, and the
-<em>length-item</em> describes how the length value is packed. Formats likely
-to be of most use are integer-packing ones like <code>n</code> for Java
strings,
-<code>w</code> for ASN.1 or SNMP, and <code>N</code> for Sun XDR.
-</p>
-<p>For <code>pack</code>, <em>sequence-item</em> may have a repeat count, in
which case
-the minimum of that and the number of available items is used as the argument
-for <em>length-item</em>. If it has no repeat count or uses a
’*’, the number
-of available items is used.
-</p>
-<p>For <code>unpack</code>, an internal stack of integer arguments unpacked so
far is
-used. You write <code>/</code><em>sequence-item</em> and the repeat count is
obtained by
-popping off the last element from the stack. The <em>sequence-item</em> must
not
-have a repeat count.
-</p>
-<p>If <em>sequence-item</em> refers to a string type
(<code>"A"</code>, <code>"a"</code>, or
<code>"Z"</code>),
-the <em>length-item</em> 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:
-</p>
-<pre class="verbatim"> This code: gives this
result:
-
- unpack("W/a", "\004Gurusamy") ("Guru")
- unpack("a3/A A*", "007 Bond J ") ("
Bond", "J")
- unpack("a3 x2 /A A*", "007: Bond, J.") ("Bond,
J", ".")
-
- pack("n/a* w/a","hello,","world")
"\000\006hello,\005world"
- pack("a/W2", ord("a") .. ord("z"))
"2ab"
-</pre>
-<p>The <em>length-item</em> is not returned explicitly from
<code>unpack</code>.
-</p>
-<p>Supplying a count to the <em>length-item</em> format letter is only useful
with
-<code>A</code>, <code>a</code>, or <code>Z</code>. Packing with a
<em>length-item</em> of <code>a</code> or <code>Z</code> may
-introduce <code>"\000"</code> characters, which Perl does not regard
as legal in
-numeric strings.
-</p>
-</li><li> The integer types <code>s</code>, <code>S</code>, <code>l</code>,
and <code>L</code> may be
-followed by a <code>!</code> modifier to specify native shorts or
-longs. As shown in the example above, a bare <code>l</code> means
-exactly 32 bits, although the native <code>long</code> as seen by the local C
compiler
-may be larger. This is mainly an issue on 64-bit platforms. You can
-see whether using <code>!</code> makes any difference this way:
-
-<pre class="verbatim"> printf "format s is %d, s! is %d\n",
- length pack("s"), length pack("s!");
-
- printf "format l is %d, l! is %d\n",
- length pack("l"), length pack("l!");
-</pre>
-<p><code>i!</code> and <code>I!</code> are also allowed, but only for
completeness’ sake:
-they are identical to <code>i</code> and <code>I</code>.
-</p>
-<p>The actual sizes (in bytes) of native shorts, ints, longs, and long
-longs on the platform where Perl was built are also available from
-the command line:
-</p>
-<pre class="verbatim"> $ perl -V:{short,int,long{,long}}size
- shortsize='2';
- intsize='4';
- longsize='4';
- longlongsize='8';
-</pre>
-<p>or programmatically via the <code>Config</code> module:
-</p>
-<pre class="verbatim"> use Config;
- print $Config{shortsize}, "\n";
- print $Config{intsize}, "\n";
- print $Config{longsize}, "\n";
- print $Config{longlongsize}, "\n";
-</pre>
-<p><code>$Config{longlongsize}</code> is undefined on systems without
-long long support.
-</p>
-</li><li> The integer formats <code>s</code>, <code>S</code>, <code>i</code>,
<code>I</code>, <code>l</code>, <code>L</code>, <code>j</code>, and
<code>J</code> are
-inherently non-portable between processors and operating systems because
-they obey native byteorder and endianness. For example, a 4-byte integer
-0x12345678 (305419896 decimal) would be ordered natively (arranged in and
-handled by the CPU registers) into bytes as
-
-<pre class="verbatim"> 0x12 0x34 0x56 0x78 # big-endian
- 0x78 0x56 0x34 0x12 # little-endian
-</pre>
-<p>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 uses (well, used)
-them in little-endian mode, but SGI/Cray uses them in big-endian mode.
-</p>
-<p>The names <em>big-endian</em> and <em>little-endian</em> are comic
references to the
-egg-eating habits of the little-endian Lilliputians and the big-endian
-Blefuscudians from the classic Jonathan Swift satire, <em>Gulliver’s
Travels</em>.
-This entered computer lingo via the paper "On Holy Wars and a Plea for
-Peace" by Danny Cohen, USC/ISI IEN 137, April 1, 1980.
-</p>
-<p>Some systems may have even weirder byte orders such as
-</p>
-<pre class="verbatim"> 0x56 0x78 0x12 0x34
- 0x34 0x12 0x78 0x56
-</pre>
-<p>These are called mid-endian, middle-endian, mixed-endian, or just weird.
-</p>
-<p>You can determine your system endianness with this incantation:
-</p>
-<pre class="verbatim"> printf("%#02x ", $_) for
unpack("W*", pack L=>0x12345678);
-</pre>
-<p>The byteorder on the platform where Perl was built is also available
-via <a href="Config.html#Top">(Config)</a>:
-</p>
-<pre class="verbatim"> use Config;
- print "$Config{byteorder}\n";
-</pre>
-<p>or from the command line:
-</p>
-<pre class="verbatim"> $ perl -V:byteorder
-</pre>
-<p>Byteorders <code>"1234"</code> and
<code>"12345678"</code> are little-endian;
<code>"4321"</code>
-and <code>"87654321"</code> are big-endian. Systems with
multiarchitecture binaries
-will have <code>"ffff"</code>, signifying that static information
doesn’t work,
-one must use runtime probing.
-</p>
-<p>For portably packed integers, either use the formats <code>n</code>,
<code>N</code>, <code>v</code>,
-and <code>V</code> or else use the <code>></code> and <code><</code>
modifiers described
-immediately below. See also <a href="#perlport-NAME">perlport NAME</a>.
-</p>
-</li><li> Also floating point numbers have endianness. Usually (but not
always)
-this agrees with the integer endianness. Even though most platforms
-these days use the IEEE 754 binary format, there are differences,
-especially if the long doubles are involved. You can see the
-<code>Config</code> variables <code>doublekind</code> and
<code>longdblkind</code> (also <code>doublesize</code>,
-<code>longdblsize</code>): the "kind" values are enums, unlike
<code>byteorder</code>.
-
-<p>Portability-wise the best option is probably to keep to the IEEE 754
-64-bit doubles, and of agreed-upon endianness. Another possibility
-is the <code>"%a"</code>) format of <code>printf</code>.
-</p>
-</li><li> Starting with Perl 5.10.0, integer and floating-point formats, along
with
-the <code>p</code> and <code>P</code> formats and <code>()</code> groups, may
all be followed by the
-<code>></code> or <code><</code> endianness modifiers to respectively
enforce big-
-or little-endian byte-order. These modifiers are especially useful
-given how <code>n</code>, <code>N</code>, <code>v</code>, and <code>V</code>
don’t cover signed integers,
-64-bit integers, or floating-point values.
-
-<p>Here are some concerns to keep in mind when using an endianness modifier:
-</p>
-<ul>
-<li> Exchanging signed integers between different platforms works only
-when all platforms store them in the same format. Most platforms store
-signed integers in two’s-complement notation, so usually this is not an
issue.
-
-</li><li> The <code>></code> or <code><</code> modifiers can only be
used on floating-point
-formats on big- or little-endian machines. Otherwise, attempting to
-use them raises an exception.
-
-</li><li> Forcing big- or little-endian byte-order on floating-point values for
-data exchange can work only if all platforms use the same
-binary representation such as IEEE floating-point. Even if all
-platforms are using IEEE, there may still be subtle differences. Being able
-to use <code>></code> or <code><</code> on floating-point values can be
useful,
-but also dangerous if you don’t know exactly what you’re doing.
-It is not a general way to portably store floating-point values.
-
-</li><li> When using <code>></code> or <code><</code> on a
<code>()</code> group, this affects
-all types inside the group that accept byte-order modifiers,
-including all subgroups. It is silently ignored for all other
-types. You are not allowed to override the byte-order within a group
-that already has a byte-order modifier suffix.
-
-</li></ul>
-
-</li><li> Real numbers (floats and doubles) are in native machine format only.
-Due to the multiplicity of floating-point formats and the lack of a
-standard "network" representation for them, no facility for
interchange has been
-made. This means that packed floating-point data written on one machine
-may not be readable on another, even if both use IEEE floating-point
-arithmetic (because the endianness of the memory representation is not part
-of the IEEE spec). See also <a href="#perlport-NAME">perlport NAME</a>.
-
-<p>If you know <em>exactly</em> what you’re doing, you can use the
<code>></code> or <code><</code>
-modifiers to force big- or little-endian byte-order on floating-point values.
-</p>
-<p>Because Perl uses doubles (or long doubles, if configured) internally for
-all numeric calculation, converting from double into float and thence
-to double again loses precision, so <code>unpack("f",
pack("f", $foo)</code>)
-will not in general equal $foo.
-</p>
-</li><li> Pack and unpack can operate in two modes: character mode
(<code>C0</code> mode) where
-the packed string is processed per character, and UTF-8 byte mode
(<code>U0</code> mode)
-where the packed string is processed in its UTF-8-encoded Unicode form on
-a byte-by-byte basis. Character mode is the default
-unless the format string starts with <code>U</code>. You
-can always switch mode mid-format with an explicit
-<code>C0</code> or <code>U0</code> in the format. This mode remains in effect
until the next
-mode change, or until the end of the <code>()</code> group it (directly)
applies to.
-
-<p>Using <code>C0</code> to get Unicode characters while using <code>U0</code>
to get <em>non</em>-Unicode
-bytes is not necessarily obvious. Probably only the first of these
-is what you want:
-</p>
-<pre class="verbatim"> $ 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
-</pre>
-<p>Those examples also illustrate that you should not try to use
-<code>pack</code>/<code>unpack</code> as a substitute for the <a
href="Encode.html#Top">(Encode)</a> module.
-</p>
-</li><li> You must yourself do any alignment or padding by inserting, for
example,
-enough <code>"x"</code>es while packing. There is no way for pack()
and unpack()
-to know where characters are going to or coming from, so they
-handle their output and input as flat sequences of characters.
-
-</li><li> A <code>()</code> group is a sub-TEMPLATE enclosed in parentheses.
A group may
-take a repeat count either as postfix, or for unpack(), also via the
<code>/</code>
-template character. Within each repetition of a group, positioning with
-<code>@</code> starts over at 0. Therefore, the result of
-
-<pre class="verbatim"> pack("@1A((@2A)@3A)", qw[X Y Z])
-</pre>
-<p>is the string <code>"\0X\0\0YZ"</code>.
-</p>
-</li><li> <code>x</code> and <code>X</code> accept the <code>!</code> modifier
to act as alignment commands: they
-jump forward or back to the closest position aligned at a multiple of
<code>count</code>
-characters. For example, to pack() or unpack() a C structure like
-
-<pre class="verbatim"> struct {
- char c; /* one signed, 8-bit character */
- double d;
- char cc[2];
- }
-</pre>
-<p>one may need to use the template <code>c x![d] d c[2]</code>. This assumes
that
-doubles must be aligned to the size of double.
-</p>
-<p>For alignment commands, a <code>count</code> of 0 is equivalent to a
<code>count</code> of 1;
-both are no-ops.
-</p>
-</li><li> <code>n</code>, <code>N</code>, <code>v</code> and <code>V</code>
accept the <code>!</code> modifier to
-represent signed 16-/32-bit integers in big-/little-endian order.
-This is portable only when all platforms sharing packed data use the
-same binary representation for signed integers; for example, when all
-platforms use two’s-complement representation.
-
-</li><li> Comments can be embedded in a TEMPLATE using <code>#</code> through
the end of line.
-White space can separate pack codes from each other, but modifiers and
-repeat counts must follow immediately. Breaking complex templates into
-individual line-by-line components, suitably annotated, can do as much to
-improve legibility and maintainability of pack/unpack formats as
<code>/x</code> can
-for complicated pattern matches.
-
-</li><li> If TEMPLATE requires more arguments than pack() is given, pack()
-assumes additional <code>""</code> arguments. If TEMPLATE requires
fewer arguments
-than given, extra arguments are ignored.
-
-</li><li> Attempting to pack the special floating point values
<code>Inf</code> and <code>NaN</code>
-(infinity, also in negative, and not-a-number) into packed integer values
-(like <code>"L"</code>) is a fatal error. The reason for this is
that there simply
-isn’t any sensible mapping for these special values into integers.
-
-</li></ul>
-
-<p>Examples:
-</p>
-<pre class="verbatim"> $foo = pack("WWWW",65,66,67,68);
- # foo eq "ABCD"
- $foo = pack("W4",65,66,67,68);
- # same thing
- $foo = pack("W4",0x24b6,0x24b7,0x24b8,0x24b9);
- # same thing with Unicode circled letters.
- $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9);
- # same thing with Unicode circled letters. You don't get the
- # UTF-8 bytes because the U at the start of the format caused
- # a switch to U0-mode, so the UTF-8 bytes get joined into
- # characters
- $foo = pack("C0U4",0x24b6,0x24b7,0x24b8,0x24b9);
- # foo eq "\xe2\x92\xb6\xe2\x92\xb7\xe2\x92\xb8\xe2\x92\xb9"
- # This is the UTF-8 encoding of the string in the
- # previous example
-
- $foo = pack("ccxxcc",65,66,67,68);
- # foo eq "AB\0\0CD"
-
- # NOTE: The examples above featuring "W" and "c" are
true
- # only on ASCII and ASCII-derived systems such as ISO Latin 1
- # and UTF-8. On EBCDIC systems, the first example would be
- # $foo = pack("WWWW",193,194,195,196);
-
- $foo = pack("s2",1,2);
- # "\001\000\002\000" on little-endian
- # "\000\001\000\002" on big-endian
-
- $foo =
pack("a4","abcd","x","y","z");
- # "abcd"
-
- $foo =
pack("aaaa","abcd","x","y","z");
- # "axyz"
-
- $foo = pack("a14","abcdefg");
- # "abcdefg\0\0\0\0\0\0\0"
-
- $foo = pack("i9pl", gmtime);
- # a real struct tm (on my system anyway)
-
- $utmp_template = "Z8 Z8 Z16 L";
- $utmp = pack($utmp_template, @utmp1);
- # a struct utmp (BSDish)
-
- @utmp2 = unpack($utmp_template, $utmp);
- # "@utmp1" eq "@utmp2"
-
- sub bintodec {
- unpack("N", pack("B32", substr("0" x 32
. shift, -32)));
- }
-
- $foo = pack('sx2l', 12, 34);
- # short 12, two zero bytes padding, long 34
- $bar = pack('address@hidden', 12, 34);
- # short 12, zero fill to position 4, long 34
- # $foo eq $bar
- $baz = pack('s.l', 12, 4, 34);
- # short 12, zero fill to position 4, long 34
-
- $foo = pack('nN', 42, 4711);
- # pack big-endian 16- and 32-bit unsigned integers
- $foo = pack('S>L>', 42, 4711);
- # exactly the same
- $foo = pack('s<l<', -42, 4711);
- # pack little-endian 16- and 32-bit signed integers
- $foo = pack('(sl)<', -42, 4711);
- # exactly the same
-</pre>
-<p>The same template may generally also be used in unpack().
-</p>
-</dd>
-<dt>package NAMESPACE</dt>
-<dd><a name="perlfunc-package-NAMESPACE"></a>
-</dd>
-<dt>package NAMESPACE VERSION</dt>
-<dd><a name="perlfunc-package-NAMESPACE-VERSION"></a>
-</dd>
-<dt>package NAMESPACE BLOCK</dt>
-<dd><a name="perlfunc-package-NAMESPACE-BLOCK"></a>
-</dd>
-<dt>package NAMESPACE VERSION BLOCK</dt>
-<dd><a name="perlfunc-package-NAMESPACE-VERSION-BLOCK"></a>
-<p>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
-<code>eval</code>). That is, the forms without a BLOCK are operative through
the end
-of the current scope, just like the <code>my</code>, <code>state</code>, and
<code>our</code> operators.
-All unqualified dynamic identifiers in this scope will be in the given
-namespace, except where overridden by another <code>package</code> declaration
or
-when they’re one of the special identifiers that qualify into
<code>main::</code>,
-like <code>STDOUT</code>, <code>ARGV</code>, <code>ENV</code>, and the
punctuation variables.
-</p>
-<p>A package statement affects dynamic variables only, including those
-you’ve used <code>local</code> on, but <em>not</em> lexically-scoped
variables, which are created
-with <code>my</code>, <code>state</code>, or <code>our</code>. Typically it
would be the first
-declaration in a file included by <code>require</code> or <code>use</code>.
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
-identifiers in other packages than the current one by prefixing the identifier
-with the package name and a double colon, as in <code>$SomePack::var</code>
-or <code>ThatPack::INPUT_HANDLE</code>. If package name is omitted, the
<code>main</code>
-package as assumed. That is, <code>$::sail</code> is equivalent to
-<code>$main::sail</code> (as well as to <code>$main'sail</code>, still seen in
ancient
-code, mostly from Perl 4).
-</p>
-<p>If VERSION is provided, <code>package</code> sets the <code>$VERSION</code>
variable in the given
-namespace to a <a href="version.html#Top">(version)</a> object with the
VERSION provided. VERSION must be a
-"strict" style version number as defined by the <a
href="version.html#Top">(version)</a> module: 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. You should set <code>$VERSION</code> only once per package.
-</p>
-<p>See <a href="#perlmod-Packages">perlmod Packages</a> for more information
about packages, modules,
-and classes. See <a href="#perlsub-NAME">perlsub NAME</a> for other scoping
issues.
-</p>
-</dd>
-<dt>__PACKAGE__</dt>
-<dd><a name="perlfunc-_005f_005fPACKAGE_005f_005f"></a>
-<p>A special token that returns the name of the package in which it occurs.
-</p>
-</dd>
-<dt>pipe READHANDLE,WRITEHANDLE</dt>
-<dd><a name="perlfunc-pipe-READHANDLE_002cWRITEHANDLE"></a>
-<p>Opens a pair of connected pipes like the corresponding system call.
-Note that if you set up a loop of piped processes, deadlock can occur
-unless you are very careful. In addition, note that Perl’s pipes use
-IO buffering, so you may need to set <code>$|</code> to flush your WRITEHANDLE
-after each command, depending on the application.
-</p>
-<p>Returns true on success.
-</p>
-<p>See <a href="IPC-Open2.html#Top">(IPC-Open2)</a>, <a
href="IPC-Open3.html#Top">(IPC-Open3)</a>, and
-<a href="#perlipc-Bidirectional-Communication-with-Another-Process">perlipc
Bidirectional Communication with Another Process</a>
-for examples of such things.
-</p>
-<p>On systems that support a close-on-exec flag on files, that flag is set
-on all newly opened file descriptors whose <code>fileno</code>s are
<em>higher</em> than
-the current value of $^F (by default 2 for <code>STDERR</code>). See <a
href="#perlvar-_0024_005eF">perlvar $^F</a>.
-</p>
-</dd>
-<dt>pop ARRAY</dt>
-<dd><a name="perlfunc-pop-ARRAY"></a>
-</dd>
-<dt>pop EXPR</dt>
-<dd><a name="perlfunc-pop-EXPR"></a>
-</dd>
-<dt>pop</dt>
-<dd><a name="perlfunc-pop"></a>
-<p>Pops and returns the last value of the array, shortening the array by
-one element.
-</p>
-<p>Returns the undefined value if the array is empty, although this may also
-happen at other times. If ARRAY is omitted, pops the <code>@ARGV</code> array
in the
-main program, but the <code>@_</code> array in subroutines, just like
<code>shift</code>.
-</p>
-<p>Starting with Perl 5.14, <code>pop</code> can take a scalar EXPR, which
must hold a
-reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of <code>pop</code> is considered highly
experimental.
-The exact behaviour may change in a future version of Perl.
-</p>
-<p>To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work <em>only</em> on Perls
of
-a recent vintage:
-</p>
-<pre class="verbatim"> use 5.014; # so push/pop/etc work on scalars
(experimental)
-</pre>
-</dd>
-<dt>pos SCALAR</dt>
-<dd><a name="perlfunc-pos-SCALAR"></a>
-</dd>
-<dt>pos</dt>
-<dd><a name="perlfunc-pos"></a>
-<p>Returns the offset of where the last <code>m//g</code> search left off for
the
-variable in question (<code>$_</code> is used when the variable is not
-specified). Note that 0 is a valid match offset. <code>undef</code> 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).
-</p>
-<p><code>pos</code> directly accesses the location used by the regexp engine to
-store the offset, so assigning to <code>pos</code> will change that offset, and
-so will also influence the <code>\G</code> zero-width assertion in regular
-expressions. Both of these effects take place for the next match, so
-you can’t affect the position with <code>pos</code> during the current
match,
-such as in <code>(?{pos() = 5})</code> or <code>s//pos() = 5/e</code>.
-</p>
-<p>Setting <code>pos</code> also resets the <em>matched with zero-length</em>
flag, described
-under <a
href="#perlre-Repeated-Patterns-Matching-a-Zero_002dlength-Substring">perlre
Repeated Patterns Matching a Zero-length Substring</a>.
-</p>
-<p>Because a failed <code>m//gc</code> match doesn’t reset the offset,
the return
-from <code>pos</code> won’t change either in this case. See <a
href="#perlre-NAME">perlre NAME</a> and
-<a href="#perlop-NAME">perlop NAME</a>.
-</p>
-</dd>
-<dt>print FILEHANDLE LIST</dt>
-<dd><a name="perlfunc-print-FILEHANDLE-LIST"></a>
-</dd>
-<dt>print FILEHANDLE</dt>
-<dd><a name="perlfunc-print-FILEHANDLE"></a>
-</dd>
-<dt>print LIST</dt>
-<dd><a name="perlfunc-print-LIST"></a>
-</dd>
-<dt>print</dt>
-<dd><a name="perlfunc-print"></a>
-<p>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 <code>+</code> or put
-parentheses around the arguments.) If FILEHANDLE is omitted, prints to the
-last selected (see <a href="#perlfunc-select">select</a>) output handle. If
LIST is omitted, prints
-<code>$_</code> to the currently selected output handle. To use FILEHANDLE
alone to
-print the content of <code>$_</code> to it, you must use a real filehandle like
-<code>FH</code>, not an indirect one like <code>$fh</code>. To set the
default output handle
-to something other than STDOUT, use the select operation.
-</p>
-<p>The current value of <code>$,</code> (if any) is printed between each LIST
item. The
-current value of <code>$\</code> (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
-<code>print</code>. 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 <code>+</code>, but that doesn’t look as good).
-</p>
-<p>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:
-</p>
-<pre class="verbatim"> print { $files[$i] } "stuff\n";
- print { $OK ? STDOUT : STDERR } "stuff\n";
-</pre>
-<p>Printing to a closed pipe or socket will generate a SIGPIPE signal. See
-<a href="#perlipc-NAME">perlipc NAME</a> for more on signal handling.
-</p>
-</dd>
-<dt>printf FILEHANDLE FORMAT, LIST</dt>
-<dd><a name="perlfunc-printf-FILEHANDLE-FORMAT_002c-LIST"></a>
-</dd>
-<dt>printf FILEHANDLE</dt>
-<dd><a name="perlfunc-printf-FILEHANDLE"></a>
-</dd>
-<dt>printf FORMAT, LIST</dt>
-<dd><a name="perlfunc-printf-FORMAT_002c-LIST"></a>
-</dd>
-<dt>printf</dt>
-<dd><a name="perlfunc-printf"></a>
-<p>Equivalent to <code>print FILEHANDLE sprintf(FORMAT, LIST)</code>, except
that <code>$\</code>
-(the output record separator) is not appended. The FORMAT and the
-LIST are actually parsed as a single list. The first argument
-of the list will be interpreted as the <code>printf</code> format. This
-means that <code>printf(@_)</code> will use <code>$_[0]</code> as the format.
See
-<a href="#perlfunc-sprintf-FORMAT_002c-LIST">sprintf</a> for an
-explanation of the format argument. If <code>use locale</code> for
<code>LC_NUMERIC</code>
-Look for this throught pod
-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
<code>LC_NUMERIC</code>
-locale setting. See <a href="#perllocale-NAME">perllocale NAME</a> and <a
href="POSIX.html#Top">(POSIX)</a>.
-</p>
-<p>For historical reasons, if you omit the list, <code>$_</code> is used as
the format;
-to use FILEHANDLE without a list, you must use a real filehandle like
-<code>FH</code>, not an indirect one like <code>$fh</code>. However, this
will rarely do what
-you want; if $_ contains formatting codes, they will be replaced with the
-empty string and a warning will be emitted if warnings are enabled. Just
-use <code>print</code> if you want to print the contents of $_.
-</p>
-<p>Don’t fall into the trap of using a <code>printf</code> when a simple
-<code>print</code> would do. The <code>print</code> is more efficient and less
-error prone.
-</p>
-</dd>
-<dt>prototype FUNCTION</dt>
-<dd><a name="perlfunc-prototype-FUNCTION"></a>
-</dd>
-<dt>prototype</dt>
-<dd><a name="perlfunc-prototype"></a>
-<p>Returns the prototype of a function as a string (or <code>undef</code> if
the
-function has no prototype). FUNCTION is a reference to, or the name of,
-the function whose prototype you want to retrieve. If FUNCTION is omitted,
-$_ is used.
-</p>
-<p>If FUNCTION is a string starting with <code>CORE::</code>, the rest is
taken as a
-name for a Perl builtin. If the builtin’s arguments
-cannot be adequately expressed by a prototype
-(such as <code>system</code>), prototype() returns <code>undef</code>, because
the builtin
-does not really behave like a Perl function. Otherwise, the string
-describing the equivalent prototype is returned.
-</p>
-</dd>
-<dt>push ARRAY,LIST</dt>
-<dd><a name="perlfunc-push-ARRAY_002cLIST"></a>
-</dd>
-<dt>push EXPR,LIST</dt>
-<dd><a name="perlfunc-push-EXPR_002cLIST"></a>
-<p>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
-</p>
-<pre class="verbatim"> for $value (LIST) {
- $ARRAY[++$#ARRAY] = $value;
- }
-</pre>
-<p>but is more efficient. Returns the number of elements in the array
following
-the completed <code>push</code>.
-</p>
-<p>Starting with Perl 5.14, <code>push</code> can take a scalar EXPR, which
must hold a
-reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of <code>push</code> is considered highly
experimental.
-The exact behaviour may change in a future version of Perl.
-</p>
-<p>To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work <em>only</em> on Perls
of
-a recent vintage:
-</p>
-<pre class="verbatim"> use 5.014; # so push/pop/etc work on scalars
(experimental)
-</pre>
-</dd>
-<dt>q/STRING/</dt>
-<dd><a name="perlfunc-q_002fSTRING_002f"></a>
-</dd>
-<dt>qq/STRING/</dt>
-<dd><a name="perlfunc-qq_002fSTRING_002f"></a>
-</dd>
-<dt>qw/STRING/</dt>
-<dd><a name="perlfunc-qw_002fSTRING_002f"></a>
-</dd>
-<dt>qx/STRING/</dt>
-<dd><a name="perlfunc-qx_002fSTRING_002f"></a>
-<p>Generalized quotes. See <a href="#perlop-Quote_002dLike-Operators">perlop
Quote-Like Operators</a>.
-</p>
-</dd>
-<dt>qr/STRING/</dt>
-<dd><a name="perlfunc-qr_002fSTRING_002f"></a>
-<p>Regexp-like quote. See <a
href="#perlop-Regexp-Quote_002dLike-Operators">perlop Regexp Quote-Like
Operators</a>.
-</p>
-</dd>
-<dt>quotemeta EXPR</dt>
-<dd><a name="perlfunc-quotemeta-EXPR"></a>
-</dd>
-<dt>quotemeta</dt>
-<dd><a name="perlfunc-quotemeta"></a>
-<p>Returns the value of EXPR with all the ASCII non-"word"
-characters backslashed. (That is, all ASCII characters not matching
-<code>/[A-Za-z_0-9]/</code> will be preceded by a backslash in the
-returned string, regardless of any locale settings.)
-This is the internal function implementing
-the <code>\Q</code> escape in double-quoted strings.
-(See below for the behavior on non-ASCII code points.)
-</p>
-<p>If EXPR is omitted, uses <code>$_</code>.
-</p>
-<p>quotemeta (and <code>\Q</code> ... <code>\E</code>) are useful when
interpolating strings into
-regular expressions, because by default an interpolated variable will be
-considered a mini-regular expression. For example:
-</p>
-<pre class="verbatim"> my $sentence = 'The quick brown fox jumped over the
lazy dog';
- my $substring = 'quick.*?fox';
- $sentence =~ s{$substring}{big bad wolf};
-</pre>
-<p>Will cause <code>$sentence</code> to become <code>'The big bad wolf jumped
over...'</code>.
-</p>
-<p>On the other hand:
-</p>
-<pre class="verbatim"> my $sentence = 'The quick brown fox jumped over the
lazy dog';
- my $substring = 'quick.*?fox';
- $sentence =~ s{\Q$substring\E}{big bad wolf};
-</pre>
-<p>Or:
-</p>
-<pre class="verbatim"> my $sentence = 'The quick brown fox jumped over the
lazy dog';
- my $substring = 'quick.*?fox';
- my $quoted_substring = quotemeta($substring);
- $sentence =~ s{$quoted_substring}{big bad wolf};
-</pre>
-<p>Will both leave the sentence as is.
-Normally, when accepting literal string
-input from the user, quotemeta() or <code>\Q</code> must be used.
-</p>
-<p>In Perl v5.14, all non-ASCII characters are quoted in non-UTF-8-encoded
-strings, but not quoted in UTF-8 strings.
-</p>
-<p>Starting in Perl v5.16, Perl adopted a Unicode-defined strategy for
-quoting non-ASCII characters; the quoting of ASCII characters is
-unchanged.
-</p>
-<p>Also unchanged is the quoting of non-UTF-8 strings when outside the
-scope of a <code>use feature 'unicode_strings'</code>, which is to quote all
-characters in the upper Latin1 range. This provides complete backwards
-compatibility for old programs which do not use Unicode. (Note that
-<code>unicode_strings</code> is automatically enabled within the scope of a
-<code>use v5.12</code><!-- /@w --> or greater.)
-</p>
-<p>Within the scope of <code>use locale</code>, all non-ASCII Latin1 code
points
-are quoted whether the string is encoded as UTF-8 or not. As mentioned
-above, locale does not affect the quoting of ASCII-range characters.
-This protects against those locales where characters such as
<code>"|"</code> are
-considered to be word characters.
-</p>
-<p>Otherwise, Perl quotes non-ASCII characters using an adaptation from
-Unicode (see <a
href="http://www.unicode.org/reports/tr31/";>http://www.unicode.org/reports/tr31/</a>).
-The only code points that are quoted are those that have any of the
-Unicode properties: Pattern_Syntax, Pattern_White_Space, White_Space,
-Default_Ignorable_Code_Point, or General_Category=Control.
-</p>
-<p>Of these properties, the two important ones are Pattern_Syntax and
-Pattern_White_Space. They have been set up by Unicode for exactly this
-purpose of deciding which characters in a regular expression pattern
-should be quoted. No character that can be in an identifier has these
-properties.
-</p>
-<p>Perl promises, that if we ever add regular expression pattern
-metacharacters to the dozen already defined
-(<code>\ | ( ) [ { ^ $ * + ? .</code>), that we will only use ones that have
the
-Pattern_Syntax property. Perl also promises, that if we ever add
-characters that are considered to be white space in regular expressions
-(currently mostly affected by <code>/x</code>), they will all have the
-Pattern_White_Space property.
-</p>
-<p>Unicode promises that the set of code points that have these two
-properties will never change, so something that is not quoted in v5.16
-will never need to be quoted in any future Perl release. (Not all the
-code points that match Pattern_Syntax have actually had characters
-assigned to them; so there is room to grow, but they are quoted
-whether assigned or not. Perl, of course, would never use an
-unassigned code point as an actual metacharacter.)
-</p>
-<p>Quoting characters that have the other 3 properties is done to enhance
-the readability of the regular expression and not because they actually
-need to be quoted for regular expression purposes (characters with the
-White_Space property are likely to be indistinguishable on the page or
-screen from those with the Pattern_White_Space property; and the other
-two properties contain non-printing characters).
-</p>
-</dd>
-<dt>rand EXPR</dt>
-<dd><a name="perlfunc-rand-EXPR"></a>
-</dd>
-<dt>rand</dt>
-<dd><a name="perlfunc-rand"></a>
-<p>Returns a random fractional number greater than or equal to <code>0</code>
and less
-than the value of EXPR. (EXPR should be positive.) If EXPR is
-omitted, the value <code>1</code> is used. Currently EXPR with the value
<code>0</code> is
-also special-cased as <code>1</code> (this was undocumented before Perl 5.8.0
-and is subject to change in future versions of Perl). Automatically calls
-<code>srand</code> unless <code>srand</code> has already been called. See
also <code>srand</code>.
-</p>
-<p>Apply <code>int()</code> to the value returned by <code>rand()</code> if
you want random
-integers instead of random fractional numbers. For example,
-</p>
-<pre class="verbatim"> int(rand(10))
-</pre>
-<p>returns a random integer between <code>0</code> and <code>9</code>,
inclusive.
-</p>
-<p>(Note: If your rand function consistently returns numbers that are too
-large or too small, then your version of Perl was probably compiled
-with the wrong number of RANDBITS.)
-</p>
-<p><strong><code>rand()</code> is not cryptographically secure. You should
not rely
-on it in security-sensitive situations.</strong> As of this writing, a
-number of third-party CPAN modules offer random number generators
-intended by their authors to be cryptographically secure,
-including: <a href="Data-Entropy.html#Top">(Data-Entropy)</a>, <a
href="Crypt-Random.html#Top">(Crypt-Random)</a>, <a
href="Math-Random-Secure.html#Top">(Math-Random-Secure)</a>,
-and <a href="Math-TrulyRandom.html#Top">(Math-TrulyRandom)</a>.
-</p>
-</dd>
-<dt>read FILEHANDLE,SCALAR,LENGTH,OFFSET</dt>
-<dd><a name="perlfunc-read-FILEHANDLE_002cSCALAR_002cLENGTH_002cOFFSET"></a>
-</dd>
-<dt>read FILEHANDLE,SCALAR,LENGTH</dt>
-<dd><a name="perlfunc-read-FILEHANDLE_002cSCALAR_002cLENGTH"></a>
-<p>Attempts to read LENGTH <em>characters</em> of data into variable SCALAR
-from the specified FILEHANDLE. Returns the number of characters
-actually read, <code>0</code> at end of file, or undef if there was an error
(in
-the latter case <code>$!</code> is also set). SCALAR will be grown or shrunk
-so that the last character actually read is the last character of the
-scalar after the read.
-</p>
-<p>An OFFSET may be specified to place the read data at some place in the
-string other than the beginning. A negative OFFSET specifies
-placement at that many characters counting backwards from the end of
-the string. A positive OFFSET greater than the length of SCALAR
-results in the string being padded to the required size with
<code>"\0"</code>
-bytes before the result of the read is appended.
-</p>
-<p>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
-<a
href="#perlfunc-sysread-FILEHANDLE_002cSCALAR_002cLENGTH_002cOFFSET">sysread</a>.
-</p>
-<p>Note the <em>characters</em>: depending on the status of the filehandle,
-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 <code>:utf8</code> I/O layer (see ‘open’, and
the <code>open</code>
-pragma, <a href="open.html#Top">(open)</a>), the I/O will operate on
UTF8-encoded Unicode
-characters, not bytes. Similarly for the <code>:encoding</code> pragma:
-in that case pretty much any characters can be read.
-</p>
-</dd>
-<dt>readdir DIRHANDLE</dt>
-<dd><a name="perlfunc-readdir-DIRHANDLE"></a>
-<p>Returns the next directory entry for a directory opened by
<code>opendir</code>.
-If used in list context, returns all the rest of the entries in the
-directory. If there are no more entries, returns the undefined value in
-scalar context and the empty list in list context.
-</p>
-<p>If you’re planning to filetest the return values out of a
<code>readdir</code>, you’d
-better prepend the directory in question. Otherwise, because we didn’t
-<code>chdir</code> there, it would have been testing the wrong file.
-</p>
-<pre class="verbatim"> opendir(my $dh, $some_dir) || die "can't
opendir $some_dir: $!";
- @dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh);
- closedir $dh;
-</pre>
-<p>As of Perl 5.12 you can use a bare <code>readdir</code> in a
<code>while</code> loop,
-which will set <code>$_</code> on every iteration.
-</p>
-<pre class="verbatim"> opendir(my $dh, $some_dir) || die;
- while(readdir $dh) {
- print "$some_dir/$_\n";
- }
- closedir $dh;
-</pre>
-<p>To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious failures, put this sort of thing at the
-top of your file to signal that your code will work <em>only</em> on Perls of a
-recent vintage:
-</p>
-<pre class="verbatim"> use 5.012; # so readdir assigns to $_ in a lone
while test
-</pre>
-</dd>
-<dt>readline EXPR</dt>
-<dd><a name="perlfunc-readline-EXPR"></a>
-</dd>
-<dt>readline</dt>
-<dd><a name="perlfunc-readline"></a>
-<p>Reads from the filehandle whose typeglob is contained in EXPR (or from
-<code>*ARGV</code> 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 <code>undef</code>. In list context, reads until
end-of-file
-is reached and returns a list of lines. Note that the notion of
"line"
-used here is whatever you may have defined with <code>$/</code> or
-<code>$INPUT_RECORD_SEPARATOR</code>). See <a
href="#perlvar-_0024_002f">perlvar $/</a>.
-</p>
-<p>When <code>$/</code> is set to <code>undef</code>, when
<code>readline</code> is in scalar
-context (i.e., file slurp mode), and when an empty file is read, it
-returns <code>''</code> the first time, followed by <code>undef</code>
subsequently.
-</p>
-<p>This is the internal function implementing the <code><EXPR></code>
-operator, but you can use it directly. The <code><EXPR></code>
-operator is discussed in more detail in <a
href="#perlop-I_002fO-Operators">perlop I/O Operators</a>.
-</p>
-<pre class="verbatim"> $line = <STDIN>;
- $line = readline(*STDIN); # same thing
-</pre>
-<p>If <code>readline</code> encounters an operating system error,
<code>$!</code> will be set
-with the corresponding error message. It can be helpful to check
-<code>$!</code> when you are reading from filehandles you don’t trust,
such as a
-tty or a socket. The following example uses the operator form of
-<code>readline</code> and dies if the result is not defined.
-</p>
-<pre class="verbatim"> while ( ! eof($fh) ) {
- defined( $_ = <$fh> ) or die "readline failed: $!";
- ...
- }
-</pre>
-<p>Note that you have can’t handle <code>readline</code> errors that way
with the
-<code>ARGV</code> filehandle. In that case, you have to open each element of
-<code>@ARGV</code> yourself since <code>eof</code> handles <code>ARGV</code>
differently.
-</p>
-<pre class="verbatim"> foreach my $arg (@ARGV) {
- open(my $fh, $arg) or warn "Can't open $arg: $!";
-
- while ( ! eof($fh) ) {
- defined( $_ = <$fh> )
- or die "readline failed for $arg: $!";
- ...
- }
- }
-</pre>
-</dd>
-<dt>readlink EXPR</dt>
-<dd><a name="perlfunc-readlink-EXPR"></a>
-</dd>
-<dt>readlink</dt>
-<dd><a name="perlfunc-readlink"></a>
-<p>Returns the value of a symbolic link, if symbolic links are
-implemented. If not, raises an exception. If there is a system
-error, returns the undefined value and sets <code>$!</code> (errno). If EXPR
is
-omitted, uses <code>$_</code>.
-</p>
-<p>Portability issues: <a href="#perlport-readlink">perlport readlink</a>.
-</p>
-</dd>
-<dt>readpipe EXPR</dt>
-<dd><a name="perlfunc-readpipe-EXPR"></a>
-</dd>
-<dt>readpipe</dt>
-<dd><a name="perlfunc-readpipe"></a>
-<p>EXPR is executed as a system command.
-The collected standard output of the command is returned.
-In scalar context, it comes back as a single (potentially
-multi-line) string. In list context, returns a list of lines
-(however you’ve defined lines with <code>$/</code> or
<code>$INPUT_RECORD_SEPARATOR</code>).
-This is the internal function implementing the <code>qx/EXPR/</code>
-operator, but you can use it directly. The <code>qx/EXPR/</code>
-operator is discussed in more detail in <a
href="#perlop-I_002fO-Operators">perlop I/O Operators</a>.
-If EXPR is omitted, uses <code>$_</code>.
-</p>
-</dd>
-<dt>recv SOCKET,SCALAR,LENGTH,FLAGS</dt>
-<dd><a name="perlfunc-recv-SOCKET_002cSCALAR_002cLENGTH_002cFLAGS"></a>
-<p>Receives a message on a socket. Attempts to receive LENGTH characters
-of data into variable SCALAR from the specified SOCKET filehandle.
-SCALAR will be grown or shrunk to the length actually read. Takes the
-same flags as the system call of the same name. Returns the address
-of the sender if SOCKET’s protocol supports this; returns an empty
-string otherwise. If there’s an error, returns the undefined value.
-This call is actually implemented in terms of recvfrom(2) system call.
-See <a href="#perlipc-UDP_003a-Message-Passing">perlipc UDP: Message
Passing</a> for examples.
-</p>
-<p>Note the <em>characters</em>: 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 <code>:encoding(utf8)</code> I/O layer (see the
-<code>open</code> pragma, <a href="open.html#Top">(open)</a>), the I/O will
operate on UTF8-encoded Unicode
-characters, not bytes. Similarly for the <code>:encoding</code> pragma: in
that
-case pretty much any characters can be read.
-</p>
-</dd>
-<dt>redo LABEL</dt>
-<dd><a name="perlfunc-redo-LABEL"></a>
-</dd>
-<dt>redo EXPR</dt>
-<dd><a name="perlfunc-redo-EXPR"></a>
-</dd>
-<dt>redo</dt>
-<dd><a name="perlfunc-redo"></a>
-<p>The <code>redo</code> command restarts the loop block without evaluating the
-conditional again. The <code>continue</code> block, if any, is not executed.
If
-the LABEL is omitted, the command refers to the innermost enclosing
-loop. The <code>redo EXPR</code> form, available starting in Perl 5.18.0,
allows a
-label name to be computed at run time, and is otherwise identical to <code>redo
-LABEL</code>. Programs that want to lie to themselves about what was just
input
-normally use this command:
-</p>
-<pre class="verbatim"> # a simpleminded Pascal comment stripper
- # (warning: assumes no { or } in strings)
- LINE: while (<STDIN>) {
- while (s|({.*}.*){.*}|$1 |) {}
- s|{.*}| |;
- if (s|{.*| |) {
- $front = $_;
- while (<STDIN>) {
- if (/}/) { # end of comment?
- s|^|$front\{|;
- redo LINE;
- }
- }
- }
- print;
- }
-</pre>
-<p><code>redo</code> cannot be used to retry a block that returns a value such
as
-<code>eval {}</code>, <code>sub {}</code>, or <code>do {}</code>, and should
not be used to exit
-a grep() or map() operation.
-</p>
-<p>Note that a block by itself is semantically identical to a loop
-that executes once. Thus <code>redo</code> inside such a block will
effectively
-turn it into a looping construct.
-</p>
-<p>See also <a href="#perlfunc-continue">continue</a> for an illustration of
how <code>last</code>, <code>next</code>, and
-<code>redo</code> work.
-</p>
-<p>Unlike most named operators, this has the same precedence as assignment.
-It is also exempt from the looks-like-a-function rule, so
-<code>redo ("foo")."bar"</code> will cause "bar"
to be part of the argument to
-<code>redo</code>.
-</p>
-</dd>
-<dt>ref EXPR</dt>
-<dd><a name="perlfunc-ref-EXPR"></a>
-</dd>
-<dt>ref</dt>
-<dd><a name="perlfunc-ref"></a>
-<p>Returns a non-empty string if EXPR is a reference, the empty
-string otherwise. If EXPR is not specified, <code>$_</code> will be used. The
-value returned depends on the type of thing the reference is a reference to.
-</p>
-<p>Builtin types include:
-</p>
-<pre class="verbatim"> SCALAR
- ARRAY
- HASH
- CODE
- REF
- GLOB
- LVALUE
- FORMAT
- IO
- VSTRING
- Regexp
-</pre>
-<p>You can think of <code>ref</code> as a <code>typeof</code> operator.
-</p>
-<pre class="verbatim"> if (ref($r) eq "HASH") {
- print "r is a reference to a hash.\n";
- }
- unless (ref($r)) {
- print "r is not a reference at all.\n";
- }
-</pre>
-<p>The return value <code>LVALUE</code> indicates a reference to an lvalue
that is not
-a variable. You get this from taking the reference of function calls like
-<code>pos()</code> or <code>substr()</code>. <code>VSTRING</code> is returned
if the reference points
-to a <a href="#perldata-Version-Strings">version string</a>.
-</p>
-<p>The result <code>Regexp</code> indicates that the argument is a regular
expression
-resulting from <code>qr//</code>.
-</p>
-<p>If the referenced object has been blessed into a package, then that package
-name is returned instead. But don’t use that, as it’s now
considered
-"bad practice". For one reason, an object could be using a class
called
-<code>Regexp</code> or <code>IO</code>, or even <code>HASH</code>. Also,
<code>ref</code> doesn’t take into account
-subclasses, like <code>isa</code> does.
-</p>
-<p>Instead, use <code>blessed</code> (in the <a
href="Scalar-Util.html#Top">(Scalar-Util)</a> module) for boolean
-checks, <code>isa</code> for specific class checks and <code>reftype</code>
(also from
-<a href="Scalar-Util.html#Top">(Scalar-Util)</a>) for type checks. (See <a
href="#perlobj-NAME">perlobj NAME</a> for details and a
-<code>blessed/isa</code> example.)
-</p>
-<p>See also <a href="#perlref-NAME">perlref NAME</a>.
-</p>
-</dd>
-<dt>rename OLDNAME,NEWNAME</dt>
-<dd><a name="perlfunc-rename-OLDNAME_002cNEWNAME"></a>
-<p>Changes the name of a file; an existing file NEWNAME will be
-clobbered. Returns true for success, false otherwise.
-</p>
-<p>Behavior of this function varies wildly depending on your system
-implementation. For example, it will usually not work across file system
-boundaries, even though the system <em>mv</em> command sometimes compensates
-for this. Other restrictions include whether it works on directories,
-open files, or pre-existing files. Check <a href="#perlport-NAME">perlport
NAME</a> and either the
-rename(2) manpage or equivalent system documentation for details.
-</p>
-<p>For a platform independent <code>move</code> function look at the <a
href="File-Copy.html#Top">(File-Copy)</a>
-module.
-</p>
-<p>Portability issues: <a href="#perlport-rename">perlport rename</a>.
-</p>
-</dd>
-<dt>require VERSION</dt>
-<dd><a name="perlfunc-require-VERSION"></a>
-</dd>
-<dt>require EXPR</dt>
-<dd><a name="perlfunc-require-EXPR"></a>
-</dd>
-<dt>require</dt>
-<dd><a name="perlfunc-require"></a>
-<p>Demands a version of Perl specified by VERSION, or demands some semantics
-specified by EXPR or by <code>$_</code> if EXPR is not supplied.
-</p>
-<p>VERSION may be either a numeric argument such as 5.006, which will be
-compared to <code>$]</code>, or a literal of the form v5.6.1, which will be
compared
-to <code>$^V</code> (aka $PERL_VERSION). An exception is raised if
-VERSION is greater than the version of the current Perl interpreter.
-Compare with ‘use’, which can do a similar check at compile time.
-</p>
-<p>Specifying VERSION as a literal of the form v5.6.1 should generally be
-avoided, because it leads to misleading error messages under earlier
-versions of Perl that do not support this syntax. The equivalent numeric
-version should be used instead.
-</p>
-<pre class="verbatim"> require v5.6.1; # run time version check
- require 5.6.1; # ditto
- require 5.006_001; # ditto; preferred for backwards
- compatibility
-</pre>
-<p>Otherwise, <code>require</code> demands that a library file be included if
it
-hasn’t already been included. The file is included via the do-FILE
-mechanism, which is essentially just a variety of <code>eval</code> with the
-caveat that lexical variables in the invoking script will be invisible
-to the included code. If it were implemented in pure Perl, it
-would have semantics similar to the following:
-</p>
-<pre class="verbatim"> use Carp 'croak';
- use version;
-
- sub require {
- my ($filename) = @_;
- if ( my $version = eval { version->parse($filename) } ) {
- if ( $version > $^V ) {
- my $vn = $version->normal;
- croak "Perl $vn required--this is only $^V, stopped";
- }
- return 1;
- }
-
- if (exists $INC{$filename}) {
- return 1 if $INC{$filename};
- croak "Compilation failed in require";
- }
-
- foreach $prefix (@INC) {
- if (ref($prefix)) {
- #... do other stuff - see text below ....
- }
- # (see text below about possible appending of .pmc
- # suffix to $filename)
- my $realfilename = "$prefix/$filename";
- next if ! -e $realfilename || -d _ || -b _;
- $INC{$filename} = $realfilename;
- my $result = do($realfilename);
- # but run in caller's namespace
-
- if (!defined $result) {
- $INC{$filename} = undef;
- croak $@ ? "address@hidden failed in require"
- : "Can't locate $filename: $!\n";
- }
- if (!$result) {
- delete $INC{$filename};
- croak "$filename did not return true value";
- }
- $! = 0;
- return $result;
- }
- croak "Can't locate $filename in address@hidden ...";
- }
-</pre>
-<p>Note that the file will not be included twice under the same specified
-name.
-</p>
-<p>The file must return true as the last statement to indicate
-successful execution of any initialization code, so it’s customary to
-end such a file with <code>1;</code> unless you’re sure it’ll
return true
-otherwise. But it’s better just to put the <code>1;</code>, in case you
add more
-statements.
-</p>
-<p>If EXPR is a bareword, the require assumes a "<samp>.pm</samp>"
extension and
-replaces "<samp>::</samp>" with "<samp>/</samp>" in the
filename for you,
-to make it easy to load standard modules. This form of loading of
-modules does not risk altering your namespace.
-</p>
-<p>In other words, if you try this:
-</p>
-<pre class="verbatim"> require Foo::Bar; # a splendid bareword
-</pre>
-<p>The require function will actually look for the
"<samp>Foo/Bar.pm</samp>" file in the
-directories specified in the <code>@INC</code> array.
-</p>
-<p>But if you try this:
-</p>
-<pre class="verbatim"> $class = 'Foo::Bar';
- require $class; # $class is not a bareword
- #or
- require "Foo::Bar"; # not a bareword because of the
""
-</pre>
-<p>The require function will look for the "<samp>Foo::Bar</samp>"
file in the @INC array and
-will complain about not finding "<samp>Foo::Bar</samp>" there. In
this case you can do:
-</p>
-<pre class="verbatim"> eval "require $class";
-</pre>
-<p>Now that you understand how <code>require</code> looks for files with a
-bareword argument, there is a little extra functionality going on behind
-the scenes. Before <code>require</code> looks for a
"<samp>.pm</samp>" extension, it will
-first look for a similar filename with a "<samp>.pmc</samp>"
extension. If this file
-is found, it will be loaded in place of any file ending in a
"<samp>.pm</samp>"
-extension.
-</p>
-<p>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.
-</p>
-<p>Subroutine references are the simplest case. When the inclusion system
-walks through @INC and encounters a subroutine, this subroutine gets
-called with two parameters, the first a reference to itself, and the
-second the name of the file to be included (e.g.,
"<samp>Foo/Bar.pm</samp>"). The
-subroutine should return either nothing or else a list of up to four
-values in the following order:
-</p>
-<ol>
-<li> A reference to a scalar, containing any initial source code to prepend to
-the file or generator output.
-
-</li><li> A filehandle, from which the file will be read.
-
-</li><li> 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 <code>$_</code> 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
<code>$_</code>.
-Again, return 1 for each valid line, and 0 after all lines have been
-returned.
-
-</li><li> Optional state for the subroutine. The state is passed in as
<code>$_[1]</code>. A
-reference to the subroutine itself is passed in as <code>$_[0]</code>.
-
-</li></ol>
-
-<p>If an empty list, <code>undef</code>, or nothing that matches the first 3
values above
-is returned, then <code>require</code> looks at the remaining elements of @INC.
-Note that this filehandle must be a real filehandle (strictly a typeglob
-or reference to a typeglob, whether blessed or unblessed); tied filehandles
-will be ignored and processing will stop there.
-</p>
-<p>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
-the array reference. This lets you indirectly pass arguments to
-the subroutine.
-</p>
-<p>In other words, you can write:
-</p>
-<pre class="verbatim"> push @INC, \&my_sub;
- sub my_sub {
- my ($coderef, $filename) = @_; # $coderef is \&my_sub
- ...
- }
-</pre>
-<p>or:
-</p>
-<pre class="verbatim"> push @INC, [ \&my_sub, $x, $y, ... ];
- sub my_sub {
- my ($arrayref, $filename) = @_;
- # Retrieve $x, $y, ...
- my @parameters = @$arrayref[1..$#$arrayref];
- ...
- }
-</pre>
-<p>If the hook is an object, it must provide an INC method that will be
-called as above, the first parameter being the object itself. (Note that
-you must fully qualify the sub’s name, as unqualified <code>INC</code>
is always forced
-into package <code>main</code>.) Here is a typical code layout:
-</p>
-<pre class="verbatim"> # In Foo.pm
- package Foo;
- sub new { ... }
- sub Foo::INC {
- my ($self, $filename) = @_;
- ...
- }
-
- # In the main program
- push @INC, Foo->new(...);
-</pre>
-<p>These hooks are also permitted to set the %INC entry
-corresponding to the files they have loaded. See <a
href="#perlvar-_0025INC">perlvar %INC</a>.
-</p>
-<p>For a yet-more-powerful import facility, see ‘use’ and <a
href="#perlmod-NAME">perlmod NAME</a>.
-</p>
-</dd>
-<dt>reset EXPR</dt>
-<dd><a name="perlfunc-reset-EXPR"></a>
-</dd>
-<dt>reset</dt>
-<dd><a name="perlfunc-reset"></a>
-<p>Generally used in a <code>continue</code> block at the end of a loop to
clear
-variables and reset <code>??</code> searches so that they work again. The
-expression is interpreted as a list of single characters (hyphens
-allowed for ranges). All variables and arrays beginning with one of
-those letters are reset to their pristine state. If the expression is
-omitted, one-match searches (<code>?pattern?</code>) are reset to match again.
-Only resets variables or searches in the current package. Always returns
-1. Examples:
-</p>
-<pre class="verbatim"> reset 'X'; # reset all X variables
- reset 'a-z'; # reset lower case variables
- reset; # just reset ?one-time? searches
-</pre>
-<p>Resetting <code>"A-Z"</code> is not recommended because
you’ll wipe out your
-<code>@ARGV</code> and <code>@INC</code> arrays and your <code>%ENV</code>
hash. Resets only package
-variables; lexical variables are unaffected, but they clean themselves
-up on scope exit anyway, so you’ll probably want to use them instead.
-See ‘my’.
-</p>
-</dd>
-<dt>return EXPR</dt>
-<dd><a name="perlfunc-return-EXPR"></a>
-</dd>
-<dt>return</dt>
-<dd><a name="perlfunc-return"></a>
-<p>Returns from a subroutine, <code>eval</code>, or <code>do FILE</code> with
the value
-given in EXPR. Evaluation of EXPR may be in list, scalar, or void
-context, depending on how the return value will be used, and the context
-may vary from one execution to the next (see <a
href="#perlfunc-wantarray">wantarray</a>). If no EXPR
-is given, returns an empty list in list context, the undefined value in
-scalar context, and (of course) nothing at all in void context.
-</p>
-<p>(In the absence of an explicit <code>return</code>, a subroutine, eval,
-or do FILE automatically returns the value of the last expression
-evaluated.)
-</p>
-<p>Unlike most named operators, this is also exempt from the
-looks-like-a-function rule, so <code>return
("foo")."bar"</code> will
-cause "bar" to be part of the argument to <code>return</code>.
-</p>
-</dd>
-<dt>reverse LIST</dt>
-<dd><a name="perlfunc-reverse-LIST"></a>
-<p>In list context, returns a list value consisting of the elements
-of LIST in the opposite order. In scalar context, concatenates the
-elements of LIST and returns a string value with all characters
-in the opposite order.
-</p>
-<pre class="verbatim"> print join(", ", reverse
"world", "Hello"); # Hello, world
-
- print scalar reverse "dlrow ,", "olleH"; # Hello,
world
-</pre>
-<p>Used without arguments in scalar context, reverse() reverses
<code>$_</code>.
-</p>
-<pre class="verbatim"> $_ = "dlrow ,olleH";
- print reverse; # No output, list context
- print scalar reverse; # Hello, world
-</pre>
-<p>Note that reversing an array to itself (as in <code>@a = reverse @a</code>)
will
-preserve non-existent elements whenever possible; i.e., for non-magical
-arrays or for tied arrays with <code>EXISTS</code> and <code>DELETE</code>
methods.
-</p>
-<p>This operator is also handy for inverting a hash, although there are some
-caveats. If a value is duplicated in the original hash, only one of those
-can be represented as a key in the inverted hash. Also, this has to
-unwind one hash and build a whole new one, which may take some time
-on a large hash, such as from a DBM file.
-</p>
-<pre class="verbatim"> %by_name = reverse %by_address; # Invert the hash
-</pre>
-</dd>
-<dt>rewinddir DIRHANDLE</dt>
-<dd><a name="perlfunc-rewinddir-DIRHANDLE"></a>
-<p>Sets the current position to the beginning of the directory for the
-<code>readdir</code> routine on DIRHANDLE.
-</p>
-<p>Portability issues: <a href="#perlport-rewinddir">perlport rewinddir</a>.
-</p>
-</dd>
-<dt>rindex STR,SUBSTR,POSITION</dt>
-<dd><a name="perlfunc-rindex-STR_002cSUBSTR_002cPOSITION"></a>
-</dd>
-<dt>rindex STR,SUBSTR</dt>
-<dd><a name="perlfunc-rindex-STR_002cSUBSTR"></a>
-<p>Works just like index() except that it returns the position of the
<em>last</em>
-occurrence of SUBSTR in STR. If POSITION is specified, returns the
-last occurrence beginning at or before that position.
-</p>
-</dd>
-<dt>rmdir FILENAME</dt>
-<dd><a name="perlfunc-rmdir-FILENAME"></a>
-</dd>
-<dt>rmdir</dt>
-<dd><a name="perlfunc-rmdir"></a>
-<p>Deletes the directory specified by FILENAME if that directory is
-empty. If it succeeds it returns true; otherwise it returns false and
-sets <code>$!</code> (errno). If FILENAME is omitted, uses <code>$_</code>.
-</p>
-<p>To remove a directory tree recursively (<code>rm -rf</code> on Unix) look at
-the <code>rmtree</code> function of the <a
href="File-Path.html#Top">(File-Path)</a> module.
-</p>
-</dd>
-<dt>s///</dt>
-<dd><a name="perlfunc-s_002f_002f_002f"></a>
-<p>The substitution operator. See <a
href="#perlop-Regexp-Quote_002dLike-Operators">perlop Regexp Quote-Like
Operators</a>.
-</p>
-</dd>
-<dt>say FILEHANDLE LIST</dt>
-<dd><a name="perlfunc-say-FILEHANDLE-LIST"></a>
-</dd>
-<dt>say FILEHANDLE</dt>
-<dd><a name="perlfunc-say-FILEHANDLE"></a>
-</dd>
-<dt>say LIST</dt>
-<dd><a name="perlfunc-say-LIST"></a>
-</dd>
-<dt>say</dt>
-<dd><a name="perlfunc-say"></a>
-<p>Just like <code>print</code>, but implicitly appends a newline. <code>say
LIST</code> is
-simply an abbreviation for <code>{ local $\ = "\n"; print LIST
}</code>. To use
-FILEHANDLE without a LIST to print the contents of <code>$_</code> to it, you
must
-use a real filehandle like <code>FH</code>, not an indirect one like
<code>$fh</code>.
-</p>
-<p>This keyword is available only when the <code>"say"</code> feature
-is enabled, or when prefixed with <code>CORE::</code>; see
-<a href="feature.html#Top">(feature)</a>. Alternately, include a <code>use
v5.10</code> or later to the current
-scope.
-</p>
-</dd>
-<dt>scalar EXPR</dt>
-<dd><a name="perlfunc-scalar-EXPR"></a>
-<p>Forces EXPR to be interpreted in scalar context and returns the value
-of EXPR.
-</p>
-<pre class="verbatim"> @counts = ( scalar @a, scalar @b, scalar @c );
-</pre>
-<p>There is no equivalent operator to force an expression to
-be interpolated in list context because in practice, this is never
-needed. If you really wanted to do so, however, you could use
-the construction <code>@{[ (some expression) ]}</code>, but usually a simple
-<code>(some expression)</code> suffices.
-</p>
-<p>Because <code>scalar</code> 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.
-</p>
-<p>The following single statement:
-</p>
-<pre class="verbatim"> print uc(scalar(&foo,$bar)),$baz;
-</pre>
-<p>is the moral equivalent of these two:
-</p>
-<pre class="verbatim"> &foo;
- print(uc($bar),$baz);
-</pre>
-<p>See <a href="#perlop-NAME">perlop NAME</a> for more details on unary
operators and the comma operator.
-</p>
-</dd>
-<dt>seek FILEHANDLE,POSITION,WHENCE</dt>
-<dd><a name="perlfunc-seek-FILEHANDLE_002cPOSITION_002cWHENCE"></a>
-<p>Sets FILEHANDLE’s position, just like the <code>fseek</code> call of
<code>stdio</code>.
-FILEHANDLE may be an expression whose value gives the name of the
-filehandle. The values for WHENCE are <code>0</code> to set the new position
-<em>in bytes</em> to POSITION; <code>1</code> to set it to the current
position plus
-POSITION; and <code>2</code> to set it to EOF plus POSITION, typically
-negative. For WHENCE you may use the constants <code>SEEK_SET</code>,
-<code>SEEK_CUR</code>, and <code>SEEK_END</code> (start of the file, current
position, end
-of the file) from the <a href="Fcntl.html#Top">(Fcntl)</a> module. Returns
<code>1</code> on success, false
-otherwise.
-</p>
-<p>Note the <em>in bytes</em>: even if the filehandle has been set to
-operate on characters (for example by using the <code>:encoding(utf8)</code>
open
-layer), tell() will return byte offsets, not character offsets
-(because implementing that would render seek() and tell() rather slow).
-</p>
-<p>If you want to position the file for <code>sysread</code> or
<code>syswrite</code>, don’t use
-<code>seek</code>, because buffering makes its effect on the file’s
read-write position
-unpredictable and non-portable. Use <code>sysseek</code> instead.
-</p>
-<p>Due to the rules and rigors of ANSI C, on some systems you have to do a
-seek whenever you switch between reading and writing. Amongst other
-things, this may have the effect of calling stdio’s clearerr(3).
-A WHENCE of <code>1</code> (<code>SEEK_CUR</code>) is useful for not moving
the file position:
-</p>
-<pre class="verbatim"> seek(TEST,0,1);
-</pre>
-<p>This is also useful for applications emulating <code>tail -f</code>. Once
you hit
-EOF on your read and then sleep for a while, you (probably) have to stick in a
-dummy seek() to reset things. The <code>seek</code> doesn’t change the
position,
-but it <em>does</em> clear the end-of-file condition on the handle, so that the
-next <code><FILE></code> makes Perl try again to read something. (We
hope.)
-</p>
-<p>If that doesn’t work (some I/O implementations are particularly
-cantankerous), you might need something like this:
-</p>
-<pre class="verbatim"> for (;;) {
- for ($curpos = tell(FILE); $_ = <FILE>;
- $curpos = tell(FILE)) {
- # search for some stuff and put it into files
- }
- sleep($for_a_while);
- seek(FILE, $curpos, 0);
- }
-</pre>
-</dd>
-<dt>seekdir DIRHANDLE,POS</dt>
-<dd><a name="perlfunc-seekdir-DIRHANDLE_002cPOS"></a>
-<p>Sets the current position for the <code>readdir</code> routine on
DIRHANDLE. POS
-must be a value returned by <code>telldir</code>. <code>seekdir</code> also
has the same caveats
-about possible directory compaction as the corresponding system library
-routine.
-</p>
-</dd>
-<dt>select FILEHANDLE</dt>
-<dd><a name="perlfunc-select-FILEHANDLE"></a>
-</dd>
-<dt>select</dt>
-<dd><a name="perlfunc-select"></a>
-<p>Returns the currently selected filehandle. If FILEHANDLE is supplied,
-sets the new current default filehandle for output. This has two
-effects: first, a <code>write</code> or a <code>print</code> without a
filehandle
-default to this FILEHANDLE. Second, references to variables related to
-output will refer to this output channel.
-</p>
-<p>For example, to set the top-of-form format for more than one
-output channel, you might do the following:
-</p>
-<pre class="verbatim"> select(REPORT1);
- $^ = 'report1_top';
- select(REPORT2);
- $^ = 'report2_top';
-</pre>
-<p>FILEHANDLE may be an expression whose value gives the name of the
-actual filehandle. Thus:
-</p>
-<pre class="verbatim"> $oldfh = select(STDERR); $| = 1; select($oldfh);
-</pre>
-<p>Some programmers may prefer to think of filehandles as objects with
-methods, preferring to write the last example as:
-</p>
-<pre class="verbatim"> use IO::Handle;
- STDERR->autoflush(1);
-</pre>
-<p>Portability issues: <a href="#perlport-select">perlport select</a>.
-</p>
-</dd>
-<dt>select RBITS,WBITS,EBITS,TIMEOUT</dt>
-<dd><a name="perlfunc-select-RBITS_002cWBITS_002cEBITS_002cTIMEOUT"></a>
-<p>This calls the select(2) syscall with the bit masks specified, which
-can be constructed using <code>fileno</code> and <code>vec</code>, along these
lines:
-</p>
-<pre class="verbatim"> $rin = $win = $ein = '';
- vec($rin, fileno(STDIN), 1) = 1;
- vec($win, fileno(STDOUT), 1) = 1;
- $ein = $rin | $win;
-</pre>
-<p>If you want to select on many filehandles, you may wish to write a
-subroutine like this:
-</p>
-<pre class="verbatim"> sub fhbits {
- my @fhlist = @_;
- my $bits = "";
- for my $fh (@fhlist) {
- vec($bits, fileno($fh), 1) = 1;
- }
- return $bits;
- }
- $rin = fhbits(*STDIN, *TTY, *MYSOCK);
-</pre>
-<p>The usual idiom is:
-</p>
-<pre class="verbatim"> ($nfound,$timeleft) =
- select($rout=$rin, $wout=$win, $eout=$ein, $timeout);
-</pre>
-<p>or to block until something becomes ready just do this
-</p>
-<pre class="verbatim"> $nfound = select($rout=$rin, $wout=$win, $eout=$ein,
undef);
-</pre>
-<p>Most systems do not bother to return anything useful in $timeleft, so
-calling select() in scalar context just returns $nfound.
-</p>
-<p>Any of the bit masks can also be undef. The timeout, if specified, is
-in seconds, which may be fractional. Note: not all implementations are
-capable of returning the $timeleft. If not, they always return
-$timeleft equal to the supplied $timeout.
-</p>
-<p>You can effect a sleep of 250 milliseconds this way:
-</p>
-<pre class="verbatim"> select(undef, undef, undef, 0.25);
-</pre>
-<p>Note that whether <code>select</code> gets restarted after signals (say,
SIGALRM)
-is implementation-dependent. See also <a href="#perlport-NAME">perlport
NAME</a> for notes on the
-portability of <code>select</code>.
-</p>
-<p>On error, <code>select</code> behaves just like select(2): it returns
--1 and sets <code>$!</code>.
-</p>
-<p>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
<code>read</code>
-would block. This can be avoided if you always use O_NONBLOCK on the
-socket. See select(2) and fcntl(2) for further details.
-</p>
-<p>The standard <code>IO::Select</code> module provides a user-friendlier
interface
-to <code>select</code>, mostly because it does all the bit-mask work for you.
-</p>
-<p><strong>WARNING</strong>: One should not attempt to mix buffered I/O (like
<code>read</code>
-or <FH>) with <code>select</code>, except as permitted by POSIX, and even
-then only on POSIX systems. You have to use <code>sysread</code> instead.
-</p>
-<p>Portability issues: <a href="#perlport-select">perlport select</a>.
-</p>
-</dd>
-<dt>semctl ID,SEMNUM,CMD,ARG</dt>
-<dd><a name="perlfunc-semctl-ID_002cSEMNUM_002cCMD_002cARG"></a>
-<p>Calls the System V IPC function semctl(2). You’ll probably have to
say
-</p>
-<pre class="verbatim"> use IPC::SysV;
-</pre>
-<p>first to get the correct constant definitions. If CMD is IPC_STAT or
-GETALL, then ARG must be a variable that will hold the returned
-semid_ds structure or semaphore value array. Returns like <code>ioctl</code>:
-the undefined value for error, "<code>0 but true</code>" for zero,
or the actual
-return value otherwise. The ARG must consist of a vector of native
-short integers, which may be created with
<code>pack("s!",(0)x$nsem)</code>.
-See also <a href="#perlipc-SysV-IPC">perlipc SysV IPC</a>,
<code>IPC::SysV</code>, <code>IPC::Semaphore</code>
-documentation.
-</p>
-<p>Portability issues: <a href="#perlport-semctl">perlport semctl</a>.
-</p>
-</dd>
-<dt>semget KEY,NSEMS,FLAGS</dt>
-<dd><a name="perlfunc-semget-KEY_002cNSEMS_002cFLAGS"></a>
-<p>Calls the System V IPC function semget(2). Returns the semaphore id, or
-the undefined value on error. See also
-<a href="#perlipc-SysV-IPC">perlipc SysV IPC</a>, <code>IPC::SysV</code>,
<code>IPC::SysV::Semaphore</code>
-documentation.
-</p>
-<p>Portability issues: <a href="#perlport-semget">perlport semget</a>.
-</p>
-</dd>
-<dt>semop KEY,OPSTRING</dt>
-<dd><a name="perlfunc-semop-KEY_002cOPSTRING"></a>
-<p>Calls the System V IPC function semop(2) for semaphore operations
-such as signalling and waiting. OPSTRING must be a packed array of
-semop structures. Each semop structure can be generated with
-<code>pack("s!3", $semnum, $semop, $semflag)</code>. The length of
OPSTRING
-implies the number of semaphore operations. Returns true if
-successful, false on error. As an example, the
-following code waits on semaphore $semnum of semaphore id $semid:
-</p>
-<pre class="verbatim"> $semop = pack("s!3", $semnum, -1, 0);
- die "Semaphore trouble: $!\n" unless semop($semid, $semop);
-</pre>
-<p>To signal the semaphore, replace <code>-1</code> with <code>1</code>. See
also
-<a href="#perlipc-SysV-IPC">perlipc SysV IPC</a>, <code>IPC::SysV</code>, and
<code>IPC::SysV::Semaphore</code>
-documentation.
-</p>
-<p>Portability issues: <a href="#perlport-semop">perlport semop</a>.
-</p>
-</dd>
-<dt>send SOCKET,MSG,FLAGS,TO</dt>
-<dd><a name="perlfunc-send-SOCKET_002cMSG_002cFLAGS_002cTO"></a>
-</dd>
-<dt>send SOCKET,MSG,FLAGS</dt>
-<dd><a name="perlfunc-send-SOCKET_002cMSG_002cFLAGS"></a>
-<p>Sends a message on a socket. Attempts to send the scalar MSG to the SOCKET
-filehandle. Takes the same flags as the system call of the same name. On
-unconnected sockets, you must specify a destination to <em>send to</em>, in
which
-case it does a sendto(2) syscall. Returns the number of characters sent,
-or the undefined value on error. The sendmsg(2) syscall is currently
-unimplemented. See <a href="#perlipc-UDP_003a-Message-Passing">perlipc UDP:
Message Passing</a> for examples.
-</p>
-<p>Note the <em>characters</em>: depending on the status of the socket, either
-(8-bit) bytes or characters are sent. By default all sockets operate
-on bytes, but for example if the socket has been changed using
-binmode() to operate with the <code>:encoding(utf8)</code> I/O layer (see
-‘open’, or the <code>open</code> pragma, <a
href="open.html#Top">(open)</a>), the I/O will operate on UTF-8
-encoded Unicode characters, not bytes. Similarly for the
<code>:encoding</code>
-pragma: in that case pretty much any characters can be sent.
-</p>
-</dd>
-<dt>setpgrp PID,PGRP</dt>
-<dd><a name="perlfunc-setpgrp-PID_002cPGRP"></a>
-<p>Sets the current process group for the specified PID, <code>0</code> for
the current
-process. Raises an exception when used on a machine that doesn’t
-implement POSIX setpgid(2) or BSD setpgrp(2). If the arguments are omitted,
-it defaults to <code>0,0</code>. Note that the BSD 4.2 version of
<code>setpgrp</code> does not
-accept any arguments, so only <code>setpgrp(0,0)</code> is portable. See also
-<code>POSIX::setsid()</code>.
-</p>
-<p>Portability issues: <a href="#perlport-setpgrp">perlport setpgrp</a>.
-</p>
-</dd>
-<dt>setpriority WHICH,WHO,PRIORITY</dt>
-<dd><a name="perlfunc-setpriority-WHICH_002cWHO_002cPRIORITY"></a>
-<p>Sets the current priority for a process, a process group, or a user.
-(See setpriority(2).) Raises an exception when used on a machine
-that doesn’t implement setpriority(2).
-</p>
-<p>Portability issues: <a href="#perlport-setpriority">perlport
setpriority</a>.
-</p>
-</dd>
-<dt>setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL</dt>
-<dd><a name="perlfunc-setsockopt-SOCKET_002cLEVEL_002cOPTNAME_002cOPTVAL"></a>
-<p>Sets the socket option requested. Returns <code>undef</code> on error.
-Use integer constants provided by the <code>Socket</code> 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).
-</p>
-<p>An example disabling Nagle’s algorithm on a socket:
-</p>
-<pre class="verbatim"> use Socket qw(IPPROTO_TCP TCP_NODELAY);
- setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
-</pre>
-<p>Portability issues: <a href="#perlport-setsockopt">perlport setsockopt</a>.
-</p>
-</dd>
-<dt>shift ARRAY</dt>
-<dd><a name="perlfunc-shift-ARRAY"></a>
-</dd>
-<dt>shift EXPR</dt>
-<dd><a name="perlfunc-shift-EXPR"></a>
-</dd>
-<dt>shift</dt>
-<dd><a name="perlfunc-shift"></a>
-<p>Shifts the first value of the array off and returns it, shortening the
-array by 1 and moving everything down. If there are no elements in the
-array, returns the undefined value. If ARRAY is omitted, shifts the
-<code>@_</code> array within the lexical scope of subroutines and formats, and
the
-<code>@ARGV</code> array outside a subroutine and also within the lexical
scopes
-established by the <code>eval STRING</code>, <code>BEGIN {}</code>, <code>INIT
{}</code>, <code>CHECK {}</code>,
-<code>UNITCHECK {}</code>, and <code>END {}</code> constructs.
-</p>
-<p>Starting with Perl 5.14, <code>shift</code> can take a scalar EXPR, which
must hold a
-reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of <code>shift</code> is considered highly
experimental.
-The exact behaviour may change in a future version of Perl.
-</p>
-<p>To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work <em>only</em> on Perls
of
-a recent vintage:
-</p>
-<pre class="verbatim"> use 5.014; # so push/pop/etc work on scalars
(experimental)
-</pre>
-<p>See also <code>unshift</code>, <code>push</code>, and <code>pop</code>.
<code>shift</code> and <code>unshift</code> do the
-same thing to the left end of an array that <code>pop</code> and
<code>push</code> do to the
-right end.
-</p>
-</dd>
-<dt>shmctl ID,CMD,ARG</dt>
-<dd><a name="perlfunc-shmctl-ID_002cCMD_002cARG"></a>
-<p>Calls the System V IPC function shmctl. You’ll probably have to say
-</p>
-<pre class="verbatim"> use IPC::SysV;
-</pre>
-<p>first to get the correct constant definitions. If CMD is
<code>IPC_STAT</code>,
-then ARG must be a variable that will hold the returned <code>shmid_ds</code>
-structure. Returns like ioctl: <code>undef</code> for error;
"<code>0</code> but
-true" for zero; and the actual return value otherwise.
-See also <a href="#perlipc-SysV-IPC">perlipc SysV IPC</a> and
<code>IPC::SysV</code> documentation.
-</p>
-<p>Portability issues: <a href="#perlport-shmctl">perlport shmctl</a>.
-</p>
-</dd>
-<dt>shmget KEY,SIZE,FLAGS</dt>
-<dd><a name="perlfunc-shmget-KEY_002cSIZE_002cFLAGS"></a>
-<p>Calls the System V IPC function shmget. Returns the shared memory
-segment id, or <code>undef</code> on error.
-See also <a href="#perlipc-SysV-IPC">perlipc SysV IPC</a> and
<code>IPC::SysV</code> documentation.
-</p>
-<p>Portability issues: <a href="#perlport-shmget">perlport shmget</a>.
-</p>
-</dd>
-<dt>shmread ID,VAR,POS,SIZE</dt>
-<dd><a name="perlfunc-shmread-ID_002cVAR_002cPOS_002cSIZE"></a>
-</dd>
-<dt>shmwrite ID,STRING,POS,SIZE</dt>
-<dd><a name="perlfunc-shmwrite-ID_002cSTRING_002cPOS_002cSIZE"></a>
-<p>Reads or writes the System V shared memory segment ID starting at
-position POS for size SIZE by attaching to it, copying in/out, and
-detaching from it. When reading, VAR must be a variable that will
-hold the data read. When writing, if STRING is too long, only SIZE
-bytes are used; if STRING is too short, nulls are written to fill out
-SIZE bytes. Return true if successful, false on error.
-shmread() taints the variable. See also <a href="#perlipc-SysV-IPC">perlipc
SysV IPC</a>,
-<code>IPC::SysV</code>, and the <code>IPC::Shareable</code> module from CPAN.
-</p>
-<p>Portability issues: <a href="#perlport-shmread">perlport shmread</a> and <a
href="#perlport-shmwrite">perlport shmwrite</a>.
-</p>
-</dd>
-<dt>shutdown SOCKET,HOW</dt>
-<dd><a name="perlfunc-shutdown-SOCKET_002cHOW"></a>
-<p>Shuts down a socket connection in the manner indicated by HOW, which
-has the same interpretation as in the syscall of the same name.
-</p>
-<pre class="verbatim"> shutdown(SOCKET, 0); # I/we have stopped reading
data
- shutdown(SOCKET, 1); # I/we have stopped writing data
- shutdown(SOCKET, 2); # I/we have stopped using this socket
-</pre>
-<p>This is useful with sockets when you want to tell the other
-side you’re done writing but not done reading, or vice versa.
-It’s also a more insistent form of close because it also
-disables the file descriptor in any forked copies in other
-processes.
-</p>
-<p>Returns <code>1</code> for success; on error, returns <code>undef</code> if
-the first argument is not a valid filehandle, or returns <code>0</code> and
sets
-<code>$!</code> for any other failure.
-</p>
-</dd>
-<dt>sin EXPR</dt>
-<dd><a name="perlfunc-sin-EXPR"></a>
-</dd>
-<dt>sin</dt>
-<dd><a name="perlfunc-sin"></a>
-<p>Returns the sine of EXPR (expressed in radians). If EXPR is omitted,
-returns sine of <code>$_</code>.
-</p>
-<p>For the inverse sine operation, you may use the
<code>Math::Trig::asin</code>
-function, or use this relation:
-</p>
-<pre class="verbatim"> sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
-</pre>
-</dd>
-<dt>sleep EXPR</dt>
-<dd><a name="perlfunc-sleep-EXPR"></a>
-</dd>
-<dt>sleep</dt>
-<dd><a name="perlfunc-sleep"></a>
-<p>Causes the script to sleep for (integer) EXPR seconds, or forever if no
-argument is given. Returns the integer number of seconds actually slept.
-</p>
-<p>May be interrupted if the process receives a signal such as
<code>SIGALRM</code>.
-</p>
-<pre class="verbatim"> eval {
- local $SIG{ALARM} = sub { die "Alarm!\n" };
- sleep;
- };
- die $@ unless $@ eq "Alarm!\n";
-</pre>
-<p>You probably cannot mix <code>alarm</code> and <code>sleep</code> calls,
because <code>sleep</code>
-is often implemented using <code>alarm</code>.
-</p>
-<p>On some older systems, it may sleep up to a full second less than what
-you requested, depending on how it counts seconds. Most modern systems
-always sleep the full amount. They may appear to sleep longer than that,
-however, because your process might not be scheduled right away in a
-busy multitasking system.
-</p>
-<p>For delays of finer granularity than one second, the Time::HiRes module
-(from CPAN, and starting from Perl 5.8 part of the standard
-distribution) provides usleep(). You may also use Perl’s four-argument
-version of select() leaving the first three arguments undefined, or you
-might be able to use the <code>syscall</code> interface to access setitimer(2)
if
-your system supports it. See <a href="perlfaq8.html#Top">(perlfaq8)</a> for
details.
-</p>
-<p>See also the POSIX module’s <code>pause</code> function.
-</p>
-</dd>
-<dt>socket SOCKET,DOMAIN,TYPE,PROTOCOL</dt>
-<dd><a name="perlfunc-socket-SOCKET_002cDOMAIN_002cTYPE_002cPROTOCOL"></a>
-<p>Opens a socket of the specified kind and attaches it to filehandle
-SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for
-the syscall of the same name. You should <code>use Socket</code> first
-to get the proper definitions imported. See the examples in
-<a href="#perlipc-Sockets_003a-Client_002fServer-Communication">perlipc
Sockets: Client/Server Communication</a>.
-</p>
-<p>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 <a href="#perlvar-_0024_005eF">perlvar $^F</a>.
-</p>
-</dd>
-<dt>socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL</dt>
-<dd><a
name="perlfunc-socketpair-SOCKET1_002cSOCKET2_002cDOMAIN_002cTYPE_002cPROTOCOL"></a>
-<p>Creates an unnamed pair of sockets in the specified domain, of the
-specified type. DOMAIN, TYPE, and PROTOCOL are specified the same as
-for the syscall of the same name. If unimplemented, raises an exception.
-Returns true if successful.
-</p>
-<p>On systems that support a close-on-exec flag on files, the flag will
-be set for the newly opened file descriptors, as determined by the value
-of $^F. See <a href="#perlvar-_0024_005eF">perlvar $^F</a>.
-</p>
-<p>Some systems defined <code>pipe</code> in terms of <code>socketpair</code>,
in which a call
-to <code>pipe(Rdr, Wtr)</code> is essentially:
-</p>
-<pre class="verbatim"> use Socket;
- socketpair(Rdr, Wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC);
- shutdown(Rdr, 1); # no more writing for reader
- shutdown(Wtr, 0); # no more reading for writer
-</pre>
-<p>See <a href="#perlipc-NAME">perlipc NAME</a> for an example of socketpair
use. Perl 5.8 and later will
-emulate socketpair using IP sockets to localhost if your system implements
-sockets but not socketpair.
-</p>
-<p>Portability issues: <a href="#perlport-socketpair">perlport socketpair</a>.
-</p>
-</dd>
-<dt>sort SUBNAME LIST</dt>
-<dd><a name="perlfunc-sort-SUBNAME-LIST"></a>
-</dd>
-<dt>sort BLOCK LIST</dt>
-<dd><a name="perlfunc-sort-BLOCK-LIST"></a>
-</dd>
-<dt>sort LIST</dt>
-<dd><a name="perlfunc-sort-LIST"></a>
-<p>In list context, this sorts the LIST and returns the sorted list value.
-In scalar context, the behaviour of <code>sort()</code> is undefined.
-</p>
-<p>If SUBNAME or BLOCK is omitted, <code>sort</code>s in standard string
comparison
-order. If SUBNAME is specified, it gives the name of a subroutine
-that returns an integer less than, equal to, or greater than <code>0</code>,
-depending on how the elements of the list are to be ordered. (The
-<code><=></code> and <code>cmp</code> operators are extremely useful in
such routines.)
-SUBNAME may be a scalar variable name (unsubscripted), in which case
-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.
-</p>
-<p>If the subroutine’s prototype is <code>($$)</code>, the elements to
be compared are
-passed by reference in <code>@_</code>, 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.
-</p>
-<p>If the subroutine is an XSUB, the elements to be compared are pushed on to
-the stack, the way arguments are usually passed to XSUBs. $a and $b are
-not set.
-</p>
-<p>The values to be compared are always passed by reference and should not
-be modified.
-</p>
-<p>You also cannot exit out of the sort block or subroutine using any of the
-loop control operators described in <a href="#perlsyn-NAME">perlsyn NAME</a>
or with <code>goto</code>.
-</p>
-<p>When <code>use locale</code> (but not <code>use locale
'not_characters'</code>) is in
-effect, <code>sort LIST</code> sorts LIST according to the
-current collation locale. See <a href="#perllocale-NAME">perllocale NAME</a>.
-</p>
-<p>sort() returns aliases into the original list, much as a for loop’s
index
-variable aliases the list elements. That is, modifying an element of a
-list returned by sort() (for example, in a <code>foreach</code>,
<code>map</code> or <code>grep</code>)
-actually modifies the element in the original list. This is usually
-something to be avoided when writing clear code.
-</p>
-<p>Perl 5.6 and earlier used a quicksort algorithm to implement sort.
-That algorithm was not stable, so <em>could</em> go quadratic. (A
<em>stable</em> 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), <em>quadratic</em> behavior, for some
-inputs.) In 5.7, the quicksort implementation was replaced with
-a stable mergesort algorithm whose worst-case behavior is O(NlogN).
-But benchmarks indicated that for some inputs, on some platforms,
-the original quicksort was faster. 5.8 has a sort pragma for
-limited control of the sort. Its rather blunt control of the
-underlying algorithm may not persist into future Perls, but the
-ability to characterize the input or output in implementation
-independent ways quite probably will. See <a href="sort.html#Top">(sort)the
sort pragma</a>.
-</p>
-<p>Examples:
-</p>
-<pre class="verbatim"> # sort lexically
- @articles = sort @files;
-
- # same thing, but with explicit sort routine
- @articles = sort {$a cmp $b} @files;
-
- # now case-insensitively
- @articles = sort {fc($a) cmp fc($b)} @files;
-
- # same thing in reversed order
- @articles = sort {$b cmp $a} @files;
-
- # sort numerically ascending
- @articles = sort {$a <=> $b} @files;
-
- # sort numerically descending
- @articles = sort {$b <=> $a} @files;
-
- # this sorts the %age hash by value instead of key
- # using an in-line function
- @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
-
- # sort using explicit subroutine name
- sub byage {
- $age{$a} <=> $age{$b}; # presuming numeric
- }
- @sortedclass = sort byage @class;
-
- sub backwards { $b cmp $a }
- @harry = qw(dog cat x Cain Abel);
- @george = qw(gone chased yz Punished Axed);
- print sort @harry;
- # prints AbelCaincatdogx
- print sort backwards @harry;
- # prints xdogcatCainAbel
- print sort @george, 'to', @harry;
- # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
-
- # inefficiently sort by descending numeric compare using
- # the first integer after the first = sign, or the
- # whole record case-insensitively otherwise
-
- my @new = sort {
- ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
- ||
- fc($a) cmp fc($b)
- } @old;
-
- # same thing, but much more efficiently;
- # we'll build auxiliary indices instead
- # for speed
- my (@nums, @caps);
- for (@old) {
- push @nums, ( /=(\d+)/ ? $1 : undef );
- push @caps, fc($_);
- }
-
- my @new = @old[ sort {
- $nums[$b] <=> $nums[$a]
- ||
- $caps[$a] cmp $caps[$b]
- } 0..$#old
- ];
-
- # same thing, but without any temps
- @new = map { $_->[0] }
- sort { $b->[1] <=> $a->[1]
- ||
- $a->[2] cmp $b->[2]
- } map { [$_, /=(\d+)/, fc($_)] } @old;
-
- # using a prototype allows you to use any comparison subroutine
- # as a sort subroutine (including other package's subroutines)
- package other;
- sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are
- # not set here
- package main;
- @new = sort other::backwards @old;
-
- # guarantee stability, regardless of algorithm
- use sort 'stable';
- @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
-
- # force use of mergesort (not portable outside Perl 5.8)
- use sort '_mergesort'; # note discouraging _
- @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
-</pre>
-<p>Warning: syntactical care is required when sorting the list returned from
-a function. If you want to sort the list returned by the function call
-<code>find_records(@key)</code>, you can use:
-</p>
-<pre class="verbatim"> @contact = sort { $a cmp $b } find_records @key;
- @contact = sort +find_records(@key);
- @contact = sort &find_records(@key);
- @contact = sort(find_records(@key));
-</pre>
-<p>If instead you want to sort the array @key with the comparison routine
-<code>find_records()</code> then you can use:
-</p>
-<pre class="verbatim"> @contact = sort { find_records() } @key;
- @contact = sort find_records(@key);
- @contact = sort(find_records @key);
- @contact = sort(find_records (@key));
-</pre>
-<p>If you’re using strict, you <em>must not</em> declare $a
-and $b as lexicals. They are package globals. That means
-that if you’re in the <code>main</code> package and type
-</p>
-<pre class="verbatim"> @articles = sort {$b <=> $a} @files;
-</pre>
-<p>then <code>$a</code> and <code>$b</code> are <code>$main::a</code> and
<code>$main::b</code> (or <code>$::a</code> and <code>$::b</code>),
-but if you’re in the <code>FooPack</code> package, it’s the same
as typing
-</p>
-<pre class="verbatim"> @articles = sort {$FooPack::b <=> $FooPack::a}
@files;
-</pre>
-<p>The comparison function is required to behave. If it returns
-inconsistent results (sometimes saying <code>$x[1]</code> is less than
<code>$x[2]</code> and
-sometimes saying the opposite, for example) the results are not
-well-defined.
-</p>
-<p>Because <code><=></code> returns <code>undef</code> when either
operand is <code>NaN</code>
-(not-a-number), be careful when sorting with a
-comparison function like <code>$a <=> $b</code> any lists that might
contain a
-<code>NaN</code>. The following example takes advantage that <code>NaN !=
NaN</code> to
-eliminate any <code>NaN</code>s from the input list.
-</p>
-<pre class="verbatim"> @result = sort { $a <=> $b } grep { $_ == $_ }
@input;
-</pre>
-</dd>
-<dt>splice ARRAY,OFFSET,LENGTH,LIST</dt>
-<dd><a name="perlfunc-splice-ARRAY_002cOFFSET_002cLENGTH_002cLIST"></a>
-</dd>
-<dt>splice ARRAY,OFFSET,LENGTH</dt>
-<dd><a name="perlfunc-splice-ARRAY_002cOFFSET_002cLENGTH"></a>
-</dd>
-<dt>splice ARRAY,OFFSET</dt>
-<dd><a name="perlfunc-splice-ARRAY_002cOFFSET"></a>
-</dd>
-<dt>splice ARRAY</dt>
-<dd><a name="perlfunc-splice-ARRAY"></a>
-</dd>
-<dt>splice EXPR,OFFSET,LENGTH,LIST</dt>
-<dd><a name="perlfunc-splice-EXPR_002cOFFSET_002cLENGTH_002cLIST"></a>
-</dd>
-<dt>splice EXPR,OFFSET,LENGTH</dt>
-<dd><a name="perlfunc-splice-EXPR_002cOFFSET_002cLENGTH"></a>
-</dd>
-<dt>splice EXPR,OFFSET</dt>
-<dd><a name="perlfunc-splice-EXPR_002cOFFSET"></a>
-</dd>
-<dt>splice EXPR</dt>
-<dd><a name="perlfunc-splice-EXPR"></a>
-<p>Removes the elements designated by OFFSET and LENGTH from an array, and
-replaces them with the elements of LIST, if any. In list context,
-returns the elements removed from the array. In scalar context,
-returns the last element removed, or <code>undef</code> if no elements are
-removed. The array grows or shrinks as necessary.
-If OFFSET is negative then it starts that far from the end of the array.
-If LENGTH is omitted, removes everything from OFFSET onward.
-If LENGTH is negative, removes the elements from OFFSET onward
-except for -LENGTH elements at the end of the array.
-If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is
-past the end of the array and a LENGTH was provided, Perl issues a warning,
-and splices at the end of the array.
-</p>
-<p>The following equivalences hold (assuming <code>$#a >= $i</code> )
-</p>
-<pre class="verbatim"> push(@a,$x,$y) splice(@a,@a,0,$x,$y)
- pop(@a) splice(@a,-1)
- shift(@a) splice(@a,0,1)
- unshift(@a,$x,$y) splice(@a,0,0,$x,$y)
- $a[$i] = $y splice(@a,$i,1,$y)
-</pre>
-<p><code>splice</code> can be used, for example, to implement n-ary queue
processing:
-</p>
-<pre class="verbatim"> sub nary_print {
- my $n = shift;
- while (my @next_n = splice @_, 0, $n) {
- say join q{ -- }, @next_n;
- }
- }
-
- nary_print(3, qw(a b c d e f g h));
- # prints:
- # a -- b -- c
- # d -- e -- f
- # g -- h
-</pre>
-<p>Starting with Perl 5.14, <code>splice</code> can take scalar EXPR, which
must hold a
-reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of <code>splice</code> is considered highly
experimental.
-The exact behaviour may change in a future version of Perl.
-</p>
-<p>To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work <em>only</em> on Perls
of
-a recent vintage:
-</p>
-<pre class="verbatim"> use 5.014; # so push/pop/etc work on scalars
(experimental)
-</pre>
-</dd>
-<dt>split /PATTERN/,EXPR,LIMIT</dt>
-<dd><a name="perlfunc-split-_002fPATTERN_002f_002cEXPR_002cLIMIT"></a>
-</dd>
-<dt>split /PATTERN/,EXPR</dt>
-<dd><a name="perlfunc-split-_002fPATTERN_002f_002cEXPR"></a>
-</dd>
-<dt>split /PATTERN/</dt>
-<dd><a name="perlfunc-split-_002fPATTERN_002f"></a>
-</dd>
-<dt>split</dt>
-<dd><a name="perlfunc-split"></a>
-<p>Splits the string EXPR into a list of strings and returns the
-list in list context, or the size of the list in scalar context.
-</p>
-<p>If only PATTERN is given, EXPR defaults to <code>$_</code>.
-</p>
-<p>Anything in EXPR that matches PATTERN is taken to be a separator
-that separates the EXPR into substrings (called "<em>fields</em>")
that
-do <strong>not</strong> include the separator. Note that a separator may be
-longer than one character or even have no characters at all (the
-empty string, which is a zero-width match).
-</p>
-<p>The PATTERN need not be constant; an expression may be used
-to specify a pattern that varies at runtime.
-</p>
-<p>If PATTERN matches the empty string, the EXPR is split at the match
-position (between characters). As an example, the following:
-</p>
-<pre class="verbatim"> print join(':', split('b', 'abc')), "\n";
-</pre>
-<p>uses the ’b’ in ’abc’ as a separator to produce the
output ’a:c’.
-However, this:
-</p>
-<pre class="verbatim"> print join(':', split('', 'abc')), "\n";
-</pre>
-<p>uses empty string matches as separators to produce the output
-’a:b:c’; thus, the empty string may be used to split EXPR into a
-list of its component characters.
-</p>
-<p>As a special case for <code>split</code>, the empty pattern given in
-<a href="#perlop-m_002fPATTERN_002fmsixpodualngc">match operator</a> syntax
(<code>//</code>)
-specifically matches the empty string, which is contrary to its usual
-interpretation as the last successful match.
-</p>
-<p>If PATTERN is <code>/^/</code>, then it is treated as if it used the
-<a href="#perlreref-OPERATORS">multiline modifier</a> (<code>/^/m</code>),
since it
-isn’t much use otherwise.
-</p>
-<p>As another special case, <code>split</code> emulates the default behavior
of the
-command line tool <strong>awk</strong> when the PATTERN is either omitted or a
<em>literal
-string</em> composed of a single space character (such as
<code>' '</code><!-- /@w --> or
-<code>"\x20"</code><!-- /@w -->, but not e.g.
<code>/ /</code><!-- /@w -->). In this case, any leading
-whitespace in EXPR is removed before splitting occurs, and the PATTERN is
-instead treated as if it were <code>/\s+/</code>; in particular, this means
that
-<em>any</em> contiguous whitespace (not just a single space character) is used
as
-a separator. However, this special treatment can be avoided by specifying
-the pattern <code>/ /</code><!-- /@w --> instead of the string
<code>" "</code><!-- /@w -->, thereby allowing
-only a single space character to be a separator. In earlier Perls this
-special case was restricted to the use of a plain
<code>" "</code><!-- /@w --> as the
-pattern argument to split, in Perl 5.18.0 and later this special case is
-triggered by any expression which evaluates as the simple string
<code>" "</code><!-- /@w -->.
-</p>
-<p>If omitted, PATTERN defaults to a single space,
<code>" "</code><!-- /@w -->, triggering
-the previously described <em>awk</em> emulation.
-</p>
-<p>If LIMIT is specified and positive, it represents the maximum number
-of fields into which the EXPR may be split; in other words, LIMIT is
-one greater than the maximum number of times EXPR may be split. Thus,
-the LIMIT value <code>1</code> means that EXPR may be split a maximum of zero
-times, producing a maximum of one field (namely, the entire value of
-EXPR). For instance:
-</p>
-<pre class="verbatim"> print join(':', split(//, 'abc', 1)), "\n";
-</pre>
-<p>produces the output ’abc’, and this:
-</p>
-<pre class="verbatim"> print join(':', split(//, 'abc', 2)), "\n";
-</pre>
-<p>produces the output ’a:bc’, and each of these:
-</p>
-<pre class="verbatim"> print join(':', split(//, 'abc', 3)), "\n";
- print join(':', split(//, 'abc', 4)), "\n";
-</pre>
-<p>produces the output ’a:b:c’.
-</p>
-<p>If LIMIT is negative, it is treated as if it were instead arbitrarily
-large; as many fields as possible are produced.
-</p>
-<p>If LIMIT is omitted (or, equivalently, zero), then it is usually
-treated as if it were instead negative but with the exception that
-trailing empty fields are stripped (empty leading fields are always
-preserved); if all fields are empty, then all fields are considered to
-be trailing (and are thus stripped in this case). Thus, the following:
-</p>
-<pre class="verbatim"> print join(':', split(',', 'a,b,c,,,')),
"\n";
-</pre>
-<p>produces the output ’a:b:c’, but the following:
-</p>
-<pre class="verbatim"> print join(':', split(',', 'a,b,c,,,', -1)),
"\n";
-</pre>
-<p>produces the output ’a:b:c:::’.
-</p>
-<p>In time-critical applications, it is worthwhile to avoid splitting
-into more fields than necessary. Thus, when assigning to a list,
-if LIMIT is omitted (or zero), then LIMIT is treated as though it
-were one larger than the number of variables in the list; for the
-following, LIMIT is implicitly 3:
-</p>
-<pre class="verbatim"> ($login, $passwd) = split(/:/);
-</pre>
-<p>Note that splitting an EXPR that evaluates to the empty string always
-produces zero fields, regardless of the LIMIT specified.
-</p>
-<p>An empty leading field is produced when there is a positive-width
-match at the beginning of EXPR. For instance:
-</p>
-<pre class="verbatim"> print join(':', split(/ /, ' abc')), "\n";
-</pre>
-<p>produces the output ’:abc’. However, a zero-width match at the
-beginning of EXPR never produces an empty field, so that:
-</p>
-<pre class="verbatim"> print join(':', split(//, ' abc'));
-</pre>
-<p>produces the output ’ :a:b:c’<!-- /@w --> (rather than
’: :a:b:c’<!-- /@w -->).
-</p>
-<p>An empty trailing field, on the other hand, is produced when there is a
-match at the end of EXPR, regardless of the length of the match
-(of course, unless a non-zero LIMIT is given explicitly, such fields are
-removed, as in the last example). Thus:
-</p>
-<pre class="verbatim"> print join(':', split(//, ' abc', -1)),
"\n";
-</pre>
-<p>produces the output ’ :a:b:c:’<!-- /@w -->.
-</p>
-<p>If the PATTERN contains
-<a href="#perlretut-Grouping-things-and-hierarchical-matching">capturing
groups</a>,
-then for each separator, an additional field is produced for each substring
-captured by a group (in the order in which the groups are specified,
-as per <a href="#perlretut-Backreferences">backreferences</a>); if any group
does not
-match, then it captures the <code>undef</code> value instead of a substring.
Also,
-note that any such additional field is produced whenever there is a
-separator (that is, whenever a split occurs), and such an additional field
-does <strong>not</strong> count towards the LIMIT. Consider the following
expressions
-evaluated in list context (each returned list is provided in the associated
-comment):
-</p>
-<pre class="verbatim"> split(/-|,/, "1-10,20", 3)
- # ('1', '10', '20')
-
- split(/(-|,)/, "1-10,20", 3)
- # ('1', '-', '10', ',', '20')
-
- split(/-|(,)/, "1-10,20", 3)
- # ('1', undef, '10', ',', '20')
-
- split(/(-)|,/, "1-10,20", 3)
- # ('1', '-', '10', undef, '20')
-
- split(/(-)|(,)/, "1-10,20", 3)
- # ('1', '-', undef, '10', undef, ',', '20')
-</pre>
-</dd>
-<dt>sprintf FORMAT, LIST</dt>
-<dd><a name="perlfunc-sprintf-FORMAT_002c-LIST"></a>
-<p>Returns a string formatted by the usual <code>printf</code> conventions of
the C
-library function <code>sprintf</code>. See below for more details
-and see <a href="http://man.he.net/man3/sprintf";>sprintf(3)</a> or <a
href="http://man.he.net/man3/printf";>printf(3)</a> on your system for an
explanation of
-the general principles.
-</p>
-<p>For example:
-</p>
-<pre class="verbatim"> # Format number with up to 8 leading zeroes
- $result = sprintf("%08d", $number);
-
- # Round number to 3 digits after decimal point
- $rounded = sprintf("%.3f", $number);
-</pre>
-<p>Perl does its own <code>sprintf</code> formatting: it emulates the C
-function sprintf(3), but doesn’t use it except for floating-point
-numbers, and even then only standard modifiers are allowed.
-Non-standard extensions in your local sprintf(3) are
-therefore unavailable from Perl.
-</p>
-<p>Unlike <code>printf</code>, <code>sprintf</code> does not do what you
probably mean when you
-pass it an array as your first argument.
-The array is given scalar context,
-and instead of using the 0th element of the array as the format, Perl will
-use the count of elements in the array as the format, which is almost never
-useful.
-</p>
-<p>Perl’s <code>sprintf</code> permits the following universally-known
conversions:
-</p>
-<pre class="verbatim"> %% a percent sign
- %c a character with the given number
- %s a string
- %d a signed integer, in decimal
- %u an unsigned integer, in decimal
- %o an unsigned integer, in octal
- %x an unsigned integer, in hexadecimal
- %e a floating-point number, in scientific notation
- %f a floating-point number, in fixed decimal notation
- %g a floating-point number, in %e or %f notation
-</pre>
-<p>In addition, Perl permits the following widely-supported conversions:
-</p>
-<pre class="verbatim"> %X like %x, but using upper-case letters
- %E like %e, but using an upper-case "E"
- %G like %g, but with an upper-case "E" (if applicable)
- %b an unsigned integer, in binary
- %B like %b, but using an upper-case "B" with the # flag
- %p a pointer (outputs the Perl value's address in hexadecimal)
- %n special: *stores* the number of characters output so far
- into the next argument in the parameter list
- %a hexadecimal floating point
- %A like %a, but using upper-case letters
-</pre>
-<p>Finally, for backward (and we do mean "backward") compatibility,
Perl
-permits these unnecessary but widely-supported conversions:
-</p>
-<pre class="verbatim"> %i a synonym for %d
- %D a synonym for %ld
- %U a synonym for %lu
- %O a synonym for %lo
- %F a synonym for %f
-</pre>
-<p>Note that the number of exponent digits in the scientific notation produced
-by <code>%e</code>, <code>%E</code>, <code>%g</code> and <code>%G</code> for
numbers with the modulus of the
-exponent less than 100 is system-dependent: it may be three or less
-(zero-padded as necessary). In other words, 1.23 times ten to the
-99th may be either "1.23e99" or "1.23e099". Similarly for
<code>%a</code> and <code>%A</code>:
-the exponent or the hexadecimal digits may float: especially the
-"long doubles" Perl configuration option may cause surprises.
-</p>
-<p>Between the <code>%</code> and the format letter, you may specify several
-additional attributes controlling the interpretation of the format.
-In order, these are:
-</p>
-<dl compact="compact">
-<dt>format parameter index</dt>
-<dd><a name="perlfunc-format-parameter-index"></a>
-<p>An explicit format parameter index, such as <code>2$</code>. By default
sprintf
-will format the next unused argument in the list, but this allows you
-to take the arguments out of order:
-</p>
-<pre class="verbatim"> printf '%2$d %1$d', 12, 34; # prints "34
12"
- printf '%3$d %d %1$d', 1, 2, 3; # prints "3 1 1"
-</pre>
-</dd>
-<dt>flags</dt>
-<dd><a name="perlfunc-flags"></a>
-<p>one or more of:
-</p>
-<pre class="verbatim"> space prefix non-negative number with a space
- + prefix non-negative number with a plus sign
- - left-justify within the field
- 0 use zeros, not spaces, to right-justify
- # ensure the leading "0" for any octal,
- prefix non-zero hexadecimal with "0x" or "0X",
- prefix non-zero binary with "0b" or "0B"
-</pre>
-<p>For example:
-</p>
-<pre class="verbatim"> printf '<% d>', 12; # prints "<
12>"
- printf '<%+d>', 12; # prints "<+12>"
- printf '<%6s>', 12; # prints "< 12>"
- printf '<%-6s>', 12; # prints "<12 >"
- printf '<%06s>', 12; # prints "<000012>"
- printf '<%#o>', 12; # prints "<014>"
- printf '<%#x>', 12; # prints "<0xc>"
- printf '<%#X>', 12; # prints "<0XC>"
- printf '<%#b>', 12; # prints "<0b1100>"
- printf '<%#B>', 12; # prints "<0B1100>"
-</pre>
-<p>When a space and a plus sign are given as the flags at once,
-a plus sign is used to prefix a positive number.
-</p>
-<pre class="verbatim"> printf '<%+ d>', 12; # prints
"<+12>"
- printf '<% +d>', 12; # prints "<+12>"
-</pre>
-<p>When the # flag and a precision are given in the %o conversion,
-the precision is incremented if it’s necessary for the leading
"0".
-</p>
-<pre class="verbatim"> printf '<%#.5o>', 012; # prints
"<00012>"
- printf '<%#.5o>', 012345; # prints "<012345>"
- printf '<%#.0o>', 0; # prints "<0>"
-</pre>
-</dd>
-<dt>vector flag</dt>
-<dd><a name="perlfunc-vector-flag"></a>
-<p>This flag tells Perl to interpret the supplied string as a vector of
-integers, one for each character in the string. Perl applies the format to
-each integer in turn, then joins the resulting strings with a separator (a
-dot <code>.</code> by default). This can be useful for displaying ordinal
values of
-characters in arbitrary strings:
-</p>
-<pre class="verbatim"> printf "%vd", "AB\x{100}";
# prints "65.66.256"
- printf "version is v%vd\n", $^V; # Perl's version
-</pre>
-<p>Put an asterisk <code>*</code> before the <code>v</code> to override the
string to
-use to separate the numbers:
-</p>
-<pre class="verbatim"> printf "address is %*vX\n", ":",
$addr; # IPv6 address
- printf "bits are %0*v8b\n", " ", $bits; # random
bitstring
-</pre>
-<p>You can also explicitly specify the argument number to use for
-the join string using something like <code>*2$v</code>; for example:
-</p>
-<pre class="verbatim"> printf '%*4$vX %*4$vX %*4$vX', # 3 IPv6 addresses
- @addr[1..3], ":";
-</pre>
-</dd>
-<dt>(minimum) width</dt>
-<dd><a name="perlfunc-_0028minimum_0029-width"></a>
-<p>Arguments are usually formatted to be only as wide as required to
-display the given value. You can override the width by putting
-a number here, or get the width from the next argument (with <code>*</code>)
-or from a specified argument (e.g., with <code>*2$</code>):
-</p>
-<pre class="verbatim"> 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)
-</pre>
-<p>If a field width obtained through <code>*</code> is negative, it has the
same
-effect as the <code>-</code> flag: left-justification.
-</p>
-</dd>
-<dt>precision, or maximum width</dt>
-<dd><a name="perlfunc-precision_002c-or-maximum-width"></a>
-<p>You can specify a precision (for numeric conversions) or a maximum
-width (for string conversions) by specifying a <code>.</code> followed by a
number.
-For floating-point formats except <code>g</code> and <code>G</code>, this
specifies
-how many places right of the decimal point to show (the default being 6).
-For example:
-</p>
-<pre class="verbatim"> # these examples are subject to system-specific
variation
- printf '<%f>', 1; # prints "<1.000000>"
- printf '<%.1f>', 1; # prints "<1.0>"
- printf '<%.0f>', 1; # prints "<1>"
- printf '<%e>', 10; # prints "<1.000000e+01>"
- printf '<%.1e>', 10; # prints "<1.0e+01>"
-</pre>
-<p>For "g" and "G", this specifies the maximum number of
digits to show,
-including those prior to the decimal point and those after it; for
-example:
-</p>
-<pre class="verbatim"> # These examples are subject to system-specific
variation.
- printf '<%g>', 1; # prints "<1>"
- printf '<%.10g>', 1; # prints "<1>"
- printf '<%g>', 100; # prints "<100>"
- printf '<%.1g>', 100; # prints "<1e+02>"
- printf '<%.2g>', 100.01; # prints "<1e+02>"
- printf '<%.5g>', 100.01; # prints "<100.01>"
- printf '<%.4g>', 100.01; # prints "<100>"
-</pre>
-<p>For integer conversions, specifying a precision implies that the
-output of the number itself should be zero-padded to this width,
-where the 0 flag is ignored:
-</p>
-<pre class="verbatim"> printf '<%.6d>', 1; # prints
"<000001>"
- printf '<%+.6d>', 1; # prints "<+000001>"
- printf '<%-10.6d>', 1; # prints "<000001 >"
- printf '<%10.6d>', 1; # prints "< 000001>"
- printf '<%010.6d>', 1; # prints "< 000001>"
- printf '<%+10.6d>', 1; # prints "< +000001>"
-
- printf '<%.6x>', 1; # prints "<000001>"
- printf '<%#.6x>', 1; # prints "<0x000001>"
- printf '<%-10.6x>', 1; # prints "<000001 >"
- printf '<%10.6x>', 1; # prints "< 000001>"
- printf '<%010.6x>', 1; # prints "< 000001>"
- printf '<%#10.6x>', 1; # prints "< 0x000001>"
-</pre>
-<p>For string conversions, specifying a precision truncates the string
-to fit the specified width:
-</p>
-<pre class="verbatim"> printf '<%.5s>', "truncated"; #
prints "<trunc>"
- printf '<%10.5s>', "truncated"; # prints "<
trunc>"
-</pre>
-<p>You can also get the precision from the next argument using <code>.*</code>:
-</p>
-<pre class="verbatim"> printf '<%.6x>', 1; # prints
"<000001>"
- printf '<%.*x>', 6, 1; # prints "<000001>"
-</pre>
-<p>If a precision obtained through <code>*</code> is negative, it counts
-as having no precision at all.
-</p>
-<pre class="verbatim"> printf '<%.*s>', 7, "string"; #
prints "<string>"
- printf '<%.*s>', 3, "string"; # prints
"<str>"
- printf '<%.*s>', 0, "string"; # prints
"<>"
- printf '<%.*s>', -1, "string"; # prints
"<string>"
-
- printf '<%.*d>', 1, 0; # prints "<0>"
- printf '<%.*d>', 0, 0; # prints "<>"
- printf '<%.*d>', -1, 0; # prints "<0>"
-</pre>
-<p>You cannot currently get the precision from a specified number,
-but it is intended that this will be possible in the future, for
-example using <code>.*2$</code>:
-</p>
-<pre class="verbatim"> printf '<%.*2$x>', 1, 6; # INVALID, but in
future will print
- # "<000001>"
-</pre>
-</dd>
-<dt>size</dt>
-<dd><a name="perlfunc-size"></a>
-<p>For numeric conversions, you can specify the size to interpret the
-number as using <code>l</code>, <code>h</code>, <code>V</code>,
<code>q</code>, <code>L</code>, or <code>ll</code>. For integer
-conversions (<code>d u o x X b i D U O</code>), numbers are usually assumed to
be
-whatever the default integer size is on your platform (usually 32 or 64
-bits), but you can override this to use instead one of the standard C types,
-as supported by the compiler used to build Perl:
-</p>
-<pre class="verbatim"> hh interpret integer as C type
"char" or "unsigned
- char" on Perl 5.14 or later
- h interpret integer as C type "short" or
- "unsigned short"
- j interpret integer as C type "intmax_t" on Perl
- 5.14 or later, and only with a C99 compiler
- (unportable)
- l interpret integer as C type "long" or
- "unsigned long"
- q, L, or ll interpret integer as C type "long long",
- "unsigned long long", or "quad" (typically
- 64-bit integers)
- t interpret integer as C type "ptrdiff_t" on Perl
- 5.14 or later
- z interpret integer as C type "size_t" on Perl 5.14
- or later
-</pre>
-<p>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
-<code>printf</code> warning class is issued on an unsupported conversion flag.
-Should you instead prefer an exception, do this:
-</p>
-<pre class="verbatim"> use warnings FATAL => "printf";
-</pre>
-<p>If you would like to know about a version dependency before you
-start running the program, put something like this at its top:
-</p>
-<pre class="verbatim"> use 5.014; # for hh/j/t/z/ printf modifiers
-</pre>
-<p>You can find out whether your Perl supports quads via <a
href="Config.html#Top">(Config)</a>:
-</p>
-<pre class="verbatim"> use Config;
- if ($Config{use64bitint} eq "define"
- || $Config{longsize} >= 8) {
- print "Nice quads!\n";
- }
-</pre>
-<p>For floating-point conversions (<code>e f g E F G</code>), numbers are
usually assumed
-to be the default floating-point size on your platform (double or long double),
-but you can force "long double" with <code>q</code>, <code>L</code>,
or <code>ll</code> if your
-platform supports them. You can find out whether your Perl supports long
-doubles via <a href="Config.html#Top">(Config)</a>:
-</p>
-<pre class="verbatim"> use Config;
- print "long doubles\n" if $Config{d_longdbl} eq
"define";
-</pre>
-<p>You can find out whether Perl considers "long double" to be the
default
-floating-point size to use on your platform via <a
href="Config.html#Top">(Config)</a>:
-</p>
-<pre class="verbatim"> use Config;
- if ($Config{uselongdouble} eq "define") {
- print "long doubles by default\n";
- }
-</pre>
-<p>It can also be that long doubles and doubles are the same thing:
-</p>
-<pre class="verbatim"> use Config;
- ($Config{doublesize} == $Config{longdblsize}) &&
- print "doubles are long doubles\n";
-</pre>
-<p>The size specifier <code>V</code> has no effect for Perl code, but is
supported for
-compatibility with XS code. It means "use the standard size for a Perl
-integer or floating-point number", which is the default.
-</p>
-</dd>
-<dt>order of arguments</dt>
-<dd><a name="perlfunc-order-of-arguments"></a>
-<p>Normally, sprintf() takes the next unused argument as the value to
-format for each format specification. If the format specification
-uses <code>*</code> to require additional arguments, these are consumed from
-the argument list in the order they appear in the format
-specification <em>before</em> the value to format. Where an argument is
-specified by an explicit index, this does not affect the normal
-order for the arguments, even when the explicitly specified index
-would have been the next argument.
-</p>
-<p>So:
-</p>
-<pre class="verbatim"> printf "<%*.*s>", $a, $b, $c;
-</pre>
-<p>uses <code>$a</code> for the width, <code>$b</code> for the precision, and
<code>$c</code>
-as the value to format; while:
-</p>
-<pre class="verbatim"> printf '<%*1$.*s>', $a, $b;
-</pre>
-<p>would use <code>$a</code> for the width and precision, and <code>$b</code>
as the
-value to format.
-</p>
-<p>Here are some more examples; be aware that when using an explicit
-index, the <code>$</code> may need escaping:
-</p>
-<pre class="verbatim"> printf "%2\$d %d\n", 12, 34; # will
print "34 12\n"
- printf "%2\$d %d %d\n", 12, 34; # will print "34 12
34\n"
- printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12
34\n"
- printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34
12\n"
-</pre>
-</dd>
-</dl>
-
-<p>If <code>use locale</code> (including <code>use locale
'not_characters'</code>) 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 <code>LC_NUMERIC</code> locale. See <a
href="#perllocale-NAME">perllocale NAME</a>
-and <a href="POSIX.html#Top">(POSIX)</a>.
-</p>
-</dd>
-<dt>sqrt EXPR</dt>
-<dd><a name="perlfunc-sqrt-EXPR"></a>
-</dd>
-<dt>sqrt</dt>
-<dd><a name="perlfunc-sqrt"></a>
-<p>Return the positive square root of EXPR. If EXPR is omitted, uses
-<code>$_</code>. Works only for non-negative operands unless you’ve
-loaded the <code>Math::Complex</code> module.
-</p>
-<pre class="verbatim"> use Math::Complex;
- print sqrt(-4); # prints 2i
-</pre>
-</dd>
-<dt>srand EXPR</dt>
-<dd><a name="perlfunc-srand-EXPR"></a>
-</dd>
-<dt>srand</dt>
-<dd><a name="perlfunc-srand"></a>
-<p>Sets and returns the random number seed for the <code>rand</code> operator.
-</p>
-<p>The point of the function is to "seed" the <code>rand</code>
function so that <code>rand</code>
-can produce a different sequence each time you run your program. When
-called with a parameter, <code>srand</code> uses that for the seed; otherwise
it
-(semi-)randomly chooses a seed. In either case, starting with Perl 5.14,
-it returns the seed. To signal that your code will work <em>only</em> on Perls
-of a recent vintage:
-</p>
-<pre class="verbatim"> use 5.014; # so srand returns the seed
-</pre>
-<p>If <code>srand()</code> is not called explicitly, it is called implicitly
without a
-parameter at the first use of the <code>rand</code> operator.
-However, there are a few situations where programs are likely to
-want to call <code>srand</code>. One is for generating predictable results,
generally for
-testing or debugging. There, you use <code>srand($seed)</code>, with the same
<code>$seed</code>
-each time. Another case is that you may want to call <code>srand()</code>
-after a <code>fork()</code> to avoid child processes sharing the same seed
value as the
-parent (and consequently each other).
-</p>
-<p>Do <strong>not</strong> call <code>srand()</code> (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
-<code>srand()</code> again actually <em>loses</em> randomness.
-</p>
-<p>Most implementations of <code>srand</code> take an integer and will silently
-truncate decimal numbers. This means <code>srand(42)</code> will usually
-produce the same results as <code>srand(42.1)</code>. To be safe, always pass
-<code>srand</code> an integer.
-</p>
-<p>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.
-</p>
-<p><strong><code>rand()</code> is not cryptographically secure. You should
not rely
-on it in security-sensitive situations.</strong> As of this writing, a
-number of third-party CPAN modules offer random number generators
-intended by their authors to be cryptographically secure,
-including: <a href="Data-Entropy.html#Top">(Data-Entropy)</a>, <a
href="Crypt-Random.html#Top">(Crypt-Random)</a>, <a
href="Math-Random-Secure.html#Top">(Math-Random-Secure)</a>,
-and <a href="Math-TrulyRandom.html#Top">(Math-TrulyRandom)</a>.
-</p>
-</dd>
-<dt>stat FILEHANDLE</dt>
-<dd><a name="perlfunc-stat-FILEHANDLE"></a>
-</dd>
-<dt>stat EXPR</dt>
-<dd><a name="perlfunc-stat-EXPR"></a>
-</dd>
-<dt>stat DIRHANDLE</dt>
-<dd><a name="perlfunc-stat-DIRHANDLE"></a>
-</dd>
-<dt>stat</dt>
-<dd><a name="perlfunc-stat"></a>
-<p>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 <code>$_</code> (not <code>_</code>!). Returns the empty
list if <code>stat</code> fails. Typically
-used as follows:
-</p>
-<pre class="verbatim"> ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
- $atime,$mtime,$ctime,$blksize,$blocks)
- = stat($filename);
-</pre>
-<p>Not all fields are supported on all filesystem types. Here are the
-meanings of the fields:
-</p>
-<pre class="verbatim"> 0 dev device number of filesystem
- 1 ino inode number
- 2 mode file mode (type and permissions)
- 3 nlink number of (hard) links to the file
- 4 uid numeric user ID of file's owner
- 5 gid numeric group ID of file's owner
- 6 rdev the device identifier (special files only)
- 7 size total size of file, in bytes
- 8 atime last access time in seconds since the epoch
- 9 mtime last modify time in seconds since the epoch
- 10 ctime inode change time in seconds since the epoch (*)
- 11 blksize preferred I/O size in bytes for interacting with the
- file (may vary from file to file)
- 12 blocks actual number of system-specific blocks allocated
- on disk (often, but not always, 512 bytes each)
-</pre>
-<p>(The epoch was at 00:00 January 1, 1970 GMT.)
-</p>
-<p>(*) 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 <a
href="#perlport-Files-and-Filesystems">perlport Files and Filesystems</a> for
details.
-</p>
-<p>If <code>stat</code> is passed the special filehandle consisting of an
underline, no
-stat is done, but the current contents of the stat structure from the
-last <code>stat</code>, <code>lstat</code>, or filetest are returned. Example:
-</p>
-<pre class="verbatim"> if (-x $file && (($d) = stat(_)) &&
$d < 0) {
- print "$file is executable NFS file\n";
- }
-</pre>
-<p>(This works on machines only for which the device number is negative
-under NFS.)
-</p>
-<p>Because the mode contains both the file type and its permissions, you
-should mask off the file type portion and (s)printf using a
<code>"%o"</code>
-if you want to see the real permissions.
-</p>
-<pre class="verbatim"> $mode = (stat($filename))[2];
- printf "Permissions are %04o\n", $mode & 07777;
-</pre>
-<p>In scalar context, <code>stat</code> returns a boolean value indicating
success
-or failure, and, if successful, sets the information associated with
-the special filehandle <code>_</code>.
-</p>
-<p>The <a href="File-stat.html#Top">(File-stat)</a> module provides a
convenient, by-name access mechanism:
-</p>
-<pre class="verbatim"> use File::stat;
- $sb = stat($filename);
- printf "File is %s, size is %s, perm %04o, mtime %s\n",
- $filename, $sb->size, $sb->mode & 07777,
- scalar localtime $sb->mtime;
-</pre>
-<p>You can import symbolic mode constants (<code>S_IF*</code>) and functions
-(<code>S_IS*</code>) from the Fcntl module:
-</p>
-<pre class="verbatim"> use Fcntl ':mode';
-
- $mode = (stat($filename))[2];
-
- $user_rwx = ($mode & S_IRWXU) >> 6;
- $group_read = ($mode & S_IRGRP) >> 3;
- $other_execute = $mode & S_IXOTH;
-
- printf "Permissions are %04o\n", S_IMODE($mode), "\n";
-
- $is_setuid = $mode & S_ISUID;
- $is_directory = S_ISDIR($mode);
-</pre>
-<p>You could write the last two using the <code>-u</code> and <code>-d</code>
operators.
-Commonly available <code>S_IF*</code> constants are:
-</p>
-<pre class="verbatim"> # Permissions: read, write, execute, for user,
group, others.
-
- S_IRWXU S_IRUSR S_IWUSR S_IXUSR
- S_IRWXG S_IRGRP S_IWGRP S_IXGRP
- S_IRWXO S_IROTH S_IWOTH S_IXOTH
-
- # Setuid/Setgid/Stickiness/SaveText.
- # Note that the exact meaning of these is system-dependent.
-
- S_ISUID S_ISGID S_ISVTX S_ISTXT
-
- # File types. Not all are necessarily available on
- # your system.
-
- S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR
- S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
-
- # The following are compatibility aliases for S_IRUSR,
- # S_IWUSR, and S_IXUSR.
-
- S_IREAD S_IWRITE S_IEXEC
-</pre>
-<p>and the <code>S_IF*</code> functions are
-</p>
-<pre class="verbatim"> S_IMODE($mode) the part of $mode containing the
permission
- bits and the setuid/setgid/sticky bits
-
- S_IFMT($mode) the part of $mode containing the file type
- which can be bit-anded with (for example)
- S_IFREG or with the following functions
-
- # The operators -f, -d, -l, -b, -c, -p, and -S.
-
- S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
- S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
-
- # No direct -X operator counterpart, but for the first one
- # the -g operator is often equivalent. The ENFMT stands for
- # record flocking enforcement, a platform-dependent feature.
-
- S_ISENFMT($mode) S_ISWHT($mode)
-</pre>
-<p>See your native chmod(2) and stat(2) documentation for more details
-about the <code>S_*</code> constants. To get status info for a symbolic link
-instead of the target file behind the link, use the <code>lstat</code>
function.
-</p>
-<p>Portability issues: <a href="#perlport-stat">perlport stat</a>.
-</p>
-</dd>
-<dt>state VARLIST</dt>
-<dd><a name="perlfunc-state-VARLIST"></a>
-</dd>
-<dt>state TYPE VARLIST</dt>
-<dd><a name="perlfunc-state-TYPE-VARLIST"></a>
-</dd>
-<dt>state VARLIST : ATTRS</dt>
-<dd><a name="perlfunc-state-VARLIST-_003a-ATTRS"></a>
-</dd>
-<dt>state TYPE VARLIST : ATTRS</dt>
-<dd><a name="perlfunc-state-TYPE-VARLIST-_003a-ATTRS"></a>
-<p><code>state</code> declares a lexically scoped variable, just like
<code>my</code>.
-However, those variables will never be reinitialized, contrary to
-lexical variables that are reinitialized each time their enclosing block
-is entered.
-See <a href="#perlsub-Persistent-Private-Variables">perlsub Persistent Private
Variables</a> for details.
-</p>
-<p>If more than one variable is listed, the list must be placed in
-parentheses. With a parenthesised list, <code>undef</code> can be used as a
-dummy placeholder. However, since initialization of state variables in
-list context is currently not possible this would serve no purpose.
-</p>
-<p><code>state</code> variables are enabled only when the <code>use feature
"state"</code> pragma
-is in effect, unless the keyword is written as <code>CORE::state</code>.
-See also <a href="feature.html#Top">(feature)</a>. Alternately, include a
<code>use v5.10</code> or later to the
-current scope.
-</p>
-</dd>
-<dt>study SCALAR</dt>
-<dd><a name="perlfunc-study-SCALAR"></a>
-</dd>
-<dt>study</dt>
-<dd><a name="perlfunc-study"></a>
-<p>May take extra time to study SCALAR (<code>$_</code> 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 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 is faster. Those loops
-that scan for many short constant strings (including the constant
-parts of more complex patterns) will benefit most.
-</p>
-<p>Note that since Perl version 5.16 this function has been a no-op, but
-this might change in a future release.
-</p>
-<p>(The way <code>study</code> works is this: a linked list of every
-character in the string to be searched is made, so we know, for
-example, where all the <code>'k'</code> characters are. From each search
string,
-the rarest character is selected, based on some static frequency tables
-constructed from some C programs and English text. Only those places
-that contain this "rarest" character are examined.)
-</p>
-<p>For example, here is a loop that inserts index producing entries
-before any line containing a certain pattern:
-</p>
-<pre class="verbatim"> while (<>) {
- study;
- print ".IX foo\n" if /\bfoo\b/;
- print ".IX bar\n" if /\bbar\b/;
- print ".IX blurfl\n" if /\bblurfl\b/;
- # ...
- print;
- }
-</pre>
-<p>In searching for <code>/\bfoo\b/</code>, only locations in <code>$_</code>
that contain <code>f</code>
-will be looked at, because <code>f</code> is rarer than <code>o</code>. In
general, this is
-a big win except in pathological cases. The only question is whether
-it saves you more time than it took to build the linked list in the
-first place.
-</p>
-<p>Note that if you have to look for strings that you don’t know till
-runtime, you can build an entire loop as a string and <code>eval</code> that to
-avoid recompiling all your patterns all the time. Together with
-undefining <code>$/</code> to input entire files as one record, this can be
quite
-fast, often faster than specialized programs like fgrep(1). The following
-scans a list of files (<code>@files</code>) for a list of words
(<code>@words</code>), and prints
-out the names of those files that contain a match:
-</p>
-<pre class="verbatim"> $search = 'while (<>) { study;';
- foreach $word (@words) {
- $search .= "++\$seen{\$ARGV} if /\\b$word\\b/;\n";
- }
- $search .= "}";
- @ARGV = @files;
- undef $/;
- eval $search; # this screams
- $/ = "\n"; # put back to normal input delimiter
- foreach $file (sort keys(%seen)) {
- print $file, "\n";
- }
-</pre>
-</dd>
-<dt>sub NAME BLOCK</dt>
-<dd><a name="perlfunc-sub-NAME-BLOCK"></a>
-</dd>
-<dt>sub NAME (PROTO) BLOCK</dt>
-<dd><a name="perlfunc-sub-NAME-_0028PROTO_0029-BLOCK"></a>
-</dd>
-<dt>sub NAME : ATTRS BLOCK</dt>
-<dd><a name="perlfunc-sub-NAME-_003a-ATTRS-BLOCK"></a>
-</dd>
-<dt>sub NAME (PROTO) : ATTRS BLOCK</dt>
-<dd><a name="perlfunc-sub-NAME-_0028PROTO_0029-_003a-ATTRS-BLOCK"></a>
-<p>This is subroutine definition, not a real function <em>per se</em>.
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.
-</p>
-<p>See <a href="#perlsub-NAME">perlsub NAME</a> and <a
href="#perlref-NAME">perlref NAME</a> for details about subroutines and
-references; see <a href="attributes.html#Top">(attributes)</a> and <a
href="Attribute-Handlers.html#Top">(Attribute-Handlers)</a> for more
-information about attributes.
-</p>
-</dd>
-<dt>__SUB__</dt>
-<dd><a name="perlfunc-_005f_005fSUB_005f_005f"></a>
-<p>A special token that returns a reference to the current subroutine, or
-<code>undef</code> outside of a subroutine.
-</p>
-<p>The behaviour of <code>__SUB__</code> within a regex code block (such as
<code>/(?{...})/</code>)
-is subject to change.
-</p>
-<p>This token is only available under <code>use v5.16</code> or the
"current_sub"
-feature. See <a href="feature.html#Top">(feature)</a>.
-</p>
-</dd>
-<dt>substr EXPR,OFFSET,LENGTH,REPLACEMENT</dt>
-<dd><a name="perlfunc-substr-EXPR_002cOFFSET_002cLENGTH_002cREPLACEMENT"></a>
-</dd>
-<dt>substr EXPR,OFFSET,LENGTH</dt>
-<dd><a name="perlfunc-substr-EXPR_002cOFFSET_002cLENGTH"></a>
-</dd>
-<dt>substr EXPR,OFFSET</dt>
-<dd><a name="perlfunc-substr-EXPR_002cOFFSET"></a>
-<p>Extracts a substring out of EXPR and returns it. First character is at
-offset zero. If OFFSET is negative, starts
-that far back from the end of the string. If LENGTH is omitted, returns
-everything through the end of the string. If LENGTH is negative, leaves that
-many characters off the end of the string.
-</p>
-<pre class="verbatim"> my $s = "The black cat climbed the green
tree";
- my $color = substr $s, 4, 5; # black
- my $middle = substr $s, 4, -11; # black cat climbed the
- my $end = substr $s, 14; # climbed the green tree
- my $tail = substr $s, -4; # tree
- my $z = substr $s, -4, 2; # tr
-</pre>
-<p>You can use the substr() function as an lvalue, in which case EXPR
-must itself be an lvalue. If you assign something shorter than LENGTH,
-the string will shrink, and if you assign something longer than LENGTH,
-the string will grow to accommodate it. To keep the string the same
-length, you may need to pad or chop your value using <code>sprintf</code>.
-</p>
-<p>If OFFSET and LENGTH specify a substring that is partly outside the
-string, only the part within the string is returned. If the substring
-is beyond either end of the string, substr() returns the undefined
-value and produces a warning. When used as an lvalue, specifying a
-substring that is entirely outside the string raises an exception.
-Here’s an example showing the behavior for boundary cases:
-</p>
-<pre class="verbatim"> my $name = 'fred';
- substr($name, 4) = 'dy'; # $name is now 'freddy'
- my $null = substr $name, 6, 2; # returns "" (no warning)
- my $oops = substr $name, 7; # returns undef, with warning
- substr($name, 7) = 'gap'; # raises an exception
-</pre>
-<p>An alternative to using substr() as an lvalue is to specify the
-replacement string as the 4th argument. This allows you to replace
-parts of the EXPR and return what was there before in one operation,
-just as you can with splice().
-</p>
-<pre class="verbatim"> my $s = "The black cat climbed the green
tree";
- my $z = substr $s, 14, 7, "jumped from"; # climbed
- # $s is now "The black cat jumped from the green tree"
-</pre>
-<p>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:
-</p>
-<pre class="verbatim"> $x = '1234';
- for (substr($x,1,2)) {
- $_ = 'a'; print $x,"\n"; # prints 1a4
- $_ = 'xyz'; print $x,"\n"; # prints 1xyz4
- $x = '56789';
- $_ = 'pq'; print $x,"\n"; # prints 5pq9
- }
-</pre>
-<p>With negative offsets, it remembers its position from the end of the string
-when the target string is modified:
-</p>
-<pre class="verbatim"> $x = '1234';
- for (substr($x, -3, 2)) {
- $_ = 'a'; print $x,"\n"; # prints 1a4, as above
- $x = 'abcdefg';
- print $_,"\n"; # prints f
- }
-</pre>
-<p>Prior to Perl version 5.10, the result of using an lvalue multiple times was
-unspecified. Prior to 5.16, the result with negative offsets was
-unspecified.
-</p>
-</dd>
-<dt>symlink OLDFILE,NEWFILE</dt>
-<dd><a name="perlfunc-symlink-OLDFILE_002cNEWFILE"></a>
-<p>Creates a new filename symbolically linked to the old filename.
-Returns <code>1</code> for success, <code>0</code> otherwise. On systems that
don’t support
-symbolic links, raises an exception. To check for that,
-use eval:
-</p>
-<pre class="verbatim"> $symlink_exists = eval {
symlink("",""); 1 };
-</pre>
-<p>Portability issues: <a href="#perlport-symlink">perlport symlink</a>.
-</p>
-</dd>
-<dt>syscall NUMBER, LIST</dt>
-<dd><a name="perlfunc-syscall-NUMBER_002c-LIST"></a>
-<p>Calls the system call specified as the first element of the list,
-passing the remaining elements as arguments to the system call. If
-unimplemented, raises an exception. The arguments are interpreted
-as follows: if a given argument is numeric, the argument is passed as
-an int. If not, the pointer to the string value is passed. You are
-responsible to make sure a string is pre-extended long enough to
-receive any result that might be written into a string. You can’t use a
-string literal (or other read-only string) as an argument to
<code>syscall</code>
-because Perl has to assume that any string pointer might be written
-through. If your
-integer arguments are not literals and have never been interpreted in a
-numeric context, you may need to add <code>0</code> to them to force them to
look
-like numbers. This emulates the <code>syswrite</code> function (or vice
versa):
-</p>
-<pre class="verbatim"> require 'syscall.ph'; # may need to run h2ph
- $s = "hi there\n";
- syscall(&SYS_write, fileno(STDOUT), $s, length $s);
-</pre>
-<p>Note that Perl supports passing of up to only 14 arguments to your syscall,
-which in practice should (usually) suffice.
-</p>
-<p>Syscall returns whatever value returned by the system call it calls.
-If the system call fails, <code>syscall</code> returns <code>-1</code> and
sets <code>$!</code> (errno).
-Note that some system calls <em>can</em> legitimately return <code>-1</code>.
The proper
-way to handle such calls is to assign <code>$!=0</code> before the call, then
-check the value of <code>$!</code> if <code>syscall</code> returns
<code>-1</code>.
-</p>
-<p>There’s a problem with <code>syscall(&SYS_pipe)</code>: it
returns the file
-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 <code>pipe</code> instead.
-</p>
-<p>Portability issues: <a href="#perlport-syscall">perlport syscall</a>.
-</p>
-</dd>
-<dt>sysopen FILEHANDLE,FILENAME,MODE</dt>
-<dd><a name="perlfunc-sysopen-FILEHANDLE_002cFILENAME_002cMODE"></a>
-</dd>
-<dt>sysopen FILEHANDLE,FILENAME,MODE,PERMS</dt>
-<dd><a name="perlfunc-sysopen-FILEHANDLE_002cFILENAME_002cMODE_002cPERMS"></a>
-<p>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 <em>open</em>(2)
function with the
-parameters FILENAME, MODE, and PERMS.
-</p>
-<p>Returns true on success and <code>undef</code> otherwise.
-</p>
-<p>The possible values and flag bits of the MODE parameter are
-system-dependent; they are available via the standard module
<code>Fcntl</code>. See
-the documentation of your operating system’s <em>open</em>(2) syscall to
see
-which values and flag bits are available. You may combine several flags
-using the <code>|</code>-operator.
-</p>
-<p>Some of the most common values are <code>O_RDONLY</code> for opening the
file in
-read-only mode, <code>O_WRONLY</code> for opening the file in write-only mode,
-and <code>O_RDWR</code> for opening the file in read-write mode.
-</p>
-<p>For historical reasons, some values work on almost every system
-supported by Perl: 0 means read-only, 1 means write-only, and 2
-means read/write. We know that these values do <em>not</em> work under
-OS/390 and on the Macintosh; you probably don’t want to
-use them in new code.
-</p>
-<p>If the file named by FILENAME does not exist and the <code>open</code> call
creates
-it (typically because MODE includes the <code>O_CREAT</code> flag), then the
value of
-PERMS specifies the permissions of the newly created file. If you omit
-the PERMS argument to <code>sysopen</code>, Perl uses the octal value
<code>0666</code>.
-These permission values need to be in octal, and are modified by your
-process’s current <code>umask</code>.
-</p>
-<p>In many systems the <code>O_EXCL</code> flag is available for opening files
in
-exclusive mode. This is <strong>not</strong> locking: exclusiveness means
here that
-if the file already exists, sysopen() fails. <code>O_EXCL</code> may not work
-on network filesystems, and has no effect unless the <code>O_CREAT</code> flag
-is set as well. Setting <code>O_CREAT|O_EXCL</code> prevents the file from
-being opened if it is a symbolic link. It does not protect against
-symbolic links in the file’s path.
-</p>
-<p>Sometimes you may want to truncate an already-existing file. This
-can be done using the <code>O_TRUNC</code> flag. The behavior of
-<code>O_TRUNC</code> with <code>O_RDONLY</code> is undefined.
-</p>
-<p>You should seldom if ever use <code>0644</code> as argument to
<code>sysopen</code>, because
-that takes away the user’s option to have a more permissive umask.
-Better to omit it. See the perlfunc(1) entry on <code>umask</code> for more
-on this.
-</p>
-<p>Note that <code>sysopen</code> depends on the fdopen() C library function.
-On many Unix systems, fdopen() is known to fail when file descriptors
-exceed a certain value, typically 255. If you need more file
-descriptors than that, consider using the POSIX::open() function.
-</p>
-<p>See <a href="#perlopentut-NAME">perlopentut NAME</a> for a kinder, gentler
explanation of opening files.
-</p>
-<p>Portability issues: <a href="#perlport-sysopen">perlport sysopen</a>.
-</p>
-</dd>
-<dt>sysread FILEHANDLE,SCALAR,LENGTH,OFFSET</dt>
-<dd><a name="perlfunc-sysread-FILEHANDLE_002cSCALAR_002cLENGTH_002cOFFSET"></a>
-</dd>
-<dt>sysread FILEHANDLE,SCALAR,LENGTH</dt>
-<dd><a name="perlfunc-sysread-FILEHANDLE_002cSCALAR_002cLENGTH"></a>
-<p>Attempts to read LENGTH bytes of data into variable SCALAR from the
-specified FILEHANDLE, using the read(2). It bypasses
-buffered IO, so mixing this with other kinds of reads, <code>print</code>,
-<code>write</code>, <code>seek</code>, <code>tell</code>, or <code>eof</code>
can cause confusion because the
-perlio or stdio layers usually buffers data. Returns the number of
-bytes actually read, <code>0</code> at end of file, or undef if there was an
-error (in the latter case <code>$!</code> is also set). SCALAR will be grown
or
-shrunk so that the last byte actually read is the last byte of the
-scalar after the read.
-</p>
-<p>An OFFSET may be specified to place the read data at some place in the
-string other than the beginning. A negative OFFSET specifies
-placement at that many characters counting backwards from the end of
-the string. A positive OFFSET greater than the length of SCALAR
-results in the string being padded to the required size with
<code>"\0"</code>
-bytes before the result of the read is appended.
-</p>
-<p>There is no syseof() function, which is ok, since eof() doesn’t work
-well on device files (like ttys) anyway. Use sysread() and check
-for a return value for 0 to decide whether you’re done.
-</p>
-<p>Note that if the filehandle has been marked as <code>:utf8</code> Unicode
-characters are read instead of bytes (the LENGTH, OFFSET, and the
-return value of sysread() are in Unicode characters).
-The <code>:encoding(...)</code> layer implicitly introduces the
<code>:utf8</code> layer.
-See ‘binmode’, ‘open’, and the <code>open</code>
pragma, <a href="open.html#Top">(open)</a>.
-</p>
-</dd>
-<dt>sysseek FILEHANDLE,POSITION,WHENCE</dt>
-<dd><a name="perlfunc-sysseek-FILEHANDLE_002cPOSITION_002cWHENCE"></a>
-<p>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 <code>0</code> to set the new position to POSITION;
<code>1</code> to set the it
-to the current position plus POSITION; and <code>2</code> to set it to EOF plus
-POSITION, typically negative.
-</p>
-<p>Note the <em>in bytes</em>: even if the filehandle has been set to operate
-on characters (for example by using the <code>:encoding(utf8)</code> I/O
layer),
-tell() will return byte offsets, not character offsets (because
-implementing that would render sysseek() unacceptably slow).
-</p>
-<p>sysseek() bypasses normal buffered IO, so mixing it with reads other
-than <code>sysread</code> (for example <code><></code> or read())
<code>print</code>, <code>write</code>,
-<code>seek</code>, <code>tell</code>, or <code>eof</code> may cause confusion.
-</p>
-<p>For WHENCE, you may also use the constants <code>SEEK_SET</code>,
<code>SEEK_CUR</code>,
-and <code>SEEK_END</code> (start of the file, current position, end of the
file)
-from the Fcntl module. Use of the constants is also more portable
-than relying on 0, 1, and 2. For example to define a "systell"
function:
-</p>
-<pre class="verbatim"> use Fcntl 'SEEK_CUR';
- sub systell { sysseek($_[0], 0, SEEK_CUR) }
-</pre>
-<p>Returns the new position, or the undefined value on failure. A position
-of zero is returned as the string <code>"0 but true"</code>; thus
<code>sysseek</code> returns
-true on success and false on failure, yet you can still easily determine
-the new position.
-</p>
-</dd>
-<dt>system LIST</dt>
-<dd><a name="perlfunc-system-LIST"></a>
-</dd>
-<dt>system PROGRAM LIST</dt>
-<dd><a name="perlfunc-system-PROGRAM-LIST"></a>
-<p>Does exactly the same thing as <code>exec LIST</code>, except that a fork is
-done first and the parent process waits for the child process to
-exit. Note that argument processing varies depending on the
-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
-given by the first element of the list with arguments given by the
-rest of the list. If there is only one scalar argument, the argument
-is checked for shell metacharacters, and if there are any, the
-entire argument is passed to the system’s command shell for parsing
-(this is <code>/bin/sh -c</code> on Unix platforms, but varies on other
-platforms). If there are no shell metacharacters in the argument,
-it is split into words and passed directly to <code>execvp</code>, which is
-more efficient. On Windows, only the <code>system PROGRAM LIST</code> syntax
will
-reliably avoid using the shell; <code>system LIST</code>, even with more than
one
-element, will fall back to the shell if the first spawn fails.
-</p>
-<p>Perl will attempt to flush all files opened for
-output before any operation that may do a fork, but this may not be
-supported on some platforms (see <a href="#perlport-NAME">perlport NAME</a>).
To be safe, you may need
-to set <code>$|</code> ($AUTOFLUSH in English) or call the
<code>autoflush()</code> method
-of <code>IO::Handle</code> on any open handles.
-</p>
-<p>The return value is the exit status of the program as returned by the
-<code>wait</code> call. To get the actual exit value, shift right by eight
(see
-below). See also ‘exec’. This is <em>not</em> what you want to
use to capture
-the output from a command; for that you should use merely backticks or
-<code>qx//</code>, as described in <a href="#perlop-_0060STRING_0060">perlop
<code>`<em>STRING</em>`</code></a>. Return value of -1
-indicates a failure to start the program or an error of the wait(2) system
-call (inspect $! for the reason).
-</p>
-<p>If you’d like to make <code>system</code> (and many other bits of
Perl) die on error,
-have a look at the <a href="autodie.html#Top">(autodie)</a> pragma.
-</p>
-<p>Like <code>exec</code>, <code>system</code> allows you to lie to a program
about its name if
-you use the <code>system PROGRAM LIST</code> syntax. Again, see
‘exec’.
-</p>
-<p>Since <code>SIGINT</code> and <code>SIGQUIT</code> are ignored during the
execution of
-<code>system</code>, if you expect your program to terminate on receipt of
these
-signals you will need to arrange to do so yourself based on the return
-value.
-</p>
-<pre class="verbatim"> @args = ("command", "arg1",
"arg2");
- system(@args) == 0
- or die "system @args failed: $?"
-</pre>
-<p>If you’d like to manually inspect <code>system</code>’s
failure, you can check all
-possible failure modes by inspecting <code>$?</code> like this:
-</p>
-<pre class="verbatim"> if ($? == -1) {
- print "failed to execute: $!\n";
- }
- elsif ($? & 127) {
- printf "child died with signal %d, %s coredump\n",
- ($? & 127), ($? & 128) ? 'with' : 'without';
- }
- else {
- printf "child exited with value %d\n", $? >> 8;
- }
-</pre>
-<p>Alternatively, you may inspect the value of
<code>${^CHILD_ERROR_NATIVE}</code>
-with the <code>W*()</code> calls from the POSIX module.
-</p>
-<p>When <code>system</code>’s arguments are executed indirectly by the
shell,
-results and return codes are subject to its quirks.
-See <a href="#perlop-_0060STRING_0060">perlop
<code>`<em>STRING</em>`</code></a> and ‘exec’ for details.
-</p>
-<p>Since <code>system</code> does a <code>fork</code> and <code>wait</code> it
may affect a <code>SIGCHLD</code>
-handler. See <a href="#perlipc-NAME">perlipc NAME</a> for details.
-</p>
-<p>Portability issues: <a href="#perlport-system">perlport system</a>.
-</p>
-</dd>
-<dt>syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET</dt>
-<dd><a
name="perlfunc-syswrite-FILEHANDLE_002cSCALAR_002cLENGTH_002cOFFSET"></a>
-</dd>
-<dt>syswrite FILEHANDLE,SCALAR,LENGTH</dt>
-<dd><a name="perlfunc-syswrite-FILEHANDLE_002cSCALAR_002cLENGTH"></a>
-</dd>
-<dt>syswrite FILEHANDLE,SCALAR</dt>
-<dd><a name="perlfunc-syswrite-FILEHANDLE_002cSCALAR"></a>
-<p>Attempts to write LENGTH bytes of data from variable SCALAR to the
-specified FILEHANDLE, using write(2). If LENGTH is
-not specified, writes whole SCALAR. It bypasses buffered IO, so
-mixing this with reads (other than <code>sysread())</code>,
<code>print</code>, <code>write</code>,
-<code>seek</code>, <code>tell</code>, or <code>eof</code> may cause confusion
because the perlio and
-stdio layers usually buffer data. Returns the number of bytes
-actually written, or <code>undef</code> if there was an error (in this case the
-errno variable <code>$!</code> is also set). If the LENGTH is greater than the
-data available in the SCALAR after the OFFSET, only as much data as is
-available will be written.
-</p>
-<p>An OFFSET may be specified to write the data from some part of the
-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.
-</p>
-<p><strong>WARNING</strong>: If the filehandle is marked <code>:utf8</code>,
Unicode characters
-encoded in UTF-8 are written instead of bytes, and the LENGTH, OFFSET, and
-return value of syswrite() are in (UTF8-encoded Unicode) characters.
-The <code>:encoding(...)</code> layer implicitly introduces the
<code>:utf8</code> 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 ‘binmode’, ‘open’, and the <code>open</code>
pragma, <a href="open.html#Top">(open)</a>.
-</p>
-</dd>
-<dt>tell FILEHANDLE</dt>
-<dd><a name="perlfunc-tell-FILEHANDLE"></a>
-</dd>
-<dt>tell</dt>
-<dd><a name="perlfunc-tell"></a>
-<p>Returns the current position <em>in bytes</em> for FILEHANDLE, or -1 on
-error. FILEHANDLE may be an expression whose value gives the name of
-the actual filehandle. If FILEHANDLE is omitted, assumes the file
-last read.
-</p>
-<p>Note the <em>in bytes</em>: even if the filehandle has been set to
-operate on characters (for example by using the <code>:encoding(utf8)</code>
open
-layer), tell() will return byte offsets, not character offsets (because
-that would render seek() and tell() rather slow).
-</p>
-<p>The return value of tell() for the standard streams like the STDIN
-depends on the operating system: it may return -1 or something else.
-tell() on pipes, fifos, and sockets usually returns -1.
-</p>
-<p>There is no <code>systell</code> function. Use <code>sysseek(FH, 0,
1)</code> for that.
-</p>
-<p>Do not use tell() (or other buffered I/O operations) on a filehandle
-that has been manipulated by sysread(), syswrite(), or sysseek().
-Those functions ignore the buffering, while tell() does not.
-</p>
-</dd>
-<dt>telldir DIRHANDLE</dt>
-<dd><a name="perlfunc-telldir-DIRHANDLE"></a>
-<p>Returns the current position of the <code>readdir</code> routines on
DIRHANDLE.
-Value may be given to <code>seekdir</code> to access a particular location in a
-directory. <code>telldir</code> has the same caveats about possible directory
-compaction as the corresponding system library routine.
-</p>
-</dd>
-<dt>tie VARIABLE,CLASSNAME,LIST</dt>
-<dd><a name="perlfunc-tie-VARIABLE_002cCLASSNAME_002cLIST"></a>
-<p>This function binds a variable to a package class that will provide the
-implementation for the variable. VARIABLE is the name of the variable
-to be enchanted. CLASSNAME is the name of a class implementing objects
-of correct type. Any additional arguments are passed to the
-appropriate constructor
-method of the class (meaning <code>TIESCALAR</code>, <code>TIEHANDLE</code>,
<code>TIEARRAY</code>,
-or <code>TIEHASH</code>). Typically these are arguments such as might be
passed
-to the <code>dbm_open()</code> function of C. The object returned by the
-constructor is also returned by the <code>tie</code> function, which would be
useful
-if you want to access other methods in CLASSNAME.
-</p>
-<p>Note that functions such as <code>keys</code> and <code>values</code> may
return huge lists
-when used on large objects, like DBM files. You may prefer to use the
-<code>each</code> function to iterate over such. Example:
-</p>
-<pre class="verbatim"> # print out history file offsets
- use NDBM_File;
- tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
- while (($key,$val) = each %HIST) {
- print $key, ' = ', unpack('L',$val), "\n";
- }
- untie(%HIST);
-</pre>
-<p>A class implementing a hash should have the following methods:
-</p>
-<pre class="verbatim"> TIEHASH classname, LIST
- FETCH this, key
- STORE this, key, value
- DELETE this, key
- CLEAR this
- EXISTS this, key
- FIRSTKEY this
- NEXTKEY this, lastkey
- SCALAR this
- DESTROY this
- UNTIE this
-</pre>
-<p>A class implementing an ordinary array should have the following methods:
-</p>
-<pre class="verbatim"> TIEARRAY classname, LIST
- FETCH this, key
- STORE this, key, value
- FETCHSIZE this
- STORESIZE this, count
- CLEAR this
- PUSH this, LIST
- POP this
- SHIFT this
- UNSHIFT this, LIST
- SPLICE this, offset, length, LIST
- EXTEND this, count
- DELETE this, key
- EXISTS this, key
- DESTROY this
- UNTIE this
-</pre>
-<p>A class implementing a filehandle should have the following methods:
-</p>
-<pre class="verbatim"> TIEHANDLE classname, LIST
- READ this, scalar, length, offset
- READLINE this
- GETC this
- WRITE this, scalar, length, offset
- PRINT this, LIST
- PRINTF this, format, LIST
- BINMODE this
- EOF this
- FILENO this
- SEEK this, position, whence
- TELL this
- OPEN this, mode, LIST
- CLOSE this
- DESTROY this
- UNTIE this
-</pre>
-<p>A class implementing a scalar should have the following methods:
-</p>
-<pre class="verbatim"> TIESCALAR classname, LIST
- FETCH this,
- STORE this, value
- DESTROY this
- UNTIE this
-</pre>
-<p>Not all methods indicated above need be implemented. See <a
href="#perltie-NAME">perltie NAME</a>,
-<a href="Tie-Hash.html#Top">(Tie-Hash)</a>, <a
href="Tie-Array.html#Top">(Tie-Array)</a>, <a
href="Tie-Scalar.html#Top">(Tie-Scalar)</a>, and <a
href="Tie-Handle.html#Top">(Tie-Handle)</a>.
-</p>
-<p>Unlike <code>dbmopen</code>, the <code>tie</code> function will not
<code>use</code> or <code>require</code> a module
-for you; you need to do that explicitly yourself. See <a
href="DB_File.html#Top">(DB_File)</a>
-or the <samp>Config</samp> module for interesting <code>tie</code>
implementations.
-</p>
-<p>For further details see <a href="#perltie-NAME">perltie NAME</a>, <a
href="#perlfunc-tied-VARIABLE">tied VARIABLE</a>.
-</p>
-</dd>
-<dt>tied VARIABLE</dt>
-<dd><a name="perlfunc-tied-VARIABLE"></a>
-<p>Returns a reference to the object underlying VARIABLE (the same value
-that was originally returned by the <code>tie</code> call that bound the
variable
-to a package.) Returns the undefined value if VARIABLE isn’t tied to a
-package.
-</p>
-</dd>
-<dt>time</dt>
-<dd><a name="perlfunc-time"></a>
-<p>Returns the number of non-leap seconds since whatever time the system
-considers to be the epoch, suitable for feeding to <code>gmtime</code> and
-<code>localtime</code>. 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.
-</p>
-<p>For measuring time in better granularity than one second, use the
-<a href="Time-HiRes.html#Top">(Time-HiRes)</a> module from Perl 5.8 onwards
(or from CPAN before then), or,
-if you have gettimeofday(2), you may be able to use the <code>syscall</code>
-interface of Perl. See <a href="perlfaq8.html#Top">(perlfaq8)</a> for details.
-</p>
-<p>For date and time processing look at the many related modules on CPAN.
-For a comprehensive date and time representation look at the
-<a href="DateTime.html#Top">(DateTime)</a> module.
-</p>
-</dd>
-<dt>times</dt>
-<dd><a name="perlfunc-times"></a>
-<p>Returns a four-element list giving the user and system times in
-seconds for this process and any exited children of this process.
-</p>
-<pre class="verbatim"> ($user,$system,$cuser,$csystem) = times;
-</pre>
-<p>In scalar context, <code>times</code> returns <code>$user</code>.
-</p>
-<p>Children’s times are only included for terminated children.
-</p>
-<p>Portability issues: <a href="#perlport-times">perlport times</a>.
-</p>
-</dd>
-<dt>tr///</dt>
-<dd><a name="perlfunc-tr_002f_002f_002f"></a>
-<p>The transliteration operator. Same as <code>y///</code>. See
-<a href="#perlop-Quote_002dLike-Operators">perlop Quote-Like Operators</a>.
-</p>
-</dd>
-<dt>truncate FILEHANDLE,LENGTH</dt>
-<dd><a name="perlfunc-truncate-FILEHANDLE_002cLENGTH"></a>
-</dd>
-<dt>truncate EXPR,LENGTH</dt>
-<dd><a name="perlfunc-truncate-EXPR_002cLENGTH"></a>
-<p>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, <code>undef</code> on error.
-</p>
-<p>The behavior is undefined if LENGTH is greater than the length of the
-file.
-</p>
-<p>The position in the file of FILEHANDLE is left unchanged. You may want to
-call <a href="#perlfunc-seek-FILEHANDLE_002cPOSITION_002cWHENCE">seek</a>
before writing to the file.
-</p>
-<p>Portability issues: <a href="#perlport-truncate">perlport truncate</a>.
-</p>
-</dd>
-<dt>uc EXPR</dt>
-<dd><a name="perlfunc-uc-EXPR"></a>
-</dd>
-<dt>uc</dt>
-<dd><a name="perlfunc-uc"></a>
-<p>Returns an uppercased version of EXPR. This is the internal function
-implementing the <code>\U</code> escape in double-quoted strings.
-It does not attempt to do titlecase mapping on initial letters. See
-<a href="#perlfunc-ucfirst">ucfirst</a> for that.
-</p>
-<p>If EXPR is omitted, uses <code>$_</code>.
-</p>
-<p>This function behaves the same way under various pragma, such as in a
locale,
-as <a href="#perlfunc-lc">lc</a> does.
-</p>
-</dd>
-<dt>ucfirst EXPR</dt>
-<dd><a name="perlfunc-ucfirst-EXPR"></a>
-</dd>
-<dt>ucfirst</dt>
-<dd><a name="perlfunc-ucfirst"></a>
-<p>Returns the value of EXPR with the first character in uppercase
-(titlecase in Unicode). This is the internal function implementing
-the <code>\u</code> escape in double-quoted strings.
-</p>
-<p>If EXPR is omitted, uses <code>$_</code>.
-</p>
-<p>This function behaves the same way under various pragma, such as in a
locale,
-as <a href="#perlfunc-lc">lc</a> does.
-</p>
-</dd>
-<dt>umask EXPR</dt>
-<dd><a name="perlfunc-umask-EXPR"></a>
-</dd>
-<dt>umask</dt>
-<dd><a name="perlfunc-umask"></a>
-<p>Sets the umask for the process to EXPR and returns the previous value.
-If EXPR is omitted, merely returns the current umask.
-</p>
-<p>The Unix permission <code>rwxr-x---</code> is represented as three sets of
three
-bits, or three octal digits: <code>0750</code> (the leading 0 indicates octal
-and isn’t one of the digits). The <code>umask</code> value is such a
number
-representing disabled permissions bits. The permission (or "mode")
-values you pass <code>mkdir</code> or <code>sysopen</code> are modified by
your umask, so
-even if you tell <code>sysopen</code> to create a file with permissions
<code>0777</code>,
-if your umask is <code>0022</code>, then the file will actually be created with
-permissions <code>0755</code>. If your <code>umask</code> were
<code>0027</code> (group can’t
-write; others can’t read, write, or execute), then passing
-<code>sysopen</code> <code>0666</code> would create a file with mode
<code>0640</code> (because
-<code>0666 &~ 027</code> is <code>0640</code>).
-</p>
-<p>Here’s some advice: supply a creation mode of <code>0666</code> for
regular
-files (in <code>sysopen</code>) and one of <code>0777</code> for directories
(in
-<code>mkdir</code>) and executable files. This gives users the freedom of
-choice: if they want protected files, they might choose process umasks
-of <code>022</code>, <code>027</code>, or even the particularly antisocial
mask of <code>077</code>.
-Programs should rarely if ever make policy decisions better left to
-the user. The exception to this is when writing files that should be
-kept private: mail files, web browser cookies, <em>.rhosts</em> files, and
-so on.
-</p>
-<p>If umask(2) is not implemented on your system and you are trying to
-restrict access for <em>yourself</em> (i.e., <code>(EXPR & 0700) >
0</code>),
-raises an exception. If umask(2) is not implemented and you are
-not trying to restrict access for yourself, returns <code>undef</code>.
-</p>
-<p>Remember that a umask is a number, usually given in octal; it is
<em>not</em> a
-string of octal digits. See also <a href="#perlfunc-oct">oct</a>, if all you
have is a string.
-</p>
-<p>Portability issues: <a href="#perlport-umask">perlport umask</a>.
-</p>
-</dd>
-<dt>undef EXPR</dt>
-<dd><a name="perlfunc-undef-EXPR"></a>
-</dd>
-<dt>undef</dt>
-<dd><a name="perlfunc-undef"></a>
-<p>Undefines the value of EXPR, which must be an lvalue. Use only on a
-scalar value, an array (using <code>@</code>), a hash (using <code>%</code>),
a subroutine
-(using <code>&</code>), or a typeglob (using <code>*</code>). Saying
<code>undef $hash{$key}</code>
-will probably not do what you expect on most predefined variables or
-DBM list values, so don’t do that; see ‘delete’. Always
returns the
-undefined value. You can omit the EXPR, in which case nothing is
-undefined, but you still get an undefined value that you could, for
-instance, return from a subroutine, assign to a variable, or pass as a
-parameter. Examples:
-</p>
-<pre class="verbatim"> undef $foo;
- undef $bar{'blurfl'}; # Compare to: delete $bar{'blurfl'};
- undef @ary;
- undef %hash;
- undef &mysub;
- undef *xyz; # destroys $xyz, @xyz, %xyz, &xyz, etc.
- return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
- select undef, undef, undef, 0.25;
- ($a, $b, undef, $c) = &foo; # Ignore third value returned
-</pre>
-<p>Note that this is a unary operator, not a list operator.
-</p>
-</dd>
-<dt>unlink LIST</dt>
-<dd><a name="perlfunc-unlink-LIST"></a>
-</dd>
-<dt>unlink</dt>
-<dd><a name="perlfunc-unlink"></a>
-<p>Deletes a list of files. On success, it returns the number of files
-it successfully deleted. On failure, it returns false and sets <code>$!</code>
-(errno):
-</p>
-<pre class="verbatim"> my $unlinked = unlink 'a', 'b', 'c';
- unlink @goners;
- unlink glob "*.bak";
-</pre>
-<p>On error, <code>unlink</code> will not tell you which files it could not
remove.
-If you want to know which files you could not remove, try them one
-at a time:
-</p>
-<pre class="verbatim"> foreach my $file ( @goners ) {
- unlink $file or warn "Could not unlink $file: $!";
- }
-</pre>
-<p>Note: <code>unlink</code> will not attempt to delete directories unless you
are
-superuser and the <strong>-U</strong> flag is supplied to Perl. Even if these
-conditions are met, be warned that unlinking a directory can inflict
-damage on your filesystem. Finally, using <code>unlink</code> on directories
is
-not supported on many operating systems. Use <code>rmdir</code> instead.
-</p>
-<p>If LIST is omitted, <code>unlink</code> uses <code>$_</code>.
-</p>
-</dd>
-<dt>unpack TEMPLATE,EXPR</dt>
-<dd><a name="perlfunc-unpack-TEMPLATE_002cEXPR"></a>
-</dd>
-<dt>unpack TEMPLATE</dt>
-<dd><a name="perlfunc-unpack-TEMPLATE"></a>
-<p><code>unpack</code> does the reverse of <code>pack</code>: it takes a string
-and expands it out into a list of values.
-(In scalar context, it returns merely the first value produced.)
-</p>
-<p>If EXPR is omitted, unpacks the <code>$_</code> string.
-See <a href="#perlpacktut-NAME">perlpacktut NAME</a> for an introduction to
this function.
-</p>
-<p>The string is broken into chunks described by the TEMPLATE. Each chunk
-is converted separately to a value. Typically, either the string is a result
-of <code>pack</code>, or the characters of the string represent a C structure
of some
-kind.
-</p>
-<p>The TEMPLATE has the same format as in the <code>pack</code> function.
-Here’s a subroutine that does substring:
-</p>
-<pre class="verbatim"> sub substr {
- my($what,$where,$howmuch) = @_;
- unpack("x$where a$howmuch", $what);
- }
-</pre>
-<p>and then there’s
-</p>
-<pre class="verbatim"> sub ordinal { unpack("W",$_[0]); } # same
as ord()
-</pre>
-<p>In addition to fields allowed in pack(), you may prefix a field with
-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
-<code>ord($char)</code> is taken; for bit fields the sum of zeroes and ones).
-</p>
-<p>For example, the following
-computes the same number as the System V sum program:
-</p>
-<pre class="verbatim"> $checksum = do {
- local $/; # slurp!
- unpack("%32W*",<>) % 65535;
- };
-</pre>
-<p>The following efficiently counts the number of set bits in a bit vector:
-</p>
-<pre class="verbatim"> $setbits = unpack("%32b*", $selectmask);
-</pre>
-<p>The <code>p</code> and <code>P</code> formats should be used with care.
Since Perl
-has no way of checking whether the value passed to <code>unpack()</code>
-corresponds to a valid memory location, passing a pointer value that’s
-not known to be valid is likely to have disastrous consequences.
-</p>
-<p>If there are more pack codes or if the repeat count of a field or a group
-is larger than what the remainder of the input string allows, the result
-is not well defined: the repeat count may be decreased, or
-<code>unpack()</code> may produce empty strings or zeros, or it may raise an
exception.
-If the input string is longer than one described by the TEMPLATE,
-the remainder of that input string is ignored.
-</p>
-<p>See ‘pack’ for more examples and notes.
-</p>
-</dd>
-<dt>unshift ARRAY,LIST</dt>
-<dd><a name="perlfunc-unshift-ARRAY_002cLIST"></a>
-</dd>
-<dt>unshift EXPR,LIST</dt>
-<dd><a name="perlfunc-unshift-EXPR_002cLIST"></a>
-<p>Does the opposite of a <code>shift</code>. Or the opposite of a
<code>push</code>,
-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.
-</p>
-<pre class="verbatim"> unshift(@ARGV, '-e') unless $ARGV[0] =~ /^-/;
-</pre>
-<p>Note the LIST is prepended whole, not one element at a time, so the
-prepended elements stay in the same order. Use <code>reverse</code> to do the
-reverse.
-</p>
-<p>Starting with Perl 5.14, <code>unshift</code> can take a scalar EXPR, which
must hold
-a reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of <code>unshift</code> is considered highly
-experimental. The exact behaviour may change in a future version of Perl.
-</p>
-<p>To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work <em>only</em> on Perls
of
-a recent vintage:
-</p>
-<pre class="verbatim"> use 5.014; # so push/pop/etc work on scalars
(experimental)
-</pre>
-</dd>
-<dt>untie VARIABLE</dt>
-<dd><a name="perlfunc-untie-VARIABLE"></a>
-<p>Breaks the binding between a variable and a package.
-(See <a href="#perlfunc-tie-VARIABLE_002cCLASSNAME_002cLIST">tie</a>.)
-Has no effect if the variable is not tied.
-</p>
-</dd>
-<dt>use Module VERSION LIST</dt>
-<dd><a name="perlfunc-use-Module-VERSION-LIST"></a>
-</dd>
-<dt>use Module VERSION</dt>
-<dd><a name="perlfunc-use-Module-VERSION"></a>
-</dd>
-<dt>use Module LIST</dt>
-<dd><a name="perlfunc-use-Module-LIST"></a>
-</dd>
-<dt>use Module</dt>
-<dd><a name="perlfunc-use-Module"></a>
-</dd>
-<dt>use VERSION</dt>
-<dd><a name="perlfunc-use-VERSION"></a>
-<p>Imports some semantics into the current package from the named module,
-generally by aliasing certain subroutine or variable names into your
-package. It is exactly equivalent to
-</p>
-<pre class="verbatim"> BEGIN { require Module; Module->import( LIST ); }
-</pre>
-<p>except that Module <em>must</em> be a bareword.
-The importation can be made conditional by using the <a
href="if.html#Top">(if)</a> module.
-</p>
-<p>In the peculiar <code>use VERSION</code> form, VERSION may be either a
positive
-decimal fraction such as 5.006, which will be compared to <code>$]</code>, or
a v-string
-of the form v5.6.1, which will be compared to <code>$^V</code> (aka
$PERL_VERSION). An
-exception is raised if VERSION is greater than the version of the
-current Perl interpreter; Perl will not attempt to parse the rest of the
-file. Compare with <a href="#perlfunc-require">require</a>, which can do a
similar check at run time.
-Symmetrically, <code>no VERSION</code> allows you to specify that you want a
version
-of Perl older than the specified one.
-</p>
-<p>Specifying VERSION as a literal of the form v5.6.1 should generally be
-avoided, because it leads to misleading error messages under earlier
-versions of Perl (that is, prior to 5.6.0) that do not support this
-syntax. The equivalent numeric version should be used instead.
-</p>
-<pre class="verbatim"> use v5.6.1; # compile time version check
- use 5.6.1; # ditto
- use 5.006_001; # ditto; preferred for backwards compatibility
-</pre>
-<p>This is often useful if you need to check the current Perl version before
-<code>use</code>ing library modules that won’t work with older versions
of Perl.
-(We try not to do this more than we have to.)
-</p>
-<p><code>use VERSION</code> also lexically enables all features available in
the requested
-version as defined by the <code>feature</code> pragma, disabling any features
-not in the requested version’s feature bundle. See <a
href="feature.html#Top">(feature)</a>.
-Similarly, if the specified Perl version is greater than or equal to
-5.12.0, strictures are enabled lexically as
-with <code>use strict</code>. Any explicit use of
-<code>use strict</code> or <code>no strict</code> overrides <code>use
VERSION</code>, even if it comes
-before it. Later use of <code>use VERSION</code>
-will override all behavior of a previous
-<code>use VERSION</code>, possibly removing the <code>strict</code> and
<code>feature</code> added by
-<code>use VERSION</code>. <code>use VERSION</code> does not
-load the <samp>feature.pm</samp> or <samp>strict.pm</samp>
-files.
-</p>
-<p>The <code>BEGIN</code> forces the <code>require</code> and
<code>import</code> to happen at compile time. The
-<code>require</code> makes sure the module is loaded into memory if it
hasn’t been
-yet. The <code>import</code> is not a builtin; it’s just an ordinary
static method
-call into the <code>Module</code> package to tell the module to import the
list of
-features back into the current package. The module can implement its
-<code>import</code> method any way it likes, though most modules just choose to
-derive their <code>import</code> method via inheritance from the
<code>Exporter</code> class that
-is defined in the <code>Exporter</code> module. See <a
href="Exporter.html#Top">(Exporter)</a>. If no <code>import</code>
-method can be found then the call is skipped, even if there is an AUTOLOAD
-method.
-</p>
-<p>If you do not want to call the package’s <code>import</code> method
(for instance,
-to stop your namespace from being altered), explicitly supply the empty list:
-</p>
-<pre class="verbatim"> use Module ();
-</pre>
-<p>That is exactly equivalent to
-</p>
-<pre class="verbatim"> BEGIN { require Module }
-</pre>
-<p>If the VERSION argument is present between Module and LIST, then the
-<code>use</code> will call the VERSION method in class Module with the given
-version as an argument. The default VERSION method, inherited from
-the UNIVERSAL class, croaks if the given version is larger than the
-value of the variable <code>$Module::VERSION</code>.
-</p>
-<p>Again, there is a distinction between omitting LIST (<code>import</code>
called
-with no arguments) and an explicit empty LIST <code>()</code>
(<code>import</code> not
-called). Note that there is no comma after VERSION!
-</p>
-<p>Because this is a wide-open interface, pragmas (compiler directives)
-are also implemented this way. Currently implemented pragmas are:
-</p>
-<pre class="verbatim"> use constant;
- use diagnostics;
- use integer;
- use sigtrap qw(SEGV BUS);
- use strict qw(subs vars refs);
- use subs qw(afunc blurfl);
- use warnings qw(all);
- use sort qw(stable _quicksort _mergesort);
-</pre>
-<p>Some of these pseudo-modules import semantics into the current
-block scope (like <code>strict</code> or <code>integer</code>, unlike ordinary
modules,
-which import symbols into the current package (which are effective
-through the end of the file).
-</p>
-<p>Because <code>use</code> takes effect at compile time, it doesn’t
respect the
-ordinary flow control of the code being compiled. In particular, putting
-a <code>use</code> inside the false branch of a conditional doesn’t
prevent it
-from being processed. If a module or pragma only needs to be loaded
-conditionally, this can be done using the <a href="if.html#Top">(if)</a>
pragma:
-</p>
-<pre class="verbatim"> use if $] < 5.008, "utf8";
- use if WANT_WARNINGS, warnings => qw(all);
-</pre>
-<p>There’s a corresponding <code>no</code> declaration that unimports
meanings imported
-by <code>use</code>, i.e., it calls <code>unimport Module LIST</code> instead
of <code>import</code>.
-It behaves just as <code>import</code> does with VERSION, an omitted or empty
LIST,
-or no unimport method being found.
-</p>
-<pre class="verbatim"> no integer;
- no strict 'refs';
- no warnings;
-</pre>
-<p>Care should be taken when using the <code>no VERSION</code> form of
<code>no</code>. It is
-<em>only</em> meant to be used to assert that the running Perl is of a earlier
-version than its argument and <em>not</em> to undo the feature-enabling side
effects
-of <code>use VERSION</code>.
-</p>
-<p>See <a href="perlmodlib.html#Top">(perlmodlib)</a> for a list of standard
modules and pragmas. See <a href="#perlrun-NAME">perlrun NAME</a>
-for the <code>-M</code> and <code>-m</code> command-line options to Perl that
give <code>use</code>
-functionality from the command-line.
-</p>
-</dd>
-<dt>utime LIST</dt>
-<dd><a name="perlfunc-utime-LIST"></a>
-<p>Changes the access and modification times on each file of a list of
-files. The first two elements of the list must be the NUMERIC access
-and modification times, in that order. Returns the number of files
-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
-Unix touch(1) command when the files <em>already exist</em> and belong to
-the user running the program:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
- $atime = $mtime = time;
- utime $atime, $mtime, @ARGV;
-</pre>
-<p>Since Perl 5.8.0, if the first two elements of the list are
<code>undef</code>,
-the utime(2) syscall from your C library is called with a null second
-argument. On most systems, this will set the file’s access and
-modification times to the current time (i.e., equivalent to the example
-above) and will work even on files you don’t own provided you have write
-permission:
-</p>
-<pre class="verbatim"> for $file (@ARGV) {
- utime(undef, undef, $file)
- || warn "couldn't touch $file: $!";
- }
-</pre>
-<p>Under NFS this will use the time of the NFS server, not the time of
-the local machine. If there is a time synchronization problem, the
-NFS server and local machine will have different times. The Unix
-touch(1) command will in fact normally use this form instead of the
-one shown in the first example.
-</p>
-<p>Passing only one of the first two elements as <code>undef</code> is
-equivalent to passing a 0 and will not have the effect
-described when both are <code>undef</code>. This also triggers an
-uninitialized warning.
-</p>
-<p>On systems that support futimes(2), you may pass filehandles among the
-files. On systems that don’t support futimes(2), passing filehandles
raises
-an exception. Filehandles must be passed as globs or glob references to be
-recognized; barewords are considered filenames.
-</p>
-<p>Portability issues: <a href="#perlport-utime">perlport utime</a>.
-</p>
-</dd>
-<dt>values HASH</dt>
-<dd><a name="perlfunc-values-HASH"></a>
-</dd>
-<dt>values ARRAY</dt>
-<dd><a name="perlfunc-values-ARRAY"></a>
-</dd>
-<dt>values EXPR</dt>
-<dd><a name="perlfunc-values-EXPR"></a>
-<p>In list context, returns a list consisting of all the values of the named
-hash. In Perl 5.12 or later only, will also return a list of the values of
-an array; prior to that release, attempting to use an array argument will
-produce a syntax error. In scalar context, returns the number of values.
-</p>
-<p>Hash entries are returned in an apparently random order. The actual random
-order is specific to a given hash; the exact same series of operations
-on two hashes may result in a different order for each hash. Any insertion
-into the hash may change the order, as will any deletion, with the exception
-that the most recent key returned by <code>each</code> or <code>keys</code>
may be deleted
-without changing the order. So long as a given hash is unmodified you may
-rely on <code>keys</code>, <code>values</code> and <code>each</code> to
repeatedly return the same order
-as each other. See <a href="#perlsec-Algorithmic-Complexity-Attacks">perlsec
Algorithmic Complexity Attacks</a> for
-details on why hash order is randomized. Aside from the guarantees
-provided here the exact details of Perl’s hash algorithm and the hash
-traversal order are subject to change in any release of Perl. Tied hashes
-may behave differently to Perl’s hashes with respect to changes in order
on
-insertion and deletion of items.
-</p>
-<p>As a side effect, calling values() resets the HASH or ARRAY’s internal
-iterator, see ‘each’. (In particular, calling values() in void
context
-resets the iterator with no other overhead. Apart from resetting the
-iterator, <code>values @array</code> in list context is the same as plain
<code>@array</code>.
-(We recommend that you use void context <code>keys @array</code> for this, but
-reasoned that taking <code>values @array</code> out would require more
-documentation than leaving it in.)
-</p>
-<p>Note that the values are not copied, which means modifying them will
-modify the contents of the hash:
-</p>
-<pre class="verbatim"> for (values %hash) { s/foo/bar/g } # modifies
%hash values
- for (@hash{keys %hash}) { s/foo/bar/g } # same
-</pre>
-<p>Starting with Perl 5.14, <code>values</code> 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 <code>values</code> is considered
highly
-experimental. The exact behaviour may change in a future version of Perl.
-</p>
-<pre class="verbatim"> for (values $hashref) { ... }
- for (values $obj->get_arrayref) { ... }
-</pre>
-<p>To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work <em>only</em> on Perls
of
-a recent vintage:
-</p>
-<pre class="verbatim"> use 5.012; # so keys/values/each work on arrays
- use 5.014; # so keys/values/each work on scalars (experimental)
-</pre>
-<p>See also <code>keys</code>, <code>each</code>, and <code>sort</code>.
-</p>
-</dd>
-<dt>vec EXPR,OFFSET,BITS</dt>
-<dd><a name="perlfunc-vec-EXPR_002cOFFSET_002cBITS"></a>
-<p>Treats the string in EXPR as a bit vector made up of elements of
-width BITS and returns the value of the element specified by OFFSET
-as an unsigned integer. BITS therefore specifies the number of bits
-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
-that).
-</p>
-<p>If BITS is 8, "elements" coincide with bytes of the input string.
-</p>
-<p>If BITS is 16 or more, bytes of the input string are grouped into chunks
-of size BITS/8, and each group is converted to a number as with
-pack()/unpack() with big-endian formats <code>n</code>/<code>N</code> (and
analogously
-for BITS==64). See ‘pack’ for details.
-</p>
-<p>If bits is 4 or less, the string is broken into bytes, then the bits
-of each byte are broken into 8/BITS groups. Bits of a byte are
-numbered in a little-endian-ish way, as in <code>0x01</code>,
<code>0x02</code>,
-<code>0x04</code>, <code>0x08</code>, <code>0x10</code>, <code>0x20</code>,
<code>0x40</code>, <code>0x80</code>. For example,
-breaking the single input byte <code>chr(0x36)</code> into two groups gives a
list
-<code>(0x6, 0x3)</code>; breaking it into 4 groups gives <code>(0x2, 0x1, 0x3,
0x0)</code>.
-</p>
-<p><code>vec</code> may also be assigned to, in which case parentheses are
needed
-to give the expression the correct precedence as in
-</p>
-<pre class="verbatim"> vec($image, $max_x * $x + $y, 8) = 3;
-</pre>
-<p>If the selected element is outside the string, the value 0 is returned.
-If an element off the end of the string is written to, Perl will first
-extend the string with sufficiently many zero bytes. It is an error
-to try to write off the beginning of the string (i.e., negative OFFSET).
-</p>
-<p>If the string happens to be encoded as UTF-8 internally (and thus has
-the UTF8 flag set), this is ignored by <code>vec</code>, and it operates on the
-internal byte string, not the conceptual character string, even if you
-only have characters with values less than 256.
-</p>
-<p>Strings created with <code>vec</code> can also be manipulated with the
logical
-operators <code>|</code>, <code>&</code>, <code>^</code>, and
<code>~</code>. These operators will assume a bit
-vector operation is desired when both operands are strings.
-See <a href="#perlop-Bitwise-String-Operators">perlop Bitwise String
Operators</a>.
-</p>
-<p>The following code will build up an ASCII string saying
<code>'PerlPerlPerl'</code>.
-The comments show the string after each step. Note that this code works
-in the same way on big-endian or little-endian machines.
-</p>
-<pre class="verbatim"> my $foo = '';
- vec($foo, 0, 32) = 0x5065726C; # 'Perl'
-
- # $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits
- print vec($foo, 0, 8); # prints 80 == 0x50 == ord('P')
-
- vec($foo, 2, 16) = 0x5065; # 'PerlPe'
- vec($foo, 3, 16) = 0x726C; # 'PerlPerl'
- vec($foo, 8, 8) = 0x50; # 'PerlPerlP'
- vec($foo, 9, 8) = 0x65; # 'PerlPerlPe'
- vec($foo, 20, 4) = 2; # 'PerlPerlPe' . "\x02"
- vec($foo, 21, 4) = 7; # 'PerlPerlPer'
- # 'r' is "\x72"
- vec($foo, 45, 2) = 3; # 'PerlPerlPer' . "\x0c"
- vec($foo, 93, 1) = 1; # 'PerlPerlPer' . "\x2c"
- vec($foo, 94, 1) = 1; # 'PerlPerlPerl'
- # 'l' is "\x6c"
-</pre>
-<p>To transform a bit vector into a string or list of 0’s and 1’s,
use these:
-</p>
-<pre class="verbatim"> $bits = unpack("b*", $vector);
- @bits = split(//, unpack("b*", $vector));
-</pre>
-<p>If you know the exact length in bits, it can be used in place of the
<code>*</code>.
-</p>
-<p>Here is an example to illustrate how the bits actually fall in place:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -wl
-
- print <<'EOT';
- 0 1 2 3
- unpack("V",$_) 01234567890123456789012345678901
- ------------------------------------------------------------------
- EOT
-
- for $w (0..3) {
- $width = 2**$w;
- for ($shift=0; $shift < $width; ++$shift) {
- for ($off=0; $off < 32/$width; ++$off) {
- $str = pack("B*", "0"x32);
- $bits = (1<<$shift);
- vec($str, $off, $width) = $bits;
- $res = unpack("b*",$str);
- $val = unpack("V", $str);
- write;
- }
- }
- }
-
- format STDOUT =
- vec($_,@#,@#) = @<< == @#########
@>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
- $off, $width, $bits, $val, $res
- .
- __END__
-</pre>
-<p>Regardless of the machine architecture on which it runs, the
-example above should print the following table:
-</p>
-<pre class="verbatim"> 0 1
2 3
- unpack("V",$_) 01234567890123456789012345678901
- ------------------------------------------------------------------
- vec($_, 0, 1) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 1) = 1 == 2 01000000000000000000000000000000
- vec($_, 2, 1) = 1 == 4 00100000000000000000000000000000
- vec($_, 3, 1) = 1 == 8 00010000000000000000000000000000
- vec($_, 4, 1) = 1 == 16 00001000000000000000000000000000
- vec($_, 5, 1) = 1 == 32 00000100000000000000000000000000
- vec($_, 6, 1) = 1 == 64 00000010000000000000000000000000
- vec($_, 7, 1) = 1 == 128 00000001000000000000000000000000
- vec($_, 8, 1) = 1 == 256 00000000100000000000000000000000
- vec($_, 9, 1) = 1 == 512 00000000010000000000000000000000
- vec($_,10, 1) = 1 == 1024 00000000001000000000000000000000
- vec($_,11, 1) = 1 == 2048 00000000000100000000000000000000
- vec($_,12, 1) = 1 == 4096 00000000000010000000000000000000
- vec($_,13, 1) = 1 == 8192 00000000000001000000000000000000
- vec($_,14, 1) = 1 == 16384 00000000000000100000000000000000
- vec($_,15, 1) = 1 == 32768 00000000000000010000000000000000
- vec($_,16, 1) = 1 == 65536 00000000000000001000000000000000
- vec($_,17, 1) = 1 == 131072 00000000000000000100000000000000
- vec($_,18, 1) = 1 == 262144 00000000000000000010000000000000
- vec($_,19, 1) = 1 == 524288 00000000000000000001000000000000
- vec($_,20, 1) = 1 == 1048576 00000000000000000000100000000000
- vec($_,21, 1) = 1 == 2097152 00000000000000000000010000000000
- vec($_,22, 1) = 1 == 4194304 00000000000000000000001000000000
- vec($_,23, 1) = 1 == 8388608 00000000000000000000000100000000
- vec($_,24, 1) = 1 == 16777216 00000000000000000000000010000000
- vec($_,25, 1) = 1 == 33554432 00000000000000000000000001000000
- vec($_,26, 1) = 1 == 67108864 00000000000000000000000000100000
- vec($_,27, 1) = 1 == 134217728 00000000000000000000000000010000
- vec($_,28, 1) = 1 == 268435456 00000000000000000000000000001000
- vec($_,29, 1) = 1 == 536870912 00000000000000000000000000000100
- vec($_,30, 1) = 1 == 1073741824 00000000000000000000000000000010
- vec($_,31, 1) = 1 == 2147483648 00000000000000000000000000000001
- vec($_, 0, 2) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 2) = 1 == 4 00100000000000000000000000000000
- vec($_, 2, 2) = 1 == 16 00001000000000000000000000000000
- vec($_, 3, 2) = 1 == 64 00000010000000000000000000000000
- vec($_, 4, 2) = 1 == 256 00000000100000000000000000000000
- vec($_, 5, 2) = 1 == 1024 00000000001000000000000000000000
- vec($_, 6, 2) = 1 == 4096 00000000000010000000000000000000
- vec($_, 7, 2) = 1 == 16384 00000000000000100000000000000000
- vec($_, 8, 2) = 1 == 65536 00000000000000001000000000000000
- vec($_, 9, 2) = 1 == 262144 00000000000000000010000000000000
- vec($_,10, 2) = 1 == 1048576 00000000000000000000100000000000
- vec($_,11, 2) = 1 == 4194304 00000000000000000000001000000000
- vec($_,12, 2) = 1 == 16777216 00000000000000000000000010000000
- vec($_,13, 2) = 1 == 67108864 00000000000000000000000000100000
- vec($_,14, 2) = 1 == 268435456 00000000000000000000000000001000
- vec($_,15, 2) = 1 == 1073741824 00000000000000000000000000000010
- vec($_, 0, 2) = 2 == 2 01000000000000000000000000000000
- vec($_, 1, 2) = 2 == 8 00010000000000000000000000000000
- vec($_, 2, 2) = 2 == 32 00000100000000000000000000000000
- vec($_, 3, 2) = 2 == 128 00000001000000000000000000000000
- vec($_, 4, 2) = 2 == 512 00000000010000000000000000000000
- vec($_, 5, 2) = 2 == 2048 00000000000100000000000000000000
- vec($_, 6, 2) = 2 == 8192 00000000000001000000000000000000
- vec($_, 7, 2) = 2 == 32768 00000000000000010000000000000000
- vec($_, 8, 2) = 2 == 131072 00000000000000000100000000000000
- vec($_, 9, 2) = 2 == 524288 00000000000000000001000000000000
- vec($_,10, 2) = 2 == 2097152 00000000000000000000010000000000
- vec($_,11, 2) = 2 == 8388608 00000000000000000000000100000000
- vec($_,12, 2) = 2 == 33554432 00000000000000000000000001000000
- vec($_,13, 2) = 2 == 134217728 00000000000000000000000000010000
- vec($_,14, 2) = 2 == 536870912 00000000000000000000000000000100
- vec($_,15, 2) = 2 == 2147483648 00000000000000000000000000000001
- vec($_, 0, 4) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 4) = 1 == 16 00001000000000000000000000000000
- vec($_, 2, 4) = 1 == 256 00000000100000000000000000000000
- vec($_, 3, 4) = 1 == 4096 00000000000010000000000000000000
- vec($_, 4, 4) = 1 == 65536 00000000000000001000000000000000
- vec($_, 5, 4) = 1 == 1048576 00000000000000000000100000000000
- vec($_, 6, 4) = 1 == 16777216 00000000000000000000000010000000
- vec($_, 7, 4) = 1 == 268435456 00000000000000000000000000001000
- vec($_, 0, 4) = 2 == 2 01000000000000000000000000000000
- vec($_, 1, 4) = 2 == 32 00000100000000000000000000000000
- vec($_, 2, 4) = 2 == 512 00000000010000000000000000000000
- vec($_, 3, 4) = 2 == 8192 00000000000001000000000000000000
- vec($_, 4, 4) = 2 == 131072 00000000000000000100000000000000
- vec($_, 5, 4) = 2 == 2097152 00000000000000000000010000000000
- vec($_, 6, 4) = 2 == 33554432 00000000000000000000000001000000
- vec($_, 7, 4) = 2 == 536870912 00000000000000000000000000000100
- vec($_, 0, 4) = 4 == 4 00100000000000000000000000000000
- vec($_, 1, 4) = 4 == 64 00000010000000000000000000000000
- vec($_, 2, 4) = 4 == 1024 00000000001000000000000000000000
- vec($_, 3, 4) = 4 == 16384 00000000000000100000000000000000
- vec($_, 4, 4) = 4 == 262144 00000000000000000010000000000000
- vec($_, 5, 4) = 4 == 4194304 00000000000000000000001000000000
- vec($_, 6, 4) = 4 == 67108864 00000000000000000000000000100000
- vec($_, 7, 4) = 4 == 1073741824 00000000000000000000000000000010
- vec($_, 0, 4) = 8 == 8 00010000000000000000000000000000
- vec($_, 1, 4) = 8 == 128 00000001000000000000000000000000
- vec($_, 2, 4) = 8 == 2048 00000000000100000000000000000000
- vec($_, 3, 4) = 8 == 32768 00000000000000010000000000000000
- vec($_, 4, 4) = 8 == 524288 00000000000000000001000000000000
- vec($_, 5, 4) = 8 == 8388608 00000000000000000000000100000000
- vec($_, 6, 4) = 8 == 134217728 00000000000000000000000000010000
- vec($_, 7, 4) = 8 == 2147483648 00000000000000000000000000000001
- vec($_, 0, 8) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 8) = 1 == 256 00000000100000000000000000000000
- vec($_, 2, 8) = 1 == 65536 00000000000000001000000000000000
- vec($_, 3, 8) = 1 == 16777216 00000000000000000000000010000000
- vec($_, 0, 8) = 2 == 2 01000000000000000000000000000000
- vec($_, 1, 8) = 2 == 512 00000000010000000000000000000000
- vec($_, 2, 8) = 2 == 131072 00000000000000000100000000000000
- vec($_, 3, 8) = 2 == 33554432 00000000000000000000000001000000
- vec($_, 0, 8) = 4 == 4 00100000000000000000000000000000
- vec($_, 1, 8) = 4 == 1024 00000000001000000000000000000000
- vec($_, 2, 8) = 4 == 262144 00000000000000000010000000000000
- vec($_, 3, 8) = 4 == 67108864 00000000000000000000000000100000
- vec($_, 0, 8) = 8 == 8 00010000000000000000000000000000
- vec($_, 1, 8) = 8 == 2048 00000000000100000000000000000000
- vec($_, 2, 8) = 8 == 524288 00000000000000000001000000000000
- vec($_, 3, 8) = 8 == 134217728 00000000000000000000000000010000
- vec($_, 0, 8) = 16 == 16 00001000000000000000000000000000
- vec($_, 1, 8) = 16 == 4096 00000000000010000000000000000000
- vec($_, 2, 8) = 16 == 1048576 00000000000000000000100000000000
- vec($_, 3, 8) = 16 == 268435456 00000000000000000000000000001000
- vec($_, 0, 8) = 32 == 32 00000100000000000000000000000000
- vec($_, 1, 8) = 32 == 8192 00000000000001000000000000000000
- vec($_, 2, 8) = 32 == 2097152 00000000000000000000010000000000
- vec($_, 3, 8) = 32 == 536870912 00000000000000000000000000000100
- vec($_, 0, 8) = 64 == 64 00000010000000000000000000000000
- vec($_, 1, 8) = 64 == 16384 00000000000000100000000000000000
- vec($_, 2, 8) = 64 == 4194304 00000000000000000000001000000000
- vec($_, 3, 8) = 64 == 1073741824 00000000000000000000000000000010
- vec($_, 0, 8) = 128 == 128 00000001000000000000000000000000
- vec($_, 1, 8) = 128 == 32768 00000000000000010000000000000000
- vec($_, 2, 8) = 128 == 8388608 00000000000000000000000100000000
- vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
-</pre>
-</dd>
-<dt>wait</dt>
-<dd><a name="perlfunc-wait"></a>
-<p>Behaves like wait(2) on your system: it waits for a child
-process to terminate and returns the pid of the deceased process, or
-<code>-1</code> if there are no child processes. The status is returned in
<code>$?</code>
-and <code>${^CHILD_ERROR_NATIVE}</code>.
-Note that a return value of <code>-1</code> could mean that child processes are
-being automatically reaped, as described in <a href="#perlipc-NAME">perlipc
NAME</a>.
-</p>
-<p>If you use <code>wait</code> in your handler for $SIG{CHLD}, it may
accidentally wait
-for the child created by qx() or system(). See <a
href="#perlipc-NAME">perlipc NAME</a> for details.
-</p>
-<p>Portability issues: <a href="#perlport-wait">perlport wait</a>.
-</p>
-</dd>
-<dt>waitpid PID,FLAGS</dt>
-<dd><a name="perlfunc-waitpid-PID_002cFLAGS"></a>
-<p>Waits for a particular child process to terminate and returns the pid of
-the deceased process, or <code>-1</code> if there is no such child process.
On some
-systems, a value of 0 indicates that there are processes still running.
-The status is returned in <code>$?</code> and
<code>${^CHILD_ERROR_NATIVE}</code>. If you say
-</p>
-<pre class="verbatim"> use POSIX ":sys_wait_h";
- #...
- do {
- $kid = waitpid(-1, WNOHANG);
- } while $kid > 0;
-</pre>
-<p>then you can do a non-blocking wait for all pending zombie processes.
-Non-blocking wait is available on machines supporting either the
-waitpid(2) or wait4(2) syscalls. However, waiting for a particular
-pid with FLAGS of <code>0</code> is implemented everywhere. (Perl emulates the
-system call by remembering the status values of processes that have
-exited but have not been harvested by the Perl script yet.)
-</p>
-<p>Note that on some systems, a return value of <code>-1</code> could mean
that child
-processes are being automatically reaped. See <a href="#perlipc-NAME">perlipc
NAME</a> for details,
-and for other examples.
-</p>
-<p>Portability issues: <a href="#perlport-waitpid">perlport waitpid</a>.
-</p>
-</dd>
-<dt>wantarray</dt>
-<dd><a name="perlfunc-wantarray"></a>
-<p>Returns true if the context of the currently executing subroutine or
-<code>eval</code> is looking for a list value. Returns false if the context is
-looking for a scalar. Returns the undefined value if the context is
-looking for no value (void context).
-</p>
-<pre class="verbatim"> return unless defined wantarray; # don't bother
doing more
- my @a = complex_calculation();
- return wantarray ? @a : "@a";
-</pre>
-<p><code>wantarray()</code>’s result is unspecified in the top level of
a file,
-in a <code>BEGIN</code>, <code>UNITCHECK</code>, <code>CHECK</code>,
<code>INIT</code> or <code>END</code> block, or
-in a <code>DESTROY</code> method.
-</p>
-<p>This function should have been named wantlist() instead.
-</p>
-</dd>
-<dt>warn LIST</dt>
-<dd><a name="perlfunc-warn-LIST"></a>
-<p>Prints the value of LIST to STDERR. If the last element of LIST does
-not end in a newline, it appends the same file/line number text as
<code>die</code>
-does.
-</p>
-<p>If the output is empty and <code>$@</code> already contains a value
(typically from a
-previous eval) that value is used after appending
<code>"\t...caught"</code>
-to <code>$@</code>. This is useful for staying almost, but not entirely
similar to
-<code>die</code>.
-</p>
-<p>If <code>$@</code> is empty then the string <code>"Warning:
Something's wrong"</code> is used.
-</p>
-<p>No message is printed if there is a <code>$SIG{__WARN__}</code> handler
-installed. It is the handler’s responsibility to deal with the message
-as it sees fit (like, for instance, converting it into a <code>die</code>).
Most
-handlers must therefore arrange to actually display the
-warnings that they are not prepared to deal with, by calling <code>warn</code>
-again in the handler. Note that this is quite safe and will not
-produce an endless loop, since <code>__WARN__</code> hooks are not called from
-inside one.
-</p>
-<p>You will find this behavior is slightly different from that of
-<code>$SIG{__DIE__}</code> handlers (which don’t suppress the error
text, but can
-instead call <code>die</code> again to change it).
-</p>
-<p>Using a <code>__WARN__</code> handler provides a powerful way to silence all
-warnings (even the so-called mandatory ones). An example:
-</p>
-<pre class="verbatim"> # wipe out *all* compile-time warnings
- BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
- my $foo = 10;
- my $foo = 20; # no warning about duplicate my $foo,
- # but hey, you asked for it!
- # no compile-time or run-time warnings before here
- $DOWARN = 1;
-
- # run-time warnings enabled after here
- warn "\$foo is alive and $foo!"; # does show up
-</pre>
-<p>See <a href="#perlvar-NAME">perlvar NAME</a> for details on setting
<code>%SIG</code> entries and for more
-examples. See the Carp module for other kinds of warnings using its
-carp() and cluck() functions.
-</p>
-</dd>
-<dt>write FILEHANDLE</dt>
-<dd><a name="perlfunc-write-FILEHANDLE"></a>
-</dd>
-<dt>write EXPR</dt>
-<dd><a name="perlfunc-write-EXPR"></a>
-</dd>
-<dt>write</dt>
-<dd><a name="perlfunc-write"></a>
-<p>Writes a formatted record (possibly multi-line) to the specified FILEHANDLE,
-using the format associated with that file. By default the format for
-a file is the one having the same name as the filehandle, but the
-format for the current output channel (see the <code>select</code> function)
may be set
-explicitly by assigning the name of the format to the <code>$~</code> variable.
-</p>
-<p>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 and 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, or
"top"
-in the current package if the former does not exist. 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 <code>$^</code> variable
while
-that filehandle is selected. The number of lines remaining on the current
-page is in variable <code>$-</code>, which can be set to <code>0</code> to
force a new page.
-</p>
-<p>If FILEHANDLE is unspecified, output goes to the current default output
-channel, which starts out as STDOUT but may be changed by the
-<code>select</code> operator. If the FILEHANDLE is an EXPR, then the
expression
-is evaluated and the resulting string is used to look up the name of
-the FILEHANDLE at run time. For more on formats, see <a
href="#perlform-NAME">perlform NAME</a>.
-</p>
-<p>Note that write is <em>not</em> the opposite of <code>read</code>.
Unfortunately.
-</p>
-</dd>
-<dt>y///</dt>
-<dd><a name="perlfunc-y_002f_002f_002f"></a>
-<p>The transliteration operator. Same as <code>tr///</code>. See
-<a href="#perlop-Quote_002dLike-Operators">perlop Quote-Like Operators</a>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlfunc-Non_002dfunction-Keywords-by-Cross_002dreference"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlfunc-Alphabetical-Listing-of-Perl-Functions"
accesskey="p" rel="prev">perlfunc Alphabetical Listing of Perl Functions</a>,
Up: <a href="#perlfunc-DESCRIPTION" accesskey="u" rel="up">perlfunc
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Non_002dfunction-Keywords-by-Cross_002dreference"></a>
-<h4 class="subsection">25.2.4 Non-function Keywords by Cross-reference</h4>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlfunc-perldata"
accesskey="1">perlfunc perldata</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfunc-perlmod"
accesskey="2">perlfunc perlmod</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfunc-perlobj"
accesskey="3">perlfunc perlobj</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfunc-perlop"
accesskey="4">perlfunc perlop</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfunc-perlsub"
accesskey="5">perlfunc perlsub</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlfunc-perlsyn"
accesskey="6">perlfunc perlsyn</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlfunc-perldata"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfunc-perlmod" accesskey="n" rel="next">perlfunc
perlmod</a>, Up: <a
href="#perlfunc-Non_002dfunction-Keywords-by-Cross_002dreference" accesskey="u"
rel="up">perlfunc Non-function Keywords by Cross-reference</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perldata-2"></a>
-<h4 class="subsubsection">25.2.4.1 perldata</h4>
-
-<dl compact="compact">
-<dt>__DATA__</dt>
-<dd><a name="perlfunc-_005f_005fDATA_005f_005f"></a>
-</dd>
-<dt>__END__</dt>
-<dd><a name="perlfunc-_005f_005fEND_005f_005f"></a>
-<p>These keywords are documented in <a
href="#perldata-Special-Literals">perldata Special Literals</a>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlfunc-perlmod"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfunc-perlobj" accesskey="n" rel="next">perlfunc
perlobj</a>, Previous: <a href="#perlfunc-perldata" accesskey="p"
rel="prev">perlfunc perldata</a>, Up: <a
href="#perlfunc-Non_002dfunction-Keywords-by-Cross_002dreference" accesskey="u"
rel="up">perlfunc Non-function Keywords by Cross-reference</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlmod-1"></a>
-<h4 class="subsubsection">25.2.4.2 perlmod</h4>
-
-<dl compact="compact">
-<dt>BEGIN</dt>
-<dd><a name="perlfunc-BEGIN"></a>
-</dd>
-<dt>CHECK</dt>
-<dd><a name="perlfunc-CHECK"></a>
-</dd>
-<dt>END</dt>
-<dd><a name="perlfunc-END"></a>
-</dd>
-<dt>INIT</dt>
-<dd><a name="perlfunc-INIT"></a>
-</dd>
-<dt>UNITCHECK</dt>
-<dd><a name="perlfunc-UNITCHECK"></a>
-<p>These compile phase keywords are documented in <a
href="#perlmod-BEGIN_002c-UNITCHECK_002c-CHECK_002c-INIT-and-END">perlmod
BEGIN, UNITCHECK, CHECK, INIT and END</a>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlfunc-perlobj"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfunc-perlop" accesskey="n" rel="next">perlfunc perlop</a>,
Previous: <a href="#perlfunc-perlmod" accesskey="p" rel="prev">perlfunc
perlmod</a>, Up: <a
href="#perlfunc-Non_002dfunction-Keywords-by-Cross_002dreference" accesskey="u"
rel="up">perlfunc Non-function Keywords by Cross-reference</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlobj-1"></a>
-<h4 class="subsubsection">25.2.4.3 perlobj</h4>
-
-<dl compact="compact">
-<dt>DESTROY</dt>
-<dd><a name="perlfunc-DESTROY"></a>
-<p>This method keyword is documented in <a href="#perlobj-Destructors">perlobj
Destructors</a>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlfunc-perlop"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfunc-perlsub" accesskey="n" rel="next">perlfunc
perlsub</a>, Previous: <a href="#perlfunc-perlobj" accesskey="p"
rel="prev">perlfunc perlobj</a>, Up: <a
href="#perlfunc-Non_002dfunction-Keywords-by-Cross_002dreference" accesskey="u"
rel="up">perlfunc Non-function Keywords by Cross-reference</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlop-1"></a>
-<h4 class="subsubsection">25.2.4.4 perlop</h4>
-
-<dl compact="compact">
-<dt>and</dt>
-<dd><a name="perlfunc-and"></a>
-</dd>
-<dt>cmp</dt>
-<dd><a name="perlfunc-cmp"></a>
-</dd>
-<dt>eq</dt>
-<dd><a name="perlfunc-eq"></a>
-</dd>
-<dt>ge</dt>
-<dd><a name="perlfunc-ge"></a>
-</dd>
-<dt>gt</dt>
-<dd><a name="perlfunc-gt"></a>
-</dd>
-<dt>le</dt>
-<dd><a name="perlfunc-le"></a>
-</dd>
-<dt>lt</dt>
-<dd><a name="perlfunc-lt"></a>
-</dd>
-<dt>ne</dt>
-<dd><a name="perlfunc-ne"></a>
-</dd>
-<dt>not</dt>
-<dd><a name="perlfunc-not"></a>
-</dd>
-<dt>or</dt>
-<dd><a name="perlfunc-or"></a>
-</dd>
-<dt>x</dt>
-<dd><a name="perlfunc-x"></a>
-</dd>
-<dt>xor</dt>
-<dd><a name="perlfunc-xor"></a>
-<p>These operators are documented in <a href="#perlop-NAME">perlop NAME</a>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlfunc-perlsub"></a>
-<div class="header">
-<p>
-Next: <a href="#perlfunc-perlsyn" accesskey="n" rel="next">perlfunc
perlsyn</a>, Previous: <a href="#perlfunc-perlop" accesskey="p"
rel="prev">perlfunc perlop</a>, Up: <a
href="#perlfunc-Non_002dfunction-Keywords-by-Cross_002dreference" accesskey="u"
rel="up">perlfunc Non-function Keywords by Cross-reference</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlsub-1"></a>
-<h4 class="subsubsection">25.2.4.5 perlsub</h4>
-
-<dl compact="compact">
-<dt>AUTOLOAD</dt>
-<dd><a name="perlfunc-AUTOLOAD"></a>
-<p>This keyword is documented in <a href="#perlsub-Autoloading">perlsub
Autoloading</a>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlfunc-perlsyn"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlfunc-perlsub" accesskey="p" rel="prev">perlfunc
perlsub</a>, Up: <a
href="#perlfunc-Non_002dfunction-Keywords-by-Cross_002dreference" accesskey="u"
rel="up">perlfunc Non-function Keywords by Cross-reference</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlsyn-1"></a>
-<h4 class="subsubsection">25.2.4.6 perlsyn</h4>
-
-<dl compact="compact">
-<dt>else</dt>
-<dd><a name="perlfunc-else"></a>
-</dd>
-<dt>elsif</dt>
-<dd><a name="perlfunc-elsif"></a>
-</dd>
-<dt>for</dt>
-<dd><a name="perlfunc-for"></a>
-</dd>
-<dt>foreach</dt>
-<dd><a name="perlfunc-foreach"></a>
-</dd>
-<dt>if</dt>
-<dd><a name="perlfunc-if"></a>
-</dd>
-<dt>unless</dt>
-<dd><a name="perlfunc-unless"></a>
-</dd>
-<dt>until</dt>
-<dd><a name="perlfunc-until"></a>
-</dd>
-<dt>while</dt>
-<dd><a name="perlfunc-while"></a>
-<p>These flow-control keywords are documented in <a
href="#perlsyn-Compound-Statements">perlsyn Compound Statements</a>.
-</p>
-</dd>
-<dt>elseif</dt>
-<dd><a name="perlfunc-elseif"></a>
-<p>The "else if" keyword is spelled <code>elsif</code> in Perl.
There’s no <code>elif</code>
-or <code>else if</code> either. It does parse <code>elseif</code>, but only
to warn you
-about not using it.
-</p>
-<p>See the documentation for flow-control keywords in <a
href="#perlsyn-Compound-Statements">perlsyn Compound Statements</a>.
-</p>
-</dd>
-</dl>
-
-<dl compact="compact">
-<dt>default</dt>
-<dd><a name="perlfunc-default"></a>
-</dd>
-<dt>given</dt>
-<dd><a name="perlfunc-given"></a>
-</dd>
-<dt>when</dt>
-<dd><a name="perlfunc-when"></a>
-<p>These flow-control keywords related to the experimental switch feature are
-documented in <a href="#perlsyn-Switch-Statements">perlsyn Switch
Statements</a>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlgit"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgpl" accesskey="n" rel="next">perlgpl</a>, Previous: <a
href="#perlfunc" accesskey="p" rel="prev">perlfunc</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlgit-1"></a>
-<h2 class="chapter">26 perlgit</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlgit-NAME"
accesskey="1">perlgit NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlgit-DESCRIPTION"
accesskey="2">perlgit DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-CLONING-THE-REPOSITORY" accesskey="3">perlgit CLONING THE
REPOSITORY</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-WORKING-WITH-THE-REPOSITORY" accesskey="4">perlgit WORKING WITH
THE REPOSITORY</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-WRITE-ACCESS-TO-THE-GIT-REPOSITORY" accesskey="5">perlgit WRITE
ACCESS TO THE GIT REPOSITORY</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlgit-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-DESCRIPTION" accesskey="n" rel="next">perlgit
DESCRIPTION</a>, Up: <a href="#perlgit" accesskey="u" rel="up">perlgit</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-25"></a>
-<h3 class="section">26.1 NAME</h3>
-
-<p>perlgit - Detailed information about git and the Perl repository
-</p>
-<hr>
-<a name="perlgit-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-CLONING-THE-REPOSITORY" accesskey="n"
rel="next">perlgit CLONING THE REPOSITORY</a>, Previous: <a
href="#perlgit-NAME" accesskey="p" rel="prev">perlgit NAME</a>, Up: <a
href="#perlgit" accesskey="u" rel="up">perlgit</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-25"></a>
-<h3 class="section">26.2 DESCRIPTION</h3>
-
-<p>This document provides details on using git to develop Perl. If you are
-just interested in working on a quick patch, see <a
href="#perlhack-NAME">perlhack NAME</a> first.
-This document is intended for people who are regular contributors to
-Perl, including those with write access to the git repository.
-</p>
-<hr>
-<a name="perlgit-CLONING-THE-REPOSITORY"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-WORKING-WITH-THE-REPOSITORY" accesskey="n"
rel="next">perlgit WORKING WITH THE REPOSITORY</a>, Previous: <a
href="#perlgit-DESCRIPTION" accesskey="p" rel="prev">perlgit DESCRIPTION</a>,
Up: <a href="#perlgit" accesskey="u" rel="up">perlgit</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="CLONING-THE-REPOSITORY"></a>
-<h3 class="section">26.3 CLONING THE REPOSITORY</h3>
-
-<p>All of Perl’s source code is kept centrally in a Git repository at
-<em>perl5.git.perl.org</em>.
-</p>
-<p>You can make a read-only clone of the repository by running:
-</p>
-<pre class="verbatim"> % git clone git://perl5.git.perl.org/perl.git perl
-</pre>
-<p>This uses the git protocol (port 9418).
-</p>
-<p>If you cannot use the git protocol for firewall reasons, you can also
-clone via http, though this is much slower:
-</p>
-<pre class="verbatim"> % git clone http://perl5.git.perl.org/perl.git perl
-</pre>
-<hr>
-<a name="perlgit-WORKING-WITH-THE-REPOSITORY"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-WRITE-ACCESS-TO-THE-GIT-REPOSITORY" accesskey="n"
rel="next">perlgit WRITE ACCESS TO THE GIT REPOSITORY</a>, Previous: <a
href="#perlgit-CLONING-THE-REPOSITORY" accesskey="p" rel="prev">perlgit CLONING
THE REPOSITORY</a>, Up: <a href="#perlgit" accesskey="u" rel="up">perlgit</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="WORKING-WITH-THE-REPOSITORY"></a>
-<h3 class="section">26.4 WORKING WITH THE REPOSITORY</h3>
-
-<p>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.
-</p>
-<pre class="verbatim"> % git branch
- * blead
-</pre>
-<p>Using the -a switch to <code>branch</code> will also show the remote
tracking
-branches in the repository:
-</p>
-<pre class="verbatim"> % git branch -a
- * blead
- origin/HEAD
- origin/blead
- ...
-</pre>
-<p>The branches that begin with "origin" correspond to the "git
remote"
-that you cloned from (which is named "origin"). Each branch on the
-remote will be exactly tracked by these branches. You should NEVER do
-work on these remote tracking branches. You only ever do work in a
-local branch. Local branches can be configured to automerge (on pull)
-from a designated remote tracking branch. This is the case with the
-default branch <code>blead</code> which will be configured to merge from the
-remote tracking branch <code>origin/blead</code>.
-</p>
-<p>You can see recent commits:
-</p>
-<pre class="verbatim"> % git log
-</pre>
-<p>And pull new changes from the repository, and update your local
-repository (must be clean first)
-</p>
-<pre class="verbatim"> % git pull
-</pre>
-<p>Assuming we are on the branch <code>blead</code> immediately after a pull,
this
-command would be more or less equivalent to:
-</p>
-<pre class="verbatim"> % git fetch
- % git merge origin/blead
-</pre>
-<p>In fact if you want to update your local repository without touching
-your working directory you do:
-</p>
-<pre class="verbatim"> % git fetch
-</pre>
-<p>And if you want to update your remote-tracking branches for all defined
-remotes simultaneously you can do
-</p>
-<pre class="verbatim"> % git remote update
-</pre>
-<p>Neither of these last two commands will update your working directory,
-however both will update the remote-tracking branches in your
-repository.
-</p>
-<p>To make a local branch of a remote branch:
-</p>
-<pre class="verbatim"> % git checkout -b maint-5.10 origin/maint-5.10
-</pre>
-<p>To switch back to blead:
-</p>
-<pre class="verbatim"> % git checkout blead
-</pre>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlgit-Finding-out-your-status" accesskey="1">perlgit Finding out your
status</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlgit-Patch-workflow"
accesskey="2">perlgit Patch workflow</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Committing-your-changes" accesskey="3">perlgit Committing your
changes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Sending-patch-emails" accesskey="4">perlgit Sending patch
emails</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-A-note-on-derived-files" accesskey="5">perlgit A note on derived
files</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Cleaning-a-working-directory" accesskey="6">perlgit Cleaning a
working directory</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlgit-Bisecting"
accesskey="7">perlgit Bisecting</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Topic-branches-and-rewriting-history" accesskey="8">perlgit
Topic branches and rewriting history</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlgit-Grafts"
accesskey="9">perlgit Grafts</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlgit-Finding-out-your-status"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-Patch-workflow" accesskey="n" rel="next">perlgit Patch
workflow</a>, Up: <a href="#perlgit-WORKING-WITH-THE-REPOSITORY" accesskey="u"
rel="up">perlgit WORKING WITH THE REPOSITORY</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Finding-out-your-status"></a>
-<h4 class="subsection">26.4.1 Finding out your status</h4>
-
-<p>The most common git command you will use will probably be
-</p>
-<pre class="verbatim"> % git status
-</pre>
-<p>This command will produce as output a description of the current state
-of the repository, including modified files and unignored untracked
-files, and in addition it will show things like what files have been
-staged for the next commit, and usually some useful information about
-how to change things. For instance the following:
-</p>
-<pre class="verbatim"> $ git status
- # On branch blead
- # Your branch is ahead of 'origin/blead' by 1 commit.
- #
- # Changes to be committed:
- # (use "git reset HEAD <file>..." to unstage)
- #
- # modified: pod/perlgit.pod
- #
- # Changed but not updated:
- # (use "git add <file>..." to update what will be
committed)
- #
- # modified: pod/perlgit.pod
- #
- # Untracked files:
- # (use "git add <file>..." to include in what will be
committed)
- #
- # deliberate.untracked
-</pre>
-<p>This shows that there were changes to this document staged for commit,
-and that there were further changes in the working directory not yet
-staged. It also shows that there was an untracked file in the working
-directory, and as you can see shows how to change all of this. It also
-shows that there is one commit on the working branch <code>blead</code> which
has
-not been pushed to the <code>origin</code> remote yet. <strong>NOTE</strong>:
that this output
-is also what you see as a template if you do not provide a message to
-<code>git commit</code>.
-</p>
-<hr>
-<a name="perlgit-Patch-workflow"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-Committing-your-changes" accesskey="n"
rel="next">perlgit Committing your changes</a>, Previous: <a
href="#perlgit-Finding-out-your-status" accesskey="p" rel="prev">perlgit
Finding out your status</a>, Up: <a href="#perlgit-WORKING-WITH-THE-REPOSITORY"
accesskey="u" rel="up">perlgit WORKING WITH THE REPOSITORY</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Patch-workflow"></a>
-<h4 class="subsection">26.4.2 Patch workflow</h4>
-
-<p>First, please read <a href="#perlhack-NAME">perlhack NAME</a> for details
on hacking the Perl core.
-That document covers many details on how to create a good patch.
-</p>
-<p>If you already have a Perl repository, you should ensure that you’re
on
-the <em>blead</em> branch, and your repository is up to date:
-</p>
-<pre class="verbatim"> % git checkout blead
- % git pull
-</pre>
-<p>It’s preferable to patch against the latest blead version, since this
-is where new development occurs for all changes other than critical bug
-fixes. Critical bug fix patches should be made against the relevant
-maint branches, or should be submitted with a note indicating all the
-branches where the fix should be applied.
-</p>
-<p>Now that we have everything up to date, we need to create a temporary
-new branch for these changes and switch into it:
-</p>
-<pre class="verbatim"> % git checkout -b orange
-</pre>
-<p>which is the short form of
-</p>
-<pre class="verbatim"> % git branch orange
- % git checkout orange
-</pre>
-<p>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.
-</p>
-<p>That’ll get you scolded on perl5-porters, so don’t do that. Be
Awesome.
-</p>
-<p>Then make your changes. For example, if Leon Brocard changes his name
-to Orange Brocard, we should change his name in the AUTHORS file:
-</p>
-<pre class="verbatim"> % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
-</pre>
-<p>You can see what files are changed:
-</p>
-<pre class="verbatim"> % git status
- # On branch orange
- # Changes to be committed:
- # (use "git reset HEAD <file>..." to unstage)
- #
- # modified: AUTHORS
- #
-</pre>
-<p>And you can see the changes:
-</p>
-<pre class="verbatim"> % git diff
- diff --git a/AUTHORS b/AUTHORS
- index 293dd70..722c93e 100644
- --- a/AUTHORS
- +++ b/AUTHORS
- @@ -541,7 +541,7 @@ Lars Hecking <address@hidden>
- Laszlo Molnar <address@hidden>
- Leif Huhn <address@hidden>
- Len Johnson <address@hidden>
- -Leon Brocard <address@hidden>
- +Orange Brocard <address@hidden>
- Les Peters <address@hidden>
- Lesley Binks <address@hidden>
- Lincoln D. Stein <address@hidden>
-</pre>
-<p>Now commit your change locally:
-</p>
-<pre class="verbatim"> % git commit -a -m 'Rename Leon Brocard to Orange
Brocard'
- Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
- 1 files changed, 1 insertions(+), 1 deletions(-)
-</pre>
-<p>The <code>-a</code> 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 <code>-a</code> and use the command
-<code>git add <em>FILE ...</em><!-- /@w --></code> before doing
the commit. <code>git add <span
class="nolinebreak">--interactive</span><!-- /@w --></code> allows you to even
just commit portions of files
-instead of all the changes in them.
-</p>
-<p>The <code>-m</code> 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.
-</p>
-<p>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:
-</p>
-<pre class="verbatim"> Created commit daf8e63: explain git status and stuff
about remotes
- 1 files changed, 83 insertions(+), 3 deletions(-)
-</pre>
-<p>If you re-run <code>git status</code>, you should see something like this:
-</p>
-<pre class="verbatim"> % 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)
-</pre>
-<p>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.
-</p>
-<p>You can examine your last commit with:
-</p>
-<pre class="verbatim"> % git show HEAD
-</pre>
-<p>and if you are not happy with either the description or the patch
-itself you can fix it up by editing the files once more and then issue:
-</p>
-<pre class="verbatim"> % git commit -a --amend
-</pre>
-<p>Now you should create a patch file for all your local changes:
-</p>
-<pre class="verbatim"> % git format-patch -M blead..
- 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
-</pre>
-<p>Or for a lot of changes, e.g. from a topic branch:
-</p>
-<pre class="verbatim"> % git format-patch --stdout -M blead.. >
topic-branch-changes.patch
-</pre>
-<p>You should now send an email to
-<a href="mailto:address@hidden";>address@hidden</a> 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 (with manual moderation, so please be patient). You
-should only send patches to
-<a href="mailto:address@hidden";>address@hidden</a> directly if the
-patch is not ready to be applied, but intended for discussion.
-</p>
-<p>Please do not use git-send-email(1) to send your patch. See <a
href="#perlgit-Sending-patch-emails">Sending
-patch emails</a> for more information.
-</p>
-<p>If you want to delete your temporary branch, you may do so with:
-</p>
-<pre class="verbatim"> % git checkout blead
- % git branch -d orange
- error: The branch 'orange' is not an ancestor of your current HEAD.
- If you are sure you want to delete it, run 'git branch -D orange'.
- % git branch -D orange
- Deleted branch orange.
-</pre>
-<hr>
-<a name="perlgit-Committing-your-changes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-Sending-patch-emails" accesskey="n" rel="next">perlgit
Sending patch emails</a>, Previous: <a href="#perlgit-Patch-workflow"
accesskey="p" rel="prev">perlgit Patch workflow</a>, Up: <a
href="#perlgit-WORKING-WITH-THE-REPOSITORY" accesskey="u" rel="up">perlgit
WORKING WITH THE REPOSITORY</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Committing-your-changes"></a>
-<h4 class="subsection">26.4.3 Committing your changes</h4>
-
-<p>Assuming that you’d like to commit all the changes you’ve made
as a
-single atomic unit, run this command:
-</p>
-<pre class="verbatim"> % git commit -a
-</pre>
-<p>(That <code>-a</code> tells git to add every file you’ve changed to
this commit.
-New files aren’t automatically added to your commit when you use
-<code>commit -a</code> If you want to add files or to commit some, but not all
of
-your changes, have a look at the documentation for <code>git add</code>.)
-</p>
-<p>Git will start up your favorite text editor, so that you can craft a
-commit message for your change. See <a
href="#perlhack-Commit-message">perlhack Commit message</a> for more
-information about what makes a good commit message.
-</p>
-<p>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:
-</p>
-<pre class="verbatim"> Created commit daf8e63: explain git status and stuff
about remotes
- 1 files changed, 83 insertions(+), 3 deletions(-)
-</pre>
-<p>If you re-run <code>git status</code>, you should see something like this:
-</p>
-<pre class="verbatim"> % 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)
-</pre>
-<p>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.
-</p>
-<hr>
-<a name="perlgit-Sending-patch-emails"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-A-note-on-derived-files" accesskey="n"
rel="next">perlgit A note on derived files</a>, Previous: <a
href="#perlgit-Committing-your-changes" accesskey="p" rel="prev">perlgit
Committing your changes</a>, Up: <a href="#perlgit-WORKING-WITH-THE-REPOSITORY"
accesskey="u" rel="up">perlgit WORKING WITH THE REPOSITORY</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Sending-patch-emails"></a>
-<h4 class="subsection">26.4.4 Sending patch emails</h4>
-
-<p>After you’ve generated your patch you should sent it
-to address@hidden (as discussed <a href="#perlgit-Patch-workflow">in the
previous
-section</a>) with a normal mail client as an
-attachment, along with a description of the patch.
-</p>
-<p>You <strong>must not</strong> use git-send-email(1) to send patches
generated with
-git-format-patch(1). The RT ticketing system living behind
address@hidden does not respect the inline contents of E-Mails,
-sending an inline patch to RT guarantees that your patch will be
-destroyed.
-</p>
-<p>Someone may download your patch from RT, which will result in the
-subject (the first line of the commit message) being omitted. See RT
-#74192 and commit a4583001 for an example. Alternatively someone may
-apply your patch from RT after it arrived in their mailbox, by which
-time RT will have modified the inline content of the message. See RT
-#74532 and commit f9bcfeac for a bad example of this failure mode.
-</p>
-<hr>
-<a name="perlgit-A-note-on-derived-files"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-Cleaning-a-working-directory" accesskey="n"
rel="next">perlgit Cleaning a working directory</a>, Previous: <a
href="#perlgit-Sending-patch-emails" accesskey="p" rel="prev">perlgit Sending
patch emails</a>, Up: <a href="#perlgit-WORKING-WITH-THE-REPOSITORY"
accesskey="u" rel="up">perlgit WORKING WITH THE REPOSITORY</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="A-note-on-derived-files"></a>
-<h4 class="subsection">26.4.5 A note on derived files</h4>
-
-<p>Be aware that many files in the distribution are derivative–avoid
-patching them, because git won’t see the changes to them, and the build
-process will overwrite them. Patch the originals instead. Most
-utilities (like perldoc) are in this category, i.e. patch
-<samp>utils/perldoc.PL</samp> rather than <samp>utils/perldoc</samp>.
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 <code>MANIFEST</code>.
-</p>
-<hr>
-<a name="perlgit-Cleaning-a-working-directory"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-Bisecting" accesskey="n" rel="next">perlgit
Bisecting</a>, Previous: <a href="#perlgit-A-note-on-derived-files"
accesskey="p" rel="prev">perlgit A note on derived files</a>, Up: <a
href="#perlgit-WORKING-WITH-THE-REPOSITORY" accesskey="u" rel="up">perlgit
WORKING WITH THE REPOSITORY</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Cleaning-a-working-directory"></a>
-<h4 class="subsection">26.4.6 Cleaning a working directory</h4>
-
-<p>The command <code>git clean</code> can with varying arguments be used as a
-replacement for <code>make clean</code>.
-</p>
-<p>To reset your working directory to a pristine condition you can do:
-</p>
-<pre class="verbatim"> % git clean -dxf
-</pre>
-<p>However, be aware this will delete ALL untracked content. You can use
-</p>
-<pre class="verbatim"> % git clean -Xf
-</pre>
-<p>to remove all ignored untracked files, such as build and test
-byproduct, but leave any manually created files alone.
-</p>
-<p>If you only want to cancel some uncommitted edits, you can use <code>git
-checkout</code> and give it a list of files to be reverted, or <code>git
checkout
--f</code> to revert them all.
-</p>
-<p>If you want to cancel one or several commits, you can use <code>git
reset</code>.
-</p>
-<hr>
-<a name="perlgit-Bisecting"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-Topic-branches-and-rewriting-history" accesskey="n"
rel="next">perlgit Topic branches and rewriting history</a>, Previous: <a
href="#perlgit-Cleaning-a-working-directory" accesskey="p" rel="prev">perlgit
Cleaning a working directory</a>, Up: <a
href="#perlgit-WORKING-WITH-THE-REPOSITORY" accesskey="u" rel="up">perlgit
WORKING WITH THE REPOSITORY</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Bisecting"></a>
-<h4 class="subsection">26.4.7 Bisecting</h4>
-
-<p><code>git</code> provides a built-in way to determine which commit should
be blamed
-for introducing a given bug. <code>git bisect</code> performs a binary search
of
-history to locate the first failing commit. It is fast, powerful and
-flexible, but requires some setup and to automate the process an auxiliary
-shell script is needed.
-</p>
-<p>The core provides a wrapper program, <samp>Porting/bisect.pl</samp>, which
attempts to
-simplify as much as possible, making bisecting as simple as running a Perl
-one-liner. For example, if you want to know when this became an error:
-</p>
-<pre class="verbatim"> perl -e 'my $a := 2'
-</pre>
-<p>you simply run this:
-</p>
-<pre class="verbatim"> .../Porting/bisect.pl -e 'my $a := 2;'
-</pre>
-<p>Using <code>bisect.pl</code>, with one command (and no other files)
it’s easy to find
-out
-</p>
-<ul>
-<li> Which commit caused this example code to break?
-
-</li><li> Which commit caused this example code to start working?
-
-</li><li> Which commit added the first file to match this regex?
-
-</li><li> Which commit removed the last file to match this regex?
-
-</li></ul>
-
-<p>usually without needing to know which versions of perl to use as start and
-end revisions, as <samp>bisect.pl</samp> automatically searches to find the
earliest
-stable version for which the test case passes. Run
-<code>Porting/bisect.pl --help</code> for the full documentation, including
how to
-set the <code>Configure</code> and build time options.
-</p>
-<p>If you require more flexibility than <samp>Porting/bisect.pl</samp> has to
offer, you’ll
-need to run <code>git bisect</code> yourself. It’s most useful to use
<code>git bisect run</code>
-to automate the building and testing of perl revisions. For this you’ll
need
-a shell script for <code>git</code> to call to test a particular revision. An
example
-script is <samp>Porting/bisect-example.sh</samp>, which you should copy
<strong>outside</strong> of
-the repository, as the bisect process will reset the state to a clean checkout
-as it runs. The instructions below assume that you copied it as
<samp>~/run</samp> and
-then edited it as appropriate.
-</p>
-<p>You first enter in bisect mode with:
-</p>
-<pre class="verbatim"> % git bisect start
-</pre>
-<p>For example, if the bug is present on <code>HEAD</code> but wasn’t in
5.10.0,
-<code>git</code> will learn about this when you enter:
-</p>
-<pre class="verbatim"> % git bisect bad
- % git bisect good perl-5.10.0
- Bisecting: 853 revisions left to test after this
-</pre>
-<p>This results in checking out the median commit between <code>HEAD</code> and
-<code>perl-5.10.0</code>. You can then run the bisecting process with:
-</p>
-<pre class="verbatim"> % git bisect run ~/run
-</pre>
-<p>When the first bad commit is isolated, <code>git bisect</code> will tell
you so:
-</p>
-<pre class="verbatim"> ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad
commit
- commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
- Author: Dave Mitchell <address@hidden>
- Date: Sat Feb 9 14:56:23 2008 +0000
-
- [perl #49472] Attributes + Unknown Error
- ...
-
- bisect run success
-</pre>
-<p>You can peek into the bisecting process with <code>git bisect log</code> and
-<code>git bisect visualize</code>. <code>git bisect reset</code> will get you
out of bisect
-mode.
-</p>
-<p>Please note that the first <code>good</code> state must be an ancestor of
the
-first <code>bad</code> state. If you want to search for the commit that
<em>solved</em>
-some bug, you have to negate your test case (i.e. exit with <code>1</code> if
OK
-and <code>0</code> if not) and still mark the lower bound as <code>good</code>
and the
-upper as <code>bad</code>. The "first bad commit" has then to be
understood as
-the "first commit where the bug is solved".
-</p>
-<p><code>git help bisect</code> has much more information on how you can tweak
your
-binary searches.
-</p>
-<hr>
-<a name="perlgit-Topic-branches-and-rewriting-history"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-Grafts" accesskey="n" rel="next">perlgit Grafts</a>,
Previous: <a href="#perlgit-Bisecting" accesskey="p" rel="prev">perlgit
Bisecting</a>, Up: <a href="#perlgit-WORKING-WITH-THE-REPOSITORY" accesskey="u"
rel="up">perlgit WORKING WITH THE REPOSITORY</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Topic-branches-and-rewriting-history"></a>
-<h4 class="subsection">26.4.8 Topic branches and rewriting history</h4>
-
-<p>Individual committers should create topic branches under
-<strong>yourname</strong>/<strong>some_descriptive_name</strong>. Other
committers should check
-with a topic branch’s creator before making any change to it.
-</p>
-<p>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:
-</p>
-<pre class="verbatim"> $ branch="$yourname/$some_descriptive_name"
- $ git push origin HEAD:$branch
- $ git checkout -b $branch origin/$branch
-</pre>
-<p>Users of git 1.7 or newer can do it in a more obvious manner:
-</p>
-<pre class="verbatim"> $ branch="$yourname/$some_descriptive_name"
- $ git checkout -b $branch
- $ git push origin -u $branch
-</pre>
-<p>If you are not the creator of
<strong>yourname</strong>/<strong>some_descriptive_name</strong>, 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.
-</p>
-<p>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.
-</p>
-<p>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).
-</p>
-<p>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
<code>refspec</code>’s
-in the git push documentation for details) after you have rebased your
-branch:
-</p>
-<pre class="verbatim"> # first rebase
- $ git checkout $user/$topic
- $ git fetch
- $ git rebase origin/blead
-
- # then "delete-and-push"
- $ git push origin :$user/$topic
- $ git push origin $user/$topic
-</pre>
-<p><strong>NOTE:</strong> it is forbidden at the repository level to delete
any of the
-"primary" branches. That is any branch matching
-<code>m!^(blead|maint|perl)!</code>. Any attempt to do so will result in git
-producing an error like this:
-</p>
-<pre class="verbatim"> $ 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'
-</pre>
-<p>As a matter of policy we do <strong>not</strong> 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.
-</p>
-<p>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.)
-</p>
-<hr>
-<a name="perlgit-Grafts"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlgit-Topic-branches-and-rewriting-history"
accesskey="p" rel="prev">perlgit Topic branches and rewriting history</a>, Up:
<a href="#perlgit-WORKING-WITH-THE-REPOSITORY" accesskey="u" rel="up">perlgit
WORKING WITH THE REPOSITORY</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Grafts"></a>
-<h4 class="subsection">26.4.9 Grafts</h4>
-
-<p>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
-<code>.git/info/grafts</code> file:
-</p>
-<pre class="verbatim"> 296f12bbbbaa06de9be9d09d3dcf8f4528898a49
434946e0cb7a32589ed92d18008aaa1d88515930
-</pre>
-<p>It is particularly important to have this graft line if any bisecting
-is done in the area of the "merge" in question.
-</p>
-<hr>
-<a name="perlgit-WRITE-ACCESS-TO-THE-GIT-REPOSITORY"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlgit-WORKING-WITH-THE-REPOSITORY" accesskey="p"
rel="prev">perlgit WORKING WITH THE REPOSITORY</a>, Up: <a href="#perlgit"
accesskey="u" rel="up">perlgit</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="WRITE-ACCESS-TO-THE-GIT-REPOSITORY"></a>
-<h3 class="section">26.5 WRITE ACCESS TO THE GIT REPOSITORY</h3>
-
-<p>Once you have write access, you will need to modify the URL for the
-origin remote to enable pushing. Edit <samp>.git/config</samp> with the
-git-config(1) command:
-</p>
-<pre class="verbatim"> % git config remote.origin.url
ssh://perl5.git.perl.org/perl.git
-</pre>
-<p>You can also set up your user name and e-mail address. Most people do
-this once globally in their <samp>~/.gitconfig</samp> by doing something like:
-</p>
-<pre class="verbatim"> % git config --global user.name "ÃÂvar
Arnfjörð Bjarmason"
- % git config --global user.email address@hidden
-</pre>
-<p>However, if you’d like to override that just for perl,
-execute something like the following in <samp>perl</samp>:
-</p>
-<pre class="verbatim"> % git config user.email address@hidden
-</pre>
-<p>It is also possible to keep <code>origin</code> as a git remote, and add a
new
-remote for ssh access:
-</p>
-<pre class="verbatim"> % git remote add camel perl5.git.perl.org:/perl.git
-</pre>
-<p>This allows you to update your local repository by pulling from
-<code>origin</code>, which is faster and doesn’t require you to
authenticate, and
-to push your changes back with the <code>camel</code> remote:
-</p>
-<pre class="verbatim"> % git fetch camel
- % git push camel
-</pre>
-<p>The <code>fetch</code> command just updates the <code>camel</code> refs, as
the objects
-themselves should have been fetched when pulling from <code>origin</code>.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlgit-Accepting-a-patch"
accesskey="1">perlgit Accepting a patch</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Committing-to-blead" accesskey="2">perlgit Committing to
blead</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-On-merging-and-rebasing" accesskey="3">perlgit On merging and
rebasing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Committing-to-maintenance-versions" accesskey="4">perlgit
Committing to maintenance versions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Merging-from-a-branch-via-GitHub" accesskey="5">perlgit Merging
from a branch via GitHub</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-Using-a-smoke_002dme-branch-to-test-changes"
accesskey="6">perlgit Using a smoke-me branch to test
changes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgit-A-note-on-camel-and-dromedary" accesskey="7">perlgit A note on
camel and dromedary</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlgit-Accepting-a-patch"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-Committing-to-blead" accesskey="n" rel="next">perlgit
Committing to blead</a>, Up: <a
href="#perlgit-WRITE-ACCESS-TO-THE-GIT-REPOSITORY" accesskey="u"
rel="up">perlgit WRITE ACCESS TO THE GIT REPOSITORY</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Accepting-a-patch"></a>
-<h4 class="subsection">26.5.1 Accepting a patch</h4>
-
-<p>If you have received a patch file generated using the above section,
-you should try out the patch.
-</p>
-<p>First we need to create a temporary new branch for these changes and
-switch into it:
-</p>
-<pre class="verbatim"> % git checkout -b experimental
-</pre>
-<p>Patches that were formatted by <code>git format-patch</code> are applied
with
-<code>git am</code>:
-</p>
-<pre class="verbatim"> % git am
0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
- Applying Rename Leon Brocard to Orange Brocard
-</pre>
-<p>If just a raw diff is provided, it is also possible use this two-step
-process:
-</p>
-<pre class="verbatim"> % git apply bugfix.diff
- % git commit -a -m "Some fixing" --author="That Guy
<address@hidden>"
-</pre>
-<p>Now we can inspect the change:
-</p>
-<pre class="verbatim"> % git show HEAD
- commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
- Author: Leon Brocard <address@hidden>
- 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
<address@hidden>
- Laszlo Molnar <address@hidden>
- Leif Huhn <address@hidden>
- Len Johnson <address@hidden>
- -Leon Brocard <address@hidden>
- +Orange Brocard <address@hidden>
- Les Peters <address@hidden>
- Lesley Binks <address@hidden>
- Lincoln D. Stein <address@hidden>
-</pre>
-<p>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:
-</p>
-<pre class="verbatim"> % git checkout blead
- % git merge experimental
- % git push origin blead
-</pre>
-<p>If you want to delete your temporary branch, you may do so with:
-</p>
-<pre class="verbatim"> % 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.
-</pre>
-<hr>
-<a name="perlgit-Committing-to-blead"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-On-merging-and-rebasing" accesskey="n"
rel="next">perlgit On merging and rebasing</a>, Previous: <a
href="#perlgit-Accepting-a-patch" accesskey="p" rel="prev">perlgit Accepting a
patch</a>, Up: <a href="#perlgit-WRITE-ACCESS-TO-THE-GIT-REPOSITORY"
accesskey="u" rel="up">perlgit WRITE ACCESS TO THE GIT REPOSITORY</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Committing-to-blead"></a>
-<h4 class="subsection">26.5.2 Committing to blead</h4>
-
-<p>The ’blead’ branch will become the next production release of
Perl.
-</p>
-<p>Before pushing <em>any</em> local change to blead, it’s incredibly
important
-that you do a few things, lest other committers come after you with
-pitchforks and torches:
-</p>
-<ul>
-<li> Make sure you have a good commit message. See <a
href="#perlhack-Commit-message">perlhack Commit message</a> for details.
-
-</li><li> 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.
-
-</li><li> If you don’t run the full test suite, at least <code>make
test_porting</code>.
-This will run basic sanity checks. To see which sanity checks, have a
-look in <samp>t/porting</samp>.
-
-</li><li> If you make any changes that affect miniperl or core routines that
have
-different code paths for miniperl, be sure to run <code>make minitest</code>.
-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.
-
-</li></ul>
-
-<hr>
-<a name="perlgit-On-merging-and-rebasing"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-Committing-to-maintenance-versions" accesskey="n"
rel="next">perlgit Committing to maintenance versions</a>, Previous: <a
href="#perlgit-Committing-to-blead" accesskey="p" rel="prev">perlgit Committing
to blead</a>, Up: <a href="#perlgit-WRITE-ACCESS-TO-THE-GIT-REPOSITORY"
accesskey="u" rel="up">perlgit WRITE ACCESS TO THE GIT REPOSITORY</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="On-merging-and-rebasing"></a>
-<h4 class="subsection">26.5.3 On merging and rebasing</h4>
-
-<p>Simple, one-off commits pushed to the ’blead’ branch should be
simple
-commits that apply cleanly. In other words, you should make sure your
-work is committed against the current position of blead, so that you can
-push back to the master repository without merging.
-</p>
-<p>Sometimes, blead will move while you’re building or testing your
-changes. When this happens, your push will be rejected with a message
-like this:
-</p>
-<pre class="verbatim"> To ssh://perl5.git.perl.org/perl.git
- ! [rejected] blead -> blead (non-fast-forward)
- error: failed to push some refs to 'ssh://perl5.git.perl.org/perl.git'
- To prevent you from losing history, non-fast-forward updates were rejected
- Merge the remote changes (e.g. 'git pull') before pushing again. See the
- 'Note about fast-forwards' section of 'git push --help' for details.
-</pre>
-<p>When this happens, you can just <em>rebase</em> your work against the new
-position of blead, like this (assuming your remote for the master
-repository is "p5p"):
-</p>
-<pre class="verbatim"> $ git fetch p5p
- $ git rebase p5p/blead
-</pre>
-<p>You will see your commits being re-applied, and you will then be able to
-push safely. More information about rebasing can be found in the
-documentation for the git-rebase(1) command.
-</p>
-<p>For larger sets of commits that only make sense together, or that would
-benefit from a summary of the set’s purpose, you should use a merge
-commit. You should perform your work on a <a
href="#perlgit-Topic-branches-and-rewriting-history">topic branch</a>, which
you should regularly rebase
-against blead to ensure that your code is not broken by blead moving.
-When you have finished your work, please perform a final rebase and
-test. Linear history is something that gets lost with every
-commit on blead, but a final rebase makes the history linear
-again, making it easier for future maintainers to see what has
-happened. Rebase as follows (assuming your work was on the
-branch <code>committer/somework</code>):
-</p>
-<pre class="verbatim"> $ git checkout committer/somework
- $ git rebase blead
-</pre>
-<p>Then you can merge it into master like this:
-</p>
-<pre class="verbatim"> $ git checkout blead
- $ git merge --no-ff --no-commit committer/somework
- $ git commit -a
-</pre>
-<p>The switches above deserve explanation. <code>--no-ff</code> indicates
that even
-if all your work can be applied linearly against blead, a merge commit
-should still be prepared. This ensures that all your work will be shown
-as a side branch, with all its commits merged into the mainstream blead
-by the merge commit.
-</p>
-<p><code>--no-commit</code> means that the merge commit will be
<em>prepared</em> but not
-<em>committed</em>. The commit is then actually performed when you run the
-next command, which will bring up your editor to describe the commit.
-Without <code>--no-commit</code>, the commit would be made with nearly no
useful
-message, which would greatly diminish the value of the merge commit as a
-placeholder for the work’s description.
-</p>
-<p>When describing the merge commit, explain the purpose of the branch, and
-keep in mind that this description will probably be used by the
-eventual release engineer when reviewing the next perldelta document.
-</p>
-<hr>
-<a name="perlgit-Committing-to-maintenance-versions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-Merging-from-a-branch-via-GitHub" accesskey="n"
rel="next">perlgit Merging from a branch via GitHub</a>, Previous: <a
href="#perlgit-On-merging-and-rebasing" accesskey="p" rel="prev">perlgit On
merging and rebasing</a>, Up: <a
href="#perlgit-WRITE-ACCESS-TO-THE-GIT-REPOSITORY" accesskey="u"
rel="up">perlgit WRITE ACCESS TO THE GIT REPOSITORY</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Committing-to-maintenance-versions"></a>
-<h4 class="subsection">26.5.4 Committing to maintenance versions</h4>
-
-<p>Maintenance versions should only be altered to add critical bug fixes,
-see <a href="#perlpolicy-NAME">perlpolicy NAME</a>.
-</p>
-<p>To commit to a maintenance version of perl, you need to create a local
-tracking branch:
-</p>
-<pre class="verbatim"> % git checkout --track -b maint-5.005
origin/maint-5.005
-</pre>
-<p>This creates a local branch named <code>maint-5.005</code>, which tracks the
-remote branch <code>origin/maint-5.005</code>. Then you can pull, commit, merge
-and push as before.
-</p>
-<p>You can also cherry-pick commits from blead and another branch, by
-using the <code>git cherry-pick</code> command. It is recommended to use the
-<strong>-x</strong> option to <code>git cherry-pick</code> in order to record
the SHA1 of the
-original commit in the new commit message.
-</p>
-<p>Before pushing any change to a maint version, make sure you’ve
-satisfied the steps in <a href="#perlgit-Committing-to-blead">Committing to
blead</a> above.
-</p>
-<hr>
-<a name="perlgit-Merging-from-a-branch-via-GitHub"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-Using-a-smoke_002dme-branch-to-test-changes"
accesskey="n" rel="next">perlgit Using a smoke-me branch to test changes</a>,
Previous: <a href="#perlgit-Committing-to-maintenance-versions" accesskey="p"
rel="prev">perlgit Committing to maintenance versions</a>, Up: <a
href="#perlgit-WRITE-ACCESS-TO-THE-GIT-REPOSITORY" accesskey="u"
rel="up">perlgit WRITE ACCESS TO THE GIT REPOSITORY</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Merging-from-a-branch-via-GitHub"></a>
-<h4 class="subsection">26.5.5 Merging from a branch via GitHub</h4>
-
-<p>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.
-</p>
-<pre class="verbatim"> % git remote add avar git://github.com/avar/perl.git
- % git fetch avar
-</pre>
-<p>Now you can see the differences between the branch and blead:
-</p>
-<pre class="verbatim"> % git diff avar/orange
-</pre>
-<p>And you can see the commits:
-</p>
-<pre class="verbatim"> % git log avar/orange
-</pre>
-<p>If you approve of a specific commit, you can cherry pick it:
-</p>
-<pre class="verbatim"> % git cherry-pick
0c24b290ae02b2ab3304f51d5e11e85eb3659eae
-</pre>
-<p>Or you could just merge the whole branch if you like it all:
-</p>
-<pre class="verbatim"> % git merge avar/orange
-</pre>
-<p>And then push back to the repository:
-</p>
-<pre class="verbatim"> % git push origin blead
-</pre>
-<hr>
-<a name="perlgit-Using-a-smoke_002dme-branch-to-test-changes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgit-A-note-on-camel-and-dromedary" accesskey="n"
rel="next">perlgit A note on camel and dromedary</a>, Previous: <a
href="#perlgit-Merging-from-a-branch-via-GitHub" accesskey="p"
rel="prev">perlgit Merging from a branch via GitHub</a>, Up: <a
href="#perlgit-WRITE-ACCESS-TO-THE-GIT-REPOSITORY" accesskey="u"
rel="up">perlgit WRITE ACCESS TO THE GIT REPOSITORY</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-a-smoke_002dme-branch-to-test-changes"></a>
-<h4 class="subsection">26.5.6 Using a smoke-me branch to test changes</h4>
-
-<p>Sometimes a change affects code paths which you cannot test on the OSes
-which are directly available to you and it would be wise to have users
-on other OSes test the change before you commit it to blead.
-</p>
-<p>Fortunately, there is a way to get your change smoke-tested on various
-OSes: push it to a "smoke-me" branch and wait for certain automated
-smoke-testers to report the results from their OSes.
-</p>
-<p>The procedure for doing this is roughly as follows (using the example of
-of tonyc’s smoke-me branch called win32stat):
-</p>
-<p>First, make a local branch and switch to it:
-</p>
-<pre class="verbatim"> % git checkout -b win32stat
-</pre>
-<p>Make some changes, build perl and test your changes, then commit them to
-your local branch. Then push your local branch to a remote smoke-me
-branch:
-</p>
-<pre class="verbatim"> % git push origin win32stat:smoke-me/tonyc/win32stat
-</pre>
-<p>Now you can switch back to blead locally:
-</p>
-<pre class="verbatim"> % git checkout blead
-</pre>
-<p>and continue working on other things while you wait a day or two,
-keeping an eye on the results reported for your smoke-me branch at
-<a
href="http://perl.develop-help.com/?b=smoke-me/tonyc/win32state";>http://perl.develop-help.com/?b=smoke-me/tonyc/win32state</a>.
-</p>
-<p>If all is well then update your blead branch:
-</p>
-<pre class="verbatim"> % git pull
-</pre>
-<p>then checkout your smoke-me branch once more and rebase it on blead:
-</p>
-<pre class="verbatim"> % git rebase blead win32stat
-</pre>
-<p>Now switch back to blead and merge your smoke-me branch into it:
-</p>
-<pre class="verbatim"> % git checkout blead
- % git merge win32stat
-</pre>
-<p>As described earlier, if there are many changes on your smoke-me branch
-then you should prepare a merge commit in which to give an overview of
-those changes by using the following command instead of the last
-command above:
-</p>
-<pre class="verbatim"> % git merge win32stat --no-ff --no-commit
-</pre>
-<p>You should now build perl and test your (merged) changes one last time
-(ideally run the whole test suite, but failing that at least run the
-<samp>t/porting/*.t</samp> tests) before pushing your changes as usual:
-</p>
-<pre class="verbatim"> % git push origin blead
-</pre>
-<p>Finally, you should then delete the remote smoke-me branch:
-</p>
-<pre class="verbatim"> % git push origin :smoke-me/tonyc/win32stat
-</pre>
-<p>(which is likely to produce a warning like this, which can be ignored:
-</p>
-<pre class="verbatim"> remote: fatal: ambiguous argument
'refs/heads/smoke-me/tonyc/win32stat':
- unknown revision or path not in the working tree.
- remote: Use '--' to separate paths from revisions
-</pre>
-<p>) and then delete your local branch:
-</p>
-<pre class="verbatim"> % git branch -d win32stat
-</pre>
-<hr>
-<a name="perlgit-A-note-on-camel-and-dromedary"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlgit-Using-a-smoke_002dme-branch-to-test-changes"
accesskey="p" rel="prev">perlgit Using a smoke-me branch to test changes</a>,
Up: <a href="#perlgit-WRITE-ACCESS-TO-THE-GIT-REPOSITORY" accesskey="u"
rel="up">perlgit WRITE ACCESS TO THE GIT REPOSITORY</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="A-note-on-camel-and-dromedary"></a>
-<h4 class="subsection">26.5.7 A note on camel and dromedary</h4>
-
-<p>The committers have SSH access to the two servers that serve
-<code>perl5.git.perl.org</code>. One is <code>perl5.git.perl.org</code> itself
(<em>camel</em>),
-which is the ’master’ repository. The second one is
-<code>users.perl5.git.perl.org</code> (<em>dromedary</em>), 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
-<code>http://users.perl5.git.perl.org/~yourlogin/</code>
-</p>
-<p>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.
-</p>
-<p>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
-<code>address@hidden</code>.
-</p>
-<hr>
-<a name="perlgpl"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts" accesskey="n" rel="next">perlguts</a>, Previous: <a
href="#perlgit" accesskey="p" rel="prev">perlgit</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlgpl-1"></a>
-<h2 class="chapter">27 perlgpl</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlgpl-NAME"
accesskey="1">perlgpl NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlgpl-SYNOPSIS"
accesskey="2">perlgpl SYNOPSIS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlgpl-DESCRIPTION"
accesskey="3">perlgpl DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlgpl-GNU-GENERAL-PUBLIC-LICENSE" accesskey="4">perlgpl GNU GENERAL
PUBLIC LICENSE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlgpl-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgpl-SYNOPSIS" accesskey="n" rel="next">perlgpl
SYNOPSIS</a>, Up: <a href="#perlgpl" accesskey="u" rel="up">perlgpl</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-26"></a>
-<h3 class="section">27.1 NAME</h3>
-
-<p>perlgpl - the GNU General Public License, version 1
-</p>
-<hr>
-<a name="perlgpl-SYNOPSIS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgpl-DESCRIPTION" accesskey="n" rel="next">perlgpl
DESCRIPTION</a>, Previous: <a href="#perlgpl-NAME" accesskey="p"
rel="prev">perlgpl NAME</a>, Up: <a href="#perlgpl" accesskey="u"
rel="up">perlgpl</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SYNOPSIS-6"></a>
-<h3 class="section">27.2 SYNOPSIS</h3>
-
-<pre class="verbatim"> You can refer to this document in Pod via
"L<perlgpl>"
- Or you can see this document by entering "perldoc perlgpl"
-</pre>
-<hr>
-<a name="perlgpl-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlgpl-GNU-GENERAL-PUBLIC-LICENSE" accesskey="n"
rel="next">perlgpl GNU GENERAL PUBLIC LICENSE</a>, Previous: <a
href="#perlgpl-SYNOPSIS" accesskey="p" rel="prev">perlgpl SYNOPSIS</a>, Up: <a
href="#perlgpl" accesskey="u" rel="up">perlgpl</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-26"></a>
-<h3 class="section">27.3 DESCRIPTION</h3>
-
-<p>Perl is free software; you can redistribute it and/or modify
-it under the terms of either:
-</p>
-<pre class="verbatim"> a) the GNU General Public License as published
by the Free
- Software Foundation; either version 1, or (at your option) any
- later version, or
-
- b) the "Artistic License" which comes with this Kit.
-</pre>
-<p>This is the <strong>"GNU General Public License, version
1"</strong>.
-It’s here so that modules, programs, etc., that want to declare
-this as their distribution license can link to it.
-</p>
-<p>For the Perl Artistic License, see <a
href="#perlartistic-NAME">perlartistic NAME</a>.
-</p>
-<hr>
-<a name="perlgpl-GNU-GENERAL-PUBLIC-LICENSE"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlgpl-DESCRIPTION" accesskey="p" rel="prev">perlgpl
DESCRIPTION</a>, Up: <a href="#perlgpl" accesskey="u" rel="up">perlgpl</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="GNU-GENERAL-PUBLIC-LICENSE"></a>
-<h3 class="section">27.4 GNU GENERAL PUBLIC LICENSE</h3>
-
-<pre class="verbatim"> GNU GENERAL PUBLIC LICENSE
- Version 1, February 1989
-
- Copyright (C) 1989 Free Software Foundation, Inc.
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
- Preamble
-
- The license agreements of most software companies try to keep users
- at the mercy of those companies. By contrast, our General Public
- License is intended to guarantee your freedom to share and change free
- software--to make sure the software is free for all its users. The
- General Public License applies to the Free Software Foundation's
- software and to any other program whose authors commit to using it.
- You can use it for your programs, too.
-
- When we speak of free software, we are referring to freedom, not
- price. Specifically, the General Public License is designed to make
- sure that you have the freedom to give away or sell copies of free
- software, that you receive source code or can get it if you want it,
- that you can change the software or use pieces of it in new free
- programs; and that you know you can do these things.
-
- To protect your rights, we need to make restrictions that forbid
- anyone to deny you these rights or to ask you to surrender the rights.
- These restrictions translate to certain responsibilities for you if you
- distribute copies of the software, or if you modify it.
-
- For example, if you distribute copies of a such a program, whether
- gratis or for a fee, you must give the recipients all the rights that
- you have. You must make sure that they, too, receive or can get the
- source code. And you must tell them their rights.
-
- We protect your rights with two steps: (1) copyright the software, and
- (2) offer you this license which gives you legal permission to copy,
- distribute and/or modify the software.
-
- Also, for each author's protection and ours, we want to make certain
- that everyone understands that there is no warranty for this free
- software. If the software is modified by someone else and passed on, we
- want its recipients to know that what they have is not the original, so
- that any problems introduced by others will not reflect on the original
- authors' reputations.
-
- The precise terms and conditions for copying, distribution and
- modification follow.
-
- GNU GENERAL PUBLIC LICENSE
- TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
- 0. This License Agreement applies to any program or other work which
- contains a notice placed by the copyright holder saying it may be
- distributed under the terms of this General Public License. The
- "Program", below, refers to any such program or work, and a
"work based
- on the Program" means either the Program or any work containing the
- Program or a portion of it, either verbatim or with modifications. Each
- licensee is addressed as "you".
-
- 1. You may copy and distribute verbatim copies of the Program's source
- code as you receive it, in any medium, provided that you conspicuously and
- appropriately publish on each copy an appropriate copyright notice and
- disclaimer of warranty; keep intact all the notices that refer to this
- General Public License and to the absence of any warranty; and give any
- other recipients of the Program a copy of this General Public License
- along with the Program. You may charge a fee for the physical act of
- transferring a copy.
-
- 2. You may modify your copy or copies of the Program or any portion of
- it, and copy and distribute such modifications under the terms of Paragraph
- 1 above, provided that you also do the following:
-
- a) cause the modified files to carry prominent notices stating that
- you changed the files and the date of any change; and
-
- b) cause the whole of any work that you distribute or publish, that
- in whole or in part contains the Program or any part thereof, either
- with or without modifications, to be licensed at no charge to all
- third parties under the terms of this General Public License (except
- that you may choose to grant warranty protection to some or all
- third parties, at your option).
-
- c) If the modified program normally reads commands interactively when
- run, you must cause it, when started running for such interactive use
- in the simplest and most usual way, to print or display an
- announcement including an appropriate copyright notice and a notice
- that there is no warranty (or else, saying that you provide a
- warranty) and that users may redistribute the program under these
- conditions, and telling the user how to view a copy of this General
- Public License.
-
- d) You may charge a fee for the physical act of transferring a
- copy, and you may at your option offer warranty protection in
- exchange for a fee.
-
- Mere aggregation of another independent work with the Program (or its
- derivative) on a volume of a storage or distribution medium does not bring
- the other work under the scope of these terms.
-
- 3. You may copy and distribute the Program (or a portion or derivative of
- it, under Paragraph 2) in object code or executable form under the terms of
- Paragraphs 1 and 2 above provided that you also do one of the following:
-
- a) accompany it with the complete corresponding machine-readable
- source code, which must be distributed under the terms of
- Paragraphs 1 and 2 above; or,
-
- b) accompany it with a written offer, valid for at least three
- years, to give any third party free (except for a nominal charge
- for the cost of distribution) a complete machine-readable copy of the
- corresponding source code, to be distributed under the terms of
- Paragraphs 1 and 2 above; or,
-
- c) accompany it with the information you received as to where the
- corresponding source code may be obtained. (This alternative is
- allowed only for noncommercial distribution and only if you
- received the program in object code or executable form alone.)
-
- Source code for a work means the preferred form of the work for making
- modifications to it. For an executable file, complete source code means
- all the source code for all modules it contains; but, as a special
- exception, it need not include source code for modules which are standard
- libraries that accompany the operating system on which the executable
- file runs, or for standard header files or definitions files that
- accompany that operating system.
-
- 4. You may not copy, modify, sublicense, distribute or transfer the
- Program except as expressly provided under this General Public License.
- Any attempt otherwise to copy, modify, sublicense, distribute or transfer
- the Program is void, and will automatically terminate your rights to use
- the Program under this License. However, parties who have received
- copies, or rights to use copies, from you under this General Public
- License will not have their licenses terminated so long as such parties
- remain in full compliance.
-
- 5. By copying, distributing or modifying the Program (or any work based
- on the Program) you indicate your acceptance of this license to do so,
- and all its terms and conditions.
-
- 6. Each time you redistribute the Program (or any work based on the
- Program), the recipient automatically receives a license from the original
- licensor to copy, distribute or modify the Program subject to these
- terms and conditions. You may not impose any further restrictions on the
- recipients' exercise of the rights granted herein.
-
- 7. The Free Software Foundation may publish revised and/or new versions
- of the General Public License from time to time. Such new versions will
- be similar in spirit to the present version, but may differ in detail to
- address new problems or concerns.
-
- Each version is given a distinguishing version number. If the Program
- specifies a version number of the license which applies to it and "any
- later version", you have the option of following the terms and conditions
- either of that version or of any later version published by the Free
- Software Foundation. If the Program does not specify a version number of
- the license, you may choose any version ever published by the Free Software
- Foundation.
-
- 8. If you wish to incorporate parts of the Program into other free
- programs whose distribution conditions are different, write to the author
- to ask for permission. For software which is copyrighted by the Free
- Software Foundation, write to the Free Software Foundation; we sometimes
- make exceptions for this. Our decision will be guided by the two goals
- of preserving the free status of all derivatives of our free software and
- of promoting the sharing and reuse of software generally.
-
- NO WARRANTY
-
- 9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
- FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
- OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
- PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED
- OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
- MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
- TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
- PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
- REPAIR OR CORRECTION.
-
- 10. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
- WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
- REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
- INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
- OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
- TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
- YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
- PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
- POSSIBILITY OF SUCH DAMAGES.
-
- END OF TERMS AND CONDITIONS
-
- Appendix: How to Apply These Terms to Your New Programs
-
- If you develop a new program, and you want it to be of the greatest
- possible use to humanity, the best way to achieve this is to make it
- free software which everyone can redistribute and change under these
- terms.
-
- To do so, attach the following notices to the program. It is safest to
- attach them to the start of each source file to most effectively convey
- the exclusion of warranty; and each file should have at least the
- "copyright" line and a pointer to where the full notice is found.
-
- <one line to give the program's name and a brief idea of what it
does.>
- Copyright (C) 19yy <name of author>
-
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 1, or (at your option)
- any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA
- 02110-1301 USA
-
-
- Also add information on how to contact you by electronic and paper mail.
-
- If the program is interactive, make it output a short notice like this
- when it starts in an interactive mode:
-
- Gnomovision version 69, Copyright (C) 19xx name of author
- Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
- This is free software, and you are welcome to redistribute it
- under certain conditions; type 'show c' for details.
-
- The hypothetical commands 'show w' and 'show c' should show the
- appropriate parts of the General Public License. Of course, the
- commands you use may be called something other than 'show w' and 'show
- c'; they could even be mouse-clicks or menu items--whatever suits your
- program.
-
- You should also get your employer (if you work as a programmer) or your
- school, if any, to sign a "copyright disclaimer" for the program, if
- necessary. Here a sample; alter the names:
-
- Yoyodyne, Inc., hereby disclaims all copyright interest in the
- program 'Gnomovision' (a program to direct compilers to make passes
- at assemblers) written by James Hacker.
-
- <signature of Ty Coon>, 1 April 1989
- Ty Coon, President of Vice
-
- That's all there is to it!
-</pre>
-<hr>
-<a name="perlguts"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack" accesskey="n" rel="next">perlhack</a>, Previous: <a
href="#perlgpl" accesskey="p" rel="prev">perlgpl</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlguts-1"></a>
-<h2 class="chapter">28 perlguts</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlguts-NAME"
accesskey="1">perlguts NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-DESCRIPTION"
accesskey="2">perlguts DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-Variables"
accesskey="3">perlguts Variables</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-Subroutines"
accesskey="4">perlguts Subroutines</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-Memory-Allocation"
accesskey="5">perlguts Memory Allocation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-PerlIO"
accesskey="6">perlguts PerlIO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-Compiled-code"
accesskey="7">perlguts Compiled code</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Examining-internal-data-structures-with-the-dump-functions"
accesskey="8">perlguts Examining internal data structures with the
<code>dump</code> functions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-How-multiple-interpreters-and-concurrency-are-supported"
accesskey="9">perlguts How multiple interpreters and concurrency are
supported</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Internal-Functions">perlguts Internal
Functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Unicode-Support">perlguts Unicode
Support</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Custom-Operators">perlguts Custom
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-AUTHORS">perlguts
AUTHORS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-SEE-ALSO">perlguts
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlguts-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-DESCRIPTION" accesskey="n" rel="next">perlguts
DESCRIPTION</a>, Up: <a href="#perlguts" accesskey="u" rel="up">perlguts</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-27"></a>
-<h3 class="section">28.1 NAME</h3>
-
-<p>perlguts - Introduction to the Perl API
-</p>
-<hr>
-<a name="perlguts-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Variables" accesskey="n" rel="next">perlguts
Variables</a>, Previous: <a href="#perlguts-NAME" accesskey="p"
rel="prev">perlguts NAME</a>, Up: <a href="#perlguts" accesskey="u"
rel="up">perlguts</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-27"></a>
-<h3 class="section">28.2 DESCRIPTION</h3>
-
-<p>This document attempts to describe how to use the Perl API, as well as
-to provide some info on the basic workings of the Perl core. It is far
-from complete and probably contains many errors. Please refer any
-questions or comments to the author below.
-</p>
-<hr>
-<a name="perlguts-Variables"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Subroutines" accesskey="n" rel="next">perlguts
Subroutines</a>, Previous: <a href="#perlguts-DESCRIPTION" accesskey="p"
rel="prev">perlguts DESCRIPTION</a>, Up: <a href="#perlguts" accesskey="u"
rel="up">perlguts</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Variables"></a>
-<h3 class="section">28.3 Variables</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlguts-Datatypes"
accesskey="1">perlguts Datatypes</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-What-is-an-_0022IV_0022_003f" accesskey="2">perlguts What is an
"IV"?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-Working-with-SVs"
accesskey="3">perlguts Working with SVs</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-Offsets"
accesskey="4">perlguts Offsets</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-What_0027s-Really-Stored-in-an-SV_003f" accesskey="5">perlguts
What's Really Stored in an SV?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-Working-with-AVs"
accesskey="6">perlguts Working with AVs</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-Working-with-HVs"
accesskey="7">perlguts Working with HVs</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Hash-API-Extensions" accesskey="8">perlguts Hash API
Extensions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-AVs_002c-HVs-and-undefined-values" accesskey="9">perlguts AVs,
HVs and undefined values</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-References">perlguts
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Blessed-References-and-Class-Objects">perlguts Blessed
References and Class Objects</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Creating-New-Variables">perlguts Creating New
Variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Reference-Counts-and-Mortality">perlguts Reference Counts and
Mortality</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Stashes-and-Globs">perlguts Stashes and
Globs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Double_002dTyped-SVs">perlguts Double-Typed
SVs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Read_002dOnly-Values">perlguts Read-Only
Values</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Copy-on-Write">perlguts Copy on
Write</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Magic-Variables">perlguts Magic
Variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Assigning-Magic">perlguts Assigning
Magic</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Magic-Virtual-Tables">perlguts Magic Virtual
Tables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Finding-Magic">perlguts Finding
Magic</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Understanding-the-Magic-of-Tied-Hashes-and-Arrays">perlguts
Understanding the Magic of Tied Hashes and
Arrays</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Localizing-changes">perlguts Localizing
changes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlguts-Datatypes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-What-is-an-_0022IV_0022_003f" accesskey="n"
rel="next">perlguts What is an "IV"?</a>, Up: <a
href="#perlguts-Variables" accesskey="u" rel="up">perlguts Variables</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Datatypes"></a>
-<h4 class="subsection">28.3.1 Datatypes</h4>
-
-<p>Perl has three typedefs that handle Perl’s three main data types:
-</p>
-<pre class="verbatim"> SV Scalar Value
- AV Array Value
- HV Hash Value
-</pre>
-<p>Each typedef has specific routines that manipulate the various data types.
-</p>
-<hr>
-<a name="perlguts-What-is-an-_0022IV_0022_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Working-with-SVs" accesskey="n" rel="next">perlguts
Working with SVs</a>, Previous: <a href="#perlguts-Datatypes" accesskey="p"
rel="prev">perlguts Datatypes</a>, Up: <a href="#perlguts-Variables"
accesskey="u" rel="up">perlguts Variables</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="What-is-an-_0022IV_0022_003f"></a>
-<h4 class="subsection">28.3.2 What is an "IV"?</h4>
-
-<p>Perl uses a special typedef IV which is a simple signed integer type that is
-guaranteed to be large enough to hold a pointer (as well as an integer).
-Additionally, there is the UV, which is simply an unsigned IV.
-</p>
-<p>Perl also uses two special typedefs, I32 and I16, which will always be at
-least 32-bits and 16-bits long, respectively. (Again, there are U32 and U16,
-as well.) They will usually be exactly 32 and 16 bits long, but on Crays
-they will both be 64 bits.
-</p>
-<hr>
-<a name="perlguts-Working-with-SVs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Offsets" accesskey="n" rel="next">perlguts
Offsets</a>, Previous: <a href="#perlguts-What-is-an-_0022IV_0022_003f"
accesskey="p" rel="prev">perlguts What is an "IV"?</a>, Up: <a
href="#perlguts-Variables" accesskey="u" rel="up">perlguts Variables</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Working-with-SVs"></a>
-<h4 class="subsection">28.3.3 Working with SVs</h4>
-
-<p>An SV can be created and loaded with one command. There are five types of
-values that can be loaded: an integer value (IV), an unsigned integer
-value (UV), a double (NV), a string (PV), and another scalar (SV).
-("PV" stands for "Pointer Value". You might think that it
is misnamed
-because it is described as pointing only to strings. However, it is
-possible to have it point to other things. For example, it could point
-to an array of UVs. But,
-using it for non-strings requires care, as the underlying assumption of
-much of the internals is that PVs are just for strings. Often, for
-example, a trailing <code>NUL</code> is tacked on automatically. The
non-string use
-is documented only in this paragraph.)
-</p>
-<p>The seven routines are:
-</p>
-<pre class="verbatim"> SV* newSViv(IV);
- SV* newSVuv(UV);
- SV* newSVnv(double);
- SV* newSVpv(const char*, STRLEN);
- SV* newSVpvn(const char*, STRLEN);
- SV* newSVpvf(const char*, ...);
- SV* newSVsv(SV*);
-</pre>
-<p><code>STRLEN</code> is an integer type (Size_t, usually defined as size_t in
-<samp>config.h</samp>) guaranteed to be large enough to represent the size of
-any string that perl can handle.
-</p>
-<p>In the unlikely case of a SV requiring more complex initialization, you
-can create an empty SV with newSV(len). If <code>len</code> is 0 an empty SV
of
-type NULL is returned, else an SV of type PV is returned with len + 1 (for
-the <code>NUL</code>) bytes of storage allocated, accessible via SvPVX. In
both cases
-the SV has the undef value.
-</p>
-<pre class="verbatim"> SV *sv = newSV(0); /* no storage allocated */
- SV *sv = newSV(10); /* 10 (+1) bytes of uninitialised storage
- * allocated */
-</pre>
-<p>To change the value of an <em>already-existing</em> SV, there are eight
routines:
-</p>
-<pre class="verbatim"> void sv_setiv(SV*, IV);
- void sv_setuv(SV*, UV);
- void sv_setnv(SV*, double);
- void sv_setpv(SV*, const char*);
- void sv_setpvn(SV*, const char*, STRLEN)
- void sv_setpvf(SV*, const char*, ...);
- void sv_vsetpvfn(SV*, const char*, STRLEN, va_list *,
- SV **, I32, bool *);
- void sv_setsv(SV*, SV*);
-</pre>
-<p>Notice that you can choose to specify the length of the string to be
-assigned by using <code>sv_setpvn</code>, <code>newSVpvn</code>, or
<code>newSVpv</code>, or you may
-allow Perl to calculate the length by using <code>sv_setpv</code> or by
specifying
-0 as the second argument to <code>newSVpv</code>. Be warned, though, that
Perl will
-determine the string’s length by using <code>strlen</code>, which
depends on the
-string terminating with a <code>NUL</code> character, and not otherwise
containing
-NULs.
-</p>
-<p>The arguments of <code>sv_setpvf</code> are processed like
<code>sprintf</code>, and the
-formatted output becomes the value.
-</p>
-<p><code>sv_vsetpvfn</code> is an analogue of <code>vsprintf</code>, but it
allows you to specify
-either a pointer to a variable argument list or the address and length of
-an array of SVs. The last argument points to a boolean; on return, if that
-boolean is true, then locale-specific information has been used to format
-the string, and the string’s contents are therefore untrustworthy (see
-<a href="#perlsec-NAME">perlsec NAME</a>). This pointer may be NULL if that
information is not
-important. Note that this function requires you to specify the length of
-the format.
-</p>
-<p>The <code>sv_set*()</code> functions are not generic enough to operate on
values
-that have "magic". See <a
href="#perlguts-Magic-Virtual-Tables">Magic Virtual Tables</a> later in this
document.
-</p>
-<p>All SVs that contain strings should be terminated with a <code>NUL</code>
character.
-If it is not <code>NUL</code>-terminated there is a risk of
-core dumps and corruptions from code which passes the string to C
-functions or system calls which expect a <code>NUL</code>-terminated string.
-Perl’s own functions typically add a trailing <code>NUL</code> for this
reason.
-Nevertheless, you should be very careful when you pass a string stored
-in an SV to a C function or system call.
-</p>
-<p>To access the actual value that an SV points to, you can use the macros:
-</p>
-<pre class="verbatim"> SvIV(SV*)
- SvUV(SV*)
- SvNV(SV*)
- SvPV(SV*, STRLEN len)
- SvPV_nolen(SV*)
-</pre>
-<p>which will automatically coerce the actual scalar type into an IV, UV,
double,
-or string.
-</p>
-<p>In the <code>SvPV</code> macro, the length of the string returned is placed
into the
-variable <code>len</code> (this is a macro, so you do <em>not</em> use
<code>&len</code>). If you do
-not care what the length of the data is, use the <code>SvPV_nolen</code> macro.
-Historically the <code>SvPV</code> macro with the global variable
<code>PL_na</code> has been
-used in this case. But that can be quite inefficient because
<code>PL_na</code> must
-be accessed in thread-local storage in threaded Perl. In any case, remember
-that Perl allows arbitrary strings of data that may both contain NULs and
-might not be terminated by a <code>NUL</code>.
-</p>
-<p>Also remember that C doesn’t allow you to safely say
<code>foo(SvPV(s, len),
-len);</code>. It might work with your
-compiler, but it won’t work for everyone.
-Break this sort of statement up into separate assignments:
-</p>
-<pre class="verbatim"> SV *s;
- STRLEN len;
- char *ptr;
- ptr = SvPV(s, len);
- foo(ptr, len);
-</pre>
-<p>If you want to know if the scalar value is TRUE, you can use:
-</p>
-<pre class="verbatim"> SvTRUE(SV*)
-</pre>
-<p>Although Perl will automatically grow strings for you, if you need to force
-Perl to allocate more memory for your SV, you can use the macro
-</p>
-<pre class="verbatim"> SvGROW(SV*, STRLEN newlen)
-</pre>
-<p>which will determine if more memory needs to be allocated. If so, it will
-call the function <code>sv_grow</code>. Note that <code>SvGROW</code> can
only increase, not
-decrease, the allocated memory of an SV and that it does not automatically
-add space for the trailing <code>NUL</code> byte (perl’s own string
functions typically do
-<code>SvGROW(sv, len + 1)</code>).
-</p>
-<p>If you want to write to an existing SV’s buffer and set its value to a
-string, use SvPV_force() or one of its variants to force the SV to be
-a PV. This will remove any of various types of non-stringness from
-the SV while preserving the content of the SV in the PV. This can be
-used, for example, to append data from an API function to a buffer
-without extra copying:
-</p>
-<pre class="verbatim"> (void)SvPVbyte_force(sv, len);
- s = SvGROW(sv, len + needlen + 1);
- /* something that modifies up to needlen bytes at s+len, but
- modifies newlen bytes
- eg. newlen = read(fd, s + len, needlen);
- ignoring errors for these examples
- */
- s[len + newlen] = '\0';
- SvCUR_set(sv, len + newlen);
- SvUTF8_off(sv);
- SvSETMAGIC(sv);
-</pre>
-<p>If you already have the data in memory or if you want to keep your
-code simple, you can use one of the sv_cat*() variants, such as
-sv_catpvn(). If you want to insert anywhere in the string you can use
-sv_insert() or sv_insert_flags().
-</p>
-<p>If you don’t need the existing content of the SV, you can avoid some
-copying with:
-</p>
-<pre class="verbatim"> sv_setpvn(sv, "", 0);
- s = SvGROW(sv, needlen + 1);
- /* something that modifies up to needlen bytes at s, but modifies
- newlen bytes
- eg. newlen = read(fd, s. needlen);
- */
- s[newlen] = '\0';
- SvCUR_set(sv, newlen);
- SvPOK_only(sv); /* also clears SVf_UTF8 */
- SvSETMAGIC(sv);
-</pre>
-<p>Again, if you already have the data in memory or want to avoid the
-complexity of the above, you can use sv_setpvn().
-</p>
-<p>If you have a buffer allocated with Newx() and want to set that as the
-SV’s value, you can use sv_usepvn_flags(). That has some requirements
-if you want to avoid perl re-allocating the buffer to fit the trailing
-NUL:
-</p>
-<pre class="verbatim"> Newx(buf, somesize+1, char);
- /* ... fill in buf ... */
- buf[somesize] = '\0';
- sv_usepvn_flags(sv, buf, somesize, SV_SMAGIC | SV_HAS_TRAILING_NUL);
- /* buf now belongs to perl, don't release it */
-</pre>
-<p>If you have an SV and want to know what kind of data Perl thinks is stored
-in it, you can use the following macros to check the type of SV you have.
-</p>
-<pre class="verbatim"> SvIOK(SV*)
- SvNOK(SV*)
- SvPOK(SV*)
-</pre>
-<p>You can get and set the current length of the string stored in an SV with
-the following macros:
-</p>
-<pre class="verbatim"> SvCUR(SV*)
- SvCUR_set(SV*, I32 val)
-</pre>
-<p>You can also get a pointer to the end of the string stored in the SV
-with the macro:
-</p>
-<pre class="verbatim"> SvEND(SV*)
-</pre>
-<p>But note that these last three macros are valid only if
<code>SvPOK()</code> is true.
-</p>
-<p>If you want to append something to the end of string stored in an
<code>SV*</code>,
-you can use the following functions:
-</p>
-<pre class="verbatim"> void sv_catpv(SV*, const char*);
- void sv_catpvn(SV*, const char*, STRLEN);
- void sv_catpvf(SV*, const char*, ...);
- void sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **,
- I32, bool);
- void sv_catsv(SV*, SV*);
-</pre>
-<p>The first function calculates the length of the string to be appended by
-using <code>strlen</code>. In the second, you specify the length of the string
-yourself. The third function processes its arguments like
<code>sprintf</code> and
-appends the formatted output. The fourth function works like
<code>vsprintf</code>.
-You can specify the address and length of an array of SVs instead of the
-va_list argument. The fifth function
-extends the string stored in the first
-SV with the string stored in the second SV. It also forces the second SV
-to be interpreted as a string.
-</p>
-<p>The <code>sv_cat*()</code> functions are not generic enough to operate on
values that
-have "magic". See <a href="#perlguts-Magic-Virtual-Tables">Magic
Virtual Tables</a> later in this document.
-</p>
-<p>If you know the name of a scalar variable, you can get a pointer to its SV
-by using the following:
-</p>
-<pre class="verbatim"> SV* get_sv("package::varname", 0);
-</pre>
-<p>This returns NULL if the variable does not exist.
-</p>
-<p>If you want to know if this variable (or any other SV) is actually
<code>defined</code>,
-you can call:
-</p>
-<pre class="verbatim"> SvOK(SV*)
-</pre>
-<p>The scalar <code>undef</code> value is stored in an SV instance called
<code>PL_sv_undef</code>.
-</p>
-<p>Its address can be used whenever an <code>SV*</code> is needed. Make sure
that
-you don’t try to compare a random sv with <code>&PL_sv_undef</code>.
For example
-when interfacing Perl code, it’ll work correctly for:
-</p>
-<pre class="verbatim"> foo(undef);
-</pre>
-<p>But won’t work when called as:
-</p>
-<pre class="verbatim"> $x = undef;
- foo($x);
-</pre>
-<p>So to repeat always use SvOK() to check whether an sv is defined.
-</p>
-<p>Also you have to be careful when using <code>&PL_sv_undef</code> as a
value in
-AVs or HVs (see <a href="#perlguts-AVs_002c-HVs-and-undefined-values">AVs, HVs
and undefined values</a>).
-</p>
-<p>There are also the two values <code>PL_sv_yes</code> and
<code>PL_sv_no</code>, which contain
-boolean TRUE and FALSE values, respectively. Like <code>PL_sv_undef</code>,
their
-addresses can be used whenever an <code>SV*</code> is needed.
-</p>
-<p>Do not be fooled into thinking that <code>(SV *) 0</code> is the same as
<code>&PL_sv_undef</code>.
-Take this code:
-</p>
-<pre class="verbatim"> SV* sv = (SV*) 0;
- if (I-am-to-return-a-real-value) {
- sv = sv_2mortal(newSViv(42));
- }
- sv_setsv(ST(0), sv);
-</pre>
-<p>This code tries to return a new SV (which contains the value 42) if it
should
-return a real value, or undef otherwise. Instead it has returned a NULL
-pointer which, somewhere down the line, will cause a segmentation violation,
-bus error, or just weird results. Change the zero to
<code>&PL_sv_undef</code> in the
-first line and all will be well.
-</p>
-<p>To free an SV that you’ve created, call
<code>SvREFCNT_dec(SV*)</code>. Normally this
-call is not necessary (see <a
href="#perlguts-Reference-Counts-and-Mortality">Reference Counts and
Mortality</a>).
-</p>
-<hr>
-<a name="perlguts-Offsets"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-What_0027s-Really-Stored-in-an-SV_003f" accesskey="n"
rel="next">perlguts What's Really Stored in an SV?</a>, Previous: <a
href="#perlguts-Working-with-SVs" accesskey="p" rel="prev">perlguts Working
with SVs</a>, Up: <a href="#perlguts-Variables" accesskey="u" rel="up">perlguts
Variables</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Offsets"></a>
-<h4 class="subsection">28.3.4 Offsets</h4>
-
-<p>Perl provides the function <code>sv_chop</code> to efficiently remove
characters
-from the beginning of a string; you give it an SV and a pointer to
-somewhere inside the PV, and it discards everything before the
-pointer. The efficiency comes by means of a little hack: instead of
-actually removing the characters, <code>sv_chop</code> sets the flag
<code>OOK</code>
-(offset OK) to signal to other functions that the offset hack is in
-effect, and it moves the PV pointer (called <code>SvPVX</code>) forward
-by the number of bytes chopped off, and adjusts <code>SvCUR</code> and
<code>SvLEN</code>
-accordingly. (A portion of the space between the old and new PV
-pointers is used to store the count of chopped bytes.)
-</p>
-<p>Hence, at this point, the start of the buffer that we allocated lives
-at <code>SvPVX(sv) - SvIV(sv)</code> in memory and the PV pointer is pointing
-into the middle of this allocated storage.
-</p>
-<p>This is best demonstrated by example. Normally copy-on-write will prevent
-the substitution from operator from using this hack, but if you can craft a
-string for which copy-on-write is not possible, you can see it in play. In
-the current implementation, the final byte of a string buffer is used as a
-copy-on-write reference count. If the buffer is not big enough, then
-copy-on-write is skipped. First have a look at an empty string:
-</p>
-<pre class="verbatim"> % ./perl -Ilib -MDevel::Peek -le '$a=""; $a
.= ""; Dump $a'
- SV = PV(0x7ffb7c008a70) at 0x7ffb7c030390
- REFCNT = 1
- FLAGS = (POK,pPOK)
- PV = 0x7ffb7bc05b50 ""\0
- CUR = 0
- LEN = 10
-</pre>
-<p>Notice here the LEN is 10. (It may differ on your platform.) Extend the
-length of the string to one less than 10, and do a substitution:
-</p>
-<pre class="verbatim"> % ./perl -Ilib -MDevel::Peek -le '$a="";
$a.="123456789"; $a=~s/.//; Dump($a)'
- SV = PV(0x7ffa04008a70) at 0x7ffa04030390
- REFCNT = 1
- FLAGS = (POK,OOK,pPOK)
- OFFSET = 1
- PV = 0x7ffa03c05b61 ( "\1" . ) "23456789"\0
- CUR = 8
- LEN = 9
-</pre>
-<p>Here the number of bytes chopped off (1) is shown next as the OFFSET. The
-portion of the string between the "real" and the "fake"
beginnings is
-shown in parentheses, and the values of <code>SvCUR</code> and
<code>SvLEN</code> reflect
-the fake beginning, not the real one. (The first character of the string
-buffer happens to have changed to "\1" here, not "1",
because the current
-implementation stores the offset count in the string buffer. This is
-subject to change.)
-</p>
-<p>Something similar to the offset hack is performed on AVs to enable
-efficient shifting and splicing off the beginning of the array; while
-<code>AvARRAY</code> points to the first element in the array that is visible
from
-Perl, <code>AvALLOC</code> points to the real start of the C array. These are
-usually the same, but a <code>shift</code> operation can be carried out by
-increasing <code>AvARRAY</code> by one and decreasing <code>AvFILL</code> and
<code>AvMAX</code>.
-Again, the location of the real start of the C array only comes into
-play when freeing the array. See <code>av_shift</code> in <samp>av.c</samp>.
-</p>
-<hr>
-<a name="perlguts-What_0027s-Really-Stored-in-an-SV_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Working-with-AVs" accesskey="n" rel="next">perlguts
Working with AVs</a>, Previous: <a href="#perlguts-Offsets" accesskey="p"
rel="prev">perlguts Offsets</a>, Up: <a href="#perlguts-Variables"
accesskey="u" rel="up">perlguts Variables</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="What_0027s-Really-Stored-in-an-SV_003f"></a>
-<h4 class="subsection">28.3.5 What’s Really Stored in an SV?</h4>
-
-<p>Recall that the usual method of determining the type of scalar you have is
-to use <code>Sv*OK</code> macros. Because a scalar can be both a number and a
string,
-usually these macros will always return TRUE and calling the <code>Sv*V</code>
-macros will do the appropriate conversion of string to integer/double or
-integer/double to string.
-</p>
-<p>If you <em>really</em> need to know if you have an integer, double, or
string
-pointer in an SV, you can use the following three macros instead:
-</p>
-<pre class="verbatim"> SvIOKp(SV*)
- SvNOKp(SV*)
- SvPOKp(SV*)
-</pre>
-<p>These will tell you if you truly have an integer, double, or string pointer
-stored in your SV. The "p" stands for private.
-</p>
-<p>There are various ways in which the private and public flags may differ.
-For example, in perl 5.16 and earlier a tied SV may have a valid
-underlying value in the IV slot (so SvIOKp is true), but the data
-should be accessed via the FETCH routine rather than directly,
-so SvIOK is false. (In perl 5.18 onwards, tied scalars use
-the flags the same way as untied scalars.) Another is when
-numeric conversion has occurred and precision has been lost: only the
-private flag is set on ’lossy’ values. So when an NV is converted
to an
-IV with loss, SvIOKp, SvNOKp and SvNOK will be set, while SvIOK wont be.
-</p>
-<p>In general, though, it’s best to use the <code>Sv*V</code> macros.
-</p>
-<hr>
-<a name="perlguts-Working-with-AVs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Working-with-HVs" accesskey="n" rel="next">perlguts
Working with HVs</a>, Previous: <a
href="#perlguts-What_0027s-Really-Stored-in-an-SV_003f" accesskey="p"
rel="prev">perlguts What's Really Stored in an SV?</a>, Up: <a
href="#perlguts-Variables" accesskey="u" rel="up">perlguts Variables</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Working-with-AVs"></a>
-<h4 class="subsection">28.3.6 Working with AVs</h4>
-
-<p>There are two ways to create and load an AV. The first method creates an
-empty AV:
-</p>
-<pre class="verbatim"> AV* newAV();
-</pre>
-<p>The second method both creates the AV and initially populates it with SVs:
-</p>
-<pre class="verbatim"> AV* av_make(SSize_t num, SV **ptr);
-</pre>
-<p>The second argument points to an array containing <code>num</code>
<code>SV*</code>’s. Once the
-AV has been created, the SVs can be destroyed, if so desired.
-</p>
-<p>Once the AV has been created, the following operations are possible on it:
-</p>
-<pre class="verbatim"> void av_push(AV*, SV*);
- SV* av_pop(AV*);
- SV* av_shift(AV*);
- void av_unshift(AV*, SSize_t num);
-</pre>
-<p>These should be familiar operations, with the exception of
<code>av_unshift</code>.
-This routine adds <code>num</code> elements at the front of the array with the
<code>undef</code>
-value. You must then use <code>av_store</code> (described below) to assign
values
-to these new elements.
-</p>
-<p>Here are some other functions:
-</p>
-<pre class="verbatim"> SSize_t av_top_index(AV*);
- SV** av_fetch(AV*, SSize_t key, I32 lval);
- SV** av_store(AV*, SSize_t key, SV* val);
-</pre>
-<p>The <code>av_top_index</code> function returns the highest index value in
an array (just
-like $#array in Perl). If the array is empty, -1 is returned. The
-<code>av_fetch</code> function returns the value at index <code>key</code>,
but if <code>lval</code>
-is non-zero, then <code>av_fetch</code> will store an undef value at that
index.
-The <code>av_store</code> function stores the value <code>val</code> at index
<code>key</code>, and does
-not increment the reference count of <code>val</code>. Thus the caller is
responsible
-for taking care of that, and if <code>av_store</code> returns NULL, the caller
will
-have to decrement the reference count to avoid a memory leak. Note that
-<code>av_fetch</code> and <code>av_store</code> both return
<code>SV**</code>’s, not <code>SV*</code>’s as their
-return value.
-</p>
-<p>A few more:
-</p>
-<pre class="verbatim"> void av_clear(AV*);
- void av_undef(AV*);
- void av_extend(AV*, SSize_t key);
-</pre>
-<p>The <code>av_clear</code> function deletes all the elements in the AV*
array, but
-does not actually delete the array itself. The <code>av_undef</code> function
will
-delete all the elements in the array plus the array itself. The
-<code>av_extend</code> function extends the array so that it contains at least
<code>key+1</code>
-elements. If <code>key+1</code> is less than the currently allocated length
of the array,
-then nothing is done.
-</p>
-<p>If you know the name of an array variable, you can get a pointer to its AV
-by using the following:
-</p>
-<pre class="verbatim"> AV* get_av("package::varname", 0);
-</pre>
-<p>This returns NULL if the variable does not exist.
-</p>
-<p>See <a
href="#perlguts-Understanding-the-Magic-of-Tied-Hashes-and-Arrays">Understanding
the Magic of Tied Hashes and Arrays</a> for more
-information on how to use the array access functions on tied arrays.
-</p>
-<hr>
-<a name="perlguts-Working-with-HVs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Hash-API-Extensions" accesskey="n"
rel="next">perlguts Hash API Extensions</a>, Previous: <a
href="#perlguts-Working-with-AVs" accesskey="p" rel="prev">perlguts Working
with AVs</a>, Up: <a href="#perlguts-Variables" accesskey="u" rel="up">perlguts
Variables</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Working-with-HVs"></a>
-<h4 class="subsection">28.3.7 Working with HVs</h4>
-
-<p>To create an HV, you use the following routine:
-</p>
-<pre class="verbatim"> HV* newHV();
-</pre>
-<p>Once the HV has been created, the following operations are possible on it:
-</p>
-<pre class="verbatim"> SV** hv_store(HV*, const char* key, U32 klen, SV*
val, U32 hash);
- SV** hv_fetch(HV*, const char* key, U32 klen, I32 lval);
-</pre>
-<p>The <code>klen</code> parameter is the length of the key being passed in
(Note that
-you cannot pass 0 in as a value of <code>klen</code> to tell Perl to measure
the
-length of the key). The <code>val</code> argument contains the SV pointer to
the
-scalar being stored, and <code>hash</code> is the precomputed hash value (zero
if
-you want <code>hv_store</code> to calculate it for you). The
<code>lval</code> parameter
-indicates whether this fetch is actually a part of a store operation, in
-which case a new undefined value will be added to the HV with the supplied
-key and <code>hv_fetch</code> will return as if the value had already existed.
-</p>
-<p>Remember that <code>hv_store</code> and <code>hv_fetch</code> return
<code>SV**</code>’s and not just
-<code>SV*</code>. To access the scalar value, you must first dereference the
return
-value. However, you should check to make sure that the return value is
-not NULL before dereferencing it.
-</p>
-<p>The first of these two functions checks if a hash table entry exists, and
the
-second deletes it.
-</p>
-<pre class="verbatim"> bool hv_exists(HV*, const char* key, U32 klen);
- SV* hv_delete(HV*, const char* key, U32 klen, I32 flags);
-</pre>
-<p>If <code>flags</code> does not include the <code>G_DISCARD</code> flag then
<code>hv_delete</code> will
-create and return a mortal copy of the deleted value.
-</p>
-<p>And more miscellaneous functions:
-</p>
-<pre class="verbatim"> void hv_clear(HV*);
- void hv_undef(HV*);
-</pre>
-<p>Like their AV counterparts, <code>hv_clear</code> deletes all the entries
in the hash
-table but does not actually delete the hash table. The <code>hv_undef</code>
deletes
-both the entries and the hash table itself.
-</p>
-<p>Perl keeps the actual data in a linked list of structures with a typedef of
HE.
-These contain the actual key and value pointers (plus extra administrative
-overhead). The key is a string pointer; the value is an <code>SV*</code>.
However,
-once you have an <code>HE*</code>, to get the actual key and value, use the
routines
-specified below.
-</p>
-<pre class="verbatim"> I32 hv_iterinit(HV*);
- /* Prepares starting point to traverse hash table */
- HE* hv_iternext(HV*);
- /* Get the next entry, and return a pointer to a
- structure that has both the key and value */
- char* hv_iterkey(HE* entry, I32* retlen);
- /* Get the key from an HE structure and also return
- the length of the key string */
- SV* hv_iterval(HV*, HE* entry);
- /* Return an SV pointer to the value of the HE
- structure */
- SV* hv_iternextsv(HV*, char** key, I32* retlen);
- /* This convenience routine combines hv_iternext,
- hv_iterkey, and hv_iterval. The key and retlen
- arguments are return values for the key and its
- length. The value is returned in the SV* argument */
-</pre>
-<p>If you know the name of a hash variable, you can get a pointer to its HV
-by using the following:
-</p>
-<pre class="verbatim"> HV* get_hv("package::varname", 0);
-</pre>
-<p>This returns NULL if the variable does not exist.
-</p>
-<p>The hash algorithm is defined in the <code>PERL_HASH</code> macro:
-</p>
-<pre class="verbatim"> PERL_HASH(hash, key, klen)
-</pre>
-<p>The exact implementation of this macro varies by architecture and version
-of perl, and the return value may change per invocation, so the value
-is only valid for the duration of a single perl process.
-</p>
-<p>See <a
href="#perlguts-Understanding-the-Magic-of-Tied-Hashes-and-Arrays">Understanding
the Magic of Tied Hashes and Arrays</a> for more
-information on how to use the hash access functions on tied hashes.
-</p>
-<hr>
-<a name="perlguts-Hash-API-Extensions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-AVs_002c-HVs-and-undefined-values" accesskey="n"
rel="next">perlguts AVs, HVs and undefined values</a>, Previous: <a
href="#perlguts-Working-with-HVs" accesskey="p" rel="prev">perlguts Working
with HVs</a>, Up: <a href="#perlguts-Variables" accesskey="u" rel="up">perlguts
Variables</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Hash-API-Extensions"></a>
-<h4 class="subsection">28.3.8 Hash API Extensions</h4>
-
-<p>Beginning with version 5.004, the following functions are also supported:
-</p>
-<pre class="verbatim"> HE* hv_fetch_ent (HV* tb, SV* key, I32 lval,
U32 hash);
- HE* hv_store_ent (HV* tb, SV* key, SV* val, U32 hash);
-
- bool hv_exists_ent (HV* tb, SV* key, U32 hash);
- SV* hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);
-
- SV* hv_iterkeysv (HE* entry);
-</pre>
-<p>Note that these functions take <code>SV*</code> keys, which simplifies
writing
-of extension code that deals with hash structures. These functions
-also allow passing of <code>SV*</code> keys to <code>tie</code> functions
without forcing
-you to stringify the keys (unlike the previous set of functions).
-</p>
-<p>They also return and accept whole hash entries (<code>HE*</code>), making
their
-use more efficient (since the hash number for a particular string
-doesn’t have to be recomputed every time). See <a
href="perlapi.html#Top">(perlapi)</a> for detailed
-descriptions.
-</p>
-<p>The following macros must always be used to access the contents of hash
-entries. Note that the arguments to these macros must be simple
-variables, since they may get evaluated more than once. See
-<a href="perlapi.html#Top">(perlapi)</a> for detailed descriptions of these
macros.
-</p>
-<pre class="verbatim"> HePV(HE* he, STRLEN len)
- HeVAL(HE* he)
- HeHASH(HE* he)
- HeSVKEY(HE* he)
- HeSVKEY_force(HE* he)
- HeSVKEY_set(HE* he, SV* sv)
-</pre>
-<p>These two lower level macros are defined, but must only be used when
-dealing with keys that are not <code>SV*</code>s:
-</p>
-<pre class="verbatim"> HeKEY(HE* he)
- HeKLEN(HE* he)
-</pre>
-<p>Note that both <code>hv_store</code> and <code>hv_store_ent</code> do not
increment the
-reference count of the stored <code>val</code>, which is the caller’s
responsibility.
-If these functions return a NULL value, the caller will usually have to
-decrement the reference count of <code>val</code> to avoid a memory leak.
-</p>
-<hr>
-<a name="perlguts-AVs_002c-HVs-and-undefined-values"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-References" accesskey="n" rel="next">perlguts
References</a>, Previous: <a href="#perlguts-Hash-API-Extensions" accesskey="p"
rel="prev">perlguts Hash API Extensions</a>, Up: <a href="#perlguts-Variables"
accesskey="u" rel="up">perlguts Variables</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AVs_002c-HVs-and-undefined-values"></a>
-<h4 class="subsection">28.3.9 AVs, HVs and undefined values</h4>
-
-<p>Sometimes you have to store undefined values in AVs or HVs. Although
-this may be a rare case, it can be tricky. That’s because you’re
-used to using <code>&PL_sv_undef</code> if you need an undefined SV.
-</p>
-<p>For example, intuition tells you that this XS code:
-</p>
-<pre class="verbatim"> AV *av = newAV();
- av_store( av, 0, &PL_sv_undef );
-</pre>
-<p>is equivalent to this Perl code:
-</p>
-<pre class="verbatim"> my @av;
- $av[0] = undef;
-</pre>
-<p>Unfortunately, this isn’t true. In perl 5.18 and earlier, AVs use
<code>&PL_sv_undef</code> as a marker
-for indicating that an array element has not yet been initialized.
-Thus, <code>exists $av[0]</code> would be true for the above Perl code, but
-false for the array generated by the XS code. In perl 5.20, storing
-&PL_sv_undef will create a read-only element, because the scalar
-&PL_sv_undef itself is stored, not a copy.
-</p>
-<p>Similar problems can occur when storing <code>&PL_sv_undef</code> in
HVs:
-</p>
-<pre class="verbatim"> hv_store( hv, "key", 3, &PL_sv_undef,
0 );
-</pre>
-<p>This will indeed make the value <code>undef</code>, but if you try to modify
-the value of <code>key</code>, you’ll get the following error:
-</p>
-<pre class="verbatim"> Modification of non-creatable hash value attempted
-</pre>
-<p>In perl 5.8.0, <code>&PL_sv_undef</code> was also used to mark
placeholders
-in restricted hashes. This caused such hash entries not to appear
-when iterating over the hash or when checking for the keys
-with the <code>hv_exists</code> function.
-</p>
-<p>You can run into similar problems when you store
<code>&PL_sv_yes</code> or
-<code>&PL_sv_no</code> into AVs or HVs. Trying to modify such elements
-will give you the following error:
-</p>
-<pre class="verbatim"> Modification of a read-only value attempted
-</pre>
-<p>To make a long story short, you can use the special variables
-<code>&PL_sv_undef</code>, <code>&PL_sv_yes</code> and
<code>&PL_sv_no</code> with AVs and
-HVs, but you have to make sure you know what you’re doing.
-</p>
-<p>Generally, if you want to store an undefined value in an AV
-or HV, you should not use <code>&PL_sv_undef</code>, but rather create a
-new undefined value using the <code>newSV</code> function, for example:
-</p>
-<pre class="verbatim"> av_store( av, 42, newSV(0) );
- hv_store( hv, "foo", 3, newSV(0), 0 );
-</pre>
-<hr>
-<a name="perlguts-References"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Blessed-References-and-Class-Objects" accesskey="n"
rel="next">perlguts Blessed References and Class Objects</a>, Previous: <a
href="#perlguts-AVs_002c-HVs-and-undefined-values" accesskey="p"
rel="prev">perlguts AVs, HVs and undefined values</a>, Up: <a
href="#perlguts-Variables" accesskey="u" rel="up">perlguts Variables</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="References-1"></a>
-<h4 class="subsection">28.3.10 References</h4>
-
-<p>References are a special type of scalar that point to other data types
-(including other references).
-</p>
-<p>To create a reference, use either of the following functions:
-</p>
-<pre class="verbatim"> SV* newRV_inc((SV*) thing);
- SV* newRV_noinc((SV*) thing);
-</pre>
-<p>The <code>thing</code> argument can be any of an <code>SV*</code>,
<code>AV*</code>, or <code>HV*</code>. The
-functions are identical except that <code>newRV_inc</code> increments the
reference
-count of the <code>thing</code>, while <code>newRV_noinc</code> does not. For
historical
-reasons, <code>newRV</code> is a synonym for <code>newRV_inc</code>.
-</p>
-<p>Once you have a reference, you can use the following macro to dereference
-the reference:
-</p>
-<pre class="verbatim"> SvRV(SV*)
-</pre>
-<p>then call the appropriate routines, casting the returned <code>SV*</code>
to either an
-<code>AV*</code> or <code>HV*</code>, if required.
-</p>
-<p>To determine if an SV is a reference, you can use the following macro:
-</p>
-<pre class="verbatim"> SvROK(SV*)
-</pre>
-<p>To discover what type of value the reference refers to, use the following
-macro and then check the return value.
-</p>
-<pre class="verbatim"> SvTYPE(SvRV(SV*))
-</pre>
-<p>The most useful types that will be returned are:
-</p>
-<pre class="verbatim"> < SVt_PVAV Scalar
- SVt_PVAV Array
- SVt_PVHV Hash
- SVt_PVCV Code
- SVt_PVGV Glob (possibly a file handle)
-</pre>
-<p>See <a href="perlapi.html#svtype">(perlapi)svtype</a> for more details.
-</p>
-<hr>
-<a name="perlguts-Blessed-References-and-Class-Objects"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Creating-New-Variables" accesskey="n"
rel="next">perlguts Creating New Variables</a>, Previous: <a
href="#perlguts-References" accesskey="p" rel="prev">perlguts References</a>,
Up: <a href="#perlguts-Variables" accesskey="u" rel="up">perlguts Variables</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Blessed-References-and-Class-Objects"></a>
-<h4 class="subsection">28.3.11 Blessed References and Class Objects</h4>
-
-<p>References are also used to support object-oriented programming. In
perl’s
-OO lexicon, an object is simply a reference that has been blessed into a
-package (or class). Once blessed, the programmer may now use the reference
-to access the various methods in the class.
-</p>
-<p>A reference can be blessed into a package with the following function:
-</p>
-<pre class="verbatim"> SV* sv_bless(SV* sv, HV* stash);
-</pre>
-<p>The <code>sv</code> argument must be a reference value. The
<code>stash</code> argument
-specifies which class the reference will belong to. See
-<a href="#perlguts-Stashes-and-Globs">Stashes and Globs</a> for information on
converting class names into stashes.
-</p>
-<p>/* Still under construction */
-</p>
-<p>The following function upgrades rv to reference if not already one.
-Creates a new SV for rv to point to. If <code>classname</code> is non-null,
the SV
-is blessed into the specified class. SV is returned.
-</p>
-<pre class="verbatim"> SV* newSVrv(SV* rv, const char* classname);
-</pre>
-<p>The following three functions copy integer, unsigned integer or double
-into an SV whose reference is <code>rv</code>. SV is blessed if
<code>classname</code> is
-non-null.
-</p>
-<pre class="verbatim"> SV* sv_setref_iv(SV* rv, const char* classname,
IV iv);
- SV* sv_setref_uv(SV* rv, const char* classname, UV uv);
- SV* sv_setref_nv(SV* rv, const char* classname, NV iv);
-</pre>
-<p>The following function copies the pointer value (<em>the address, not the
-string!</em>) into an SV whose reference is rv. SV is blessed if
<code>classname</code>
-is non-null.
-</p>
-<pre class="verbatim"> SV* sv_setref_pv(SV* rv, const char* classname,
void* pv);
-</pre>
-<p>The following function copies a string into an SV whose reference is
<code>rv</code>.
-Set length to 0 to let Perl calculate the string length. SV is blessed if
-<code>classname</code> is non-null.
-</p>
-<pre class="verbatim"> SV* sv_setref_pvn(SV* rv, const char* classname,
char* pv,
- STRLEN length);
-</pre>
-<p>The following function tests whether the SV is blessed into the specified
-class. It does not check inheritance relationships.
-</p>
-<pre class="verbatim"> int sv_isa(SV* sv, const char* name);
-</pre>
-<p>The following function tests whether the SV is a reference to a blessed
object.
-</p>
-<pre class="verbatim"> int sv_isobject(SV* sv);
-</pre>
-<p>The following function tests whether the SV is derived from the specified
-class. SV can be either a reference to a blessed object or a string
-containing a class name. This is the function implementing the
-<code>UNIVERSAL::isa</code> functionality.
-</p>
-<pre class="verbatim"> bool sv_derived_from(SV* sv, const char* name);
-</pre>
-<p>To check if you’ve got an object derived from a specific class you
have
-to write:
-</p>
-<pre class="verbatim"> if (sv_isobject(sv) &&
sv_derived_from(sv, class)) { ... }
-</pre>
-<hr>
-<a name="perlguts-Creating-New-Variables"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Reference-Counts-and-Mortality" accesskey="n"
rel="next">perlguts Reference Counts and Mortality</a>, Previous: <a
href="#perlguts-Blessed-References-and-Class-Objects" accesskey="p"
rel="prev">perlguts Blessed References and Class Objects</a>, Up: <a
href="#perlguts-Variables" accesskey="u" rel="up">perlguts Variables</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Creating-New-Variables"></a>
-<h4 class="subsection">28.3.12 Creating New Variables</h4>
-
-<p>To create a new Perl variable with an undef value which can be accessed from
-your Perl script, use the following routines, depending on the variable type.
-</p>
-<pre class="verbatim"> SV* get_sv("package::varname", GV_ADD);
- AV* get_av("package::varname", GV_ADD);
- HV* get_hv("package::varname", GV_ADD);
-</pre>
-<p>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.
-</p>
-<p>There are additional macros whose values may be bitwise OR’ed with the
-<code>GV_ADD</code> argument to enable certain extra features. Those bits are:
-</p>
-<dl compact="compact">
-<dt>GV_ADDMULTI</dt>
-<dd><a name="perlguts-GV_005fADDMULTI"></a>
-<p>Marks the variable as multiply defined, thus preventing the:
-</p>
-<pre class="verbatim"> Name <varname> used only once: possible typo
-</pre>
-<p>warning.
-</p>
-</dd>
-<dt>GV_ADDWARN</dt>
-<dd><a name="perlguts-GV_005fADDWARN"></a>
-<p>Issues the warning:
-</p>
-<pre class="verbatim"> Had to create <varname> unexpectedly
-</pre>
-<p>if the variable did not exist before the function was called.
-</p>
-</dd>
-</dl>
-
-<p>If you do not specify a package name, the variable is created in the current
-package.
-</p>
-<hr>
-<a name="perlguts-Reference-Counts-and-Mortality"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Stashes-and-Globs" accesskey="n" rel="next">perlguts
Stashes and Globs</a>, Previous: <a href="#perlguts-Creating-New-Variables"
accesskey="p" rel="prev">perlguts Creating New Variables</a>, Up: <a
href="#perlguts-Variables" accesskey="u" rel="up">perlguts Variables</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Reference-Counts-and-Mortality"></a>
-<h4 class="subsection">28.3.13 Reference Counts and Mortality</h4>
-
-<p>Perl uses a reference count-driven garbage collection mechanism. SVs,
-AVs, or HVs (xV for short in the following) start their life with a
-reference count of 1. If the reference count of an xV ever drops to 0,
-then it will be destroyed and its memory made available for reuse.
-</p>
-<p>This normally doesn’t happen at the Perl level unless a variable is
-undef’ed or the last variable holding a reference to it is changed or
-overwritten. At the internal level, however, reference counts can be
-manipulated with the following macros:
-</p>
-<pre class="verbatim"> int SvREFCNT(SV* sv);
- SV* SvREFCNT_inc(SV* sv);
- void SvREFCNT_dec(SV* sv);
-</pre>
-<p>However, there is one other function which manipulates the reference
-count of its argument. The <code>newRV_inc</code> function, you will recall,
-creates a reference to the specified argument. As a side effect,
-it increments the argument’s reference count. If this is not what
-you want, use <code>newRV_noinc</code> instead.
-</p>
-<p>For example, imagine you want to return a reference from an XSUB function.
-Inside the XSUB routine, you create an SV which initially has a reference
-count of one. Then you call <code>newRV_inc</code>, passing it the
just-created SV.
-This returns the reference as a new SV, but the reference count of the
-SV you passed to <code>newRV_inc</code> has been incremented to two. Now you
-return the reference from the XSUB routine and forget about the SV.
-But Perl hasn’t! Whenever the returned reference is destroyed, the
-reference count of the original SV is decreased to one and nothing happens.
-The SV will hang around without any way to access it until Perl itself
-terminates. This is a memory leak.
-</p>
-<p>The correct procedure, then, is to use <code>newRV_noinc</code> instead of
-<code>newRV_inc</code>. Then, if and when the last reference is destroyed,
-the reference count of the SV will go to zero and it will be destroyed,
-stopping any memory leak.
-</p>
-<p>There are some convenience functions available that can help with the
-destruction of xVs. These functions introduce the concept of
"mortality".
-An xV that is mortal has had its reference count marked to be decremented,
-but not actually decremented, until "a short time later". Generally
the
-term "short time later" means a single Perl statement, such as a
call to
-an XSUB function. The actual determinant for when mortal xVs have their
-reference count decremented depends on two macros, SAVETMPS and FREETMPS.
-See <a href="#perlcall-NAME">perlcall NAME</a> and <a
href="perlxs.html#Top">(perlxs)</a> for more details on these macros.
-</p>
-<p>"Mortalization" then is at its simplest a deferred
<code>SvREFCNT_dec</code>.
-However, if you mortalize a variable twice, the reference count will
-later be decremented twice.
-</p>
-<p>"Mortal" SVs are mainly used for SVs that are placed on
perl’s stack.
-For example an SV which is created just to pass a number to a called sub
-is made mortal to have it cleaned up automatically when it’s popped off
-the stack. Similarly, results returned by XSUBs (which are pushed on the
-stack) are often made mortal.
-</p>
-<p>To create a mortal variable, use the functions:
-</p>
-<pre class="verbatim"> SV* sv_newmortal()
- SV* sv_2mortal(SV*)
- SV* sv_mortalcopy(SV*)
-</pre>
-<p>The first call creates a mortal SV (with no value), the second converts an
existing
-SV to a mortal SV (and thus defers a call to <code>SvREFCNT_dec</code>), and
the
-third creates a mortal copy of an existing SV.
-Because <code>sv_newmortal</code> gives the new SV no value, it must normally
be given one
-via <code>sv_setpv</code>, <code>sv_setiv</code>, etc. :
-</p>
-<pre class="verbatim"> SV *tmp = sv_newmortal();
- sv_setiv(tmp, an_integer);
-</pre>
-<p>As that is multiple C statements it is quite common so see this idiom
instead:
-</p>
-<pre class="verbatim"> SV *tmp = sv_2mortal(newSViv(an_integer));
-</pre>
-<p>You should be careful about creating mortal variables. Strange things
-can happen if you make the same value mortal within multiple contexts,
-or if you make a variable mortal multiple
-times. Thinking of "Mortalization"
-as deferred <code>SvREFCNT_dec</code> should help to minimize such problems.
-For example if you are passing an SV which you <em>know</em> has a high enough
REFCNT
-to survive its use on the stack you need not do any mortalization.
-If you are not sure then doing an <code>SvREFCNT_inc</code> and
<code>sv_2mortal</code>, or
-making a <code>sv_mortalcopy</code> is safer.
-</p>
-<p>The mortal routines are not just for SVs; AVs and HVs can be
-made mortal by passing their address (type-casted to <code>SV*</code>) to the
-<code>sv_2mortal</code> or <code>sv_mortalcopy</code> routines.
-</p>
-<hr>
-<a name="perlguts-Stashes-and-Globs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Double_002dTyped-SVs" accesskey="n"
rel="next">perlguts Double-Typed SVs</a>, Previous: <a
href="#perlguts-Reference-Counts-and-Mortality" accesskey="p"
rel="prev">perlguts Reference Counts and Mortality</a>, Up: <a
href="#perlguts-Variables" accesskey="u" rel="up">perlguts Variables</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Stashes-and-Globs"></a>
-<h4 class="subsection">28.3.14 Stashes and Globs</h4>
-
-<p>A <strong>stash</strong> is a hash that contains all variables that are
defined
-within a package. Each key of the stash is a symbol
-name (shared by all the different types of objects that have the same
-name), and each value in the hash table is a GV (Glob Value). This GV
-in turn contains references to the various objects of that name,
-including (but not limited to) the following:
-</p>
-<pre class="verbatim"> Scalar Value
- Array Value
- Hash Value
- I/O Handle
- Format
- Subroutine
-</pre>
-<p>There is a single stash called <code>PL_defstash</code> that holds the
items that exist
-in the <code>main</code> package. To get at the items in other packages,
append the
-string "::" to the package name. The items in the <code>Foo</code>
package are in
-the stash <code>Foo::</code> in PL_defstash. The items in the
<code>Bar::Baz</code> package are
-in the stash <code>Baz::</code> in <code>Bar::</code>’s stash.
-</p>
-<p>To get the stash pointer for a particular package, use the function:
-</p>
-<pre class="verbatim"> HV* gv_stashpv(const char* name, I32 flags)
- HV* gv_stashsv(SV*, I32 flags)
-</pre>
-<p>The first function takes a literal string, the second uses the string stored
-in the SV. Remember that a stash is just a hash table, so you get back an
-<code>HV*</code>. The <code>flags</code> flag will create a new package if it
is set to GV_ADD.
-</p>
-<p>The name that <code>gv_stash*v</code> wants is the name of the package
whose symbol table
-you want. The default package is called <code>main</code>. If you have
multiply nested
-packages, pass their names to <code>gv_stash*v</code>, separated by
<code>::</code> as in the Perl
-language itself.
-</p>
-<p>Alternately, if you have an SV that is a blessed reference, you can find
-out the stash pointer by using:
-</p>
-<pre class="verbatim"> HV* SvSTASH(SvRV(SV*));
-</pre>
-<p>then use the following to get the package name itself:
-</p>
-<pre class="verbatim"> char* HvNAME(HV* stash);
-</pre>
-<p>If you need to bless or re-bless an object you can use the following
-function:
-</p>
-<pre class="verbatim"> SV* sv_bless(SV*, HV* stash)
-</pre>
-<p>where the first argument, an <code>SV*</code>, must be a reference, and the
second
-argument is a stash. The returned <code>SV*</code> can now be used in the
same way
-as any other SV.
-</p>
-<p>For more information on references and blessings, consult <a
href="#perlref-NAME">perlref NAME</a>.
-</p>
-<hr>
-<a name="perlguts-Double_002dTyped-SVs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Read_002dOnly-Values" accesskey="n"
rel="next">perlguts Read-Only Values</a>, Previous: <a
href="#perlguts-Stashes-and-Globs" accesskey="p" rel="prev">perlguts Stashes
and Globs</a>, Up: <a href="#perlguts-Variables" accesskey="u"
rel="up">perlguts Variables</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Double_002dTyped-SVs"></a>
-<h4 class="subsection">28.3.15 Double-Typed SVs</h4>
-
-<p>Scalar variables normally contain only one type of value, an integer,
-double, pointer, or reference. Perl will automatically convert the
-actual scalar data from the stored type into the requested type.
-</p>
-<p>Some scalar variables contain more than one type of scalar data. For
-example, the variable <code>$!</code> contains either the numeric value of
<code>errno</code>
-or its string equivalent from either <code>strerror</code> or
<code>sys_errlist[]</code>.
-</p>
-<p>To force multiple data values into an SV, you must do two things: use the
-<code>sv_set*v</code> routines to add the additional scalar type, then set a
flag
-so that Perl will believe it contains more than one type of data. The
-four macros to set the flags are:
-</p>
-<pre class="verbatim"> SvIOK_on
- SvNOK_on
- SvPOK_on
- SvROK_on
-</pre>
-<p>The particular macro you must use depends on which <code>sv_set*v</code>
routine
-you called first. This is because every <code>sv_set*v</code> routine turns on
-only the bit for the particular type of data being set, and turns off
-all the rest.
-</p>
-<p>For example, to create a new Perl variable called "dberror" that
contains
-both the numeric and descriptive string error values, you could use the
-following code:
-</p>
-<pre class="verbatim"> extern int dberror;
- extern char *dberror_list;
-
- SV* sv = get_sv("dberror", GV_ADD);
- sv_setiv(sv, (IV) dberror);
- sv_setpv(sv, dberror_list[dberror]);
- SvIOK_on(sv);
-</pre>
-<p>If the order of <code>sv_setiv</code> and <code>sv_setpv</code> had been
reversed, then the
-macro <code>SvPOK_on</code> would need to be called instead of
<code>SvIOK_on</code>.
-</p>
-<hr>
-<a name="perlguts-Read_002dOnly-Values"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Copy-on-Write" accesskey="n" rel="next">perlguts Copy
on Write</a>, Previous: <a href="#perlguts-Double_002dTyped-SVs" accesskey="p"
rel="prev">perlguts Double-Typed SVs</a>, Up: <a href="#perlguts-Variables"
accesskey="u" rel="up">perlguts Variables</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Read_002dOnly-Values"></a>
-<h4 class="subsection">28.3.16 Read-Only Values</h4>
-
-<p>In Perl 5.16 and earlier, copy-on-write (see the next section) shared a
-flag bit with read-only scalars. So the only way to test whether
-<code>sv_setsv</code>, etc., will raise a "Modification of a read-only
value" error
-in those versions is:
-</p>
-<pre class="verbatim"> SvREADONLY(sv) && !SvIsCOW(sv)
-</pre>
-<p>Under Perl 5.18 and later, SvREADONLY only applies to read-only variables,
-and, under 5.20, copy-on-write scalars can also be read-only, so the above
-check is incorrect. You just want:
-</p>
-<pre class="verbatim"> SvREADONLY(sv)
-</pre>
-<p>If you need to do this check often, define your own macro like this:
-</p>
-<pre class="verbatim"> #if PERL_VERSION >= 18
- # define SvTRULYREADONLY(sv) SvREADONLY(sv)
- #else
- # define SvTRULYREADONLY(sv) (SvREADONLY(sv) && !SvIsCOW(sv))
- #endif
-</pre>
-<hr>
-<a name="perlguts-Copy-on-Write"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Magic-Variables" accesskey="n" rel="next">perlguts
Magic Variables</a>, Previous: <a href="#perlguts-Read_002dOnly-Values"
accesskey="p" rel="prev">perlguts Read-Only Values</a>, Up: <a
href="#perlguts-Variables" accesskey="u" rel="up">perlguts Variables</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Copy-on-Write"></a>
-<h4 class="subsection">28.3.17 Copy on Write</h4>
-
-<p>Perl implements a copy-on-write (COW) mechanism for scalars, in which
-string copies are not immediately made when requested, but are deferred
-until made necessary by one or the other scalar changing. This is mostly
-transparent, but one must take care not to modify string buffers that are
-shared by multiple SVs.
-</p>
-<p>You can test whether an SV is using copy-on-write with
<code>SvIsCOW(sv)</code>.
-</p>
-<p>You can force an SV to make its own copy of its string buffer by calling
<code>sv_force_normal(sv)</code> or SvPV_force_nolen(sv).
-</p>
-<p>If you want to make the SV drop its string buffer, use
-<code>sv_force_normal_flags(sv, SV_COW_DROP_PV)</code> or simply
-<code>sv_setsv(sv, NULL)</code>.
-</p>
-<p>All of these functions will croak on read-only scalars (see the previous
-section for more on those).
-</p>
-<p>To test that your code is behaving correctly and not modifying COW buffers,
-on systems that support <a href="http://man.he.net/man2/mmap";>mmap(2)</a>
(i.e., Unix) you can configure perl with
-<code>-Accflags=-DPERL_DEBUG_READONLY_COW</code> and it will turn buffer
violations
-into crashes. You will find it to be marvellously slow, so you may want to
-skip perl’s own tests.
-</p>
-<hr>
-<a name="perlguts-Magic-Variables"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Assigning-Magic" accesskey="n" rel="next">perlguts
Assigning Magic</a>, Previous: <a href="#perlguts-Copy-on-Write" accesskey="p"
rel="prev">perlguts Copy on Write</a>, Up: <a href="#perlguts-Variables"
accesskey="u" rel="up">perlguts Variables</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Magic-Variables"></a>
-<h4 class="subsection">28.3.18 Magic Variables</h4>
-
-<p>[This section still under construction. Ignore everything here. Post no
-bills. Everything not permitted is forbidden.]
-</p>
-<p>Any SV may be magical, that is, it has special features that a normal
-SV does not have. These features are stored in the SV structure in a
-linked list of <code>struct magic</code>’s, typedef’ed to
<code>MAGIC</code>.
-</p>
-<pre class="verbatim"> struct magic {
- MAGIC* mg_moremagic;
- MGVTBL* mg_virtual;
- U16 mg_private;
- char mg_type;
- U8 mg_flags;
- I32 mg_len;
- SV* mg_obj;
- char* mg_ptr;
- };
-</pre>
-<p>Note this is current as of patchlevel 0, and could change at any time.
-</p>
-<hr>
-<a name="perlguts-Assigning-Magic"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Magic-Virtual-Tables" accesskey="n"
rel="next">perlguts Magic Virtual Tables</a>, Previous: <a
href="#perlguts-Magic-Variables" accesskey="p" rel="prev">perlguts Magic
Variables</a>, Up: <a href="#perlguts-Variables" accesskey="u"
rel="up">perlguts Variables</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Assigning-Magic"></a>
-<h4 class="subsection">28.3.19 Assigning Magic</h4>
-
-<p>Perl adds magic to an SV using the sv_magic function:
-</p>
-<pre class="verbatim"> void sv_magic(SV* sv, SV* obj, int how, const char*
name, I32 namlen);
-</pre>
-<p>The <code>sv</code> argument is a pointer to the SV that is to acquire a
new magical
-feature.
-</p>
-<p>If <code>sv</code> is not already magical, Perl uses the
<code>SvUPGRADE</code> macro to
-convert <code>sv</code> to type <code>SVt_PVMG</code>.
-Perl then continues by adding new magic
-to the beginning of the linked list of magical features. Any prior entry
-of the same type of magic is deleted. Note that this can be overridden,
-and multiple instances of the same type of magic can be associated with an
-SV.
-</p>
-<p>The <code>name</code> and <code>namlen</code> arguments are used to
associate a string with
-the magic, typically the name of a variable. <code>namlen</code> is stored in
the
-<code>mg_len</code> field and if <code>name</code> is non-null then either a
<code>savepvn</code> copy of
-<code>name</code> or <code>name</code> itself is stored in the
<code>mg_ptr</code> field, depending on
-whether <code>namlen</code> is greater than zero or equal to zero
respectively. As a
-special case, if <code>(name && namlen == HEf_SVKEY)</code> then
<code>name</code> is assumed
-to contain an <code>SV*</code> and is stored as-is with its REFCNT incremented.
-</p>
-<p>The sv_magic function uses <code>how</code> to determine which, if any,
predefined
-"Magic Virtual Table" should be assigned to the
<code>mg_virtual</code> field.
-See the <a href="#perlguts-Magic-Virtual-Tables">Magic Virtual Tables</a>
section below. The <code>how</code> argument is also
-stored in the <code>mg_type</code> field. The value of
-<code>how</code> should be chosen from the set of macros
-<code>PERL_MAGIC_foo</code> found in <samp>perl.h</samp>. Note that before
-these macros were added, Perl internals used to directly use character
-literals, so you may occasionally come across old code or documentation
-referring to ’U’ magic rather than <code>PERL_MAGIC_uvar</code>
for example.
-</p>
-<p>The <code>obj</code> argument is stored in the <code>mg_obj</code> field of
the <code>MAGIC</code>
-structure. If it is not the same as the <code>sv</code> argument, the
reference
-count of the <code>obj</code> object is incremented. If it is the same, or if
-the <code>how</code> argument is <code>PERL_MAGIC_arylen</code>, or if it is a
NULL pointer,
-then <code>obj</code> is merely stored, without the reference count being
incremented.
-</p>
-<p>See also <code>sv_magicext</code> in <a
href="perlapi.html#Top">(perlapi)</a> for a more flexible way to add magic
-to an SV.
-</p>
-<p>There is also a function to add magic to an <code>HV</code>:
-</p>
-<pre class="verbatim"> void hv_magic(HV *hv, GV *gv, int how);
-</pre>
-<p>This simply calls <code>sv_magic</code> and coerces the <code>gv</code>
argument into an <code>SV</code>.
-</p>
-<p>To remove the magic from an SV, call the function sv_unmagic:
-</p>
-<pre class="verbatim"> int sv_unmagic(SV *sv, int type);
-</pre>
-<p>The <code>type</code> argument should be equal to the <code>how</code>
value when the <code>SV</code>
-was initially made magical.
-</p>
-<p>However, note that <code>sv_unmagic</code> removes all magic of a certain
<code>type</code> from the
-<code>SV</code>. If you want to remove only certain
-magic of a <code>type</code> based on the magic
-virtual table, use <code>sv_unmagicext</code> instead:
-</p>
-<pre class="verbatim"> int sv_unmagicext(SV *sv, int type, MGVTBL *vtbl);
-</pre>
-<hr>
-<a name="perlguts-Magic-Virtual-Tables"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Finding-Magic" accesskey="n" rel="next">perlguts
Finding Magic</a>, Previous: <a href="#perlguts-Assigning-Magic" accesskey="p"
rel="prev">perlguts Assigning Magic</a>, Up: <a href="#perlguts-Variables"
accesskey="u" rel="up">perlguts Variables</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Magic-Virtual-Tables"></a>
-<h4 class="subsection">28.3.20 Magic Virtual Tables</h4>
-
-<p>The <code>mg_virtual</code> field in the <code>MAGIC</code> structure is a
pointer to an
-<code>MGVTBL</code>, which is a structure of function pointers and stands for
-"Magic Virtual Table" to handle the various operations that might be
-applied to that variable.
-</p>
-<p>The <code>MGVTBL</code> has five (or sometimes eight) pointers to the
following
-routine types:
-</p>
-<pre class="verbatim"> int (*svt_get)(SV* sv, MAGIC* mg);
- int (*svt_set)(SV* sv, MAGIC* mg);
- U32 (*svt_len)(SV* sv, MAGIC* mg);
- int (*svt_clear)(SV* sv, MAGIC* mg);
- int (*svt_free)(SV* sv, MAGIC* mg);
-
- int (*svt_copy)(SV *sv, MAGIC* mg, SV *nsv,
- const char *name, I32 namlen);
- int (*svt_dup)(MAGIC *mg, CLONE_PARAMS *param);
- int (*svt_local)(SV *nsv, MAGIC *mg);
-</pre>
-<p>This MGVTBL structure is set at compile-time in <samp>perl.h</samp> and
there are
-currently 32 types. These different structures contain pointers to various
-routines that perform additional actions depending on which function is
-being called.
-</p>
-<pre class="verbatim"> Function pointer Action taken
- ---------------- ------------
- svt_get Do something before the value of the SV is
- retrieved.
- svt_set Do something after the SV is assigned a value.
- svt_len Report on the SV's length.
- svt_clear Clear something the SV represents.
- svt_free Free any extra storage associated with the SV.
-
- svt_copy copy tied variable magic to a tied element
- svt_dup duplicate a magic structure during thread cloning
- svt_local copy magic to local value during 'local'
-</pre>
-<p>For instance, the MGVTBL structure called <code>vtbl_sv</code> (which
corresponds
-to an <code>mg_type</code> of <code>PERL_MAGIC_sv</code>) contains:
-</p>
-<pre class="verbatim"> { magic_get, magic_set, magic_len, 0, 0 }
-</pre>
-<p>Thus, when an SV is determined to be magical and of type
<code>PERL_MAGIC_sv</code>,
-if a get operation is being performed, the routine <code>magic_get</code> is
-called. All the various routines for the various magical types begin
-with <code>magic_</code>. NOTE: the magic routines are not considered part of
-the Perl API, and may not be exported by the Perl library.
-</p>
-<p>The last three slots are a recent addition, and for source code
-compatibility they are only checked for if one of the three flags
-MGf_COPY, MGf_DUP or MGf_LOCAL is set in mg_flags.
-This means that most code can continue declaring
-a vtable as a 5-element value. These three are
-currently used exclusively by the threading code, and are highly subject
-to change.
-</p>
-<p>The current kinds of Magic Virtual Tables are:
-</p>
-<pre class="verbatim"> mg_type
- (old-style char and macro) MGVTBL Type of magic
- -------------------------- ------ -------------
- \0 PERL_MAGIC_sv vtbl_sv Special scalar variable
- # PERL_MAGIC_arylen vtbl_arylen Array length ($#ary)
- % PERL_MAGIC_rhash (none) Extra data for restricted
- hashes
- * PERL_MAGIC_debugvar vtbl_debugvar $DB::single, signal, trace
- vars
- . PERL_MAGIC_pos vtbl_pos pos() lvalue
- : PERL_MAGIC_symtab (none) Extra data for symbol
- tables
- < PERL_MAGIC_backref vtbl_backref For weak ref data
- @ PERL_MAGIC_arylen_p (none) To move arylen out of XPVAV
- B PERL_MAGIC_bm vtbl_regexp Boyer-Moore
- (fast string search)
- c PERL_MAGIC_overload_table vtbl_ovrld Holds overload table
- (AMT) on stash
- D PERL_MAGIC_regdata vtbl_regdata Regex match position data
- (@+ and @- vars)
- d PERL_MAGIC_regdatum vtbl_regdatum Regex match position data
- element
- E PERL_MAGIC_env vtbl_env %ENV hash
- e PERL_MAGIC_envelem vtbl_envelem %ENV hash element
- f PERL_MAGIC_fm vtbl_regexp Formline
- ('compiled' format)
- g PERL_MAGIC_regex_global vtbl_mglob m//g target
- H PERL_MAGIC_hints vtbl_hints %^H hash
- h PERL_MAGIC_hintselem vtbl_hintselem %^H hash element
- I PERL_MAGIC_isa vtbl_isa @ISA array
- i PERL_MAGIC_isaelem vtbl_isaelem @ISA array element
- k PERL_MAGIC_nkeys vtbl_nkeys scalar(keys()) lvalue
- L PERL_MAGIC_dbfile (none) Debugger %_<filename
- l PERL_MAGIC_dbline vtbl_dbline Debugger %_<filename
- element
- N PERL_MAGIC_shared (none) Shared between threads
- n PERL_MAGIC_shared_scalar (none) Shared between threads
- o PERL_MAGIC_collxfrm vtbl_collxfrm Locale transformation
- P PERL_MAGIC_tied vtbl_pack Tied array or hash
- p PERL_MAGIC_tiedelem vtbl_packelem Tied array or hash element
- q PERL_MAGIC_tiedscalar vtbl_packelem Tied scalar or handle
- r PERL_MAGIC_qr vtbl_regexp Precompiled qr// regex
- S PERL_MAGIC_sig (none) %SIG hash
- s PERL_MAGIC_sigelem vtbl_sigelem %SIG hash element
- t PERL_MAGIC_taint vtbl_taint Taintedness
- U PERL_MAGIC_uvar vtbl_uvar Available for use by
- extensions
- u PERL_MAGIC_uvar_elem (none) Reserved for use by
- extensions
- V PERL_MAGIC_vstring (none) SV was vstring literal
- v PERL_MAGIC_vec vtbl_vec vec() lvalue
- w PERL_MAGIC_utf8 vtbl_utf8 Cached UTF-8 information
- x PERL_MAGIC_substr vtbl_substr substr() lvalue
- y PERL_MAGIC_defelem vtbl_defelem Shadow "foreach"
iterator
- variable / smart parameter
- vivification
- \ PERL_MAGIC_lvref vtbl_lvref Lvalue reference
- constructor
- ] PERL_MAGIC_checkcall vtbl_checkcall Inlining/mutation of call
- to this CV
- ~ PERL_MAGIC_ext (none) Available for use by
- extensions
-</pre>
-<p>When an uppercase and lowercase letter both exist in the table, then the
-uppercase letter is typically used to represent some kind of composite type
-(a list or a hash), and the lowercase letter is used to represent an element
-of that composite type. Some internals code makes use of this case
-relationship. However, ’v’ and ’V’ (vec and v-string)
are in no way related.
-</p>
-<p>The <code>PERL_MAGIC_ext</code> and <code>PERL_MAGIC_uvar</code> magic
types are defined
-specifically for use by extensions and will not be used by perl itself.
-Extensions can use <code>PERL_MAGIC_ext</code> magic to ’attach’
private information
-to variables (typically objects). This is especially useful because
-there is no way for normal perl code to corrupt this private information
-(unlike using extra elements of a hash object).
-</p>
-<p>Similarly, <code>PERL_MAGIC_uvar</code> magic can be used much like tie()
to call a
-C function any time a scalar’s value is used or changed. The
<code>MAGIC</code>’s
-<code>mg_ptr</code> field points to a <code>ufuncs</code> structure:
-</p>
-<pre class="verbatim"> struct ufuncs {
- I32 (*uf_val)(pTHX_ IV, SV*);
- I32 (*uf_set)(pTHX_ IV, SV*);
- IV uf_index;
- };
-</pre>
-<p>When the SV is read from or written to, the <code>uf_val</code> or
<code>uf_set</code>
-function will be called with <code>uf_index</code> as the first arg and a
pointer to
-the SV as the second. A simple example of how to add
<code>PERL_MAGIC_uvar</code>
-magic is shown below. Note that the ufuncs structure is copied by
-sv_magic, so you can safely allocate it on the stack.
-</p>
-<pre class="verbatim"> void
- Umagic(sv)
- SV *sv;
- PREINIT:
- struct ufuncs uf;
- CODE:
- uf.uf_val = &my_get_fn;
- uf.uf_set = &my_set_fn;
- uf.uf_index = 0;
- sv_magic(sv, 0, PERL_MAGIC_uvar, (char*)&uf, sizeof(uf));
-</pre>
-<p>Attaching <code>PERL_MAGIC_uvar</code> to arrays is permissible but has no
effect.
-</p>
-<p>For hashes there is a specialized hook that gives control over hash
-keys (but not values). This hook calls <code>PERL_MAGIC_uvar</code>
’get’ magic
-if the "set" function in the <code>ufuncs</code> structure is NULL.
The hook
-is activated whenever the hash is accessed with a key specified as
-an <code>SV</code> through the functions <code>hv_store_ent</code>,
<code>hv_fetch_ent</code>,
-<code>hv_delete_ent</code>, and <code>hv_exists_ent</code>. Accessing the key
as a string
-through the functions without the <code>..._ent</code> suffix circumvents the
-hook. See <a
href="Hash-Util-FieldHash.html#GUTS">(Hash-Util-FieldHash)GUTS</a> for a
detailed description.
-</p>
-<p>Note that because multiple extensions may be using
<code>PERL_MAGIC_ext</code>
-or <code>PERL_MAGIC_uvar</code> 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 <code>PERL_MAGIC_ext</code> magic, it is usually a good idea to define an
-<code>MGVTBL</code>, even if all its fields will be <code>0</code>, so that
individual
-<code>MAGIC</code> pointers can be identified as a particular kind of magic
-using their magic virtual table. <code>mg_findext</code> provides an easy way
-to do that:
-</p>
-<pre class="verbatim"> 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;
- ...
- }
-</pre>
-<p>Also note that the <code>sv_set*()</code> and <code>sv_cat*()</code>
functions described
-earlier do <strong>not</strong> invoke ’set’ magic on their
targets. This must
-be done by the user either by calling the <code>SvSETMAGIC()</code> macro after
-calling these functions, or by using one of the <code>sv_set*_mg()</code> or
-<code>sv_cat*_mg()</code> functions. Similarly, generic C code must call the
-<code>SvGETMAGIC()</code> macro to invoke any ’get’ magic if they
use an SV
-obtained from external sources in functions that don’t handle magic.
-See <a href="perlapi.html#Top">(perlapi)</a> for a description of these
functions.
-For example, calls to the <code>sv_cat*()</code> functions typically need to be
-followed by <code>SvSETMAGIC()</code>, but they don’t need a prior
<code>SvGETMAGIC()</code>
-since their implementation handles ’get’ magic.
-</p>
-<hr>
-<a name="perlguts-Finding-Magic"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Understanding-the-Magic-of-Tied-Hashes-and-Arrays"
accesskey="n" rel="next">perlguts Understanding the Magic of Tied Hashes and
Arrays</a>, Previous: <a href="#perlguts-Magic-Virtual-Tables" accesskey="p"
rel="prev">perlguts Magic Virtual Tables</a>, Up: <a href="#perlguts-Variables"
accesskey="u" rel="up">perlguts Variables</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Finding-Magic"></a>
-<h4 class="subsection">28.3.21 Finding Magic</h4>
-
-<pre class="verbatim"> MAGIC *mg_find(SV *sv, int type); /* Finds the magic
pointer of that
- * type */
-</pre>
-<p>This routine returns a pointer to a <code>MAGIC</code> structure stored in
the SV.
-If the SV does not have that magical
-feature, <code>NULL</code> is returned. If the
-SV has multiple instances of that magical feature, the first one will be
-returned. <code>mg_findext</code> can be used
-to find a <code>MAGIC</code> structure of an SV
-based on both its magic type and its magic virtual table:
-</p>
-<pre class="verbatim"> MAGIC *mg_findext(SV *sv, int type, MGVTBL *vtbl);
-</pre>
-<p>Also, if the SV passed to <code>mg_find</code> or <code>mg_findext</code>
is not of type
-SVt_PVMG, Perl may core dump.
-</p>
-<pre class="verbatim"> int mg_copy(SV* sv, SV* nsv, const char* key, STRLEN
klen);
-</pre>
-<p>This routine checks to see what types of magic <code>sv</code> has. If the
mg_type
-field is an uppercase letter, then the mg_obj is copied to <code>nsv</code>,
but
-the mg_type field is changed to be the lowercase letter.
-</p>
-<hr>
-<a name="perlguts-Understanding-the-Magic-of-Tied-Hashes-and-Arrays"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Localizing-changes" accesskey="n" rel="next">perlguts
Localizing changes</a>, Previous: <a href="#perlguts-Finding-Magic"
accesskey="p" rel="prev">perlguts Finding Magic</a>, Up: <a
href="#perlguts-Variables" accesskey="u" rel="up">perlguts Variables</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Understanding-the-Magic-of-Tied-Hashes-and-Arrays"></a>
-<h4 class="subsection">28.3.22 Understanding the Magic of Tied Hashes and
Arrays</h4>
-
-<p>Tied hashes and arrays are magical beasts of the
<code>PERL_MAGIC_tied</code>
-magic type.
-</p>
-<p>WARNING: As of the 5.004 release, proper usage of the array and hash
-access functions requires understanding a few caveats. Some
-of these caveats are actually considered bugs in the API, to be fixed
-in later releases, and are bracketed with [MAYCHANGE] below. If
-you find yourself actually applying such information in this section, be
-aware that the behavior may change in the future, umm, without warning.
-</p>
-<p>The perl tie function associates a variable with an object that implements
-the various GET, SET, etc methods. To perform the equivalent of the perl
-tie function from an XSUB, you must mimic this behaviour. The code below
-carries out the necessary steps – firstly it creates a new hash, and then
-creates a second hash which it blesses into the class which will implement
-the tie methods. Lastly it ties the two hashes together, and returns a
-reference to the new tied hash. Note that the code below does NOT call the
-TIEHASH method in the MyTie class -
-see <a href="#perlguts-Calling-Perl-Routines-from-within-C-Programs">Calling
Perl Routines from within C Programs</a> for details on how
-to do this.
-</p>
-<pre class="verbatim"> SV*
- mytie()
- PREINIT:
- HV *hash;
- HV *stash;
- SV *tie;
- CODE:
- hash = newHV();
- tie = newRV_noinc((SV*)newHV());
- stash = gv_stashpv("MyTie", GV_ADD);
- sv_bless(tie, stash);
- hv_magic(hash, (GV*)tie, PERL_MAGIC_tied);
- RETVAL = newRV_noinc(hash);
- OUTPUT:
- RETVAL
-</pre>
-<p>The <code>av_store</code> function, when given a tied array argument, merely
-copies the magic of the array onto the value to be "stored", using
-<code>mg_copy</code>. It may also return NULL, indicating that the value did
not
-actually need to be stored in the array. [MAYCHANGE] After a call to
-<code>av_store</code> on a tied array, the caller will usually need to call
-<code>mg_set(val)</code> to actually invoke the perl level "STORE"
method on the
-TIEARRAY object. If <code>av_store</code> did return NULL, a call to
-<code>SvREFCNT_dec(val)</code> will also be usually necessary to avoid a memory
-leak. [/MAYCHANGE]
-</p>
-<p>The previous paragraph is applicable verbatim to tied hash access using the
-<code>hv_store</code> and <code>hv_store_ent</code> functions as well.
-</p>
-<p><code>av_fetch</code> and the corresponding hash functions
<code>hv_fetch</code> and
-<code>hv_fetch_ent</code> actually return an undefined mortal value whose magic
-has been initialized using <code>mg_copy</code>. Note the value so returned
does not
-need to be deallocated, as it is already mortal. [MAYCHANGE] But you will
-need to call <code>mg_get()</code> on the returned value in order to actually
invoke
-the perl level "FETCH" method on the underlying TIE object.
Similarly,
-you may also call <code>mg_set()</code> on the return value after possibly
assigning
-a suitable value to it using <code>sv_setsv</code>, which will invoke the
"STORE"
-method on the TIE object. [/MAYCHANGE]
-</p>
-<p>[MAYCHANGE]
-In other words, the array or hash fetch/store functions don’t really
-fetch and store actual values in the case of tied arrays and hashes. They
-merely call <code>mg_copy</code> to attach magic to the values that were meant
to be
-"stored" or "fetched". Later calls to <code>mg_get</code>
and <code>mg_set</code> actually
-do the job of invoking the TIE methods on the underlying objects. Thus
-the magic mechanism currently implements a kind of lazy access to arrays
-and hashes.
-</p>
-<p>Currently (as of perl version 5.004), use of the hash and array access
-functions requires the user to be aware of whether they are operating on
-"normal" hashes and arrays, or on their tied variants. The API may
be
-changed to provide more transparent access to both tied and normal data
-types in future versions.
-[/MAYCHANGE]
-</p>
-<p>You would do well to understand that the TIEARRAY and TIEHASH interfaces
-are mere sugar to invoke some perl method calls while using the uniform hash
-and array syntax. The use of this sugar imposes some overhead (typically
-about two to four extra opcodes per FETCH/STORE operation, in addition to
-the creation of all the mortal variables required to invoke the methods).
-This overhead will be comparatively small if the TIE methods are themselves
-substantial, but if they are only a few statements long, the overhead
-will not be insignificant.
-</p>
-<hr>
-<a name="perlguts-Localizing-changes"></a>
-<div class="header">
-<p>
-Previous: <a
href="#perlguts-Understanding-the-Magic-of-Tied-Hashes-and-Arrays"
accesskey="p" rel="prev">perlguts Understanding the Magic of Tied Hashes and
Arrays</a>, Up: <a href="#perlguts-Variables" accesskey="u" rel="up">perlguts
Variables</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Localizing-changes"></a>
-<h4 class="subsection">28.3.23 Localizing changes</h4>
-
-<p>Perl has a very handy construction
-</p>
-<pre class="verbatim"> {
- local $var = 2;
- ...
- }
-</pre>
-<p>This construction is <em>approximately</em> equivalent to
-</p>
-<pre class="verbatim"> {
- my $oldvar = $var;
- $var = 2;
- ...
- $var = $oldvar;
- }
-</pre>
-<p>The biggest difference is that the first construction would
-reinstate the initial value of $var, irrespective of how control exits
-the block: <code>goto</code>, <code>return</code>,
<code>die</code>/<code>eval</code>, etc. It is a little bit
-more efficient as well.
-</p>
-<p>There is a way to achieve a similar task from C via Perl API: create a
-<em>pseudo-block</em>, and arrange for some changes to be automatically
-undone at the end of it, either explicit, or via a non-local exit (via
-die()). A <em>block</em>-like construct is created by a pair of
-<code>ENTER</code>/<code>LEAVE</code> macros (see <a
href="#perlcall-Returning-a-Scalar">perlcall Returning a Scalar</a>).
-Such a construct may be created specially for some important localized
-task, or an existing one (like boundaries of enclosing Perl
-subroutine/block, or an existing pair for freeing TMPs) may be
-used. (In the second case the overhead of additional localization must
-be almost negligible.) Note that any XSUB is automatically enclosed in
-an <code>ENTER</code>/<code>LEAVE</code> pair.
-</p>
-<p>Inside such a <em>pseudo-block</em> the following service is available:
-</p>
-<dl compact="compact">
-<dt><code>SAVEINT(int i)</code></dt>
-<dd><a name="perlguts-SAVEINT_0028int-i_0029"></a>
-</dd>
-<dt><code>SAVEIV(IV i)</code></dt>
-<dd><a name="perlguts-SAVEIV_0028IV-i_0029"></a>
-</dd>
-<dt><code>SAVEI32(I32 i)</code></dt>
-<dd><a name="perlguts-SAVEI32_0028I32-i_0029"></a>
-</dd>
-<dt><code>SAVELONG(long i)</code></dt>
-<dd><a name="perlguts-SAVELONG_0028long-i_0029"></a>
-<p>These macros arrange things to restore the value of integer variable
-<code>i</code> at the end of enclosing <em>pseudo-block</em>.
-</p>
-</dd>
-<dt><code>SAVESPTR(s)</code></dt>
-<dd><a name="perlguts-SAVESPTR_0028s_0029"></a>
-</dd>
-<dt><code>SAVEPPTR(p)</code></dt>
-<dd><a name="perlguts-SAVEPPTR_0028p_0029"></a>
-<p>These macros arrange things to restore the value of pointers <code>s</code>
and
-<code>p</code>. <code>s</code> must be a pointer of a type which survives
conversion to
-<code>SV*</code> and back, <code>p</code> should be able to survive conversion
to <code>char*</code>
-and back.
-</p>
-</dd>
-<dt><code>SAVEFREESV(SV *sv)</code></dt>
-<dd><a name="perlguts-SAVEFREESV_0028SV-_002asv_0029"></a>
-<p>The refcount of <code>sv</code> would be decremented at the end of
-<em>pseudo-block</em>. This is similar to <code>sv_2mortal</code> in that it
is also a
-mechanism for doing a delayed <code>SvREFCNT_dec</code>. However, while
<code>sv_2mortal</code>
-extends the lifetime of <code>sv</code> until the beginning of the next
statement,
-<code>SAVEFREESV</code> extends it until the end of the enclosing scope. These
-lifetimes can be wildly different.
-</p>
-<p>Also compare <code>SAVEMORTALIZESV</code>.
-</p>
-</dd>
-<dt><code>SAVEMORTALIZESV(SV *sv)</code></dt>
-<dd><a name="perlguts-SAVEMORTALIZESV_0028SV-_002asv_0029"></a>
-<p>Just like <code>SAVEFREESV</code>, but mortalizes <code>sv</code> at the
end of the current
-scope instead of decrementing its reference count. This usually has the
-effect of keeping <code>sv</code> alive until the statement that called the
currently
-live scope has finished executing.
-</p>
-</dd>
-<dt><code>SAVEFREEOP(OP *op)</code></dt>
-<dd><a name="perlguts-SAVEFREEOP_0028OP-_002aop_0029"></a>
-<p>The <code>OP *</code> is op_free()ed at the end of <em>pseudo-block</em>.
-</p>
-</dd>
-<dt><code>SAVEFREEPV(p)</code></dt>
-<dd><a name="perlguts-SAVEFREEPV_0028p_0029"></a>
-<p>The chunk of memory which is pointed to by <code>p</code> is Safefree()ed
at the
-end of <em>pseudo-block</em>.
-</p>
-</dd>
-<dt><code>SAVECLEARSV(SV *sv)</code></dt>
-<dd><a name="perlguts-SAVECLEARSV_0028SV-_002asv_0029"></a>
-<p>Clears a slot in the current scratchpad which corresponds to
<code>sv</code> at
-the end of <em>pseudo-block</em>.
-</p>
-</dd>
-<dt><code>SAVEDELETE(HV *hv, char *key, I32 length)</code></dt>
-<dd><a
name="perlguts-SAVEDELETE_0028HV-_002ahv_002c-char-_002akey_002c-I32-length_0029"></a>
-<p>The key <code>key</code> of <code>hv</code> is deleted at the end of
<em>pseudo-block</em>. The
-string pointed to by <code>key</code> is Safefree()ed. If one has a
<em>key</em> in
-short-lived storage, the corresponding string may be reallocated like
-this:
-</p>
-<pre class="verbatim"> SAVEDELETE(PL_defstash, savepv(tmpbuf),
strlen(tmpbuf));
-</pre>
-</dd>
-<dt><code>SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)</code></dt>
-<dd><a
name="perlguts-SAVEDESTRUCTOR_0028DESTRUCTORFUNC_005fNOCONTEXT_005ft-f_002c-void-_002ap_0029"></a>
-<p>At the end of <em>pseudo-block</em> the function <code>f</code> is called
with the
-only argument <code>p</code>.
-</p>
-</dd>
-<dt><code>SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)</code></dt>
-<dd><a
name="perlguts-SAVEDESTRUCTOR_005fX_0028DESTRUCTORFUNC_005ft-f_002c-void-_002ap_0029"></a>
-<p>At the end of <em>pseudo-block</em> the function <code>f</code> is called
with the
-implicit context argument (if any), and <code>p</code>.
-</p>
-</dd>
-<dt><code>SAVESTACK_POS()</code></dt>
-<dd><a name="perlguts-SAVESTACK_005fPOS_0028_0029"></a>
-<p>The current offset on the Perl internal stack (cf. <code>SP</code>) is
restored
-at the end of <em>pseudo-block</em>.
-</p>
-</dd>
-</dl>
-
-<p>The following API list contains functions, thus one needs to
-provide pointers to the modifiable data explicitly (either C pointers,
-or Perlish <code>GV *</code>s). Where the above macros take <code>int</code>,
a similar
-function takes <code>int *</code>.
-</p>
-<dl compact="compact">
-<dt><code>SV* save_scalar(GV *gv)</code></dt>
-<dd><a name="perlguts-SV_002a-save_005fscalar_0028GV-_002agv_0029"></a>
-<p>Equivalent to Perl code <code>local $gv</code>.
-</p>
-</dd>
-<dt><code>AV* save_ary(GV *gv)</code></dt>
-<dd><a name="perlguts-AV_002a-save_005fary_0028GV-_002agv_0029"></a>
-</dd>
-<dt><code>HV* save_hash(GV *gv)</code></dt>
-<dd><a name="perlguts-HV_002a-save_005fhash_0028GV-_002agv_0029"></a>
-<p>Similar to <code>save_scalar</code>, but localize <code>@gv</code> and
<code>%gv</code>.
-</p>
-</dd>
-<dt><code>void save_item(SV *item)</code></dt>
-<dd><a name="perlguts-void-save_005fitem_0028SV-_002aitem_0029"></a>
-<p>Duplicates the current value of <code>SV</code>, on the exit from the
current
-<code>ENTER</code>/<code>LEAVE</code> <em>pseudo-block</em> will restore the
value of <code>SV</code>
-using the stored value. It doesn’t handle magic. Use
<code>save_scalar</code> if
-magic is affected.
-</p>
-</dd>
-<dt><code>void save_list(SV **sarg, I32 maxsarg)</code></dt>
-<dd><a
name="perlguts-void-save_005flist_0028SV-_002a_002asarg_002c-I32-maxsarg_0029"></a>
-<p>A variant of <code>save_item</code> which takes multiple arguments via an
array
-<code>sarg</code> of <code>SV*</code> of length <code>maxsarg</code>.
-</p>
-</dd>
-<dt><code>SV* save_svref(SV **sptr)</code></dt>
-<dd><a name="perlguts-SV_002a-save_005fsvref_0028SV-_002a_002asptr_0029"></a>
-<p>Similar to <code>save_scalar</code>, but will reinstate an <code>SV
*</code>.
-</p>
-</dd>
-<dt><code>void save_aptr(AV **aptr)</code></dt>
-<dd><a name="perlguts-void-save_005faptr_0028AV-_002a_002aaptr_0029"></a>
-</dd>
-<dt><code>void save_hptr(HV **hptr)</code></dt>
-<dd><a name="perlguts-void-save_005fhptr_0028HV-_002a_002ahptr_0029"></a>
-<p>Similar to <code>save_svref</code>, but localize <code>AV *</code> and
<code>HV *</code>.
-</p>
-</dd>
-</dl>
-
-<p>The <code>Alias</code> module implements localization of the basic types
within the
-<em>caller’s scope</em>. People who are interested in how to localize
things in
-the containing scope should take a look there too.
-</p>
-<hr>
-<a name="perlguts-Subroutines"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Memory-Allocation" accesskey="n" rel="next">perlguts
Memory Allocation</a>, Previous: <a href="#perlguts-Variables" accesskey="p"
rel="prev">perlguts Variables</a>, Up: <a href="#perlguts" accesskey="u"
rel="up">perlguts</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Subroutines"></a>
-<h3 class="section">28.4 Subroutines</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlguts-XSUBs-and-the-Argument-Stack" accesskey="1">perlguts XSUBs and
the Argument Stack</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Autoloading-with-XSUBs" accesskey="2">perlguts Autoloading with
XSUBs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Calling-Perl-Routines-from-within-C-Programs"
accesskey="3">perlguts Calling Perl Routines from within C
Programs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Putting-a-C-value-on-Perl-stack" accesskey="4">perlguts Putting
a C value on Perl stack</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-Scratchpads"
accesskey="5">perlguts Scratchpads</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Scratchpads-and-recursion" accesskey="6">perlguts Scratchpads
and recursion</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlguts-XSUBs-and-the-Argument-Stack"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Autoloading-with-XSUBs" accesskey="n"
rel="next">perlguts Autoloading with XSUBs</a>, Up: <a
href="#perlguts-Subroutines" accesskey="u" rel="up">perlguts Subroutines</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="XSUBs-and-the-Argument-Stack"></a>
-<h4 class="subsection">28.4.1 XSUBs and the Argument Stack</h4>
-
-<p>The XSUB mechanism is a simple way for Perl programs to access C
subroutines.
-An XSUB routine will have a stack that contains the arguments from the Perl
-program, and a way to map from the Perl data structures to a C equivalent.
-</p>
-<p>The stack arguments are accessible through the <code>ST(n)</code> macro,
which returns
-the <code>n</code>’th stack argument. Argument 0 is the first argument
passed in the
-Perl subroutine call. These arguments are <code>SV*</code>, and can be used
anywhere
-an <code>SV*</code> is used.
-</p>
-<p>Most of the time, output from the C routine can be handled through use of
-the RETVAL and OUTPUT directives. However, there are some cases where the
-argument stack is not already long enough to handle all the return values.
-An example is the POSIX tzname() call, which takes no arguments, but returns
-two, the local time zone’s standard and summer time abbreviations.
-</p>
-<p>To handle this situation, the PPCODE directive is used and the stack is
-extended using the macro:
-</p>
-<pre class="verbatim"> EXTEND(SP, num);
-</pre>
-<p>where <code>SP</code> is the macro that represents the local copy of the
stack pointer,
-and <code>num</code> is the number of elements the stack should be extended by.
-</p>
-<p>Now that there is room on the stack, values can be pushed on it using
<code>PUSHs</code>
-macro. The pushed values will often need to be "mortal" (See
-<a href="#perlguts-Reference-Counts-and-Mortality">Reference Counts and
Mortality</a>):
-</p>
-<pre class="verbatim"> PUSHs(sv_2mortal(newSViv(an_integer)))
- 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))
-</pre>
-<p>And now the Perl program calling <code>tzname</code>, the two values will
be assigned
-as in:
-</p>
-<pre class="verbatim"> ($standard_abbrev, $summer_abbrev) = POSIX::tzname;
-</pre>
-<p>An alternate (and possibly simpler) method to pushing values on the stack is
-to use the macro:
-</p>
-<pre class="verbatim"> XPUSHs(SV*)
-</pre>
-<p>This macro automatically adjusts the stack for you, if needed. Thus, you
-do not need to call <code>EXTEND</code> to extend the stack.
-</p>
-<p>Despite their suggestions in earlier versions of this document the macros
-<code>(X)PUSH[iunp]</code> are <em>not</em> suited to XSUBs which return
multiple results.
-For that, either stick to the <code>(X)PUSHs</code> macros shown above, or use
the new
-<code>m(X)PUSH[iunp]</code> macros instead; see <a
href="#perlguts-Putting-a-C-value-on-Perl-stack">Putting a C value on Perl
stack</a>.
-</p>
-<p>For more information, consult <a href="perlxs.html#Top">(perlxs)</a> and <a
href="perlxstut.html#Top">(perlxstut)</a>.
-</p>
-<hr>
-<a name="perlguts-Autoloading-with-XSUBs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Calling-Perl-Routines-from-within-C-Programs"
accesskey="n" rel="next">perlguts Calling Perl Routines from within C
Programs</a>, Previous: <a href="#perlguts-XSUBs-and-the-Argument-Stack"
accesskey="p" rel="prev">perlguts XSUBs and the Argument Stack</a>, Up: <a
href="#perlguts-Subroutines" accesskey="u" rel="up">perlguts Subroutines</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Autoloading-with-XSUBs"></a>
-<h4 class="subsection">28.4.2 Autoloading with XSUBs</h4>
-
-<p>If an AUTOLOAD routine is an XSUB, as with Perl subroutines, Perl puts the
-fully-qualified name of the autoloaded subroutine in the $AUTOLOAD variable
-of the XSUB’s package.
-</p>
-<p>But it also puts the same information in certain fields of the XSUB itself:
-</p>
-<pre class="verbatim"> HV *stash = CvSTASH(cv);
- const char *subname = SvPVX(cv);
- STRLEN name_length = SvCUR(cv); /* in bytes */
- U32 is_utf8 = SvUTF8(cv);
-</pre>
-<p><code>SvPVX(cv)</code> contains just the sub name itself, not including the
package.
-For an AUTOLOAD routine in UNIVERSAL or one of its superclasses,
-<code>CvSTASH(cv)</code> returns NULL during a method call on a nonexistent
package.
-</p>
-<p><strong>Note</strong>: Setting $AUTOLOAD stopped working in 5.6.1, which
did not support
-XS AUTOLOAD subs at all. Perl 5.8.0 introduced the use of fields in the
-XSUB itself. Perl 5.16.0 restored the setting of $AUTOLOAD. If you need
-to support 5.8-5.14, use the XSUB’s fields.
-</p>
-<hr>
-<a name="perlguts-Calling-Perl-Routines-from-within-C-Programs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Putting-a-C-value-on-Perl-stack" accesskey="n"
rel="next">perlguts Putting a C value on Perl stack</a>, Previous: <a
href="#perlguts-Autoloading-with-XSUBs" accesskey="p" rel="prev">perlguts
Autoloading with XSUBs</a>, Up: <a href="#perlguts-Subroutines" accesskey="u"
rel="up">perlguts Subroutines</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Calling-Perl-Routines-from-within-C-Programs"></a>
-<h4 class="subsection">28.4.3 Calling Perl Routines from within C Programs</h4>
-
-<p>There are four routines that can be used to call a Perl subroutine from
-within a C program. These four are:
-</p>
-<pre class="verbatim"> I32 call_sv(SV*, I32);
- I32 call_pv(const char*, I32);
- I32 call_method(const char*, I32);
- I32 call_argv(const char*, I32, char**);
-</pre>
-<p>The routine most often used is <code>call_sv</code>. The <code>SV*</code>
argument
-contains either the name of the Perl subroutine to be called, or a
-reference to the subroutine. The second argument consists of flags
-that control the context in which the subroutine is called, whether
-or not the subroutine is being passed arguments, how errors should be
-trapped, and how to treat return values.
-</p>
-<p>All four routines return the number of arguments that the subroutine
returned
-on the Perl stack.
-</p>
-<p>These routines used to be called <code>perl_call_sv</code>, etc., before
Perl v5.6.0,
-but those names are now deprecated; macros of the same name are provided for
-compatibility.
-</p>
-<p>When using any of these routines (except <code>call_argv</code>), the
programmer
-must manipulate the Perl stack. These include the following macros and
-functions:
-</p>
-<pre class="verbatim"> dSP
- SP
- PUSHMARK()
- PUTBACK
- SPAGAIN
- ENTER
- SAVETMPS
- FREETMPS
- LEAVE
- XPUSH*()
- POP*()
-</pre>
-<p>For a detailed description of calling conventions from C to Perl,
-consult <a href="#perlcall-NAME">perlcall NAME</a>.
-</p>
-<hr>
-<a name="perlguts-Putting-a-C-value-on-Perl-stack"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Scratchpads" accesskey="n" rel="next">perlguts
Scratchpads</a>, Previous: <a
href="#perlguts-Calling-Perl-Routines-from-within-C-Programs" accesskey="p"
rel="prev">perlguts Calling Perl Routines from within C Programs</a>, Up: <a
href="#perlguts-Subroutines" accesskey="u" rel="up">perlguts Subroutines</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Putting-a-C-value-on-Perl-stack"></a>
-<h4 class="subsection">28.4.4 Putting a C value on Perl stack</h4>
-
-<p>A lot of opcodes (this is an elementary operation in the internal perl
-stack machine) put an SV* on the stack. However, as an optimization
-the corresponding SV is (usually) not recreated each time. The opcodes
-reuse specially assigned SVs (<em>target</em>s) which are (as a corollary)
-not constantly freed/created.
-</p>
-<p>Each of the targets is created only once (but see
-<a href="#perlguts-Scratchpads-and-recursion">Scratchpads and recursion</a>
below), and when an opcode needs to put
-an integer, a double, or a string on stack, it just sets the
-corresponding parts of its <em>target</em> and puts the <em>target</em> on
stack.
-</p>
-<p>The macro to put this target on stack is <code>PUSHTARG</code>, and it is
-directly used in some opcodes, as well as indirectly in zillions of
-others, which use it via <code>(X)PUSH[iunp]</code>.
-</p>
-<p>Because the target is reused, you must be careful when pushing multiple
-values on the stack. The following code will not do what you think:
-</p>
-<pre class="verbatim"> XPUSHi(10);
- XPUSHi(20);
-</pre>
-<p>This translates as "set <code>TARG</code> to 10, push a pointer to
<code>TARG</code> onto
-the stack; set <code>TARG</code> to 20, push a pointer to <code>TARG</code>
onto the stack".
-At the end of the operation, the stack does not contain the values 10
-and 20, but actually contains two pointers to <code>TARG</code>, which we have
set
-to 20.
-</p>
-<p>If you need to push multiple different values then you should either use
-the <code>(X)PUSHs</code> macros, or else use the new
<code>m(X)PUSH[iunp]</code> macros,
-none of which make use of <code>TARG</code>. The <code>(X)PUSHs</code> macros
simply push an
-SV* on the stack, which, as noted under <a
href="#perlguts-XSUBs-and-the-Argument-Stack">XSUBs and the Argument Stack</a>,
-will often need to be "mortal". The new <code>m(X)PUSH[iunp]</code>
macros make
-this a little easier to achieve by creating a new mortal for you (via
-<code>(X)PUSHmortal</code>), pushing that onto the stack (extending it if
necessary
-in the case of the <code>mXPUSH[iunp]</code> macros), and then setting its
value.
-Thus, instead of writing this to "fix" the example above:
-</p>
-<pre class="verbatim"> XPUSHs(sv_2mortal(newSViv(10)))
- XPUSHs(sv_2mortal(newSViv(20)))
-</pre>
-<p>you can simply write:
-</p>
-<pre class="verbatim"> mXPUSHi(10)
- mXPUSHi(20)
-</pre>
-<p>On a related note, if you do use <code>(X)PUSH[iunp]</code>, then
you’re going to
-need a <code>dTARG</code> in your variable declarations so that the
<code>*PUSH*</code>
-macros can make use of the local variable <code>TARG</code>. See also
<code>dTARGET</code>
-and <code>dXSTARG</code>.
-</p>
-<hr>
-<a name="perlguts-Scratchpads"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Scratchpads-and-recursion" accesskey="n"
rel="next">perlguts Scratchpads and recursion</a>, Previous: <a
href="#perlguts-Putting-a-C-value-on-Perl-stack" accesskey="p"
rel="prev">perlguts Putting a C value on Perl stack</a>, Up: <a
href="#perlguts-Subroutines" accesskey="u" rel="up">perlguts Subroutines</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Scratchpads"></a>
-<h4 class="subsection">28.4.5 Scratchpads</h4>
-
-<p>The question remains on when the SVs which are <em>target</em>s for opcodes
-are created. The answer is that they are created when the current
-unit–a subroutine or a file (for opcodes for statements outside of
-subroutines)–is compiled. During this time a special anonymous Perl
-array is created, which is called a scratchpad for the current unit.
-</p>
-<p>A scratchpad keeps SVs which are lexicals for the current unit and are
-targets for opcodes. A previous version of this document
-stated that one can deduce that an SV lives on a scratchpad
-by looking on its flags: lexicals have <code>SVs_PADMY</code> set, and
-<em>target</em>s have <code>SVs_PADTMP</code> set. But this has never been
fully true.
-<code>SVs_PADMY</code> could be set on a variable that no longer resides in
any pad.
-While <em>target</em>s do have <code>SVs_PADTMP</code> set, it can also be set
on variables
-that have never resided in a pad, but nonetheless act like <em>target</em>s.
As
-of perl 5.21.5, the <code>SVs_PADMY</code> flag is no longer used and is
defined as
-0. <code>SvPADMY()</code> now returns true for anything without
<code>SVs_PADTMP</code>.
-</p>
-<p>The correspondence between OPs and <em>target</em>s is not 1-to-1.
Different
-OPs in the compile tree of the unit can use the same target, if this
-would not conflict with the expected life of the temporary.
-</p>
-<hr>
-<a name="perlguts-Scratchpads-and-recursion"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlguts-Scratchpads" accesskey="p" rel="prev">perlguts
Scratchpads</a>, Up: <a href="#perlguts-Subroutines" accesskey="u"
rel="up">perlguts Subroutines</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Scratchpads-and-recursion"></a>
-<h4 class="subsection">28.4.6 Scratchpads and recursion</h4>
-
-<p>In fact it is not 100% true that a compiled unit contains a pointer to
-the scratchpad AV. In fact it contains a pointer to an AV of
-(initially) one element, and this element is the scratchpad AV. Why do
-we need an extra level of indirection?
-</p>
-<p>The answer is <strong>recursion</strong>, and maybe
<strong>threads</strong>. Both
-these can create several execution pointers going into the same
-subroutine. For the subroutine-child not write over the temporaries
-for the subroutine-parent (lifespan of which covers the call to the
-child), the parent and the child should have different
-scratchpads. (<em>And</em> the lexicals should be separate anyway!)
-</p>
-<p>So each subroutine is born with an array of scratchpads (of length 1).
-On each entry to the subroutine it is checked that the current
-depth of the recursion is not more than the length of this array, and
-if it is, new scratchpad is created and pushed into the array.
-</p>
-<p>The <em>target</em>s on this scratchpad are <code>undef</code>s, but they
are already
-marked with correct flags.
-</p>
-<hr>
-<a name="perlguts-Memory-Allocation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-PerlIO" accesskey="n" rel="next">perlguts PerlIO</a>,
Previous: <a href="#perlguts-Subroutines" accesskey="p" rel="prev">perlguts
Subroutines</a>, Up: <a href="#perlguts" accesskey="u" rel="up">perlguts</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Memory-Allocation"></a>
-<h3 class="section">28.5 Memory Allocation</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlguts-Allocation"
accesskey="1">perlguts Allocation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-Reallocation"
accesskey="2">perlguts Reallocation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-Moving"
accesskey="3">perlguts Moving</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlguts-Allocation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Reallocation" accesskey="n" rel="next">perlguts
Reallocation</a>, Up: <a href="#perlguts-Memory-Allocation" accesskey="u"
rel="up">perlguts Memory Allocation</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Allocation"></a>
-<h4 class="subsection">28.5.1 Allocation</h4>
-
-<p>All memory meant to be used with the Perl API functions should be
manipulated
-using the macros described in this section. The macros provide the necessary
-transparency between differences in the actual malloc implementation that is
-used within perl.
-</p>
-<p>It is suggested that you enable the version of malloc that is distributed
-with Perl. It keeps pools of various sizes of unallocated memory in
-order to satisfy allocation requests more quickly. However, on some
-platforms, it may cause spurious malloc or free errors.
-</p>
-<p>The following three macros are used to initially allocate memory :
-</p>
-<pre class="verbatim"> Newx(pointer, number, type);
- Newxc(pointer, number, type, cast);
- Newxz(pointer, number, type);
-</pre>
-<p>The first argument <code>pointer</code> should be the name of a variable
that will
-point to the newly allocated memory.
-</p>
-<p>The second and third arguments <code>number</code> and <code>type</code>
specify how many of
-the specified type of data structure should be allocated. The argument
-<code>type</code> is passed to <code>sizeof</code>. The final argument to
<code>Newxc</code>, <code>cast</code>,
-should be used if the <code>pointer</code> argument is different from the
<code>type</code>
-argument.
-</p>
-<p>Unlike the <code>Newx</code> and <code>Newxc</code> macros, the
<code>Newxz</code> macro calls <code>memzero</code>
-to zero out all the newly allocated memory.
-</p>
-<hr>
-<a name="perlguts-Reallocation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Moving" accesskey="n" rel="next">perlguts Moving</a>,
Previous: <a href="#perlguts-Allocation" accesskey="p" rel="prev">perlguts
Allocation</a>, Up: <a href="#perlguts-Memory-Allocation" accesskey="u"
rel="up">perlguts Memory Allocation</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Reallocation"></a>
-<h4 class="subsection">28.5.2 Reallocation</h4>
-
-<pre class="verbatim"> Renew(pointer, number, type);
- Renewc(pointer, number, type, cast);
- Safefree(pointer)
-</pre>
-<p>These three macros are used to change a memory buffer size or to free a
-piece of memory no longer needed. The arguments to <code>Renew</code> and
<code>Renewc</code>
-match those of <code>New</code> and <code>Newc</code> with the exception of
not needing the
-"magic cookie" argument.
-</p>
-<hr>
-<a name="perlguts-Moving"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlguts-Reallocation" accesskey="p" rel="prev">perlguts
Reallocation</a>, Up: <a href="#perlguts-Memory-Allocation" accesskey="u"
rel="up">perlguts Memory Allocation</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Moving"></a>
-<h4 class="subsection">28.5.3 Moving</h4>
-
-<pre class="verbatim"> Move(source, dest, number, type);
- Copy(source, dest, number, type);
- Zero(dest, number, type);
-</pre>
-<p>These three macros are used to move, copy, or zero out previously allocated
-memory. The <code>source</code> and <code>dest</code> arguments point to the
source and
-destination starting points. Perl will move, copy, or zero out
<code>number</code>
-instances of the size of the <code>type</code> data structure (using the
<code>sizeof</code>
-function).
-</p>
-<hr>
-<a name="perlguts-PerlIO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Compiled-code" accesskey="n" rel="next">perlguts
Compiled code</a>, Previous: <a href="#perlguts-Memory-Allocation"
accesskey="p" rel="prev">perlguts Memory Allocation</a>, Up: <a
href="#perlguts" accesskey="u" rel="up">perlguts</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PerlIO"></a>
-<h3 class="section">28.6 PerlIO</h3>
-
-<p>The most recent development releases of Perl have been experimenting with
-removing Perl’s dependency on the "normal" standard I/O suite
and allowing
-other stdio implementations to be used. This involves creating a new
-abstraction layer that then calls whichever implementation of stdio Perl
-was compiled with. All XSUBs should now use the functions in the PerlIO
-abstraction layer and not make any assumptions about what kind of stdio
-is being used.
-</p>
-<p>For a complete description of the PerlIO abstraction, consult <a
href="#perlapio-NAME">perlapio NAME</a>.
-</p>
-<hr>
-<a name="perlguts-Compiled-code"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlguts-Examining-internal-data-structures-with-the-dump-functions"
accesskey="n" rel="next">perlguts Examining internal data structures with the
<code>dump</code> functions</a>, Previous: <a href="#perlguts-PerlIO"
accesskey="p" rel="prev">perlguts PerlIO</a>, Up: <a href="#perlguts"
accesskey="u" rel="up">perlguts</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Compiled-code"></a>
-<h3 class="section">28.7 Compiled code</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlguts-Code-tree"
accesskey="1">perlguts Code tree</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Examining-the-tree" accesskey="2">perlguts Examining the
tree</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Compile-pass-1_003a-check-routines" accesskey="3">perlguts
Compile pass 1: check routines</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Compile-pass-1a_003a-constant-folding" accesskey="4">perlguts
Compile pass 1a: constant folding</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Compile-pass-2_003a-context-propagation" accesskey="5">perlguts
Compile pass 2: context propagation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Compile-pass-3_003a-peephole-optimization"
accesskey="6">perlguts Compile pass 3: peephole
optimization</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlguts-Pluggable-runops"
accesskey="7">perlguts Pluggable runops</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Compile_002dtime-scope-hooks" accesskey="8">perlguts
Compile-time scope hooks</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlguts-Code-tree"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Examining-the-tree" accesskey="n" rel="next">perlguts
Examining the tree</a>, Up: <a href="#perlguts-Compiled-code" accesskey="u"
rel="up">perlguts Compiled code</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Code-tree"></a>
-<h4 class="subsection">28.7.1 Code tree</h4>
-
-<p>Here we describe the internal form your code is converted to by
-Perl. Start with a simple example:
-</p>
-<pre class="verbatim"> $a = $b + $c;
-</pre>
-<p>This is converted to a tree similar to this one:
-</p>
-<pre class="verbatim"> assign-to
- / \
- + $a
- / \
- $b $c
-</pre>
-<p>(but slightly more complicated). This tree reflects the way Perl
-parsed your code, but has nothing to do with the execution order.
-There is an additional "thread" going through the nodes of the tree
-which shows the order of execution of the nodes. In our simplified
-example above it looks like:
-</p>
-<pre class="verbatim"> $b ---> $c ---> + ---> $a ---> assign-to
-</pre>
-<p>But with the actual compile tree for <code>$a = $b + $c</code> it is
different:
-some nodes <em>optimized away</em>. As a corollary, though the actual tree
-contains more nodes than our simplified example, the execution order
-is the same as in our example.
-</p>
-<hr>
-<a name="perlguts-Examining-the-tree"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Compile-pass-1_003a-check-routines" accesskey="n"
rel="next">perlguts Compile pass 1: check routines</a>, Previous: <a
href="#perlguts-Code-tree" accesskey="p" rel="prev">perlguts Code tree</a>, Up:
<a href="#perlguts-Compiled-code" accesskey="u" rel="up">perlguts Compiled
code</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Examining-the-tree"></a>
-<h4 class="subsection">28.7.2 Examining the tree</h4>
-
-<p>If you have your perl compiled for debugging (usually done with
-<code>-DDEBUGGING</code> on the <code>Configure</code> command line), you may
examine the
-compiled tree by specifying <code>-Dx</code> on the Perl command line. The
-output takes several lines per node, and for <code>$b+$c</code> it looks like
-this:
-</p>
-<pre class="verbatim"> 5 TYPE = add ===> 6
- TARG = 1
- FLAGS = (SCALAR,KIDS)
- {
- TYPE = null ===> (4)
- (was rv2sv)
- FLAGS = (SCALAR,KIDS)
- {
- 3 TYPE = gvsv ===> 4
- FLAGS = (SCALAR)
- GV = main::b
- }
- }
- {
- TYPE = null ===> (5)
- (was rv2sv)
- FLAGS = (SCALAR,KIDS)
- {
- 4 TYPE = gvsv ===> 5
- FLAGS = (SCALAR)
- GV = main::c
- }
- }
-</pre>
-<p>This tree has 5 nodes (one per <code>TYPE</code> specifier), only 3 of them
are
-not optimized away (one per number in the left column). The immediate
-children of the given node correspond to <code>{}</code> pairs on the same
level
-of indentation, thus this listing corresponds to the tree:
-</p>
-<pre class="verbatim"> add
- / \
- null null
- | |
- gvsv gvsv
-</pre>
-<p>The execution order is indicated by <code>===></code> marks, thus it is
<code>3
-4 5 6</code> (node <code>6</code> is not included into above listing), i.e.,
-<code>gvsv gvsv add whatever</code>.
-</p>
-<p>Each of these nodes represents an op, a fundamental operation inside the
-Perl core. The code which implements each operation can be found in the
-<samp>pp*.c</samp> files; the function which implements the op with type
<code>gvsv</code>
-is <code>pp_gvsv</code>, and so on. As the tree above shows, different ops
have
-different numbers of children: <code>add</code> is a binary operator, as one
would
-expect, and so has two children. To accommodate the various different
-numbers of children, there are various types of op data structure, and
-they link together in different ways.
-</p>
-<p>The simplest type of op structure is <code>OP</code>: this has no children.
Unary
-operators, <code>UNOP</code>s, have one child, and this is pointed to by the
-<code>op_first</code> field. Binary operators (<code>BINOP</code>s) have not
only an
-<code>op_first</code> field but also an <code>op_last</code> field. The most
complex type of
-op is a <code>LISTOP</code>, which has any number of children. In this case,
the
-first child is pointed to by <code>op_first</code> and the last child by
-<code>op_last</code>. The children in between can be found by iteratively
-following the <code>OpSIBLING</code> pointer from the first child to the last
(but
-see below).
-</p>
-<p>There are also some other op types: a <code>PMOP</code> holds a regular
expression,
-and has no children, and a <code>LOOP</code> may or may not have children. If
the
-<code>op_children</code> field is non-zero, it behaves like a
<code>LISTOP</code>. To
-complicate matters, if a <code>UNOP</code> is actually a <code>null</code> op
after
-optimization (see <a
href="#perlguts-Compile-pass-2_003a-context-propagation">Compile pass 2:
context propagation</a>) it will still
-have children in accordance with its former type.
-</p>
-<p>Finally, there is a <code>LOGOP</code>, or logic op. Like a
<code>LISTOP</code>, this has one
-or more children, but it doesn’t have an <code>op_last</code> field: so
you have to
-follow <code>op_first</code> and then the <code>OpSIBLING</code> chain itself
to find the
-last child. Instead it has an <code>op_other</code> field, which is comparable
to
-the <code>op_next</code> field described below, and represents an alternate
-execution path. Operators like <code>and</code>, <code>or</code> and
<code>?</code> are <code>LOGOP</code>s. Note
-that in general, <code>op_other</code> may not point to any of the direct
children
-of the <code>LOGOP</code>.
-</p>
-<p>Starting in version 5.21.2, perls built with the experimental
-define <code>-DPERL_OP_PARENT</code> add an extra boolean flag for each op,
-<code>op_moresib</code>. When not set, this indicates that this is the last
op in an
-<code>OpSIBLING</code> chain. This frees up the <code>op_sibling</code> field
on the last
-sibling to point back to the parent op. Under this build, that field is
-also renamed <code>op_sibparent</code> to reflect its joint role. The macro
-<code>OpSIBLING(o)</code> wraps this special behaviour, and always returns
NULL on
-the last sibling. With this build the <code>op_parent(o)</code> function can
be
-used to find the parent of any op. Thus for forward compatibility, you
-should always use the <code>OpSIBLING(o)</code> macro rather than accessing
-<code>op_sibling</code> directly.
-</p>
-<p>Another way to examine the tree is to use a compiler back-end module, such
-as <a href="B-Concise.html#Top">(B-Concise)</a>.
-</p>
-<hr>
-<a name="perlguts-Compile-pass-1_003a-check-routines"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Compile-pass-1a_003a-constant-folding" accesskey="n"
rel="next">perlguts Compile pass 1a: constant folding</a>, Previous: <a
href="#perlguts-Examining-the-tree" accesskey="p" rel="prev">perlguts Examining
the tree</a>, Up: <a href="#perlguts-Compiled-code" accesskey="u"
rel="up">perlguts Compiled code</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Compile-pass-1_003a-check-routines"></a>
-<h4 class="subsection">28.7.3 Compile pass 1: check routines</h4>
-
-<p>The tree is created by the compiler while <em>yacc</em> code feeds it
-the constructions it recognizes. Since <em>yacc</em> works bottom-up, so does
-the first pass of perl compilation.
-</p>
-<p>What makes this pass interesting for perl developers is that some
-optimization may be performed on this pass. This is optimization by
-so-called "check routines". The correspondence between node names
-and corresponding check routines is described in <samp>opcode.pl</samp> (do not
-forget to run <code>make regen_headers</code> if you modify this file).
-</p>
-<p>A check routine is called when the node is fully constructed except
-for the execution-order thread. Since at this time there are no
-back-links to the currently constructed node, one can do most any
-operation to the top-level node, including freeing it and/or creating
-new nodes above/below it.
-</p>
-<p>The check routine returns the node which should be inserted into the
-tree (if the top-level node was not modified, check routine returns
-its argument).
-</p>
-<p>By convention, check routines have names <code>ck_*</code>. They are
usually
-called from <code>new*OP</code> subroutines (or <code>convert</code>) (which
in turn are
-called from <samp>perly.y</samp>).
-</p>
-<hr>
-<a name="perlguts-Compile-pass-1a_003a-constant-folding"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Compile-pass-2_003a-context-propagation"
accesskey="n" rel="next">perlguts Compile pass 2: context propagation</a>,
Previous: <a href="#perlguts-Compile-pass-1_003a-check-routines" accesskey="p"
rel="prev">perlguts Compile pass 1: check routines</a>, Up: <a
href="#perlguts-Compiled-code" accesskey="u" rel="up">perlguts Compiled
code</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Compile-pass-1a_003a-constant-folding"></a>
-<h4 class="subsection">28.7.4 Compile pass 1a: constant folding</h4>
-
-<p>Immediately after the check routine is called the returned node is
-checked for being compile-time executable. If it is (the value is
-judged to be constant) it is immediately executed, and a <em>constant</em>
-node with the "return value" of the corresponding subtree is
-substituted instead. The subtree is deleted.
-</p>
-<p>If constant folding was not performed, the execution-order thread is
-created.
-</p>
-<hr>
-<a name="perlguts-Compile-pass-2_003a-context-propagation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Compile-pass-3_003a-peephole-optimization"
accesskey="n" rel="next">perlguts Compile pass 3: peephole optimization</a>,
Previous: <a href="#perlguts-Compile-pass-1a_003a-constant-folding"
accesskey="p" rel="prev">perlguts Compile pass 1a: constant folding</a>, Up: <a
href="#perlguts-Compiled-code" accesskey="u" rel="up">perlguts Compiled
code</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Compile-pass-2_003a-context-propagation"></a>
-<h4 class="subsection">28.7.5 Compile pass 2: context propagation</h4>
-
-<p>When a context for a part of compile tree is known, it is propagated
-down through the tree. At this time the context can have 5 values
-(instead of 2 for runtime context): void, boolean, scalar, list, and
-lvalue. In contrast with the pass 1 this pass is processed from top
-to bottom: a node’s context determines the context for its children.
-</p>
-<p>Additional context-dependent optimizations are performed at this time.
-Since at this moment the compile tree contains back-references (via
-"thread" pointers), nodes cannot be free()d now. To allow
-optimized-away nodes at this stage, such nodes are null()ified instead
-of free()ing (i.e. their type is changed to OP_NULL).
-</p>
-<hr>
-<a name="perlguts-Compile-pass-3_003a-peephole-optimization"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Pluggable-runops" accesskey="n" rel="next">perlguts
Pluggable runops</a>, Previous: <a
href="#perlguts-Compile-pass-2_003a-context-propagation" accesskey="p"
rel="prev">perlguts Compile pass 2: context propagation</a>, Up: <a
href="#perlguts-Compiled-code" accesskey="u" rel="up">perlguts Compiled
code</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Compile-pass-3_003a-peephole-optimization"></a>
-<h4 class="subsection">28.7.6 Compile pass 3: peephole optimization</h4>
-
-<p>After the compile tree for a subroutine (or for an <code>eval</code> 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). Optimizations performed
-at this stage are subject to the same restrictions as in the pass 2.
-</p>
-<p>Peephole optimizations are done by calling the function pointed to
-by the global variable <code>PL_peepp</code>. By default,
<code>PL_peepp</code> just
-calls the function pointed to by the global variable <code>PL_rpeepp</code>.
-By default, that performs some basic op fixups and optimisations along
-the execution-order op chain, and recursively calls <code>PL_rpeepp</code> 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:
-</p>
-<pre class="verbatim"> static peep_t prev_peepp;
- static void my_peep(pTHX_ OP *o)
- {
- /* custom per-subroutine optimisation goes here */
- prev_peepp(aTHX_ 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(aTHX_ orig_o);
- }
- BOOT:
- prev_rpeepp = PL_rpeepp;
- PL_rpeepp = my_rpeep;
-</pre>
-<hr>
-<a name="perlguts-Pluggable-runops"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Compile_002dtime-scope-hooks" accesskey="n"
rel="next">perlguts Compile-time scope hooks</a>, Previous: <a
href="#perlguts-Compile-pass-3_003a-peephole-optimization" accesskey="p"
rel="prev">perlguts Compile pass 3: peephole optimization</a>, Up: <a
href="#perlguts-Compiled-code" accesskey="u" rel="up">perlguts Compiled
code</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Pluggable-runops"></a>
-<h4 class="subsection">28.7.7 Pluggable runops</h4>
-
-<p>The compile tree is executed in a runops function. There are two runops
-functions, in <samp>run.c</samp> and in <samp>dump.c</samp>.
<code>Perl_runops_debug</code> is used
-with DEBUGGING and <code>Perl_runops_standard</code> is used otherwise. For
fine
-control over the execution of the compile tree it is possible to provide
-your own runops function.
-</p>
-<p>It’s probably best to copy one of the existing runops functions and
-change it to suit your needs. Then, in the BOOT section of your XS
-file, add the line:
-</p>
-<pre class="verbatim"> PL_runops = my_runops;
-</pre>
-<p>This function should be as efficient as possible to keep your programs
-running as fast as possible.
-</p>
-<hr>
-<a name="perlguts-Compile_002dtime-scope-hooks"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlguts-Pluggable-runops" accesskey="p"
rel="prev">perlguts Pluggable runops</a>, Up: <a href="#perlguts-Compiled-code"
accesskey="u" rel="up">perlguts Compiled code</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Compile_002dtime-scope-hooks"></a>
-<h4 class="subsection">28.7.8 Compile-time scope hooks</h4>
-
-<p>As of perl 5.14 it is possible to hook into the compile-time lexical
-scope mechanism using <code>Perl_blockhook_register</code>. This is used like
-this:
-</p>
-<pre class="verbatim"> 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);
-</pre>
-<p>This will arrange to have <code>my_start_hook</code> called at the start of
-compiling every lexical scope. The available hooks are:
-</p>
-<dl compact="compact">
-<dt><code>void bhk_start(pTHX_ int full)</code></dt>
-<dd><a name="perlguts-void-bhk_005fstart_0028pTHX_005f-int-full_0029"></a>
-<p>This is called just after starting a new lexical scope. Note that Perl
-code like
-</p>
-<pre class="verbatim"> if ($x) { ... }
-</pre>
-<p>creates two scopes: the first starts at the <code>(</code> and has
<code>full == 1</code>,
-the second starts at the <code>{</code> and has <code>full == 0</code>. Both
end at the
-<code>}</code>, so calls to <code>start</code> and <code>pre/post_end</code>
will match. Anything
-pushed onto the save stack by this hook will be popped just before the
-scope ends (between the <code>pre_</code> and <code>post_end</code> hooks, in
fact).
-</p>
-</dd>
-<dt><code>void bhk_pre_end(pTHX_ OP **o)</code></dt>
-<dd><a
name="perlguts-void-bhk_005fpre_005fend_0028pTHX_005f-OP-_002a_002ao_0029"></a>
-<p>This is called at the end of a lexical scope, just before unwinding the
-stack. <em>o</em> is the root of the optree representing the scope; it is a
-double pointer so you can replace the OP if you need to.
-</p>
-</dd>
-<dt><code>void bhk_post_end(pTHX_ OP **o)</code></dt>
-<dd><a
name="perlguts-void-bhk_005fpost_005fend_0028pTHX_005f-OP-_002a_002ao_0029"></a>
-<p>This is called at the end of a lexical scope, just after unwinding the
-stack. <em>o</em> is as above. Note that it is possible for calls to
<code>pre_</code>
-and <code>post_end</code> to nest, if there is something on the save stack that
-calls string eval.
-</p>
-</dd>
-<dt><code>void bhk_eval(pTHX_ OP *const o)</code></dt>
-<dd><a
name="perlguts-void-bhk_005feval_0028pTHX_005f-OP-_002aconst-o_0029"></a>
-<p>This is called just before starting to compile an <code>eval STRING</code>,
<code>do
-FILE</code>, <code>require</code> or <code>use</code>, after the eval has been
set up. <em>o</em> is the
-OP that requested the eval, and will normally be an <code>OP_ENTEREVAL</code>,
-<code>OP_DOFILE</code> or <code>OP_REQUIRE</code>.
-</p>
-</dd>
-</dl>
-
-<p>Once you have your hook functions, you need a <code>BHK</code> 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 <code>BhkENTRY_set</code> macro, which will also
set
-flags indicating which entries are valid. If you do need to allocate
-your <code>BHK</code> dynamically for some reason, be sure to zero it before
you
-start.
-</p>
-<p>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
<code>%^H</code>
-is probably the best way, so the effect is lexically scoped; however it
-is also possible to use the <code>BhkDISABLE</code> and <code>BhkENABLE</code>
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 <code>pre/post_end</code> pairs that
-didn’t have a matching <code>start</code>.
-</p>
-<hr>
-<a
name="perlguts-Examining-internal-data-structures-with-the-dump-functions"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlguts-How-multiple-interpreters-and-concurrency-are-supported"
accesskey="n" rel="next">perlguts How multiple interpreters and concurrency are
supported</a>, Previous: <a href="#perlguts-Compiled-code" accesskey="p"
rel="prev">perlguts Compiled code</a>, Up: <a href="#perlguts" accesskey="u"
rel="up">perlguts</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Examining-internal-data-structures-with-the-dump-functions"></a>
-<h3 class="section">28.8 Examining internal data structures with the
<code>dump</code> functions</h3>
-
-<p>To aid debugging, the source file <samp>dump.c</samp> contains a number of
-functions which produce formatted output of internal data structures.
-</p>
-<p>The most commonly used of these functions is <code>Perl_sv_dump</code>;
it’s used
-for dumping SVs, AVs, HVs, and CVs. The <code>Devel::Peek</code> module calls
-<code>sv_dump</code> to produce debugging output from Perl-space, so users of
that
-module should already be familiar with its format.
-</p>
-<p><code>Perl_op_dump</code> can be used to dump an <code>OP</code> structure
or any of its
-derivatives, and produces output similar to <code>perl -Dx</code>; in fact,
-<code>Perl_dump_eval</code> will dump the main root of the code being
evaluated,
-exactly like <code>-Dx</code>.
-</p>
-<p>Other useful functions are <code>Perl_dump_sub</code>, which turns a
<code>GV</code> into an
-op tree, <code>Perl_dump_packsubs</code> which calls
<code>Perl_dump_sub</code> on all the
-subroutines in a package like so: (Thankfully, these are all xsubs, so
-there is no op tree)
-</p>
-<pre class="verbatim"> (gdb) print Perl_dump_packsubs(PL_defstash)
-
- SUB attributes::bootstrap = (xsub 0x811fedc 0)
-
- SUB UNIVERSAL::can = (xsub 0x811f50c 0)
-
- SUB UNIVERSAL::isa = (xsub 0x811f304 0)
-
- SUB UNIVERSAL::VERSION = (xsub 0x811f7ac 0)
-
- SUB DynaLoader::boot_DynaLoader = (xsub 0x805b188 0)
-</pre>
-<p>and <code>Perl_dump_all</code>, which dumps all the subroutines in the
stash and
-the op tree of the main root.
-</p>
-<hr>
-<a name="perlguts-How-multiple-interpreters-and-concurrency-are-supported"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Internal-Functions" accesskey="n" rel="next">perlguts
Internal Functions</a>, Previous: <a
href="#perlguts-Examining-internal-data-structures-with-the-dump-functions"
accesskey="p" rel="prev">perlguts Examining internal data structures with the
<code>dump</code> functions</a>, Up: <a href="#perlguts" accesskey="u"
rel="up">perlguts</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="How-multiple-interpreters-and-concurrency-are-supported"></a>
-<h3 class="section">28.9 How multiple interpreters and concurrency are
supported</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlguts-Background-and-PERL_005fIMPLICIT_005fCONTEXT"
accesskey="1">perlguts Background and
PERL_IMPLICIT_CONTEXT</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-So-what-happened-to-dTHR_003f" accesskey="2">perlguts So what
happened to dTHR?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-How-do-I-use-all-this-in-extensions_003f"
accesskey="3">perlguts How do I use all this in
extensions?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Should-I-do-anything-special-if-I-call-perl-from-multiple-threads_003f"
accesskey="4">perlguts Should I do anything special if I call perl from
multiple threads?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Future-Plans-and-PERL_005fIMPLICIT_005fSYS"
accesskey="5">perlguts Future Plans and
PERL_IMPLICIT_SYS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlguts-Background-and-PERL_005fIMPLICIT_005fCONTEXT"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-So-what-happened-to-dTHR_003f" accesskey="n"
rel="next">perlguts So what happened to dTHR?</a>, Up: <a
href="#perlguts-How-multiple-interpreters-and-concurrency-are-supported"
accesskey="u" rel="up">perlguts How multiple interpreters and concurrency are
supported</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Background-and-PERL_005fIMPLICIT_005fCONTEXT"></a>
-<h4 class="subsection">28.9.1 Background and PERL_IMPLICIT_CONTEXT</h4>
-
-<p>The Perl interpreter can be regarded as a closed box: it has an API
-for feeding it code or otherwise making it do things, but it also has
-functions for its own use. This smells a lot like an object, and
-there are ways for you to build Perl so that you can have multiple
-interpreters, with one interpreter represented either as a C structure,
-or inside a thread-specific structure. These structures contain all
-the context, the state of that interpreter.
-</p>
-<p>One macro controls the major Perl build flavor: MULTIPLICITY. The
-MULTIPLICITY build has a C structure that packages all the interpreter
-state. With multiplicity-enabled perls, PERL_IMPLICIT_CONTEXT is also
-normally defined, and enables the support for passing in a "hidden"
first
-argument that represents all three data structures. MULTIPLICITY makes
-multi-threaded perls possible (with the ithreads threading model, related
-to the macro USE_ITHREADS.)
-</p>
-<p>Two other "encapsulation" macros are the PERL_GLOBAL_STRUCT and
-PERL_GLOBAL_STRUCT_PRIVATE (the latter turns on the former, and the
-former turns on MULTIPLICITY.) The PERL_GLOBAL_STRUCT causes all the
-internal variables of Perl to be wrapped inside a single global struct,
-struct perl_vars, accessible as (globals) &PL_Vars or PL_VarsPtr or
-the function Perl_GetVars(). The PERL_GLOBAL_STRUCT_PRIVATE goes
-one step further, there is still a single struct (allocated in main()
-either from heap or from stack) but there are no global data symbols
-pointing to it. In either case the global struct should be initialized
-as the very first thing in main() using Perl_init_global_struct() and
-correspondingly tear it down after perl_free() using Perl_free_global_struct(),
-please see <samp>miniperlmain.c</samp> for usage details. You may also need
-to use <code>dVAR</code> in your coding to "declare the global
variables"
-when you are using them. dTHX does this for you automatically.
-</p>
-<p>To see whether you have non-const data you can use a BSD (or GNU)
-compatible <code>nm</code>:
-</p>
-<pre class="verbatim"> nm libperl.a | grep -v ' [TURtr] '
-</pre>
-<p>If this displays any <code>D</code> or <code>d</code> symbols (or possibly
<code>C</code> or <code>c</code>),
-you have non-const data. The symbols the <code>grep</code> removed are as
follows:
-<code>Tt</code> are <em>text</em>, or code, the <code>Rr</code> are
<em>read-only</em> (const) data,
-and the <code>U</code> is <undefined>, external symbols referred to.
-</p>
-<p>The test <samp>t/porting/libperl.t</samp> does this kind of symbol sanity
-checking on <code>libperl.a</code>.
-</p>
-<p>For backward compatibility reasons defining just PERL_GLOBAL_STRUCT
-doesn’t actually hide all symbols inside a big global struct: some
-PerlIO_xxx vtables are left visible. The PERL_GLOBAL_STRUCT_PRIVATE
-then hides everything (see how the PERLIO_FUNCS_DECL is used).
-</p>
-<p>All this obviously requires a way for the Perl internal functions to be
-either subroutines taking some kind of structure as the first
-argument, or subroutines taking nothing as the first argument. To
-enable these two very different ways of building the interpreter,
-the Perl source (as it does in so many other situations) makes heavy
-use of macros and subroutine naming conventions.
-</p>
-<p>First problem: deciding which functions will be public API functions and
-which will be private. All functions whose names begin <code>S_</code> are
private
-(think "S" for "secret" or "static"). All other
functions begin with
-"Perl_", but just because a function begins with "Perl_"
does not mean it is
-part of the API. (See <a href="#perlguts-Internal-Functions">Internal
-Functions</a>.) The easiest way to be <strong>sure</strong> a
-function is part of the API is to find its entry in <a
href="perlapi.html#Top">(perlapi)</a>.
-If it exists in <a href="perlapi.html#Top">(perlapi)</a>, it’s part of
the API. If it doesn’t, and you
-think it should be (i.e., you need it for your extension), send mail via
-<a href="perlbug.html#Top">(perlbug)</a> explaining why you think it should be.
-</p>
-<p>Second problem: there must be a syntax so that the same subroutine
-declarations and calls can pass a structure as their first argument,
-or pass nothing. To solve this, the subroutines are named and
-declared in a particular way. Here’s a typical start of a static
-function used within the Perl guts:
-</p>
-<pre class="verbatim"> STATIC void
- S_incline(pTHX_ char *s)
-</pre>
-<p>STATIC becomes "static" in C, and may be #define’d to
nothing in some
-configurations in the future.
-</p>
-<p>A public function (i.e. part of the internal API, but not necessarily
-sanctioned for use in extensions) begins like this:
-</p>
-<pre class="verbatim"> void
- Perl_sv_setiv(pTHX_ SV* dsv, IV num)
-</pre>
-<p><code>pTHX_</code> is one of a number of macros (in <samp>perl.h</samp>)
that hide the
-details of the interpreter’s context. THX stands for
"thread", "this",
-or "thingy", as the case may be. (And no, George Lucas is not
involved. :-)
-The first character could be ’p’ for a <strong>p</strong>rototype,
’a’ for <strong>a</strong>rgument,
-or ’d’ for <strong>d</strong>eclaration, so we have
<code>pTHX</code>, <code>aTHX</code> and <code>dTHX</code>, and
-their variants.
-</p>
-<p>When Perl is built without options that set PERL_IMPLICIT_CONTEXT, there is
no
-first argument containing the interpreter’s context. The trailing
underscore
-in the pTHX_ macro indicates that the macro expansion needs a comma
-after the context argument because other arguments follow it. If
-PERL_IMPLICIT_CONTEXT is not defined, pTHX_ will be ignored, and the
-subroutine is not prototyped to take the extra argument. The form of the
-macro without the trailing underscore is used when there are no additional
-explicit arguments.
-</p>
-<p>When a core function calls another, it must pass the context. This
-is normally hidden via macros. Consider <code>sv_setiv</code>. It expands
into
-something like this:
-</p>
-<pre class="verbatim"> #ifdef PERL_IMPLICIT_CONTEXT
- #define sv_setiv(a,b) Perl_sv_setiv(aTHX_ a, b)
- /* can't do this for vararg functions, see below */
- #else
- #define sv_setiv Perl_sv_setiv
- #endif
-</pre>
-<p>This works well, and means that XS authors can gleefully write:
-</p>
-<pre class="verbatim"> sv_setiv(foo, bar);
-</pre>
-<p>and still have it work under all the modes Perl could have been
-compiled with.
-</p>
-<p>This doesn’t work so cleanly for varargs functions, though, as macros
-imply that the number of arguments is known in advance. Instead we
-either need to spell them out fully, passing <code>aTHX_</code> as the first
-argument (the Perl core tends to do this with functions like
-Perl_warner), or use a context-free version.
-</p>
-<p>The context-free version of Perl_warner is called
-Perl_warner_nocontext, and does not take the extra argument. Instead
-it does dTHX; to get the context from thread-local storage. We
-<code>#define warner Perl_warner_nocontext</code> so that extensions get source
-compatibility at the expense of performance. (Passing an arg is
-cheaper than grabbing it from thread-local storage.)
-</p>
-<p>You can ignore [pad]THXx when browsing the Perl headers/sources.
-Those are strictly for use within the core. Extensions and embedders
-need only be aware of [pad]THX.
-</p>
-<hr>
-<a name="perlguts-So-what-happened-to-dTHR_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-How-do-I-use-all-this-in-extensions_003f"
accesskey="n" rel="next">perlguts How do I use all this in extensions?</a>,
Previous: <a href="#perlguts-Background-and-PERL_005fIMPLICIT_005fCONTEXT"
accesskey="p" rel="prev">perlguts Background and PERL_IMPLICIT_CONTEXT</a>, Up:
<a href="#perlguts-How-multiple-interpreters-and-concurrency-are-supported"
accesskey="u" rel="up">perlguts How multiple interpreters and concurrency are
supported</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="So-what-happened-to-dTHR_003f"></a>
-<h4 class="subsection">28.9.2 So what happened to dTHR?</h4>
-
-<p><code>dTHR</code> was introduced in perl 5.005 to support the older thread
model.
-The older thread model now uses the <code>THX</code> mechanism to pass context
-pointers around, so <code>dTHR</code> is not useful any more. Perl 5.6.0 and
-later still have it for backward source compatibility, but it is defined
-to be a no-op.
-</p>
-<hr>
-<a name="perlguts-How-do-I-use-all-this-in-extensions_003f"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlguts-Should-I-do-anything-special-if-I-call-perl-from-multiple-threads_003f"
accesskey="n" rel="next">perlguts Should I do anything special if I call perl
from multiple threads?</a>, Previous: <a
href="#perlguts-So-what-happened-to-dTHR_003f" accesskey="p"
rel="prev">perlguts So what happened to dTHR?</a>, Up: <a
href="#perlguts-How-multiple-interpreters-and-concurrency-are-supported"
accesskey="u" rel="up">perlguts How multiple interpreters and concurrency are
supported</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="How-do-I-use-all-this-in-extensions_003f"></a>
-<h4 class="subsection">28.9.3 How do I use all this in extensions?</h4>
-
-<p>When Perl is built with PERL_IMPLICIT_CONTEXT, extensions that call
-any functions in the Perl API will need to pass the initial context
-argument somehow. The kicker is that you will need to write it in
-such a way that the extension still compiles when Perl hasn’t been
-built with PERL_IMPLICIT_CONTEXT enabled.
-</p>
-<p>There are three ways to do this. First, the easy but inefficient way,
-which is also the default, in order to maintain source compatibility
-with extensions: whenever <samp>XSUB.h</samp> is #included, it redefines the
aTHX
-and aTHX_ macros to call a function that will return the context.
-Thus, something like:
-</p>
-<pre class="verbatim"> sv_setiv(sv, num);
-</pre>
-<p>in your extension will translate to this when PERL_IMPLICIT_CONTEXT is
-in effect:
-</p>
-<pre class="verbatim"> Perl_sv_setiv(Perl_get_context(), sv, num);
-</pre>
-<p>or to this otherwise:
-</p>
-<pre class="verbatim"> Perl_sv_setiv(sv, num);
-</pre>
-<p>You don’t have to do anything new in your extension to get this; since
-the Perl library provides Perl_get_context(), it will all just
-work.
-</p>
-<p>The second, more efficient way is to use the following template for
-your Foo.xs:
-</p>
-<pre class="verbatim"> #define PERL_NO_GET_CONTEXT /* we want
efficiency */
- #include "EXTERN.h"
- #include "perl.h"
- #include "XSUB.h"
-
- STATIC void my_private_function(int arg1, int arg2);
-
- STATIC void
- my_private_function(int arg1, int arg2)
- {
- dTHX; /* fetch context */
- ... call many Perl API functions ...
- }
-
- [... etc ...]
-
- MODULE = Foo PACKAGE = Foo
-
- /* typical XSUB */
-
- void
- my_xsub(arg)
- int arg
- CODE:
- my_private_function(arg, 10);
-</pre>
-<p>Note that the only two changes from the normal way of writing an
-extension is the addition of a <code>#define PERL_NO_GET_CONTEXT</code> before
-including the Perl headers, followed by a <code>dTHX;</code> declaration at
-the start of every function that will call the Perl API. (You’ll
-know which functions need this, because the C compiler will complain
-that there’s an undeclared identifier in those functions.) No changes
-are needed for the XSUBs themselves, because the XS() macro is
-correctly defined to pass in the implicit context if needed.
-</p>
-<p>The third, even more efficient way is to ape how it is done within
-the Perl guts:
-</p>
-<pre class="verbatim"> #define PERL_NO_GET_CONTEXT /* we want
efficiency */
- #include "EXTERN.h"
- #include "perl.h"
- #include "XSUB.h"
-
- /* pTHX_ only needed for functions that call Perl API */
- STATIC void my_private_function(pTHX_ int arg1, int arg2);
-
- STATIC void
- my_private_function(pTHX_ int arg1, int arg2)
- {
- /* dTHX; not needed here, because THX is an argument */
- ... call Perl API functions ...
- }
-
- [... etc ...]
-
- MODULE = Foo PACKAGE = Foo
-
- /* typical XSUB */
-
- void
- my_xsub(arg)
- int arg
- CODE:
- my_private_function(aTHX_ arg, 10);
-</pre>
-<p>This implementation never has to fetch the context using a function
-call, since it is always passed as an extra argument. Depending on
-your needs for simplicity or efficiency, you may mix the previous
-two approaches freely.
-</p>
-<p>Never add a comma after <code>pTHX</code> yourself–always use the
form of the
-macro with the underscore for functions that take explicit arguments,
-or the form without the argument for functions with no explicit arguments.
-</p>
-<p>If one is compiling Perl with the <code>-DPERL_GLOBAL_STRUCT</code> the
<code>dVAR</code>
-definition is needed if the Perl global variables (see <samp>perlvars.h</samp>
-or <samp>globvar.sym</samp>) are accessed in the function and
<code>dTHX</code> is not
-used (the <code>dTHX</code> includes the <code>dVAR</code> if necessary). One
notices
-the need for <code>dVAR</code> only with the said compile-time define, because
-otherwise the Perl global variables are visible as-is.
-</p>
-<hr>
-<a
name="perlguts-Should-I-do-anything-special-if-I-call-perl-from-multiple-threads_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Future-Plans-and-PERL_005fIMPLICIT_005fSYS"
accesskey="n" rel="next">perlguts Future Plans and PERL_IMPLICIT_SYS</a>,
Previous: <a href="#perlguts-How-do-I-use-all-this-in-extensions_003f"
accesskey="p" rel="prev">perlguts How do I use all this in extensions?</a>, Up:
<a href="#perlguts-How-multiple-interpreters-and-concurrency-are-supported"
accesskey="u" rel="up">perlguts How multiple interpreters and concurrency are
supported</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a
name="Should-I-do-anything-special-if-I-call-perl-from-multiple-threads_003f"></a>
-<h4 class="subsection">28.9.4 Should I do anything special if I call perl from
multiple threads?</h4>
-
-<p>If you create interpreters in one thread and then proceed to call them in
-another, you need to make sure perl’s own Thread Local Storage (TLS)
slot is
-initialized correctly in each of those threads.
-</p>
-<p>The <code>perl_alloc</code> and <code>perl_clone</code> API functions will
automatically set
-the TLS slot to the interpreter they created, so that there is no need to do
-anything special if the interpreter is always accessed in the same thread that
-created it, and that thread did not create or call any other interpreters
-afterwards. If that is not the case, you have to set the TLS slot of the
-thread before calling any functions in the Perl API on that particular
-interpreter. This is done by calling the <code>PERL_SET_CONTEXT</code> macro
in that
-thread as the first thing you do:
-</p>
-<pre class="verbatim"> /* do this before doing anything else with
some_perl */
- PERL_SET_CONTEXT(some_perl);
-
- ... other Perl API calls on some_perl go here ...
-</pre>
-<hr>
-<a name="perlguts-Future-Plans-and-PERL_005fIMPLICIT_005fSYS"></a>
-<div class="header">
-<p>
-Previous: <a
href="#perlguts-Should-I-do-anything-special-if-I-call-perl-from-multiple-threads_003f"
accesskey="p" rel="prev">perlguts Should I do anything special if I call perl
from multiple threads?</a>, Up: <a
href="#perlguts-How-multiple-interpreters-and-concurrency-are-supported"
accesskey="u" rel="up">perlguts How multiple interpreters and concurrency are
supported</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Future-Plans-and-PERL_005fIMPLICIT_005fSYS"></a>
-<h4 class="subsection">28.9.5 Future Plans and PERL_IMPLICIT_SYS</h4>
-
-<p>Just as PERL_IMPLICIT_CONTEXT provides a way to bundle up everything
-that the interpreter knows about itself and pass it around, so too are
-there plans to allow the interpreter to bundle up everything it knows
-about the environment it’s running on. This is enabled with the
-PERL_IMPLICIT_SYS macro. Currently it only works with USE_ITHREADS on
-Windows.
-</p>
-<p>This allows the ability to provide an extra pointer (called the
"host"
-environment) for all the system calls. This makes it possible for
-all the system stuff to maintain their own state, broken down into
-seven C structures. These are thin wrappers around the usual system
-calls (see <samp>win32/perllib.c</samp>) for the default perl executable, but
for a
-more ambitious host (like the one that would do fork() emulation) all
-the extra work needed to pretend that different interpreters are
-actually different "processes", would be done here.
-</p>
-<p>The Perl engine/interpreter and the host are orthogonal entities.
-There could be one or more interpreters in a process, and one or
-more "hosts", with free association between them.
-</p>
-<hr>
-<a name="perlguts-Internal-Functions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Unicode-Support" accesskey="n" rel="next">perlguts
Unicode Support</a>, Previous: <a
href="#perlguts-How-multiple-interpreters-and-concurrency-are-supported"
accesskey="p" rel="prev">perlguts How multiple interpreters and concurrency are
supported</a>, Up: <a href="#perlguts" accesskey="u" rel="up">perlguts</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Internal-Functions"></a>
-<h3 class="section">28.10 Internal Functions</h3>
-
-<p>All of Perl’s internal functions which will be exposed to the outside
-world are prefixed by <code>Perl_</code> so that they will not conflict with XS
-functions or functions used in a program in which Perl is embedded.
-Similarly, all global variables begin with <code>PL_</code>. (By convention,
-static functions start with <code>S_</code>.)
-</p>
-<p>Inside the Perl core (<code>PERL_CORE</code> defined), you can get at the
functions
-either with or without the <code>Perl_</code> prefix, thanks to a bunch of
defines
-that live in <samp>embed.h</samp>. Note that extension code should
<em>not</em> set
-<code>PERL_CORE</code>; this exposes the full perl internals, and is likely to
cause
-breakage of the XS in each new perl release.
-</p>
-<p>The file <samp>embed.h</samp> is generated automatically from
-<samp>embed.pl</samp> and <samp>embed.fnc</samp>. <samp>embed.pl</samp> also
creates the prototyping
-header files for the internal functions, generates the documentation
-and a lot of other bits and pieces. It’s important that when you add
-a new function to the core or change an existing one, you change the
-data in the table in <samp>embed.fnc</samp> as well. Here’s a sample
entry from
-that table:
-</p>
-<pre class="verbatim"> Apd |SV** |av_fetch |AV* ar|I32 key|I32 lval
-</pre>
-<p>The second column is the return type, the third column the name. Columns
-after that are the arguments. The first column is a set of flags:
-</p>
-<dl compact="compact">
-<dt>A</dt>
-<dd><a name="perlguts-A"></a>
-<p>This function is a part of the public
-API. All such functions should also
-have ’d’, very few do not.
-</p>
-</dd>
-<dt>p</dt>
-<dd><a name="perlguts-p"></a>
-<p>This function has a <code>Perl_</code> prefix; i.e. it is defined as
-<code>Perl_av_fetch</code>.
-</p>
-</dd>
-<dt>d</dt>
-<dd><a name="perlguts-d"></a>
-<p>This function has documentation using the <code>apidoc</code> feature which
we’ll
-look at in a second. Some functions have ’d’ but not
’A’; docs are good.
-</p>
-</dd>
-</dl>
-
-<p>Other available flags are:
-</p>
-<dl compact="compact">
-<dt>s</dt>
-<dd><a name="perlguts-s"></a>
-<p>This is a static function and is defined as <code>STATIC S_whatever</code>,
and
-usually called within the sources as <code>whatever(...)</code>.
-</p>
-</dd>
-<dt>n</dt>
-<dd><a name="perlguts-n"></a>
-<p>This does not need an interpreter context, so the definition has no
-<code>pTHX</code>, and it follows that callers don’t use
<code>aTHX</code>. (See
-<a href="#perlguts-Background-and-PERL_005fIMPLICIT_005fCONTEXT">Background
and PERL_IMPLICIT_CONTEXT</a>.)
-</p>
-</dd>
-<dt>r</dt>
-<dd><a name="perlguts-r"></a>
-<p>This function never returns; <code>croak</code>, <code>exit</code> and
friends.
-</p>
-</dd>
-<dt>f</dt>
-<dd><a name="perlguts-f"></a>
-<p>This function takes a variable number of arguments, <code>printf</code>
style.
-The argument list should end with <code>...</code>, like this:
-</p>
-<pre class="verbatim"> Afprd |void |croak |const char* pat|...
-</pre>
-</dd>
-<dt>M</dt>
-<dd><a name="perlguts-M"></a>
-<p>This function is part of the experimental development API, and may change
-or disappear without notice.
-</p>
-</dd>
-<dt>o</dt>
-<dd><a name="perlguts-o"></a>
-<p>This function should not have a compatibility macro to define, say,
-<code>Perl_parse</code> to <code>parse</code>. It must be called as
<code>Perl_parse</code>.
-</p>
-</dd>
-<dt>x</dt>
-<dd><a name="perlguts-x"></a>
-<p>This function isn’t exported out of the Perl core.
-</p>
-</dd>
-<dt>m</dt>
-<dd><a name="perlguts-m"></a>
-<p>This is implemented as a macro.
-</p>
-</dd>
-<dt>X</dt>
-<dd><a name="perlguts-X"></a>
-<p>This function is explicitly exported.
-</p>
-</dd>
-<dt>E</dt>
-<dd><a name="perlguts-E"></a>
-<p>This function is visible to extensions included in the Perl core.
-</p>
-</dd>
-<dt>b</dt>
-<dd><a name="perlguts-b"></a>
-<p>Binary backward compatibility; this function is a macro but also has
-a <code>Perl_</code> implementation (which is exported).
-</p>
-</dd>
-<dt>others</dt>
-<dd><a name="perlguts-others"></a>
-<p>See the comments at the top of <code>embed.fnc</code> for others.
-</p>
-</dd>
-</dl>
-
-<p>If you edit <samp>embed.pl</samp> or <samp>embed.fnc</samp>, you will need
to run
-<code>make regen_headers</code> to force a rebuild of <samp>embed.h</samp> and
other
-auto-generated files.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlguts-Formatted-Printing-of-IVs_002c-UVs_002c-and-NVs"
accesskey="1">perlguts Formatted Printing of IVs, UVs, and
NVs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Pointer_002dTo_002dInteger-and-Integer_002dTo_002dPointer"
accesskey="2">perlguts Pointer-To-Integer and
Integer-To-Pointer</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Exception-Handling" accesskey="3">perlguts Exception
Handling</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Source-Documentation" accesskey="4">perlguts Source
Documentation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Backwards-compatibility" accesskey="5">perlguts Backwards
compatibility</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlguts-Formatted-Printing-of-IVs_002c-UVs_002c-and-NVs"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlguts-Pointer_002dTo_002dInteger-and-Integer_002dTo_002dPointer"
accesskey="n" rel="next">perlguts Pointer-To-Integer and
Integer-To-Pointer</a>, Up: <a href="#perlguts-Internal-Functions"
accesskey="u" rel="up">perlguts Internal Functions</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Formatted-Printing-of-IVs_002c-UVs_002c-and-NVs"></a>
-<h4 class="subsection">28.10.1 Formatted Printing of IVs, UVs, and NVs</h4>
-
-<p>If you are printing IVs, UVs, or NVS instead of the stdio(3) style
-formatting codes like <code>%d</code>, <code>%ld</code>, <code>%f</code>, you
should use the
-following macros for portability
-</p>
-<pre class="verbatim"> IVdf IV in decimal
- UVuf UV in decimal
- UVof UV in octal
- UVxf UV in hexadecimal
- NVef NV %e-like
- NVff NV %f-like
- NVgf NV %g-like
-</pre>
-<p>These will take care of 64-bit integers and long doubles.
-For example:
-</p>
-<pre class="verbatim"> printf("IV is %"IVdf"\n",
iv);
-</pre>
-<p>The IVdf will expand to whatever is the correct format for the IVs.
-</p>
-<p>Note that there are different "long doubles": Perl will use
-whatever the compiler has.
-</p>
-<p>If you are printing addresses of pointers, use UVxf combined
-with PTR2UV(), do not use %lx or %p.
-</p>
-<hr>
-<a
name="perlguts-Pointer_002dTo_002dInteger-and-Integer_002dTo_002dPointer"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Exception-Handling" accesskey="n" rel="next">perlguts
Exception Handling</a>, Previous: <a
href="#perlguts-Formatted-Printing-of-IVs_002c-UVs_002c-and-NVs" accesskey="p"
rel="prev">perlguts Formatted Printing of IVs, UVs, and NVs</a>, Up: <a
href="#perlguts-Internal-Functions" accesskey="u" rel="up">perlguts Internal
Functions</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Pointer_002dTo_002dInteger-and-Integer_002dTo_002dPointer"></a>
-<h4 class="subsection">28.10.2 Pointer-To-Integer and Integer-To-Pointer</h4>
-
-<p>Because pointer size does not necessarily equal integer size,
-use the follow macros to do it right.
-</p>
-<pre class="verbatim"> PTR2UV(pointer)
- PTR2IV(pointer)
- PTR2NV(pointer)
- INT2PTR(pointertotype, integer)
-</pre>
-<p>For example:
-</p>
-<pre class="verbatim"> IV iv = ...;
- SV *sv = INT2PTR(SV*, iv);
-</pre>
-<p>and
-</p>
-<pre class="verbatim"> AV *av = ...;
- UV uv = PTR2UV(av);
-</pre>
-<hr>
-<a name="perlguts-Exception-Handling"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Source-Documentation" accesskey="n"
rel="next">perlguts Source Documentation</a>, Previous: <a
href="#perlguts-Pointer_002dTo_002dInteger-and-Integer_002dTo_002dPointer"
accesskey="p" rel="prev">perlguts Pointer-To-Integer and
Integer-To-Pointer</a>, Up: <a href="#perlguts-Internal-Functions"
accesskey="u" rel="up">perlguts Internal Functions</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Exception-Handling"></a>
-<h4 class="subsection">28.10.3 Exception Handling</h4>
-
-<p>There are a couple of macros to do very basic exception handling in XS
-modules. You have to define <code>NO_XSLOCKS</code> before including
<samp>XSUB.h</samp> to
-be able to use these macros:
-</p>
-<pre class="verbatim"> #define NO_XSLOCKS
- #include "XSUB.h"
-</pre>
-<p>You can use these macros if you call code that may croak, but you need
-to do some cleanup before giving control back to Perl. For example:
-</p>
-<pre class="verbatim"> dXCPT; /* set up necessary variables */
-
- XCPT_TRY_START {
- code_that_may_croak();
- } XCPT_TRY_END
-
- XCPT_CATCH
- {
- /* do cleanup here */
- XCPT_RETHROW;
- }
-</pre>
-<p>Note that you always have to rethrow an exception that has been
-caught. Using these macros, it is not possible to just catch the
-exception and ignore it. If you have to ignore the exception, you
-have to use the <code>call_*</code> function.
-</p>
-<p>The advantage of using the above macros is that you don’t have
-to setup an extra function for <code>call_*</code>, and that using these
-macros is faster than using <code>call_*</code>.
-</p>
-<hr>
-<a name="perlguts-Source-Documentation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Backwards-compatibility" accesskey="n"
rel="next">perlguts Backwards compatibility</a>, Previous: <a
href="#perlguts-Exception-Handling" accesskey="p" rel="prev">perlguts Exception
Handling</a>, Up: <a href="#perlguts-Internal-Functions" accesskey="u"
rel="up">perlguts Internal Functions</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Source-Documentation"></a>
-<h4 class="subsection">28.10.4 Source Documentation</h4>
-
-<p>There’s an effort going on to document the internal functions and
-automatically produce reference manuals from them – <a
href="perlapi.html#Top">(perlapi)</a> is one
-such manual which details all the functions which are available to XS
-writers. <a href="perlintern.html#Top">(perlintern)</a> is the autogenerated
manual for the functions
-which are not part of the API and are supposedly for internal use only.
-</p>
-<p>Source documentation is created by putting POD comments into the C
-source, like this:
-</p>
-<pre class="verbatim"> /*
- =for apidoc sv_setiv
-
- Copies an integer into the given SV. Does not handle 'set' magic. See
- C<sv_setiv_mg>.
-
- =cut
- */
-</pre>
-<p>Please try and supply some documentation if you add functions to the
-Perl core.
-</p>
-<hr>
-<a name="perlguts-Backwards-compatibility"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlguts-Source-Documentation" accesskey="p"
rel="prev">perlguts Source Documentation</a>, Up: <a
href="#perlguts-Internal-Functions" accesskey="u" rel="up">perlguts Internal
Functions</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Backwards-compatibility"></a>
-<h4 class="subsection">28.10.5 Backwards compatibility</h4>
-
-<p>The Perl API changes over time. New functions are
-added or the interfaces of existing functions are
-changed. The <code>Devel::PPPort</code> module tries to
-provide compatibility code for some of these changes, so XS writers don’t
-have to code it themselves when supporting multiple versions of Perl.
-</p>
-<p><code>Devel::PPPort</code> generates a C header file <samp>ppport.h</samp>
that can also
-be run as a Perl script. To generate <samp>ppport.h</samp>, run:
-</p>
-<pre class="verbatim"> perl -MDevel::PPPort -eDevel::PPPort::WriteFile
-</pre>
-<p>Besides checking existing XS code, the script can also be used to retrieve
-compatibility information for various API calls using the
<code>--api-info</code>
-command line switch. For example:
-</p>
-<pre class="verbatim"> % perl ppport.h --api-info=sv_magicext
-</pre>
-<p>For details, see <code>perldoc ppport.h</code>.
-</p>
-<hr>
-<a name="perlguts-Unicode-Support"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Custom-Operators" accesskey="n" rel="next">perlguts
Custom Operators</a>, Previous: <a href="#perlguts-Internal-Functions"
accesskey="p" rel="prev">perlguts Internal Functions</a>, Up: <a
href="#perlguts" accesskey="u" rel="up">perlguts</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-Support"></a>
-<h3 class="section">28.11 Unicode Support</h3>
-
-<p>Perl 5.6.0 introduced Unicode support. It’s important for porters
and XS
-writers to understand this support and make sure that the code they
-write does not corrupt Unicode data.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlguts-What-is-Unicode_002c-anyway_003f" accesskey="1">perlguts What
<strong>is</strong> Unicode, anyway?</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-How-can-I-recognise-a-UTF_002d8-string_003f"
accesskey="2">perlguts How can I recognise a UTF-8
string?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-How-does-UTF_002d8-represent-Unicode-characters_003f"
accesskey="3">perlguts How does UTF-8 represent Unicode
characters?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-How-does-Perl-store-UTF_002d8-strings_003f"
accesskey="4">perlguts How does Perl store UTF-8
strings?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-How-do-I-convert-a-string-to-UTF_002d8_003f"
accesskey="5">perlguts How do I convert a string to
UTF-8?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-How-do-I-compare-strings_003f" accesskey="6">perlguts How do I
compare strings?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlguts-Is-there-anything-else-I-need-to-know_003f"
accesskey="7">perlguts Is there anything else I need to
know?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlguts-What-is-Unicode_002c-anyway_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-How-can-I-recognise-a-UTF_002d8-string_003f"
accesskey="n" rel="next">perlguts How can I recognise a UTF-8 string?</a>, Up:
<a href="#perlguts-Unicode-Support" accesskey="u" rel="up">perlguts Unicode
Support</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="What-is-Unicode_002c-anyway_003f"></a>
-<h4 class="subsection">28.11.1 What <strong>is</strong> Unicode, anyway?</h4>
-
-<p>In the olden, less enlightened times, we all used to use ASCII. Most of
-us did, anyway. The big problem with ASCII is that it’s American. Well,
-no, that’s not actually the problem; the problem is that it’s not
-particularly useful for people who don’t use the Roman alphabet. What
-used to happen was that particular languages would stick their own
-alphabet in the upper range of the sequence, between 128 and 255. Of
-course, we then ended up with plenty of variants that weren’t quite
-ASCII, and the whole point of it being a standard was lost.
-</p>
-<p>Worse still, if you’ve got a language like Chinese or
-Japanese that has hundreds or thousands of characters, then you really
-can’t fit them into a mere 256, so they had to forget about ASCII
-altogether, and build their own systems using pairs of numbers to refer
-to one character.
-</p>
-<p>To fix this, some people formed Unicode, Inc. and
-produced a new character set containing all the characters you can
-possibly think of and more. There are several ways of representing these
-characters, and the one Perl uses is called UTF-8. UTF-8 uses
-a variable number of bytes to represent a character. You can learn more
-about Unicode and Perl’s Unicode model in <a
href="#perlunicode-NAME">perlunicode NAME</a>.
-</p>
-<p>(On EBCDIC platforms, Perl uses instead UTF-EBCDIC, which is a form of
-UTF-8 adapted for EBCDIC platforms. Below, we just talk about UTF-8.
-UTF-EBCDIC is like UTF-8, but the details are different. The macros
-hide the differences from you, just remember that the particular numbers
-and bit patterns presented below will differ in UTF-EBCDIC.)
-</p>
-<hr>
-<a name="perlguts-How-can-I-recognise-a-UTF_002d8-string_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-How-does-UTF_002d8-represent-Unicode-characters_003f"
accesskey="n" rel="next">perlguts How does UTF-8 represent Unicode
characters?</a>, Previous: <a href="#perlguts-What-is-Unicode_002c-anyway_003f"
accesskey="p" rel="prev">perlguts What <strong>is</strong> Unicode,
anyway?</a>, Up: <a href="#perlguts-Unicode-Support" accesskey="u"
rel="up">perlguts Unicode Support</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="How-can-I-recognise-a-UTF_002d8-string_003f"></a>
-<h4 class="subsection">28.11.2 How can I recognise a UTF-8 string?</h4>
-
-<p>You can’t. This is because UTF-8 data is stored in bytes just like
-non-UTF-8 data. The Unicode character 200, (<code>0xC8</code> for you hex
types)
-capital E with a grave accent, is represented by the two bytes
-<code>v196.172</code>. Unfortunately, the non-Unicode string
<code>chr(196).chr(172)</code>
-has that byte sequence as well. So you can’t tell just by looking
– this
-is what makes Unicode input an interesting problem.
-</p>
-<p>In general, you either have to know what you’re dealing with, or you
-have to guess. The API function <code>is_utf8_string</code> can help;
it’ll tell
-you if a string contains only valid UTF-8 characters, and the chances
-of a non-UTF-8 string looking like valid UTF-8 become very small very
-quickly with increasing string length. On a character-by-character
-basis, <code>isUTF8_CHAR</code>
-will tell you whether the current character in a string is valid UTF-8.
-</p>
-<hr>
-<a name="perlguts-How-does-UTF_002d8-represent-Unicode-characters_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-How-does-Perl-store-UTF_002d8-strings_003f"
accesskey="n" rel="next">perlguts How does Perl store UTF-8 strings?</a>,
Previous: <a href="#perlguts-How-can-I-recognise-a-UTF_002d8-string_003f"
accesskey="p" rel="prev">perlguts How can I recognise a UTF-8 string?</a>, Up:
<a href="#perlguts-Unicode-Support" accesskey="u" rel="up">perlguts Unicode
Support</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="How-does-UTF_002d8-represent-Unicode-characters_003f"></a>
-<h4 class="subsection">28.11.3 How does UTF-8 represent Unicode
characters?</h4>
-
-<p>As mentioned above, UTF-8 uses a variable number of bytes to store a
-character. Characters with values 0...127 are stored in one
-byte, just like good ol’ ASCII. Character 128 is stored as
-<code>v194.128</code>; this continues up to character 191, which is
-<code>v194.191</code>. Now we’ve run out of bits (191 is binary
-<code>10111111</code>) so we move on; character 192 is <code>v195.128</code>.
And
-so it goes on, moving to three bytes at character 2048.
-<a href="#perlunicode-Unicode-Encodings">perlunicode Unicode Encodings</a> has
pictures of how this works.
-</p>
-<p>Assuming you know you’re dealing with a UTF-8 string, you can find out
-how long the first character in it is with the <code>UTF8SKIP</code> macro:
-</p>
-<pre class="verbatim"> char *utf = "\305\233\340\240\201";
- I32 len;
-
- len = UTF8SKIP(utf); /* len is 2 here */
- utf += len;
- len = UTF8SKIP(utf); /* len is 3 here */
-</pre>
-<p>Another way to skip over characters in a UTF-8 string is to use
-<code>utf8_hop</code>, which takes a string and a number of characters to skip
-over. You’re on your own about bounds checking, though, so don’t
use it
-lightly.
-</p>
-<p>All bytes in a multi-byte UTF-8 character will have the high bit set,
-so you can test if you need to do something special with this
-character like this (the <code>UTF8_IS_INVARIANT()</code> is a macro that tests
-whether the byte is encoded as a single byte even in UTF-8):
-</p>
-<pre class="verbatim"> U8 *utf;
- U8 *utf_end; /* 1 beyond buffer pointed to by utf */
- UV uv; /* Note: a UV, not a U8, not a char */
- STRLEN len; /* length of character in bytes */
-
- if (!UTF8_IS_INVARIANT(*utf))
- /* Must treat this as UTF-8 */
- uv = utf8_to_uvchr_buf(utf, utf_end, &len);
- else
- /* OK to treat this character as a byte */
- uv = *utf;
-</pre>
-<p>You can also see in that example that we use <code>utf8_to_uvchr_buf</code>
to get the
-value of the character; the inverse function <code>uvchr_to_utf8</code> is
available
-for putting a UV into UTF-8:
-</p>
-<pre class="verbatim"> if (!UVCHR_IS_INVARIANT(uv))
- /* Must treat this as UTF8 */
- utf8 = uvchr_to_utf8(utf8, uv);
- else
- /* OK to treat this character as a byte */
- *utf8++ = uv;
-</pre>
-<p>You <strong>must</strong> convert characters to UVs using the above
functions if
-you’re ever in a situation where you have to match UTF-8 and non-UTF-8
-characters. You may not skip over UTF-8 characters in this case. If you
-do this, you’ll lose the ability to match hi-bit non-UTF-8 characters;
-for instance, if your UTF-8 string contains <code>v196.172</code>, and you skip
-that character, you can never match a <code>chr(200)</code> in a non-UTF-8
string.
-So don’t do that!
-</p>
-<p>(Note that we don’t have to test for invariant characters in the
-examples above. The functions work on any well-formed UTF-8 input.
-It’s just that its faster to avoid the function overhead when it’s
not
-needed.)
-</p>
-<hr>
-<a name="perlguts-How-does-Perl-store-UTF_002d8-strings_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-How-do-I-convert-a-string-to-UTF_002d8_003f"
accesskey="n" rel="next">perlguts How do I convert a string to UTF-8?</a>,
Previous: <a
href="#perlguts-How-does-UTF_002d8-represent-Unicode-characters_003f"
accesskey="p" rel="prev">perlguts How does UTF-8 represent Unicode
characters?</a>, Up: <a href="#perlguts-Unicode-Support" accesskey="u"
rel="up">perlguts Unicode Support</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="How-does-Perl-store-UTF_002d8-strings_003f"></a>
-<h4 class="subsection">28.11.4 How does Perl store UTF-8 strings?</h4>
-
-<p>Currently, Perl deals with UTF-8 strings and non-UTF-8 strings
-slightly differently. A flag in the SV, <code>SVf_UTF8</code>, indicates that
the
-string is internally encoded as UTF-8. Without it, the byte value is the
-codepoint number and vice versa. This flag is only meaningful if the SV
-is <code>SvPOK</code> or immediately after stringification via
<code>SvPV</code> or a
-similar macro. You can check and manipulate this flag with the
-following macros:
-</p>
-<pre class="verbatim"> SvUTF8(sv)
- SvUTF8_on(sv)
- SvUTF8_off(sv)
-</pre>
-<p>This flag has an important effect on Perl’s treatment of the string:
if
-UTF-8 data is not properly distinguished, regular expressions,
-<code>length</code>, <code>substr</code> and other string handling operations
will have
-undesirable (wrong) results.
-</p>
-<p>The problem comes when you have, for instance, a string that isn’t
-flagged as UTF-8, and contains a byte sequence that could be UTF-8 –
-especially when combining non-UTF-8 and UTF-8 strings.
-</p>
-<p>Never forget that the <code>SVf_UTF8</code> flag is separate from the PV
value; you
-need to be sure you don’t accidentally knock it off while you’re
-manipulating SVs. More specifically, you cannot expect to do this:
-</p>
-<pre class="verbatim"> SV *sv;
- SV *nsv;
- STRLEN len;
- char *p;
-
- p = SvPV(sv, len);
- frobnicate(p);
- nsv = newSVpvn(p, len);
-</pre>
-<p>The <code>char*</code> string does not tell you the whole story, and you
can’t
-copy or reconstruct an SV just by copying the string value. Check if the
-old SV has the UTF8 flag set (<em>after</em> the <code>SvPV</code> call), and
act
-accordingly:
-</p>
-<pre class="verbatim"> p = SvPV(sv, len);
- is_utf8 = SvUTF8(sv);
- frobnicate(p, is_utf8);
- nsv = newSVpvn(p, len);
- if (is_utf8)
- SvUTF8_on(nsv);
-</pre>
-<p>In the above, your <code>frobnicate</code> function has been changed to be
made
-aware of whether or not it’s dealing with UTF-8 data, so that it can
-handle the string appropriately.
-</p>
-<p>Since just passing an SV to an XS function and copying the data of
-the SV is not enough to copy the UTF8 flags, even less right is just
-passing a <code>char *</code><!-- /@w --> to an XS function.
-</p>
-<p>For full generality, use the <a
href="perlapi.html#DO_005fUTF8">(perlapi)DO_UTF8</a> macro to see if the
-string in an SV is to be <em>treated</em> as UTF-8. This takes into account
-if the call to the XS function is being made from within the scope of
-<a href="bytes.html#Top">(bytes)<code>use bytes</code><!-- /@w --></a>.
If so, the underlying bytes that comprise the
-UTF-8 string are to be exposed, rather than the character they
-represent. But this pragma should only really be used for debugging and
-perhaps low-level testing at the byte level. Hence most XS code need
-not concern itself with this, but various areas of the perl core do need
-to support it.
-</p>
-<p>And this isn’t the whole story. Starting in Perl v5.12, strings that
-aren’t encoded in UTF-8 may also be treated as Unicode under various
-conditions (see <a
href="#perlunicode-ASCII-Rules-versus-Unicode-Rules">perlunicode ASCII Rules
versus Unicode Rules</a>).
-This is only really a problem for characters whose ordinals are between
-128 and 255, and their behavior varies under ASCII versus Unicode rules
-in ways that your code cares about (see <a
href="#perlunicode-The-_0022Unicode-Bug_0022">perlunicode The "Unicode
Bug"</a>).
-There is no published API for dealing with this, as it is subject to
-change, but you can look at the code for <code>pp_lc</code> in
<samp>pp.c</samp> for an
-example as to how it’s currently done.
-</p>
-<hr>
-<a name="perlguts-How-do-I-convert-a-string-to-UTF_002d8_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-How-do-I-compare-strings_003f" accesskey="n"
rel="next">perlguts How do I compare strings?</a>, Previous: <a
href="#perlguts-How-does-Perl-store-UTF_002d8-strings_003f" accesskey="p"
rel="prev">perlguts How does Perl store UTF-8 strings?</a>, Up: <a
href="#perlguts-Unicode-Support" accesskey="u" rel="up">perlguts Unicode
Support</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="How-do-I-convert-a-string-to-UTF_002d8_003f"></a>
-<h4 class="subsection">28.11.5 How do I convert a string to UTF-8?</h4>
-
-<p>If you’re mixing UTF-8 and non-UTF-8 strings, it is necessary to
upgrade
-the non-UTF-8 strings to UTF-8. If you’ve got an SV, the easiest way to
do
-this is:
-</p>
-<pre class="verbatim"> sv_utf8_upgrade(sv);
-</pre>
-<p>However, you must not do this, for example:
-</p>
-<pre class="verbatim"> if (!SvUTF8(left))
- sv_utf8_upgrade(left);
-</pre>
-<p>If you do this in a binary operator, you will actually change one of the
-strings that came into the operator, and, while it shouldn’t be
noticeable
-by the end user, it can cause problems in deficient code.
-</p>
-<p>Instead, <code>bytes_to_utf8</code> will give you a UTF-8-encoded
<strong>copy</strong> of its
-string argument. This is useful for having the data available for
-comparisons and so on, without harming the original SV. There’s also
-<code>utf8_to_bytes</code> to go the other way, but naturally, this will fail
if
-the string contains any characters above 255 that can’t be represented
-in a single byte.
-</p>
-<hr>
-<a name="perlguts-How-do-I-compare-strings_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-Is-there-anything-else-I-need-to-know_003f"
accesskey="n" rel="next">perlguts Is there anything else I need to know?</a>,
Previous: <a href="#perlguts-How-do-I-convert-a-string-to-UTF_002d8_003f"
accesskey="p" rel="prev">perlguts How do I convert a string to UTF-8?</a>, Up:
<a href="#perlguts-Unicode-Support" accesskey="u" rel="up">perlguts Unicode
Support</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="How-do-I-compare-strings_003f"></a>
-<h4 class="subsection">28.11.6 How do I compare strings?</h4>
-
-<p><a href="perlapi.html#sv_005fcmp">(perlapi)sv_cmp</a> and <a
href="perlapi.html#sv_005fcmp_005fflags">(perlapi)sv_cmp_flags</a> do a
lexigraphic
-comparison of two SV’s, and handle UTF-8ness properly. Note, however,
-that Unicode specifies a much fancier mechanism for collation, available
-via the <a href="Unicode-Collate.html#Top">(Unicode-Collate)</a> module.
-</p>
-<p>To just compare two strings for equality/non-equality, you can just use
-<a href="perlapi.html#memEQ">(perlapi)<code>memEQ()</code></a> and <a
href="perlapi.html#memEQ">(perlapi)<code>memNE()</code></a> as usual,
-except the strings must be both UTF-8 or not UTF-8 encoded.
-</p>
-<p>To compare two strings case-insensitively, use
-<a href="perlapi.html#foldEQ_005futf8">(perlapi)<code>foldEQ_utf8()</code></a>
(the strings don’t have to have
-the same UTF-8ness).
-</p>
-<hr>
-<a name="perlguts-Is-there-anything-else-I-need-to-know_003f"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlguts-How-do-I-compare-strings_003f" accesskey="p"
rel="prev">perlguts How do I compare strings?</a>, Up: <a
href="#perlguts-Unicode-Support" accesskey="u" rel="up">perlguts Unicode
Support</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Is-there-anything-else-I-need-to-know_003f"></a>
-<h4 class="subsection">28.11.7 Is there anything else I need to know?</h4>
-
-<p>Not really. Just remember these things:
-</p>
-<ul>
-<li> There’s no way to tell if a <code>char *</code><!-- /@w --> or
<code>U8 *</code><!-- /@w --> string is UTF-8
-or not. But you can tell if an SV is to be treated as UTF-8 by calling
-<code>DO_UTF8</code> on it, after stringifying it with <code>SvPV</code> or a
similar
-macro. And, you can tell if SV is actually UTF-8 (even if it is not to
-be treated as such) by looking at its <code>SvUTF8</code> flag (again after
-stringifying it). Don’t forget to set the flag if something should be
-UTF-8.
-Treat the flag as part of the PV, even though it’s not – if you
pass on
-the PV to somewhere, pass on the flag too.
-
-</li><li> If a string is UTF-8, <strong>always</strong> use
<code>utf8_to_uvchr_buf</code> to get at the value,
-unless <code>UTF8_IS_INVARIANT(*s)</code> in which case you can use
<code>*s</code>.
-
-</li><li> When writing a character UV to a UTF-8 string,
<strong>always</strong> use
-<code>uvchr_to_utf8</code>, unless <code>UVCHR_IS_INVARIANT(uv))</code> in
which case
-you can use <code>*s = uv</code>.
-
-</li><li> Mixing UTF-8 and non-UTF-8 strings is
-tricky. Use <code>bytes_to_utf8</code> to get
-a new string which is UTF-8 encoded, and then combine them.
-
-</li></ul>
-
-<hr>
-<a name="perlguts-Custom-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-AUTHORS" accesskey="n" rel="next">perlguts
AUTHORS</a>, Previous: <a href="#perlguts-Unicode-Support" accesskey="p"
rel="prev">perlguts Unicode Support</a>, Up: <a href="#perlguts" accesskey="u"
rel="up">perlguts</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Custom-Operators"></a>
-<h3 class="section">28.12 Custom Operators</h3>
-
-<p>Custom operator support is an experimental feature that allows you to
-define your own ops. This is primarily to allow the building of
-interpreters for other languages in the Perl core, but it also allows
-optimizations through the creation of "macro-ops" (ops which perform
the
-functions of multiple ops which are usually executed together, such as
-<code>gvsv, gvsv, add</code>.)
-</p>
-<p>This feature is implemented as a new op type, <code>OP_CUSTOM</code>. The
Perl
-core does not "know" anything special about this op type, and so it
will
-not be involved in any optimizations. This also means that you can
-define your custom ops to be any op structure – unary, binary, list and
-so on – you like.
-</p>
-<p>It’s important to know what custom operators won’t do for you.
They
-won’t let you add new syntax to Perl, directly. They won’t even
let you
-add new keywords, directly. In fact, they won’t change the way Perl
-compiles a program at all. You have to do those changes yourself, after
-Perl has compiled the program. You do this either by manipulating the op
-tree using a <code>CHECK</code> block and the <code>B::Generate</code> module,
or by adding
-a custom peephole optimizer with the <code>optimize</code> module.
-</p>
-<p>When you do this, you replace ordinary Perl ops with custom ops by
-creating ops with the type <code>OP_CUSTOM</code> and the
<code>op_ppaddr</code> of your own
-PP function. This should be defined in XS code, and should look like
-the PP ops in <code>pp_*.c</code>. You are responsible for ensuring that your
op
-takes the appropriate number of values from the stack, and you are
-responsible for adding stack marks if necessary.
-</p>
-<p>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
<code>OP_CUSTOM</code>,
-Perl uses the value of <code>o->op_ppaddr</code> to determine which custom
op
-it is dealing with. You should create an <code>XOP</code> structure for each
-ppaddr you use, set the properties of the custom op with
-<code>XopENTRY_set</code>, and register the structure against the ppaddr using
-<code>Perl_custom_op_register</code>. A trivial example might look like:
-</p>
-<pre class="verbatim"> 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);
-</pre>
-<p>The available fields in the structure are:
-</p>
-<dl compact="compact">
-<dt>xop_name</dt>
-<dd><a name="perlguts-xop_005fname"></a>
-<p>A short name for your op. This will be included in some error messages,
-and will also be returned as <code>$op->name</code> by the <a
href="B.html#Top">(B)B</a> module, so
-it will appear in the output of module like <a
href="B-Concise.html#Top">(B-Concise)B::Concise</a>.
-</p>
-</dd>
-<dt>xop_desc</dt>
-<dd><a name="perlguts-xop_005fdesc"></a>
-<p>A short description of the function of the op.
-</p>
-</dd>
-<dt>xop_class</dt>
-<dd><a name="perlguts-xop_005fclass"></a>
-<p>Which of the various <code>*OP</code> structures this op uses. This should
be one of
-the <code>OA_*</code> constants from <samp>op.h</samp>, namely
-</p>
-<dl compact="compact">
-<dt>OA_BASEOP</dt>
-<dd><a name="perlguts-OA_005fBASEOP"></a>
-</dd>
-<dt>OA_UNOP</dt>
-<dd><a name="perlguts-OA_005fUNOP"></a>
-</dd>
-<dt>OA_BINOP</dt>
-<dd><a name="perlguts-OA_005fBINOP"></a>
-</dd>
-<dt>OA_LOGOP</dt>
-<dd><a name="perlguts-OA_005fLOGOP"></a>
-</dd>
-<dt>OA_LISTOP</dt>
-<dd><a name="perlguts-OA_005fLISTOP"></a>
-</dd>
-<dt>OA_PMOP</dt>
-<dd><a name="perlguts-OA_005fPMOP"></a>
-</dd>
-<dt>OA_SVOP</dt>
-<dd><a name="perlguts-OA_005fSVOP"></a>
-</dd>
-<dt>OA_PADOP</dt>
-<dd><a name="perlguts-OA_005fPADOP"></a>
-</dd>
-<dt>OA_PVOP_OR_SVOP</dt>
-<dd><a name="perlguts-OA_005fPVOP_005fOR_005fSVOP"></a>
-<p>This should be interpreted as ’<code>PVOP</code>’ only. The
<code>_OR_SVOP</code> is because
-the only core <code>PVOP</code>, <code>OP_TRANS</code>, can sometimes be a
<code>SVOP</code> instead.
-</p>
-</dd>
-<dt>OA_LOOP</dt>
-<dd><a name="perlguts-OA_005fLOOP"></a>
-</dd>
-<dt>OA_COP</dt>
-<dd><a name="perlguts-OA_005fCOP"></a>
-</dd>
-</dl>
-
-<p>The other <code>OA_*</code> constants should not be used.
-</p>
-</dd>
-<dt>xop_peep</dt>
-<dd><a name="perlguts-xop_005fpeep"></a>
-<p>This member is of type <code>Perl_cpeep_t</code>, which expands to
<code>void
-(*Perl_cpeep_t)(aTHX_ OP *o, OP *oldop)</code>. If it is set, this function
-will be called from <code>Perl_rpeep</code> when ops of this type are
encountered
-by the peephole optimizer. <em>o</em> is the OP that needs optimizing;
-<em>oldop</em> is the previous OP optimized, whose <code>op_next</code> points
to <em>o</em>.
-</p>
-</dd>
-</dl>
-
-<p><code>B::Generate</code> directly supports the creation of custom ops by
name.
-</p>
-<hr>
-<a name="perlguts-AUTHORS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlguts-SEE-ALSO" accesskey="n" rel="next">perlguts SEE
ALSO</a>, Previous: <a href="#perlguts-Custom-Operators" accesskey="p"
rel="prev">perlguts Custom Operators</a>, Up: <a href="#perlguts" accesskey="u"
rel="up">perlguts</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHORS-2"></a>
-<h3 class="section">28.13 AUTHORS</h3>
-
-<p>Until May 1997, this document was maintained by Jeff Okamoto
-<address@hidden>. It is now maintained as part of Perl
-itself by the Perl 5 Porters <address@hidden>.
-</p>
-<p>With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
-Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
-Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
-Stephen McCamant, and Gurusamy Sarathy.
-</p>
-<hr>
-<a name="perlguts-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlguts-AUTHORS" accesskey="p" rel="prev">perlguts
AUTHORS</a>, Up: <a href="#perlguts" accesskey="u" rel="up">perlguts</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-15"></a>
-<h3 class="section">28.14 SEE ALSO</h3>
-
-<p><a href="perlapi.html#Top">(perlapi)</a>, <a
href="perlintern.html#Top">(perlintern)</a>, <a
href="perlxs.html#Top">(perlxs)</a>, <a href="#perlembed-NAME">perlembed
NAME</a>
-</p>
-<hr>
-<a name="perlhack"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips" accesskey="n" rel="next">perlhacktips</a>,
Previous: <a href="#perlguts" accesskey="p" rel="prev">perlguts</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlhack-1"></a>
-<h2 class="chapter">29 perlhack</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlhack-NAME"
accesskey="1">perlhack NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhack-DESCRIPTION"
accesskey="2">perlhack DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-SUPER-QUICK-PATCH-GUIDE" accesskey="3">perlhack SUPER QUICK
PATCH GUIDE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhack-BUG-REPORTING"
accesskey="4">perlhack BUG REPORTING</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhack-PERL-5-PORTERS"
accesskey="5">perlhack PERL 5 PORTERS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-GETTING-THE-PERL-SOURCE" accesskey="6">perlhack GETTING THE
PERL SOURCE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhack-PATCHING-PERL"
accesskey="7">perlhack PATCHING PERL</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhack-TESTING"
accesskey="8">perlhack TESTING</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-MORE-READING-FOR-GUTS-HACKERS" accesskey="9">perlhack MORE
READING FOR GUTS HACKERS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-CPAN-TESTERS-AND-PERL-SMOKERS">perlhack CPAN TESTERS AND PERL
SMOKERS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-WHAT-NEXT_003f">perlhack WHAT
NEXT?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhack-AUTHOR">perlhack
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhack-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-DESCRIPTION" accesskey="n" rel="next">perlhack
DESCRIPTION</a>, Up: <a href="#perlhack" accesskey="u" rel="up">perlhack</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-28"></a>
-<h3 class="section">29.1 NAME</h3>
-
-<p>perlhack - How to hack on Perl
-</p>
-<hr>
-<a name="perlhack-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-SUPER-QUICK-PATCH-GUIDE" accesskey="n"
rel="next">perlhack SUPER QUICK PATCH GUIDE</a>, Previous: <a
href="#perlhack-NAME" accesskey="p" rel="prev">perlhack NAME</a>, Up: <a
href="#perlhack" accesskey="u" rel="up">perlhack</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-28"></a>
-<h3 class="section">29.2 DESCRIPTION</h3>
-
-<p>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.
-</p>
-<hr>
-<a name="perlhack-SUPER-QUICK-PATCH-GUIDE"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-BUG-REPORTING" accesskey="n" rel="next">perlhack BUG
REPORTING</a>, Previous: <a href="#perlhack-DESCRIPTION" accesskey="p"
rel="prev">perlhack DESCRIPTION</a>, Up: <a href="#perlhack" accesskey="u"
rel="up">perlhack</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SUPER-QUICK-PATCH-GUIDE"></a>
-<h3 class="section">29.3 SUPER QUICK PATCH GUIDE</h3>
-
-<p>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:
-</p>
-<ul>
-<li> Check out the source repository
-
-<p>The perl source is in a git repository. You can clone the repository
-with the following command:
-</p>
-<pre class="verbatim"> % git clone git://perl5.git.perl.org/perl.git perl
-</pre>
-</li><li> Ensure you’re following the latest advice
-
-<p>In case the advice in this guide has been updated recently, read the
-latest version directly from the perl source:
-</p>
-<pre class="verbatim"> % perldoc pod/perlhack.pod
-</pre>
-</li><li> Make your change
-
-<p>Hack, hack, hack. Keep in mind that Perl runs on many different
-platforms, with different operating systems that have different
-capabilities, different filesystem organizations, and even different
-character sets. <a href="#perlhacktips-NAME">perlhacktips NAME</a> gives
advice on this.
-</p>
-</li><li> Test your change
-
-<p>You can run all the tests with the following commands:
-</p>
-<pre class="verbatim"> % ./Configure -des -Dusedevel
- % make test
-</pre>
-<p>Keep hacking until the tests pass.
-</p>
-</li><li> Commit your change
-
-<p>Committing your work will save the change <em>on your local system</em>:
-</p>
-<pre class="verbatim"> % git commit -a -m 'Commit message goes here'
-</pre>
-<p>Make sure the commit message describes your change in a single
-sentence. For example, "Fixed spelling errors in perlhack.pod".
-</p>
-</li><li> Send your change to perlbug
-
-<p>The next step is to submit your patch to the Perl core ticket system
-via email.
-</p>
-<p>If your changes are in a single git commit, run the following commands
-to generate the patch file and attach it to your bug report:
-</p>
-<pre class="verbatim"> % git format-patch -1
- % ./perl -Ilib utils/perlbug -p 0001-*.patch
-</pre>
-<p>The perlbug program will ask you a few questions about your email
-address and the patch you’re submitting. Once you’ve answered
them it
-will submit your patch via email.
-</p>
-<p>If your changes are in multiple commits, generate a patch file for each
-one and provide them to perlbug’s <code>-p</code> option separated by
commas:
-</p>
-<pre class="verbatim"> % git format-patch -3
- % ./perl -Ilib utils/perlbug -p 0001-fix1.patch,0002-fix2.patch,\
- > 0003-fix3.patch
-</pre>
-<p>When prompted, pick a subject that summarizes your changes.
-</p>
-</li><li> Thank you
-
-<p>The porters appreciate the time you spent helping to make Perl better.
-Thank you!
-</p>
-</li><li> Next time
-
-<p>The next time you wish to make a patch, you need to start from the
-latest perl in a pristine state. Check you don’t have any local changes
-or added files in your perl check-out which you wish to keep, then run
-these commands:
-</p>
-<pre class="verbatim"> % git pull
- % git reset --hard origin/blead
- % git clean -dxf
-</pre>
-</li></ul>
-
-<hr>
-<a name="perlhack-BUG-REPORTING"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-PERL-5-PORTERS" accesskey="n" rel="next">perlhack
PERL 5 PORTERS</a>, Previous: <a href="#perlhack-SUPER-QUICK-PATCH-GUIDE"
accesskey="p" rel="prev">perlhack SUPER QUICK PATCH GUIDE</a>, Up: <a
href="#perlhack" accesskey="u" rel="up">perlhack</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="BUG-REPORTING"></a>
-<h3 class="section">29.4 BUG REPORTING</h3>
-
-<p>If you want to report a bug in Perl, you must use the <samp>perlbug</samp>
-command line tool. This tool will ensure that your bug report includes
-all the relevant system and configuration information.
-</p>
-<p>To browse existing Perl bugs and patches, you can use the web interface
-at <a href="http://rt.perl.org/";>http://rt.perl.org/</a>.
-</p>
-<p>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.
-</p>
-<p>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.
-</p>
-<hr>
-<a name="perlhack-PERL-5-PORTERS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-GETTING-THE-PERL-SOURCE" accesskey="n"
rel="next">perlhack GETTING THE PERL SOURCE</a>, Previous: <a
href="#perlhack-BUG-REPORTING" accesskey="p" rel="prev">perlhack BUG
REPORTING</a>, Up: <a href="#perlhack" accesskey="u" rel="up">perlhack</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="PERL-5-PORTERS"></a>
-<h3 class="section">29.5 PERL 5 PORTERS</h3>
-
-<p>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", "p5p" or
just the
-"porters".
-</p>
-<p>A searchable archive of the list is available at
-<a
href="http://markmail.org/search/?q=perl5-porters";>http://markmail.org/search/?q=perl5-porters</a>.
There is also an archive at
-<a
href="http://archive.develooper.com/address@hidden/";>http://archive.develooper.com/address@hidden/</a>.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhack-perl_002dchanges-mailing-list" accesskey="1">perlhack
perl-changes mailing list</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhack-_0023p5p-on-IRC"
accesskey="2">perlhack #p5p on IRC</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhack-perl_002dchanges-mailing-list"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-_0023p5p-on-IRC" accesskey="n" rel="next">perlhack
#p5p on IRC</a>, Up: <a href="#perlhack-PERL-5-PORTERS" accesskey="u"
rel="up">perlhack PERL 5 PORTERS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perl_002dchanges-mailing-list"></a>
-<h4 class="subsection">29.5.1 perl-changes mailing list</h4>
-
-<p>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 <a
href="http://lists.perl.org/list/perl5-changes.html";>http://lists.perl.org/list/perl5-changes.html</a>
for
-subscription and archive information.
-</p>
-<hr>
-<a name="perlhack-_0023p5p-on-IRC"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhack-perl_002dchanges-mailing-list" accesskey="p"
rel="prev">perlhack perl-changes mailing list</a>, Up: <a
href="#perlhack-PERL-5-PORTERS" accesskey="u" rel="up">perlhack PERL 5
PORTERS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="g_t_0023p5p-on-IRC"></a>
-<h4 class="subsection">29.5.2 #p5p on IRC</h4>
-
-<p>Many porters are also active on the <a
href="irc://irc.perl.org/#p5p">irc://irc.perl.org/#p5p</a> channel.
-Feel free to join the channel and ask questions about hacking on the
-Perl core.
-</p>
-<hr>
-<a name="perlhack-GETTING-THE-PERL-SOURCE"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-PATCHING-PERL" accesskey="n" rel="next">perlhack
PATCHING PERL</a>, Previous: <a href="#perlhack-PERL-5-PORTERS" accesskey="p"
rel="prev">perlhack PERL 5 PORTERS</a>, Up: <a href="#perlhack" accesskey="u"
rel="up">perlhack</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="GETTING-THE-PERL-SOURCE"></a>
-<h3 class="section">29.6 GETTING THE PERL SOURCE</h3>
-
-<p>All of Perl’s source code is kept centrally in a Git repository at
-<em>perl5.git.perl.org</em>. The repository contains many Perl revisions
-from Perl 1 onwards and all the revisions from Perforce, the previous
-version control system.
-</p>
-<p>For much more detail on using git with the Perl repository, please see
-<a href="#perlgit-NAME">perlgit NAME</a>.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhack-Read-access-via-Git" accesskey="1">perlhack Read access via
Git</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Read-access-via-the-web" accesskey="2">perlhack Read access via
the web</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Read-access-via-rsync" accesskey="3">perlhack Read access via
rsync</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Write-access-via-git" accesskey="4">perlhack Write access via
git</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhack-Read-access-via-Git"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Read-access-via-the-web" accesskey="n"
rel="next">perlhack Read access via the web</a>, Up: <a
href="#perlhack-GETTING-THE-PERL-SOURCE" accesskey="u" rel="up">perlhack
GETTING THE PERL SOURCE</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Read-access-via-Git"></a>
-<h4 class="subsection">29.6.1 Read access via Git</h4>
-
-<p>You will need a copy of Git for your computer. You can fetch a copy of
-the repository using the git protocol:
-</p>
-<pre class="verbatim"> % git clone git://perl5.git.perl.org/perl.git perl
-</pre>
-<p>This clones the repository and makes a local copy in the <samp>perl</samp>
-directory.
-</p>
-<p>If you cannot use the git protocol for firewall reasons, you can also
-clone via http, though this is much slower:
-</p>
-<pre class="verbatim"> % git clone http://perl5.git.perl.org/perl.git perl
-</pre>
-<hr>
-<a name="perlhack-Read-access-via-the-web"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Read-access-via-rsync" accesskey="n"
rel="next">perlhack Read access via rsync</a>, Previous: <a
href="#perlhack-Read-access-via-Git" accesskey="p" rel="prev">perlhack Read
access via Git</a>, Up: <a href="#perlhack-GETTING-THE-PERL-SOURCE"
accesskey="u" rel="up">perlhack GETTING THE PERL SOURCE</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Read-access-via-the-web"></a>
-<h4 class="subsection">29.6.2 Read access via the web</h4>
-
-<p>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
-<a
href="http://perl5.git.perl.org/perl.git";>http://perl5.git.perl.org/perl.git</a>.
A mirror of the repository is
-found at <a
href="https://github.com/Perl/perl5";>https://github.com/Perl/perl5</a>.
-</p>
-<hr>
-<a name="perlhack-Read-access-via-rsync"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Write-access-via-git" accesskey="n"
rel="next">perlhack Write access via git</a>, Previous: <a
href="#perlhack-Read-access-via-the-web" accesskey="p" rel="prev">perlhack Read
access via the web</a>, Up: <a href="#perlhack-GETTING-THE-PERL-SOURCE"
accesskey="u" rel="up">perlhack GETTING THE PERL SOURCE</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Read-access-via-rsync"></a>
-<h4 class="subsection">29.6.3 Read access via rsync</h4>
-
-<p>You can also choose to use rsync to get a copy of the current source
-tree for the bleadperl branch and all maintenance branches:
-</p>
-<pre class="verbatim"> % 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 .
-</pre>
-<p>(Add the <code>--delete</code> option to remove leftover files.)
-</p>
-<p>To get a full list of the available sync points:
-</p>
-<pre class="verbatim"> % rsync perl5.git.perl.org::
-</pre>
-<hr>
-<a name="perlhack-Write-access-via-git"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhack-Read-access-via-rsync" accesskey="p"
rel="prev">perlhack Read access via rsync</a>, Up: <a
href="#perlhack-GETTING-THE-PERL-SOURCE" accesskey="u" rel="up">perlhack
GETTING THE PERL SOURCE</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Write-access-via-git"></a>
-<h4 class="subsection">29.6.4 Write access via git</h4>
-
-<p>If you have a commit bit, please see <a href="#perlgit-NAME">perlgit
NAME</a> for more details on
-using git.
-</p>
-<hr>
-<a name="perlhack-PATCHING-PERL"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-TESTING" accesskey="n" rel="next">perlhack
TESTING</a>, Previous: <a href="#perlhack-GETTING-THE-PERL-SOURCE"
accesskey="p" rel="prev">perlhack GETTING THE PERL SOURCE</a>, Up: <a
href="#perlhack" accesskey="u" rel="up">perlhack</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PATCHING-PERL"></a>
-<h3 class="section">29.7 PATCHING PERL</h3>
-
-<p>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.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhack-Submitting-patches" accesskey="1">perlhack Submitting
patches</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Getting-your-patch-accepted" accesskey="2">perlhack Getting
your patch accepted</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Patching-a-core-module" accesskey="3">perlhack Patching a core
module</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Updating-perldelta" accesskey="4">perlhack Updating
perldelta</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-What-makes-for-a-good-patch_003f" accesskey="5">perlhack What
makes for a good patch?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhack-Submitting-patches"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Getting-your-patch-accepted" accesskey="n"
rel="next">perlhack Getting your patch accepted</a>, Up: <a
href="#perlhack-PATCHING-PERL" accesskey="u" rel="up">perlhack PATCHING
PERL</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Submitting-patches"></a>
-<h4 class="subsection">29.7.1 Submitting patches</h4>
-
-<p>If you have a small patch to submit, please submit it via perlbug. You
-can also send email directly to address@hidden Please note that
-messages sent to perlbug may be held in a moderation queue, so you
-won’t receive a response immediately.
-</p>
-<p>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 address@hidden list.
-</p>
-<p>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.
-</p>
-<p>In other cases, the patch will need more work or discussion. That will
-happen on the p5p list.
-</p>
-<p>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.
-</p>
-<p>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 (see <a href="#perlpolicy-MAINTENANCE-BRANCHES">perlpolicy MAINTENANCE
BRANCHES</a>), please explain why
-when you submit it.
-</p>
-<hr>
-<a name="perlhack-Getting-your-patch-accepted"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Patching-a-core-module" accesskey="n"
rel="next">perlhack Patching a core module</a>, Previous: <a
href="#perlhack-Submitting-patches" accesskey="p" rel="prev">perlhack
Submitting patches</a>, Up: <a href="#perlhack-PATCHING-PERL" accesskey="u"
rel="up">perlhack PATCHING PERL</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Getting-your-patch-accepted"></a>
-<h4 class="subsection">29.7.2 Getting your patch accepted</h4>
-
-<p>If you are submitting a code patch there are several things that you
-can do to help the Perl 5 Porters accept your patch.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlhack-Patch-style"
accesskey="1">perlhack Patch style</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhack-Commit-message"
accesskey="2">perlhack Commit message</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Comments_002c-Comments_002c-Comments" accesskey="3">perlhack
Comments, Comments, Comments</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhack-Style"
accesskey="4">perlhack Style</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhack-Test-suite"
accesskey="5">perlhack Test suite</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhack-Patch-style"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Commit-message" accesskey="n" rel="next">perlhack
Commit message</a>, Up: <a href="#perlhack-Getting-your-patch-accepted"
accesskey="u" rel="up">perlhack Getting your patch accepted</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Patch-style"></a>
-<h4 class="subsubsection">29.7.2.1 Patch style</h4>
-
-<p>If you used git to check out the Perl source, then using <code>git
-format-patch</code> will produce a patch in a style suitable for Perl. The
-<code>format-patch</code> command produces one patch file for each commit you
-made. If you prefer to send a single patch for all commits, you can
-use <code>git diff</code>.
-</p>
-<pre class="verbatim"> % git checkout blead
- % git pull
- % git diff blead my-branch-name
-</pre>
-<p>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 <code>git pull</code>
first.
-</p>
-<p>We strongly recommend that you use git if possible. It will make your
-life easier, and ours as well.
-</p>
-<p>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 <code>diff</code>, you can
produce a
-diff like this:
-</p>
-<pre class="verbatim"> % diff -Npurd perl.pristine perl.mine
-</pre>
-<p>Make sure that you <code>make realclean</code> in your copy of Perl to
remove any
-build artifacts, or you may get a confusing result.
-</p>
-<hr>
-<a name="perlhack-Commit-message"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Comments_002c-Comments_002c-Comments" accesskey="n"
rel="next">perlhack Comments, Comments, Comments</a>, Previous: <a
href="#perlhack-Patch-style" accesskey="p" rel="prev">perlhack Patch style</a>,
Up: <a href="#perlhack-Getting-your-patch-accepted" accesskey="u"
rel="up">perlhack Getting your patch accepted</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Commit-message"></a>
-<h4 class="subsubsection">29.7.2.2 Commit message</h4>
-
-<p>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.
-</p>
-<p>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.
-</p>
-<p>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.
-</p>
-<p>The commit message should include a description of the problem that the
-patch corrects or new functionality that the patch adds.
-</p>
-<p>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.
-</p>
-<ul>
-<li> Why
-
-<p>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.
-</p>
-<p>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.
-</p>
-</li><li> What
-
-<p>Your commit message should describe what part of the Perl core you’re
-changing and what you expect your patch to do.
-</p>
-</li><li> How
-
-<p>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.
-</p>
-</li></ul>
-
-<p>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.
-</p>
-<p>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.
-</p>
-<hr>
-<a name="perlhack-Comments_002c-Comments_002c-Comments"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Style" accesskey="n" rel="next">perlhack Style</a>,
Previous: <a href="#perlhack-Commit-message" accesskey="p" rel="prev">perlhack
Commit message</a>, Up: <a href="#perlhack-Getting-your-patch-accepted"
accesskey="u" rel="up">perlhack Getting your patch accepted</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Comments_002c-Comments_002c-Comments"></a>
-<h4 class="subsubsection">29.7.2.3 Comments, Comments, Comments</h4>
-
-<p>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.
-</p>
-<p>The best comments explain <em>why</em> the code does what it does, not
<em>what
-it does</em>.
-</p>
-<hr>
-<a name="perlhack-Style"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Test-suite" accesskey="n" rel="next">perlhack Test
suite</a>, Previous: <a href="#perlhack-Comments_002c-Comments_002c-Comments"
accesskey="p" rel="prev">perlhack Comments, Comments, Comments</a>, Up: <a
href="#perlhack-Getting-your-patch-accepted" accesskey="u" rel="up">perlhack
Getting your patch accepted</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Style"></a>
-<h4 class="subsubsection">29.7.2.4 Style</h4>
-
-<p>In general, please follow the particular style of the code you are
-patching.
-</p>
-<p>In particular, follow these general guidelines for patching Perl
-sources:
-</p>
-<ul>
-<li> 8-wide tabs (no exceptions!)
-
-</li><li> 4-wide indents for code, 2-wide indents for nested CPP #defines
-
-</li><li> Try hard not to exceed 79-columns
-
-</li><li> ANSI C prototypes
-
-</li><li> Uncuddled elses and "K&R" style for indenting control
constructs
-
-</li><li> No C++ style (//) comments
-
-</li><li> Mark places that need to be revisited with XXX (and revisit often!)
-
-</li><li> Opening brace lines up with "if" when conditional spans
multiple lines;
-should be at end-of-line otherwise
-
-</li><li> In function definitions, name starts in column 0 (return value-type
is on
-previous line)
-
-</li><li> Single space after keywords that are followed by parens, no space
-between function name and following paren
-
-</li><li> Avoid assignments in conditionals, but if they’re unavoidable,
use
-extra paren, e.g. "if (a && (b = c)) ..."
-
-</li><li> "return foo;" rather than "return(foo);"
-
-</li><li> "if (!foo) ..." rather than "if (foo == FALSE)
..." etc.
-
-</li><li> Do not declare variables using "register". It may be
counterproductive
-with modern compilers, and is deprecated in C++, under which the Perl
-source is regularly compiled.
-
-</li><li> In-line functions that are in headers that are accessible to XS code
-need to be able to compile without warnings with commonly used extra
-compilation flags, such as gcc’s <code>-Wswitch-default</code> which
warns
-whenever a switch statement does not have a "default" case. The use
of
-these extra flags is to catch potential problems in legal C code, and
-is often used by Perl aggregators, such as Linux distributors.
-
-</li></ul>
-
-<hr>
-<a name="perlhack-Test-suite"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhack-Style" accesskey="p" rel="prev">perlhack
Style</a>, Up: <a href="#perlhack-Getting-your-patch-accepted" accesskey="u"
rel="up">perlhack Getting your patch accepted</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Test-suite"></a>
-<h4 class="subsubsection">29.7.2.5 Test suite</h4>
-
-<p>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.
-</p>
-<p>Your test suite additions should generally follow these guidelines
-(courtesy of Gurusamy Sarathy <address@hidden>):
-</p>
-<ul>
-<li> Know what you’re testing. Read the docs, and the source.
-
-</li><li> Tend to fail, not succeed.
-
-</li><li> Interpret results strictly.
-
-</li><li> Use unrelated features (this will flush out bizarre interactions).
-
-</li><li> Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
-
-</li><li> 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).
-
-</li><li> Give meaningful error messages when a test fails.
-
-</li><li> Avoid using qx// and system() unless you are testing for them. If
you
-do use them, make sure that you cover _all_ perl platforms.
-
-</li><li> Unlink any temporary files you create.
-
-</li><li> Promote unforeseen warnings to errors with $SIG{__WARN__}.
-
-</li><li> Be sure to use the libraries and modules shipped with the version
being
-tested, not those that were already installed.
-
-</li><li> Add comments to the code explaining what you are testing for.
-
-</li><li> Make updating the ’1..42’ string unnecessary. Or make
sure that you
-update it.
-
-</li><li> Test _all_ behaviors of a given operator, library, or function.
-
-<p>Test all optional arguments.
-</p>
-<p>Test return values in various contexts (boolean, scalar, list, lvalue).
-</p>
-<p>Use both global and lexical variables.
-</p>
-<p>Don’t forget the exceptional, pathological cases.
-</p>
-</li></ul>
-
-<hr>
-<a name="perlhack-Patching-a-core-module"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Updating-perldelta" accesskey="n" rel="next">perlhack
Updating perldelta</a>, Previous: <a
href="#perlhack-Getting-your-patch-accepted" accesskey="p" rel="prev">perlhack
Getting your patch accepted</a>, Up: <a href="#perlhack-PATCHING-PERL"
accesskey="u" rel="up">perlhack PATCHING PERL</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Patching-a-core-module"></a>
-<h4 class="subsection">29.7.3 Patching a core module</h4>
-
-<p>This works just like patching anything else, with one extra
-consideration.
-</p>
-<p>Modules in the <samp>cpan/</samp> directory of the source tree are
maintained
-outside of the Perl core. When the author updates the module, the
-updates are simply copied into the core. See that module’s
-documentation or its listing on <a
href="http://search.cpan.org/";>http://search.cpan.org/</a> for more
-information on reporting bugs and submitting patches.
-</p>
-<p>In most cases, patches to modules in <samp>cpan/</samp> should be sent
upstream
-and should not be applied to the Perl core individually. If a patch to
-a file in <samp>cpan/</samp> absolutely cannot wait for the fix to be made
-upstream, released to CPAN and copied to blead, you must add (or
-update) a <code>CUSTOMIZED</code> entry in the
<samp>"Porting/Maintainers.pl"</samp> file
-to flag that a local modification has been made. See
-<samp>"Porting/Maintainers.pl"</samp> for more details.
-</p>
-<p>In contrast, modules in the <samp>dist/</samp> directory are maintained in
the
-core.
-</p>
-<hr>
-<a name="perlhack-Updating-perldelta"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-What-makes-for-a-good-patch_003f" accesskey="n"
rel="next">perlhack What makes for a good patch?</a>, Previous: <a
href="#perlhack-Patching-a-core-module" accesskey="p" rel="prev">perlhack
Patching a core module</a>, Up: <a href="#perlhack-PATCHING-PERL" accesskey="u"
rel="up">perlhack PATCHING PERL</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Updating-perldelta"></a>
-<h4 class="subsection">29.7.4 Updating perldelta</h4>
-
-<p>For changes significant enough to warrant a <samp>pod/perldelta.pod</samp>
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:
-</p>
-<ul>
-<li> Adding, deprecating, or removing core features
-
-</li><li> Adding, deprecating, removing, or upgrading core or dual-life modules
-
-</li><li> Adding new core tests
-
-</li><li> Fixing security issues and user-visible bugs in the core
-
-</li><li> Changes that might break existing code, either on the perl or C level
-
-</li><li> Significant performance improvements
-
-</li><li> Adding, removing, or significantly changing documentation in the
-<samp>pod/</samp> directory
-
-</li><li> Important platform-specific changes
-
-</li></ul>
-
-<p>Please make sure you add the perldelta entry to the right section
-within <samp>pod/perldelta.pod</samp>. More information on how to write good
-perldelta entries is available in the <code>Style</code> section of
-<samp>Porting/how_to_write_a_perldelta.pod</samp>.
-</p>
-<hr>
-<a name="perlhack-What-makes-for-a-good-patch_003f"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhack-Updating-perldelta" accesskey="p"
rel="prev">perlhack Updating perldelta</a>, Up: <a
href="#perlhack-PATCHING-PERL" accesskey="u" rel="up">perlhack PATCHING
PERL</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="What-makes-for-a-good-patch_003f"></a>
-<h4 class="subsection">29.7.5 What makes for a good patch?</h4>
-
-<p>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:
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhack-Does-the-concept-match-the-general-goals-of-Perl_003f"
accesskey="1">perlhack Does the concept match the general goals of
Perl?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Where-is-the-implementation_003f" accesskey="2">perlhack Where
is the implementation?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Backwards-compatibility" accesskey="3">perlhack Backwards
compatibility</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Could-it-be-a-module-instead_003f" accesskey="4">perlhack Could
it be a module instead?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Is-the-feature-generic-enough_003f" accesskey="5">perlhack Is
the feature generic enough?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Does-it-potentially-introduce-new-bugs_003f"
accesskey="6">perlhack Does it potentially introduce new
bugs?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-How-big-is-it_003f" accesskey="7">perlhack How big is
it?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Does-it-preclude-other-desirable-features_003f"
accesskey="8">perlhack Does it preclude other desirable
features?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Is-the-implementation-robust_003f" accesskey="9">perlhack Is
the implementation robust?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Is-the-implementation-generic-enough-to-be-portable_003f">perlhack
Is the implementation generic enough to be
portable?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Is-the-implementation-tested_003f">perlhack Is the
implementation tested?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Is-there-enough-documentation_003f">perlhack Is there enough
documentation?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Is-there-another-way-to-do-it_003f">perlhack Is there another
way to do it?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Does-it-create-too-much-work_003f">perlhack Does it create too
much work?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Patches-speak-louder-than-words">perlhack Patches speak louder
than words</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhack-Does-the-concept-match-the-general-goals-of-Perl_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Where-is-the-implementation_003f" accesskey="n"
rel="next">perlhack Where is the implementation?</a>, Up: <a
href="#perlhack-What-makes-for-a-good-patch_003f" accesskey="u"
rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Does-the-concept-match-the-general-goals-of-Perl_003f"></a>
-<h4 class="subsubsection">29.7.5.1 Does the concept match the general goals of
Perl?</h4>
-
-<p>Our goals include, but are not limited to:
-</p>
-<ol>
-<li> Keep it fast, simple, and useful.
-
-</li><li> Keep features/concepts as orthogonal as possible.
-
-</li><li> No arbitrary limits (platforms, data sizes, cultures).
-
-</li><li> Keep it open and exciting to use/patch/advocate Perl everywhere.
-
-</li><li> Either assimilate new technologies, or build bridges to them.
-
-</li></ol>
-
-<hr>
-<a name="perlhack-Where-is-the-implementation_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Backwards-compatibility" accesskey="n"
rel="next">perlhack Backwards compatibility</a>, Previous: <a
href="#perlhack-Does-the-concept-match-the-general-goals-of-Perl_003f"
accesskey="p" rel="prev">perlhack Does the concept match the general goals of
Perl?</a>, Up: <a href="#perlhack-What-makes-for-a-good-patch_003f"
accesskey="u" rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Where-is-the-implementation_003f"></a>
-<h4 class="subsubsection">29.7.5.2 Where is the implementation?</h4>
-
-<p>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.
-</p>
-<hr>
-<a name="perlhack-Backwards-compatibility"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Could-it-be-a-module-instead_003f" accesskey="n"
rel="next">perlhack Could it be a module instead?</a>, Previous: <a
href="#perlhack-Where-is-the-implementation_003f" accesskey="p"
rel="prev">perlhack Where is the implementation?</a>, Up: <a
href="#perlhack-What-makes-for-a-good-patch_003f" accesskey="u"
rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Backwards-compatibility-1"></a>
-<h4 class="subsubsection">29.7.5.3 Backwards compatibility</h4>
-
-<p>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.
-</p>
-<p>The Perl 5 core includes mechanisms to help porters make backwards
-incompatible changes more compatible such as the <a
href="feature.html#Top">(feature)</a> and
-<a href="deprecate.html#Top">(deprecate)</a> modules. Please use them when
appropriate.
-</p>
-<hr>
-<a name="perlhack-Could-it-be-a-module-instead_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Is-the-feature-generic-enough_003f" accesskey="n"
rel="next">perlhack Is the feature generic enough?</a>, Previous: <a
href="#perlhack-Backwards-compatibility" accesskey="p" rel="prev">perlhack
Backwards compatibility</a>, Up: <a
href="#perlhack-What-makes-for-a-good-patch_003f" accesskey="u"
rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Could-it-be-a-module-instead_003f"></a>
-<h4 class="subsubsection">29.7.5.4 Could it be a module instead?</h4>
-
-<p>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.
-</p>
-<p>Whenever possible, new features should be prototyped in a CPAN module
-before they will be considered for the core.
-</p>
-<hr>
-<a name="perlhack-Is-the-feature-generic-enough_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Does-it-potentially-introduce-new-bugs_003f"
accesskey="n" rel="next">perlhack Does it potentially introduce new bugs?</a>,
Previous: <a href="#perlhack-Could-it-be-a-module-instead_003f" accesskey="p"
rel="prev">perlhack Could it be a module instead?</a>, Up: <a
href="#perlhack-What-makes-for-a-good-patch_003f" accesskey="u"
rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Is-the-feature-generic-enough_003f"></a>
-<h4 class="subsubsection">29.7.5.5 Is the feature generic enough?</h4>
-
-<p>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.
-</p>
-<hr>
-<a name="perlhack-Does-it-potentially-introduce-new-bugs_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-How-big-is-it_003f" accesskey="n" rel="next">perlhack
How big is it?</a>, Previous: <a
href="#perlhack-Is-the-feature-generic-enough_003f" accesskey="p"
rel="prev">perlhack Is the feature generic enough?</a>, Up: <a
href="#perlhack-What-makes-for-a-good-patch_003f" accesskey="u"
rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Does-it-potentially-introduce-new-bugs_003f"></a>
-<h4 class="subsubsection">29.7.5.6 Does it potentially introduce new bugs?</h4>
-
-<p>Radical rewrites of large chunks of the Perl interpreter have the
-potential to introduce new bugs.
-</p>
-<hr>
-<a name="perlhack-How-big-is-it_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Does-it-preclude-other-desirable-features_003f"
accesskey="n" rel="next">perlhack Does it preclude other desirable
features?</a>, Previous: <a
href="#perlhack-Does-it-potentially-introduce-new-bugs_003f" accesskey="p"
rel="prev">perlhack Does it potentially introduce new bugs?</a>, Up: <a
href="#perlhack-What-makes-for-a-good-patch_003f" accesskey="u"
rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="How-big-is-it_003f"></a>
-<h4 class="subsubsection">29.7.5.7 How big is it?</h4>
-
-<p>The smaller and more localized the change, the better. Similarly, a
-series of small patches is greatly preferred over a single large patch.
-</p>
-<hr>
-<a name="perlhack-Does-it-preclude-other-desirable-features_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Is-the-implementation-robust_003f" accesskey="n"
rel="next">perlhack Is the implementation robust?</a>, Previous: <a
href="#perlhack-How-big-is-it_003f" accesskey="p" rel="prev">perlhack How big
is it?</a>, Up: <a href="#perlhack-What-makes-for-a-good-patch_003f"
accesskey="u" rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Does-it-preclude-other-desirable-features_003f"></a>
-<h4 class="subsubsection">29.7.5.8 Does it preclude other desirable
features?</h4>
-
-<p>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.
-</p>
-<hr>
-<a name="perlhack-Is-the-implementation-robust_003f"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlhack-Is-the-implementation-generic-enough-to-be-portable_003f"
accesskey="n" rel="next">perlhack Is the implementation generic enough to be
portable?</a>, Previous: <a
href="#perlhack-Does-it-preclude-other-desirable-features_003f" accesskey="p"
rel="prev">perlhack Does it preclude other desirable features?</a>, Up: <a
href="#perlhack-What-makes-for-a-good-patch_003f" accesskey="u"
rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Is-the-implementation-robust_003f"></a>
-<h4 class="subsubsection">29.7.5.9 Is the implementation robust?</h4>
-
-<p>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.
-</p>
-<hr>
-<a
name="perlhack-Is-the-implementation-generic-enough-to-be-portable_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Is-the-implementation-tested_003f" accesskey="n"
rel="next">perlhack Is the implementation tested?</a>, Previous: <a
href="#perlhack-Is-the-implementation-robust_003f" accesskey="p"
rel="prev">perlhack Is the implementation robust?</a>, Up: <a
href="#perlhack-What-makes-for-a-good-patch_003f" accesskey="u"
rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Is-the-implementation-generic-enough-to-be-portable_003f"></a>
-<h4 class="subsubsection">29.7.5.10 Is the implementation generic enough to be
portable?</h4>
-
-<p>The worst patches make use of system-specific features. It’s highly
-unlikely that non-portable additions to the Perl language will be
-accepted.
-</p>
-<hr>
-<a name="perlhack-Is-the-implementation-tested_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Is-there-enough-documentation_003f" accesskey="n"
rel="next">perlhack Is there enough documentation?</a>, Previous: <a
href="#perlhack-Is-the-implementation-generic-enough-to-be-portable_003f"
accesskey="p" rel="prev">perlhack Is the implementation generic enough to be
portable?</a>, Up: <a href="#perlhack-What-makes-for-a-good-patch_003f"
accesskey="u" rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Is-the-implementation-tested_003f"></a>
-<h4 class="subsubsection">29.7.5.11 Is the implementation tested?</h4>
-
-<p>Patches which change behaviour (fixing bugs or introducing new
-features) must include regression tests to verify that everything works
-as expected.
-</p>
-<p>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?
-</p>
-<hr>
-<a name="perlhack-Is-there-enough-documentation_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Is-there-another-way-to-do-it_003f" accesskey="n"
rel="next">perlhack Is there another way to do it?</a>, Previous: <a
href="#perlhack-Is-the-implementation-tested_003f" accesskey="p"
rel="prev">perlhack Is the implementation tested?</a>, Up: <a
href="#perlhack-What-makes-for-a-good-patch_003f" accesskey="u"
rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Is-there-enough-documentation_003f"></a>
-<h4 class="subsubsection">29.7.5.12 Is there enough documentation?</h4>
-
-<p>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.
-</p>
-<hr>
-<a name="perlhack-Is-there-another-way-to-do-it_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Does-it-create-too-much-work_003f" accesskey="n"
rel="next">perlhack Does it create too much work?</a>, Previous: <a
href="#perlhack-Is-there-enough-documentation_003f" accesskey="p"
rel="prev">perlhack Is there enough documentation?</a>, Up: <a
href="#perlhack-What-makes-for-a-good-patch_003f" accesskey="u"
rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Is-there-another-way-to-do-it_003f"></a>
-<h4 class="subsubsection">29.7.5.13 Is there another way to do it?</h4>
-
-<p>Larry said "Although the Perl Slogan is <em>There’s More Than
One Way to
-Do It</em>, 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.
-</p>
-<hr>
-<a name="perlhack-Does-it-create-too-much-work_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Patches-speak-louder-than-words" accesskey="n"
rel="next">perlhack Patches speak louder than words</a>, Previous: <a
href="#perlhack-Is-there-another-way-to-do-it_003f" accesskey="p"
rel="prev">perlhack Is there another way to do it?</a>, Up: <a
href="#perlhack-What-makes-for-a-good-patch_003f" accesskey="u"
rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Does-it-create-too-much-work_003f"></a>
-<h4 class="subsubsection">29.7.5.14 Does it create too much work?</h4>
-
-<p>Work for the pumpking, work for Perl programmers, work for module
-authors, ... Perl is supposed to be easy.
-</p>
-<hr>
-<a name="perlhack-Patches-speak-louder-than-words"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhack-Does-it-create-too-much-work_003f" accesskey="p"
rel="prev">perlhack Does it create too much work?</a>, Up: <a
href="#perlhack-What-makes-for-a-good-patch_003f" accesskey="u"
rel="up">perlhack What makes for a good patch?</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Patches-speak-louder-than-words"></a>
-<h4 class="subsubsection">29.7.5.15 Patches speak louder than words</h4>
-
-<p>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.
-</p>
-<hr>
-<a name="perlhack-TESTING"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-MORE-READING-FOR-GUTS-HACKERS" accesskey="n"
rel="next">perlhack MORE READING FOR GUTS HACKERS</a>, Previous: <a
href="#perlhack-PATCHING-PERL" accesskey="p" rel="prev">perlhack PATCHING
PERL</a>, Up: <a href="#perlhack" accesskey="u" rel="up">perlhack</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="TESTING"></a>
-<h3 class="section">29.8 TESTING</h3>
-
-<p>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.
-</p>
-<p>There are three ways to write a test in the core: <a
href="Test-More.html#Top">(Test-More)</a>,
-<samp>t/test.pl</samp> and ad hoc <code>print $test ? "ok 42\n" :
"not ok 42\n"</code>.
-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.
-</p>
-<p>The <samp>t/test.pl</samp> library provides some of the features of
-<a href="Test-More.html#Top">(Test-More)</a>, but avoids loading most modules
and uses as few core
-features as possible.
-</p>
-<p>If you write your own test, use the <a href="http://testanything.org";>Test
Anything
-Protocol</a>.
-</p>
-<ul>
-<li> <samp>t/base</samp>, <samp>t/comp</samp> and <samp>t/opbasic</samp>
-
-<p>Since we don’t know if <code>require</code> works, or even
subroutines, use ad hoc
-tests for these three. Step carefully to avoid using the feature being
-tested. Tests in <samp>t/opbasic</samp>, for instance, have been placed there
-rather than in <samp>t/op</samp> because they test functionality which
-<samp>t/test.pl</samp> presumes has already been demonstrated to work.
-</p>
-</li><li> <samp>t/cmd</samp>, <samp>t/run</samp>, <samp>t/io</samp> and
<samp>t/op</samp>
-
-<p>Now that basic require() and subroutines are tested, you can use the
-<samp>t/test.pl</samp> library.
-</p>
-<p>You can also use certain libraries like Config conditionally, but be
-sure to skip the test gracefully if it’s not there.
-</p>
-</li><li> Everything else
-
-<p>Now that the core of Perl is tested, <a
href="Test-More.html#Top">(Test-More)</a> can and should be
-used. You can also use the full suite of core modules in the tests.
-</p>
-</li></ul>
-
-<p>When you say "make test", Perl uses the <samp>t/TEST</samp>
program to run the
-test suite (except under Win32 where it uses <samp>t/harness</samp> instead).
-All tests are run from the <samp>t/</samp> directory, <strong>not</strong> the
directory which
-contains the test. This causes some problems with the tests in
-<samp>lib/</samp>, so here’s some opportunity for some patching.
-</p>
-<p>You must be triply conscious of cross-platform concerns. This usually
-boils down to using <a href="File-Spec.html#Top">(File-Spec)</a>, avoiding
things like <code>fork()</code>
-and <code>system()</code> unless absolutely necessary, and not assuming that a
-given character has a particular ordinal value (code point) or that its
-UTF-8 representation is composed of particular bytes.
-</p>
-<p>There are several functions available to specify characters and code
-points portably in tests. The always-preloaded functions
-<code>utf8::unicode_to_native()</code> and its inverse
-<code>utf8::native_to_unicode()</code> take code points and translate
-appropriately. The file <samp>t/charset_tools.pl</samp> has several functions
-that can be useful. It has versions of the previous two functions
-that take strings as inputs – not single numeric code points:
-<code>uni_to_native()</code> and <code>native_to_uni()</code>. If you must
look at the
-individual bytes comprising a UTF-8 encoded string,
-<code>byte_utf8a_to_utf8n()</code> takes as input a string of those bytes
encoded
-for an ASCII platform, and returns the equivalent string in the native
-platform. For example, <code>byte_utf8a_to_utf8n("\xC2\xA0")</code>
returns the
-byte sequence on the current platform that form the UTF-8 for
<code>U+00A0</code>,
-since <code>"\xC2\xA0"</code> are the UTF-8 bytes on an ASCII
platform for that
-code point. This function returns <code>"\xC2\xA0"</code> on an
ASCII platform, and
-<code>"\x80\x41"</code> on an EBCDIC 1047 one.
-</p>
-<p>But easiest is, if the character is specifiable as a literal, like
-<code>"A"</code> or <code>"%"</code>, to use that; if not
so specificable, you can use use
-<code>\N{}</code> , if the side effects aren’t troublesome. Simply
specify all
-your characters in hex, using <code>\N{U+ZZ}</code> instead of
<code>\xZZ</code>. <code>\N{}</code>
-is the Unicode name, and so it
-always gives you the Unicode character. <code>\N{U+41}</code> is the character
-whose Unicode code point is <code>0x41</code>, hence is <code>'A'</code> on
all platforms.
-The side effects are:
-</p>
-<dl compact="compact">
-<dt>1)</dt>
-<dd><a name="perlhack-1_0029"></a>
-<p>These select Unicode rules. That means that in double-quotish strings,
-the string is always converted to UTF-8 to force a Unicode
-interpretation (you can <code>utf8::downgrade()</code> afterwards to convert
back
-to non-UTF8, if possible). In regular expression patterns, the
-conversion isn’t done, but if the character set modifier would
-otherwise be <code>/d</code>, it is changed to <code>/u</code>.
-</p>
-</dd>
-<dt>2)</dt>
-<dd><a name="perlhack-2_0029"></a>
-<p>If you use the form <code>\N{<em>character name</em>}</code>, the <a
href="charnames.html#Top">(charnames)</a> module
-gets automatically loaded. This may not be suitable for the test level
-you are doing.
-</p>
-</dd>
-</dl>
-
-<p>If you are testing locales (see <a href="#perllocale-NAME">perllocale
NAME</a>), there are helper
-functions in <samp>t/loc_tools.pl</samp> to enable you to see what locales
there
-are on the current platform.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhack-Special-make-test-targets" accesskey="1">perlhack Special
<code>make test</code> targets</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhack-Parallel-tests"
accesskey="2">perlhack Parallel tests</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Running-tests-by-hand" accesskey="3">perlhack Running tests by
hand</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Using-t_002fharness-for-testing" accesskey="4">perlhack Using
<samp>t/harness</samp> for testing</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Performance-testing" accesskey="5">perlhack Performance
testing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhack-Special-make-test-targets"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Parallel-tests" accesskey="n" rel="next">perlhack
Parallel tests</a>, Up: <a href="#perlhack-TESTING" accesskey="u"
rel="up">perlhack TESTING</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Special-make-test-targets"></a>
-<h4 class="subsection">29.8.1 Special <code>make test</code> targets</h4>
-
-<p>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
-aliases, and many of them are not available on certain operating
-systems.
-</p>
-<ul>
-<li> test_porting
-
-<p>This runs some basic sanity tests on the source tree and helps catch
-basic errors before you submit a patch.
-</p>
-</li><li> minitest
-
-<p>Run <samp>miniperl</samp> on <samp>t/base</samp>, <samp>t/comp</samp>,
<samp>t/cmd</samp>, <samp>t/run</samp>, <samp>t/io</samp>,
-<samp>t/op</samp>, <samp>t/uni</samp> and <samp>t/mro</samp> tests.
-</p>
-</li><li> test.valgrind check.valgrind
-
-<p>(Only in Linux) Run all the tests using the memory leak + naughty
-memory access tool "valgrind". The log files will be named
-<samp>testname.valgrind</samp>.
-</p>
-</li><li> test_harness
-
-<p>Run the test suite with the <samp>t/harness</samp> controlling program,
instead
-of <samp>t/TEST</samp>. <samp>t/harness</samp> is more sophisticated, and
uses the
-<a href="Test-Harness.html#Top">(Test-Harness)</a> 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 <samp>t/TEST</samp>,
-it doesn’t redirect stderr to stdout.
-</p>
-<p>Note that under Win32 <samp>t/harness</samp> is always used instead of
<samp>t/TEST</samp>,
-so there is no special "test_harness" target.
-</p>
-<p>Under Win32’s "test" target you may use the TEST_SWITCHES
and
-TEST_FILES environment variables to control the behaviour of
-<samp>t/harness</samp>. This means you can say
-</p>
-<pre class="verbatim"> nmake test TEST_FILES="op/*.t"
- nmake test TEST_SWITCHES="-torture" TEST_FILES="op/*.t"
-</pre>
-</li><li> test-notty test_notty
-
-<p>Sets PERL_SKIP_TTY_TEST to true before running normal test.
-</p>
-</li></ul>
-
-<hr>
-<a name="perlhack-Parallel-tests"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Running-tests-by-hand" accesskey="n"
rel="next">perlhack Running tests by hand</a>, Previous: <a
href="#perlhack-Special-make-test-targets" accesskey="p" rel="prev">perlhack
Special <code>make test</code> targets</a>, Up: <a href="#perlhack-TESTING"
accesskey="u" rel="up">perlhack TESTING</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Parallel-tests"></a>
-<h4 class="subsection">29.8.2 Parallel tests</h4>
-
-<p>The core distribution can now run its regression tests in parallel on
-Unix-like platforms. Instead of running <code>make test</code>, set
<code>TEST_JOBS</code>
-in your environment to the number of tests to run in parallel, and run
-<code>make test_harness</code>. On a Bourne-like shell, this can be done as
-</p>
-<pre class="verbatim"> TEST_JOBS=3 make test_harness # Run 3 tests in
parallel
-</pre>
-<p>An environment variable is used, rather than parallel make itself,
-because <a href="TAP-Harness.html#Top">(TAP-Harness)</a> needs to be able to
schedule individual
-non-conflicting test scripts itself, and there is no standard interface
-to <code>make</code> utilities to interact with their job schedulers.
-</p>
-<p>Note that currently some test scripts may fail when run in parallel
-(most notably <samp>ext/IO/t/io_dir.t</samp>). If necessary, run just the
-failing scripts again sequentially and see if the failures go away.
-</p>
-<hr>
-<a name="perlhack-Running-tests-by-hand"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Using-t_002fharness-for-testing" accesskey="n"
rel="next">perlhack Using <samp>t/harness</samp> for testing</a>, Previous: <a
href="#perlhack-Parallel-tests" accesskey="p" rel="prev">perlhack Parallel
tests</a>, Up: <a href="#perlhack-TESTING" accesskey="u" rel="up">perlhack
TESTING</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Running-tests-by-hand"></a>
-<h4 class="subsection">29.8.3 Running tests by hand</h4>
-
-<p>You can run part of the test suite by hand by using one of the
-following commands from the <samp>t/</samp> directory:
-</p>
-<pre class="verbatim"> ./perl -I../lib TEST list-of-.t-files
-</pre>
-<p>or
-</p>
-<pre class="verbatim"> ./perl -I../lib harness list-of-.t-files
-</pre>
-<p>(If you don’t specify test scripts, the whole test suite will be run.)
-</p>
-<hr>
-<a name="perlhack-Using-t_002fharness-for-testing"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Performance-testing" accesskey="n"
rel="next">perlhack Performance testing</a>, Previous: <a
href="#perlhack-Running-tests-by-hand" accesskey="p" rel="prev">perlhack
Running tests by hand</a>, Up: <a href="#perlhack-TESTING" accesskey="u"
rel="up">perlhack TESTING</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-t_002fharness-for-testing"></a>
-<h4 class="subsection">29.8.4 Using <samp>t/harness</samp> for testing</h4>
-
-<p>If you use <code>harness</code> 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.
-</p>
-<pre class="verbatim"> harness -v -torture -re=pattern LIST OF FILES TO TEST
- harness -v -torture -re LIST OF PATTERNS TO MATCH
-</pre>
-<p>If <code>LIST OF FILES TO TEST</code> is omitted, the file list is obtained
from
-the manifest. The file list may include shell wildcards which will be
-expanded out.
-</p>
-<ul>
-<li> -v
-
-<p>Run the tests under verbose mode so you can see what tests were run,
-and debug output.
-</p>
-</li><li> -torture
-
-<p>Run the torture tests as well as the normal set.
-</p>
-</li><li> -re=PATTERN
-
-<p>Filter the file list so that all the test files run match PATTERN.
-Note that this form is distinct from the <strong>-re LIST OF PATTERNS</strong>
form
-below in that it allows the file list to be provided as well.
-</p>
-</li><li> -re LIST OF PATTERNS
-
-<p>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.
-</p>
-</li></ul>
-
-<p>You can run an individual test by a command similar to
-</p>
-<pre class="verbatim"> ./perl -I../lib path/to/foo.t
-</pre>
-<p>except that the harnesses set up some environment variables that may
-affect the execution of the test:
-</p>
-<ul>
-<li> PERL_CORE=1
-
-<p>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.
-</p>
-</li><li> PERL_DESTRUCT_LEVEL=2
-
-<p>is set to 2 if it isn’t set already (see
-<a href="#perlhacktips-PERL_005fDESTRUCT_005fLEVEL">perlhacktips
PERL_DESTRUCT_LEVEL</a>).
-</p>
-</li><li> PERL
-
-<p>(used only by <samp>t/TEST</samp>) if set, overrides the path to the perl
-executable that should be used to run the tests (the default being
-<samp>./perl</samp>).
-</p>
-</li><li> PERL_SKIP_TTY_TEST
-
-<p>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 running ’make test_notty’.
-</p>
-</li></ul>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhack-Other-environment-variables-that-may-influence-tests"
accesskey="1">perlhack Other environment variables that may influence
tests</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhack-Other-environment-variables-that-may-influence-tests"></a>
-<div class="header">
-<p>
-Up: <a href="#perlhack-Using-t_002fharness-for-testing" accesskey="u"
rel="up">perlhack Using <samp>t/harness</samp> for testing</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Other-environment-variables-that-may-influence-tests"></a>
-<h4 class="subsubsection">29.8.4.1 Other environment variables that may
influence tests</h4>
-
-<ul>
-<li> PERL_TEST_Net_Ping
-
-<p>Setting this variable runs all the Net::Ping modules tests, otherwise
-some tests that interact with the outside world are skipped. See
-<a href="perl58delta.html#Top">(perl58delta)</a>.
-</p>
-</li><li> PERL_TEST_NOVREXX
-
-<p>Setting this variable skips the vrexx.t tests for OS2::REXX.
-</p>
-</li><li> PERL_TEST_NUMCONVERTS
-
-<p>This sets a variable in op/numconvert.t.
-</p>
-</li><li> PERL_TEST_MEMORY
-
-<p>Setting this variable includes the tests in <samp>t/bigmem/</samp>. This
should
-be set to the number of gigabytes of memory available for testing, eg.
-<code>PERL_TEST_MEMORY=4</code> indicates that tests that require 4GiB of
-available memory can be run safely.
-</p>
-</li></ul>
-
-<p>See also the documentation for the Test and Test::Harness modules, for
-more environment variables that affect testing.
-</p>
-<hr>
-<a name="perlhack-Performance-testing"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhack-Using-t_002fharness-for-testing" accesskey="p"
rel="prev">perlhack Using <samp>t/harness</samp> for testing</a>, Up: <a
href="#perlhack-TESTING" accesskey="u" rel="up">perlhack TESTING</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Performance-testing"></a>
-<h4 class="subsection">29.8.5 Performance testing</h4>
-
-<p>The file <samp>t/perf/benchmarks</samp> contains snippets of perl code
which are
-intended to be benchmarked across a range of perls by the
-<samp>Porting/bench.pl</samp> tool. If you fix or enhance a performance issue,
you
-may want to add a representative code sample to the file, then run
-<samp>bench.pl</samp> against the previous and current perls to see what
difference
-it has made, and whether anything else has slowed down as a consequence.
-</p>
-<p>The file <samp>t/perf/opcount.t</samp> is designed to test whether a
particular
-code snippet has been compiled into an optree containing specified
-numbers of particular op types. This is good for testing whether
-optimisations which alter ops, such as converting an <code>aelem</code> op
into an
-<code>aelemfast</code> op, are really doing that.
-</p>
-<p>The files <samp>t/perf/speed.t</samp> and <samp>t/re/speed.t</samp> are
designed to test
-things that run thousands of times slower if a particular optimisation
-is broken (for example, the utf8 length cache on long utf8 strings).
-Add a test that will take a fraction of a second normally, and minutes
-otherwise, causing the test file to time out on failure.
-</p>
-<hr>
-<a name="perlhack-MORE-READING-FOR-GUTS-HACKERS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-CPAN-TESTERS-AND-PERL-SMOKERS" accesskey="n"
rel="next">perlhack CPAN TESTERS AND PERL SMOKERS</a>, Previous: <a
href="#perlhack-TESTING" accesskey="p" rel="prev">perlhack TESTING</a>, Up: <a
href="#perlhack" accesskey="u" rel="up">perlhack</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="MORE-READING-FOR-GUTS-HACKERS"></a>
-<h3 class="section">29.9 MORE READING FOR GUTS HACKERS</h3>
-
-<p>To hack on the Perl guts, you’ll need to read the following things:
-</p>
-<ul>
-<li> <a href="#perlsource-NAME">perlsource NAME</a>
-
-<p>An overview of the Perl source tree. This will help you find the files
-you’re looking for.
-</p>
-</li><li> <a href="#perlinterp-NAME">perlinterp NAME</a>
-
-<p>An overview of the Perl interpreter source code and some details on how
-Perl does what it does.
-</p>
-</li><li> <a href="#perlhacktut-NAME">perlhacktut NAME</a>
-
-<p>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.
-</p>
-</li><li> <a href="#perlhacktips-NAME">perlhacktips NAME</a>
-
-<p>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.
-</p>
-<p>If you plan on doing serious C hacking, make sure to read this.
-</p>
-</li><li> <a href="#perlguts-NAME">perlguts NAME</a>
-
-<p>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.
-</p>
-<p>Gisle Aas’s "illustrated perlguts", also known as
<em>illguts</em>, has very
-helpful pictures:
-</p>
-<p><a
href="http://search.cpan.org/dist/illguts/";>http://search.cpan.org/dist/illguts/</a>
-</p>
-</li><li> <a href="perlxstut.html#Top">(perlxstut)</a> and <a
href="perlxs.html#Top">(perlxs)</a>
-
-<p>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.
-</p>
-</li><li> <a href="perlapi.html#Top">(perlapi)</a>
-
-<p>The documentation for the Perl API explains what some of the internal
-functions do, as well as the many macros used in the source.
-</p>
-</li><li> <samp>Porting/pumpkin.pod</samp>
-
-<p>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.
-</p>
-</li></ul>
-
-<hr>
-<a name="perlhack-CPAN-TESTERS-AND-PERL-SMOKERS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-WHAT-NEXT_003f" accesskey="n" rel="next">perlhack
WHAT NEXT?</a>, Previous: <a href="#perlhack-MORE-READING-FOR-GUTS-HACKERS"
accesskey="p" rel="prev">perlhack MORE READING FOR GUTS HACKERS</a>, Up: <a
href="#perlhack" accesskey="u" rel="up">perlhack</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="CPAN-TESTERS-AND-PERL-SMOKERS"></a>
-<h3 class="section">29.10 CPAN TESTERS AND PERL SMOKERS</h3>
-
-<p>The CPAN testers ( http://testers.cpan.org/ ) are a group of volunteers
-who test CPAN modules on a variety of platforms.
-</p>
-<p>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.
-</p>
-<p>Both efforts welcome volunteers. In order to get involved in smoke
-testing of the perl itself visit
-<a
href="http://search.cpan.org/dist/Test-Smoke/";>http://search.cpan.org/dist/Test-Smoke/</a>.
In order to start smoke
-testing CPAN modules visit
-<a
href="http://search.cpan.org/dist/CPANPLUS-YACSmoke/";>http://search.cpan.org/dist/CPANPLUS-YACSmoke/</a>
or
-<a
href="http://search.cpan.org/dist/minismokebox/";>http://search.cpan.org/dist/minismokebox/</a>
or
-<a
href="http://search.cpan.org/dist/CPAN-Reporter/";>http://search.cpan.org/dist/CPAN-Reporter/</a>.
-</p>
-<hr>
-<a name="perlhack-WHAT-NEXT_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-AUTHOR" accesskey="n" rel="next">perlhack AUTHOR</a>,
Previous: <a href="#perlhack-CPAN-TESTERS-AND-PERL-SMOKERS" accesskey="p"
rel="prev">perlhack CPAN TESTERS AND PERL SMOKERS</a>, Up: <a href="#perlhack"
accesskey="u" rel="up">perlhack</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="WHAT-NEXT_003f"></a>
-<h3 class="section">29.11 WHAT NEXT?</h3>
-
-<p>If you’ve read all the documentation in the document and the ones
-listed above, you’re more than ready to hack on Perl.
-</p>
-<p>Here’s some more recommendations
-</p>
-<ul>
-<li> 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...
-
-</li><li> 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.
-
-</li><li> 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
-<samp>perl</samp>’s activity as well, and probably sooner than
you’d think.
-
-</li></ul>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhack-_0022The-Road-goes-ever-on-and-on_002c-down-from-the-door-where-it-began_002e_0022"
accesskey="1">perlhack "The Road goes ever on and on, down from the door
where it began."</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhack-Metaphoric-Quotations" accesskey="2">perlhack Metaphoric
Quotations</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a
name="perlhack-_0022The-Road-goes-ever-on-and-on_002c-down-from-the-door-where-it-began_002e_0022"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhack-Metaphoric-Quotations" accesskey="n"
rel="next">perlhack Metaphoric Quotations</a>, Up: <a
href="#perlhack-WHAT-NEXT_003f" accesskey="u" rel="up">perlhack WHAT NEXT?</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a
name="g_t_0022The-Road-goes-ever-on-and-on_002c-down-from-the-door-where-it-began_002e_0022"></a>
-<h4 class="subsection">29.11.1 "The Road goes ever on and on, down from
the door where it began."</h4>
-
-<p>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!
-</p>
-<hr>
-<a name="perlhack-Metaphoric-Quotations"></a>
-<div class="header">
-<p>
-Previous: <a
href="#perlhack-_0022The-Road-goes-ever-on-and-on_002c-down-from-the-door-where-it-began_002e_0022"
accesskey="p" rel="prev">perlhack "The Road goes ever on and on, down
from the door where it began."</a>, Up: <a href="#perlhack-WHAT-NEXT_003f"
accesskey="u" rel="up">perlhack WHAT NEXT?</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Metaphoric-Quotations"></a>
-<h4 class="subsection">29.11.2 Metaphoric Quotations</h4>
-
-<p>If you recognized the quote about the Road above, you’re in luck.
-</p>
-<p>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.
-</p>
-<p>Like chapters in many books, all top-level Perl source files (along
-with a few others here and there) begin with an epigrammatic
-inscription that alludes, indirectly and metaphorically, to the
-material you’re about to read.
-</p>
-<p>Quotations are taken from writings of J.R.R. Tolkien pertaining to his
-Legendarium, almost always from <em>The Lord of the Rings</em>. Chapters and
-page numbers are given using the following editions:
-</p>
-<ul>
-<li> <em>The Hobbit</em>, 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.
-
-</li><li> <em>The Lord of the Rings</em>, 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.
-
-</li><li> <em>The Lays of Beleriand</em>, 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 <em>History of Middle Earth</em>.
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.
-
-</li></ul>
-
-<p>Other JRRT books fair game for quotes would thus include <em>The
-Adventures of Tom Bombadil</em>, <em>The Silmarillion</em>, <em>Unfinished
Tales</em>,
-and <em>The Tale of the Children of Hurin</em>, all but the first
-posthumously assembled by CJRT. But <em>The Lord of the Rings</em> itself is
-perfectly fine and probably best to quote from, provided you can find a
-suitable quote there.
-</p>
-<p>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.
-</p>
-<hr>
-<a name="perlhack-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhack-WHAT-NEXT_003f" accesskey="p" rel="prev">perlhack
WHAT NEXT?</a>, Up: <a href="#perlhack" accesskey="u" rel="up">perlhack</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-11"></a>
-<h3 class="section">29.12 AUTHOR</h3>
-
-<p>This document was originally written by Nathan Torkington, and is
-maintained by the perl5-porters mailing list.
-</p>
-<hr>
-<a name="perlhacktips"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktut" accesskey="n" rel="next">perlhacktut</a>,
Previous: <a href="#perlhack" accesskey="p" rel="prev">perlhack</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlhacktips-1"></a>
-<h2 class="chapter">30 perlhacktips</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlhacktips-NAME"
accesskey="1">perlhacktips NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhacktips-DESCRIPTION"
accesskey="2">perlhacktips DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-COMMON-PROBLEMS" accesskey="3">perlhacktips COMMON
PROBLEMS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhacktips-DEBUGGING"
accesskey="4">perlhacktips DEBUGGING</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-SOURCE-CODE-STATIC-ANALYSIS" accesskey="5">perlhacktips
SOURCE CODE STATIC ANALYSIS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-MEMORY-DEBUGGERS" accesskey="6">perlhacktips MEMORY
DEBUGGERS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhacktips-PROFILING"
accesskey="7">perlhacktips PROFILING</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-MISCELLANEOUS-TRICKS" accesskey="8">perlhacktips
MISCELLANEOUS TRICKS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhacktips-AUTHOR"
accesskey="9">perlhacktips AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhacktips-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-DESCRIPTION" accesskey="n"
rel="next">perlhacktips DESCRIPTION</a>, Up: <a href="#perlhacktips"
accesskey="u" rel="up">perlhacktips</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-29"></a>
-<h3 class="section">30.1 NAME</h3>
-
-<p>perlhacktips - Tips for Perl core C code hacking
-</p>
-<hr>
-<a name="perlhacktips-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-COMMON-PROBLEMS" accesskey="n"
rel="next">perlhacktips COMMON PROBLEMS</a>, Previous: <a
href="#perlhacktips-NAME" accesskey="p" rel="prev">perlhacktips NAME</a>, Up:
<a href="#perlhacktips" accesskey="u" rel="up">perlhacktips</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-29"></a>
-<h3 class="section">30.2 DESCRIPTION</h3>
-
-<p>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.
-</p>
-<p>If you haven’t read <a href="#perlhack-NAME">perlhack NAME</a> and <a
href="#perlhacktut-NAME">perlhacktut NAME</a> yet, you might want
-to do that first.
-</p>
-<hr>
-<a name="perlhacktips-COMMON-PROBLEMS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-DEBUGGING" accesskey="n" rel="next">perlhacktips
DEBUGGING</a>, Previous: <a href="#perlhacktips-DESCRIPTION" accesskey="p"
rel="prev">perlhacktips DESCRIPTION</a>, Up: <a href="#perlhacktips"
accesskey="u" rel="up">perlhacktips</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="COMMON-PROBLEMS"></a>
-<h3 class="section">30.3 COMMON PROBLEMS</h3>
-
-<p>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.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Perl-environment-problems" accesskey="1">perlhacktips Perl
environment problems</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Portability-problems" accesskey="2">perlhacktips
Portability problems</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Problematic-System-Interfaces" accesskey="3">perlhacktips
Problematic System Interfaces</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Security-problems" accesskey="4">perlhacktips Security
problems</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhacktips-Perl-environment-problems"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-Portability-problems" accesskey="n"
rel="next">perlhacktips Portability problems</a>, Up: <a
href="#perlhacktips-COMMON-PROBLEMS" accesskey="u" rel="up">perlhacktips COMMON
PROBLEMS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Perl-environment-problems"></a>
-<h4 class="subsection">30.3.1 Perl environment problems</h4>
-
-<ul>
-<li> Not compiling with threading
-
-<p>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:
-</p>
-<pre class="verbatim"> Perl_sv_setiv(aTHX_ ...);
- sv_setiv(...);
-</pre>
-<p>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.
-</p>
-<p>See <a
href="#perlguts-How-multiple-interpreters-and-concurrency-are-supported">perlguts
How multiple interpreters and concurrency are supported</a> for further
discussion about context.
-</p>
-</li><li> Not compiling with -DDEBUGGING
-
-<p>The DEBUGGING define exposes more code to the compiler, therefore more
-ways for things to go wrong. You should try it.
-</p>
-</li><li> Introducing (non-read-only) globals
-
-<p>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 <samp>intrpvar.h</samp> (at the very end for binary
-compatibility).
-</p>
-<p>Introducing read-only (const) globals is okay, as long as you verify
-with e.g. <code>nm libperl.a|egrep -v ' [TURtr] '</code> (if your
<code>nm</code> 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.)
-</p>
-<p>If you want to have static strings, make them constant:
-</p>
-<pre class="verbatim"> static const char etc[] = "...";
-</pre>
-<p>If you want to have arrays of constant strings, note carefully the
-right combination of <code>const</code>s:
-</p>
-<pre class="verbatim"> static const char * const yippee[] =
- {"hi", "ho", "silver"};
-</pre>
-<p>There is a way to completely hide any modifiable globals (they are all
-moved to heap), the compilation setting
-<code>-DPERL_GLOBAL_STRUCT_PRIVATE</code>. It is not normally used, but can be
-used for testing, read more about it in <a
href="#perlguts-Background-and-PERL_005fIMPLICIT_005fCONTEXT">perlguts
Background and PERL_IMPLICIT_CONTEXT</a>.
-</p>
-</li><li> Not exporting your new function
-
-<p>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 <samp>embed.pl</samp>
in
-<a href="#perlguts-NAME">perlguts NAME</a>.
-</p>
-</li><li> Exporting your new function
-
-<p>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?
-</p>
-<p>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.
-</p>
-<p>If the function is used only inside one source code file, make it
-static. See the discussion about <samp>embed.pl</samp> in <a
href="#perlguts-NAME">perlguts NAME</a>.
-</p>
-<p>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 <samp>embed.pl</samp> in
-<a href="#perlguts-NAME">perlguts NAME</a>.
-</p>
-</li></ul>
-
-<hr>
-<a name="perlhacktips-Portability-problems"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-Problematic-System-Interfaces" accesskey="n"
rel="next">perlhacktips Problematic System Interfaces</a>, Previous: <a
href="#perlhacktips-Perl-environment-problems" accesskey="p"
rel="prev">perlhacktips Perl environment problems</a>, Up: <a
href="#perlhacktips-COMMON-PROBLEMS" accesskey="u" rel="up">perlhacktips COMMON
PROBLEMS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Portability-problems"></a>
-<h4 class="subsection">30.3.2 Portability problems</h4>
-
-<p>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.
-</p>
-<p>If using gcc, you can add the <code>-std=c89</code> option which will
hopefully
-catch most of these unportabilities. (However it might also catch
-incompatibilities in your system’s header files.)
-</p>
-<p>Use the Configure <code>-Dgccansipedantic</code> flag to enable the gcc
<code>-ansi
--pedantic</code> flags which enforce stricter ANSI rules.
-</p>
-<p>If using the <code>gcc -Wall</code> note that not all the possible warnings
(like
-<code>-Wunitialized</code>) are given unless you also compile with
<code>-O</code>.
-</p>
-<p>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 <code>-std=c89</code>, <code>-ansi</code>,
<code>-pedantic</code>, and a
-selection of <code>-W</code> flags (see cflags.SH).
-</p>
-<p>Also study <a href="#perlport-NAME">perlport NAME</a> carefully to avoid
any bad assumptions about the
-operating system, filesystems, character set, and so forth.
-</p>
-<p>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.)
-</p>
-<p>Do not assume an operating system indicates a certain compiler.
-</p>
-<ul>
-<li> Casting pointers to integers or casting integers to pointers
-
-<pre class="verbatim"> void castaway(U8* p)
- {
- IV i = p;
-</pre>
-<p>or
-</p>
-<pre class="verbatim"> void castaway(U8* p)
- {
- IV i = (IV)p;
-</pre>
-<p>Both are bad, and broken, and unportable. Use the PTR2IV() macro that
-does it right. (Likewise, there are PTR2UV(), PTR2NV(), INT2PTR(), and
-NUM2PTR().)
-</p>
-</li><li> Casting between function pointers and data pointers
-
-<p>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.
-</p>
-</li><li> Assuming sizeof(int) == sizeof(long)
-
-<p>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".)
-</p>
-<p>Instead, use the definitions IV, UV, IVSIZE, I32SIZE, and so forth.
-Avoid things like I32 because they are <strong>not</strong> guaranteed to be
-<em>exactly</em> 32 bits, they are <em>at least</em> 32 bits, nor are they
-guaranteed to be <strong>int</strong> or <strong>long</strong>. If you really
explicitly need
-64-bit variables, use I64 and U64, but only if guarded by HAS_QUAD.
-</p>
-</li><li> Assuming one can dereference any type of pointer for any type of data
-
-<pre class="verbatim"> char *p = ...;
- long pony = *p; /* BAD */
-</pre>
-<p>Many platforms, quite rightly so, will give you a core dump instead of
-a pony if the p happens not to be correctly aligned.
-</p>
-</li><li> Lvalue casts
-
-<pre class="verbatim"> (int)*p = ...; /* BAD */
-</pre>
-<p>Simply not portable. Get your lvalue to be of the right type, or maybe
-use temporary variables, or dirty tricks with unions.
-</p>
-</li><li> Assume <strong>anything</strong> about structs (especially the ones
you don’t
-control, like the ones coming from the system headers)
-
-<ul>
-<li> That a certain field exists in a struct
-
-</li><li> That no other fields exist besides the ones you know of
-
-</li><li> That a field is of certain signedness, sizeof, or type
-
-</li><li> That the fields are in a certain order
-
-<ul>
-<li> While C guarantees the ordering specified in the struct definition,
-between different platforms the definitions might differ
-
-</li></ul>
-
-</li><li> That the sizeof(struct) or the alignments are the same everywhere
-
-<ul>
-<li> There might be padding bytes between the fields to align the fields -
-the bytes can be anything
-
-</li><li> 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
-
-</li></ul>
-
-</li></ul>
-
-</li><li> Assuming the character set is ASCIIish
-
-<p>Perl can compile and run under EBCDIC platforms. See <a
href="#perlebcdic-NAME">perlebcdic NAME</a>.
-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 <code>'A'</code>, but not
<code>0x41</code>.
-You can safely say <code>'\n'</code>, but not <code>\012</code>. However, you
can use
-macros defined in <samp>utf8.h</samp> to specify any code point portably.
-<code>LATIN1_TO_NATIVE(0xDF)</code> is going to be the code point that means
-LATIN SMALL LETTER SHARP S on whatever platform you are running on (on
-ASCII platforms it compiles without adding any extra code, so there is
-zero performance hit on those). The acceptable inputs to
-<code>LATIN1_TO_NATIVE</code> are from <code>0x00</code> through
<code>0xFF</code>. If your input
-isn’t guaranteed to be in that range, use <code>UNICODE_TO_NATIVE</code>
instead.
-<code>NATIVE_TO_LATIN1</code> and <code>NATIVE_TO_UNICODE</code> translate the
opposite
-direction.
-</p>
-<p>If you need the string representation of a character that doesn’t
have a
-mnemonic name in C, you should add it to the list in
-<samp>regen/unicode_constants.pl</samp>, and have Perl create
<code>#define</code>’s for you,
-based on the current platform.
-</p>
-<p>Note that the <code>is<em>FOO</em></code> and <code>to<em>FOO</em></code>
macros in <samp>handy.h</samp> work
-properly on native code points and strings.
-</p>
-<p>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. (Note that special handling of ranges in
-regular expression patterns makes it appear to Perl
-code that the aforementioned ranges are all unbroken.)
-</p>
-<p>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.
-</p>
-<p>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 <samp>utf8.h</samp> and
<samp>utfebcdic.h</samp> are used to
-allow the calling code to think that there is only one such encoding.
-This is almost always referred to as <code>utf8</code>, 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 UTF-8 <code>invariant
-characters</code> 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, <code>hibit</code>. The situation differs and is not so simple on
-EBCDIC machines, but as long as the code itself uses the
-<code>NATIVE_IS_INVARIANT()</code> macro appropriately, it works, even if the
-comments are wrong.
-</p>
-<p>As noted in <a href="#perlhack-TESTING">perlhack TESTING</a>, when writing
test scripts, the file
-<samp>t/charset_tools.pl</samp> contains some helpful functions for writing
tests
-valid on both ASCII and EBCDIC platforms. Sometimes, though, a test
-can’t use a function and it’s inconvenient to have different test
-versions depending on the platform. There are 20 code points that are
-the same in all 4 character sets currently recognized by Perl (the 3
-EBCDIC code pages plus ISO 8859-1 (ASCII/Latin1)). These can be used in
-such tests, though there is a small possibility that Perl will become
-available in yet another character set, breaking your test. All but one
-of these code points are C0 control characters. The most significant
-controls that are the same are <code>\0</code>, <code>\r</code>, and
<code>\N{VT}</code> (also
-specifiable as <code>\cK</code>, <code>\x0B</code>, <code>\N{U+0B}</code>, or
<code>\013</code>). The single
-non-control is U+00B6 PILCROW SIGN. The controls that are the same have
-the same bit pattern in all 4 character sets, regardless of the UTF8ness
-of the string containing them. The bit pattern for U+B6 is the same in
-all 4 for non-UTF8 strings, but differs in each when its containing
-string is UTF-8 encoded. The only other code points that have some sort
-of sameness across all 4 character sets are the pair 0xDC and 0xFC.
-Together these represent upper- and lowercase LATIN LETTER U WITH
-DIAERESIS, but which is upper and which is lower may be reversed: 0xDC
-is the capital in Latin1 and 0xFC is the small letter, while 0xFC is the
-capital in EBCDIC and 0xDC is the small one. This factoid may be
-exploited in writing case insensitive tests that are the same across all
-4 character sets.
-</p>
-</li><li> Assuming the character set is just ASCII
-
-<p>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 has being
-changed starting in 5.12 so that these characters can be considered to
-be Latin-1 (ISO-8859-1).
-</p>
-</li><li> Mixing #define and #ifdef
-
-<pre class="verbatim"> #define BURGLE(x) ... \
- #ifdef BURGLE_OLD_STYLE /* BAD */
- ... do it the old way ... \
- #else
- ... do it the new way ... \
- #endif
-</pre>
-<p>You cannot portably "stack" cpp directives. For example in the
above
-you need two separate BURGLE() #defines, one for each #ifdef branch.
-</p>
-</li><li> Adding non-comment stuff after #endif or #else
-
-<pre class="verbatim"> #ifdef SNOSH
- ...
- #else !SNOSH /* BAD */
- ...
- #endif SNOSH /* BAD */
-</pre>
-<p>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:
-</p>
-<pre class="verbatim"> #ifdef SNOSH
- ...
- #else /* !SNOSH */
- ...
- #endif /* SNOSH */
-</pre>
-<p>The gcc option <code>-Wendif-labels</code> warns about the bad variant (by
-default on starting from Perl 5.9.4).
-</p>
-</li><li> Having a comma after the last element of an enum list
-
-<pre class="verbatim"> enum color {
- CERULEAN,
- CHARTREUSE,
- CINNABAR, /* BAD */
- };
-</pre>
-<p>is not portable. Leave out the last comma.
-</p>
-<p>Also note that whether enums are implicitly morphable to ints varies
-between compilers, you might need to (int).
-</p>
-</li><li> Using //-comments
-
-<pre class="verbatim"> // This function bamfoodles the zorklator. /* BAD */
-</pre>
-<p>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.
-</p>
-</li><li> Mixing declarations and code
-
-<pre class="verbatim"> void zorklator()
- {
- int n = 3;
- set_zorkmids(n); /* BAD */
- int q = 4;
-</pre>
-<p>That is C99 or C++. Some C compilers allow that, but you shouldn’t.
-</p>
-<p>The gcc option <code>-Wdeclaration-after-statements</code> scans for such
-problems (by default on starting from Perl 5.9.4).
-</p>
-</li><li> Introducing variables inside for()
-
-<pre class="verbatim"> for(int i = ...; ...; ...) { /* BAD */
-</pre>
-<p>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.
-</p>
-</li><li> Mixing signed char pointers with unsigned char pointers
-
-<pre class="verbatim"> int foo(char *s) { ... }
- ...
- unsigned char *t = ...; /* Or U8* t = ... */
- foo(t); /* BAD */
-</pre>
-<p>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.
-</p>
-</li><li> Macros that have string constants and their arguments as substrings
of
-the string constants
-
-<pre class="verbatim"> #define FOO(n) printf("number = %d\n", n)
/* BAD */
- FOO(10);
-</pre>
-<p>Pre-ANSI semantics for that was equivalent to
-</p>
-<pre class="verbatim"> printf("10umber = %d\10");
-</pre>
-<p>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.
-</p>
-</li><li> Using printf formats for non-basic C types
-
-<pre class="verbatim"> IV i = ...;
- printf("i = %d\n", i); /* BAD */
-</pre>
-<p>While this might by accident work in some platform (where IV happens to
-be an <code>int</code>), 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 <samp>config.h</samp>):
-</p>
-<pre class="verbatim"> Uid_t who = ...;
- printf("who = %d\n", who); /* BAD */
-</pre>
-<p>The problem here is that Uid_t might be not only not <code>int</code>-wide
but it
-might also be unsigned, in which case large uids would be printed as
-negative values.
-</p>
-<p>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:
-</p>
-<pre class="verbatim"> 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);
-</pre>
-<p>Or you can try casting to a "wide enough" type:
-</p>
-<pre class="verbatim"> printf("i = %"IVdf"\n",
(IV)something_very_small_and_signed);
-</pre>
-<p>Also remember that the <code>%p</code> format really does require a void
pointer:
-</p>
-<pre class="verbatim"> U8* p = ...;
- printf("p = %p\n", (void*)p);
-</pre>
-<p>The gcc option <code>-Wformat</code> scans for such problems.
-</p>
-</li><li> Blindly using variadic macros
-
-<p>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.
-</p>
-</li><li> Blindly passing va_list
-
-<p>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.
-</p>
-</li><li> Using gcc statement expressions
-
-<pre class="verbatim"> val = ({...;...;...}); /* BAD */
-</pre>
-<p>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.
-</p>
-</li><li> Binding together several statements in a macro
-
-<p>Use the macros STMT_START and STMT_END.
-</p>
-<pre class="verbatim"> STMT_START {
- ...
- } STMT_END
-</pre>
-</li><li> Testing for operating systems or versions when should be testing for
-features
-
-<pre class="verbatim"> #ifdef __FOONIX__ /* BAD */
- foo = quux();
- #endif
-</pre>
-<p>Unless you know with 100% certainty that quux() is only ever available
-for the "Foonix" operating system <strong>and</strong> that is
available <strong>and</strong>
-correctly working for <strong>all</strong> past, present, <strong>and</strong>
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):
-</p>
-<pre class="verbatim"> #ifdef HAS_QUUX
- foo = quux();
- #endif
-</pre>
-<p>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.
-</p>
-<p>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:
-</p>
-<pre class="verbatim"> #if (defined(__FOONIX__) || defined(__BARNIX__))
- # define HAS_QUUX
- #endif
-
- ...
-
- #ifdef HAS_QUUX
- foo = quux();
- #endif
-</pre>
-<p>But in any case, try to keep the features and operating systems
-separate.
-</p>
-</li><li> Assuming the contents of static memory pointed to by the return
values
-of Perl wrappers for C library functions doesn’t change. Many C library
-functions return pointers to static storage that can be overwritten by
-subsequent calls to the same or related functions. Perl has
-light-weight wrappers for some of these functions, and which don’t make
-copies of the static memory. A good example is the interface to the
-environment variables that are in effect for the program. Perl has
-<code>PerlEnv_getenv</code> to get values from the environment. But the
return is
-a pointer to static memory in the C library. If you are using the value
-to immediately test for something, that’s fine, but if you save the
-value and expect it to be unchanged by later processing, you would be
-wrong, but perhaps you wouldn’t know it because different C library
-implementations behave differently, and the one on the platform you’re
-testing on might work for your situation. But on some platforms, a
-subsequent call to <code>PerlEnv_getenv</code> or related function WILL
overwrite
-the memory that your first call points to. This has led to some
-hard-to-debug problems. Do a <a
href="perlapi.html#savepv">(perlapi)savepv</a> to make a copy, thus
-avoiding these problems. You will have to free the copy when you’re
-done to avoid memory leaks. If you don’t have control over when it gets
-freed, you’ll need to make the copy in a mortal scalar, like so:
-
-<pre class="verbatim"> if ((s = PerlEnv_getenv("foo") == NULL) {
- ... /* handle NULL case */
- }
- else {
- s = SvPVX(sv_2mortal(newSVpv(s, 0)));
- }
-</pre>
-<p>The above example works only if <code>"s"</code> is
<code>NUL</code>-terminated; otherwise
-you have to pass its length to <code>newSVpv</code>.
-</p>
-</li></ul>
-
-<hr>
-<a name="perlhacktips-Problematic-System-Interfaces"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-Security-problems" accesskey="n"
rel="next">perlhacktips Security problems</a>, Previous: <a
href="#perlhacktips-Portability-problems" accesskey="p" rel="prev">perlhacktips
Portability problems</a>, Up: <a href="#perlhacktips-COMMON-PROBLEMS"
accesskey="u" rel="up">perlhacktips COMMON PROBLEMS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Problematic-System-Interfaces"></a>
-<h4 class="subsection">30.3.3 Problematic System Interfaces</h4>
-
-<ul>
-<li> 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.)
-
-</li><li> snprintf() - the return type is unportable. Use my_snprintf()
instead.
-
-</li></ul>
-
-<hr>
-<a name="perlhacktips-Security-problems"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhacktips-Problematic-System-Interfaces" accesskey="p"
rel="prev">perlhacktips Problematic System Interfaces</a>, Up: <a
href="#perlhacktips-COMMON-PROBLEMS" accesskey="u" rel="up">perlhacktips COMMON
PROBLEMS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Security-problems"></a>
-<h4 class="subsection">30.3.4 Security problems</h4>
-
-<p>Last but not least, here are various tips for safer coding.
-See also <a href="#perlclib-NAME">perlclib NAME</a> for libc/stdio
replacements one should use.
-</p>
-<ul>
-<li> Do not use gets()
-
-<p>Or we will publicly ridicule you. Seriously.
-</p>
-</li><li> Do not use tmpfile()
-
-<p>Use mkstemp() instead.
-</p>
-</li><li> Do not use strcpy() or strcat() or strncpy() or strncat()
-
-<p>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).
-</p>
-</li><li> Do not use sprintf() or vsprintf()
-
-<p>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
-<a href="perlapi.html#form">(perlapi)<code>Perl_form</code>()</a> or SVs and
-<a
href="perlapi.html#sv_005fcatpvf">(perlapi)<code>Perl_sv_catpvf()</code></a>.
-</p>
-<p>Note that glibc <code>printf()</code>, <code>sprintf()</code>, etc. are
buggy before glibc
-version 2.17. They won’t allow a <code>%.s</code> format with a
precision to
-create a string that isn’t valid UTF-8 if the current underlying locale
-of the program is UTF-8. What happens is that the <code>%s</code> and its
operand are
-simply skipped without any notice.
-<a
href="https://sourceware.org/bugzilla/show_bug.cgi?id=6530";>https://sourceware.org/bugzilla/show_bug.cgi?id=6530</a>.
-</p>
-</li><li> Do not use atoi()
-
-<p>Use grok_atoUV() instead. atoi() has ill-defined behavior on overflows,
-and cannot be used for incremental parsing. It is also affected by locale,
-which is bad.
-</p>
-</li><li> Do not use strtol() or strtoul()
-
-<p>Use grok_atoUV() instead. strtol() or strtoul() (or their IV/UV-friendly
-macro disguises, Strtol() and Strtoul(), or Atol() and Atoul() are
-affected by locale, which is bad.
-</p>
-</li></ul>
-
-<hr>
-<a name="perlhacktips-DEBUGGING"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-SOURCE-CODE-STATIC-ANALYSIS" accesskey="n"
rel="next">perlhacktips SOURCE CODE STATIC ANALYSIS</a>, Previous: <a
href="#perlhacktips-COMMON-PROBLEMS" accesskey="p" rel="prev">perlhacktips
COMMON PROBLEMS</a>, Up: <a href="#perlhacktips" accesskey="u"
rel="up">perlhacktips</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DEBUGGING-1"></a>
-<h3 class="section">30.4 DEBUGGING</h3>
-
-<p>You can compile a special debugging version of Perl, which allows you
-to use the <code>-D</code> 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.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Poking-at-Perl" accesskey="1">perlhacktips Poking at
Perl</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Using-a-source_002dlevel-debugger"
accesskey="2">perlhacktips Using a source-level
debugger</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-gdb-macro-support" accesskey="3">perlhacktips gdb macro
support</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Dumping-Perl-Data-Structures" accesskey="4">perlhacktips
Dumping Perl Data Structures</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Using-gdb-to-look-at-specific-parts-of-a-program"
accesskey="5">perlhacktips Using gdb to look at specific parts of a
program</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Using-gdb-to-look-at-what-the-parser_002flexer-are-doing"
accesskey="6">perlhacktips Using gdb to look at what the parser/lexer are
doing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhacktips-Poking-at-Perl"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-Using-a-source_002dlevel-debugger" accesskey="n"
rel="next">perlhacktips Using a source-level debugger</a>, Up: <a
href="#perlhacktips-DEBUGGING" accesskey="u" rel="up">perlhacktips
DEBUGGING</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Poking-at-Perl"></a>
-<h4 class="subsection">30.4.1 Poking at Perl</h4>
-
-<p>To really poke around with Perl, you’ll probably want to build Perl
for
-debugging, like this:
-</p>
-<pre class="verbatim"> ./Configure -d -D optimize=-g
- make
-</pre>
-<p><code>-g</code> 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).
-</p>
-<p><samp>Configure</samp> will also turn on the <code>DEBUGGING</code>
compilation symbol
-which enables all the internal debugging code in Perl. There are a
-whole bunch of things you can debug with this: <a href="#perlrun-NAME">perlrun
NAME</a> lists them
-all, and the best way to find out about them is to play about with
-them. The most useful options are probably
-</p>
-<pre class="verbatim"> l Context (loop) stack processing
- t Trace execution
- o Method and overloading resolution
- c String/numeric conversions
-</pre>
-<p>Some of the functionality of the debugging code can be achieved using
-XS modules.
-</p>
-<pre class="verbatim"> -Dr => use re 'debug'
- -Dx => use O 'Debug'
-</pre>
-<hr>
-<a name="perlhacktips-Using-a-source_002dlevel-debugger"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-gdb-macro-support" accesskey="n"
rel="next">perlhacktips gdb macro support</a>, Previous: <a
href="#perlhacktips-Poking-at-Perl" accesskey="p" rel="prev">perlhacktips
Poking at Perl</a>, Up: <a href="#perlhacktips-DEBUGGING" accesskey="u"
rel="up">perlhacktips DEBUGGING</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-a-source_002dlevel-debugger"></a>
-<h4 class="subsection">30.4.2 Using a source-level debugger</h4>
-
-<p>If the debugging output of <code>-D</code> doesn’t help you,
it’s time to step
-through perl’s execution with a source-level debugger.
-</p>
-<ul>
-<li> We’ll use <code>gdb</code> for our examples here; the principles
will apply to
-any debugger (many vendors call their debugger <code>dbx</code>), but check the
-manual of the one you’re using.
-
-</li></ul>
-
-<p>To fire up the debugger, type
-</p>
-<pre class="verbatim"> gdb ./perl
-</pre>
-<p>Or if you have a core dump:
-</p>
-<pre class="verbatim"> gdb ./perl core
-</pre>
-<p>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.
-</p>
-<pre class="verbatim"> (gdb)
-</pre>
-<p><code>help</code> will get you into the documentation, but here are the most
-useful commands:
-</p>
-<ul>
-<li> run [args]
-
-<p>Run the program with the given arguments.
-</p>
-</li><li> break function_name
-
-</li><li> break source.c:xxx
-
-<p>Tells the debugger that we’ll want to pause execution when we reach
-either the named function (but see <a
href="#perlguts-Internal-Functions">perlguts Internal Functions</a>!) or
-the given line in the named source file.
-</p>
-</li><li> step
-
-<p>Steps through the program a line at a time.
-</p>
-</li><li> next
-
-<p>Steps through the program a line at a time, without descending into
-functions.
-</p>
-</li><li> continue
-
-<p>Run until the next breakpoint.
-</p>
-</li><li> finish
-
-<p>Run until the end of the current function, then stop again.
-</p>
-</li><li> ’enter’
-
-<p>Just pressing Enter will do the most recent operation again - it’s a
-blessing when stepping through miles of source code.
-</p>
-</li><li> ptype
-
-<p>Prints the C definition of the argument given.
-</p>
-<pre class="verbatim"> (gdb) ptype PL_op
- type = struct op {
- OP *op_next;
- OP *op_sibparent;
- OP *(*op_ppaddr)(void);
- PADOFFSET op_targ;
- unsigned int op_type : 9;
- unsigned int op_opt : 1;
- unsigned int op_slabbed : 1;
- unsigned int op_savefree : 1;
- unsigned int op_static : 1;
- unsigned int op_folded : 1;
- unsigned int op_spare : 2;
- U8 op_flags;
- U8 op_private;
- } *
-</pre>
-</li><li> print
-
-<p>Execute the given C code and print its results. <strong>WARNING</strong>:
Perl makes
-heavy use of macros, and <samp>gdb</samp> does not necessarily support macros
-(see later <a href="#perlhacktips-gdb-macro-support">gdb macro support</a>).
You’ll have to substitute them
-yourself, or to invoke cpp on the source code files (see <a
href="#perlhacktips-The-_002ei-Targets">The .i
-Targets</a>) So, for instance, you can’t say
-</p>
-<pre class="verbatim"> print SvPV_nolen(sv)
-</pre>
-<p>but you have to say
-</p>
-<pre class="verbatim"> print Perl_sv_2pv_nolen(sv)
-</pre>
-</li></ul>
-
-<p>You may find it helpful to have a "macro dictionary", which you
can
-produce by saying <code>cpp -dM perl.c | sort</code>. Even then,
<samp>cpp</samp> won’t
-recursively apply those macros for you.
-</p>
-<hr>
-<a name="perlhacktips-gdb-macro-support"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-Dumping-Perl-Data-Structures" accesskey="n"
rel="next">perlhacktips Dumping Perl Data Structures</a>, Previous: <a
href="#perlhacktips-Using-a-source_002dlevel-debugger" accesskey="p"
rel="prev">perlhacktips Using a source-level debugger</a>, Up: <a
href="#perlhacktips-DEBUGGING" accesskey="u" rel="up">perlhacktips
DEBUGGING</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="gdb-macro-support"></a>
-<h4 class="subsection">30.4.3 gdb macro support</h4>
-
-<p>Recent versions of <samp>gdb</samp> 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 <samp>gcc</samp> version 3.1, this means
-configuring with <code>-Doptimize=-g3</code>. Other compilers might use a
-different switch (if they support debugging macros at all).
-</p>
-<hr>
-<a name="perlhacktips-Dumping-Perl-Data-Structures"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-Using-gdb-to-look-at-specific-parts-of-a-program"
accesskey="n" rel="next">perlhacktips Using gdb to look at specific parts of a
program</a>, Previous: <a href="#perlhacktips-gdb-macro-support" accesskey="p"
rel="prev">perlhacktips gdb macro support</a>, Up: <a
href="#perlhacktips-DEBUGGING" accesskey="u" rel="up">perlhacktips
DEBUGGING</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Dumping-Perl-Data-Structures"></a>
-<h4 class="subsection">30.4.4 Dumping Perl Data Structures</h4>
-
-<p>One way to get around this macro hell is to use the dumping functions
-in <samp>dump.c</samp>; these work a little like an internal
-<a href="Devel-Peek.html#Top">(Devel-Peek)Devel::Peek</a>, 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 <code>$a = $b + $c</code> we used before, but give it a
bit of
-context: <code>$b = "6XXXX"; $c = 2.3;</code>. Where’s a good
place to stop and
-poke around?
-</p>
-<p>What about <code>pp_add</code>, the function we examined earlier to
implement the
-<code>+</code> operator:
-</p>
-<pre class="verbatim"> (gdb) break Perl_pp_add
- Breakpoint 1 at 0x46249f: file pp_hot.c, line 309.
-</pre>
-<p>Notice we use <code>Perl_pp_add</code> and not <code>pp_add</code> - see
-<a href="#perlguts-Internal-Functions">perlguts Internal Functions</a>. With
the breakpoint in place, we can
-run our program:
-</p>
-<pre class="verbatim"> (gdb) run -e '$b = "6XXXX"; $c = 2.3; $a =
$b + $c'
-</pre>
-<p>Lots of junk will go past as gdb reads in the relevant source files and
-libraries, and then:
-</p>
-<pre class="verbatim"> Breakpoint 1, Perl_pp_add () at pp_hot.c:309
- 309 dSP; dATARGET; tryAMAGICbin(add,opASSIGN);
- (gdb) step
- 311 dPOPTOPnnrl_ul;
- (gdb)
-</pre>
-<p>We looked at this bit of code before, and we said that
-<code>dPOPTOPnnrl_ul</code> arranges for two <code>NV</code>s to be placed
into <code>left</code> and
-<code>right</code> - let’s slightly expand it:
-</p>
-<pre class="verbatim"> #define dPOPTOPnnrl_ul NV right = POPn; \
- SV *leftsv = TOPs; \
- NV left = USE_LEFT(leftsv) ? SvNV(leftsv) : 0.0
-</pre>
-<p><code>POPn</code> takes the SV from the top of the stack and obtains its NV
-either directly (if <code>SvNOK</code> is set) or by calling the
<code>sv_2nv</code>
-function. <code>TOPs</code> takes the next SV from the top of the stack - yes,
-<code>POPn</code> uses <code>TOPs</code> - but doesn’t remove it. We
then use <code>SvNV</code> to
-get the NV from <code>leftsv</code> in the same way as before - yes,
<code>POPn</code> uses
-<code>SvNV</code>.
-</p>
-<p>Since we don’t have an NV for <code>$b</code>, we’ll have to
use <code>sv_2nv</code> to
-convert it. If we step again, we’ll find ourselves there:
-</p>
-<pre class="verbatim"> (gdb) step
- Perl_sv_2nv (sv=0xa0675d0) at sv.c:1669
- 1669 if (!sv)
- (gdb)
-</pre>
-<p>We can now use <code>Perl_sv_dump</code> to investigate the SV:
-</p>
-<pre class="verbatim"> (gdb) print Perl_sv_dump(sv)
- SV = PV(0xa057cc0) at 0xa0675d0
- REFCNT = 1
- FLAGS = (POK,pPOK)
- PV = 0xa06a510 "6XXXX"\0
- CUR = 5
- LEN = 6
- $1 = void
-</pre>
-<p>We know we’re going to get <code>6</code> from this, so let’s
finish the
-subroutine:
-</p>
-<pre class="verbatim"> (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;
-</pre>
-<p>We can also dump out this op: the current op is always stored in
-<code>PL_op</code>, and we can dump it with <code>Perl_op_dump</code>.
This’ll give us
-similar output to <a href="B-Debug.html#Top">(B-Debug)B::Debug</a>.
-</p>
-<pre class="verbatim"> (gdb) print Perl_op_dump(PL_op)
- {
- 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
- }
- }
-</pre>
-<p># finish this later #
-</p>
-<hr>
-<a name="perlhacktips-Using-gdb-to-look-at-specific-parts-of-a-program"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlhacktips-Using-gdb-to-look-at-what-the-parser_002flexer-are-doing"
accesskey="n" rel="next">perlhacktips Using gdb to look at what the
parser/lexer are doing</a>, Previous: <a
href="#perlhacktips-Dumping-Perl-Data-Structures" accesskey="p"
rel="prev">perlhacktips Dumping Perl Data Structures</a>, Up: <a
href="#perlhacktips-DEBUGGING" accesskey="u" rel="up">perlhacktips
DEBUGGING</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-gdb-to-look-at-specific-parts-of-a-program"></a>
-<h4 class="subsection">30.4.5 Using gdb to look at specific parts of a
program</h4>
-
-<p>With the example above, you knew to look for <code>Perl_pp_add</code>, but
what if
-there were multiple calls to it all over the place, or you didn’t know
what
-the op was you were looking for?
-</p>
-<p>One way to do this is to inject a rare call somewhere near what
you’re looking
-for. For example, you could add <code>study</code> before your method:
-</p>
-<pre class="verbatim"> study;
-</pre>
-<p>And in gdb do:
-</p>
-<pre class="verbatim"> (gdb) break Perl_pp_study
-</pre>
-<p>And then step until you hit what you’re
-looking for. This works well in a loop
-if you want to only break at certain iterations:
-</p>
-<pre class="verbatim"> for my $c (1..100) {
- study if $c == 50;
- }
-</pre>
-<hr>
-<a
name="perlhacktips-Using-gdb-to-look-at-what-the-parser_002flexer-are-doing"></a>
-<div class="header">
-<p>
-Previous: <a
href="#perlhacktips-Using-gdb-to-look-at-specific-parts-of-a-program"
accesskey="p" rel="prev">perlhacktips Using gdb to look at specific parts of a
program</a>, Up: <a href="#perlhacktips-DEBUGGING" accesskey="u"
rel="up">perlhacktips DEBUGGING</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-gdb-to-look-at-what-the-parser_002flexer-are-doing"></a>
-<h4 class="subsection">30.4.6 Using gdb to look at what the parser/lexer are
doing</h4>
-
-<p>If you want to see what perl is doing when parsing/lexing your code, you
can
-use <code>BEGIN {}</code>:
-</p>
-<pre class="verbatim"> print "Before\n";
- BEGIN { study; }
- print "After\n";
-</pre>
-<p>And in gdb:
-</p>
-<pre class="verbatim"> (gdb) break Perl_pp_study
-</pre>
-<p>If you want to see what the parser/lexer is doing inside of <code>if</code>
blocks and
-the like you need to be a little trickier:
-</p>
-<pre class="verbatim"> if ($a && $b && do { BEGIN { study }
1 } && $c) { ... }
-</pre>
-<hr>
-<a name="perlhacktips-SOURCE-CODE-STATIC-ANALYSIS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-MEMORY-DEBUGGERS" accesskey="n"
rel="next">perlhacktips MEMORY DEBUGGERS</a>, Previous: <a
href="#perlhacktips-DEBUGGING" accesskey="p" rel="prev">perlhacktips
DEBUGGING</a>, Up: <a href="#perlhacktips" accesskey="u"
rel="up">perlhacktips</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SOURCE-CODE-STATIC-ANALYSIS"></a>
-<h3 class="section">30.5 SOURCE CODE STATIC ANALYSIS</h3>
-
-<p>Various tools exist for analysing C source code
<strong>statically</strong>, as
-opposed to <strong>dynamically</strong>, 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.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-lint_002c-splint" accesskey="1">perlhacktips lint,
splint</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhacktips-Coverity"
accesskey="2">perlhacktips Coverity</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-cpd-_0028cut_002dand_002dpaste-detector_0029"
accesskey="3">perlhacktips cpd (cut-and-paste
detector)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhacktips-gcc-warnings"
accesskey="4">perlhacktips gcc warnings</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Warnings-of-other-C-compilers" accesskey="5">perlhacktips
Warnings of other C compilers</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhacktips-lint_002c-splint"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-Coverity" accesskey="n" rel="next">perlhacktips
Coverity</a>, Up: <a href="#perlhacktips-SOURCE-CODE-STATIC-ANALYSIS"
accesskey="u" rel="up">perlhacktips SOURCE CODE STATIC ANALYSIS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="lint_002c-splint"></a>
-<h4 class="subsection">30.5.1 lint, splint</h4>
-
-<p>The good old C code quality inspector, <code>lint</code>, 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.
-</p>
-<p>There is a lint variant called <code>splint</code> (Secure Programming Lint)
-available from http://www.splint.org/ that should compile on any
-Unix-like platform.
-</p>
-<p>There are <code>lint</code> and <splint> targets in Makefile, but you
may have to
-diddle with the flags (see above).
-</p>
-<hr>
-<a name="perlhacktips-Coverity"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-cpd-_0028cut_002dand_002dpaste-detector_0029"
accesskey="n" rel="next">perlhacktips cpd (cut-and-paste detector)</a>,
Previous: <a href="#perlhacktips-lint_002c-splint" accesskey="p"
rel="prev">perlhacktips lint, splint</a>, Up: <a
href="#perlhacktips-SOURCE-CODE-STATIC-ANALYSIS" accesskey="u"
rel="up">perlhacktips SOURCE CODE STATIC ANALYSIS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Coverity"></a>
-<h4 class="subsection">30.5.2 Coverity</h4>
-
-<p>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.
-</p>
-<hr>
-<a name="perlhacktips-cpd-_0028cut_002dand_002dpaste-detector_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-gcc-warnings" accesskey="n"
rel="next">perlhacktips gcc warnings</a>, Previous: <a
href="#perlhacktips-Coverity" accesskey="p" rel="prev">perlhacktips
Coverity</a>, Up: <a href="#perlhacktips-SOURCE-CODE-STATIC-ANALYSIS"
accesskey="u" rel="up">perlhacktips SOURCE CODE STATIC ANALYSIS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="cpd-_0028cut_002dand_002dpaste-detector_0029"></a>
-<h4 class="subsection">30.5.3 cpd (cut-and-paste detector)</h4>
-
-<p>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.
-</p>
-<p>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++.
-</p>
-<p>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:
-</p>
-<pre class="verbatim"> java -cp pmd-X.Y.jar net.sourceforge.pmd.cpd.CPD \
- --minimum-tokens 100 --files /some/where/src --language c > cpd.txt
-</pre>
-<p>You may run into memory limits, in which case you should use the -Xmx
-option:
-</p>
-<pre class="verbatim"> java -Xmx512M ...
-</pre>
-<hr>
-<a name="perlhacktips-gcc-warnings"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-Warnings-of-other-C-compilers" accesskey="n"
rel="next">perlhacktips Warnings of other C compilers</a>, Previous: <a
href="#perlhacktips-cpd-_0028cut_002dand_002dpaste-detector_0029" accesskey="p"
rel="prev">perlhacktips cpd (cut-and-paste detector)</a>, Up: <a
href="#perlhacktips-SOURCE-CODE-STATIC-ANALYSIS" accesskey="u"
rel="up">perlhacktips SOURCE CODE STATIC ANALYSIS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="gcc-warnings"></a>
-<h4 class="subsection">30.5.4 gcc warnings</h4>
-
-<p>Though much can be written about the inconsistency and coverage
-problems of gcc warnings (like <code>-Wall</code> not meaning "all the
warnings",
-or some common portability problems not being covered by <code>-Wall</code>, or
-<code>-ansi</code> and <code>-pedantic</code> both being a poorly defined
collection of
-warnings, and so forth), gcc is still a useful tool in keeping our
-coding nose clean.
-</p>
-<p>The <code>-Wall</code> is by default on.
-</p>
-<p>The <code>-ansi</code> (and its sidekick, <code>-pedantic</code>) 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 <code>-Dgccansipedantic</code> is used,
the
-<code>cflags</code> frontend selects <code>-ansi -pedantic</code> for the
platforms where
-they are known to be safe.
-</p>
-<p>Starting from Perl 5.9.4 the following extra flags are added:
-</p>
-<ul>
-<li> <code>-Wendif-labels</code>
-
-</li><li> <code>-Wextra</code>
-
-</li><li> <code>-Wdeclaration-after-statement</code>
-
-</li></ul>
-
-<p>The following flags would be nice to have but they would first need
-their own Augean stablemaster:
-</p>
-<ul>
-<li> <code>-Wpointer-arith</code>
-
-</li><li> <code>-Wshadow</code>
-
-</li><li> <code>-Wstrict-prototypes</code>
-
-</li></ul>
-
-<p>The <code>-Wtraditional</code> 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.
-</p>
-<hr>
-<a name="perlhacktips-Warnings-of-other-C-compilers"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhacktips-gcc-warnings" accesskey="p"
rel="prev">perlhacktips gcc warnings</a>, Up: <a
href="#perlhacktips-SOURCE-CODE-STATIC-ANALYSIS" accesskey="u"
rel="up">perlhacktips SOURCE CODE STATIC ANALYSIS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Warnings-of-other-C-compilers"></a>
-<h4 class="subsection">30.5.5 Warnings of other C compilers</h4>
-
-<p>Other C compilers (yes, there <strong>are</strong> 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
<code>-Xa</code>
-mode on (though implicitly), or the DEC (these days, HP...) has its
-<code>-std1</code> mode on.
-</p>
-<hr>
-<a name="perlhacktips-MEMORY-DEBUGGERS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-PROFILING" accesskey="n" rel="next">perlhacktips
PROFILING</a>, Previous: <a href="#perlhacktips-SOURCE-CODE-STATIC-ANALYSIS"
accesskey="p" rel="prev">perlhacktips SOURCE CODE STATIC ANALYSIS</a>, Up: <a
href="#perlhacktips" accesskey="u" rel="up">perlhacktips</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="MEMORY-DEBUGGERS"></a>
-<h3 class="section">30.6 MEMORY DEBUGGERS</h3>
-
-<p><strong>NOTE 1</strong>: Running under older memory debuggers such as
Purify,
-valgrind or Third Degree greatly slows down the execution: seconds
-become minutes, minutes become hours. For example as of Perl 5.8.1, the
-ext/Encode/t/Unicode.t takes extraordinarily long to complete under
-e.g. Purify, Third Degree, and valgrind. Under valgrind it takes more
-than six hours, even on a snappy computer. The said test must be doing
-something that is quite unfriendly for memory debuggers. If you don’t
-feel like waiting, that you can simply kill away the perl process.
-Roughly valgrind slows down execution by factor 10, AddressSanitizer by
-factor 2.
-</p>
-<p><strong>NOTE 2</strong>: To minimize the number of memory leak false alarms
(see
-<a href="#perlhacktips-PERL_005fDESTRUCT_005fLEVEL">PERL_DESTRUCT_LEVEL</a>
for more information), you have to set the
-environment variable PERL_DESTRUCT_LEVEL to 2. For example, like this:
-</p>
-<pre class="verbatim"> env PERL_DESTRUCT_LEVEL=2 valgrind ./perl -Ilib ...
-</pre>
-<p><strong>NOTE 3</strong>: There are known memory leaks when there are
compile-time
-errors within eval or require, seeing <code>S_doeval</code> in the call stack
is
-a good sign of these. Fixing these leaks is non-trivial, unfortunately,
-but they must be fixed eventually.
-</p>
-<p><strong>NOTE 4</strong>: <a href="DynaLoader.html#Top">(DynaLoader)</a>
will not clean up after itself completely
-unless Perl is built with the Configure option
-<code>-Accflags=-DDL_UNLOAD_ALL_AT_EXIT</code>.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlhacktips-valgrind"
accesskey="1">perlhacktips valgrind</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-AddressSanitizer" accesskey="2">perlhacktips
AddressSanitizer</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhacktips-valgrind"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-AddressSanitizer" accesskey="n"
rel="next">perlhacktips AddressSanitizer</a>, Up: <a
href="#perlhacktips-MEMORY-DEBUGGERS" accesskey="u" rel="up">perlhacktips
MEMORY DEBUGGERS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="valgrind"></a>
-<h4 class="subsection">30.6.1 valgrind</h4>
-
-<p>The valgrind tool can be used to find out both memory leaks and illegal
-heap memory accesses. As of version 3.3.0, Valgrind only supports Linux
-on x86, x86-64 and PowerPC and Darwin (OS X) on x86 and x86-64). The
-special "test.valgrind" target can be used to run the tests under
-valgrind. Found errors and memory leaks are logged in files named
-<samp>testfile.valgrind</samp> and by default output is displayed inline.
-</p>
-<p>Example usage:
-</p>
-<pre class="verbatim"> make test.valgrind
-</pre>
-<p>Since valgrind adds significant overhead, tests will take much longer to
-run. The valgrind tests support being run in parallel to help with this:
-</p>
-<pre class="verbatim"> TEST_JOBS=9 make test.valgrind
-</pre>
-<p>Note that the above two invocations will be very verbose as reachable
-memory and leak-checking is enabled by default. If you want to just see
-pure errors, try:
-</p>
-<pre class="verbatim"> VG_OPTS='-q --leak-check=no --show-reachable=no'
TEST_JOBS=9 \
- make test.valgrind
-</pre>
-<p>Valgrind also provides a cachegrind tool, invoked on perl as:
-</p>
-<pre class="verbatim"> VG_OPTS=--tool=cachegrind make test.valgrind
-</pre>
-<p>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 <samp>t/perl.supp</samp>.
-</p>
-<p>To get valgrind and for more information see
-</p>
-<pre class="verbatim"> http://valgrind.org/
-</pre>
-<hr>
-<a name="perlhacktips-AddressSanitizer"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhacktips-valgrind" accesskey="p"
rel="prev">perlhacktips valgrind</a>, Up: <a
href="#perlhacktips-MEMORY-DEBUGGERS" accesskey="u" rel="up">perlhacktips
MEMORY DEBUGGERS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AddressSanitizer"></a>
-<h4 class="subsection">30.6.2 AddressSanitizer</h4>
-
-<p>AddressSanitizer is a clang and gcc extension, included in clang since
-v3.1 and gcc since v4.8. It checks illegal heap pointers, global
-pointers, stack pointers and use after free errors, and is fast enough
-that you can easily compile your debugging or optimized perl with it.
-It does not check memory leaks though. AddressSanitizer is available
-for Linux, Mac OS X and soon on Windows.
-</p>
-<p>To build perl with AddressSanitizer, your Configure invocation should
-look like:
-</p>
-<pre class="verbatim"> sh Configure -des -Dcc=clang \
- -Accflags=-faddress-sanitizer -Aldflags=-faddress-sanitizer \
- -Alddlflags=-shared\ -faddress-sanitizer
-</pre>
-<p>where these arguments mean:
-</p>
-<ul>
-<li> -Dcc=clang
-
-<p>This should be replaced by the full path to your clang executable if it
-is not in your path.
-</p>
-</li><li> -Accflags=-faddress-sanitizer
-
-<p>Compile perl and extensions sources with AddressSanitizer.
-</p>
-</li><li> -Aldflags=-faddress-sanitizer
-
-<p>Link the perl executable with AddressSanitizer.
-</p>
-</li><li> -Alddlflags=-shared\ -faddress-sanitizer
-
-<p>Link dynamic extensions with AddressSanitizer. You must manually
-specify <code>-shared</code> because using <code>-Alddlflags=-shared</code>
will prevent
-Configure from setting a default value for <code>lddlflags</code>, which
usually
-contains <code>-shared</code> (at least on Linux).
-</p>
-</li></ul>
-
-<p>See also
-<a
href="http://code.google.com/p/address-sanitizer/wiki/AddressSanitizer";>http://code.google.com/p/address-sanitizer/wiki/AddressSanitizer</a>.
-</p>
-<hr>
-<a name="perlhacktips-PROFILING"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-MISCELLANEOUS-TRICKS" accesskey="n"
rel="next">perlhacktips MISCELLANEOUS TRICKS</a>, Previous: <a
href="#perlhacktips-MEMORY-DEBUGGERS" accesskey="p" rel="prev">perlhacktips
MEMORY DEBUGGERS</a>, Up: <a href="#perlhacktips" accesskey="u"
rel="up">perlhacktips</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PROFILING"></a>
-<h3 class="section">30.7 PROFILING</h3>
-
-<p>Depending on your platform there are various ways of profiling Perl.
-</p>
-<p>There are two commonly used techniques of profiling executables:
-<em>statistical time-sampling</em> and <em>basic-block counting</em>.
-</p>
-<p>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.
-</p>
-<p>The second method divides up the generated code into <em>basic blocks</em>.
-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
-<em>instrumenting</em> the code by adding <em>enter basic block #nnnn</em>
-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.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Gprof-Profiling" accesskey="1">perlhacktips Gprof
Profiling</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-GCC-gcov-Profiling" accesskey="2">perlhacktips GCC gcov
Profiling</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhacktips-Gprof-Profiling"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-GCC-gcov-Profiling" accesskey="n"
rel="next">perlhacktips GCC gcov Profiling</a>, Up: <a
href="#perlhacktips-PROFILING" accesskey="u" rel="up">perlhacktips
PROFILING</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Gprof-Profiling"></a>
-<h4 class="subsection">30.7.1 Gprof Profiling</h4>
-
-<p><em>gprof</em> is a profiling tool available in many Unix platforms which
-uses <em>statistical time-sampling</em>. You can build a profiled version of
-<samp>perl</samp> by compiling using gcc with the flag <code>-pg</code>.
Either edit
-<samp>config.sh</samp> or re-run <samp>Configure</samp>. Running the profiled
version of
-Perl will create an output file called <samp>gmon.out</samp> which contains the
-profiling data collected during the execution.
-</p>
-<p>quick hint:
-</p>
-<pre class="verbatim"> $ sh Configure -des -Dusedevel -Accflags='-pg' \
- -Aldflags='-pg' -Alddlflags='-pg -shared' \
- && make perl
- $ ./perl ... # creates gmon.out in current directory
- $ gprof ./perl > out
- $ less out
-</pre>
-<p>(you probably need to add <code>-shared</code> to the <-Alddlflags>
line until RT
-#118199 is resolved)
-</p>
-<p>The <samp>gprof</samp> tool can then display the collected data in various
ways.
-Usually <samp>gprof</samp> understands the following options:
-</p>
-<ul>
-<li> -a
-
-<p>Suppress statically defined functions from the profile.
-</p>
-</li><li> -b
-
-<p>Suppress the verbose descriptions in the profile.
-</p>
-</li><li> -e routine
-
-<p>Exclude the given routine and its descendants from the profile.
-</p>
-</li><li> -f routine
-
-<p>Display only the given routine and its descendants in the profile.
-</p>
-</li><li> -s
-
-<p>Generate a summary file called <samp>gmon.sum</samp> which then may be
given to
-subsequent gprof runs to accumulate data over several runs.
-</p>
-</li><li> -z
-
-<p>Display routines that have zero usage.
-</p>
-</li></ul>
-
-<p>For more detailed explanation of the available commands and output
-formats, see your own local documentation of <samp>gprof</samp>.
-</p>
-<hr>
-<a name="perlhacktips-GCC-gcov-Profiling"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhacktips-Gprof-Profiling" accesskey="p"
rel="prev">perlhacktips Gprof Profiling</a>, Up: <a
href="#perlhacktips-PROFILING" accesskey="u" rel="up">perlhacktips
PROFILING</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="GCC-gcov-Profiling"></a>
-<h4 class="subsection">30.7.2 GCC gcov Profiling</h4>
-
-<p><em>basic block profiling</em> is officially available in gcc 3.0 and later.
-You can build a profiled version of <samp>perl</samp> by compiling using gcc
with
-the flags <code>-fprofile-arcs -ftest-coverage</code>. Either edit
<samp>config.sh</samp>
-or re-run <samp>Configure</samp>.
-</p>
-<p>quick hint:
-</p>
-<pre class="verbatim"> $ sh Configure -des -Dusedevel -Doptimize='-g' \
- -Accflags='-fprofile-arcs -ftest-coverage' \
- -Aldflags='-fprofile-arcs -ftest-coverage' \
- -Alddlflags='-fprofile-arcs -ftest-coverage -shared' \
- && make perl
- $ rm -f regexec.c.gcov regexec.gcda
- $ ./perl ...
- $ gcov regexec.c
- $ less regexec.c.gcov
-</pre>
-<p>(you probably need to add <code>-shared</code> to the <-Alddlflags>
line until RT
-#118199 is resolved)
-</p>
-<p>Running the profiled version of Perl will cause profile output to be
-generated. For each source file an accompanying <samp>.gcda</samp> file will
be
-created.
-</p>
-<p>To display the results you use the <em>gcov</em> utility (which should be
-installed if you have gcc 3.0 or newer installed). <samp>gcov</samp> is run on
-source code files, like this
-</p>
-<pre class="verbatim"> gcov sv.c
-</pre>
-<p>which will cause <samp>sv.c.gcov</samp> to be created. The
<samp>.gcov</samp> files contain
-the source code annotated with relative frequencies of execution
-indicated by "#" markers. If you want to generate
<samp>.gcov</samp> files for
-all profiled object files, you can run something like this:
-</p>
-<pre class="verbatim"> for file in `find . -name \*.gcno`
- do sh -c "cd `dirname $file` && gcov `basename $file
.gcno`"
- done
-</pre>
-<p>Useful options of <samp>gcov</samp> include <code>-b</code> which will
summarise the basic
-block, branch, and function call coverage, and <code>-c</code> which instead of
-relative frequencies will use the actual counts. For more information
-on the use of <samp>gcov</samp> and basic block profiling with gcc, see the
-latest GNU CC manual. As of gcc 4.8, this is at
-<a
href="http://gcc.gnu.org/onlinedocs/gcc/Gcov-Intro.html#Gcov-Intro";>http://gcc.gnu.org/onlinedocs/gcc/Gcov-Intro.html#Gcov-Intro</a>
-</p>
-<hr>
-<a name="perlhacktips-MISCELLANEOUS-TRICKS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-AUTHOR" accesskey="n" rel="next">perlhacktips
AUTHOR</a>, Previous: <a href="#perlhacktips-PROFILING" accesskey="p"
rel="prev">perlhacktips PROFILING</a>, Up: <a href="#perlhacktips"
accesskey="u" rel="up">perlhacktips</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="MISCELLANEOUS-TRICKS"></a>
-<h3 class="section">30.8 MISCELLANEOUS TRICKS</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-PERL_005fDESTRUCT_005fLEVEL" accesskey="1">perlhacktips
PERL_DESTRUCT_LEVEL</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-PERL_005fMEM_005fLOG" accesskey="2">perlhacktips
PERL_MEM_LOG</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhacktips-DDD-over-gdb"
accesskey="3">perlhacktips DDD over gdb</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhacktips-C-backtrace"
accesskey="4">perlhacktips C backtrace</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhacktips-Poison"
accesskey="5">perlhacktips Poison</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-Read_002donly-optrees" accesskey="6">perlhacktips Read-only
optrees</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-When-is-a-bool-not-a-bool_003f" accesskey="7">perlhacktips
When is a bool not a bool?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktips-The-_002ei-Targets" accesskey="8">perlhacktips The .i
Targets</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhacktips-PERL_005fDESTRUCT_005fLEVEL"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-PERL_005fMEM_005fLOG" accesskey="n"
rel="next">perlhacktips PERL_MEM_LOG</a>, Up: <a
href="#perlhacktips-MISCELLANEOUS-TRICKS" accesskey="u" rel="up">perlhacktips
MISCELLANEOUS TRICKS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PERL_005fDESTRUCT_005fLEVEL"></a>
-<h4 class="subsection">30.8.1 PERL_DESTRUCT_LEVEL</h4>
-
-<p>If you want to run any of the tests yourself manually using e.g.
-valgrind, please note that by default perl <strong>does not</strong> 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".
-</p>
-<p>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 running under
valgrind
-</p>
-<pre class="verbatim"> env PERL_DESTRUCT_LEVEL=2 valgrind ./perl -Ilib
t/foo/bar.t
-</pre>
-<p>(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.)
-</p>
-<p>If, at the end of a run you get the message <em>N scalars leaked</em>, you
-can recompile with <code>-DDEBUG_LEAKING_SCALARS</code>, 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 <code>new_SV()</code> from a macro into a real
-function, so you can use your favourite debugger to discover where
-those pesky SVs were allocated.
-</p>
-<p>If you see that you’re leaking memory at runtime, but neither valgrind
-nor <code>-DDEBUG_LEAKING_SCALARS</code> 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
<code>-Dm</code>
-switch can point you to the source of the leak. If the executable was
-built with <code>-DDEBUG_LEAKING_SCALARS</code>, <code>-Dm</code> 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
-<code>new_SV()</code> and make it break only when <code>PL_sv_serial</code> 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.
-</p>
-<p>As <code>-Dm</code> 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
-<code>-DPERL_MEM_LOG</code> instead.
-</p>
-<hr>
-<a name="perlhacktips-PERL_005fMEM_005fLOG"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-DDD-over-gdb" accesskey="n"
rel="next">perlhacktips DDD over gdb</a>, Previous: <a
href="#perlhacktips-PERL_005fDESTRUCT_005fLEVEL" accesskey="p"
rel="prev">perlhacktips PERL_DESTRUCT_LEVEL</a>, Up: <a
href="#perlhacktips-MISCELLANEOUS-TRICKS" accesskey="u" rel="up">perlhacktips
MISCELLANEOUS TRICKS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PERL_005fMEM_005fLOG"></a>
-<h4 class="subsection">30.8.2 PERL_MEM_LOG</h4>
-
-<p>If compiled with <code>-DPERL_MEM_LOG</code>, both memory and SV
allocations go
-through logging functions, which is handy for breakpoint setting.
-</p>
-<p>Unless <code>-DPERL_MEM_LOG_NOIMPL</code> is also compiled, the logging
functions
-read $ENV{PERL_MEM_LOG} to determine whether to log the event, and if
-so how:
-</p>
-<pre class="verbatim"> $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)
-</pre>
-<p>Memory logging is somewhat similar to <code>-Dm</code> but is independent of
-<code>-DDEBUGGING</code>, 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, <code>-Dm</code> is directly at the point of <code>malloc()</code>.
SV logging is
-similar.
-</p>
-<p>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 <code>-DDEBUG_LEAKING_SCALARS</code>, the serial number for each
SV
-allocation is also logged.
-</p>
-<hr>
-<a name="perlhacktips-DDD-over-gdb"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-C-backtrace" accesskey="n"
rel="next">perlhacktips C backtrace</a>, Previous: <a
href="#perlhacktips-PERL_005fMEM_005fLOG" accesskey="p" rel="prev">perlhacktips
PERL_MEM_LOG</a>, Up: <a href="#perlhacktips-MISCELLANEOUS-TRICKS"
accesskey="u" rel="up">perlhacktips MISCELLANEOUS TRICKS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DDD-over-gdb"></a>
-<h4 class="subsection">30.8.3 DDD over gdb</h4>
-
-<p>Those debugging perl with the DDD frontend over gdb may find the
-following useful:
-</p>
-<p>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:
-</p>
-<pre class="verbatim"> ! Display shortcuts.
- Ddd*gdbDisplayShortcuts: \
- /t () // Convert to Bin\n\
- /d () // Convert to Dec\n\
- /x () // Convert to Hex\n\
- /o () // Convert to Oct(\n\
-</pre>
-<p>the following two lines:
-</p>
-<pre class="verbatim"> ((XPV*) (())->sv_any )->xpv_pv // 2pvx\n\
- ((XPVIV*) (())->sv_any )->xiv_iv // 2ivx
-</pre>
-<p>so now you can do ivx and pvx lookups or you can plug there the sv_peek
-"conversion":
-</p>
-<pre class="verbatim"> Perl_sv_peek(my_perl, (SV*)()) // sv_peek
-</pre>
-<p>(The my_perl is for threaded builds.) Just remember that every line,
-but the last one, should end with \n\
-</p>
-<p>Alternatively edit the init file interactively via: 3rd mouse button ->
-New Display -> Edit Menu
-</p>
-<p>Note: you can define up to 20 conversion shortcuts in the gdb section.
-</p>
-<hr>
-<a name="perlhacktips-C-backtrace"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-Poison" accesskey="n" rel="next">perlhacktips
Poison</a>, Previous: <a href="#perlhacktips-DDD-over-gdb" accesskey="p"
rel="prev">perlhacktips DDD over gdb</a>, Up: <a
href="#perlhacktips-MISCELLANEOUS-TRICKS" accesskey="u" rel="up">perlhacktips
MISCELLANEOUS TRICKS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="C-backtrace"></a>
-<h4 class="subsection">30.8.4 C backtrace</h4>
-
-<p>On some platforms Perl supports retrieving the C level backtrace
-(similar to what symbolic debuggers like gdb do).
-</p>
-<p>The backtrace returns the stack trace of the C call frames,
-with the symbol names (function names), the object names (like
"perl"),
-and if it can, also the source code locations (file:line).
-</p>
-<p>The supported platforms are Linux, and OS X (some *BSD might
-work at least partly, but they have not yet been tested).
-</p>
-<p>This feature hasn’t been tested with multiple threads, but it will
-only show the backtrace of the thread doing the backtracing.
-</p>
-<p>The feature needs to be enabled with <code>Configure -Dusecbacktrace</code>.
-</p>
-<p>The <code>-Dusecbacktrace</code> also enables keeping the debug information
when
-compiling/linking (often: <code>-g</code>). Many compilers/linkers do support
-having both optimization and keeping the debug information. The debug
-information is needed for the symbol names and the source locations.
-</p>
-<p>Static functions might not be visible for the backtrace.
-</p>
-<p>Source code locations, even if available, can often be missing or
-misleading if the compiler has e.g. inlined code. Optimizer can
-make matching the source code and the object code quite challenging.
-</p>
-<dl compact="compact">
-<dt>Linux</dt>
-<dd><a name="perlhacktips-Linux"></a>
-<p>You <strong>must</strong> have the BFD (-lbfd) library installed, otherwise
<code>perl</code> will
-fail to link. The BFD is usually distributed as part of the GNU binutils.
-</p>
-<p>Summary: <code>Configure ... -Dusecbacktrace</code>
-and you need <code>-lbfd</code>.
-</p>
-</dd>
-<dt>OS X</dt>
-<dd><a name="perlhacktips-OS-X"></a>
-<p>The source code locations are supported <strong>only</strong> if you have
-the Developer Tools installed. (BFD is <strong>not</strong> needed.)
-</p>
-<p>Summary: <code>Configure ... -Dusecbacktrace</code>
-and installing the Developer Tools would be good.
-</p>
-</dd>
-</dl>
-
-<p>Optionally, for trying out the feature, you may want to enable
-automatic dumping of the backtrace just before a warning or croak (die)
-message is emitted, by adding <code>-Accflags=-DUSE_C_BACKTRACE_ON_ERROR</code>
-for Configure.
-</p>
-<p>Unless the above additional feature is enabled, nothing about the
-backtrace functionality is visible, except for the Perl/XS level.
-</p>
-<p>Furthermore, even if you have enabled this feature to be compiled,
-you need to enable it in runtime with an environment variable:
-<code>PERL_C_BACKTRACE_ON_ERROR=10</code>. It must be an integer higher
-than zero, telling the desired frame count.
-</p>
-<p>Retrieving the backtrace from Perl level (using for example an XS
-extension) would be much less exciting than one would hope: normally
-you would see <code>runops</code>, <code>entersub</code>, and not much else.
This API is
-intended to be called <strong>from within</strong> the Perl implementation,
not from
-Perl level execution.
-</p>
-<p>The C API for the backtrace is as follows:
-</p>
-<dl compact="compact">
-<dt>get_c_backtrace</dt>
-<dd><a name="perlhacktips-get_005fc_005fbacktrace"></a>
-</dd>
-<dt>free_c_backtrace</dt>
-<dd><a name="perlhacktips-free_005fc_005fbacktrace"></a>
-</dd>
-<dt>get_c_backtrace_dump</dt>
-<dd><a name="perlhacktips-get_005fc_005fbacktrace_005fdump"></a>
-</dd>
-<dt>dump_c_backtrace</dt>
-<dd><a name="perlhacktips-dump_005fc_005fbacktrace"></a>
-</dd>
-</dl>
-
-<hr>
-<a name="perlhacktips-Poison"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-Read_002donly-optrees" accesskey="n"
rel="next">perlhacktips Read-only optrees</a>, Previous: <a
href="#perlhacktips-C-backtrace" accesskey="p" rel="prev">perlhacktips C
backtrace</a>, Up: <a href="#perlhacktips-MISCELLANEOUS-TRICKS" accesskey="u"
rel="up">perlhacktips MISCELLANEOUS TRICKS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Poison"></a>
-<h4 class="subsection">30.8.5 Poison</h4>
-
-<p>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
-<a href="#perlclib-NAME">perlclib NAME</a>.
-</p>
-<hr>
-<a name="perlhacktips-Read_002donly-optrees"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-When-is-a-bool-not-a-bool_003f" accesskey="n"
rel="next">perlhacktips When is a bool not a bool?</a>, Previous: <a
href="#perlhacktips-Poison" accesskey="p" rel="prev">perlhacktips Poison</a>,
Up: <a href="#perlhacktips-MISCELLANEOUS-TRICKS" accesskey="u"
rel="up">perlhacktips MISCELLANEOUS TRICKS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Read_002donly-optrees"></a>
-<h4 class="subsection">30.8.6 Read-only optrees</h4>
-
-<p>Under ithreads the optree is read only. If you want to enforce this, to
-check for write accesses from buggy code, compile with
-<code>-Accflags=-DPERL_DEBUG_READONLY_OPS</code>
-to enable code that allocates op memory
-via <code>mmap</code>, and sets it read-only when it is attached to a
subroutine.
-Any write access to an op results in a <code>SIGBUS</code> and abort.
-</p>
-<p>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 does not apply to
-op slabs belonging to <code>BEGIN</code> blocks.
-</p>
-<p>However, as an 80% solution it is still effective, as it has caught
-bugs in the past.
-</p>
-<hr>
-<a name="perlhacktips-When-is-a-bool-not-a-bool_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktips-The-_002ei-Targets" accesskey="n"
rel="next">perlhacktips The .i Targets</a>, Previous: <a
href="#perlhacktips-Read_002donly-optrees" accesskey="p"
rel="prev">perlhacktips Read-only optrees</a>, Up: <a
href="#perlhacktips-MISCELLANEOUS-TRICKS" accesskey="u" rel="up">perlhacktips
MISCELLANEOUS TRICKS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="When-is-a-bool-not-a-bool_003f"></a>
-<h4 class="subsection">30.8.7 When is a bool not a bool?</h4>
-
-<p>On pre-C99 compilers, <code>bool</code> is defined as equivalent to
<code>char</code>.
-Consequently assignment of any larger type to a <code>bool</code> is unsafe
and may
-be truncated. The <code>cBOOL</code> macro exists to cast it correctly.
-</p>
-<p>On those platforms and compilers where <code>bool</code> really is a
boolean (C++,
-C99), it is easy to forget the cast. You can force <code>bool</code> to be a
<code>char</code>
-by compiling with <code>-Accflags=-DPERL_BOOL_AS_CHAR</code>. You may also
wish to
-run <code>Configure</code> with something like
-</p>
-<pre class="verbatim"> -Accflags='-Wconversion -Wno-sign-conversion
-Wno-shorten-64-to-32'
-</pre>
-<p>or your compiler’s equivalent to make it easier to spot any unsafe
truncations
-that show up.
-</p>
-<hr>
-<a name="perlhacktips-The-_002ei-Targets"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhacktips-When-is-a-bool-not-a-bool_003f" accesskey="p"
rel="prev">perlhacktips When is a bool not a bool?</a>, Up: <a
href="#perlhacktips-MISCELLANEOUS-TRICKS" accesskey="u" rel="up">perlhacktips
MISCELLANEOUS TRICKS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-_002ei-Targets"></a>
-<h4 class="subsection">30.8.8 The .i Targets</h4>
-
-<p>You can expand the macros in a <samp>foo.c</samp> file by saying
-</p>
-<pre class="verbatim"> make foo.i
-</pre>
-<p>which will expand the macros using cpp. Don’t be scared by the
-results.
-</p>
-<hr>
-<a name="perlhacktips-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhacktips-MISCELLANEOUS-TRICKS" accesskey="p"
rel="prev">perlhacktips MISCELLANEOUS TRICKS</a>, Up: <a href="#perlhacktips"
accesskey="u" rel="up">perlhacktips</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-12"></a>
-<h3 class="section">30.9 AUTHOR</h3>
-
-<p>This document was originally written by Nathan Torkington, and is
-maintained by the perl5-porters mailing list.
-</p>
-<hr>
-<a name="perlhacktut"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhist" accesskey="n" rel="next">perlhist</a>, Previous: <a
href="#perlhacktips" accesskey="p" rel="prev">perlhacktips</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlhacktut-1"></a>
-<h2 class="chapter">31 perlhacktut</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlhacktut-NAME"
accesskey="1">perlhacktut NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhacktut-DESCRIPTION"
accesskey="2">perlhacktut DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktut-EXAMPLE-OF-A-SIMPLE-PATCH" accesskey="3">perlhacktut EXAMPLE
OF A SIMPLE PATCH</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhacktut-AUTHOR"
accesskey="4">perlhacktut AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhacktut-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktut-DESCRIPTION" accesskey="n" rel="next">perlhacktut
DESCRIPTION</a>, Up: <a href="#perlhacktut" accesskey="u"
rel="up">perlhacktut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-30"></a>
-<h3 class="section">31.1 NAME</h3>
-
-<p>perlhacktut - Walk through the creation of a simple C code patch
-</p>
-<hr>
-<a name="perlhacktut-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktut-EXAMPLE-OF-A-SIMPLE-PATCH" accesskey="n"
rel="next">perlhacktut EXAMPLE OF A SIMPLE PATCH</a>, Previous: <a
href="#perlhacktut-NAME" accesskey="p" rel="prev">perlhacktut NAME</a>, Up: <a
href="#perlhacktut" accesskey="u" rel="up">perlhacktut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-30"></a>
-<h3 class="section">31.2 DESCRIPTION</h3>
-
-<p>This document takes you through a simple patch example.
-</p>
-<p>If you haven’t read <a href="#perlhack-NAME">perlhack NAME</a> yet,
go do that first! You might also
-want to read through <a href="#perlsource-NAME">perlsource NAME</a> too.
-</p>
-<p>Once you’re done here, check out <a
href="#perlhacktips-NAME">perlhacktips NAME</a> next.
-</p>
-<hr>
-<a name="perlhacktut-EXAMPLE-OF-A-SIMPLE-PATCH"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktut-AUTHOR" accesskey="n" rel="next">perlhacktut
AUTHOR</a>, Previous: <a href="#perlhacktut-DESCRIPTION" accesskey="p"
rel="prev">perlhacktut DESCRIPTION</a>, Up: <a href="#perlhacktut"
accesskey="u" rel="up">perlhacktut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="EXAMPLE-OF-A-SIMPLE-PATCH"></a>
-<h3 class="section">31.3 EXAMPLE OF A SIMPLE PATCH</h3>
-
-<p>Let’s take a simple patch from start to finish.
-</p>
-<p>Here’s something Larry suggested: if a <code>U</code> is the first
active format
-during a <code>pack</code>, (for example, <code>pack "U3C8",
@stuff</code>) then the
-resulting string should be treated as UTF-8 encoded.
-</p>
-<p>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 <a href="#perlgit-NAME">perlgit NAME</a>
for details on how to do
-this.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhacktut-Writing-the-patch" accesskey="1">perlhacktut Writing the
patch</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktut-Testing-the-patch" accesskey="2">perlhacktut Testing the
patch</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhacktut-Documenting-the-patch" accesskey="3">perlhacktut Documenting
the patch</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhacktut-Submit"
accesskey="4">perlhacktut Submit</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhacktut-Writing-the-patch"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktut-Testing-the-patch" accesskey="n"
rel="next">perlhacktut Testing the patch</a>, Up: <a
href="#perlhacktut-EXAMPLE-OF-A-SIMPLE-PATCH" accesskey="u"
rel="up">perlhacktut EXAMPLE OF A SIMPLE PATCH</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Writing-the-patch"></a>
-<h4 class="subsection">31.3.1 Writing the patch</h4>
-
-<p>How do we prepare to fix this up? First we locate the code in question
-- the <code>pack</code> happens at runtime, so it’s going to be in one
of the
-<samp>pp</samp> files. Sure enough, <code>pp_pack</code> is in
<samp>pp.c</samp>. Since we’re going
-to be altering this file, let’s copy it to <samp>pp.c~</samp>.
-</p>
-<p>[Well, it was in <samp>pp.c</samp> when this tutorial was written. It has
now
-been split off with <code>pp_unpack</code> to its own file,
<samp>pp_pack.c</samp>]
-</p>
-<p>Now let’s look over <code>pp_pack</code>: we take a pattern into
<code>pat</code>, and then
-loop over the pattern, taking each format character in turn into
-<code>datum_type</code>. 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 <code>cat</code>.
-</p>
-<p>How do we know if the <code>U</code> is the first format in the
<code>pat</code>? Well, if
-we have a pointer to the start of <code>pat</code> then, if we see a
<code>U</code> we can
-test whether we’re still at the start of the string. So, here’s
where
-<code>pat</code> is set up:
-</p>
-<pre class="verbatim"> STRLEN fromlen;
- char *pat = SvPVx(*++MARK, fromlen);
- char *patend = pat + fromlen;
- I32 len;
- I32 datumtype;
- SV *fromstr;
-</pre>
-<p>We’ll have another string pointer in there:
-</p>
-<pre class="verbatim"> STRLEN fromlen;
- char *pat = SvPVx(*++MARK, fromlen);
- char *patend = pat + fromlen;
- + char *patcopy;
- I32 len;
- I32 datumtype;
- SV *fromstr;
-</pre>
-<p>And just before we start the loop, we’ll set <code>patcopy</code> to
be the start
-of <code>pat</code>:
-</p>
-<pre class="verbatim"> items = SP - MARK;
- MARK++;
- sv_setpvn(cat, "", 0);
- + patcopy = pat;
- while (pat < patend) {
-</pre>
-<p>Now if we see a <code>U</code> which was at the start of the string, we
turn on
-the <code>UTF8</code> flag for the output SV, <code>cat</code>:
-</p>
-<pre class="verbatim"> + if (datumtype == 'U' && pat==patcopy+1)
- + SvUTF8_on(cat);
- if (datumtype == '#') {
- while (pat < patend && *pat != '\n')
- pat++;
-</pre>
-<p>Remember that it has to be <code>patcopy+1</code> because the first
character of
-the string is the <code>U</code> which has been swallowed into
<code>datumtype!</code>
-</p>
-<p>Oops, we forgot one thing: what if there are spaces at the start of the
-pattern? <code>pack(" U*", @stuff)</code> will have <code>U</code>
as the first active
-character, even though it’s not the first thing in the pattern. In this
-case, we have to advance <code>patcopy</code> along with <code>pat</code> when
we see
-spaces:
-</p>
-<pre class="verbatim"> if (isSPACE(datumtype))
- continue;
-</pre>
-<p>needs to become
-</p>
-<pre class="verbatim"> if (isSPACE(datumtype)) {
- patcopy++;
- continue;
- }
-</pre>
-<p>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.
-</p>
-<hr>
-<a name="perlhacktut-Testing-the-patch"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktut-Documenting-the-patch" accesskey="n"
rel="next">perlhacktut Documenting the patch</a>, Previous: <a
href="#perlhacktut-Writing-the-patch" accesskey="p" rel="prev">perlhacktut
Writing the patch</a>, Up: <a href="#perlhacktut-EXAMPLE-OF-A-SIMPLE-PATCH"
accesskey="u" rel="up">perlhacktut EXAMPLE OF A SIMPLE PATCH</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Testing-the-patch"></a>
-<h4 class="subsection">31.3.2 Testing the patch</h4>
-
-<p>The regression tests for each operator live in <samp>t/op/</samp>, and so
we make
-a copy of <samp>t/op/pack.t</samp> to <samp>t/op/pack.t~</samp>. Now we can
add our tests
-to the end. First, we’ll test that the <code>U</code> does indeed create
Unicode
-strings.
-</p>
-<p>t/op/pack.t has a sensible ok() function, but if it didn’t we could
use
-the one from t/test.pl.
-</p>
-<pre class="verbatim"> require './test.pl';
- plan( tests => 159 );
-</pre>
-<p>so instead of this:
-</p>
-<pre class="verbatim"> print 'not ' unless "1.20.300.4000" eq
sprintf "%vd",
-
pack("U*",1,20,300,4000);
- print "ok $test\n"; $test++;
-</pre>
-<p>we can write the more sensible (see <a
href="Test-More.html#Top">(Test-More)</a> for a full
-explanation of is() and other testing functions).
-</p>
-<pre class="verbatim"> is( "1.20.300.4000", sprintf "%vd",
pack("U*",1,20,300,4000),
- "U* produces Unicode" );
-</pre>
-<p>Now we’ll test that we got that space-at-the-beginning business right:
-</p>
-<pre class="verbatim"> is( "1.20.300.4000", sprintf "%vd",
pack(" U*",1,20,300,4000),
- " with spaces at the
beginning" );
-</pre>
-<p>And finally we’ll test that we don’t make Unicode strings if
<code>U</code> is
-<strong>not</strong> the first active format:
-</p>
-<pre class="verbatim"> isnt( v1.20.300.4000, sprintf "%vd",
pack("C0U*",1,20,300,4000),
- "U* not first isn't Unicode"
);
-</pre>
-<p>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:
-</p>
-<pre class="verbatim"> print "1..156\n";
-</pre>
-<p>or this:
-</p>
-<pre class="verbatim"> plan( tests => 156 );
-</pre>
-<p>We now compile up Perl, and run it through the test suite. Our new
-tests pass, hooray!
-</p>
-<hr>
-<a name="perlhacktut-Documenting-the-patch"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhacktut-Submit" accesskey="n" rel="next">perlhacktut
Submit</a>, Previous: <a href="#perlhacktut-Testing-the-patch" accesskey="p"
rel="prev">perlhacktut Testing the patch</a>, Up: <a
href="#perlhacktut-EXAMPLE-OF-A-SIMPLE-PATCH" accesskey="u"
rel="up">perlhacktut EXAMPLE OF A SIMPLE PATCH</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Documenting-the-patch"></a>
-<h4 class="subsection">31.3.3 Documenting the patch</h4>
-
-<p>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 <samp>pod/perlfunc.pod</samp>; again, we make a copy, and then
we’ll
-insert this text in the description of <code>pack</code>:
-</p>
-<pre class="verbatim"> =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.
-</pre>
-<hr>
-<a name="perlhacktut-Submit"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhacktut-Documenting-the-patch" accesskey="p"
rel="prev">perlhacktut Documenting the patch</a>, Up: <a
href="#perlhacktut-EXAMPLE-OF-A-SIMPLE-PATCH" accesskey="u"
rel="up">perlhacktut EXAMPLE OF A SIMPLE PATCH</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Submit"></a>
-<h4 class="subsection">31.3.4 Submit</h4>
-
-<p>See <a href="#perlhack-NAME">perlhack NAME</a> for details on how to submit
this patch.
-</p>
-<hr>
-<a name="perlhacktut-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhacktut-EXAMPLE-OF-A-SIMPLE-PATCH" accesskey="p"
rel="prev">perlhacktut EXAMPLE OF A SIMPLE PATCH</a>, Up: <a
href="#perlhacktut" accesskey="u" rel="up">perlhacktut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-13"></a>
-<h3 class="section">31.4 AUTHOR</h3>
-
-<p>This document was originally written by Nathan Torkington, and is
-maintained by the perl5-porters mailing list.
-</p>
-<hr>
-<a name="perlhist"></a>
-<div class="header">
-<p>
-Next: <a href="#perlinterp" accesskey="n" rel="next">perlinterp</a>, Previous:
<a href="#perlhacktut" accesskey="p" rel="prev">perlhacktut</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlhist-1"></a>
-<h2 class="chapter">32 perlhist</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlhist-NAME"
accesskey="1">perlhist NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhist-DESCRIPTION"
accesskey="2">perlhist DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhist-INTRODUCTION"
accesskey="3">perlhist INTRODUCTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhist-THE-KEEPERS-OF-THE-PUMPKIN" accesskey="4">perlhist THE KEEPERS
OF THE PUMPKIN</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlhist-THE-RECORDS"
accesskey="5">perlhist THE RECORDS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhist-THE-KEEPERS-OF-THE-RECORDS" accesskey="6">perlhist THE KEEPERS
OF THE RECORDS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhist-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhist-DESCRIPTION" accesskey="n" rel="next">perlhist
DESCRIPTION</a>, Up: <a href="#perlhist" accesskey="u" rel="up">perlhist</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-31"></a>
-<h3 class="section">32.1 NAME</h3>
-
-<p>perlhist - the Perl history records
-</p>
-<hr>
-<a name="perlhist-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhist-INTRODUCTION" accesskey="n" rel="next">perlhist
INTRODUCTION</a>, Previous: <a href="#perlhist-NAME" accesskey="p"
rel="prev">perlhist NAME</a>, Up: <a href="#perlhist" accesskey="u"
rel="up">perlhist</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-31"></a>
-<h3 class="section">32.2 DESCRIPTION</h3>
-
-<p>This document aims to record the Perl source code releases.
-</p>
-<hr>
-<a name="perlhist-INTRODUCTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhist-THE-KEEPERS-OF-THE-PUMPKIN" accesskey="n"
rel="next">perlhist THE KEEPERS OF THE PUMPKIN</a>, Previous: <a
href="#perlhist-DESCRIPTION" accesskey="p" rel="prev">perlhist DESCRIPTION</a>,
Up: <a href="#perlhist" accesskey="u" rel="up">perlhist</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="INTRODUCTION"></a>
-<h3 class="section">32.3 INTRODUCTION</h3>
-
-<p>Perl history in brief, by Larry Wall:
-</p>
-<pre class="verbatim"> Perl 0 introduced Perl to my officemates.
- Perl 1 introduced Perl to the world, and changed /\(...\|...\)/ to
- /(...|...)/. \(Dan Faigin still hasn't forgiven me. :-\)
- Perl 2 introduced Henry Spencer's regular expression package.
- Perl 3 introduced the ability to handle binary data (embedded nulls).
- Perl 4 introduced the first Camel book. Really. We mostly just
- switched version numbers so the book could refer to 4.000.
- Perl 5 introduced everything else, including the ability to
- introduce everything else.
-</pre>
-<hr>
-<a name="perlhist-THE-KEEPERS-OF-THE-PUMPKIN"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhist-THE-RECORDS" accesskey="n" rel="next">perlhist THE
RECORDS</a>, Previous: <a href="#perlhist-INTRODUCTION" accesskey="p"
rel="prev">perlhist INTRODUCTION</a>, Up: <a href="#perlhist" accesskey="u"
rel="up">perlhist</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="THE-KEEPERS-OF-THE-PUMPKIN"></a>
-<h3 class="section">32.4 THE KEEPERS OF THE PUMPKIN</h3>
-
-<p>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,
-Matt S Trout, David Golden, Florian Ragwitz, Tatsuhiko Miyagawa,
-Chris <code>BinGOs</code> Williams, Zefram, ÃÂvar Arnfjörð Bjarmason,
Stevan
-Little, Dave Rolsky, Max Maischein, Abigail, Jesse Luehrs, Tony Cook,
-Dominic Hargreaves, Aaron Crane, Aristotle Pagaltzis, Matthew Horsfall,
-Peter Martini, and Sawyer X.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlhist-PUMPKIN_003f"
accesskey="1">perlhist PUMPKIN?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhist-PUMPKIN_003f"></a>
-<div class="header">
-<p>
-Up: <a href="#perlhist-THE-KEEPERS-OF-THE-PUMPKIN" accesskey="u"
rel="up">perlhist THE KEEPERS OF THE PUMPKIN</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PUMPKIN_003f"></a>
-<h4 class="subsection">32.4.1 PUMPKIN?</h4>
-
-<p>[from Porting/pumpkin.pod in the Perl source code distribution]
-</p>
-<p>Chip Salzenberg gets credit for that, with a nod to his cow orker,
-David Croy. We had passed around various names (baton, token, hot
-potato) but none caught on. Then, Chip asked:
-</p>
-<p>[begin quote]
-</p>
-<pre class="verbatim"> Who has the patch pumpkin?
-</pre>
-<p>To explain: David Croy once told me that at a previous job,
-there was one tape drive and multiple systems that used it for backups.
-But instead of some high-tech exclusion software, they used a low-tech
-method to prevent multiple simultaneous backups: a stuffed pumpkin.
-No one was allowed to make backups unless they had the "backup
pumpkin".
-</p>
-<p>[end quote]
-</p>
-<p>The name has stuck. The holder of the pumpkin is sometimes called
-the pumpking (keeping the source afloat?) or the pumpkineer (pulling
-the strings?).
-</p>
-<hr>
-<a name="perlhist-THE-RECORDS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhist-THE-KEEPERS-OF-THE-RECORDS" accesskey="n"
rel="next">perlhist THE KEEPERS OF THE RECORDS</a>, Previous: <a
href="#perlhist-THE-KEEPERS-OF-THE-PUMPKIN" accesskey="p" rel="prev">perlhist
THE KEEPERS OF THE PUMPKIN</a>, Up: <a href="#perlhist" accesskey="u"
rel="up">perlhist</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="THE-RECORDS"></a>
-<h3 class="section">32.5 THE RECORDS</h3>
-
-<pre class="verbatim"> Pump- Release Date Notes
- king (by no means
- comprehensive,
- see Changes*
- for details)
- ======================================================================
-
- Larry 0 Classified. Don't ask.
-
- Larry 1.000 1987-Dec-18
-
- 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
-
- Larry 2.000 1988-Jun-05
-
- 2.001 1988-Jun-28
-
- Larry 3.000 1989-Oct-18
-
- 3.001 1989-Oct-26
- 3.002..4 1989-Nov-11
- 3.005 1989-Nov-18
- 3.006..8 1989-Dec-22
- 3.009..13 1990-Mar-02
- 3.014 1990-Mar-13
- 3.015 1990-Mar-14
- 3.016..18 1990-Mar-28
- 3.019..27 1990-Aug-10 User subs.
- 3.028 1990-Aug-14
- 3.029..36 1990-Oct-17
- 3.037 1990-Oct-20
- 3.040 1990-Nov-10
- 3.041 1990-Nov-13
- 3.042..43 1991-Jan-??
- 3.044 1991-Jan-12
-
- Larry 4.000 1991-Mar-21
-
- 4.001..3 1991-Apr-12
- 4.004..9 1991-Jun-07
- 4.010 1991-Jun-10
- 4.011..18 1991-Nov-05
- 4.019 1991-Nov-11 Stable.
- 4.020..33 1992-Jun-08
- 4.034 1992-Jun-11
- 4.035 1992-Jun-23
- Larry 4.036 1993-Feb-05 Very stable.
-
- 5.000alpha1 1993-Jul-31
- 5.000alpha2 1993-Aug-16
- 5.000alpha3 1993-Oct-10
- 5.000alpha4 1993-???-??
- 5.000alpha5 1993-???-??
- 5.000alpha6 1994-Mar-18
- 5.000alpha7 1994-Mar-25
- Andy 5.000alpha8 1994-Apr-04
- Larry 5.000alpha9 1994-May-05 ext appears.
- 5.000alpha10 1994-Jun-11
- 5.000alpha11 1994-Jul-01
- Andy 5.000a11a 1994-Jul-07 To fit 14.
- 5.000a11b 1994-Jul-14
- 5.000a11c 1994-Jul-19
- 5.000a11d 1994-Jul-22
- Larry 5.000alpha12 1994-Aug-04
- Andy 5.000a12a 1994-Aug-08
- 5.000a12b 1994-Aug-15
- 5.000a12c 1994-Aug-22
- 5.000a12d 1994-Aug-22
- 5.000a12e 1994-Aug-22
- 5.000a12f 1994-Aug-24
- 5.000a12g 1994-Aug-24
- 5.000a12h 1994-Aug-24
- Larry 5.000beta1 1994-Aug-30
- Andy 5.000b1a 1994-Sep-06
- Larry 5.000beta2 1994-Sep-14 Core slushified.
- Andy 5.000b2a 1994-Sep-14
- 5.000b2b 1994-Sep-17
- 5.000b2c 1994-Sep-17
- Larry 5.000beta3 1994-Sep-??
- Andy 5.000b3a 1994-Sep-18
- 5.000b3b 1994-Sep-22
- 5.000b3c 1994-Sep-23
- 5.000b3d 1994-Sep-27
- 5.000b3e 1994-Sep-28
- 5.000b3f 1994-Sep-30
- 5.000b3g 1994-Oct-04
- Andy 5.000b3h 1994-Oct-07
- Larry? 5.000gamma 1994-Oct-13?
-
- Larry 5.000 1994-Oct-17
-
- Andy 5.000a 1994-Dec-19
- 5.000b 1995-Jan-18
- 5.000c 1995-Jan-18
- 5.000d 1995-Jan-18
- 5.000e 1995-Jan-18
- 5.000f 1995-Jan-18
- 5.000g 1995-Jan-18
- 5.000h 1995-Jan-18
- 5.000i 1995-Jan-26
- 5.000j 1995-Feb-07
- 5.000k 1995-Feb-11
- 5.000l 1995-Feb-21
- 5.000m 1995-Feb-28
- 5.000n 1995-Mar-07
- 5.000o 1995-Mar-13?
-
- Larry 5.001 1995-Mar-13
-
- Andy 5.001a 1995-Mar-15
- 5.001b 1995-Mar-31
- 5.001c 1995-Apr-07
- 5.001d 1995-Apr-14
- 5.001e 1995-Apr-18 Stable.
- 5.001f 1995-May-31
- 5.001g 1995-May-25
- 5.001h 1995-May-25
- 5.001i 1995-May-30
- 5.001j 1995-Jun-05
- 5.001k 1995-Jun-06
- 5.001l 1995-Jun-06 Stable.
- 5.001m 1995-Jul-02 Very stable.
- 5.001n 1995-Oct-31 Very unstable.
- 5.002beta1 1995-Nov-21
- 5.002b1a 1995-Dec-04
- 5.002b1b 1995-Dec-04
- 5.002b1c 1995-Dec-04
- 5.002b1d 1995-Dec-04
- 5.002b1e 1995-Dec-08
- 5.002b1f 1995-Dec-08
- Tom 5.002b1g 1995-Dec-21 Doc release.
- Andy 5.002b1h 1996-Jan-05
- 5.002b2 1996-Jan-14
- Larry 5.002b3 1996-Feb-02
- Andy 5.002gamma 1996-Feb-11
- Larry 5.002delta 1996-Feb-27
-
- Larry 5.002 1996-Feb-29 Prototypes.
-
- Charles 5.002_01 1996-Mar-25
-
- 5.003 1996-Jun-25 Security release.
-
- 5.003_01 1996-Jul-31
- Nick 5.003_02 1996-Aug-10
- Andy 5.003_03 1996-Aug-28
- 5.003_04 1996-Sep-02
- 5.003_05 1996-Sep-12
- 5.003_06 1996-Oct-07
- 5.003_07 1996-Oct-10
- Chip 5.003_08 1996-Nov-19
- 5.003_09 1996-Nov-26
- 5.003_10 1996-Nov-29
- 5.003_11 1996-Dec-06
- 5.003_12 1996-Dec-19
- 5.003_13 1996-Dec-20
- 5.003_14 1996-Dec-23
- 5.003_15 1996-Dec-23
- 5.003_16 1996-Dec-24
- 5.003_17 1996-Dec-27
- 5.003_18 1996-Dec-31
- 5.003_19 1997-Jan-04
- 5.003_20 1997-Jan-07
- 5.003_21 1997-Jan-15
- 5.003_22 1997-Jan-16
- 5.003_23 1997-Jan-25
- 5.003_24 1997-Jan-29
- 5.003_25 1997-Feb-04
- 5.003_26 1997-Feb-10
- 5.003_27 1997-Feb-18
- 5.003_28 1997-Feb-21
- 5.003_90 1997-Feb-25 Ramping up to the 5.004 release.
- 5.003_91 1997-Mar-01
- 5.003_92 1997-Mar-06
- 5.003_93 1997-Mar-10
- 5.003_94 1997-Mar-22
- 5.003_95 1997-Mar-25
- 5.003_96 1997-Apr-01
- 5.003_97 1997-Apr-03 Fairly widely used.
- 5.003_97a 1997-Apr-05
- 5.003_97b 1997-Apr-08
- 5.003_97c 1997-Apr-10
- 5.003_97d 1997-Apr-13
- 5.003_97e 1997-Apr-15
- 5.003_97f 1997-Apr-17
- 5.003_97g 1997-Apr-18
- 5.003_97h 1997-Apr-24
- 5.003_97i 1997-Apr-25
- 5.003_97j 1997-Apr-28
- 5.003_98 1997-Apr-30
- 5.003_99 1997-May-01
- 5.003_99a 1997-May-09
- p54rc1 1997-May-12 Release Candidates.
- p54rc2 1997-May-14
-
- Chip 5.004 1997-May-15 A major maintenance release.
-
- Tim 5.004_01-t1 1997-???-?? The 5.004 maintenance track.
- 5.004_01-t2 1997-Jun-11 aka perl5.004m1t2
- 5.004_01 1997-Jun-13
- 5.004_01_01 1997-Jul-29 aka perl5.004m2t1
- 5.004_01_02 1997-Aug-01 aka perl5.004m2t2
- 5.004_01_03 1997-Aug-05 aka perl5.004m2t3
- 5.004_02 1997-Aug-07
- 5.004_02_01 1997-Aug-12 aka perl5.004m3t1
- 5.004_03-t2 1997-Aug-13 aka perl5.004m3t2
- 5.004_03 1997-Sep-05
- 5.004_04-t1 1997-Sep-19 aka perl5.004m4t1
- 5.004_04-t2 1997-Sep-23 aka perl5.004m4t2
- 5.004_04-t3 1997-Oct-10 aka perl5.004m4t3
- 5.004_04-t4 1997-Oct-14 aka perl5.004m4t4
- 5.004_04 1997-Oct-15
- 5.004_04-m1 1998-Mar-04 (5.004m5t1) Maint. trials for 5.004_05.
- 5.004_04-m2 1998-May-01
- 5.004_04-m3 1998-May-15
- 5.004_04-m4 1998-May-19
- 5.004_05-MT5 1998-Jul-21
- 5.004_05-MT6 1998-Oct-09
- 5.004_05-MT7 1998-Nov-22
- 5.004_05-MT8 1998-Dec-03
- Chip 5.004_05-MT9 1999-Apr-26
- 5.004_05 1999-Apr-29
-
- Malcolm 5.004_50 1997-Sep-09 The 5.005 development track.
- 5.004_51 1997-Oct-02
- 5.004_52 1997-Oct-15
- 5.004_53 1997-Oct-16
- 5.004_54 1997-Nov-14
- 5.004_55 1997-Nov-25
- 5.004_56 1997-Dec-18
- 5.004_57 1998-Feb-03
- 5.004_58 1998-Feb-06
- 5.004_59 1998-Feb-13
- 5.004_60 1998-Feb-20
- 5.004_61 1998-Feb-27
- 5.004_62 1998-Mar-06
- 5.004_63 1998-Mar-17
- 5.004_64 1998-Apr-03
- 5.004_65 1998-May-15
- 5.004_66 1998-May-29
- Sarathy 5.004_67 1998-Jun-15
- 5.004_68 1998-Jun-23
- 5.004_69 1998-Jun-29
- 5.004_70 1998-Jul-06
- 5.004_71 1998-Jul-09
- 5.004_72 1998-Jul-12
- 5.004_73 1998-Jul-13
- 5.004_74 1998-Jul-14 5.005 beta candidate.
- 5.004_75 1998-Jul-15 5.005 beta1.
- 5.004_76 1998-Jul-21 5.005 beta2.
-
- Sarathy 5.005 1998-Jul-22 Oneperl.
-
- Sarathy 5.005_01 1998-Jul-27 The 5.005 maintenance track.
- 5.005_02-T1 1998-Aug-02
- 5.005_02-T2 1998-Aug-05
- 5.005_02 1998-Aug-08
- Graham 5.005_03-MT1 1998-Nov-30
- 5.005_03-MT2 1999-Jan-04
- 5.005_03-MT3 1999-Jan-17
- 5.005_03-MT4 1999-Jan-26
- 5.005_03-MT5 1999-Jan-28
- 5.005_03-MT6 1999-Mar-05
- 5.005_03 1999-Mar-28
- 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
- 5.005_52 1998-Sep-25
- 5.005_53 1998-Oct-31
- 5.005_54 1998-Nov-30
- 5.005_55 1999-Feb-16
- 5.005_56 1999-Mar-01
- 5.005_57 1999-May-25
- 5.005_58 1999-Jul-27
- 5.005_59 1999-Aug-02
- 5.005_60 1999-Aug-02
- 5.005_61 1999-Aug-20
- 5.005_62 1999-Oct-15
- 5.005_63 1999-Dec-09
- 5.5.640 2000-Feb-02
- 5.5.650 2000-Feb-08 beta1
- 5.5.660 2000-Feb-22 beta2
- 5.5.670 2000-Feb-29 beta3
- 5.6.0-RC1 2000-Mar-09 Release candidate 1.
- 5.6.0-RC2 2000-Mar-14 Release candidate 2.
- 5.6.0-RC3 2000-Mar-21 Release candidate 3.
-
- Sarathy 5.6.0 2000-Mar-22
-
- Sarathy 5.6.1-TRIAL1 2000-Dec-18 The 5.6 maintenance track.
- 5.6.1-TRIAL2 2001-Jan-31
- 5.6.1-TRIAL3 2001-Mar-19
- 5.6.1-foolish 2001-Apr-01 The "fools-gold" release.
- 5.6.1 2001-Apr-08
- Rafael 5.6.2-RC1 2003-Nov-08
- 5.6.2 2003-Nov-15 Fix new build issues
-
- Jarkko 5.7.0 2000-Sep-02 The 5.7 track: Development.
- 5.7.1 2001-Apr-09
- 5.7.2 2001-Jul-13 Virtual release candidate 0.
- 5.7.3 2002-Mar-05
- 5.8.0-RC1 2002-Jun-01
- 5.8.0-RC2 2002-Jun-21
- 5.8.0-RC3 2002-Jul-13
-
- Jarkko 5.8.0 2002-Jul-18
-
- Jarkko 5.8.1-RC1 2003-Jul-10 The 5.8 maintenance track
- 5.8.1-RC2 2003-Jul-11
- 5.8.1-RC3 2003-Jul-30
- 5.8.1-RC4 2003-Aug-01
- 5.8.1-RC5 2003-Sep-22
- 5.8.1 2003-Sep-25
- Nicholas 5.8.2-RC1 2003-Oct-27
- 5.8.2-RC2 2003-Nov-03
- 5.8.2 2003-Nov-05
- 5.8.3-RC1 2004-Jan-07
- 5.8.3 2004-Jan-14
- 5.8.4-RC1 2004-Apr-05
- 5.8.4-RC2 2004-Apr-15
- 5.8.4 2004-Apr-21
- 5.8.5-RC1 2004-Jul-06
- 5.8.5-RC2 2004-Jul-08
- 5.8.5 2004-Jul-19
- 5.8.6-RC1 2004-Nov-11
- 5.8.6 2004-Nov-27
- 5.8.7-RC1 2005-May-18
- 5.8.7 2005-May-30
- 5.8.8-RC1 2006-Jan-20
- 5.8.8 2006-Jan-31
- 5.8.9-RC1 2008-Nov-10
- 5.8.9-RC2 2008-Dec-06
- 5.8.9 2008-Dec-14
-
- Hugo 5.9.0 2003-Oct-27 The 5.9 development track
- Rafael 5.9.1 2004-Mar-16
- 5.9.2 2005-Apr-01
- 5.9.3 2006-Jan-28
- 5.9.4 2006-Aug-15
- 5.9.5 2007-Jul-07
- 5.10.0-RC1 2007-Nov-17
- 5.10.0-RC2 2007-Nov-25
-
- Rafael 5.10.0 2007-Dec-18
-
- 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
-
- Jesse 5.11.0 2009-Oct-02 The 5.11 development track
- 5.11.1 2009-Oct-20
- Leon 5.11.2 2009-Nov-20
- 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-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-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.12.4-RC1 2011-Jun-08
- Leon 5.12.4 2011-Jun-20
- Dominic 5.12.5 2012-Nov-10
-
- Leon 5.13.0 2010-Apr-20 The 5.13 development track
- Ricardo 5.13.1 2010-May-20
- 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
- Dominic 5.14.3 2012-Oct-12
- David M 5.14.4-RC1 2013-Mar-05
- David M 5.14.4-RC2 2013-Mar-07
- David M 5.14.4 2013-Mar-10
-
- David G 5.15.0 2011-Jun-20 The 5.15 development track
- Zefram 5.15.1 2011-Jul-20
- Ricardo 5.15.2 2011-Aug-20
- Stevan 5.15.3 2011-Sep-20
- Florian 5.15.4 2011-Oct-20
- Steve 5.15.5 2011-Nov-20
- Dave R 5.15.6 2011-Dec-20
- BinGOs 5.15.7 2012-Jan-20
- Max M 5.15.8 2012-Feb-20
- Abigail 5.15.9 2012-Mar-20
- Ricardo 5.16.0-RC0 2012-May-10
- Ricardo 5.16.0-RC1 2012-May-14
- Ricardo 5.16.0-RC2 2012-May-15
-
- Ricardo 5.16.0 2012-May-20 The 5.16 maintenance track
- Ricardo 5.16.1 2012-Aug-08
- Ricardo 5.16.2 2012-Nov-01
- Ricardo 5.16.3-RC1 2013-Mar-06
- Ricardo 5.16.3 2013-Mar-11
-
- Zefram 5.17.0 2012-May-26 The 5.17 development track
- Jesse L 5.17.1 2012-Jun-20
- TonyC 5.17.2 2012-Jul-20
- Steve 5.17.3 2012-Aug-20
- Florian 5.17.4 2012-Sep-20
- Florian 5.17.5 2012-Oct-20
- Ricardo 5.17.6 2012-Nov-20
- Dave R 5.17.7 2012-Dec-18
- Aaron 5.17.8 2013-Jan-20
- BinGOs 5.17.9 2013-Feb-20
- Max M 5.17.10 2013-Mar-21
- Ricardo 5.17.11 2013-Apr-20
-
- Ricardo 5.18.0-RC1 2013-May-11 The 5.18 maintenance track
- Ricardo 5.18.0-RC2 2013-May-12
- Ricardo 5.18.0-RC3 2013-May-13
- Ricardo 5.18.0-RC4 2013-May-15
- Ricardo 5.18.0 2013-May-18
- Ricardo 5.18.1-RC1 2013-Aug-01
- Ricardo 5.18.1-RC2 2013-Aug-03
- Ricardo 5.18.1-RC3 2013-Aug-08
- Ricardo 5.18.1 2013-Aug-12
- Ricardo 5.18.2 2014-Jan-06
- Ricardo 5.18.3-RC1 2014-Sep-17
- Ricardo 5.18.3-RC2 2014-Sep-27
- Ricardo 5.18.3 2014-Oct-01
- Ricardo 5.18.4 2014-Oct-01
-
- Ricardo 5.19.0 2013-May-20 The 5.19 development track
- David G 5.19.1 2013-Jun-21
- Aristotle 5.19.2 2013-Jul-22
- Steve 5.19.3 2013-Aug-20
- Steve 5.19.4 2013-Sep-20
- Steve 5.19.5 2013-Oct-20
- BinGOs 5.19.6 2013-Nov-20
- Abigail 5.19.7 2013-Dec-20
- Ricardo 5.19.8 2014-Jan-20
- TonyC 5.19.9 2014-Feb-20
- Aaron 5.19.10 2014-Mar-20
- Steve 5.19.11 2014-Apr-20
-
- Ricardo 5.20.0-RC1 2014-May-16 The 5.20 maintenance track
- Ricardo 5.20.0 2014-May-27
- Steve 5.20.1-RC1 2014-Aug-25
- Steve 5.20.1-RC2 2014-Sep-07
- Steve 5.20.1 2014-Sep-14
- Steve 5.20.2-RC1 2015-Jan-31
- Steve 5.20.2 2015-Feb-14
- Steve 5.20.3-RC1 2015-Aug-22
- Steve 5.20.3-RC2 2015-Aug-29
- Steve 5.20.3 2015-Sep-12
-
- Ricardo 5.21.0 2014-May-27 The 5.21 development track
- Matthew H 5.21.1 2014-Jun-20
- Abigail 5.21.2 2014-Jul-20
- Peter 5.21.3 2014-Aug-20
- Steve 5.21.4 2014-Sep-20
- Abigail 5.21.5 2014-Oct-20
- BinGOs 5.21.6 2014-Nov-20
- Max M 5.21.7 2014-Dec-20
- Matthew H 5.21.8 2015-Jan-20
- Sawyer X 5.21.9 2015-Feb-20
- Steve 5.21.10 2015-Mar-20
- Steve 5.21.11 2015-Apr-20
-
- Ricardo 5.22.0-RC1 2015-May-19 The 5.22 maintenance track
- Ricardo 5.22.0-RC2 2015-May-21
- Ricardo 5.22.0 2015-Jun-01
- Steve 5.22.1-RC1 2015-Oct-31
- Steve 5.22.1-RC2 2015-Nov-15
- Steve 5.22.1-RC3 2015-Dec-02
- Steve 5.22.1-RC4 2015-Dec-08
- Steve 5.22.1 2015-Dec-13
-
- Ricardo 5.23.0 2015-Jun-20 The 5.23 development track
- Matthew 5.23.1 2015-Jul-20
- Matthew 5.23.2 2015-Aug-20
- Peter 5.23.3 2015-Sep-20
- Steve 5.23.4 2015-Oct-20
- Abigail 5.23.5 2015-Nov-20
-</pre>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhist-SELECTED-RELEASE-SIZES" accesskey="1">perlhist SELECTED RELEASE
SIZES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlhist-SELECTED-PATCH-SIZES" accesskey="2">perlhist SELECTED PATCH
SIZES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhist-SELECTED-RELEASE-SIZES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlhist-SELECTED-PATCH-SIZES" accesskey="n"
rel="next">perlhist SELECTED PATCH SIZES</a>, Up: <a
href="#perlhist-THE-RECORDS" accesskey="u" rel="up">perlhist THE RECORDS</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SELECTED-RELEASE-SIZES"></a>
-<h4 class="subsection">32.5.1 SELECTED RELEASE SIZES</h4>
-
-<p>For example the notation "core: 212 29" in the release 1.000
means that
-it had in the core 212 kilobytes, in 29 files. The
"core".."doc" are
-explained below.
-</p>
-<pre class="verbatim"> release core lib ext t
doc
- ======================================================================
-
- 1.000 212 29 - - - - 38 51 62 3
- 1.014 219 29 - - - - 39 52 68 4
- 2.000 309 31 2 3 - - 55 57 92 4
- 2.001 312 31 2 3 - - 55 57 94 4
- 3.000 508 36 24 11 - - 79 73 156 5
- 3.044 645 37 61 20 - - 90 74 190 6
- 4.000 635 37 59 20 - - 91 75 198 4
- 4.019 680 37 85 29 - - 98 76 199 4
- 4.036 709 37 89 30 - - 98 76 208 5
- 5.000alpha2 785 50 114 32 - - 112 86 209 5
- 5.000alpha3 801 50 117 33 - - 121 87 209 5
- 5.000alpha9 1022 56 149 43 116 29 125 90 217 6
- 5.000a12h 978 49 140 49 205 46 152 97 228 9
- 5.000b3h 1035 53 232 70 216 38 162 94 218 21
- 5.000 1038 53 250 76 216 38 154 92 536 62
- 5.001m 1071 54 388 82 240 38 159 95 544 29
- 5.002 1121 54 661 101 287 43 155 94 847 35
- 5.003 1129 54 680 102 291 43 166 100 853 35
- 5.003_07 1231 60 748 106 396 53 213 137 976 39
- 5.004 1351 60 1230 136 408 51 355 161 1587 55
- 5.004_01 1356 60 1258 138 410 51 358 161 1587 55
- 5.004_04 1375 60 1294 139 413 51 394 162 1629 55
- 5.004_05 1463 60 1435 150 394 50 445 175 1855 59
- 5.004_51 1401 61 1260 140 413 53 358 162 1594 56
- 5.004_53 1422 62 1295 141 438 70 394 162 1637 56
- 5.004_56 1501 66 1301 140 447 74 408 165 1648 57
- 5.004_59 1555 72 1317 142 448 74 424 171 1678 58
- 5.004_62 1602 77 1327 144 629 92 428 173 1674 58
- 5.004_65 1626 77 1358 146 615 92 446 179 1698 60
- 5.004_68 1856 74 1382 152 619 92 463 187 1784 60
- 5.004_70 1863 75 1456 154 675 92 494 194 1809 60
- 5.004_73 1874 76 1467 152 762 102 506 196 1883 61
- 5.004_75 1877 76 1467 152 770 103 508 196 1896 62
- 5.005 1896 76 1469 152 795 103 509 197 1945 63
- 5.005_03 1936 77 1541 153 813 104 551 201 2176 72
- 5.005_50 1969 78 1842 301 795 103 514 198 1948 63
- 5.005_53 1999 79 1885 303 806 104 602 224 2002 67
- 5.005_56 2086 79 1970 307 866 113 672 238 2221 75
- 5.6.0 2820 79 2626 364 1096 129 863 280 2840 93
- 5.6.1 2946 78 2921 430 1171 132 1024 304 3330 102
- 5.6.2 2947 78 3143 451 1247 127 1303 387 3406 102
- 5.7.0 2977 80 2801 425 1250 132 975 307 3206 100
- 5.7.1 3351 84 3442 455 1944 167 1334 357 3698 124
- 5.7.2 3491 87 4858 618 3290 298 1598 449 3910 139
- 5.7.3 3299 85 4295 537 2196 300 2176 626 4171 120
- 5.8.0 3489 87 4533 585 2437 331 2588 726 4368 125
- 5.8.1 3674 90 5104 623 2604 353 2983 836 4625 134
- 5.8.2 3633 90 5111 623 2623 357 3019 848 4634 135
- 5.8.3 3625 90 5141 624 2660 363 3083 869 4669 136
- 5.8.4 3653 90 5170 634 2684 368 3148 885 4689 137
- 5.8.5 3664 90 4260 303 2707 369 3208 898 4689 138
- 5.8.6 3690 90 4271 303 3141 396 3411 925 4709 139
- 5.8.7 3788 90 4322 307 3297 401 3485 964 4744 141
- 5.8.8 3895 90 4357 314 3409 431 3622 1017 4979 144
- 5.8.9 4132 93 5508 330 3826 529 4364 1234 5348 152
- 5.9.0 3657 90 4951 626 2603 354 3011 841 4609 135
- 5.9.1 3580 90 5196 634 2665 367 3186 889 4725 138
- 5.9.2 3863 90 4654 312 3283 403 3551 973 4800 142
- 5.9.3 4096 91 5318 381 4806 597 4272 1214 5139 147
- 5.9.4 4393 94 5718 415 4578 642 4646 1310 5335 153
- 5.9.5 4681 96 6849 479 4827 671 5155 1490 5572 159
- 5.10.0 4710 97 7050 486 4899 673 5275 1503 5673 160
- 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
- 5.14.0 5328 104 1100 114 17779 2479 7697 2130 5871 188
- 5.16.0 5562 109 1077 80 20504 2702 8750 2375 4815 152
- 5.18.0 5892 113 1088 79 20077 2760 9365 2439 4943 154
- 5.20.0 6243 115 1187 75 19499 2701 9620 2457 5145 159
- 5.22.0 7819 115 1284 77 19121 2635 9772 2434 5615 176
-</pre>
-<p>The "core"..."doc" mean the following files from the
Perl source code
-distribution. The glob notation ** means recursively, (.) means
-regular files.
-</p>
-<pre class="verbatim"> core *.[hcy]
- lib lib/**/*.p[ml]
- ext ext/**/*.{[hcyt],xs,pm} (for -5.10.1) or
- {dist,ext,cpan}/**/*.{[hcyt],xs,pm} (for 5.12.0-)
- t t/**/*(.) (for 1-5.005_56) or **/*.t (for 5.6.0-5.7.3)
- doc {README*,INSTALL,*[_.]man{,.?},pod/**/*.pod}
-</pre>
-<p>Here are some statistics for the other subdirectories and one file in
-the Perl source distribution for somewhat more selected releases.
-</p>
-<pre class="verbatim">
======================================================================
- Legend: kB #
-
- 1.014 2.001 3.044
-
- Configure 31 1 37 1 62 1
- eg - - 34 28 47 39
- h2pl - - - - 12 12
- msdos - - - - 41 13
- os2 - - - - 63 22
- usub - - - - 21 16
- x2p 103 17 104 17 137 17
-
- ======================================================================
-
- 4.000 4.019 4.036
-
- atarist - - - - 113 31
- Configure 73 1 83 1 86 1
- eg 47 39 47 39 47 39
- emacs 67 4 67 4 67 4
- h2pl 12 12 12 12 12 12
- hints - - 5 42 11 56
- msdos 57 15 58 15 60 15
- os2 81 29 81 29 113 31
- usub 25 7 43 8 43 8
- x2p 147 18 152 19 154 19
-
- ======================================================================
-
- 5.000a2 5.000a12h 5.000b3h 5.000 5.001m
-
- apollo 8 3 8 3 8 3 8 3 8 3
- atarist 113 31 113 31 - - - - - -
- bench - - 0 1 - - - - - -
- Bugs 2 5 26 1 - - - - - -
- dlperl 40 5 - - - - - - - -
- do 127 71 - - - - - - - -
- Configure - - 153 1 159 1 160 1 180 1
- Doc - - 26 1 75 7 11 1 11 1
- eg 79 58 53 44 51 43 54 44 54 44
- emacs 67 4 104 6 104 6 104 1 104 6
- h2pl 12 12 12 12 12 12 12 12 12 12
- hints 11 56 12 46 18 48 18 48 44 56
- msdos 60 15 60 15 - - - - - -
- os2 113 31 113 31 - - - - - -
- U - - 62 8 112 42 - - - -
- usub 43 8 - - - - - - - -
- vms - - 80 7 123 9 184 15 304 20
- x2p 171 22 171 21 162 20 162 20 279 20
-
- ======================================================================
-
- 5.002 5.003 5.003_07
-
- Configure 201 1 201 1 217 1
- eg 54 44 54 44 54 44
- emacs 108 1 108 1 143 1
- h2pl 12 12 12 12 12 12
- hints 73 59 77 60 90 62
- os2 84 17 56 10 117 42
- plan9 - - - - 79 15
- Porting - - - - 51 1
- utils 87 7 88 7 97 7
- vms 500 24 475 26 505 27
- x2p 280 20 280 20 280 19
-
- ======================================================================
-
- 5.004 5.004_04 5.004_62 5.004_65 5.004_68
-
- beos - - - - - - 1 1 1 1
- Configure 225 1 225 1 240 1 248 1 256 1
- cygwin32 23 5 23 5 23 5 24 5 24 5
- djgpp - - - - 14 5 14 5 14 5
- eg 81 62 81 62 81 62 81 62 81 62
- emacs 194 1 204 1 212 2 212 2 212 2
- h2pl 12 12 12 12 12 12 12 12 12 12
- hints 129 69 132 71 144 72 151 74 155 74
- os2 121 42 127 42 127 44 129 44 129 44
- plan9 82 15 82 15 82 15 82 15 82 15
- Porting 94 2 109 4 203 6 234 8 241 9
- qnx 1 2 1 2 1 2 1 2 1 2
- utils 112 8 118 8 124 8 156 9 159 9
- vms 518 34 524 34 538 34 569 34 569 34
- win32 285 33 378 36 470 39 493 39 575 41
- x2p 281 19 281 19 281 19 282 19 281 19
-
- ======================================================================
-
- 5.004_70 5.004_73 5.004_75 5.005 5.005_03
-
- apollo - - - - - - - - 0 1
- beos 1 1 1 1 1 1 1 1 1 1
- Configure 256 1 256 1 264 1 264 1 270 1
- cygwin32 24 5 24 5 24 5 24 5 24 5
- djgpp 14 5 14 5 14 5 14 5 15 5
- eg 86 65 86 65 86 65 86 65 86 65
- emacs 262 2 262 2 262 2 262 2 274 2
- h2pl 12 12 12 12 12 12 12 12 12 12
- hints 157 74 157 74 159 74 160 74 179 77
- mint - - - - - - - - 4 7
- mpeix - - - - 5 3 5 3 5 3
- os2 129 44 139 44 142 44 143 44 148 44
- plan9 82 15 82 15 82 15 82 15 82 15
- Porting 241 9 253 9 259 10 264 12 272 13
- qnx 1 2 1 2 1 2 1 2 1 2
- utils 160 9 160 9 160 9 160 9 164 9
- vms 570 34 572 34 573 34 575 34 583 34
- vos - - - - - - - - 156 10
- win32 577 41 585 41 585 41 587 41 600 42
- x2p 281 19 281 19 281 19 281 19 281 19
-
- ======================================================================
-
- 5.6.0 5.6.1 5.6.2 5.7.3
-
- apollo 8 3 8 3 8 3 8 3
- beos 5 2 5 2 5 2 6 4
- Configure 346 1 361 1 363 1 394 1
- Cross - - - - - - 4 2
- djgpp 19 6 19 6 19 6 21 7
- eg 112 71 112 71 112 71 - -
- emacs 303 4 319 4 319 4 319 4
- epoc 29 8 35 8 35 8 36 8
- h2pl 24 15 24 15 24 15 24 15
- hints 242 83 250 84 321 89 272 87
- mint 11 9 11 9 11 9 11 9
- mpeix 9 4 9 4 9 4 9 4
- NetWare - - - - - - 423 57
- os2 214 59 224 60 224 60 357 66
- plan9 92 17 92 17 92 17 85 15
- Porting 361 15 390 16 390 16 425 21
- qnx 5 3 5 3 5 3 5 3
- utils 228 12 221 11 222 11 267 13
- uts - - - - - - 12 3
- vmesa 25 4 25 4 25 4 25 4
- vms 686 38 627 38 627 38 649 36
- vos 227 12 249 15 248 15 281 17
- win32 755 41 782 42 801 42 1006 50
- x2p 307 20 307 20 307 20 345 20
-
- ======================================================================
-
- 5.8.0 5.8.1 5.8.2 5.8.3 5.8.4
-
- apollo 8 3 8 3 8 3 8 3 8 3
- beos 6 4 6 4 6 4 6 4 6 4
- Configure 472 1 493 1 493 1 493 1 494 1
- Cross 4 2 45 10 45 10 45 10 45 10
- djgpp 21 7 21 7 21 7 21 7 21 7
- emacs 319 4 329 4 329 4 329 4 329 4
- epoc 33 8 33 8 33 8 33 8 33 8
- h2pl 24 15 24 15 24 15 24 15 24 15
- hints 294 88 321 89 321 89 321 89 348 91
- mint 11 9 11 9 11 9 11 9 11 9
- mpeix 24 5 25 5 25 5 25 5 25 5
- NetWare 488 61 490 61 490 61 490 61 488 61
- os2 361 66 445 67 450 67 488 67 488 67
- plan9 85 15 325 17 325 17 325 17 321 17
- Porting 479 22 537 32 538 32 539 32 538 33
- qnx 5 3 5 3 5 3 5 3 5 3
- utils 275 15 258 16 258 16 263 19 263 19
- uts 12 3 12 3 12 3 12 3 12 3
- vmesa 25 4 25 4 25 4 25 4 25 4
- vms 648 36 654 36 654 36 656 36 656 36
- vos 330 20 335 20 335 20 335 20 335 20
- win32 1062 49 1125 49 1127 49 1126 49 1181 56
- x2p 347 20 348 20 348 20 348 20 348 20
-
- ======================================================================
-
- 5.8.5 5.8.6 5.8.7 5.8.8 5.8.9
-
- apollo 8 3 8 3 8 3 8 3 8 3
- beos 6 4 6 4 8 4 8 4 8 4
- Configure 494 1 494 1 495 1 506 1 520 1
- Cross 45 10 45 10 45 10 45 10 46 10
- djgpp 21 7 21 7 21 7 21 7 21 7
- emacs 329 4 329 4 329 4 329 4 406 4
- epoc 33 8 33 8 33 8 34 8 35 8
- h2pl 24 15 24 15 24 15 24 15 24 15
- hints 350 91 352 91 355 94 360 94 387 99
- mint 11 9 11 9 11 9 11 9 11 9
- mpeix 25 5 25 5 25 5 49 6 49 6
- NetWare 488 61 488 61 488 61 490 61 491 61
- os2 488 67 488 67 488 67 488 67 552 70
- plan9 321 17 321 17 321 17 322 17 324 17
- Porting 538 34 548 35 549 35 564 37 625 41
- qnx 5 3 5 3 5 3 5 3 5 3
- utils 265 19 265 19 266 19 267 19 281 21
- uts 12 3 12 3 12 3 12 3 12 3
- vmesa 25 4 25 4 25 4 25 4 25 4
- vms 657 36 658 36 662 36 664 36 716 35
- vos 335 20 335 20 335 20 336 21 345 22
- win32 1183 56 1190 56 1199 56 1219 56 1484 68
- x2p 349 20 349 20 349 20 349 19 350 19
-
- ======================================================================
-
- 5.9.0 5.9.1 5.9.2 5.9.3 5.9.4
-
- apollo 8 3 8 3 8 3 8 3 8 3
- beos 6 4 6 4 8 4 8 4 8 4
- Configure 493 1 493 1 495 1 508 1 512 1
- Cross 45 10 45 10 45 10 45 10 46 10
- djgpp 21 7 21 7 21 7 21 7 21 7
- emacs 329 4 329 4 329 4 329 4 329 4
- epoc 33 8 33 8 33 8 34 8 34 8
- h2pl 24 15 24 15 24 15 24 15 24 15
- hints 321 89 346 91 355 94 359 94 366 96
- mad - - - - - - - - 174 6
- mint 11 9 11 9 11 9 11 9 11 9
- mpeix 25 5 25 5 25 5 49 6 49 6
- NetWare 489 61 487 61 487 61 489 61 489 61
- os2 444 67 488 67 488 67 488 67 488 67
- plan9 325 17 321 17 321 17 322 17 323 17
- Porting 537 32 536 33 549 36 564 38 576 38
- qnx 5 3 5 3 5 3 5 3 5 3
- symbian - - - - - - 293 53 293 53
- utils 258 16 263 19 268 20 273 23 275 24
- uts 12 3 12 3 12 3 12 3 12 3
- vmesa 25 4 25 4 25 4 25 4 25 4
- vms 660 36 547 33 553 33 661 33 696 33
- vos 11 7 11 7 11 7 11 7 11 7
- win32 1120 49 1124 51 1191 56 1209 56 1719 90
- x2p 348 20 348 20 349 20 349 19 349 19
-
- ======================================================================
-
- 5.9.5 5.10.0 5.10.1 5.12.0 5.12.1
-
- apollo 8 3 8 3 0 3 0 3 0 3
- beos 8 4 8 4 4 4 4 4 4 4
- Configure 518 1 518 1 533 1 536 1 536 1
- Cross 122 15 122 15 119 15 118 15 118 15
- djgpp 21 7 21 7 17 7 17 7 17 7
- emacs 329 4 406 4 402 4 402 4 402 4
- epoc 34 8 35 8 31 8 31 8 31 8
- h2pl 24 15 24 15 12 15 12 15 12 15
- hints 377 98 381 98 385 100 368 97 368 97
- mad 182 8 182 8 174 8 174 8 174 8
- mint 11 9 11 9 3 9 - - - -
- mpeix 49 6 49 6 45 6 45 6 45 6
- NetWare 489 61 489 61 465 61 466 61 466 61
- os2 552 70 552 70 507 70 507 70 507 70
- plan9 324 17 324 17 316 17 316 17 316 17
- Porting 627 40 632 40 933 53 749 54 749 54
- qnx 5 3 5 4 1 4 1 4 1 4
- symbian 300 54 300 54 290 54 288 54 288 54
- utils 260 26 264 27 268 27 269 27 269 27
- uts 12 3 12 3 8 3 8 3 8 3
- vmesa 25 4 25 4 21 4 21 4 21 4
- vms 690 32 722 32 693 30 645 18 645 18
- vos 19 8 19 8 16 8 16 8 16 8
- 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 5.14.0 5.16.0 5.18.0
-
- apollo 0 3 0 3 - - - - - -
- beos 4 4 4 4 5 4 5 4 - -
- Configure 536 1 536 1 539 1 547 1 550 1
- Cross 118 15 118 15 118 15 118 15 118 15
- djgpp 17 7 17 7 18 7 18 7 18 7
- emacs 402 4 402 4 - - - - - -
- epoc 31 8 31 8 32 8 30 8 - -
- h2pl 12 15 12 15 15 15 15 15 13 15
- hints 368 97 368 97 370 96 371 96 354 91
- mad 174 8 174 8 176 8 176 8 174 8
- mpeix 45 6 45 6 46 6 46 6 - -
- NetWare 466 61 466 61 473 61 472 61 469 61
- os2 507 70 507 70 518 70 519 70 510 70
- plan9 316 17 316 17 319 17 319 17 318 17
- Porting 750 54 750 54 855 60 1093 69 1149 70
- qnx 1 4 1 4 2 4 2 4 1 4
- symbian 288 54 288 54 292 54 292 54 290 54
- utils 269 27 269 27 249 29 245 30 246 31
- uts 8 3 8 3 9 3 9 3 - -
- vmesa 21 4 21 4 22 4 22 4 - -
- vms 646 18 644 18 639 17 571 15 564 15
- vos 16 8 16 8 17 8 9 7 8 7
- win32 1841 73 1841 73 1833 72 1655 67 1157 62
- x2p 345 19 345 19 346 19 345 19 344 20
-
- ======================================================================
-
- 5.20.0 5.22.0
-
- Configure 552 1 570 1
- Cross 118 15 118 15
- djgpp 18 7 17 7
- h2pl 13 15 13 15
- hints 355 90 356 87
- mad 174 8 - -
- NetWare 467 61 466 61
- os2 510 70 510 70
- plan9 316 17 317 17
- Porting 1204 68 1393 71
- qnx 1 4 1 4
- symbian 290 54 291 54
- utils 241 27 242 27
- vms 538 12 532 12
- vos 8 7 8 7
- win32 1183 64 1201 64
- x2p 341 19 - -
-</pre>
-<hr>
-<a name="perlhist-SELECTED-PATCH-SIZES"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhist-SELECTED-RELEASE-SIZES" accesskey="p"
rel="prev">perlhist SELECTED RELEASE SIZES</a>, Up: <a
href="#perlhist-THE-RECORDS" accesskey="u" rel="up">perlhist THE RECORDS</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SELECTED-PATCH-SIZES"></a>
-<h4 class="subsection">32.5.2 SELECTED PATCH SIZES</h4>
-
-<p>The "diff lines kB" means that for example the patch 5.003_08, to
be
-applied on top of the 5.003_07 (or whatever was before the 5.003_08)
-added lines for 110 kilobytes, it removed lines for 19 kilobytes, and
-changed lines for 424 kilobytes. Just the lines themselves are
-counted, not their context. The "+ - !" become from the diff(1)
-context diff output format.
-</p>
-<pre class="verbatim"> Pump- Release Date diff lines kB
- king -------------
- + - !
- ======================================================================
-
- Chip 5.003_08 1996-Nov-19 110 19 424
- 5.003_09 1996-Nov-26 38 9 248
- 5.003_10 1996-Nov-29 29 2 27
- 5.003_11 1996-Dec-06 73 12 165
- 5.003_12 1996-Dec-19 275 6 436
- 5.003_13 1996-Dec-20 95 1 56
- 5.003_14 1996-Dec-23 23 7 333
- 5.003_15 1996-Dec-23 0 0 1
- 5.003_16 1996-Dec-24 12 3 50
- 5.003_17 1996-Dec-27 19 1 14
- 5.003_18 1996-Dec-31 21 1 32
- 5.003_19 1997-Jan-04 80 3 85
- 5.003_20 1997-Jan-07 18 1 146
- 5.003_21 1997-Jan-15 38 10 221
- 5.003_22 1997-Jan-16 4 0 18
- 5.003_23 1997-Jan-25 71 15 119
- 5.003_24 1997-Jan-29 426 1 20
- 5.003_25 1997-Feb-04 21 8 169
- 5.003_26 1997-Feb-10 16 1 15
- 5.003_27 1997-Feb-18 32 10 38
- 5.003_28 1997-Feb-21 58 4 66
- 5.003_90 1997-Feb-25 22 2 34
- 5.003_91 1997-Mar-01 37 1 39
- 5.003_92 1997-Mar-06 16 3 69
- 5.003_93 1997-Mar-10 12 3 15
- 5.003_94 1997-Mar-22 407 7 200
- 5.003_95 1997-Mar-25 41 1 37
- 5.003_96 1997-Apr-01 283 5 261
- 5.003_97 1997-Apr-03 13 2 34
- 5.003_97a 1997-Apr-05 57 1 27
- 5.003_97b 1997-Apr-08 14 1 20
- 5.003_97c 1997-Apr-10 20 1 16
- 5.003_97d 1997-Apr-13 8 0 16
- 5.003_97e 1997-Apr-15 15 4 46
- 5.003_97f 1997-Apr-17 7 1 33
- 5.003_97g 1997-Apr-18 6 1 42
- 5.003_97h 1997-Apr-24 23 3 68
- 5.003_97i 1997-Apr-25 23 1 31
- 5.003_97j 1997-Apr-28 36 1 49
- 5.003_98 1997-Apr-30 171 12 539
- 5.003_99 1997-May-01 6 0 7
- 5.003_99a 1997-May-09 36 2 61
- p54rc1 1997-May-12 8 1 11
- p54rc2 1997-May-14 6 0 40
-
- 5.004 1997-May-15 4 0 4
-
- Tim 5.004_01 1997-Jun-13 222 14 57
- 5.004_02 1997-Aug-07 112 16 119
- 5.004_03 1997-Sep-05 109 0 17
- 5.004_04 1997-Oct-15 66 8 173
-</pre>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlhist-The-patch_002dfree-era" accesskey="1">perlhist The patch-free
era</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlhist-The-patch_002dfree-era"></a>
-<div class="header">
-<p>
-Up: <a href="#perlhist-SELECTED-PATCH-SIZES" accesskey="u" rel="up">perlhist
SELECTED PATCH SIZES</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-patch_002dfree-era"></a>
-<h4 class="subsubsection">32.5.2.1 The patch-free era</h4>
-
-<p>In more modern times, named releases don’t come as often, and as
progress
-can be followed (nearly) instantly (with rsync, and since late 2008, git)
-patches between versions are no longer provided. However, that doesn’t
-keep us from calculating how large a patch could have been. Which is
-shown in the table below. Unless noted otherwise, the size mentioned is
-the patch to bring version x.y.z to x.y.z+1.
-</p>
-<pre class="verbatim"> Sarathy 5.6.1 2001-Apr-08 531 44 651
- Rafael 5.6.2 2003-Nov-15 20 11 1819
-
- Jarkko 5.8.0 2002-Jul-18 1205 31 471 From 5.7.3
-
- 5.8.1 2003-Sep-25 243 102 6162
- Nicholas 5.8.2 2003-Nov-05 10 50 788
- 5.8.3 2004-Jan-14 31 13 360
- 5.8.4 2004-Apr-21 33 8 299
- 5.8.5 2004-Jul-19 11 19 255
- 5.8.6 2004-Nov-27 35 3 192
- 5.8.7 2005-May-30 75 34 778
- 5.8.8 2006-Jan-31 131 42 1251
- 5.8.9 2008-Dec-14 340 132 12988
-
- Hugo 5.9.0 2003-Oct-27 281 168 7132 From 5.8.0
- Rafael 5.9.1 2004-Mar-16 57 250 2107
- 5.9.2 2005-Apr-01 720 57 858
- 5.9.3 2006-Jan-28 1124 102 1906
- 5.9.4 2006-Aug-15 896 60 862
- 5.9.5 2007-Jul-07 1149 128 1062
-
- 5.10.0 2007-Dec-18 50 31 13111 From 5.9.5
-</pre>
-<hr>
-<a name="perlhist-THE-KEEPERS-OF-THE-RECORDS"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlhist-THE-RECORDS" accesskey="p" rel="prev">perlhist
THE RECORDS</a>, Up: <a href="#perlhist" accesskey="u" rel="up">perlhist</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="THE-KEEPERS-OF-THE-RECORDS"></a>
-<h3 class="section">32.6 THE KEEPERS OF THE RECORDS</h3>
-
-<p>Jarkko Hietaniemi <<samp>address@hidden</samp>>.
-</p>
-<p>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,
-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.
-</p>
-<hr>
-<a name="perlinterp"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro" accesskey="n" rel="next">perlintro</a>, Previous:
<a href="#perlhist" accesskey="p" rel="prev">perlhist</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlinterp-1"></a>
-<h2 class="chapter">33 perlinterp</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlinterp-NAME"
accesskey="1">perlinterp NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlinterp-DESCRIPTION"
accesskey="2">perlinterp DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-ELEMENTS-OF-THE-INTERPRETER" accesskey="3">perlinterp
ELEMENTS OF THE INTERPRETER</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlinterp-OP-TREES"
accesskey="4">perlinterp OP TREES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlinterp-STACKS"
accesskey="5">perlinterp STACKS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-MILLIONS-OF-MACROS" accesskey="6">perlinterp MILLIONS OF
MACROS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlinterp-FURTHER-READING"
accesskey="7">perlinterp FURTHER READING</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlinterp-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlinterp-DESCRIPTION" accesskey="n" rel="next">perlinterp
DESCRIPTION</a>, Up: <a href="#perlinterp" accesskey="u"
rel="up">perlinterp</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-32"></a>
-<h3 class="section">33.1 NAME</h3>
-
-<p>perlinterp - An overview of the Perl interpreter
-</p>
-<hr>
-<a name="perlinterp-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlinterp-ELEMENTS-OF-THE-INTERPRETER" accesskey="n"
rel="next">perlinterp ELEMENTS OF THE INTERPRETER</a>, Previous: <a
href="#perlinterp-NAME" accesskey="p" rel="prev">perlinterp NAME</a>, Up: <a
href="#perlinterp" accesskey="u" rel="up">perlinterp</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-32"></a>
-<h3 class="section">33.2 DESCRIPTION</h3>
-
-<p>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.
-</p>
-<hr>
-<a name="perlinterp-ELEMENTS-OF-THE-INTERPRETER"></a>
-<div class="header">
-<p>
-Next: <a href="#perlinterp-OP-TREES" accesskey="n" rel="next">perlinterp OP
TREES</a>, Previous: <a href="#perlinterp-DESCRIPTION" accesskey="p"
rel="prev">perlinterp DESCRIPTION</a>, Up: <a href="#perlinterp" accesskey="u"
rel="up">perlinterp</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="ELEMENTS-OF-THE-INTERPRETER"></a>
-<h3 class="section">33.3 ELEMENTS OF THE INTERPRETER</h3>
-
-<p>The work of the interpreter has two main stages: compiling the code
-into the internal representation, or bytecode, and then executing it.
-<a href="#perlguts-Compiled-code">perlguts Compiled code</a> explains exactly
how the compilation stage
-happens.
-</p>
-<p>Here is a short breakdown of perl’s operation:
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlinterp-Startup"
accesskey="1">perlinterp Startup</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlinterp-Parsing"
accesskey="2">perlinterp Parsing</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlinterp-Optimization"
accesskey="3">perlinterp Optimization</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlinterp-Running"
accesskey="4">perlinterp Running</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-Exception-handing" accesskey="5">perlinterp Exception
handing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlinterp-INTERNAL-VARIABLE-TYPES" accesskey="6">perlinterp INTERNAL
VARIABLE TYPES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlinterp-Startup"></a>
-<div class="header">
-<p>
-Next: <a href="#perlinterp-Parsing" accesskey="n" rel="next">perlinterp
Parsing</a>, Up: <a href="#perlinterp-ELEMENTS-OF-THE-INTERPRETER"
accesskey="u" rel="up">perlinterp ELEMENTS OF THE INTERPRETER</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Startup"></a>
-<h4 class="subsection">33.3.1 Startup</h4>
-
-<p>The action begins in <samp>perlmain.c</samp>. (or
<samp>miniperlmain.c</samp> for miniperl)
-This is very high-level code, enough to fit on a single screen, and it
-resembles the code found in <a href="#perlembed-NAME">perlembed NAME</a>; most
of the real action takes
-place in <samp>perl.c</samp>
-</p>
-<p><samp>perlmain.c</samp> is generated by <code>ExtUtils::Miniperl</code> from
-<samp>miniperlmain.c</samp> at make time, so you should make perl to follow
this
-along.
-</p>
-<p>First, <samp>perlmain.c</samp> allocates some memory and constructs a Perl
-interpreter, along these lines:
-</p>
-<pre class="verbatim"> 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 }
-</pre>
-<p>Line 1 is a macro, and its definition is dependent on your operating
-system. Line 3 references <code>PL_do_undump</code>, a global variable - all
-global variables in Perl start with <code>PL_</code>. This tells you whether
the
-current running program was created with the <code>-u</code> flag to perl and
-then <samp>undump</samp>, which means it’s going to be false in any sane
context.
-</p>
-<p>Line 4 calls a function in <samp>perl.c</samp> to allocate memory for a Perl
-interpreter. It’s quite a simple function, and the guts of it looks
-like this:
-</p>
-<pre class="verbatim"> my_perl =
(PerlInterpreter*)PerlMem_malloc(sizeof(PerlInterpreter));
-</pre>
-<p>Here you see an example of Perl’s system abstraction, which
we’ll see
-later: <code>PerlMem_malloc</code> is either your system’s
<code>malloc</code>, or Perl’s
-own <code>malloc</code> as defined in <samp>malloc.c</samp> if you selected
that option at
-configure time.
-</p>
-<p>Next, in line 7, we construct the interpreter using perl_construct,
-also in <samp>perl.c</samp>; this sets up all the special variables that Perl
-needs, the stacks, and so on.
-</p>
-<p>Now we pass Perl the command line options, and tell it to go:
-</p>
-<pre class="verbatim"> 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);
-</pre>
-<p><code>perl_parse</code> is actually a wrapper around
<code>S_parse_body</code>, as defined
-in <samp>perl.c</samp>, which processes the command line options, sets up any
-statically linked XS modules, opens the program and calls <code>yyparse</code>
to
-parse it.
-</p>
-<hr>
-<a name="perlinterp-Parsing"></a>
-<div class="header">
-<p>
-Next: <a href="#perlinterp-Optimization" accesskey="n" rel="next">perlinterp
Optimization</a>, Previous: <a href="#perlinterp-Startup" accesskey="p"
rel="prev">perlinterp Startup</a>, Up: <a
href="#perlinterp-ELEMENTS-OF-THE-INTERPRETER" accesskey="u"
rel="up">perlinterp ELEMENTS OF THE INTERPRETER</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Parsing"></a>
-<h4 class="subsection">33.3.2 Parsing</h4>
-
-<p>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.
-</p>
-<p><code>yyparse</code>, the parser, lives in <samp>perly.c</samp>, although
you’re better off
-reading the original YACC input in <samp>perly.y</samp>. (Yes, Virginia, there
-<strong>is</strong> 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.
-</p>
-<p>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 <code>yylex</code>, and that and
its
-associated routines can be found in <samp>toke.c</samp>. 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.
-</p>
-<p>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 <samp>op.c</samp>, and will be examined later.
-</p>
-<hr>
-<a name="perlinterp-Optimization"></a>
-<div class="header">
-<p>
-Next: <a href="#perlinterp-Running" accesskey="n" rel="next">perlinterp
Running</a>, Previous: <a href="#perlinterp-Parsing" accesskey="p"
rel="prev">perlinterp Parsing</a>, Up: <a
href="#perlinterp-ELEMENTS-OF-THE-INTERPRETER" accesskey="u"
rel="up">perlinterp ELEMENTS OF THE INTERPRETER</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Optimization"></a>
-<h4 class="subsection">33.3.3 Optimization</h4>
-
-<p>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 <code>3 + 4</code> 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
-<code>$foo</code>, instead of grabbing the glob <code>*foo</code> 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
<code>peep</code>
-in <samp>op.c</samp>, and many ops have their own optimizing functions.
-</p>
-<hr>
-<a name="perlinterp-Running"></a>
-<div class="header">
-<p>
-Next: <a href="#perlinterp-Exception-handing" accesskey="n"
rel="next">perlinterp Exception handing</a>, Previous: <a
href="#perlinterp-Optimization" accesskey="p" rel="prev">perlinterp
Optimization</a>, Up: <a href="#perlinterp-ELEMENTS-OF-THE-INTERPRETER"
accesskey="u" rel="up">perlinterp ELEMENTS OF THE INTERPRETER</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Running"></a>
-<h4 class="subsection">33.3.4 Running</h4>
-
-<p>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
-<code>runops_standard</code> function in <samp>run.c</samp>; more
specifically, it’s done
-by these three innocent looking lines:
-</p>
-<pre class="verbatim"> while ((PL_op = PL_op->op_ppaddr(aTHX))) {
- PERL_ASYNC_CHECK();
- }
-</pre>
-<p>You may be more comfortable with the Perl version of that:
-</p>
-<pre class="verbatim"> PERL_ASYNC_CHECK() while $Perl::op =
&{$Perl::op->{function}};
-</pre>
-<p>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 <code>if</code> which choose the next op dynamically at run time.
The
-<code>PERL_ASYNC_CHECK</code> makes sure that things like signals interrupt
-execution if required.
-</p>
-<p>The actual functions called are known as PP code, and they’re spread
-between four files: <samp>pp_hot.c</samp> contains the "hot" code,
which is most
-often used and highly optimized, <samp>pp_sys.c</samp> contains all the
-system-specific functions, <samp>pp_ctl.c</samp> contains the functions which
-implement control structures (<code>if</code>, <code>while</code> and the
like) and <samp>pp.c</samp>
-contains everything else. These are, if you like, the C code for Perl’s
-built-in functions and operators.
-</p>
-<p>Note that each <code>pp_</code> 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, <code>pp_entersub</code> and <code>pp_entertry</code> just push a
<code>CxSUB</code> or
-<code>CxEVAL</code> 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 <code>pp_leavesub</code> or <code>pp_leavetry</code> op pops
the <code>CxSUB</code>
-or <code>CxEVAL</code>, retrieves the return op from it, and returns it.
-</p>
-<hr>
-<a name="perlinterp-Exception-handing"></a>
-<div class="header">
-<p>
-Next: <a href="#perlinterp-INTERNAL-VARIABLE-TYPES" accesskey="n"
rel="next">perlinterp INTERNAL VARIABLE TYPES</a>, Previous: <a
href="#perlinterp-Running" accesskey="p" rel="prev">perlinterp Running</a>, Up:
<a href="#perlinterp-ELEMENTS-OF-THE-INTERPRETER" accesskey="u"
rel="up">perlinterp ELEMENTS OF THE INTERPRETER</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Exception-handing"></a>
-<h4 class="subsection">33.3.5 Exception handing</h4>
-
-<p>Perl’s exception handing (i.e. <code>die</code> etc.) is built on top
of the
-low-level <code>setjmp()</code>/<code>longjmp()</code> C-library functions.
These basically
-provide a way to capture the current PC and SP registers and later
-restore them; i.e. a <code>longjmp()</code> continues at the point in code
where
-a previous <code>setjmp()</code> was done, with anything further up on the C
-stack being lost. This is why code should always save values using
-<code>SAVE_FOO</code> rather than in auto variables.
-</p>
-<p>The perl core wraps <code>setjmp()</code> etc in the macros
<code>JMPENV_PUSH</code> and
-<code>JMPENV_JUMP</code>. The basic rule of perl exceptions is that
<code>exit</code>, and
-<code>die</code> (in the absence of <code>eval</code>) perform a
<code>JMPENV_JUMP(2)</code>, while
-<code>die</code> within <code>eval</code> does a <code>JMPENV_JUMP(3)</code>.
-</p>
-<p>At entry points to perl, such as <code>perl_parse()</code>,
<code>perl_run()</code> and
-<code>call_sv(cv, G_EVAL)</code> each does a <code>JMPENV_PUSH</code>, 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
-<code>CHECK</code> or <code>END</code> blocks. Amongst other things, this is
how scope
-cleanup still occurs during an <code>exit</code>.
-</p>
-<p>If a <code>die</code> can find a <code>CxEVAL</code> block on the context
stack, then the
-stack is popped to that level and the return op in that block is
-assigned to <code>PL_restartop</code>; then a <code>JMPENV_JUMP(3)</code> is
performed.
-This normally passes control back to the guard. In the case of
-<code>perl_run</code> and <code>call_sv</code>, a non-null
<code>PL_restartop</code> triggers
-re-entry to the runops loop. The is the normal way that <code>die</code> or
-<code>croak</code> is handled within an <code>eval</code>.
-</p>
-<p>Sometimes ops are executed within an inner runops loop, such as tie,
-sort or overload code. In this case, something like
-</p>
-<pre class="verbatim"> sub FETCH { eval { die } }
-</pre>
-<p>would cause a longjmp right back to the guard in <code>perl_run</code>,
popping
-both runops loops, which is clearly incorrect. One way to avoid this is
-for the tie code to do a <code>JMPENV_PUSH</code> before executing
<code>FETCH</code> in
-the inner runops loop, but for efficiency reasons, perl in fact just
-sets a flag, using <code>CATCH_SET(TRUE)</code>. The <code>pp_require</code>,
-<code>pp_entereval</code> and <code>pp_entertry</code> ops check this flag,
and if true,
-they call <code>docatch</code>, which does a <code>JMPENV_PUSH</code> and
starts a new
-runops level to execute the code, rather than doing it on the current
-loop.
-</p>
-<p>As a further optimisation, on exit from the eval block in the
<code>FETCH</code>,
-execution of the code following the block is still carried on in the
-inner loop. When an exception is raised, <code>docatch</code> compares the
-<code>JMPENV</code> level of the <code>CxEVAL</code> with
<code>PL_top_env</code> and if they differ,
-just re-throws the exception. In this way any inner loops get popped.
-</p>
-<p>Here’s an example.
-</p>
-<pre class="verbatim"> 1: eval { tie @a, 'A' };
- 2: sub A::TIEARRAY {
- 3: eval { die };
- 4: die;
- 5: }
-</pre>
-<p>To run this code, <code>perl_run</code> is called, which does a
<code>JMPENV_PUSH</code>
-then enters a runops loop. This loop executes the eval and tie ops on
-line 1, with the eval pushing a <code>CxEVAL</code> onto the context stack.
-</p>
-<p>The <code>pp_tie</code> does a <code>CATCH_SET(TRUE)</code>, then starts a
second runops
-loop to execute the body of <code>TIEARRAY</code>. When it executes the
entertry
-op on line 3, <code>CATCH_GET</code> is true, so <code>pp_entertry</code>
calls <code>docatch</code>
-which does a <code>JMPENV_PUSH</code> and starts a third runops loop, which
then
-executes the die op. At this point the C call stack looks like this:
-</p>
-<pre class="verbatim"> 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
-</pre>
-<p>and the context and data stacks, as shown by <code>-Dstv</code>, look like:
-</p>
-<pre class="verbatim"> 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
-</pre>
-<p>The die pops the first <code>CxEVAL</code> off the context stack, sets
-<code>PL_restartop</code> from it, does a <code>JMPENV_JUMP(3)</code>, and
control returns
-to the top <code>docatch</code>. 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 <code>pp_die</code> 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:
-</p>
-<pre class="verbatim"> STACK 0: MAIN
- CX 0: BLOCK =>
- CX 1: EVAL => AV() PV("A"\0)
- retop=leave
- STACK 1: MAGIC
- CX 0: SUB =>
- retop=(null)
-</pre>
-<p>The die on line 4 pops the context stack back down to the CxEVAL,
-leaving it as:
-</p>
-<pre class="verbatim"> STACK 0: MAIN
- CX 0: BLOCK =>
-</pre>
-<p>As usual, <code>PL_restartop</code> is extracted from the
<code>CxEVAL</code>, and a
-<code>JMPENV_JUMP(3)</code> done, which pops the C stack back to the docatch:
-</p>
-<pre class="verbatim"> 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
-</pre>
-<p>In this case, because the <code>JMPENV</code> level recorded in the
<code>CxEVAL</code>
-differs from the current one, <code>docatch</code> just does a
<code>JMPENV_JUMP(3)</code>
-and the C stack unwinds to:
-</p>
-<pre class="verbatim"> perl_run
- main
-</pre>
-<p>Because <code>PL_restartop</code> is non-null, <code>run_body</code> starts
a new runops
-loop and execution continues.
-</p>
-<hr>
-<a name="perlinterp-INTERNAL-VARIABLE-TYPES"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlinterp-Exception-handing" accesskey="p"
rel="prev">perlinterp Exception handing</a>, Up: <a
href="#perlinterp-ELEMENTS-OF-THE-INTERPRETER" accesskey="u"
rel="up">perlinterp ELEMENTS OF THE INTERPRETER</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="INTERNAL-VARIABLE-TYPES"></a>
-<h4 class="subsection">33.3.6 INTERNAL VARIABLE TYPES</h4>
-
-<p>You should by now have had a look at <a href="#perlguts-NAME">perlguts
NAME</a>, which tells you about
-Perl’s internal variable types: SVs, HVs, AVs and the rest. If not, do
-that now.
-</p>
-<p>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.
-</p>
-<p>The core <a href="Devel-Peek.html#Top">(Devel-Peek)Devel::Peek</a> module
lets us examine SVs from a
-Perl program. Let’s see, for instance, how Perl treats the constant
-<code>"hello"</code>.
-</p>
-<pre class="verbatim"> % 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
-</pre>
-<p>Reading <code>Devel::Peek</code> output takes a bit of practise, so
let’s go
-through it line by line.
-</p>
-<p>Line 1 tells us we’re looking at an SV which lives at
<code>0xa04ecbc</code> 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 <code>0xa041450</code>. Line
2
-is the reference count; there are no other references to this data, so
-it’s 1.
-</p>
-<p>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
-<code>0xa0484e0</code>.
-</p>
-<p>Line 5 gives us the current length of the string - note that this does
-<strong>not</strong> 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 <code>SvGROW</code>.
-</p>
-<p>You can get at any of these quantities from C very easily; just add
-<code>Sv</code> to the name of the field shown in the snippet, and
you’ve got a
-macro which will return the value: <code>SvCUR(sv)</code> returns the current
-length of the string, <code>SvREFCOUNT(sv)</code> returns the reference count,
-<code>SvPV(sv, len)</code> returns the string itself with its length, and so
on.
-More macros to manipulate these properties can be found in <a
href="#perlguts-NAME">perlguts NAME</a>.
-</p>
-<p>Let’s take an example of manipulating a PV, from
<code>sv_catpvn</code>, in
-<samp>sv.c</samp>
-</p>
-<pre class="verbatim"> 1 void
- 2 Perl_sv_catpvn(pTHX_ SV *sv, const char *ptr, 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 }
-</pre>
-<p>This is a function which adds a string, <code>ptr</code>, of length
<code>len</code> onto
-the end of the PV stored in <code>sv</code>. The first thing we do in line 6 is
-make sure that the SV <strong>has</strong> a valid PV, by calling the
<code>SvPV_force</code>
-macro to force a PV. As a side effect, <code>tlen</code> gets set to the
current
-value of the PV, and the PV itself is returned to <code>junk</code>.
-</p>
-<p>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
-<code>LEN</code> isn’t big enough, <code>SvGROW</code> will reallocate
space for us.
-</p>
-<p>Now, if <code>junk</code> is the same as the string we’re trying to
add, we can
-grab the string directly from the SV; <code>SvPVX</code> is the address of the
PV
-in the SV.
-</p>
-<p>Line 10 does the actual catenation: the <code>Move</code> macro moves a
chunk of
-memory around: we move the string <code>ptr</code> to the end of the PV -
that’s
-the start of the PV plus its current length. We’re moving
<code>len</code> bytes
-of type <code>char</code>. After doing so, we need to tell Perl we’ve
extended
-the string, by altering <code>CUR</code> to reflect the new length.
<code>SvEND</code> is a
-macro which gives us the end of the string, so that needs to be a
-<code>"\0"</code>.
-</p>
-<p>Line 13 manipulates the flags; since we’ve changed the PV, any IV or
NV
-values will no longer be valid: if we have <code>$a=10;
$a.="6";</code> we don’t
-want to use the old IV of 10. <code>SvPOK_only_utf8</code> is a special
-UTF-8-aware version of <code>SvPOK_only</code>, a macro which turns off the IOK
-and NOK flags and turns on POK. The final <code>SvTAINT</code> is a macro which
-launders tainted data if taint mode is turned on.
-</p>
-<p>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.
-</p>
-<hr>
-<a name="perlinterp-OP-TREES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlinterp-STACKS" accesskey="n" rel="next">perlinterp
STACKS</a>, Previous: <a href="#perlinterp-ELEMENTS-OF-THE-INTERPRETER"
accesskey="p" rel="prev">perlinterp ELEMENTS OF THE INTERPRETER</a>, Up: <a
href="#perlinterp" accesskey="u" rel="up">perlinterp</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="OP-TREES"></a>
-<h3 class="section">33.4 OP TREES</h3>
-
-<p>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 <a href="#perlinterp-Running">Running</a>.
-</p>
-<p>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.
-</p>
-<p>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.
-</p>
-<p>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 <a href="B-Terse.html#Top">(B-Terse)B::Terse</a>, <a
href="B-Concise.html#Top">(B-Concise)B::Concise</a>
-and <a href="B-Debug.html#Top">(B-Debug)B::Debug</a> do.
-</p>
-<p>Let’s have a look at how Perl sees <code>$a = $b + $c</code>:
-</p>
-<pre class="verbatim"> % 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
-</pre>
-<p>Let’s start in the middle, at line 4. This is a BINOP, a binary
-operator, which is at location <code>0x8179828</code>. The specific operator in
-question is <code>sassign</code> - scalar assignment - and you can find the
code
-which implements it in the function <code>pp_sassign</code> in
<samp>pp_hot.c</samp>. As a
-binary operator, it has two children: the add operator, providing the
-result of <code>$b+$c</code>, is uppermost on line 5, and the left hand side is
-on line 10.
-</p>
-<p>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 <a
href="#perlinterp-Optimization">Optimization</a>, 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:
-</p>
-<pre class="verbatim"> 10 SVOP (0x816b4f0) rv2sv [15]
- 11 SVOP (0x816dcf0) gv GV (0x80fa460) *a
-</pre>
-<p>That is, fetch the <code>a</code> entry from the main symbol table, and
then look
-at the scalar component of it: <code>gvsv</code> (<code>pp_gvsv</code> into
<samp>pp_hot.c</samp>)
-happens to do both these things.
-</p>
-<p>The right hand side, starting at line 5 is similar to what we’ve just
-seen: we have the <code>add</code> op (<code>pp_add</code> also in
<samp>pp_hot.c</samp>) add
-together two <code>gvsv</code>s.
-</p>
-<p>Now, what’s this about?
-</p>
-<pre class="verbatim"> 1 LISTOP (0x8179888) leave
- 2 OP (0x81798b0) enter
- 3 COP (0x8179850) nextstate
-</pre>
-<p><code>enter</code> and <code>leave</code> 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: <code>leave</code> is a list, and
its
-children are all the statements in the block. Statements are delimited
-by <code>nextstate</code>, so a block is a collection of
<code>nextstate</code> ops, with
-the ops to be performed for each statement being the children of
-<code>nextstate</code>. <code>enter</code> is a single op which functions as a
marker.
-</p>
-<p>That’s how Perl parsed the program, from top to bottom:
-</p>
-<pre class="verbatim"> Program
- |
- Statement
- |
- =
- / \
- / \
- $a +
- / \
- $b $c
-</pre>
-<p>However, it’s impossible to <strong>perform</strong> the operations
in this order:
-you have to find the values of <code>$b</code> and <code>$c</code> 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 <code>op_next</code> 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 <code>exec</code> option to <code>B::Terse</code>:
-</p>
-<pre class="verbatim"> % 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
-</pre>
-<p>This probably makes more sense for a human: enter a block, start a
-statement. Get the values of <code>$b</code> and <code>$c</code>, and add them
together.
-Find <code>$a</code>, and assign one to the other. Then leave.
-</p>
-<p>The way Perl builds up these op trees in the parsing process can be
-unravelled by examining <samp>perly.y</samp>, the YACC grammar. Let’s
take the
-piece we need to construct the tree for <code>$a = $b + $c</code>
-</p>
-<pre class="verbatim"> 1 term : term ASSIGNOP term
- 2 { $$ = newASSIGNOP(OPf_STACKED, $1, $2, $3); }
- 3 | term ADDOP term
- 4 { $$ = newBINOP($2, 0, scalar($1), scalar($3)); }
-</pre>
-<p>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, <code>ADDOP</code>, is provided when the tokeniser sees
<code>+</code> in
-your code. <code>ASSIGNOP</code> is provided when <code>=</code> is used for
assigning.
-These are "terminal symbols", because you can’t get any
simpler than
-them.
-</p>
-<p>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. <code>term</code> here is a
-non-terminal symbol, representing a single expression.
-</p>
-<p>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, <code>term</code> followed by
<code>=</code>
-followed by <code>term</code> makes a <code>term</code>, and <code>term</code>
followed by <code>+</code>
-followed by <code>term</code> can also make a <code>term</code>.
-</p>
-<p>So, if you see two terms with an <code>=</code> or <code>+</code>, 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 <code>=</code>, you’ll do
the code
-in line 2. If you see <code>+</code>, you’ll do the code in line 4.
It’s this
-code which contributes to the op tree.
-</p>
-<pre class="verbatim"> | term ADDOP term
- { $$ = newBINOP($2, 0, scalar($1), scalar($3)); }
-</pre>
-<p>What this does is creates a new binary op, and feeds it a number of
-variables. The variables refer to the tokens: <code>$1</code> is the first
token
-in the input, <code>$2</code> the second, and so on - think regular expression
-backreferences. <code>$$</code> is the op returned from this reduction. So, we
-call <code>newBINOP</code> to create a new binary operator. The first parameter
-to <code>newBINOP</code>, a function in <samp>op.c</samp>, is the op type.
It’s an addition
-operator, so we want the type to be <code>ADDOP</code>. We could specify this
-directly, but it’s right there as the second token in the input, so we
-use <code>$2</code>. 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.
-</p>
-<hr>
-<a name="perlinterp-STACKS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlinterp-MILLIONS-OF-MACROS" accesskey="n"
rel="next">perlinterp MILLIONS OF MACROS</a>, Previous: <a
href="#perlinterp-OP-TREES" accesskey="p" rel="prev">perlinterp OP TREES</a>,
Up: <a href="#perlinterp" accesskey="u" rel="up">perlinterp</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="STACKS"></a>
-<h3 class="section">33.5 STACKS</h3>
-
-<p>When perl executes something like <code>addop</code>, 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.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlinterp-Argument-stack"
accesskey="1">perlinterp Argument stack</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlinterp-Mark-stack"
accesskey="2">perlinterp Mark stack</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlinterp-Save-stack"
accesskey="3">perlinterp Save stack</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlinterp-Argument-stack"></a>
-<div class="header">
-<p>
-Next: <a href="#perlinterp-Mark-stack" accesskey="n" rel="next">perlinterp
Mark stack</a>, Up: <a href="#perlinterp-STACKS" accesskey="u"
rel="up">perlinterp STACKS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Argument-stack"></a>
-<h4 class="subsection">33.5.1 Argument stack</h4>
-
-<p>Arguments are passed to PP code and returned from PP code using the
-argument stack, <code>ST</code>. 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:
-</p>
-<pre class="verbatim"> NV value;
- value = POPn;
- value = Perl_cos(value);
- XPUSHn(value);
-</pre>
-<p>We’ll see a more tricky example of this when we consider Perl’s
macros
-below. <code>POPn</code> gives you the NV (floating point value) of the top SV
on
-the stack: the <code>$x</code> in <code>cos($x)</code>. Then we compute the
cosine, and
-push the result back as an NV. The <code>X</code> in <code>XPUSHn</code> 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 <code>XPUSH*</code> macros at least
guarantee safety.
-</p>
-<p>Alternatively, you can fiddle with the stack directly: <code>SP</code>
gives you
-the first element in your portion of the stack, and <code>TOP*</code> gives you
-the top SV/IV/NV/etc. on the stack. So, for instance, to do unary
-negation of an integer:
-</p>
-<pre class="verbatim"> SETi(-TOPi);
-</pre>
-<p>Just set the integer value of the top stack entry to its negation.
-</p>
-<p>Argument stack manipulation in the core is exactly the same as it is in
-XSUBs - see <a href="perlxstut.html#Top">(perlxstut)</a>, <a
href="perlxs.html#Top">(perlxs)</a> and <a href="#perlguts-NAME">perlguts
NAME</a> for a longer
-description of the macros used in stack manipulation.
-</p>
-<hr>
-<a name="perlinterp-Mark-stack"></a>
-<div class="header">
-<p>
-Next: <a href="#perlinterp-Save-stack" accesskey="n" rel="next">perlinterp
Save stack</a>, Previous: <a href="#perlinterp-Argument-stack" accesskey="p"
rel="prev">perlinterp Argument stack</a>, Up: <a href="#perlinterp-STACKS"
accesskey="u" rel="up">perlinterp STACKS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Mark-stack"></a>
-<h4 class="subsection">33.5.2 Mark stack</h4>
-
-<p>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 <code>push</code> is implemented; see
<code>av_push</code> in
-<samp>av.c</samp>:
-</p>
-<pre class="verbatim"> 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;
-</pre>
-<p>Let’s examine the whole implementation, for practice:
-</p>
-<pre class="verbatim"> 1 PUSHMARK(SP);
-</pre>
-<p>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.
-</p>
-<pre class="verbatim"> 2 EXTEND(SP,2);
- 3 PUSHs(SvTIED_obj((SV*)av, mg));
- 4 PUSHs(val);
-</pre>
-<p>We’re going to add two more items onto the argument stack: when you
-have a tied array, the <code>PUSH</code> subroutine receives the object and the
-value to be pushed, and that’s exactly what we have here - the tied
-object, retrieved with <code>SvTIED_obj</code>, and the value, the SV
<code>val</code>.
-</p>
-<pre class="verbatim"> 5 PUTBACK;
-</pre>
-<p>Next we tell Perl to update the global stack pointer from our internal
-variable: <code>dSP</code> only gave us a local copy, not a reference to the
-global.
-</p>
-<pre class="verbatim"> 6 ENTER;
- 7 call_method("PUSH", G_SCALAR|G_DISCARD);
- 8 LEAVE;
-</pre>
-<p><code>ENTER</code> and <code>LEAVE</code> 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 <code>{</code> and
-<code>}</code> of a Perl block.
-</p>
-<p>To actually do the magic method call, we have to call a subroutine in
-Perl space: <code>call_method</code> takes care of that, and it’s
described in
-<a href="#perlcall-NAME">perlcall NAME</a>. We call the <code>PUSH</code>
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.
-</p>
-<hr>
-<a name="perlinterp-Save-stack"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlinterp-Mark-stack" accesskey="p" rel="prev">perlinterp
Mark stack</a>, Up: <a href="#perlinterp-STACKS" accesskey="u"
rel="up">perlinterp STACKS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Save-stack"></a>
-<h4 class="subsection">33.5.3 Save stack</h4>
-
-<p>C doesn’t have a concept of local scope, so perl provides one.
We’ve
-seen that <code>ENTER</code> and <code>LEAVE</code> are used as scoping
braces; the save
-stack implements the C equivalent of, for example:
-</p>
-<pre class="verbatim"> {
- local $foo = 42;
- ...
- }
-</pre>
-<p>See <a href="#perlguts-Localizing-changes">perlguts Localizing changes</a>
for how to use the save stack.
-</p>
-<hr>
-<a name="perlinterp-MILLIONS-OF-MACROS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlinterp-FURTHER-READING" accesskey="n"
rel="next">perlinterp FURTHER READING</a>, Previous: <a
href="#perlinterp-STACKS" accesskey="p" rel="prev">perlinterp STACKS</a>, Up:
<a href="#perlinterp" accesskey="u" rel="up">perlinterp</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="MILLIONS-OF-MACROS"></a>
-<h3 class="section">33.6 MILLIONS OF MACROS</h3>
-
-<p>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:
-</p>
-<pre class="verbatim"> 1 PP(pp_add)
- 2 {
- 3 dSP; dATARGET; tryAMAGICbin(add,opASSIGN);
- 4 {
- 5 dPOPTOPnnrl_ul;
- 6 SETn( left + right );
- 7 RETURN;
- 8 }
- 9 }
-</pre>
-<p>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.
-</p>
-<p>Line 5 is another variable declaration - all variable declarations
-start with <code>d</code> - which pops from the top of the argument stack two
NVs
-(hence <code>nn</code>) and puts them into the variables <code>right</code>
and <code>left</code>,
-hence the <code>rl</code>. These are the two operands to the addition operator.
-Next, we call <code>SETn</code> to set the NV of the return value to the result
-of adding the two values. This done, we return - the <code>RETURN</code> macro
-makes sure that our return value is properly handled, and we pass the
-next operator to run back to the main run loop.
-</p>
-<p>Most of these macros are explained in <a
href="perlapi.html#Top">(perlapi)</a>, and some of the more
-important ones are explained in <a href="perlxs.html#Top">(perlxs)</a> as
well. Pay special
-attention to <a
href="#perlguts-Background-and-PERL_005fIMPLICIT_005fCONTEXT">perlguts
Background and PERL_IMPLICIT_CONTEXT</a> for
-information on the <code>[pad]THX_?</code> macros.
-</p>
-<hr>
-<a name="perlinterp-FURTHER-READING"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlinterp-MILLIONS-OF-MACROS" accesskey="p"
rel="prev">perlinterp MILLIONS OF MACROS</a>, Up: <a href="#perlinterp"
accesskey="u" rel="up">perlinterp</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="FURTHER-READING"></a>
-<h3 class="section">33.7 FURTHER READING</h3>
-
-<p>For more information on the Perl internals, please see the documents
-listed at <a href="#perl-Internals-and-C-Language-Interface">perl Internals
and C Language Interface</a>.
-</p>
-<hr>
-<a name="perlintro"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol" accesskey="n" rel="next">perliol</a>, Previous: <a
href="#perlinterp" accesskey="p" rel="prev">perlinterp</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlintro-1"></a>
-<h2 class="chapter">34 perlintro</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlintro-NAME"
accesskey="1">perlintro NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlintro-DESCRIPTION"
accesskey="2">perlintro DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlintro-AUTHOR"
accesskey="3">perlintro AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlintro-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro-DESCRIPTION" accesskey="n" rel="next">perlintro
DESCRIPTION</a>, Up: <a href="#perlintro" accesskey="u" rel="up">perlintro</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-33"></a>
-<h3 class="section">34.1 NAME</h3>
-
-<p>perlintro – a brief introduction and overview of Perl
-</p>
-<hr>
-<a name="perlintro-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro-AUTHOR" accesskey="n" rel="next">perlintro
AUTHOR</a>, Previous: <a href="#perlintro-NAME" accesskey="p"
rel="prev">perlintro NAME</a>, Up: <a href="#perlintro" accesskey="u"
rel="up">perlintro</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-33"></a>
-<h3 class="section">34.2 DESCRIPTION</h3>
-
-<p>This document is intended to give you a quick overview of the Perl
-programming language, along with pointers to further documentation. It
-is intended as a "bootstrap" guide for those who are new to the
-language, and provides just enough information for you to be able to
-read other peoples’ Perl and understand roughly what it’s doing, or
-write your own simple scripts.
-</p>
-<p>This introductory document does not aim to be complete. It does not
-even aim to be entirely accurate. In some cases perfection has been
-sacrificed in the goal of getting the general idea across. You are
-<em>strongly</em> advised to follow this introduction with more information
-from the full Perl manual, the table of contents to which can be found
-in <a href="perltoc.html#Top">(perltoc)</a>.
-</p>
-<p>Throughout this document you’ll see references to other parts of the
-Perl documentation. You can read that documentation using the
<code>perldoc</code>
-command or whatever method you’re using to read this document.
-</p>
-<p>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.
-</p>
-<p>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 <code>use strict</code> and <code>use warnings</code>
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.
-</p>
-<p>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’s
-More Than One Way To Do It" is one of Perl’s mottos. After all, in
your
-journey as a programmer, you are likely to encounter different styles.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlintro-What-is-Perl_003f" accesskey="1">perlintro What is
Perl?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Running-Perl-programs" accesskey="2">perlintro Running Perl
programs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlintro-Safety-net"
accesskey="3">perlintro Safety net</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Basic-syntax-overview" accesskey="4">perlintro Basic syntax
overview</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Perl-variable-types" accesskey="5">perlintro Perl variable
types</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlintro-Variable-scoping"
accesskey="6">perlintro Variable scoping</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Conditional-and-looping-constructs" accesskey="7">perlintro
Conditional and looping constructs</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Builtin-operators-and-functions" accesskey="8">perlintro
Builtin operators and functions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Files-and-I_002fO" accesskey="9">perlintro Files and
I/O</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Regular-expressions">perlintro Regular
expressions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Writing-subroutines">perlintro Writing
subroutines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-OO-Perl">perlintro OO Perl</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlintro-Using-Perl-modules">perlintro Using Perl
modules</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlintro-What-is-Perl_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro-Running-Perl-programs" accesskey="n"
rel="next">perlintro Running Perl programs</a>, Up: <a
href="#perlintro-DESCRIPTION" accesskey="u" rel="up">perlintro DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="What-is-Perl_003f"></a>
-<h4 class="subsection">34.2.1 What is Perl?</h4>
-
-<p>Perl is a general-purpose programming language originally developed for
-text manipulation and now used for a wide range of tasks including
-system administration, web development, network programming, GUI
-development, and more.
-</p>
-<p>The language is intended to be practical (easy to use, efficient,
-complete) rather than beautiful (tiny, elegant, minimal). Its major
-features are that it’s easy to use, supports both procedural and
-object-oriented (OO) programming, has powerful built-in support for text
-processing, and has one of the world’s most impressive collections of
-third-party modules.
-</p>
-<p>Different definitions of Perl are given in <a href="#perl-NAME">perl
NAME</a>, <a href="perlfaq1.html#Top">(perlfaq1)</a> and
-no doubt other places. From this we can determine that Perl is different
-things to different people, but that lots of people think it’s at least
-worth writing about.
-</p>
-<hr>
-<a name="perlintro-Running-Perl-programs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro-Safety-net" accesskey="n" rel="next">perlintro
Safety net</a>, Previous: <a href="#perlintro-What-is-Perl_003f" accesskey="p"
rel="prev">perlintro What is Perl?</a>, Up: <a href="#perlintro-DESCRIPTION"
accesskey="u" rel="up">perlintro DESCRIPTION</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Running-Perl-programs"></a>
-<h4 class="subsection">34.2.2 Running Perl programs</h4>
-
-<p>To run a Perl program from the Unix command line:
-</p>
-<pre class="verbatim"> perl progname.pl
-</pre>
-<p>Alternatively, put this as the first line of your script:
-</p>
-<pre class="verbatim"> #!/usr/bin/env perl
-</pre>
-<p>... and run the script as <samp>/path/to/script.pl</samp>. Of course,
it’ll need
-to be executable first, so <code>chmod 755 script.pl</code> (under Unix).
-</p>
-<p>(This start line assumes you have the <strong>env</strong> program. You
can also put
-directly the path to your perl executable, like in
<code>#!/usr/bin/perl</code>).
-</p>
-<p>For more information, including instructions for other platforms such as
-Windows and Mac OS, read <a href="#perlrun-NAME">perlrun NAME</a>.
-</p>
-<hr>
-<a name="perlintro-Safety-net"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro-Basic-syntax-overview" accesskey="n"
rel="next">perlintro Basic syntax overview</a>, Previous: <a
href="#perlintro-Running-Perl-programs" accesskey="p" rel="prev">perlintro
Running Perl programs</a>, Up: <a href="#perlintro-DESCRIPTION" accesskey="u"
rel="up">perlintro DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Safety-net"></a>
-<h4 class="subsection">34.2.3 Safety net</h4>
-
-<p>Perl by default is very forgiving. In order to make it more robust
-it is recommended to start every program with the following lines:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
- use strict;
- use warnings;
-</pre>
-<p>The two additional lines request from perl to catch various common
-problems in your code. They check different things so you need both. A
-potential problem caught by <code>use strict;</code> will cause your code to
stop
-immediately when it is encountered, while <code>use warnings;</code> will
merely
-give a warning (like the command-line switch <strong>-w</strong>) and let your
code run.
-To read more about them check their respective manual pages at <a
href="strict.html#Top">(strict)</a>
-and <a href="warnings.html#Top">(warnings)</a>.
-</p>
-<hr>
-<a name="perlintro-Basic-syntax-overview"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro-Perl-variable-types" accesskey="n"
rel="next">perlintro Perl variable types</a>, Previous: <a
href="#perlintro-Safety-net" accesskey="p" rel="prev">perlintro Safety net</a>,
Up: <a href="#perlintro-DESCRIPTION" accesskey="u" rel="up">perlintro
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Basic-syntax-overview"></a>
-<h4 class="subsection">34.2.4 Basic syntax overview</h4>
-
-<p>A Perl script or program consists of one or more statements. These
-statements are simply written in the script in a straightforward
-fashion. There is no need to have a <code>main()</code> function or anything
of
-that kind.
-</p>
-<p>Perl statements end in a semi-colon:
-</p>
-<pre class="verbatim"> print "Hello, world";
-</pre>
-<p>Comments start with a hash symbol and run to the end of the line
-</p>
-<pre class="verbatim"> # This is a comment
-</pre>
-<p>Whitespace is irrelevant:
-</p>
-<pre class="verbatim"> print
- "Hello, world"
- ;
-</pre>
-<p>... except inside quoted strings:
-</p>
-<pre class="verbatim"> # this would print with a linebreak in the middle
- print "Hello
- world";
-</pre>
-<p>Double quotes or single quotes may be used around literal strings:
-</p>
-<pre class="verbatim"> print "Hello, world";
- print 'Hello, world';
-</pre>
-<p>However, only double quotes "interpolate" variables and special
-characters such as newlines (<code>\n</code>):
-</p>
-<pre class="verbatim"> print "Hello, $name\n"; # works fine
- print 'Hello, $name\n'; # prints $name\n literally
-</pre>
-<p>Numbers don’t need quotes around them:
-</p>
-<pre class="verbatim"> print 42;
-</pre>
-<p>You can use parentheses for functions’ arguments or omit them
-according to your personal taste. They are only required
-occasionally to clarify issues of precedence.
-</p>
-<pre class="verbatim"> print("Hello, world\n");
- print "Hello, world\n";
-</pre>
-<p>More detailed information about Perl syntax can be found in <a
href="#perlsyn-NAME">perlsyn NAME</a>.
-</p>
-<hr>
-<a name="perlintro-Perl-variable-types"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro-Variable-scoping" accesskey="n" rel="next">perlintro
Variable scoping</a>, Previous: <a href="#perlintro-Basic-syntax-overview"
accesskey="p" rel="prev">perlintro Basic syntax overview</a>, Up: <a
href="#perlintro-DESCRIPTION" accesskey="u" rel="up">perlintro DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Perl-variable-types"></a>
-<h4 class="subsection">34.2.5 Perl variable types</h4>
-
-<p>Perl has three main variable types: scalars, arrays, and hashes.
-</p>
-<dl compact="compact">
-<dt>Scalars</dt>
-<dd><a name="perlintro-Scalars"></a>
-<p>A scalar represents a single value:
-</p>
-<pre class="verbatim"> my $animal = "camel";
- my $answer = 42;
-</pre>
-<p>Scalar values can be strings, integers or floating point numbers, and Perl
-will automatically convert between them as required. There is no need
-to pre-declare your variable types, but you have to declare them using
-the <code>my</code> keyword the first time you use them. (This is one of the
-requirements of <code>use strict;</code>.)
-</p>
-<p>Scalar values can be used in various ways:
-</p>
-<pre class="verbatim"> print $animal;
- print "The animal is $animal\n";
- print "The square of $answer is ", $answer * $answer,
"\n";
-</pre>
-<p>There are a number of "magic" scalars with names that look like
-punctuation or line noise. These special variables are used for all
-kinds of purposes, and are documented in <a href="#perlvar-NAME">perlvar
NAME</a>. The only one you
-need to know about for now is <code>$_</code> which is the "default
variable".
-It’s used as the default argument to a number of functions in Perl, and
-it’s set implicitly by certain looping constructs.
-</p>
-<pre class="verbatim"> print; # prints contents of $_ by default
-</pre>
-</dd>
-<dt>Arrays</dt>
-<dd><a name="perlintro-Arrays"></a>
-<p>An array represents a list of values:
-</p>
-<pre class="verbatim"> my @animals = ("camel", "llama",
"owl");
- my @numbers = (23, 42, 69);
- my @mixed = ("camel", 42, 1.23);
-</pre>
-<p>Arrays are zero-indexed. Here’s how you get at elements in an array:
-</p>
-<pre class="verbatim"> print $animals[0]; # prints
"camel"
- print $animals[1]; # prints "llama"
-</pre>
-<p>The special variable <code>$#array</code> tells you the index of the last
element
-of an array:
-</p>
-<pre class="verbatim"> print $mixed[$#mixed]; # last element, prints 1.23
-</pre>
-<p>You might be tempted to use <code>$#array + 1</code> to tell you how many
items there
-are in an array. Don’t bother. As it happens, using
<code>@array</code> where Perl
-expects to find a scalar value ("in scalar context") will give you
the number
-of elements in the array:
-</p>
-<pre class="verbatim"> if (@animals < 5) { ... }
-</pre>
-<p>The elements we’re getting from the array start with a <code>$</code>
because
-we’re getting just a single value out of the array; you ask for a scalar,
-you get a scalar.
-</p>
-<p>To get multiple values from an array:
-</p>
-<pre class="verbatim"> @animals[0,1]; # gives
("camel", "llama");
- @animals[0..2]; # gives ("camel", "llama",
"owl");
- @animals[1..$#animals]; # gives all except the first element
-</pre>
-<p>This is called an "array slice".
-</p>
-<p>You can do various useful things to lists:
-</p>
-<pre class="verbatim"> my @sorted = sort @animals;
- my @backwards = reverse @numbers;
-</pre>
-<p>There are a couple of special arrays too, such as <code>@ARGV</code> (the
command
-line arguments to your script) and <code>@_</code> (the arguments passed to a
-subroutine). These are documented in <a href="#perlvar-NAME">perlvar NAME</a>.
-</p>
-</dd>
-<dt>Hashes</dt>
-<dd><a name="perlintro-Hashes"></a>
-<p>A hash represents a set of key/value pairs:
-</p>
-<pre class="verbatim"> my %fruit_color = ("apple", "red",
"banana", "yellow");
-</pre>
-<p>You can use whitespace and the <code>=></code> operator to lay them out
more
-nicely:
-</p>
-<pre class="verbatim"> my %fruit_color = (
- apple => "red",
- banana => "yellow",
- );
-</pre>
-<p>To get at hash elements:
-</p>
-<pre class="verbatim"> $fruit_color{"apple"}; # gives
"red"
-</pre>
-<p>You can get at lists of keys and values with <code>keys()</code> and
-<code>values()</code>.
-</p>
-<pre class="verbatim"> my @fruits = keys %fruit_colors;
- my @colors = values %fruit_colors;
-</pre>
-<p>Hashes have no particular internal order, though you can sort the keys
-and loop through them.
-</p>
-<p>Just like special scalars and arrays, there are also special hashes.
-The most well known of these is <code>%ENV</code> which contains environment
-variables. Read all about it (and other special variables) in
-<a href="#perlvar-NAME">perlvar NAME</a>.
-</p>
-</dd>
-</dl>
-
-<p>Scalars, arrays and hashes are documented more fully in <a
href="#perldata-NAME">perldata NAME</a>.
-</p>
-<p>More complex data types can be constructed using references, which allow
-you to build lists and hashes within lists and hashes.
-</p>
-<p>A reference is a scalar value and can refer to any other Perl data
-type. So by storing a reference as the value of an array or hash
-element, you can easily create lists and hashes within lists and
-hashes. The following example shows a 2 level hash of hash
-structure using anonymous hash references.
-</p>
-<pre class="verbatim"> my $variables = {
- scalar => {
- description => "single item",
- sigil => '$',
- },
- array => {
- description => "ordered list of items",
- sigil => '@',
- },
- hash => {
- description => "key/value pairs",
- sigil => '%',
- },
- };
-
- print "Scalars begin with a
$variables->{'scalar'}->{'sigil'}\n";
-</pre>
-<p>Exhaustive information on the topic of references can be found in
-<a href="#perlreftut-NAME">perlreftut NAME</a>, <a
href="#perllol-NAME">perllol NAME</a>, <a href="#perlref-NAME">perlref NAME</a>
and <a href="#perldsc-NAME">perldsc NAME</a>.
-</p>
-<hr>
-<a name="perlintro-Variable-scoping"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro-Conditional-and-looping-constructs" accesskey="n"
rel="next">perlintro Conditional and looping constructs</a>, Previous: <a
href="#perlintro-Perl-variable-types" accesskey="p" rel="prev">perlintro Perl
variable types</a>, Up: <a href="#perlintro-DESCRIPTION" accesskey="u"
rel="up">perlintro DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Variable-scoping"></a>
-<h4 class="subsection">34.2.6 Variable scoping</h4>
-
-<p>Throughout the previous section all the examples have used the syntax:
-</p>
-<pre class="verbatim"> my $var = "value";
-</pre>
-<p>The <code>my</code> is actually not required; you could just use:
-</p>
-<pre class="verbatim"> $var = "value";
-</pre>
-<p>However, the above usage will create global variables throughout your
-program, which is bad programming practice. <code>my</code> creates lexically
-scoped variables instead. The variables are scoped to the block
-(i.e. a bunch of statements surrounded by curly-braces) in which they
-are defined.
-</p>
-<pre class="verbatim"> my $x = "foo";
- my $some_condition = 1;
- if ($some_condition) {
- my $y = "bar";
- print $x; # prints "foo"
- print $y; # prints "bar"
- }
- print $x; # prints "foo"
- print $y; # prints nothing; $y has fallen out of scope
-</pre>
-<p>Using <code>my</code> in combination with a <code>use strict;</code> at the
top of
-your Perl scripts means that the interpreter will pick up certain common
-programming errors. For instance, in the example above, the final
-<code>print $y</code> would cause a compile-time error and prevent you from
-running the program. Using <code>strict</code> is highly recommended.
-</p>
-<hr>
-<a name="perlintro-Conditional-and-looping-constructs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro-Builtin-operators-and-functions" accesskey="n"
rel="next">perlintro Builtin operators and functions</a>, Previous: <a
href="#perlintro-Variable-scoping" accesskey="p" rel="prev">perlintro Variable
scoping</a>, Up: <a href="#perlintro-DESCRIPTION" accesskey="u"
rel="up">perlintro DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Conditional-and-looping-constructs"></a>
-<h4 class="subsection">34.2.7 Conditional and looping constructs</h4>
-
-<p>Perl has most of the usual conditional and looping constructs. As of Perl
-5.10, it even has a case/switch statement (spelled
<code>given</code>/<code>when</code>). See
-<a href="#perlsyn-Switch-Statements">perlsyn Switch Statements</a> for more
details.
-</p>
-<p>The conditions can be any Perl expression. See the list of operators in
-the next section for information on comparison and boolean logic operators,
-which are commonly used in conditional statements.
-</p>
-<dl compact="compact">
-<dt>if</dt>
-<dd><a name="perlintro-if"></a>
-<pre class="verbatim"> if ( condition ) {
- ...
- } elsif ( other condition ) {
- ...
- } else {
- ...
- }
-</pre>
-<p>There’s also a negated version of it:
-</p>
-<pre class="verbatim"> unless ( condition ) {
- ...
- }
-</pre>
-<p>This is provided as a more readable version of <code>if
(!<em>condition</em>)</code>.
-</p>
-<p>Note that the braces are required in Perl, even if you’ve only got one
-line in the block. However, there is a clever way of making your one-line
-conditional blocks more English like:
-</p>
-<pre class="verbatim"> # the traditional way
- if ($zippy) {
- print "Yow!";
- }
-
- # the Perlish post-condition way
- print "Yow!" if $zippy;
- print "We have no bananas" unless $bananas;
-</pre>
-</dd>
-<dt>while</dt>
-<dd><a name="perlintro-while"></a>
-<pre class="verbatim"> while ( condition ) {
- ...
- }
-</pre>
-<p>There’s also a negated version, for the same reason we have
<code>unless</code>:
-</p>
-<pre class="verbatim"> until ( condition ) {
- ...
- }
-</pre>
-<p>You can also use <code>while</code> in a post-condition:
-</p>
-<pre class="verbatim"> print "LA LA LA\n" while 1; # loops
forever
-</pre>
-</dd>
-<dt>for</dt>
-<dd><a name="perlintro-for"></a>
-<p>Exactly like C:
-</p>
-<pre class="verbatim"> for ($i = 0; $i <= $max; $i++) {
- ...
- }
-</pre>
-<p>The C style for loop is rarely needed in Perl since Perl provides
-the more friendly list scanning <code>foreach</code> loop.
-</p>
-</dd>
-<dt>foreach</dt>
-<dd><a name="perlintro-foreach"></a>
-<pre class="verbatim"> foreach (@array) {
- print "This element is $_\n";
- }
-
- print $list[$_] foreach 0 .. $max;
-
- # you don't have to use the default $_ either...
- foreach my $key (keys %hash) {
- print "The value of $key is $hash{$key}\n";
- }
-</pre>
-<p>The <code>foreach</code> keyword is actually a synonym for the
<code>for</code>
-keyword. See <code><a href="#perlsyn-Foreach-Loops">perlsyn Foreach
Loops</a></code>.
-</p>
-</dd>
-</dl>
-
-<p>For more detail on looping constructs (and some that weren’t
mentioned in
-this overview) see <a href="#perlsyn-NAME">perlsyn NAME</a>.
-</p>
-<hr>
-<a name="perlintro-Builtin-operators-and-functions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro-Files-and-I_002fO" accesskey="n"
rel="next">perlintro Files and I/O</a>, Previous: <a
href="#perlintro-Conditional-and-looping-constructs" accesskey="p"
rel="prev">perlintro Conditional and looping constructs</a>, Up: <a
href="#perlintro-DESCRIPTION" accesskey="u" rel="up">perlintro DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Builtin-operators-and-functions"></a>
-<h4 class="subsection">34.2.8 Builtin operators and functions</h4>
-
-<p>Perl comes with a wide selection of builtin functions. Some of the ones
-we’ve already seen include <code>print</code>, <code>sort</code> and
<code>reverse</code>. A list of
-them is given at the start of <a href="#perlfunc-NAME">perlfunc NAME</a> and
you can easily read
-about any given function by using <code>perldoc -f
<em>functionname</em></code>.
-</p>
-<p>Perl operators are documented in full in <a href="#perlop-NAME">perlop
NAME</a>, but here are a few
-of the most common ones:
-</p>
-<dl compact="compact">
-<dt>Arithmetic</dt>
-<dd><a name="perlintro-Arithmetic"></a>
-<pre class="verbatim"> + addition
- - subtraction
- * multiplication
- / division
-</pre>
-</dd>
-<dt>Numeric comparison</dt>
-<dd><a name="perlintro-Numeric-comparison"></a>
-<pre class="verbatim"> == equality
- != inequality
- < less than
- > greater than
- <= less than or equal
- >= greater than or equal
-</pre>
-</dd>
-<dt>String comparison</dt>
-<dd><a name="perlintro-String-comparison"></a>
-<pre class="verbatim"> eq equality
- ne inequality
- lt less than
- gt greater than
- le less than or equal
- ge greater than or equal
-</pre>
-<p>(Why do we have separate numeric and string comparisons? Because we
don’t
-have special variable types, and Perl needs to know whether to sort
-numerically (where 99 is less than 100) or alphabetically (where 100 comes
-before 99).
-</p>
-</dd>
-<dt>Boolean logic</dt>
-<dd><a name="perlintro-Boolean-logic"></a>
-<pre class="verbatim"> && and
- || or
- ! not
-</pre>
-<p>(<code>and</code>, <code>or</code> and <code>not</code> aren’t just
in the above table as descriptions
-of the operators. They’re also supported as operators in their own
-right. They’re more readable than the C-style operators, but have
-different precedence to <code>&&</code> and friends. Check <a
href="#perlop-NAME">perlop NAME</a> for more
-detail.)
-</p>
-</dd>
-<dt>Miscellaneous</dt>
-<dd><a name="perlintro-Miscellaneous"></a>
-<pre class="verbatim"> = assignment
- . string concatenation
- x string multiplication
- .. range operator (creates a list of numbers or strings)
-</pre>
-</dd>
-</dl>
-
-<p>Many operators can be combined with a <code>=</code> as follows:
-</p>
-<pre class="verbatim"> $a += 1; # same as $a = $a + 1
- $a -= 1; # same as $a = $a - 1
- $a .= "\n"; # same as $a = $a . "\n";
-</pre>
-<hr>
-<a name="perlintro-Files-and-I_002fO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro-Regular-expressions" accesskey="n"
rel="next">perlintro Regular expressions</a>, Previous: <a
href="#perlintro-Builtin-operators-and-functions" accesskey="p"
rel="prev">perlintro Builtin operators and functions</a>, Up: <a
href="#perlintro-DESCRIPTION" accesskey="u" rel="up">perlintro DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Files-and-I_002fO"></a>
-<h4 class="subsection">34.2.9 Files and I/O</h4>
-
-<p>You can open a file for input or output using the <code>open()</code>
function.
-It’s documented in extravagant detail in <a
href="#perlfunc-NAME">perlfunc NAME</a> and <a
href="#perlopentut-NAME">perlopentut NAME</a>,
-but in short:
-</p>
-<pre class="verbatim"> open(my $in, "<", "input.txt")
or die "Can't open input.txt: $!";
- open(my $out, ">", "output.txt") or die "Can't
open output.txt: $!";
- open(my $log, ">>", "my.log") or die
"Can't open my.log: $!";
-</pre>
-<p>You can read from an open filehandle using the <code><></code>
operator. In
-scalar context it reads a single line from the filehandle, and in list
-context it reads the whole file in, assigning each line to an element of
-the list:
-</p>
-<pre class="verbatim"> my $line = <$in>;
- my @lines = <$in>;
-</pre>
-<p>Reading in the whole file at one time is called slurping. It can
-be useful but it may be a memory hog. Most text file processing
-can be done a line at a time with Perl’s looping constructs.
-</p>
-<p>The <code><></code> operator is most often seen in a
<code>while</code> loop:
-</p>
-<pre class="verbatim"> while (<$in>) { # assigns each line in turn
to $_
- print "Just read in this line: $_";
- }
-</pre>
-<p>We’ve already seen how to print to standard output using
<code>print()</code>.
-However, <code>print()</code> can also take an optional first argument
specifying
-which filehandle to print to:
-</p>
-<pre class="verbatim"> print STDERR "This is your final warning.\n";
- print $out $record;
- print $log $logmessage;
-</pre>
-<p>When you’re done with your filehandles, you should
<code>close()</code> them
-(though to be honest, Perl will clean up after you if you forget):
-</p>
-<pre class="verbatim"> close $in or die "$in: $!";
-</pre>
-<hr>
-<a name="perlintro-Regular-expressions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro-Writing-subroutines" accesskey="n"
rel="next">perlintro Writing subroutines</a>, Previous: <a
href="#perlintro-Files-and-I_002fO" accesskey="p" rel="prev">perlintro Files
and I/O</a>, Up: <a href="#perlintro-DESCRIPTION" accesskey="u"
rel="up">perlintro DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Regular-expressions"></a>
-<h4 class="subsection">34.2.10 Regular expressions</h4>
-
-<p>Perl’s regular expression support is both broad and deep, and is the
-subject of lengthy documentation in <a href="#perlrequick-NAME">perlrequick
NAME</a>, <a href="#perlretut-NAME">perlretut NAME</a>, and
-elsewhere. However, in short:
-</p>
-<dl compact="compact">
-<dt>Simple matching</dt>
-<dd><a name="perlintro-Simple-matching"></a>
-<pre class="verbatim"> if (/foo/) { ... } # true if $_ contains
"foo"
- if ($a =~ /foo/) { ... } # true if $a contains "foo"
-</pre>
-<p>The <code>//</code> matching operator is documented in <a
href="#perlop-NAME">perlop NAME</a>. It operates on
-<code>$_</code> by default, or can be bound to another variable using the
<code>=~</code>
-binding operator (also documented in <a href="#perlop-NAME">perlop NAME</a>).
-</p>
-</dd>
-<dt>Simple substitution</dt>
-<dd><a name="perlintro-Simple-substitution"></a>
-<pre class="verbatim"> s/foo/bar/; # replaces foo with bar in $_
- $a =~ s/foo/bar/; # replaces foo with bar in $a
- $a =~ s/foo/bar/g; # replaces ALL INSTANCES of foo with bar
- # in $a
-</pre>
-<p>The <code>s///</code> substitution operator is documented in <a
href="#perlop-NAME">perlop NAME</a>.
-</p>
-</dd>
-<dt>More complex regular expressions</dt>
-<dd><a name="perlintro-More-complex-regular-expressions"></a>
-<p>You don’t just have to match on fixed strings. In fact, you can match
-on just about anything you could dream of by using more complex regular
-expressions. These are documented at great length in <a
href="#perlre-NAME">perlre NAME</a>, but for
-the meantime, here’s a quick cheat sheet:
-</p>
-<pre class="verbatim"> . a single character
- \s a whitespace character (space, tab, newline,
- ...)
- \S non-whitespace character
- \d a digit (0-9)
- \D a non-digit
- \w a word character (a-z, A-Z, 0-9, _)
- \W a non-word character
- [aeiou] matches a single character in the given set
- [^aeiou] matches a single character outside the given
- set
- (foo|bar|baz) matches any of the alternatives specified
-
- ^ start of string
- $ end of string
-</pre>
-<p>Quantifiers can be used to specify how many of the previous thing you
-want to match on, where "thing" means either a literal character, one
-of the metacharacters listed above, or a group of characters or
-metacharacters in parentheses.
-</p>
-<pre class="verbatim"> * zero or more of the previous thing
- + one or more of the previous thing
- ? zero or one of the previous thing
- {3} matches exactly 3 of the previous thing
- {3,6} matches between 3 and 6 of the previous thing
- {3,} matches 3 or more of the previous thing
-</pre>
-<p>Some brief examples:
-</p>
-<pre class="verbatim"> /^\d+/ string starts with one or more
digits
- /^$/ nothing in the string (start and end are
- adjacent)
- /(\d\s){3}/ three digits, each followed by a whitespace
- character (eg "3 4 5 ")
- /(a.)+/ matches a string in which every odd-numbered
- letter is a (eg "abacadaf")
-
- # This loop reads from STDIN, and prints non-blank lines:
- while (<>) {
- next if /^$/;
- print;
- }
-</pre>
-</dd>
-<dt>Parentheses for capturing</dt>
-<dd><a name="perlintro-Parentheses-for-capturing"></a>
-<p>As well as grouping, parentheses serve a second purpose. They can be
-used to capture the results of parts of the regexp match for later use.
-The results end up in <code>$1</code>, <code>$2</code> and so on.
-</p>
-<pre class="verbatim"> # a cheap and nasty way to break an email address up
into parts
-
- if ($email =~ /(address@hidden)@(.+)/) {
- print "Username is $1\n";
- print "Hostname is $2\n";
- }
-</pre>
-</dd>
-<dt>Other regexp features</dt>
-<dd><a name="perlintro-Other-regexp-features"></a>
-<p>Perl regexps also support backreferences, lookaheads, and all kinds of
-other complex details. Read all about them in <a
href="#perlrequick-NAME">perlrequick NAME</a>,
-<a href="#perlretut-NAME">perlretut NAME</a>, and <a
href="#perlre-NAME">perlre NAME</a>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlintro-Writing-subroutines"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro-OO-Perl" accesskey="n" rel="next">perlintro OO
Perl</a>, Previous: <a href="#perlintro-Regular-expressions" accesskey="p"
rel="prev">perlintro Regular expressions</a>, Up: <a
href="#perlintro-DESCRIPTION" accesskey="u" rel="up">perlintro DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Writing-subroutines"></a>
-<h4 class="subsection">34.2.11 Writing subroutines</h4>
-
-<p>Writing subroutines is easy:
-</p>
-<pre class="verbatim"> sub logger {
- my $logmessage = shift;
- open my $logfile, ">>", "my.log" or die
"Could not open my.log: $!";
- print $logfile $logmessage;
- }
-</pre>
-<p>Now we can use the subroutine just as any other built-in function:
-</p>
-<pre class="verbatim"> logger("We have a logger subroutine!");
-</pre>
-<p>What’s that <code>shift</code>? Well, the arguments to a subroutine
are available
-to us as a special array called <code>@_</code> (see <a
href="#perlvar-NAME">perlvar NAME</a> for more on that).
-The default argument to the <code>shift</code> function just happens to be
<code>@_</code>.
-So <code>my $logmessage = shift;</code> shifts the first item off the list of
-arguments and assigns it to <code>$logmessage</code>.
-</p>
-<p>We can manipulate <code>@_</code> in other ways too:
-</p>
-<pre class="verbatim"> my ($logmessage, $priority) = @_; # common
- my $logmessage = $_[0]; # uncommon, and ugly
-</pre>
-<p>Subroutines can also return values:
-</p>
-<pre class="verbatim"> sub square {
- my $num = shift;
- my $result = $num * $num;
- return $result;
- }
-</pre>
-<p>Then use it like:
-</p>
-<pre class="verbatim"> $sq = square(8);
-</pre>
-<p>For more information on writing subroutines, see <a
href="#perlsub-NAME">perlsub NAME</a>.
-</p>
-<hr>
-<a name="perlintro-OO-Perl"></a>
-<div class="header">
-<p>
-Next: <a href="#perlintro-Using-Perl-modules" accesskey="n"
rel="next">perlintro Using Perl modules</a>, Previous: <a
href="#perlintro-Writing-subroutines" accesskey="p" rel="prev">perlintro
Writing subroutines</a>, Up: <a href="#perlintro-DESCRIPTION" accesskey="u"
rel="up">perlintro DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="OO-Perl"></a>
-<h4 class="subsection">34.2.12 OO Perl</h4>
-
-<p>OO Perl is relatively simple and is implemented using references which
-know what sort of object they are based on Perl’s concept of packages.
-However, OO Perl is largely beyond the scope of this document.
-Read <a href="#perlootut-NAME">perlootut NAME</a> and <a
href="#perlobj-NAME">perlobj NAME</a>.
-</p>
-<p>As a beginning Perl programmer, your most common use of OO Perl will be
-in using third-party modules, which are documented below.
-</p>
-<hr>
-<a name="perlintro-Using-Perl-modules"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlintro-OO-Perl" accesskey="p" rel="prev">perlintro OO
Perl</a>, Up: <a href="#perlintro-DESCRIPTION" accesskey="u" rel="up">perlintro
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-Perl-modules"></a>
-<h4 class="subsection">34.2.13 Using Perl modules</h4>
-
-<p>Perl modules provide a range of features to help you avoid reinventing
-the wheel, and can be downloaded from CPAN ( http://www.cpan.org/ ). A
-number of popular modules are included with the Perl distribution
-itself.
-</p>
-<p>Categories of modules range from text manipulation to network protocols
-to database integration to graphics. A categorized list of modules is
-also available from CPAN.
-</p>
-<p>To learn how to install modules you download from CPAN, read
-<a href="#perlmodinstall-NAME">perlmodinstall NAME</a>.
-</p>
-<p>To learn how to use a particular module, use <code>perldoc
<em>Module::Name</em></code>.
-Typically you will want to <code>use <em>Module::Name</em></code>, which will
then give
-you access to exported functions or an OO interface to the module.
-</p>
-<p><a href="perlfaq.html#Top">(perlfaq)</a> contains questions and answers
related to many common
-tasks, and often provides suggestions for good CPAN modules to use.
-</p>
-<p><a href="#perlmod-NAME">perlmod NAME</a> describes Perl modules in general.
<a href="perlmodlib.html#Top">(perlmodlib)</a> lists the
-modules which came with your Perl installation.
-</p>
-<p>If you feel the urge to write Perl modules, <a
href="#perlnewmod-NAME">perlnewmod NAME</a> will give you
-good advice.
-</p>
-<hr>
-<a name="perlintro-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlintro-DESCRIPTION" accesskey="p" rel="prev">perlintro
DESCRIPTION</a>, Up: <a href="#perlintro" accesskey="u" rel="up">perlintro</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-14"></a>
-<h3 class="section">34.3 AUTHOR</h3>
-
-<p>Kirrily "Skud" Robert <address@hidden>
-</p>
-<hr>
-<a name="perliol"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc" accesskey="n" rel="next">perlipc</a>, Previous: <a
href="#perlintro" accesskey="p" rel="prev">perlintro</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perliol-1"></a>
-<h2 class="chapter">35 perliol</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perliol-NAME"
accesskey="1">perliol NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perliol-SYNOPSIS"
accesskey="2">perliol SYNOPSIS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perliol-DESCRIPTION"
accesskey="3">perliol DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perliol-TODO"
accesskey="4">perliol TODO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perliol-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-SYNOPSIS" accesskey="n" rel="next">perliol
SYNOPSIS</a>, Up: <a href="#perliol" accesskey="u" rel="up">perliol</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-34"></a>
-<h3 class="section">35.1 NAME</h3>
-
-<p>perliol - C API for Perl’s implementation of IO in Layers.
-</p>
-<hr>
-<a name="perliol-SYNOPSIS"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-DESCRIPTION" accesskey="n" rel="next">perliol
DESCRIPTION</a>, Previous: <a href="#perliol-NAME" accesskey="p"
rel="prev">perliol NAME</a>, Up: <a href="#perliol" accesskey="u"
rel="up">perliol</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SYNOPSIS-7"></a>
-<h3 class="section">35.2 SYNOPSIS</h3>
-
-<pre class="verbatim"> /* Defining a layer ... */
- #include <perliol.h>
-</pre>
-<hr>
-<a name="perliol-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-TODO" accesskey="n" rel="next">perliol TODO</a>,
Previous: <a href="#perliol-SYNOPSIS" accesskey="p" rel="prev">perliol
SYNOPSIS</a>, Up: <a href="#perliol" accesskey="u" rel="up">perliol</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-34"></a>
-<h3 class="section">35.3 DESCRIPTION</h3>
-
-<p>This document describes the behavior and implementation of the PerlIO
-abstraction described in <a href="#perlapio-NAME">perlapio NAME</a> when
<code>USE_PERLIO</code> is defined.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perliol-History-and-Background" accesskey="1">perliol History and
Background</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perliol-Basic-Structure"
accesskey="2">perliol Basic Structure</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Layers-vs-Disciplines" accesskey="3">perliol Layers vs
Disciplines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perliol-Data-Structures"
accesskey="4">perliol Data Structures</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Functions-and-Attributes" accesskey="5">perliol Functions and
Attributes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Per_002dinstance-Data" accesskey="6">perliol Per-instance
Data</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Layers-in-action_002e" accesskey="7">perliol Layers in
action.</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Per_002dinstance-flag-bits" accesskey="8">perliol Per-instance
flag bits</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perliol-Methods-in-Detail"
accesskey="9">perliol Methods in Detail</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perliol-Utilities">perliol
Utilities</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Implementing-PerlIO-Layers">perliol Implementing PerlIO
Layers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Core-Layers">perliol Core
Layers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perliol-Extension-Layers">perliol Extension
Layers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perliol-History-and-Background"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-Basic-Structure" accesskey="n" rel="next">perliol
Basic Structure</a>, Up: <a href="#perliol-DESCRIPTION" accesskey="u"
rel="up">perliol DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="History-and-Background"></a>
-<h4 class="subsection">35.3.1 History and Background</h4>
-
-<p>The PerlIO abstraction was introduced in perl5.003_02 but languished as
-just an abstraction until perl5.7.0. However during that time a number
-of perl extensions switched to using it, so the API is mostly fixed to
-maintain (source) compatibility.
-</p>
-<p>The aim of the implementation is to provide the PerlIO API in a flexible
-and platform neutral manner. It is also a trial of an "Object Oriented
-C, with vtables" approach which may be applied to Perl 6.
-</p>
-<hr>
-<a name="perliol-Basic-Structure"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-Layers-vs-Disciplines" accesskey="n"
rel="next">perliol Layers vs Disciplines</a>, Previous: <a
href="#perliol-History-and-Background" accesskey="p" rel="prev">perliol History
and Background</a>, Up: <a href="#perliol-DESCRIPTION" accesskey="u"
rel="up">perliol DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Basic-Structure"></a>
-<h4 class="subsection">35.3.2 Basic Structure</h4>
-
-<p>PerlIO is a stack of layers.
-</p>
-<p>The low levels of the stack work with the low-level operating system
-calls (file descriptors in C) getting bytes in and out, the higher
-layers of the stack buffer, filter, and otherwise manipulate the I/O,
-and return characters (or bytes) to Perl. Terms <em>above</em> and
<em>below</em>
-are used to refer to the relative positioning of the stack layers.
-</p>
-<p>A layer contains a "vtable", the table of I/O operations (at C
level
-a table of function pointers), and status flags. The functions in the
-vtable implement operations like "open", "read", and
"write".
-</p>
-<p>When I/O, for example "read", is requested, the request goes from
Perl
-first down the stack using "read" functions of each layer, then at
the
-bottom the input is requested from the operating system services, then
-the result is returned up the stack, finally being interpreted as Perl
-data.
-</p>
-<p>The requests do not necessarily go always all the way down to the
-operating system: that’s where PerlIO buffering comes into play.
-</p>
-<p>When you do an open() and specify extra PerlIO layers to be deployed,
-the layers you specify are "pushed" on top of the already existing
-default stack. One way to see it is that "operating system is
-on the left" and "Perl is on the right".
-</p>
-<p>What exact layers are in this default stack depends on a lot of
-things: your operating system, Perl version, Perl compile time
-configuration, and Perl runtime configuration. See <a
href="PerlIO.html#Top">(PerlIO)</a>,
-<a href="#perlrun-PERLIO">perlrun PERLIO</a>, and <a
href="open.html#Top">(open)</a> for more information.
-</p>
-<p>binmode() operates similarly to open(): by default the specified
-layers are pushed on top of the existing stack.
-</p>
-<p>However, note that even as the specified layers are "pushed on
top"
-for open() and binmode(), this doesn’t mean that the effects are
-limited to the "top": PerlIO layers can be very ’active’
and inspect
-and affect layers also deeper in the stack. As an example there
-is a layer called "raw" which repeatedly "pops" layers
until
-it reaches the first layer that has declared itself capable of
-handling binary data. The "pushed" layers are processed in
left-to-right
-order.
-</p>
-<p>sysopen() operates (unsurprisingly) at a lower level in the stack than
-open(). For example in Unix or Unix-like systems sysopen() operates
-directly at the level of file descriptors: in the terms of PerlIO
-layers, it uses only the "unix" layer, which is a rather thin wrapper
-on top of the Unix file descriptors.
-</p>
-<hr>
-<a name="perliol-Layers-vs-Disciplines"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-Data-Structures" accesskey="n" rel="next">perliol Data
Structures</a>, Previous: <a href="#perliol-Basic-Structure" accesskey="p"
rel="prev">perliol Basic Structure</a>, Up: <a href="#perliol-DESCRIPTION"
accesskey="u" rel="up">perliol DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Layers-vs-Disciplines"></a>
-<h4 class="subsection">35.3.3 Layers vs Disciplines</h4>
-
-<p>Initial discussion of the ability to modify IO streams behaviour used
-the term "discipline" for the entities which were added. This came (I
-believe) from the use of the term in "sfio", which in turn borrowed
it
-from "line disciplines" on Unix terminals. However, this document
(and
-the C code) uses the term "layer".
-</p>
-<p>This is, I hope, a natural term given the implementation, and should
-avoid connotations that are inherent in earlier uses of "discipline"
-for things which are rather different.
-</p>
-<hr>
-<a name="perliol-Data-Structures"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-Functions-and-Attributes" accesskey="n"
rel="next">perliol Functions and Attributes</a>, Previous: <a
href="#perliol-Layers-vs-Disciplines" accesskey="p" rel="prev">perliol Layers
vs Disciplines</a>, Up: <a href="#perliol-DESCRIPTION" accesskey="u"
rel="up">perliol DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Data-Structures"></a>
-<h4 class="subsection">35.3.4 Data Structures</h4>
-
-<p>The basic data structure is a PerlIOl:
-</p>
-<pre class="verbatim"> typedef struct _PerlIO PerlIOl;
- typedef struct _PerlIO_funcs PerlIO_funcs;
- typedef PerlIOl *PerlIO;
-
- struct _PerlIO
- {
- PerlIOl * next; /* Lower layer */
- PerlIO_funcs * tab; /* Functions for this layer */
- U32 flags; /* Various flags for state */
- };
-</pre>
-<p>A <code>PerlIOl *</code> is a pointer to the struct, and the
<em>application</em>
-level <code>PerlIO *</code> is a pointer to a <code>PerlIOl *</code> - i.e. a
pointer
-to a pointer to the struct. This allows the application level <code>PerlIO
*</code>
-to remain constant while the actual <code>PerlIOl *</code> underneath
-changes. (Compare perl’s <code>SV *</code> which remains constant while
its
-<code>sv_any</code> field changes as the scalar’s type changes.) An IO
stream is
-then in general represented as a pointer to this linked-list of
-"layers".
-</p>
-<p>It should be noted that because of the double indirection in a <code>PerlIO
*</code>,
-a <code>&(perlio->next)</code> "is" a <code>PerlIO *</code>,
and so to some degree
-at least one layer can use the "standard" API on the next layer down.
-</p>
-<p>A "layer" is composed of two parts:
-</p>
-<ol>
-<li> The functions and attributes of the "layer class".
-
-</li><li> The per-instance data for a particular handle.
-
-</li></ol>
-
-<hr>
-<a name="perliol-Functions-and-Attributes"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-Per_002dinstance-Data" accesskey="n"
rel="next">perliol Per-instance Data</a>, Previous: <a
href="#perliol-Data-Structures" accesskey="p" rel="prev">perliol Data
Structures</a>, Up: <a href="#perliol-DESCRIPTION" accesskey="u"
rel="up">perliol DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Functions-and-Attributes"></a>
-<h4 class="subsection">35.3.5 Functions and Attributes</h4>
-
-<p>The functions and attributes are accessed via the "tab" (for
table)
-member of <code>PerlIOl</code>. The functions (methods of the layer
"class") are
-fixed, and are defined by the <code>PerlIO_funcs</code> type. They are broadly
the
-same as the public <code>PerlIO_xxxxx</code> functions:
-</p>
-<pre class="verbatim"> struct _PerlIO_funcs
- {
- Size_t fsize;
- char * name;
- Size_t size;
- IV kind;
- IV (*Pushed)(pTHX_ PerlIO *f,const char *mode,SV *arg,
PerlIO_funcs *tab);
- IV (*Popped)(pTHX_ PerlIO *f);
- PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab,
- PerlIO_list_t *layers, IV n,
- const char *mode,
- int fd, int imode, int perm,
- PerlIO *old,
- int narg, SV **args);
- IV (*Binmode)(pTHX_ PerlIO *f);
- SV * (*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, int flags)
- IV (*Fileno)(pTHX_ PerlIO *f);
- PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o, CLONE_PARAMS *param, int
flags)
- /* Unix-like functions - cf sfio line disciplines */
- SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
- SSize_t (*Unread)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
- SSize_t (*Write)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
- IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
- Off_t (*Tell)(pTHX_ PerlIO *f);
- IV (*Close)(pTHX_ PerlIO *f);
- /* Stdio-like buffered IO functions */
- IV (*Flush)(pTHX_ PerlIO *f);
- IV (*Fill)(pTHX_ PerlIO *f);
- IV (*Eof)(pTHX_ PerlIO *f);
- IV (*Error)(pTHX_ PerlIO *f);
- void (*Clearerr)(pTHX_ PerlIO *f);
- void (*Setlinebuf)(pTHX_ PerlIO *f);
- /* Perl's snooping functions */
- STDCHAR * (*Get_base)(pTHX_ PerlIO *f);
- Size_t (*Get_bufsiz)(pTHX_ PerlIO *f);
- STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f);
- SSize_t (*Get_cnt)(pTHX_ PerlIO *f);
- void (*Set_ptrcnt)(pTHX_ PerlIO *f,STDCHAR *ptr,SSize_t cnt);
- };
-</pre>
-<p>The first few members of the struct give a function table size for
-compatibility check "name" for the layer, the size to
<code>malloc</code> for the per-instance data,
-and some flags which are attributes of the class as whole (such as whether it
is a buffering
-layer), then follow the functions which fall into four basic groups:
-</p>
-<ol>
-<li> Opening and setup functions
-
-</li><li> Basic IO operations
-
-</li><li> Stdio class buffering options.
-
-</li><li> Functions to support Perl’s traditional "fast"
access to the buffer.
-
-</li></ol>
-
-<p>A layer does not have to implement all the functions, but the whole
-table has to be present. Unimplemented slots can be NULL (which will
-result in an error when called) or can be filled in with stubs to
-"inherit" behaviour from a "base class". This
"inheritance" is fixed
-for all instances of the layer, but as the layer chooses which stubs
-to populate the table, limited "multiple inheritance" is possible.
-</p>
-<hr>
-<a name="perliol-Per_002dinstance-Data"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-Layers-in-action_002e" accesskey="n"
rel="next">perliol Layers in action.</a>, Previous: <a
href="#perliol-Functions-and-Attributes" accesskey="p" rel="prev">perliol
Functions and Attributes</a>, Up: <a href="#perliol-DESCRIPTION" accesskey="u"
rel="up">perliol DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Per_002dinstance-Data"></a>
-<h4 class="subsection">35.3.6 Per-instance Data</h4>
-
-<p>The per-instance data are held in memory beyond the basic PerlIOl
-struct, by making a PerlIOl the first member of the layer’s struct
-thus:
-</p>
-<pre class="verbatim"> typedef struct
- {
- struct _PerlIO base; /* Base "class" info */
- STDCHAR * buf; /* Start of buffer */
- STDCHAR * end; /* End of valid part of buffer */
- STDCHAR * ptr; /* Current position in buffer */
- Off_t posn; /* Offset of buf into the file */
- Size_t bufsiz; /* Real size of buffer */
- IV oneword; /* Emergency buffer */
- } PerlIOBuf;
-</pre>
-<p>In this way (as for perl’s scalars) a pointer to a PerlIOBuf can be
-treated as a pointer to a PerlIOl.
-</p>
-<hr>
-<a name="perliol-Layers-in-action_002e"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-Per_002dinstance-flag-bits" accesskey="n"
rel="next">perliol Per-instance flag bits</a>, Previous: <a
href="#perliol-Per_002dinstance-Data" accesskey="p" rel="prev">perliol
Per-instance Data</a>, Up: <a href="#perliol-DESCRIPTION" accesskey="u"
rel="up">perliol DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Layers-in-action_002e"></a>
-<h4 class="subsection">35.3.7 Layers in action.</h4>
-
-<pre class="verbatim"> table perlio unix
- | |
- +-----------+ +----------+ +--------+
- PerlIO ->| |--->| next |--->| NULL |
- +-----------+ +----------+ +--------+
- | | | buffer | | fd |
- +-----------+ | | +--------+
- | | +----------+
-</pre>
-<p>The above attempts to show how the layer scheme works in a simple case.
-The application’s <code>PerlIO *</code> points to an entry in the
table(s)
-representing open (allocated) handles. For example the first three slots
-in the table correspond to <code>stdin</code>,<code>stdout</code> and
<code>stderr</code>. The table
-in turn points to the current "top" layer for the handle - in this
case
-an instance of the generic buffering layer "perlio". That layer in
turn
-points to the next layer down - in this case the low-level "unix"
layer.
-</p>
-<p>The above is roughly equivalent to a "stdio" buffered stream, but
with
-much more flexibility:
-</p>
-<ul>
-<li> If Unix level <code>read</code>/<code>write</code>/<code>lseek</code> is
not appropriate for (say)
-sockets then the "unix" layer can be replaced (at open time or even
-dynamically) with a "socket" layer.
-
-</li><li> Different handles can have different buffering schemes. The
"top"
-layer could be the "mmap" layer if reading disk files was quicker
-using <code>mmap</code> than <code>read</code>. An "unbuffered"
stream can be implemented
-simply by not having a buffer layer.
-
-</li><li> Extra layers can be inserted to process the data as it flows through.
-This was the driving need for including the scheme in perl 5.7.0+ - we
-needed a mechanism to allow data to be translated between perl’s
-internal encoding (conceptually at least Unicode as UTF-8), and the
-"native" format used by the system. This is provided by the
-":encoding(xxxx)" layer which typically sits above the buffering
layer.
-
-</li><li> A layer can be added that does "\n" to CRLF translation.
This layer
-can be used on any platform, not just those that normally do such
-things.
-
-</li></ul>
-
-<hr>
-<a name="perliol-Per_002dinstance-flag-bits"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-Methods-in-Detail" accesskey="n" rel="next">perliol
Methods in Detail</a>, Previous: <a href="#perliol-Layers-in-action_002e"
accesskey="p" rel="prev">perliol Layers in action.</a>, Up: <a
href="#perliol-DESCRIPTION" accesskey="u" rel="up">perliol DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Per_002dinstance-flag-bits"></a>
-<h4 class="subsection">35.3.8 Per-instance flag bits</h4>
-
-<p>The generic flag bits are a hybrid of <code>O_XXXXX</code> style flags
deduced
-from the mode string passed to <code>PerlIO_open()</code>, and state bits for
-typical buffer layers.
-</p>
-<dl compact="compact">
-<dt>PERLIO_F_EOF</dt>
-<dd><a name="perliol-PERLIO_005fF_005fEOF"></a>
-<p>End of file.
-</p>
-</dd>
-<dt>PERLIO_F_CANWRITE</dt>
-<dd><a name="perliol-PERLIO_005fF_005fCANWRITE"></a>
-<p>Writes are permitted, i.e. opened as "w" or "r+" or
"a", etc.
-</p>
-</dd>
-<dt>PERLIO_F_CANREAD</dt>
-<dd><a name="perliol-PERLIO_005fF_005fCANREAD"></a>
-<p>Reads are permitted i.e. opened "r" or "w+" (or even
"a+" - ick).
-</p>
-</dd>
-<dt>PERLIO_F_ERROR</dt>
-<dd><a name="perliol-PERLIO_005fF_005fERROR"></a>
-<p>An error has occurred (for <code>PerlIO_error()</code>).
-</p>
-</dd>
-<dt>PERLIO_F_TRUNCATE</dt>
-<dd><a name="perliol-PERLIO_005fF_005fTRUNCATE"></a>
-<p>Truncate file suggested by open mode.
-</p>
-</dd>
-<dt>PERLIO_F_APPEND</dt>
-<dd><a name="perliol-PERLIO_005fF_005fAPPEND"></a>
-<p>All writes should be appends.
-</p>
-</dd>
-<dt>PERLIO_F_CRLF</dt>
-<dd><a name="perliol-PERLIO_005fF_005fCRLF"></a>
-<p>Layer is performing Win32-like "\n" mapped to CR,LF for output
and CR,LF
-mapped to "\n" for input. Normally the provided "crlf"
layer is the only
-layer that need bother about this. <code>PerlIO_binmode()</code> will mess
with this
-flag rather than add/remove layers if the <code>PERLIO_K_CANCRLF</code> bit is
set
-for the layers class.
-</p>
-</dd>
-<dt>PERLIO_F_UTF8</dt>
-<dd><a name="perliol-PERLIO_005fF_005fUTF8"></a>
-<p>Data written to this layer should be UTF-8 encoded; data provided
-by this layer should be considered UTF-8 encoded. Can be set on any layer
-by ":utf8" dummy layer. Also set on ":encoding" layer.
-</p>
-</dd>
-<dt>PERLIO_F_UNBUF</dt>
-<dd><a name="perliol-PERLIO_005fF_005fUNBUF"></a>
-<p>Layer is unbuffered - i.e. write to next layer down should occur for
-each write to this layer.
-</p>
-</dd>
-<dt>PERLIO_F_WRBUF</dt>
-<dd><a name="perliol-PERLIO_005fF_005fWRBUF"></a>
-<p>The buffer for this layer currently holds data written to it but not sent
-to next layer.
-</p>
-</dd>
-<dt>PERLIO_F_RDBUF</dt>
-<dd><a name="perliol-PERLIO_005fF_005fRDBUF"></a>
-<p>The buffer for this layer currently holds unconsumed data read from
-layer below.
-</p>
-</dd>
-<dt>PERLIO_F_LINEBUF</dt>
-<dd><a name="perliol-PERLIO_005fF_005fLINEBUF"></a>
-<p>Layer is line buffered. Write data should be passed to next layer down
-whenever a "\n" is seen. Any data beyond the "\n" should
then be
-processed.
-</p>
-</dd>
-<dt>PERLIO_F_TEMP</dt>
-<dd><a name="perliol-PERLIO_005fF_005fTEMP"></a>
-<p>File has been <code>unlink()</code>ed, or should be deleted on
<code>close()</code>.
-</p>
-</dd>
-<dt>PERLIO_F_OPEN</dt>
-<dd><a name="perliol-PERLIO_005fF_005fOPEN"></a>
-<p>Handle is open.
-</p>
-</dd>
-<dt>PERLIO_F_FASTGETS</dt>
-<dd><a name="perliol-PERLIO_005fF_005fFASTGETS"></a>
-<p>This instance of this layer supports the "fast <code>gets</code>"
interface.
-Normally set based on <code>PERLIO_K_FASTGETS</code> for the class and by the
-existence of the function(s) in the table. However a class that
-normally provides that interface may need to avoid it on a
-particular instance. The "pending" layer needs to do this when
-it is pushed above a layer which does not support the interface.
-(Perl’s <code>sv_gets()</code> does not expect the streams fast
<code>gets</code> behaviour
-to change during one "get".)
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perliol-Methods-in-Detail"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-Utilities" accesskey="n" rel="next">perliol
Utilities</a>, Previous: <a href="#perliol-Per_002dinstance-flag-bits"
accesskey="p" rel="prev">perliol Per-instance flag bits</a>, Up: <a
href="#perliol-DESCRIPTION" accesskey="u" rel="up">perliol DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Methods-in-Detail"></a>
-<h4 class="subsection">35.3.9 Methods in Detail</h4>
-
-<dl compact="compact">
-<dt>fsize</dt>
-<dd><a name="perliol-fsize"></a>
-<pre class="verbatim"> Size_t fsize;
-</pre>
-<p>Size of the function table. This is compared against the value PerlIO
-code "knows" as a compatibility check. Future versions <em>may</em>
be able
-to tolerate layers compiled against an old version of the headers.
-</p>
-</dd>
-<dt>name</dt>
-<dd><a name="perliol-name"></a>
-<pre class="verbatim"> char * name;
-</pre>
-<p>The name of the layer whose open() method Perl should invoke on
-open(). For example if the layer is called APR, you will call:
-</p>
-<pre class="verbatim"> open $fh, ">:APR", ...
-</pre>
-<p>and Perl knows that it has to invoke the PerlIOAPR_open() method
-implemented by the APR layer.
-</p>
-</dd>
-<dt>size</dt>
-<dd><a name="perliol-size"></a>
-<pre class="verbatim"> Size_t size;
-</pre>
-<p>The size of the per-instance data structure, e.g.:
-</p>
-<pre class="verbatim"> sizeof(PerlIOAPR)
-</pre>
-<p>If this field is zero then <code>PerlIO_pushed</code> does not malloc
anything
-and assumes layer’s Pushed function will do any required layer stack
-manipulation - used to avoid malloc/free overhead for dummy layers.
-If the field is non-zero it must be at least the size of <code>PerlIOl</code>,
-<code>PerlIO_pushed</code> will allocate memory for the layer’s data
structures
-and link new layer onto the stream’s stack. (If the layer’s Pushed
-method returns an error indication the layer is popped again.)
-</p>
-</dd>
-<dt>kind</dt>
-<dd><a name="perliol-kind"></a>
-<pre class="verbatim"> IV kind;
-</pre>
-<ul>
-<li> PERLIO_K_BUFFERED
-
-<p>The layer is buffered.
-</p>
-</li><li> PERLIO_K_RAW
-
-<p>The layer is acceptable to have in a binmode(FH) stack - i.e. it does not
-(or will configure itself not to) transform bytes passing through it.
-</p>
-</li><li> PERLIO_K_CANCRLF
-
-<p>Layer can translate between "\n" and CRLF line ends.
-</p>
-</li><li> PERLIO_K_FASTGETS
-
-<p>Layer allows buffer snooping.
-</p>
-</li><li> PERLIO_K_MULTIARG
-
-<p>Used when the layer’s open() accepts more arguments than usual. The
-extra arguments should come not before the <code>MODE</code> argument. When
this
-flag is used it’s up to the layer to validate the args.
-</p>
-</li></ul>
-
-</dd>
-<dt>Pushed</dt>
-<dd><a name="perliol-Pushed"></a>
-<pre class="verbatim"> IV (*Pushed)(pTHX_ PerlIO *f,const char
*mode, SV *arg);
-</pre>
-<p>The only absolutely mandatory method. Called when the layer is pushed
-onto the stack. The <code>mode</code> argument may be NULL if this occurs
-post-open. The <code>arg</code> will be non-<code>NULL</code> if an argument
string was
-passed. In most cases this should call <code>PerlIOBase_pushed()</code> to
-convert <code>mode</code> into the appropriate <code>PERLIO_F_XXXXX</code>
flags in
-addition to any actions the layer itself takes. If a layer is not
-expecting an argument it need neither save the one passed to it, nor
-provide <code>Getarg()</code> (it could perhaps <code>Perl_warn</code> that
the argument
-was un-expected).
-</p>
-<p>Returns 0 on success. On failure returns -1 and should set errno.
-</p>
-</dd>
-<dt>Popped</dt>
-<dd><a name="perliol-Popped"></a>
-<pre class="verbatim"> IV (*Popped)(pTHX_ PerlIO *f);
-</pre>
-<p>Called when the layer is popped from the stack. A layer will normally
-be popped after <code>Close()</code> is called. But a layer can be popped
-without being closed if the program is dynamically managing layers on
-the stream. In such cases <code>Popped()</code> should free any resources
-(buffers, translation tables, ...) not held directly in the layer’s
-struct. It should also <code>Unread()</code> any unconsumed data that has been
-read and buffered from the layer below back to that layer, so that it
-can be re-provided to what ever is now above.
-</p>
-<p>Returns 0 on success and failure. If <code>Popped()</code> returns
<em>true</em> then
-<em>perlio.c</em> assumes that either the layer has popped itself, or the
-layer is super special and needs to be retained for other reasons.
-In most cases it should return <em>false</em>.
-</p>
-</dd>
-<dt>Open</dt>
-<dd><a name="perliol-Open"></a>
-<pre class="verbatim"> PerlIO * (*Open)(...);
-</pre>
-<p>The <code>Open()</code> method has lots of arguments because it combines the
-functions of perl’s <code>open</code>, <code>PerlIO_open</code>,
perl’s <code>sysopen</code>,
-<code>PerlIO_fdopen</code> and <code>PerlIO_reopen</code>. The full prototype
is as
-follows:
-</p>
-<pre class="verbatim"> PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab,
- PerlIO_list_t *layers, IV n,
- const char *mode,
- int fd, int imode, int perm,
- PerlIO *old,
- int narg, SV **args);
-</pre>
-<p>Open should (perhaps indirectly) call <code>PerlIO_allocate()</code> to
allocate
-a slot in the table and associate it with the layers information for
-the opened file, by calling <code>PerlIO_push</code>. The <em>layers</em> is
an
-array of all the layers destined for the <code>PerlIO *</code>, and any
-arguments passed to them, <em>n</em> is the index into that array of the
-layer being called. The macro <code>PerlIOArg</code> will return a (possibly
-<code>NULL</code>) SV * for the argument passed to the layer.
-</p>
-<p>The <em>mode</em> string is an "<code>fopen()</code>-like" string
which would match
-the regular expression <code>/^[I#]?[rwa]\+?[bt]?$/</code>.
-</p>
-<p>The <code>'I'</code> prefix is used during creation of
<code>stdin</code>..<code>stderr</code> via
-special <code>PerlIO_fdopen</code> calls; the <code>'#'</code> prefix means
that this is
-<code>sysopen</code> and that <em>imode</em> and <em>perm</em> should be
passed to
-<code>PerlLIO_open3</code>; <code>'r'</code> means <strong>r</strong>ead,
<code>'w'</code> means <strong>w</strong>rite and
-<code>'a'</code> means <strong>a</strong>ppend. The <code>'+'</code> suffix
means that both reading and
-writing/appending are permitted. The <code>'b'</code> suffix means file should
-be binary, and <code>'t'</code> means it is text. (Almost all layers should do
-the IO in binary mode, and ignore the b/t bits. The <code>:crlf</code> layer
-should be pushed to handle the distinction.)
-</p>
-<p>If <em>old</em> is not <code>NULL</code> then this is a
<code>PerlIO_reopen</code>. Perl itself
-does not use this (yet?) and semantics are a little vague.
-</p>
-<p>If <em>fd</em> not negative then it is the numeric file descriptor
<em>fd</em>,
-which will be open in a manner compatible with the supplied mode
-string, the call is thus equivalent to <code>PerlIO_fdopen</code>. In this case
-<em>nargs</em> will be zero.
-</p>
-<p>If <em>nargs</em> is greater than zero then it gives the number of arguments
-passed to <code>open</code>, otherwise it will be 1 if for example
-<code>PerlIO_open</code> was called. In simple cases SvPV_nolen(*args) is the
-pathname to open.
-</p>
-<p>If a layer provides <code>Open()</code> it should normally call the
<code>Open()</code>
-method of next layer down (if any) and then push itself on top if that
-succeeds. <code>PerlIOBase_open</code> is provided to do exactly that, so in
-most cases you don’t have to write your own <code>Open()</code> method.
If this
-method is not defined, other layers may have difficulty pushing
-themselves on top of it during open.
-</p>
-<p>If <code>PerlIO_push</code> was performed and open has failed, it must
-<code>PerlIO_pop</code> itself, since if it’s not, the layer won’t
be removed
-and may cause bad problems.
-</p>
-<p>Returns <code>NULL</code> on failure.
-</p>
-</dd>
-<dt>Binmode</dt>
-<dd><a name="perliol-Binmode"></a>
-<pre class="verbatim"> IV (*Binmode)(pTHX_ PerlIO *f);
-</pre>
-<p>Optional. Used when <code>:raw</code> layer is pushed (explicitly or as a
result
-of binmode(FH)). If not present layer will be popped. If present
-should configure layer as binary (or pop itself) and return 0.
-If it returns -1 for error <code>binmode</code> will fail with layer
-still on the stack.
-</p>
-</dd>
-<dt>Getarg</dt>
-<dd><a name="perliol-Getarg"></a>
-<pre class="verbatim"> SV * (*Getarg)(pTHX_ PerlIO *f,
- CLONE_PARAMS *param, int flags);
-</pre>
-<p>Optional. If present should return an SV * representing the string
-argument passed to the layer when it was
-pushed. e.g. ":encoding(ascii)" would return an SvPV with value
-"ascii". (<em>param</em> and <em>flags</em> arguments can be ignored
in most
-cases)
-</p>
-<p><code>Dup</code> uses <code>Getarg</code> to retrieve the argument
originally passed to
-<code>Pushed</code>, so you must implement this function if your layer has an
-extra argument to <code>Pushed</code> and will ever be <code>Dup</code>ed.
-</p>
-</dd>
-<dt>Fileno</dt>
-<dd><a name="perliol-Fileno"></a>
-<pre class="verbatim"> IV (*Fileno)(pTHX_ PerlIO *f);
-</pre>
-<p>Returns the Unix/Posix numeric file descriptor for the handle. Normally
-<code>PerlIOBase_fileno()</code> (which just asks next layer down) will suffice
-for this.
-</p>
-<p>Returns -1 on error, which is considered to include the case where the
-layer cannot provide such a file descriptor.
-</p>
-</dd>
-<dt>Dup</dt>
-<dd><a name="perliol-Dup"></a>
-<pre class="verbatim"> PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o,
- CLONE_PARAMS *param, int flags);
-</pre>
-<p>XXX: Needs more docs.
-</p>
-<p>Used as part of the "clone" process when a thread is spawned (in
which
-case param will be non-NULL) and when a stream is being duplicated via
-’&’ in the <code>open</code>.
-</p>
-<p>Similar to <code>Open</code>, returns PerlIO* on success, <code>NULL</code>
on failure.
-</p>
-</dd>
-<dt>Read</dt>
-<dd><a name="perliol-Read"></a>
-<pre class="verbatim"> SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf,
Size_t count);
-</pre>
-<p>Basic read operation.
-</p>
-<p>Typically will call <code>Fill</code> and manipulate pointers (possibly via
the
-API). <code>PerlIOBuf_read()</code> may be suitable for derived classes which
-provide "fast gets" methods.
-</p>
-<p>Returns actual bytes read, or -1 on an error.
-</p>
-</dd>
-<dt>Unread</dt>
-<dd><a name="perliol-Unread"></a>
-<pre class="verbatim"> SSize_t (*Unread)(pTHX_ PerlIO *f,
- const void *vbuf, Size_t count);
-</pre>
-<p>A superset of stdio’s <code>ungetc()</code>. Should arrange for
future reads to
-see the bytes in <code>vbuf</code>. If there is no obviously better
implementation
-then <code>PerlIOBase_unread()</code> provides the function by pushing a
"fake"
-"pending" layer above the calling layer.
-</p>
-<p>Returns the number of unread chars.
-</p>
-</dd>
-<dt>Write</dt>
-<dd><a name="perliol-Write"></a>
-<pre class="verbatim"> SSize_t (*Write)(PerlIO *f, const void *vbuf,
Size_t count);
-</pre>
-<p>Basic write operation.
-</p>
-<p>Returns bytes written or -1 on an error.
-</p>
-</dd>
-<dt>Seek</dt>
-<dd><a name="perliol-Seek"></a>
-<pre class="verbatim"> IV (*Seek)(pTHX_ PerlIO *f, Off_t offset,
int whence);
-</pre>
-<p>Position the file pointer. Should normally call its own <code>Flush</code>
-method and then the <code>Seek</code> method of next layer down.
-</p>
-<p>Returns 0 on success, -1 on failure.
-</p>
-</dd>
-<dt>Tell</dt>
-<dd><a name="perliol-Tell"></a>
-<pre class="verbatim"> Off_t (*Tell)(pTHX_ PerlIO *f);
-</pre>
-<p>Return the file pointer. May be based on layers cached concept of
-position to avoid overhead.
-</p>
-<p>Returns -1 on failure to get the file pointer.
-</p>
-</dd>
-<dt>Close</dt>
-<dd><a name="perliol-Close"></a>
-<pre class="verbatim"> IV (*Close)(pTHX_ PerlIO *f);
-</pre>
-<p>Close the stream. Should normally call <code>PerlIOBase_close()</code> to
flush
-itself and close layers below, and then deallocate any data structures
-(buffers, translation tables, ...) not held directly in the data
-structure.
-</p>
-<p>Returns 0 on success, -1 on failure.
-</p>
-</dd>
-<dt>Flush</dt>
-<dd><a name="perliol-Flush"></a>
-<pre class="verbatim"> IV (*Flush)(pTHX_ PerlIO *f);
-</pre>
-<p>Should make stream’s state consistent with layers below. That is, any
-buffered write data should be written, and file position of lower layers
-adjusted for data read from below but not actually consumed.
-(Should perhaps <code>Unread()</code> such data to the lower layer.)
-</p>
-<p>Returns 0 on success, -1 on failure.
-</p>
-</dd>
-<dt>Fill</dt>
-<dd><a name="perliol-Fill"></a>
-<pre class="verbatim"> IV (*Fill)(pTHX_ PerlIO *f);
-</pre>
-<p>The buffer for this layer should be filled (for read) from layer
-below. When you "subclass" PerlIOBuf layer, you want to use its
-<em>_read</em> method and to supply your own fill method, which fills the
-PerlIOBuf’s buffer.
-</p>
-<p>Returns 0 on success, -1 on failure.
-</p>
-</dd>
-<dt>Eof</dt>
-<dd><a name="perliol-Eof"></a>
-<pre class="verbatim"> IV (*Eof)(pTHX_ PerlIO *f);
-</pre>
-<p>Return end-of-file indicator. <code>PerlIOBase_eof()</code> is normally
sufficient.
-</p>
-<p>Returns 0 on end-of-file, 1 if not end-of-file, -1 on error.
-</p>
-</dd>
-<dt>Error</dt>
-<dd><a name="perliol-Error"></a>
-<pre class="verbatim"> IV (*Error)(pTHX_ PerlIO *f);
-</pre>
-<p>Return error indicator. <code>PerlIOBase_error()</code> is normally
sufficient.
-</p>
-<p>Returns 1 if there is an error (usually when <code>PERLIO_F_ERROR</code> is
set),
-0 otherwise.
-</p>
-</dd>
-<dt>Clearerr</dt>
-<dd><a name="perliol-Clearerr"></a>
-<pre class="verbatim"> void (*Clearerr)(pTHX_ PerlIO *f);
-</pre>
-<p>Clear end-of-file and error indicators. Should call
<code>PerlIOBase_clearerr()</code>
-to set the <code>PERLIO_F_XXXXX</code> flags, which may suffice.
-</p>
-</dd>
-<dt>Setlinebuf</dt>
-<dd><a name="perliol-Setlinebuf"></a>
-<pre class="verbatim"> void (*Setlinebuf)(pTHX_ PerlIO *f);
-</pre>
-<p>Mark the stream as line buffered. <code>PerlIOBase_setlinebuf()</code> sets
the
-PERLIO_F_LINEBUF flag and is normally sufficient.
-</p>
-</dd>
-<dt>Get_base</dt>
-<dd><a name="perliol-Get_005fbase"></a>
-<pre class="verbatim"> STDCHAR * (*Get_base)(pTHX_ PerlIO *f);
-</pre>
-<p>Allocate (if not already done so) the read buffer for this layer and
-return pointer to it. Return NULL on failure.
-</p>
-</dd>
-<dt>Get_bufsiz</dt>
-<dd><a name="perliol-Get_005fbufsiz"></a>
-<pre class="verbatim"> Size_t (*Get_bufsiz)(pTHX_ PerlIO *f);
-</pre>
-<p>Return the number of bytes that last <code>Fill()</code> put in the buffer.
-</p>
-</dd>
-<dt>Get_ptr</dt>
-<dd><a name="perliol-Get_005fptr"></a>
-<pre class="verbatim"> STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f);
-</pre>
-<p>Return the current read pointer relative to this layer’s buffer.
-</p>
-</dd>
-<dt>Get_cnt</dt>
-<dd><a name="perliol-Get_005fcnt"></a>
-<pre class="verbatim"> SSize_t (*Get_cnt)(pTHX_ PerlIO *f);
-</pre>
-<p>Return the number of bytes left to be read in the current buffer.
-</p>
-</dd>
-<dt>Set_ptrcnt</dt>
-<dd><a name="perliol-Set_005fptrcnt"></a>
-<pre class="verbatim"> void (*Set_ptrcnt)(pTHX_ PerlIO *f,
- STDCHAR *ptr, SSize_t cnt);
-</pre>
-<p>Adjust the read pointer and count of bytes to match <code>ptr</code> and/or
<code>cnt</code>.
-The application (or layer above) must ensure they are consistent.
-(Checking is allowed by the paranoid.)
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perliol-Utilities"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-Implementing-PerlIO-Layers" accesskey="n"
rel="next">perliol Implementing PerlIO Layers</a>, Previous: <a
href="#perliol-Methods-in-Detail" accesskey="p" rel="prev">perliol Methods in
Detail</a>, Up: <a href="#perliol-DESCRIPTION" accesskey="u" rel="up">perliol
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Utilities"></a>
-<h4 class="subsection">35.3.10 Utilities</h4>
-
-<p>To ask for the next layer down use PerlIONext(PerlIO *f).
-</p>
-<p>To check that a PerlIO* is valid use PerlIOValid(PerlIO *f). (All
-this does is really just to check that the pointer is non-NULL and
-that the pointer behind that is non-NULL.)
-</p>
-<p>PerlIOBase(PerlIO *f) returns the "Base" pointer, or in other
words,
-the <code>PerlIOl*</code> pointer.
-</p>
-<p>PerlIOSelf(PerlIO* f, type) return the PerlIOBase cast to a type.
-</p>
-<p>Perl_PerlIO_or_Base(PerlIO* f, callback, base, failure, args) either
-calls the <em>callback</em> from the functions of the layer <em>f</em> (just by
-the name of the IO function, like "Read") with the <em>args</em>, or
if
-there is no such callback, calls the <em>base</em> version of the callback
-with the same args, or if the f is invalid, set errno to EBADF and
-return <em>failure</em>.
-</p>
-<p>Perl_PerlIO_or_fail(PerlIO* f, callback, failure, args) either calls
-the <em>callback</em> of the functions of the layer <em>f</em> with the
<em>args</em>,
-or if there is no such callback, set errno to EINVAL. Or if the f is
-invalid, set errno to EBADF and return <em>failure</em>.
-</p>
-<p>Perl_PerlIO_or_Base_void(PerlIO* f, callback, base, args) either calls
-the <em>callback</em> of the functions of the layer <em>f</em> with the
<em>args</em>,
-or if there is no such callback, calls the <em>base</em> version of the
-callback with the same args, or if the f is invalid, set errno to
-EBADF.
-</p>
-<p>Perl_PerlIO_or_fail_void(PerlIO* f, callback, args) either calls the
-<em>callback</em> of the functions of the layer <em>f</em> with the
<em>args</em>, or if
-there is no such callback, set errno to EINVAL. Or if the f is
-invalid, set errno to EBADF.
-</p>
-<hr>
-<a name="perliol-Implementing-PerlIO-Layers"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-Core-Layers" accesskey="n" rel="next">perliol Core
Layers</a>, Previous: <a href="#perliol-Utilities" accesskey="p"
rel="prev">perliol Utilities</a>, Up: <a href="#perliol-DESCRIPTION"
accesskey="u" rel="up">perliol DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Implementing-PerlIO-Layers"></a>
-<h4 class="subsection">35.3.11 Implementing PerlIO Layers</h4>
-
-<p>If you find the implementation document unclear or not sufficient,
-look at the existing PerlIO layer implementations, which include:
-</p>
-<ul>
-<li> C implementations
-
-<p>The <samp>perlio.c</samp> and <samp>perliol.h</samp> in the Perl core
implement the
-"unix", "perlio", "stdio", "crlf",
"utf8", "byte", "raw", "pending"
-layers, and also the "mmap" and "win32" layers if
applicable.
-(The "win32" is currently unfinished and unused, to see what is used
-instead in Win32, see <a
href="PerlIO.html#Querying-the-layers-of-filehandles">(PerlIO)Querying the
layers of filehandles</a> .)
-</p>
-<p>PerlIO::encoding, PerlIO::scalar, PerlIO::via in the Perl core.
-</p>
-<p>PerlIO::gzip and APR::PerlIO (mod_perl 2.0) on CPAN.
-</p>
-</li><li> Perl implementations
-
-<p>PerlIO::via::QuotedPrint in the Perl core and PerlIO::via::* on CPAN.
-</p>
-</li></ul>
-
-<p>If you are creating a PerlIO layer, you may want to be lazy, in other
-words, implement only the methods that interest you. The other methods
-you can either replace with the "blank" methods
-</p>
-<pre class="verbatim"> PerlIOBase_noop_ok
- PerlIOBase_noop_fail
-</pre>
-<p>(which do nothing, and return zero and -1, respectively) or for
-certain methods you may assume a default behaviour by using a NULL
-method. The Open method looks for help in the ’parent’ layer.
-The following table summarizes the behaviour:
-</p>
-<pre class="verbatim"> method behaviour with NULL
-
- Clearerr PerlIOBase_clearerr
- Close PerlIOBase_close
- Dup PerlIOBase_dup
- Eof PerlIOBase_eof
- Error PerlIOBase_error
- Fileno PerlIOBase_fileno
- Fill FAILURE
- Flush SUCCESS
- Getarg SUCCESS
- Get_base FAILURE
- Get_bufsiz FAILURE
- Get_cnt FAILURE
- Get_ptr FAILURE
- Open INHERITED
- Popped SUCCESS
- Pushed SUCCESS
- Read PerlIOBase_read
- Seek FAILURE
- Set_cnt FAILURE
- Set_ptrcnt FAILURE
- Setlinebuf PerlIOBase_setlinebuf
- Tell FAILURE
- Unread PerlIOBase_unread
- Write FAILURE
-
- FAILURE Set errno (to EINVAL in Unixish, to LIB$_INVARG in VMS) and
- return -1 (for numeric return values) or NULL (for pointers)
- INHERITED Inherited from the layer below
- SUCCESS Return 0 (for numeric return values) or a pointer
-</pre>
-<hr>
-<a name="perliol-Core-Layers"></a>
-<div class="header">
-<p>
-Next: <a href="#perliol-Extension-Layers" accesskey="n" rel="next">perliol
Extension Layers</a>, Previous: <a href="#perliol-Implementing-PerlIO-Layers"
accesskey="p" rel="prev">perliol Implementing PerlIO Layers</a>, Up: <a
href="#perliol-DESCRIPTION" accesskey="u" rel="up">perliol DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Core-Layers"></a>
-<h4 class="subsection">35.3.12 Core Layers</h4>
-
-<p>The file <code>perlio.c</code> provides the following layers:
-</p>
-<dl compact="compact">
-<dt>"unix"</dt>
-<dd><a name="perliol-_0022unix_0022"></a>
-<p>A basic non-buffered layer which calls Unix/POSIX <code>read()</code>,
<code>write()</code>,
-<code>lseek()</code>, <code>close()</code>. No buffering. Even on platforms
that distinguish
-between O_TEXT and O_BINARY this layer is always O_BINARY.
-</p>
-</dd>
-<dt>"perlio"</dt>
-<dd><a name="perliol-_0022perlio_0022"></a>
-<p>A very complete generic buffering layer which provides the whole of
-PerlIO API. It is also intended to be used as a "base class" for
other
-layers. (For example its <code>Read()</code> method is implemented in terms of
-the <code>Get_cnt()</code>/<code>Get_ptr()</code>/<code>Set_ptrcnt()</code>
methods).
-</p>
-<p>"perlio" over "unix" provides a complete replacement
for stdio as seen
-via PerlIO API. This is the default for USE_PERLIO when system’s stdio
-does not permit perl’s "fast gets" access, and which do not
-distinguish between <code>O_TEXT</code> and <code>O_BINARY</code>.
-</p>
-</dd>
-<dt>"stdio"</dt>
-<dd><a name="perliol-_0022stdio_0022"></a>
-<p>A layer which provides the PerlIO API via the layer scheme, but
-implements it by calling system’s stdio. This is (currently) the default
-if system’s stdio provides sufficient access to allow perl’s
"fast gets"
-access and which do not distinguish between <code>O_TEXT</code> and
<code>O_BINARY</code>.
-</p>
-</dd>
-<dt>"crlf"</dt>
-<dd><a name="perliol-_0022crlf_0022"></a>
-<p>A layer derived using "perlio" as a base class. It provides
Win32-like
-"\n" to CR,LF translation. Can either be applied above
"perlio" or serve
-as the buffer layer itself. "crlf" over "unix" is the
default if system
-distinguishes between <code>O_TEXT</code> and <code>O_BINARY</code> opens. (At
some point
-"unix" will be replaced by a "native" Win32 IO layer on
that platform,
-as Win32’s read/write layer has various drawbacks.) The "crlf"
layer is
-a reasonable model for a layer which transforms data in some way.
-</p>
-</dd>
-<dt>"mmap"</dt>
-<dd><a name="perliol-_0022mmap_0022"></a>
-<p>If Configure detects <code>mmap()</code> functions this layer is provided
(with
-"perlio" as a "base") which does "read"
operations by mmap()ing the
-file. Performance improvement is marginal on modern systems, so it is
-mainly there as a proof of concept. It is likely to be unbundled from
-the core at some point. The "mmap" layer is a reasonable model for a
-minimalist "derived" layer.
-</p>
-</dd>
-<dt>"pending"</dt>
-<dd><a name="perliol-_0022pending_0022"></a>
-<p>An "internal" derivative of "perlio" which can be used
to provide
-Unread() function for layers which have no buffer or cannot be
-bothered. (Basically this layer’s <code>Fill()</code> pops itself off
the stack
-and so resumes reading from layer below.)
-</p>
-</dd>
-<dt>"raw"</dt>
-<dd><a name="perliol-_0022raw_0022"></a>
-<p>A dummy layer which never exists on the layer stack. Instead when
-"pushed" it actually pops the stack removing itself, it then calls
-Binmode function table entry on all the layers in the stack - normally
-this (via PerlIOBase_binmode) removes any layers which do not have
-<code>PERLIO_K_RAW</code> bit set. Layers can modify that behaviour by defining
-their own Binmode entry.
-</p>
-</dd>
-<dt>"utf8"</dt>
-<dd><a name="perliol-_0022utf8_0022"></a>
-<p>Another dummy layer. When pushed it pops itself and sets the
-<code>PERLIO_F_UTF8</code> flag on the layer which was (and now is once more)
-the top of the stack.
-</p>
-</dd>
-</dl>
-
-<p>In addition <samp>perlio.c</samp> also provides a number of
<code>PerlIOBase_xxxx()</code>
-functions which are intended to be used in the table slots of classes
-which do not need to do anything special for a particular method.
-</p>
-<hr>
-<a name="perliol-Extension-Layers"></a>
-<div class="header">
-<p>
-Previous: <a href="#perliol-Core-Layers" accesskey="p" rel="prev">perliol Core
Layers</a>, Up: <a href="#perliol-DESCRIPTION" accesskey="u" rel="up">perliol
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Extension-Layers"></a>
-<h4 class="subsection">35.3.13 Extension Layers</h4>
-
-<p>Layers can be made available by extension modules. When an unknown layer
-is encountered the PerlIO code will perform the equivalent of :
-</p>
-<pre class="verbatim"> use PerlIO 'layer';
-</pre>
-<p>Where <em>layer</em> is the unknown layer. <samp>PerlIO.pm</samp> will then
attempt to:
-</p>
-<pre class="verbatim"> require PerlIO::layer;
-</pre>
-<p>If after that process the layer is still not defined then the
<code>open</code>
-will fail.
-</p>
-<p>The following extension layers are bundled with perl:
-</p>
-<dl compact="compact">
-<dt>":encoding"</dt>
-<dd><a name="perliol-_0022_003aencoding_0022"></a>
-<pre class="verbatim"> use Encoding;
-</pre>
-<p>makes this layer available, although <samp>PerlIO.pm</samp>
"knows" where to
-find it. It is an example of a layer which takes an argument as it is
-called thus:
-</p>
-<pre class="verbatim"> open( $fh, "<:encoding(iso-8859-7)",
$pathname );
-</pre>
-</dd>
-<dt>":scalar"</dt>
-<dd><a name="perliol-_0022_003ascalar_0022"></a>
-<p>Provides support for reading data from and writing data to a scalar.
-</p>
-<pre class="verbatim"> open( $fh, "+<:scalar", \$scalar );
-</pre>
-<p>When a handle is so opened, then reads get bytes from the string value
-of <em>$scalar</em>, and writes change the value. In both cases the position
-in <em>$scalar</em> starts as zero but can be altered via <code>seek</code>,
and
-determined via <code>tell</code>.
-</p>
-<p>Please note that this layer is implied when calling open() thus:
-</p>
-<pre class="verbatim"> open( $fh, "+<", \$scalar );
-</pre>
-</dd>
-<dt>":via"</dt>
-<dd><a name="perliol-_0022_003avia_0022"></a>
-<p>Provided to allow layers to be implemented as Perl code. For instance:
-</p>
-<pre class="verbatim"> use PerlIO::via::StripHTML;
- open( my $fh, "<:via(StripHTML)", "index.html" );
-</pre>
-<p>See <a href="PerlIO-via.html#Top">(PerlIO-via)</a> for details.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perliol-TODO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perliol-DESCRIPTION" accesskey="p" rel="prev">perliol
DESCRIPTION</a>, Up: <a href="#perliol" accesskey="u" rel="up">perliol</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="TODO"></a>
-<h3 class="section">35.4 TODO</h3>
-
-<p>Things that need to be done to improve this document.
-</p>
-<ul>
-<li> Explain how to make a valid fh without going through open()(i.e. apply
-a layer). For example if the file is not opened through perl, but we
-want to get back a fh, like it was opened by Perl.
-
-<p>How PerlIO_apply_layera fits in, where its docs, was it made public?
-</p>
-<p>Currently the example could be something like this:
-</p>
-<pre class="verbatim"> PerlIO *foo_to_PerlIO(pTHX_ char *mode, ...)
- {
- char *mode; /* "w", "r", etc */
- const char *layers = ":APR"; /* the layer name */
- PerlIO *f = PerlIO_allocate(aTHX);
- if (!f) {
- return NULL;
- }
-
- PerlIO_apply_layers(aTHX_ f, mode, layers);
-
- if (f) {
- PerlIOAPR *st = PerlIOSelf(f, PerlIOAPR);
- /* fill in the st struct, as in _open() */
- st->file = file;
- PerlIOBase(f)->flags |= PERLIO_F_OPEN;
-
- return f;
- }
- return NULL;
- }
-</pre>
-</li><li> fix/add the documentation in places marked as XXX.
-
-</li><li> The handling of errors by the layer is not specified. e.g. when $!
-should be set explicitly, when the error handling should be just
-delegated to the top layer.
-
-<p>Probably give some hints on using SETERRNO() or pointers to where they
-can be found.
-</p>
-</li><li> I think it would help to give some concrete examples to make it
easier
-to understand the API. Of course I agree that the API has to be
-concise, but since there is no second document that is more of a
-guide, I think that it’d make it easier to start with the doc which is
-an API, but has examples in it in places where things are unclear, to
-a person who is not a PerlIO guru (yet).
-
-</li></ul>
-
-<hr>
-<a name="perlipc"></a>
-<div class="header">
-<p>
-Next: <a href="#perllexwarn" accesskey="n" rel="next">perllexwarn</a>,
Previous: <a href="#perliol" accesskey="p" rel="prev">perliol</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlipc-1"></a>
-<h2 class="chapter">36 perlipc</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlipc-NAME"
accesskey="1">perlipc NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-DESCRIPTION"
accesskey="2">perlipc DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-Signals"
accesskey="3">perlipc Signals</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-Named-Pipes"
accesskey="4">perlipc Named Pipes</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Using-open_0028_0029-for-IPC" accesskey="5">perlipc Using open()
for IPC</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Sockets_003a-Client_002fServer-Communication"
accesskey="6">perlipc Sockets: Client/Server
Communication</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-TCP-Clients-with-IO_003a_003aSocket" accesskey="7">perlipc TCP
Clients with IO::Socket</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-TCP-Servers-with-IO_003a_003aSocket" accesskey="8">perlipc TCP
Servers with IO::Socket</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-UDP_003a-Message-Passing" accesskey="9">perlipc UDP: Message
Passing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-SysV-IPC">perlipc
SysV IPC</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-NOTES">perlipc
NOTES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-BUGS">perlipc
BUGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-AUTHOR">perlipc
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-SEE-ALSO">perlipc
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlipc-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-DESCRIPTION" accesskey="n" rel="next">perlipc
DESCRIPTION</a>, Up: <a href="#perlipc" accesskey="u" rel="up">perlipc</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-35"></a>
-<h3 class="section">36.1 NAME</h3>
-
-<p>perlipc - Perl interprocess communication (signals, fifos, pipes, safe
subprocesses, sockets, and semaphores)
-</p>
-<hr>
-<a name="perlipc-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-Signals" accesskey="n" rel="next">perlipc Signals</a>,
Previous: <a href="#perlipc-NAME" accesskey="p" rel="prev">perlipc NAME</a>,
Up: <a href="#perlipc" accesskey="u" rel="up">perlipc</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-35"></a>
-<h3 class="section">36.2 DESCRIPTION</h3>
-
-<p>The basic IPC facilities of Perl are built out of the good old Unix
-signals, named pipes, pipe opens, the Berkeley socket routines, and SysV
-IPC calls. Each is used in slightly different situations.
-</p>
-<hr>
-<a name="perlipc-Signals"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-Named-Pipes" accesskey="n" rel="next">perlipc Named
Pipes</a>, Previous: <a href="#perlipc-DESCRIPTION" accesskey="p"
rel="prev">perlipc DESCRIPTION</a>, Up: <a href="#perlipc" accesskey="u"
rel="up">perlipc</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Signals"></a>
-<h3 class="section">36.3 Signals</h3>
-
-<p>Perl uses a simple signal handling model: the %SIG hash contains names
-or references of user-installed signal handlers. These handlers will
-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 own process
-running out of stack space, or hitting a process file-size limit.
-</p>
-<p>For example, to trap an interrupt signal, set up a handler like this:
-</p>
-<pre class="verbatim"> our $shucks;
-
- sub catch_zap {
- my $signame = shift;
- $shucks++;
- die "Somebody sent me a SIG$signame";
- }
- $SIG{INT} = __PACKAGE__ . "::catch_zap";
- $SIG{INT} = \&catch_zap; # best strategy
-</pre>
-<p>Prior to Perl 5.8.0 it was necessary to do as little as you possibly
-could in your handler; notice how all we do is set a global variable
-and then raise an exception. That’s because on most systems,
-libraries are not re-entrant; particularly, memory allocation and I/O
-routines are not. That meant that doing nearly <em>anything</em> in your
-handler could in theory trigger a memory fault and subsequent core
-dump - see <a href="#perlipc-Deferred-Signals-_0028Safe-Signals_0029">Deferred
Signals (Safe Signals)</a> below.
-</p>
-<p>The names of the signals are the ones listed out by <code>kill -l</code> on
your
-system, or you can retrieve them using the CPAN module <a
href="IPC-Signal.html#Top">(IPC-Signal)</a>.
-</p>
-<p>You may also choose to assign the strings <code>"IGNORE"</code>
or <code>"DEFAULT"</code> as
-the handler, in which case Perl will try to discard the signal or do the
-default thing.
-</p>
-<p>On most Unix platforms, the <code>CHLD</code> (sometimes also known as
<code>CLD</code>) signal
-has special behavior with respect to a value of
<code>"IGNORE"</code>.
-Setting <code>$SIG{CHLD}</code> to <code>"IGNORE"</code> on such a
platform has the effect of
-not creating zombie processes when the parent process fails to
<code>wait()</code>
-on its child processes (i.e., child processes are automatically reaped).
-Calling <code>wait()</code> with <code>$SIG{CHLD}</code> set to
<code>"IGNORE"</code> usually returns
-<code>-1</code> on such platforms.
-</p>
-<p>Some signals can be neither trapped nor ignored, such as the KILL and STOP
-(but not the TSTP) signals. Note that ignoring signals makes them disappear.
-If you only want them blocked temporarily without them getting lost
you’ll
-have to use POSIX’ sigprocmask.
-</p>
-<p>Sending a signal to a negative process ID means that you send the signal
-to the entire Unix process group. This code sends a hang-up signal to all
-processes in the current process group, and also sets $SIG{HUP} to
<code>"IGNORE"</code>
-so it doesn’t kill itself:
-</p>
-<pre class="verbatim"> # block scope for local
- {
- local $SIG{HUP} = "IGNORE";
- kill HUP => -$$;
- # snazzy writing of: kill("HUP", -$$)
- }
-</pre>
-<p>Another interesting signal to send is signal number zero. This
doesn’t
-actually affect a child process, but instead checks whether it’s alive
-or has changed its UIDs.
-</p>
-<pre class="verbatim"> unless (kill 0 => $kid_pid) {
- warn "something wicked happened to $kid_pid";
- }
-</pre>
-<p>Signal number zero may fail because you lack permission to send the
-signal when directed at a process whose real or saved UID is not
-identical to the real or effective UID of the sending process, even
-though the process is alive. You may be able to determine the cause of
-failure using <code>$!</code> or <code>%!</code>.
-</p>
-<pre class="verbatim"> unless (kill(0 => $pid) || $!{EPERM}) {
- warn "$pid looks dead";
- }
-</pre>
-<p>You might also want to employ anonymous functions for simple signal
-handlers:
-</p>
-<pre class="verbatim"> $SIG{INT} = sub { die "\nOutta here!\n" };
-</pre>
-<p>SIGCHLD handlers require some special care. If a second child dies
-while in the signal handler caused by the first death, we won’t get
-another signal. So must loop here else we will leave the unreaped child
-as a zombie. And the next time two children die we get another zombie.
-And so on.
-</p>
-<pre class="verbatim"> use POSIX ":sys_wait_h";
- $SIG{CHLD} = sub {
- while ((my $child = waitpid(-1, WNOHANG)) > 0) {
- $Kid_Status{$child} = $?;
- }
- };
- # do something that forks...
-</pre>
-<p>Be careful: qx(), system(), and some modules for calling external commands
-do a fork(), then wait() for the result. Thus, your signal handler
-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.
-</p>
-<p>The best way to prevent this issue is to use waitpid(), as in the following
-example:
-</p>
-<pre class="verbatim"> use POSIX ":sys_wait_h"; # for nonblocking
read
-
- my %children;
-
- $SIG{CHLD} = sub {
- # don't change $! and $? outside handler
- local ($!, $?);
- while ( (my $pid = waitpid(-1, WNOHANG)) > 0 ) {
- delete $children{$pid};
- cleanup_child($pid, $?);
- }
- };
-
- while (1) {
- my $pid = fork();
- die "cannot fork" unless defined $pid;
- if ($pid == 0) {
- # ...
- exit 0;
- } else {
- $children{$pid}=1;
- # ...
- system($command);
- # ...
- }
- }
-</pre>
-<p>Signal handling is also used for timeouts in Unix. While safely
-protected within an <code>eval{}</code> block, you set a signal handler to trap
-alarm signals and then schedule to have one delivered to you in some
-number of seconds. Then try your blocking operation, clearing the alarm
-when it’s done but not before you’ve exited your
<code>eval{}</code> block. If it
-goes off, you’ll use die() to jump out of the block.
-</p>
-<p>Here’s an example:
-</p>
-<pre class="verbatim"> my $ALARM_EXCEPTION = "alarm clock
restart";
- eval {
- local $SIG{ALRM} = sub { die $ALARM_EXCEPTION };
- alarm 10;
- flock(FH, 2) # blocking write lock
- || die "cannot flock: $!";
- alarm 0;
- };
- if ($@ && $@ !~ quotemeta($ALARM_EXCEPTION)) { die }
-</pre>
-<p>If the operation being timed out is system() or qx(), this technique
-is liable to generate zombies. If this matters to you, you’ll
-need to do your own fork() and exec(), and kill the errant child process.
-</p>
-<p>For more complex signal handling, you might see the standard POSIX
-module. Lamentably, this is almost entirely undocumented, but
-the <samp>t/lib/posix.t</samp> file from the Perl source distribution has some
-examples in it.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlipc-Handling-the-SIGHUP-Signal-in-Daemons" accesskey="1">perlipc
Handling the SIGHUP Signal in Daemons</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Deferred-Signals-_0028Safe-Signals_0029" accesskey="2">perlipc
Deferred Signals (Safe Signals)</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlipc-Handling-the-SIGHUP-Signal-in-Daemons"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-Deferred-Signals-_0028Safe-Signals_0029" accesskey="n"
rel="next">perlipc Deferred Signals (Safe Signals)</a>, Up: <a
href="#perlipc-Signals" accesskey="u" rel="up">perlipc Signals</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Handling-the-SIGHUP-Signal-in-Daemons"></a>
-<h4 class="subsection">36.3.1 Handling the SIGHUP Signal in Daemons</h4>
-
-<p>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 reread its configuration file without stopping
-the process. Many daemons provide this mechanism using a <code>SIGHUP</code>
-signal handler. When you want to tell the daemon to reread the file,
-simply send it the <code>SIGHUP</code> signal.
-</p>
-<p>The following example implements a simple daemon, which restarts
-itself every time the <code>SIGHUP</code> signal is received. The actual code
is
-located in the subroutine <code>code()</code>, which just prints some debugging
-info to show that it works; it should be replaced with the real code.
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
-
- use strict;
- use warnings;
-
- use POSIX ();
- use FindBin ();
- use File::Basename ();
- use File::Spec::Functions qw(catfile);
-
- $| = 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);
-
- # POSIX unmasks the sigprocmask properly
- $SIG{HUP} = sub {
- print "got SIGHUP\n";
- exec($SELF, @ARGV) || die "$0: couldn't restart: $!";
- };
-
- code();
-
- sub code {
- print "PID: $$\n";
- print "ARGV: @ARGV\n";
- my $count = 0;
- while (1) {
- sleep 2;
- print ++$count, "\n";
- }
- }
-</pre>
-<hr>
-<a name="perlipc-Deferred-Signals-_0028Safe-Signals_0029"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlipc-Handling-the-SIGHUP-Signal-in-Daemons"
accesskey="p" rel="prev">perlipc Handling the SIGHUP Signal in Daemons</a>, Up:
<a href="#perlipc-Signals" accesskey="u" rel="up">perlipc Signals</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Deferred-Signals-_0028Safe-Signals_0029"></a>
-<h4 class="subsection">36.3.2 Deferred Signals (Safe Signals)</h4>
-
-<p>Before Perl 5.8.0, installing Perl code to deal with signals exposed you to
-danger from two things. First, few system library functions are
-re-entrant. If the signal interrupts while Perl is executing one function
-(like malloc(3) or printf(3)), and your signal handler then calls the same
-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.
-</p>
-<p>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
-signal handler. Set an existing integer variable that already has a
-value, and return. This doesn’t help you if you’re in a slow
system call,
-which will just restart. That means you have to <code>die</code> to
longjmp(3) out
-of the handler. Even this is a little cavalier for the true paranoiac,
-who avoids <code>die</code> in a handler because the system <em>is</em> out to
get you.
-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.
-</p>
-<p>Perl 5.8.0 and later avoid these problems by "deferring" signals.
That is,
-when the signal is delivered to the process by the system (to the C code
-that implements Perl) a flag is set, and the handler returns immediately.
-Then at strategic "safe" points in the Perl interpreter (e.g. when
it is
-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:
-</p>
-<dl compact="compact">
-<dt>Long-running opcodes</dt>
-<dd><a name="perlipc-Long_002drunning-opcodes"></a>
-<p>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.
-</p>
-<p>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
-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
-completes, those signals may well be caught and deferred during
-subsequent opcodes, with sometimes surprising results. For example, you
-may see alarms delivered even after calling <code>alarm(0)</code> as the latter
-stops the raising of alarms but does not cancel the delivery of alarms
-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.
-</p>
-</dd>
-<dt>Interrupting IO</dt>
-<dd><a name="perlipc-Interrupting-IO"></a>
-<p>When a signal is delivered (e.g., SIGINT from a control-C) the operating
-system breaks into IO operations like <em>read</em>(2), which is used to
-implement Perl’s readline() function, the <code><></code>
operator. On older
-Perls the handler was called immediately (and as <code>read</code> is not
"unsafe",
-this worked well). With the "deferred" scheme the handler is
<em>not</em> called
-immediately, and if Perl is using the system’s <code>stdio</code>
library that
-library may restart the <code>read</code> 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 <code>:perlio</code> layer to do IO–at least on
those handles
-that you want to be able to break into with signals. (The <code>:perlio</code>
layer
-checks the signal flags and calls %SIG handlers before resuming IO
-operation.)
-</p>
-<p>The default in Perl 5.8.0 and later is to automatically use
-the <code>:perlio</code> layer.
-</p>
-<p>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.
-</p>
-<p>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.
-</p>
-<p>Instead of setting <code>$SIG{ALRM}</code>:
-</p>
-<pre class="verbatim"> local $SIG{ALRM} = sub { die "alarm" };
-</pre>
-<p>try something like the following:
-</p>
-<pre class="verbatim"> use POSIX qw(SIGALRM);
- POSIX::sigaction(SIGALRM, POSIX::SigAction->new(sub { die
"alarm" }))
- || die "Error setting SIGALRM handler: $!\n";
-</pre>
-<p>Another way to disable the safe signal behavior locally is to use
-the <code>Perl::Unsafe::Signals</code> module from CPAN, which affects
-all signals.
-</p>
-</dd>
-<dt>Restartable system calls</dt>
-<dd><a name="perlipc-Restartable-system-calls"></a>
-<p>On systems that supported it, older versions of Perl used the
-SA_RESTART flag when installing %SIG handlers. This meant that
-restartable system calls would continue rather than returning when
-a signal arrived. In order to deliver deferred signals promptly,
-Perl 5.8.0 and later do <em>not</em> use SA_RESTART. Consequently,
-restartable system calls can fail (with $! set to <code>EINTR</code>) in places
-where they previously would have succeeded.
-</p>
-<p>The default <code>:perlio</code> layer retries <code>read</code>,
<code>write</code>
-and <code>close</code> as described above; interrupted <code>wait</code> and
-<code>waitpid</code> calls will always be retried.
-</p>
-</dd>
-<dt>Signals as "faults"</dt>
-<dd><a name="perlipc-Signals-as-_0022faults_0022"></a>
-<p>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 delivers them
-immediately rather than attempting to defer them.
-</p>
-</dd>
-<dt>Signals triggered by operating system state</dt>
-<dd><a name="perlipc-Signals-triggered-by-operating-system-state"></a>
-<p>On some operating systems certain signal handlers are supposed to "do
-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 <code>wait</code> for the completed child
-process. On such systems the deferred signal scheme will not work for
-those signals: it does not do the <code>wait</code>. 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 <code>wait</code>ed
for.
-</p>
-</dd>
-</dl>
-
-<p>If you want the old signal behavior back despite possible
-memory corruption, set the environment variable <code>PERL_SIGNALS</code> to
-<code>"unsafe"</code>. This feature first appeared in Perl 5.8.1.
-</p>
-<hr>
-<a name="perlipc-Named-Pipes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-Using-open_0028_0029-for-IPC" accesskey="n"
rel="next">perlipc Using open() for IPC</a>, Previous: <a
href="#perlipc-Signals" accesskey="p" rel="prev">perlipc Signals</a>, Up: <a
href="#perlipc" accesskey="u" rel="up">perlipc</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Named-Pipes"></a>
-<h3 class="section">36.4 Named Pipes</h3>
-
-<p>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.
-</p>
-<p>To create a named pipe, use the <code>POSIX::mkfifo()</code> function.
-</p>
-<pre class="verbatim"> use POSIX qw(mkfifo);
- mkfifo($path, 0700) || die "mkfifo $path failed: $!";
-</pre>
-<p>You can also use the Unix command mknod(1), or on some
-systems, mkfifo(1). These may not be in your normal path, though.
-</p>
-<pre class="verbatim"> # 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";
- }
-</pre>
-<p>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.
-</p>
-<p>For example, let’s say you’d like to have your
<samp>.signature</samp> 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,
<strong>-p</strong>, to find
-out whether anyone (or anything) has accidentally removed our fifo.
-</p>
-<pre class="verbatim"> 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 (address@hidden)\n", `fortune -s`;
- close(FIFO) || die "can't close $FIFO: $!";
- sleep 2; # to avoid dup signals
- }
-</pre>
-<hr>
-<a name="perlipc-Using-open_0028_0029-for-IPC"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-Sockets_003a-Client_002fServer-Communication"
accesskey="n" rel="next">perlipc Sockets: Client/Server Communication</a>,
Previous: <a href="#perlipc-Named-Pipes" accesskey="p" rel="prev">perlipc Named
Pipes</a>, Up: <a href="#perlipc" accesskey="u" rel="up">perlipc</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-open_0028_0029-for-IPC"></a>
-<h3 class="section">36.5 Using open() for IPC</h3>
-
-<p>Perl’s basic open() statement can also be used for unidirectional
-interprocess communication by either appending or prepending a pipe
-symbol to the second argument to open(). Here’s how to start
-something up in a child process you intend to write to:
-</p>
-<pre class="verbatim"> open(SPOOLER, "| cat -v | lpr -h
2>/dev/null")
- || die "can't fork: $!";
- local $SIG{PIPE} = sub { die "spooler pipe broke" };
- print SPOOLER "stuff\n";
- close SPOOLER || die "bad spool: $! $?";
-</pre>
-<p>And here’s how to start up a child process you intend to read from:
-</p>
-<pre class="verbatim"> open(STATUS, "netstat -an 2>&1 |")
- || die "can't fork: $!";
- while (<STATUS>) {
- next if /^(tcp|udp)/;
- print;
- }
- close STATUS || die "bad netstat: $! $?";
-</pre>
-<p>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:
-</p>
-<pre class="verbatim"> % program f1 "cmd1|" - f2
"cmd2|" f3 < tmpfile
-</pre>
-<p>and no matter which sort of shell it’s called from, the Perl program
will
-read from the file <samp>f1</samp>, the process <samp>cmd1</samp>, standard
input (<samp>tmpfile</samp>
-in this case), the <samp>f2</samp> file, the <samp>cmd2</samp> command, and
finally the <samp>f3</samp>
-file. Pretty nifty, eh?
-</p>
-<p>You might notice that you could use backticks for much the
-same effect as opening a pipe for reading:
-</p>
-<pre class="verbatim"> print grep { !/^(tcp|udp)/ } `netstat -an
2>&1`;
- die "bad netstatus ($?)" if $?;
-</pre>
-<p>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 kill off the child process early if you’d
like.
-</p>
-<p>Be careful to check the return values from both open() and close(). If
-you’re <em>writing</em> 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
-running in a separate process whose exec() might have failed. Therefore,
-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:
-</p>
-<pre class="verbatim"> 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: $!";
-</pre>
-<p>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:
-</p>
-<pre class="verbatim"> $SIG{PIPE} = "IGNORE";
- open(FH, "|bogus") || die "can't fork: $!";
- print FH "bang\n";
- close(FH) || die "can't close: status=$?";
-</pre>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlipc-Filehandles"
accesskey="1">perlipc Filehandles</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Background-Processes" accesskey="2">perlipc Background
Processes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Complete-Dissociation-of-Child-from-Parent"
accesskey="3">perlipc Complete Dissociation of Child from
Parent</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-Safe-Pipe-Opens"
accesskey="4">perlipc Safe Pipe Opens</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Avoiding-Pipe-Deadlocks" accesskey="5">perlipc Avoiding Pipe
Deadlocks</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Bidirectional-Communication-with-Another-Process"
accesskey="6">perlipc Bidirectional Communication with Another
Process</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Bidirectional-Communication-with-Yourself" accesskey="7">perlipc
Bidirectional Communication with Yourself</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlipc-Filehandles"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-Background-Processes" accesskey="n" rel="next">perlipc
Background Processes</a>, Up: <a href="#perlipc-Using-open_0028_0029-for-IPC"
accesskey="u" rel="up">perlipc Using open() for IPC</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Filehandles"></a>
-<h4 class="subsection">36.5.1 Filehandles</h4>
-
-<p>Both the main process and any child processes it forks share the same
-STDIN, STDOUT, and STDERR filehandles. If both processes try to access
-them at once, strange things can happen. You may also want to close
-or reopen the filehandles for the child. You can get around this by
-opening your pipe with open(), but on some systems this means that the
-child process cannot outlive the parent.
-</p>
-<hr>
-<a name="perlipc-Background-Processes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-Complete-Dissociation-of-Child-from-Parent"
accesskey="n" rel="next">perlipc Complete Dissociation of Child from
Parent</a>, Previous: <a href="#perlipc-Filehandles" accesskey="p"
rel="prev">perlipc Filehandles</a>, Up: <a
href="#perlipc-Using-open_0028_0029-for-IPC" accesskey="u" rel="up">perlipc
Using open() for IPC</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Background-Processes"></a>
-<h4 class="subsection">36.5.2 Background Processes</h4>
-
-<p>You can run a command in the background with:
-</p>
-<pre class="verbatim"> system("cmd &");
-</pre>
-<p>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 details.
-</p>
-<hr>
-<a name="perlipc-Complete-Dissociation-of-Child-from-Parent"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-Safe-Pipe-Opens" accesskey="n" rel="next">perlipc Safe
Pipe Opens</a>, Previous: <a href="#perlipc-Background-Processes" accesskey="p"
rel="prev">perlipc Background Processes</a>, Up: <a
href="#perlipc-Using-open_0028_0029-for-IPC" accesskey="u" rel="up">perlipc
Using open() for IPC</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Complete-Dissociation-of-Child-from-Parent"></a>
-<h4 class="subsection">36.5.3 Complete Dissociation of Child from Parent</h4>
-
-<p>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 <samp>/dev/null</samp> so that random
-output doesn’t wind up on the user’s terminal.
-</p>
-<pre class="verbatim"> use POSIX "setsid";
-
- sub daemonize {
- 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: $!";
- }
-</pre>
-<p>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 <samp>/dev/tty</samp>
and use the
-<code>TIOCNOTTY</code> ioctl() on it instead. See tty(4) for details.
-</p>
-<p>Non-Unix users should check their <code><em>Your_OS</em>::Process</code>
module for
-other possible solutions.
-</p>
-<hr>
-<a name="perlipc-Safe-Pipe-Opens"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-Avoiding-Pipe-Deadlocks" accesskey="n"
rel="next">perlipc Avoiding Pipe Deadlocks</a>, Previous: <a
href="#perlipc-Complete-Dissociation-of-Child-from-Parent" accesskey="p"
rel="prev">perlipc Complete Dissociation of Child from Parent</a>, Up: <a
href="#perlipc-Using-open_0028_0029-for-IPC" accesskey="u" rel="up">perlipc
Using open() for IPC</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Safe-Pipe-Opens"></a>
-<h4 class="subsection">36.5.4 Safe Pipe Opens</h4>
-
-<p>Another interesting approach to IPC is making your single program go
-multiprocess and communicate between–or even amongst–yourselves.
The
-open() function will accept a file argument of either
<code>"-|"</code> or <code>"|-"</code>
-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 <em>to</em> minus, you can
-write to the filehandle you opened and your kid will find it in <em>his</em>
-STDIN. If you open a pipe <em>from</em> minus, you can read from the
filehandle
-you opened whatever your kid writes to <em>his</em> STDOUT.
-</p>
-<pre class="verbatim"> use English;
- 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;
- }
- } until defined $pid;
-
- 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!!
- }
-</pre>
-<p>Another common use for this construct is when you need to execute
-something without the shell’s interference. With system(), it’s
-straightforward, but you can’t use a pipe open or backticks safely.
-That’s because there’s no way to stop the shell from getting its
hands on
-your arguments. Instead, use lower-level control to call exec() directly.
-</p>
-<p>Here’s a safe backtick or pipe open for read:
-</p>
-<pre class="verbatim"> 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 $?";
-
- } else { # child
- ($EUID, $EGID) = ($UID, $GID); # suid only
- exec($program, @options, @args)
- || die "can't exec program: $!";
- # NOTREACHED
- }
-</pre>
-<p>And here’s a safe pipe open for writing:
-</p>
-<pre class="verbatim"> my $pid = open(KID_TO_WRITE, "|-");
- defined($pid) || die "can't fork: $!";
-
- $SIG{PIPE} = sub { die "whoops, $program pipe broke" };
-
- 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
- }
-</pre>
-<p>It is very easy to dead-lock a process using this form of open(), or
-indeed with any use of pipe() with multiple subprocesses. The
-example above is "safe" because it is simple and calls exec(). See
-<a href="#perlipc-Avoiding-Pipe-Deadlocks">Avoiding Pipe Deadlocks</a> for
general safety principles, but there
-are extra gotchas with Safe Pipe Opens.
-</p>
-<p>In particular, if you opened the pipe using <code>open FH,
"|-"</code>, then you
-cannot simply use close() in the parent process to close an unwanted
-writer. Consider this code:
-</p>
-<pre class="verbatim"> my $pid = open(WRITER, "|-"); #
fork open a kid
- defined($pid) || die "first fork failed: $!";
- if ($pid) {
- if (my $sub_pid = fork()) {
- defined($sub_pid) || die "second fork failed: $!";
- close(WRITER) || die "couldn't close WRITER: $!";
- # now do something else...
- }
- else {
- # first write to WRITER
- # ...
- # then when finished
- close(WRITER) || die "couldn't close WRITER: $!";
- exit(0);
- }
- }
- else {
- # first do something with STDIN, then
- exit(0);
- }
-</pre>
-<p>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
-<code>open FH, "|-"</code>, it has a special behavior: closing it
calls
-waitpid() (see ‘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", you have deadlock.
-</p>
-<p>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.
-</p>
-<p>To solve this, you must manually use pipe(), fork(), and the form of
-open() which sets one file descriptor to another, as shown below:
-</p>
-<pre class="verbatim"> pipe(READER, WRITER) || die "pipe
failed: $!";
- $pid = fork();
- defined($pid) || die "first fork failed: $!";
- if ($pid) {
- close READER;
- if (my $sub_pid = fork()) {
- defined($sub_pid) || die "first fork failed: $!";
- close(WRITER) || die "can't close WRITER: $!";
- }
- else {
- # write to WRITER...
- # ...
- # then when finished
- close(WRITER) || die "can't close WRITER: $!";
- exit(0);
- }
- # write to WRITER...
- }
- else {
- open(STDIN, "<&READER") || die "can't reopen
STDIN: $!";
- close(WRITER) || die "can't close WRITER: $!";
- # do something...
- exit(0);
- }
-</pre>
-<p>Since Perl 5.8.0, you can also use the list form of <code>open</code> for
pipes.
-This is preferred when you wish to avoid having the shell interpret
-metacharacters that may be in your command string.
-</p>
-<p>So for example, instead of using:
-</p>
-<pre class="verbatim"> open(PS_PIPE, "ps aux|") || die
"can't open ps pipe: $!";
-</pre>
-<p>One would use either of these:
-</p>
-<pre class="verbatim"> open(PS_PIPE, "-|", "ps",
"aux")
- || die "can't open ps pipe: $!";
-
- @ps_args = qw[ ps aux ];
- open(PS_PIPE, "-|", @ps_args)
- || die "can't open @ps_args|: $!";
-</pre>
-<p>Because there are more than three arguments to open(), forks the ps(1)
-command <em>without</em> spawning a shell, and reads its standard output via
the
-<code>PS_PIPE</code> filehandle. The corresponding syntax to <em>write</em>
to command
-pipes is to use <code>"|-"</code> in place of
<code>"-|"</code>.
-</p>
-<p>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:
-</p>
-<pre class="verbatim"> @grep_args = ("egrep", "-i",
$some_pattern, @many_files);
- open(GREP_PIPE, "-|", @grep_args)
- || die "can't open @grep_args|: $!";
-</pre>
-<p>Here the multi-argument form of pipe open() is preferred because the
-pattern and indeed even the filenames themselves might hold metacharacters.
-</p>
-<p>Be aware that these operations are full Unix forks, which means they may
-not be correctly implemented on all alien systems.
-</p>
-<hr>
-<a name="perlipc-Avoiding-Pipe-Deadlocks"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-Bidirectional-Communication-with-Another-Process"
accesskey="n" rel="next">perlipc Bidirectional Communication with Another
Process</a>, Previous: <a href="#perlipc-Safe-Pipe-Opens" accesskey="p"
rel="prev">perlipc Safe Pipe Opens</a>, Up: <a
href="#perlipc-Using-open_0028_0029-for-IPC" accesskey="u" rel="up">perlipc
Using open() for IPC</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Avoiding-Pipe-Deadlocks"></a>
-<h4 class="subsection">36.5.5 Avoiding Pipe Deadlocks</h4>
-
-<p>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.
-</p>
-<p>Certain built-in Unix features help prevent this most of the time. For
-instance, filehandles have a "close on exec" flag, which is set
<em>en masse</em>
-under control of the <code>$^F</code> variable. This is so any filehandles you
-didn’t explicitly route to the STDIN, STDOUT or STDERR of a child
-<em>program</em> will be automatically closed.
-</p>
-<p>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.
-</p>
-<hr>
-<a name="perlipc-Bidirectional-Communication-with-Another-Process"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-Bidirectional-Communication-with-Yourself"
accesskey="n" rel="next">perlipc Bidirectional Communication with Yourself</a>,
Previous: <a href="#perlipc-Avoiding-Pipe-Deadlocks" accesskey="p"
rel="prev">perlipc Avoiding Pipe Deadlocks</a>, Up: <a
href="#perlipc-Using-open_0028_0029-for-IPC" accesskey="u" rel="up">perlipc
Using open() for IPC</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Bidirectional-Communication-with-Another-Process"></a>
-<h4 class="subsection">36.5.6 Bidirectional Communication with Another
Process</h4>
-
-<p>While this works reasonably well for unidirectional communication, what
-about bidirectional communication? The most obvious approach doesn’t
work:
-</p>
-<pre class="verbatim"> # THIS DOES NOT WORK!!
- open(PROG_FOR_READING_AND_WRITING, "| some program |")
-</pre>
-<p>If you forget to <code>use warnings</code>, you’ll miss out entirely
on the
-helpful diagnostic message:
-</p>
-<pre class="verbatim"> Can't do bidirectional pipe at -e line 1.
-</pre>
-<p>If you really want to, you can use the standard open2() from the
-<code>IPC::Open2</code> module to catch both ends. There’s also an
open3() in
-<code>IPC::Open3</code> 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.
-</p>
-<p>If you look at its source, you’ll see that open2() uses low-level
-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.
-</p>
-<p>Here’s an example of using open2():
-</p>
-<pre class="verbatim"> use FileHandle;
- use IPC::Open2;
- $pid = open2(*Reader, *Writer, "cat -un");
- print Writer "stuff\n";
- $got = <Reader>;
-</pre>
-<p>The problem with this is that buffering is really going to ruin your
-day. Even though your <code>Writer</code> 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
-<em>cat</em> a <strong>-u</strong> 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.
-</p>
-<p>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
<code>Expect</code> module
-from CPAN also addresses this kind of thing. This module requires two
-other modules from CPAN, <code>IO::Pty</code> and <code>IO::Stty</code>. 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.
-</p>
-<hr>
-<a name="perlipc-Bidirectional-Communication-with-Yourself"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlipc-Bidirectional-Communication-with-Another-Process"
accesskey="p" rel="prev">perlipc Bidirectional Communication with Another
Process</a>, Up: <a href="#perlipc-Using-open_0028_0029-for-IPC" accesskey="u"
rel="up">perlipc Using open() for IPC</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Bidirectional-Communication-with-Yourself"></a>
-<h4 class="subsection">36.5.7 Bidirectional Communication with Yourself</h4>
-
-<p>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.)
-</p>
-<pre class="verbatim"> #!/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: 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);
- } 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(0);
- }
-</pre>
-<p>But you don’t actually have to make two pipe calls. If you
-have the socketpair() system call, it will do this all for you.
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -w
- # pipe2 - bidirectional communication using socketpair
- # "the best ones always go both ways"
-
- use Socket;
- 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)
- || 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);
- } 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(0);
- }
-</pre>
-<hr>
-<a name="perlipc-Sockets_003a-Client_002fServer-Communication"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-TCP-Clients-with-IO_003a_003aSocket" accesskey="n"
rel="next">perlipc TCP Clients with IO::Socket</a>, Previous: <a
href="#perlipc-Using-open_0028_0029-for-IPC" accesskey="p" rel="prev">perlipc
Using open() for IPC</a>, Up: <a href="#perlipc" accesskey="u"
rel="up">perlipc</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Sockets_003a-Client_002fServer-Communication"></a>
-<h3 class="section">36.6 Sockets: Client/Server Communication</h3>
-
-<p>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.
-</p>
-<p>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
-descriptors. Second, Perl already knows the length of its strings, so you
-don’t need to pass that information.
-</p>
-<p>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 <code>$AF_INET = 2</code>, you know you’re in for big
trouble.
-An immeasurably superior approach is to use the <code>Socket</code> module,
which more
-reliably grants access to the various constants and functions you’ll
need.
-</p>
-<p>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
-know when the client has finished talking, and vice-versa. Most
-protocols are based on one-line messages and responses (so one party
-knows the other has finished when a "\n" is received) or multi-line
-messages and responses that end with a period on an empty line
-("\n.\n" terminates a message/response).
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlipc-Internet-Line-Terminators" accesskey="1">perlipc Internet Line
Terminators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Internet-TCP-Clients-and-Servers" accesskey="2">perlipc Internet
TCP Clients and Servers</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Unix_002dDomain-TCP-Clients-and-Servers" accesskey="3">perlipc
Unix-Domain TCP Clients and Servers</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlipc-Internet-Line-Terminators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-Internet-TCP-Clients-and-Servers" accesskey="n"
rel="next">perlipc Internet TCP Clients and Servers</a>, Up: <a
href="#perlipc-Sockets_003a-Client_002fServer-Communication" accesskey="u"
rel="up">perlipc Sockets: Client/Server Communication</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Internet-Line-Terminators"></a>
-<h4 class="subsection">36.6.1 Internet Line Terminators</h4>
-
-<p>The Internet line terminator is "\015\012". Under ASCII variants
of
-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 (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 from way back in its pre-Unix dark ages,
you’ll
-probably be ok.
-</p>
-<hr>
-<a name="perlipc-Internet-TCP-Clients-and-Servers"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-Unix_002dDomain-TCP-Clients-and-Servers" accesskey="n"
rel="next">perlipc Unix-Domain TCP Clients and Servers</a>, Previous: <a
href="#perlipc-Internet-Line-Terminators" accesskey="p" rel="prev">perlipc
Internet Line Terminators</a>, Up: <a
href="#perlipc-Sockets_003a-Client_002fServer-Communication" accesskey="u"
rel="up">perlipc Sockets: Client/Server Communication</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Internet-TCP-Clients-and-Servers"></a>
-<h4 class="subsection">36.6.2 Internet TCP Clients and Servers</h4>
-
-<p>Use Internet-domain sockets when you want to do client-server
-communication that might extend to machines outside of your own system.
-</p>
-<p>Here’s a sample TCP client using Internet-domain sockets:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -w
- use strict;
- use Socket;
- my ($remote, $port, $iaddr, $paddr, $proto, $line);
-
- $remote = shift || "localhost";
- $port = shift || 2345; # random port
- if ($port =~ /\D/) { $port = getservbyname($port, "tcp") }
- die "No port" unless $port;
- $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 ($line = <SOCK>) {
- print $line;
- }
-
- close (SOCK) || die "close: $!";
- exit(0);
-</pre>
-<p>And here’s a corresponding server to go along with it. We’ll
-leave the address as <code>INADDR_ANY</code> 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), fill this in with your real address instead.
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -Tw
- use strict;
- BEGIN { $ENV{PATH} = "/usr/bin:/bin" }
- use Socket;
- use Carp;
- my $EOL = "\015\012";
-
- sub logmsg { print "$0 $$: @_ at ", scalar localtime(),
"\n" }
-
- my $port = shift || 2345;
- die "invalid port" unless if $port =~ /^ \d+ $/x;
-
- 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:
$!";
-
- logmsg "server started on port $port";
-
- my $paddr;
-
- $SIG{CHLD} = \&REAPER;
-
- 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";
-
- print Client "Hello there, $name, it's now ",
- scalar localtime(), $EOL;
- }
-</pre>
-<p>And here’s a multitasking version. It’s multitasked in that
-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.
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -Tw
- use strict;
- 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" }
-
- my $port = shift || 2345;
- die "invalid port" unless $port =~ /^ \d+ $/x;
-
- 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:
$!";
-
- logmsg "server started on port $port";
-
- my $waitedpid = 0;
- my $paddr;
-
- use POSIX ":sys_wait_h";
- use Errno;
-
- sub REAPER {
- local $!; # don't let waitpid() overwrite current error
- while ((my $pid = waitpid(-1, WNOHANG)) > 0 &&
WIFEXITED($?)) {
- logmsg "reaped $waitedpid" . ($? ? " with exit
$?" : "");
- }
- $SIG{CHLD} = \&REAPER; # loathe SysV
- }
-
- $SIG{CHLD} = \&REAPER;
-
- while (1) {
- $paddr = accept(Client, Server) || do {
- # try again if accept() returned because got a signal
- next if $!{EINTR};
- die "accept: $!";
- };
- my ($port, $iaddr) = sockaddr_in($paddr);
- my $name = gethostbyaddr($iaddr, AF_INET);
-
- logmsg "connection from $name [",
- inet_ntoa($iaddr),
- "] at port $port";
-
- spawn sub {
- $| = 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;
- }
-
- sub spawn {
- 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->());
- }
-</pre>
-<p>This server takes the trouble to clone off a child version via fork()
-for each incoming request. That way it can handle many requests at
-once, which you might not always want. Even if you don’t fork(), the
-listen() will allow that many pending connections. Forking servers
-have to be particularly careful about cleaning up their dead children
-(called "zombies" in Unix parlance), because otherwise you’ll
quickly
-fill up your process table. The REAPER subroutine is used here to
-call waitpid() for any child processes that have finished, thereby
-ensuring that they terminate cleanly and don’t join the ranks of the
-living dead.
-</p>
-<p>Within the while loop we call accept() and check to see if it returns
-a false value. This would normally indicate a system error needs
-to be reported. However, the introduction of safe signals (see
-<a href="#perlipc-Deferred-Signals-_0028Safe-Signals_0029">Deferred Signals
(Safe Signals)</a> above) in Perl 5.8.0 means that
-accept() might also be interrupted when the process receives a signal.
-This typically happens when one of the forked subprocesses exits and
-notifies the parent process with a CHLD signal.
-</p>
-<p>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 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.
-</p>
-<p>You should use the <strong>-T</strong> flag to enable taint checking (see
<a href="#perlsec-NAME">perlsec NAME</a>)
-even if we aren’t running setuid or setgid. This is always a good idea
-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.
-</p>
-<p>Let’s look at another TCP client. This one connects to the TCP
"time"
-service on a number of different machines and shows how far their clocks
-differ from the system on which it’s being run:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -w
- use strict;
- use Socket;
-
- 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 $paddr = sockaddr_in(0, $iaddr);
- my($host);
-
- $| = 1;
- 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 = 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);
- }
-</pre>
-<hr>
-<a name="perlipc-Unix_002dDomain-TCP-Clients-and-Servers"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlipc-Internet-TCP-Clients-and-Servers" accesskey="p"
rel="prev">perlipc Internet TCP Clients and Servers</a>, Up: <a
href="#perlipc-Sockets_003a-Client_002fServer-Communication" accesskey="u"
rel="up">perlipc Sockets: Client/Server Communication</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Unix_002dDomain-TCP-Clients-and-Servers"></a>
-<h4 class="subsection">36.6.3 Unix-Domain TCP Clients and Servers</h4>
-
-<p>That’s fine for Internet-domain clients and servers, but what about
local
-communications? While you can use the same setup, sometimes you don’t
-want to. Unix-domain sockets are local to the current host, and are often
-used internally to implement pipes. Unlike Internet domain sockets, Unix
-domain sockets can show up in the file system with an ls(1) listing.
-</p>
-<pre class="verbatim"> % ls -l /dev/log
- srw-rw-rw- 1 root 0 Oct 31 07:23 /dev/log
-</pre>
-<p>You can test for these with Perl’s <strong>-S</strong> file test:
-</p>
-<pre class="verbatim"> unless (-S "/dev/log") {
- die "something's wicked with the log system";
- }
-</pre>
-<p>Here’s a sample Unix-domain client:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -w
- use Socket;
- use strict;
- my ($rendezvous, $line);
-
- $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;
- }
- exit(0);
-</pre>
-<p>And here’s a corresponding server. You don’t have to worry
about silly
-network terminators here because Unix domain sockets are guaranteed
-to be on the localhost, and thus everything works right.
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -Tw
- use strict;
- use Socket;
- use Carp;
-
- BEGIN { $ENV{PATH} = "/usr/bin:/bin" }
- sub spawn; # forward declaration
- sub logmsg { print "$0 $$: @_ at ", scalar localtime(),
"\n" }
-
- my $NAME = "catsock";
- my $uaddr = sockaddr_un($NAME);
- my $proto = getprotobyname("tcp");
-
- socket(Server, PF_UNIX, SOCK_STREAM, 0) || die "socket: $!";
- unlink($NAME);
- bind (Server, $uaddr) || die "bind: $!";
- listen(Server, SOMAXCONN) || die "listen: $!";
-
- logmsg "server started on $NAME";
-
- my $waitedpid;
-
- 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
- }
-
- $SIG{CHLD} = \&REAPER;
-
-
- for ( $waitedpid = 0;
- 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") || die "can't exec
fortune: $!";
- };
- }
-
- sub spawn {
- 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->());
- }
-</pre>
-<p>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 the same as in the other
server.
-</p>
-<p>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
-arguments.
-</p>
-<p>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.
-</p>
-<hr>
-<a name="perlipc-TCP-Clients-with-IO_003a_003aSocket"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-TCP-Servers-with-IO_003a_003aSocket" accesskey="n"
rel="next">perlipc TCP Servers with IO::Socket</a>, Previous: <a
href="#perlipc-Sockets_003a-Client_002fServer-Communication" accesskey="p"
rel="prev">perlipc Sockets: Client/Server Communication</a>, Up: <a
href="#perlipc" accesskey="u" rel="up">perlipc</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="TCP-Clients-with-IO_003a_003aSocket"></a>
-<h3 class="section">36.7 TCP Clients with IO::Socket</h3>
-
-<p>For those preferring a higher-level interface to socket programming, the
-IO::Socket module provides an object-oriented approach. If for some reason
-you lack this module, you can just fetch IO::Socket from CPAN, where
you’ll also
-find modules providing easy interfaces to the following systems: DNS, FTP,
-Ident (RFC 931), NIS and NISPlus, NNTP, Ping, POP3, SMTP, SNMP, SSLeay,
-Telnet, and Time–to name just a few.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlipc-A-Simple-Client"
accesskey="1">perlipc A Simple Client</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlipc-A-Webget-Client"
accesskey="2">perlipc A Webget Client</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlipc-Interactive-Client-with-IO_003a_003aSocket"
accesskey="3">perlipc Interactive Client with
IO::Socket</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlipc-A-Simple-Client"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-A-Webget-Client" accesskey="n" rel="next">perlipc A
Webget Client</a>, Up: <a href="#perlipc-TCP-Clients-with-IO_003a_003aSocket"
accesskey="u" rel="up">perlipc TCP Clients with IO::Socket</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="A-Simple-Client"></a>
-<h4 class="subsection">36.7.1 A Simple Client</h4>
-
-<p>Here’s a client that creates a TCP connection to the
"daytime"
-service at port 13 of the host name "localhost" and prints out
everything
-that the server there cares to provide.
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -w
- use IO::Socket;
- $remote = IO::Socket::INET->new(
- Proto => "tcp",
- PeerAddr => "localhost",
- PeerPort => "daytime(13)",
- )
- || die "can't connect to daytime service on
localhost";
- while (<$remote>) { print }
-</pre>
-<p>When you run this program, you should get something back that
-looks like this:
-</p>
-<pre class="verbatim"> Wed May 14 08:40:46 MDT 1997
-</pre>
-<p>Here are what those parameters to the new() constructor mean:
-</p>
-<dl compact="compact">
-<dt><code>Proto</code></dt>
-<dd><a name="perlipc-Proto"></a>
-<p>This is which protocol to use. In this case, the socket handle returned
-will be connected to a TCP socket, because we want a stream-oriented
-connection, that is, one that acts pretty much like a plain old file.
-Not all sockets are this of this type. For example, the UDP protocol
-can be used to make a datagram socket, used for message-passing.
-</p>
-</dd>
-<dt><code>PeerAddr</code></dt>
-<dd><a name="perlipc-PeerAddr"></a>
-<p>This is the name or Internet address of the remote host the server is
-running on. We could have specified a longer name like
<code>"www.perl.com"</code>,
-or an address like <code>"207.171.7.72"</code>. For demonstration
purposes, we’ve
-used the special hostname <code>"localhost"</code>, which should
always mean the
-current machine you’re running on. The corresponding Internet address
-for localhost is <code>"127.0.0.1"</code>, if you’d rather use
that.
-</p>
-</dd>
-<dt><code>PeerPort</code></dt>
-<dd><a name="perlipc-PeerPort"></a>
-<p>This is the service name or port number we’d like to connect to.
-We could have gotten away with using just <code>"daytime"</code> on
systems with a
-well-configured system services file,[FOOTNOTE: The system services file
-is found in <em>/etc/services</em> 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.
-</p>
-</dd>
-</dl>
-
-<p>Notice how the return value from the <code>new</code> constructor is used as
-a filehandle in the <code>while</code> loop? That’s what’s called
an <em>indirect
-filehandle</em>, 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:
-</p>
-<pre class="verbatim"> $line = <$handle>;
-</pre>
-<p>all remaining lines from is this way:
-</p>
-<pre class="verbatim"> @lines = <$handle>;
-</pre>
-<p>and send a line of data to it this way:
-</p>
-<pre class="verbatim"> print $handle "some data\n";
-</pre>
-<hr>
-<a name="perlipc-A-Webget-Client"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-Interactive-Client-with-IO_003a_003aSocket"
accesskey="n" rel="next">perlipc Interactive Client with IO::Socket</a>,
Previous: <a href="#perlipc-A-Simple-Client" accesskey="p" rel="prev">perlipc A
Simple Client</a>, Up: <a href="#perlipc-TCP-Clients-with-IO_003a_003aSocket"
accesskey="u" rel="up">perlipc TCP Clients with IO::Socket</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="A-Webget-Client"></a>
-<h4 class="subsection">36.7.2 A Webget Client</h4>
-
-<p>Here’s a simple client that takes a remote host to fetch a document
-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.
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -w
- use IO::Socket;
- unless (@ARGV > 1) { die "usage: $0 host url ..." }
- $host = shift(@ARGV);
- $EOL = "\015\012";
- $BLANK = $EOL x 2;
- 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;
- }
-</pre>
-<p>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, <code>PeerPort => 8080</code>. The
<code>autoflush</code>
-method is used on the socket because otherwise the system would buffer
-up the output we sent it. (If you’re on a prehistoric Mac, you’ll
also
-need to change every <code>"\n"</code> in your code that sends data
over the network
-to be a <code>"\015\012"</code> instead.)
-</p>
-<p>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
-on the network has its own little command language that it expects as
-input. The string that we send to the server starting with "GET" is
in
-HTTP syntax. In this case, we simply request each specified document.
-Yes, we really are making a new connection for each document, even though
-it’s the same host. That’s the way you always used to have to
speak HTTP.
-Recent versions of web browsers may request that the remote server leave
-the connection open a little while, but the server doesn’t have to honor
-such a request.
-</p>
-<p>Here’s an example of running that program, which we’ll call
<em>webget</em>:
-</p>
-<pre class="verbatim"> % webget www.perl.com /guanaco.html
- HTTP/1.1 404 File Not Found
- Date: Thu, 08 May 1997 18:02:32 GMT
- Server: Apache/1.2b6
- Connection: close
- Content-type: text/html
-
- <HEAD><TITLE>404 File Not Found</TITLE></HEAD>
- <BODY><H1>File Not Found</H1>
- The requested URL /guanaco.html was not found on this server.<P>
- </BODY>
-</pre>
-<p>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.
-</p>
-<p>For a more featureful version of this program, you should look to
-the <em>lwp-request</em> program included with the LWP modules from CPAN.
-</p>
-<hr>
-<a name="perlipc-Interactive-Client-with-IO_003a_003aSocket"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlipc-A-Webget-Client" accesskey="p" rel="prev">perlipc
A Webget Client</a>, Up: <a href="#perlipc-TCP-Clients-with-IO_003a_003aSocket"
accesskey="u" rel="up">perlipc TCP Clients with IO::Socket</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Interactive-Client-with-IO_003a_003aSocket"></a>
-<h4 class="subsection">36.7.3 Interactive Client with IO::Socket</h4>
-
-<p>Well, that’s all fine if you want to send one command and get one
answer,
-but what about setting up something fully interactive, somewhat like
-the way <em>telnet</em> works? That way you can type a line, get the answer,
-type a line, get the answer, etc.
-</p>
-<p>This client is more complicated than the two we’ve done so far, but if
-you’re on a system that supports the powerful <code>fork</code> call,
the solution
-isn’t that rough. Once you’ve made the connection to whatever
service
-you’d like to chat with, call <code>fork</code> to clone your process.
Each of
-these two identical process has a very simple job to do: the parent
-copies everything from the socket to standard output, while the child
-simultaneously copies everything from standard input to the socket.
-To accomplish the same thing using just one process would be <em>much</em>
-harder, because it’s easier to code two processes to do one thing than it
-is to code one process to do two things. (This keep-it-simple principle
-a cornerstones of the Unix philosophy, and good software engineering as
-well, which is probably why it’s spread to other systems.)
-</p>
-<p>Here’s the code:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -w
- use strict;
- use IO::Socket;
- my ($host, $port, $kidpid, $handle, $line);
-
- unless (@ARGV == 2) { die "usage: $0 host port" }
- ($host, $port) = @ARGV;
-
- # create a tcp connection to the specified host and port
- $handle = IO::Socket::INET->new(Proto => "tcp",
- PeerAddr => $host,
- PeerPort => $port)
- || die "can't connect to port $port on $host: $!";
-
- $handle->autoflush(1); # so output gets there right away
- print STDERR "[Connected to $host:$port]\n";
-
- # split the program into two processes, identical twins
- die "can't fork: $!" unless defined($kidpid = fork());
-
- # 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
- }
- # the else{} block runs only in the child process
- else {
- # copy standard input to the socket
- while (defined ($line = <STDIN>)) {
- print $handle $line;
- }
- exit(0); # just in case
- }
-</pre>
-<p>The <code>kill</code> function in the parent’s <code>if</code> block
is there to send a
-signal to our child process, currently running in the <code>else</code> block,
-as soon as the remote server has closed its end of the connection.
-</p>
-<p>If the remote server sends data a byte at time, and you need that
-data immediately without waiting for a newline (which might not happen),
-you may wish to replace the <code>while</code> loop in the parent with the
-following:
-</p>
-<pre class="verbatim"> my $byte;
- while (sysread($handle, $byte, 1) == 1) {
- print STDOUT $byte;
- }
-</pre>
-<p>Making a system call for each byte you want to read is not very efficient
-(to put it mildly) but is the simplest to explain and works reasonably
-well.
-</p>
-<hr>
-<a name="perlipc-TCP-Servers-with-IO_003a_003aSocket"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-UDP_003a-Message-Passing" accesskey="n"
rel="next">perlipc UDP: Message Passing</a>, Previous: <a
href="#perlipc-TCP-Clients-with-IO_003a_003aSocket" accesskey="p"
rel="prev">perlipc TCP Clients with IO::Socket</a>, Up: <a href="#perlipc"
accesskey="u" rel="up">perlipc</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="TCP-Servers-with-IO_003a_003aSocket"></a>
-<h3 class="section">36.8 TCP Servers with IO::Socket</h3>
-
-<p>As always, setting up a server is little bit more involved than running a
client.
-The model is that the server creates a special kind of socket that
-does nothing but listen on a particular port for incoming connections.
-It does this by calling the <code>IO::Socket::INET->new()</code> method with
-slightly different arguments than the client did.
-</p>
-<dl compact="compact">
-<dt>Proto</dt>
-<dd><a name="perlipc-Proto-1"></a>
-<p>This is which protocol to use. Like our clients, we’ll
-still specify <code>"tcp"</code> here.
-</p>
-</dd>
-<dt>LocalPort</dt>
-<dd><a name="perlipc-LocalPort"></a>
-<p>We specify a local
-port in the <code>LocalPort</code> argument, which we didn’t do for the
client.
-This is service name or port number for which you want to be the
-server. (Under Unix, ports under 1024 are restricted to the
-superuser.) In our sample, we’ll use port 9000, but you can use
-any port that’s not currently in use on your system. If you try
-to use one already in used, you’ll get an "Address already in
use"
-message. Under Unix, the <code>netstat -a</code> command will show
-which services current have servers.
-</p>
-</dd>
-<dt>Listen</dt>
-<dd><a name="perlipc-Listen"></a>
-<p>The <code>Listen</code> parameter is set to the maximum number of
-pending connections we can accept until we turn away incoming clients.
-Think of it as a call-waiting queue for your telephone.
-The low-level Socket module has a special symbol for the system maximum, which
-is SOMAXCONN.
-</p>
-</dd>
-<dt>Reuse</dt>
-<dd><a name="perlipc-Reuse"></a>
-<p>The <code>Reuse</code> parameter is needed so that we restart our server
-manually without waiting a few minutes to allow system buffers to
-clear out.
-</p>
-</dd>
-</dl>
-
-<p>Once the generic server socket has been created using the parameters
-listed above, the server then waits for a new client to connect
-to it. The server blocks in the <code>accept</code> method, which eventually
accepts a
-bidirectional connection from the remote client. (Make sure to autoflush
-this handle to circumvent buffering.)
-</p>
-<p>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 <code>sysread</code> variant of the interactive
client above.
-</p>
-<p>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. Multitasking servers are covered in
-Chapter 16 of the Camel.
-</p>
-<p>Here’s the code. We’ll
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -w
- use IO::Socket;
- use Net::hostent; # for OOish version of gethostbyaddr
-
- $PORT = 9000; # pick something not in use
-
- $server = IO::Socket::INET->new( Proto => "tcp",
- LocalPort => $PORT,
- Listen => SOMAXCONN,
- Reuse => 1);
-
- die "can't setup server" unless $server;
- print "[Server $0 accepting clients]\n";
-
- while ($client = $server->accept()) {
- $client->autoflush(1);
- print $client "Welcome to $0; type help for command list.\n";
- $hostinfo = gethostbyaddr($client->peeraddr);
- 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`
}
- else {
- print $client "Commands: quit date who cookie motd\n";
- }
- } continue {
- print $client "Command? ";
- }
- close $client;
- }
-</pre>
-<hr>
-<a name="perlipc-UDP_003a-Message-Passing"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-SysV-IPC" accesskey="n" rel="next">perlipc SysV
IPC</a>, Previous: <a href="#perlipc-TCP-Servers-with-IO_003a_003aSocket"
accesskey="p" rel="prev">perlipc TCP Servers with IO::Socket</a>, Up: <a
href="#perlipc" accesskey="u" rel="up">perlipc</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="UDP_003a-Message-Passing"></a>
-<h3 class="section">36.9 UDP: Message Passing</h3>
-
-<p>Another kind of client-server setup is one that uses not connections, but
-messages. UDP communications involve much lower overhead but also provide
-less reliability, as there are no promises that messages will arrive at
-all, let alone in order and unmangled. Still, UDP offers some advantages
-over TCP, including being able to "broadcast" or
"multicast" to a whole
-bunch of destination hosts at once (usually on your local subnet). If you
-find yourself overly concerned about reliability and start building checks
-into your message system, then you probably should use just TCP to start
-with.
-</p>
-<p>UDP datagrams are <em>not</em> 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.
-</p>
-<p>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
-will check many of them asynchronously by simulating a multicast and then
-using select() to do a timed-out wait for I/O. To do something similar
-with TCP, you’d have to use a different socket handle for each host.
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -w
- use strict;
- use Socket;
- use Sys::Hostname;
-
- my ( $count, $hisiaddr, $hispaddr, $histime,
- $host, $iaddr, $paddr, $port, $proto,
- $rin, $rout, $rtime, $SECS_OF_70_YEARS);
-
- $SECS_OF_70_YEARS = 2_208_988_800;
-
- $iaddr = gethostbyname(hostname());
- $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();
- $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:
$!";
- }
-
- $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--;
- }
-</pre>
-<p>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.
-</p>
-<hr>
-<a name="perlipc-SysV-IPC"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-NOTES" accesskey="n" rel="next">perlipc NOTES</a>,
Previous: <a href="#perlipc-UDP_003a-Message-Passing" accesskey="p"
rel="prev">perlipc UDP: Message Passing</a>, Up: <a href="#perlipc"
accesskey="u" rel="up">perlipc</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SysV-IPC"></a>
-<h3 class="section">36.10 SysV IPC</h3>
-
-<p>While System V IPC isn’t so widely used as sockets, it still has some
-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 <code>IPC::Shareable</code> or <code>threads::shared</code>
modules for that.
-</p>
-<p>Here’s a small example showing shared memory usage.
-</p>
-<pre class="verbatim"> use IPC::SysV qw(IPC_PRIVATE IPC_RMID S_IRUSR
S_IWUSR);
-
- $size = 2000;
- $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: $!";
- print "wrote: '$message'\n";
- 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")) = "";
- print "un" unless $buff eq $message;
- print "swell\n";
-
- print "deleting shm $id\n";
- shmctl($id, IPC_RMID, 0) || die "shmctl: $!";
-</pre>
-<p>Here’s an example of a semaphore:
-</p>
-<pre class="verbatim"> use IPC::SysV qw(IPC_CREAT);
-
- $IPC_KEY = 1234;
- $id = semget($IPC_KEY, 10, 0666 | IPC_CREAT);
- defined($id) || die "semget: $!";
- print "sem id $id\n";
-</pre>
-<p>Put this code in a separate file to be run in more than one process.
-Call the file <samp>take</samp>:
-</p>
-<pre class="verbatim"> # create a semaphore
-
- $IPC_KEY = 1234;
- $id = semget($IPC_KEY, 0, 0);
- defined($id) || die "semget: $!";
-
- $semnum = 0;
- $semflag = 0;
-
- # "take" semaphore
- # wait for semaphore to be zero
- $semop = 0;
- $opstring1 = pack("s!s!s!", $semnum, $semop, $semflag);
-
- # Increment the semaphore count
- $semop = 1;
- $opstring2 = pack("s!s!s!", $semnum, $semop, $semflag);
- $opstring = $opstring1 . $opstring2;
-
- semop($id, $opstring) || die "semop: $!";
-</pre>
-<p>Put this code in a separate file to be run in more than one process.
-Call this file <samp>give</samp>:
-</p>
-<pre class="verbatim"> # "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 unless defined($id);
-
- $semnum = 0;
- $semflag = 0;
-
- # Decrement the semaphore count
- $semop = -1;
- $opstring = pack("s!s!s!", $semnum, $semop, $semflag);
-
- semop($id, $opstring) || die "semop: $!";
-</pre>
-<p>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.
-</p>
-<p>A small example demonstrating SysV message queues:
-</p>
-<pre class="verbatim"> 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 $type_sent = 1234;
-
- 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 {
- print "not okay\n";
- }
-
- msgctl($id, IPC_RMID, 0) || die "msgctl failed: $!\n";
-</pre>
-<hr>
-<a name="perlipc-NOTES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-BUGS" accesskey="n" rel="next">perlipc BUGS</a>,
Previous: <a href="#perlipc-SysV-IPC" accesskey="p" rel="prev">perlipc SysV
IPC</a>, Up: <a href="#perlipc" accesskey="u" rel="up">perlipc</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NOTES-2"></a>
-<h3 class="section">36.11 NOTES</h3>
-
-<p>Most of these routines quietly but politely return <code>undef</code> when
they
-fail instead of causing your program to die right then and there due to
-an uncaught exception. (Actually, some of the new <em>Socket</em> conversion
-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 the
<strong>-T</strong>
-taint-checking flag to the <code>#!</code> line for servers:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -Tw
- use strict;
- use sigtrap;
- use Socket;
-</pre>
-<hr>
-<a name="perlipc-BUGS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-AUTHOR" accesskey="n" rel="next">perlipc AUTHOR</a>,
Previous: <a href="#perlipc-NOTES" accesskey="p" rel="prev">perlipc NOTES</a>,
Up: <a href="#perlipc" accesskey="u" rel="up">perlipc</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="BUGS-4"></a>
-<h3 class="section">36.12 BUGS</h3>
-
-<p>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
-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.
-</p>
-<hr>
-<a name="perlipc-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlipc-SEE-ALSO" accesskey="n" rel="next">perlipc SEE
ALSO</a>, Previous: <a href="#perlipc-BUGS" accesskey="p" rel="prev">perlipc
BUGS</a>, Up: <a href="#perlipc" accesskey="u" rel="up">perlipc</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-15"></a>
-<h3 class="section">36.13 AUTHOR</h3>
-
-<p>Tom Christiansen, with occasional vestiges of Larry Wall’s original
-version and suggestions from the Perl Porters.
-</p>
-<hr>
-<a name="perlipc-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlipc-AUTHOR" accesskey="p" rel="prev">perlipc
AUTHOR</a>, Up: <a href="#perlipc" accesskey="u" rel="up">perlipc</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-16"></a>
-<h3 class="section">36.14 SEE ALSO</h3>
-
-<p>There’s a lot more to networking than this, but this should get you
-started.
-</p>
-<p>For intrepid programmers, the indispensable textbook is <em>Unix Network
-Programming, 2nd Edition, Volume 1</em> 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.
-</p>
-<p>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 <a href="#perlfunc-NAME">perlfunc NAME</a>, you should also check
out the <samp>modules</samp> file at
-your nearest CPAN site, especially
-<a
href="http://www.cpan.org/modules/00modlist.long.html#ID5_Networking_";>http://www.cpan.org/modules/00modlist.long.html#ID5_Networking_</a>.
-See <a href="perlmodlib.html#Top">(perlmodlib)</a> or best yet, the <samp>Perl
FAQ</samp> for a description
-of what CPAN is and where to get it if the previous link doesn’t work
-for you.
-</p>
-<p>Section 5 of CPAN’s <samp>modules</samp> 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.
-</p>
-<hr>
-<a name="perllexwarn"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale" accesskey="n" rel="next">perllocale</a>, Previous:
<a href="#perlipc" accesskey="p" rel="prev">perlipc</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perllexwarn-1"></a>
-<h2 class="chapter">37 perllexwarn</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perllexwarn-NAME"
accesskey="1">perllexwarn NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllexwarn-DESCRIPTION"
accesskey="2">perllexwarn DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perllexwarn-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perllexwarn-DESCRIPTION" accesskey="n" rel="next">perllexwarn
DESCRIPTION</a>, Up: <a href="#perllexwarn" accesskey="u"
rel="up">perllexwarn</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-36"></a>
-<h3 class="section">37.1 NAME</h3>
-
-<p>perllexwarn - Perl Lexical Warnings
-</p>
-<hr>
-<a name="perllexwarn-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perllexwarn-NAME" accesskey="p" rel="prev">perllexwarn
NAME</a>, Up: <a href="#perllexwarn" accesskey="u" rel="up">perllexwarn</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-36"></a>
-<h3 class="section">37.2 DESCRIPTION</h3>
-
-<p>Perl v5.6.0 introduced lexical control over the handling of warnings by
-category. The <code>warnings</code> pragma generally replaces the command
line flag
-<strong>-w</strong>. Documentation on the use of lexical warnings, once
partly found in
-this document, is now found in the <a href="warnings.html#Top">(warnings)</a>
documentation.
-</p>
-<hr>
-<a name="perllocale"></a>
-<div class="header">
-<p>
-Next: <a href="#perllol" accesskey="n" rel="next">perllol</a>, Previous: <a
href="#perllexwarn" accesskey="p" rel="prev">perllexwarn</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perllocale-1"></a>
-<h2 class="chapter">38 perllocale</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perllocale-NAME"
accesskey="1">perllocale NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllocale-DESCRIPTION"
accesskey="2">perllocale DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-WHAT-IS-A-LOCALE" accesskey="3">perllocale WHAT IS A
LOCALE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-PREPARING-TO-USE-LOCALES" accesskey="4">perllocale PREPARING
TO USE LOCALES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllocale-USING-LOCALES"
accesskey="5">perllocale USING LOCALES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-LOCALE-CATEGORIES" accesskey="6">perllocale LOCALE
CATEGORIES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllocale-SECURITY"
accesskey="7">perllocale SECURITY</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllocale-ENVIRONMENT"
accesskey="8">perllocale ENVIRONMENT</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllocale-NOTES"
accesskey="9">perllocale NOTES</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Unicode-and-UTF_002d8">perllocale Unicode and
UTF-8</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllocale-BUGS">perllocale
BUGS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-SEE-ALSO">perllocale SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-HISTORY">perllocale HISTORY</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perllocale-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-DESCRIPTION" accesskey="n" rel="next">perllocale
DESCRIPTION</a>, Up: <a href="#perllocale" accesskey="u"
rel="up">perllocale</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-37"></a>
-<h3 class="section">38.1 NAME</h3>
-
-<p>perllocale - Perl locale handling (internationalization and localization)
-</p>
-<hr>
-<a name="perllocale-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-WHAT-IS-A-LOCALE" accesskey="n"
rel="next">perllocale WHAT IS A LOCALE</a>, Previous: <a
href="#perllocale-NAME" accesskey="p" rel="prev">perllocale NAME</a>, Up: <a
href="#perllocale" accesskey="u" rel="up">perllocale</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-37"></a>
-<h3 class="section">38.2 DESCRIPTION</h3>
-
-<p>In the beginning there was ASCII, the "American Standard Code for
-Information Interchange", which works quite well for Americans with
-their English alphabet and dollar-denominated currency. But it doesn’t
-work so well even for other English speakers, who may use different
-currencies, such as the pound sterling (as the symbol for that currency
-is not in ASCII); and it’s hopelessly inadequate for many of the
-thousands of the world’s other languages.
-</p>
-<p>To address these deficiencies, the concept of locales was invented
-(formally the ISO C, XPG4, POSIX 1.c "locale system"). And
applications
-were and are being written that use the locale mechanism. The process of
-making such an application take account of its users’ preferences in
-these kinds of matters is called <strong>internationalization</strong> (often
-abbreviated as <strong>i18n</strong>); telling such an application about a
particular
-set of preferences is known as <strong>localization</strong>
(<strong>l10n</strong>).
-</p>
-<p>Perl has been extended to support the locale system. This
-is controlled per application by using one pragma, one function call,
-and several environment variables.
-</p>
-<p>Unfortunately, there are quite a few deficiencies with the design (and
-often, the implementations) of locales. Unicode was invented (see
-<a href="#perlunitut-NAME">perlunitut NAME</a> for an introduction to that) in
part to address these
-design deficiencies, and nowadays, there is a series of "UTF-8
-locales", based on Unicode. These are locales whose character set is
-Unicode, encoded in UTF-8. Starting in v5.20, Perl fully supports
-UTF-8 locales, except for sorting and string comparisons. (Use
-<a href="Unicode-Collate.html#Top">(Unicode-Collate)</a> for these.) Perl
continues to support the old
-non UTF-8 locales as well. There are currently no UTF-8 locales for
-EBCDIC platforms.
-</p>
-<p>(Unicode is also creating <code>CLDR</code>, the "Common Locale Data
Repository",
-<a href="http://cldr.unicode.org/";>http://cldr.unicode.org/</a> which includes
more types of information than
-are available in the POSIX locale system. At the time of this writing,
-there was no CPAN module that provides access to this XML-encoded data.
-However, many of its locales have the POSIX-only data extracted, and are
-available as UTF-8 locales at
-<a
href="http://unicode.org/Public/cldr/latest/";>http://unicode.org/Public/cldr/latest/</a>.)
-</p>
-<hr>
-<a name="perllocale-WHAT-IS-A-LOCALE"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-PREPARING-TO-USE-LOCALES" accesskey="n"
rel="next">perllocale PREPARING TO USE LOCALES</a>, Previous: <a
href="#perllocale-DESCRIPTION" accesskey="p" rel="prev">perllocale
DESCRIPTION</a>, Up: <a href="#perllocale" accesskey="u"
rel="up">perllocale</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="WHAT-IS-A-LOCALE"></a>
-<h3 class="section">38.3 WHAT IS A LOCALE</h3>
-
-<p>A locale is a set of data that describes various aspects of how various
-communities in the world categorize their world. These categories are
-broken down into the following types (some of which include a brief
-note here):
-</p>
-<dl compact="compact">
-<dt>Category <code>LC_NUMERIC</code>: Numeric formatting</dt>
-<dd><a name="perllocale-Category-LC_005fNUMERIC_003a-Numeric-formatting"></a>
-<p>This indicates how numbers should be formatted for human readability,
-for example the character used as the decimal point.
-</p>
-</dd>
-<dt>Category <code>LC_MONETARY</code>: Formatting of monetary amounts</dt>
-<dd><a
name="perllocale-Category-LC_005fMONETARY_003a-Formatting-of-monetary-amounts"></a>
-<p>ÃÂ
-</p>
-</dd>
-<dt>Category <code>LC_TIME</code>: Date/Time formatting</dt>
-<dd><a
name="perllocale-Category-LC_005fTIME_003a-Date_002fTime-formatting"></a>
-<p>ÃÂ
-</p>
-</dd>
-<dt>Category <code>LC_MESSAGES</code>: Error and other messages</dt>
-<dd><a
name="perllocale-Category-LC_005fMESSAGES_003a-Error-and-other-messages"></a>
-<p>This is used by Perl itself only for accessing operating system error
-messages via <a href="#perlvar-_0024ERRNO">$!</a> and <a
href="#perlvar-_0024EXTENDED_005fOS_005fERROR">$^E</a>.
-</p>
-</dd>
-<dt>Category <code>LC_COLLATE</code>: Collation</dt>
-<dd><a name="perllocale-Category-LC_005fCOLLATE_003a-Collation"></a>
-<p>This indicates the ordering of letters for comparison and sorting.
-In Latin alphabets, for example, "b", generally follows
"a".
-</p>
-</dd>
-<dt>Category <code>LC_CTYPE</code>: Character Types</dt>
-<dd><a name="perllocale-Category-LC_005fCTYPE_003a-Character-Types"></a>
-<p>This indicates, for example if a character is an uppercase letter.
-</p>
-</dd>
-<dt>Other categories</dt>
-<dd><a name="perllocale-Other-categories"></a>
-<p>Some platforms have other categories, dealing with such things as
-measurement units and paper sizes. None of these are used directly by
-Perl, but outside operations that Perl interacts with may use
-these. See <a
href="#perllocale-Not-within-the-scope-of-_0022use-locale_0022">Not within the
scope of "use locale"</a> below.
-</p>
-</dd>
-</dl>
-
-<p>More details on the categories used by Perl are given below in <a
href="#perllocale-LOCALE-CATEGORIES">LOCALE
-CATEGORIES</a>.
-</p>
-<p>Together, these categories go a long way towards being able to customize
-a single program to run in many different locations. But there are
-deficiencies, so keep reading.
-</p>
-<hr>
-<a name="perllocale-PREPARING-TO-USE-LOCALES"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-USING-LOCALES" accesskey="n" rel="next">perllocale
USING LOCALES</a>, Previous: <a href="#perllocale-WHAT-IS-A-LOCALE"
accesskey="p" rel="prev">perllocale WHAT IS A LOCALE</a>, Up: <a
href="#perllocale" accesskey="u" rel="up">perllocale</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PREPARING-TO-USE-LOCALES"></a>
-<h3 class="section">38.4 PREPARING TO USE LOCALES</h3>
-
-<p>Perl itself (outside the <a href="POSIX.html#Top">(POSIX)</a> module) will
not use locales unless
-specifically requested to (but
-again note that Perl may interact with code that does use them). Even
-if there is such a request, <strong>all</strong> of the following must be true
-for it to work properly:
-</p>
-<ul>
-<li> <strong>Your operating system must support the locale system</strong>.
If it does,
-you should find that the <code>setlocale()</code> function is a documented
part of
-its C library.
-
-</li><li> <strong>Definitions for locales that you use must be
installed</strong>. You, or
-your system administrator, must make sure that this is the case. The
-available locales, the location in which they are kept, and the manner
-in which they are installed all vary from system to system. Some systems
-provide only a few, hard-wired locales and do not allow more to be
-added. Others allow you to add "canned" locales provided by the
system
-supplier. Still others allow you or the system administrator to define
-and add arbitrary locales. (You may have to ask your supplier to
-provide canned locales that are not delivered with your operating
-system.) Read your system documentation for further illumination.
-
-</li><li> <strong>Perl must believe that the locale system is
supported</strong>. If it does,
-<code>perl -V:d_setlocale</code> will say that the value for
<code>d_setlocale</code> is
-<code>define</code>.
-
-</li></ul>
-
-<p>If you want a Perl application to process and present your data
-according to a particular locale, the application code should include
-the <code>use locale</code><!-- /@w --> pragma (see <a
href="#perllocale-The-_0022use-locale_0022-pragma">The "use locale"
pragma</a>) where
-appropriate, and <strong>at least one</strong> of the following must be true:
-</p>
-<ol>
-<li> <strong>The locale-determining environment variables (see <a
href="#perllocale-ENVIRONMENT">ENVIRONMENT</a>)
-must be correctly set up</strong> at the time the application is started,
either
-by yourself or by whomever set up your system account; or
-
-</li><li> <strong>The application must set its own locale</strong> using the
method described in
-<a href="#perllocale-The-setlocale-function">The setlocale function</a>.
-
-</li></ol>
-
-<hr>
-<a name="perllocale-USING-LOCALES"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-LOCALE-CATEGORIES" accesskey="n"
rel="next">perllocale LOCALE CATEGORIES</a>, Previous: <a
href="#perllocale-PREPARING-TO-USE-LOCALES" accesskey="p" rel="prev">perllocale
PREPARING TO USE LOCALES</a>, Up: <a href="#perllocale" accesskey="u"
rel="up">perllocale</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="USING-LOCALES"></a>
-<h3 class="section">38.5 USING LOCALES</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perllocale-The-_0022use-locale_0022-pragma" accesskey="1">perllocale The
<code>"use locale"</code> pragma</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-The-setlocale-function" accesskey="2">perllocale The
setlocale function</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllocale-Finding-locales"
accesskey="3">perllocale Finding locales</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllocale-LOCALE-PROBLEMS"
accesskey="4">perllocale LOCALE PROBLEMS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Testing-for-broken-locales" accesskey="5">perllocale Testing
for broken locales</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Temporarily-fixing-locale-problems" accesskey="6">perllocale
Temporarily fixing locale problems</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Permanently-fixing-locale-problems" accesskey="7">perllocale
Permanently fixing locale problems</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Permanently-fixing-your-system_0027s-locale-configuration"
accesskey="8">perllocale Permanently fixing your system's locale
configuration</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Fixing-system-locale-configuration" accesskey="9">perllocale
Fixing system locale configuration</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-The-localeconv-function">perllocale The localeconv
function</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-I18N_003a_003aLanginfo">perllocale
I18N::Langinfo</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perllocale-The-_0022use-locale_0022-pragma"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-The-setlocale-function" accesskey="n"
rel="next">perllocale The setlocale function</a>, Up: <a
href="#perllocale-USING-LOCALES" accesskey="u" rel="up">perllocale USING
LOCALES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-_0022use-locale_0022-pragma"></a>
-<h4 class="subsection">38.5.1 The <code>"use locale"</code>
pragma</h4>
-
-<p>By default, Perl itself (outside the <a href="POSIX.html#Top">(POSIX)</a>
module)
-ignores the current locale. The <code>use locale</code><!-- /@w -->
-pragma tells Perl to use the current locale for some operations.
-Starting in v5.16, there are optional parameters to this pragma,
-described below, which restrict which operations are affected by it.
-</p>
-<p>The current locale is set at execution time by
-<a href="#perllocale-The-setlocale-function">setlocale()</a> 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 <a
href="#perllocale-ENVIRONMENT">ENVIRONMENT</a> in
-effect at the start of the program.
-If there is no valid environment, the current locale is whatever the
-system default has been set to. On POSIX systems, it is likely, but
-not necessarily, the "C" locale. On Windows, the default is set via
the
-computer’s <code>Control <span
class="nolinebreak">Panel->Regional</span> and Language Options</code><!--
/@w --> (or its
-current equivalent).
-</p>
-<p>The operations that are affected by locale are:
-</p>
-<dl compact="compact">
-<dt><strong>Not within the scope of <code>"use
locale"</code></strong></dt>
-<dd><a name="perllocale-Not-within-the-scope-of-_0022use-locale_0022"></a>
-<p>Only certain operations originating outside Perl should be affected, as
-follows:
-</p>
-<ul>
-<li> The current locale is used when going outside of Perl with
-operations like <a href="#perlfunc-system-LIST">system()</a> or
-<a href="#perlop-qx_002fSTRING_002f">qx//</a>, if those operations are
-locale-sensitive.
-
-</li><li> Also Perl gives access to various C library functions through the
-<a href="POSIX.html#Top">(POSIX)</a> module. Some of those functions are
always affected by the
-current locale. For example, <code>POSIX::strftime()</code> uses
<code>LC_TIME</code>;
-<code>POSIX::strtod()</code> uses <code>LC_NUMERIC</code>;
<code>POSIX::strcoll()</code> and
-<code>POSIX::strxfrm()</code> use <code>LC_COLLATE</code>; and character
classification
-functions like <code>POSIX::isalnum()</code> use <code>LC_CTYPE</code>. All
such functions
-will behave according to the current underlying locale, even if that
-locale isn’t exposed to Perl space.
-
-</li><li> XS modules for all categories but <code>LC_NUMERIC</code> get the
underlying
-locale, and hence any C library functions they call will use that
-underlying locale. For more discussion, see <a
href="perlxs.html#CAVEATS">(perlxs)CAVEATS</a>.
-
-</li></ul>
-
-<p>Note that all C programs (including the perl interpreter, which is
-written in C) always have an underlying locale. That locale is the
"C"
-locale unless changed by a call to <a
href="#perllocale-The-setlocale-function">setlocale()</a>. When Perl starts
up, it changes the underlying locale to the
-one which is indicated by the <a
href="#perllocale-ENVIRONMENT">ENVIRONMENT</a>. When using the <a
href="POSIX.html#Top">(POSIX)</a>
-module or writing XS code, it is important to keep in mind that the
-underlying locale may be something other than "C", even if the
program
-hasn’t explicitly changed it.
-</p>
-<p>ÃÂ
-</p>
-</dd>
-<dt><strong>Lingering effects of <code>use locale<!-- /@w
--></code></strong></dt>
-<dd><a name="perllocale-Lingering-effects-of-use-locale"></a>
-<p>Certain Perl operations that are set-up within the scope of a
-<code>use locale</code> retain that effect even outside the scope.
-These include:
-</p>
-<ul>
-<li> The output format of a <a href="#perlfunc-write">write()</a> is
determined by an
-earlier format declaration (<a href="#perlfunc-format">perlfunc format</a>),
so whether or not the
-output is affected by locale is determined by if the <code>format()</code> is
-within the scope of a <code>use locale</code>, not whether the
<code>write()</code>
-is.
-
-</li><li> Regular expression patterns can be compiled using
-<a href="#perlop-qr_002fSTRING_002fmsixpodualn">qr//</a> with actual
-matching deferred to later. Again, it is whether or not the compilation
-was done within the scope of <code>use locale</code> that determines the match
-behavior, not if the matches are done within such a scope or not.
-
-</li></ul>
-
-<p>ÃÂ
-</p>
-</dd>
-<dt><strong>Under <code>"use locale";</code></strong></dt>
-<dd><a name="perllocale-Under-_0022use-locale_0022_003b"></a>
-<ul>
-<li> All the above operations
-
-</li><li> <strong>Format declarations</strong> (<a
href="#perlfunc-format">perlfunc format</a>) and hence any subsequent
-<code>write()</code>s use <code>LC_NUMERIC</code>.
-
-</li><li> <strong>stringification and output</strong> use
<code>LC_NUMERIC</code>.
-These include the results of
-<code>print()</code>,
-<code>printf()</code>,
-<code>say()</code>,
-and
-<code>sprintf()</code>.
-
-</li><li> <strong>The comparison operators</strong> (<code>lt</code>,
<code>le</code>, <code>cmp</code>, <code>ge</code>, and <code>gt</code>) use
-<code>LC_COLLATE</code>. <code>sort()</code> is also affected if used without
an
-explicit comparison function, because it uses <code>cmp</code> by default.
-
-<p><strong>Note:</strong> <code>eq</code> and <code>ne</code> are unaffected
by locale: they always
-perform a char-by-char comparison of their scalar operands. What’s
-more, if <code>cmp</code> finds that its operands are equal according to the
-collation sequence specified by the current locale, it goes on to
-perform a char-by-char comparison, and only returns <em>0</em> (equal) if the
-operands are char-for-char identical. If you really want to know whether
-two strings–which <code>eq</code> and <code>cmp</code> may consider
different–are equal
-as far as collation in the locale is concerned, see the discussion in
-<a href="#perllocale-Category-LC_005fCOLLATE_003a-Collation">Category
LC_COLLATE: Collation</a>.
-</p>
-</li><li> <strong>Regular expressions and case-modification functions</strong>
(<code>uc()</code>, <code>lc()</code>,
-<code>ucfirst()</code>, and <code>lcfirst()</code>) use <code>LC_CTYPE</code>
-
-</li><li> <strong>The variables <a href="#perlvar-_0024ERRNO">$!</a></strong>
(and its synonyms <code>$ERRNO</code> and
-<code>$OS_ERROR</code>) <strong>and <a
href="#perlvar-_0024EXTENDED_005fOS_005fERROR">$^E</a></strong> (and its synonym
-<code>$EXTENDED_OS_ERROR</code>) when used as strings use
<code>LC_MESSAGES</code>.
-
-</li></ul>
-
-</dd>
-</dl>
-
-<p>The default behavior is restored with the <code>no locale</code><!--
/@w --> pragma, or
-upon reaching the end of the block enclosing <code>use locale</code>.
-Note that <code>use locale</code> calls may be
-nested, and that what is in effect within an inner scope will revert to
-the outer scope’s rules at the end of the inner scope.
-</p>
-<p>The string result of any operation that uses locale
-information is tainted, as it is possible for a locale to be
-untrustworthy. See <a href="#perllocale-SECURITY">SECURITY</a>.
-</p>
-<p>Starting in Perl v5.16 in a very limited way, and more generally in
-v5.22, you can restrict which category or categories are enabled by this
-particular instance of the pragma by adding parameters to it. For
-example,
-</p>
-<pre class="verbatim"> use locale qw(:ctype :numeric);
-</pre>
-<p>enables locale awareness within its scope of only those operations
-(listed above) that are affected by <code>LC_CTYPE</code> and
<code>LC_NUMERIC</code>.
-</p>
-<p>The possible categories are: <code>:collate</code>, <code>:ctype</code>,
<code>:messages</code>,
-<code>:monetary</code>, <code>:numeric</code>, <code>:time</code>, and the
pseudo category
-<code>:characters</code> (described below).
-</p>
-<p>Thus you can say
-</p>
-<pre class="verbatim"> use locale ':messages';
-</pre>
-<p>and only <a href="#perlvar-_0024ERRNO">$!</a> and <a
href="#perlvar-_0024EXTENDED_005fOS_005fERROR">$^E</a>
-will be locale aware. Everything else is unaffected.
-</p>
-<p>Since Perl doesn’t currently do anything with the
<code>LC_MONETARY</code>
-category, specifying <code>:monetary</code> does effectively nothing. Some
-systems have other categories, such as <code>LC_PAPER_SIZE</code>, but Perl
-also doesn’t know anything about them, and there is no way to specify
-them in this pragma’s arguments.
-</p>
-<p>You can also easily say to use all categories but one, by either, for
-example,
-</p>
-<pre class="verbatim"> use locale ':!ctype';
- use locale ':not_ctype';
-</pre>
-<p>both of which mean to enable locale awarness of all categories but
-<code>LC_CTYPE</code>. Only one category argument may be specified in a
-<code>use locale</code><!-- /@w --> if it is of the negated form.
-</p>
-<p>Prior to v5.22 only one form of the pragma with arguments is available:
-</p>
-<pre class="verbatim"> use locale ':not_characters';
-</pre>
-<p>(and you have to say <code>not_</code>; you can’t use the bang
<code>!</code> form). This
-pseudo category is a shorthand for specifying both <code>:collate</code> and
-<code>:ctype</code>. Hence, in the negated form, it is nearly the same thing
as
-saying
-</p>
-<pre class="verbatim"> use locale qw(:messages :monetary :numeric :time);
-</pre>
-<p>We use the term "nearly", because <code>:not_characters</code>
also turns on
-<code>use feature <span
class="nolinebreak">'unicode_strings'</span></code><!-- /@w --> within its
scope. This form is
-less useful in v5.20 and later, and is described fully in
-<a href="#perllocale-Unicode-and-UTF_002d8">Unicode and UTF-8</a>, but
briefly, it tells Perl to not use the
-character portions of the locale definition, that is the <code>LC_CTYPE</code>
and
-<code>LC_COLLATE</code> categories. Instead it will use the native character
set
-(extended by Unicode). When using this parameter, you are responsible
-for getting the external character set translated into the
-native/Unicode one (which it already will be if it is one of the
-increasingly popular UTF-8 locales). There are convenient ways of doing
-this, as described in <a href="#perllocale-Unicode-and-UTF_002d8">Unicode and
UTF-8</a>.
-</p>
-<hr>
-<a name="perllocale-The-setlocale-function"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-Finding-locales" accesskey="n"
rel="next">perllocale Finding locales</a>, Previous: <a
href="#perllocale-The-_0022use-locale_0022-pragma" accesskey="p"
rel="prev">perllocale The <code>"use locale"</code> pragma</a>, Up:
<a href="#perllocale-USING-LOCALES" accesskey="u" rel="up">perllocale USING
LOCALES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-setlocale-function"></a>
-<h4 class="subsection">38.5.2 The setlocale function</h4>
-
-<p>You can switch locales as often as you wish at run time with the
-<code>POSIX::setlocale()</code> function:
-</p>
-<pre class="verbatim"> # Import locale-handling tool set from POSIX
module.
- # This example uses: setlocale -- the function call
- # LC_CTYPE -- explained below
- # (Showing the testing for success/failure of operations is
- # omitted in these examples to avoid distracting from the main
- # point)
-
- use POSIX qw(locale_h);
- use locale;
- my $old_locale;
-
- # query and save the old locale
- $old_locale = setlocale(LC_CTYPE);
-
- setlocale(LC_CTYPE, "fr_CA.ISO8859-1");
- # LC_CTYPE now in locale "French, Canada, codeset ISO 8859-1"
-
- setlocale(LC_CTYPE, "");
- # LC_CTYPE now reset to the default defined by the
- # LC_ALL/LC_CTYPE/LANG environment variables, or to the system
- # default. See below for documentation.
-
- # restore the old locale
- setlocale(LC_CTYPE, $old_locale);
-</pre>
-<p>This simultaneously affects all threads of the program, so it may be
-problematic to use locales in threaded applications except where there
-is a single locale applicable to all threads.
-</p>
-<p>The first argument of <code>setlocale()</code> gives the
<strong>category</strong>, the second the
-<strong>locale</strong>. The category tells in what aspect of data processing
you
-want to apply locale-specific rules. Category names are discussed in
-<a href="#perllocale-LOCALE-CATEGORIES">LOCALE CATEGORIES</a> and <a
href="#perllocale-ENVIRONMENT">ENVIRONMENT</a>. The locale is the name of a
-collection of customization information corresponding to a particular
-combination of language, country or territory, and codeset. Read on for
-hints on the naming of locales: not all systems name locales as in the
-example.
-</p>
-<p>If no second argument is provided and the category is something other
-than <code>LC_ALL</code>, the function returns a string naming the current
locale
-for the category. You can use this value as the second argument in a
-subsequent call to <code>setlocale()</code>, <strong>but</strong> on some
platforms the string
-is opaque, not something that most people would be able to decipher as
-to what locale it means.
-</p>
-<p>If no second argument is provided and the category is <code>LC_ALL</code>,
the
-result is implementation-dependent. It may be a string of
-concatenated locale names (separator also implementation-dependent)
-or a single locale name. Please consult your <a
href="http://man.he.net/man3/setlocale";>setlocale(3)</a> man page for
-details.
-</p>
-<p>If a second argument is given and it corresponds to a valid locale,
-the locale for the category is set to that value, and the function
-returns the now-current locale value. You can then use this in yet
-another call to <code>setlocale()</code>. (In some implementations, the return
-value may sometimes differ from the value you gave as the second
-argument–think of it as an alias for the value you gave.)
-</p>
-<p>As the example shows, if the second argument is an empty string, the
-category’s locale is returned to the default specified by the
-corresponding environment variables. Generally, this results in a
-return to the default that was in force when Perl started up: changes
-to the environment made by the application after startup may or may not
-be noticed, depending on your system’s C library.
-</p>
-<p>Note that when a form of <code>use locale</code> that doesn’t include
all
-categories is specified, Perl ignores the excluded categories.
-</p>
-<p>If <code>set_locale()</code> fails for some reason (for example, an attempt
to set
-to a locale unknown to the system), the locale for the category is not
-changed, and the function returns <code>undef</code>.
-</p>
-<p>For further information about the categories, consult <a
href="http://man.he.net/man3/setlocale";>setlocale(3)</a>.
-</p>
-<hr>
-<a name="perllocale-Finding-locales"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-LOCALE-PROBLEMS" accesskey="n"
rel="next">perllocale LOCALE PROBLEMS</a>, Previous: <a
href="#perllocale-The-setlocale-function" accesskey="p" rel="prev">perllocale
The setlocale function</a>, Up: <a href="#perllocale-USING-LOCALES"
accesskey="u" rel="up">perllocale USING LOCALES</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Finding-locales"></a>
-<h4 class="subsection">38.5.3 Finding locales</h4>
-
-<p>For locales available in your system, consult also <a
href="http://man.he.net/man3/setlocale";>setlocale(3)</a> to
-see whether it leads to the list of available locales (search for the
-<em>SEE ALSO</em> section). If that fails, try the following command lines:
-</p>
-<pre class="verbatim"> locale -a
-
- nlsinfo
-
- ls /usr/lib/nls/loc
-
- ls /usr/lib/locale
-
- ls /usr/lib/nls
-
- ls /usr/share/locale
-</pre>
-<p>and see whether they list something resembling these
-</p>
-<pre class="verbatim"> en_US.ISO8859-1 de_DE.ISO8859-1
ru_RU.ISO8859-5
- en_US.iso88591 de_DE.iso88591 ru_RU.iso88595
- en_US de_DE ru_RU
- en de ru
- english german russian
- english.iso88591 german.iso88591 russian.iso88595
- english.roman8 russian.koi8r
-</pre>
-<p>Sadly, even though the calling interface for <code>setlocale()</code> has
been
-standardized, names of locales and the directories where the
-configuration resides have not been. The basic form of the name is
-<em>language_territory</em><strong>.</strong><em>codeset</em>, but the latter
parts after
-<em>language</em> are not always present. The <em>language</em> and
<em>country</em>
-are usually from the standards <strong>ISO 3166</strong> and <strong>ISO
639</strong>, the
-two-letter abbreviations for the countries and the languages of the
-world, respectively. The <em>codeset</em> part often mentions some <strong>ISO
-8859</strong> character set, the Latin codesets. For example, <code>ISO
8859-1</code>
-is the so-called "Western European codeset" that can be used to
encode
-most Western European languages adequately. Again, there are several
-ways to write even the name of that one standard. Lamentably.
-</p>
-<p>Two special locales are worth particular mention: "C" and
"POSIX".
-Currently these are effectively the same locale: the difference is
-mainly that the first one is defined by the C standard, the second by
-the POSIX standard. They define the <strong>default locale</strong> in which
-every program starts in the absence of locale information in its
-environment. (The <em>default</em> default locale, if you will.) Its language
-is (American) English and its character codeset ASCII or, rarely, a
-superset thereof (such as the "DEC Multinational Character Set
-(DEC-MCS)"). <strong>Warning</strong>. The C locale delivered by some
vendors
-may not actually exactly match what the C standard calls for. So
-beware.
-</p>
-<p><strong>NOTE</strong>: Not all systems have the "POSIX" locale
(not all systems are
-POSIX-conformant), so use "C" when you need explicitly to specify
this
-default locale.
-</p>
-<hr>
-<a name="perllocale-LOCALE-PROBLEMS"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-Testing-for-broken-locales" accesskey="n"
rel="next">perllocale Testing for broken locales</a>, Previous: <a
href="#perllocale-Finding-locales" accesskey="p" rel="prev">perllocale Finding
locales</a>, Up: <a href="#perllocale-USING-LOCALES" accesskey="u"
rel="up">perllocale USING LOCALES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="LOCALE-PROBLEMS"></a>
-<h4 class="subsection">38.5.4 LOCALE PROBLEMS</h4>
-
-<p>You may encounter the following warning message at Perl startup:
-</p>
-<pre class="verbatim"> perl: warning: Setting locale failed.
- perl: warning: Please check that your locale settings:
- LC_ALL = "En_US",
- LANG = (unset)
- are supported and installed on your system.
- perl: warning: Falling back to the standard locale ("C").
-</pre>
-<p>This means that your locale settings had <code>LC_ALL</code> set to
"En_US" and
-LANG exists but has no value. Perl tried to believe you but could not.
-Instead, Perl gave up and fell back to the "C" locale, the default
locale
-that is supposed to work no matter what. (On Windows, it first tries
-falling back to the system default locale.) This usually means your
-locale settings were wrong, they mention locales your system has never
-heard of, or the locale installation in your system has problems (for
-example, some system files are broken or missing). There are quick and
-temporary fixes to these problems, as well as more thorough and lasting
-fixes.
-</p>
-<hr>
-<a name="perllocale-Testing-for-broken-locales"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-Temporarily-fixing-locale-problems" accesskey="n"
rel="next">perllocale Temporarily fixing locale problems</a>, Previous: <a
href="#perllocale-LOCALE-PROBLEMS" accesskey="p" rel="prev">perllocale LOCALE
PROBLEMS</a>, Up: <a href="#perllocale-USING-LOCALES" accesskey="u"
rel="up">perllocale USING LOCALES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Testing-for-broken-locales"></a>
-<h4 class="subsection">38.5.5 Testing for broken locales</h4>
-
-<p>If you are building Perl from source, the Perl test suite file
-<samp>lib/locale.t</samp> can be used to test the locales on your system.
-Setting the environment variable <code>PERL_DEBUG_FULL_TEST</code> to 1
-will cause it to output detailed results. For example, on Linux, you
-could say
-</p>
-<pre class="verbatim"> PERL_DEBUG_FULL_TEST=1 ./perl -T -Ilib lib/locale.t
> locale.log 2>&1
-</pre>
-<p>Besides many other tests, it will test every locale it finds on your
-system to see if they conform to the POSIX standard. If any have
-errors, it will include a summary near the end of the output of which
-locales passed all its tests, and which failed, and why.
-</p>
-<hr>
-<a name="perllocale-Temporarily-fixing-locale-problems"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-Permanently-fixing-locale-problems" accesskey="n"
rel="next">perllocale Permanently fixing locale problems</a>, Previous: <a
href="#perllocale-Testing-for-broken-locales" accesskey="p"
rel="prev">perllocale Testing for broken locales</a>, Up: <a
href="#perllocale-USING-LOCALES" accesskey="u" rel="up">perllocale USING
LOCALES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Temporarily-fixing-locale-problems"></a>
-<h4 class="subsection">38.5.6 Temporarily fixing locale problems</h4>
-
-<p>The two quickest fixes are either to render Perl silent about any
-locale inconsistencies or to run Perl under the default locale "C".
-</p>
-<p>Perl’s moaning about locale problems can be silenced by setting the
-environment variable <code>PERL_BADLANG</code> to "0" or
"".
-This method really just sweeps the problem under the carpet: you tell
-Perl to shut up even when Perl sees that something is wrong. Do not
-be surprised if later something locale-dependent misbehaves.
-</p>
-<p>Perl can be run under the "C" locale by setting the environment
-variable <code>LC_ALL</code> to "C". This method is perhaps a bit
more civilized
-than the <code>PERL_BADLANG</code> approach, but setting <code>LC_ALL</code>
(or
-other locale variables) may affect other programs as well, not just
-Perl. In particular, external programs run from within Perl will see
-these changes. If you make the new settings permanent (read on), all
-programs you run see the changes. See <a
href="#perllocale-ENVIRONMENT">ENVIRONMENT</a> for
-the full list of relevant environment variables and <a
href="#perllocale-USING-LOCALES">USING LOCALES</a>
-for their effects in Perl. Effects in other programs are
-easily deducible. For example, the variable <code>LC_COLLATE</code> may well
affect
-your <strong>sort</strong> program (or whatever the program that arranges
"records"
-alphabetically in your system is called).
-</p>
-<p>You can test out changing these variables temporarily, and if the
-new settings seem to help, put those settings into your shell startup
-files. Consult your local documentation for the exact details. For
-Bourne-like shells (<strong>sh</strong>, <strong>ksh</strong>,
<strong>bash</strong>, <strong>zsh</strong>):
-</p>
-<pre class="verbatim"> LC_ALL=en_US.ISO8859-1
- export LC_ALL
-</pre>
-<p>This assumes that we saw the locale "en_US.ISO8859-1" using the
commands
-discussed above. We decided to try that instead of the above faulty
-locale "En_US"–and in Cshish shells (<strong>csh</strong>,
<strong>tcsh</strong>)
-</p>
-<pre class="verbatim"> setenv LC_ALL en_US.ISO8859-1
-</pre>
-<p>or if you have the "env" application you can do (in any shell)
-</p>
-<pre class="verbatim"> env LC_ALL=en_US.ISO8859-1 perl ...
-</pre>
-<p>If you do not know what shell you have, consult your local
-helpdesk or the equivalent.
-</p>
-<hr>
-<a name="perllocale-Permanently-fixing-locale-problems"></a>
-<div class="header">
-<p>
-Next: <a
href="#perllocale-Permanently-fixing-your-system_0027s-locale-configuration"
accesskey="n" rel="next">perllocale Permanently fixing your system's locale
configuration</a>, Previous: <a
href="#perllocale-Temporarily-fixing-locale-problems" accesskey="p"
rel="prev">perllocale Temporarily fixing locale problems</a>, Up: <a
href="#perllocale-USING-LOCALES" accesskey="u" rel="up">perllocale USING
LOCALES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Permanently-fixing-locale-problems"></a>
-<h4 class="subsection">38.5.7 Permanently fixing locale problems</h4>
-
-<p>The slower but superior fixes are when you may be able to yourself
-fix the misconfiguration of your own environment variables. The
-mis(sing)configuration of the whole system’s locales usually requires
-the help of your friendly system administrator.
-</p>
-<p>First, see earlier in this document about <a
href="#perllocale-Finding-locales">Finding locales</a>. That tells
-how to find which locales are really supported–and more importantly,
-installed–on your system. In our example error message, environment
-variables affecting the locale are listed in the order of decreasing
-importance (and unset variables do not matter). Therefore, having
-LC_ALL set to "En_US" must have been the bad choice, as shown by the
-error message. First try fixing locale settings listed first.
-</p>
-<p>Second, if using the listed commands you see something
<strong>exactly</strong>
-(prefix matches do not count and case usually counts) like "En_US"
-without the quotes, then you should be okay because you are using a
-locale name that should be installed and available in your system.
-In this case, see <a
href="#perllocale-Permanently-fixing-your-system_0027s-locale-configuration">Permanently
fixing your system’s locale configuration</a>.
-</p>
-<hr>
-<a
name="perllocale-Permanently-fixing-your-system_0027s-locale-configuration"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-Fixing-system-locale-configuration" accesskey="n"
rel="next">perllocale Fixing system locale configuration</a>, Previous: <a
href="#perllocale-Permanently-fixing-locale-problems" accesskey="p"
rel="prev">perllocale Permanently fixing locale problems</a>, Up: <a
href="#perllocale-USING-LOCALES" accesskey="u" rel="up">perllocale USING
LOCALES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Permanently-fixing-your-system_0027s-locale-configuration"></a>
-<h4 class="subsection">38.5.8 Permanently fixing your system’s locale
configuration</h4>
-
-<p>This is when you see something like:
-</p>
-<pre class="verbatim"> perl: warning: Please check that your locale
settings:
- LC_ALL = "En_US",
- LANG = (unset)
- are supported and installed on your system.
-</pre>
-<p>but then cannot see that "En_US" listed by the above-mentioned
-commands. You may see things like "en_US.ISO8859-1", but that
isn’t
-the same. In this case, try running under a locale
-that you can list and which somehow matches what you tried. The
-rules for matching locale names are a bit vague because
-standardization is weak in this area. See again the
-<a href="#perllocale-Finding-locales">Finding locales</a> about general rules.
-</p>
-<hr>
-<a name="perllocale-Fixing-system-locale-configuration"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-The-localeconv-function" accesskey="n"
rel="next">perllocale The localeconv function</a>, Previous: <a
href="#perllocale-Permanently-fixing-your-system_0027s-locale-configuration"
accesskey="p" rel="prev">perllocale Permanently fixing your system's locale
configuration</a>, Up: <a href="#perllocale-USING-LOCALES" accesskey="u"
rel="up">perllocale USING LOCALES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Fixing-system-locale-configuration"></a>
-<h4 class="subsection">38.5.9 Fixing system locale configuration</h4>
-
-<p>Contact a system administrator (preferably your own) and report the exact
-error message you get, and ask them to read this same documentation you
-are now reading. They should be able to check whether there is something
-wrong with the locale configuration of the system. The <a
href="#perllocale-Finding-locales">Finding locales</a>
-section is unfortunately a bit vague about the exact commands and places
-because these things are not that standardized.
-</p>
-<hr>
-<a name="perllocale-The-localeconv-function"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-I18N_003a_003aLanginfo" accesskey="n"
rel="next">perllocale I18N::Langinfo</a>, Previous: <a
href="#perllocale-Fixing-system-locale-configuration" accesskey="p"
rel="prev">perllocale Fixing system locale configuration</a>, Up: <a
href="#perllocale-USING-LOCALES" accesskey="u" rel="up">perllocale USING
LOCALES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-localeconv-function"></a>
-<h4 class="subsection">38.5.10 The localeconv function</h4>
-
-<p>The <code>POSIX::localeconv()</code> function allows you to get particulars
of the
-locale-dependent numeric formatting information specified by the current
-underlying <code>LC_NUMERIC</code> and <code>LC_MONETARY</code> locales
(regardless of
-whether called from within the scope of <code>use locale<!-- /@w
--></code> or not). (If
-you just want the name of
-the current locale for a particular category, use
<code>POSIX::setlocale()</code>
-with a single parameter–see <a
href="#perllocale-The-setlocale-function">The setlocale function</a>.)
-</p>
-<pre class="verbatim"> use POSIX qw(locale_h);
-
- # Get a reference to a hash of locale-dependent info
- $locale_values = localeconv();
-
- # Output sorted list of the values
- for (sort keys %$locale_values) {
- printf "%-20s = %s\n", $_, $locale_values->{$_}
- }
-</pre>
-<p><code>localeconv()</code> takes no arguments, and returns <strong>a
reference to</strong> a hash.
-The keys of this hash are variable names for formatting, such as
-<code>decimal_point</code> and <code>thousands_sep</code>. The values are the
-corresponding, er, values. See <a
href="POSIX.html#localeconv">(POSIX)localeconv</a> for a longer
-example listing the categories an implementation might be expected to
-provide; some provide more and others fewer. You don’t need an
-explicit <code>use locale</code>, because <code>localeconv()</code> always
observes the
-current locale.
-</p>
-<p>Here’s a simple-minded example program that rewrites its command-line
-parameters as integers correctly formatted in the current locale:
-</p>
-<pre class="verbatim"> use POSIX qw(locale_h);
-
- # Get some of locale's numeric formatting parameters
- my ($thousands_sep, $grouping) =
- @{localeconv()}{'thousands_sep', 'grouping'};
-
- # Apply defaults if values are missing
- $thousands_sep = ',' unless $thousands_sep;
-
- # grouping and mon_grouping are packed lists
- # of small integers (characters) telling the
- # grouping (thousand_seps and mon_thousand_seps
- # being the group dividers) of numbers and
- # monetary quantities. The integers' meanings:
- # 255 means no more grouping, 0 means repeat
- # the previous grouping, 1-254 means use that
- # as the current grouping. Grouping goes from
- # right to left (low to high digits). In the
- # below we cheat slightly by never using anything
- # else than the first grouping (whatever that is).
- if ($grouping) {
- @grouping = unpack("C*", $grouping);
- } else {
- @grouping = (3);
- }
-
- # Format command line params for current locale
- for (@ARGV) {
- $_ = int; # Chop non-integer part
- 1 while
- s/(\d)(\d{$grouping[0]}($|$thousands_sep))/$1$thousands_sep$2/;
- print "$_";
- }
- print "\n";
-</pre>
-<p>Note that if the platform doesn’t have <code>LC_NUMERIC</code> and/or
-<code>LC_MONETARY</code> available or enabled, the corresponding elements of
the
-hash will be missing.
-</p>
-<hr>
-<a name="perllocale-I18N_003a_003aLanginfo"></a>
-<div class="header">
-<p>
-Previous: <a href="#perllocale-The-localeconv-function" accesskey="p"
rel="prev">perllocale The localeconv function</a>, Up: <a
href="#perllocale-USING-LOCALES" accesskey="u" rel="up">perllocale USING
LOCALES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="I18N_003a_003aLanginfo"></a>
-<h4 class="subsection">38.5.11 I18N::Langinfo</h4>
-
-<p>Another interface for querying locale-dependent information is the
-<code>I18N::Langinfo::langinfo()</code> function, available at least in
Unix-like
-systems and VMS.
-</p>
-<p>The following example will import the <code>langinfo()</code> function
itself and
-three constants to be used as arguments to <code>langinfo()</code>: a constant
for
-the abbreviated first day of the week (the numbering starts from
-Sunday = 1) and two more constants for the affirmative and negative
-answers for a yes/no question in the current locale.
-</p>
-<pre class="verbatim"> use I18N::Langinfo qw(langinfo ABDAY_1 YESSTR NOSTR);
-
- my ($abday_1, $yesstr, $nostr)
- = map { langinfo } qw(ABDAY_1 YESSTR NOSTR);
-
- print "$abday_1? [$yesstr/$nostr] ";
-</pre>
-<p>In other words, in the "C" (or English) locale the above will
probably
-print something like:
-</p>
-<pre class="verbatim"> Sun? [yes/no]
-</pre>
-<p>See <a href="I18N-Langinfo.html#Top">(I18N-Langinfo)</a> for more
information.
-</p>
-<hr>
-<a name="perllocale-LOCALE-CATEGORIES"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-SECURITY" accesskey="n" rel="next">perllocale
SECURITY</a>, Previous: <a href="#perllocale-USING-LOCALES" accesskey="p"
rel="prev">perllocale USING LOCALES</a>, Up: <a href="#perllocale"
accesskey="u" rel="up">perllocale</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="LOCALE-CATEGORIES"></a>
-<h3 class="section">38.6 LOCALE CATEGORIES</h3>
-
-<p>The following subsections describe basic locale categories. Beyond these,
-some combination categories allow manipulation of more than one
-basic category at a time. See <a
href="#perllocale-ENVIRONMENT">ENVIRONMENT</a> for a discussion of these.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perllocale-Category-LC_005fCOLLATE_003a-Collation-1"
accesskey="1">perllocale Category <code>LC_COLLATE</code>: Collation
1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Category-LC_005fCTYPE_003a-Character-Types-1"
accesskey="2">perllocale Category <code>LC_CTYPE</code>: Character Types
1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Category-LC_005fNUMERIC_003a-Numeric-Formatting"
accesskey="3">perllocale Category <code>LC_NUMERIC</code>: Numeric
Formatting</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Category-LC_005fMONETARY_003a-Formatting-of-monetary-amounts-1"
accesskey="4">perllocale Category <code>LC_MONETARY</code>: Formatting of
monetary amounts 1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllocale-LC_005fTIME"
accesskey="5">perllocale <code>LC_TIME</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Other-categories-1" accesskey="6">perllocale Other categories
1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perllocale-Category-LC_005fCOLLATE_003a-Collation-1"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-Category-LC_005fCTYPE_003a-Character-Types-1"
accesskey="n" rel="next">perllocale Category <code>LC_CTYPE</code>: Character
Types 1</a>, Up: <a href="#perllocale-LOCALE-CATEGORIES" accesskey="u"
rel="up">perllocale LOCALE CATEGORIES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Category-LC_005fCOLLATE_003a-Collation"></a>
-<h4 class="subsection">38.6.1 Category <code>LC_COLLATE</code>: Collation</h4>
-
-<p>In the scope of a <code>use locale</code><!-- /@w --> form that
includes collation, Perl
-looks to the <code>LC_COLLATE</code>
-environment variable to determine the application’s notions on collation
-(ordering) of characters. For example, "b" follows "a" in
Latin
-alphabets, but where do "á" and "ÃÂ¥" belong? And
while
-"color" follows "chocolate" in English, what about in
traditional Spanish?
-</p>
-<p>The following collations all make sense and you may meet any of them
-if you <code>"use locale"</code>.
-</p>
-<pre class="verbatim"> A B C D E a b c d e
- A a B b C c D d E e
- a A b B c C d D e E
- a b c d e A B C D E
-</pre>
-<p>Here is a code snippet to tell what "word"
-characters are in the current locale, in that locale’s order:
-</p>
-<pre class="verbatim"> use locale;
- print +(sort grep /\w/, map { chr } 0..255), "\n";
-</pre>
-<p>Compare this with the characters that you see and their order if you
-state explicitly that the locale should be ignored:
-</p>
-<pre class="verbatim"> no locale;
- print +(sort grep /\w/, map { chr } 0..255), "\n";
-</pre>
-<p>This machine-native collation (which is what you get unless
<code>use locale</code><!-- /@w --> has appeared earlier in the same
block) must be used for
-sorting raw binary data, whereas the locale-dependent collation of the
-first example is useful for natural text.
-</p>
-<p>As noted in <a href="#perllocale-USING-LOCALES">USING LOCALES</a>,
<code>cmp</code> compares according to the current
-collation locale when <code>use locale</code> is in effect, but falls back to a
-char-by-char comparison for strings that the locale says are equal. You
-can use <code>POSIX::strcoll()</code> if you don’t want this fall-back:
-</p>
-<pre class="verbatim"> use POSIX qw(strcoll);
- $equal_in_locale =
- !strcoll("space and case ignored",
"SpaceAndCaseIgnored");
-</pre>
-<p><code>$equal_in_locale</code> will be true if the collation locale
specifies a
-dictionary-like ordering that ignores space characters completely and
-which folds case.
-</p>
-<p>Perl currently only supports single-byte locales for
<code>LC_COLLATE</code>. This means
-that a UTF-8 locale likely will just give you machine-native ordering.
-Use <a href="Unicode-Collate.html#Top">(Unicode-Collate)</a> for the full
implementation of the Unicode
-Collation Algorithm.
-</p>
-<p>If you have a single string that you want to check for "equality in
-locale" against several others, you might think you could gain a little
-efficiency by using <code>POSIX::strxfrm()</code> in conjunction with
<code>eq</code>:
-</p>
-<pre class="verbatim"> use POSIX qw(strxfrm);
- $xfrm_string = strxfrm("Mixed-case string");
- print "locale collation ignores spaces\n"
- if $xfrm_string eq strxfrm("Mixed-casestring");
- print "locale collation ignores hyphens\n"
- if $xfrm_string eq strxfrm("Mixedcase string");
- print "locale collation ignores case\n"
- if $xfrm_string eq strxfrm("mixed-case string");
-</pre>
-<p><code>strxfrm()</code> takes a string and maps it into a transformed string
for use
-in char-by-char comparisons against other transformed strings during
-collation. "Under the hood", locale-affected Perl comparison
operators
-call <code>strxfrm()</code> for both operands, then do a char-by-char
-comparison of the transformed strings. By calling <code>strxfrm()</code>
explicitly
-and using a non locale-affected comparison, the example attempts to save
-a couple of transformations. But in fact, it doesn’t save anything: Perl
-magic (see <a href="#perlguts-Magic-Variables">perlguts Magic Variables</a>)
creates the transformed version of a
-string the first time it’s needed in a comparison, then keeps this
version around
-in case it’s needed again. An example rewritten the easy way with
-<code>cmp</code> runs just about as fast. It also copes with null characters
-embedded in strings; if you call <code>strxfrm()</code> directly, it treats
the first
-null it finds as a terminator. don’t expect the transformed strings
-it produces to be portable across systems–or even from one revision
-of your operating system to the next. In short, don’t call
<code>strxfrm()</code>
-directly: let Perl do it for you.
-</p>
-<p>Note: <code>use locale</code> isn’t shown in some of these examples
because it isn’t
-needed: <code>strcoll()</code> and <code>strxfrm()</code> are POSIX functions
-which use the standard system-supplied <code>libc</code> functions that
-always obey the current <code>LC_COLLATE</code> locale.
-</p>
-<hr>
-<a name="perllocale-Category-LC_005fCTYPE_003a-Character-Types-1"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-Category-LC_005fNUMERIC_003a-Numeric-Formatting"
accesskey="n" rel="next">perllocale Category <code>LC_NUMERIC</code>: Numeric
Formatting</a>, Previous: <a
href="#perllocale-Category-LC_005fCOLLATE_003a-Collation-1" accesskey="p"
rel="prev">perllocale Category <code>LC_COLLATE</code>: Collation 1</a>, Up: <a
href="#perllocale-LOCALE-CATEGORIES" accesskey="u" rel="up">perllocale LOCALE
CATEGORIES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Category-LC_005fCTYPE_003a-Character-Types"></a>
-<h4 class="subsection">38.6.2 Category <code>LC_CTYPE</code>: Character
Types</h4>
-
-<p>In the scope of a <code>use locale</code><!-- /@w --> form that
includes <code>LC_CTYPE</code>, Perl
-obeys the <code>LC_CTYPE</code> locale
-setting. This controls the application’s notion of which characters are
-alphabetic, numeric, punctuation, <em>etc</em>. This affects Perl’s
<code>\w</code>
-regular expression metanotation,
-which stands for alphanumeric characters–that is, alphabetic,
-numeric, and the platform’s native underscore.
-(Consult <a href="#perlre-NAME">perlre NAME</a> for more information about
-regular expressions.) Thanks to <code>LC_CTYPE</code>, depending on your
locale
-setting, characters like "æ", "ð", "ÃÂ",
and
-"ø" may be understood as <code>\w</code> characters.
-It also affects things like <code>\s</code>, <code>\D</code>, and the POSIX
character
-classes, like <code>[[:graph:]]</code>. (See <a
href="#perlrecharclass-NAME">perlrecharclass NAME</a> for more
-information on all these.)
-</p>
-<p>The <code>LC_CTYPE</code> locale also provides the map used in
transliterating
-characters between lower and uppercase. This affects the case-mapping
-functions–<code>fc()</code>, <code>lc()</code>, <code>lcfirst()</code>,
<code>uc()</code>, and <code>ucfirst()</code>;
-case-mapping
-interpolation with <code>\F</code>, <code>\l</code>, <code>\L</code>,
<code>\u</code>, or <code>\U</code> in double-quoted
-strings and <code>s///</code> substitutions; and case-independent regular
expression
-pattern matching using the <code>i</code> modifier.
-</p>
-<p>Finally, <code>LC_CTYPE</code> affects the (deprecated) POSIX
character-class test
-functions–<code>POSIX::isalpha()</code>, <code>POSIX::islower()</code>,
and so on. For
-example, if you move from the "C" locale to a 7-bit ISO 646 one,
-you may find–possibly to your surprise–that
<code>"|"</code> moves from the
-<code>POSIX::ispunct()</code> class to <code>POSIX::isalpha()</code>.
-Unfortunately, this creates big problems for regular expressions.
"|" still
-means alternation even though it matches <code>\w</code>. Starting in v5.22, a
-warning will be raised when such a locale is switched into. More
-details are given several paragraphs further down.
-</p>
-<p>Starting in v5.20, Perl supports UTF-8 locales for <code>LC_CTYPE</code>,
but
-otherwise Perl only supports single-byte locales, such as the ISO 8859
-series. This means that wide character locales, for example for Asian
-languages, are not well-supported. (If the platform has the capability
-for Perl to detect such a locale, starting in Perl v5.22,
-<a href="warnings.html#Category-Hierarchy">(warnings)Perl will warn, default
enabled</a>,
-using the <code>locale</code> warning category, whenever such a locale is
switched
-into.) The UTF-8 locale support is actually a
-superset of POSIX locales, because it is really full Unicode behavior
-as if no <code>LC_CTYPE</code> locale were in effect at all (except for
tainting;
-see <a href="#perllocale-SECURITY">SECURITY</a>). POSIX locales, even UTF-8
ones,
-are lacking certain concepts in Unicode, such as the idea that changing
-the case of a character could expand to be more than one character.
-Perl in a UTF-8 locale, will give you that expansion. Prior to v5.20,
-Perl treated a UTF-8 locale on some platforms like an ISO 8859-1 one,
-with some restrictions, and on other platforms more like the "C"
locale.
-For releases v5.16 and v5.18, <code>use locale <span
class="nolinebreak">'not_characters</span><!-- /@w --></code> could be
-used as a workaround for this (see <a
href="#perllocale-Unicode-and-UTF_002d8">Unicode and UTF-8</a>).
-</p>
-<p>Note that there are quite a few things that are unaffected by the
-current locale. Any literal character is the native character for the
-given platform. Hence ’A’ means the character at code point 65 on
ASCII
-platforms, and 193 on EBCDIC. That may or may not be an ’A’ in the
-current locale, if that locale even has an ’A’.
-Similarly, all the escape sequences for particular characters,
-<code>\n</code> for example, always mean the platform’s native one.
This means,
-for example, that <code>\N</code> in regular expressions (every character
-but new-line) works on the platform character set.
-</p>
-<p>Starting in v5.22, Perl will by default warn when switching into a
-locale that redefines any ASCII printable character (plus <code>\t</code> and
-<code>\n</code>) into a different class than expected. This is likely to
-happen on modern locales only on EBCDIC platforms, where, for example,
-a CCSID 0037 locale on a CCSID 1047 machine moves <code>"["</code>,
but it can
-happen on ASCII platforms with the ISO 646 and other
-7-bit locales that are essentially obsolete. Things may still work,
-depending on what features of Perl are used by the program. For
-example, in the example from above where <code>"|"</code> becomes a
<code>\w</code>, and
-there are no regular expressions where this matters, the program may
-still work properly. The warning lists all the characters that
-it can determine could be adversely affected.
-</p>
-<p><strong>Note:</strong> A broken or malicious <code>LC_CTYPE</code> locale
definition may result
-in clearly ineligible characters being considered to be alphanumeric by
-your application. For strict matching of (mundane) ASCII letters and
-digits–for example, in command strings–locale-aware applications
-should use <code>\w</code> with the <code>/a</code> regular expression
modifier. See <a href="#perllocale-SECURITY">SECURITY</a>.
-</p>
-<hr>
-<a name="perllocale-Category-LC_005fNUMERIC_003a-Numeric-Formatting"></a>
-<div class="header">
-<p>
-Next: <a
href="#perllocale-Category-LC_005fMONETARY_003a-Formatting-of-monetary-amounts-1"
accesskey="n" rel="next">perllocale Category <code>LC_MONETARY</code>:
Formatting of monetary amounts 1</a>, Previous: <a
href="#perllocale-Category-LC_005fCTYPE_003a-Character-Types-1" accesskey="p"
rel="prev">perllocale Category <code>LC_CTYPE</code>: Character Types 1</a>,
Up: <a href="#perllocale-LOCALE-CATEGORIES" accesskey="u" rel="up">perllocale
LOCALE CATEGORIES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Category-LC_005fNUMERIC_003a-Numeric-Formatting"></a>
-<h4 class="subsection">38.6.3 Category <code>LC_NUMERIC</code>: Numeric
Formatting</h4>
-
-<p>After a proper <code>POSIX::setlocale()</code> call, and within the scope of
-of a <code>use locale</code> form that includes numerics, Perl obeys the
-<code>LC_NUMERIC</code> locale information, which controls an
application’s idea
-of how numbers should be formatted for human readability.
-In most implementations the only effect is to
-change the character used for the decimal point–perhaps from
"." to ",".
-The functions aren’t aware of such niceties as thousands separation and
-so on. (See <a href="#perllocale-The-localeconv-function">The localeconv
function</a> if you care about these things.)
-</p>
-<pre class="verbatim"> use POSIX qw(strtod setlocale LC_NUMERIC);
- use locale;
-
- setlocale LC_NUMERIC, "";
-
- $n = 5/2; # Assign numeric 2.5 to $n
-
- $a = " $n"; # Locale-dependent conversion to string
-
- print "half five is $n\n"; # Locale-dependent output
-
- printf "half five is %g\n", $n; # Locale-dependent output
-
- print "DECIMAL POINT IS COMMA\n"
- if $n == (strtod("2,5"))[0]; # Locale-dependent conversion
-</pre>
-<p>See also <a href="I18N-Langinfo.html#Top">(I18N-Langinfo)</a> and
<code>RADIXCHAR</code>.
-</p>
-<hr>
-<a
name="perllocale-Category-LC_005fMONETARY_003a-Formatting-of-monetary-amounts-1"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-LC_005fTIME" accesskey="n" rel="next">perllocale
<code>LC_TIME</code></a>, Previous: <a
href="#perllocale-Category-LC_005fNUMERIC_003a-Numeric-Formatting"
accesskey="p" rel="prev">perllocale Category <code>LC_NUMERIC</code>: Numeric
Formatting</a>, Up: <a href="#perllocale-LOCALE-CATEGORIES" accesskey="u"
rel="up">perllocale LOCALE CATEGORIES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Category-LC_005fMONETARY_003a-Formatting-of-monetary-amounts"></a>
-<h4 class="subsection">38.6.4 Category <code>LC_MONETARY</code>: Formatting of
monetary amounts</h4>
-
-<p>The C standard defines the <code>LC_MONETARY</code> 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 essentially takes no notice of it. If you
-really want to use <code>LC_MONETARY</code>, you can query its
contents–see
-<a href="#perllocale-The-localeconv-function">The localeconv
function</a>–and use the information that it returns in your
-application’s own formatting of currency amounts. However, you may well
-find that the information, voluminous and complex though it may be, still
-does not quite meet your requirements: currency formatting is a hard nut
-to crack.
-</p>
-<p>See also <a href="I18N-Langinfo.html#Top">(I18N-Langinfo)</a> and
<code>CRNCYSTR</code>.
-</p>
-<hr>
-<a name="perllocale-LC_005fTIME"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-Other-categories-1" accesskey="n"
rel="next">perllocale Other categories 1</a>, Previous: <a
href="#perllocale-Category-LC_005fMONETARY_003a-Formatting-of-monetary-amounts-1"
accesskey="p" rel="prev">perllocale Category <code>LC_MONETARY</code>:
Formatting of monetary amounts 1</a>, Up: <a
href="#perllocale-LOCALE-CATEGORIES" accesskey="u" rel="up">perllocale LOCALE
CATEGORIES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="LC_005fTIME"></a>
-<h4 class="subsection">38.6.5 <code>LC_TIME</code></h4>
-
-<p>Output produced by <code>POSIX::strftime()</code>, which builds a formatted
-human-readable date/time string, is affected by the current
<code>LC_TIME</code>
-locale. Thus, in a French locale, the output produced by the <code>%B</code>
-format element (full month name) for the first month of the year would
-be "janvier". Here’s how to get a list of long month names in
the
-current locale:
-</p>
-<pre class="verbatim"> use POSIX qw(strftime);
- for (0..11) {
- $long_month_name[$_] =
- strftime("%B", 0, 0, 0, 1, $_, 96);
- }
-</pre>
-<p>Note: <code>use locale</code> isn’t needed in this example:
<code>strftime()</code> is a POSIX
-function which uses the standard system-supplied <code>libc</code> function
that
-always obeys the current <code>LC_TIME</code> locale.
-</p>
-<p>See also <a href="I18N-Langinfo.html#Top">(I18N-Langinfo)</a> and
<code>ABDAY_1</code>..<code>ABDAY_7</code>,
<code>DAY_1</code>..<code>DAY_7</code>,
-<code>ABMON_1</code>..<code>ABMON_12</code>, and
<code>ABMON_1</code>..<code>ABMON_12</code>.
-</p>
-<hr>
-<a name="perllocale-Other-categories-1"></a>
-<div class="header">
-<p>
-Previous: <a href="#perllocale-LC_005fTIME" accesskey="p"
rel="prev">perllocale <code>LC_TIME</code></a>, Up: <a
href="#perllocale-LOCALE-CATEGORIES" accesskey="u" rel="up">perllocale LOCALE
CATEGORIES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Other-categories"></a>
-<h4 class="subsection">38.6.6 Other categories</h4>
-
-<p>The remaining locale categories are not currently used by Perl itself.
-But again note that things Perl interacts with may use these, including
-extensions outside the standard Perl distribution, and by the
-operating system and its utilities. Note especially that the string
-value of <code>$!</code> and the error messages given by external utilities may
-be changed by <code>LC_MESSAGES</code>. If you want to have portable error
-codes, use <code>%!</code>. See <a href="Errno.html#Top">(Errno)</a>.
-</p>
-<hr>
-<a name="perllocale-SECURITY"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-ENVIRONMENT" accesskey="n" rel="next">perllocale
ENVIRONMENT</a>, Previous: <a href="#perllocale-LOCALE-CATEGORIES"
accesskey="p" rel="prev">perllocale LOCALE CATEGORIES</a>, Up: <a
href="#perllocale" accesskey="u" rel="up">perllocale</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SECURITY"></a>
-<h3 class="section">38.7 SECURITY</h3>
-
-<p>Although the main discussion of Perl security issues can be found in
-<a href="#perlsec-NAME">perlsec NAME</a>, a discussion of Perl’s locale
handling would be incomplete
-if it did not draw your attention to locale-dependent security issues.
-Locales–particularly on systems that allow unprivileged users to
-build their own locales–are untrustworthy. A malicious (or just plain
-broken) locale can make a locale-aware application give unexpected
-results. Here are a few possibilities:
-</p>
-<ul>
-<li> Regular expression checks for safe file names or mail addresses using
-<code>\w</code> may be spoofed by an <code>LC_CTYPE</code> locale that claims
that
-characters such as <code>">"</code> and
<code>"|"</code> are alphanumeric.
-
-</li><li> String interpolation with case-mapping, as in, say, <code>$dest =
-"C:\U$name.$ext"</code>, may produce dangerous results if a bogus
<code>LC_CTYPE</code>
-case-mapping table is in effect.
-
-</li><li> A sneaky <code>LC_COLLATE</code> locale could result in the names of
students with
-"D" grades appearing ahead of those with "A"s.
-
-</li><li> An application that takes the trouble to use information in
-<code>LC_MONETARY</code> may format debits as if they were credits and vice
versa
-if that locale has been subverted. Or it might make payments in US
-dollars instead of Hong Kong dollars.
-
-</li><li> The date and day names in dates formatted by <code>strftime()</code>
could be
-manipulated to advantage by a malicious user able to subvert the
-<code>LC_DATE</code> locale. ("Look–it says I wasn’t in the
building on
-Sunday.")
-
-</li></ul>
-
-<p>Such dangers are not peculiar to the locale system: any aspect of an
-application’s environment which may be modified maliciously presents
-similar challenges. Similarly, they are not specific to Perl: any
-programming language that allows you to write programs that take
-account of their environment exposes you to these issues.
-</p>
-<p>Perl cannot protect you from all possibilities shown in the
-examples–there is no substitute for your own vigilance–but, when
-<code>use locale</code> is in effect, Perl uses the tainting mechanism (see
-<a href="#perlsec-NAME">perlsec NAME</a>) to mark string results that become
locale-dependent, and
-which may be untrustworthy in consequence. Here is a summary of the
-tainting behavior of operators and functions that may be affected by
-the locale:
-</p>
-<ul>
-<li> <strong>Comparison operators</strong> (<code>lt</code>, <code>le</code>,
<code>ge</code>, <code>gt</code> and <code>cmp</code>):
-
-<p>Scalar true/false (or less/equal/greater) result is never tainted.
-</p>
-</li><li> <strong>Case-mapping interpolation</strong> (with <code>\l</code>,
<code>\L</code>, <code>\u</code>, <code>\U</code>, or <code>\F</code>)
-
-<p>The result string containing interpolated material is tainted if
-a <code>use locale</code> form that includes <code>LC_CTYPE</code> is in
effect.
-</p>
-</li><li> <strong>Matching operator</strong> (<code>m//</code>):
-
-<p>Scalar true/false result never tainted.
-</p>
-<p>All subpatterns, either delivered as a list-context result or as
<code>$1</code>
-<em>etc</em>., are tainted if a <code>use locale</code> form that includes
-<code>LC_CTYPE</code> is in effect, and the subpattern
-regular expression contains a locale-dependent construct. These
-constructs include <code>\w</code> (to match an alphanumeric character),
<code>\W</code>
-(non-alphanumeric character), <code>\b</code> and <code>\B</code>
(word-boundary and
-non-boundardy, which depend on what <code>\w</code> and <code>\W</code>
match), <code>\s</code>
-(whitespace character), <code>\S</code> (non whitespace character),
<code>\d</code> and
-<code>\D</code> (digits and non-digits), and the POSIX character classes, such
as
-<code>[:alpha:]</code> (see <a
href="#perlrecharclass-POSIX-Character-Classes">perlrecharclass POSIX Character
Classes</a>).
-</p>
-<p>Tainting is also likely if the pattern is to be matched
-case-insensitively (via <code>/i</code>). The exception is if all the code
points
-to be matched this way are above 255 and do not have folds under Unicode
-rules to below 256. Tainting is not done for these because Perl
-only uses Unicode rules for such code points, and those rules are the
-same no matter what the current locale.
-</p>
-<p>The matched-pattern variables, <code>$&</code>, <code>$`</code>
(pre-match), <code>$'</code>
-(post-match), and <code>$+</code> (last match) also are tainted.
-</p>
-</li><li> <strong>Substitution operator</strong> (<code>s///</code>):
-
-<p>Has the same behavior as the match operator. Also, the left
-operand of <code>=~</code> becomes tainted when a <code>use locale</code>
-form that includes <code>LC_CTYPE</code> is in effect, if modified as
-a result of a substitution based on a regular
-expression match involving any of the things mentioned in the previous
-item, or of case-mapping, such as <code>\l</code>,
<code>\L</code>,<code>\u</code>, <code>\U</code>, or <code>\F</code>.
-</p>
-</li><li> <strong>Output formatting functions</strong> (<code>printf()</code>
and <code>write()</code>):
-
-<p>Results are never tainted because otherwise even output from print,
-for example <code>print(1/7)</code>, should be tainted if <code>use
locale</code> is in
-effect.
-</p>
-</li><li> <strong>Case-mapping functions</strong> (<code>lc()</code>,
<code>lcfirst()</code>, <code>uc()</code>, <code>ucfirst()</code>):
-
-<p>Results are tainted if a <code>use locale</code> form that includes
<code>LC_CTYPE</code> is
-in effect.
-</p>
-</li><li> <strong>POSIX locale-dependent functions</strong>
(<code>localeconv()</code>, <code>strcoll()</code>,
-<code>strftime()</code>, <code>strxfrm()</code>):
-
-<p>Results are never tainted.
-</p>
-</li><li> <strong>POSIX character class tests</strong>
(<code>POSIX::isalnum()</code>,
-<code>POSIX::isalpha()</code>, <code>POSIX::isdigit()</code>,
<code>POSIX::isgraph()</code>,
-<code>POSIX::islower()</code>, <code>POSIX::isprint()</code>,
<code>POSIX::ispunct()</code>,
-<code>POSIX::isspace()</code>, <code>POSIX::isupper()</code>,
<code>POSIX::isxdigit()</code>):
-
-<p>True/false results are never tainted.
-</p>
-</li></ul>
-
-<p>Three examples illustrate locale-dependent tainting.
-The first program, which ignores its locale, won’t run: a value taken
-directly from the command line may not be used to name an output file
-when taint checks are enabled.
-</p>
-<pre class="verbatim"> #/usr/local/bin/perl -T
- # Run with taint checking
-
- # Command line sanity check omitted...
- $tainted_output_file = shift;
-
- open(F, ">$tainted_output_file")
- or warn "Open of $tainted_output_file failed: $!\n";
-</pre>
-<p>The program can be made to run by "laundering" the tainted value
through
-a regular expression: the second example–which still ignores locale
-information–runs, creating the file named on its command line
-if it can.
-</p>
-<pre class="verbatim"> #/usr/local/bin/perl -T
-
- $tainted_output_file = shift;
- $tainted_output_file =~ m%[\w/]+%;
- $untainted_output_file = $&;
-
- open(F, ">$untainted_output_file")
- or warn "Open of $untainted_output_file failed: $!\n";
-</pre>
-<p>Compare this with a similar but locale-aware program:
-</p>
-<pre class="verbatim"> #/usr/local/bin/perl -T
-
- $tainted_output_file = shift;
- use locale;
- $tainted_output_file =~ m%[\w/]+%;
- $localized_output_file = $&;
-
- open(F, ">$localized_output_file")
- or warn "Open of $localized_output_file failed: $!\n";
-</pre>
-<p>This third program fails to run because <code>$&</code> is tainted: it
is the result
-of a match involving <code>\w</code> while <code>use locale</code> is in
effect.
-</p>
-<hr>
-<a name="perllocale-ENVIRONMENT"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-NOTES" accesskey="n" rel="next">perllocale
NOTES</a>, Previous: <a href="#perllocale-SECURITY" accesskey="p"
rel="prev">perllocale SECURITY</a>, Up: <a href="#perllocale" accesskey="u"
rel="up">perllocale</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="ENVIRONMENT-1"></a>
-<h3 class="section">38.8 ENVIRONMENT</h3>
-
-<dl compact="compact">
-<dt>PERL_SKIP_LOCALE_INIT</dt>
-<dd><a name="perllocale-PERL_005fSKIP_005fLOCALE_005fINIT"></a>
-<p>This environment variable, available starting in Perl v5.20, if set
-(to any value), tells Perl to not use the rest of the
-environment variables to initialize with. Instead, Perl uses whatever
-the current locale settings are. This is particularly useful in
-embedded environments, see
-<a href="#perlembed-Using-embedded-Perl-with-POSIX-locales">perlembed Using
embedded Perl with POSIX locales</a>.
-</p>
-</dd>
-<dt>PERL_BADLANG</dt>
-<dd><a name="perllocale-PERL_005fBADLANG"></a>
-<p>A string that can suppress Perl’s warning about failed locale settings
-at startup. Failure can occur if the locale support in the operating
-system is lacking (broken) in some way–or if you mistyped the name of
-a locale when you set up your environment. If this environment
-variable is absent, or has a value other than "0" or "",
Perl will
-complain about locale setting failures.
-</p>
-<p><strong>NOTE</strong>: <code>PERL_BADLANG</code> only gives you a way to
hide the warning message.
-The message tells about some problem in your system’s locale support,
-and you should investigate what the problem is.
-</p>
-</dd>
-</dl>
-
-<p>The following environment variables are not specific to Perl: They are
-part of the standardized (ISO C, XPG4, POSIX 1.c) <code>setlocale()</code>
method
-for controlling an application’s opinion on data. Windows is non-POSIX,
-but Perl arranges for the following to work as described anyway.
-If the locale given by an environment variable is not valid, Perl tries
-the next lower one in priority. If none are valid, on Windows, the
-system default locale is then tried. If all else fails, the
<code>"C"</code>
-locale is used. If even that doesn’t work, something is badly broken,
-but Perl tries to forge ahead with whatever the locale settings might
-be.
-</p>
-<dl compact="compact">
-<dt><code>LC_ALL</code></dt>
-<dd><a name="perllocale-LC_005fALL"></a>
-<p><code>LC_ALL</code> is the "override-all" locale environment
variable. If
-set, it overrides all the rest of the locale environment variables.
-</p>
-</dd>
-<dt><code>LANGUAGE</code></dt>
-<dd><a name="perllocale-LANGUAGE"></a>
-<p><strong>NOTE</strong>: <code>LANGUAGE</code> is a GNU extension, it affects
you only if you
-are using the GNU libc. This is the case if you are using e.g. Linux.
-If you are using "commercial" Unixes you are most probably
<em>not</em>
-using GNU libc and you can ignore <code>LANGUAGE</code>.
-</p>
-<p>However, in the case you are using <code>LANGUAGE</code>: it affects the
-language of informational, warning, and error messages output by
-commands (in other words, it’s like <code>LC_MESSAGES</code>) but it has
higher
-priority than <code>LC_ALL</code>. Moreover, it’s not a single value but
-instead a "path" (":"-separated list) of
<em>languages</em> (not locales).
-See the GNU <code>gettext</code> library documentation for more information.
-</p>
-</dd>
-<dt><code>LC_CTYPE</code></dt>
-<dd><a name="perllocale-LC_005fCTYPE"></a>
-<p>In the absence of <code>LC_ALL</code>, <code>LC_CTYPE</code> chooses the
character type
-locale. In the absence of both <code>LC_ALL</code> and <code>LC_CTYPE</code>,
<code>LANG</code>
-chooses the character type locale.
-</p>
-</dd>
-<dt><code>LC_COLLATE</code></dt>
-<dd><a name="perllocale-LC_005fCOLLATE"></a>
-<p>In the absence of <code>LC_ALL</code>, <code>LC_COLLATE</code> chooses the
collation
-(sorting) locale. In the absence of both <code>LC_ALL</code> and
<code>LC_COLLATE</code>,
-<code>LANG</code> chooses the collation locale.
-</p>
-</dd>
-<dt><code>LC_MONETARY</code></dt>
-<dd><a name="perllocale-LC_005fMONETARY"></a>
-<p>In the absence of <code>LC_ALL</code>, <code>LC_MONETARY</code> chooses the
monetary
-formatting locale. In the absence of both <code>LC_ALL</code> and
<code>LC_MONETARY</code>,
-<code>LANG</code> chooses the monetary formatting locale.
-</p>
-</dd>
-<dt><code>LC_NUMERIC</code></dt>
-<dd><a name="perllocale-LC_005fNUMERIC"></a>
-<p>In the absence of <code>LC_ALL</code>, <code>LC_NUMERIC</code> chooses the
numeric format
-locale. In the absence of both <code>LC_ALL</code> and
<code>LC_NUMERIC</code>, <code>LANG</code>
-chooses the numeric format.
-</p>
-</dd>
-<dt><code>LC_TIME</code></dt>
-<dd><a name="perllocale-LC_005fTIME-1"></a>
-<p>In the absence of <code>LC_ALL</code>, <code>LC_TIME</code> chooses the
date and time
-formatting locale. In the absence of both <code>LC_ALL</code> and
<code>LC_TIME</code>,
-<code>LANG</code> chooses the date and time formatting locale.
-</p>
-</dd>
-<dt><code>LANG</code></dt>
-<dd><a name="perllocale-LANG"></a>
-<p><code>LANG</code> is the "catch-all" locale environment variable.
If it is set, it
-is used as the last resort after the overall <code>LC_ALL</code> and the
-category-specific <code>LC_<em>foo</em></code>.
-</p>
-</dd>
-</dl>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perllocale-Examples"
accesskey="1">perllocale Examples</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perllocale-Examples"></a>
-<div class="header">
-<p>
-Up: <a href="#perllocale-ENVIRONMENT" accesskey="u" rel="up">perllocale
ENVIRONMENT</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Examples"></a>
-<h4 class="subsection">38.8.1 Examples</h4>
-
-<p>The <code>LC_NUMERIC</code> controls the numeric output:
-</p>
-<pre class="verbatim"> use locale;
- use POSIX qw(locale_h); # Imports setlocale() and the LC_ constants.
- setlocale(LC_NUMERIC, "fr_FR") or die "Pardon";
- printf "%g\n", 1.23; # If the "fr_FR" succeeded,
probably shows 1,23.
-</pre>
-<p>and also how strings are parsed by <code>POSIX::strtod()</code> as numbers:
-</p>
-<pre class="verbatim"> use locale;
- use POSIX qw(locale_h strtod);
- setlocale(LC_NUMERIC, "de_DE") or die "Entschuldigung";
- my $x = strtod("2,34") + 5;
- print $x, "\n"; # Probably shows 7,34.
-</pre>
-<hr>
-<a name="perllocale-NOTES"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-Unicode-and-UTF_002d8" accesskey="n"
rel="next">perllocale Unicode and UTF-8</a>, Previous: <a
href="#perllocale-ENVIRONMENT" accesskey="p" rel="prev">perllocale
ENVIRONMENT</a>, Up: <a href="#perllocale" accesskey="u"
rel="up">perllocale</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NOTES-3"></a>
-<h3 class="section">38.9 NOTES</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perllocale-String-eval-and-LC_005fNUMERIC" accesskey="1">perllocale
String <code>eval</code> and
<code>LC_NUMERIC</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Backward-compatibility" accesskey="2">perllocale Backward
compatibility</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-I18N_003aCollate-obsolete" accesskey="3">perllocale
I18N:Collate obsolete</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Sort-speed-and-memory-use-impacts" accesskey="4">perllocale
Sort speed and memory use impacts</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-Freely-available-locale-definitions" accesskey="5">perllocale
Freely available locale definitions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllocale-I18n-and-l10n"
accesskey="6">perllocale I18n and l10n</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllocale-An-imperfect-standard" accesskey="7">perllocale An imperfect
standard</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perllocale-String-eval-and-LC_005fNUMERIC"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-Backward-compatibility" accesskey="n"
rel="next">perllocale Backward compatibility</a>, Up: <a
href="#perllocale-NOTES" accesskey="u" rel="up">perllocale NOTES</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="String-eval-and-LC_005fNUMERIC"></a>
-<h4 class="subsection">38.9.1 String <code>eval</code> and
<code>LC_NUMERIC</code></h4>
-
-<p>A string <a href="#perlfunc-eval-EXPR">eval</a> parses its expression as
standard
-Perl. It is therefore expecting the decimal point to be a dot. If
-<code>LC_NUMERIC</code> is set to have this be a comma instead, the parsing
will
-be confused, perhaps silently.
-</p>
-<pre class="verbatim"> use locale;
- use POSIX qw(locale_h);
- setlocale(LC_NUMERIC, "fr_FR") or die "Pardon";
- my $a = 1.2;
- print eval "$a + 1.5";
- print "\n";
-</pre>
-<p>prints <code>13,5</code>. This is because in that locale, the comma is the
-decimal point character. The <code>eval</code> thus expands to:
-</p>
-<pre class="verbatim"> eval "1,2 + 1.5"
-</pre>
-<p>and the result is not what you likely expected. No warnings are
-generated. If you do string <code>eval</code>’s within the scope of
-<code>use locale</code><!-- /@w -->, you should instead change the
<code>eval</code> line to do
-something like:
-</p>
-<pre class="verbatim"> print eval "no locale; $a + 1.5";
-</pre>
-<p>This prints <code>2.7</code>.
-</p>
-<p>You could also exclude <code>LC_NUMERIC</code>, if you don’t need it,
by
-</p>
-<pre class="verbatim"> use locale ':!numeric';
-</pre>
-<hr>
-<a name="perllocale-Backward-compatibility"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-I18N_003aCollate-obsolete" accesskey="n"
rel="next">perllocale I18N:Collate obsolete</a>, Previous: <a
href="#perllocale-String-eval-and-LC_005fNUMERIC" accesskey="p"
rel="prev">perllocale String <code>eval</code> and <code>LC_NUMERIC</code></a>,
Up: <a href="#perllocale-NOTES" accesskey="u" rel="up">perllocale NOTES</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Backward-compatibility"></a>
-<h4 class="subsection">38.9.2 Backward compatibility</h4>
-
-<p>Versions of Perl prior to 5.004 <strong>mostly</strong> ignored locale
information,
-generally behaving as if something similar to the <code>"C"</code>
locale were
-always in force, even if the program environment suggested otherwise
-(see <a href="#perllocale-The-setlocale-function">The setlocale function</a>).
By default, Perl still behaves this
-way for backward compatibility. If you want a Perl application to pay
-attention to locale information, you <strong>must</strong> use the
<code>use locale</code><!-- /@w -->
-pragma (see <a href="#perllocale-The-_0022use-locale_0022-pragma">The
"use locale" pragma</a>) or, in the unlikely event
-that you want to do so for just pattern matching, the
-<code>/l</code> regular expression modifier (see <a
href="#perlre-Character-set-modifiers">perlre Character set modifiers</a>) to
instruct it to do so.
-</p>
-<p>Versions of Perl from 5.002 to 5.003 did use the <code>LC_CTYPE</code>
-information if available; that is, <code>\w</code> did understand what
-were the letters according to the locale environment variables.
-The problem was that the user had no control over the feature:
-if the C library supported locales, Perl used them.
-</p>
-<hr>
-<a name="perllocale-I18N_003aCollate-obsolete"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-Sort-speed-and-memory-use-impacts" accesskey="n"
rel="next">perllocale Sort speed and memory use impacts</a>, Previous: <a
href="#perllocale-Backward-compatibility" accesskey="p" rel="prev">perllocale
Backward compatibility</a>, Up: <a href="#perllocale-NOTES" accesskey="u"
rel="up">perllocale NOTES</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="I18N_003aCollate-obsolete"></a>
-<h4 class="subsection">38.9.3 I18N:Collate obsolete</h4>
-
-<p>In versions of Perl prior to 5.004, per-locale collation was possible
-using the <code>I18N::Collate</code> library module. This module is now mildly
-obsolete and should be avoided in new applications. The
<code>LC_COLLATE</code>
-functionality is now integrated into the Perl core language: One can
-use locale-specific scalar data completely normally with <code>use
locale</code>,
-so there is no longer any need to juggle with the scalar references of
-<code>I18N::Collate</code>.
-</p>
-<hr>
-<a name="perllocale-Sort-speed-and-memory-use-impacts"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-Freely-available-locale-definitions" accesskey="n"
rel="next">perllocale Freely available locale definitions</a>, Previous: <a
href="#perllocale-I18N_003aCollate-obsolete" accesskey="p"
rel="prev">perllocale I18N:Collate obsolete</a>, Up: <a
href="#perllocale-NOTES" accesskey="u" rel="up">perllocale NOTES</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Sort-speed-and-memory-use-impacts"></a>
-<h4 class="subsection">38.9.4 Sort speed and memory use impacts</h4>
-
-<p>Comparing and sorting by locale is usually slower than the default
-sorting; slow-downs of two to four times have been observed. It will
-also consume more memory: once a Perl scalar variable has participated
-in any string comparison or sorting operation obeying the locale
-collation rules, it will take 3-15 times more memory than before. (The
-exact multiplier depends on the string’s contents, the operating system
-and the locale.) These downsides are dictated more by the operating
-system’s implementation of the locale system than by Perl.
-</p>
-<hr>
-<a name="perllocale-Freely-available-locale-definitions"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-I18n-and-l10n" accesskey="n" rel="next">perllocale
I18n and l10n</a>, Previous: <a
href="#perllocale-Sort-speed-and-memory-use-impacts" accesskey="p"
rel="prev">perllocale Sort speed and memory use impacts</a>, Up: <a
href="#perllocale-NOTES" accesskey="u" rel="up">perllocale NOTES</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Freely-available-locale-definitions"></a>
-<h4 class="subsection">38.9.5 Freely available locale definitions</h4>
-
-<p>The Unicode CLDR project extracts the POSIX portion of many of its
-locales, available at
-</p>
-<pre class="verbatim"> http://unicode.org/Public/cldr/latest/
-</pre>
-<p>There is a large collection of locale definitions at:
-</p>
-<pre class="verbatim"> http://std.dkuug.dk/i18n/WG15-collection/locales/
-</pre>
-<p>You should be aware that it is
-unsupported, and is not claimed to be fit for any purpose. If your
-system allows installation of arbitrary locales, you may find the
-definitions useful as they are, or as a basis for the development of
-your own locales.
-</p>
-<hr>
-<a name="perllocale-I18n-and-l10n"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-An-imperfect-standard" accesskey="n"
rel="next">perllocale An imperfect standard</a>, Previous: <a
href="#perllocale-Freely-available-locale-definitions" accesskey="p"
rel="prev">perllocale Freely available locale definitions</a>, Up: <a
href="#perllocale-NOTES" accesskey="u" rel="up">perllocale NOTES</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="I18n-and-l10n"></a>
-<h4 class="subsection">38.9.6 I18n and l10n</h4>
-
-<p>"Internationalization" is often abbreviated as
<strong>i18n</strong> because its first
-and last letters are separated by eighteen others. (You may guess why
-the internalin ... internaliti ... i18n tends to get abbreviated.) In
-the same way, "localization" is often abbreviated to
<strong>l10n</strong>.
-</p>
-<hr>
-<a name="perllocale-An-imperfect-standard"></a>
-<div class="header">
-<p>
-Previous: <a href="#perllocale-I18n-and-l10n" accesskey="p"
rel="prev">perllocale I18n and l10n</a>, Up: <a href="#perllocale-NOTES"
accesskey="u" rel="up">perllocale NOTES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="An-imperfect-standard"></a>
-<h4 class="subsection">38.9.7 An imperfect standard</h4>
-
-<p>Internationalization, as defined in the C and POSIX standards, can be
-criticized as incomplete, ungainly, and having too large a granularity.
-(Locales apply to a whole process, when it would arguably be more useful
-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.
-</p>
-<hr>
-<a name="perllocale-Unicode-and-UTF_002d8"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-BUGS" accesskey="n" rel="next">perllocale BUGS</a>,
Previous: <a href="#perllocale-NOTES" accesskey="p" rel="prev">perllocale
NOTES</a>, Up: <a href="#perllocale" accesskey="u" rel="up">perllocale</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-and-UTF_002d8"></a>
-<h3 class="section">38.10 Unicode and UTF-8</h3>
-
-<p>The support of Unicode is new starting from Perl version v5.6, and more
fully
-implemented in versions v5.8 and later. See <a
href="#perluniintro-NAME">perluniintro NAME</a>.
-</p>
-<p>Starting in Perl v5.20, UTF-8 locales are supported in Perl, except for
-<code>LC_COLLATE</code> (use <a
href="Unicode-Collate.html#Top">(Unicode-Collate)</a> instead). If you have
Perl v5.16
-or v5.18 and can’t upgrade, you can use
-</p>
-<pre class="verbatim"> use locale ':not_characters';
-</pre>
-<p>When this form of the pragma is used, only the non-character portions of
-locales are used by Perl, for example <code>LC_NUMERIC</code>. Perl assumes
that
-you have translated all the characters it is to operate on into Unicode
-(actually the platform’s native character set (ASCII or EBCDIC) plus
-Unicode). For data in files, this can conveniently be done by also
-specifying
-</p>
-<pre class="verbatim"> use open ':locale';
-</pre>
-<p>This pragma arranges for all inputs from files to be translated into
-Unicode from the current locale as specified in the environment (see
-<a href="#perllocale-ENVIRONMENT">ENVIRONMENT</a>), and all outputs to files
to be translated back
-into the locale. (See <a href="open.html#Top">(open)</a>). On a
per-filehandle basis, you can
-instead use the <a href="PerlIO-locale.html#Top">(PerlIO-locale)</a> module,
or the <a href="Encode-Locale.html#Top">(Encode-Locale)</a>
-module, both available from CPAN. The latter module also has methods to
-ease the handling of <code>ARGV</code> and environment variables, and can be
used
-on individual strings. If you know that all your locales will be
-UTF-8, as many are these days, you can use the
‘<strong>-C</strong>’
-command line switch.
-</p>
-<p>This form of the pragma allows essentially seamless handling of locales
-with Unicode. The collation order will be by Unicode code point order.
-It is strongly
-recommended that when you need to order and sort strings that you use
-the standard module <a href="Unicode-Collate.html#Top">(Unicode-Collate)</a>
which gives much better results
-in many instances than you can get with the old-style locale handling.
-</p>
-<p>All the modules and switches just described can be used in v5.20 with
-just plain <code>use locale</code>, and, should the input locales not be UTF-8,
-you’ll get the less than ideal behavior, described below, that you get
-with pre-v5.16 Perls, or when you use the locale pragma without the
-<code>:not_characters</code> parameter in v5.16 and v5.18. If you are using
-exclusively UTF-8 locales in v5.20 and higher, the rest of this section
-does not apply to you.
-</p>
-<p>There are two cases, multi-byte and single-byte locales. First
-multi-byte:
-</p>
-<p>The only multi-byte (or wide character) locale that Perl is ever likely
-to support is UTF-8. This is due to the difficulty of implementation,
-the fact that high quality UTF-8 locales are now published for every
-area of the world (<a
href="http://unicode.org/Public/cldr/latest/";>http://unicode.org/Public/cldr/latest/</a>),
and that
-failing all that you can use the <a href="Encode.html#Top">(Encode)</a> module
to translate to/from
-your locale. So, you’ll have to do one of those things if you’re
using
-one of these locales, such as Big5 or Shift JIS. For UTF-8 locales, in
-Perls (pre v5.20) that don’t have full UTF-8 locale support, they may
-work reasonably well (depending on your C library implementation)
-simply because both
-they and Perl store characters that take up multiple bytes the same way.
-However, some, if not most, C library implementations may not process
-the characters in the upper half of the Latin-1 range (128 - 255)
-properly under <code>LC_CTYPE</code>. To see if a character is a particular
type
-under a locale, Perl uses the functions like <code>isalnum()</code>. Your C
-library may not work for UTF-8 locales with those functions, instead
-only working under the newer wide library functions like
<code>iswalnum()</code>,
-which Perl does not use.
-These multi-byte locales are treated like single-byte locales, and will
-have the restrictions described below. Starting in Perl v5.22 a warning
-message is raised when Perl detects a multi-byte locale that it doesn’t
-fully support.
-</p>
-<p>For single-byte locales,
-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
-isn’t uniformly applied, see the note at the end of this section). This
-prevents many problems in locales that aren’t UTF-8. Suppose the locale
-is ISO8859-7, Greek. The character at 0xD7 there is a capital Chi. But
-in the ISO8859-1 locale, Latin1, it is a multiplication sign. The POSIX
-regular expression character class <code>[[:alpha:]]</code> will magically
match
-0xD7 in the Greek locale but not in the Latin one.
-</p>
-<p>However, there are places where this breaks down. Certain Perl constructs
are
-for Unicode only, such as <code>\p{Alpha}</code>. 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, <code>\p{Alpha}</code> will never match it, regardless of locale. A
similar
-issue occurs with <code>\N{...}</code>. Prior to v5.20, It is therefore a bad
-idea to use <code>\p{}</code> or
-<code>\N{}</code> under plain <code>use locale</code>–<em>unless</em>
you can guarantee that the
-locale will be ISO8859-1. Use POSIX character classes instead.
-</p>
-<p>Another problem with this approach is that operations that cross the
-single byte/multiple byte boundary are not well-defined, and so are
-disallowed. (This boundary is between the codepoints at 255/256.)
-For example, lower casing LATIN CAPITAL LETTER Y WITH DIAERESIS (U+0178)
-should return LATIN SMALL LETTER Y WITH DIAERESIS (U+00FF). But in the
-Greek locale, for example, there is no character at 0xFF, and Perl
-has no way of knowing what the character at 0xFF is really supposed to
-represent. Thus it disallows the operation. In this mode, the
-lowercase of U+0178 is itself.
-</p>
-<p>The same problems ensue if you enable automatic UTF-8-ification of your
-standard file handles, default <code>open()</code> layer, and
<code>@ARGV</code> on non-ISO8859-1,
-non-UTF-8 locales (by using either the <strong>-C</strong> command line switch
or the
-<code>PERL_UNICODE</code> environment variable; see <a
href="#perlrun-NAME">perlrun NAME</a>).
-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. This is not a problem
-<em>provided</em> you make certain that all locales will always and only be
either
-an ISO8859-1, or, if you don’t have a deficient C library, a UTF-8
locale.
-</p>
-<p>Still another problem is that this approach can lead to two code
-points meaning the same character. Thus in a Greek locale, both U+03A7
-and U+00D7 are GREEK CAPITAL LETTER CHI.
-</p>
-<p>Because of all these problems, starting in v5.22, Perl will raise a
-warning if a multi-byte (hence Unicode) code point is used when a
-single-byte locale is in effect. (Although it doesn’t check for this if
-doing so would unreasonably slow execution down.)
-</p>
-<p>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. (However, the Unicode-supplied locales should be better, and
-there is a feed back mechanism to correct any problems. See
-<a href="#perllocale-Freely-available-locale-definitions">Freely available
locale definitions</a>.)
-</p>
-<p>If you have Perl v5.16, the problems mentioned above go away if you use
-the <code>:not_characters</code> parameter to the locale pragma (except for
vendor
-bugs in the non-character portions). If you don’t have v5.16, and you
-<em>do</em> have locales that work, using them may be worthwhile for certain
-specific purposes, as long as you keep in mind the gotchas already
-mentioned. For example, if the collation for your locales works, it
-runs faster under locales than under <a
href="Unicode-Collate.html#Top">(Unicode-Collate)</a>; and you gain
-access to such things as the local currency symbol and the names of the
-months and days of the week. (But to hammer home the point, in v5.16,
-you get this access without the downsides of locales by using the
-<code>:not_characters</code> form of the pragma.)
-</p>
-<p>Note: The policy of using locale rules for code points that can fit in a
-byte, and Unicode rules for those that can’t is not uniformly applied.
-Pre-v5.12, it was somewhat haphazard; in v5.12 it was applied fairly
-consistently to regular expression matching except for bracketed
-character classes; in v5.14 it was extended to all regex matches; and in
-v5.16 to the casing operations such as <code>\L</code> and <code>uc()</code>.
For
-collation, in all releases so far, the system’s <code>strxfrm()</code>
function is
-called, and whatever it does is what you get.
-</p>
-<hr>
-<a name="perllocale-BUGS"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-SEE-ALSO" accesskey="n" rel="next">perllocale SEE
ALSO</a>, Previous: <a href="#perllocale-Unicode-and-UTF_002d8" accesskey="p"
rel="prev">perllocale Unicode and UTF-8</a>, Up: <a href="#perllocale"
accesskey="u" rel="up">perllocale</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="BUGS-5"></a>
-<h3 class="section">38.11 BUGS</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perllocale-Broken-systems"
accesskey="1">perllocale Broken systems</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perllocale-Broken-systems"></a>
-<div class="header">
-<p>
-Up: <a href="#perllocale-BUGS" accesskey="u" rel="up">perllocale BUGS</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Broken-systems"></a>
-<h4 class="subsection">38.11.1 Broken systems</h4>
-
-<p>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
-<code>use locale</code> is in effect. When confronted with such a system,
-please report in excruciating detail to <<samp>address@hidden</samp>>,
and
-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. If you have the source for Perl, include in
-the perlbug email the output of the test described above in <a
href="#perllocale-Testing-for-broken-locales">Testing
-for broken locales</a>.
-</p>
-<hr>
-<a name="perllocale-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perllocale-HISTORY" accesskey="n" rel="next">perllocale
HISTORY</a>, Previous: <a href="#perllocale-BUGS" accesskey="p"
rel="prev">perllocale BUGS</a>, Up: <a href="#perllocale" accesskey="u"
rel="up">perllocale</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-17"></a>
-<h3 class="section">38.12 SEE ALSO</h3>
-
-<p><a href="I18N-Langinfo.html#Top">(I18N-Langinfo)</a>, <a
href="#perluniintro-NAME">perluniintro NAME</a>, <a
href="#perlunicode-NAME">perlunicode NAME</a>, <a
href="open.html#Top">(open)</a>,
-<a href="POSIX.html#isalnum">(POSIX)isalnum</a>, <a
href="POSIX.html#isalpha">(POSIX)isalpha</a>,
-<a href="POSIX.html#isdigit">(POSIX)isdigit</a>, <a
href="POSIX.html#isgraph">(POSIX)isgraph</a>, <a
href="POSIX.html#islower">(POSIX)islower</a>,
-<a href="POSIX.html#isprint">(POSIX)isprint</a>, <a
href="POSIX.html#ispunct">(POSIX)ispunct</a>, <a
href="POSIX.html#isspace">(POSIX)isspace</a>,
-<a href="POSIX.html#isupper">(POSIX)isupper</a>, <a
href="POSIX.html#isxdigit">(POSIX)isxdigit</a>, <a
href="POSIX.html#localeconv">(POSIX)localeconv</a>,
-<a href="POSIX.html#setlocale">(POSIX)setlocale</a>, <a
href="POSIX.html#strcoll">(POSIX)strcoll</a>, <a
href="POSIX.html#strftime">(POSIX)strftime</a>,
-<a href="POSIX.html#strtod">(POSIX)strtod</a>, <a
href="POSIX.html#strxfrm">(POSIX)strxfrm</a>.
-</p>
-<p>For special considerations when Perl is embedded in a C program,
-see <a href="#perlembed-Using-embedded-Perl-with-POSIX-locales">perlembed
Using embedded Perl with POSIX locales</a>.
-</p>
-<hr>
-<a name="perllocale-HISTORY"></a>
-<div class="header">
-<p>
-Previous: <a href="#perllocale-SEE-ALSO" accesskey="p" rel="prev">perllocale
SEE ALSO</a>, Up: <a href="#perllocale" accesskey="u" rel="up">perllocale</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="HISTORY-2"></a>
-<h3 class="section">38.13 HISTORY</h3>
-
-<p>Jarkko Hietaniemi’s original <samp>perli18n.pod</samp> heavily hacked
by Dominic
-Dunlop, assisted by the perl5-porters. Prose worked over a bit by
-Tom Christiansen, and updated by Perl 5 porters.
-</p>
-<hr>
-<a name="perllol"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmod" accesskey="n" rel="next">perlmod</a>, Previous: <a
href="#perllocale" accesskey="p" rel="prev">perllocale</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perllol-1"></a>
-<h2 class="chapter">39 perllol</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perllol-NAME"
accesskey="1">perllol NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllol-DESCRIPTION"
accesskey="2">perllol DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllol-SEE-ALSO"
accesskey="3">perllol SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllol-AUTHOR"
accesskey="4">perllol AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perllol-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perllol-DESCRIPTION" accesskey="n" rel="next">perllol
DESCRIPTION</a>, Up: <a href="#perllol" accesskey="u" rel="up">perllol</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-38"></a>
-<h3 class="section">39.1 NAME</h3>
-
-<p>perllol - Manipulating Arrays of Arrays in Perl
-</p>
-<hr>
-<a name="perllol-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perllol-SEE-ALSO" accesskey="n" rel="next">perllol SEE
ALSO</a>, Previous: <a href="#perllol-NAME" accesskey="p" rel="prev">perllol
NAME</a>, Up: <a href="#perllol" accesskey="u" rel="up">perllol</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-38"></a>
-<h3 class="section">39.2 DESCRIPTION</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perllol-Declaration-and-Access-of-Arrays-of-Arrays"
accesskey="1">perllol Declaration and Access of Arrays of
Arrays</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllol-Growing-Your-Own"
accesskey="2">perllol Growing Your Own</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perllol-Access-and-Printing" accesskey="3">perllol Access and
Printing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perllol-Slices"
accesskey="4">perllol Slices</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perllol-Declaration-and-Access-of-Arrays-of-Arrays"></a>
-<div class="header">
-<p>
-Next: <a href="#perllol-Growing-Your-Own" accesskey="n" rel="next">perllol
Growing Your Own</a>, Up: <a href="#perllol-DESCRIPTION" accesskey="u"
rel="up">perllol DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Declaration-and-Access-of-Arrays-of-Arrays"></a>
-<h4 class="subsection">39.2.1 Declaration and Access of Arrays of Arrays</h4>
-
-<p>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.
-</p>
-<p>An array of an array is just a regular old array @AoA that you can
-get at with two subscripts, like <code>$AoA[3][2]</code>. Here’s a
declaration
-of the array:
-</p>
-<pre class="verbatim"> use 5.010; # so we can use say()
-
- # assign to our array, an array of array references
- @AoA = (
- [ "fred", "barney", "pebbles",
"bambam", "dino", ],
- [ "george", "jane", "elroy",
"judy", ],
- [ "homer", "bart", "marge",
"maggie", ],
- );
- say $AoA[2][1];
- bart
-</pre>
-<p>Now you should be very careful that the outer bracket type
-is a round one, that is, a parenthesis. That’s because you’re
assigning to
-an @array, so you need parentheses. If you wanted there <em>not</em> to be an
@AoA,
-but rather just a reference to it, you could do something more like this:
-</p>
-<pre class="verbatim"> # assign a reference to array of array references
- $ref_to_AoA = [
- [ "fred", "barney", "pebbles",
"bambam", "dino", ],
- [ "george", "jane", "elroy",
"judy", ],
- [ "homer", "bart", "marge",
"maggie", ],
- ];
- say $ref_to_AoA->[2][1];
- bart
-</pre>
-<p>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
-interchange arrays and references thereto. $ref_to_AoA is a reference to an
-array, whereas @AoA is an array proper. Likewise, <code>$AoA[2]</code> is not
an
-array, but an array ref. So how come you can write these:
-</p>
-<pre class="verbatim"> $AoA[2][2]
- $ref_to_AoA->[2][2]
-</pre>
-<p>instead of having to write these:
-</p>
-<pre class="verbatim"> $AoA[2]->[2]
- $ref_to_AoA->[2]->[2]
-</pre>
-<p>Well, that’s because the rule is that on adjacent brackets only
(whether
-square or curly), you are free to omit the pointer dereferencing arrow.
-But you cannot do so for the very first one if it’s a scalar containing
-a reference, which means that $ref_to_AoA always needs it.
-</p>
-<hr>
-<a name="perllol-Growing-Your-Own"></a>
-<div class="header">
-<p>
-Next: <a href="#perllol-Access-and-Printing" accesskey="n" rel="next">perllol
Access and Printing</a>, Previous: <a
href="#perllol-Declaration-and-Access-of-Arrays-of-Arrays" accesskey="p"
rel="prev">perllol Declaration and Access of Arrays of Arrays</a>, Up: <a
href="#perllol-DESCRIPTION" accesskey="u" rel="up">perllol DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Growing-Your-Own"></a>
-<h4 class="subsection">39.2.2 Growing Your Own</h4>
-
-<p>That’s all well and good for declaration of a fixed data structure,
-but what if you wanted to add new elements on the fly, or build
-it up entirely from scratch?
-</p>
-<p>First, let’s look at reading it in from a file. This is something
like
-adding a row at a time. We’ll assume that there’s a flat file in
which
-each line is a row and each word an element. If you’re trying to
develop an
address@hidden array containing all these, here’s the right way to do
that:
-</p>
-<pre class="verbatim"> while (<>) {
- @tmp = split;
- push @AoA, [ @tmp ];
- }
-</pre>
-<p>You might also have loaded that from a function:
-</p>
-<pre class="verbatim"> for $i ( 1 .. 10 ) {
- $AoA[$i] = [ somefunc($i) ];
- }
-</pre>
-<p>Or you might have had a temporary variable sitting around with the
-array in it.
-</p>
-<pre class="verbatim"> for $i ( 1 .. 10 ) {
- @tmp = somefunc($i);
- $AoA[$i] = [ @tmp ];
- }
-</pre>
-<p>It’s important you make sure to use the <code>[ ]</code> array
reference
-constructor. That’s because this wouldn’t work:
-</p>
-<pre class="verbatim"> $AoA[$i] = @tmp; # WRONG!
-</pre>
-<p>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.
-</p>
-<p>If you are running under <code>use strict</code> (and if you aren’t,
why in
-the world aren’t you?), you’ll have to add some declarations to
-make it happy:
-</p>
-<pre class="verbatim"> use strict;
- my(@AoA, @tmp);
- while (<>) {
- @tmp = split;
- push @AoA, [ @tmp ];
- }
-</pre>
-<p>Of course, you don’t need the temporary array to have a name at all:
-</p>
-<pre class="verbatim"> while (<>) {
- push @AoA, [ split ];
- }
-</pre>
-<p>You also don’t have to use push(). You could just make a direct
assignment
-if you knew where you wanted to put it:
-</p>
-<pre class="verbatim"> my (@AoA, $i, $line);
- for $i ( 0 .. 10 ) {
- $line = <>;
- $AoA[$i] = [ split " ", $line ];
- }
-</pre>
-<p>or even just
-</p>
-<pre class="verbatim"> my (@AoA, $i);
- for $i ( 0 .. 10 ) {
- $AoA[$i] = [ split " ", <> ];
- }
-</pre>
-<p>You should in general be leery of using functions that could
-potentially return lists in scalar context without explicitly stating
-such. This would be clearer to the casual reader:
-</p>
-<pre class="verbatim"> my (@AoA, $i);
- for $i ( 0 .. 10 ) {
- $AoA[$i] = [ split " ", scalar(<>) ];
- }
-</pre>
-<p>If you wanted to have a $ref_to_AoA variable as a reference to an array,
-you’d have to do something like this:
-</p>
-<pre class="verbatim"> while (<>) {
- push @$ref_to_AoA, [ split ];
- }
-</pre>
-<p>Now you can add new rows. What about adding new columns? If you’re
-dealing with just matrices, it’s often easiest to use simple assignment:
-</p>
-<pre class="verbatim"> for $x (1 .. 10) {
- for $y (1 .. 10) {
- $AoA[$x][$y] = func($x, $y);
- }
- }
-
- for $x ( 3, 7, 9 ) {
- $AoA[$x][20] += func2($x);
- }
-</pre>
-<p>It doesn’t matter whether those elements are already
-there or not: it’ll gladly create them for you, setting
-intervening elements to <code>undef</code> as need be.
-</p>
-<p>If you wanted just to append to a row, you’d have
-to do something a bit funnier looking:
-</p>
-<pre class="verbatim"> # add new columns to an existing row
- push @{ $AoA[0] }, "wilma", "betty"; # explicit deref
-</pre>
-<p>Prior to Perl 5.14, this wouldn’t even compile:
-</p>
-<pre class="verbatim"> push $AoA[0], "wilma", "betty";
# implicit deref
-</pre>
-<p>How come? Because once upon a time, the argument to push() had to be a
-real array, not just a reference to one. That’s no longer true. In fact,
-the line marked "implicit deref" above works just fine–in this
-instance–to do what the one that says explicit deref did.
-</p>
-<p>The reason I said "in this instance" is because that
<em>only</em> works
-because <code>$AoA[0]</code> 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 <code>@{
}</code>
-always will:
-</p>
-<pre class="verbatim"> my $aref = undef;
- push $aref, qw(some more values); # WRONG!
- push @$aref, qw(a few more); # ok
-</pre>
-<p>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
-</p>
-<pre class="verbatim"> use v5.14; # needed for implicit deref of array
refs by array ops
-</pre>
-<p>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
-</p>
-<pre class="verbatim"> 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.
-</pre>
-<p>they’ll be politely informed that
-</p>
-<pre class="verbatim"> 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.
-</pre>
-<hr>
-<a name="perllol-Access-and-Printing"></a>
-<div class="header">
-<p>
-Next: <a href="#perllol-Slices" accesskey="n" rel="next">perllol Slices</a>,
Previous: <a href="#perllol-Growing-Your-Own" accesskey="p" rel="prev">perllol
Growing Your Own</a>, Up: <a href="#perllol-DESCRIPTION" accesskey="u"
rel="up">perllol DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Access-and-Printing"></a>
-<h4 class="subsection">39.2.3 Access and Printing</h4>
-
-<p>Now it’s time to print your data structure out. How
-are you going to do that? Well, if you want only one
-of the elements, it’s trivial:
-</p>
-<pre class="verbatim"> print $AoA[0][0];
-</pre>
-<p>If you want to print the whole thing, though, you can’t
-say
-</p>
-<pre class="verbatim"> print @AoA; # WRONG
-</pre>
-<p>because you’ll get just references listed, and perl will never
-automatically dereference things for you. Instead, you have to
-roll yourself a loop or two. This prints the whole structure,
-using the shell-style for() construct to loop across the outer
-set of subscripts.
-</p>
-<pre class="verbatim"> for $aref ( @AoA ) {
- say "\t [ @$aref ],";
- }
-</pre>
-<p>If you wanted to keep track of subscripts, you might do this:
-</p>
-<pre class="verbatim"> for $i ( 0 .. $#AoA ) {
- say "\t elt $i is [ @{$AoA[$i]} ],";
- }
-</pre>
-<p>or maybe even this. Notice the inner loop.
-</p>
-<pre class="verbatim"> for $i ( 0 .. $#AoA ) {
- for $j ( 0 .. $#{$AoA[$i]} ) {
- say "elt $i $j is $AoA[$i][$j]";
- }
- }
-</pre>
-<p>As you can see, it’s getting a bit complicated. That’s why
-sometimes is easier to take a temporary on your way through:
-</p>
-<pre class="verbatim"> for $i ( 0 .. $#AoA ) {
- $aref = $AoA[$i];
- for $j ( 0 .. $#{$aref} ) {
- say "elt $i $j is $AoA[$i][$j]";
- }
- }
-</pre>
-<p>Hmm... that’s still a bit ugly. How about this:
-</p>
-<pre class="verbatim"> for $i ( 0 .. $#AoA ) {
- $aref = $AoA[$i];
- $n = @$aref - 1;
- for $j ( 0 .. $n ) {
- say "elt $i $j is $AoA[$i][$j]";
- }
- }
-</pre>
-<p>When you get tired of writing a custom print for your data structures,
-you might look at the standard <a href="Dumpvalue.html#Top">(Dumpvalue)</a> or
<a href="Data-Dumper.html#Top">(Data-Dumper)</a> modules.
-The former is what the Perl debugger uses, while the latter generates
-parsable Perl code. For example:
-</p>
-<pre class="verbatim"> 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;
-</pre>
-<p>will print out:
-</p>
-<pre class="verbatim"> 0 0..3 "fred" "barney"
"wilma" "betty"
- 1 0..2 "george" "jane" "elroy"
- 2 0..2 "homer" "marge" "bart"
-</pre>
-<p>Whereas if you comment out the two lines I said you might wish to,
-then it shows it to you this way instead:
-</p>
-<pre class="verbatim"> 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"
-</pre>
-<hr>
-<a name="perllol-Slices"></a>
-<div class="header">
-<p>
-Previous: <a href="#perllol-Access-and-Printing" accesskey="p"
rel="prev">perllol Access and Printing</a>, Up: <a href="#perllol-DESCRIPTION"
accesskey="u" rel="up">perllol DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Slices-1"></a>
-<h4 class="subsection">39.2.4 Slices</h4>
-
-<p>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.
-</p>
-<p>Here’s how to do one operation using a loop. We’ll assume an
@AoA
-variable as before.
-</p>
-<pre class="verbatim"> @part = ();
- $x = 4;
- for ($y = 7; $y < 13; $y++) {
- push @part, $AoA[$x][$y];
- }
-</pre>
-<p>That same loop could be replaced with a slice operation:
-</p>
-<pre class="verbatim"> @part = @{$AoA[4]}[7..12];
-</pre>
-<p>or spaced out a bit:
-</p>
-<pre class="verbatim"> @part = @{ $AoA[4] } [ 7..12 ];
-</pre>
-<p>But as you might well imagine, this can get pretty rough on the reader.
-</p>
-<p>Ah, but what if you wanted a <em>two-dimensional slice</em>, such as having
-$x run from 4..8 and $y run from 7 to 12? Hmm... here’s the simple way:
-</p>
-<pre class="verbatim"> @newAoA = ();
- for ($startx = $x = 4; $x <= 8; $x++) {
- for ($starty = $y = 7; $y <= 12; $y++) {
- $newAoA[$x - $startx][$y - $starty] = $AoA[$x][$y];
- }
- }
-</pre>
-<p>We can reduce some of the looping through slices
-</p>
-<pre class="verbatim"> for ($x = 4; $x <= 8; $x++) {
- push @newAoA, [ @{ $AoA[$x] } [ 7..12 ] ];
- }
-</pre>
-<p>If you were into Schwartzian Transforms, you would probably
-have selected map for that
-</p>
-<pre class="verbatim"> @newAoA = map { [ @{ $AoA[$_] } [ 7..12 ] ] } 4 .. 8;
-</pre>
-<p>Although if your manager accused you of seeking job security (or rapid
-insecurity) through inscrutable code, it would be hard to argue. :-)
-If I were you, I’d put that in a function:
-</p>
-<pre class="verbatim"> @newAoA = splice_2D( address@hidden, 4 => 8, 7
=> 12 );
- sub splice_2D {
- my $lrr = shift; # ref to array of array refs!
- my ($x_lo, $x_hi,
- $y_lo, $y_hi) = @_;
-
- return map {
- [ @{ $lrr->[$_] } [ $y_lo .. $y_hi ] ]
- } $x_lo .. $x_hi;
- }
-</pre>
-<hr>
-<a name="perllol-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perllol-AUTHOR" accesskey="n" rel="next">perllol AUTHOR</a>,
Previous: <a href="#perllol-DESCRIPTION" accesskey="p" rel="prev">perllol
DESCRIPTION</a>, Up: <a href="#perllol" accesskey="u" rel="up">perllol</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-18"></a>
-<h3 class="section">39.3 SEE ALSO</h3>
-
-<p><a href="#perldata-NAME">perldata NAME</a>, <a href="#perlref-NAME">perlref
NAME</a>, <a href="#perldsc-NAME">perldsc NAME</a>
-</p>
-<hr>
-<a name="perllol-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perllol-SEE-ALSO" accesskey="p" rel="prev">perllol SEE
ALSO</a>, Up: <a href="#perllol" accesskey="u" rel="up">perllol</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-16"></a>
-<h3 class="section">39.4 AUTHOR</h3>
-
-<p>Tom Christiansen <<samp>address@hidden</samp>>
-</p>
-<p>Last update: Tue Apr 26 18:30:55 MDT 2011
-</p>
-<hr>
-<a name="perlmod"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodinstall" accesskey="n" rel="next">perlmodinstall</a>,
Previous: <a href="#perllol" accesskey="p" rel="prev">perllol</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlmod-2"></a>
-<h2 class="chapter">40 perlmod</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlmod-NAME"
accesskey="1">perlmod NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmod-DESCRIPTION"
accesskey="2">perlmod DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmod-SEE-ALSO"
accesskey="3">perlmod SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlmod-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmod-DESCRIPTION" accesskey="n" rel="next">perlmod
DESCRIPTION</a>, Up: <a href="#perlmod" accesskey="u" rel="up">perlmod</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-39"></a>
-<h3 class="section">40.1 NAME</h3>
-
-<p>perlmod - Perl modules (packages and symbol tables)
-</p>
-<hr>
-<a name="perlmod-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmod-SEE-ALSO" accesskey="n" rel="next">perlmod SEE
ALSO</a>, Previous: <a href="#perlmod-NAME" accesskey="p" rel="prev">perlmod
NAME</a>, Up: <a href="#perlmod" accesskey="u" rel="up">perlmod</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-39"></a>
-<h3 class="section">40.2 DESCRIPTION</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlmod-Is-this-the-document-you-were-after_003f" accesskey="1">perlmod
Is this the document you were after?</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmod-Packages"
accesskey="2">perlmod Packages</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmod-Symbol-Tables"
accesskey="3">perlmod Symbol Tables</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmod-BEGIN_002c-UNITCHECK_002c-CHECK_002c-INIT-and-END"
accesskey="4">perlmod BEGIN, UNITCHECK, CHECK, INIT and
END</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmod-Perl-Classes"
accesskey="5">perlmod Perl Classes</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmod-Perl-Modules"
accesskey="6">perlmod Perl Modules</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmod-Making-your-module-threadsafe" accesskey="7">perlmod Making your
module threadsafe</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlmod-Is-this-the-document-you-were-after_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmod-Packages" accesskey="n" rel="next">perlmod
Packages</a>, Up: <a href="#perlmod-DESCRIPTION" accesskey="u" rel="up">perlmod
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Is-this-the-document-you-were-after_003f"></a>
-<h4 class="subsection">40.2.1 Is this the document you were after?</h4>
-
-<p>There are other documents which might contain the information that
you’re
-looking for:
-</p>
-<dl compact="compact">
-<dt>This doc</dt>
-<dd><a name="perlmod-This-doc"></a>
-<p>Perl’s packages, namespaces, and some info on classes.
-</p>
-</dd>
-<dt><a href="#perlnewmod-NAME">perlnewmod NAME</a></dt>
-<dd><a name="perlmod-perlnewmod-NAME"></a>
-<p>Tutorial on making a new module.
-</p>
-</dd>
-<dt><a href="#perlmodstyle-NAME">perlmodstyle NAME</a></dt>
-<dd><a name="perlmod-perlmodstyle-NAME"></a>
-<p>Best practices for making a new module.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlmod-Packages"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmod-Symbol-Tables" accesskey="n" rel="next">perlmod Symbol
Tables</a>, Previous: <a
href="#perlmod-Is-this-the-document-you-were-after_003f" accesskey="p"
rel="prev">perlmod Is this the document you were after?</a>, Up: <a
href="#perlmod-DESCRIPTION" accesskey="u" rel="up">perlmod DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Packages"></a>
-<h4 class="subsection">40.2.2 Packages</h4>
-
-<p>Perl provides a mechanism for alternative namespaces to protect
-packages from stomping on each other’s variables. In fact, there’s
-really no such thing as a global variable in Perl. The package
-statement 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, <code>eval</code>,
-or file, whichever comes first (the same scope as the my() and
-local() operators). Unqualified dynamic identifiers will be in
-this namespace, except for those few identifiers that if unqualified,
-default to the main package instead of the current one as described
-below. A package statement affects only dynamic variables–including
-those you’ve used local() on–but <em>not</em> lexical variables
created
-with my(). Typically it would be the first declaration in a file
-included by the <code>do</code>, <code>require</code>, or <code>use</code>
operators. You can
-switch into a package in more than one place; it merely influences
-which symbol table is used by the compiler for the rest of that
-block. You can refer to variables and filehandles in other packages
-by prefixing the identifier with the package name and a double
-colon: <code>$Package::Variable</code>. If the package name is null, the
-<code>main</code> package is assumed. That is, <code>$::sail</code> is
equivalent to
-<code>$main::sail</code>.
-</p>
-<p>The old package delimiter was a single quote, but double colon is now the
-preferred delimiter, in part because it’s more readable to humans, and
-in part because it’s more readable to <strong>emacs</strong> macros. It
also makes C++
-programmers feel like they know what’s going on–as opposed to
using the
-single quote as separator, which was there to make Ada programmers feel
-like they knew what was going on. Because the old-fashioned syntax is still
-supported for backwards compatibility, if you try to use a string like
-<code>"This is $owner's house"</code>, you’ll be accessing
<code>$owner::s</code>; that is,
-the $s variable in package <code>owner</code>, which is probably not what you
meant.
-Use braces to disambiguate, as in <code>"This is ${owner}'s
house"</code>.
-</p>
-<p>Packages may themselves contain package separators, as in
-<code>$OUTER::INNER::var</code>. This implies nothing about the order of
-name lookups, however. There are no relative packages: all symbols
-are either local to the current package, or must be fully qualified
-from the outer package name down. For instance, there is nowhere
-within package <code>OUTER</code> that <code>$INNER::var</code> refers to
-<code>$OUTER::INNER::var</code>. <code>INNER</code> refers to a totally
-separate global package.
-</p>
-<p>Only identifiers starting with letters (or underscore) are stored
-in a package’s symbol table. All other symbols are kept in package
-<code>main</code>, including all punctuation variables, like $_. In addition,
-when unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV,
-ARGVOUT, ENV, INC, and SIG are forced to be in package <code>main</code>,
-even when used for other purposes than their built-in ones. If you
-have a package called <code>m</code>, <code>s</code>, or <code>y</code>, then
you can’t use the
-qualified form of an identifier because it would be instead interpreted
-as a pattern match, a substitution, or a transliteration.
-</p>
-<p>Variables beginning with underscore used to be forced into package
-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 <code>_</code>, such as
-$_ and <code>sub _</code>, are still forced into the package
<code>main</code>. See also
-<a href="#perlvar-The-Syntax-of-Variable-Names">perlvar The Syntax of Variable
Names</a>.
-</p>
-<p><code>eval</code>ed strings are compiled in the package in which the eval()
was
-compiled. (Assignments to <code>$SIG{}</code>, however, assume the signal
-handler specified is in the <code>main</code> package. Qualify the signal
handler
-name if you wish to have a signal handler in a package.) For an
-example, examine <samp>perldb.pl</samp> in the Perl library. It initially
switches
-to the <code>DB</code> package so that the debugger doesn’t interfere
with variables
-in the program you are trying to debug. At various points, however, it
-temporarily switches back to the <code>main</code> package to evaluate various
-expressions in the context of the <code>main</code> package (or wherever you
came
-from). See <a href="#perldebug-NAME">perldebug NAME</a>.
-</p>
-<p>The special symbol <code>__PACKAGE__</code> contains the current package,
but cannot
-(easily) be used to construct variable names.
-</p>
-<p>See <a href="#perlsub-NAME">perlsub NAME</a> for other scoping issues
related to my() and local(),
-and <a href="#perlref-NAME">perlref NAME</a> regarding closures.
-</p>
-<hr>
-<a name="perlmod-Symbol-Tables"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmod-BEGIN_002c-UNITCHECK_002c-CHECK_002c-INIT-and-END"
accesskey="n" rel="next">perlmod BEGIN, UNITCHECK, CHECK, INIT and END</a>,
Previous: <a href="#perlmod-Packages" accesskey="p" rel="prev">perlmod
Packages</a>, Up: <a href="#perlmod-DESCRIPTION" accesskey="u" rel="up">perlmod
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Symbol-Tables"></a>
-<h4 class="subsection">40.2.3 Symbol Tables</h4>
-
-<p>The symbol table for a package happens to be stored in the hash of that
-name with two colons appended. The main symbol table’s name is thus
-<code>%main::</code>, or <code>%::</code> for short. Likewise the symbol
table for the nested
-package mentioned earlier is named <code>%OUTER::INNER::</code>.
-</p>
-<p>The value in each entry of the hash is what you are referring to when you
-use the <code>*name</code> typeglob notation.
-</p>
-<pre class="verbatim"> local *main::foo = *main::bar;
-</pre>
-<p>You can use this to print out all the variables in a package, for
-instance. The standard but antiquated <samp>dumpvar.pl</samp> library and
-the CPAN module Devel::Symdump make use of this.
-</p>
-<p>The results of creating new symbol table entries directly or modifying any
-entries that are not already typeglobs are undefined and subject to change
-between releases of perl.
-</p>
-<p>Assignment to a typeglob performs an aliasing operation, i.e.,
-</p>
-<pre class="verbatim"> *dick = *richard;
-</pre>
-<p>causes variables, subroutines, formats, and file and directory handles
-accessible via the identifier <code>richard</code> also to be accessible via
the
-identifier <code>dick</code>. If you want to alias only a particular variable
or
-subroutine, assign a reference instead:
-</p>
-<pre class="verbatim"> *dick = \$richard;
-</pre>
-<p>Which makes $richard and $dick the same variable, but leaves
address@hidden and @dick as separate arrays. Tricky, eh?
-</p>
-<p>There is one subtle difference between the following statements:
-</p>
-<pre class="verbatim"> *foo = *bar;
- *foo = \$bar;
-</pre>
-<p><code>*foo = *bar</code> makes the typeglobs themselves synonymous while
-<code>*foo = \$bar</code> makes the SCALAR portions of two distinct typeglobs
-refer to the same scalar value. This means that the following code:
-</p>
-<pre class="verbatim"> $bar = 1;
- *foo = \$bar; # Make $foo an alias for $bar
-
- {
- local $bar = 2; # Restrict changes to block
- print $foo; # Prints '1'!
- }
-</pre>
-<p>Would print ’1’, because <code>$foo</code> holds a reference to
the <em>original</em>
-<code>$bar</code>. The one that was stuffed away by <code>local()</code> and
which will be
-restored when the block ends. Because variables are accessed through the
-typeglob, you can use <code>*foo = *bar</code> to create an alias which can be
-localized. (But be aware that this means you can’t have a separate
-<code>@foo</code> and <code>@bar</code>, etc.)
-</p>
-<p>What makes all of this important is that the Exporter module uses glob
-aliasing as the import/export mechanism. Whether or not you can properly
-localize a variable that has been exported from a module depends on how
-it was exported:
-</p>
-<pre class="verbatim"> @EXPORT = qw($FOO); # Usual form, can't be localized
- @EXPORT = qw(*FOO); # Can be localized
-</pre>
-<p>You can work around the first case by using the fully qualified name
-(<code>$Package::FOO</code>) where you need a local value, or by overriding it
-by saying <code>*FOO = *Package::FOO</code> in your script.
-</p>
-<p>The <code>*x = \$y</code> mechanism may be used to pass and return cheap
references
-into or from subroutines if you don’t want to copy the whole
-thing. It only works when assigning to dynamic variables, not
-lexicals.
-</p>
-<pre class="verbatim"> %some_hash = (); # can't be my()
- *some_hash = fn( \%another_hash );
- sub fn {
- local *hashsym = shift;
- # now use %hashsym normally, and you
- # will affect the caller's %another_hash
- my %nhash = (); # do what you want
- return \%nhash;
- }
-</pre>
-<p>On return, the reference will overwrite the hash slot in the
-symbol table specified by the *some_hash typeglob. This
-is a somewhat tricky way of passing around references cheaply
-when you don’t want to have to remember to dereference variables
-explicitly.
-</p>
-<p>Another use of symbol tables is for making "constant" scalars.
-</p>
-<pre class="verbatim"> *PI = \3.14159265358979;
-</pre>
-<p>Now you cannot alter <code>$PI</code>, which is probably a good thing all
in all.
-This isn’t the same as a constant subroutine, which is subject to
-optimization at compile-time. A constant subroutine is one prototyped
-to take no arguments and to return a constant expression. See
-<a href="#perlsub-NAME">perlsub NAME</a> for details on these. The <code>use
constant</code> pragma is a
-convenient shorthand for these.
-</p>
-<p>You can say <code>*foo{PACKAGE}</code> and <code>*foo{NAME}</code> to find
out what name and
-package the *foo symbol table entry comes from. This may be useful
-in a subroutine that gets passed typeglobs as arguments:
-</p>
-<pre class="verbatim"> sub identify_typeglob {
- my $glob = shift;
- print 'You gave me ', *{$glob}{PACKAGE},
- '::', *{$glob}{NAME}, "\n";
- }
- identify_typeglob *foo;
- identify_typeglob *bar::baz;
-</pre>
-<p>This prints
-</p>
-<pre class="verbatim"> You gave me main::foo
- You gave me bar::baz
-</pre>
-<p>The <code>*foo{THING}</code> notation can also be used to obtain references
to the
-individual elements of *foo. See <a href="#perlref-NAME">perlref NAME</a>.
-</p>
-<p>Subroutine definitions (and declarations, for that matter) need
-not necessarily be situated in the package whose symbol table they
-occupy. You can define a subroutine outside its package by
-explicitly qualifying the name of the subroutine:
-</p>
-<pre class="verbatim"> package main;
- sub Some_package::foo { ... } # &foo defined in Some_package
-</pre>
-<p>This is just a shorthand for a typeglob assignment at compile time:
-</p>
-<pre class="verbatim"> BEGIN { *Some_package::foo = sub { ... } }
-</pre>
-<p>and is <em>not</em> the same as writing:
-</p>
-<pre class="verbatim"> {
- package Some_package;
- sub foo { ... }
- }
-</pre>
-<p>In the first two versions, the body of the subroutine is
-lexically in the main package, <em>not</em> in Some_package. So
-something like this:
-</p>
-<pre class="verbatim"> package main;
-
- $Some_package::name = "fred";
- $main::name = "barney";
-
- sub Some_package::foo {
- print "in ", __PACKAGE__, ": \$name is '$name'\n";
- }
-
- Some_package::foo();
-</pre>
-<p>prints:
-</p>
-<pre class="verbatim"> in main: $name is 'barney'
-</pre>
-<p>rather than:
-</p>
-<pre class="verbatim"> in Some_package: $name is 'fred'
-</pre>
-<p>This also has implications for the use of the SUPER:: qualifier
-(see <a href="#perlobj-NAME">perlobj NAME</a>).
-</p>
-<hr>
-<a name="perlmod-BEGIN_002c-UNITCHECK_002c-CHECK_002c-INIT-and-END"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmod-Perl-Classes" accesskey="n" rel="next">perlmod Perl
Classes</a>, Previous: <a href="#perlmod-Symbol-Tables" accesskey="p"
rel="prev">perlmod Symbol Tables</a>, Up: <a href="#perlmod-DESCRIPTION"
accesskey="u" rel="up">perlmod DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="BEGIN_002c-UNITCHECK_002c-CHECK_002c-INIT-and-END"></a>
-<h4 class="subsection">40.2.4 BEGIN, UNITCHECK, CHECK, INIT and END</h4>
-
-<p>Five specially named code blocks are executed at the beginning and at
-the end of a running Perl program. These are the <code>BEGIN</code>,
-<code>UNITCHECK</code>, <code>CHECK</code>, <code>INIT</code>, and
<code>END</code> blocks.
-</p>
-<p>These code blocks can be prefixed with <code>sub</code> to give the
appearance of a
-subroutine (although this is not considered good style). One should note
-that these code blocks don’t really exist as named subroutines (despite
-their appearance). The thing that gives this away is the fact that you can
-have <strong>more than one</strong> of these code blocks in a program, and
they will get
-<strong>all</strong> executed at the appropriate moment. So you can’t
execute any of
-these code blocks by name.
-</p>
-<p>A <code>BEGIN</code> code block is executed as soon as possible, that is,
the moment
-it is completely defined, even before the rest of the containing file (or
-string) is parsed. You may have multiple <code>BEGIN</code> blocks within a
file (or
-eval’ed string); they will execute in order of definition. Because a
<code>BEGIN</code>
-code block executes immediately, it can pull in definitions of subroutines
-and such from other files in time to be visible to the rest of the compile
-and run time. Once a <code>BEGIN</code> has run, it is immediately undefined
and any
-code it used is returned to Perl’s memory pool.
-</p>
-<p>An <code>END</code> code block is executed as late as possible, that is,
after
-perl has finished running the program and just before the interpreter
-is being exited, even if it is exiting as a result of a die() function.
-(But not if it’s morphing into another program via <code>exec</code>, or
-being blown out of the water by a signal–you have to trap that yourself
-(if you can).) You may have multiple <code>END</code> blocks within a
file–they
-will execute in reverse order of definition; that is: last in, first
-out (LIFO). <code>END</code> blocks are not executed when you run perl with
the
-<code>-c</code> switch, or if compilation fails.
-</p>
-<p>Note that <code>END</code> code blocks are <strong>not</strong> executed at
the end of a string
-<code>eval()</code>: if any <code>END</code> code blocks are created in a
string <code>eval()</code>,
-they will be executed just as any other <code>END</code> code block of that
package
-in LIFO order just before the interpreter is being exited.
-</p>
-<p>Inside an <code>END</code> code block, <code>$?</code> contains the value
that the program is
-going to pass to <code>exit()</code>. You can modify <code>$?</code> to
change the exit
-value of the program. Beware of changing <code>$?</code> by accident (e.g. by
-running something via <code>system</code>).
-</p>
-<p>Inside of a <code>END</code> block, the value of
<code>${^GLOBAL_PHASE}</code> will be
-<code>"END"</code>.
-</p>
-<p><code>UNITCHECK</code>, <code>CHECK</code> and <code>INIT</code> code
blocks are useful to catch the
-transition between the compilation phase and the execution phase of
-the main program.
-</p>
-<p><code>UNITCHECK</code> blocks are run just after the unit which defined
them has
-been compiled. The main program file and each module it loads are
-compilation units, as are string <code>eval</code>s, run-time code compiled
using the
-<code>(?{ })</code> construct in a regex, calls to <code>do FILE</code>,
<code>require FILE</code>,
-and code after the <code>-e</code> switch on the command line.
-</p>
-<p><code>BEGIN</code> and <code>UNITCHECK</code> blocks are not directly
related to the phase of
-the interpreter. They can be created and executed during any phase.
-</p>
-<p><code>CHECK</code> code blocks are run just after the
<strong>initial</strong> Perl compile phase ends
-and before the run time begins, in LIFO order. <code>CHECK</code> code blocks
are used
-in the Perl compiler suite to save the compiled state of the program.
-</p>
-<p>Inside of a <code>CHECK</code> block, the value of
<code>${^GLOBAL_PHASE}</code> will be
-<code>"CHECK"</code>.
-</p>
-<p><code>INIT</code> blocks are run just before the Perl runtime begins
execution, in
-"first in, first out" (FIFO) order.
-</p>
-<p>Inside of an <code>INIT</code> block, the value of
<code>${^GLOBAL_PHASE}</code> will be <code>"INIT"</code>.
-</p>
-<p>The <code>CHECK</code> and <code>INIT</code> blocks in code compiled by
<code>require</code>, string <code>do</code>,
-or string <code>eval</code> 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.
-</p>
-<p>When you use the <strong>-n</strong> and <strong>-p</strong> switches to
Perl, <code>BEGIN</code> and
-<code>END</code> work just as they do in <strong>awk</strong>, as a degenerate
case.
-Both <code>BEGIN</code> and <code>CHECK</code> blocks are run when you use the
<strong>-c</strong>
-switch for a compile-only syntax check, although your main code
-is not.
-</p>
-<p>The <strong>begincheck</strong> program makes it all clear, eventually:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
-
- # begincheck
-
- print "10. Ordinary code runs at runtime.\n";
-
- END { print "16. So this is the end of the tale.\n" }
- INIT { print " 7. INIT blocks run FIFO just before runtime.\n" }
- UNITCHECK {
- print " 4. And therefore before any CHECK blocks.\n"
- }
- CHECK { print " 6. So this is the sixth line.\n" }
-
- print "11. It runs in order, of course.\n";
-
- BEGIN { print " 1. BEGIN blocks run FIFO during compilation.\n" }
- END { print "15. Read perlmod for the rest of the story.\n" }
- CHECK { print " 5. CHECK blocks run LIFO after all compilation.\n"
}
- INIT { print " 8. Run this again, using Perl's -c switch.\n" }
-
- print "12. This is anti-obfuscated code.\n";
-
- END { print "14. END blocks run LIFO at quitting time.\n" }
- BEGIN { print " 2. So this line comes out second.\n" }
- UNITCHECK {
- print " 3. UNITCHECK blocks run LIFO after each file is
compiled.\n"
- }
- INIT { print " 9. You'll see the difference right away.\n" }
-
- print "13. It only _looks_ like it should be
confusing.\n";
-
- __END__
-</pre>
-<hr>
-<a name="perlmod-Perl-Classes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmod-Perl-Modules" accesskey="n" rel="next">perlmod Perl
Modules</a>, Previous: <a
href="#perlmod-BEGIN_002c-UNITCHECK_002c-CHECK_002c-INIT-and-END" accesskey="p"
rel="prev">perlmod BEGIN, UNITCHECK, CHECK, INIT and END</a>, Up: <a
href="#perlmod-DESCRIPTION" accesskey="u" rel="up">perlmod DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Perl-Classes"></a>
-<h4 class="subsection">40.2.5 Perl Classes</h4>
-
-<p>There is no special class syntax in Perl, but a package may act
-as a class if it provides subroutines to act as methods. Such a
-package may also derive some of its methods from another class (package)
-by listing the other package name(s) in its global @ISA array (which
-must be a package global, not a lexical).
-</p>
-<p>For more on this, see <a href="#perlootut-NAME">perlootut NAME</a> and <a
href="#perlobj-NAME">perlobj NAME</a>.
-</p>
-<hr>
-<a name="perlmod-Perl-Modules"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmod-Making-your-module-threadsafe" accesskey="n"
rel="next">perlmod Making your module threadsafe</a>, Previous: <a
href="#perlmod-Perl-Classes" accesskey="p" rel="prev">perlmod Perl Classes</a>,
Up: <a href="#perlmod-DESCRIPTION" accesskey="u" rel="up">perlmod
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Perl-Modules"></a>
-<h4 class="subsection">40.2.6 Perl Modules</h4>
-
-<p>A module is just a set of related functions in a library file, i.e.,
-a Perl package with the same name as the file. It is specifically
-designed to be reusable by other modules or programs. It may do this
-by providing a mechanism for exporting some of its symbols into the
-symbol table of any package using it, or it may function as a class
-definition and make its semantics available implicitly through
-method calls on the class and its objects, without explicitly
-exporting anything. Or it can do a little of both.
-</p>
-<p>For example, to start a traditional, non-OO module called Some::Module,
-create a file called <samp>Some/Module.pm</samp> and start with this template:
-</p>
-<pre class="verbatim"> package Some::Module; # assumes Some/Module.pm
-
- use strict;
- use warnings;
-
- BEGIN {
- require Exporter;
-
- # set the version for version checking
- our $VERSION = 1.00;
-
- # Inherit from Exporter to export functions and variables
- our @ISA = qw(Exporter);
-
- # Functions and variables which are exported by default
- our @EXPORT = qw(func1 func2);
-
- # Functions and variables which can be optionally exported
- our @EXPORT_OK = qw($Var1 %Hashit func3);
- }
-
- # exported package globals go here
- our $Var1 = '';
- our %Hashit = ();
-
- # non-exported package globals go here
- # (they are still accessible as $Some::Module::stuff)
- our @more = ();
- our $stuff = '';
-
- # file-private lexicals go here, before any functions which use them
- my $priv_var = '';
- my %secret_hash = ();
-
- # here's a file-private function as a closure,
- # callable as $priv_func->();
- my $priv_func = sub {
- ...
- };
-
- # make all your functions, whether exported or not;
- # remember to put something interesting in the {} stubs
- sub func1 { ... }
- sub func2 { ... }
-
- # this one isn't exported, but could be called directly
- # as Some::Module::func3()
- sub func3 { ... }
-
- END { ... } # module clean-up code here (global destructor)
-
- 1; # don't forget to return a true value from the file
-</pre>
-<p>Then go on to declare and use your variables in functions without
-any qualifications. See <a href="Exporter.html#Top">(Exporter)</a> and the <a
href="perlmodlib.html#Top">(perlmodlib)</a> for
-details on mechanics and style issues in module creation.
-</p>
-<p>Perl modules are included into your program by saying
-</p>
-<pre class="verbatim"> use Module;
-</pre>
-<p>or
-</p>
-<pre class="verbatim"> use Module LIST;
-</pre>
-<p>This is exactly equivalent to
-</p>
-<pre class="verbatim"> BEGIN { require 'Module.pm'; 'Module'->import; }
-</pre>
-<p>or
-</p>
-<pre class="verbatim"> BEGIN { require 'Module.pm'; 'Module'->import(
LIST ); }
-</pre>
-<p>As a special case
-</p>
-<pre class="verbatim"> use Module ();
-</pre>
-<p>is exactly equivalent to
-</p>
-<pre class="verbatim"> BEGIN { require 'Module.pm'; }
-</pre>
-<p>All Perl module files have the extension <samp>.pm</samp>. The
<code>use</code> operator
-assumes this so you don’t have to spell out
"<samp>Module.pm</samp>" in quotes.
-This also helps to differentiate new modules from old <samp>.pl</samp> and
-<samp>.ph</samp> files. Module names are also capitalized unless they’re
-functioning as pragmas; pragmas are in effect compiler directives,
-and are sometimes called "pragmatic modules" (or even
"pragmata"
-if you’re a classicist).
-</p>
-<p>The two statements:
-</p>
-<pre class="verbatim"> require SomeModule;
- require "SomeModule.pm";
-</pre>
-<p>differ from each other in two ways. In the first case, any double
-colons in the module name, such as <code>Some::Module</code>, are translated
-into your system’s directory separator, usually "/". The
second
-case does not, and would have to be specified literally. The other
-difference is that seeing the first <code>require</code> clues in the compiler
-that uses of indirect object notation involving "SomeModule", as
-in <code>$ob = purge SomeModule</code>, are method calls, not function calls.
-(Yes, this really can make a difference.)
-</p>
-<p>Because the <code>use</code> statement implies a <code>BEGIN</code> block,
the importing
-of semantics happens as soon as the <code>use</code> statement is compiled,
-before the rest of the file is compiled. This is how it is able
-to function as a pragma mechanism, and also how modules are able to
-declare subroutines that are then visible as list or unary operators for
-the rest of the current file. This will not work if you use
<code>require</code>
-instead of <code>use</code>. With <code>require</code> you can get into this
problem:
-</p>
-<pre class="verbatim"> require Cwd; # make Cwd:: accessible
- $here = Cwd::getcwd();
-
- use Cwd; # import names from Cwd::
- $here = getcwd();
-
- require Cwd; # make Cwd:: accessible
- $here = getcwd(); # oops! no main::getcwd()
-</pre>
-<p>In general, <code>use Module ()</code> is recommended over <code>require
Module</code>,
-because it determines module availability at compile time, not in the
-middle of your program’s execution. An exception would be if two modules
-each tried to <code>use</code> each other, and each also called a function from
-that other module. In that case, it’s easy to use <code>require</code>
instead.
-</p>
-<p>Perl packages may be nested inside other package names, so we can have
-package names containing <code>::</code>. But if we used that package name
-directly as a filename it would make for unwieldy or impossible
-filenames on some systems. Therefore, if a module’s name is, say,
-<code>Text::Soundex</code>, then its definition is actually found in the
library
-file <samp>Text/Soundex.pm</samp>.
-</p>
-<p>Perl modules always have a <samp>.pm</samp> file, but there may also be
-dynamically linked executables (often ending in <samp>.so</samp>) or autoloaded
-subroutine definitions (often ending in <samp>.al</samp>) associated with the
-module. If so, these will be entirely transparent to the user of
-the module. It is the responsibility of the <samp>.pm</samp> file to load
-(or arrange to autoload) any additional functionality. For example,
-although the POSIX module happens to do both dynamic loading and
-autoloading, the user can say just <code>use POSIX</code> to get it all.
-</p>
-<hr>
-<a name="perlmod-Making-your-module-threadsafe"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlmod-Perl-Modules" accesskey="p" rel="prev">perlmod
Perl Modules</a>, Up: <a href="#perlmod-DESCRIPTION" accesskey="u"
rel="up">perlmod DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Making-your-module-threadsafe"></a>
-<h4 class="subsection">40.2.7 Making your module threadsafe</h4>
-
-<p>Perl supports a type of threads called interpreter threads (ithreads).
-These threads can be used explicitly and implicitly.
-</p>
-<p>Ithreads work by cloning the data tree so that no data is shared
-between different threads. These threads can be used by using the
<code>threads</code>
-module or by doing fork() on win32 (fake fork() support). When a
-thread is cloned all Perl data is cloned, however non-Perl data cannot
-be cloned automatically. Perl after 5.8.0 has support for the
<code>CLONE</code>
-special subroutine. In <code>CLONE</code> you can do whatever
-you need to do,
-like for example handle the cloning of non-Perl data, if necessary.
-<code>CLONE</code> 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
-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.
-</p>
-<p>If you want to CLONE all objects you will need to keep track of them per
-package. This is simply done using a hash and Scalar::Util::weaken().
-</p>
-<p>Perl after 5.8.7 has support for the <code>CLONE_SKIP</code> special
subroutine.
-Like <code>CLONE</code>, <code>CLONE_SKIP</code> is called once per package;
however, it is
-called just before cloning starts, and in the context of the parent
-thread. If it returns a true value, then no objects of that class will
-be cloned; or rather, they will be copied as unblessed, undef values.
-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
-<code>sub CLONE_SKIP { 1 }</code> at the top of the class, and
<code>DESTROY()</code> 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.
-</p>
-<p>Like <code>CLONE</code>, <code>CLONE_SKIP</code> is currently called with
no parameters other
-than the invocant package name, although that may change. Similarly, to
-allow for future expansion, the return value should be a single <code>0</code>
or
-<code>1</code> value.
-</p>
-<hr>
-<a name="perlmod-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlmod-DESCRIPTION" accesskey="p" rel="prev">perlmod
DESCRIPTION</a>, Up: <a href="#perlmod" accesskey="u" rel="up">perlmod</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-19"></a>
-<h3 class="section">40.3 SEE ALSO</h3>
-
-<p>See <a href="perlmodlib.html#Top">(perlmodlib)</a> for general style issues
related to building Perl
-modules and classes, as well as descriptions of the standard library
-and CPAN, <a href="Exporter.html#Top">(Exporter)</a> for how Perl’s
standard import/export mechanism
-works, <a href="#perlootut-NAME">perlootut NAME</a> and <a
href="#perlobj-NAME">perlobj NAME</a> for in-depth information on
-creating classes, <a href="#perlobj-NAME">perlobj NAME</a> for a hard-core
reference document on
-objects, <a href="#perlsub-NAME">perlsub NAME</a> for an explanation of
functions and scoping,
-and <a href="perlxstut.html#Top">(perlxstut)</a> and <a
href="#perlguts-NAME">perlguts NAME</a> for more information on writing
-extension modules.
-</p>
-<hr>
-<a name="perlmodinstall"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle" accesskey="n" rel="next">perlmodstyle</a>,
Previous: <a href="#perlmod" accesskey="p" rel="prev">perlmod</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlmodinstall-1"></a>
-<h2 class="chapter">41 perlmodinstall</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlmodinstall-NAME"
accesskey="1">perlmodinstall NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmodinstall-DESCRIPTION"
accesskey="2">perlmodinstall DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmodinstall-PORTABILITY"
accesskey="3">perlmodinstall PORTABILITY</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmodinstall-HEY"
accesskey="4">perlmodinstall HEY</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmodinstall-AUTHOR"
accesskey="5">perlmodinstall AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmodinstall-COPYRIGHT"
accesskey="6">perlmodinstall COPYRIGHT</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlmodinstall-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodinstall-DESCRIPTION" accesskey="n"
rel="next">perlmodinstall DESCRIPTION</a>, Up: <a href="#perlmodinstall"
accesskey="u" rel="up">perlmodinstall</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-40"></a>
-<h3 class="section">41.1 NAME</h3>
-
-<p>perlmodinstall - Installing CPAN Modules
-</p>
-<hr>
-<a name="perlmodinstall-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodinstall-PORTABILITY" accesskey="n"
rel="next">perlmodinstall PORTABILITY</a>, Previous: <a
href="#perlmodinstall-NAME" accesskey="p" rel="prev">perlmodinstall NAME</a>,
Up: <a href="#perlmodinstall" accesskey="u" rel="up">perlmodinstall</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-40"></a>
-<h3 class="section">41.2 DESCRIPTION</h3>
-
-<p>You can think of a module as the fundamental unit of reusable Perl
-code; see <a href="#perlmod-NAME">perlmod NAME</a> for details. Whenever
anyone creates a chunk of
-Perl code that they think will be useful to the world, they register
-as a Perl developer at http://www.cpan.org/modules/04pause.html
-so that they can then upload their code to the CPAN. The CPAN is the
-Comprehensive Perl Archive Network and can be accessed at
-http://www.cpan.org/ , and searched at http://search.cpan.org/ .
-</p>
-<p>This documentation is for people who want to download CPAN modules
-and install them on their own computer.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlmodinstall-PREAMBLE"
accesskey="1">perlmodinstall PREAMBLE</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlmodinstall-PREAMBLE"></a>
-<div class="header">
-<p>
-Up: <a href="#perlmodinstall-DESCRIPTION" accesskey="u"
rel="up">perlmodinstall DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PREAMBLE-1"></a>
-<h4 class="subsection">41.2.1 PREAMBLE</h4>
-
-<p>First, are you sure that the module isn’t already on your system? Try
-<code>perl -MFoo -e 1</code>. (Replace "Foo" with the name of the
module; for
-instance, <code>perl -MCGI::Carp -e 1</code>.)
-</p>
-<p>If you don’t see an error message, you have the module. (If you do
-see an error message, it’s still possible you have the module, but
-that it’s not in your path, which you can display with <code>perl -e
-"print qq(@INC)"</code>.) For the remainder of this document,
we’ll assume
-that you really honestly truly lack an installed module, but have
-found it on the CPAN.
-</p>
-<p>So now you have a file ending in .tar.gz (or, less often, .zip). You
-know there’s a tasty module inside. There are four steps you must now
-take:
-</p>
-<dl compact="compact">
-<dt><strong>DECOMPRESS</strong> the file</dt>
-<dd><a name="perlmodinstall-DECOMPRESS-the-file"></a>
-</dd>
-<dt><strong>UNPACK</strong> the file into a directory</dt>
-<dd><a name="perlmodinstall-UNPACK-the-file-into-a-directory"></a>
-</dd>
-<dt><strong>BUILD</strong> the module (sometimes unnecessary)</dt>
-<dd><a
name="perlmodinstall-BUILD-the-module-_0028sometimes-unnecessary_0029"></a>
-</dd>
-<dt><strong>INSTALL</strong> the module.</dt>
-<dd><a name="perlmodinstall-INSTALL-the-module_002e"></a>
-</dd>
-</dl>
-
-<p>Here’s how to perform each step for each operating system. This is
-<not> a substitute for reading the README and INSTALL files that
-might have come with your module!
-</p>
-<p>Also note that these instructions are tailored for installing the
-module into your system’s repository of Perl modules, but you can
-install modules into any directory you wish. For instance, where I
-say <code>perl Makefile.PL</code>, you can substitute <code>perl Makefile.PL
-PREFIX=/my/perl_directory</code> to install the modules into
-<samp>/my/perl_directory</samp>. Then you can use the modules from your Perl
-programs with <code>use lib
"/my/perl_directory/lib/site_perl";</code> or
-sometimes just <code>use "/my/perl_directory";</code>. If
you’re on a system
-that requires superuser/root access to install modules into the
-directories you see when you type <code>perl -e "print
qq(@INC)"</code>, you’ll
-want to install them into a local directory (such as your home
-directory) and use this approach.
-</p>
-<ul>
-<li> <strong>If you’re on a Unix or Unix-like system,</strong>
-
-<p>You can use Andreas Koenig’s CPAN module
-( http://www.cpan.org/modules/by-module/CPAN )
-to automate the following steps, from DECOMPRESS through INSTALL.
-</p>
-<p>A. DECOMPRESS
-</p>
-<p>Decompress the file with <code>gzip -d yourmodule.tar.gz</code>
-</p>
-<p>You can get gzip from ftp://prep.ai.mit.edu/pub/gnu/
-</p>
-<p>Or, you can combine this step with the next to save disk space:
-</p>
-<pre class="verbatim"> gzip -dc yourmodule.tar.gz | tar -xof -
-</pre>
-<p>B. UNPACK
-</p>
-<p>Unpack the result with <code>tar -xof yourmodule.tar</code>
-</p>
-<p>C. BUILD
-</p>
-<p>Go into the newly-created directory and type:
-</p>
-<pre class="verbatim"> perl Makefile.PL
- make test
-</pre>
-<p>or
-</p>
-<pre class="verbatim"> perl Makefile.PL PREFIX=/my/perl_directory
-</pre>
-<p>to install it locally. (Remember that if you do this, you’ll have to
-put <code>use lib "/my/perl_directory";</code> near the top of the
program that
-is to use this module.
-</p>
-<p>D. INSTALL
-</p>
-<p>While still in that directory, type:
-</p>
-<pre class="verbatim"> make install
-</pre>
-<p>Make sure you have the appropriate permissions to install the module
-in your Perl 5 library directory. Often, you’ll need to be root.
-</p>
-<p>That’s all you need to do on Unix systems with dynamic linking.
-Most Unix systems have dynamic linking. If yours doesn’t, or if for
-another reason you have a statically-linked perl, <strong>and</strong> the
-module requires compilation, you’ll need to build a new Perl binary
-that includes the module. Again, you’ll probably need to be root.
-</p>
-</li><li> <strong>If you’re running ActivePerl (Win95/98/2K/NT/XP,
Linux, Solaris),</strong>
-
-<p>First, type <code>ppm</code> from a shell and see whether
ActiveState’s PPM
-repository has your module. If so, you can install it with <code>ppm</code>
and
-you won’t have to bother with any of the other steps here. You might
-be able to use the CPAN instructions from the "Unix or Linux" section
-above as well; give it a try. Otherwise, you’ll have to follow the
-steps below.
-</p>
-<pre class="verbatim"> A. DECOMPRESS
-</pre>
-<p>You can use the shareware Winzip ( http://www.winzip.com ) to
-decompress and unpack modules.
-</p>
-<pre class="verbatim"> B. UNPACK
-</pre>
-<p>If you used WinZip, this was already done for you.
-</p>
-<pre class="verbatim"> C. BUILD
-</pre>
-<p>You’ll need the <code>nmake</code> utility, available at
-http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe
-or dmake, available on CPAN.
-http://search.cpan.org/dist/dmake/
-</p>
-<p>Does the module require compilation (i.e. does it have files that end
-in .xs, .c, .h, .y, .cc, .cxx, or .C)? If it does, life is now
-officially tough for you, because you have to compile the module
-yourself (no easy feat on Windows). You’ll need a compiler such as
-Visual C++. Alternatively, you can download a pre-built PPM package
-from ActiveState.
-http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/
-</p>
-<p>Go into the newly-created directory and type:
-</p>
-<pre class="verbatim"> perl Makefile.PL
- nmake test
-
-
- D. INSTALL
-</pre>
-<p>While still in that directory, type:
-</p>
-<pre class="verbatim"> nmake install
-</pre>
-</li><li> <strong>If you’re using a Macintosh with "Classic"
MacOS and MacPerl,</strong>
-
-<p>A. DECOMPRESS
-</p>
-<p>First, make sure you have the latest <strong>cpan-mac</strong> distribution
(
-http://www.cpan.org/authors/id/CNANDOR/ ), which has utilities for
-doing all of the steps. Read the cpan-mac directions carefully and
-install it. If you choose not to use cpan-mac for some reason, there
-are alternatives listed here.
-</p>
-<p>After installing cpan-mac, drop the module archive on the
-<strong>untarzipme</strong> droplet, which will decompress and unpack for you.
-</p>
-<p><strong>Or</strong>, you can either use the shareware <strong>StuffIt
Expander</strong> program
-( http://my.smithmicro.com/mac/stuffit/ )
-or the freeware <strong>MacGzip</strong> program (
-http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ).
-</p>
-<p>B. UNPACK
-</p>
-<p>If you’re using untarzipme or StuffIt, the archive should be extracted
-now. <strong>Or</strong>, you can use the freeware <strong>suntar</strong> or
<em>Tar</em> (
-http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ).
-</p>
-<p>C. BUILD
-</p>
-<p>Check the contents of the distribution.
-Read the module’s documentation, looking for
-reasons why you might have trouble using it with MacPerl. Look for
-<samp>.xs</samp> and <samp>.c</samp> files, which normally denote that the
distribution
-must be compiled, and you cannot install it "out of the box."
-(See <a href="#perlmodinstall-PORTABILITY">PORTABILITY</a>.)
-</p>
-<p>D. INSTALL
-</p>
-<p>If you are using cpan-mac, just drop the folder on the
-<strong>installme</strong> droplet, and use the module.
-</p>
-<p><strong>Or</strong>, if you aren’t using cpan-mac, do some manual
labor.
-</p>
-<p>Make sure the newlines for the modules are in Mac format, not Unix format.
-If they are not then you might have decompressed them incorrectly. Check
-your decompression and unpacking utilities settings to make sure they are
-translating text files properly.
-</p>
-<p>As a last resort, you can use the perl one-liner:
-</p>
-<pre class="verbatim"> perl -i.bak -pe 's/(?:\015)?\012/\015/g'
<filenames>
-</pre>
-<p>on the source files.
-</p>
-<p>Then move the files (probably just the <samp>.pm</samp> files, though there
-may be some additional ones, too; check the module documentation)
-to their final destination: This will
-most likely be in <code>$ENV{MACPERL}site_lib:</code> (i.e.,
-<code>HD:MacPerl folder:site_lib:</code>). You can add new paths to
-the default <code>@INC</code> in the Preferences menu item in the
-MacPerl application (<code>$ENV{MACPERL}site_lib:</code> is added
-automagically). Create whatever directory structures are required
-(i.e., for <code>Some::Module</code>, create
-<code>$ENV{MACPERL}site_lib:Some:</code> and put
-<code>Module.pm</code> in that directory).
-</p>
-<p>Then run the following script (or something like it):
-</p>
-<pre class="verbatim"> #!perl -w
- use AutoSplit;
- my $dir = "${MACPERL}site_perl";
- autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1,
1);
-</pre>
-</li><li> <strong>If you’re on the DJGPP port of DOS,</strong>
-
-<pre class="verbatim"> A. DECOMPRESS
-</pre>
-<p>djtarx ( ftp://ftp.delorie.com/pub/djgpp/current/v2/ )
-will both uncompress and unpack.
-</p>
-<pre class="verbatim"> B. UNPACK
-</pre>
-<p>See above.
-</p>
-<pre class="verbatim"> C. BUILD
-</pre>
-<p>Go into the newly-created directory and type:
-</p>
-<pre class="verbatim"> perl Makefile.PL
- make test
-</pre>
-<p>You will need the packages mentioned in <samp>README.dos</samp>
-in the Perl distribution.
-</p>
-<pre class="verbatim"> D. INSTALL
-</pre>
-<p>While still in that directory, type:
-</p>
-<pre class="verbatim"> make install
-</pre>
-<p>You will need the packages mentioned in <samp>README.dos</samp> in the Perl
distribution.
-</p>
-</li><li> <strong>If you’re on OS/2,</strong>
-
-<p>Get the EMX development suite and gzip/tar, from either Hobbes (
-http://hobbes.nmsu.edu ) or Leo ( http://www.leo.org ), and then follow
-the instructions for Unix.
-</p>
-</li><li> <strong>If you’re on VMS,</strong>
-
-<p>When downloading from CPAN, save your file with a <code>.tgz</code>
-extension instead of <code>.tar.gz</code>. All other periods in the
-filename should be replaced with underscores. For example,
-<code>Your-Module-1.33.tar.gz</code> should be downloaded as
-<code>Your-Module-1_33.tgz</code>.
-</p>
-<p>A. DECOMPRESS
-</p>
-<p>Type
-</p>
-<pre class="verbatim"> gzip -d Your-Module.tgz
-</pre>
-<p>or, for zipped modules, type
-</p>
-<pre class="verbatim"> unzip Your-Module.zip
-</pre>
-<p>Executables for gzip, zip, and VMStar:
-</p>
-<pre class="verbatim"> http://www.hp.com/go/openvms/freeware/
-</pre>
-<p>and their source code:
-</p>
-<pre class="verbatim"> http://www.fsf.org/order/ftp.html
-</pre>
-<p>Note that GNU’s gzip/gunzip is not the same as Info-ZIP’s
zip/unzip
-package. The former is a simple compression tool; the latter permits
-creation of multi-file archives.
-</p>
-<p>B. UNPACK
-</p>
-<p>If you’re using VMStar:
-</p>
-<pre class="verbatim"> VMStar xf Your-Module.tar
-</pre>
-<p>Or, if you’re fond of VMS command syntax:
-</p>
-<pre class="verbatim"> tar/extract/verbose Your_Module.tar
-</pre>
-<p>C. BUILD
-</p>
-<p>Make sure you have MMS (from Digital) or the freeware MMK ( available
-from MadGoat at http://www.madgoat.com ). Then type this to create
-the DESCRIP.MMS for the module:
-</p>
-<pre class="verbatim"> perl Makefile.PL
-</pre>
-<p>Now you’re ready to build:
-</p>
-<pre class="verbatim"> mms test
-</pre>
-<p>Substitute <code>mmk</code> for <code>mms</code> above if you’re
using MMK.
-</p>
-<p>D. INSTALL
-</p>
-<p>Type
-</p>
-<pre class="verbatim"> mms install
-</pre>
-<p>Substitute <code>mmk</code> for <code>mms</code> above if you’re
using MMK.
-</p>
-</li><li> <strong>If you’re on MVS</strong>,
-
-<p>Introduce the <samp>.tar.gz</samp> file into an HFS as binary; don’t
translate from
-ASCII to EBCDIC.
-</p>
-<p>A. DECOMPRESS
-</p>
-<p>Decompress the file with <code>gzip -d yourmodule.tar.gz</code>
-</p>
-<p>You can get gzip from
-http://www.s390.ibm.com/products/oe/bpxqp1.html
-</p>
-<p>B. UNPACK
-</p>
-<p>Unpack the result with
-</p>
-<pre class="verbatim"> pax -o to=IBM-1047,from=ISO8859-1 -r <
yourmodule.tar
-</pre>
-<p>The BUILD and INSTALL steps are identical to those for Unix. Some
-modules generate Makefiles that work better with GNU make, which is
-available from http://www.mks.com/s390/gnu/
-</p>
-</li></ul>
-
-<hr>
-<a name="perlmodinstall-PORTABILITY"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodinstall-HEY" accesskey="n" rel="next">perlmodinstall
HEY</a>, Previous: <a href="#perlmodinstall-DESCRIPTION" accesskey="p"
rel="prev">perlmodinstall DESCRIPTION</a>, Up: <a href="#perlmodinstall"
accesskey="u" rel="up">perlmodinstall</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PORTABILITY"></a>
-<h3 class="section">41.3 PORTABILITY</h3>
-
-<p>Note that not all modules will work with on all platforms.
-See <a href="#perlport-NAME">perlport NAME</a> for more information on
portability issues.
-Read the documentation to see if the module will work on your
-system. There are basically three categories
-of modules that will not work "out of the box" with all
-platforms (with some possibility of overlap):
-</p>
-<ul>
-<li> <strong>Those that should, but don’t.</strong> These need to be
fixed; consider
-contacting the author and possibly writing a patch.
-
-</li><li> <strong>Those that need to be compiled, where the target platform
-doesn’t have compilers readily available.</strong> (These modules
contain
-<samp>.xs</samp> or <samp>.c</samp> files, usually.) You might be able to find
-existing binaries on the CPAN or elsewhere, or you might
-want to try getting compilers and building it yourself, and then
-release the binary for other poor souls to use.
-
-</li><li> <strong>Those that are targeted at a specific platform.</strong>
-(Such as the Win32:: modules.) If the module is targeted
-specifically at a platform other than yours, you’re out
-of luck, most likely.
-
-</li></ul>
-
-<p>Check the CPAN Testers if a module should work with your platform
-but it doesn’t behave as you’d expect, or you aren’t sure
whether or
-not a module will work under your platform. If the module you want
-isn’t listed there, you can test it yourself and let CPAN Testers know,
-you can join CPAN Testers, or you can request it be tested.
-</p>
-<pre class="verbatim"> http://testers.cpan.org/
-</pre>
-<hr>
-<a name="perlmodinstall-HEY"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodinstall-AUTHOR" accesskey="n" rel="next">perlmodinstall
AUTHOR</a>, Previous: <a href="#perlmodinstall-PORTABILITY" accesskey="p"
rel="prev">perlmodinstall PORTABILITY</a>, Up: <a href="#perlmodinstall"
accesskey="u" rel="up">perlmodinstall</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="HEY"></a>
-<h3 class="section">41.4 HEY</h3>
-
-<p>If you have any suggested changes for this page, let me know. Please
-don’t send me mail asking for help on how to install your modules.
-There are too many modules, and too few Orwants, for me to be able to
-answer or even acknowledge all your questions. Contact the module
-author instead, or post to comp.lang.perl.modules, or ask someone
-familiar with Perl on your operating system.
-</p>
-<hr>
-<a name="perlmodinstall-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodinstall-COPYRIGHT" accesskey="n"
rel="next">perlmodinstall COPYRIGHT</a>, Previous: <a
href="#perlmodinstall-HEY" accesskey="p" rel="prev">perlmodinstall HEY</a>, Up:
<a href="#perlmodinstall" accesskey="u" rel="up">perlmodinstall</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-17"></a>
-<h3 class="section">41.5 AUTHOR</h3>
-
-<p>Jon Orwant
-</p>
-<p>address@hidden
-</p>
-<p>with invaluable help from Chris Nandor, and valuable help from Brandon
-Allbery, Charles Bailey, Graham Barr, Dominic Dunlop, Jarkko
-Hietaniemi, Ben Holzman, Tom Horsley, Nick Ing-Simmons, Tuomas
-J. Lukka, Laszlo Molnar, Alan Olsen, Peter Prymmer, Gurusamy Sarathy,
-Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich.
-</p>
-<p>First version July 22, 1998; last revised November 21, 2001.
-</p>
-<hr>
-<a name="perlmodinstall-COPYRIGHT"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlmodinstall-AUTHOR" accesskey="p"
rel="prev">perlmodinstall AUTHOR</a>, Up: <a href="#perlmodinstall"
accesskey="u" rel="up">perlmodinstall</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="COPYRIGHT-2"></a>
-<h3 class="section">41.6 COPYRIGHT</h3>
-
-<p>Copyright (C) 1998, 2002, 2003 Jon Orwant. All Rights Reserved.
-</p>
-<p>This document may be distributed under the same terms as Perl itself.
-</p>
-<hr>
-<a name="perlmodstyle"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmroapi" accesskey="n" rel="next">perlmroapi</a>, Previous:
<a href="#perlmodinstall" accesskey="p" rel="prev">perlmodinstall</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlmodstyle-1"></a>
-<h2 class="chapter">42 perlmodstyle</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlmodstyle-NAME"
accesskey="1">perlmodstyle NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmodstyle-INTRODUCTION"
accesskey="2">perlmodstyle INTRODUCTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-QUICK-CHECKLIST" accesskey="3">perlmodstyle QUICK
CHECKLIST</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-BEFORE-YOU-START-WRITING-A-MODULE"
accesskey="4">perlmodstyle BEFORE YOU START WRITING A
MODULE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-DESIGNING-AND-WRITING-YOUR-MODULE"
accesskey="5">perlmodstyle DESIGNING AND WRITING YOUR
MODULE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-DOCUMENTING-YOUR-MODULE" accesskey="6">perlmodstyle
DOCUMENTING YOUR MODULE</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-RELEASE-CONSIDERATIONS" accesskey="7">perlmodstyle RELEASE
CONSIDERATIONS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-COMMON-PITFALLS" accesskey="8">perlmodstyle COMMON
PITFALLS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmodstyle-SEE-ALSO"
accesskey="9">perlmodstyle SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-AUTHOR">perlmodstyle
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlmodstyle-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-INTRODUCTION" accesskey="n"
rel="next">perlmodstyle INTRODUCTION</a>, Up: <a href="#perlmodstyle"
accesskey="u" rel="up">perlmodstyle</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-41"></a>
-<h3 class="section">42.1 NAME</h3>
-
-<p>perlmodstyle - Perl module style guide
-</p>
-<hr>
-<a name="perlmodstyle-INTRODUCTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-QUICK-CHECKLIST" accesskey="n"
rel="next">perlmodstyle QUICK CHECKLIST</a>, Previous: <a
href="#perlmodstyle-NAME" accesskey="p" rel="prev">perlmodstyle NAME</a>, Up:
<a href="#perlmodstyle" accesskey="u" rel="up">perlmodstyle</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="INTRODUCTION-1"></a>
-<h3 class="section">42.2 INTRODUCTION</h3>
-
-<p>This document attempts to describe the Perl Community’s "best
practice"
-for writing Perl modules. It extends the recommendations found in
-<a href="#perlstyle-NAME">perlstyle NAME</a> , which should be considered
required reading
-before reading this document.
-</p>
-<p>While this document is intended to be useful to all module authors, it is
-particularly aimed at authors who wish to publish their modules on CPAN.
-</p>
-<p>The focus is on elements of style which are visible to the users of a
-module, rather than those parts which are only seen by the module’s
-developers. However, many of the guidelines presented in this document
-can be extrapolated and applied successfully to a module’s internals.
-</p>
-<p>This document differs from <a href="#perlnewmod-NAME">perlnewmod NAME</a>
in that it is a style guide
-rather than a tutorial on creating CPAN modules. It provides a
-checklist against which modules can be compared to determine whether
-they conform to best practice, without necessarily describing in detail
-how to achieve this.
-</p>
-<p>All the advice contained in this document has been gleaned from
-extensive conversations with experienced CPAN authors and users. Every
-piece of advice given here is the result of previous mistakes. This
-information is here to help you avoid the same mistakes and the extra
-work that would inevitably be required to fix them.
-</p>
-<p>The first section of this document provides an itemized checklist;
-subsequent sections provide a more detailed discussion of the items on
-the list. The final section, "Common Pitfalls", describes some of
the
-most popular mistakes made by CPAN authors.
-</p>
-<hr>
-<a name="perlmodstyle-QUICK-CHECKLIST"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-BEFORE-YOU-START-WRITING-A-MODULE" accesskey="n"
rel="next">perlmodstyle BEFORE YOU START WRITING A MODULE</a>, Previous: <a
href="#perlmodstyle-INTRODUCTION" accesskey="p" rel="prev">perlmodstyle
INTRODUCTION</a>, Up: <a href="#perlmodstyle" accesskey="u"
rel="up">perlmodstyle</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="QUICK-CHECKLIST"></a>
-<h3 class="section">42.3 QUICK CHECKLIST</h3>
-
-<p>For more detail on each item in this checklist, see below.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Before-you-start" accesskey="1">perlmodstyle Before you
start</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmodstyle-The-API"
accesskey="2">perlmodstyle The API</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmodstyle-Stability"
accesskey="3">perlmodstyle Stability</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmodstyle-Documentation"
accesskey="4">perlmodstyle Documentation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Release-considerations" accesskey="5">perlmodstyle Release
considerations</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlmodstyle-Before-you-start"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-The-API" accesskey="n" rel="next">perlmodstyle
The API</a>, Up: <a href="#perlmodstyle-QUICK-CHECKLIST" accesskey="u"
rel="up">perlmodstyle QUICK CHECKLIST</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Before-you-start"></a>
-<h4 class="subsection">42.3.1 Before you start</h4>
-
-<ul>
-<li> Don’t re-invent the wheel
-
-</li><li> Patch, extend or subclass an existing module where possible
-
-</li><li> Do one thing and do it well
-
-</li><li> Choose an appropriate name
-
-</li><li> Get feedback before publishing
-
-</li></ul>
-
-<hr>
-<a name="perlmodstyle-The-API"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Stability" accesskey="n" rel="next">perlmodstyle
Stability</a>, Previous: <a href="#perlmodstyle-Before-you-start" accesskey="p"
rel="prev">perlmodstyle Before you start</a>, Up: <a
href="#perlmodstyle-QUICK-CHECKLIST" accesskey="u" rel="up">perlmodstyle QUICK
CHECKLIST</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-API"></a>
-<h4 class="subsection">42.3.2 The API</h4>
-
-<ul>
-<li> API should be understandable by the average programmer
-
-</li><li> Simple methods for simple tasks
-
-</li><li> Separate functionality from output
-
-</li><li> Consistent naming of subroutines or methods
-
-</li><li> Use named parameters (a hash or hashref) when there are more than two
-parameters
-
-</li></ul>
-
-<hr>
-<a name="perlmodstyle-Stability"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Documentation" accesskey="n"
rel="next">perlmodstyle Documentation</a>, Previous: <a
href="#perlmodstyle-The-API" accesskey="p" rel="prev">perlmodstyle The API</a>,
Up: <a href="#perlmodstyle-QUICK-CHECKLIST" accesskey="u" rel="up">perlmodstyle
QUICK CHECKLIST</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Stability"></a>
-<h4 class="subsection">42.3.3 Stability</h4>
-
-<ul>
-<li> Ensure your module works under <code>use strict</code> and <code>-w</code>
-
-</li><li> Stable modules should maintain backwards compatibility
-
-</li></ul>
-
-<hr>
-<a name="perlmodstyle-Documentation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Release-considerations" accesskey="n"
rel="next">perlmodstyle Release considerations</a>, Previous: <a
href="#perlmodstyle-Stability" accesskey="p" rel="prev">perlmodstyle
Stability</a>, Up: <a href="#perlmodstyle-QUICK-CHECKLIST" accesskey="u"
rel="up">perlmodstyle QUICK CHECKLIST</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Documentation"></a>
-<h4 class="subsection">42.3.4 Documentation</h4>
-
-<ul>
-<li> Write documentation in POD
-
-</li><li> Document purpose, scope and target applications
-
-</li><li> Document each publically accessible method or subroutine, including
params and return values
-
-</li><li> Give examples of use in your documentation
-
-</li><li> Provide a README file and perhaps also release notes, changelog, etc
-
-</li><li> Provide links to further information (URL, email)
-
-</li></ul>
-
-<hr>
-<a name="perlmodstyle-Release-considerations"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlmodstyle-Documentation" accesskey="p"
rel="prev">perlmodstyle Documentation</a>, Up: <a
href="#perlmodstyle-QUICK-CHECKLIST" accesskey="u" rel="up">perlmodstyle QUICK
CHECKLIST</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Release-considerations"></a>
-<h4 class="subsection">42.3.5 Release considerations</h4>
-
-<ul>
-<li> Specify pre-requisites in Makefile.PL or Build.PL
-
-</li><li> Specify Perl version requirements with <code>use</code>
-
-</li><li> Include tests with your module
-
-</li><li> Choose a sensible and consistent version numbering scheme (X.YY is
the common Perl module numbering scheme)
-
-</li><li> Increment the version number for every change, no matter how small
-
-</li><li> Package the module using "make dist"
-
-</li><li> Choose an appropriate license (GPL/Artistic is a good default)
-
-</li></ul>
-
-<hr>
-<a name="perlmodstyle-BEFORE-YOU-START-WRITING-A-MODULE"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-DESIGNING-AND-WRITING-YOUR-MODULE" accesskey="n"
rel="next">perlmodstyle DESIGNING AND WRITING YOUR MODULE</a>, Previous: <a
href="#perlmodstyle-QUICK-CHECKLIST" accesskey="p" rel="prev">perlmodstyle
QUICK CHECKLIST</a>, Up: <a href="#perlmodstyle" accesskey="u"
rel="up">perlmodstyle</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="BEFORE-YOU-START-WRITING-A-MODULE"></a>
-<h3 class="section">42.4 BEFORE YOU START WRITING A MODULE</h3>
-
-<p>Try not to launch headlong into developing your module without spending
-some time thinking first. A little forethought may save you a vast
-amount of effort later on.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Has-it-been-done-before_003f" accesskey="1">perlmodstyle
Has it been done before?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Do-one-thing-and-do-it-well" accesskey="2">perlmodstyle Do
one thing and do it well</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-What_0027s-in-a-name_003f" accesskey="3">perlmodstyle
What's in a name?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Get-feedback-before-publishing" accesskey="4">perlmodstyle
Get feedback before publishing</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlmodstyle-Has-it-been-done-before_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Do-one-thing-and-do-it-well" accesskey="n"
rel="next">perlmodstyle Do one thing and do it well</a>, Up: <a
href="#perlmodstyle-BEFORE-YOU-START-WRITING-A-MODULE" accesskey="u"
rel="up">perlmodstyle BEFORE YOU START WRITING A MODULE</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Has-it-been-done-before_003f"></a>
-<h4 class="subsection">42.4.1 Has it been done before?</h4>
-
-<p>You may not even need to write the module. Check whether it’s
already
-been done in Perl, and avoid re-inventing the wheel unless you have a
-good reason.
-</p>
-<p>Good places to look for pre-existing modules include
-<a href="http://search.cpan.org/";>http://search.cpan.org/</a> and <a
href="https://metacpan.org";>https://metacpan.org</a>
-and asking on <code>address@hidden</code>
-(<a
href="http://lists.perl.org/list/module-authors.html";>http://lists.perl.org/list/module-authors.html</a>).
-</p>
-<p>If an existing module <strong>almost</strong> does what you want, consider
writing a
-patch, writing a subclass, or otherwise extending the existing module
-rather than rewriting it.
-</p>
-<hr>
-<a name="perlmodstyle-Do-one-thing-and-do-it-well"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-What_0027s-in-a-name_003f" accesskey="n"
rel="next">perlmodstyle What's in a name?</a>, Previous: <a
href="#perlmodstyle-Has-it-been-done-before_003f" accesskey="p"
rel="prev">perlmodstyle Has it been done before?</a>, Up: <a
href="#perlmodstyle-BEFORE-YOU-START-WRITING-A-MODULE" accesskey="u"
rel="up">perlmodstyle BEFORE YOU START WRITING A MODULE</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Do-one-thing-and-do-it-well"></a>
-<h4 class="subsection">42.4.2 Do one thing and do it well</h4>
-
-<p>At the risk of stating the obvious, modules are intended to be modular.
-A Perl developer should be able to use modules to put together the
-building blocks of their application. However, it’s important that the
-blocks are the right shape, and that the developer shouldn’t have to use
-a big block when all they need is a small one.
-</p>
-<p>Your module should have a clearly defined scope which is no longer than
-a single sentence. Can your module be broken down into a family of
-related modules?
-</p>
-<p>Bad example:
-</p>
-<p>"FooBar.pm provides an implementation of the FOO protocol and the
-related BAR standard."
-</p>
-<p>Good example:
-</p>
-<p>"Foo.pm provides an implementation of the FOO protocol. Bar.pm
-implements the related BAR protocol."
-</p>
-<p>This means that if a developer only needs a module for the BAR standard,
-they should not be forced to install libraries for FOO as well.
-</p>
-<hr>
-<a name="perlmodstyle-What_0027s-in-a-name_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Get-feedback-before-publishing" accesskey="n"
rel="next">perlmodstyle Get feedback before publishing</a>, Previous: <a
href="#perlmodstyle-Do-one-thing-and-do-it-well" accesskey="p"
rel="prev">perlmodstyle Do one thing and do it well</a>, Up: <a
href="#perlmodstyle-BEFORE-YOU-START-WRITING-A-MODULE" accesskey="u"
rel="up">perlmodstyle BEFORE YOU START WRITING A MODULE</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="What_0027s-in-a-name_003f"></a>
-<h4 class="subsection">42.4.3 What’s in a name?</h4>
-
-<p>Make sure you choose an appropriate name for your module early on. This
-will help people find and remember your module, and make programming
-with your module more intuitive.
-</p>
-<p>When naming your module, consider the following:
-</p>
-<ul>
-<li> Be descriptive (i.e. accurately describes the purpose of the module).
-
-</li><li> Be consistent with existing modules.
-
-</li><li> Reflect the functionality of the module, not the implementation.
-
-</li><li> Avoid starting a new top-level hierarchy, especially if a suitable
-hierarchy already exists under which you could place your module.
-
-</li></ul>
-
-<hr>
-<a name="perlmodstyle-Get-feedback-before-publishing"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlmodstyle-What_0027s-in-a-name_003f" accesskey="p"
rel="prev">perlmodstyle What's in a name?</a>, Up: <a
href="#perlmodstyle-BEFORE-YOU-START-WRITING-A-MODULE" accesskey="u"
rel="up">perlmodstyle BEFORE YOU START WRITING A MODULE</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Get-feedback-before-publishing"></a>
-<h4 class="subsection">42.4.4 Get feedback before publishing</h4>
-
-<p>If you have never uploaded a module to CPAN before (and even if you have),
-you are strongly encouraged to get feedback on <a
href="http://prepan.org";>PrePAN</a>.
-PrePAN is a site dedicated to discussing ideas for CPAN modules with other
-Perl developers and is a great resource for new (and experienced) Perl
-developers.
-</p>
-<p>You should also try to get feedback from people who are already familiar
-with the module’s application domain and the CPAN naming system. Authors
-of similar modules, or modules with similar names, may be a good place to
-start, as are community sites like <a href="http://www.perlmonks.org";>Perl
Monks</a>.
-</p>
-<hr>
-<a name="perlmodstyle-DESIGNING-AND-WRITING-YOUR-MODULE"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-DOCUMENTING-YOUR-MODULE" accesskey="n"
rel="next">perlmodstyle DOCUMENTING YOUR MODULE</a>, Previous: <a
href="#perlmodstyle-BEFORE-YOU-START-WRITING-A-MODULE" accesskey="p"
rel="prev">perlmodstyle BEFORE YOU START WRITING A MODULE</a>, Up: <a
href="#perlmodstyle" accesskey="u" rel="up">perlmodstyle</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESIGNING-AND-WRITING-YOUR-MODULE"></a>
-<h3 class="section">42.5 DESIGNING AND WRITING YOUR MODULE</h3>
-
-<p>Considerations for module design and coding:
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-To-OO-or-not-to-OO_003f" accesskey="1">perlmodstyle To OO
or not to OO?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Designing-your-API" accesskey="2">perlmodstyle Designing
your API</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Strictness-and-warnings" accesskey="3">perlmodstyle
Strictness and warnings</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Backwards-compatibility" accesskey="4">perlmodstyle
Backwards compatibility</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Error-handling-and-messages" accesskey="5">perlmodstyle
Error handling and messages</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlmodstyle-To-OO-or-not-to-OO_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Designing-your-API" accesskey="n"
rel="next">perlmodstyle Designing your API</a>, Up: <a
href="#perlmodstyle-DESIGNING-AND-WRITING-YOUR-MODULE" accesskey="u"
rel="up">perlmodstyle DESIGNING AND WRITING YOUR MODULE</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="To-OO-or-not-to-OO_003f"></a>
-<h4 class="subsection">42.5.1 To OO or not to OO?</h4>
-
-<p>Your module may be object oriented (OO) or not, or it may have both kinds
-of interfaces available. There are pros and cons of each technique, which
-should be considered when you design your API.
-</p>
-<p>In <em>Perl Best Practices</em> (copyright 2004, Published by
O’Reilly Media, Inc.),
-Damian Conway provides a list of criteria to use when deciding if OO is the
-right fit for your problem:
-</p>
-<ul>
-<li> The system being designed is large, or is likely to become large.
-
-</li><li> The data can be aggregated into obvious structures, especially if
-there’s a large amount of data in each aggregate.
-
-</li><li> The various types of data aggregate form a natural hierarchy that
-facilitates the use of inheritance and polymorphism.
-
-</li><li> You have a piece of data on which many different operations are
-applied.
-
-</li><li> You need to perform the same general operations on related types of
-data, but with slight variations depending on the specific type of data
-the operations are applied to.
-
-</li><li> It’s likely you’ll have to add new data types later.
-
-</li><li> The typical interactions between pieces of data are best represented
by
-operators.
-
-</li><li> The implementation of individual components of the system is likely
to
-change over time.
-
-</li><li> The system design is already object-oriented.
-
-</li><li> Large numbers of other programmers will be using your code modules.
-
-</li></ul>
-
-<p>Think carefully about whether OO is appropriate for your module.
-Gratuitous object orientation results in complex APIs which are
-difficult for the average module user to understand or use.
-</p>
-<hr>
-<a name="perlmodstyle-Designing-your-API"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Strictness-and-warnings" accesskey="n"
rel="next">perlmodstyle Strictness and warnings</a>, Previous: <a
href="#perlmodstyle-To-OO-or-not-to-OO_003f" accesskey="p"
rel="prev">perlmodstyle To OO or not to OO?</a>, Up: <a
href="#perlmodstyle-DESIGNING-AND-WRITING-YOUR-MODULE" accesskey="u"
rel="up">perlmodstyle DESIGNING AND WRITING YOUR MODULE</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Designing-your-API"></a>
-<h4 class="subsection">42.5.2 Designing your API</h4>
-
-<p>Your interfaces should be understandable by an average Perl programmer.
-The following guidelines may help you judge whether your API is
-sufficiently straightforward:
-</p>
-<dl compact="compact">
-<dt>Write simple routines to do simple things.</dt>
-<dd><a name="perlmodstyle-Write-simple-routines-to-do-simple-things_002e"></a>
-<p>It’s better to have numerous simple routines than a few monolithic
ones.
-If your routine changes its behaviour significantly based on its
-arguments, it’s a sign that you should have two (or more) separate
-routines.
-</p>
-</dd>
-<dt>Separate functionality from output.</dt>
-<dd><a name="perlmodstyle-Separate-functionality-from-output_002e"></a>
-<p>Return your results in the most generic form possible and allow the user
-to choose how to use them. The most generic form possible is usually a
-Perl data structure which can then be used to generate a text report,
-HTML, XML, a database query, or whatever else your users require.
-</p>
-<p>If your routine iterates through some kind of list (such as a list of
-files, or records in a database) you may consider providing a callback
-so that users can manipulate each element of the list in turn.
-File::Find provides an example of this with its
-<code>find(\&wanted, $dir)</code> syntax.
-</p>
-</dd>
-<dt>Provide sensible shortcuts and defaults.</dt>
-<dd><a name="perlmodstyle-Provide-sensible-shortcuts-and-defaults_002e"></a>
-<p>Don’t require every module user to jump through the same hoops to
achieve a
-simple result. You can always include optional parameters or routines for
-more complex or non-standard behaviour. If most of your users have to
-type a few almost identical lines of code when they start using your
-module, it’s a sign that you should have made that behaviour a default.
-Another good indicator that you should use defaults is if most of your
-users call your routines with the same arguments.
-</p>
-</dd>
-<dt>Naming conventions</dt>
-<dd><a name="perlmodstyle-Naming-conventions"></a>
-<p>Your naming should be consistent. For instance, it’s better to have:
-</p>
-<pre class="verbatim"> display_day();
- display_week();
- display_year();
-</pre>
-<p>than
-</p>
-<pre class="verbatim"> display_day();
- week_display();
- show_year();
-</pre>
-<p>This applies equally to method names, parameter names, and anything else
-which is visible to the user (and most things that aren’t!)
-</p>
-</dd>
-<dt>Parameter passing</dt>
-<dd><a name="perlmodstyle-Parameter-passing"></a>
-<p>Use named parameters. It’s easier to use a hash like this:
-</p>
-<pre class="verbatim"> $obj->do_something(
- name => "wibble",
- type => "text",
- size => 1024,
- );
-</pre>
-<p>... than to have a long list of unnamed parameters like this:
-</p>
-<pre class="verbatim"> $obj->do_something("wibble",
"text", 1024);
-</pre>
-<p>While the list of arguments might work fine for one, two or even three
-arguments, any more arguments become hard for the module user to
-remember, and hard for the module author to manage. If you want to add
-a new parameter you will have to add it to the end of the list for
-backward compatibility, and this will probably make your list order
-unintuitive. Also, if many elements may be undefined you may see the
-following unattractive method calls:
-</p>
-<pre class="verbatim"> $obj->do_something(undef, undef, undef, undef,
undef, 1024);
-</pre>
-<p>Provide sensible defaults for parameters which have them. Don’t make
-your users specify parameters which will almost always be the same.
-</p>
-<p>The issue of whether to pass the arguments in a hash or a hashref is
-largely a matter of personal style.
-</p>
-<p>The use of hash keys starting with a hyphen (<code>-name</code>) or
entirely in
-upper case (<code>NAME</code>) is a relic of older versions of Perl in which
-ordinary lower case strings were not handled correctly by the
<code>=></code>
-operator. While some modules retain uppercase or hyphenated argument
-keys for historical reasons or as a matter of personal style, most new
-modules should use simple lower case keys. Whatever you choose, be
-consistent!
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlmodstyle-Strictness-and-warnings"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Backwards-compatibility" accesskey="n"
rel="next">perlmodstyle Backwards compatibility</a>, Previous: <a
href="#perlmodstyle-Designing-your-API" accesskey="p" rel="prev">perlmodstyle
Designing your API</a>, Up: <a
href="#perlmodstyle-DESIGNING-AND-WRITING-YOUR-MODULE" accesskey="u"
rel="up">perlmodstyle DESIGNING AND WRITING YOUR MODULE</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Strictness-and-warnings"></a>
-<h4 class="subsection">42.5.3 Strictness and warnings</h4>
-
-<p>Your module should run successfully under the strict pragma and should
-run without generating any warnings. Your module should also handle
-taint-checking where appropriate, though this can cause difficulties in
-many cases.
-</p>
-<hr>
-<a name="perlmodstyle-Backwards-compatibility"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Error-handling-and-messages" accesskey="n"
rel="next">perlmodstyle Error handling and messages</a>, Previous: <a
href="#perlmodstyle-Strictness-and-warnings" accesskey="p"
rel="prev">perlmodstyle Strictness and warnings</a>, Up: <a
href="#perlmodstyle-DESIGNING-AND-WRITING-YOUR-MODULE" accesskey="u"
rel="up">perlmodstyle DESIGNING AND WRITING YOUR MODULE</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Backwards-compatibility-2"></a>
-<h4 class="subsection">42.5.4 Backwards compatibility</h4>
-
-<p>Modules which are "stable" should not break backwards
compatibility
-without at least a long transition phase and a major change in version
-number.
-</p>
-<hr>
-<a name="perlmodstyle-Error-handling-and-messages"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlmodstyle-Backwards-compatibility" accesskey="p"
rel="prev">perlmodstyle Backwards compatibility</a>, Up: <a
href="#perlmodstyle-DESIGNING-AND-WRITING-YOUR-MODULE" accesskey="u"
rel="up">perlmodstyle DESIGNING AND WRITING YOUR MODULE</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Error-handling-and-messages"></a>
-<h4 class="subsection">42.5.5 Error handling and messages</h4>
-
-<p>When your module encounters an error it should do one or more of:
-</p>
-<ul>
-<li> Return an undefined value.
-
-</li><li> set <code>$Module::errstr</code> or similar (<code>errstr</code> is
a common name used by
-DBI and other popular modules; if you choose something else, be sure to
-document it clearly).
-
-</li><li> <code>warn()</code> or <code>carp()</code> a message to STDERR.
-
-</li><li> <code>croak()</code> only when your module absolutely cannot figure
out what to
-do. (<code>croak()</code> is a better version of <code>die()</code> for use
within
-modules, which reports its errors from the perspective of the caller.
-See <a href="Carp.html#Top">(Carp)</a> for details of <code>croak()</code>,
<code>carp()</code> and other useful
-routines.)
-
-</li><li> As an alternative to the above, you may prefer to throw exceptions
using
-the Error module.
-
-</li></ul>
-
-<p>Configurable error handling can be very useful to your users. Consider
-offering a choice of levels for warning and debug messages, an option to
-send messages to a separate file, a way to specify an error-handling
-routine, or other such features. Be sure to default all these options
-to the commonest use.
-</p>
-<hr>
-<a name="perlmodstyle-DOCUMENTING-YOUR-MODULE"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-RELEASE-CONSIDERATIONS" accesskey="n"
rel="next">perlmodstyle RELEASE CONSIDERATIONS</a>, Previous: <a
href="#perlmodstyle-DESIGNING-AND-WRITING-YOUR-MODULE" accesskey="p"
rel="prev">perlmodstyle DESIGNING AND WRITING YOUR MODULE</a>, Up: <a
href="#perlmodstyle" accesskey="u" rel="up">perlmodstyle</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DOCUMENTING-YOUR-MODULE"></a>
-<h3 class="section">42.6 DOCUMENTING YOUR MODULE</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlmodstyle-POD"
accesskey="1">perlmodstyle POD</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-README_002c-INSTALL_002c-release-notes_002c-changelogs"
accesskey="2">perlmodstyle README, INSTALL, release notes,
changelogs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlmodstyle-POD"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlmodstyle-README_002c-INSTALL_002c-release-notes_002c-changelogs"
accesskey="n" rel="next">perlmodstyle README, INSTALL, release notes,
changelogs</a>, Up: <a href="#perlmodstyle-DOCUMENTING-YOUR-MODULE"
accesskey="u" rel="up">perlmodstyle DOCUMENTING YOUR MODULE</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="POD"></a>
-<h4 class="subsection">42.6.1 POD</h4>
-
-<p>Your module should include documentation aimed at Perl developers.
-You should use Perl’s "plain old documentation" (POD) for your
general
-technical documentation, though you may wish to write additional
-documentation (white papers, tutorials, etc) in some other format.
-You need to cover the following subjects:
-</p>
-<ul>
-<li> A synopsis of the common uses of the module
-
-</li><li> The purpose, scope and target applications of your module
-
-</li><li> Use of each publically accessible method or subroutine, including
-parameters and return values
-
-</li><li> Examples of use
-
-</li><li> Sources of further information
-
-</li><li> A contact email address for the author/maintainer
-
-</li></ul>
-
-<p>The level of detail in Perl module documentation generally goes from
-less detailed to more detailed. Your SYNOPSIS section should contain a
-minimal example of use (perhaps as little as one line of code; skip the
-unusual use cases or anything not needed by most users); the
-DESCRIPTION should describe your module in broad terms, generally in
-just a few paragraphs; more detail of the module’s routines or methods,
-lengthy code examples, or other in-depth material should be given in
-subsequent sections.
-</p>
-<p>Ideally, someone who’s slightly familiar with your module should be
able
-to refresh their memory without hitting "page down". As your reader
-continues through the document, they should receive a progressively
-greater amount of knowledge.
-</p>
-<p>The recommended order of sections in Perl module documentation is:
-</p>
-<ul>
-<li> NAME
-
-</li><li> SYNOPSIS
-
-</li><li> DESCRIPTION
-
-</li><li> One or more sections or subsections giving greater detail of
available
-methods and routines and any other relevant information.
-
-</li><li> BUGS/CAVEATS/etc
-
-</li><li> AUTHOR
-
-</li><li> SEE ALSO
-
-</li><li> COPYRIGHT and LICENSE
-
-</li></ul>
-
-<p>Keep your documentation near the code it documents ("inline"
-documentation). Include POD for a given method right above that
-method’s subroutine. This makes it easier to keep the documentation up
-to date, and avoids having to document each piece of code twice (once in
-POD and once in comments).
-</p>
-<hr>
-<a
name="perlmodstyle-README_002c-INSTALL_002c-release-notes_002c-changelogs"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlmodstyle-POD" accesskey="p" rel="prev">perlmodstyle
POD</a>, Up: <a href="#perlmodstyle-DOCUMENTING-YOUR-MODULE" accesskey="u"
rel="up">perlmodstyle DOCUMENTING YOUR MODULE</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="README_002c-INSTALL_002c-release-notes_002c-changelogs"></a>
-<h4 class="subsection">42.6.2 README, INSTALL, release notes, changelogs</h4>
-
-<p>Your module should also include a README file describing the module and
-giving pointers to further information (website, author email).
-</p>
-<p>An INSTALL file should be included, and should contain simple installation
-instructions. When using ExtUtils::MakeMaker this will usually be:
-</p>
-<dl compact="compact">
-<dt>perl Makefile.PL</dt>
-<dd><a name="perlmodstyle-perl-Makefile_002ePL"></a>
-</dd>
-<dt>make</dt>
-<dd><a name="perlmodstyle-make"></a>
-</dd>
-<dt>make test</dt>
-<dd><a name="perlmodstyle-make-test"></a>
-</dd>
-<dt>make install</dt>
-<dd><a name="perlmodstyle-make-install"></a>
-</dd>
-</dl>
-
-<p>When using Module::Build, this will usually be:
-</p>
-<dl compact="compact">
-<dt>perl Build.PL</dt>
-<dd><a name="perlmodstyle-perl-Build_002ePL"></a>
-</dd>
-<dt>perl Build</dt>
-<dd><a name="perlmodstyle-perl-Build"></a>
-</dd>
-<dt>perl Build test</dt>
-<dd><a name="perlmodstyle-perl-Build-test"></a>
-</dd>
-<dt>perl Build install</dt>
-<dd><a name="perlmodstyle-perl-Build-install"></a>
-</dd>
-</dl>
-
-<p>Release notes or changelogs should be produced for each release of your
-software describing user-visible changes to your module, in terms
-relevant to the user.
-</p>
-<p>Unless you have good reasons for using some other format
-(for example, a format used within your company),
-the convention is to name your changelog file <code>Changes</code>,
-and to follow the simple format described in <a
href="CPAN-Changes-Spec.html#Top">(CPAN-Changes-Spec)</a>.
-</p>
-<hr>
-<a name="perlmodstyle-RELEASE-CONSIDERATIONS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-COMMON-PITFALLS" accesskey="n"
rel="next">perlmodstyle COMMON PITFALLS</a>, Previous: <a
href="#perlmodstyle-DOCUMENTING-YOUR-MODULE" accesskey="p"
rel="prev">perlmodstyle DOCUMENTING YOUR MODULE</a>, Up: <a
href="#perlmodstyle" accesskey="u" rel="up">perlmodstyle</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="RELEASE-CONSIDERATIONS"></a>
-<h3 class="section">42.7 RELEASE CONSIDERATIONS</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Version-numbering" accesskey="1">perlmodstyle Version
numbering</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Pre_002drequisites" accesskey="2">perlmodstyle
Pre-requisites</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmodstyle-Testing"
accesskey="3">perlmodstyle Testing</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmodstyle-Packaging"
accesskey="4">perlmodstyle Packaging</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmodstyle-Licensing"
accesskey="5">perlmodstyle Licensing</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlmodstyle-Version-numbering"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Pre_002drequisites" accesskey="n"
rel="next">perlmodstyle Pre-requisites</a>, Up: <a
href="#perlmodstyle-RELEASE-CONSIDERATIONS" accesskey="u" rel="up">perlmodstyle
RELEASE CONSIDERATIONS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Version-numbering"></a>
-<h4 class="subsection">42.7.1 Version numbering</h4>
-
-<p>Version numbers should indicate at least major and minor releases, and
-possibly sub-minor releases. A major release is one in which most of
-the functionality has changed, or in which major new functionality is
-added. A minor release is one in which a small amount of functionality
-has been added or changed. Sub-minor version numbers are usually used
-for changes which do not affect functionality, such as documentation
-patches.
-</p>
-<p>The most common CPAN version numbering scheme looks like this:
-</p>
-<pre class="verbatim"> 1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32
-</pre>
-<p>A correct CPAN version number is a floating point number with at least
-2 digits after the decimal. You can test whether it conforms to CPAN by
-using
-</p>
-<pre class="verbatim"> perl -MExtUtils::MakeMaker -le 'print
MM->parse_version(shift)' 'Foo.pm'
-</pre>
-<p>If you want to release a ’beta’ or ’alpha’ version
of a module but
-don’t want CPAN.pm to list it as most recent use an ’_’
after the
-regular version number followed by at least 2 digits, eg. 1.20_01. If
-you do this, the following idiom is recommended:
-</p>
-<pre class="verbatim"> our $VERSION = "1.12_01"; # so CPAN
distribution will have
- # right filename
- our $XS_VERSION = $VERSION; # only needed if you have XS code
- $VERSION = eval $VERSION; # so "use Module 0.002" won't warn on
- # underscore
-</pre>
-<p>With that trick MakeMaker will only read the first line and thus read
-the underscore, while the perl interpreter will evaluate the $VERSION
-and convert the string into a number. Later operations that treat
-$VERSION as a number will then be able to do so without provoking a
-warning about $VERSION not being a number.
-</p>
-<p>Never release anything (even a one-word documentation patch) without
-incrementing the number. Even a one-word documentation patch should
-result in a change in version at the sub-minor level.
-</p>
-<p>Once picked, it is important to stick to your version scheme, without
-reducing the number of digits. This is because "downstream"
packagers,
-such as the FreeBSD ports system, interpret the version numbers in
-various ways. If you change the number of digits in your version scheme,
-you can confuse these systems so they get the versions of your module
-out of order, which is obviously bad.
-</p>
-<hr>
-<a name="perlmodstyle-Pre_002drequisites"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Testing" accesskey="n" rel="next">perlmodstyle
Testing</a>, Previous: <a href="#perlmodstyle-Version-numbering" accesskey="p"
rel="prev">perlmodstyle Version numbering</a>, Up: <a
href="#perlmodstyle-RELEASE-CONSIDERATIONS" accesskey="u" rel="up">perlmodstyle
RELEASE CONSIDERATIONS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Pre_002drequisites"></a>
-<h4 class="subsection">42.7.2 Pre-requisites</h4>
-
-<p>Module authors should carefully consider whether to rely on other
-modules, and which modules to rely on.
-</p>
-<p>Most importantly, choose modules which are as stable as possible. In
-order of preference:
-</p>
-<ul>
-<li> Core Perl modules
-
-</li><li> Stable CPAN modules
-
-</li><li> Unstable CPAN modules
-
-</li><li> Modules not available from CPAN
-
-</li></ul>
-
-<p>Specify version requirements for other Perl modules in the
-pre-requisites in your Makefile.PL or Build.PL.
-</p>
-<p>Be sure to specify Perl version requirements both in Makefile.PL or
-Build.PL and with <code>require 5.6.1</code> or similar. See the section on
-<code>use VERSION</code> of <a href="#perlfunc-require">perlfunc require</a>
for details.
-</p>
-<hr>
-<a name="perlmodstyle-Testing"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Packaging" accesskey="n" rel="next">perlmodstyle
Packaging</a>, Previous: <a href="#perlmodstyle-Pre_002drequisites"
accesskey="p" rel="prev">perlmodstyle Pre-requisites</a>, Up: <a
href="#perlmodstyle-RELEASE-CONSIDERATIONS" accesskey="u" rel="up">perlmodstyle
RELEASE CONSIDERATIONS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Testing"></a>
-<h4 class="subsection">42.7.3 Testing</h4>
-
-<p>All modules should be tested before distribution (using "make
disttest"),
-and the tests should also be available to people installing the modules
-(using "make test").
-For Module::Build you would use the <code>make test</code> equivalent
<code>perl Build test</code>.
-</p>
-<p>The importance of these tests is proportional to the alleged stability of a
-module. A module which purports to be
-stable or which hopes to achieve wide
-use should adhere to as strict a testing regime as possible.
-</p>
-<p>Useful modules to help you write tests (with minimum impact on your
-development process or your time) include Test::Simple, Carp::Assert
-and Test::Inline.
-For more sophisticated test suites there are Test::More and Test::MockObject.
-</p>
-<hr>
-<a name="perlmodstyle-Packaging"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Licensing" accesskey="n" rel="next">perlmodstyle
Licensing</a>, Previous: <a href="#perlmodstyle-Testing" accesskey="p"
rel="prev">perlmodstyle Testing</a>, Up: <a
href="#perlmodstyle-RELEASE-CONSIDERATIONS" accesskey="u" rel="up">perlmodstyle
RELEASE CONSIDERATIONS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Packaging"></a>
-<h4 class="subsection">42.7.4 Packaging</h4>
-
-<p>Modules should be packaged using one of the standard packaging tools.
-Currently you have the choice between ExtUtils::MakeMaker and the
-more platform independent Module::Build, allowing modules to be installed in a
-consistent manner.
-When using ExtUtils::MakeMaker, you can use "make dist" to create
your
-package. Tools exist to help you to build your module in a
-MakeMaker-friendly style. These include ExtUtils::ModuleMaker and h2xs.
-See also <a href="#perlnewmod-NAME">perlnewmod NAME</a>.
-</p>
-<hr>
-<a name="perlmodstyle-Licensing"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlmodstyle-Packaging" accesskey="p"
rel="prev">perlmodstyle Packaging</a>, Up: <a
href="#perlmodstyle-RELEASE-CONSIDERATIONS" accesskey="u" rel="up">perlmodstyle
RELEASE CONSIDERATIONS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Licensing"></a>
-<h4 class="subsection">42.7.5 Licensing</h4>
-
-<p>Make sure that your module has a license, and that the full text of it
-is included in the distribution (unless it’s a common one and the terms
-of the license don’t require you to include it).
-</p>
-<p>If you don’t know what license to use, dual licensing under the GPL
-and Artistic licenses (the same as Perl itself) is a good idea.
-See <a href="#perlgpl-NAME">perlgpl NAME</a> and <a
href="#perlartistic-NAME">perlartistic NAME</a>.
-</p>
-<hr>
-<a name="perlmodstyle-COMMON-PITFALLS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-SEE-ALSO" accesskey="n" rel="next">perlmodstyle
SEE ALSO</a>, Previous: <a href="#perlmodstyle-RELEASE-CONSIDERATIONS"
accesskey="p" rel="prev">perlmodstyle RELEASE CONSIDERATIONS</a>, Up: <a
href="#perlmodstyle" accesskey="u" rel="up">perlmodstyle</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="COMMON-PITFALLS"></a>
-<h3 class="section">42.8 COMMON PITFALLS</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Reinventing-the-wheel" accesskey="1">perlmodstyle
Reinventing the wheel</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Trying-to-do-too-much" accesskey="2">perlmodstyle Trying to
do too much</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlmodstyle-Inappropriate-documentation" accesskey="3">perlmodstyle
Inappropriate documentation</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlmodstyle-Reinventing-the-wheel"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Trying-to-do-too-much" accesskey="n"
rel="next">perlmodstyle Trying to do too much</a>, Up: <a
href="#perlmodstyle-COMMON-PITFALLS" accesskey="u" rel="up">perlmodstyle COMMON
PITFALLS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Reinventing-the-wheel"></a>
-<h4 class="subsection">42.8.1 Reinventing the wheel</h4>
-
-<p>There are certain application spaces which are already very, very well
-served by CPAN. One example is templating systems, another is date and
-time modules, and there are many more. While it is a rite of passage to
-write your own version of these things, please consider carefully
-whether the Perl world really needs you to publish it.
-</p>
-<hr>
-<a name="perlmodstyle-Trying-to-do-too-much"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-Inappropriate-documentation" accesskey="n"
rel="next">perlmodstyle Inappropriate documentation</a>, Previous: <a
href="#perlmodstyle-Reinventing-the-wheel" accesskey="p"
rel="prev">perlmodstyle Reinventing the wheel</a>, Up: <a
href="#perlmodstyle-COMMON-PITFALLS" accesskey="u" rel="up">perlmodstyle COMMON
PITFALLS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Trying-to-do-too-much"></a>
-<h4 class="subsection">42.8.2 Trying to do too much</h4>
-
-<p>Your module will be part of a developer’s toolkit. It will not, in
-itself, form the <strong>entire</strong> toolkit. It’s tempting to add
extra features
-until your code is a monolithic system rather than a set of modular
-building blocks.
-</p>
-<hr>
-<a name="perlmodstyle-Inappropriate-documentation"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlmodstyle-Trying-to-do-too-much" accesskey="p"
rel="prev">perlmodstyle Trying to do too much</a>, Up: <a
href="#perlmodstyle-COMMON-PITFALLS" accesskey="u" rel="up">perlmodstyle COMMON
PITFALLS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Inappropriate-documentation"></a>
-<h4 class="subsection">42.8.3 Inappropriate documentation</h4>
-
-<p>Don’t fall into the trap of writing for the wrong audience. Your
-primary audience is a reasonably experienced developer with at least
-a moderate understanding of your module’s application domain,
who’s just
-downloaded your module and wants to start using it as quickly as possible.
-</p>
-<p>Tutorials, end-user documentation, research papers, FAQs etc are not
-appropriate in a module’s main documentation. If you really want to
-write these, include them as sub-documents such as
<code>My::Module::Tutorial</code> or
-<code>My::Module::FAQ</code> and provide a link in the SEE ALSO section of the
-main documentation.
-</p>
-<hr>
-<a name="perlmodstyle-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmodstyle-AUTHOR" accesskey="n" rel="next">perlmodstyle
AUTHOR</a>, Previous: <a href="#perlmodstyle-COMMON-PITFALLS" accesskey="p"
rel="prev">perlmodstyle COMMON PITFALLS</a>, Up: <a href="#perlmodstyle"
accesskey="u" rel="up">perlmodstyle</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-20"></a>
-<h3 class="section">42.9 SEE ALSO</h3>
-
-<dl compact="compact">
-<dt><a href="#perlstyle-NAME">perlstyle NAME</a></dt>
-<dd><a name="perlmodstyle-perlstyle-NAME"></a>
-<p>General Perl style guide
-</p>
-</dd>
-<dt><a href="#perlnewmod-NAME">perlnewmod NAME</a></dt>
-<dd><a name="perlmodstyle-perlnewmod-NAME"></a>
-<p>How to create a new module
-</p>
-</dd>
-<dt><a href="#perlpod-NAME">perlpod NAME</a></dt>
-<dd><a name="perlmodstyle-perlpod-NAME"></a>
-<p>POD documentation
-</p>
-</dd>
-<dt><a href="podchecker.html#Top">(podchecker)</a></dt>
-<dd><a name="perlmodstyle-podchecker"></a>
-<p>Verifies your POD’s correctness
-</p>
-</dd>
-<dt>Packaging Tools</dt>
-<dd><a name="perlmodstyle-Packaging-Tools"></a>
-<p><a href="ExtUtils-MakeMaker.html#Top">(ExtUtils-MakeMaker)</a>, <a
href="Module-Build.html#Top">(Module-Build)</a>
-</p>
-</dd>
-<dt>Testing tools</dt>
-<dd><a name="perlmodstyle-Testing-tools"></a>
-<p><a href="Test-Simple.html#Top">(Test-Simple)</a>, <a
href="Test-Inline.html#Top">(Test-Inline)</a>, <a
href="Carp-Assert.html#Top">(Carp-Assert)</a>, <a
href="Test-More.html#Top">(Test-More)</a>, <a
href="Test-MockObject.html#Top">(Test-MockObject)</a>
-</p>
-</dd>
-<dt>http://pause.perl.org/</dt>
-<dd><a name="perlmodstyle-http_003a_002f_002fpause_002eperl_002eorg_002f"></a>
-<p>Perl Authors Upload Server. Contains links to information for module
-authors.
-</p>
-</dd>
-<dt>Any good book on software engineering</dt>
-<dd><a name="perlmodstyle-Any-good-book-on-software-engineering"></a>
-</dd>
-</dl>
-
-<hr>
-<a name="perlmodstyle-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlmodstyle-SEE-ALSO" accesskey="p"
rel="prev">perlmodstyle SEE ALSO</a>, Up: <a href="#perlmodstyle" accesskey="u"
rel="up">perlmodstyle</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-18"></a>
-<h3 class="section">42.10 AUTHOR</h3>
-
-<p>Kirrily "Skud" Robert <address@hidden>
-</p>
-<hr>
-<a name="perlmroapi"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnewmod" accesskey="n" rel="next">perlnewmod</a>, Previous:
<a href="#perlmodstyle" accesskey="p" rel="prev">perlmodstyle</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlmroapi-1"></a>
-<h2 class="chapter">43 perlmroapi</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlmroapi-NAME"
accesskey="1">perlmroapi NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmroapi-DESCRIPTION"
accesskey="2">perlmroapi DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmroapi-Callbacks"
accesskey="3">perlmroapi Callbacks</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmroapi-Caching"
accesskey="4">perlmroapi Caching</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmroapi-Examples"
accesskey="5">perlmroapi Examples</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlmroapi-AUTHORS"
accesskey="6">perlmroapi AUTHORS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlmroapi-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmroapi-DESCRIPTION" accesskey="n" rel="next">perlmroapi
DESCRIPTION</a>, Up: <a href="#perlmroapi" accesskey="u"
rel="up">perlmroapi</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-42"></a>
-<h3 class="section">43.1 NAME</h3>
-
-<p>perlmroapi - Perl method resolution plugin interface
-</p>
-<hr>
-<a name="perlmroapi-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmroapi-Callbacks" accesskey="n" rel="next">perlmroapi
Callbacks</a>, Previous: <a href="#perlmroapi-NAME" accesskey="p"
rel="prev">perlmroapi NAME</a>, Up: <a href="#perlmroapi" accesskey="u"
rel="up">perlmroapi</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-41"></a>
-<h3 class="section">43.2 DESCRIPTION</h3>
-
-<p>As of Perl 5.10.1 there is a new interface for plugging and using method
-resolution orders other than the default (linear depth first search).
-The C3 method resolution order added in 5.10.0 has been re-implemented as
-a plugin, without changing its Perl-space interface.
-</p>
-<p>Each plugin should register itself by providing
-the following structure
-</p>
-<pre class="verbatim"> struct mro_alg {
- AV *(*resolve)(pTHX_ HV *stash, U32 level);
- const char *name;
- U16 length;
- U16 kflags;
- U32 hash;
- };
-</pre>
-<p>and calling <code>Perl_mro_register</code>:
-</p>
-<pre class="verbatim"> Perl_mro_register(aTHX_ &my_mro_alg);
-</pre>
-<dl compact="compact">
-<dt>resolve</dt>
-<dd><a name="perlmroapi-resolve"></a>
-<p>Pointer to the linearisation function, described below.
-</p>
-</dd>
-<dt>name</dt>
-<dd><a name="perlmroapi-name"></a>
-<p>Name of the MRO, either in ISO-8859-1 or UTF-8.
-</p>
-</dd>
-<dt>length</dt>
-<dd><a name="perlmroapi-length"></a>
-<p>Length of the name.
-</p>
-</dd>
-<dt>kflags</dt>
-<dd><a name="perlmroapi-kflags"></a>
-<p>If the name is given in UTF-8, set this to <code>HVhek_UTF8</code>. The
value is passed
-direct as the parameter <em>kflags</em> to <code>hv_common()</code>.
-</p>
-</dd>
-<dt>hash</dt>
-<dd><a name="perlmroapi-hash"></a>
-<p>A precomputed hash value for the MRO’s name, or 0.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlmroapi-Callbacks"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmroapi-Caching" accesskey="n" rel="next">perlmroapi
Caching</a>, Previous: <a href="#perlmroapi-DESCRIPTION" accesskey="p"
rel="prev">perlmroapi DESCRIPTION</a>, Up: <a href="#perlmroapi" accesskey="u"
rel="up">perlmroapi</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Callbacks"></a>
-<h3 class="section">43.3 Callbacks</h3>
-
-<p>The <code>resolve</code> function is called to generate a linearised ISA
for the
-given stash, using this MRO. It is called with a pointer to the stash, and
-a <em>level</em> of 0. The core always sets <em>level</em> to 0 when it calls
your
-function - the parameter is provided to allow your implementation to track
-depth if it needs to recurse.
-</p>
-<p>The function should return a reference to an array containing the parent
-classes in order. The names of the classes should be the result of calling
-<code>HvENAME()</code> on the stash. In those cases where
<code>HvENAME()</code> returns null,
-<code>HvNAME()</code> should be used instead.
-</p>
-<p>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, <code>sv_2mortal()</code> 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.
-</p>
-<hr>
-<a name="perlmroapi-Caching"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmroapi-Examples" accesskey="n" rel="next">perlmroapi
Examples</a>, Previous: <a href="#perlmroapi-Callbacks" accesskey="p"
rel="prev">perlmroapi Callbacks</a>, Up: <a href="#perlmroapi" accesskey="u"
rel="up">perlmroapi</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Caching"></a>
-<h3 class="section">43.4 Caching</h3>
-
-<p>Computing MROs can be expensive. The implementation provides a cache, in
-which you can store a single <code>SV *</code>, or anything that can be cast to
-<code>SV *</code>, such as <code>AV *</code>. To read your private value, use
the macro
-<code>MRO_GET_PRIVATE_DATA()</code>, passing it the <code>mro_meta</code>
structure from the
-stash, and a pointer to your <code>mro_alg</code> structure:
-</p>
-<pre class="verbatim"> meta = HvMROMETA(stash);
- private_sv = MRO_GET_PRIVATE_DATA(meta, &my_mro_alg);
-</pre>
-<p>To set your private value, call <code>Perl_mro_set_private_data()</code>:
-</p>
-<pre class="verbatim"> Perl_mro_set_private_data(aTHX_ meta, &c3_alg,
private_sv);
-</pre>
-<p>The private data cache will take ownership of a reference to private_sv,
-much the same way that <code>hv_store()</code> takes ownership of a reference
to the
-value that you pass it.
-</p>
-<hr>
-<a name="perlmroapi-Examples"></a>
-<div class="header">
-<p>
-Next: <a href="#perlmroapi-AUTHORS" accesskey="n" rel="next">perlmroapi
AUTHORS</a>, Previous: <a href="#perlmroapi-Caching" accesskey="p"
rel="prev">perlmroapi Caching</a>, Up: <a href="#perlmroapi" accesskey="u"
rel="up">perlmroapi</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Examples-1"></a>
-<h3 class="section">43.5 Examples</h3>
-
-<p>For examples of MRO implementations, see
<code>S_mro_get_linear_isa_c3()</code>
-and the <code>BOOT:</code> section of <samp>mro/mro.xs</samp>, and
<code>S_mro_get_linear_isa_dfs()</code>
-in <samp>mro.c</samp>
-</p>
-<hr>
-<a name="perlmroapi-AUTHORS"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlmroapi-Examples" accesskey="p" rel="prev">perlmroapi
Examples</a>, Up: <a href="#perlmroapi" accesskey="u" rel="up">perlmroapi</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHORS-3"></a>
-<h3 class="section">43.6 AUTHORS</h3>
-
-<p>The implementation of the C3 MRO and switchable MROs within the perl core
was
-written by Brandon L Black. Nicholas Clark created the pluggable interface,
-refactored Brandon’s implementation to work with it, and wrote this
document.
-</p>
-<hr>
-<a name="perlnewmod"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnumber" accesskey="n" rel="next">perlnumber</a>, Previous:
<a href="#perlmroapi" accesskey="p" rel="prev">perlmroapi</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlnewmod-1"></a>
-<h2 class="chapter">44 perlnewmod</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlnewmod-NAME"
accesskey="1">perlnewmod NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlnewmod-DESCRIPTION"
accesskey="2">perlnewmod DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlnewmod-AUTHOR"
accesskey="3">perlnewmod AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlnewmod-SEE-ALSO"
accesskey="4">perlnewmod SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlnewmod-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnewmod-DESCRIPTION" accesskey="n" rel="next">perlnewmod
DESCRIPTION</a>, Up: <a href="#perlnewmod" accesskey="u"
rel="up">perlnewmod</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-43"></a>
-<h3 class="section">44.1 NAME</h3>
-
-<p>perlnewmod - preparing a new module for distribution
-</p>
-<hr>
-<a name="perlnewmod-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnewmod-AUTHOR" accesskey="n" rel="next">perlnewmod
AUTHOR</a>, Previous: <a href="#perlnewmod-NAME" accesskey="p"
rel="prev">perlnewmod NAME</a>, Up: <a href="#perlnewmod" accesskey="u"
rel="up">perlnewmod</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-42"></a>
-<h3 class="section">44.2 DESCRIPTION</h3>
-
-<p>This document gives you some suggestions about how to go about writing
-Perl modules, preparing them for distribution, and making them available
-via CPAN.
-</p>
-<p>One of the things that makes Perl really powerful is the fact that Perl
-hackers tend to want to share the solutions to problems they’ve faced,
-so you and I don’t have to battle with the same problem again.
-</p>
-<p>The main way they do this is by abstracting the solution into a Perl
-module. If you don’t know what one of these is, the rest of this
-document isn’t going to be much use to you. You’re also missing
out on
-an awful lot of useful code; consider having a look at <a
href="#perlmod-NAME">perlmod NAME</a>,
-<a href="perlmodlib.html#Top">(perlmodlib)</a> and <a
href="#perlmodinstall-NAME">perlmodinstall NAME</a> before coming back here.
-</p>
-<p>When you’ve found that there isn’t a module available for what
you’re
-trying to do, and you’ve had to write the code yourself, consider
-packaging up the solution into a module and uploading it to CPAN so that
-others can benefit.
-</p>
-<p>You should also take a look at <a href="#perlmodstyle-NAME">perlmodstyle
NAME</a> for best practices in
-making a module.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlnewmod-Warning"
accesskey="1">perlnewmod Warning</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnewmod-What-should-I-make-into-a-module_003f"
accesskey="2">perlnewmod What should I make into a
module?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnewmod-Step_002dby_002dstep_003a-Preparing-the-ground"
accesskey="3">perlnewmod Step-by-step: Preparing the
ground</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnewmod-Step_002dby_002dstep_003a-Making-the-module"
accesskey="4">perlnewmod Step-by-step: Making the
module</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnewmod-Step_002dby_002dstep_003a-Distributing-your-module"
accesskey="5">perlnewmod Step-by-step: Distributing your
module</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlnewmod-Warning"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnewmod-What-should-I-make-into-a-module_003f"
accesskey="n" rel="next">perlnewmod What should I make into a module?</a>, Up:
<a href="#perlnewmod-DESCRIPTION" accesskey="u" rel="up">perlnewmod
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Warning"></a>
-<h4 class="subsection">44.2.1 Warning</h4>
-
-<p>We’re going to primarily concentrate on Perl-only modules here, rather
-than XS modules. XS modules serve a rather different purpose, and
-you should consider different things before distributing them - the
-popularity of the library you are gluing, the portability to other
-operating systems, and so on. However, the notes on preparing the Perl
-side of the module and packaging and distributing it will apply equally
-well to an XS module as a pure-Perl one.
-</p>
-<hr>
-<a name="perlnewmod-What-should-I-make-into-a-module_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnewmod-Step_002dby_002dstep_003a-Preparing-the-ground"
accesskey="n" rel="next">perlnewmod Step-by-step: Preparing the ground</a>,
Previous: <a href="#perlnewmod-Warning" accesskey="p" rel="prev">perlnewmod
Warning</a>, Up: <a href="#perlnewmod-DESCRIPTION" accesskey="u"
rel="up">perlnewmod DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="What-should-I-make-into-a-module_003f"></a>
-<h4 class="subsection">44.2.2 What should I make into a module?</h4>
-
-<p>You should make a module out of any code that you think is going to be
-useful to others. Anything that’s likely to fill a hole in the communal
-library and which someone else can slot directly into their program. Any
-part of your code which you can isolate and extract and plug into
-something else is a likely candidate.
-</p>
-<p>Let’s take an example. Suppose you’re reading in data from a
local
-format into a hash-of-hashes in Perl, turning that into a tree, walking
-the tree and then piping each node to an Acme Transmogrifier Server.
-</p>
-<p>Now, quite a few people have the Acme Transmogrifier, and you’ve had
to
-write something to talk the protocol from scratch - you’d almost
-certainly want to make that into a module. The level at which you pitch
-it is up to you: you might want protocol-level modules analogous to
-<a href="Net-SMTP.html#Top">(Net-SMTP)Net::SMTP</a> which then talk to higher
level modules analogous
-to <a href="Mail-Send.html#Top">(Mail-Send)Mail::Send</a>. The choice is
yours, but you do want to get
-a module out for that server protocol.
-</p>
-<p>Nobody else on the planet is going to talk your local data format, so we
-can ignore that. But what about the thing in the middle? Building tree
-structures from Perl variables and then traversing them is a nice,
-general problem, and if nobody’s already written a module that does
-that, you might want to modularise that code too.
-</p>
-<p>So hopefully you’ve now got a few ideas about what’s good to
modularise.
-Let’s now see how it’s done.
-</p>
-<hr>
-<a name="perlnewmod-Step_002dby_002dstep_003a-Preparing-the-ground"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnewmod-Step_002dby_002dstep_003a-Making-the-module"
accesskey="n" rel="next">perlnewmod Step-by-step: Making the module</a>,
Previous: <a href="#perlnewmod-What-should-I-make-into-a-module_003f"
accesskey="p" rel="prev">perlnewmod What should I make into a module?</a>, Up:
<a href="#perlnewmod-DESCRIPTION" accesskey="u" rel="up">perlnewmod
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Step_002dby_002dstep_003a-Preparing-the-ground"></a>
-<h4 class="subsection">44.2.3 Step-by-step: Preparing the ground</h4>
-
-<p>Before we even start scraping out the code, there are a few things
we’ll
-want to do in advance.
-</p>
-<dl compact="compact">
-<dt>Look around</dt>
-<dd><a name="perlnewmod-Look-around"></a>
-<p>Dig into a bunch of modules to see how they’re written. I’d
suggest
-starting with <a href="Text-Tabs.html#Top">(Text-Tabs)Text::Tabs</a>, since
it’s in the standard
-library and is nice and simple, and then looking at something a little
-more complex like <a href="File-Copy.html#Top">(File-Copy)File::Copy</a>. For
object oriented
-code, <code>WWW::Mechanize</code> or the <code>Email::*</code> modules provide
some good
-examples.
-</p>
-<p>These should give you an overall feel for how modules are laid out and
-written.
-</p>
-</dd>
-<dt>Check it’s new</dt>
-<dd><a name="perlnewmod-Check-it_0027s-new"></a>
-<p>There are a lot of modules on CPAN, and it’s easy to miss one
that’s
-similar to what you’re planning on contributing. Have a good plough
-through the <a href="http://search.cpan.org";>http://search.cpan.org</a> and
make sure you’re not the one
-reinventing the wheel!
-</p>
-</dd>
-<dt>Discuss the need</dt>
-<dd><a name="perlnewmod-Discuss-the-need"></a>
-<p>You might love it. You might feel that everyone else needs it. But there
-might not actually be any real demand for it out there. If you’re unsure
-about the demand your module will have, consider sending out feelers
-on the <code>comp.lang.perl.modules</code> newsgroup, or as a last resort, ask
the
-modules list at <code>address@hidden</code>. Remember that this is a closed
list
-with a very long turn-around time - be prepared to wait a good while for
-a response from them.
-</p>
-</dd>
-<dt>Choose a name</dt>
-<dd><a name="perlnewmod-Choose-a-name"></a>
-<p>Perl modules included on CPAN have a naming hierarchy you should try to
-fit in with. See <a href="perlmodlib.html#Top">(perlmodlib)</a> for more
details on how this works, and
-browse around CPAN and the modules list to get a feel of it. At the very
-least, remember this: modules should be title capitalised, (This::Thing)
-fit in with a category, and explain their purpose succinctly.
-</p>
-</dd>
-<dt>Check again</dt>
-<dd><a name="perlnewmod-Check-again"></a>
-<p>While you’re doing that, make really sure you haven’t missed a
module
-similar to the one you’re about to write.
-</p>
-<p>When you’ve got your name sorted out and you’re sure that your
module is
-wanted and not currently available, it’s time to start coding.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlnewmod-Step_002dby_002dstep_003a-Making-the-module"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnewmod-Step_002dby_002dstep_003a-Distributing-your-module"
accesskey="n" rel="next">perlnewmod Step-by-step: Distributing your module</a>,
Previous: <a href="#perlnewmod-Step_002dby_002dstep_003a-Preparing-the-ground"
accesskey="p" rel="prev">perlnewmod Step-by-step: Preparing the ground</a>, Up:
<a href="#perlnewmod-DESCRIPTION" accesskey="u" rel="up">perlnewmod
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Step_002dby_002dstep_003a-Making-the-module"></a>
-<h4 class="subsection">44.2.4 Step-by-step: Making the module</h4>
-
-<dl compact="compact">
-<dt>Start with <samp>module-starter</samp> or <samp>h2xs</samp></dt>
-<dd><a name="perlnewmod-Start-with-module_002dstarter-or-h2xs"></a>
-<p>The <samp>module-starter</samp> utility is distributed as part of the
-<a href="Module-Starter.html#Top">(Module-Starter)Module::Starter</a> CPAN
package. It creates a directory
-with stubs of all the necessary files to start a new module, according
-to recent "best practice" for module development, and is invoked from
-the command line, thus:
-</p>
-<pre class="verbatim"> module-starter --module=Foo::Bar \
- --author="Your Name" address@hidden
-</pre>
-<p>If you do not wish to install the <a
href="Module-Starter.html#Top">(Module-Starter)Module::Starter</a>
-package from CPAN, <samp>h2xs</samp> is an older tool, originally intended for
the
-development of XS modules, which comes packaged with the Perl
-distribution.
-</p>
-<p>A typical invocation of <a href="h2xs.html#Top">(h2xs)h2xs</a> for a pure
Perl module is:
-</p>
-<pre class="verbatim"> h2xs -AX --skip-exporter --use-new-tests -n Foo::Bar
-</pre>
-<p>The <code>-A</code> omits the Autoloader code, <code>-X</code> omits XS
elements,
-<code>--skip-exporter</code> omits the Exporter code,
<code>--use-new-tests</code> sets up a
-modern testing environment, and <code>-n</code> specifies the name of the
module.
-</p>
-</dd>
-<dt>Use <a href="strict.html#Top">(strict)strict</a> and <a
href="warnings.html#Top">(warnings)warnings</a></dt>
-<dd><a name="perlnewmod-Use-strict-and-warnings"></a>
-<p>A module’s code has to be warning and strict-clean, since you
can’t
-guarantee the conditions that it’ll be used under. Besides, you
wouldn’t
-want to distribute code that wasn’t warning or strict-clean anyway,
-right?
-</p>
-</dd>
-<dt>Use <a href="Carp.html#Top">(Carp)Carp</a></dt>
-<dd><a name="perlnewmod-Use-Carp"></a>
-<p>The <a href="Carp.html#Top">(Carp)Carp</a> module allows you to present
your error messages from
-the caller’s perspective; this gives you a way to signal a problem with
-the caller and not your module. For instance, if you say this:
-</p>
-<pre class="verbatim"> warn "No hostname given";
-</pre>
-<p>the user will see something like this:
-</p>
-<pre class="verbatim"> No hostname given at
/usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm
- line 123.
-</pre>
-<p>which looks like your module is doing something wrong. Instead, you want
-to put the blame on the user, and say this:
-</p>
-<pre class="verbatim"> No hostname given at bad_code, line 10.
-</pre>
-<p>You do this by using <a href="Carp.html#Top">(Carp)Carp</a> and replacing
your <code>warn</code>s with
-<code>carp</code>s. If you need to <code>die</code>, say <code>croak</code>
instead. However, keep
-<code>warn</code> and <code>die</code> in place for your sanity checks - where
it really is
-your module at fault.
-</p>
-</dd>
-<dt>Use <a href="Exporter.html#Top">(Exporter)Exporter</a> - wisely!</dt>
-<dd><a name="perlnewmod-Use-Exporter-_002d-wisely_0021"></a>
-<p><a href="Exporter.html#Top">(Exporter)Exporter</a> gives you a standard way
of exporting symbols and
-subroutines from your module into the caller’s namespace. For instance,
-saying <code>use Net::Acme qw(&frob)</code> would import the
<code>frob</code> subroutine.
-</p>
-<p>The package variable <code>@EXPORT</code> will determine which symbols will
get
-exported when the caller simply says <code>use Net::Acme</code> - you will
hardly
-ever want to put anything in there. <code>@EXPORT_OK</code>, on the other hand,
-specifies which symbols you’re willing to export. If you do want to
-export a bunch of symbols, use the <code>%EXPORT_TAGS</code> and define a
standard
-export set - look at <a href="Exporter.html#Top">(Exporter)</a> for more
details.
-</p>
-</dd>
-<dt>Use <a href="#perlpod-NAME">plain old documentation</a></dt>
-<dd><a name="perlnewmod-Use-perlpod-NAME"></a>
-<p>The work isn’t over until the paperwork is done, and you’re
going to
-need to put in some time writing some documentation for your module.
-<code>module-starter</code> or <code>h2xs</code> will provide a stub for you
to fill in; if
-you’re not sure about the format, look at <a
href="#perlpod-NAME">perlpod NAME</a> for an
-introduction. Provide a good synopsis of how your module is used in
-code, a description, and then notes on the syntax and function of the
-individual subroutines or methods. Use Perl comments for developer notes
-and POD for end-user notes.
-</p>
-</dd>
-<dt>Write tests</dt>
-<dd><a name="perlnewmod-Write-tests"></a>
-<p>You’re encouraged to create self-tests for your module to ensure
it’s
-working as intended on the myriad platforms Perl supports; if you upload
-your module to CPAN, a host of testers will build your module and send
-you the results of the tests. Again, <code>module-starter</code> and
<code>h2xs</code>
-provide a test framework which you can extend - you should do something
-more than just checking your module will compile.
-<a href="Test-Simple.html#Top">(Test-Simple)Test::Simple</a> and <a
href="Test-More.html#Top">(Test-More)Test::More</a> are good
-places to start when writing a test suite.
-</p>
-</dd>
-<dt>Write the README</dt>
-<dd><a name="perlnewmod-Write-the-README"></a>
-<p>If you’re uploading to CPAN, the automated gremlins will extract the
-README file and place that in your CPAN directory. It’ll also appear in
-the main <samp>by-module</samp> and <samp>by-category</samp> directories if
you make it onto
-the modules list. It’s a good idea to put here what the module actually
-does in detail, and the user-visible changes since the last release.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlnewmod-Step_002dby_002dstep_003a-Distributing-your-module"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlnewmod-Step_002dby_002dstep_003a-Making-the-module"
accesskey="p" rel="prev">perlnewmod Step-by-step: Making the module</a>, Up: <a
href="#perlnewmod-DESCRIPTION" accesskey="u" rel="up">perlnewmod
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Step_002dby_002dstep_003a-Distributing-your-module"></a>
-<h4 class="subsection">44.2.5 Step-by-step: Distributing your module</h4>
-
-<dl compact="compact">
-<dt>Get a CPAN user ID</dt>
-<dd><a name="perlnewmod-Get-a-CPAN-user-ID"></a>
-<p>Every developer publishing modules on CPAN needs a CPAN ID. Visit
-<code>http://pause.perl.org/</code>, select "Request PAUSE Account",
and wait for
-your request to be approved by the PAUSE administrators.
-</p>
-</dd>
-<dt><code>perl Makefile.PL; make test; make dist</code></dt>
-<dd><a
name="perlnewmod-perl-Makefile_002ePL_003b-make-test_003b-make-dist"></a>
-<p>Once again, <code>module-starter</code> or <code>h2xs</code> has done all
the work for you.
-They produce the standard <code>Makefile.PL</code> you see when you download
and
-install modules, and this produces a Makefile with a <code>dist</code> target.
-</p>
-<p>Once you’ve ensured that your module passes its own tests - always a
-good thing to make sure - you can <code>make dist</code>, and the Makefile will
-hopefully produce you a nice tarball of your module, ready for upload.
-</p>
-</dd>
-<dt>Upload the tarball</dt>
-<dd><a name="perlnewmod-Upload-the-tarball"></a>
-<p>The email you got when you received your CPAN ID will tell you how to
-log in to PAUSE, the Perl Authors Upload SErver. From the menus there,
-you can upload your module to CPAN.
-</p>
-</dd>
-<dt>Announce to the modules list</dt>
-<dd><a name="perlnewmod-Announce-to-the-modules-list"></a>
-<p>Once uploaded, it’ll sit unnoticed in your author directory. If you
want
-it connected to the rest of the CPAN, you’ll need to go to "Register
-Namespace" on PAUSE. Once registered, your module will appear in the
-by-module and by-category listings on CPAN.
-</p>
-</dd>
-<dt>Announce to clpa</dt>
-<dd><a name="perlnewmod-Announce-to-clpa"></a>
-<p>If you have a burning desire to tell the world about your release, post
-an announcement to the moderated <code>comp.lang.perl.announce</code>
newsgroup.
-</p>
-</dd>
-<dt>Fix bugs!</dt>
-<dd><a name="perlnewmod-Fix-bugs_0021"></a>
-<p>Once you start accumulating users, they’ll send you bug reports. If
-you’re lucky, they’ll even send you patches. Welcome to the joys of
-maintaining a software project...
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlnewmod-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnewmod-SEE-ALSO" accesskey="n" rel="next">perlnewmod SEE
ALSO</a>, Previous: <a href="#perlnewmod-DESCRIPTION" accesskey="p"
rel="prev">perlnewmod DESCRIPTION</a>, Up: <a href="#perlnewmod" accesskey="u"
rel="up">perlnewmod</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-19"></a>
-<h3 class="section">44.3 AUTHOR</h3>
-
-<p>Simon Cozens, <code>address@hidden</code>
-</p>
-<p>Updated by Kirrily "Skud" Robert, <code>address@hidden</code>
-</p>
-<hr>
-<a name="perlnewmod-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlnewmod-AUTHOR" accesskey="p" rel="prev">perlnewmod
AUTHOR</a>, Up: <a href="#perlnewmod" accesskey="u" rel="up">perlnewmod</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-21"></a>
-<h3 class="section">44.4 SEE ALSO</h3>
-
-<p><a href="#perlmod-NAME">perlmod NAME</a>, <a
href="perlmodlib.html#Top">(perlmodlib)</a>, <a
href="#perlmodinstall-NAME">perlmodinstall NAME</a>, <a
href="h2xs.html#Top">(h2xs)</a>, <a href="strict.html#Top">(strict)</a>,
-<a href="Carp.html#Top">(Carp)</a>, <a
href="Exporter.html#Top">(Exporter)</a>, <a href="#perlpod-NAME">perlpod
NAME</a>, <a href="Test-Simple.html#Top">(Test-Simple)</a>, <a
href="Test-More.html#Top">(Test-More)</a>
-<a href="ExtUtils-MakeMaker.html#Top">(ExtUtils-MakeMaker)</a>, <a
href="Module-Build.html#Top">(Module-Build)</a>, <a
href="Module-Starter.html#Top">(Module-Starter)</a>
-http://www.cpan.org/ , Ken Williams’s tutorial on building your own
-module at http://mathforum.org/~ken/perl_modules.html
-</p>
-<hr>
-<a name="perlnumber"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj" accesskey="n" rel="next">perlobj</a>, Previous: <a
href="#perlnewmod" accesskey="p" rel="prev">perlnewmod</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlnumber-1"></a>
-<h2 class="chapter">45 perlnumber</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlnumber-NAME"
accesskey="1">perlnumber NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlnumber-SYNOPSIS"
accesskey="2">perlnumber SYNOPSIS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlnumber-DESCRIPTION"
accesskey="3">perlnumber DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlnumber-Storing-numbers"
accesskey="4">perlnumber Storing numbers</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnumber-Numeric-operators-and-numeric-conversions"
accesskey="5">perlnumber Numeric operators and numeric
conversions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlnumber-Flavors-of-Perl-numeric-operations" accesskey="6">perlnumber
Flavors of Perl numeric operations</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlnumber-AUTHOR"
accesskey="7">perlnumber AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlnumber-SEE-ALSO"
accesskey="8">perlnumber SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlnumber-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnumber-SYNOPSIS" accesskey="n" rel="next">perlnumber
SYNOPSIS</a>, Up: <a href="#perlnumber" accesskey="u" rel="up">perlnumber</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-44"></a>
-<h3 class="section">45.1 NAME</h3>
-
-<p>perlnumber - semantics of numbers and numeric operations in Perl
-</p>
-<hr>
-<a name="perlnumber-SYNOPSIS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnumber-DESCRIPTION" accesskey="n" rel="next">perlnumber
DESCRIPTION</a>, Previous: <a href="#perlnumber-NAME" accesskey="p"
rel="prev">perlnumber NAME</a>, Up: <a href="#perlnumber" accesskey="u"
rel="up">perlnumber</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SYNOPSIS-8"></a>
-<h3 class="section">45.2 SYNOPSIS</h3>
-
-<pre class="verbatim"> $n = 1234; # decimal integer
- $n = 0b1110011; # binary integer
- $n = 01234; # octal integer
- $n = 0x1234; # hexadecimal integer
- $n = 12.34e-56; # exponential notation
- $n = "-12.34e56"; # number specified as a string
- $n = "1234"; # number specified as a string
-</pre>
-<hr>
-<a name="perlnumber-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnumber-Storing-numbers" accesskey="n"
rel="next">perlnumber Storing numbers</a>, Previous: <a
href="#perlnumber-SYNOPSIS" accesskey="p" rel="prev">perlnumber SYNOPSIS</a>,
Up: <a href="#perlnumber" accesskey="u" rel="up">perlnumber</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-43"></a>
-<h3 class="section">45.3 DESCRIPTION</h3>
-
-<p>This document describes how Perl internally handles numeric values.
-</p>
-<p>Perl’s operator overloading facility is completely ignored here.
Operator
-overloading allows user-defined behaviors for numbers, such as operations
-over arbitrarily large integers, floating points numbers with arbitrary
-precision, operations over "exotic" numbers such as modular
arithmetic or
-p-adic arithmetic, and so on. See <a href="overload.html#Top">(overload)</a>
for details.
-</p>
-<hr>
-<a name="perlnumber-Storing-numbers"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnumber-Numeric-operators-and-numeric-conversions"
accesskey="n" rel="next">perlnumber Numeric operators and numeric
conversions</a>, Previous: <a href="#perlnumber-DESCRIPTION" accesskey="p"
rel="prev">perlnumber DESCRIPTION</a>, Up: <a href="#perlnumber" accesskey="u"
rel="up">perlnumber</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Storing-numbers"></a>
-<h3 class="section">45.4 Storing numbers</h3>
-
-<p>Perl can internally represent numbers in 3 different ways: as native
-integers, as native floating point numbers, and as decimal strings.
-Decimal strings may have an exponential notation part, as in
<code>"12.34e-56"</code>.
-<em>Native</em> here means "a format supported by the C compiler which
was used
-to build perl".
-</p>
-<p>The term "native" does not mean quite as much when we talk about
native
-integers, as it does when native floating point numbers are involved.
-The only implication of the term "native" on integers is that the
limits for
-the maximal and the minimal supported true integral quantities are close to
-powers of 2. However, "native" floats have a most fundamental
-restriction: they may represent only those numbers which have a relatively
-"short" representation when converted to a binary fraction. For
example,
-0.9 cannot be represented by a native float, since the binary fraction
-for 0.9 is infinite:
-</p>
-<pre class="verbatim"> binary0.1110011001100...
-</pre>
-<p>with the sequence <code>1100</code> repeating again and again. In addition
to this
-limitation, the exponent of the binary number is also restricted when it
-is represented as a floating point number. On typical hardware, floating
-point values can store numbers with up to 53 binary digits, and with binary
-exponents between -1024 and 1024. In decimal representation this is close
-to 16 decimal digits and decimal exponents in the range of -304..304.
-The upshot of all this is that Perl cannot store a number like
-12345678901234567 as a floating point number on such architectures without
-loss of information.
-</p>
-<p>Similarly, decimal strings can represent only those numbers which have a
-finite decimal expansion. Being strings, and thus of arbitrary length, there
-is no practical limit for the exponent or number of decimal digits for these
-numbers. (But realize that what we are discussing the rules for just the
-<em>storage</em> of these numbers. The fact that you can store such
"large" numbers
-does not mean that the <em>operations</em> over these numbers will use all
-of the significant digits.
-See <a href="#perlnumber-Numeric-operators-and-numeric-conversions">Numeric
operators and numeric conversions</a> for details.)
-</p>
-<p>In fact numbers stored in the native integer format may be stored either
-in the signed native form, or in the unsigned native form. Thus the limits
-for Perl numbers stored as native integers would typically be -2**31..2**32-1,
-with appropriate modifications in the case of 64-bit integers. Again, this
-does not mean that Perl can do operations only over integers in this range:
-it is possible to store many more integers in floating point format.
-</p>
-<p>Summing up, Perl numeric values can store only those numbers which have
-a finite decimal expansion or a "short" binary expansion.
-</p>
-<hr>
-<a name="perlnumber-Numeric-operators-and-numeric-conversions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnumber-Flavors-of-Perl-numeric-operations" accesskey="n"
rel="next">perlnumber Flavors of Perl numeric operations</a>, Previous: <a
href="#perlnumber-Storing-numbers" accesskey="p" rel="prev">perlnumber Storing
numbers</a>, Up: <a href="#perlnumber" accesskey="u" rel="up">perlnumber</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Numeric-operators-and-numeric-conversions"></a>
-<h3 class="section">45.5 Numeric operators and numeric conversions</h3>
-
-<p>As mentioned earlier, Perl can store a number in any one of three formats,
-but most operators typically understand only one of those formats. When
-a numeric value is passed as an argument to such an operator, it will be
-converted to the format understood by the operator.
-</p>
-<p>Six such conversions are possible:
-</p>
-<pre class="verbatim"> native integer --> native floating point
(*)
- native integer --> decimal string
- native floating_point --> native integer (*)
- native floating_point --> decimal string (*)
- decimal string --> native integer
- decimal string --> native floating point (*)
-</pre>
-<p>These conversions are governed by the following general rules:
-</p>
-<ul>
-<li> If the source number can be represented in the target form, that
-representation is used.
-
-</li><li> If the source number is outside of the limits representable in the
target form,
-a representation of the closest limit is used. (<em>Loss of information</em>)
-
-</li><li> If the source number is between two numbers representable in the
target form,
-a representation of one of these numbers is used. (<em>Loss of
information</em>)
-
-</li><li> In <code>native floating point --> native integer</code>
conversions the magnitude
-of the result is less than or equal to the magnitude of the source.
-(<em>"Rounding to zero".</em>)
-
-</li><li> If the <code>decimal string --> native integer</code> conversion
cannot be done
-without loss of information, the result is compatible with the conversion
-sequence <code>decimal_string --> native_floating_point -->
native_integer</code>.
-In particular, rounding is strongly biased to 0, though a number like
-<code>"0.99999999999999999999"</code> has a chance of being rounded
to 1.
-
-</li></ul>
-
-<p><strong>RESTRICTION</strong>: The conversions marked with <code>(*)</code>
above involve steps
-performed by the C compiler. In particular, bugs/features of the compiler
-used may lead to breakage of some of the above rules.
-</p>
-<hr>
-<a name="perlnumber-Flavors-of-Perl-numeric-operations"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnumber-AUTHOR" accesskey="n" rel="next">perlnumber
AUTHOR</a>, Previous: <a
href="#perlnumber-Numeric-operators-and-numeric-conversions" accesskey="p"
rel="prev">perlnumber Numeric operators and numeric conversions</a>, Up: <a
href="#perlnumber" accesskey="u" rel="up">perlnumber</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Flavors-of-Perl-numeric-operations"></a>
-<h3 class="section">45.6 Flavors of Perl numeric operations</h3>
-
-<p>Perl operations which take a numeric argument treat that argument in one
-of four different ways: they may force it to one of the integer/floating/
-string formats, or they may behave differently depending on the format of
-the operand. Forcing a numeric value to a particular format does not
-change the number stored in the value.
-</p>
-<p>All the operators which need an argument in the integer format treat the
-argument as in modular arithmetic, e.g., <code>mod 2**32</code> on a 32-bit
-architecture. <code>sprintf "%u", -1</code> therefore provides the
same result as
-<code>sprintf "%u", ~0</code>.
-</p>
-<dl compact="compact">
-<dt>Arithmetic operators</dt>
-<dd><a name="perlnumber-Arithmetic-operators"></a>
-<p>The binary operators <code>+</code> <code>-</code> <code>*</code>
<code>/</code> <code>%</code> <code>==</code> <code>!=</code> <code>></code>
<code><</code>
-<code>>=</code> <code><=</code> and the unary operators <code>-</code>
<code>abs</code> and <code>--</code> will
-attempt to convert arguments to integers. If both conversions are possible
-without loss of precision, and the operation can be performed without
-loss of precision then the integer result is used. Otherwise arguments are
-converted to floating point format and the floating point result is used.
-The caching of conversions (as described above) means that the integer
-conversion does not throw away fractional parts on floating point numbers.
-</p>
-</dd>
-<dt>++</dt>
-<dd><a name="perlnumber-_002b_002b"></a>
-<p><code>++</code> behaves as the other operators above, except that if it is
a string
-matching the format <code>/^[a-zA-Z]*[0-9]*\z/</code> the string increment
described
-in <a href="#perlop-NAME">perlop NAME</a> is used.
-</p>
-</dd>
-<dt>Arithmetic operators during <code>use integer</code></dt>
-<dd><a name="perlnumber-Arithmetic-operators-during-use-integer"></a>
-<p>In scopes where <code>use integer;</code> is in force, nearly all the
operators listed
-above will force their argument(s) into integer format, and return an integer
-result. The exceptions, <code>abs</code>, <code>++</code> and
<code>--</code>, do not change their
-behavior with <code>use integer;</code>
-</p>
-</dd>
-<dt>Other mathematical operators</dt>
-<dd><a name="perlnumber-Other-mathematical-operators"></a>
-<p>Operators such as <code>**</code>, <code>sin</code> and <code>exp</code>
force arguments to floating point
-format.
-</p>
-</dd>
-<dt>Bitwise operators</dt>
-<dd><a name="perlnumber-Bitwise-operators"></a>
-<p>Arguments are forced into the integer format if not strings.
-</p>
-</dd>
-<dt>Bitwise operators during <code>use integer</code></dt>
-<dd><a name="perlnumber-Bitwise-operators-during-use-integer"></a>
-<p>forces arguments to integer format. Also shift operations internally use
-signed integers rather than the default unsigned.
-</p>
-</dd>
-<dt>Operators which expect an integer</dt>
-<dd><a name="perlnumber-Operators-which-expect-an-integer"></a>
-<p>force the argument into the integer format. This is applicable
-to the third and fourth arguments of <code>sysread</code>, for example.
-</p>
-</dd>
-<dt>Operators which expect a string</dt>
-<dd><a name="perlnumber-Operators-which-expect-a-string"></a>
-<p>force the argument into the string format. For example, this is
-applicable to <code>printf "%s", $value</code>.
-</p>
-</dd>
-</dl>
-
-<p>Though forcing an argument into a particular form does not change the
-stored number, Perl remembers the result of such conversions. In
-particular, though the first such conversion may be time-consuming,
-repeated operations will not need to redo the conversion.
-</p>
-<hr>
-<a name="perlnumber-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlnumber-SEE-ALSO" accesskey="n" rel="next">perlnumber SEE
ALSO</a>, Previous: <a href="#perlnumber-Flavors-of-Perl-numeric-operations"
accesskey="p" rel="prev">perlnumber Flavors of Perl numeric operations</a>, Up:
<a href="#perlnumber" accesskey="u" rel="up">perlnumber</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-20"></a>
-<h3 class="section">45.7 AUTHOR</h3>
-
-<p>Ilya Zakharevich <code>address@hidden</code>
-</p>
-<p>Editorial adjustments by Gurusamy Sarathy <address@hidden>
-</p>
-<p>Updates for 5.8.0 by Nicholas Clark <address@hidden>
-</p>
-<hr>
-<a name="perlnumber-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlnumber-AUTHOR" accesskey="p" rel="prev">perlnumber
AUTHOR</a>, Up: <a href="#perlnumber" accesskey="u" rel="up">perlnumber</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-22"></a>
-<h3 class="section">45.8 SEE ALSO</h3>
-
-<p><a href="overload.html#Top">(overload)</a>, <a href="#perlop-NAME">perlop
NAME</a>
-</p>
-<hr>
-<a name="perlobj"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut" accesskey="n" rel="next">perlootut</a>, Previous:
<a href="#perlnumber" accesskey="p" rel="prev">perlnumber</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlobj-2"></a>
-<h2 class="chapter">46 perlobj</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlobj-NAME"
accesskey="1">perlobj NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlobj-DESCRIPTION"
accesskey="2">perlobj DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlobj-SEE-ALSO"
accesskey="3">perlobj SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlobj-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-DESCRIPTION" accesskey="n" rel="next">perlobj
DESCRIPTION</a>, Up: <a href="#perlobj" accesskey="u" rel="up">perlobj</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-45"></a>
-<h3 class="section">46.1 NAME</h3>
-
-<p>perlobj - Perl object reference
-</p>
-<hr>
-<a name="perlobj-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-SEE-ALSO" accesskey="n" rel="next">perlobj SEE
ALSO</a>, Previous: <a href="#perlobj-NAME" accesskey="p" rel="prev">perlobj
NAME</a>, Up: <a href="#perlobj" accesskey="u" rel="up">perlobj</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-44"></a>
-<h3 class="section">46.2 DESCRIPTION</h3>
-
-<p>This document provides a reference for Perl’s object orientation
-features. If you’re looking for an introduction to object-oriented
-programming in Perl, please see <a href="#perlootut-NAME">perlootut NAME</a>.
-</p>
-<p>In order to understand Perl objects, you first need to understand
-references in Perl. See <a href="#perlref-NAME">perlref NAME</a> for details.
-</p>
-<p>This document describes all of Perl’s object-oriented (OO) features
-from the ground up. If you’re just looking to write some
-object-oriented code of your own, you are probably better served by
-using one of the object systems from CPAN described in <a
href="#perlootut-NAME">perlootut NAME</a>.
-</p>
-<p>If you’re looking to write your own object system, or you need to
-maintain code which implements objects from scratch then this document
-will help you understand exactly how Perl does object orientation.
-</p>
-<p>There are a few basic principles which define object oriented Perl:
-</p>
-<ol>
-<li> An object is simply a data structure that knows to which class it
-belongs.
-
-</li><li> A class is simply a package. A class provides methods that expect to
-operate on objects.
-
-</li><li> A method is simply a subroutine that expects a reference to an object
-(or a package name, for class methods) as the first argument.
-
-</li></ol>
-
-<p>Let’s look at each of these principles in depth.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlobj-An-Object-is-Simply-a-Data-Structure" accesskey="1">perlobj An
Object is Simply a Data Structure</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-A-Class-is-Simply-a-Package" accesskey="2">perlobj A Class is
Simply a Package</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-A-Method-is-Simply-a-Subroutine" accesskey="3">perlobj A Method
is Simply a Subroutine</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Method-Invocation-_003e_003e" accesskey="4">perlobj Method
Invocation >></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlobj-Inheritance"
accesskey="5">perlobj Inheritance</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Writing-Constructors" accesskey="6">perlobj Writing
Constructors</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlobj-Attributes"
accesskey="7">perlobj Attributes</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-An-Aside-About-Smarter-and-Safer-Code" accesskey="8">perlobj An
Aside About Smarter and Safer Code</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Method-Call-Variations" accesskey="9">perlobj Method Call
Variations</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Invoking-Class-Methods">perlobj Invoking Class
Methods</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-bless_002c-blessed_002c-and-ref">perlobj <code>bless</code>,
<code>blessed</code>, and <code>ref</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-The-UNIVERSAL-Class">perlobj The UNIVERSAL
Class</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlobj-AUTOLOAD">perlobj
AUTOLOAD</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Destructors">perlobj
Destructors</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Non_002dHash-Objects">perlobj Non-Hash
Objects</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Inside_002dOut-objects">perlobj Inside-Out
objects</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Pseudo_002dhashes">perlobj
Pseudo-hashes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlobj-An-Object-is-Simply-a-Data-Structure"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-A-Class-is-Simply-a-Package" accesskey="n"
rel="next">perlobj A Class is Simply a Package</a>, Up: <a
href="#perlobj-DESCRIPTION" accesskey="u" rel="up">perlobj DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="An-Object-is-Simply-a-Data-Structure"></a>
-<h4 class="subsection">46.2.1 An Object is Simply a Data Structure</h4>
-
-<p>Unlike many other languages which support object orientation, Perl does
-not provide any special syntax for constructing an object. Objects are
-merely Perl data structures (hashes, arrays, scalars, filehandles,
-etc.) that have been explicitly associated with a particular class.
-</p>
-<p>That explicit association is created by the built-in <code>bless</code>
function,
-which is typically used within the <em>constructor</em> subroutine of the
-class.
-</p>
-<p>Here is a simple constructor:
-</p>
-<pre class="verbatim"> package File;
-
- sub new {
- my $class = shift;
-
- return bless {}, $class;
- }
-</pre>
-<p>The name <code>new</code> isn’t special. We could name our
constructor something
-else:
-</p>
-<pre class="verbatim"> package File;
-
- sub load {
- my $class = shift;
-
- return bless {}, $class;
- }
-</pre>
-<p>The modern convention for OO modules is to always use <code>new</code> as
the
-name for the constructor, but there is no requirement to do so. Any
-subroutine that blesses a data structure into a class is a valid
-constructor in Perl.
-</p>
-<p>In the previous examples, the <code>{}</code> code creates a reference to an
-empty anonymous hash. The <code>bless</code> function then takes that reference
-and associates the hash with the class in <code>$class</code>. In the simplest
-case, the <code>$class</code> variable will end up containing the string
"File".
-</p>
-<p>We can also use a variable to store a reference to the data structure
-that is being blessed as our object:
-</p>
-<pre class="verbatim"> sub new {
- my $class = shift;
-
- my $self = {};
- bless $self, $class;
-
- return $self;
- }
-</pre>
-<p>Once we’ve blessed the hash referred to by <code>$self</code> we can
start
-calling methods on it. This is useful if you want to put object
-initialization in its own separate method:
-</p>
-<pre class="verbatim"> sub new {
- my $class = shift;
-
- my $self = {};
- bless $self, $class;
-
- $self->_initialize();
-
- return $self;
- }
-</pre>
-<p>Since the object is also a hash, you can treat it as one, using it to
-store data associated with the object. Typically, code inside the class
-can treat the hash as an accessible data structure, while code outside
-the class should always treat the object as opaque. This is called
-<strong>encapsulation</strong>. Encapsulation means that the user of an object
does
-not have to know how it is implemented. The user simply calls
-documented methods on the object.
-</p>
-<p>Note, however, that (unlike most other OO languages) Perl does not
-ensure or enforce encapsulation in any way. If you want objects to
-actually <em>be</em> opaque you need to arrange for that yourself. This can
-be done in a variety of ways, including using <a
href="#perlobj-Inside_002dOut-objects">Inside-Out objects</a>
-or modules from CPAN.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlobj-Objects-Are-Blessed_003b-Variables-Are-Not"
accesskey="1">perlobj Objects Are Blessed; Variables Are
Not</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlobj-Objects-Are-Blessed_003b-Variables-Are-Not"></a>
-<div class="header">
-<p>
-Up: <a href="#perlobj-An-Object-is-Simply-a-Data-Structure" accesskey="u"
rel="up">perlobj An Object is Simply a Data Structure</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Objects-Are-Blessed_003b-Variables-Are-Not"></a>
-<h4 class="subsubsection">46.2.1.1 Objects Are Blessed; Variables Are Not</h4>
-
-<p>When we bless something, we are not blessing the variable which
-contains a reference to that thing, nor are we blessing the reference
-that the variable stores; we are blessing the thing that the variable
-refers to (sometimes known as the <em>referent</em>). This is best
-demonstrated with this code:
-</p>
-<pre class="verbatim"> use Scalar::Util 'blessed';
-
- my $foo = {};
- my $bar = $foo;
-
- bless $foo, 'Class';
- print blessed( $bar ) // 'not blessed'; # prints "Class"
-
- $bar = "some other value";
- print blessed( $bar ) // 'not blessed'; # prints "not blessed"
-</pre>
-<p>When we call <code>bless</code> on a variable, we are actually blessing the
-underlying data structure that the variable refers to. We are not
-blessing the reference itself, nor the variable that contains that
-reference. That’s why the second call to <code>blessed( $bar )</code>
returns
-false. At that point <code>$bar</code> is no longer storing a reference to an
-object.
-</p>
-<p>You will sometimes see older books or documentation mention "blessing a
-reference" or describe an object as a "blessed reference", but
this is
-incorrect. It isn’t the reference that is blessed as an object;
it’s
-the thing the reference refers to (i.e. the referent).
-</p>
-<hr>
-<a name="perlobj-A-Class-is-Simply-a-Package"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-A-Method-is-Simply-a-Subroutine" accesskey="n"
rel="next">perlobj A Method is Simply a Subroutine</a>, Previous: <a
href="#perlobj-An-Object-is-Simply-a-Data-Structure" accesskey="p"
rel="prev">perlobj An Object is Simply a Data Structure</a>, Up: <a
href="#perlobj-DESCRIPTION" accesskey="u" rel="up">perlobj DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="A-Class-is-Simply-a-Package"></a>
-<h4 class="subsection">46.2.2 A Class is Simply a Package</h4>
-
-<p>Perl does not provide any special syntax for class definitions. A
-package is simply a namespace containing variables and subroutines. The
-only difference is that in a class, the subroutines may expect a
-reference to an object or the name of a class as the first argument.
-This is purely a matter of convention, so a class may contain both
-methods and subroutines which <em>don’t</em> operate on an object or
class.
-</p>
-<p>Each package contains a special array called <code>@ISA</code>. The
<code>@ISA</code> array
-contains a list of that class’s parent classes, if any. This array is
-examined when Perl does method resolution, which we will cover later.
-</p>
-<p>It is possible to manually set <code>@ISA</code>, and you may see this in
older
-Perl code. Much older code also uses the <a href="base.html#Top">(base)</a>
pragma. For new code,
-we recommend that you use the <a href="parent.html#Top">(parent)</a> pragma to
declare your parents.
-This pragma will take care of setting <code>@ISA</code>. It will also load the
-parent classes and make sure that the package doesn’t inherit from
-itself.
-</p>
-<p>However the parent classes are set, the package’s <code>@ISA</code>
variable will
-contain a list of those parents. This is simply a list of scalars, each
-of which is a string that corresponds to a package name.
-</p>
-<p>All classes inherit from the <a href="UNIVERSAL.html#Top">(UNIVERSAL)</a>
class implicitly. The
-<a href="UNIVERSAL.html#Top">(UNIVERSAL)</a> class is implemented by the Perl
core, and provides
-several default methods, such as <code>isa()</code>, <code>can()</code>, and
<code>VERSION()</code>.
-The <code>UNIVERSAL</code> class will <em>never</em> appear in a
package’s <code>@ISA</code>
-variable.
-</p>
-<p>Perl <em>only</em> provides method inheritance as a built-in feature.
-Attribute inheritance is left up the class to implement. See the
-<a href="#perlobj-Writing-Accessors">Writing Accessors</a> section for details.
-</p>
-<hr>
-<a name="perlobj-A-Method-is-Simply-a-Subroutine"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Method-Invocation-_003e_003e" accesskey="n"
rel="next">perlobj Method Invocation >></a>, Previous: <a
href="#perlobj-A-Class-is-Simply-a-Package" accesskey="p" rel="prev">perlobj A
Class is Simply a Package</a>, Up: <a href="#perlobj-DESCRIPTION" accesskey="u"
rel="up">perlobj DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="A-Method-is-Simply-a-Subroutine"></a>
-<h4 class="subsection">46.2.3 A Method is Simply a Subroutine</h4>
-
-<p>Perl does not provide any special syntax for defining a method. A
-method is simply a regular subroutine, and is declared with <code>sub</code>.
-What makes a method special is that it expects to receive either an
-object or a class name as its first argument.
-</p>
-<p>Perl <em>does</em> provide special syntax for method invocation, the
<code>-></code> operator. We will cover this in more detail later.
-</p>
-<p>Most methods you write will expect to operate on objects:
-</p>
-<pre class="verbatim"> sub save {
- my $self = shift;
-
- open my $fh, '>', $self->path() or die $!;
- print {$fh} $self->data() or die $!;
- close $fh or die $!;
- }
-</pre>
-<hr>
-<a name="perlobj-Method-Invocation-_003e_003e"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Inheritance" accesskey="n" rel="next">perlobj
Inheritance</a>, Previous: <a href="#perlobj-A-Method-is-Simply-a-Subroutine"
accesskey="p" rel="prev">perlobj A Method is Simply a Subroutine</a>, Up: <a
href="#perlobj-DESCRIPTION" accesskey="u" rel="up">perlobj DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Method-Invocation-_003e_003e"></a>
-<h4 class="subsection">46.2.4 Method Invocation >></h4>
-
-<p>Calling a method on an object is written as <code>$object->method</code>.
-</p>
-<p>The left hand side of the method invocation (or arrow) operator is the
-object (or class name), and the right hand side is the method name.
-</p>
-<pre class="verbatim"> my $pod = File->new( 'perlobj.pod', $data );
- $pod->save();
-</pre>
-<p>The <code>-></code> syntax is also used when dereferencing a reference.
It
-looks like the same operator, but these are two different operations.
-</p>
-<p>When you call a method, the thing on the left side of the arrow is
-passed as the first argument to the method. That means when we call
<code>Critter->new()</code>, the <code>new()</code> method receives the
string <code>"Critter"</code>
-as its first argument. When we call <code>$fred->speak()</code>, the
<code>$fred</code>
-variable is passed as the first argument to <code>speak()</code>.
-</p>
-<p>Just as with any Perl subroutine, all of the arguments passed in
<code>@_</code>
-are aliases to the original argument. This includes the object itself.
-If you assign directly to <code>$_[0]</code> you will change the contents of
the
-variable that holds the reference to the object. We recommend that you
-don’t do this unless you know exactly what you’re doing.
-</p>
-<p>Perl knows what package the method is in by looking at the left side of
-the arrow. If the left hand side is a package name, it looks for the
-method in that package. If the left hand side is an object, then Perl
-looks for the method in the package that the object has been blessed
-into.
-</p>
-<p>If the left hand side is neither a package name nor an object, then the
-method call will cause an error, but see the section on <a
href="#perlobj-Method-Call-Variations">Method Call
-Variations</a> for more nuances.
-</p>
-<hr>
-<a name="perlobj-Inheritance"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Writing-Constructors" accesskey="n" rel="next">perlobj
Writing Constructors</a>, Previous: <a
href="#perlobj-Method-Invocation-_003e_003e" accesskey="p" rel="prev">perlobj
Method Invocation >></a>, Up: <a href="#perlobj-DESCRIPTION"
accesskey="u" rel="up">perlobj DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Inheritance"></a>
-<h4 class="subsection">46.2.5 Inheritance</h4>
-
-<p>We already talked about the special <code>@ISA</code> array and the <a
href="parent.html#Top">(parent)</a>
-pragma.
-</p>
-<p>When a class inherits from another class, any methods defined in the
-parent class are available to the child class. If you attempt to call a
-method on an object that isn’t defined in its own class, Perl will also
-look for that method in any parent classes it may have.
-</p>
-<pre class="verbatim"> package File::MP3;
- use parent 'File'; # sets @File::MP3::ISA = ('File');
-
- my $mp3 = File::MP3->new( 'Andvari.mp3', $data );
- $mp3->save();
-</pre>
-<p>Since we didn’t define a <code>save()</code> method in the
<code>File::MP3</code> class,
-Perl will look at the <code>File::MP3</code> class’s parent classes to
find the
-<code>save()</code> method. If Perl cannot find a <code>save()</code> method
anywhere in
-the inheritance hierarchy, it will die.
-</p>
-<p>In this case, it finds a <code>save()</code> method in the
<code>File</code> class. Note
-that the object passed to <code>save()</code> in this case is still a
-<code>File::MP3</code> object, even though the method is found in the
<code>File</code>
-class.
-</p>
-<p>We can override a parent’s method in a child class. When we do so, we
-can still call the parent class’s method with the <code>SUPER</code>
-pseudo-class.
-</p>
-<pre class="verbatim"> sub save {
- my $self = shift;
-
- say 'Prepare to rock';
- $self->SUPER::save();
- }
-</pre>
-<p>The <code>SUPER</code> modifier can <em>only</em> be used for method calls.
You can’t
-use it for regular subroutine calls or class methods:
-</p>
-<pre class="verbatim"> SUPER::save($thing); # FAIL: looks for save() sub
in package SUPER
-
- SUPER->save($thing); # FAIL: looks for save() method in class
- # SUPER
-
- $thing->SUPER::save(); # Okay: looks for save() method in parent
- # classes
-</pre>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlobj-How-SUPER-is-Resolved" accesskey="1">perlobj How SUPER is
Resolved</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Multiple-Inheritance" accesskey="2">perlobj Multiple
Inheritance</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Method-Resolution-Order" accesskey="3">perlobj Method Resolution
Order</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Method-Resolution-Caching" accesskey="4">perlobj Method
Resolution Caching</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlobj-How-SUPER-is-Resolved"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Multiple-Inheritance" accesskey="n" rel="next">perlobj
Multiple Inheritance</a>, Up: <a href="#perlobj-Inheritance" accesskey="u"
rel="up">perlobj Inheritance</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="How-SUPER-is-Resolved"></a>
-<h4 class="subsubsection">46.2.5.1 How SUPER is Resolved</h4>
-
-<p>The <code>SUPER</code> pseudo-class is resolved from the package where the
call
-is made. It is <em>not</em> resolved based on the object’s class. This is
-important, because it lets methods at different levels within a deep
-inheritance hierarchy each correctly call their respective parent
-methods.
-</p>
-<pre class="verbatim"> package A;
-
- sub new {
- return bless {}, shift;
- }
-
- sub speak {
- my $self = shift;
-
- say 'A';
- }
-
- package B;
-
- use parent -norequire, 'A';
-
- sub speak {
- my $self = shift;
-
- $self->SUPER::speak();
-
- say 'B';
- }
-
- package C;
-
- use parent -norequire, 'B';
-
- sub speak {
- my $self = shift;
-
- $self->SUPER::speak();
-
- say 'C';
- }
-
- my $c = C->new();
- $c->speak();
-</pre>
-<p>In this example, we will get the following output:
-</p>
-<pre class="verbatim"> A
- B
- C
-</pre>
-<p>This demonstrates how <code>SUPER</code> is resolved. Even though the
object is
-blessed into the <code>C</code> class, the <code>speak()</code> method in the
<code>B</code> class
-can still call <code>SUPER::speak()</code> and expect it to correctly look in
the
-parent class of <code>B</code> (i.e the class the method call is in), not in
the
-parent class of <code>C</code> (i.e. the class the object belongs to).
-</p>
-<p>There are rare cases where this package-based resolution can be a
-problem. If you copy a subroutine from one package to another,
<code>SUPER</code>
-resolution will be done based on the original package.
-</p>
-<hr>
-<a name="perlobj-Multiple-Inheritance"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Method-Resolution-Order" accesskey="n"
rel="next">perlobj Method Resolution Order</a>, Previous: <a
href="#perlobj-How-SUPER-is-Resolved" accesskey="p" rel="prev">perlobj How
SUPER is Resolved</a>, Up: <a href="#perlobj-Inheritance" accesskey="u"
rel="up">perlobj Inheritance</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Multiple-Inheritance"></a>
-<h4 class="subsubsection">46.2.5.2 Multiple Inheritance</h4>
-
-<p>Multiple inheritance often indicates a design problem, but Perl always
-gives you enough rope to hang yourself with if you ask for it.
-</p>
-<p>To declare multiple parents, you simply need to pass multiple class
-names to <code>use parent</code>:
-</p>
-<pre class="verbatim"> package MultiChild;
-
- use parent 'Parent1', 'Parent2';
-</pre>
-<hr>
-<a name="perlobj-Method-Resolution-Order"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Method-Resolution-Caching" accesskey="n"
rel="next">perlobj Method Resolution Caching</a>, Previous: <a
href="#perlobj-Multiple-Inheritance" accesskey="p" rel="prev">perlobj Multiple
Inheritance</a>, Up: <a href="#perlobj-Inheritance" accesskey="u"
rel="up">perlobj Inheritance</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Method-Resolution-Order"></a>
-<h4 class="subsubsection">46.2.5.3 Method Resolution Order</h4>
-
-<p>Method resolution order only matters in the case of multiple
-inheritance. In the case of single inheritance, Perl simply looks up
-the inheritance chain to find a method:
-</p>
-<pre class="verbatim"> Grandparent
- |
- Parent
- |
- Child
-</pre>
-<p>If we call a method on a <code>Child</code> object and that method is not
defined
-in the <code>Child</code> class, Perl will look for that method in the
<code>Parent</code>
-class and then, if necessary, in the <code>Grandparent</code> class.
-</p>
-<p>If Perl cannot find the method in any of these classes, it will die
-with an error message.
-</p>
-<p>When a class has multiple parents, the method lookup order becomes more
-complicated.
-</p>
-<p>By default, Perl does a depth-first left-to-right search for a method.
-That means it starts with the first parent in the <code>@ISA</code> array, and
-then searches all of its parents, grandparents, etc. If it fails to
-find the method, it then goes to the next parent in the original
-class’s <code>@ISA</code> array and searches from there.
-</p>
-<pre class="verbatim"> SharedGreatGrandParent
- / \
- PaternalGrandparent MaternalGrandparent
- \ /
- Father Mother
- \ /
- Child
-</pre>
-<p>So given the diagram above, Perl will search <code>Child</code>,
<code>Father</code>,
-<code>PaternalGrandparent</code>, <code>SharedGreatGrandParent</code>,
<code>Mother</code>, and
-finally <code>MaternalGrandparent</code>. This may be a problem because now
we’re
-looking in <code>SharedGreatGrandParent</code> <em>before</em> we’ve
checked all its
-derived classes (i.e. before we tried <code>Mother</code> and
-<code>MaternalGrandparent</code>).
-</p>
-<p>It is possible to ask for a different method resolution order with the
-<a href="mro.html#Top">(mro)</a> pragma.
-</p>
-<pre class="verbatim"> package Child;
-
- use mro 'c3';
- use parent 'Father', 'Mother';
-</pre>
-<p>This pragma lets you switch to the "C3" resolution order. In
simple
-terms, "C3" order ensures that shared parent classes are never
searched
-before child classes, so Perl will now search: <code>Child</code>,
<code>Father</code>,
-<code>PaternalGrandparent</code>, <code>Mother</code>
<code>MaternalGrandparent</code>, and finally
-<code>SharedGreatGrandParent</code>. Note however that this is not
-"breadth-first" searching: All the <code>Father</code> ancestors
(except the
-common ancestor) are searched before any of the <code>Mother</code> ancestors
are
-considered.
-</p>
-<p>The C3 order also lets you call methods in sibling classes with the
-<code>next</code> pseudo-class. See the <a href="mro.html#Top">(mro)</a>
documentation for more details on
-this feature.
-</p>
-<hr>
-<a name="perlobj-Method-Resolution-Caching"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlobj-Method-Resolution-Order" accesskey="p"
rel="prev">perlobj Method Resolution Order</a>, Up: <a
href="#perlobj-Inheritance" accesskey="u" rel="up">perlobj Inheritance</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Method-Resolution-Caching"></a>
-<h4 class="subsubsection">46.2.5.4 Method Resolution Caching</h4>
-
-<p>When Perl searches for a method, it caches the lookup so that future
-calls to the method do not need to search for it again. Changing a
-class’s parent class or adding subroutines to a class will invalidate
-the cache for that class.
-</p>
-<p>The <a href="mro.html#Top">(mro)</a> pragma provides some functions for
manipulating the method
-cache directly.
-</p>
-<hr>
-<a name="perlobj-Writing-Constructors"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Attributes" accesskey="n" rel="next">perlobj
Attributes</a>, Previous: <a href="#perlobj-Inheritance" accesskey="p"
rel="prev">perlobj Inheritance</a>, Up: <a href="#perlobj-DESCRIPTION"
accesskey="u" rel="up">perlobj DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Writing-Constructors"></a>
-<h4 class="subsection">46.2.6 Writing Constructors</h4>
-
-<p>As we mentioned earlier, Perl provides no special constructor syntax.
-This means that a class must implement its own constructor. A
-constructor is simply a class method that returns a reference to a new
-object.
-</p>
-<p>The constructor can also accept additional parameters that define the
-object. Let’s write a real constructor for the <code>File</code> class
we used
-earlier:
-</p>
-<pre class="verbatim"> package File;
-
- sub new {
- my $class = shift;
- my ( $path, $data ) = @_;
-
- my $self = bless {
- path => $path,
- data => $data,
- }, $class;
-
- return $self;
- }
-</pre>
-<p>As you can see, we’ve stored the path and file data in the object
-itself. Remember, under the hood, this object is still just a hash.
-Later, we’ll write accessors to manipulate this data.
-</p>
-<p>For our File::MP3 class, we can check to make sure that the path we’re
-given ends with ".mp3":
-</p>
-<pre class="verbatim"> package File::MP3;
-
- sub new {
- my $class = shift;
- my ( $path, $data ) = @_;
-
- die "You cannot create a File::MP3 without an mp3 extension\n"
- unless $path =~ /\.mp3\z/;
-
- return $class->SUPER::new(@_);
- }
-</pre>
-<p>This constructor lets its parent class do the actual object
-construction.
-</p>
-<hr>
-<a name="perlobj-Attributes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-An-Aside-About-Smarter-and-Safer-Code" accesskey="n"
rel="next">perlobj An Aside About Smarter and Safer Code</a>, Previous: <a
href="#perlobj-Writing-Constructors" accesskey="p" rel="prev">perlobj Writing
Constructors</a>, Up: <a href="#perlobj-DESCRIPTION" accesskey="u"
rel="up">perlobj DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Attributes"></a>
-<h4 class="subsection">46.2.7 Attributes</h4>
-
-<p>An attribute is a piece of data belonging to a particular object.
-Unlike most object-oriented languages, Perl provides no special syntax
-or support for declaring and manipulating attributes.
-</p>
-<p>Attributes are often stored in the object itself. For example, if the
-object is an anonymous hash, we can store the attribute values in the
-hash using the attribute name as the key.
-</p>
-<p>While it’s possible to refer directly to these hash keys outside of
the
-class, it’s considered a best practice to wrap all access to the
-attribute with accessor methods.
-</p>
-<p>This has several advantages. Accessors make it easier to change the
-implementation of an object later while still preserving the original
-API.
-</p>
-<p>An accessor lets you add additional code around attribute access. For
-example, you could apply a default to an attribute that wasn’t set in
-the constructor, or you could validate that a new value for the
-attribute is acceptable.
-</p>
-<p>Finally, using accessors makes inheritance much simpler. Subclasses can
-use the accessors rather than having to know how a parent class is
-implemented internally.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlobj-Writing-Accessors"
accesskey="1">perlobj Writing Accessors</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlobj-Writing-Accessors"></a>
-<div class="header">
-<p>
-Up: <a href="#perlobj-Attributes" accesskey="u" rel="up">perlobj
Attributes</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Writing-Accessors"></a>
-<h4 class="subsubsection">46.2.7.1 Writing Accessors</h4>
-
-<p>As with constructors, Perl provides no special accessor declaration
-syntax, so classes must provide explicitly written accessor methods.
-There are two common types of accessors, read-only and read-write.
-</p>
-<p>A simple read-only accessor simply gets the value of a single
-attribute:
-</p>
-<pre class="verbatim"> sub path {
- my $self = shift;
-
- return $self->{path};
- }
-</pre>
-<p>A read-write accessor will allow the caller to set the value as well as
-get it:
-</p>
-<pre class="verbatim"> sub path {
- my $self = shift;
-
- if (@_) {
- $self->{path} = shift;
- }
-
- return $self->{path};
- }
-</pre>
-<hr>
-<a name="perlobj-An-Aside-About-Smarter-and-Safer-Code"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Method-Call-Variations" accesskey="n"
rel="next">perlobj Method Call Variations</a>, Previous: <a
href="#perlobj-Attributes" accesskey="p" rel="prev">perlobj Attributes</a>, Up:
<a href="#perlobj-DESCRIPTION" accesskey="u" rel="up">perlobj DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="An-Aside-About-Smarter-and-Safer-Code"></a>
-<h4 class="subsection">46.2.8 An Aside About Smarter and Safer Code</h4>
-
-<p>Our constructor and accessors are not very smart. They don’t check
that
-a <code>$path</code> is defined, nor do they check that a <code>$path</code>
is a valid
-filesystem path.
-</p>
-<p>Doing these checks by hand can quickly become tedious. Writing a bunch
-of accessors by hand is also incredibly tedious. There are a lot of
-modules on CPAN that can help you write safer and more concise code,
-including the modules we recommend in <a href="#perlootut-NAME">perlootut
NAME</a>.
-</p>
-<hr>
-<a name="perlobj-Method-Call-Variations"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Invoking-Class-Methods" accesskey="n"
rel="next">perlobj Invoking Class Methods</a>, Previous: <a
href="#perlobj-An-Aside-About-Smarter-and-Safer-Code" accesskey="p"
rel="prev">perlobj An Aside About Smarter and Safer Code</a>, Up: <a
href="#perlobj-DESCRIPTION" accesskey="u" rel="up">perlobj DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Method-Call-Variations"></a>
-<h4 class="subsection">46.2.9 Method Call Variations</h4>
-
-<p>Perl supports several other ways to call methods besides the
<code>$object->method()</code> usage we’ve seen so far.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlobj-Method-Names-as-Strings" accesskey="1">perlobj Method Names as
Strings</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Class-Names-as-Strings" accesskey="2">perlobj Class Names as
Strings</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Subroutine-References-as-Methods" accesskey="3">perlobj
Subroutine References as Methods</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Deferencing-Method-Call" accesskey="4">perlobj Deferencing
Method Call</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlobj-Method-Calls-on-Filehandles" accesskey="5">perlobj Method Calls
on Filehandles</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlobj-Method-Names-as-Strings"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Class-Names-as-Strings" accesskey="n"
rel="next">perlobj Class Names as Strings</a>, Up: <a
href="#perlobj-Method-Call-Variations" accesskey="u" rel="up">perlobj Method
Call Variations</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Method-Names-as-Strings"></a>
-<h4 class="subsubsection">46.2.9.1 Method Names as Strings</h4>
-
-<p>Perl lets you use a scalar variable containing a string as a method
-name:
-</p>
-<pre class="verbatim"> my $file = File->new( $path, $data );
-
- my $method = 'save';
- $file->$method();
-</pre>
-<p>This works exactly like calling <code>$file->save()</code>. This can be
very
-useful for writing dynamic code. For example, it allows you to pass a
-method name to be called as a parameter to another method.
-</p>
-<hr>
-<a name="perlobj-Class-Names-as-Strings"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Subroutine-References-as-Methods" accesskey="n"
rel="next">perlobj Subroutine References as Methods</a>, Previous: <a
href="#perlobj-Method-Names-as-Strings" accesskey="p" rel="prev">perlobj Method
Names as Strings</a>, Up: <a href="#perlobj-Method-Call-Variations"
accesskey="u" rel="up">perlobj Method Call Variations</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Class-Names-as-Strings"></a>
-<h4 class="subsubsection">46.2.9.2 Class Names as Strings</h4>
-
-<p>Perl also lets you use a scalar containing a string as a class name:
-</p>
-<pre class="verbatim"> my $class = 'File';
-
- my $file = $class->new( $path, $data );
-</pre>
-<p>Again, this allows for very dynamic code.
-</p>
-<hr>
-<a name="perlobj-Subroutine-References-as-Methods"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Deferencing-Method-Call" accesskey="n"
rel="next">perlobj Deferencing Method Call</a>, Previous: <a
href="#perlobj-Class-Names-as-Strings" accesskey="p" rel="prev">perlobj Class
Names as Strings</a>, Up: <a href="#perlobj-Method-Call-Variations"
accesskey="u" rel="up">perlobj Method Call Variations</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Subroutine-References-as-Methods"></a>
-<h4 class="subsubsection">46.2.9.3 Subroutine References as Methods</h4>
-
-<p>You can also use a subroutine reference as a method:
-</p>
-<pre class="verbatim"> my $sub = sub {
- my $self = shift;
-
- $self->save();
- };
-
- $file->$sub();
-</pre>
-<p>This is exactly equivalent to writing <code>$sub->($file)</code>. You
may see
-this idiom in the wild combined with a call to <code>can</code>:
-</p>
-<pre class="verbatim"> if ( my $meth = $object->can('foo') ) {
- $object->$meth();
- }
-</pre>
-<hr>
-<a name="perlobj-Deferencing-Method-Call"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Method-Calls-on-Filehandles" accesskey="n"
rel="next">perlobj Method Calls on Filehandles</a>, Previous: <a
href="#perlobj-Subroutine-References-as-Methods" accesskey="p"
rel="prev">perlobj Subroutine References as Methods</a>, Up: <a
href="#perlobj-Method-Call-Variations" accesskey="u" rel="up">perlobj Method
Call Variations</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Deferencing-Method-Call"></a>
-<h4 class="subsubsection">46.2.9.4 Deferencing Method Call</h4>
-
-<p>Perl also lets you use a dereferenced scalar reference in a method
-call. That’s a mouthful, so let’s look at some code:
-</p>
-<pre class="verbatim"> $file->${ \'save' };
- $file->${ returns_scalar_ref() };
- $file->${ \( returns_scalar() ) };
- $file->${ returns_ref_to_sub_ref() };
-</pre>
-<p>This works if the dereference produces a string <em>or</em> a subroutine
-reference.
-</p>
-<hr>
-<a name="perlobj-Method-Calls-on-Filehandles"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlobj-Deferencing-Method-Call" accesskey="p"
rel="prev">perlobj Deferencing Method Call</a>, Up: <a
href="#perlobj-Method-Call-Variations" accesskey="u" rel="up">perlobj Method
Call Variations</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Method-Calls-on-Filehandles"></a>
-<h4 class="subsubsection">46.2.9.5 Method Calls on Filehandles</h4>
-
-<p>Under the hood, Perl filehandles are instances of the
<code>IO::Handle</code> or
-<code>IO::File</code> class. Once you have an open filehandle, you can call
-methods on it. Additionally, you can call methods on the <code>STDIN</code>,
-<code>STDOUT</code>, and <code>STDERR</code> filehandles.
-</p>
-<pre class="verbatim"> open my $fh, '>', 'path/to/file';
- $fh->autoflush();
- $fh->print('content');
-
- STDOUT->autoflush();
-</pre>
-<hr>
-<a name="perlobj-Invoking-Class-Methods"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-bless_002c-blessed_002c-and-ref" accesskey="n"
rel="next">perlobj <code>bless</code>, <code>blessed</code>, and
<code>ref</code></a>, Previous: <a href="#perlobj-Method-Call-Variations"
accesskey="p" rel="prev">perlobj Method Call Variations</a>, Up: <a
href="#perlobj-DESCRIPTION" accesskey="u" rel="up">perlobj DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Invoking-Class-Methods"></a>
-<h4 class="subsection">46.2.10 Invoking Class Methods</h4>
-
-<p>Because Perl allows you to use barewords for package names and
-subroutine names, it sometimes interprets a bareword’s meaning
-incorrectly. For example, the construct <code>Class->new()</code> can be
-interpreted as either <code>'Class'->new()</code> or
<code>Class()->new()</code>.
-In English, that second interpretation reads as "call a subroutine
-named Class(), then call new() as a method on the return value of
-Class()". If there is a subroutine named <code>Class()</code> in the
current
-namespace, Perl will always interpret <code>Class->new()</code> as the
second
-alternative: a call to <code>new()</code> on the object returned by a call to
-<code>Class()</code>
-</p>
-<p>You can force Perl to use the first interpretation (i.e. as a method
-call on the class named "Class") in two ways. First, you can append a
-<code>::</code> to the class name:
-</p>
-<pre class="verbatim"> Class::->new()
-</pre>
-<p>Perl will always interpret this as a method call.
-</p>
-<p>Alternatively, you can quote the class name:
-</p>
-<pre class="verbatim"> 'Class'->new()
-</pre>
-<p>Of course, if the class name is in a scalar Perl will do the right
-thing as well:
-</p>
-<pre class="verbatim"> my $class = 'Class';
- $class->new();
-</pre>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlobj-Indirect-Object-Syntax" accesskey="1">perlobj Indirect Object
Syntax</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlobj-Indirect-Object-Syntax"></a>
-<div class="header">
-<p>
-Up: <a href="#perlobj-Invoking-Class-Methods" accesskey="u" rel="up">perlobj
Invoking Class Methods</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Indirect-Object-Syntax"></a>
-<h4 class="subsubsection">46.2.10.1 Indirect Object Syntax</h4>
-
-<p><strong>Outside of the file handle case, use of this syntax is discouraged
as
-it can confuse the Perl interpreter. See below for more details.</strong>
-</p>
-<p>Perl supports another method invocation syntax called "indirect
object"
-notation. This syntax is called "indirect" because the method comes
-before the object it is being invoked on.
-</p>
-<p>This syntax can be used with any class or object method:
-</p>
-<pre class="verbatim"> my $file = new File $path, $data;
- save $file;
-</pre>
-<p>We recommend that you avoid this syntax, for several reasons.
-</p>
-<p>First, it can be confusing to read. In the above example, it’s not
-clear if <code>save</code> is a method provided by the <code>File</code> class
or simply a
-subroutine that expects a file object as its first argument.
-</p>
-<p>When used with class methods, the problem is even worse. Because Perl
-allows subroutine names to be written as barewords, Perl has to guess
-whether the bareword after the method is a class name or subroutine
-name. In other words, Perl can resolve the syntax as either
<code>File->new( $path, $data )</code> <strong>or</strong> <code>new( File(
$path, $data ) )</code>.
-</p>
-<p>To parse this code, Perl uses a heuristic based on what package names
-it has seen, what subroutines exist in the current package, what
-barewords it has previously seen, and other input. Needless to say,
-heuristics can produce very surprising results!
-</p>
-<p>Older documentation (and some CPAN modules) encouraged this syntax,
-particularly for constructors, so you may still find it in the wild.
-However, we encourage you to avoid using it in new code.
-</p>
-<p>You can force Perl to interpret the bareword as a class name by
-appending "::" to it, like we saw earlier:
-</p>
-<pre class="verbatim"> my $file = new File:: $path, $data;
-</pre>
-<hr>
-<a name="perlobj-bless_002c-blessed_002c-and-ref"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-The-UNIVERSAL-Class" accesskey="n" rel="next">perlobj
The UNIVERSAL Class</a>, Previous: <a href="#perlobj-Invoking-Class-Methods"
accesskey="p" rel="prev">perlobj Invoking Class Methods</a>, Up: <a
href="#perlobj-DESCRIPTION" accesskey="u" rel="up">perlobj DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="bless_002c-blessed_002c-and-ref"></a>
-<h4 class="subsection">46.2.11 <code>bless</code>, <code>blessed</code>, and
<code>ref</code></h4>
-
-<p>As we saw earlier, an object is simply a data structure that has been
-blessed into a class via the <code>bless</code> function. The
<code>bless</code> function
-can take either one or two arguments:
-</p>
-<pre class="verbatim"> my $object = bless {}, $class;
- my $object = bless {};
-</pre>
-<p>In the first form, the anonymous hash is being blessed into the class
-in <code>$class</code>. In the second form, the anonymous hash is blessed into
-the current package.
-</p>
-<p>The second form is strongly discouraged, because it breaks the ability
-of a subclass to reuse the parent’s constructor, but you may still run
-across it in existing code.
-</p>
-<p>If you want to know whether a particular scalar refers to an object,
-you can use the <code>blessed</code> function exported by <a
href="Scalar-Util.html#Top">(Scalar-Util)</a>, which
-is shipped with the Perl core.
-</p>
-<pre class="verbatim"> use Scalar::Util 'blessed';
-
- if ( defined blessed($thing) ) { ... }
-</pre>
-<p>If <code>$thing</code> refers to an object, then this function returns the
name
-of the package the object has been blessed into. If <code>$thing</code>
doesn’t
-contain a reference to a blessed object, the <code>blessed</code> function
-returns <code>undef</code>.
-</p>
-<p>Note that <code>blessed($thing)</code> will also return false if
<code>$thing</code> has
-been blessed into a class named "0". This is a possible, but quite
-pathological. Don’t create a class named "0" unless you know
what
-you’re doing.
-</p>
-<p>Similarly, Perl’s built-in <code>ref</code> function treats a
reference to a
-blessed object specially. If you call <code>ref($thing)</code> and
<code>$thing</code>
-holds a reference to an object, it will return the name of the class
-that the object has been blessed into.
-</p>
-<p>If you simply want to check that a variable contains an object
-reference, we recommend that you use <code>defined blessed($object)</code>,
since
-<code>ref</code> returns true values for all references, not just objects.
-</p>
-<hr>
-<a name="perlobj-The-UNIVERSAL-Class"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-AUTOLOAD" accesskey="n" rel="next">perlobj
AUTOLOAD</a>, Previous: <a href="#perlobj-bless_002c-blessed_002c-and-ref"
accesskey="p" rel="prev">perlobj <code>bless</code>, <code>blessed</code>, and
<code>ref</code></a>, Up: <a href="#perlobj-DESCRIPTION" accesskey="u"
rel="up">perlobj DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-UNIVERSAL-Class"></a>
-<h4 class="subsection">46.2.12 The UNIVERSAL Class</h4>
-
-<p>All classes automatically inherit from the <a
href="UNIVERSAL.html#Top">(UNIVERSAL)</a> class, which is
-built-in to the Perl core. This class provides a number of methods, all
-of which can be called on either a class or an object. You can also
-choose to override some of these methods in your class. If you do so,
-we recommend that you follow the built-in semantics described below.
-</p>
-<dl compact="compact">
-<dt>isa($class)</dt>
-<dd><a name="perlobj-isa_0028_0024class_0029"></a>
-<p>The <code>isa</code> method returns <em>true</em> if the object is a member
of the
-class in <code>$class</code>, or a member of a subclass of <code>$class</code>.
-</p>
-<p>If you override this method, it should never throw an exception.
-</p>
-</dd>
-<dt>DOES($role)</dt>
-<dd><a name="perlobj-DOES_0028_0024role_0029"></a>
-<p>The <code>DOES</code> method returns <em>true</em> if its object claims to
perform the
-role <code>$role</code>. By default, this is equivalent to <code>isa</code>.
This method is
-provided for use by object system extensions that implement roles, like
-<code>Moose</code> and <code>Role::Tiny</code>.
-</p>
-<p>You can also override <code>DOES</code> directly in your own classes. If you
-override this method, it should never throw an exception.
-</p>
-</dd>
-<dt>can($method)</dt>
-<dd><a name="perlobj-can_0028_0024method_0029"></a>
-<p>The <code>can</code> method checks to see if the class or object it was
called on
-has a method named <code>$method</code>. This checks for the method in the
class
-and all of its parents. If the method exists, then a reference to the
-subroutine is returned. If it does not then <code>undef</code> is returned.
-</p>
-<p>If your class responds to method calls via <code>AUTOLOAD</code>, you may
want to
-overload <code>can</code> to return a subroutine reference for methods which
your
-<code>AUTOLOAD</code> method handles.
-</p>
-<p>If you override this method, it should never throw an exception.
-</p>
-</dd>
-<dt>VERSION($need)</dt>
-<dd><a name="perlobj-VERSION_0028_0024need_0029"></a>
-<p>The <code>VERSION</code> method returns the version number of the class
-(package).
-</p>
-<p>If the <code>$need</code> argument is given then it will check that the
current
-version (as defined by the $VERSION variable in the package) is greater
-than or equal to <code>$need</code>; it will die if this is not the case. This
-method is called automatically by the <code>VERSION</code> form of
<code>use</code>.
-</p>
-<pre class="verbatim"> use Package 1.2 qw(some imported subs);
- # implies:
- Package->VERSION(1.2);
-</pre>
-<p>We recommend that you use this method to access another package’s
-version, rather than looking directly at <code>$Package::VERSION</code>. The
-package you are looking at could have overridden the <code>VERSION</code>
method.
-</p>
-<p>We also recommend using this method to check whether a module has a
-sufficient version. The internal implementation uses the <a
href="version.html#Top">(version)</a>
-module to make sure that different types of version numbers are
-compared correctly.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlobj-AUTOLOAD"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Destructors" accesskey="n" rel="next">perlobj
Destructors</a>, Previous: <a href="#perlobj-The-UNIVERSAL-Class" accesskey="p"
rel="prev">perlobj The UNIVERSAL Class</a>, Up: <a href="#perlobj-DESCRIPTION"
accesskey="u" rel="up">perlobj DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTOLOAD"></a>
-<h4 class="subsection">46.2.13 AUTOLOAD</h4>
-
-<p>If you call a method that doesn’t exist in a class, Perl will throw an
-error. However, if that class or any of its parent classes defines an
-<code>AUTOLOAD</code> method, that <code>AUTOLOAD</code> method is called
instead.
-</p>
-<p><code>AUTOLOAD</code> is called as a regular method, and the caller will
not know
-the difference. Whatever value your <code>AUTOLOAD</code> method returns is
-returned to the caller.
-</p>
-<p>The fully qualified method name that was called is available in the
-<code>$AUTOLOAD</code> package global for your class. Since this is a global,
if
-you want to refer to do it without a package name prefix under <code>strict
-'vars'</code>, you need to declare it.
-</p>
-<pre class="verbatim"> # XXX - this is a terrible way to implement accessors,
but it makes
- # for a simple example.
- our $AUTOLOAD;
- sub AUTOLOAD {
- my $self = shift;
-
- # Remove qualifier from original method name...
- my $called = $AUTOLOAD =~ s/.*:://r;
-
- # Is there an attribute of that name?
- die "No such attribute: $called"
- unless exists $self->{$called};
-
- # If so, return it...
- return $self->{$called};
- }
-
- sub DESTROY { } # see below
-</pre>
-<p>Without the <code>our $AUTOLOAD</code> declaration, this code will not
compile
-under the <a href="strict.html#Top">(strict)</a> pragma.
-</p>
-<p>As the comment says, this is not a good way to implement accessors.
-It’s slow and too clever by far. However, you may see this as a way to
-provide accessors in older Perl code. See <a href="#perlootut-NAME">perlootut
NAME</a> for
-recommendations on OO coding in Perl.
-</p>
-<p>If your class does have an <code>AUTOLOAD</code> method, we strongly
recommend
-that you override <code>can</code> in your class as well. Your overridden
<code>can</code>
-method should return a subroutine reference for any method that your
-<code>AUTOLOAD</code> responds to.
-</p>
-<hr>
-<a name="perlobj-Destructors"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Non_002dHash-Objects" accesskey="n" rel="next">perlobj
Non-Hash Objects</a>, Previous: <a href="#perlobj-AUTOLOAD" accesskey="p"
rel="prev">perlobj AUTOLOAD</a>, Up: <a href="#perlobj-DESCRIPTION"
accesskey="u" rel="up">perlobj DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Destructors"></a>
-<h4 class="subsection">46.2.14 Destructors</h4>
-
-<p>When the last reference to an object goes away, the object is
-destroyed. If you only have one reference to an object stored in a
-lexical scalar, the object is destroyed when that scalar goes out of
-scope. If you store the object in a package global, that object may not
-go out of scope until the program exits.
-</p>
-<p>If you want to do something when the object is destroyed, you can
-define a <code>DESTROY</code> method in your class. This method will always be
-called by Perl at the appropriate time, unless the method is empty.
-</p>
-<p>This is called just like any other method, with the object as the first
-argument. It does not receive any additional arguments. However, the
-<code>$_[0]</code> variable will be read-only in the destructor, so you cannot
-assign a value to it.
-</p>
-<p>If your <code>DESTROY</code> method throws an error, this error will be
ignored.
-It will not be sent to <code>STDERR</code> and it will not cause the program to
-die. However, if your destructor is running inside an <code>eval {}</code>
block,
-then the error will change the value of <code>$@</code>.
-</p>
-<p>Because <code>DESTROY</code> methods can be called at any time, you should
-localize any global variables you might update in your <code>DESTROY</code>. In
-particular, if you use <code>eval {}</code> you should localize
<code>$@</code>, and if you
-use <code>system</code> or backticks you should localize <code>$?</code>.
-</p>
-<p>If you define an <code>AUTOLOAD</code> in your class, then Perl will call
your
-<code>AUTOLOAD</code> to handle the <code>DESTROY</code> method. You can
prevent this by
-defining an empty <code>DESTROY</code>, like we did in the autoloading example.
-You can also check the value of <code>$AUTOLOAD</code> and return without doing
-anything when called to handle <code>DESTROY</code>.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlobj-Global-Destruction"
accesskey="1">perlobj Global Destruction</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlobj-Global-Destruction"></a>
-<div class="header">
-<p>
-Up: <a href="#perlobj-Destructors" accesskey="u" rel="up">perlobj
Destructors</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Global-Destruction"></a>
-<h4 class="subsubsection">46.2.14.1 Global Destruction</h4>
-
-<p>The order in which objects are destroyed during the global destruction
-before the program exits is unpredictable. This means that any objects
-contained by your object may already have been destroyed. You should
-check that a contained object is defined before calling a method on it:
-</p>
-<pre class="verbatim"> sub DESTROY {
- my $self = shift;
-
- $self->{handle}->close() if $self->{handle};
- }
-</pre>
-<p>You can use the <code>${^GLOBAL_PHASE}</code> variable to detect if you are
-currently in the global destruction phase:
-</p>
-<pre class="verbatim"> sub DESTROY {
- my $self = shift;
-
- return if ${^GLOBAL_PHASE} eq 'DESTRUCT';
-
- $self->{handle}->close();
- }
-</pre>
-<p>Note that this variable was added in Perl 5.14.0. If you want to detect
-the global destruction phase on older versions of Perl, you can use the
-<code>Devel::GlobalDestruction</code> module on CPAN.
-</p>
-<p>If your <code>DESTROY</code> method issues a warning during global
destruction,
-the Perl interpreter will append the string " during global
-destruction" to the warning.
-</p>
-<p>During global destruction, Perl will always garbage collect objects
-before unblessed references. See <a
href="#perlhacktips-PERL_005fDESTRUCT_005fLEVEL">perlhacktips
PERL_DESTRUCT_LEVEL</a>
-for more information about global destruction.
-</p>
-<hr>
-<a name="perlobj-Non_002dHash-Objects"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Inside_002dOut-objects" accesskey="n"
rel="next">perlobj Inside-Out objects</a>, Previous: <a
href="#perlobj-Destructors" accesskey="p" rel="prev">perlobj Destructors</a>,
Up: <a href="#perlobj-DESCRIPTION" accesskey="u" rel="up">perlobj
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Non_002dHash-Objects"></a>
-<h4 class="subsection">46.2.15 Non-Hash Objects</h4>
-
-<p>All the examples so far have shown objects based on a blessed hash.
-However, it’s possible to bless any type of data structure or referent,
-including scalars, globs, and subroutines. You may see this sort of
-thing when looking at code in the wild.
-</p>
-<p>Here’s an example of a module as a blessed scalar:
-</p>
-<pre class="verbatim"> package Time;
-
- use strict;
- use warnings;
-
- sub new {
- my $class = shift;
-
- my $time = time;
- return bless \$time, $class;
- }
-
- sub epoch {
- my $self = shift;
- return ${ $self };
- }
-
- my $time = Time->new();
- print $time->epoch();
-</pre>
-<hr>
-<a name="perlobj-Inside_002dOut-objects"></a>
-<div class="header">
-<p>
-Next: <a href="#perlobj-Pseudo_002dhashes" accesskey="n" rel="next">perlobj
Pseudo-hashes</a>, Previous: <a href="#perlobj-Non_002dHash-Objects"
accesskey="p" rel="prev">perlobj Non-Hash Objects</a>, Up: <a
href="#perlobj-DESCRIPTION" accesskey="u" rel="up">perlobj DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Inside_002dOut-objects"></a>
-<h4 class="subsection">46.2.16 Inside-Out objects</h4>
-
-<p>In the past, the Perl community experimented with a technique called
-"inside-out objects". An inside-out object stores its data outside of
-the object’s reference, indexed on a unique property of the object,
-such as its memory address, rather than in the object itself. This has
-the advantage of enforcing the encapsulation of object attributes,
-since their data is not stored in the object itself.
-</p>
-<p>This technique was popular for a while (and was recommended in Damian
-Conway’s <em>Perl Best Practices</em>), but never achieved universal
-adoption. The <a href="Object-InsideOut.html#Top">(Object-InsideOut)</a>
module on CPAN provides a
-comprehensive implementation of this technique, and you may see it or
-other inside-out modules in the wild.
-</p>
-<p>Here is a simple example of the technique, using the
-<a href="Hash-Util-FieldHash.html#Top">(Hash-Util-FieldHash)</a> core module.
This module was added to the core
-to support inside-out object implementations.
-</p>
-<pre class="verbatim"> package Time;
-
- use strict;
- use warnings;
-
- use Hash::Util::FieldHash 'fieldhash';
-
- fieldhash my %time_for;
-
- sub new {
- my $class = shift;
-
- my $self = bless \( my $object ), $class;
-
- $time_for{$self} = time;
-
- return $self;
- }
-
- sub epoch {
- my $self = shift;
-
- return $time_for{$self};
- }
-
- my $time = Time->new;
- print $time->epoch;
-</pre>
-<hr>
-<a name="perlobj-Pseudo_002dhashes"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlobj-Inside_002dOut-objects" accesskey="p"
rel="prev">perlobj Inside-Out objects</a>, Up: <a href="#perlobj-DESCRIPTION"
accesskey="u" rel="up">perlobj DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Pseudo_002dhashes"></a>
-<h4 class="subsection">46.2.17 Pseudo-hashes</h4>
-
-<p>The pseudo-hash feature was an experimental feature introduced in
-earlier versions of Perl and removed in 5.10.0. A pseudo-hash is an
-array reference which can be accessed using named keys like a hash. You
-may run in to some code in the wild which uses it. See the <a
href="fields.html#Top">(fields)</a>
-pragma for more information.
-</p>
-<hr>
-<a name="perlobj-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlobj-DESCRIPTION" accesskey="p" rel="prev">perlobj
DESCRIPTION</a>, Up: <a href="#perlobj" accesskey="u" rel="up">perlobj</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-23"></a>
-<h3 class="section">46.3 SEE ALSO</h3>
-
-<p>A kinder, gentler tutorial on object-oriented programming in Perl can
-be found in <a href="#perlootut-NAME">perlootut NAME</a>. You should also
check out <a href="perlmodlib.html#Top">(perlmodlib)</a> for
-some style guides on constructing both modules and classes.
-</p>
-<hr>
-<a name="perlootut"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop" accesskey="n" rel="next">perlop</a>, Previous: <a
href="#perlobj" accesskey="p" rel="prev">perlobj</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlootut-1"></a>
-<h2 class="chapter">47 perlootut</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlootut-NAME"
accesskey="1">perlootut NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-DATE"
accesskey="2">perlootut DATE</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-DESCRIPTION"
accesskey="3">perlootut DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS" accesskey="4">perlootut
OBJECT-ORIENTED FUNDAMENTALS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-PERL-OO-SYSTEMS"
accesskey="5">perlootut PERL OO SYSTEMS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-CONCLUSION"
accesskey="6">perlootut CONCLUSION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlootut-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-DATE" accesskey="n" rel="next">perlootut DATE</a>,
Up: <a href="#perlootut" accesskey="u" rel="up">perlootut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-46"></a>
-<h3 class="section">47.1 NAME</h3>
-
-<p>perlootut - Object-Oriented Programming in Perl Tutorial
-</p>
-<hr>
-<a name="perlootut-DATE"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-DESCRIPTION" accesskey="n" rel="next">perlootut
DESCRIPTION</a>, Previous: <a href="#perlootut-NAME" accesskey="p"
rel="prev">perlootut NAME</a>, Up: <a href="#perlootut" accesskey="u"
rel="up">perlootut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DATE-1"></a>
-<h3 class="section">47.2 DATE</h3>
-
-<p>This document was created in February, 2011, and the last major
-revision was in February, 2013.
-</p>
-<p>If you are reading this in the future then it’s possible that the
state
-of the art has changed. We recommend you start by reading the perlootut
-document in the latest stable release of Perl, rather than this
-version.
-</p>
-<hr>
-<a name="perlootut-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS" accesskey="n"
rel="next">perlootut OBJECT-ORIENTED FUNDAMENTALS</a>, Previous: <a
href="#perlootut-DATE" accesskey="p" rel="prev">perlootut DATE</a>, Up: <a
href="#perlootut" accesskey="u" rel="up">perlootut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-45"></a>
-<h3 class="section">47.3 DESCRIPTION</h3>
-
-<p>This document provides an introduction to object-oriented programming
-in Perl. It begins with a brief overview of the concepts behind object
-oriented design. Then it introduces several different OO systems from
-<a href="http://search.cpan.org";>CPAN</a> which build on top of what Perl
-provides.
-</p>
-<p>By default, Perl’s built-in OO system is very minimal, leaving you to
-do most of the work. This minimalism made a lot of sense in 1994, but
-in the years since Perl 5.0 we’ve seen a number of common patterns
-emerge in Perl OO. Fortunately, Perl’s flexibility has allowed a rich
-ecosystem of Perl OO systems to flourish.
-</p>
-<p>If you want to know how Perl OO works under the hood, the <a
href="#perlobj-NAME">perlobj NAME</a>
-document explains the nitty gritty details.
-</p>
-<p>This document assumes that you already understand the basics of Perl
-syntax, variable types, operators, and subroutine calls. If you don’t
-understand these concepts yet, please read <a href="#perlintro-NAME">perlintro
NAME</a> first. You
-should also read the <a href="#perlsyn-NAME">perlsyn NAME</a>, <a
href="#perlop-NAME">perlop NAME</a>, and <a href="#perlsub-NAME">perlsub
NAME</a> documents.
-</p>
-<hr>
-<a name="perlootut-OBJECT_002dORIENTED-FUNDAMENTALS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-PERL-OO-SYSTEMS" accesskey="n" rel="next">perlootut
PERL OO SYSTEMS</a>, Previous: <a href="#perlootut-DESCRIPTION" accesskey="p"
rel="prev">perlootut DESCRIPTION</a>, Up: <a href="#perlootut" accesskey="u"
rel="up">perlootut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="OBJECT_002dORIENTED-FUNDAMENTALS"></a>
-<h3 class="section">47.4 OBJECT-ORIENTED FUNDAMENTALS</h3>
-
-<p>Most object systems share a number of common concepts. You’ve probably
-heard terms like "class", "object, "method", and
"attribute" before.
-Understanding the concepts will make it much easier to read and write
-object-oriented code. If you’re already familiar with these terms, you
-should still skim this section, since it explains each concept in terms
-of Perl’s OO implementation.
-</p>
-<p>Perl’s OO system is class-based. Class-based OO is fairly common.
It’s
-used by Java, C++, C#, Python, Ruby, and many other languages. There
-are other object orientation paradigms as well. JavaScript is the most
-popular language to use another paradigm. JavaScript’s OO system is
-prototype-based.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlootut-Object"
accesskey="1">perlootut Object</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-Class"
accesskey="2">perlootut Class</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-Methods"
accesskey="3">perlootut Methods</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-Attributes"
accesskey="4">perlootut Attributes</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-Polymorphism"
accesskey="5">perlootut Polymorphism</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-Inheritance"
accesskey="6">perlootut Inheritance</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-Encapsulation"
accesskey="7">perlootut Encapsulation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-Composition"
accesskey="8">perlootut Composition</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-Roles"
accesskey="9">perlootut Roles</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-When-to-Use-OO">perlootut When to Use
OO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlootut-Object"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-Class" accesskey="n" rel="next">perlootut Class</a>,
Up: <a href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS" accesskey="u"
rel="up">perlootut OBJECT-ORIENTED FUNDAMENTALS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Object"></a>
-<h4 class="subsection">47.4.1 Object</h4>
-
-<p>An <strong>object</strong> is a data structure that bundles together data
and
-subroutines which operate on that data. An object’s data is called
-<strong>attributes</strong>, and its subroutines are called
<strong>methods</strong>. An object can
-be thought of as a noun (a person, a web service, a computer).
-</p>
-<p>An object represents a single discrete thing. For example, an object
-might represent a file. The attributes for a file object might include
-its path, content, and last modification time. If we created an object
-to represent <samp>/etc/hostname</samp> on a machine named
"foo.example.com",
-that object’s path would be "/etc/hostname", its content would
be
-"foo\n", and it’s last modification time would be 1304974868
seconds
-since the beginning of the epoch.
-</p>
-<p>The methods associated with a file might include <code>rename()</code> and
-<code>write()</code>.
-</p>
-<p>In Perl most objects are hashes, but the OO systems we recommend keep
-you from having to worry about this. In practice, it’s best to consider
-an object’s internal data structure opaque.
-</p>
-<hr>
-<a name="perlootut-Class"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-Methods" accesskey="n" rel="next">perlootut
Methods</a>, Previous: <a href="#perlootut-Object" accesskey="p"
rel="prev">perlootut Object</a>, Up: <a
href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS" accesskey="u"
rel="up">perlootut OBJECT-ORIENTED FUNDAMENTALS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Class"></a>
-<h4 class="subsection">47.4.2 Class</h4>
-
-<p>A <strong>class</strong> defines the behavior of a category of objects. A
class is a
-name for a category (like "File"), and a class also defines the
-behavior of objects in that category.
-</p>
-<p>All objects belong to a specific class. For example, our
-<samp>/etc/hostname</samp> object belongs to the <code>File</code> class. When
we want to
-create a specific object, we start with its class, and
<strong>construct</strong> or
-<strong>instantiate</strong> an object. A specific object is often referred to
as an
-<strong>instance</strong> of a class.
-</p>
-<p>In Perl, any package can be a class. The difference between a package
-which is a class and one which isn’t is based on how the package is
-used. Here’s our "class declaration" for the <code>File</code>
class:
-</p>
-<pre class="verbatim"> package File;
-</pre>
-<p>In Perl, there is no special keyword for constructing an object.
-However, most OO modules on CPAN use a method named <code>new()</code> to
-construct a new object:
-</p>
-<pre class="verbatim"> my $hostname = File->new(
- path => '/etc/hostname',
- content => "foo\n",
- last_mod_time => 1304974868,
- );
-</pre>
-<p>(Don’t worry about that <code>-></code> operator, it will be
explained
-later.)
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlootut-Blessing"
accesskey="1">perlootut Blessing</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-Constructor"
accesskey="2">perlootut Constructor</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlootut-Blessing"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-Constructor" accesskey="n" rel="next">perlootut
Constructor</a>, Up: <a href="#perlootut-Class" accesskey="u"
rel="up">perlootut Class</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Blessing"></a>
-<h4 class="subsubsection">47.4.2.1 Blessing</h4>
-
-<p>As we said earlier, most Perl objects are hashes, but an object can be
-an instance of any Perl data type (scalar, array, etc.). Turning a
-plain data structure into an object is done by <strong>blessing</strong> that
data
-structure using Perl’s <code>bless</code> function.
-</p>
-<p>While we strongly suggest you don’t build your objects from scratch,
-you should know the term <strong>bless</strong>. A <strong>blessed</strong>
data structure (aka "a
-referent") is an object. We sometimes say that an object has been
-"blessed into a class".
-</p>
-<p>Once a referent has been blessed, the <code>blessed</code> function from the
-<a href="Scalar-Util.html#Top">(Scalar-Util)</a> core module can tell us its
class name. This subroutine
-returns an object’s class when passed an object, and false otherwise.
-</p>
-<pre class="verbatim"> use Scalar::Util 'blessed';
-
- print blessed($hash); # undef
- print blessed($hostname); # File
-</pre>
-<hr>
-<a name="perlootut-Constructor"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlootut-Blessing" accesskey="p" rel="prev">perlootut
Blessing</a>, Up: <a href="#perlootut-Class" accesskey="u" rel="up">perlootut
Class</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Constructor"></a>
-<h4 class="subsubsection">47.4.2.2 Constructor</h4>
-
-<p>A <strong>constructor</strong> creates a new object. In Perl, a
class’s constructor
-is just another method, unlike some other languages, which provide
-syntax for constructors. Most Perl classes use <code>new</code> as the name for
-their constructor:
-</p>
-<pre class="verbatim"> my $file = File->new(...);
-</pre>
-<hr>
-<a name="perlootut-Methods"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-Attributes" accesskey="n" rel="next">perlootut
Attributes</a>, Previous: <a href="#perlootut-Class" accesskey="p"
rel="prev">perlootut Class</a>, Up: <a
href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS" accesskey="u"
rel="up">perlootut OBJECT-ORIENTED FUNDAMENTALS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Methods"></a>
-<h4 class="subsection">47.4.3 Methods</h4>
-
-<p>You already learned that a <strong>method</strong> is a subroutine that
operates on
-an object. You can think of a method as the things that an object can
-<em>do</em>. If an object is a noun, then methods are its verbs (save, print,
-open).
-</p>
-<p>In Perl, methods are simply subroutines that live in a class’s
package.
-Methods are always written to receive the object as their first
-argument:
-</p>
-<pre class="verbatim"> sub print_info {
- my $self = shift;
-
- print "This file is at ", $self->path, "\n";
- }
-
- $file->print_info;
- # The file is at /etc/hostname
-</pre>
-<p>What makes a method special is <em>how it’s called</em>. The arrow
operator
-(<code>-></code>) tells Perl that we are calling a method.
-</p>
-<p>When we make a method call, Perl arranges for the method’s
<strong>invocant</strong>
-to be passed as the first argument. <strong>Invocant</strong> is a fancy name
for the
-thing on the left side of the arrow. The invocant can either be a class
-name or an object. We can also pass additional arguments to the method:
-</p>
-<pre class="verbatim"> sub print_info {
- my $self = shift;
- my $prefix = shift // "This file is at ";
-
- print $prefix, ", ", $self->path, "\n";
- }
-
- $file->print_info("The file is located at ");
- # The file is located at /etc/hostname
-</pre>
-<hr>
-<a name="perlootut-Attributes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-Polymorphism" accesskey="n" rel="next">perlootut
Polymorphism</a>, Previous: <a href="#perlootut-Methods" accesskey="p"
rel="prev">perlootut Methods</a>, Up: <a
href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS" accesskey="u"
rel="up">perlootut OBJECT-ORIENTED FUNDAMENTALS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Attributes-1"></a>
-<h4 class="subsection">47.4.4 Attributes</h4>
-
-<p>Each class can define its <strong>attributes</strong>. When we instantiate
an object,
-we assign values to those attributes. For example, every <code>File</code>
object
-has a path. Attributes are sometimes called <strong>properties</strong>.
-</p>
-<p>Perl has no special syntax for attributes. Under the hood, attributes
-are often stored as keys in the object’s underlying hash, but don’t
-worry about this.
-</p>
-<p>We recommend that you only access attributes via <strong>accessor</strong>
methods.
-These are methods that can get or set the value of each attribute. We
-saw this earlier in the <code>print_info()</code> example, which calls
<code>$self->path</code>.
-</p>
-<p>You might also see the terms <strong>getter</strong> and
<strong>setter</strong>. These are two
-types of accessors. A getter gets the attribute’s value, while a setter
-sets it. Another term for a setter is <strong>mutator</strong>
-</p>
-<p>Attributes are typically defined as read-only or read-write. Read-only
-attributes can only be set when the object is first created, while
-read-write attributes can be altered at any time.
-</p>
-<p>The value of an attribute may itself be another object. For example,
-instead of returning its last mod time as a number, the <code>File</code> class
-could return a <a href="DateTime.html#Top">(DateTime)</a> object representing
that value.
-</p>
-<p>It’s possible to have a class that does not expose any publicly
-settable attributes. Not every class has attributes and methods.
-</p>
-<hr>
-<a name="perlootut-Polymorphism"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-Inheritance" accesskey="n" rel="next">perlootut
Inheritance</a>, Previous: <a href="#perlootut-Attributes" accesskey="p"
rel="prev">perlootut Attributes</a>, Up: <a
href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS" accesskey="u"
rel="up">perlootut OBJECT-ORIENTED FUNDAMENTALS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Polymorphism"></a>
-<h4 class="subsection">47.4.5 Polymorphism</h4>
-
-<p><strong>Polymorphism</strong> is a fancy way of saying that objects from two
-different classes share an API. For example, we could have <code>File</code>
and
-<code>WebPage</code> classes which both have a <code>print_content()</code>
method. This
-method might produce different output for each class, but they share a
-common interface.
-</p>
-<p>While the two classes may differ in many ways, when it comes to the
-<code>print_content()</code> method, they are the same. This means that we can
-try to call the <code>print_content()</code> method on an object of either
class,
-and <strong>we don’t have to know what class the object belongs
to!</strong>
-</p>
-<p>Polymorphism is one of the key concepts of object-oriented design.
-</p>
-<hr>
-<a name="perlootut-Inheritance"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-Encapsulation" accesskey="n" rel="next">perlootut
Encapsulation</a>, Previous: <a href="#perlootut-Polymorphism" accesskey="p"
rel="prev">perlootut Polymorphism</a>, Up: <a
href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS" accesskey="u"
rel="up">perlootut OBJECT-ORIENTED FUNDAMENTALS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Inheritance-1"></a>
-<h4 class="subsection">47.4.6 Inheritance</h4>
-
-<p><strong>Inheritance</strong> lets you create a specialized version of an
existing
-class. Inheritance lets the new class reuse the methods and attributes
-of another class.
-</p>
-<p>For example, we could create an <code>File::MP3</code> class which
<strong>inherits</strong>
-from <code>File</code>. An <code>File::MP3</code> <strong>is-a</strong>
<em>more specific</em> type of <code>File</code>.
-All mp3 files are files, but not all files are mp3 files.
-</p>
-<p>We often refer to inheritance relationships as
<strong>parent-child</strong> or
-<code>superclass/subclass</code> relationships. Sometimes we say that the child
-has an <strong>is-a</strong> relationship with its parent class.
-</p>
-<p><code>File</code> is a <strong>superclass</strong> of
<code>File::MP3</code>, and <code>File::MP3</code> is a
-<strong>subclass</strong> of <code>File</code>.
-</p>
-<pre class="verbatim"> package File::MP3;
-
- use parent 'File';
-</pre>
-<p>The <a href="parent.html#Top">(parent)</a> module is one of several ways
that Perl lets you define
-inheritance relationships.
-</p>
-<p>Perl allows multiple inheritance, which means that a class can inherit
-from multiple parents. While this is possible, we strongly recommend
-against it. Generally, you can use <strong>roles</strong> to do everything you
can do
-with multiple inheritance, but in a cleaner way.
-</p>
-<p>Note that there’s nothing wrong with defining multiple subclasses of a
-given class. This is both common and safe. For example, we might define
-<code>File::MP3::FixedBitrate</code> and
<code>File::MP3::VariableBitrate</code> classes to
-distinguish between different types of mp3 file.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlootut-Overriding-methods-and-method-resolution"
accesskey="1">perlootut Overriding methods and method
resolution</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlootut-Overriding-methods-and-method-resolution"></a>
-<div class="header">
-<p>
-Up: <a href="#perlootut-Inheritance" accesskey="u" rel="up">perlootut
Inheritance</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Overriding-methods-and-method-resolution"></a>
-<h4 class="subsubsection">47.4.6.1 Overriding methods and method
resolution</h4>
-
-<p>Inheritance allows two classes to share code. By default, every method
-in the parent class is also available in the child. The child can
-explicitly <strong>override</strong> a parent’s method to provide its own
-implementation. For example, if we have an <code>File::MP3</code> object, it
has
-the <code>print_info()</code> method from <code>File</code>:
-</p>
-<pre class="verbatim"> my $cage = File::MP3->new(
- path => 'mp3s/My-Body-Is-a-Cage.mp3',
- content => $mp3_data,
- last_mod_time => 1304974868,
- title => 'My Body Is a Cage',
- );
-
- $cage->print_info;
- # The file is at mp3s/My-Body-Is-a-Cage.mp3
-</pre>
-<p>If we wanted to include the mp3’s title in the greeting, we could
-override the method:
-</p>
-<pre class="verbatim"> package File::MP3;
-
- use parent 'File';
-
- sub print_info {
- my $self = shift;
-
- print "This file is at ", $self->path, "\n";
- print "Its title is ", $self->title, "\n";
- }
-
- $cage->print_info;
- # The file is at mp3s/My-Body-Is-a-Cage.mp3
- # Its title is My Body Is a Cage
-</pre>
-<p>The process of determining what method should be used is called
-<strong>method resolution</strong>. What Perl does is look at the
object’s class
-first (<code>File::MP3</code> in this case). If that class defines the method,
-then that class’s version of the method is called. If not, Perl looks
-at each parent class in turn. For <code>File::MP3</code>, its only parent is
-<code>File</code>. If <code>File::MP3</code> does not define the method, but
<code>File</code> does,
-then Perl calls the method in <code>File</code>.
-</p>
-<p>If <code>File</code> inherited from <code>DataSource</code>, which
inherited from <code>Thing</code>,
-then Perl would keep looking "up the chain" if necessary.
-</p>
-<p>It is possible to explicitly call a parent method from a child:
-</p>
-<pre class="verbatim"> package File::MP3;
-
- use parent 'File';
-
- sub print_info {
- my $self = shift;
-
- $self->SUPER::print_info();
- print "Its title is ", $self->title, "\n";
- }
-</pre>
-<p>The <code>SUPER::</code> bit tells Perl to look for the
<code>print_info()</code> in the
-<code>File::MP3</code> class’s inheritance chain. When it finds the
parent class
-that implements this method, the method is called.
-</p>
-<p>We mentioned multiple inheritance earlier. The main problem with
-multiple inheritance is that it greatly complicates method resolution.
-See <a href="#perlobj-NAME">perlobj NAME</a> for more details.
-</p>
-<hr>
-<a name="perlootut-Encapsulation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-Composition" accesskey="n" rel="next">perlootut
Composition</a>, Previous: <a href="#perlootut-Inheritance" accesskey="p"
rel="prev">perlootut Inheritance</a>, Up: <a
href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS" accesskey="u"
rel="up">perlootut OBJECT-ORIENTED FUNDAMENTALS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Encapsulation"></a>
-<h4 class="subsection">47.4.7 Encapsulation</h4>
-
-<p><strong>Encapsulation</strong> is the idea that an object is opaque. When
another
-developer uses your class, they don’t need to know <em>how</em> it is
-implemented, they just need to know <em>what</em> it does.
-</p>
-<p>Encapsulation is important for several reasons. First, it allows you to
-separate the public API from the private implementation. This means you
-can change that implementation without breaking the API.
-</p>
-<p>Second, when classes are well encapsulated, they become easier to
-subclass. Ideally, a subclass uses the same APIs to access object data
-that its parent class uses. In reality, subclassing sometimes involves
-violating encapsulation, but a good API can minimize the need to do
-this.
-</p>
-<p>We mentioned earlier that most Perl objects are implemented as hashes
-under the hood. The principle of encapsulation tells us that we should
-not rely on this. Instead, we should use accessor methods to access the
-data in that hash. The object systems that we recommend below all
-automate the generation of accessor methods. If you use one of them,
-you should never have to access the object as a hash directly.
-</p>
-<hr>
-<a name="perlootut-Composition"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-Roles" accesskey="n" rel="next">perlootut Roles</a>,
Previous: <a href="#perlootut-Encapsulation" accesskey="p" rel="prev">perlootut
Encapsulation</a>, Up: <a href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS"
accesskey="u" rel="up">perlootut OBJECT-ORIENTED FUNDAMENTALS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Composition"></a>
-<h4 class="subsection">47.4.8 Composition</h4>
-
-<p>In object-oriented code, we often find that one object references
-another object. This is called <strong>composition</strong>, or a
<strong>has-a</strong>
-relationship.
-</p>
-<p>Earlier, we mentioned that the <code>File</code> class’s
<code>last_mod_time</code>
-accessor could return a <a href="DateTime.html#Top">(DateTime)</a> object.
This is a perfect example
-of composition. We could go even further, and make the <code>path</code> and
-<code>content</code> accessors return objects as well. The <code>File</code>
class would
-then be <strong>composed</strong> of several other objects.
-</p>
-<hr>
-<a name="perlootut-Roles"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-When-to-Use-OO" accesskey="n" rel="next">perlootut
When to Use OO</a>, Previous: <a href="#perlootut-Composition" accesskey="p"
rel="prev">perlootut Composition</a>, Up: <a
href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS" accesskey="u"
rel="up">perlootut OBJECT-ORIENTED FUNDAMENTALS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Roles"></a>
-<h4 class="subsection">47.4.9 Roles</h4>
-
-<p><strong>Roles</strong> are something that a class <em>does</em>, rather
than something that
-it <em>is</em>. Roles are relatively new to Perl, but have become rather
-popular. Roles are <strong>applied</strong> to classes. Sometimes we say that
classes
-<strong>consume</strong> roles.
-</p>
-<p>Roles are an alternative to inheritance for providing polymorphism.
-Let’s assume we have two classes, <code>Radio</code> and
<code>Computer</code>. Both of
-these things have on/off switches. We want to model that in our class
-definitions.
-</p>
-<p>We could have both classes inherit from a common parent, like
-<code>Machine</code>, but not all machines have on/off switches. We could
create
-a parent class called <code>HasOnOffSwitch</code>, but that is very artificial.
-Radios and computers are not specializations of this parent. This
-parent is really a rather ridiculous creation.
-</p>
-<p>This is where roles come in. It makes a lot of sense to create a
-<code>HasOnOffSwitch</code> role and apply it to both classes. This role would
-define a known API like providing <code>turn_on()</code> and
<code>turn_off()</code>
-methods.
-</p>
-<p>Perl does not have any built-in way to express roles. In the past,
-people just bit the bullet and used multiple inheritance. Nowadays,
-there are several good choices on CPAN for using roles.
-</p>
-<hr>
-<a name="perlootut-When-to-Use-OO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlootut-Roles" accesskey="p" rel="prev">perlootut
Roles</a>, Up: <a href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS"
accesskey="u" rel="up">perlootut OBJECT-ORIENTED FUNDAMENTALS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="When-to-Use-OO"></a>
-<h4 class="subsection">47.4.10 When to Use OO</h4>
-
-<p>Object Orientation is not the best solution to every problem. In <em>Perl
-Best Practices</em> (copyright 2004, Published by O’Reilly Media, Inc.),
-Damian Conway provides a list of criteria to use when deciding if OO is
-the right fit for your problem:
-</p>
-<ul>
-<li> The system being designed is large, or is likely to become large.
-
-</li><li> The data can be aggregated into obvious structures, especially if
-there’s a large amount of data in each aggregate.
-
-</li><li> The various types of data aggregate form a natural hierarchy that
-facilitates the use of inheritance and polymorphism.
-
-</li><li> You have a piece of data on which many different operations are
-applied.
-
-</li><li> You need to perform the same general operations on related types of
-data, but with slight variations depending on the specific type of data
-the operations are applied to.
-
-</li><li> It’s likely you’ll have to add new data types later.
-
-</li><li> The typical interactions between pieces of data are best represented
by
-operators.
-
-</li><li> The implementation of individual components of the system is likely
to
-change over time.
-
-</li><li> The system design is already object-oriented.
-
-</li><li> Large numbers of other programmers will be using your code modules.
-
-</li></ul>
-
-<hr>
-<a name="perlootut-PERL-OO-SYSTEMS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-CONCLUSION" accesskey="n" rel="next">perlootut
CONCLUSION</a>, Previous: <a href="#perlootut-OBJECT_002dORIENTED-FUNDAMENTALS"
accesskey="p" rel="prev">perlootut OBJECT-ORIENTED FUNDAMENTALS</a>, Up: <a
href="#perlootut" accesskey="u" rel="up">perlootut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PERL-OO-SYSTEMS"></a>
-<h3 class="section">47.5 PERL OO SYSTEMS</h3>
-
-<p>As we mentioned before, Perl’s built-in OO system is very minimal, but
-also quite flexible. Over the years, many people have developed systems
-which build on top of Perl’s built-in system to provide more features
-and convenience.
-</p>
-<p>We strongly recommend that you use one of these systems. Even the most
-minimal of them eliminates a lot of repetitive boilerplate. There’s
-really no good reason to write your classes from scratch in Perl.
-</p>
-<p>If you are interested in the guts underlying these systems, check out
-<a href="#perlobj-NAME">perlobj NAME</a>.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlootut-Moose"
accesskey="1">perlootut Moose</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-Class_003a_003aAccessor" accesskey="2">perlootut
Class::Accessor</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-Class_003a_003aTiny" accesskey="3">perlootut
Class::Tiny</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-Role_003a_003aTiny" accesskey="4">perlootut
Role::Tiny</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlootut-OO-System-Summary" accesskey="5">perlootut OO System
Summary</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlootut-Other-OO-Systems"
accesskey="6">perlootut Other OO Systems</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlootut-Moose"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-Class_003a_003aAccessor" accesskey="n"
rel="next">perlootut Class::Accessor</a>, Up: <a
href="#perlootut-PERL-OO-SYSTEMS" accesskey="u" rel="up">perlootut PERL OO
SYSTEMS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Moose"></a>
-<h4 class="subsection">47.5.1 Moose</h4>
-
-<p><a href="Moose.html#Top">(Moose)</a> bills itself as a "postmodern
object system for Perl 5". Don’t
-be scared, the "postmodern" label is a callback to Larry’s
description
-of Perl as "the first postmodern computer language".
-</p>
-<p><code>Moose</code> provides a complete, modern OO system. Its biggest
influence
-is the Common Lisp Object System, but it also borrows ideas from
-Smalltalk and several other languages. <code>Moose</code> was created by Stevan
-Little, and draws heavily from his work on the Perl 6 OO design.
-</p>
-<p>Here is our <code>File</code> class using <code>Moose</code>:
-</p>
-<pre class="verbatim"> package File;
- use Moose;
-
- has path => ( is => 'ro' );
- has content => ( is => 'ro' );
- has last_mod_time => ( is => 'ro' );
-
- sub print_info {
- my $self = shift;
-
- print "This file is at ", $self->path, "\n";
- }
-</pre>
-<p><code>Moose</code> provides a number of features:
-</p>
-<ul>
-<li> Declarative sugar
-
-<p><code>Moose</code> provides a layer of declarative "sugar" for
defining classes.
-That sugar is just a set of exported functions that make declaring how
-your class works simpler and more palatable. This lets you describe
-<em>what</em> your class is, rather than having to tell Perl <em>how</em> to
-implement your class.
-</p>
-<p>The <code>has()</code> subroutine declares an attribute, and
<code>Moose</code>
-automatically creates accessors for these attributes. It also takes
-care of creating a <code>new()</code> method for you. This constructor knows
-about the attributes you declared, so you can set them when creating a
-new <code>File</code>.
-</p>
-</li><li> Roles built-in
-
-<p><code>Moose</code> lets you define roles the same way you define classes:
-</p>
-<pre class="verbatim"> package HasOnOfSwitch;
- use Moose::Role;
-
- has is_on => (
- is => 'rw',
- isa => 'Bool',
- );
-
- sub turn_on {
- my $self = shift;
- $self->is_on(1);
- }
-
- sub turn_off {
- my $self = shift;
- $self->is_on(0);
- }
-</pre>
-</li><li> A miniature type system
-
-<p>In the example above, you can see that we passed <code>isa =>
'Bool'</code>
-to <code>has()</code> when creating our <code>is_on</code> attribute. This
tells <code>Moose</code>
-that this attribute must be a boolean value. If we try to set it to an
-invalid value, our code will throw an error.
-</p>
-</li><li> Full introspection and manipulation
-
-<p>Perl’s built-in introspection features are fairly minimal.
<code>Moose</code>
-builds on top of them and creates a full introspection layer for your
-classes. This lets you ask questions like "what methods does the File
-class implement?" It also lets you modify your classes
-programmatically.
-</p>
-</li><li> Self-hosted and extensible
-
-<p><code>Moose</code> describes itself using its own introspection API. Besides
-being a cool trick, this means that you can extend <code>Moose</code> using
-<code>Moose</code> itself.
-</p>
-</li><li> Rich ecosystem
-
-<p>There is a rich ecosystem of <code>Moose</code> extensions on CPAN under the
-<a href="http://search.cpan.org/search?query=MooseX&mode=dist";>MooseX</a>
-namespace. In addition, many modules on CPAN already use <code>Moose</code>,
-providing you with lots of examples to learn from.
-</p>
-</li><li> Many more features
-
-<p><code>Moose</code> is a very powerful tool, and we can’t cover all of
its
-features here. We encourage you to learn more by reading the <code>Moose</code>
-documentation, starting with
-<a href="http://search.cpan.org/perldoc?Moose::Manual";>Moose::Manual</a>.
-</p>
-</li></ul>
-
-<p>Of course, <code>Moose</code> isn’t perfect.
-</p>
-<p><code>Moose</code> can make your code slower to load. <code>Moose</code>
itself is not
-small, and it does a <em>lot</em> of code generation when you define your
-class. This code generation means that your runtime code is as fast as
-it can be, but you pay for this when your modules are first loaded.
-</p>
-<p>This load time hit can be a problem when startup speed is important,
-such as with a command-line script or a "plain vanilla" CGI script
that
-must be loaded each time it is executed.
-</p>
-<p>Before you panic, know that many people do use <code>Moose</code> for
-command-line tools and other startup-sensitive code. We encourage you
-to try <code>Moose</code> out first before worrying about startup speed.
-</p>
-<p><code>Moose</code> also has several dependencies on other modules. Most of
these
-are small stand-alone modules, a number of which have been spun off
-from <code>Moose</code>. <code>Moose</code> itself, and some of its
dependencies, require a
-compiler. If you need to install your software on a system without a
-compiler, or if having <em>any</em> dependencies is a problem, then
<code>Moose</code>
-may not be right for you.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlootut-Moo"
accesskey="1">perlootut Moo</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlootut-Moo"></a>
-<div class="header">
-<p>
-Up: <a href="#perlootut-Moose" accesskey="u" rel="up">perlootut Moose</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Moo"></a>
-<h4 class="subsubsection">47.5.1.1 Moo</h4>
-
-<p>If you try <code>Moose</code> and find that one of these issues is
preventing you
-from using <code>Moose</code>, we encourage you to consider <a
href="Moo.html#Top">(Moo)</a> next. <code>Moo</code>
-implements a subset of <code>Moose</code>’s functionality in a simpler
package.
-For most features that it does implement, the end-user API is
-<em>identical</em> to <code>Moose</code>, meaning you can switch from
<code>Moo</code> to
-<code>Moose</code> quite easily.
-</p>
-<p><code>Moo</code> does not implement most of <code>Moose</code>’s
introspection API, so it’s
-often faster when loading your modules. Additionally, none of its
-dependencies require XS, so it can be installed on machines without a
-compiler.
-</p>
-<p>One of <code>Moo</code>’s most compelling features is its
interoperability with
-<code>Moose</code>. When someone tries to use <code>Moose</code>’s
introspection API on a
-<code>Moo</code> class or role, it is transparently inflated into a
<code>Moose</code>
-class or role. This makes it easier to incorporate <code>Moo</code>-using code
-into a <code>Moose</code> code base and vice versa.
-</p>
-<p>For example, a <code>Moose</code> class can subclass a <code>Moo</code>
class using
-<code>extends</code> or consume a <code>Moo</code> role using
<code>with</code>.
-</p>
-<p>The <code>Moose</code> authors hope that one day <code>Moo</code> can be
made obsolete by
-improving <code>Moose</code> enough, but for now it provides a worthwhile
-alternative to <code>Moose</code>.
-</p>
-<hr>
-<a name="perlootut-Class_003a_003aAccessor"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-Class_003a_003aTiny" accesskey="n"
rel="next">perlootut Class::Tiny</a>, Previous: <a href="#perlootut-Moose"
accesskey="p" rel="prev">perlootut Moose</a>, Up: <a
href="#perlootut-PERL-OO-SYSTEMS" accesskey="u" rel="up">perlootut PERL OO
SYSTEMS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Class_003a_003aAccessor"></a>
-<h4 class="subsection">47.5.2 Class::Accessor</h4>
-
-<p><a href="Class-Accessor.html#Top">(Class-Accessor)</a> is the polar
opposite of <code>Moose</code>. It provides very
-few features, nor is it self-hosting.
-</p>
-<p>It is, however, very simple, pure Perl, and it has no non-core
-dependencies. It also provides a "Moose-like" API on demand for the
-features it supports.
-</p>
-<p>Even though it doesn’t do much, it is still preferable to writing your
-own classes from scratch.
-</p>
-<p>Here’s our <code>File</code> class with <code>Class::Accessor</code>:
-</p>
-<pre class="verbatim"> package File;
- use Class::Accessor 'antlers';
-
- has path => ( is => 'ro' );
- has content => ( is => 'ro' );
- has last_mod_time => ( is => 'ro' );
-
- sub print_info {
- my $self = shift;
-
- print "This file is at ", $self->path, "\n";
- }
-</pre>
-<p>The <code>antlers</code> import flag tells <code>Class::Accessor</code>
that you want to
-define your attributes using <code>Moose</code>-like syntax. The only parameter
-that you can pass to <code>has</code> is <code>is</code>. We recommend that
you use this
-Moose-like syntax if you choose <code>Class::Accessor</code> since it means you
-will have a smoother upgrade path if you later decide to move to
-<code>Moose</code>.
-</p>
-<p>Like <code>Moose</code>, <code>Class::Accessor</code> generates accessor
methods and a
-constructor for your class.
-</p>
-<hr>
-<a name="perlootut-Class_003a_003aTiny"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-Role_003a_003aTiny" accesskey="n"
rel="next">perlootut Role::Tiny</a>, Previous: <a
href="#perlootut-Class_003a_003aAccessor" accesskey="p" rel="prev">perlootut
Class::Accessor</a>, Up: <a href="#perlootut-PERL-OO-SYSTEMS" accesskey="u"
rel="up">perlootut PERL OO SYSTEMS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Class_003a_003aTiny"></a>
-<h4 class="subsection">47.5.3 Class::Tiny</h4>
-
-<p>Finally, we have <a href="Class-Tiny.html#Top">(Class-Tiny)</a>. This
module truly lives up to its
-name. It has an incredibly minimal API and absolutely no dependencies
-on any recent Perl. Still, we think it’s a lot easier to use than writing
-your own OO code from scratch.
-</p>
-<p>Here’s our <code>File</code> class once more:
-</p>
-<pre class="verbatim"> package File;
- use Class::Tiny qw( path content last_mod_time );
-
- sub print_info {
- my $self = shift;
-
- print "This file is at ", $self->path, "\n";
- }
-</pre>
-<p>That’s it!
-</p>
-<p>With <code>Class::Tiny</code>, all accessors are read-write. It generates a
-constructor for you, as well as the accessors you define.
-</p>
-<p>You can also use <a
href="Class-Tiny-Antlers.html#Top">(Class-Tiny-Antlers)</a> for
<code>Moose</code>-like syntax.
-</p>
-<hr>
-<a name="perlootut-Role_003a_003aTiny"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-OO-System-Summary" accesskey="n"
rel="next">perlootut OO System Summary</a>, Previous: <a
href="#perlootut-Class_003a_003aTiny" accesskey="p" rel="prev">perlootut
Class::Tiny</a>, Up: <a href="#perlootut-PERL-OO-SYSTEMS" accesskey="u"
rel="up">perlootut PERL OO SYSTEMS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Role_003a_003aTiny"></a>
-<h4 class="subsection">47.5.4 Role::Tiny</h4>
-
-<p>As we mentioned before, roles provide an alternative to inheritance,
-but Perl does not have any built-in role support. If you choose to use
-Moose, it comes with a full-fledged role implementation. However, if
-you use one of our other recommended OO modules, you can still use
-roles with <a href="Role-Tiny.html#Top">(Role-Tiny)</a>
-</p>
-<p><code>Role::Tiny</code> provides some of the same features as Moose’s
role
-system, but in a much smaller package. Most notably, it doesn’t support
-any sort of attribute declaration, so you have to do that by hand.
-Still, it’s useful, and works well with <code>Class::Accessor</code> and
-<code>Class::Tiny</code>
-</p>
-<hr>
-<a name="perlootut-OO-System-Summary"></a>
-<div class="header">
-<p>
-Next: <a href="#perlootut-Other-OO-Systems" accesskey="n" rel="next">perlootut
Other OO Systems</a>, Previous: <a href="#perlootut-Role_003a_003aTiny"
accesskey="p" rel="prev">perlootut Role::Tiny</a>, Up: <a
href="#perlootut-PERL-OO-SYSTEMS" accesskey="u" rel="up">perlootut PERL OO
SYSTEMS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="OO-System-Summary"></a>
-<h4 class="subsection">47.5.5 OO System Summary</h4>
-
-<p>Here’s a brief recap of the options we covered:
-</p>
-<ul>
-<li> <a href="Moose.html#Top">(Moose)</a>
-
-<p><code>Moose</code> is the maximal option. It has a lot of features, a big
-ecosystem, and a thriving user base. We also covered <a
href="Moo.html#Top">(Moo)</a> briefly.
-<code>Moo</code> is <code>Moose</code> lite, and a reasonable alternative when
Moose
-doesn’t work for your application.
-</p>
-</li><li> <a href="Class-Accessor.html#Top">(Class-Accessor)</a>
-
-<p><code>Class::Accessor</code> does a lot less than <code>Moose</code>, and
is a nice
-alternative if you find <code>Moose</code> overwhelming. It’s been
around a long
-time and is well battle-tested. It also has a minimal <code>Moose</code>
-compatibility mode which makes moving from <code>Class::Accessor</code> to
-<code>Moose</code> easy.
-</p>
-</li><li> <a href="Class-Tiny.html#Top">(Class-Tiny)</a>
-
-<p><code>Class::Tiny</code> is the absolute minimal option. It has no
dependencies,
-and almost no syntax to learn. It’s a good option for a super minimal
-environment and for throwing something together quickly without having
-to worry about details.
-</p>
-</li><li> <a href="Role-Tiny.html#Top">(Role-Tiny)</a>
-
-<p>Use <code>Role::Tiny</code> with <code>Class::Accessor</code> or
<code>Class::Tiny</code> if you
-find yourself considering multiple inheritance. If you go with
-<code>Moose</code>, it comes with its own role implementation.
-</p>
-</li></ul>
-
-<hr>
-<a name="perlootut-Other-OO-Systems"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlootut-OO-System-Summary" accesskey="p"
rel="prev">perlootut OO System Summary</a>, Up: <a
href="#perlootut-PERL-OO-SYSTEMS" accesskey="u" rel="up">perlootut PERL OO
SYSTEMS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Other-OO-Systems"></a>
-<h4 class="subsection">47.5.6 Other OO Systems</h4>
-
-<p>There are literally dozens of other OO-related modules on CPAN besides
-those covered here, and you’re likely to run across one or more of them
-if you work with other people’s code.
-</p>
-<p>In addition, plenty of code in the wild does all of its OO "by
hand",
-using just the Perl built-in OO features. If you need to maintain such
-code, you should read <a href="#perlobj-NAME">perlobj NAME</a> to understand
exactly how Perl’s
-built-in OO works.
-</p>
-<hr>
-<a name="perlootut-CONCLUSION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlootut-PERL-OO-SYSTEMS" accesskey="p"
rel="prev">perlootut PERL OO SYSTEMS</a>, Up: <a href="#perlootut"
accesskey="u" rel="up">perlootut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="CONCLUSION-1"></a>
-<h3 class="section">47.6 CONCLUSION</h3>
-
-<p>As we said before, Perl’s minimal OO system has led to a profusion of
-OO systems on CPAN. While you can still drop down to the bare metal and
-write your classes by hand, there’s really no reason to do that with
-modern Perl.
-</p>
-<p>For small systems, <a href="Class-Tiny.html#Top">(Class-Tiny)</a> and <a
href="Class-Accessor.html#Top">(Class-Accessor)</a> both provide
-minimal object systems that take care of basic boilerplate for you.
-</p>
-<p>For bigger projects, <a href="Moose.html#Top">(Moose)</a> provides a rich
set of features that will
-let you focus on implementing your business logic.
-</p>
-<p>We encourage you to play with and evaluate <a
href="Moose.html#Top">(Moose)</a>,
-<a href="Class-Accessor.html#Top">(Class-Accessor)</a>, and <a
href="Class-Tiny.html#Top">(Class-Tiny)</a> to see which OO system is right
-for you.
-</p>
-<hr>
-<a name="perlop"></a>
-<div class="header">
-<p>
-Next: <a href="#perlopentut" accesskey="n" rel="next">perlopentut</a>,
Previous: <a href="#perlootut" accesskey="p" rel="prev">perlootut</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlop-2"></a>
-<h2 class="chapter">48 perlop</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlop-NAME"
accesskey="1">perlop NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlop-DESCRIPTION"
accesskey="2">perlop DESCRIPTION</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlop-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-DESCRIPTION" accesskey="n" rel="next">perlop
DESCRIPTION</a>, Up: <a href="#perlop" accesskey="u" rel="up">perlop</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-47"></a>
-<h3 class="section">48.1 NAME</h3>
-
-<p>perlop - Perl operators and precedence
-</p>
-<hr>
-<a name="perlop-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlop-NAME" accesskey="p" rel="prev">perlop NAME</a>, Up:
<a href="#perlop" accesskey="u" rel="up">perlop</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-46"></a>
-<h3 class="section">48.2 DESCRIPTION</h3>
-
-<p>In Perl, the operator determines what operation is performed,
-independent of the type of the operands. For example
<code>$x + $y</code><!-- /@w -->
-is always a numeric addition, and if <code>$x</code> or <code>$y</code> do not
contain
-numbers, an attempt is made to convert them to numbers first.
-</p>
-<p>This is in contrast to many other dynamic languages, where the
-operation is determined by the type of the first argument. It also
-means that Perl has two versions of some operators, one for numeric
-and one for string comparison. For example
<code>$x == $y</code><!-- /@w --> compares
-two numbers for equality, and <code>$x eq $y</code><!-- /@w -->
compares two strings.
-</p>
-<p>There are a few exceptions though: <code>x</code> can be either string
-repetition or list repetition, depending on the type of the left
-operand, and <code>&</code>, <code>|</code>, <code>^</code> and
<code>~</code> can be either string or numeric bit
-operations.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlop-Operator-Precedence-and-Associativity" accesskey="1">perlop
Operator Precedence and Associativity</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Terms-and-List-Operators-_0028Leftward_0029" accesskey="2">perlop
Terms and List Operators (Leftward)</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-The-Arrow-Operator-_003e_003e" accesskey="3">perlop The Arrow
Operator >></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Auto_002dincrement-and-Auto_002ddecrement" accesskey="4">perlop
Auto-increment and Auto-decrement</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlop-Exponentiation"
accesskey="5">perlop Exponentiation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Symbolic-Unary-Operators" accesskey="6">perlop Symbolic Unary
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlop-Binding-Operators"
accesskey="7">perlop Binding Operators</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Multiplicative-Operators" accesskey="8">perlop Multiplicative
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlop-Additive-Operators"
accesskey="9">perlop Additive Operators</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Shift-Operators-_003e-_003e_003e_003e">perlop Shift Operators
> >>></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Named-Unary-Operators">perlop Named Unary
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Relational-Operators">perlop Relational
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Equality-Operators">perlop Equality
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Smartmatch-Operator">perlop Smartmatch
Operator</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlop-Bitwise-And">perlop
Bitwise And</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Bitwise-Or-and-Exclusive-Or">perlop Bitwise Or and Exclusive
Or</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-C_002dstyle-Logical-And">perlop C-style Logical
And</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-C_002dstyle-Logical-Or">perlop C-style Logical
Or</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Logical-Defined_002dOr">perlop Logical
Defined-Or</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Range-Operators">perlop Range
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Conditional-Operator">perlop Conditional
Operator</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Assignment-Operators">perlop Assignment
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Comma-Operator">perlop Comma
Operator</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-List-Operators-_0028Rightward_0029">perlop List Operators
(Rightward)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlop-Logical-Not">perlop
Logical Not</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlop-Logical-And">perlop
Logical And</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Logical-or-and-Exclusive-Or">perlop Logical or and Exclusive
Or</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-C-Operators-Missing-From-Perl">perlop C Operators Missing From
Perl</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Quote-and-Quote_002dlike-Operators">perlop Quote and Quote-like
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Regexp-Quote_002dLike-Operators">perlop Regexp Quote-Like
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Quote_002dLike-Operators">perlop Quote-Like
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Gory-details-of-parsing-quoted-constructs">perlop Gory details of
parsing quoted constructs</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-I_002fO-Operators">perlop I/O
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Constant-Folding">perlop Constant
Folding</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlop-No_002dops">perlop
No-ops</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Bitwise-String-Operators">perlop Bitwise String
Operators</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Integer-Arithmetic">perlop Integer
Arithmetic</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Floating_002dpoint-Arithmetic">perlop Floating-point
Arithmetic</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlop-Bigger-Numbers">perlop Bigger
Numbers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlop-Operator-Precedence-and-Associativity"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Terms-and-List-Operators-_0028Leftward_0029"
accesskey="n" rel="next">perlop Terms and List Operators (Leftward)</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Operator-Precedence-and-Associativity"></a>
-<h4 class="subsection">48.2.1 Operator Precedence and Associativity</h4>
-
-<p>Operator precedence and associativity work in Perl more or less like
-they do in mathematics.
-</p>
-<p><em>Operator precedence</em> means some operators are evaluated before
-others. For example, in <code>2 + 4 * 5</code><!-- /@w
-->, the multiplication has higher
-precedence so <code>4 * 5</code><!-- /@w --> is evaluated first
yielding <code>2 + 20 == 22</code><!-- /@w --> and not
<code>6 * 5 == 30</code><!-- /@w -->.
-</p>
-<p><em>Operator associativity</em> defines what happens if a sequence of the
-same operators is used one after another: whether the evaluator will
-evaluate the left operations first, or the right first. For example, in
-<code>8 <span class="nolinebreak">-</span> 4 <span
class="nolinebreak">-</span> 2</code><!-- /@w -->, subtraction is left
associative so Perl evaluates the
-expression left to right. <code>8 <span
class="nolinebreak">-</span> 4</code><!-- /@w --> is evaluated first
making the
-expression <code>4 <span
class="nolinebreak">-</span> 2 == 2</code><!-- /@w --> and not
<code>8 <span
class="nolinebreak">-</span> 2 == 6</code><!-- /@w -->.
-</p>
-<p>Perl operators have the following associativity and precedence,
-listed from highest precedence to lowest. Operators borrowed from
-C keep the same precedence relationship with each other, even where
-C’s precedence is slightly screwy. (This makes learning Perl easier
-for C folks.) With very few exceptions, these all operate on scalar
-values only, not array values.
-</p>
-<pre class="verbatim"> left terms and list operators (leftward)
- left ->
- nonassoc ++ --
- right **
- right ! ~ \ and unary + and -
- left =~ !~
- left * / % x
- left + - .
- left << >>
- nonassoc named unary operators
- nonassoc < > <= >= lt gt le ge
- nonassoc == != <=> eq ne cmp ~~
- left &
- left | ^
- left &&
- left || //
- nonassoc .. ...
- right ?:
- right = += -= *= etc. goto last next redo dump
- left , =>
- nonassoc list operators (rightward)
- right not
- left and
- left or xor
-</pre>
-<p>In the following sections, these operators are covered in precedence order.
-</p>
-<p>Many operators can be overloaded for objects. See <a
href="overload.html#Top">(overload)</a>.
-</p>
-<hr>
-<a name="perlop-Terms-and-List-Operators-_0028Leftward_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-The-Arrow-Operator-_003e_003e" accesskey="n"
rel="next">perlop The Arrow Operator >></a>, Previous: <a
href="#perlop-Operator-Precedence-and-Associativity" accesskey="p"
rel="prev">perlop Operator Precedence and Associativity</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Terms-and-List-Operators-_0028Leftward_0029"></a>
-<h4 class="subsection">48.2.2 Terms and List Operators (Leftward)</h4>
-
-<p>A TERM has the highest precedence in Perl. They include variables,
-quote and quote-like operators, any expression in parentheses,
-and any function whose arguments are parenthesized. Actually, there
-aren’t really functions in this sense, just list operators and unary
-operators behaving as functions because you put parentheses around
-the arguments. These are all documented in <a href="#perlfunc-NAME">perlfunc
NAME</a>.
-</p>
-<p>If any list operator (<code>print()</code>, etc.) or any unary operator
(<code>chdir()</code>, etc.)
-is followed by a left parenthesis as the next token, the operator and
-arguments within parentheses are taken to be of highest precedence,
-just like a normal function call.
-</p>
-<p>In the absence of parentheses, the precedence of list operators such as
-<code>print</code>, <code>sort</code>, or <code>chmod</code> is either very
high or very low depending on
-whether you are looking at the left side or the right side of the operator.
-For example, in
-</p>
-<pre class="verbatim"> @ary = (1, 3, sort 4, 2);
- print @ary; # prints 1324
-</pre>
-<p>the commas on the right of the <code>sort</code> are evaluated before the
<code>sort</code>,
-but the commas on the left are evaluated after. In other words,
-list operators tend to gobble up all arguments that follow, and
-then act like a simple TERM with regard to the preceding expression.
-Be careful with parentheses:
-</p>
-<pre class="verbatim"> # These evaluate exit before doing the print:
- print($foo, exit); # Obviously not what you want.
- print $foo, exit; # Nor is this.
-
- # These do the print before evaluating exit:
- (print $foo), exit; # This is what you want.
- print($foo), exit; # Or this.
- print ($foo), exit; # Or even this.
-</pre>
-<p>Also note that
-</p>
-<pre class="verbatim"> print ($foo & 255) + 1, "\n";
-</pre>
-<p>probably doesn’t do what you expect at first glance. The parentheses
-enclose the argument list for <code>print</code> which is evaluated (printing
-the result of <code>$foo & 255</code><!-- /@w -->). Then one is
added to the return value
-of <code>print</code> (usually 1). The result is something like this:
-</p>
-<pre class="verbatim"> 1 + 1, "\n"; # Obviously not what you
meant.
-</pre>
-<p>To do what you meant properly, you must write:
-</p>
-<pre class="verbatim"> print(($foo & 255) + 1, "\n");
-</pre>
-<p>See <a href="#perlop-Named-Unary-Operators">Named Unary Operators</a> for
more discussion of this.
-</p>
-<p>Also parsed as terms are the <code>do {}</code><!-- /@w --> and
<code>eval {}</code><!-- /@w --> constructs, as
-well as subroutine and method calls, and the anonymous
-constructors <code>[]</code> and <code>{}</code>.
-</p>
-<p>See also <a href="#perlop-Quote-and-Quote_002dlike-Operators">Quote and
Quote-like Operators</a> toward the end of this section,
-as well as <a href="#perlop-I_002fO-Operators">I/O Operators</a>.
-</p>
-<hr>
-<a name="perlop-The-Arrow-Operator-_003e_003e"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Auto_002dincrement-and-Auto_002ddecrement"
accesskey="n" rel="next">perlop Auto-increment and Auto-decrement</a>,
Previous: <a href="#perlop-Terms-and-List-Operators-_0028Leftward_0029"
accesskey="p" rel="prev">perlop Terms and List Operators (Leftward)</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-Arrow-Operator-_003e_003e"></a>
-<h4 class="subsection">48.2.3 The Arrow Operator >></h4>
-
-<p>"<code>-></code>" is an infix dereference operator, just as it
is in C
-and C++. If the right side is either a <code>[...]</code>,
<code>{...}</code>, or a
-<code>(...)</code> subscript, then the left side must be either a hard or
-symbolic reference to an array, a hash, or a subroutine respectively.
-(Or technically speaking, a location capable of holding a hard
-reference, if it’s an array or hash reference being used for
-assignment.) See <a href="#perlreftut-NAME">perlreftut NAME</a> and <a
href="#perlref-NAME">perlref NAME</a>.
-</p>
-<p>Otherwise, the right side is a method name or a simple scalar
-variable containing either the method name or a subroutine reference,
-and the left side must be either an object (a blessed reference)
-or a class name (that is, a package name). See <a
href="#perlobj-NAME">perlobj NAME</a>.
-</p>
-<p>The dereferencing cases (as opposed to method-calling cases) are
-somewhat extended by the experimental <code>postderef</code> feature. For the
-details of that feature, consult <a
href="#perlref-Postfix-Dereference-Syntax">perlref Postfix Dereference
Syntax</a>.
-</p>
-<hr>
-<a name="perlop-Auto_002dincrement-and-Auto_002ddecrement"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Exponentiation" accesskey="n" rel="next">perlop
Exponentiation</a>, Previous: <a href="#perlop-The-Arrow-Operator-_003e_003e"
accesskey="p" rel="prev">perlop The Arrow Operator >></a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Auto_002dincrement-and-Auto_002ddecrement"></a>
-<h4 class="subsection">48.2.4 Auto-increment and Auto-decrement</h4>
-
-<p><code>"++"</code> and <code>"--"</code> work as in C.
That is, if placed before a variable,
-they increment or decrement the variable by one before returning the
-value, and if placed after, increment or decrement after returning the
-value.
-</p>
-<pre class="verbatim"> $i = 0; $j = 0;
- print $i++; # prints 0
- print ++$j; # prints 1
-</pre>
-<p>Note that just as in C, Perl doesn’t define <strong>when</strong> 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 behavior.
-Avoid statements like:
-</p>
-<pre class="verbatim"> $i = $i ++;
- print ++ $i + $i ++;
-</pre>
-<p>Perl will not guarantee what the result of the above statements is.
-</p>
-<p>The auto-increment operator has a little extra builtin magic to it. If
-you increment a variable that is numeric, or that has ever been used in
-a numeric context, you get a normal increment. If, however, the
-variable has been used in only string contexts since it was set, and
-has a value that is not the empty string and matches the pattern
-<code>/^[a-zA-Z]*[0-9]*\z/</code>, the increment is done as a string,
preserving each
-character within its range, with carry:
-</p>
-<pre class="verbatim"> print ++($foo = "99"); # prints
"100"
- print ++($foo = "a0"); # prints "a1"
- print ++($foo = "Az"); # prints "Ba"
- print ++($foo = "zz"); # prints "aaa"
-</pre>
-<p><code>undef</code> is always treated as numeric, and in particular is
changed
-to <code>0</code> before incrementing (so that a post-increment of an undef
value
-will return <code>0</code> rather than <code>undef</code>).
-</p>
-<p>The auto-decrement operator is not magical.
-</p>
-<hr>
-<a name="perlop-Exponentiation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Symbolic-Unary-Operators" accesskey="n"
rel="next">perlop Symbolic Unary Operators</a>, Previous: <a
href="#perlop-Auto_002dincrement-and-Auto_002ddecrement" accesskey="p"
rel="prev">perlop Auto-increment and Auto-decrement</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Exponentiation"></a>
-<h4 class="subsection">48.2.5 Exponentiation</h4>
-
-<p>Binary <code>"**"</code> is the exponentiation operator. It
binds even more
-tightly than unary minus, so <code>-2**4</code> is <code>-(2**4)</code>, not
<code>(-2)**4</code>.
-(This is
-implemented using C’s <code>pow(3)</code> function, which actually works
on doubles
-internally.)
-</p>
-<p>Note that certain exponentiation expressions are ill-defined:
-these include <code>0**0</code>, <code>1**Inf</code>, and <code>Inf**0</code>.
Do not expect
-any particular results from these special cases, the results
-are platform-dependent.
-</p>
-<hr>
-<a name="perlop-Symbolic-Unary-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Binding-Operators" accesskey="n" rel="next">perlop
Binding Operators</a>, Previous: <a href="#perlop-Exponentiation" accesskey="p"
rel="prev">perlop Exponentiation</a>, Up: <a href="#perlop-DESCRIPTION"
accesskey="u" rel="up">perlop DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Symbolic-Unary-Operators"></a>
-<h4 class="subsection">48.2.6 Symbolic Unary Operators</h4>
-
-<p>Unary <code>"!"</code> performs logical negation, that is,
"not". See also <code>not</code> for a lower
-precedence version of this.
-</p>
-<p>Unary <code>"-"</code> 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 <code>-bareword</code> is
equivalent
-to the string <code>"-bareword"</code>. If, however, the string
begins with a
-non-alphabetic character (excluding <code>"+"</code> or
<code>"-"</code>), Perl will attempt
-to convert
-the string to a numeric, and the arithmetic negation is performed. If the
-string cannot be cleanly converted to a numeric, Perl will give the warning
-<strong>Argument "the string" isn’t numeric in negation (-) at
...</strong>.
-</p>
-<p>Unary <code>"~"</code> performs bitwise negation, that is,
1’s complement. For
-example, <code>0666 & ~027</code><!-- /@w --> is 0640. (See
also <a href="#perlop-Integer-Arithmetic">Integer Arithmetic</a> and
-<a href="#perlop-Bitwise-String-Operators">Bitwise String Operators</a>.)
Note that the width of the result is
-platform-dependent: <code>~0</code> 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 <code>"&"</code> operator to mask off
the excess bits.
-</p>
-<p>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, <code>~"\x{3B1}"</code> is
<code>"\x{FFFF_FC4E}"</code> on
-32-bit machines and <code>"\x{FFFF_FFFF_FFFF_FC4E}"</code> on 64-bit
machines.
-</p>
-<p>If the experimental "bitwise" feature is enabled via
<code>use feature 'bitwise'</code><!-- /@w -->, then unary
<code>"~"</code> always treats its argument as a number, and an
-alternate form of the operator, <code>"~."</code>, always treats its
argument as a
-string. So <code>~0</code> and <code>~"0"</code> will both give
2**32-1 on 32-bit platforms,
-whereas <code>~.0</code> and <code>~."0"</code> will both yield
<code>"\xff"</code>. This feature
-produces a warning unless you use
<code>no warnings 'experimental::bitwise'</code><!-- /@w -->.
-</p>
-<p>Unary <code>"+"</code> 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
-arguments. (See examples above under Terms and List Operators (Leftward).)
-</p>
-<p>Unary <code>"\"</code> creates a reference to whatever follows
it. See <a href="#perlreftut-NAME">perlreftut NAME</a>
-and <a href="#perlref-NAME">perlref NAME</a>. Do not confuse this behavior
with the behavior of
-backslash within a string, although both forms do convey the notion
-of protecting the next thing from interpolation.
-</p>
-<hr>
-<a name="perlop-Binding-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Multiplicative-Operators" accesskey="n"
rel="next">perlop Multiplicative Operators</a>, Previous: <a
href="#perlop-Symbolic-Unary-Operators" accesskey="p" rel="prev">perlop
Symbolic Unary Operators</a>, Up: <a href="#perlop-DESCRIPTION" accesskey="u"
rel="up">perlop DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Binding-Operators"></a>
-<h4 class="subsection">48.2.7 Binding Operators</h4>
-
-<p>Binary <code>"=~"</code> binds a scalar expression to a pattern
match. Certain operations
-search or modify the string <code>$_</code> by default. This operator makes
that kind
-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
-<code>$_</code>. When used in scalar context, the return value generally
indicates the
-success of the operation. The exceptions are substitution (<code>s///</code>)
-and transliteration (<code>y///</code>) with the <code>/r</code>
(non-destructive) option,
-which cause the <strong>r</strong>eturn value to be the result of the
substitution.
-Behavior in list context depends on the particular operator.
-See <a href="#perlop-Regexp-Quote_002dLike-Operators">Regexp Quote-Like
Operators</a> for details and <a href="#perlretut-NAME">perlretut NAME</a> for
-examples using these operators.
-</p>
-<p>If the right argument is an expression rather than a search pattern,
-substitution, or transliteration, it is interpreted as a search pattern at run
-time. Note that this means that its
-contents will be interpolated twice, so
-</p>
-<pre class="verbatim"> '\\' =~ q'\\';
-</pre>
-<p>is not ok, as the regex engine will end up trying to compile the
-pattern <code>\</code>, which it will consider a syntax error.
-</p>
-<p>Binary <code>"!~"</code> is just like <code>"=~"</code>
except the return value is negated in
-the logical sense.
-</p>
-<p>Binary <code>"!~"</code> with a non-destructive substitution
(<code>s///r</code>) or transliteration
-(<code>y///r</code>) is a syntax error.
-</p>
-<hr>
-<a name="perlop-Multiplicative-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Additive-Operators" accesskey="n" rel="next">perlop
Additive Operators</a>, Previous: <a href="#perlop-Binding-Operators"
accesskey="p" rel="prev">perlop Binding Operators</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Multiplicative-Operators"></a>
-<h4 class="subsection">48.2.8 Multiplicative Operators</h4>
-
-<p>Binary <code>"*"</code> multiplies two numbers.
-</p>
-<p>Binary <code>"/"</code> divides two numbers.
-</p>
-<p>Binary <code>"%"</code> is the modulo operator, which computes
the division
-remainder of its first argument with respect to its second argument.
-Given integer
-operands <code>$m</code> and <code>$n</code>: If <code>$n</code> is positive,
then <code>$m % $n</code><!-- /@w --> is
-<code>$m</code> minus the largest multiple of <code>$n</code> less than or
equal to
-<code>$m</code>. If <code>$n</code> is negative, then
<code>$m % $n</code><!-- /@w --> is <code>$m</code> minus the
-smallest multiple of <code>$n</code> that is not less than <code>$m</code>
(that is, the
-result will be less than or equal to zero). If the operands
-<code>$m</code> and <code>$n</code> are floating point values and the absolute
value of
-<code>$n</code> (that is <code>abs($n)</code>) is less than <code><span
class="nolinebreak">(UV_MAX</span> + 1)</code><!-- /@w -->, only
-the integer portion of <code>$m</code> and <code>$n</code> will be used in the
operation
-(Note: here <code>UV_MAX</code> means the maximum of the unsigned integer
type).
-If the absolute value of the right operand (<code>abs($n)</code>) is greater
than
-or equal to <code><span
class="nolinebreak">(UV_MAX</span> + 1)</code><!-- /@w -->,
<code>"%"</code> computes the floating-point remainder
-<code>$r</code> in the equation <code>($r = $m <span
class="nolinebreak">-</span> $i*$n)</code><!-- /@w --> where
<code>$i</code> is a certain
-integer that makes <code>$r</code> have the same sign as the right operand
-<code>$n</code> (<strong>not</strong> as the left operand <code>$m</code> like
C function <code>fmod()</code>)
-and the absolute value less than that of <code>$n</code>.
-Note that when <code>use integer</code><!-- /@w --> is in scope,
<code>"%"</code> gives you direct access
-to the modulo operator as implemented by your C compiler. This
-operator is not as well defined for negative operands, but it will
-execute faster.
-</p>
-<p>Binary <code>"x"</code> is the repetition operator. In scalar
context or if the left
-operand is not enclosed in parentheses, it returns a string consisting
-of the left operand repeated the number of times specified by the right
-operand. In list context, if the left operand is enclosed in
-parentheses or is a list formed by <code>qw/<em>STRING</em>/</code>, it
repeats the list.
-If the right operand is zero or negative (raising a warning on
-negative), it returns an empty string
-or an empty list, depending on the context.
-</p>
-<pre class="verbatim"> print '-' x 80; # print row of dashes
-
- print "\t" x ($tab/8), ' ' x ($tab%8); # tab over
-
- @ones = (1) x 80; # a list of 80 1's
- @ones = (5) x @ones; # set all elements to 5
-</pre>
-<hr>
-<a name="perlop-Additive-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Shift-Operators-_003e-_003e_003e_003e" accesskey="n"
rel="next">perlop Shift Operators > >>></a>, Previous: <a
href="#perlop-Multiplicative-Operators" accesskey="p" rel="prev">perlop
Multiplicative Operators</a>, Up: <a href="#perlop-DESCRIPTION" accesskey="u"
rel="up">perlop DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Additive-Operators"></a>
-<h4 class="subsection">48.2.9 Additive Operators</h4>
-
-<p>Binary <code>"+"</code> returns the sum of two numbers.
-</p>
-<p>Binary <code>"-"</code> returns the difference of two numbers.
-</p>
-<p>Binary <code>"."</code> concatenates two strings.
-</p>
-<hr>
-<a name="perlop-Shift-Operators-_003e-_003e_003e_003e"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Named-Unary-Operators" accesskey="n" rel="next">perlop
Named Unary Operators</a>, Previous: <a href="#perlop-Additive-Operators"
accesskey="p" rel="prev">perlop Additive Operators</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Shift-Operators-_003e-_003e_003e_003e"></a>
-<h4 class="subsection">48.2.10 Shift Operators > >>></h4>
-
-<p>Binary <code>"<<"</code> returns the value of its left
argument shifted left by the
-number of bits specified by the right argument. Arguments should be
-integers. (See also <a href="#perlop-Integer-Arithmetic">Integer
Arithmetic</a>.)
-</p>
-<p>Binary <code>">>"</code> returns the value of its left
argument shifted right by
-the number of bits specified by the right argument. Arguments should
-be integers. (See also <a href="#perlop-Integer-Arithmetic">Integer
Arithmetic</a>.)
-</p>
-<p>Note that both <code><<</code> and <code>>></code> in Perl are
implemented directly using
-<code><<</code> and <code>>></code> in C. If
<code>use integer</code><!-- /@w --> (see <a
href="#perlop-Integer-Arithmetic">Integer Arithmetic</a>) is
-in force then signed C integers are used, else unsigned C integers are
-used, even for negative shiftees. Either way, the implementation isn’t
going to generate results
-larger than the size of the integer type Perl was built with (32 bits
-or 64 bits).
-</p>
-<p>The result of overflowing the range of the integers is undefined
-because it is undefined also in C. In other words, using 32-bit
-integers, <code>1 << 32</code><!-- /@w --> is undefined.
Shifting by a negative number
-of bits is also undefined.
-</p>
-<p>If you get tired of being subject to your platform’s native integers,
-the <code>use bigint</code><!-- /@w --> pragma neatly sidesteps the issue
altogether:
-</p>
-<pre class="verbatim"> print 20 << 20; # 20971520
- print 20 << 40; # 5120 on 32-bit machines,
- # 21990232555520 on 64-bit machines
- use bigint;
- print 20 << 100; # 25353012004564588029934064107520
-</pre>
-<hr>
-<a name="perlop-Named-Unary-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Relational-Operators" accesskey="n" rel="next">perlop
Relational Operators</a>, Previous: <a
href="#perlop-Shift-Operators-_003e-_003e_003e_003e" accesskey="p"
rel="prev">perlop Shift Operators > >>></a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Named-Unary-Operators"></a>
-<h4 class="subsection">48.2.11 Named Unary Operators</h4>
-
-<p>The various named unary operators are treated as functions with one
-argument, with optional parentheses.
-</p>
-<p>If any list operator (<code>print()</code>, etc.) or any unary operator
(<code>chdir()</code>, etc.)
-is followed by a left parenthesis as the next token, the operator and
-arguments within parentheses are taken to be of highest precedence,
-just like a normal function call. For example,
-because named unary operators are higher precedence than <code>||</code>:
-</p>
-<pre class="verbatim"> chdir $foo || die; # (chdir $foo) || die
- chdir($foo) || die; # (chdir $foo) || die
- chdir ($foo) || die; # (chdir $foo) || die
- chdir +($foo) || die; # (chdir $foo) || die
-</pre>
-<p>but, because <code>"*"</code> is higher precedence than named
operators:
-</p>
-<pre class="verbatim"> chdir $foo * 20; # chdir ($foo * 20)
- chdir($foo) * 20; # (chdir $foo) * 20
- chdir ($foo) * 20; # (chdir $foo) * 20
- chdir +($foo) * 20; # chdir ($foo * 20)
-
- rand 10 * 20; # rand (10 * 20)
- rand(10) * 20; # (rand 10) * 20
- rand (10) * 20; # (rand 10) * 20
- rand +(10) * 20; # rand (10 * 20)
-</pre>
-<p>Regarding precedence, the filetest operators, like <code>-f</code>,
<code>-M</code>, etc. are
-treated like named unary operators, but they don’t follow this functional
-parenthesis rule. That means, for example, that
<code>-f($file).".bak"</code> is
-equivalent to <code><span
class="nolinebreak">-f</span> "$file.bak"</code><!-- /@w -->.
-</p>
-<p>See also <a
href="#perlop-Terms-and-List-Operators-_0028Leftward_0029">Terms and List
Operators (Leftward)</a>.
-</p>
-<hr>
-<a name="perlop-Relational-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Equality-Operators" accesskey="n" rel="next">perlop
Equality Operators</a>, Previous: <a href="#perlop-Named-Unary-Operators"
accesskey="p" rel="prev">perlop Named Unary Operators</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Relational-Operators"></a>
-<h4 class="subsection">48.2.12 Relational Operators</h4>
-
-<p>Perl operators that return true or false generally return values
-that can be safely used as numbers. For example, the relational
-operators in this section and the equality operators in the next
-one return <code>1</code> for true and a special version of the defined empty
-string, <code>""</code>, which counts as a zero but is exempt from
warnings
-about improper numeric conversions, just as
<code>"0 but true"</code><!-- /@w --> is.
-</p>
-<p>Binary <code>"<"</code> returns true if the left argument is
numerically less than
-the right argument.
-</p>
-<p>Binary <code>">"</code> returns true if the left argument is
numerically greater
-than the right argument.
- >>
-</p>
-<p>Binary <code>"<="</code> returns true if the left argument is
numerically less than
-or equal to the right argument.
-</p>
-<p>Binary <code>">="</code> returns true if the left argument is
numerically greater
-than or equal to the right argument.
-= >>
-</p>
-<p>Binary <code>"lt"</code> returns true if the left argument is
stringwise less than
-the right argument.
-</p>
-<p>Binary <code>"gt"</code> returns true if the left argument is
stringwise greater
-than the right argument.
-</p>
-<p>Binary <code>"le"</code> returns true if the left argument is
stringwise less than
-or equal to the right argument.
-</p>
-<p>Binary <code>"ge"</code> returns true if the left argument is
stringwise greater
-than or equal to the right argument.
-</p>
-<hr>
-<a name="perlop-Equality-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Smartmatch-Operator" accesskey="n" rel="next">perlop
Smartmatch Operator</a>, Previous: <a href="#perlop-Relational-Operators"
accesskey="p" rel="prev">perlop Relational Operators</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Equality-Operators"></a>
-<h4 class="subsection">48.2.13 Equality Operators</h4>
-
-<p>Binary <code>"=="</code> returns true if the left argument is
numerically equal to
-the right argument.
-</p>
-<p>Binary <code>"!="</code> returns true if the left argument is
numerically not equal
-to the right argument.
-</p>
-<p>Binary <code>"<=>"</code> returns -1, 0, or 1 depending on
whether the left
-argument is numerically less than, equal to, or greater than the right
-argument. If your platform supports <code>NaN</code>’s (not-a-numbers)
as numeric
-values, using them with <code>"<=>"</code> returns undef.
<code>NaN</code> is not
-<code>"<"</code>, <code>"=="</code>,
<code>">"</code>, <code>"<="</code> or
<code>">="</code> anything
-(even <code>NaN</code>), so those 5 return false.
<code>NaN != NaN</code><!-- /@w --> returns
-true, as does <code>NaN !=</code> <em>anything else</em><!--
/@w -->. If your platform doesn’t
-support <code>NaN</code>’s then <code>NaN</code> is just a string with
numeric value 0.
- >>
-</p>
-<pre class="verbatim"> $ perl -le '$x = "NaN"; print "No NaN
support here" if $x == $x'
- $ perl -le '$x = "NaN"; print "NaN support here" if $x
!= $x'
-</pre>
-<p>(Note that the <a href="bigint.html#Top">(bigint)</a>, <a
href="bigrat.html#Top">(bigrat)</a>, and <a href="bignum.html#Top">(bignum)</a>
pragmas all
-support <code>"NaN"</code>.)
-</p>
-<p>Binary <code>"eq"</code> returns true if the left argument is
stringwise equal to
-the right argument.
-</p>
-<p>Binary <code>"ne"</code> returns true if the left argument is
stringwise not equal
-to the right argument.
-</p>
-<p>Binary <code>"cmp"</code> returns -1, 0, or 1 depending on
whether the left
-argument is stringwise less than, equal to, or greater than the right
-argument.
-</p>
-<p>Binary <code>"~~"</code> does a smartmatch between its arguments.
Smart matching
-is described in the next section.
-</p>
-<p><code>"lt"</code>, <code>"le"</code>,
<code>"ge"</code>, <code>"gt"</code> and
<code>"cmp"</code> use the collation (sort)
-order specified by the current <code>LC_COLLATE</code> locale if a
<code>use locale</code><!-- /@w --> form that includes collation is in
effect. See <a href="#perllocale-NAME">perllocale NAME</a>.
-Do not mix these with Unicode,
-only use them with legacy 8-bit locale encodings.
-The standard <code><a
href="Unicode-Collate.html#Top">(Unicode-Collate)</a></code> and
-<code><a
href="Unicode-Collate-Locale.html#Top">(Unicode-Collate-Locale)</a></code>
modules offer much more powerful
-solutions to collation issues.
-</p>
-<p>For case-insensitive comparisions, look at the <a
href="#perlfunc-fc">perlfunc fc</a> case-folding
-function, available in Perl v5.16 or later:
-</p>
-<pre class="verbatim"> if ( fc($x) eq fc($y) ) { ... }
-</pre>
-<hr>
-<a name="perlop-Smartmatch-Operator"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Bitwise-And" accesskey="n" rel="next">perlop Bitwise
And</a>, Previous: <a href="#perlop-Equality-Operators" accesskey="p"
rel="prev">perlop Equality Operators</a>, Up: <a href="#perlop-DESCRIPTION"
accesskey="u" rel="up">perlop DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Smartmatch-Operator"></a>
-<h4 class="subsection">48.2.14 Smartmatch Operator</h4>
-
-<p>First available in Perl 5.10.1 (the 5.10.0 version behaved differently),
-binary <code>~~</code> does a "smartmatch" between its arguments.
This is mostly
-used implicitly in the <code>when</code> construct described in <a
href="#perlsyn-NAME">perlsyn NAME</a>, although
-not all <code>when</code> clauses call the smartmatch operator. Unique among
all of
-Perl’s operators, the smartmatch operator can recurse. The smartmatch
-operator is <a href="#perlpolicy-experimental">experimental</a> and its
behavior is
-subject to change.
-</p>
-<p>It is also unique in that all other Perl operators impose a context
-(usually string or numeric context) on their operands, autoconverting
-those operands to those imposed contexts. In contrast, smartmatch
-<em>infers</em> contexts from the actual types of its operands and uses that
-type information to select a suitable comparison mechanism.
-</p>
-<p>The <code>~~</code> operator compares its operands
"polymorphically", determining how
-to compare them according to their actual types (numeric, string, array,
-hash, etc.) Like the equality operators with which it shares the same
-precedence, <code>~~</code> returns 1 for true and <code>""</code>
for false. It is often best
-read aloud as "in", "inside of", or "is contained
in", because the left
-operand is often looked for <em>inside</em> the right operand. That makes the
-order of the operands to the smartmatch operand often opposite that of
-the regular match operator. In other words, the "smaller" thing is
usually
-placed in the left operand and the larger one in the right.
-</p>
-<p>The behavior of a smartmatch depends on what type of things its arguments
-are, as determined by the following table. The first row of the table
-whose types apply determines the smartmatch behavior. Because what
-actually happens is mostly determined by the type of the second operand,
-the table is sorted on the right operand instead of on the left.
-</p>
-<pre class="verbatim"> Left Right Description and pseudocode
- ===============================================================
- Any undef check whether Any is undefined
- like: !defined Any
-
- Any Object invoke ~~ overloading on Object, or die
-
- Right operand is an ARRAY:
-
- Left Right Description and pseudocode
- ===============================================================
- ARRAY1 ARRAY2 recurse on paired elements of ARRAY1 and ARRAY2[2]
- like: (ARRAY1[0] ~~ ARRAY2[0])
- && (ARRAY1[1] ~~ ARRAY2[1]) && ...
- HASH ARRAY any ARRAY elements exist as HASH keys
- like: grep { exists HASH->{$_} } ARRAY
- Regexp ARRAY any ARRAY elements pattern match Regexp
- like: grep { /Regexp/ } ARRAY
- undef ARRAY undef in ARRAY
- like: grep { !defined } ARRAY
- Any ARRAY smartmatch each ARRAY element[3]
- like: grep { Any ~~ $_ } ARRAY
-
- Right operand is a HASH:
-
- Left Right Description and pseudocode
- ===============================================================
- HASH1 HASH2 all same keys in both HASHes
- like: keys HASH1 ==
- grep { exists HASH2->{$_} } keys HASH1
- ARRAY HASH any ARRAY elements exist as HASH keys
- like: grep { exists HASH->{$_} } ARRAY
- Regexp HASH any HASH keys pattern match Regexp
- like: grep { /Regexp/ } keys HASH
- undef HASH always false (undef can't be a key)
- like: 0 == 1
- Any HASH HASH key existence
- like: exists HASH->{Any}
-
- Right operand is CODE:
-
- Left Right Description and pseudocode
- ===============================================================
- ARRAY CODE sub returns true on all ARRAY elements[1]
- like: !grep { !CODE->($_) } ARRAY
- HASH CODE sub returns true on all HASH keys[1]
- like: !grep { !CODE->($_) } keys HASH
- Any CODE sub passed Any returns true
- like: CODE->(Any)
-</pre>
-<p>Right operand is a Regexp:
-</p>
-<pre class="verbatim"> Left Right Description and pseudocode
- ===============================================================
- ARRAY Regexp any ARRAY elements match Regexp
- like: grep { /Regexp/ } ARRAY
- HASH Regexp any HASH keys match Regexp
- like: grep { /Regexp/ } keys HASH
- Any Regexp pattern match
- like: Any =~ /Regexp/
-
- Other:
-
- Left Right Description and pseudocode
- ===============================================================
- Object Any invoke ~~ overloading on Object,
- or fall back to...
-
- Any Num numeric equality
- like: Any == Num
- Num nummy[4] numeric equality
- like: Num == nummy
- undef Any check whether undefined
- like: !defined(Any)
- Any Any string equality
- like: Any eq Any
-</pre>
-<p>Notes:
-</p>
-<dl compact="compact">
-<dt>1. Empty hashes or arrays match.</dt>
-<dd><a name="perlop-1_002e-Empty-hashes-or-arrays-match_002e"></a>
-</dd>
-<dt>2. That is, each element smartmatches the element of the same index in the
other array.[3]</dt>
-<dd><a
name="perlop-2_002e-That-is_002c-each-element-smartmatches-the-element-of-the-same-index-in-the-other-array_002e_005b3_005d"></a>
-</dd>
-<dt>3. If a circular reference is found, fall back to referential
equality.</dt>
-<dd><a
name="perlop-3_002e-If-a-circular-reference-is-found_002c-fall-back-to-referential-equality_002e"></a>
-</dd>
-<dt>4. Either an actual number, or a string that looks like one.</dt>
-<dd><a
name="perlop-4_002e-Either-an-actual-number_002c-or-a-string-that-looks-like-one_002e"></a>
-</dd>
-</dl>
-
-<p>The smartmatch implicitly dereferences any non-blessed hash or array
-reference, so the <code><em>HASH</em></code> and <code><em>ARRAY</em></code>
entries apply in those cases.
-For blessed references, the <code><em>Object</em></code> entries apply.
Smartmatches
-involving hashes only consider hash keys, never hash values.
-</p>
-<p>The "like" code entry is not always an exact rendition. For
example, the
-smartmatch operator short-circuits whenever possible, but <code>grep</code>
does
-not. Also, <code>grep</code> in scalar context returns the number of matches,
but
-<code>~~</code> returns only true or false.
-</p>
-<p>Unlike most operators, the smartmatch operator knows to treat
<code>undef</code>
-specially:
-</p>
-<pre class="verbatim"> use v5.10.1;
- @array = (1, 2, 3, undef, 4, 5);
- say "some elements undefined" if undef ~~ @array;
-</pre>
-<p>Each operand is considered in a modified scalar context, the modification
-being that array and hash variables are passed by reference to the
-operator, which implicitly dereferences them. Both elements
-of each pair are the same:
-</p>
-<pre class="verbatim"> use v5.10.1;
-
- my %hash = (red => 1, blue => 2, green => 3,
- orange => 4, yellow => 5, purple => 6,
- black => 7, grey => 8, white => 9);
-
- my @array = qw(red blue green);
-
- say "some array elements in hash keys" if @array ~~ %hash;
- say "some array elements in hash keys" if address@hidden ~~
\%hash;
-
- say "red in array" if "red" ~~ @array;
- say "red in array" if "red" ~~ address@hidden;
-
- say "some keys end in e" if /e$/ ~~ %hash;
- say "some keys end in e" if /e$/ ~~ \%hash;
-</pre>
-<p>Two arrays smartmatch if each element in the first array smartmatches
-(that is, is "in") the corresponding element in the second array,
-recursively.
-</p>
-<pre class="verbatim"> use v5.10.1;
- my @little = qw(red blue green);
- my @bigger = ("red", "blue", [ "orange",
"green" ] );
- if (@little ~~ @bigger) { # true!
- say "little is contained in bigger";
- }
-</pre>
-<p>Because the smartmatch operator recurses on nested arrays, this
-will still report that "red" is in the array.
-</p>
-<pre class="verbatim"> use v5.10.1;
- my @array = qw(red blue green);
- my $nested_array = [[[[[[[ @array ]]]]]]];
- say "red in array" if "red" ~~ $nested_array;
-</pre>
-<p>If two arrays smartmatch each other, then they are deep
-copies of each others’ values, as this example reports:
-</p>
-<pre class="verbatim"> use v5.12.0;
- my @a = (0, 1, 2, [3, [4, 5], 6], 7);
- my @b = (0, 1, 2, [3, [4, 5], 6], 7);
-
- if (@a ~~ @b && @b ~~ @a) {
- say "a and b are deep copies of each other";
- }
- elsif (@a ~~ @b) {
- say "a smartmatches in b";
- }
- elsif (@b ~~ @a) {
- say "b smartmatches in a";
- }
- else {
- say "a and b don't smartmatch each other at all";
- }
-</pre>
-<p>If you were to set <code>$b[3] = 4</code><!-- /@w -->, then
instead of reporting that "a and b
-are deep copies of each other", it now reports that <code>"b
smartmatches in a"</code>.
-That’s because the corresponding position in <code>@a</code> contains an
array that
-(eventually) has a 4 in it.
-</p>
-<p>Smartmatching one hash against another reports whether both contain the
-same keys, no more and no less. This could be used to see whether two
-records have the same field names, without caring what values those fields
-might have. For example:
-</p>
-<pre class="verbatim"> use v5.10.1;
- sub make_dogtag {
- state $REQUIRED_FIELDS = { name=>1, rank=>1, serial_num=>1 };
-
- my ($class, $init_fields) = @_;
-
- die "Must supply (only) name, rank, and serial number"
- unless $init_fields ~~ $REQUIRED_FIELDS;
-
- ...
- }
-</pre>
-<p>or, if other non-required fields are allowed, use ARRAY ~~ HASH:
-</p>
-<pre class="verbatim"> use v5.10.1;
- sub make_dogtag {
- state $REQUIRED_FIELDS = { name=>1, rank=>1, serial_num=>1 };
-
- my ($class, $init_fields) = @_;
-
- die "Must supply (at least) name, rank, and serial number"
- unless [keys %{$init_fields}] ~~ $REQUIRED_FIELDS;
-
- ...
- }
-</pre>
-<p>The smartmatch operator is most often used as the implicit operator of a
-<code>when</code> clause. See the section on "Switch Statements" in
<a href="#perlsyn-NAME">perlsyn NAME</a>.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlop-Smartmatching-of-Objects" accesskey="1">perlop Smartmatching of
Objects</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlop-Smartmatching-of-Objects"></a>
-<div class="header">
-<p>
-Up: <a href="#perlop-Smartmatch-Operator" accesskey="u" rel="up">perlop
Smartmatch Operator</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Smartmatching-of-Objects"></a>
-<h4 class="subsubsection">48.2.14.1 Smartmatching of Objects</h4>
-
-<p>To avoid relying on an object’s underlying representation, if the
-smartmatch’s right operand is an object that doesn’t overload
<code>~~</code>,
-it raises the exception "<code>Smartmatching a non-overloaded object
-breaks encapsulation</code>". That’s because one has no business
digging
-around to see whether something is "in" an object. These are all
-illegal on objects without a <code>~~</code> overload:
-</p>
-<pre class="verbatim"> %hash ~~ $object
- 42 ~~ $object
- "fred" ~~ $object
-</pre>
-<p>However, you can change the way an object is smartmatched by overloading
-the <code>~~</code> operator. This is allowed to
-extend the usual smartmatch semantics.
-For objects that do have an <code>~~</code> overload, see <a
href="overload.html#Top">(overload)</a>.
-</p>
-<p>Using an object as the left operand is allowed, although not very useful.
-Smartmatching rules take precedence over overloading, so even if the
-object in the left operand has smartmatch overloading, this will be
-ignored. A left operand that is a non-overloaded object falls back on a
-string or numeric comparison of whatever the <code>ref</code> operator
returns. That
-means that
-</p>
-<pre class="verbatim"> $object ~~ X
-</pre>
-<p>does <em>not</em> invoke the overload method with <code><em>X</em></code>
as an argument.
-Instead the above table is consulted as normal, and based on the type of
-<code><em>X</em></code>, overloading may or may not be invoked. For simple
strings or
-numbers, "in" becomes equivalent to this:
-</p>
-<pre class="verbatim"> $object ~~ $number ref($object) == $number
- $object ~~ $string ref($object) eq $string
-</pre>
-<p>For example, this reports that the handle smells IOish
-(but please don’t really do this!):
-</p>
-<pre class="verbatim"> use IO::Handle;
- my $fh = IO::Handle->new();
- if ($fh ~~ /\bIO\b/) {
- say "handle smells IOish";
- }
-</pre>
-<p>That’s because it treats <code>$fh</code> as a string like
-<code>"IO::Handle=GLOB(0x8039e0)"</code>, then pattern matches
against that.
-</p>
-<hr>
-<a name="perlop-Bitwise-And"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Bitwise-Or-and-Exclusive-Or" accesskey="n"
rel="next">perlop Bitwise Or and Exclusive Or</a>, Previous: <a
href="#perlop-Smartmatch-Operator" accesskey="p" rel="prev">perlop Smartmatch
Operator</a>, Up: <a href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Bitwise-And"></a>
-<h4 class="subsection">48.2.15 Bitwise And</h4>
-
-<p>Binary <code>"&"</code> returns its operands ANDed together
bit by bit. Although no
-warning is currently raised, the result is not well defined when this operation
-is performed on operands that aren’t either numbers (see
-<a href="#perlop-Integer-Arithmetic">Integer Arithmetic</a>) nor bitstrings
(see <a href="#perlop-Bitwise-String-Operators">Bitwise String Operators</a>).
-</p>
-<p>Note that <code>"&"</code> has lower priority than relational
operators, so for example
-the parentheses are essential in a test like
-</p>
-<pre class="verbatim"> print "Even\n" if ($x & 1) == 0;
-</pre>
-<p>If the experimental "bitwise" feature is enabled via
<code>use feature 'bitwise'</code><!-- /@w -->, then this operator
always treats its operand as numbers. This
-feature produces a warning unless you also use
<code>no warnings 'experimental::bitwise'<!-- /@w --></code>.
-</p>
-<hr>
-<a name="perlop-Bitwise-Or-and-Exclusive-Or"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-C_002dstyle-Logical-And" accesskey="n"
rel="next">perlop C-style Logical And</a>, Previous: <a
href="#perlop-Bitwise-And" accesskey="p" rel="prev">perlop Bitwise And</a>, Up:
<a href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Bitwise-Or-and-Exclusive-Or"></a>
-<h4 class="subsection">48.2.16 Bitwise Or and Exclusive Or</h4>
-
-<p>Binary <code>"|"</code> returns its operands ORed together bit by
bit.
-</p>
-<p>Binary <code>"^"</code> returns its operands XORed together bit
by bit.
-</p>
-<p>Although no warning is currently raised, the results are not well
-defined when these operations are performed on operands that aren’t
either
-numbers (see <a href="#perlop-Integer-Arithmetic">Integer Arithmetic</a>) nor
bitstrings (see <a href="#perlop-Bitwise-String-Operators">Bitwise String
-Operators</a>).
-</p>
-<p>Note that <code>"|"</code> and <code>"^"</code> have
lower priority than relational operators, so
-for example the parentheses are essential in a test like
-</p>
-<pre class="verbatim"> print "false\n" if (8 | 2) != 10;
-</pre>
-<p>If the experimental "bitwise" feature is enabled via
<code>use feature 'bitwise'</code><!-- /@w -->, then this operator
always treats its operand as numbers. This
-feature produces a warning unless you also use
<code>no warnings 'experimental::bitwise'</code><!-- /@w -->.
-</p>
-<hr>
-<a name="perlop-C_002dstyle-Logical-And"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-C_002dstyle-Logical-Or" accesskey="n" rel="next">perlop
C-style Logical Or</a>, Previous: <a href="#perlop-Bitwise-Or-and-Exclusive-Or"
accesskey="p" rel="prev">perlop Bitwise Or and Exclusive Or</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="C_002dstyle-Logical-And"></a>
-<h4 class="subsection">48.2.17 C-style Logical And</h4>
-
-<p>Binary <code>"&&"</code> performs a short-circuit logical
AND operation. That is,
-if the left operand is false, the right operand is not even evaluated.
-Scalar or list context propagates down to the right operand if it
-is evaluated.
-</p>
-<hr>
-<a name="perlop-C_002dstyle-Logical-Or"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Logical-Defined_002dOr" accesskey="n" rel="next">perlop
Logical Defined-Or</a>, Previous: <a href="#perlop-C_002dstyle-Logical-And"
accesskey="p" rel="prev">perlop C-style Logical And</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="C_002dstyle-Logical-Or"></a>
-<h4 class="subsection">48.2.18 C-style Logical Or</h4>
-
-<p>Binary <code>"||"</code> performs a short-circuit logical OR
operation. That is,
-if the left operand is true, the right operand is not even evaluated.
-Scalar or list context propagates down to the right operand if it
-is evaluated.
-</p>
-<hr>
-<a name="perlop-Logical-Defined_002dOr"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Range-Operators" accesskey="n" rel="next">perlop Range
Operators</a>, Previous: <a href="#perlop-C_002dstyle-Logical-Or" accesskey="p"
rel="prev">perlop C-style Logical Or</a>, Up: <a href="#perlop-DESCRIPTION"
accesskey="u" rel="up">perlop DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Logical-Defined_002dOr"></a>
-<h4 class="subsection">48.2.19 Logical Defined-Or</h4>
-
-<p>Although it has no direct equivalent in C, Perl’s <code>//</code>
operator is related
-to its C-style "or". In fact, it’s exactly the same as
<code>||</code>, except that it
-tests the left hand side’s definedness instead of its truth. Thus,
-<code>EXPR1 // EXPR2</code><!-- /@w --> returns the value of
<code>EXPR1</code> if it’s defined,
-otherwise, the value of <code>EXPR2</code> is returned.
-(<code>EXPR1</code> is evaluated in scalar context, <code>EXPR2</code>
-in the context of <code>//</code> itself). Usually,
-this is the same result as
<code>defined(EXPR1) ? EXPR1 : EXPR2</code><!-- /@w -->
(except that
-the ternary-operator form can be used as a lvalue, while
<code>EXPR1 // EXPR2</code><!-- /@w -->
-cannot). This is very useful for
-providing default values for variables. If you actually want to test if
-at least one of <code>$x</code> and <code>$y</code> is defined, use
<code>defined($x // $y)</code><!-- /@w -->.
-</p>
-<p>The <code>||</code>, <code>//</code> and <code>&&</code> operators
return the last value evaluated
-(unlike C’s <code>||</code> and <code>&&</code>, which return 0
or 1). Thus, a reasonably
-portable way to find out the home directory might be:
-</p>
-<pre class="verbatim"> $home = $ENV{HOME}
- // $ENV{LOGDIR}
- // (getpwuid($<))[7]
- // die "You're homeless!\n";
-</pre>
-<p>In particular, this means that you shouldn’t use this
-for selecting between two aggregates for assignment:
-</p>
-<pre class="verbatim"> @a = @b || @c; # this is wrong
- @a = scalar(@b) || @c; # really meant this
- @a = @b ? @b : @c; # this works fine, though
-</pre>
-<p>As alternatives to <code>&&</code> and <code>||</code> when used for
-control flow, Perl provides the <code>and</code> and <code>or</code> operators
(see below).
-The short-circuit behavior is identical. The precedence of
<code>"and"</code>
-and <code>"or"</code> is much lower, however, so that you can safely
use them after a
-list operator without the need for parentheses:
-</p>
-<pre class="verbatim"> unlink "alpha", "beta",
"gamma"
- or gripe(), next LINE;
-</pre>
-<p>With the C-style operators that would have been written like this:
-</p>
-<pre class="verbatim"> unlink("alpha", "beta",
"gamma")
- || (gripe(), next LINE);
-</pre>
-<p>It would be even more readable to write that this way:
-</p>
-<pre class="verbatim"> unless(unlink("alpha", "beta",
"gamma")) {
- gripe();
- next LINE;
- }
-</pre>
-<p>Using <code>"or"</code> for assignment is unlikely to do what you
want; see below.
-</p>
-<hr>
-<a name="perlop-Range-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Conditional-Operator" accesskey="n" rel="next">perlop
Conditional Operator</a>, Previous: <a href="#perlop-Logical-Defined_002dOr"
accesskey="p" rel="prev">perlop Logical Defined-Or</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Range-Operators"></a>
-<h4 class="subsection">48.2.20 Range Operators</h4>
-
-<p>Binary <code>".."</code> is the range operator, which is really
two different
-operators depending on the context. In list context, it returns a
-list of values counting (up by ones) from the left value to the right
-value. If the left value is greater than the right value then it
-returns the empty list. The range operator is useful for writing
-<code>foreach (1..10)</code><!-- /@w --> loops and for doing slice
operations on arrays. In
-the current implementation, no temporary array is created when the
-range operator is used as the expression in <code>foreach</code> loops, but
older
-versions of Perl might burn a lot of memory when you write something
-like this:
-</p>
-<pre class="verbatim"> for (1 .. 1_000_000) {
- # code
- }
-</pre>
-<p>The range operator also works on strings, using the magical
-auto-increment, see below.
-</p>
-<p>In scalar context, <code>".."</code> returns a boolean value.
The operator is
-bistable, like a flip-flop, and emulates the line-range (comma)
-operator of <strong>sed</strong>, <strong>awk</strong>, and various editors.
Each <code>".."</code> operator
-maintains its own boolean state, even across calls to a subroutine
-that contains it. It is false as long as its left operand is false.
-Once the left operand is true, the range operator stays true until the
-right operand is true, <em>AFTER</em> which the range operator becomes false
-again. It doesn’t become false till the next time the range operator
-is evaluated. It can test the right operand and become false on the
-same evaluation it became true (as in <strong>awk</strong>), but it still
returns
-true once. If you don’t want it to test the right operand until the
-next evaluation, as in <strong>sed</strong>, just use three dots
(<code>"..."</code>) instead of
-two. In all other regards, <code>"..."</code> behaves just like
<code>".."</code> does.
-</p>
-<p>The right operand is not evaluated while the operator is in the
-"false" state, and the left operand is not evaluated while the
-operator is in the "true" state. The precedence is a little lower
-than || and &&. The value returned is either the empty string for
-false, or a sequence number (beginning with 1) for true. The sequence
-number is reset for each range encountered. The final sequence number
-in a range has the string <code>"E0"</code> appended to it, which
doesn’t affect
-its numeric value, but gives you something to search for if you want
-to exclude the endpoint. You can exclude the beginning point by
-waiting for the sequence number to be greater than 1.
-</p>
-<p>If either operand of scalar <code>".."</code> is a constant
expression,
-that operand is considered true if it is equal (<code>==</code>) to the current
-input line number (the <code>$.</code> variable).
-</p>
-<p>To be pedantic, the comparison is actually
<code>int(EXPR) == int(EXPR)</code><!-- /@w -->,
-but that is only an issue if you use a floating point expression; when
-implicitly using <code>$.</code> as described in the previous paragraph, the
-comparison is <code>int(EXPR) == int($.)</code><!-- /@w --> which is
only an issue when <code>$.</code>
-is set to a floating point value and you are not reading from a file.
-Furthermore, <code>"span" .. "spat"</code><!--
/@w --> or <code>2.18 .. 3.14</code><!-- /@w --> will not do what
-you want in scalar context because each of the operands are evaluated
-using their integer representation.
-</p>
-<p>Examples:
-</p>
-<p>As a scalar operator:
-</p>
-<pre class="verbatim"> if (101 .. 200) { print; } # print 2nd hundred
lines, short for
- # if ($. == 101 .. $. == 200) { print; }
-
- next LINE if (1 .. /^$/); # skip header lines, short for
- # next LINE if ($. == 1 .. /^$/);
- # (typically in a loop labeled LINE)
-
- s/^/> / if (/^$/ .. eof()); # quote body
-
- # parse mail messages
- while (<>) {
- $in_header = 1 .. /^$/;
- $in_body = /^$/ .. eof;
- if ($in_header) {
- # do something
- } else { # in body
- # do something else
- }
- } continue {
- close ARGV if eof; # reset $. each file
- }
-</pre>
-<p>Here’s a simple example to illustrate the difference between
-the two range operators:
-</p>
-<pre class="verbatim"> @lines = (" - Foo",
- "01 - Bar",
- "1 - Baz",
- " - Quux");
-
- foreach (@lines) {
- if (/0/ .. /1/) {
- print "$_\n";
- }
- }
-</pre>
-<p>This program will print only the line containing "Bar". If
-the range operator is changed to <code>...</code>, it will also print the
-"Baz" line.
-</p>
-<p>And now some examples as a list operator:
-</p>
-<pre class="verbatim"> for (101 .. 200) { print } # print $_ 100 times
- @foo = @foo[0 .. $#foo]; # an expensive no-op
- @foo = @foo[$#foo-4 .. $#foo]; # slice last 5 items
-</pre>
-<p>The range operator (in list context) makes use of the magical
-auto-increment algorithm if the operands are strings. You
-can say
-</p>
-<pre class="verbatim"> @alphabet = ("A" .. "Z");
-</pre>
-<p>to get all normal letters of the English alphabet, or
-</p>
-<pre class="verbatim"> $hexdigit = (0 .. 9, "a" ..
"f")[$num & 15];
-</pre>
-<p>to get a hexadecimal digit, or
-</p>
-<pre class="verbatim"> @z2 = ("01" .. "31");
- print $z2[$mday];
-</pre>
-<p>to get dates with leading zeros.
-</p>
-<p>If the final value specified is not in the sequence that the magical
-increment would produce, the sequence goes until the next value would
-be longer than the final value specified.
-</p>
-<p>If the initial value specified isn’t part of a magical increment
-sequence (that is, a non-empty string matching
<code>/^[a-zA-Z]*[0-9]*\z/</code>),
-only the initial value will be returned. So the following will only
-return an alpha:
-</p>
-<pre class="verbatim"> use charnames "greek";
- my @greek_small = ("\N{alpha}" .. "\N{omega}");
-</pre>
-<p>To get the 25 traditional lowercase Greek letters, including both sigmas,
-you could use this instead:
-</p>
-<pre class="verbatim"> use charnames "greek";
- my @greek_small = map { chr } ( ord("\N{alpha}")
- ..
- ord("\N{omega}")
- );
-</pre>
-<p>However, because there are <em>many</em> other lowercase Greek characters
than
-just those, to match lowercase Greek characters in a regular expression,
-you could use the pattern <code>/(?:(?=\p{Greek})\p{Lower})+/</code> (or the
-<a href="#perlrecharclass-Extended-Bracketed-Character-Classes">experimental
feature</a> <code>/(?[ \p{Greek} & \p{Lower} ])+/<!--
/@w --></code>).
-</p>
-<p>Because each operand is evaluated in integer form,
<code>2.18 .. 3.14</code><!-- /@w --> will
-return two elements in list context.
-</p>
-<pre class="verbatim"> @list = (2.18 .. 3.14); # same as @list = (2 .. 3);
-</pre>
-<hr>
-<a name="perlop-Conditional-Operator"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Assignment-Operators" accesskey="n" rel="next">perlop
Assignment Operators</a>, Previous: <a href="#perlop-Range-Operators"
accesskey="p" rel="prev">perlop Range Operators</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Conditional-Operator"></a>
-<h4 class="subsection">48.2.21 Conditional Operator</h4>
-
-<p>Ternary <code>"?:"</code> is the conditional operator, just as in
C. It works much
-like an if-then-else. If the argument before the <code>?</code> is true, the
-argument before the <code>:</code> is returned, otherwise the argument after
the
-<code>:</code> is returned. For example:
-</p>
-<pre class="verbatim"> printf "I have %d dog%s.\n", $n,
- ($n == 1) ? "" : "s";
-</pre>
-<p>Scalar or list context propagates downward into the 2nd
-or 3rd argument, whichever is selected.
-</p>
-<pre class="verbatim"> $x = $ok ? $y : $z; # get a scalar
- @x = $ok ? @y : @z; # get an array
- $x = $ok ? @y : @z; # oops, that's just a count!
-</pre>
-<p>The operator may be assigned to if both the 2nd and 3rd arguments are
-legal lvalues (meaning that you can assign to them):
-</p>
-<pre class="verbatim"> ($x_or_y ? $x : $y) = $z;
-</pre>
-<p>Because this operator produces an assignable result, using assignments
-without parentheses will get you in trouble. For example, this:
-</p>
-<pre class="verbatim"> $x % 2 ? $x += 10 : $x += 2
-</pre>
-<p>Really means this:
-</p>
-<pre class="verbatim"> (($x % 2) ? ($x += 10) : $x) += 2
-</pre>
-<p>Rather than this:
-</p>
-<pre class="verbatim"> ($x % 2) ? ($x += 10) : ($x += 2)
-</pre>
-<p>That should probably be written more simply as:
-</p>
-<pre class="verbatim"> $x += ($x % 2) ? 10 : 2;
-</pre>
-<hr>
-<a name="perlop-Assignment-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Comma-Operator" accesskey="n" rel="next">perlop Comma
Operator</a>, Previous: <a href="#perlop-Conditional-Operator" accesskey="p"
rel="prev">perlop Conditional Operator</a>, Up: <a href="#perlop-DESCRIPTION"
accesskey="u" rel="up">perlop DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Assignment-Operators"></a>
-<h4 class="subsection">48.2.22 Assignment Operators</h4>
-
-<p>> = >>>
-</p>
-<p><code>"="</code> is the ordinary assignment operator.
-</p>
-<p>Assignment operators work as in C. That is,
-</p>
-<pre class="verbatim"> $x += 2;
-</pre>
-<p>is equivalent to
-</p>
-<pre class="verbatim"> $x = $x + 2;
-</pre>
-<p>although without duplicating any side effects that dereferencing the lvalue
-might trigger, such as from <code>tie()</code>. Other assignment operators
work similarly.
-The following are recognized:
-</p>
-<pre class="verbatim"> **= += *= &= &.= <<=
&&=
- -= /= |= |.= >>= ||=
- .= %= ^= ^.= //=
- x=
-</pre>
-<p>Although these are grouped by family, they all have the precedence
-of assignment. These combined assignment operators can only operate on
-scalars, whereas the ordinary assignment operator can assign to arrays,
-hashes, lists and even references. (See <a
href="#perldata-Context">"Context"</a>
-and <a href="#perldata-List-value-constructors">perldata List value
constructors</a>, and <a href="#perlref-Assigning-to-References">perlref
Assigning to References</a>.)
-</p>
-<p>Unlike in C, the scalar assignment operator produces a valid lvalue.
-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:
-</p>
-<pre class="verbatim"> ($tmp = $global) =~ tr/13579/24680/;
-</pre>
-<p>Although as of 5.14, that can be also be accomplished this way:
-</p>
-<pre class="verbatim"> use v5.14;
- $tmp = ($global =~ tr/13579/24680/r);
-</pre>
-<p>Likewise,
-</p>
-<pre class="verbatim"> ($x += 2) *= 3;
-</pre>
-<p>is equivalent to
-</p>
-<pre class="verbatim"> $x += 2;
- $x *= 3;
-</pre>
-<p>Similarly, a list assignment in list context produces the list of
-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.
-</p>
-<p>The three dotted bitwise assignment operators (<code>&.=</code>
<code>|.=</code> <code>^.=</code>) are new in
-Perl 5.22 and experimental. See <a
href="#perlop-Bitwise-String-Operators">Bitwise String Operators</a>.
-</p>
-<hr>
-<a name="perlop-Comma-Operator"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-List-Operators-_0028Rightward_0029" accesskey="n"
rel="next">perlop List Operators (Rightward)</a>, Previous: <a
href="#perlop-Assignment-Operators" accesskey="p" rel="prev">perlop Assignment
Operators</a>, Up: <a href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Comma-Operator"></a>
-<h4 class="subsection">48.2.23 Comma Operator</h4>
-
-<p>Binary <code>","</code> is the comma operator. In scalar context
it evaluates
-its left argument, throws that value away, then evaluates its right
-argument and returns that value. This is just like C’s comma operator.
-</p>
-<p>In list context, it’s just the list argument separator, and inserts
-both its arguments into the list. These arguments are also evaluated
-from left to right.
-</p>
-<p>The <code>=></code> operator (sometimes pronounced "fat
comma") is a synonym
-for the comma except that it causes a
-word on its left to be interpreted as a string if it begins with a letter
-or underscore and is composed only of letters, digits and underscores.
-This includes operands that might otherwise be interpreted as operators,
-constants, single number v-strings or function calls. If in doubt about
-this behavior, the left operand can be quoted explicitly.
-</p>
-<p>Otherwise, the <code>=></code> operator behaves exactly as the comma
operator
-or list argument separator, according to context.
-</p>
-<p>For example:
-</p>
-<pre class="verbatim"> use constant FOO => "something";
-
- my %h = ( FOO => 23 );
-</pre>
-<p>is equivalent to:
-</p>
-<pre class="verbatim"> my %h = ("FOO", 23);
-</pre>
-<p>It is <em>NOT</em>:
-</p>
-<pre class="verbatim"> my %h = ("something", 23);
-</pre>
-<p>The <code>=></code> operator is helpful in documenting the correspondence
-between keys and values in hashes, and other paired elements in lists.
-</p>
-<pre class="verbatim"> %hash = ( $key => $value );
- login( $username => $password );
-</pre>
-<p>The special quoting behavior ignores precedence, and hence may apply to
-<em>part</em> of the left operand:
-</p>
-<pre class="verbatim"> print time.shift => "bbb";
-</pre>
-<p>That example prints something like
<code>"1314363215shiftbbb"</code>, because the
-<code>=></code> implicitly quotes the <code>shift</code> immediately on its
left, ignoring
-the fact that <code>time.shift</code> is the entire left operand.
-</p>
-<hr>
-<a name="perlop-List-Operators-_0028Rightward_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Logical-Not" accesskey="n" rel="next">perlop Logical
Not</a>, Previous: <a href="#perlop-Comma-Operator" accesskey="p"
rel="prev">perlop Comma Operator</a>, Up: <a href="#perlop-DESCRIPTION"
accesskey="u" rel="up">perlop DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="List-Operators-_0028Rightward_0029"></a>
-<h4 class="subsection">48.2.24 List Operators (Rightward)</h4>
-
-<p>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
-<code>"and"</code>, <code>"or"</code>, and
<code>"not"</code>, which may be used to evaluate calls to list
-operators without the need for parentheses:
-</p>
-<pre class="verbatim"> open HANDLE, "< :utf8",
"filename" or die "Can't open: $!\n";
-</pre>
-<p>However, some people find that code harder to read than writing
-it with parentheses:
-</p>
-<pre class="verbatim"> open(HANDLE, "< :utf8",
"filename") or die "Can't open: $!\n";
-</pre>
-<p>in which case you might as well just use the more customary
<code>"||"</code> operator:
-</p>
-<pre class="verbatim"> open(HANDLE, "< :utf8",
"filename") || die "Can't open: $!\n";
-</pre>
-<p>See also discussion of list operators in Terms and List Operators
(Leftward).
-</p>
-<hr>
-<a name="perlop-Logical-Not"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Logical-And" accesskey="n" rel="next">perlop Logical
And</a>, Previous: <a href="#perlop-List-Operators-_0028Rightward_0029"
accesskey="p" rel="prev">perlop List Operators (Rightward)</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Logical-Not"></a>
-<h4 class="subsection">48.2.25 Logical Not</h4>
-
-<p>Unary <code>"not"</code> returns the logical negation of the
expression to its right.
-It’s the equivalent of <code>"!"</code> except for the very
low precedence.
-</p>
-<hr>
-<a name="perlop-Logical-And"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Logical-or-and-Exclusive-Or" accesskey="n"
rel="next">perlop Logical or and Exclusive Or</a>, Previous: <a
href="#perlop-Logical-Not" accesskey="p" rel="prev">perlop Logical Not</a>, Up:
<a href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Logical-And"></a>
-<h4 class="subsection">48.2.26 Logical And</h4>
-
-<p>Binary <code>"and"</code> returns the logical conjunction of the
two surrounding
-expressions. It’s equivalent to <code>&&</code> except for the
very low
-precedence. This means that it short-circuits: the right
-expression is evaluated only if the left expression is true.
-</p>
-<hr>
-<a name="perlop-Logical-or-and-Exclusive-Or"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-C-Operators-Missing-From-Perl" accesskey="n"
rel="next">perlop C Operators Missing From Perl</a>, Previous: <a
href="#perlop-Logical-And" accesskey="p" rel="prev">perlop Logical And</a>, Up:
<a href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Logical-or-and-Exclusive-Or"></a>
-<h4 class="subsection">48.2.27 Logical or and Exclusive Or</h4>
-
-<p>Binary <code>"or"</code> returns the logical disjunction of the
two surrounding
-expressions. It’s equivalent to <code>||</code> except for the very low
precedence.
-This makes it useful for control flow:
-</p>
-<pre class="verbatim"> print FH $data or die "Can't write
to FH: $!";
-</pre>
-<p>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 <code>||</code> operator.
-It usually works out better for flow control than in assignments:
-</p>
-<pre class="verbatim"> $x = $y or $z; # bug: this is wrong
- ($x = $y) or $z; # really means this
- $x = $y || $z; # better written this way
-</pre>
-<p>However, when it’s a list-context assignment and you’re trying
to use
-<code>||</code> for control flow, you probably need
<code>"or"</code> so that the assignment
-takes higher precedence.
-</p>
-<pre class="verbatim"> @info = stat($file) || die; # oops, scalar sense
of stat!
- @info = stat($file) or die; # better, now @info gets its due
-</pre>
-<p>Then again, you could always use parentheses.
-</p>
-<p>Binary <code>"xor"</code> returns the exclusive-OR of the two
surrounding expressions.
-It cannot short-circuit (of course).
-</p>
-<p>There is no low precedence operator for defined-OR.
-</p>
-<hr>
-<a name="perlop-C-Operators-Missing-From-Perl"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Quote-and-Quote_002dlike-Operators" accesskey="n"
rel="next">perlop Quote and Quote-like Operators</a>, Previous: <a
href="#perlop-Logical-or-and-Exclusive-Or" accesskey="p" rel="prev">perlop
Logical or and Exclusive Or</a>, Up: <a href="#perlop-DESCRIPTION"
accesskey="u" rel="up">perlop DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="C-Operators-Missing-From-Perl"></a>
-<h4 class="subsection">48.2.28 C Operators Missing From Perl</h4>
-
-<p>Here is what C has that Perl doesn’t:
-</p>
-<dl compact="compact">
-<dt>unary &</dt>
-<dd><a name="perlop-unary-_0026"></a>
-<p>Address-of operator. (But see the <code>"\"</code> operator for
taking a reference.)
-</p>
-</dd>
-<dt>unary *</dt>
-<dd><a name="perlop-unary-_002a"></a>
-<p>Dereference-address operator. (Perl’s prefix dereferencing
-operators are typed: <code>$</code>, <code>@</code>, <code>%</code>, and
<code>&</code>.)
-</p>
-</dd>
-<dt>(TYPE)</dt>
-<dd><a name="perlop-_0028TYPE_0029"></a>
-<p>Type-casting operator.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlop-Quote-and-Quote_002dlike-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Regexp-Quote_002dLike-Operators" accesskey="n"
rel="next">perlop Regexp Quote-Like Operators</a>, Previous: <a
href="#perlop-C-Operators-Missing-From-Perl" accesskey="p" rel="prev">perlop C
Operators Missing From Perl</a>, Up: <a href="#perlop-DESCRIPTION"
accesskey="u" rel="up">perlop DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Quote-and-Quote_002dlike-Operators"></a>
-<h4 class="subsection">48.2.29 Quote and Quote-like Operators</h4>
-
-<pre class="verbatim"> >
-
-</pre>
-<p>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
-for these behaviors, but also provides a way for you to choose your
-quote character for any of them. In the following table, a <code>{}</code>
represents
-any pair of delimiters you choose.
-</p>
-<pre class="verbatim"> Customary Generic Meaning Interpolates
- '' q{} Literal no
- "" qq{} Literal yes
- `` qx{} Command yes*
- qw{} Word list no
- // m{} Pattern match yes*
- 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 ''.
-</pre>
-<p>Non-bracketing delimiters use the same character fore and aft, but the four
-sorts of ASCII brackets (round, angle, square, curly) all nest, which means
-that
-</p>
-<pre class="verbatim"> q{foo{bar}baz}
-</pre>
-<p>is the same as
-</p>
-<pre class="verbatim"> 'foo{bar}baz'
-</pre>
-<p>Note, however, that this does not always work for quoting Perl code:
-</p>
-<pre class="verbatim"> $s = q{ if($x eq "}") ... }; # WRONG
-</pre>
-<p>is a syntax error. The <code><a
href="Text-Balanced.html#Top">(Text-Balanced)</a></code> module (standard as of
v5.8,
-and from CPAN before then) is able to do this properly.
-</p>
-<p>There can be whitespace between the operator and the quoting
-characters, except when <code>#</code> is being used as the quoting character.
-<code>q#foo#</code> is parsed as the string <code>foo</code>, while
<code>q #foo#</code><!-- /@w --> is the
-operator <code>q</code> followed by a comment. Its argument will be taken
-from the next line. This allows you to write:
-</p>
-<pre class="verbatim"> s {foo} # Replace foo
- {bar} # with bar.
-</pre>
-<p>The following escape sequences are available in constructs that interpolate,
-and in transliterations:
-</p>
-<pre class="verbatim"> 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)
-</pre>
-<dl compact="compact">
-<dt>[1]</dt>
-<dd><a name="perlop-_005b1_005d"></a>
-<p>The result is the character specified by the hexadecimal number between
-the braces. See <a href="#perlop-_005b8_005d">[8]</a> below for details on
which character.
-</p>
-<p>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.
-</p>
-<p>If there are no valid digits between the braces, the generated character is
-the NULL character (<code>\x{00}</code>). However, an explicit empty brace
(<code>\x{}</code>)
-will not cause a warning (currently).
-</p>
-</dd>
-<dt>[2]</dt>
-<dd><a name="perlop-_005b2_005d"></a>
-<p>The result is the character specified by the hexadecimal number in the range
-0x00 to 0xFF. See <a href="#perlop-_005b8_005d">[8]</a> below for details on
which character.
-</p>
-<p>Only hexadecimal digits are valid following <code>\x</code>. When
<code>\x</code> is followed
-by fewer than two valid digits, any valid digits will be zero-padded. This
-means that <code>\x7</code> will be interpreted as <code>\x07</code>, and a
lone <code>"\x"</code> will be
-interpreted as <code>\x00</code>. 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:
-</p>
-<pre class="verbatim"> Original Result Warns?
- "\x7" "\x07" no
- "\x" "\x00" no
- "\x7q" "\x07q" yes
- "\xq" "\x00q" yes
-</pre>
-</dd>
-<dt>[3]</dt>
-<dd><a name="perlop-_005b3_005d"></a>
-<p>The result is the Unicode character or character sequence given by
<em>name</em>.
-See <a href="charnames.html#Top">(charnames)</a>.
-</p>
-</dd>
-<dt>[4]</dt>
-<dd><a name="perlop-_005b4_005d"></a>
-<p><code>\N{U+<em>hexadecimal number</em>}</code><!-- /@w --> means the
Unicode character whose Unicode code
-point is <em>hexadecimal number</em>.
-</p>
-</dd>
-<dt>[5]</dt>
-<dd><a name="perlop-_005b5_005d"></a>
-<p>The character following <code>\c</code> is mapped to some other character
as shown in the
-table:
-</p>
-<pre class="verbatim"> 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)
- # See below for chr(28)
- \c] chr(29)
- \c^ chr(30)
- \c_ chr(31)
- \c? chr(127) # (on ASCII platforms; see below for link to
- # EBCDIC discussion)
-</pre>
-<p>In other words, it’s the character whose code point has had 64
xor’d with
-its uppercase. <code>\c?</code> is DELETE on ASCII platforms because
-<code>ord("?") ^ 64</code><!-- /@w --> is 127, and
-<code>\c@</code> is NULL because the ord of <code>"@"</code> is 64,
so xor’ing 64 itself produces 0.
-</p>
-<p>Also, <code>\c\<em>X</em></code> yields
<code> chr(28) . "<em>X</em>"</code><!-- /@w --> for
any <em>X</em>, but cannot come at the
-end of a string, because the backslash would be parsed as escaping the end
-quote.
-</p>
-<p>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
-<a href="#perlebcdic-OPERATOR-DIFFERENCES">perlebcdic OPERATOR DIFFERENCES</a>
for a full discussion of the
-differences between these for ASCII versus EBCDIC platforms.
-</p>
-<p>Use of any other character following the <code>"c"</code> besides
those listed above is
-discouraged, and as of Perl v5.20, the only characters actually allowed
-are the printable ASCII ones, minus the left brace <code>"{"</code>.
What happens
-for any of the allowed other characters is that the value is derived by
-xor’ing with the seventh bit, which is 64, and a warning raised if
-enabled. Using the non-allowed characters generates a fatal error.
-</p>
-<p>To get platform independent controls, you can use <code>\N{...}</code>.
-</p>
-</dd>
-<dt>[6]</dt>
-<dd><a name="perlop-_005b6_005d"></a>
-<p>The result is the character specified by the octal number between the
braces.
-See <a href="#perlop-_005b8_005d">[8]</a> below for details on which character.
-</p>
-<p>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.
-</p>
-</dd>
-<dt>[7]</dt>
-<dd><a name="perlop-_005b7_005d"></a>
-<p>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
-<a href="#perlop-_005b8_005d">[8]</a> below for details on which character.
-</p>
-<p>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, in a regular expression it may be confused with a backreference;
-see <a href="#perlrebackslash-Octal-escapes">perlrebackslash Octal
escapes</a>.) Starting in Perl 5.14, you may
-use <code>\o{}</code> instead, which avoids all these problems. Otherwise, it
is best to
-use this construct only for ordinals <code>\077</code> and below, remembering
to pad to
-the left with zeros to make three digits. For larger ordinals, either use
-<code>\o{}</code>, or convert to something else, such as to hex and use
<code>\N{U+}</code>
-(which is portable between platforms with different character sets) or
-<code>\x{}</code> instead.
-</p>
-</dd>
-<dt>[8]</dt>
-<dd><a name="perlop-_005b8_005d"></a>
-<p>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 <code>\x{50}</code> and <code>\o{120}</code> 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 <code>"P"</code>, and in EBCDIC it is the
ampersand symbol <code>"&"</code>.
-<code>\x{100}</code> and <code>\o{400}</code> 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 256th position (indexed by 0) in Unicode is
-<code>LATIN CAPITAL LETTER A WITH MACRON</code>.
-</p>
-<p>There are a couple of exceptions to the above rule.
<code>\N{U+<em>hex number</em>}</code><!-- /@w --> is
-always interpreted as a Unicode code point, so that <code>\N{U+0050}</code> is
<code>"P"</code> even
-on EBCDIC platforms. And if <code><a
href="encoding.html#Top">(encoding)use encoding</a><!-- /@w --></code> 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.
-</p>
-</dd>
-</dl>
-
-<p><strong>NOTE</strong>: Unlike C and other languages, Perl has no
<code>\v</code> escape sequence for
-the vertical tab (VT, which is 11 in both ASCII and EBCDIC), but you may
-use <code>\N{VT}</code>, <code>\ck</code>, <code>\N{U+0b}</code>, or
<code>\x0b</code>. (<code>\v</code>
-does have meaning in regular expression patterns in Perl, see <a
href="#perlre-NAME">perlre NAME</a>.)
-</p>
-<p>The following escape sequences are available in constructs that interpolate,
-but not in transliterations.
-</p>
-<pre class="verbatim"> \l lowercase next character only
- \u titlecase (not uppercase!) next character only
- \L lowercase all characters till \E or end of string
- \U uppercase all characters till \E or end of string
- \F foldcase all characters till \E or end of string
- \Q quote (disable) pattern metacharacters till \E or
- end of string
- \E end either case modification or quoted section
- (whichever was last seen)
-</pre>
-<p>See <a href="#perlfunc-quotemeta">perlfunc quotemeta</a> for the exact
definition of characters that
-are quoted by <code>\Q</code>.
-</p>
-<p><code>\L</code>, <code>\U</code>, <code>\F</code>, and <code>\Q</code> can
stack, in which case you need one
-<code>\E</code> for each. For example:
-</p>
-<pre class="verbatim"> 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?
-</pre>
-<p>If a <code>use locale</code><!-- /@w --> form that includes
<code>LC_CTYPE</code> is in effect (see
-<a href="#perllocale-NAME">perllocale NAME</a>), the case map used by
<code>\l</code>, <code>\L</code>, <code>\u</code>, and <code>\U</code> is
-taken from the current locale. If Unicode (for example, <code>\N{}</code> or
code
-points of 0x100 or beyond) is being used, the case map used by <code>\l</code>,
-<code>\L</code>, <code>\u</code>, and <code>\U</code> is as defined by
Unicode. That means that
-case-mapping a single character can sometimes produce a sequence of
-several characters.
-Under <code>use locale</code><!-- /@w -->, <code>\F</code> produces the
same results as <code>\L</code>
-for all locales but a UTF-8 one, where it instead uses the Unicode
-definition.
-</p>
-<p>All systems use the virtual <code>"\n"</code> 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 <code>"\r"</code> as ASCII CR and
<code>"\n"</code> as ASCII LF. For example,
-on the ancient Macs (pre-MacOS X) of yesteryear, these used to be reversed,
-and on systems without a line terminator,
-printing <code>"\n"</code> might emit no actual data. In general,
use <code>"\n"</code> 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 (<code>"\015\012"</code> or
<code>"\cM\cJ"</code>) for line terminators,
-and although they often accept just <code>"\012"</code>, they seldom
tolerate just
-<code>"\015"</code>. If you get in the habit of using
<code>"\n"</code> for networking,
-you may be burned some day.
-</p>
-<p>For constructs that do interpolate, variables beginning with
"<code>$</code>"
-or "<code>@</code>" are interpolated. Subscripted variables such as
<code>$a[3]</code> or
-<code>$href->{key}[0]</code> are also interpolated, as are array and hash
slices.
-But method calls such as <code>$obj->meth</code> are not.
-</p>
-<p>Interpolating an array or slice interpolates the elements in order,
-separated by the value of <code>$"</code>, so is equivalent to
interpolating
-<code>join $", @array</code><!-- /@w -->.
"Punctuation" arrays such as <code>@*</code> are usually
-interpolated only if the name is enclosed in braces <code>@{*}</code>, but the
-arrays <code>@_</code>, <code>@+</code>, and <code>@-</code> are interpolated
even without braces.
-</p>
-<p>For double-quoted strings, the quoting from <code>\Q</code> is applied after
-interpolation and escapes are processed.
-</p>
-<pre class="verbatim"> "abc\Qfoo\tbar$s\Exyz"
-</pre>
-<p>is equivalent to
-</p>
-<pre class="verbatim"> "abc" . quotemeta("foo\tbar$s")
. "xyz"
-</pre>
-<p>For the pattern of regex operators (<code>qr//</code>, <code>m//</code> and
<code>s///</code>),
-the quoting from <code>\Q</code> is applied after interpolation is processed,
-but before escapes are processed. This allows the pattern to match
-literally (except for <code>$</code> and <code>@</code>). For example, the
following matches:
-</p>
-<pre class="verbatim"> '\s\t' =~ /\Q\s\t/
-</pre>
-<p>Because <code>$</code> or <code>@</code> trigger interpolation,
you’ll need to use something
-like <code>/address@hidden/</code> to match them literally.
-</p>
-<p>Patterns are subject to an additional level of interpretation as a
-regular expression. This is done as a second pass, after variables are
-interpolated, so that regular expressions may be incorporated into the
-pattern from the variables. If this is not what you want, use <code>\Q</code>
to
-interpolate a variable literally.
-</p>
-<p>Apart from the behavior described above, Perl does not expand
-multiple levels of interpolation. In particular, contrary to the
-expectations of shell programmers, back-quotes do <em>NOT</em> interpolate
-within double quotes, nor do single quotes impede evaluation of
-variables when used within double quotes.
-</p>
-<hr>
-<a name="perlop-Regexp-Quote_002dLike-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Quote_002dLike-Operators" accesskey="n"
rel="next">perlop Quote-Like Operators</a>, Previous: <a
href="#perlop-Quote-and-Quote_002dlike-Operators" accesskey="p"
rel="prev">perlop Quote and Quote-like Operators</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Regexp-Quote_002dLike-Operators"></a>
-<h4 class="subsection">48.2.30 Regexp Quote-Like Operators</h4>
-
-<p>Here are the quote-like operators that apply to pattern
-matching and related activities.
-</p>
-<dl compact="compact">
-<dt><code>qr/<em>STRING</em>/msixpodualn</code></dt>
-<dd><a name="perlop-qr_002fSTRING_002fmsixpodualn"></a>
-<p>This operator quotes (and possibly compiles) its <em>STRING</em> as a
regular
-expression. <em>STRING</em> is interpolated the same way as <em>PATTERN</em>
-in <code>m/<em>PATTERN</em>/</code>. If <code>"'"</code> is used as
the delimiter, no interpolation
-is done. Returns a Perl value which may be used instead of the
-corresponding <code>/<em>STRING</em>/msixpodualn</code> expression. The
returned value is a
-normalized version of the original pattern. It magically differs from
-a string containing the same characters: <code>ref(qr/x/)</code> returns
"Regexp";
-however, dereferencing it is not well defined (you currently get the
-normalized version of the original pattern, but this may change).
-</p>
-<p>For example,
-</p>
-<pre class="verbatim"> $rex = qr/my.STRING/is;
- print $rex; # prints (?si-xm:my.STRING)
- s/$rex/foo/;
-</pre>
-<p>is equivalent to
-</p>
-<pre class="verbatim"> s/my.STRING/foo/is;
-</pre>
-<p>The result may be used as a subpattern in a match:
-</p>
-<pre class="verbatim"> $re = qr/$pattern/;
- $string =~ /foo${re}bar/; # can be interpolated in other
- # patterns
- $string =~ $re; # or used standalone
- $string =~ /$re/; # or this way
-</pre>
-<p>Since Perl may compile the pattern at the moment of execution of the
<code>qr()</code>
-operator, using <code>qr()</code> may have speed advantages in some situations,
-notably if the result of <code>qr()</code> is used standalone:
-</p>
-<pre class="verbatim"> sub match {
- my $patterns = shift;
- my @compiled = map qr/$_/i, @$patterns;
- grep {
- my $success = 0;
- foreach my $pat (@compiled) {
- $success = 1, last if /$pat/;
- }
- $success;
- } @_;
- }
-</pre>
-<p>Precompilation of the pattern into an internal representation at
-the moment of <code>qr()</code> avoids the need to recompile the pattern every
-time a match <code>/$pat/</code> is attempted. (Perl has many other internal
-optimizations, but none would be triggered in the above example if
-we did not use <code>qr()</code> operator.)
-</p>
-<p>Options (specified by the following modifiers) are:
-</p>
-<pre class="verbatim"> m Treat string as multiple lines.
- s Treat string as single line. (Make . match a newline)
- i Do case-insensitive pattern matching.
- x Use extended regular expressions.
- p When matching preserve a copy of the matched string so
- that ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be
- defined (ignored starting in v5.20) as these are always
- defined starting in that relese
- o Compile pattern only once.
- a ASCII-restrict: Use ASCII for \d, \s, \w; specifying two
- a's further restricts things to that that no ASCII
- character will match a non-ASCII one under /i.
- l Use the current run-time locale's rules.
- u Use Unicode rules.
- d Use Unicode or native charset, as in 5.12 and earlier.
- n Non-capture mode. Don't let () fill in $1, $2, etc...
-</pre>
-<p>If a precompiled pattern is embedded in a larger pattern then the effect
-of <code>"msixpluadn"</code> will be propagated appropriately. The
effect that the
-<code>/o</code> modifier has is not propagated, being restricted to those
patterns
-explicitly using it.
-</p>
-<p>The last four modifiers listed above, added in Perl 5.14,
-control the character set rules, but <code>/a</code> is the only one you are
likely
-to want to specify explicitly; the other three are selected
-automatically by various pragmas.
-</p>
-<p>See <a href="#perlre-NAME">perlre NAME</a> for additional information on
valid syntax for <em>STRING</em>, and
-for a detailed look at the semantics of regular expressions. In
-particular, all modifiers except the largely obsolete <code>/o</code> are
further
-explained in <a href="#perlre-Modifiers">perlre Modifiers</a>.
<code>/o</code> is described in the next section.
-</p>
-</dd>
-<dt><code>m/<em>PATTERN</em>/msixpodualngc</code></dt>
-<dd><a name="perlop-m_002fPATTERN_002fmsixpodualngc"></a>
-</dd>
-<dt><code>/<em>PATTERN</em>/msixpodualngc</code></dt>
-<dd><a name="perlop-_002fPATTERN_002fmsixpodualngc"></a>
-<p>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 <code>=~</code> or <code>!~</code> operator, the <code>$_</code>
string is searched. (The
-string specified with <code>=~</code> need not be an lvalue–it may be the
-result of an expression evaluation, but remember the <code>=~</code> binds
-rather tightly.) See also <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-<p>Options are as described in <code>qr//</code> above; in addition, the
following match
-process modifiers are available:
-</p>
-<pre class="verbatim"> g Match globally, i.e., find all occurrences.
- c Do not reset search position on a failed match when /g is
- in effect.
-</pre>
-<p>If <code>"/"</code> is the delimiter then the initial
<code>m</code> is optional. With the <code>m</code>
-you can use any pair of non-whitespace (ASCII) characters
-as delimiters. This is particularly useful for matching path names
-that contain <code>"/"</code>, to avoid LTS (leaning toothpick
syndrome). If <code>"?"</code> is
-the delimiter, then a match-only-once rule applies,
-described in <code>m?<em>PATTERN</em>?</code> below. If
<code>"'"</code> (single quote) is the delimiter,
-no interpolation is performed on the <em>PATTERN</em>.
-When using a delimiter character valid in an identifier, whitespace is required
-after the <code>m</code>.
-</p>
-<p><em>PATTERN</em> 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 <code>$(</code>,
<code>$)</code>, and
-<code>$|</code> are not interpolated because they look like end-of-string
tests.)
-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 <code>/o</code> (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 <code>/o</code> are one
of:
-</p>
-<ol>
-<li> 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 <code>/o</code> constitutes a promise that you
won’t
-change the variables in the pattern. If you do change them, Perl won’t
-even notice.)
-
-</li><li> 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 <code>/o</code>.)
-
-</li><li> If the pattern contains embedded code, such as
-
-<pre class="verbatim"> use re 'eval';
- $code = 'foo(?{ $x })';
- /$code/
-</pre>
-<p>then perl will recompile each time, even though the pattern string
hasn’t
-changed, to ensure that the current value of <code>$x</code> is seen each time.
-Use <code>/o</code> if you want to avoid this.
-</p>
-</li></ol>
-
-<p>The bottom line is that using <code>/o</code> is almost never a good idea.
-</p>
-</dd>
-<dt>The empty pattern <code>//</code></dt>
-<dd><a name="perlop-The-empty-pattern-_002f_002f"></a>
-<p>If the <em>PATTERN</em> evaluates to the empty string, the last
-<em>successfully</em> matched regular expression is used instead. In this
-case, only the <code>g</code> and <code>c</code> 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).
-</p>
-<p>Note that it’s possible to confuse Perl into thinking <code>//</code>
(the empty
-regex) is really <code>//</code> (the defined-or operator). Perl is usually
pretty
-good about this, but some pathological cases might trigger this, such as
-<code>$x///</code> (is that <code>($x) / (//)</code><!-- /@w --> or
<code>$x // /</code><!-- /@w -->?) and
<code>print $fh //</code><!-- /@w -->
-(<code>print $fh(//</code><!-- /@w --> or
<code>print($fh //</code><!-- /@w -->?). In all of these examples, Perl
-will assume you meant defined-or. If you meant the empty regex, just
-use parentheses or spaces to disambiguate, or even prefix the empty
-regex with an <code>m</code> (so <code>//</code> becomes <code>m//</code>).
-</p>
-</dd>
-<dt>Matching in list context</dt>
-<dd><a name="perlop-Matching-in-list-context"></a>
-<p>If the <code>/g</code> option is not used, <code>m//</code> in list context
returns a
-list consisting of the subexpressions matched by the parentheses in the
-pattern, that is, (<code>$1</code>, <code>$2</code>, <code>$3</code>...)
(Note that here <code>$1</code> etc. are
-also set). When there are no parentheses in the pattern, the return
-value is the list <code>(1)</code> for success.
-With or without parentheses, an empty list is returned upon failure.
-</p>
-<p>Examples:
-</p>
-<pre class="verbatim"> open(TTY, "+</dev/tty")
- || die "can't access /dev/tty: $!";
-
- <TTY> =~ /^y/i && foo(); # do foo if desired
-
- if (/Version: *([0-9.]*)/) { $version = $1; }
-
- next if m#^/usr/spool/uucp#;
-
- # poor man's grep
- $arg = shift;
- while (<>) {
- print if /$arg/o; # compile only once (no longer needed!)
- }
-
- if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
-</pre>
-<p>This last example splits <code>$foo</code> into the first two words and the
-remainder of the line, and assigns those three fields to <code>$F1</code>,
<code>$F2</code>, and
-<code>$Etc</code>. The conditional is true if any variables were assigned;
that is,
-if the pattern matched.
-</p>
-<p>The <code>/g</code> 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
-substrings matched by any capturing parentheses in the regular
-expression. If there are no parentheses, it returns a list of all
-the matched strings, as if there were parentheses around the whole
-pattern.
-</p>
-<p>In scalar context, each execution of <code>m//g</code> 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
<code>pos()</code>
-function; see <a href="#perlfunc-pos">perlfunc pos</a>. A failed match
normally resets the
-search position to the beginning of the string, but you can avoid that
-by adding the <code>/c</code> modifier (for example, <code>m//gc</code>).
Modifying the target
-string also resets the search position.
-</p>
-</dd>
-<dt><code>\G <em>assertion</em></code></dt>
-<dd><a name="perlop-_005cG-assertion"></a>
-<p>You can intermix <code>m//g</code> matches with <code>m/\G.../g</code>,
where <code>\G</code> is a
-zero-width assertion that matches the exact position where the
-previous <code>m//g</code>, if any, left off. Without the <code>/g</code>
modifier, the
-<code>\G</code> assertion still anchors at <code>pos()</code> as it was at the
start of
-the operation (see <a href="#perlfunc-pos">perlfunc pos</a>), but the match is
of course only
-attempted once. Using <code>\G</code> without <code>/g</code> on a target
string that has
-not previously had a <code>/g</code> match applied to it is the same as using
-the <code>\A</code> assertion to match the beginning of the string. Note also
-that, currently, <code>\G</code> is only properly supported when anchored at
the
-very beginning of the pattern.
-</p>
-<p>Examples:
-</p>
-<pre class="verbatim"> # list context
- ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g);
-
- # scalar context
- local $/ = "";
- while ($paragraph = <>) {
- while ($paragraph =~ /\p{Ll}['")]*[.!?]+['")]*\s/g) {
- $sentences++;
- }
- }
- say $sentences;
-</pre>
-<p>Here’s another way to check for sentences in a paragraph:
-</p>
-<pre class="verbatim"> my $sentence_rx = qr{
- (?: (?<= ^ ) | (?<= \s ) ) # after start-of-string or
- # whitespace
- \p{Lu} # capital letter
- .*? # a bunch of anything
- (?<= \S ) # that ends in non-
- # whitespace
- (?<! \b [DMS]r ) # but isn't a common abbr.
- (?<! \b Mrs )
- (?<! \b Sra )
- (?<! \b St )
- [.?!] # followed by a sentence
- # ender
- (?= $ | \s ) # in front of end-of-string
- # or whitespace
- }sx;
- local $/ = "";
- while (my $paragraph = <>) {
- say "NEW PARAGRAPH";
- my $count = 0;
- while ($paragraph =~ /($sentence_rx)/g) {
- printf "\tgot sentence %d: <%s>\n", ++$count, $1;
- }
- }
-</pre>
-<p>Here’s how to use <code>m//gc</code> with <code>\G</code>:
-</p>
-<pre class="verbatim"> $_ = "ppooqppqq";
- while ($i++ < 2) {
- print "1: '";
- print $1 while /(o)/gc; print "', pos=", pos, "\n";
- print "2: '";
- print $1 if /\G(q)/gc; print "', pos=", pos, "\n";
- print "3: '";
- print $1 while /(p)/gc; print "', pos=", pos, "\n";
- }
- print "Final: '$1', pos=",pos,"\n" if /\G(.)/;
-</pre>
-<p>The last example should print:
-</p>
-<pre class="verbatim"> 1: 'oo', pos=4
- 2: 'q', pos=5
- 3: 'pp', pos=7
- 1: '', pos=7
- 2: 'q', pos=8
- 3: '', pos=8
- Final: 'q', pos=8
-</pre>
-<p>Notice that the final match matched <code>q</code> instead of
<code>p</code>, which a match
-without the <code>\G</code> anchor would have done. Also note that the final
match
-did not update <code>pos</code>. <code>pos</code> is only updated on a
<code>/g</code> match. If the
-final match did indeed match <code>p</code>, it’s a good bet that
you’re running a
-very old (pre-5.6.0) version of Perl.
-</p>
-<p>A useful idiom for <code>lex</code>-like scanners is
<code>/\G.../gc</code>. You can
-combine several regexps like this to process a string part-by-part,
-doing different actions depending on which regexp matched. Each
-regexp tries to match where the previous one leaves off.
-</p>
-<pre class="verbatim"> $_ = <<'EOL';
- $url = URI::URL->new( "http://example.com/" );
- die if $url eq "xXx";
- EOL
-
- LOOP: {
- print(" digits"), redo LOOP if /\G\d+\b[,.;]?\s*/gc;
- print(" lowercase"), redo LOOP
- if /\G\p{Ll}+\b[,.;]?\s*/gc;
- print(" UPPERCASE"), redo LOOP
- if /\G\p{Lu}+\b[,.;]?\s*/gc;
- print(" Capitalized"), redo LOOP
- if /\G\p{Lu}\p{Ll}+\b[,.;]?\s*/gc;
- print(" 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";
- }
-</pre>
-<p>Here is the output (split into several lines):
-</p>
-<pre class="verbatim"> 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!
-</pre>
-</dd>
-<dt><code>m?<em>PATTERN</em>?msixpodualngc</code></dt>
-<dd><a name="perlop-m_003fPATTERN_003fmsixpodualngc"></a>
-</dd>
-<dt><code>?<em>PATTERN</em>?msixpodualngc</code></dt>
-<dd><a name="perlop-_003fPATTERN_003fmsixpodualngc"></a>
-<p>This is just like the <code>m/<em>PATTERN</em>/</code> search, except that
it matches
-only once between calls to the <code>reset()</code> 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 <code>m??</code>
-patterns local to the current package are reset.
-</p>
-<pre class="verbatim"> while (<>) {
- if (m?^$?) {
- # blank line between header and body
- }
- } continue {
- reset if eof; # clear m?? status for next file
- }
-</pre>
-<p>Another example switched the first "latin1" encoding it finds
-to "utf8" in a pod file:
-</p>
-<pre class="verbatim"> s//utf8/ if m? ^ =encoding \h+ \K latin1 ?x;
-</pre>
-<p>The match-once behavior is controlled by the match delimiter being
-<code>?</code>; with any other delimiter this is the normal <code>m//</code>
operator.
-</p>
-<p>In the past, the leading <code>m</code> in <code>m?<em>PATTERN</em>?</code>
was optional, but omitting it
-would produce a deprecation warning. As of v5.22.0, omitting it produces a
-syntax error. If you encounter this construct in older code, you can just add
-<code>m</code>.
-</p>
-</dd>
-<dt><code>s/<em>PATTERN</em>/<em>REPLACEMENT</em>/msixpodualngcer</code></dt>
-<dd><a name="perlop-s_002fPATTERN_002fREPLACEMENT_002fmsixpodualngcer"></a>
-<p>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).
-</p>
-<p>If the <code>/r</code> (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
-<code>/r</code> is used. The copy will always be a plain string, even if the
-input is an object or a tied variable.
-</p>
-<p>If no string is specified via the <code>=~</code> or <code>!~</code>
operator, the <code>$_</code>
-variable is searched and modified. Unless the <code>/r</code> 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.
-</p>
-<p>If the delimiter chosen is a single quote, no interpolation is
-done on either the <em>PATTERN</em> or the <em>REPLACEMENT</em>. Otherwise,
if the
-<em>PATTERN</em> contains a <code>$</code> that looks like a variable rather
than an
-end-of-string test, the variable will be interpolated into the pattern
-at run-time. If you want the pattern compiled only once the first time
-the variable is interpolated, use the <code>/o</code> option. If the pattern
-evaluates to the empty string, the last successfully executed regular
-expression is used instead. See <a href="#perlre-NAME">perlre NAME</a> for
further explanation on these.
-</p>
-<p>Options are as with <code>m//</code> with the addition of the following
replacement
-specific options:
-</p>
-<pre class="verbatim"> e Evaluate the right side as an expression.
- ee Evaluate the right side as a string then eval the
- result.
- r Return substitution and leave the original string
- untouched.
-</pre>
-<p>Any non-whitespace delimiter may replace the slashes. Add space after
-the <code>s</code> when using a character allowed in identifiers. If single
quotes
-are used, no interpretation is done on the replacement string (the
<code>/e</code>
-modifier overrides this, however). Note that Perl treats backticks
-as normal delimiters; the replacement text is not evaluated as a command.
-If the <em>PATTERN</em> is delimited by bracketing quotes, the
<em>REPLACEMENT</em> has
-its own pair of quotes, which may or may not be bracketing quotes, for example,
-<code>s(foo)(bar)</code> or <code>s<foo>/bar/</code>. A <code>/e</code>
will cause the
-replacement portion to be treated as a full-fledged Perl expression
-and evaluated right then and there. It is, however, syntax checked at
-compile-time. A second <code>e</code> modifier will cause the replacement
portion
-to be <code>eval</code>ed before being run as a Perl expression.
-</p>
-<p>Examples:
-</p>
-<pre class="verbatim"> s/\bgreen\b/mauve/g; # don't change
wintergreen
-
- $path =~ s|/usr/bin|/usr/local/bin|;
-
- s/Login: $foo/Login: $bar/; # run-time pattern
-
- ($foo = $bar) =~ s/this/that/; # copy first, then
- # change
- ($foo = "$bar") =~ s/this/that/; # convert to string,
- # copy, then change
- $foo = $bar =~ s/this/that/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-cnt
-
- $_ = 'abc123xyz';
- s/\d+/$&*2/e; # yields 'abc246xyz'
- s/\d+/sprintf("%5d",$&)/e; # yields 'abc 246xyz'
- s/\w/$& x 2/eg; # yields 'aabbcc 224466xxyyzz'
-
- s/%(.)/$percent{$1}/g; # change percent escapes; no /e
- s/%(.)/$percent{$1} || $&/ge; # expr now, so /e
- s/^=(\w+)/pod($1)/ge; # use function call
-
- $_ = 'abc123xyz';
- $x = s/abc/def/r; # $x is 'def123xyz' and
- # $_ remains 'abc123xyz'.
-
- # expand variables in $_, but dynamics only, using
- # symbolic dereferencing
- s/\$(\w+)/${$1}/g;
-
- # 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
- s/(\$\w+)/$1/eeg;
-
- # Delete (most) C comments.
- $program =~ s {
- /\* # Match the opening delimiter.
- .*? # Match a minimal number of characters.
- \*/ # Match the closing delimiter.
- } []gsx;
-
- s/^\s*(.*?)\s*$/$1/; # trim whitespace in $_,
- # expensively
-
- for ($variable) { # trim whitespace in $variable,
- # cheap
- s/^\s+//;
- s/\s+$//;
- }
-
- s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields
-</pre>
-<p>Note the use of <code>$</code> instead of <code>\</code> in the last
example. Unlike
-<strong>sed</strong>, we use the \<<em>digit</em>> form only in the left
hand side.
-Anywhere else it’s $<<em>digit</em>>.
-</p>
-<p>Occasionally, you can’t use just a <code>/g</code> to get all the
changes
-to occur that you might want. Here are two common cases:
-</p>
-<pre class="verbatim"> # put commas in the right places in an integer
- 1 while s/(\d)(\d\d\d)(?!\d)/$1,$2/g;
-
- # expand tabs to 8-column spacing
- 1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
-</pre>
-</dd>
-</dl>
-
-<hr>
-<a name="perlop-Quote_002dLike-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Gory-details-of-parsing-quoted-constructs"
accesskey="n" rel="next">perlop Gory details of parsing quoted constructs</a>,
Previous: <a href="#perlop-Regexp-Quote_002dLike-Operators" accesskey="p"
rel="prev">perlop Regexp Quote-Like Operators</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Quote_002dLike-Operators"></a>
-<h4 class="subsection">48.2.31 Quote-Like Operators</h4>
-
-<dl compact="compact">
-<dt><code>q/<em>STRING</em>/</code></dt>
-<dd><a name="perlop-q_002fSTRING_002f"></a>
-</dd>
-<dt><code>'<em>STRING</em>'</code></dt>
-<dd><a name="perlop-_0027STRING_0027"></a>
-<p>A single-quoted, literal string. A backslash represents a backslash
-unless followed by the delimiter or another backslash, in which case
-the delimiter or backslash is interpolated.
-</p>
-<pre class="verbatim"> $foo = q!I said, "You said, 'She said
it.'"!;
- $bar = q('This is it.');
- $baz = '\n'; # a two-character string
-</pre>
-</dd>
-<dt><code>qq/<em>STRING</em>/</code></dt>
-<dd><a name="perlop-qq_002fSTRING_002f"></a>
-</dd>
-<dt>"<em>STRING</em>"</dt>
-<dd><a name="perlop-_0022STRING_0022"></a>
-<p>A double-quoted, interpolated string.
-</p>
-<pre class="verbatim"> $_ .= qq
- (*** The previous line contains the naughty word "$1".\n)
- if /\b(tcl|java|python)\b/i; # :-)
- $baz = "\n"; # a one-character string
-</pre>
-</dd>
-<dt><code>qx/<em>STRING</em>/</code></dt>
-<dd><a name="perlop-qx_002fSTRING_002f"></a>
-</dd>
-<dt><code>`<em>STRING</em>`</code></dt>
-<dd><a name="perlop-_0060STRING_0060"></a>
-<p>A string which is (possibly) interpolated and then executed as a
-system command with <samp>/bin/sh</samp> or its equivalent. Shell wildcards,
-pipes, and redirections will be honored. The collected standard
-output of the command is returned; standard error is unaffected. In
-scalar context, it comes back as a single (potentially multi-line)
-string, or <code>undef</code> if the command failed. In list context, returns
a
-list of lines (however you’ve defined lines with <code>$/</code> or
-<code>$INPUT_RECORD_SEPARATOR</code>), or an empty list if the command failed.
-</p>
-<p>Because backticks do not affect standard error, use shell file descriptor
-syntax (assuming the shell supports this) if you care to address this.
-To capture a command’s STDERR and STDOUT together:
-</p>
-<pre class="verbatim"> $output = `cmd 2>&1`;
-</pre>
-<p>To capture a command’s STDOUT but discard its STDERR:
-</p>
-<pre class="verbatim"> $output = `cmd 2>/dev/null`;
-</pre>
-<p>To capture a command’s STDERR but discard its STDOUT (ordering is
-important here):
-</p>
-<pre class="verbatim"> $output = `cmd 2>&1 1>/dev/null`;
-</pre>
-<p>To exchange a command’s STDOUT and STDERR in order to capture the
STDERR
-but leave its STDOUT to come out the old STDERR:
-</p>
-<pre class="verbatim"> $output = `cmd 3>&1 1>&2 2>&3
3>&-`;
-</pre>
-<p>To read both a command’s STDOUT and its STDERR separately, it’s
easiest
-to redirect them separately to files, and then read from those files
-when the program is done:
-</p>
-<pre class="verbatim"> system("program args 1>program.stdout
2>program.stderr");
-</pre>
-<p>The STDIN filehandle used by the command is inherited from Perl’s
STDIN.
-For example:
-</p>
-<pre class="verbatim"> open(SPLAT, "stuff") || die "can't
open stuff: $!";
- open(STDIN, "<&SPLAT") || die "can't dupe SPLAT:
$!";
- print STDOUT `sort`;
-</pre>
-<p>will print the sorted contents of the file named
<samp>"stuff"</samp>.
-</p>
-<p>Using single-quote as a delimiter protects the command from Perl’s
-double-quote interpolation, passing it on to the shell instead:
-</p>
-<pre class="verbatim"> $perl_info = qx(ps $$); # that's Perl's
$$
- $shell_info = qx'ps $$'; # that's the new shell's $$
-</pre>
-<p>How that string gets evaluated is entirely subject to the command
-interpreter on your system. On most platforms, you will have to protect
-shell metacharacters if you want them treated literally. This is in
-practice difficult to do, as it’s unclear how to escape which characters.
-See <a href="#perlsec-NAME">perlsec NAME</a> for a clean and safe example of a
manual <code>fork()</code> and <code>exec()</code>
-to emulate backticks safely.
-</p>
-<p>On some platforms (notably DOS-like ones), the shell may not be
-capable of dealing with multiline commands, so putting newlines in
-the string may not get you what you want. You may be able to evaluate
-multiple commands in a single line by separating them with the command
-separator character, if your shell supports that (for example, <code>;</code>
on
-many Unix shells and <code>&</code> on the Windows NT <code>cmd</code>
shell).
-</p>
-<p>Perl will attempt to flush all files opened for
-output before starting the child process, but this may not be supported
-on some platforms (see <a href="#perlport-NAME">perlport NAME</a>). To be
safe, you may need to set
-<code>$|</code> (<code>$AUTOFLUSH</code> in <code><a
href="English.html#Top">(English)</a></code>) or call the
<code>autoflush()</code> method of
-<code><a href="IO-Handle.html#Top">(IO-Handle)</a></code> on any open handles.
-</p>
-<p>Beware that some command shells may place restrictions on the length
-of the command line. You must ensure your strings don’t exceed this
-limit after any necessary interpolations. See the platform-specific
-release notes for more details about your particular environment.
-</p>
-<p>Using this operator can lead to programs that are difficult to port,
-because the shell commands called vary between systems, and may in
-fact not be present at all. As one example, the <code>type</code> command
under
-the POSIX shell is very different from the <code>type</code> command under DOS.
-That doesn’t mean you should go out of your way to avoid backticks
-when they’re the right way to get something done. Perl was made to be
-a glue language, and one of the things it glues together is commands.
-Just understand what you’re getting yourself into.
-</p>
-<p>See <a href="#perlop-I_002fO-Operators">I/O Operators</a> for more
discussion.
-</p>
-</dd>
-<dt><code>qw/<em>STRING</em>/</code></dt>
-<dd><a name="perlop-qw_002fSTRING_002f"></a>
-<p>Evaluates to a list of the words extracted out of <em>STRING</em>, using
embedded
-whitespace as the word delimiters. It can be understood as being roughly
-equivalent to:
-</p>
-<pre class="verbatim"> split(" ", q/STRING/);
-</pre>
-<p>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
-this expression:
-</p>
-<pre class="verbatim"> qw(foo bar baz)
-</pre>
-<p>is semantically equivalent to the list:
-</p>
-<pre class="verbatim"> "foo", "bar", "baz"
-</pre>
-<p>Some frequently seen examples:
-</p>
-<pre class="verbatim"> use POSIX qw( setlocale localeconv )
- @EXPORT = qw( foo bar baz );
-</pre>
-<p>A common mistake is to try to separate the words with commas or to
-put comments into a multi-line <code>qw</code>-string. For this reason, the
-<code>use warnings</code><!-- /@w --> pragma and the <strong>-w</strong>
switch (that is, the <code>$^W</code> variable)
-produces warnings if the <em>STRING</em> contains the
<code>","</code> or the <code>"#"</code> character.
-</p>
-</dd>
-<dt><code>tr/<em>SEARCHLIST</em>/<em>REPLACEMENTLIST</em>/cdsr</code></dt>
-<dd><a name="perlop-tr_002fSEARCHLIST_002fREPLACEMENTLIST_002fcdsr"></a>
-</dd>
-<dt><code>y/<em>SEARCHLIST</em>/<em>REPLACEMENTLIST</em>/cdsr</code></dt>
-<dd><a name="perlop-y_002fSEARCHLIST_002fREPLACEMENTLIST_002fcdsr"></a>
-<p>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 <code>=~</code> or <code>!~</code> operator, the
<code>$_</code> string is transliterated.
-</p>
-<p>If the <code>/r</code> (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.
-</p>
-<p>Unless the <code>/r</code> option is used, the string specified with
<code>=~</code> must be a
-scalar variable, an array element, a hash element, or an assignment to one
-of those; in other words, an lvalue.
-</p>
-<p>A character range may be specified with a hyphen, so
<code>tr/A-J/0-9/</code>
-does the same replacement as <code>tr/ACEGIBDFHJ/0246813579/</code>.
-For <strong>sed</strong> devotees, <code>y</code> is provided as a synonym for
<code>tr</code>. If the
-<em>SEARCHLIST</em> is delimited by bracketing quotes, the
<em>REPLACEMENTLIST</em> has
-its own pair of quotes, which may or may not be bracketing quotes;
-for example, <code>tr[aeiouy][yuoiea]</code> or <code>tr(+\-*/)/ABCD/</code>.
-</p>
-<p>Characters may be literals or any of the escape sequences accepted in
-double-quoted strings. But there is no interpolation, so
<code>"$"</code> and
-<code>"@"</code> are treated as literals. A hyphen at the beginning
or end, or
-preceded by a backslash is considered a literal. Escape sequence
-details are in <a href="#perlop-Quote-and-Quote_002dlike-Operators">the table
near the beginning of this section</a>. It is a bug in Perl v5.22 that
something like
-</p>
-<pre class="verbatim"> tr/\N{U+20}-\N{U+7E}foobar//
-</pre>
-<p>does not treat that range as fully Unicode.
-</p>
-<p>Note that <code>tr</code> does <strong>not</strong> do regular expression
character classes such as
-<code>\d</code> or <code>\pL</code>. The <code>tr</code> operator is not
equivalent to the <code><a href="http://man.he.net/man1/tr";>tr(1)</a></code>
-utility. If you want to map strings between lower/upper cases, see
-<a href="#perlfunc-lc">perlfunc lc</a> and <a href="#perlfunc-uc">perlfunc
uc</a>, and in general consider using the <code>s</code>
-operator if you need regular expressions. The <code>\U</code>,
<code>\u</code>, <code>\L</code>, and
-<code>\l</code> string-interpolation escapes on the right side of a
substitution
-operator will perform correct case-mappings, but <code>tr[a-z][A-Z]</code>
will not
-(except sometimes on legacy 7-bit data).
-</p>
-<p>Note also that the whole range idea is rather unportable between
-character sets–and even within character sets they may cause results
-you probably didn’t expect. A sound principle is to use only ranges
-that begin from and end at either alphabets of equal case (a-e, A-E),
-or digits (0-4). Anything else is unsafe. If in doubt, spell out the
-character sets in full.
-</p>
-<p>Options:
-</p>
-<pre class="verbatim"> 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.
-</pre>
-<p>If the <code>/c</code> modifier is specified, the <em>SEARCHLIST</em>
character set
-is complemented. If the <code>/d</code> modifier is specified, any characters
-specified by <em>SEARCHLIST</em> not found in <em>REPLACEMENTLIST</em> are
deleted.
-(Note that this is slightly more flexible than the behavior of some
-<strong>tr</strong> programs, which delete anything they find in the
<em>SEARCHLIST</em>,
-period.) If the <code>/s</code> modifier is specified, sequences of characters
-that were transliterated to the same character are squashed down
-to a single instance of the character.
-</p>
-<p>If the <code>/d</code> modifier is used, the <em>REPLACEMENTLIST</em> is
always interpreted
-exactly as specified. Otherwise, if the <em>REPLACEMENTLIST</em> is shorter
-than the <em>SEARCHLIST</em>, the final character is replicated till it is long
-enough. If the <em>REPLACEMENTLIST</em> is empty, the <em>SEARCHLIST</em> is
replicated.
-This latter is useful for counting characters in a class or for
-squashing character sequences in a class.
-</p>
-<p>Examples:
-</p>
-<pre class="verbatim"> $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower
case ASCII
-
- $cnt = tr/*/*/; # count the stars in $_
-
- $cnt = $sky =~ tr/*/*/; # count the stars in $sky
-
- $cnt = tr/0-9//; # count the digits in $_
-
- 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]; # wickedly delete 8th bit
-</pre>
-<p>If multiple transliterations are given for a character, only the
-first one is used:
-</p>
-<pre class="verbatim"> tr/AAA/XYZ/
-</pre>
-<p>will transliterate any A to X.
-</p>
-<p>Because the transliteration table is built at compile time, neither
-the <em>SEARCHLIST</em> nor the <em>REPLACEMENTLIST</em> are subjected to
double quote
-interpolation. That means that if you want to use variables, you
-must use an <code>eval()</code>:
-</p>
-<pre class="verbatim"> eval "tr/$oldlist/$newlist/";
- die $@ if $@;
-
- eval "tr/$oldlist/$newlist/, 1" or die $@;
-</pre>
-</dd>
-<dt><code><<<em>EOF</em></code> ></dt>
-<dd><a name="perlop-_003c_003cEOF-_003e"></a>
-<p>A line-oriented form of quoting is based on the shell
"here-document"
-syntax. Following a <code><<</code> you specify a string to terminate
-the quoted material, and all lines following the current line down to
-the terminating string are the value of the item.
-</p>
-<p>The terminating string may be either an identifier (a word), or some
-quoted text. An unquoted identifier works like double quotes.
-There may not be a space between the <code><<</code> and the identifier,
-unless the identifier is explicitly quoted. (If you put a space it
-will be treated as a null identifier, which is valid, and matches the
-first empty line.) The terminating string must appear by itself
-(unquoted and with no surrounding whitespace) on the terminating line.
-</p>
-<p>If the terminating string is quoted, the type of quotes used determine
-the treatment of the text.
-</p>
-<dl compact="compact">
-<dt>Double Quotes</dt>
-<dd><a name="perlop-Double-Quotes"></a>
-<p>Double quotes indicate that the text will be interpolated using exactly
-the same rules as normal double quoted strings.
-</p>
-<pre class="verbatim"> print <<EOF;
- The price is $Price.
- EOF
-
- print << "EOF"; # same as above
- The price is $Price.
- EOF
-</pre>
-</dd>
-<dt>Single Quotes</dt>
-<dd><a name="perlop-Single-Quotes"></a>
-<p>Single quotes indicate the text is to be treated literally with no
-interpolation of its content. This is similar to single quoted
-strings except that backslashes have no special meaning, with <code>\\</code>
-being treated as two backslashes and not one as they would in every
-other quoting construct.
-</p>
-<p>Just as in the shell, a backslashed bareword following the
<code><<</code>
-means the same thing as a single-quoted string does:
-</p>
-<pre class="verbatim"> $cost = <<'VISTA'; # hasta la ...
- That'll be $10 please, ma'am.
- VISTA
-
- $cost = <<\VISTA; # Same thing!
- That'll be $10 please, ma'am.
- VISTA
-</pre>
-<p>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.
-</p>
-</dd>
-<dt>Backticks</dt>
-<dd><a name="perlop-Backticks"></a>
-<p>The content of the here doc is treated just as it would be if the
-string were embedded in backticks. Thus the content is interpolated
-as though it were double quoted and then executed via the shell, with
-the results of the execution returned.
-</p>
-<pre class="verbatim"> print << `EOC`; # execute command and get
results
- echo hi there
- EOC
-</pre>
-</dd>
-</dl>
-
-<p>It is possible to stack multiple here-docs in a row:
-</p>
-<pre class="verbatim"> print <<"foo",
<<"bar"; # you can stack them
- I said foo.
- foo
- I said bar.
- bar
-
- myfunc(<< "THIS", 23, <<'THAT');
- Here's a line
- or two.
- THIS
- and here's another.
- THAT
-</pre>
-<p>Just don’t forget that you have to put a semicolon on the end
-to finish the statement, as Perl doesn’t know you’re not going to
-try to do this:
-</p>
-<pre class="verbatim"> print <<ABC
- 179231
- ABC
- + 20;
-</pre>
-<p>If you want to remove the line terminator from your here-docs,
-use <code>chomp()</code>.
-</p>
-<pre class="verbatim"> chomp($string = <<'END');
- This is a string.
- END
-</pre>
-<p>If you want your here-docs to be indented with the rest of the code,
-you’ll need to remove leading whitespace from each line manually:
-</p>
-<pre class="verbatim"> ($quote = <<'FINIS') =~ s/^\s+//gm;
- The Road goes ever on and on,
- down from the door where it began.
- FINIS
-</pre>
-<p>If you use a here-doc within a delimited construct, such as in
<code>s///eg</code>,
-the quoted material must still come on the line following the
-<code><<FOO</code> marker, which means it may be inside the delimited
-construct:
-</p>
-<pre class="verbatim"> s/this/<<E . 'that'
- the other
- E
- . 'more '/eg;
-</pre>
-<p>It works this way as of Perl 5.18. Historically, it was inconsistent, and
-you would have to write
-</p>
-<pre class="verbatim"> s/this/<<E . 'that'
- . 'more '/eg;
- the other
- E
-</pre>
-<p>outside of string evals.
-</p>
-<p>Additionally, quoting rules for the end-of-string identifier are
-unrelated to Perl’s quoting rules. <code>q()</code>, <code>qq()</code>,
and the like are not
-supported in place of <code>''</code> and <code>""</code>, and the
only interpolation is for
-backslashing the quoting character:
-</p>
-<pre class="verbatim"> print << "abc\"def";
- testing...
- abc"def
-</pre>
-<p>Finally, quoted strings cannot span multiple lines. The general rule is
-that the identifier must be a string literal. Stick with that, and you
-should be safe.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlop-Gory-details-of-parsing-quoted-constructs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-I_002fO-Operators" accesskey="n" rel="next">perlop I/O
Operators</a>, Previous: <a href="#perlop-Quote_002dLike-Operators"
accesskey="p" rel="prev">perlop Quote-Like Operators</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Gory-details-of-parsing-quoted-constructs"></a>
-<h4 class="subsection">48.2.32 Gory details of parsing quoted constructs</h4>
-
-<p>When presented with something that might have several different
-interpretations, Perl uses the <strong>DWIM</strong> (that’s "Do
What I Mean")
-principle to pick the most probable interpretation. This strategy
-is so successful that Perl programmers often do not suspect the
-ambivalence of what they write. But from time to time, Perl’s
-notions differ substantially from what the author honestly meant.
-</p>
-<p>This section hopes to clarify how Perl handles quoted constructs.
-Although the most common reason to learn this is to unravel labyrinthine
-regular expressions, because the initial steps of parsing are the
-same for all quoting operators, they are all discussed together.
-</p>
-<p>The most important Perl parsing rule is the first one discussed
-below: when processing a quoted construct, Perl first finds the end
-of that construct, then interprets its contents. If you understand
-this rule, you may skip the rest of this section on the first
-reading. The other rules are likely to contradict the user’s
-expectations much less frequently than this first one.
-</p>
-<p>Some passes discussed below are performed concurrently, but because
-their results are the same, we consider them individually. For different
-quoting constructs, Perl performs different numbers of passes, from
-one to four, but these passes are always performed in the same order.
-</p>
-<dl compact="compact">
-<dt>Finding the end</dt>
-<dd><a name="perlop-Finding-the-end"></a>
-<p>The first pass is finding the end of the quoted construct. This results
-in saving to a safe location a copy of the text (between the starting
-and ending delimiters), normalized as necessary to avoid needing to know
-what the original delimiters were.
-</p>
-<p>If the construct is a here-doc, the ending delimiter is a line
-that has a terminating string as the content. Therefore
<code><<EOF</code> is
-terminated by <code>EOF</code> immediately followed by
<code>"\n"</code> and starting
-from the first column of the terminating line.
-When searching for the terminating line of a here-doc, nothing
-is skipped. In other words, lines after the here-doc syntax
-are compared with the terminating string line by line.
-</p>
-<p>For the constructs except here-docs, single characters are used as starting
-and ending delimiters. If the starting delimiter is an opening punctuation
-(that is <code>(</code>, <code>[</code>, <code>{</code>, or
<code><</code>), the ending delimiter is the
-corresponding closing punctuation (that is <code>)</code>, <code>]</code>,
<code>}</code>, or <code>></code>).
-If the starting delimiter is an unpaired character like <code>/</code> or a
closing
-punctuation, the ending delimiter is the same as the starting delimiter.
-Therefore a <code>/</code> terminates a <code>qq//</code> construct, while a
<code>]</code> terminates
-both <code>qq[]</code> and <code>qq]]</code> constructs.
-</p>
-<p>When searching for single-character delimiters, escaped delimiters
-and <code>\\</code> are skipped. For example, while searching for terminating
<code>/</code>,
-combinations of <code>\\</code> and <code>\/</code> are skipped. If the
delimiters are
-bracketing, nested pairs are also skipped. For example, while searching
-for a closing <code>]</code> paired with the opening <code>[</code>,
combinations of <code>\\</code>, <code>\]</code>,
-and <code>\[</code> are all skipped, and nested <code>[</code> and
<code>]</code> are skipped as well.
-However, when backslashes are used as the delimiters (like <code>qq\\</code>
and
-<code>tr\\\</code>), nothing is skipped.
-During the search for the end, backslashes that escape delimiters or
-other backslashes are removed (exactly speaking, they are not copied to the
-safe location).
-</p>
-<p>For constructs with three-part delimiters (<code>s///</code>,
<code>y///</code>, and
-<code>tr///</code>), the search is repeated once more.
-If the first delimiter is not an opening punctuation, the three delimiters must
-be the same, such as <code>s!!!</code> and <code>tr)))</code>,
-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 punctuation (that is
<code>()</code>,
-<code>[]</code>, <code>{}</code>, or <code><></code>), the right part
needs another pair of
-delimiters such as <code>s(){}</code> and <code>tr[]//</code>. In these
cases, whitespace
-and comments are allowed between the two parts, although the comment must
follow
-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.
-</p>
-<p>During this search no attention is paid to the semantics of the construct.
-Thus:
-</p>
-<pre class="verbatim"> "$hash{"$foo/$bar"}"
-</pre>
-<p>or:
-</p>
-<pre class="verbatim"> m/
- bar # NOT a comment, this slash / terminated m//!
- /x
-</pre>
-<p>do not form legal quoted expressions. The quoted part ends on the
-first <code>"</code> and <code>/</code>, and the rest happens to be a
syntax error.
-Because the slash that terminated <code>m//</code> was followed by a
<code>SPACE</code>,
-the example above is not <code>m//x</code>, but rather <code>m//</code> with
no <code>/x</code>
-modifier. So the embedded <code>#</code> is interpreted as a literal
<code>#</code>.
-</p>
-<p>Also no attention is paid to <code>\c\</code> (multichar control char
syntax) during
-this search. Thus the second <code>\</code> in <code>qq/\c\/</code> is
interpreted as a part
-of <code>\/</code>, and the following <code>/</code> is not recognized as a
delimiter.
-Instead, use <code>\034</code> or <code>\x1c</code> at the end of quoted
constructs.
-</p>
-</dd>
-<dt>Interpolation</dt>
-<dd><a name="perlop-Interpolation"></a>
-<p>The next step is interpolation in the text obtained, which is now
-delimiter-independent. There are multiple cases.
-</p>
-<dl compact="compact">
-<dt><code><<'EOF'</code></dt>
-<dd><a name="perlop-_003c_003c_0027EOF_0027"></a>
-<p>No interpolation is performed.
-Note that the combination <code>\\</code> is left intact, since escaped
delimiters
-are not available for here-docs.
-</p>
-</dd>
-<dt><code>m''</code>, the pattern of <code>s'''</code></dt>
-<dd><a name="perlop-m_0027_0027_002c-the-pattern-of-s_0027_0027_0027"></a>
-<p>No interpolation is performed at this stage.
-Any backslashed sequences including <code>\\</code> are treated at the stage
-to <a href="#perlop-parsing-regular-expressions">parsing regular
expressions</a>.
-</p>
-</dd>
-<dt><code>''</code>, <code>q//</code>, <code>tr'''</code>, <code>y'''</code>,
the replacement of <code>s'''</code></dt>
-<dd><a
name="perlop-_0027_0027_002c-q_002f_002f_002c-tr_0027_0027_0027_002c-y_0027_0027_0027_002c-the-replacement-of-s_0027_0027_0027"></a>
-<p>The only interpolation is removal of <code>\</code> from pairs of
<code>\\</code>.
-Therefore <code>"-"</code> in <code>tr'''</code> and
<code>y'''</code> is treated literally
-as a hyphen and no character range is available.
-<code>\1</code> in the replacement of <code>s'''</code> does not work as
<code>$1</code>.
-</p>
-</dd>
-<dt><code>tr///</code>, <code>y///</code></dt>
-<dd><a name="perlop-tr_002f_002f_002f_002c-y_002f_002f_002f"></a>
-<p>No variable interpolation occurs. String modifying combinations for
-case and quoting such as <code>\Q</code>, <code>\U</code>, and <code>\E</code>
are not recognized.
-The other escape sequences such as <code>\200</code> and <code>\t</code> and
backslashed
-characters such as <code>\\</code> and <code>\-</code> are converted to
appropriate literals.
-The character <code>"-"</code> is treated specially and therefore
<code>\-</code> is treated
-as a literal <code>"-"</code>.
-</p>
-</dd>
-<dt><code>""</code>, <code>``</code>, <code>qq//</code>,
<code>qx//</code>, <code><file*glob></code>,
<code><<"EOF"</code></dt>
-<dd><a
name="perlop-_0022_0022_002c-_0060_0060_002c-qq_002f_002f_002c-qx_002f_002f_002c-_003cfile_002aglob_003e_002c-_003c_003c_0022EOF_0022"></a>
-<p><code>\Q</code>, <code>\U</code>, <code>\u</code>, <code>\L</code>,
<code>\l</code>, <code>\F</code> (possibly paired with <code>\E</code>) are
-converted to corresponding Perl constructs. Thus,
<code>"$foo\Qbaz$bar"</code>
-is converted to
<code>$foo . (quotemeta("baz" . $bar))</code><!--
/@w --> internally.
-The other escape sequences such as <code>\200</code> and <code>\t</code> and
backslashed
-characters such as <code>\\</code> and <code>\-</code> are replaced with
appropriate
-expansions.
-</p>
-<p>Let it be stressed that <em>whatever falls between <code>\Q</code> and
<code>\E</code></em>
-is interpolated in the usual way. Something like
<code>"\Q\\E"</code> has
-no <code>\E</code> inside. Instead, it has <code>\Q</code>, <code>\\</code>,
and <code>E</code>, so the
-result is the same as for <code>"\\\\E"</code>. As a general rule,
backslashes
-between <code>\Q</code> and <code>\E</code> may lead to counterintuitive
results. So,
-<code>"\Q\t\E"</code> is converted to
<code>quotemeta("\t")</code>, which is the same
-as <code>"\\\t"</code> (since TAB is not alphanumeric). Note also
that:
-</p>
-<pre class="verbatim"> $str = '\t';
- return "\Q$str";
-</pre>
-<p>may be closer to the conjectural <em>intention</em> of the writer of
<code>"\Q\t\E"</code>.
-</p>
-<p>Interpolated scalars and arrays are converted internally to the
<code>join</code> and
-<code>"."</code> catenation operations. Thus,
<code>"$foo XXX '@arr'"</code><!-- /@w --> becomes:
-</p>
-<pre class="verbatim"> $foo . " XXX '" . (join $", @arr) .
"'";
-</pre>
-<p>All operations above are performed simultaneously, left to right.
-</p>
-<p>Because the result of
<code>"\Q <em>STRING</em> \E"</code><!-- /@w --> has all
metacharacters
-quoted, there is no way to insert a literal <code>$</code> or <code>@</code>
inside a
-<code>\Q\E</code> pair. If protected by <code>\</code>, <code>$</code> will
be quoted to become
-<code>"\\\$"</code>; if not, it is interpreted as the start of an
interpolated
-scalar.
-</p>
-<p>Note also that the interpolation code needs to make a decision on
-where the interpolated scalar ends. For instance, whether
-<code>"a $x <span
class="nolinebreak">-></span> {c}"</code><!-- /@w --> really means:
-</p>
-<pre class="verbatim"> "a " . $x . " -> {c}";
-</pre>
-<p>or:
-</p>
-<pre class="verbatim"> "a " . $x -> {c};
-</pre>
-<p>Most of the time, the longest possible text that does not include
-spaces between components and which contains matching braces or
-brackets. because the outcome may be determined by voting based
-on heuristic estimators, the result is not strictly predictable.
-Fortunately, it’s usually correct for ambiguous cases.
-</p>
-</dd>
-<dt>the replacement of <code>s///</code></dt>
-<dd><a name="perlop-the-replacement-of-s_002f_002f_002f"></a>
-<p>Processing of <code>\Q</code>, <code>\U</code>, <code>\u</code>,
<code>\L</code>, <code>\l</code>, <code>\F</code> and interpolation
-happens as with <code>qq//</code> constructs.
-</p>
-<p>It is at this step that <code>\1</code> is begrudgingly converted to
<code>$1</code> in
-the replacement text of <code>s///</code>, in order to correct the incorrigible
-<em>sed</em> hackers who haven’t picked up the saner idiom yet. A
warning
-is emitted if the <code>use warnings</code><!-- /@w --> pragma or the
<strong>-w</strong> command-line flag
-(that is, the <code>$^W</code> variable) was set.
-</p>
-</dd>
-<dt><code>RE</code> in <code>?RE?</code>, <code>/RE/</code>,
<code>m/RE/</code>, <code>s/RE/foo/</code>,</dt>
-<dd><a
name="perlop-RE-in-_003fRE_003f_002c-_002fRE_002f_002c-m_002fRE_002f_002c-s_002fRE_002ffoo_002f_002c"></a>
-<p>Processing of <code>\Q</code>, <code>\U</code>, <code>\u</code>,
<code>\L</code>, <code>\l</code>, <code>\F</code>, <code>\E</code>,
-and interpolation happens (almost) as with <code>qq//</code> constructs.
-</p>
-<p>Processing of <code>\N{...}</code> is also done here, and compiled into an
intermediate
-form for the regex compiler. (This is because, as mentioned below, the regex
-compilation may be done at execution time, and <code>\N{...}</code> is a
compile-time
-construct.)
-</p>
-<p>However any other combinations of <code>\</code> followed by a character
-are not substituted but only skipped, in order to parse them
-as regular expressions at the following step.
-As <code>\c</code> is skipped at this step, <code>@</code> of <code>\c@</code>
in RE is possibly
-treated as an array symbol (for example <code>@foo</code>),
-even though the same text in <code>qq//</code> gives interpolation of
<code>\c@</code>.
-</p>
-<p>Code blocks such as <code>(?{BLOCK})</code> are handled by temporarily
passing control
-back to the perl parser, in a similar way that an interpolated array
-subscript expression such as
<code>"foo$array[1+f("[xyz")]bar"</code> would be.
-</p>
-<p>Moreover, inside <code>(?{BLOCK})</code>,
<code>(?# comment )</code><!-- /@w -->, and
-a <code>#</code>-comment in a <code>/x</code>-regular expression, no
processing is
-performed whatsoever. This is the first step at which the presence
-of the <code>/x</code> modifier is relevant.
-</p>
-<p>Interpolation in patterns has several quirks: <code>$|</code>,
<code>$(</code>, <code>$)</code>, <code>@+</code>
-and <code>@-</code> are not interpolated, and constructs
<code>$var[SOMETHING]</code> are
-voted (by several different estimators) to be either an array element
-or <code>$var</code> followed by an RE alternative. This is where the notation
-<code>${arr[$bar]}</code> comes handy: <code>/${arr[0-9]}/</code> is
interpreted as
-array element <code>-9</code>, not as a regular expression from the variable
-<code>$arr</code> followed by a digit, which would be the interpretation of
-<code>/$arr[0-9]/</code>. Since voting among different estimators may occur,
-the result is not predictable.
-</p>
-<p>The lack of processing of <code>\\</code> creates specific restrictions on
-the post-processed text. If the delimiter is <code>/</code>, one cannot get
-the combination <code>\/</code> into the result of this step. <code>/</code>
will
-finish the regular expression, <code>\/</code> will be stripped to
<code>/</code> on
-the previous step, and <code>\\/</code> will be left as is. Because
<code>/</code> is
-equivalent to <code>\/</code> inside a regular expression, this does not
-matter unless the delimiter happens to be character special to the
-RE engine, such as in <code>s*foo*bar*</code>, <code>m[foo]</code>, or
<code>?foo?</code>; or an
-alphanumeric char, as in:
-</p>
-<pre class="verbatim"> m m ^ a \s* b mmx;
-</pre>
-<p>In the RE above, which is intentionally obfuscated for illustration, the
-delimiter is <code>m</code>, the modifier is <code>mx</code>, and after
delimiter-removal the
-RE is the same as for
<code>m/ ^ a \s* b /mx</code><!-- /@w -->.
There’s more than one
-reason you’re encouraged to restrict your delimiters to non-alphanumeric,
-non-whitespace choices.
-</p>
-</dd>
-</dl>
-
-<p>This step is the last one for all constructs except regular expressions,
-which are processed further.
-</p>
-</dd>
-<dt>parsing regular expressions</dt>
-<dd><a name="perlop-parsing-regular-expressions"></a>
-<p>Previous steps were performed during the compilation of Perl code,
-but this one happens at run time, although it may be optimized to
-be calculated at compile time if appropriate. After preprocessing
-described above, and possibly after evaluation if concatenation,
-joining, casing translation, or metaquoting are involved, the
-resulting <em>string</em> is passed to the RE engine for compilation.
-</p>
-<p>Whatever happens in the RE engine might be better discussed in <a
href="#perlre-NAME">perlre NAME</a>,
-but for the sake of continuity, we shall do so here.
-</p>
-<p>This is another step where the presence of the <code>/x</code> modifier is
-relevant. The RE engine scans the string from left to right and
-converts it into a finite automaton.
-</p>
-<p>Backslashed characters are either replaced with corresponding
-literal strings (as with <code>\{</code>), or else they generate special nodes
-in the finite automaton (as with <code>\b</code>). Characters special to the
-RE engine (such as <code>|</code>) generate corresponding nodes or groups of
-nodes. <code>(?#...)</code> comments are ignored. All the rest is either
-converted to literal strings to match, or else is ignored (as is
-whitespace and <code>#</code>-style comments if <code>/x</code> is present).
-</p>
-<p>Parsing of the bracketed character class construct, <code>[...]</code>, is
-rather different than the rule used for the rest of the pattern.
-The terminator of this construct is found using the same rules as
-for finding the terminator of a <code>{}</code>-delimited construct, the only
-exception being that <code>]</code> immediately following <code>[</code> is
treated as
-though preceded by a backslash.
-</p>
-<p>The terminator of runtime <code>(?{...})</code> is found by temporarily
switching
-control to the perl parser, which should stop at the point where the
-logically balancing terminating <code>}</code> is found.
-</p>
-<p>It is possible to inspect both the string given to RE engine and the
-resulting finite automaton. See the arguments
<code>debug</code>/<code>debugcolor</code>
-in the <code>use <a href="re.html#Top">(re)</a></code><!-- /@w -->
pragma, as well as Perl’s <strong>-Dr</strong> command-line
-switch documented in <a href="#perlrun-Command-Switches">perlrun Command
Switches</a>.
-</p>
-</dd>
-<dt>Optimization of regular expressions</dt>
-<dd><a name="perlop-Optimization-of-regular-expressions"></a>
-<p>This step is listed for completeness only. Since it does not change
-semantics, details of this step are not documented and are subject
-to change without notice. This step is performed over the finite
-automaton that was generated during the previous pass.
-</p>
-<p>It is at this stage that <code>split()</code> silently optimizes
<code>/^/</code> to
-mean <code>/^/m</code>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlop-I_002fO-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Constant-Folding" accesskey="n" rel="next">perlop
Constant Folding</a>, Previous: <a
href="#perlop-Gory-details-of-parsing-quoted-constructs" accesskey="p"
rel="prev">perlop Gory details of parsing quoted constructs</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="I_002fO-Operators"></a>
-<h4 class="subsection">48.2.33 I/O Operators</h4>
-
-<pre class="verbatim"> >> >>
-</pre>
-<p>There are several I/O operators you should know about.
-</p>
-<p>A string enclosed by backticks (grave accents) first undergoes
-double-quote interpolation. It is then interpreted as an external
-command, and the output of that command is the value of the
-backtick string, like in a shell. In scalar context, a single string
-consisting of all output is returned. In list context, a list of
-values is returned, one per line of output. (You can set <code>$/</code> to
use
-a different line terminator.) The command is executed each time the
-pseudo-literal is evaluated. The status value of the command is
-returned in <code>$?</code> (see <a href="#perlvar-NAME">perlvar NAME</a> for
the interpretation of <code>$?</code>).
-Unlike in <strong>csh</strong>, no translation is done on the return
data–newlines
-remain newlines. Unlike in any of the shells, single quotes do not
-hide variable names in the command from interpretation. To pass a
-literal dollar-sign through to the shell you need to hide it with a
-backslash. The generalized form of backticks is <code>qx//</code>. (Because
-backticks always undergo shell expansion as well, see <a
href="#perlsec-NAME">perlsec NAME</a> for
-security concerns.)
-</p>
-<p>In scalar context, evaluating a filehandle in angle brackets yields
-the next line from that file (the newline, if any, included), or
-<code>undef</code> at end-of-file or on error. When <code>$/</code> is set to
<code>undef</code>
-(sometimes known as file-slurp mode) and the file is empty, it
-returns <code>''</code> the first time, followed by <code>undef</code>
subsequently.
-</p>
-<p>Ordinarily you must assign the returned value to a variable, but
-there is one situation where an automatic assignment happens. If
-and only if the input symbol is the only thing inside the conditional
-of a <code>while</code> statement (even if disguised as a <code>for(;;)</code>
loop),
-the value is automatically assigned to the global variable <code>$_</code>,
-destroying whatever was there previously. (This may seem like an
-odd thing to you, but you’ll use the construct in almost every Perl
-script you write.) The <code>$_</code> variable is not implicitly localized.
-You’ll have to put a <code>local <span
class="nolinebreak">$_;</span></code><!-- /@w --> before the loop if you want
that
-to happen.
-</p>
-<p>The following lines are equivalent:
-</p>
-<pre class="verbatim"> while (defined($_ = <STDIN>)) { print; }
- while ($_ = <STDIN>) { print; }
- while (<STDIN>) { print; }
- for (;<STDIN>;) { print; }
- print while defined($_ = <STDIN>);
- print while ($_ = <STDIN>);
- print while <STDIN>;
-</pre>
-<p>This also behaves similarly, but assigns to a lexical variable
-instead of to <code>$_</code>:
-</p>
-<pre class="verbatim"> while (my $line = <STDIN>) { print $line }
-</pre>
-<p>In these loop constructs, the assigned value (whether assignment
-is automatic or explicit) is then tested to see whether it is
-defined. The defined test avoids problems where the line has a string
-value that would be treated as false by Perl; for example a "" or
-a <code>"0"</code> with no trailing newline. If you really mean for
such values
-to terminate the loop, they should be tested for explicitly:
-</p>
-<pre class="verbatim"> while (($_ = <STDIN>) ne '0') { ... }
- while (<STDIN>) { last unless $_; ... }
-</pre>
-<p>In other boolean contexts, <code><<em>FILEHANDLE</em>></code> without
an
-explicit <code>defined</code> test or comparison elicits a warning if the
-<code>use warnings</code><!-- /@w --> pragma or the <strong>-w</strong>
-command-line switch (the <code>$^W</code> variable) is in effect.
-</p>
-<p>The filehandles STDIN, STDOUT, and STDERR are predefined. (The
-filehandles <code>stdin</code>, <code>stdout</code>, and <code>stderr</code>
will also work except
-in packages, where they would be interpreted as local identifiers
-rather than global.) Additional filehandles may be created with
-the <code>open()</code> function, amongst others. See <a
href="#perlopentut-NAME">perlopentut NAME</a> and
-‘perlfunc open’ for details on this.
-</p>
-<p>If a <code><<em>FILEHANDLE</em>></code> is used in a context that is
looking for
-a list, a list comprising all input lines is returned, one line per
-list element. It’s easy to grow to a rather large data space this
-way, so use with care.
-</p>
-<p><code><<em>FILEHANDLE</em>></code> may also be spelled
<code>readline(*<em>FILEHANDLE</em>)</code>.
-See <a href="#perlfunc-readline">perlfunc readline</a>.
-</p>
-<p>The null filehandle <code><></code> is special: it can be used to
emulate the
-behavior of <strong>sed</strong> and <strong>awk</strong>, and any other Unix
filter program
-that takes a list of filenames, doing the same to each line
-of input from all of them. Input from <code><></code> comes either from
-standard input, or from each file listed on the command line. Here’s
-how it works: the first time <code><></code> is evaluated, the
<code>@ARGV</code> array is
-checked, and if it is empty, <code>$ARGV[0]</code> is set to
<code>"-"</code>, which when opened
-gives you standard input. The <code>@ARGV</code> array is then processed as a
list
-of filenames. The loop
-</p>
-<pre class="verbatim"> while (<>) {
- ... # code for each line
- }
-</pre>
-<p>is equivalent to the following Perl-like pseudo code:
-</p>
-<pre class="verbatim"> unshift(@ARGV, '-') unless @ARGV;
- while ($ARGV = shift) {
- open(ARGV, $ARGV);
- while (<ARGV>) {
- ... # code for each line
- }
- }
-</pre>
-<p>except that it isn’t so cumbersome to say, and will actually work.
-It really does shift the <code>@ARGV</code> array and put the current filename
-into the <code>$ARGV</code> variable. It also uses filehandle <em>ARGV</em>
-internally. <code><></code> is just a synonym for
<code><ARGV></code>, which
-is magical. (The pseudo code above doesn’t work because it treats
-<code><ARGV></code> as non-magical.)
-</p>
-<p>Since the null filehandle uses the two argument form of ‘perlfunc
open’
-it interprets special characters, so if you have a script like this:
-</p>
-<pre class="verbatim"> while (<>) {
- print;
- }
-</pre>
-<p>and call it with <code>perl dangerous.pl 'rm <span
class="nolinebreak">-rfv</span> *|'</code><!-- /@w -->, it actually opens a
-pipe, executes the <code>rm</code> command and reads <code>rm</code>’s
output from that pipe.
-If you want all items in <code>@ARGV</code> to be interpreted as file names,
you
-can use the module <code>ARGV::readonly</code> from CPAN, or use the double
bracket:
-</p>
-<pre class="verbatim"> while (<<>>) {
- print;
- }
-</pre>
-<p>Using double angle brackets inside of a while causes the open to use the
-three argument form (with the second argument being <code><</code>), so all
-arguments in <code>ARGV</code> are treated as literal filenames (including
<code>"-"</code>).
-(Note that for convenience, if you use <code><<>></code> and if
<code>@ARGV</code> is
-empty, it will still read from the standard input.)
-</p>
-<p>You can modify <code>@ARGV</code> before the first <code><></code> as
long as the array ends up
-containing the list of filenames you really want. Line numbers
(<code>$.</code>)
-continue as though the input were one big happy file. See the example
-in <a href="#perlfunc-eof">perlfunc eof</a> for how to reset line numbers on
each file.
-</p>
-<p>If you want to set <code>@ARGV</code> to your own list of files, go right
ahead.
-This sets <code>@ARGV</code> to all plain text files if no <code>@ARGV</code>
was given:
-</p>
-<pre class="verbatim"> @ARGV = grep { -f && -T } glob('*') unless
@ARGV;
-</pre>
-<p>You can even set them to pipe commands. For example, this automatically
-filters compressed arguments through <strong>gzip</strong>:
-</p>
-<pre class="verbatim"> @ARGV = map { /\.(gz|Z)$/ ? "gzip -dc < $_
|" : $_ } @ARGV;
-</pre>
-<p>If you want to pass switches into your script, you can use one of the
-<code>Getopts</code> modules or put a loop on the front like this:
-</p>
-<pre class="verbatim"> while ($_ = $ARGV[0], /^-/) {
- shift;
- last if /^--$/;
- if (/^-D(.*)/) { $debug = $1 }
- if (/^-v/) { $verbose++ }
- # ... # other switches
- }
-
- while (<>) {
- # ... # code for each line
- }
-</pre>
-<p>The <code><></code> symbol will return <code>undef</code> for
end-of-file only once.
-If you call it again after this, it will assume you are processing another
-<code>@ARGV</code> list, and if you haven’t set <code>@ARGV</code>, will
read input from STDIN.
-</p>
-<p>If what the angle brackets contain is a simple scalar variable (for example,
-<code>$foo</code>), then that variable contains the name of the
-filehandle to input from, or its typeglob, or a reference to the
-same. For example:
-</p>
-<pre class="verbatim"> $fh = \*STDIN;
- $line = <$fh>;
-</pre>
-<p>If what’s within the angle brackets is neither a filehandle nor a
simple
-scalar variable containing a filehandle name, typeglob, or typeglob
-reference, it is interpreted as a filename pattern to be globbed, and
-either a list of filenames or the next filename in the list is returned,
-depending on context. This distinction is determined on syntactic
-grounds alone. That means <code><$x></code> is always a
<code>readline()</code> from
-an indirect handle, but <code><$hash{key}></code> is always a
<code>glob()</code>.
-That’s because <code>$x</code> is a simple scalar variable, but
<code>$hash{key}</code> is
-not–it’s a hash element. Even <code><$x ></code> (note the
extra space)
-is treated as <code>glob("$x ")</code>, not
<code>readline($x)</code>.
-</p>
-<p>One level of double-quote interpretation is done first, but you can’t
-say <code><$foo></code> because that’s an indirect filehandle as
explained
-in the previous paragraph. (In older versions of Perl, programmers
-would insert curly brackets to force interpretation as a filename glob:
-<code><${foo}></code>. These days, it’s considered cleaner to
call the
-internal function directly as <code>glob($foo)</code>, which is probably the
right
-way to have done it in the first place.) For example:
-</p>
-<pre class="verbatim"> while (<*.c>) {
- chmod 0644, $_;
- }
-</pre>
-<p>is roughly equivalent to:
-</p>
-<pre class="verbatim"> open(FOO, "echo *.c | tr -s ' \t\r\f'
'\\012\\012\\012\\012'|");
- while (<FOO>) {
- chomp;
- chmod 0644, $_;
- }
-</pre>
-<p>except that the globbing is actually done internally using the standard
-<code><a href="File-Glob.html#Top">(File-Glob)</a></code> extension. Of
course, the shortest way to do the above is:
-</p>
-<pre class="verbatim"> chmod 0644, <*.c>;
-</pre>
-<p>A (file)glob evaluates its (embedded) argument only when it is
-starting a new list. All values must be read before it will start
-over. In list context, this isn’t important because you automatically
-get them all anyway. However, in scalar context the operator returns
-the next value each time it’s called, or <code>undef</code> when the
list has
-run out. As with filehandle reads, an automatic <code>defined</code> is
-generated when the glob occurs in the test part of a <code>while</code>,
-because legal glob returns (for example,
-a file called <samp>0</samp>) would otherwise
-terminate the loop. Again, <code>undef</code> is returned only once. So if
-you’re expecting a single value from a glob, it is much better to
-say
-</p>
-<pre class="verbatim"> ($file) = <blurch*>;
-</pre>
-<p>than
-</p>
-<pre class="verbatim"> $file = <blurch*>;
-</pre>
-<p>because the latter will alternate between returning a filename and
-returning false.
-</p>
-<p>If you’re trying to do variable interpolation, it’s definitely
better
-to use the <code>glob()</code> function, because the older notation can cause
people
-to become confused with the indirect filehandle notation.
-</p>
-<pre class="verbatim"> @files = glob("$dir/*.[ch]");
- @files = glob($files[$i]);
-</pre>
-<hr>
-<a name="perlop-Constant-Folding"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-No_002dops" accesskey="n" rel="next">perlop No-ops</a>,
Previous: <a href="#perlop-I_002fO-Operators" accesskey="p" rel="prev">perlop
I/O Operators</a>, Up: <a href="#perlop-DESCRIPTION" accesskey="u"
rel="up">perlop DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Constant-Folding"></a>
-<h4 class="subsection">48.2.34 Constant Folding</h4>
-
-<p>Like C, Perl does a certain amount of expression evaluation at
-compile time whenever it determines that all arguments to an
-operator are static and have no side effects. In particular, string
-concatenation happens at compile time between literals that don’t do
-variable substitution. Backslash interpolation also happens at
-compile time. You can say
-</p>
-<pre class="verbatim"> 'Now is the time for all'
- . "\n"
- . 'good men to come to.'
-</pre>
-<p>and this all reduces to one string internally. Likewise, if
-you say
-</p>
-<pre class="verbatim"> foreach $file (@filenames) {
- if (-s $file > 5 + 100 * 2**16) { }
- }
-</pre>
-<p>the compiler precomputes the number which that expression
-represents so that the interpreter won’t have to.
-</p>
-<hr>
-<a name="perlop-No_002dops"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Bitwise-String-Operators" accesskey="n"
rel="next">perlop Bitwise String Operators</a>, Previous: <a
href="#perlop-Constant-Folding" accesskey="p" rel="prev">perlop Constant
Folding</a>, Up: <a href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="No_002dops"></a>
-<h4 class="subsection">48.2.35 No-ops</h4>
-
-<p>Perl doesn’t officially have a no-op operator, but the bare constants
-<code>0</code> and <code>1</code> are special-cased not to produce a warning
in void
-context, so you can for example safely do
-</p>
-<pre class="verbatim"> 1 while foo();
-</pre>
-<hr>
-<a name="perlop-Bitwise-String-Operators"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Integer-Arithmetic" accesskey="n" rel="next">perlop
Integer Arithmetic</a>, Previous: <a href="#perlop-No_002dops" accesskey="p"
rel="prev">perlop No-ops</a>, Up: <a href="#perlop-DESCRIPTION" accesskey="u"
rel="up">perlop DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Bitwise-String-Operators"></a>
-<h4 class="subsection">48.2.36 Bitwise String Operators</h4>
-
-<p>Bitstrings of any size may be manipulated by the bitwise operators
-(<code>~ | & ^</code>).
-</p>
-<p>If the operands to a binary bitwise op are strings of different
-sizes, <strong>|</strong> and <strong>^</strong> ops act as though the shorter
operand had
-additional zero bits on the right, while the <strong>&</strong> op acts as
though
-the longer operand were truncated to the length of the shorter.
-The granularity for such extension or truncation is one or more
-bytes.
-</p>
-<pre class="verbatim"> # ASCII-based examples
- print "j p \n" ^ " a h"; # prints
"JAPH\n"
- print "JA" | " ph\n"; # prints
"japh\n"
- print "japh\nJunk" & '_____'; # prints
"JAPH\n";
- print 'p N$' ^ " E<H\n"; # prints
"Perl\n";
-</pre>
-<p>If you are intending to manipulate bitstrings, be certain that
-you’re supplying bitstrings: If an operand is a number, that will imply
-a <strong>numeric</strong> bitwise operation. You may explicitly show which
type of
-operation you intend by using <code>""</code> or <code>0+</code>, as
in the examples below.
-</p>
-<pre class="verbatim"> $foo = 150 | 105; # yields 255 (0x96 |
0x69 is 0xFF)
- $foo = '150' | 105; # yields 255
- $foo = 150 | '105'; # yields 255
- $foo = '150' | '105'; # yields string '155' (under ASCII)
-
- $baz = 0+$foo & 0+$bar; # both ops explicitly numeric
- $biz = "$foo" ^ "$bar"; # both ops explicitly
stringy
-</pre>
-<p>This somewhat unpredictable behavior can be avoided with the experimental
-"bitwise" feature, new in Perl 5.22. You can enable it via
<code>use feature 'bitwise'</code><!-- /@w -->. By default, it will
warn unless the <code>"experimental::bitwise"</code>
-warnings category has been disabled.
(<code>use experimental 'bitwise'</code><!-- /@w --> will
-enable the feature and disable the warning.) Under this feature, the four
-standard bitwise operators (<code>~ | & ^</code>) are always numeric.
Adding a dot
-after each operator (<code>~. |. &. ^.</code>) forces it to treat its
operands as
-strings:
-</p>
-<pre class="verbatim"> use experimental "bitwise";
- $foo = 150 | 105; # yields 255 (0x96 | 0x69 is 0xFF)
- $foo = '150' | 105; # yields 255
- $foo = 150 | '105'; # yields 255
- $foo = '150' | '105'; # yields 255
- $foo = 150 |. 105; # yields string '155'
- $foo = '150' |. 105; # yields string '155'
- $foo = 150 |.'105'; # yields string '155'
- $foo = '150' |.'105'; # yields string '155'
-
- $baz = $foo & $bar; # both operands numeric
- $biz = $foo ^. $bar; # both operands stringy
-</pre>
-<p>The assignment variants of these operators (<code>&= |= ^= &.= |.=
^.=</code>)
-behave likewise under the feature.
-</p>
-<p>The behavior of these operators is problematic (and subject to change)
-if either or both of the strings are encoded in UTF-8 (see
-<a href="#perlunicode-Byte-and-Character-Semantics">perlunicode Byte and
Character Semantics</a>.
-</p>
-<p>See ‘perlfunc vec’ for information on how to manipulate
individual bits
-in a bit vector.
-</p>
-<hr>
-<a name="perlop-Integer-Arithmetic"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Floating_002dpoint-Arithmetic" accesskey="n"
rel="next">perlop Floating-point Arithmetic</a>, Previous: <a
href="#perlop-Bitwise-String-Operators" accesskey="p" rel="prev">perlop Bitwise
String Operators</a>, Up: <a href="#perlop-DESCRIPTION" accesskey="u"
rel="up">perlop DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Integer-Arithmetic"></a>
-<h4 class="subsection">48.2.37 Integer Arithmetic</h4>
-
-<p>By default, Perl assumes that it must do most of its arithmetic in
-floating point. But by saying
-</p>
-<pre class="verbatim"> use integer;
-</pre>
-<p>you may tell the compiler to use integer operations
-(see <a href="integer.html#Top">(integer)</a> for a detailed explanation) from
here to the end of
-the enclosing BLOCK. An inner BLOCK may countermand this by saying
-</p>
-<pre class="verbatim"> no integer;
-</pre>
-<p>which lasts until the end of that BLOCK. Note that this doesn’t
-mean everything is an integer, merely that Perl will use integer
-operations for arithmetic, comparison, and bitwise operators. For
-example, even under <code>use integer</code><!-- /@w -->, if you take the
<code>sqrt(2)</code>, you’ll
-still get <code>1.4142135623731</code> or so.
-</p>
-<p>Used on numbers, the bitwise operators (<code>&</code> <code>|</code>
<code>^</code> <code>~</code> <code><<</code>
-<code>>></code>) always produce integral results. (But see also
-<a href="#perlop-Bitwise-String-Operators">Bitwise String Operators</a>.)
However, <code>use integer</code><!-- /@w --> still has meaning for
-them. By default, their results are interpreted as unsigned integers, but
-if <code>use integer</code><!-- /@w --> is in effect, their results are
interpreted
-as signed integers. For example, <code>~0</code> usually evaluates to a large
-integral value. However, <code>use integer; ~0</code><!-- /@w -->
is <code>-1</code> on two’s-complement
-machines.
-</p>
-<hr>
-<a name="perlop-Floating_002dpoint-Arithmetic"></a>
-<div class="header">
-<p>
-Next: <a href="#perlop-Bigger-Numbers" accesskey="n" rel="next">perlop Bigger
Numbers</a>, Previous: <a href="#perlop-Integer-Arithmetic" accesskey="p"
rel="prev">perlop Integer Arithmetic</a>, Up: <a href="#perlop-DESCRIPTION"
accesskey="u" rel="up">perlop DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Floating_002dpoint-Arithmetic"></a>
-<h4 class="subsection">48.2.38 Floating-point Arithmetic</h4>
-
-<p>While <code>use integer</code><!-- /@w --> provides integer-only
arithmetic, there is no
-analogous mechanism to provide automatic rounding or truncation to a
-certain number of decimal places. For rounding to a certain number
-of digits, <code>sprintf()</code> or <code>printf()</code> is usually the
easiest route.
-See <a href="perlfaq4.html#Top">(perlfaq4)</a>.
-</p>
-<p>Floating-point numbers are only approximations to what a mathematician
-would call real numbers. There are infinitely more reals than floats,
-so some corners must be cut. For example:
-</p>
-<pre class="verbatim"> printf "%.20g\n", 123456789123456789;
- # produces 123456789123456784
-</pre>
-<p>Testing for exact floating-point equality or inequality is not a
-good idea. Here’s a (relatively expensive) work-around to compare
-whether two floating-point numbers are equal to a particular number of
-decimal places. See Knuth, volume II, for a more robust treatment of
-this topic.
-</p>
-<pre class="verbatim"> sub fp_equal {
- my ($X, $Y, $POINTS) = @_;
- my ($tX, $tY);
- $tX = sprintf("%.${POINTS}g", $X);
- $tY = sprintf("%.${POINTS}g", $Y);
- return $tX eq $tY;
- }
-</pre>
-<p>The POSIX module (part of the standard perl distribution) implements
-<code>ceil()</code>, <code>floor()</code>, and other mathematical and
trigonometric functions.
-The <code><a href="Math-Complex.html#Top">(Math-Complex)</a></code> module
(part of the standard perl distribution)
-defines mathematical functions that work on both the reals and the
-imaginary numbers. <code>Math::Complex</code> is not as efficient as POSIX,
but
-POSIX can’t work with complex numbers.
-</p>
-<p>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
-need yourself.
-</p>
-<hr>
-<a name="perlop-Bigger-Numbers"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlop-Floating_002dpoint-Arithmetic" accesskey="p"
rel="prev">perlop Floating-point Arithmetic</a>, Up: <a
href="#perlop-DESCRIPTION" accesskey="u" rel="up">perlop DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Bigger-Numbers"></a>
-<h4 class="subsection">48.2.39 Bigger Numbers</h4>
-
-<p>The standard <code><a href="Math-BigInt.html#Top">(Math-BigInt)</a></code>,
<code><a href="Math-BigRat.html#Top">(Math-BigRat)</a></code>, and
-<code><a href="Math-BigFloat.html#Top">(Math-BigFloat)</a></code> modules,
-along with the <code>bignum</code>, <code>bigint</code>, and
<code>bigrat</code> 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.
-</p>
-<pre class="verbatim"> use 5.010;
- use bigint; # easy interface to Math::BigInt
- $x = 123456789123456789;
- say $x * $x;
- +15241578780673678515622620750190521
-</pre>
-<p>Or with rationals:
-</p>
-<pre class="verbatim"> use 5.010;
- use bigrat;
- $x = 3/22;
- $y = 4/6;
- say "x/y is ", $x/$y;
- say "x*y is ", $x*$y;
- x/y is 9/44
- x*y is 1/11
-</pre>
-<p>Several modules let you calculate with unlimited or fixed precision
-(bound only by memory and CPU time). There
-are also some non-standard modules that
-provide faster implementations via external C libraries.
-</p>
-<p>Here is a short, but incomplete summary:
-</p>
-<pre class="verbatim"> 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::Cephes uses the external Cephes C library (no
- big numbers)
- Math::Cephes::Fraction fractions via the Cephes library
- Math::GMP another one using an external C library
- Math::GMPz an alternative interface to libgmp's big ints
- Math::GMPq an interface to libgmp's fraction numbers
- Math::GMPf an interface to libgmp's floating point numbers
-</pre>
-<p>Choose wisely.
-</p>
-<hr>
-<a name="perlopentut"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut" accesskey="n" rel="next">perlpacktut</a>,
Previous: <a href="#perlop" accesskey="p" rel="prev">perlop</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlopentut-1"></a>
-<h2 class="chapter">49 perlopentut</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlopentut-NAME"
accesskey="1">perlopentut NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlopentut-DESCRIPTION"
accesskey="2">perlopentut DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlopentut-Opening-Text-Files" accesskey="3">perlopentut Opening Text
Files</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlopentut-Opening-Binary-Files" accesskey="4">perlopentut Opening
Binary Files</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlopentut-Opening-Pipes"
accesskey="5">perlopentut Opening Pipes</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlopentut-Low_002dlevel-File-Opens-via-sysopen"
accesskey="6">perlopentut Low-level File Opens via
sysopen</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlopentut-SEE-ALSO"
accesskey="7">perlopentut SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlopentut-AUTHOR-and-COPYRIGHT" accesskey="8">perlopentut AUTHOR and
COPYRIGHT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlopentut-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlopentut-DESCRIPTION" accesskey="n" rel="next">perlopentut
DESCRIPTION</a>, Up: <a href="#perlopentut" accesskey="u"
rel="up">perlopentut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-48"></a>
-<h3 class="section">49.1 NAME</h3>
-
-<p>perlopentut - simple recipes for opening files and pipes in Perl
-</p>
-<hr>
-<a name="perlopentut-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlopentut-Opening-Text-Files" accesskey="n"
rel="next">perlopentut Opening Text Files</a>, Previous: <a
href="#perlopentut-NAME" accesskey="p" rel="prev">perlopentut NAME</a>, Up: <a
href="#perlopentut" accesskey="u" rel="up">perlopentut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-47"></a>
-<h3 class="section">49.2 DESCRIPTION</h3>
-
-<p>Whenever you do I/O on a file in Perl, you do so through what in Perl is
-called a <strong>filehandle</strong>. A filehandle is an internal name for an
external
-file. It is the job of the <code>open</code> function to make the association
-between the internal name and the external name, and it is the job
-of the <code>close</code> function to break that association.
-</p>
-<p>For your convenience, Perl sets up a few special filehandles that are
-already open when you run. These include <code>STDIN</code>,
<code>STDOUT</code>, <code>STDERR</code>,
-and <code>ARGV</code>. Since those are pre-opened, you can use them right away
-without having to go to the trouble of opening them yourself:
-</p>
-<pre class="verbatim"> print STDERR "This is a debugging
message.\n";
-
- print STDOUT "Please enter something: ";
- $response = <STDIN> // die "how come no input?";
- print STDOUT "Thank you!\n";
-
- while (<ARGV>) { ... }
-</pre>
-<p>As you see from those examples, <code>STDOUT</code> and <code>STDERR</code>
are output
-handles, and <code>STDIN</code> and <code>ARGV</code> are input handles. They
are
-in all capital letters because they are reserved to Perl, much
-like the <code>@ARGV</code> array and the <code>%ENV</code> hash are. Their
external
-associations were set up by your shell.
-</p>
-<p>You will need to open every other filehandle on your own. Although there
-are many variants, the most common way to call Perl’s open() function
-is with three arguments and one return value:
-</p>
-<p><code> <em>OK</em> = open(<em>HANDLE</em>, <em>MODE</em>,
<em>PATHNAME</em>)</code>
-</p>
-<p>Where:
-</p>
-<dl compact="compact">
-<dt><em>OK</em></dt>
-<dd><a name="perlopentut-OK"></a>
-<p>will be some defined value if the open succeeds, but
-<code>undef</code> if it fails;
-</p>
-</dd>
-<dt><em>HANDLE</em></dt>
-<dd><a name="perlopentut-HANDLE"></a>
-<p>should be an undefined scalar variable to be filled in by the
-<code>open</code> function if it succeeds;
-</p>
-</dd>
-<dt><em>MODE</em></dt>
-<dd><a name="perlopentut-MODE"></a>
-<p>is the access mode and the encoding format to open the file with;
-</p>
-</dd>
-<dt><em>PATHNAME</em></dt>
-<dd><a name="perlopentut-PATHNAME"></a>
-<p>is the external name of the file you want opened.
-</p>
-</dd>
-</dl>
-
-<p>Most of the complexity of the <code>open</code> function lies in the many
-possible values that the <em>MODE</em> parameter can take on.
-</p>
-<p>One last thing before we show you how to open files: opening
-files does not (usually) automatically lock them in Perl. See
-<a href="perlfaq5.html#Top">(perlfaq5)</a> for how to lock.
-</p>
-<hr>
-<a name="perlopentut-Opening-Text-Files"></a>
-<div class="header">
-<p>
-Next: <a href="#perlopentut-Opening-Binary-Files" accesskey="n"
rel="next">perlopentut Opening Binary Files</a>, Previous: <a
href="#perlopentut-DESCRIPTION" accesskey="p" rel="prev">perlopentut
DESCRIPTION</a>, Up: <a href="#perlopentut" accesskey="u"
rel="up">perlopentut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Opening-Text-Files"></a>
-<h3 class="section">49.3 Opening Text Files</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlopentut-Opening-Text-Files-for-Reading" accesskey="1">perlopentut
Opening Text Files for Reading</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlopentut-Opening-Text-Files-for-Writing" accesskey="2">perlopentut
Opening Text Files for Writing</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlopentut-Opening-Text-Files-for-Reading"></a>
-<div class="header">
-<p>
-Next: <a href="#perlopentut-Opening-Text-Files-for-Writing" accesskey="n"
rel="next">perlopentut Opening Text Files for Writing</a>, Up: <a
href="#perlopentut-Opening-Text-Files" accesskey="u" rel="up">perlopentut
Opening Text Files</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Opening-Text-Files-for-Reading"></a>
-<h4 class="subsection">49.3.1 Opening Text Files for Reading</h4>
-
-<p>If you want to read from a text file, first open it in
-read-only mode like this:
-</p>
-<pre class="verbatim"> my $filename =
"/some/path/to/a/textfile/goes/here";
- my $encoding = ":encoding(UTF-8)";
- my $handle = undef; # this will be filled in on success
-
- open($handle, "< $encoding", $filename)
- || die "$0: can't open $filename for reading: $!";
-</pre>
-<p>As with the shell, in Perl the <code>"<"</code> is used to
open the file in
-read-only mode. If it succeeds, Perl allocates a brand new filehandle for
-you and fills in your previously undefined <code>$handle</code> argument with a
-reference to that handle.
-</p>
-<p>Now you may use functions like <code>readline</code>, <code>read</code>,
<code>getc</code>, and
-<code>sysread</code> on that handle. Probably the most common input function
-is the one that looks like an operator:
-</p>
-<pre class="verbatim"> $line = readline($handle);
- $line = <$handle>; # same thing
-</pre>
-<p>Because the <code>readline</code> function returns <code>undef</code> at
end of file or
-upon error, you will sometimes see it used this way:
-</p>
-<pre class="verbatim"> $line = <$handle>;
- if (defined $line) {
- # do something with $line
- }
- else {
- # $line is not valid, so skip it
- }
-</pre>
-<p>You can also just quickly <code>die</code> on an undefined value this way:
-</p>
-<pre class="verbatim"> $line = <$handle> // die "no input
found";
-</pre>
-<p>However, if hitting EOF is an expected and normal event, you do not want to
-exit simply because you have run out of input. Instead, you probably just want
-to exit an input loop. You can then test to see if an actual error has caused
-the loop to terminate, and act accordingly:
-</p>
-<pre class="verbatim"> while (<$handle>) {
- # do something with data in $_
- }
- if ($!) {
- die "unexpected error while reading from $filename: $!";
- }
-</pre>
-<p><strong>A Note on Encodings</strong>: Having to specify the text encoding
every time
-might seem a bit of a bother. To set up a default encoding for
<code>open</code> so
-that you don’t have to supply it each time, you can use the
<code>open</code> pragma:
-</p>
-<pre class="verbatim"> use open qw< :encoding(UTF-8) >;
-</pre>
-<p>Once you’ve done that, you can safely omit the encoding part of the
-open mode:
-</p>
-<pre class="verbatim"> open($handle, "<", $filename)
- || die "$0: can't open $filename for reading: $!";
-</pre>
-<p>But never use the bare <code>"<"</code> without having set up
a default encoding
-first. Otherwise, Perl cannot know which of the many, many, many possible
-flavors of text file you have, and Perl will have no idea how to correctly
-map the data in your file into actual characters it can work with. Other
-common encoding formats including <code>"ASCII"</code>,
<code>"ISO-8859-1"</code>,
-<code>"ISO-8859-15"</code>, <code>"Windows-1252"</code>,
<code>"MacRoman"</code>, and even <code>"UTF-16LE"</code>.
-See <a href="#perlunitut-NAME">perlunitut NAME</a> for more about encodings.
-</p>
-<hr>
-<a name="perlopentut-Opening-Text-Files-for-Writing"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlopentut-Opening-Text-Files-for-Reading" accesskey="p"
rel="prev">perlopentut Opening Text Files for Reading</a>, Up: <a
href="#perlopentut-Opening-Text-Files" accesskey="u" rel="up">perlopentut
Opening Text Files</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Opening-Text-Files-for-Writing"></a>
-<h4 class="subsection">49.3.2 Opening Text Files for Writing</h4>
-
-<p>When you want to write to a file, you first have to decide what to do about
-any existing contents of that file. You have two basic choices here: to
-preserve or to clobber.
-</p>
-<p>If you want to preserve any existing contents, then you want to open the
file
-in append mode. As in the shell, in Perl you use
<code>">>"</code> to open an
-existing file in append mode. <code>">>"</code> creates the
file if it does not
-already exist.
-</p>
-<pre class="verbatim"> my $handle = undef;
- my $filename = "/some/path/to/a/textfile/goes/here";
- my $encoding = ":encoding(UTF-8)";
-
- open($handle, ">> $encoding", $filename)
- || die "$0: can't open $filename for appending: $!";
-</pre>
-<p>Now you can write to that filehandle using any of <code>print</code>,
<code>printf</code>,
-<code>say</code>, <code>write</code>, or <code>syswrite</code>.
-</p>
-<p>As noted above, if the file does not already exist, then the append-mode
open
-will create it for you. But if the file does already exist, its contents are
-safe from harm because you will be adding your new text past the end of the
-old text.
-</p>
-<p>On the other hand, sometimes you want to clobber whatever might already be
-there. To empty out a file before you start writing to it, you can open it
-in write-only mode:
-</p>
-<pre class="verbatim"> my $handle = undef;
- my $filename = "/some/path/to/a/textfile/goes/here";
- my $encoding = ":encoding(UTF-8)";
-
- open($handle, "> $encoding", $filename)
- || die "$0: can't open $filename in write-open mode: $!";
-</pre>
-<p>Here again Perl works just like the shell in that the
<code>">"</code> clobbers
-an existing file.
-</p>
-<p>As with the append mode, when you open a file in write-only mode,
-you can now write to that filehandle using any of <code>print</code>,
<code>printf</code>,
-<code>say</code>, <code>write</code>, or <code>syswrite</code>.
-</p>
-<p>What about read-write mode? You should probably pretend it doesn’t
exist,
-because opening text files in read-write mode is unlikely to do what you
-would like. See <a href="perlfaq5.html#Top">(perlfaq5)</a> for details.
-</p>
-<hr>
-<a name="perlopentut-Opening-Binary-Files"></a>
-<div class="header">
-<p>
-Next: <a href="#perlopentut-Opening-Pipes" accesskey="n"
rel="next">perlopentut Opening Pipes</a>, Previous: <a
href="#perlopentut-Opening-Text-Files" accesskey="p" rel="prev">perlopentut
Opening Text Files</a>, Up: <a href="#perlopentut" accesskey="u"
rel="up">perlopentut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Opening-Binary-Files"></a>
-<h3 class="section">49.4 Opening Binary Files</h3>
-
-<p>If the file to be opened contains binary data instead of text characters,
-then the <code>MODE</code> argument to <code>open</code> is a little
different. Instead of
-specifying the encoding, you tell Perl that your data are in raw bytes.
-</p>
-<pre class="verbatim"> my $filename =
"/some/path/to/a/binary/file/goes/here";
- my $encoding = ":raw :bytes"
- my $handle = undef; # this will be filled in on success
-</pre>
-<p>And then open as before, choosing <code>"<"</code>,
<code>">>"</code>, or
-<code>">"</code> as needed:
-</p>
-<pre class="verbatim"> open($handle, "< $encoding", $filename)
- || die "$0: can't open $filename for reading: $!";
-
- open($handle, ">> $encoding", $filename)
- || die "$0: can't open $filename for appending: $!";
-
- open($handle, "> $encoding", $filename)
- || die "$0: can't open $filename in write-open mode: $!";
-</pre>
-<p>Alternately, you can change to binary mode on an existing handle this way:
-</p>
-<pre class="verbatim"> binmode($handle) || die "cannot binmode
handle";
-</pre>
-<p>This is especially handy for the handles that Perl has already opened for
you.
-</p>
-<pre class="verbatim"> binmode(STDIN) || die "cannot binmode
STDIN";
- binmode(STDOUT) || die "cannot binmode STDOUT";
-</pre>
-<p>You can also pass <code>binmode</code> an explicit encoding to change it on
the fly.
-This isn’t exactly "binary" mode, but we still use
<code>binmode</code> to do it:
-</p>
-<pre class="verbatim"> binmode(STDIN, ":encoding(MacRoman)") ||
die "cannot binmode STDIN";
- binmode(STDOUT, ":encoding(UTF-8)") || die "cannot binmode
STDOUT";
-</pre>
-<p>Once you have your binary file properly opened in the right mode, you can
-use all the same Perl I/O functions as you used on text files. However,
-you may wish to use the fixed-size <code>read</code> instead of the
variable-sized
-<code>readline</code> for your input.
-</p>
-<p>Here’s an example of how to copy a binary file:
-</p>
-<pre class="verbatim"> my $BUFSIZ = 64 * (2 ** 10);
- my $name_in = "/some/input/file";
- my $name_out = "/some/output/flie";
-
- my($in_fh, $out_fh, $buffer);
-
- open($in_fh, "<", $name_in)
- || die "$0: cannot open $name_in for reading: $!";
- open($out_fh, ">", $name_out)
- || die "$0: cannot open $name_out for writing: $!";
-
- for my $fh ($in_fh, $out_fh) {
- binmode($fh) || die "binmode failed";
- }
-
- while (read($in_fh, $buffer, $BUFSIZ)) {
- unless (print $out_fh $buffer) {
- die "couldn't write to $name_out: $!";
- }
- }
-
- close($in_fh) || die "couldn't close $name_in: $!";
- close($out_fh) || die "couldn't close $name_out: $!";
-</pre>
-<hr>
-<a name="perlopentut-Opening-Pipes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlopentut-Low_002dlevel-File-Opens-via-sysopen"
accesskey="n" rel="next">perlopentut Low-level File Opens via sysopen</a>,
Previous: <a href="#perlopentut-Opening-Binary-Files" accesskey="p"
rel="prev">perlopentut Opening Binary Files</a>, Up: <a href="#perlopentut"
accesskey="u" rel="up">perlopentut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Opening-Pipes"></a>
-<h3 class="section">49.5 Opening Pipes</h3>
-
-<p>To be announced.
-</p>
-<hr>
-<a name="perlopentut-Low_002dlevel-File-Opens-via-sysopen"></a>
-<div class="header">
-<p>
-Next: <a href="#perlopentut-SEE-ALSO" accesskey="n" rel="next">perlopentut SEE
ALSO</a>, Previous: <a href="#perlopentut-Opening-Pipes" accesskey="p"
rel="prev">perlopentut Opening Pipes</a>, Up: <a href="#perlopentut"
accesskey="u" rel="up">perlopentut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Low_002dlevel-File-Opens-via-sysopen"></a>
-<h3 class="section">49.6 Low-level File Opens via sysopen</h3>
-
-<p>To be announced. Or deleted.
-</p>
-<hr>
-<a name="perlopentut-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlopentut-AUTHOR-and-COPYRIGHT" accesskey="n"
rel="next">perlopentut AUTHOR and COPYRIGHT</a>, Previous: <a
href="#perlopentut-Low_002dlevel-File-Opens-via-sysopen" accesskey="p"
rel="prev">perlopentut Low-level File Opens via sysopen</a>, Up: <a
href="#perlopentut" accesskey="u" rel="up">perlopentut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-24"></a>
-<h3 class="section">49.7 SEE ALSO</h3>
-
-<p>To be announced.
-</p>
-<hr>
-<a name="perlopentut-AUTHOR-and-COPYRIGHT"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlopentut-SEE-ALSO" accesskey="p" rel="prev">perlopentut
SEE ALSO</a>, Up: <a href="#perlopentut" accesskey="u" rel="up">perlopentut</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-and-COPYRIGHT"></a>
-<h3 class="section">49.8 AUTHOR and COPYRIGHT</h3>
-
-<p>Copyright 2013 Tom Christiansen.
-</p>
-<p>This documentation is free; you can redistribute it and/or modify it under
-the same terms as Perl itself.
-</p>
-<hr>
-<a name="perlpacktut"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf" accesskey="n" rel="next">perlperf</a>, Previous: <a
href="#perlopentut" accesskey="p" rel="prev">perlopentut</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlpacktut-1"></a>
-<h2 class="chapter">50 perlpacktut</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlpacktut-NAME"
accesskey="1">perlpacktut NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpacktut-DESCRIPTION"
accesskey="2">perlpacktut DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-The-Basic-Principle" accesskey="3">perlpacktut The Basic
Principle</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpacktut-Packing-Text"
accesskey="4">perlpacktut Packing Text</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Packing-Numbers" accesskey="5">perlpacktut Packing
Numbers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Exotic-Templates" accesskey="6">perlpacktut Exotic
Templates</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Template-Grouping" accesskey="7">perlpacktut Template
Grouping</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Lengths-and-Widths" accesskey="8">perlpacktut Lengths and
Widths</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Packing-and-Unpacking-C-Structures"
accesskey="9">perlpacktut Packing and Unpacking C
Structures</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Pack-Recipes">perlpacktut Pack
Recipes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Funnies-Section">perlpacktut Funnies
Section</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Authors">perlpacktut
Authors</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpacktut-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-DESCRIPTION" accesskey="n" rel="next">perlpacktut
DESCRIPTION</a>, Up: <a href="#perlpacktut" accesskey="u"
rel="up">perlpacktut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-49"></a>
-<h3 class="section">50.1 NAME</h3>
-
-<p>perlpacktut - tutorial on <code>pack</code> and <code>unpack</code>
-</p>
-<hr>
-<a name="perlpacktut-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-The-Basic-Principle" accesskey="n"
rel="next">perlpacktut The Basic Principle</a>, Previous: <a
href="#perlpacktut-NAME" accesskey="p" rel="prev">perlpacktut NAME</a>, Up: <a
href="#perlpacktut" accesskey="u" rel="up">perlpacktut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-48"></a>
-<h3 class="section">50.2 DESCRIPTION</h3>
-
-<p><code>pack</code> and <code>unpack</code> are two functions for
transforming data according
-to a user-defined template, between the guarded way Perl stores values
-and some well-defined representation as might be required in the
-environment of a Perl program. Unfortunately, they’re also two of
-the most misunderstood and most often overlooked functions that Perl
-provides. This tutorial will demystify them for you.
-</p>
-<hr>
-<a name="perlpacktut-The-Basic-Principle"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Packing-Text" accesskey="n" rel="next">perlpacktut
Packing Text</a>, Previous: <a href="#perlpacktut-DESCRIPTION" accesskey="p"
rel="prev">perlpacktut DESCRIPTION</a>, Up: <a href="#perlpacktut"
accesskey="u" rel="up">perlpacktut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-Basic-Principle"></a>
-<h3 class="section">50.3 The Basic Principle</h3>
-
-<p>Most programming languages don’t shelter the memory where variables
are
-stored. In C, for instance, you can take the address of some variable,
-and the <code>sizeof</code> operator tells you how many bytes are allocated to
-the variable. Using the address and the size, you may access the storage
-to your heart’s content.
-</p>
-<p>In Perl, you just can’t access memory at random, but the structural
and
-representational conversion provided by <code>pack</code> and
<code>unpack</code> is an
-excellent alternative. The <code>pack</code> function converts values to a byte
-sequence containing representations according to a given specification,
-the so-called "template" argument. <code>unpack</code> is the
reverse process,
-deriving some values from the contents of a string of bytes. (Be cautioned,
-however, that not all that has been packed together can be neatly unpacked -
-a very common experience as seasoned travellers are likely to confirm.)
-</p>
-<p>Why, you may ask, would you need a chunk of memory containing some values
-in binary representation? One good reason is input and output accessing
-some file, a device, or a network connection, whereby this binary
-representation is either forced on you or will give you some benefit
-in processing. Another cause is passing data to some system call that
-is not available as a Perl function: <code>syscall</code> requires you to
provide
-parameters stored in the way it happens in a C program. Even text processing
-(as shown in the next section) may be simplified with judicious usage
-of these two functions.
-</p>
-<p>To see how (un)packing works, we’ll start with a simple template
-code where the conversion is in low gear: between the contents of a byte
-sequence and a string of hexadecimal digits. Let’s use
<code>unpack</code>, since
-this is likely to remind you of a dump program, or some desperate last
-message unfortunate programs are wont to throw at you before they expire
-into the wild blue yonder. Assuming that the variable <code>$mem</code> holds
a
-sequence of bytes that we’d like to inspect without assuming anything
-about its meaning, we can write
-</p>
-<pre class="verbatim"> my( $hex ) = unpack( 'H*', $mem );
- print "$hex\n";
-</pre>
-<p>whereupon we might see something like this, with each pair of hex digits
-corresponding to a byte:
-</p>
-<pre class="verbatim"> 41204d414e204120504c414e20412043414e414c2050414e414d41
-</pre>
-<p>What was in this chunk of memory? Numbers, characters, or a mixture of
-both? Assuming that we’re on a computer where ASCII (or some similar)
-encoding is used: hexadecimal values in the range <code>0x40</code> -
<code>0x5A</code>
-indicate an uppercase letter, and <code>0x20</code> encodes a space. So we
might
-assume it is a piece of text, which some are able to read like a tabloid;
-but others will have to get hold of an ASCII table and relive that
-firstgrader feeling. Not caring too much about which way to read this,
-we note that <code>unpack</code> with the template code <code>H</code>
converts the contents
-of a sequence of bytes into the customary hexadecimal notation. Since
-"a sequence of" is a pretty vague indication of quantity,
<code>H</code> has been
-defined to convert just a single hexadecimal digit unless it is followed
-by a repeat count. An asterisk for the repeat count means to use whatever
-remains.
-</p>
-<p>The inverse operation - packing byte contents from a string of hexadecimal
-digits - is just as easily written. For instance:
-</p>
-<pre class="verbatim"> my $s = pack( 'H2' x 10, 30..39 );
- print "$s\n";
-</pre>
-<p>Since we feed a list of ten 2-digit hexadecimal strings to
<code>pack</code>, the
-pack template should contain ten pack codes. If this is run on a computer
-with ASCII character coding, it will print <code>0123456789</code>.
-</p>
-<hr>
-<a name="perlpacktut-Packing-Text"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Packing-Numbers" accesskey="n"
rel="next">perlpacktut Packing Numbers</a>, Previous: <a
href="#perlpacktut-The-Basic-Principle" accesskey="p" rel="prev">perlpacktut
The Basic Principle</a>, Up: <a href="#perlpacktut" accesskey="u"
rel="up">perlpacktut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Packing-Text"></a>
-<h3 class="section">50.4 Packing Text</h3>
-
-<p>Let’s suppose you’ve got to read in a data file like this:
-</p>
-<pre class="verbatim"> Date |Description |
Income|Expenditure
- 01/24/2001 Zed's Camel Emporium 1147.99
- 01/28/2001 Flea spray 24.99
- 01/29/2001 Camel rides to tourists 235.00
-</pre>
-<p>How do we do it? You might think first to use <code>split</code>; however,
since
-<code>split</code> collapses blank fields, you’ll never know whether a
record was
-income or expenditure. Oops. Well, you could always use <code>substr</code>:
-</p>
-<pre class="verbatim"> while (<>) {
- my $date = substr($_, 0, 11);
- my $desc = substr($_, 12, 27);
- my $income = substr($_, 40, 7);
- my $expend = substr($_, 52, 7);
- ...
- }
-</pre>
-<p>It’s not really a barrel of laughs, is it? In fact, it’s worse
than it
-may seem; the eagle-eyed may notice that the first field should only be
-10 characters wide, and the error has propagated right through the other
-numbers - which we’ve had to count by hand. So it’s error-prone as
well
-as horribly unfriendly.
-</p>
-<p>Or maybe we could use regular expressions:
-</p>
-<pre class="verbatim"> while (<>) {
- my($date, $desc, $income, $expend) =
- m|(\d\d/\d\d/\d{4}) (.{27}) (.{7})(.*)|;
- ...
- }
-</pre>
-<p>Urgh. Well, it’s a bit better, but - well, would you want to maintain
-that?
-</p>
-<p>Hey, isn’t Perl supposed to make this sort of thing easy? Well, it
does,
-if you use the right tools. <code>pack</code> and <code>unpack</code> are
designed to help
-you out when dealing with fixed-width data like the above. Let’s have a
-look at a solution with <code>unpack</code>:
-</p>
-<pre class="verbatim"> while (<>) {
- my($date, $desc, $income, $expend) = unpack("A10xA27xA7A*",
$_);
- ...
- }
-</pre>
-<p>That looks a bit nicer; but we’ve got to take apart that weird
template.
-Where did I pull that out of?
-</p>
-<p>OK, let’s have a look at some of our data again; in fact, we’ll
include
-the headers, and a handy ruler so we can keep track of where we are.
-</p>
-<pre class="verbatim"> 1 2 3 4 5
- 1234567890123456789012345678901234567890123456789012345678
- Date |Description | Income|Expenditure
- 01/28/2001 Flea spray 24.99
- 01/29/2001 Camel rides to tourists 235.00
-</pre>
-<p>From this, we can see that the date column stretches from column 1 to
-column 10 - ten characters wide. The <code>pack</code>-ese for
"character" is
-<code>A</code>, and ten of them are <code>A10</code>. So if we just wanted to
extract the
-dates, we could say this:
-</p>
-<pre class="verbatim"> my($date) = unpack("A10", $_);
-</pre>
-<p>OK, what’s next? Between the date and the description is a blank
column;
-we want to skip over that. The <code>x</code> template means "skip
forward", so we
-want one of those. Next, we have another batch of characters, from 12 to
-38. That’s 27 more characters, hence <code>A27</code>. (Don’t make
the fencepost
-error - there are 27 characters between 12 and 38, not 26. Count ’em!)
-</p>
-<p>Now we skip another character and pick up the next 7 characters:
-</p>
-<pre class="verbatim"> my($date,$description,$income) =
unpack("A10xA27xA7", $_);
-</pre>
-<p>Now comes the clever bit. Lines in our ledger which are just income and
-not expenditure might end at column 46. Hence, we don’t want to tell our
-<code>unpack</code> pattern that we <strong>need</strong> to find another 12
characters; we’ll
-just say "if there’s anything left, take it". As you might
guess from
-regular expressions, that’s what the <code>*</code> means: "use
everything
-remaining".
-</p>
-<ul>
-<li> Be warned, though, that unlike regular expressions, if the
<code>unpack</code>
-template doesn’t match the incoming data, Perl will scream and die.
-
-</li></ul>
-
-<p>Hence, putting it all together:
-</p>
-<pre class="verbatim"> my ($date, $description, $income, $expend) =
- unpack("A10xA27xA7xA*", $_);
-</pre>
-<p>Now, that’s our data parsed. I suppose what we might want to do now is
-total up our income and expenditure, and add another line to the end of
-our ledger - in the same format - saying how much we’ve brought in and
-how much we’ve spent:
-</p>
-<pre class="verbatim"> while (<>) {
- my ($date, $desc, $income, $expend) =
- unpack("A10xA27xA7xA*", $_);
- $tot_income += $income;
- $tot_expend += $expend;
- }
-
- $tot_income = sprintf("%.2f", $tot_income); # Get them into
- $tot_expend = sprintf("%.2f", $tot_expend); #
"financial" format
-
- $date = POSIX::strftime("%m/%d/%Y", localtime);
-
- # OK, let's go:
-
- print pack("A10xA27xA7xA*", $date, "Totals",
- $tot_income, $tot_expend);
-</pre>
-<p>Oh, hmm. That didn’t quite work. Let’s see what happened:
-</p>
-<pre class="verbatim"> 01/24/2001 Zed's Camel Emporium
1147.99
- 01/28/2001 Flea spray 24.99
- 01/29/2001 Camel rides to tourists 1235.00
- 03/23/2001Totals 1235.001172.98
-</pre>
-<p>OK, it’s a start, but what happened to the spaces? We put
<code>x</code>, didn’t
-we? Shouldn’t it skip forward? Let’s look at what ‘perlfunc
pack’ says:
-</p>
-<pre class="verbatim"> x A null byte.
-</pre>
-<p>Urgh. No wonder. There’s a big difference between "a null
byte",
-character zero, and "a space", character 32. Perl’s put
something
-between the date and the description - but unfortunately, we can’t see
-it!
-</p>
-<p>What we actually need to do is expand the width of the fields. The
<code>A</code>
-format pads any non-existent characters with spaces, so we can use the
-additional spaces to line up our fields, like this:
-</p>
-<pre class="verbatim"> print pack("A11 A28 A8 A*", $date,
"Totals",
- $tot_income, $tot_expend);
-</pre>
-<p>(Note that you can put spaces in the template to make it more readable,
-but they don’t translate to spaces in the output.) Here’s what we
got
-this time:
-</p>
-<pre class="verbatim"> 01/24/2001 Zed's Camel Emporium
1147.99
- 01/28/2001 Flea spray 24.99
- 01/29/2001 Camel rides to tourists 1235.00
- 03/23/2001 Totals 1235.00 1172.98
-</pre>
-<p>That’s a bit better, but we still have that last column which needs to
-be moved further over. There’s an easy way to fix this up:
-unfortunately, we can’t get <code>pack</code> to right-justify our
fields, but we
-can get <code>sprintf</code> to do it:
-</p>
-<pre class="verbatim"> $tot_income = sprintf("%.2f",
$tot_income);
- $tot_expend = sprintf("%12.2f", $tot_expend);
- $date = POSIX::strftime("%m/%d/%Y", localtime);
- print pack("A11 A28 A8 A*", $date, "Totals",
- $tot_income, $tot_expend);
-</pre>
-<p>This time we get the right answer:
-</p>
-<pre class="verbatim"> 01/28/2001 Flea spray
24.99
- 01/29/2001 Camel rides to tourists 1235.00
- 03/23/2001 Totals 1235.00 1172.98
-</pre>
-<p>So that’s how we consume and produce fixed-width data. Let’s
recap what
-we’ve seen of <code>pack</code> and <code>unpack</code> so far:
-</p>
-<ul>
-<li> Use <code>pack</code> to go from several pieces of data to one fixed-width
-version; use <code>unpack</code> to turn a fixed-width-format string into
several
-pieces of data.
-
-</li><li> The pack format <code>A</code> means "any character"; if
you’re <code>pack</code>ing and
-you’ve run out of things to pack, <code>pack</code> will fill the rest
up with
-spaces.
-
-</li><li> <code>x</code> means "skip a byte" when
<code>unpack</code>ing; when <code>pack</code>ing, it means
-"introduce a null byte" - that’s probably not what you mean if
you’re
-dealing with plain text.
-
-</li><li> You can follow the formats with numbers to say how many characters
-should be affected by that format: <code>A12</code> means "take 12
characters";
-<code>x6</code> means "skip 6 bytes" or "character 0, 6
times".
-
-</li><li> Instead of a number, you can use <code>*</code> to mean
"consume everything else
-left".
-
-<p><strong>Warning</strong>: when packing multiple pieces of data,
<code>*</code> only means
-"consume all of the current piece of data". That’s to say
-</p>
-<pre class="verbatim"> pack("A*A*", $one, $two)
-</pre>
-<p>packs all of <code>$one</code> into the first <code>A*</code> and then all
of <code>$two</code> into
-the second. This is a general principle: each format character
-corresponds to one piece of data to be <code>pack</code>ed.
-</p>
-</li></ul>
-
-<hr>
-<a name="perlpacktut-Packing-Numbers"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Exotic-Templates" accesskey="n"
rel="next">perlpacktut Exotic Templates</a>, Previous: <a
href="#perlpacktut-Packing-Text" accesskey="p" rel="prev">perlpacktut Packing
Text</a>, Up: <a href="#perlpacktut" accesskey="u" rel="up">perlpacktut</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Packing-Numbers"></a>
-<h3 class="section">50.5 Packing Numbers</h3>
-
-<p>So much for textual data. Let’s get onto the meaty stuff that
<code>pack</code>
-and <code>unpack</code> are best at: handling binary formats for numbers.
There is,
-of course, not just one binary format - life would be too simple - but
-Perl will do all the finicky labor for you.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlpacktut-Integers"
accesskey="1">perlpacktut Integers</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Unpacking-a-Stack-Frame" accesskey="2">perlpacktut Unpacking
a Stack Frame</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-How-to-Eat-an-Egg-on-a-Net" accesskey="3">perlpacktut How to
Eat an Egg on a Net</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Byte_002dorder-modifiers" accesskey="4">perlpacktut
Byte-order modifiers</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Floating-point-Numbers" accesskey="5">perlpacktut Floating
point Numbers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpacktut-Integers"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Unpacking-a-Stack-Frame" accesskey="n"
rel="next">perlpacktut Unpacking a Stack Frame</a>, Up: <a
href="#perlpacktut-Packing-Numbers" accesskey="u" rel="up">perlpacktut Packing
Numbers</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Integers"></a>
-<h4 class="subsection">50.5.1 Integers</h4>
-
-<p>Packing and unpacking numbers implies conversion to and from some
-<em>specific</em> binary representation. Leaving floating point numbers
-aside for the moment, the salient properties of any such representation
-are:
-</p>
-<ul>
-<li> the number of bytes used for storing the integer,
-
-</li><li> whether the contents are interpreted as a signed or unsigned number,
-
-</li><li> the byte ordering: whether the first byte is the least or most
-significant byte (or: little-endian or big-endian, respectively).
-
-</li></ul>
-
-<p>So, for instance, to pack 20302 to a signed 16 bit integer in your
-computer’s representation you write
-</p>
-<pre class="verbatim"> my $ps = pack( 's', 20302 );
-</pre>
-<p>Again, the result is a string, now containing 2 bytes. If you print
-this string (which is, generally, not recommended) you might see
-<code>ON</code> or <code>NO</code> (depending on your system’s byte
ordering) - or something
-entirely different if your computer doesn’t use ASCII character encoding.
-Unpacking <code>$ps</code> with the same template returns the original integer
value:
-</p>
-<pre class="verbatim"> my( $s ) = unpack( 's', $ps );
-</pre>
-<p>This is true for all numeric template codes. But don’t expect
miracles:
-if the packed value exceeds the allotted byte capacity, high order bits
-are silently discarded, and unpack certainly won’t be able to pull them
-back out of some magic hat. And, when you pack using a signed template
-code such as <code>s</code>, an excess value may result in the sign bit
-getting set, and unpacking this will smartly return a negative value.
-</p>
-<p>16 bits won’t get you too far with integers, but there is
<code>l</code> and <code>L</code>
-for signed and unsigned 32-bit integers. And if this is not enough and
-your system supports 64 bit integers you can push the limits much closer
-to infinity with pack codes <code>q</code> and <code>Q</code>. A notable
exception is provided
-by pack codes <code>i</code> and <code>I</code> for signed and unsigned
integers of the
-"local custom" variety: Such an integer will take up as many bytes as
-a local C compiler returns for <code>sizeof(int)</code>, but it’ll use
<em>at least</em>
-32 bits.
-</p>
-<p>Each of the integer pack codes <code>sSlLqQ</code> results in a fixed
number of bytes,
-no matter where you execute your program. This may be useful for some
-applications, but it does not provide for a portable way to pass data
-structures between Perl and C programs (bound to happen when you call
-XS extensions or the Perl function <code>syscall</code>), or when you read or
-write binary files. What you’ll need in this case are template codes that
-depend on what your local C compiler compiles when you code <code>short</code>
or
-<code>unsigned long</code>, for instance. These codes and their corresponding
-byte lengths are shown in the table below. Since the C standard leaves
-much leeway with respect to the relative sizes of these data types, actual
-values may vary, and that’s why the values are given as expressions in
-C and Perl. (If you’d like to use values from <code>%Config</code> in
your program
-you have to import it with <code>use Config</code>.)
-</p>
-<pre class="verbatim"> signed unsigned byte length in C byte length in
Perl
- s! S! sizeof(short) $Config{shortsize}
- i! I! sizeof(int) $Config{intsize}
- l! L! sizeof(long) $Config{longsize}
- q! Q! sizeof(long long) $Config{longlongsize}
-</pre>
-<p>The <code>i!</code> and <code>I!</code> codes aren’t different from
<code>i</code> and <code>I</code>; they are
-tolerated for completeness’ sake.
-</p>
-<hr>
-<a name="perlpacktut-Unpacking-a-Stack-Frame"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-How-to-Eat-an-Egg-on-a-Net" accesskey="n"
rel="next">perlpacktut How to Eat an Egg on a Net</a>, Previous: <a
href="#perlpacktut-Integers" accesskey="p" rel="prev">perlpacktut Integers</a>,
Up: <a href="#perlpacktut-Packing-Numbers" accesskey="u" rel="up">perlpacktut
Packing Numbers</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Unpacking-a-Stack-Frame"></a>
-<h4 class="subsection">50.5.2 Unpacking a Stack Frame</h4>
-
-<p>Requesting a particular byte ordering may be necessary when you work with
-binary data coming from some specific architecture whereas your program could
-run on a totally different system. As an example, assume you have 24 bytes
-containing a stack frame as it happens on an Intel 8086:
-</p>
-<pre class="verbatim"> +---------+ +----+----+
+---------+
- TOS: | IP | TOS+4:| FL | FH | FLAGS TOS+14:| SI |
- +---------+ +----+----+ +---------+
- | CS | | AL | AH | AX | DI |
- +---------+ +----+----+ +---------+
- | BL | BH | BX | BP |
- +----+----+ +---------+
- | CL | CH | CX | DS |
- +----+----+ +---------+
- | DL | DH | DX | ES |
- +----+----+ +---------+
-</pre>
-<p>First, we note that this time-honored 16-bit CPU uses little-endian order,
-and that’s why the low order byte is stored at the lower address. To
-unpack such a (unsigned) short we’ll have to use code <code>v</code>. A
repeat
-count unpacks all 12 shorts:
-</p>
-<pre class="verbatim"> my( $ip, $cs, $flags, $ax, $bx, $cd, $dx, $si, $di,
$bp, $ds, $es ) =
- unpack( 'v12', $frame );
-</pre>
-<p>Alternatively, we could have used <code>C</code> to unpack the individually
-accessible byte registers FL, FH, AL, AH, etc.:
-</p>
-<pre class="verbatim"> my( $fl, $fh, $al, $ah, $bl, $bh, $cl, $ch, $dl, $dh
) =
- unpack( 'C10', substr( $frame, 4, 10 ) );
-</pre>
-<p>It would be nice if we could do this in one fell swoop: unpack a short,
-back up a little, and then unpack 2 bytes. Since Perl <em>is</em> nice, it
-proffers the template code <code>X</code> to back up one byte. Putting this all
-together, we may now write:
-</p>
-<pre class="verbatim"> my( $ip, $cs,
- $flags,$fl,$fh,
- $ax,$al,$ah, $bx,$bl,$bh, $cx,$cl,$ch, $dx,$dl,$dh,
- $si, $di, $bp, $ds, $es ) =
- unpack( 'v2' . ('vXXCC' x 5) . 'v5', $frame );
-</pre>
-<p>(The clumsy construction of the template can be avoided - just read on!)
-</p>
-<p>We’ve taken some pains to construct the template so that it matches
-the contents of our frame buffer. Otherwise we’d either get undefined
values,
-or <code>unpack</code> could not unpack all. If <code>pack</code> runs out of
items, it will
-supply null strings (which are coerced into zeroes whenever the pack code
-says so).
-</p>
-<hr>
-<a name="perlpacktut-How-to-Eat-an-Egg-on-a-Net"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Byte_002dorder-modifiers" accesskey="n"
rel="next">perlpacktut Byte-order modifiers</a>, Previous: <a
href="#perlpacktut-Unpacking-a-Stack-Frame" accesskey="p"
rel="prev">perlpacktut Unpacking a Stack Frame</a>, Up: <a
href="#perlpacktut-Packing-Numbers" accesskey="u" rel="up">perlpacktut Packing
Numbers</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="How-to-Eat-an-Egg-on-a-Net"></a>
-<h4 class="subsection">50.5.3 How to Eat an Egg on a Net</h4>
-
-<p>The pack code for big-endian (high order byte at the lowest address) is
-<code>n</code> for 16 bit and <code>N</code> for 32 bit integers. You use
these codes
-if you know that your data comes from a compliant architecture, but,
-surprisingly enough, you should also use these pack codes if you
-exchange binary data, across the network, with some system that you
-know next to nothing about. The simple reason is that this
-order has been chosen as the <em>network order</em>, and all standard-fearing
-programs ought to follow this convention. (This is, of course, a stern
-backing for one of the Lilliputian parties and may well influence the
-political development there.) So, if the protocol expects you to send
-a message by sending the length first, followed by just so many bytes,
-you could write:
-</p>
-<pre class="verbatim"> my $buf = pack( 'N', length( $msg ) ) . $msg;
-</pre>
-<p>or even:
-</p>
-<pre class="verbatim"> my $buf = pack( 'NA*', length( $msg ), $msg );
-</pre>
-<p>and pass <code>$buf</code> to your send routine. Some protocols demand that
the
-count should include the length of the count itself: then just add 4
-to the data length. (But make sure to read <a
href="#perlpacktut-Lengths-and-Widths">Lengths and Widths</a> before
-you really code this!)
-</p>
-<hr>
-<a name="perlpacktut-Byte_002dorder-modifiers"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Floating-point-Numbers" accesskey="n"
rel="next">perlpacktut Floating point Numbers</a>, Previous: <a
href="#perlpacktut-How-to-Eat-an-Egg-on-a-Net" accesskey="p"
rel="prev">perlpacktut How to Eat an Egg on a Net</a>, Up: <a
href="#perlpacktut-Packing-Numbers" accesskey="u" rel="up">perlpacktut Packing
Numbers</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Byte_002dorder-modifiers"></a>
-<h4 class="subsection">50.5.4 Byte-order modifiers</h4>
-
-<p>In the previous sections we’ve learned how to use <code>n</code>,
<code>N</code>, <code>v</code> and
-<code>V</code> to pack and unpack integers with big- or little-endian
byte-order.
-While this is nice, it’s still rather limited because it leaves out all
-kinds of signed integers as well as 64-bit integers. For example, if you
-wanted to unpack a sequence of signed big-endian 16-bit integers in a
-platform-independent way, you would have to write:
-</p>
-<pre class="verbatim"> my @data = unpack 's*', pack 'S*', unpack 'n*', $buf;
-</pre>
-<p>This is ugly. As of Perl 5.9.2, there’s a much nicer way to express
your
-desire for a certain byte-order: the <code>></code> and <code><</code>
modifiers.
-<code>></code> is the big-endian modifier, while <code><</code> is the
little-endian
-modifier. Using them, we could rewrite the above code as:
-</p>
-<pre class="verbatim"> my @data = unpack 's>*', $buf;
-</pre>
-<p>As you can see, the "big end" of the arrow touches the
<code>s</code>, which is a
-nice way to remember that <code>></code> is the big-endian modifier. The
same
-obviously works for <code><</code>, where the "little end"
touches the code.
-</p>
-<p>You will probably find these modifiers even more useful if you have
-to deal with big- or little-endian C structures. Be sure to read
-<a href="#perlpacktut-Packing-and-Unpacking-C-Structures">Packing and
Unpacking C Structures</a> for more on that.
-</p>
-<hr>
-<a name="perlpacktut-Floating-point-Numbers"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlpacktut-Byte_002dorder-modifiers" accesskey="p"
rel="prev">perlpacktut Byte-order modifiers</a>, Up: <a
href="#perlpacktut-Packing-Numbers" accesskey="u" rel="up">perlpacktut Packing
Numbers</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Floating-point-Numbers"></a>
-<h4 class="subsection">50.5.5 Floating point Numbers</h4>
-
-<p>For packing floating point numbers you have the choice between the
-pack codes <code>f</code>, <code>d</code>, <code>F</code> and <code>D</code>.
<code>f</code> and <code>d</code> pack into (or unpack
-from) single-precision or double-precision representation as it is provided
-by your system. If your systems supports it, <code>D</code> can be used to
pack and
-unpack (<code>long double</code>) values, which can offer even more resolution
-than <code>f</code> or <code>d</code>. <strong>Note that there are different
long double formats.</strong>
-</p>
-<p><code>F</code> packs an <code>NV</code>, which is the floating point type
used by Perl
-internally.
-</p>
-<p>There is no such thing as a network representation for reals, so if
-you want to send your real numbers across computer boundaries, you’d
-better stick to text representation, possibly using the hexadecimal
-float format (avoiding the decimal conversion loss), unless you’re
-absolutely sure what’s on the other end of the line. For the even more
-adventuresome, you can use the byte-order modifiers from the previous
-section also on floating point codes.
-</p>
-<hr>
-<a name="perlpacktut-Exotic-Templates"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Template-Grouping" accesskey="n"
rel="next">perlpacktut Template Grouping</a>, Previous: <a
href="#perlpacktut-Packing-Numbers" accesskey="p" rel="prev">perlpacktut
Packing Numbers</a>, Up: <a href="#perlpacktut" accesskey="u"
rel="up">perlpacktut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Exotic-Templates"></a>
-<h3 class="section">50.6 Exotic Templates</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlpacktut-Bit-Strings"
accesskey="1">perlpacktut Bit Strings</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpacktut-Uuencoding"
accesskey="2">perlpacktut Uuencoding</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpacktut-Doing-Sums"
accesskey="3">perlpacktut Doing Sums</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpacktut-Unicode"
accesskey="4">perlpacktut Unicode</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Another-Portable-Binary-Encoding" accesskey="5">perlpacktut
Another Portable Binary Encoding</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpacktut-Bit-Strings"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Uuencoding" accesskey="n" rel="next">perlpacktut
Uuencoding</a>, Up: <a href="#perlpacktut-Exotic-Templates" accesskey="u"
rel="up">perlpacktut Exotic Templates</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Bit-Strings"></a>
-<h4 class="subsection">50.6.1 Bit Strings</h4>
-
-<p>Bits are the atoms in the memory world. Access to individual bits may
-have to be used either as a last resort or because it is the most
-convenient way to handle your data. Bit string (un)packing converts
-between strings containing a series of <code>0</code> and <code>1</code>
characters and
-a sequence of bytes each containing a group of 8 bits. This is almost
-as simple as it sounds, except that there are two ways the contents of
-a byte may be written as a bit string. Let’s have a look at an annotated
-byte:
-</p>
-<pre class="verbatim"> 7 6 5 4 3 2 1 0
- +-----------------+
- | 1 0 0 0 1 1 0 0 |
- +-----------------+
- MSB LSB
-</pre>
-<p>It’s egg-eating all over again: Some think that as a bit string this
should
-be written "10001100" i.e. beginning with the most significant bit,
others
-insist on "00110001". Well, Perl isn’t biased, so that’s
why we have two bit
-string codes:
-</p>
-<pre class="verbatim"> $byte = pack( 'B8', '10001100' ); # start with MSB
- $byte = pack( 'b8', '00110001' ); # start with LSB
-</pre>
-<p>It is not possible to pack or unpack bit fields - just integral bytes.
-<code>pack</code> always starts at the next byte boundary and "rounds
up" to the
-next multiple of 8 by adding zero bits as required. (If you do want bit
-fields, there is ‘perlfunc vec’. Or you could implement bit field
-handling at the character string level, using split, substr, and
-concatenation on unpacked bit strings.)
-</p>
-<p>To illustrate unpacking for bit strings, we’ll decompose a simple
-status register (a "-" stands for a "reserved" bit):
-</p>
-<pre class="verbatim"> +-----------------+-----------------+
- | S Z - A - P - C | - - - - O D I T |
- +-----------------+-----------------+
- MSB LSB MSB LSB
-</pre>
-<p>Converting these two bytes to a string can be done with the unpack
-template <code>'b16'</code>. To obtain the individual bit values from the bit
-string we use <code>split</code> with the "empty" separator pattern
which dissects
-into individual characters. Bit values from the "reserved" positions
are
-simply assigned to <code>undef</code>, a convenient notation for "I
don’t care where
-this goes".
-</p>
-<pre class="verbatim"> ($carry, undef, $parity, undef, $auxcarry, undef,
$zero, $sign,
- $trace, $interrupt, $direction, $overflow) =
- split( //, unpack( 'b16', $status ) );
-</pre>
-<p>We could have used an unpack template <code>'b12'</code> just as well,
since the
-last 4 bits can be ignored anyway.
-</p>
-<hr>
-<a name="perlpacktut-Uuencoding"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Doing-Sums" accesskey="n" rel="next">perlpacktut
Doing Sums</a>, Previous: <a href="#perlpacktut-Bit-Strings" accesskey="p"
rel="prev">perlpacktut Bit Strings</a>, Up: <a
href="#perlpacktut-Exotic-Templates" accesskey="u" rel="up">perlpacktut Exotic
Templates</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Uuencoding"></a>
-<h4 class="subsection">50.6.2 Uuencoding</h4>
-
-<p>Another odd-man-out in the template alphabet is <code>u</code>, which packs
a
-"uuencoded string". ("uu" is short for Unix-to-Unix.)
Chances are that
-you won’t ever need this encoding technique which was invented to
overcome
-the shortcomings of old-fashioned transmission mediums that do not support
-other than simple ASCII data. The essential recipe is simple: Take three
-bytes, or 24 bits. Split them into 4 six-packs, adding a space (0x20) to
-each. Repeat until all of the data is blended. Fold groups of 4 bytes into
-lines no longer than 60 and garnish them in front with the original byte count
-(incremented by 0x20) and a <code>"\n"</code> at the end. - The
<code>pack</code> chef will
-prepare this for you, a la minute, when you select pack code <code>u</code> on
the menu:
-</p>
-<pre class="verbatim"> my $uubuf = pack( 'u', $bindat );
-</pre>
-<p>A repeat count after <code>u</code> sets the number of bytes to put into an
-uuencoded line, which is the maximum of 45 by default, but could be
-set to some (smaller) integer multiple of three. <code>unpack</code> simply
ignores
-the repeat count.
-</p>
-<hr>
-<a name="perlpacktut-Doing-Sums"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Unicode" accesskey="n" rel="next">perlpacktut
Unicode</a>, Previous: <a href="#perlpacktut-Uuencoding" accesskey="p"
rel="prev">perlpacktut Uuencoding</a>, Up: <a
href="#perlpacktut-Exotic-Templates" accesskey="u" rel="up">perlpacktut Exotic
Templates</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Doing-Sums"></a>
-<h4 class="subsection">50.6.3 Doing Sums</h4>
-
-<p>An even stranger template code is <code>%</code><<em>number</em>>.
First, because
-it’s used as a prefix to some other template code. Second, because it
-cannot be used in <code>pack</code> at all, and third, in <code>unpack</code>,
doesn’t return the
-data as defined by the template code it precedes. Instead it’ll give you
an
-integer of <em>number</em> bits that is computed from the data value by
-doing sums. For numeric unpack codes, no big feat is achieved:
-</p>
-<pre class="verbatim"> my $buf = pack( 'iii', 100, 20, 3 );
- print unpack( '%32i3', $buf ), "\n"; # prints 123
-</pre>
-<p>For string values, <code>%</code> returns the sum of the byte values saving
-you the trouble of a sum loop with <code>substr</code> and <code>ord</code>:
-</p>
-<pre class="verbatim"> print unpack( '%32A*', "\x01\x10" ),
"\n"; # prints 17
-</pre>
-<p>Although the <code>%</code> code is documented as returning a
"checksum":
-don’t put your trust in such values! Even when applied to a small number
-of bytes, they won’t guarantee a noticeable Hamming distance.
-</p>
-<p>In connection with <code>b</code> or <code>B</code>, <code>%</code> simply
adds bits, and this can be put
-to good use to count set bits efficiently:
-</p>
-<pre class="verbatim"> my $bitcount = unpack( '%32b*', $mask );
-</pre>
-<p>And an even parity bit can be determined like this:
-</p>
-<pre class="verbatim"> my $evenparity = unpack( '%1b*', $mask );
-</pre>
-<hr>
-<a name="perlpacktut-Unicode"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Another-Portable-Binary-Encoding" accesskey="n"
rel="next">perlpacktut Another Portable Binary Encoding</a>, Previous: <a
href="#perlpacktut-Doing-Sums" accesskey="p" rel="prev">perlpacktut Doing
Sums</a>, Up: <a href="#perlpacktut-Exotic-Templates" accesskey="u"
rel="up">perlpacktut Exotic Templates</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode"></a>
-<h4 class="subsection">50.6.4 Unicode</h4>
-
-<p>Unicode is a character set that can represent most characters in most of
-the world’s languages, providing room for over one million different
-characters. Unicode 3.1 specifies 94,140 characters: The Basic Latin
-characters are assigned to the numbers 0 - 127. The Latin-1 Supplement with
-characters that are used in several European languages is in the next
-range, up to 255. After some more Latin extensions we find the character
-sets from languages using non-Roman alphabets, interspersed with a
-variety of symbol sets such as currency symbols, Zapf Dingbats or Braille.
-(You might want to visit <a
href="http://www.unicode.org/";>http://www.unicode.org/</a> for a look at some of
-them - my personal favourites are Telugu and Kannada.)
-</p>
-<p>The Unicode character sets associates characters with integers. Encoding
-these numbers in an equal number of bytes would more than double the
-requirements for storing texts written in Latin alphabets.
-The UTF-8 encoding avoids this by storing the most common (from a western
-point of view) characters in a single byte while encoding the rarer
-ones in three or more bytes.
-</p>
-<p>Perl uses UTF-8, internally, for most Unicode strings.
-</p>
-<p>So what has this got to do with <code>pack</code>? Well, if you want to
compose a
-Unicode string (that is internally encoded as UTF-8), you can do so by
-using template code <code>U</code>. As an example, let’s produce the
Euro currency
-symbol (code number 0x20AC):
-</p>
-<pre class="verbatim"> $UTF8{Euro} = pack( 'U', 0x20AC );
- # Equivalent to: $UTF8{Euro} = "\x{20ac}";
-</pre>
-<p>Inspecting <code>$UTF8{Euro}</code> shows that it contains 3 bytes:
-"\xe2\x82\xac". However, it contains only 1 character, number 0x20AC.
-The round trip can be completed with <code>unpack</code>:
-</p>
-<pre class="verbatim"> $Unicode{Euro} = unpack( 'U', $UTF8{Euro} );
-</pre>
-<p>Unpacking using the <code>U</code> template code also works on UTF-8
encoded byte
-strings.
-</p>
-<p>Usually you’ll want to pack or unpack UTF-8 strings:
-</p>
-<pre class="verbatim"> # pack and unpack the Hebrew alphabet
- my $alefbet = pack( 'U*', 0x05d0..0x05ea );
- my @hebrew = unpack( 'U*', $utf );
-</pre>
-<p>Please note: in the general case, you’re better off using
-Encode::decode_utf8 to decode a UTF-8 encoded byte string to a Perl
-Unicode string, and Encode::encode_utf8 to encode a Perl Unicode string
-to UTF-8 bytes. These functions provide means of handling invalid byte
-sequences and generally have a friendlier interface.
-</p>
-<hr>
-<a name="perlpacktut-Another-Portable-Binary-Encoding"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlpacktut-Unicode" accesskey="p" rel="prev">perlpacktut
Unicode</a>, Up: <a href="#perlpacktut-Exotic-Templates" accesskey="u"
rel="up">perlpacktut Exotic Templates</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Another-Portable-Binary-Encoding"></a>
-<h4 class="subsection">50.6.5 Another Portable Binary Encoding</h4>
-
-<p>The pack code <code>w</code> has been added to support a portable binary
data
-encoding scheme that goes way beyond simple integers. (Details can
-be found at <a href="http://Casbah.org/";>http://Casbah.org/</a>, the Scarab
project.) A BER (Binary Encoded
-Representation) compressed unsigned integer stores base 128
-digits, most significant digit first, with as few digits as possible.
-Bit eight (the high bit) is set on each byte except the last. There
-is no size limit to BER encoding, but Perl won’t go to extremes.
-</p>
-<pre class="verbatim"> my $berbuf = pack( 'w*', 1, 128, 128+1, 128*128+127 );
-</pre>
-<p>A hex dump of <code>$berbuf</code>, with spaces inserted at the right
places,
-shows 01 8100 8101 81807F. Since the last byte is always less than
-128, <code>unpack</code> knows where to stop.
-</p>
-<hr>
-<a name="perlpacktut-Template-Grouping"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Lengths-and-Widths" accesskey="n"
rel="next">perlpacktut Lengths and Widths</a>, Previous: <a
href="#perlpacktut-Exotic-Templates" accesskey="p" rel="prev">perlpacktut
Exotic Templates</a>, Up: <a href="#perlpacktut" accesskey="u"
rel="up">perlpacktut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Template-Grouping"></a>
-<h3 class="section">50.7 Template Grouping</h3>
-
-<p>Prior to Perl 5.8, repetitions of templates had to be made by
-<code>x</code>-multiplication of template strings. Now there is a better way as
-we may use the pack codes <code>(</code> and <code>)</code> combined with a
repeat count.
-The <code>unpack</code> template from the Stack Frame example can simply
-be written like this:
-</p>
-<pre class="verbatim"> unpack( 'v2 (vXXCC)5 v5', $frame )
-</pre>
-<p>Let’s explore this feature a little more. We’ll begin with the
equivalent of
-</p>
-<pre class="verbatim"> join( '', map( substr( $_, 0, 1 ), @str ) )
-</pre>
-<p>which returns a string consisting of the first character from each string.
-Using pack, we can write
-</p>
-<pre class="verbatim"> pack( '(A)'address@hidden, @str )
-</pre>
-<p>or, because a repeat count <code>*</code> means "repeat as often as
required",
-simply
-</p>
-<pre class="verbatim"> pack( '(A)*', @str )
-</pre>
-<p>(Note that the template <code>A*</code> would only have packed
<code>$str[0]</code> in full
-length.)
-</p>
-<p>To pack dates stored as triplets ( day, month, year ) in an array
<code>@dates</code>
-into a sequence of byte, byte, short integer we can write
-</p>
-<pre class="verbatim"> $pd = pack( '(CCS)*', map( @$_, @dates ) );
-</pre>
-<p>To swap pairs of characters in a string (with even length) one could use
-several techniques. First, let’s use <code>x</code> and <code>X</code>
to skip forward and back:
-</p>
-<pre class="verbatim"> $s = pack( '(A)*', unpack( '(xAXXAx)*', $s ) );
-</pre>
-<p>We can also use <code>@</code> to jump to an offset, with 0 being the
position where
-we were when the last <code>(</code> was encountered:
-</p>
-<pre class="verbatim"> $s = pack( '(A)*', unpack( '(@1A @0A @2)*', $s ) );
-</pre>
-<p>Finally, there is also an entirely different approach by unpacking big
-endian shorts and packing them in the reverse byte order:
-</p>
-<pre class="verbatim"> $s = pack( '(v)*', unpack( '(n)*', $s );
-</pre>
-<hr>
-<a name="perlpacktut-Lengths-and-Widths"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Packing-and-Unpacking-C-Structures" accesskey="n"
rel="next">perlpacktut Packing and Unpacking C Structures</a>, Previous: <a
href="#perlpacktut-Template-Grouping" accesskey="p" rel="prev">perlpacktut
Template Grouping</a>, Up: <a href="#perlpacktut" accesskey="u"
rel="up">perlpacktut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Lengths-and-Widths"></a>
-<h3 class="section">50.8 Lengths and Widths</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlpacktut-String-Lengths"
accesskey="1">perlpacktut String Lengths</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Dynamic-Templates" accesskey="2">perlpacktut Dynamic
Templates</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Counting-Repetitions" accesskey="3">perlpacktut Counting
Repetitions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpacktut-Intel-HEX"
accesskey="4">perlpacktut Intel HEX</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpacktut-String-Lengths"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Dynamic-Templates" accesskey="n"
rel="next">perlpacktut Dynamic Templates</a>, Up: <a
href="#perlpacktut-Lengths-and-Widths" accesskey="u" rel="up">perlpacktut
Lengths and Widths</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="String-Lengths"></a>
-<h4 class="subsection">50.8.1 String Lengths</h4>
-
-<p>In the previous section we’ve seen a network message that was
constructed
-by prefixing the binary message length to the actual message. You’ll find
-that packing a length followed by so many bytes of data is a
-frequently used recipe since appending a null byte won’t work
-if a null byte may be part of the data. Here is an example where both
-techniques are used: after two null terminated strings with source and
-destination address, a Short Message (to a mobile phone) is sent after
-a length byte:
-</p>
-<pre class="verbatim"> my $msg = pack( 'Z*Z*CA*', $src, $dst, length( $sm ),
$sm );
-</pre>
-<p>Unpacking this message can be done with the same template:
-</p>
-<pre class="verbatim"> ( $src, $dst, $len, $sm ) = unpack( 'Z*Z*CA*', $msg );
-</pre>
-<p>There’s a subtle trap lurking in the offing: Adding another field
after
-the Short Message (in variable <code>$sm</code>) is all right when packing,
but this
-cannot be unpacked naively:
-</p>
-<pre class="verbatim"> # pack a message
- my $msg = pack( 'Z*Z*CA*C', $src, $dst, length( $sm ), $sm, $prio );
-
- # unpack fails - $prio remains undefined!
- ( $src, $dst, $len, $sm, $prio ) = unpack( 'Z*Z*CA*C', $msg );
-</pre>
-<p>The pack code <code>A*</code> gobbles up all remaining bytes, and
<code>$prio</code> remains
-undefined! Before we let disappointment dampen the morale: Perl’s got
-the trump card to make this trick too, just a little further up the sleeve.
-Watch this:
-</p>
-<pre class="verbatim"> # pack a message: ASCIIZ, ASCIIZ, length/string, byte
- my $msg = pack( 'Z* Z* C/A* C', $src, $dst, $sm, $prio );
-
- # unpack
- ( $src, $dst, $sm, $prio ) = unpack( 'Z* Z* C/A* C', $msg );
-</pre>
-<p>Combining two pack codes with a slash (<code>/</code>) associates them with
a single
-value from the argument list. In <code>pack</code>, the length of the argument
is
-taken and packed according to the first code while the argument itself
-is added after being converted with the template code after the slash.
-This saves us the trouble of inserting the <code>length</code> call, but it is
-in <code>unpack</code> where we really score: The value of the length byte
marks the
-end of the string to be taken from the buffer. Since this combination
-doesn’t make sense except when the second pack code isn’t
<code>a*</code>, <code>A*</code>
-or <code>Z*</code>, Perl won’t let you.
-</p>
-<p>The pack code preceding <code>/</code> may be anything that’s fit to
represent a
-number: All the numeric binary pack codes, and even text codes such as
-<code>A4</code> or <code>Z*</code>:
-</p>
-<pre class="verbatim"> # pack/unpack a string preceded by its length in ASCII
- my $buf = pack( 'A4/A*', "Humpty-Dumpty" );
- # unpack $buf: '13 Humpty-Dumpty'
- my $txt = unpack( 'A4/A*', $buf );
-</pre>
-<p><code>/</code> is not implemented in Perls before 5.6, so if your code is
required to
-work on older Perls you’ll need to <code>unpack( 'Z* Z* C')</code> to
get the length,
-then use it to make a new unpack string. For example
-</p>
-<pre class="verbatim"> # pack a message: ASCIIZ, ASCIIZ, length, string, byte
- # (5.005 compatible)
- my $msg = pack( 'Z* Z* C A* C', $src, $dst, length $sm, $sm, $prio );
-
- # unpack
- ( undef, undef, $len) = unpack( 'Z* Z* C', $msg );
- ($src, $dst, $sm, $prio) = unpack ( "Z* Z* x A$len C", $msg );
-</pre>
-<p>But that second <code>unpack</code> is rushing ahead. It isn’t using
a simple literal
-string for the template. So maybe we should introduce...
-</p>
-<hr>
-<a name="perlpacktut-Dynamic-Templates"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Counting-Repetitions" accesskey="n"
rel="next">perlpacktut Counting Repetitions</a>, Previous: <a
href="#perlpacktut-String-Lengths" accesskey="p" rel="prev">perlpacktut String
Lengths</a>, Up: <a href="#perlpacktut-Lengths-and-Widths" accesskey="u"
rel="up">perlpacktut Lengths and Widths</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Dynamic-Templates"></a>
-<h4 class="subsection">50.8.2 Dynamic Templates</h4>
-
-<p>So far, we’ve seen literals used as templates. If the list of pack
-items doesn’t have fixed length, an expression constructing the
-template is required (whenever, for some reason, <code>()*</code> cannot be
used).
-Here’s an example: To store named string values in a way that can be
-conveniently parsed by a C program, we create a sequence of names and
-null terminated ASCII strings, with <code>=</code> between the name and the
value,
-followed by an additional delimiting null byte. Here’s how:
-</p>
-<pre class="verbatim"> my $env = pack( '(A*A*Z*)' . keys( %Env ) . 'C',
- map( { ( $_, '=', $Env{$_} ) } keys( %Env ) ), 0 );
-</pre>
-<p>Let’s examine the cogs of this byte mill, one by one. There’s
the <code>map</code>
-call, creating the items we intend to stuff into the <code>$env</code> buffer:
-to each key (in <code>$_</code>) it adds the <code>=</code> separator and the
hash entry value.
-Each triplet is packed with the template code sequence <code>A*A*Z*</code> that
-is repeated according to the number of keys. (Yes, that’s what the
<code>keys</code>
-function returns in scalar context.) To get the very last null byte,
-we add a <code>0</code> at the end of the <code>pack</code> list, to be packed
with <code>C</code>.
-(Attentive readers may have noticed that we could have omitted the 0.)
-</p>
-<p>For the reverse operation, we’ll have to determine the number of items
-in the buffer before we can let <code>unpack</code> rip it apart:
-</p>
-<pre class="verbatim"> my $n = $env =~ tr/\0// - 1;
- my %env = map( split( /=/, $_ ), unpack( "(Z*)$n", $env ) );
-</pre>
-<p>The <code>tr</code> counts the null bytes. The <code>unpack</code> call
returns a list of
-name-value pairs each of which is taken apart in the <code>map</code> block.
-</p>
-<hr>
-<a name="perlpacktut-Counting-Repetitions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Intel-HEX" accesskey="n" rel="next">perlpacktut
Intel HEX</a>, Previous: <a href="#perlpacktut-Dynamic-Templates" accesskey="p"
rel="prev">perlpacktut Dynamic Templates</a>, Up: <a
href="#perlpacktut-Lengths-and-Widths" accesskey="u" rel="up">perlpacktut
Lengths and Widths</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Counting-Repetitions"></a>
-<h4 class="subsection">50.8.3 Counting Repetitions</h4>
-
-<p>Rather than storing a sentinel at the end of a data item (or a list of
items),
-we could precede the data with a count. Again, we pack keys and values of
-a hash, preceding each with an unsigned short length count, and up front
-we store the number of pairs:
-</p>
-<pre class="verbatim"> my $env = pack( 'S(S/A* S/A*)*', scalar keys( %Env ),
%Env );
-</pre>
-<p>This simplifies the reverse operation as the number of repetitions can be
-unpacked with the <code>/</code> code:
-</p>
-<pre class="verbatim"> my %env = unpack( 'S/(S/A* S/A*)', $env );
-</pre>
-<p>Note that this is one of the rare cases where you cannot use the same
-template for <code>pack</code> and <code>unpack</code> because
<code>pack</code> can’t determine
-a repeat count for a <code>()</code>-group.
-</p>
-<hr>
-<a name="perlpacktut-Intel-HEX"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlpacktut-Counting-Repetitions" accesskey="p"
rel="prev">perlpacktut Counting Repetitions</a>, Up: <a
href="#perlpacktut-Lengths-and-Widths" accesskey="u" rel="up">perlpacktut
Lengths and Widths</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Intel-HEX"></a>
-<h4 class="subsection">50.8.4 Intel HEX</h4>
-
-<p>Intel HEX is a file format for representing binary data, mostly for
-programming various chips, as a text file. (See
-<a
href="http://en.wikipedia.org/wiki/.hex";>http://en.wikipedia.org/wiki/.hex</a>
for a detailed description, and
-<a
href="http://en.wikipedia.org/wiki/SREC_(file_format)">http://en.wikipedia.org/wiki/SREC_(file_format)</a>
for the Motorola
-S-record format, which can be unravelled using the same technique.)
-Each line begins with a colon (’:’) and is followed by a sequence
of
-hexadecimal characters, specifying a byte count <em>n</em> (8 bit),
-an address (16 bit, big endian), a record type (8 bit), <em>n</em> data bytes
-and a checksum (8 bit) computed as the least significant byte of the
two’s
-complement sum of the preceding bytes. Example: <code>:0300300002337A1E</code>.
-</p>
-<p>The first step of processing such a line is the conversion, to binary,
-of the hexadecimal data, to obtain the four fields, while checking the
-checksum. No surprise here: we’ll start with a simple <code>pack</code>
call to
-convert everything to binary:
-</p>
-<pre class="verbatim"> my $binrec = pack( 'H*', substr( $hexrec, 1 ) );
-</pre>
-<p>The resulting byte sequence is most convenient for checking the checksum.
-Don’t slow your program down with a for loop adding the <code>ord</code>
values
-of this string’s bytes - the <code>unpack</code> code <code>%</code> is
the thing to use
-for computing the 8-bit sum of all bytes, which must be equal to zero:
-</p>
-<pre class="verbatim"> die unless unpack( "%8C*", $binrec ) == 0;
-</pre>
-<p>Finally, let’s get those four fields. By now, you shouldn’t
have any
-problems with the first three fields - but how can we use the byte count
-of the data in the first field as a length for the data field? Here
-the codes <code>x</code> and <code>X</code> come to the rescue, as they permit
jumping
-back and forth in the string to unpack.
-</p>
-<pre class="verbatim"> my( $addr, $type, $data ) = unpack( "x n C X4 C
x3 /a", $bin );
-</pre>
-<p>Code <code>x</code> skips a byte, since we don’t need the count yet.
Code <code>n</code> takes
-care of the 16-bit big-endian integer address, and <code>C</code> unpacks the
-record type. Being at offset 4, where the data begins, we need the count.
-<code>X4</code> brings us back to square one, which is the byte at offset 0.
-Now we pick up the count, and zoom forth to offset 4, where we are
-now fully furnished to extract the exact number of data bytes, leaving
-the trailing checksum byte alone.
-</p>
-<hr>
-<a name="perlpacktut-Packing-and-Unpacking-C-Structures"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Pack-Recipes" accesskey="n" rel="next">perlpacktut
Pack Recipes</a>, Previous: <a href="#perlpacktut-Lengths-and-Widths"
accesskey="p" rel="prev">perlpacktut Lengths and Widths</a>, Up: <a
href="#perlpacktut" accesskey="u" rel="up">perlpacktut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Packing-and-Unpacking-C-Structures"></a>
-<h3 class="section">50.9 Packing and Unpacking C Structures</h3>
-
-<p>In previous sections we have seen how to pack numbers and character
-strings. If it were not for a couple of snags we could conclude this
-section right away with the terse remark that C structures don’t
-contain anything else, and therefore you already know all there is to it.
-Sorry, no: read on, please.
-</p>
-<p>If you have to deal with a lot of C structures, and don’t want to
-hack all your template strings manually, you’ll probably want to have
-a look at the CPAN module <code>Convert::Binary::C</code>. Not only can it
parse
-your C source directly, but it also has built-in support for all the
-odds and ends described further on in this section.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-The-Alignment-Pit" accesskey="1">perlpacktut The Alignment
Pit</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Dealing-with-Endian_002dness" accesskey="2">perlpacktut
Dealing with Endian-ness</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Alignment_002c-Take-2" accesskey="3">perlpacktut Alignment,
Take 2</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Alignment_002c-Take-3" accesskey="4">perlpacktut Alignment,
Take 3</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpacktut-Pointers-for-How-to-Use-Them" accesskey="5">perlpacktut
Pointers for How to Use Them</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpacktut-The-Alignment-Pit"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Dealing-with-Endian_002dness" accesskey="n"
rel="next">perlpacktut Dealing with Endian-ness</a>, Up: <a
href="#perlpacktut-Packing-and-Unpacking-C-Structures" accesskey="u"
rel="up">perlpacktut Packing and Unpacking C Structures</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-Alignment-Pit"></a>
-<h4 class="subsection">50.9.1 The Alignment Pit</h4>
-
-<p>In the consideration of speed against memory requirements the balance
-has been tilted in favor of faster execution. This has influenced the
-way C compilers allocate memory for structures: On architectures
-where a 16-bit or 32-bit operand can be moved faster between places in
-memory, or to or from a CPU register, if it is aligned at an even or
-multiple-of-four or even at a multiple-of eight address, a C compiler
-will give you this speed benefit by stuffing extra bytes into structures.
-If you don’t cross the C shoreline this is not likely to cause you any
-grief (although you should care when you design large data structures,
-or you want your code to be portable between architectures (you do want
-that, don’t you?)).
-</p>
-<p>To see how this affects <code>pack</code> and <code>unpack</code>,
we’ll compare these two
-C structures:
-</p>
-<pre class="verbatim"> typedef struct {
- char c1;
- short s;
- char c2;
- long l;
- } gappy_t;
-
- typedef struct {
- long l;
- short s;
- char c1;
- char c2;
- } dense_t;
-</pre>
-<p>Typically, a C compiler allocates 12 bytes to a <code>gappy_t</code>
variable, but
-requires only 8 bytes for a <code>dense_t</code>. After investigating this
further,
-we can draw memory maps, showing where the extra 4 bytes are hidden:
-</p>
-<pre class="verbatim"> 0 +4 +8 +12
- +--+--+--+--+--+--+--+--+--+--+--+--+
- |c1|xx| s |c2|xx|xx|xx| l | xx = fill byte
- +--+--+--+--+--+--+--+--+--+--+--+--+
- gappy_t
-
- 0 +4 +8
- +--+--+--+--+--+--+--+--+
- | l | h |c1|c2|
- +--+--+--+--+--+--+--+--+
- dense_t
-</pre>
-<p>And that’s where the first quirk strikes: <code>pack</code> and
<code>unpack</code>
-templates have to be stuffed with <code>x</code> codes to get those extra fill
bytes.
-</p>
-<p>The natural question: "Why can’t Perl compensate for the
gaps?" warrants
-an answer. One good reason is that C compilers might provide (non-ANSI)
-extensions permitting all sorts of fancy control over the way structures
-are aligned, even at the level of an individual structure field. And, if
-this were not enough, there is an insidious thing called <code>union</code>
where
-the amount of fill bytes cannot be derived from the alignment of the next
-item alone.
-</p>
-<p>OK, so let’s bite the bullet. Here’s one way to get the
alignment right
-by inserting template codes <code>x</code>, which don’t take a
corresponding item
-from the list:
-</p>
-<pre class="verbatim"> my $gappy = pack( 'cxs cxxx l!', $c1, $s, $c2, $l );
-</pre>
-<p>Note the <code>!</code> after <code>l</code>: We want to make sure that we
pack a long
-integer as it is compiled by our C compiler. And even now, it will only
-work for the platforms where the compiler aligns things as above.
-And somebody somewhere has a platform where it doesn’t.
-[Probably a Cray, where <code>short</code>s, <code>int</code>s and
<code>long</code>s are all 8 bytes. :-)]
-</p>
-<p>Counting bytes and watching alignments in lengthy structures is bound to
-be a drag. Isn’t there a way we can create the template with a simple
-program? Here’s a C program that does the trick:
-</p>
-<pre class="verbatim"> #include <stdio.h>
- #include <stddef.h>
-
- typedef struct {
- char fc1;
- short fs;
- char fc2;
- long fl;
- } gappy_t;
-
- #define Pt(struct,field,tchar) \
- printf( "@%d%s ", offsetof(struct,field), # tchar );
-
- int main() {
- Pt( gappy_t, fc1, c );
- Pt( gappy_t, fs, s! );
- Pt( gappy_t, fc2, c );
- Pt( gappy_t, fl, l! );
- printf( "\n" );
- }
-</pre>
-<p>The output line can be used as a template in a <code>pack</code> or
<code>unpack</code> call:
-</p>
-<pre class="verbatim"> my $gappy = pack( '@0c @2s! @4c @8l!', $c1, $s, $c2,
$l );
-</pre>
-<p>Gee, yet another template code - as if we hadn’t plenty. But
-<code>@</code> saves our day by enabling us to specify the offset from the
beginning
-of the pack buffer to the next item: This is just the value
-the <code>offsetof</code> macro (defined in <code><stddef.h></code>)
returns when
-given a <code>struct</code> type and one of its field names
("member-designator" in
-C standardese).
-</p>
-<p>Neither using offsets nor adding <code>x</code>’s to bridge the gaps
is satisfactory.
-(Just imagine what happens if the structure changes.) What we really need
-is a way of saying "skip as many bytes as required to the next multiple
of N".
-In fluent Templatese, you say this with <code>x!N</code> where N is replaced
by the
-appropriate value. Here’s the next version of our struct packaging:
-</p>
-<pre class="verbatim"> my $gappy = pack( 'c x!2 s c x!4 l!', $c1, $s, $c2, $l
);
-</pre>
-<p>That’s certainly better, but we still have to know how long all the
-integers are, and portability is far away. Rather than <code>2</code>,
-for instance, we want to say "however long a short is". But this can
be
-done by enclosing the appropriate pack code in brackets: <code>[s]</code>. So,
here’s
-the very best we can do:
-</p>
-<pre class="verbatim"> my $gappy = pack( 'c x![s] s c x![l!] l!', $c1, $s,
$c2, $l );
-</pre>
-<hr>
-<a name="perlpacktut-Dealing-with-Endian_002dness"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Alignment_002c-Take-2" accesskey="n"
rel="next">perlpacktut Alignment, Take 2</a>, Previous: <a
href="#perlpacktut-The-Alignment-Pit" accesskey="p" rel="prev">perlpacktut The
Alignment Pit</a>, Up: <a
href="#perlpacktut-Packing-and-Unpacking-C-Structures" accesskey="u"
rel="up">perlpacktut Packing and Unpacking C Structures</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Dealing-with-Endian_002dness"></a>
-<h4 class="subsection">50.9.2 Dealing with Endian-ness</h4>
-
-<p>Now, imagine that we want to pack the data for a machine with a
-different byte-order. First, we’ll have to figure out how big the data
-types on the target machine really are. Let’s assume that the longs are
-32 bits wide and the shorts are 16 bits wide. You can then rewrite the
-template as:
-</p>
-<pre class="verbatim"> my $gappy = pack( 'c x![s] s c x![l] l', $c1, $s, $c2,
$l );
-</pre>
-<p>If the target machine is little-endian, we could write:
-</p>
-<pre class="verbatim"> my $gappy = pack( 'c x![s] s< c x![l] l<', $c1,
$s, $c2, $l );
-</pre>
-<p>This forces the short and the long members to be little-endian, and is
-just fine if you don’t have too many struct members. But we could also
-use the byte-order modifier on a group and write the following:
-</p>
-<pre class="verbatim"> my $gappy = pack( '( c x![s] s c x![l] l )<', $c1,
$s, $c2, $l );
-</pre>
-<p>This is not as short as before, but it makes it more obvious that we
-intend to have little-endian byte-order for a whole group, not only
-for individual template codes. It can also be more readable and easier
-to maintain.
-</p>
-<hr>
-<a name="perlpacktut-Alignment_002c-Take-2"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Alignment_002c-Take-3" accesskey="n"
rel="next">perlpacktut Alignment, Take 3</a>, Previous: <a
href="#perlpacktut-Dealing-with-Endian_002dness" accesskey="p"
rel="prev">perlpacktut Dealing with Endian-ness</a>, Up: <a
href="#perlpacktut-Packing-and-Unpacking-C-Structures" accesskey="u"
rel="up">perlpacktut Packing and Unpacking C Structures</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Alignment_002c-Take-2"></a>
-<h4 class="subsection">50.9.3 Alignment, Take 2</h4>
-
-<p>I’m afraid that we’re not quite through with the alignment
catch yet. The
-hydra raises another ugly head when you pack arrays of structures:
-</p>
-<pre class="verbatim"> typedef struct {
- short count;
- char glyph;
- } cell_t;
-
- typedef cell_t buffer_t[BUFLEN];
-</pre>
-<p>Where’s the catch? Padding is neither required before the first field
<code>count</code>,
-nor between this and the next field <code>glyph</code>, so why can’t we
simply pack
-like this:
-</p>
-<pre class="verbatim"> # something goes wrong here:
- pack( 's!a' x @buffer,
- map{ ( $_->{count}, $_->{glyph} ) } @buffer );
-</pre>
-<p>This packs <code>address@hidden</code> bytes, but it turns out that the
size of
-<code>buffer_t</code> is four times <code>BUFLEN</code>! The moral of the
story is that
-the required alignment of a structure or array is propagated to the
-next higher level where we have to consider padding <em>at the end</em>
-of each component as well. Thus the correct template is:
-</p>
-<pre class="verbatim"> pack( 's!ax' x @buffer,
- map{ ( $_->{count}, $_->{glyph} ) } @buffer );
-</pre>
-<hr>
-<a name="perlpacktut-Alignment_002c-Take-3"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Pointers-for-How-to-Use-Them" accesskey="n"
rel="next">perlpacktut Pointers for How to Use Them</a>, Previous: <a
href="#perlpacktut-Alignment_002c-Take-2" accesskey="p" rel="prev">perlpacktut
Alignment, Take 2</a>, Up: <a
href="#perlpacktut-Packing-and-Unpacking-C-Structures" accesskey="u"
rel="up">perlpacktut Packing and Unpacking C Structures</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Alignment_002c-Take-3"></a>
-<h4 class="subsection">50.9.4 Alignment, Take 3</h4>
-
-<p>And even if you take all the above into account, ANSI still lets this:
-</p>
-<pre class="verbatim"> typedef struct {
- char foo[2];
- } foo_t;
-</pre>
-<p>vary in size. The alignment constraint of the structure can be greater than
-any of its elements. [And if you think that this doesn’t affect anything
-common, dismember the next cellphone that you see. Many have ARM cores, and
-the ARM structure rules make <code>sizeof (foo_t)</code> == 4]
-</p>
-<hr>
-<a name="perlpacktut-Pointers-for-How-to-Use-Them"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlpacktut-Alignment_002c-Take-3" accesskey="p"
rel="prev">perlpacktut Alignment, Take 3</a>, Up: <a
href="#perlpacktut-Packing-and-Unpacking-C-Structures" accesskey="u"
rel="up">perlpacktut Packing and Unpacking C Structures</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Pointers-for-How-to-Use-Them"></a>
-<h4 class="subsection">50.9.5 Pointers for How to Use Them</h4>
-
-<p>The title of this section indicates the second problem you may run into
-sooner or later when you pack C structures. If the function you intend
-to call expects a, say, <code>void *</code> value, you <em>cannot</em> simply
take
-a reference to a Perl variable. (Although that value certainly is a
-memory address, it’s not the address where the variable’s contents
are
-stored.)
-</p>
-<p>Template code <code>P</code> promises to pack a "pointer to a fixed
length string".
-Isn’t this what we want? Let’s try:
-</p>
-<pre class="verbatim"> # allocate some storage and pack a pointer to it
- my $memory = "\x00" x $size;
- my $memptr = pack( 'P', $memory );
-</pre>
-<p>But wait: doesn’t <code>pack</code> just return a sequence of bytes?
How can we pass this
-string of bytes to some C code expecting a pointer which is, after all,
-nothing but a number? The answer is simple: We have to obtain the numeric
-address from the bytes returned by <code>pack</code>.
-</p>
-<pre class="verbatim"> my $ptr = unpack( 'L!', $memptr );
-</pre>
-<p>Obviously this assumes that it is possible to typecast a pointer
-to an unsigned long and vice versa, which frequently works but should not
-be taken as a universal law. - Now that we have this pointer the next question
-is: How can we put it to good use? We need a call to some C function
-where a pointer is expected. The read(2) system call comes to mind:
-</p>
-<pre class="verbatim"> ssize_t read(int fd, void *buf, size_t count);
-</pre>
-<p>After reading <a href="#perlfunc-NAME">perlfunc NAME</a> explaining how to
use <code>syscall</code> we can write
-this Perl function copying a file to standard output:
-</p>
-<pre class="verbatim"> require 'syscall.ph'; # run h2ph to generate this
file
- sub cat($){
- my $path = shift();
- my $size = -s $path;
- my $memory = "\x00" x $size; # allocate some memory
- my $ptr = unpack( 'L', pack( 'P', $memory ) );
- open( F, $path ) || die( "$path: cannot open ($!)\n" );
- my $fd = fileno(F);
- my $res = syscall( &SYS_read, fileno(F), $ptr, $size );
- print $memory;
- close( F );
- }
-</pre>
-<p>This is neither a specimen of simplicity nor a paragon of portability but
-it illustrates the point: We are able to sneak behind the scenes and
-access Perl’s otherwise well-guarded memory! (Important note:
Perl’s
-<code>syscall</code> does <em>not</em> require you to construct pointers in
this roundabout
-way. You simply pass a string variable, and Perl forwards the address.)
-</p>
-<p>How does <code>unpack</code> with <code>P</code> work? Imagine some pointer
in the buffer
-about to be unpacked: If it isn’t the null pointer (which will smartly
-produce the <code>undef</code> value) we have a start address - but then what?
-Perl has no way of knowing how long this "fixed length string" is, so
-it’s up to you to specify the actual size as an explicit length after
<code>P</code>.
-</p>
-<pre class="verbatim"> my $mem = "abcdefghijklmn";
- print unpack( 'P5', pack( 'P', $mem ) ); # prints "abcde"
-</pre>
-<p>As a consequence, <code>pack</code> ignores any number or <code>*</code>
after <code>P</code>.
-</p>
-<p>Now that we have seen <code>P</code> at work, we might as well give
<code>p</code> a whirl.
-Why do we need a second template code for packing pointers at all? The
-answer lies behind the simple fact that an <code>unpack</code> with
<code>p</code> promises
-a null-terminated string starting at the address taken from the buffer,
-and that implies a length for the data item to be returned:
-</p>
-<pre class="verbatim"> my $buf = pack( 'p', "abc\x00efhijklmn" );
- print unpack( 'p', $buf ); # prints "abc"
-</pre>
-<p>Albeit this is apt to be confusing: As a consequence of the length being
-implied by the string’s length, a number after pack code <code>p</code>
is a repeat
-count, not a length as after <code>P</code>.
-</p>
-<p>Using <code>pack(..., $x)</code> with <code>P</code> or <code>p</code> to
get the address where <code>$x</code> is
-actually stored must be used with circumspection. Perl’s internal
machinery
-considers the relation between a variable and that address as its very own
-private matter and doesn’t really care that we have obtained a copy.
Therefore:
-</p>
-<ul>
-<li> Do not use <code>pack</code> with <code>p</code> or <code>P</code> to
obtain the address of variable
-that’s bound to go out of scope (and thereby freeing its memory) before
you
-are done with using the memory at that address.
-
-</li><li> Be very careful with Perl operations that change the value of the
-variable. Appending something to the variable, for instance, might require
-reallocation of its storage, leaving you with a pointer into no-man’s
land.
-
-</li><li> Don’t think that you can get the address of a Perl variable
-when it is stored as an integer or double number! <code>pack('P', $x)</code>
will
-force the variable’s internal representation to string, just as if you
-had written something like <code>$x .= ''</code>.
-
-</li></ul>
-
-<p>It’s safe, however, to P- or p-pack a string literal, because Perl
simply
-allocates an anonymous variable.
-</p>
-<hr>
-<a name="perlpacktut-Pack-Recipes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Funnies-Section" accesskey="n"
rel="next">perlpacktut Funnies Section</a>, Previous: <a
href="#perlpacktut-Packing-and-Unpacking-C-Structures" accesskey="p"
rel="prev">perlpacktut Packing and Unpacking C Structures</a>, Up: <a
href="#perlpacktut" accesskey="u" rel="up">perlpacktut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Pack-Recipes"></a>
-<h3 class="section">50.10 Pack Recipes</h3>
-
-<p>Here are a collection of (possibly) useful canned recipes for
<code>pack</code>
-and <code>unpack</code>:
-</p>
-<pre class="verbatim"> # Convert IP address for socket functions
- pack( "C4", split /\./, "123.4.5.6" );
-
- # Count the bits in a chunk of memory (e.g. a select vector)
- unpack( '%32b*', $mask );
-
- # Determine the endianness of your system
- $is_little_endian = unpack( 'c', pack( 's', 1 ) );
- $is_big_endian = unpack( 'xc', pack( 's', 1 ) );
-
- # Determine the number of bits in a native integer
- $bits = unpack( '%32I!', ~0 );
-
- # Prepare argument for the nanosleep system call
- my $timespec = pack( 'L!L!', $secs, $nanosecs );
-</pre>
-<p>For a simple memory dump we unpack some bytes into just as
-many pairs of hex digits, and use <code>map</code> to handle the traditional
-spacing - 16 bytes to a line:
-</p>
-<pre class="verbatim"> my $i;
- print map( ++$i % 16 ? "$_ " : "$_\n",
- unpack( 'H2' x length( $mem ), $mem ) ),
- length( $mem ) % 16 ? "\n" : '';
-</pre>
-<hr>
-<a name="perlpacktut-Funnies-Section"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpacktut-Authors" accesskey="n" rel="next">perlpacktut
Authors</a>, Previous: <a href="#perlpacktut-Pack-Recipes" accesskey="p"
rel="prev">perlpacktut Pack Recipes</a>, Up: <a href="#perlpacktut"
accesskey="u" rel="up">perlpacktut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Funnies-Section"></a>
-<h3 class="section">50.11 Funnies Section</h3>
-
-<pre class="verbatim"> # Pulling digits out of nowhere...
- print unpack( 'C', pack( 'x' ) ),
- unpack( '%B*', pack( 'A' ) ),
- unpack( 'H', pack( 'A' ) ),
- unpack( 'A', unpack( 'C', pack( 'A' ) ) ), "\n";
-
- # One for the road ;-)
- my $advice = pack( 'all u can in a van' );
-</pre>
-<hr>
-<a name="perlpacktut-Authors"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlpacktut-Funnies-Section" accesskey="p"
rel="prev">perlpacktut Funnies Section</a>, Up: <a href="#perlpacktut"
accesskey="u" rel="up">perlpacktut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Authors"></a>
-<h3 class="section">50.12 Authors</h3>
-
-<p>Simon Cozens and Wolfgang Laun.
-</p>
-<hr>
-<a name="perlperf"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpod" accesskey="n" rel="next">perlpod</a>, Previous: <a
href="#perlpacktut" accesskey="p" rel="prev">perlpacktut</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlperf-1"></a>
-<h2 class="chapter">51 perlperf</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlperf-NAME"
accesskey="1">perlperf NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-DESCRIPTION"
accesskey="2">perlperf DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-OVERVIEW"
accesskey="3">perlperf OVERVIEW</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-GENERAL-GUIDELINES" accesskey="4">perlperf GENERAL
GUIDELINES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-BENCHMARKS"
accesskey="5">perlperf BENCHMARKS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-PROFILING-TOOLS"
accesskey="6">perlperf PROFILING TOOLS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-SORTING"
accesskey="7">perlperf SORTING</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-LOGGING"
accesskey="8">perlperf LOGGING</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-POSTSCRIPT"
accesskey="9">perlperf POSTSCRIPT</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-SEE-ALSO">perlperf
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-AUTHOR">perlperf
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlperf-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-DESCRIPTION" accesskey="n" rel="next">perlperf
DESCRIPTION</a>, Up: <a href="#perlperf" accesskey="u" rel="up">perlperf</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-50"></a>
-<h3 class="section">51.1 NAME</h3>
-
-<p>perlperf - Perl Performance and Optimization Techniques
-</p>
-<hr>
-<a name="perlperf-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-OVERVIEW" accesskey="n" rel="next">perlperf
OVERVIEW</a>, Previous: <a href="#perlperf-NAME" accesskey="p"
rel="prev">perlperf NAME</a>, Up: <a href="#perlperf" accesskey="u"
rel="up">perlperf</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-49"></a>
-<h3 class="section">51.2 DESCRIPTION</h3>
-
-<p>This is an introduction to the use of performance and optimization
techniques
-which can be used with particular reference to perl programs. While many perl
-developers have come from other languages, and can use their prior knowledge
-where appropriate, there are many other people who might benefit from a few
-perl specific pointers. If you want the condensed version, perhaps the best
-advice comes from the renowned Japanese Samurai, Miyamoto Musashi, who said:
-</p>
-<pre class="verbatim"> "Do Not Engage in Useless Activity"
-</pre>
-<p>in 1645.
-</p>
-<hr>
-<a name="perlperf-OVERVIEW"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-GENERAL-GUIDELINES" accesskey="n" rel="next">perlperf
GENERAL GUIDELINES</a>, Previous: <a href="#perlperf-DESCRIPTION" accesskey="p"
rel="prev">perlperf DESCRIPTION</a>, Up: <a href="#perlperf" accesskey="u"
rel="up">perlperf</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="OVERVIEW"></a>
-<h3 class="section">51.3 OVERVIEW</h3>
-
-<p>Perhaps the most common mistake programmers make is to attempt to optimize
-their code before a program actually does anything useful - this is a bad idea.
-There’s no point in having an extremely fast program that doesn’t
work. The
-first job is to get a program to <em>correctly</em> do something
<strong>useful</strong>, (not to
-mention ensuring the test suite is fully functional), and only then to consider
-optimizing it. Having decided to optimize existing working code, there are
-several simple but essential steps to consider which are intrinsic to any
-optimization process.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlperf-ONE-STEP-SIDEWAYS"
accesskey="1">perlperf ONE STEP SIDEWAYS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-ONE-STEP-FORWARD"
accesskey="2">perlperf ONE STEP FORWARD</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-ANOTHER-STEP-SIDEWAYS" accesskey="3">perlperf ANOTHER STEP
SIDEWAYS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlperf-ONE-STEP-SIDEWAYS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-ONE-STEP-FORWARD" accesskey="n" rel="next">perlperf
ONE STEP FORWARD</a>, Up: <a href="#perlperf-OVERVIEW" accesskey="u"
rel="up">perlperf OVERVIEW</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="ONE-STEP-SIDEWAYS"></a>
-<h4 class="subsection">51.3.1 ONE STEP SIDEWAYS</h4>
-
-<p>Firstly, you need to establish a baseline time for the existing code, which
-timing needs to be reliable and repeatable. You’ll probably want to use
the
-<code>Benchmark</code> or <code>Devel::NYTProf</code> modules, or something
similar, for this step,
-or perhaps the Unix system <code>time</code> utility, whichever is
appropriate. See the
-base of this document for a longer list of benchmarking and profiling modules,
-and recommended further reading.
-</p>
-<hr>
-<a name="perlperf-ONE-STEP-FORWARD"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-ANOTHER-STEP-SIDEWAYS" accesskey="n"
rel="next">perlperf ANOTHER STEP SIDEWAYS</a>, Previous: <a
href="#perlperf-ONE-STEP-SIDEWAYS" accesskey="p" rel="prev">perlperf ONE STEP
SIDEWAYS</a>, Up: <a href="#perlperf-OVERVIEW" accesskey="u" rel="up">perlperf
OVERVIEW</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="ONE-STEP-FORWARD"></a>
-<h4 class="subsection">51.3.2 ONE STEP FORWARD</h4>
-
-<p>Next, having examined the program for <em>hot spots</em>, (places where the
code
-seems to run slowly), change the code with the intention of making it run
-faster. Using version control software, like <code>subversion</code>, will
ensure no
-changes are irreversible. It’s too easy to fiddle here and fiddle there
-
-don’t change too much at any one time or you might not discover which
piece of
-code <strong>really</strong> was the slow bit.
-</p>
-<hr>
-<a name="perlperf-ANOTHER-STEP-SIDEWAYS"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlperf-ONE-STEP-FORWARD" accesskey="p"
rel="prev">perlperf ONE STEP FORWARD</a>, Up: <a href="#perlperf-OVERVIEW"
accesskey="u" rel="up">perlperf OVERVIEW</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="ANOTHER-STEP-SIDEWAYS"></a>
-<h4 class="subsection">51.3.3 ANOTHER STEP SIDEWAYS</h4>
-
-<p>It’s not enough to say: "that will make it run faster", you
have to check it.
-Rerun the code under control of the benchmarking or profiling modules, from the
-first step above, and check that the new code executed the <strong>same
task</strong> in
-<em>less time</em>. Save your work and repeat...
-</p>
-<hr>
-<a name="perlperf-GENERAL-GUIDELINES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-BENCHMARKS" accesskey="n" rel="next">perlperf
BENCHMARKS</a>, Previous: <a href="#perlperf-OVERVIEW" accesskey="p"
rel="prev">perlperf OVERVIEW</a>, Up: <a href="#perlperf" accesskey="u"
rel="up">perlperf</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="GENERAL-GUIDELINES"></a>
-<h3 class="section">51.4 GENERAL GUIDELINES</h3>
-
-<p>The critical thing when considering performance is to remember there is no
such
-thing as a <code>Golden Bullet</code>, which is why there are no rules, only
guidelines.
-</p>
-<p>It is clear that inline code is going to be faster than subroutine or method
-calls, because there is less overhead, but this approach has the disadvantage
-of being less maintainable and comes at the cost of greater memory usage -
-there is no such thing as a free lunch. If you are searching for an element in
-a list, it can be more efficient to store the data in a hash structure, and
-then simply look to see whether the key is defined, rather than to loop through
-the entire array using grep() for instance. substr() may be (a lot) faster
-than grep() but not as flexible, so you have another trade-off to access. Your
-code may contain a line which takes 0.01 of a second to execute which if you
-call it 1,000 times, quite likely in a program parsing even medium sized files
-for instance, you already have a 10 second delay, in just one single code
-location, and if you call that line 100,000 times, your entire program will
-slow down to an unbearable crawl.
-</p>
-<p>Using a subroutine as part of your sort is a powerful way to get exactly
what
-you want, but will usually be slower than the built-in <em>alphabetic</em>
<code>cmp</code> and
-<em>numeric</em> <code><=></code> sort operators. It is possible to
make multiple
-passes over your data, building indices to make the upcoming sort more
-efficient, and to use what is known as the <code>OM</code> (Orcish Maneuver)
to cache the
-sort keys in advance. The cache lookup, while a good idea, can itself be a
-source of slowdown by enforcing a double pass over the data - once to setup the
-cache, and once to sort the data. Using <code>pack()</code> to extract the
required sort
-key into a consistent string can be an efficient way to build a single string
-to compare, instead of using multiple sort keys, which makes it possible to use
-the standard, written in <code>c</code> and fast, perl <code>sort()</code>
function on the output,
-and is the basis of the <code>GRT</code> (Guttman Rossler Transform). Some
string
-combinations can slow the <code>GRT</code> down, by just being too plain
complex for its
-own good.
-</p>
-<p>For applications using database backends, the standard <code>DBIx</code>
namespace has
-tries to help with keeping things nippy, not least because it tries to
<em>not</em>
-query the database until the latest possible moment, but always read the docs
-which come with your choice of libraries. Among the many issues facing
-developers dealing with databases should remain aware of is to always use
-<code>SQL</code> placeholders and to consider pre-fetching data sets when this
might
-prove advantageous. Splitting up a large file by assigning multiple processes
-to parsing a single file, using say <code>POE</code>, <code>threads</code> or
<code>fork</code> can also be a
-useful way of optimizing your usage of the available <code>CPU</code>
resources, though
-this technique is fraught with concurrency issues and demands high attention to
-detail.
-</p>
-<p>Every case has a specific application and one or more exceptions, and there
is
-no replacement for running a few tests and finding out which method works best
-for your particular environment, this is why writing optimal code is not an
-exact science, and why we love using Perl so much - TMTOWTDI.
-</p>
-<hr>
-<a name="perlperf-BENCHMARKS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-PROFILING-TOOLS" accesskey="n" rel="next">perlperf
PROFILING TOOLS</a>, Previous: <a href="#perlperf-GENERAL-GUIDELINES"
accesskey="p" rel="prev">perlperf GENERAL GUIDELINES</a>, Up: <a
href="#perlperf" accesskey="u" rel="up">perlperf</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="BENCHMARKS"></a>
-<h3 class="section">51.5 BENCHMARKS</h3>
-
-<p>Here are a few examples to demonstrate usage of Perl’s benchmarking
tools.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlperf-Assigning-and-Dereferencing-Variables_002e"
accesskey="1">perlperf Assigning and Dereferencing
Variables.</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-Search-and-replace-or-tr" accesskey="2">perlperf Search and
replace or tr</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlperf-Assigning-and-Dereferencing-Variables_002e"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-Search-and-replace-or-tr" accesskey="n"
rel="next">perlperf Search and replace or tr</a>, Up: <a
href="#perlperf-BENCHMARKS" accesskey="u" rel="up">perlperf BENCHMARKS</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Assigning-and-Dereferencing-Variables_002e"></a>
-<h4 class="subsection">51.5.1 Assigning and Dereferencing Variables.</h4>
-
-<p>I’m sure most of us have seen code which looks like, (or worse than),
this:
-</p>
-<pre class="verbatim"> if ( $obj->{_ref}->{_myscore} >=
$obj->{_ref}->{_yourscore} ) {
- ...
-</pre>
-<p>This sort of code can be a real eyesore to read, as well as being very
-sensitive to typos, and it’s much clearer to dereference the variable
-explicitly. We’re side-stepping the issue of working with
object-oriented
-programming techniques to encapsulate variable access via methods, only
-accessible through an object. Here we’re just discussing the technical
-implementation of choice, and whether this has an effect on performance. We
-can see whether this dereferencing operation, has any overhead by putting
-comparative code in a file and running a <code>Benchmark</code> test.
-</p>
-<p># dereference
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
-
- use strict;
- use warnings;
-
- use Benchmark;
-
- my $ref = {
- 'ref' => {
- _myscore => '100 + 1',
- _yourscore => '102 - 1',
- },
- };
-
- timethese(1000000, {
- 'direct' => sub {
- my $x = $ref->{ref}->{_myscore} .
$ref->{ref}->{_yourscore} ;
- },
- 'dereference' => sub {
- my $ref = $ref->{ref};
- my $myscore = $ref->{_myscore};
- my $yourscore = $ref->{_yourscore};
- my $x = $myscore . $yourscore;
- },
- });
-</pre>
-<p>It’s essential to run any timing measurements a sufficient number of
times so
-the numbers settle on a numerical average, otherwise each run will naturally
-fluctuate due to variations in the environment, to reduce the effect of
-contention for <code>CPU</code> resources and network bandwidth for instance.
Running
-the above code for one million iterations, we can take a look at the report
-output by the <code>Benchmark</code> module, to see which approach is the most
effective.
-</p>
-<pre class="verbatim"> $> perl dereference
-
- Benchmark: timing 1000000 iterations of dereference, direct...
- dereference: 2 wallclock secs ( 1.59 usr + 0.00 sys = 1.59 CPU) @
628930.82/s (n=1000000)
- direct: 1 wallclock secs ( 1.20 usr + 0.00 sys = 1.20 CPU) @
833333.33/s (n=1000000)
-</pre>
-<p>The difference is clear to see and the dereferencing approach is slower.
While
-it managed to execute an average of 628,930 times a second during our test, the
-direct approach managed to run an additional 204,403 times, unfortunately.
-Unfortunately, because there are many examples of code written using the
-multiple layer direct variable access, and it’s usually horrible. It is,
-however, minusculy faster. The question remains whether the minute gain is
-actually worth the eyestrain, or the loss of maintainability.
-</p>
-<hr>
-<a name="perlperf-Search-and-replace-or-tr"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlperf-Assigning-and-Dereferencing-Variables_002e"
accesskey="p" rel="prev">perlperf Assigning and Dereferencing Variables.</a>,
Up: <a href="#perlperf-BENCHMARKS" accesskey="u" rel="up">perlperf
BENCHMARKS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Search-and-replace-or-tr"></a>
-<h4 class="subsection">51.5.2 Search and replace or tr</h4>
-
-<p>If we have a string which needs to be modified, while a regex will almost
-always be much more flexible, <code>tr</code>, an oft underused tool, can
still be a
-useful. One scenario might be replace all vowels with another character. The
-regex solution might look like this:
-</p>
-<pre class="verbatim"> $str =~ s/[aeiou]/x/g
-</pre>
-<p>The <code>tr</code> alternative might look like this:
-</p>
-<pre class="verbatim"> $str =~ tr/aeiou/xxxxx/
-</pre>
-<p>We can put that into a test file which we can run to check which approach is
-the fastest, using a global <code>$STR</code> variable to assign to the
<code>my $str</code>
-variable so as to avoid perl trying to optimize any of the work away by
-noticing it’s assigned only the once.
-</p>
-<p># regex-transliterate
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
-
- use strict;
- use warnings;
-
- use Benchmark;
-
- my $STR = "$$-this and that";
-
- timethese( 1000000, {
- 'sr' => sub { my $str = $STR; $str =~ s/[aeiou]/x/g; return
$str; },
- 'tr' => sub { my $str = $STR; $str =~ tr/aeiou/xxxxx/; return
$str; },
- });
-</pre>
-<p>Running the code gives us our results:
-</p>
-<pre class="verbatim"> $> perl regex-transliterate
-
- Benchmark: timing 1000000 iterations of sr, tr...
- sr: 2 wallclock secs ( 1.19 usr + 0.00 sys = 1.19 CPU) @
840336.13/s (n=1000000)
- tr: 0 wallclock secs ( 0.49 usr + 0.00 sys = 0.49 CPU) @
2040816.33/s (n=1000000)
-</pre>
-<p>The <code>tr</code> version is a clear winner. One solution is flexible,
the other is
-fast - and it’s appropriately the programmer’s choice which to use.
-</p>
-<p>Check the <code>Benchmark</code> docs for further useful techniques.
-</p>
-<hr>
-<a name="perlperf-PROFILING-TOOLS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-SORTING" accesskey="n" rel="next">perlperf
SORTING</a>, Previous: <a href="#perlperf-BENCHMARKS" accesskey="p"
rel="prev">perlperf BENCHMARKS</a>, Up: <a href="#perlperf" accesskey="u"
rel="up">perlperf</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="PROFILING-TOOLS"></a>
-<h3 class="section">51.6 PROFILING TOOLS</h3>
-
-<p>A slightly larger piece of code will provide something on which a profiler
can
-produce more extensive reporting statistics. This example uses the simplistic
-<code>wordmatch</code> program which parses a given input file and spews out a
short
-report on the contents.
-</p>
-<p># wordmatch
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
-
- use strict;
- use warnings;
-
- =head1 NAME
-
- filewords - word analysis of input file
-
- =head1 SYNOPSIS
-
- filewords -f inputfilename [-d]
-
- =head1 DESCRIPTION
-
- This program parses the given filename, specified with C<-f>, and
displays a
- simple analysis of the words found therein. Use the C<-d> switch to
enable
- debugging messages.
-
- =cut
-
- use FileHandle;
- use Getopt::Long;
-
- my $debug = 0;
- my $file = '';
-
- my $result = GetOptions (
- 'debug' => \$debug,
- 'file=s' => \$file,
- );
- die("invalid args") unless $result;
-
- unless ( -f $file ) {
- die("Usage: $0 -f filename [-d]");
- }
- my $FH = FileHandle->new("< $file") or die("unable to
open file($file): $!");
-
- my $i_LINES = 0;
- my $i_WORDS = 0;
- my %count = ();
-
- my @lines = <$FH>;
- foreach my $line ( @lines ) {
- $i_LINES++;
- $line =~ s/\n//;
- my @words = split(/ +/, $line);
- my $i_words = scalar(@words);
- $i_WORDS = $i_WORDS + $i_words;
- debug("line: $i_LINES supplying $i_words words: @words");
- my $i_word = 0;
- foreach my $word ( @words ) {
- $i_word++;
- $count{$i_LINES}{spec} += matches($i_word, $word, '[^a-zA-Z0-9]');
- $count{$i_LINES}{only} += matches($i_word, $word,
'^[^a-zA-Z0-9]+$');
- $count{$i_LINES}{cons} += matches($i_word, $word,
'^[(?i:bcdfghjklmnpqrstvwxyz)]+$');
- $count{$i_LINES}{vows} += matches($i_word, $word,
'^[(?i:aeiou)]+$');
- $count{$i_LINES}{caps} += matches($i_word, $word, '^[(A-Z)]+$');
- }
- }
-
- print report( %count );
-
- sub matches {
- my $i_wd = shift;
- my $word = shift;
- my $regex = shift;
- my $has = 0;
-
- if ( $word =~ /($regex)/ ) {
- $has++ if $1;
- }
-
- debug("word: $i_wd ".($has ? 'matches' : 'does not
match')." chars: /$regex/");
-
- return $has;
- }
-
- sub report {
- my %report = @_;
- my %rep;
-
- foreach my $line ( keys %report ) {
- foreach my $key ( keys %{ $report{$line} } ) {
- $rep{$key} += $report{$line}{$key};
- }
- }
-
- my $report = qq|
- $0 report for $file:
- lines in file: $i_LINES
- words in file: $i_WORDS
- words with special (non-word) characters: $i_spec
- words with only special (non-word) characters: $i_only
- words with only consonants: $i_cons
- words with only capital letters: $i_caps
- words with only vowels: $i_vows
- |;
-
- return $report;
- }
-
- sub debug {
- my $message = shift;
-
- if ( $debug ) {
- print STDERR "DBG: $message\n";
- }
- }
-
- exit 0;
-</pre>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlperf-Devel_003a_003aDProf" accesskey="1">perlperf
Devel::DProf</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-Devel_003a_003aProfiler" accesskey="2">perlperf
Devel::Profiler</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-Devel_003a_003aSmallProf" accesskey="3">perlperf
Devel::SmallProf</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-Devel_003a_003aFastProf" accesskey="4">perlperf
Devel::FastProf</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlperf-Devel_003a_003aNYTProf" accesskey="5">perlperf
Devel::NYTProf</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlperf-Devel_003a_003aDProf"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-Devel_003a_003aProfiler" accesskey="n"
rel="next">perlperf Devel::Profiler</a>, Up: <a
href="#perlperf-PROFILING-TOOLS" accesskey="u" rel="up">perlperf PROFILING
TOOLS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Devel_003a_003aDProf"></a>
-<h4 class="subsection">51.6.1 Devel::DProf</h4>
-
-<p>This venerable module has been the de-facto standard for Perl code profiling
-for more than a decade, but has been replaced by a number of other modules
-which have brought us back to the 21st century. Although you’re
recommended to
-evaluate your tool from the several mentioned here and from the CPAN list at
-the base of this document, (and currently <a
href="Devel-NYTProf.html#Top">(Devel-NYTProf)</a> seems to be the
-weapon of choice - see below), we’ll take a quick look at the output from
-<a href="Devel-DProf.html#Top">(Devel-DProf)</a> first, to set a baseline for
Perl profiling tools. Run the
-above program under the control of <code>Devel::DProf</code> by using the
<code>-d</code> switch on
-the command-line.
-</p>
-<pre class="verbatim"> $> perl -d:DProf wordmatch -f perl5db.pl
-
- <...multiple lines snipped...>
-
- wordmatch report for perl5db.pl:
- lines in file: 9428
- words in file: 50243
- words with special (non-word) characters: 20480
- words with only special (non-word) characters: 7790
- words with only consonants: 4801
- words with only capital letters: 1316
- words with only vowels: 1701
-</pre>
-<p><code>Devel::DProf</code> produces a special file, called
<samp>tmon.out</samp> by default, and
-this file is read by the <code>dprofpp</code> program, which is already
installed as part
-of the <code>Devel::DProf</code> distribution. If you call
<code>dprofpp</code> with no options,
-it will read the <samp>tmon.out</samp> file in the current directory and
produce a human
-readable statistics report of the run of your program. Note that this may take
-a little time.
-</p>
-<pre class="verbatim"> $> dprofpp
-
- Total Elapsed Time = 2.951677 Seconds
- User+System Time = 2.871677 Seconds
- Exclusive Times
- %Time ExclSec CumulS #Calls sec/call Csec/c Name
- 102. 2.945 3.003 251215 0.0000 0.0000 main::matches
- 2.40 0.069 0.069 260643 0.0000 0.0000 main::debug
- 1.74 0.050 0.050 1 0.0500 0.0500 main::report
- 1.04 0.030 0.049 4 0.0075 0.0123 main::BEGIN
- 0.35 0.010 0.010 3 0.0033 0.0033 Exporter::as_heavy
- 0.35 0.010 0.010 7 0.0014 0.0014 IO::File::BEGIN
- 0.00 - -0.000 1 - - Getopt::Long::FindOption
- 0.00 - -0.000 1 - - Symbol::BEGIN
- 0.00 - -0.000 1 - - Fcntl::BEGIN
- 0.00 - -0.000 1 - - Fcntl::bootstrap
- 0.00 - -0.000 1 - - warnings::BEGIN
- 0.00 - -0.000 1 - - IO::bootstrap
- 0.00 - -0.000 1 - - Getopt::Long::ConfigDefaults
- 0.00 - -0.000 1 - - Getopt::Long::Configure
- 0.00 - -0.000 1 - - Symbol::gensym
-</pre>
-<p><code>dprofpp</code> will produce some quite detailed reporting on the
activity of the
-<code>wordmatch</code> program. The wallclock, user and system, times are at
the top of
-the analysis, and after this are the main columns defining which define the
-report. Check the <code>dprofpp</code> docs for details of the many options
it supports.
-</p>
-<p>See also <code>Apache::DProf</code> which hooks <code>Devel::DProf</code>
into <code>mod_perl</code>.
-</p>
-<hr>
-<a name="perlperf-Devel_003a_003aProfiler"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-Devel_003a_003aSmallProf" accesskey="n"
rel="next">perlperf Devel::SmallProf</a>, Previous: <a
href="#perlperf-Devel_003a_003aDProf" accesskey="p" rel="prev">perlperf
Devel::DProf</a>, Up: <a href="#perlperf-PROFILING-TOOLS" accesskey="u"
rel="up">perlperf PROFILING TOOLS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Devel_003a_003aProfiler"></a>
-<h4 class="subsection">51.6.2 Devel::Profiler</h4>
-
-<p>Let’s take a look at the same program using a different profiler:
-<code>Devel::Profiler</code>, a drop-in Perl-only replacement for
<code>Devel::DProf</code>. The
-usage is very slightly different in that instead of using the special
<code>-d:</code>
-flag, you pull <code>Devel::Profiler</code> in directly as a module using
<code>-M</code>.
-</p>
-<pre class="verbatim"> $> perl -MDevel::Profiler wordmatch -f perl5db.pl
-
- <...multiple lines snipped...>
-
- wordmatch report for perl5db.pl:
- lines in file: 9428
- words in file: 50243
- words with special (non-word) characters: 20480
- words with only special (non-word) characters: 7790
- words with only consonants: 4801
- words with only capital letters: 1316
- words with only vowels: 1701
-</pre>
-<p><code>Devel::Profiler</code> generates a tmon.out file which is compatible
with the
-<code>dprofpp</code> program, thus saving the construction of a dedicated
statistics
-reader program. <code>dprofpp</code> usage is therefore identical to the
above example.
-</p>
-<pre class="verbatim"> $> dprofpp
-
- Total Elapsed Time = 20.984 Seconds
- User+System Time = 19.981 Seconds
- Exclusive Times
- %Time ExclSec CumulS #Calls sec/call Csec/c Name
- 49.0 9.792 14.509 251215 0.0000 0.0001 main::matches
- 24.4 4.887 4.887 260643 0.0000 0.0000 main::debug
- 0.25 0.049 0.049 1 0.0490 0.0490 main::report
- 0.00 0.000 0.000 1 0.0000 0.0000 Getopt::Long::GetOptions
- 0.00 0.000 0.000 2 0.0000 0.0000 Getopt::Long::ParseOptionSpec
- 0.00 0.000 0.000 1 0.0000 0.0000 Getopt::Long::FindOption
- 0.00 0.000 0.000 1 0.0000 0.0000 IO::File::new
- 0.00 0.000 0.000 1 0.0000 0.0000 IO::Handle::new
- 0.00 0.000 0.000 1 0.0000 0.0000 Symbol::gensym
- 0.00 0.000 0.000 1 0.0000 0.0000 IO::File::open
-</pre>
-<p>Interestingly we get slightly different results, which is mostly because the
-algorithm which generates the report is different, even though the output file
-format was allegedly identical. The elapsed, user and system times are clearly
-showing the time it took for <code>Devel::Profiler</code> to execute its own
run, but
-the column listings feel more accurate somehow than the ones we had earlier
-from <code>Devel::DProf</code>. The 102% figure has disappeared, for example.
This is
-where we have to use the tools at our disposal, and recognise their pros and
-cons, before using them. Interestingly, the numbers of calls for each
-subroutine are identical in the two reports, it’s the percentages which
differ.
-As the author of <code>Devel::Proviler</code> writes:
-</p>
-<pre class="verbatim"> ...running HTML::Template's test suite under
Devel::DProf shows output()
- taking NO time but Devel::Profiler shows around 10% of the time is in
output().
- I don't know which to trust but my gut tells me something is wrong with
- Devel::DProf. HTML::Template::output() is a big routine that's called for
- every test. Either way, something needs fixing.
-</pre>
-<p>YMMV.
-</p>
-<p>See also <code>Devel::Apache::Profiler</code> which hooks
<code>Devel::Profiler</code> into <code>mod_perl</code>.
-</p>
-<hr>
-<a name="perlperf-Devel_003a_003aSmallProf"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-Devel_003a_003aFastProf" accesskey="n"
rel="next">perlperf Devel::FastProf</a>, Previous: <a
href="#perlperf-Devel_003a_003aProfiler" accesskey="p" rel="prev">perlperf
Devel::Profiler</a>, Up: <a href="#perlperf-PROFILING-TOOLS" accesskey="u"
rel="up">perlperf PROFILING TOOLS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Devel_003a_003aSmallProf"></a>
-<h4 class="subsection">51.6.3 Devel::SmallProf</h4>
-
-<p>The <code>Devel::SmallProf</code> profiler examines the runtime of your
Perl program and
-produces a line-by-line listing to show how many times each line was called,
-and how long each line took to execute. It is called by supplying the familiar
-<code>-d</code> flag to Perl at runtime.
-</p>
-<pre class="verbatim"> $> perl -d:SmallProf wordmatch -f perl5db.pl
-
- <...multiple lines snipped...>
-
- wordmatch report for perl5db.pl:
- lines in file: 9428
- words in file: 50243
- words with special (non-word) characters: 20480
- words with only special (non-word) characters: 7790
- words with only consonants: 4801
- words with only capital letters: 1316
- words with only vowels: 1701
-</pre>
-<p><code>Devel::SmallProf</code> writes it’s output into a file called
<samp>smallprof.out</samp>, by
-default. The format of the file looks like this:
-</p>
-<pre class="verbatim"> <num> <time> <ctime>
<line>:<text>
-</pre>
-<p>When the program has terminated, the output may be examined and sorted using
-any standard text filtering utilities. Something like the following may be
-sufficient:
-</p>
-<pre class="verbatim"> $> cat smallprof.out | grep \d*: | sort -k3 | tac
| head -n20
-
- 251215 1.65674 7.68000 75: if ( $word =~ /($regex)/ ) {
- 251215 0.03264 4.40000 79: debug("word: $i_wd ".($has ?
'matches' :
- 251215 0.02693 4.10000 81: return $has;
- 260643 0.02841 4.07000 128: if ( $debug ) {
- 260643 0.02601 4.04000 126: my $message = shift;
- 251215 0.02641 3.91000 73: my $has = 0;
- 251215 0.03311 3.71000 70: my $i_wd = shift;
- 251215 0.02699 3.69000 72: my $regex = shift;
- 251215 0.02766 3.68000 71: my $word = shift;
- 50243 0.59726 1.00000 59: $count{$i_LINES}{cons} =
- 50243 0.48175 0.92000 61: $count{$i_LINES}{spec} =
- 50243 0.00644 0.89000 56: my $i_cons = matches($i_word, $word,
- 50243 0.48837 0.88000 63: $count{$i_LINES}{caps} =
- 50243 0.00516 0.88000 58: my $i_caps = matches($i_word, $word,
'^[(A-
- 50243 0.00631 0.81000 54: my $i_spec = matches($i_word, $word,
'[^a-
- 50243 0.00496 0.80000 57: my $i_vows = matches($i_word, $word,
- 50243 0.00688 0.80000 53: $i_word++;
- 50243 0.48469 0.79000 62: $count{$i_LINES}{only} =
- 50243 0.48928 0.77000 60: $count{$i_LINES}{vows} =
- 50243 0.00683 0.75000 55: my $i_only = matches($i_word, $word,
'^[^a-
-</pre>
-<p>You can immediately see a slightly different focus to the subroutine
profiling
-modules, and we start to see exactly which line of code is taking the most
-time. That regex line is looking a bit suspicious, for example. Remember that
-these tools are supposed to be used together, there is no single best way to
-profile your code, you need to use the best tools for the job.
-</p>
-<p>See also <code>Apache::SmallProf</code> which hooks
<code>Devel::SmallProf</code> into <code>mod_perl</code>.
-</p>
-<hr>
-<a name="perlperf-Devel_003a_003aFastProf"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-Devel_003a_003aNYTProf" accesskey="n"
rel="next">perlperf Devel::NYTProf</a>, Previous: <a
href="#perlperf-Devel_003a_003aSmallProf" accesskey="p" rel="prev">perlperf
Devel::SmallProf</a>, Up: <a href="#perlperf-PROFILING-TOOLS" accesskey="u"
rel="up">perlperf PROFILING TOOLS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Devel_003a_003aFastProf"></a>
-<h4 class="subsection">51.6.4 Devel::FastProf</h4>
-
-<p><code>Devel::FastProf</code> is another Perl line profiler. This was
written with a view
-to getting a faster line profiler, than is possible with for example
-<code>Devel::SmallProf</code>, because it’s written in <code>C</code>.
To use <code>Devel::FastProf</code>,
-supply the <code>-d</code> argument to Perl:
-</p>
-<pre class="verbatim"> $> perl -d:FastProf wordmatch -f perl5db.pl
-
- <...multiple lines snipped...>
-
- wordmatch report for perl5db.pl:
- lines in file: 9428
- words in file: 50243
- words with special (non-word) characters: 20480
- words with only special (non-word) characters: 7790
- words with only consonants: 4801
- words with only capital letters: 1316
- words with only vowels: 1701
-</pre>
-<p><code>Devel::FastProf</code> writes statistics to the file
<samp>fastprof.out</samp> in the current
-directory. The output file, which can be specified, can be interpreted by
using
-the <code>fprofpp</code> command-line program.
-</p>
-<pre class="verbatim"> $> fprofpp | head -n20
-
- # fprofpp output format is:
- # filename:line time count: source
- wordmatch:75 3.93338 251215: if ( $word =~ /($regex)/ ) {
- wordmatch:79 1.77774 251215: debug("word: $i_wd ".($has ?
'matches' : 'does not match')." chars: /$regex/");
- wordmatch:81 1.47604 251215: return $has;
- wordmatch:126 1.43441 260643: my $message = shift;
- wordmatch:128 1.42156 260643: if ( $debug ) {
- wordmatch:70 1.36824 251215: my $i_wd = shift;
- wordmatch:71 1.36739 251215: my $word = shift;
- wordmatch:72 1.35939 251215: my $regex = shift;
-</pre>
-<p>Straightaway we can see that the number of times each line has been called
is
-identical to the <code>Devel::SmallProf</code> output, and the sequence is
only very
-slightly different based on the ordering of the amount of time each line took
-to execute, <code>if ( $debug ) { </code> and <code>my $message =
shift;</code>, 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.
-</p>
-<p>See also the <a href="DBIx-Profile.html#Top">(DBIx-Profile)</a> which will
profile database queries running
-under the <code>DBIx::*</code> namespace.
-</p>
-<hr>
-<a name="perlperf-Devel_003a_003aNYTProf"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlperf-Devel_003a_003aFastProf" accesskey="p"
rel="prev">perlperf Devel::FastProf</a>, Up: <a
href="#perlperf-PROFILING-TOOLS" accesskey="u" rel="up">perlperf PROFILING
TOOLS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Devel_003a_003aNYTProf"></a>
-<h4 class="subsection">51.6.5 Devel::NYTProf</h4>
-
-<p><code>Devel::NYTProf</code> is the <strong>next generation</strong> of Perl
code profiler, fixing many
-shortcomings in other tools and implementing many cool features. First of all
it
-can be used as either a <em>line</em> profiler, a <em>block</em> or a
<em>subroutine</em>
-profiler, all at once. It can also use sub-microsecond (100ns) resolution on
-systems which provide <code>clock_gettime()</code>. It can be started and
stopped even
-by the program being profiled. It’s a one-line entry to profile
<code>mod_perl</code>
-applications. It’s written in <code>c</code> and is probably the
fastest profiler
-available for Perl. The list of coolness just goes on. Enough of that,
let’s
-see how to it works - just use the familiar <code>-d</code> switch to plug it
in and run
-the code.
-</p>
-<pre class="verbatim"> $> perl -d:NYTProf wordmatch -f perl5db.pl
-
- wordmatch report for perl5db.pl:
- lines in file: 9427
- words in file: 50243
- words with special (non-word) characters: 20480
- words with only special (non-word) characters: 7790
- words with only consonants: 4801
- words with only capital letters: 1316
- words with only vowels: 1701
-</pre>
-<p><code>NYTProf</code> will generate a report database into the file
<samp>nytprof.out</samp> by
-default. Human readable reports can be generated from here by using the
-supplied <code>nytprofhtml</code> (HTML output) and <code>nytprofcsv</code>
(CSV output) programs.
-We’ve used the Unix system <code>html2text</code> utility to convert the
-<samp>nytprof/index.html</samp> file for convenience here.
-</p>
-<pre class="verbatim"> $> html2text nytprof/index.html
-
- Performance Profile Index
- For wordmatch
- Run on Fri Sep 26 13:46:39 2008
- Reported on Fri Sep 26 13:47:23 2008
-
- Top 15 Subroutines -- ordered by exclusive time
- |Calls |P |F |Inclusive|Exclusive|Subroutine |
- | | | |Time |Time | |
- |251215|5 |1 |13.09263 |10.47692 |main:: |matches |
- |260642|2 |1 |2.71199 |2.71199 |main:: |debug |
- |1 |1 |1 |0.21404 |0.21404 |main:: |report |
- |2 |2 |2 |0.00511 |0.00511 |XSLoader:: |load (xsub) |
- |14 |14|7 |0.00304 |0.00298 |Exporter:: |import |
- |3 |1 |1 |0.00265 |0.00254 |Exporter:: |as_heavy |
- |10 |10|4 |0.00140 |0.00140 |vars:: |import |
- |13 |13|1 |0.00129 |0.00109 |constant:: |import |
- |1 |1 |1 |0.00360 |0.00096 |FileHandle:: |import |
- |3 |3 |3 |0.00086 |0.00074 |warnings::register::|import |
- |9 |3 |1 |0.00036 |0.00036 |strict:: |bits |
- |13 |13|13|0.00032 |0.00029 |strict:: |import |
- |2 |2 |2 |0.00020 |0.00020 |warnings:: |import |
- |2 |1 |1 |0.00020 |0.00020 |Getopt::Long:: |ParseOptionSpec|
- |7 |7 |6 |0.00043 |0.00020 |strict:: |unimport |
-
- For more information see the full list of 189 subroutines.
-</pre>
-<p>The first part of the report already shows the critical information
regarding
-which subroutines are using the most time. The next gives some statistics
-about the source files profiled.
-</p>
-<pre class="verbatim"> Source Code Files -- ordered by exclusive
time then name
- |Stmts |Exclusive|Avg. |Reports |Source File
|
- | |Time | | |
|
- |2699761|15.66654 |6e-06 |line . block . sub|wordmatch
|
- |35 |0.02187 |0.00062|line . block . sub|IO/Handle.pm
|
- |274 |0.01525 |0.00006|line . block . sub|Getopt/Long.pm
|
- |20 |0.00585 |0.00029|line . block . sub|Fcntl.pm
|
- |128 |0.00340 |0.00003|line . block . sub|Exporter/Heavy.pm
|
- |42 |0.00332 |0.00008|line . block . sub|IO/File.pm
|
- |261 |0.00308 |0.00001|line . block . sub|Exporter.pm
|
- |323 |0.00248 |8e-06 |line . block . sub|constant.pm
|
- |12 |0.00246 |0.00021|line . block . sub|File/Spec/Unix.pm
|
- |191 |0.00240 |0.00001|line . block . sub|vars.pm
|
- |77 |0.00201 |0.00003|line . block . sub|FileHandle.pm
|
- |12 |0.00198 |0.00016|line . block . sub|Carp.pm
|
- |14 |0.00175 |0.00013|line . block . sub|Symbol.pm
|
- |15 |0.00130 |0.00009|line . block . sub|IO.pm
|
- |22 |0.00120 |0.00005|line . block . sub|IO/Seekable.pm
|
- |198 |0.00085 |4e-06 |line . block .
sub|warnings/register.pm|
- |114 |0.00080 |7e-06 |line . block . sub|strict.pm
|
- |47 |0.00068 |0.00001|line . block . sub|warnings.pm
|
- |27 |0.00054 |0.00002|line . block . sub|overload.pm
|
- |9 |0.00047 |0.00005|line . block . sub|SelectSaver.pm
|
- |13 |0.00045 |0.00003|line . block . sub|File/Spec.pm
|
- |2701595|15.73869 | |Total |
- |128647 |0.74946 | |Average |
- | |0.00201 |0.00003|Median |
- | |0.00121 |0.00003|Deviation |
-
- Report produced by the NYTProf 2.03 Perl profiler, developed by Tim Bunce
and
- Adam Kaplan.
-</pre>
-<p>At this point, if you’re using the <em>html</em> report, you can
click through the
-various links to bore down into each subroutine and each line of code. Because
-we’re using the text reporting here, and there’s a whole directory
full of
-reports built for each source file, we’ll just display a part of the
-corresponding <samp>wordmatch-line.html</samp> file, sufficient to give an
idea of the
-sort of output you can expect from this cool tool.
-</p>
-<pre class="verbatim"> $> html2text nytprof/wordmatch-line.html
-
- Performance Profile -- -block view-.-line view-.-sub view-
- For wordmatch
- Run on Fri Sep 26 13:46:39 2008
- Reported on Fri Sep 26 13:47:22 2008
-
- File wordmatch
-
- Subroutines -- ordered by exclusive time
- |Calls |P|F|Inclusive|Exclusive|Subroutine |
- | | | |Time |Time | |
- |251215|5|1|13.09263 |10.47692 |main::|matches|
- |260642|2|1|2.71199 |2.71199 |main::|debug |
- |1 |1|1|0.21404 |0.21404 |main::|report |
- |0 |0|0|0 |0 |main::|BEGIN |
-
-
- |Line|Stmts.|Exclusive|Avg. |Code
|
- | | |Time | |
|
- |1 | | | |#!/usr/bin/perl
|
- |2 | | | |
|
- | | | | |use strict;
|
- |3 |3 |0.00086 |0.00029|# spent 0.00003s making 1 calls to strict::
|
- | | | | |import
|
- | | | | |use warnings;
|
- |4 |3 |0.01563 |0.00521|# spent 0.00012s making 1 calls to
warnings:: |
- | | | | |import
|
- |5 | | | |
|
- |6 | | | |=head1 NAME
|
- |7 | | | |
|
- |8 | | | |filewords - word analysis of input file
|
- <...snip...>
- |62 |1 |0.00445 |0.00445|print report( %count );
|
- | | | | |# spent 0.21404s making 1 calls to
main::report|
- |63 | | | |
|
- | | | | |# spent 23.56955s (10.47692+2.61571) within
|
- | | | | |main::matches which was called 251215
times, |
- | | | | |avg 0.00005s/call: # 50243 times
|
- | | | | |(2.12134+0.51939s) at line 57 of wordmatch,
avg|
- | | | | |0.00005s/call # 50243 times
(2.17735+0.54550s) |
- |64 | | | |at line 56 of wordmatch, avg 0.00005s/call
# |
- | | | | |50243 times (2.10992+0.51797s) at line 58
of |
- | | | | |wordmatch, avg 0.00005s/call # 50243 times
|
- | | | | |(2.12696+0.51598s) at line 55 of wordmatch,
avg|
- | | | | |0.00005s/call # 50243 times
(1.94134+0.51687s) |
- | | | | |at line 54 of wordmatch, avg 0.00005s/call
|
- | | | | |sub matches {
|
- <...snip...>
- |102 | | | |
|
- | | | | |# spent 2.71199s within main::debug which
was |
- | | | | |called 260642 times, avg 0.00001s/call: #
|
- | | | | |251215 times (2.61571+0s) by main::matches
at |
- |103 | | | |line 74 of wordmatch, avg 0.00001s/call #
9427 |
- | | | | |times (0.09628+0s) at line 50 of wordmatch,
avg|
- | | | | |0.00001s/call
|
- | | | | |sub debug {
|
- |104 |260642|0.58496 |2e-06 |my $message = shift;
|
- |105 | | | |
|
- |106 |260642|1.09917 |4e-06 |if ( $debug ) {
|
- |107 | | | |print STDERR "DBG: $message\n";
|
- |108 | | | |}
|
- |109 | | | |}
|
- |110 | | | |
|
- |111 |1 |0.01501 |0.01501|exit 0;
|
- |112 | | | |
|
-</pre>
-<p>Oodles of very useful information in there - this seems to be the way
forward.
-</p>
-<p>See also <code>Devel::NYTProf::Apache</code> which hooks
<code>Devel::NYTProf</code> into <code>mod_perl</code>.
-</p>
-<hr>
-<a name="perlperf-SORTING"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-LOGGING" accesskey="n" rel="next">perlperf
LOGGING</a>, Previous: <a href="#perlperf-PROFILING-TOOLS" accesskey="p"
rel="prev">perlperf PROFILING TOOLS</a>, Up: <a href="#perlperf" accesskey="u"
rel="up">perlperf</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SORTING-1"></a>
-<h3 class="section">51.7 SORTING</h3>
-
-<p>Perl modules are not the only tools a performance analyst has at their
-disposal, system tools like <code>time</code> should not be overlooked as the
next
-example shows, where we take a quick look at sorting. Many books, theses and
-articles, have been written about efficient sorting algorithms, and this is not
-the place to repeat such work, there’s several good sorting modules which
-deserve taking a look at too: <code>Sort::Maker</code>, <code>Sort::Key</code>
spring to mind.
-However, it’s still possible to make some observations on certain Perl
specific
-interpretations on issues relating to sorting data sets and give an example or
-two with regard to how sorting large data volumes can effect performance.
-Firstly, an often overlooked point when sorting large amounts of data, one can
-attempt to reduce the data set to be dealt with and in many cases
<code>grep()</code> can
-be quite useful as a simple filter:
-</p>
-<pre class="verbatim"> @data = sort grep { /$filter/ } @incoming
-</pre>
-<p>A command such as this can vastly reduce the volume of material to actually
-sort through in the first place, and should not be too lightly disregarded
-purely on the basis of its simplicity. The <code>KISS</code> principle is too
often
-overlooked - the next example uses the simple system <code>time</code> utility
to
-demonstrate. Let’s take a look at an actual example of sorting the
contents of
-a large file, an apache logfile would do. This one has over a quarter of a
-million lines, is 50M in size, and a snippet of it looks like this:
-</p>
-<p># logfile
-</p>
-<pre class="verbatim"> 188.209-65-87.adsl-dyn.isp.belgacom.be - -
[08/Feb/2007:12:57:16 +0000] "GET /favicon.ico HTTP/1.1" 404 209
"-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1;
SV1)"
- 188.209-65-87.adsl-dyn.isp.belgacom.be - - [08/Feb/2007:12:57:16 +0000]
"GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/4.0
(compatible; MSIE 6.0; Windows NT 5.1; SV1)"
- 151.56.71.198 - - [08/Feb/2007:12:57:41 +0000] "GET
/suse-on-vaio.html HTTP/1.1" 200 2858
"http://www.linux-on-laptops.com/sony.html" "Mozilla/5.0
(Windows; U; Windows NT 5.2; en-US; rv:1.8.1.1) Gecko/20061204
Firefox/2.0.0.1"
- 151.56.71.198 - - [08/Feb/2007:12:57:42 +0000] "GET /data/css
HTTP/1.1" 404 206 "http://www.rfi.net/suse-on-vaio.html"
"Mozilla/5.0 (Windows; U; Windows NT 5.2; en-US; rv:1.8.1.1)
Gecko/20061204 Firefox/2.0.0.1"
- 151.56.71.198 - - [08/Feb/2007:12:57:43 +0000] "GET /favicon.ico
HTTP/1.1" 404 209 "-" "Mozilla/5.0 (Windows; U; Windows NT
5.2; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1"
- 217.113.68.60 - - [08/Feb/2007:13:02:15 +0000] "GET / HTTP/1.1"
304 - "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1;
SV1)"
- 217.113.68.60 - - [08/Feb/2007:13:02:16 +0000] "GET /data/css
HTTP/1.1" 404 206 "http://www.rfi.net/" "Mozilla/4.0
(compatible; MSIE 6.0; Windows NT 5.1; SV1)"
- debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET
/suse-on-vaio.html HTTP/1.1" 200 2858
"http://www.linux-on-laptops.com/sony.html" "Mozilla/5.0
(compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)"
- debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET /data/css
HTTP/1.1" 404 206 "http://www.rfi.net/suse-on-vaio.html"
"Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like
Gecko)"
- debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET
/favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/5.0
(compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)"
- 195.24.196.99 - - [08/Feb/2007:13:26:48 +0000] "GET / HTTP/1.0"
200 3309 "-" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr;
rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9"
- 195.24.196.99 - - [08/Feb/2007:13:26:58 +0000] "GET /data/css
HTTP/1.0" 404 206 "http://www.rfi.net/" "Mozilla/5.0
(Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206
Firefox/1.5.0.9"
- 195.24.196.99 - - [08/Feb/2007:13:26:59 +0000] "GET /favicon.ico
HTTP/1.0" 404 209 "-" "Mozilla/5.0 (Windows; U; Windows NT
5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9"
- crawl1.cosmixcorp.com - - [08/Feb/2007:13:27:57 +0000] "GET
/robots.txt HTTP/1.0" 200 179 "-" "voyager/1.0"
- crawl1.cosmixcorp.com - - [08/Feb/2007:13:28:25 +0000] "GET
/links.html HTTP/1.0" 200 3413 "-" "voyager/1.0"
- fhm226.internetdsl.tpnet.pl - - [08/Feb/2007:13:37:32 +0000] "GET
/suse-on-vaio.html HTTP/1.1" 200 2858
"http://www.linux-on-laptops.com/sony.html" "Mozilla/4.0
(compatible; MSIE 6.0; Windows NT 5.1; SV1)"
- fhm226.internetdsl.tpnet.pl - - [08/Feb/2007:13:37:34 +0000] "GET
/data/css HTTP/1.1" 404 206
"http://www.rfi.net/suse-on-vaio.html" "Mozilla/4.0 (compatible;
MSIE 6.0; Windows NT 5.1; SV1)"
- 80.247.140.134 - - [08/Feb/2007:13:57:35 +0000] "GET / HTTP/1.1"
200 3309 "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1;
.NET CLR 1.1.4322)"
- 80.247.140.134 - - [08/Feb/2007:13:57:37 +0000] "GET /data/css
HTTP/1.1" 404 206 "http://www.rfi.net" "Mozilla/4.0
(compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)"
- pop.compuscan.co.za - - [08/Feb/2007:14:10:43 +0000] "GET /
HTTP/1.1" 200 3309 "-" "www.clamav.net"
- livebot-207-46-98-57.search.live.com - - [08/Feb/2007:14:12:04 +0000]
"GET /robots.txt HTTP/1.0" 200 179 "-" "msnbot/1.0
(+http://search.msn.com/msnbot.htm)"
- livebot-207-46-98-57.search.live.com - - [08/Feb/2007:14:12:04 +0000]
"GET /html/oracle.html HTTP/1.0" 404 214 "-"
"msnbot/1.0 (+http://search.msn.com/msnbot.htm)"
- dslb-088-064-005-154.pools.arcor-ip.net - - [08/Feb/2007:14:12:15 +0000]
"GET / HTTP/1.1" 200 3309 "-" "www.clamav.net"
- 196.201.92.41 - - [08/Feb/2007:14:15:01 +0000] "GET / HTTP/1.1"
200 3309 "-" "MOT-L7/08.B7.DCR MIB/2.2.1 Profile/MIDP-2.0
Configuration/CLDC-1.1"
-</pre>
-<p>The specific task here is to sort the 286,525 lines of this file by Response
-Code, Query, Browser, Referring Url, and lastly Date. One solution might be to
-use the following code, which iterates over the files given on the
-command-line.
-</p>
-<p># sort-apache-log
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -n
-
- use strict;
- use warnings;
-
- my @data;
-
- LINE:
- while ( <> ) {
- my $line = $_;
- if (
- $line =~ m/^(
- ([\w\.\-]+) # client
- \s*-\s*-\s*\[
- ([^]]+) # date
- \]\s*"\w+\s*
- (\S+) # query
- [^"]+"\s*
- (\d+) # status
- \s+\S+\s+"[^"]*"\s+"
- ([^"]*) # browser
- "
- .*
- )$/x
- ) {
- my @chunks = split(/ +/, $line);
- my $ip = $1;
- my $date = $2;
- my $query = $3;
- my $status = $4;
- my $browser = $5;
-
- push(@data, [$ip, $date, $query, $status, $browser, $line]);
- }
- }
-
- my @sorted = sort {
- $a->[3] cmp $b->[3]
- ||
- $a->[2] cmp $b->[2]
- ||
- $a->[0] cmp $b->[0]
- ||
- $a->[1] cmp $b->[1]
- ||
- $a->[4] cmp $b->[4]
- } @data;
-
- foreach my $data ( @sorted ) {
- print $data->[5];
- }
-
- exit 0;
-</pre>
-<p>When running this program, redirect <code>STDOUT</code> so it is possible
to check the
-output is correct from following test runs and use the system
<code>time</code> utility
-to check the overall runtime.
-</p>
-<pre class="verbatim"> $> time ./sort-apache-log logfile > out-sort
-
- real 0m17.371s
- user 0m15.757s
- sys 0m0.592s
-</pre>
-<p>The program took just over 17 wallclock seconds to run. Note the different
-values <code>time</code> outputs, it’s important to always use the same
one, and to not
-confuse what each one means.
-</p>
-<dl compact="compact">
-<dt>Elapsed Real Time</dt>
-<dd><a name="perlperf-Elapsed-Real-Time"></a>
-<p>The overall, or wallclock, time between when <code>time</code> was called,
and when it
-terminates. The elapsed time includes both user and system times, and time
-spent waiting for other users and processes on the system. Inevitably, this is
-the most approximate of the measurements given.
-</p>
-</dd>
-<dt>User CPU Time</dt>
-<dd><a name="perlperf-User-CPU-Time"></a>
-<p>The user time is the amount of time the entire process spent on behalf of
the
-user on this system executing this program.
-</p>
-</dd>
-<dt>System CPU Time</dt>
-<dd><a name="perlperf-System-CPU-Time"></a>
-<p>The system time is the amount of time the kernel itself spent executing
-routines, or system calls, on behalf of this process user.
-</p>
-</dd>
-</dl>
-
-<p>Running this same process as a <code>Schwarzian Transform</code> it is
possible to
-eliminate the input and output arrays for storing all the data, and work on the
-input directly as it arrives too. Otherwise, the code looks fairly similar:
-</p>
-<p># sort-apache-log-schwarzian
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -n
-
- use strict;
- use warnings;
-
- print
-
- map $_->[0] =>
-
- sort {
- $a->[4] cmp $b->[4]
- ||
- $a->[3] cmp $b->[3]
- ||
- $a->[1] cmp $b->[1]
- ||
- $a->[2] cmp $b->[2]
- ||
- $a->[5] cmp $b->[5]
- }
- map [ $_, m/^(
- ([\w\.\-]+) # client
- \s*-\s*-\s*\[
- ([^]]+) # date
- \]\s*"\w+\s*
- (\S+) # query
- [^"]+"\s*
- (\d+) # status
- \s+\S+\s+"[^"]*"\s+"
- ([^"]*) # browser
- "
- .*
- )$/xo ]
-
- => <>;
-
- exit 0;
-</pre>
-<p>Run the new code against the same logfile, as above, to check the new time.
-</p>
-<pre class="verbatim"> $> time ./sort-apache-log-schwarzian logfile >
out-schwarz
-
- real 0m9.664s
- user 0m8.873s
- sys 0m0.704s
-</pre>
-<p>The time has been cut in half, which is a respectable speed improvement by
any
-standard. Naturally, it is important to check the output is consistent with
-the first program run, this is where the Unix system <code>cksum</code>
utility comes in.
-</p>
-<pre class="verbatim"> $> cksum out-sort out-schwarz
- 3044173777 52029194 out-sort
- 3044173777 52029194 out-schwarz
-</pre>
-<p>BTW. Beware too of pressure from managers who see you speed a program up by
50%
-of the runtime once, only to get a request one month later to do the same again
-(true story) - you’ll just have to point out you’re only human,
even if you are a
-Perl programmer, and you’ll see what you can do...
-</p>
-<hr>
-<a name="perlperf-LOGGING"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-POSTSCRIPT" accesskey="n" rel="next">perlperf
POSTSCRIPT</a>, Previous: <a href="#perlperf-SORTING" accesskey="p"
rel="prev">perlperf SORTING</a>, Up: <a href="#perlperf" accesskey="u"
rel="up">perlperf</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="LOGGING"></a>
-<h3 class="section">51.8 LOGGING</h3>
-
-<p>An essential part of any good development process is appropriate error
handling
-with appropriately informative messages, however there exists a school of
-thought which suggests that log files should be <em>chatty</em>, as if the
chain of
-unbroken output somehow ensures the survival of the program. If speed is in
-any way an issue, this approach is wrong.
-</p>
-<p>A common sight is code which looks something like this:
-</p>
-<pre class="verbatim"> logger->debug( "A logging message via
process-id: $$ INC: " . Dumper(\%INC) )
-</pre>
-<p>The problem is that this code will always be parsed and executed, even when
the
-debug level set in the logging configuration file is zero. Once the debug()
-subroutine has been entered, and the internal <code>$debug</code> variable
confirmed to
-be zero, for example, the message which has been sent in will be discarded and
-the program will continue. In the example given though, the
<code>\%INC</code> hash will
-already have been dumped, and the message string constructed, all of which work
-could be bypassed by a debug variable at the statement level, like this:
-</p>
-<pre class="verbatim"> logger->debug( "A logging message via
process-id: $$ INC: " . Dumper(\%INC) ) if $DEBUG;
-</pre>
-<p>This effect can be demonstrated by setting up a test script with both forms,
-including a <code>debug()</code> subroutine to emulate typical
<code>logger()</code> functionality.
-</p>
-<p># ifdebug
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
-
- use strict;
- use warnings;
-
- use Benchmark;
- use Data::Dumper;
- my $DEBUG = 0;
-
- sub debug {
- my $msg = shift;
-
- if ( $DEBUG ) {
- print "DEBUG: $msg\n";
- }
- };
-
- timethese(100000, {
- 'debug' => sub {
- debug( "A $0 logging message via process-id: $$" .
Dumper(\%INC) )
- },
- 'ifdebug' => sub {
- debug( "A $0 logging message via process-id: $$" .
Dumper(\%INC) ) if $DEBUG
- },
- });
-</pre>
-<p>Let’s see what <code>Benchmark</code> makes of this:
-</p>
-<pre class="verbatim"> $> perl ifdebug
- Benchmark: timing 100000 iterations of constant, sub...
- ifdebug: 0 wallclock secs ( 0.01 usr + 0.00 sys = 0.01 CPU) @
10000000.00/s (n=100000)
- (warning: too few iterations for a reliable count)
- debug: 14 wallclock secs (13.18 usr + 0.04 sys = 13.22 CPU) @
7564.30/s (n=100000)
-</pre>
-<p>In the one case the code, which does exactly the same thing as far as
-outputting any debugging information is concerned, in other words nothing,
-takes 14 seconds, and in the other case the code takes one hundredth of a
-second. Looks fairly definitive. Use a <code>$DEBUG</code> variable BEFORE
you call the
-subroutine, rather than relying on the smart functionality inside it.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlperf-Logging-if-DEBUG-_0028constant_0029" accesskey="1">perlperf
Logging if DEBUG (constant)</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlperf-Logging-if-DEBUG-_0028constant_0029"></a>
-<div class="header">
-<p>
-Up: <a href="#perlperf-LOGGING" accesskey="u" rel="up">perlperf LOGGING</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Logging-if-DEBUG-_0028constant_0029"></a>
-<h4 class="subsection">51.8.1 Logging if DEBUG (constant)</h4>
-
-<p>It’s possible to take the previous idea a little further, by using a
compile
-time <code>DEBUG</code> constant.
-</p>
-<p># ifdebug-constant
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
-
- use strict;
- use warnings;
-
- use Benchmark;
- use Data::Dumper;
- use constant
- DEBUG => 0
- ;
-
- sub debug {
- if ( DEBUG ) {
- my $msg = shift;
- print "DEBUG: $msg\n";
- }
- };
-
- timethese(100000, {
- 'debug' => sub {
- debug( "A $0 logging message via process-id: $$" .
Dumper(\%INC) )
- },
- 'constant' => sub {
- debug( "A $0 logging message via process-id: $$" .
Dumper(\%INC) ) if DEBUG
- },
- });
-</pre>
-<p>Running this program produces the following output:
-</p>
-<pre class="verbatim"> $> perl ifdebug-constant
- Benchmark: timing 100000 iterations of constant, sub...
- constant: 0 wallclock secs (-0.00 usr + 0.00 sys = -0.00 CPU) @
-7205759403792793600000.00/s (n=100000)
- (warning: too few iterations for a reliable count)
- sub: 14 wallclock secs (13.09 usr + 0.00 sys = 13.09 CPU) @
7639.42/s (n=100000)
-</pre>
-<p>The <code>DEBUG</code> constant wipes the floor with even the
<code>$debug</code> variable,
-clocking in at minus zero seconds, and generates a "warning: too few
iterations
-for a reliable count" message into the bargain. To see what is really
going
-on, and why we had too few iterations when we thought we asked for 100000, we
-can use the very useful <code>B::Deparse</code> to inspect the new code:
-</p>
-<pre class="verbatim"> $> perl -MO=Deparse ifdebug-constant
-
- use Benchmark;
- use Data::Dumper;
- use constant ('DEBUG', 0);
- sub debug {
- use warnings;
- use strict 'refs';
- 0;
- }
- use warnings;
- use strict 'refs';
- timethese(100000, {'sub', sub {
- debug "A $0 logging message via process-id: $$" .
Dumper(\%INC);
- }
- , 'constant', sub {
- 0;
- }
- });
- ifdebug-constant syntax OK
-</pre>
-<p>The output shows the constant() subroutine we’re testing being
replaced with
-the value of the <code>DEBUG</code> constant: zero. The line to be tested has
been
-completely optimized away, and you can’t get much more efficient than
that.
-</p>
-<hr>
-<a name="perlperf-POSTSCRIPT"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-SEE-ALSO" accesskey="n" rel="next">perlperf SEE
ALSO</a>, Previous: <a href="#perlperf-LOGGING" accesskey="p"
rel="prev">perlperf LOGGING</a>, Up: <a href="#perlperf" accesskey="u"
rel="up">perlperf</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="POSTSCRIPT"></a>
-<h3 class="section">51.9 POSTSCRIPT</h3>
-
-<p>This document has provided several way to go about identifying hot-spots,
and
-checking whether any modifications have improved the runtime of the code.
-</p>
-<p>As a final thought, remember that it’s not (at the time of writing)
possible to
-produce a useful program which will run in zero or negative time and this basic
-principle can be written as: <em>useful programs are slow</em> by their very
-definition. It is of course possible to write a nearly instantaneous program,
-but it’s not going to do very much, here’s a very efficient one:
-</p>
-<pre class="verbatim"> $> perl -e 0
-</pre>
-<p>Optimizing that any further is a job for <code>p5p</code>.
-</p>
-<hr>
-<a name="perlperf-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-AUTHOR" accesskey="n" rel="next">perlperf AUTHOR</a>,
Previous: <a href="#perlperf-POSTSCRIPT" accesskey="p" rel="prev">perlperf
POSTSCRIPT</a>, Up: <a href="#perlperf" accesskey="u" rel="up">perlperf</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-25"></a>
-<h3 class="section">51.10 SEE ALSO</h3>
-
-<p>Further reading can be found using the modules and links below.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlperf-PERLDOCS"
accesskey="1">perlperf PERLDOCS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-MAN-PAGES"
accesskey="2">perlperf MAN PAGES</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-MODULES"
accesskey="3">perlperf MODULES</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlperf-URLS"
accesskey="4">perlperf URLS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlperf-PERLDOCS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-MAN-PAGES" accesskey="n" rel="next">perlperf MAN
PAGES</a>, Up: <a href="#perlperf-SEE-ALSO" accesskey="u" rel="up">perlperf SEE
ALSO</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="PERLDOCS"></a>
-<h4 class="subsection">51.10.1 PERLDOCS</h4>
-
-<p>For example: <code>perldoc -f sort</code>.
-</p>
-<p><a href="perlfaq4.html#Top">(perlfaq4)</a>.
-</p>
-<p><a href="#perlfork-NAME">perlfork NAME</a>, <a
href="#perlfunc-NAME">perlfunc NAME</a>, <a href="#perlretut-NAME">perlretut
NAME</a>, <a href="#perlthrtut-NAME">perlthrtut NAME</a>.
-</p>
-<p><a href="threads.html#Top">(threads)</a>.
-</p>
-<hr>
-<a name="perlperf-MAN-PAGES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-MODULES" accesskey="n" rel="next">perlperf
MODULES</a>, Previous: <a href="#perlperf-PERLDOCS" accesskey="p"
rel="prev">perlperf PERLDOCS</a>, Up: <a href="#perlperf-SEE-ALSO"
accesskey="u" rel="up">perlperf SEE ALSO</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="MAN-PAGES"></a>
-<h4 class="subsection">51.10.2 MAN PAGES</h4>
-
-<p><code>time</code>.
-</p>
-<hr>
-<a name="perlperf-MODULES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlperf-URLS" accesskey="n" rel="next">perlperf URLS</a>,
Previous: <a href="#perlperf-MAN-PAGES" accesskey="p" rel="prev">perlperf MAN
PAGES</a>, Up: <a href="#perlperf-SEE-ALSO" accesskey="u" rel="up">perlperf SEE
ALSO</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="MODULES"></a>
-<h4 class="subsection">51.10.3 MODULES</h4>
-
-<p>It’s not possible to individually showcase all the performance
related code for
-Perl here, naturally, but here’s a short list of modules from the CPAN
which
-deserve further attention.
-</p>
-<pre class="verbatim"> Apache::DProf
- Apache::SmallProf
- Benchmark
- DBIx::Profile
- Devel::AutoProfiler
- Devel::DProf
- Devel::DProfLB
- Devel::FastProf
- Devel::GraphVizProf
- Devel::NYTProf
- Devel::NYTProf::Apache
- Devel::Profiler
- Devel::Profile
- Devel::Profit
- Devel::SmallProf
- Devel::WxProf
- POE::Devel::Profiler
- Sort::Key
- Sort::Maker
-</pre>
-<hr>
-<a name="perlperf-URLS"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlperf-MODULES" accesskey="p" rel="prev">perlperf
MODULES</a>, Up: <a href="#perlperf-SEE-ALSO" accesskey="u" rel="up">perlperf
SEE ALSO</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="URLS"></a>
-<h4 class="subsection">51.10.4 URLS</h4>
-
-<p>Very useful online reference material:
-</p>
-<pre class="verbatim"> http://www.ccl4.org/~nick/P/Fast_Enough/
-
- http://www-128.ibm.com/developerworks/library/l-optperl.html
-
-
http://perlbuzz.com/2007/11/bind-output-variables-in-dbi-for-speed-and-safety.html
-
- http://en.wikipedia.org/wiki/Performance_analysis
-
- http://apache.perl.org/docs/1.0/guide/performance.html
-
- http://perlgolf.sourceforge.net/
-
- http://www.sysarch.com/Perl/sort_paper.html
-</pre>
-<hr>
-<a name="perlperf-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlperf-SEE-ALSO" accesskey="p" rel="prev">perlperf SEE
ALSO</a>, Up: <a href="#perlperf" accesskey="u" rel="up">perlperf</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-21"></a>
-<h3 class="section">51.11 AUTHOR</h3>
-
-<p>Richard Foley <address@hidden> Copyright (c) 2008
-</p>
-<hr>
-<a name="perlpod"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodspec" accesskey="n" rel="next">perlpodspec</a>,
Previous: <a href="#perlperf" accesskey="p" rel="prev">perlperf</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlpod-1"></a>
-<h2 class="chapter">52 perlpod</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlpod-NAME"
accesskey="1">perlpod NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpod-DESCRIPTION"
accesskey="2">perlpod DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpod-SEE-ALSO"
accesskey="3">perlpod SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpod-AUTHOR"
accesskey="4">perlpod AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpod-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpod-DESCRIPTION" accesskey="n" rel="next">perlpod
DESCRIPTION</a>, Up: <a href="#perlpod" accesskey="u" rel="up">perlpod</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-51"></a>
-<h3 class="section">52.1 NAME</h3>
-
-<p>perlpod - the Plain Old Documentation format
-</p>
-<hr>
-<a name="perlpod-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpod-SEE-ALSO" accesskey="n" rel="next">perlpod SEE
ALSO</a>, Previous: <a href="#perlpod-NAME" accesskey="p" rel="prev">perlpod
NAME</a>, Up: <a href="#perlpod" accesskey="u" rel="up">perlpod</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-50"></a>
-<h3 class="section">52.2 DESCRIPTION</h3>
-
-<p>Pod is a simple-to-use markup language used for writing documentation
-for Perl, Perl programs, and Perl modules.
-</p>
-<p>Translators are available for converting Pod to various formats
-like plain text, HTML, man pages, and more.
-</p>
-<p>Pod markup consists of three basic kinds of paragraphs:
-<a href="#perlpod-Ordinary-Paragraph">ordinary</a>,
-<a href="#perlpod-Verbatim-Paragraph">verbatim</a>, and
-<a href="#perlpod-Command-Paragraph">command</a>.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlpod-Ordinary-Paragraph"
accesskey="1">perlpod Ordinary Paragraph</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpod-Verbatim-Paragraph"
accesskey="2">perlpod Verbatim Paragraph</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpod-Command-Paragraph"
accesskey="3">perlpod Command Paragraph</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpod-Formatting-Codes"
accesskey="4">perlpod Formatting Codes</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpod-The-Intent"
accesskey="5">perlpod The Intent</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpod-Embedding-Pods-in-Perl-Modules" accesskey="6">perlpod Embedding
Pods in Perl Modules</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpod-Hints-for-Writing-Pod" accesskey="7">perlpod Hints for Writing
Pod</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpod-Ordinary-Paragraph"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpod-Verbatim-Paragraph" accesskey="n" rel="next">perlpod
Verbatim Paragraph</a>, Up: <a href="#perlpod-DESCRIPTION" accesskey="u"
rel="up">perlpod DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Ordinary-Paragraph"></a>
-<h4 class="subsection">52.2.1 Ordinary Paragraph</h4>
-
-<p>Most paragraphs in your documentation will be ordinary blocks
-of text, like this one. You can simply type in your text without
-any markup whatsoever, and with just a blank line before and
-after. When it gets formatted, it will undergo minimal formatting,
-like being rewrapped, probably put into a proportionally spaced
-font, and maybe even justified.
-</p>
-<p>You can use formatting codes in ordinary paragraphs, for
<strong>bold</strong>,
-<em>italic</em>, <code>code-style</code>, <a
href="perlfaq.html#Top">(perlfaq)hyperlinks</a>, and more. Such
-codes are explained in the "<a
href="#perlpod-Formatting-Codes">Formatting Codes</a>"
-section, below.
-</p>
-<hr>
-<a name="perlpod-Verbatim-Paragraph"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpod-Command-Paragraph" accesskey="n" rel="next">perlpod
Command Paragraph</a>, Previous: <a href="#perlpod-Ordinary-Paragraph"
accesskey="p" rel="prev">perlpod Ordinary Paragraph</a>, Up: <a
href="#perlpod-DESCRIPTION" accesskey="u" rel="up">perlpod DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Verbatim-Paragraph"></a>
-<h4 class="subsection">52.2.2 Verbatim Paragraph</h4>
-
-<p>Verbatim paragraphs are usually used for presenting a codeblock or
-other text which does not require any special parsing or formatting,
-and which shouldn’t be wrapped.
-</p>
-<p>A verbatim paragraph is distinguished by having its first character
-be a space or a tab. (And commonly, all its lines begin with spaces
-and/or tabs.) It should be reproduced exactly, with tabs assumed to
-be on 8-column boundaries. There are no special formatting codes,
-so you can’t italicize or anything like that. A \ means \, and
-nothing else.
-</p>
-<hr>
-<a name="perlpod-Command-Paragraph"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpod-Formatting-Codes" accesskey="n" rel="next">perlpod
Formatting Codes</a>, Previous: <a href="#perlpod-Verbatim-Paragraph"
accesskey="p" rel="prev">perlpod Verbatim Paragraph</a>, Up: <a
href="#perlpod-DESCRIPTION" accesskey="u" rel="up">perlpod DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Command-Paragraph"></a>
-<h4 class="subsection">52.2.3 Command Paragraph</h4>
-
-<p>A command paragraph is used for special treatment of whole chunks
-of text, usually as headings or parts of lists.
-</p>
-<p>All command paragraphs (which are typically only one line long) start
-with "=", followed by an identifier, followed by arbitrary text that
-the command can use however it pleases. Currently recognized commands
-are
-</p>
-<pre class="verbatim"> =pod
- =head1 Heading Text
- =head2 Heading Text
- =head3 Heading Text
- =head4 Heading Text
- =over indentlevel
- =item stuff
- =back
- =begin format
- =end format
- =for format text...
- =encoding type
- =cut
-</pre>
-<p>To explain them each in detail:
-</p>
-<dl compact="compact">
-<dt><code>=head1 <em>Heading Text</em></code></dt>
-<dd><a name="perlpod-_003dhead1-Heading-Text"></a>
-</dd>
-<dt><code>=head2 <em>Heading Text</em></code></dt>
-<dd><a name="perlpod-_003dhead2-Heading-Text"></a>
-</dd>
-<dt><code>=head3 <em>Heading Text</em></code></dt>
-<dd><a name="perlpod-_003dhead3-Heading-Text"></a>
-</dd>
-<dt><code>=head4 <em>Heading Text</em></code></dt>
-<dd><a name="perlpod-_003dhead4-Heading-Text"></a>
-<p>Head1 through head4 produce headings, head1 being the highest
-level. The text in the rest of this paragraph is the content of the
-heading. For example:
-</p>
-<pre class="verbatim"> =head2 Object Attributes
-</pre>
-<p>The text "Object Attributes" comprises the heading there.
-The text in these heading commands can use formatting codes, as seen here:
-</p>
-<pre class="verbatim"> =head2 Possible Values for C<$/>
-</pre>
-<p>Such commands are explained in the
-"<a href="#perlpod-Formatting-Codes">Formatting Codes</a>" section,
below.
-</p>
-</dd>
-<dt><code>=over <em>indentlevel</em></code></dt>
-<dd><a name="perlpod-_003dover-indentlevel"></a>
-</dd>
-<dt><code>=item <em>stuff...</em></code></dt>
-<dd><a name="perlpod-_003ditem-stuff_002e_002e_002e"></a>
-</dd>
-<dt><code>=back</code></dt>
-<dd><a name="perlpod-_003dback"></a>
-<p>Item, over, and back require a little more explanation: "=over"
starts
-a region specifically for the generation of a list using "=item"
-commands, or for indenting (groups of) normal paragraphs. At the end
-of your list, use "=back" to end it. The <em>indentlevel</em>
option to
-"=over" indicates how far over to indent, generally in ems (where
-one em is the width of an "M" in the document’s base font) or
roughly
-comparable units; if there is no <em>indentlevel</em> option, it defaults
-to four. (And some formatters may just ignore whatever <em>indentlevel</em>
-you provide.) In the <em>stuff</em> in <code>=item <em>stuff...</em></code>,
you may
-use formatting codes, as seen here:
-</p>
-<pre class="verbatim"> =item Using C<$|> to Control Buffering
-</pre>
-<p>Such commands are explained in the
-"<a href="#perlpod-Formatting-Codes">Formatting Codes</a>" section,
below.
-</p>
-<p>Note also that there are some basic rules to using "=over" ...
-"=back" regions:
-</p>
-<ul>
-<li> Don’t use "=item"s outside of an "=over" ...
"=back" region.
-
-</li><li> The first thing after the "=over" command should be an
"=item", unless
-there aren’t going to be any items at all in this "=over" ...
"=back"
-region.
-
-</li><li> Don’t put "=head<em>n</em>" commands inside an
"=over" ... "=back" region.
-
-</li><li> And perhaps most importantly, keep the items consistent: either use
-"=item *" for all of them, to produce bullets; or use "=item
1.",
-"=item 2.", etc., to produce numbered lists; or use "=item
foo",
-"=item bar", etc.–namely, things that look nothing like
bullets or
-numbers.
-
-<p>If you start with bullets or numbers, stick with them, as
-formatters use the first "=item" type to decide how to format the
-list.
-</p>
-</li></ul>
-
-</dd>
-<dt><code>=cut</code></dt>
-<dd><a name="perlpod-_003dcut"></a>
-<p>To end a Pod block, use a blank line,
-then a line beginning with "=cut", and a blank
-line after it. This lets Perl (and the Pod formatter) know that
-this is where Perl code is resuming. (The blank line before the
"=cut"
-is not technically necessary, but many older Pod processors require it.)
-</p>
-</dd>
-<dt><code>=pod</code></dt>
-<dd><a name="perlpod-_003dpod"></a>
-<p>The "=pod" command by itself doesn’t do much of anything,
but it
-signals to Perl (and Pod formatters) that a Pod block starts here. A
-Pod block starts with <em>any</em> command paragraph, so a "=pod"
command is
-usually used just when you want to start a Pod block with an ordinary
-paragraph or a verbatim paragraph. For example:
-</p>
-<pre class="verbatim"> =item stuff()
-
- This function does stuff.
-
- =cut
-
- sub stuff {
- ...
- }
-
- =pod
-
- Remember to check its return value, as in:
-
- stuff() || die "Couldn't do stuff!";
-
- =cut
-</pre>
-</dd>
-<dt><code>=begin <em>formatname</em></code></dt>
-<dd><a name="perlpod-_003dbegin-formatname"></a>
-</dd>
-<dt><code>=end <em>formatname</em></code></dt>
-<dd><a name="perlpod-_003dend-formatname"></a>
-</dd>
-<dt><code>=for <em>formatname</em> <em>text...</em></code></dt>
-<dd><a name="perlpod-_003dfor-formatname-text_002e_002e_002e"></a>
-<p>For, begin, and end will let you have regions of text/code/data that
-are not generally interpreted as normal Pod text, but are passed
-directly to particular formatters, or are otherwise special. A
-formatter that can use that format will use the region, otherwise it
-will be completely ignored.
-</p>
-<p>A command "=begin <em>formatname</em>", some paragraphs, and a
-command "=end <em>formatname</em>", mean that the text/data in
between
-is meant for formatters that understand the special format
-called <em>formatname</em>. For example,
-</p>
-<pre class="verbatim"> =begin html
-
- <hr> <img src="thang.png">
- <p> This is a raw HTML paragraph </p>
-
- =end html
-</pre>
-<p>The command "=for <em>formatname</em> <em>text...</em>"
-specifies that the remainder of just this paragraph (starting
-right after <em>formatname</em>) is in that special format.
-</p>
-<pre class="verbatim"> =for html <hr> <img
src="thang.png">
- <p> This is a raw HTML paragraph </p>
-</pre>
-<p>This means the same thing as the above "=begin html" ...
"=end html"
-region.
-</p>
-<p>That is, with "=for", you can have only one paragraph’s
worth
-of text (i.e., the text in "=foo targetname text..."), but with
-"=begin targetname" ... "=end targetname", you can have
any amount
-of stuff in between. (Note that there still must be a blank line
-after the "=begin" command and a blank line before the
"=end"
-command.)
-</p>
-<p>Here are some examples of how to use these:
-</p>
-<pre class="verbatim"> =begin html
-
- <br>Figure 1.<br><IMG
SRC="figure1.png"><br>
-
- =end html
-
- =begin text
-
- ---------------
- | foo |
- | bar |
- ---------------
-
- ^^^^ Figure 1. ^^^^
-
- =end text
-</pre>
-<p>Some format names that formatters currently are known to accept
-include "roff", "man", "latex", "tex",
"text", and "html". (Some
-formatters will treat some of these as synonyms.)
-</p>
-<p>A format name of "comment" is common for just making notes
(presumably
-to yourself) that won’t appear in any formatted version of the Pod
-document:
-</p>
-<pre class="verbatim"> =for comment
- Make sure that all the available options are documented!
-</pre>
-<p>Some <em>formatnames</em> will require a leading colon (as in
-<code>"=for :formatname"</code>, or
-<code>"=begin :formatname" ... "=end :formatname"</code>),
-to signal that the text is not raw data, but instead <em>is</em> Pod text
-(i.e., possibly containing formatting codes) that’s just not for
-normal formatting (e.g., may not be a normal-use paragraph, but might
-be for formatting as a footnote).
-</p>
-</dd>
-<dt><code>=encoding <em>encodingname</em></code></dt>
-<dd><a name="perlpod-_003dencoding-encodingname"></a>
-<p>This command is used for declaring the encoding of a document. Most
-users won’t need this; but if your encoding isn’t US-ASCII,
-then put a <code>=encoding <em>encodingname</em></code> command very early in
the document so
-that pod formatters will know how to decode the document. For
-<em>encodingname</em>, use a name recognized by the <a
href="Encode-Supported.html#Top">(Encode-Supported)</a>
-module. Some pod formatters may try to guess between a Latin-1 or
-CP-1252 versus
-UTF-8 encoding, but they may guess wrong. It’s best to be explicit if
-you use anything besides strict ASCII. Examples:
-</p>
-<pre class="verbatim"> =encoding latin1
-
- =encoding utf8
-
- =encoding koi8-r
-
- =encoding ShiftJIS
-
- =encoding big5
-</pre>
-<p><code>=encoding</code> affects the whole document, and must occur only once.
-</p>
-</dd>
-</dl>
-
-<p>And don’t forget, all commands but <code>=encoding</code> last up
-until the end of its <em>paragraph</em>, not its line. So in the
-examples below, you can see that every command needs the blank
-line after it, to end its paragraph. (And some older Pod translators
-may require the <code>=encoding</code> line to have a following blank line as
-well, even though it should be legal to omit.)
-</p>
-<p>Some examples of lists include:
-</p>
-<pre class="verbatim"> =over
-
- =item *
-
- First item
-
- =item *
-
- Second item
-
- =back
-
- =over
-
- =item Foo()
-
- Description of Foo function
-
- =item Bar()
-
- Description of Bar function
-
- =back
-</pre>
-<hr>
-<a name="perlpod-Formatting-Codes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpod-The-Intent" accesskey="n" rel="next">perlpod The
Intent</a>, Previous: <a href="#perlpod-Command-Paragraph" accesskey="p"
rel="prev">perlpod Command Paragraph</a>, Up: <a href="#perlpod-DESCRIPTION"
accesskey="u" rel="up">perlpod DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Formatting-Codes"></a>
-<h4 class="subsection">52.2.4 Formatting Codes</h4>
-
-<p>In ordinary paragraphs and in some command paragraphs, various
-formatting codes (a.k.a. "interior sequences") can be used:
-</p>
-<dl compact="compact">
-<dt><code>I<text></code> – italic text <> >></dt>
-<dd><a
name="perlpod-I_003ctext_003e-_002d_002d-italic-text-_003c_003e-_003e_003e"></a>
-<p>Used for emphasis ("<code>be I<careful!></code>") and
parameters
-("<code>redo I<LABEL></code>")
-</p>
-</dd>
-<dt><code>B<text></code> – bold text <> >></dt>
-<dd><a
name="perlpod-B_003ctext_003e-_002d_002d-bold-text-_003c_003e-_003e_003e"></a>
-<p>Used for switches ("<code>perl's B<-n> switch</code>"),
programs
-("<code>some systems provide a B<chfn> for that</code>"),
-emphasis ("<code>be B<careful!></code>"), and so on
-("<code>and that feature is known as
B<autovivification></code>").
-</p>
-</dd>
-<dt><code>C<code></code> – code text <> >></dt>
-<dd><a
name="perlpod-C_003ccode_003e-_002d_002d-code-text-_003c_003e-_003e_003e"></a>
-<p>Renders code in a typewriter font, or gives some other indication that
-this represents program text ("<code>C<gmtime($^T)></code>")
or some other
-form of computerese ("<code>C<drwxr-xr-x></code>").
-</p>
-</dd>
-<dt><code>L<name></code> – a hyperlink <> >></dt>
-<dd><a
name="perlpod-L_003cname_003e-_002d_002d-a-hyperlink-_003c_003e-_003e_003e"></a>
-<p>There are various syntaxes, listed below. In the syntaxes given,
-<code>text</code>, <code>name</code>, and <code>section</code> cannot contain
the characters
-’/’ and ’|’; and any ’<’ or
’>’ should be matched.
-</p>
-<ul>
-<li> <code>L<name></code>
-
-<p>Link to a Perl manual page (e.g., <code>L<Net::Ping></code>). Note
-that <code>name</code> should not contain spaces. This syntax
-is also occasionally used for references to Unix man pages, as in
-<code>L<crontab(5)></code>.
-</p>
-</li><li> <code>L<name/"sec"></code> or
<code>L<name/sec></code>
-
-<p>Link to a section in other manual page. E.g.,
-<code>L<perlsyn/"For Loops"></code>
-</p>
-</li><li> <code>L</"sec"></code> or <code>L</sec></code>
-
-<p>Link to a section in this manual page. E.g.,
-<code>L</"Object Methods"></code>
-</p>
-</li></ul>
-
-<p>A section is started by the named heading or item. For
-example, <code>L<perlvar/$.></code> or
<code>L<perlvar/"$."></code> both
-link to the section started by "<code>=item $.</code>" in perlvar.
And
-<code>L<perlsyn/For Loops></code> or <code>L<perlsyn/"For
Loops"></code>
-both link to the section started by "<code>=head2 For Loops</code>"
-in perlsyn.
-</p>
-<p>To control what text is used for display, you
-use "<code>L<text|...></code>", as in:
-</p>
-<ul>
-<li> <code>L<text|name></code>
-
-<p>Link this text to that manual page. E.g.,
-<code>L<Perl Error Messages|perldiag></code>
-</p>
-</li><li> <code>L<text|name/"sec"></code> or
<code>L<text|name/sec></code>
-
-<p>Link this text to that section in that manual page. E.g.,
-<code>L<postfix "if"|perlsyn/"Statement
Modifiers"></code>
-</p>
-</li><li> <code>L<text|/"sec"></code> or
<code>L<text|/sec></code>
-or <code>L<text|"sec"></code>
-
-<p>Link this text to that section in this manual page. E.g.,
-<code>L<the various attributes|/"Member Data"></code>
-</p>
-</li></ul>
-
-<p>Or you can link to a web page:
-</p>
-<ul>
-<li> <code>L<scheme:...></code>
-
-<p><code>L<text|scheme:...></code>
-</p>
-<p>Links to an absolute URL. For example,
<code>L<http://www.perl.org/></code> or
-<code>L<The Perl Home Page|http://www.perl.org/></code>.
-</p>
-</li></ul>
-
-</dd>
-<dt><code>E<escape></code> – a character escape <>
>></dt>
-<dd><a
name="perlpod-E_003cescape_003e-_002d_002d-a-character-escape-_003c_003e-_003e_003e"></a>
-<p>Very similar to HTML/XML <code>&<em>foo</em>;</code> "entity
references":
-</p>
-<ul>
-<li> <code>E<lt></code> – a literal < (less than)
-
-</li><li> <code>E<gt></code> – a literal > (greater than)
-
-</li><li> <code>E<verbar></code> – a literal | (<em>ver</em>tical
<em>bar</em>)
-
-</li><li> <code>E<sol></code> – a literal / (<em>sol</em>idus)
-
-<p>The above four are optional except in other formatting codes,
-notably <code>L<...></code>, and when preceded by a
-capital letter.
-</p>
-</li><li> <code>E<htmlname></code>
-
-<p>Some non-numeric HTML entity name, such as <code>E<eacute></code>,
-meaning the same thing as <code>&eacute;</code> in HTML – i.e., a
lowercase
-e with an acute (/-shaped) accent.
-</p>
-</li><li> <code>E<number></code>
-
-<p>The ASCII/Latin-1/Unicode character with that number. A
-leading "0x" means that <em>number</em> is hex, as in
-<code>E<0x201E></code>. A leading "0" means that
<em>number</em> is octal,
-as in <code>E<075></code>. Otherwise <em>number</em> is interpreted as
being
-in decimal, as in <code>E<181></code>.
-</p>
-<p>Note that older Pod formatters might not recognize octal or
-hex numeric escapes, and that many formatters cannot reliably
-render characters above 255. (Some formatters may even have
-to use compromised renderings of Latin-1/CP-1252 characters, like
-rendering <code>E<eacute></code> as just a plain "e".)
-</p>
-</li></ul>
-
-</dd>
-<dt><code>F<filename></code> – used for filenames <>
>></dt>
-<dd><a
name="perlpod-F_003cfilename_003e-_002d_002d-used-for-filenames-_003c_003e-_003e_003e"></a>
-<p>Typically displayed in italics. Example:
"<code>F<.cshrc></code>"
-</p>
-</dd>
-<dt><code>S<text></code> – text contains non-breaking spaces
<> >></dt>
-<dd><a
name="perlpod-S_003ctext_003e-_002d_002d-text-contains-non_002dbreaking-spaces-_003c_003e-_003e_003e"></a>
-<p>This means that the words in <em>text</em> should not be broken
-across lines. Example:
<code>S<$x ? $y : $z></code><!-- /@w -->.
-</p>
-</dd>
-<dt><code>X<topic name></code> – an index entry <>
>></dt>
-<dd><a
name="perlpod-X_003ctopic-name_003e-_002d_002d-an-index-entry-_003c_003e-_003e_003e"></a>
-<p>This is ignored by most formatters, but some may use it for building
-indexes. It always renders as empty-string.
-Example: <code>X<absolutizing relative URLs></code>
-</p>
-</dd>
-<dt><code>Z<></code> – a null (zero-effect) formatting code
<> >></dt>
-<dd><a
name="perlpod-Z_003c_003e-_002d_002d-a-null-_0028zero_002deffect_0029-formatting-code-_003c_003e-_003e_003e"></a>
-<p>This is rarely used. It’s one way to get around using an
-E<...> code sometimes. For example, instead of
-"<code>NE<lt>3</code>" (for "N<3") you could write
-"<code>NZ<><3</code>" (the "Z<>" breaks up
the "N" and
-the "<" so they can’t be considered
-the part of a (fictitious) "N<...>" code).
-</p>
-</dd>
-</dl>
-
-<p>Most of the time, you will need only a single set of angle brackets to
-delimit the beginning and end of formatting codes. However,
-sometimes you will want to put a real right angle bracket (a
-greater-than sign, ’>’) inside of a formatting code. This is
particularly
-common when using a formatting code to provide a different font-type for a
-snippet of code. As with all things in Perl, there is more than
-one way to do it. One way is to simply escape the closing bracket
-using an <code>E</code> code:
-</p>
-<pre class="verbatim"> C<$a E<lt>=E<gt> $b>
-</pre>
-<p>This will produce: "<code>$a <=> $b</code>"
-</p>
-<p>A more readable, and perhaps more "plain" way is to use an
alternate
-set of delimiters that doesn’t require a single ">" to be
escaped.
-Doubled angle brackets ("<<" and ">>") may be
used <em>if and only if there is
-whitespace right after the opening delimiter and whitespace right
-before the closing delimiter!</em> For example, the following will
-do the trick:
-</p>
-<pre class="verbatim"> C<< $a <=> $b >>
-</pre>
-<p>In fact, you can use as many repeated angle-brackets as you like so
-long as you have the same number of them in the opening and closing
-delimiters, and make sure that whitespace immediately follows the last
-’<’ of the opening delimiter, and immediately precedes the
first ’>’
-of the closing delimiter. (The whitespace is ignored.) So the
-following will also work:
-</p>
-<pre class="verbatim"> C<<< $a <=> $b >>>
- C<<<< $a <=> $b >>>>
-</pre>
-<p>And they all mean exactly the same as this:
-</p>
-<pre class="verbatim"> C<$a E<lt>=E<gt> $b>
-</pre>
-<p>The multiple-bracket form does not affect the interpretation of the
contents of
-the formatting code, only how it must end. That means that the examples above
-are also exactly the same as this:
-</p>
-<pre class="verbatim"> C<< $a E<lt>=E<gt> $b >>
-</pre>
-<p>As a further example, this means that if you wanted to put these bits of
-code in <code>C</code> (code) style:
-</p>
-<pre class="verbatim"> open(X, ">>thing.dat") || die $!
- $foo->bar();
-</pre>
-<p>you could do it like so:
-</p>
-<pre class="verbatim"> C<<< open(X, ">>thing.dat")
|| die $! >>>
- C<< $foo->bar(); >>
-</pre>
-<p>which is presumably easier to read than the old way:
-</p>
-<pre class="verbatim"> C<open(X,
"E<gt>E<gt>thing.dat") || die $!>
- C<$foo-E<gt>bar();>
-</pre>
-<p>This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man),
-and any other pod2xxx or Pod::Xxxx translators that use
-Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.
-</p>
-<hr>
-<a name="perlpod-The-Intent"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpod-Embedding-Pods-in-Perl-Modules" accesskey="n"
rel="next">perlpod Embedding Pods in Perl Modules</a>, Previous: <a
href="#perlpod-Formatting-Codes" accesskey="p" rel="prev">perlpod Formatting
Codes</a>, Up: <a href="#perlpod-DESCRIPTION" accesskey="u" rel="up">perlpod
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-Intent"></a>
-<h4 class="subsection">52.2.5 The Intent</h4>
-
-<p>The intent is simplicity of use, not power of expression. Paragraphs
-look like paragraphs (block format), so that they stand out
-visually, and so that I could run them through <code>fmt</code> easily to
reformat
-them (that’s F7 in my version of <strong>vi</strong>, or Esc Q in my
version of
-<strong>emacs</strong>). I wanted the translator to always leave the
<code>'</code> and <code>`</code> and
-<code>"</code> quotes alone, in verbatim mode, so I could slurp in a
-working program, shift it over four spaces, and have it print out, er,
-verbatim. And presumably in a monospace font.
-</p>
-<p>The Pod format is not necessarily sufficient for writing a book. Pod
-is just meant to be an idiot-proof common source for nroff, HTML,
-TeX, and other markup languages, as used for online
-documentation. Translators exist for <strong>pod2text</strong>,
<strong>pod2html</strong>,
-<strong>pod2man</strong> (that’s for nroff(1) and troff(1)),
<strong>pod2latex</strong>, and
-<strong>pod2fm</strong>. Various others are available in CPAN.
-</p>
-<hr>
-<a name="perlpod-Embedding-Pods-in-Perl-Modules"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpod-Hints-for-Writing-Pod" accesskey="n"
rel="next">perlpod Hints for Writing Pod</a>, Previous: <a
href="#perlpod-The-Intent" accesskey="p" rel="prev">perlpod The Intent</a>, Up:
<a href="#perlpod-DESCRIPTION" accesskey="u" rel="up">perlpod DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Embedding-Pods-in-Perl-Modules"></a>
-<h4 class="subsection">52.2.6 Embedding Pods in Perl Modules</h4>
-
-<p>You can embed Pod documentation in your Perl modules and scripts. Start
-your documentation with an empty line, a "=head1" command at the
-beginning, and end it with a "=cut" command and an empty line. The
-<strong>perl</strong> executable will ignore the Pod text. You can place a Pod
-statement where <strong>perl</strong> expects the beginning of a new
statement, but
-not within a statement, as that would result in an error. See any of
-the supplied library modules for examples.
-</p>
-<p>If you’re going to put your Pod at the end of the file, and
you’re using
-an <code>__END__</code> or <code>__DATA__</code> cut mark, make sure to put an
empty line there
-before the first Pod command.
-</p>
-<pre class="verbatim"> __END__
-
- =head1 NAME
-
- Time::Local - efficiently compute time from local and GMT time
-</pre>
-<p>Without that empty line before the "=head1", many translators
wouldn’t
-have recognized the "=head1" as starting a Pod block.
-</p>
-<hr>
-<a name="perlpod-Hints-for-Writing-Pod"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlpod-Embedding-Pods-in-Perl-Modules" accesskey="p"
rel="prev">perlpod Embedding Pods in Perl Modules</a>, Up: <a
href="#perlpod-DESCRIPTION" accesskey="u" rel="up">perlpod DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Hints-for-Writing-Pod"></a>
-<h4 class="subsection">52.2.7 Hints for Writing Pod</h4>
-
-<ul>
-<li> The <strong>podchecker</strong> command is provided for checking Pod
syntax for errors
-and warnings. For example, it checks for completely blank lines in
-Pod blocks and for unknown commands and formatting codes. You should
-still also pass your document through one or more translators and proofread
-the result, or print out the result and proofread that. Some of the
-problems found may be bugs in the translators, which you may or may not
-wish to work around.
-
-</li><li> If you’re more familiar with writing in HTML than with writing
in Pod, you
-can try your hand at writing documentation in simple HTML, and converting
-it to Pod with the experimental <a
href="Pod-HTML2Pod.html#Top">(Pod-HTML2Pod)Pod::HTML2Pod</a> module,
-(available in CPAN), and looking at the resulting code. The experimental
-<a href="Pod-PXML.html#Top">(Pod-PXML)Pod::PXML</a> module in CPAN might also
be useful.
-
-</li><li> Many older Pod translators require the lines before every Pod
-command and after every Pod command (including "=cut"!) to be a blank
-line. Having something like this:
-
-<pre class="verbatim"> # - - - - - - - - - - - -
- =item $firecracker->boom()
-
- This noisily detonates the firecracker object.
- =cut
- sub boom {
- ...
-</pre>
-<p>...will make such Pod translators completely fail to see the Pod block
-at all.
-</p>
-<p>Instead, have it like this:
-</p>
-<pre class="verbatim"> # - - - - - - - - - - - -
-
- =item $firecracker->boom()
-
- This noisily detonates the firecracker object.
-
- =cut
-
- sub boom {
- ...
-</pre>
-</li><li> Some older Pod translators require paragraphs (including command
-paragraphs like "=head2 Functions") to be separated by
<em>completely</em>
-empty lines. If you have an apparently empty line with some spaces
-on it, this might not count as a separator for those translators, and
-that could cause odd formatting.
-
-</li><li> Older translators might add wording around an L<> link, so that
-<code>L<Foo::Bar></code> may become "the Foo::Bar manpage",
for example.
-So you shouldn’t write things like <code>the L<foo>
-documentation</code>, if you want the translated document to read sensibly.
-Instead, write <code>the L<Foo::Bar|Foo::Bar> documentation</code> or
-<code>L<the Foo::Bar documentation|Foo::Bar></code>, to control how the
-link comes out.
-
-</li><li> Going past the 70th column in a verbatim block might be ungracefully
-wrapped by some formatters.
-
-</li></ul>
-
-<hr>
-<a name="perlpod-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpod-AUTHOR" accesskey="n" rel="next">perlpod AUTHOR</a>,
Previous: <a href="#perlpod-DESCRIPTION" accesskey="p" rel="prev">perlpod
DESCRIPTION</a>, Up: <a href="#perlpod" accesskey="u" rel="up">perlpod</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-26"></a>
-<h3 class="section">52.3 SEE ALSO</h3>
-
-<p><a href="#perlpodspec-NAME">perlpodspec NAME</a>, <a
href="#perlsyn-PODs_003a-Embedded-Documentation">perlsyn PODs: Embedded
Documentation</a>,
-<a href="#perlnewmod-NAME">perlnewmod NAME</a>, <a
href="perldoc.html#Top">(perldoc)</a>, <a
href="pod2html.html#Top">(pod2html)</a>, <a
href="pod2man.html#Top">(pod2man)</a>, <a
href="podchecker.html#Top">(podchecker)</a>.
-</p>
-<hr>
-<a name="perlpod-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlpod-SEE-ALSO" accesskey="p" rel="prev">perlpod SEE
ALSO</a>, Up: <a href="#perlpod" accesskey="u" rel="up">perlpod</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-22"></a>
-<h3 class="section">52.4 AUTHOR</h3>
-
-<p>Larry Wall, Sean M. Burke
-</p>
-<hr>
-<a name="perlpodspec"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodstyle" accesskey="n" rel="next">perlpodstyle</a>,
Previous: <a href="#perlpod" accesskey="p" rel="prev">perlpod</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlpodspec-1"></a>
-<h2 class="chapter">53 perlpodspec</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlpodspec-NAME"
accesskey="1">perlpodspec NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpodspec-DESCRIPTION"
accesskey="2">perlpodspec DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-Pod-Definitions" accesskey="3">perlpodspec Pod
Definitions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpodspec-Pod-Commands"
accesskey="4">perlpodspec Pod Commands</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-Pod-Formatting-Codes" accesskey="5">perlpodspec Pod
Formatting Codes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-Notes-on-Implementing-Pod-Processors"
accesskey="6">perlpodspec Notes on Implementing Pod
Processors</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-About-L_003c_002e_002e_002e_003e-Codes"
accesskey="7">perlpodspec About L<...>
Codes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-About-_003dover_002e_002e_002e_003dback-Regions"
accesskey="8">perlpodspec About =over...=back
Regions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-About-Data-Paragraphs-and-_0022_003dbegin_002f_003dend_0022-Regions"
accesskey="9">perlpodspec About Data Paragraphs and "=begin/=end"
Regions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-SEE-ALSO">perlpodspec SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodspec-AUTHOR">perlpodspec AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpodspec-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodspec-DESCRIPTION" accesskey="n" rel="next">perlpodspec
DESCRIPTION</a>, Up: <a href="#perlpodspec" accesskey="u"
rel="up">perlpodspec</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-52"></a>
-<h3 class="section">53.1 NAME</h3>
-
-<p>perlpodspec - Plain Old Documentation: format specification and notes
-</p>
-<hr>
-<a name="perlpodspec-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodspec-Pod-Definitions" accesskey="n"
rel="next">perlpodspec Pod Definitions</a>, Previous: <a
href="#perlpodspec-NAME" accesskey="p" rel="prev">perlpodspec NAME</a>, Up: <a
href="#perlpodspec" accesskey="u" rel="up">perlpodspec</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-51"></a>
-<h3 class="section">53.2 DESCRIPTION</h3>
-
-<p>This document is detailed notes on the Pod markup language. Most
-people will only have to read <a href="#perlpod-NAME">perlpod</a> to know how
to write
-in Pod, but this document may answer some incidental questions to do
-with parsing and rendering Pod.
-</p>
-<p>In this document, "must" / "must not",
"should" /
-"should not", and "may" have their conventional (cf. RFC
2119)
-meanings: "X must do Y" means that if X doesn’t do Y,
it’s against
-this specification, and should really be fixed. "X should do Y"
-means that it’s recommended, but X may fail to do Y, if there’s a
-good reason. "X may do Y" is merely a note that X can do Y at
-will (although it is up to the reader to detect any connotation of
-"and I think it would be <em>nice</em> if X did Y" versus "it
wouldn’t
-really <em>bother</em> me if X did Y").
-</p>
-<p>Notably, when I say "the parser should do Y", the
-parser may fail to do Y, if the calling application explicitly
-requests that the parser <em>not</em> do Y. I often phrase this as
-"the parser should, by default, do Y." This doesn’t
<em>require</em>
-the parser to provide an option for turning off whatever
-feature Y is (like expanding tabs in verbatim paragraphs), although
-it implicates that such an option <em>may</em> be provided.
-</p>
-<hr>
-<a name="perlpodspec-Pod-Definitions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodspec-Pod-Commands" accesskey="n" rel="next">perlpodspec
Pod Commands</a>, Previous: <a href="#perlpodspec-DESCRIPTION" accesskey="p"
rel="prev">perlpodspec DESCRIPTION</a>, Up: <a href="#perlpodspec"
accesskey="u" rel="up">perlpodspec</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Pod-Definitions"></a>
-<h3 class="section">53.3 Pod Definitions</h3>
-
-<p>Pod is embedded in files, typically Perl source files, although you
-can write a file that’s nothing but Pod.
-</p>
-<p>A <strong>line</strong> in a file consists of zero or more non-newline
characters,
-terminated by either a newline or the end of the file.
-</p>
-<p>A <strong>newline sequence</strong> is usually a platform-dependent
concept, but
-Pod parsers should understand it to mean any of CR (ASCII 13), LF
-(ASCII 10), or a CRLF (ASCII 13 followed immediately by ASCII 10), in
-addition to any other system-specific meaning. The first CR/CRLF/LF
-sequence in the file may be used as the basis for identifying the
-newline sequence for parsing the rest of the file.
-</p>
-<p>A <strong>blank line</strong> is a line consisting entirely of zero or more
spaces
-(ASCII 32) or tabs (ASCII 9), and terminated by a newline or end-of-file.
-A <strong>non-blank line</strong> is a line containing one or more characters
other
-than space or tab (and terminated by a newline or end-of-file).
-</p>
-<p>(<em>Note:</em> Many older Pod parsers did not accept a line consisting of
-spaces/tabs and then a newline as a blank line. The only lines they
-considered blank were lines consisting of <em>no characters at all</em>,
-terminated by a newline.)
-</p>
-<p><strong>Whitespace</strong> is used in this document as a blanket term for
spaces,
-tabs, and newline sequences. (By itself, this term usually refers
-to literal whitespace. That is, sequences of whitespace characters
-in Pod source, as opposed to "E<32>", which is a formatting
-code that <em>denotes</em> a whitespace character.)
-</p>
-<p>A <strong>Pod parser</strong> is a module meant for parsing Pod (regardless
of
-whether this involves calling callbacks or building a parse tree or
-directly formatting it). A <strong>Pod formatter</strong> (or <strong>Pod
translator</strong>)
-is a module or program that converts Pod to some other format (HTML,
-plaintext, TeX, PostScript, RTF). A <strong>Pod processor</strong> might be a
-formatter or translator, or might be a program that does something
-else with the Pod (like counting words, scanning for index points,
-etc.).
-</p>
-<p>Pod content is contained in <strong>Pod blocks</strong>. A Pod block
starts with a
-line that matches <code>m/\A=[a-zA-Z]/</code>, and continues up to the next
line
-that matches <code>m/\A=cut/</code> or up to the end of the file if there is
-no <code>m/\A=cut/</code> line.
-</p>
-<p>Within a Pod block, there are <strong>Pod paragraphs</strong>. A Pod
paragraph
-consists of non-blank lines of text, separated by one or more blank
-lines.
-</p>
-<p>For purposes of Pod processing, there are four types of paragraphs in
-a Pod block:
-</p>
-<ul>
-<li> A command paragraph (also called a "directive"). The first
line of
-this paragraph must match <code>m/\A=[a-zA-Z]/</code>. Command paragraphs are
-typically one line, as in:
-
-<pre class="verbatim"> =head1 NOTES
-
- =item *
-</pre>
-<p>But they may span several (non-blank) lines:
-</p>
-<pre class="verbatim"> =for comment
- Hm, I wonder what it would look like if
- you tried to write a BNF for Pod from this.
-
- =head3 Dr. Strangelove, or: How I Learned to
- Stop Worrying and Love the Bomb
-</pre>
-<p><em>Some</em> command paragraphs allow formatting codes in their content
-(i.e., after the part that matches <code>m/\A=[a-zA-Z]\S*\s*/</code>), as in:
-</p>
-<pre class="verbatim"> =head1 Did You Remember to C<use strict;>?
-</pre>
-<p>In other words, the Pod processing handler for "head1" will apply
the
-same processing to "Did You Remember to C<use strict;>?" that
it
-would to an ordinary paragraph (i.e., formatting codes like
-"C<...>") are parsed and presumably formatted appropriately,
and
-whitespace in the form of literal spaces and/or tabs is not
-significant.
-</p>
-</li><li> A <strong>verbatim paragraph</strong>. The first line of this
paragraph must be a
-literal space or tab, and this paragraph must not be inside a "=begin
-<em>identifier</em>", ... "=end <em>identifier</em>" sequence
unless
-"<em>identifier</em>" begins with a colon (":"). That is,
if a paragraph
-starts with a literal space or tab, but <em>is</em> inside a
-"=begin <em>identifier</em>", ... "=end
<em>identifier</em>" region, then it’s
-a data paragraph, unless "<em>identifier</em>" begins with a colon.
-
-<p>Whitespace <em>is</em> significant in verbatim paragraphs (although, in
-processing, tabs are probably expanded).
-</p>
-</li><li> An <strong>ordinary paragraph</strong>. A paragraph is an ordinary
paragraph
-if its first line matches neither <code>m/\A=[a-zA-Z]/</code> nor
-<code>m/\A[ \t]/</code>, <em>and</em> if it’s not inside a "=begin
<em>identifier</em>",
-... "=end <em>identifier</em>" sequence unless
"<em>identifier</em>" begins with
-a colon (":").
-
-</li><li> A <strong>data paragraph</strong>. This is a paragraph that
<em>is</em> inside a "=begin
-<em>identifier</em>" ... "=end <em>identifier</em>" sequence
where
-"<em>identifier</em>" does <em>not</em> begin with a literal colon
(":"). In
-some sense, a data paragraph is not part of Pod at all (i.e.,
-effectively it’s "out-of-band"), since it’s not subject
to most kinds
-of Pod parsing; but it is specified here, since Pod
-parsers need to be able to call an event for it, or store it in some
-form in a parse tree, or at least just parse <em>around</em> it.
-
-</li></ul>
-
-<p>For example: consider the following paragraphs:
-</p>
-<pre class="verbatim"> # <- that's the 0th column
-
- =head1 Foo
-
- Stuff
-
- $foo->bar
-
- =cut
-</pre>
-<p>Here, "=head1 Foo" and "=cut" are command paragraphs
because the first
-line of each matches <code>m/\A=[a-zA-Z]/</code>.
"<em>[space][space]</em>$foo->bar"
-is a verbatim paragraph, because its first line starts with a literal
-whitespace character (and there’s no
"=begin"..."=end" region around).
-</p>
-<p>The "=begin <em>identifier</em>" ... "=end
<em>identifier</em>" commands stop
-paragraphs that they surround from being parsed as ordinary or verbatim
-paragraphs, if <em>identifier</em> doesn’t begin with a colon. This
-is discussed in detail in the section
-<a
href="#perlpodspec-About-Data-Paragraphs-and-_0022_003dbegin_002f_003dend_0022-Regions">About
Data Paragraphs and "=begin/=end" Regions</a>.
-</p>
-<hr>
-<a name="perlpodspec-Pod-Commands"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodspec-Pod-Formatting-Codes" accesskey="n"
rel="next">perlpodspec Pod Formatting Codes</a>, Previous: <a
href="#perlpodspec-Pod-Definitions" accesskey="p" rel="prev">perlpodspec Pod
Definitions</a>, Up: <a href="#perlpodspec" accesskey="u"
rel="up">perlpodspec</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Pod-Commands"></a>
-<h3 class="section">53.4 Pod Commands</h3>
-
-<p>This section is intended to supplement and clarify the discussion in
-<a href="#perlpod-Command-Paragraph">perlpod Command Paragraph</a>. These are
the currently recognized
-Pod commands:
-</p>
-<dl compact="compact">
-<dt>"=head1", "=head2", "=head3",
"=head4"</dt>
-<dd><a
name="perlpodspec-_0022_003dhead1_0022_002c-_0022_003dhead2_0022_002c-_0022_003dhead3_0022_002c-_0022_003dhead4_0022"></a>
-<p>This command indicates that the text in the remainder of the paragraph
-is a heading. That text may contain formatting codes. Examples:
-</p>
-<pre class="verbatim"> =head1 Object Attributes
-
- =head3 What B<Not> to Do!
-</pre>
-</dd>
-<dt>"=pod"</dt>
-<dd><a name="perlpodspec-_0022_003dpod_0022"></a>
-<p>This command indicates that this paragraph begins a Pod block. (If we
-are already in the middle of a Pod block, this command has no effect at
-all.) If there is any text in this command paragraph after "=pod",
-it must be ignored. Examples:
-</p>
-<pre class="verbatim"> =pod
-
- This is a plain Pod paragraph.
-
- =pod This text is ignored.
-</pre>
-</dd>
-<dt>"=cut"</dt>
-<dd><a name="perlpodspec-_0022_003dcut_0022"></a>
-<p>This command indicates that this line is the end of this previously
-started Pod block. If there is any text after "=cut" on the line,
it must be
-ignored. Examples:
-</p>
-<pre class="verbatim"> =cut
-
- =cut The documentation ends here.
-
- =cut
- # This is the first line of program text.
- sub foo { # This is the second.
-</pre>
-<p>It is an error to try to <em>start</em> a Pod block with a "=cut"
command. In
-that case, the Pod processor must halt parsing of the input file, and
-must by default emit a warning.
-</p>
-</dd>
-<dt>"=over"</dt>
-<dd><a name="perlpodspec-_0022_003dover_0022"></a>
-<p>This command indicates that this is the start of a list/indent
-region. If there is any text following the "=over", it must consist
-of only a nonzero positive numeral. The semantics of this numeral is
-explained in the <a
href="#perlpodspec-About-_003dover_002e_002e_002e_003dback-Regions">About
=over...=back Regions</a> section, further
-below. Formatting codes are not expanded. Examples:
-</p>
-<pre class="verbatim"> =over 3
-
- =over 3.5
-
- =over
-</pre>
-</dd>
-<dt>"=item"</dt>
-<dd><a name="perlpodspec-_0022_003ditem_0022"></a>
-<p>This command indicates that an item in a list begins here. Formatting
-codes are processed. The semantics of the (optional) text in the
-remainder of this paragraph are
-explained in the <a
href="#perlpodspec-About-_003dover_002e_002e_002e_003dback-Regions">About
=over...=back Regions</a> section, further
-below. Examples:
-</p>
-<pre class="verbatim"> =item
-
- =item *
-
- =item *
-
- =item 14
-
- =item 3.
-
- =item C<< $thing->stuff(I<dodad>) >>
-
- =item For transporting us beyond seas to be tried for pretended
- offenses
-
- =item He is at this time transporting large armies of foreign
- mercenaries to complete the works of death, desolation and
- tyranny, already begun with circumstances of cruelty and perfidy
- scarcely paralleled in the most barbarous ages, and totally
- unworthy the head of a civilized nation.
-</pre>
-</dd>
-<dt>"=back"</dt>
-<dd><a name="perlpodspec-_0022_003dback_0022"></a>
-<p>This command indicates that this is the end of the region begun
-by the most recent "=over" command. It permits no text after the
-"=back" command.
-</p>
-</dd>
-<dt>"=begin formatname"</dt>
-<dd><a name="perlpodspec-_0022_003dbegin-formatname_0022"></a>
-</dd>
-<dt>"=begin formatname parameter"</dt>
-<dd><a name="perlpodspec-_0022_003dbegin-formatname-parameter_0022"></a>
-<p>This marks the following paragraphs (until the matching "=end
-formatname") as being for some special kind of processing. Unless
-"formatname" begins with a colon, the contained non-command
-paragraphs are data paragraphs. But if "formatname" <em>does</em>
begin
-with a colon, then non-command paragraphs are ordinary paragraphs
-or data paragraphs. This is discussed in detail in the section
-<a
href="#perlpodspec-About-Data-Paragraphs-and-_0022_003dbegin_002f_003dend_0022-Regions">About
Data Paragraphs and "=begin/=end" Regions</a>.
-</p>
-<p>It is advised that formatnames match the regexp
-<code>m/\A:?[-a-zA-Z0-9_]+\z/</code>. Everything following whitespace after
the
-formatname is a parameter that may be used by the formatter when dealing
-with this region. This parameter must not be repeated in the "=end"
-paragraph. Implementors should anticipate future expansion in the
-semantics and syntax of the first parameter to
"=begin"/"=end"/"=for".
-</p>
-</dd>
-<dt>"=end formatname"</dt>
-<dd><a name="perlpodspec-_0022_003dend-formatname_0022"></a>
-<p>This marks the end of the region opened by the matching
-"=begin formatname" region. If "formatname" is not the
formatname
-of the most recent open "=begin formatname" region, then this
-is an error, and must generate an error message. This
-is discussed in detail in the section
-<a
href="#perlpodspec-About-Data-Paragraphs-and-_0022_003dbegin_002f_003dend_0022-Regions">About
Data Paragraphs and "=begin/=end" Regions</a>.
-</p>
-</dd>
-<dt>"=for formatname text..."</dt>
-<dd><a
name="perlpodspec-_0022_003dfor-formatname-text_002e_002e_002e_0022"></a>
-<p>This is synonymous with:
-</p>
-<pre class="verbatim"> =begin formatname
-
- text...
-
- =end formatname
-</pre>
-<p>That is, it creates a region consisting of a single paragraph; that
-paragraph is to be treated as a normal paragraph if "formatname"
-begins with a ":"; if "formatname" <em>doesn’t</em>
begin with a colon,
-then "text..." will constitute a data paragraph. There is no way
-to use "=for formatname text..." to express "text..." as a
verbatim
-paragraph.
-</p>
-</dd>
-<dt>"=encoding encodingname"</dt>
-<dd><a name="perlpodspec-_0022_003dencoding-encodingname_0022"></a>
-<p>This command, which should occur early in the document (at least
-before any non-US-ASCII data!), declares that this document is
-encoded in the encoding <em>encodingname</em>, which must be
-an encoding name that <a href="Encode.html#Top">(Encode)</a> recognizes.
(Encode’s list
-of supported encodings, in <a
href="Encode-Supported.html#Top">(Encode-Supported)</a>, is useful here.)
-If the Pod parser cannot decode the declared encoding, it
-should emit a warning and may abort parsing the document
-altogether.
-</p>
-<p>A document having more than one "=encoding" line should be
-considered an error. Pod processors may silently tolerate this if
-the not-first "=encoding" lines are just duplicates of the
-first one (e.g., if there’s a "=encoding utf8" line, and later
on
-another "=encoding utf8" line). But Pod processors should complain
if
-there are contradictory "=encoding" lines in the same document
-(e.g., if there is a "=encoding utf8" early in the document and
-"=encoding big5" later). Pod processors that recognize BOMs
-may also complain if they see an "=encoding" line
-that contradicts the BOM (e.g., if a document with a UTF-16LE
-BOM has an "=encoding shiftjis" line).
-</p>
-</dd>
-</dl>
-
-<p>If a Pod processor sees any command other than the ones listed
-above (like "=head", or "=haed1", or "=stuff",
or "=cuttlefish",
-or "=w123"), that processor must by default treat this as an
-error. It must not process the paragraph beginning with that
-command, must by default warn of this as an error, and may
-abort the parse. A Pod parser may allow a way for particular
-applications to add to the above list of known commands, and to
-stipulate, for each additional command, whether formatting
-codes should be processed.
-</p>
-<p>Future versions of this specification may add additional
-commands.
-</p>
-<hr>
-<a name="perlpodspec-Pod-Formatting-Codes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodspec-Notes-on-Implementing-Pod-Processors"
accesskey="n" rel="next">perlpodspec Notes on Implementing Pod Processors</a>,
Previous: <a href="#perlpodspec-Pod-Commands" accesskey="p"
rel="prev">perlpodspec Pod Commands</a>, Up: <a href="#perlpodspec"
accesskey="u" rel="up">perlpodspec</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Pod-Formatting-Codes"></a>
-<h3 class="section">53.5 Pod Formatting Codes</h3>
-
-<p>(Note that in previous drafts of this document and of perlpod,
-formatting codes were referred to as "interior sequences", and
-this term may still be found in the documentation for Pod parsers,
-and in error messages from Pod processors.)
-</p>
-<p>There are two syntaxes for formatting codes:
-</p>
-<ul>
-<li> A formatting code starts with a capital letter (just US-ASCII [A-Z])
-followed by a "<", any number of characters, and ending with the
first
-matching ">". Examples:
-
-<pre class="verbatim"> That's what I<you> think!
-
- What's C<dump()> for?
-
- and C<unlink()> Under Different Operating Systems>
-</pre>
-</li><li> A formatting code starts with a capital letter (just US-ASCII [A-Z])
-followed by two or more "<"’s, one or more whitespace
characters,
-any number of characters, one or more whitespace characters,
-and ending with the first matching sequence of two or more
">"’s, where
-the number of ">"’s equals the number of
"<"’s in the opening of this
-formatting code. Examples:
-
-<pre class="verbatim"> That's what I<< you >> think!
-
- C<<< open(X, ">>thing.dat") || die $! >>>
-
- B<< $foo->bar(); >>
-</pre>
-<p>With this syntax, the whitespace character(s) after the
"C<<<"
-and before the ">>>" (or whatever letter) are <em>not</em>
renderable. They
-do not signify whitespace, are merely part of the formatting codes
-themselves. That is, these are all synonymous:
-</p>
-<pre class="verbatim"> C<thing>
- C<< thing >>
- C<< thing >>
- C<<< thing >>>
- C<<<<
- thing
- >>>>
-</pre>
-<p>and so on.
-</p>
-<p>Finally, the multiple-angle-bracket form does <em>not</em> alter the
interpretation
-of nested formatting codes, meaning that the following four example lines are
-identical in meaning:
-</p>
-<pre class="verbatim"> B<example: C<$a E<lt>=E<gt>
$b>>
-
- B<example: C<< $a <=> $b >>>
-
- B<example: C<< $a E<lt>=E<gt> $b >>>
-
- B<<< example: C<< $a E<lt>=E<gt> $b >>
>>>
-</pre>
-</li></ul>
-
-<p>In parsing Pod, a notably tricky part is the correct parsing of
-(potentially nested!) formatting codes. Implementors should
-consult the code in the <code>parse_text</code> routine in Pod::Parser as an
-example of a correct implementation.
-</p>
-<dl compact="compact">
-<dt><code>I<text></code> – italic text</dt>
-<dd><a name="perlpodspec-I_003ctext_003e-_002d_002d-italic-text"></a>
-<p>See the brief discussion in <a href="#perlpod-Formatting-Codes">perlpod
Formatting Codes</a>.
-</p>
-</dd>
-<dt><code>B<text></code> – bold text</dt>
-<dd><a name="perlpodspec-B_003ctext_003e-_002d_002d-bold-text"></a>
-<p>See the brief discussion in <a href="#perlpod-Formatting-Codes">perlpod
Formatting Codes</a>.
-</p>
-</dd>
-<dt><code>C<code></code> – code text</dt>
-<dd><a name="perlpodspec-C_003ccode_003e-_002d_002d-code-text"></a>
-<p>See the brief discussion in <a href="#perlpod-Formatting-Codes">perlpod
Formatting Codes</a>.
-</p>
-</dd>
-<dt><code>F<filename></code> – style for filenames</dt>
-<dd><a
name="perlpodspec-F_003cfilename_003e-_002d_002d-style-for-filenames"></a>
-<p>See the brief discussion in <a href="#perlpod-Formatting-Codes">perlpod
Formatting Codes</a>.
-</p>
-</dd>
-<dt><code>X<topic name></code> – an index entry</dt>
-<dd><a name="perlpodspec-X_003ctopic-name_003e-_002d_002d-an-index-entry"></a>
-<p>See the brief discussion in <a href="#perlpod-Formatting-Codes">perlpod
Formatting Codes</a>.
-</p>
-<p>This code is unusual in that most formatters completely discard
-this code and its content. Other formatters will render it with
-invisible codes that can be used in building an index of
-the current document.
-</p>
-</dd>
-<dt><code>Z<></code> – a null (zero-effect) formatting code</dt>
-<dd><a
name="perlpodspec-Z_003c_003e-_002d_002d-a-null-_0028zero_002deffect_0029-formatting-code"></a>
-<p>Discussed briefly in <a href="#perlpod-Formatting-Codes">perlpod Formatting
Codes</a>.
-</p>
-<p>This code is unusual is that it should have no content. That is,
-a processor may complain if it sees <code>Z<potatoes></code>. Whether
-or not it complains, the <em>potatoes</em> text should ignored.
-</p>
-</dd>
-<dt><code>L<name></code> – a hyperlink</dt>
-<dd><a name="perlpodspec-L_003cname_003e-_002d_002d-a-hyperlink"></a>
-<p>The complicated syntaxes of this code are discussed at length in
-<a href="#perlpod-Formatting-Codes">perlpod Formatting Codes</a>, and
implementation details are
-discussed below, in <a
href="#perlpodspec-About-L_003c_002e_002e_002e_003e-Codes">About L<...>
Codes</a>. Parsing the
-contents of L<content> is tricky. Notably, the content has to be
-checked for whether it looks like a URL, or whether it has to be split
-on literal "|" and/or "/" (in the right order!), and so on,
-<em>before</em> E<...> codes are resolved.
-</p>
-</dd>
-<dt><code>E<escape></code> – a character escape</dt>
-<dd><a name="perlpodspec-E_003cescape_003e-_002d_002d-a-character-escape"></a>
-<p>See <a href="#perlpod-Formatting-Codes">perlpod Formatting Codes</a>, and
several points in
-<a href="#perlpodspec-Notes-on-Implementing-Pod-Processors">Notes on
Implementing Pod Processors</a>.
-</p>
-</dd>
-<dt><code>S<text></code> – text contains non-breaking spaces</dt>
-<dd><a
name="perlpodspec-S_003ctext_003e-_002d_002d-text-contains-non_002dbreaking-spaces"></a>
-<p>This formatting code is syntactically simple, but semantically
-complex. What it means is that each space in the printable
-content of this code signifies a non-breaking space.
-</p>
-<p>Consider:
-</p>
-<pre class="verbatim"> C<$x ? $y : $z>
-
- S<C<$x ? $y : $z>>
-</pre>
-<p>Both signify the monospace (c[ode] style) text consisting of
-"$x", one space, "?", one space, ":", one space,
"$z". The
-difference is that in the latter, with the S code, those spaces
-are not "normal" spaces, but instead are non-breaking spaces.
-</p>
-</dd>
-</dl>
-
-<p>If a Pod processor sees any formatting code other than the ones
-listed above (as in "N<...>", or "Q<...>",
etc.), that
-processor must by default treat this as an error.
-A Pod parser may allow a way for particular
-applications to add to the above list of known formatting codes;
-a Pod parser might even allow a way to stipulate, for each additional
-command, whether it requires some form of special processing, as
-L<...> does.
-</p>
-<p>Future versions of this specification may add additional
-formatting codes.
-</p>
-<p>Historical note: A few older Pod processors would not see a
">" as
-closing a "C<" code, if the ">" was immediately
preceded by
-a "-". This was so that this:
-</p>
-<pre class="verbatim"> C<$foo->bar>
-</pre>
-<p>would parse as equivalent to this:
-</p>
-<pre class="verbatim"> C<$foo-E<gt>bar>
-</pre>
-<p>instead of as equivalent to a "C" formatting code containing
-only "$foo-", and then a "bar>" outside the
"C" formatting code. This
-problem has since been solved by the addition of syntaxes like this:
-</p>
-<pre class="verbatim"> C<< $foo->bar >>
-</pre>
-<p>Compliant parsers must not treat "->" as special.
-</p>
-<p>Formatting codes absolutely cannot span paragraphs. If a code is
-opened in one paragraph, and no closing code is found by the end of
-that paragraph, the Pod parser must close that formatting code,
-and should complain (as in "Unterminated I code in the paragraph
-starting at line 123: ’Time objects are not...’"). So these
-two paragraphs:
-</p>
-<pre class="verbatim"> I<I told you not to do this!
-
- Don't make me say it again!>
-</pre>
-<p>...must <em>not</em> be parsed as two paragraphs in italics (with the I
-code starting in one paragraph and starting in another.) Instead,
-the first paragraph should generate a warning, but that aside, the
-above code must parse as if it were:
-</p>
-<pre class="verbatim"> I<I told you not to do this!>
-
- Don't make me say it again!E<gt>
-</pre>
-<p>(In SGMLish jargon, all Pod commands are like block-level
-elements, whereas all Pod formatting codes are like inline-level
-elements.)
-</p>
-<hr>
-<a name="perlpodspec-Notes-on-Implementing-Pod-Processors"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodspec-About-L_003c_002e_002e_002e_003e-Codes"
accesskey="n" rel="next">perlpodspec About L<...> Codes</a>, Previous: <a
href="#perlpodspec-Pod-Formatting-Codes" accesskey="p" rel="prev">perlpodspec
Pod Formatting Codes</a>, Up: <a href="#perlpodspec" accesskey="u"
rel="up">perlpodspec</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Notes-on-Implementing-Pod-Processors"></a>
-<h3 class="section">53.6 Notes on Implementing Pod Processors</h3>
-
-<p>The following is a long section of miscellaneous requirements
-and suggestions to do with Pod processing.
-</p>
-<ul>
-<li> Pod formatters should tolerate lines in verbatim blocks that are of
-any length, even if that means having to break them (possibly several
-times, for very long lines) to avoid text running off the side of the
-page. Pod formatters may warn of such line-breaking. Such warnings
-are particularly appropriate for lines are over 100 characters long, which
-are usually not intentional.
-
-</li><li> Pod parsers must recognize <em>all</em> of the three well-known
newline
-formats: CR, LF, and CRLF. See <a href="#perlport-NAME">perlport</a>.
-
-</li><li> Pod parsers should accept input lines that are of any length.
-
-</li><li> Since Perl recognizes a Unicode Byte Order Mark at the start of files
-as signaling that the file is Unicode encoded as in UTF-16 (whether
-big-endian or little-endian) or UTF-8, Pod parsers should do the
-same. Otherwise, the character encoding should be understood as
-being UTF-8 if the first highbit byte sequence in the file seems
-valid as a UTF-8 sequence, or otherwise as CP-1252 (earlier versions of
-this specification used Latin-1 instead of CP-1252).
-
-<p>Future versions of this specification may specify
-how Pod can accept other encodings. Presumably treatment of other
-encodings in Pod parsing would be as in XML parsing: whatever the
-encoding declared by a particular Pod file, content is to be
-stored in memory as Unicode characters.
-</p>
-</li><li> The well known Unicode Byte Order Marks are as follows: if the
-file begins with the two literal byte values 0xFE 0xFF, this is
-the BOM for big-endian UTF-16. If the file begins with the two
-literal byte value 0xFF 0xFE, this is the BOM for little-endian
-UTF-16. On an ASCII platform, if the file begins with the three literal
-byte values
-0xEF 0xBB 0xBF, this is the BOM for UTF-8.
-A mechanism portable to EBCDIC platforms is to:
-
-<pre class="verbatim"> my $utf8_bom = "\x{FEFF}";
- utf8::encode($utf8_bom);
-</pre>
-</li><li> A naive, but often sufficient heuristic on ASCII platforms, for
testing
-the first highbit
-byte-sequence in a BOM-less file (whether in code or in Pod!), to see
-whether that sequence is valid as UTF-8 (RFC 2279) is to check whether
-that the first byte in the sequence is in the range 0xC2 - 0xFD
-<em>and</em> whether the next byte is in the range
-0x80 - 0xBF. If so, the parser may conclude that this file is in
-UTF-8, and all highbit sequences in the file should be assumed to
-be UTF-8. Otherwise the parser should treat the file as being
-in CP-1252. (A better check, and which works on EBCDIC platforms as
-well, is to pass a copy of the sequence to
-<a href="utf8.html#Top">(utf8)utf8::decode()</a> which performs a full
validity check on the
-sequence and returns TRUE if it is valid UTF-8, FALSE otherwise. This
-function is always pre-loaded, is fast because it is written in C, and
-will only get called at most once, so you don’t need to avoid it out of
-performance concerns.)
-In the unlikely circumstance that the first highbit
-sequence in a truly non-UTF-8 file happens to appear to be UTF-8, one
-can cater to our heuristic (as well as any more intelligent heuristic)
-by prefacing that line with a comment line containing a highbit
-sequence that is clearly <em>not</em> valid as UTF-8. A line consisting
-of simply "#", an e-acute, and any non-highbit byte,
-is sufficient to establish this file’s encoding.
-
-</li><li> Pod processors must treat a "=for [label] [content...]"
paragraph as
-meaning the same thing as a "=begin [label]" paragraph, content, and
-an "=end [label]" paragraph. (The parser may conflate these two
-constructs, or may leave them distinct, in the expectation that the
-formatter will nevertheless treat them the same.)
-
-</li><li> When rendering Pod to a format that allows comments (i.e., to nearly
-any format other than plaintext), a Pod formatter must insert comment
-text identifying its name and version number, and the name and
-version numbers of any modules it might be using to process the Pod.
-Minimal examples:
-
-<pre class="verbatim"> %% POD::Pod2PS v3.14159, using POD::Parser v1.92
-
- <!-- Pod::HTML v3.14159, using POD::Parser v1.92 -->
-
- {\doccomm generated by Pod::Tree::RTF 3.14159 using Pod::Tree 1.08}
-
- .\" Pod::Man version 3.14159, using POD::Parser version 1.92
-</pre>
-<p>Formatters may also insert additional comments, including: the
-release date of the Pod formatter program, the contact address for
-the author(s) of the formatter, the current time, the name of input
-file, the formatting options in effect, version of Perl used, etc.
-</p>
-<p>Formatters may also choose to note errors/warnings as comments,
-besides or instead of emitting them otherwise (as in messages to
-STDERR, or <code>die</code>ing).
-</p>
-</li><li> Pod parsers <em>may</em> emit warnings or error messages
("Unknown E code
-E<zslig>!") to STDERR (whether through printing to STDERR, or
-<code>warn</code>ing/<code>carp</code>ing, or
<code>die</code>ing/<code>croak</code>ing), but <em>must</em> allow
-suppressing all such STDERR output, and instead allow an option for
-reporting errors/warnings
-in some other way, whether by triggering a callback, or noting errors
-in some attribute of the document object, or some similarly unobtrusive
-mechanism – or even by appending a "Pod Errors" section to the
end of
-the parsed form of the document.
-
-</li><li> In cases of exceptionally aberrant documents, Pod parsers may abort
the
-parse. Even then, using <code>die</code>ing/<code>croak</code>ing is to be
avoided; where
-possible, the parser library may simply close the input file
-and add text like "*** Formatting Aborted ***" to the end of the
-(partial) in-memory document.
-
-</li><li> In paragraphs where formatting codes (like E<...>,
B<...>)
-are understood (i.e., <em>not</em> verbatim paragraphs, but <em>including</em>
-ordinary paragraphs, and command paragraphs that produce renderable
-text, like "=head1"), literal whitespace should generally be
considered
-"insignificant", in that one literal space has the same meaning as
any
-(nonzero) number of literal spaces, literal newlines, and literal tabs
-(as long as this produces no blank lines, since those would terminate
-the paragraph). Pod parsers should compact literal whitespace in each
-processed paragraph, but may provide an option for overriding this
-(since some processing tasks do not require it), or may follow
-additional special rules (for example, specially treating
-period-space-space or period-newline sequences).
-
-</li><li> Pod parsers should not, by default, try to coerce apostrophe
(’) and
-quote (") into smart quotes (little 9’s, 66’s, 99’s,
etc), nor try to
-turn backtick (‘) into anything else but a single backtick character
-(distinct from an open quote character!), nor "–" into
anything but
-two minus signs. They <em>must never</em> do any of those things to text
-in C<...> formatting codes, and never <em>ever</em> to text in verbatim
-paragraphs.
-
-</li><li> When rendering Pod to a format that has two kinds of hyphens (-), one
-that’s a non-breaking hyphen, and another that’s a breakable hyphen
-(as in "object-oriented", which can be split across lines as
-"object-", newline, "oriented"), formatters are encouraged
to
-generally translate "-" to non-breaking hyphen, but may apply
-heuristics to convert some of these to breaking hyphens.
-
-</li><li> Pod formatters should make reasonable efforts to keep words of Perl
-code from being broken across lines. For example, "Foo::Bar" in some
-formatting systems is seen as eligible for being broken across lines
-as "Foo::" newline "Bar" or even "Foo::-"
newline "Bar". This should
-be avoided where possible, either by disabling all line-breaking in
-mid-word, or by wrapping particular words with internal punctuation
-in "don’t break this across lines" codes (which in some
formats may
-not be a single code, but might be a matter of inserting non-breaking
-zero-width spaces between every pair of characters in a word.)
-
-</li><li> Pod parsers should, by default, expand tabs in verbatim paragraphs as
-they are processed, before passing them to the formatter or other
-processor. Parsers may also allow an option for overriding this.
-
-</li><li> Pod parsers should, by default, remove newlines from the end of
-ordinary and verbatim paragraphs before passing them to the
-formatter. For example, while the paragraph you’re reading now
-could be considered, in Pod source, to end with (and contain)
-the newline(s) that end it, it should be processed as ending with
-(and containing) the period character that ends this sentence.
-
-</li><li> Pod parsers, when reporting errors, should make some effort to report
-an approximate line number ("Nested E<>’s in Paragraph #52,
near
-line 633 of Thing/Foo.pm!"), instead of merely noting the paragraph
-number ("Nested E<>’s in Paragraph #52 of
Thing/Foo.pm!"). Where
-this is problematic, the paragraph number should at least be
-accompanied by an excerpt from the paragraph ("Nested E<>’s in
-Paragraph #52 of Thing/Foo.pm, which begins ’Read/write accessor for
-the C<interest rate> attribute...’").
-
-</li><li> Pod parsers, when processing a series of verbatim paragraphs one
-after another, should consider them to be one large verbatim
-paragraph that happens to contain blank lines. I.e., these two
-lines, which have a blank line between them:
-
-<pre class="verbatim"> use Foo;
-
- print Foo->VERSION
-</pre>
-<p>should be unified into one paragraph ("\tuse Foo;\n\n\tprint
-Foo->VERSION") before being passed to the formatter or other
-processor. Parsers may also allow an option for overriding this.
-</p>
-<p>While this might be too cumbersome to implement in event-based Pod
-parsers, it is straightforward for parsers that return parse trees.
-</p>
-</li><li> Pod formatters, where feasible, are advised to avoid splitting short
-verbatim paragraphs (under twelve lines, say) across pages.
-
-</li><li> Pod parsers must treat a line with only spaces and/or tabs on it as a
-"blank line" such as separates paragraphs. (Some older parsers
-recognized only two adjacent newlines as a "blank line" but would not
-recognize a newline, a space, and a newline, as a blank line. This
-is noncompliant behavior.)
-
-</li><li> Authors of Pod formatters/processors should make every effort to
-avoid writing their own Pod parser. There are already several in
-CPAN, with a wide range of interface styles – and one of them,
-Pod::Parser, comes with modern versions of Perl.
-
-</li><li> Characters in Pod documents may be conveyed either as literals, or by
-number in E<n> codes, or by an equivalent mnemonic, as in
-E<eacute> which is exactly equivalent to E<233>. The numbers
-are the Latin1/Unicode values, even on EBCDIC platforms.
-
-<p>When referring to characters by using a E<n> numeric code, numbers
-in the range 32-126 refer to those well known US-ASCII characters (also
-defined there by Unicode, with the same meaning), which all Pod
-formatters must render faithfully. Characters whose E<> numbers
-are in the ranges 0-31 and 127-159 should not be used (neither as
-literals,
-nor as E<number> codes), except for the literal byte-sequences for
-newline (ASCII 13, ASCII 13 10, or ASCII 10), and tab (ASCII 9).
-</p>
-<p>Numbers in the range 160-255 refer to Latin-1 characters (also
-defined there by Unicode, with the same meaning). Numbers above
-255 should be understood to refer to Unicode characters.
-</p>
-</li><li> Be warned
-that some formatters cannot reliably render characters outside 32-126;
-and many are able to handle 32-126 and 160-255, but nothing above
-255.
-
-</li><li> Besides the well-known "E<lt>" and
"E<gt>" codes for
-less-than and greater-than, Pod parsers must understand
"E<sol>"
-for "/" (solidus, slash), and "E<verbar>" for
"|" (vertical bar,
-pipe). Pod parsers should also understand "E<lchevron>" and
-"E<rchevron>" as legacy codes for characters 171 and 187, i.e.,
-"left-pointing double angle quotation mark" = "left pointing
-guillemet" and "right-pointing double angle quotation mark" =
"right
-pointing guillemet". (These look like little "<<" and
">>", and they
-are now preferably expressed with the HTML/XHTML codes
"E<laquo>"
-and "E<raquo>".)
-
-</li><li> Pod parsers should understand all "E<html>" codes as
defined
-in the entity declarations in the most recent XHTML specification at
-<code>www.W3.org</code>. Pod parsers must understand at least the entities
-that define characters in the range 160-255 (Latin-1). Pod parsers,
-when faced with some unknown "E<<em>identifier</em>>" code,
-shouldn’t simply replace it with nullstring (by default, at least),
-but may pass it through as a string consisting of the literal characters
-E, less-than, <em>identifier</em>, greater-than. Or Pod parsers may offer the
-alternative option of processing such unknown
-"E<<em>identifier</em>>" codes by firing an event especially
-for such codes, or by adding a special node-type to the in-memory
-document tree. Such "E<<em>identifier</em>>" may have special
meaning
-to some processors, or some processors may choose to add them to
-a special error report.
-
-</li><li> Pod parsers must also support the XHTML codes
"E<quot>" for
-character 34 (doublequote, "), "E<amp>" for character 38
-(ampersand, &), and "E<apos>" for character 39
(apostrophe, ’).
-
-</li><li> Note that in all cases of "E<whatever>",
<em>whatever</em> (whether
-an htmlname, or a number in any base) must consist only of
-alphanumeric characters – that is, <em>whatever</em> must watch
-<code>m/\A\w+\z/</code>. So
"E< 0 1 2 3 >"<!-- /@w --> is invalid,
because
-it contains spaces, which aren’t alphanumeric characters. This
-presumably does not <em>need</em> special treatment by a Pod processor;
-" 0 1 2 3 "<!-- /@w --> doesn’t look
like a number in any base, so it would
-presumably be looked up in the table of HTML-like names. Since
-there isn’t (and cannot be) an HTML-like entity called
" 0 1 2 3 "<!-- /@w -->,
-this will be treated as an error. However, Pod processors may
-treat "E< 0 1 2 3 >"<!-- /@w --> or
"E<e-acute>" as <em>syntactically</em>
-invalid, potentially earning a different error message than the
-error message (or warning, or event) generated by a merely unknown
-(but theoretically valid) htmlname, as in "E<qacute>"
-[sic]. However, Pod parsers are not required to make this
-distinction.
-
-</li><li> Note that E<number> <em>must not</em> be interpreted as simply
-"codepoint <em>number</em> in the current/native character set". It
always
-means only "the character represented by codepoint <em>number</em> in
-Unicode." (This is identical to the semantics of &#<em>number</em>;
in XML.)
-
-<p>This will likely require many formatters to have tables mapping from
-treatable Unicode codepoints (such as the "\xE9" for the e-acute
-character) to the escape sequences or codes necessary for conveying
-such sequences in the target output format. A converter to *roff
-would, for example know that "\xE9" (whether conveyed literally, or
via
-a E<...> sequence) is to be conveyed as "e\\*’".
-Similarly, a program rendering Pod in a Mac OS application window, would
-presumably need to know that "\xE9" maps to codepoint 142 in MacRoman
-encoding that (at time of writing) is native for Mac OS. Such
-Unicode2whatever mappings are presumably already widely available for
-common output formats. (Such mappings may be incomplete! Implementers
-are not expected to bend over backwards in an attempt to render
-Cherokee syllabics, Etruscan runes, Byzantine musical symbols, or any
-of the other weird things that Unicode can encode.) And
-if a Pod document uses a character not found in such a mapping, the
-formatter should consider it an unrenderable character.
-</p>
-</li><li> If, surprisingly, the implementor of a Pod formatter can’t
find a
-satisfactory pre-existing table mapping from Unicode characters to
-escapes in the target format (e.g., a decent table of Unicode
-characters to *roff escapes), it will be necessary to build such a
-table. If you are in this circumstance, you should begin with the
-characters in the range 0x00A0 - 0x00FF, which is mostly the heavily
-used accented characters. Then proceed (as patience permits and
-fastidiousness compels) through the characters that the (X)HTML
-standards groups judged important enough to merit mnemonics
-for. These are declared in the (X)HTML specifications at the
-www.W3.org site. At time of writing (September 2001), the most recent
-entity declaration files are:
-
-<pre class="verbatim"> http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent
- http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent
- http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent
-</pre>
-<p>Then you can progress through any remaining notable Unicode characters
-in the range 0x2000-0x204D (consult the character tables at
-www.unicode.org), and whatever else strikes your fancy. For example,
-in <samp>xhtml-symbol.ent</samp>, there is the entry:
-</p>
-<pre class="verbatim"> <!ENTITY infin "&#8734;">
<!-- infinity, U+221E ISOtech -->
-</pre>
-<p>While the mapping "infin" to the character "\x{221E}"
will (hopefully)
-have been already handled by the Pod parser, the presence of the
-character in this file means that it’s reasonably important enough to
-include in a formatter’s table that maps from notable Unicode characters
-to the codes necessary for rendering them. So for a Unicode-to-*roff
-mapping, for example, this would merit the entry:
-</p>
-<pre class="verbatim"> "\x{221E}" => '\(in',
-</pre>
-<p>It is eagerly hoped that in the future, increasing numbers of formats
-(and formatters) will support Unicode characters directly (as (X)HTML
-does with <code>&infin;</code>, <code>&#8734;</code>, or
<code>&#x221E;</code>), reducing the need
-for idiosyncratic mappings of Unicode-to-<em>my_escapes</em>.
-</p>
-</li><li> It is up to individual Pod formatter to display good judgement when
-confronted with an unrenderable character (which is distinct from an
-unknown E<thing> sequence that the parser couldn’t resolve to
-anything, renderable or not). It is good practice to map Latin letters
-with diacritics (like "E<eacute>"/"E<233>") to
the corresponding
-unaccented US-ASCII letters (like a simple character 101, "e"), but
-clearly this is often not feasible, and an unrenderable character may
-be represented as "?", or the like. In attempting a sane fallback
-(as from E<233> to "e"), Pod formatters may use the
-%Latin1Code_to_fallback table in <a
href="Pod-Escapes.html#Top">(Pod-Escapes)Pod::Escapes</a>, or
-<a href="Text-Unidecode.html#Top">(Text-Unidecode)Text::Unidecode</a>, if
available.
-
-<p>For example, this Pod text:
-</p>
-<pre class="verbatim"> magic is enabled if you set C<$Currency> to
'E<euro>'.
-</pre>
-<p>may be rendered as:
-"magic is enabled if you set <code>$Currency</code> to
’<em>?</em>’" or as
-"magic is enabled if you set <code>$Currency</code> to
’<strong>[euro]</strong>’", or as
-"magic is enabled if you set <code>$Currency</code> to
’[x20AC]’, etc.
-</p>
-<p>A Pod formatter may also note, in a comment or warning, a list of what
-unrenderable characters were encountered.
-</p>
-</li><li> E<...> may freely appear in any formatting code (other than
-in another E<...> or in an Z<>). That is, "X<The
-E<euro>1,000,000 Solution>" is valid, as is "L<The
-E<euro>1,000,000 Solution|Million::Euros>".
-
-</li><li> Some Pod formatters output to formats that implement non-breaking
-spaces as an individual character (which I’ll call "NBSP"), and
-others output to formats that implement non-breaking spaces just as
-spaces wrapped in a "don’t break this across lines" code.
Note that
-at the level of Pod, both sorts of codes can occur: Pod can contain a
-NBSP character (whether as a literal, or as a "E<160>" or
-"E<nbsp>" code); and Pod can contain "S<foo
-I<bar> baz>" codes, where "mere spaces" (character 32)
in
-such codes are taken to represent non-breaking spaces. Pod
-parsers should consider supporting the optional parsing of "S<foo
-I<bar> baz>" as if it were
-"foo<em>NBSP</em>I<bar><em>NBSP</em>baz", and, going the other
way, the
-optional parsing of groups of words joined by NBSP’s as if each group
-were in a S<...> code, so that formatters may use the
-representation that maps best to what the output format demands.
-
-</li><li> Some processors may find that the <code>S<...></code> code is
easiest to
-implement by replacing each space in the parse tree under the content
-of the S, with an NBSP. But note: the replacement should apply <em>not</em> to
-spaces in <em>all</em> text, but <em>only</em> to spaces in <em>printable</em>
text. (This
-distinction may or may not be evident in the particular tree/event
-model implemented by the Pod parser.) For example, consider this
-unusual case:
-
-<pre class="verbatim"> S<L</Autoloaded Functions>>
-</pre>
-<p>This means that the space in the middle of the visible link text must
-not be broken across lines. In other words, it’s the same as this:
-</p>
-<pre class="verbatim">
L<"AutoloadedE<160>Functions"/Autoloaded Functions>
-</pre>
-<p>However, a misapplied space-to-NBSP replacement could (wrongly)
-produce something equivalent to this:
-</p>
-<pre class="verbatim">
L<"AutoloadedE<160>Functions"/AutoloadedE<160>Functions>
-</pre>
-<p>...which is almost definitely not going to work as a hyperlink (assuming
-this formatter outputs a format supporting hypertext).
-</p>
-<p>Formatters may choose to just not support the S format code,
-especially in cases where the output format simply has no NBSP
-character/code and no code for "don’t break this stuff across
lines".
-</p>
-</li><li> Besides the NBSP character discussed above, implementors are reminded
-of the existence of the other "special" character in Latin-1, the
-"soft hyphen" character, also known as "discretionary
hyphen",
-i.e. <code>E<173></code> = <code>E<0xAD></code> =
-<code>E<shy></code>). This character expresses an optional hyphenation
-point. That is, it normally renders as nothing, but may render as a
-"-" if a formatter breaks the word at that point. Pod formatters
-should, as appropriate, do one of the following: 1) render this with
-a code with the same meaning (e.g., "\-" in RTF), 2) pass it through
-in the expectation that the formatter understands this character as
-such, or 3) delete it.
-
-<p>For example:
-</p>
-<pre class="verbatim"> sigE<shy>action
- manuE<shy>script
- JarkE<shy>ko HieE<shy>taE<shy>nieE<shy>mi
-</pre>
-<p>These signal to a formatter that if it is to hyphenate "sigaction"
-or "manuscript", then it should be done as
-"sig-<em>[linebreak]</em>action" or
"manu-<em>[linebreak]</em>script"
-(and if it doesn’t hyphenate it, then the <code>E<shy></code>
doesn’t
-show up at all). And if it is
-to hyphenate "Jarkko" and/or "Hietaniemi", it can do
-so only at the points where there is a <code>E<shy></code> code.
-</p>
-<p>In practice, it is anticipated that this character will not be used
-often, but formatters should either support it, or delete it.
-</p>
-</li><li> If you think that you want to add a new command to Pod (like, say, a
-"=biblio" command), consider whether you could get the same
-effect with a for or begin/end sequence: "=for biblio ..." or
"=begin
-biblio" ... "=end biblio". Pod processors that don’t
understand
-"=for biblio", etc, will simply ignore it, whereas they may complain
-loudly if they see "=biblio".
-
-</li><li> Throughout this document, "Pod" has been the preferred
spelling for
-the name of the documentation format. One may also use "POD" or
-"pod". For the documentation that is (typically) in the Pod
-format, you may use "pod", or "Pod", or "POD".
Understanding these
-distinctions is useful; but obsessing over how to spell them, usually
-is not.
-
-</li></ul>
-
-<hr>
-<a name="perlpodspec-About-L_003c_002e_002e_002e_003e-Codes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodspec-About-_003dover_002e_002e_002e_003dback-Regions"
accesskey="n" rel="next">perlpodspec About =over...=back Regions</a>, Previous:
<a href="#perlpodspec-Notes-on-Implementing-Pod-Processors" accesskey="p"
rel="prev">perlpodspec Notes on Implementing Pod Processors</a>, Up: <a
href="#perlpodspec" accesskey="u" rel="up">perlpodspec</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="About-L_003c_002e_002e_002e_003e-Codes"></a>
-<h3 class="section">53.7 About L<...> Codes</h3>
-
-<p>As you can tell from a glance at <a href="#perlpod-NAME">perlpod</a>, the
L<...>
-code is the most complex of the Pod formatting codes. The points below
-will hopefully clarify what it means and how processors should deal
-with it.
-</p>
-<ul>
-<li> In parsing an L<...> code, Pod parsers must distinguish at least
-four attributes:
-
-<dl compact="compact">
-<dt>First:</dt>
-<dd><a name="perlpodspec-First_003a"></a>
-<p>The link-text. If there is none, this must be <code>undef</code>. (E.g.,
in
-"L<Perl Functions|perlfunc>", the link-text is "Perl
Functions".
-In "L<Time::HiRes>" and even
"L<|Time::HiRes>", there is no
-link text. Note that link text may contain formatting.)
-</p>
-</dd>
-<dt>Second:</dt>
-<dd><a name="perlpodspec-Second_003a"></a>
-<p>The possibly inferred link-text; i.e., if there was no real link
-text, then this is the text that we’ll infer in its place. (E.g., for
-"L<Getopt::Std>", the inferred link text is
"Getopt::Std".)
-</p>
-</dd>
-<dt>Third:</dt>
-<dd><a name="perlpodspec-Third_003a"></a>
-<p>The name or URL, or <code>undef</code> if none. (E.g., in "L<Perl
-Functions|perlfunc>", the name (also sometimes called the page)
-is "perlfunc". In "L</CAVEATS>", the name is
<code>undef</code>.)
-</p>
-</dd>
-<dt>Fourth:</dt>
-<dd><a name="perlpodspec-Fourth_003a"></a>
-<p>The section (AKA "item" in older perlpods), or <code>undef</code>
if none. E.g.,
-in "L<Getopt::Std/DESCRIPTION>", "DESCRIPTION" is
the section. (Note
-that this is not the same as a manpage section like the "5" in
"man 5
-crontab". "Section Foo" in the Pod sense means the part of the
text
-that’s introduced by the heading or item whose text is "Foo".)
-</p>
-</dd>
-</dl>
-
-<p>Pod parsers may also note additional attributes including:
-</p>
-<dl compact="compact">
-<dt>Fifth:</dt>
-<dd><a name="perlpodspec-Fifth_003a"></a>
-<p>A flag for whether item 3 (if present) is a URL (like
-"http://lists.perl.org" is), in which case there should be no section
-attribute; a Pod name (like "perldoc" and "Getopt::Std"
are); or
-possibly a man page name (like "crontab(5)" is).
-</p>
-</dd>
-<dt>Sixth:</dt>
-<dd><a name="perlpodspec-Sixth_003a"></a>
-<p>The raw original L<...> content, before text is split on
-"|", "/", etc, and before E<...> codes are expanded.
-</p>
-</dd>
-</dl>
-
-<p>(The above were numbered only for concise reference below. It is not
-a requirement that these be passed as an actual list or array.)
-</p>
-<p>For example:
-</p>
-<pre class="verbatim"> L<Foo::Bar>
- => undef, # link text
- "Foo::Bar", # possibly inferred link text
- "Foo::Bar", # name
- undef, # section
- 'pod', # what sort of link
- "Foo::Bar" # original content
-
- L<Perlport's section on NL's|perlport/Newlines>
- => "Perlport's section on NL's", # link text
- "Perlport's section on NL's", # possibly inferred link text
- "perlport", # name
- "Newlines", # section
- 'pod', # what sort of link
- "Perlport's section on NL's|perlport/Newlines"
- # original content
-
- L<perlport/Newlines>
- => undef, # link text
- '"Newlines" in perlport', # possibly inferred link text
- "perlport", # name
- "Newlines", # section
- 'pod', # what sort of link
- "perlport/Newlines" # original content
-
- L<crontab(5)/"DESCRIPTION">
- => undef, # link text
- '"DESCRIPTION" in crontab(5)', # possibly inferred link text
- "crontab(5)", # name
- "DESCRIPTION", # section
- 'man', # what sort of link
- 'crontab(5)/"DESCRIPTION"' # original content
-
- L</Object Attributes>
- => undef, # link text
- '"Object Attributes"', # possibly inferred link text
- undef, # name
- "Object Attributes", # section
- 'pod', # what sort of link
- "/Object Attributes" # original content
-
- L<http://www.perl.org/>
- => undef, # link text
- "http://www.perl.org/", # possibly inferred link text
- "http://www.perl.org/", # name
- undef, # section
- 'url', # what sort of link
- "http://www.perl.org/" # original content
-
- L<Perl.org|http://www.perl.org/>
- => "Perl.org", # link text
- "http://www.perl.org/", # possibly inferred link text
- "http://www.perl.org/", # name
- undef, # section
- 'url', # what sort of link
- "Perl.org|http://www.perl.org/" # original content
-</pre>
-<p>Note that you can distinguish URL-links from anything else by the
-fact that they match <code>m/\A\w+:[^:\s]\S*\z/</code>. So
-<code>L<http://www.perl.com></code> is a URL, but
-<code>L<HTTP::Response></code> isn’t.
-</p>
-</li><li> In case of L<...> codes with no "text|" part in them,
-older formatters have exhibited great variation in actually displaying
-the link or cross reference. For example, L<crontab(5)> would render
-as "the <code>crontab(5)</code> manpage", or "in the
<code>crontab(5)</code> manpage"
-or just "<code>crontab(5)</code>".
-
-<p>Pod processors must now treat "text|"-less links as follows:
-</p>
-<pre class="verbatim"> L<name> => L<name|name>
- L</section> => L<"section"|/section>
- L<name/section> => L<"section" in
name|name/section>
-</pre>
-</li><li> Note that section names might contain markup. I.e., if a section
-starts with:
-
-<pre class="verbatim"> =head2 About the C<-M> Operator
-</pre>
-<p>or with:
-</p>
-<pre class="verbatim"> =item About the C<-M> Operator
-</pre>
-<p>then a link to it would look like this:
-</p>
-<pre class="verbatim"> L<somedoc/About the C<-M> Operator>
-</pre>
-<p>Formatters may choose to ignore the markup for purposes of resolving
-the link and use only the renderable characters in the section name,
-as in:
-</p>
-<pre class="verbatim"> <h1><a
name="About_the_-M_Operator">About the <code>-M</code>
- Operator</h1>
-
- ...
-
- <a href="somedoc#About_the_-M_Operator">About the
<code>-M</code>
- Operator" in somedoc</a>
-</pre>
-</li><li> Previous versions of perlpod distinguished
<code>L<name/"section"></code>
-links from <code>L<name/item></code> links (and their targets). These
-have been merged syntactically and semantically in the current
-specification, and <em>section</em> can refer either to a
"=head<em>n</em> Heading
-Content" command or to a "=item Item Content" command. This
-specification does not specify what behavior should be in the case
-of a given document having several things all seeming to produce the
-same <em>section</em> identifier (e.g., in HTML, several things all producing
-the same <em>anchorname</em> in <a
name="<em>anchorname</em>">...</a>
-elements). Where Pod processors can control this behavior, they should
-use the first such anchor. That is, <code>L<Foo/Bar></code> refers to
the
-<em>first</em> "Bar" section in Foo.
-
-<p>But for some processors/formats this cannot be easily controlled; as
-with the HTML example, the behavior of multiple ambiguous
-<a name="<em>anchorname</em>">...</a> is most easily
just left up to
-browsers to decide.
-</p>
-</li><li> In a <code>L<text|...></code> code, text may contain
formatting codes
-for formatting or for E<...> escapes, as in:
-
-<pre class="verbatim"> L<B<ummE<234>stuff>|...>
-</pre>
-<p>For <code>L<...></code> codes without a "name|" part, only
-<code>E<...></code> and <code>Z<></code> codes may occur. That is,
-authors should not use "<code>L<B<Foo::Bar>></code>".
-</p>
-<p>Note, however, that formatting codes and Z<>’s can occur in any
-and all parts of an L<...> (i.e., in <em>name</em>, <em>section</em>,
<em>text</em>,
-and <em>url</em>).
-</p>
-<p>Authors must not nest L<...> codes. For example, "L<The
-L<Foo::Bar> man page>" should be treated as an error.
-</p>
-</li><li> Note that Pod authors may use formatting codes inside the
"text"
-part of "L<text|name>" (and so on for
L<text|/"sec">).
-
-<p>In other words, this is valid:
-</p>
-<pre class="verbatim"> Go read L<the docs on
C<$.>|perlvar/"$.">
-</pre>
-<p>Some output formats that do allow rendering "L<...>" codes
as
-hypertext, might not allow the link-text to be formatted; in
-that case, formatters will have to just ignore that formatting.
-</p>
-</li><li> At time of writing, <code>L<name></code> values are of two
types:
-either the name of a Pod page like <code>L<Foo::Bar></code> (which
-might be a real Perl module or program in an @INC / PATH
-directory, or a .pod file in those places); or the name of a Unix
-man page, like <code>L<crontab(5)></code>. In theory,
<code>L<chmod></code>
-in ambiguous between a Pod page called "chmod", or the Unix man page
-"chmod" (in whatever man-section). However, the presence of a string
-in parens, as in "crontab(5)", is sufficient to signal that what
-is being discussed is not a Pod page, and so is presumably a
-Unix man page. The distinction is of no importance to many
-Pod processors, but some processors that render to hypertext formats
-may need to distinguish them in order to know how to render a
-given <code>L<foo></code> code.
-
-</li><li> Previous versions of perlpod allowed for a
<code>L<section></code> syntax (as in
-<code>L<Object Attributes></code>), which was not easily distinguishable
from
-<code>L<name></code> syntax and for
<code>L<"section"></code> which was only
-slightly less ambiguous. This syntax is no longer in the specification, and
-has been replaced by the <code>L</section></code> syntax (where the
slash was
-formerly optional). Pod parsers should tolerate the
<code>L<"section"></code>
-syntax, for a while at least. The suggested heuristic for distinguishing
-<code>L<section></code> from <code>L<name></code> is that if it
contains any
-whitespace, it’s a <em>section</em>. Pod processors should warn about
this being
-deprecated syntax.
-
-</li></ul>
-
-<hr>
-<a name="perlpodspec-About-_003dover_002e_002e_002e_003dback-Regions"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlpodspec-About-Data-Paragraphs-and-_0022_003dbegin_002f_003dend_0022-Regions"
accesskey="n" rel="next">perlpodspec About Data Paragraphs and
"=begin/=end" Regions</a>, Previous: <a
href="#perlpodspec-About-L_003c_002e_002e_002e_003e-Codes" accesskey="p"
rel="prev">perlpodspec About L<...> Codes</a>, Up: <a href="#perlpodspec"
accesskey="u" rel="up">perlpodspec</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="About-_003dover_002e_002e_002e_003dback-Regions"></a>
-<h3 class="section">53.8 About =over...=back Regions</h3>
-
-<p>"=over"..."=back" regions are used for various kinds of
list-like
-structures. (I use the term "region" here simply as a collective
-term for everything from the "=over" to the matching
"=back".)
-</p>
-<ul>
-<li> The non-zero numeric <em>indentlevel</em> in "=over
<em>indentlevel</em>" ...
-"=back" is used for giving the formatter a clue as to how many
-"spaces" (ems, or roughly equivalent units) it should tab over,
-although many formatters will have to convert this to an absolute
-measurement that may not exactly match with the size of spaces (or M’s)
-in the document’s base font. Other formatters may have to completely
-ignore the number. The lack of any explicit <em>indentlevel</em> parameter is
-equivalent to an <em>indentlevel</em> value of 4. Pod processors may
-complain if <em>indentlevel</em> is present but is not a positive number
-matching <code>m/\A(\d*\.)?\d+\z/</code>.
-
-</li><li> Authors of Pod formatters are reminded that "=over" ...
"=back" may
-map to several different constructs in your output format. For
-example, in converting Pod to (X)HTML, it can map to any of
-<ul>...</ul>, <ol>...</ol>, <dl>...</dl>,
or
-<blockquote>...</blockquote>. Similarly, "=item" can
map to <li> or
-<dt>.
-
-</li><li> Each "=over" ... "=back" region should be one of
the following:
-
-<ul>
-<li> An "=over" ... "=back" region containing only
"=item *" commands,
-each followed by some number of ordinary/verbatim paragraphs, other
-nested "=over" ... "=back" regions, "=for..."
paragraphs, and
-"=begin"..."=end" regions.
-
-<p>(Pod processors must tolerate a bare "=item" as if it were
"=item
-*".) Whether "*" is rendered as a literal asterisk, an
"o", or as
-some kind of real bullet character, is left up to the Pod formatter,
-and may depend on the level of nesting.
-</p>
-</li><li> An "=over" ... "=back" region containing only
-<code>m/\A=item\s+\d+\.?\s*\z/</code> paragraphs, each one (or each group of
them)
-followed by some number of ordinary/verbatim paragraphs, other nested
-"=over" ... "=back" regions, "=for..."
paragraphs, and/or
-"=begin"..."=end" codes. Note that the numbers must start
at 1
-in each section, and must proceed in order and without skipping
-numbers.
-
-<p>(Pod processors must tolerate lines like "=item 1" as if they were
-"=item 1.", with the period.)
-</p>
-</li><li> An "=over" ... "=back" region containing only
"=item [text]"
-commands, each one (or each group of them) followed by some number of
-ordinary/verbatim paragraphs, other nested "=over" ...
"=back"
-regions, or "=for..." paragraphs, and
"=begin"..."=end" regions.
-
-<p>The "=item [text]" paragraph should not match
-<code>m/\A=item\s+\d+\.?\s*\z/</code> or <code>m/\A=item\s+\*\s*\z/</code>,
nor should it
-match just <code>m/\A=item\s*\z/</code>.
-</p>
-</li><li> An "=over" ... "=back" region containing no
"=item" paragraphs at
-all, and containing only some number of
-ordinary/verbatim paragraphs, and possibly also some nested "=over"
-... "=back" regions, "=for..." paragraphs, and
"=begin"..."=end"
-regions. Such an itemless "=over" ... "=back" region in
Pod is
-equivalent in meaning to a
"<blockquote>...</blockquote>" element in
-HTML.
-
-</li></ul>
-
-<p>Note that with all the above cases, you can determine which type of
-"=over" ... "=back" you have, by examining the first
(non-"=cut",
-non-"=pod") Pod paragraph after the "=over" command.
-</p>
-</li><li> Pod formatters <em>must</em> tolerate arbitrarily large amounts of
text
-in the "=item <em>text...</em>" paragraph. In practice, most such
-paragraphs are short, as in:
-
-<pre class="verbatim"> =item For cutting off our trade with all parts of the
world
-</pre>
-<p>But they may be arbitrarily long:
-</p>
-<pre class="verbatim"> =item For transporting us beyond seas to be tried for
pretended
- offenses
-
- =item He is at this time transporting large armies of foreign
- mercenaries to complete the works of death, desolation and
- tyranny, already begun with circumstances of cruelty and perfidy
- scarcely paralleled in the most barbarous ages, and totally
- unworthy the head of a civilized nation.
-</pre>
-</li><li> Pod processors should tolerate "=item *" / "=item
<em>number</em>" commands
-with no accompanying paragraph. The middle item is an example:
-
-<pre class="verbatim"> =over
-
- =item 1
-
- Pick up dry cleaning.
-
- =item 2
-
- =item 3
-
- Stop by the store. Get Abba Zabas, Stoli, and cheap lawn chairs.
-
- =back
-</pre>
-</li><li> No "=over" ... "=back" region can contain
headings. Processors may
-treat such a heading as an error.
-
-</li><li> Note that an "=over" ... "=back" region should
have some
-content. That is, authors should not have an empty region like this:
-
-<pre class="verbatim"> =over
-
- =back
-</pre>
-<p>Pod processors seeing such a contentless "=over" ...
"=back" region,
-may ignore it, or may report it as an error.
-</p>
-</li><li> Processors must tolerate an "=over" list that goes off the
end of the
-document (i.e., which has no matching "=back"), but they may warn
-about such a list.
-
-</li><li> Authors of Pod formatters should note that this construct:
-
-<pre class="verbatim"> =item Neque
-
- =item Porro
-
- =item Quisquam Est
-
- Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
- velit, sed quia non numquam eius modi tempora incidunt ut
- labore et dolore magnam aliquam quaerat voluptatem.
-
- =item Ut Enim
-</pre>
-<p>is semantically ambiguous, in a way that makes formatting decisions
-a bit difficult. On the one hand, it could be mention of an item
-"Neque", mention of another item "Porro", and mention of
another
-item "Quisquam Est", with just the last one requiring the explanatory
-paragraph "Qui dolorem ipsum quia dolor..."; and then an item
-"Ut Enim". In that case, you’d want to format it like so:
-</p>
-<pre class="verbatim"> Neque
-
- Porro
-
- Quisquam Est
- Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
- velit, sed quia non numquam eius modi tempora incidunt ut
- labore et dolore magnam aliquam quaerat voluptatem.
-
- Ut Enim
-</pre>
-<p>But it could equally well be a discussion of three (related or equivalent)
-items, "Neque", "Porro", and "Quisquam Est",
followed by a paragraph
-explaining them all, and then a new item "Ut Enim". In that case,
you’d
-probably want to format it like so:
-</p>
-<pre class="verbatim"> Neque
- Porro
- Quisquam Est
- Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
- velit, sed quia non numquam eius modi tempora incidunt ut
- labore et dolore magnam aliquam quaerat voluptatem.
-
- Ut Enim
-</pre>
-<p>But (for the foreseeable future), Pod does not provide any way for Pod
-authors to distinguish which grouping is meant by the above
-"=item"-cluster structure. So formatters should format it like so:
-</p>
-<pre class="verbatim"> Neque
-
- Porro
-
- Quisquam Est
-
- Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
- velit, sed quia non numquam eius modi tempora incidunt ut
- labore et dolore magnam aliquam quaerat voluptatem.
-
- Ut Enim
-</pre>
-<p>That is, there should be (at least roughly) equal spacing between
-items as between paragraphs (although that spacing may well be less
-than the full height of a line of text). This leaves it to the reader
-to use (con)textual cues to figure out whether the "Qui dolorem
-ipsum..." paragraph applies to the "Quisquam Est" item or to
all three
-items "Neque", "Porro", and "Quisquam Est".
While not an ideal
-situation, this is preferable to providing formatting cues that may
-be actually contrary to the author’s intent.
-</p>
-</li></ul>
-
-<hr>
-<a
name="perlpodspec-About-Data-Paragraphs-and-_0022_003dbegin_002f_003dend_0022-Regions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodspec-SEE-ALSO" accesskey="n" rel="next">perlpodspec SEE
ALSO</a>, Previous: <a
href="#perlpodspec-About-_003dover_002e_002e_002e_003dback-Regions"
accesskey="p" rel="prev">perlpodspec About =over...=back Regions</a>, Up: <a
href="#perlpodspec" accesskey="u" rel="up">perlpodspec</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a
name="About-Data-Paragraphs-and-_0022_003dbegin_002f_003dend_0022-Regions"></a>
-<h3 class="section">53.9 About Data Paragraphs and "=begin/=end"
Regions</h3>
-
-<p>Data paragraphs are typically used for inlining non-Pod data that is
-to be used (typically passed through) when rendering the document to
-a specific format:
-</p>
-<pre class="verbatim"> =begin rtf
-
- \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}
-
- =end rtf
-</pre>
-<p>The exact same effect could, incidentally, be achieved with a single
-"=for" paragraph:
-</p>
-<pre class="verbatim"> =for rtf \par{\pard\qr\sa4500{\i
Printed\~\chdate\~\chtime}\par}
-</pre>
-<p>(Although that is not formally a data paragraph, it has the same
-meaning as one, and Pod parsers may parse it as one.)
-</p>
-<p>Another example of a data paragraph:
-</p>
-<pre class="verbatim"> =begin html
-
- I like <em>PIE</em>!
-
- <hr>Especially pecan pie!
-
- =end html
-</pre>
-<p>If these were ordinary paragraphs, the Pod parser would try to
-expand the "E</em>" (in the first paragraph) as a formatting
-code, just like "E<lt>" or "E<eacute>". But
since this
-is in a "=begin <em>identifier</em>"..."=end
<em>identifier</em>" region <em>and</em>
-the identifier "html" doesn’t begin have a ":"
prefix, the contents
-of this region are stored as data paragraphs, instead of being
-processed as ordinary paragraphs (or if they began with a spaces
-and/or tabs, as verbatim paragraphs).
-</p>
-<p>As a further example: At time of writing, no "biblio" identifier
is
-supported, but suppose some processor were written to recognize it as
-a way of (say) denoting a bibliographic reference (necessarily
-containing formatting codes in ordinary paragraphs). The fact that
-"biblio" paragraphs were meant for ordinary processing would be
-indicated by prefacing each "biblio" identifier with a colon:
-</p>
-<pre class="verbatim"> =begin :biblio
-
- Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
- Programs.> Prentice-Hall, Englewood Cliffs, NJ.
-
- =end :biblio
-</pre>
-<p>This would signal to the parser that paragraphs in this begin...end
-region are subject to normal handling as ordinary/verbatim paragraphs
-(while still tagged as meant only for processors that understand the
-"biblio" identifier). The same effect could be had with:
-</p>
-<pre class="verbatim"> =for :biblio
- Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
- Programs.> Prentice-Hall, Englewood Cliffs, NJ.
-</pre>
-<p>The ":" on these identifiers means simply "process this stuff
-normally, even though the result will be for some special target".
-I suggest that parser APIs report "biblio" as the target identifier,
-but also report that it had a ":" prefix. (And similarly, with the
-above "html", report "html" as the target identifier, and
note the
-<em>lack</em> of a ":" prefix.)
-</p>
-<p>Note that a "=begin <em>identifier</em>"..."=end
<em>identifier</em>" region where
-<em>identifier</em> begins with a colon, <em>can</em> contain commands. For
example:
-</p>
-<pre class="verbatim"> =begin :biblio
-
- Wirth's classic is available in several editions, including:
-
- =for comment
- hm, check abebooks.com for how much used copies cost.
-
- =over
-
- =item
-
- Wirth, Niklaus. 1975. I<Algorithmen und Datenstrukturen.>
- Teubner, Stuttgart. [Yes, it's in German.]
-
- =item
-
- Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
- Programs.> Prentice-Hall, Englewood Cliffs, NJ.
-
- =back
-
- =end :biblio
-</pre>
-<p>Note, however, a "=begin <em>identifier</em>"..."=end
<em>identifier</em>"
-region where <em>identifier</em> does <em>not</em> begin with a colon, should
not
-directly contain "=head1" ... "=head4" commands, nor
"=over", nor "=back",
-nor "=item". For example, this may be considered invalid:
-</p>
-<pre class="verbatim"> =begin somedata
-
- This is a data paragraph.
-
- =head1 Don't do this!
-
- This is a data paragraph too.
-
- =end somedata
-</pre>
-<p>A Pod processor may signal that the above (specifically the
"=head1"
-paragraph) is an error. Note, however, that the following should
-<em>not</em> be treated as an error:
-</p>
-<pre class="verbatim"> =begin somedata
-
- This is a data paragraph.
-
- =cut
-
- # Yup, this isn't Pod anymore.
- sub excl { (rand() > .5) ? "hoo!" : "hah!" }
-
- =pod
-
- This is a data paragraph too.
-
- =end somedata
-</pre>
-<p>And this too is valid:
-</p>
-<pre class="verbatim"> =begin someformat
-
- This is a data paragraph.
-
- And this is a data paragraph.
-
- =begin someotherformat
-
- This is a data paragraph too.
-
- And this is a data paragraph too.
-
- =begin :yetanotherformat
-
- =head2 This is a command paragraph!
-
- This is an ordinary paragraph!
-
- And this is a verbatim paragraph!
-
- =end :yetanotherformat
-
- =end someotherformat
-
- Another data paragraph!
-
- =end someformat
-</pre>
-<p>The contents of the above "=begin :yetanotherformat" ...
-"=end :yetanotherformat" region <em>aren’t</em> data
paragraphs, because
-the immediately containing region’s identifier
(":yetanotherformat")
-begins with a colon. In practice, most regions that contain
-data paragraphs will contain <em>only</em> data paragraphs; however,
-the above nesting is syntactically valid as Pod, even if it is
-rare. However, the handlers for some formats, like "html",
-will accept only data paragraphs, not nested regions; and they may
-complain if they see (targeted for them) nested regions, or commands,
-other than "=end", "=pod", and "=cut".
-</p>
-<p>Also consider this valid structure:
-</p>
-<pre class="verbatim"> =begin :biblio
-
- Wirth's classic is available in several editions, including:
-
- =over
-
- =item
-
- Wirth, Niklaus. 1975. I<Algorithmen und Datenstrukturen.>
- Teubner, Stuttgart. [Yes, it's in German.]
-
- =item
-
- Wirth, Niklaus. 1976. I<Algorithms + Data Structures =
- Programs.> Prentice-Hall, Englewood Cliffs, NJ.
-
- =back
-
- Buy buy buy!
-
- =begin html
-
- <img src='wirth_spokesmodeling_book.png'>
-
- <hr>
-
- =end html
-
- Now now now!
-
- =end :biblio
-</pre>
-<p>There, the "=begin html"..."=end html" region is nested
inside
-the larger "=begin :biblio"..."=end :biblio" region. Note
that the
-content of the "=begin html"..."=end html" region is data
-paragraph(s), because the immediately containing region’s identifier
-("html") <em>doesn’t</em> begin with a colon.
-</p>
-<p>Pod parsers, when processing a series of data paragraphs one
-after another (within a single region), should consider them to
-be one large data paragraph that happens to contain blank lines. So
-the content of the above "=begin html"..."=end html"
<em>may</em> be stored
-as two data paragraphs (one consisting of
-"<img src=’wirth_spokesmodeling_book.png’>\n"
-and another consisting of "<hr>\n"), but <em>should</em> be
stored as
-a single data paragraph (consisting of
-"<img
src=’wirth_spokesmodeling_book.png’>\n\n<hr>\n").
-</p>
-<p>Pod processors should tolerate empty
-"=begin <em>something</em>"..."=end <em>something</em>"
regions,
-empty "=begin :<em>something</em>"..."=end
:<em>something</em>" regions, and
-contentless "=for <em>something</em>" and "=for
:<em>something</em>"
-paragraphs. I.e., these should be tolerated:
-</p>
-<pre class="verbatim"> =for html
-
- =begin html
-
- =end html
-
- =begin :biblio
-
- =end :biblio
-</pre>
-<p>Incidentally, note that there’s no easy way to express a data
-paragraph starting with something that looks like a command. Consider:
-</p>
-<pre class="verbatim"> =begin stuff
-
- =shazbot
-
- =end stuff
-</pre>
-<p>There, "=shazbot" will be parsed as a Pod command
"shazbot", not as a data
-paragraph "=shazbot\n". However, you can express a data paragraph
consisting
-of "=shazbot\n" using this code:
-</p>
-<pre class="verbatim"> =for stuff =shazbot
-</pre>
-<p>The situation where this is necessary, is presumably quite rare.
-</p>
-<p>Note that =end commands must match the currently open =begin command. That
-is, they must properly nest. For example, this is valid:
-</p>
-<pre class="verbatim"> =begin outer
-
- X
-
- =begin inner
-
- Y
-
- =end inner
-
- Z
-
- =end outer
-</pre>
-<p>while this is invalid:
-</p>
-<pre class="verbatim"> =begin outer
-
- X
-
- =begin inner
-
- Y
-
- =end outer
-
- Z
-
- =end inner
-</pre>
-<p>This latter is improper because when the "=end outer" command is
seen, the
-currently open region has the formatname "inner", not
"outer". (It just
-happens that "outer" is the format name of a higher-up region.)
This is
-an error. Processors must by default report this as an error, and may halt
-processing the document containing that error. A corollary of this is that
-regions cannot "overlap". That is, the latter block above does not
represent
-a region called "outer" which contains X and Y, overlapping a region
called
-"inner" which contains Y and Z. But because it is invalid (as all
-apparently overlapping regions would be), it doesn’t represent that, or
-anything at all.
-</p>
-<p>Similarly, this is invalid:
-</p>
-<pre class="verbatim"> =begin thing
-
- =end hting
-</pre>
-<p>This is an error because the region is opened by "thing", and the
"=end"
-tries to close "hting" [sic].
-</p>
-<p>This is also invalid:
-</p>
-<pre class="verbatim"> =begin thing
-
- =end
-</pre>
-<p>This is invalid because every "=end" command must have a
formatname
-parameter.
-</p>
-<hr>
-<a name="perlpodspec-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodspec-AUTHOR" accesskey="n" rel="next">perlpodspec
AUTHOR</a>, Previous: <a
href="#perlpodspec-About-Data-Paragraphs-and-_0022_003dbegin_002f_003dend_0022-Regions"
accesskey="p" rel="prev">perlpodspec About Data Paragraphs and
"=begin/=end" Regions</a>, Up: <a href="#perlpodspec" accesskey="u"
rel="up">perlpodspec</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-27"></a>
-<h3 class="section">53.10 SEE ALSO</h3>
-
-<p><a href="#perlpod-NAME">perlpod NAME</a>, <a
href="#perlsyn-PODs_003a-Embedded-Documentation">perlsyn PODs: Embedded
Documentation</a>,
-<a href="podchecker.html#Top">(podchecker)</a>
-</p>
-<hr>
-<a name="perlpodspec-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlpodspec-SEE-ALSO" accesskey="p" rel="prev">perlpodspec
SEE ALSO</a>, Up: <a href="#perlpodspec" accesskey="u" rel="up">perlpodspec</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-23"></a>
-<h3 class="section">53.11 AUTHOR</h3>
-
-<p>Sean M. Burke
-</p>
-<hr>
-<a name="perlpodstyle"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpolicy" accesskey="n" rel="next">perlpolicy</a>, Previous:
<a href="#perlpodspec" accesskey="p" rel="prev">perlpodspec</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlpodstyle-1"></a>
-<h2 class="chapter">54 perlpodstyle</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlpodstyle-NAME"
accesskey="1">perlpodstyle NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpodstyle-DESCRIPTION"
accesskey="2">perlpodstyle DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpodstyle-SEE-ALSO-1"
accesskey="3">perlpodstyle SEE ALSO 1</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpodstyle-AUTHOR-1"
accesskey="4">perlpodstyle AUTHOR 1</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpodstyle-COPYRIGHT-AND-LICENSE-1" accesskey="5">perlpodstyle
COPYRIGHT AND LICENSE 1</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpodstyle-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodstyle-DESCRIPTION" accesskey="n"
rel="next">perlpodstyle DESCRIPTION</a>, Up: <a href="#perlpodstyle"
accesskey="u" rel="up">perlpodstyle</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-53"></a>
-<h3 class="section">54.1 NAME</h3>
-
-<p>perlpodstyle - Perl POD style guide
-</p>
-<hr>
-<a name="perlpodstyle-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodstyle-SEE-ALSO-1" accesskey="n" rel="next">perlpodstyle
SEE ALSO 1</a>, Previous: <a href="#perlpodstyle-NAME" accesskey="p"
rel="prev">perlpodstyle NAME</a>, Up: <a href="#perlpodstyle" accesskey="u"
rel="up">perlpodstyle</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-52"></a>
-<h3 class="section">54.2 DESCRIPTION</h3>
-
-<p>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.
-</p>
-<p>The name of the program being documented is conventionally written in bold
-(using B<>) wherever it occurs, as are all program options.
-Arguments should be written in italics (I<>). 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 C<>. References to other man pages should be in the form
-<code>manpage(section)</code> or <code>L<manpage(section)></code>, and
Pod::Man will
-automatically format those appropriately. The second form, with
-L<>, 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 <code>L<Module::Name></code> for
module
-references instead.
-</p>
-<p>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
-B<>.
-</p>
-<p>The major headers should be set out using a <code>=head1</code> 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 <code>=head2</code>, and are typically in mixed case.
-</p>
-<p>The standard sections of a manual page are:
-</p>
-<dl compact="compact">
-<dt>NAME</dt>
-<dd><a name="perlpodstyle-NAME-1"></a>
-<p>Mandatory section; should be a comma-separated list of programs or
-functions documented by this POD page, such as:
-</p>
-<pre class="verbatim"> foo, bar - programs to do something
-</pre>
-<p>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
-C<> or B<> anywhere in this line. Functions should not be
-qualified with <code>()</code> or the like. The description should ideally
fit on a
-single line, even if a man program replaces the dash with a few tabs.
-</p>
-</dd>
-<dt>SYNOPSIS</dt>
-<dd><a name="perlpodstyle-SYNOPSIS"></a>
-<p>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.
-</p>
-</dd>
-<dt>DESCRIPTION</dt>
-<dd><a name="perlpodstyle-DESCRIPTION-1"></a>
-<p>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
-<code>=head2</code> directives like:
-</p>
-<pre class="verbatim"> =head2 Normal Usage
-
- =head2 Advanced Features
-
- =head2 Writing Configuration Files
-</pre>
-<p>or whatever is appropriate for your documentation.
-</p>
-<p>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
-<code>=item</code> 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.
-</p>
-</dd>
-<dt>OPTIONS</dt>
-<dd><a name="perlpodstyle-OPTIONS"></a>
-<p>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 <a href="Pod-Usage.html#Top">(Pod-Usage)</a>. This is normally
presented as a list, with
-each option as a separate <code>=item</code>. The specific option string
should be
-enclosed in B<>. Any values that the option takes should be
-enclosed in I<>. For example, the section for the option
-<strong>–section</strong>=<em>manext</em> would be introduced with:
-</p>
-<pre class="verbatim"> =item B<--section>=I<manext>
-</pre>
-<p>Synonymous options (like both the short and long forms) are separated by a
-comma and a space on the same <code>=item</code> line, or optionally listed as
their
-own item with a reference to the canonical name. For example, since
-<strong>–section</strong> can also be written as <strong>-s</strong>,
the above would be:
-</p>
-<pre class="verbatim"> =item B<-s> I<manext>,
B<--section>=I<manext>
-</pre>
-<p>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.
-</p>
-</dd>
-<dt>RETURN VALUE</dt>
-<dd><a name="perlpodstyle-RETURN-VALUE"></a>
-<p>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.
-</p>
-</dd>
-<dt>ERRORS</dt>
-<dd><a name="perlpodstyle-ERRORS"></a>
-<p>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 <code>STDOUT</code> or <code>STDERR</code> 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.
-</p>
-</dd>
-<dt>DIAGNOSTICS</dt>
-<dd><a name="perlpodstyle-DIAGNOSTICS"></a>
-<p>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).
-</p>
-<p>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.
-</p>
-</dd>
-<dt>EXAMPLES</dt>
-<dd><a name="perlpodstyle-EXAMPLES"></a>
-<p>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.
-</p>
-<p>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.
-</p>
-</dd>
-<dt>ENVIRONMENT</dt>
-<dd><a name="perlpodstyle-ENVIRONMENT"></a>
-<p>Environment variables that the program cares about, normally presented as
-a list using <code>=over</code>, <code>=item</code>, and <code>=back</code>.
For example:
-</p>
-<pre class="verbatim"> =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
-</pre>
-<p>Since environment variables are normally in all uppercase, no additional
-special formatting is generally needed; they’re glaring enough as it is.
-</p>
-</dd>
-<dt>FILES</dt>
-<dd><a name="perlpodstyle-FILES"></a>
-<p>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 F<>.
-It’s particularly important to document files that will be potentially
-modified.
-</p>
-</dd>
-<dt>CAVEATS</dt>
-<dd><a name="perlpodstyle-CAVEATS"></a>
-<p>Things to take special care with, sometimes called WARNINGS.
-</p>
-</dd>
-<dt>BUGS</dt>
-<dd><a name="perlpodstyle-BUGS"></a>
-<p>Things that are broken or just don’t work quite right.
-</p>
-</dd>
-<dt>RESTRICTIONS</dt>
-<dd><a name="perlpodstyle-RESTRICTIONS"></a>
-<p>Bugs you don’t plan to fix. :-)
-</p>
-</dd>
-<dt>NOTES</dt>
-<dd><a name="perlpodstyle-NOTES"></a>
-<p>Miscellaneous commentary.
-</p>
-</dd>
-<dt>AUTHOR</dt>
-<dd><a name="perlpodstyle-AUTHOR"></a>
-<p>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.
-</p>
-</dd>
-<dt>HISTORY</dt>
-<dd><a name="perlpodstyle-HISTORY"></a>
-<p>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.
-</p>
-</dd>
-<dt>COPYRIGHT AND LICENSE</dt>
-<dd><a name="perlpodstyle-COPYRIGHT-AND-LICENSE"></a>
-<p>For copyright
-</p>
-<pre class="verbatim"> Copyright YEAR(s) YOUR NAME(s)
-</pre>
-<p>(No, (C) is not needed. No, "all rights reserved" is not needed.)
-</p>
-<p>For licensing the easiest way is to use the same licensing as Perl itself:
-</p>
-<pre class="verbatim"> This library is free software; you may redistribute
it and/or
- modify it under the same terms as Perl itself.
-</pre>
-<p>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.
-</p>
-</dd>
-<dt>SEE ALSO</dt>
-<dd><a name="perlpodstyle-SEE-ALSO"></a>
-<p>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 <code>name(section)</code> form, don’t have to be
enclosed in
-L<> (although it’s recommended), but other things in this section
-probably should be when appropriate.
-</p>
-<p>If the package has a mailing list, include a URL or subscription
-instructions here.
-</p>
-<p>If the package has a web site, include a URL here.
-</p>
-</dd>
-</dl>
-
-<p>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.
-</p>
-<p>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.
-</p>
-<p>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.
-</p>
-<p>Finally, as a general note, try not to use an excessive amount of markup.
-As documented here and in <a href="Pod-Man.html#Top">(Pod-Man)</a>, 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
-L<>, so don’t do that.
-</p>
-<hr>
-<a name="perlpodstyle-SEE-ALSO-1"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodstyle-AUTHOR-1" accesskey="n" rel="next">perlpodstyle
AUTHOR 1</a>, Previous: <a href="#perlpodstyle-DESCRIPTION" accesskey="p"
rel="prev">perlpodstyle DESCRIPTION</a>, Up: <a href="#perlpodstyle"
accesskey="u" rel="up">perlpodstyle</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-28"></a>
-<h3 class="section">54.3 SEE ALSO</h3>
-
-<p>For additional information that may be more accurate for your specific
-system, see either <a href="http://man.he.net/man5/man";>man(5)</a> or <a
href="http://man.he.net/man7/man";>man(7)</a> depending on your system manual
-section numbering conventions.
-</p>
-<p>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/>.
-</p>
-<hr>
-<a name="perlpodstyle-AUTHOR-1"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpodstyle-COPYRIGHT-AND-LICENSE-1" accesskey="n"
rel="next">perlpodstyle COPYRIGHT AND LICENSE 1</a>, Previous: <a
href="#perlpodstyle-SEE-ALSO-1" accesskey="p" rel="prev">perlpodstyle SEE ALSO
1</a>, Up: <a href="#perlpodstyle" accesskey="u" rel="up">perlpodstyle</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-24"></a>
-<h3 class="section">54.4 AUTHOR</h3>
-
-<p>Russ Allbery <address@hidden>, with large portions of this
documentation
-taken from the documentation of the original <strong>pod2man</strong>
implementation by
-Larry Wall and Tom Christiansen.
-</p>
-<hr>
-<a name="perlpodstyle-COPYRIGHT-AND-LICENSE-1"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlpodstyle-AUTHOR-1" accesskey="p"
rel="prev">perlpodstyle AUTHOR 1</a>, Up: <a href="#perlpodstyle" accesskey="u"
rel="up">perlpodstyle</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="COPYRIGHT-AND-LICENSE"></a>
-<h3 class="section">54.5 COPYRIGHT AND LICENSE</h3>
-
-<p>Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010 Russ Allbery
-<address@hidden>.
-</p>
-<p>This documentation is free software; you may redistribute it and/or modify
-it under the same terms as Perl itself.
-</p>
-<hr>
-<a name="perlpolicy"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport" accesskey="n" rel="next">perlport</a>, Previous: <a
href="#perlpodstyle" accesskey="p" rel="prev">perlpodstyle</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlpolicy-1"></a>
-<h2 class="chapter">55 perlpolicy</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlpolicy-NAME"
accesskey="1">perlpolicy NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpolicy-DESCRIPTION"
accesskey="2">perlpolicy DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpolicy-GOVERNANCE"
accesskey="3">perlpolicy GOVERNANCE</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-MAINTENANCE-AND-SUPPORT" accesskey="4">perlpolicy MAINTENANCE
AND SUPPORT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-BACKWARD-COMPATIBILITY-AND-DEPRECATION"
accesskey="5">perlpolicy BACKWARD COMPATIBILITY AND
DEPRECATION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-MAINTENANCE-BRANCHES" accesskey="6">perlpolicy MAINTENANCE
BRANCHES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-CONTRIBUTED-MODULES" accesskey="7">perlpolicy CONTRIBUTED
MODULES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpolicy-DOCUMENTATION"
accesskey="8">perlpolicy DOCUMENTATION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-STANDARDS-OF-CONDUCT" accesskey="9">perlpolicy STANDARDS OF
CONDUCT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-CREDITS">perlpolicy CREDITS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpolicy-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpolicy-DESCRIPTION" accesskey="n" rel="next">perlpolicy
DESCRIPTION</a>, Up: <a href="#perlpolicy" accesskey="u"
rel="up">perlpolicy</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-54"></a>
-<h3 class="section">55.1 NAME</h3>
-
-<p>perlpolicy - Various and sundry policies and commitments related to the
Perl core
-</p>
-<hr>
-<a name="perlpolicy-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpolicy-GOVERNANCE" accesskey="n" rel="next">perlpolicy
GOVERNANCE</a>, Previous: <a href="#perlpolicy-NAME" accesskey="p"
rel="prev">perlpolicy NAME</a>, Up: <a href="#perlpolicy" accesskey="u"
rel="up">perlpolicy</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-53"></a>
-<h3 class="section">55.2 DESCRIPTION</h3>
-
-<p>This document is the master document which records all written
-policies about how the Perl 5 Porters collectively develop and maintain
-the Perl core.
-</p>
-<hr>
-<a name="perlpolicy-GOVERNANCE"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpolicy-MAINTENANCE-AND-SUPPORT" accesskey="n"
rel="next">perlpolicy MAINTENANCE AND SUPPORT</a>, Previous: <a
href="#perlpolicy-DESCRIPTION" accesskey="p" rel="prev">perlpolicy
DESCRIPTION</a>, Up: <a href="#perlpolicy" accesskey="u"
rel="up">perlpolicy</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="GOVERNANCE"></a>
-<h3 class="section">55.3 GOVERNANCE</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlpolicy-Perl-5-Porters"
accesskey="1">perlpolicy Perl 5 Porters</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpolicy-Perl-5-Porters"></a>
-<div class="header">
-<p>
-Up: <a href="#perlpolicy-GOVERNANCE" accesskey="u" rel="up">perlpolicy
GOVERNANCE</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Perl-5-Porters"></a>
-<h4 class="subsection">55.3.1 Perl 5 Porters</h4>
-
-<p>Subscribers to perl5-porters (the porters themselves) come in several
flavours.
-Some are quiet curious lurkers, who rarely pitch in and instead watch
-the ongoing development to ensure they’re forewarned of new changes or
-features in Perl. Some are representatives of vendors, who are there
-to make sure that Perl continues to compile and work on their
-platforms. Some patch any reported bug that they know how to fix,
-some are actively patching their pet area (threads, Win32, the regexp
--engine), while others seem to do nothing but complain. In other
-words, it’s your usual mix of technical people.
-</p>
-<p>Over this group of porters presides Larry Wall. He has the final word
-in what does and does not change in any of the Perl programming languages.
-These days, Larry spends most of his time on Perl 6, while Perl 5 is
-shepherded by a "pumpking", a porter responsible for deciding what
-goes into each release and ensuring that releases happen on a regular
-basis.
-</p>
-<p>Larry sees Perl development along the lines of the US government:
-there’s the Legislature (the porters), the Executive branch (the
--pumpking), and the Supreme Court (Larry). The legislature can
-discuss and submit patches to the executive branch all they like, but
-the executive branch is free to veto them. Rarely, the Supreme Court
-will side with the executive branch over the legislature, or the
-legislature over the executive branch. Mostly, however, the
-legislature and the executive branch are supposed to get along and
-work out their differences without impeachment or court cases.
-</p>
-<p>You might sometimes see reference to Rule 1 and Rule 2. Larry’s power
-as Supreme Court is expressed in The Rules:
-</p>
-<ol>
-<li> Larry is always by definition right about how Perl should behave.
-This means he has final veto power on the core functionality.
-
-</li><li> Larry is allowed to change his mind about any matter at a later date,
-regardless of whether he previously invoked Rule 1.
-
-</li></ol>
-
-<p>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.
-</p>
-<hr>
-<a name="perlpolicy-MAINTENANCE-AND-SUPPORT"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpolicy-BACKWARD-COMPATIBILITY-AND-DEPRECATION"
accesskey="n" rel="next">perlpolicy BACKWARD COMPATIBILITY AND DEPRECATION</a>,
Previous: <a href="#perlpolicy-GOVERNANCE" accesskey="p" rel="prev">perlpolicy
GOVERNANCE</a>, Up: <a href="#perlpolicy" accesskey="u" rel="up">perlpolicy</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="MAINTENANCE-AND-SUPPORT"></a>
-<h3 class="section">55.4 MAINTENANCE AND SUPPORT</h3>
-
-<p>Perl 5 is developed by a community, not a corporate entity. Every change
-contributed to the Perl core is the result of a donation. Typically, these
-donations are contributions of code or time by individual members of our
-community. On occasion, these donations come in the form of corporate
-or organizational sponsorship of a particular individual or project.
-</p>
-<p>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.
-</p>
-<p>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.
-</p>
-<p>This document codifies the support and maintenance commitments that
-the Perl community should expect from Perl’s developers:
-</p>
-<ul>
-<li> We "officially" support the two most recent stable release
series. 5.16.x
-and earlier are now out of support. As of the release of 5.22.0, we will
-"officially" end support for Perl 5.18.x, other than providing
security
-updates as described below.
-
-</li><li> 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
-current release series take precedence over fixes for the previous
-release series.
-
-</li><li> To the best of our ability, we will provide "critical"
security patches
-/ 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.
-
-</li><li> We will not provide security updates or bug fixes for development
-releases of Perl.
-
-</li><li> We encourage vendors to ship the most recent supported release of
-Perl at the time of their code freeze.
-
-</li><li> As a vendor, you may have a requirement to backport security fixes
-beyond our 3 year support commitment. We can provide limited support and
-advice to you as you do so and, where possible will try to apply
-those patches to the relevant -maint branches in git, though we may or
-may not choose to make numbered releases or "official" patches
-available. Contact us at <address@hidden>
-to begin that process.
-
-</li></ul>
-
-<hr>
-<a name="perlpolicy-BACKWARD-COMPATIBILITY-AND-DEPRECATION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpolicy-MAINTENANCE-BRANCHES" accesskey="n"
rel="next">perlpolicy MAINTENANCE BRANCHES</a>, Previous: <a
href="#perlpolicy-MAINTENANCE-AND-SUPPORT" accesskey="p" rel="prev">perlpolicy
MAINTENANCE AND SUPPORT</a>, Up: <a href="#perlpolicy" accesskey="u"
rel="up">perlpolicy</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="BACKWARD-COMPATIBILITY-AND-DEPRECATION"></a>
-<h3 class="section">55.5 BACKWARD COMPATIBILITY AND DEPRECATION</h3>
-
-<p>Our community has a long-held belief that backward-compatibility is a
-virtue, even when the functionality in question is a design flaw.
-</p>
-<p>We would all love to unmake some mistakes we’ve made over the past
-decades. Living with every design error we’ve ever made can lead
-to painful stagnation. Unwinding our mistakes is very, very
-difficult. Doing so without actively harming our users is
-nearly impossible.
-</p>
-<p>Lately, ignoring or actively opposing compatibility with earlier versions
-of Perl has come into vogue. Sometimes, a change is proposed which
-wants to usurp syntax which previously had another meaning. Sometimes,
-a change wants to improve previously-crazy semantics.
-</p>
-<p>Down this road lies madness.
-</p>
-<p>Requiring end-user programmers to change just a few language constructs,
-even language constructs which no well-educated developer would ever
-intentionally use is tantamount to saying "you should not upgrade to
-a new release of Perl unless you have 100% test coverage and can do a
-full manual audit of your codebase." If we were to have tools capable of
-reliably upgrading Perl source code from one version of Perl to another,
-this concern could be significantly mitigated.
-</p>
-<p>We want to ensure that Perl continues to grow and flourish in the coming
-years and decades, but not at the expense of our user community.
-</p>
-<p>Existing syntax and semantics should only be marked for destruction in
-very limited circumstances. If they are believed to be very rarely used,
-stand in the way of actual improvement to the Perl language or perl
-interpreter, and if affected code can be easily updated to continue
-working, they may be considered for removal. When in doubt, caution
-dictates that we will favor backward compatibility. When a feature is
-deprecated, a statement of reasoning describing the decision process
-will be posted, and a link to it will be provided in the relevant
-perldelta documents.
-</p>
-<p>Using a lexical pragma to enable or disable legacy behavior should be
-considered when appropriate, and in the absence of any pragma legacy
-behavior should be enabled. Which backward-incompatible changes are
-controlled implicitly by a ’use v5.x.y’ is a decision which should
be
-made by the pumpking in consultation with the community.
-</p>
-<p>Historically, we’ve held ourselves to a far higher standard than
-backward-compatibility – bugward-compatibility. Any accident of
-implementation or unintentional side-effect of running some bit of code
-has been considered to be a feature of the language to be defended with
-the same zeal as any other feature or functionality. No matter how
-frustrating these unintentional features may be to us as we continue
-to improve Perl, these unintentional features often deserve our
-protection. It is very important that existing software written in
-Perl continue to work correctly. If end-user developers have adopted a
-bug as a feature, we need to treat it as such.
-</p>
-<p>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. In most cases,
-these additions will be marked as <em>experimental</em> for some time. See
-below for more on that.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlpolicy-Terminology"
accesskey="1">perlpolicy Terminology</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpolicy-Terminology"></a>
-<div class="header">
-<p>
-Up: <a href="#perlpolicy-BACKWARD-COMPATIBILITY-AND-DEPRECATION" accesskey="u"
rel="up">perlpolicy BACKWARD COMPATIBILITY AND DEPRECATION</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Terminology"></a>
-<h4 class="subsection">55.5.1 Terminology</h4>
-
-<p>To make sure we’re talking about the same thing when we discuss the
removal
-of features or functionality from the Perl core, we have specific definitions
-for a few words and phrases.
-</p>
-<dl compact="compact">
-<dt>experimental</dt>
-<dd><a name="perlpolicy-experimental"></a>
-<p>If something in the Perl core is marked as <strong>experimental</strong>,
we may change
-its behaviour, deprecate or remove it without notice. While we’ll always
-do our best to smooth the transition path for users of experimental
-features, you should contact the perl5-porters mailinglist if you find
-an experimental feature useful and want to help shape its future.
-</p>
-<p>Experimental features must be experimental in two stable releases before
being
-marked non-experimental. Experimental features will only have their
-experimental status revoked when they no longer have any design-changing bugs
-open against them and when they have remained unchanged in behavior for the
-entire length of a development cycle. In other words, a feature present in
-v5.20.0 may be marked no longer experimental in v5.22.0 if and only if its
-behavior is unchanged throughout all of v5.21.
-</p>
-</dd>
-<dt>deprecated</dt>
-<dd><a name="perlpolicy-deprecated"></a>
-<p>If something in the Perl core is marked as <strong>deprecated</strong>, we
may remove it
-from the core in the future, though we might not. Generally, backward
-incompatible changes will have deprecation warnings for two release
-cycles before being removed, but may be removed after just one cycle if
-the risk seems quite low or the benefits quite high.
-</p>
-<p>As of
-Perl 5.12, deprecated features and modules warn the user as they’re used.
-When a module is deprecated, it will also be made available on CPAN.
-Installing it from CPAN will silence deprecation warnings for that module.
-</p>
-<p>If you use a deprecated feature or module and believe that its removal from
-the Perl core would be a mistake, please contact the perl5-porters
-mailinglist and plead your case. We don’t deprecate things without a
good
-reason, but sometimes there’s a counterargument we haven’t
considered.
-Historically, we did not distinguish between "deprecated" and
"discouraged"
-features.
-</p>
-</dd>
-<dt>discouraged</dt>
-<dd><a name="perlpolicy-discouraged"></a>
-<p>From time to time, we may mark language constructs and features which we
-consider to have been mistakes as <strong>discouraged</strong>. Discouraged
features
-aren’t currently candidates for removal, but
-we may later deprecate them if they’re found to stand in the way of a
-significant improvement to the Perl core.
-</p>
-</dd>
-<dt>removed</dt>
-<dd><a name="perlpolicy-removed"></a>
-<p>Once a feature, construct or module has been marked as deprecated, we
-may remove it from the Perl core. Unsurprisingly,
-we say we’ve <strong>removed</strong> these things. When a module is
removed, it will
-no longer ship with Perl, but will continue to be available on CPAN.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlpolicy-MAINTENANCE-BRANCHES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpolicy-CONTRIBUTED-MODULES" accesskey="n"
rel="next">perlpolicy CONTRIBUTED MODULES</a>, Previous: <a
href="#perlpolicy-BACKWARD-COMPATIBILITY-AND-DEPRECATION" accesskey="p"
rel="prev">perlpolicy BACKWARD COMPATIBILITY AND DEPRECATION</a>, Up: <a
href="#perlpolicy" accesskey="u" rel="up">perlpolicy</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="MAINTENANCE-BRANCHES"></a>
-<h3 class="section">55.6 MAINTENANCE BRANCHES</h3>
-
-<p>New releases of maintenance branches should only contain changes that fall
into
-one of the "acceptable" categories set out below, but must not
contain any
-changes that fall into one of the "unacceptable" categories. (For
example, a
-fix for a crashing bug must not be included if it breaks binary compatibility.)
-</p>
-<p>It is not necessary to include every change meeting these criteria, and in
-general the focus should be on addressing security issues, crashing bugs,
-regressions and serious installation issues. The temptation to include a
-plethora of minor changes that don’t affect the installation or
execution of
-perl (e.g. spelling corrections in documentation) should be resisted in order
-to reduce the overall risk of overlooking something. The intention is to
-create maintenance releases which are both worthwhile and which users can have
-full confidence in the stability of. (A secondary concern is to avoid burning
-out the maint-pumpking or overwhelming other committers voting on changes to be
-included (see <a
href="#perlpolicy-Getting-changes-into-a-maint-branch">Getting changes into a
maint branch</a> below).)
-</p>
-<p>The following types of change may be considered acceptable, as long as they
do
-not also fall into any of the "unacceptable" categories set out
below:
-</p>
-<ul>
-<li> Patches that fix CVEs or security issues. These changes should
-be run through the address@hidden mailing list
-rather than applied directly.
-
-</li><li> Patches that fix crashing bugs, assertion failures and
-memory corruption but which do not otherwise change perl’s
-functionality or negatively impact performance.
-
-</li><li> Patches that fix regressions in perl’s behavior relative to
previous
-releases, no matter how old the regression, since some people may
-upgrade from very old versions of perl to the latest version.
-
-</li><li> Patches that fix bugs in features that were new in the corresponding
5.x.0
-stable release.
-
-</li><li> Patches that fix anything which prevents or seriously impacts the
build
-or installation of perl.
-
-</li><li> Portability fixes, such as changes to Configure and the files in
-the hints/ folder.
-
-</li><li> Minimal patches that fix platform-specific test failures.
-
-</li><li> Documentation updates that correct factual errors, explain
significant
-bugs or deficiencies in the current implementation, or fix broken markup.
-
-</li><li> Updates to dual-life modules should consist of minimal patches to
-fix crashing bugs or security issues (as above). Any changes made to
-dual-life modules for which CPAN is canonical should be coordinated with
-the upstream author.
-
-</li></ul>
-
-<p>The following types of change are NOT acceptable:
-</p>
-<ul>
-<li> Patches that break binary compatibility. (Please talk to a pumpking.)
-
-</li><li> Patches that add or remove features.
-
-</li><li> Patches that add new warnings or errors or deprecate features.
-
-</li><li> Ports of Perl to a new platform, architecture or OS release that
-involve changes to the implementation.
-
-</li><li> New versions of dual-life modules should NOT be imported into maint.
-Those belong in the next stable series.
-
-</li></ul>
-
-<p>If there is any question about whether a given patch might merit
-inclusion in a maint release, then it almost certainly should not
-be included.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-Getting-changes-into-a-maint-branch" accesskey="1">perlpolicy
Getting changes into a maint branch</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpolicy-Getting-changes-into-a-maint-branch"></a>
-<div class="header">
-<p>
-Up: <a href="#perlpolicy-MAINTENANCE-BRANCHES" accesskey="u"
rel="up">perlpolicy MAINTENANCE BRANCHES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Getting-changes-into-a-maint-branch"></a>
-<h4 class="subsection">55.6.1 Getting changes into a maint branch</h4>
-
-<p>Historically, only the pumpking cherry-picked changes from bleadperl
-into maintperl. This has scaling problems. At the same time,
-maintenance branches of stable versions of Perl need to be treated with
-great care. To that end, as of Perl 5.12, we have a new process for
-maint branches.
-</p>
-<p>Any committer may cherry-pick any commit from blead to a maint branch if
-they send mail to perl5-porters announcing their intent to cherry-pick
-a specific commit along with a rationale for doing so and at least two
-other committers respond to the list giving their assent. (This policy
-applies to current and former pumpkings, as well as other committers.)
-</p>
-<p>Other voting mechanisms may be used instead, as long as the same number of
-votes is gathered in a transparent manner. Specifically, proposals of
-which changes to cherry-pick must be visible to everyone on perl5-porters
-so that the views of everyone interested may be heard.
-</p>
-<p>It is not necessary for voting to be held on cherry-picking perldelta
-entries associated with changes that have already been cherry-picked, nor
-for the maint-pumpking to obtain votes on changes required by the
-<samp>Porting/release_managers_guide.pod</samp> where such changes can be
applied by
-the means of cherry-picking from blead.
-</p>
-<hr>
-<a name="perlpolicy-CONTRIBUTED-MODULES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpolicy-DOCUMENTATION" accesskey="n" rel="next">perlpolicy
DOCUMENTATION</a>, Previous: <a href="#perlpolicy-MAINTENANCE-BRANCHES"
accesskey="p" rel="prev">perlpolicy MAINTENANCE BRANCHES</a>, Up: <a
href="#perlpolicy" accesskey="u" rel="up">perlpolicy</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="CONTRIBUTED-MODULES"></a>
-<h3 class="section">55.7 CONTRIBUTED MODULES</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlpolicy-A-Social-Contract-about-Artistic-Control"
accesskey="1">perlpolicy A Social Contract about Artistic
Control</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpolicy-A-Social-Contract-about-Artistic-Control"></a>
-<div class="header">
-<p>
-Up: <a href="#perlpolicy-CONTRIBUTED-MODULES" accesskey="u"
rel="up">perlpolicy CONTRIBUTED MODULES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="A-Social-Contract-about-Artistic-Control"></a>
-<h4 class="subsection">55.7.1 A Social Contract about Artistic Control</h4>
-
-<p>What follows is a statement about artistic control, defined as the ability
-of authors of packages to guide the future of their code and maintain
-control over their work. It is a recognition that authors should have
-control over their work, and that it is a responsibility of the rest of
-the Perl community to ensure that they retain this control. It is an
-attempt to document the standards to which we, as Perl developers, intend
-to hold ourselves. It is an attempt to write down rough guidelines about
-the respect we owe each other as Perl developers.
-</p>
-<p>This statement is not a legal contract. This statement is not a legal
-document in any way, shape, or form. Perl is distributed under the GNU
-Public License and under the Artistic License; those are the precise legal
-terms. This statement isn’t about the law or licenses. It’s about
-community, mutual respect, trust, and good-faith cooperation.
-</p>
-<p>We recognize that the Perl core, defined as the software distributed with
-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
-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
-necessarily mean some loss of control over it, since changes may
-occasionally have to be made on short notice or for consistency with the
-rest of Perl.
-</p>
-<p>Once a module has been included in the Perl core, however, everyone
-involved in maintaining Perl should be aware that the module is still the
-property of the original author unless the original author explicitly
-gives up their ownership of it. In particular:
-</p>
-<ul>
-<li> 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.
-
-</li><li> Patches may be applied by the pumpkin holder without the explicit
-cooperation of the module author if and only if they are very minor,
-time-critical in some fashion (such as urgent security fixes), or if
-the module author cannot be reached. Those patches must still be
-given back to the author when possible, and if the author decides on
-an alternate fix in their version, that fix should be strongly
-preferred unless there is a serious problem with it. Any changes not
-endorsed by the author should be marked as such, and the contributor
-of the change acknowledged.
-
-</li><li> The version of the module distributed with Perl should, whenever
-possible, be the latest version of the module as distributed by the
-author (the latest non-beta version in the case of public Perl
-releases), although the pumpkin holder may hold off on upgrading the
-version of the module distributed with Perl to the latest version
-until the latest version has had sufficient testing.
-
-</li></ul>
-
-<p>In other words, the author of a module should be considered to have final
-say on modifications to their module whenever possible (bearing in mind
-that it’s expected that everyone involved will work together and arrive
at
-reasonable compromises when there are disagreements).
-</p>
-<p>As a last resort, however:
-</p>
-<p>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 Perl core from the
-one maintained by the author. This should not be done lightly and
-should <strong>always</strong> 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 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.
-</p>
-<p>Again, this should be a last resort only. Ideally, this should never
-happen, and every possible effort at cooperation and compromise should be
-made before doing this. If it does prove necessary to fork a module for
-the overall health of Perl, proper credit must be given to the original
-author in perpetuity and the decision should be constantly re-evaluated to
-see if a remerging of the two branches is possible down the road.
-</p>
-<p>In all dealings with contributed modules, everyone maintaining Perl should
-keep in mind that the code belongs to the original author, that they may
-not be on perl5-porters at any given time, and that a patch is not
-official unless it has been integrated into the author’s copy of the
-module. To aid with this, and with points #1, #2, and #3 above, contact
-information for the authors of all contributed modules should be kept with
-the Perl distribution.
-</p>
-<p>Finally, the Perl community as a whole recognizes that respect for
-ownership of code, respect for artistic control, proper credit, and active
-effort to prevent unintentional code skew or communication gaps is vital
-to the health of the community and Perl itself. Members of a community
-should not normally have to resort to rules and laws to deal with each
-other, and this document, although it contains rules so as to be clear, is
-about an attitude and general approach. The first step in any dispute
-should be open communication, respect for opposing views, and an attempt
-at a compromise. In nearly every circumstance nothing more will be
-necessary, and certainly no more drastic measure should be used until
-every avenue of communication and discussion has failed.
-</p>
-<hr>
-<a name="perlpolicy-DOCUMENTATION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpolicy-STANDARDS-OF-CONDUCT" accesskey="n"
rel="next">perlpolicy STANDARDS OF CONDUCT</a>, Previous: <a
href="#perlpolicy-CONTRIBUTED-MODULES" accesskey="p" rel="prev">perlpolicy
CONTRIBUTED MODULES</a>, Up: <a href="#perlpolicy" accesskey="u"
rel="up">perlpolicy</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DOCUMENTATION"></a>
-<h3 class="section">55.8 DOCUMENTATION</h3>
-
-<p>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.
-</p>
-<p>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.
-</p>
-<p>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 <code>use strict</code> and
<code>use warnings</code>,
-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.
-</p>
-<p>As Perl is developed by a global team of volunteers, our
-documentation often contains spellings which look funny
-to <em>somebody</em>. 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.
-</p>
-<p>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.
-</p>
-<hr>
-<a name="perlpolicy-STANDARDS-OF-CONDUCT"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpolicy-CREDITS" accesskey="n" rel="next">perlpolicy
CREDITS</a>, Previous: <a href="#perlpolicy-DOCUMENTATION" accesskey="p"
rel="prev">perlpolicy DOCUMENTATION</a>, Up: <a href="#perlpolicy"
accesskey="u" rel="up">perlpolicy</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="STANDARDS-OF-CONDUCT"></a>
-<h3 class="section">55.9 STANDARDS OF CONDUCT</h3>
-
-<p>The official forum for the development of perl is the perl5-porters mailing
-list, mentioned above, and its bugtracker at rt.perl.org. All participants in
-discussion there are expected to adhere to a standard of conduct.
-</p>
-<ul>
-<li> Always be civil.
-
-</li><li> Heed the moderators.
-
-</li></ul>
-
-<p>Civility is simple: stick to the facts while avoiding demeaning remarks and
-sarcasm. It is not enough to be factual. You must also be civil. Responding
-in kind to incivility is not acceptable.
-</p>
-<p>While civility is required, kindness is encouraged; if you have any doubt
about
-whether you are being civil, simply ask yourself, "Am I being kind?"
and aspire
-to that.
-</p>
-<p>If the list moderators tell you that you are not being civil, carefully
-consider how your words have appeared before responding in any way. Were they
-kind? You may protest, but repeated protest in the face of a repeatedly
-reaffirmed decision is not acceptable.
-</p>
-<p>Unacceptable behavior will result in a public and clearly identified
warning.
-Repeated unacceptable behavior will result in removal from the mailing list and
-revocation of rights to update rt.perl.org. The first removal is for one
-month. Subsequent removals will double in length. After six months with no
-warning, a user’s ban length is reset. Removals, like warnings, are
public.
-</p>
-<p>The list of moderators will be public knowledge. At present, it is:
-Aaron Crane, Andy Dougherty, Ricardo Signes, Steffen Müller.
-</p>
-<hr>
-<a name="perlpolicy-CREDITS"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlpolicy-STANDARDS-OF-CONDUCT" accesskey="p"
rel="prev">perlpolicy STANDARDS OF CONDUCT</a>, Up: <a href="#perlpolicy"
accesskey="u" rel="up">perlpolicy</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="CREDITS"></a>
-<h3 class="section">55.10 CREDITS</h3>
-
-<p>"Social Contract about Contributed Modules" originally by Russ
Allbery <address@hidden> and the perl5-porters.
-</p>
-<hr>
-<a name="perlport"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpragma" accesskey="n" rel="next">perlpragma</a>, Previous:
<a href="#perlpolicy" accesskey="p" rel="prev">perlpolicy</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlport-1"></a>
-<h2 class="chapter">56 perlport</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlport-NAME"
accesskey="1">perlport NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-DESCRIPTION"
accesskey="2">perlport DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-ISSUES"
accesskey="3">perlport ISSUES</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-CPAN-Testers"
accesskey="4">perlport CPAN Testers</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-PLATFORMS"
accesskey="5">perlport PLATFORMS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-FUNCTION-IMPLEMENTATIONS" accesskey="6">perlport FUNCTION
IMPLEMENTATIONS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Supported-Platforms" accesskey="7">perlport Supported
Platforms</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-EOL-Platforms"
accesskey="8">perlport EOL Platforms</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Supported-Platforms-_0028Perl-5_002e8_0029"
accesskey="9">perlport Supported Platforms (Perl
5.8)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-SEE-ALSO">perlport
SEE ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-AUTHORS-_002f-CONTRIBUTORS">perlport AUTHORS /
CONTRIBUTORS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlport-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-DESCRIPTION" accesskey="n" rel="next">perlport
DESCRIPTION</a>, Up: <a href="#perlport" accesskey="u" rel="up">perlport</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-55"></a>
-<h3 class="section">56.1 NAME</h3>
-
-<p>perlport - Writing portable Perl
-</p>
-<hr>
-<a name="perlport-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-ISSUES" accesskey="n" rel="next">perlport ISSUES</a>,
Previous: <a href="#perlport-NAME" accesskey="p" rel="prev">perlport NAME</a>,
Up: <a href="#perlport" accesskey="u" rel="up">perlport</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-54"></a>
-<h3 class="section">56.2 DESCRIPTION</h3>
-
-<p>Perl runs on numerous operating systems. While most of them share
-much in common, they also have their own unique features.
-</p>
-<p>This document is meant to help you to find out what constitutes portable
-Perl code. That way once you make a decision to write portably,
-you know where the lines are drawn, and you can stay within them.
-</p>
-<p>There is a tradeoff between taking full advantage of one particular
-type of computer and taking advantage of a full range of them.
-Naturally, as you broaden your range and become more diverse, the
-common factors drop, and you are left with an increasingly smaller
-area of common ground in which you can operate to accomplish a
-particular task. Thus, when you begin attacking a problem, it is
-important to consider under which part of the tradeoff curve you
-want to operate. Specifically, you must decide whether it is
-important that the task that you are coding has the full generality
-of being portable, or whether to just get the job done right now.
-This is the hardest choice to be made. The rest is easy, because
-Perl provides many choices, whichever way you want to approach your
-problem.
-</p>
-<p>Looking at it another way, writing portable code is usually about
-willfully limiting your available choices. Naturally, it takes
-discipline and sacrifice to do that. The product of portability
-and convenience may be a constant. You have been warned.
-</p>
-<p>Be aware of two important points:
-</p>
-<dl compact="compact">
-<dt>Not all Perl programs have to be portable</dt>
-<dd><a name="perlport-Not-all-Perl-programs-have-to-be-portable"></a>
-<p>There is no reason you should not use Perl as a language to glue Unix
-tools together, or to prototype a Macintosh application, or to manage the
-Windows registry. If it makes no sense to aim for portability for one
-reason or another in a given program, then don’t bother.
-</p>
-</dd>
-<dt>Nearly all of Perl already <em>is</em> portable</dt>
-<dd><a name="perlport-Nearly-all-of-Perl-already-is-portable"></a>
-<p>Don’t be fooled into thinking that it is hard to create portable Perl
-code. It isn’t. Perl tries its level-best to bridge the gaps between
-what’s available on different platforms, and all the means available to
-use those features. Thus almost all Perl code runs on any machine
-without modification. But there are some significant issues in
-writing portable code, and this document is entirely about those issues.
-</p>
-</dd>
-</dl>
-
-<p>Here’s the general rule: When you approach a task commonly done
-using a whole range of platforms, think about writing portable
-code. That way, you don’t sacrifice much by way of the implementation
-choices you can avail yourself of, and at the same time you can give
-your users lots of platform choices. On the other hand, when you have to
-take advantage of some unique feature of a particular platform, as is
-often the case with systems programming (whether for Unix, Windows,
-VMS, etc.), consider writing platform-specific code.
-</p>
-<p>When the code will run on only two or three operating systems, you
-may need to consider only the differences of those particular systems.
-The important thing is to decide where the code will run and to be
-deliberate in your decision.
-</p>
-<p>The material below is separated into three main sections: main issues of
-portability (<a href="#perlport-ISSUES">ISSUES</a>), platform-specific issues
(<a href="#perlport-PLATFORMS">PLATFORMS</a>), and
-built-in Perl functions that behave differently on various ports
-(<a href="#perlport-FUNCTION-IMPLEMENTATIONS">FUNCTION IMPLEMENTATIONS</a>).
-</p>
-<p>This information should not be considered complete; it includes possibly
-transient information about idiosyncrasies of some of the ports, almost
-all of which are in a state of constant evolution. Thus, this material
-should be considered a perpetual work in progress
-(<code><IMG SRC="yellow_sign.gif" ALT="Under
Construction"></code>).
-</p>
-<hr>
-<a name="perlport-ISSUES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-CPAN-Testers" accesskey="n" rel="next">perlport CPAN
Testers</a>, Previous: <a href="#perlport-DESCRIPTION" accesskey="p"
rel="prev">perlport DESCRIPTION</a>, Up: <a href="#perlport" accesskey="u"
rel="up">perlport</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="ISSUES"></a>
-<h3 class="section">56.3 ISSUES</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlport-Newlines"
accesskey="1">perlport Newlines</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Numbers-endianness-and-Width" accesskey="2">perlport Numbers
endianness and Width</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Files-and-Filesystems" accesskey="3">perlport Files and
Filesystems</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-System-Interaction" accesskey="4">perlport System
Interaction</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Command-names-versus-file-pathnames" accesskey="5">perlport
Command names versus file pathnames</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-Networking"
accesskey="6">perlport Networking</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Interprocess-Communication-_0028IPC_0029"
accesskey="7">perlport Interprocess Communication
(IPC)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-External-Subroutines-_0028XS_0029" accesskey="8">perlport
External Subroutines (XS)</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-Standard-Modules"
accesskey="9">perlport Standard Modules</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Time-and-Date">perlport Time and
Date</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Character-sets-and-character-encoding">perlport Character sets
and character encoding</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-Internationalisation">perlport
Internationalisation</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-System-Resources">perlport System
Resources</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-Security">perlport
Security</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-Style">perlport
Style</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlport-Newlines"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Numbers-endianness-and-Width" accesskey="n"
rel="next">perlport Numbers endianness and Width</a>, Up: <a
href="#perlport-ISSUES" accesskey="u" rel="up">perlport ISSUES</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Newlines"></a>
-<h4 class="subsection">56.3.1 Newlines</h4>
-
-<p>In most operating systems, lines in files are terminated by newlines.
-Just what is used as a newline may vary from OS to OS. Unix
-traditionally uses <code>\012</code>, one type of DOSish I/O uses
<code>\015\012</code>,
-Mac OS<!-- /@w --> uses <code>\015</code>, and z/OS uses
<code>\025</code>.
-</p>
-<p>Perl uses <code>\n</code> to represent the "logical" newline,
where what is
-logical may depend on the platform in use. In MacPerl, <code>\n</code> always
-means <code>\015</code>. On EBCDIC platforms, <code>\n</code> could be
<code>\025</code> or <code>\045</code>.
-In DOSish perls, <code>\n</code> usually means <code>\012</code>, but when
-accessing a file in "text" mode, perl uses the <code>:crlf</code>
layer that
-translates it to (or from) <code>\015\012</code>, depending on whether
you’re
-reading or writing. Unix does the same thing on ttys in canonical
-mode. <code>\015\012</code> is commonly referred to as CRLF.
-</p>
-<p>To trim trailing newlines from text lines use <code>chomp()</code>. With
default
-settings that function looks for a trailing <code>\n</code> character and thus
-trims in a portable way.
-</p>
-<p>When dealing with binary files (or text files in binary mode) be sure
-to explicitly set $/ to the appropriate value for your file format
-before using <code>chomp()</code>.
-</p>
-<p>Because of the "text" mode translation, DOSish perls have
limitations
-in using <code>seek</code> and <code>tell</code> on a file accessed in
"text" mode.
-Stick to <code>seek</code>-ing to locations you got from <code>tell</code>
(and no
-others), and you are usually free to use <code>seek</code> and
<code>tell</code> even
-in "text" mode. Using <code>seek</code> or <code>tell</code> or
other file operations
-may be non-portable. If you use <code>binmode</code> on a file, however, you
-can usually <code>seek</code> and <code>tell</code> with arbitrary values
safely.
-</p>
-<p>A common misconception in socket programming is that
<code>\n eq \012</code><!-- /@w -->
-everywhere. When using protocols such as common Internet protocols,
-<code>\012</code> and <code>\015</code> are called for specifically, and the
values of
-the logical <code>\n</code> and <code>\r</code> (carriage return) are not
reliable.
-</p>
-<pre class="verbatim"> print SOCKET "Hi there, client!\r\n";
# WRONG
- print SOCKET "Hi there, client!\015\012"; # RIGHT
-</pre>
-<p>However, using <code>\015\012</code> (or <code>\cM\cJ</code>, or
<code>\x0D\x0A</code>) can be tedious
-and unsightly, as well as confusing to those maintaining the code. As
-such, the <code>Socket</code> module supplies the Right Thing for those who
want it.
-</p>
-<pre class="verbatim"> use Socket qw(:DEFAULT :crlf);
- print SOCKET "Hi there, client!$CRLF" # RIGHT
-</pre>
-<p>When reading from a socket, remember that the default input record
-separator <code>$/</code> is <code>\n</code>, but robust socket code will
recognize as
-either <code>\012</code> or <code>\015\012</code> as end of line:
-</p>
-<pre class="verbatim"> while (<SOCKET>) { # NOT ADVISABLE!
- # ...
- }
-</pre>
-<p>Because both CRLF and LF end in LF, the input record separator can
-be set to LF and any CR stripped later. Better to write:
-</p>
-<pre class="verbatim"> use Socket qw(:DEFAULT :crlf);
- local($/) = LF; # not needed if $/ is already \012
-
- while (<SOCKET>) {
- s/$CR?$LF/\n/; # not sure if socket uses LF or CRLF, OK
- # s/\015?\012/\n/; # same thing
- }
-</pre>
-<p>This example is preferred over the previous one–even for Unix
-platforms–because now any <code>\015</code>’s
(<code>\cM</code>’s) are stripped out
-(and there was much rejoicing).
-</p>
-<p>Similarly, functions that return text data–such as a function that
-fetches a web page–should sometimes translate newlines before
-returning the data, if they’ve not yet been translated to the local
-newline representation. A single line of code will often suffice:
-</p>
-<pre class="verbatim"> $data =~ s/\015?\012/\n/g;
- return $data;
-</pre>
-<p>Some of this may be confusing. Here’s a handy reference to the ASCII
CR
-and LF characters. You can print it out and stick it in your wallet.
-</p>
-<pre class="verbatim"> LF eq \012 eq \x0A eq \cJ eq chr(10) eq
ASCII 10
- CR eq \015 eq \x0D eq \cM eq chr(13) eq ASCII 13
-
- | Unix | DOS | Mac |
- ---------------------------
- \n | LF | LF | CR |
- \r | CR | CR | LF |
- \n * | LF | CRLF | CR |
- \r * | CR | CR | LF |
- ---------------------------
- * text-mode STDIO
-</pre>
-<p>The Unix column assumes that you are not accessing a serial line
-(like a tty) in canonical mode. If you are, then CR on input becomes
-"\n", and "\n" on output becomes CRLF.
-</p>
-<p>These are just the most common definitions of <code>\n</code> and
<code>\r</code> in Perl.
-There may well be others. For example, on an EBCDIC implementation
-such as z/OS (OS/390) or OS/400 (using the ILE, the PASE is ASCII-based)
-the above material is similar to "Unix" but the code numbers change:
-</p>
-<pre class="verbatim"> LF eq \025 eq \x15 eq \cU eq chr(21) eq
CP-1047 21
- LF eq \045 eq \x25 eq chr(37) eq CP-0037 37
- CR eq \015 eq \x0D eq \cM eq chr(13) eq CP-1047 13
- CR eq \015 eq \x0D eq \cM eq chr(13) eq CP-0037 13
-
- | z/OS | OS/400 |
- ----------------------
- \n | LF | LF |
- \r | CR | CR |
- \n * | LF | LF |
- \r * | CR | CR |
- ----------------------
- * text-mode STDIO
-</pre>
-<hr>
-<a name="perlport-Numbers-endianness-and-Width"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Files-and-Filesystems" accesskey="n"
rel="next">perlport Files and Filesystems</a>, Previous: <a
href="#perlport-Newlines" accesskey="p" rel="prev">perlport Newlines</a>, Up:
<a href="#perlport-ISSUES" accesskey="u" rel="up">perlport ISSUES</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Numbers-endianness-and-Width"></a>
-<h4 class="subsection">56.3.2 Numbers endianness and Width</h4>
-
-<p>Different CPUs store integers and floating point numbers in different
-orders (called <em>endianness</em>) and widths (32-bit and 64-bit being the
-most common today). This affects your programs when they attempt to transfer
-numbers in binary format from one CPU architecture to another,
-usually either "live" via network connection, or by storing the
-numbers to secondary storage such as a disk file or tape.
-</p>
-<p>Conflicting storage orders make an utter mess out of the numbers. If a
-little-endian host (Intel, VAX) stores 0x12345678 (305419896 in
-decimal), a big-endian host (Motorola, Sparc, PA) reads it as
-0x78563412 (2018915346 in decimal). Alpha and MIPS can be either:
-Digital/Compaq used/uses them in little-endian mode; SGI/Cray uses
-them in big-endian mode. To avoid this problem in network (socket)
-connections use the <code>pack</code> and <code>unpack</code> formats
<code>n</code> and <code>N</code>, the
-"network" orders. These are guaranteed to be portable.
-</p>
-<p>As of Perl 5.10.0, you can also use the <code>></code> and
<code><</code> modifiers
-to force big- or little-endian byte-order. This is useful if you want
-to store signed integers or 64-bit integers, for example.
-</p>
-<p>You can explore the endianness of your platform by unpacking a
-data structure packed in native format such as:
-</p>
-<pre class="verbatim"> print unpack("h*", pack("s2", 1,
2)), "\n";
- # '10002000' on e.g. Intel x86 or Alpha 21064 in little-endian mode
- # '00100020' on e.g. Motorola 68040
-</pre>
-<p>If you need to distinguish between endian architectures you could use
-either of the variables set like so:
-</p>
-<pre class="verbatim"> $is_big_endian = unpack("h*",
pack("s", 1)) =~ /01/;
- $is_little_endian = unpack("h*", pack("s", 1)) =~ /^1/;
-</pre>
-<p>Differing widths can cause truncation even between platforms of equal
-endianness. The platform of shorter width loses the upper parts of the
-number. There is no good solution for this problem except to avoid
-transferring or storing raw binary numbers.
-</p>
-<p>One can circumnavigate both these problems in two ways. Either
-transfer and store numbers always in text format, instead of raw
-binary, or else consider using modules like <code>Data::Dumper</code> and
-<code>Storable</code>
-(included as of Perl 5.8). Keeping all data as text significantly
-simplifies matters.
-</p>
-<p>The v-strings are portable only up to v2147483647 (0x7FFF_FFFF),
that’s
-how far EBCDIC, or more precisely UTF-EBCDIC will go.
-</p>
-<hr>
-<a name="perlport-Files-and-Filesystems"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-System-Interaction" accesskey="n" rel="next">perlport
System Interaction</a>, Previous: <a
href="#perlport-Numbers-endianness-and-Width" accesskey="p" rel="prev">perlport
Numbers endianness and Width</a>, Up: <a href="#perlport-ISSUES" accesskey="u"
rel="up">perlport ISSUES</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Files-and-Filesystems"></a>
-<h4 class="subsection">56.3.3 Files and Filesystems</h4>
-
-<p>Most platforms these days structure files in a hierarchical fashion.
-So, it is reasonably safe to assume that all platforms support the
-notion of a "path" to uniquely identify a file on the system. How
-that path is really written, though, differs considerably.
-</p>
-<p>Although similar, file path specifications differ between Unix,
-Windows, Mac OS<!-- /@w -->, OS/2, VMS, VOS, RISC OS<!-- /@w -->,
and probably others.
-Unix, for example, is one of the few OSes that has the elegant idea
-of a single root directory.
-</p>
-<p>DOS, OS/2, VMS, VOS, and Windows can work similarly to Unix with
<code>/</code>
-as path separator, or in their own idiosyncratic ways (such as having
-several root directories and various "unrooted" device files such
NIL:
-and LPT:).
-</p>
-<p>Mac OS<!-- /@w --> 9 and earlier used <code>:</code> as a path
separator instead of <code>/</code>.
-</p>
-<p>The filesystem may support neither hard links (<code>link</code>) nor
-symbolic links (<code>symlink</code>, <code>readlink</code>,
<code>lstat</code>).
-</p>
-<p>The filesystem may support neither access timestamp nor change
-timestamp (meaning that about the only portable timestamp is the
-modification timestamp), or one second granularity of any timestamps
-(e.g. the FAT filesystem limits the time granularity to two seconds).
-</p>
-<p>The "inode change timestamp" (the <code>-C</code> filetest) may
really be the
-"creation timestamp" (which it is not in Unix).
-</p>
-<p>VOS perl can emulate Unix filenames with <code>/</code> as path separator.
The
-native pathname characters greater-than, less-than, number-sign, and
-percent-sign are always accepted.
-</p>
-<p>RISC OS<!-- /@w --> perl can emulate Unix filenames with
<code>/</code> as path
-separator, or go native and use <code>.</code> for path separator and
<code>:</code> to
-signal filesystems and disk names.
-</p>
-<p>Don’t assume Unix filesystem access semantics: that read, write,
-and execute are all the permissions there are, and even if they exist,
-that their semantics (for example what do <code>"r"</code>,
<code>"w"</code>, and <code>"x"</code> mean on
-a directory) are the Unix ones. The various Unix/POSIX compatibility
-layers usually try to make interfaces like <code>chmod()</code> work, but
sometimes
-there simply is no good mapping.
-</p>
-<p>If all this is intimidating, have no (well, maybe only a little)
-fear. There are modules that can help. The <code>File::Spec</code> modules
-provide methods to do the Right Thing on whatever platform happens
-to be running the program.
-</p>
-<pre class="verbatim"> use File::Spec::Functions;
- chdir(updir()); # go up one directory
- my $file = catfile(curdir(), 'temp', 'file.txt');
- # on Unix and Win32, './temp/file.txt'
- # on Mac OS Classic, ':temp:file.txt'
- # on VMS, '[.temp]file.txt'
-</pre>
-<p><code>File::Spec</code> is available in the standard distribution as of
version
-5.004_05. <code>File::Spec::Functions</code> is only in
<code>File::Spec</code> 0.7 and later,
-and some versions of Perl come with version 0.6. If <code>File::Spec</code>
-is not updated to 0.7 or later, you must use the object-oriented
-interface from <code>File::Spec</code> (or upgrade <code>File::Spec</code>).
-</p>
-<p>In general, production code should not have file paths hardcoded.
-Making them user-supplied or read from a configuration file is
-better, keeping in mind that file path syntax varies on different
-machines.
-</p>
-<p>This is especially noticeable in scripts like Makefiles and test suites,
-which often assume <code>/</code> as a path separator for subdirectories.
-</p>
-<p>Also of use is <code>File::Basename</code> from the standard distribution,
which
-splits a pathname into pieces (base filename, full path to directory,
-and file suffix).
-</p>
-<p>Even when on a single platform (if you can call Unix a single platform),
-remember not to count on the existence or the contents of particular
-system-specific files or directories, like <samp>/etc/passwd</samp>,
-<samp>/etc/sendmail.conf</samp>, <samp>/etc/resolv.conf</samp>, or even
<samp>/tmp/</samp>. For
-example, <samp>/etc/passwd</samp> may exist but not contain the encrypted
-passwords, because the system is using some form of enhanced security.
-Or it may not contain all the accounts, because the system is using NIS.
-If code does need to rely on such a file, include a description of the
-file and its format in the code’s documentation, then make it easy for
-the user to override the default location of the file.
-</p>
-<p>Don’t assume a text file will end with a newline. They should,
-but people forget.
-</p>
-<p>Do not have two files or directories of the same name with different
-case, like <samp>test.pl</samp> and <samp>Test.pl</samp>, as many platforms
have
-case-insensitive (or at least case-forgiving) filenames. Also, try
-not to have non-word characters (except for <code>.</code>) in the names, and
-keep them to the 8.3 convention, for maximum portability, onerous a
-burden though this may appear.
-</p>
-<p>Likewise, when using the <code>AutoSplit</code> module, try to keep your
functions to
-8.3 naming and case-insensitive conventions; or, at the least,
-make it so the resulting files have a unique (case-insensitively)
-first 8 characters.
-</p>
-<p>Whitespace in filenames is tolerated on most systems, but not all,
-and even on systems where it might be tolerated, some utilities
-might become confused by such whitespace.
-</p>
-<p>Many systems (DOS, VMS ODS-2) cannot have more than one <code>.</code> in
their
-filenames.
-</p>
-<p>Don’t assume <code>></code> won’t be the first character of
a filename.
-Always use <code><</code> explicitly to open a file for reading, or even
-better, use the three-arg version of <code>open</code>, unless you want the
user to
-be able to specify a pipe open.
-</p>
-<pre class="verbatim"> open my $fh, '<', $existing_file) or die $!;
-</pre>
-<p>If filenames might use strange characters, it is safest to open it
-with <code>sysopen</code> instead of <code>open</code>. <code>open</code> is
magic and can
-translate characters like <code>></code>, <code><</code>, and
<code>|</code>, which may
-be the wrong thing to do. (Sometimes, though, it’s the right thing.)
-Three-arg open can also help protect against this translation in cases
-where it is undesirable.
-</p>
-<p>Don’t use <code>:</code> as a part of a filename since many systems
use that for
-their own semantics (Mac OS Classic for separating pathname components,
-many networking schemes and utilities for separating the nodename and
-the pathname, and so on). For the same reasons, avoid <code>@</code>,
<code>;</code> and
-<code>|</code>.
-</p>
-<p>Don’t assume that in pathnames you can collapse two leading slashes
-<code>//</code> into one: some networking and clustering filesystems have
special
-semantics for that. Let the operating system sort it out.
-</p>
-<p>The <em>portable filename characters</em> as defined by ANSI C are
-</p>
-<pre class="verbatim"> a b c d e f g h i j k l m n o p q r t u v w x y z
- A B C D E F G H I J K L M N O P Q R T U V W X Y Z
- 0 1 2 3 4 5 6 7 8 9
- . _ -
-</pre>
-<p>and the <code>"-"</code> shouldn’t be the first character.
If you want to be
-hypercorrect, stay case-insensitive and within the 8.3 naming
-convention (all the files and directories have to be unique within one
-directory if their names are lowercased and truncated to eight
-characters before the <code>.</code>, if any, and to three characters after the
-<code>.</code>, if any). (And do not use <code>.</code>s in directory names.)
-</p>
-<hr>
-<a name="perlport-System-Interaction"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Command-names-versus-file-pathnames" accesskey="n"
rel="next">perlport Command names versus file pathnames</a>, Previous: <a
href="#perlport-Files-and-Filesystems" accesskey="p" rel="prev">perlport Files
and Filesystems</a>, Up: <a href="#perlport-ISSUES" accesskey="u"
rel="up">perlport ISSUES</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="System-Interaction"></a>
-<h4 class="subsection">56.3.4 System Interaction</h4>
-
-<p>Not all platforms provide a command line. These are usually platforms
-that rely primarily on a Graphical User Interface (GUI) for user
-interaction. A program requiring a command line interface might
-not work everywhere. This is probably for the user of the program
-to deal with, so don’t stay up late worrying about it.
-</p>
-<p>Some platforms can’t delete or rename files held open by the system,
-this limitation may also apply to changing filesystem metainformation
-like file permissions or owners. Remember to <code>close</code> files when you
-are done with them. Don’t <code>unlink</code> or <code>rename</code> an
open file. Don’t
-<code>tie</code> or <code>open</code> a file already tied or opened;
<code>untie</code> or <code>close</code>
-it first.
-</p>
-<p>Don’t open the same file more than once at a time for writing, as some
-operating systems put mandatory locks on such files.
-</p>
-<p>Don’t assume that write/modify permission on a directory gives the
-right to add or delete files/directories in that directory. That is
-filesystem specific: in some filesystems you need write/modify
-permission also (or even just) in the file/directory itself. In some
-filesystems (AFS, DFS) the permission to add/delete directory entries
-is a completely separate permission.
-</p>
-<p>Don’t assume that a single <code>unlink</code> completely gets rid of
the file:
-some filesystems (most notably the ones in VMS) have versioned
-filesystems, and <code>unlink()</code> removes only the most recent one (it
doesn’t
-remove all the versions because by default the native tools on those
-platforms remove just the most recent version, too). The portable
-idiom to remove all the versions of a file is
-</p>
-<pre class="verbatim"> 1 while unlink "file";
-</pre>
-<p>This will terminate if the file is undeleteable for some reason
-(protected, not there, and so on).
-</p>
-<p>Don’t count on a specific environment variable existing in
<code>%ENV</code>.
-Don’t count on <code>%ENV</code> entries being case-sensitive, or even
-case-preserving. Don’t try to clear <code>%ENV</code> by saying
<code>%ENV = ();</code>, or,
-if you really have to, make it conditional on <code>$^O ne 'VMS'</code> since
in
-VMS the <code>%ENV</code> table is much more than a per-process key-value
string
-table.
-</p>
-<p>On VMS, some entries in the <code>%ENV</code> hash are dynamically created
when
-their key is used on a read if they did not previously exist. The
-values for <code>$ENV{HOME}</code>, <code>$ENV{TERM}</code>,
<code>$ENV{PATH}</code>, and <code>$ENV{USER}</code>,
-are known to be dynamically generated. The specific names that are
-dynamically generated may vary with the version of the C library on VMS,
-and more may exist than are documented.
-</p>
-<p>On VMS by default, changes to the %ENV hash persist after perl exits.
-Subsequent invocations of perl in the same process can inadvertently
-inherit environment settings that were meant to be temporary.
-</p>
-<p>Don’t count on signals or <code>%SIG</code> for anything.
-</p>
-<p>Don’t count on filename globbing. Use <code>opendir</code>,
<code>readdir</code>, and
-<code>closedir</code> instead.
-</p>
-<p>Don’t count on per-program environment variables, or per-program
current
-directories.
-</p>
-<p>Don’t count on specific values of <code>$!</code>, neither numeric nor
-especially the string values. Users may switch their locales causing
-error messages to be translated into their languages. If you can
-trust a POSIXish environment, you can portably use the symbols defined
-by the <code>Errno</code> module, like <code>ENOENT</code>. And don’t
trust on the values of <code>$!</code>
-at all except immediately after a failed system call.
-</p>
-<hr>
-<a name="perlport-Command-names-versus-file-pathnames"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Networking" accesskey="n" rel="next">perlport
Networking</a>, Previous: <a href="#perlport-System-Interaction" accesskey="p"
rel="prev">perlport System Interaction</a>, Up: <a href="#perlport-ISSUES"
accesskey="u" rel="up">perlport ISSUES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Command-names-versus-file-pathnames"></a>
-<h4 class="subsection">56.3.5 Command names versus file pathnames</h4>
-
-<p>Don’t assume that the name used to invoke a command or program with
-<code>system</code> or <code>exec</code> can also be used to test for the
existence of the
-file that holds the executable code for that command or program.
-First, many systems have "internal" commands that are built-in to the
-shell or OS and while these commands can be invoked, there is no
-corresponding file. Second, some operating systems (e.g., Cygwin,
-DJGPP, OS/2, and VOS) have required suffixes for executable files;
-these suffixes are generally permitted on the command name but are not
-required. Thus, a command like <samp>"perl"</samp> might exist in a
file named
-<samp>"perl"</samp>, <samp>"perl.exe"</samp>, or
<samp>"perl.pm"</samp>, depending on the operating system.
-The variable <code>"_exe"</code> in the <code>Config</code> module
holds the executable suffix,
-if any. Third, the VMS port carefully sets up <code>$^X</code> and
-<code>$Config{perlpath}</code> so that no further processing is required.
This is
-just as well, because the matching regular expression used below would
-then have to deal with a possible trailing version number in the VMS
-file name.
-</p>
-<p>To convert <code>$^X</code> to a file pathname, taking account of the
requirements
-of the various operating system possibilities, say:
-</p>
-<pre class="verbatim"> use Config;
- my $thisperl = $^X;
- if ($^O ne 'VMS')
- {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;}
-</pre>
-<p>To convert <code>$Config{perlpath}</code> to a file pathname, say:
-</p>
-<pre class="verbatim"> use Config;
- my $thisperl = $Config{perlpath};
- if ($^O ne 'VMS')
- {$thisperl .= $Config{_exe} unless $thisperl =~ m/$Config{_exe}$/i;}
-</pre>
-<hr>
-<a name="perlport-Networking"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Interprocess-Communication-_0028IPC_0029"
accesskey="n" rel="next">perlport Interprocess Communication (IPC)</a>,
Previous: <a href="#perlport-Command-names-versus-file-pathnames" accesskey="p"
rel="prev">perlport Command names versus file pathnames</a>, Up: <a
href="#perlport-ISSUES" accesskey="u" rel="up">perlport ISSUES</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Networking"></a>
-<h4 class="subsection">56.3.6 Networking</h4>
-
-<p>Don’t assume that you can reach the public Internet.
-</p>
-<p>Don’t assume that there is only one way to get through firewalls
-to the public Internet.
-</p>
-<p>Don’t assume that you can reach outside world through any other port
-than 80, or some web proxy. ftp is blocked by many firewalls.
-</p>
-<p>Don’t assume that you can send email by connecting to the local SMTP
port.
-</p>
-<p>Don’t assume that you can reach yourself or any node by the name
-’localhost’. The same goes for ’127.0.0.1’. You will
have to try both.
-</p>
-<p>Don’t assume that the host has only one network card, or that it
-can’t bind to many virtual IP addresses.
-</p>
-<p>Don’t assume a particular network device name.
-</p>
-<p>Don’t assume a particular set of <code>ioctl()</code>s will work.
-</p>
-<p>Don’t assume that you can ping hosts and get replies.
-</p>
-<p>Don’t assume that any particular port (service) will respond.
-</p>
-<p>Don’t assume that <code>Sys::Hostname</code> (or any other API or
command) returns
-either a fully qualified hostname or a non-qualified hostname: it all
-depends on how the system had been configured. Also remember that for
-things such as DHCP and NAT, the hostname you get back might not be
-very useful.
-</p>
-<p>All the above "don’t":s may look daunting, and they are,
but the key
-is to degrade gracefully if one cannot reach the particular network
-service one wants. Croaking or hanging do not look very professional.
-</p>
-<hr>
-<a name="perlport-Interprocess-Communication-_0028IPC_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-External-Subroutines-_0028XS_0029" accesskey="n"
rel="next">perlport External Subroutines (XS)</a>, Previous: <a
href="#perlport-Networking" accesskey="p" rel="prev">perlport Networking</a>,
Up: <a href="#perlport-ISSUES" accesskey="u" rel="up">perlport ISSUES</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Interprocess-Communication-_0028IPC_0029"></a>
-<h4 class="subsection">56.3.7 Interprocess Communication (IPC)</h4>
-
-<p>In general, don’t directly access the system in code meant to be
-portable. That means, no <code>system</code>, <code>exec</code>,
<code>fork</code>, <code>pipe</code>,
-<code>``</code>, <code>qx//</code>, <code>open</code> with a <code>|</code>,
nor any of the other things
-that makes being a Perl hacker worth being.
-</p>
-<p>Commands that launch external processes are generally supported on
-most platforms (though many of them do not support any type of
-forking). The problem with using them arises from what you invoke
-them on. External tools are often named differently on different
-platforms, may not be available in the same location, might accept
-different arguments, can behave differently, and often present their
-results in a platform-dependent way. Thus, you should seldom depend
-on them to produce consistent results. (Then again, if you’re calling
-<em>netstat -a</em>, you probably don’t expect it to run on both Unix
and CP/M.)
-</p>
-<p>One especially common bit of Perl code is opening a pipe to
<strong>sendmail</strong>:
-</p>
-<pre class="verbatim"> open(MAIL, '|/usr/lib/sendmail -t')
- or die "cannot fork sendmail: $!";
-</pre>
-<p>This is fine for systems programming when sendmail is known to be
-available. But it is not fine for many non-Unix systems, and even
-some Unix systems that may not have sendmail installed. If a portable
-solution is needed, see the various distributions on CPAN that deal
-with it. <code>Mail::Mailer</code> and <code>Mail::Send</code> in the
<code>MailTools</code> distribution are
-commonly used, and provide several mailing methods, including
<code>mail</code>,
-<code>sendmail</code>, and direct SMTP (via <code>Net::SMTP</code>) if a mail
transfer agent is
-not available. <code>Mail::Sendmail</code> is a standalone module that
provides
-simple, platform-independent mailing.
-</p>
-<p>The Unix System V IPC (<code>msg*(), sem*(), shm*()</code>) is not available
-even on all Unix platforms.
-</p>
-<p>Do not use either the bare result of <code>pack("N", 10, 20, 30,
40)</code> or
-bare v-strings (such as <code>v10.20.30.40</code>) to represent IPv4 addresses:
-both forms just pack the four bytes into network order. That this
-would be equal to the C language <code>in_addr</code> struct (which is what the
-socket code internally uses) is not guaranteed. To be portable use
-the routines of the <code>Socket</code> extension, such as
<code>inet_aton()</code>,
-<code>inet_ntoa()</code>, and <code>sockaddr_in()</code>.
-</p>
-<p>The rule of thumb for portable code is: Do it all in portable Perl, or
-use a module (that may internally implement it with platform-specific
-code, but exposes a common interface).
-</p>
-<hr>
-<a name="perlport-External-Subroutines-_0028XS_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Standard-Modules" accesskey="n" rel="next">perlport
Standard Modules</a>, Previous: <a
href="#perlport-Interprocess-Communication-_0028IPC_0029" accesskey="p"
rel="prev">perlport Interprocess Communication (IPC)</a>, Up: <a
href="#perlport-ISSUES" accesskey="u" rel="up">perlport ISSUES</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="External-Subroutines-_0028XS_0029"></a>
-<h4 class="subsection">56.3.8 External Subroutines (XS)</h4>
-
-<p>XS code can usually be made to work with any platform, but dependent
-libraries, header files, etc., might not be readily available or
-portable, or the XS code itself might be platform-specific, just as Perl
-code might be. If the libraries and headers are portable, then it is
-normally reasonable to make sure the XS code is portable, too.
-</p>
-<p>A different type of portability issue arises when writing XS code:
-availability of a C compiler on the end-user’s system. C brings
-with it its own portability issues, and writing XS code will expose
-you to some of those. Writing purely in Perl is an easier way to
-achieve portability.
-</p>
-<hr>
-<a name="perlport-Standard-Modules"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Time-and-Date" accesskey="n" rel="next">perlport Time
and Date</a>, Previous: <a href="#perlport-External-Subroutines-_0028XS_0029"
accesskey="p" rel="prev">perlport External Subroutines (XS)</a>, Up: <a
href="#perlport-ISSUES" accesskey="u" rel="up">perlport ISSUES</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Standard-Modules"></a>
-<h4 class="subsection">56.3.9 Standard Modules</h4>
-
-<p>In general, the standard modules work across platforms. Notable
-exceptions are the <code>CPAN</code> module (which currently makes connections
to external
-programs that may not be available), platform-specific modules (like
-<code>ExtUtils::MM_VMS</code>), and DBM modules.
-</p>
-<p>There is no one DBM module available on all platforms.
-<code>SDBM_File</code> and the others are generally available on all Unix and
DOSish
-ports, but not in MacPerl, where only <code>NDBM_File</code> and
<code>DB_File</code> are
-available.
-</p>
-<p>The good news is that at least some DBM module should be available, and
-<code>AnyDBM_File</code> will use whichever module it can find. Of course,
then
-the code needs to be fairly strict, dropping to the greatest common
-factor (e.g., not exceeding 1K for each record), so that it will
-work with any DBM module. See <a
href="AnyDBM_File.html#Top">(AnyDBM_File)</a> for more details.
-</p>
-<hr>
-<a name="perlport-Time-and-Date"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Character-sets-and-character-encoding" accesskey="n"
rel="next">perlport Character sets and character encoding</a>, Previous: <a
href="#perlport-Standard-Modules" accesskey="p" rel="prev">perlport Standard
Modules</a>, Up: <a href="#perlport-ISSUES" accesskey="u" rel="up">perlport
ISSUES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Time-and-Date"></a>
-<h4 class="subsection">56.3.10 Time and Date</h4>
-
-<p>The system’s notion of time of day and calendar date is controlled in
-widely different ways. Don’t assume the timezone is stored in
<code>$ENV{TZ}</code>,
-and even if it is, don’t assume that you can control the timezone through
-that variable. Don’t assume anything about the three-letter timezone
-abbreviations (for example that MST would be the Mountain Standard Time,
-it’s been known to stand for Moscow Standard Time). If you need to
-use timezones, express them in some unambiguous format like the
-exact number of minutes offset from UTC, or the POSIX timezone
-format.
-</p>
-<p>Don’t assume that the epoch starts at 00:00:00, January 1, 1970,
-because that is OS- and implementation-specific. It is better to
-store a date in an unambiguous representation. The ISO 8601 standard
-defines YYYY-MM-DD as the date format, or YYYY-MM-DDTHH:MM:SS
-(that’s a literal "T" separating the date from the time).
-Please do use the ISO 8601 instead of making us guess what
-date 02/03/04 might be. ISO 8601 even sorts nicely as-is.
-A text representation (like "1987-12-18") can be easily converted
-into an OS-specific value using a module like <code>Date::Parse</code>.
-An array of values, such as those returned by <code>localtime</code>, can be
-converted to an OS-specific representation using <code>Time::Local</code>.
-</p>
-<p>When calculating specific times, such as for tests in time or date modules,
-it may be appropriate to calculate an offset for the epoch.
-</p>
-<pre class="verbatim"> require Time::Local;
- my $offset = Time::Local::timegm(0, 0, 0, 1, 0, 70);
-</pre>
-<p>The value for <code>$offset</code> in Unix will be <code>0</code>, but in
Mac OS Classic
-will be some large number. <code>$offset</code> can then be added to a Unix
time
-value to get what should be the proper value on any system.
-</p>
-<hr>
-<a name="perlport-Character-sets-and-character-encoding"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Internationalisation" accesskey="n"
rel="next">perlport Internationalisation</a>, Previous: <a
href="#perlport-Time-and-Date" accesskey="p" rel="prev">perlport Time and
Date</a>, Up: <a href="#perlport-ISSUES" accesskey="u" rel="up">perlport
ISSUES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Character-sets-and-character-encoding"></a>
-<h4 class="subsection">56.3.11 Character sets and character encoding</h4>
-
-<p>Assume very little about character sets.
-</p>
-<p>Assume nothing about numerical values (<code>ord</code>, <code>chr</code>)
of characters.
-Do not use explicit code point ranges (like <code>\xHH-\xHH)</code>. However,
-starting in Perl v5.22, regular expression pattern bracketed character
-class ranges specified like <code>qr/[\N{U+HH}-\N{U+HH}]/</code> are portable.
-You can portably use symbolic character classes like <code>[:print:]</code>.
-</p>
-<p>Do not assume that the alphabetic characters are encoded contiguously
-(in the numeric sense). There may be gaps. Special coding in Perl,
-however, guarantees that all subsets of <code>qr/[A-Z]/</code>,
<code>qr/[a-z]/</code>, and
-<code>qr/[0-9]/</code> behave as expected. <code>tr///</code> behaves the
same for these
-ranges. In patterns, any ranges specified with end points using the
-<code>\N{...}</code> notations ensures character set portability, but it is a
bug
-in Perl v5.22, that this isn’t true of <code>tr///</code>.
-</p>
-<p>Do not assume anything about the ordering of the characters.
-The lowercase letters may come before or after the uppercase letters;
-the lowercase and uppercase may be interlaced so that both "a" and
"A"
-come before "b"; the accented and other international characters may
-be interlaced so that ä comes before "b".
-<a href="Unicode-Collate.html#Top">(Unicode-Collate)</a> can be used to sort
this all out.
-</p>
-<hr>
-<a name="perlport-Internationalisation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-System-Resources" accesskey="n" rel="next">perlport
System Resources</a>, Previous: <a
href="#perlport-Character-sets-and-character-encoding" accesskey="p"
rel="prev">perlport Character sets and character encoding</a>, Up: <a
href="#perlport-ISSUES" accesskey="u" rel="up">perlport ISSUES</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Internationalisation"></a>
-<h4 class="subsection">56.3.12 Internationalisation</h4>
-
-<p>If you may assume POSIX (a rather large assumption), you may read
-more about the POSIX locale system from <a href="#perllocale-NAME">perllocale
NAME</a>. The locale
-system at least attempts to make things a little bit more portable,
-or at least more convenient and native-friendly for non-English
-users. The system affects character sets and encoding, and date
-and time formatting–amongst other things.
-</p>
-<p>If you really want to be international, you should consider Unicode.
-See <a href="#perluniintro-NAME">perluniintro NAME</a> and <a
href="#perlunicode-NAME">perlunicode NAME</a> for more information.
-</p>
-<p>If you want to use non-ASCII bytes (outside the bytes 0x00..0x7f) in
-the "source code" of your code, to be portable you have to be
explicit
-about what bytes they are. Someone might for example be using your
-code under a UTF-8 locale, in which case random native bytes might be
-illegal ("Malformed UTF-8 ...") This means that for example
embedding
-ISO 8859-1 bytes beyond 0x7f into your strings might cause trouble
-later. If the bytes are native 8-bit bytes, you can use the <code>bytes</code>
-pragma. If the bytes are in a string (regular expressions being
-curious strings), you can often also use the <code>\xHH</code> or more
portably,
-the <code>\N{U+HH}</code> notations instead
-of embedding the bytes as-is. If you want to write your code in UTF-8,
-you can use <a href="utf8.html#Top">(utf8)</a>.
-</p>
-<hr>
-<a name="perlport-System-Resources"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Security" accesskey="n" rel="next">perlport
Security</a>, Previous: <a href="#perlport-Internationalisation" accesskey="p"
rel="prev">perlport Internationalisation</a>, Up: <a href="#perlport-ISSUES"
accesskey="u" rel="up">perlport ISSUES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="System-Resources"></a>
-<h4 class="subsection">56.3.13 System Resources</h4>
-
-<p>If your code is destined for systems with severely constrained (or
-missing!) virtual memory systems then you want to be <em>especially</em>
mindful
-of avoiding wasteful constructs such as:
-</p>
-<pre class="verbatim"> my @lines = <$very_large_file>; #
bad
-
- while (<$fh>) {$file .= $_} # sometimes bad
- my $file = join('', <$fh>); # better
-</pre>
-<p>The last two constructs may appear unintuitive to most people. The
-first repeatedly grows a string, whereas the second allocates a
-large chunk of memory in one go. On some systems, the second is
-more efficient than the first.
-</p>
-<hr>
-<a name="perlport-Security"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Style" accesskey="n" rel="next">perlport Style</a>,
Previous: <a href="#perlport-System-Resources" accesskey="p"
rel="prev">perlport System Resources</a>, Up: <a href="#perlport-ISSUES"
accesskey="u" rel="up">perlport ISSUES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Security"></a>
-<h4 class="subsection">56.3.14 Security</h4>
-
-<p>Most multi-user platforms provide basic levels of security, usually
-implemented at the filesystem level. Some, however, unfortunately do
-not. Thus the notion of user id, or "home" directory,
-or even the state of being logged-in, may be unrecognizable on many
-platforms. If you write programs that are security-conscious, it
-is usually best to know what type of system you will be running
-under so that you can write code explicitly for that platform (or
-class of platforms).
-</p>
-<p>Don’t assume the Unix filesystem access semantics: the operating
-system or the filesystem may be using some ACL systems, which are
-richer languages than the usual <code>rwx</code>. Even if the
<code>rwx</code> exist,
-their semantics might be different.
-</p>
-<p>(From the security viewpoint, testing for permissions before attempting to
-do something is silly anyway: if one tries this, there is potential
-for race conditions. Someone or something might change the
-permissions between the permissions check and the actual operation.
-Just try the operation.)
-</p>
-<p>Don’t assume the Unix user and group semantics: especially,
don’t
-expect <code>$<</code> and <code>$></code> (or <code>$(</code> and
<code>$)</code>) to work
-for switching identities (or memberships).
-</p>
-<p>Don’t assume set-uid and set-gid semantics. (And even if you do,
-think twice: set-uid and set-gid are a known can of security worms.)
-</p>
-<hr>
-<a name="perlport-Style"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlport-Security" accesskey="p" rel="prev">perlport
Security</a>, Up: <a href="#perlport-ISSUES" accesskey="u" rel="up">perlport
ISSUES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Style-1"></a>
-<h4 class="subsection">56.3.15 Style</h4>
-
-<p>For those times when it is necessary to have platform-specific code,
-consider keeping the platform-specific code in one place, making porting
-to other platforms easier. Use the <code>Config</code> module and the special
-variable <code>$^O</code> to differentiate platforms, as described in
-<a href="#perlport-PLATFORMS">PLATFORMS</a>.
-</p>
-<p>Be careful in the tests you supply with your module or programs.
-Module code may be fully portable, but its tests might not be. This
-often happens when tests spawn off other processes or call external
-programs to aid in the testing, or when (as noted above) the tests
-assume certain things about the filesystem and paths. Be careful not
-to depend on a specific output style for errors, such as when checking
-<code>$!</code> after a failed system call. Using <code>$!</code> for
anything else than
-displaying it as output is doubtful (though see the <code>Errno</code> module
for
-testing reasonably portably for error value). Some platforms expect
-a certain output format, and Perl on those platforms may have been
-adjusted accordingly. Most specifically, don’t anchor a regex when
-testing an error value.
-</p>
-<hr>
-<a name="perlport-CPAN-Testers"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-PLATFORMS" accesskey="n" rel="next">perlport
PLATFORMS</a>, Previous: <a href="#perlport-ISSUES" accesskey="p"
rel="prev">perlport ISSUES</a>, Up: <a href="#perlport" accesskey="u"
rel="up">perlport</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="CPAN-Testers"></a>
-<h3 class="section">56.4 CPAN Testers</h3>
-
-<p>Modules uploaded to CPAN are tested by a variety of volunteers on
-different platforms. These CPAN testers are notified by mail of each
-new upload, and reply to the list with PASS, FAIL, NA (not applicable to
-this platform), or UNKNOWN (unknown), along with any relevant notations.
-</p>
-<p>The purpose of the testing is twofold: one, to help developers fix any
-problems in their code that crop up because of lack of testing on other
-platforms; two, to provide users with information about whether
-a given module works on a given platform.
-</p>
-<p>Also see:
-</p>
-<ul>
-<li> Mailing list: address@hidden
-
-</li><li> Testing results: <a
href="http://www.cpantesters.org/";>http://www.cpantesters.org/</a>
-
-</li></ul>
-
-<hr>
-<a name="perlport-PLATFORMS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-FUNCTION-IMPLEMENTATIONS" accesskey="n"
rel="next">perlport FUNCTION IMPLEMENTATIONS</a>, Previous: <a
href="#perlport-CPAN-Testers" accesskey="p" rel="prev">perlport CPAN
Testers</a>, Up: <a href="#perlport" accesskey="u" rel="up">perlport</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="PLATFORMS"></a>
-<h3 class="section">56.5 PLATFORMS</h3>
-
-<p>Perl is built with a <code>$^O</code> variable that indicates the operating
-system it was built on. This was implemented
-to help speed up code that would otherwise have to <code>use Config</code>
-and use the value of <code>$Config{osname}</code>. Of course, to get more
-detailed information about the system, looking into <code>%Config</code> is
-certainly recommended.
-</p>
-<p><code>%Config</code> cannot always be trusted, however, because it was built
-at compile time. If perl was built in one place, then transferred
-elsewhere, some values may be wrong. The values may even have been
-edited after the fact.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlport-Unix"
accesskey="1">perlport Unix</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-DOS-and-Derivatives" accesskey="2">perlport DOS and
Derivatives</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-VMS"
accesskey="3">perlport VMS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-VOS"
accesskey="4">perlport VOS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-EBCDIC-Platforms"
accesskey="5">perlport EBCDIC Platforms</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-Acorn-RISC-OS"
accesskey="6">perlport Acorn RISC OS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlport-Other-perls"
accesskey="7">perlport Other perls</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlport-Unix"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-DOS-and-Derivatives" accesskey="n"
rel="next">perlport DOS and Derivatives</a>, Up: <a href="#perlport-PLATFORMS"
accesskey="u" rel="up">perlport PLATFORMS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Unix"></a>
-<h4 class="subsection">56.5.1 Unix</h4>
-
-<p>Perl works on a bewildering variety of Unix and Unix-like platforms (see
-e.g. most of the files in the <samp>hints/</samp> directory in the source code
kit).
-On most of these systems, the value of <code>$^O</code> (hence
<code>$Config{'osname'}</code>,
-too) is determined either by lowercasing and stripping punctuation from the
-first field of the string returned by typing <code>uname -a</code> (or a
similar command)
-at the shell prompt or by testing the file system for the presence of
-uniquely named files such as a kernel or header file. Here, for example,
-are a few of the more popular Unix flavors:
-</p>
-<pre class="verbatim"> uname $^O $Config{'archname'}
- --------------------------------------------
- AIX aix aix
- BSD/OS bsdos i386-bsdos
- Darwin darwin darwin
- DYNIX/ptx dynixptx i386-dynixptx
- FreeBSD freebsd freebsd-i386
- Haiku haiku BePC-haiku
- Linux linux arm-linux
- Linux linux armv5tel-linux
- Linux linux i386-linux
- Linux linux i586-linux
- Linux linux ppc-linux
- HP-UX hpux PA-RISC1.1
- IRIX irix irix
- Mac OS X darwin darwin
- NeXT 3 next next-fat
- NeXT 4 next OPENSTEP-Mach
- openbsd openbsd i386-openbsd
- OSF1 dec_osf alpha-dec_osf
- reliantunix-n svr4 RM400-svr4
- SCO_SV sco_sv i386-sco_sv
- SINIX-N svr4 RM400-svr4
- sn4609 unicos CRAY_C90-unicos
- sn6521 unicosmk t3e-unicosmk
- sn9617 unicos CRAY_J90-unicos
- SunOS solaris sun4-solaris
- SunOS solaris i86pc-solaris
- SunOS4 sunos sun4-sunos
-</pre>
-<p>Because the value of <code>$Config{archname}</code> may depend on the
-hardware architecture, it can vary more than the value of <code>$^O</code>.
-</p>
-<hr>
-<a name="perlport-DOS-and-Derivatives"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-VMS" accesskey="n" rel="next">perlport VMS</a>,
Previous: <a href="#perlport-Unix" accesskey="p" rel="prev">perlport Unix</a>,
Up: <a href="#perlport-PLATFORMS" accesskey="u" rel="up">perlport PLATFORMS</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DOS-and-Derivatives"></a>
-<h4 class="subsection">56.5.2 DOS and Derivatives</h4>
-
-<p>Perl has long been ported to Intel-style microcomputers running under
-systems like PC-DOS, MS-DOS, OS/2, and most Windows platforms you can
-bring yourself to mention (except for Windows CE, if you count that).
-Users familiar with <em>COMMAND.COM</em> or <em>CMD.EXE</em> style shells
should
-be aware that each of these file specifications may have subtle
-differences:
-</p>
-<pre class="verbatim"> my $filespec0 = "c:/foo/bar/file.txt";
- my $filespec1 = "c:\\foo\\bar\\file.txt";
- my $filespec2 = 'c:\foo\bar\file.txt';
- my $filespec3 = 'c:\\foo\\bar\\file.txt';
-</pre>
-<p>System calls accept either <code>/</code> or <code>\</code> as the path
separator.
-However, many command-line utilities of DOS vintage treat <code>/</code> as
-the option prefix, so may get confused by filenames containing <code>/</code>.
-Aside from calling any external programs, <code>/</code> will work just fine,
-and probably better, as it is more consistent with popular usage,
-and avoids the problem of remembering what to backwhack and what
-not to.
-</p>
-<p>The DOS FAT filesystem can accommodate only "8.3" style
filenames. Under
-the "case-insensitive, but case-preserving" HPFS (OS/2) and NTFS (NT)
-filesystems you may have to be careful about case returned with functions
-like <code>readdir</code> or used with functions like <code>open</code> or
<code>opendir</code>.
-</p>
-<p>DOS also treats several filenames as special, such as AUX, PRN,
-NUL, CON, COM1, LPT1, LPT2, etc. Unfortunately, sometimes these
-filenames won’t even work if you include an explicit directory
-prefix. It is best to avoid such filenames, if you want your code
-to be portable to DOS and its derivatives. It’s hard to know what
-these all are, unfortunately.
-</p>
-<p>Users of these operating systems may also wish to make use of
-scripts such as <em>pl2bat.bat</em> or <em>pl2cmd</em> to
-put wrappers around your scripts.
-</p>
-<p>Newline (<code>\n</code>) is translated as <code>\015\012</code> by STDIO
when reading from
-and writing to files (see <a href="#perlport-Newlines">Newlines</a>).
<code>binmode(FILEHANDLE)</code>
-will keep <code>\n</code> translated as <code>\012</code> for that filehandle.
Since it is a
-no-op on other systems, <code>binmode</code> should be used for cross-platform
code
-that deals with binary data. That’s assuming you realize in advance
-that your data is in binary. General-purpose programs should
-often assume nothing about their data.
-</p>
-<p>The <code>$^O</code> variable and the <code>$Config{archname}</code> values
for various
-DOSish perls are as follows:
-</p>
-<pre class="verbatim"> OS $^O $Config{archname} ID
Version
- --------------------------------------------------------
- MS-DOS dos ?
- PC-DOS dos ?
- OS/2 os2 ?
- Windows 3.1 ? ? 0 3 01
- Windows 95 MSWin32 MSWin32-x86 1 4 00
- Windows 98 MSWin32 MSWin32-x86 1 4 10
- Windows ME MSWin32 MSWin32-x86 1 ?
- Windows NT MSWin32 MSWin32-x86 2 4 xx
- Windows NT MSWin32 MSWin32-ALPHA 2 4 xx
- Windows NT MSWin32 MSWin32-ppc 2 4 xx
- Windows 2000 MSWin32 MSWin32-x86 2 5 00
- Windows XP MSWin32 MSWin32-x86 2 5 01
- Windows 2003 MSWin32 MSWin32-x86 2 5 02
- Windows Vista MSWin32 MSWin32-x86 2 6 00
- Windows 7 MSWin32 MSWin32-x86 2 6 01
- Windows 7 MSWin32 MSWin32-x64 2 6 01
- Windows 2008 MSWin32 MSWin32-x86 2 6 01
- Windows 2008 MSWin32 MSWin32-x64 2 6 01
- Windows CE MSWin32 ? 3
- Cygwin cygwin cygwin
-</pre>
-<p>The various MSWin32 Perl’s can distinguish the OS they are running on
-via the value of the fifth element of the list returned from
-<code>Win32::GetOSVersion()</code>. For example:
-</p>
-<pre class="verbatim"> if ($^O eq 'MSWin32') {
- my @os_version_info = Win32::GetOSVersion();
- print +('3.1','95','NT')[$os_version_info[4]],"\n";
- }
-</pre>
-<p>There are also <code>Win32::IsWinNT()</code> and
<code>Win32::IsWin95()</code>; try <code>perldoc Win32</code>,
-and as of libwin32 0.19 (not part of the core Perl distribution)
-<code>Win32::GetOSName()</code>. The very portable
<code>POSIX::uname()</code> will work too:
-</p>
-<pre class="verbatim"> c:\> perl -MPOSIX -we "print join '|',
uname"
- Windows NT|moonru|5.0|Build 2195 (Service Pack 2)|x86
-</pre>
-<p>Also see:
-</p>
-<ul>
-<li> The djgpp environment for DOS, <a
href="http://www.delorie.com/djgpp/";>http://www.delorie.com/djgpp/</a>
-and <a href="perldos.html#Top">(perldos)</a>.
-
-</li><li> The EMX environment for DOS, OS/2, etc. address@hidden,
-<a
href="ftp://hobbes.nmsu.edu/pub/os2/dev/emx/";>ftp://hobbes.nmsu.edu/pub/os2/dev/emx/</a>
Also <a href="perlos2.html#Top">(perlos2)</a>.
-
-</li><li> Build instructions for Win32 in <a
href="perlwin32.html#Top">(perlwin32)</a>, or under the Cygnus environment
-in <a href="perlcygwin.html#Top">(perlcygwin)</a>.
-
-</li><li> The <code>Win32::*</code> modules in <a
href="Win32.html#Top">(Win32)</a>.
-
-</li><li> The ActiveState Pages, <a
href="http://www.activestate.com/";>http://www.activestate.com/</a>
-
-</li><li> The Cygwin environment for Win32; <samp>README.cygwin</samp>
(installed
-as <a href="perlcygwin.html#Top">(perlcygwin)</a>), <a
href="http://www.cygwin.com/";>http://www.cygwin.com/</a>
-
-</li><li> The U/WIN environment for Win32,
-<a
href="http://www.research.att.com/sw/tools/uwin/";>http://www.research.att.com/sw/tools/uwin/</a>
-
-</li><li> Build instructions for OS/2, <a href="perlos2.html#Top">(perlos2)</a>
-
-</li></ul>
-
-<hr>
-<a name="perlport-VMS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-VOS" accesskey="n" rel="next">perlport VOS</a>,
Previous: <a href="#perlport-DOS-and-Derivatives" accesskey="p"
rel="prev">perlport DOS and Derivatives</a>, Up: <a href="#perlport-PLATFORMS"
accesskey="u" rel="up">perlport PLATFORMS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="VMS"></a>
-<h4 class="subsection">56.5.3 VMS</h4>
-
-<p>Perl on VMS is discussed in <a href="#perlvms-NAME">perlvms NAME</a> in the
Perl distribution.
-</p>
-<p>The official name of VMS as of this writing is OpenVMS.
-</p>
-<p>Interacting with Perl from the Digital Command Language (DCL) shell
-often requires a different set of quotation marks than Unix shells do.
-For example:
-</p>
-<pre class="verbatim"> $ perl -e "print ""Hello,
world.\n"""
- Hello, world.
-</pre>
-<p>There are several ways to wrap your Perl scripts in DCL <samp>.COM</samp>
files, if
-you are so inclined. For example:
-</p>
-<pre class="verbatim"> $ write sys$output "Hello from DCL!"
- $ if p1 .eqs. ""
- $ then perl -x 'f$environment("PROCEDURE")
- $ else perl -x - 'p1 'p2 'p3 'p4 'p5 'p6 'p7 'p8
- $ deck/dollars="__END__"
- #!/usr/bin/perl
-
- print "Hello from Perl!\n";
-
- __END__
- $ endif
-</pre>
-<p>Do take care with <code>$ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT</code>
if your
-Perl-in-DCL script expects to do things like <code>$read =
<STDIN>;</code>.
-</p>
-<p>The VMS operating system has two filesystems, designated by their
-on-disk structure (ODS) level: ODS-2 and its successor ODS-5. The
-initial port of Perl to VMS pre-dates ODS-5, but all current testing and
-development assumes ODS-5 and its capabilities, including case
-preservation, extended characters in filespecs, and names up to 8192
-bytes long.
-</p>
-<p>Perl on VMS can accept either VMS- or Unix-style file
-specifications as in either of the following:
-</p>
-<pre class="verbatim"> $ perl -ne "print if /perl_setup/i"
SYS$LOGIN:LOGIN.COM
- $ perl -ne "print if /perl_setup/i" /sys$login/login.com
-</pre>
-<p>but not a mixture of both as in:
-</p>
-<pre class="verbatim"> $ perl -ne "print if /perl_setup/i"
sys$login:/login.com
- Can't open sys$login:/login.com: file specification syntax error
-</pre>
-<p>In general, the easiest path to portability is always to specify
-filenames in Unix format unless they will need to be processed by native
-commands or utilities. Because of this latter consideration, the
-File::Spec module by default returns native format specifications
-regardless of input format. This default may be reversed so that
-filenames are always reported in Unix format by specifying the
-<code>DECC$FILENAME_UNIX_REPORT</code> feature logical in the environment.
-</p>
-<p>The file type, or extension, is always present in a VMS-format file
-specification even if it’s zero-length. This means that, by default,
-<code>readdir</code> will return a trailing dot on a file with no extension, so
-where you would see <code>"a"</code> on Unix you’ll see
<code>"a."</code> on VMS. However,
-the trailing dot may be suppressed by enabling the
-<code>DECC$READDIR_DROPDOTNOTYPE</code> feature in the environment (see the
CRTL
-documentation on feature logical names).
-</p>
-<p>What <code>\n</code> represents depends on the type of file opened. It
usually
-represents <code>\012</code> but it could also be <code>\015</code>,
<code>\012</code>, <code>\015\012</code>,
-<code>\000</code>, <code>\040</code>, or nothing depending on the file
organization and
-record format. The <code>VMS::Stdio</code> module provides access to the
-special <code>fopen()</code> requirements of files with unusual attributes on
VMS.
-</p>
-<p>The value of <code>$^O</code> on OpenVMS is "VMS". To determine
the architecture
-that you are running on refer to <code>$Config{'archname'}</code>.
-</p>
-<p>On VMS, perl determines the UTC offset from the
<code>SYS$TIMEZONE_DIFFERENTIAL</code>
-logical name. Although the VMS epoch began at 17-NOV-1858 00:00:00.00,
-calls to <code>localtime</code> are adjusted to count offsets from
-01-JAN-1970 00:00:00.00, just like Unix.
-</p>
-<p>Also see:
-</p>
-<ul>
-<li> <samp>README.vms</samp> (installed as <samp>README_vms</samp>), <a
href="#perlvms-NAME">perlvms NAME</a>
-
-</li><li> vmsperl list, address@hidden
-
-</li><li> vmsperl on the web, <a
href="http://www.sidhe.org/vmsperl/index.html";>http://www.sidhe.org/vmsperl/index.html</a>
-
-</li><li> VMS Software Inc. web site, <a
href="http://www.vmssoftware.com";>http://www.vmssoftware.com</a>
-
-</li></ul>
-
-<hr>
-<a name="perlport-VOS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-EBCDIC-Platforms" accesskey="n" rel="next">perlport
EBCDIC Platforms</a>, Previous: <a href="#perlport-VMS" accesskey="p"
rel="prev">perlport VMS</a>, Up: <a href="#perlport-PLATFORMS" accesskey="u"
rel="up">perlport PLATFORMS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="VOS"></a>
-<h4 class="subsection">56.5.4 VOS</h4>
-
-<p>Perl on VOS (also known as OpenVOS) is discussed in <samp>README.vos</samp>
-in the Perl distribution (installed as <a
href="perlvos.html#Top">(perlvos)</a>). Perl on VOS
-can accept either VOS- or Unix-style file specifications as in
-either of the following:
-</p>
-<pre class="verbatim"> $ perl -ne "print if /perl_setup/i"
>system>notices
- $ perl -ne "print if /perl_setup/i" /system/notices
-</pre>
-<p>or even a mixture of both as in:
-</p>
-<pre class="verbatim"> $ perl -ne "print if /perl_setup/i"
>system/notices
-</pre>
-<p>Even though VOS allows the slash character to appear in object
-names, because the VOS port of Perl interprets it as a pathname
-delimiting character, VOS files, directories, or links whose
-names contain a slash character cannot be processed. Such files
-must be renamed before they can be processed by Perl.
-</p>
-<p>Older releases of VOS (prior to OpenVOS Release 17.0) limit file
-names to 32 or fewer characters, prohibit file names from
-starting with a <code>-</code> character, and prohibit file names from
-containing any character matching <code>tr/ !#%&'()*;<=>?//</code>.
-</p>
-<p>Newer releases of VOS (OpenVOS Release 17.0 or later) support a
-feature known as extended names. On these releases, file names
-can contain up to 255 characters, are prohibited from starting
-with a <code>-</code> character, and the set of prohibited characters is
-reduced to any character matching <code>tr/#%*<>?//</code>. There are
-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
-character combinations are prohibited: space-space,
-space-hyphen, period-space, space-period, period-apostrophe,
-apostrophe-period, leading or trailing space, and leading or
-trailing apostrophe. Although an extended file name is limited
-to 255 characters, a path name is still limited to 256
-characters.
-</p>
-<p>The value of <code>$^O</code> on VOS is "vos". To determine the
-architecture that you are running on without resorting to loading
-all of <code>%Config</code> you can examine the content of the
<code>@INC</code> array
-like so:
-</p>
-<pre class="verbatim"> if ($^O =~ /vos/) {
- print "I'm on a Stratus box!\n";
- } else {
- print "I'm not on a Stratus box!\n";
- die;
- }
-</pre>
-<p>Also see:
-</p>
-<ul>
-<li> <samp>README.vos</samp> (installed as <a
href="perlvos.html#Top">(perlvos)</a>)
-
-</li><li> The VOS mailing list.
-
-<p>There is no specific mailing list for Perl on VOS. You can contact
-the Stratus Technologies Customer Assistance Center (CAC) for your
-region, or you can use the contact information located in the
-distribution files on the Stratus Anonymous FTP site.
-</p>
-</li><li> Stratus Technologies on the web at <a
href="http://www.stratus.com";>http://www.stratus.com</a>
-
-</li><li> VOS Open-Source Software on the web at <a
href="http://ftp.stratus.com/pub/vos/vos.html";>http://ftp.stratus.com/pub/vos/vos.html</a>
-
-</li></ul>
-
-<hr>
-<a name="perlport-EBCDIC-Platforms"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Acorn-RISC-OS" accesskey="n" rel="next">perlport
Acorn RISC OS</a>, Previous: <a href="#perlport-VOS" accesskey="p"
rel="prev">perlport VOS</a>, Up: <a href="#perlport-PLATFORMS" accesskey="u"
rel="up">perlport PLATFORMS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="EBCDIC-Platforms"></a>
-<h4 class="subsection">56.5.5 EBCDIC Platforms</h4>
-
-<p>v5.22 core Perl runs on z/OS (formerly OS/390). Theoretically it could
-run on the successors of OS/400 on AS/400 minicomputers as well as
-VM/ESA, and BS2000 for S/390 Mainframes. Such computers use EBCDIC
-character sets internally (usually
-Character Code Set ID 0037 for OS/400 and either 1047 or POSIX-BC for S/390
-systems).
-</p>
-<p>The rest of this section may need updating, but we don’t know what it
-should say. Please email comments to
-<a href="mailto:address@hidden";>address@hidden</a>.
-</p>
-<p>On the mainframe Perl currently works under the "Unix system
-services for OS/390" (formerly known as OpenEdition), VM/ESA OpenEdition,
or
-the BS200 POSIX-BC system (BS2000 is supported in Perl 5.6 and greater).
-See <a href="perlos390.html#Top">(perlos390)</a> for details. Note that for
OS/400 there is also a port of
-Perl 5.8.1/5.10.0 or later to the PASE which is ASCII-based (as opposed to
-ILE which is EBCDIC-based), see <a href="perlos400.html#Top">(perlos400)</a>.
-</p>
-<p>As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix
-sub-systems do not support the <code>#!</code> shebang trick for script
invocation.
-Hence, on OS/390 and VM/ESA Perl scripts can be executed with a header
-similar to the following simple script:
-</p>
-<pre class="verbatim"> : # use perl
- eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
- if 0;
- #!/usr/local/bin/perl # just a comment really
-
- print "Hello from perl!\n";
-</pre>
-<p>OS/390 will support the <code>#!</code> shebang trick in release 2.8 and
beyond.
-Calls to <code>system</code> and backticks can use POSIX shell syntax on all
-S/390 systems.
-</p>
-<p>On the AS/400, if PERL5 is in your library list, you may need
-to wrap your Perl scripts in a CL procedure to invoke them like so:
-</p>
-<pre class="verbatim"> BEGIN
- CALL PGM(PERL5/PERL) PARM('/QOpenSys/hello.pl')
- ENDPGM
-</pre>
-<p>This will invoke the Perl script <samp>hello.pl</samp> in the root of the
-QOpenSys file system. On the AS/400 calls to <code>system</code> or backticks
-must use CL syntax.
-</p>
-<p>On these platforms, bear in mind that the EBCDIC character set may have
-an effect on what happens with some Perl functions (such as <code>chr</code>,
-<code>pack</code>, <code>print</code>, <code>printf</code>, <code>ord</code>,
<code>sort</code>, <code>sprintf</code>, <code>unpack</code>), as
-well as bit-fiddling with ASCII constants using operators like <code>^</code>,
<code>&</code>
-and <code>|</code>, not to mention dealing with socket interfaces to ASCII
computers
-(see <a href="#perlport-Newlines">Newlines</a>).
-</p>
-<p>Fortunately, most web servers for the mainframe will correctly
-translate the <code>\n</code> in the following statement to its ASCII
equivalent
-(<code>\r</code> is the same under both Unix and z/OS):
-</p>
-<pre class="verbatim"> print "Content-type: text/html\r\n\r\n";
-</pre>
-<p>The values of <code>$^O</code> on some of these platforms includes:
-</p>
-<pre class="verbatim"> uname $^O $Config{'archname'}
- --------------------------------------------
- OS/390 os390 os390
- OS400 os400 os400
- POSIX-BC posix-bc BS2000-posix-bc
-</pre>
-<p>Some simple tricks for determining if you are running on an EBCDIC
-platform could include any of the following (perhaps all):
-</p>
-<pre class="verbatim"> if ("\t" eq "\005") { print
"EBCDIC may be spoken here!\n"; }
-
- if (ord('A') == 193) { print "EBCDIC may be spoken here!\n"; }
-
- if (chr(169) eq 'z') { print "EBCDIC may be spoken here!\n"; }
-</pre>
-<p>One thing you may not want to rely on is the EBCDIC encoding
-of punctuation characters since these may differ from code page to code
-page (and once your module or script is rumoured to work with EBCDIC,
-folks will want it to work with all EBCDIC character sets).
-</p>
-<p>Also see:
-</p>
-<ul>
-<li> <a href="perlos390.html#Top">(perlos390)</a>, <a
href="perlos400.html#Top">(perlos400)</a>, <a
href="perlbs2000.html#Top">(perlbs2000)</a>, <a
href="#perlebcdic-NAME">perlebcdic NAME</a>.
-
-</li><li> The address@hidden list is for discussion of porting issues as well
as
-general usage issues for all EBCDIC Perls. Send a message body of
-"subscribe perl-mvs" to address@hidden
-
-</li><li> AS/400 Perl information at
-<a href="http://as400.rochester.ibm.com/";>http://as400.rochester.ibm.com/</a>
-as well as on CPAN in the <samp>ports/</samp> directory.
-
-</li></ul>
-
-<hr>
-<a name="perlport-Acorn-RISC-OS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Other-perls" accesskey="n" rel="next">perlport Other
perls</a>, Previous: <a href="#perlport-EBCDIC-Platforms" accesskey="p"
rel="prev">perlport EBCDIC Platforms</a>, Up: <a href="#perlport-PLATFORMS"
accesskey="u" rel="up">perlport PLATFORMS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Acorn-RISC-OS"></a>
-<h4 class="subsection">56.5.6 Acorn RISC OS</h4>
-
-<p>Because Acorns use ASCII with newlines (<code>\n</code>) in text files as
<code>\012</code> like
-Unix, and because Unix filename emulation is turned on by default,
-most simple scripts will probably work "out of the box". The native
-filesystem is modular, and individual filesystems are free to be
-case-sensitive or insensitive, and are usually case-preserving. Some
-native filesystems have name length limits, which file and directory
-names are silently truncated to fit. Scripts should be aware that the
-standard filesystem currently has a name length limit of <strong>10</strong>
-characters, with up to 77 items in a directory, but other filesystems
-may not impose such limitations.
-</p>
-<p>Native filenames are of the form
-</p>
-<pre class="verbatim">
Filesystem#Special_Field::DiskName.$.Directory.Directory.File
-</pre>
-<p>where
-</p>
-<pre class="verbatim"> Special_Field is not usually present, but may
contain . and $ .
- Filesystem =~ m|[A-Za-z0-9_]|
- DsicName =~ m|[A-Za-z0-9_/]|
- $ represents the root directory
- . is the path separator
- @ is the current directory (per filesystem but machine global)
- ^ is the parent directory
- Directory and File =~ m|[^\0- "\.\$\%\&:address@hidden|\177]+|
-</pre>
-<p>The default filename translation is roughly <code>tr|/.|./|;</code>
-</p>
-<p>Note that <code>"ADFS::HardDisk.$.File" ne
'ADFS::HardDisk.$.File'</code> and that
-the second stage of <code>$</code> interpolation in regular expressions will
fall
-foul of the <code>$.</code> if scripts are not careful.
-</p>
-<p>Logical paths specified by system variables containing comma-separated
-search lists are also allowed; hence <code>System:Modules</code> is a valid
-filename, and the filesystem will prefix <code>Modules</code> with each
section of
-<code>System$Path</code> until a name is made that points to an object on disk.
-Writing to a new file <code>System:Modules</code> would be allowed only if
-<code>System$Path</code> contains a single item list. The filesystem will also
-expand system variables in filenames if enclosed in angle brackets, so
-<code><System$Dir>.Modules</code> would look for the file
-<code>$ENV{'System$Dir'} . 'Modules'</code><!-- /@w -->. The
obvious implication of this is
-that <strong>fully qualified filenames can start with
<code><></code></strong> and should
-be protected when <code>open</code> is used for input.
-</p>
-<p>Because <code>.</code> was in use as a directory separator and filenames
could not
-be assumed to be unique after 10 characters, Acorn implemented the C
-compiler to strip the trailing <code>.c</code> <code>.h</code> <code>.s</code>
and <code>.o</code> suffix from
-filenames specified in source code and store the respective files in
-subdirectories named after the suffix. Hence files are translated:
-</p>
-<pre class="verbatim"> foo.h h.foo
- C:foo.h C:h.foo (logical path variable)
- sys/os.h sys.h.os (C compiler groks Unix-speak)
- 10charname.c c.10charname
- 10charname.o o.10charname
- 11charname_.c c.11charname (assuming filesystem truncates at 10)
-</pre>
-<p>The Unix emulation library’s translation of filenames to native
assumes
-that this sort of translation is required, and it allows a user-defined list
-of known suffixes that it will transpose in this fashion. This may
-seem transparent, but consider that with these rules <samp>foo/bar/baz.h</samp>
-and <samp>foo/bar/h/baz</samp> both map to <samp>foo.bar.h.baz</samp>, and
that <code>readdir</code> and
-<code>glob</code> cannot and do not attempt to emulate the reverse mapping.
Other
-<code>.</code>’s in filenames are translated to <code>/</code>.
-</p>
-<p>As implied above, the environment accessed through <code>%ENV</code> is
global, and
-the convention is that program specific environment variables are of the
-form <code>Program$Name</code>. Each filesystem maintains a current directory,
-and the current filesystem’s current directory is the
<strong>global</strong> current
-directory. Consequently, sociable programs don’t change the current
-directory but rely on full pathnames, and programs (and Makefiles) cannot
-assume that they can spawn a child process which can change the current
-directory without affecting its parent (and everyone else for that
-matter).
-</p>
-<p>Because native operating system filehandles are global and are currently
-allocated down from 255, with 0 being a reserved value, the Unix emulation
-library emulates Unix filehandles. Consequently, you can’t rely on
-passing <code>STDIN</code>, <code>STDOUT</code>, or <code>STDERR</code> to
your children.
-</p>
-<p>The desire of users to express filenames of the form
-<code><Foo$Dir>.Bar</code> on the command line unquoted causes problems,
-too: <code>``</code> command output capture has to perform a guessing game. It
-assumes that a string <code><[^<>]+\$[^<>]></code> is a
-reference to an environment variable, whereas anything else involving
-<code><</code> or <code>></code> is redirection, and generally manages
to be 99%
-right. Of course, the problem remains that scripts cannot rely on any
-Unix tools being available, or that any tools found have Unix-like command
-line arguments.
-</p>
-<p>Extensions and XS are, in theory, buildable by anyone using free
-tools. In practice, many don’t, as users of the Acorn platform are
-used to binary distributions. MakeMaker does run, but no available
-make currently copes with MakeMaker’s makefiles; even if and when
-this should be fixed, the lack of a Unix-like shell will cause
-problems with makefile rules, especially lines of the form <code>cd
-sdbm && make all</code>, and anything using quoting.
-</p>
-<p>"RISC OS<!-- /@w -->" is the proper name for the operating
system, but the value
-in <code>$^O</code> is "riscos" (because we don’t like
shouting).
-</p>
-<hr>
-<a name="perlport-Other-perls"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlport-Acorn-RISC-OS" accesskey="p" rel="prev">perlport
Acorn RISC OS</a>, Up: <a href="#perlport-PLATFORMS" accesskey="u"
rel="up">perlport PLATFORMS</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Other-perls"></a>
-<h4 class="subsection">56.5.7 Other perls</h4>
-
-<p>Perl has been ported to many platforms that do not fit into any of
-the categories listed above. Some, such as AmigaOS,
-QNX, Plan 9, and VOS, have been well-integrated into the standard
-Perl source code kit. You may need to see the <samp>ports/</samp> directory
-on CPAN for information, and possibly binaries, for the likes of:
-aos, Atari ST, lynxos, riscos, Novell Netware, Tandem Guardian,
-<em>etc.</em> (Yes, we know that some of these OSes may fall under the
-Unix category, but we are not a standards body.)
-</p>
-<p>Some approximate operating system names and their <code>$^O</code> values
-in the "OTHER" category include:
-</p>
-<pre class="verbatim"> OS $^O $Config{'archname'}
- ------------------------------------------
- Amiga DOS amigaos m68k-amigos
-</pre>
-<p>See also:
-</p>
-<ul>
-<li> Amiga, <samp>README.amiga</samp> (installed as <a
href="perlamiga.html#Top">(perlamiga)</a>).
-
-</li><li> A free perl5-based PERL.NLM for Novell Netware is available in
-precompiled binary and source code form from <a
href="http://www.novell.com/";>http://www.novell.com/</a>
-as well as from CPAN.
-
-</li><li> Plan 9<!-- /@w -->, <samp>README.plan9</samp>
-
-</li></ul>
-
-<hr>
-<a name="perlport-FUNCTION-IMPLEMENTATIONS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Supported-Platforms" accesskey="n"
rel="next">perlport Supported Platforms</a>, Previous: <a
href="#perlport-PLATFORMS" accesskey="p" rel="prev">perlport PLATFORMS</a>, Up:
<a href="#perlport" accesskey="u" rel="up">perlport</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="FUNCTION-IMPLEMENTATIONS"></a>
-<h3 class="section">56.6 FUNCTION IMPLEMENTATIONS</h3>
-
-<p>Listed below are functions that are either completely unimplemented
-or else have been implemented differently on various platforms.
-Following each description will be, in parentheses, a list of
-platforms that the description applies to.
-</p>
-<p>The list may well be incomplete, or even wrong in some places. When
-in doubt, consult the platform-specific README files in the Perl
-source distribution, and any other documentation resources accompanying
-a given port.
-</p>
-<p>Be aware, moreover, that even among Unix-ish systems there are variations.
-</p>
-<p>For many functions, you can also query <code>%Config</code>, exported by
-default from the <code>Config</code> module. For example, to check whether the
-platform has the <code>lstat</code> call, check <code>$Config{d_lstat}</code>.
See
-<a href="Config.html#Top">(Config)</a> for a full description of available
variables.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlport-Alphabetical-Listing-of-Perl-Functions" accesskey="1">perlport
Alphabetical Listing of Perl Functions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlport-Alphabetical-Listing-of-Perl-Functions"></a>
-<div class="header">
-<p>
-Up: <a href="#perlport-FUNCTION-IMPLEMENTATIONS" accesskey="u"
rel="up">perlport FUNCTION IMPLEMENTATIONS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Alphabetical-Listing-of-Perl-Functions-1"></a>
-<h4 class="subsection">56.6.1 Alphabetical Listing of Perl Functions</h4>
-
-<dl compact="compact">
-<dt>-X</dt>
-<dd><a name="perlport-_002dX"></a>
-<p><code>-w</code> only inspects the read-only file attribute
(FILE_ATTRIBUTE_READONLY),
-which determines whether the directory can be deleted, not whether it can
-be written to. Directories always have read and write access unless denied
-by discretionary access control lists (DACLs). (Win32<!-- /@w -->)
-</p>
-<p><code>-r</code>, <code>-w</code>, <code>-x</code>, and <code>-o</code> tell
whether the file is accessible,
-which may not reflect UIC-based file protections. (VMS)
-</p>
-<p><code>-s</code> by name on an open file will return the space reserved on
disk,
-rather than the current extent. <code>-s</code> on an open filehandle returns
the
-current size. (RISC OS<!-- /@w -->)
-</p>
-<p><code>-R</code>, <code>-W</code>, <code>-X</code>, <code>-O</code> are
indistinguishable from <code>-r</code>, <code>-w</code>,
-<code>-x</code>, <code>-o</code>. (Win32, VMS, RISC OS<!-- /@w -->)
-</p>
-<p><code>-g</code>, <code>-k</code>, <code>-l</code>, <code>-u</code>,
<code>-A</code> are not particularly meaningful.
-(Win32, VMS, RISC OS<!-- /@w -->)
-</p>
-<p><code>-p</code> is not particularly meaningful. (VMS, RISC OS<!-- /@w
-->)
-</p>
-<p><code>-d</code> is true if passed a device spec without an explicit
directory.
-(VMS)
-</p>
-<p><code>-x</code> (or <code>-X</code>) determine if a file ends in one of the
executable
-suffixes. <code>-S</code> is meaningless. (Win32)
-</p>
-<p><code>-x</code> (or <code>-X</code>) determine if a file has an executable
file type.
-(RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>alarm</dt>
-<dd><a name="perlport-alarm"></a>
-<p>Emulated using timers that must be explicitly polled whenever Perl
-wants to dispatch "safe signals" and therefore cannot interrupt
-blocking system calls. (Win32)
-</p>
-</dd>
-<dt>atan2</dt>
-<dd><a name="perlport-atan2"></a>
-<p>Due to issues with various CPUs, math libraries, compilers, and standards,
-results for <code>atan2()</code> may vary depending on any combination of the
above.
-Perl attempts to conform to the Open Group/IEEE standards for the results
-returned from <code>atan2()</code>, but cannot force the issue if the system
Perl is
-run on does not allow it. (Tru64, HP-UX 10.20)
-</p>
-<p>The current version of the standards for <code>atan2()</code> is available
at
-<a
href="http://www.opengroup.org/onlinepubs/009695399/functions/atan2.html";>http://www.opengroup.org/onlinepubs/009695399/functions/atan2.html</a>.
-</p>
-</dd>
-<dt>binmode</dt>
-<dd><a name="perlport-binmode"></a>
-<p>Meaningless. (RISC OS<!-- /@w -->)
-</p>
-<p>Reopens file and restores pointer; if function fails, underlying
-filehandle may be closed, or pointer may be in a different position.
-(VMS)
-</p>
-<p>The value returned by <code>tell</code> may be affected after the call, and
-the filehandle may be flushed. (Win32)
-</p>
-</dd>
-<dt>chmod</dt>
-<dd><a name="perlport-chmod"></a>
-<p>Only good for changing "owner" read-write access,
"group", and "other"
-bits are meaningless. (Win32)
-</p>
-<p>Only good for changing "owner" and "other" read-write
access. (RISC OS<!-- /@w -->)
-</p>
-<p>Access permissions are mapped onto VOS access-control list changes. (VOS)
-</p>
-<p>The actual permissions set depend on the value of the <code>CYGWIN</code>
-in the SYSTEM environment settings. (Cygwin)
-</p>
-<p>Setting the exec bit on some locations (generally <samp>/sdcard</samp>)
will return true
-but not actually set the bit. (Android)
-</p>
-</dd>
-<dt>chown</dt>
-<dd><a name="perlport-chown"></a>
-<p>Not implemented. (Win32, Plan 9<!-- /@w -->, RISC OS<!-- /@w -->)
-</p>
-<p>Does nothing, but won’t fail. (Win32)
-</p>
-<p>A little funky, because VOS’s notion of ownership is a little funky
(VOS).
-</p>
-</dd>
-<dt>chroot</dt>
-<dd><a name="perlport-chroot"></a>
-<p>Not implemented. (Win32, VMS, Plan 9<!-- /@w -->, RISC OS<!-- /@w
-->, VOS)
-</p>
-</dd>
-<dt>crypt</dt>
-<dd><a name="perlport-crypt"></a>
-<p>May not be available if library or source was not provided when building
-perl. (Win32)
-</p>
-<p>Not implemented. (Android)
-</p>
-</dd>
-<dt>dbmclose</dt>
-<dd><a name="perlport-dbmclose"></a>
-<p>Not implemented. (VMS, Plan 9<!-- /@w -->, VOS)
-</p>
-</dd>
-<dt>dbmopen</dt>
-<dd><a name="perlport-dbmopen"></a>
-<p>Not implemented. (VMS, Plan 9<!-- /@w -->, VOS)
-</p>
-</dd>
-<dt>dump</dt>
-<dd><a name="perlport-dump"></a>
-<p>Not useful. (RISC OS<!-- /@w -->)
-</p>
-<p>Not supported. (Cygwin, Win32)
-</p>
-<p>Invokes VMS debugger. (VMS)
-</p>
-</dd>
-<dt>exec</dt>
-<dd><a name="perlport-exec"></a>
-<p><code>exec LIST</code> without the use of indirect object syntax
(<code>exec PROGRAM LIST</code>)
-may fall back to trying the shell if the first <code>spawn()</code> fails.
(Win32)
-</p>
-<p>Does not automatically flush output handles on some platforms.
-(SunOS, Solaris, HP-UX)
-</p>
-<p>Not supported. (Symbian OS)
-</p>
-</dd>
-<dt>exit</dt>
-<dd><a name="perlport-exit"></a>
-<p>Emulates Unix <code>exit()</code> (which considers <code>exit 1</code> to
indicate an error) by
-mapping the <code>1</code> to <code>SS$_ABORT</code> (<code>44</code>). This
behavior may be overridden
-with the pragma <code>use vmsish 'exit'</code>. As with the CRTL’s
<code>exit()</code>
-function, <code>exit 0</code> is also mapped to an exit status of
<code>SS$_NORMAL</code>
-(<code>1</code>); this mapping cannot be overridden. Any other argument to
-<code>exit()</code>
-is used directly as Perl’s exit status. On VMS, unless the future
-POSIX_EXIT mode is enabled, the exit code should always be a valid
-VMS exit code and not a generic number. When the POSIX_EXIT mode is
-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)
-</p>
-<p><code>exit()</code> resets file pointers, which is a problem when called
-from a child process (created by <code>fork()</code>) in <code>BEGIN</code>.
-A workaround is to use <code>POSIX::_exit</code>. (Solaris)
-</p>
-<pre class="verbatim"> exit unless $Config{archname} =~ /\bsolaris\b/;
- require POSIX and POSIX::_exit(0);
-</pre>
-</dd>
-<dt>fcntl</dt>
-<dd><a name="perlport-fcntl"></a>
-<p>Not implemented. (Win32)
-</p>
-<p>Some functions available based on the version of VMS. (VMS)
-</p>
-</dd>
-<dt>flock</dt>
-<dd><a name="perlport-flock"></a>
-<p>Not implemented (VMS, RISC OS<!-- /@w -->, VOS).
-</p>
-</dd>
-<dt>fork</dt>
-<dd><a name="perlport-fork"></a>
-<p>Not implemented. (AmigaOS, RISC OS<!-- /@w -->, VMS)
-</p>
-<p>Emulated using multiple interpreters. See <a
href="#perlfork-NAME">perlfork NAME</a>. (Win32)
-</p>
-<p>Does not automatically flush output handles on some platforms.
-(SunOS, Solaris, HP-UX)
-</p>
-</dd>
-<dt>getlogin</dt>
-<dd><a name="perlport-getlogin"></a>
-<p>Not implemented. (RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>getpgrp</dt>
-<dd><a name="perlport-getpgrp"></a>
-<p>Not implemented. (Win32, VMS, RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>getppid</dt>
-<dd><a name="perlport-getppid"></a>
-<p>Not implemented. (Win32, RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>getpriority</dt>
-<dd><a name="perlport-getpriority"></a>
-<p>Not implemented. (Win32, VMS, RISC OS<!-- /@w -->, VOS)
-</p>
-</dd>
-<dt>getpwnam</dt>
-<dd><a name="perlport-getpwnam"></a>
-<p>Not implemented. (Win32)
-</p>
-<p>Not useful. (RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>getgrnam</dt>
-<dd><a name="perlport-getgrnam"></a>
-<p>Not implemented. (Win32, VMS, RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>getnetbyname</dt>
-<dd><a name="perlport-getnetbyname"></a>
-<p>Not implemented. (Android, Win32, Plan 9<!-- /@w -->)
-</p>
-</dd>
-<dt>getpwuid</dt>
-<dd><a name="perlport-getpwuid"></a>
-<p>Not implemented. (Win32)
-</p>
-<p>Not useful. (RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>getgrgid</dt>
-<dd><a name="perlport-getgrgid"></a>
-<p>Not implemented. (Win32, VMS, RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>getnetbyaddr</dt>
-<dd><a name="perlport-getnetbyaddr"></a>
-<p>Not implemented. (Android, Win32, Plan 9<!-- /@w -->)
-</p>
-</dd>
-<dt>getprotobynumber</dt>
-<dd><a name="perlport-getprotobynumber"></a>
-<p>Not implemented. (Android)
-</p>
-</dd>
-<dt>getservbyport</dt>
-<dd><a name="perlport-getservbyport"></a>
-</dd>
-<dt>getpwent</dt>
-<dd><a name="perlport-getpwent"></a>
-<p>Not implemented. (Android, Win32)
-</p>
-</dd>
-<dt>getgrent</dt>
-<dd><a name="perlport-getgrent"></a>
-<p>Not implemented. (Android, Win32, VMS)
-</p>
-</dd>
-<dt>gethostbyname</dt>
-<dd><a name="perlport-gethostbyname"></a>
-<p><code>gethostbyname('localhost')</code> does not work everywhere: you may
have
-to use <code>gethostbyname('127.0.0.1')</code>. (Irix 5<!-- /@w -->)
-</p>
-</dd>
-<dt>gethostent</dt>
-<dd><a name="perlport-gethostent"></a>
-<p>Not implemented. (Win32)
-</p>
-</dd>
-<dt>getnetent</dt>
-<dd><a name="perlport-getnetent"></a>
-<p>Not implemented. (Android, Win32, Plan 9<!-- /@w -->)
-</p>
-</dd>
-<dt>getprotoent</dt>
-<dd><a name="perlport-getprotoent"></a>
-<p>Not implemented. (Android, Win32, Plan 9<!-- /@w -->)
-</p>
-</dd>
-<dt>getservent</dt>
-<dd><a name="perlport-getservent"></a>
-<p>Not implemented. (Win32, Plan 9<!-- /@w -->)
-</p>
-</dd>
-<dt>seekdir</dt>
-<dd><a name="perlport-seekdir"></a>
-<p>Not implemented. (Android)
-</p>
-</dd>
-<dt>sethostent</dt>
-<dd><a name="perlport-sethostent"></a>
-<p>Not implemented. (Android, Win32, Plan 9<!-- /@w -->, RISC OS<!--
/@w -->)
-</p>
-</dd>
-<dt>setnetent</dt>
-<dd><a name="perlport-setnetent"></a>
-<p>Not implemented. (Win32, Plan 9<!-- /@w -->, RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>setprotoent</dt>
-<dd><a name="perlport-setprotoent"></a>
-<p>Not implemented. (Android, Win32, Plan 9<!-- /@w -->, RISC OS<!--
/@w -->)
-</p>
-</dd>
-<dt>setservent</dt>
-<dd><a name="perlport-setservent"></a>
-<p>Not implemented. (Plan 9<!-- /@w -->, Win32, RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>endpwent</dt>
-<dd><a name="perlport-endpwent"></a>
-<p>Not implemented. (Win32)
-</p>
-<p>Either not implemented or a no-op. (Android)
-</p>
-</dd>
-<dt>endgrent</dt>
-<dd><a name="perlport-endgrent"></a>
-<p>Not implemented. (Android, RISC OS<!-- /@w -->, VMS, Win32)
-</p>
-</dd>
-<dt>endhostent</dt>
-<dd><a name="perlport-endhostent"></a>
-<p>Not implemented. (Android, Win32)
-</p>
-</dd>
-<dt>endnetent</dt>
-<dd><a name="perlport-endnetent"></a>
-<p>Not implemented. (Android, Win32, Plan 9<!-- /@w -->)
-</p>
-</dd>
-<dt>endprotoent</dt>
-<dd><a name="perlport-endprotoent"></a>
-<p>Not implemented. (Android, Win32, Plan 9<!-- /@w -->)
-</p>
-</dd>
-<dt>endservent</dt>
-<dd><a name="perlport-endservent"></a>
-<p>Not implemented. (Plan 9<!-- /@w -->, Win32)
-</p>
-</dd>
-<dt>getsockopt SOCKET,LEVEL,OPTNAME</dt>
-<dd><a name="perlport-getsockopt-SOCKET_002cLEVEL_002cOPTNAME"></a>
-<p>Not implemented. (Plan 9<!-- /@w -->)
-</p>
-</dd>
-<dt>glob</dt>
-<dd><a name="perlport-glob"></a>
-<p>This operator is implemented via the <code>File::Glob</code> extension on
most
-platforms. See <a href="File-Glob.html#Top">(File-Glob)</a> for portability
information.
-</p>
-</dd>
-<dt>gmtime</dt>
-<dd><a name="perlport-gmtime"></a>
-<p>In theory, <code>gmtime()</code> is reliable from -2**63 to 2**63-1.
However,
-because work arounds in the implementation use floating point numbers,
-it will become inaccurate as the time gets larger. This is a bug and
-will be fixed in the future.
-</p>
-<p>On VOS, time values are 32-bit quantities.
-</p>
-</dd>
-<dt>ioctl FILEHANDLE,FUNCTION,SCALAR</dt>
-<dd><a name="perlport-ioctl-FILEHANDLE_002cFUNCTION_002cSCALAR"></a>
-<p>Not implemented. (VMS)
-</p>
-<p>Available only for socket handles, and it does what the
<code>ioctlsocket()</code> call
-in the Winsock API does. (Win32)
-</p>
-<p>Available only for socket handles. (RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>kill</dt>
-<dd><a name="perlport-kill"></a>
-<p>Not implemented, hence not useful for taint checking. (RISC OS<!-- /@w
-->)
-</p>
-<p><code>kill()</code> doesn’t have the semantics of
<code>raise()</code>, i.e. it doesn’t send
-a signal to the identified process like it does on Unix platforms.
-Instead <code>kill($sig, $pid)</code> terminates the process identified by
<code>$pid</code>,
-and makes it exit immediately with exit status $sig. As in Unix, if
-$sig is 0 and the specified process exists, it returns true without
-actually terminating it. (Win32)
-</p>
-<p><code>kill(-9, $pid)</code> will terminate the process specified by
<code>$pid</code> and
-recursively all child processes owned by it. This is different from
-the Unix semantics, where the signal will be delivered to all
-processes in the same process group as the process specified by
-$pid. (Win32)
-</p>
-<p>Is not supported for process identification number of 0 or negative
-numbers. (VMS)
-</p>
-</dd>
-<dt>link</dt>
-<dd><a name="perlport-link"></a>
-<p>Not implemented. (RISC OS<!-- /@w -->, VOS)
-</p>
-<p>Link count not updated because hard links are not quite that hard
-(They are sort of half-way between hard and soft links). (AmigaOS)
-</p>
-<p>Hard links are implemented on Win32 under NTFS only. They are
-natively supported on Windows 2000 and later. On Windows NT they
-are implemented using the Windows POSIX subsystem support and the
-Perl process will need Administrator or Backup Operator privileges
-to create hard links.
-</p>
-<p>Available on 64 bit OpenVMS 8.2 and later. (VMS)
-</p>
-</dd>
-<dt>localtime</dt>
-<dd><a name="perlport-localtime"></a>
-<p>localtime() has the same range as <a href="#perlport-gmtime">gmtime</a>,
but because time zone
-rules change its accuracy for historical and future times may degrade
-but usually by no more than an hour.
-</p>
-</dd>
-<dt>lstat</dt>
-<dd><a name="perlport-lstat"></a>
-<p>Not implemented. (RISC OS<!-- /@w -->)
-</p>
-<p>Return values (especially for device and inode) may be bogus. (Win32)
-</p>
-</dd>
-<dt>msgctl</dt>
-<dd><a name="perlport-msgctl"></a>
-</dd>
-<dt>msgget</dt>
-<dd><a name="perlport-msgget"></a>
-</dd>
-<dt>msgsnd</dt>
-<dd><a name="perlport-msgsnd"></a>
-</dd>
-<dt>msgrcv</dt>
-<dd><a name="perlport-msgrcv"></a>
-<p>Not implemented. (Android, Win32, VMS, Plan 9<!-- /@w -->,
RISC OS<!-- /@w -->, VOS)
-</p>
-</dd>
-<dt>open</dt>
-<dd><a name="perlport-open"></a>
-<p>open to <code>|-</code> and <code>-|</code> are unsupported. (Win32,
RISC OS<!-- /@w -->)
-</p>
-<p>Opening a process does not automatically flush output handles on some
-platforms. (SunOS, Solaris, HP-UX)
-</p>
-</dd>
-<dt>readlink</dt>
-<dd><a name="perlport-readlink"></a>
-<p>Not implemented. (Win32, VMS, RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>rename</dt>
-<dd><a name="perlport-rename"></a>
-<p>Can’t move directories between directories on different logical
volumes. (Win32)
-</p>
-</dd>
-<dt>rewinddir</dt>
-<dd><a name="perlport-rewinddir"></a>
-<p>Will not cause <code>readdir()</code> to re-read the directory stream. The
entries
-already read before the <code>rewinddir()</code> call will just be returned
again
-from a cache buffer. (Win32)
-</p>
-</dd>
-<dt>select</dt>
-<dd><a name="perlport-select"></a>
-<p>Only implemented on sockets. (Win32, VMS)
-</p>
-<p>Only reliable on sockets. (RISC OS<!-- /@w -->)
-</p>
-<p>Note that the <code>select FILEHANDLE</code> form is generally portable.
-</p>
-</dd>
-<dt>semctl</dt>
-<dd><a name="perlport-semctl"></a>
-</dd>
-<dt>semget</dt>
-<dd><a name="perlport-semget"></a>
-</dd>
-<dt>semop</dt>
-<dd><a name="perlport-semop"></a>
-<p>Not implemented. (Android, Win32, VMS, RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>setgrent</dt>
-<dd><a name="perlport-setgrent"></a>
-<p>Not implemented. (Android, VMS, Win32, RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>setpgrp</dt>
-<dd><a name="perlport-setpgrp"></a>
-<p>Not implemented. (Win32, VMS, RISC OS<!-- /@w -->, VOS)
-</p>
-</dd>
-<dt>setpriority</dt>
-<dd><a name="perlport-setpriority"></a>
-<p>Not implemented. (Win32, VMS, RISC OS<!-- /@w -->, VOS)
-</p>
-</dd>
-<dt>setpwent</dt>
-<dd><a name="perlport-setpwent"></a>
-<p>Not implemented. (Android, Win32, RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>setsockopt</dt>
-<dd><a name="perlport-setsockopt"></a>
-<p>Not implemented. (Plan 9<!-- /@w -->)
-</p>
-</dd>
-<dt>shmctl</dt>
-<dd><a name="perlport-shmctl"></a>
-</dd>
-<dt>shmget</dt>
-<dd><a name="perlport-shmget"></a>
-</dd>
-<dt>shmread</dt>
-<dd><a name="perlport-shmread"></a>
-</dd>
-<dt>shmwrite</dt>
-<dd><a name="perlport-shmwrite"></a>
-<p>Not implemented. (Android, Win32, VMS, RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>sleep</dt>
-<dd><a name="perlport-sleep"></a>
-<p>Emulated using synchronization functions such that it can be
-interrupted by <code>alarm()</code>, and limited to a maximum of 4294967
seconds,
-approximately 49 days. (Win32)
-</p>
-</dd>
-<dt>sockatmark</dt>
-<dd><a name="perlport-sockatmark"></a>
-<p>A relatively recent addition to socket functions, may not
-be implemented even in Unix platforms.
-</p>
-</dd>
-<dt>socketpair</dt>
-<dd><a name="perlport-socketpair"></a>
-<p>Not implemented. (RISC OS<!-- /@w -->)
-</p>
-<p>Available on 64 bit OpenVMS 8.2 and later. (VMS)
-</p>
-</dd>
-<dt>stat</dt>
-<dd><a name="perlport-stat"></a>
-<p>Platforms that do not have rdev, blksize, or blocks will return these
-as ”, so numeric comparison or manipulation of these fields may cause
-’not numeric’ warnings.
-</p>
-<p>ctime not supported on UFS (Mac OS X<!-- /@w -->).
-</p>
-<p>ctime is creation time instead of inode change time (Win32).
-</p>
-<p>device and inode are not meaningful. (Win32)
-</p>
-<p>device and inode are not necessarily reliable. (VMS)
-</p>
-<p>mtime, atime and ctime all return the last modification time. Device and
-inode are not necessarily reliable. (RISC OS<!-- /@w -->)
-</p>
-<p>dev, rdev, blksize, and blocks are not available. inode is not
-meaningful and will differ between stat calls on the same file. (os2)
-</p>
-<p>some versions of cygwin when doing a <code>stat("foo")</code> and
if not finding it
-may then attempt to <code>stat("foo.exe")</code> (Cygwin)
-</p>
-<p>On Win32 <code>stat()</code> needs to open the file to determine the link
count
-and update attributes that may have been changed through hard links.
-Setting <code>${^WIN32_SLOPPY_STAT}</code> to a true value speeds up
<code>stat()</code> by
-not performing this operation. (Win32)
-</p>
-</dd>
-<dt>symlink</dt>
-<dd><a name="perlport-symlink"></a>
-<p>Not implemented. (Win32, RISC OS<!-- /@w -->)
-</p>
-<p>Implemented on 64 bit VMS 8.3. VMS requires the symbolic link to be in Unix
-syntax if it is intended to resolve to a valid path.
-</p>
-</dd>
-<dt>syscall</dt>
-<dd><a name="perlport-syscall"></a>
-<p>Not implemented. (Win32, VMS, RISC OS<!-- /@w -->, VOS)
-</p>
-</dd>
-<dt>sysopen</dt>
-<dd><a name="perlport-sysopen"></a>
-<p>The traditional "0", "1", and "2" MODEs are
implemented with different
-numeric values on some systems. The flags exported by <code>Fcntl</code>
-(O_RDONLY, O_WRONLY, O_RDWR) should work everywhere though. (Mac OS<!--
/@w -->, OS/390)
-</p>
-</dd>
-<dt>system</dt>
-<dd><a name="perlport-system"></a>
-<p>As an optimization, may not call the command shell specified in
-<code>$ENV{PERL5SHELL}</code>. <code>system(1, @args)</code> spawns an
external
-process and immediately returns its process designator, without
-waiting for it to terminate. Return value may be used subsequently
-in <code>wait</code> or <code>waitpid</code>. Failure to <code>spawn()</code>
a subprocess is indicated
-by setting <code>$?</code> to
<code>"255 << 8"</code><!-- /@w -->. <code>$?</code>
is set in a way compatible with
-Unix (i.e. the exitstatus of the subprocess is obtained by
<code>"$? </code><!-- /@w --> 8">>,
-as described in the documentation). (Win32)
-</p>
-<p>There is no shell to process metacharacters, and the native standard is
-to pass a command line terminated by "\n" "\r" or
"\0" to the spawned
-program. Redirection such as <code>> foo</code> is performed (if at all) by
-the run time library of the spawned program. <code>system</code>
<em>list</em> will call
-the Unix emulation library’s <code>exec</code> emulation, which attempts
to provide
-emulation of the stdin, stdout, stderr in force in the parent, providing
-the child program uses a compatible version of the emulation library.
-<em>scalar</em> will call the native command line direct and no such emulation
-of a child Unix program will exists. Mileage <strong>will</strong> vary.
(RISC OS<!-- /@w -->)
-</p>
-<p><code>system LIST</code> without the use of indirect object syntax
(<code>system PROGRAM LIST</code>)
-may fall back to trying the shell if the first <code>spawn()</code> fails.
(Win32)
-</p>
-<p>Does not automatically flush output handles on some platforms.
-(SunOS, Solaris, HP-UX)
-</p>
-<p>The return value is POSIX-like (shifted up by 8 bits), which only allows
-room for a made-up value derived from the severity bits of the native
-32-bit condition code (unless overridden by <code>use vmsish 'status'</code>).
-If the native condition code is one that has a POSIX value encoded, the
-POSIX value will be decoded to extract the expected exit value.
-For more details see <a href="#perlvms-_0024_003f">perlvms $?</a>. (VMS)
-</p>
-</dd>
-<dt>telldir</dt>
-<dd><a name="perlport-telldir"></a>
-<p>Not implemented. (Android)
-</p>
-</dd>
-<dt>times</dt>
-<dd><a name="perlport-times"></a>
-<p>"cumulative" times will be bogus. On anything other than Windows
NT
-or Windows 2000, "system" time will be bogus, and "user"
time is
-actually the time returned by the <code>clock()</code> function in the C
runtime
-library. (Win32)
-</p>
-<p>Not useful. (RISC OS<!-- /@w -->)
-</p>
-</dd>
-<dt>truncate</dt>
-<dd><a name="perlport-truncate"></a>
-<p>Not implemented. (Older versions of VMS)
-</p>
-<p>Truncation to same-or-shorter lengths only. (VOS)
-</p>
-<p>If a FILEHANDLE is supplied, it must be writable and opened in append
-mode (i.e., use <code>open(FH, '>>filename')</code>
-or <code>sysopen(FH,...,O_APPEND|O_RDWR)</code>. If a filename is supplied, it
-should not be held open elsewhere. (Win32)
-</p>
-</dd>
-<dt>umask</dt>
-<dd><a name="perlport-umask"></a>
-<p>Returns undef where unavailable.
-</p>
-<p><code>umask</code> works but the correct permissions are set only when the
file
-is finally closed. (AmigaOS)
-</p>
-</dd>
-<dt>utime</dt>
-<dd><a name="perlport-utime"></a>
-<p>Only the modification time is updated. (VMS, RISC OS<!-- /@w -->)
-</p>
-<p>May not behave as expected. Behavior depends on the C runtime
-library’s implementation of <code>utime()</code>, and the filesystem
being
-used. The FAT filesystem typically does not support an "access
-time" field, and it may limit timestamps to a granularity of
-two seconds. (Win32)
-</p>
-</dd>
-<dt>wait</dt>
-<dd><a name="perlport-wait"></a>
-</dd>
-<dt>waitpid</dt>
-<dd><a name="perlport-waitpid"></a>
-<p>Can only be applied to process handles returned for processes spawned
-using <code>system(1, ...)</code> or pseudo processes created with
<code>fork()</code>. (Win32)
-</p>
-<p>Not useful. (RISC OS<!-- /@w -->)
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlport-Supported-Platforms"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-EOL-Platforms" accesskey="n" rel="next">perlport EOL
Platforms</a>, Previous: <a href="#perlport-FUNCTION-IMPLEMENTATIONS"
accesskey="p" rel="prev">perlport FUNCTION IMPLEMENTATIONS</a>, Up: <a
href="#perlport" accesskey="u" rel="up">perlport</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Supported-Platforms"></a>
-<h3 class="section">56.7 Supported Platforms</h3>
-
-<p>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 <a href="http://www.cpan.org/src";>http://www.cpan.org/src</a>
-</p>
-<dl compact="compact">
-<dt>Linux (x86, ARM, IA64)</dt>
-<dd><a name="perlport-Linux-_0028x86_002c-ARM_002c-IA64_0029"></a>
-</dd>
-<dt>HP-UX</dt>
-<dd><a name="perlport-HP_002dUX"></a>
-</dd>
-<dt>AIX</dt>
-<dd><a name="perlport-AIX"></a>
-</dd>
-<dt>Win32</dt>
-<dd><a name="perlport-Win32"></a>
-<dl compact="compact">
-<dt>Windows 2000</dt>
-<dd><a name="perlport-Windows-2000"></a>
-</dd>
-<dt>Windows XP</dt>
-<dd><a name="perlport-Windows-XP"></a>
-</dd>
-<dt>Windows Server 2003</dt>
-<dd><a name="perlport-Windows-Server-2003"></a>
-</dd>
-<dt>Windows Vista</dt>
-<dd><a name="perlport-Windows-Vista"></a>
-</dd>
-<dt>Windows Server 2008</dt>
-<dd><a name="perlport-Windows-Server-2008"></a>
-</dd>
-<dt>Windows 7</dt>
-<dd><a name="perlport-Windows-7"></a>
-</dd>
-</dl>
-
-</dd>
-<dt>Cygwin</dt>
-<dd><a name="perlport-Cygwin"></a>
-<p>Some tests are known to fail:
-</p>
-<ul>
-<li> <samp>ext/XS-APItes/t/call_checker.t</samp> - see
-<a
href="https://rt.perl.org/Ticket/Display.html?id=78502";>https://rt.perl.org/Ticket/Display.html?id=78502</a>
-
-</li><li> <samp>dist/I18N-Collate/t/I18N-Collate.t</samp>
-
-</li><li> <samp>ext/Win32CORE/t/win32core.t</samp> - may fail on recent cygwin
installs.
-
-</li></ul>
-
-</dd>
-<dt>Solaris (x86, SPARC)</dt>
-<dd><a name="perlport-Solaris-_0028x86_002c-SPARC_0029"></a>
-</dd>
-<dt>OpenVMS</dt>
-<dd><a name="perlport-OpenVMS"></a>
-<dl compact="compact">
-<dt>Alpha (7.2 and later)</dt>
-<dd><a name="perlport-Alpha-_00287_002e2-and-later_0029"></a>
-</dd>
-<dt>I64 (8.2 and later)</dt>
-<dd><a name="perlport-I64-_00288_002e2-and-later_0029"></a>
-</dd>
-</dl>
-
-</dd>
-<dt>Symbian</dt>
-<dd><a name="perlport-Symbian"></a>
-</dd>
-<dt>NetBSD</dt>
-<dd><a name="perlport-NetBSD"></a>
-</dd>
-<dt>FreeBSD</dt>
-<dd><a name="perlport-FreeBSD"></a>
-</dd>
-<dt>Debian GNU/kFreeBSD</dt>
-<dd><a name="perlport-Debian-GNU_002fkFreeBSD"></a>
-</dd>
-<dt>Haiku</dt>
-<dd><a name="perlport-Haiku"></a>
-</dd>
-<dt>Irix (6.5. What else?)</dt>
-<dd><a name="perlport-Irix-_00286_002e5_002e-What-else_003f_0029"></a>
-</dd>
-<dt>OpenBSD</dt>
-<dd><a name="perlport-OpenBSD"></a>
-</dd>
-<dt>Dragonfly BSD</dt>
-<dd><a name="perlport-Dragonfly-BSD"></a>
-</dd>
-<dt>Midnight BSD</dt>
-<dd><a name="perlport-Midnight-BSD"></a>
-</dd>
-<dt>QNX Neutrino RTOS (6.5.0)</dt>
-<dd><a name="perlport-QNX-Neutrino-RTOS-_00286_002e5_002e0_0029"></a>
-</dd>
-<dt>MirOS BSD</dt>
-<dd><a name="perlport-MirOS-BSD"></a>
-</dd>
-<dt>Stratus OpenVOS (17.0 or later)</dt>
-<dd><a name="perlport-Stratus-OpenVOS-_002817_002e0-or-later_0029"></a>
-<p>Caveats:
-</p>
-<dl compact="compact">
-<dt>time_t issues that may or may not be fixed</dt>
-<dd><a name="perlport-time_005ft-issues-that-may-or-may-not-be-fixed"></a>
-</dd>
-</dl>
-
-</dd>
-<dt>Symbian (Series 60 v3, 3.2 and 5 - what else?)</dt>
-<dd><a
name="perlport-Symbian-_0028Series-60-v3_002c-3_002e2-and-5-_002d-what-else_003f_0029"></a>
-</dd>
-<dt>Stratus VOS / OpenVOS</dt>
-<dd><a name="perlport-Stratus-VOS-_002f-OpenVOS"></a>
-</dd>
-<dt>AIX</dt>
-<dd><a name="perlport-AIX-1"></a>
-</dd>
-<dt>Android</dt>
-<dd><a name="perlport-Android"></a>
-</dd>
-<dt>FreeMINT</dt>
-<dd><a name="perlport-FreeMINT"></a>
-<p>Perl now builds with FreeMiNT/Atari. It fails a few tests, that needs
-some investigation.
-</p>
-<p>The FreeMiNT port uses GNU dld for loadable module capabilities. So
-ensure you have that library installed when building perl.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlport-EOL-Platforms"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-Supported-Platforms-_0028Perl-5_002e8_0029"
accesskey="n" rel="next">perlport Supported Platforms (Perl 5.8)</a>, Previous:
<a href="#perlport-Supported-Platforms" accesskey="p" rel="prev">perlport
Supported Platforms</a>, Up: <a href="#perlport" accesskey="u"
rel="up">perlport</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="EOL-Platforms"></a>
-<h3 class="section">56.8 EOL Platforms</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlport-_0028Perl-5_002e20_0029" accesskey="1">perlport (Perl
5.20)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-_0028Perl-5_002e14_0029" accesskey="2">perlport (Perl
5.14)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlport-_0028Perl-5_002e12_0029" accesskey="3">perlport (Perl
5.12)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlport-_0028Perl-5_002e20_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-_0028Perl-5_002e14_0029" accesskey="n"
rel="next">perlport (Perl 5.14)</a>, Up: <a href="#perlport-EOL-Platforms"
accesskey="u" rel="up">perlport EOL Platforms</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="g_t_0028Perl-5_002e20_0029"></a>
-<h4 class="subsection">56.8.1 (Perl 5.20)</h4>
-
-<p>The following platforms were supported by a previous version of
-Perl but have been officially removed from Perl’s source code
-as of 5.20:
-</p>
-<dl compact="compact">
-<dt>AT&T 3b1</dt>
-<dd><a name="perlport-AT_0026T-3b1"></a>
-</dd>
-</dl>
-
-<hr>
-<a name="perlport-_0028Perl-5_002e14_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-_0028Perl-5_002e12_0029" accesskey="n"
rel="next">perlport (Perl 5.12)</a>, Previous: <a
href="#perlport-_0028Perl-5_002e20_0029" accesskey="p" rel="prev">perlport
(Perl 5.20)</a>, Up: <a href="#perlport-EOL-Platforms" accesskey="u"
rel="up">perlport EOL Platforms</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="g_t_0028Perl-5_002e14_0029"></a>
-<h4 class="subsection">56.8.2 (Perl 5.14)</h4>
-
-<p>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:
-</p>
-<dl compact="compact">
-<dt>Windows 95</dt>
-<dd><a name="perlport-Windows-95"></a>
-</dd>
-<dt>Windows 98</dt>
-<dd><a name="perlport-Windows-98"></a>
-</dd>
-<dt>Windows ME</dt>
-<dd><a name="perlport-Windows-ME"></a>
-</dd>
-<dt>Windows NT4</dt>
-<dd><a name="perlport-Windows-NT4"></a>
-</dd>
-</dl>
-
-<hr>
-<a name="perlport-_0028Perl-5_002e12_0029"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlport-_0028Perl-5_002e14_0029" accesskey="p"
rel="prev">perlport (Perl 5.14)</a>, Up: <a href="#perlport-EOL-Platforms"
accesskey="u" rel="up">perlport EOL Platforms</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="g_t_0028Perl-5_002e12_0029"></a>
-<h4 class="subsection">56.8.3 (Perl 5.12)</h4>
-
-<p>The following platforms were supported by a previous version of
-Perl but have been officially removed from Perl’s source code
-as of 5.12:
-</p>
-<dl compact="compact">
-<dt>Atari MiNT</dt>
-<dd><a name="perlport-Atari-MiNT"></a>
-</dd>
-<dt>Apollo Domain/OS</dt>
-<dd><a name="perlport-Apollo-Domain_002fOS"></a>
-</dd>
-<dt>Apple Mac OS 8/9</dt>
-<dd><a name="perlport-Apple-Mac-OS-8_002f9"></a>
-</dd>
-<dt>Tenon Machten</dt>
-<dd><a name="perlport-Tenon-Machten"></a>
-</dd>
-</dl>
-
-<hr>
-<a name="perlport-Supported-Platforms-_0028Perl-5_002e8_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-SEE-ALSO" accesskey="n" rel="next">perlport SEE
ALSO</a>, Previous: <a href="#perlport-EOL-Platforms" accesskey="p"
rel="prev">perlport EOL Platforms</a>, Up: <a href="#perlport" accesskey="u"
rel="up">perlport</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Supported-Platforms-_0028Perl-5_002e8_0029"></a>
-<h3 class="section">56.9 Supported Platforms (Perl 5.8)</h3>
-
-<p>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 <a href="http://www.cpan.org/src/";>http://www.cpan.org/src/</a>
-</p>
-<pre class="verbatim"> AIX
- BeOS
- BSD/OS (BSDi)
- Cygwin
- DG/UX
- DOS DJGPP 1)
- DYNIX/ptx
- EPOC R5
- FreeBSD
- HI-UXMPP (Hitachi) (5.8.0 worked but we didn't know it)
- HP-UX
- IRIX
- Linux
- Mac OS Classic
- Mac OS X (Darwin)
- MPE/iX
- NetBSD
- NetWare
- NonStop-UX
- ReliantUNIX (formerly SINIX)
- OpenBSD
- OpenVMS (formerly VMS)
- Open UNIX (Unixware) (since Perl 5.8.1/5.9.0)
- OS/2
- OS/400 (using the PASE) (since Perl 5.8.1/5.9.0)
- PowerUX
- POSIX-BC (formerly BS2000)
- QNX
- Solaris
- SunOS 4
- SUPER-UX (NEC)
- Tru64 UNIX (formerly DEC OSF/1, Digital UNIX)
- UNICOS
- UNICOS/mk
- UTS
- VOS / OpenVOS
- Win95/98/ME/2K/XP 2)
- WinCE
- z/OS (formerly OS/390)
- VM/ESA
-
- 1) in DOS mode either the DOS or OS/2 ports can be used
- 2) compilers: Borland, MinGW (GCC), VC6
-</pre>
-<p>The following platforms worked with the previous releases (5.6 and
-5.7), but we did not manage either to fix or to test these in time
-for the 5.8.0 release. There is a very good chance that many of these
-will work fine with the 5.8.0.
-</p>
-<pre class="verbatim"> BSD/OS
- DomainOS
- Hurd
- LynxOS
- MachTen
- PowerMAX
- SCO SV
- SVR4
- Unixware
- Windows 3.1
-</pre>
-<p>Known to be broken for 5.8.0 (but 5.6.1 and 5.7.2 can be used):
-</p>
-<pre class="verbatim"> AmigaOS
-</pre>
-<p>The following platforms have been known to build Perl from source in
-the past (5.005_03 and earlier), but we haven’t been able to verify
-their status for the current release, either because the
-hardware/software platforms are rare or because we don’t have an
-active champion on these platforms–or both. They used to work,
-though, so go ahead and try compiling them, and let address@hidden
-of any trouble.
-</p>
-<pre class="verbatim"> 3b1
- A/UX
- ConvexOS
- CX/UX
- DC/OSx
- DDE SMES
- DOS EMX
- Dynix
- EP/IX
- ESIX
- FPS
- GENIX
- Greenhills
- ISC
- MachTen 68k
- MPC
- NEWS-OS
- NextSTEP
- OpenSTEP
- Opus
- Plan 9
- RISC/os
- SCO ODT/OSR
- Stellar
- SVR2
- TI1500
- TitanOS
- Ultrix
- Unisys Dynix
-</pre>
-<p>The following platforms have their own source code distributions and
-binaries available via <a
href="http://www.cpan.org/ports/";>http://www.cpan.org/ports/</a>
-</p>
-<pre class="verbatim"> Perl release
-
- OS/400 (ILE) 5.005_02
- Tandem Guardian 5.004
-</pre>
-<p>The following platforms have only binaries available via
-<a
href="http://www.cpan.org/ports/index.html";>http://www.cpan.org/ports/index.html</a>
:
-</p>
-<pre class="verbatim"> Perl release
-
- Acorn RISCOS 5.005_02
- AOS 5.002
- LynxOS 5.004_02
-</pre>
-<p>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
-<a
href="http://www.cpan.org/ports/index.html";>http://www.cpan.org/ports/index.html</a>
for binary distributions.
-</p>
-<hr>
-<a name="perlport-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlport-AUTHORS-_002f-CONTRIBUTORS" accesskey="n"
rel="next">perlport AUTHORS / CONTRIBUTORS</a>, Previous: <a
href="#perlport-Supported-Platforms-_0028Perl-5_002e8_0029" accesskey="p"
rel="prev">perlport Supported Platforms (Perl 5.8)</a>, Up: <a href="#perlport"
accesskey="u" rel="up">perlport</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-29"></a>
-<h3 class="section">56.10 SEE ALSO</h3>
-
-<p><a href="perlaix.html#Top">(perlaix)</a>, <a
href="perlamiga.html#Top">(perlamiga)</a>, <a
href="perlbs2000.html#Top">(perlbs2000)</a>,
-<a href="perlce.html#Top">(perlce)</a>, <a
href="perlcygwin.html#Top">(perlcygwin)</a>, <a
href="perldos.html#Top">(perldos)</a>,
-<a href="#perlebcdic-NAME">perlebcdic NAME</a>, <a
href="perlfreebsd.html#Top">(perlfreebsd)</a>, <a
href="perlhurd.html#Top">(perlhurd)</a>, <a
href="perlhpux.html#Top">(perlhpux)</a>, <a
href="perlirix.html#Top">(perlirix)</a>,
-<a href="perlmacos.html#Top">(perlmacos)</a>, <a
href="perlmacosx.html#Top">(perlmacosx)</a>,
-<a href="perlnetware.html#Top">(perlnetware)</a>, <a
href="perlos2.html#Top">(perlos2)</a>, <a
href="perlos390.html#Top">(perlos390)</a>, <a
href="perlos400.html#Top">(perlos400)</a>,
-<a href="perlplan9.html#Top">(perlplan9)</a>, <a
href="perlqnx.html#Top">(perlqnx)</a>, <a
href="perlsolaris.html#Top">(perlsolaris)</a>, <a
href="perltru64.html#Top">(perltru64)</a>,
-<a href="#perlunicode-NAME">perlunicode NAME</a>, <a
href="#perlvms-NAME">perlvms NAME</a>, <a
href="perlvos.html#Top">(perlvos)</a>, <a
href="perlwin32.html#Top">(perlwin32)</a>, and <a
href="Win32.html#Top">(Win32)</a>.
-</p>
-<hr>
-<a name="perlport-AUTHORS-_002f-CONTRIBUTORS"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlport-SEE-ALSO" accesskey="p" rel="prev">perlport SEE
ALSO</a>, Up: <a href="#perlport" accesskey="u" rel="up">perlport</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHORS-_002f-CONTRIBUTORS"></a>
-<h3 class="section">56.11 AUTHORS / CONTRIBUTORS</h3>
-
-<p>Abigail <address@hidden>,
-Charles Bailey <address@hidden>,
-Graham Barr <address@hidden>,
-Tom Christiansen <address@hidden>,
-Nicholas Clark <address@hidden>,
-Thomas Dorner <address@hidden>,
-Andy Dougherty <address@hidden>,
-Dominic Dunlop <address@hidden>,
-Neale Ferguson <address@hidden>,
-David J. Fiander <address@hidden>,
-Paul Green <address@hidden>,
-M.J.T. Guy <address@hidden>,
-Jarkko Hietaniemi <address@hidden>,
-Luther Huffman <address@hidden>,
-Nick Ing-Simmons <address@hidden>,
-Andreas J. König <address@hidden>,
-Markus Laker <address@hidden>,
-Andrew M. Langmead <address@hidden>,
-Larry Moore <address@hidden>,
-Paul Moore <address@hidden>,
-Chris Nandor <address@hidden>,
-Matthias Neeracher <address@hidden>,
-Philip Newton <address@hidden>,
-Gary Ng <address@hidden>,
-Tom Phoenix <address@hidden>,
-André Pirard <address@hidden>,
-Peter Prymmer <address@hidden>,
-Hugo van der Sanden <address@hidden>,
-Gurusamy Sarathy <address@hidden>,
-Paul J. Schinder <address@hidden>,
-Michael G Schwern <address@hidden>,
-Dan Sugalski <address@hidden>,
-Nathan Torkington <address@hidden>,
-John Malmberg <address@hidden>
-</p>
-<hr>
-<a name="perlpragma"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre" accesskey="n" rel="next">perlre</a>, Previous: <a
href="#perlport" accesskey="p" rel="prev">perlport</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlpragma-1"></a>
-<h2 class="chapter">57 perlpragma</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlpragma-NAME"
accesskey="1">perlpragma NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpragma-DESCRIPTION"
accesskey="2">perlpragma DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpragma-A-basic-example"
accesskey="3">perlpragma A basic example</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlpragma-Key-naming"
accesskey="4">perlpragma Key naming</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlpragma-Implementation-details" accesskey="5">perlpragma
Implementation details</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlpragma-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpragma-DESCRIPTION" accesskey="n" rel="next">perlpragma
DESCRIPTION</a>, Up: <a href="#perlpragma" accesskey="u"
rel="up">perlpragma</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-56"></a>
-<h3 class="section">57.1 NAME</h3>
-
-<p>perlpragma - how to write a user pragma
-</p>
-<hr>
-<a name="perlpragma-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpragma-A-basic-example" accesskey="n"
rel="next">perlpragma A basic example</a>, Previous: <a href="#perlpragma-NAME"
accesskey="p" rel="prev">perlpragma NAME</a>, Up: <a href="#perlpragma"
accesskey="u" rel="up">perlpragma</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-55"></a>
-<h3 class="section">57.2 DESCRIPTION</h3>
-
-<p>A pragma is a module which influences some aspect of the compile time or run
-time behaviour of Perl, such as <code>strict</code> or <code>warnings</code>.
With Perl 5.10 you
-are no longer limited to the built in pragmata; you can now create user
-pragmata that modify the behaviour of user functions within a lexical scope.
-</p>
-<hr>
-<a name="perlpragma-A-basic-example"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpragma-Key-naming" accesskey="n" rel="next">perlpragma Key
naming</a>, Previous: <a href="#perlpragma-DESCRIPTION" accesskey="p"
rel="prev">perlpragma DESCRIPTION</a>, Up: <a href="#perlpragma" accesskey="u"
rel="up">perlpragma</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="A-basic-example"></a>
-<h3 class="section">57.3 A basic example</h3>
-
-<p>For example, say you need to create a class implementing overloaded
-mathematical operators, and would like to provide your own pragma that
-functions much like <code>use integer;</code> You’d like this code
-</p>
-<pre class="verbatim"> use MyMaths;
-
- my $l = MyMaths->new(1.2);
- my $r = MyMaths->new(3.4);
-
- print "A: ", $l + $r, "\n";
-
- use myint;
- print "B: ", $l + $r, "\n";
-
- {
- no myint;
- print "C: ", $l + $r, "\n";
- }
-
- print "D: ", $l + $r, "\n";
-
- no myint;
- print "E: ", $l + $r, "\n";
-</pre>
-<p>to give the output
-</p>
-<pre class="verbatim"> A: 4.6
- B: 4
- C: 4.6
- D: 4
- E: 4.6
-</pre>
-<p><em>i.e.</em>, where <code>use myint;</code> is in effect, addition
operations are forced
-to integer, whereas by default they are not, with the default behaviour being
-restored via <code>no myint;</code>
-</p>
-<p>The minimal implementation of the package <code>MyMaths</code> would be
something like
-this:
-</p>
-<pre class="verbatim"> package MyMaths;
- use warnings;
- use strict;
- use myint();
- use overload '+' => sub {
- my ($l, $r) = @_;
- # Pass 1 to check up one call level from here
- if (myint::in_effect(1)) {
- int($$l) + int($$r);
- } else {
- $$l + $$r;
- }
- };
-
- sub new {
- my ($class, $value) = @_;
- bless \$value, $class;
- }
-
- 1;
-</pre>
-<p>Note how we load the user pragma <code>myint</code> with an empty list
<code>()</code> to
-prevent its <code>import</code> being called.
-</p>
-<p>The interaction with the Perl compilation happens inside package
<code>myint</code>:
-</p>
-<pre class="verbatim"> package myint;
-
- use strict;
- use warnings;
-
- sub import {
- $^H{"myint/in_effect"} = 1;
- }
-
- sub unimport {
- $^H{"myint/in_effect"} = 0;
- }
-
- sub in_effect {
- my $level = shift // 0;
- my $hinthash = (caller($level))[10];
- return $hinthash->{"myint/in_effect"};
- }
-
- 1;
-</pre>
-<p>As pragmata are implemented as modules, like any other module, <code>use
myint;</code>
-becomes
-</p>
-<pre class="verbatim"> BEGIN {
- require myint;
- myint->import();
- }
-</pre>
-<p>and <code>no myint;</code> is
-</p>
-<pre class="verbatim"> BEGIN {
- require myint;
- myint->unimport();
- }
-</pre>
-<p>Hence the <code>import</code> and <code>unimport</code> routines are called
at <strong>compile time</strong>
-for the user’s code.
-</p>
-<p>User pragmata store their state by writing to the magical hash
<code>%^H</code>,
-hence these two routines manipulate it. The state information in
<code>%^H</code> is
-stored in the optree, and can be retrieved read-only at runtime with
<code>caller()</code>,
-at index 10 of the list of returned results. In the example pragma, retrieval
-is encapsulated into the routine <code>in_effect()</code>, which takes as
parameter
-the number of call frames to go up to find the value of the pragma in the
-user’s script. This uses <code>caller()</code> to determine the value of
-<code>$^H{"myint/in_effect"}</code> when each line of the
user’s script was called, and
-therefore provide the correct semantics in the subroutine implementing the
-overloaded addition.
-</p>
-<hr>
-<a name="perlpragma-Key-naming"></a>
-<div class="header">
-<p>
-Next: <a href="#perlpragma-Implementation-details" accesskey="n"
rel="next">perlpragma Implementation details</a>, Previous: <a
href="#perlpragma-A-basic-example" accesskey="p" rel="prev">perlpragma A basic
example</a>, Up: <a href="#perlpragma" accesskey="u" rel="up">perlpragma</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Key-naming"></a>
-<h3 class="section">57.4 Key naming</h3>
-
-<p>There is only a single <code>%^H</code>, but arbitrarily many modules that
want
-to use its scoping semantics. To avoid stepping on each other’s toes,
-they need to be sure to use different keys in the hash. It is therefore
-conventional for a module to use only keys that begin with the module’s
-name (the name of its main package) and a "/" character. After this
-module-identifying prefix, the rest of the key is entirely up to the
-module: it may include any characters whatsoever. For example, a module
-<code>Foo::Bar</code> should use keys such as <code>Foo::Bar/baz</code> and
<code>Foo::Bar/$%/_!</code>.
-Modules following this convention all play nicely with each other.
-</p>
-<p>The Perl core uses a handful of keys in <code>%^H</code> which do not
follow this
-convention, because they predate it. Keys that follow the convention
-won’t conflict with the core’s historical keys.
-</p>
-<hr>
-<a name="perlpragma-Implementation-details"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlpragma-Key-naming" accesskey="p" rel="prev">perlpragma
Key naming</a>, Up: <a href="#perlpragma" accesskey="u" rel="up">perlpragma</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Implementation-details"></a>
-<h3 class="section">57.5 Implementation details</h3>
-
-<p>The optree is shared between threads. This means there is a possibility
that
-the optree will outlive the particular thread (and therefore the interpreter
-instance) that created it, so true Perl scalars cannot be stored in the
-optree. Instead a compact form is used, which can only store values that are
-integers (signed and unsigned), strings or <code>undef</code> - references and
-floating point values are stringified. If you need to store multiple values
-or complex structures, you should serialise them, for example with
<code>pack</code>.
-The deletion of a hash key from <code>%^H</code> is recorded, and as ever can
be
-distinguished from the existence of a key with value <code>undef</code> with
-<code>exists</code>.
-</p>
-<p><strong>Don’t</strong> attempt to store references to data structures
as integers which
-are retrieved via <code>caller</code> and converted back, as this will not be
threadsafe.
-Accesses would be to the structure without locking (which is not safe for
-Perl’s scalars), and either the structure has to leak, or it has to be
-freed when its creating thread terminates, which may be before the optree
-referencing it is deleted, if other threads outlive it.
-</p>
-<hr>
-<a name="perlre"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi" accesskey="n" rel="next">perlreapi</a>, Previous:
<a href="#perlpragma" accesskey="p" rel="prev">perlpragma</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlre-1"></a>
-<h2 class="chapter">58 perlre</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlre-NAME"
accesskey="1">perlre NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-DESCRIPTION"
accesskey="2">perlre DESCRIPTION</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-BUGS"
accesskey="3">perlre BUGS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-SEE-ALSO"
accesskey="4">perlre SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlre-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-DESCRIPTION" accesskey="n" rel="next">perlre
DESCRIPTION</a>, Up: <a href="#perlre" accesskey="u" rel="up">perlre</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-57"></a>
-<h3 class="section">58.1 NAME</h3>
-
-<p>perlre - Perl regular expressions
-</p>
-<hr>
-<a name="perlre-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-BUGS" accesskey="n" rel="next">perlre BUGS</a>,
Previous: <a href="#perlre-NAME" accesskey="p" rel="prev">perlre NAME</a>, Up:
<a href="#perlre" accesskey="u" rel="up">perlre</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-56"></a>
-<h3 class="section">58.2 DESCRIPTION</h3>
-
-<p>This page describes the syntax of regular expressions in Perl.
-</p>
-<p>If you haven’t used regular expressions before, a quick-start
-introduction is available in <a href="#perlrequick-NAME">perlrequick NAME</a>,
and a longer tutorial
-introduction is available in <a href="#perlretut-NAME">perlretut NAME</a>.
-</p>
-<p>For reference on how regular expressions are used in matching
-operations, plus various examples of the same, see discussions of
-<code>m//</code>, <code>s///</code>, <code>qr//</code> and <code>??</code> in
<a href="#perlop-Regexp-Quote_002dLike-Operators">perlop Regexp Quote-Like
Operators</a>.
-</p>
-<p>New in v5.22, <a href="re.html#g_t_0027strict_0027-mode">(re)<code>use re
'strict'</code></a> applies stricter
-rules than otherwise when compiling regular expression patterns. It can
-find things that, while legal, may not be what you intended.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlre-Modifiers"
accesskey="1">perlre Modifiers</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-Regular-Expressions"
accesskey="2">perlre Regular Expressions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Quoting-metacharacters" accesskey="3">perlre Quoting
metacharacters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-Extended-Patterns"
accesskey="4">perlre Extended Patterns</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Special-Backtracking-Control-Verbs" accesskey="5">perlre Special
Backtracking Control Verbs</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-Backtracking"
accesskey="6">perlre Backtracking</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Version-8-Regular-Expressions" accesskey="7">perlre Version 8
Regular Expressions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Warning-on-_005c1-Instead-of-_00241" accesskey="8">perlre Warning
on \1 Instead of $1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Repeated-Patterns-Matching-a-Zero_002dlength-Substring"
accesskey="9">perlre Repeated Patterns Matching a Zero-length
Substring</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Combining-RE-Pieces">perlre Combining RE
Pieces</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Creating-Custom-RE-Engines">perlre Creating Custom RE
Engines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Embedded-Code-Execution-Frequency">perlre Embedded Code Execution
Frequency</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-PCRE_002fPython-Support">perlre PCRE/Python
Support</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlre-Modifiers"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Regular-Expressions" accesskey="n" rel="next">perlre
Regular Expressions</a>, Up: <a href="#perlre-DESCRIPTION" accesskey="u"
rel="up">perlre DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Modifiers"></a>
-<h4 class="subsection">58.2.1 Modifiers</h4>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlre-Overview"
accesskey="1">perlre Overview</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Details-on-some-modifiers" accesskey="2">perlre Details on some
modifiers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-_002fx"
accesskey="3">perlre /x</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Character-set-modifiers" accesskey="4">perlre Character set
modifiers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-_002fl"
accesskey="5">perlre /l</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-_002fu"
accesskey="6">perlre /u</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-_002fd"
accesskey="7">perlre /d</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-_002fa-_0028and-_002faa_0029" accesskey="8">perlre /a (and
/aa)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Which-character-set-modifier-is-in-effect_003f"
accesskey="9">perlre Which character set modifier is in
effect?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Character-set-modifier-behavior-prior-to-Perl-5_002e14">perlre
Character set modifier behavior prior to Perl
5.14</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlre-Overview"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Details-on-some-modifiers" accesskey="n"
rel="next">perlre Details on some modifiers</a>, Up: <a
href="#perlre-Modifiers" accesskey="u" rel="up">perlre Modifiers</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Overview-1"></a>
-<h4 class="subsubsection">58.2.1.1 Overview</h4>
-
-<p>Matching operations can have various modifiers. Modifiers
-that relate to the interpretation of the regular expression inside
-are listed below. Modifiers that alter the way a regular expression
-is used by Perl are detailed in <a
href="#perlop-Regexp-Quote_002dLike-Operators">perlop Regexp Quote-Like
Operators</a> and
-<a href="#perlop-Gory-details-of-parsing-quoted-constructs">perlop Gory
details of parsing quoted constructs</a>.
-</p>
-<dl compact="compact">
-<dt>m</dt>
-<dd><a name="perlre-m"></a>
-<p>Treat string as multiple lines. That is, change "^" and
"$" from matching
-the start of the string’s first line and the end of its last line to
-matching the start and end of each line within the string.
-</p>
-</dd>
-<dt>s</dt>
-<dd><a name="perlre-s"></a>
-<p>Treat string as single line. That is, change "." to match any
character
-whatsoever, even a newline, which normally it would not match.
-</p>
-<p>Used together, as <code>/ms</code>, they let the "." match any
character whatsoever,
-while still allowing "^" and "$" to match, respectively,
just after
-and just before newlines within the string.
-</p>
-</dd>
-<dt>i</dt>
-<dd><a name="perlre-i"></a>
-<p>Do case-insensitive pattern matching.
-</p>
-<p>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
-<a href="#perllocale-NAME">perllocale NAME</a>.
-</p>
-<p>There are a number of Unicode characters that match multiple characters
-under <code>/i</code>. For example, <code>LATIN SMALL LIGATURE FI</code>
-should match the sequence <code>fi</code>. 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
-</p>
-<pre class="verbatim"> "\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!
-</pre>
-<p>Perl doesn’t match multiple characters in a bracketed
-character class unless the character that maps to them is explicitly
-mentioned, and it doesn’t match them at all if the character class is
-inverted, which otherwise could be highly confusing. See
-<a href="#perlrecharclass-Bracketed-Character-Classes">perlrecharclass
Bracketed Character Classes</a>, and
-<a href="#perlrecharclass-Negation">perlrecharclass Negation</a>.
-</p>
-</dd>
-<dt>x</dt>
-<dd><a name="perlre-x"></a>
-<p>Extend your pattern’s legibility by permitting whitespace and
comments.
-Details in <a href="#perlre-_002fx">/x</a>
-</p>
-</dd>
-<dt>p</dt>
-<dd><a name="perlre-p"></a>
-<p>Preserve the string matched such that ${^PREMATCH}, ${^MATCH}, and
-${^POSTMATCH} are available for use after matching.
-</p>
-<p>In Perl 5.20 and higher this is ignored. Due to a new copy-on-write
-mechanism, ${^PREMATCH}, ${^MATCH}, and ${^POSTMATCH} will be available
-after the match regardless of the modifier.
-</p>
-</dd>
-<dt>a, d, l and u</dt>
-<dd><a name="perlre-a_002c-d_002c-l-and-u"></a>
-<p>These modifiers, all new in 5.14, affect which character-set rules
-(Unicode, etc.) are used, as described below in
-<a href="#perlre-Character-set-modifiers">Character set modifiers</a>.
-</p>
-</dd>
-<dt>n</dt>
-<dd><a name="perlre-n"></a>
-<p>Prevent the grouping metacharacters <code>()</code> from capturing. This
modifier,
-new in 5.22, will stop <code>$1</code>, <code>$2</code>, etc... from being
filled in.
-</p>
-<pre class="verbatim"> "hello" =~ /(hi|hello)/; # $1 is
"hello"
- "hello" =~ /(hi|hello)/n; # $1 is undef
-</pre>
-<p>This is equivalent to putting <code>?:</code> at the beginning of every
capturing group:
-</p>
-<pre class="verbatim"> "hello" =~ /(?:hi|hello)/; # $1 is undef
-</pre>
-<p><code>/n</code> can be negated on a per-group basis. Alternatively, named
captures
-may still be used.
-</p>
-<pre class="verbatim"> "hello" =~ /(?-n:(hi|hello))/n; # $1 is
"hello"
- "hello" =~ /(?<greet>hi|hello)/n; # $1 is "hello",
$+{greet} is
- # "hello"
-</pre>
-</dd>
-<dt>Other Modifiers</dt>
-<dd><a name="perlre-Other-Modifiers"></a>
-<p>There are a number of flags that can be found at the end of regular
-expression constructs that are <em>not</em> generic regular expression flags,
but
-apply to the operation being performed, like matching or substitution
(<code>m//</code>
-or <code>s///</code> respectively).
-</p>
-<p>Flags described further in
-<a href="#perlretut-Using-regular-expressions-in-Perl">perlretut Using regular
expressions in Perl</a> are:
-</p>
-<pre class="verbatim"> c - keep the current position during repeated matching
- g - globally match the pattern repeatedly in the string
-</pre>
-<p>Substitution-specific modifiers described in
-</p>
-<p><a href="#perlop-s_002fPATTERN_002fREPLACEMENT_002fmsixpodualngcer">perlop
<code>s/<em>PATTERN</em>/<em>REPLACEMENT</em>/msixpodualngcer</code></a> are:
-</p>
-<pre class="verbatim"> e - evaluate the right-hand side as an expression
- ee - evaluate the right side as a string then eval the result
- o - pretend to optimize your code, but actually introduce bugs
- r - perform non-destructive substitution and return the new value
-</pre>
-</dd>
-</dl>
-
-<p>Regular expression modifiers are usually written in documentation
-as e.g., "the <code>/x</code> modifier", even though the delimiter
-in question might not really be a slash. The modifiers
<code>/imnsxadlup</code>
-may also be embedded within the regular expression itself using
-the <code>(?...)</code> construct, see <a
href="#perlre-Extended-Patterns">Extended Patterns</a> below.
-</p>
-<hr>
-<a name="perlre-Details-on-some-modifiers"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-_002fx" accesskey="n" rel="next">perlre /x</a>,
Previous: <a href="#perlre-Overview" accesskey="p" rel="prev">perlre
Overview</a>, Up: <a href="#perlre-Modifiers" accesskey="u" rel="up">perlre
Modifiers</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Details-on-some-modifiers"></a>
-<h4 class="subsubsection">58.2.1.2 Details on some modifiers</h4>
-
-<p>Some of the modifiers require more explanation than given in the
-<a href="#perlre-Overview">Overview</a> above.
-</p>
-<hr>
-<a name="perlre-_002fx"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Character-set-modifiers" accesskey="n"
rel="next">perlre Character set modifiers</a>, Previous: <a
href="#perlre-Details-on-some-modifiers" accesskey="p" rel="prev">perlre
Details on some modifiers</a>, Up: <a href="#perlre-Modifiers" accesskey="u"
rel="up">perlre Modifiers</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="g_t_002fx"></a>
-<h4 class="subsubsection">58.2.1.3 /x</h4>
-
-<p><code>/x</code> tells
-the regular expression parser to ignore most whitespace that is neither
-backslashed nor within a bracketed character class. You can use this to
-break up your regular expression into (slightly) more readable parts.
-Also, the <code>#</code> character is treated as a metacharacter introducing a
-comment that runs up to the pattern’s closing delimiter, or to the end
-of the current line if the pattern extends onto the next line. Hence,
-this is very much like an ordinary Perl code comment. (You can include
-the closing delimiter within the comment only if you precede it with a
-backslash, so be careful!)
-</p>
-<p>Use of <code>/x</code> means that if you want real
-whitespace or <code>#</code> characters in the pattern (outside a bracketed
character
-class, which is unaffected by <code>/x</code>), then you’ll either have
to
-escape them (using backslashes or <code>\Q...\E</code>) or encode them using
octal,
-hex, or <code>\N{}</code> escapes.
-It is ineffective to try to continue a comment onto the next line by
-escaping the <code>\n</code> with a backslash or <code>\Q</code>.
-</p>
-<p>You can use <a href="#perlre-_0028_003f_0023text_0029">(?#text)</a> to
create a comment that ends earlier than the
-end of the current line, but <code>text</code> also can’t contain the
closing
-delimiter unless escaped with a backslash.
-</p>
-<p>Taken together, these features go a long way towards
-making Perl’s regular expressions more readable. Here’s an
example:
-</p>
-<pre class="verbatim"> # Delete (most) C comments.
- $program =~ s {
- /\* # Match the opening delimiter.
- .*? # Match a minimal number of characters.
- \*/ # Match the closing delimiter.
- } []gsx;
-</pre>
-<p>Note that anything inside
-a <code>\Q...\E</code> stays unaffected by <code>/x</code>. And note that
<code>/x</code> doesn’t affect
-space interpretation within a single multi-character construct. For
-example in <code>\x{...}</code>, regardless of the <code>/x</code> modifier,
there can be no
-spaces. Same for a <a href="#perlre-Quantifiers">quantifier</a> such as
<code>{3}</code> or
-<code>{5,}</code>. Similarly, <code>(?:...)</code> can’t have a space
between the <code>(</code>,
-<code>?</code>, and <code>:</code>. Within any delimiters for such a
-construct, allowed spaces are not affected by <code>/x</code>, and depend on
the
-construct. For example, <code>\x{...}</code> can’t have spaces because
hexadecimal
-numbers don’t have spaces in them. But, Unicode properties can have
spaces, so
-in <code>\p{...}</code> there can be spaces that follow the Unicode rules, for
which see
-<a
href="perluniprops.html#Properties-accessible-through-_005cp_007b_007d-and-_005cP_007b_007d">(perluniprops)Properties
accessible through \p{} and \P{}</a>.
-</p>
-<p>The set of characters that are deemed whitespace are those that Unicode
-calls "Pattern White Space", namely:
-</p>
-<pre class="verbatim"> U+0009 CHARACTER TABULATION
- U+000A LINE FEED
- U+000B LINE TABULATION
- U+000C FORM FEED
- U+000D CARRIAGE RETURN
- U+0020 SPACE
- U+0085 NEXT LINE
- U+200E LEFT-TO-RIGHT MARK
- U+200F RIGHT-TO-LEFT MARK
- U+2028 LINE SEPARATOR
- U+2029 PARAGRAPH SEPARATOR
-</pre>
-<hr>
-<a name="perlre-Character-set-modifiers"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-_002fl" accesskey="n" rel="next">perlre /l</a>,
Previous: <a href="#perlre-_002fx" accesskey="p" rel="prev">perlre /x</a>, Up:
<a href="#perlre-Modifiers" accesskey="u" rel="up">perlre Modifiers</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Character-set-modifiers"></a>
-<h4 class="subsubsection">58.2.1.4 Character set modifiers</h4>
-
-<p><code>/d</code>, <code>/u</code>, <code>/a</code>, and <code>/l</code>,
available starting in 5.14, are called
-the character set modifiers; they affect the character set rules
-used for the regular expression.
-</p>
-<p>The <code>/d</code>, <code>/u</code>, and <code>/l</code> modifiers are not
likely to be of much use
-to you, and so you need not worry about them very much. They exist for
-Perl’s internal use, so that complex regular expression data structures
-can be automatically serialized and later exactly reconstituted,
-including all their nuances. But, since Perl can’t keep a secret, and
-there may be rare instances where they are useful, they are documented
-here.
-</p>
-<p>The <code>/a</code> modifier, on the other hand, may be useful. Its
purpose is to
-allow code that is to work mostly on ASCII data to not have to concern
-itself with Unicode.
-</p>
-<p>Briefly, <code>/l</code> sets the character set to that of whatever
<strong>L</strong>ocale is in
-effect at the time of the execution of the pattern match.
-</p>
-<p><code>/u</code> sets the character set to <strong>U</strong>nicode.
-</p>
-<p><code>/a</code> also sets the character set to Unicode, BUT adds several
-restrictions for <strong>A</strong>SCII-safe matching.
-</p>
-<p><code>/d</code> is the old, problematic, pre-5.14 <strong>D</strong>efault
character set
-behavior. Its only use is to force that old behavior.
-</p>
-<p>At any given time, exactly one of these modifiers is in effect. Their
-existence allows Perl to keep the originally compiled behavior of a
-regular expression, regardless of what rules are in effect when it is
-actually executed. And if it is interpolated into a larger regex, the
-original’s rules continue to apply to it, and only it.
-</p>
-<p>The <code>/l</code> and <code>/u</code> modifiers are automatically
selected for
-regular expressions compiled within the scope of various pragmas,
-and we recommend that in general, you use those pragmas instead of
-specifying these modifiers explicitly. For one thing, the modifiers
-affect only pattern matching, and do not extend to even any replacement
-done, whereas using the pragmas give consistent results for all
-appropriate operations within their scopes. For example,
-</p>
-<pre class="verbatim"> s/foo/\Ubar/il
-</pre>
-<p>will match "foo" using the locale’s rules for
case-insensitive matching,
-but the <code>/l</code> does not affect how the <code>\U</code> operates.
Most likely you
-want both of them to use locale rules. To do this, instead compile the
-regular expression within the scope of <code>use locale</code>. This both
-implicitly adds the <code>/l</code>, and applies locale rules to the
<code>\U</code>. The
-lesson is to <code>use locale</code>, and not <code>/l</code> explicitly.
-</p>
-<p>Similarly, it would be better to use <code>use feature
'unicode_strings'</code>
-instead of,
-</p>
-<pre class="verbatim"> s/foo/\Lbar/iu
-</pre>
-<p>to get Unicode rules, as the <code>\L</code> in the former (but not
necessarily
-the latter) would also use Unicode rules.
-</p>
-<p>More detail on each of the modifiers follows. Most likely you don’t
-need to know this detail for <code>/l</code>, <code>/u</code>, and
<code>/d</code>, and can skip ahead
-to <a href="#perlre-_002fa-_0028and-_002faa_0029">/a</a>.
-</p>
-<hr>
-<a name="perlre-_002fl"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-_002fu" accesskey="n" rel="next">perlre /u</a>,
Previous: <a href="#perlre-Character-set-modifiers" accesskey="p"
rel="prev">perlre Character set modifiers</a>, Up: <a href="#perlre-Modifiers"
accesskey="u" rel="up">perlre Modifiers</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="g_t_002fl"></a>
-<h4 class="subsubsection">58.2.1.5 /l</h4>
-
-<p>means to use the current locale’s rules (see <a
href="#perllocale-NAME">perllocale NAME</a>) when pattern
-matching. For example, <code>\w</code> will match the "word"
characters of that
-locale, and <code>"/i"</code> 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
-<a href="#perllocale-The-setlocale-function">setlocale() function</a>.
-</p>
-<p>The only non-single-byte locale Perl supports is (starting in v5.20)
-UTF-8. This means that code points above 255 are treated as Unicode no
-matter what locale is in effect (since UTF-8 implies Unicode).
-</p>
-<p>Under Unicode rules, there are a few case-insensitive matches that cross
-the 255/256 boundary. Except for UTF-8 locales in Perls v5.20 and
-later, these are disallowed under <code>/l</code>. For example, 0xFF (on ASCII
-platforms) does not caselessly match the character at 0x178, <code>LATIN
-CAPITAL LETTER Y WITH DIAERESIS</code>, because 0xFF may not be <code>LATIN
SMALL
-LETTER Y WITH DIAERESIS</code> 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.
-</p>
-<p>In a UTF-8 locale in v5.20 and later, the only visible difference
-between locale and non-locale in regular expressions should be tainting
-(see <a href="#perlsec-NAME">perlsec NAME</a>).
-</p>
-<p>This modifier may be specified to be the default by <code>use
locale</code>, but
-see <a href="#perlre-Which-character-set-modifier-is-in-effect_003f">Which
character set modifier is in effect?</a>.
-</p>
-<hr>
-<a name="perlre-_002fu"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-_002fd" accesskey="n" rel="next">perlre /d</a>,
Previous: <a href="#perlre-_002fl" accesskey="p" rel="prev">perlre /l</a>, Up:
<a href="#perlre-Modifiers" accesskey="u" rel="up">perlre Modifiers</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="g_t_002fu"></a>
-<h4 class="subsubsection">58.2.1.6 /u</h4>
-
-<p>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).
-(Otherwise Perl considers their meanings to be undefined.) Thus,
-under this modifier, the ASCII platform effectively becomes a Unicode
-platform; and hence, for example, <code>\w</code> will match any of the more
than
-100_000 word characters in Unicode.
-</p>
-<p>Unlike most locales, which are specific to a language and country pair,
-Unicode classifies all the characters that are letters <em>somewhere</em> in
-the world as
-<code>\w</code>. For example, your locale might not think that <code>LATIN
SMALL
-LETTER ETH</code> 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 <code>\d</code>; 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,
-<code>BENGALI DIGIT FOUR</code> (U+09EA) looks very much like an
-<code>ASCII DIGIT EIGHT</code> (U+0038). And, <code>\d+</code>, may match
strings of digits
-that are a mixture from different writing systems, creating a security
-issue. <a href="Unicode-UCD.html#num_0028_0029">(Unicode-UCD)num()</a> can be
used to sort
-this out. Or the <code>/a</code> modifier can be used to force
<code>\d</code> to match
-just the ASCII 0 through 9.
-</p>
-<p>Also, under this modifier, case-insensitive matching works on the full
-set of Unicode
-characters. The <code>KELVIN SIGN</code>, for example matches the letters
"k" and
-"K"; and <code>LATIN SMALL LIGATURE FF</code> matches the sequence
"ff", which,
-if you’re not prepared, might make it look like a hexadecimal constant,
-presenting another potential security issue. See
-<a href="http://unicode.org/reports/tr36";>http://unicode.org/reports/tr36</a>
for a detailed discussion of Unicode
-security issues.
-</p>
-<p>This modifier may be specified to be the default by <code>use feature
-'unicode_strings</code>, <code>use locale ':not_characters'</code>, or
-<code><a href="#perlfunc-use-VERSION">use 5.012</a></code> (or higher),
-but see <a href="#perlre-Which-character-set-modifier-is-in-effect_003f">Which
character set modifier is in effect?</a>.
-</p>
-<hr>
-<a name="perlre-_002fd"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-_002fa-_0028and-_002faa_0029" accesskey="n"
rel="next">perlre /a (and /aa)</a>, Previous: <a href="#perlre-_002fu"
accesskey="p" rel="prev">perlre /u</a>, Up: <a href="#perlre-Modifiers"
accesskey="u" rel="up">perlre Modifiers</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="g_t_002fd"></a>
-<h4 class="subsubsection">58.2.1.7 /d</h4>
-
-<p>This modifier means to use the "Default" native rules of the
platform
-except when there is cause to use Unicode rules instead, as follows:
-</p>
-<ol>
-<li> the target string is encoded in UTF-8; or
-
-</li><li> the pattern is encoded in UTF-8; or
-
-</li><li> the pattern explicitly mentions a code point that is above 255 (say
by
-<code>\x{100}</code>); or
-
-</li><li> the pattern uses a Unicode name (<code>\N{...}</code>); or
-
-</li><li> the pattern uses a Unicode property (<code>\p{...}</code> or
<code>\P{...}</code>); or
-
-</li><li> the pattern uses a Unicode break (<code>\b{...}</code> or
<code>\B{...}</code>); or
-
-</li><li> the pattern uses <a href="#perlre-_0028_003f_005b-_005d_0029">(?[
])</a>
-
-</li></ol>
-
-<p>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 <a href="#perlunicode-The-_0022Unicode-Bug_0022">perlunicode The
"Unicode Bug"</a>. The Unicode Bug has
-become rather infamous, leading to yet another (printable) name for this
-modifier, "Dodgy".
-</p>
-<p>Unless the pattern or string are encoded in UTF-8, only ASCII characters
-can match positively.
-</p>
-<p>Here are some examples of how that works on an ASCII platform:
-</p>
-<pre class="verbatim"> $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.
-</pre>
-<p>This modifier is automatically selected by default when none of the
-others are, so yet another name for it is "Default".
-</p>
-<p>Because of the unexpected behaviors associated with this modifier, you
-probably should only use it to maintain weird backward compatibilities.
-</p>
-<hr>
-<a name="perlre-_002fa-_0028and-_002faa_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Which-character-set-modifier-is-in-effect_003f"
accesskey="n" rel="next">perlre Which character set modifier is in effect?</a>,
Previous: <a href="#perlre-_002fd" accesskey="p" rel="prev">perlre /d</a>, Up:
<a href="#perlre-Modifiers" accesskey="u" rel="up">perlre Modifiers</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="g_t_002fa-_0028and-_002faa_0029"></a>
-<h4 class="subsubsection">58.2.1.8 /a (and /aa)</h4>
-
-<p>This modifier stands for ASCII-restrict (or ASCII-safe). This modifier,
-unlike the others, may be doubled-up to increase its effect.
-</p>
-<p>When it appears singly, it causes the sequences <code>\d</code>,
<code>\s</code>, <code>\w</code>, and
-the Posix character classes to match only in the ASCII range. They thus
-revert to their pre-5.6, pre-Unicode meanings. Under <code>/a</code>,
<code>\d</code>
-always means precisely the digits <code>"0"</code> to
<code>"9"</code>; <code>\s</code> means the five
-characters <code>[ \f\n\r\t]</code>, and starting in Perl v5.18, the vertical
tab;
-<code>\w</code> means the 63 characters
-<code>[A-Za-z0-9_]</code>; and likewise, all the Posix classes such as
-<code>[[:print:]]</code> match only the appropriate ASCII-range characters.
-</p>
-<p>This modifier is useful for people who only incidentally use Unicode,
-and who do not wish to be burdened with its complexities and security
-concerns.
-</p>
-<p>With <code>/a</code>, one can write <code>\d</code> with confidence that it
will only match
-ASCII characters, and should the need arise to match beyond ASCII, you
-can instead use <code>\p{Digit}</code> (or <code>\p{Word}</code> for
<code>\w</code>). There are
-similar <code>\p{...}</code> constructs that can match beyond ASCII both white
-space (see <a href="#perlrecharclass-Whitespace">perlrecharclass
Whitespace</a>), and Posix classes (see
-<a href="#perlrecharclass-POSIX-Character-Classes">perlrecharclass POSIX
Character Classes</a>). Thus, this modifier
-doesn’t mean you can’t use Unicode, it means that to get Unicode
-matching you must explicitly use a construct (<code>\p{}</code>,
<code>\P{}</code>) that
-signals Unicode.
-</p>
-<p>As you would expect, this modifier causes, for example, <code>\D</code> to
mean
-the same thing as <code>[^0-9]</code>; in fact, all non-ASCII characters match
-<code>\D</code>, <code>\S</code>, and <code>\W</code>. <code>\b</code> still
means to match at the boundary
-between <code>\w</code> and <code>\W</code>, using the <code>/a</code>
definitions of them (similarly
-for <code>\B</code>).
-</p>
-<p>Otherwise, <code>/a</code> behaves like the <code>/u</code> modifier, in
that
-case-insensitive matching uses Unicode rules; for example, "k" will
-match the Unicode <code>\N{KELVIN SIGN}</code> under <code>/i</code> matching,
and code
-points in the Latin1 range, above ASCII will have Unicode rules when it
-comes to case-insensitive matching.
-</p>
-<p>To forbid ASCII/non-ASCII matches (like "k" with <code>\N{KELVIN
SIGN}</code>),
-specify the "a" twice, for example <code>/aai</code> or
<code>/aia</code>. (The first
-occurrence of "a" restricts the <code>\d</code>, etc., and the
second occurrence
-adds the <code>/i</code> restrictions.) But, note that code points outside the
-ASCII range will use Unicode rules for <code>/i</code> matching, so the
modifier
-doesn’t really restrict things to just ASCII; it just forbids the
-intermixing of ASCII and non-ASCII.
-</p>
-<p>To summarize, this modifier provides protection for applications that
-don’t wish to be exposed to all of Unicode. Specifying it twice
-gives added protection.
-</p>
-<p>This modifier may be specified to be the default by <code>use re '/a'</code>
-or <code>use re '/aa'</code>. If you do so, you may actually have occasion to
use
-the <code>/u</code> modifier explicitly if there are a few regular expressions
-where you do want full Unicode rules (but even here, it’s best if
-everything were under feature <code>"unicode_strings"</code>, along
with the
-<code>use re '/aa'</code>). Also see <a
href="#perlre-Which-character-set-modifier-is-in-effect_003f">Which character
set modifier is in
-effect?</a>.
-</p>
-<hr>
-<a name="perlre-Which-character-set-modifier-is-in-effect_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Character-set-modifier-behavior-prior-to-Perl-5_002e14"
accesskey="n" rel="next">perlre Character set modifier behavior prior to Perl
5.14</a>, Previous: <a href="#perlre-_002fa-_0028and-_002faa_0029"
accesskey="p" rel="prev">perlre /a (and /aa)</a>, Up: <a
href="#perlre-Modifiers" accesskey="u" rel="up">perlre Modifiers</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Which-character-set-modifier-is-in-effect_003f"></a>
-<h4 class="subsubsection">58.2.1.9 Which character set modifier is in
effect?</h4>
-
-<p>Which of these modifiers is in effect at any given point in a regular
-expression depends on a fairly complex set of interactions. These have
-been designed so that in general you don’t have to worry about it, but
-this section gives the gory details. As
-explained below in <a href="#perlre-Extended-Patterns">Extended Patterns</a>
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.
-</p>
-<p>The <code><a href="re.html#g_t_0027_002fflags_0027-mode">(re)use re
'/foo'</a></code> 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 also change the defaults.
-</p>
-<p>Otherwise, <code><a href="#perllocale-NAME">use locale</a></code> sets the
default modifier to <code>/l</code>;
-and <code><a href="feature.html#Top">(feature)use feature
'unicode_strings</a></code>, or
-<code><a href="#perlfunc-use-VERSION">use 5.012</a></code> (or higher) set the
default to
-<code>/u</code> when not in the same scope as either <code><a
href="#perllocale-NAME">use locale</a></code>
-or <code><a href="bytes.html#Top">(bytes)use bytes</a></code>.
-(<code><a href="#perllocale-Unicode-and-UTF_002d8">use locale
':not_characters'</a></code> also
-sets the default to <code>/u</code>, overriding any plain <code>use
locale</code>.)
-Unlike the mechanisms mentioned above, these
-affect operations besides regular expressions pattern matching, and so
-give more consistent results with other operators, including using
-<code>\U</code>, <code>\l</code>, etc. in substitution replacements.
-</p>
-<p>If none of the above apply, for backwards compatibility reasons, the
-<code>/d</code> 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.
-</p>
-<hr>
-<a name="perlre-Character-set-modifier-behavior-prior-to-Perl-5_002e14"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlre-Which-character-set-modifier-is-in-effect_003f"
accesskey="p" rel="prev">perlre Which character set modifier is in effect?</a>,
Up: <a href="#perlre-Modifiers" accesskey="u" rel="up">perlre Modifiers</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Character-set-modifier-behavior-prior-to-Perl-5_002e14"></a>
-<h4 class="subsubsection">58.2.1.10 Character set modifier behavior prior to
Perl 5.14</h4>
-
-<p>Prior to 5.14, there were no explicit modifiers, but <code>/l</code> was
implied
-for regexes compiled within the scope of <code>use locale</code>, and
<code>/d</code> 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 <code>/d</code> modifier, where Unicode rules
-would be used when inappropriate, and vice versa. <code>\p{}</code> did not
imply
-Unicode rules, and neither did all occurrences of <code>\N{}</code>, until
5.12.
-</p>
-<hr>
-<a name="perlre-Regular-Expressions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Quoting-metacharacters" accesskey="n" rel="next">perlre
Quoting metacharacters</a>, Previous: <a href="#perlre-Modifiers" accesskey="p"
rel="prev">perlre Modifiers</a>, Up: <a href="#perlre-DESCRIPTION"
accesskey="u" rel="up">perlre DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Regular-Expressions"></a>
-<h4 class="subsection">58.2.2 Regular Expressions</h4>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlre-Metacharacters"
accesskey="1">perlre Metacharacters</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-Quantifiers"
accesskey="2">perlre Quantifiers</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-Escape-sequences"
accesskey="3">perlre Escape sequences</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlre-Character-Classes-and-other-Special-Escapes" accesskey="4">perlre
Character Classes and other Special Escapes</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-Assertions"
accesskey="5">perlre Assertions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlre-Capture-groups"
accesskey="6">perlre Capture groups</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlre-Metacharacters"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Quantifiers" accesskey="n" rel="next">perlre
Quantifiers</a>, Up: <a href="#perlre-Regular-Expressions" accesskey="u"
rel="up">perlre Regular Expressions</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Metacharacters"></a>
-<h4 class="subsubsection">58.2.2.1 Metacharacters</h4>
-
-<p>The patterns used in Perl pattern matching evolved from those supplied in
-the Version 8 regex routines. (The routines are derived
-(distantly) from Henry Spencer’s freely redistributable reimplementation
-of the V8 routines.) See <a
href="#perlre-Version-8-Regular-Expressions">Version 8 Regular Expressions</a>
for
-details.
-</p>
-<p>In particular the following metacharacters have their standard
<em>egrep</em>-ish
-meanings:
-</p>
-<pre class="verbatim"> \ Quote the next metacharacter
- ^ Match the beginning of the line
- . Match any character (except newline)
- $ Match the end of the string (or before newline at the end
- of the string)
- | Alternation
- () Grouping
- [] Bracketed Character class
-</pre>
-<p>By default, the "^" character is guaranteed to match only the
-beginning of the string, the "$" character only the end (or before
the
-newline at the end), and Perl does certain optimizations with the
-assumption that the string contains only one line. Embedded newlines
-will not be matched by "^" or "$". You may, however, wish
to treat a
-string as a multi-line buffer, such that the "^" will match after any
-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
<code>$*</code>,
-but this option was removed in perl 5.10.)
-</p>
-<p>To simplify multi-line substitutions, the "." character never
matches a
-newline unless you use the <code>/s</code> modifier, which in effect tells
Perl to pretend
-the string is a single line–even if it isn’t.
-</p>
-<hr>
-<a name="perlre-Quantifiers"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Escape-sequences" accesskey="n" rel="next">perlre
Escape sequences</a>, Previous: <a href="#perlre-Metacharacters" accesskey="p"
rel="prev">perlre Metacharacters</a>, Up: <a href="#perlre-Regular-Expressions"
accesskey="u" rel="up">perlre Regular Expressions</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Quantifiers"></a>
-<h4 class="subsubsection">58.2.2.2 Quantifiers</h4>
-
-<p>The following standard quantifiers are recognized:
-</p>
-<pre class="verbatim"> * 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
-</pre>
-<p>(If a curly bracket occurs in any other context and does not form part of
-a backslashed sequence like <code>\x{...}</code>, it is treated as a regular
-character. However, a deprecation warning is raised for all such
-occurrences, and in Perl v5.26, literal uses of a curly bracket will be
-required to be escaped, say by preceding them with a backslash
(<code>"\{"</code>)
-or enclosing them within square brackets (<code>"[{]"</code>).
This change will
-allow for future syntax extensions (like making the lower bound of a
-quantifier optional), and better error checking of quantifiers.)
-</p>
-<p>The "*" quantifier is equivalent to <code>{0,}</code>, the
"+"
-quantifier to <code>{1,}</code>, and the "?" quantifier to
<code>{0,1}</code>. n and m are limited
-to non-negative integral values less than a preset limit defined when perl is
built.
-This is usually 32766 on the most common platforms. The actual limit can
-be seen in the error message generated by code such as this:
-</p>
-<pre class="verbatim"> $_ **= $_ , / {$_} / for 2 .. 42;
-</pre>
-<p>By default, a quantified subpattern is "greedy", that is, it will
match as
-many times as possible (given a particular starting location) while still
-allowing the rest of the pattern to match. If you want it to match the
-minimum number of times possible, follow the quantifier with a "?".
Note
-that the meanings don’t change, just the "greediness":
-</p>
-<pre class="verbatim"> *? 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
-</pre>
-<p>Normally 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.
-</p>
-<pre class="verbatim"> *+ 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
-</pre>
-<p>For instance,
-</p>
-<pre class="verbatim"> 'aaaa' =~ /a++a/
-</pre>
-<p>will never match, as the <code>a++</code> will gobble up all the
<code>a</code>’s in the
-string and won’t leave any for the remaining part of the pattern. This
-feature can be extremely useful to give perl hints about where it
-shouldn’t backtrack. For instance, the typical "match a
double-quoted
-string" problem can be most efficiently performed when written as:
-</p>
-<pre class="verbatim"> /"(?:[^"\\]++|\\.)*+"/
-</pre>
-<p>as we know that if the final quote does not match, backtracking will not
-help. See the independent subexpression
-<a href="#perlre-_0028_003f_003epattern_0029">(?>pattern)</a> for more
details;
-possessive quantifiers are just syntactic sugar for that construct. For
-instance the above example could also be written as follows:
-</p>
-<pre class="verbatim"> /"(?>(?:(?>[^"\\]+)|\\.)*)"/
-</pre>
-<p>Note that the possessive quantifier modifier can not be be combined
-with the non-greedy modifier. This is because it would make no sense.
-Consider the follow equivalency table:
-</p>
-<pre class="verbatim"> Illegal Legal
- ------------ ------
- X??+ X{0}
- X+?+ X{1}
- X{min,max}?+ X{min}
-</pre>
-<hr>
-<a name="perlre-Escape-sequences"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Character-Classes-and-other-Special-Escapes"
accesskey="n" rel="next">perlre Character Classes and other Special
Escapes</a>, Previous: <a href="#perlre-Quantifiers" accesskey="p"
rel="prev">perlre Quantifiers</a>, Up: <a href="#perlre-Regular-Expressions"
accesskey="u" rel="up">perlre Regular Expressions</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Escape-sequences"></a>
-<h4 class="subsubsection">58.2.2.3 Escape sequences</h4>
-
-<p>Because patterns are processed as double-quoted strings, the following
-also work:
-</p>
-<pre class="verbatim"> \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 until \E (think vi)
- \U uppercase until \E (think vi)
- \Q quote (disable) pattern metacharacters until \E
- \E end either case modification or quoted section, think vi
-</pre>
-<p>Details are in <a href="#perlop-Quote-and-Quote_002dlike-Operators">perlop
Quote and Quote-like Operators</a>.
-</p>
-<hr>
-<a name="perlre-Character-Classes-and-other-Special-Escapes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Assertions" accesskey="n" rel="next">perlre
Assertions</a>, Previous: <a href="#perlre-Escape-sequences" accesskey="p"
rel="prev">perlre Escape sequences</a>, Up: <a
href="#perlre-Regular-Expressions" accesskey="u" rel="up">perlre Regular
Expressions</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Character-Classes-and-other-Special-Escapes"></a>
-<h4 class="subsubsection">58.2.2.4 Character Classes and other Special
Escapes</h4>
-
-<p>In addition, Perl defines the following:
-</p>
-<pre class="verbatim"> 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.
- (?[...]) [8] Extended bracketed character class
- \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. (Deprecated.)
- \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. 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
-</pre>
-<dl compact="compact">
-<dt>[1]</dt>
-<dd><a name="perlre-_005b1_005d"></a>
-<p>See <a href="#perlrecharclass-Bracketed-Character-Classes">perlrecharclass
Bracketed Character Classes</a> for details.
-</p>
-</dd>
-<dt>[2]</dt>
-<dd><a name="perlre-_005b2_005d"></a>
-<p>See <a href="#perlrecharclass-POSIX-Character-Classes">perlrecharclass
POSIX Character Classes</a> for details.
-</p>
-</dd>
-<dt>[3]</dt>
-<dd><a name="perlre-_005b3_005d"></a>
-<p>See <a href="#perlrecharclass-Backslash-sequences">perlrecharclass
Backslash sequences</a> for details.
-</p>
-</dd>
-<dt>[4]</dt>
-<dd><a name="perlre-_005b4_005d"></a>
-<p>See <a href="#perlrebackslash-Misc">perlrebackslash Misc</a> for details.
-</p>
-</dd>
-<dt>[5]</dt>
-<dd><a name="perlre-_005b5_005d"></a>
-<p>See <a href="#perlre-Capture-groups">Capture groups</a> below for details.
-</p>
-</dd>
-<dt>[6]</dt>
-<dd><a name="perlre-_005b6_005d"></a>
-<p>See <a href="#perlre-Extended-Patterns">Extended Patterns</a> below for
details.
-</p>
-</dd>
-<dt>[7]</dt>
-<dd><a name="perlre-_005b7_005d"></a>
-<p>Note that <code>\N</code> has two meanings. When of the form
<code>\N{NAME}</code>, it matches the
-character or character sequence whose name is <code>NAME</code>; and similarly
-when of the form <code>\N{U+<em>hex</em>}</code>, it matches the character
whose Unicode
-code point is <em>hex</em>. Otherwise it matches any character but
<code>\n</code>.
-</p>
-</dd>
-<dt>[8]</dt>
-<dd><a name="perlre-_005b8_005d"></a>
-<p>See <a
href="#perlrecharclass-Extended-Bracketed-Character-Classes">perlrecharclass
Extended Bracketed Character Classes</a> for details.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlre-Assertions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Capture-groups" accesskey="n" rel="next">perlre Capture
groups</a>, Previous: <a
href="#perlre-Character-Classes-and-other-Special-Escapes" accesskey="p"
rel="prev">perlre Character Classes and other Special Escapes</a>, Up: <a
href="#perlre-Regular-Expressions" accesskey="u" rel="up">perlre Regular
Expressions</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Assertions"></a>
-<h4 class="subsubsection">58.2.2.5 Assertions</h4>
-
-<p>Perl defines the following zero-width assertions:
-</p>
-<pre class="verbatim"> \b{} Match at Unicode boundary of specified type
- \B{} Match where corresponding \b{} doesn't match
- \b Match a word boundary
- \B Match except at a word boundary
- \A Match only at beginning of string
- \Z Match only at end of string, or before newline at the end
- \z Match only at end of string
- \G Match only at pos() (e.g. at the end-of-match position
- of prior m//g)
-</pre>
-<p>A Unicode boundary (<code>\b{}</code>), available starting in v5.22, is a
spot
-between two characters, or before the first character in the string, or
-after the final character in the string where certain criteria defined
-by Unicode are met. See <a
href="#perlrebackslash-_005cb_007b_007d_002c-_005cb_002c-_005cB_007b_007d_002c-_005cB">perlrebackslash
\b{}, \b, \B{}, \B</a> for
-details.
-</p>
-<p>A word boundary (<code>\b</code>) is a spot between two characters
-that has a <code>\w</code> on one side of it and a <code>\W</code> on the
other side
-of it (in either order), counting the imaginary characters off the
-beginning and end of the string as matching a <code>\W</code>. (Within
-character classes <code>\b</code> represents backspace rather than a word
-boundary, just as it normally does in any double-quoted string.)
-The <code>\A</code> and <code>\Z</code> are just like "^" and
"$", except that they
-won’t match multiple times when the <code>/m</code> modifier is used,
while
-"^" and "$" will match at every internal line boundary.
To match
-the actual end of the string and not ignore an optional trailing
-newline, use <code>\z</code>.
-</p>
-<p>The <code>\G</code> assertion can be used to chain global matches (using
-<code>m//g</code>), as described in <a
href="#perlop-Regexp-Quote_002dLike-Operators">perlop Regexp Quote-Like
Operators</a>.
-It is also useful when writing <code>lex</code>-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
-where <code>\G</code> will match can also be influenced by using
<code>pos()</code> as
-an lvalue: see <a href="#perlfunc-pos">perlfunc pos</a>. Note that the rule
for zero-length
-matches (see <a
href="#perlre-Repeated-Patterns-Matching-a-Zero_002dlength-Substring">Repeated
Patterns Matching a Zero-length Substring</a>)
-is modified somewhat, in that contents to the left of <code>\G</code> are
-not counted when determining the length of the match. Thus the following
-will not match forever:
-</p>
-<pre class="verbatim"> my $string = 'ABC';
- pos($string) = 1;
- while ($string =~ /(.\G)/g) {
- print $1;
- }
-</pre>
-<p>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
-row.
-</p>
-<p>It is worth noting that <code>\G</code> improperly used can result in an
infinite
-loop. Take care when using patterns that include <code>\G</code> in an
alternation.
-</p>
-<p>Note also that <code>s///</code> will refuse to overwrite part of a
substitution
-that has already been replaced; so for example this will stop after the
-first iteration, rather than iterating its way backwards through the
-string:
-</p>
-<pre class="verbatim"> $_ = "123456789";
- pos = 6;
- s/.(?=.\G)/X/g;
- print; # prints 1234X6789, not XXXXX6789
-</pre>
-<hr>
-<a name="perlre-Capture-groups"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlre-Assertions" accesskey="p" rel="prev">perlre
Assertions</a>, Up: <a href="#perlre-Regular-Expressions" accesskey="u"
rel="up">perlre Regular Expressions</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Capture-groups"></a>
-<h4 class="subsubsection">58.2.2.6 Capture groups</h4>
-
-<p>The bracketing construct <code>( ... )</code> 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 <code>\g1</code> (or <code>\g{1}</code>) for the first,
<code>\g2</code> (or <code>\g{2}</code>)
-for the second, and so on.
-This is called a <em>backreference</em>.
-</p>
-<pre class="verbatim"> >>
-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.
-</pre>
-<p>You can also refer to capture groups relatively, by using a negative
number, so
-that <code>\g-1</code> and <code>\g{-1}</code> both refer to the immediately
preceding capture
-group, and <code>\g-2</code> and <code>\g{-2}</code> both refer to the group
before it. For
-example:
-</p>
-<pre class="verbatim"> /
- (Y) # group 1
- ( # group 2
- (X) # group 3
- \g{-1} # backref to group 3
- \g{-3} # backref to group 1
- )
- /x
-</pre>
-<p>would match the same as <code>/(Y) ( (X) \g3 \g1 )/x</code>. This allows
you to
-interpolate regexes into larger regexes and not have to worry about the
-capture groups being renumbered.
-</p>
-<p>You can dispense with numbers altogether and create named capture groups.
-The notation is <code>(?<<em>name</em>>...)</code> to declare and
<code>\g{<em>name</em>}</code> to
-reference. (To be compatible with .Net regular expressions,
<code>\g{<em>name</em>}</code> may
-also be written as <code>\k{<em>name</em>}</code>,
<code>\k<<em>name</em>></code> or <code>\k'<em>name</em>'</code>.)
-<em>name</em> 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 <code>(??{})</code>.)
-</p>
-<p>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 <a
href="#perlsyn-Compound-Statements">perlsyn Compound Statements</a>.)
-You can refer to them by absolute number (using <code>"$1"</code>
instead of <code>"\g1"</code>,
-etc); or by name via the <code>%+</code> hash, using
<code>"$+{<em>name</em>}"</code>.
-</p>
-<p>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 <code>qr/$a$b/</code>,
and <code>$a</code>
-contained <code>"\g1"</code>, and <code>$b</code> contained
<code>"37"</code>, you would get <code>/\g137/</code> which
-is probably not what you intended.
-</p>
-<p>The <code>\g</code> and <code>\k</code> 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 <code>\1</code>,
-<code>\2</code>, 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 <code>\10</code> 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 <code>\10</code> as a
backreference
-only if at least 10 left parentheses have opened before it. Likewise
<code>\11</code> is
-a backreference only if at least 11 left parentheses have opened before it.
-And so on. <code>\1</code> through <code>\9</code> are always interpreted as
backreferences.
-There are several examples below that illustrate these perils. You can avoid
-the ambiguity by always using <code>\g{}</code> or <code>\g</code> if you mean
capturing groups;
-and for octal constants always using <code>\o{}</code>, or for
<code>\077</code> and below, using 3
-digits padded with leading zeros, since a leading zero implies an octal
-constant.
-</p>
-<p>The <code>\<em>digit</em></code> notation also works in certain
circumstances outside
-the pattern. See <a
href="#perlre-Warning-on-_005c1-Instead-of-_00241">Warning on \1 Instead of
$1</a> below for details.
-</p>
-<p>Examples:
-</p>
-<pre class="verbatim"> s/^([^ ]*) *([^ ]*)/$2 $1/; # swap first two
words
-
- /(.)\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'.)\g1/ # ... mix and match
- and print "'$1' is the first doubled character\n";
-
- if (/Time: (..):(..):(..)/) { # parse out values
- $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
-</pre>
-<p>Several special variables also refer back to portions of the previous
-match. <code>$+</code> returns whatever the last bracket match matched.
-<code>$&</code> returns the entire matched string. (At one point
<code>$0</code> did
-also, but now it returns the name of the program.) <code>$`</code> returns
-everything before the matched string. <code>$'</code> returns everything
-after the matched string. And <code>$^N</code> contains whatever was matched by
-the most-recently closed group (submatch). <code>$^N</code> can be used in
-extended patterns (see below), for example to assign a submatch to a
-variable.
-</p>
-<p>These special variables, like the <code>%+</code> hash and the numbered
match variables
-(<code>$1</code>, <code>$2</code>, <code>$3</code>, etc.) are dynamically
scoped
-until the end of the enclosing block or until the next successful
-match, whichever comes first. (See <a
href="#perlsyn-Compound-Statements">perlsyn Compound Statements</a>.)
-</p>
-<p><strong>NOTE</strong>: 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.
-</p>
-<p><strong>WARNING</strong>: If your code is to run on Perl 5.16 or earlier,
-beware that once Perl sees that you need one of <code>$&</code>,
<code>$`</code>, or
-<code>$'</code> anywhere in the program, it has to provide them for every
-pattern match. This may substantially slow your program.
-</p>
-<p>Perl uses the same mechanism to produce <code>$1</code>, <code>$2</code>,
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 <code>(?: ... )</code> instead.) But if you never
-use <code>$&</code>, <code>$`</code> or <code>$'</code>, then patterns
<em>without</em> capturing
-parentheses will not be penalized. So avoid <code>$&</code>,
<code>$'</code>, and <code>$`</code>
-if you can, but if you can’t (and some algorithms really appreciate
-them), once you’ve used them once, use them at will, because you’ve
-already paid the price.
-</p>
-<p>Perl 5.16 introduced a slightly more efficient mechanism that notes
-separately whether each of <code>$`</code>, <code>$&</code>, and
<code>$'</code> have been seen, and
-thus may only need to copy part of the string. Perl 5.20 introduced a
-much more efficient copy-on-write mechanism which eliminates any slowdown.
-</p>
-<p>As another workaround for this problem, Perl 5.10.0 introduced
<code>${^PREMATCH}</code>,
-<code>${^MATCH}</code> and <code>${^POSTMATCH}</code>, which are equivalent to
<code>$`</code>, <code>$&</code>
-and <code>$'</code>, <strong>except</strong> that they are only guaranteed to
be defined after a
-successful match that was executed with the <code>/p</code> (preserve)
modifier.
-The use of these variables incurs no global performance penalty, unlike
-their punctuation char equivalents, however at the trade-off that you
-have to tell perl when you want to use them. As of Perl 5.20, these three
-variables are equivalent to <code>$`</code>, <code>$&</code> and
<code>$'</code>, and <code>/p</code> is ignored.
-</p>
-<hr>
-<a name="perlre-Quoting-metacharacters"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Extended-Patterns" accesskey="n" rel="next">perlre
Extended Patterns</a>, Previous: <a href="#perlre-Regular-Expressions"
accesskey="p" rel="prev">perlre Regular Expressions</a>, Up: <a
href="#perlre-DESCRIPTION" accesskey="u" rel="up">perlre DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Quoting-metacharacters"></a>
-<h4 class="subsection">58.2.3 Quoting metacharacters</h4>
-
-<p>Backslashed metacharacters in Perl are alphanumeric, such as
<code>\b</code>,
-<code>\w</code>, <code>\n</code>. Unlike some other regular expression
languages, there
-are no backslashed symbols that aren’t alphanumeric. So anything
-that looks like \\, \(, \), \[, \], \{, or \} is always
-interpreted as a literal character, not a metacharacter. This was
-once used in a common idiom to disable or quote the special meanings
-of regular expression metacharacters in a string that you want to
-use for a pattern. Simply quote all non-"word" characters:
-</p>
-<pre class="verbatim"> $pattern =~ s/(\W)/\\$1/g;
-</pre>
-<p>(If <code>use locale</code> is set, then this depends on the current
locale.)
-Today it is more common to use the quotemeta() function or the <code>\Q</code>
-metaquoting escape sequence to disable all metacharacters’ special
-meanings like this:
-</p>
-<pre class="verbatim"> /$unquoted\Q$quoted\E$unquoted/
-</pre>
-<p>Beware that if you put literal backslashes (those not inside
-interpolated variables) between <code>\Q</code> and <code>\E</code>,
double-quotish
-backslash interpolation may lead to confusing results. If you
-<em>need</em> to use literal backslashes within <code>\Q...\E</code>,
-consult <a href="#perlop-Gory-details-of-parsing-quoted-constructs">perlop
Gory details of parsing quoted constructs</a>.
-</p>
-<p><code>quotemeta()</code> and <code>\Q</code> are fully described in <a
href="#perlfunc-quotemeta">perlfunc quotemeta</a>.
-</p>
-<hr>
-<a name="perlre-Extended-Patterns"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Special-Backtracking-Control-Verbs" accesskey="n"
rel="next">perlre Special Backtracking Control Verbs</a>, Previous: <a
href="#perlre-Quoting-metacharacters" accesskey="p" rel="prev">perlre Quoting
metacharacters</a>, Up: <a href="#perlre-DESCRIPTION" accesskey="u"
rel="up">perlre DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Extended-Patterns"></a>
-<h4 class="subsection">58.2.4 Extended Patterns</h4>
-
-<p>Perl also defines a consistent extension syntax for features not
-found in standard tools like <strong>awk</strong> and
-<strong>lex</strong>. 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.
-</p>
-<p>The stability of these extensions varies widely. Some have been
-part of the core language for many years. Others are experimental
-and may change without warning or be completely removed. Check
-the documentation on an individual feature to verify its current
-status.
-</p>
-<p>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....
-</p>
-<dl compact="compact">
-<dt><code>(?#text)</code></dt>
-<dd><a name="perlre-_0028_003f_0023text_0029"></a>
-<p>A comment. The text is ignored.
-Note that Perl closes
-the comment as soon as it sees a <code>)</code>, so there is no way to put a
literal
-<code>)</code> in the comment. The pattern’s closing delimiter must be
escaped by
-a backslash if it appears in the comment.
-</p>
-<p>See <a href="#perlre-_002fx">/x</a> for another way to have comments in
patterns.
-</p>
-</dd>
-<dt><code>(?adlupimnsx-imnsx)</code></dt>
-<dd><a name="perlre-_0028_003fadlupimnsx_002dimnsx_0029"></a>
-</dd>
-<dt><code>(?^alupimnsx)</code></dt>
-<dd><a name="perlre-_0028_003f_005ealupimnsx_0029"></a>
-<p>One or more embedded pattern-match modifiers, to be turned on (or
-turned off, if preceded by <code>-</code>) for the remainder of the pattern or
-the remainder of the enclosing pattern group (if any).
-</p>
-<p>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
-include <code>(?i)</code> at the front of the pattern. For example:
-</p>
-<pre class="verbatim"> $pattern = "foobar";
- if ( /$pattern/i ) { }
-
- # more flexible:
-
- $pattern = "(?i)foobar";
- if ( /$pattern/ ) { }
-</pre>
-<p>These modifiers are restored at the end of the enclosing group. For example,
-</p>
-<pre class="verbatim"> ( (?i) blah ) \s+ \g1
-</pre>
-<p>will match <code>blah</code> in any case, some spaces, and an exact
(<em>including the case</em>!)
-repetition of the previous word, assuming the <code>/x</code> modifier, and no
<code>/i</code>
-modifier outside this group.
-</p>
-<p>These modifiers do not carry over into named subpatterns called in the
-enclosing group. In other words, a pattern such as
<code>((?i)(?&NAME))</code> does not
-change the case-sensitivity of the "NAME" pattern.
-</p>
-<p>Any of these modifiers can be set to apply globally to all regular
-expressions compiled within the scope of a <code>use re</code>. See
-<a href="re.html#g_t_0027_002fflags_0027-mode">(re)'/flags' mode</a>.
-</p>
-<p>Starting in Perl 5.14, a <code>"^"</code> (caret or circumflex
accent) immediately
-after the <code>"?"</code> is a shorthand equivalent to
<code>d-imnsx</code>. Flags (except
-<code>"d"</code>) may follow the caret to override it.
-But a minus sign is not legal with it.
-</p>
-<p>Note that the <code>a</code>, <code>d</code>, <code>l</code>,
<code>p</code>, and <code>u</code> modifiers are special in
-that they can only be enabled, not disabled, and the <code>a</code>,
<code>d</code>, <code>l</code>, and
-<code>u</code> modifiers are mutually exclusive: specifying one de-specifies
the
-others, and a maximum of one (or two <code>a</code>’s) may appear in the
-construct. Thus, for
-example, <code>(?-p)</code> will warn when compiled under <code>use
warnings</code>;
-<code>(?-d:...)</code> and <code>(?dl:...)</code> are fatal errors.
-</p>
-<p>Note also that the <code>p</code> modifier is special in that its presence
-anywhere in a pattern has a global effect.
-</p>
-</dd>
-<dt><code>(?:pattern)</code></dt>
-<dd><a name="perlre-_0028_003f_003apattern_0029"></a>
-</dd>
-<dt><code>(?adluimnsx-imnsx:pattern)</code></dt>
-<dd><a name="perlre-_0028_003fadluimnsx_002dimnsx_003apattern_0029"></a>
-</dd>
-<dt><code>(?^aluimnsx:pattern)</code></dt>
-<dd><a name="perlre-_0028_003f_005ealuimnsx_003apattern_0029"></a>
-<p>This is for clustering, not capturing; it groups subexpressions like
-"()", but doesn’t make backreferences as "()" does.
So
-</p>
-<pre class="verbatim"> @fields = split(/\b(?:a|b|c)\b/)
-</pre>
-<p>is like
-</p>
-<pre class="verbatim"> @fields = split(/\b(a|b|c)\b/)
-</pre>
-<p>but doesn’t spit out extra fields. It’s also cheaper not to
capture
-characters if you don’t need to.
-</p>
-<p>Any letters between <code>?</code> and <code>:</code> act as flags
modifiers as with
-<code>(?adluimnsx-imnsx)</code>. For example,
-</p>
-<pre class="verbatim"> /(?s-i:more.*than).*million/i
-</pre>
-<p>is equivalent to the more verbose
-</p>
-<pre class="verbatim"> /(?:(?s-i)more.*than).*million/i
-</pre>
-<p>Note that any <code>(...)</code> constructs enclosed within this one will
still
-capture unless the <code>/n</code> modifier is in effect.
-</p>
-<p>Starting in Perl 5.14, a <code>"^"</code> (caret or circumflex
accent) immediately
-after the <code>"?"</code> is a shorthand equivalent to
<code>d-imnsx</code>. Any positive
-flags (except <code>"d"</code>) may follow the caret, so
-</p>
-<pre class="verbatim"> (?^x:foo)
-</pre>
-<p>is equivalent to
-</p>
-<pre class="verbatim"> (?x-imns:foo)
-</pre>
-<p>The caret tells Perl that this cluster doesn’t inherit the flags of
any
-surrounding pattern, but uses the system defaults (<code>d-imnsx</code>),
-modified by any flags specified.
-</p>
-<p>The caret allows for simpler stringification of compiled regular
-expressions. These look like
-</p>
-<pre class="verbatim"> (?^:pattern)
-</pre>
-<p>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.
-</p>
-<p>Specifying a negative flag after the caret is an error, as the flag is
-redundant.
-</p>
-<p>Mnemonic for <code>(?^...)</code>: A fresh beginning since the usual use
of a caret is
-to match at the beginning.
-</p>
-</dd>
-<dt><code>(?|pattern)</code></dt>
-<dd><a name="perlre-_0028_003f_007cpattern_0029"></a>
-<p>This is the "branch reset" pattern, which has the special property
-that the capture groups are numbered from the same starting point
-in each alternation branch. It is available starting from perl 5.10.0.
-</p>
-<p>Capture groups are numbered from left to right, but inside this
-construct the numbering is restarted for each branch.
-</p>
-<p>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
-groups in it.
-</p>
-<p>This construct is useful when you want to capture one of a
-number of alternative matches.
-</p>
-<p>Consider the following pattern. The numbers underneath show in
-which group the captured content will be stored.
-</p>
-<pre class="verbatim"> # before ---------------branch-reset-----------
after
- / ( a ) (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x
- # 1 2 2 3 2 3 4
-</pre>
-<p>Be careful when using the branch reset pattern in combination with
-named captures. Named captures are implemented as being aliases to
-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:
-</p>
-<pre class="verbatim"> /(?| (?<a> x ) (?<b> y )
- | (?<a> z ) (?<b> w )) /x
-</pre>
-<p>Not doing so may lead to surprises:
-</p>
-<pre class="verbatim"> "12" =~ /(?| (?<a> \d+ ) | (?<b>
\D+))/x;
- say $+ {a}; # Prints '12'
- say $+ {b}; # *Also* prints '12'.
-</pre>
-<p>The problem here is that both the group named <code>a</code> and the group
-named <code>b</code> are aliases for the group belonging to <code>$1</code>.
-</p>
-</dd>
-<dt>Look-Around Assertions</dt>
-<dd><a name="perlre-Look_002dAround-Assertions"></a>
-<p>Look-around assertions are zero-width patterns which match a specific
-pattern without including it in <code>$&</code>. Positive assertions match
when
-their subpattern matches, negative assertions match when their subpattern
-fails. Look-behind matches text up to the current match position,
-look-ahead matches text following the current match position.
-</p>
-<dl compact="compact">
-<dt><code>(?=pattern)</code></dt>
-<dd><a name="perlre-_0028_003f_003dpattern_0029"></a>
-<p>A zero-width positive look-ahead assertion. For example,
<code>/\w+(?=\t)/</code>
-matches a word followed by a tab, without including the tab in
<code>$&</code>.
-</p>
-</dd>
-<dt><code>(?!pattern)</code></dt>
-<dd><a name="perlre-_0028_003f_0021pattern_0029"></a>
-<p>A zero-width negative look-ahead assertion. For example
<code>/foo(?!bar)/</code>
-matches any occurrence of "foo" that isn’t followed by
"bar". Note
-however that look-ahead and look-behind are NOT the same thing. You cannot
-use this for look-behind.
-</p>
-<p>If you are looking for a "bar" that isn’t preceded by a
"foo", <code>/(?!foo)bar/</code>
-will not do what you want. That’s because the <code>(?!foo)</code> is
just saying that
-the next thing cannot be "foo"–and it’s not, it’s
a "bar", so "foobar" will
-match. Use look-behind instead (see below).
-</p>
-</dd>
-<dt><code>(?<=pattern)</code> <code>\K</code></dt>
-<dd><a name="perlre-_0028_003f_003c_003dpattern_0029-_005cK"></a>
-<p>A zero-width positive look-behind assertion. For example,
<code>/(?<=\t)\w+/</code>
-matches a word that follows a tab, without including the tab in
<code>$&</code>.
-Works only for fixed-width look-behind.
-</p>
-<p>There is a special form of this construct, called <code>\K</code>
(available since
-Perl 5.10.0), which causes the
-regex engine to "keep" everything it had matched prior to the
<code>\K</code> and
-not include it in <code>$&</code>. This effectively provides
variable-length
-look-behind. The use of <code>\K</code> inside of another look-around assertion
-is allowed, but the behaviour is currently not well defined.
-</p>
-<p>For various reasons <code>\K</code> may be significantly more efficient
than the
-equivalent <code>(?<=...)</code> construct, and it is especially useful in
-situations where you want to efficiently remove something following
-something else in a string. For instance
-</p>
-<pre class="verbatim"> s/(foo)bar/$1/g;
-</pre>
-<p>can be rewritten as the much more efficient
-</p>
-<pre class="verbatim"> s/foo\Kbar//g;
-</pre>
-</dd>
-<dt><code>(?<!pattern)</code></dt>
-<dd><a name="perlre-_0028_003f_003c_0021pattern_0029"></a>
-<p>A zero-width negative look-behind assertion. For example
<code>/(?<!bar)foo/</code>
-matches any occurrence of "foo" that does not follow
"bar". Works
-only for fixed-width look-behind.
-</p>
-</dd>
-</dl>
-
-</dd>
-<dt><code>(?'NAME'pattern)</code></dt>
-<dd><a name="perlre-_0028_003f_0027NAME_0027pattern_0029"></a>
-</dd>
-<dt><code>(?<NAME>pattern)</code> ) >></dt>
-<dd><a name="perlre-_0028_003f_003cNAME_003epattern_0029-_0029-_003e_003e"></a>
-<p>A named capture group. Identical in every respect to normal capturing
-parentheses <code>()</code> but for the additional fact that the group
-can be referred to by name in various regular expression
-constructs (like <code>\g{NAME}</code>) and can be accessed by name
-after a successful match via <code>%+</code> or <code>%-</code>. See <a
href="#perlvar-NAME">perlvar NAME</a>
-for more details on the <code>%+</code> and <code>%-</code> hashes.
-</p>
-<p>If multiple distinct capture groups have the same name then the
-$+{NAME} will refer to the leftmost defined group in the match.
-</p>
-<p>The forms <code>(?'NAME'pattern)</code> and
<code>(?<NAME>pattern)</code> are equivalent.
-</p>
-<p><strong>NOTE:</strong> While the notation of this construct is the same as
the similar
-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
-</p>
-<pre class="verbatim"> /(x)(?<foo>y)(z)/
-</pre>
-<p>$+{foo} will be the same as $2, and $3 will contain ’z’ instead
of
-the opposite which is what a .NET regex hacker might expect.
-</p>
-<p>Currently NAME is restricted to simple identifiers only.
-In other words, it must match <code>/^[_A-Za-z][_A-Za-z0-9]*\z/</code> or
-its Unicode extension (see <a href="utf8.html#Top">(utf8)</a>),
-though it isn’t extended by the locale (see <a
href="#perllocale-NAME">perllocale NAME</a>).
-</p>
-<p><strong>NOTE:</strong> In order to make things easier for programmers with
experience
-with the Python or PCRE regex engines, the pattern
<code>(?P<NAME>pattern)</code>
-may be used instead of <code>(?<NAME>pattern)</code>; however this form
does not
-support the use of single quotes as a delimiter for the name.
-</p>
-</dd>
-<dt><code>\k<NAME></code></dt>
-<dd><a name="perlre-_005ck_003cNAME_003e"></a>
-</dd>
-<dt><code>\k'NAME'</code></dt>
-<dd><a name="perlre-_005ck_0027NAME_0027"></a>
-<p>Named backreference. Similar to numeric backreferences, except that
-the group is designated by name and not number. If multiple groups
-have the same name then it refers to the leftmost defined group in
-the current match.
-</p>
-<p>It is an error to refer to a name not defined by a
<code>(?<NAME>)</code>
-earlier in the pattern.
-</p>
-<p>Both forms are equivalent.
-</p>
-<p><strong>NOTE:</strong> In order to make things easier for programmers with
experience
-with the Python or PCRE regex engines, the pattern <code>(?P=NAME)</code>
-may be used instead of <code>\k<NAME></code>.
-</p>
-</dd>
-<dt><code>(?{ code })</code></dt>
-<dd><a name="perlre-_0028_003f_007b-code-_007d_0029"></a>
-<p><strong>WARNING</strong>: Using this feature safely requires that you
understand its
-limitations. Code executed that has side effects may not perform identically
-from version to version due to the effect of future optimisations in the regex
-engine. For more information on this, see <a
href="#perlre-Embedded-Code-Execution-Frequency">Embedded Code Execution
-Frequency</a>.
-</p>
-<p>This zero-width assertion executes any embedded Perl code. It always
-succeeds, and its return value is set as <code>$^R</code>.
-</p>
-<p>In literal patterns, the code is parsed at the same time as the
-surrounding code. While within the pattern, control is passed temporarily
-back to the perl parser, until the logically-balancing closing brace is
-encountered. This is similar to the way that an array index expression in
-a literal string is handled, for example
-</p>
-<pre class="verbatim"> "abc$array[ 1 + f('[') + g()]def"
-</pre>
-<p>In particular, braces do not need to be balanced:
-</p>
-<pre class="verbatim"> s/abc(?{ f('{'); })/def/
-</pre>
-<p>Even in a pattern that is interpolated and compiled at run-time, literal
-code blocks will be compiled once, at perl compile time; the following
-prints "ABCD":
-</p>
-<pre class="verbatim"> print "D";
- my $qr = qr/(?{ BEGIN { print "A" } })/;
- my $foo = "foo";
- /$foo$qr(?{ BEGIN { print "B" } })/;
- BEGIN { print "C" }
-</pre>
-<p>In patterns where the text of the code is derived from run-time
-information rather than appearing literally in a source code /pattern/,
-the code is compiled at the same time that the pattern is compiled, and
-for reasons of security, <code>use re 'eval'</code> must be in scope. This is
to
-stop user-supplied patterns containing code snippets from being
-executable.
-</p>
-<p>In situations where you need to enable this with <code>use re
'eval'</code>, you should
-also have taint checking enabled. Better yet, use the carefully
-constrained evaluation within a Safe compartment. See <a
href="#perlsec-NAME">perlsec NAME</a> for
-details about both these mechanisms.
-</p>
-<p>From the viewpoint of parsing, lexical variable scope and closures,
-</p>
-<pre class="verbatim"> /AAA(?{ BBB })CCC/
-</pre>
-<p>behaves approximately like
-</p>
-<pre class="verbatim"> /AAA/ && do { BBB } && /CCC/
-</pre>
-<p>Similarly,
-</p>
-<pre class="verbatim"> qr/AAA(?{ BBB })CCC/
-</pre>
-<p>behaves approximately like
-</p>
-<pre class="verbatim"> sub { /AAA/ && do { BBB } && /CCC/ }
-</pre>
-<p>In particular:
-</p>
-<pre class="verbatim"> { my $i = 1; $r = qr/(?{ print $i })/ }
- my $i = 2;
- /$r/; # prints "1"
-</pre>
-<p>Inside a <code>(?{...})</code> block, <code>$_</code> refers to the string
the regular
-expression is matching against. You can also use <code>pos()</code> to know
what is
-the current position of matching within this string.
-</p>
-<p>The code block introduces a new scope from the perspective of lexical
-variable declarations, but <strong>not</strong> from the perspective of
<code>local</code> and
-similar localizing behaviours. So later code blocks within the same
-pattern will still see the values which were localized in earlier blocks.
-These accumulated localizations are undone either at the end of a
-successful match, or if the assertion is backtracked (compare
-<a href="#perlre-Backtracking">Backtracking</a>). For example,
-</p>
-<pre class="verbatim"> $_ = 'a' x 8;
- m<
- (?{ $cnt = 0 }) # Initialize $cnt.
- (
- a
- (?{
- local $cnt = $cnt + 1; # Update $cnt,
- # backtracking-safe.
- })
- )*
- aaaa
- (?{ $res = $cnt }) # On success copy to
- # non-localized location.
- >x;
-</pre>
-<p>will initially increment <code>$cnt</code> up to 8; then during
backtracking, its
-value will be unwound back to 4, which is the value assigned to
<code>$res</code>.
-At the end of the regex execution, $cnt will be wound back to its initial
-value of 0.
-</p>
-<p>This assertion may be used as the condition in a
-</p>
-<pre class="verbatim"> (?(condition)yes-pattern|no-pattern)
-</pre>
-<p>switch. If <em>not</em> used in this way, the result of evaluation of
<code>code</code>
-is put into the special variable <code>$^R</code>. This happens immediately,
so
-<code>$^R</code> can be used from other <code>(?{ code })</code> assertions
inside the same
-regular expression.
-</p>
-<p>The assignment to <code>$^R</code> above is properly localized, so the old
-value of <code>$^R</code> is restored if the assertion is backtracked; compare
-<a href="#perlre-Backtracking">Backtracking</a>.
-</p>
-<p>Note that the special variable <code>$^N</code> is particularly useful
with code
-blocks to capture the results of submatches in variables without having to
-keep track of the number of nested parentheses. For example:
-</p>
-<pre class="verbatim"> $_ = "The brown fox jumps over the lazy dog";
- /the (\S+)(?{ $color = $^N }) (\S+)(?{ $animal = $^N })/i;
- print "color = $color, animal = $animal\n";
-</pre>
-</dd>
-<dt><code>(??{ code })</code></dt>
-<dd><a name="perlre-_0028_003f_003f_007b-code-_007d_0029"></a>
-<p><strong>WARNING</strong>: Using this feature safely requires that you
understand its
-limitations. Code executed that has side effects may not perform
-identically from version to version due to the effect of future
-optimisations in the regex engine. For more information on this, see
-<a href="#perlre-Embedded-Code-Execution-Frequency">Embedded Code Execution
Frequency</a>.
-</p>
-<p>This is a "postponed" regular subexpression. It behaves in
<em>exactly</em> the
-same way as a <code>(?{ code })</code> code block as described above, except
that
-its return value, rather than being assigned to <code>$^R</code>, is treated
as a
-pattern, compiled if it’s a string (or used as-is if its a qr// object),
-then matched as if it were inserted instead of this construct.
-</p>
-<p>During the matching of this sub-pattern, it has its own set of
-captures which are valid during the sub-match, but are discarded once
-control returns to the main pattern. For example, the following matches,
-with the inner pattern capturing "B" and matching "BB",
while the outer
-pattern captures "A";
-</p>
-<pre class="verbatim"> my $inner = '(.)\1';
- "ABBA" =~ /^(.)(??{ $inner })\1/;
- print $1; # prints "A";
-</pre>
-<p>Note that this means that there is no way for the inner pattern to refer
-to a capture group defined outside. (The code block itself can use
<code>$1</code>,
-etc., to refer to the enclosing pattern’s capture groups.) Thus,
although
-</p>
-<pre class="verbatim"> ('a' x 100)=~/(??{'(.)' x 100})/
-</pre>
-<p><em>will</em> match, it will <em>not</em> set $1 on exit.
-</p>
-<p>The following pattern matches a parenthesized group:
-</p>
-<pre class="verbatim"> $re = qr{
- \(
- (?:
- (?> [^()]+ ) # Non-parens without backtracking
- |
- (??{ $re }) # Group with matching parens
- )*
- \)
- }x;
-</pre>
-<p>See also
-<a
href="#perlre-_0028_003fPARNO_0029-_0028_003f_002dPARNO_0029-_0028_003f_002bPARNO_0029-_0028_003fR_0029-_0028_003f0_0029"><code>(?<em>PARNO</em>)</code></a>
-for a different, more efficient way to accomplish
-the same task.
-</p>
-<p>Executing a postponed regular expression 50 times without consuming any
-input string will result in a fatal error. The maximum depth is compiled
-into perl, so changing it requires a custom build.
-</p>
-</dd>
-<dt><code>(?<em>PARNO</em>)</code> <code>(?-<em>PARNO</em>)</code>
<code>(?+<em>PARNO</em>)</code> <code>(?R)</code> <code>(?0)</code></dt>
-<dd><a
name="perlre-_0028_003fPARNO_0029-_0028_003f_002dPARNO_0029-_0028_003f_002bPARNO_0029-_0028_003fR_0029-_0028_003f0_0029"></a>
-<p>Recursive subpattern. Treat the contents of a given capture buffer in the
-current pattern as an independent subpattern and attempt to match it at
-the current position in the string. Information about capture state from
-the caller for things like backreferences is available to the subpattern,
-but capture buffers set by the subpattern are not visible to the caller.
-</p>
-<p>Similar to <code>(??{ code })</code> except that it does not involve
executing any
-code or potentially compiling a returned pattern string; instead it treats
-the part of the current pattern contained within a specified capture group
-as an independent pattern that must match at the current position. Also
-different is the treatment of capture buffers, unlike <code>(??{ code })</code>
-recursive patterns have access to their callers match state, so one can
-use backreferences safely.
-</p>
-<p><em>PARNO</em> is a sequence of digits (not starting with 0) whose value
reflects
-the paren-number of the capture group to recurse to. <code>(?R)</code>
recurses to
-the beginning of the whole pattern. <code>(?0)</code> is an alternate syntax
for
-<code>(?R)</code>. If <em>PARNO</em> is preceded by a plus or minus sign then
it is assumed
-to be relative, with negative numbers indicating preceding capture groups
-and positive ones following. Thus <code>(?-1)</code> refers to the most
recently
-declared group, and <code>(?+1)</code> 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 groups
<strong>are</strong>
-included.
-</p>
-<p>The following pattern matches a function foo() which may contain
-balanced parentheses as the argument.
-</p>
-<pre class="verbatim"> $re = qr{ ( # paren group 1 (full
function)
- foo
- ( # paren group 2 (parens)
- \(
- ( # paren group 3 (contents of parens)
- (?:
- (?> [^()]+ ) # Non-parens without backtracking
- |
- (?2) # Recurse to start of paren group 2
- )*
- )
- \)
- )
- )
- }x;
-</pre>
-<p>If the pattern was used as follows
-</p>
-<pre class="verbatim"> 'foo(bar(baz)+baz(bop))'=~/$re/
- and print "\$1 = $1\n",
- "\$2 = $2\n",
- "\$3 = $3\n";
-</pre>
-<p>the output produced should be the following:
-</p>
-<pre class="verbatim"> $1 = foo(bar(baz)+baz(bop))
- $2 = (bar(baz)+baz(bop))
- $3 = bar(baz)+baz(bop)
-</pre>
-<p>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.
-</p>
-<p>The following shows how using negative indexing can make it
-easier to embed recursive patterns inside of a <code>qr//</code> construct
-for later use:
-</p>
-<pre class="verbatim"> my $parens = qr/(\((?:[^()]++|(?-1))*+\))/;
- if (/foo $parens \s+ \+ \s+ bar $parens/x) {
- # do something here...
- }
-</pre>
-<p><strong>Note</strong> that this pattern does not behave the same way as the
equivalent
-PCRE or Python construct of the same form. In Perl you can backtrack into
-a recursed group, in PCRE and Python the recursed into group is treated
-as atomic. Also, modifiers are resolved at compile time, so constructs
-like (?i:(?1)) or (?:(?i)(?1)) do not affect how the sub-pattern will
-be processed.
-</p>
-</dd>
-<dt><code>(?&NAME)</code></dt>
-<dd><a name="perlre-_0028_003f_0026NAME_0029"></a>
-<p>Recurse to a named subpattern. Identical to <code>(?<em>PARNO</em>)</code>
except that the
-parenthesis to recurse to is determined by name. If multiple parentheses have
-the same name, then it recurses to the leftmost.
-</p>
-<p>It is an error to refer to a name that is not declared somewhere in the
-pattern.
-</p>
-<p><strong>NOTE:</strong> In order to make things easier for programmers with
experience
-with the Python or PCRE regex engines the pattern <code>(?P>NAME)</code>
-may be used instead of <code>(?&NAME)</code>.
-</p>
-</dd>
-<dt><code>(?(condition)yes-pattern|no-pattern)</code></dt>
-<dd><a
name="perlre-_0028_003f_0028condition_0029yes_002dpattern_007cno_002dpattern_0029"></a>
-</dd>
-<dt><code>(?(condition)yes-pattern)</code></dt>
-<dd><a name="perlre-_0028_003f_0028condition_0029yes_002dpattern_0029"></a>
-<p>Conditional expression. Matches <code>yes-pattern</code> if
<code>condition</code> yields
-a true value, matches <code>no-pattern</code> otherwise. A missing pattern
always
-matches.
-</p>
-<p><code>(condition)</code> should be one of: 1) an integer in
-parentheses (which is valid if the corresponding pair of parentheses
-matched); 2) a look-ahead/look-behind/evaluate zero-width assertion; 3) a
-name in angle brackets or single quotes (which is valid if a group
-with the given name matched); or 4) the special symbol (R) (true when
-evaluated inside of recursion or eval). Additionally the R may be
-followed by a number, (which will be true when evaluated when recursing
-inside of the appropriate group), or by <code>&NAME</code>, in which case
it will
-be true only when evaluated during recursion in the named group.
-</p>
-<p>Here’s a summary of the possible predicates:
-</p>
-<dl compact="compact">
-<dt>(1) (2) ...</dt>
-<dd><a name="perlre-_00281_0029-_00282_0029-_002e_002e_002e"></a>
-<p>Checks if the numbered capturing group has matched something.
-</p>
-</dd>
-<dt>(<NAME>) (’NAME’)</dt>
-<dd><a name="perlre-_0028_003cNAME_003e_0029-_0028_0027NAME_0027_0029"></a>
-<p>Checks if a group with the given name has matched something.
-</p>
-</dd>
-<dt>(?=...) (?!...) (?<=...) (?<!...)</dt>
-<dd><a
name="perlre-_0028_003f_003d_002e_002e_002e_0029-_0028_003f_0021_002e_002e_002e_0029-_0028_003f_003c_003d_002e_002e_002e_0029-_0028_003f_003c_0021_002e_002e_002e_0029"></a>
-<p>Checks whether the pattern matches (or does not match, for the
’!’
-variants).
-</p>
-</dd>
-<dt>(?{ CODE })</dt>
-<dd><a name="perlre-_0028_003f_007b-CODE-_007d_0029"></a>
-<p>Treats the return value of the code block as the condition.
-</p>
-</dd>
-<dt>(R)</dt>
-<dd><a name="perlre-_0028R_0029"></a>
-<p>Checks if the expression has been evaluated inside of recursion.
-</p>
-</dd>
-<dt>(R1) (R2) ...</dt>
-<dd><a name="perlre-_0028R1_0029-_0028R2_0029-_002e_002e_002e"></a>
-<p>Checks if the expression has been evaluated while executing directly
-inside of the n-th capture group. This check is the regex equivalent of
-</p>
-<pre class="verbatim"> if ((caller(0))[3] eq 'subname') { ... }
-</pre>
-<p>In other words, it does not check the full recursion stack.
-</p>
-</dd>
-<dt>(R&NAME)</dt>
-<dd><a name="perlre-_0028R_0026NAME_0029"></a>
-<p>Similar to <code>(R1)</code>, this predicate checks to see if we’re
executing
-directly inside of the leftmost group with a given name (this is the same
-logic used by <code>(?&NAME)</code> to disambiguate). It does not check
the full
-stack, but only the name of the innermost active recursion.
-</p>
-</dd>
-<dt>(DEFINE)</dt>
-<dd><a name="perlre-_0028DEFINE_0029"></a>
-<p>In this case, the yes-pattern is never directly executed, and no
-no-pattern is allowed. Similar in spirit to <code>(?{0})</code> but more
efficient.
-See below for details.
-</p>
-</dd>
-</dl>
-
-<p>For example:
-</p>
-<pre class="verbatim"> m{ ( \( )?
- [^()]+
- (?(1) \) )
- }x
-</pre>
-<p>matches a chunk of non-parentheses, possibly included in parentheses
-themselves.
-</p>
-<p>A special form is the <code>(DEFINE)</code> 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.
-</p>
-<p>It is recommended that for this usage you put the DEFINE block at the
-end of the pattern, and that you name any subpatterns defined within it.
-</p>
-<p>Also, it’s worth noting that patterns defined this way probably will
-not be as efficient, as the optimizer is not very clever about
-handling them.
-</p>
-<p>An example of how this might be used is as follows:
-</p>
-<pre class="verbatim">
/(?<NAME>(?&NAME_PAT))(?<ADDR>(?&ADDRESS_PAT))
- (?(DEFINE)
- (?<NAME_PAT>....)
- (?<ADDRESS_PAT>....)
- )/x
-</pre>
-<p>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 <code>$+{NAME_PAT}</code> would not be defined even though
-<code>$+{NAME}</code> would be.
-</p>
-<p>Finally, keep in mind that subpatterns created inside a DEFINE block
-count towards the absolute and relative number of captures, so this:
-</p>
-<pre class="verbatim"> my @captures = "a" =~ /(.)
# First capture
- (?(DEFINE)
- (?<EXAMPLE> 1 ) # Second capture
- )/x;
- say scalar @captures;
-</pre>
-<p>Will output 2, not 1. This is particularly important if you intend to
-compile the definitions with the <code>qr//</code> operator, and later
-interpolate them in another pattern.
-</p>
-</dd>
-<dt><code>(?>pattern)</code></dt>
-<dd><a name="perlre-_0028_003f_003epattern_0029"></a>
-<p>An "independent" subexpression, one which matches the substring
-that a <em>standalone</em> <code>pattern</code> would match if anchored at the
given
-position, and it matches <em>nothing other than this substring</em>. This
-construct is useful for optimizations of what would otherwise be
-"eternal" matches, because it will not backtrack (see <a
href="#perlre-Backtracking">Backtracking</a>).
-It may also be useful in places where the "grab all you can, and do not
-give anything back" semantic is desirable.
-</p>
-<p>For example: <code>^(?>a*)ab</code> will never match, since
<code>(?>a*)</code>
-(anchored at the beginning of string, as above) will match <em>all</em>
-characters <code>a</code> at the beginning of string, leaving no
<code>a</code> for
-<code>ab</code> to match. In contrast, <code>a*ab</code> will match the same
as <code>a+b</code>,
-since the match of the subgroup <code>a*</code> is influenced by the following
-group <code>ab</code> (see <a href="#perlre-Backtracking">Backtracking</a>).
In particular, <code>a*</code> inside
-<code>a*ab</code> will match fewer characters than a standalone
<code>a*</code>, since
-this makes the tail match.
-</p>
-<p><code>(?>pattern)</code> does not disable backtracking altogether once
it has
-matched. It is still possible to backtrack past the construct, but not
-into it. So <code>((?>a*)|(?>b*))ar</code> will still match
"bar".
-</p>
-<p>An effect similar to <code>(?>pattern)</code> may be achieved by writing
-<code>(?=(pattern))\g{-1}</code>. This matches the same substring as a
standalone
-<code>a+</code>, and the following <code>\g{-1}</code> eats the matched
string; it therefore
-makes a zero-length assertion into an analogue of <code>(?>...)</code>.
-(The difference between these two constructs is that the second one
-uses a capturing group, thus shifting ordinals of backreferences
-in the rest of a regular expression.)
-</p>
-<p>Consider this pattern:
-</p>
-<pre class="verbatim"> m{ \(
- (
- [^()]+ # x+
- |
- \( [^()]* \)
- )+
- \)
- }x
-</pre>
-<p>That will efficiently match a nonempty group with matching parentheses
-two levels deep or less. However, if there is no such group, it
-will take virtually forever on a long string. That’s because there
-are so many different ways to split a long string into several
-substrings. This is what <code>(.+)+</code> is doing, and <code>(.+)+</code>
is similar
-to a subpattern of the above pattern. Consider how the pattern
-above detects no-match on <code>((()aaaaaaaaaaaaaaaaaa</code> in several
-seconds, but that each extra letter doubles this time. This
-exponential performance will make it appear that your program has
-hung. However, a tiny change to this pattern
-</p>
-<pre class="verbatim"> m{ \(
- (
- (?> [^()]+ ) # change x+ above to (?> x+ )
- |
- \( [^()]* \)
- )+
- \)
- }x
-</pre>
-<p>which uses <code>(?>...)</code> 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 <code>a</code>s. Be aware,
-however, that, when this construct is followed by a
-quantifier, it currently triggers a warning message under
-the <code>use warnings</code> pragma or <strong>-w</strong> switch saying it
-<code>"matches null string many times in regex"</code>.
-</p>
-<p>On simple groups, such as the pattern <code>(?> [^()]+ )</code>, a
comparable
-effect may be achieved by negative look-ahead, as in <code>[^()]+ (?! [^()]
)</code>.
-This was only 4 times slower on a string with 1000000 <code>a</code>s.
-</p>
-<p>The "grab all you can, and do not give anything back" semantic is
desirable
-in many situations where on the first sight a simple <code>()*</code> looks
like
-the correct solution. Suppose we parse text with comments being delimited
-by <code>#</code> followed by some optional (horizontal) whitespace. Contrary
to
-its appearance, <code>#[ \t]*</code> <em>is not</em> the correct subexpression
to match
-the comment delimiter, because it may "give up" some whitespace if
-the remainder of the pattern can be made to match that way. The correct
-answer is either one of these:
-</p>
-<pre class="verbatim"> (?>#[ \t]*)
- #[ \t]*(?![ \t])
-</pre>
-<p>For example, to grab non-empty comments into $1, one should use either
-one of these:
-</p>
-<pre class="verbatim"> / (?> \# [ \t]* ) ( .+ ) /x;
- / \# [ \t]* ( [^ \t] .* ) /x;
-</pre>
-<p>Which one you pick depends on which of these expressions better reflects
-the above specification of comments.
-</p>
-<p>In some literature this construct is called "atomic matching" or
-"possessive matching".
-</p>
-<p>Possessive quantifiers are equivalent to putting the item they are applied
-to inside of one of these constructs. The following equivalences apply:
-</p>
-<pre class="verbatim"> Quantifier Form Bracketing Form
- --------------- ---------------
- PAT*+ (?>PAT*)
- PAT++ (?>PAT+)
- PAT?+ (?>PAT?)
- PAT{min,max}+ (?>PAT{min,max})
-</pre>
-</dd>
-<dt><code>(?[ ])</code></dt>
-<dd><a name="perlre-_0028_003f_005b-_005d_0029"></a>
-<p>See <a
href="#perlrecharclass-Extended-Bracketed-Character-Classes">perlrecharclass
Extended Bracketed Character Classes</a>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlre-Special-Backtracking-Control-Verbs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Backtracking" accesskey="n" rel="next">perlre
Backtracking</a>, Previous: <a href="#perlre-Extended-Patterns" accesskey="p"
rel="prev">perlre Extended Patterns</a>, Up: <a href="#perlre-DESCRIPTION"
accesskey="u" rel="up">perlre DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Special-Backtracking-Control-Verbs"></a>
-<h4 class="subsection">58.2.5 Special Backtracking Control Verbs</h4>
-
-<p>These special patterns are generally of the form <code>(*VERB:ARG)</code>.
Unless
-otherwise stated the ARG argument is optional; in some cases, it is
-forbidden.
-</p>
-<p>Any pattern containing a special backtracking verb that allows an argument
-has the special behaviour that when executed it sets the current
package’s
-<code>$REGERROR</code> and <code>$REGMARK</code> variables. When doing so the
following
-rules apply:
-</p>
-<p>On failure, the <code>$REGERROR</code> variable will be set to the ARG
value of the
-verb pattern, if the verb was involved in the failure of the match. If the
-ARG part of the pattern was omitted, then <code>$REGERROR</code> will be set
to the
-name of the last <code>(*MARK:NAME)</code> pattern executed, or to TRUE if
there was
-none. Also, the <code>$REGMARK</code> variable will be set to FALSE.
-</p>
-<p>On a successful match, the <code>$REGERROR</code> variable will be set to
FALSE, and
-the <code>$REGMARK</code> variable will be set to the name of the last
-<code>(*MARK:NAME)</code> pattern executed. See the explanation for the
-<code>(*MARK:NAME)</code> verb below for more details.
-</p>
-<p><strong>NOTE:</strong> <code>$REGERROR</code> and <code>$REGMARK</code> are
not magic variables like <code>$1</code>
-and most other regex-related variables. They are not local to a scope, nor
-readonly, but instead are volatile package variables similar to
<code>$AUTOLOAD</code>.
-Use <code>local</code> to localize changes to them to a specific scope if
necessary.
-</p>
-<p>If a pattern does not contain a special backtracking verb that allows an
-argument, then <code>$REGERROR</code> and <code>$REGMARK</code> are not
touched at all.
-</p>
-<dl compact="compact">
-<dt>Verbs that take an argument</dt>
-<dd><a name="perlre-Verbs-that-take-an-argument"></a>
-<dl compact="compact">
-<dt><code>(*PRUNE)</code> <code>(*PRUNE:NAME)</code></dt>
-<dd><a name="perlre-_0028_002aPRUNE_0029-_0028_002aPRUNE_003aNAME_0029"></a>
-<p>This zero-width pattern prunes the backtracking tree at the current point
-when backtracked into on failure. Consider the pattern <code>A (*PRUNE)
B</code>,
-where A and B are complex patterns. Until the <code>(*PRUNE)</code> verb is
reached,
-A may backtrack as necessary to match. Once it is reached, matching
-continues in B, which may also backtrack as necessary; however, should B
-not match, then no further backtracking will take place, and the pattern
-will fail outright at the current starting position.
-</p>
-<p>The following example counts all the possible matching strings in a
-pattern (without actually matching any of them).
-</p>
-<pre class="verbatim"> 'aaab' =~ /a+b?(?{print "$&\n";
$count++})(*FAIL)/;
- print "Count=$count\n";
-</pre>
-<p>which produces:
-</p>
-<pre class="verbatim"> aaab
- aaa
- aa
- a
- aab
- aa
- a
- ab
- a
- Count=9
-</pre>
-<p>If we add a <code>(*PRUNE)</code> before the count like the following
-</p>
-<pre class="verbatim"> 'aaab' =~ /a+b?(*PRUNE)(?{print
"$&\n"; $count++})(*FAIL)/;
- print "Count=$count\n";
-</pre>
-<p>we prevent backtracking and find the count of the longest matching string
-at each matching starting point like so:
-</p>
-<pre class="verbatim"> aaab
- aab
- ab
- Count=3
-</pre>
-<p>Any number of <code>(*PRUNE)</code> assertions may be used in a pattern.
-</p>
-<p>See also <code>(?>pattern)</code> and possessive quantifiers for other
ways to
-control backtracking. In some cases, the use of <code>(*PRUNE)</code> can be
-replaced with a <code>(?>pattern)</code> with no functional difference;
however,
-<code>(*PRUNE)</code> can be used to handle cases that cannot be expressed
using a
-<code>(?>pattern)</code> alone.
-</p>
-</dd>
-<dt><code>(*SKIP)</code> <code>(*SKIP:NAME)</code></dt>
-<dd><a name="perlre-_0028_002aSKIP_0029-_0028_002aSKIP_003aNAME_0029"></a>
-<p>This zero-width pattern is similar to <code>(*PRUNE)</code>, except that on
-failure it also signifies that whatever text that was matched leading up
-to the <code>(*SKIP)</code> pattern being executed cannot be part of
<em>any</em> match
-of this pattern. This effectively means that the regex engine
"skips" forward
-to this position on failure and tries to match again, (assuming that
-there is sufficient room to match).
-</p>
-<p>The name of the <code>(*SKIP:NAME)</code> pattern has special significance.
If a
-<code>(*MARK:NAME)</code> was encountered while matching, then it is that
position
-which is used as the "skip point". If no <code>(*MARK)</code> of
that name was
-encountered, then the <code>(*SKIP)</code> operator has no effect. When used
-without a name the "skip point" is where the match point was when
-executing the (*SKIP) pattern.
-</p>
-<p>Compare the following to the examples in <code>(*PRUNE)</code>; note the
string
-is twice as long:
-</p>
-<pre class="verbatim"> 'aaabaaab' =~ /a+b?(*SKIP)(?{print
"$&\n"; $count++})(*FAIL)/;
- print "Count=$count\n";
-</pre>
-<p>outputs
-</p>
-<pre class="verbatim"> aaab
- aaab
- Count=2
-</pre>
-<p>Once the ’aaab’ at the start of the string has matched, and the
<code>(*SKIP)</code>
-executed, the next starting point will be where the cursor was when the
-<code>(*SKIP)</code> was executed.
-</p>
-</dd>
-<dt><code>(*MARK:NAME)</code> <code>(*:NAME)</code></dt>
-<dd><a name="perlre-_0028_002aMARK_003aNAME_0029-_0028_002a_003aNAME_0029"></a>
-<p>This zero-width pattern can be used to mark the point reached in a string
-when a certain part of the pattern has been successfully matched. This
-mark may be given a name. A later <code>(*SKIP)</code> pattern will then skip
-forward to that point if backtracked into on failure. Any number of
-<code>(*MARK)</code> patterns are allowed, and the NAME portion may be
duplicated.
-</p>
-<p>In addition to interacting with the <code>(*SKIP)</code> pattern,
<code>(*MARK:NAME)</code>
-can be used to "label" a pattern branch, so that after matching, the
-program can determine which branches of the pattern were involved in the
-match.
-</p>
-<p>When a match is successful, the <code>$REGMARK</code> variable will be set
to the
-name of the most recently executed <code>(*MARK:NAME)</code> that was involved
-in the match.
-</p>
-<p>This can be used to determine which branch of a pattern was matched
-without using a separate capture group for each branch, which in turn
-can result in a performance improvement, as perl cannot optimize
-<code>/(?:(x)|(y)|(z))/</code> as efficiently as something like
-<code>/(?:x(*MARK:x)|y(*MARK:y)|z(*MARK:z))/</code>.
-</p>
-<p>When a match has failed, and unless another verb has been involved in
-failing the match and has provided its own name to use, the
<code>$REGERROR</code>
-variable will be set to the name of the most recently executed
-<code>(*MARK:NAME)</code>.
-</p>
-<p>See ‘(*SKIP)’ for more details.
-</p>
-<p>As a shortcut <code>(*MARK:NAME)</code> can be written
<code>(*:NAME)</code>.
-</p>
-</dd>
-<dt><code>(*THEN)</code> <code>(*THEN:NAME)</code></dt>
-<dd><a name="perlre-_0028_002aTHEN_0029-_0028_002aTHEN_003aNAME_0029"></a>
-<p>This is similar to the "cut group" operator <code>::</code> from
Perl 6. Like
-<code>(*PRUNE)</code>, this verb always matches, and when backtracked into on
-failure, it causes the regex engine to try the next alternation in the
-innermost enclosing group (capturing or otherwise) that has alternations.
-The two branches of a <code>(?(condition)yes-pattern|no-pattern)</code> do not
-count as an alternation, as far as <code>(*THEN)</code> is concerned.
-</p>
-<p>Its name comes from the observation that this operation combined with the
-alternation operator (<code>|</code>) can be used to create what is
essentially a
-pattern-based if/then/else block:
-</p>
-<pre class="verbatim"> ( COND (*THEN) FOO | COND2 (*THEN) BAR | COND3 (*THEN)
BAZ )
-</pre>
-<p>Note that if this operator is used and NOT inside of an alternation then
-it acts exactly like the <code>(*PRUNE)</code> operator.
-</p>
-<pre class="verbatim"> / A (*PRUNE) B /
-</pre>
-<p>is the same as
-</p>
-<pre class="verbatim"> / A (*THEN) B /
-</pre>
-<p>but
-</p>
-<pre class="verbatim"> / ( A (*THEN) B | C ) /
-</pre>
-<p>is not the same as
-</p>
-<pre class="verbatim"> / ( A (*PRUNE) B | C ) /
-</pre>
-<p>as after matching the A but failing on the B the <code>(*THEN)</code> verb
will
-backtrack and try C; but the <code>(*PRUNE)</code> verb will simply fail.
-</p>
-</dd>
-</dl>
-
-</dd>
-<dt>Verbs without an argument</dt>
-<dd><a name="perlre-Verbs-without-an-argument"></a>
-<dl compact="compact">
-<dt><code>(*COMMIT)</code></dt>
-<dd><a name="perlre-_0028_002aCOMMIT_0029"></a>
-<p>This is the Perl 6 "commit pattern" <code><commit></code>
or <code>:::</code>. It’s a
-zero-width pattern similar to <code>(*SKIP)</code>, except that when
backtracked
-into on failure it causes the match to fail outright. No further attempts
-to find a valid match by advancing the start pointer will occur again.
-For example,
-</p>
-<pre class="verbatim"> 'aaabaaab' =~ /a+b?(*COMMIT)(?{print
"$&\n"; $count++})(*FAIL)/;
- print "Count=$count\n";
-</pre>
-<p>outputs
-</p>
-<pre class="verbatim"> aaab
- Count=1
-</pre>
-<p>In other words, once the <code>(*COMMIT)</code> has been entered, and if
the pattern
-does not match, the regex engine will not try any further matching on the
-rest of the string.
-</p>
-</dd>
-<dt><code>(*FAIL)</code> <code>(*F)</code></dt>
-<dd><a name="perlre-_0028_002aFAIL_0029-_0028_002aF_0029"></a>
-<p>This pattern matches nothing and always fails. It can be used to force the
-engine to backtrack. It is equivalent to <code>(?!)</code>, but easier to
read. In
-fact, <code>(?!)</code> gets optimised into <code>(*FAIL)</code> internally.
-</p>
-<p>It is probably useful only when combined with <code>(?{})</code> or
<code>(??{})</code>.
-</p>
-</dd>
-<dt><code>(*ACCEPT)</code></dt>
-<dd><a name="perlre-_0028_002aACCEPT_0029"></a>
-<p>This pattern matches nothing and causes the end of successful matching at
-the point at which the <code>(*ACCEPT)</code> pattern was encountered,
regardless of
-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 <code>(??{})</code>, only the innermost pattern is ended immediately.
-</p>
-<p>If the <code>(*ACCEPT)</code> is inside of capturing groups then the groups
are
-marked as ended at the point at which the <code>(*ACCEPT)</code> was
encountered.
-For instance:
-</p>
-<pre class="verbatim"> 'AB' =~ /(A (A|B(*ACCEPT)|C) D)(E)/x;
-</pre>
-<p>will match, and <code>$1</code> will be <code>AB</code> and <code>$2</code>
will be <code>B</code>, <code>$3</code> will not
-be set. If another branch in the inner parentheses was matched, such as in the
-string ’ACDE’, then the <code>D</code> and <code>E</code> would
have to be matched as well.
-</p>
-</dd>
-</dl>
-
-</dd>
-</dl>
-
-<hr>
-<a name="perlre-Backtracking"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Version-8-Regular-Expressions" accesskey="n"
rel="next">perlre Version 8 Regular Expressions</a>, Previous: <a
href="#perlre-Special-Backtracking-Control-Verbs" accesskey="p"
rel="prev">perlre Special Backtracking Control Verbs</a>, Up: <a
href="#perlre-DESCRIPTION" accesskey="u" rel="up">perlre DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Backtracking"></a>
-<h4 class="subsection">58.2.6 Backtracking</h4>
-
-<p>NOTE: This section presents an abstract approximation of regular
-expression behavior. For a more rigorous (and complicated) view of
-the rules involved in selecting a match among possible alternatives,
-see <a href="#perlre-Combining-RE-Pieces">Combining RE Pieces</a>.
-</p>
-<p>A fundamental feature of regular expression matching involves the
-notion called <em>backtracking</em>, which is currently used (when needed)
-by all regular non-possessive expression quantifiers, namely <code>*</code>,
<code>*?</code>, <code>+</code>,
-<code>+?</code>, <code>{n,m}</code>, and <code>{n,m}?</code>. Backtracking is
often optimized
-internally, but the general principle outlined here is valid.
-</p>
-<p>For a regular expression to match, the <em>entire</em> regular expression
must
-match, not just part of it. So if the beginning of a pattern containing a
-quantifier succeeds in a way that causes later parts in the pattern to
-fail, the matching engine backs up and recalculates the beginning
-part–that’s why it’s called backtracking.
-</p>
-<p>Here is an example of backtracking: Let’s say you want to find the
-word following "foo" in the string "Food is on the foo
table.":
-</p>
-<pre class="verbatim"> $_ = "Food is on the foo table.";
- if ( /\b(foo)\s+(\w+)/i ) {
- print "$2 follows $1.\n";
- }
-</pre>
-<p>When the match runs, the first part of the regular expression
(<code>\b(foo)</code>)
-finds a possible match right at the beginning of the string, and loads up
-$1 with "Foo". However, as soon as the matching engine sees that
there’s
-no whitespace following the "Foo" that it had saved in $1, it
realizes its
-mistake and starts over again one character after where it had the
-tentative match. This time it goes all the way until the next occurrence
-of "foo". The complete regular expression matches this time, and you
get
-the expected output of "table follows foo."
-</p>
-<p>Sometimes minimal matching can help a lot. Imagine you’d like to
match
-everything between "foo" and "bar". Initially, you write
something
-like this:
-</p>
-<pre class="verbatim"> $_ = "The food is under the bar in the
barn.";
- if ( /foo(.*)bar/ ) {
- print "got <$1>\n";
- }
-</pre>
-<p>Which perhaps unexpectedly yields:
-</p>
-<pre class="verbatim"> got <d is under the bar in the >
-</pre>
-<p>That’s because <code>.*</code> was greedy, so you get everything
between the
-<em>first</em> "foo" and the <em>last</em> "bar". Here
it’s more effective
-to use minimal matching to make sure you get the text between a "foo"
-and the first "bar" thereafter.
-</p>
-<pre class="verbatim"> if ( /foo(.*?)bar/ ) { print "got
<$1>\n" }
- got <d is under the >
-</pre>
-<p>Here’s another example. Let’s say you’d like to match a
number at the end
-of a string, and you also want to keep the preceding part of the match.
-So you write this:
-</p>
-<pre class="verbatim"> $_ = "I have 2 numbers: 53147";
- if ( /(.*)(\d*)/ ) { # Wrong!
- print "Beginning is <$1>, number is <$2>.\n";
- }
-</pre>
-<p>That won’t work at all, because <code>.*</code> was greedy and
gobbled up the
-whole string. As <code>\d*</code> can match on an empty string the complete
-regular expression matched successfully.
-</p>
-<pre class="verbatim"> Beginning is <I have 2 numbers: 53147>, number
is <>.
-</pre>
-<p>Here are some variants, most of which don’t work:
-</p>
-<pre class="verbatim"> $_ = "I have 2 numbers: 53147";
- @pats = qw{
- (.*)(\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";
- }
- }
-</pre>
-<p>That will print out:
-</p>
-<pre class="verbatim"> (.*)(\d*) <I have 2 numbers: 53147> <>
- (.*)(\d+) <I have 2 numbers: 5314> <7>
- (.*?)(\d*) <> <>
- (.*?)(\d+) <I have > <2>
- (.*)(\d+)$ <I have 2 numbers: 5314> <7>
- (.*?)(\d+)$ <I have 2 numbers: > <53147>
- (.*)\b(\d+)$ <I have 2 numbers: > <53147>
- (.*\D)(\d+)$ <I have 2 numbers: > <53147>
-</pre>
-<p>As you see, this can be a bit tricky. It’s important to realize that
a
-regular expression is merely a set of assertions that gives a definition
-of success. There may be 0, 1, or several different ways that the
-definition might succeed against a particular string. And if there are
-multiple ways it might succeed, you need to understand backtracking to
-know which variety of success you will achieve.
-</p>
-<p>When using look-ahead assertions and negations, this can all get even
-trickier. Imagine you’d like to find a sequence of non-digits not
-followed by "123". You might try to write that as
-</p>
-<pre class="verbatim"> $_ = "ABC123";
- if ( /^\D*(?!123)/ ) { # Wrong!
- print "Yup, no 123 in $_\n";
- }
-</pre>
-<p>But that isn’t going to match; at least, not the way you’re
hoping. It
-claims that there is no 123 in the string. Here’s a clearer picture of
-why that pattern matches, contrary to popular expectations:
-</p>
-<pre class="verbatim"> $x = 'ABC123';
- $y = 'ABC445';
-
- print "1: got $1\n" if $x =~ /^(ABC)(?!123)/;
- print "2: got $1\n" if $y =~ /^(ABC)(?!123)/;
-
- print "3: got $1\n" if $x =~ /^(\D*)(?!123)/;
- print "4: got $1\n" if $y =~ /^(\D*)(?!123)/;
-</pre>
-<p>This prints
-</p>
-<pre class="verbatim"> 2: got ABC
- 3: got AB
- 4: got ABC
-</pre>
-<p>You might have expected test 3 to fail because it seems to a more
-general purpose version of test 1. The important difference between
-them is that test 3 contains a quantifier (<code>\D*</code>) and so can use
-backtracking, whereas test 1 will not. What’s happening is
-that you’ve asked "Is it true that at the start of $x, following 0
or more
-non-digits, you have something that’s not 123?" If the pattern
matcher had
-let <code>\D*</code> expand to "ABC", this would have caused the
whole pattern to
-fail.
-</p>
-<p>The search engine will initially match <code>\D*</code> with
"ABC". Then it will
-try to match <code>(?!123)</code> with "123", which fails. But
because
-a quantifier (<code>\D*</code>) 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.
-</p>
-<p>The pattern really, <em>really</em> wants to succeed, so it uses the
-standard pattern back-off-and-retry and lets <code>\D*</code> expand to just
"AB" this
-time. Now there’s indeed something following "AB" that is not
-"123". It’s "C123", which suffices.
-</p>
-<p>We can deal with this by using both an assertion and a negation.
-We’ll say that the first part in $1 must be followed both by a digit
-and by something that’s not "123". Remember that the
look-aheads
-are zero-width expressions–they only look, but don’t consume any
-of the string in their match. So rewriting this way produces what
-you’d expect; that is, case 5 will fail, but case 6 succeeds:
-</p>
-<pre class="verbatim"> print "5: got $1\n" if $x =~
/^(\D*)(?=\d)(?!123)/;
- print "6: got $1\n" if $y =~ /^(\D*)(?=\d)(?!123)/;
-
- 6: got ABC
-</pre>
-<p>In other words, the two zero-width assertions next to each other work as
though
-they’re ANDed together, just as you’d use any built-in assertions:
<code>/^$/</code>
-matches only if you’re at the beginning of the line AND the end of the
-line simultaneously. The deeper underlying truth is that juxtaposition in
-regular expressions always means AND, except when you write an explicit OR
-using the vertical bar. <code>/ab/</code> means match "a" AND
(then) match "b",
-although the attempted matches are made at different positions because
"a"
-is not a zero-width assertion, but a one-width assertion.
-</p>
-<p><strong>WARNING</strong>: Particularly complicated regular expressions can
take
-exponential time to solve because of the immense number of possible
-ways they can use backtracking to try for a match. For example, without
-internal optimizations done by the regular expression engine, this will
-take a painfully long time to run:
-</p>
-<pre class="verbatim"> 'aaaaaaaaaaaa' =~ /((a{0,5}){0,5})*[c]/
-</pre>
-<p>And if you used <code>*</code>’s in the internal groups instead of
limiting them
-to 0 through 5 matches, then it would take forever–or until you ran
-out of stack space. Moreover, these internal optimizations are not
-always applicable. For example, if you put <code>{0,5}</code> instead of
<code>*</code>
-on the external group, no current optimization is applicable, and the
-match takes a long time to finish.
-</p>
-<p>A powerful tool for optimizing such beasts is what is known as an
-"independent group",
-which does not backtrack (see <a
href="#perlre-_0028_003f_003epattern_0029">(?>pattern)</a>). 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 <em>might</em> have influenced the
-following match, see <a
href="#perlre-_0028_003f_003epattern_0029">(?>pattern)</a>.
-</p>
-<hr>
-<a name="perlre-Version-8-Regular-Expressions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Warning-on-_005c1-Instead-of-_00241" accesskey="n"
rel="next">perlre Warning on \1 Instead of $1</a>, Previous: <a
href="#perlre-Backtracking" accesskey="p" rel="prev">perlre Backtracking</a>,
Up: <a href="#perlre-DESCRIPTION" accesskey="u" rel="up">perlre DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Version-8-Regular-Expressions"></a>
-<h4 class="subsection">58.2.7 Version 8 Regular Expressions</h4>
-
-<p>In case you’re not familiar with the "regular" Version 8
regex
-routines, here are the pattern-matching rules not described above.
-</p>
-<p>Any single character matches itself, unless it is a <em>metacharacter</em>
-with a special meaning described here or above. You can cause
-characters that normally function as metacharacters to be interpreted
-literally by prefixing them with a "\" (e.g., "\." matches
a ".", not any
-character; "\\" matches a "\"). This escape mechanism is
also required
-for the character used as the pattern delimiter.
-</p>
-<p>A series of characters matches that series of characters in the target
-string, so the pattern <code>blurfl</code> would match "blurfl" in
the target
-string.
-</p>
-<p>You can specify a character class, by enclosing a list of characters
-in <code>[]</code>, which will match any character from the list. If the
-first character after the "[" is "^", the class matches
any character not
-in the list. Within a list, the "-" character specifies a
-range, so that <code>a-z</code> represents all characters between
"a" and "z",
-inclusive. If you want either "-" or "]" itself to be a
member of a
-class, put it at the start of the list (possibly after a "^"), or
-escape it with a backslash. "-" is also taken literally when it is
-at the end of the list, just before the closing "]". (The
-following all specify the same class of three characters: <code>[-az]</code>,
-<code>[az-]</code>, and <code>[a\-z]</code>. All are different from
<code>[a-z]</code>, which
-specifies a class containing twenty-six characters, even on EBCDIC-based
-character sets.) Also, if you try to use the character
-classes <code>\w</code>, <code>\W</code>, <code>\s</code>, <code>\S</code>,
<code>\d</code>, or <code>\D</code> as endpoints of
-a range, the "-" is understood literally.
-</p>
-<p>Note also that the whole range idea is rather unportable between
-character sets, except for four situations that Perl handles specially.
-Any subset of the ranges <code>[A-Z]</code>, <code>[a-z]</code>, and
<code>[0-9]</code> are guaranteed
-to match the expected subset of ASCII characters, no matter what
-character set the platform is running. The fourth portable way to
-specify ranges is to use the <code>\N{...}</code> syntax to specify either end
-point of the range. For example, <code>[\N{U+04}-\N{U+07}]</code> means to
match
-the Unicode code points <code>\N{U+04}</code>, <code>\N{U+05}</code>,
<code>\N{U+06}</code>, and
-<code>\N{U+07}</code>, whatever their native values may be on the platform.
Under
-<a href="re.html#g_t_0027strict_0027-mode">(re)use re ’strict’</a>
or within a <a href="#perlre-_0028_003f_005b-_005d_0029">(?[ ])</a>, a warning
-is raised, if enabled, and the other end point of a range which has a
-<code>\N{...}</code> endpoint is not portably specified. For example,
-</p>
-<pre class="verbatim"> [\N{U+00}-\x06] # Warning under "use re
'strict'".
-</pre>
-<p>It is hard to understand without digging what exactly matches ranges
-other than subsets of <code>[A-Z]</code>, <code>[a-z]</code>, and
<code>[0-9]</code>. A sound
-principle is to use only ranges that begin from and end at either
-alphabetics of equal case ([a-e], [A-E]), or digits ([0-9]). Anything
-else is unsafe or unclear. If in doubt, spell out the range in full.
-</p>
-<p>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, \<em>nnn</em>, where
<em>nnn</em> is a string
-of three octal digits, matches the character whose coded character set value
-is <em>nnn</em>. Similarly, \x<em>nn</em>, where <em>nn</em> are hexadecimal
digits,
-matches the character whose ordinal is <em>nn</em>. The expression \c<em>x</em>
-matches the character control-<em>x</em>. Finally, the "."
metacharacter
-matches any character except "\n" (unless you use <code>/s</code>).
-</p>
-<p>You can specify a series of alternatives for a pattern using "|"
to
-separate them, so that <code>fee|fie|foe</code> will match any of
"fee", "fie",
-or "foe" in the target string (as would <code>f(e|i|o)e</code>). The
-first alternative includes everything from the last pattern delimiter
-("(", "(?:", etc. or the beginning of the pattern) up to
the first "|", and
-the last alternative contains everything from the last "|" to the
next
-closing pattern delimiter. That’s why it’s common practice to
include
-alternatives in parentheses: to minimize confusion about where they
-start and end.
-</p>
-<p>Alternatives are tried from left to right, so the first
-alternative found for which the entire expression matches, is the one that
-is chosen. This means that alternatives are not necessarily greedy. For
-example: when matching <code>foo|foot</code> against "barefoot",
only the "foo"
-part will match, as that is the first alternative tried, and it successfully
-matches the target string. (This might not seem important, but it is
-important when you are capturing matched text using parentheses.)
-</p>
-<p>Also remember that "|" is interpreted as a literal within square
brackets,
-so if you write <code>[fee|fie|foe]</code> you’re really only matching
<code>[feio|]</code>.
-</p>
-<p>Within a pattern, you may designate subpatterns for later reference
-by enclosing them in parentheses, and you may refer back to the
-<em>n</em>th subpattern later in the pattern using the metacharacter
-\<em>n</em> or \g<em>n</em>. 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, <code>(0|0x)\d*\s\g1\d*</code> will
-match "0x1234 0x4321", but not "0x1234 01234", because
subpattern
-1 matched "0x", even though the rule <code>0|0x</code> could
potentially match
-the leading 0 in the second number.
-</p>
-<hr>
-<a name="perlre-Warning-on-_005c1-Instead-of-_00241"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Repeated-Patterns-Matching-a-Zero_002dlength-Substring"
accesskey="n" rel="next">perlre Repeated Patterns Matching a Zero-length
Substring</a>, Previous: <a href="#perlre-Version-8-Regular-Expressions"
accesskey="p" rel="prev">perlre Version 8 Regular Expressions</a>, Up: <a
href="#perlre-DESCRIPTION" accesskey="u" rel="up">perlre DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Warning-on-_005c1-Instead-of-_00241"></a>
-<h4 class="subsection">58.2.8 Warning on \1 Instead of $1</h4>
-
-<p>Some people get too used to writing things like:
-</p>
-<pre class="verbatim"> $pattern =~ s/(\W)/\\\1/g;
-</pre>
-<p>This is grandfathered (for \1 to \9) for the RHS of a substitute to avoid
-shocking the
-<strong>sed</strong> addicts, but it’s a dirty habit to get into.
That’s because in
-PerlThink, the righthand side of an <code>s///</code> is a double-quoted
string. <code>\1</code> in
-the usual double-quoted string means a control-A. The customary Unix
-meaning of <code>\1</code> is kludged in for <code>s///</code>. However, if
you get into the habit
-of doing that, you get yourself into trouble if you then add an <code>/e</code>
-modifier.
-</p>
-<pre class="verbatim"> s/(\d+)/ \1 + 1 /eg; # causes warning
under -w
-</pre>
-<p>Or if you try to do
-</p>
-<pre class="verbatim"> s/(\d+)/\1000/;
-</pre>
-<p>You can’t disambiguate that by saying <code>\{1}000</code>, whereas
you can fix it with
-<code>${1}000</code>. The operation of interpolation should not be confused
-with the operation of matching a backreference. Certainly they mean two
-different things on the <em>left</em> side of the <code>s///</code>.
-</p>
-<hr>
-<a name="perlre-Repeated-Patterns-Matching-a-Zero_002dlength-Substring"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Combining-RE-Pieces" accesskey="n" rel="next">perlre
Combining RE Pieces</a>, Previous: <a
href="#perlre-Warning-on-_005c1-Instead-of-_00241" accesskey="p"
rel="prev">perlre Warning on \1 Instead of $1</a>, Up: <a
href="#perlre-DESCRIPTION" accesskey="u" rel="up">perlre DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Repeated-Patterns-Matching-a-Zero_002dlength-Substring"></a>
-<h4 class="subsection">58.2.9 Repeated Patterns Matching a Zero-length
Substring</h4>
-
-<p><strong>WARNING</strong>: Difficult material (and prose) ahead. This
section needs a rewrite.
-</p>
-<p>Regular expressions provide a terse and powerful programming language. As
-with most other power tools, power comes together with the ability
-to wreak havoc.
-</p>
-<p>A common abuse of this power stems from the ability to make infinite
-loops using regular expressions, with something as innocuous as:
-</p>
-<pre class="verbatim"> 'foo' =~ m{ ( o? )* }x;
-</pre>
-<p>The <code>o?</code> matches at the beginning of <code>'foo'</code>, and
since the position
-in the string is not moved by the match, <code>o?</code> would match again and
again
-because of the <code>*</code> quantifier. Another common way to create a
similar cycle
-is with the looping modifier <code>//g</code>:
-</p>
-<pre class="verbatim"> @matches = ( 'foo' =~ m{ o? }xg );
-</pre>
-<p>or
-</p>
-<pre class="verbatim"> print "match: <$&>\n" while
'foo' =~ m{ o? }xg;
-</pre>
-<p>or the loop implied by split().
-</p>
-<p>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:
-</p>
-<pre class="verbatim"> @chars = split //, $string; # // is not
magic in split
- ($whitewashed = $string) =~ s/()/ /g; # parens avoid magic s// /
-</pre>
-<p>Thus Perl allows such constructs, by <em>forcefully breaking
-the infinite loop</em>. The rules for this are different for lower-level
-loops given by the greedy quantifiers <code>*+{}</code>, and for higher-level
-ones like the <code>/g</code> modifier or split() operator.
-</p>
-<p>The lower-level loops are <em>interrupted</em> (that is, the loop is
-broken) when Perl detects that a repeated expression matched a
-zero-length substring. Thus
-</p>
-<pre class="verbatim"> m{ (?: NON_ZERO_LENGTH | ZERO_LENGTH )* }x;
-</pre>
-<p>is made equivalent to
-</p>
-<pre class="verbatim"> m{ (?: NON_ZERO_LENGTH )* (?: ZERO_LENGTH )? }x;
-</pre>
-<p>For example, this program
-</p>
-<pre class="verbatim"> #!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;
-</pre>
-<p>prints
-</p>
-<pre class="verbatim"> hello
- aaaaa
- b
-</pre>
-<p>Notice that "hello" is only printed once, as when Perl sees that
the sixth
-iteration of the outermost <code>(?:)*</code> matches a zero-length string, it
stops
-the <code>*</code>.
-</p>
-<p>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 <a
href="#perlre-Backtracking">Backtracking</a>),
-and so the <em>second best</em> match is chosen if the <em>best</em> match is
of
-zero length.
-</p>
-<p>For example:
-</p>
-<pre class="verbatim"> $_ = 'bar';
- s/\w??/<$&>/g;
-</pre>
-<p>results in
<code><><b><><a><><r><></code>. At
each position of the string the best
-match given by non-greedy <code>??</code> is the zero-length match, and the
<em>second
-best</em> match is what is matched by <code>\w</code>. Thus zero-length
matches
-alternate with one-character-long matches.
-</p>
-<p>Similarly, for repeated <code>m/()/g</code> the second-best match is the
match at the
-position one notch further in the string.
-</p>
-<p>The additional state of being <em>matched with zero-length</em> is
associated with
-the matched string, and is reset by each assignment to pos().
-Zero-length matches at the end of the previous match are ignored
-during <code>split</code>.
-</p>
-<hr>
-<a name="perlre-Combining-RE-Pieces"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Creating-Custom-RE-Engines" accesskey="n"
rel="next">perlre Creating Custom RE Engines</a>, Previous: <a
href="#perlre-Repeated-Patterns-Matching-a-Zero_002dlength-Substring"
accesskey="p" rel="prev">perlre Repeated Patterns Matching a Zero-length
Substring</a>, Up: <a href="#perlre-DESCRIPTION" accesskey="u" rel="up">perlre
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Combining-RE-Pieces"></a>
-<h4 class="subsection">58.2.10 Combining RE Pieces</h4>
-
-<p>Each of the elementary pieces of regular expressions which were described
-before (such as <code>ab</code> or <code>\Z</code>) 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 <code>ST</code>, <code>S|T</code>,
<code>S*</code> etc.
-(in these examples <code>S</code> and <code>T</code> are regular
subexpressions).
-</p>
-<p>Such combinations can include alternatives, leading to a problem of choice:
-if we match a regular expression <code>a|ab</code> against
<code>"abc"</code>, will it match
-substring <code>"a"</code> or <code>"ab"</code>? One way
to describe which substring is
-actually matched is the concept of backtracking (see <a
href="#perlre-Backtracking">Backtracking</a>).
-However, this description is too low-level and makes you think
-in terms of a particular implementation.
-</p>
-<p>Another description starts with notions of
"better"/"worse". All the
-substrings which may be matched by the given regular expression can be
-sorted from the "best" match to the "worst" match, and it
is the "best"
-match which is chosen. This substitutes the question of "what is
chosen?"
-by the question of "which matches are better, and which are worse?".
-</p>
-<p>Again, for elementary pieces there is no such question, since at most
-one match at a given position is possible. This section describes the
-notion of better/worse for combining operators. In the description
-below <code>S</code> and <code>T</code> are regular subexpressions.
-</p>
-<dl compact="compact">
-<dt><code>ST</code></dt>
-<dd><a name="perlre-ST"></a>
-<p>Consider two possible matches, <code>AB</code> and <code>A'B'</code>,
<code>A</code> and <code>A'</code> are
-substrings which can be matched by <code>S</code>, <code>B</code> and
<code>B'</code> are substrings
-which can be matched by <code>T</code>.
-</p>
-<p>If <code>A</code> is a better match for <code>S</code> than
<code>A'</code>, <code>AB</code> is a better
-match than <code>A'B'</code>.
-</p>
-<p>If <code>A</code> and <code>A'</code> coincide: <code>AB</code> is a better
match than <code>AB'</code> if
-<code>B</code> is a better match for <code>T</code> than <code>B'</code>.
-</p>
-</dd>
-<dt><code>S|T</code></dt>
-<dd><a name="perlre-S_007cT"></a>
-<p>When <code>S</code> can match, it is a better match than when only
<code>T</code> can match.
-</p>
-<p>Ordering of two matches for <code>S</code> is the same as for
<code>S</code>. Similar for
-two matches for <code>T</code>.
-</p>
-</dd>
-<dt><code>S{REPEAT_COUNT}</code></dt>
-<dd><a name="perlre-S_007bREPEAT_005fCOUNT_007d"></a>
-<p>Matches as <code>SSS...S</code> (repeated as many times as necessary).
-</p>
-</dd>
-<dt><code>S{min,max}</code></dt>
-<dd><a name="perlre-S_007bmin_002cmax_007d"></a>
-<p>Matches as <code>S{max}|S{max-1}|...|S{min+1}|S{min}</code>.
-</p>
-</dd>
-<dt><code>S{min,max}?</code></dt>
-<dd><a name="perlre-S_007bmin_002cmax_007d_003f"></a>
-<p>Matches as <code>S{min}|S{min+1}|...|S{max-1}|S{max}</code>.
-</p>
-</dd>
-<dt><code>S?</code>, <code>S*</code>, <code>S+</code></dt>
-<dd><a name="perlre-S_003f_002c-S_002a_002c-S_002b"></a>
-<p>Same as <code>S{0,1}</code>, <code>S{0,BIG_NUMBER}</code>,
<code>S{1,BIG_NUMBER}</code> respectively.
-</p>
-</dd>
-<dt><code>S??</code>, <code>S*?</code>, <code>S+?</code></dt>
-<dd><a name="perlre-S_003f_003f_002c-S_002a_003f_002c-S_002b_003f"></a>
-<p>Same as <code>S{0,1}?</code>, <code>S{0,BIG_NUMBER}?</code>,
<code>S{1,BIG_NUMBER}?</code> respectively.
-</p>
-</dd>
-<dt><code>(?>S)</code></dt>
-<dd><a name="perlre-_0028_003f_003eS_0029"></a>
-<p>Matches the best match for <code>S</code> and only that.
-</p>
-</dd>
-<dt><code>(?=S)</code>, <code>(?<=S)</code></dt>
-<dd><a name="perlre-_0028_003f_003dS_0029_002c-_0028_003f_003c_003dS_0029"></a>
-<p>Only the best match for <code>S</code> is considered. (This is important
only if
-<code>S</code> has capturing parentheses, and backreferences are used somewhere
-else in the whole regular expression.)
-</p>
-</dd>
-<dt><code>(?!S)</code>, <code>(?<!S)</code></dt>
-<dd><a name="perlre-_0028_003f_0021S_0029_002c-_0028_003f_003c_0021S_0029"></a>
-<p>For this grouping operator there is no need to describe the ordering, since
-only whether or not <code>S</code> can match is important.
-</p>
-</dd>
-<dt><code>(??{ EXPR })</code>, <code>(?<em>PARNO</em>)</code></dt>
-<dd><a
name="perlre-_0028_003f_003f_007b-EXPR-_007d_0029_002c-_0028_003fPARNO_0029"></a>
-<p>The ordering is the same as for the regular expression which is
-the result of EXPR, or the pattern contained by capture group <em>PARNO</em>.
-</p>
-</dd>
-<dt><code>(?(condition)yes-pattern|no-pattern)</code></dt>
-<dd><a
name="perlre-_0028_003f_0028condition_0029yes_002dpattern_007cno_002dpattern_0029-1"></a>
-<p>Recall that which of <code>yes-pattern</code> or <code>no-pattern</code>
actually matches is
-already determined. The ordering of the matches is the same as for the
-chosen subexpression.
-</p>
-</dd>
-</dl>
-
-<p>The above recipes describe the ordering of matches <em>at a given
position</em>.
-One more rule is needed to understand how a match is determined for the
-whole regular expression: a match at an earlier position is always better
-than a match at a later position.
-</p>
-<hr>
-<a name="perlre-Creating-Custom-RE-Engines"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-Embedded-Code-Execution-Frequency" accesskey="n"
rel="next">perlre Embedded Code Execution Frequency</a>, Previous: <a
href="#perlre-Combining-RE-Pieces" accesskey="p" rel="prev">perlre Combining RE
Pieces</a>, Up: <a href="#perlre-DESCRIPTION" accesskey="u" rel="up">perlre
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Creating-Custom-RE-Engines"></a>
-<h4 class="subsection">58.2.11 Creating Custom RE Engines</h4>
-
-<p>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
-<a href="#perlreapi-NAME">perlreapi NAME</a> for more details.
-</p>
-<p>As an alternative, overloaded constants (see <a
href="overload.html#Top">(overload)</a>) provide a simple
-way to extend the functionality of the RE engine, by substituting one
-pattern for another.
-</p>
-<p>Suppose that we want to enable a new RE escape-sequence <code>\Y|</code>
which
-matches at a boundary between whitespace characters and non-whitespace
-characters. Note that <code>(?=\S)(?<!\S)|(?!\S)(?<=\S)</code> matches
exactly
-at these positions, so we want to have each <code>\Y|</code> in the place of
the
-more complicated version. We can create a module <code>customre</code> to do
-this:
-</p>
-<pre class="verbatim"> package customre;
- use overload;
-
- sub import {
- shift;
- die "No argument to customre::import allowed" if @_;
- overload::constant 'qr' => \&convert;
- }
-
- sub invalid { die "/$_[0]/: invalid escape '\\$_[1]'"}
-
- # 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)/ );
- sub convert {
- my $re = shift;
- $re =~ s{
- \\ ( \\ | Y . )
- }
- { $rules{$1} or invalid($re,$1) }sgex;
- return $re;
- }
-</pre>
-<p>Now <code>use customre</code> enables the new escape in constant regular
-expressions, i.e., those without any runtime variable interpolations.
-As documented in <a href="overload.html#Top">(overload)</a>, this conversion
will work only over
-literal parts of regular expressions. For <code>\Y|$re\Y|</code> the variable
-part of this regular expression needs to be converted explicitly
-(but only if the special meaning of <code>\Y|</code> should be enabled inside
$re):
-</p>
-<pre class="verbatim"> use customre;
- $re = <>;
- chomp $re;
- $re = customre::convert $re;
- /\Y|$re\Y|/;
-</pre>
-<hr>
-<a name="perlre-Embedded-Code-Execution-Frequency"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-PCRE_002fPython-Support" accesskey="n"
rel="next">perlre PCRE/Python Support</a>, Previous: <a
href="#perlre-Creating-Custom-RE-Engines" accesskey="p" rel="prev">perlre
Creating Custom RE Engines</a>, Up: <a href="#perlre-DESCRIPTION" accesskey="u"
rel="up">perlre DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Embedded-Code-Execution-Frequency"></a>
-<h4 class="subsection">58.2.12 Embedded Code Execution Frequency</h4>
-
-<p>The exact rules for how often (??{}) and (?{}) are executed in a pattern
-are unspecified. In the case of a successful match you can assume that
-they DWIM and will be executed in left to right order the appropriate
-number of times in the accepting path of the pattern as would any other
-meta-pattern. How non-accepting pathways and match failures affect the
-number of times a pattern is executed is specifically unspecified and
-may vary depending on what optimizations can be applied to the pattern
-and is likely to change from version to version.
-</p>
-<p>For instance in
-</p>
-<pre class="verbatim"> "aaabcdeeeee"=~/a(?{print
"a"})b(?{print "b"})cde/;
-</pre>
-<p>the exact number of times "a" or "b" are printed out is
unspecified for
-failure, but you may assume they will be printed at least once during
-a successful match, additionally you may assume that if "b" is
printed,
-it will be preceded by at least one "a".
-</p>
-<p>In the case of branching constructs like the following:
-</p>
-<pre class="verbatim"> /a(b|(?{ print "a" }))c(?{ print
"c" })/;
-</pre>
-<p>you can assume that the input "ac" will output "ac",
and that "abc"
-will output only "c".
-</p>
-<p>When embedded code is quantified, successful matches will call the
-code once for each matched iteration of the quantifier. For
-example:
-</p>
-<pre class="verbatim"> "good" =~ /g(?:o(?{print "o"}))*d/;
-</pre>
-<p>will output "o" twice.
-</p>
-<hr>
-<a name="perlre-PCRE_002fPython-Support"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlre-Embedded-Code-Execution-Frequency" accesskey="p"
rel="prev">perlre Embedded Code Execution Frequency</a>, Up: <a
href="#perlre-DESCRIPTION" accesskey="u" rel="up">perlre DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="PCRE_002fPython-Support"></a>
-<h4 class="subsection">58.2.13 PCRE/Python Support</h4>
-
-<p>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:
-</p>
-<dl compact="compact">
-<dt><code>(?P<NAME>pattern)</code></dt>
-<dd><a name="perlre-_0028_003fP_003cNAME_003epattern_0029"></a>
-<p>Define a named capture group. Equivalent to
<code>(?<NAME>pattern)</code>.
-</p>
-</dd>
-<dt><code>(?P=NAME)</code></dt>
-<dd><a name="perlre-_0028_003fP_003dNAME_0029"></a>
-<p>Backreference to a named capture group. Equivalent to <code>\g{NAME}</code>.
-</p>
-</dd>
-<dt><code>(?P>NAME)</code></dt>
-<dd><a name="perlre-_0028_003fP_003eNAME_0029"></a>
-<p>Subroutine call to a named capture group. Equivalent to
<code>(?&NAME)</code>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlre-BUGS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlre-SEE-ALSO" accesskey="n" rel="next">perlre SEE ALSO</a>,
Previous: <a href="#perlre-DESCRIPTION" accesskey="p" rel="prev">perlre
DESCRIPTION</a>, Up: <a href="#perlre" accesskey="u" rel="up">perlre</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="BUGS-6"></a>
-<h3 class="section">58.3 BUGS</h3>
-
-<p>Many regular expression constructs don’t work on EBCDIC platforms.
-</p>
-<p>There are a number of issues with regard to case-insensitive matching
-in Unicode rules. See <code>i</code> under <a
href="#perlre-Modifiers">Modifiers</a> above.
-</p>
-<p>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.
-</p>
-<p>This document needs a rewrite that separates the tutorial content
-from the reference content.
-</p>
-<hr>
-<a name="perlre-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlre-BUGS" accesskey="p" rel="prev">perlre BUGS</a>, Up:
<a href="#perlre" accesskey="u" rel="up">perlre</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-30"></a>
-<h3 class="section">58.4 SEE ALSO</h3>
-
-<p><a href="#perlrequick-NAME">perlrequick NAME</a>.
-</p>
-<p><a href="#perlretut-NAME">perlretut NAME</a>.
-</p>
-<p><a href="#perlop-Regexp-Quote_002dLike-Operators">perlop Regexp Quote-Like
Operators</a>.
-</p>
-<p><a href="#perlop-Gory-details-of-parsing-quoted-constructs">perlop Gory
details of parsing quoted constructs</a>.
-</p>
-<p><a href="perlfaq6.html#Top">(perlfaq6)</a>.
-</p>
-<p><a href="#perlfunc-pos">perlfunc pos</a>.
-</p>
-<p><a href="#perllocale-NAME">perllocale NAME</a>.
-</p>
-<p><a href="#perlebcdic-NAME">perlebcdic NAME</a>.
-</p>
-<p><em>Mastering Regular Expressions</em> by Jeffrey Friedl, published
-by O’Reilly and Associates.
-</p>
-<hr>
-<a name="perlreapi"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash" accesskey="n" rel="next">perlrebackslash</a>,
Previous: <a href="#perlre" accesskey="p" rel="prev">perlre</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlreapi-1"></a>
-<h2 class="chapter">59 perlreapi</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlreapi-NAME"
accesskey="1">perlreapi NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-DESCRIPTION"
accesskey="2">perlreapi DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-Callbacks"
accesskey="3">perlreapi Callbacks</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-The-REGEXP-structure" accesskey="4">perlreapi The REGEXP
structure</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-HISTORY"
accesskey="5">perlreapi HISTORY</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-AUTHORS"
accesskey="6">perlreapi AUTHORS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-LICENSE"
accesskey="7">perlreapi LICENSE</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreapi-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-DESCRIPTION" accesskey="n" rel="next">perlreapi
DESCRIPTION</a>, Up: <a href="#perlreapi" accesskey="u" rel="up">perlreapi</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-58"></a>
-<h3 class="section">59.1 NAME</h3>
-
-<p>perlreapi - Perl regular expression plugin interface
-</p>
-<hr>
-<a name="perlreapi-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-Callbacks" accesskey="n" rel="next">perlreapi
Callbacks</a>, Previous: <a href="#perlreapi-NAME" accesskey="p"
rel="prev">perlreapi NAME</a>, Up: <a href="#perlreapi" accesskey="u"
rel="up">perlreapi</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-57"></a>
-<h3 class="section">59.2 DESCRIPTION</h3>
-
-<p>As of Perl 5.9.5 there is a new interface for plugging and using
-regular expression engines other than the default one.
-</p>
-<p>Each engine is supposed to provide access to a constant structure of the
-following format:
-</p>
-<pre class="verbatim"> typedef struct regexp_engine {
- REGEXP* (*comp) (pTHX_
- const SV * const pattern, const U32 flags);
- I32 (*exec) (pTHX_
- REGEXP * const rx,
- char* stringarg,
- char* strend, char* strbeg,
- SSize_t minend, SV* sv,
- void* data, U32 flags);
- char* (*intuit) (pTHX_
- REGEXP * const rx, SV *sv,
- const char * const strbeg,
- char *strpos, char *strend, U32 flags,
- struct re_scream_pos_data_s *data);
- SV* (*checkstr) (pTHX_ REGEXP * const rx);
- void (*free) (pTHX_ REGEXP * const rx);
- void (*numbered_buff_FETCH) (pTHX_
- REGEXP * const rx,
- const I32 paren,
- SV * const sv);
- void (*numbered_buff_STORE) (pTHX_
- REGEXP * const rx,
- const I32 paren,
- SV const * const value);
- I32 (*numbered_buff_LENGTH) (pTHX_
- REGEXP * const rx,
- const SV * const sv,
- const I32 paren);
- SV* (*named_buff) (pTHX_
- REGEXP * const rx,
- SV * const key,
- SV * const value,
- U32 flags);
- SV* (*named_buff_iter) (pTHX_
- REGEXP * const rx,
- const SV * const lastkey,
- const U32 flags);
- SV* (*qr_package)(pTHX_ REGEXP * const rx);
- #ifdef USE_ITHREADS
- void* (*dupe) (pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
- #endif
- REGEXP* (*op_comp) (...);
-</pre>
-<p>When a regexp is compiled, its <code>engine</code> field is then set to
point at
-the appropriate structure, so that when it needs to be used Perl can find
-the right routines to do so.
-</p>
-<p>In order to install a new regexp handler, <code>$^H{regcomp}</code> is set
-to an integer which (when casted appropriately) resolves to one of these
-structures. When compiling, the <code>comp</code> method is executed, and the
-resulting <code>regexp</code> structure’s engine field is expected to
point back at
-the same structure.
-</p>
-<p>The pTHX_ symbol in the definition is a macro used by Perl under threading
-to provide an extra argument to the routine holding a pointer back to
-the interpreter that is executing the regexp. So under threading all
-routines get an extra argument.
-</p>
-<hr>
-<a name="perlreapi-Callbacks"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-The-REGEXP-structure" accesskey="n"
rel="next">perlreapi The REGEXP structure</a>, Previous: <a
href="#perlreapi-DESCRIPTION" accesskey="p" rel="prev">perlreapi
DESCRIPTION</a>, Up: <a href="#perlreapi" accesskey="u" rel="up">perlreapi</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Callbacks-1"></a>
-<h3 class="section">59.3 Callbacks</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlreapi-comp"
accesskey="1">perlreapi comp</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-exec"
accesskey="2">perlreapi exec</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-intuit"
accesskey="3">perlreapi intuit</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-checkstr"
accesskey="4">perlreapi checkstr</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-free"
accesskey="5">perlreapi free</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-Numbered-capture-callbacks" accesskey="6">perlreapi Numbered
capture callbacks</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-Named-capture-callbacks" accesskey="7">perlreapi Named capture
callbacks</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-qr_005fpackage"
accesskey="8">perlreapi qr_package</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-dupe"
accesskey="9">perlreapi dupe</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-op_005fcomp">perlreapi
op_comp</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreapi-comp"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-exec" accesskey="n" rel="next">perlreapi exec</a>,
Up: <a href="#perlreapi-Callbacks" accesskey="u" rel="up">perlreapi
Callbacks</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="comp"></a>
-<h4 class="subsection">59.3.1 comp</h4>
-
-<pre class="verbatim"> REGEXP* comp(pTHX_ const SV * const pattern, const
U32 flags);
-</pre>
-<p>Compile the pattern stored in <code>pattern</code> using the given
<code>flags</code> and
-return a pointer to a prepared <code>REGEXP</code> structure that can perform
-the match. See <a href="#perlreapi-The-REGEXP-structure">The REGEXP
structure</a> below for an explanation of
-the individual fields in the REGEXP struct.
-</p>
-<p>The <code>pattern</code> parameter is the scalar that was used as the
-pattern. Previous versions of Perl would pass two <code>char*</code>
indicating
-the start and end of the stringified pattern; the following snippet can
-be used to get the old parameters:
-</p>
-<pre class="verbatim"> STRLEN plen;
- char* exp = SvPV(pattern, plen);
- char* xend = exp + plen;
-</pre>
-<p>Since any scalar can be passed as a pattern, it’s possible to
implement
-an engine that does something with an array (<code>"ook" =~ [ qw/ eek
-hlagh / ]</code>) or with the non-stringified form of a compiled regular
-expression (<code>"ook" =~ qr/eek/</code>). Perl’s own engine
will always
-stringify everything using the snippet above, but that doesn’t mean
-other engines have to.
-</p>
-<p>The <code>flags</code> parameter is a bitfield which indicates which of the
-<code>msixpn</code> flags the regex was compiled with. It also contains
-additional info, such as if <code>use locale</code> is in effect.
-</p>
-<p>The <code>eogc</code> flags are stripped out before being passed to the comp
-routine. The regex engine does not need to know if any of these
-are set, as those flags should only affect what Perl does with the
-pattern and its match variables, not how it gets compiled and
-executed.
-</p>
-<p>By the time the comp callback is called, some of these flags have
-already had effect (noted below where applicable). However most of
-their effect occurs after the comp callback has run, in routines that
-read the <code>rx->extflags</code> field which it populates.
-</p>
-<p>In general the flags should be preserved in <code>rx->extflags</code>
after
-compilation, although the regex engine might want to add or delete
-some of them to invoke or disable some special behavior in Perl. The
-flags along with any special behavior they cause are documented below:
-</p>
-<p>The pattern modifiers:
-</p>
-<dl compact="compact">
-<dt><code>/m</code> - RXf_PMf_MULTILINE</dt>
-<dd><a name="perlreapi-_002fm-_002d-RXf_005fPMf_005fMULTILINE"></a>
-<p>If this is in <code>rx->extflags</code> it will be passed to
-<code>Perl_fbm_instr</code> by <code>pp_split</code> which will treat the
subject string
-as a multi-line string.
-</p>
-</dd>
-<dt><code>/s</code> - RXf_PMf_SINGLELINE</dt>
-<dd><a name="perlreapi-_002fs-_002d-RXf_005fPMf_005fSINGLELINE"></a>
-</dd>
-<dt><code>/i</code> - RXf_PMf_FOLD</dt>
-<dd><a name="perlreapi-_002fi-_002d-RXf_005fPMf_005fFOLD"></a>
-</dd>
-<dt><code>/x</code> - RXf_PMf_EXTENDED</dt>
-<dd><a name="perlreapi-_002fx-_002d-RXf_005fPMf_005fEXTENDED"></a>
-<p>If present on a regex, <code>"#"</code> comments will be handled
differently by the
-tokenizer in some cases.
-</p>
-<p>TODO: Document those cases.
-</p>
-</dd>
-<dt><code>/p</code> - RXf_PMf_KEEPCOPY</dt>
-<dd><a name="perlreapi-_002fp-_002d-RXf_005fPMf_005fKEEPCOPY"></a>
-<p>TODO: Document this
-</p>
-</dd>
-<dt>Character set</dt>
-<dd><a name="perlreapi-Character-set"></a>
-<p>The character set rules 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
-<code>get_regex_charset(const U32 flags)</code>. The only currently documented
-value returned from it is REGEX_LOCALE_CHARSET, which is set if
-<code>use locale</code> is in effect. If present in
<code>rx->extflags</code>,
-<code>split</code> will use the locale dependent definition of whitespace
-when RXf_SKIPWHITE or RXf_WHITE is in effect. ASCII whitespace
-is defined as per <a href="perlapi.html#isSPACE">(perlapi)isSPACE</a>, and by
the internal
-macros <code>is_utf8_space</code> under UTF-8, and <code>isSPACE_LC</code>
under <code>use
-locale</code>.
-</p>
-</dd>
-</dl>
-
-<p>Additional flags:
-</p>
-<dl compact="compact">
-<dt>RXf_SPLIT</dt>
-<dd><a name="perlreapi-RXf_005fSPLIT"></a>
-<p>This flag was removed in perl 5.18.0. <code>split ' '</code> is now
special-cased
-solely in the parser. RXf_SPLIT is still #defined, so you can test for it.
-This is how it used to work:
-</p>
-<p>If <code>split</code> is invoked as <code>split ' '</code> or with no
arguments (which
-really means <code>split(' ', $_)</code>, see <a
href="#perlfunc-split">split</a>), Perl will
-set this flag. The regex engine can then check for it and set the
-SKIPWHITE and WHITE extflags. To do this, the Perl engine does:
-</p>
-<pre class="verbatim"> if (flags & RXf_SPLIT && r->prelen ==
1 && r->precomp[0] == ' ')
- r->extflags |= (RXf_SKIPWHITE|RXf_WHITE);
-</pre>
-</dd>
-</dl>
-
-<p>These flags can be set during compilation to enable optimizations in
-the <code>split</code> operator.
-</p>
-<dl compact="compact">
-<dt>RXf_SKIPWHITE</dt>
-<dd><a name="perlreapi-RXf_005fSKIPWHITE"></a>
-<p>This flag was removed in perl 5.18.0. It is still #defined, so you can
-set it, but doing so will have no effect. This is how it used to work:
-</p>
-<p>If the flag is present in <code>rx->extflags</code> <code>split</code>
will delete
-whitespace from the start of the subject string before it’s operated
-on. What is considered whitespace depends on if the subject is a
-UTF-8 string and if the <code>RXf_PMf_LOCALE</code> flag is set.
-</p>
-<p>If RXf_WHITE is set in addition to this flag, <code>split</code> will
behave like
-<code>split " "</code> under the Perl engine.
-</p>
-</dd>
-<dt>RXf_START_ONLY</dt>
-<dd><a name="perlreapi-RXf_005fSTART_005fONLY"></a>
-<p>Tells the split operator to split the target string on newlines
-(<code>\n</code>) without invoking the regex engine.
-</p>
-<p>Perl’s engine sets this if the pattern is <code>/^/</code>
(<code>plen == 1 && *exp
-== '^'</code>), even under <code>/^/s</code>; see <a
href="#perlfunc-NAME">split</a>. Of course a
-different regex engine might want to use the same optimizations
-with a different syntax.
-</p>
-</dd>
-<dt>RXf_WHITE</dt>
-<dd><a name="perlreapi-RXf_005fWHITE"></a>
-<p>Tells the split operator to split the target string on whitespace
-without invoking the regex engine. The definition of whitespace varies
-depending on if the target string is a UTF-8 string and on
-if RXf_PMf_LOCALE is set.
-</p>
-<p>Perl’s engine sets this flag if the pattern is <code>\s+</code>.
-</p>
-</dd>
-<dt>RXf_NULL</dt>
-<dd><a name="perlreapi-RXf_005fNULL"></a>
-<p>Tells the split operator to split the target string on
-characters. The definition of character varies depending on if
-the target string is a UTF-8 string.
-</p>
-<p>Perl’s engine sets this flag on empty patterns, this optimization
-makes <code>split //</code> much faster than it would otherwise be.
It’s even
-faster than <code>unpack</code>.
-</p>
-</dd>
-<dt>RXf_NO_INPLACE_SUBST</dt>
-<dd><a name="perlreapi-RXf_005fNO_005fINPLACE_005fSUBST"></a>
-<p>Added in perl 5.18.0, this flag indicates that a regular expression might
-perform an operation that would interfere with inplace substitution. For
-instance it might contain lookbehind, or assign to non-magical variables
-(such as $REGMARK and $REGERROR) during matching. <code>s///</code> will skip
-certain optimisations when this is set.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlreapi-exec"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-intuit" accesskey="n" rel="next">perlreapi
intuit</a>, Previous: <a href="#perlreapi-comp" accesskey="p"
rel="prev">perlreapi comp</a>, Up: <a href="#perlreapi-Callbacks" accesskey="u"
rel="up">perlreapi Callbacks</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="exec"></a>
-<h4 class="subsection">59.3.2 exec</h4>
-
-<pre class="verbatim"> I32 exec(pTHX_ REGEXP * const rx,
- char *stringarg, char* strend, char* strbeg,
- SSize_t minend, SV* sv,
- void* data, U32 flags);
-</pre>
-<p>Execute a regexp. The arguments are
-</p>
-<dl compact="compact">
-<dt>rx</dt>
-<dd><a name="perlreapi-rx"></a>
-<p>The regular expression to execute.
-</p>
-</dd>
-<dt>sv</dt>
-<dd><a name="perlreapi-sv"></a>
-<p>This is the SV to be matched against. Note that the
-actual char array to be matched against is supplied by the arguments
-described below; the SV is just used to determine UTF8ness, <code>pos()</code>
etc.
-</p>
-</dd>
-<dt>strbeg</dt>
-<dd><a name="perlreapi-strbeg"></a>
-<p>Pointer to the physical start of the string.
-</p>
-</dd>
-<dt>strend</dt>
-<dd><a name="perlreapi-strend"></a>
-<p>Pointer to the character following the physical end of the string (i.e.
-the <code>\0</code>, if any).
-</p>
-</dd>
-<dt>stringarg</dt>
-<dd><a name="perlreapi-stringarg"></a>
-<p>Pointer to the position in the string where matching should start; it might
-not be equal to <code>strbeg</code> (for example in a later iteration of
<code>/.../g</code>).
-</p>
-</dd>
-<dt>minend</dt>
-<dd><a name="perlreapi-minend"></a>
-<p>Minimum length of string (measured in bytes from <code>stringarg</code>)
that must
-match; if the engine reaches the end of the match but hasn’t reached this
-position in the string, it should fail.
-</p>
-</dd>
-<dt>data</dt>
-<dd><a name="perlreapi-data"></a>
-<p>Optimisation data; subject to change.
-</p>
-</dd>
-<dt>flags</dt>
-<dd><a name="perlreapi-flags"></a>
-<p>Optimisation flags; subject to change.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlreapi-intuit"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-checkstr" accesskey="n" rel="next">perlreapi
checkstr</a>, Previous: <a href="#perlreapi-exec" accesskey="p"
rel="prev">perlreapi exec</a>, Up: <a href="#perlreapi-Callbacks" accesskey="u"
rel="up">perlreapi Callbacks</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="intuit"></a>
-<h4 class="subsection">59.3.3 intuit</h4>
-
-<pre class="verbatim"> char* intuit(pTHX_
- REGEXP * const rx,
- SV *sv,
- const char * const strbeg,
- char *strpos,
- char *strend,
- const U32 flags,
- struct re_scream_pos_data_s *data);
-</pre>
-<p>Find the start position where a regex match should be attempted,
-or possibly if the regex engine should not be run because the
-pattern can’t match. This is called, as appropriate, by the core,
-depending on the values of the <code>extflags</code> member of the
<code>regexp</code>
-structure.
-</p>
-<p>Arguments:
-</p>
-<pre class="verbatim"> rx: the regex to match against
- sv: the SV being matched: only used for utf8 flag; the string
- itself is accessed via the pointers below. Note that on
- something like an overloaded SV, SvPOK(sv) may be false
- and the string pointers may point to something unrelated to
- the SV itself.
- strbeg: real beginning of string
- strpos: the point in the string at which to begin matching
- strend: pointer to the byte following the last char of the string
- flags currently unused; set to 0
- data: currently unused; set to NULL
-</pre>
-<hr>
-<a name="perlreapi-checkstr"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-free" accesskey="n" rel="next">perlreapi free</a>,
Previous: <a href="#perlreapi-intuit" accesskey="p" rel="prev">perlreapi
intuit</a>, Up: <a href="#perlreapi-Callbacks" accesskey="u" rel="up">perlreapi
Callbacks</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="checkstr"></a>
-<h4 class="subsection">59.3.4 checkstr</h4>
-
-<pre class="verbatim"> SV* checkstr(pTHX_ REGEXP * const rx);
-</pre>
-<p>Return a SV containing a string that must appear in the pattern. Used
-by <code>split</code> for optimising matches.
-</p>
-<hr>
-<a name="perlreapi-free"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-Numbered-capture-callbacks" accesskey="n"
rel="next">perlreapi Numbered capture callbacks</a>, Previous: <a
href="#perlreapi-checkstr" accesskey="p" rel="prev">perlreapi checkstr</a>, Up:
<a href="#perlreapi-Callbacks" accesskey="u" rel="up">perlreapi Callbacks</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="free"></a>
-<h4 class="subsection">59.3.5 free</h4>
-
-<pre class="verbatim"> void free(pTHX_ REGEXP * const rx);
-</pre>
-<p>Called by Perl when it is freeing a regexp pattern so that the engine
-can release any resources pointed to by the <code>pprivate</code> member of the
-<code>regexp</code> structure. This is only responsible for freeing private
data;
-Perl will handle releasing anything else contained in the <code>regexp</code>
structure.
-</p>
-<hr>
-<a name="perlreapi-Numbered-capture-callbacks"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-Named-capture-callbacks" accesskey="n"
rel="next">perlreapi Named capture callbacks</a>, Previous: <a
href="#perlreapi-free" accesskey="p" rel="prev">perlreapi free</a>, Up: <a
href="#perlreapi-Callbacks" accesskey="u" rel="up">perlreapi Callbacks</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Numbered-capture-callbacks"></a>
-<h4 class="subsection">59.3.6 Numbered capture callbacks</h4>
-
-<p>Called to get/set the value of <code>$`</code>, <code>$'</code>,
<code>$&</code> and their named
-equivalents, ${^PREMATCH}, ${^POSTMATCH} and ${^MATCH}, as well as the
-numbered capture groups (<code>$1</code>, <code>$2</code>, ...).
-</p>
-<p>The <code>paren</code> parameter will be <code>1</code> for
<code>$1</code>, <code>2</code> for <code>$2</code> and so
-forth, and have these symbolic values for the special variables:
-</p>
-<pre class="verbatim"> ${^PREMATCH} RX_BUFF_IDX_CARET_PREMATCH
- ${^POSTMATCH} RX_BUFF_IDX_CARET_POSTMATCH
- ${^MATCH} RX_BUFF_IDX_CARET_FULLMATCH
- $` RX_BUFF_IDX_PREMATCH
- $' RX_BUFF_IDX_POSTMATCH
- $& RX_BUFF_IDX_FULLMATCH
-</pre>
-<p>Note that in Perl 5.17.3 and earlier, the last three constants were also
-used for the caret variants of the variables.
-</p>
-<p>The names have been chosen by analogy with <a
href="Tie-Scalar.html#Top">(Tie-Scalar)</a> methods
-names with an additional <strong>LENGTH</strong> callback for efficiency.
However
-named capture variables are currently not tied internally but
-implemented via magic.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlreapi-numbered_005fbuff_005fFETCH" accesskey="1">perlreapi
numbered_buff_FETCH</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-numbered_005fbuff_005fSTORE" accesskey="2">perlreapi
numbered_buff_STORE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-numbered_005fbuff_005fLENGTH" accesskey="3">perlreapi
numbered_buff_LENGTH</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreapi-numbered_005fbuff_005fFETCH"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-numbered_005fbuff_005fSTORE" accesskey="n"
rel="next">perlreapi numbered_buff_STORE</a>, Up: <a
href="#perlreapi-Numbered-capture-callbacks" accesskey="u" rel="up">perlreapi
Numbered capture callbacks</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="numbered_005fbuff_005fFETCH"></a>
-<h4 class="subsubsection">59.3.6.1 numbered_buff_FETCH</h4>
-
-<pre class="verbatim"> void numbered_buff_FETCH(pTHX_ REGEXP * const rx,
const I32 paren,
- SV * const sv);
-</pre>
-<p>Fetch a specified numbered capture. <code>sv</code> should be set to the
scalar
-to return, the scalar is passed as an argument rather than being
-returned from the function because when it’s called Perl already has a
-scalar to store the value, creating another one would be
-redundant. The scalar can be set with <code>sv_setsv</code>,
<code>sv_setpvn</code> and
-friends, see <a href="perlapi.html#Top">(perlapi)</a>.
-</p>
-<p>This callback is where Perl untaints its own capture variables under
-taint mode (see <a href="#perlsec-NAME">perlsec NAME</a>). See the
<code>Perl_reg_numbered_buff_fetch</code>
-function in <samp>regcomp.c</samp> for how to untaint capture variables if
-that’s something you’d like your engine to do as well.
-</p>
-<hr>
-<a name="perlreapi-numbered_005fbuff_005fSTORE"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-numbered_005fbuff_005fLENGTH" accesskey="n"
rel="next">perlreapi numbered_buff_LENGTH</a>, Previous: <a
href="#perlreapi-numbered_005fbuff_005fFETCH" accesskey="p"
rel="prev">perlreapi numbered_buff_FETCH</a>, Up: <a
href="#perlreapi-Numbered-capture-callbacks" accesskey="u" rel="up">perlreapi
Numbered capture callbacks</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="numbered_005fbuff_005fSTORE"></a>
-<h4 class="subsubsection">59.3.6.2 numbered_buff_STORE</h4>
-
-<pre class="verbatim"> void (*numbered_buff_STORE) (pTHX_
- REGEXP * const rx,
- const I32 paren,
- SV const * const value);
-</pre>
-<p>Set the value of a numbered capture variable. <code>value</code> is the
scalar
-that is to be used as the new value. It’s up to the engine to make
-sure this is used as the new value (or reject it).
-</p>
-<p>Example:
-</p>
-<pre class="verbatim"> if ("ook" =~ /(o*)/) {
- # 'paren' will be '1' and 'value' will be 'ee'
- $1 =~ tr/o/e/;
- }
-</pre>
-<p>Perl’s own engine will croak on any attempt to modify the capture
-variables, to do this in another engine use the following callback
-(copied from <code>Perl_reg_numbered_buff_store</code>):
-</p>
-<pre class="verbatim"> void
- Example_reg_numbered_buff_store(pTHX_
- REGEXP * const rx,
- const I32 paren,
- SV const * const value)
- {
- PERL_UNUSED_ARG(rx);
- PERL_UNUSED_ARG(paren);
- PERL_UNUSED_ARG(value);
-
- if (!PL_localizing)
- Perl_croak(aTHX_ PL_no_modify);
- }
-</pre>
-<p>Actually Perl will not <em>always</em> croak in a statement that looks
-like it would modify a numbered capture variable. This is because the
-STORE callback will not be called if Perl can determine that it
-doesn’t have to modify the value. This is exactly how tied variables
-behave in the same situation:
-</p>
-<pre class="verbatim"> package CaptureVar;
- use parent 'Tie::Scalar';
-
- sub TIESCALAR { bless [] }
- sub FETCH { undef }
- sub STORE { die "This doesn't get called" }
-
- package main;
-
- tie my $sv => "CaptureVar";
- $sv =~ y/a/b/;
-</pre>
-<p>Because <code>$sv</code> is <code>undef</code> when the <code>y///</code>
operator is applied to it,
-the transliteration won’t actually execute and the program won’t
-<code>die</code>. This is different to how 5.8 and earlier versions behaved
-since the capture variables were READONLY variables then; now they’ll
-just die when assigned to in the default engine.
-</p>
-<hr>
-<a name="perlreapi-numbered_005fbuff_005fLENGTH"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreapi-numbered_005fbuff_005fSTORE" accesskey="p"
rel="prev">perlreapi numbered_buff_STORE</a>, Up: <a
href="#perlreapi-Numbered-capture-callbacks" accesskey="u" rel="up">perlreapi
Numbered capture callbacks</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="numbered_005fbuff_005fLENGTH"></a>
-<h4 class="subsubsection">59.3.6.3 numbered_buff_LENGTH</h4>
-
-<pre class="verbatim"> I32 numbered_buff_LENGTH (pTHX_
- REGEXP * const rx,
- const SV * const sv,
- const I32 paren);
-</pre>
-<p>Get the <code>length</code> of a capture variable. There’s a special
callback
-for this so that Perl doesn’t have to do a FETCH and run
<code>length</code> on
-the result, since the length is (in Perl’s case) known from an offset
-stored in <code>rx->offs</code>, this is much more efficient:
-</p>
-<pre class="verbatim"> I32 s1 = rx->offs[paren].start;
- I32 s2 = rx->offs[paren].end;
- I32 len = t1 - s1;
-</pre>
-<p>This is a little bit more complex in the case of UTF-8, see what
-<code>Perl_reg_numbered_buff_length</code> does with
-<a
href="perlapi.html#is_005futf8_005fstring_005floclen">(perlapi)is_utf8_string_loclen</a>.
-</p>
-<hr>
-<a name="perlreapi-Named-capture-callbacks"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-qr_005fpackage" accesskey="n" rel="next">perlreapi
qr_package</a>, Previous: <a href="#perlreapi-Numbered-capture-callbacks"
accesskey="p" rel="prev">perlreapi Numbered capture callbacks</a>, Up: <a
href="#perlreapi-Callbacks" accesskey="u" rel="up">perlreapi Callbacks</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Named-capture-callbacks"></a>
-<h4 class="subsection">59.3.7 Named capture callbacks</h4>
-
-<p>Called to get/set the value of <code>%+</code> and <code>%-</code>, as well
as by some
-utility functions in <a href="re.html#Top">(re)</a>.
-</p>
-<p>There are two callbacks, <code>named_buff</code> is called in all the cases
the
-FETCH, STORE, DELETE, CLEAR, EXISTS and SCALAR <a
href="Tie-Hash.html#Top">(Tie-Hash)</a> callbacks
-would be on changes to <code>%+</code> and <code>%-</code> and
<code>named_buff_iter</code> in the
-same cases as FIRSTKEY and NEXTKEY.
-</p>
-<p>The <code>flags</code> parameter can be used to determine which of these
-operations the callbacks should respond to. The following flags are
-currently defined:
-</p>
-<p>Which <a href="Tie-Hash.html#Top">(Tie-Hash)</a> operation is being
performed from the Perl level on
-<code>%+</code> or <code>%+</code>, if any:
-</p>
-<pre class="verbatim"> RXapif_FETCH
- RXapif_STORE
- RXapif_DELETE
- RXapif_CLEAR
- RXapif_EXISTS
- RXapif_SCALAR
- RXapif_FIRSTKEY
- RXapif_NEXTKEY
-</pre>
-<p>If <code>%+</code> or <code>%-</code> is being operated on, if any.
-</p>
-<pre class="verbatim"> RXapif_ONE /* %+ */
- RXapif_ALL /* %- */
-</pre>
-<p>If this is being called as <code>re::regname</code>,
<code>re::regnames</code> or
-<code>re::regnames_count</code>, if any. The first two will be combined with
-<code>RXapif_ONE</code> or <code>RXapif_ALL</code>.
-</p>
-<pre class="verbatim"> RXapif_REGNAME
- RXapif_REGNAMES
- RXapif_REGNAMES_COUNT
-</pre>
-<p>Internally <code>%+</code> and <code>%-</code> are implemented with a real
tied interface
-via <a href="Tie-Hash-NamedCapture.html#Top">(Tie-Hash-NamedCapture)</a>. The
methods in that package will call
-back into these functions. However the usage of
-<a href="Tie-Hash-NamedCapture.html#Top">(Tie-Hash-NamedCapture)</a> for this
purpose might change in future
-releases. For instance this might be implemented by magic instead
-(would need an extension to mgvtbl).
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlreapi-named_005fbuff"
accesskey="1">perlreapi named_buff</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-named_005fbuff_005fiter" accesskey="2">perlreapi
named_buff_iter</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreapi-named_005fbuff"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-named_005fbuff_005fiter" accesskey="n"
rel="next">perlreapi named_buff_iter</a>, Up: <a
href="#perlreapi-Named-capture-callbacks" accesskey="u" rel="up">perlreapi
Named capture callbacks</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="named_005fbuff"></a>
-<h4 class="subsubsection">59.3.7.1 named_buff</h4>
-
-<pre class="verbatim"> SV* (*named_buff) (pTHX_ REGEXP * const rx, SV *
const key,
- SV * const value, U32 flags);
-</pre>
-<hr>
-<a name="perlreapi-named_005fbuff_005fiter"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreapi-named_005fbuff" accesskey="p"
rel="prev">perlreapi named_buff</a>, Up: <a
href="#perlreapi-Named-capture-callbacks" accesskey="u" rel="up">perlreapi
Named capture callbacks</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="named_005fbuff_005fiter"></a>
-<h4 class="subsubsection">59.3.7.2 named_buff_iter</h4>
-
-<pre class="verbatim"> SV* (*named_buff_iter) (pTHX_
- REGEXP * const rx,
- const SV * const lastkey,
- const U32 flags);
-</pre>
-<hr>
-<a name="perlreapi-qr_005fpackage"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-dupe" accesskey="n" rel="next">perlreapi dupe</a>,
Previous: <a href="#perlreapi-Named-capture-callbacks" accesskey="p"
rel="prev">perlreapi Named capture callbacks</a>, Up: <a
href="#perlreapi-Callbacks" accesskey="u" rel="up">perlreapi Callbacks</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="qr_005fpackage"></a>
-<h4 class="subsection">59.3.8 qr_package</h4>
-
-<pre class="verbatim"> SV* qr_package(pTHX_ REGEXP * const rx);
-</pre>
-<p>The package the qr// magic object is blessed into (as seen by <code>ref
-qr//</code>). It is recommended that engines change this to their package
-name for identification regardless of if they implement methods
-on the object.
-</p>
-<p>The package this method returns should also have the internal
-<code>Regexp</code> package in its <code>@ISA</code>.
<code>qr//->isa("Regexp")</code> should always
-be true regardless of what engine is being used.
-</p>
-<p>Example implementation might be:
-</p>
-<pre class="verbatim"> SV*
- Example_qr_package(pTHX_ REGEXP * const rx)
- {
- PERL_UNUSED_ARG(rx);
- return newSVpvs("re::engine::Example");
- }
-</pre>
-<p>Any method calls on an object created with <code>qr//</code> will be
dispatched to the
-package as a normal object.
-</p>
-<pre class="verbatim"> use re::engine::Example;
- my $re = qr//;
- $re->meth; # dispatched to re::engine::Example::meth()
-</pre>
-<p>To retrieve the <code>REGEXP</code> object from the scalar in an XS
function use
-the <code>SvRX</code> macro, see <a
href="perlapi.html#REGEXP-Functions">(perlapi)"REGEXP Functions" in
perlapi</a>.
-</p>
-<pre class="verbatim"> void meth(SV * rv)
- PPCODE:
- REGEXP * re = SvRX(sv);
-</pre>
-<hr>
-<a name="perlreapi-dupe"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-op_005fcomp" accesskey="n" rel="next">perlreapi
op_comp</a>, Previous: <a href="#perlreapi-qr_005fpackage" accesskey="p"
rel="prev">perlreapi qr_package</a>, Up: <a href="#perlreapi-Callbacks"
accesskey="u" rel="up">perlreapi Callbacks</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="dupe"></a>
-<h4 class="subsection">59.3.9 dupe</h4>
-
-<pre class="verbatim"> void* dupe(pTHX_ REGEXP * const rx, CLONE_PARAMS
*param);
-</pre>
-<p>On threaded builds a regexp may need to be duplicated so that the pattern
-can be used by multiple threads. This routine is expected to handle the
-duplication of any private data pointed to by the <code>pprivate</code> member
of
-the <code>regexp</code> structure. It will be called with the preconstructed
new
-<code>regexp</code> structure as an argument, the <code>pprivate</code> member
will point at
-the <strong>old</strong> private structure, and it is this routine’s
responsibility to
-construct a copy and return a pointer to it (which Perl will then use to
-overwrite the field as passed to this routine.)
-</p>
-<p>This allows the engine to dupe its private data but also if necessary
-modify the final structure if it really must.
-</p>
-<p>On unthreaded builds this field doesn’t exist.
-</p>
-<hr>
-<a name="perlreapi-op_005fcomp"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreapi-dupe" accesskey="p" rel="prev">perlreapi
dupe</a>, Up: <a href="#perlreapi-Callbacks" accesskey="u" rel="up">perlreapi
Callbacks</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="op_005fcomp"></a>
-<h4 class="subsection">59.3.10 op_comp</h4>
-
-<p>This is private to the Perl core and subject to change. Should be left
-null.
-</p>
-<hr>
-<a name="perlreapi-The-REGEXP-structure"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-HISTORY" accesskey="n" rel="next">perlreapi
HISTORY</a>, Previous: <a href="#perlreapi-Callbacks" accesskey="p"
rel="prev">perlreapi Callbacks</a>, Up: <a href="#perlreapi" accesskey="u"
rel="up">perlreapi</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-REGEXP-structure"></a>
-<h3 class="section">59.4 The REGEXP structure</h3>
-
-<p>The REGEXP struct is defined in <samp>regexp.h</samp>.
-All regex engines must be able to
-correctly build such a structure in their <a href="#perlreapi-comp">comp</a>
routine.
-</p>
-<p>The REGEXP structure contains all the data that Perl needs to be aware of
-to properly work with the regular expression. It includes data about
-optimisations that Perl can use to determine if the regex engine should
-really be used, and various other control info that is needed to properly
-execute patterns in various contexts, such as if the pattern anchored in
-some way, or what flags were used during the compile, or if the
-program contains special constructs that Perl needs to be aware of.
-</p>
-<p>In addition it contains two fields that are intended for the private
-use of the regex engine that compiled the pattern. These are the
-<code>intflags</code> and <code>pprivate</code> members.
<code>pprivate</code> is a void pointer to
-an arbitrary structure, whose use and management is the responsibility
-of the compiling engine. Perl will never modify either of these
-values.
-</p>
-<pre class="verbatim"> typedef struct regexp {
- /* what engine created this regexp? */
- const struct regexp_engine* engine;
-
- /* what re is this a lightweight copy of? */
- struct regexp* mother_re;
-
- /* Information about the match that the Perl core uses to manage
- * things */
- U32 extflags; /* Flags used both externally and internally */
- I32 minlen; /* mininum possible number of chars in */
- string to match */
- I32 minlenret; /* mininum possible number of chars in $& */
- U32 gofs; /* chars left of pos that we search from */
-
- /* substring data about strings that must appear
- in the final match, used for optimisations */
- struct reg_substr_data *substrs;
-
- U32 nparens; /* number of capture groups */
-
- /* private engine specific data */
- U32 intflags; /* Engine Specific Internal flags */
- void *pprivate; /* Data private to the regex engine which
- created this object. */
-
- /* Data about the last/current match. These are modified during
- * matching*/
- U32 lastparen; /* highest close paren matched ($+) */
- U32 lastcloseparen; /* last close paren matched ($^N) */
- regexp_paren_pair *swap; /* Swap copy of *offs */
- regexp_paren_pair *offs; /* Array of offsets for (@-) and
- (@+) */
-
- char *subbeg; /* saved or original string so \digit works
- forever. */
- SV_SAVED_COPY /* If non-NULL, SV which is COW from original */
- I32 sublen; /* Length of string pointed by subbeg */
- I32 suboffset; /* byte offset of subbeg from logical start of
- str */
- I32 subcoffset; /* suboffset equiv, but in chars (for @-/@+) */
-
- /* Information about the match that isn't often used */
- I32 prelen; /* length of precomp */
- const char *precomp; /* pre-compilation regular expression */
-
- char *wrapped; /* wrapped version of the pattern */
- I32 wraplen; /* length of wrapped */
-
- I32 seen_evals; /* number of eval groups in the pattern - for
- security checks */
- HV *paren_names; /* Optional hash of paren names */
-
- /* Refcount of this regexp */
- I32 refcnt; /* Refcount of this regexp */
- } regexp;
-</pre>
-<p>The fields are discussed in more detail below:
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlreapi-engine"
accesskey="1">perlreapi <code>engine</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-mother_005fre"
accesskey="2">perlreapi
<code>mother_re</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-extflags"
accesskey="3">perlreapi <code>extflags</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-minlen-minlenret"
accesskey="4">perlreapi <code>minlen</code>
<code>minlenret</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-gofs"
accesskey="5">perlreapi <code>gofs</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-substrs"
accesskey="6">perlreapi <code>substrs</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-nparens_002c-lastparen_002c-and-lastcloseparen"
accesskey="7">perlreapi <code>nparens</code>, <code>lastparen</code>, and
<code>lastcloseparen</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-intflags"
accesskey="8">perlreapi <code>intflags</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-pprivate"
accesskey="9">perlreapi <code>pprivate</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-swap">perlreapi
<code>swap</code></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-offs">perlreapi
<code>offs</code></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-precomp-prelen">perlreapi <code>precomp</code>
<code>prelen</code></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-paren_005fnames">perlreapi
<code>paren_names</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-substrs-1">perlreapi <code>substrs</code>
1</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-subbeg-sublen-saved_005fcopy-suboffset-subcoffset">perlreapi
<code>subbeg</code> <code>sublen</code> <code>saved_copy</code>
<code>suboffset</code>
<code>subcoffset</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-wrapped-wraplen">perlreapi <code>wrapped</code>
<code>wraplen</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreapi-seen_005fevals">perlreapi
<code>seen_evals</code></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreapi-refcnt">perlreapi
<code>refcnt</code></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreapi-engine"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-mother_005fre" accesskey="n" rel="next">perlreapi
<code>mother_re</code></a>, Up: <a href="#perlreapi-The-REGEXP-structure"
accesskey="u" rel="up">perlreapi The REGEXP structure</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="engine"></a>
-<h4 class="subsection">59.4.1 <code>engine</code></h4>
-
-<p>This field points at a <code>regexp_engine</code> structure which contains
pointers
-to the subroutines that are to be used for performing a match. It
-is the compiling routine’s responsibility to populate this field before
-returning the regexp object.
-</p>
-<p>Internally this is set to <code>NULL</code> unless a custom engine is
specified in
-<code>$^H{regcomp}</code>, Perl’s own set of callbacks can be accessed
in the struct
-pointed to by <code>RE_ENGINE_PTR</code>.
-</p>
-<hr>
-<a name="perlreapi-mother_005fre"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-extflags" accesskey="n" rel="next">perlreapi
<code>extflags</code></a>, Previous: <a href="#perlreapi-engine" accesskey="p"
rel="prev">perlreapi <code>engine</code></a>, Up: <a
href="#perlreapi-The-REGEXP-structure" accesskey="u" rel="up">perlreapi The
REGEXP structure</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="mother_005fre"></a>
-<h4 class="subsection">59.4.2 <code>mother_re</code></h4>
-
-<p>TODO, see <a
href="http://www.mail-archive.com/address@hidden/msg17328.html";>http://www.mail-archive.com/address@hidden/msg17328.html</a>
-</p>
-<hr>
-<a name="perlreapi-extflags"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-minlen-minlenret" accesskey="n" rel="next">perlreapi
<code>minlen</code> <code>minlenret</code></a>, Previous: <a
href="#perlreapi-mother_005fre" accesskey="p" rel="prev">perlreapi
<code>mother_re</code></a>, Up: <a href="#perlreapi-The-REGEXP-structure"
accesskey="u" rel="up">perlreapi The REGEXP structure</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="extflags"></a>
-<h4 class="subsection">59.4.3 <code>extflags</code></h4>
-
-<p>This will be used by Perl to see what flags the regexp was compiled
-with, this will normally be set to the value of the flags parameter by
-the <a href="#perlreapi-comp">comp</a> callback. See the <a
href="#perlreapi-comp">comp</a> documentation for
-valid flags.
-</p>
-<hr>
-<a name="perlreapi-minlen-minlenret"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-gofs" accesskey="n" rel="next">perlreapi
<code>gofs</code></a>, Previous: <a href="#perlreapi-extflags" accesskey="p"
rel="prev">perlreapi <code>extflags</code></a>, Up: <a
href="#perlreapi-The-REGEXP-structure" accesskey="u" rel="up">perlreapi The
REGEXP structure</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="minlen-minlenret"></a>
-<h4 class="subsection">59.4.4 <code>minlen</code> <code>minlenret</code></h4>
-
-<p>The minimum string length (in characters) required for the pattern to match.
-This is used to
-prune the search space by not bothering to match any closer to the end of a
-string than would allow a match. For instance there is no point in even
-starting the regex engine if the minlen is 10 but the string is only 5
-characters long. There is no way that the pattern can match.
-</p>
-<p><code>minlenret</code> is the minimum length (in characters) of the string
that would
-be found in $& after a match.
-</p>
-<p>The difference between <code>minlen</code> and <code>minlenret</code> can
be seen in the
-following pattern:
-</p>
-<pre class="verbatim"> /ns(?=\d)/
-</pre>
-<p>where the <code>minlen</code> would be 3 but <code>minlenret</code> would
only be 2 as the \d is
-required to match but is not actually
-included in the matched content. This
-distinction is particularly important as the substitution logic uses the
-<code>minlenret</code> to tell if it can do in-place substitutions (these can
-result in considerable speed-up).
-</p>
-<hr>
-<a name="perlreapi-gofs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-substrs" accesskey="n" rel="next">perlreapi
<code>substrs</code></a>, Previous: <a href="#perlreapi-minlen-minlenret"
accesskey="p" rel="prev">perlreapi <code>minlen</code>
<code>minlenret</code></a>, Up: <a href="#perlreapi-The-REGEXP-structure"
accesskey="u" rel="up">perlreapi The REGEXP structure</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="gofs"></a>
-<h4 class="subsection">59.4.5 <code>gofs</code></h4>
-
-<p>Left offset from pos() to start match at.
-</p>
-<hr>
-<a name="perlreapi-substrs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-nparens_002c-lastparen_002c-and-lastcloseparen"
accesskey="n" rel="next">perlreapi <code>nparens</code>,
<code>lastparen</code>, and <code>lastcloseparen</code></a>, Previous: <a
href="#perlreapi-gofs" accesskey="p" rel="prev">perlreapi
<code>gofs</code></a>, Up: <a href="#perlreapi-The-REGEXP-structure"
accesskey="u" rel="up">perlreapi The REGEXP structure</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="substrs"></a>
-<h4 class="subsection">59.4.6 <code>substrs</code></h4>
-
-<p>Substring data about strings that must appear in the final match. This
-is currently only used internally by Perl’s engine, but might be
-used in the future for all engines for optimisations.
-</p>
-<hr>
-<a name="perlreapi-nparens_002c-lastparen_002c-and-lastcloseparen"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-intflags" accesskey="n" rel="next">perlreapi
<code>intflags</code></a>, Previous: <a href="#perlreapi-substrs" accesskey="p"
rel="prev">perlreapi <code>substrs</code></a>, Up: <a
href="#perlreapi-The-REGEXP-structure" accesskey="u" rel="up">perlreapi The
REGEXP structure</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="nparens_002c-lastparen_002c-and-lastcloseparen"></a>
-<h4 class="subsection">59.4.7 <code>nparens</code>, <code>lastparen</code>,
and <code>lastcloseparen</code></h4>
-
-<p>These fields are used to keep track of how many paren groups could be
matched
-in the pattern, which was the last open paren to be entered, and which was
-the last close paren to be entered.
-</p>
-<hr>
-<a name="perlreapi-intflags"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-pprivate" accesskey="n" rel="next">perlreapi
<code>pprivate</code></a>, Previous: <a
href="#perlreapi-nparens_002c-lastparen_002c-and-lastcloseparen" accesskey="p"
rel="prev">perlreapi <code>nparens</code>, <code>lastparen</code>, and
<code>lastcloseparen</code></a>, Up: <a href="#perlreapi-The-REGEXP-structure"
accesskey="u" rel="up">perlreapi The REGEXP structure</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="intflags"></a>
-<h4 class="subsection">59.4.8 <code>intflags</code></h4>
-
-<p>The engine’s private copy of the flags the pattern was compiled with.
Usually
-this is the same as <code>extflags</code> unless the engine chose to modify
one of them.
-</p>
-<hr>
-<a name="perlreapi-pprivate"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-swap" accesskey="n" rel="next">perlreapi
<code>swap</code></a>, Previous: <a href="#perlreapi-intflags" accesskey="p"
rel="prev">perlreapi <code>intflags</code></a>, Up: <a
href="#perlreapi-The-REGEXP-structure" accesskey="u" rel="up">perlreapi The
REGEXP structure</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="pprivate"></a>
-<h4 class="subsection">59.4.9 <code>pprivate</code></h4>
-
-<p>A void* pointing to an engine-defined
-data structure. The Perl engine uses the
-<code>regexp_internal</code> structure (see <a
href="#perlreguts-Base-Structures">perlreguts Base Structures</a>) but a custom
-engine should use something else.
-</p>
-<hr>
-<a name="perlreapi-swap"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-offs" accesskey="n" rel="next">perlreapi
<code>offs</code></a>, Previous: <a href="#perlreapi-pprivate" accesskey="p"
rel="prev">perlreapi <code>pprivate</code></a>, Up: <a
href="#perlreapi-The-REGEXP-structure" accesskey="u" rel="up">perlreapi The
REGEXP structure</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="swap"></a>
-<h4 class="subsection">59.4.10 <code>swap</code></h4>
-
-<p>Unused. Left in for compatibility with Perl 5.10.0.
-</p>
-<hr>
-<a name="perlreapi-offs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-precomp-prelen" accesskey="n" rel="next">perlreapi
<code>precomp</code> <code>prelen</code></a>, Previous: <a
href="#perlreapi-swap" accesskey="p" rel="prev">perlreapi
<code>swap</code></a>, Up: <a href="#perlreapi-The-REGEXP-structure"
accesskey="u" rel="up">perlreapi The REGEXP structure</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="offs"></a>
-<h4 class="subsection">59.4.11 <code>offs</code></h4>
-
-<p>A <code>regexp_paren_pair</code> structure which defines offsets into the
string being
-matched which correspond to the <code>$&</code> and <code>$1</code>,
<code>$2</code> etc. captures, the
-<code>regexp_paren_pair</code> struct is defined as follows:
-</p>
-<pre class="verbatim"> typedef struct regexp_paren_pair {
- I32 start;
- I32 end;
- } regexp_paren_pair;
-</pre>
-<p>If <code>->offs[num].start</code> or <code>->offs[num].end</code> is
<code>-1</code> then that
-capture group did not match.
-<code>->offs[0].start/end</code> represents <code>$&</code> (or
-<code>${^MATCH}</code> under <code>//p</code>) and
<code>->offs[paren].end</code> matches <code>$$paren</code> where
-<code>$paren </code>= 1>.
-</p>
-<hr>
-<a name="perlreapi-precomp-prelen"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-paren_005fnames" accesskey="n" rel="next">perlreapi
<code>paren_names</code></a>, Previous: <a href="#perlreapi-offs" accesskey="p"
rel="prev">perlreapi <code>offs</code></a>, Up: <a
href="#perlreapi-The-REGEXP-structure" accesskey="u" rel="up">perlreapi The
REGEXP structure</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="precomp-prelen"></a>
-<h4 class="subsection">59.4.12 <code>precomp</code> <code>prelen</code></h4>
-
-<p>Used for optimisations. <code>precomp</code> holds a copy of the pattern
that
-was compiled and <code>prelen</code> its length. When a new pattern is to be
-compiled (such as inside a loop) the internal <code>regcomp</code> operator
-checks if the last compiled <code>REGEXP</code>’s <code>precomp</code>
and <code>prelen</code>
-are equivalent to the new one, and if so uses the old pattern instead
-of compiling a new one.
-</p>
-<p>The relevant snippet from <code>Perl_pp_regcomp</code>:
-</p>
-<pre class="verbatim"> if (!re || !re->precomp || re->prelen !=
(I32)len ||
- memNE(re->precomp, t, len))
- /* Compile a new pattern */
-</pre>
-<hr>
-<a name="perlreapi-paren_005fnames"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-substrs-1" accesskey="n" rel="next">perlreapi
<code>substrs</code> 1</a>, Previous: <a href="#perlreapi-precomp-prelen"
accesskey="p" rel="prev">perlreapi <code>precomp</code>
<code>prelen</code></a>, Up: <a href="#perlreapi-The-REGEXP-structure"
accesskey="u" rel="up">perlreapi The REGEXP structure</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="paren_005fnames"></a>
-<h4 class="subsection">59.4.13 <code>paren_names</code></h4>
-
-<p>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
-independently in the data array in cases where named backreferences are
-used.
-</p>
-<hr>
-<a name="perlreapi-substrs-1"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-subbeg-sublen-saved_005fcopy-suboffset-subcoffset"
accesskey="n" rel="next">perlreapi <code>subbeg</code> <code>sublen</code>
<code>saved_copy</code> <code>suboffset</code> <code>subcoffset</code></a>,
Previous: <a href="#perlreapi-paren_005fnames" accesskey="p"
rel="prev">perlreapi <code>paren_names</code></a>, Up: <a
href="#perlreapi-The-REGEXP-structure" accesskey="u" rel="up">perlreapi The
REGEXP structure</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="substrs-1"></a>
-<h4 class="subsection">59.4.14 <code>substrs</code></h4>
-
-<p>Holds information on the longest string that must occur at a fixed
-offset from the start of the pattern, and the longest string that must
-occur at a floating offset from the start of the pattern. Used to do
-Fast-Boyer-Moore searches on the string to find out if its worth using
-the regex engine at all, and if so where in the string to search.
-</p>
-<hr>
-<a name="perlreapi-subbeg-sublen-saved_005fcopy-suboffset-subcoffset"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-wrapped-wraplen" accesskey="n" rel="next">perlreapi
<code>wrapped</code> <code>wraplen</code></a>, Previous: <a
href="#perlreapi-substrs-1" accesskey="p" rel="prev">perlreapi
<code>substrs</code> 1</a>, Up: <a href="#perlreapi-The-REGEXP-structure"
accesskey="u" rel="up">perlreapi The REGEXP structure</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="subbeg-sublen-saved_005fcopy-suboffset-subcoffset"></a>
-<h4 class="subsection">59.4.15 <code>subbeg</code> <code>sublen</code>
<code>saved_copy</code> <code>suboffset</code> <code>subcoffset</code></h4>
-
-<p>Used during the execution phase for managing search and replace patterns,
-and for providing the text for <code>$&</code>, <code>$1</code> etc.
<code>subbeg</code> points to a
-buffer (either the original string, or a copy in the case of
-<code>RX_MATCH_COPIED(rx)</code>), and <code>sublen</code> is the length of
the buffer. The
-<code>RX_OFFS</code> start and end indices index into this buffer.
-</p>
-<p>In the presence of the <code>REXEC_COPY_STR</code> flag, but with the
addition of
-the <code>REXEC_COPY_SKIP_PRE</code> or <code>REXEC_COPY_SKIP_POST</code>
flags, an engine
-can choose not to copy the full buffer (although it must still do so in
-the presence of <code>RXf_PMf_KEEPCOPY</code> or the relevant bits being set in
-<code>PL_sawampersand</code>). In this case, it may set
<code>suboffset</code> to indicate the
-number of bytes from the logical start of the buffer to the physical start
-(i.e. <code>subbeg</code>). It should also set <code>subcoffset</code>, the
number of
-characters in the offset. The latter is needed to support <code>@-</code> and
<code>@+</code>
-which work in characters, not bytes.
-</p>
-<hr>
-<a name="perlreapi-wrapped-wraplen"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-seen_005fevals" accesskey="n" rel="next">perlreapi
<code>seen_evals</code></a>, Previous: <a
href="#perlreapi-subbeg-sublen-saved_005fcopy-suboffset-subcoffset"
accesskey="p" rel="prev">perlreapi <code>subbeg</code> <code>sublen</code>
<code>saved_copy</code> <code>suboffset</code> <code>subcoffset</code></a>, Up:
<a href="#perlreapi-The-REGEXP-structure" accesskey="u" rel="up">perlreapi The
REGEXP structure</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="wrapped-wraplen"></a>
-<h4 class="subsection">59.4.16 <code>wrapped</code> <code>wraplen</code></h4>
-
-<p>Stores the string <code>qr//</code> stringifies to. The Perl engine for
example
-stores <code>(?^:eek)</code> in the case of <code>qr/eek/</code>.
-</p>
-<p>When using a custom engine that doesn’t support the <code>(?:)</code>
construct
-for inline modifiers, it’s probably best to have <code>qr//</code>
stringify to
-the supplied pattern, note that this will create undesired patterns in
-cases such as:
-</p>
-<pre class="verbatim"> my $x = qr/a|b/; # "a|b"
- my $y = qr/c/i; # "c"
- my $z = qr/$x$y/; # "a|bc"
-</pre>
-<p>There’s no solution for this problem other than making the custom
-engine understand a construct like <code>(?:)</code>.
-</p>
-<hr>
-<a name="perlreapi-seen_005fevals"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-refcnt" accesskey="n" rel="next">perlreapi
<code>refcnt</code></a>, Previous: <a href="#perlreapi-wrapped-wraplen"
accesskey="p" rel="prev">perlreapi <code>wrapped</code>
<code>wraplen</code></a>, Up: <a href="#perlreapi-The-REGEXP-structure"
accesskey="u" rel="up">perlreapi The REGEXP structure</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="seen_005fevals"></a>
-<h4 class="subsection">59.4.17 <code>seen_evals</code></h4>
-
-<p>This stores the number of eval groups in
-the pattern. This is used for security
-purposes when embedding compiled regexes into larger patterns with
<code>qr//</code>.
-</p>
-<hr>
-<a name="perlreapi-refcnt"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreapi-seen_005fevals" accesskey="p"
rel="prev">perlreapi <code>seen_evals</code></a>, Up: <a
href="#perlreapi-The-REGEXP-structure" accesskey="u" rel="up">perlreapi The
REGEXP structure</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="refcnt"></a>
-<h4 class="subsection">59.4.18 <code>refcnt</code></h4>
-
-<p>The number of times the structure is referenced. When
-this falls to 0, the regexp is automatically freed
-by a call to pregfree. This should be set to 1 in
-each engine’s <a href="#perlreapi-comp">comp</a> routine.
-</p>
-<hr>
-<a name="perlreapi-HISTORY"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-AUTHORS" accesskey="n" rel="next">perlreapi
AUTHORS</a>, Previous: <a href="#perlreapi-The-REGEXP-structure" accesskey="p"
rel="prev">perlreapi The REGEXP structure</a>, Up: <a href="#perlreapi"
accesskey="u" rel="up">perlreapi</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="HISTORY-3"></a>
-<h3 class="section">59.5 HISTORY</h3>
-
-<p>Originally part of <a href="#perlreguts-NAME">perlreguts NAME</a>.
-</p>
-<hr>
-<a name="perlreapi-AUTHORS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreapi-LICENSE" accesskey="n" rel="next">perlreapi
LICENSE</a>, Previous: <a href="#perlreapi-HISTORY" accesskey="p"
rel="prev">perlreapi HISTORY</a>, Up: <a href="#perlreapi" accesskey="u"
rel="up">perlreapi</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHORS-4"></a>
-<h3 class="section">59.6 AUTHORS</h3>
-
-<p>Originally written by Yves Orton, expanded by ÃÂvar Arnfjörð
-Bjarmason.
-</p>
-<hr>
-<a name="perlreapi-LICENSE"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreapi-AUTHORS" accesskey="p" rel="prev">perlreapi
AUTHORS</a>, Up: <a href="#perlreapi" accesskey="u" rel="up">perlreapi</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="LICENSE-1"></a>
-<h3 class="section">59.7 LICENSE</h3>
-
-<p>Copyright 2006 Yves Orton and 2007 ÃÂvar Arnfjörð Bjarmason.
-</p>
-<p>This program is free software; you can redistribute it and/or modify it
under
-the same terms as Perl itself.
-</p>
-<hr>
-<a name="perlrebackslash"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass" accesskey="n" rel="next">perlrecharclass</a>,
Previous: <a href="#perlreapi" accesskey="p" rel="prev">perlreapi</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlrebackslash-1"></a>
-<h2 class="chapter">60 perlrebackslash</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlrebackslash-NAME"
accesskey="1">perlrebackslash NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-DESCRIPTION" accesskey="2">perlrebackslash
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrebackslash-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-DESCRIPTION" accesskey="n"
rel="next">perlrebackslash DESCRIPTION</a>, Up: <a href="#perlrebackslash"
accesskey="u" rel="up">perlrebackslash</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-59"></a>
-<h3 class="section">60.1 NAME</h3>
-
-<p>perlrebackslash - Perl Regular Expression Backslash Sequences and Escapes
-</p>
-<hr>
-<a name="perlrebackslash-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlrebackslash-NAME" accesskey="p"
rel="prev">perlrebackslash NAME</a>, Up: <a href="#perlrebackslash"
accesskey="u" rel="up">perlrebackslash</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-58"></a>
-<h3 class="section">60.2 DESCRIPTION</h3>
-
-<p>The top level documentation about Perl regular expressions
-is found in <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-<p>This document describes all backslash and escape sequences. After
-explaining the role of the backslash, it lists all the sequences that have
-a special meaning in Perl regular expressions (in alphabetical order),
-then describes each of them.
-</p>
-<p>Most sequences are described in detail in different documents; the primary
-purpose of this document is to have a quick reference guide describing all
-backslash and escape sequences.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-The-backslash" accesskey="1">perlrebackslash The
backslash</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-All-the-sequences-and-escapes"
accesskey="2">perlrebackslash All the sequences and
escapes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Character-Escapes" accesskey="3">perlrebackslash
Character Escapes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrebackslash-Modifiers"
accesskey="4">perlrebackslash Modifiers</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Character-classes" accesskey="5">perlrebackslash
Character classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Referencing" accesskey="6">perlrebackslash
Referencing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrebackslash-Assertions"
accesskey="7">perlrebackslash Assertions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrebackslash-Misc"
accesskey="8">perlrebackslash Misc</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrebackslash-The-backslash"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-All-the-sequences-and-escapes" accesskey="n"
rel="next">perlrebackslash All the sequences and escapes</a>, Up: <a
href="#perlrebackslash-DESCRIPTION" accesskey="u" rel="up">perlrebackslash
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-backslash"></a>
-<h4 class="subsection">60.2.1 The backslash</h4>
-
-<p>In a regular expression, the backslash can perform one of two tasks:
-it either takes away the special meaning of the character following it
-(for instance, <code>\|</code> matches a vertical bar, it’s not an
alternation),
-or it is the start of a backslash or escape sequence.
-</p>
-<p>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 any special meaning of the character following it.
-</p>
-<p>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 issues a warning if you use such a
-sequence. [1].
-</p>
-<p>It is however guaranteed that backslash or escape sequences never have a
-punctuation character following the backslash, not now, and not in a future
-version of Perl 5. So it is safe to put a backslash in front of a non-word
-character.
-</p>
-<p>Note that the backslash itself is special; if you want to match a backslash,
-you have to escape the backslash with a backslash: <code>/\\/</code> matches a
single
-backslash.
-</p>
-<dl compact="compact">
-<dt>[1]</dt>
-<dd><a name="perlrebackslash-_005b1_005d"></a>
-<p>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 have to escape the delimiter if you want to match
-it. Perl won’t warn then. See also <a
href="#perlop-Gory-details-of-parsing-quoted-constructs">perlop Gory details of
parsing quoted constructs</a>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlrebackslash-All-the-sequences-and-escapes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Character-Escapes" accesskey="n"
rel="next">perlrebackslash Character Escapes</a>, Previous: <a
href="#perlrebackslash-The-backslash" accesskey="p" rel="prev">perlrebackslash
The backslash</a>, Up: <a href="#perlrebackslash-DESCRIPTION" accesskey="u"
rel="up">perlrebackslash DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="All-the-sequences-and-escapes"></a>
-<h4 class="subsection">60.2.2 All the sequences and escapes</h4>
-
-<p>Those not usable within a bracketed character class (like
<code>[\da-z]</code>) are marked
-as <code>Not in [].</code>
-</p>
-<pre class="verbatim"> \000 Octal escape sequence. See also \o{}.
- \1 Absolute backreference. Not in [].
- \a Alarm or bell.
- \A Beginning of string. Not in [].
- \b{}, \b Boundary. (\b is a backspace in []).
- \B{}, \B Not a boundary. Not in [].
- \cX Control-X.
- \C Single octet, even under UTF-8. Not in [].
- (Deprecated)
- \d Character class for digits.
- \D Character class for non-digits.
- \e Escape character.
- \E Turn off \Q, \L and \U processing. Not in [].
- \f Form feed.
- \F Foldcase till \E. Not in [].
- \g{}, \g1 Named, absolute or relative backreference.
- Not in [].
- \G Pos assertion. Not in [].
- \h Character class for horizontal whitespace.
- \H Character class for non horizontal whitespace.
- \k{}, \k<>, \k'' Named backreference. Not in [].
- \K Keep the stuff left of \K. Not in [].
- \l Lowercase next character. Not in [].
- \L Lowercase till \E. Not in [].
- \n (Logical) newline character.
- \N Any character but newline. Not in [].
- \N{} Named or numbered (Unicode) character or sequence.
- \o{} Octal escape sequence.
- \p{}, \pP Character with the given Unicode property.
- \P{}, \PP Character without the given Unicode property.
- \Q Quote (disable) pattern metacharacters till \E. Not
- in [].
- \r Return character.
- \R Generic new line. Not in [].
- \s Character class for whitespace.
- \S Character class for non whitespace.
- \t Tab character.
- \u Titlecase next character. Not in [].
- \U Uppercase till \E. Not in [].
- \v Character class for vertical whitespace.
- \V Character class for non vertical whitespace.
- \w Character class for word characters.
- \W Character class for non-word characters.
- \x{}, \x00 Hexadecimal escape sequence.
- \X Unicode "extended grapheme cluster". Not in [].
- \z End of string. Not in [].
- \Z End of string. Not in [].
-</pre>
-<hr>
-<a name="perlrebackslash-Character-Escapes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Modifiers" accesskey="n"
rel="next">perlrebackslash Modifiers</a>, Previous: <a
href="#perlrebackslash-All-the-sequences-and-escapes" accesskey="p"
rel="prev">perlrebackslash All the sequences and escapes</a>, Up: <a
href="#perlrebackslash-DESCRIPTION" accesskey="u" rel="up">perlrebackslash
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Character-Escapes"></a>
-<h4 class="subsection">60.2.3 Character Escapes</h4>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Fixed-characters" accesskey="1">perlrebackslash Fixed
characters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrebackslash-Example"
accesskey="2">perlrebackslash Example</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Control-characters" accesskey="3">perlrebackslash
Control characters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrebackslash-Example-1"
accesskey="4">perlrebackslash Example 1</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Named-or-numbered-characters-and-character-sequences"
accesskey="5">perlrebackslash Named or numbered characters and character
sequences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrebackslash-Example-2"
accesskey="6">perlrebackslash Example 2</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Octal-escapes" accesskey="7">perlrebackslash Octal
escapes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Examples-_0028assuming-an-ASCII-platform_0029"
accesskey="8">perlrebackslash Examples (assuming an ASCII
platform)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Disambiguation-rules-between-old_002dstyle-octal-escapes-and-backreferences"
accesskey="9">perlrebackslash Disambiguation rules between old-style octal
escapes and backreferences</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Hexadecimal-escapes">perlrebackslash Hexadecimal
escapes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Examples-_0028assuming-an-ASCII-platform_0029-1">perlrebackslash
Examples (assuming an ASCII platform) 1</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrebackslash-Fixed-characters"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Example" accesskey="n"
rel="next">perlrebackslash Example</a>, Up: <a
href="#perlrebackslash-Character-Escapes" accesskey="u"
rel="up">perlrebackslash Character Escapes</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Fixed-characters"></a>
-<h4 class="subsubsection">60.2.3.1 Fixed characters</h4>
-
-<p>A handful of characters have a dedicated <em>character escape</em>. The
following
-table shows them, along with their ASCII code points (in decimal and hex),
-their ASCII name, the control escape on ASCII platforms and a short
-description. (For EBCDIC platforms, see <a
href="#perlebcdic-OPERATOR-DIFFERENCES">perlebcdic OPERATOR DIFFERENCES</a>.)
-</p>
-<pre class="verbatim"> Seq. Code Point ASCII Cntrl Description.
- Dec Hex
- \a 7 07 BEL \cG alarm or bell
- \b 8 08 BS \cH backspace [1]
- \e 27 1B ESC \c[ escape character
- \f 12 0C FF \cL form feed
- \n 10 0A LF \cJ line feed [2]
- \r 13 0D CR \cM carriage return
- \t 9 09 TAB \cI tab
-</pre>
-<dl compact="compact">
-<dt>[1]</dt>
-<dd><a name="perlrebackslash-_005b1_005d-1"></a>
-<p><code>\b</code> is the backspace character only inside a character class.
Outside a
-character class, <code>\b</code> alone is a word-character/non-word-character
-boundary, and <code>\b{}</code> is some other type of boundary.
-</p>
-</dd>
-<dt>[2]</dt>
-<dd><a name="perlrebackslash-_005b2_005d"></a>
-<p><code>\n</code> matches a logical newline. Perl converts between
<code>\n</code> and your
-OS’s native newline character when reading from or writing to text files.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlrebackslash-Example"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Control-characters" accesskey="n"
rel="next">perlrebackslash Control characters</a>, Previous: <a
href="#perlrebackslash-Fixed-characters" accesskey="p"
rel="prev">perlrebackslash Fixed characters</a>, Up: <a
href="#perlrebackslash-Character-Escapes" accesskey="u"
rel="up">perlrebackslash Character Escapes</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Example"></a>
-<h4 class="subsubsection">60.2.3.2 Example</h4>
-
-<pre class="verbatim"> $str =~ /\t/; # Matches if $str contains a
(horizontal) tab.
-</pre>
-<hr>
-<a name="perlrebackslash-Control-characters"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Example-1" accesskey="n"
rel="next">perlrebackslash Example 1</a>, Previous: <a
href="#perlrebackslash-Example" accesskey="p" rel="prev">perlrebackslash
Example</a>, Up: <a href="#perlrebackslash-Character-Escapes" accesskey="u"
rel="up">perlrebackslash Character Escapes</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Control-characters"></a>
-<h4 class="subsubsection">60.2.3.3 Control characters</h4>
-
-<p><code>\c</code> is used to denote a control character; the character
following <code>\c</code>
-determines the value of the construct. For example the value of
<code>\cA</code> is
-<code>chr(1)</code>, and the value of <code>\cb</code> is <code>chr(2)</code>,
etc.
-The gory details are in <a
href="#perlop-Regexp-Quote_002dLike-Operators">perlop Regexp Quote-Like
Operators</a>. A complete
-list of what <code>chr(1)</code>, etc. means for ASCII and EBCDIC platforms is
in
-<a href="#perlebcdic-OPERATOR-DIFFERENCES">perlebcdic OPERATOR DIFFERENCES</a>.
-</p>
-<p>Note that <code>\c\</code> alone at the end of a regular expression (or
doubled-quoted
-string) is not valid. The backslash must be followed by another character.
-That is, <code>\c\<em>X</em></code> means <code>chr(28) . '<em>X</em>'</code>
for all characters <em>X</em>.
-</p>
-<p>To write platform-independent code, you must use
<code>\N{<em>NAME</em>}</code> instead, like
-<code>\N{ESCAPE}</code> or <code>\N{U+001B}</code>, see <a
href="charnames.html#Top">(charnames)</a>.
-</p>
-<p>Mnemonic: <em>c</em>ontrol character.
-</p>
-<hr>
-<a name="perlrebackslash-Example-1"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlrebackslash-Named-or-numbered-characters-and-character-sequences"
accesskey="n" rel="next">perlrebackslash Named or numbered characters and
character sequences</a>, Previous: <a
href="#perlrebackslash-Control-characters" accesskey="p"
rel="prev">perlrebackslash Control characters</a>, Up: <a
href="#perlrebackslash-Character-Escapes" accesskey="u"
rel="up">perlrebackslash Character Escapes</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Example-1"></a>
-<h4 class="subsubsection">60.2.3.4 Example</h4>
-
-<pre class="verbatim"> $str =~ /\cK/; # Matches if $str contains a vertical
tab (control-K).
-</pre>
-<hr>
-<a
name="perlrebackslash-Named-or-numbered-characters-and-character-sequences"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Example-2" accesskey="n"
rel="next">perlrebackslash Example 2</a>, Previous: <a
href="#perlrebackslash-Example-1" accesskey="p" rel="prev">perlrebackslash
Example 1</a>, Up: <a href="#perlrebackslash-Character-Escapes" accesskey="u"
rel="up">perlrebackslash Character Escapes</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Named-or-numbered-characters-and-character-sequences"></a>
-<h4 class="subsubsection">60.2.3.5 Named or numbered characters and character
sequences</h4>
-
-<p>Unicode characters have a Unicode name and numeric code point (ordinal)
-value. Use the
-<code>\N{}</code> construct to specify a character by either of these values.
-Certain sequences of characters also have names.
-</p>
-<p>To specify by name, the name of the character or character sequence goes
-between the curly braces.
-</p>
-<p>To specify a character by Unicode code point, use the form
<code>\N{U+<em>code
-point</em>}</code>, where <em>code point</em> 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 <code>\N{U+0041}</code> means <code>LATIN CAPITAL LETTER
A</code>, and you will
-rarely see it written without the two leading zeros. <code>\N{U+0041}</code>
means
-"A" even on EBCDIC machines (where the ordinal value of
"A" is not 0x41).
-</p>
-<p>It is even possible to give your own names to characters and character
-sequences. For details, see <a href="charnames.html#Top">(charnames)</a>.
-</p>
-<p>(There is an expanded internal form that you may see in debug output:
-<code>\N{U+<em>code point</em>.<em>code point</em>...}</code>.
-The <code>...</code> means any number of these <em>code point</em>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.)
-</p>
-<p>Mnemonic: <em>N</em>amed character.
-</p>
-<p>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".
-</p>
-<hr>
-<a name="perlrebackslash-Example-2"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Octal-escapes" accesskey="n"
rel="next">perlrebackslash Octal escapes</a>, Previous: <a
href="#perlrebackslash-Named-or-numbered-characters-and-character-sequences"
accesskey="p" rel="prev">perlrebackslash Named or numbered characters and
character sequences</a>, Up: <a href="#perlrebackslash-Character-Escapes"
accesskey="u" rel="up">perlrebackslash Character Escapes</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Example-2"></a>
-<h4 class="subsubsection">60.2.3.6 Example</h4>
-
-<pre class="verbatim"> $str =~ /\N{THAI CHARACTER SO SO}/; # Matches the Thai
SO SO character
-
- use charnames 'Cyrillic'; # Loads Cyrillic names.
- $str =~ /\N{ZHE}\N{KA}/; # Match "ZHE" followed by
"KA".
-</pre>
-<hr>
-<a name="perlrebackslash-Octal-escapes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Examples-_0028assuming-an-ASCII-platform_0029"
accesskey="n" rel="next">perlrebackslash Examples (assuming an ASCII
platform)</a>, Previous: <a href="#perlrebackslash-Example-2" accesskey="p"
rel="prev">perlrebackslash Example 2</a>, Up: <a
href="#perlrebackslash-Character-Escapes" accesskey="u"
rel="up">perlrebackslash Character Escapes</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Octal-escapes"></a>
-<h4 class="subsubsection">60.2.3.7 Octal escapes</h4>
-
-<p>There are two forms of octal escapes. Each is used to specify a character
by
-its code point specified in octal notation.
-</p>
-<p>One form, available starting in Perl 5.14 looks like <code>\o{...}</code>,
where the dots
-represent one or more octal digits. It can be used for any Unicode character.
-</p>
-<p>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
-<a
href="#perlrebackslash-Disambiguation-rules-between-old_002dstyle-octal-escapes-and-backreferences">Disambiguation
rules between old-style octal escapes and backreferences</a>
-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.
-</p>
-<p>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 <a
href="#perlrebackslash-Absolute-referencing">Absolute referencing</a> for more
-discussion and examples of the snippet problem.
-</p>
-<p>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".
-</p>
-<p>To summarize, the <code>\o{}</code> 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.
-</p>
-<p>Mnemonic: <em>0</em>ctal or <em>o</em>ctal.
-</p>
-<hr>
-<a name="perlrebackslash-Examples-_0028assuming-an-ASCII-platform_0029"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlrebackslash-Disambiguation-rules-between-old_002dstyle-octal-escapes-and-backreferences"
accesskey="n" rel="next">perlrebackslash Disambiguation rules between
old-style octal escapes and backreferences</a>, Previous: <a
href="#perlrebackslash-Octal-escapes" accesskey="p" rel="prev">perlrebackslash
Octal escapes</a>, Up: <a href="#perlrebackslash-Character-Escapes"
accesskey="u" rel="up">perlrebackslash Character Escapes</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Examples-_0028assuming-an-ASCII-platform_0029"></a>
-<h4 class="subsubsection">60.2.3.8 Examples (assuming an ASCII platform)</h4>
-
-<pre class="verbatim"> $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).
-</pre>
-<hr>
-<a
name="perlrebackslash-Disambiguation-rules-between-old_002dstyle-octal-escapes-and-backreferences"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Hexadecimal-escapes" accesskey="n"
rel="next">perlrebackslash Hexadecimal escapes</a>, Previous: <a
href="#perlrebackslash-Examples-_0028assuming-an-ASCII-platform_0029"
accesskey="p" rel="prev">perlrebackslash Examples (assuming an ASCII
platform)</a>, Up: <a href="#perlrebackslash-Character-Escapes" accesskey="u"
rel="up">perlrebackslash Character Escapes</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a
name="Disambiguation-rules-between-old_002dstyle-octal-escapes-and-backreferences"></a>
-<h4 class="subsubsection">60.2.3.9 Disambiguation rules between old-style
octal escapes and backreferences</h4>
-
-<p>Octal escapes of the <code>\000</code> form outside of bracketed character
classes
-potentially clash with old-style backreferences (see <a
href="#perlrebackslash-Absolute-referencing">Absolute referencing</a>
-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:
-</p>
-<ol>
-<li> If the backslash is followed by a single digit, it’s a
backreference.
-
-</li><li> If the first digit following the backslash is a 0, it’s an
octal escape.
-
-</li><li> 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.
-
-<pre class="verbatim"> my $pat = "(" x 999;
- $pat .= "a";
- $pat .= ")" x 999;
- /^($pat)\1000$/; # Matches 'aa'; there are 1000 capture groups.
- /^$pat\1000$/; # Matches 'address@hidden'; there are 999 capture groups
- # and \1000 is seen as \100 (a '@') and a '0'.
-</pre>
-</li></ol>
-
-<p>You can force a backreference interpretation always by using the
<code>\g{...}</code>
-form. You can the force an octal interpretation always by using the
<code>\o{...}</code>
-form, or for numbers up through \077 (= 63 decimal), by using three digits,
-beginning with a "0".
-</p>
-<hr>
-<a name="perlrebackslash-Hexadecimal-escapes"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlrebackslash-Examples-_0028assuming-an-ASCII-platform_0029-1"
accesskey="n" rel="next">perlrebackslash Examples (assuming an ASCII platform)
1</a>, Previous: <a
href="#perlrebackslash-Disambiguation-rules-between-old_002dstyle-octal-escapes-and-backreferences"
accesskey="p" rel="prev">perlrebackslash Disambiguation rules between
old-style octal escapes and backreferences</a>, Up: <a
href="#perlrebackslash-Character-Escapes" accesskey="u"
rel="up">perlrebackslash Character Escapes</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Hexadecimal-escapes"></a>
-<h4 class="subsubsection">60.2.3.10 Hexadecimal escapes</h4>
-
-<p>Like octal escapes, there are two forms of hexadecimal escapes, but both
start
-with the sequence <code>\x</code>. 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.
-</p>
-<p>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".
-</p>
-<p>Mnemonic: he<em>x</em>adecimal.
-</p>
-<hr>
-<a name="perlrebackslash-Examples-_0028assuming-an-ASCII-platform_0029-1"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlrebackslash-Hexadecimal-escapes" accesskey="p"
rel="prev">perlrebackslash Hexadecimal escapes</a>, Up: <a
href="#perlrebackslash-Character-Escapes" accesskey="u"
rel="up">perlrebackslash Character Escapes</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Examples-_0028assuming-an-ASCII-platform_0029-1"></a>
-<h4 class="subsubsection">60.2.3.11 Examples (assuming an ASCII platform)</h4>
-
-<pre class="verbatim"> $str = "Perl";
- $str =~ /\x50/; # Match, "\x50" is "P".
- $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.
- # The Unicode character 2603 is a snowman,
- # the Unicode character 2602 is an umbrella.
- /\x{263B}/ # Black smiling face.
- /\x{263b}/ # Same, the hex digits A - F are case insensitive.
-</pre>
-<hr>
-<a name="perlrebackslash-Modifiers"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Character-classes" accesskey="n"
rel="next">perlrebackslash Character classes</a>, Previous: <a
href="#perlrebackslash-Character-Escapes" accesskey="p"
rel="prev">perlrebackslash Character Escapes</a>, Up: <a
href="#perlrebackslash-DESCRIPTION" accesskey="u" rel="up">perlrebackslash
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Modifiers-1"></a>
-<h4 class="subsection">60.2.4 Modifiers</h4>
-
-<p>A number of backslash sequences have to do with changing the character,
-or characters following them. <code>\l</code> will lowercase the character
following
-it, while <code>\u</code> will uppercase (or, more accurately, titlecase) the
-character following it. They provide functionality similar to the
-functions <code>lcfirst</code> and <code>ucfirst</code>.
-</p>
-<p>To uppercase or lowercase several characters, one might want to use
-<code>\L</code> or <code>\U</code>, which will lowercase/uppercase all
characters following
-them, until either the end of the pattern or the next occurrence of
-<code>\E</code>, whichever comes first. They provide functionality similar to
what
-the functions <code>lc</code> and <code>uc</code> provide.
-</p>
-<p><code>\Q</code> is used to quote (disable) pattern metacharacters, up to
the next
-<code>\E</code> or the end of the pattern. <code>\Q</code> adds a backslash to
any character
-that could have special meaning to Perl. In the ASCII range, it quotes
-every character that isn’t a letter, digit, or underscore. See
-<a href="#perlfunc-quotemeta">perlfunc quotemeta</a> for details on what gets
quoted for non-ASCII
-code points. Using this ensures that any character between <code>\Q</code> and
-<code>\E</code> will be matched literally, not interpreted as a metacharacter
by
-the regex engine.
-</p>
-<p><code>\F</code> can be used to casefold all characters following, up to the
next <code>\E</code>
-or the end of the pattern. It provides the functionality similar to
-the <code>fc</code> function.
-</p>
-<p>Mnemonic: <em>L</em>owercase, <em>U</em>ppercase, <em>F</em>old-case,
<em>Q</em>uotemeta, <em>E</em>nd.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlrebackslash-Examples"
accesskey="1">perlrebackslash Examples</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrebackslash-Examples"></a>
-<div class="header">
-<p>
-Up: <a href="#perlrebackslash-Modifiers" accesskey="u"
rel="up">perlrebackslash Modifiers</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Examples-2"></a>
-<h4 class="subsubsection">60.2.4.1 Examples</h4>
-
-<pre class="verbatim"> $sid = "sid";
- $greg = "GrEg";
- $miranda = "(Miranda)";
- $str =~ /\u$sid/; # Matches 'Sid'
- $str =~ /\L$greg/; # Matches 'greg'
- $str =~ /\Q$miranda\E/; # Matches '(Miranda)', as if the pattern
- # had been written as /\(Miranda\)/
-</pre>
-<hr>
-<a name="perlrebackslash-Character-classes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Referencing" accesskey="n"
rel="next">perlrebackslash Referencing</a>, Previous: <a
href="#perlrebackslash-Modifiers" accesskey="p" rel="prev">perlrebackslash
Modifiers</a>, Up: <a href="#perlrebackslash-DESCRIPTION" accesskey="u"
rel="up">perlrebackslash DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Character-classes"></a>
-<h4 class="subsection">60.2.5 Character classes</h4>
-
-<p>Perl regular expressions have a large range of character classes. Some of
-the character classes are written as a backslash sequence. We will briefly
-discuss those here; full details of character classes can be found in
-<a href="#perlrecharclass-NAME">perlrecharclass NAME</a>.
-</p>
-<p><code>\w</code> is a character class that matches any single <em>word</em>
character
-(letters, digits, Unicode marks, and connector punctuation (like the
-underscore)). <code>\d</code> is a character class that matches any decimal
-digit, while the character class <code>\s</code> matches any whitespace
character.
-New in perl 5.10.0 are the classes <code>\h</code> and <code>\v</code> which
match horizontal
-and vertical whitespace characters.
-</p>
-<p>The exact set of characters matched by <code>\d</code>, <code>\s</code>,
and <code>\w</code> varies
-depending on various pragma and regular expression modifiers. It is
-possible to restrict the match to the ASCII range by using the <code>/a</code>
-regular expression modifier. See <a
href="#perlrecharclass-NAME">perlrecharclass NAME</a>.
-</p>
-<p>The uppercase variants (<code>\W</code>, <code>\D</code>, <code>\S</code>,
<code>\H</code>, and <code>\V</code>) are
-character classes that match, respectively, any character that isn’t a
-word character, digit, whitespace, horizontal whitespace, or vertical
-whitespace.
-</p>
-<p>Mnemonics: <em>w</em>ord, <em>d</em>igit, <em>s</em>pace,
<em>h</em>orizontal, <em>v</em>ertical.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Unicode-classes" accesskey="1">perlrebackslash Unicode
classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrebackslash-Unicode-classes"></a>
-<div class="header">
-<p>
-Up: <a href="#perlrebackslash-Character-classes" accesskey="u"
rel="up">perlrebackslash Character classes</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-classes"></a>
-<h4 class="subsubsection">60.2.5.1 Unicode classes</h4>
-
-<p><code>\pP</code> (where <code>P</code> is a single letter) and
<code>\p{Property}</code> are used to
-match a character that matches the given Unicode property; properties
-include things like "letter", or "thai character".
Capitalizing the
-sequence to <code>\PP</code> and <code>\P{Property}</code> make the sequence
match a character
-that doesn’t match the given Unicode property. For more details, see
-<a href="#perlrecharclass-Backslash-sequences">perlrecharclass Backslash
sequences</a> and
-<a href="#perlunicode-Unicode-Character-Properties">perlunicode Unicode
Character Properties</a>.
-</p>
-<p>Mnemonic: <em>p</em>roperty.
-</p>
-<hr>
-<a name="perlrebackslash-Referencing"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Assertions" accesskey="n"
rel="next">perlrebackslash Assertions</a>, Previous: <a
href="#perlrebackslash-Character-classes" accesskey="p"
rel="prev">perlrebackslash Character classes</a>, Up: <a
href="#perlrebackslash-DESCRIPTION" accesskey="u" rel="up">perlrebackslash
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Referencing"></a>
-<h4 class="subsection">60.2.6 Referencing</h4>
-
-<p>If capturing parenthesis are used in a regular expression, we can refer
-to the part of the source string that was matched, and match exactly the
-same thing. There are three ways of referring to such <em>backreference</em>:
-absolutely, relatively, and by name.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Absolute-referencing" accesskey="1">perlrebackslash
Absolute referencing</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrebackslash-Examples-1"
accesskey="2">perlrebackslash Examples 1</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Relative-referencing" accesskey="3">perlrebackslash
Relative referencing</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrebackslash-Examples-2"
accesskey="4">perlrebackslash Examples 2</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrebackslash-Named-referencing" accesskey="5">perlrebackslash Named
referencing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrebackslash-Examples-3"
accesskey="6">perlrebackslash Examples 3</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrebackslash-Absolute-referencing"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Examples-1" accesskey="n"
rel="next">perlrebackslash Examples 1</a>, Up: <a
href="#perlrebackslash-Referencing" accesskey="u" rel="up">perlrebackslash
Referencing</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Absolute-referencing"></a>
-<h4 class="subsubsection">60.2.6.1 Absolute referencing</h4>
-
-<p>Either <code>\g<em>N</em></code> (starting in Perl 5.10.0), or
<code>\<em>N</em></code> (old-style) where <em>N</em>
-is a positive (unsigned) decimal number of any length is an absolute reference
-to a capturing group.
-</p>
-<p><em>N</em> refers to the Nth set of parentheses, so
<code>\g<em>N</em></code> refers to whatever has
-been matched by that set of parentheses. Thus <code>\g1</code> refers to the
first
-capture group in the regex.
-</p>
-<p>The <code>\g<em>N</em></code> form can be equivalently written as
<code>\g{<em>N</em>}</code>
-which avoids ambiguity when building a regex by concatenating shorter
-strings. Otherwise if you had a regex <code>qr/$a$b/</code>, and
<code>$a</code> contained
-<code>"\g1"</code>, and <code>$b</code> contained
<code>"37"</code>, you would get <code>/\g137/</code> which is
-probably not what you intended.
-</p>
-<p>In the <code>\<em>N</em></code> form, <em>N</em> must not begin with a
"0", and there must be at
-least <em>N</em> capturing groups, or else <em>N</em> is considered an octal
escape
-(but something like <code>\18</code> is the same as <code>\0018</code>; that
is, the octal escape
-<code>"\001"</code> followed by a literal digit
<code>"8"</code>).
-</p>
-<p>Mnemonic: <em>g</em>roup.
-</p>
-<hr>
-<a name="perlrebackslash-Examples-1"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Relative-referencing" accesskey="n"
rel="next">perlrebackslash Relative referencing</a>, Previous: <a
href="#perlrebackslash-Absolute-referencing" accesskey="p"
rel="prev">perlrebackslash Absolute referencing</a>, Up: <a
href="#perlrebackslash-Referencing" accesskey="u" rel="up">perlrebackslash
Referencing</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Examples-3"></a>
-<h4 class="subsubsection">60.2.6.2 Examples</h4>
-
-<pre class="verbatim"> /(\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").
-</pre>
-<hr>
-<a name="perlrebackslash-Relative-referencing"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Examples-2" accesskey="n"
rel="next">perlrebackslash Examples 2</a>, Previous: <a
href="#perlrebackslash-Examples-1" accesskey="p" rel="prev">perlrebackslash
Examples 1</a>, Up: <a href="#perlrebackslash-Referencing" accesskey="u"
rel="up">perlrebackslash Referencing</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Relative-referencing"></a>
-<h4 class="subsubsection">60.2.6.3 Relative referencing</h4>
-
-<p><code>\g-<em>N</em></code> (starting in Perl 5.10.0) is used for relative
addressing. (It can
-be written as <code>\g{-<em>N</em></code>.) It refers to the <em>N</em>th
group before the
-<code>\g{-<em>N</em>}</code>.
-</p>
-<p>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.
-</p>
-<hr>
-<a name="perlrebackslash-Examples-2"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Named-referencing" accesskey="n"
rel="next">perlrebackslash Named referencing</a>, Previous: <a
href="#perlrebackslash-Relative-referencing" accesskey="p"
rel="prev">perlrebackslash Relative referencing</a>, Up: <a
href="#perlrebackslash-Referencing" accesskey="u" rel="up">perlrebackslash
Referencing</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Examples-4"></a>
-<h4 class="subsubsection">60.2.6.4 Examples</h4>
-
-<pre class="verbatim"> /(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".
-
- my $qr = qr /(.)(.)\g{-2}\g{-1}/; # Matches 'abab', 'cdcd', etc.
- /$qr$qr/ # Matches 'ababcdcd'.
-</pre>
-<hr>
-<a name="perlrebackslash-Named-referencing"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Examples-3" accesskey="n"
rel="next">perlrebackslash Examples 3</a>, Previous: <a
href="#perlrebackslash-Examples-2" accesskey="p" rel="prev">perlrebackslash
Examples 2</a>, Up: <a href="#perlrebackslash-Referencing" accesskey="u"
rel="up">perlrebackslash Referencing</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Named-referencing"></a>
-<h4 class="subsubsection">60.2.6.5 Named referencing</h4>
-
-<p><code>\g{<em>name</em>}</code> (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.
-</p>
-<p>To be compatible with .Net regular expressions, <code>\g{name}</code> may
also be
-written as <code>\k{name}</code>, <code>\k<name></code> or
<code>\k'name'</code>.
-</p>
-<p>To prevent any ambiguity, <em>name</em> must not start with a digit nor
contain a
-hyphen.
-</p>
-<hr>
-<a name="perlrebackslash-Examples-3"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlrebackslash-Named-referencing" accesskey="p"
rel="prev">perlrebackslash Named referencing</a>, Up: <a
href="#perlrebackslash-Referencing" accesskey="u" rel="up">perlrebackslash
Referencing</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Examples-5"></a>
-<h4 class="subsubsection">60.2.6.6 Examples</h4>
-
-<pre class="verbatim"> /(?<word>\w+) \g{word}/ # Finds duplicated word,
(e.g. "cat cat")
- /(?<word>\w+) \k{word}/ # Same.
- /(?<word>\w+) \k<word>/ # Same.
- /(?<letter1>.)(?<letter2>.)\g{letter2}\g{letter1}/
- # Match a four letter palindrome (e.g.
"ABBA")
-</pre>
-<hr>
-<a name="perlrebackslash-Assertions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrebackslash-Misc" accesskey="n" rel="next">perlrebackslash
Misc</a>, Previous: <a href="#perlrebackslash-Referencing" accesskey="p"
rel="prev">perlrebackslash Referencing</a>, Up: <a
href="#perlrebackslash-DESCRIPTION" accesskey="u" rel="up">perlrebackslash
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Assertions-1"></a>
-<h4 class="subsection">60.2.7 Assertions</h4>
-
-<p>Assertions are conditions that have to be true; they don’t actually
-match parts of the substring. There are six assertions that are written as
-backslash sequences.
-</p>
-<dl compact="compact">
-<dt>\A</dt>
-<dd><a name="perlrebackslash-_005cA"></a>
-<p><code>\A</code> only matches at the beginning of the string. If the
<code>/m</code> modifier
-isn’t used, then <code>/\A/</code> is equivalent to <code>/^/</code>.
However, if the <code>/m</code>
-modifier is used, then <code>/^/</code> matches internal newlines, but the
meaning
-of <code>/\A/</code> isn’t changed by the <code>/m</code> modifier.
<code>\A</code> matches at the beginning
-of the string regardless whether the <code>/m</code> modifier is used.
-</p>
-</dd>
-<dt>\z, \Z</dt>
-<dd><a name="perlrebackslash-_005cz_002c-_005cZ"></a>
-<p><code>\z</code> and <code>\Z</code> match at the end of the string. If the
<code>/m</code> modifier isn’t
-used, then <code>/\Z/</code> is equivalent to <code>/$/</code>; that is, it
matches at the
-end of the string, or one before the newline at the end of the string. If the
-<code>/m</code> modifier is used, then <code>/$/</code> matches at internal
newlines, but the
-meaning of <code>/\Z/</code> isn’t changed by the <code>/m</code>
modifier. <code>\Z</code> matches at
-the end of the string (or just before a trailing newline) regardless whether
-the <code>/m</code> modifier is used.
-</p>
-<p><code>\z</code> is just like <code>\Z</code>, except that it does not match
before a trailing
-newline. <code>\z</code> 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.
-</p>
-</dd>
-<dt>\G</dt>
-<dd><a name="perlrebackslash-_005cG"></a>
-<p><code>\G</code> is usually used only in combination with the
<code>/g</code> modifier. If the
-<code>/g</code> 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.
-</p>
-<p><code>\G</code> matches the point where the previous match on that string
ended,
-or the beginning of that string if there was no previous match.
-</p>
-<p>Mnemonic: <em>G</em>lobal.
-</p>
-</dd>
-<dt>\b{}, \b, \B{}, \B</dt>
-<dd><a
name="perlrebackslash-_005cb_007b_007d_002c-_005cb_002c-_005cB_007b_007d_002c-_005cB"></a>
-<p><code>\b{...}</code>, available starting in v5.22, matches a boundary
(between two
-characters, or before the first character of the string, or after the
-final character of the string) based on the Unicode rules for the
-boundary type specified inside the braces. The currently known boundary
-types are given a few paragraphs below. <code>\B{...}</code> matches at any
place
-between characters where <code>\b{...}</code> of the same type doesn’t
match.
-</p>
-<p><code>\b</code> when not immediately followed by a
<code>"{"</code> matches at any place
-between a word (something matched by <code>\w</code>) and a non-word character
-(<code>\W</code>); <code>\B</code> when not immediately followed by a
<code>"{"</code> matches at any
-place between characters where <code>\b</code> doesn’t match. To get
better
-word matching of natural language text, see <a href="bwb.html#Top">(bwb)</a>
below.
-</p>
-<p><code>\b</code>
-and <code>\B</code> assume there’s a non-word character before the
beginning and after
-the end of the source string; so <code>\b</code> will match at the beginning
(or end)
-of the source string if the source string begins (or ends) with a word
-character. Otherwise, <code>\B</code> will match.
-</p>
-<p>Do not use something like <code>\b=head\d\b</code> 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 plain <code>\b</code> and <code>\B</code> boundary determinations look for
word
-characters alone, not for
-non-word characters nor for string ends. It may help to understand how
-<\b> and <\B> work by equating them as follows:
-</p>
-<pre class="verbatim"> \b really means
(?:(?<=\w)(?!\w)|(?<!\w)(?=\w))
- \B really means (?:(?<=\w)(?=\w)|(?<!\w)(?!\w))
-</pre>
-<p>In contrast, <code>\b{...}</code> and <code>\B{...}</code> may or may not
match at the
-beginning and end of the line, depending on the boundary type. These
-implement the Unicode default boundaries, specified in
-<a
href="http://www.unicode.org/reports/tr29/";>http://www.unicode.org/reports/tr29/</a>.
-The boundary types currently available are:
-</p>
-<dl compact="compact">
-<dt><code>\b{gcb}</code> or <code>\b{g}</code></dt>
-<dd><a name="perlrebackslash-_005cb_007bgcb_007d-or-_005cb_007bg_007d"></a>
-<p>This matches a Unicode "Grapheme Cluster Boundary". (Actually
Perl
-always uses the improved "extended" grapheme cluster"). These
are
-explained below under <a href="#perlrebackslash-_005cX">\X</a>. In fact,
<code>\X</code> is another way to get
-the same functionality. It is equivalent to <code>/.+?\b{gcb}/</code>. Use
-whichever is most convenient for your situation.
-</p>
-</dd>
-<dt><code>\b{sb}</code></dt>
-<dd><a name="perlrebackslash-_005cb_007bsb_007d"></a>
-<p>This matches a Unicode "Sentence Boundary". This is an aid to
parsing
-natural language sentences. It gives good, but imperfect results. For
-example, it thinks that "Mr. Smith" is two sentences. More details
are
-at <a
href="http://www.unicode.org/reports/tr29/";>http://www.unicode.org/reports/tr29/</a>.
Note also that it thinks
-that anything matching <a href="#perlrebackslash-_005cR">\R</a> (except form
feed and vertical tab) is a
-sentence boundary. <code>\b{sb}</code> works with text designed for
-word-processors which wrap lines
-automatically for display, but hard-coded line boundaries are considered
-to be essentially the ends of text blocks (paragraphs really), and hence
-the ends of sententces. <code>\b{sb}</code> doesn’t do well with text
containing
-embedded newlines, like the source text of the document you are reading.
-Such text needs to be preprocessed to get rid of the line separators
-before looking for sentence boundaries. Some people view this as a bug
-in the Unicode standard, and this behavior is quite subject to change in
-future Perl versions.
-</p>
-</dd>
-<dt><code>\b{wb}</code></dt>
-<dd><a name="perlrebackslash-_005cb_007bwb_007d"></a>
-<p>This matches a Unicode "Word Boundary". This gives better
(though not
-perfect) results for natural language processing than plain <code>\b</code>
-(without braces) does. For example, it understands that apostrophes can
-be in the middle of words and that parentheses aren’t (see the examples
-below). More details are at <a
href="http://www.unicode.org/reports/tr29/";>http://www.unicode.org/reports/tr29/</a>.
-</p>
-</dd>
-</dl>
-
-<p>It is important to realize when you use these Unicode boundaries,
-that you are taking a risk that a future version of Perl which contains
-a later version of the Unicode Standard will not work precisely the same
-way as it did when your code was written. These rules are not
-considered stable and have been somewhat more subject to change than the
-rest of the Standard. Unicode reserves the right to change them at
-will, and Perl reserves the right to update its implementation to
-Unicode’s new rules. In the past, some changes have been because new
-characters have been added to the Standard which have different
-characteristics than all previous characters, so new rules are
-formulated for handling them. These should not cause any backward
-compatibility issues. But some changes have changed the treatment of
-existing characters because the Unicode Technical Committee has decided
-that the change is warranted for whatever reason. This could be to fix
-a bug, or because they think better results are obtained with the new
-rule.
-</p>
-<p>It is also important to realize that these are default boundary
-definitions, and that implementations may wish to tailor the results for
-particular purposes and locales.
-</p>
-<p>Unicode defines a fourth boundary type, accessible through the
-<a href="Unicode-LineBreak.html#Top">(Unicode-LineBreak)</a> module.
-</p>
-<p>Mnemonic: <em>b</em>oundary.
-</p>
-</dd>
-</dl>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlrebackslash-Examples-4"
accesskey="1">perlrebackslash Examples 4</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrebackslash-Examples-4"></a>
-<div class="header">
-<p>
-Up: <a href="#perlrebackslash-Assertions" accesskey="u"
rel="up">perlrebackslash Assertions</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Examples-6"></a>
-<h4 class="subsubsection">60.2.7.1 Examples</h4>
-
-<pre class="verbatim"> "cat" =~ /\Acat/; # Match.
- "cat" =~ /cat\Z/; # Match.
- "cat\n" =~ /cat\Z/; # Match.
- "cat\n" =~ /cat\z/; # No match.
-
- "cat" =~ /\bcat\b/; # Matches.
- "cats" =~ /\bcat\b/; # No match.
- "cat" =~ /\bcat\B/; # No match.
- "cats" =~ /\bcat\B/; # Match.
-
- while ("cat dog" =~ /(\w+)/g) {
- print $1; # Prints 'catdog'
- }
- while ("cat dog" =~ /\G(\w+)/g) {
- print $1; # Prints 'cat'
- }
-
- my $s = "He said, \"Is pi 3.14? (I'm not sure).\"";
- print join("|", $s =~ m/ ( .+? \b ) /xg), "\n";
- print join("|", $s =~ m/ ( .+? \b{wb} ) /xg), "\n";
- prints
- He| |said|, "|Is| |pi| |3|.|14|? (|I|'|m| |not| |sure
- He| |said|,| |"|Is| |pi| |3.14|?| |(|I'm| |not| |sure|)|.|"
-</pre>
-<hr>
-<a name="perlrebackslash-Misc"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlrebackslash-Assertions" accesskey="p"
rel="prev">perlrebackslash Assertions</a>, Up: <a
href="#perlrebackslash-DESCRIPTION" accesskey="u" rel="up">perlrebackslash
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Misc"></a>
-<h4 class="subsection">60.2.8 Misc</h4>
-
-<p>Here we document the backslash sequences that don’t fall in one of the
-categories above. These are:
-</p>
-<dl compact="compact">
-<dt>\C</dt>
-<dd><a name="perlrebackslash-_005cC"></a>
-<p>(Deprecated.) <code>\C</code> 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.
-This is very dangerous, because it violates
-the logical character abstraction and can cause UTF-8 sequences to become
malformed.
-</p>
-<p>Use <code>utf8::encode()</code> instead.
-</p>
-<p>Mnemonic: o<em>C</em>tet.
-</p>
-</dd>
-<dt>\K</dt>
-<dd><a name="perlrebackslash-_005cK"></a>
-<p>This appeared in perl 5.10.0. Anything matched left of <code>\K</code> is
-not included in <code>$&</code>, and will not be replaced if the pattern is
-used in a substitution. This lets you write <code>s/PAT1 \K PAT2/REPL/x</code>
-instead of <code>s/(PAT1) PAT2/${1}REPL/x</code> or <code>s/(?<=PAT1)
PAT2/REPL/x</code>.
-</p>
-<p>Mnemonic: <em>K</em>eep.
-</p>
-</dd>
-<dt>\N</dt>
-<dd><a name="perlrebackslash-_005cN"></a>
-<p>This feature, available starting in v5.12, matches any character
-that is <strong>not</strong> a newline. It is a short-hand for writing
<code>[^\n]</code>, and is
-identical to the <code>.</code> metasymbol, except under the <code>/s</code>
flag, which changes
-the meaning of <code>.</code>, but not <code>\N</code>.
-</p>
-<p>Note that <code>\N{...}</code> can mean a
-<a
href="#perlrebackslash-Named-or-numbered-characters-and-character-sequences">named
or numbered character</a>.
-</p>
-<p>Mnemonic: Complement of <em>\n</em>.
-</p>
-</dd>
-<dt>\R</dt>
-<dd><a name="perlrebackslash-_005cR"></a>
-<p><code>\R</code> matches a <em>generic newline</em>; that is, anything
considered a
-linebreak sequence by Unicode. This includes all characters matched by
-<code>\v</code> (vertical whitespace), and the multi character sequence
<code>"\x0D\x0A"</code>
-(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). <code>\R</code> is equivalent to
<code>(?>\x0D\x0A|\v)</code>. (The
-reason it doesn’t backtrack is that the sequence is considered
-inseparable. That means that
-</p>
-<pre class="verbatim"> "\x0D\x0A" =~ /^\R\x0A$/ # No match
-</pre>
-<p>fails, because the <code>\R</code> matches the entire string, and
won’t backtrack
-to match just the <code>"\x0D"</code>.) Since
-<code>\R</code> can match a sequence of more than one character, it cannot be
put
-inside a bracketed character class; <code>/[\R]/</code> is an error; use
<code>\v</code>
-instead. <code>\R</code> was introduced in perl 5.10.0.
-</p>
-<p>Note that this does not respect any locale that might be in effect; it
-matches according to the platform’s native character set.
-</p>
-<p>Mnemonic: none really. <code>\R</code> was picked because PCRE already uses
<code>\R</code>,
-and more importantly because Unicode recommends such a regular expression
-metacharacter, and suggests <code>\R</code> as its notation.
-</p>
-</dd>
-<dt>\X</dt>
-<dd><a name="perlrebackslash-_005cX"></a>
-<p>This matches a Unicode <em>extended grapheme cluster</em>.
-</p>
-<p><code>\X</code> matches quite well what normal (non-Unicode-programmer)
usage
-would consider a single character. As an example, consider a G with some sort
-of diacritic mark, such as an arrow. There is no such single character in
-Unicode, but one can be composed by using a G followed by a Unicode
"COMBINING
-UPWARDS ARROW BELOW", and would be displayed by Unicode-aware software as
if it
-were a single character.
-</p>
-<p>The match is greedy and non-backtracking, so that the cluster is never
-broken up into smaller components.
-</p>
-<p>See also <a
href="#perlrebackslash-_005cb_007b_007d_002c-_005cb_002c-_005cB_007b_007d_002c-_005cB"><code>\b{gcb}</code></a>.
-</p>
-<p>Mnemonic: e<em>X</em>tended Unicode character.
-</p>
-</dd>
-</dl>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlrebackslash-Examples-5"
accesskey="1">perlrebackslash Examples 5</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrebackslash-Examples-5"></a>
-<div class="header">
-<p>
-Up: <a href="#perlrebackslash-Misc" accesskey="u" rel="up">perlrebackslash
Misc</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Examples-7"></a>
-<h4 class="subsubsection">60.2.8.1 Examples</h4>
-
-<pre class="verbatim"> $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{307}" =~ /^\X$/ # \X matches a P with a dot above.
-</pre>
-<hr>
-<a name="perlrecharclass"></a>
-<div class="header">
-<p>
-Next: <a href="#perlref" accesskey="n" rel="next">perlref</a>, Previous: <a
href="#perlrebackslash" accesskey="p" rel="prev">perlrebackslash</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlrecharclass-1"></a>
-<h2 class="chapter">61 perlrecharclass</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlrecharclass-NAME"
accesskey="1">perlrecharclass NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-DESCRIPTION" accesskey="2">perlrecharclass
DESCRIPTION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrecharclass-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-DESCRIPTION" accesskey="n"
rel="next">perlrecharclass DESCRIPTION</a>, Up: <a href="#perlrecharclass"
accesskey="u" rel="up">perlrecharclass</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-60"></a>
-<h3 class="section">61.1 NAME</h3>
-
-<p>perlrecharclass - Perl Regular Expression Character Classes
-</p>
-<hr>
-<a name="perlrecharclass-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlrecharclass-NAME" accesskey="p"
rel="prev">perlrecharclass NAME</a>, Up: <a href="#perlrecharclass"
accesskey="u" rel="up">perlrecharclass</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-59"></a>
-<h3 class="section">61.2 DESCRIPTION</h3>
-
-<p>The top level documentation about Perl regular expressions
-is found in <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-<p>This manual page discusses the syntax and use of character
-classes in Perl regular expressions.
-</p>
-<p>A character class is a way of denoting a set of characters
-in such a way that one character of the set is matched.
-It’s important to remember that: matching a character class
-consumes exactly one character in the source string. (The source
-string is the string the regular expression is matched against.)
-</p>
-<p>There are three types of character classes in Perl regular
-expressions: the dot, backslash sequences, and the form enclosed in square
-brackets. Keep in mind, though, that often the term "character
class" is used
-to mean just the bracketed form. Certainly, most Perl documentation does that.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlrecharclass-The-dot"
accesskey="1">perlrecharclass The dot</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Backslash-sequences" accesskey="2">perlrecharclass
Backslash sequences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Bracketed-Character-Classes"
accesskey="3">perlrecharclass Bracketed Character
Classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrecharclass-The-dot"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-Backslash-sequences" accesskey="n"
rel="next">perlrecharclass Backslash sequences</a>, Up: <a
href="#perlrecharclass-DESCRIPTION" accesskey="u" rel="up">perlrecharclass
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-dot"></a>
-<h4 class="subsection">61.2.1 The dot</h4>
-
-<p>The dot (or period), <code>.</code> is probably the most used, and certainly
-the most well-known character class. By default, a dot matches any
-character, except for the newline. That default can be changed to
-add matching the newline by using the <em>single line</em> modifier: either
-for the entire regular expression with the <code>/s</code> modifier, or
-locally with <code>(?s)</code>. (The <code><a
href="#perlrecharclass-_005cN">\N</a></code> backslash sequence, described
-below, matches any character except newline without regard to the
-<em>single line</em> modifier.)
-</p>
-<p>Here are some examples:
-</p>
-<pre class="verbatim"> "a" =~ /./ # Match
- "." =~ /./ # Match
- "" =~ /./ # No match (dot has to match a character)
- "\n" =~ /./ # No match (dot does not match a newline)
- "\n" =~ /./s # Match (global 'single line' modifier)
- "\n" =~ /(?s:.)/ # Match (local 'single line' modifier)
- "ab" =~ /^.$/ # No match (dot matches one character)
-</pre>
-<hr>
-<a name="perlrecharclass-Backslash-sequences"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-Bracketed-Character-Classes" accesskey="n"
rel="next">perlrecharclass Bracketed Character Classes</a>, Previous: <a
href="#perlrecharclass-The-dot" accesskey="p" rel="prev">perlrecharclass The
dot</a>, Up: <a href="#perlrecharclass-DESCRIPTION" accesskey="u"
rel="up">perlrecharclass DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Backslash-sequences"></a>
-<h4 class="subsection">61.2.2 Backslash sequences</h4>
-
-<p>A backslash sequence is a sequence of characters, the first one of which is
a
-backslash. Perl ascribes special meaning to many such sequences, and some of
-these are character classes. That is, they match a single character each,
-provided that the character belongs to the specific set of characters defined
-by the sequence.
-</p>
-<p>Here’s a list of the backslash sequences that are character classes.
They
-are discussed in more detail below. (For the backslash sequences that
aren’t
-character classes, see <a href="#perlrebackslash-NAME">perlrebackslash
NAME</a>.)
-</p>
-<pre class="verbatim"> \d Match a decimal digit character.
- \D Match a non-decimal-digit character.
- \w Match a "word" character.
- \W Match a non-"word" character.
- \s Match a whitespace character.
- \S Match a non-whitespace character.
- \h Match a horizontal whitespace character.
- \H Match a character that isn't horizontal whitespace.
- \v Match a vertical whitespace character.
- \V Match a character that isn't vertical whitespace.
- \N Match a character that isn't a newline.
- \pP, \p{Prop} Match a character that has the given Unicode property.
- \PP, \P{Prop} Match a character that doesn't have the Unicode property
-</pre>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlrecharclass-_005cN"
accesskey="1">perlrecharclass \N</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrecharclass-Digits"
accesskey="2">perlrecharclass Digits</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Word-characters" accesskey="3">perlrecharclass Word
characters</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrecharclass-Whitespace"
accesskey="4">perlrecharclass Whitespace</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Unicode-Properties" accesskey="5">perlrecharclass
Unicode Properties</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrecharclass-Examples"
accesskey="6">perlrecharclass Examples</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrecharclass-_005cN"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-Digits" accesskey="n"
rel="next">perlrecharclass Digits</a>, Up: <a
href="#perlrecharclass-Backslash-sequences" accesskey="u"
rel="up">perlrecharclass Backslash sequences</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="g_t_005cN"></a>
-<h4 class="subsubsection">61.2.2.1 \N</h4>
-
-<p><code>\N</code>, available starting in v5.12, like the dot, matches any
-character that is not a newline. The difference is that <code>\N</code> is not
influenced
-by the <em>single line</em> regular expression modifier (see <a
href="#perlrecharclass-The-dot">The dot</a> above). Note
-that the form <code>\N{...}</code> may mean something completely different.
When the
-<code>{...}</code> is a <a href="#perlre-Quantifiers">quantifier</a>, it means
to match a non-newline
-character that many times. For example, <code>\N{3}</code> means to match 3
-non-newlines; <code>\N{5,}</code> means to match 5 or more non-newlines. But
if <code>{...}</code>
-is not a legal quantifier, it is presumed to be a named character. See
-<a href="charnames.html#Top">(charnames)</a> for those. For example, none of
<code>\N{COLON}</code>, <code>\N{4F}</code>, and
-<code>\N{F4}</code> contain legal quantifiers, so Perl will try to find
characters whose
-names are respectively <code>COLON</code>, <code>4F</code>, and
<code>F4</code>.
-</p>
-<hr>
-<a name="perlrecharclass-Digits"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-Word-characters" accesskey="n"
rel="next">perlrecharclass Word characters</a>, Previous: <a
href="#perlrecharclass-_005cN" accesskey="p" rel="prev">perlrecharclass \N</a>,
Up: <a href="#perlrecharclass-Backslash-sequences" accesskey="u"
rel="up">perlrecharclass Backslash sequences</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Digits"></a>
-<h4 class="subsubsection">61.2.2.2 Digits</h4>
-
-<p><code>\d</code> matches a single character considered to be a decimal
<em>digit</em>.
-If the <code>/a</code> regular expression modifier is in effect, it matches
[0-9].
-Otherwise, it
-matches anything that is matched by <code>\p{Digit}</code>, which includes
[0-9].
-(An unlikely possible exception is that under locale matching rules, the
-current locale might not have <code>[0-9]</code> matched by <code>\d</code>,
and/or might match
-other characters whose code point is less than 256. The only such locale
-definitions that are legal would be to match <code>[0-9]</code> plus another
set of
-10 consecutive digit characters; anything else would be in violation of
-the C language standard, but Perl doesn’t currently assume anything in
-regard to this.)
-</p>
-<p>What this means is that unless the <code>/a</code> modifier is in effect
<code>\d</code> 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.
-</p>
-<p>Some digits that <code>\d</code> 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
-<code>\d+</code>, 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. <a
href="Unicode-UCD.html#num_0028_0029">(Unicode-UCD)num()</a> can
-be used to safely
-calculate the value, returning <code>undef</code> if the input string contains
-such a mixture.
-</p>
-<p>What <code>\p{Digit}</code> means (and hence <code>\d</code> except under
the <code>/a</code>
-modifier) is <code>\p{General_Category=Decimal_Number}</code>, or synonymously,
-<code>\p{General_Category=Digit}</code>. Starting with Unicode version 4.1,
this
-is the same set of characters matched by <code>\p{Numeric_Type=Decimal}</code>.
-But Unicode also has a different property with a similar name,
-<code>\p{Numeric_Type=Digit}</code>, which matches a completely different set
of
-characters. These characters are things such as <code>CIRCLED DIGIT ONE</code>
-or subscripts, or are from writing systems that lack all ten digits.
-</p>
-<p>The design intent is for <code>\d</code> 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",
-<code>\p{Numeric_Type=Digit}</code>, and so <code>\d</code> doesn’t
match them.
-</p>
-<p>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 <a
href="http://www.unicode.org/notes/tn21";>http://www.unicode.org/notes/tn21</a>.)
-</p>
-<p>Any character not matched by <code>\d</code> is matched by <code>\D</code>.
-</p>
-<hr>
-<a name="perlrecharclass-Word-characters"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-Whitespace" accesskey="n"
rel="next">perlrecharclass Whitespace</a>, Previous: <a
href="#perlrecharclass-Digits" accesskey="p" rel="prev">perlrecharclass
Digits</a>, Up: <a href="#perlrecharclass-Backslash-sequences" accesskey="u"
rel="up">perlrecharclass Backslash sequences</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Word-characters"></a>
-<h4 class="subsubsection">61.2.2.3 Word characters</h4>
-
-<p>A <code>\w</code> matches a single alphanumeric character (an alphabetic
character, or a
-decimal digit); or a connecting punctuation character, such as an
-underscore ("_"); or a "mark" character (like some sort of
accent) that
-attaches to one of those. It does not match a whole word. To match a
-whole word, use <code>\w+</code>. 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.
-</p>
-<dl compact="compact">
-<dt>If the <code>/a</code> modifier is in effect ...</dt>
-<dd><a
name="perlrecharclass-If-the-_002fa-modifier-is-in-effect-_002e_002e_002e"></a>
-<p><code>\w</code> matches the 63 characters [a-zA-Z0-9_].
-</p>
-</dd>
-<dt>otherwise ...</dt>
-<dd><a name="perlrecharclass-otherwise-_002e_002e_002e"></a>
-<dl compact="compact">
-<dt>For code points above 255 ...</dt>
-<dd><a name="perlrecharclass-For-code-points-above-255-_002e_002e_002e"></a>
-<p><code>\w</code> matches the same as <code>\p{Word}</code> 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 <code>COMBINING TILDE</code> and the modifier letters,
which
-are generally used to add auxiliary markings to letters.
-</p>
-</dd>
-<dt>For code points below 256 ...</dt>
-<dd><a name="perlrecharclass-For-code-points-below-256-_002e_002e_002e"></a>
-<dl compact="compact">
-<dt>if locale rules are in effect ...</dt>
-<dd><a
name="perlrecharclass-if-locale-rules-are-in-effect-_002e_002e_002e"></a>
-<p><code>\w</code> matches the platform’s native underscore character
plus whatever
-the locale considers to be alphanumeric.
-</p>
-</dd>
-<dt>if Unicode rules are in effect ...</dt>
-<dd><a
name="perlrecharclass-if-Unicode-rules-are-in-effect-_002e_002e_002e"></a>
-<p><code>\w</code> matches exactly what <code>\p{Word}</code> matches.
-</p>
-</dd>
-<dt>otherwise ...</dt>
-<dd><a name="perlrecharclass-otherwise-_002e_002e_002e-1"></a>
-<p><code>\w</code> matches [a-zA-Z0-9_].
-</p>
-</dd>
-</dl>
-
-</dd>
-</dl>
-
-</dd>
-</dl>
-
-<p>Which rules apply are determined as described in <a
href="#perlre-Which-character-set-modifier-is-in-effect_003f">perlre Which
character set modifier is in effect?</a>.
-</p>
-<p>There are a number of security issues with the full Unicode list of word
-characters. See <a
href="http://unicode.org/reports/tr36";>http://unicode.org/reports/tr36</a>.
-</p>
-<p>Also, for a somewhat finer-grained set of characters that are in programming
-language identifiers beyond the ASCII range, you may wish to instead use the
-more customized <a href="#perlrecharclass-Unicode-Properties">Unicode
Properties</a>, <code>\p{ID_Start}</code>,
-<code>\p{ID_Continue}</code>, <code>\p{XID_Start}</code>, and
<code>\p{XID_Continue}</code>. See
-<a href="http://unicode.org/reports/tr31";>http://unicode.org/reports/tr31</a>.
-</p>
-<p>Any character not matched by <code>\w</code> is matched by <code>\W</code>.
-</p>
-<hr>
-<a name="perlrecharclass-Whitespace"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-Unicode-Properties" accesskey="n"
rel="next">perlrecharclass Unicode Properties</a>, Previous: <a
href="#perlrecharclass-Word-characters" accesskey="p"
rel="prev">perlrecharclass Word characters</a>, Up: <a
href="#perlrecharclass-Backslash-sequences" accesskey="u"
rel="up">perlrecharclass Backslash sequences</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Whitespace"></a>
-<h4 class="subsubsection">61.2.2.4 Whitespace</h4>
-
-<p><code>\s</code> matches any single character considered whitespace.
-</p>
-<dl compact="compact">
-<dt>If the <code>/a</code> modifier is in effect ...</dt>
-<dd><a
name="perlrecharclass-If-the-_002fa-modifier-is-in-effect-_002e_002e_002e-1"></a>
-<p>In all Perl versions, <code>\s</code> matches the 5 characters [\t\n\f\r ];
that
-is, the horizontal tab,
-the newline, the form feed, the carriage return, and the space.
-Starting in Perl v5.18, it also matches the vertical tab, <code>\cK</code>.
-See note <code>[1]</code> below for a discussion of this.
-</p>
-</dd>
-<dt>otherwise ...</dt>
-<dd><a name="perlrecharclass-otherwise-_002e_002e_002e-2"></a>
-<dl compact="compact">
-<dt>For code points above 255 ...</dt>
-<dd><a name="perlrecharclass-For-code-points-above-255-_002e_002e_002e-1"></a>
-<p><code>\s</code> matches exactly the code points above 255 shown with an
"s" column
-in the table below.
-</p>
-</dd>
-<dt>For code points below 256 ...</dt>
-<dd><a name="perlrecharclass-For-code-points-below-256-_002e_002e_002e-1"></a>
-<dl compact="compact">
-<dt>if locale rules are in effect ...</dt>
-<dd><a
name="perlrecharclass-if-locale-rules-are-in-effect-_002e_002e_002e-1"></a>
-<p><code>\s</code> matches whatever the locale considers to be whitespace.
-</p>
-</dd>
-<dt>if Unicode rules are in effect ...</dt>
-<dd><a
name="perlrecharclass-if-Unicode-rules-are-in-effect-_002e_002e_002e-1"></a>
-<p><code>\s</code> matches exactly the characters shown with an "s"
column in the
-table below.
-</p>
-</dd>
-<dt>otherwise ...</dt>
-<dd><a name="perlrecharclass-otherwise-_002e_002e_002e-3"></a>
-<p><code>\s</code> matches [\t\n\f\r ] and, starting in Perl
-v5.18, the vertical tab, <code>\cK</code>.
-(See note <code>[1]</code> below for a discussion of this.)
-Note that this list doesn’t include the non-breaking space.
-</p>
-</dd>
-</dl>
-
-</dd>
-</dl>
-
-</dd>
-</dl>
-
-<p>Which rules apply are determined as described in <a
href="#perlre-Which-character-set-modifier-is-in-effect_003f">perlre Which
character set modifier is in effect?</a>.
-</p>
-<p>Any character not matched by <code>\s</code> is matched by <code>\S</code>.
-</p>
-<p><code>\h</code> matches any character considered horizontal whitespace;
-this includes the platform’s space and tab characters and several others
-listed in the table below. <code>\H</code> matches any character
-not considered horizontal whitespace. They use the platform’s native
-character set, and do not consider any locale that may otherwise be in
-use.
-</p>
-<p><code>\v</code> matches any character considered vertical whitespace;
-this includes the platform’s carriage return and line feed characters
(newline)
-plus several other characters, all listed in the table below.
-<code>\V</code> matches any character not considered vertical whitespace.
-They use the platform’s native character set, and do not consider any
-locale that may otherwise be in use.
-</p>
-<p><code>\R</code> matches anything that can be considered a newline under
Unicode
-rules. It can match a multi-character sequence. It cannot be used inside
-a bracketed character class; use <code>\v</code> instead (vertical whitespace).
-It uses the platform’s
-native character set, and does not consider any locale that may
-otherwise be in use.
-Details are discussed in <a href="#perlrebackslash-NAME">perlrebackslash
NAME</a>.
-</p>
-<p>Note that unlike <code>\s</code> (and <code>\d</code> and <code>\w</code>),
<code>\h</code> and <code>\v</code> always match
-the same characters, without regard to other factors, such as the active
-locale or whether the source string is in UTF-8 format.
-</p>
-<p>One might think that <code>\s</code> is equivalent to <code>[\h\v]</code>.
This is indeed true
-starting in Perl v5.18, but prior to that, the sole difference was that the
-vertical tab (<code>"\cK"</code>) was not matched by <code>\s</code>.
-</p>
-<p>The following table is a complete listing of characters matched by
-<code>\s</code>, <code>\h</code> and <code>\v</code> as of Unicode 6.3.
-</p>
-<p>The first column gives the Unicode code point of the character (in hex
format),
-the second column gives the (Unicode) name. The third column indicates
-by which class(es) the character is matched (assuming no locale is in
-effect that changes the <code>\s</code> matching).
-</p>
-<pre class="verbatim"> 0x0009 CHARACTER TABULATION h s
- 0x000a LINE FEED (LF) vs
- 0x000b LINE TABULATION vs [1]
- 0x000c FORM FEED (FF) vs
- 0x000d CARRIAGE RETURN (CR) vs
- 0x0020 SPACE h s
- 0x0085 NEXT LINE (NEL) vs [2]
- 0x00a0 NO-BREAK SPACE h s [2]
- 0x1680 OGHAM SPACE MARK h s
- 0x2000 EN QUAD h s
- 0x2001 EM QUAD h s
- 0x2002 EN SPACE h s
- 0x2003 EM SPACE h s
- 0x2004 THREE-PER-EM SPACE h s
- 0x2005 FOUR-PER-EM SPACE h s
- 0x2006 SIX-PER-EM SPACE h s
- 0x2007 FIGURE SPACE h s
- 0x2008 PUNCTUATION SPACE h s
- 0x2009 THIN SPACE h s
- 0x200a HAIR SPACE h s
- 0x2028 LINE SEPARATOR vs
- 0x2029 PARAGRAPH SEPARATOR vs
- 0x202f NARROW NO-BREAK SPACE h s
- 0x205f MEDIUM MATHEMATICAL SPACE h s
- 0x3000 IDEOGRAPHIC SPACE h s
-</pre>
-<dl compact="compact">
-<dt>[1]</dt>
-<dd><a name="perlrecharclass-_005b1_005d"></a>
-<p>Prior to Perl v5.18, <code>\s</code> did not match the vertical tab.
-<code>[^\S\cK]</code> (obscurely) matches what <code>\s</code> traditionally
did.
-</p>
-</dd>
-<dt>[2]</dt>
-<dd><a name="perlrecharclass-_005b2_005d"></a>
-<p>NEXT LINE and NO-BREAK SPACE may or may not match <code>\s</code> depending
-on the rules in effect. See
-<a href="#perlrecharclass-Whitespace">the beginning of this section</a>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlrecharclass-Unicode-Properties"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-Examples" accesskey="n"
rel="next">perlrecharclass Examples</a>, Previous: <a
href="#perlrecharclass-Whitespace" accesskey="p" rel="prev">perlrecharclass
Whitespace</a>, Up: <a href="#perlrecharclass-Backslash-sequences"
accesskey="u" rel="up">perlrecharclass Backslash sequences</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-Properties"></a>
-<h4 class="subsubsection">61.2.2.5 Unicode Properties</h4>
-
-<p><code>\pP</code> and <code>\p{Prop}</code> are character classes to match
characters that fit given
-Unicode properties. One letter property names can be used in the
<code>\pP</code> form,
-with the property name following the <code>\p</code>, 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
<code>\p{name=value}</code>,
-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 <code>/\pN/</code> or as
-<code>/\p{Number}/</code>, or as <code>/\p{Number=True}/</code>.
-Lowercase letters are matched by the property <em>Lowercase_Letter</em> which
-has the short form <em>Ll</em>. They need the braces, so are written as
<code>/\p{Ll}/</code> or
-<code>/\p{Lowercase_Letter}/</code>, or
<code>/\p{General_Category=Lowercase_Letter}/</code>
-(the underscores are optional).
-<code>/\pLl/</code> is valid, but means something different.
-It matches a two character string: a letter (Unicode property
<code>\pL</code>),
-followed by a lowercase <code>l</code>.
-</p>
-<p>If locale rules are not in effect, the use of
-a Unicode property will force the regular expression into using Unicode
-rules, if it isn’t already.
-</p>
-<p>Note that almost all properties are immune to case-insensitive matching.
-That is, adding a <code>/i</code> regular expression modifier does not change
what
-they match. There are two sets that are affected. The first set is
-<code>Uppercase_Letter</code>,
-<code>Lowercase_Letter</code>,
-and <code>Titlecase_Letter</code>,
-all of which match <code>Cased_Letter</code> under <code>/i</code> matching.
-The second set is
-<code>Uppercase</code>,
-<code>Lowercase</code>,
-and <code>Titlecase</code>,
-all of which match <code>Cased</code> under <code>/i</code> matching.
-(The difference between these sets is that some things, such as Roman
-numerals, come in both upper and lower case, so they are <code>Cased</code>,
but
-aren’t considered to be letters, so they aren’t
<code>Cased_Letter</code>s. They’re
-actually <code>Letter_Number</code>s.)
-This set also includes its subsets <code>PosixUpper</code> and
<code>PosixLower</code>, both
-of which under <code>/i</code> match <code>PosixAlpha</code>.
-</p>
-<p>For more details on Unicode properties, see <a
href="#perlunicode-Unicode-Character-Properties">perlunicode Unicode Character
Properties</a>; for a
-complete list of possible properties, see
-<a
href="perluniprops.html#Properties-accessible-through-_005cp_007b_007d-and-_005cP_007b_007d">(perluniprops)Properties
accessible through \p{} and \P{}</a>,
-which notes all forms that have <code>/i</code> differences.
-It is also possible to define your own properties. This is discussed in
-<a href="#perlunicode-User_002dDefined-Character-Properties">perlunicode
User-Defined Character Properties</a>.
-</p>
-<p>Unicode properties are defined (surprise!) only on Unicode code points.
-Starting in v5.20, when matching against <code>\p</code> and <code>\P</code>,
Perl treats
-non-Unicode code points (those above the legal Unicode maximum of
-0x10FFFF) as if they were typical unassigned Unicode code points.
-</p>
-<p>Prior to v5.20, Perl raised a warning and made all matches fail on
-non-Unicode code points. This could be somewhat surprising:
-</p>
-<pre class="verbatim"> chr(0x110000) =~ \p{ASCII_Hex_Digit=True} # Fails
on Perls < v5.20.
- chr(0x110000) =~ \p{ASCII_Hex_Digit=False} # Also fails on Perls
- # < v5.20
-</pre>
-<p>Even though these two matches might be thought of as complements, until
-v5.20 they were so only on Unicode code points.
-</p>
-<hr>
-<a name="perlrecharclass-Examples"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlrecharclass-Unicode-Properties" accesskey="p"
rel="prev">perlrecharclass Unicode Properties</a>, Up: <a
href="#perlrecharclass-Backslash-sequences" accesskey="u"
rel="up">perlrecharclass Backslash sequences</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Examples-8"></a>
-<h4 class="subsubsection">61.2.2.6 Examples</h4>
-
-<pre class="verbatim"> "a" =~ /\w/ # Match, "a" is
a 'word' character.
- "7" =~ /\w/ # Match, "7" is a 'word' character as
well.
- "a" =~ /\d/ # No match, "a" isn't a digit.
- "7" =~ /\d/ # Match, "7" is a digit.
- " " =~ /\s/ # Match, a space is whitespace.
- "a" =~ /\D/ # Match, "a" is a non-digit.
- "7" =~ /\D/ # No match, "7" is not a non-digit.
- " " =~ /\S/ # No match, a space is not non-whitespace.
-
- " " =~ /\h/ # Match, space is horizontal whitespace.
- " " =~ /\v/ # No match, space is not vertical whitespace.
- "\r" =~ /\v/ # Match, a return is vertical whitespace.
-
- "a" =~ /\pL/ # Match, "a" is a letter.
- "a" =~ /\p{Lu}/ # No match, /\p{Lu}/ matches upper case letters.
-
- "\x{0e0b}" =~ /\p{Thai}/ # Match, \x{0e0b} is the character
- # 'THAI CHARACTER SO SO', and that's in
- # Thai Unicode class.
- "a" =~ /\P{Lao}/ # Match, as "a" is not a Laotian
character.
-</pre>
-<p>It is worth emphasizing that <code>\d</code>, <code>\w</code>, etc, match
single characters, not
-complete numbers or words. To match a number (that consists of digits),
-use <code>\d+</code>; to match a word, use <code>\w+</code>. But be aware of
the security
-considerations in doing so, as mentioned above.
-</p>
-<hr>
-<a name="perlrecharclass-Bracketed-Character-Classes"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlrecharclass-Backslash-sequences" accesskey="p"
rel="prev">perlrecharclass Backslash sequences</a>, Up: <a
href="#perlrecharclass-DESCRIPTION" accesskey="u" rel="up">perlrecharclass
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Bracketed-Character-Classes"></a>
-<h4 class="subsection">61.2.3 Bracketed Character Classes</h4>
-
-<p>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:
<code>[aeiou]</code>.
-This matches one of <code>a</code>, <code>e</code>, <code>i</code>,
<code>o</code> or <code>u</code>. Like the other
-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 <a
href="#perlre-Quantifiers">quantifier</a>. For
-instance, <code>[aeiou]+</code> matches one or more lowercase English vowels.
-</p>
-<p>Repeating a character in a character class has no
-effect; it’s considered to be in the set only once.
-</p>
-<p>Examples:
-</p>
-<pre class="verbatim"> "e" =~ /[aeiou]/ # Match, as
"e" is listed in the class.
- "p" =~ /[aeiou]/ # No match, "p" is not listed
in the class.
- "ae" =~ /^[aeiou]$/ # No match, a character class only matches
- # a single character.
- "ae" =~ /^[aeiou]+$/ # Match, due to the quantifier.
-
- -------
-</pre>
-<p>* There are two exceptions to a bracketed character class matching a
-single character only. Each requires special handling by Perl to make
-things work:
-</p>
-<ul>
-<li> When the class is to match caselessly under <code>/i</code> matching
rules, and a
-character that is explicitly mentioned inside the class matches a
-multiple-character sequence caselessly under Unicode rules, the class
-will also match that sequence. For example, Unicode says that the
-letter <code>LATIN SMALL LETTER SHARP S</code> should match the sequence
<code>ss</code>
-under <code>/i</code> rules. Thus,
-
-<pre class="verbatim"> 'ss' =~ /\A\N{LATIN SMALL LETTER SHARP S}\z/i
# Matches
- 'ss' =~ /\A[aeioust\N{LATIN SMALL LETTER SHARP S}]\z/i # Matches
-</pre>
-<p>For this to happen, the class must not be inverted (see <a
href="#perlrecharclass-Negation">Negation</a>)
-and the character must be explicitly specified, and not be part of a
-multi-character range (not even as one of its endpoints). (<a
href="#perlrecharclass-Character-Ranges">Character
-Ranges</a> will be explained shortly.) Therefore,
-</p>
-<pre class="verbatim"> 'ss' =~ /\A[\0-\x{ff}]\z/ui # Doesn't match
- 'ss' =~ /\A[\0-\N{LATIN SMALL LETTER SHARP S}]\z/ui # No match
- 'ss' =~ /\A[\xDF-\xDF]\z/ui # Matches on ASCII platforms, since
- # \xDF is LATIN SMALL LETTER SHARP S,
- # and the range is just a single
- # element
-</pre>
-<p>Note that it isn’t a good idea to specify these types of ranges
anyway.
-</p>
-</li><li> Some names known to <code>\N{...}</code> refer to a sequence of
multiple characters,
-instead of the usual single character. When one of these is included in
-the class, the entire sequence is matched. For example,
-
-<pre class="verbatim"> "\N{TAMIL LETTER KA}\N{TAMIL VOWEL SIGN AU}"
- =~ / ^ [\N{TAMIL SYLLABLE KAU}] $ /x;
-</pre>
-<p>matches, because <code>\N{TAMIL SYLLABLE KAU}</code> is a named sequence
-consisting of the two characters matched against. Like the other
-instance where a bracketed class can match multiple characters, and for
-similar reasons, the class must not be inverted, and the named sequence
-may not appear in a range, even one where it is both endpoints. If
-these happen, it is a fatal error if the character class is within an
-extended <a
href="#perlrecharclass-Extended-Bracketed-Character-Classes"><code>(?[...])</code></a>
-class; and only the first code point is used (with
-a <code>regexp</code>-type warning raised) otherwise.
-</p>
-</li></ul>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Special-Characters-Inside-a-Bracketed-Character-Class"
accesskey="1">perlrecharclass Special Characters Inside a Bracketed Character
Class</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Character-Ranges" accesskey="2">perlrecharclass
Character Ranges</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrecharclass-Negation"
accesskey="3">perlrecharclass Negation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Backslash-Sequences" accesskey="4">perlrecharclass
Backslash Sequences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-POSIX-Character-Classes" accesskey="5">perlrecharclass
POSIX Character Classes</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Negation-of-POSIX-character-classes"
accesskey="6">perlrecharclass Negation of POSIX character
classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-_005b_003d-_003d_005d-and-_005b_002e-_002e_005d"
accesskey="7">perlrecharclass [= =] and [. .]</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrecharclass-Examples-1"
accesskey="8">perlrecharclass Examples 1</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrecharclass-Extended-Bracketed-Character-Classes"
accesskey="9">perlrecharclass Extended Bracketed Character
Classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a
name="perlrecharclass-Special-Characters-Inside-a-Bracketed-Character-Class"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-Character-Ranges" accesskey="n"
rel="next">perlrecharclass Character Ranges</a>, Up: <a
href="#perlrecharclass-Bracketed-Character-Classes" accesskey="u"
rel="up">perlrecharclass Bracketed Character Classes</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Special-Characters-Inside-a-Bracketed-Character-Class"></a>
-<h4 class="subsubsection">61.2.3.1 Special Characters Inside a Bracketed
Character Class</h4>
-
-<p>Most characters that are meta characters in regular expressions (that
-is, characters that carry a special meaning like <code>.</code>,
<code>*</code>, or <code>(</code>) lose
-their special meaning and can be used inside a character class without
-the need to escape them. For instance, <code>[()]</code> matches either an
opening
-parenthesis, or a closing parenthesis, and the parens inside the character
-class don’t group or capture.
-</p>
-<p>Characters that may carry a special meaning inside a character class are:
-<code>\</code>, <code>^</code>, <code>-</code>, <code>[</code> and
<code>]</code>, and are discussed below. They can be
-escaped with a backslash, although this is sometimes not needed, in which
-case the backslash may be omitted.
-</p>
-<p>The sequence <code>\b</code> is special inside a bracketed character class.
While
-outside the character class, <code>\b</code> is an assertion indicating a point
-that does not have either two word characters or two non-word characters
-on either side, inside a bracketed character class, <code>\b</code> matches a
-backspace character.
-</p>
-<p>The sequences
-<code>\a</code>,
-<code>\c</code>,
-<code>\e</code>,
-<code>\f</code>,
-<code>\n</code>,
-<code>\N{<em>NAME</em>}</code>,
-<code>\N{U+<em>hex char</em>}</code>,
-<code>\r</code>,
-<code>\t</code>,
-and
-<code>\x</code>
-are also special and have the same meanings as they do outside a
-bracketed character class.
-</p>
-<p>Also, a backslash followed by two or three octal digits is considered an
octal
-number.
-</p>
-<p>A <code>[</code> is not special inside a character class, unless it’s
the start of a
-POSIX character class (see <a
href="#perlrecharclass-POSIX-Character-Classes">POSIX Character Classes</a>
below). It normally does
-not need escaping.
-</p>
-<p>A <code>]</code> is normally either the end of a POSIX character class (see
-<a href="#perlrecharclass-POSIX-Character-Classes">POSIX Character Classes</a>
below), or it signals the end of the bracketed
-character class. If you want to include a <code>]</code> in the set of
characters, you
-must generally escape it.
-</p>
-<p>However, if the <code>]</code> is the <em>first</em> (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)
-and is considered part of the set of characters that can be matched without
-escaping.
-</p>
-<p>Examples:
-</p>
-<pre class="verbatim"> "+" =~ /[+?*]/ # Match, "+"
in a character class is not special.
- "\cH" =~ /[\b]/ # Match, \b inside in a character class
- # is equivalent to a backspace.
- "]" =~ /[][]/ # Match, as the character class contains
- # both [ and ].
- "[]" =~ /[[]]/ # Match, the pattern contains a character
class
- # containing just [, and the character class is
- # followed by a ].
-</pre>
-<hr>
-<a name="perlrecharclass-Character-Ranges"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-Negation" accesskey="n"
rel="next">perlrecharclass Negation</a>, Previous: <a
href="#perlrecharclass-Special-Characters-Inside-a-Bracketed-Character-Class"
accesskey="p" rel="prev">perlrecharclass Special Characters Inside a Bracketed
Character Class</a>, Up: <a href="#perlrecharclass-Bracketed-Character-Classes"
accesskey="u" rel="up">perlrecharclass Bracketed Character Classes</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Character-Ranges"></a>
-<h4 class="subsubsection">61.2.3.2 Character Ranges</h4>
-
-<p>It is not uncommon to want to match a range of characters. Luckily, instead
-of listing all characters in the range, one may use the hyphen
(<code>-</code>).
-If inside a bracketed character class you have two characters separated
-by a hyphen, it’s treated as if all characters between the two were in
-the class. For instance, <code>[0-9]</code> matches any ASCII digit, and
<code>[a-m]</code>
-matches any lowercase letter from the first half of the ASCII alphabet.
-</p>
-<p>Note that the two characters on either side of the hyphen are not
-necessarily both letters or both digits. Any character is possible,
-although not advisable. <code>['-?]</code> contains a range of characters, but
-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.
-</p>
-<p>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 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.
-</p>
-<p>Examples:
-</p>
-<pre class="verbatim"> [a-z] # Matches a character that is a lower case
ASCII letter.
- [a-fz] # Matches any letter between 'a' and 'f' (inclusive) or
- # the letter 'z'.
- [-z] # Matches either a hyphen ('-') or the letter 'z'.
- [a-f-m] # Matches any letter between 'a' and 'f' (inclusive), the
- # hyphen ('-'), or the letter 'm'.
- ['-?] # Matches any of the characters '()*+,-./0123456789:;<=>?
- # (But not on an EBCDIC platform).
- [\N{APOSTROPHE}-\N{QUESTION MARK}]
- # Matches any of the characters '()*+,-./0123456789:;<=>?
- # even on an EBCDIC platform.
- [\N{U+27}-\N{U+3F}] # Same. (U+27 is "'", and U+3F is "?")
-</pre>
-<p>As the final two examples above show, you can achieve portablity to
-non-ASCII platforms by using the <code>\N{...}</code> form for the range
-endpoints. These indicate that the specified range is to be interpreted
-using Unicode values, so <code>[\N{U+27}-\N{U+3F}]</code> means to match
-<code>\N{U+27}</code>, <code>\N{U+28}</code>, <code>\N{U+29}</code>, ...,
<code>\N{U+3D}</code>, <code>\N{U+3E}</code>,
-and <code>\N{U+3F}</code>, whatever the native code point versions for those
are.
-These are called "Unicode" ranges. If either end is of the
<code>\N{...}</code>
-form, the range is considered Unicode. A <code>regexp</code> warning is raised
-under <code>"use re 'strict'"<!-- /@w --></code> if the
other endpoint is specified
-non-portably:
-</p>
-<pre class="verbatim"> [\N{U+00}-\x09] # Warning under re 'strict'; \x09 is
non-portable
- [\N{U+00}-\t] # No warning;
-</pre>
-<p>Both of the above match the characters <code>\N{U+00}</code>
<code>\N{U+01}</code>, ...
-<code>\N{U+08}</code>, <code>\N{U+09}</code>, but the <code>\x09</code> looks
like it could be a
-mistake so the warning is raised (under <code>re 'strict'</code>) for it.
-</p>
-<p>Perl also guarantees that the ranges <code>A-Z</code>, <code>a-z</code>,
<code>0-9</code>, and any
-subranges of these match what an English-only speaker would expect them
-to match on any platform. That is, <code>[A-Z]</code> matches the 26 ASCII
-uppercase letters;
-<code>[a-z]</code> matches the 26 lowercase letters; and <code>[0-9]</code>
matches the 10
-digits. Subranges, like <code>[h-k]</code>, match correspondingly, in this
case
-just the four letters <code>"h"</code>, <code>"i"</code>,
<code>"j"</code>, and <code>"k"</code>. This is the
-natural behavior on ASCII platforms where the code points (ordinal
-values) for <code>"h"</code> through <code>"k"</code> are
consecutive integers (0x68 through
-0x6B). But special handling to achieve this may be needed on platforms
-with a non-ASCII native character set. For example, on EBCDIC
-platforms, the code point for <code>"h"</code> is 0x88,
<code>"i"</code> is 0x89, <code>"j"</code> is
-0x91, and <code>"k"</code> is 0x92. Perl specially treats
<code>[h-k]</code> to exclude the
-seven code points in the gap: 0x8A through 0x90. This special handling is
-only invoked when the range is a subrange of one of the ASCII uppercase,
-lowercase, and digit ranges, AND each end of the range is expressed
-either as a literal, like <code>"A"</code>, or as a named character
(<code>\N{...}</code>,
-including the <code>\N{U+...</code> form).
-</p>
-<p>EBCDIC Examples:
-</p>
-<pre class="verbatim"> [i-j] # Matches either "i" or
"j"
- [i-\N{LATIN SMALL LETTER J}] # Same
- [i-\N{U+6A}] # Same
- [\N{U+69}-\N{U+6A}] # Same
- [\x{89}-\x{91}] # Matches 0x89 ("i"), 0x8A .. 0x90, 0x91
("j")
- [i-\x{91}] # Same
- [\x{89}-j] # Same
- [i-J] # Matches, 0x89 ("i") .. 0xC1 ("J");
special
- # handling doesn't apply because range is mixed
- # case
-</pre>
-<hr>
-<a name="perlrecharclass-Negation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-Backslash-Sequences" accesskey="n"
rel="next">perlrecharclass Backslash Sequences</a>, Previous: <a
href="#perlrecharclass-Character-Ranges" accesskey="p"
rel="prev">perlrecharclass Character Ranges</a>, Up: <a
href="#perlrecharclass-Bracketed-Character-Classes" accesskey="u"
rel="up">perlrecharclass Bracketed Character Classes</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Negation"></a>
-<h4 class="subsubsection">61.2.3.3 Negation</h4>
-
-<p>It is also possible to instead list the characters you do not want to
-match. You can do so by using a caret (<code>^</code>) as the first character
in the
-character class. For instance, <code>[^a-z]</code> matches any character that
is not a
-lowercase ASCII letter, which therefore includes more than a million
-Unicode code points. The class is said to be "negated" or
"inverted".
-</p>
-<p>This syntax make the caret a special character inside a bracketed character
-class, but only if it is the first character of the class. So if you want
-the caret as one of the characters to match, either escape the caret or
-else don’t list it first.
-</p>
-<p>In inverted bracketed character classes, Perl ignores the Unicode rules
-that normally say that named sequence, and certain characters should
-match a sequence of multiple characters use under caseless <code>/i</code>
-matching. Following those rules could lead to highly confusing
-situations:
-</p>
-<pre class="verbatim"> "ss" =~ /^[^\xDF]+$/ui; # Matches!
-</pre>
-<p>This should match any sequences of characters that aren’t
<code>\xDF</code> nor
-what <code>\xDF</code> matches under <code>/i</code>.
<code>"s"</code> isn’t <code>\xDF</code>, but Unicode
-says that <code>"ss"</code> is what <code>\xDF</code> matches under
<code>/i</code>. So which one
-"wins"? Do you fail the match because the string has <code>ss</code>
or accept it
-because it has an <code>s</code> followed by another <code>s</code>? Perl has
chosen the
-latter. (See note in <a
href="#perlrecharclass-Bracketed-Character-Classes">Bracketed Character
Classes</a> above.)
-</p>
-<p>Examples:
-</p>
-<pre class="verbatim"> "e" =~ /[^aeiou]/ # No match, the 'e' is
listed.
- "x" =~ /[^aeiou]/ # Match, as 'x' isn't a lowercase vowel.
- "^" =~ /[^^]/ # No match, matches anything that isn't a
caret.
- "^" =~ /[x^]/ # Match, caret is not special here.
-</pre>
-<hr>
-<a name="perlrecharclass-Backslash-Sequences"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-POSIX-Character-Classes" accesskey="n"
rel="next">perlrecharclass POSIX Character Classes</a>, Previous: <a
href="#perlrecharclass-Negation" accesskey="p" rel="prev">perlrecharclass
Negation</a>, Up: <a href="#perlrecharclass-Bracketed-Character-Classes"
accesskey="u" rel="up">perlrecharclass Bracketed Character Classes</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Backslash-Sequences"></a>
-<h4 class="subsubsection">61.2.3.4 Backslash Sequences</h4>
-
-<p>You can put any backslash sequence character class (with the exception of
-<code>\N</code> and <code>\R</code>) 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, <code>[a-f\d]</code> matches any decimal digit,
or any
-of the lowercase letters between ’a’ and ’f’ inclusive.
-</p>
-<p><code>\N</code> within a bracketed character class must be of the forms
<code>\N{<em>name</em>}</code>
-or <code>\N{U+<em>hex char</em>}</code>, and NOT be the form that matches
non-newlines,
-for the same reason that a dot <code>.</code> inside a bracketed character
class loses
-its special meaning: it matches nearly anything, which generally isn’t
what you
-want to happen.
-</p>
-<p>Examples:
-</p>
-<pre class="verbatim"> /[\p{Thai}\d]/ # Matches a character that is either
a Thai
- # character, or a digit.
- /[^\p{Arabic}()]/ # Matches a character that is neither an Arabic
- # character, nor a parenthesis.
-</pre>
-<p>Backslash sequence character classes cannot form one of the endpoints
-of a range. Thus, you can’t say:
-</p>
-<pre class="verbatim"> /[\p{Thai}-\d]/ # Wrong!
-</pre>
-<hr>
-<a name="perlrecharclass-POSIX-Character-Classes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-Negation-of-POSIX-character-classes"
accesskey="n" rel="next">perlrecharclass Negation of POSIX character
classes</a>, Previous: <a href="#perlrecharclass-Backslash-Sequences"
accesskey="p" rel="prev">perlrecharclass Backslash Sequences</a>, Up: <a
href="#perlrecharclass-Bracketed-Character-Classes" accesskey="u"
rel="up">perlrecharclass Bracketed Character Classes</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="POSIX-Character-Classes"></a>
-<h4 class="subsubsection">61.2.3.5 POSIX Character Classes</h4>
-
-<p>POSIX character classes have the form <code>[:class:]</code>, where
<em>class</em> is the
-name, and the <code>[:</code> and <code>:]</code> delimiters. POSIX character
classes only appear
-<em>inside</em> bracketed character classes, and are a convenient and
descriptive
-way of listing a group of characters.
-</p>
-<p>Be careful about the syntax,
-</p>
-<pre class="verbatim"> # Correct:
- $string =~ /[[:alpha:]]/
-
- # Incorrect (will warn):
- $string =~ /[:alpha:]/
-</pre>
-<p>The latter pattern would be a character class consisting of a colon,
-and the letters <code>a</code>, <code>l</code>, <code>p</code> and
<code>h</code>.
-</p>
-<p>POSIX character classes can be part of a larger bracketed character class.
-For example,
-</p>
-<pre class="verbatim"> [01[:alpha:]%]
-</pre>
-<p>is valid and matches ’0’, ’1’, any alphabetic
character, and the percent sign.
-</p>
-<p>Perl recognizes the following POSIX character classes:
-</p>
-<pre class="verbatim"> alpha Any alphabetical character
("[A-Za-z]").
- 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.
- digit Any decimal digit ("[0-9]"), equivalent to "\d".
- graph Any printable character, excluding a space. See Note [3] below.
- lower Any lowercase character ("[a-z]").
- print Any printable character, including a space. See Note [4] below.
- punct Any graphical character excluding "word" characters. Note
[5].
- space Any whitespace character. "\s" including the vertical tab
- ("\cK").
- upper Any uppercase character ("[A-Z]").
- word A Perl extension ("[A-Za-z0-9_]"), equivalent to
"\w".
- xdigit Any hexadecimal digit ("[0-9a-fA-F]").
-</pre>
-<p>Like the <a href="#perlrecharclass-Unicode-Properties">Unicode
properties</a>, most of the POSIX
-properties match the same regardless of whether case-insensitive
(<code>/i</code>)
-matching is in effect or not. The two exceptions are <code>[:upper:]</code>
and
-<code>[:lower:]</code>. Under <code>/i</code>, they each match the union of
<code>[:upper:]</code> and
-<code>[:lower:]</code>.
-</p>
-<p>Most POSIX character classes have two Unicode-style <code>\p</code> property
-counterparts. (They are not official Unicode properties, but Perl extensions
-derived from official Unicode properties.) The table below shows the relation
-between POSIX character classes and these counterparts.
-</p>
-<p>One counterpart, in the column labelled "ASCII-range Unicode" in
-the table, matches only characters in the ASCII character set.
-</p>
-<p>The other counterpart, in the column labelled "Full-range
Unicode", matches any
-appropriate characters in the full Unicode character set. For example,
-<code>\p{Alpha}</code> matches not just the ASCII alphabetic characters, but
any
-character in the entire Unicode character set considered alphabetic.
-An entry in the column labelled "backslash sequence" is a (short)
-equivalent.
-</p>
-<pre class="verbatim"> [[:...:]] ASCII-range Full-range
backslash Note
- Unicode Unicode sequence
- -----------------------------------------------------
- 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}
-</pre>
-<dl compact="compact">
-<dt>[1]</dt>
-<dd><a name="perlrecharclass-_005b1_005d-1"></a>
-<p><code>\p{Blank}</code> and <code>\p{HorizSpace}</code> are synonyms.
-</p>
-</dd>
-<dt>[2]</dt>
-<dd><a name="perlrecharclass-_005b2_005d-1"></a>
-<p>Control characters don’t produce output as such, but instead usually
control
-the terminal somehow: for example, newline and backspace are control
characters.
-On ASCII platforms, in the ASCII range, characters whose code points are
-between 0 and 31 inclusive, plus 127 (<code>DEL</code>) are control
characters; on
-EBCDIC platforms, their counterparts are control characters.
-</p>
-</dd>
-<dt>[3]</dt>
-<dd><a name="perlrecharclass-_005b3_005d"></a>
-<p>Any character that is <em>graphical</em>, that is, visible. This class
consists
-of all alphanumeric characters and all punctuation characters.
-</p>
-</dd>
-<dt>[4]</dt>
-<dd><a name="perlrecharclass-_005b4_005d"></a>
-<p>All printable characters, which is the set of all graphical characters
-plus those whitespace characters which are not also controls.
-</p>
-</dd>
-<dt>[5]</dt>
-<dd><a name="perlrecharclass-_005b5_005d"></a>
-<p><code>\p{PosixPunct}</code> and <code>[[:punct:]]</code> in the ASCII range
match all
-non-controls, non-alphanumeric, non-space characters:
-<code>[-!"#$%&'()*+,./:;<=>address@hidden|}~]</code> (although
if a locale is in effect,
-it could alter the behavior of <code>[[:punct:]]</code>).
-</p>
-<p>The similarly named property, <code>\p{Punct}</code>, matches a somewhat
different
-set in the ASCII range, namely
-<code>[-!"#%&'()*,./:;address@hidden</code>. That is, it is missing
the nine
-characters <code>[$+<=>^`|~]</code>.
-This is because Unicode splits what POSIX considers to be punctuation into two
-categories, Punctuation and Symbols.
-</p>
-<p><code>\p{XPosixPunct}</code> and (under Unicode rules)
<code>[[:punct:]]</code>, match what
-<code>\p{PosixPunct}</code> matches in the ASCII range, plus what
<code>\p{Punct}</code>
-matches. This is different than strictly matching according to
-<code>\p{Punct}</code>. Another way to say it is that
-if Unicode rules are in effect, <code>[[:punct:]]</code> matches all characters
-that Unicode considers punctuation, plus all ASCII-range characters that
-Unicode considers symbols.
-</p>
-</dd>
-<dt>[6]</dt>
-<dd><a name="perlrecharclass-_005b6_005d"></a>
-<p><code>\p{XPerlSpace}</code> and <code>\p{Space}</code> match identically
starting with Perl
-v5.18. In earlier versions, these differ only in that in non-locale
-matching, <code>\p{XPerlSpace}</code> did not match the vertical tab,
<code>\cK</code>.
-Same for the two ASCII-only range forms.
-</p>
-</dd>
-</dl>
-
-<p>There are various other synonyms that can be used besides the names
-listed in the table. For example, <code>\p{PosixAlpha}</code> can be written
as
-<code>\p{Alpha}</code>. All are listed in
-<a
href="perluniprops.html#Properties-accessible-through-_005cp_007b_007d-and-_005cP_007b_007d">(perluniprops)Properties
accessible through \p{} and \P{}</a>.
-</p>
-<p>Both the <code>\p</code> 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:
-</p>
-<dl compact="compact">
-<dt>If the <code>/a</code> modifier, is in effect ...</dt>
-<dd><a
name="perlrecharclass-If-the-_002fa-modifier_002c-is-in-effect-_002e_002e_002e"></a>
-<p>Each of the POSIX classes matches exactly the same as their ASCII-range
-counterparts.
-</p>
-</dd>
-<dt>otherwise ...</dt>
-<dd><a name="perlrecharclass-otherwise-_002e_002e_002e-4"></a>
-<dl compact="compact">
-<dt>For code points above 255 ...</dt>
-<dd><a name="perlrecharclass-For-code-points-above-255-_002e_002e_002e-2"></a>
-<p>The POSIX class matches the same as its Full-range counterpart.
-</p>
-</dd>
-<dt>For code points below 256 ...</dt>
-<dd><a name="perlrecharclass-For-code-points-below-256-_002e_002e_002e-2"></a>
-<dl compact="compact">
-<dt>if locale rules are in effect ...</dt>
-<dd><a
name="perlrecharclass-if-locale-rules-are-in-effect-_002e_002e_002e-2"></a>
-<p>The POSIX class matches according to the locale, except:
-</p>
-<dl compact="compact">
-<dt><code>word</code></dt>
-<dd><a name="perlrecharclass-word"></a>
-<p>also includes the platform’s native underscore character, no matter
what
-the locale is.
-</p>
-</dd>
-<dt><code>ascii</code></dt>
-<dd><a name="perlrecharclass-ascii"></a>
-<p>on platforms that don’t have the POSIX <code>ascii</code> extension,
this matches
-just the platform’s native ASCII-range characters.
-</p>
-</dd>
-<dt><code>blank</code></dt>
-<dd><a name="perlrecharclass-blank"></a>
-<p>on platforms that don’t have the POSIX <code>blank</code> extension,
this matches
-just the platform’s native tab and space characters.
-</p>
-</dd>
-</dl>
-
-</dd>
-<dt>if Unicode rules are in effect ...</dt>
-<dd><a
name="perlrecharclass-if-Unicode-rules-are-in-effect-_002e_002e_002e-2"></a>
-<p>The POSIX class matches the same as the Full-range counterpart.
-</p>
-</dd>
-<dt>otherwise ...</dt>
-<dd><a name="perlrecharclass-otherwise-_002e_002e_002e-5"></a>
-<p>The POSIX class matches the same as the ASCII range counterpart.
-</p>
-</dd>
-</dl>
-
-</dd>
-</dl>
-
-</dd>
-</dl>
-
-<p>Which rules apply are determined as described in
-<a href="#perlre-Which-character-set-modifier-is-in-effect_003f">perlre Which
character set modifier is in effect?</a>.
-</p>
-<p>It is proposed to change this behavior in a future release of Perl so that
-whether or not Unicode rules are in effect would not change the
-behavior: Outside of locale, the POSIX classes
-would behave like their ASCII-range counterparts. If you wish to
-comment on this proposal, send email to <code>address@hidden</code>.
-</p>
-<hr>
-<a name="perlrecharclass-Negation-of-POSIX-character-classes"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlrecharclass-_005b_003d-_003d_005d-and-_005b_002e-_002e_005d"
accesskey="n" rel="next">perlrecharclass [= =] and [. .]</a>, Previous: <a
href="#perlrecharclass-POSIX-Character-Classes" accesskey="p"
rel="prev">perlrecharclass POSIX Character Classes</a>, Up: <a
href="#perlrecharclass-Bracketed-Character-Classes" accesskey="u"
rel="up">perlrecharclass Bracketed Character Classes</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Negation-of-POSIX-character-classes"></a>
-<h4 class="subsubsection">61.2.3.6 Negation of POSIX character classes</h4>
-
-<p>A Perl extension to the POSIX character class is the ability to
-negate it. This is done by prefixing the class name with a caret
(<code>^</code>).
-Some examples:
-</p>
-<pre class="verbatim"> POSIX ASCII-range Full-range backslash
- Unicode Unicode sequence
- -----------------------------------------------------
- [[:^digit:]] \P{PosixDigit} \P{XPosixDigit} \D
- [[:^space:]] \P{PosixSpace} \P{XPosixSpace}
- \P{PerlSpace} \P{XPerlSpace} \S
- [[:^word:]] \P{PerlWord} \P{XPosixWord} \W
-</pre>
-<p>The backslash sequence can mean either ASCII- or Full-range Unicode,
-depending on various factors as described in <a
href="#perlre-Which-character-set-modifier-is-in-effect_003f">perlre Which
character set modifier is in effect?</a>.
-</p>
-<hr>
-<a name="perlrecharclass-_005b_003d-_003d_005d-and-_005b_002e-_002e_005d"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-Examples-1" accesskey="n"
rel="next">perlrecharclass Examples 1</a>, Previous: <a
href="#perlrecharclass-Negation-of-POSIX-character-classes" accesskey="p"
rel="prev">perlrecharclass Negation of POSIX character classes</a>, Up: <a
href="#perlrecharclass-Bracketed-Character-Classes" accesskey="u"
rel="up">perlrecharclass Bracketed Character Classes</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="g_t_005b_003d-_003d_005d-and-_005b_002e-_002e_005d"></a>
-<h4 class="subsubsection">61.2.3.7 [= =] and [. .]</h4>
-
-<p>Perl recognizes the POSIX character classes <code>[=class=]</code> and
-<code>[.class.]</code>, but does not (yet?) support them. Any attempt to use
-either construct raises an exception.
-</p>
-<hr>
-<a name="perlrecharclass-Examples-1"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrecharclass-Extended-Bracketed-Character-Classes"
accesskey="n" rel="next">perlrecharclass Extended Bracketed Character
Classes</a>, Previous: <a
href="#perlrecharclass-_005b_003d-_003d_005d-and-_005b_002e-_002e_005d"
accesskey="p" rel="prev">perlrecharclass [= =] and [. .]</a>, Up: <a
href="#perlrecharclass-Bracketed-Character-Classes" accesskey="u"
rel="up">perlrecharclass Bracketed Character Classes</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Examples-9"></a>
-<h4 class="subsubsection">61.2.3.8 Examples</h4>
-
-<pre class="verbatim"> /[[:digit:]]/ # Matches a character that is
a digit.
- /[01[:lower:]]/ # Matches a character that is either a
- # lowercase letter, or '0' or '1'.
- /[[:digit:][:^xdigit:]]/ # Matches a character that can be anything
- # except the letters 'a' to 'f' and 'A' to
- # 'F'. This is because the main character
- # class is composed of two POSIX character
- # classes that are ORed together, one that
- # matches any digit, and the other that
- # matches anything that isn't a hex digit.
- # The OR adds the digits, leaving only the
- # letters 'a' to 'f' and 'A' to 'F' excluded.
-</pre>
-<hr>
-<a name="perlrecharclass-Extended-Bracketed-Character-Classes"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlrecharclass-Examples-1" accesskey="p"
rel="prev">perlrecharclass Examples 1</a>, Up: <a
href="#perlrecharclass-Bracketed-Character-Classes" accesskey="u"
rel="up">perlrecharclass Bracketed Character Classes</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Extended-Bracketed-Character-Classes"></a>
-<h4 class="subsubsection">61.2.3.9 Extended Bracketed Character Classes</h4>
-
-<p>This is a fancy bracketed character class that can be used for more
-readable and less error-prone classes, and to perform set operations,
-such as intersection. An example is
-</p>
-<pre class="verbatim"> /(?[ \p{Thai} & \p{Digit} ])/
-</pre>
-<p>This will match all the digit characters that are in the Thai script.
-</p>
-<p>This is an experimental feature available starting in 5.18, and is
-subject to change as we gain field experience with it. Any attempt to
-use it will raise a warning, unless disabled via
-</p>
-<pre class="verbatim"> no warnings "experimental::regex_sets";
-</pre>
-<p>Comments on this feature are welcome; send email to
-<code>address@hidden</code>.
-</p>
-<p>We can extend the example above:
-</p>
-<pre class="verbatim"> /(?[ ( \p{Thai} + \p{Lao} ) & \p{Digit} ])/
-</pre>
-<p>This matches digits that are in either the Thai or Laotian scripts.
-</p>
-<p>Notice the white space in these examples. This construct always has
-the <code>/x</code> modifier turned on within it.
-</p>
-<p>The available binary operators are:
-</p>
-<pre class="verbatim"> & intersection
- + union
- | another name for '+', hence means union
- - subtraction (the result matches the set consisting of those
- code points matched by the first operand, excluding any that
- are also matched by the second operand)
- ^ symmetric difference (the union minus the intersection). This
- is like an exclusive or, in that the result is the set of code
- points that are matched by either, but not both, of the
- operands.
-</pre>
-<p>There is one unary operator:
-</p>
-<pre class="verbatim"> ! complement
-</pre>
-<p>All the binary operators left associate; <code>"&"</code> is
higher precedence
-than the others, which all have equal precedence. The unary operator
-right associates, and has highest precedence. Thus this follows the
-normal Perl precedence rules for logical operators. Use parentheses to
-override the default precedence and associativity.
-</p>
-<p>The main restriction is that everything is a metacharacter. Thus,
-you cannot refer to single characters by doing something like this:
-</p>
-<pre class="verbatim"> /(?[ a + b ])/ # Syntax error!
-</pre>
-<p>The easiest way to specify an individual typable character is to enclose
-it in brackets:
-</p>
-<pre class="verbatim"> /(?[ [a] + [b] ])/
-</pre>
-<p>(This is the same thing as <code>[ab]</code>.) You could also have said the
-equivalent:
-</p>
-<pre class="verbatim"> /(?[[ a b ]])/
-</pre>
-<p>(You can, of course, specify single characters by using,
<code>\x{...}</code>,
-<code>\N{...}</code>, etc.)
-</p>
-<p>This last example shows the use of this construct to specify an ordinary
-bracketed character class without additional set operations. Note the
-white space within it; <code>/x</code> is turned on even within bracketed
-character classes, except you can’t have comments inside them. Hence,
-</p>
-<pre class="verbatim"> (?[ [#] ])
-</pre>
-<p>matches the literal character "#". To specify a literal white
space character,
-you can escape it with a backslash, like:
-</p>
-<pre class="verbatim"> /(?[ [ a e i o u \ ] ])/
-</pre>
-<p>This matches the English vowels plus the SPACE character.
-All the other escapes accepted by normal bracketed character classes are
-accepted here as well; but unrecognized escapes that generate warnings
-in normal classes are fatal errors here.
-</p>
-<p>All warnings from these class elements are fatal, as well as some
-practices that don’t currently warn. For example you cannot say
-</p>
-<pre class="verbatim"> /(?[ [ \xF ] ])/ # Syntax error!
-</pre>
-<p>You have to have two hex digits after a braceless <code>\x</code> (use a
leading
-zero to make two). These restrictions are to lower the incidence of
-typos causing the class to not match what you thought it would.
-</p>
-<p>If a regular bracketed character class contains a <code>\p{}</code> or
<code>\P{}</code> and
-is matched against a non-Unicode code point, a warning may be
-raised, as the result is not Unicode-defined. No such warning will come
-when using this extended form.
-</p>
-<p>The final difference between regular bracketed character classes and
-these, is that it is not possible to get these to match a
-multi-character fold. Thus,
-</p>
-<pre class="verbatim"> /(?[ [\xDF] ])/iu
-</pre>
-<p>does not match the string <code>ss</code>.
-</p>
-<p>You don’t have to enclose POSIX class names inside double brackets,
-hence both of the following work:
-</p>
-<pre class="verbatim"> /(?[ [:word:] - [:lower:] ])/
- /(?[ [[:word:]] - [[:lower:]] ])/
-</pre>
-<p>Any contained POSIX character classes, including things like
<code>\w</code> and <code>\D</code>
-respect the <code>/a</code> (and <code>/aa</code>) modifiers.
-</p>
-<p><code>(?[ ])</code> is a regex-compile-time construct. Any attempt to use
-something which isn’t knowable at the time the containing regular
-expression is compiled is a fatal error. In practice, this means
-just three limitations:
-</p>
-<ol>
-<li> This construct cannot be used within the scope of
-<code>use locale</code> (or the <code>/l</code> regex modifier).
-
-</li><li> Any
-<a href="#perlunicode-User_002dDefined-Character-Properties">user-defined
property</a>
-used must be already defined by the time the regular expression is
-compiled (but note that this construct can be used instead of such
-properties).
-
-</li><li> A regular expression that otherwise would compile
-using <code>/d</code> rules, and which uses this construct will instead
-use <code>/u</code>. Thus this construct tells Perl that you don’t want
-<code>/d</code> rules for the entire regular expression containing it.
-
-</li></ol>
-
-<p>Note that skipping white space applies only to the interior of this
-construct. There must not be any space between any of the characters
-that form the initial <code>(?[</code>. Nor may there be space between the
-closing <code>])</code> characters.
-</p>
-<p>Just as in all regular expressions, the pattern can be built up by
-including variables that are interpolated at regex compilation time.
-Care must be taken to ensure that you are getting what you expect. For
-example:
-</p>
-<pre class="verbatim"> my $thai_or_lao = '\p{Thai} + \p{Lao}';
- ...
- qr/(?[ \p{Digit} & $thai_or_lao ])/;
-</pre>
-<p>compiles to
-</p>
-<pre class="verbatim"> qr/(?[ \p{Digit} & \p{Thai} + \p{Lao} ])/;
-</pre>
-<p>But this does not have the effect that someone reading the code would
-likely expect, as the intersection applies just to <code>\p{Thai}</code>,
-excluding the Laotian. Pitfalls like this can be avoided by
-parenthesizing the component pieces:
-</p>
-<pre class="verbatim"> my $thai_or_lao = '( \p{Thai} + \p{Lao} )';
-</pre>
-<p>But any modifiers will still apply to all the components:
-</p>
-<pre class="verbatim"> my $lower = '\p{Lower} + \p{Digit}';
- qr/(?[ \p{Greek} & $lower ])/i;
-</pre>
-<p>matches upper case things. You can avoid surprises by making the
-components into instances of this construct by compiling them:
-</p>
-<pre class="verbatim"> my $thai_or_lao = qr/(?[ \p{Thai} + \p{Lao} ])/;
- my $lower = qr/(?[ \p{Lower} + \p{Digit} ])/;
-</pre>
-<p>When these are embedded in another pattern, what they match does not
-change, regardless of parenthesization or what modifiers are in effect
-in that outer pattern.
-</p>
-<p>Due to the way that Perl parses things, your parentheses and brackets
-may need to be balanced, even including comments. If you run into any
-examples, please send them to <code>address@hidden</code>, so that we can have
a
-concrete example for this man page.
-</p>
-<p>We may change it so that things that remain legal uses in normal bracketed
-character classes might become illegal within this experimental
-construct. One proposal, for example, is to forbid adjacent uses of the
-same character, as in <code>(?[ [aa] ])</code>. The motivation for such a
change
-is that this usage is likely a typo, as the second "a" adds nothing.
-</p>
-<hr>
-<a name="perlref"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreftut" accesskey="n" rel="next">perlreftut</a>, Previous:
<a href="#perlrecharclass" accesskey="p" rel="prev">perlrecharclass</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlref-1"></a>
-<h2 class="chapter">62 perlref</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlref-NAME"
accesskey="1">perlref NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlref-NOTE"
accesskey="2">perlref NOTE</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlref-DESCRIPTION"
accesskey="3">perlref DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlref-WARNING"
accesskey="4">perlref WARNING</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-Postfix-Dereference-Syntax" accesskey="5">perlref Postfix
Dereference Syntax</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-Assigning-to-References" accesskey="6">perlref Assigning to
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlref-SEE-ALSO"
accesskey="7">perlref SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlref-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlref-NOTE" accesskey="n" rel="next">perlref NOTE</a>, Up:
<a href="#perlref" accesskey="u" rel="up">perlref</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-61"></a>
-<h3 class="section">62.1 NAME</h3>
-
-<p>perlref - Perl references and nested data structures
-</p>
-<hr>
-<a name="perlref-NOTE"></a>
-<div class="header">
-<p>
-Next: <a href="#perlref-DESCRIPTION" accesskey="n" rel="next">perlref
DESCRIPTION</a>, Previous: <a href="#perlref-NAME" accesskey="p"
rel="prev">perlref NAME</a>, Up: <a href="#perlref" accesskey="u"
rel="up">perlref</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NOTE"></a>
-<h3 class="section">62.2 NOTE</h3>
-
-<p>This is complete documentation about all aspects of references.
-For a shorter, tutorial introduction to just the essential features,
-see <a href="#perlreftut-NAME">perlreftut NAME</a>.
-</p>
-<hr>
-<a name="perlref-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlref-WARNING" accesskey="n" rel="next">perlref WARNING</a>,
Previous: <a href="#perlref-NOTE" accesskey="p" rel="prev">perlref NOTE</a>,
Up: <a href="#perlref" accesskey="u" rel="up">perlref</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-60"></a>
-<h3 class="section">62.3 DESCRIPTION</h3>
-
-<p>Before release 5 of Perl it was difficult to represent complex data
-structures, because all references had to be symbolic–and even then
-it was difficult to refer to a variable instead of a symbol table entry.
-Perl now not only makes it easier to use symbolic references to variables,
-but also lets you have "hard" references to any piece of data or
code.
-Any scalar may hold a hard reference. Because arrays and hashes contain
-scalars, you can now easily build arrays of arrays, arrays of hashes,
-hashes of arrays, arrays of hashes of functions, and so on.
-</p>
-<p>Hard references are smart–they keep track of reference counts for you,
-automatically freeing the thing referred to when its reference count goes
-to zero. (Reference counts for values in self-referential or
-cyclic data structures may not go to zero without a little help; see
-<a href="#perlref-Circular-References">Circular References</a> for a detailed
explanation.)
-If that thing happens to be an object, the object is destructed. See
-<a href="#perlobj-NAME">perlobj NAME</a> for more about objects. (In a sense,
everything in Perl is an
-object, but we usually reserve the word for references to objects that
-have been officially "blessed" into a class package.)
-</p>
-<p>Symbolic references are names of variables or other objects, just as a
-symbolic link in a Unix filesystem contains merely the name of a file.
-The <code>*glob</code> notation is something of a symbolic reference.
(Symbolic
-references are sometimes called "soft references", but please
don’t call
-them that; references are confusing enough without useless synonyms.)
-</p>
-<p>In contrast, hard references are more like hard links in a Unix file
-system: They are used to access an underlying object without concern for
-what its (other) name is. When the word "reference" is used without
an
-adjective, as in the following paragraph, it is usually talking about a
-hard reference.
-</p>
-<p>References are easy to use in Perl. There is just one overriding
-principle: in general, Perl does no implicit referencing or dereferencing.
-When a scalar is holding a reference, it always behaves as a simple scalar.
-It doesn’t magically start being an array or hash or subroutine; you
have to
-tell it explicitly to do so, by dereferencing it.
-</p>
-<p>That said, be aware that Perl version 5.14 introduces an exception
-to the rule, for syntactic convenience. Experimental array and hash container
-function behavior allows array and hash references to be handled by Perl as
-if they had been explicitly syntactically dereferenced. See
-<a
href="perl5140delta.html#Syntactical-Enhancements">(perl5140delta)Syntactical
Enhancements</a>
-and <a href="#perlfunc-NAME">perlfunc NAME</a> for details.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlref-Making-References"
accesskey="1">perlref Making References</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlref-Using-References"
accesskey="2">perlref Using References</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-Circular-References" accesskey="3">perlref Circular
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-Symbolic-references" accesskey="4">perlref Symbolic
references</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-Not_002dso_002dsymbolic-references" accesskey="5">perlref
Not-so-symbolic references</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlref-Pseudo_002dhashes_003a-Using-an-array-as-a-hash"
accesskey="6">perlref Pseudo-hashes: Using an array as a
hash</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlref-Function-Templates"
accesskey="7">perlref Function Templates</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlref-Making-References"></a>
-<div class="header">
-<p>
-Next: <a href="#perlref-Using-References" accesskey="n" rel="next">perlref
Using References</a>, Up: <a href="#perlref-DESCRIPTION" accesskey="u"
rel="up">perlref DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Making-References"></a>
-<h4 class="subsection">62.3.1 Making References</h4>
-
-<p>References can be created in several ways.
-</p>
-<ol>
-<li> By using the backslash operator on a variable, subroutine, or value.
-(This works much like the & (address-of) operator in C.)
-This typically creates <em>another</em> reference to a variable, because
-there’s already a reference to the variable in the symbol table. But
-the symbol table reference might go away, and you’ll still have the
-reference that the backslash returned. Here are some examples:
-
-<pre class="verbatim"> $scalarref = \$foo;
- $arrayref = address@hidden;
- $hashref = \%ENV;
- $coderef = \&handler;
- $globref = \*foo;
-</pre>
-<p>It isn’t possible to create a true reference to an IO handle
(filehandle
-or dirhandle) using the backslash operator. The most you can get is a
-reference to a typeglob, which is actually a complete symbol table entry.
-But see the explanation of the <code>*foo{THING}</code> syntax below. However,
-you can still use type globs and globrefs as though they were IO handles.
-</p>
-</li><li> A reference to an anonymous array can be created using square
-brackets:
-
-<pre class="verbatim"> $arrayref = [1, 2, ['a', 'b', 'c']];
-</pre>
-<p>Here we’ve created a reference to an anonymous array of three elements
-whose final element is itself a reference to another anonymous array of three
-elements. (The multidimensional syntax described later can be used to
-access this. For example, after the above, <code>$arrayref->[2][1]</code>
would have
-the value "b".)
-</p>
-<p>Taking a reference to an enumerated list is not the same
-as using square brackets–instead it’s the same as creating
-a list of references!
-</p>
-<pre class="verbatim"> @list = (\$a, address@hidden, \%c);
- @list = \($a, @b, %c); # same thing!
-</pre>
-<p>As a special case, <code>\(@foo)</code> returns a list of references to the
contents
-of <code>@foo</code>, not a reference to <code>@foo</code> itself. Likewise
for <code>%foo</code>,
-except that the key references are to copies (since the keys are just
-strings rather than full-fledged scalars).
-</p>
-</li><li> A reference to an anonymous hash can be created using curly
-brackets:
-
-<pre class="verbatim"> $hashref = {
- 'Adam' => 'Eve',
- 'Clyde' => 'Bonnie',
- };
-</pre>
-<p>Anonymous hash and array composers like these can be intermixed freely to
-produce as complicated a structure as you want. The multidimensional
-syntax described below works for these too. The values above are
-literals, but variables and expressions would work just as well, because
-assignment operators in Perl (even within local() or my()) are executable
-statements, not compile-time declarations.
-</p>
-<p>Because curly brackets (braces) are used for several other things
-including BLOCKs, you may occasionally have to disambiguate braces at the
-beginning of a statement by putting a <code>+</code> or a <code>return</code>
in front so
-that Perl realizes the opening brace isn’t starting a BLOCK. The
economy and
-mnemonic value of using curlies is deemed worth this occasional extra
-hassle.
-</p>
-<p>For example, if you wanted a function to make a new hash and return a
-reference to it, you have these options:
-</p>
-<pre class="verbatim"> sub hashem { { @_ } } # silently wrong
- sub hashem { +{ @_ } } # ok
- sub hashem { return { @_ } } # ok
-</pre>
-<p>On the other hand, if you want the other meaning, you can do this:
-</p>
-<pre class="verbatim"> sub showem { { @_ } } # ambiguous
(currently ok,
- # but may change)
- sub showem { {; @_ } } # ok
- sub showem { { return @_ } } # ok
-</pre>
-<p>The leading <code>+{</code> and <code>{;</code> always serve to disambiguate
-the expression to mean either the HASH reference, or the BLOCK.
-</p>
-</li><li> A reference to an anonymous subroutine can be created by using
-<code>sub</code> without a subname:
-
-<pre class="verbatim"> $coderef = sub { print "Boink!\n" };
-</pre>
-<p>Note the semicolon. Except for the code
-inside not being immediately executed, a <code>sub {}</code> is not so much a
-declaration as it is an operator, like <code>do{}</code> or
<code>eval{}</code>. (However, no
-matter how many times you execute that particular line (unless you’re in
an
-<code>eval("...")</code>), $coderef will still have a reference to
the <em>same</em>
-anonymous subroutine.)
-</p>
-<p>Anonymous subroutines act as closures with respect to my() variables,
-that is, variables lexically visible within the current scope. Closure
-is a notion out of the Lisp world that says if you define an anonymous
-function in a particular lexical context, it pretends to run in that
-context even when it’s called outside the context.
-</p>
-<p>In human terms, it’s a funny way of passing arguments to a subroutine
when
-you define it as well as when you call it. It’s useful for setting up
-little bits of code to run later, such as callbacks. You can even
-do object-oriented stuff with it, though Perl already provides a different
-mechanism to do that–see <a href="#perlobj-NAME">perlobj NAME</a>.
-</p>
-<p>You might also think of closure as a way to write a subroutine
-template without using eval(). Here’s a small example of how
-closures work:
-</p>
-<pre class="verbatim"> sub newprint {
- my $x = shift;
- return sub { my $y = shift; print "$x, $y!\n"; };
- }
- $h = newprint("Howdy");
- $g = newprint("Greetings");
-
- # Time passes...
-
- &$h("world");
- &$g("earthlings");
-</pre>
-<p>This prints
-</p>
-<pre class="verbatim"> Howdy, world!
- Greetings, earthlings!
-</pre>
-<p>Note particularly that $x continues to refer to the value passed
-into newprint() <em>despite</em> "my $x" having gone out of scope by
the
-time the anonymous subroutine runs. That’s what a closure is all
-about.
-</p>
-<p>This applies only to lexical variables, by the way. Dynamic variables
-continue to work as they have always worked. Closure is not something
-that most Perl programmers need trouble themselves about to begin with.
-</p>
-</li><li> References are often returned by special subroutines called
constructors. Perl
-objects are just references to a special type of object that happens to know
-which package it’s associated with. Constructors are just special
subroutines
-that know how to create that association. They do so by starting with an
-ordinary reference, and it remains an ordinary reference even while it’s
also
-being an object. Constructors are often named <code>new()</code>. You
<em>can</em> call them
-indirectly:
-
-<pre class="verbatim"> $objref = new Doggie( Tail => 'short', Ears =>
'long' );
-</pre>
-<p>But that can produce ambiguous syntax in certain cases, so it’s often
-better to use the direct method invocation approach:
-</p>
-<pre class="verbatim"> $objref = Doggie->new(Tail => 'short', Ears
=> 'long');
-
- use Term::Cap;
- $terminal = Term::Cap->Tgetent( { OSPEED => 9600 });
-
- use Tk;
- $main = MainWindow->new();
- $menubar = $main->Frame(-relief => "raised",
- -borderwidth => 2)
-</pre>
-</li><li> References of the appropriate type can spring into existence if you
-dereference them in a context that assumes they exist. Because we
haven’t
-talked about dereferencing yet, we can’t show you any examples yet.
-
-</li><li> A reference can be created by using a special syntax, lovingly known
as
-the *foo{THING} syntax. *foo{THING} returns a reference to the THING
-slot in *foo (which is the symbol table entry which holds everything
-known as foo).
-
-<pre class="verbatim"> $scalarref = *foo{SCALAR};
- $arrayref = *ARGV{ARRAY};
- $hashref = *ENV{HASH};
- $coderef = *handler{CODE};
- $ioref = *STDIN{IO};
- $globref = *foo{GLOB};
- $formatref = *foo{FORMAT};
- $globname = *foo{NAME}; # "foo"
- $pkgname = *foo{PACKAGE}; # "main"
-</pre>
-<p>Most of these are self-explanatory, but <code>*foo{IO}</code>
-deserves special attention. It returns
-the IO handle, used for file handles (‘perlfunc open’), sockets
-(‘perlfunc socket’ and ‘perlfunc socketpair’), and
directory
-handles (‘perlfunc opendir’). For compatibility with previous
-versions of Perl, <code>*foo{FILEHANDLE}</code> is a synonym for
<code>*foo{IO}</code>, though it
-is deprecated as of 5.8.0. If deprecation warnings are in effect, it will warn
-of its use.
-</p>
-<p><code>*foo{THING}</code> returns undef if that particular THING
hasn’t been used yet,
-except in the case of scalars. <code>*foo{SCALAR}</code> returns a reference
to an
-anonymous scalar if $foo hasn’t been used yet. This might change in a
-future release.
-</p>
-<p><code>*foo{NAME}</code> and <code>*foo{PACKAGE}</code> are the exception,
in that they return
-strings, rather than references. These return the package and name of the
-typeglob itself, rather than one that has been assigned to it. So, after
-<code>*foo=*Foo::bar</code>, <code>*foo</code> will become
"*Foo::bar" when used as a string,
-but <code>*foo{PACKAGE}</code> and <code>*foo{NAME}</code> will continue to
produce "main" and
-"foo", respectively.
-</p>
-<p><code>*foo{IO}</code> is an alternative to the <code>*HANDLE</code>
mechanism given in
-<a href="#perldata-Typeglobs-and-Filehandles">perldata Typeglobs and
Filehandles</a> for passing filehandles
-into or out of subroutines, or storing into larger data structures.
-Its disadvantage is that it won’t create a new filehandle for you.
-Its advantage is that you have less risk of clobbering more than
-you want to with a typeglob assignment. (It still conflates file
-and directory handles, though.) However, if you assign the incoming
-value to a scalar instead of a typeglob as we do in the examples
-below, there’s no risk of that happening.
-</p>
-<pre class="verbatim"> splutter(*STDOUT); # pass the whole glob
- splutter(*STDOUT{IO}); # pass both file and dir handles
-
- sub splutter {
- my $fh = shift;
- print $fh "her um well a hmmm\n";
- }
-
- $rec = get_rec(*STDIN); # pass the whole glob
- $rec = get_rec(*STDIN{IO}); # pass both file and dir handles
-
- sub get_rec {
- my $fh = shift;
- return scalar <$fh>;
- }
-</pre>
-</li></ol>
-
-<hr>
-<a name="perlref-Using-References"></a>
-<div class="header">
-<p>
-Next: <a href="#perlref-Circular-References" accesskey="n" rel="next">perlref
Circular References</a>, Previous: <a href="#perlref-Making-References"
accesskey="p" rel="prev">perlref Making References</a>, Up: <a
href="#perlref-DESCRIPTION" accesskey="u" rel="up">perlref DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-References"></a>
-<h4 class="subsection">62.3.2 Using References</h4>
-
-<p>That’s it for creating references. By now you’re probably
dying to
-know how to use references to get back to your long-lost data. There
-are several basic methods.
-</p>
-<ol>
-<li> Anywhere you’d put an identifier (or chain of identifiers) as part
-of a variable or subroutine name, you can replace the identifier with
-a simple scalar variable containing a reference of the correct type:
-
-<pre class="verbatim"> $bar = $$scalarref;
- push(@$arrayref, $filename);
- $$arrayref[0] = "January";
- $$hashref{"KEY"} = "VALUE";
- &$coderef(1,2,3);
- print $globref "output\n";
-</pre>
-<p>It’s important to understand that we are specifically <em>not</em>
dereferencing
-<code>$arrayref[0]</code> or <code>$hashref{"KEY"}</code> there.
The dereference of the
-scalar variable happens <em>before</em> it does any key lookups. Anything more
-complicated than a simple scalar variable must use methods 2 or 3 below.
-However, a "simple scalar" includes an identifier that itself uses
method
-1 recursively. Therefore, the following prints "howdy".
-</p>
-<pre class="verbatim"> $refrefref = \\\"howdy";
- print $$$$refrefref;
-</pre>
-</li><li> Anywhere you’d put an identifier (or chain of identifiers) as
part of a
-variable or subroutine name, you can replace the identifier with a
-BLOCK returning a reference of the correct type. In other words, the
-previous examples could be written like this:
-
-<pre class="verbatim"> $bar = ${$scalarref};
- push(@{$arrayref}, $filename);
- ${$arrayref}[0] = "January";
- ${$hashref}{"KEY"} = "VALUE";
- &{$coderef}(1,2,3);
- $globref->print("output\n"); # iff IO::Handle is loaded
-</pre>
-<p>Admittedly, it’s a little silly to use the curlies in this case, but
-the BLOCK can contain any arbitrary expression, in particular,
-subscripted expressions:
-</p>
-<pre class="verbatim"> &{ $dispatch{$index} }(1,2,3); # call
correct routine
-</pre>
-<p>Because of being able to omit the curlies for the simple case of
<code>$$x</code>,
-people often make the mistake of viewing the dereferencing symbols as
-proper operators, and wonder about their precedence. If they were,
-though, you could use parentheses instead of braces. That’s not the
case.
-Consider the difference below; case 0 is a short-hand version of case 1,
-<em>not</em> case 2:
-</p>
-<pre class="verbatim"> $$hashref{"KEY"} = "VALUE";
# CASE 0
- ${$hashref}{"KEY"} = "VALUE"; # CASE 1
- ${$hashref{"KEY"}} = "VALUE"; # CASE 2
- ${$hashref->{"KEY"}} = "VALUE"; # CASE 3
-</pre>
-<p>Case 2 is also deceptive in that you’re accessing a variable
-called %hashref, not dereferencing through $hashref to the hash
-it’s presumably referencing. That would be case 3.
-</p>
-</li><li> Subroutine calls and lookups of individual array elements arise often
-enough that it gets cumbersome to use method 2. As a form of
-syntactic sugar, the examples for method 2 may be written:
-
-<pre class="verbatim"> $arrayref->[0] = "January"; # Array
element
- $hashref->{"KEY"} = "VALUE"; # Hash element
- $coderef->(1,2,3); # Subroutine call
-</pre>
-<p>The left side of the arrow can be any expression returning a reference,
-including a previous dereference. Note that <code>$array[$x]</code> is
<em>not</em> the
-same thing as <code>$array->[$x]</code> here:
-</p>
-<pre class="verbatim"> $array[$x]->{"foo"}->[0] =
"January";
-</pre>
-<p>This is one of the cases we mentioned earlier in which references could
-spring into existence when in an lvalue context. Before this
-statement, <code>$array[$x]</code> may have been undefined. If so, it’s
-automatically defined with a hash reference so that we can look up
-<code>{"foo"}</code> in it. Likewise
<code>$array[$x]->{"foo"}</code> will automatically get
-defined with an array reference so that we can look up <code>[0]</code> in it.
-This process is called <em>autovivification</em>.
-</p>
-<p>One more thing here. The arrow is optional <em>between</em> brackets
-subscripts, so you can shrink the above down to
-</p>
-<pre class="verbatim"> $array[$x]{"foo"}[0] = "January";
-</pre>
-<p>Which, in the degenerate case of using only ordinary arrays, gives you
-multidimensional arrays just like C’s:
-</p>
-<pre class="verbatim"> $score[$x][$y][$z] += 42;
-</pre>
-<p>Well, okay, not entirely like C’s arrays, actually. C doesn’t
know how
-to grow its arrays on demand. Perl does.
-</p>
-</li><li> If a reference happens to be a reference to an object, then there are
-probably methods to access the things referred to, and you should probably
-stick to those methods unless you’re in the class package that defines
the
-object’s methods. In other words, be nice, and don’t violate the
object’s
-encapsulation without a very good reason. Perl does not enforce
-encapsulation. We are not totalitarians here. We do expect some basic
-civility though.
-
-</li></ol>
-
-<p>Using a string or number as a reference produces a symbolic reference,
-as explained above. Using a reference as a number produces an
-integer representing its storage location in memory. The only
-useful thing to be done with this is to compare two references
-numerically to see whether they refer to the same location.
-</p>
-<pre class="verbatim"> if ($ref1 == $ref2) { # cheap numeric compare of
references
- print "refs 1 and 2 refer to the same thing\n";
- }
-</pre>
-<p>Using a reference as a string produces both its referent’s type,
-including any package blessing as described in <a href="#perlobj-NAME">perlobj
NAME</a>, as well
-as the numeric address expressed in hex. The ref() operator returns
-just the type of thing the reference is pointing to, without the
-address. See <a href="#perlfunc-ref">perlfunc ref</a> for details and
examples of its use.
-</p>
-<p>The bless() operator may be used to associate the object a reference
-points to with a package functioning as an object class. See <a
href="#perlobj-NAME">perlobj NAME</a>.
-</p>
-<p>A typeglob may be dereferenced the same way a reference can, because
-the dereference syntax always indicates the type of reference desired.
-So <code>${*foo}</code> and <code>${\$foo}</code> both indicate the same
scalar variable.
-</p>
-<p>Here’s a trick for interpolating a subroutine call into a string:
-</p>
-<pre class="verbatim"> print "My sub returned @{[mysub(1,2,3)]} that
time.\n";
-</pre>
-<p>The way it works is that when the <code>@{...}</code> is seen in the
double-quoted
-string, it’s evaluated as a block. The block creates a reference to an
-anonymous array containing the results of the call to
<code>mysub(1,2,3)</code>. So
-the whole block returns a reference to an array, which is then
-dereferenced by <code>@{...}</code> and stuck into the double-quoted string.
This
-chicanery is also useful for arbitrary expressions:
-</p>
-<pre class="verbatim"> print "That yields @{[$n + 5]} widgets\n";
-</pre>
-<p>Similarly, an expression that returns a reference to a scalar can be
-dereferenced via <code>${...}</code>. Thus, the above expression may be written
-as:
-</p>
-<pre class="verbatim"> print "That yields ${\($n + 5)} widgets\n";
-</pre>
-<hr>
-<a name="perlref-Circular-References"></a>
-<div class="header">
-<p>
-Next: <a href="#perlref-Symbolic-references" accesskey="n" rel="next">perlref
Symbolic references</a>, Previous: <a href="#perlref-Using-References"
accesskey="p" rel="prev">perlref Using References</a>, Up: <a
href="#perlref-DESCRIPTION" accesskey="u" rel="up">perlref DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Circular-References"></a>
-<h4 class="subsection">62.3.3 Circular References</h4>
-
-<p>It is possible to create a "circular reference" in Perl, which
can lead
-to memory leaks. A circular reference occurs when two references
-contain a reference to each other, like this:
-</p>
-<pre class="verbatim"> my $foo = {};
- my $bar = { foo => $foo };
- $foo->{bar} = $bar;
-</pre>
-<p>You can also create a circular reference with a single variable:
-</p>
-<pre class="verbatim"> my $foo;
- $foo = \$foo;
-</pre>
-<p>In this case, the reference count for the variables will never reach 0,
-and the references will never be garbage-collected. This can lead to
-memory leaks.
-</p>
-<p>Because objects in Perl are implemented as references, it’s possible
to
-have circular references with objects as well. Imagine a TreeNode class
-where each node references its parent and child nodes. Any node with a
-parent will be part of a circular reference.
-</p>
-<p>You can break circular references by creating a "weak reference".
A
-weak reference does not increment the reference count for a variable,
-which means that the object can go out of scope and be destroyed. You
-can weaken a reference with the <code>weaken</code> function exported by the
-<a href="Scalar-Util.html#Top">(Scalar-Util)</a> module.
-</p>
-<p>Here’s how we can make the first example safer:
-</p>
-<pre class="verbatim"> use Scalar::Util 'weaken';
-
- my $foo = {};
- my $bar = { foo => $foo };
- $foo->{bar} = $bar;
-
- weaken $foo->{bar};
-</pre>
-<p>The reference from <code>$foo</code> to <code>$bar</code> has been
weakened. When the
-<code>$bar</code> variable goes out of scope, it will be garbage-collected. The
-next time you look at the value of the <code>$foo->{bar}</code> key, it will
-be <code>undef</code>.
-</p>
-<p>This action at a distance can be confusing, so you should be careful
-with your use of weaken. You should weaken the reference in the
-variable that will go out of scope <em>first</em>. That way, the longer-lived
-variable will contain the expected reference until it goes out of
-scope.
-</p>
-<hr>
-<a name="perlref-Symbolic-references"></a>
-<div class="header">
-<p>
-Next: <a href="#perlref-Not_002dso_002dsymbolic-references" accesskey="n"
rel="next">perlref Not-so-symbolic references</a>, Previous: <a
href="#perlref-Circular-References" accesskey="p" rel="prev">perlref Circular
References</a>, Up: <a href="#perlref-DESCRIPTION" accesskey="u"
rel="up">perlref DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Symbolic-references"></a>
-<h4 class="subsection">62.3.4 Symbolic references</h4>
-
-<p>We said that references spring into existence as necessary if they are
-undefined, but we didn’t say what happens if a value used as a
-reference is already defined, but <em>isn’t</em> a hard reference. If
you
-use it as a reference, it’ll be treated as a symbolic
-reference. That is, the value of the scalar is taken to be the <em>name</em>
-of a variable, rather than a direct link to a (possibly) anonymous
-value.
-</p>
-<p>People frequently expect it to work like this. So it does.
-</p>
-<pre class="verbatim"> $name = "foo";
- $$name = 1; # Sets $foo
- ${$name} = 2; # Sets $foo
- ${$name x 2} = 3; # Sets $foofoo
- $name->[0] = 4; # Sets $foo[0]
- @$name = (); # Clears @foo
- &$name(); # Calls &foo()
- $pack = "THAT";
- ${"${pack}::$name"} = 5; # Sets $THAT::foo without eval
-</pre>
-<p>This is powerful, and slightly dangerous, in that it’s possible
-to intend (with the utmost sincerity) to use a hard reference, and
-accidentally use a symbolic reference instead. To protect against
-that, you can say
-</p>
-<pre class="verbatim"> use strict 'refs';
-</pre>
-<p>and then only hard references will be allowed for the rest of the enclosing
-block. An inner block may countermand that with
-</p>
-<pre class="verbatim"> no strict 'refs';
-</pre>
-<p>Only package variables (globals, even if localized) are visible to
-symbolic references. Lexical variables (declared with my()) aren’t in
-a symbol table, and thus are invisible to this mechanism. For example:
-</p>
-<pre class="verbatim"> local $value = 10;
- $ref = "value";
- {
- my $value = 20;
- print $$ref;
- }
-</pre>
-<p>This will still print 10, not 20. Remember that local() affects package
-variables, which are all "global" to the package.
-</p>
-<hr>
-<a name="perlref-Not_002dso_002dsymbolic-references"></a>
-<div class="header">
-<p>
-Next: <a href="#perlref-Pseudo_002dhashes_003a-Using-an-array-as-a-hash"
accesskey="n" rel="next">perlref Pseudo-hashes: Using an array as a hash</a>,
Previous: <a href="#perlref-Symbolic-references" accesskey="p"
rel="prev">perlref Symbolic references</a>, Up: <a href="#perlref-DESCRIPTION"
accesskey="u" rel="up">perlref DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Not_002dso_002dsymbolic-references"></a>
-<h4 class="subsection">62.3.5 Not-so-symbolic references</h4>
-
-<p>Brackets around a symbolic reference can simply
-serve to isolate an identifier or variable name from the rest of an
-expression, just as they always have within a string. For example,
-</p>
-<pre class="verbatim"> $push = "pop on ";
- print "${push}over";
-</pre>
-<p>has always meant to print "pop on over", even though push is
-a reserved word. This is generalized to work the same
-without the enclosing double quotes, so that
-</p>
-<pre class="verbatim"> print ${push} . "over";
-</pre>
-<p>and even
-</p>
-<pre class="verbatim"> print ${ push } . "over";
-</pre>
-<p>will have the same effect. This
-construct is <em>not</em> considered to be a symbolic reference when
you’re
-using strict refs:
-</p>
-<pre class="verbatim"> use strict 'refs';
- ${ bareword }; # Okay, means $bareword.
- ${ "bareword" }; # Error, symbolic reference.
-</pre>
-<p>Similarly, because of all the subscripting that is done using single words,
-the same rule applies to any bareword that is used for subscripting a hash.
-So now, instead of writing
-</p>
-<pre class="verbatim"> $array{ "aaa" }{ "bbb" }{
"ccc" }
-</pre>
-<p>you can write just
-</p>
-<pre class="verbatim"> $array{ aaa }{ bbb }{ ccc }
-</pre>
-<p>and not worry about whether the subscripts are reserved words. In the
-rare event that you do wish to do something like
-</p>
-<pre class="verbatim"> $array{ shift }
-</pre>
-<p>you can force interpretation as a reserved word by adding anything that
-makes it more than a bareword:
-</p>
-<pre class="verbatim"> $array{ shift() }
- $array{ +shift }
- $array{ shift @_ }
-</pre>
-<p>The <code>use warnings</code> pragma or the <strong>-w</strong> switch will
warn you if it
-interprets a reserved word as a string.
-But it will no longer warn you about using lowercase words, because the
-string is effectively quoted.
-</p>
-<hr>
-<a name="perlref-Pseudo_002dhashes_003a-Using-an-array-as-a-hash"></a>
-<div class="header">
-<p>
-Next: <a href="#perlref-Function-Templates" accesskey="n" rel="next">perlref
Function Templates</a>, Previous: <a
href="#perlref-Not_002dso_002dsymbolic-references" accesskey="p"
rel="prev">perlref Not-so-symbolic references</a>, Up: <a
href="#perlref-DESCRIPTION" accesskey="u" rel="up">perlref DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Pseudo_002dhashes_003a-Using-an-array-as-a-hash"></a>
-<h4 class="subsection">62.3.6 Pseudo-hashes: Using an array as a hash</h4>
-
-<p>Pseudo-hashes have been removed from Perl. The ’fields’ pragma
-remains available.
-</p>
-<hr>
-<a name="perlref-Function-Templates"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlref-Pseudo_002dhashes_003a-Using-an-array-as-a-hash"
accesskey="p" rel="prev">perlref Pseudo-hashes: Using an array as a hash</a>,
Up: <a href="#perlref-DESCRIPTION" accesskey="u" rel="up">perlref
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Function-Templates"></a>
-<h4 class="subsection">62.3.7 Function Templates</h4>
-
-<p>As explained above, an anonymous function with access to the lexical
-variables visible when that function was compiled, creates a closure. It
-retains access to those variables even though it doesn’t get run until
-later, such as in a signal handler or a Tk callback.
-</p>
-<p>Using a closure as a function template allows us to generate many functions
-that act similarly. Suppose you wanted functions named after the colors
-that generated HTML font changes for the various colors:
-</p>
-<pre class="verbatim"> print "Be ", red("careful"),
"with that ", green("light");
-</pre>
-<p>The red() and green() functions would be similar. To create these,
-we’ll assign a closure to a typeglob of the name of the function
we’re
-trying to build.
-</p>
-<pre class="verbatim"> @colors = qw(red blue green yellow orange purple
violet);
- for my $name (@colors) {
- no strict 'refs'; # allow symbol table manipulation
- *$name = *{uc $name} = sub { "<FONT
COLOR='$name'>@_</FONT>" };
- }
-</pre>
-<p>Now all those different functions appear to exist independently. You can
-call red(), RED(), blue(), BLUE(), green(), etc. This technique saves on
-both compile time and memory use, and is less error-prone as well, since
-syntax checks happen at compile time. It’s critical that any variables
in
-the anonymous subroutine be lexicals in order to create a proper closure.
-That’s the reasons for the <code>my</code> on the loop iteration
variable.
-</p>
-<p>This is one of the only places where giving a prototype to a closure makes
-much sense. If you wanted to impose scalar context on the arguments of
-these functions (probably not a wise idea for this particular example),
-you could have written it this way instead:
-</p>
-<pre class="verbatim"> *$name = sub ($) { "<FONT
COLOR='$name'>$_[0]</FONT>" };
-</pre>
-<p>However, since prototype checking happens at compile time, the assignment
-above happens too late to be of much use. You could address this by
-putting the whole loop of assignments within a BEGIN block, forcing it
-to occur during compilation.
-</p>
-<p>Access to lexicals that change over time–like those in the
<code>for</code> loop
-above, basically aliases to elements from the surrounding lexical scopes–
-only works with anonymous subs, not with named subroutines. Generally
-said, named subroutines do not nest properly and should only be declared
-in the main package scope.
-</p>
-<p>This is because named subroutines are created at compile time so their
-lexical variables get assigned to the parent lexicals from the first
-execution of the parent block. If a parent scope is entered a second
-time, its lexicals are created again, while the nested subs still
-reference the old ones.
-</p>
-<p>Anonymous subroutines get to capture each time you execute the
<code>sub</code>
-operator, as they are created on the fly. If you are accustomed to using
-nested subroutines in other programming languages with their own private
-variables, you’ll have to work at it a bit in Perl. The intuitive coding
-of this type of thing incurs mysterious warnings about "will not stay
-shared" due to the reasons explained above.
-For example, this won’t work:
-</p>
-<pre class="verbatim"> sub outer {
- my $x = $_[0] + 35;
- sub inner { return $x * 19 } # WRONG
- return $x + inner();
- }
-</pre>
-<p>A work-around is the following:
-</p>
-<pre class="verbatim"> sub outer {
- my $x = $_[0] + 35;
- local *inner = sub { return $x * 19 };
- return $x + inner();
- }
-</pre>
-<p>Now inner() can only be called from within outer(), because of the
-temporary assignments of the anonymous subroutine. But when it does,
-it has normal access to the lexical variable $x from the scope of
-outer() at the time outer is invoked.
-</p>
-<p>This has the interesting effect of creating a function local to another
-function, something not normally supported in Perl.
-</p>
-<hr>
-<a name="perlref-WARNING"></a>
-<div class="header">
-<p>
-Next: <a href="#perlref-Postfix-Dereference-Syntax" accesskey="n"
rel="next">perlref Postfix Dereference Syntax</a>, Previous: <a
href="#perlref-DESCRIPTION" accesskey="p" rel="prev">perlref DESCRIPTION</a>,
Up: <a href="#perlref" accesskey="u" rel="up">perlref</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="WARNING"></a>
-<h3 class="section">62.4 WARNING</h3>
-
-<p>You may not (usefully) use a reference as the key to a hash. It will be
-converted into a string:
-</p>
-<pre class="verbatim"> $x{ \$a } = $a;
-</pre>
-<p>If you try to dereference the key, it won’t do a hard dereference, and
-you won’t accomplish what you’re attempting. You might want to do
something
-more like
-</p>
-<pre class="verbatim"> $r = address@hidden;
- $x{ $r } = $r;
-</pre>
-<p>And then at least you can use the values(), which will be
-real refs, instead of the keys(), which won’t.
-</p>
-<p>The standard Tie::RefHash module provides a convenient workaround to this.
-</p>
-<hr>
-<a name="perlref-Postfix-Dereference-Syntax"></a>
-<div class="header">
-<p>
-Next: <a href="#perlref-Assigning-to-References" accesskey="n"
rel="next">perlref Assigning to References</a>, Previous: <a
href="#perlref-WARNING" accesskey="p" rel="prev">perlref WARNING</a>, Up: <a
href="#perlref" accesskey="u" rel="up">perlref</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Postfix-Dereference-Syntax"></a>
-<h3 class="section">62.5 Postfix Dereference Syntax</h3>
-
-<p>Beginning in v5.20.0, a postfix syntax for using references is
-available. It behaves as described in <a
href="#perlref-Using-References">Using References</a>, but instead
-of a prefixed sigil, a postfixed sigil-and-star is used.
-</p>
-<p>For example:
-</p>
-<pre class="verbatim"> $r = address@hidden;
- @b = $r->@*; # equivalent to @$r or @{ $r }
-
- $r = [ 1, [ 2, 3 ], 4 ];
- $r->[1]->@*; # equivalent to @{ $r->[1] }
-</pre>
-<p>This syntax must be enabled with <code>use feature 'postderef'</code>. It
is
-experimental, and will warn by default unless <code>no warnings
-'experimental::postderef'</code> is in effect.
-</p>
-<p>Postfix dereference should work in all circumstances where block
-(circumfix) dereference worked, and should be entirely equivalent. This
-syntax allows dereferencing to be written and read entirely
-left-to-right. The following equivalencies are defined:
-</p>
-<pre class="verbatim"> $sref->$*; # same as ${ $sref }
- $aref->@*; # same as @{ $aref }
- $aref->$#*; # same as $#{ $aref }
- $href->%*; # same as %{ $href }
- $cref->&*; # same as &{ $cref }
- $gref->**; # same as *{ $gref }
-</pre>
-<p>Note especially that <code>$cref->&*</code> is <em>not</em>
equivalent to <code>$cref->()</code>, and can serve different purposes.
-</p>
-<p>Glob elements can be extracted through the postfix dereferencing feature:
-</p>
-<pre class="verbatim"> $gref->*{SCALAR}; # same as *{ $gref }{SCALAR}
-</pre>
-<p>Postfix array and scalar dereferencing <em>can</em> be used in interpolating
-strings (double quotes or the <code>qq</code> operator), but only if the
-additional <code>postderef_qq</code> feature is enabled.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlref-Postfix-Reference-Slicing" accesskey="1">perlref Postfix
Reference Slicing</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlref-Postfix-Reference-Slicing"></a>
-<div class="header">
-<p>
-Up: <a href="#perlref-Postfix-Dereference-Syntax" accesskey="u"
rel="up">perlref Postfix Dereference Syntax</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Postfix-Reference-Slicing"></a>
-<h4 class="subsection">62.5.1 Postfix Reference Slicing</h4>
-
-<p>Value slices of arrays and hashes may also be taken with postfix
-dereferencing notation, with the following equivalencies:
-</p>
-<pre class="verbatim"> $aref->@[ ... ]; # same as @$aref[ ... ]
- $href->@{ ... }; # same as @$href{ ... }
-</pre>
-<p>Postfix key/value pair slicing, added in 5.20.0 and documented in
-<a href="#perldata-Key_002fValue-Hash-Slices">the Key/Value Hash Slices
section of perldata</a>, also behaves as expected:
-</p>
-<pre class="verbatim"> $aref->%[ ... ]; # same as %$aref[ ... ]
- $href->%{ ... }; # same as %$href{ ... }
-</pre>
-<p>As with postfix array, postfix value slice dereferencing <em>can</em> be
used
-in interpolating strings (double quotes or the <code>qq</code> operator), but
only
-if the additional <code>postderef_qq</code> <a
href="feature.html#Top">(feature)</a> is enabled.
-</p>
-<hr>
-<a name="perlref-Assigning-to-References"></a>
-<div class="header">
-<p>
-Next: <a href="#perlref-SEE-ALSO" accesskey="n" rel="next">perlref SEE
ALSO</a>, Previous: <a href="#perlref-Postfix-Dereference-Syntax" accesskey="p"
rel="prev">perlref Postfix Dereference Syntax</a>, Up: <a href="#perlref"
accesskey="u" rel="up">perlref</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Assigning-to-References"></a>
-<h3 class="section">62.6 Assigning to References</h3>
-
-<p>Beginning in v5.22.0, the referencing operator can be assigned to. It
-performs an aliasing operation, so that the variable name referenced on the
-left-hand side becomes an alias for the thing referenced on the right-hand
-side:
-</p>
-<pre class="verbatim"> \$a = \$b; # $a and $b now point to the same scalar
- \&foo = \&bar; # foo() now means bar()
-</pre>
-<p>This syntax must be enabled with <code>use feature 'refaliasing'</code>.
It is
-experimental, and will warn by default unless <code>no warnings
-'experimental::refaliasing'</code> is in effect.
-</p>
-<p>These forms may be assigned to, and cause the right-hand side to be
-evaluated in scalar context:
-</p>
-<pre class="verbatim"> \$scalar
- address@hidden
- \%hash
- \&sub
- \my $scalar
- \my @array
- \my %hash
- \state $scalar # or @array, etc.
- \our $scalar # etc.
- \local $scalar # etc.
- \local our $scalar # etc.
- \$some_array[$index]
- \$some_hash{$key}
- \local $some_array[$index]
- \local $some_hash{$key}
- condition ? \$this : \$that[0] # etc.
-</pre>
-<p>Slicing operations and parentheses cause
-the right-hand side to be evaluated in
-list context:
-</p>
-<pre class="verbatim"> address@hidden
- (address@hidden)
- \(@array[5..7])
- address@hidden'foo','bar'}
- (address@hidden'foo','bar'})
- \(@hash{'foo','bar'})
- (\$scalar)
- \($scalar)
- \(my $scalar)
- \my($scalar)
- (address@hidden)
- (\%hash)
- (\&sub)
- \(&sub)
- \($foo, @bar, %baz)
- (\$foo, address@hidden, \%baz)
-</pre>
-<p>Each element on the right-hand side must be a reference to a datum of the
-right type. Parentheses immediately surrounding an array (and possibly
-also <code>my</code>/<code>state</code>/<code>our</code>/<code>local</code>)
will make each element of the array an
-alias to the corresponding scalar referenced on the right-hand side:
-</p>
-<pre class="verbatim"> \(@a) = \(@b); # @a and @b now have the same elements
- \my(@a) = \(@b); # likewise
- \(my @a) = \(@b); # likewise
- push @a, 3; # but now @a has an extra element that @b lacks
- \(@a) = (\$a, \$b, \$c); # @a now contains $a, $b, and $c
-</pre>
-<p>Combining that form with <code>local</code> and putting parentheses
immediately
-around a hash are forbidden (because it is not clear what they should do):
-</p>
-<pre class="verbatim"> \local(@array) = foo(); # WRONG
- \(%hash) = bar(); # wRONG
-</pre>
-<p>Assignment to references and non-references may be combined in lists and
-conditional ternary expressions, as long as the values on the right-hand
-side are the right type for each element on the left, though this may make
-for obfuscated code:
-</p>
-<pre class="verbatim"> (my $tom, \my $dick, \my @harry) = (\1, \2, [1..3]);
- # $tom is now \1
- # $dick is now 2 (read-only)
- # @harry is (1,2,3)
-
- my $type = ref $thingy;
- ($type ? $type == 'ARRAY' ? address@hidden : \$bar : $baz) = $thingy;
-</pre>
-<p>The <code>foreach</code> loop can also take a reference constructor for its
loop
-variable, though the syntax is limited to one of the following, with an
-optional <code>my</code>, <code>state</code>, or <code>our</code> after the
backslash:
-</p>
-<pre class="verbatim"> \$s
- address@hidden
- \%h
- \&c
-</pre>
-<p>No parentheses are permitted. This feature is particularly useful for
-arrays-of-arrays, or arrays-of-hashes:
-</p>
-<pre class="verbatim"> foreach \my @a (@array_of_arrays) {
- frobnicate($a[0], $a[-1]);
- }
-
- foreach \my %h (@array_of_hashes) {
- $h{gelastic}++ if $h{type} == 'funny';
- }
-</pre>
-<p><strong>CAVEAT:</strong> Aliasing does not work correctly with closures.
If you try to
-alias lexical variables from an inner subroutine or <code>eval</code>, the
aliasing
-will only be visible within that inner sub, and will not affect the outer
-subroutine where the variables are declared. This bizarre behavior is
-subject to change.
-</p>
-<hr>
-<a name="perlref-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlref-Assigning-to-References" accesskey="p"
rel="prev">perlref Assigning to References</a>, Up: <a href="#perlref"
accesskey="u" rel="up">perlref</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-31"></a>
-<h3 class="section">62.7 SEE ALSO</h3>
-
-<p>Besides the obvious documents, source code can be instructive.
-Some pathological examples of the use of references can be found
-in the <samp>t/op/ref.t</samp> regression test in the Perl source directory.
-</p>
-<p>See also <a href="#perldsc-NAME">perldsc NAME</a> and <a
href="#perllol-NAME">perllol NAME</a> for how to use references to create
-complex data structures, and <a href="#perlootut-NAME">perlootut NAME</a> and
<a href="#perlobj-NAME">perlobj NAME</a>
-for how to use them to create objects.
-</p>
-<hr>
-<a name="perlreftut"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts" accesskey="n" rel="next">perlreguts</a>, Previous:
<a href="#perlref" accesskey="p" rel="prev">perlref</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlreftut-1"></a>
-<h2 class="chapter">63 perlreftut</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlreftut-NAME"
accesskey="1">perlreftut NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreftut-DESCRIPTION"
accesskey="2">perlreftut DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut-Who-Needs-Complicated-Data-Structures_003f"
accesskey="3">perlreftut Who Needs Complicated Data
Structures?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreftut-The-Solution"
accesskey="4">perlreftut The Solution</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreftut-Syntax"
accesskey="5">perlreftut Syntax</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreftut-Solution"
accesskey="6">perlreftut Solution</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreftut-The-Rest"
accesskey="7">perlreftut The Rest</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreftut-Summary"
accesskey="8">perlreftut Summary</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreftut-Credits"
accesskey="9">perlreftut Credits</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreftut-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreftut-DESCRIPTION" accesskey="n" rel="next">perlreftut
DESCRIPTION</a>, Up: <a href="#perlreftut" accesskey="u"
rel="up">perlreftut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-62"></a>
-<h3 class="section">63.1 NAME</h3>
-
-<p>perlreftut - Mark’s very short tutorial about references
-</p>
-<hr>
-<a name="perlreftut-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreftut-Who-Needs-Complicated-Data-Structures_003f"
accesskey="n" rel="next">perlreftut Who Needs Complicated Data Structures?</a>,
Previous: <a href="#perlreftut-NAME" accesskey="p" rel="prev">perlreftut
NAME</a>, Up: <a href="#perlreftut" accesskey="u" rel="up">perlreftut</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-61"></a>
-<h3 class="section">63.2 DESCRIPTION</h3>
-
-<p>One of the most important new features in Perl 5 was the capability to
-manage complicated data structures like multidimensional arrays and
-nested hashes. To enable these, Perl 5 introduced a feature called
-’references’, and using references is the key to managing
complicated,
-structured data in Perl. Unfortunately, there’s a lot of funny syntax
-to learn, and the main manual page can be hard to follow. The manual
-is quite complete, and sometimes people find that a problem, because
-it can be hard to tell what is important and what isn’t.
-</p>
-<p>Fortunately, you only need to know 10% of what’s in the main page to
get
-90% of the benefit. This page will show you that 10%.
-</p>
-<hr>
-<a name="perlreftut-Who-Needs-Complicated-Data-Structures_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreftut-The-Solution" accesskey="n" rel="next">perlreftut
The Solution</a>, Previous: <a href="#perlreftut-DESCRIPTION" accesskey="p"
rel="prev">perlreftut DESCRIPTION</a>, Up: <a href="#perlreftut" accesskey="u"
rel="up">perlreftut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Who-Needs-Complicated-Data-Structures_003f"></a>
-<h3 class="section">63.3 Who Needs Complicated Data Structures?</h3>
-
-<p>One problem that comes up all the time is needing a hash whose values are
-lists. Perl has hashes, of course, but the values have to be scalars;
-they can’t be lists.
-</p>
-<p>Why would you want a hash of lists? Let’s take a simple example: You
-have a file of city and country names, like this:
-</p>
-<pre class="verbatim"> Chicago, USA
- Frankfurt, Germany
- Berlin, Germany
- Washington, USA
- Helsinki, Finland
- New York, USA
-</pre>
-<p>and you want to produce an output like this, with each country mentioned
-once, and then an alphabetical list of the cities in that country:
-</p>
-<pre class="verbatim"> Finland: Helsinki.
- Germany: Berlin, Frankfurt.
- USA: Chicago, New York, Washington.
-</pre>
-<p>The natural way to do this is to have a hash whose keys are country
-names. Associated with each country name key is a list of the cities in
-that country. Each time you read a line of input, split it into a country
-and a city, look up the list of cities already known to be in that
-country, and append the new city to the list. When you’re done reading
-the input, iterate over the hash as usual, sorting each list of cities
-before you print it out.
-</p>
-<p>If hash values couldn’t be lists, you lose. You’d probably
have to
-combine all the cities into a single string somehow, and then when
-time came to write the output, you’d have to break the string into a
-list, sort the list, and turn it back into a string. This is messy
-and error-prone. And it’s frustrating, because Perl already has
-perfectly good lists that would solve the problem if only you could
-use them.
-</p>
-<hr>
-<a name="perlreftut-The-Solution"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreftut-Syntax" accesskey="n" rel="next">perlreftut
Syntax</a>, Previous: <a
href="#perlreftut-Who-Needs-Complicated-Data-Structures_003f" accesskey="p"
rel="prev">perlreftut Who Needs Complicated Data Structures?</a>, Up: <a
href="#perlreftut" accesskey="u" rel="up">perlreftut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-Solution"></a>
-<h3 class="section">63.4 The Solution</h3>
-
-<p>By the time Perl 5 rolled around, we were already stuck with this
-design: Hash values must be scalars. The solution to this is
-references.
-</p>
-<p>A reference is a scalar value that <em>refers to</em> an entire array or an
-entire hash (or to just about anything else). Names are one kind of
-reference that you’re already familiar with. Think of the President
-of the United States: a messy, inconvenient bag of blood and bones.
-But to talk about him, or to represent him in a computer program, all
-you need is the easy, convenient scalar string "Barack Obama".
-</p>
-<p>References in Perl are like names for arrays and hashes. They’re
-Perl’s private, internal names, so you can be sure they’re
-unambiguous. Unlike "Barack Obama", a reference only refers to one
-thing, and you always know what it refers to. If you have a reference
-to an array, you can recover the entire array from it. If you have a
-reference to a hash, you can recover the entire hash. But the
-reference is still an easy, compact scalar value.
-</p>
-<p>You can’t have a hash whose values are arrays; hash values can only be
-scalars. We’re stuck with that. But a single reference can refer to
-an entire array, and references are scalars, so you can have a hash of
-references to arrays, and it’ll act a lot like a hash of arrays, and
-it’ll be just as useful as a hash of arrays.
-</p>
-<p>We’ll come back to this city-country problem later, after we’ve
seen
-some syntax for managing references.
-</p>
-<hr>
-<a name="perlreftut-Syntax"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreftut-Solution" accesskey="n" rel="next">perlreftut
Solution</a>, Previous: <a href="#perlreftut-The-Solution" accesskey="p"
rel="prev">perlreftut The Solution</a>, Up: <a href="#perlreftut" accesskey="u"
rel="up">perlreftut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Syntax"></a>
-<h3 class="section">63.5 Syntax</h3>
-
-<p>There are just two ways to make a reference, and just two ways to use
-it once you have it.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlreftut-Making-References" accesskey="1">perlreftut Making
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreftut-Using-References" accesskey="2">perlreftut Using
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreftut-An-Example"
accesskey="3">perlreftut An Example</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreftut-Arrow-Rule"
accesskey="4">perlreftut Arrow Rule</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreftut-Making-References"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreftut-Using-References" accesskey="n"
rel="next">perlreftut Using References</a>, Up: <a href="#perlreftut-Syntax"
accesskey="u" rel="up">perlreftut Syntax</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Making-References-1"></a>
-<h4 class="subsection">63.5.1 Making References</h4>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlreftut-Make-Rule-1"
accesskey="1">perlreftut <strong>Make Rule
1</strong></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreftut-Make-Rule-1"></a>
-<div class="header">
-<p>
-Up: <a href="#perlreftut-Making-References" accesskey="u" rel="up">perlreftut
Making References</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Make-Rule-1"></a>
-<h4 class="subsubsection">63.5.1.1 <strong>Make Rule 1</strong></h4>
-
-<p>If you put a <code>\</code> in front of a variable, you get a
-reference to that variable.
-</p>
-<pre class="verbatim"> $aref = address@hidden; # $aref now holds a
reference to @array
- $href = \%hash; # $href now holds a reference to %hash
- $sref = \$scalar; # $sref now holds a reference to $scalar
-</pre>
-<p>Once the reference is stored in a variable like $aref or $href, you
-can copy it or store it just the same as any other scalar value:
-</p>
-<pre class="verbatim"> $xy = $aref; # $xy now holds a reference
to @array
- $p[3] = $href; # $p[3] now holds a reference to %hash
- $z = $p[3]; # $z now holds a reference to %hash
-</pre>
-<p>These examples show how to make references to variables with names.
-Sometimes you want to make an array or a hash that doesn’t have a
-name. This is analogous to the way you like to be able to use the
-string <code>"\n"</code> or the number 80 without having to store it
in a named
-variable first.
-</p>
-<p><strong>Make Rule 2</strong>
-</p>
-<p><code>[ ITEMS ]</code> makes a new, anonymous array, and returns a
reference to
-that array. <code>{ ITEMS }</code> makes a new, anonymous hash, and returns a
-reference to that hash.
-</p>
-<pre class="verbatim"> $aref = [ 1, "foo", undef, 13 ];
- # $aref now holds a reference to an array
-
- $href = { APR => 4, AUG => 8 };
- # $href now holds a reference to a hash
-</pre>
-<p>The references you get from rule 2 are the same kind of
-references that you get from rule 1:
-</p>
-<pre class="verbatim"> # This:
- $aref = [ 1, 2, 3 ];
-
- # Does the same as this:
- @array = (1, 2, 3);
- $aref = address@hidden;
-</pre>
-<p>The first line is an abbreviation for the following two lines, except
-that it doesn’t create the superfluous array variable
<code>@array</code>.
-</p>
-<p>If you write just <code>[]</code>, you get a new, empty anonymous array.
-If you write just <code>{}</code>, you get a new, empty anonymous hash.
-</p>
-<hr>
-<a name="perlreftut-Using-References"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreftut-An-Example" accesskey="n" rel="next">perlreftut An
Example</a>, Previous: <a href="#perlreftut-Making-References" accesskey="p"
rel="prev">perlreftut Making References</a>, Up: <a href="#perlreftut-Syntax"
accesskey="u" rel="up">perlreftut Syntax</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-References-1"></a>
-<h4 class="subsection">63.5.2 Using References</h4>
-
-<p>What can you do with a reference once you have it? It’s a scalar
-value, and we’ve seen that you can store it as a scalar and get it back
-again just like any scalar. There are just two more ways to use it:
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlreftut-Use-Rule-1"
accesskey="1">perlreftut <strong>Use Rule
1</strong></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreftut-Use-Rule-2"
accesskey="2">perlreftut <strong>Use Rule
2</strong></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreftut-Use-Rule-1"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreftut-Use-Rule-2" accesskey="n" rel="next">perlreftut
<strong>Use Rule 2</strong></a>, Up: <a href="#perlreftut-Using-References"
accesskey="u" rel="up">perlreftut Using References</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Use-Rule-1"></a>
-<h4 class="subsubsection">63.5.2.1 <strong>Use Rule 1</strong></h4>
-
-<p>You can always use an array reference, in curly braces, in place of
-the name of an array. For example, <code>@{$aref}</code> instead of
<code>@array</code>.
-</p>
-<p>Here are some examples of that:
-</p>
-<p>Arrays:
-</p>
-<pre class="verbatim"> @a @{$aref} An array
- reverse @a reverse @{$aref} Reverse the array
- $a[3] ${$aref}[3] An element of the array
- $a[3] = 17; ${$aref}[3] = 17 Assigning an element
-</pre>
-<p>On each line are two expressions that do the same thing. The
-left-hand versions operate on the array <code>@a</code>. The right-hand
-versions operate on the array that is referred to by <code>$aref</code>. Once
-they find the array they’re operating on, both versions do the same
-things to the arrays.
-</p>
-<p>Using a hash reference is <em>exactly</em> the same:
-</p>
-<pre class="verbatim"> %h %{$href} A hash
- keys %h keys %{$href} Get the keys from the hash
- $h{'red'} ${$href}{'red'} An element of the hash
- $h{'red'} = 17 ${$href}{'red'} = 17 Assigning an element
-</pre>
-<p>Whatever you want to do with a reference, <strong>Use Rule 1</strong> tells
you how
-to do it. You just write the Perl code that you would have written
-for doing the same thing to a regular array or hash, and then replace
-the array or hash name with <code>{$reference}</code>. "How do I loop
over an
-array when all I have is a reference?" Well, to loop over an array, you
-would write
-</p>
-<pre class="verbatim"> for my $element (@array) {
- ...
- }
-</pre>
-<p>so replace the array name, <code>@array</code>, with the reference:
-</p>
-<pre class="verbatim"> for my $element (@{$aref}) {
- ...
- }
-</pre>
-<p>"How do I print out the contents of a hash when all I have is a
-reference?" First write the code for printing out a hash:
-</p>
-<pre class="verbatim"> for my $key (keys %hash) {
- print "$key => $hash{$key}\n";
- }
-</pre>
-<p>And then replace the hash name with the reference:
-</p>
-<pre class="verbatim"> for my $key (keys %{$href}) {
- print "$key => ${$href}{$key}\n";
- }
-</pre>
-<hr>
-<a name="perlreftut-Use-Rule-2"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreftut-Use-Rule-1" accesskey="p" rel="prev">perlreftut
<strong>Use Rule 1</strong></a>, Up: <a href="#perlreftut-Using-References"
accesskey="u" rel="up">perlreftut Using References</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Use-Rule-2"></a>
-<h4 class="subsubsection">63.5.2.2 <strong>Use Rule 2</strong></h4>
-
-<p><strong>Use Rule 1</strong> is all you really need, because it tells you
how to do
-absolutely everything you ever need to do with references. But the
-most common thing to do with an array or a hash is to extract a single
-element, and the <strong>Use Rule 1</strong> notation is cumbersome. So there
is an
-abbreviation.
-</p>
-<p><code>${$aref}[3]</code> is too hard to read, so you can write
<code>$aref->[3]</code>
-instead.
-</p>
-<p><code>${$href}{red}</code> is too hard to read, so you can write
-<code>$href->{red}</code> instead.
-</p>
-<p>If <code>$aref</code> holds a reference to an array, then
<code>$aref->[3]</code> is
-the fourth element of the array. Don’t confuse this with
<code>$aref[3]</code>,
-which is the fourth element of a totally different array, one
-deceptively named <code>@aref</code>. <code>$aref</code> and
<code>@aref</code> are unrelated the
-same way that <code>$item</code> and <code>@item</code> are.
-</p>
-<p>Similarly, <code>$href->{'red'}</code> is part of the hash referred to by
-the scalar variable <code>$href</code>, perhaps even one with no name.
-<code>$href{'red'}</code> is part of the deceptively named <code>%href</code>
hash. It’s
-easy to forget to leave out the <code>-></code>, and if you do,
you’ll get
-bizarre results when your program gets array and hash elements out of
-totally unexpected hashes and arrays that weren’t the ones you wanted
-to use.
-</p>
-<hr>
-<a name="perlreftut-An-Example"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreftut-Arrow-Rule" accesskey="n" rel="next">perlreftut
Arrow Rule</a>, Previous: <a href="#perlreftut-Using-References" accesskey="p"
rel="prev">perlreftut Using References</a>, Up: <a href="#perlreftut-Syntax"
accesskey="u" rel="up">perlreftut Syntax</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="An-Example"></a>
-<h4 class="subsection">63.5.3 An Example</h4>
-
-<p>Let’s see a quick example of how all this is useful.
-</p>
-<p>First, remember that <code>[1, 2, 3]</code> makes an anonymous array
containing
-<code>(1, 2, 3)</code>, and gives you a reference to that array.
-</p>
-<p>Now think about
-</p>
-<pre class="verbatim"> @a = ( [1, 2, 3],
- [4, 5, 6],
- [7, 8, 9]
- );
-</pre>
-<p>@a is an array with three elements, and each one is a reference to
-another array.
-</p>
-<p><code>$a[1]</code> is one of these references. It refers to an array, the
array
-containing <code>(4, 5, 6)</code>, and because it is a reference to an array,
-<strong>Use Rule 2</strong> says that we can write <code>$a[1]->[2]</code>
to get the
-third element from that array. <code>$a[1]->[2]</code> is the 6.
-Similarly, <code>$a[0]->[1]</code> is the 2. What we have here is like a
-two-dimensional array; you can write <code>$a[ROW]->[COLUMN]</code> to get
-or set the element in any row and any column of the array.
-</p>
-<p>The notation still looks a little cumbersome, so there’s one more
-abbreviation:
-</p>
-<hr>
-<a name="perlreftut-Arrow-Rule"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreftut-An-Example" accesskey="p" rel="prev">perlreftut
An Example</a>, Up: <a href="#perlreftut-Syntax" accesskey="u"
rel="up">perlreftut Syntax</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Arrow-Rule"></a>
-<h4 class="subsection">63.5.4 Arrow Rule</h4>
-
-<p>In between two <strong>subscripts</strong>, the arrow is optional.
-</p>
-<p>Instead of <code>$a[1]->[2]</code>, we can write <code>$a[1][2]</code>;
it means the
-same thing. Instead of <code>$a[0]->[1] = 23</code>, we can write
-<code>$a[0][1] = 23</code>; it means the same thing.
-</p>
-<p>Now it really looks like two-dimensional arrays!
-</p>
-<p>You can see why the arrows are important. Without them, we would have
-had to write <code>${$a[1]}[2]</code> instead of <code>$a[1][2]</code>. For
-three-dimensional arrays, they let us write <code>$x[2][3][5]</code> instead of
-the unreadable <code>${${$x[2]}[3]}[5]</code>.
-</p>
-<hr>
-<a name="perlreftut-Solution"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreftut-The-Rest" accesskey="n" rel="next">perlreftut The
Rest</a>, Previous: <a href="#perlreftut-Syntax" accesskey="p"
rel="prev">perlreftut Syntax</a>, Up: <a href="#perlreftut" accesskey="u"
rel="up">perlreftut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Solution"></a>
-<h3 class="section">63.6 Solution</h3>
-
-<p>Here’s the answer to the problem I posed earlier, of reformatting a
-file of city and country names.
-</p>
-<pre class="verbatim"> 1 my %table;
-
- 2 while (<>) {
- 3 chomp;
- 4 my ($city, $country) = split /, /;
- 5 $table{$country} = [] unless exists $table{$country};
- 6 push @{$table{$country}}, $city;
- 7 }
-
- 8 foreach $country (sort keys %table) {
- 9 print "$country: ";
- 10 my @cities = @{$table{$country}};
- 11 print join ', ', sort @cities;
- 12 print ".\n";
- 13 }
-</pre>
-<p>The program has two pieces: Lines 2–7 read the input and build a data
-structure, and lines 8-13 analyze the data and print out the report.
-We’re going to have a hash, <code>%table</code>, whose keys are country
names,
-and whose values are references to arrays of city names. The data
-structure will look like this:
-</p>
-<pre class="verbatim"> %table
- +-------+---+
- | | | +-----------+--------+
- |Germany| *---->| Frankfurt | Berlin |
- | | | +-----------+--------+
- +-------+---+
- | | | +----------+
- |Finland| *---->| Helsinki |
- | | | +----------+
- +-------+---+
- | | | +---------+------------+----------+
- | USA | *---->| Chicago | Washington | New York |
- | | | +---------+------------+----------+
- +-------+---+
-</pre>
-<p>We’ll look at output first. Supposing we already have this structure,
-how do we print it out?
-</p>
-<pre class="verbatim"> 8 foreach $country (sort keys %table) {
- 9 print "$country: ";
- 10 my @cities = @{$table{$country}};
- 11 print join ', ', sort @cities;
- 12 print ".\n";
- 13 }
-</pre>
-<p><code>%table</code> is an
-ordinary hash, and we get a list of keys from it, sort the keys, and
-loop over the keys as usual. The only use of references is in line 10.
-<code>$table{$country}</code> looks up the key <code>$country</code> in the
hash
-and gets the value, which is a reference to an array of cities in that country.
-<strong>Use Rule 1</strong> says that
-we can recover the array by saying
-<code>@{$table{$country}}</code>. Line 10 is just like
-</p>
-<pre class="verbatim"> @cities = @array;
-</pre>
-<p>except that the name <code>array</code> has been replaced by the reference
-<code>{$table{$country}}</code>. The <code>@</code> tells Perl to get the
entire array.
-Having gotten the list of cities, we sort it, join it, and print it
-out as usual.
-</p>
-<p>Lines 2-7 are responsible for building the structure in the first
-place. Here they are again:
-</p>
-<pre class="verbatim"> 2 while (<>) {
- 3 chomp;
- 4 my ($city, $country) = split /, /;
- 5 $table{$country} = [] unless exists $table{$country};
- 6 push @{$table{$country}}, $city;
- 7 }
-</pre>
-<p>Lines 2-4 acquire a city and country name. Line 5 looks to see if the
-country is already present as a key in the hash. If it’s not, the
-program uses the <code>[]</code> notation (<strong>Make Rule 2</strong>) to
manufacture a new,
-empty anonymous array of cities, and installs a reference to it into
-the hash under the appropriate key.
-</p>
-<p>Line 6 installs the city name into the appropriate array.
-<code>$table{$country}</code> now holds a reference to the array of cities seen
-in that country so far. Line 6 is exactly like
-</p>
-<pre class="verbatim"> push @array, $city;
-</pre>
-<p>except that the name <code>array</code> has been replaced by the reference
-<code>{$table{$country}}</code>. The <code>push</code> adds a city name to
the end of the
-referred-to array.
-</p>
-<p>There’s one fine point I skipped. Line 5 is unnecessary, and we can
-get rid of it.
-</p>
-<pre class="verbatim"> 2 while (<>) {
- 3 chomp;
- 4 my ($city, $country) = split /, /;
- 5 #### $table{$country} = [] unless exists $table{$country};
- 6 push @{$table{$country}}, $city;
- 7 }
-</pre>
-<p>If there’s already an entry in <code>%table</code> for the current
<code>$country</code>,
-then nothing is different. Line 6 will locate the value in
-<code>$table{$country}</code>, which is a reference to an array, and push
-<code>$city</code> into the array. But
-what does it do when
-<code>$country</code> holds a key, say <code>Greece</code>, that is not yet in
<code>%table</code>?
-</p>
-<p>This is Perl, so it does the exact right thing. It sees that you want
-to push <code>Athens</code> onto an array that doesn’t exist, so it
helpfully
-makes a new, empty, anonymous array for you, installs it into
-<code>%table</code>, and then pushes <code>Athens</code> onto it. This is
called
-’autovivification’–bringing things to life automatically.
Perl saw
-that the key wasn’t in the hash, so it created a new hash entry
-automatically. Perl saw that you wanted to use the hash value as an
-array, so it created a new empty array and installed a reference to it
-in the hash automatically. And as usual, Perl made the array one
-element longer to hold the new city name.
-</p>
-<hr>
-<a name="perlreftut-The-Rest"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreftut-Summary" accesskey="n" rel="next">perlreftut
Summary</a>, Previous: <a href="#perlreftut-Solution" accesskey="p"
rel="prev">perlreftut Solution</a>, Up: <a href="#perlreftut" accesskey="u"
rel="up">perlreftut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-Rest"></a>
-<h3 class="section">63.7 The Rest</h3>
-
-<p>I promised to give you 90% of the benefit with 10% of the details, and
-that means I left out 90% of the details. Now that you have an
-overview of the important parts, it should be easier to read the
-<a href="#perlref-NAME">perlref NAME</a> manual page, which discusses 100% of
the details.
-</p>
-<p>Some of the highlights of <a href="#perlref-NAME">perlref NAME</a>:
-</p>
-<ul>
-<li> You can make references to anything, including scalars, functions, and
-other references.
-
-</li><li> In <strong>Use Rule 1</strong>, you can omit the curly brackets
whenever the thing
-inside them is an atomic scalar variable like <code>$aref</code>. For example,
-<code>@$aref</code> is the same as <code>@{$aref}</code>, and
<code>$$aref[1]</code> is the same as
-<code>${$aref}[1]</code>. If you’re just starting out, you may want to
adopt
-the habit of always including the curly brackets.
-
-</li><li> This doesn’t copy the underlying array:
-
-<pre class="verbatim"> $aref2 = $aref1;
-</pre>
-<p>You get two references to the same array. If you modify
-<code>$aref1->[23]</code> and then look at
-<code>$aref2->[23]</code> you’ll see the change.
-</p>
-<p>To copy the array, use
-</p>
-<pre class="verbatim"> $aref2 = address@hidden;
-</pre>
-<p>This uses <code>[...]</code> notation to create a new anonymous array, and
-<code>$aref2</code> is assigned a reference to the new array. The new array is
-initialized with the contents of the array referred to by <code>$aref1</code>.
-</p>
-<p>Similarly, to copy an anonymous hash, you can use
-</p>
-<pre class="verbatim"> $href2 = {%{$href1}};
-</pre>
-</li><li> To see if a variable contains a reference, use the <code>ref</code>
function. It
-returns true if its argument is a reference. Actually it’s a little
-better than that: It returns <code>HASH</code> for hash references and
<code>ARRAY</code>
-for array references.
-
-</li><li> If you try to use a reference like a string, you get strings like
-
-<pre class="verbatim"> ARRAY(0x80f5dec) or HASH(0x826afc0)
-</pre>
-<p>If you ever see a string that looks like this, you’ll know you
-printed out a reference by mistake.
-</p>
-<p>A side effect of this representation is that you can use <code>eq</code> to
see
-if two references refer to the same thing. (But you should usually use
-<code>==</code> instead because it’s much faster.)
-</p>
-</li><li> You can use a string as if it were a reference. If you use the
string
-<code>"foo"</code> as an array reference, it’s taken to be a
reference to the
-array <code>@foo</code>. This is called a <em>soft reference</em> or
<em>symbolic
-reference</em>. The declaration <code>use strict 'refs'</code> disables this
-feature, which can cause all sorts of trouble if you use it by accident.
-
-</li></ul>
-
-<p>You might prefer to go on to <a href="#perllol-NAME">perllol NAME</a>
instead of <a href="#perlref-NAME">perlref NAME</a>; it
-discusses lists of lists and multidimensional arrays in detail. After
-that, you should move on to <a href="#perldsc-NAME">perldsc NAME</a>;
it’s a Data Structure Cookbook
-that shows recipes for using and printing out arrays of hashes, hashes
-of arrays, and other kinds of data.
-</p>
-<hr>
-<a name="perlreftut-Summary"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreftut-Credits" accesskey="n" rel="next">perlreftut
Credits</a>, Previous: <a href="#perlreftut-The-Rest" accesskey="p"
rel="prev">perlreftut The Rest</a>, Up: <a href="#perlreftut" accesskey="u"
rel="up">perlreftut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Summary"></a>
-<h3 class="section">63.8 Summary</h3>
-
-<p>Everyone needs compound data structures, and in Perl the way you get
-them is with references. There are four important rules for managing
-references: Two for making references and two for using them. Once
-you know these rules you can do most of the important things you need
-to do with references.
-</p>
-<hr>
-<a name="perlreftut-Credits"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreftut-Summary" accesskey="p" rel="prev">perlreftut
Summary</a>, Up: <a href="#perlreftut" accesskey="u" rel="up">perlreftut</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Credits"></a>
-<h3 class="section">63.9 Credits</h3>
-
-<p>Author: Mark Jason Dominus, Plover Systems (<code>address@hidden</code>)
-</p>
-<p>This article originally appeared in <em>The Perl Journal</em>
-( http://www.tpj.com/ ) volume 3, #2. Reprinted with permission.
-</p>
-<p>The original title was <em>Understand References Today</em>.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlreftut-Distribution-Conditions" accesskey="1">perlreftut
Distribution Conditions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreftut-Distribution-Conditions"></a>
-<div class="header">
-<p>
-Up: <a href="#perlreftut-Credits" accesskey="u" rel="up">perlreftut
Credits</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Distribution-Conditions"></a>
-<h4 class="subsection">63.9.1 Distribution Conditions</h4>
-
-<p>Copyright 1998 The Perl Journal.
-</p>
-<p>This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-</p>
-<p>Irrespective of its distribution, all code examples in these files are
-hereby placed into the public domain. You are permitted and
-encouraged to use this code in your own programs for fun or for profit
-as you see fit. A simple comment in the code giving credit would be
-courteous but is not required.
-</p>
-<hr>
-<a name="perlreguts"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrepository" accesskey="n" rel="next">perlrepository</a>,
Previous: <a href="#perlreftut" accesskey="p" rel="prev">perlreftut</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlreguts-1"></a>
-<h2 class="chapter">64 perlreguts</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlreguts-NAME"
accesskey="1">perlreguts NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreguts-DESCRIPTION"
accesskey="2">perlreguts DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreguts-OVERVIEW"
accesskey="3">perlreguts OVERVIEW</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Process-Overview" accesskey="4">perlreguts Process
Overview</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreguts-MISCELLANEOUS"
accesskey="5">perlreguts MISCELLANEOUS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreguts-SEE-ALSO"
accesskey="6">perlreguts SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreguts-AUTHOR"
accesskey="7">perlreguts AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreguts-LICENCE"
accesskey="8">perlreguts LICENCE</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreguts-REFERENCES"
accesskey="9">perlreguts REFERENCES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreguts-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-DESCRIPTION" accesskey="n" rel="next">perlreguts
DESCRIPTION</a>, Up: <a href="#perlreguts" accesskey="u"
rel="up">perlreguts</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-63"></a>
-<h3 class="section">64.1 NAME</h3>
-
-<p>perlreguts - Description of the Perl regular expression engine.
-</p>
-<hr>
-<a name="perlreguts-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-OVERVIEW" accesskey="n" rel="next">perlreguts
OVERVIEW</a>, Previous: <a href="#perlreguts-NAME" accesskey="p"
rel="prev">perlreguts NAME</a>, Up: <a href="#perlreguts" accesskey="u"
rel="up">perlreguts</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-62"></a>
-<h3 class="section">64.2 DESCRIPTION</h3>
-
-<p>This document is an attempt to shine some light on the guts of the regex
-engine and how it works. The regex engine represents a significant chunk
-of the perl codebase, but is relatively poorly understood. This document
-is a meagre attempt at addressing this situation. It is derived from the
-author’s experience, comments in the source code, other papers on the
-regex engine, feedback on the perl5-porters mail list, and no doubt other
-places as well.
-</p>
-<p><strong>NOTICE!</strong> It should be clearly understood that the behavior
and
-structures discussed in this represents the state of the engine as the
-author understood it at the time of writing. It is <strong>NOT</strong> an API
-definition, it is purely an internals guide for those who want to hack
-the regex engine, or understand how the regex engine works. Readers of
-this document are expected to understand perl’s regex syntax and its
-usage in detail. If you want to learn about the basics of Perl’s
-regular expressions, see <a href="#perlre-NAME">perlre NAME</a>. And if you
want to replace the
-regex engine with your own, see <a href="#perlreapi-NAME">perlreapi NAME</a>.
-</p>
-<hr>
-<a name="perlreguts-OVERVIEW"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-Process-Overview" accesskey="n"
rel="next">perlreguts Process Overview</a>, Previous: <a
href="#perlreguts-DESCRIPTION" accesskey="p" rel="prev">perlreguts
DESCRIPTION</a>, Up: <a href="#perlreguts" accesskey="u"
rel="up">perlreguts</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="OVERVIEW-1"></a>
-<h3 class="section">64.3 OVERVIEW</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlreguts-A-quick-note-on-terms" accesskey="1">perlreguts A quick note
on terms</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-What-is-a-regular-expression-engine_003f"
accesskey="2">perlreguts What is a regular expression
engine?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Structure-of-a-Regexp-Program" accesskey="3">perlreguts
Structure of a Regexp Program</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreguts-A-quick-note-on-terms"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-What-is-a-regular-expression-engine_003f"
accesskey="n" rel="next">perlreguts What is a regular expression engine?</a>,
Up: <a href="#perlreguts-OVERVIEW" accesskey="u" rel="up">perlreguts
OVERVIEW</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="A-quick-note-on-terms"></a>
-<h4 class="subsection">64.3.1 A quick note on terms</h4>
-
-<p>There is some debate as to whether to say "regexp" or
"regex". In this
-document we will use the term "regex" unless there is a special
reason
-not to, in which case we will explain why.
-</p>
-<p>When speaking about regexes we need to distinguish between their source
-code form and their internal form. In this document we will use the term
-"pattern" when we speak of their textual, source code form, and the
term
-"program" when we speak of their internal representation. These
-correspond to the terms <em>S-regex</em> and <em>B-regex</em> that Mark Jason
-Dominus employs in his paper on "Rx" ([1] in <a
href="#perlreguts-REFERENCES">REFERENCES</a>).
-</p>
-<hr>
-<a name="perlreguts-What-is-a-regular-expression-engine_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-Structure-of-a-Regexp-Program" accesskey="n"
rel="next">perlreguts Structure of a Regexp Program</a>, Previous: <a
href="#perlreguts-A-quick-note-on-terms" accesskey="p" rel="prev">perlreguts A
quick note on terms</a>, Up: <a href="#perlreguts-OVERVIEW" accesskey="u"
rel="up">perlreguts OVERVIEW</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="What-is-a-regular-expression-engine_003f"></a>
-<h4 class="subsection">64.3.2 What is a regular expression engine?</h4>
-
-<p>A regular expression engine is a program that takes a set of constraints
-specified in a mini-language, and then applies those constraints to a
-target string, and determines whether or not the string satisfies the
-constraints. See <a href="#perlre-NAME">perlre NAME</a> for a full definition
of the language.
-</p>
-<p>In less grandiose terms, the first part of the job is to turn a pattern into
-something the computer can efficiently use to find the matching point in
-the string, and the second part is performing the search itself.
-</p>
-<p>To do this we need to produce a program by parsing the text. We then
-need to execute the program to find the point in the string that
-matches. And we need to do the whole thing efficiently.
-</p>
-<hr>
-<a name="perlreguts-Structure-of-a-Regexp-Program"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreguts-What-is-a-regular-expression-engine_003f"
accesskey="p" rel="prev">perlreguts What is a regular expression engine?</a>,
Up: <a href="#perlreguts-OVERVIEW" accesskey="u" rel="up">perlreguts
OVERVIEW</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Structure-of-a-Regexp-Program"></a>
-<h4 class="subsection">64.3.3 Structure of a Regexp Program</h4>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlreguts-High-Level"
accesskey="1">perlreguts High Level</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreguts-Regops"
accesskey="2">perlreguts Regops</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-What-regop-is-next_003f" accesskey="3">perlreguts What regop
is next?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreguts-High-Level"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-Regops" accesskey="n" rel="next">perlreguts
Regops</a>, Up: <a href="#perlreguts-Structure-of-a-Regexp-Program"
accesskey="u" rel="up">perlreguts Structure of a Regexp Program</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="High-Level"></a>
-<h4 class="subsubsection">64.3.3.1 High Level</h4>
-
-<p>Although it is a bit confusing and some people object to the terminology, it
-is worth taking a look at a comment that has
-been in <samp>regexp.h</samp> for years:
-</p>
-<p><em>This is essentially a linear encoding of a nondeterministic
-finite-state machine (aka syntax charts or "railroad normal form" in
-parsing technology).</em>
-</p>
-<p>The term "railroad normal form" is a bit esoteric, with
"syntax
-diagram/charts", or "railroad diagram/charts" being more common
terms.
-Nevertheless it provides a useful mental image of a regex program: each
-node can be thought of as a unit of track, with a single entry and in
-most cases a single exit point (there are pieces of track that fork, but
-statistically not many), and the whole forms a layout with a
-single entry and single exit point. The matching process can be thought
-of as a car that moves along the track, with the particular route through
-the system being determined by the character read at each possible
-connector point. A car can fall off the track at any point but it may
-only proceed as long as it matches the track.
-</p>
-<p>Thus the pattern <code>/foo(?:\w+|\d+|\s+)bar/</code> can be thought of as
the
-following chart:
-</p>
-<pre class="verbatim"> [start]
- |
- <foo>
- |
- +-----+-----+
- | | |
- <\w+> <\d+> <\s+>
- | | |
- +-----+-----+
- |
- <bar>
- |
- [end]
-</pre>
-<p>The truth of the matter is that perl’s regular expressions these days
are
-much more complex than this kind of structure, but visualising it this way
-can help when trying to get your bearings, and it matches the
-current implementation pretty closely.
-</p>
-<p>To be more precise, we will say that a regex program is an encoding
-of a graph. Each node in the graph corresponds to part of
-the original regex pattern, such as a literal string or a branch,
-and has a pointer to the nodes representing the next component
-to be matched. Since "node" and "opcode" already have
other meanings in the
-perl source, we will call the nodes in a regex program "regops".
-</p>
-<p>The program is represented by an array of <code>regnode</code> structures,
one or
-more of which represent a single regop of the program. Struct
-<code>regnode</code> is the smallest struct needed, and has a field structure
which is
-shared with all the other larger structures.
-</p>
-<p>The "next" pointers of all regops except <code>BRANCH</code>
implement concatenation;
-a "next" pointer with a <code>BRANCH</code> on both ends of it is
connecting two
-alternatives. [Here we have one of the subtle syntax dependencies: an
-individual <code>BRANCH</code> (as opposed to a collection of them) is never
-concatenated with anything because of operator precedence.]
-</p>
-<p>The operand of some types of regop is a literal string; for others,
-it is a regop leading into a sub-program. In particular, the operand
-of a <code>BRANCH</code> node is the first regop of the branch.
-</p>
-<p><strong>NOTE</strong>: As the railroad metaphor suggests, this is
<strong>not</strong> a tree
-structure: the tail of the branch connects to the thing following the
-set of <code>BRANCH</code>es. It is a like a single line of railway track that
-splits as it goes into a station or railway yard and rejoins as it comes
-out the other side.
-</p>
-<hr>
-<a name="perlreguts-Regops"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-What-regop-is-next_003f" accesskey="n"
rel="next">perlreguts What regop is next?</a>, Previous: <a
href="#perlreguts-High-Level" accesskey="p" rel="prev">perlreguts High
Level</a>, Up: <a href="#perlreguts-Structure-of-a-Regexp-Program"
accesskey="u" rel="up">perlreguts Structure of a Regexp Program</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Regops"></a>
-<h4 class="subsubsection">64.3.3.2 Regops</h4>
-
-<p>The base structure of a regop is defined in <samp>regexp.h</samp> as
follows:
-</p>
-<pre class="verbatim"> struct regnode {
- U8 flags; /* Various purposes, sometimes overridden */
- U8 type; /* Opcode value as specified by regnodes.h */
- U16 next_off; /* Offset in size regnode */
- };
-</pre>
-<p>Other larger <code>regnode</code>-like structures are defined in
<samp>regcomp.h</samp>. They
-are almost like subclasses in that they have the same fields as
-<code>regnode</code>, with possibly additional fields following in
-the structure, and in some cases the specific meaning (and name)
-of some of base fields are overridden. The following is a more
-complete description.
-</p>
-<dl compact="compact">
-<dt><code>regnode_1</code></dt>
-<dd><a name="perlreguts-regnode_005f1"></a>
-</dd>
-<dt><code>regnode_2</code></dt>
-<dd><a name="perlreguts-regnode_005f2"></a>
-<p><code>regnode_1</code> structures have the same header, followed by a single
-four-byte argument; <code>regnode_2</code> structures contain two two-byte
-arguments instead:
-</p>
-<pre class="verbatim"> regnode_1 U32 arg1;
- regnode_2 U16 arg1; U16 arg2;
-</pre>
-</dd>
-<dt><code>regnode_string</code></dt>
-<dd><a name="perlreguts-regnode_005fstring"></a>
-<p><code>regnode_string</code> structures, used for literal strings, follow
the header
-with a one-byte length and then the string data. Strings are padded on
-the end with zero bytes so that the total length of the node is a
-multiple of four bytes:
-</p>
-<pre class="verbatim"> regnode_string char string[1];
- U8 str_len; /* overrides flags */
-</pre>
-</dd>
-<dt><code>regnode_charclass</code></dt>
-<dd><a name="perlreguts-regnode_005fcharclass"></a>
-<p>Bracketed character classes are represented by
<code>regnode_charclass</code>
-structures, which have a four-byte argument and then a 32-byte (256-bit)
-bitmap indicating which characters in the Latin1 range are included in
-the class.
-</p>
-<pre class="verbatim"> regnode_charclass U32 arg1;
- char bitmap[ANYOF_BITMAP_SIZE];
-</pre>
-<p>Various flags whose names begin with <code>ANYOF_</code> are used for
special
-situations. Above Latin1 matches and things not known until run-time
-are stored in <a href="#perlreguts-Perl_0027s-pprivate-structure">Perl’s
pprivate structure</a>.
-</p>
-</dd>
-<dt><code>regnode_charclass_posixl</code></dt>
-<dd><a name="perlreguts-regnode_005fcharclass_005fposixl"></a>
-<p>There is also a larger form of a char class structure used to represent
-POSIX char classes under <code>/l</code> matching,
-called <code>regnode_charclass_posixl</code> which has an
-additional 32-bit bitmap indicating which POSIX char classes
-have been included.
-</p>
-<pre class="verbatim"> regnode_charclass_posixl U32 arg1;
- char bitmap[ANYOF_BITMAP_SIZE];
- U32 classflags;
-</pre>
-</dd>
-</dl>
-
-<p><samp>regnodes.h</samp> defines an array called <code>regarglen[]</code>
which gives the size
-of each opcode in units of <code>size regnode</code> (4-byte). A macro is used
-to calculate the size of an <code>EXACT</code> node based on its
<code>str_len</code> field.
-</p>
-<p>The regops are defined in <samp>regnodes.h</samp> which is generated from
-<samp>regcomp.sym</samp> by <samp>regcomp.pl</samp>. Currently the maximum
possible number
-of distinct regops is restricted to 256, with about a quarter already
-used.
-</p>
-<p>A set of macros makes accessing the fields
-easier and more consistent. These include <code>OP()</code>, which is used to
determine
-the type of a <code>regnode</code>-like structure; <code>NEXT_OFF()</code>,
which is the offset to
-the next node (more on this later); <code>ARG()</code>, <code>ARG1()</code>,
<code>ARG2()</code>, <code>ARG_SET()</code>,
-and equivalents for reading and setting the arguments; and
<code>STR_LEN()</code>,
-<code>STRING()</code> and <code>OPERAND()</code> for manipulating strings and
regop bearing
-types.
-</p>
-<hr>
-<a name="perlreguts-What-regop-is-next_003f"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreguts-Regops" accesskey="p" rel="prev">perlreguts
Regops</a>, Up: <a href="#perlreguts-Structure-of-a-Regexp-Program"
accesskey="u" rel="up">perlreguts Structure of a Regexp Program</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="What-regop-is-next_003f"></a>
-<h4 class="subsubsection">64.3.3.3 What regop is next?</h4>
-
-<p>There are three distinct concepts of "next" in the regex engine,
and
-it is important to keep them clear.
-</p>
-<ul>
-<li> There is the "next regnode" from a given regnode, a value which
is
-rarely useful except that sometimes it matches up in terms of value
-with one of the others, and that sometimes the code assumes this to
-always be so.
-
-</li><li> There is the "next regop" from a given regop/regnode. This
is the
-regop physically located after the current one, as determined by
-the size of the current regop. This is often useful, such as when
-dumping the structure we use this order to traverse. Sometimes the code
-assumes that the "next regnode" is the same as the "next
regop", or in
-other words assumes that the sizeof a given regop type is always going
-to be one regnode large.
-
-</li><li> There is the "regnext" from a given regop. This is the
regop which
-is reached by jumping forward by the value of <code>NEXT_OFF()</code>,
-or in a few cases for longer jumps by the <code>arg1</code> field of the
<code>regnode_1</code>
-structure. The subroutine <code>regnext()</code> handles this transparently.
-This is the logical successor of the node, which in some cases, like
-that of the <code>BRANCH</code> regop, has special meaning.
-
-</li></ul>
-
-<hr>
-<a name="perlreguts-Process-Overview"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-MISCELLANEOUS" accesskey="n" rel="next">perlreguts
MISCELLANEOUS</a>, Previous: <a href="#perlreguts-OVERVIEW" accesskey="p"
rel="prev">perlreguts OVERVIEW</a>, Up: <a href="#perlreguts" accesskey="u"
rel="up">perlreguts</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Process-Overview"></a>
-<h3 class="section">64.4 Process Overview</h3>
-
-<p>Broadly speaking, performing a match of a string against a pattern
-involves the following steps:
-</p>
-<dl compact="compact">
-<dt>A. Compilation</dt>
-<dd><a name="perlreguts-A_002e-Compilation"></a>
-<dl compact="compact">
-<dt>1. Parsing for size</dt>
-<dd><a name="perlreguts-1_002e-Parsing-for-size"></a>
-</dd>
-<dt>2. Parsing for construction</dt>
-<dd><a name="perlreguts-2_002e-Parsing-for-construction"></a>
-</dd>
-<dt>3. Peep-hole optimisation and analysis</dt>
-<dd><a name="perlreguts-3_002e-Peep_002dhole-optimisation-and-analysis"></a>
-</dd>
-</dl>
-
-</dd>
-<dt>B. Execution</dt>
-<dd><a name="perlreguts-B_002e-Execution"></a>
-<dl compact="compact">
-<dt>4. Start position and no-match optimisations</dt>
-<dd><a
name="perlreguts-4_002e-Start-position-and-no_002dmatch-optimisations"></a>
-</dd>
-<dt>5. Program execution</dt>
-<dd><a name="perlreguts-5_002e-Program-execution"></a>
-</dd>
-</dl>
-
-</dd>
-</dl>
-
-<p>Where these steps occur in the actual execution of a perl program is
-determined by whether the pattern involves interpolating any string
-variables. If interpolation occurs, then compilation happens at run time. If it
-does not, then compilation is performed at compile time. (The <code>/o</code>
modifier changes this,
-as does <code>qr//</code> to a certain extent.) The engine doesn’t
really care that
-much.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlreguts-Compilation"
accesskey="1">perlreguts Compilation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreguts-Execution"
accesskey="2">perlreguts Execution</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreguts-Compilation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-Execution" accesskey="n" rel="next">perlreguts
Execution</a>, Up: <a href="#perlreguts-Process-Overview" accesskey="u"
rel="up">perlreguts Process Overview</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Compilation"></a>
-<h4 class="subsection">64.4.1 Compilation</h4>
-
-<p>This code resides primarily in <samp>regcomp.c</samp>, along with the
header files
-<samp>regcomp.h</samp>, <samp>regexp.h</samp> and <samp>regnodes.h</samp>.
-</p>
-<p>Compilation starts with <code>pregcomp()</code>, which is mostly an
initialisation
-wrapper which farms work out to two other routines for the heavy lifting: the
-first is <code>reg()</code>, which is the start point for parsing; the second,
-<code>study_chunk()</code>, is responsible for optimisation.
-</p>
-<p>Initialisation in <code>pregcomp()</code> mostly involves the creation and
data-filling
-of a special structure, <code>RExC_state_t</code> (defined in
<samp>regcomp.c</samp>).
-Almost all internally-used routines in <samp>regcomp.h</samp> take a pointer
to one
-of these structures as their first argument, with the name
<code>pRExC_state</code>.
-This structure is used to store the compilation state and contains many
-fields. Likewise there are many macros which operate on this
-variable: anything that looks like <code>RExC_xxxx</code> is a macro that
operates on
-this pointer/structure.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Parsing-for-size" accesskey="1">perlreguts Parsing for
size</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Parsing-for-construction" accesskey="2">perlreguts Parsing
for construction</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Parse-Call-Graph-and-a-Grammar" accesskey="3">perlreguts
Parse Call Graph and a Grammar</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Parsing-complications" accesskey="4">perlreguts Parsing
complications</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreguts-Debug-Output"
accesskey="5">perlreguts Debug Output</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Peep_002dhole-Optimisation-and-Analysis"
accesskey="6">perlreguts Peep-hole Optimisation and
Analysis</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreguts-Parsing-for-size"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-Parsing-for-construction" accesskey="n"
rel="next">perlreguts Parsing for construction</a>, Up: <a
href="#perlreguts-Compilation" accesskey="u" rel="up">perlreguts
Compilation</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Parsing-for-size"></a>
-<h4 class="subsubsection">64.4.1.1 Parsing for size</h4>
-
-<p>In this pass the input pattern is parsed in order to calculate how much
-space is needed for each regop we would need to emit. The size is also
-used to determine whether long jumps will be required in the program.
-</p>
-<p>This stage is controlled by the macro <code>SIZE_ONLY</code> being set.
-</p>
-<p>The parse proceeds pretty much exactly as it does during the
-construction phase, except that most routines are short-circuited to
-change the size field <code>RExC_size</code> and not do anything else.
-</p>
-<hr>
-<a name="perlreguts-Parsing-for-construction"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-Parse-Call-Graph-and-a-Grammar" accesskey="n"
rel="next">perlreguts Parse Call Graph and a Grammar</a>, Previous: <a
href="#perlreguts-Parsing-for-size" accesskey="p" rel="prev">perlreguts Parsing
for size</a>, Up: <a href="#perlreguts-Compilation" accesskey="u"
rel="up">perlreguts Compilation</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Parsing-for-construction"></a>
-<h4 class="subsubsection">64.4.1.2 Parsing for construction</h4>
-
-<p>Once the size of the program has been determined, the pattern is parsed
-again, but this time for real. Now <code>SIZE_ONLY</code> will be false, and
the
-actual construction can occur.
-</p>
-<p><code>reg()</code> is the start of the parse process. It is responsible for
-parsing an arbitrary chunk of pattern up to either the end of the
-string, or the first closing parenthesis it encounters in the pattern.
-This means it can be used to parse the top-level regex, or any section
-inside of a grouping parenthesis. It also handles the "special
parens"
-that perl’s regexes have. For instance when parsing
<code>/x(?:foo)y/</code> <code>reg()</code>
-will at one point be called to parse from the "?" symbol up to and
-including the ")".
-</p>
-<p>Additionally, <code>reg()</code> is responsible for parsing the one or more
-branches from the pattern, and for "finishing them off" by correctly
-setting their next pointers. In order to do the parsing, it repeatedly
-calls out to <code>regbranch()</code>, which is responsible for handling up to
the
-first <code>|</code> symbol it sees.
-</p>
-<p><code>regbranch()</code> in turn calls <code>regpiece()</code> which
-handles "things" followed by a quantifier. In order to parse the
-"things", <code>regatom()</code> is called. This is the lowest level
routine, which
-parses out constant strings, character classes, and the
-various special symbols like <code>$</code>. If <code>regatom()</code>
encounters a "("
-character it in turn calls <code>reg()</code>.
-</p>
-<p>The routine <code>regtail()</code> is called by both <code>reg()</code> and
<code>regbranch()</code>
-in order to "set the tail pointer" correctly. When executing and
-we get to the end of a branch, we need to go to the node following the
-grouping parens. When parsing, however, we don’t know where the end will
-be until we get there, so when we do we must go back and update the
-offsets as appropriate. <code>regtail</code> is used to make this easier.
-</p>
-<p>A subtlety of the parsing process means that a regex like
<code>/foo/</code> is
-originally parsed into an alternation with a single branch. It is only
-afterwards that the optimiser converts single branch alternations into the
-simpler form.
-</p>
-<hr>
-<a name="perlreguts-Parse-Call-Graph-and-a-Grammar"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-Parsing-complications" accesskey="n"
rel="next">perlreguts Parsing complications</a>, Previous: <a
href="#perlreguts-Parsing-for-construction" accesskey="p" rel="prev">perlreguts
Parsing for construction</a>, Up: <a href="#perlreguts-Compilation"
accesskey="u" rel="up">perlreguts Compilation</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Parse-Call-Graph-and-a-Grammar"></a>
-<h4 class="subsubsection">64.4.1.3 Parse Call Graph and a Grammar</h4>
-
-<p>The call graph looks like this:
-</p>
-<pre class="verbatim"> reg() # parse a top level regex,
or inside of
- # parens
- regbranch() # parse a single branch of an alternation
- regpiece() # parse a pattern followed by a quantifier
- regatom() # parse a simple pattern
- regclass() # used to handle a class
- reg() # used to handle a parenthesised
- # subpattern
- ....
- ...
- regtail() # finish off the branch
- ...
- regtail() # finish off the branch sequence. Tie each
- # branch's tail to the tail of the
- # sequence
- # (NEW) In Debug mode this is
- # regtail_study().
-</pre>
-<p>A grammar form might be something like this:
-</p>
-<pre class="verbatim"> atom : constant | class
- quant : '*' | '+' | '?' | '{min,max}'
- _branch: piece
- | piece _branch
- | nothing
- branch: _branch
- | _branch '|' branch
- group : '(' branch ')'
- _piece: atom | group
- piece : _piece
- | _piece quant
-</pre>
-<hr>
-<a name="perlreguts-Parsing-complications"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-Debug-Output" accesskey="n" rel="next">perlreguts
Debug Output</a>, Previous: <a
href="#perlreguts-Parse-Call-Graph-and-a-Grammar" accesskey="p"
rel="prev">perlreguts Parse Call Graph and a Grammar</a>, Up: <a
href="#perlreguts-Compilation" accesskey="u" rel="up">perlreguts
Compilation</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Parsing-complications"></a>
-<h4 class="subsubsection">64.4.1.4 Parsing complications</h4>
-
-<p>The implication of the above description is that a pattern containing nested
-parentheses will result in a call graph which cycles through
<code>reg()</code>,
-<code>regbranch()</code>, <code>regpiece()</code>, <code>regatom()</code>,
<code>reg()</code>, <code>regbranch()</code> <em>etc</em>
-multiple times, until the deepest level of nesting is reached. All the above
-routines return a pointer to a <code>regnode</code>, which is usually the last
regnode
-added to the program. However, one complication is that reg() returns NULL
-for parsing <code>(?:)</code> syntax for embedded modifiers, setting the flag
-<code>TRYAGAIN</code>. The <code>TRYAGAIN</code> propagates upwards until it
is captured, in
-some cases by <code>regatom()</code>, but otherwise unconditionally by
-<code>regbranch()</code>. Hence it will never be returned by
<code>regbranch()</code> to
-<code>reg()</code>. This flag permits patterns such as <code>(?i)+</code> to
be detected as
-errors (<em>Quantifier follows nothing in regex; marked by <– HERE in
m/(?i)+
-<– HERE /</em>).
-</p>
-<p>Another complication is that the representation used for the program differs
-if it needs to store Unicode, but it’s not always possible to know for
sure
-whether it does until midway through parsing. The Unicode representation for
-the program is larger, and cannot be matched as efficiently. (See <a
href="#perlreguts-Unicode-and-Localisation-Support">Unicode
-and Localisation Support</a> below for more details as to why.) If the pattern
-contains literal Unicode, it’s obvious that the program needs to store
-Unicode. Otherwise, the parser optimistically assumes that the more
-efficient representation can be used, and starts sizing on this basis.
-However, if it then encounters something in the pattern which must be stored
-as Unicode, such as an <code>\x{...}</code> escape sequence representing a
character
-literal, then this means that all previously calculated sizes need to be
-redone, using values appropriate for the Unicode representation. Currently,
-all regular expression constructions which can trigger this are parsed by code
-in <code>regatom()</code>.
-</p>
-<p>To avoid wasted work when a restart is needed, the sizing pass is abandoned
-- <code>regatom()</code> immediately returns NULL, setting the flag
<code>RESTART_UTF8</code>.
-(This action is encapsulated using the macro <code>REQUIRE_UTF8</code>.) This
restart
-request is propagated up the call chain in a similar fashion, until it is
-"caught" in <code>Perl_re_op_compile()</code>, which marks the
pattern as containing
-Unicode, and restarts the sizing pass. It is also possible for constructions
-within run-time code blocks to turn out to need Unicode representation.,
-which is signalled by <code>S_compile_runtime_code()</code> returning false to
-<code>Perl_re_op_compile()</code>.
-</p>
-<p>The restart was previously implemented using a <code>longjmp</code> in
<code>regatom()</code>
-back to a <code>setjmp</code> in <code>Perl_re_op_compile()</code>, but this
proved to be
-problematic as the latter is a large function containing many automatic
-variables, which interact badly with the emergent control flow of
<code>setjmp</code>.
-</p>
-<hr>
-<a name="perlreguts-Debug-Output"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-Peep_002dhole-Optimisation-and-Analysis"
accesskey="n" rel="next">perlreguts Peep-hole Optimisation and Analysis</a>,
Previous: <a href="#perlreguts-Parsing-complications" accesskey="p"
rel="prev">perlreguts Parsing complications</a>, Up: <a
href="#perlreguts-Compilation" accesskey="u" rel="up">perlreguts
Compilation</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Debug-Output"></a>
-<h4 class="subsubsection">64.4.1.5 Debug Output</h4>
-
-<p>In the 5.9.x development version of perl you can <code>use re Debug =>
'PARSE'</code>
-to see some trace information about the parse process. We will start with some
-simple patterns and build up to more complex patterns.
-</p>
-<p>So when we parse <code>/foo/</code> we see something like the following
table. The
-left shows what is being parsed, and the number indicates where the next regop
-would go. The stuff on the right is the trace output of the graph. The
-names are chosen to be short to make it less dense on the screen.
’tsdy’
-is a special form of <code>regtail()</code> which does some extra analysis.
-</p>
-<pre class="verbatim"> >foo< 1 reg
- brnc
- piec
- atom
- >< 4 tsdy~ EXACT <foo> (EXACT) (1)
- ~ attach to END (3) offset to 2
-</pre>
-<p>The resulting program then looks like:
-</p>
-<pre class="verbatim"> 1: EXACT <foo>(3)
- 3: END(0)
-</pre>
-<p>As you can see, even though we parsed out a branch and a piece, it was
ultimately
-only an atom. The final program shows us how things work. We have an
<code>EXACT</code> regop,
-followed by an <code>END</code> regop. The number in parens indicates where
the <code>regnext</code> of
-the node goes. The <code>regnext</code> of an <code>END</code> regop is
unused, as <code>END</code> regops mean
-we have successfully matched. The number on the left indicates the position of
-the regop in the regnode array.
-</p>
-<p>Now let’s try a harder pattern. We will add a quantifier, so now we
have the pattern
-<code>/foo+/</code>. We will see that <code>regbranch()</code> calls
<code>regpiece()</code> twice.
-</p>
-<pre class="verbatim"> >foo+< 1 reg
- brnc
- piec
- atom
- >o+< 3 piec
- atom
- >< 6 tail~ EXACT <fo> (1)
- 7 tsdy~ EXACT <fo> (EXACT) (1)
- ~ PLUS (END) (3)
- ~ attach to END (6) offset to 3
-</pre>
-<p>And we end up with the program:
-</p>
-<pre class="verbatim"> 1: EXACT <fo>(3)
- 3: PLUS(6)
- 4: EXACT <o>(0)
- 6: END(0)
-</pre>
-<p>Now we have a special case. The <code>EXACT</code> regop has a
<code>regnext</code> of 0. This is
-because if it matches it should try to match itself again. The
<code>PLUS</code> regop
-handles the actual failure of the <code>EXACT</code> regop and acts
appropriately (going
-to regnode 6 if the <code>EXACT</code> matched at least once, or failing if it
didn’t).
-</p>
-<p>Now for something much more complex:
<code>/x(?:foo*|b[a][rR])(foo|bar)$/</code>
-</p>
-<pre class="verbatim"> >x(?:foo*|b... 1 reg
- brnc
- piec
- atom
- >(?:foo*|b[... 3 piec
- atom
- >?:foo*|b[a... reg
- >foo*|b[a][... brnc
- piec
- atom
- >o*|b[a][rR... 5 piec
- atom
- >|b[a][rR])... 8 tail~ EXACT <fo> (3)
- >b[a][rR])(... 9 brnc
- 10 piec
- atom
- >[a][rR])(f... 12 piec
- atom
- >a][rR])(fo... clas
- >[rR])(foo|... 14 tail~ EXACT <b> (10)
- piec
- atom
- >rR])(foo|b... clas
- >)(foo|bar)... 25 tail~ EXACT <a> (12)
- tail~ BRANCH (3)
- 26 tsdy~ BRANCH (END) (9)
- ~ attach to TAIL (25) offset to 16
- tsdy~ EXACT <fo> (EXACT) (4)
- ~ STAR (END) (6)
- ~ attach to TAIL (25) offset to 19
- tsdy~ EXACT <b> (EXACT) (10)
- ~ EXACT <a> (EXACT) (12)
- ~ ANYOF[Rr] (END) (14)
- ~ attach to TAIL (25) offset to 11
- >(foo|bar)$< tail~ EXACT <x> (1)
- piec
- atom
- >foo|bar)$< reg
- 28 brnc
- piec
- atom
- >|bar)$< 31 tail~ OPEN1 (26)
- >bar)$< brnc
- 32 piec
- atom
- >)$< 34 tail~ BRANCH (28)
- 36 tsdy~ BRANCH (END) (31)
- ~ attach to CLOSE1 (34) offset to 3
- tsdy~ EXACT <foo> (EXACT) (29)
- ~ attach to CLOSE1 (34) offset to 5
- tsdy~ EXACT <bar> (EXACT) (32)
- ~ attach to CLOSE1 (34) offset to 2
- >$< tail~ BRANCH (3)
- ~ BRANCH (9)
- ~ TAIL (25)
- piec
- atom
- >< 37 tail~ OPEN1 (26)
- ~ BRANCH (28)
- ~ BRANCH (31)
- ~ CLOSE1 (34)
- 38 tsdy~ EXACT <x> (EXACT) (1)
- ~ BRANCH (END) (3)
- ~ BRANCH (END) (9)
- ~ TAIL (END) (25)
- ~ OPEN1 (END) (26)
- ~ BRANCH (END) (28)
- ~ BRANCH (END) (31)
- ~ CLOSE1 (END) (34)
- ~ EOL (END) (36)
- ~ attach to END (37) offset to 1
-</pre>
-<p>Resulting in the program
-</p>
-<pre class="verbatim"> 1: EXACT <x>(3)
- 3: BRANCH(9)
- 4: EXACT <fo>(6)
- 6: STAR(26)
- 7: EXACT <o>(0)
- 9: BRANCH(25)
- 10: EXACT <ba>(14)
- 12: OPTIMIZED (2 nodes)
- 14: ANYOF[Rr](26)
- 25: TAIL(26)
- 26: OPEN1(28)
- 28: TRIE-EXACT(34)
- [StS:1 Wds:2 Cs:6 Uq:5 #Sts:7 Mn:3 Mx:3 Stcls:bf]
- <foo>
- <bar>
- 30: OPTIMIZED (4 nodes)
- 34: CLOSE1(36)
- 36: EOL(37)
- 37: END(0)
-</pre>
-<p>Here we can see a much more complex program, with various optimisations in
-play. At regnode 10 we see an example where a character class with only
-one character in it was turned into an <code>EXACT</code> node. We can also
see where
-an entire alternation was turned into a <code>TRIE-EXACT</code> node. As a
consequence,
-some of the regnodes have been marked as optimised away. We can see that
-the <code>$</code> symbol has been converted into an <code>EOL</code> regop, a
special piece of
-code that looks for <code>\n</code> or the end of the string.
-</p>
-<p>The next pointer for <code>BRANCH</code>es is interesting in that it points
at where
-execution should go if the branch fails. When executing, if the engine
-tries to traverse from a branch to a <code>regnext</code> that isn’t a
branch then
-the engine will know that the entire set of branches has failed.
-</p>
-<hr>
-<a name="perlreguts-Peep_002dhole-Optimisation-and-Analysis"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreguts-Debug-Output" accesskey="p"
rel="prev">perlreguts Debug Output</a>, Up: <a href="#perlreguts-Compilation"
accesskey="u" rel="up">perlreguts Compilation</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Peep_002dhole-Optimisation-and-Analysis"></a>
-<h4 class="subsubsection">64.4.1.6 Peep-hole Optimisation and Analysis</h4>
-
-<p>The regular expression engine can be a weighty tool to wield. On long
-strings and complex patterns it can end up having to do a lot of work
-to find a match, and even more to decide that no match is possible.
-Consider a situation like the following pattern.
-</p>
-<pre class="verbatim"> 'ababababababababababab' =~ /(a|b)*z/
-</pre>
-<p>The <code>(a|b)*</code> part can match at every char in the string, and
then fail
-every time because there is no <code>z</code> in the string. So obviously we
can
-avoid using the regex engine unless there is a <code>z</code> in the string.
-Likewise in a pattern like:
-</p>
-<pre class="verbatim"> /foo(\w+)bar/
-</pre>
-<p>In this case we know that the string must contain a <code>foo</code> which
must be
-followed by <code>bar</code>. We can use Fast Boyer-Moore matching as
implemented
-in <code>fbm_instr()</code> to find the location of these strings. If they
don’t exist
-then we don’t need to resort to the much more expensive regex engine.
-Even better, if they do exist then we can use their positions to
-reduce the search space that the regex engine needs to cover to determine
-if the entire pattern matches.
-</p>
-<p>There are various aspects of the pattern that can be used to facilitate
-optimisations along these lines:
-</p>
-<ul>
-<li> anchored fixed strings
-
-</li><li> floating fixed strings
-
-</li><li> minimum and maximum length requirements
-
-</li><li> start class
-
-</li><li> Beginning/End of line positions
-
-</li></ul>
-
-<p>Another form of optimisation that can occur is the post-parse
"peep-hole"
-optimisation, where inefficient constructs are replaced by more efficient
-constructs. The <code>TAIL</code> regops which are used during parsing to mark
the end
-of branches and the end of groups are examples of this. These regops are used
-as place-holders during construction and "always match" so they can
be
-"optimised away" by making the things that point to the
<code>TAIL</code> point to the
-thing that <code>TAIL</code> points to, thus "skipping" the node.
-</p>
-<p>Another optimisation that can occur is that of "<code>EXACT</code>
merging" which is
-where two consecutive <code>EXACT</code> nodes are merged into a single
-regop. An even more aggressive form of this is that a branch
-sequence of the form <code>EXACT BRANCH ... EXACT</code> can be converted into
a
-<code>TRIE-EXACT</code> regop.
-</p>
-<p>All of this occurs in the routine <code>study_chunk()</code> which uses a
special
-structure <code>scan_data_t</code> to store the analysis that it has
performed, and
-does the "peep-hole" optimisations as it goes.
-</p>
-<p>The code involved in <code>study_chunk()</code> is extremely cryptic. Be
careful. :-)
-</p>
-<hr>
-<a name="perlreguts-Execution"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreguts-Compilation" accesskey="p"
rel="prev">perlreguts Compilation</a>, Up: <a
href="#perlreguts-Process-Overview" accesskey="u" rel="up">perlreguts Process
Overview</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Execution"></a>
-<h4 class="subsection">64.4.2 Execution</h4>
-
-<p>Execution of a regex generally involves two phases, the first being
-finding the start point in the string where we should match from,
-and the second being running the regop interpreter.
-</p>
-<p>If we can tell that there is no valid start point then we don’t
bother running
-the interpreter at all. Likewise, if we know from the analysis phase that we
-cannot detect a short-cut to the start position, we go straight to the
-interpreter.
-</p>
-<p>The two entry points are <code>re_intuit_start()</code> and
<code>pregexec()</code>. These routines
-have a somewhat incestuous relationship with overlap between their functions,
-and <code>pregexec()</code> may even call <code>re_intuit_start()</code> on
its own. Nevertheless
-other parts of the perl source code may call into either, or both.
-</p>
-<p>Execution of the interpreter itself used to be recursive, but thanks to the
-efforts of Dave Mitchell in the 5.9.x development track, that has changed: now
an
-internal stack is maintained on the heap and the routine is fully
-iterative. This can make it tricky as the code is quite conservative
-about what state it stores, with the result that two consecutive lines in the
-code can actually be running in totally different contexts due to the
-simulated recursion.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Start-position-and-no_002dmatch-optimisations"
accesskey="1">perlreguts Start position and no-match
optimisations</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Program-execution" accesskey="2">perlreguts Program
execution</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreguts-Start-position-and-no_002dmatch-optimisations"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-Program-execution" accesskey="n"
rel="next">perlreguts Program execution</a>, Up: <a
href="#perlreguts-Execution" accesskey="u" rel="up">perlreguts Execution</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Start-position-and-no_002dmatch-optimisations"></a>
-<h4 class="subsubsection">64.4.2.1 Start position and no-match
optimisations</h4>
-
-<p><code>re_intuit_start()</code> is responsible for handling start points and
no-match
-optimisations as determined by the results of the analysis done by
-<code>study_chunk()</code> (and described in <a
href="#perlreguts-Peep_002dhole-Optimisation-and-Analysis">Peep-hole
Optimisation and Analysis</a>).
-</p>
-<p>The basic structure of this routine is to try to find the start- and/or
-end-points of where the pattern could match, and to ensure that the string
-is long enough to match the pattern. It tries to use more efficient
-methods over less efficient methods and may involve considerable
-cross-checking of constraints to find the place in the string that matches.
-For instance it may try to determine that a given fixed string must be
-not only present but a certain number of chars before the end of the
-string, or whatever.
-</p>
-<p>It calls several other routines, such as <code>fbm_instr()</code> which does
-Fast Boyer Moore matching and <code>find_byclass()</code> which is responsible
for
-finding the start using the first mandatory regop in the program.
-</p>
-<p>When the optimisation criteria have been satisfied, <code>reg_try()</code>
is called
-to perform the match.
-</p>
-<hr>
-<a name="perlreguts-Program-execution"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreguts-Start-position-and-no_002dmatch-optimisations"
accesskey="p" rel="prev">perlreguts Start position and no-match
optimisations</a>, Up: <a href="#perlreguts-Execution" accesskey="u"
rel="up">perlreguts Execution</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Program-execution"></a>
-<h4 class="subsubsection">64.4.2.2 Program execution</h4>
-
-<p><code>pregexec()</code> is the main entry point for running a regex. It
contains
-support for initialising the regex interpreter’s state, running
-<code>re_intuit_start()</code> if needed, and running the interpreter on the
string
-from various start positions as needed. When it is necessary to use
-the regex interpreter <code>pregexec()</code> calls <code>regtry()</code>.
-</p>
-<p><code>regtry()</code> is the entry point into the regex interpreter. It
expects
-as arguments a pointer to a <code>regmatch_info</code> structure and a pointer
to
-a string. It returns an integer 1 for success and a 0 for failure.
-It is basically a set-up wrapper around <code>regmatch()</code>.
-</p>
-<p><code>regmatch</code> is the main "recursive loop" of the
interpreter. It is
-basically a giant switch statement that implements a state machine, where
-the possible states are the regops themselves, plus a number of additional
-intermediate and failure states. A few of the states are implemented as
-subroutines but the bulk are inline code.
-</p>
-<hr>
-<a name="perlreguts-MISCELLANEOUS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-SEE-ALSO" accesskey="n" rel="next">perlreguts SEE
ALSO</a>, Previous: <a href="#perlreguts-Process-Overview" accesskey="p"
rel="prev">perlreguts Process Overview</a>, Up: <a href="#perlreguts"
accesskey="u" rel="up">perlreguts</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="MISCELLANEOUS"></a>
-<h3 class="section">64.5 MISCELLANEOUS</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Unicode-and-Localisation-Support" accesskey="1">perlreguts
Unicode and Localisation Support</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreguts-Base-Structures"
accesskey="2">perlreguts Base Structures</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreguts-Unicode-and-Localisation-Support"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-Base-Structures" accesskey="n"
rel="next">perlreguts Base Structures</a>, Up: <a
href="#perlreguts-MISCELLANEOUS" accesskey="u" rel="up">perlreguts
MISCELLANEOUS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-and-Localisation-Support"></a>
-<h4 class="subsection">64.5.1 Unicode and Localisation Support</h4>
-
-<p>When dealing with strings containing characters that cannot be represented
-using an eight-bit character set, perl uses an internal representation
-that is a permissive version of Unicode’s UTF-8 encoding[2]. This uses
single
-bytes to represent characters from the ASCII character set, and sequences
-of two or more bytes for all other characters. (See <a
href="#perlunitut-NAME">perlunitut NAME</a>
-for more information about the relationship between UTF-8 and perl’s
-encoding, utf8. The difference isn’t important for this discussion.)
-</p>
-<p>No matter how you look at it, Unicode support is going to be a pain in a
-regex engine. Tricks that might be fine when you have 256 possible
-characters often won’t scale to handle the size of the UTF-8 character
-set. Things you can take for granted with ASCII may not be true with
-Unicode. For instance, in ASCII, it is safe to assume that
-<code>sizeof(char1) == sizeof(char2)</code>, but in UTF-8 it isn’t.
Unicode case folding is
-vastly more complex than the simple rules of ASCII, and even when not
-using Unicode but only localised single byte encodings, things can get
-tricky (for example, <strong>LATIN SMALL LETTER SHARP S</strong> (U+00DF, ÃÂ)
-should match ’SS’ in localised case-insensitive matching).
-</p>
-<p>Making things worse is that UTF-8 support was a later addition to the
-regex engine (as it was to perl) and this necessarily made things a lot
-more complicated. Obviously it is easier to design a regex engine with
-Unicode support in mind from the beginning than it is to retrofit it to
-one that wasn’t.
-</p>
-<p>Nearly all regops that involve looking at the input string have
-two cases, one for UTF-8, and one not. In fact, it’s often more complex
-than that, as the pattern may be UTF-8 as well.
-</p>
-<p>Care must be taken when making changes to make sure that you handle
-UTF-8 properly, both at compile time and at execution time, including
-when the string and pattern are mismatched.
-</p>
-<hr>
-<a name="perlreguts-Base-Structures"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreguts-Unicode-and-Localisation-Support" accesskey="p"
rel="prev">perlreguts Unicode and Localisation Support</a>, Up: <a
href="#perlreguts-MISCELLANEOUS" accesskey="u" rel="up">perlreguts
MISCELLANEOUS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Base-Structures"></a>
-<h4 class="subsection">64.5.2 Base Structures</h4>
-
-<p>The <code>regexp</code> structure described in <a
href="#perlreapi-NAME">perlreapi NAME</a> is common to all
-regex engines. Two of its fields are intended for the private use
-of the regex engine that compiled the pattern. These are the
-<code>intflags</code> and pprivate members. The <code>pprivate</code> is a
void pointer to
-an arbitrary structure whose use and management is the responsibility
-of the compiling engine. perl will never modify either of these
-values. In the case of the stock engine the structure pointed to by
-<code>pprivate</code> is called <code>regexp_internal</code>.
-</p>
-<p>Its <code>pprivate</code> and <code>intflags</code> fields contain data
-specific to each engine.
-</p>
-<p>There are two structures used to store a compiled regular expression.
-One, the <code>regexp</code> structure described in <a
href="#perlreapi-NAME">perlreapi NAME</a> is populated by
-the engine currently being. used and some of its fields read by perl to
-implement things such as the stringification of <code>qr//</code>.
-</p>
-<p>The other structure is pointed to by the <code>regexp</code> struct’s
-<code>pprivate</code> and is in addition to <code>intflags</code> in the same
struct
-considered to be the property of the regex engine which compiled the
-regular expression;
-</p>
-<p>The regexp structure contains all the data that perl needs to be aware of
-to properly work with the regular expression. It includes data about
-optimisations that perl can use to determine if the regex engine should
-really be used, and various other control info that is needed to properly
-execute patterns in various contexts such as is the pattern anchored in
-some way, or what flags were used during the compile, or whether the
-program contains special constructs that perl needs to be aware of.
-</p>
-<p>In addition it contains two fields that are intended for the private use
-of the regex engine that compiled the pattern. These are the
<code>intflags</code>
-and pprivate members. The <code>pprivate</code> is a void pointer to an
arbitrary
-structure whose use and management is the responsibility of the compiling
-engine. perl will never modify either of these values.
-</p>
-<p>As mentioned earlier, in the case of the default engines, the
<code>pprivate</code>
-will be a pointer to a regexp_internal structure which holds the compiled
-program and any additional data that is private to the regex engine
-implementation.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlreguts-Perl_0027s-pprivate-structure" accesskey="1">perlreguts
Perl's <code>pprivate</code> structure</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreguts-Perl_0027s-pprivate-structure"></a>
-<div class="header">
-<p>
-Up: <a href="#perlreguts-Base-Structures" accesskey="u" rel="up">perlreguts
Base Structures</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Perl_0027s-pprivate-structure"></a>
-<h4 class="subsubsection">64.5.2.1 Perl’s <code>pprivate</code>
structure</h4>
-
-<p>The following structure is used as the <code>pprivate</code> struct by
perl’s
-regex engine. Since it is specific to perl it is only of curiosity
-value to other engine implementations.
-</p>
-<pre class="verbatim"> typedef struct regexp_internal {
- U32 *offsets; /* offset annotations 20001228 MJD
- * data about mapping the program to
- * the string*/
- regnode *regstclass; /* Optional startclass as identified or
- * constructed by the optimiser */
- struct reg_data *data; /* Additional miscellaneous data used
- * by the program. Used to make it
- * easier to clone and free arbitrary
- * data that the regops need. Often the
- * ARG field of a regop is an index
- * into this structure */
- regnode program[1]; /* Unwarranted chumminess with
- * compiler. */
- } regexp_internal;
-</pre>
-<dl compact="compact">
-<dt><code>offsets</code></dt>
-<dd><a name="perlreguts-offsets"></a>
-<p>Offsets holds a mapping of offset in the <code>program</code>
-to offset in the <code>precomp</code> string. This is only used by
ActiveState’s
-visual regex debugger.
-</p>
-</dd>
-<dt><code>regstclass</code></dt>
-<dd><a name="perlreguts-regstclass"></a>
-<p>Special regop that is used by <code>re_intuit_start()</code> to check if a
pattern
-can match at a certain position. For instance if the regex engine knows
-that the pattern must start with a ’Z’ then it can scan the string
until
-it finds one and then launch the regex engine from there. The routine
-that handles this is called <code>find_by_class()</code>. Sometimes this field
-points at a regop embedded in the program, and sometimes it points at
-an independent synthetic regop that has been constructed by the optimiser.
-</p>
-</dd>
-<dt><code>data</code></dt>
-<dd><a name="perlreguts-data"></a>
-<p>This field points at a <code>reg_data</code> structure, which is defined as
follows
-</p>
-<pre class="verbatim"> struct reg_data {
- U32 count;
- U8 *what;
- void* data[1];
- };
-</pre>
-<p>This structure is used for handling data structures that the regex engine
-needs to handle specially during a clone or free operation on the compiled
-product. Each element in the data array has a corresponding element in the
-what array. During compilation regops that need special structures stored
-will add an element to each array using the add_data() routine and then store
-the index in the regop.
-</p>
-</dd>
-<dt><code>program</code></dt>
-<dd><a name="perlreguts-program"></a>
-<p>Compiled program. Inlined into the structure so the entire struct can be
-treated as a single blob.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlreguts-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-AUTHOR" accesskey="n" rel="next">perlreguts
AUTHOR</a>, Previous: <a href="#perlreguts-MISCELLANEOUS" accesskey="p"
rel="prev">perlreguts MISCELLANEOUS</a>, Up: <a href="#perlreguts"
accesskey="u" rel="up">perlreguts</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-32"></a>
-<h3 class="section">64.6 SEE ALSO</h3>
-
-<p><a href="#perlreapi-NAME">perlreapi NAME</a>
-</p>
-<p><a href="#perlre-NAME">perlre NAME</a>
-</p>
-<p><a href="#perlunitut-NAME">perlunitut NAME</a>
-</p>
-<hr>
-<a name="perlreguts-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-LICENCE" accesskey="n" rel="next">perlreguts
LICENCE</a>, Previous: <a href="#perlreguts-SEE-ALSO" accesskey="p"
rel="prev">perlreguts SEE ALSO</a>, Up: <a href="#perlreguts" accesskey="u"
rel="up">perlreguts</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-25"></a>
-<h3 class="section">64.7 AUTHOR</h3>
-
-<p>by Yves Orton, 2006.
-</p>
-<p>With excerpts from Perl, and contributions and suggestions from
-Ronald J. Kimball, Dave Mitchell, Dominic Dunlop, Mark Jason Dominus,
-Stephen McCamant, and David Landgren.
-</p>
-<hr>
-<a name="perlreguts-LICENCE"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreguts-REFERENCES" accesskey="n" rel="next">perlreguts
REFERENCES</a>, Previous: <a href="#perlreguts-AUTHOR" accesskey="p"
rel="prev">perlreguts AUTHOR</a>, Up: <a href="#perlreguts" accesskey="u"
rel="up">perlreguts</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="LICENCE"></a>
-<h3 class="section">64.8 LICENCE</h3>
-
-<p>Same terms as Perl.
-</p>
-<hr>
-<a name="perlreguts-REFERENCES"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreguts-LICENCE" accesskey="p" rel="prev">perlreguts
LICENCE</a>, Up: <a href="#perlreguts" accesskey="u" rel="up">perlreguts</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="REFERENCES-3"></a>
-<h3 class="section">64.9 REFERENCES</h3>
-
-<p>[1] <a
href="http://perl.plover.com/Rx/paper/";>http://perl.plover.com/Rx/paper/</a>
-</p>
-<p>[2] <a href="http://www.unicode.org";>http://www.unicode.org</a>
-</p>
-<hr>
-<a name="perlrepository"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick" accesskey="n" rel="next">perlrequick</a>,
Previous: <a href="#perlreguts" accesskey="p" rel="prev">perlreguts</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlrepository-1"></a>
-<h2 class="chapter">65 perlrepository</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlrepository-NAME"
accesskey="1">perlrepository NAME</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrepository-DESCRIPTION"
accesskey="2">perlrepository DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrepository-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrepository-DESCRIPTION" accesskey="n"
rel="next">perlrepository DESCRIPTION</a>, Up: <a href="#perlrepository"
accesskey="u" rel="up">perlrepository</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-64"></a>
-<h3 class="section">65.1 NAME</h3>
-
-<p>perlrepository - Links to current information on the Perl source repository
-</p>
-<hr>
-<a name="perlrepository-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlrepository-NAME" accesskey="p"
rel="prev">perlrepository NAME</a>, Up: <a href="#perlrepository" accesskey="u"
rel="up">perlrepository</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-63"></a>
-<h3 class="section">65.2 DESCRIPTION</h3>
-
-<p>Perl’s source code is stored in a Git repository.
-</p>
-<p>See <a href="#perlhack-NAME">perlhack NAME</a> for an explanation of Perl
development, including the
-<a href="#perlhack-SUPER-QUICK-PATCH-GUIDE">Super Quick Patch Guide</a> for
making and
-submitting a small patch.
-</p>
-<p>See <a href="#perlgit-NAME">perlgit NAME</a> for detailed information about
Perl’s Git repository.
-</p>
-<p>(The above documents supersede the information that was formerly here in
-perlrepository.)
-</p>
-<hr>
-<a name="perlrequick"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref" accesskey="n" rel="next">perlreref</a>, Previous:
<a href="#perlrepository" accesskey="p" rel="prev">perlrepository</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlrequick-1"></a>
-<h2 class="chapter">66 perlrequick</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlrequick-NAME"
accesskey="1">perlrequick NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrequick-DESCRIPTION"
accesskey="2">perlrequick DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrequick-The-Guide"
accesskey="3">perlrequick The Guide</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrequick-BUGS"
accesskey="4">perlrequick BUGS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrequick-SEE-ALSO"
accesskey="5">perlrequick SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-AUTHOR-AND-COPYRIGHT" accesskey="6">perlrequick AUTHOR AND
COPYRIGHT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrequick-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick-DESCRIPTION" accesskey="n" rel="next">perlrequick
DESCRIPTION</a>, Up: <a href="#perlrequick" accesskey="u"
rel="up">perlrequick</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-65"></a>
-<h3 class="section">66.1 NAME</h3>
-
-<p>perlrequick - Perl regular expressions quick start
-</p>
-<hr>
-<a name="perlrequick-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick-The-Guide" accesskey="n" rel="next">perlrequick
The Guide</a>, Previous: <a href="#perlrequick-NAME" accesskey="p"
rel="prev">perlrequick NAME</a>, Up: <a href="#perlrequick" accesskey="u"
rel="up">perlrequick</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-64"></a>
-<h3 class="section">66.2 DESCRIPTION</h3>
-
-<p>This page covers the very basics of understanding, creating and
-using regular expressions (’regexes’) in Perl.
-</p>
-<hr>
-<a name="perlrequick-The-Guide"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick-BUGS" accesskey="n" rel="next">perlrequick
BUGS</a>, Previous: <a href="#perlrequick-DESCRIPTION" accesskey="p"
rel="prev">perlrequick DESCRIPTION</a>, Up: <a href="#perlrequick"
accesskey="u" rel="up">perlrequick</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-Guide"></a>
-<h3 class="section">66.3 The Guide</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlrequick-Simple-word-matching" accesskey="1">perlrequick Simple word
matching</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-Using-character-classes" accesskey="2">perlrequick Using
character classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-Matching-this-or-that" accesskey="3">perlrequick Matching
this or that</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-Grouping-things-and-hierarchical-matching"
accesskey="4">perlrequick Grouping things and hierarchical
matching</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-Extracting-matches" accesskey="5">perlrequick Extracting
matches</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-Matching-repetitions" accesskey="6">perlrequick Matching
repetitions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrequick-More-matching"
accesskey="7">perlrequick More matching</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-Search-and-replace" accesskey="8">perlrequick Search and
replace</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-The-split-operator" accesskey="9">perlrequick The split
operator</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlrequick-use-re-_0027strict_0027">perlrequick <code>use re
'strict'</code></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrequick-Simple-word-matching"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick-Using-character-classes" accesskey="n"
rel="next">perlrequick Using character classes</a>, Up: <a
href="#perlrequick-The-Guide" accesskey="u" rel="up">perlrequick The Guide</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Simple-word-matching"></a>
-<h4 class="subsection">66.3.1 Simple word matching</h4>
-
-<p>The simplest regex is simply a word, or more generally, a string of
-characters. A regex consisting of a word matches any string that
-contains that word:
-</p>
-<pre class="verbatim"> "Hello World" =~ /World/; # matches
-</pre>
-<p>In this statement, <code>World</code> is a regex and the <code>//</code>
enclosing
-<code>/World/</code> tells Perl to search a string for a match. The operator
-<code>=~</code> 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, <code>World</code> matches the second word in <code>"Hello
World"</code>, so the
-expression is true. This idea has several variations.
-</p>
-<p>Expressions like this are useful in conditionals:
-</p>
-<pre class="verbatim"> print "It matches\n" if "Hello
World" =~ /World/;
-</pre>
-<p>The sense of the match can be reversed by using <code>!~</code> operator:
-</p>
-<pre class="verbatim"> print "It doesn't match\n" if "Hello
World" !~ /World/;
-</pre>
-<p>The literal string in the regex can be replaced by a variable:
-</p>
-<pre class="verbatim"> $greeting = "World";
- print "It matches\n" if "Hello World" =~ /$greeting/;
-</pre>
-<p>If you’re matching against <code>$_</code>, the <code>$_ =~</code>
part can be omitted:
-</p>
-<pre class="verbatim"> $_ = "Hello World";
- print "It matches\n" if /World/;
-</pre>
-<p>Finally, the <code>//</code> default delimiters for a match can be changed
to
-arbitrary delimiters by putting an <code>'m'</code> out front:
-</p>
-<pre class="verbatim"> "Hello World" =~ m!World!; # matches,
delimited by '!'
- "Hello World" =~ m{World}; # matches, note the matching '{}'
- "/usr/bin/perl" =~ m"/perl"; # matches after
'/usr/bin',
- # '/' becomes an ordinary char
-</pre>
-<p>Regexes must match a part of the string <em>exactly</em> in order for the
-statement to be true:
-</p>
-<pre class="verbatim"> "Hello World" =~ /world/; # doesn't
match, case sensitive
- "Hello World" =~ /o W/; # matches, ' ' is an ordinary char
- "Hello World" =~ /World /; # doesn't match, no ' ' at end
-</pre>
-<p>Perl will always match at the earliest possible point in the string:
-</p>
-<pre class="verbatim"> "Hello World" =~ /o/; # matches 'o'
in 'Hello'
- "That hat is red" =~ /hat/; # matches 'hat' in 'That'
-</pre>
-<p>Not all characters can be used ’as is’ in a match. Some
characters,
-called <strong>metacharacters</strong>, are reserved for use in regex notation.
-The metacharacters are
-</p>
-<pre class="verbatim"> {}[]()^$.|*+?\
-</pre>
-<p>A metacharacter can be matched by putting a backslash before it:
-</p>
-<pre class="verbatim"> "2+2=4" =~ /2+2/; # doesn't match, + is
a metacharacter
- "2+2=4" =~ /2\+2/; # matches, \+ is treated like an ordinary +
- 'C:\WIN32' =~ /C:\\WIN/; # matches
- "/usr/bin/perl" =~ /\/usr\/bin\/perl/; # matches
-</pre>
-<p>In the last regex, the forward slash <code>'/'</code> is also backslashed,
-because it is used to delimit the regex.
-</p>
-<p>Non-printable ASCII characters are represented by <strong>escape
sequences</strong>.
-Common examples are <code>\t</code> for a tab, <code>\n</code> for a newline,
and <code>\r</code>
-for a carriage return. Arbitrary bytes are represented by octal
-escape sequences, e.g., <code>\033</code>, or hexadecimal escape sequences,
-e.g., <code>\x1B</code>:
-</p>
-<pre class="verbatim"> "1000\t2000" =~ m(0\t2) # matches
- "cat" =~ /\143\x61\x74/ # matches in ASCII, but
- # a weird way to spell cat
-</pre>
-<p>Regexes are treated mostly as double-quoted strings, so variable
-substitution works:
-</p>
-<pre class="verbatim"> $foo = 'house';
- 'cathouse' =~ /cat$foo/; # matches
- 'housecat' =~ /${foo}cat/; # matches
-</pre>
-<p>With all of the regexes above, if the regex matched anywhere in the
-string, it was considered a match. To specify <em>where</em> it should
-match, we would use the <strong>anchor</strong> metacharacters <code>^</code>
and <code>$</code>. The
-anchor <code>^</code> means match at the beginning of the string and the anchor
-<code>$</code> means match at the end of the string, or before a newline at the
-end of the string. Some examples:
-</p>
-<pre class="verbatim"> "housekeeper" =~ /keeper/; #
matches
- "housekeeper" =~ /^keeper/; # doesn't match
- "housekeeper" =~ /keeper$/; # matches
- "housekeeper\n" =~ /keeper$/; # matches
- "housekeeper" =~ /^housekeeper$/; # matches
-</pre>
-<hr>
-<a name="perlrequick-Using-character-classes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick-Matching-this-or-that" accesskey="n"
rel="next">perlrequick Matching this or that</a>, Previous: <a
href="#perlrequick-Simple-word-matching" accesskey="p" rel="prev">perlrequick
Simple word matching</a>, Up: <a href="#perlrequick-The-Guide" accesskey="u"
rel="up">perlrequick The Guide</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-character-classes"></a>
-<h4 class="subsection">66.3.2 Using character classes</h4>
-
-<p>A <strong>character class</strong> allows a set of possible characters,
rather than
-just a single character, to match at a particular point in a regex.
-Character classes are denoted by brackets <code>[...]</code>, with the set of
-characters to be possibly matched inside. Here are some examples:
-</p>
-<pre class="verbatim"> /cat/; # matches 'cat'
- /[bcr]at/; # matches 'bat', 'cat', or 'rat'
- "abc" =~ /[cab]/; # matches 'a'
-</pre>
-<p>In the last statement, even though <code>'c'</code> is the first character
in
-the class, the earliest point at which the regex can match is <code>'a'</code>.
-</p>
-<pre class="verbatim"> /[yY][eE][sS]/; # match 'yes' in a case-insensitive
way
- # 'yes', 'Yes', 'YES', etc.
- /yes/i; # also match 'yes' in a case-insensitive way
-</pre>
-<p>The last example shows a match with an <code>'i'</code>
<strong>modifier</strong>, which makes
-the match case-insensitive.
-</p>
-<p>Character classes also have ordinary and special characters, but the
-sets of ordinary and special characters inside a character class are
-different than those outside a character class. The special
-characters for a character class are <code>-]\^$</code> and are matched using
an
-escape:
-</p>
-<pre class="verbatim"> /[\]c]def/; # matches ']def' or 'cdef'
- $x = 'bcr';
- /[$x]at/; # matches 'bat, 'cat', or 'rat'
- /[\$x]at/; # matches '$at' or 'xat'
- /[\\$x]at/; # matches '\at', 'bat, 'cat', or 'rat'
-</pre>
-<p>The special character <code>'-'</code> acts as a range operator within
character
-classes, so that the unwieldy <code>[0123456789]</code> and
<code>[abc...xyz]</code>
-become the svelte <code>[0-9]</code> and <code>[a-z]</code>:
-</p>
-<pre class="verbatim"> /item[0-9]/; # matches 'item0' or ... or 'item9'
- /[0-9a-fA-F]/; # matches a hexadecimal digit
-</pre>
-<p>If <code>'-'</code> is the first or last character in a character class, it
is
-treated as an ordinary character.
-</p>
-<p>The special character <code>^</code> in the first position of a character
class
-denotes a <strong>negated character class</strong>, which matches any
character but
-those in the brackets. Both <code>[...]</code> and <code>[^...]</code> must
match a
-character, or the match fails. Then
-</p>
-<pre class="verbatim"> /[^a]at/; # doesn't match 'aat' or 'at', but matches
- # all other 'bat', 'cat, '0at', '%at', etc.
- /[^0-9]/; # matches a non-numeric character
- /[a^]at/; # matches 'aat' or '^at'; here '^' is ordinary
-</pre>
-<p>Perl has several abbreviations for common character classes. (These
-definitions are those that Perl uses in ASCII-safe mode with the
<code>/a</code> modifier.
-Otherwise they could match many more non-ASCII Unicode characters as
-well. See <a href="#perlrecharclass-Backslash-sequences">perlrecharclass
Backslash sequences</a> for details.)
-</p>
-<ul>
-<li> \d is a digit and represents
-
-<pre class="verbatim"> [0-9]
-</pre>
-</li><li> \s is a whitespace character and represents
-
-<pre class="verbatim"> [\ \t\r\n\f]
-</pre>
-</li><li> \w is a word character (alphanumeric or _) and represents
-
-<pre class="verbatim"> [0-9a-zA-Z_]
-</pre>
-</li><li> \D is a negated \d; it represents any character but a digit
-
-<pre class="verbatim"> [^0-9]
-</pre>
-</li><li> \S is a negated \s; it represents any non-whitespace character
-
-<pre class="verbatim"> [^\s]
-</pre>
-</li><li> \W is a negated \w; it represents any non-word character
-
-<pre class="verbatim"> [^\w]
-</pre>
-</li><li> The period ’.’ matches any character but "\n"
-
-</li></ul>
-
-<p>The <code>\d\s\w\D\S\W</code> abbreviations can be used both inside and
outside
-of character classes. Here are some in use:
-</p>
-<pre class="verbatim"> /\d\d:\d\d:\d\d/; # matches a hh:mm:ss time format
- /[\d\s]/; # matches any digit or whitespace character
- /\w\W\w/; # matches a word char, followed by a
- # non-word char, followed by a word char
- /..rt/; # matches any two chars, followed by 'rt'
- /end\./; # matches 'end.'
- /end[.]/; # same thing, matches 'end.'
-</pre>
-<p>The <strong>word anchor</strong> <!-- /@w --> <code>\b</code>
matches a boundary between a word
-character and a non-word character <code>\w\W</code> or <code>\W\w</code>:
-</p>
-<pre class="verbatim"> $x = "Housecat catenates house and cat";
- $x =~ /\bcat/; # matches cat in 'catenates'
- $x =~ /cat\b/; # matches cat in 'housecat'
- $x =~ /\bcat\b/; # matches 'cat' at end of string
-</pre>
-<p>In the last example, the end of the string is considered a word
-boundary.
-</p>
-<p>For natural language processing (so that, for example, apostrophes are
-included in words), use instead <code>\b{wb}</code>
-</p>
-<pre class="verbatim"> "don't" =~ / .+? \b{wb} /x; # matches the
whole string
-</pre>
-<hr>
-<a name="perlrequick-Matching-this-or-that"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick-Grouping-things-and-hierarchical-matching"
accesskey="n" rel="next">perlrequick Grouping things and hierarchical
matching</a>, Previous: <a href="#perlrequick-Using-character-classes"
accesskey="p" rel="prev">perlrequick Using character classes</a>, Up: <a
href="#perlrequick-The-Guide" accesskey="u" rel="up">perlrequick The Guide</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Matching-this-or-that"></a>
-<h4 class="subsection">66.3.3 Matching this or that</h4>
-
-<p>We can match different character strings with the
<strong>alternation</strong>
-metacharacter <code>'|'</code>. To match <code>dog</code> or
<code>cat</code>, we form the regex
-<code>dog|cat</code>. 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, <code>dog</code>. If
-<code>dog</code> doesn’t match, Perl will then try the next alternative,
<code>cat</code>.
-If <code>cat</code> doesn’t match either, then the match fails and Perl
moves to
-the next position in the string. Some examples:
-</p>
-<pre class="verbatim"> "cats and dogs" =~ /cat|dog|bird/; #
matches "cat"
- "cats and dogs" =~ /dog|cat|bird/; # matches "cat"
-</pre>
-<p>Even though <code>dog</code> is the first alternative in the second regex,
-<code>cat</code> is able to match earlier in the string.
-</p>
-<pre class="verbatim"> "cats" =~ /c|ca|cat|cats/; #
matches "c"
- "cats" =~ /cats|cat|ca|c/; # matches "cats"
-</pre>
-<p>At a given character position, the first alternative that allows the
-regex match to succeed will be the one that matches. Here, all the
-alternatives match at the first string position, so the first matches.
-</p>
-<hr>
-<a name="perlrequick-Grouping-things-and-hierarchical-matching"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick-Extracting-matches" accesskey="n"
rel="next">perlrequick Extracting matches</a>, Previous: <a
href="#perlrequick-Matching-this-or-that" accesskey="p" rel="prev">perlrequick
Matching this or that</a>, Up: <a href="#perlrequick-The-Guide" accesskey="u"
rel="up">perlrequick The Guide</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Grouping-things-and-hierarchical-matching"></a>
-<h4 class="subsection">66.3.4 Grouping things and hierarchical matching</h4>
-
-<p>The <strong>grouping</strong> metacharacters <code>()</code> allow a part
of a regex to be
-treated as a single unit. Parts of a regex are grouped by enclosing
-them in parentheses. The regex <code>house(cat|keeper)</code> means match
-<code>house</code> followed by either <code>cat</code> or <code>keeper</code>.
Some more examples
-are
-</p>
-<pre class="verbatim"> /(a|b)b/; # matches 'ab' or 'bb'
- /(^a|b)c/; # matches 'ac' at start of string or 'bc' anywhere
-
- /house(cat|)/; # matches either 'housecat' or 'house'
- /house(cat(s|)|)/; # matches either 'housecats' or 'housecat' or
- # 'house'. Note groups can be nested.
-
- "20" =~ /(19|20|)\d\d/; # matches the null alternative '()\d\d',
- # because '20\d\d' can't match
-</pre>
-<hr>
-<a name="perlrequick-Extracting-matches"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick-Matching-repetitions" accesskey="n"
rel="next">perlrequick Matching repetitions</a>, Previous: <a
href="#perlrequick-Grouping-things-and-hierarchical-matching" accesskey="p"
rel="prev">perlrequick Grouping things and hierarchical matching</a>, Up: <a
href="#perlrequick-The-Guide" accesskey="u" rel="up">perlrequick The Guide</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Extracting-matches"></a>
-<h4 class="subsection">66.3.5 Extracting matches</h4>
-
-<p>The grouping metacharacters <code>()</code> also allow the extraction of the
-parts of a string that matched. For each grouping, the part that
-matched inside goes into the special variables <code>$1</code>,
<code>$2</code>, etc.
-They can be used just as ordinary variables:
-</p>
-<pre class="verbatim"> # extract hours, minutes, seconds
- $time =~ /(\d\d):(\d\d):(\d\d)/; # match hh:mm:ss format
- $hours = $1;
- $minutes = $2;
- $seconds = $3;
-</pre>
-<p>In list context, a match <code>/regex/</code> with groupings will return the
-list of matched values <code>($1,$2,...)</code>. So we could rewrite it as
-</p>
-<pre class="verbatim"> ($hours, $minutes, $second) = ($time =~
/(\d\d):(\d\d):(\d\d)/);
-</pre>
-<p>If the groupings in a regex are nested, <code>$1</code> gets the group with
the
-leftmost opening parenthesis, <code>$2</code> the next opening parenthesis,
-etc. For example, here is a complex regex and the matching variables
-indicated below it:
-</p>
-<pre class="verbatim"> /(ab(cd|ef)((gi)|j))/;
- 1 2 34
-</pre>
-<p>Associated with the matching variables <code>$1</code>, <code>$2</code>,
... are
-the <strong>backreferences</strong> <code>\g1</code>, <code>\g2</code>, ...
Backreferences are
-matching variables that can be used <em>inside</em> a regex:
-</p>
-<pre class="verbatim"> /(\w\w\w)\s\g1/; # find sequences like 'the the' in
string
-</pre>
-<p><code>$1</code>, <code>$2</code>, ... should only be used outside of a
regex, and <code>\g1</code>,
-<code>\g2</code>, ... only inside a regex.
-</p>
-<hr>
-<a name="perlrequick-Matching-repetitions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick-More-matching" accesskey="n"
rel="next">perlrequick More matching</a>, Previous: <a
href="#perlrequick-Extracting-matches" accesskey="p" rel="prev">perlrequick
Extracting matches</a>, Up: <a href="#perlrequick-The-Guide" accesskey="u"
rel="up">perlrequick The Guide</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Matching-repetitions"></a>
-<h4 class="subsection">66.3.6 Matching repetitions</h4>
-
-<p>The <strong>quantifier</strong> metacharacters <code>?</code>,
<code>*</code>, <code>+</code>, and <code>{}</code> allow us
-to determine the number of repeats of a portion of a regex we
-consider to be a match. Quantifiers are put immediately after the
-character, character class, or grouping that we want to specify. They
-have the following meanings:
-</p>
-<ul>
-<li> <code>a?</code> = match ’a’ 1 or 0 times
-
-</li><li> <code>a*</code> = match ’a’ 0 or more times, i.e., any
number of times
-
-</li><li> <code>a+</code> = match ’a’ 1 or more times, i.e., at
least once
-
-</li><li> <code>a{n,m}</code> = match at least <code>n</code> times, but not
more than <code>m</code>
-times.
-
-</li><li> <code>a{n,}</code> = match at least <code>n</code> or more times
-
-</li><li> <code>a{n}</code> = match exactly <code>n</code> times
-
-</li></ul>
-
-<p>Here are some examples:
-</p>
-<pre class="verbatim"> /[a-z]+\s+\d*/; # match a lowercase word, at least
some space, and
- # any number of digits
- /(\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
-</pre>
-<p>These quantifiers will try to match as much of the string as possible,
-while still allowing the regex to match. So we have
-</p>
-<pre class="verbatim"> $x = 'the cat in the hat';
- $x =~ /^(.*)(at)(.*)$/; # matches,
- # $1 = 'the cat in the h'
- # $2 = 'at'
- # $3 = '' (0 matches)
-</pre>
-<p>The first quantifier <code>.*</code> grabs as much of the string as possible
-while still having the regex match. The second quantifier <code>.*</code> has
-no string left to it, so it matches 0 times.
-</p>
-<hr>
-<a name="perlrequick-More-matching"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick-Search-and-replace" accesskey="n"
rel="next">perlrequick Search and replace</a>, Previous: <a
href="#perlrequick-Matching-repetitions" accesskey="p" rel="prev">perlrequick
Matching repetitions</a>, Up: <a href="#perlrequick-The-Guide" accesskey="u"
rel="up">perlrequick The Guide</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="More-matching"></a>
-<h4 class="subsection">66.3.7 More matching</h4>
-
-<p>There are a few more things you might want to know about matching
-operators.
-The global modifier <code>//g</code> allows the matching operator to match
-within a string as many times as possible. In scalar context,
-successive matches against a string will have <code>//g</code> 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 <code>pos()</code> function.
-For example,
-</p>
-<pre class="verbatim"> $x = "cat dog house"; # 3 words
- while ($x =~ /(\w+)/g) {
- print "Word is $1, ends at position ", pos $x,
"\n";
- }
-</pre>
-<p>prints
-</p>
-<pre class="verbatim"> Word is cat, ends at position 3
- Word is dog, ends at position 7
- Word is house, ends at position 13
-</pre>
-<p>A failed match or changing the target string resets the position. If
-you don’t want the position reset after failure to match, add the
-<code>//c</code>, as in <code>/regex/gc</code>.
-</p>
-<p>In list context, <code>//g</code> returns a list of matched groupings, or if
-there are no groupings, a list of matches to the whole regex. So
-</p>
-<pre class="verbatim"> @words = ($x =~ /(\w+)/g); # matches,
- # $word[0] = 'cat'
- # $word[1] = 'dog'
- # $word[2] = 'house'
-</pre>
-<hr>
-<a name="perlrequick-Search-and-replace"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick-The-split-operator" accesskey="n"
rel="next">perlrequick The split operator</a>, Previous: <a
href="#perlrequick-More-matching" accesskey="p" rel="prev">perlrequick More
matching</a>, Up: <a href="#perlrequick-The-Guide" accesskey="u"
rel="up">perlrequick The Guide</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Search-and-replace"></a>
-<h4 class="subsection">66.3.8 Search and replace</h4>
-
-<p>Search and replace is performed using
<code>s/regex/replacement/modifiers</code>.
-The <code>replacement</code> is a Perl double-quoted string that replaces in
the
-string whatever is matched with the <code>regex</code>. The operator
<code>=~</code> is
-also used here to associate a string with <code>s///</code>. If matching
-against <code>$_</code>, the <code><span
class="nolinebreak">$_</span> =~</code><!-- /@w --> can be dropped. If
there is a match,
-<code>s///</code> returns the number of substitutions made; otherwise it
returns
-false. Here are a few examples:
-</p>
-<pre class="verbatim"> $x = "Time to feed the cat!";
- $x =~ s/cat/hacker/; # $x contains "Time to feed the hacker!"
- $y = "'quoted words'";
- $y =~ s/^'(.*)'$/$1/; # strip single quotes,
- # $y contains "quoted words"
-</pre>
-<p>With the <code>s///</code> operator, the matched variables <code>$1</code>,
<code>$2</code>, etc.
-are immediately available for use in the replacement expression. With
-the global modifier, <code>s///g</code> will search and replace all occurrences
-of the regex in the string:
-</p>
-<pre class="verbatim"> $x = "I batted 4 for 4";
- $x =~ s/4/four/; # $x contains "I batted four for 4"
- $x = "I batted 4 for 4";
- $x =~ s/4/four/g; # $x contains "I batted four for four"
-</pre>
-<p>The non-destructive modifier <code>s///r</code> causes the result of the
substitution
-to be returned instead of modifying <code>$_</code> (or whatever variable the
-substitute was bound to with <code>=~</code>):
-</p>
-<pre class="verbatim"> $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)
-</pre>
-<p>The evaluation modifier <code>s///e</code> wraps an <code>eval{...}</code>
around the
-replacement string and the evaluated result is substituted for the
-matched substring. Some examples:
-</p>
-<pre class="verbatim"> # reverse all the words in a string
- $x = "the cat in the hat";
- $x =~ s/(\w+)/reverse $1/ge; # $x contains "eht tac ni eht tah"
-
- # convert percentage to decimal
- $x = "A 39% hit rate";
- $x =~ s!(\d+)%!$1/100!e; # $x contains "A 0.39 hit rate"
-</pre>
-<p>The last example shows that <code>s///</code> can use other delimiters,
such as
-<code>s!!!</code> and <code>s{}{}</code>, and even <code>s{}//</code>. If
single quotes are used
-<code>s'''</code>, then the regex and replacement are treated as single-quoted
-strings.
-</p>
-<hr>
-<a name="perlrequick-The-split-operator"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick-use-re-_0027strict_0027" accesskey="n"
rel="next">perlrequick <code>use re 'strict'</code></a>, Previous: <a
href="#perlrequick-Search-and-replace" accesskey="p" rel="prev">perlrequick
Search and replace</a>, Up: <a href="#perlrequick-The-Guide" accesskey="u"
rel="up">perlrequick The Guide</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-split-operator"></a>
-<h4 class="subsection">66.3.9 The split operator</h4>
-
-<p><code>split /regex/, string</code> splits <code>string</code> into a list
of substrings
-and returns that list. The regex determines the character sequence
-that <code>string</code> is split with respect to. For example, to split a
-string into words, use
-</p>
-<pre class="verbatim"> $x = "Calvin and Hobbes";
- @word = split /\s+/, $x; # $word[0] = 'Calvin'
- # $word[1] = 'and'
- # $word[2] = 'Hobbes'
-</pre>
-<p>To extract a comma-delimited list of numbers, use
-</p>
-<pre class="verbatim"> $x = "1.618,2.718, 3.142";
- @const = split /,\s*/, $x; # $const[0] = '1.618'
- # $const[1] = '2.718'
- # $const[2] = '3.142'
-</pre>
-<p>If the empty regex <code>//</code> is used, the string is split into
individual
-characters. If the regex has groupings, then the list produced contains
-the matched substrings from the groupings as well:
-</p>
-<pre class="verbatim"> $x = "/usr/bin";
- @parts = split m!(/)!, $x; # $parts[0] = ''
- # $parts[1] = '/'
- # $parts[2] = 'usr'
- # $parts[3] = '/'
- # $parts[4] = 'bin'
-</pre>
-<p>Since the first character of $x matched the regex, <code>split</code>
prepended
-an empty initial element to the list.
-</p>
-<hr>
-<a name="perlrequick-use-re-_0027strict_0027"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlrequick-The-split-operator" accesskey="p"
rel="prev">perlrequick The split operator</a>, Up: <a
href="#perlrequick-The-Guide" accesskey="u" rel="up">perlrequick The Guide</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="use-re-_0027strict_0027"></a>
-<h4 class="subsection">66.3.10 <code>use re 'strict'</code></h4>
-
-<p>New in v5.22, this applies stricter rules than otherwise when compiling
-regular expression patterns. It can find things that, while legal, may
-not be what you intended.
-</p>
-<p>See <a href="re.html#g_t_0027strict_0027-mode">(re)’strict’ in
re</a>.
-</p>
-<hr>
-<a name="perlrequick-BUGS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick-SEE-ALSO" accesskey="n" rel="next">perlrequick SEE
ALSO</a>, Previous: <a href="#perlrequick-The-Guide" accesskey="p"
rel="prev">perlrequick The Guide</a>, Up: <a href="#perlrequick" accesskey="u"
rel="up">perlrequick</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="BUGS-7"></a>
-<h3 class="section">66.4 BUGS</h3>
-
-<p>None.
-</p>
-<hr>
-<a name="perlrequick-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrequick-AUTHOR-AND-COPYRIGHT" accesskey="n"
rel="next">perlrequick AUTHOR AND COPYRIGHT</a>, Previous: <a
href="#perlrequick-BUGS" accesskey="p" rel="prev">perlrequick BUGS</a>, Up: <a
href="#perlrequick" accesskey="u" rel="up">perlrequick</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-33"></a>
-<h3 class="section">66.5 SEE ALSO</h3>
-
-<p>This is just a quick start guide. For a more in-depth tutorial on
-regexes, see <a href="#perlretut-NAME">perlretut NAME</a> and for the
reference page, see <a href="#perlre-NAME">perlre NAME</a>.
-</p>
-<hr>
-<a name="perlrequick-AUTHOR-AND-COPYRIGHT"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlrequick-SEE-ALSO" accesskey="p" rel="prev">perlrequick
SEE ALSO</a>, Up: <a href="#perlrequick" accesskey="u" rel="up">perlrequick</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-AND-COPYRIGHT"></a>
-<h3 class="section">66.6 AUTHOR AND COPYRIGHT</h3>
-
-<p>Copyright (c) 2000 Mark Kvale
-All rights reserved.
-</p>
-<p>This document may be distributed under the same terms as Perl itself.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlrequick-Acknowledgments" accesskey="1">perlrequick
Acknowledgments</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrequick-Acknowledgments"></a>
-<div class="header">
-<p>
-Up: <a href="#perlrequick-AUTHOR-AND-COPYRIGHT" accesskey="u"
rel="up">perlrequick AUTHOR AND COPYRIGHT</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Acknowledgments"></a>
-<h4 class="subsection">66.6.1 Acknowledgments</h4>
-
-<p>The author would like to thank Mark-Jason Dominus, Tom Christiansen,
-Ilya Zakharevich, Brad Hughes, and Mike Giroux for all their helpful
-comments.
-</p>
-<hr>
-<a name="perlreref"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut" accesskey="n" rel="next">perlretut</a>, Previous:
<a href="#perlrequick" accesskey="p" rel="prev">perlrequick</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlreref-1"></a>
-<h2 class="chapter">67 perlreref</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlreref-NAME"
accesskey="1">perlreref NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreref-DESCRIPTION"
accesskey="2">perlreref DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreref-AUTHOR"
accesskey="3">perlreref AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreref-SEE-ALSO"
accesskey="4">perlreref SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreref-THANKS"
accesskey="5">perlreref THANKS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreref-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref-DESCRIPTION" accesskey="n" rel="next">perlreref
DESCRIPTION</a>, Up: <a href="#perlreref" accesskey="u" rel="up">perlreref</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-66"></a>
-<h3 class="section">67.1 NAME</h3>
-
-<p>perlreref - Perl Regular Expressions Reference
-</p>
-<hr>
-<a name="perlreref-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref-AUTHOR" accesskey="n" rel="next">perlreref
AUTHOR</a>, Previous: <a href="#perlreref-NAME" accesskey="p"
rel="prev">perlreref NAME</a>, Up: <a href="#perlreref" accesskey="u"
rel="up">perlreref</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-65"></a>
-<h3 class="section">67.2 DESCRIPTION</h3>
-
-<p>This is a quick reference to Perl’s regular expressions.
-For full information see <a href="#perlre-NAME">perlre NAME</a> and <a
href="#perlop-NAME">perlop NAME</a>, as well
-as the <a href="#perlreref-SEE-ALSO">SEE ALSO</a> section in this document.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlreref-OPERATORS"
accesskey="1">perlreref OPERATORS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreref-SYNTAX"
accesskey="2">perlreref SYNTAX</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreref-ESCAPE-SEQUENCES"
accesskey="3">perlreref ESCAPE SEQUENCES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref-CHARACTER-CLASSES" accesskey="4">perlreref CHARACTER
CLASSES</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreref-ANCHORS"
accesskey="5">perlreref ANCHORS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreref-QUANTIFIERS"
accesskey="6">perlreref QUANTIFIERS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref-EXTENDED-CONSTRUCTS" accesskey="7">perlreref EXTENDED
CONSTRUCTS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreref-VARIABLES"
accesskey="8">perlreref VARIABLES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreref-FUNCTIONS"
accesskey="9">perlreref FUNCTIONS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlreref-TERMINOLOGY">perlreref
TERMINOLOGY</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreref-OPERATORS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref-SYNTAX" accesskey="n" rel="next">perlreref
SYNTAX</a>, Up: <a href="#perlreref-DESCRIPTION" accesskey="u"
rel="up">perlreref DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="OPERATORS"></a>
-<h4 class="subsection">67.2.1 OPERATORS</h4>
-
-<p><code>=~</code> determines to which variable the regex is applied.
-In its absence, $_ is used.
-</p>
-<pre class="verbatim"> $var =~ /foo/;
-</pre>
-<p><code>!~</code> determines to which variable the regex is applied,
-and negates the result of the match; it returns
-false if the match succeeds, and true if it fails.
-</p>
-<pre class="verbatim"> $var !~ /foo/;
-</pre>
-<p><code>m/pattern/msixpogcdualn</code> searches a string for a pattern match,
-applying the given options.
-</p>
-<pre class="verbatim"> m Multiline mode - ^ and $ match internal lines
- s match as a Single line - . matches \n
- i case-Insensitive
- x eXtended legibility - free whitespace and comments
- p Preserve a copy of the matched string -
- ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be defined.
- 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
- n Non-capture mode. Don't let () fill in $1, $2, etc...
-</pre>
-<p>If ’pattern’ is an empty string, the last <em>successfully</em>
matched
-regex is used. Delimiters other than ’/’ may be used for both this
-operator and the following ones. The leading <code>m</code> can be omitted
-if the delimiter is ’/’.
-</p>
-<p><code>qr/pattern/msixpodualn</code> lets you store a regex in a variable,
-or pass one around. Modifiers as for <code>m//</code>, and are stored
-within the regex.
-</p>
-<p><code>s/pattern/replacement/msixpogcedual</code> substitutes matches of
-’pattern’ with ’replacement’. Modifiers as for
<code>m//</code>,
-with two additions:
-</p>
-<pre class="verbatim"> e Evaluate 'replacement' as an expression
- r Return substitution and leave the original string untouched.
-</pre>
-<p>’e’ may be specified multiple times. ’replacement’
is interpreted
-as a double quoted string unless a single-quote (<code>'</code>) is the
delimiter.
-</p>
-<p><code>?pattern?</code> is like <code>m/pattern/</code> but matches only
once. No alternate
-delimiters can be used. Must be reset with reset().
-</p>
-<hr>
-<a name="perlreref-SYNTAX"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref-ESCAPE-SEQUENCES" accesskey="n" rel="next">perlreref
ESCAPE SEQUENCES</a>, Previous: <a href="#perlreref-OPERATORS" accesskey="p"
rel="prev">perlreref OPERATORS</a>, Up: <a href="#perlreref-DESCRIPTION"
accesskey="u" rel="up">perlreref DESCRIPTION</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SYNTAX"></a>
-<h4 class="subsection">67.2.2 SYNTAX</h4>
-
-<pre class="verbatim"> \ Escapes the character immediately following it
- . Matches any single character except a newline (unless /s is
- used)
- ^ Matches at the beginning of the string (or line, if /m is used)
- $ Matches at the end of the string (or line, if /m is used)
- * Matches the preceding element 0 or more times
- + Matches the preceding element 1 or more times
- ? Matches the preceding element 0 or 1 times
- {...} Specifies a range of occurrences for the element preceding it
- [...] Matches any one of the characters contained within the brackets
- (...) Groups subexpressions for capturing to $1, $2...
- (?:...) Groups subexpressions without capturing (cluster)
- | Matches either the subexpression preceding or following it
- \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
- \k'name' Named backreference
- (?P=name) Named backreference (python syntax)
-</pre>
-<hr>
-<a name="perlreref-ESCAPE-SEQUENCES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref-CHARACTER-CLASSES" accesskey="n"
rel="next">perlreref CHARACTER CLASSES</a>, Previous: <a
href="#perlreref-SYNTAX" accesskey="p" rel="prev">perlreref SYNTAX</a>, Up: <a
href="#perlreref-DESCRIPTION" accesskey="u" rel="up">perlreref DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="ESCAPE-SEQUENCES"></a>
-<h4 class="subsection">67.2.3 ESCAPE SEQUENCES</h4>
-
-<p>These work as in normal strings.
-</p>
-<pre class="verbatim"> \a Alarm (beep)
- \e Escape
- \f Formfeed
- \n Newline
- \r Carriage return
- \t Tab
- \037 Char whose ordinal is the 3 octal digits, max \777
- \o{2307} Char whose ordinal is the octal number, unrestricted
- \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 or character sequence
- \N{U+263D} A Unicode character by hex ordinal
-
- \l Lowercase next character
- \u Titlecase next character
- \L Lowercase until \E
- \U Uppercase until \E
- \F Foldcase until \E
- \Q Disable pattern metacharacters until \E
- \E End modification
-</pre>
-<p>For Titlecase, see <a href="#perlreref-Titlecase">Titlecase</a>.
-</p>
-<p>This one works differently from normal strings:
-</p>
-<pre class="verbatim"> \b An assertion, not backspace, except in a
character class
-</pre>
-<hr>
-<a name="perlreref-CHARACTER-CLASSES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref-ANCHORS" accesskey="n" rel="next">perlreref
ANCHORS</a>, Previous: <a href="#perlreref-ESCAPE-SEQUENCES" accesskey="p"
rel="prev">perlreref ESCAPE SEQUENCES</a>, Up: <a href="#perlreref-DESCRIPTION"
accesskey="u" rel="up">perlreref DESCRIPTION</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="CHARACTER-CLASSES"></a>
-<h4 class="subsection">67.2.4 CHARACTER CLASSES</h4>
-
-<pre class="verbatim"> [amy] Match 'a', 'm' or 'y'
- [f-j] Dash specifies "range"
- [f-j-] Dash escaped or at start or end means 'dash'
- [^f-j] Caret indicates "match any character _except_ these"
-</pre>
-<p>The following sequences (except <code>\N</code>) work within or without a
character class.
-The first six are locale aware, all are Unicode aware. See <a
href="#perllocale-NAME">perllocale NAME</a>
-and <a href="#perlunicode-NAME">perlunicode NAME</a> for details.
-</p>
-<pre class="verbatim"> \d A digit
- \D A nondigit
- \w A word character
- \W A non-word character
- \s A whitespace character
- \S A non-whitespace character
- \h An horizontal whitespace
- \H A non horizontal whitespace
- \N A non newline (when not followed by '{NAME}';;
- not valid in a character class; equivalent to [^\n]; it's
- like '.' without /s modifier)
- \v A vertical whitespace
- \V A non vertical whitespace
- \R A generic newline (?>\v|\x0D\x0A)
-
- \C Match a byte (with Unicode, '.' matches a character)
- (Deprecated.)
- \pP Match P-named (Unicode) property
- \p{...} Match Unicode property with name longer than 1 character
- \PP Match non-P
- \P{...} Match lack of Unicode property with name longer than 1 char
- \X Match Unicode extended grapheme cluster
-</pre>
-<p>POSIX character classes and their Unicode and Perl equivalents:
-</p>
-<pre class="verbatim"> ASCII- Full-
- POSIX range range backslash
- [[:...:]] \p{...} \p{...} sequence Description
-
- -----------------------------------------------------------------------
- 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 PosixWord XPosixWord \w Alnum + Unicode marks +
- connectors, like '_'
- (Perl extension)
- xdigit ASCII_Hex_Digit XPosixDigit Hexadecimal digit,
- ASCII-range is
- [0-9A-Fa-f]
-</pre>
-<p>Also, various synonyms like <code>\p{Alpha}</code> for
<code>\p{XPosixAlpha}</code>; all listed
-in <a
href="perluniprops.html#Properties-accessible-through-_005cp_007b_007d-and-_005cP_007b_007d">(perluniprops)Properties
accessible through \p{} and \P{}</a>
-</p>
-<p>Within a character class:
-</p>
-<pre class="verbatim"> POSIX traditional Unicode
- [:digit:] \d \p{Digit}
- [:^digit:] \D \P{Digit}
-</pre>
-<hr>
-<a name="perlreref-ANCHORS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref-QUANTIFIERS" accesskey="n" rel="next">perlreref
QUANTIFIERS</a>, Previous: <a href="#perlreref-CHARACTER-CLASSES" accesskey="p"
rel="prev">perlreref CHARACTER CLASSES</a>, Up: <a
href="#perlreref-DESCRIPTION" accesskey="u" rel="up">perlreref DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="ANCHORS"></a>
-<h4 class="subsection">67.2.5 ANCHORS</h4>
-
-<p>All are zero-width assertions.
-</p>
-<pre class="verbatim"> ^ Match string start (or line, if /m is used)
- $ Match string end (or line, if /m is used) or before newline
- \b{} Match boundary of type specified within the braces
- \B{} Match wherever \b{} doesn't match
- \b Match word boundary (between \w and \W)
- \B Match except at word boundary (between \w and \w or \W and \W)
- \A Match string start (regardless of /m)
- \Z Match string end (before optional newline)
- \z Match absolute string end
- \G Match where previous m//g left off
- \K Keep the stuff left of the \K, don't include it in $&
-</pre>
-<hr>
-<a name="perlreref-QUANTIFIERS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref-EXTENDED-CONSTRUCTS" accesskey="n"
rel="next">perlreref EXTENDED CONSTRUCTS</a>, Previous: <a
href="#perlreref-ANCHORS" accesskey="p" rel="prev">perlreref ANCHORS</a>, Up:
<a href="#perlreref-DESCRIPTION" accesskey="u" rel="up">perlreref
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="QUANTIFIERS"></a>
-<h4 class="subsection">67.2.6 QUANTIFIERS</h4>
-
-<p>Quantifiers are greedy by default and match the <strong>longest</strong>
leftmost.
-</p>
-<pre class="verbatim"> Maximal Minimal Possessive Allowed range
- ------- ------- ---------- -------------
- {n,m} {n,m}? {n,m}+ Must occur at least n times
- but no more than m times
- {n,} {n,}? {n,}+ Must occur at least n times
- {n} {n}? {n}+ Must occur exactly n times
- * *? *+ 0 or more times (same as {0,})
- + +? ++ 1 or more times (same as {1,})
- ? ?? ?+ 0 or 1 time (same as {0,1})
-</pre>
-<p>The possessive forms (new in Perl 5.10) prevent backtracking: what gets
-matched by a pattern with a possessive quantifier will not be backtracked
-into, even if that causes the whole match to fail.
-</p>
-<p>There is no quantifier <code>{,n}</code>. That’s interpreted as a
literal string.
-</p>
-<hr>
-<a name="perlreref-EXTENDED-CONSTRUCTS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref-VARIABLES" accesskey="n" rel="next">perlreref
VARIABLES</a>, Previous: <a href="#perlreref-QUANTIFIERS" accesskey="p"
rel="prev">perlreref QUANTIFIERS</a>, Up: <a href="#perlreref-DESCRIPTION"
accesskey="u" rel="up">perlreref DESCRIPTION</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="EXTENDED-CONSTRUCTS"></a>
-<h4 class="subsection">67.2.7 EXTENDED CONSTRUCTS</h4>
-
-<pre class="verbatim"> (?#text) A comment
- (?:...) Groups subexpressions without capturing (cluster)
- (?pimsx-imsx:...) Enable/disable option (as per m// modifiers)
- (?=...) Zero-width positive lookahead assertion
- (?!...) Zero-width negative lookahead assertion
- (?<=...) Zero-width positive lookbehind assertion
- (?<!...) Zero-width negative lookbehind assertion
- (?>...) Grab what we can, prohibit backtracking
- (?|...) Branch reset
- (?<name>...) Named capture
- (?'name'...) Named capture
- (?P<name>...) Named capture (python syntax)
- (?[...]) Extended bracketed character class
- (?{ code }) Embedded code, return value becomes $^R
- (??{ code }) Dynamic regex, return value used as regex
- (?N) Recurse into subpattern number N
- (?-N), (?+N) Recurse into Nth previous/next subpattern
- (?R), (?0) Recurse at the beginning of the whole pattern
- (?&name) Recurse into a named subpattern
- (?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
- (?{code}) code condition
- (R) true if recursing
- (RN) true if recursing into Nth subpattern
- (R&name) true if recursing into named subpattern
- (DEFINE) always false, no no-pattern allowed
-</pre>
-<hr>
-<a name="perlreref-VARIABLES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref-FUNCTIONS" accesskey="n" rel="next">perlreref
FUNCTIONS</a>, Previous: <a href="#perlreref-EXTENDED-CONSTRUCTS" accesskey="p"
rel="prev">perlreref EXTENDED CONSTRUCTS</a>, Up: <a
href="#perlreref-DESCRIPTION" accesskey="u" rel="up">perlreref DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="VARIABLES"></a>
-<h4 class="subsection">67.2.8 VARIABLES</h4>
-
-<pre class="verbatim"> $_ Default variable for operators to use
-
- $` Everything prior to matched string
- $& Entire matched string
- $' Everything after to matched string
-
- ${^PREMATCH} Everything prior to matched string
- ${^MATCH} Entire matched string
- ${^POSTMATCH} Everything after to matched string
-</pre>
-<p>Note to those still using Perl 5.18 or earlier:
-The use of <code>$`</code>, <code>$&</code> or <code>$'</code> will slow
down <strong>all</strong> regex use
-within your program. Consult <a href="#perlvar-NAME">perlvar NAME</a> for
<code>@-</code>
-to see equivalent expressions that won’t cause slow down.
-See also <a href="Devel-SawAmpersand.html#Top">(Devel-SawAmpersand)</a>.
Starting with Perl 5.10, you
-can also use the equivalent variables <code>${^PREMATCH}</code>,
<code>${^MATCH}</code>
-and <code>${^POSTMATCH}</code>, but for them to be defined, you have to
-specify the <code>/p</code> (preserve) modifier on your regular expression.
-In Perl 5.20, the use of <code>$`</code>, <code>$&</code> and
<code>$'</code> makes no speed difference.
-</p>
-<pre class="verbatim"> $1, $2 ... hold the Xth captured expr
- $+ Last parenthesized pattern match
- $^N Holds the most recently closed capture
- $^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 groups
- %- Named capture groups, as array refs
-</pre>
-<p>Captured groups are numbered according to their <em>opening</em> paren.
-</p>
-<hr>
-<a name="perlreref-FUNCTIONS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref-TERMINOLOGY" accesskey="n" rel="next">perlreref
TERMINOLOGY</a>, Previous: <a href="#perlreref-VARIABLES" accesskey="p"
rel="prev">perlreref VARIABLES</a>, Up: <a href="#perlreref-DESCRIPTION"
accesskey="u" rel="up">perlreref DESCRIPTION</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="FUNCTIONS"></a>
-<h4 class="subsection">67.2.9 FUNCTIONS</h4>
-
-<pre class="verbatim"> lc Lowercase a string
- lcfirst Lowercase first char of a string
- uc Uppercase a string
- ucfirst Titlecase first char of a string
- fc Foldcase a string
-
- pos Return or set current match position
- quotemeta Quote metacharacters
- reset Reset ?pattern? status
- study Analyze string for optimizing matching
-
- split Use a regex to split a string into parts
-</pre>
-<p>The first five of these are like the escape sequences <code>\L</code>,
<code>\l</code>,
-<code>\U</code>, <code>\u</code>, and <code>\F</code>. For Titlecase, see <a
href="#perlreref-Titlecase">Titlecase</a>; For
-Foldcase, see <a href="#perlreref-Foldcase">Foldcase</a>.
-</p>
-<hr>
-<a name="perlreref-TERMINOLOGY"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreref-FUNCTIONS" accesskey="p" rel="prev">perlreref
FUNCTIONS</a>, Up: <a href="#perlreref-DESCRIPTION" accesskey="u"
rel="up">perlreref DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="TERMINOLOGY"></a>
-<h4 class="subsection">67.2.10 TERMINOLOGY</h4>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlreref-Titlecase"
accesskey="1">perlreref Titlecase</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlreref-Foldcase"
accesskey="2">perlreref Foldcase</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlreref-Titlecase"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref-Foldcase" accesskey="n" rel="next">perlreref
Foldcase</a>, Up: <a href="#perlreref-TERMINOLOGY" accesskey="u"
rel="up">perlreref TERMINOLOGY</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Titlecase"></a>
-<h4 class="subsubsection">67.2.10.1 Titlecase</h4>
-
-<p>Unicode concept which most often is equal to uppercase, but for
-certain characters like the German "sharp s" there is a difference.
-</p>
-<hr>
-<a name="perlreref-Foldcase"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreref-Titlecase" accesskey="p" rel="prev">perlreref
Titlecase</a>, Up: <a href="#perlreref-TERMINOLOGY" accesskey="u"
rel="up">perlreref TERMINOLOGY</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Foldcase"></a>
-<h4 class="subsubsection">67.2.10.2 Foldcase</h4>
-
-<p>Unicode form that is useful when comparing strings regardless of case,
-as certain characters have complex one-to-many case mappings. Primarily a
-variant of lowercase.
-</p>
-<hr>
-<a name="perlreref-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref-SEE-ALSO" accesskey="n" rel="next">perlreref SEE
ALSO</a>, Previous: <a href="#perlreref-DESCRIPTION" accesskey="p"
rel="prev">perlreref DESCRIPTION</a>, Up: <a href="#perlreref" accesskey="u"
rel="up">perlreref</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-26"></a>
-<h3 class="section">67.3 AUTHOR</h3>
-
-<p>Iain Truskett. Updated by the Perl 5 Porters.
-</p>
-<p>This document may be distributed under the same terms as Perl itself.
-</p>
-<hr>
-<a name="perlreref-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlreref-THANKS" accesskey="n" rel="next">perlreref
THANKS</a>, Previous: <a href="#perlreref-AUTHOR" accesskey="p"
rel="prev">perlreref AUTHOR</a>, Up: <a href="#perlreref" accesskey="u"
rel="up">perlreref</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-34"></a>
-<h3 class="section">67.4 SEE ALSO</h3>
-
-<ul>
-<li> <a href="#perlretut-NAME">perlretut NAME</a> for a tutorial on regular
expressions.
-
-</li><li> <a href="#perlrequick-NAME">perlrequick NAME</a> for a rapid
tutorial.
-
-</li><li> <a href="#perlre-NAME">perlre NAME</a> for more details.
-
-</li><li> <a href="#perlvar-NAME">perlvar NAME</a> for details on the
variables.
-
-</li><li> <a href="#perlop-NAME">perlop NAME</a> for details on the operators.
-
-</li><li> <a href="#perlfunc-NAME">perlfunc NAME</a> for details on the
functions.
-
-</li><li> <a href="perlfaq6.html#Top">(perlfaq6)</a> for FAQs on regular
expressions.
-
-</li><li> <a href="#perlrebackslash-NAME">perlrebackslash NAME</a> for a
reference on backslash sequences.
-
-</li><li> <a href="#perlrecharclass-NAME">perlrecharclass NAME</a> for a
reference on character classes.
-
-</li><li> The <a href="re.html#Top">(re)</a> module to alter behaviour and aid
-debugging.
-
-</li><li> <a href="#perldebug-Debugging-Regular-Expressions">perldebug
Debugging Regular Expressions</a>
-
-</li><li> <a href="#perluniintro-NAME">perluniintro NAME</a>, <a
href="#perlunicode-NAME">perlunicode NAME</a>, <a
href="charnames.html#Top">(charnames)</a> and <a
href="#perllocale-NAME">perllocale NAME</a>
-for details on regexes and internationalisation.
-
-</li><li> <em>Mastering Regular Expressions</em> by Jeffrey Friedl
-(<samp>http://oreilly.com/catalog/9780596528126/</samp>) for a thorough
grounding and
-reference on the topic.
-
-</li></ul>
-
-<hr>
-<a name="perlreref-THANKS"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlreref-SEE-ALSO" accesskey="p" rel="prev">perlreref SEE
ALSO</a>, Up: <a href="#perlreref" accesskey="u" rel="up">perlreref</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="THANKS"></a>
-<h3 class="section">67.5 THANKS</h3>
-
-<p>David P.C. Wollmann,
-Richard Soderberg,
-Sean M. Burke,
-Tom Christiansen,
-Jim Cromie,
-and
-Jeffrey Goff
-for useful advice.
-</p>
-<hr>
-<a name="perlretut"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrun" accesskey="n" rel="next">perlrun</a>, Previous: <a
href="#perlreref" accesskey="p" rel="prev">perlreref</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlretut-10"></a>
-<h2 class="chapter">68 perlretut</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlretut-NAME"
accesskey="1">perlretut NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlretut-DESCRIPTION"
accesskey="2">perlretut DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Part-1_003a-The-basics" accesskey="3">perlretut Part 1: The
basics</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Part-2_003a-Power-tools" accesskey="4">perlretut Part 2: Power
tools</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlretut-BUGS"
accesskey="5">perlretut BUGS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlretut-SEE-ALSO"
accesskey="6">perlretut SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-AUTHOR-AND-COPYRIGHT" accesskey="7">perlretut AUTHOR AND
COPYRIGHT</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlretut-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-DESCRIPTION" accesskey="n" rel="next">perlretut
DESCRIPTION</a>, Up: <a href="#perlretut" accesskey="u" rel="up">perlretut</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-67"></a>
-<h3 class="section">68.1 NAME</h3>
-
-<p>perlretut - Perl regular expressions tutorial
-</p>
-<hr>
-<a name="perlretut-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Part-1_003a-The-basics" accesskey="n"
rel="next">perlretut Part 1: The basics</a>, Previous: <a
href="#perlretut-NAME" accesskey="p" rel="prev">perlretut NAME</a>, Up: <a
href="#perlretut" accesskey="u" rel="up">perlretut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-66"></a>
-<h3 class="section">68.2 DESCRIPTION</h3>
-
-<p>This page provides a basic tutorial on understanding, creating and
-using regular expressions in Perl. It serves as a complement to the
-reference page on regular expressions <a href="#perlre-NAME">perlre NAME</a>.
Regular expressions
-are an integral part of the <code>m//</code>, <code>s///</code>,
<code>qr//</code> and <code>split</code>
-operators and so this tutorial also overlaps with
-<a href="#perlop-Regexp-Quote_002dLike-Operators">perlop Regexp Quote-Like
Operators</a> and <a href="#perlfunc-split">perlfunc split</a>.
-</p>
-<p>Perl is widely renowned for excellence in text processing, and regular
-expressions are one of the big factors behind this fame. Perl regular
-expressions display an efficiency and flexibility unknown in most
-other computer languages. Mastering even the basics of regular
-expressions will allow you to manipulate text with surprising ease.
-</p>
-<p>What is a regular expression? A regular expression is simply a string
-that describes a pattern. Patterns are in common use these days;
-examples are the patterns typed into a search engine to find web pages
-and the patterns used to list files in a directory, e.g., <code>ls *.txt</code>
-or <code>dir *.*</code>. In Perl, the patterns described by regular
expressions
-are used to search strings, extract desired parts of strings, and to
-do search and replace operations.
-</p>
-<p>Regular expressions have the undeserved reputation of being abstract
-and difficult to understand. Regular expressions are constructed using
-simple concepts like conditionals and loops and are no more difficult
-to understand than the corresponding <code>if</code> conditionals and
<code>while</code>
-loops in the Perl language itself. In fact, the main challenge in
-learning regular expressions is just getting used to the terse
-notation used to express these concepts.
-</p>
-<p>This tutorial flattens the learning curve by discussing regular
-expression concepts, along with their notation, one at a time and with
-many examples. The first part of the tutorial will progress from the
-simplest word searches to the basic regular expression concepts. If
-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.
-</p>
-<p>A note: to save time, ’regular expression’ is often abbreviated
as
-regexp or regex. Regexp is a more natural abbreviation than regex, but
-is harder to pronounce. The Perl pod documentation is evenly split on
-regexp vs regex; in Perl, there is more than one way to abbreviate it.
-We’ll use regexp in this tutorial.
-</p>
-<p>New in v5.22, <a href="re.html#g_t_0027strict_0027-mode">(re)<code>use re
'strict'</code></a> applies stricter
-rules than otherwise when compiling regular expression patterns. It can
-find things that, while legal, may not be what you intended.
-</p>
-<hr>
-<a name="perlretut-Part-1_003a-The-basics"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Part-2_003a-Power-tools" accesskey="n"
rel="next">perlretut Part 2: Power tools</a>, Previous: <a
href="#perlretut-DESCRIPTION" accesskey="p" rel="prev">perlretut
DESCRIPTION</a>, Up: <a href="#perlretut" accesskey="u" rel="up">perlretut</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Part-1_003a-The-basics"></a>
-<h3 class="section">68.3 Part 1: The basics</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlretut-Simple-word-matching" accesskey="1">perlretut Simple word
matching</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Using-character-classes" accesskey="2">perlretut Using
character classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Matching-this-or-that" accesskey="3">perlretut Matching this
or that</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Grouping-things-and-hierarchical-matching"
accesskey="4">perlretut Grouping things and hierarchical
matching</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Extracting-matches" accesskey="5">perlretut Extracting
matches</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlretut-Backreferences"
accesskey="6">perlretut Backreferences</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Relative-backreferences" accesskey="7">perlretut Relative
backreferences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Named-backreferences" accesskey="8">perlretut Named
backreferences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Alternative-capture-group-numbering" accesskey="9">perlretut
Alternative capture group numbering</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Position-information">perlretut Position
information</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Non_002dcapturing-groupings">perlretut Non-capturing
groupings</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Matching-repetitions">perlretut Matching
repetitions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Possessive-quantifiers">perlretut Possessive
quantifiers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Building-a-regexp">perlretut Building a
regexp</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Using-regular-expressions-in-Perl">perlretut Using regular
expressions in Perl</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlretut-Simple-word-matching"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Using-character-classes" accesskey="n"
rel="next">perlretut Using character classes</a>, Up: <a
href="#perlretut-Part-1_003a-The-basics" accesskey="u" rel="up">perlretut Part
1: The basics</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Simple-word-matching-1"></a>
-<h4 class="subsection">68.3.1 Simple word matching</h4>
-
-<p>The simplest regexp is simply a word, or more generally, a string of
-characters. A regexp consisting of a word matches any string that
-contains that word:
-</p>
-<pre class="verbatim"> "Hello World" =~ /World/; # matches
-</pre>
-<p>What is this Perl statement all about? <code>"Hello World"</code>
is a simple
-double-quoted string. <code>World</code> is the regular expression and the
-<code>//</code> enclosing <code>/World/</code> tells Perl to search a string
for a match.
-The operator <code>=~</code> associates the string with the regexp match and
-produces a true value if the regexp matched, or false if the regexp
-did not match. In our case, <code>World</code> matches the second word in
-<code>"Hello World"</code>, so the expression is true. Expressions
like this
-are useful in conditionals:
-</p>
-<pre class="verbatim"> if ("Hello World" =~ /World/) {
- print "It matches\n";
- }
- else {
- print "It doesn't match\n";
- }
-</pre>
-<p>There are useful variations on this theme. The sense of the match can
-be reversed by using the <code>!~</code> operator:
-</p>
-<pre class="verbatim"> if ("Hello World" !~ /World/) {
- print "It doesn't match\n";
- }
- else {
- print "It matches\n";
- }
-</pre>
-<p>The literal string in the regexp can be replaced by a variable:
-</p>
-<pre class="verbatim"> $greeting = "World";
- if ("Hello World" =~ /$greeting/) {
- print "It matches\n";
- }
- else {
- print "It doesn't match\n";
- }
-</pre>
-<p>If you’re matching against the special default variable
<code>$_</code>, the
-<code>$_ =~</code> part can be omitted:
-</p>
-<pre class="verbatim"> $_ = "Hello World";
- if (/World/) {
- print "It matches\n";
- }
- else {
- print "It doesn't match\n";
- }
-</pre>
-<p>And finally, the <code>//</code> default delimiters for a match can be
changed
-to arbitrary delimiters by putting an <code>'m'</code> out front:
-</p>
-<pre class="verbatim"> "Hello World" =~ m!World!; # matches,
delimited by '!'
- "Hello World" =~ m{World}; # matches, note the matching '{}'
- "/usr/bin/perl" =~ m"/perl"; # matches after
'/usr/bin',
- # '/' becomes an ordinary char
-</pre>
-<p><code>/World/</code>, <code>m!World!</code>, and <code>m{World}</code> all
represent the
-same thing. When, e.g., the quote (<code>"</code>) is used as a
delimiter, the forward
-slash <code>'/'</code> becomes an ordinary character and can be used in this
regexp
-without trouble.
-</p>
-<p>Let’s consider how different regexps would match <code>"Hello
World"</code>:
-</p>
-<pre class="verbatim"> "Hello World" =~ /world/; # doesn't match
- "Hello World" =~ /o W/; # matches
- "Hello World" =~ /oW/; # doesn't match
- "Hello World" =~ /World /; # doesn't match
-</pre>
-<p>The first regexp <code>world</code> doesn’t match because regexps are
-case-sensitive. The second regexp matches because the substring
-<code>'o W'</code><!-- /@w --> occurs in the string
<code>"Hello World"</code><!-- /@w -->. The space
-character ’ ’ is treated like any other character in a regexp and
is
-needed to match in this case. The lack of a space character is the
-reason the third regexp <code>'oW'</code> doesn’t match. The fourth
regexp
-<code>'World '</code> doesn’t match because there is a space at the end
of the
-regexp, but not at the end of the string. The lesson here is that
-regexps must match a part of the string <em>exactly</em> in order for the
-statement to be true.
-</p>
-<p>If a regexp matches in more than one place in the string, Perl will
-always match at the earliest possible point in the string:
-</p>
-<pre class="verbatim"> "Hello World" =~ /o/; # matches 'o'
in 'Hello'
- "That hat is red" =~ /hat/; # matches 'hat' in 'That'
-</pre>
-<p>With respect to character matching, there are a few more points you
-need to know about. First of all, not all characters can be used ’as
-is’ in a match. Some characters, called <em>metacharacters</em>, are
reserved
-for use in regexp notation. The metacharacters are
-</p>
-<pre class="verbatim"> {}[]()^$.|*+?\
-</pre>
-<p>The significance of each of these will be explained
-in the rest of the tutorial, but for now, it is important only to know
-that a metacharacter can be matched by putting a backslash before it:
-</p>
-<pre class="verbatim"> "2+2=4" =~ /2+2/; # doesn't match, + is
a metacharacter
- "2+2=4" =~ /2\+2/; # matches, \+ is treated like an ordinary +
- "The interval is [0,1)." =~ /[0,1)./ # is a syntax error!
- "The interval is [0,1)." =~ /\[0,1\)\./ # matches
- "#!/usr/bin/perl" =~ /#!\/usr\/bin\/perl/; # matches
-</pre>
-<p>In the last regexp, the forward slash <code>'/'</code> is also backslashed,
-because it is used to delimit the regexp. This can lead to LTS
-(leaning toothpick syndrome), however, and it is often more readable
-to change delimiters.
-</p>
-<pre class="verbatim"> "#!/usr/bin/perl" =~ m!#\!/usr/bin/perl!;
# easier to read
-</pre>
-<p>The backslash character <code>'\'</code> is a metacharacter itself and
needs to
-be backslashed:
-</p>
-<pre class="verbatim"> 'C:\WIN32' =~ /C:\\WIN/; # matches
-</pre>
-<p>In addition to the metacharacters, there are some ASCII characters
-which don’t have printable character equivalents and are instead
-represented by <em>escape sequences</em>. Common examples are <code>\t</code>
for a
-tab, <code>\n</code> for a newline, <code>\r</code> for a carriage return and
<code>\a</code> for a
-bell (or alert). If your string is better thought of as a sequence of
arbitrary
-bytes, the octal escape sequence, e.g., <code>\033</code>, or hexadecimal
escape
-sequence, e.g., <code>\x1B</code> may be a more natural representation for your
-bytes. Here are some examples of escapes:
-</p>
-<pre class="verbatim"> "1000\t2000" =~ m(0\t2) # matches
- "1000\n2000" =~ /0\n20/ # matches
- "1000\t2000" =~ /\000\t2/ # doesn't match, "0" ne
"\000"
- "cat" =~ /\o{143}\x61\x74/ # matches in ASCII, but a weird way
- # to spell cat
-</pre>
-<p>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
-strings and in fact the regexps in Perl are mostly treated as
-double-quoted strings. This means that variables can be used in
-regexps as well. Just like double-quoted strings, the values of the
-variables in the regexp will be substituted in before the regexp is
-evaluated for matching purposes. So we have:
-</p>
-<pre class="verbatim"> $foo = 'house';
- 'housecat' =~ /$foo/; # matches
- 'cathouse' =~ /cat$foo/; # matches
- 'housecat' =~ /${foo}cat/; # matches
-</pre>
-<p>So far, so good. With the knowledge above you can already perform
-searches with just about any literal string regexp you can dream up.
-Here is a <em>very simple</em> emulation of the Unix grep program:
-</p>
-<pre class="verbatim"> % cat > simple_grep
- #!/usr/bin/perl
- $regexp = shift;
- while (<>) {
- print if /$regexp/;
- }
- ^D
-
- % chmod +x simple_grep
-
- % simple_grep abba /usr/dict/words
- Babbage
- cabbage
- cabbages
- sabbath
- Sabbathize
- Sabbathizes
- sabbatical
- scabbard
- scabbards
-</pre>
-<p>This program is easy to understand. <code>#!/usr/bin/perl</code> is the
standard
-way to invoke a perl program from the shell.
-<code>$regexp = shift;</code><!-- /@w --> saves the first command
line argument as the
-regexp to be used, leaving the rest of the command line arguments to
-be treated as files. <code>while (<>)</code><!-- /@w --> loops
over all the lines in
-all the files. For each line, <code>print if /$regexp/;</code><!--
/@w --> prints the
-line if the regexp matches the line. In this line, both <code>print</code> and
-<code>/$regexp/</code> use the default variable <code>$_</code> implicitly.
-</p>
-<p>With all of the regexps above, if the regexp matched anywhere in the
-string, it was considered a match. Sometimes, however, we’d like to
-specify <em>where</em> in the string the regexp should try to match. To do
-this, we would use the <em>anchor</em> metacharacters <code>^</code> and
<code>$</code>. The
-anchor <code>^</code> means match at the beginning of the string and the anchor
-<code>$</code> means match at the end of the string, or before a newline at the
-end of the string. Here is how they are used:
-</p>
-<pre class="verbatim"> "housekeeper" =~ /keeper/; # matches
- "housekeeper" =~ /^keeper/; # doesn't match
- "housekeeper" =~ /keeper$/; # matches
- "housekeeper\n" =~ /keeper$/; # matches
-</pre>
-<p>The second regexp doesn’t match because <code>^</code> constrains
<code>keeper</code> to
-match only at the beginning of the string, but
<code>"housekeeper"</code> has
-keeper starting in the middle. The third regexp does match, since the
-<code>$</code> constrains <code>keeper</code> to match only at the end of the
string.
-</p>
-<p>When both <code>^</code> and <code>$</code> are used at the same time, the
regexp has to
-match both the beginning and the end of the string, i.e., the regexp
-matches the whole string. Consider
-</p>
-<pre class="verbatim"> "keeper" =~ /^keep$/; # doesn't match
- "keeper" =~ /^keeper$/; # matches
- "" =~ /^$/; # ^$ matches an empty string
-</pre>
-<p>The first regexp doesn’t match because the string has more to it than
-<code>keep</code>. Since the second regexp is exactly the string, it
-matches. Using both <code>^</code> and <code>$</code> in a regexp forces the
complete
-string to match, so it gives you complete control over which strings
-match and which don’t. Suppose you are looking for a fellow named
-bert, off in a string by himself:
-</p>
-<pre class="verbatim"> "dogbert" =~ /bert/; # matches, but not
what you want
-
- "dilbert" =~ /^bert/; # doesn't match, but ..
- "bertram" =~ /^bert/; # matches, so still not good enough
-
- "bertram" =~ /^bert$/; # doesn't match, good
- "dilbert" =~ /^bert$/; # doesn't match, good
- "bert" =~ /^bert$/; # matches, perfect
-</pre>
-<p>Of course, in the case of a literal string, one could just as easily
-use the string comparison <code>$string eq 'bert'</code><!-- /@w -->
and it would be
-more efficient. The <code>^...$</code> regexp really becomes useful when we
-add in the more powerful regexp tools below.
-</p>
-<hr>
-<a name="perlretut-Using-character-classes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Matching-this-or-that" accesskey="n"
rel="next">perlretut Matching this or that</a>, Previous: <a
href="#perlretut-Simple-word-matching" accesskey="p" rel="prev">perlretut
Simple word matching</a>, Up: <a href="#perlretut-Part-1_003a-The-basics"
accesskey="u" rel="up">perlretut Part 1: The basics</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-character-classes-1"></a>
-<h4 class="subsection">68.3.2 Using character classes</h4>
-
-<p>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 represent not just a single character sequence, but a <em>whole
-class</em> of them.
-</p>
-<p>One such concept is that of a <em>character class</em>. A character class
-allows a set of possible characters, rather than just a single
-character, to match at a particular point in a regexp. You can define
-your own custom character classes. These
-are denoted by brackets <code>[...]</code>, with the set of characters
-to be possibly matched inside. Here are some examples:
-</p>
-<pre class="verbatim"> /cat/; # matches 'cat'
- /[bcr]at/; # matches 'bat, 'cat', or 'rat'
- /item[0123456789]/; # matches 'item0' or ... or 'item9'
- "abc" =~ /[cab]/; # matches 'a'
-</pre>
-<p>In the last statement, even though <code>'c'</code> is the first character
in
-the class, <code>'a'</code> matches because the first character position in the
-string is the earliest point at which the regexp can match.
-</p>
-<pre class="verbatim"> /[yY][eE][sS]/; # match 'yes' in a
case-insensitive way
- # 'yes', 'Yes', 'YES', etc.
-</pre>
-<p>This regexp displays a common task: perform a case-insensitive
-match. Perl provides a way of avoiding all those brackets by simply
-appending an <code>'i'</code> to the end of the match. Then
<code>/[yY][eE][sS]/;</code>
-can be rewritten as <code>/yes/i;</code>. The <code>'i'</code> stands for
-case-insensitive and is an example of a <em>modifier</em> of the matching
-operation. We will meet other modifiers later in the tutorial.
-</p>
-<p>We saw in the section above that there were ordinary characters, which
-represented themselves, and special characters, which needed a
-backslash <code>\</code> to represent themselves. The same is true in a
-character class, but the sets of ordinary and special characters
-inside a character class are different than those outside a character
-class. The special characters for a character class are <code>-]\^$</code>
(and
-the pattern delimiter, whatever it is).
-<code>]</code> is special because it denotes the end of a character class.
<code>$</code> is
-special because it denotes a scalar variable. <code>\</code> is special
because
-it is used in escape sequences, just like above. Here is how the
-special characters <code>]$\</code> are handled:
-</p>
-<pre class="verbatim"> /[\]c]def/; # matches ']def' or 'cdef'
- $x = 'bcr';
- /[$x]at/; # matches 'bat', 'cat', or 'rat'
- /[\$x]at/; # matches '$at' or 'xat'
- /[\\$x]at/; # matches '\at', 'bat, 'cat', or 'rat'
-</pre>
-<p>The last two are a little tricky. In <code>[\$x]</code>, the backslash
protects
-the dollar sign, so the character class has two members <code>$</code> and
<code>x</code>.
-In <code>[\\$x]</code>, the backslash is protected, so <code>$x</code> is
treated as a
-variable and substituted in double quote fashion.
-</p>
-<p>The special character <code>'-'</code> acts as a range operator within
character
-classes, so that a contiguous set of characters can be written as a
-range. With ranges, the unwieldy <code>[0123456789]</code> and
<code>[abc...xyz]</code>
-become the svelte <code>[0-9]</code> and <code>[a-z]</code>. Some examples are
-</p>
-<pre class="verbatim"> /item[0-9]/; # matches 'item0' or ... or 'item9'
- /[0-9bx-z]aa/; # matches '0aa', ..., '9aa',
- # 'baa', 'xaa', 'yaa', or 'zaa'
- /[0-9a-fA-F]/; # matches a hexadecimal digit
- /[0-9a-zA-Z_]/; # matches a "word" character,
- # like those in a Perl variable name
-</pre>
-<p>If <code>'-'</code> is the first or last character in a character class, it
is
-treated as an ordinary character; <code>[-ab]</code>, <code>[ab-]</code> and
<code>[a\-b]</code> are
-all equivalent.
-</p>
-<p>The special character <code>^</code> in the first position of a character
class
-denotes a <em>negated character class</em>, which matches any character but
-those in the brackets. Both <code>[...]</code> and <code>[^...]</code> must
match a
-character, or the match fails. Then
-</p>
-<pre class="verbatim"> /[^a]at/; # doesn't match 'aat' or 'at', but matches
- # all other 'bat', 'cat, '0at', '%at', etc.
- /[^0-9]/; # matches a non-numeric character
- /[a^]at/; # matches 'aat' or '^at'; here '^' is ordinary
-</pre>
-<p>Now, even <code>[0-9]</code> 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, unless the <code>//a</code> modifier is in
-effect, these character classes match more than just a few characters in
-the ASCII range.
-</p>
-<ul>
-<li> \d matches a digit, not just [0-9] but also digits from non-roman scripts
-
-</li><li> \s matches a whitespace character, the set [\ \t\r\n\f] and others
-
-</li><li> \w matches a word character (alphanumeric or _), not just
[0-9a-zA-Z_]
-but also digits and characters from non-roman scripts
-
-</li><li> \D is a negated \d; it represents any other character than a digit,
or [^\d]
-
-</li><li> \S is a negated \s; it represents any non-whitespace character [^\s]
-
-</li><li> \W is a negated \w; it represents any non-word character [^\w]
-
-</li><li> The period ’.’ matches any character but "\n"
(unless the modifier <code>//s</code> is
-in effect, as explained below).
-
-</li><li> \N, like the period, matches any character but "\n", but
it does so
-regardless of whether the modifier <code>//s</code> is in effect.
-
-</li></ul>
-
-<p>The <code>//a</code> 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,
<code>//aa</code>, 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".)
-</p>
-<p>The <code>\d\s\w\D\S\W</code> abbreviations can be used both inside and
outside
-of bracketed character classes. Here are some in use:
-</p>
-<pre class="verbatim"> /\d\d:\d\d:\d\d/; # matches a hh:mm:ss time format
- /[\d\s]/; # matches any digit or whitespace character
- /\w\W\w/; # matches a word char, followed by a
- # non-word char, followed by a word char
- /..rt/; # matches any two chars, followed by 'rt'
- /end\./; # matches 'end.'
- /end[.]/; # same thing, matches 'end.'
-</pre>
-<p>Because a period is a metacharacter, it needs to be escaped to match
-as an ordinary period. Because, for example, <code>\d</code> and
<code>\w</code> are sets
-of characters, it is incorrect to think of <code>[^\d\w]</code> as
<code>[\D\W]</code>; in
-fact <code>[^\d\w]</code> is the same as <code>[^\w]</code>, which is the same
as
-<code>[\W]</code>. Think DeMorgan’s laws.
-</p>
-<p>In actuality, the period and <code>\d\s\w\D\S\W</code> abbreviations are
-themselves types of character classes, so the ones surrounded by
-brackets are just one type of character class. When we need to make a
-distinction, we refer to them as "bracketed character classes."
-</p>
-<p>An anchor useful in basic regexps is the <em>word anchor</em>
-<code>\b</code>. This matches a boundary between a word character and a
non-word
-character <code>\w\W</code> or <code>\W\w</code>:
-</p>
-<pre class="verbatim"> $x = "Housecat catenates house and cat";
- $x =~ /cat/; # matches cat in 'housecat'
- $x =~ /\bcat/; # matches cat in 'catenates'
- $x =~ /cat\b/; # matches cat in 'housecat'
- $x =~ /\bcat\b/; # matches 'cat' at end of string
-</pre>
-<p>Note in the last example, the end of the string is considered a word
-boundary.
-</p>
-<p>For natural language processing (so that, for example, apostrophes are
-included in words), use instead <code>\b{wb}</code>
-</p>
-<pre class="verbatim"> "don't" =~ / .+? \b{wb} /x; # matches the
whole string
-</pre>
-<p>You might wonder why <code>'.'</code> matches everything but
<code>"\n"</code> - why not
-every character? The reason is that often one is matching against
-lines and would like to ignore the newline characters. For instance,
-while the string <code>"\n"</code> represents one line, we would
like to think
-of it as empty. Then
-</p>
-<pre class="verbatim"> "" =~ /^$/; # matches
- "\n" =~ /^$/; # matches, $ anchors before "\n"
-
- "" =~ /./; # doesn't match; it needs a char
- "" =~ /^.$/; # doesn't match; it needs a char
- "\n" =~ /^.$/; # doesn't match; it needs a char other than
"\n"
- "a" =~ /^.$/; # matches
- "a\n" =~ /^.$/; # matches, $ anchors before "\n"
-</pre>
-<p>This behavior is convenient, because we usually want to ignore
-newlines when we count and match characters in a line. Sometimes,
-however, we want to keep track of newlines. We might even want <code>^</code>
-and <code>$</code> to anchor at the beginning and end of lines within the
-string, rather than just the beginning and end of the string. Perl
-allows us to choose between ignoring and paying attention to newlines
-by using the <code>//s</code> and <code>//m</code> modifiers.
<code>//s</code> and <code>//m</code> stand for
-single line and multi-line and they determine whether a string is to
-be treated as one continuous string, or as a set of lines. The two
-modifiers affect two aspects of how the regexp is interpreted: 1) how
-the <code>'.'</code> character class is defined, and 2) where the anchors
<code>^</code>
-and <code>$</code> are able to match. Here are the four possible combinations:
-</p>
-<ul>
-<li> no modifiers (//): Default behavior. <code>'.'</code> matches any
character
-except <code>"\n"</code>. <code>^</code> matches only at the
beginning of the string and
-<code>$</code> matches only at the end or before a newline at the end.
-
-</li><li> s modifier (//s): Treat string as a single long line.
<code>'.'</code> matches
-any character, even <code>"\n"</code>. <code>^</code> matches only
at the beginning of
-the string and <code>$</code> matches only at the end or before a newline at
the
-end.
-
-</li><li> m modifier (//m): Treat string as a set of multiple lines.
<code>'.'</code>
-matches any character except <code>"\n"</code>. <code>^</code> and
<code>$</code> are able to match
-at the start or end of <em>any</em> line within the string.
-
-</li><li> both s and m modifiers (//sm): Treat string as a single long line,
but
-detect multiple lines. <code>'.'</code> matches any character, even
-<code>"\n"</code>. <code>^</code> and <code>$</code>, however, are
able to match at the start or end
-of <em>any</em> line within the string.
-
-</li></ul>
-
-<p>Here are examples of <code>//s</code> and <code>//m</code> in action:
-</p>
-<pre class="verbatim"> $x = "There once was a girl\nWho programmed in
Perl\n";
-
- $x =~ /^Who/; # doesn't match, "Who" not at start of string
- $x =~ /^Who/s; # doesn't match, "Who" not at start of string
- $x =~ /^Who/m; # matches, "Who" at start of second line
- $x =~ /^Who/sm; # matches, "Who" at start of second line
-
- $x =~ /girl.Who/; # doesn't match, "." doesn't match
"\n"
- $x =~ /girl.Who/s; # matches, "." matches "\n"
- $x =~ /girl.Who/m; # doesn't match, "." doesn't match
"\n"
- $x =~ /girl.Who/sm; # matches, "." matches "\n"
-</pre>
-<p>Most of the time, the default behavior is what is wanted, but
<code>//s</code> and
-<code>//m</code> are occasionally very useful. If <code>//m</code> is being
used, the start
-of the string can still be matched with <code>\A</code> and the end of the
string
-can still be matched with the anchors <code>\Z</code> (matches both the end and
-the newline before, like <code>$</code>), and <code>\z</code> (matches only
the end):
-</p>
-<pre class="verbatim"> $x =~ /^Who/m; # matches, "Who" at start
of second line
- $x =~ /\AWho/m; # doesn't match, "Who" is not at start of string
-
- $x =~ /girl$/m; # matches, "girl" at end of first line
- $x =~ /girl\Z/m; # doesn't match, "girl" is not at end of string
-
- $x =~ /Perl\Z/m; # matches, "Perl" is at newline before end
- $x =~ /Perl\z/m; # doesn't match, "Perl" is not at end of string
-</pre>
-<p>We now know how to create choices among classes of characters in a
-regexp. What about choices among words or character strings? Such
-choices are described in the next section.
-</p>
-<hr>
-<a name="perlretut-Matching-this-or-that"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Grouping-things-and-hierarchical-matching"
accesskey="n" rel="next">perlretut Grouping things and hierarchical
matching</a>, Previous: <a href="#perlretut-Using-character-classes"
accesskey="p" rel="prev">perlretut Using character classes</a>, Up: <a
href="#perlretut-Part-1_003a-The-basics" accesskey="u" rel="up">perlretut Part
1: The basics</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Matching-this-or-that-1"></a>
-<h4 class="subsection">68.3.3 Matching this or that</h4>
-
-<p>Sometimes we would like our regexp to be able to match different
-possible words or character strings. This is accomplished by using
-the <em>alternation</em> metacharacter <code>|</code>. To match
<code>dog</code> or <code>cat</code>, we
-form the regexp <code>dog|cat</code>. As before, Perl will try to match the
-regexp at the earliest possible point in the string. At each
-character position, Perl will first try to match the first
-alternative, <code>dog</code>. If <code>dog</code> doesn’t match, Perl
will then try the
-next alternative, <code>cat</code>. If <code>cat</code> doesn’t match
either, then the
-match fails and Perl moves to the next position in the string. Some
-examples:
-</p>
-<pre class="verbatim"> "cats and dogs" =~ /cat|dog|bird/; #
matches "cat"
- "cats and dogs" =~ /dog|cat|bird/; # matches "cat"
-</pre>
-<p>Even though <code>dog</code> is the first alternative in the second regexp,
-<code>cat</code> is able to match earlier in the string.
-</p>
-<pre class="verbatim"> "cats" =~ /c|ca|cat|cats/; #
matches "c"
- "cats" =~ /cats|cat|ca|c/; # matches "cats"
-</pre>
-<p>Here, all the alternatives match at the first string position, so the
-first alternative is the one that matches. If some of the
-alternatives are truncations of the others, put the longest ones first
-to give them a chance to match.
-</p>
-<pre class="verbatim"> "cab" =~ /a|b|c/ # matches "c"
- # /a|b|c/ == /[abc]/
-</pre>
-<p>The last example points out that character classes are like
-alternations of characters. At a given character position, the first
-alternative that allows the regexp match to succeed will be the one
-that matches.
-</p>
-<hr>
-<a name="perlretut-Grouping-things-and-hierarchical-matching"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Extracting-matches" accesskey="n"
rel="next">perlretut Extracting matches</a>, Previous: <a
href="#perlretut-Matching-this-or-that" accesskey="p" rel="prev">perlretut
Matching this or that</a>, Up: <a href="#perlretut-Part-1_003a-The-basics"
accesskey="u" rel="up">perlretut Part 1: The basics</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Grouping-things-and-hierarchical-matching-1"></a>
-<h4 class="subsection">68.3.4 Grouping things and hierarchical matching</h4>
-
-<p>Alternation allows a regexp to choose among alternatives, but by
-itself it is unsatisfying. The reason is that each alternative is a whole
-regexp, but sometime we want alternatives for just part of a
-regexp. For instance, suppose we want to search for housecats or
-housekeepers. The regexp <code>housecat|housekeeper</code> fits the bill, but
is
-inefficient because we had to type <code>house</code> twice. It would be nice
to
-have parts of the regexp be constant, like <code>house</code>, and some
-parts have alternatives, like <code>cat|keeper</code>.
-</p>
-<p>The <em>grouping</em> metacharacters <code>()</code> solve this problem.
Grouping
-allows parts of a regexp to be treated as a single unit. Parts of a
-regexp are grouped by enclosing them in parentheses. Thus we could solve
-the <code>housecat|housekeeper</code> by forming the regexp as
-<code>house(cat|keeper)</code>. The regexp <code>house(cat|keeper)</code>
means match
-<code>house</code> followed by either <code>cat</code> or <code>keeper</code>.
Some more examples
-are
-</p>
-<pre class="verbatim"> /(a|b)b/; # matches 'ab' or 'bb'
- /(ac|b)b/; # matches 'acb' or 'bb'
- /(^a|b)c/; # matches 'ac' at start of string or 'bc' anywhere
- /(a|[bc])d/; # matches 'ad', 'bd', or 'cd'
-
- /house(cat|)/; # matches either 'housecat' or 'house'
- /house(cat(s|)|)/; # matches either 'housecats' or 'housecat' or
- # 'house'. Note groups can be nested.
-
- /(19|20|)\d\d/; # match years 19xx, 20xx, or the Y2K problem, xx
- "20" =~ /(19|20|)\d\d/; # matches the null alternative '()\d\d',
- # because '20\d\d' can't match
-</pre>
-<p>Alternations behave the same way in groups as out of them: at a given
-string position, the leftmost alternative that allows the regexp to
-match is taken. So in the last example at the first string position,
-<code>"20"</code> matches the second alternative, but there is
nothing left over
-to match the next two digits <code>\d\d</code>. So Perl moves on to the next
-alternative, which is the null alternative and that works, since
-<code>"20"</code> is two digits.
-</p>
-<p>The process of trying one alternative, seeing if it matches, and
-moving on to the next alternative, while going back in the string
-from where the previous alternative was tried, if it doesn’t, is called
-<em>backtracking</em>. The term ’backtracking’ comes from the
idea that
-matching a regexp is like a walk in the woods. Successfully matching
-a regexp is like arriving at a destination. There are many possible
-trailheads, one for each string position, and each one is tried in
-order, left to right. From each trailhead there may be many paths,
-some of which get you there, and some which are dead ends. When you
-walk along a trail and hit a dead end, you have to backtrack along the
-trail to an earlier point to try another trail. If you hit your
-destination, you stop immediately and forget about trying all the
-other trails. You are persistent, and only if you have tried all the
-trails from all the trailheads and not arrived at your destination, do
-you declare failure. To be concrete, here is a step-by-step analysis
-of what Perl does when it tries to match the regexp
-</p>
-<pre class="verbatim"> "abcde" =~ /(abd|abc)(df|d|de)/;
-</pre>
-<dl compact="compact">
-<dt>0</dt>
-<dd><a name="perlretut-0"></a>
-<p>Start with the first letter in the string ’a’.
-</p>
-</dd>
-<dt>1</dt>
-<dd><a name="perlretut-1"></a>
-<p>Try the first alternative in the first group ’abd’.
-</p>
-</dd>
-<dt>2</dt>
-<dd><a name="perlretut-2"></a>
-<p>Match ’a’ followed by ’b’. So far so good.
-</p>
-</dd>
-<dt>3</dt>
-<dd><a name="perlretut-3"></a>
-<p>’d’ in the regexp doesn’t match ’c’ in the
string - a dead
-end. So backtrack two characters and pick the second alternative in
-the first group ’abc’.
-</p>
-</dd>
-<dt>4</dt>
-<dd><a name="perlretut-4"></a>
-<p>Match ’a’ followed by ’b’ followed by
’c’. We are on a roll
-and have satisfied the first group. Set $1 to ’abc’.
-</p>
-</dd>
-<dt>5</dt>
-<dd><a name="perlretut-5"></a>
-<p>Move on to the second group and pick the first alternative
-’df’.
-</p>
-</dd>
-<dt>6</dt>
-<dd><a name="perlretut-6"></a>
-<p>Match the ’d’.
-</p>
-</dd>
-<dt>7</dt>
-<dd><a name="perlretut-7"></a>
-<p>’f’ in the regexp doesn’t match ’e’ in the
string, so a dead
-end. Backtrack one character and pick the second alternative in the
-second group ’d’.
-</p>
-</dd>
-<dt>8</dt>
-<dd><a name="perlretut-8"></a>
-<p>’d’ matches. The second grouping is satisfied, so set $2 to
-’d’.
-</p>
-</dd>
-<dt>9</dt>
-<dd><a name="perlretut-9"></a>
-<p>We are at the end of the regexp, so we are done! We have
-matched ’abcd’ out of the string "abcde".
-</p>
-</dd>
-</dl>
-
-<p>There are a couple of things to note about this analysis. First, the
-third alternative in the second group ’de’ also allows a match,
but we
-stopped before we got to it - at a given character position, leftmost
-wins. Second, we were able to get a match at the first character
-position of the string ’a’. If there were no matches at the first
-position, Perl would move to the second character position ’b’ and
-attempt the match all over again. Only when all possible paths at all
-possible character positions have been exhausted does Perl give
-up and declare <code>$string =~ /(abd|abc)(df|d|de)/;</code><!-- /@w
--> to be false.
-</p>
-<p>Even with all this work, regexp matching happens remarkably fast. To
-speed things up, Perl compiles the regexp into a compact sequence of
-opcodes that can often fit inside a processor cache. When the code is
-executed, these opcodes can then run at full throttle and search very
-quickly.
-</p>
-<hr>
-<a name="perlretut-Extracting-matches"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Backreferences" accesskey="n" rel="next">perlretut
Backreferences</a>, Previous: <a
href="#perlretut-Grouping-things-and-hierarchical-matching" accesskey="p"
rel="prev">perlretut Grouping things and hierarchical matching</a>, Up: <a
href="#perlretut-Part-1_003a-The-basics" accesskey="u" rel="up">perlretut Part
1: The basics</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Extracting-matches-1"></a>
-<h4 class="subsection">68.3.5 Extracting matches</h4>
-
-<p>The grouping metacharacters <code>()</code> also serve another completely
-different function: they allow the extraction of the parts of a string
-that matched. This is very useful to find out what matched and for
-text processing in general. For each grouping, the part that matched
-inside goes into the special variables <code>$1</code>, <code>$2</code>, etc.
They can be
-used just as ordinary variables:
-</p>
-<pre class="verbatim"> # extract hours, minutes, seconds
- if ($time =~ /(\d\d):(\d\d):(\d\d)/) { # match hh:mm:ss format
- $hours = $1;
- $minutes = $2;
- $seconds = $3;
- }
-</pre>
-<p>Now, we know that in scalar context,
-<code>$time =~ /(\d\d):(\d\d):(\d\d)/</code><!-- /@w --> returns a
true or false
-value. In list context, however, it returns the list of matched values
-<code>($1,$2,$3)</code>. So we could write the code more compactly as
-</p>
-<pre class="verbatim"> # extract hours, minutes, seconds
- ($hours, $minutes, $second) = ($time =~ /(\d\d):(\d\d):(\d\d)/);
-</pre>
-<p>If the groupings in a regexp are nested, <code>$1</code> gets the group
with the
-leftmost opening parenthesis, <code>$2</code> the next opening parenthesis,
-etc. Here is a regexp with nested groups:
-</p>
-<pre class="verbatim"> /(ab(cd|ef)((gi)|j))/;
- 1 2 34
-</pre>
-<p>If this regexp matches, <code>$1</code> contains a string starting with
-<code>'ab'</code>, <code>$2</code> is either set to <code>'cd'</code> or
<code>'ef'</code>, <code>$3</code> equals either
-<code>'gi'</code> or <code>'j'</code>, and <code>$4</code> is either set to
<code>'gi'</code>, just like <code>$3</code>,
-or it remains undefined.
-</p>
-<p>For convenience, Perl sets <code>$+</code> to the string held by the
highest numbered
-<code>$1</code>, <code>$2</code>,... that got assigned (and, somewhat related,
<code>$^N</code> to the
-value of the <code>$1</code>, <code>$2</code>,... most-recently assigned; i.e.
the <code>$1</code>,
-<code>$2</code>,... associated with the rightmost closing parenthesis used in
the
-match).
-</p>
-<hr>
-<a name="perlretut-Backreferences"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Relative-backreferences" accesskey="n"
rel="next">perlretut Relative backreferences</a>, Previous: <a
href="#perlretut-Extracting-matches" accesskey="p" rel="prev">perlretut
Extracting matches</a>, Up: <a href="#perlretut-Part-1_003a-The-basics"
accesskey="u" rel="up">perlretut Part 1: The basics</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Backreferences"></a>
-<h4 class="subsection">68.3.6 Backreferences</h4>
-
-<p>Closely associated with the matching variables <code>$1</code>,
<code>$2</code>, ... are
-the <em>backreferences</em> <code>\g1</code>, <code>\g2</code>,...
Backreferences are simply
-matching variables that can be used <em>inside</em> 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:
-</p>
-<pre class="verbatim"> /\b(\w\w\w)\s\g1\b/;
-</pre>
-<p>The grouping assigns a value to \g1, so that the same 3-letter sequence
-is used for both parts.
-</p>
-<p>A similar task is to find words consisting of two identical parts:
-</p>
-<pre class="verbatim"> % simple_grep '^(\w\w\w\w|\w\w\w|\w\w|\w)\g1$'
/usr/dict/words
- beriberi
- booboo
- coco
- mama
- murmur
- papa
-</pre>
-<p>The regexp has a single grouping which considers 4-letter
-combinations, then 3-letter combinations, etc., and uses <code>\g1</code> to
look for
-a repeat. Although <code>$1</code> and <code>\g1</code> represent the same
thing, care should be
-taken to use matched variables <code>$1</code>, <code>$2</code>,... only
<em>outside</em> a regexp
-and backreferences <code>\g1</code>, <code>\g2</code>,... only <em>inside</em>
a regexp; not doing
-so may lead to surprising and unsatisfactory results.
-</p>
-<hr>
-<a name="perlretut-Relative-backreferences"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Named-backreferences" accesskey="n"
rel="next">perlretut Named backreferences</a>, Previous: <a
href="#perlretut-Backreferences" accesskey="p" rel="prev">perlretut
Backreferences</a>, Up: <a href="#perlretut-Part-1_003a-The-basics"
accesskey="u" rel="up">perlretut Part 1: The basics</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Relative-backreferences"></a>
-<h4 class="subsection">68.3.7 Relative backreferences</h4>
-
-<p>Counting the opening parentheses to get the correct number for a
-backreference is error-prone as soon as there is more than one
-capturing group. A more convenient technique became available
-with Perl 5.10: relative backreferences. To refer to the immediately
-preceding capture group one now may write <code>\g{-1}</code>, the next but
-last is available via <code>\g{-2}</code>, and so on.
-</p>
-<p>Another good reason in addition to readability and maintainability
-for using relative backreferences is illustrated by the following example,
-where a simple pattern for matching peculiar strings is used:
-</p>
-<pre class="verbatim"> $a99a = '([a-z])(\d)\g2\g1'; # matches a11a, g22g,
x33x, etc.
-</pre>
-<p>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:
-</p>
-<pre class="verbatim"> $line = "code=e99e";
- if ($line =~ /^(\w+)=$a99a$/){ # unexpected behavior!
- print "$1 is valid\n";
- } else {
- print "bad line: '$line'\n";
- }
-</pre>
-<p>But this doesn’t match, at least not the way one might expect. Only
-after inserting the interpolated <code>$a99a</code> and looking at the
resulting
-full text of the regexp is it obvious that the backreferences have
-backfired. The subexpression <code>(\w+)</code> has snatched number 1 and
-demoted the groups in <code>$a99a</code> by one rank. This can be avoided by
-using relative backreferences:
-</p>
-<pre class="verbatim"> $a99a = '([a-z])(\d)\g{-1}\g{-2}'; # safe for being
interpolated
-</pre>
-<hr>
-<a name="perlretut-Named-backreferences"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Alternative-capture-group-numbering" accesskey="n"
rel="next">perlretut Alternative capture group numbering</a>, Previous: <a
href="#perlretut-Relative-backreferences" accesskey="p" rel="prev">perlretut
Relative backreferences</a>, Up: <a href="#perlretut-Part-1_003a-The-basics"
accesskey="u" rel="up">perlretut Part 1: The basics</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Named-backreferences"></a>
-<h4 class="subsection">68.3.8 Named backreferences</h4>
-
-<p>Perl 5.10 also introduced named capture groups and named backreferences.
-To attach a name to a capturing group, you write either
-<code>(?<name>...)</code> or <code>(?'name'...)</code>. The
backreference may
-then be written as <code>\g{name}</code>. 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 group is accessible through the <code>%+</code> hash.
-</p>
-<p>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 groups capturing the pertaining components of a date. The
-matching operation combines the three patterns as alternatives:
-</p>
-<pre class="verbatim"> $fmt1 =
'(?<y>\d\d\d\d)-(?<m>\d\d)-(?<d>\d\d)';
- $fmt2 = '(?<m>\d\d)/(?<d>\d\d)/(?<y>\d\d\d\d)';
- $fmt3 = '(?<d>\d\d)\.(?<m>\d\d)\.(?<y>\d\d\d\d)';
- for my $d qw( 2006-10-21 15.01.2007 10/31/2005 ){
- if ( $d =~ m{$fmt1|$fmt2|$fmt3} ){
- print "day=$+{d} month=$+{m} year=$+{y}\n";
- }
- }
-</pre>
-<p>If any of the alternatives matches, the hash <code>%+</code> is bound to
contain the
-three key-value pairs.
-</p>
-<hr>
-<a name="perlretut-Alternative-capture-group-numbering"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Position-information" accesskey="n"
rel="next">perlretut Position information</a>, Previous: <a
href="#perlretut-Named-backreferences" accesskey="p" rel="prev">perlretut Named
backreferences</a>, Up: <a href="#perlretut-Part-1_003a-The-basics"
accesskey="u" rel="up">perlretut Part 1: The basics</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Alternative-capture-group-numbering"></a>
-<h4 class="subsection">68.3.9 Alternative capture group numbering</h4>
-
-<p>Yet another capturing group numbering technique (also as from Perl 5.10)
-deals with the problem of referring to groups within a set of alternatives.
-Consider a pattern for matching a time of the day, civil or military style:
-</p>
-<pre class="verbatim"> if ( $time =~ /(\d\d|\d):(\d\d)|(\d\d)(\d\d)/ ){
- # process hour and minute
- }
-</pre>
-<p>Processing the results requires an additional if statement to determine
-whether <code>$1</code> and <code>$2</code> or <code>$3</code> and
<code>$4</code> contain the goodies. It would
-be easier if we could use group numbers 1 and 2 in second alternative as
-well, and this is exactly what the parenthesized construct
<code>(?|...)</code>,
-set around an alternative achieves. Here is an extended version of the
-previous pattern:
-</p>
-<pre class="verbatim"> if($time =~
/(?|(\d\d|\d):(\d\d)|(\d\d)(\d\d))\s+([A-Z][A-Z][A-Z])/){
- print "hour=$1 minute=$2 zone=$3\n";
- }
-</pre>
-<p>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.
-</p>
-<hr>
-<a name="perlretut-Position-information"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Non_002dcapturing-groupings" accesskey="n"
rel="next">perlretut Non-capturing groupings</a>, Previous: <a
href="#perlretut-Alternative-capture-group-numbering" accesskey="p"
rel="prev">perlretut Alternative capture group numbering</a>, Up: <a
href="#perlretut-Part-1_003a-The-basics" accesskey="u" rel="up">perlretut Part
1: The basics</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Position-information"></a>
-<h4 class="subsection">68.3.10 Position information</h4>
-
-<p>In addition to what was matched, Perl also provides the
-positions of what was matched as contents of the <code>@-</code> and
<code>@+</code>
-arrays. <code>$-[0]</code> is the position of the start of the entire match and
-<code>$+[0]</code> is the position of the end. Similarly, <code>$-[n]</code>
is the
-position of the start of the <code>$n</code> match and <code>$+[n]</code> is
the position
-of the end. If <code>$n</code> is undefined, so are <code>$-[n]</code> and
<code>$+[n]</code>. Then
-this code
-</p>
-<pre class="verbatim"> $x = "Mmm...donut, thought Homer";
- $x =~ /^(Mmm|Yech)\.\.\.(donut|peas)/; # matches
- foreach $exp (1..$#-) {
- print "Match $exp: '${$exp}' at position
($-[$exp],$+[$exp])\n";
- }
-</pre>
-<p>prints
-</p>
-<pre class="verbatim"> Match 1: 'Mmm' at position (0,3)
- Match 2: 'donut' at position (6,11)
-</pre>
-<p>Even if there are no groupings in a regexp, it is still possible to
-find out what exactly matched in a string. If you use them, Perl
-will set <code>$`</code> to the part of the string before the match, will set
<code>$&</code>
-to the part of the string that matched, and will set <code>$'</code> to the
part
-of the string after the match. An example:
-</p>
-<pre class="verbatim"> $x = "the cat caught the mouse";
- $x =~ /cat/; # $` = 'the ', $& = 'cat', $' = ' caught the mouse'
- $x =~ /the/; # $` = '', $& = 'the', $' = ' cat caught the mouse'
-</pre>
-<p>In the second match, <code>$`</code> equals <code>''</code> because the
regexp matched at the
-first character position in the string and stopped; it never saw the
-second ’the’.
-</p>
-<p>If your code is to run on Perl versions earlier than
-5.20, it is worthwhile to note that using <code>$`</code> and <code>$'</code>
-slows down regexp matching quite a bit, while <code>$&</code> slows it
down to a
-lesser extent, because if they are used in one regexp in a program,
-they are generated for <em>all</em> regexps in the program. So if raw
-performance is a goal of your application, they should be avoided.
-If you need to extract the corresponding substrings, use <code>@-</code> and
-<code>@+</code> instead:
-</p>
-<pre class="verbatim"> $` is the same as substr( $x, 0, $-[0] )
- $& is the same as substr( $x, $-[0], $+[0]-$-[0] )
- $' is the same as substr( $x, $+[0] )
-</pre>
-<p>As of Perl 5.10, the <code>${^PREMATCH}</code>, <code>${^MATCH}</code> and
<code>${^POSTMATCH}</code>
-variables may be used. These are only set if the <code>/p</code> modifier is
-present. Consequently they do not penalize the rest of the program. In
-Perl 5.20, <code>${^PREMATCH}</code>, <code>${^MATCH}</code> and
<code>${^POSTMATCH}</code> are available
-whether the <code>/p</code> has been used or not (the modifier is ignored), and
-<code>$`</code>, <code>$'</code> and <code>$&</code> do not cause any
speed difference.
-</p>
-<hr>
-<a name="perlretut-Non_002dcapturing-groupings"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Matching-repetitions" accesskey="n"
rel="next">perlretut Matching repetitions</a>, Previous: <a
href="#perlretut-Position-information" accesskey="p" rel="prev">perlretut
Position information</a>, Up: <a href="#perlretut-Part-1_003a-The-basics"
accesskey="u" rel="up">perlretut Part 1: The basics</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Non_002dcapturing-groupings"></a>
-<h4 class="subsection">68.3.11 Non-capturing groupings</h4>
-
-<p>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 group values, inside as well as
-outside the regexp. Non-capturing groupings, denoted by
<code>(?:regexp)</code>,
-still allow the regexp to be treated as a single unit, but don’t
establish
-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
-which parts of a regexp are to be extracted to matching variables:
-</p>
-<pre class="verbatim"> # match a number, $1-$4 are set, but we only want $1
- /([+-]?\ *(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?)/;
-
- # match a number faster , only $1 is set
- /([+-]?\ *(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)/;
-
- # match a number, get $1 = whole number, $2 = exponent
- /([+-]?\ *(?:\d+(?:\.\d*)?|\.\d+)(?:[eE]([+-]?\d+))?)/;
-</pre>
-<p>Non-capturing groupings are also useful for removing nuisance
-elements gathered from a split operation where parentheses are
-required for some reason:
-</p>
-<pre class="verbatim"> $x = '12aba34ba5';
- @num = split /(a|b)+/, $x; # @num = ('12','a','34','a','5')
- @num = split /(?:a|b)+/, $x; # @num = ('12','34','5')
-</pre>
-<p>In Perl 5.22 and later, all groups within a regexp can be set to
-non-capturing by using the new <code>/n</code> flag:
-</p>
-<pre class="verbatim"> "hello" =~ /(hi|hello)/n; # $1 is not set!
-</pre>
-<p>See <a href="#perlre-n">perlre n</a> for more information.
-</p>
-<hr>
-<a name="perlretut-Matching-repetitions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Possessive-quantifiers" accesskey="n"
rel="next">perlretut Possessive quantifiers</a>, Previous: <a
href="#perlretut-Non_002dcapturing-groupings" accesskey="p"
rel="prev">perlretut Non-capturing groupings</a>, Up: <a
href="#perlretut-Part-1_003a-The-basics" accesskey="u" rel="up">perlretut Part
1: The basics</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Matching-repetitions-1"></a>
-<h4 class="subsection">68.3.12 Matching repetitions</h4>
-
-<p>The examples in the previous section display an annoying weakness. We
-were only matching 3-letter words, or chunks of words of 4 letters or
-less. We’d like to be able to match words or, more generally, strings
-of any length, without writing out tedious alternatives like
-<code>\w\w\w\w|\w\w\w|\w\w|\w</code>.
-</p>
-<p>This is exactly the problem the <em>quantifier</em> metacharacters
<code>?</code>,
-<code>*</code>, <code>+</code>, and <code>{}</code> were created for. They
allow us to delimit the
-number of repeats for a portion of a regexp we consider to be a
-match. Quantifiers are put immediately after the character, character
-class, or grouping that we want to specify. They have the following
-meanings:
-</p>
-<ul>
-<li> <code>a?</code> means: match ’a’ 1 or 0 times
-
-</li><li> <code>a*</code> means: match ’a’ 0 or more times, i.e.,
any number of times
-
-</li><li> <code>a+</code> means: match ’a’ 1 or more times, i.e.,
at least once
-
-</li><li> <code>a{n,m}</code> means: match at least <code>n</code> times, but
not more than <code>m</code>
-times.
-
-</li><li> <code>a{n,}</code> means: match at least <code>n</code> or more times
-
-</li><li> <code>a{n}</code> means: match exactly <code>n</code> times
-
-</li></ul>
-
-<p>Here are some examples:
-</p>
-<pre class="verbatim"> /[a-z]+\s+\d*/; # match a lowercase word, at least
one space, and
- # any number of digits
- /(\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 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
- mama
- murmur
- papa
-</pre>
-<p>For all of these quantifiers, Perl will try to match as much of the
-string as possible, while still allowing the regexp to succeed. Thus
-with <code>/a?.../</code>, Perl will first try to match the regexp with the
<code>a</code>
-present; if that fails, Perl will try to match the regexp without the
-<code>a</code> present. For the quantifier <code>*</code>, we get the
following:
-</p>
-<pre class="verbatim"> $x = "the cat in the hat";
- $x =~ /^(.*)(cat)(.*)$/; # matches,
- # $1 = 'the '
- # $2 = 'cat'
- # $3 = ' in the hat'
-</pre>
-<p>Which is what we might expect, the match finds the only <code>cat</code> in
the
-string and locks onto it. Consider, however, this regexp:
-</p>
-<pre class="verbatim"> $x =~ /^(.*)(at)(.*)$/; # matches,
- # $1 = 'the cat in the h'
- # $2 = 'at'
- # $3 = '' (0 characters match)
-</pre>
-<p>One might initially guess that Perl would find the <code>at</code> in
<code>cat</code> and
-stop there, but that wouldn’t give the longest possible string to the
-first quantifier <code>.*</code>. Instead, the first quantifier
<code>.*</code> grabs as
-much of the string as possible while still having the regexp match. In
-this example, that means having the <code>at</code> sequence with the final
<code>at</code>
-in the string. The other important principle illustrated here is that,
-when there are two or more elements in a regexp, the <em>leftmost</em>
-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 <code>.*</code> grabs most of the string,
while
-the second quantifier <code>.*</code> gets the empty string. Quantifiers that
-grab as much of the string as possible are called <em>maximal match</em> or
-<em>greedy</em> quantifiers.
-</p>
-<p>When a regexp can match a string in several different ways, we can use
-the principles above to predict which way the regexp will match:
-</p>
-<ul>
-<li> Principle 0: Taken as a whole, any regexp will be matched at the
-earliest possible position in the string.
-
-</li><li> Principle 1: In an alternation <code>a|b|c...</code>, the leftmost
alternative
-that allows a match for the whole regexp will be the one used.
-
-</li><li> Principle 2: The maximal matching quantifiers <code>?</code>,
<code>*</code>, <code>+</code> and
-<code>{n,m}</code> will in general match as much of the string as possible
while
-still allowing the whole regexp to match.
-
-</li><li> Principle 3: If there are two or more elements in a regexp, the
-leftmost greedy quantifier, if any, will match as much of the string
-as possible while still allowing the whole regexp to match. The next
-leftmost greedy quantifier, if any, will try to match as much of the
-string remaining available to it as possible, while still allowing the
-whole regexp to match. And so on, until all the regexp elements are
-satisfied.
-
-</li></ul>
-
-<p>As we have seen above, Principle 0 overrides the others. The regexp
-will be matched as early as possible, with the other principles
-determining how the regexp matches at that earliest character
-position.
-</p>
-<p>Here is an example of these principles in action:
-</p>
-<pre class="verbatim"> $x = "The programming republic of Perl";
- $x =~ /^(.+)(e|r)(.*)$/; # matches,
- # $1 = 'The programming republic of Pe'
- # $2 = 'r'
- # $3 = 'l'
-</pre>
-<p>This regexp matches at the earliest string position, <code>'T'</code>. One
-might think that <code>e</code>, being leftmost in the alternation, would be
-matched, but <code>r</code> produces the longest string in the first
quantifier.
-</p>
-<pre class="verbatim"> $x =~ /(m{1,2})(.*)$/; # matches,
- # $1 = 'mm'
- # $2 = 'ing republic of Perl'
-</pre>
-<p>Here, The earliest possible match is at the first <code>'m'</code> in
-<code>programming</code>. <code>m{1,2}</code> is the first quantifier, so it
gets to match
-a maximal <code>mm</code>.
-</p>
-<pre class="verbatim"> $x =~ /.*(m{1,2})(.*)$/; # matches,
- # $1 = 'm'
- # $2 = 'ing republic of Perl'
-</pre>
-<p>Here, the regexp matches at the start of the string. The first
-quantifier <code>.*</code> grabs as much as possible, leaving just a single
-<code>'m'</code> for the second quantifier <code>m{1,2}</code>.
-</p>
-<pre class="verbatim"> $x =~ /(.?)(m{1,2})(.*)$/; # matches,
- # $1 = 'a'
- # $2 = 'mm'
- # $3 = 'ing republic of Perl'
-</pre>
-<p>Here, <code>.?</code> eats its maximal one character at the earliest
possible
-position in the string, <code>'a'</code> in <code>programming</code>, leaving
<code>m{1,2}</code>
-the opportunity to match both <code>m</code>’s. Finally,
-</p>
-<pre class="verbatim"> "aXXXb" =~ /(X*)/; # matches with $1 = ''
-</pre>
-<p>because it can match zero copies of <code>'X'</code> at the beginning of the
-string. If you definitely want to match at least one <code>'X'</code>, use
-<code>X+</code>, not <code>X*</code>.
-</p>
-<p>Sometimes greed is not good. At times, we would like quantifiers to
-match a <em>minimal</em> piece of string, rather than a maximal piece. For
-this purpose, Larry Wall created the <em>minimal match</em> or
-<em>non-greedy</em> quantifiers <code>??</code>, <code>*?</code>,
<code>+?</code>, and <code>{}?</code>. These are
-the usual quantifiers with a <code>?</code> appended to them. They have the
-following meanings:
-</p>
-<ul>
-<li> <code>a??</code> means: match ’a’ 0 or 1 times. Try 0 first,
then 1.
-
-</li><li> <code>a*?</code> means: match ’a’ 0 or more times, i.e.,
any number of times,
-but as few times as possible
-
-</li><li> <code>a+?</code> means: match ’a’ 1 or more times, i.e.,
at least once, but
-as few times as possible
-
-</li><li> <code>a{n,m}?</code> means: match at least <code>n</code> times, not
more than <code>m</code>
-times, as few times as possible
-
-</li><li> <code>a{n,}?</code> means: match at least <code>n</code> times, but
as few times as
-possible
-
-</li><li> <code>a{n}?</code> means: match exactly <code>n</code> times.
Because we match exactly
-<code>n</code> times, <code>a{n}?</code> is equivalent to <code>a{n}</code>
and is just there for
-notational consistency.
-
-</li></ul>
-
-<p>Let’s look at the example above, but with minimal quantifiers:
-</p>
-<pre class="verbatim"> $x = "The programming republic of Perl";
- $x =~ /^(.+?)(e|r)(.*)$/; # matches,
- # $1 = 'Th'
- # $2 = 'e'
- # $3 = ' programming republic of Perl'
-</pre>
-<p>The minimal string that will allow both the start of the string
<code>^</code>
-and the alternation to match is <code>Th</code>, with the alternation
<code>e|r</code>
-matching <code>e</code>. The second quantifier <code>.*</code> is free to
gobble up the
-rest of the string.
-</p>
-<pre class="verbatim"> $x =~ /(m{1,2}?)(.*?)$/; # matches,
- # $1 = 'm'
- # $2 = 'ming republic of Perl'
-</pre>
-<p>The first string position that this regexp can match is at the first
-<code>'m'</code> in <code>programming</code>. At this position, the minimal
<code>m{1,2}?</code>
-matches just one <code>'m'</code>. Although the second quantifier
<code>.*?</code> would
-prefer to match no characters, it is constrained by the end-of-string
-anchor <code>$</code> to match the rest of the string.
-</p>
-<pre class="verbatim"> $x =~ /(.*?)(m{1,2}?)(.*)$/; # matches,
- # $1 = 'The progra'
- # $2 = 'm'
- # $3 = 'ming republic of Perl'
-</pre>
-<p>In this regexp, you might expect the first minimal quantifier
<code>.*?</code>
-to match the empty string, because it is not constrained by a <code>^</code>
-anchor to match the beginning of the word. Principle 0 applies here,
-however. Because it is possible for the whole regexp to match at the
-start of the string, it <em>will</em> match at the start of the string. Thus
-the first quantifier has to match everything up to the first <code>m</code>.
The
-second minimal quantifier matches just one <code>m</code> and the third
-quantifier matches the rest of the string.
-</p>
-<pre class="verbatim"> $x =~ /(.??)(m{1,2})(.*)$/; # matches,
- # $1 = 'a'
- # $2 = 'mm'
- # $3 = 'ing republic of Perl'
-</pre>
-<p>Just as in the previous regexp, the first quantifier <code>.??</code> can
match
-earliest at position <code>'a'</code>, so it does. The second quantifier is
-greedy, so it matches <code>mm</code>, and the third matches the rest of the
-string.
-</p>
-<p>We can modify principle 3 above to take into account non-greedy
-quantifiers:
-</p>
-<ul>
-<li> Principle 3: If there are two or more elements in a regexp, the
-leftmost greedy (non-greedy) quantifier, if any, will match as much
-(little) of the string as possible while still allowing the whole
-regexp to match. The next leftmost greedy (non-greedy) quantifier, if
-any, will try to match as much (little) of the string remaining
-available to it as possible, while still allowing the whole regexp to
-match. And so on, until all the regexp elements are satisfied.
-
-</li></ul>
-
-<p>Just like alternation, quantifiers are also susceptible to
-backtracking. Here is a step-by-step analysis of the example
-</p>
-<pre class="verbatim"> $x = "the cat in the hat";
- $x =~ /^(.*)(at)(.*)$/; # matches,
- # $1 = 'the cat in the h'
- # $2 = 'at'
- # $3 = '' (0 matches)
-</pre>
-<dl compact="compact">
-<dt>0</dt>
-<dd><a name="perlretut-0-1"></a>
-<p>Start with the first letter in the string ’t’.
-</p>
-</dd>
-<dt>1</dt>
-<dd><a name="perlretut-1-1"></a>
-<p>The first quantifier ’.*’ starts out by matching the whole
-string ’the cat in the hat’.
-</p>
-</dd>
-<dt>2</dt>
-<dd><a name="perlretut-2-1"></a>
-<p>’a’ in the regexp element ’at’ doesn’t match
the end of the
-string. Backtrack one character.
-</p>
-</dd>
-<dt>3</dt>
-<dd><a name="perlretut-3-1"></a>
-<p>’a’ in the regexp element ’at’ still doesn’t
match the last
-letter of the string ’t’, so backtrack one more character.
-</p>
-</dd>
-<dt>4</dt>
-<dd><a name="perlretut-4-1"></a>
-<p>Now we can match the ’a’ and the ’t’.
-</p>
-</dd>
-<dt>5</dt>
-<dd><a name="perlretut-5-1"></a>
-<p>Move on to the third element ’.*’. Since we are at the end of
-the string and ’.*’ can match 0 times, assign it the empty string.
-</p>
-</dd>
-<dt>6</dt>
-<dd><a name="perlretut-6-1"></a>
-<p>We are done!
-</p>
-</dd>
-</dl>
-
-<p>Most of the time, all this moving forward and backtracking happens
-quickly and searching is fast. There are some pathological regexps,
-however, whose execution time exponentially grows with the size of the
-string. A typical structure that blows up in your face is of the form
-</p>
-<pre class="verbatim"> /(a|b+)*/;
-</pre>
-<p>The problem is the nested indeterminate quantifiers. There are many
-different ways of partitioning a string of length n between the <code>+</code>
-and <code>*</code>: one repetition with <code>b+</code> of length n, two
repetitions with
-the first <code>b+</code> length k and the second with length n-k, m
repetitions
-whose bits add up to length n, etc. In fact there are an exponential
-number of ways to partition a string as a function of its length. A
-regexp may get lucky and match early in the process, but if there is
-no match, Perl will try <em>every</em> possibility before giving up. So be
-careful with nested <code>*</code>’s, <code>{n,m}</code>’s, and
<code>+</code>’s. The book
-<em>Mastering Regular Expressions</em> by Jeffrey Friedl gives a wonderful
-discussion of this and other efficiency issues.
-</p>
-<hr>
-<a name="perlretut-Possessive-quantifiers"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Building-a-regexp" accesskey="n"
rel="next">perlretut Building a regexp</a>, Previous: <a
href="#perlretut-Matching-repetitions" accesskey="p" rel="prev">perlretut
Matching repetitions</a>, Up: <a href="#perlretut-Part-1_003a-The-basics"
accesskey="u" rel="up">perlretut Part 1: The basics</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Possessive-quantifiers"></a>
-<h4 class="subsection">68.3.13 Possessive quantifiers</h4>
-
-<p>Backtracking during the relentless search for a match may be a waste
-of time, particularly when the match is bound to fail. Consider
-the simple pattern
-</p>
-<pre class="verbatim"> /^\w+\s+\w+$/; # a word, spaces, a word
-</pre>
-<p>Whenever this is applied to a string which doesn’t quite meet the
-pattern’s expectations such as
<code>"abc "</code><!-- /@w --> or
<code>"abc def "</code><!-- /@w -->,
-the regex engine will backtrack, approximately once for each character
-in the string. But we know that there is no way around taking <em>all</em>
-of the initial word characters to match the first repetition, that <em>all</em>
-spaces must be eaten by the middle part, and the same goes for the second
-word.
-</p>
-<p>With the introduction of the <em>possessive quantifiers</em> in Perl 5.10,
we
-have a way of instructing the regex engine not to backtrack, with the
-usual quantifiers with a <code>+</code> appended to them. This makes them
greedy as
-well as stingy; once they succeed they won’t give anything back to permit
-another solution. They have the following meanings:
-</p>
-<ul>
-<li> <code>a{n,m}+</code> means: match at least <code>n</code> times, not more
than <code>m</code> times,
-as many times as possible, and don’t give anything up. <code>a?+</code>
is short
-for <code>a{0,1}+</code>
-
-</li><li> <code>a{n,}+</code> means: match at least <code>n</code> times, but
as many times as possible,
-and don’t give anything up. <code>a*+</code> is short for
<code>a{0,}+</code> and <code>a++</code> is
-short for <code>a{1,}+</code>.
-
-</li><li> <code>a{n}+</code> means: match exactly <code>n</code> times. It is
just there for
-notational consistency.
-
-</li></ul>
-
-<p>These possessive quantifiers represent a special case of a more general
-concept, the <em>independent subexpression</em>, see below.
-</p>
-<p>As an example where a possessive quantifier is suitable we consider
-matching a quoted string, as it appears in several programming languages.
-The backslash is used as an escape character that indicates that the
-next character is to be taken literally, as another character for the
-string. Therefore, after the opening quote, we expect a (possibly
-empty) sequence of alternatives: either some character except an
-unescaped quote or backslash or an escaped character.
-</p>
-<pre class="verbatim"> /"(?:[^"\\]++|\\.)*+"/;
-</pre>
-<hr>
-<a name="perlretut-Building-a-regexp"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Using-regular-expressions-in-Perl" accesskey="n"
rel="next">perlretut Using regular expressions in Perl</a>, Previous: <a
href="#perlretut-Possessive-quantifiers" accesskey="p" rel="prev">perlretut
Possessive quantifiers</a>, Up: <a href="#perlretut-Part-1_003a-The-basics"
accesskey="u" rel="up">perlretut Part 1: The basics</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Building-a-regexp"></a>
-<h4 class="subsection">68.3.14 Building a regexp</h4>
-
-<p>At this point, we have all the basic regexp concepts covered, so let’s
-give a more involved example of a regular expression. We will build a
-regexp that matches numbers.
-</p>
-<p>The first task in building a regexp is to decide what we want to match
-and what we want to exclude. In our case, we want to match both
-integers and floating point numbers and we want to reject any string
-that isn’t a number.
-</p>
-<p>The next task is to break the problem down into smaller problems that
-are easily converted into a regexp.
-</p>
-<p>The simplest case is integers. These consist of a sequence of digits,
-with an optional sign in front. The digits we can represent with
-<code>\d+</code> and the sign can be matched with <code>[+-]</code>. Thus the
integer
-regexp is
-</p>
-<pre class="verbatim"> /[+-]?\d+/; # matches integers
-</pre>
-<p>A floating point number potentially has a sign, an integral part, a
-decimal point, a fractional part, and an exponent. One or more of these
-parts is optional, so we need to check out the different
-possibilities. Floating point numbers which are in proper form include
-123., 0.345, .34, -1e6, and 25.4E-72. As with integers, the sign out
-front is completely optional and can be matched by <code>[+-]?</code>. We can
-see that if there is no exponent, floating point numbers must have a
-decimal point, otherwise they are integers. We might be tempted to
-model these with <code>\d*\.\d*</code>, but this would also match just a single
-decimal point, which is not a number. So the three cases of floating
-point number without exponent are
-</p>
-<pre class="verbatim"> /[+-]?\d+\./; # 1., 321., etc.
- /[+-]?\.\d+/; # .1, .234, etc.
- /[+-]?\d+\.\d+/; # 1.0, 30.56, etc.
-</pre>
-<p>These can be combined into a single regexp with a three-way alternation:
-</p>
-<pre class="verbatim"> /[+-]?(\d+\.\d+|\d+\.|\.\d+)/; # floating point, no
exponent
-</pre>
-<p>In this alternation, it is important to put <code>'\d+\.\d+'</code> before
-<code>'\d+\.'</code>. If <code>'\d+\.'</code> were first, the regexp would
happily match that
-and ignore the fractional part of the number.
-</p>
-<p>Now consider floating point numbers with exponents. The key
-observation here is that <em>both</em> integers and numbers with decimal
-points are allowed in front of an exponent. Then exponents, like the
-overall sign, are independent of whether we are matching numbers with
-or without decimal points, and can be ’decoupled’ from the
-mantissa. The overall form of the regexp now becomes clear:
-</p>
-<pre class="verbatim"> /^(optional sign)(integer | f.p. mantissa)(optional
exponent)$/;
-</pre>
-<p>The exponent is an <code>e</code> or <code>E</code>, followed by an
integer. So the
-exponent regexp is
-</p>
-<pre class="verbatim"> /[eE][+-]?\d+/; # exponent
-</pre>
-<p>Putting all the parts together, we get a regexp that matches numbers:
-</p>
-<pre class="verbatim"> /^[+-]?(\d+\.\d+|\d+\.|\.\d+|\d+)([eE][+-]?\d+)?$/;
# Ta da!
-</pre>
-<p>Long regexps like this may impress your friends, but can be hard to
-decipher. In complex situations like this, the <code>//x</code> modifier for a
-match is invaluable. It allows one to put nearly arbitrary whitespace
-and comments into a regexp without affecting their meaning. Using it,
-we can rewrite our ’extended’ regexp in the more pleasing form
-</p>
-<pre class="verbatim"> /^
- [+-]? # first, match an optional sign
- ( # then match integers or f.p. mantissas:
- \d+\.\d+ # mantissa of the form a.b
- |\d+\. # mantissa of the form a.
- |\.\d+ # mantissa of the form .b
- |\d+ # integer of the form a
- )
- ([eE][+-]?\d+)? # finally, optionally match an exponent
- $/x;
-</pre>
-<p>If whitespace is mostly irrelevant, how does one include space
-characters in an extended regexp? The answer is to backslash it
-<code>'\ '</code><!-- /@w --> or put it in a character class
<code>[ ]</code><!-- /@w -->. The same thing
-goes for pound signs: use <code>\#</code> or <code>[#]</code>. For instance,
Perl allows
-a space between the sign and the mantissa or integer, and we could add
-this to our regexp as follows:
-</p>
-<pre class="verbatim"> /^
- [+-]?\ * # first, match an optional sign *and space*
- ( # then match integers or f.p. mantissas:
- \d+\.\d+ # mantissa of the form a.b
- |\d+\. # mantissa of the form a.
- |\.\d+ # mantissa of the form .b
- |\d+ # integer of the form a
- )
- ([eE][+-]?\d+)? # finally, optionally match an exponent
- $/x;
-</pre>
-<p>In this form, it is easier to see a way to simplify the
-alternation. Alternatives 1, 2, and 4 all start with <code>\d+</code>, so it
-could be factored out:
-</p>
-<pre class="verbatim"> /^
- [+-]?\ * # first, match an optional sign
- ( # then match integers or f.p. mantissas:
- \d+ # start out with a ...
- (
- \.\d* # mantissa of the form a.b or a.
- )? # ? takes care of integers of the form a
- |\.\d+ # mantissa of the form .b
- )
- ([eE][+-]?\d+)? # finally, optionally match an exponent
- $/x;
-</pre>
-<p>or written in the compact form,
-</p>
-<pre class="verbatim"> /^[+-]?\ *(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$/;
-</pre>
-<p>This is our final regexp. To recap, we built a regexp by
-</p>
-<ul>
-<li> specifying the task in detail,
-
-</li><li> breaking down the problem into smaller parts,
-
-</li><li> translating the small parts into regexps,
-
-</li><li> combining the regexps,
-
-</li><li> and optimizing the final combined regexp.
-
-</li></ul>
-
-<p>These are also the typical steps involved in writing a computer
-program. This makes perfect sense, because regular expressions are
-essentially programs written in a little computer language that specifies
-patterns.
-</p>
-<hr>
-<a name="perlretut-Using-regular-expressions-in-Perl"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlretut-Building-a-regexp" accesskey="p"
rel="prev">perlretut Building a regexp</a>, Up: <a
href="#perlretut-Part-1_003a-The-basics" accesskey="u" rel="up">perlretut Part
1: The basics</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-regular-expressions-in-Perl"></a>
-<h4 class="subsection">68.3.15 Using regular expressions in Perl</h4>
-
-<p>The last topic of Part 1 briefly covers how regexps are used in Perl
-programs. Where do they fit into Perl syntax?
-</p>
-<p>We have already introduced the matching operator in its default
-<code>/regexp/</code> and arbitrary delimiter <code>m!regexp!</code> forms.
We have used
-the binding operator <code>=~</code> and its negation <code>!~</code> to test
for string
-matches. Associated with the matching operator, we have discussed the
-single line <code>//s</code>, multi-line <code>//m</code>, case-insensitive
<code>//i</code> and
-extended <code>//x</code> modifiers. There are a few more things you might
-want to know about matching operators.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlretut-Prohibiting-substitution" accesskey="1">perlretut Prohibiting
substitution</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlretut-Global-matching"
accesskey="2">perlretut Global matching</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Search-and-replace" accesskey="3">perlretut Search and
replace</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-The-split-function" accesskey="4">perlretut The split
function</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlretut-Prohibiting-substitution"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Global-matching" accesskey="n" rel="next">perlretut
Global matching</a>, Up: <a href="#perlretut-Using-regular-expressions-in-Perl"
accesskey="u" rel="up">perlretut Using regular expressions in Perl</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Prohibiting-substitution"></a>
-<h4 class="subsubsection">68.3.15.1 Prohibiting substitution</h4>
-
-<p>If you change <code>$pattern</code> after the first substitution happens,
Perl
-will ignore it. If you don’t want any substitutions at all, use the
-special delimiter <code>m''</code>:
-</p>
-<pre class="verbatim"> @pattern = ('Seuss');
- while (<>) {
- print if m'@pattern'; # matches literal '@pattern', not 'Seuss'
- }
-</pre>
-<p>Similar to strings, <code>m''</code> acts like apostrophes on a regexp; all
other
-<code>m</code> delimiters act like quotes. If the regexp evaluates to the
empty string,
-the regexp in the <em>last successful match</em> is used instead. So we have
-</p>
-<pre class="verbatim"> "dog" =~ /d/; # 'd' matches
- "dogbert =~ //; # this matches the 'd' regexp used before
-</pre>
-<hr>
-<a name="perlretut-Global-matching"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Search-and-replace" accesskey="n"
rel="next">perlretut Search and replace</a>, Previous: <a
href="#perlretut-Prohibiting-substitution" accesskey="p" rel="prev">perlretut
Prohibiting substitution</a>, Up: <a
href="#perlretut-Using-regular-expressions-in-Perl" accesskey="u"
rel="up">perlretut Using regular expressions in Perl</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Global-matching"></a>
-<h4 class="subsubsection">68.3.15.2 Global matching</h4>
-
-<p>The final two modifiers we will discuss here,
-<code>//g</code> and <code>//c</code>, concern multiple matches.
-The modifier <code>//g</code> 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
-<code>//g</code> 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
-<code>pos()</code> function.
-</p>
-<p>The use of <code>//g</code> is shown in the following example. Suppose we
have
-a string that consists of words separated by spaces. If we know how
-many words there are in advance, we could extract the words using
-groupings:
-</p>
-<pre class="verbatim"> $x = "cat dog house"; # 3 words
- $x =~ /^\s*(\w+)\s+(\w+)\s+(\w+)\s*$/; # matches,
- # $1 = 'cat'
- # $2 = 'dog'
- # $3 = 'house'
-</pre>
-<p>But what if we had an indeterminate number of words? This is the sort
-of task <code>//g</code> was made for. To extract all words, form the simple
-regexp <code>(\w+)</code> and loop over all matches with <code>/(\w+)/g</code>:
-</p>
-<pre class="verbatim"> while ($x =~ /(\w+)/g) {
- print "Word is $1, ends at position ", pos $x,
"\n";
- }
-</pre>
-<p>prints
-</p>
-<pre class="verbatim"> Word is cat, ends at position 3
- Word is dog, ends at position 7
- Word is house, ends at position 13
-</pre>
-<p>A failed match or changing the target string resets the position. If
-you don’t want the position reset after failure to match, add the
-<code>//c</code>, as in <code>/regexp/gc</code>. The current position in the
string is
-associated with the string, not the regexp. This means that different
-strings have different positions and their respective positions can be
-set or read independently.
-</p>
-<p>In list context, <code>//g</code> returns a list of matched groupings, or if
-there are no groupings, a list of matches to the whole regexp. So if
-we wanted just the words, we could use
-</p>
-<pre class="verbatim"> @words = ($x =~ /(\w+)/g); # matches,
- # $words[0] = 'cat'
- # $words[1] = 'dog'
- # $words[2] = 'house'
-</pre>
-<p>Closely associated with the <code>//g</code> modifier is the
<code>\G</code> anchor. The
-<code>\G</code> anchor matches at the point where the previous
<code>//g</code> match left
-off. <code>\G</code> allows us to easily do context-sensitive matching:
-</p>
-<pre class="verbatim"> $metric = 1; # use metric units
- ...
- $x = <FILE>; # read in measurement
- $x =~ /^([+-]?\d+)\s*/g; # get magnitude
- $weight = $1;
- if ($metric) { # error checking
- print "Units error!" unless $x =~ /\Gkg\./g;
- }
- else {
- print "Units error!" unless $x =~ /\Glbs\./g;
- }
- $x =~ /\G\s+(widget|sprocket)/g; # continue processing
-</pre>
-<p>The combination of <code>//g</code> and <code>\G</code> allows us to
process the string a
-bit at a time and use arbitrary Perl logic to decide what to do next.
-Currently, the <code>\G</code> anchor is only fully supported when used to
anchor
-to the start of the pattern.
-</p>
-<p><code>\G</code> is also invaluable in processing fixed-length records with
-regexps. Suppose we have a snippet of coding region DNA, encoded as
-base pair letters <code>ATCGTTGAAT...</code> and we want to find all the stop
-codons <code>TGA</code>. In a coding region, codons are 3-letter sequences, so
-we can think of the DNA snippet as a sequence of 3-letter records. The
-naive regexp
-</p>
-<pre class="verbatim"> # expanded, this is "ATC GTT GAA TGC AAA TGA
CAT GAC"
- $dna = "ATCGTTGAATGCAAATGACATGAC";
- $dna =~ /TGA/;
-</pre>
-<p>doesn’t work; it may match a <code>TGA</code>, but there is no
guarantee that
-the match is aligned with codon boundaries, e.g., the substring
-<code>GTT GAA</code><!-- /@w --> gives a match. A better solution is
-</p>
-<pre class="verbatim"> while ($dna =~ /(\w\w\w)*?TGA/g) { # note the
minimal *?
- print "Got a TGA stop codon at position ", pos $dna,
"\n";
- }
-</pre>
-<p>which prints
-</p>
-<pre class="verbatim"> Got a TGA stop codon at position 18
- Got a TGA stop codon at position 23
-</pre>
-<p>Position 18 is good, but position 23 is bogus. What happened?
-</p>
-<p>The answer is that our regexp works well until we get past the last
-real match. Then the regexp will fail to match a synchronized <code>TGA</code>
-and start stepping ahead one character position at a time, not what we
-want. The solution is to use <code>\G</code> to anchor the match to the codon
-alignment:
-</p>
-<pre class="verbatim"> while ($dna =~ /\G(\w\w\w)*?TGA/g) {
- print "Got a TGA stop codon at position ", pos $dna,
"\n";
- }
-</pre>
-<p>This prints
-</p>
-<pre class="verbatim"> Got a TGA stop codon at position 18
-</pre>
-<p>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.
-</p>
-<p>(There are other regexp modifiers that are available, such as
-<code>//o</code>, but their specialized uses are beyond the
-scope of this introduction. )
-</p>
-<hr>
-<a name="perlretut-Search-and-replace"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-The-split-function" accesskey="n"
rel="next">perlretut The split function</a>, Previous: <a
href="#perlretut-Global-matching" accesskey="p" rel="prev">perlretut Global
matching</a>, Up: <a href="#perlretut-Using-regular-expressions-in-Perl"
accesskey="u" rel="up">perlretut Using regular expressions in Perl</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Search-and-replace-1"></a>
-<h4 class="subsubsection">68.3.15.3 Search and replace</h4>
-
-<p>Regular expressions also play a big role in <em>search and replace</em>
-operations in Perl. Search and replace is accomplished with the
-<code>s///</code> operator. The general form is
-<code>s/regexp/replacement/modifiers</code>, with everything we know about
-regexps and modifiers applying in this case as well. The
-<code>replacement</code> is a Perl double-quoted string that replaces in the
-string whatever is matched with the <code>regexp</code>. The operator
<code>=~</code> is
-also used here to associate a string with <code>s///</code>. If matching
-against <code>$_</code>, the <code><span
class="nolinebreak">$_</span> =~</code><!-- /@w --> can be dropped. If
there is a match,
-<code>s///</code> returns the number of substitutions made; otherwise it
returns
-false. Here are a few examples:
-</p>
-<pre class="verbatim"> $x = "Time to feed the cat!";
- $x =~ s/cat/hacker/; # $x contains "Time to feed the hacker!"
- if ($x =~ s/^(Time.*hacker)!$/$1 now!/) {
- $more_insistent = 1;
- }
- $y = "'quoted words'";
- $y =~ s/^'(.*)'$/$1/; # strip single quotes,
- # $y contains "quoted words"
-</pre>
-<p>In the last example, the whole string was matched, but only the part
-inside the single quotes was grouped. With the <code>s///</code> operator, the
-matched variables <code>$1</code>, <code>$2</code>, etc. are immediately
available for use
-in the replacement expression, so we use <code>$1</code> to replace the quoted
-string with just what was quoted. With the global modifier, <code>s///g</code>
-will search and replace all occurrences of the regexp in the string:
-</p>
-<pre class="verbatim"> $x = "I batted 4 for 4";
- $x =~ s/4/four/; # doesn't do it all:
- # $x contains "I batted four for 4"
- $x = "I batted 4 for 4";
- $x =~ s/4/four/g; # does it all:
- # $x contains "I batted four for four"
-</pre>
-<p>If you prefer ’regex’ over ’regexp’ in this
tutorial, you could use
-the following program to replace it:
-</p>
-<pre class="verbatim"> % cat > simple_replace
- #!/usr/bin/perl
- $regexp = shift;
- $replacement = shift;
- while (<>) {
- s/$regexp/$replacement/g;
- print;
- }
- ^D
-
- % simple_replace regexp regex perlretut.pod
-</pre>
-<p>In <code>simple_replace</code> we used the <code>s///g</code> modifier to
replace all
-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 <code>simple_grep</code>, both the
-<code>print</code> and the <code>s/$regexp/$replacement/g</code> use
<code>$_</code> implicitly.
-</p>
-<p>If you don’t want <code>s///</code> to change your original variable
you can use
-the non-destructive substitute modifier, <code>s///r</code>. This changes the
-behavior so that <code>s///r</code> returns the final substituted string
-(instead of the number of substitutions):
-</p>
-<pre class="verbatim"> $x = "I like dogs.";
- $y = $x =~ s/dogs/cats/r;
- print "$x $y\n";
-</pre>
-<p>That example will print "I like dogs. I like cats". Notice the
original
-<code>$x</code> variable has not been affected. The overall
-result of the substitution is instead stored in <code>$y</code>. If the
-substitution doesn’t affect anything then the original string is
-returned:
-</p>
-<pre class="verbatim"> $x = "I like dogs.";
- $y = $x =~ s/elephants/cougars/r;
- print "$x $y\n"; # prints "I like dogs. I like dogs."
-</pre>
-<p>One other interesting thing that the <code>s///r</code> flag allows is
chaining
-substitutions:
-</p>
-<pre class="verbatim"> $x = "Cats are great.";
- print $x =~ s/Cats/Dogs/r =~ s/Dogs/Frogs/r =~
- s/Frogs/Hedgehogs/r, "\n";
- # prints "Hedgehogs are great."
-</pre>
-<p>A modifier available specifically to search and replace is the
-<code>s///e</code> evaluation modifier. <code>s///e</code> 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. <code>s///e</code> 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:
-</p>
-<pre class="verbatim"> $x = "Bill the cat";
- $x =~ s/(.)/$chars{$1}++;$1/eg; # final $1 replaces char with itself
- print "frequency of '$_' is $chars{$_}\n"
- foreach (sort {$chars{$b} <=> $chars{$a}} keys %chars);
-</pre>
-<p>This prints
-</p>
-<pre class="verbatim"> frequency of ' ' is 2
- frequency of 't' is 2
- frequency of 'l' is 2
- frequency of 'B' is 1
- frequency of 'c' is 1
- frequency of 'e' is 1
- frequency of 'h' is 1
- frequency of 'i' is 1
- frequency of 'a' is 1
-</pre>
-<p>As with the match <code>m//</code> operator, <code>s///</code> can use
other delimiters,
-such as <code>s!!!</code> and <code>s{}{}</code>, and even <code>s{}//</code>.
If single quotes are
-used <code>s'''</code>, then the regexp and replacement are
-treated as single-quoted strings and there are no
-variable substitutions. <code>s///</code> in list context
-returns the same thing as in scalar context, i.e., the number of
-matches.
-</p>
-<hr>
-<a name="perlretut-The-split-function"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlretut-Search-and-replace" accesskey="p"
rel="prev">perlretut Search and replace</a>, Up: <a
href="#perlretut-Using-regular-expressions-in-Perl" accesskey="u"
rel="up">perlretut Using regular expressions in Perl</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-split-function"></a>
-<h4 class="subsubsection">68.3.15.4 The split function</h4>
-
-<p>The <code>split()</code> function is another place where a regexp is used.
-<code>split /regexp/, string, limit</code> separates the <code>string</code>
operand into
-a list of substrings and returns that list. The regexp must be designed
-to match whatever constitutes the separators for the desired substrings.
-The <code>limit</code>, if present, constrains splitting into no more than
<code>limit</code>
-number of strings. For example, to split a string into words, use
-</p>
-<pre class="verbatim"> $x = "Calvin and Hobbes";
- @words = split /\s+/, $x; # $word[0] = 'Calvin'
- # $word[1] = 'and'
- # $word[2] = 'Hobbes'
-</pre>
-<p>If the empty regexp <code>//</code> is used, the regexp always matches and
-the string is split into individual characters. If the regexp has
-groupings, then the resulting list contains the matched substrings from the
-groupings as well. For instance,
-</p>
-<pre class="verbatim"> $x = "/usr/bin/perl";
- @dirs = split m!/!, $x; # $dirs[0] = ''
- # $dirs[1] = 'usr'
- # $dirs[2] = 'bin'
- # $dirs[3] = 'perl'
- @parts = split m!(/)!, $x; # $parts[0] = ''
- # $parts[1] = '/'
- # $parts[2] = 'usr'
- # $parts[3] = '/'
- # $parts[4] = 'bin'
- # $parts[5] = '/'
- # $parts[6] = 'perl'
-</pre>
-<p>Since the first character of $x matched the regexp, <code>split</code>
prepended
-an empty initial element to the list.
-</p>
-<p>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.... Part 2<!--
/@w -->
-concerns the more esoteric aspects of regular expressions and those
-concepts certainly aren’t needed right at the start.
-</p>
-<hr>
-<a name="perlretut-Part-2_003a-Power-tools"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-BUGS" accesskey="n" rel="next">perlretut BUGS</a>,
Previous: <a href="#perlretut-Part-1_003a-The-basics" accesskey="p"
rel="prev">perlretut Part 1: The basics</a>, Up: <a href="#perlretut"
accesskey="u" rel="up">perlretut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Part-2_003a-Power-tools"></a>
-<h3 class="section">68.4 Part 2: Power tools</h3>
-
-<p>OK, you know the basics of regexps and you want to know more. If
-matching regular expressions is analogous to a walk in the woods, then
-the tools discussed in Part 1 are analogous to topo maps and a
-compass, basic tools we use all the time. Most of the tools in part 2
-are analogous to flare guns and satellite phones. They aren’t used
-too often on a hike, but when we are stuck, they can be invaluable.
-</p>
-<p>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 advanced features.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlretut-More-on-characters_002c-strings_002c-and-character-classes"
accesskey="1">perlretut More on characters, strings, and character
classes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Compiling-and-saving-regular-expressions"
accesskey="2">perlretut Compiling and saving regular
expressions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Composing-regular-expressions-at-runtime"
accesskey="3">perlretut Composing regular expressions at
runtime</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Embedding-comments-and-modifiers-in-a-regular-expression"
accesskey="4">perlretut Embedding comments and modifiers in a regular
expression</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Looking-ahead-and-looking-behind" accesskey="5">perlretut
Looking ahead and looking behind</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Using-independent-subexpressions-to-prevent-backtracking"
accesskey="6">perlretut Using independent subexpressions to prevent
backtracking</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Conditional-expressions" accesskey="7">perlretut Conditional
expressions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Defining-named-patterns" accesskey="8">perlretut Defining
named patterns</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Recursive-patterns" accesskey="9">perlretut Recursive
patterns</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-A-bit-of-magic_003a-executing-Perl-code-in-a-regular-expression">perlretut
A bit of magic: executing Perl code in a regular
expression</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Backtracking-control-verbs">perlretut Backtracking control
verbs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlretut-Pragmas-and-debugging">perlretut Pragmas and
debugging</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a
name="perlretut-More-on-characters_002c-strings_002c-and-character-classes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Compiling-and-saving-regular-expressions"
accesskey="n" rel="next">perlretut Compiling and saving regular
expressions</a>, Up: <a href="#perlretut-Part-2_003a-Power-tools" accesskey="u"
rel="up">perlretut Part 2: Power tools</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="More-on-characters_002c-strings_002c-and-character-classes"></a>
-<h4 class="subsection">68.4.1 More on characters, strings, and character
classes</h4>
-
-<p>There are a number of escape sequences and character classes that we
-haven’t covered yet.
-</p>
-<p>There are several escape sequences that convert characters or strings
-between upper and lower case, and they are also available within
-patterns. <code>\l</code> and <code>\u</code> convert the next character to
lower or
-upper case, respectively:
-</p>
-<pre class="verbatim"> $x = "perl";
- $string =~ /\u$x/; # matches 'Perl' in $string
- $x = "M(rs?|s)\\."; # note the double backslash
- $string =~ /\l$x/; # matches 'mr.', 'mrs.', and 'ms.',
-</pre>
-<p>A <code>\L</code> or <code>\U</code> indicates a lasting conversion of
case, until
-terminated by <code>\E</code> or thrown over by another <code>\U</code> or
<code>\L</code>:
-</p>
-<pre class="verbatim"> $x = "This word is in lower case:\L
SHOUT\E";
- $x =~ /shout/; # matches
- $x = "I STILL KEYPUNCH CARDS FOR MY 360"
- $x =~ /\Ukeypunch/; # matches punch card string
-</pre>
-<p>If there is no <code>\E</code>, case is converted until the end of the
-string. The regexps <code>\L\u$word</code> or <code>\u\L$word</code> convert
the first
-character of <code>$word</code> to uppercase and the rest of the characters to
-lowercase.
-</p>
-<p>Control characters can be escaped with <code>\c</code>, so that a control-Z
-character would be matched with <code>\cZ</code>. The escape sequence
-<code>\Q</code>...<code>\E</code> quotes, or protects most non-alphabetic
characters. For
-instance,
-</p>
-<pre class="verbatim"> $x = "\QThat !^*&%~& cat!";
- $x =~ /\Q!^*&%~&\E/; # check for rough language
-</pre>
-<p>It does not protect <code>$</code> or <code>@</code>, so that variables can
still be
-substituted.
-</p>
-<p><code>\Q</code>, <code>\L</code>, <code>\l</code>, <code>\U</code>,
<code>\u</code> and <code>\E</code> are actually part of
-double-quotish syntax, and not part of regexp syntax proper. They will
-work if they appear in a regular expression embedded directly in a
-program, but not when contained in a string that is interpolated in a
-pattern.
-</p>
-<p>Perl regexps can handle more than just the
-standard ASCII character set. Perl supports <em>Unicode</em>, 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.
-</p>
-<p>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 <code>chr(255)</code> are represented using the
<code>\x{hex}</code> 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 <code>\o{oct}</code>.)
-</p>
-<pre class="verbatim"> /\x{263a}/; # match a Unicode smiley face :)
-</pre>
-<p><strong>NOTE</strong>: In Perl 5.6.0 it used to be that one needed to say
<code>use
-utf8</code> to use any Unicode features. This is no more the case: for
-almost all Unicode processing, the explicit <code>utf8</code> pragma is not
-needed. (The only case where it matters is if your Perl script is in
-Unicode and encoded in UTF-8, then an explicit <code>use utf8</code> is
needed.)
-</p>
-<p>Figuring out the hexadecimal sequence of a Unicode character you want
-or deciphering someone else’s hexadecimal Unicode regexp is about as
-much fun as programming in machine code. So another way to specify
-Unicode characters is to use the <em>named character</em> escape
-sequence <code>\N{<em>name</em>}</code>. <em>name</em> is a name for the
Unicode character, as
-specified in the Unicode standard. For instance, if we wanted to
-represent or match the astrological sign for the planet Mercury, we
-could use
-</p>
-<pre class="verbatim"> $x = "abc\N{MERCURY}def";
- $x =~ /\N{MERCURY}/; # matches
-</pre>
-<p>One can also use "short" names:
-</p>
-<pre class="verbatim"> print "\N{GREEK SMALL LETTER SIGMA} is called
sigma.\n";
- print "\N{greek:Sigma} is an upper-case sigma.\n";
-</pre>
-<p>You can also restrict names to a certain alphabet by specifying the
-<a href="charnames.html#Top">(charnames)</a> pragma:
-</p>
-<pre class="verbatim"> use charnames qw(greek);
- print "\N{sigma} is Greek sigma\n";
-</pre>
-<p>An index of character names is available on-line from the Unicode
-Consortium, <a
href="http://www.unicode.org/charts/charindex.html";>http://www.unicode.org/charts/charindex.html</a>;
explanatory
-material with links to other resources at
-<a
href="http://www.unicode.org/standard/where";>http://www.unicode.org/standard/where</a>.
-</p>
-<p>The answer to requirement 2) is that a regexp (mostly)
-uses Unicode characters. The "mostly" is for messy backward
-compatibility reasons, but starting in Perl 5.14, any regex compiled in
-the scope of a <code>use feature 'unicode_strings'</code> (which is
automatically
-turned on within the scope of a <code>use 5.012</code> or higher) will turn
that
-"mostly" into "always". If you want to handle Unicode
properly, you
-should ensure that <code>'unicode_strings'</code> is turned on.
-Internally, this is encoded to bytes using either UTF-8 or a native 8
-bit encoding, depending on the history of the string, but conceptually
-it is a sequence of characters, not bytes. See <a
href="#perlunitut-NAME">perlunitut NAME</a> for a
-tutorial about that.
-</p>
-<p>Let us now discuss Unicode character classes, most usually called
-"character properties". These are represented by the
-<code>\p{name}</code> escape sequence. Closely associated is the
<code>\P{name}</code>
-property, which is the negation of the <code>\p{name}</code> one. For
-example, to match lower and uppercase characters,
-</p>
-<pre class="verbatim"> $x = "BOB";
- $x =~ /^\p{IsUpper}/; # matches, uppercase char class
- $x =~ /^\P{IsUpper}/; # doesn't match, char class sans uppercase
- $x =~ /^\p{IsLower}/; # doesn't match, lowercase char class
- $x =~ /^\P{IsLower}/; # matches, char class sans lowercase
-</pre>
-<p>(The "Is" is optional.)
-</p>
-<p>There are many, many Unicode character properties. For the full list
-see <a href="perluniprops.html#Top">(perluniprops)</a>. Most of them have
synonyms with shorter names,
-also listed there. Some synonyms are a single character. For these,
-you can drop the braces. For instance, <code>\pM</code> is the same thing as
-<code>\p{Mark}</code>, meaning things like accent marks.
-</p>
-<p>The Unicode <code>\p{Script}</code> property is used to categorize every
Unicode
-character into the language script it is written in. For example,
-English, French, and a bunch of other European languages are written in
-the Latin script. But there is also the Greek script, the Thai script,
-the Katakana script, etc. You can test whether a character is in a
-particular script with, for example <code>\p{Latin}</code>,
<code>\p{Greek}</code>,
-or <code>\p{Katakana}</code>. To test if it isn’t in the Balinese
script, you
-would use <code>\P{Balinese}</code>.
-</p>
-<p>What we have described so far is the single form of the
<code>\p{...}</code> character
-classes. There is also a compound form which you may run into. These
-look like <code>\p{name=value}</code> or <code>\p{name:value}</code> (the
equals sign and colon
-can be used interchangeably). These are more general than the single form,
-and in fact most of the single forms are just Perl-defined shortcuts for common
-compound forms. For example, the script examples in the previous paragraph
-could be written equivalently as <code>\p{Script=Latin}</code>,
<code>\p{Script:Greek}</code>,
-<code>\p{script=katakana}</code>, and <code>\P{script=balinese}</code> (case
is irrelevant
-between the <code>{}</code> braces). You may
-never have to use the compound forms, but sometimes it is necessary, and their
-use can make your code easier to understand.
-</p>
-<p><code>\X</code> is an abbreviation for a character class that comprises
-a Unicode <em>extended grapheme cluster</em>. 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.,
<code>A + COMBINING RING</code><!-- /@w --> is a grapheme
cluster with base character <code>A</code> and combining character
-<code>COMBINING RING</code><!-- /@w -->, which translates in Danish to A
with the circle atop it,
-as in the word ÃÂ
ngstrom.
-</p>
-<p>For the full and latest information about Unicode see the latest
-Unicode standard, or the Unicode Consortium’s website <a
href="http://www.unicode.org";>http://www.unicode.org</a>
-</p>
-<p>As if all those classes weren’t enough, Perl also defines POSIX-style
-character classes. These have the form <code>[:name:]</code>, with
<code>name</code> the
-name of the POSIX class. The POSIX classes are <code>alpha</code>,
<code>alnum</code>,
-<code>ascii</code>, <code>cntrl</code>, <code>digit</code>,
<code>graph</code>, <code>lower</code>, <code>print</code>, <code>punct</code>,
-<code>space</code>, <code>upper</code>, and <code>xdigit</code>, and two
extensions, <code>word</code> (a Perl
-extension to match <code>\w</code>), and <code>blank</code> (a GNU extension).
The <code>//a</code>
-modifier restricts these to matching just in the ASCII range; otherwise
-they can match the same as their corresponding Perl Unicode classes:
-<code>[:upper:]</code> is the same as <code>\p{IsUpper}</code>, etc. (There
are some
-exceptions and gotchas with this; see <a
href="#perlrecharclass-NAME">perlrecharclass NAME</a> for a full
-discussion.) The <code>[:digit:]</code>, <code>[:word:]</code>, and
-<code>[:space:]</code> correspond to the familiar <code>\d</code>,
<code>\w</code>, and <code>\s</code>
-character classes. To negate a POSIX class, put a <code>^</code> in front of
-the name, so that, e.g., <code>[:^digit:]</code> corresponds to
<code>\D</code> and, under
-Unicode, <code>\P{IsDigit}</code>. The Unicode and POSIX character classes can
-be used just like <code>\d</code>, with the exception that POSIX character
-classes can only be used inside of a character class:
-</p>
-<pre class="verbatim"> /\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
- /\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
-</pre>
-<p>Whew! That is all the rest of the characters and character classes.
-</p>
-<hr>
-<a name="perlretut-Compiling-and-saving-regular-expressions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Composing-regular-expressions-at-runtime"
accesskey="n" rel="next">perlretut Composing regular expressions at
runtime</a>, Previous: <a
href="#perlretut-More-on-characters_002c-strings_002c-and-character-classes"
accesskey="p" rel="prev">perlretut More on characters, strings, and character
classes</a>, Up: <a href="#perlretut-Part-2_003a-Power-tools" accesskey="u"
rel="up">perlretut Part 2: Power tools</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Compiling-and-saving-regular-expressions"></a>
-<h4 class="subsection">68.4.2 Compiling and saving regular expressions</h4>
-
-<p>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
-<code>qr//</code> does exactly that: <code>qr/string/</code> compiles the
<code>string</code> as a
-regexp and transforms the result into a form that can be assigned to a
-variable:
-</p>
-<pre class="verbatim"> $reg = qr/foo+bar?/; # reg contains a compiled
regexp
-</pre>
-<p>Then <code>$reg</code> can be used as a regexp:
-</p>
-<pre class="verbatim"> $x = "fooooba";
- $x =~ $reg; # matches, just like /foo+bar?/
- $x =~ /$reg/; # same thing, alternate form
-</pre>
-<p><code>$reg</code> can also be interpolated into a larger regexp:
-</p>
-<pre class="verbatim"> $x =~ /(abc)?$reg/; # still matches
-</pre>
-<p>As with the matching operator, the regexp quote can use different
-delimiters, e.g., <code>qr!!</code>, <code>qr{}</code> or <code>qr~~</code>.
Apostrophes
-as delimiters (<code>qr''</code>) inhibit any interpolation.
-</p>
-<p>Pre-compiled regexps are useful for creating dynamic matches that
-don’t need to be recompiled each time they are encountered. Using
-pre-compiled regexps, we write a <code>grep_step</code> program which greps
-for a sequence of patterns, advancing to the next pattern as soon
-as one has been satisfied.
-</p>
-<pre class="verbatim"> % cat > grep_step
- #!/usr/bin/perl
- # grep_step - match <number> regexps, one after the other
- # usage: multi_grep <number> regexp1 regexp2 ... file1 file2 ...
-
- $number = shift;
- $regexp[$_] = shift foreach (0..$number-1);
- @compiled = map qr/$_/, @regexp;
- while ($line = <>) {
- if ($line =~ /$compiled[0]/) {
- print $line;
- shift @compiled;
- last unless @compiled;
- }
- }
- ^D
-
- % grep_step 3 shift print last grep_step
- $number = shift;
- print $line;
- last unless @compiled;
-</pre>
-<p>Storing pre-compiled regexps in an array <code>@compiled</code> allows us to
-simply loop through the regexps without any recompilation, thus gaining
-flexibility without sacrificing speed.
-</p>
-<hr>
-<a name="perlretut-Composing-regular-expressions-at-runtime"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlretut-Embedding-comments-and-modifiers-in-a-regular-expression"
accesskey="n" rel="next">perlretut Embedding comments and modifiers in a
regular expression</a>, Previous: <a
href="#perlretut-Compiling-and-saving-regular-expressions" accesskey="p"
rel="prev">perlretut Compiling and saving regular expressions</a>, Up: <a
href="#perlretut-Part-2_003a-Power-tools" accesskey="u" rel="up">perlretut Part
2: Power tools</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Composing-regular-expressions-at-runtime"></a>
-<h4 class="subsection">68.4.3 Composing regular expressions at runtime</h4>
-
-<p>Backtracking is more efficient than repeated tries with different regular
-expressions. If there are several regular expressions and a match with
-any of them is acceptable, then it is possible to combine them into a set
-of alternatives. If the individual expressions are input data, this
-can be done by programming a join operation. We’ll exploit this idea in
-an improved version of the <code>simple_grep</code> program: a program that
matches
-multiple patterns:
-</p>
-<pre class="verbatim"> % cat > multi_grep
- #!/usr/bin/perl
- # multi_grep - match any of <number> regexps
- # usage: multi_grep <number> regexp1 regexp2 ... file1 file2 ...
-
- $number = shift;
- $regexp[$_] = shift foreach (0..$number-1);
- $pattern = join '|', @regexp;
-
- while ($line = <>) {
- print $line if $line =~ /$pattern/;
- }
- ^D
-
- % multi_grep 2 shift for multi_grep
- $number = shift;
- $regexp[$_] = shift foreach (0..$number-1);
-</pre>
-<p>Sometimes it is advantageous to construct a pattern from the <em>input</em>
-that is to be analyzed and use the permissible values on the left
-hand side of the matching operations. As an example for this somewhat
-paradoxical situation, let’s assume that our input contains a command
-verb which should match one out of a set of available command verbs,
-with the additional twist that commands may be abbreviated as long as
-the given string is unique. The program below demonstrates the basic
-algorithm.
-</p>
-<pre class="verbatim"> % cat > keymatch
- #!/usr/bin/perl
- $kwds = 'copy compare list print';
- while( $cmd = <> ){
- $cmd =~ s/^\s+|\s+$//g; # trim leading and trailing spaces
- if( ( @matches = $kwds =~ /\b$cmd\w*/g ) == 1 ){
- print "command: '@matches'\n";
- } elsif( @matches == 0 ){
- print "no such command: '$cmd'\n";
- } else {
- print "not unique: '$cmd' (could be one of: @matches)\n";
- }
- }
- ^D
-
- % keymatch
- li
- command: 'list'
- co
- not unique: 'co' (could be one of: copy compare)
- printer
- no such command: 'printer'
-</pre>
-<p>Rather than trying to match the input against the keywords, we match the
-combined set of keywords against the input. The pattern matching
-operation <code>$kwds =~ /\b($cmd\w*)/g</code><!-- /@w --> does
several things at the
-same time. It makes sure that the given command begins where a keyword
-begins (<code>\b</code>). It tolerates abbreviations due to the added
<code>\w*</code>. It
-tells us the number of matches (<code>scalar @matches</code>) and all the
keywords
-that were actually matched. You could hardly ask for more.
-</p>
-<hr>
-<a
name="perlretut-Embedding-comments-and-modifiers-in-a-regular-expression"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Looking-ahead-and-looking-behind" accesskey="n"
rel="next">perlretut Looking ahead and looking behind</a>, Previous: <a
href="#perlretut-Composing-regular-expressions-at-runtime" accesskey="p"
rel="prev">perlretut Composing regular expressions at runtime</a>, Up: <a
href="#perlretut-Part-2_003a-Power-tools" accesskey="u" rel="up">perlretut Part
2: Power tools</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Embedding-comments-and-modifiers-in-a-regular-expression"></a>
-<h4 class="subsection">68.4.4 Embedding comments and modifiers in a regular
expression</h4>
-
-<p>Starting with this section, we will be discussing Perl’s set of
-<em>extended patterns</em>. 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 <code>??</code>, <code>*?</code>, <code>+?</code>,
<code>{n,m}?</code>, and <code>{n,}?</code>. Most
-of the extensions below have the form <code>(?char...)</code>, where the
-<code>char</code> is a character that determines the type of extension.
-</p>
-<p>The first extension is an embedded comment <code>(?#text)</code>. This
embeds a
-comment into the regular expression without affecting its meaning. The
-comment should not have any closing parentheses in the text. An
-example is
-</p>
-<pre class="verbatim"> /(?# Match an integer:)[+-]?\d+/;
-</pre>
-<p>This style of commenting has been largely superseded by the raw,
-freeform commenting that is allowed with the <code>//x</code> modifier.
-</p>
-<p>Most modifiers, such as <code>//i</code>, <code>//m</code>,
<code>//s</code> and <code>//x</code> (or any
-combination thereof) can also be embedded in
-a regexp using <code>(?i)</code>, <code>(?m)</code>, <code>(?s)</code>, and
<code>(?x)</code>. For instance,
-</p>
-<pre class="verbatim"> /(?i)yes/; # match 'yes' case insensitively
- /yes/i; # same thing
- /(?x)( # freeform version of an integer regexp
- [+-]? # match an optional sign
- \d+ # match a sequence of digits
- )
- /x;
-</pre>
-<p>Embedded modifiers can have two important advantages over the usual
-modifiers. Embedded modifiers allow a custom set of modifiers to
-<em>each</em> regexp pattern. This is great for matching an array of regexps
-that must have different modifiers:
-</p>
-<pre class="verbatim"> $pattern[0] = '(?i)doctor';
- $pattern[1] = 'Johnson';
- ...
- while (<>) {
- foreach $patt (@pattern) {
- print if /$patt/;
- }
- }
-</pre>
-<p>The second advantage is that embedded modifiers (except <code>//p</code>,
which
-modifies the entire regexp) only affect the regexp
-inside the group the embedded modifier is contained in. So grouping
-can be used to localize the modifier’s effects:
-</p>
-<pre class="verbatim"> /Answer: ((?i)yes)/; # matches 'Answer: yes',
'Answer: YES', etc.
-</pre>
-<p>Embedded modifiers can also turn off any modifiers already present
-by using, e.g., <code>(?-i)</code>. Modifiers can also be combined into
-a single expression, e.g., <code>(?s-i)</code> turns on single line mode and
-turns off case insensitivity.
-</p>
-<p>Embedded modifiers may also be added to a non-capturing grouping.
-<code>(?i-m:regexp)</code> is a non-capturing grouping that matches
<code>regexp</code>
-case insensitively and turns off multi-line mode.
-</p>
-<hr>
-<a name="perlretut-Looking-ahead-and-looking-behind"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlretut-Using-independent-subexpressions-to-prevent-backtracking"
accesskey="n" rel="next">perlretut Using independent subexpressions to prevent
backtracking</a>, Previous: <a
href="#perlretut-Embedding-comments-and-modifiers-in-a-regular-expression"
accesskey="p" rel="prev">perlretut Embedding comments and modifiers in a
regular expression</a>, Up: <a href="#perlretut-Part-2_003a-Power-tools"
accesskey="u" rel="up">perlretut Part 2: Power tools</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Looking-ahead-and-looking-behind"></a>
-<h4 class="subsection">68.4.5 Looking ahead and looking behind</h4>
-
-<p>This section concerns the lookahead and lookbehind assertions. First,
-a little background.
-</p>
-<p>In Perl regular expressions, most regexp elements ’eat up’ a
certain
-amount of string when they match. For instance, the regexp element
-<code>[abc}]</code> eats up one character of the string when it matches, in the
-sense that Perl moves to the next character position in the string
-after the match. There are some elements, however, that don’t eat up
-characters (advance the character position) if they match. The examples
-we have seen so far are the anchors. The anchor <code>^</code> matches the
-beginning of the line, but doesn’t eat any characters. Similarly, the
-word boundary anchor <code>\b</code> matches wherever a character matching
<code>\w</code>
-is next to a character that doesn’t, but it doesn’t eat up any
-characters itself. Anchors are examples of <em>zero-width assertions</em>:
-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
-us stop a moment and check our surroundings. If the local environment
-checks out, we can proceed forward. But if the local environment
-doesn’t satisfy us, we must backtrack.
-</p>
-<p>Checking the environment entails either looking ahead on the trail,
-looking behind, or both. <code>^</code> looks behind, to see that there are no
-characters before. <code>$</code> looks ahead, to see that there are no
-characters after. <code>\b</code> looks both ahead and behind, to see if the
-characters on either side differ in their "word-ness".
-</p>
-<p>The lookahead and lookbehind assertions are generalizations of the
-anchor concept. Lookahead and lookbehind are zero-width assertions
-that let us specify which characters we want to test for. The
-lookahead assertion is denoted by <code>(?=regexp)</code> and the lookbehind
-assertion is denoted by <code>(?<=fixed-regexp)</code>. Some examples are
-</p>
-<pre class="verbatim"> $x = "I catch the housecat 'Tom-cat' with
catnip";
- $x =~ /cat(?=\s)/; # matches 'cat' in 'housecat'
- @catwords = ($x =~ /(?<=\s)cat\w+/g); # matches,
- # $catwords[0] = 'catch'
- # $catwords[1] = 'catnip'
- $x =~ /\bcat\b/; # matches 'cat' in 'Tom-cat'
- $x =~ /(?<=\s)cat(?=\s)/; # doesn't match; no isolated 'cat' in
- # middle of $x
-</pre>
-<p>Note that the parentheses in <code>(?=regexp)</code> and
<code>(?<=regexp)</code> are
-non-capturing, since these are zero-width assertions. Thus in the
-second regexp, the substrings captured are those of the whole regexp
-itself. Lookahead <code>(?=regexp)</code> can match arbitrary regexps, but
-lookbehind <code>(?<=fixed-regexp)</code> only works for regexps of fixed
-width, i.e., a fixed number of characters long. Thus
-<code>(?<=(ab|bc))</code> is fine, but <code>(?<=(ab)*)</code> is not.
The
-negated versions of the lookahead and lookbehind assertions are
-denoted by <code>(?!regexp)</code> and <code>(?<!fixed-regexp)</code>
respectively.
-They evaluate true if the regexps do <em>not</em> match:
-</p>
-<pre class="verbatim"> $x = "foobar";
- $x =~ /foo(?!bar)/; # doesn't match, 'bar' follows 'foo'
- $x =~ /foo(?!baz)/; # matches, 'baz' doesn't follow 'foo'
- $x =~ /(?<!\s)foo/; # matches, there is no \s before 'foo'
-</pre>
-<p>The <code>\C</code> is unsupported in lookbehind, because the already
-treacherous definition of <code>\C</code> would become even more so
-when going backwards.
-</p>
-<p>Here is an example where a string containing blank-separated words,
-numbers and single dashes is to be split into its components.
-Using <code>/\s+/</code> alone won’t work, because spaces are not
required between
-dashes, or a word or a dash. Additional places for a split are established
-by looking ahead and behind:
-</p>
-<pre class="verbatim"> $str = "one two - --6-8";
- @toks = split / \s+ # a run of spaces
- | (?<=\S) (?=-) # any non-space followed by '-'
- | (?<=-) (?=\S) # a '-' followed by any non-space
- /x, $str; # @toks = qw(one two - - - 6 - 8)
-</pre>
-<hr>
-<a
name="perlretut-Using-independent-subexpressions-to-prevent-backtracking"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Conditional-expressions" accesskey="n"
rel="next">perlretut Conditional expressions</a>, Previous: <a
href="#perlretut-Looking-ahead-and-looking-behind" accesskey="p"
rel="prev">perlretut Looking ahead and looking behind</a>, Up: <a
href="#perlretut-Part-2_003a-Power-tools" accesskey="u" rel="up">perlretut Part
2: Power tools</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-independent-subexpressions-to-prevent-backtracking"></a>
-<h4 class="subsection">68.4.6 Using independent subexpressions to prevent
backtracking</h4>
-
-<p><em>Independent subexpressions</em> are regular expressions, in the
-context of a larger regular expression, that function independently of
-the larger regular expression. That is, they consume as much or as
-little of the string as they wish without regard for the ability of
-the larger regexp to match. Independent subexpressions are represented
-by <code>(?>regexp)</code>. We can illustrate their behavior by first
-considering an ordinary regexp:
-</p>
-<pre class="verbatim"> $x = "ab";
- $x =~ /a*ab/; # matches
-</pre>
-<p>This obviously matches, but in the process of matching, the
-subexpression <code>a*</code> first grabbed the <code>a</code>. Doing so,
however,
-wouldn’t allow the whole regexp to match, so after backtracking,
<code>a*</code>
-eventually gave back the <code>a</code> and matched the empty string. Here,
what
-<code>a*</code> matched was <em>dependent</em> on what the rest of the regexp
matched.
-</p>
-<p>Contrast that with an independent subexpression:
-</p>
-<pre class="verbatim"> $x =~ /(?>a*)ab/; # doesn't match!
-</pre>
-<p>The independent subexpression <code>(?>a*)</code> doesn’t care
about the rest
-of the regexp, so it sees an <code>a</code> and grabs it. Then the rest of the
-regexp <code>ab</code> cannot match. Because <code>(?>a*)</code> is
independent, there
-is no backtracking and the independent subexpression does not give
-up its <code>a</code>. Thus the match of the regexp as a whole fails. A
similar
-behavior occurs with completely independent regexps:
-</p>
-<pre class="verbatim"> $x = "ab";
- $x =~ /a*/g; # matches, eats an 'a'
- $x =~ /\Gab/g; # doesn't match, no 'a' available
-</pre>
-<p>Here <code>//g</code> and <code>\G</code> create a ’tag team’
handoff of the string from
-one regexp to the other. Regexps with an independent subexpression are
-much like this, with a handoff of the string to the independent
-subexpression, and a handoff of the string back to the enclosing
-regexp.
-</p>
-<p>The ability of an independent subexpression to prevent backtracking
-can be quite useful. Suppose we want to match a non-empty string
-enclosed in parentheses up to two levels deep. Then the following
-regexp matches:
-</p>
-<pre class="verbatim"> $x = "abc(de(fg)h"; # unbalanced
parentheses
- $x =~ /\( ( [^()]+ | \([^()]*\) )+ \)/x;
-</pre>
-<p>The regexp matches an open parenthesis, one or more copies of an
-alternation, and a close parenthesis. The alternation is two-way, with
-the first alternative <code>[^()]+</code> matching a substring with no
-parentheses and the second alternative <code>\([^()]*\)</code> matching a
-substring delimited by parentheses. The problem with this regexp is
-that it is pathological: it has nested indeterminate quantifiers
-of the form <code>(a+|b)+</code>. We discussed in Part 1 how nested
quantifiers
-like this could take an exponentially long time to execute if there
-was no match possible. To prevent the exponential blowup, we need to
-prevent useless backtracking at some point. This can be done by
-enclosing the inner quantifier as an independent subexpression:
-</p>
-<pre class="verbatim"> $x =~ /\( ( (?>[^()]+) | \([^()]*\) )+ \)/x;
-</pre>
-<p>Here, <code>(?>[^()]+)</code> breaks the degeneracy of string
partitioning
-by gobbling up as much of the string as possible and keeping it. Then
-match failures fail much more quickly.
-</p>
-<hr>
-<a name="perlretut-Conditional-expressions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Defining-named-patterns" accesskey="n"
rel="next">perlretut Defining named patterns</a>, Previous: <a
href="#perlretut-Using-independent-subexpressions-to-prevent-backtracking"
accesskey="p" rel="prev">perlretut Using independent subexpressions to prevent
backtracking</a>, Up: <a href="#perlretut-Part-2_003a-Power-tools"
accesskey="u" rel="up">perlretut Part 2: Power tools</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Conditional-expressions"></a>
-<h4 class="subsection">68.4.7 Conditional expressions</h4>
-
-<p>A <em>conditional expression</em> is a form of if-then-else statement
-that allows one to choose which patterns are to be matched, based on
-some condition. There are two types of conditional expression:
-<code>(?(condition)yes-regexp)</code> and
-<code>(?(condition)yes-regexp|no-regexp)</code>.
<code>(?(condition)yes-regexp)</code> is
-like an <code>'if () {}'</code><!-- /@w --> statement in Perl. If
the <code>condition</code> is true,
-the <code>yes-regexp</code> will be matched. If the <code>condition</code> is
false, the
-<code>yes-regexp</code> will be skipped and Perl will move onto the next regexp
-element. The second form is like an
<code>'if () {} else {}'</code><!-- /@w --> statement
-in Perl. If the <code>condition</code> is true, the <code>yes-regexp</code>
will be
-matched, otherwise the <code>no-regexp</code> will be matched.
-</p>
-<p>The <code>condition</code> can have several forms. The first form is
simply an
-integer in parentheses <code>(integer)</code>. It is true if the corresponding
-backreference <code>\integer</code> matched earlier in the regexp. The same
-thing can be done with a name associated with a capture group, written
-as <code>(<name>)</code> or <code>('name')</code>. The second form is a
bare
-zero-width assertion <code>(?...)</code>, 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 (<code>(R)</code>) or is being called from some capturing group,
-referenced either by number (<code>(R1)</code>, <code>(R2)</code>,...) or by
name
-(<code>(R&name)</code>).
-</p>
-<p>The integer or name form of the <code>condition</code> 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 <code>"$x$x"</code> or
<code>"$x$y$y$x"</code>:
-</p>
-<pre class="verbatim"> % simple_grep '^(\w+)(\w+)?(?(2)\g2\g1|\g1)$'
/usr/dict/words
- beriberi
- coco
- couscous
- deed
- ...
- toot
- toto
- tutu
-</pre>
-<p>The lookbehind <code>condition</code> allows, along with backreferences,
-an earlier part of the match to influence a later part of the
-match. For instance,
-</p>
-<pre class="verbatim"> /[ATGC]+(?(?<=AA)G|C)$/;
-</pre>
-<p>matches a DNA sequence such that it either ends in <code>AAG</code>, or some
-other base pair combination and <code>C</code>. Note that the form is
-<code>(?(?<=AA)G|C)</code> and not <code>(?((?<=AA))G|C)</code>; for the
-lookahead, lookbehind or code assertions, the parentheses around the
-conditional are not needed.
-</p>
-<hr>
-<a name="perlretut-Defining-named-patterns"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Recursive-patterns" accesskey="n"
rel="next">perlretut Recursive patterns</a>, Previous: <a
href="#perlretut-Conditional-expressions" accesskey="p" rel="prev">perlretut
Conditional expressions</a>, Up: <a href="#perlretut-Part-2_003a-Power-tools"
accesskey="u" rel="up">perlretut Part 2: Power tools</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Defining-named-patterns"></a>
-<h4 class="subsection">68.4.8 Defining named patterns</h4>
-
-<p>Some regular expressions use identical subpatterns in several places.
-Starting with Perl 5.10, it is possible to define named subpatterns in
-a section of the pattern so that they can be called up by name
-anywhere in the pattern. This syntactic pattern for this definition
-group is <code>(?(DEFINE)(?<name>pattern)...)</code>. An insertion
-of a named pattern is written as <code>(?&name)</code>.
-</p>
-<p>The example below illustrates this feature using the pattern for
-floating point numbers that was presented earlier on. The three
-subpatterns that are used more than once are the optional sign, the
-digit sequence for an integer and the decimal fraction. The DEFINE
-group at the end of the pattern contains their definition. Notice
-that the decimal fraction pattern is the first place where we can
-reuse the integer pattern.
-</p>
-<pre class="verbatim"> /^ (?&osg)\ * ( (?&int)(?&dec)? |
(?&dec) )
- (?: [eE](?&osg)(?&int) )?
- $
- (?(DEFINE)
- (?<osg>[-+]?) # optional sign
- (?<int>\d++) # integer
- (?<dec>\.(?&int)) # decimal fraction
- )/x
-</pre>
-<hr>
-<a name="perlretut-Recursive-patterns"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlretut-A-bit-of-magic_003a-executing-Perl-code-in-a-regular-expression"
accesskey="n" rel="next">perlretut A bit of magic: executing Perl code in a
regular expression</a>, Previous: <a href="#perlretut-Defining-named-patterns"
accesskey="p" rel="prev">perlretut Defining named patterns</a>, Up: <a
href="#perlretut-Part-2_003a-Power-tools" accesskey="u" rel="up">perlretut Part
2: Power tools</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Recursive-patterns"></a>
-<h4 class="subsection">68.4.9 Recursive patterns</h4>
-
-<p>This feature (introduced in Perl 5.10) significantly extends the
-power of Perl’s pattern matching. By referring to some other
-capture group anywhere in the pattern with the construct
-<code>(?group-ref)</code>, the <em>pattern</em> within the referenced group is
used
-as an independent subpattern in place of the group reference itself.
-Because the group reference may be contained <em>within</em> the group it
-refers to, it is now possible to apply pattern matching to tasks that
-hitherto required a recursive parser.
-</p>
-<p>To illustrate this feature, we’ll design a pattern that matches if
-a string contains a palindrome. (This is a word or a sentence that,
-while ignoring spaces, interpunctuation and case, reads the same backwards
-as forwards. We begin by observing that the empty string or a string
-containing just one word character is a palindrome. Otherwise it must
-have a word character up front and the same at its end, with another
-palindrome in between.
-</p>
-<pre class="verbatim"> /(?: (\w) (?...Here be a palindrome...) \g{-1} | \w?
)/x
-</pre>
-<p>Adding <code>\W*</code> at either end to eliminate what is to be ignored,
we already
-have the full pattern:
-</p>
-<pre class="verbatim"> my $pp = qr/^(\W* (?: (\w) (?1) \g{-1} | \w? )
\W*)$/ix;
- for $s ( "saippuakauppias", "A man, a plan, a canal:
Panama!" ){
- print "'$s' is a palindrome\n" if $s =~ /$pp/;
- }
-</pre>
-<p>In <code>(?...)</code> both absolute and relative backreferences may be
used.
-The entire pattern can be reinserted with <code>(?R)</code> or
<code>(?0)</code>.
-If you prefer to name your groups, you can use <code>(?&name)</code> to
-recurse into that group.
-</p>
-<hr>
-<a
name="perlretut-A-bit-of-magic_003a-executing-Perl-code-in-a-regular-expression"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Backtracking-control-verbs" accesskey="n"
rel="next">perlretut Backtracking control verbs</a>, Previous: <a
href="#perlretut-Recursive-patterns" accesskey="p" rel="prev">perlretut
Recursive patterns</a>, Up: <a href="#perlretut-Part-2_003a-Power-tools"
accesskey="u" rel="up">perlretut Part 2: Power tools</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="A-bit-of-magic_003a-executing-Perl-code-in-a-regular-expression"></a>
-<h4 class="subsection">68.4.10 A bit of magic: executing Perl code in a
regular expression</h4>
-
-<p>Normally, regexps are a part of Perl expressions.
-<em>Code evaluation</em> expressions turn that around by allowing
-arbitrary Perl code to be a part of a regexp. A code evaluation
-expression is denoted <code>(?{code})</code>, with <em>code</em> a string of
Perl
-statements.
-</p>
-<p>Be warned that this feature is considered experimental, and may be
-changed without notice.
-</p>
-<p>Code expressions are zero-width assertions, and the value they return
-depends on their environment. There are two possibilities: either the
-code expression is used as a conditional in a conditional expression
-<code>(?(condition)...)</code>, or it is not. If the code expression is a
-conditional, the code is evaluated and the result (i.e., the result of
-the last statement) is used to determine truth or falsehood. If the
-code expression is not used as a conditional, the assertion always
-evaluates true and the result is put into the special variable
-<code>$^R</code>. The variable <code>$^R</code> can then be used in code
expressions later
-in the regexp. Here are some silly examples:
-</p>
-<pre class="verbatim"> $x = "abcdef";
- $x =~ /abc(?{print "Hi Mom!";})def/; # matches,
- # prints 'Hi Mom!'
- $x =~ /aaa(?{print "Hi Mom!";})def/; # doesn't match,
- # no 'Hi Mom!'
-</pre>
-<p>Pay careful attention to the next example:
-</p>
-<pre class="verbatim"> $x =~ /abc(?{print "Hi Mom!";})ddd/; #
doesn't match,
- # no 'Hi Mom!'
- # but why not?
-</pre>
-<p>At first glance, you’d think that it shouldn’t print, because
obviously
-the <code>ddd</code> isn’t going to match the target string. But look at
this
-example:
-</p>
-<pre class="verbatim"> $x =~ /abc(?{print "Hi Mom!";})[dD]dd/; #
doesn't match,
- # but _does_ print
-</pre>
-<p>Hmm. What happened here? If you’ve been following along, you know that
-the above pattern should be effectively (almost) the same as the last one;
-enclosing the <code>d</code> in a character class isn’t going to change
what it
-matches. So why does the first not print while the second one does?
-</p>
-<p>The answer lies in the optimizations the regex engine makes. In the first
-case, all the engine sees are plain old characters (aside from the
-<code>?{}</code> construct). It’s smart enough to realize that the
string ’ddd’
-doesn’t occur in our target string before actually running the pattern
-through. But in the second case, we’ve tricked it into thinking that our
-pattern is more complicated. It takes a look, sees our
-character class, and decides that it will have to actually run the
-pattern to determine whether or not it matches, and in the process of
-running it hits the print statement before it discovers that we don’t
-have a match.
-</p>
-<p>To take a closer look at how the engine does optimizations, see the
-section <a href="#perlretut-Pragmas-and-debugging">Pragmas and debugging</a>
below.
-</p>
-<p>More fun with <code>?{}</code>:
-</p>
-<pre class="verbatim"> $x =~ /(?{print "Hi Mom!";})/; #
matches,
- # prints 'Hi Mom!'
- $x =~ /(?{$c = 1;})(?{print "$c";})/; # matches,
- # prints '1'
- $x =~ /(?{$c = 1;})(?{print "$^R";})/; # matches,
- # prints '1'
-</pre>
-<p>The bit of magic mentioned in the section title occurs when the regexp
-backtracks in the process of searching for a match. If the regexp
-backtracks over a code expression and if the variables used within are
-localized using <code>local</code>, the changes in the variables produced by
the
-code expression are undone! Thus, if we wanted to count how many times
-a character got matched inside a group, we could use, e.g.,
-</p>
-<pre class="verbatim"> $x = "aaaa";
- $count = 0; # initialize 'a' count
- $c = "bob"; # test if $c gets clobbered
- $x =~ /(?{local $c = 0;}) # initialize count
- ( a # match 'a'
- (?{local $c = $c + 1;}) # increment count
- )* # do this any number of times,
- aa # but match 'aa' at the end
- (?{$count = $c;}) # copy local $c var into $count
- /x;
- print "'a' count is $count, \$c variable is '$c'\n";
-</pre>
-<p>This prints
-</p>
-<pre class="verbatim"> 'a' count is 2, $c variable is 'bob'
-</pre>
-<p>If we replace the
<code> (?{local $c = $c + 1;})</code><!-- /@w -->
with
-<code> (?{$c = $c + 1;})</code><!-- /@w -->, the
variable changes are <em>not</em> undone
-during backtracking, and we get
-</p>
-<pre class="verbatim"> 'a' count is 4, $c variable is 'bob'
-</pre>
-<p>Note that only localized variable changes are undone. Other side
-effects of code expression execution are permanent. Thus
-</p>
-<pre class="verbatim"> $x = "aaaa";
- $x =~ /(a(?{print "Yow\n";}))*aa/;
-</pre>
-<p>produces
-</p>
-<pre class="verbatim"> Yow
- Yow
- Yow
- Yow
-</pre>
-<p>The result <code>$^R</code> is automatically localized, so that it will
behave
-properly in the presence of backtracking.
-</p>
-<p>This example uses a code expression in a conditional to match a
-definite article, either ’the’ in English or
’der|die|das’ in German:
-</p>
-<pre class="verbatim"> $lang = 'DE'; # use German
- ...
- $text = "das";
- print "matched\n"
- if $text =~ /(?(?{
- $lang eq 'EN'; # is the language English?
- })
- the | # if so, then match 'the'
- (der|die|das) # else, match 'der|die|das'
- )
- /xi;
-</pre>
-<p>Note that the syntax here is <code>(?(?{...})yes-regexp|no-regexp)</code>,
not
-<code>(?((?{...}))yes-regexp|no-regexp)</code>. In other words, in the case
of a
-code expression, we don’t need the extra parentheses around the
-conditional.
-</p>
-<p>If you try to use code expressions where the code text is contained within
-an interpolated variable, rather than appearing literally in the pattern,
-Perl may surprise you:
-</p>
-<pre class="verbatim"> $bar = 5;
- $pat = '(?{ 1 })';
- /foo(?{ $bar })bar/; # compiles ok, $bar not interpolated
- /foo(?{ 1 })$bar/; # compiles ok, $bar interpolated
- /foo${pat}bar/; # compile error!
-
- $pat = qr/(?{ $foo = 1 })/; # precompile code regexp
- /foo${pat}bar/; # compiles ok
-</pre>
-<p>If a regexp has a variable that interpolates a code expression, Perl
-treats the regexp as an error. If the code expression is precompiled into
-a variable, however, interpolating is ok. The question is, why is this an
-error?
-</p>
-<p>The reason is that variable interpolation and code expressions
-together pose a security risk. The combination is dangerous because
-many programmers who write search engines often take user input and
-plug it directly into a regexp:
-</p>
-<pre class="verbatim"> $regexp = <>; # read user-supplied regexp
- $chomp $regexp; # get rid of possible newline
- $text =~ /$regexp/; # search $text for the $regexp
-</pre>
-<p>If the <code>$regexp</code> variable contains a code expression, the user
could
-then execute arbitrary Perl code. For instance, some joker could
-search for <code>system('rm <span
class="nolinebreak">-rf</span> *');</code><!-- /@w --> to erase your
files. In this
-sense, the combination of interpolation and code expressions <em>taints</em>
-your regexp. So by default, using both interpolation and code
-expressions in the same regexp is not allowed. If you’re not
-concerned about malicious users, it is possible to bypass this
-security check by invoking <code>use re 'eval'</code><!-- /@w -->:
-</p>
-<pre class="verbatim"> use re 'eval'; # throw caution out the door
- $bar = 5;
- $pat = '(?{ 1 })';
- /foo${pat}bar/; # compiles ok
-</pre>
-<p>Another form of code expression is the <em>pattern code expression</em>.
-The pattern code expression is like a regular code expression, except
-that the result of the code evaluation is treated as a regular
-expression and matched immediately. A simple example is
-</p>
-<pre class="verbatim"> $length = 5;
- $char = 'a';
- $x = 'aaaaabb';
- $x =~ /(??{$char x $length})/x; # matches, there are 5 of 'a'
-</pre>
-<p>This final example contains both ordinary and pattern code
-expressions. It detects whether a binary string <code>1101010010001...</code>
has a
-Fibonacci spacing 0,1,1,2,3,5,... of the <code>1</code>’s:
-</p>
-<pre class="verbatim"> $x = "1101010010001000001";
- $z0 = ''; $z1 = '0'; # initial conditions
- print "It is a Fibonacci sequence\n"
- if $x =~ /^1 # match an initial '1'
- (?:
- ((??{ $z0 })) # match some '0'
- 1 # and then a '1'
- (?{ $z0 = $z1; $z1 .= $^N; })
- )+ # repeat as needed
- $ # that is all there is
- /x;
- printf "Largest sequence matched was %d\n",
length($z1)-length($z0);
-</pre>
-<p>Remember that <code>$^N</code> is set to whatever was matched by the last
-completed capture group. This prints
-</p>
-<pre class="verbatim"> It is a Fibonacci sequence
- Largest sequence matched was 5
-</pre>
-<p>Ha! Try that with your garden variety regexp package...
-</p>
-<p>Note that the variables <code>$z0</code> and <code>$z1</code> are not
substituted when the
-regexp is compiled, as happens for ordinary variables outside a code
-expression. Rather, the whole code block is parsed as perl code at the
-same time as perl is compiling the code containing the literal regexp
-pattern.
-</p>
-<p>The regexp without the <code>//x</code> modifier is
-</p>
-<pre class="verbatim"> /^1(?:((??{ $z0 }))1(?{ $z0 = $z1; $z1 .= $^N; }))+$/
-</pre>
-<p>which shows that spaces are still possible in the code parts. Nevertheless,
-when working with code and conditional expressions, the extended form of
-regexps is almost necessary in creating and debugging regexps.
-</p>
-<hr>
-<a name="perlretut-Backtracking-control-verbs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-Pragmas-and-debugging" accesskey="n"
rel="next">perlretut Pragmas and debugging</a>, Previous: <a
href="#perlretut-A-bit-of-magic_003a-executing-Perl-code-in-a-regular-expression"
accesskey="p" rel="prev">perlretut A bit of magic: executing Perl code in a
regular expression</a>, Up: <a href="#perlretut-Part-2_003a-Power-tools"
accesskey="u" rel="up">perlretut Part 2: Power tools</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Backtracking-control-verbs"></a>
-<h4 class="subsection">68.4.11 Backtracking control verbs</h4>
-
-<p>Perl 5.10 introduced a number of control verbs intended to provide
-detailed control over the backtracking process, by directly influencing
-the regexp engine and by providing monitoring techniques. As all
-the features in this group are experimental and subject to change or
-removal in a future version of Perl, the interested reader is
-referred to <a href="#perlre-Special-Backtracking-Control-Verbs">perlre
Special Backtracking Control Verbs</a> for a
-detailed description.
-</p>
-<p>Below is just one example, illustrating the control verb
<code>(*FAIL)</code>,
-which may be abbreviated as <code>(*F)</code>. If this is inserted in a regexp
-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
-groups or produce results, it may be necessary to use this in
-combination with embedded code.
-</p>
-<pre class="verbatim"> %count = ();
- "supercalifragilisticexpialidocious" =~
- /([aeiou])(?{ $count{$1}++; })(*FAIL)/i;
- printf "%3d '%s'\n", $count{$_}, $_ for (sort keys %count);
-</pre>
-<p>The pattern begins with a class matching a subset of letters. Whenever
-this matches, a statement like <code>$count{'a'}++;</code> is executed,
incrementing
-the letter’s counter. Then <code>(*FAIL)</code> 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
-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
-</p>
-<pre class="verbatim"> $count{lc($_)}++ for split('',
"supercalifragilisticexpialidocious");
- printf "%3d '%s'\n", $count2{$_}, $_ for ( qw{ a e i o u } );
-</pre>
-<p>is considerably slower.)
-</p>
-<hr>
-<a name="perlretut-Pragmas-and-debugging"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlretut-Backtracking-control-verbs" accesskey="p"
rel="prev">perlretut Backtracking control verbs</a>, Up: <a
href="#perlretut-Part-2_003a-Power-tools" accesskey="u" rel="up">perlretut Part
2: Power tools</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Pragmas-and-debugging"></a>
-<h4 class="subsection">68.4.12 Pragmas and debugging</h4>
-
-<p>Speaking of debugging, there are several pragmas available to control
-and debug regexps in Perl. We have already encountered one pragma in
-the previous section, <code>use re 'eval';</code><!-- /@w -->, that
allows variable
-interpolation and code expressions to coexist in a regexp. The other
-pragmas are
-</p>
-<pre class="verbatim"> use re 'taint';
- $tainted = <>;
- @parts = ($tainted =~ /(\w+)\s+(\w+)/; # @parts is now tainted
-</pre>
-<p>The <code>taint</code> pragma causes any substrings from a match with a
tainted
-variable to be tainted as well. This is not normally the case, as
-regexps are often used to extract the safe bits from a tainted
-variable. Use <code>taint</code> when you are not extracting safe bits, but
are
-performing some other processing. Both <code>taint</code> and
<code>eval</code> pragmas
-are lexically scoped, which means they are in effect only until
-the end of the block enclosing the pragmas.
-</p>
-<pre class="verbatim"> use re '/m'; # or any other flags
- $multiline_string =~ /^foo/; # /m is implied
-</pre>
-<p>The <code>re '/flags'</code> pragma (introduced in Perl
-5.14) turns on the given regular expression flags
-until the end of the lexical scope. See
-<a href="re.html#g_t_0027_002fflags_0027-mode">(re)'/flags' mode</a> for more
-detail.
-</p>
-<pre class="verbatim"> use re 'debug';
- /^(.*)$/s; # output debugging info
-
- use re 'debugcolor';
- /^(.*)$/s; # output debugging info in living color
-</pre>
-<p>The global <code>debug</code> and <code>debugcolor</code> pragmas allow one
to get
-detailed debugging info about regexp compilation and
-execution. <code>debugcolor</code> is the same as debug, except the debugging
-information is displayed in color on terminals that can display
-termcap color sequences. Here is example output:
-</p>
-<pre class="verbatim"> % perl -e 'use re "debug"; "abc"
=~ /a*b+c/;'
- Compiling REx 'a*b+c'
- size 9 first at 1
- 1: STAR(4)
- 2: EXACT <a>(0)
- 4: PLUS(7)
- 5: EXACT <b>(0)
- 7: EXACT <c>(9)
- 9: END(0)
- floating 'bc' at 0..2147483647 (checking floating) minlen 2
- Guessing start of match, REx 'a*b+c' against 'abc'...
- Found floating substr 'bc' at offset 1...
- Guessed: match at offset 0
- Matching REx 'a*b+c' against 'abc'
- Setting an EVAL scope, savestack=3
- 0 <> <abc> | 1: STAR
- EXACT <a> can match 1 times out of 32767...
- Setting an EVAL scope, savestack=3
- 1 <a> <bc> | 4: PLUS
- EXACT <b> can match 1 times out of 32767...
- Setting an EVAL scope, savestack=3
- 2 <ab> <c> | 7: EXACT <c>
- 3 <abc> <> | 9: END
- Match successful!
- Freeing REx: 'a*b+c'
-</pre>
-<p>If you have gotten this far into the tutorial, you can probably guess
-what the different parts of the debugging output tell you. The first
-part
-</p>
-<pre class="verbatim"> Compiling REx 'a*b+c'
- size 9 first at 1
- 1: STAR(4)
- 2: EXACT <a>(0)
- 4: PLUS(7)
- 5: EXACT <b>(0)
- 7: EXACT <c>(9)
- 9: END(0)
-</pre>
-<p>describes the compilation stage. <code>STAR(4)</code> means that there is a
-starred object, in this case <code>'a'</code>, and if it matches, goto line 4,
-i.e., <code>PLUS(7)</code>. The middle lines describe some heuristics and
-optimizations performed before a match:
-</p>
-<pre class="verbatim"> floating 'bc' at 0..2147483647 (checking floating)
minlen 2
- Guessing start of match, REx 'a*b+c' against 'abc'...
- Found floating substr 'bc' at offset 1...
- Guessed: match at offset 0
-</pre>
-<p>Then the match is executed and the remaining lines describe the
-process:
-</p>
-<pre class="verbatim"> Matching REx 'a*b+c' against 'abc'
- Setting an EVAL scope, savestack=3
- 0 <> <abc> | 1: STAR
- EXACT <a> can match 1 times out of 32767...
- Setting an EVAL scope, savestack=3
- 1 <a> <bc> | 4: PLUS
- EXACT <b> can match 1 times out of 32767...
- Setting an EVAL scope, savestack=3
- 2 <ab> <c> | 7: EXACT <c>
- 3 <abc> <> | 9: END
- Match successful!
- Freeing REx: 'a*b+c'
-</pre>
-<p>Each step is of the form <code>n <x> <y></code><!--
/@w -->, with <code><x></code> the
-part of the string matched and <code><y></code> the part not yet
-matched. The <code>| 1: STAR</code><!-- /@w --> says
that Perl is at line number 1
-in the compilation list above. See
-<a href="#perldebguts-Debugging-Regular-Expressions">perldebguts Debugging
Regular Expressions</a> for much more detail.
-</p>
-<p>An alternative method of debugging regexps is to embed <code>print</code>
-statements within the regexp. This provides a blow-by-blow account of
-the backtracking in an alternation:
-</p>
-<pre class="verbatim"> "that this" =~ m@(?{print "Start at
position ", pos, "\n";})
- t(?{print "t1\n";})
- h(?{print "h1\n";})
- i(?{print "i1\n";})
- s(?{print "s1\n";})
- |
- t(?{print "t2\n";})
- h(?{print "h2\n";})
- a(?{print "a2\n";})
- t(?{print "t2\n";})
- (?{print "Done at position ", pos,
"\n";})
- @x;
-</pre>
-<p>prints
-</p>
-<pre class="verbatim"> Start at position 0
- t1
- h1
- t2
- h2
- a2
- t2
- Done at position 4
-</pre>
-<hr>
-<a name="perlretut-BUGS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-SEE-ALSO" accesskey="n" rel="next">perlretut SEE
ALSO</a>, Previous: <a href="#perlretut-Part-2_003a-Power-tools" accesskey="p"
rel="prev">perlretut Part 2: Power tools</a>, Up: <a href="#perlretut"
accesskey="u" rel="up">perlretut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="BUGS-8"></a>
-<h3 class="section">68.5 BUGS</h3>
-
-<p>Code expressions, conditional expressions, and independent expressions
-are <em>experimental</em>. Don’t use them in production code. Yet.
-</p>
-<hr>
-<a name="perlretut-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlretut-AUTHOR-AND-COPYRIGHT" accesskey="n"
rel="next">perlretut AUTHOR AND COPYRIGHT</a>, Previous: <a
href="#perlretut-BUGS" accesskey="p" rel="prev">perlretut BUGS</a>, Up: <a
href="#perlretut" accesskey="u" rel="up">perlretut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-35"></a>
-<h3 class="section">68.6 SEE ALSO</h3>
-
-<p>This is just a tutorial. For the full story on Perl regular
-expressions, see the <a href="#perlre-NAME">perlre NAME</a> regular
expressions reference page.
-</p>
-<p>For more information on the matching <code>m//</code> and substitution
<code>s///</code>
-operators, see <a href="#perlop-Regexp-Quote_002dLike-Operators">perlop Regexp
Quote-Like Operators</a>. For
-information on the <code>split</code> operation, see <a
href="#perlfunc-split">perlfunc split</a>.
-</p>
-<p>For an excellent all-around resource on the care and feeding of
-regular expressions, see the book <em>Mastering Regular Expressions</em> by
-Jeffrey Friedl (published by O’Reilly, ISBN 1556592-257-3).
-</p>
-<hr>
-<a name="perlretut-AUTHOR-AND-COPYRIGHT"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlretut-SEE-ALSO" accesskey="p" rel="prev">perlretut SEE
ALSO</a>, Up: <a href="#perlretut" accesskey="u" rel="up">perlretut</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-AND-COPYRIGHT-1"></a>
-<h3 class="section">68.7 AUTHOR AND COPYRIGHT</h3>
-
-<p>Copyright (c) 2000 Mark Kvale
-All rights reserved.
-</p>
-<p>This document may be distributed under the same terms as Perl itself.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlretut-Acknowledgments"
accesskey="1">perlretut Acknowledgments</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlretut-Acknowledgments"></a>
-<div class="header">
-<p>
-Up: <a href="#perlretut-AUTHOR-AND-COPYRIGHT" accesskey="u" rel="up">perlretut
AUTHOR AND COPYRIGHT</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Acknowledgments-1"></a>
-<h4 class="subsection">68.7.1 Acknowledgments</h4>
-
-<p>The inspiration for the stop codon DNA example came from the ZIP
-code example in chapter 7 of <em>Mastering Regular Expressions</em>.
-</p>
-<p>The author would like to thank Jeff Pinyan, Andrew Johnson, Peter
-Haworth, Ronald J Kimball, and Joe Smith for all their helpful
-comments.
-</p>
-<hr>
-<a name="perlrun"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsec" accesskey="n" rel="next">perlsec</a>, Previous: <a
href="#perlretut" accesskey="p" rel="prev">perlretut</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlrun-1"></a>
-<h2 class="chapter">69 perlrun</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlrun-NAME"
accesskey="1">perlrun NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrun-SYNOPSIS"
accesskey="2">perlrun SYNOPSIS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrun-DESCRIPTION"
accesskey="3">perlrun DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrun-ENVIRONMENT"
accesskey="4">perlrun ENVIRONMENT</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrun-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrun-SYNOPSIS" accesskey="n" rel="next">perlrun
SYNOPSIS</a>, Up: <a href="#perlrun" accesskey="u" rel="up">perlrun</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-68"></a>
-<h3 class="section">69.1 NAME</h3>
-
-<p>perlrun - how to execute the Perl interpreter
-</p>
-<hr>
-<a name="perlrun-SYNOPSIS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrun-DESCRIPTION" accesskey="n" rel="next">perlrun
DESCRIPTION</a>, Previous: <a href="#perlrun-NAME" accesskey="p"
rel="prev">perlrun NAME</a>, Up: <a href="#perlrun" accesskey="u"
rel="up">perlrun</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SYNOPSIS-9"></a>
-<h3 class="section">69.2 SYNOPSIS</h3>
-
-<p><strong>perl</strong> [ <strong><span
class="nolinebreak">-sTtuUWX</span></strong> ]<!-- /@w -->
- [ <strong><span
class="nolinebreak">-hv</span></strong> ] [ <strong><span
class="nolinebreak">-V</span></strong>[:<em>configvar</em>] ]<!-- /@w -->
- [ <strong><span
class="nolinebreak">-cw</span></strong> ] [ <strong><span
class="nolinebreak">-d</span></strong>[<strong>t</strong>][:<em>debugger</em>] ] [ <strong><span
class="nolinebreak">-D</span></strong>[<em>number/list</em>] ]<!-- /@w -->
- [ <strong><span
class="nolinebreak">-pna</span></strong> ] [ <strong><span
class="nolinebreak">-F</span></strong><em>pattern</em> ] [ <strong><span
class="nolinebreak">-l</span></strong>[<em>octal</em>] ] [ <strong><span
class="nolinebreak">-0</span></strong>[<em>octal/hexadecimal</em>] ]<!--
/@w -->
- [ <strong><span
class="nolinebreak">-I</span></strong><em>dir</em> ] [ <strong><span
class="nolinebreak">-m</span></strong>[<strong><span
class="nolinebreak">-</span></strong>]<em>module</em> ] [ <strong><span
class="nolinebreak">-M</span></strong>[<strong><span
class="nolinebreak">-</span></strong>]<em>’module...’</em> ] [ <strong><span
class="nolinebreak">-f</span></strong> ]<!-- /@w -->
- [ <strong><span
class="nolinebreak">-C</span> [<em>number/list</em>] </strong>]<!--
/@w -->
- [ <strong><span class="nolinebreak">-S</span></strong> ]<!--
/@w -->
- [ <strong><span
class="nolinebreak">-x</span></strong>[<em>dir</em>] ]<!-- /@w -->
- [ <strong><span
class="nolinebreak">-i</span></strong>[<em>extension</em>] ]<!-- /@w -->
- [ [<strong><span
class="nolinebreak">-e</span></strong>|<strong><span
class="nolinebreak">-E</span></strong>] <em>’command’</em> ] [ <strong>–</strong> ] [ <em>programfile</em> ] [ <em>argument</em> ]...<!--
/@w -->
-</p>
-<hr>
-<a name="perlrun-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrun-ENVIRONMENT" accesskey="n" rel="next">perlrun
ENVIRONMENT</a>, Previous: <a href="#perlrun-SYNOPSIS" accesskey="p"
rel="prev">perlrun SYNOPSIS</a>, Up: <a href="#perlrun" accesskey="u"
rel="up">perlrun</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-67"></a>
-<h3 class="section">69.3 DESCRIPTION</h3>
-
-<p>The normal way to run a Perl program is by making it directly
-executable, or else by passing the name of the source file as an
-argument on the command line. (An interactive Perl environment
-is also possible–see <a href="#perldebug-NAME">perldebug NAME</a> for
details on how to do that.)
-Upon startup, Perl looks for your program in one of the following
-places:
-</p>
-<ol>
-<li> Specified line by line via <strong>-e</strong> or <strong>-E</strong>
switches on the command line.
-
-</li><li> Contained in the file specified by the first filename on the command
line.
-(Note that systems supporting the <code>#!</code> notation invoke interpreters
this
-way. See <a href="#perlrun-Location-of-Perl">Location of Perl</a>.)
-
-</li><li> Passed in implicitly via standard input. This works only if there
are
-no filename arguments–to pass arguments to a STDIN-read program you
-must explicitly specify a "-" for the program name.
-
-</li></ol>
-
-<p>With methods 2 and 3, Perl starts parsing the input file from the
-beginning, unless you’ve specified a <strong>-x</strong> switch, in
which case it
-scans for the first line starting with <code>#!</code> 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 <code>__END__</code> token.)
-</p>
-<p>The <code>#!</code> 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 <code>#!</code> line, or worse, doesn’t even recognize the
<code>#!</code> line, you
-still can get consistent switch behaviour regardless of how Perl was
-invoked, even if <strong>-x</strong> was used to find the beginning of the
program.
-</p>
-<p>Because historically some operating systems silently chopped off
-kernel interpretation of the <code>#!</code> 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
-before or after that 32-character boundary. Most switches don’t
-actually care if they’re processed redundantly, but getting a
"-"
-instead of a complete switch could cause Perl to try to execute
-standard input instead of your program. And a partial <strong>-I</strong>
switch
-could also cause odd results.
-</p>
-<p>Some switches do care if they are processed twice, for instance
-combinations of <strong>-l</strong> and <strong>-0</strong>. Either put all
the switches after
-the 32-character boundary (if applicable), or replace the use of
-<strong>-0</strong><em>digits</em> by <code>BEGIN{ $/ = "\0digits";
}</code>.
-</p>
-<p>Parsing of the <code>#!</code> 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
-</p>
-<pre class="verbatim"> #!/bin/sh
- #! -*-perl-*-
- eval 'exec perl -x -wS $0 ${1+"$@"}'
- if 0;
-</pre>
-<p>to let Perl see the <strong>-p</strong> switch.
-</p>
-<p>A similar trick involves the <em>env</em> program, if you have it.
-</p>
-<pre class="verbatim"> #!/usr/bin/env perl
-</pre>
-<p>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.14.1, you should place
-that directly in the <code>#!</code> line’s path.
-</p>
-<p>If the <code>#!</code> line does not contain the word "perl" nor
the word "indir"
-the program named after the <code>#!</code> is executed instead of the Perl
-interpreter. This is slightly bizarre, but it helps people on machines
-that don’t do <code>#!</code>, because they can tell a program that
their SHELL is
-<samp>/usr/bin/perl</samp>, and Perl will then dispatch the program to the
correct
-interpreter for them.
-</p>
-<p>After locating your program, Perl compiles the entire program to an
-internal form. If there are any compilation errors, execution of the
-program is not attempted. (This is unlike the typical shell script,
-which might run part-way through before finding a syntax error.)
-</p>
-<p>If the program is syntactically correct, it is executed. If the program
-runs off the end without hitting an exit() or die() operator, an implicit
-<code>exit(0)</code> is provided to indicate successful completion.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlrun-_0023_0021-and-quoting-on-non_002dUnix-systems"
accesskey="1">perlrun #! and quoting on non-Unix
systems</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrun-Location-of-Perl"
accesskey="2">perlrun Location of Perl</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlrun-Command-Switches"
accesskey="3">perlrun Command Switches</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlrun-_0023_0021-and-quoting-on-non_002dUnix-systems"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrun-Location-of-Perl" accesskey="n" rel="next">perlrun
Location of Perl</a>, Up: <a href="#perlrun-DESCRIPTION" accesskey="u"
rel="up">perlrun DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="g_t_0023_0021-and-quoting-on-non_002dUnix-systems"></a>
-<h4 class="subsection">69.3.1 #! and quoting on non-Unix systems</h4>
-
-<p>Unix’s <code>#!</code> technique can be simulated on other systems:
-</p>
-<dl compact="compact">
-<dt>OS/2</dt>
-<dd><a name="perlrun-OS_002f2"></a>
-<p>Put
-</p>
-<pre class="verbatim"> extproc perl -S -your_switches
-</pre>
-<p>as the first line in <code>*.cmd</code> file (<strong>-S</strong> due to a
bug in cmd.exe’s
-‘extproc’ handling).
-</p>
-</dd>
-<dt>MS-DOS</dt>
-<dd><a name="perlrun-MS_002dDOS"></a>
-<p>Create a batch file to run your program, and codify it in
-<code>ALTERNATE_SHEBANG</code> (see the <samp>dosish.h</samp> file in the
source
-distribution for more information).
-</p>
-</dd>
-<dt>Win95/NT</dt>
-<dd><a name="perlrun-Win95_002fNT"></a>
-<p>The Win95/NT installation, when using the ActiveState installer for Perl,
-will modify the Registry to associate the <samp>.pl</samp> extension with the
perl
-interpreter. If you install Perl by other means (including building from
-the sources), you may have to modify the Registry yourself. Note that
-this means you can no longer tell the difference between an executable
-Perl program and a Perl library file.
-</p>
-</dd>
-<dt>VMS</dt>
-<dd><a name="perlrun-VMS"></a>
-<p>Put
-</p>
-<pre class="verbatim"> $ perl -mysw 'f$env("procedure")' 'p1' 'p2'
'p3' 'p4' 'p5' 'p6' 'p7' 'p8' !
- $ exit++ + ++$status != 0 and $exit = $status = undef;
-</pre>
-<p>at the top of your program, where <strong>-mysw</strong> are any command
line switches you
-want to pass to Perl. You can now invoke the program directly, by saying
-<code>perl program</code>, or as a DCL procedure, by saying
<code>@program</code> (or implicitly
-via <samp>DCL$PATH</samp> by just using the name of the program).
-</p>
-<p>This incantation is a bit much to remember, but Perl will display it for
-you if you say <code>perl "-V:startperl"</code>.
-</p>
-</dd>
-</dl>
-
-<p>Command-interpreters on non-Unix systems have rather different ideas
-on quoting than Unix shells. You’ll need to learn the special
-characters in your command-interpreter (<code>*</code>, <code>\</code> and
<code>"</code> are
-common) and how to protect whitespace and these characters to run
-one-liners (see <a href="#perlrun-_002de-commandline">-e</a> below).
-</p>
-<p>On some systems, you may have to change single-quotes to double ones,
-which you must <em>not</em> do on Unix or Plan 9 systems. You might also
-have to change a single % to a %%.
-</p>
-<p>For example:
-</p>
-<pre class="verbatim"> # Unix
- perl -e 'print "Hello world\n"'
-
- # MS-DOS, etc.
- perl -e "print \"Hello world\n\""
-
- # VMS
- perl -e "print ""Hello world\n"""
-</pre>
-<p>The problem is that none of this is reliable: it depends on the
-command and it is entirely possible neither works. If <em>4DOS</em> were
-the command shell, this would probably work better:
-</p>
-<pre class="verbatim"> perl -e "print <Ctrl-x>"Hello
world\n<Ctrl-x>""
-</pre>
-<p><strong>CMD.EXE</strong> in Windows NT slipped a lot of standard Unix
functionality in
-when nobody was looking, but just try to find documentation for its
-quoting rules.
-</p>
-<p>There is no general solution to all of this. It’s just a mess.
-</p>
-<hr>
-<a name="perlrun-Location-of-Perl"></a>
-<div class="header">
-<p>
-Next: <a href="#perlrun-Command-Switches" accesskey="n" rel="next">perlrun
Command Switches</a>, Previous: <a
href="#perlrun-_0023_0021-and-quoting-on-non_002dUnix-systems" accesskey="p"
rel="prev">perlrun #! and quoting on non-Unix systems</a>, Up: <a
href="#perlrun-DESCRIPTION" accesskey="u" rel="up">perlrun DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Location-of-Perl"></a>
-<h4 class="subsection">69.3.2 Location of Perl</h4>
-
-<p>It may seem obvious to say, but Perl is useful only when users can
-easily find it. When possible, it’s good for both
<samp>/usr/bin/perl</samp>
-and <samp>/usr/local/bin/perl</samp> to be symlinks to the actual binary. If
-that can’t be done, system administrators are strongly encouraged
-to put (symlinks to) perl and its accompanying utilities into a
-directory typically found along a user’s PATH, or in some other
-obvious and convenient place.
-</p>
-<p>In this documentation, <code>#!/usr/bin/perl</code> on the first line of
the program
-will stand in for whatever method works on your system. You are
-advised to use a specific path if you care about a specific version.
-</p>
-<pre class="verbatim"> #!/usr/local/bin/perl5.14
-</pre>
-<p>or if you just want to be running at least version, place a statement
-like this at the top of your program:
-</p>
-<pre class="verbatim"> use 5.014;
-</pre>
-<hr>
-<a name="perlrun-Command-Switches"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlrun-Location-of-Perl" accesskey="p" rel="prev">perlrun
Location of Perl</a>, Up: <a href="#perlrun-DESCRIPTION" accesskey="u"
rel="up">perlrun DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Command-Switches"></a>
-<h4 class="subsection">69.3.3 Command Switches</h4>
-
-<p>As with all standard commands, a single-character switch may be
-clustered with the following switch, if any.
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -spi.orig # same as -s -p -i.orig
-</pre>
-<p>A <code>--</code> signals the end of options and disables further option
processing. Any
-arguments after the <code>--</code> are treated as filenames and arguments.
-</p>
-<p>Switches include:
-</p>
-<dl compact="compact">
-<dt><strong>-0</strong>[<em>octal/hexadecimal</em>]</dt>
-<dd><a name="perlrun-_002d0_005boctal_002fhexadecimal_005d"></a>
-<p>specifies the input record separator (<code>$/</code>) 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 <em>find</em> which can print filenames
-terminated by the null character, you can say this:
-</p>
-<pre class="verbatim"> find . -name '*.orig' -print0 | perl -n0e unlink
-</pre>
-<p>The special value 00 will cause Perl to slurp files in paragraph mode.
-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.
-</p>
-<p>You can also specify the separator character using hexadecimal notation:
-<strong>-0x<em>HHH...</em></strong>, where the <code><em>H</em></code> 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 <em>really</em> want a record separator of 0777,
-specify it as <strong>-0x1FF</strong>. (This means that you cannot use the
<strong>-x</strong> option
-with a directory name that consists of hexadecimal digits, or else Perl
-will think you have specified a hex number to <strong>-0</strong>.)
-</p>
-</dd>
-<dt><strong>-a</strong></dt>
-<dd><a name="perlrun-_002da"></a>
-<p>turns on autosplit mode when used with a <strong>-n</strong> or
<strong>-p</strong>. An implicit
-split command to the @F array is done as the first thing inside the
-implicit while loop produced by the <strong>-n</strong> or <strong>-p</strong>.
-</p>
-<pre class="verbatim"> perl -ane 'print pop(@F), "\n";'
-</pre>
-<p>is equivalent to
-</p>
-<pre class="verbatim"> while (<>) {
- @F = split(' ');
- print pop(@F), "\n";
- }
-</pre>
-<p>An alternate delimiter may be specified using <strong>-F</strong>.
-</p>
-<p><strong>-a</strong> implicitly sets <strong>-n</strong>.
-</p>
-</dd>
-<dt><strong>-C [<em>number/list</em>]</strong></dt>
-<dd><a name="perlrun-_002dC-_005bnumber_002flist_005d"></a>
-<p>The <strong>-C</strong> flag controls some of the Perl Unicode features.
-</p>
-<p>As of 5.8.1, the <strong>-C</strong> 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.
-</p>
-<pre class="verbatim"> I 1 STDIN is assumed to be in UTF-8
- O 2 STDOUT will be in UTF-8
- E 4 STDERR will be in UTF-8
- S 7 I + O + E
- i 8 UTF-8 is the default PerlIO layer for input streams
- o 16 UTF-8 is the default PerlIO layer for output streams
- D 24 i + o
- A 32 the @ARGV elements are expected to be strings encoded
- in UTF-8
- L 64 normally the "IOEioA" are unconditional, the L makes
- them conditional on the locale environment variables
- (the LC_ALL, LC_CTYPE, and LANG, in the order of
- decreasing precedence) -- if the variables indicate
- UTF-8, then the selected "IOEioA" are in effect
- a 256 Set ${^UTF8CACHE} to -1, to run the UTF-8 caching
- code in debugging mode.
-</pre>
-<p>For example, <strong>-COE</strong> and <strong>-C6</strong> will both turn
on UTF-8-ness on both
-STDOUT and STDERR. Repeating letters is just redundant, not cumulative
-nor toggling.
-</p>
-<p>The <code>io</code> options mean that any subsequent open() (or similar I/O
-operations) in the current file scope will have the <code>:utf8</code> 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.
-</p>
-<p><strong>-C</strong> on its own (not followed by any number or option list),
or the
-empty string <code>""</code> for the <code>PERL_UNICODE</code>
environment variable, has the
-same effect as <strong>-CSDL</strong>. In other words, the standard I/O
handles and
-the default <code>open()</code> layer are UTF-8-fied <em>but</em> only if the
locale
-environment variables indicate a UTF-8 locale. This behaviour follows
-the <em>implicit</em> (and problematic) UTF-8 behaviour of Perl 5.8.0.
-(See <a
href="perl581delta.html#UTF_002d8-no-longer-default-under-UTF_002d8-locales">(perl581delta)UTF-8
no longer default under UTF-8 locales</a>.)
-</p>
-<p>You can use <strong>-C0</strong> (or <code>"0"</code> for
<code>PERL_UNICODE</code>) to explicitly
-disable all the above Unicode features.
-</p>
-<p>The read-only magic variable <code>${^UNICODE}</code> reflects the numeric
value
-of this setting. This variable is set during Perl startup and is
-thereafter read-only. If you want runtime effects, use the three-arg
-open() (see ‘perlfunc open’), the two-arg binmode() (see
‘perlfunc binmode’),
-and the <code>open</code> pragma (see <a href="open.html#Top">(open)</a>).
-</p>
-<p>(In Perls earlier than 5.8.1 the <strong>-C</strong> 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".)
-</p>
-<p><strong>Note:</strong> Since perl 5.10.1, if the <strong>-C</strong> option
is used on the <code>#!</code> 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.
-</p>
-</dd>
-<dt><strong>-c</strong></dt>
-<dd><a name="perlrun-_002dc"></a>
-<p>causes Perl to check the syntax of the program and then exit without
-executing it. Actually, it <em>will</em> execute and <code>BEGIN</code>,
<code>UNITCHECK</code>,
-or <code>CHECK</code> blocks and any <code>use</code> statements: these are
considered as
-occurring outside the execution of your program. <code>INIT</code> and
<code>END</code>
-blocks, however, will be skipped.
-</p>
-</dd>
-<dt><strong>-d</strong></dt>
-<dd><a name="perlrun-_002dd"></a>
-</dd>
-<dt><strong>-dt</strong></dt>
-<dd><a name="perlrun-_002ddt"></a>
-<p>runs the program under the Perl debugger. See <a
href="#perldebug-NAME">perldebug NAME</a>.
-If <strong>t</strong> is specified, it indicates to the debugger that threads
-will be used in the code being debugged.
-</p>
-</dd>
-<dt><strong>-d:</strong><em>MOD[=bar,baz]</em></dt>
-<dd><a name="perlrun-_002dd_003aMOD_005b_003dbar_002cbaz_005d"></a>
-</dd>
-<dt><strong>-dt:</strong><em>MOD[=bar,baz]</em></dt>
-<dd><a name="perlrun-_002ddt_003aMOD_005b_003dbar_002cbaz_005d"></a>
-<p>runs the program under the control of a debugging, profiling, or tracing
-module installed as <code>Devel::<em>MOD</em></code>. E.g.,
<strong>-d:DProf</strong> executes the
-program using the <code>Devel::DProf</code> profiler. As with the
<strong>-M</strong> flag, options
-may be passed to the <code>Devel::<em>MOD</em></code> package where they will
be received
-and interpreted by the <code>Devel::<em>MOD</em>::import</code> routine.
Again, like <strong>-M</strong>,
-use -<strong>-d:-<em>MOD</em></strong> to call
<code>Devel::<em>MOD</em>::unimport</code> instead of import. The
-comma-separated list of options must follow a <code>=</code> character. If
<strong>t</strong> is
-specified, it indicates to the debugger that threads will be used in the
-code being debugged. See <a href="#perldebug-NAME">perldebug NAME</a>.
-</p>
-</dd>
-<dt><strong>-D</strong><em>letters</em></dt>
-<dd><a name="perlrun-_002dDletters"></a>
-</dd>
-<dt><strong>-D</strong><em>number</em></dt>
-<dd><a name="perlrun-_002dDnumber"></a>
-<p>sets debugging flags. To watch how it executes your program, use
-<strong>-Dtls</strong>. (This works only if debugging is compiled into your
-Perl.) Another nice value is <strong>-Dx</strong>, which lists your compiled
-syntax tree. And <strong>-Dr</strong> displays compiled regular expressions;
-the format of the output is explained in <a
href="#perldebguts-NAME">perldebguts NAME</a>.
-</p>
-<p>As an alternative, specify a number instead of list of letters (e.g.,
-<strong>-D14</strong> is equivalent to <strong>-Dtls</strong>):
-</p>
-<pre class="verbatim"> 1 p Tokenizing and parsing (with v, displays
parse stack)
- 2 s Stack snapshots (with v, displays all stacks)
- 4 l Context (loop) stack processing
- 8 t Trace execution
- 16 o Method and overloading resolution
- 32 c String/numeric conversions
- 64 P Print profiling info, source file input state
- 128 m Memory and SV allocation
- 256 f Format processing
- 512 r Regular expression parsing and execution
- 1024 x Syntax tree dump
- 2048 u Tainting checks
- 4096 U Unofficial, User hacking (reserved for private,
- unreleased use)
- 8192 H Hash dump -- usurps values()
- 16384 X Scratchpad allocation
- 32768 D Cleaning up
- 65536 S Op slab allocation
- 131072 T Tokenizing
- 262144 R Include reference counts of dumped variables (eg when
- using -Ds)
- 524288 J show s,t,P-debug (don't Jump over) on opcodes within
- package DB
- 1048576 v Verbose: use in conjunction with other flags
- 2097152 C Copy On Write
- 4194304 A Consistency checks on internal structures
- 8388608 q quiet - currently only suppresses the "EXECUTING"
- message
- 16777216 M trace smart match resolution
- 33554432 B dump suBroutine definitions, including special Blocks
- like BEGIN
- 67108864 L trace Locale-related info; what gets output is very
- subject to change
-</pre>
-<p>All these flags require <strong>-DDEBUGGING</strong> when you compile the
Perl
-executable (but see <code>:opd</code> in <a
href="Devel-Peek.html#Top">(Devel-Peek)</a> or <a
href="re.html#g_t_0027debug_0027-mode">(re)'debug' mode</a>
-which may change this).
-See the <samp>INSTALL</samp> file in the Perl source distribution
-for how to do this. This flag is automatically set if you include
<strong>-g</strong>
-option when <code>Configure</code> asks you about optimizer/debugger flags.
-</p>
-<p>If you’re just trying to get a print out of each line of Perl code
-as it executes, the way that <code>sh -x</code> provides for shell scripts,
-you can’t use Perl’s <strong>-D</strong> switch. Instead do this
-</p>
-<pre class="verbatim"> # If you have "env" utility
- env PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
-
- # Bourne shell syntax
- $ PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
-
- # csh syntax
- % (setenv PERLDB_OPTS "NonStop=1 AutoTrace=1 frame=2"; perl -dS
program)
-</pre>
-<p>See <a href="#perldebug-NAME">perldebug NAME</a> for details and variations.
-</p>
-</dd>
-<dt><strong>-e</strong> <em>commandline</em></dt>
-<dd><a name="perlrun-_002de-commandline"></a>
-<p>may be used to enter one line of program. If <strong>-e</strong> is given,
Perl
-will not look for a filename in the argument list. Multiple
<strong>-e</strong>
-commands may be given to build up a multi-line script. Make sure
-to use semicolons where you would in a normal program.
-</p>
-</dd>
-<dt><strong>-E</strong> <em>commandline</em></dt>
-<dd><a name="perlrun-_002dE-commandline"></a>
-<p>behaves just like <strong>-e</strong>, except that it implicitly enables all
-optional features (in the main compilation unit). See <a
href="feature.html#Top">(feature)</a>.
-</p>
-</dd>
-<dt><strong>-f</strong></dt>
-<dd><a name="perlrun-_002df"></a>
-<p>Disable executing <samp>$Config{sitelib}/sitecustomize.pl</samp> at startup.
-</p>
-<p>Perl can be built so that it by default will try to execute
-<samp>$Config{sitelib}/sitecustomize.pl</samp> 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
-find modules in non-standard locations.
-</p>
-<p>Perl actually inserts the following code:
-</p>
-<pre class="verbatim"> BEGIN {
- do { local $!; -f "$Config{sitelib}/sitecustomize.pl"; }
- && do "$Config{sitelib}/sitecustomize.pl";
- }
-</pre>
-<p>Since it is an actual <code>do</code> (not a <code>require</code>),
<samp>sitecustomize.pl</samp>
-doesn’t need to return a true value. The code is run in package
<code>main</code>,
-in its own lexical scope. However, if the script dies, <code>$@</code> will not
-be set.
-</p>
-<p>The value of <code>$Config{sitelib}</code> is also determined in C code and
not
-read from <code>Config.pm</code>, which is not loaded.
-</p>
-<p>The code is executed <em>very</em> early. For example, any changes made to
-<code>@INC</code> will show up in the output of ‘perl -V‘. Of
course, <code>END</code>
-blocks will be likewise executed very late.
-</p>
-<p>To determine at runtime if this capability has been compiled in your
-perl, you can check the value of <code>$Config{usesitecustomize}</code>.
-</p>
-</dd>
-<dt><strong>-F</strong><em>pattern</em></dt>
-<dd><a name="perlrun-_002dFpattern"></a>
-<p>specifies the pattern to split on for <strong>-a</strong>. The pattern may
be
-surrounded by <code>//</code>, <code>""</code>, or <code>''</code>,
otherwise it will be put in single
-quotes. You can’t use literal whitespace in the pattern.
-</p>
-<p><strong>-F</strong> implicitly sets both <strong>-a</strong> and
<strong>-n</strong>.
-</p>
-</dd>
-<dt><strong>-h</strong></dt>
-<dd><a name="perlrun-_002dh"></a>
-<p>prints a summary of the options.
-</p>
-</dd>
-<dt><strong>-i</strong>[<em>extension</em>]</dt>
-<dd><a name="perlrun-_002di_005bextension_005d"></a>
-<p>specifies that files processed by the <code><></code> construct are
to be
-edited in-place. It does this by renaming the input file, opening the
-output file by the original name, and selecting that output file as the
-default for print() statements. The extension, if supplied, is used to
-modify the name of the old file to make a backup copy, following these
-rules:
-</p>
-<p>If no extension is supplied, and your system supports it, the original
-<em>file</em> is kept open without a name while the output is redirected to
-a new file with the original <em>filename</em>. When perl exits, cleanly or
not,
-the original <em>file</em> is unlinked.
-</p>
-<p>If the extension doesn’t contain a <code>*</code>, then it is
appended to the
-end of the current filename as a suffix. If the extension does
-contain one or more <code>*</code> characters, then each <code>*</code> is
replaced
-with the current filename. In Perl terms, you could think of this
-as:
-</p>
-<pre class="verbatim"> ($backup = $extension) =~ s/\*/$file_name/g;
-</pre>
-<p>This allows you to add a prefix to the backup file, instead of (or in
-addition to) a suffix:
-</p>
-<pre class="verbatim"> $ perl -pi'orig_*' -e 's/bar/baz/' fileA # backup to
- # 'orig_fileA'
-</pre>
-<p>Or even to place backup copies of the original files into another
-directory (provided the directory already exists):
-</p>
-<pre class="verbatim"> $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA # backup
to
- # 'old/fileA.orig'
-</pre>
-<p>These sets of one-liners are equivalent:
-</p>
-<pre class="verbatim"> $ perl -pi -e 's/bar/baz/' fileA # overwrite
current file
- $ perl -pi'*' -e 's/bar/baz/' fileA # overwrite current file
-
- $ perl -pi'.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
- $ perl -pi'*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
-</pre>
-<p>From the shell, saying
-</p>
-<pre class="verbatim"> $ perl -p -i.orig -e "s/foo/bar/; ... "
-</pre>
-<p>is the same as using the program:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -pi.orig
- s/foo/bar/;
-</pre>
-<p>which is equivalent to
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
- $extension = '.orig';
- LINE: while (<>) {
- if ($ARGV ne $oldargv) {
- if ($extension !~ /\*/) {
- $backup = $ARGV . $extension;
- }
- else {
- ($backup = $extension) =~ s/\*/$ARGV/g;
- }
- rename($ARGV, $backup);
- open(ARGVOUT, ">$ARGV");
- select(ARGVOUT);
- $oldargv = $ARGV;
- }
- s/foo/bar/;
- }
- continue {
- print; # this prints to original filename
- }
- select(STDOUT);
-</pre>
-<p>except that the <strong>-i</strong> form doesn’t need to compare
$ARGV to $oldargv to
-know when the filename has changed. It does, however, use ARGVOUT for
-the selected filehandle. Note that STDOUT is restored as the default
-output filehandle after the loop.
-</p>
-<p>As shown above, Perl creates the backup file whether or not any output
-is actually changed. So this is just a fancy way to copy files:
-</p>
-<pre class="verbatim"> $ perl -p -i'/some/file/path/*' -e 1 file1 file2
file3...
-or
- $ perl -p -i'.orig' -e 1 file1 file2 file3...
-</pre>
-<p>You can use <code>eof</code> without parentheses to locate the end of each
input
-file, in case you want to append to each file, or reset line numbering
-(see example in <a href="#perlfunc-eof">perlfunc eof</a>).
-</p>
-<p>If, for a given file, Perl is unable to create the backup file as
-specified in the extension then it will skip that file and continue on
-with the next one (if it exists).
-</p>
-<p>For a discussion of issues surrounding file permissions and
<strong>-i</strong>, see
-<a
href="perlfaq5.html#Why-does-Perl-let-me-delete-read_002donly-files_003f-Why-does-_002di-clobber-protected-files_003f-Isn_0027t-this-a-bug-in-Perl_003f">(perlfaq5)Why
does Perl let me delete read-only files? Why does -i clobber
-protected files? Isn't this a bug in Perl?</a>.
-</p>
-<p>You cannot use <strong>-i</strong> to create directories or to strip
extensions from
-files.
-</p>
-<p>Perl does not expand <code>~</code> in filenames, which is good, since some
-folks use it for their backup files:
-</p>
-<pre class="verbatim"> $ perl -pi~ -e 's/foo/bar/' file1 file2 file3...
-</pre>
-<p>Note that because <strong>-i</strong> renames or deletes the original file
before
-creating a new file of the same name, Unix-style soft and hard links will
-not be preserved.
-</p>
-<p>Finally, the <strong>-i</strong> switch does not impede execution when no
-files are given on the command line. In this case, no backup is made
-(the original file cannot, of course, be determined) and processing
-proceeds from STDIN to STDOUT as might be expected.
-</p>
-</dd>
-<dt><strong>-I</strong><em>directory</em></dt>
-<dd><a name="perlrun-_002dIdirectory"></a>
-<p>Directories specified by <strong>-I</strong> are prepended to the search
path for
-modules (<code>@INC</code>).
-</p>
-</dd>
-<dt><strong>-l</strong>[<em>octnum</em>]</dt>
-<dd><a name="perlrun-_002dl_005boctnum_005d"></a>
-<p>enables automatic line-ending processing. It has two separate
-effects. First, it automatically chomps <code>$/</code> (the input record
-separator) when used with <strong>-n</strong> or <strong>-p</strong>. Second,
it assigns <code>$\</code>
-(the output record separator) to have the value of <em>octnum</em> so
-that any print statements will have that separator added back on.
-If <em>octnum</em> is omitted, sets <code>$\</code> to the current value of
-<code>$/</code>. For instance, to trim lines to 80 columns:
-</p>
-<pre class="verbatim"> perl -lpe 'substr($_, 80) = ""'
-</pre>
-<p>Note that the assignment <code>$\ = $/</code> is done when the switch is
processed,
-so the input record separator can be different than the output record
-separator if the <strong>-l</strong> switch is followed by a
<strong>-0</strong> switch:
-</p>
-<pre class="verbatim"> gnufind / -print0 | perl -ln0e 'print "found
$_" if -p'
-</pre>
-<p>This sets <code>$\</code> to newline and then sets <code>$/</code> to the
null character.
-</p>
-</dd>
-<dt><strong>-m</strong>[<strong>-</strong>]<em>module</em></dt>
-<dd><a name="perlrun-_002dm_005b_002d_005dmodule"></a>
-</dd>
-<dt><strong>-M</strong>[<strong>-</strong>]<em>module</em></dt>
-<dd><a name="perlrun-_002dM_005b_002d_005dmodule"></a>
-</dd>
-<dt><strong>-M</strong>[<strong>-</strong>]<em>’module
...’</em></dt>
-<dd><a
name="perlrun-_002dM_005b_002d_005d_0027module-_002e_002e_002e_0027"></a>
-</dd>
-<dt><strong>-[mM]</strong>[<strong>-</strong>]<em>module=arg[,arg]...</em></dt>
-<dd><a
name="perlrun-_002d_005bmM_005d_005b_002d_005dmodule_003darg_005b_002carg_005d_002e_002e_002e"></a>
-<p><strong>-m</strong><em>module</em> executes <code>use</code>
<em>module</em> <code>();</code> before executing your
-program.
-</p>
-<p><strong>-M</strong><em>module</em> executes <code>use</code>
<em>module</em> <code>;</code> before executing your
-program. You can use quotes to add extra code after the module name,
-e.g., <code>'-M<em>MODULE</em> qw(foo bar)'</code>.
-</p>
-<p>If the first character after the <strong>-M</strong> or <strong>-m</strong>
is a dash (<strong>-</strong>)
-then the ’use’ is replaced with ’no’.
-</p>
-<p>A little builtin syntactic sugar means you can also say
-<strong>-m<em>MODULE</em>=foo,bar</strong> or
<strong>-M<em>MODULE</em>=foo,bar</strong> as a shortcut for
-<strong>’-M<em>MODULE</em> qw(foo bar)’</strong>. This avoids the
need to use quotes when
-importing symbols. The actual code generated by
<strong>-M<em>MODULE</em>=foo,bar</strong> is
-<code>use module split(/,/,q{foo,bar})</code>. Note that the <code>=</code>
form
-removes the distinction between <strong>-m</strong> and <strong>-M</strong>;
that is,
-<strong>-m<em>MODULE</em>=foo,bar</strong> is the same as
<strong>-M<em>MODULE</em>=foo,bar</strong>.
-</p>
-<p>A consequence of this is that <strong>-M<em>MODULE</em>=number</strong>
never does a version check,
-unless <code><em>MODULE</em>::import()</code> itself is set up to do a version
check, which
-could happen for example if <em>MODULE</em> inherits from <a
href="Exporter.html#Top">(Exporter)</a>.
-</p>
-</dd>
-<dt><strong>-n</strong></dt>
-<dd><a name="perlrun-_002dn"></a>
-<p>causes Perl to assume the following loop around your program, which
-makes it iterate over filename arguments somewhat like <em>sed -n</em> or
-<em>awk</em>:
-</p>
-<pre class="verbatim"> LINE:
- while (<>) {
- ... # your program goes here
- }
-</pre>
-<p>Note that the lines are not printed by default. See <a
href="#perlrun-_002dp">-p</a> to have
-lines printed. If a file named by an argument cannot be opened for
-some reason, Perl warns you about it and moves on to the next file.
-</p>
-<p>Also note that <code><></code> passes command line arguments to
-‘perlfunc open’, which doesn’t necessarily interpret them as
file names.
-See <a href="#perlop-NAME">perlop NAME</a> for possible security implications.
-</p>
-<p>Here is an efficient way to delete all files that haven’t been
modified for
-at least a week:
-</p>
-<pre class="verbatim"> find . -mtime +7 -print | perl -nle unlink
-</pre>
-<p>This is faster than using the <strong>-exec</strong> switch of
<em>find</em> 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 <strong>-0</strong>.
-</p>
-<p><code>BEGIN</code> and <code>END</code> blocks may be used to capture
control before or after
-the implicit program loop, just as in <em>awk</em>.
-</p>
-</dd>
-<dt><strong>-p</strong></dt>
-<dd><a name="perlrun-_002dp"></a>
-<p>causes Perl to assume the following loop around your program, which
-makes it iterate over filename arguments somewhat like <em>sed</em>:
-</p>
-<pre class="verbatim"> LINE:
- while (<>) {
- ... # your program goes here
- } continue {
- print or die "-p destination: $!\n";
- }
-</pre>
-<p>If a file named by an argument cannot be opened for some reason, Perl
-warns you about it, and moves on to the next file. Note that the
-lines are printed automatically. An error occurring during printing is
-treated as fatal. To suppress printing use the <strong>-n</strong> switch. A
<strong>-p</strong>
-overrides a <strong>-n</strong> switch.
-</p>
-<p><code>BEGIN</code> and <code>END</code> blocks may be used to capture
control before or after
-the implicit loop, just as in <em>awk</em>.
-</p>
-</dd>
-<dt><strong>-s</strong></dt>
-<dd><a name="perlrun-_002ds"></a>
-<p>enables rudimentary switch parsing for switches on the command
-line after the program name but before any filename arguments (or before
-an argument of <strong>–</strong>). Any switch found there is removed
from @ARGV and sets the
-corresponding variable in the Perl program. The following program
-prints "1" if the program is invoked with a <strong>-xyz</strong>
switch, and "abc"
-if it is invoked with <strong>-xyz=abc</strong>.
-</p>
-<pre class="verbatim"> #!/usr/bin/perl -s
- if ($xyz) { print "$xyz\n" }
-</pre>
-<p>Do note that a switch like <strong>–help</strong> creates the
variable <code>${-help}</code>, which is
-not compliant with <code>use strict "refs"</code>. Also, when using
this option on a
-script with warnings enabled you may get a lot of spurious "used only
once"
-warnings.
-</p>
-</dd>
-<dt><strong>-S</strong></dt>
-<dd><a name="perlrun-_002dS"></a>
-<p>makes Perl use the PATH environment variable to search for the
-program unless the name of the program contains path separators.
-</p>
-<p>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 <code>DEBUGGING</code>
turned
-on, using the <strong>-Dp</strong> switch to Perl shows how the search
progresses.
-</p>
-<p>Typically this is used to emulate <code>#!</code> startup on platforms that
don’t
-support <code>#!</code>. It’s also convenient when debugging a script
that uses <code>#!</code>,
-and is thus normally found by the shell’s $PATH search mechanism.
-</p>
-<p>This example works on many platforms that have a shell compatible with
-Bourne shell:
-</p>
-<pre class="verbatim"> #!/usr/bin/perl
- eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
- if $running_under_some_shell;
-</pre>
-<p>The system ignores the first line and feeds the program to
<samp>/bin/sh</samp>,
-which proceeds to try to execute the Perl program as a shell script.
-The shell executes the second line as a normal shell command, and thus
-starts up the Perl interpreter. On some systems $0 doesn’t always
-contain the full pathname, so the <strong>-S</strong> tells Perl to search for
the
-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 <code>${1+"$@"}</code> with <code>$*</code>, even though
that doesn’t understand
-embedded spaces (and such) in the argument list. To start up <em>sh</em>
rather
-than <em>csh</em>, some systems may have to replace the <code>#!</code> 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 <em>csh</em>, <em>sh</em>, or Perl, such as the
following:
-</p>
-<pre class="verbatim"> eval '(exit $?0)' && eval 'exec perl -wS
$0 ${1+"$@"}'
- & eval 'exec /usr/bin/perl -wS $0 $argv:q'
- if $running_under_some_shell;
-</pre>
-<p>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.
-</p>
-<p>On DOS-like platforms, if the program does not contain directory
-separators, it will first be searched for in the current directory
-before being searched for on the PATH. On Unix platforms, the
-program will be searched for strictly on the PATH.
-</p>
-</dd>
-<dt><strong>-t</strong></dt>
-<dd><a name="perlrun-_002dt"></a>
-<p>Like <strong>-T</strong>, but taint checks will issue warnings rather than
fatal
-errors. These warnings can now be controlled normally with <code>no warnings
-qw(taint)</code>.
-</p>
-<p><strong>Note: This is not a substitute for <code>-T</code>!</strong> This
is meant to be
-used <em>only</em> 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 <strong>-T</strong>.
-</p>
-</dd>
-<dt><strong>-T</strong></dt>
-<dd><a name="perlrun-_002dT"></a>
-<p>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
-<a href="#perlsec-NAME">perlsec NAME</a> 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 <code>#!</code> line for systems which support
-that construct.
-</p>
-</dd>
-<dt><strong>-u</strong></dt>
-<dd><a name="perlrun-_002du"></a>
-<p>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 <em>undump</em> 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 <em>undump</em> is platform
-specific and may not be available for a specific port of Perl.
-</p>
-</dd>
-<dt><strong>-U</strong></dt>
-<dd><a name="perlrun-_002dU"></a>
-<p>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 warnings must be enabled along with this option to actually
-<em>generate</em> the taint-check warnings.
-</p>
-</dd>
-<dt><strong>-v</strong></dt>
-<dd><a name="perlrun-_002dv"></a>
-<p>prints the version and patchlevel of your perl executable.
-</p>
-</dd>
-<dt><strong>-V</strong></dt>
-<dd><a name="perlrun-_002dV"></a>
-<p>prints summary of the major perl configuration values and the current
-values of @INC.
-</p>
-</dd>
-<dt><strong>-V:</strong><em>configvar</em></dt>
-<dd><a name="perlrun-_002dV_003aconfigvar"></a>
-<p>Prints to STDOUT the value of the named configuration variable(s),
-with multiples when your <code><em>configvar</em></code> argument looks like a
regex (has
-non-letters). For example:
-</p>
-<pre class="verbatim"> $ perl -V:libc
- libc='/lib/libc-2.2.4.so';
- $ perl -V:lib.
- libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
- libc='/lib/libc-2.2.4.so';
- $ perl -V:lib.*
- libpth='/usr/local/lib /lib /usr/lib';
- libs='-lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lc';
- lib_ext='.a';
- libc='/lib/libc-2.2.4.so';
- libperl='libperl.a';
- ....
-</pre>
-<p>Additionally, extra colons can be used to control formatting. A
-trailing colon suppresses the linefeed and terminator ";", allowing
-you to embed queries into shell commands. (mnemonic: PATH separator
-":".)
-</p>
-<pre class="verbatim"> $ echo "compression-vars: " `perl -V:z.*:
` " are here !"
- compression-vars: zcat='' zip='zip' are here !
-</pre>
-<p>A leading colon removes the "name=" part of the response, this
allows
-you to map to the name you need. (mnemonic: empty label)
-</p>
-<pre class="verbatim"> $ echo "goodvfork="`./perl -Ilib
-V::usevfork`
- goodvfork=false;
-</pre>
-<p>Leading and trailing colons can be used together if you need
-positional parameter values without the names. Note that in the case
-below, the <code>PERL_API</code> params are returned in alphabetical order.
-</p>
-<pre class="verbatim"> $ echo building_on `perl -V::osname:
-V::PERL_API_.*:` now
- building_on 'linux' '5' '1' '9' now
-</pre>
-</dd>
-<dt><strong>-w</strong></dt>
-<dd><a name="perlrun-_002dw"></a>
-<p>prints warnings about dubious constructs, such as variable names
-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 <em>look</em> like
numbers;
-using an array as though it were a scalar; if your subroutines
-recurse more than 100 deep; and innumerable other things.
-</p>
-<p>This switch really just enables the global <code>$^W</code> variable;
normally,
-the lexically scoped <code>use warnings</code> pragma is preferred. You
-can disable or promote into fatal errors specific warnings using
-<code>__WARN__</code> hooks, as described in <a href="#perlvar-NAME">perlvar
NAME</a> and ‘perlfunc warn’.
-See also <a href="#perldiag-NAME">perldiag NAME</a> and <a
href="#perltrap-NAME">perltrap NAME</a>. A fine-grained warning
-facility is also available if you want to manipulate entire classes
-of warnings; see <a href="warnings.html#Top">(warnings)</a>.
-</p>
-</dd>
-<dt><strong>-W</strong></dt>
-<dd><a name="perlrun-_002dW"></a>
-<p>Enables all warnings regardless of <code>no warnings</code> or
<code>$^W</code>.
-See <a href="warnings.html#Top">(warnings)</a>.
-</p>
-</dd>
-<dt><strong>-X</strong></dt>
-<dd><a name="perlrun-_002dX"></a>
-<p>Disables all warnings regardless of <code>use warnings</code> or
<code>$^W</code>.
-See <a href="warnings.html#Top">(warnings)</a>.
-</p>
-</dd>
-<dt><strong>-x</strong></dt>
-<dd><a name="perlrun-_002dx"></a>
-</dd>
-<dt><strong>-x</strong><em>directory</em></dt>
-<dd><a name="perlrun-_002dxdirectory"></a>
-<p>tells Perl that the program is embedded in a larger chunk of unrelated
-text, such as in a mail message. Leading garbage will be
-discarded until the first line that starts with <code>#!</code> and contains
the
-string "perl". Any meaningful switches on that line will be applied.
-</p>
-<p>All references to line numbers by the program (warnings, errors, ...)
-will treat the <code>#!</code> 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 <code>#line</code> directive.
-(See <a href="#perlsyn-Plain-Old-Comments-_0028Not_0021_0029">perlsyn Plain
Old Comments (Not!)</a>)
-</p>
-<p>If a directory name is specified, Perl will switch to that directory
-before running the program. The <strong>-x</strong> switch controls only the
-disposal of leading garbage. The program must be terminated with
-<code>__END__</code> if there is trailing garbage to be ignored; the program
-can process any or all of the trailing garbage via the <code>DATA</code>
filehandle
-if desired.
-</p>
-<p>The directory, if specified, must appear immediately following the
<strong>-x</strong>
-with no intervening whitespace.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlrun-ENVIRONMENT"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlrun-DESCRIPTION" accesskey="p" rel="prev">perlrun
DESCRIPTION</a>, Up: <a href="#perlrun" accesskey="u" rel="up">perlrun</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="ENVIRONMENT-2"></a>
-<h3 class="section">69.4 ENVIRONMENT</h3>
-
-<dl compact="compact">
-<dt>HOME</dt>
-<dd><a name="perlrun-HOME"></a>
-<p>Used if <code>chdir</code> has no argument.
-</p>
-</dd>
-<dt>LOGDIR</dt>
-<dd><a name="perlrun-LOGDIR"></a>
-<p>Used if <code>chdir</code> has no argument and HOME is not set.
-</p>
-</dd>
-<dt>PATH</dt>
-<dd><a name="perlrun-PATH"></a>
-<p>Used in executing subprocesses, and in finding the program if
<strong>-S</strong> is
-used.
-</p>
-</dd>
-<dt>PERL5LIB</dt>
-<dd><a name="perlrun-PERL5LIB"></a>
-<p>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 and version-specific directories,
-such as <samp>version/archname/</samp>, <samp>version/</samp>, or
<samp>archname/</samp> under the
-specified locations are automatically included if they exist, with this
-lookup done at interpreter startup time. In addition, any directories
-matching the entries in <code>$Config{inc_version_list}</code> are added.
-(These typically would be for older compatible perl versions installed
-in the same directory tree.)
-</p>
-<p>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 <code>perl
--V:<em>path_sep</em></code>).
-</p>
-<p>When running taint checks, either because the program was running setuid or
-setgid, or the <strong>-T</strong> or <strong>-t</strong> switch was
specified, neither PERL5LIB nor
-PERLLIB is consulted. The program should instead say:
-</p>
-<pre class="verbatim"> use lib "/my/directory";
-</pre>
-</dd>
-<dt>PERL5OPT</dt>
-<dd><a name="perlrun-PERL5OPT"></a>
-<p>Command-line options (switches). Switches in this variable are treated
-as if they were on every Perl command line. Only the
<strong>-[CDIMUdmtwW]</strong>
-switches are allowed. When running taint checks (either because the
-program was running setuid or setgid, or because the <strong>-T</strong> or
<strong>-t</strong>
-switch was used), this variable is ignored. If PERL5OPT begins with
-<strong>-T</strong>, tainting will be enabled and subsequent options ignored.
If
-PERL5OPT begins with <strong>-t</strong>, tainting will be enabled, a writable
dot
-removed from @INC, and subsequent options honored.
-</p>
-</dd>
-<dt>PERLIO</dt>
-<dd><a name="perlrun-PERLIO"></a>
-<p>A space (or colon) separated list of PerlIO layers. If perl is built
-to use PerlIO system for IO (the default) these layers affect Perl’s IO.
-</p>
-<p>It is conventional to start layer names with a colon (for example,
<code>:perlio</code>) 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.
-</p>
-<p>An unset or empty PERLIO is equivalent to the default set of layers for
-your platform; for example, <code>:unix:perlio</code> on Unix-like systems
-and <code>:unix:crlf</code> on Windows and other DOS-like systems.
-</p>
-<p>The list becomes the default for <em>all</em> Perl’s IO. Consequently
only built-in
-layers can appear in this list, as external layers (such as
<code>:encoding()</code>) need
-IO in order to load them! See <a href="open.html#Top">(open)"open
pragma"</a> for how to add external
-encodings as defaults.
-</p>
-<p>Layers it makes sense to include in the PERLIO environment
-variable are briefly summarized below. For more details see <a
href="PerlIO.html#Top">(PerlIO)</a>.
-</p>
-<dl compact="compact">
-<dt>:bytes</dt>
-<dd><a name="perlrun-_003abytes"></a>
-<p>A pseudolayer that turns the <code>:utf8</code> flag <em>off</em> for the
layer below;
-unlikely to be useful on its own in the global PERLIO environment variable.
-You perhaps were thinking of <code>:crlf:bytes</code> or
<code>:perlio:bytes</code>.
-</p>
-</dd>
-<dt>:crlf</dt>
-<dd><a name="perlrun-_003acrlf"></a>
-<p>A layer which does CRLF to <code>"\n"</code> translation
distinguishing "text" and
-"binary" files in the manner of MS-DOS and similar operating systems.
-(It currently does <em>not</em> mimic MS-DOS as far as treating of Control-Z
-as being an end-of-file marker.)
-</p>
-</dd>
-<dt>:mmap</dt>
-<dd><a name="perlrun-_003ammap"></a>
-<p>A layer that implements "reading" of files by using
<em>mmap</em>(2) to
-make an entire file appear in the process’s address space, and then
-using that as PerlIO’s "buffer".
-</p>
-</dd>
-<dt>:perlio</dt>
-<dd><a name="perlrun-_003aperlio"></a>
-<p>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 <code>:unix</code>.
-</p>
-</dd>
-<dt>:pop</dt>
-<dd><a name="perlrun-_003apop"></a>
-<p>An experimental pseudolayer that removes the topmost layer.
-Use with the same care as is reserved for nitroglycerine.
-</p>
-</dd>
-<dt>:raw</dt>
-<dd><a name="perlrun-_003araw"></a>
-<p>A pseudolayer that manipulates other layers. Applying the <code>:raw</code>
-layer is equivalent to calling <code>binmode($fh)</code>. It makes the stream
-pass each byte as-is without translation. In particular, both CRLF
-translation and intuiting <code>:utf8</code> from the locale are disabled.
-</p>
-<p>Unlike in earlier versions of Perl, <code>:raw</code> is <em>not</em>
-just the inverse of <code>:crlf</code>: other layers which would affect the
-binary nature of the stream are also removed or disabled.
-</p>
-</dd>
-<dt>:stdio</dt>
-<dd><a name="perlrun-_003astdio"></a>
-<p>This layer provides a PerlIO interface by wrapping system’s ANSI C
"stdio"
-library calls. The layer provides both buffering and IO.
-Note that the <code>:stdio</code> layer does <em>not</em> do CRLF translation
even if that
-is the platform’s normal behaviour. You will need a <code>:crlf</code>
layer above it
-to do that.
-</p>
-</dd>
-<dt>:unix</dt>
-<dd><a name="perlrun-_003aunix"></a>
-<p>Low-level layer that calls <code>read</code>, <code>write</code>,
<code>lseek</code>, etc.
-</p>
-</dd>
-<dt>:utf8</dt>
-<dd><a name="perlrun-_003autf8"></a>
-<p>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. <strong>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.</strong> Generally
<code>:encoding(utf8)</code> is
-the best option when reading UTF-8 encoded data.
-</p>
-</dd>
-<dt>:win32</dt>
-<dd><a name="perlrun-_003awin32"></a>
-<p>On Win32 platforms this <em>experimental</em> layer uses native
"handle" IO
-rather than a Unix-like numeric file descriptor layer. Known to be
-buggy in this release (5.14).
-</p>
-</dd>
-</dl>
-
-<p>The default set of layers should give acceptable results on all platforms
-</p>
-<p>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.
-</p>
-<p>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 <code>crlf</code>
layer as
-the buffer avoids those issues and makes things more uniform. The
<code>crlf</code>
-layer provides CRLF conversion as well as buffering.
-</p>
-<p>This release (5.14) uses <code>unix</code> as the bottom layer on Win32,
and so still
-uses the C compiler’s numeric file descriptor routines. There is an
-experimental native <code>win32</code> layer, which is expected to be enhanced
and
-should eventually become the default under Win32.
-</p>
-<p>The PERLIO environment variable is completely ignored when Perl
-is run in taint mode.
-</p>
-</dd>
-<dt>PERLIO_DEBUG</dt>
-<dd><a name="perlrun-PERLIO_005fDEBUG"></a>
-<p>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:
-</p>
-<pre class="verbatim"> % env PERLIO_DEBUG=/dev/tty perl script ...
-</pre>
-<p>and under Win32, the approximately equivalent:
-</p>
-<pre class="verbatim"> > set PERLIO_DEBUG=CON
- perl script ...
-</pre>
-<p>This functionality is disabled for setuid scripts and for scripts run
-with <strong>-T</strong>.
-</p>
-</dd>
-<dt>PERLLIB</dt>
-<dd><a name="perlrun-PERLLIB"></a>
-<p>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.
-</p>
-<p>The PERLLIB environment variable is completely ignored when Perl
-is run in taint mode.
-</p>
-</dd>
-<dt>PERL5DB</dt>
-<dd><a name="perlrun-PERL5DB"></a>
-<p>The command used to load the debugger code. The default is:
-</p>
-<pre class="verbatim"> BEGIN { require "perl5db.pl" }
-</pre>
-<p>The PERL5DB environment variable is only used when Perl is started with
-a bare <strong>-d</strong> switch.
-</p>
-</dd>
-<dt>PERL5DB_THREADED</dt>
-<dd><a name="perlrun-PERL5DB_005fTHREADED"></a>
-<p>If set to a true value, indicates to the debugger that the code being
-debugged uses threads.
-</p>
-</dd>
-<dt>PERL5SHELL (specific to the Win32 port)</dt>
-<dd><a name="perlrun-PERL5SHELL-_0028specific-to-the-Win32-port_0029"></a>
-<p>On Win32 ports only, may be set to an alternative shell that Perl must use
-internally for executing "backtick" commands or system(). Default is
-<code>cmd.exe /x/d/c</code> on WindowsNT and <code>command.com /c</code> on
Windows95. The
-value is considered space-separated. Precede any character that
-needs to be protected, like a space or backslash, with another backslash.
-</p>
-<p>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
-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).
-</p>
-<p>Before Perl 5.10.0 and 5.8.8, PERL5SHELL was not taint checked
-when running external commands. It is recommended that
-you explicitly set (or delete) <code>$ENV{PERL5SHELL}</code> when running
-in taint mode under Windows.
-</p>
-</dd>
-<dt>PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)</dt>
-<dd><a
name="perlrun-PERL_005fALLOW_005fNON_005fIFS_005fLSP-_0028specific-to-the-Win32-port_0029"></a>
-<p>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 <em>McAfee Guardian</em>, which
requires
-that all applications use its LSP but which is not IFS-compatible, because
clearly
-Perl will normally avoid using such an LSP.
-</p>
-<p>Setting this environment variable to 1 means that Perl will simply use the
-first suitable LSP enumerated in the catalog, which keeps <em>McAfee
Guardian</em>
-happy–and in that particular case Perl still works too because <em>McAfee
-Guardian</em>’s LSP actually plays other games which allow applications
-requiring IFS compatibility to work.
-</p>
-</dd>
-<dt>PERL_DEBUG_MSTATS</dt>
-<dd><a name="perlrun-PERL_005fDEBUG_005fMSTATS"></a>
-<p>Relevant only if Perl is compiled with the <code>malloc</code> included
with the Perl
-distribution; that is, if <code>perl -V:d_mymalloc</code> is
"define".
-</p>
-<p>If set, this dumps out memory statistics after execution. If set
-to an integer greater than one, also dumps out memory statistics
-after compilation.
-</p>
-</dd>
-<dt>PERL_DESTRUCT_LEVEL</dt>
-<dd><a name="perlrun-PERL_005fDESTRUCT_005fLEVEL"></a>
-<p>Relevant only if your Perl executable was built with
<strong>-DDEBUGGING</strong>,
-this controls the behaviour of global destruction of objects and other
-references. See <a
href="#perlhacktips-PERL_005fDESTRUCT_005fLEVEL">perlhacktips
PERL_DESTRUCT_LEVEL</a> for more information.
-</p>
-</dd>
-<dt>PERL_DL_NONLAZY</dt>
-<dd><a name="perlrun-PERL_005fDL_005fNONLAZY"></a>
-<p>Set to <code>"1"</code> to have Perl resolve <em>all</em>
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 them.
-</p>
-</dd>
-<dt>PERL_ENCODING</dt>
-<dd><a name="perlrun-PERL_005fENCODING"></a>
-<p>If using the <code>use encoding</code> pragma without an explicit encoding
name, the
-PERL_ENCODING environment variable is consulted for an encoding name.
-</p>
-</dd>
-<dt>PERL_HASH_SEED</dt>
-<dd><a name="perlrun-PERL_005fHASH_005fSEED"></a>
-<p>(Since Perl 5.8.1, new semantics in Perl 5.18.0) Used to override
-the randomization of Perl’s internal hash function. The value is
expressed
-in hexadecimal, and may include a leading 0x. Truncated patterns
-are treated as though they are suffixed with sufficient 0’s as required.
-</p>
-<p>If the option is provided, and <code>PERL_PERTURB_KEYS</code> is NOT set,
then
-a value of ’0’ implies <code>PERL_PERTURB_KEYS=0</code> and any
other value
-implies <code>PERL_PERTURB_KEYS=2</code>.
-</p>
-<p><strong>PLEASE NOTE: The hash seed is sensitive information</strong>.
Hashes are
-randomized to protect against local and remote attacks against Perl
-code. By manually setting a seed, this protection may be partially or
-completely lost.
-</p>
-<p>See <a href="#perlsec-Algorithmic-Complexity-Attacks">perlsec Algorithmic
Complexity Attacks</a>, <a
href="#perlrun-PERL_005fPERTURB_005fKEYS">PERL_PERTURB_KEYS</a>, and
-<a href="#perlrun-PERL_005fHASH_005fSEED_005fDEBUG">PERL_HASH_SEED_DEBUG</a>
for more information.
-</p>
-</dd>
-<dt>PERL_PERTURB_KEYS</dt>
-<dd><a name="perlrun-PERL_005fPERTURB_005fKEYS"></a>
-<p>(Since Perl 5.18.0) Set to <code>"0"</code> or
<code>"NO"</code> then traversing keys
-will be repeatable from run to run for the same PERL_HASH_SEED.
-Insertion into a hash will not change the order, except to provide
-for more space in the hash. When combined with setting PERL_HASH_SEED
-this mode is as close to pre 5.18 behavior as you can get.
-</p>
-<p>When set to <code>"1"</code> or <code>"RANDOM"</code>
then traversing keys will be randomized.
-Every time a hash is inserted into the key order will change in a random
-fashion. The order may not be repeatable in a following program run
-even if the PERL_HASH_SEED has been specified. This is the default
-mode for perl.
-</p>
-<p>When set to <code>"2"</code> or
<code>"DETERMINISTIC"</code> then inserting keys into a hash
-will cause the key order to change, but in a way that is repeatable
-from program run to program run.
-</p>
-<p><strong>NOTE:</strong> Use of this option is considered insecure, and is
intended only
-for debugging non-deterministic behavior in Perl’s hash function. Do
-not use it in production.
-</p>
-<p>See <a href="#perlsec-Algorithmic-Complexity-Attacks">perlsec Algorithmic
Complexity Attacks</a> and <a
href="#perlrun-PERL_005fHASH_005fSEED">PERL_HASH_SEED</a>
-and <a
href="#perlrun-PERL_005fHASH_005fSEED_005fDEBUG">PERL_HASH_SEED_DEBUG</a> for
more information. You can get and set the
-key traversal mask for a specific hash by using the
<code>hash_traversal_mask()</code>
-function from <a href="Hash-Util.html#Top">(Hash-Util)</a>.
-</p>
-</dd>
-<dt>PERL_HASH_SEED_DEBUG</dt>
-<dd><a name="perlrun-PERL_005fHASH_005fSEED_005fDEBUG"></a>
-<p>(Since Perl 5.8.1.) Set to <code>"1"</code> to display (to
STDERR) information
-about the hash function, seed, and what type of key traversal
-randomization is in effect at the beginning of execution. This, combined
-with <a href="#perlrun-PERL_005fHASH_005fSEED">PERL_HASH_SEED</a> and <a
href="#perlrun-PERL_005fPERTURB_005fKEYS">PERL_PERTURB_KEYS</a> is intended to
aid in
-debugging nondeterministic behaviour caused by hash randomization.
-</p>
-<p><strong>Note</strong> that any information about the hash function,
especially the hash
-seed is <strong>sensitive information</strong>: by knowing it, one can craft a
denial-of-service
-attack against Perl code, even remotely; see <a
href="#perlsec-Algorithmic-Complexity-Attacks">perlsec Algorithmic Complexity
Attacks</a>
-for more information. <strong>Do not disclose the hash seed</strong> to people
who
-don’t need to know it. See also <code>hash_seed()</code> and
-<code>key_traversal_mask()</code> in <a
href="Hash-Util.html#Top">(Hash-Util)</a>.
-</p>
-<p>An example output might be:
-</p>
-<pre class="verbatim"> HASH_FUNCTION = ONE_AT_A_TIME_HARD HASH_SEED =
0x652e9b9349a7a032 PERTURB_KEYS = 1 (RANDOM)
-</pre>
-</dd>
-<dt>PERL_MEM_LOG</dt>
-<dd><a name="perlrun-PERL_005fMEM_005fLOG"></a>
-<p>If your Perl was configured with <strong>-Accflags=-DPERL_MEM_LOG</strong>,
setting
-the environment variable <code>PERL_MEM_LOG</code> enables logging debug
-messages. The value has the form
<code><<em>number</em>>[m][s][t]</code>, where
-<code><em>number</em></code> 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, <code>PERL_MEM_LOG=1mst</code> logs all
-information to stdout. You can write to other opened file descriptors
-in a variety of ways:
-</p>
-<pre class="verbatim"> $ 3>foo3 PERL_MEM_LOG=3m perl ...
-</pre>
-</dd>
-<dt>PERL_ROOT (specific to the VMS port)</dt>
-<dd><a name="perlrun-PERL_005fROOT-_0028specific-to-the-VMS-port_0029"></a>
-<p>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
-<a href="#perlvms-NAME">perlvms NAME</a> and in <samp>README.vms</samp> in the
Perl source distribution.
-</p>
-</dd>
-<dt>PERL_SIGNALS</dt>
-<dd><a name="perlrun-PERL_005fSIGNALS"></a>
-<p>Available in Perls 5.8.1 and later. If set to
<code>"unsafe"</code>, the pre-Perl-5.8.0
-signal behaviour (which is immediate but unsafe) is restored. If set
-to <code>safe</code>, then safe (but deferred) signals are used. See
-<a href="#perlipc-Deferred-Signals-_0028Safe-Signals_0029">perlipc Deferred
Signals (Safe Signals)</a>.
-</p>
-</dd>
-<dt>PERL_UNICODE</dt>
-<dd><a name="perlrun-PERL_005fUNICODE"></a>
-<p>Equivalent to the <strong>-C</strong> command-line switch. Note that this
is not
-a boolean variable. Setting this to <code>"1"</code> is not the
right way to
-"enable Unicode" (whatever that would mean). You can use
<code>"0"</code> to
-"disable Unicode", though (or alternatively unset PERL_UNICODE in
-your shell before starting Perl). See the description of the
<strong>-C</strong>
-switch for more information.
-</p>
-</dd>
-<dt>SYS$LOGIN (specific to the VMS port)</dt>
-<dd><a name="perlrun-SYS_0024LOGIN-_0028specific-to-the-VMS-port_0029"></a>
-<p>Used if chdir has no argument and HOME and LOGDIR are not set.
-</p>
-</dd>
-</dl>
-
-<p>Perl also has environment variables that control how Perl handles data
-specific to particular natural languages; see <a
href="#perllocale-NAME">perllocale NAME</a>.
-</p>
-<p>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 <a href="perlsolaris.html#Top">(perlsolaris)</a>, <a
href="perllinux.html#Top">(perllinux)</a>, <a
href="perlmacosx.html#Top">(perlmacosx)</a>, <a
href="perlwin32.html#Top">(perlwin32)</a>, etc) for
-variables peculiar to those specific situations.
-</p>
-<p>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:
-</p>
-<pre class="verbatim"> $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)};
-</pre>
-<hr>
-<a name="perlsec"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsource" accesskey="n" rel="next">perlsource</a>, Previous:
<a href="#perlrun" accesskey="p" rel="prev">perlrun</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlsec-1"></a>
-<h2 class="chapter">70 perlsec</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlsec-NAME"
accesskey="1">perlsec NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsec-DESCRIPTION"
accesskey="2">perlsec DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-SECURITY-VULNERABILITY-CONTACT-INFORMATION"
accesskey="3">perlsec SECURITY VULNERABILITY CONTACT
INFORMATION</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-SECURITY-MECHANISMS-AND-CONCERNS" accesskey="4">perlsec SECURITY
MECHANISMS AND CONCERNS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsec-SEE-ALSO"
accesskey="5">perlsec SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlsec-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsec-DESCRIPTION" accesskey="n" rel="next">perlsec
DESCRIPTION</a>, Up: <a href="#perlsec" accesskey="u" rel="up">perlsec</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-69"></a>
-<h3 class="section">70.1 NAME</h3>
-
-<p>perlsec - Perl security
-</p>
-<hr>
-<a name="perlsec-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsec-SECURITY-VULNERABILITY-CONTACT-INFORMATION"
accesskey="n" rel="next">perlsec SECURITY VULNERABILITY CONTACT
INFORMATION</a>, Previous: <a href="#perlsec-NAME" accesskey="p"
rel="prev">perlsec NAME</a>, Up: <a href="#perlsec" accesskey="u"
rel="up">perlsec</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-68"></a>
-<h3 class="section">70.2 DESCRIPTION</h3>
-
-<p>Perl is designed to make it easy to program securely even when running
-with extra privileges, like setuid or setgid programs. Unlike most
-command line shells, which are based on multiple substitution passes on
-each line of the script, Perl uses a more conventional evaluation scheme
-with fewer hidden snags. Additionally, because the language has more
-builtin functionality, it can rely less upon external (and possibly
-untrustworthy) programs to accomplish its purposes.
-</p>
-<hr>
-<a name="perlsec-SECURITY-VULNERABILITY-CONTACT-INFORMATION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsec-SECURITY-MECHANISMS-AND-CONCERNS" accesskey="n"
rel="next">perlsec SECURITY MECHANISMS AND CONCERNS</a>, Previous: <a
href="#perlsec-DESCRIPTION" accesskey="p" rel="prev">perlsec DESCRIPTION</a>,
Up: <a href="#perlsec" accesskey="u" rel="up">perlsec</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SECURITY-VULNERABILITY-CONTACT-INFORMATION"></a>
-<h3 class="section">70.3 SECURITY VULNERABILITY CONTACT INFORMATION</h3>
-
-<p>If you believe you have found a security vulnerability in Perl, please email
address@hidden with details. This points to a closed
-subscription, unarchived mailing list. Please only use this address for
-security issues in the Perl core, not for modules independently distributed on
-CPAN.
-</p>
-<hr>
-<a name="perlsec-SECURITY-MECHANISMS-AND-CONCERNS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsec-SEE-ALSO" accesskey="n" rel="next">perlsec SEE
ALSO</a>, Previous: <a
href="#perlsec-SECURITY-VULNERABILITY-CONTACT-INFORMATION" accesskey="p"
rel="prev">perlsec SECURITY VULNERABILITY CONTACT INFORMATION</a>, Up: <a
href="#perlsec" accesskey="u" rel="up">perlsec</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SECURITY-MECHANISMS-AND-CONCERNS"></a>
-<h3 class="section">70.4 SECURITY MECHANISMS AND CONCERNS</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlsec-Taint-mode"
accesskey="1">perlsec Taint mode</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-Laundering-and-Detecting-Tainted-Data" accesskey="2">perlsec
Laundering and Detecting Tainted Data</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-Switches-On-the-_0022_0023_0021_0022-Line" accesskey="3">perlsec
Switches On the "#!" Line</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-Taint-mode-and-_0040INC" accesskey="4">perlsec Taint mode and
@INC</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-Cleaning-Up-Your-Path" accesskey="5">perlsec Cleaning Up Your
Path</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsec-Security-Bugs"
accesskey="6">perlsec Security Bugs</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-Protecting-Your-Programs" accesskey="7">perlsec Protecting Your
Programs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsec-Unicode"
accesskey="8">perlsec Unicode</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsec-Algorithmic-Complexity-Attacks" accesskey="9">perlsec
Algorithmic Complexity Attacks</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlsec-Taint-mode"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsec-Laundering-and-Detecting-Tainted-Data" accesskey="n"
rel="next">perlsec Laundering and Detecting Tainted Data</a>, Up: <a
href="#perlsec-SECURITY-MECHANISMS-AND-CONCERNS" accesskey="u" rel="up">perlsec
SECURITY MECHANISMS AND CONCERNS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Taint-mode"></a>
-<h4 class="subsection">70.4.1 Taint mode</h4>
-
-<p>Perl automatically enables a set of special security checks, called
<em>taint
-mode</em>, when it detects its program running with differing real and
effective
-user or group IDs. The setuid bit in Unix permissions is mode 04000, the
-setgid bit mode 02000; either or both may be set. You can also enable taint
-mode explicitly by using the <strong>-T</strong> command line flag. This flag
is
-<em>strongly</em> suggested for server programs and any program run on behalf
of
-someone else, such as a CGI script. Once taint mode is on, it’s on for
-the remainder of your script.
-</p>
-<p>While in this mode, Perl takes special precautions called <em>taint
-checks</em> to prevent both obvious and subtle traps. Some of these checks
-are reasonably simple, such as verifying that path directories aren’t
-writable by others; careful programmers have always used checks like
-these. Other checks, however, are best supported by the language itself,
-and it is these checks especially that contribute to making a set-id Perl
-program more secure than the corresponding C program.
-</p>
-<p>You may not use data derived from outside your program to affect
-something else outside your program–at least, not by accident. All
-command line arguments, environment variables, locale information (see
-<a href="#perllocale-NAME">perllocale NAME</a>), results of certain system
calls (<code>readdir()</code>,
-<code>readlink()</code>, the variable of <code>shmread()</code>, the messages
returned by
-<code>msgrcv()</code>, the password, gcos and shell fields returned by the
-<code>getpwxxx()</code> calls), and all file input are marked as
"tainted".
-Tainted data may not be used directly or indirectly in any command
-that invokes a sub-shell, nor in any command that modifies files,
-directories, or processes, <strong>with the following exceptions</strong>:
-</p>
-<ul>
-<li> Arguments to <code>print</code> and <code>syswrite</code> are
<strong>not</strong> checked for taintedness.
-
-</li><li> Symbolic methods
-
-<pre class="verbatim"> $obj->$method(@args);
-</pre>
-<p>and symbolic sub references
-</p>
-<pre class="verbatim"> &{$foo}(@args);
- $foo->(@args);
-</pre>
-<p>are not checked for taintedness. This requires extra carefulness
-unless you want external data to affect your control flow. Unless
-you carefully limit what these symbolic values are, people are able
-to call functions <strong>outside</strong> your Perl code, such as
POSIX::system,
-in which case they are able to run arbitrary external code.
-</p>
-</li><li> Hash keys are <strong>never</strong> tainted.
-
-</li></ul>
-
-<p>For efficiency reasons, Perl takes a conservative view of
-whether data is tainted. If an expression contains tainted data,
-any subexpression may be considered tainted, even if the value
-of the subexpression is not itself affected by the tainted data.
-</p>
-<p>Because taintedness is associated with each scalar value, some
-elements of an array or hash can be tainted and others not.
-The keys of a hash are <strong>never</strong> tainted.
-</p>
-<p>For example:
-</p>
-<pre class="verbatim"> $arg = shift; # $arg is tainted
- $hid = $arg . 'bar'; # $hid is also tainted
- $line = <>; # Tainted
- $line = <STDIN>; # Also tainted
- open FOO, "/home/me/bar" or die $!;
- $line = <FOO>; # Still tainted
- $path = $ENV{'PATH'}; # Tainted, but see below
- $data = 'abc'; # Not tainted
-
- system "echo $arg"; # Insecure
- system "/bin/echo", $arg; # Considered insecure
- # (Perl doesn't know about /bin/echo)
- system "echo $hid"; # Insecure
- system "echo $data"; # Insecure until PATH set
-
- $path = $ENV{'PATH'}; # $path now tainted
-
- $ENV{'PATH'} = '/bin:/usr/bin';
- delete @ENV{'IFS', 'CDPATH', 'ENV', 'BASH_ENV'};
-
- $path = $ENV{'PATH'}; # $path now NOT tainted
- system "echo $data"; # Is secure now!
-
- open(FOO, "< $arg"); # OK - read-only file
- open(FOO, "> $arg"); # Not OK - trying to write
-
- open(FOO,"echo $arg|"); # Not OK
- open(FOO,"-|")
- or exec 'echo', $arg; # Also not OK
-
- $shout = `echo $arg`; # Insecure, $shout now tainted
-
- unlink $data, $arg; # Insecure
- umask $arg; # Insecure
-
- exec "echo $arg"; # Insecure
- exec "echo", $arg; # Insecure
- exec "sh", '-c', $arg; # Very insecure!
-
- @files = <*.c>; # insecure (uses readdir() or similar)
- @files = glob('*.c'); # insecure (uses readdir() or similar)
-
- # In either case, the results of glob are tainted, since the list of
- # filenames comes from outside of the program.
-
- $bad = ($arg, 23); # $bad will be tainted
- $arg, `true`; # Insecure (although it isn't really)
-</pre>
-<p>If you try to do something insecure, you will get a fatal error saying
-something like "Insecure dependency" or "Insecure
$ENV{PATH}".
-</p>
-<p>The exception to the principle of "one tainted value taints the whole
-expression" is with the ternary conditional operator <code>?:</code>.
Since code
-with a ternary conditional
-</p>
-<pre class="verbatim"> $result = $tainted_value ? "Untainted" :
"Also untainted";
-</pre>
-<p>is effectively
-</p>
-<pre class="verbatim"> if ( $tainted_value ) {
- $result = "Untainted";
- } else {
- $result = "Also untainted";
- }
-</pre>
-<p>it doesn’t make sense for <code>$result</code> to be tainted.
-</p>
-<hr>
-<a name="perlsec-Laundering-and-Detecting-Tainted-Data"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsec-Switches-On-the-_0022_0023_0021_0022-Line"
accesskey="n" rel="next">perlsec Switches On the "#!" Line</a>,
Previous: <a href="#perlsec-Taint-mode" accesskey="p" rel="prev">perlsec Taint
mode</a>, Up: <a href="#perlsec-SECURITY-MECHANISMS-AND-CONCERNS" accesskey="u"
rel="up">perlsec SECURITY MECHANISMS AND CONCERNS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Laundering-and-Detecting-Tainted-Data"></a>
-<h4 class="subsection">70.4.2 Laundering and Detecting Tainted Data</h4>
-
-<p>To test whether a variable contains tainted data, and whose use would
-thus trigger an "Insecure dependency" message, you can use the
-<code>tainted()</code> function of the Scalar::Util module, available in your
-nearby CPAN mirror, and included in Perl starting from the release 5.8.0.
-Or you may be able to use the following <code>is_tainted()</code> function.
-</p>
-<pre class="verbatim"> sub is_tainted {
- local $@; # Don't pollute caller's value.
- return ! eval { eval("#" . substr(join("", @_), 0,
0)); 1 };
- }
-</pre>
-<p>This function makes use of the fact that the presence of tainted data
-anywhere within an expression renders the entire expression tainted. It
-would be inefficient for every operator to test every argument for
-taintedness. Instead, the slightly more efficient and conservative
-approach is used that if any tainted value has been accessed within the
-same expression, the whole expression is considered tainted.
-</p>
-<p>But testing for taintedness gets you only so far. Sometimes you have just
-to clear your data’s taintedness. Values may be untainted by using them
-as keys in a hash; otherwise the only way to bypass the tainting
-mechanism is by referencing subpatterns from a regular expression match.
-Perl presumes that if you reference a substring using $1, $2, etc. in a
-non-tainting pattern, that
-you knew what you were doing when you wrote that pattern. That means using
-a bit of thought–don’t just blindly untaint anything, or you
defeat the
-entire mechanism. It’s better to verify that the variable has only good
-characters (for certain values of "good") rather than checking
whether it
-has any bad characters. That’s because it’s far too easy to miss
bad
-characters that you never thought of.
-</p>
-<p>Here’s a test to make sure that the data contains nothing but
"word"
-characters (alphabetics, numerics, and underscores), a hyphen, an at sign,
-or a dot.
-</p>
-<pre class="verbatim"> if ($data =~ /^(address@hidden)$/) {
- $data = $1; # $data now untainted
- } else {
- die "Bad data in '$data'"; # log this somewhere
- }
-</pre>
-<p>This is fairly secure because <code>/\w+/</code> doesn’t normally
match shell
-metacharacters, nor are dot, dash, or at going to mean something special
-to the shell. Use of <code>/.+/</code> would have been insecure in theory
because
-it lets everything through, but Perl doesn’t check for that. The lesson
-is that when untainting, you must be exceedingly careful with your patterns.
-Laundering data using regular expression is the <em>only</em> mechanism for
-untainting dirty data, unless you use the strategy detailed below to fork
-a child of lesser privilege.
-</p>
-<p>The example does not untaint <code>$data</code> if <code>use locale</code>
is in effect,
-because the characters matched by <code>\w</code> are determined by the locale.
-Perl considers that locale definitions are untrustworthy because they
-contain data from outside the program. If you are writing a
-locale-aware program, and want to launder data with a regular expression
-containing <code>\w</code>, put <code>no locale</code> ahead of the expression
in the same
-block. See <a href="#perllocale-SECURITY">perllocale SECURITY</a> for further
discussion and examples.
-</p>
-<hr>
-<a name="perlsec-Switches-On-the-_0022_0023_0021_0022-Line"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsec-Taint-mode-and-_0040INC" accesskey="n"
rel="next">perlsec Taint mode and @INC</a>, Previous: <a
href="#perlsec-Laundering-and-Detecting-Tainted-Data" accesskey="p"
rel="prev">perlsec Laundering and Detecting Tainted Data</a>, Up: <a
href="#perlsec-SECURITY-MECHANISMS-AND-CONCERNS" accesskey="u" rel="up">perlsec
SECURITY MECHANISMS AND CONCERNS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Switches-On-the-_0022_0023_0021_0022-Line"></a>
-<h4 class="subsection">70.4.3 Switches On the "#!" Line</h4>
-
-<p>When you make a script executable, in order to make it usable as a
-command, the system will pass switches to perl from the script’s #!
-line. Perl checks that any command line switches given to a setuid
-(or setgid) script actually match the ones set on the #! line. Some
-Unix and Unix-like environments impose a one-switch limit on the #!
-line, so you may need to use something like <code>-wU</code> instead of
<code>-w -U</code>
-under such systems. (This issue should arise only in Unix or
-Unix-like environments that support #! and setuid or setgid scripts.)
-</p>
-<hr>
-<a name="perlsec-Taint-mode-and-_0040INC"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsec-Cleaning-Up-Your-Path" accesskey="n"
rel="next">perlsec Cleaning Up Your Path</a>, Previous: <a
href="#perlsec-Switches-On-the-_0022_0023_0021_0022-Line" accesskey="p"
rel="prev">perlsec Switches On the "#!" Line</a>, Up: <a
href="#perlsec-SECURITY-MECHANISMS-AND-CONCERNS" accesskey="u" rel="up">perlsec
SECURITY MECHANISMS AND CONCERNS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Taint-mode-and-_0040INC"></a>
-<h4 class="subsection">70.4.4 Taint mode and @INC</h4>
-
-<p>When the taint mode (<code>-T</code>) is in effect, the "."
directory is removed
-from <code>@INC</code>, and the environment variables <code>PERL5LIB</code>
and <code>PERLLIB</code>
-are ignored by Perl. You can still adjust <code>@INC</code> from outside the
-program by using the <code>-I</code> command line option as explained in
-<a href="#perlrun-NAME">perlrun NAME</a>. The two environment variables are
ignored because
-they are obscured, and a user running a program could be unaware that
-they are set, whereas the <code>-I</code> option is clearly visible and
-therefore permitted.
-</p>
-<p>Another way to modify <code>@INC</code> without modifying the program, is
to use
-the <code>lib</code> pragma, e.g.:
-</p>
-<pre class="verbatim"> perl -Mlib=/foo program
-</pre>
-<p>The benefit of using <code>-Mlib=/foo</code> over <code>-I/foo</code>, is
that the former
-will automagically remove any duplicated directories, while the latter
-will not.
-</p>
-<p>Note that if a tainted string is added to <code>@INC</code>, the following
-problem will be reported:
-</p>
-<pre class="verbatim"> Insecure dependency in require while running with -T
switch
-</pre>
-<hr>
-<a name="perlsec-Cleaning-Up-Your-Path"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsec-Security-Bugs" accesskey="n" rel="next">perlsec
Security Bugs</a>, Previous: <a href="#perlsec-Taint-mode-and-_0040INC"
accesskey="p" rel="prev">perlsec Taint mode and @INC</a>, Up: <a
href="#perlsec-SECURITY-MECHANISMS-AND-CONCERNS" accesskey="u" rel="up">perlsec
SECURITY MECHANISMS AND CONCERNS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Cleaning-Up-Your-Path"></a>
-<h4 class="subsection">70.4.5 Cleaning Up Your Path</h4>
-
-<p>For "Insecure <code>$ENV{PATH}</code>" messages, you need to set
<code>$ENV{'PATH'}</code> to
-a known value, and each directory in the path must be absolute and
-non-writable by others than its owner and group. You may be surprised to
-get this message even if the pathname to your executable is fully
-qualified. This is <em>not</em> generated because you didn’t supply a
full path
-to the program; instead, it’s generated because you never set your PATH
-environment variable, or you didn’t set it to something that was safe.
-Because Perl can’t guarantee that the executable in question isn’t
itself
-going to turn around and execute some other program that is dependent on
-your PATH, it makes sure you set the PATH.
-</p>
-<p>The PATH isn’t the only environment variable which can cause problems.
-Because some shells may use the variables IFS, CDPATH, ENV, and
-BASH_ENV, Perl checks that those are either empty or untainted when
-starting subprocesses. You may wish to add something like this to your
-setid and taint-checking scripts.
-</p>
-<pre class="verbatim"> delete @ENV{qw(IFS CDPATH ENV BASH_ENV)}; # Make
%ENV safer
-</pre>
-<p>It’s also possible to get into trouble with other operations that
don’t
-care whether they use tainted values. Make judicious use of the file
-tests in dealing with any user-supplied filenames. When possible, do
-opens and such <strong>after</strong> properly dropping any special user (or
group!)
-privileges. Perl doesn’t prevent you from
-opening tainted filenames for reading,
-so be careful what you print out. The tainting mechanism is intended to
-prevent stupid mistakes, not to remove the need for thought.
-</p>
-<p>Perl does not call the shell to expand wild cards when you pass
<code>system</code>
-and <code>exec</code> explicit parameter lists instead of strings with
possible shell
-wildcards in them. Unfortunately, the <code>open</code>, <code>glob</code>,
and
-backtick functions provide no such alternate calling convention, so more
-subterfuge will be required.
-</p>
-<p>Perl provides a reasonably safe way to open a file or pipe from a setuid
-or setgid program: just create a child process with reduced privilege who
-does the dirty work for you. First, fork a child using the special
-<code>open</code> syntax that connects the parent and child by a pipe. Now the
-child resets its ID set and any other per-process attributes, like
-environment variables, umasks, current working directories, back to the
-originals or known safe values. Then the child process, which no longer
-has any special permissions, does the <code>open</code> or other system call.
-Finally, the child passes the data it managed to access back to the
-parent. Because the file or pipe was opened in the child while running
-under less privilege than the parent, it’s not apt to be tricked into
-doing something it shouldn’t.
-</p>
-<p>Here’s a way to do backticks reasonably safely. Notice how the
<code>exec</code> is
-not called with a string that the shell could expand. This is by far the
-best way to call something that might be subjected to shell escapes: just
-never call the shell at all.
-</p>
-<pre class="verbatim"> use English;
- die "Can't fork: $!" unless defined($pid = open(KID,
"-|"));
- if ($pid) { # parent
- while (<KID>) {
- # do something
- }
- close KID;
- } else {
- my @temp = ($EUID, $EGID);
- my $orig_uid = $UID;
- my $orig_gid = $GID;
- $EUID = $UID;
- $EGID = $GID;
- # Drop privileges
- $UID = $orig_uid;
- $GID = $orig_gid;
- # Make sure privs are really gone
- ($EUID, $EGID) = @temp;
- die "Can't drop privileges"
- unless $UID == $EUID && $GID eq $EGID;
- $ENV{PATH} = "/bin:/usr/bin"; # Minimal PATH.
- # Consider sanitizing the environment even more.
- exec 'myprog', 'arg1', 'arg2'
- or die "can't exec myprog: $!";
- }
-</pre>
-<p>A similar strategy would work for wildcard expansion via <code>glob</code>,
although
-you can use <code>readdir</code> instead.
-</p>
-<p>Taint checking is most useful when although you trust yourself not to have
-written a program to give away the farm, you don’t necessarily trust
those
-who end up using it not to try to trick it into doing something bad. This
-is the kind of security checking that’s useful for set-id programs and
-programs launched on someone else’s behalf, like CGI programs.
-</p>
-<p>This is quite different, however, from not even trusting the writer of the
-code not to try to do something evil. That’s the kind of trust needed
-when someone hands you a program you’ve never seen before and says,
"Here,
-run this." For that kind of safety, you might want to check out the Safe
-module, included standard in the Perl distribution. This module allows the
-programmer to set up special compartments in which all system operations
-are trapped and namespace access is carefully controlled. Safe should
-not be considered bullet-proof, though: it will not prevent the foreign
-code to set up infinite loops, allocate gigabytes of memory, or even
-abusing perl bugs to make the host interpreter crash or behave in
-unpredictable ways. In any case it’s better avoided completely if
you’re
-really concerned about security.
-</p>
-<hr>
-<a name="perlsec-Security-Bugs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsec-Protecting-Your-Programs" accesskey="n"
rel="next">perlsec Protecting Your Programs</a>, Previous: <a
href="#perlsec-Cleaning-Up-Your-Path" accesskey="p" rel="prev">perlsec Cleaning
Up Your Path</a>, Up: <a href="#perlsec-SECURITY-MECHANISMS-AND-CONCERNS"
accesskey="u" rel="up">perlsec SECURITY MECHANISMS AND CONCERNS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Security-Bugs"></a>
-<h4 class="subsection">70.4.6 Security Bugs</h4>
-
-<p>Beyond the obvious problems that stem from giving special privileges to
-systems as flexible as scripts, on many versions of Unix, set-id scripts
-are inherently insecure right from the start. The problem is a race
-condition in the kernel. Between the time the kernel opens the file to
-see which interpreter to run and when the (now-set-id) interpreter turns
-around and reopens the file to interpret it, the file in question may have
-changed, especially if you have symbolic links on your system.
-</p>
-<p>Fortunately, sometimes this kernel "feature" can be disabled.
-Unfortunately, there are two ways to disable it. The system can simply
-outlaw scripts with any set-id bit set, which doesn’t help much.
-Alternately, it can simply ignore the set-id bits on scripts.
-</p>
-<p>However, if the kernel set-id script feature isn’t disabled, Perl will
-complain loudly that your set-id script is insecure. You’ll need to
-either disable the kernel set-id script feature, or put a C wrapper around
-the script. A C wrapper is just a compiled program that does nothing
-except call your Perl program. Compiled programs are not subject to the
-kernel bug that plagues set-id scripts. Here’s a simple wrapper, written
-in C:
-</p>
-<pre class="verbatim"> #define REAL_PATH "/path/to/script"
- main(ac, av)
- char **av;
- {
- execv(REAL_PATH, av);
- }
-</pre>
-<p>Compile this wrapper into a binary executable and then make <em>it</em>
rather
-than your script setuid or setgid.
-</p>
-<p>In recent years, vendors have begun to supply systems free of this
-inherent security bug. On such systems, when the kernel passes the name
-of the set-id script to open to the interpreter, rather than using a
-pathname subject to meddling, it instead passes <em>/dev/fd/3</em>. This is a
-special file already opened on the script, so that there can be no race
-condition for evil scripts to exploit. On these systems, Perl should be
-compiled with <code>-DSETUID_SCRIPTS_ARE_SECURE_NOW</code>. The
<samp>Configure</samp>
-program that builds Perl tries to figure this out for itself, so you
-should never have to specify this yourself. Most modern releases of
-SysVr4 and BSD 4.4 use this approach to avoid the kernel race condition.
-</p>
-<hr>
-<a name="perlsec-Protecting-Your-Programs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsec-Unicode" accesskey="n" rel="next">perlsec Unicode</a>,
Previous: <a href="#perlsec-Security-Bugs" accesskey="p" rel="prev">perlsec
Security Bugs</a>, Up: <a href="#perlsec-SECURITY-MECHANISMS-AND-CONCERNS"
accesskey="u" rel="up">perlsec SECURITY MECHANISMS AND CONCERNS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Protecting-Your-Programs"></a>
-<h4 class="subsection">70.4.7 Protecting Your Programs</h4>
-
-<p>There are a number of ways to hide the source to your Perl programs,
-with varying levels of "security".
-</p>
-<p>First of all, however, you <em>can’t</em> take away read permission,
because
-the source code has to be readable in order to be compiled and
-interpreted. (That doesn’t mean that a CGI script’s source is
-readable by people on the web, though.) So you have to leave the
-permissions at the socially friendly 0755 level. This lets
-people on your local system only see your source.
-</p>
-<p>Some people mistakenly regard this as a security problem. If your program
does
-insecure things, and relies on people not knowing how to exploit those
-insecurities, it is not secure. It is often possible for someone to
-determine the insecure things and exploit them without viewing the
-source. Security through obscurity, the name for hiding your bugs
-instead of fixing them, is little security indeed.
-</p>
-<p>You can try using encryption via source filters (Filter::* from CPAN,
-or Filter::Util::Call and Filter::Simple since Perl 5.8).
-But crackers might be able to decrypt it. You can try using the byte
-code compiler and interpreter described below, but crackers might be
-able to de-compile it. You can try using the native-code compiler
-described below, but crackers might be able to disassemble it. These
-pose varying degrees of difficulty to people wanting to get at your
-code, but none can definitively conceal it (this is true of every
-language, not just Perl).
-</p>
-<p>If you’re concerned about people profiting from your code, then the
-bottom line is that nothing but a restrictive license will give you
-legal security. License your software and pepper it with threatening
-statements like "This is unpublished proprietary software of XYZ Corp.
-Your access to it does not give you permission to use it blah blah
-blah." You should see a lawyer to be sure your license’s wording
will
-stand up in court.
-</p>
-<hr>
-<a name="perlsec-Unicode"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsec-Algorithmic-Complexity-Attacks" accesskey="n"
rel="next">perlsec Algorithmic Complexity Attacks</a>, Previous: <a
href="#perlsec-Protecting-Your-Programs" accesskey="p" rel="prev">perlsec
Protecting Your Programs</a>, Up: <a
href="#perlsec-SECURITY-MECHANISMS-AND-CONCERNS" accesskey="u" rel="up">perlsec
SECURITY MECHANISMS AND CONCERNS</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-1"></a>
-<h4 class="subsection">70.4.8 Unicode</h4>
-
-<p>Unicode is a new and complex technology and one may easily overlook
-certain security pitfalls. See <a href="#perluniintro-NAME">perluniintro
NAME</a> for an overview and
-<a href="#perlunicode-NAME">perlunicode NAME</a> for details, and <a
href="#perlunicode-Security-Implications-of-Unicode">perlunicode Security
Implications of Unicode</a> for security implications in particular.
-</p>
-<hr>
-<a name="perlsec-Algorithmic-Complexity-Attacks"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlsec-Unicode" accesskey="p" rel="prev">perlsec
Unicode</a>, Up: <a href="#perlsec-SECURITY-MECHANISMS-AND-CONCERNS"
accesskey="u" rel="up">perlsec SECURITY MECHANISMS AND CONCERNS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Algorithmic-Complexity-Attacks"></a>
-<h4 class="subsection">70.4.9 Algorithmic Complexity Attacks</h4>
-
-<p>Certain internal algorithms used in the implementation of Perl can
-be attacked by choosing the input carefully to consume large amounts
-of either time or space or both. This can lead into the so-called
-<em>Denial of Service</em> (DoS) attacks.
-</p>
-<ul>
-<li> Hash Algorithm - Hash algorithms like the one used in Perl are well
-known to be vulnerable to collision attacks on their hash function.
-Such attacks involve constructing a set of keys which collide into
-the same bucket producing inefficient behavior. Such attacks often
-depend on discovering the seed of the hash function used to map the
-keys to buckets. That seed is then used to brute-force a key set which
-can be used to mount a denial of service attack. In Perl 5.8.1 changes
-were introduced to harden Perl to such attacks, and then later in
-Perl 5.18.0 these features were enhanced and additional protections
-added.
-
-<p>At the time of this writing, Perl 5.18.0 is considered to be
-well-hardened against algorithmic complexity attacks on its hash
-implementation. This is largely owed to the following measures
-mitigate attacks:
-</p>
-<dl compact="compact">
-<dt>Hash Seed Randomization</dt>
-<dd><a name="perlsec-Hash-Seed-Randomization"></a>
-<p>In order to make it impossible to know what seed to generate an attack
-key set for, this seed is randomly initialized at process start. This
-may be overridden by using the PERL_HASH_SEED environment variable, see
-<a href="#perlrun-PERL_005fHASH_005fSEED">perlrun PERL_HASH_SEED</a>. This
environment variable controls how
-items are actually stored, not how they are presented via
-<code>keys</code>, <code>values</code> and <code>each</code>.
-</p>
-</dd>
-<dt>Hash Traversal Randomization</dt>
-<dd><a name="perlsec-Hash-Traversal-Randomization"></a>
-<p>Independent of which seed is used in the hash function, <code>keys</code>,
-<code>values</code>, and <code>each</code> return items in a per-hash
randomized order.
-Modifying a hash by insertion will change the iteration order of that hash.
-This behavior can be overridden by using <code>hash_traversal_mask()</code>
from
-<a href="Hash-Util.html#Top">(Hash-Util)</a> or by using the PERL_PERTURB_KEYS
environment variable,
-see <a href="#perlrun-PERL_005fPERTURB_005fKEYS">perlrun
PERL_PERTURB_KEYS</a>. Note that this feature controls the
-"visible" order of the keys, and not the actual order they are
stored in.
-</p>
-</dd>
-<dt>Bucket Order Perturbance</dt>
-<dd><a name="perlsec-Bucket-Order-Perturbance"></a>
-<p>When items collide into a given hash bucket the order they are stored in
-the chain is no longer predictable in Perl 5.18. This
-has the intention to make it harder to observe a
-collision. This behavior can be overridden by using
-the PERL_PERTURB_KEYS environment variable, see <a
href="#perlrun-PERL_005fPERTURB_005fKEYS">perlrun PERL_PERTURB_KEYS</a>.
-</p>
-</dd>
-<dt>New Default Hash Function</dt>
-<dd><a name="perlsec-New-Default-Hash-Function"></a>
-<p>The default hash function has been modified with the intention of making
-it harder to infer the hash seed.
-</p>
-</dd>
-<dt>Alternative Hash Functions</dt>
-<dd><a name="perlsec-Alternative-Hash-Functions"></a>
-<p>The source code includes multiple hash algorithms to choose from. While we
-believe that the default perl hash is robust to attack, we have included the
-hash function Siphash as a fall-back option. At the time of release of
-Perl 5.18.0 Siphash is believed to be of cryptographic strength. This is
-not the default as it is much slower than the default hash.
-</p>
-</dd>
-</dl>
-
-<p>Without compiling a special Perl, there is no way to get the exact same
-behavior of any versions prior to Perl 5.18.0. The closest one can get
-is by setting PERL_PERTURB_KEYS to 0 and setting the PERL_HASH_SEED
-to a known value. We do not advise those settings for production use
-due to the above security considerations.
-</p>
-<p><strong>Perl has never guaranteed any ordering of the hash keys</strong>,
and
-the ordering has already changed several times during the lifetime of
-Perl 5. Also, the ordering of hash keys has always been, and continues
-to be, affected by the insertion order and the history of changes made
-to the hash over its lifetime.
-</p>
-<p>Also note that while the order of the hash elements might be
-randomized, this "pseudo-ordering" should <strong>not</strong> be
used for
-applications like shuffling a list randomly (use
<code>List::Util::shuffle()</code>
-for that, see <a href="List-Util.html#Top">(List-Util)</a>, a standard core
module since Perl 5.8.0;
-or the CPAN module <code>Algorithm::Numerical::Shuffle</code>), or for
generating
-permutations (use e.g. the CPAN modules <code>Algorithm::Permute</code> or
-<code>Algorithm::FastPermute</code>), or for any cryptographic applications.
-</p>
-<p>Tied hashes may have their own ordering and algorithmic complexity
-attacks.
-</p>
-</li><li> Regular expressions - Perl’s regular expression engine is so
called NFA
-(Non-deterministic Finite Automaton), which among other things means that
-it can rather easily consume large amounts of both time and space if the
-regular expression may match in several ways. Careful crafting of the
-regular expressions can help but quite often there really isn’t much
-one can do (the book "Mastering Regular Expressions" is required
-reading, see <a href="perlfaq2.html#Top">(perlfaq2)</a>). Running out of
space manifests itself by
-Perl running out of memory.
-
-</li><li> Sorting - the quicksort algorithm used in Perls before 5.8.0 to
-implement the sort() function is very easy to trick into misbehaving
-so that it consumes a lot of time. Starting from Perl 5.8.0 a different
-sorting algorithm, mergesort, is used by default. Mergesort cannot
-misbehave on any input.
-
-</li></ul>
-
-<p>See <a
href="http://www.cs.rice.edu/~scrosby/hash/";>http://www.cs.rice.edu/~scrosby/hash/</a>
for more information,
-and any computer science textbook on algorithmic complexity.
-</p>
-<hr>
-<a name="perlsec-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlsec-SECURITY-MECHANISMS-AND-CONCERNS" accesskey="p"
rel="prev">perlsec SECURITY MECHANISMS AND CONCERNS</a>, Up: <a href="#perlsec"
accesskey="u" rel="up">perlsec</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-36"></a>
-<h3 class="section">70.5 SEE ALSO</h3>
-
-<p><a href="#perlrun-NAME">perlrun NAME</a> for its description of cleaning up
environment variables.
-</p>
-<hr>
-<a name="perlsource"></a>
-<div class="header">
-<p>
-Next: <a href="#perlstyle" accesskey="n" rel="next">perlstyle</a>, Previous:
<a href="#perlsec" accesskey="p" rel="prev">perlsec</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlsource-1"></a>
-<h2 class="chapter">71 perlsource</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlsource-NAME"
accesskey="1">perlsource NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsource-DESCRIPTION"
accesskey="2">perlsource DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsource-FINDING-YOUR-WAY-AROUND" accesskey="3">perlsource FINDING
YOUR WAY AROUND</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlsource-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsource-DESCRIPTION" accesskey="n" rel="next">perlsource
DESCRIPTION</a>, Up: <a href="#perlsource" accesskey="u"
rel="up">perlsource</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-70"></a>
-<h3 class="section">71.1 NAME</h3>
-
-<p>perlsource - A guide to the Perl source tree
-</p>
-<hr>
-<a name="perlsource-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsource-FINDING-YOUR-WAY-AROUND" accesskey="n"
rel="next">perlsource FINDING YOUR WAY AROUND</a>, Previous: <a
href="#perlsource-NAME" accesskey="p" rel="prev">perlsource NAME</a>, Up: <a
href="#perlsource" accesskey="u" rel="up">perlsource</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-69"></a>
-<h3 class="section">71.2 DESCRIPTION</h3>
-
-<p>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.
-</p>
-<hr>
-<a name="perlsource-FINDING-YOUR-WAY-AROUND"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlsource-DESCRIPTION" accesskey="p"
rel="prev">perlsource DESCRIPTION</a>, Up: <a href="#perlsource" accesskey="u"
rel="up">perlsource</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="FINDING-YOUR-WAY-AROUND"></a>
-<h3 class="section">71.3 FINDING YOUR WAY AROUND</h3>
-
-<p>The Perl source tree is big. Here’s some of the thing you’ll
find in
-it:
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlsource-C-code"
accesskey="1">perlsource C code</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsource-Core-modules"
accesskey="2">perlsource Core modules</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsource-Tests"
accesskey="3">perlsource Tests</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsource-Documentation"
accesskey="4">perlsource Documentation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsource-Hacking-tools-and-documentation" accesskey="5">perlsource
Hacking tools and documentation</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsource-Build-system"
accesskey="6">perlsource Build system</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsource-AUTHORS"
accesskey="7">perlsource <samp>AUTHORS</samp></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsource-MANIFEST"
accesskey="8">perlsource
<samp>MANIFEST</samp></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlsource-C-code"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsource-Core-modules" accesskey="n" rel="next">perlsource
Core modules</a>, Up: <a href="#perlsource-FINDING-YOUR-WAY-AROUND"
accesskey="u" rel="up">perlsource FINDING YOUR WAY AROUND</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="C-code"></a>
-<h4 class="subsection">71.3.1 C code</h4>
-
-<p>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.
-</p>
-<p>See <a href="#perlinterp-NAME">perlinterp NAME</a> for more details on the
files that make up the Perl
-interpreter, as well as details on how it works.
-</p>
-<hr>
-<a name="perlsource-Core-modules"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsource-Tests" accesskey="n" rel="next">perlsource
Tests</a>, Previous: <a href="#perlsource-C-code" accesskey="p"
rel="prev">perlsource C code</a>, Up: <a
href="#perlsource-FINDING-YOUR-WAY-AROUND" accesskey="u" rel="up">perlsource
FINDING YOUR WAY AROUND</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Core-modules"></a>
-<h4 class="subsection">71.3.2 Core modules</h4>
-
-<p>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.
-</p>
-<ul>
-<li> <samp>lib/</samp>
-
-<p>This directory contains pure-Perl modules which are only released as
-part of the core. This directory contains <em>all</em> of the modules and
-their tests, unlike other core modules.
-</p>
-</li><li> <samp>ext/</samp>
-
-<p>Like <samp>lib/</samp>, this directory contains modules which are only
released
-as part of the core. Unlike <samp>lib/</samp>, however, a module under
<samp>ext/</samp>
-generally has a CPAN-style directory- and file-layout and its own
-<samp>Makefile.PL</samp>. There is no expectation that a module under
<samp>ext/</samp>
-will work with earlier versions of Perl 5. Hence, such a module may
-take full advantage of syntactical and other improvements in Perl 5
-blead.
-</p>
-</li><li> <samp>dist/</samp>
-
-<p>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. Modules under <samp>dist/</samp> should make
-an effort to work with earlier versions of Perl 5.
-</p>
-</li><li> <samp>cpan/</samp>
-
-<p>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.
-</p>
-</li></ul>
-
-<p>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 <samp>cpan/</samp>.
-</p>
-<hr>
-<a name="perlsource-Tests"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsource-Documentation" accesskey="n" rel="next">perlsource
Documentation</a>, Previous: <a href="#perlsource-Core-modules" accesskey="p"
rel="prev">perlsource Core modules</a>, Up: <a
href="#perlsource-FINDING-YOUR-WAY-AROUND" accesskey="u" rel="up">perlsource
FINDING YOUR WAY AROUND</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Tests"></a>
-<h4 class="subsection">71.3.3 Tests</h4>
-
-<p>The Perl core has an extensive test suite. If you add new tests (or new
-modules with tests), you may need to update the <samp>t/TEST</samp> file so
that
-the tests are run.
-</p>
-<ul>
-<li> Module tests
-
-<p>Tests for core modules in the <samp>lib/</samp> directory are right next to
the
-module itself. For example, we have <samp>lib/strict.pm</samp> and
-<samp>lib/strict.t</samp>.
-</p>
-<p>Tests for modules in <samp>ext/</samp> and the dual-life modules are in
<samp>t/</samp>
-subdirectories for each module, like a standard CPAN distribution.
-</p>
-</li><li> <samp>t/base/</samp>
-
-<p>Tests for the absolute basic functionality of Perl. This includes
-<code>if</code>, basic file reads and writes, simple regexes, etc. These are
run
-first in the test suite and if any of them fail, something is <em>really</em>
-broken.
-</p>
-</li><li> <samp>t/cmd/</samp>
-
-<p>Tests for basic control structures, <code>if/else</code>,
<code>while</code>, subroutines,
-etc.
-</p>
-</li><li> <samp>t/comp/</samp>
-
-<p>Tests for basic issues of how Perl parses and compiles itself.
-</p>
-</li><li> <samp>t/io/</samp>
-
-<p>Tests for built-in IO functions, including command line arguments.
-</p>
-</li><li> <samp>t/mro/</samp>
-
-<p>Tests for perl’s method resolution order implementations (see <a
href="mro.html#Top">(mro)</a>).
-</p>
-</li><li> <samp>t/op/</samp>
-
-<p>Tests for perl’s built in functions that don’t fit into any of
the
-other directories.
-</p>
-</li><li> <samp>t/opbasic/</samp>
-
-<p>Tests for perl’s built in functions which, like those in
<samp>t/op/</samp>, do
-not fit into any of the other directories, but which, in addition,
-cannot use <samp>t/test.pl</samp>,as that program depends on functionality
which
-the test file itself is testing.
-</p>
-</li><li> <samp>t/re/</samp>
-
-<p>Tests for regex related functions or behaviour. (These used to live in
-t/op).
-</p>
-</li><li> <samp>t/run/</samp>
-
-<p>Tests for features of how perl actually runs, including exit codes and
-handling of PERL* environment variables.
-</p>
-</li><li> <samp>t/uni/</samp>
-
-<p>Tests for the core support of Unicode.
-</p>
-</li><li> <samp>t/win32/</samp>
-
-<p>Windows-specific tests.
-</p>
-</li><li> <samp>t/porting/</samp>
-
-<p>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 <samp>AUTHORS</samp> file.
-</p>
-</li><li> <samp>t/lib/</samp>
-
-<p>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!
-</p>
-</li></ul>
-
-<hr>
-<a name="perlsource-Documentation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsource-Hacking-tools-and-documentation" accesskey="n"
rel="next">perlsource Hacking tools and documentation</a>, Previous: <a
href="#perlsource-Tests" accesskey="p" rel="prev">perlsource Tests</a>, Up: <a
href="#perlsource-FINDING-YOUR-WAY-AROUND" accesskey="u" rel="up">perlsource
FINDING YOUR WAY AROUND</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Documentation-1"></a>
-<h4 class="subsection">71.3.4 Documentation</h4>
-
-<p>All of the core documentation intended for end users lives in
<samp>pod/</samp>.
-Individual modules in <samp>lib/</samp>, <samp>ext/</samp>,
<samp>dist/</samp>, and <samp>cpan/</samp> usually
-have their own documentation, either in the <samp>Module.pm</samp> file or an
-accompanying <samp>Module.pod</samp> file.
-</p>
-<p>Finally, documentation intended for core Perl developers lives in the
-<samp>Porting/</samp> directory.
-</p>
-<hr>
-<a name="perlsource-Hacking-tools-and-documentation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsource-Build-system" accesskey="n" rel="next">perlsource
Build system</a>, Previous: <a href="#perlsource-Documentation" accesskey="p"
rel="prev">perlsource Documentation</a>, Up: <a
href="#perlsource-FINDING-YOUR-WAY-AROUND" accesskey="u" rel="up">perlsource
FINDING YOUR WAY AROUND</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Hacking-tools-and-documentation"></a>
-<h4 class="subsection">71.3.5 Hacking tools and documentation</h4>
-
-<p>The <samp>Porting</samp> directory contains a grab bag of code and
documentation
-intended to help porters work on Perl. Some of the highlights include:
-</p>
-<ul>
-<li> <samp>check*</samp>
-
-<p>These are scripts which will check the source things like ANSI C
-violations, POD encoding issues, etc.
-</p>
-</li><li> <samp>Maintainers</samp>, <samp>Maintainers.pl</samp>, and
<samp>Maintainers.pm</samp>
-
-<p>These files contain information on who maintains which modules. Run
-<code>perl Porting/Maintainers -M Module::Name</code> to find out more
-information about a dual-life module.
-</p>
-</li><li> <samp>podtidy</samp>
-
-<p>Tidies a pod file. It’s a good idea to run this on a pod file
you’ve
-patched.
-</p>
-</li></ul>
-
-<hr>
-<a name="perlsource-Build-system"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsource-AUTHORS" accesskey="n" rel="next">perlsource
<samp>AUTHORS</samp></a>, Previous: <a
href="#perlsource-Hacking-tools-and-documentation" accesskey="p"
rel="prev">perlsource Hacking tools and documentation</a>, Up: <a
href="#perlsource-FINDING-YOUR-WAY-AROUND" accesskey="u" rel="up">perlsource
FINDING YOUR WAY AROUND</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Build-system"></a>
-<h4 class="subsection">71.3.6 Build system</h4>
-
-<p>The Perl build system starts with the <samp>Configure</samp> script in the
root
-directory.
-</p>
-<p>Platform-specific pieces of the build system also live in
-platform-specific directories like <samp>win32/</samp>, <samp>vms/</samp>, etc.
-</p>
-<p>The <samp>Configure</samp> script is ultimately responsible for generating a
-<samp>Makefile</samp>.
-</p>
-<p>The build system that Perl uses is called metaconfig. This system is
-maintained separately from the Perl core.
-</p>
-<p>The metaconfig system has its own git repository. Please see its README
-file in <a
href="http://perl5.git.perl.org/metaconfig.git/";>http://perl5.git.perl.org/metaconfig.git/</a>
for more details.
-</p>
-<p>The <samp>Cross</samp> directory contains various files related to
-cross-compiling Perl. See <samp>Cross/README</samp> for more details.
-</p>
-<hr>
-<a name="perlsource-AUTHORS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsource-MANIFEST" accesskey="n" rel="next">perlsource
<samp>MANIFEST</samp></a>, Previous: <a href="#perlsource-Build-system"
accesskey="p" rel="prev">perlsource Build system</a>, Up: <a
href="#perlsource-FINDING-YOUR-WAY-AROUND" accesskey="u" rel="up">perlsource
FINDING YOUR WAY AROUND</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHORS-5"></a>
-<h4 class="subsection">71.3.7 <samp>AUTHORS</samp></h4>
-
-<p>This file lists everyone who’s contributed to Perl. If you submit a
-patch, you should add your name to this file as part of the patch.
-</p>
-<hr>
-<a name="perlsource-MANIFEST"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlsource-AUTHORS" accesskey="p" rel="prev">perlsource
<samp>AUTHORS</samp></a>, Up: <a href="#perlsource-FINDING-YOUR-WAY-AROUND"
accesskey="u" rel="up">perlsource FINDING YOUR WAY AROUND</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="MANIFEST"></a>
-<h4 class="subsection">71.3.8 <samp>MANIFEST</samp></h4>
-
-<p>The <samp>MANIFEST</samp> 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.
-</p>
-<p>You can get an overview of all the files with this command:
-</p>
-<pre class="verbatim"> % perl -lne 'print if /^[^\/]+\.[ch]\s+/' MANIFEST
-</pre>
-<hr>
-<a name="perlstyle"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub" accesskey="n" rel="next">perlsub</a>, Previous: <a
href="#perlsource" accesskey="p" rel="prev">perlsource</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlstyle-1"></a>
-<h2 class="chapter">72 perlstyle</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlstyle-NAME"
accesskey="1">perlstyle NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlstyle-DESCRIPTION"
accesskey="2">perlstyle DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlstyle-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlstyle-DESCRIPTION" accesskey="n" rel="next">perlstyle
DESCRIPTION</a>, Up: <a href="#perlstyle" accesskey="u" rel="up">perlstyle</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-71"></a>
-<h3 class="section">72.1 NAME</h3>
-
-<p>perlstyle - Perl style guide
-</p>
-<hr>
-<a name="perlstyle-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlstyle-NAME" accesskey="p" rel="prev">perlstyle
NAME</a>, Up: <a href="#perlstyle" accesskey="u" rel="up">perlstyle</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-70"></a>
-<h3 class="section">72.2 DESCRIPTION</h3>
-
-<p>Each programmer will, of course, have his or her own preferences in
-regards to formatting, but there are some general guidelines that will
-make your programs easier to read, understand, and maintain.
-</p>
-<p>The most important thing is to run your programs under the
<strong>-w</strong>
-flag at all times. You may turn it off explicitly for particular
-portions of code via the <code>no warnings</code> pragma or the
<code>$^W</code> variable
-if you must. You should also always run under <code>use strict</code> or know
the
-reason why not. The <code>use sigtrap</code> and even <code>use
diagnostics</code> pragmas
-may also prove useful.
-</p>
-<p>Regarding aesthetics of code lay out, about the only thing Larry
-cares strongly about is that the closing curly bracket of
-a multi-line BLOCK should line up with the keyword that started the construct.
-Beyond that, he has other preferences that aren’t so strong:
-</p>
-<ul>
-<li> 4-column indent.
-
-</li><li> Opening curly on same line as keyword, if possible, otherwise line
up.
-
-</li><li> Space before the opening curly of a multi-line BLOCK.
-
-</li><li> One-line BLOCK may be put on one line, including curlies.
-
-</li><li> No space before the semicolon.
-
-</li><li> Semicolon omitted in "short" one-line BLOCK.
-
-</li><li> Space around most operators.
-
-</li><li> Space around a "complex" subscript (inside brackets).
-
-</li><li> Blank lines between chunks that do different things.
-
-</li><li> Uncuddled elses.
-
-</li><li> No space between function name and its opening parenthesis.
-
-</li><li> Space after each comma.
-
-</li><li> Long lines broken after an operator (except <code>and</code> and
<code>or</code>).
-
-</li><li> Space after last parenthesis matching on current line.
-
-</li><li> Line up corresponding items vertically.
-
-</li><li> Omit redundant punctuation as long as clarity doesn’t suffer.
-
-</li></ul>
-
-<p>Larry has his reasons for each of these things, but he doesn’t claim
that
-everyone else’s mind works the same as his does.
-</p>
-<p>Here are some other more substantive style issues to think about:
-</p>
-<ul>
-<li> Just because you <em>CAN</em> do something a particular way doesn’t
mean that
-you <em>SHOULD</em> do it that way. Perl is designed to give you several
-ways to do anything, so consider picking the most readable one. For
-instance
-
-<pre class="verbatim"> open(FOO,$foo) || die "Can't open $foo:
$!";
-</pre>
-<p>is better than
-</p>
-<pre class="verbatim"> die "Can't open $foo: $!" unless
open(FOO,$foo);
-</pre>
-<p>because the second way hides the main point of the statement in a
-modifier. On the other hand
-</p>
-<pre class="verbatim"> print "Starting analysis\n" if $verbose;
-</pre>
-<p>is better than
-</p>
-<pre class="verbatim"> $verbose && print "Starting
analysis\n";
-</pre>
-<p>because the main point isn’t whether the user typed
<strong>-v</strong> or not.
-</p>
-<p>Similarly, just because an operator lets you assume default arguments
-doesn’t mean that you have to make use of the defaults. The defaults
-are there for lazy systems programmers writing one-shot programs. If
-you want your program to be readable, consider supplying the argument.
-</p>
-<p>Along the same lines, just because you <em>CAN</em> omit parentheses in many
-places doesn’t mean that you ought to:
-</p>
-<pre class="verbatim"> return print reverse sort num values %array;
- return print(reverse(sort num (values(%array))));
-</pre>
-<p>When in doubt, parenthesize. At the very least it will let some poor
-schmuck bounce on the % key in <strong>vi</strong>.
-</p>
-<p>Even if you aren’t in doubt, consider the mental welfare of the person
-who has to maintain the code after you, and who will probably put
-parentheses in the wrong place.
-</p>
-</li><li> Don’t go through silly contortions to exit a loop at the top
or the
-bottom, when Perl provides the <code>last</code> operator so you can exit in
-the middle. Just "outdent" it a little to make it more visible:
-
-<pre class="verbatim"> LINE:
- for (;;) {
- statements;
- last LINE if $foo;
- next LINE if /^#/;
- statements;
- }
-</pre>
-</li><li> Don’t be afraid to use loop labels–they’re there
to enhance
-readability as well as to allow multilevel loop breaks. See the
-previous example.
-
-</li><li> Avoid using <code>grep()</code> (or <code>map()</code>) or
‘backticks‘ in a void context, that is,
-when you just throw away their return values. Those functions all
-have return values, so use them. Otherwise use a <code>foreach()</code> loop
or
-the <code>system()</code> function instead.
-
-</li><li> For portability, when using features that may not be implemented on
-every machine, test the construct in an eval to see if it fails. If
-you know what version or patchlevel a particular feature was
-implemented, you can test <code>$]</code> (<code>$PERL_VERSION</code> in
<code>English</code>) to see if it
-will be there. The <code>Config</code> module will also let you interrogate
values
-determined by the <strong>Configure</strong> program when Perl was installed.
-
-</li><li> Choose mnemonic identifiers. If you can’t remember what
mnemonic means,
-you’ve got a problem.
-
-</li><li> While short identifiers like <code>$gotit</code> are probably ok,
use underscores to
-separate words in longer identifiers. It is generally easier to read
-<code>$var_names_like_this</code> than <code>$VarNamesLikeThis</code>,
especially for
-non-native speakers of English. It’s also a simple rule that works
-consistently with <code>VAR_NAMES_LIKE_THIS</code>.
-
-<p>Package names are sometimes an exception to this rule. Perl informally
-reserves lowercase module names for "pragma" modules like
<code>integer</code> and
-<code>strict</code>. Other modules should begin with a capital letter and use
mixed
-case, but probably without underscores due to limitations in primitive
-file systems’ representations of module names as files that must fit
into a
-few sparse bytes.
-</p>
-</li><li> You may find it helpful to use letter case to indicate the scope
-or nature of a variable. For example:
-
-<pre class="verbatim"> $ALL_CAPS_HERE constants only (beware clashes with
perl vars!)
- $Some_Caps_Here package-wide global/static
- $no_caps_here function scope my() or local() variables
-</pre>
-<p>Function and method names seem to work best as all lowercase.
-E.g., <code>$obj->as_string()</code>.
-</p>
-<p>You can use a leading underscore to indicate that a variable or
-function should not be used outside the package that defined it.
-</p>
-</li><li> If you have a really hairy regular expression, use the
<code>/x</code> modifier and
-put in some whitespace to make it look a little less like line noise.
-Don’t use slash as a delimiter when your regexp has slashes or
backslashes.
-
-</li><li> Use the new <code>and</code> and <code>or</code> operators to avoid
having to parenthesize
-list operators so much, and to reduce the incidence of punctuation
-operators like <code>&&</code> and <code>||</code>. Call your
subroutines as if they were
-functions or list operators to avoid excessive ampersands and parentheses.
-
-</li><li> Use here documents instead of repeated <code>print()</code>
statements.
-
-</li><li> Line up corresponding things vertically, especially if it’d be
too long
-to fit on one line anyway.
-
-<pre class="verbatim"> $IDX = $ST_MTIME;
- $IDX = $ST_ATIME if $opt_u;
- $IDX = $ST_CTIME if $opt_c;
- $IDX = $ST_SIZE if $opt_s;
-
- mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!";
- chdir($tmpdir) or die "can't chdir $tmpdir: $!";
- mkdir 'tmp', 0777 or die "can't mkdir $tmpdir/tmp: $!";
-</pre>
-</li><li> Always check the return codes of system calls. Good error messages
should
-go to <code>STDERR</code>, include which program caused the problem, what the
failed
-system call and arguments were, and (VERY IMPORTANT) should contain the
-standard system error message for what went wrong. Here’s a simple but
-sufficient example:
-
-<pre class="verbatim"> opendir(D, $dir) or die "can't opendir
$dir: $!";
-</pre>
-</li><li> Line up your transliterations when it makes sense:
-
-<pre class="verbatim"> tr [abc]
- [xyz];
-</pre>
-</li><li> Think about reusability. Why waste brainpower on a one-shot when you
-might want to do something like it again? Consider generalizing your
-code. Consider writing a module or object class. Consider making your
-code run cleanly with <code>use strict</code> and <code>use warnings</code>
(or <strong>-w</strong>) in
-effect. Consider giving away your code. Consider changing your whole
-world view. Consider... oh, never mind.
-
-</li><li> Try to document your code and use Pod formatting in a consistent
way. Here
-are commonly expected conventions:
-
-<ul>
-<li> use <code>C<></code> for function, variable and module names (and
more
-generally anything that can be considered part of code, like filehandles
-or specific values). Note that function names are considered more readable
-with parentheses after their name, that is <code>function()</code>.
-
-</li><li> use <code>B<></code> for commands names like
<strong>cat</strong> or <strong>grep</strong>.
-
-</li><li> use <code>F<></code> or <code>C<></code> for file names.
<code>F<></code> should
-be the only Pod code for file names, but as most Pod formatters render it
-as italic, Unix and Windows paths with their slashes and backslashes may
-be less readable, and better rendered with <code>C<></code>.
-
-</li></ul>
-
-</li><li> Be consistent.
-
-</li><li> Be nice.
-
-</li></ul>
-
-<hr>
-<a name="perlsub"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn" accesskey="n" rel="next">perlsyn</a>, Previous: <a
href="#perlstyle" accesskey="p" rel="prev">perlstyle</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlsub-2"></a>
-<h2 class="chapter">73 perlsub</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlsub-NAME"
accesskey="1">perlsub NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsub-SYNOPSIS"
accesskey="2">perlsub SYNOPSIS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsub-DESCRIPTION"
accesskey="3">perlsub DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsub-SEE-ALSO"
accesskey="4">perlsub SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlsub-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-SYNOPSIS" accesskey="n" rel="next">perlsub
SYNOPSIS</a>, Up: <a href="#perlsub" accesskey="u" rel="up">perlsub</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-72"></a>
-<h3 class="section">73.1 NAME</h3>
-
-<p>perlsub - Perl subroutines
-</p>
-<hr>
-<a name="perlsub-SYNOPSIS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-DESCRIPTION" accesskey="n" rel="next">perlsub
DESCRIPTION</a>, Previous: <a href="#perlsub-NAME" accesskey="p"
rel="prev">perlsub NAME</a>, Up: <a href="#perlsub" accesskey="u"
rel="up">perlsub</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SYNOPSIS-10"></a>
-<h3 class="section">73.2 SYNOPSIS</h3>
-
-<p>To declare subroutines:
-</p>
-<pre class="verbatim"> sub NAME; # A
"forward" declaration.
- sub NAME(PROTO); # ditto, but with prototypes
- sub NAME : ATTRS; # with attributes
- sub NAME(PROTO) : ATTRS; # with attributes and prototypes
-
- sub NAME BLOCK # A declaration and a definition.
- sub NAME(PROTO) BLOCK # ditto, but with prototypes
- sub NAME(SIG) BLOCK # with a signature instead
- sub NAME : ATTRS BLOCK # with attributes
- sub NAME(PROTO) : ATTRS BLOCK # with prototypes and attributes
- sub NAME(SIG) : ATTRS BLOCK # with a signature and attributes
-</pre>
-<p>To define an anonymous subroutine at runtime:
-</p>
-<pre class="verbatim"> $subref = sub BLOCK; # no proto
- $subref = sub (PROTO) BLOCK; # with proto
- $subref = sub (SIG) BLOCK; # with signature
- $subref = sub : ATTRS BLOCK; # with attributes
- $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes
- $subref = sub (SIG) : ATTRS BLOCK; # with signature and attributes
-</pre>
-<p>To import subroutines:
-</p>
-<pre class="verbatim"> use MODULE qw(NAME1 NAME2 NAME3);
-</pre>
-<p>To call subroutines:
-</p>
-<pre class="verbatim"> NAME(LIST); # & is optional with parentheses.
- NAME LIST; # Parentheses optional if predeclared/imported.
- &NAME(LIST); # Circumvent prototypes.
- &NAME; # Makes current @_ visible to called subroutine.
-</pre>
-<hr>
-<a name="perlsub-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-SEE-ALSO" accesskey="n" rel="next">perlsub SEE
ALSO</a>, Previous: <a href="#perlsub-SYNOPSIS" accesskey="p"
rel="prev">perlsub SYNOPSIS</a>, Up: <a href="#perlsub" accesskey="u"
rel="up">perlsub</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-71"></a>
-<h3 class="section">73.3 DESCRIPTION</h3>
-
-<p>Like many languages, Perl provides for user-defined subroutines.
-These may be located anywhere in the main program, loaded in from
-other files via the <code>do</code>, <code>require</code>, or <code>use</code>
keywords, or
-generated on the fly using <code>eval</code> or anonymous subroutines.
-You can even call a function indirectly using a variable containing
-its name or a CODE reference.
-</p>
-<p>The Perl model for function call and return values is simple: all
-functions are passed as parameters one single flat list of scalars, and
-all functions likewise return to their caller one single flat list of
-scalars. Any arrays or hashes in these call and return lists will
-collapse, losing their identities–but you may always use
-pass-by-reference instead to avoid this. Both call and return lists may
-contain as many or as few scalar elements as you’d like. (Often a
-function without an explicit return statement is called a subroutine, but
-there’s really no difference from Perl’s perspective.)
-</p>
-<p>Any arguments passed in show up in the array <code>@_</code>.
-(They may also show up in lexical variables introduced by a signature;
-see <a href="#perlsub-Signatures">Signatures</a> below.) Therefore, if
-you called a function with two arguments, those would be stored in
-<code>$_[0]</code> and <code>$_[1]</code>. The array <code>@_</code> is a
local array, but its
-elements are aliases for the actual scalar parameters. In particular,
-if an element <code>$_[0]</code> is updated, the corresponding argument is
-updated (or an error occurs if it is not updatable). If an argument
-is an array or hash element which did not exist when the function
-was called, that element is created only when (and if) it is modified
-or a reference to it is taken. (Some earlier versions of Perl
-created the element whether or not the element was assigned to.)
-Assigning to the whole array <code>@_</code> removes that aliasing, and does
-not update any arguments.
-</p>
-<p>A <code>return</code> statement may be used to exit a subroutine, optionally
-specifying the returned value, which will be evaluated in the
-appropriate context (list, scalar, or void) depending on the context of
-the subroutine call. If you specify no return value, the subroutine
-returns an empty list in list context, the undefined value in scalar
-context, or nothing in void context. If you return one or more
-aggregates (arrays and hashes), these will be flattened together into
-one large indistinguishable list.
-</p>
-<p>If no <code>return</code> is found and if the last statement is an
expression, its
-value is returned. If the last statement is a loop control structure
-like a <code>foreach</code> or a <code>while</code>, the returned value is
unspecified. The
-empty sub returns the empty list.
-</p>
-<p>Aside from an experimental facility (see <a
href="#perlsub-Signatures">Signatures</a> below),
-Perl does not have named formal parameters. In practice all you
-do is assign to a <code>my()</code> list of these. Variables that aren’t
-declared to be private are global variables. For gory details
-on creating private variables, see <a
href="#perlsub-Private-Variables-via-my_0028_0029">Private Variables via
my()</a>
-and <a href="#perlsub-Temporary-Values-via-local_0028_0029">Temporary Values
via local()</a>. To create protected
-environments for a set of functions in a separate package (and
-probably a separate file), see <a href="#perlmod-Packages">perlmod
Packages</a>.
-</p>
-<p>Example:
-</p>
-<pre class="verbatim"> sub max {
- my $max = shift(@_);
- foreach $foo (@_) {
- $max = $foo if $max < $foo;
- }
- return $max;
- }
- $bestday = max($mon,$tue,$wed,$thu,$fri);
-</pre>
-<p>Example:
-</p>
-<pre class="verbatim"> # get a line, combining continuation lines
- # that start with whitespace
-
- sub get_line {
- $thisline = $lookahead; # global variables!
- LINE: while (defined($lookahead = <STDIN>)) {
- if ($lookahead =~ /^[ \t]/) {
- $thisline .= $lookahead;
- }
- else {
- last LINE;
- }
- }
- return $thisline;
- }
-
- $lookahead = <STDIN>; # get first line
- while (defined($line = get_line())) {
- ...
- }
-</pre>
-<p>Assigning to a list of private variables to name your arguments:
-</p>
-<pre class="verbatim"> sub maybeset {
- my($key, $value) = @_;
- $Foo{$key} = $value unless $Foo{$key};
- }
-</pre>
-<p>Because the assignment copies the values, this also has the effect
-of turning call-by-reference into call-by-value. Otherwise a
-function is free to do in-place modifications of <code>@_</code> and change
-its caller’s values.
-</p>
-<pre class="verbatim"> upcase_in($v1, $v2); # this changes $v1 and $v2
- sub upcase_in {
- for (@_) { tr/a-z/A-Z/ }
- }
-</pre>
-<p>You aren’t allowed to modify constants in this way, of course. If an
-argument were actually literal and you tried to change it, you’d take a
-(presumably fatal) exception. For example, this won’t work:
-</p>
-<pre class="verbatim"> upcase_in("frederick");
-</pre>
-<p>It would be much safer if the <code>upcase_in()</code> function
-were written to return a copy of its parameters instead
-of changing them in place:
-</p>
-<pre class="verbatim"> ($v3, $v4) = upcase($v1, $v2); # this doesn't
change $v1 and $v2
- sub upcase {
- return unless defined wantarray; # void context, do nothing
- my @parms = @_;
- for (@parms) { tr/a-z/A-Z/ }
- return wantarray ? @parms : $parms[0];
- }
-</pre>
-<p>Notice how this (unprototyped) function doesn’t care whether it was
-passed real scalars or arrays. Perl sees all arguments as one big,
-long, flat parameter list in <code>@_</code>. This is one area where
-Perl’s simple argument-passing style shines. The <code>upcase()</code>
-function would work perfectly well without changing the <code>upcase()</code>
-definition even if we fed it things like this:
-</p>
-<pre class="verbatim"> @newlist = upcase(@list1, @list2);
- @newlist = upcase( split /:/, $var );
-</pre>
-<p>Do not, however, be tempted to do this:
-</p>
-<pre class="verbatim"> (@a, @b) = upcase(@list1, @list2);
-</pre>
-<p>Like the flattened incoming parameter list, the return list is also
-flattened on return. So all you have managed to do here is stored
-everything in <code>@a</code> and made <code>@b</code> empty. See
-<a href="#perlsub-Pass-by-Reference">Pass by Reference</a> for alternatives.
-</p>
-<p>A subroutine may be called using an explicit <code>&</code> prefix. The
-<code>&</code> is optional in modern Perl, as are parentheses if the
-subroutine has been predeclared. The <code>&</code> is <em>not</em>
optional
-when just naming the subroutine, such as when it’s used as
-an argument to defined() or undef(). Nor is it optional when you
-want to do an indirect subroutine call with a subroutine name or
-reference using the <code>&$subref()</code> or
<code>&{$subref}()</code> constructs,
-although the <code>$subref->()</code> notation solves that problem.
-See <a href="#perlref-NAME">perlref NAME</a> for more about all that.
-</p>
-<p>Subroutines may be called recursively. If a subroutine is called
-using the <code>&</code> form, the argument list is optional, and if
omitted,
-no <code>@_</code> array is set up for the subroutine: the <code>@_</code>
array at the
-time of the call is visible to subroutine instead. This is an
-efficiency mechanism that new users may wish to avoid.
-</p>
-<pre class="verbatim"> &foo(1,2,3); # pass three arguments
- foo(1,2,3); # the same
-
- foo(); # pass a null list
- &foo(); # the same
-
- &foo; # foo() get current args, like foo(@_) !!
- foo; # like foo() IFF sub foo predeclared, else
"foo"
-</pre>
-<p>Not only does the <code>&</code> form make the argument list optional,
it also
-disables any prototype checking on arguments you do provide. This
-is partly for historical reasons, and partly for having a convenient way
-to cheat if you know what you’re doing. See <a
href="#perlsub-Prototypes">Prototypes</a> below.
-</p>
-<p>Since Perl 5.16.0, the <code>__SUB__</code> token is available under
<code>use feature
-'current_sub'</code> and <code>use 5.16.0</code>. It will evaluate to a
reference to the
-currently-running sub, which allows for recursive calls without knowing
-your subroutine’s name.
-</p>
-<pre class="verbatim"> use 5.16.0;
- my $factorial = sub {
- my ($x) = @_;
- return 1 if $x == 1;
- return($x * __SUB__->( $x - 1 ) );
- };
-</pre>
-<p>The behavior of <code>__SUB__</code> within a regex code block (such as
<code>/(?{...})/</code>)
-is subject to change.
-</p>
-<p>Subroutines whose names are in all upper case are reserved to the Perl
-core, as are modules whose names are in all lower case. A subroutine in
-all capitals is a loosely-held convention meaning it will be called
-indirectly by the run-time system itself, usually due to a triggered event.
-Subroutines whose name start with a left parenthesis are also reserved the
-same way. The following is a list of some subroutines that currently do
-special, pre-defined things.
-</p>
-<dl compact="compact">
-<dt>documented later in this document</dt>
-<dd><a name="perlsub-documented-later-in-this-document"></a>
-<p><code>AUTOLOAD</code>
-</p>
-</dd>
-<dt>documented in <a href="#perlmod-NAME">perlmod NAME</a></dt>
-<dd><a name="perlsub-documented-in-perlmod-NAME"></a>
-<p><code>CLONE</code>, <code>CLONE_SKIP</code>,
-</p>
-</dd>
-<dt>documented in <a href="#perlobj-NAME">perlobj NAME</a></dt>
-<dd><a name="perlsub-documented-in-perlobj-NAME"></a>
-<p><code>DESTROY</code>
-</p>
-</dd>
-<dt>documented in <a href="#perltie-NAME">perltie NAME</a></dt>
-<dd><a name="perlsub-documented-in-perltie-NAME"></a>
-<p><code>BINMODE</code>, <code>CLEAR</code>, <code>CLOSE</code>,
<code>DELETE</code>, <code>DESTROY</code>, <code>EOF</code>,
<code>EXISTS</code>,
-<code>EXTEND</code>, <code>FETCH</code>, <code>FETCHSIZE</code>,
<code>FILENO</code>, <code>FIRSTKEY</code>, <code>GETC</code>,
-<code>NEXTKEY</code>, <code>OPEN</code>, <code>POP</code>, <code>PRINT</code>,
<code>PRINTF</code>, <code>PUSH</code>, <code>READ</code>,
-<code>READLINE</code>, <code>SCALAR</code>, <code>SEEK</code>,
<code>SHIFT</code>, <code>SPLICE</code>, <code>STORE</code>,
-<code>STORESIZE</code>, <code>TELL</code>, <code>TIEARRAY</code>,
<code>TIEHANDLE</code>, <code>TIEHASH</code>,
-<code>TIESCALAR</code>, <code>UNSHIFT</code>, <code>UNTIE</code>,
<code>WRITE</code>
-</p>
-</dd>
-<dt>documented in <a href="PerlIO-via.html#Top">(PerlIO-via)</a></dt>
-<dd><a name="perlsub-documented-in-PerlIO_002dvia"></a>
-<p><code>BINMODE</code>, <code>CLEARERR</code>, <code>CLOSE</code>,
<code>EOF</code>, <code>ERROR</code>, <code>FDOPEN</code>, <code>FILENO</code>,
-<code>FILL</code>, <code>FLUSH</code>, <code>OPEN</code>, <code>POPPED</code>,
<code>PUSHED</code>, <code>READ</code>, <code>SEEK</code>,
-<code>SETLINEBUF</code>, <code>SYSOPEN</code>, <code>TELL</code>,
<code>UNREAD</code>, <code>UTF8</code>, <code>WRITE</code>
-</p>
-</dd>
-<dt>documented in <a href="#perlfunc-NAME">perlfunc NAME</a></dt>
-<dd><a name="perlsub-documented-in-perlfunc-NAME"></a>
-<p><a href="_perlfunc.html#use">(_perlfunc)<code>import</code></a>, <a
href="_perlfunc.html#use">(_perlfunc)<code>unimport</code></a>,
-<a href="_perlfunc.html#require">(_perlfunc)<code>INC</code></a>
-</p>
-</dd>
-<dt>documented in <a href="UNIVERSAL.html#Top">(UNIVERSAL)</a></dt>
-<dd><a name="perlsub-documented-in-UNIVERSAL"></a>
-<p><code>VERSION</code>
-</p>
-</dd>
-<dt>documented in <a href="#perldebguts-NAME">perldebguts NAME</a></dt>
-<dd><a name="perlsub-documented-in-perldebguts-NAME"></a>
-<p><code>DB::DB</code>, <code>DB::sub</code>, <code>DB::lsub</code>,
<code>DB::goto</code>, <code>DB::postponed</code>
-</p>
-</dd>
-<dt>undocumented, used internally by the <a
href="overload.html#Top">(overload)</a> feature</dt>
-<dd><a
name="perlsub-undocumented_002c-used-internally-by-the-overload-feature"></a>
-<p>any starting with <code>(</code>
-</p>
-</dd>
-</dl>
-
-<p>The <code>BEGIN</code>, <code>UNITCHECK</code>, <code>CHECK</code>,
<code>INIT</code> and <code>END</code> subroutines
-are not so much subroutines as named special code blocks, of which you
-can have more than one in a package, and which you can <strong>not</strong>
call
-explicitly. See <a
href="#perlmod-BEGIN_002c-UNITCHECK_002c-CHECK_002c-INIT-and-END">perlmod
BEGIN, UNITCHECK, CHECK, INIT and END</a>
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlsub-Signatures"
accesskey="1">perlsub Signatures</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Private-Variables-via-my_0028_0029" accesskey="2">perlsub
Private Variables via my()</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Persistent-Private-Variables" accesskey="3">perlsub Persistent
Private Variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Temporary-Values-via-local_0028_0029" accesskey="4">perlsub
Temporary Values via local()</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsub-Lvalue-subroutines"
accesskey="5">perlsub Lvalue subroutines</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Lexical-Subroutines" accesskey="6">perlsub Lexical
Subroutines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Passing-Symbol-Table-Entries-_0028typeglobs_0029"
accesskey="7">perlsub Passing Symbol Table Entries
(typeglobs)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-When-to-Still-Use-local_0028_0029" accesskey="8">perlsub When to
Still Use local()</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsub-Pass-by-Reference"
accesskey="9">perlsub Pass by Reference</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsub-Prototypes">perlsub
Prototypes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Constant-Functions">perlsub Constant
Functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Overriding-Built_002din-Functions">perlsub Overriding Built-in
Functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Autoloading">perlsub
Autoloading</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Subroutine-Attributes">perlsub Subroutine
Attributes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlsub-Signatures"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Private-Variables-via-my_0028_0029" accesskey="n"
rel="next">perlsub Private Variables via my()</a>, Up: <a
href="#perlsub-DESCRIPTION" accesskey="u" rel="up">perlsub DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Signatures"></a>
-<h4 class="subsection">73.3.1 Signatures</h4>
-
-<p><strong>WARNING</strong>: Subroutine signatures are experimental. The
feature may be
-modified or removed in future versions of Perl.
-</p>
-<p>Perl has an experimental facility to allow a subroutine’s formal
-parameters to be introduced by special syntax, separate from the
-procedural code of the subroutine body. The formal parameter list
-is known as a <em>signature</em>. The facility must be enabled first by a
-pragmatic declaration, <code>use feature 'signatures'</code>, and it will
produce
-a warning unless the "experimental::signatures" warnings category is
-disabled.
-</p>
-<p>The signature is part of a subroutine’s body. Normally the body of a
-subroutine is simply a braced block of code. When using a signature,
-the signature is a parenthesised list that goes immediately after
-the subroutine name (or, for anonymous subroutines, immediately after
-the <code>sub</code> keyword). The signature declares lexical variables that
are
-in scope for the block. When the subroutine is called, the signature
-takes control first. It populates the signature variables from the
-list of arguments that were passed. If the argument list doesn’t meet
-the requirements of the signature, then it will throw an exception.
-When the signature processing is complete, control passes to the block.
-</p>
-<p>Positional parameters are handled by simply naming scalar variables in
-the signature. For example,
-</p>
-<pre class="verbatim"> sub foo ($left, $right) {
- return $left + $right;
- }
-</pre>
-<p>takes two positional parameters, which must be filled at runtime by
-two arguments. By default the parameters are mandatory, and it is
-not permitted to pass more arguments than expected. So the above is
-equivalent to
-</p>
-<pre class="verbatim"> sub foo {
- die "Too many arguments for subroutine" unless @_ <= 2;
- die "Too few arguments for subroutine" unless @_ >= 2;
- my $left = $_[0];
- my $right = $_[1];
- return $left + $right;
- }
-</pre>
-<p>An argument can be ignored by omitting the main part of the name from
-a parameter declaration, leaving just a bare <code>$</code> sigil. For
example,
-</p>
-<pre class="verbatim"> sub foo ($first, $, $third) {
- return "first=$first, third=$third";
- }
-</pre>
-<p>Although the ignored argument doesn’t go into a variable, it is still
-mandatory for the caller to pass it.
-</p>
-<p>A positional parameter is made optional by giving a default value,
-separated from the parameter name by <code>=</code>:
-</p>
-<pre class="verbatim"> sub foo ($left, $right = 0) {
- return $left + $right;
- }
-</pre>
-<p>The above subroutine may be called with either one or two arguments.
-The default value expression is evaluated when the subroutine is called,
-so it may provide different default values for different calls. It is
-only evaluated if the argument was actually omitted from the call.
-For example,
-</p>
-<pre class="verbatim"> my $auto_id = 0;
- sub foo ($thing, $id = $auto_id++) {
- print "$thing has ID $id";
- }
-</pre>
-<p>automatically assigns distinct sequential IDs to things for which no
-ID was supplied by the caller. A default value expression may also
-refer to parameters earlier in the signature, making the default for
-one parameter vary according to the earlier parameters. For example,
-</p>
-<pre class="verbatim"> sub foo ($first_name, $surname, $nickname =
$first_name) {
- print "$first_name $surname is known as
\"$nickname\"";
- }
-</pre>
-<p>An optional parameter can be nameless just like a mandatory parameter.
-For example,
-</p>
-<pre class="verbatim"> sub foo ($thing, $ = 1) {
- print $thing;
- }
-</pre>
-<p>The parameter’s default value will still be evaluated if the
corresponding
-argument isn’t supplied, even though the value won’t be stored
anywhere.
-This is in case evaluating it has important side effects. However, it
-will be evaluated in void context, so if it doesn’t have side effects
-and is not trivial it will generate a warning if the "void" warning
-category is enabled. If a nameless optional parameter’s default value
-is not important, it may be omitted just as the parameter’s name was:
-</p>
-<pre class="verbatim"> sub foo ($thing, $=) {
- print $thing;
- }
-</pre>
-<p>Optional positional parameters must come after all mandatory positional
-parameters. (If there are no mandatory positional parameters then an
-optional positional parameters can be the first thing in the signature.)
-If there are multiple optional positional parameters and not enough
-arguments are supplied to fill them all, they will be filled from left
-to right.
-</p>
-<p>After positional parameters, additional arguments may be captured in a
-slurpy parameter. The simplest form of this is just an array variable:
-</p>
-<pre class="verbatim"> sub foo ($filter, @inputs) {
- print $filter->($_) foreach @inputs;
- }
-</pre>
-<p>With a slurpy parameter in the signature, there is no upper limit on how
-many arguments may be passed. A slurpy array parameter may be nameless
-just like a positional parameter, in which case its only effect is to
-turn off the argument limit that would otherwise apply:
-</p>
-<pre class="verbatim"> sub foo ($thing, @) {
- print $thing;
- }
-</pre>
-<p>A slurpy parameter may instead be a hash, in which case the arguments
-available to it are interpreted as alternating keys and values.
-There must be as many keys as values: if there is an odd argument then
-an exception will be thrown. Keys will be stringified, and if there are
-duplicates then the later instance takes precedence over the earlier,
-as with standard hash construction.
-</p>
-<pre class="verbatim"> sub foo ($filter, %inputs) {
- print $filter->($_, $inputs{$_}) foreach sort keys %inputs;
- }
-</pre>
-<p>A slurpy hash parameter may be nameless just like other kinds of
-parameter. It still insists that the number of arguments available to
-it be even, even though they’re not being put into a variable.
-</p>
-<pre class="verbatim"> sub foo ($thing, %) {
- print $thing;
- }
-</pre>
-<p>A slurpy parameter, either array or hash, must be the last thing in the
-signature. It may follow mandatory and optional positional parameters;
-it may also be the only thing in the signature. Slurpy parameters cannot
-have default values: if no arguments are supplied for them then you get
-an empty array or empty hash.
-</p>
-<p>A signature may be entirely empty, in which case all it does is check
-that the caller passed no arguments:
-</p>
-<pre class="verbatim"> sub foo () {
- return 123;
- }
-</pre>
-<p>When using a signature, the arguments are still available in the special
-array variable <code>@_</code>, in addition to the lexical variables of the
-signature. There is a difference between the two ways of accessing the
-arguments: <code>@_</code> <em>aliases</em> the arguments, but the signature
variables
-get <em>copies</em> of the arguments. So writing to a signature variable
-only changes that variable, and has no effect on the caller’s variables,
-but writing to an element of <code>@_</code> modifies whatever the caller used
to
-supply that argument.
-</p>
-<p>There is a potential syntactic ambiguity between signatures and prototypes
-(see <a href="#perlsub-Prototypes">Prototypes</a>), because both start with an
opening parenthesis and
-both can appear in some of the same places, such as just after the name
-in a subroutine declaration. For historical reasons, when signatures
-are not enabled, any opening parenthesis in such a context will trigger
-very forgiving prototype parsing. Most signatures will be interpreted
-as prototypes in those circumstances, but won’t be valid prototypes.
-(A valid prototype cannot contain any alphabetic character.) This will
-lead to somewhat confusing error messages.
-</p>
-<p>To avoid ambiguity, when signatures are enabled the special syntax
-for prototypes is disabled. There is no attempt to guess whether a
-parenthesised group was intended to be a prototype or a signature.
-To give a subroutine a prototype under these circumstances, use a
-<a href="attributes.html#Built_002din-Attributes">(attributes)prototype
attribute</a>. For example,
-</p>
-<pre class="verbatim"> sub foo :prototype($) { $_[0] }
-</pre>
-<p>It is entirely possible for a subroutine to have both a prototype and
-a signature. They do different jobs: the prototype affects compilation
-of calls to the subroutine, and the signature puts argument values into
-lexical variables at runtime. You can therefore write
-</p>
-<pre class="verbatim"> sub foo ($left, $right) : prototype($$) {
- return $left + $right;
- }
-</pre>
-<p>The prototype attribute, and any other attributes, come after
-the signature.
-</p>
-<hr>
-<a name="perlsub-Private-Variables-via-my_0028_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Persistent-Private-Variables" accesskey="n"
rel="next">perlsub Persistent Private Variables</a>, Previous: <a
href="#perlsub-Signatures" accesskey="p" rel="prev">perlsub Signatures</a>, Up:
<a href="#perlsub-DESCRIPTION" accesskey="u" rel="up">perlsub DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Private-Variables-via-my_0028_0029"></a>
-<h4 class="subsection">73.3.2 Private Variables via my()</h4>
-
-<p>Synopsis:
-</p>
-<pre class="verbatim"> my $foo; # declare $foo lexically local
- my (@wid, %get); # declare list of variables local
- my $foo = "flurp"; # declare $foo lexical, and init it
- my @oof = @bar; # declare @oof lexical, and init it
- my $x : Foo = $y; # similar, with an attribute applied
-</pre>
-<p><strong>WARNING</strong>: The use of attribute lists on <code>my</code>
declarations is still
-evolving. The current semantics and interface are subject to change.
-See <a href="attributes.html#Top">(attributes)</a> and <a
href="Attribute-Handlers.html#Top">(Attribute-Handlers)</a>.
-</p>
-<p>The <code>my</code> operator declares the listed variables to be lexically
-confined to the enclosing block, conditional
(<code>if/unless/elsif/else</code>),
-loop (<code>for/foreach/while/until/continue</code>), subroutine,
<code>eval</code>,
-or <code>do/require/use</code>’d file. If more than one value is
listed, the
-list must be placed in parentheses. All listed elements must be
-legal lvalues. Only alphanumeric identifiers may be lexically
-scoped–magical built-ins like <code>$/</code> must currently be
<code>local</code>ized
-with <code>local</code> instead.
-</p>
-<p>Unlike dynamic variables created by the <code>local</code> operator, lexical
-variables declared with <code>my</code> are totally hidden from the outside
-world, including any called subroutines. This is true if it’s the
-same subroutine called from itself or elsewhere–every call gets
-its own copy.
-</p>
-<p>This doesn’t mean that a <code>my</code> variable declared in a
statically
-enclosing lexical scope would be invisible. Only dynamic scopes
-are cut off. For example, the <code>bumpx()</code> function below has access
-to the lexical $x variable because both the <code>my</code> and the
<code>sub</code>
-occurred at the same scope, presumably file scope.
-</p>
-<pre class="verbatim"> my $x = 10;
- sub bumpx { $x++ }
-</pre>
-<p>An <code>eval()</code>, however, can see lexical variables of the scope it
is
-being evaluated in, so long as the names aren’t hidden by declarations
within
-the <code>eval()</code> itself. See <a href="#perlref-NAME">perlref NAME</a>.
-</p>
-<p>The parameter list to my() may be assigned to if desired, which allows you
-to initialize your variables. (If no initializer is given for a
-particular variable, it is created with the undefined value.) Commonly
-this is used to name input parameters to a subroutine. Examples:
-</p>
-<pre class="verbatim"> $arg = "fred"; # "global"
variable
- $n = cube_root(27);
- print "$arg thinks the root is $n\n";
- fred thinks the root is 3
-
- sub cube_root {
- my $arg = shift; # name doesn't matter
- $arg **= 1/3;
- return $arg;
- }
-</pre>
-<p>The <code>my</code> is simply a modifier on something you might assign to.
So when
-you do assign to variables in its argument list, <code>my</code> doesn’t
-change whether those variables are viewed as a scalar or an array. So
-</p>
-<pre class="verbatim"> my ($foo) = <STDIN>; # WRONG?
- my @FOO = <STDIN>;
-</pre>
-<p>both supply a list context to the right-hand side, while
-</p>
-<pre class="verbatim"> my $foo = <STDIN>;
-</pre>
-<p>supplies a scalar context. But the following declares only one variable:
-</p>
-<pre class="verbatim"> my $foo, $bar = 1; # WRONG
-</pre>
-<p>That has the same effect as
-</p>
-<pre class="verbatim"> my $foo;
- $bar = 1;
-</pre>
-<p>The declared variable is not introduced (is not visible) until after
-the current statement. Thus,
-</p>
-<pre class="verbatim"> my $x = $x;
-</pre>
-<p>can be used to initialize a new $x with the value of the old $x, and
-the expression
-</p>
-<pre class="verbatim"> my $x = 123 and $x == 123
-</pre>
-<p>is false unless the old $x happened to have the value <code>123</code>.
-</p>
-<p>Lexical scopes of control structures are not bounded precisely by the
-braces that delimit their controlled blocks; control expressions are
-part of that scope, too. Thus in the loop
-</p>
-<pre class="verbatim"> while (my $line = <>) {
- $line = lc $line;
- } continue {
- print $line;
- }
-</pre>
-<p>the scope of $line extends from its declaration throughout the rest of
-the loop construct (including the <code>continue</code> clause), but not beyond
-it. Similarly, in the conditional
-</p>
-<pre class="verbatim"> if ((my $answer = <STDIN>) =~ /^yes$/i) {
- user_agrees();
- } elsif ($answer =~ /^no$/i) {
- user_disagrees();
- } else {
- chomp $answer;
- die "'$answer' is neither 'yes' nor 'no'";
- }
-</pre>
-<p>the scope of $answer extends from its declaration through the rest
-of that conditional, including any <code>elsif</code> and <code>else</code>
clauses,
-but not beyond it. See <a href="#perlsyn-Simple-Statements">perlsyn Simple
Statements</a> for information
-on the scope of variables in statements with modifiers.
-</p>
-<p>The <code>foreach</code> loop defaults to scoping its index variable
dynamically
-in the manner of <code>local</code>. However, if the index variable is
-prefixed with the keyword <code>my</code>, or if there is already a lexical
-by that name in scope, then a new lexical is created instead. Thus
-in the loop
-</p>
-<pre class="verbatim"> for my $i (1, 2, 3) {
- some_function();
- }
-</pre>
-<p>the scope of $i extends to the end of the loop, but not beyond it,
-rendering the value of $i inaccessible within <code>some_function()</code>.
-</p>
-<p>Some users may wish to encourage the use of lexically scoped variables.
-As an aid to catching implicit uses to package variables,
-which are always global, if you say
-</p>
-<pre class="verbatim"> use strict 'vars';
-</pre>
-<p>then any variable mentioned from there to the end of the enclosing
-block must either refer to a lexical variable, be predeclared via
-<code>our</code> or <code>use vars</code>, or else must be fully qualified
with the package name.
-A compilation error results otherwise. An inner block may countermand
-this with <code>no strict 'vars'</code>.
-</p>
-<p>A <code>my</code> has both a compile-time and a run-time effect. At compile
-time, the compiler takes notice of it. The principal usefulness
-of this is to quiet <code>use strict 'vars'</code>, but it is also essential
-for generation of closures as detailed in <a href="#perlref-NAME">perlref
NAME</a>. Actual
-initialization is delayed until run time, though, so it gets executed
-at the appropriate time, such as each time through a loop, for
-example.
-</p>
-<p>Variables declared with <code>my</code> are not part of any package and are
therefore
-never fully qualified with the package name. In particular, you’re not
-allowed to try to make a package variable (or other global) lexical:
-</p>
-<pre class="verbatim"> my $pack::var; # ERROR! Illegal syntax
-</pre>
-<p>In fact, a dynamic variable (also known as package or global variables)
-are still accessible using the fully qualified <code>::</code> notation even
while a
-lexical of the same name is also visible:
-</p>
-<pre class="verbatim"> package main;
- local $x = 10;
- my $x = 20;
- print "$x and $::x\n";
-</pre>
-<p>That will print out <code>20</code> and <code>10</code>.
-</p>
-<p>You may declare <code>my</code> variables at the outermost scope of a file
-to hide any such identifiers from the world outside that file. This
-is similar in spirit to C’s static variables when they are used at
-the file level. To do this with a subroutine requires the use of
-a closure (an anonymous function that accesses enclosing lexicals).
-If you want to create a private subroutine that cannot be called
-from outside that block, it can declare a lexical variable containing
-an anonymous sub reference:
-</p>
-<pre class="verbatim"> my $secret_version = '1.001-beta';
- my $secret_sub = sub { print $secret_version };
- &$secret_sub();
-</pre>
-<p>As long as the reference is never returned by any function within the
-module, no outside module can see the subroutine, because its name is not in
-any package’s symbol table. Remember that it’s not
<em>REALLY</em> called
-<code>$some_pack::secret_version</code> or anything; it’s just
$secret_version,
-unqualified and unqualifiable.
-</p>
-<p>This does not work with object methods, however; all object methods
-have to be in the symbol table of some package to be found. See
-<a href="#perlref-Function-Templates">perlref Function Templates</a> for
something of a work-around to
-this.
-</p>
-<hr>
-<a name="perlsub-Persistent-Private-Variables"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Temporary-Values-via-local_0028_0029" accesskey="n"
rel="next">perlsub Temporary Values via local()</a>, Previous: <a
href="#perlsub-Private-Variables-via-my_0028_0029" accesskey="p"
rel="prev">perlsub Private Variables via my()</a>, Up: <a
href="#perlsub-DESCRIPTION" accesskey="u" rel="up">perlsub DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Persistent-Private-Variables"></a>
-<h4 class="subsection">73.3.3 Persistent Private Variables</h4>
-
-<p>There are two ways to build persistent private variables in Perl 5.10.
-First, you can simply use the <code>state</code> feature. Or, you can use
closures,
-if you want to stay compatible with releases older than 5.10.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlsub-Persistent-variables-via-state_0028_0029" accesskey="1">perlsub
Persistent variables via state()</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Persistent-variables-with-closures" accesskey="2">perlsub
Persistent variables with closures</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlsub-Persistent-variables-via-state_0028_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Persistent-variables-with-closures" accesskey="n"
rel="next">perlsub Persistent variables with closures</a>, Up: <a
href="#perlsub-Persistent-Private-Variables" accesskey="u" rel="up">perlsub
Persistent Private Variables</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Persistent-variables-via-state_0028_0029"></a>
-<h4 class="subsubsection">73.3.3.1 Persistent variables via state()</h4>
-
-<p>Beginning with Perl 5.10.0, you can declare variables with the
<code>state</code>
-keyword in place of <code>my</code>. For that to work, though, you must have
-enabled that feature beforehand, either by using the <code>feature</code>
pragma, or
-by using <code>-E</code> on one-liners (see <a
href="feature.html#Top">(feature)</a>). Beginning with Perl 5.16,
-the <code>CORE::state</code> form does not require the
-<code>feature</code> pragma.
-</p>
-<p>The <code>state</code> keyword creates a lexical variable (following the
same scoping
-rules as <code>my</code>) that persists from one subroutine call to the next.
If a
-state variable resides inside an anonymous subroutine, then each copy of
-the subroutine has its own copy of the state variable. However, the value
-of the state variable will still persist between calls to the same copy of
-the anonymous subroutine. (Don’t forget that <code>sub { ... }</code>
creates a new
-subroutine each time it is executed.)
-</p>
-<p>For example, the following code maintains a private counter, incremented
-each time the gimme_another() function is called:
-</p>
-<pre class="verbatim"> use feature 'state';
- sub gimme_another { state $x; return ++$x }
-</pre>
-<p>And this example uses anonymous subroutines to create separate counters:
-</p>
-<pre class="verbatim"> use feature 'state';
- sub create_counter {
- return sub { state $x; return ++$x }
- }
-</pre>
-<p>Also, since <code>$x</code> is lexical, it can’t be reached or
modified by any Perl
-code outside.
-</p>
-<p>When combined with variable declaration, simple scalar assignment to
<code>state</code>
-variables (as in <code>state $x = 42</code>) is executed only the first time.
When such
-statements are evaluated subsequent times, the assignment is ignored. The
-behavior of this sort of assignment to non-scalar variables is undefined.
-</p>
-<hr>
-<a name="perlsub-Persistent-variables-with-closures"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlsub-Persistent-variables-via-state_0028_0029"
accesskey="p" rel="prev">perlsub Persistent variables via state()</a>, Up: <a
href="#perlsub-Persistent-Private-Variables" accesskey="u" rel="up">perlsub
Persistent Private Variables</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Persistent-variables-with-closures"></a>
-<h4 class="subsubsection">73.3.3.2 Persistent variables with closures</h4>
-
-<p>Just because a lexical variable is lexically (also called statically)
-scoped to its enclosing block, <code>eval</code>, or <code>do</code> FILE,
this doesn’t mean that
-within a function it works like a C static. It normally works more
-like a C auto, but with implicit garbage collection.
-</p>
-<p>Unlike local variables in C or C++, Perl’s lexical variables
don’t
-necessarily get recycled just because their scope has exited.
-If something more permanent is still aware of the lexical, it will
-stick around. So long as something else references a lexical, that
-lexical won’t be freed–which is as it should be. You
wouldn’t want
-memory being free until you were done using it, or kept around once you
-were done. Automatic garbage collection takes care of this for you.
-</p>
-<p>This means that you can pass back or save away references to lexical
-variables, whereas to return a pointer to a C auto is a grave error.
-It also gives us a way to simulate C’s function statics. Here’s a
-mechanism for giving a function private variables with both lexical
-scoping and a static lifetime. If you do want to create something like
-C’s static variables, just enclose the whole function in an extra block,
-and put the static variable outside the function but in the block.
-</p>
-<pre class="verbatim"> {
- my $secret_val = 0;
- sub gimme_another {
- return ++$secret_val;
- }
- }
- # $secret_val now becomes unreachable by the outside
- # world, but retains its value between calls to gimme_another
-</pre>
-<p>If this function is being sourced in from a separate file
-via <code>require</code> or <code>use</code>, then this is probably just fine.
If it’s
-all in the main program, you’ll need to arrange for the <code>my</code>
-to be executed early, either by putting the whole block above
-your main program, or more likely, placing merely a <code>BEGIN</code>
-code block around it to make sure it gets executed before your program
-starts to run:
-</p>
-<pre class="verbatim"> BEGIN {
- my $secret_val = 0;
- sub gimme_another {
- return ++$secret_val;
- }
- }
-</pre>
-<p>See <a
href="#perlmod-BEGIN_002c-UNITCHECK_002c-CHECK_002c-INIT-and-END">perlmod
BEGIN, UNITCHECK, CHECK, INIT and END</a> about the
-special triggered code blocks, <code>BEGIN</code>, <code>UNITCHECK</code>,
<code>CHECK</code>,
-<code>INIT</code> and <code>END</code>.
-</p>
-<p>If declared at the outermost scope (the file scope), then lexicals
-work somewhat like C’s file statics. They are available to all
-functions in that same file declared below them, but are inaccessible
-from outside that file. This strategy is sometimes used in modules
-to create private variables that the whole module can see.
-</p>
-<hr>
-<a name="perlsub-Temporary-Values-via-local_0028_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Lvalue-subroutines" accesskey="n" rel="next">perlsub
Lvalue subroutines</a>, Previous: <a
href="#perlsub-Persistent-Private-Variables" accesskey="p" rel="prev">perlsub
Persistent Private Variables</a>, Up: <a href="#perlsub-DESCRIPTION"
accesskey="u" rel="up">perlsub DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Temporary-Values-via-local_0028_0029"></a>
-<h4 class="subsection">73.3.4 Temporary Values via local()</h4>
-
-<p><strong>WARNING</strong>: In general, you should be using <code>my</code>
instead of <code>local</code>, because
-it’s faster and safer. Exceptions to this include the global punctuation
-variables, global filehandles and formats, and direct manipulation of the
-Perl symbol table itself. <code>local</code> is mostly used when the current
value
-of a variable must be visible to called subroutines.
-</p>
-<p>Synopsis:
-</p>
-<pre class="verbatim"> # localization of values
-
- local $foo; # make $foo dynamically local
- local (@wid, %get); # make list of variables local
- local $foo = "flurp"; # make $foo dynamic, and init it
- local @oof = @bar; # make @oof dynamic, and init it
-
- local $hash{key} = "val"; # sets a local value for this hash
entry
- delete local $hash{key}; # delete this entry for the current block
- local ($cond ? $v1 : $v2); # several types of lvalues support
- # localization
-
- # localization of symbols
-
- local *FH; # localize $FH, @FH, %FH, &FH ...
- local *merlyn = *randal; # now $merlyn is really $randal, plus
- # @merlyn is really @randal, etc
- local *merlyn = 'randal'; # SAME THING: promote 'randal' to *randal
- local *merlyn = \$randal; # just alias $merlyn, not @merlyn etc
-</pre>
-<p>A <code>local</code> modifies its listed variables to be "local"
to the
-enclosing block, <code>eval</code>, or <code>do FILE</code>–and to
<em>any subroutine
-called from within that block</em>. A <code>local</code> just gives temporary
-values to global (meaning package) variables. It does <em>not</em> create
-a local variable. This is known as dynamic scoping. Lexical scoping
-is done with <code>my</code>, which works more like C’s auto
declarations.
-</p>
-<p>Some types of lvalues can be localized as well: hash and array elements
-and slices, conditionals (provided that their result is always
-localizable), and symbolic references. As for simple variables, this
-creates new, dynamically scoped values.
-</p>
-<p>If more than one variable or expression is given to <code>local</code>,
they must be
-placed in parentheses. This operator works
-by saving the current values of those variables in its argument list on a
-hidden stack and restoring them upon exiting the block, subroutine, or
-eval. This means that called subroutines can also reference the local
-variable, but not the global one. The argument list may be assigned to if
-desired, which allows you to initialize your local variables. (If no
-initializer is given for a particular variable, it is created with an
-undefined value.)
-</p>
-<p>Because <code>local</code> is a run-time operator, it gets executed each
time
-through a loop. Consequently, it’s more efficient to localize your
-variables outside the loop.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlsub-Grammatical-note-on-local_0028_0029" accesskey="1">perlsub
Grammatical note on local()</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Localization-of-special-variables" accesskey="2">perlsub
Localization of special variables</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Localization-of-globs" accesskey="3">perlsub Localization of
globs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Localization-of-elements-of-composite-types"
accesskey="4">perlsub Localization of elements of composite
types</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsub-Localized-deletion-of-elements-of-composite-types"
accesskey="5">perlsub Localized deletion of elements of composite
types</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlsub-Grammatical-note-on-local_0028_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Localization-of-special-variables" accesskey="n"
rel="next">perlsub Localization of special variables</a>, Up: <a
href="#perlsub-Temporary-Values-via-local_0028_0029" accesskey="u"
rel="up">perlsub Temporary Values via local()</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Grammatical-note-on-local_0028_0029"></a>
-<h4 class="subsubsection">73.3.4.1 Grammatical note on local()</h4>
-
-<p>A <code>local</code> is simply a modifier on an lvalue expression. When
you assign to
-a <code>local</code>ized variable, the <code>local</code> doesn’t change
whether its list is viewed
-as a scalar or an array. So
-</p>
-<pre class="verbatim"> local($foo) = <STDIN>;
- local @FOO = <STDIN>;
-</pre>
-<p>both supply a list context to the right-hand side, while
-</p>
-<pre class="verbatim"> local $foo = <STDIN>;
-</pre>
-<p>supplies a scalar context.
-</p>
-<hr>
-<a name="perlsub-Localization-of-special-variables"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Localization-of-globs" accesskey="n"
rel="next">perlsub Localization of globs</a>, Previous: <a
href="#perlsub-Grammatical-note-on-local_0028_0029" accesskey="p"
rel="prev">perlsub Grammatical note on local()</a>, Up: <a
href="#perlsub-Temporary-Values-via-local_0028_0029" accesskey="u"
rel="up">perlsub Temporary Values via local()</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Localization-of-special-variables"></a>
-<h4 class="subsubsection">73.3.4.2 Localization of special variables</h4>
-
-<p>If you localize a special variable, you’ll be giving a new value to
it,
-but its magic won’t go away. That means that all side-effects related
-to this magic still work with the localized value.
-</p>
-<p>This feature allows code like this to work :
-</p>
-<pre class="verbatim"> # Read the whole contents of FILE in $slurp
- { local $/ = undef; $slurp = <FILE>; }
-</pre>
-<p>Note, however, that this restricts localization of some values ; for
-example, the following statement dies, as of perl 5.10.0, with an error
-<em>Modification of a read-only value attempted</em>, because the $1 variable
is
-magical and read-only :
-</p>
-<pre class="verbatim"> local $1 = 2;
-</pre>
-<p>One exception is the default scalar variable: starting with perl 5.14
-<code>local($_)</code> will always strip all magic from $_, to make it possible
-to safely reuse $_ in a subroutine.
-</p>
-<p><strong>WARNING</strong>: Localization of tied arrays and hashes does not
currently
-work as described.
-This will be fixed in a future release of Perl; in the meantime, avoid
-code that relies on any particular behavior of localising tied arrays
-or hashes (localising individual elements is still okay).
-See <a
href="perl58delta.html#Localising-Tied-Arrays-and-Hashes-Is-Broken">(perl58delta)Localising
Tied Arrays and Hashes Is Broken</a> for more
-details.
-</p>
-<hr>
-<a name="perlsub-Localization-of-globs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Localization-of-elements-of-composite-types"
accesskey="n" rel="next">perlsub Localization of elements of composite
types</a>, Previous: <a href="#perlsub-Localization-of-special-variables"
accesskey="p" rel="prev">perlsub Localization of special variables</a>, Up: <a
href="#perlsub-Temporary-Values-via-local_0028_0029" accesskey="u"
rel="up">perlsub Temporary Values via local()</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Localization-of-globs"></a>
-<h4 class="subsubsection">73.3.4.3 Localization of globs</h4>
-
-<p>The construct
-</p>
-<pre class="verbatim"> local *name;
-</pre>
-<p>creates a whole new symbol table entry for the glob <code>name</code> in the
-current package. That means that all variables in its glob slot ($name,
address@hidden, %name, &name, and the <code>name</code> filehandle) are
dynamically reset.
-</p>
-<p>This implies, among other things, that any magic eventually carried by
-those variables is locally lost. In other words, saying <code>local */</code>
-will not have any effect on the internal value of the input record
-separator.
-</p>
-<hr>
-<a name="perlsub-Localization-of-elements-of-composite-types"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Localized-deletion-of-elements-of-composite-types"
accesskey="n" rel="next">perlsub Localized deletion of elements of composite
types</a>, Previous: <a href="#perlsub-Localization-of-globs" accesskey="p"
rel="prev">perlsub Localization of globs</a>, Up: <a
href="#perlsub-Temporary-Values-via-local_0028_0029" accesskey="u"
rel="up">perlsub Temporary Values via local()</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Localization-of-elements-of-composite-types"></a>
-<h4 class="subsubsection">73.3.4.4 Localization of elements of composite
types</h4>
-
-<p>It’s also worth taking a moment to explain what happens when you
-<code>local</code>ize a member of a composite type (i.e. an array or hash
element).
-In this case, the element is <code>local</code>ized <em>by name</em>. This
means that
-when the scope of the <code>local()</code> ends, the saved value will be
-restored to the hash element whose key was named in the <code>local()</code>,
or
-the array element whose index was named in the <code>local()</code>. If that
-element was deleted while the <code>local()</code> was in effect (e.g. by a
-<code>delete()</code> from a hash or a <code>shift()</code> of an array), it
will spring
-back into existence, possibly extending an array and filling in the
-skipped elements with <code>undef</code>. For instance, if you say
-</p>
-<pre class="verbatim"> %hash = ( 'This' => 'is', 'a' => 'test' );
- @ary = ( 0..5 );
- {
- local($ary[5]) = 6;
- local($hash{'a'}) = 'drill';
- while (my $e = pop(@ary)) {
- print "$e . . .\n";
- last unless $e > 3;
- }
- if (@ary) {
- $hash{'only a'} = 'test';
- delete $hash{'a'};
- }
- }
- print join(' ', map { "$_ $hash{$_}" } sort keys
%hash),".\n";
- print "The array has ",scalar(@ary)," elements: ",
- join(', ', map { defined $_ ? $_ : 'undef' } @ary),"\n";
-</pre>
-<p>Perl will print
-</p>
-<pre class="verbatim"> 6 . . .
- 4 . . .
- 3 . . .
- This is a test only a test.
- The array has 6 elements: 0, 1, 2, undef, undef, 5
-</pre>
-<p>The behavior of local() on non-existent members of composite
-types is subject to change in future.
-</p>
-<hr>
-<a name="perlsub-Localized-deletion-of-elements-of-composite-types"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlsub-Localization-of-elements-of-composite-types"
accesskey="p" rel="prev">perlsub Localization of elements of composite
types</a>, Up: <a href="#perlsub-Temporary-Values-via-local_0028_0029"
accesskey="u" rel="up">perlsub Temporary Values via local()</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Localized-deletion-of-elements-of-composite-types"></a>
-<h4 class="subsubsection">73.3.4.5 Localized deletion of elements of composite
types</h4>
-
-<p>You can use the <code>delete local $array[$idx]</code> and <code>delete
local $hash{key}</code>
-constructs to delete a composite type entry for the current block and restore
-it when it ends. They return the array/hash value before the localization,
-which means that they are respectively equivalent to
-</p>
-<pre class="verbatim"> do {
- my $val = $array[$idx];
- local $array[$idx];
- delete $array[$idx];
- $val
- }
-</pre>
-<p>and
-</p>
-<pre class="verbatim"> do {
- my $val = $hash{key};
- local $hash{key};
- delete $hash{key};
- $val
- }
-</pre>
-<p>except that for those the <code>local</code> is
-scoped to the <code>do</code> block. Slices are
-also accepted.
-</p>
-<pre class="verbatim"> my %hash = (
- a => [ 7, 8, 9 ],
- b => 1,
- )
-
- {
- my $a = delete local $hash{a};
- # $a is [ 7, 8, 9 ]
- # %hash is (b => 1)
-
- {
- my @nums = delete local @$a[0, 2]
- # @nums is (7, 9)
- # $a is [ undef, 8 ]
-
- $a[0] = 999; # will be erased when the scope ends
- }
- # $a is back to [ 7, 8, 9 ]
-
- }
- # %hash is back to its original state
-</pre>
-<hr>
-<a name="perlsub-Lvalue-subroutines"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Lexical-Subroutines" accesskey="n" rel="next">perlsub
Lexical Subroutines</a>, Previous: <a
href="#perlsub-Temporary-Values-via-local_0028_0029" accesskey="p"
rel="prev">perlsub Temporary Values via local()</a>, Up: <a
href="#perlsub-DESCRIPTION" accesskey="u" rel="up">perlsub DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Lvalue-subroutines"></a>
-<h4 class="subsection">73.3.5 Lvalue subroutines</h4>
-
-<p>It is possible to return a modifiable value from a subroutine.
-To do this, you have to declare the subroutine to return an lvalue.
-</p>
-<pre class="verbatim"> my $val;
- sub canmod : lvalue {
- $val; # or: return $val;
- }
- sub nomod {
- $val;
- }
-
- canmod() = 5; # assigns to $val
- nomod() = 5; # ERROR
-</pre>
-<p>The scalar/list context for the subroutine and for the right-hand
-side of assignment is determined as if the subroutine call is replaced
-by a scalar. For example, consider:
-</p>
-<pre class="verbatim"> data(2,3) = get_data(3,4);
-</pre>
-<p>Both subroutines here are called in a scalar context, while in:
-</p>
-<pre class="verbatim"> (data(2,3)) = get_data(3,4);
-</pre>
-<p>and in:
-</p>
-<pre class="verbatim"> (data(2),data(3)) = get_data(3,4);
-</pre>
-<p>all the subroutines are called in a list context.
-</p>
-<p>Lvalue subroutines are convenient, but you have to keep in mind that,
-when used with objects, they may violate encapsulation. A normal
-mutator can check the supplied argument before setting the attribute
-it is protecting, an lvalue subroutine cannot. If you require any
-special processing when storing and retrieving the values, consider
-using the CPAN module Sentinel or something similar.
-</p>
-<hr>
-<a name="perlsub-Lexical-Subroutines"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Passing-Symbol-Table-Entries-_0028typeglobs_0029"
accesskey="n" rel="next">perlsub Passing Symbol Table Entries (typeglobs)</a>,
Previous: <a href="#perlsub-Lvalue-subroutines" accesskey="p"
rel="prev">perlsub Lvalue subroutines</a>, Up: <a href="#perlsub-DESCRIPTION"
accesskey="u" rel="up">perlsub DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Lexical-Subroutines"></a>
-<h4 class="subsection">73.3.6 Lexical Subroutines</h4>
-
-<p><strong>WARNING</strong>: Lexical subroutines are still experimental. The
feature may be
-modified or removed in future versions of Perl.
-</p>
-<p>Lexical subroutines are only available under the <code>use feature
-'lexical_subs'</code> pragma, which produces a warning unless the
-"experimental::lexical_subs" warnings category is disabled.
-</p>
-<p>Beginning with Perl 5.18, you can declare a private subroutine with
<code>my</code>
-or <code>state</code>. As with state variables, the <code>state</code>
keyword is only
-available under <code>use feature 'state'</code> or <code>use 5.010</code> or
higher.
-</p>
-<p>These subroutines are only visible within the block in which they are
-declared, and only after that declaration:
-</p>
-<pre class="verbatim"> no warnings "experimental::lexical_subs";
- use feature 'lexical_subs';
-
- foo(); # calls the package/global subroutine
- state sub foo {
- foo(); # also calls the package subroutine
- }
- foo(); # calls "state" sub
- my $ref = \&foo; # take a reference to "state" sub
-
- my sub bar { ... }
- bar(); # calls "my" sub
-</pre>
-<p>To use a lexical subroutine from inside the subroutine itself, you must
-predeclare it. The <code>sub foo {...}</code> subroutine definition syntax
respects
-any previous <code>my sub;</code> or <code>state sub;</code> declaration.
-</p>
-<pre class="verbatim"> my sub baz; # predeclaration
- sub baz { # define the "my" sub
- baz(); # recursive call
- }
-</pre>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlsub-state-sub-vs-my-sub" accesskey="1">perlsub <code>state
sub</code> vs <code>my sub</code></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsub-our-subroutines"
accesskey="2">perlsub <code>our</code>
subroutines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlsub-state-sub-vs-my-sub"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-our-subroutines" accesskey="n" rel="next">perlsub
<code>our</code> subroutines</a>, Up: <a href="#perlsub-Lexical-Subroutines"
accesskey="u" rel="up">perlsub Lexical Subroutines</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="state-sub-vs-my-sub"></a>
-<h4 class="subsubsection">73.3.6.1 <code>state sub</code> vs <code>my
sub</code></h4>
-
-<p>What is the difference between "state" subs and "my"
subs? Each time that
-execution enters a block when "my" subs are declared, a new copy of
each
-sub is created. "State" subroutines persist from one execution of
the
-containing block to the next.
-</p>
-<p>So, in general, "state" subroutines are faster. But
"my" subs are
-necessary if you want to create closures:
-</p>
-<pre class="verbatim"> no warnings "experimental::lexical_subs";
- use feature 'lexical_subs';
-
- sub whatever {
- my $x = shift;
- my sub inner {
- ... do something with $x ...
- }
- inner();
- }
-</pre>
-<p>In this example, a new <code>$x</code> is created when
<code>whatever</code> is called, and
-also a new <code>inner</code>, which can see the new <code>$x</code>. A
"state" sub will only
-see the <code>$x</code> from the first call to <code>whatever</code>.
-</p>
-<hr>
-<a name="perlsub-our-subroutines"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlsub-state-sub-vs-my-sub" accesskey="p"
rel="prev">perlsub <code>state sub</code> vs <code>my sub</code></a>, Up: <a
href="#perlsub-Lexical-Subroutines" accesskey="u" rel="up">perlsub Lexical
Subroutines</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="our-subroutines"></a>
-<h4 class="subsubsection">73.3.6.2 <code>our</code> subroutines</h4>
-
-<p>Like <code>our $variable</code>, <code>our sub</code> creates a lexical
alias to the package
-subroutine of the same name.
-</p>
-<p>The two main uses for this are to switch back to using the package sub
-inside an inner scope:
-</p>
-<pre class="verbatim"> no warnings "experimental::lexical_subs";
- use feature 'lexical_subs';
-
- sub foo { ... }
-
- sub bar {
- my sub foo { ... }
- {
- # need to use the outer foo here
- our sub foo;
- foo();
- }
- }
-</pre>
-<p>and to make a subroutine visible to other packages in the same scope:
-</p>
-<pre class="verbatim"> package MySneakyModule;
-
- no warnings "experimental::lexical_subs";
- use feature 'lexical_subs';
-
- our sub do_something { ... }
-
- sub do_something_with_caller {
- package DB;
- () = caller 1; # sets @DB::args
- do_something(@args); # uses MySneakyModule::do_something
- }
-</pre>
-<hr>
-<a name="perlsub-Passing-Symbol-Table-Entries-_0028typeglobs_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-When-to-Still-Use-local_0028_0029" accesskey="n"
rel="next">perlsub When to Still Use local()</a>, Previous: <a
href="#perlsub-Lexical-Subroutines" accesskey="p" rel="prev">perlsub Lexical
Subroutines</a>, Up: <a href="#perlsub-DESCRIPTION" accesskey="u"
rel="up">perlsub DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Passing-Symbol-Table-Entries-_0028typeglobs_0029"></a>
-<h4 class="subsection">73.3.7 Passing Symbol Table Entries (typeglobs)</h4>
-
-<p><strong>WARNING</strong>: The mechanism described in this section was
originally
-the only way to simulate pass-by-reference in older versions of
-Perl. While it still works fine in modern versions, the new reference
-mechanism is generally easier to work with. See below.
-</p>
-<p>Sometimes you don’t want to pass the value of an array to a subroutine
-but rather the name of it, so that the subroutine can modify the global
-copy of it rather than working with a local copy. In perl you can
-refer to all objects of a particular name by prefixing the name
-with a star: <code>*foo</code>. This is often known as a
"typeglob", because the
-star on the front can be thought of as a wildcard match for all the
-funny prefix characters on variables and subroutines and such.
-</p>
-<p>When evaluated, the typeglob produces a scalar value that represents
-all the objects of that name, including any filehandle, format, or
-subroutine. When assigned to, it causes the name mentioned to refer to
-whatever <code>*</code> value was assigned to it. Example:
-</p>
-<pre class="verbatim"> sub doubleary {
- local(*someary) = @_;
- foreach $elem (@someary) {
- $elem *= 2;
- }
- }
- doubleary(*foo);
- doubleary(*bar);
-</pre>
-<p>Scalars are already passed by reference, so you can modify
-scalar arguments without using this mechanism by referring explicitly
-to <code>$_[0]</code> etc. You can modify all the elements of an array by
passing
-all the elements as scalars, but you have to use the <code>*</code> mechanism
(or
-the equivalent reference mechanism) to <code>push</code>, <code>pop</code>, or
change the size of
-an array. It will certainly be faster to pass the typeglob (or reference).
-</p>
-<p>Even if you don’t want to modify an array, this mechanism is useful
for
-passing multiple arrays in a single LIST, because normally the LIST
-mechanism will merge all the array values so that you can’t extract out
-the individual arrays. For more on typeglobs, see
-<a href="#perldata-Typeglobs-and-Filehandles">perldata Typeglobs and
Filehandles</a>.
-</p>
-<hr>
-<a name="perlsub-When-to-Still-Use-local_0028_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Pass-by-Reference" accesskey="n" rel="next">perlsub
Pass by Reference</a>, Previous: <a
href="#perlsub-Passing-Symbol-Table-Entries-_0028typeglobs_0029" accesskey="p"
rel="prev">perlsub Passing Symbol Table Entries (typeglobs)</a>, Up: <a
href="#perlsub-DESCRIPTION" accesskey="u" rel="up">perlsub DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="When-to-Still-Use-local_0028_0029"></a>
-<h4 class="subsection">73.3.8 When to Still Use local()</h4>
-
-<p>Despite the existence of <code>my</code>, there are still three places
where the
-<code>local</code> operator still shines. In fact, in these three places, you
-<em>must</em> use <code>local</code> instead of <code>my</code>.
-</p>
-<ol>
-<li> You need to give a global variable a temporary value, especially $_.
-
-<p>The global variables, like <code>@ARGV</code> or the punctuation variables,
must be
-<code>local</code>ized with <code>local()</code>. This block reads in
<samp>/etc/motd</samp>, and splits
-it up into chunks separated by lines of equal signs, which are placed
-in <code>@Fields</code>.
-</p>
-<pre class="verbatim"> {
- local @ARGV = ("/etc/motd");
- local $/ = undef;
- local $_ = <>;
- @Fields = split /^\s*=+\s*$/;
- }
-</pre>
-<p>It particular, it’s important to <code>local</code>ize $_ in any
routine that assigns
-to it. Look out for implicit assignments in <code>while</code> conditionals.
-</p>
-</li><li> You need to create a local file or directory handle or a local
function.
-
-<p>A function that needs a filehandle of its own must use
-<code>local()</code> on a complete typeglob. This can be used to create new
symbol
-table entries:
-</p>
-<pre class="verbatim"> sub ioqueue {
- local (*READER, *WRITER); # not my!
- pipe (READER, WRITER) or die "pipe: $!";
- return (*READER, *WRITER);
- }
- ($head, $tail) = ioqueue();
-</pre>
-<p>See the Symbol module for a way to create anonymous symbol table
-entries.
-</p>
-<p>Because assignment of a reference to a typeglob creates an alias, this
-can be used to create what is effectively a local function, or at least,
-a local alias.
-</p>
-<pre class="verbatim"> {
- local *grow = \&shrink; # only until this block exits
- grow(); # really calls shrink()
- move(); # if move() grow()s, it shrink()s too
- }
- grow(); # get the real grow() again
-</pre>
-<p>See <a href="#perlref-Function-Templates">perlref Function Templates</a>
for more about manipulating
-functions by name in this way.
-</p>
-</li><li> You want to temporarily change just one element of an array or hash.
-
-<p>You can <code>local</code>ize just one element of an aggregate. Usually
this
-is done on dynamics:
-</p>
-<pre class="verbatim"> {
- local $SIG{INT} = 'IGNORE';
- funct(); # uninterruptible
- }
- # interruptibility automatically restored here
-</pre>
-<p>But it also works on lexically declared aggregates.
-</p>
-</li></ol>
-
-<hr>
-<a name="perlsub-Pass-by-Reference"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Prototypes" accesskey="n" rel="next">perlsub
Prototypes</a>, Previous: <a href="#perlsub-When-to-Still-Use-local_0028_0029"
accesskey="p" rel="prev">perlsub When to Still Use local()</a>, Up: <a
href="#perlsub-DESCRIPTION" accesskey="u" rel="up">perlsub DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Pass-by-Reference"></a>
-<h4 class="subsection">73.3.9 Pass by Reference</h4>
-
-<p>If you want to pass more than one array or hash into a function–or
-return them from it–and have them maintain their integrity, then
-you’re going to have to use an explicit pass-by-reference. Before you
-do that, you need to understand references as detailed in <a
href="#perlref-NAME">perlref NAME</a>.
-This section may not make much sense to you otherwise.
-</p>
-<p>Here are a few simple examples. First, let’s pass in several arrays
-to a function and have it <code>pop</code> all of then, returning a new list
-of all their former last elements:
-</p>
-<pre class="verbatim"> @tailings = popmany ( address@hidden,
address@hidden, address@hidden, address@hidden );
-
- sub popmany {
- my $aref;
- my @retlist = ();
- foreach $aref ( @_ ) {
- push @retlist, pop @$aref;
- }
- return @retlist;
- }
-</pre>
-<p>Here’s how you might write a function that returns a
-list of keys occurring in all the hashes passed to it:
-</p>
-<pre class="verbatim"> @common = inter( \%foo, \%bar, \%joe );
- sub inter {
- my ($k, $href, %seen); # locals
- foreach $href (@_) {
- while ( $k = each %$href ) {
- $seen{$k}++;
- }
- }
- return grep { $seen{$_} == @_ } keys %seen;
- }
-</pre>
-<p>So far, we’re using just the normal list return mechanism.
-What happens if you want to pass or return a hash? Well,
-if you’re using only one of them, or you don’t mind them
-concatenating, then the normal calling convention is ok, although
-a little expensive.
-</p>
-<p>Where people get into trouble is here:
-</p>
-<pre class="verbatim"> (@a, @b) = func(@c, @d);
-or
- (%a, %b) = func(%c, %d);
-</pre>
-<p>That syntax simply won’t work. It sets just <code>@a</code> or
<code>%a</code> and
-clears the <code>@b</code> or <code>%b</code>. Plus the function didn’t
get passed
-into two separate arrays or hashes: it got one long list in <code>@_</code>,
-as always.
-</p>
-<p>If you can arrange for everyone to deal with this through references,
it’s
-cleaner code, although not so nice to look at. Here’s a function that
-takes two array references as arguments, returning the two array elements
-in order of how many elements they have in them:
-</p>
-<pre class="verbatim"> ($aref, $bref) = func(address@hidden,
address@hidden);
- print "@$aref has more than @$bref\n";
- sub func {
- my ($cref, $dref) = @_;
- if (@$cref > @$dref) {
- return ($cref, $dref);
- } else {
- return ($dref, $cref);
- }
- }
-</pre>
-<p>It turns out that you can actually do this also:
-</p>
-<pre class="verbatim"> (*a, *b) = func(address@hidden, address@hidden);
- print "@a has more than @b\n";
- sub func {
- local (*c, *d) = @_;
- if (@c > @d) {
- return (address@hidden, address@hidden);
- } else {
- return (address@hidden, address@hidden);
- }
- }
-</pre>
-<p>Here we’re using the typeglobs to do symbol table aliasing.
It’s
-a tad subtle, though, and also won’t work if you’re using
<code>my</code>
-variables, because only globals (even in disguise as <code>local</code>s)
-are in the symbol table.
-</p>
-<p>If you’re passing around filehandles, you could usually just use the
bare
-typeglob, like <code>*STDOUT</code>, but typeglobs references work, too.
-For example:
-</p>
-<pre class="verbatim"> splutter(\*STDOUT);
- sub splutter {
- my $fh = shift;
- print $fh "her um well a hmmm\n";
- }
-
- $rec = get_rec(\*STDIN);
- sub get_rec {
- my $fh = shift;
- return scalar <$fh>;
- }
-</pre>
-<p>If you’re planning on generating new filehandles, you could do this.
-Notice to pass back just the bare *FH, not its reference.
-</p>
-<pre class="verbatim"> sub openit {
- my $path = shift;
- local *FH;
- return open (FH, $path) ? *FH : undef;
- }
-</pre>
-<hr>
-<a name="perlsub-Prototypes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Constant-Functions" accesskey="n" rel="next">perlsub
Constant Functions</a>, Previous: <a href="#perlsub-Pass-by-Reference"
accesskey="p" rel="prev">perlsub Pass by Reference</a>, Up: <a
href="#perlsub-DESCRIPTION" accesskey="u" rel="up">perlsub DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Prototypes"></a>
-<h4 class="subsection">73.3.10 Prototypes</h4>
-
-<p>Perl supports a very limited kind of compile-time argument checking
-using function prototyping. This can be declared in either the PROTO
-section or with a <a
href="attributes.html#Built_002din-Attributes">(attributes)prototype
attribute</a>.
-If you declare either of
-</p>
-<pre class="verbatim"> sub mypush (+@)
- sub mypush :prototype(+@)
-</pre>
-<p>then <code>mypush()</code> takes arguments exactly like <code>push()</code>
does.
-</p>
-<p>If subroutine signatures are enabled (see <a
href="#perlsub-Signatures">Signatures</a>), then
-the shorter PROTO syntax is unavailable, because it would clash with
-signatures. In that case, a prototype can only be declared in the form
-of an attribute.
-</p>
-<p>The
-function declaration must be visible at compile time. The prototype
-affects only interpretation of new-style calls to the function,
-where new-style is defined as not using the <code>&</code> character. In
-other words, if you call it like a built-in function, then it behaves
-like a built-in function. If you call it like an old-fashioned
-subroutine, then it behaves like an old-fashioned subroutine. It
-naturally falls out from this rule that prototypes have no influence
-on subroutine references like <code>\&foo</code> or on indirect subroutine
-calls like <code>&{$subref}</code> or <code>$subref->()</code>.
-</p>
-<p>Method calls are not influenced by prototypes either, because the
-function to be called is indeterminate at compile time, since
-the exact code called depends on inheritance.
-</p>
-<p>Because the intent of this feature is primarily to let you define
-subroutines that work like built-in functions, here are prototypes
-for some other functions that parse almost exactly like the
-corresponding built-in.
-</p>
-<pre class="verbatim"> Declared as Called as
-
- sub mylink ($$) mylink $old, $new
- sub myvec ($$$) myvec $var, $offset, 1
- sub myindex ($$;$) myindex &getstring, "substr"
- 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 myopen (*;$) myopen HANDLE, $name
- sub mypipe (**) mypipe READHANDLE, WRITEHANDLE
- sub mygrep (&@) mygrep { /foo/ } $a, $b, $c
- sub myrand (;$) myrand 42
- sub mytime () mytime
-</pre>
-<p>Any backslashed prototype character represents an actual argument
-that must start with that character (optionally preceded by <code>my</code>,
-<code>our</code> or <code>local</code>), with the exception of <code>$</code>,
which will
-accept any scalar lvalue expression, such as <code>$foo = 7</code> or
-<code>my_function()->[0]</code>. The value passed as part of
<code>@_</code> will be a
-reference to the actual argument given in the subroutine call,
-obtained by applying <code>\</code> to that argument.
-</p>
-<p>You can use the <code>\[]</code> backslash group notation to specify more
than one
-allowed argument type. For example:
-</p>
-<pre class="verbatim"> sub myref (address@hidden&*])
-</pre>
-<p>will allow calling myref() as
-</p>
-<pre class="verbatim"> myref $var
- myref @array
- myref %hash
- myref &sub
- myref *glob
-</pre>
-<p>and the first argument of myref() will be a reference to
-a scalar, an array, a hash, a code, or a glob.
-</p>
-<p>Unbackslashed prototype characters have special meanings. Any
-unbackslashed <code>@</code> or <code>%</code> eats all remaining arguments,
and forces
-list context. An argument represented by <code>$</code> forces scalar
context. An
-<code>&</code> requires an anonymous subroutine, which, if passed as the
first
-argument, does not require the <code>sub</code> keyword or a subsequent comma.
-</p>
-<p>A <code>*</code> allows the subroutine to accept a bareword, constant,
scalar expression,
-typeglob, or a reference to a typeglob in that slot. The value will be
-available to the subroutine either as a simple scalar, or (in the latter
-two cases) as a reference to the typeglob. If you wish to always convert
-such arguments to a typeglob reference, use Symbol::qualify_to_ref() as
-follows:
-</p>
-<pre class="verbatim"> use Symbol 'qualify_to_ref';
-
- sub foo (*) {
- my $fh = qualify_to_ref(shift, caller);
- ...
- }
-</pre>
-<p>The <code>+</code> prototype is a special alternative to <code>$</code>
that will act like
-<code>address@hidden</code> 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:
-</p>
-<pre class="verbatim"> sub mypush (+@) {
- my $aref = shift;
- die "Not an array or arrayref" unless ref $aref eq 'ARRAY';
- push @$aref, @_;
- }
-</pre>
-<p>When using the <code>+</code> prototype, your function must check that the
argument
-is of an acceptable type.
-</p>
-<p>A semicolon (<code>;</code>) separates mandatory arguments from optional
arguments.
-It is redundant before <code>@</code> or <code>%</code>, which gobble up
everything else.
-</p>
-<p>As the last character of a prototype, or just before a semicolon, a
<code>@</code>
-or a <code>%</code>, you can use <code>_</code> in place of <code>$</code>: if
this argument is not
-provided, <code>$_</code> will be used instead.
-</p>
-<p>Note how the last three examples in the table above are treated
-specially by the parser. <code>mygrep()</code> is parsed as a true list
-operator, <code>myrand()</code> is parsed as a true unary operator with unary
-precedence the same as <code>rand()</code>, and <code>mytime()</code> is truly
without
-arguments, just like <code>time()</code>. That is, if you say
-</p>
-<pre class="verbatim"> mytime +2;
-</pre>
-<p>you’ll get <code>mytime() + 2</code>, not <code>mytime(2)</code>,
which is how it would be parsed
-without a prototype. If you want to force a unary function to have the
-same precedence as a list operator, add <code>;</code> to the end of the
prototype:
-</p>
-<pre class="verbatim"> sub mygetprotobynumber($;);
- mygetprotobynumber $a > $b; # parsed as mygetprotobynumber($a > $b)
-</pre>
-<p>The interesting thing about <code>&</code> is that you can generate new
syntax with it,
-provided it’s in the initial position:
-</p>
-<pre class="verbatim"> sub try (&@) {
- my($try,$catch) = @_;
- eval { &$try };
- if ($@) {
- local $_ = $@;
- &$catch;
- }
- }
- sub catch (&) { $_[0] }
-
- try {
- die "phooey";
- } catch {
- /phooey/ and print "unphooey\n";
- };
-</pre>
-<p>That prints <code>"unphooey"</code>. (Yes, there are still
unresolved
-issues having to do with visibility of <code>@_</code>. I’m ignoring
that
-question for the moment. (But note that if we make <code>@_</code> lexically
-scoped, those anonymous subroutines can act like closures... (Gee,
-is this sounding a little Lispish? (Never mind.))))
-</p>
-<p>And here’s a reimplementation of the Perl <code>grep</code> operator:
-</p>
-<pre class="verbatim"> sub mygrep (&@) {
- my $code = shift;
- my @result;
- foreach $_ (@_) {
- push(@result, $_) if &$code;
- }
- @result;
- }
-</pre>
-<p>Some folks would prefer full alphanumeric prototypes. Alphanumerics have
-been intentionally left out of prototypes for the express purpose of
-someday in the future adding named, formal parameters. The current
-mechanism’s main goal is to let module writers provide better diagnostics
-for module users. Larry feels the notation quite understandable to Perl
-programmers, and that it will not intrude greatly upon the meat of the
-module, nor make it harder to read. The line noise is visually
-encapsulated into a small pill that’s easy to swallow.
-</p>
-<p>If you try to use an alphanumeric sequence in a prototype you will
-generate an optional warning - "Illegal character in prototype...".
-Unfortunately earlier versions of Perl allowed the prototype to be
-used as long as its prefix was a valid prototype. The warning may be
-upgraded to a fatal error in a future version of Perl once the
-majority of offending code is fixed.
-</p>
-<p>It’s probably best to prototype new functions, not retrofit
prototyping
-into older ones. That’s because you must be especially careful about
-silent impositions of differing list versus scalar contexts. For example,
-if you decide that a function should take just one parameter, like this:
-</p>
-<pre class="verbatim"> sub func ($) {
- my $n = shift;
- print "you gave me $n\n";
- }
-</pre>
-<p>and someone has been calling it with an array or expression
-returning a list:
-</p>
-<pre class="verbatim"> func(@foo);
- func( split /:/ );
-</pre>
-<p>Then you’ve just supplied an automatic <code>scalar</code> in front
of their
-argument, which can be more than a bit surprising. The old <code>@foo</code>
-which used to hold one thing doesn’t get passed in. Instead,
-<code>func()</code> now gets passed in a <code>1</code>; that is, the number
of elements
-in <code>@foo</code>. And the <code>split</code> gets called in scalar
context so it
-starts scribbling on your <code>@_</code> parameter list. Ouch!
-</p>
-<p>If a sub has both a PROTO and a BLOCK, the prototype is not applied
-until after the BLOCK is completely defined. This means that a recursive
-function with a prototype has to be predeclared for the prototype to take
-effect, like so:
-</p>
-<pre class="verbatim"> sub foo($$);
- sub foo($$) {
- foo 1, 2;
- }
-</pre>
-<p>This is all very powerful, of course, and should be used only in moderation
-to make the world a better place.
-</p>
-<hr>
-<a name="perlsub-Constant-Functions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Overriding-Built_002din-Functions" accesskey="n"
rel="next">perlsub Overriding Built-in Functions</a>, Previous: <a
href="#perlsub-Prototypes" accesskey="p" rel="prev">perlsub Prototypes</a>, Up:
<a href="#perlsub-DESCRIPTION" accesskey="u" rel="up">perlsub DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Constant-Functions"></a>
-<h4 class="subsection">73.3.11 Constant Functions</h4>
-
-<p>Functions with a prototype of <code>()</code> are potential candidates for
-inlining. If the result after optimization and constant folding
-is either a constant or a lexically-scoped scalar which has no other
-references, then it will be used in place of function calls made
-without <code>&</code>. Calls made using <code>&</code> are never
inlined. (See
-<samp>constant.pm</samp> for an easy way to declare most constants.)
-</p>
-<p>The following functions would all be inlined:
-</p>
-<pre class="verbatim"> sub pi () { 3.14159 } # Not
exact, but close.
- sub PI () { 4 * atan2 1, 1 } # As good as it gets,
- # and it's inlined, too!
- sub ST_DEV () { 0 }
- sub ST_INO () { 1 }
-
- sub FLAG_FOO () { 1 << 8 }
- sub FLAG_BAR () { 1 << 9 }
- sub FLAG_MASK () { FLAG_FOO | FLAG_BAR }
-
- sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) }
-
- sub N () { int(OPT_BAZ) / 3 }
-
- sub FOO_SET () { 1 if FLAG_MASK & FLAG_FOO }
- sub FOO_SET2 () { if (FLAG_MASK & FLAG_FOO) { 1 } }
-</pre>
-<p>(Be aware that the last example was not always inlined in Perl 5.20 and
-earlier, which did not behave consistently with subroutines containing
-inner scopes.) You can countermand inlining by using an explicit
-<code>return</code>:
-</p>
-<pre class="verbatim"> sub baz_val () {
- if (OPT_BAZ) {
- return 23;
- }
- else {
- return 42;
- }
- }
- sub bonk_val () { return 12345 }
-</pre>
-<p>As alluded to earlier you can also declare inlined subs dynamically at
-BEGIN time if their body consists of a lexically-scoped scalar which
-has no other references. Only the first example here will be inlined:
-</p>
-<pre class="verbatim"> BEGIN {
- my $var = 1;
- no strict 'refs';
- *INLINED = sub () { $var };
- }
-
- BEGIN {
- my $var = 1;
- my $ref = \$var;
- no strict 'refs';
- *NOT_INLINED = sub () { $var };
- }
-</pre>
-<p>A not so obvious caveat with this (see [RT #79908]) is that the
-variable will be immediately inlined, and will stop behaving like a
-normal lexical variable, e.g. this will print <code>79907</code>, not
<code>79908</code>:
-</p>
-<pre class="verbatim"> BEGIN {
- my $x = 79907;
- *RT_79908 = sub () { $x };
- $x++;
- }
- print RT_79908(); # prints 79907
-</pre>
-<p>As of Perl 5.22, this buggy behavior, while preserved for backward
-compatibility, is detected and emits a deprecation warning. If you want
-the subroutine to be inlined (with no warning), make sure the variable is
-not used in a context where it could be modified aside from where it is
-declared.
-</p>
-<pre class="verbatim"> # Fine, no warning
- BEGIN {
- my $x = 54321;
- *INLINED = sub () { $x };
- }
- # Warns. Future Perl versions will stop inlining it.
- BEGIN {
- my $x;
- $x = 54321;
- *ALSO_INLINED = sub () { $x };
- }
-</pre>
-<p>Perl 5.22 also introduces the experimental "const" attribute as an
-alternative. (Disable the "experimental::const_attr" warnings if
you want
-to use it.) When applied to an anonymous subroutine, it forces the sub to
-be called when the <code>sub</code> expression is evaluated. The return value
is
-captured and turned into a constant subroutine:
-</p>
-<pre class="verbatim"> my $x = 54321;
- *INLINED = sub : const { $x };
- $x++;
-</pre>
-<p>The return value of <code>INLINED</code> in this example will always be
54321,
-regardless of later modifications to $x. You can also put any arbitrary
-code inside the sub, at it will be executed immediately and its return
-value captured the same way.
-</p>
-<p>If you really want a subroutine with a <code>()</code> prototype that
returns a
-lexical variable you can easily force it to not be inlined by adding
-an explicit <code>return</code>:
-</p>
-<pre class="verbatim"> BEGIN {
- my $x = 79907;
- *RT_79908 = sub () { return $x };
- $x++;
- }
- print RT_79908(); # prints 79908
-</pre>
-<p>The easiest way to tell if a subroutine was inlined is by using
-<a href="B-Deparse.html#Top">(B-Deparse)</a>. Consider this example of two
subroutines returning
-<code>1</code>, one with a <code>()</code> prototype causing it to be inlined,
and one
-without (with deparse output truncated for clarity):
-</p>
-<pre class="verbatim"> $ perl -MO=Deparse -le 'sub ONE { 1 } if (ONE) { print
ONE if ONE }'
- sub ONE {
- 1;
- }
- if (ONE ) {
- print ONE() if ONE ;
- }
- $ perl -MO=Deparse -le 'sub ONE () { 1 } if (ONE) { print ONE if ONE }'
- sub ONE () { 1 }
- do {
- print 1
- };
-</pre>
-<p>If you redefine a subroutine that was eligible for inlining, you’ll
-get a warning by default. You can use this warning to tell whether or
-not a particular subroutine is considered inlinable, since it’s
-different than the warning for overriding non-inlined subroutines:
-</p>
-<pre class="verbatim"> $ perl -e 'sub one () {1} sub one () {2}'
- Constant subroutine one redefined at -e line 1.
- $ perl -we 'sub one {1} sub one {2}'
- Subroutine one redefined at -e line 1.
-</pre>
-<p>The warning is considered severe enough not to be affected by the
-<strong>-w</strong> switch (or its absence) because previously compiled
invocations
-of the function will still be using the old value of the function. If
-you need to be able to redefine the subroutine, you need to ensure
-that it isn’t inlined, either by dropping the <code>()</code> prototype
(which
-changes calling semantics, so beware) or by thwarting the inlining
-mechanism in some other way, e.g. by adding an explicit <code>return</code>, as
-mentioned above:
-</p>
-<pre class="verbatim"> sub not_inlined () { return 23 }
-</pre>
-<hr>
-<a name="perlsub-Overriding-Built_002din-Functions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Autoloading" accesskey="n" rel="next">perlsub
Autoloading</a>, Previous: <a href="#perlsub-Constant-Functions" accesskey="p"
rel="prev">perlsub Constant Functions</a>, Up: <a href="#perlsub-DESCRIPTION"
accesskey="u" rel="up">perlsub DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Overriding-Built_002din-Functions"></a>
-<h4 class="subsection">73.3.12 Overriding Built-in Functions</h4>
-
-<p>Many built-in functions may be overridden, though this should be tried
-only occasionally and for good reason. Typically this might be
-done by a package attempting to emulate missing built-in functionality
-on a non-Unix system.
-</p>
-<p>Overriding may be done only by importing the name from a module at
-compile time–ordinary predeclaration isn’t good enough. However,
the
-<code>use subs</code> pragma lets you, in effect, predeclare subs
-via the import syntax, and these names may then override built-in ones:
-</p>
-<pre class="verbatim"> use subs 'chdir', 'chroot', 'chmod', 'chown';
- chdir $somewhere;
- sub chdir { ... }
-</pre>
-<p>To unambiguously refer to the built-in form, precede the
-built-in name with the special package qualifier <code>CORE::</code>. For
example,
-saying <code>CORE::open()</code> always refers to the built-in
<code>open()</code>, even
-if the current package has imported some other subroutine called
-<code>&open()</code> from elsewhere. Even though it looks like a regular
-function call, it isn’t: the CORE:: prefix in that case is part of
Perl’s
-syntax, and works for any keyword, regardless of what is in the CORE
-package. Taking a reference to it, that is, <code>\&CORE::open</code>,
only works
-for some keywords. See <a href="CORE.html#Top">(CORE)</a>.
-</p>
-<p>Library modules should not in general export built-in names like
<code>open</code>
-or <code>chdir</code> as part of their default <code>@EXPORT</code> list,
because these may
-sneak into someone else’s namespace and change the semantics
unexpectedly.
-Instead, if the module adds that name to <code>@EXPORT_OK</code>, then
it’s
-possible for a user to import the name explicitly, but not implicitly.
-That is, they could say
-</p>
-<pre class="verbatim"> use Module 'open';
-</pre>
-<p>and it would import the <code>open</code> override. But if they said
-</p>
-<pre class="verbatim"> use Module;
-</pre>
-<p>they would get the default imports without overrides.
-</p>
-<p>The foregoing mechanism for overriding built-in is restricted, quite
-deliberately, to the package that requests the import. There is a second
-method that is sometimes applicable when you wish to override a built-in
-everywhere, without regard to namespace boundaries. This is achieved by
-importing a sub into the special namespace <code>CORE::GLOBAL::</code>. Here
is an
-example that quite brazenly replaces the <code>glob</code> operator with
something
-that understands regular expressions.
-</p>
-<pre class="verbatim"> package REGlob;
- require Exporter;
- @ISA = 'Exporter';
- @EXPORT_OK = 'glob';
-
- sub import {
- my $pkg = shift;
- return unless @_;
- my $sym = shift;
- my $where = ($sym =~ s/^GLOBAL_// ? 'CORE::GLOBAL' : caller(0));
- $pkg->export($where, $sym, @_);
- }
-
- sub glob {
- my $pat = shift;
- my @got;
- if (opendir my $d, '.') {
- @got = grep /$pat/, readdir $d;
- closedir $d;
- }
- return @got;
- }
- 1;
-</pre>
-<p>And here’s how it could be (ab)used:
-</p>
-<pre class="verbatim"> #use REGlob 'GLOBAL_glob'; # override glob() in
ALL namespaces
- package Foo;
- use REGlob 'glob'; # override glob() in Foo:: only
- print for <^[a-z_]+\.pm\$>; # show all pragmatic modules
-</pre>
-<p>The initial comment shows a contrived, even dangerous example.
-By overriding <code>glob</code> globally, you would be forcing the new (and
-subversive) behavior for the <code>glob</code> operator for <em>every</em>
namespace,
-without the complete cognizance or cooperation of the modules that own
-those namespaces. Naturally, this should be done with extreme caution–if
-it must be done at all.
-</p>
-<p>The <code>REGlob</code> example above does not implement all the support
needed to
-cleanly override perl’s <code>glob</code> operator. The built-in
<code>glob</code> has
-different behaviors depending on whether it appears in a scalar or list
-context, but our <code>REGlob</code> doesn’t. Indeed, many perl
built-in have such
-context sensitive behaviors, and these must be adequately supported by
-a properly written override. For a fully functional example of overriding
-<code>glob</code>, study the implementation of <code>File::DosGlob</code> in
the standard
-library.
-</p>
-<p>When you override a built-in, your replacement should be consistent (if
-possible) with the built-in native syntax. You can achieve this by using
-a suitable prototype. To get the prototype of an overridable built-in,
-use the <code>prototype</code> function with an argument of
<code>"CORE::builtin_name"</code>
-(see <a href="#perlfunc-prototype">perlfunc prototype</a>).
-</p>
-<p>Note however that some built-ins can’t have their syntax expressed by
a
-prototype (such as <code>system</code> or <code>chomp</code>). If you
override them you won’t
-be able to fully mimic their original syntax.
-</p>
-<p>The built-ins <code>do</code>, <code>require</code> and <code>glob</code>
can also be overridden, but due
-to special magic, their original syntax is preserved, and you don’t have
-to define a prototype for their replacements. (You can’t override the
-<code>do BLOCK</code> syntax, though).
-</p>
-<p><code>require</code> has special additional dark magic: if you invoke your
-<code>require</code> replacement as <code>require Foo::Bar</code>, it will
actually receive
-the argument <code>"Foo/Bar.pm"</code> in @_. See <a
href="#perlfunc-require">perlfunc require</a>.
-</p>
-<p>And, as you’ll have noticed from the previous example, if you override
-<code>glob</code>, the <code><*></code> glob operator is overridden as
well.
-</p>
-<p>In a similar fashion, overriding the <code>readline</code> function also
overrides
-the equivalent I/O operator <code><FILEHANDLE></code>. Also, overriding
-<code>readpipe</code> also overrides the operators <code>``</code> and
<code>qx//</code>.
-</p>
-<p>Finally, some built-ins (e.g. <code>exists</code> or <code>grep</code>)
can’t be overridden.
-</p>
-<hr>
-<a name="perlsub-Autoloading"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsub-Subroutine-Attributes" accesskey="n"
rel="next">perlsub Subroutine Attributes</a>, Previous: <a
href="#perlsub-Overriding-Built_002din-Functions" accesskey="p"
rel="prev">perlsub Overriding Built-in Functions</a>, Up: <a
href="#perlsub-DESCRIPTION" accesskey="u" rel="up">perlsub DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Autoloading"></a>
-<h4 class="subsection">73.3.13 Autoloading</h4>
-
-<p>If you call a subroutine that is undefined, you would ordinarily
-get an immediate, fatal error complaining that the subroutine doesn’t
-exist. (Likewise for subroutines being used as methods, when the
-method doesn’t exist in any base class of the class’s package.)
-However, if an <code>AUTOLOAD</code> subroutine is defined in the package or
-packages used to locate the original subroutine, then that
-<code>AUTOLOAD</code> subroutine is called with the arguments that would have
-been passed to the original subroutine. The fully qualified name
-of the original subroutine magically appears in the global $AUTOLOAD
-variable of the same package as the <code>AUTOLOAD</code> 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
-<code>import</code> or <code>unimport</code> method is just skipped instead.
Also, if
-the AUTOLOAD subroutine is an XSUB, there are other ways to retrieve the
-subroutine name. See <a href="#perlguts-Autoloading-with-XSUBs">perlguts
Autoloading with XSUBs</a> for details.)
-</p>
-<p>Many <code>AUTOLOAD</code> routines load in a definition for the requested
-subroutine using eval(), then execute that subroutine using a special
-form of goto() that erases the stack frame of the <code>AUTOLOAD</code> routine
-without a trace. (See the source to the standard module documented
-in <a href="AutoLoader.html#Top">(AutoLoader)</a>, for example.) But an
<code>AUTOLOAD</code> routine can
-also just emulate the routine and never define it. For example,
-let’s pretend that a function that wasn’t defined should just
invoke
-<code>system</code> with those arguments. All you’d do is:
-</p>
-<pre class="verbatim"> sub AUTOLOAD {
- my $program = $AUTOLOAD;
- $program =~ s/.*:://;
- system($program, @_);
- }
- date();
- who('am', 'i');
- ls('-l');
-</pre>
-<p>In fact, if you predeclare functions you want to call that way, you
don’t
-even need parentheses:
-</p>
-<pre class="verbatim"> use subs qw(date who ls);
- date;
- who "am", "i";
- ls '-l';
-</pre>
-<p>A more complete example of this is the Shell module on CPAN, which
-can treat undefined subroutine calls as calls to external programs.
-</p>
-<p>Mechanisms are available to help modules writers split their modules
-into autoloadable files. See the standard AutoLoader module
-described in <a href="AutoLoader.html#Top">(AutoLoader)</a> and in <a
href="AutoSplit.html#Top">(AutoSplit)</a>, the standard
-SelfLoader modules in <a href="SelfLoader.html#Top">(SelfLoader)</a>, and the
document on adding C
-functions to Perl code in <a href="perlxs.html#Top">(perlxs)</a>.
-</p>
-<hr>
-<a name="perlsub-Subroutine-Attributes"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlsub-Autoloading" accesskey="p" rel="prev">perlsub
Autoloading</a>, Up: <a href="#perlsub-DESCRIPTION" accesskey="u"
rel="up">perlsub DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Subroutine-Attributes"></a>
-<h4 class="subsection">73.3.14 Subroutine Attributes</h4>
-
-<p>A subroutine declaration or definition may have a list of attributes
-associated with it. If such an attribute list is present, it is
-broken up at space or colon boundaries and treated as though a
-<code>use attributes</code> had been seen. See <a
href="attributes.html#Top">(attributes)</a> for details
-about what attributes are currently supported.
-Unlike the limitation with the obsolescent <code>use attrs</code>, the
-<code>sub : ATTRLIST</code> syntax works to associate the attributes with
-a pre-declaration, and not just with a subroutine definition.
-</p>
-<p>The attributes must be valid as simple identifier names (without any
-punctuation other than the ’_’ character). They may have a
parameter
-list appended, which is only checked for whether its parentheses
(’(’,’)’)
-nest properly.
-</p>
-<p>Examples of valid syntax (even though the attributes are unknown):
-</p>
-<pre class="verbatim"> sub fnord (&\%) : switch(10,foo(7,3)) :
expensive;
- sub plugh () : Ugly('\(") :Bad;
- sub xyzzy : _5x5 { ... }
-</pre>
-<p>Examples of invalid syntax:
-</p>
-<pre class="verbatim"> sub fnord : switch(10,foo(); # ()-string not balanced
- sub snoid : Ugly('('); # ()-string not balanced
- sub xyzzy : 5x5; # "5x5" not a valid identifier
- sub plugh : Y2::north; # "Y2::north" not a simple
identifier
- sub snurt : foo + bar; # "+" not a colon or space
-</pre>
-<p>The attribute list is passed as a list of constant strings to the code
-which associates them with the subroutine. In particular, the second example
-of valid syntax above currently looks like this in terms of how it’s
-parsed and invoked:
-</p>
-<pre class="verbatim"> use attributes __PACKAGE__, \&plugh,
q[Ugly('\(")], 'Bad';
-</pre>
-<p>For further details on attribute lists and their manipulation,
-see <a href="attributes.html#Top">(attributes)</a> and <a
href="Attribute-Handlers.html#Top">(Attribute-Handlers)</a>.
-</p>
-<hr>
-<a name="perlsub-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlsub-DESCRIPTION" accesskey="p" rel="prev">perlsub
DESCRIPTION</a>, Up: <a href="#perlsub" accesskey="u" rel="up">perlsub</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-37"></a>
-<h3 class="section">73.4 SEE ALSO</h3>
-
-<p>See <a href="#perlref-Function-Templates">perlref Function Templates</a>
for more about references and closures.
-See <a href="perlxs.html#Top">(perlxs)</a> if you’d like to learn about
calling C subroutines from Perl.
-See <a href="#perlembed-NAME">perlembed NAME</a> if you’d like to learn
about calling Perl subroutines from C.
-See <a href="#perlmod-NAME">perlmod NAME</a> to learn about bundling up your
functions in separate files.
-See <a href="perlmodlib.html#Top">(perlmodlib)</a> to learn what library
modules come standard on your system.
-See <a href="#perlootut-NAME">perlootut NAME</a> to learn how to make object
method calls.
-</p>
-<hr>
-<a name="perlsyn"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut" accesskey="n" rel="next">perlthrtut</a>, Previous:
<a href="#perlsub" accesskey="p" rel="prev">perlsub</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlsyn-2"></a>
-<h2 class="chapter">74 perlsyn</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlsyn-NAME"
accesskey="1">perlsyn NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsyn-DESCRIPTION"
accesskey="2">perlsyn DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlsyn-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-DESCRIPTION" accesskey="n" rel="next">perlsyn
DESCRIPTION</a>, Up: <a href="#perlsyn" accesskey="u" rel="up">perlsyn</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-73"></a>
-<h3 class="section">74.1 NAME</h3>
-
-<p>perlsyn - Perl syntax
-</p>
-<hr>
-<a name="perlsyn-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlsyn-NAME" accesskey="p" rel="prev">perlsyn NAME</a>,
Up: <a href="#perlsyn" accesskey="u" rel="up">perlsyn</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-72"></a>
-<h3 class="section">74.2 DESCRIPTION</h3>
-
-<p>A Perl program consists of a sequence of declarations and statements
-which run from the top to the bottom. Loops, subroutines, and other
-control structures allow you to jump around within the code.
-</p>
-<p>Perl is a <strong>free-form</strong> language: you can format and indent it
however
-you like. Whitespace serves mostly to separate tokens, unlike
-languages like Python where it is an important part of the syntax,
-or Fortran where it is immaterial.
-</p>
-<p>Many of Perl’s syntactic elements are <strong>optional</strong>.
Rather than
-requiring you to put parentheses around every function call and
-declare every variable, you can often leave such explicit elements off
-and Perl will figure out what you meant. This is known as <strong>Do What I
-Mean</strong>, abbreviated <strong>DWIM</strong>. It allows programmers to be
<strong>lazy</strong> and to
-code in a style with which they are comfortable.
-</p>
-<p>Perl <strong>borrows syntax</strong> and concepts from many languages: awk,
sed, C,
-Bourne Shell, Smalltalk, Lisp and even English. Other
-languages have borrowed syntax from Perl, particularly its regular
-expression extensions. So if you have programmed in another language
-you will see familiar pieces in Perl. They often work the same, but
-see <a href="#perltrap-NAME">perltrap NAME</a> for information about how they
differ.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlsyn-Declarations"
accesskey="1">perlsyn Declarations</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsyn-Comments"
accesskey="2">perlsyn Comments</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsyn-Simple-Statements"
accesskey="3">perlsyn Simple Statements</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Truth-and-Falsehood" accesskey="4">perlsyn Truth and
Falsehood</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Statement-Modifiers" accesskey="5">perlsyn Statement
Modifiers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Compound-Statements" accesskey="6">perlsyn Compound
Statements</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsyn-Loop-Control"
accesskey="7">perlsyn Loop Control</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsyn-For-Loops"
accesskey="8">perlsyn For Loops</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsyn-Foreach-Loops"
accesskey="9">perlsyn Foreach Loops</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Basic-BLOCKs">perlsyn Basic
BLOCKs</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Switch-Statements">perlsyn Switch
Statements</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsyn-Goto">perlsyn
Goto</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-The-Ellipsis-Statement">perlsyn The Ellipsis
Statement</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-PODs_003a-Embedded-Documentation">perlsyn PODs: Embedded
Documentation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Plain-Old-Comments-_0028Not_0021_0029">perlsyn Plain Old
Comments (Not!)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Experimental-Details-on-given-and-when">perlsyn Experimental
Details on given and when</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlsyn-Declarations"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Comments" accesskey="n" rel="next">perlsyn
Comments</a>, Up: <a href="#perlsyn-DESCRIPTION" accesskey="u" rel="up">perlsyn
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Declarations"></a>
-<h4 class="subsection">74.2.1 Declarations</h4>
-
-<p>The only things you need to declare in Perl are report formats and
-subroutines (and sometimes not even subroutines). A scalar variable holds
-the undefined value (<code>undef</code>) until it has been assigned a defined
-value, which is anything other than <code>undef</code>. When used as a number,
-<code>undef</code> is treated as <code>0</code>; when used as a string, it is
treated as
-the empty string, <code>""</code>; and when used as a reference that
isn’t being
-assigned to, it is treated as an error. If you enable warnings,
-you’ll be notified of an uninitialized value whenever you treat
-<code>undef</code> as a string or a number. Well, usually. Boolean contexts,
-such as:
-</p>
-<pre class="verbatim"> if ($a) {}
-</pre>
-<p>are exempt from warnings (because they care about truth rather than
-definedness). Operators such as <code>++</code>, <code>--</code>,
<code>+=</code>,
-<code>-=</code>, and <code>.=</code>, that operate on undefined variables such
as:
-</p>
-<pre class="verbatim"> undef $a;
- $a++;
-</pre>
-<p>are also always exempt from such warnings.
-</p>
-<p>A declaration can be put anywhere a statement can, but has no effect on
-the execution of the primary sequence of statements: declarations all
-take effect at compile time. All declarations are typically put at
-the beginning or the end of the script. However, if you’re using
-lexically-scoped private variables created with <code>my()</code>,
-<code>state()</code>, or <code>our()</code>, you’ll have to make sure
-your format or subroutine definition is within the same block scope
-as the my if you expect to be able to access those private variables.
-</p>
-<p>Declaring a subroutine allows a subroutine name to be used as if it were a
-list operator from that point forward in the program. You can declare a
-subroutine without defining it by saying <code>sub name</code>, thus:
-</p>
-<pre class="verbatim"> sub myname;
- $me = myname $0 or die "can't get myname";
-</pre>
-<p>A bare declaration like that declares the function to be a list operator,
-not a unary operator, so you have to be careful to use parentheses (or
-<code>or</code> instead of <code>||</code>.) The <code>||</code> operator
binds too tightly to use after
-list operators; it becomes part of the last element. You can always use
-parentheses around the list operators arguments to turn the list operator
-back into something that behaves more like a function call. Alternatively,
-you can use the prototype <code>($)</code> to turn the subroutine into a unary
-operator:
-</p>
-<pre class="verbatim"> sub myname ($);
- $me = myname $0 || die "can't get myname";
-</pre>
-<p>That now parses as you’d expect, but you still ought to get in the
habit of
-using parentheses in that situation. For more on prototypes, see
-<a href="#perlsub-NAME">perlsub NAME</a>.
-</p>
-<p>Subroutines declarations can also be loaded up with the
<code>require</code> statement
-or both loaded and imported into your namespace with a <code>use</code>
statement.
-See <a href="#perlmod-NAME">perlmod NAME</a> for details on this.
-</p>
-<p>A statement sequence may contain declarations of lexically-scoped
-variables, but apart from declaring a variable name, the declaration acts
-like an ordinary statement, and is elaborated within the sequence of
-statements as if it were an ordinary statement. That means it actually
-has both compile-time and run-time effects.
-</p>
-<hr>
-<a name="perlsyn-Comments"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Simple-Statements" accesskey="n" rel="next">perlsyn
Simple Statements</a>, Previous: <a href="#perlsyn-Declarations" accesskey="p"
rel="prev">perlsyn Declarations</a>, Up: <a href="#perlsyn-DESCRIPTION"
accesskey="u" rel="up">perlsyn DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Comments"></a>
-<h4 class="subsection">74.2.2 Comments</h4>
-
-<p>Text from a <code>"#"</code> character until the end of the line
is a comment,
-and is ignored. Exceptions include <code>"#"</code> inside a string
or regular
-expression.
-</p>
-<hr>
-<a name="perlsyn-Simple-Statements"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Truth-and-Falsehood" accesskey="n" rel="next">perlsyn
Truth and Falsehood</a>, Previous: <a href="#perlsyn-Comments" accesskey="p"
rel="prev">perlsyn Comments</a>, Up: <a href="#perlsyn-DESCRIPTION"
accesskey="u" rel="up">perlsyn DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Simple-Statements"></a>
-<h4 class="subsection">74.2.3 Simple Statements</h4>
-
-<p>The only kind of simple statement is an expression evaluated for its
-side-effects. Every simple statement must be terminated with a
-semicolon, unless it is the final statement in a block, in which case
-the semicolon is optional. But put the semicolon in anyway if the
-block takes up more than one line, because you may eventually add
-another line. Note that there are operators like <code>eval {}</code>,
<code>sub {}</code>, and
-<code>do {}</code> that <em>look</em> like compound statements, but
aren’t–they’re just
-TERMs in an expression–and thus need an explicit termination when used
-as the last item in a statement.
-</p>
-<hr>
-<a name="perlsyn-Truth-and-Falsehood"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Statement-Modifiers" accesskey="n" rel="next">perlsyn
Statement Modifiers</a>, Previous: <a href="#perlsyn-Simple-Statements"
accesskey="p" rel="prev">perlsyn Simple Statements</a>, Up: <a
href="#perlsyn-DESCRIPTION" accesskey="u" rel="up">perlsyn DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Truth-and-Falsehood"></a>
-<h4 class="subsection">74.2.4 Truth and Falsehood</h4>
-
-<p>The number 0, the strings <code>'0'</code> and <code>""</code>,
the empty list <code>()</code>, and
-<code>undef</code> are all false in a boolean context. All other values are
true.
-Negation of a true value by <code>!</code> or <code>not</code> returns a
special false value.
-When evaluated as a string it is treated as <code>""</code>, but as
a number, it
-is treated as 0. Most Perl operators
-that return true or false behave this way.
-</p>
-<hr>
-<a name="perlsyn-Statement-Modifiers"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Compound-Statements" accesskey="n" rel="next">perlsyn
Compound Statements</a>, Previous: <a href="#perlsyn-Truth-and-Falsehood"
accesskey="p" rel="prev">perlsyn Truth and Falsehood</a>, Up: <a
href="#perlsyn-DESCRIPTION" accesskey="u" rel="up">perlsyn DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Statement-Modifiers"></a>
-<h4 class="subsection">74.2.5 Statement Modifiers</h4>
-
-<p>Any simple statement may optionally be followed by a <em>SINGLE</em>
modifier,
-just before the terminating semicolon (or block ending). The possible
-modifiers are:
-</p>
-<pre class="verbatim"> if EXPR
- unless EXPR
- while EXPR
- until EXPR
- for LIST
- foreach LIST
- when EXPR
-</pre>
-<p>The <code>EXPR</code> following the modifier is referred to as the
"condition".
-Its truth or falsehood determines how the modifier will behave.
-</p>
-<p><code>if</code> executes the statement once <em>if</em> and only if the
condition is
-true. <code>unless</code> is the opposite, it executes the statement
<em>unless</em>
-the condition is true (that is, if the condition is false).
-</p>
-<pre class="verbatim"> print "Basset hounds got long ears" if
length $ear >= 10;
- go_outside() and play() unless $is_raining;
-</pre>
-<p>The <code>for(each)</code> modifier is an iterator: it executes the
statement once
-for each item in the LIST (with <code>$_</code> aliased to each item in turn).
-</p>
-<pre class="verbatim"> print "Hello $_!\n" for qw(world Dolly
nurse);
-</pre>
-<p><code>while</code> repeats the statement <em>while</em> the condition is
true.
-<code>until</code> does the opposite, it repeats the statement <em>until</em>
the
-condition is true (or while the condition is false):
-</p>
-<pre class="verbatim"> # Both of these count from 0 to 10.
- print $i++ while $i <= 10;
- print $j++ until $j > 10;
-</pre>
-<p>The <code>while</code> and <code>until</code> modifiers have the usual
"<code>while</code> loop"
-semantics (conditional evaluated first), except when applied to a
-<code>do</code>-BLOCK (or to the Perl4 <code>do</code>-SUBROUTINE statement),
in
-which case the block executes once before the conditional is
-evaluated.
-</p>
-<p>This is so that you can write loops like:
-</p>
-<pre class="verbatim"> do {
- $line = <STDIN>;
- ...
- } until !defined($line) || $line eq ".\n"
-</pre>
-<p>See ‘perlfunc do’. Note also that the loop control statements
described
-later will <em>NOT</em> work in this construct, because modifiers don’t
take
-loop labels. Sorry. You can always put another block inside of it
-(for <code>next</code>) or around it (for <code>last</code>) to do that sort
of thing.
-For <code>next</code>, just double the braces:
-</p>
-<pre class="verbatim"> do {{
- next if $x == $y;
- # do something here
- }} until $x++ > $z;
-</pre>
-<p>For <code>last</code>, you have to be more elaborate:
-</p>
-<pre class="verbatim"> LOOP: {
- do {
- last if $x = $y**2;
- # do something here
- } while $x++ <= $z;
- }
-</pre>
-<p><strong>NOTE:</strong> The behaviour of a <code>my</code>,
<code>state</code>, or
-<code>our</code> modified with a statement modifier conditional
-or loop construct (for example, <code>my $x if ...</code>) is
-<strong>undefined</strong>. The value of the <code>my</code> variable may be
<code>undef</code>, any
-previously assigned value, or possibly anything else. Don’t rely on
-it. Future versions of perl might do something different from the
-version of perl you try it out on. Here be dragons.
-</p>
-<p>The <code>when</code> modifier is an experimental feature that first
appeared in Perl
-5.14. To use it, you should include a <code>use v5.14</code> declaration.
-(Technically, it requires only the <code>switch</code> feature, but that
aspect of it
-was not available before 5.14.) Operative only from within a
<code>foreach</code>
-loop or a <code>given</code> block, it executes the statement only if the
smartmatch
-<code>$_ ~~ <em>EXPR</em></code> is true. If the statement executes, it is
followed by
-a <code>next</code> from inside a <code>foreach</code> and <code>break</code>
from inside a <code>given</code>.
-</p>
-<p>Under the current implementation, the <code>foreach</code> loop can be
-anywhere within the <code>when</code> modifier’s dynamic scope, but must
be
-within the <code>given</code> block’s lexical scope. This restricted may
-be relaxed in a future release. See <a
href="#perlsyn-Switch-Statements">Switch Statements</a> below.
-</p>
-<hr>
-<a name="perlsyn-Compound-Statements"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Loop-Control" accesskey="n" rel="next">perlsyn Loop
Control</a>, Previous: <a href="#perlsyn-Statement-Modifiers" accesskey="p"
rel="prev">perlsyn Statement Modifiers</a>, Up: <a href="#perlsyn-DESCRIPTION"
accesskey="u" rel="up">perlsyn DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Compound-Statements"></a>
-<h4 class="subsection">74.2.6 Compound Statements</h4>
-
-<p>In Perl, a sequence of statements that defines a scope is called a block.
-Sometimes a block is delimited by the file containing it (in the case
-of a required file, or the program as a whole), and sometimes a block
-is delimited by the extent of a string (in the case of an eval).
-</p>
-<p>But generally, a block is delimited by curly brackets, also known as braces.
-We will call this syntactic construct a BLOCK.
-</p>
-<p>The following compound statements may be used to control flow:
-</p>
-<pre class="verbatim"> if (EXPR) BLOCK
- if (EXPR) BLOCK else BLOCK
- if (EXPR) BLOCK elsif (EXPR) BLOCK ...
- if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
-
- unless (EXPR) BLOCK
- unless (EXPR) BLOCK else BLOCK
- unless (EXPR) BLOCK elsif (EXPR) BLOCK ...
- unless (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
-
- given (EXPR) BLOCK
-
- LABEL while (EXPR) BLOCK
- LABEL while (EXPR) BLOCK continue BLOCK
-
- LABEL until (EXPR) BLOCK
- LABEL until (EXPR) BLOCK continue BLOCK
-
- LABEL for (EXPR; EXPR; EXPR) BLOCK
- LABEL for VAR (LIST) BLOCK
- LABEL for VAR (LIST) BLOCK continue BLOCK
-
- LABEL foreach (EXPR; EXPR; EXPR) BLOCK
- LABEL foreach VAR (LIST) BLOCK
- LABEL foreach VAR (LIST) BLOCK continue BLOCK
-
- LABEL BLOCK
- LABEL BLOCK continue BLOCK
-
- PHASE BLOCK
-</pre>
-<p>The experimental <code>given</code> statement is <em>not automatically
enabled</em>; see
-<a href="#perlsyn-Switch-Statements">Switch Statements</a> below for how to do
so, and the attendant caveats.
-</p>
-<p>Unlike in C and Pascal, in Perl these are all defined in terms of BLOCKs,
-not statements. This means that the curly brackets are
<em>required</em>–no
-dangling statements allowed. If you want to write conditionals without
-curly brackets, there are several other ways to do it. The following
-all do the same thing:
-</p>
-<pre class="verbatim"> if (!open(FOO)) { die "Can't open $FOO:
$!" }
- die "Can't open $FOO: $!" unless open(FOO);
- open(FOO) || die "Can't open $FOO: $!";
- open(FOO) ? () : die "Can't open $FOO: $!";
- # a bit exotic, that last one
-</pre>
-<p>The <code>if</code> statement is straightforward. Because BLOCKs are always
-bounded by curly brackets, there is never any ambiguity about which
-<code>if</code> an <code>else</code> goes with. If you use
<code>unless</code> in place of <code>if</code>,
-the sense of the test is reversed. Like <code>if</code>, <code>unless</code>
can be followed
-by <code>else</code>. <code>unless</code> can even be followed by one or more
<code>elsif</code>
-statements, though you may want to think twice before using that particular
-language construct, as everyone reading your code will have to think at least
-twice before they can understand what’s going on.
-</p>
-<p>The <code>while</code> statement executes the block as long as the
expression is
-<a href="#perlsyn-Truth-and-Falsehood">true</a>.
-The <code>until</code> statement executes the block as long as the expression
is
-false.
-The LABEL is optional, and if present, consists of an identifier followed
-by a colon. The LABEL identifies the loop for the loop control
-statements <code>next</code>, <code>last</code>, and <code>redo</code>.
-If the LABEL is omitted, the loop control statement
-refers to the innermost enclosing loop. This may include dynamically
-looking back your call-stack at run time to find the LABEL. Such
-desperate behavior triggers a warning if you use the <code>use warnings</code>
-pragma or the <strong>-w</strong> flag.
-</p>
-<p>If there is a <code>continue</code> BLOCK, it is always executed just
before the
-conditional is about to be evaluated again. Thus it can be used to
-increment a loop variable, even when the loop has been continued via
-the <code>next</code> statement.
-</p>
-<p>When a block is preceding by a compilation phase keyword such as
<code>BEGIN</code>,
-<code>END</code>, <code>INIT</code>, <code>CHECK</code>, or
<code>UNITCHECK</code>, then the block will run only
-during the corresponding phase of execution. See <a
href="#perlmod-NAME">perlmod NAME</a> for more details.
-</p>
-<p>Extension modules can also hook into the Perl parser to define new
-kinds of compound statements. These are introduced by a keyword which
-the extension recognizes, and the syntax following the keyword is
-defined entirely by the extension. If you are an implementor, see
-<a
href="perlapi.html#PL_005fkeyword_005fplugin">(perlapi)PL_keyword_plugin</a>
for the mechanism. If you are using such
-a module, see the module’s documentation for details of the syntax that
-it defines.
-</p>
-<hr>
-<a name="perlsyn-Loop-Control"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-For-Loops" accesskey="n" rel="next">perlsyn For
Loops</a>, Previous: <a href="#perlsyn-Compound-Statements" accesskey="p"
rel="prev">perlsyn Compound Statements</a>, Up: <a href="#perlsyn-DESCRIPTION"
accesskey="u" rel="up">perlsyn DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Loop-Control"></a>
-<h4 class="subsection">74.2.7 Loop Control</h4>
-
-<p>The <code>next</code> command starts the next iteration of the loop:
-</p>
-<pre class="verbatim"> LINE: while (<STDIN>) {
- next LINE if /^#/; # discard comments
- ...
- }
-</pre>
-<p>The <code>last</code> command immediately exits the loop in question. The
-<code>continue</code> block, if any, is not executed:
-</p>
-<pre class="verbatim"> LINE: while (<STDIN>) {
- last LINE if /^$/; # exit when done with header
- ...
- }
-</pre>
-<p>The <code>redo</code> command restarts the loop block without evaluating the
-conditional again. The <code>continue</code> block, if any, is <em>not</em>
executed.
-This command is normally used by programs that want to lie to themselves
-about what was just input.
-</p>
-<p>For example, when processing a file like <samp>/etc/termcap</samp>.
-If your input lines might end in backslashes to indicate continuation, you
-want to skip ahead and get the next record.
-</p>
-<pre class="verbatim"> while (<>) {
- chomp;
- if (s/\\$//) {
- $_ .= <>;
- redo unless eof();
- }
- # now process $_
- }
-</pre>
-<p>which is Perl shorthand for the more explicitly written version:
-</p>
-<pre class="verbatim"> LINE: while (defined($line = <ARGV>)) {
- chomp($line);
- if ($line =~ s/\\$//) {
- $line .= <ARGV>;
- redo LINE unless eof(); # not eof(ARGV)!
- }
- # now process $line
- }
-</pre>
-<p>Note that if there were a <code>continue</code> 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 <code>m?pat?</code> one-time matches:
-</p>
-<pre class="verbatim"> # inspired by :1,$g/fred/s//WILMA/
- while (<>) {
- 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?
- }
-</pre>
-<p>If the word <code>while</code> is replaced by the word <code>until</code>,
the sense of the
-test is reversed, but the conditional is still tested before the first
-iteration.
-</p>
-<p>Loop control statements don’t work in an <code>if</code> or
<code>unless</code>, since
-they aren’t loops. You can double the braces to make them such, though.
-</p>
-<pre class="verbatim"> if (/pattern/) {{
- last if /fred/;
- next if /barney/; # same effect as "last",
- # but doesn't document as well
- # do something here
- }}
-</pre>
-<p>This is caused by the fact that a block by itself acts as a loop that
-executes once, see <a href="#perlsyn-Basic-BLOCKs">Basic BLOCKs</a>.
-</p>
-<p>The form <code>while/if BLOCK BLOCK</code>, available in Perl 4, is no
longer
-available. Replace any occurrence of <code>if BLOCK</code> by <code>if (do
BLOCK)</code>.
-</p>
-<hr>
-<a name="perlsyn-For-Loops"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Foreach-Loops" accesskey="n" rel="next">perlsyn
Foreach Loops</a>, Previous: <a href="#perlsyn-Loop-Control" accesskey="p"
rel="prev">perlsyn Loop Control</a>, Up: <a href="#perlsyn-DESCRIPTION"
accesskey="u" rel="up">perlsyn DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="For-Loops"></a>
-<h4 class="subsection">74.2.8 For Loops</h4>
-
-<p>Perl’s C-style <code>for</code> loop works like the corresponding
<code>while</code> loop;
-that means that this:
-</p>
-<pre class="verbatim"> for ($i = 1; $i < 10; $i++) {
- ...
- }
-</pre>
-<p>is the same as this:
-</p>
-<pre class="verbatim"> $i = 1;
- while ($i < 10) {
- ...
- } continue {
- $i++;
- }
-</pre>
-<p>There is one minor difference: if variables are declared with
<code>my</code>
-in the initialization section of the <code>for</code>, the lexical scope of
-those variables is exactly the <code>for</code> loop (the body of the loop
-and the control sections).
-</p>
-<p>As a special case, if the test in the <code>for</code> loop (or the
corresponding
-<code>while</code> loop) is empty, it is treated as true. That is, both
-</p>
-<pre class="verbatim"> for (;;) {
- ...
- }
-</pre>
-<p>and
-</p>
-<pre class="verbatim"> while () {
- ...
- }
-</pre>
-<p>are treated as infinite loops.
-</p>
-<p>Besides the normal array index looping, <code>for</code> can lend itself
-to many other interesting applications. Here’s one that avoids the
-problem you get into if you explicitly test for end-of-file on
-an interactive file descriptor causing your program to appear to
-hang.
-</p>
-<pre class="verbatim"> $on_a_tty = -t STDIN && -t STDOUT;
- sub prompt { print "yes? " if $on_a_tty }
- for ( prompt(); <STDIN>; prompt() ) {
- # do something
- }
-</pre>
-<p>Using <code>readline</code> (or the operator form,
<code><EXPR></code>) as the
-conditional of a <code>for</code> loop is shorthand for the following. This
-behaviour is the same as a <code>while</code> loop conditional.
- >>
-</p>
-<pre class="verbatim"> for ( prompt(); defined( $_ = <STDIN> );
prompt() ) {
- # do something
- }
-</pre>
-<hr>
-<a name="perlsyn-Foreach-Loops"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Basic-BLOCKs" accesskey="n" rel="next">perlsyn Basic
BLOCKs</a>, Previous: <a href="#perlsyn-For-Loops" accesskey="p"
rel="prev">perlsyn For Loops</a>, Up: <a href="#perlsyn-DESCRIPTION"
accesskey="u" rel="up">perlsyn DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Foreach-Loops"></a>
-<h4 class="subsection">74.2.9 Foreach Loops</h4>
-
-<p>The <code>foreach</code> loop iterates over a normal list value and sets
the scalar
-variable VAR to be each element of the list in turn. If the variable
-is preceded with the keyword <code>my</code>, then it is lexically scoped, and
-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 <code>my</code>, it
uses
-that variable instead of the global one, but it’s still localized to
-the loop. This implicit localization occurs <em>only</em> in a
<code>foreach</code>
-loop.
-</p>
-<p>The <code>foreach</code> keyword is actually a synonym for the
<code>for</code> keyword, so
-you can use either. If VAR is omitted, <code>$_</code> is set to each value.
-</p>
-<p>If any element of LIST is an lvalue, you can modify it by modifying
-VAR inside the loop. Conversely, if any element of LIST is NOT an
-lvalue, any attempt to modify that element will fail. In other words,
-the <code>foreach</code> loop index variable is an implicit alias for each item
-in the list that you’re looping over.
-</p>
-<p>If any part of LIST is an array, <code>foreach</code> will get very
confused if
-you add or remove elements within the loop body, for example with
-<code>splice</code>. So don’t do that.
-</p>
-<p><code>foreach</code> probably won’t do what you expect if VAR is a
tied or other
-special variable. Don’t do that either.
-</p>
-<p>As of Perl 5.22, there is an experimental variant of this loop that accepts
-a variable preceded by a backslash for VAR, in which case the items in the
-LIST must be references. The backslashed variable will become an alias
-to each referenced item in the LIST, which must be of the correct type.
-The variable needn’t be a scalar in this case, and the backslash may be
-followed by <code>my</code>. To use this form, you must enable the
<code>refaliasing</code>
-feature via <code>use feature</code>. (See <a
href="feature.html#Top">(feature)</a>. See also <a
href="#perlref-Assigning-to-References">perlref Assigning to References</a>.)
-</p>
-<p>Examples:
-</p>
-<pre class="verbatim"> for (@ary) { s/foo/bar/ }
-
- for my $elem (@elements) {
- $elem *= 2;
- }
-
- for $count (reverse(1..10), "BOOM") {
- print $count, "\n";
- sleep(1);
- }
-
- for (1..15) { print "Merry Christmas\n"; }
-
- foreach $item (split(/:[\\\n:]*/, $ENV{TERMCAP})) {
- print "Item: $item\n";
- }
-
- use feature "refaliasing";
- no warnings "experimental::refaliasing";
- foreach \my %hash (@array_of_hash_references) {
- # do something which each %hash
- }
-</pre>
-<p>Here’s how a C programmer might code up a particular algorithm in
Perl:
-</p>
-<pre class="verbatim"> for (my $i = 0; $i < @ary1; $i++) {
- for (my $j = 0; $j < @ary2; $j++) {
- if ($ary1[$i] > $ary2[$j]) {
- last; # can't go to outer :-(
- }
- $ary1[$i] += $ary2[$j];
- }
- # this is where that last takes me
- }
-</pre>
-<p>Whereas here’s how a Perl programmer more comfortable with the idiom
might
-do it:
-</p>
-<pre class="verbatim"> OUTER: for my $wid (@ary1) {
- INNER: for my $jet (@ary2) {
- next OUTER if $wid > $jet;
- $wid += $jet;
- }
- }
-</pre>
-<p>See how much easier this is? It’s cleaner, safer, and faster.
It’s
-cleaner because it’s less noisy. It’s safer because if code gets
added
-between the inner and outer loops later on, the new code won’t be
-accidentally executed. The <code>next</code> explicitly iterates the other
loop
-rather than merely terminating the inner one. And it’s faster because
-Perl executes a <code>foreach</code> statement more rapidly than it would the
-equivalent <code>for</code> loop.
-</p>
-<p>Perceptive Perl hackers may have noticed that a <code>for</code> loop has a
return
-value, and that this value can be captured by wrapping the loop in a
<code>do</code>
-block. The reward for this discovery is this cautionary advice: The
-return value of a <code>for</code> loop is unspecified and may change without
notice.
-Do not rely on it.
-</p>
-<hr>
-<a name="perlsyn-Basic-BLOCKs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Switch-Statements" accesskey="n" rel="next">perlsyn
Switch Statements</a>, Previous: <a href="#perlsyn-Foreach-Loops" accesskey="p"
rel="prev">perlsyn Foreach Loops</a>, Up: <a href="#perlsyn-DESCRIPTION"
accesskey="u" rel="up">perlsyn DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Basic-BLOCKs"></a>
-<h4 class="subsection">74.2.10 Basic BLOCKs</h4>
-
-<p>A BLOCK by itself (labeled or not) is semantically equivalent to a
-loop that executes once. Thus you can use any of the loop control
-statements in it to leave or restart the block. (Note that this is
-<em>NOT</em> true in <code>eval{}</code>, <code>sub{}</code>, or contrary to
popular belief
-<code>do{}</code> blocks, which do <em>NOT</em> count as loops.) The
<code>continue</code>
-block is optional.
-</p>
-<p>The BLOCK construct can be used to emulate case structures.
-</p>
-<pre class="verbatim"> SWITCH: {
- if (/^abc/) { $abc = 1; last SWITCH; }
- if (/^def/) { $def = 1; last SWITCH; }
- if (/^xyz/) { $xyz = 1; last SWITCH; }
- $nothing = 1;
- }
-</pre>
-<p>You’ll also find that <code>foreach</code> loop used to create a
topicalizer
-and a switch:
-</p>
-<pre class="verbatim"> SWITCH:
- for ($var) {
- if (/^abc/) { $abc = 1; last SWITCH; }
- if (/^def/) { $def = 1; last SWITCH; }
- if (/^xyz/) { $xyz = 1; last SWITCH; }
- $nothing = 1;
- }
-</pre>
-<p>Such constructs are quite frequently used, both because older versions of
-Perl had no official <code>switch</code> statement, and also because the new
version
-described immediately below remains experimental and can sometimes be
confusing.
-</p>
-<hr>
-<a name="perlsyn-Switch-Statements"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Goto" accesskey="n" rel="next">perlsyn Goto</a>,
Previous: <a href="#perlsyn-Basic-BLOCKs" accesskey="p" rel="prev">perlsyn
Basic BLOCKs</a>, Up: <a href="#perlsyn-DESCRIPTION" accesskey="u"
rel="up">perlsyn DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Switch-Statements"></a>
-<h4 class="subsection">74.2.11 Switch Statements</h4>
-
-<p>Starting from Perl 5.10.1 (well, 5.10.0, but it didn’t work
-right), you can say
-</p>
-<pre class="verbatim"> use feature "switch";
-</pre>
-<p>to enable an experimental switch feature. This is loosely based on an
-old version of a Perl 6 proposal, but it no longer resembles the Perl 6
-construct. You also get the switch feature whenever you declare that your
-code prefers to run under a version of Perl that is 5.10 or later. For
-example:
-</p>
-<pre class="verbatim"> use v5.14;
-</pre>
-<p>Under the "switch" feature, Perl gains the experimental keywords
-<code>given</code>, <code>when</code>, <code>default</code>,
<code>continue</code>, and <code>break</code>.
-Starting from Perl 5.16, one can prefix the switch
-keywords with <code>CORE::</code> to access the feature without a <code>use
feature</code>
-statement. The keywords <code>given</code> and
-<code>when</code> are analogous to <code>switch</code> and
-<code>case</code> in other languages, so the code in the previous section
could be
-rewritten as
-</p>
-<pre class="verbatim"> use v5.10.1;
- for ($var) {
- when (/^abc/) { $abc = 1 }
- when (/^def/) { $def = 1 }
- when (/^xyz/) { $xyz = 1 }
- default { $nothing = 1 }
- }
-</pre>
-<p>The <code>foreach</code> is the non-experimental way to set a topicalizer.
-If you wish to use the highly experimental <code>given</code>, that could be
-written like this:
-</p>
-<pre class="verbatim"> use v5.10.1;
- given ($var) {
- when (/^abc/) { $abc = 1 }
- when (/^def/) { $def = 1 }
- when (/^xyz/) { $xyz = 1 }
- default { $nothing = 1 }
- }
-</pre>
-<p>As of 5.14, that can also be written this way:
-</p>
-<pre class="verbatim"> use v5.14;
- for ($var) {
- $abc = 1 when /^abc/;
- $def = 1 when /^def/;
- $xyz = 1 when /^xyz/;
- default { $nothing = 1 }
- }
-</pre>
-<p>Or if you don’t care to play it safe, like this:
-</p>
-<pre class="verbatim"> use v5.14;
- given ($var) {
- $abc = 1 when /^abc/;
- $def = 1 when /^def/;
- $xyz = 1 when /^xyz/;
- default { $nothing = 1 }
- }
-</pre>
-<p>The arguments to <code>given</code> and <code>when</code> are in scalar
context,
-and <code>given</code> assigns the <code>$_</code> variable its topic value.
-</p>
-<p>Exactly what the <em>EXPR</em> argument to <code>when</code> does is hard
to describe
-precisely, but in general, it tries to guess what you want done. Sometimes
-it is interpreted as <code>$_ ~~ <em>EXPR</em></code>, and sometimes it is
not. It
-also behaves differently when lexically enclosed by a <code>given</code> block
than
-it does when dynamically enclosed by a <code>foreach</code> loop. The rules
are far
-too difficult to understand to be described here. See <a
href="#perlsyn-Experimental-Details-on-given-and-when">Experimental Details
-on given and when</a> later on.
-</p>
-<p>Due to an unfortunate bug in how <code>given</code> was implemented between
Perl 5.10
-and 5.16, under those implementations the version of <code>$_</code> governed
by
-<code>given</code> is merely a lexically scoped copy of the original, not a
-dynamically scoped alias to the original, as it would be if it were a
-<code>foreach</code> or under both the original and the current Perl 6 language
-specification. This bug was fixed in Perl
-5.18. If you really want a lexical <code>$_</code>,
-specify that explicitly, but note that <code>my $_</code>
-is now deprecated and will warn unless warnings
-have been disabled:
-</p>
-<pre class="verbatim"> given(my $_ = EXPR) { ... }
-</pre>
-<p>If your code still needs to run on older versions,
-stick to <code>foreach</code> for your topicalizer and
-you will be less unhappy.
-</p>
-<hr>
-<a name="perlsyn-Goto"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-The-Ellipsis-Statement" accesskey="n"
rel="next">perlsyn The Ellipsis Statement</a>, Previous: <a
href="#perlsyn-Switch-Statements" accesskey="p" rel="prev">perlsyn Switch
Statements</a>, Up: <a href="#perlsyn-DESCRIPTION" accesskey="u"
rel="up">perlsyn DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Goto"></a>
-<h4 class="subsection">74.2.12 Goto</h4>
-
-<p>Although not for the faint of heart, Perl does support a <code>goto</code>
-statement. There are three forms: <code>goto</code>-LABEL,
<code>goto</code>-EXPR, and
-<code>goto</code>-&NAME. A loop’s LABEL is not actually a valid
target for
-a <code>goto</code>; it’s just the name of the loop.
-</p>
-<p>The <code>goto</code>-LABEL form finds the statement labeled with LABEL and
resumes
-execution there. It may not be used to go into any construct that
-requires initialization, such as a subroutine or a <code>foreach</code> loop.
It
-also can’t be used to go into a construct that is optimized away. It
-can be used to go almost anywhere else within the dynamic scope,
-including out of subroutines, but it’s usually better to use some other
-construct such as <code>last</code> or <code>die</code>. The author of Perl
has never felt the
-need to use this form of <code>goto</code> (in Perl, that is–C is
another matter).
-</p>
-<p>The <code>goto</code>-EXPR form expects a label name, whose scope will be
resolved
-dynamically. This allows for computed <code>goto</code>s per FORTRAN, but
isn’t
-necessarily recommended if you’re optimizing for maintainability:
-</p>
-<pre class="verbatim"> goto(("FOO", "BAR",
"GLARCH")[$i]);
-</pre>
-<p>The <code>goto</code>-&NAME form is highly magical, and substitutes a
call to the
-named subroutine for the currently running subroutine. This is used by
-<code>AUTOLOAD()</code> subroutines that wish to load another subroutine and
then
-pretend that the other subroutine had been called in the first place
-(except that any modifications to <code>@_</code> in the current subroutine are
-propagated to the other subroutine.) After the <code>goto</code>, not even
<code>caller()</code>
-will be able to tell that this routine was called first.
-</p>
-<p>In almost all cases like this, it’s usually a far, far better idea to
use the
-structured control flow mechanisms of <code>next</code>, <code>last</code>, or
<code>redo</code> instead of
-resorting to a <code>goto</code>. For certain applications, the catch and
throw pair of
-<code>eval{}</code> and die() for exception processing can also be a prudent
approach.
-</p>
-<hr>
-<a name="perlsyn-The-Ellipsis-Statement"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-PODs_003a-Embedded-Documentation" accesskey="n"
rel="next">perlsyn PODs: Embedded Documentation</a>, Previous: <a
href="#perlsyn-Goto" accesskey="p" rel="prev">perlsyn Goto</a>, Up: <a
href="#perlsyn-DESCRIPTION" accesskey="u" rel="up">perlsyn DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-Ellipsis-Statement"></a>
-<h4 class="subsection">74.2.13 The Ellipsis Statement</h4>
-
-<p>Beginning in Perl 5.12, Perl accepts an ellipsis,
"<code>...</code>", as a
-placeholder for code that you haven’t implemented yet. This form of
-ellipsis, the unimplemented statement, should not be confused with the
-binary flip-flop <code>...</code> operator. One is a statement and the other
an
-operator. (Perl doesn’t usually confuse them because usually Perl can
tell
-whether it wants an operator or a statement, but see below for exceptions.)
-</p>
-<p>When Perl 5.12 or later encounters an ellipsis statement, it parses this
-without error, but if and when you should actually try to execute it, Perl
-throws an exception with the text <code>Unimplemented</code>:
-</p>
-<pre class="verbatim"> use v5.12;
- sub unimplemented { ... }
- eval { unimplemented() };
- if ($@ =~ /^Unimplemented at /) {
- say "I found an ellipsis!";
- }
-</pre>
-<p>You can only use the elliptical statement to stand in for a
-complete statement. These examples of how the ellipsis works:
-</p>
-<pre class="verbatim"> use v5.12;
- { ... }
- sub foo { ... }
- ...;
- eval { ... };
- sub somemeth {
- my $self = shift;
- ...;
- }
- $x = do {
- my $n;
- ...;
- say "Hurrah!";
- $n;
- };
-</pre>
-<p>The elliptical statement cannot stand in for an expression that
-is part of a larger statement, since the <code>...</code> is also the three-dot
-version of the flip-flop operator (see <a
href="#perlop-Range-Operators">perlop Range Operators</a>).
-</p>
-<p>These examples of attempts to use an ellipsis are syntax errors:
-</p>
-<pre class="verbatim"> use v5.12;
-
- print ...;
- open(my $fh, ">", "/dev/passwd") or ...;
- if ($condition && ... ) { say "Howdy" };
-</pre>
-<p>There are some cases where Perl can’t immediately tell the difference
-between an expression and a statement. For instance, the syntax for a
-block and an anonymous hash reference constructor look the same unless
-there’s something in the braces to give Perl a hint. The ellipsis is a
-syntax error if Perl doesn’t guess that the <code>{ ... }</code> is a
block. In that
-case, it doesn’t think the <code>...</code> is an ellipsis because
it’s expecting an
-expression instead of a statement:
-</p>
-<pre class="verbatim"> @transformed = map { ... } @input; # syntax error
-</pre>
-<p>Inside your block, you can use a <code>;</code> before the ellipsis to
denote that the
-<code>{ ... }</code> is a block and not a hash reference constructor. Now the
ellipsis
-works:
-</p>
-<pre class="verbatim"> @transformed = map {; ... } @input; # ';'
disambiguates
-</pre>
-<p>Note: Some folks colloquially refer to this bit of punctuation as a
-"yada-yada" or "triple-dot", but its true name
-is actually an ellipsis.
-</p>
-<hr>
-<a name="perlsyn-PODs_003a-Embedded-Documentation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Plain-Old-Comments-_0028Not_0021_0029" accesskey="n"
rel="next">perlsyn Plain Old Comments (Not!)</a>, Previous: <a
href="#perlsyn-The-Ellipsis-Statement" accesskey="p" rel="prev">perlsyn The
Ellipsis Statement</a>, Up: <a href="#perlsyn-DESCRIPTION" accesskey="u"
rel="up">perlsyn DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PODs_003a-Embedded-Documentation"></a>
-<h4 class="subsection">74.2.14 PODs: Embedded Documentation</h4>
-
-<p>Perl has a mechanism for intermixing documentation with source code.
-While it’s expecting the beginning of a new statement, if the compiler
-encounters a line that begins with an equal sign and a word, like this
-</p>
-<pre class="verbatim"> =head1 Here There Be Pods!
-</pre>
-<p>Then that text and all remaining text up through and including a line
-beginning with <code>=cut</code> will be ignored. The format of the
intervening
-text is described in <a href="#perlpod-NAME">perlpod NAME</a>.
-</p>
-<p>This allows you to intermix your source code
-and your documentation text freely, as in
-</p>
-<pre class="verbatim"> =item snazzle($)
-
- The snazzle() function will behave in the most spectacular
- form that you can possibly imagine, not even excepting
- cybernetic pyrotechnics.
-
- =cut back to the compiler, nuff of this pod stuff!
-
- sub snazzle($) {
- my $thingie = shift;
- .........
- }
-</pre>
-<p>Note that pod translators should look at only paragraphs beginning
-with a pod directive (it makes parsing easier), whereas the compiler
-actually knows to look for pod escapes even in the middle of a
-paragraph. This means that the following secret stuff will be
-ignored by both the compiler and the translators.
-</p>
-<pre class="verbatim"> $a=3;
- =secret stuff
- warn "Neither POD nor CODE!?"
- =cut back
- print "got $a\n";
-</pre>
-<p>You probably shouldn’t rely upon the <code>warn()</code> being podded
out forever.
-Not all pod translators are well-behaved in this regard, and perhaps
-the compiler will become pickier.
-</p>
-<p>One may also use pod directives to quickly comment out a section
-of code.
-</p>
-<hr>
-<a name="perlsyn-Plain-Old-Comments-_0028Not_0021_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Experimental-Details-on-given-and-when" accesskey="n"
rel="next">perlsyn Experimental Details on given and when</a>, Previous: <a
href="#perlsyn-PODs_003a-Embedded-Documentation" accesskey="p"
rel="prev">perlsyn PODs: Embedded Documentation</a>, Up: <a
href="#perlsyn-DESCRIPTION" accesskey="u" rel="up">perlsyn DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Plain-Old-Comments-_0028Not_0021_0029"></a>
-<h4 class="subsection">74.2.15 Plain Old Comments (Not!)</h4>
-
-<p>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 <code>eval()</code>). The syntax for this mechanism is almost the same
as for
-most C preprocessors: it matches the regular expression
-</p>
-<pre class="verbatim"> # example: '# line 42 "new_filename.plx"'
- /^\# \s*
- line \s+ (\d+) \s*
- (?:\s("?)([^"]+)\g2)? \s*
- $/x
-</pre>
-<p>with <code>$1</code> being the line number for the next line, and
<code>$3</code> being
-the optional filename (specified with or without quotes). Note that
-no whitespace may precede the <code>#</code>, unlike modern C preprocessors.
-</p>
-<p>There is a fairly obvious gotcha included with the line directive:
-Debuggers and profilers will only show the last source line to appear
-at a particular line number in a given file. Care should be taken not
-to cause line number collisions in code you’d like to debug later.
-</p>
-<p>Here are some examples that you should be able to type into your command
-shell:
-</p>
-<pre class="verbatim"> % perl
- # line 200 "bzzzt"
- # the '#' on the previous line must be the first char on line
- die 'foo';
- __END__
- foo at bzzzt line 201.
-
- % perl
- # line 200 "bzzzt"
- eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
- __END__
- foo at - line 2001.
-
- % perl
- eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
- __END__
- foo at foo bar line 200.
-
- % perl
- # line 345 "goop"
- eval "\n#line " . __LINE__ . ' "' . __FILE__
."\"\ndie 'foo'";
- print $@;
- __END__
- foo at goop line 345.
-</pre>
-<hr>
-<a name="perlsyn-Experimental-Details-on-given-and-when"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlsyn-Plain-Old-Comments-_0028Not_0021_0029"
accesskey="p" rel="prev">perlsyn Plain Old Comments (Not!)</a>, Up: <a
href="#perlsyn-DESCRIPTION" accesskey="u" rel="up">perlsyn DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Experimental-Details-on-given-and-when"></a>
-<h4 class="subsection">74.2.16 Experimental Details on given and when</h4>
-
-<p>As previously mentioned, the "switch" feature is considered highly
-experimental; it is subject to change with little notice. In particular,
-<code>when</code> has tricky behaviours that are expected to change to become
less
-tricky in the future. Do not rely upon its current (mis)implementation.
-Before Perl 5.18, <code>given</code> also had tricky behaviours that you
should still
-beware of if your code must run on older versions of Perl.
-</p>
-<p>Here is a longer example of <code>given</code>:
-</p>
-<pre class="verbatim"> use feature ":5.10";
- given ($foo) {
- when (undef) {
- say '$foo is undefined';
- }
- when ("foo") {
- say '$foo is the string "foo"';
- }
- when ([1,3,5,7,9]) {
- say '$foo is an odd digit';
- continue; # Fall through
- }
- when ($_ < 100) {
- say '$foo is numerically less than 100';
- }
- when (\&complicated_check) {
- say 'a complicated check for $foo is true';
- }
- default {
- die q(I don't know what to do with $foo);
- }
- }
-</pre>
-<p>Before Perl 5.18, <code>given(EXPR)</code> assigned the value of
<em>EXPR</em> to
-merely a lexically scoped <em><strong>copy</strong></em> (!) of
<code>$_</code>, not a dynamically
-scoped alias the way <code>foreach</code> does. That made it similar to
-</p>
-<pre class="verbatim"> do { my $_ = EXPR; ... }
-</pre>
-<p>except that the block was automatically broken out of by a successful
-<code>when</code> or an explicit <code>break</code>. Because it was only a
copy, and because
-it was only lexically scoped, not dynamically scoped, you could not do the
-things with it that you are used to in a <code>foreach</code> loop. In
particular,
-it did not work for arbitrary function calls if those functions might try
-to access $_. Best stick to <code>foreach</code> for that.
-</p>
-<p>Most of the power comes from the implicit smartmatching that can
-sometimes apply. Most of the time, <code>when(EXPR)</code> is treated as an
-implicit smartmatch of <code>$_</code>, that is, <code>$_ ~~ EXPR</code>. (See
-<a href="#perlop-Smartmatch-Operator">perlop Smartmatch Operator</a> for more
information on smartmatching.)
-But when <em>EXPR</em> is one of the 10 exceptional cases (or things like them)
-listed below, it is used directly as a boolean.
-</p>
-<dl compact="compact">
-<dt>1.</dt>
-<dd><a name="perlsyn-1_002e"></a>
-<p>A user-defined subroutine call or a method invocation.
-</p>
-</dd>
-<dt>2.</dt>
-<dd><a name="perlsyn-2_002e"></a>
-<p>A regular expression match in the form of <code>/REGEX/</code>, <code>$foo
=~ /REGEX/</code>,
-or <code>$foo =~ EXPR</code>. Also, a negated regular expression match in
-the form <code>!/REGEX/</code>, <code>$foo !~ /REGEX/</code>, or <code>$foo !~
EXPR</code>.
-</p>
-</dd>
-<dt>3.</dt>
-<dd><a name="perlsyn-3_002e"></a>
-<p>A smart match that uses an explicit <code>~~</code> operator, such as
<code>EXPR ~~ EXPR</code>.
-</p>
-<p><strong>NOTE:</strong> You will often have to use <code>$c ~~ $_</code>
because the default case
-uses <code>$_ ~~ $c</code> , which is frequentlythe opposite of what you want.
-</p>
-</dd>
-<dt>4.</dt>
-<dd><a name="perlsyn-4_002e"></a>
-<p>A boolean comparison operator such as <code>$_ < 10</code> or <code>$x
eq "abc"</code>. The
-relational operators that this applies to are the six numeric comparisons
-(<code><</code>, <code>></code>, <code><=</code>, <code>>=</code>,
<code>==</code>, and <code>!=</code>), and
-the six string comparisons (<code>lt</code>, <code>gt</code>, <code>le</code>,
<code>ge</code>, <code>eq</code>, and <code>ne</code>).
-</p>
-</dd>
-<dt>5.</dt>
-<dd><a name="perlsyn-5_002e"></a>
-<p>At least the three builtin functions <code>defined(...)</code>,
<code>exists(...)</code>, and
-<code>eof(...)</code>. We might someday add more of these later if we think
of them.
-</p>
-</dd>
-<dt>6.</dt>
-<dd><a name="perlsyn-6_002e"></a>
-<p>A negated expression, whether <code>!(EXPR)</code> or
<code>not(EXPR)</code>, or a logical
-exclusive-or, <code>(EXPR1) xor (EXPR2)</code>. The bitwise versions
(<code>~</code> and <code>^</code>)
-are not included.
-</p>
-</dd>
-<dt>7.</dt>
-<dd><a name="perlsyn-7_002e"></a>
-<p>A filetest operator, with exactly 4 exceptions: <code>-s</code>,
<code>-M</code>, <code>-A</code>, and
-<code>-C</code>, as these return numerical values, not boolean ones. The
<code>-z</code>
-filetest operator is not included in the exception list.
-</p>
-</dd>
-<dt>8.</dt>
-<dd><a name="perlsyn-8_002e"></a>
-<p>The <code>..</code> and <code>...</code> flip-flop operators. Note that
the <code>...</code> flip-flop
-operator is completely different from the <code>...</code> elliptical statement
-just described.
-</p>
-</dd>
-</dl>
-
-<p>In those 8 cases above, the value of EXPR is used directly as a boolean, so
-no smartmatching is done. You may think of <code>when</code> as a
smartsmartmatch.
-</p>
-<p>Furthermore, Perl inspects the operands of logical operators to
-decide whether to use smartmatching for each one by applying the
-above test to the operands:
-</p>
-<dl compact="compact">
-<dt>9.</dt>
-<dd><a name="perlsyn-9_002e"></a>
-<p>If EXPR is <code>EXPR1 && EXPR2</code> or <code>EXPR1 and
EXPR2</code>, the test is applied
-<em>recursively</em> to both EXPR1 and EXPR2.
-Only if <em>both</em> operands also pass the
-test, <em>recursively</em>, will the expression be treated as boolean.
Otherwise,
-smartmatching is used.
-</p>
-</dd>
-<dt>10.</dt>
-<dd><a name="perlsyn-10_002e"></a>
-<p>If EXPR is <code>EXPR1 || EXPR2</code>, <code>EXPR1 // EXPR2</code>, or
<code>EXPR1 or EXPR2</code>, the
-test is applied <em>recursively</em> to EXPR1 only (which might itself be a
-higher-precedence AND operator, for example, and thus subject to the
-previous rule), not to EXPR2. If EXPR1 is to use smartmatching, then EXPR2
-also does so, no matter what EXPR2 contains. But if EXPR2 does not get to
-use smartmatching, then the second argument will not be either. This is
-quite different from the <code>&&</code> case just described, so be
careful.
-</p>
-</dd>
-</dl>
-
-<p>These rules are complicated, but the goal is for them to do what you want
-(even if you don’t quite understand why they are doing it). For example:
-</p>
-<pre class="verbatim"> when (/^\d+$/ && $_ < 75) { ... }
-</pre>
-<p>will be treated as a boolean match because the rules say both
-a regex match and an explicit test on <code>$_</code> will be treated
-as boolean.
-</p>
-<p>Also:
-</p>
-<pre class="verbatim"> when ([qw(foo bar)] && /baz/) { ... }
-</pre>
-<p>will use smartmatching because only <em>one</em> of the operands is a
boolean:
-the other uses smartmatching, and that wins.
-</p>
-<p>Further:
-</p>
-<pre class="verbatim"> when ([qw(foo bar)] || /^baz/) { ... }
-</pre>
-<p>will use smart matching (only the first operand is considered), whereas
-</p>
-<pre class="verbatim"> when (/^baz/ || [qw(foo bar)]) { ... }
-</pre>
-<p>will test only the regex, which causes both operands to be
-treated as boolean. Watch out for this one, then, because an
-arrayref is always a true value, which makes it effectively
-redundant. Not a good idea.
-</p>
-<p>Tautologous boolean operators are still going to be optimized
-away. Don’t be tempted to write
-</p>
-<pre class="verbatim"> when ("foo" or "bar") { ... }
-</pre>
-<p>This will optimize down to <code>"foo"</code>, so
<code>"bar"</code> will never be considered (even
-though the rules say to use a smartmatch
-on <code>"foo"</code>). For an alternation like
-this, an array ref will work, because this will instigate smartmatching:
-</p>
-<pre class="verbatim"> when ([qw(foo bar)] { ... }
-</pre>
-<p>This is somewhat equivalent to the C-style switch statement’s
fallthrough
-functionality (not to be confused with <em>Perl’s</em> fallthrough
-functionality–see below), wherein the same block is used for several
-<code>case</code> statements.
-</p>
-<p>Another useful shortcut is that, if you use a literal array or hash as the
-argument to <code>given</code>, it is turned into a reference. So
<code>given(@foo)</code> is
-the same as <code>given(address@hidden)</code>, for example.
-</p>
-<p><code>default</code> behaves exactly like <code>when(1 == 1)</code>, which
is
-to say that it always matches.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlsyn-Breaking-out"
accesskey="1">perlsyn Breaking out</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsyn-Fall_002dthrough"
accesskey="2">perlsyn Fall-through</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlsyn-Return-value"
accesskey="3">perlsyn Return value</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Switching-in-a-loop" accesskey="4">perlsyn Switching in a
loop</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlsyn-Differences-from-Perl-6" accesskey="5">perlsyn Differences from
Perl 6</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlsyn-Breaking-out"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Fall_002dthrough" accesskey="n" rel="next">perlsyn
Fall-through</a>, Up: <a href="#perlsyn-Experimental-Details-on-given-and-when"
accesskey="u" rel="up">perlsyn Experimental Details on given and when</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Breaking-out"></a>
-<h4 class="subsubsection">74.2.16.1 Breaking out</h4>
-
-<p>You can use the <code>break</code> keyword to break out of the enclosing
-<code>given</code> block. Every <code>when</code> block is implicitly ended
with
-a <code>break</code>.
-</p>
-<hr>
-<a name="perlsyn-Fall_002dthrough"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Return-value" accesskey="n" rel="next">perlsyn Return
value</a>, Previous: <a href="#perlsyn-Breaking-out" accesskey="p"
rel="prev">perlsyn Breaking out</a>, Up: <a
href="#perlsyn-Experimental-Details-on-given-and-when" accesskey="u"
rel="up">perlsyn Experimental Details on given and when</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Fall_002dthrough"></a>
-<h4 class="subsubsection">74.2.16.2 Fall-through</h4>
-
-<p>You can use the <code>continue</code> keyword to fall through from one
-case to the next:
-</p>
-<pre class="verbatim"> given($foo) {
- when (/x/) { say '$foo contains an x'; continue }
- when (/y/) { say '$foo contains a y' }
- default { say '$foo does not contain a y' }
- }
-</pre>
-<hr>
-<a name="perlsyn-Return-value"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Switching-in-a-loop" accesskey="n" rel="next">perlsyn
Switching in a loop</a>, Previous: <a href="#perlsyn-Fall_002dthrough"
accesskey="p" rel="prev">perlsyn Fall-through</a>, Up: <a
href="#perlsyn-Experimental-Details-on-given-and-when" accesskey="u"
rel="up">perlsyn Experimental Details on given and when</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Return-value"></a>
-<h4 class="subsubsection">74.2.16.3 Return value</h4>
-
-<p>When a <code>given</code> statement is also a valid expression (for example,
-when it’s the last statement of a block), it evaluates to:
-</p>
-<ul>
-<li> An empty list as soon as an explicit <code>break</code> is encountered.
-
-</li><li> The value of the last evaluated expression of the successful
-<code>when</code>/<code>default</code> clause, if there happens to be one.
-
-</li><li> The value of the last evaluated expression of the <code>given</code>
block if no
-condition is true.
-
-</li></ul>
-
-<p>In both last cases, the last expression is evaluated in the context that
-was applied to the <code>given</code> block.
-</p>
-<p>Note that, unlike <code>if</code> and <code>unless</code>, failed
<code>when</code> statements always
-evaluate to an empty list.
-</p>
-<pre class="verbatim"> my $price = do {
- given ($item) {
- when (["pear", "apple"]) { 1 }
- break when "vote"; # My vote cannot be bought
- 1e10 when /Mona Lisa/;
- "unknown";
- }
- };
-</pre>
-<p>Currently, <code>given</code> blocks can’t always
-be used as proper expressions. This
-may be addressed in a future version of Perl.
-</p>
-<hr>
-<a name="perlsyn-Switching-in-a-loop"></a>
-<div class="header">
-<p>
-Next: <a href="#perlsyn-Differences-from-Perl-6" accesskey="n"
rel="next">perlsyn Differences from Perl 6</a>, Previous: <a
href="#perlsyn-Return-value" accesskey="p" rel="prev">perlsyn Return value</a>,
Up: <a href="#perlsyn-Experimental-Details-on-given-and-when" accesskey="u"
rel="up">perlsyn Experimental Details on given and when</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Switching-in-a-loop"></a>
-<h4 class="subsubsection">74.2.16.4 Switching in a loop</h4>
-
-<p>Instead of using <code>given()</code>, you can use a <code>foreach()</code>
loop.
-For example, here’s one way to count how many times a particular
-string occurs in an array:
-</p>
-<pre class="verbatim"> use v5.10.1;
- my $count = 0;
- for (@array) {
- when ("foo") { ++$count }
- }
- print "address@hidden contains $count copies of 'foo'\n";
-</pre>
-<p>Or in a more recent version:
-</p>
-<pre class="verbatim"> use v5.14;
- my $count = 0;
- for (@array) {
- ++$count when "foo";
- }
- print "address@hidden contains $count copies of 'foo'\n";
-</pre>
-<p>At the end of all <code>when</code> blocks, there is an implicit
<code>next</code>.
-You can override that with an explicit <code>last</code> if you’re
-interested in only the first match alone.
-</p>
-<p>This doesn’t work if you explicitly specify a loop variable, as
-in <code>for $item (@array)</code>. You have to use the default variable
<code>$_</code>.
-</p>
-<hr>
-<a name="perlsyn-Differences-from-Perl-6"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlsyn-Switching-in-a-loop" accesskey="p"
rel="prev">perlsyn Switching in a loop</a>, Up: <a
href="#perlsyn-Experimental-Details-on-given-and-when" accesskey="u"
rel="up">perlsyn Experimental Details on given and when</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Differences-from-Perl-6"></a>
-<h4 class="subsubsection">74.2.16.5 Differences from Perl 6</h4>
-
-<p>The Perl 5 smartmatch and <code>given</code>/<code>when</code> constructs
are not compatible
-with their Perl 6 analogues. The most visible difference and least
-important difference is that, in Perl 5, parentheses are required around
-the argument to <code>given()</code> and <code>when()</code> (except when this
last one is used
-as a statement modifier). Parentheses in Perl 6 are always optional in a
-control construct such as <code>if()</code>, <code>while()</code>, or
<code>when()</code>; they can’t be
-made optional in Perl 5 without a great deal of potential confusion,
-because Perl 5 would parse the expression
-</p>
-<pre class="verbatim"> given $foo {
- ...
- }
-</pre>
-<p>as though the argument to <code>given</code> were an element of the hash
-<code>%foo</code>, interpreting the braces as hash-element syntax.
-</p>
-<p>However, their are many, many other differences. For example,
-this works in Perl 5:
-</p>
-<pre class="verbatim"> use v5.12;
- my @primary = ("red", "blue", "green");
-
- if (@primary ~~ "red") {
- say "primary smartmatches red";
- }
-
- if ("red" ~~ @primary) {
- say "red smartmatches primary";
- }
-
- say "that's all, folks!";
-</pre>
-<p>But it doesn’t work at all in Perl 6. Instead, you should
-use the (parallelizable) <code>any</code> operator:
-</p>
-<pre class="verbatim"> if any(@primary) eq "red" {
- say "primary smartmatches red";
- }
-
- if "red" eq any(@primary) {
- say "red smartmatches primary";
- }
-</pre>
-<p>The table of smartmatches in <a href="#perlop-Smartmatch-Operator">perlop
Smartmatch Operator</a> is not
-identical to that proposed by the Perl 6 specification, mainly due to
-differences between Perl 6’s and Perl 5’s data models, but also
because
-the Perl 6 spec has changed since Perl 5 rushed into early adoption.
-</p>
-<p>In Perl 6, <code>when()</code> will always do an implicit smartmatch with
its
-argument, while in Perl 5 it is convenient (albeit potentially confusing) to
-suppress this implicit smartmatch in various rather loosely-defined
-situations, as roughly outlined above. (The difference is largely because
-Perl 5 does not have, even internally, a boolean type.)
-</p>
-<hr>
-<a name="perlthrtut"></a>
-<div class="header">
-<p>
-Next: <a href="#perltie" accesskey="n" rel="next">perltie</a>, Previous: <a
href="#perlsyn" accesskey="p" rel="prev">perlsyn</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlthrtut-1"></a>
-<h2 class="chapter">75 perlthrtut</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlthrtut-NAME"
accesskey="1">perlthrtut NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlthrtut-DESCRIPTION"
accesskey="2">perlthrtut DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-What-Is-A-Thread-Anyway_003f" accesskey="3">perlthrtut What
Is A Thread Anyway?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Threaded-Program-Models" accesskey="4">perlthrtut Threaded
Program Models</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-What-kind-of-threads-are-Perl-threads_003f"
accesskey="5">perlthrtut What kind of threads are Perl
threads?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Thread_002dSafe-Modules" accesskey="6">perlthrtut Thread-Safe
Modules</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlthrtut-Thread-Basics"
accesskey="7">perlthrtut Thread Basics</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Threads-And-Data" accesskey="8">perlthrtut Threads And
Data</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Synchronization-and-control" accesskey="9">perlthrtut
Synchronization and control</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-General-Thread-Utility-Routines">perlthrtut General Thread
Utility Routines</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-A-Complete-Example">perlthrtut A Complete
Example</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Different-implementations-of-threads">perlthrtut Different
implementations of threads</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Performance-considerations">perlthrtut Performance
considerations</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Process_002dscope-Changes">perlthrtut Process-scope
Changes</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Thread_002dSafety-of-System-Libraries">perlthrtut
Thread-Safety of System Libraries</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Conclusion">perlthrtut
Conclusion</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-SEE-ALSO">perlthrtut SEE
ALSO</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Bibliography">perlthrtut
Bibliography</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Acknowledgements">perlthrtut
Acknowledgements</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-AUTHOR">perlthrtut AUTHOR</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Copyrights">perlthrtut
Copyrights</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlthrtut-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-DESCRIPTION" accesskey="n" rel="next">perlthrtut
DESCRIPTION</a>, Up: <a href="#perlthrtut" accesskey="u"
rel="up">perlthrtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-74"></a>
-<h3 class="section">75.1 NAME</h3>
-
-<p>perlthrtut - Tutorial on threads in Perl
-</p>
-<hr>
-<a name="perlthrtut-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-What-Is-A-Thread-Anyway_003f" accesskey="n"
rel="next">perlthrtut What Is A Thread Anyway?</a>, Previous: <a
href="#perlthrtut-NAME" accesskey="p" rel="prev">perlthrtut NAME</a>, Up: <a
href="#perlthrtut" accesskey="u" rel="up">perlthrtut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-73"></a>
-<h3 class="section">75.2 DESCRIPTION</h3>
-
-<p>This tutorial describes the use of Perl interpreter threads (sometimes
-referred to as <em>ithreads</em>). In this
-model, each thread runs in its own Perl interpreter, and any data sharing
-between threads must be explicit. The user-level interface for
<em>ithreads</em>
-uses the <a href="threads.html#Top">(threads)</a> class.
-</p>
-<p><strong>NOTE</strong>: There was another older Perl threading flavor called
the 5.005 model
-that used the <a href="threads.html#Top">(threads)</a> class. This old model
was known to have problems, is
-deprecated, and was removed for release 5.10. You are
-strongly encouraged to migrate any existing 5.005 threads code to the new
-model as soon as possible.
-</p>
-<p>You can see which (or neither) threading flavour you have by
-running <code>perl -V</code> and looking at the <code>Platform</code> section.
-If you have <code>useithreads=define</code> you have ithreads, if you
-have <code>use5005threads=define</code> you have 5.005 threads.
-If you have neither, you don’t have any thread support built in.
-If you have both, you are in trouble.
-</p>
-<p>The <a href="threads.html#Top">(threads)</a> and <a
href="threads-shared.html#Top">(threads-shared)</a> modules are included in the
core Perl
-distribution. Additionally, they are maintained as a separate modules on
-CPAN, so you can check there for any updates.
-</p>
-<hr>
-<a name="perlthrtut-What-Is-A-Thread-Anyway_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Threaded-Program-Models" accesskey="n"
rel="next">perlthrtut Threaded Program Models</a>, Previous: <a
href="#perlthrtut-DESCRIPTION" accesskey="p" rel="prev">perlthrtut
DESCRIPTION</a>, Up: <a href="#perlthrtut" accesskey="u"
rel="up">perlthrtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="What-Is-A-Thread-Anyway_003f"></a>
-<h3 class="section">75.3 What Is A Thread Anyway?</h3>
-
-<p>A thread is a flow of control through a program with a single
-execution point.
-</p>
-<p>Sounds an awful lot like a process, doesn’t it? Well, it should.
-Threads are one of the pieces of a process. Every process has at least
-one thread and, up until now, every process running Perl had only one
-thread. With 5.8, though, you can create extra threads. We’re going
-to show you how, when, and why.
-</p>
-<hr>
-<a name="perlthrtut-Threaded-Program-Models"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-What-kind-of-threads-are-Perl-threads_003f"
accesskey="n" rel="next">perlthrtut What kind of threads are Perl threads?</a>,
Previous: <a href="#perlthrtut-What-Is-A-Thread-Anyway_003f" accesskey="p"
rel="prev">perlthrtut What Is A Thread Anyway?</a>, Up: <a href="#perlthrtut"
accesskey="u" rel="up">perlthrtut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Threaded-Program-Models"></a>
-<h3 class="section">75.4 Threaded Program Models</h3>
-
-<p>There are three basic ways that you can structure a threaded
-program. Which model you choose depends on what you need your program
-to do. For many non-trivial threaded programs, you’ll need to choose
-different models for different pieces of your program.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlthrtut-Boss_002fWorker"
accesskey="1">perlthrtut Boss/Worker</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlthrtut-Work-Crew"
accesskey="2">perlthrtut Work Crew</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlthrtut-Pipeline"
accesskey="3">perlthrtut Pipeline</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlthrtut-Boss_002fWorker"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Work-Crew" accesskey="n" rel="next">perlthrtut Work
Crew</a>, Up: <a href="#perlthrtut-Threaded-Program-Models" accesskey="u"
rel="up">perlthrtut Threaded Program Models</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Boss_002fWorker"></a>
-<h4 class="subsection">75.4.1 Boss/Worker</h4>
-
-<p>The boss/worker model usually has one <em>boss</em> thread and one or more
-<em>worker</em> threads. The boss thread gathers or generates tasks that need
-to be done, then parcels those tasks out to the appropriate worker
-thread.
-</p>
-<p>This model is common in GUI and server programs, where a main thread
-waits for some event and then passes that event to the appropriate
-worker threads for processing. Once the event has been passed on, the
-boss thread goes back to waiting for another event.
-</p>
-<p>The boss thread does relatively little work. While tasks aren’t
-necessarily performed faster than with any other method, it tends to
-have the best user-response times.
-</p>
-<hr>
-<a name="perlthrtut-Work-Crew"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Pipeline" accesskey="n" rel="next">perlthrtut
Pipeline</a>, Previous: <a href="#perlthrtut-Boss_002fWorker" accesskey="p"
rel="prev">perlthrtut Boss/Worker</a>, Up: <a
href="#perlthrtut-Threaded-Program-Models" accesskey="u" rel="up">perlthrtut
Threaded Program Models</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Work-Crew"></a>
-<h4 class="subsection">75.4.2 Work Crew</h4>
-
-<p>In the work crew model, several threads are created that do
-essentially the same thing to different pieces of data. It closely
-mirrors classical parallel processing and vector processors, where a
-large array of processors do the exact same thing to many pieces of
-data.
-</p>
-<p>This model is particularly useful if the system running the program
-will distribute multiple threads across different processors. It can
-also be useful in ray tracing or rendering engines, where the
-individual threads can pass on interim results to give the user visual
-feedback.
-</p>
-<hr>
-<a name="perlthrtut-Pipeline"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlthrtut-Work-Crew" accesskey="p" rel="prev">perlthrtut
Work Crew</a>, Up: <a href="#perlthrtut-Threaded-Program-Models" accesskey="u"
rel="up">perlthrtut Threaded Program Models</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Pipeline"></a>
-<h4 class="subsection">75.4.3 Pipeline</h4>
-
-<p>The pipeline model divides up a task into a series of steps, and
-passes the results of one step on to the thread processing the
-next. Each thread does one thing to each piece of data and passes the
-results to the next thread in line.
-</p>
-<p>This model makes the most sense if you have multiple processors so two
-or more threads will be executing in parallel, though it can often
-make sense in other contexts as well. It tends to keep the individual
-tasks small and simple, as well as allowing some parts of the pipeline
-to block (on I/O or system calls, for example) while other parts keep
-going. If you’re running different parts of the pipeline on different
-processors you may also take advantage of the caches on each
-processor.
-</p>
-<p>This model is also handy for a form of recursive programming where,
-rather than having a subroutine call itself, it instead creates
-another thread. Prime and Fibonacci generators both map well to this
-form of the pipeline model. (A version of a prime number generator is
-presented later on.)
-</p>
-<hr>
-<a name="perlthrtut-What-kind-of-threads-are-Perl-threads_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Thread_002dSafe-Modules" accesskey="n"
rel="next">perlthrtut Thread-Safe Modules</a>, Previous: <a
href="#perlthrtut-Threaded-Program-Models" accesskey="p" rel="prev">perlthrtut
Threaded Program Models</a>, Up: <a href="#perlthrtut" accesskey="u"
rel="up">perlthrtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="What-kind-of-threads-are-Perl-threads_003f"></a>
-<h3 class="section">75.5 What kind of threads are Perl threads?</h3>
-
-<p>If you have experience with other thread implementations, you might
-find that things aren’t quite what you expect. It’s very
important to
-remember when dealing with Perl threads that <em>Perl Threads Are Not X
-Threads</em> for all values of X. They aren’t POSIX threads, or
-DecThreads, or Java’s Green threads, or Win32 threads. There are
-similarities, and the broad concepts are the same, but if you start
-looking for implementation details you’re going to be either
-disappointed or confused. Possibly both.
-</p>
-<p>This is not to say that Perl threads are completely different from
-everything that’s ever come before. They’re not. Perl’s
threading
-model owes a lot to other thread models, especially POSIX. Just as
-Perl is not C, though, Perl threads are not POSIX threads. So if you
-find yourself looking for mutexes, or thread priorities, it’s time to
-step back a bit and think about what you want to do and how Perl can
-do it.
-</p>
-<p>However, it is important to remember that Perl threads cannot magically
-do things unless your operating system’s threads allow it. So if your
-system blocks the entire process on <code>sleep()</code>, Perl usually will,
as well.
-</p>
-<p><strong>Perl Threads Are Different.</strong>
-</p>
-<hr>
-<a name="perlthrtut-Thread_002dSafe-Modules"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Thread-Basics" accesskey="n" rel="next">perlthrtut
Thread Basics</a>, Previous: <a
href="#perlthrtut-What-kind-of-threads-are-Perl-threads_003f" accesskey="p"
rel="prev">perlthrtut What kind of threads are Perl threads?</a>, Up: <a
href="#perlthrtut" accesskey="u" rel="up">perlthrtut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Thread_002dSafe-Modules"></a>
-<h3 class="section">75.6 Thread-Safe Modules</h3>
-
-<p>The addition of threads has changed Perl’s internals
-substantially. There are implications for people who write
-modules with XS code or external libraries. However, since Perl data is
-not shared among threads by default, Perl modules stand a high chance of
-being thread-safe or can be made thread-safe easily. Modules that are not
-tagged as thread-safe should be tested or code reviewed before being used
-in production code.
-</p>
-<p>Not all modules that you might use are thread-safe, and you should
-always assume a module is unsafe unless the documentation says
-otherwise. This includes modules that are distributed as part of the
-core. Threads are a relatively new feature, and even some of the standard
-modules aren’t thread-safe.
-</p>
-<p>Even if a module is thread-safe, it doesn’t mean that the module is
optimized
-to work well with threads. A module could possibly be rewritten to utilize
-the new features in threaded Perl to increase performance in a threaded
-environment.
-</p>
-<p>If you’re using a module that’s not thread-safe for some
reason, you
-can protect yourself by using it from one, and only one thread at all.
-If you need multiple threads to access such a module, you can use semaphores
and
-lots of programming discipline to control access to it. Semaphores
-are covered in <a href="#perlthrtut-Basic-semaphores">Basic semaphores</a>.
-</p>
-<p>See also <a
href="#perlthrtut-Thread_002dSafety-of-System-Libraries">Thread-Safety of
System Libraries</a>.
-</p>
-<hr>
-<a name="perlthrtut-Thread-Basics"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Threads-And-Data" accesskey="n"
rel="next">perlthrtut Threads And Data</a>, Previous: <a
href="#perlthrtut-Thread_002dSafe-Modules" accesskey="p" rel="prev">perlthrtut
Thread-Safe Modules</a>, Up: <a href="#perlthrtut" accesskey="u"
rel="up">perlthrtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Thread-Basics"></a>
-<h3 class="section">75.7 Thread Basics</h3>
-
-<p>The <a href="threads.html#Top">(threads)</a> module provides the basic
functions you need to write
-threaded programs. In the following sections, we’ll cover the basics,
-showing you what you need to do to create a threaded program. After
-that, we’ll go over some of the features of the <a
href="threads.html#Top">(threads)</a> module that
-make threaded programming easier.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Basic-Thread-Support" accesskey="1">perlthrtut Basic Thread
Support</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-A-Note-about-the-Examples" accesskey="2">perlthrtut A Note
about the Examples</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Creating-Threads" accesskey="3">perlthrtut Creating
Threads</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Waiting-For-A-Thread-To-Exit" accesskey="4">perlthrtut
Waiting For A Thread To Exit</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Ignoring-A-Thread" accesskey="5">perlthrtut Ignoring A
Thread</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Process-and-Thread-Termination" accesskey="6">perlthrtut
Process and Thread Termination</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlthrtut-Basic-Thread-Support"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-A-Note-about-the-Examples" accesskey="n"
rel="next">perlthrtut A Note about the Examples</a>, Up: <a
href="#perlthrtut-Thread-Basics" accesskey="u" rel="up">perlthrtut Thread
Basics</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Basic-Thread-Support"></a>
-<h4 class="subsection">75.7.1 Basic Thread Support</h4>
-
-<p>Thread support is a Perl compile-time option. It’s something
that’s
-turned on or off when Perl is built at your site, rather than when
-your programs are compiled. If your Perl wasn’t compiled with thread
-support enabled, then any attempt to use threads will fail.
-</p>
-<p>Your programs can use the Config module to check whether threads are
-enabled. If your program can’t run without them, you can say something
-like:
-</p>
-<pre class="verbatim"> use Config;
- $Config{useithreads} or
- die('Recompile Perl with threads to run this program.');
-</pre>
-<p>A possibly-threaded program using a possibly-threaded module might
-have code like this:
-</p>
-<pre class="verbatim"> use Config;
- use MyMod;
-
- BEGIN {
- if ($Config{useithreads}) {
- # We have threads
- require MyMod_threaded;
- import MyMod_threaded;
- } else {
- require MyMod_unthreaded;
- import MyMod_unthreaded;
- }
- }
-</pre>
-<p>Since code that runs both with and without threads is usually pretty
-messy, it’s best to isolate the thread-specific code in its own
-module. In our example above, that’s what <code>MyMod_threaded</code>
is, and it’s
-only imported if we’re running on a threaded Perl.
-</p>
-<hr>
-<a name="perlthrtut-A-Note-about-the-Examples"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Creating-Threads" accesskey="n"
rel="next">perlthrtut Creating Threads</a>, Previous: <a
href="#perlthrtut-Basic-Thread-Support" accesskey="p" rel="prev">perlthrtut
Basic Thread Support</a>, Up: <a href="#perlthrtut-Thread-Basics" accesskey="u"
rel="up">perlthrtut Thread Basics</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="A-Note-about-the-Examples"></a>
-<h4 class="subsection">75.7.2 A Note about the Examples</h4>
-
-<p>In a real situation, care should be taken that all threads are finished
-executing before the program exits. That care has <strong>not</strong> been
taken in these
-examples in the interest of simplicity. Running these examples <em>as is</em>
will
-produce error messages, usually caused by the fact that there are still
-threads running when the program exits. You should not be alarmed by this.
-</p>
-<hr>
-<a name="perlthrtut-Creating-Threads"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Waiting-For-A-Thread-To-Exit" accesskey="n"
rel="next">perlthrtut Waiting For A Thread To Exit</a>, Previous: <a
href="#perlthrtut-A-Note-about-the-Examples" accesskey="p"
rel="prev">perlthrtut A Note about the Examples</a>, Up: <a
href="#perlthrtut-Thread-Basics" accesskey="u" rel="up">perlthrtut Thread
Basics</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Creating-Threads"></a>
-<h4 class="subsection">75.7.3 Creating Threads</h4>
-
-<p>The <a href="threads.html#Top">(threads)</a> module provides the tools you
need to create new
-threads. Like any other module, you need to tell Perl that you want to use
-it; <code>use threads;</code> imports all the pieces you need to create basic
-threads.
-</p>
-<p>The simplest, most straightforward way to create a thread is with
<code>create()</code>:
-</p>
-<pre class="verbatim"> use threads;
-
- my $thr = threads->create(\&sub1);
-
- sub sub1 {
- print("In the thread\n");
- }
-</pre>
-<p>The <code>create()</code> method takes a reference to a subroutine and
creates a new
-thread that starts executing in the referenced subroutine. Control
-then passes both to the subroutine and the caller.
-</p>
-<p>If you need to, your program can pass parameters to the subroutine as
-part of the thread startup. Just include the list of parameters as
-part of the <code>threads->create()</code> call, like this:
-</p>
-<pre class="verbatim"> use threads;
-
- my $Param3 = 'foo';
- my $thr1 = threads->create(\&sub1, 'Param 1', 'Param 2', $Param3);
- my @ParamList = (42, 'Hello', 3.14);
- my $thr2 = threads->create(\&sub1, @ParamList);
- my $thr3 = threads->create(\&sub1, qw(Param1 Param2 Param3));
-
- sub sub1 {
- my @InboundParameters = @_;
- print("In the thread\n");
- print('Got parameters >', join('<>',@InboundParameters),
"<\n");
- }
-</pre>
-<p>The last example illustrates another feature of threads. You can spawn
-off several threads using the same subroutine. Each thread executes
-the same subroutine, but in a separate thread with a separate
-environment and potentially separate arguments.
-</p>
-<p><code>new()</code> is a synonym for <code>create()</code>.
-</p>
-<hr>
-<a name="perlthrtut-Waiting-For-A-Thread-To-Exit"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Ignoring-A-Thread" accesskey="n"
rel="next">perlthrtut Ignoring A Thread</a>, Previous: <a
href="#perlthrtut-Creating-Threads" accesskey="p" rel="prev">perlthrtut
Creating Threads</a>, Up: <a href="#perlthrtut-Thread-Basics" accesskey="u"
rel="up">perlthrtut Thread Basics</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Waiting-For-A-Thread-To-Exit"></a>
-<h4 class="subsection">75.7.4 Waiting For A Thread To Exit</h4>
-
-<p>Since threads are also subroutines, they can return values. To wait
-for a thread to exit and extract any values it might return, you can
-use the <code>join()</code> method:
-</p>
-<pre class="verbatim"> use threads;
-
- my ($thr) = threads->create(\&sub1);
-
- my @ReturnData = $thr->join();
- print('Thread returned ', join(', ', @ReturnData), "\n");
-
- sub sub1 { return ('Fifty-six', 'foo', 2); }
-</pre>
-<p>In the example above, the <code>join()</code> method returns as soon as the
thread
-ends. In addition to waiting for a thread to finish and gathering up
-any values that the thread might have returned, <code>join()</code> also
performs
-any OS cleanup necessary for the thread. That cleanup might be
-important, especially for long-running programs that spawn lots of
-threads. If you don’t want the return values and don’t want to
wait
-for the thread to finish, you should call the <code>detach()</code> method
-instead, as described next.
-</p>
-<p>NOTE: In the example above, the thread returns a list, thus necessitating
-that the thread creation call be made in list context (i.e., <code>my
($thr)</code>).
-See <a
href="threads.html#g_t_0024thr_002d_003ejoin_0028_0029">(threads)$thr->join()</a>
and <a href="threads.html#THREAD-CONTEXT">(threads)THREAD CONTEXT</a> for more
-details on thread context and return values.
-</p>
-<hr>
-<a name="perlthrtut-Ignoring-A-Thread"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Process-and-Thread-Termination" accesskey="n"
rel="next">perlthrtut Process and Thread Termination</a>, Previous: <a
href="#perlthrtut-Waiting-For-A-Thread-To-Exit" accesskey="p"
rel="prev">perlthrtut Waiting For A Thread To Exit</a>, Up: <a
href="#perlthrtut-Thread-Basics" accesskey="u" rel="up">perlthrtut Thread
Basics</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Ignoring-A-Thread"></a>
-<h4 class="subsection">75.7.5 Ignoring A Thread</h4>
-
-<p><code>join()</code> does three things: it waits for a thread to exit,
cleans up
-after it, and returns any data the thread may have produced. But what
-if you’re not interested in the thread’s return values, and you
don’t
-really care when the thread finishes? All you want is for the thread
-to get cleaned up after when it’s done.
-</p>
-<p>In this case, you use the <code>detach()</code> method. Once a thread is
detached,
-it’ll run until it’s finished; then Perl will clean up after it
-automatically.
-</p>
-<pre class="verbatim"> use threads;
-
- my $thr = threads->create(\&sub1); # Spawn the thread
-
- $thr->detach(); # Now we officially don't care any more
-
- sleep(15); # Let thread run for awhile
-
- sub sub1 {
- my $count = 0;
- while (1) {
- $count++;
- print("\$count is $count\n");
- sleep(1);
- }
- }
-</pre>
-<p>Once a thread is detached, it may not be joined, and any return data
-that it might have produced (if it was done and waiting for a join) is
-lost.
-</p>
-<p><code>detach()</code> can also be called as a class method to allow a
thread to
-detach itself:
-</p>
-<pre class="verbatim"> use threads;
-
- my $thr = threads->create(\&sub1);
-
- sub sub1 {
- threads->detach();
- # Do more work
- }
-</pre>
-<hr>
-<a name="perlthrtut-Process-and-Thread-Termination"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlthrtut-Ignoring-A-Thread" accesskey="p"
rel="prev">perlthrtut Ignoring A Thread</a>, Up: <a
href="#perlthrtut-Thread-Basics" accesskey="u" rel="up">perlthrtut Thread
Basics</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Process-and-Thread-Termination"></a>
-<h4 class="subsection">75.7.6 Process and Thread Termination</h4>
-
-<p>With threads one must be careful to make sure they all have a chance to
-run to completion, assuming that is what you want.
-</p>
-<p>An action that terminates a process will terminate <em>all</em> running
-threads. die() and exit() have this property,
-and perl does an exit when the main thread exits,
-perhaps implicitly by falling off the end of your code,
-even if that’s not what you want.
-</p>
-<p>As an example of this case, this code prints the message
-"Perl exited with active threads: 2 running and unjoined":
-</p>
-<pre class="verbatim"> use threads;
- my $thr1 = threads->new(\&thrsub, "test1");
- my $thr2 = threads->new(\&thrsub, "test2");
- sub thrsub {
- my ($message) = @_;
- sleep 1;
- print "thread $message\n";
- }
-</pre>
-<p>But when the following lines are added at the end:
-</p>
-<pre class="verbatim"> $thr1->join();
- $thr2->join();
-</pre>
-<p>it prints two lines of output, a perhaps more useful outcome.
-</p>
-<hr>
-<a name="perlthrtut-Threads-And-Data"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Synchronization-and-control" accesskey="n"
rel="next">perlthrtut Synchronization and control</a>, Previous: <a
href="#perlthrtut-Thread-Basics" accesskey="p" rel="prev">perlthrtut Thread
Basics</a>, Up: <a href="#perlthrtut" accesskey="u" rel="up">perlthrtut</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Threads-And-Data"></a>
-<h3 class="section">75.8 Threads And Data</h3>
-
-<p>Now that we’ve covered the basics of threads, it’s time for our
next
-topic: Data. Threading introduces a couple of complications to data
-access that non-threaded programs never need to worry about.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Shared-And-Unshared-Data" accesskey="1">perlthrtut Shared And
Unshared Data</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Thread-Pitfalls_003a-Races" accesskey="2">perlthrtut Thread
Pitfalls: Races</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlthrtut-Shared-And-Unshared-Data"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Thread-Pitfalls_003a-Races" accesskey="n"
rel="next">perlthrtut Thread Pitfalls: Races</a>, Up: <a
href="#perlthrtut-Threads-And-Data" accesskey="u" rel="up">perlthrtut Threads
And Data</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Shared-And-Unshared-Data"></a>
-<h4 class="subsection">75.8.1 Shared And Unshared Data</h4>
-
-<p>The biggest difference between Perl <em>ithreads</em> and the old 5.005
style
-threading, or for that matter, to most other threading systems out there,
-is that by default, no data is shared. When a new Perl thread is created,
-all the data associated with the current thread is copied to the new
-thread, and is subsequently private to that new thread!
-This is similar in feel to what happens when a Unix process forks,
-except that in this case, the data is just copied to a different part of
-memory within the same process rather than a real fork taking place.
-</p>
-<p>To make use of threading, however, one usually wants the threads to share
-at least some data between themselves. This is done with the
-<a href="threads-shared.html#Top">(threads-shared)</a> module and the
<code>:shared</code> attribute:
-</p>
-<pre class="verbatim"> use threads;
- use threads::shared;
-
- my $foo :shared = 1;
- my $bar = 1;
- threads->create(sub { $foo++; $bar++; })->join();
-
- print("$foo\n"); # Prints 2 since $foo is shared
- print("$bar\n"); # Prints 1 since $bar is not shared
-</pre>
-<p>In the case of a shared array, all the array’s elements are shared,
and for
-a shared hash, all the keys and values are shared. This places
-restrictions on what may be assigned to shared array and hash elements: only
-simple values or references to shared variables are allowed - this is
-so that a private variable can’t accidentally become shared. A bad
-assignment will cause the thread to die. For example:
-</p>
-<pre class="verbatim"> use threads;
- use threads::shared;
-
- my $var = 1;
- my $svar :shared = 2;
- my %hash :shared;
-
- ... create some threads ...
-
- $hash{a} = 1; # All threads see exists($hash{a})
- # and $hash{a} == 1
- $hash{a} = $var; # okay - copy-by-value: same effect as previous
- $hash{a} = $svar; # okay - copy-by-value: same effect as previous
- $hash{a} = \$svar; # okay - a reference to a shared variable
- $hash{a} = \$var; # This will die
- delete($hash{a}); # okay - all threads will see !exists($hash{a})
-</pre>
-<p>Note that a shared variable guarantees that if two or more threads try to
-modify it at the same time, the internal state of the variable will not
-become corrupted. However, there are no guarantees beyond this, as
-explained in the next section.
-</p>
-<hr>
-<a name="perlthrtut-Thread-Pitfalls_003a-Races"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlthrtut-Shared-And-Unshared-Data" accesskey="p"
rel="prev">perlthrtut Shared And Unshared Data</a>, Up: <a
href="#perlthrtut-Threads-And-Data" accesskey="u" rel="up">perlthrtut Threads
And Data</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Thread-Pitfalls_003a-Races"></a>
-<h4 class="subsection">75.8.2 Thread Pitfalls: Races</h4>
-
-<p>While threads bring a new set of useful tools, they also bring a
-number of pitfalls. One pitfall is the race condition:
-</p>
-<pre class="verbatim"> use threads;
- use threads::shared;
-
- my $x :shared = 1;
- my $thr1 = threads->create(\&sub1);
- my $thr2 = threads->create(\&sub2);
-
- $thr1->join();
- $thr2->join();
- print("$x\n");
-
- sub sub1 { my $foo = $x; $x = $foo + 1; }
- sub sub2 { my $bar = $x; $x = $bar + 1; }
-</pre>
-<p>What do you think <code>$x</code> will be? The answer, unfortunately, is
<em>it
-depends</em>. Both <code>sub1()</code> and <code>sub2()</code> access the
global variable <code>$x</code>, once
-to read and once to write. Depending on factors ranging from your
-thread implementation’s scheduling algorithm to the phase of the moon,
-<code>$x</code> can be 2 or 3.
-</p>
-<p>Race conditions are caused by unsynchronized access to shared
-data. Without explicit synchronization, there’s no way to be sure that
-nothing has happened to the shared data between the time you access it
-and the time you update it. Even this simple code fragment has the
-possibility of error:
-</p>
-<pre class="verbatim"> use threads;
- my $x :shared = 2;
- my $y :shared;
- my $z :shared;
- my $thr1 = threads->create(sub { $y = $x; $x = $y + 1; });
- my $thr2 = threads->create(sub { $z = $x; $x = $z + 1; });
- $thr1->join();
- $thr2->join();
-</pre>
-<p>Two threads both access <code>$x</code>. Each thread can potentially be
interrupted
-at any point, or be executed in any order. At the end, <code>$x</code> could
be 3
-or 4, and both <code>$y</code> and <code>$z</code> could be 2 or 3.
-</p>
-<p>Even <code>$x += 5</code> or <code>$x++</code> are not guaranteed to be
atomic.
-</p>
-<p>Whenever your program accesses data or resources that can be accessed
-by other threads, you must take steps to coordinate access or risk
-data inconsistency and race conditions. Note that Perl will protect its
-internals from your race conditions, but it won’t protect you from you.
-</p>
-<hr>
-<a name="perlthrtut-Synchronization-and-control"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-General-Thread-Utility-Routines" accesskey="n"
rel="next">perlthrtut General Thread Utility Routines</a>, Previous: <a
href="#perlthrtut-Threads-And-Data" accesskey="p" rel="prev">perlthrtut Threads
And Data</a>, Up: <a href="#perlthrtut" accesskey="u" rel="up">perlthrtut</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Synchronization-and-control"></a>
-<h3 class="section">75.9 Synchronization and control</h3>
-
-<p>Perl provides a number of mechanisms to coordinate the interactions
-between themselves and their data, to avoid race conditions and the like.
-Some of these are designed to resemble the common techniques used in thread
-libraries such as <code>pthreads</code>; others are Perl-specific. Often, the
-standard techniques are clumsy and difficult to get right (such as
-condition waits). Where possible, it is usually easier to use Perlish
-techniques such as queues, which remove some of the hard work involved.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Controlling-access_003a-lock_0028_0029"
accesskey="1">perlthrtut Controlling access:
lock()</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-A-Thread-Pitfall_003a-Deadlocks" accesskey="2">perlthrtut A
Thread Pitfall: Deadlocks</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Queues_003a-Passing-Data-Around" accesskey="3">perlthrtut
Queues: Passing Data Around</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Semaphores_003a-Synchronizing-Data-Access"
accesskey="4">perlthrtut Semaphores: Synchronizing Data
Access</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Basic-semaphores" accesskey="5">perlthrtut Basic
semaphores</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Advanced-Semaphores" accesskey="6">perlthrtut Advanced
Semaphores</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Waiting-for-a-Condition" accesskey="7">perlthrtut Waiting for
a Condition</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Giving-up-control" accesskey="8">perlthrtut Giving up
control</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlthrtut-Controlling-access_003a-lock_0028_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-A-Thread-Pitfall_003a-Deadlocks" accesskey="n"
rel="next">perlthrtut A Thread Pitfall: Deadlocks</a>, Up: <a
href="#perlthrtut-Synchronization-and-control" accesskey="u"
rel="up">perlthrtut Synchronization and control</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Controlling-access_003a-lock_0028_0029"></a>
-<h4 class="subsection">75.9.1 Controlling access: lock()</h4>
-
-<p>The <code>lock()</code> function takes a shared variable and puts a lock on
it.
-No other thread may lock the variable until the variable is unlocked
-by the thread holding the lock. Unlocking happens automatically
-when the locking thread exits the block that contains the call to the
-<code>lock()</code> function. Using <code>lock()</code> is straightforward:
This example has
-several threads doing some calculations in parallel, and occasionally
-updating a running total:
-</p>
-<pre class="verbatim"> use threads;
- use threads::shared;
-
- my $total :shared = 0;
-
- sub calc {
- while (1) {
- my $result;
- # (... do some calculations and set $result ...)
- {
- lock($total); # Block until we obtain the lock
- $total += $result;
- } # Lock implicitly released at end of scope
- last if $result == 0;
- }
- }
-
- my $thr1 = threads->create(\&calc);
- my $thr2 = threads->create(\&calc);
- my $thr3 = threads->create(\&calc);
- $thr1->join();
- $thr2->join();
- $thr3->join();
- print("total=$total\n");
-</pre>
-<p><code>lock()</code> blocks the thread until the variable being locked is
-available. When <code>lock()</code> returns, your thread can be sure that no
other
-thread can lock that variable until the block containing the
-lock exits.
-</p>
-<p>It’s important to note that locks don’t prevent access to the
variable
-in question, only lock attempts. This is in keeping with Perl’s
-longstanding tradition of courteous programming, and the advisory file
-locking that <code>flock()</code> gives you.
-</p>
-<p>You may lock arrays and hashes as well as scalars. Locking an array,
-though, will not block subsequent locks on array elements, just lock
-attempts on the array itself.
-</p>
-<p>Locks are recursive, which means it’s okay for a thread to
-lock a variable more than once. The lock will last until the outermost
-<code>lock()</code> on the variable goes out of scope. For example:
-</p>
-<pre class="verbatim"> my $x :shared;
- doit();
-
- sub doit {
- {
- {
- lock($x); # Wait for lock
- lock($x); # NOOP - we already have the lock
- {
- lock($x); # NOOP
- {
- lock($x); # NOOP
- lockit_some_more();
- }
- }
- } # *** Implicit unlock here ***
- }
- }
-
- sub lockit_some_more {
- lock($x); # NOOP
- } # Nothing happens here
-</pre>
-<p>Note that there is no <code>unlock()</code> function - the only way to
unlock a
-variable is to allow it to go out of scope.
-</p>
-<p>A lock can either be used to guard the data contained within the variable
-being locked, or it can be used to guard something else, like a section
-of code. In this latter case, the variable in question does not hold any
-useful data, and exists only for the purpose of being locked. In this
-respect, the variable behaves like the mutexes and basic semaphores of
-traditional thread libraries.
-</p>
-<hr>
-<a name="perlthrtut-A-Thread-Pitfall_003a-Deadlocks"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Queues_003a-Passing-Data-Around" accesskey="n"
rel="next">perlthrtut Queues: Passing Data Around</a>, Previous: <a
href="#perlthrtut-Controlling-access_003a-lock_0028_0029" accesskey="p"
rel="prev">perlthrtut Controlling access: lock()</a>, Up: <a
href="#perlthrtut-Synchronization-and-control" accesskey="u"
rel="up">perlthrtut Synchronization and control</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="A-Thread-Pitfall_003a-Deadlocks"></a>
-<h4 class="subsection">75.9.2 A Thread Pitfall: Deadlocks</h4>
-
-<p>Locks are a handy tool to synchronize access to data, and using them
-properly is the key to safe shared data. Unfortunately, locks aren’t
-without their dangers, especially when multiple locks are involved.
-Consider the following code:
-</p>
-<pre class="verbatim"> use threads;
-
- my $x :shared = 4;
- my $y :shared = 'foo';
- my $thr1 = threads->create(sub {
- lock($x);
- sleep(20);
- lock($y);
- });
- my $thr2 = threads->create(sub {
- lock($y);
- sleep(20);
- lock($x);
- });
-</pre>
-<p>This program will probably hang until you kill it. The only way it
-won’t hang is if one of the two threads acquires both locks
-first. A guaranteed-to-hang version is more complicated, but the
-principle is the same.
-</p>
-<p>The first thread will grab a lock on <code>$x</code>, then, after a pause
during which
-the second thread has probably had time to do some work, try to grab a
-lock on <code>$y</code>. Meanwhile, the second thread grabs a lock on
<code>$y</code>, then later
-tries to grab a lock on <code>$x</code>. The second lock attempt for both
threads will
-block, each waiting for the other to release its lock.
-</p>
-<p>This condition is called a deadlock, and it occurs whenever two or
-more threads are trying to get locks on resources that the others
-own. Each thread will block, waiting for the other to release a lock
-on a resource. That never happens, though, since the thread with the
-resource is itself waiting for a lock to be released.
-</p>
-<p>There are a number of ways to handle this sort of problem. The best
-way is to always have all threads acquire locks in the exact same
-order. If, for example, you lock variables <code>$x</code>, <code>$y</code>,
and <code>$z</code>, always lock
-<code>$x</code> before <code>$y</code>, and <code>$y</code> before
<code>$z</code>. It’s also best to hold on to locks for
-as short a period of time to minimize the risks of deadlock.
-</p>
-<p>The other synchronization primitives described below can suffer from
-similar problems.
-</p>
-<hr>
-<a name="perlthrtut-Queues_003a-Passing-Data-Around"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Semaphores_003a-Synchronizing-Data-Access"
accesskey="n" rel="next">perlthrtut Semaphores: Synchronizing Data Access</a>,
Previous: <a href="#perlthrtut-A-Thread-Pitfall_003a-Deadlocks" accesskey="p"
rel="prev">perlthrtut A Thread Pitfall: Deadlocks</a>, Up: <a
href="#perlthrtut-Synchronization-and-control" accesskey="u"
rel="up">perlthrtut Synchronization and control</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Queues_003a-Passing-Data-Around"></a>
-<h4 class="subsection">75.9.3 Queues: Passing Data Around</h4>
-
-<p>A queue is a special thread-safe object that lets you put data in one
-end and take it out the other without having to worry about
-synchronization issues. They’re pretty straightforward, and look like
-this:
-</p>
-<pre class="verbatim"> use threads;
- use Thread::Queue;
-
- my $DataQueue = Thread::Queue->new();
- my $thr = threads->create(sub {
- while (my $DataElement = $DataQueue->dequeue()) {
- print("Popped $DataElement off the queue\n");
- }
- });
-
- $DataQueue->enqueue(12);
- $DataQueue->enqueue("A", "B", "C");
- sleep(10);
- $DataQueue->enqueue(undef);
- $thr->join();
-</pre>
-<p>You create the queue with <code>Thread::Queue->new()</code>. Then you
can
-add lists of scalars onto the end with <code>enqueue()</code>, and pop scalars
off
-the front of it with <code>dequeue()</code>. A queue has no fixed size, and
can grow
-as needed to hold everything pushed on to it.
-</p>
-<p>If a queue is empty, <code>dequeue()</code> blocks until another thread
enqueues
-something. This makes queues ideal for event loops and other
-communications between threads.
-</p>
-<hr>
-<a name="perlthrtut-Semaphores_003a-Synchronizing-Data-Access"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Basic-semaphores" accesskey="n"
rel="next">perlthrtut Basic semaphores</a>, Previous: <a
href="#perlthrtut-Queues_003a-Passing-Data-Around" accesskey="p"
rel="prev">perlthrtut Queues: Passing Data Around</a>, Up: <a
href="#perlthrtut-Synchronization-and-control" accesskey="u"
rel="up">perlthrtut Synchronization and control</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Semaphores_003a-Synchronizing-Data-Access"></a>
-<h4 class="subsection">75.9.4 Semaphores: Synchronizing Data Access</h4>
-
-<p>Semaphores are a kind of generic locking mechanism. In their most basic
-form, they behave very much like lockable scalars, except that they
-can’t hold data, and that they must be explicitly unlocked. In their
-advanced form, they act like a kind of counter, and can allow multiple
-threads to have the <em>lock</em> at any one time.
-</p>
-<hr>
-<a name="perlthrtut-Basic-semaphores"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Advanced-Semaphores" accesskey="n"
rel="next">perlthrtut Advanced Semaphores</a>, Previous: <a
href="#perlthrtut-Semaphores_003a-Synchronizing-Data-Access" accesskey="p"
rel="prev">perlthrtut Semaphores: Synchronizing Data Access</a>, Up: <a
href="#perlthrtut-Synchronization-and-control" accesskey="u"
rel="up">perlthrtut Synchronization and control</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Basic-semaphores"></a>
-<h4 class="subsection">75.9.5 Basic semaphores</h4>
-
-<p>Semaphores have two methods, <code>down()</code> and <code>up()</code>:
<code>down()</code> decrements the resource
-count, while <code>up()</code> increments it. Calls to <code>down()</code>
will block if the
-semaphore’s current count would decrement below zero. This program
-gives a quick demonstration:
-</p>
-<pre class="verbatim"> use threads;
- use Thread::Semaphore;
-
- my $semaphore = Thread::Semaphore->new();
- my $GlobalVariable :shared = 0;
-
- $thr1 = threads->create(\&sample_sub, 1);
- $thr2 = threads->create(\&sample_sub, 2);
- $thr3 = threads->create(\&sample_sub, 3);
-
- sub sample_sub {
- my $SubNumber = shift(@_);
- my $TryCount = 10;
- my $LocalCopy;
- sleep(1);
- while ($TryCount--) {
- $semaphore->down();
- $LocalCopy = $GlobalVariable;
- print("$TryCount tries left for sub $SubNumber "
- ."(\$GlobalVariable is $GlobalVariable)\n");
- sleep(2);
- $LocalCopy++;
- $GlobalVariable = $LocalCopy;
- $semaphore->up();
- }
- }
-
- $thr1->join();
- $thr2->join();
- $thr3->join();
-</pre>
-<p>The three invocations of the subroutine all operate in sync. The
-semaphore, though, makes sure that only one thread is accessing the
-global variable at once.
-</p>
-<hr>
-<a name="perlthrtut-Advanced-Semaphores"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Waiting-for-a-Condition" accesskey="n"
rel="next">perlthrtut Waiting for a Condition</a>, Previous: <a
href="#perlthrtut-Basic-semaphores" accesskey="p" rel="prev">perlthrtut Basic
semaphores</a>, Up: <a href="#perlthrtut-Synchronization-and-control"
accesskey="u" rel="up">perlthrtut Synchronization and control</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Advanced-Semaphores"></a>
-<h4 class="subsection">75.9.6 Advanced Semaphores</h4>
-
-<p>By default, semaphores behave like locks, letting only one thread
-<code>down()</code> them at a time. However, there are other uses for
semaphores.
-</p>
-<p>Each semaphore has a counter attached to it. By default, semaphores are
-created with the counter set to one, <code>down()</code> decrements the
counter by
-one, and <code>up()</code> increments by one. However, we can override any or
all
-of these defaults simply by passing in different values:
-</p>
-<pre class="verbatim"> use threads;
- use Thread::Semaphore;
-
- my $semaphore = Thread::Semaphore->new(5);
- # Creates a semaphore with the counter set to five
-
- my $thr1 = threads->create(\&sub1);
- my $thr2 = threads->create(\&sub1);
-
- sub sub1 {
- $semaphore->down(5); # Decrements the counter by five
- # Do stuff here
- $semaphore->up(5); # Increment the counter by five
- }
-
- $thr1->detach();
- $thr2->detach();
-</pre>
-<p>If <code>down()</code> attempts to decrement the counter below zero, it
blocks until
-the counter is large enough. Note that while a semaphore can be created
-with a starting count of zero, any <code>up()</code> or <code>down()</code>
always changes the
-counter by at least one, and so <code>$semaphore->down(0)</code> is the
same as
-<code>$semaphore->down(1)</code>.
-</p>
-<p>The question, of course, is why would you do something like this? Why
-create a semaphore with a starting count that’s not one, or why
-decrement or increment it by more than one? The answer is resource
-availability. Many resources that you want to manage access for can be
-safely used by more than one thread at once.
-</p>
-<p>For example, let’s take a GUI driven program. It has a semaphore that
-it uses to synchronize access to the display, so only one thread is
-ever drawing at once. Handy, but of course you don’t want any thread
-to start drawing until things are properly set up. In this case, you
-can create a semaphore with a counter set to zero, and up it when
-things are ready for drawing.
-</p>
-<p>Semaphores with counters greater than one are also useful for
-establishing quotas. Say, for example, that you have a number of
-threads that can do I/O at once. You don’t want all the threads
-reading or writing at once though, since that can potentially swamp
-your I/O channels, or deplete your process’s quota of filehandles. You
-can use a semaphore initialized to the number of concurrent I/O
-requests (or open files) that you want at any one time, and have your
-threads quietly block and unblock themselves.
-</p>
-<p>Larger increments or decrements are handy in those cases where a
-thread needs to check out or return a number of resources at once.
-</p>
-<hr>
-<a name="perlthrtut-Waiting-for-a-Condition"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Giving-up-control" accesskey="n"
rel="next">perlthrtut Giving up control</a>, Previous: <a
href="#perlthrtut-Advanced-Semaphores" accesskey="p" rel="prev">perlthrtut
Advanced Semaphores</a>, Up: <a href="#perlthrtut-Synchronization-and-control"
accesskey="u" rel="up">perlthrtut Synchronization and control</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Waiting-for-a-Condition"></a>
-<h4 class="subsection">75.9.7 Waiting for a Condition</h4>
-
-<p>The functions <code>cond_wait()</code> and <code>cond_signal()</code>
-can be used in conjunction with locks to notify
-co-operating threads that a resource has become available. They are
-very similar in use to the functions found in <code>pthreads</code>. However
-for most purposes, queues are simpler to use and more intuitive. See
-<a href="threads-shared.html#Top">(threads-shared)</a> for more details.
-</p>
-<hr>
-<a name="perlthrtut-Giving-up-control"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlthrtut-Waiting-for-a-Condition" accesskey="p"
rel="prev">perlthrtut Waiting for a Condition</a>, Up: <a
href="#perlthrtut-Synchronization-and-control" accesskey="u"
rel="up">perlthrtut Synchronization and control</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Giving-up-control"></a>
-<h4 class="subsection">75.9.8 Giving up control</h4>
-
-<p>There are times when you may find it useful to have a thread
-explicitly give up the CPU to another thread. You may be doing something
-processor-intensive and want to make sure that the user-interface thread
-gets called frequently. Regardless, there are times that you might want
-a thread to give up the processor.
-</p>
-<p>Perl’s threading package provides the <code>yield()</code> function
that does
-this. <code>yield()</code> is pretty straightforward, and works like this:
-</p>
-<pre class="verbatim"> use threads;
-
- sub loop {
- my $thread = shift;
- my $foo = 50;
- while($foo--) { print("In thread $thread\n"); }
- threads->yield();
- $foo = 50;
- while($foo--) { print("In thread $thread\n"); }
- }
-
- my $thr1 = threads->create(\&loop, 'first');
- my $thr2 = threads->create(\&loop, 'second');
- my $thr3 = threads->create(\&loop, 'third');
-</pre>
-<p>It is important to remember that <code>yield()</code> is only a hint to
give up the CPU,
-it depends on your hardware, OS and threading libraries what actually happens.
-<strong>On many operating systems, yield() is a no-op.</strong> Therefore it
is important
-to note that one should not build the scheduling of the threads around
-<code>yield()</code> calls. It might work on your platform but it won’t
work on another
-platform.
-</p>
-<hr>
-<a name="perlthrtut-General-Thread-Utility-Routines"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-A-Complete-Example" accesskey="n"
rel="next">perlthrtut A Complete Example</a>, Previous: <a
href="#perlthrtut-Synchronization-and-control" accesskey="p"
rel="prev">perlthrtut Synchronization and control</a>, Up: <a
href="#perlthrtut" accesskey="u" rel="up">perlthrtut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="General-Thread-Utility-Routines"></a>
-<h3 class="section">75.10 General Thread Utility Routines</h3>
-
-<p>We’ve covered the workhorse parts of Perl’s threading package,
and
-with these tools you should be well on your way to writing threaded
-code and packages. There are a few useful little pieces that didn’t
-really fit in anyplace else.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-What-Thread-Am-I-In_003f" accesskey="1">perlthrtut What
Thread Am I In?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlthrtut-Thread-IDs"
accesskey="2">perlthrtut Thread IDs</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Are-These-Threads-The-Same_003f" accesskey="3">perlthrtut Are
These Threads The Same?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-What-Threads-Are-Running_003f" accesskey="4">perlthrtut What
Threads Are Running?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlthrtut-What-Thread-Am-I-In_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Thread-IDs" accesskey="n" rel="next">perlthrtut
Thread IDs</a>, Up: <a href="#perlthrtut-General-Thread-Utility-Routines"
accesskey="u" rel="up">perlthrtut General Thread Utility Routines</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="What-Thread-Am-I-In_003f"></a>
-<h4 class="subsection">75.10.1 What Thread Am I In?</h4>
-
-<p>The <code>threads->self()</code> class method provides your program with
a way to
-get an object representing the thread it’s currently in. You can use
this
-object in the same way as the ones returned from thread creation.
-</p>
-<hr>
-<a name="perlthrtut-Thread-IDs"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Are-These-Threads-The-Same_003f" accesskey="n"
rel="next">perlthrtut Are These Threads The Same?</a>, Previous: <a
href="#perlthrtut-What-Thread-Am-I-In_003f" accesskey="p" rel="prev">perlthrtut
What Thread Am I In?</a>, Up: <a
href="#perlthrtut-General-Thread-Utility-Routines" accesskey="u"
rel="up">perlthrtut General Thread Utility Routines</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Thread-IDs"></a>
-<h4 class="subsection">75.10.2 Thread IDs</h4>
-
-<p><code>tid()</code> is a thread object method that returns the thread ID of
the
-thread the object represents. Thread IDs are integers, with the main
-thread in a program being 0. Currently Perl assigns a unique TID to
-every thread ever created in your program, assigning the first thread
-to be created a TID of 1, and increasing the TID by 1 for each new
-thread that’s created. When used as a class method,
<code>threads->tid()</code>
-can be used by a thread to get its own TID.
-</p>
-<hr>
-<a name="perlthrtut-Are-These-Threads-The-Same_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-What-Threads-Are-Running_003f" accesskey="n"
rel="next">perlthrtut What Threads Are Running?</a>, Previous: <a
href="#perlthrtut-Thread-IDs" accesskey="p" rel="prev">perlthrtut Thread
IDs</a>, Up: <a href="#perlthrtut-General-Thread-Utility-Routines"
accesskey="u" rel="up">perlthrtut General Thread Utility Routines</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Are-These-Threads-The-Same_003f"></a>
-<h4 class="subsection">75.10.3 Are These Threads The Same?</h4>
-
-<p>The <code>equal()</code> method takes two thread objects and returns true
-if the objects represent the same thread, and false if they don’t.
-</p>
-<p>Thread objects also have an overloaded <code>==</code> comparison so that
you can do
-comparison on them as you would with normal objects.
-</p>
-<hr>
-<a name="perlthrtut-What-Threads-Are-Running_003f"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlthrtut-Are-These-Threads-The-Same_003f" accesskey="p"
rel="prev">perlthrtut Are These Threads The Same?</a>, Up: <a
href="#perlthrtut-General-Thread-Utility-Routines" accesskey="u"
rel="up">perlthrtut General Thread Utility Routines</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="What-Threads-Are-Running_003f"></a>
-<h4 class="subsection">75.10.4 What Threads Are Running?</h4>
-
-<p><code>threads->list()</code> returns a list of thread objects, one for
each thread
-that’s currently running and not detached. Handy for a number of things,
-including cleaning up at the end of your program (from the main Perl thread,
-of course):
-</p>
-<pre class="verbatim"> # Loop through all the threads
- foreach my $thr (threads->list()) {
- $thr->join();
- }
-</pre>
-<p>If some threads have not finished running when the main Perl thread
-ends, Perl will warn you about it and die, since it is impossible for Perl
-to clean up itself while other threads are running.
-</p>
-<p>NOTE: The main Perl thread (thread 0) is in a <em>detached</em> state, and
so
-does not appear in the list returned by <code>threads->list()</code>.
-</p>
-<hr>
-<a name="perlthrtut-A-Complete-Example"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Different-implementations-of-threads" accesskey="n"
rel="next">perlthrtut Different implementations of threads</a>, Previous: <a
href="#perlthrtut-General-Thread-Utility-Routines" accesskey="p"
rel="prev">perlthrtut General Thread Utility Routines</a>, Up: <a
href="#perlthrtut" accesskey="u" rel="up">perlthrtut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="A-Complete-Example"></a>
-<h3 class="section">75.11 A Complete Example</h3>
-
-<p>Confused yet? It’s time for an example program to show some of the
-things we’ve covered. This program finds prime numbers using threads.
-</p>
-<pre class="verbatim"> 1 #!/usr/bin/perl
- 2 # prime-pthread, courtesy of Tom Christiansen
- 3
- 4 use strict;
- 5 use warnings;
- 6
- 7 use threads;
- 8 use Thread::Queue;
- 9
- 10 sub check_num {
- 11 my ($upstream, $cur_prime) = @_;
- 12 my $kid;
- 13 my $downstream = Thread::Queue->new();
- 14 while (my $num = $upstream->dequeue()) {
- 15 next unless ($num % $cur_prime);
- 16 if ($kid) {
- 17 $downstream->enqueue($num);
- 18 } else {
- 19 print("Found prime: $num\n");
- 20 $kid = threads->create(\&check_num, $downstream, $num);
- 21 if (! $kid) {
- 22 warn("Sorry. Ran out of threads.\n");
- 23 last;
- 24 }
- 25 }
- 26 }
- 27 if ($kid) {
- 28 $downstream->enqueue(undef);
- 29 $kid->join();
- 30 }
- 31 }
- 32
- 33 my $stream = Thread::Queue->new(3..1000, undef);
- 34 check_num($stream, 2);
-</pre>
-<p>This program uses the pipeline model to generate prime numbers. Each
-thread in the pipeline has an input queue that feeds numbers to be
-checked, a prime number that it’s responsible for, and an output queue
-into which it funnels numbers that have failed the check. If the thread
-has a number that’s failed its check and there’s no child thread,
then
-the thread must have found a new prime number. In that case, a new
-child thread is created for that prime and stuck on the end of the
-pipeline.
-</p>
-<p>This probably sounds a bit more confusing than it really is, so let’s
-go through this program piece by piece and see what it does. (For
-those of you who might be trying to remember exactly what a prime
-number is, it’s a number that’s only evenly divisible by itself
and 1.)
-</p>
-<p>The bulk of the work is done by the <code>check_num()</code> subroutine,
which
-takes a reference to its input queue and a prime number that it’s
-responsible for. After pulling in the input queue and the prime that
-the subroutine is checking (line 11), we create a new queue (line 13)
-and reserve a scalar for the thread that we’re likely to create later
-(line 12).
-</p>
-<p>The while loop from line 14 to line 26 grabs a scalar off the input
-queue and checks against the prime this thread is responsible
-for. Line 15 checks to see if there’s a remainder when we divide the
-number to be checked by our prime. If there is one, the number
-must not be evenly divisible by our prime, so we need to either pass
-it on to the next thread if we’ve created one (line 17) or create a
-new thread if we haven’t.
-</p>
-<p>The new thread creation is line 20. We pass on to it a reference to
-the queue we’ve created, and the prime number we’ve found. In
lines 21
-through 24, we check to make sure that our new thread got created, and
-if not, we stop checking any remaining numbers in the queue.
-</p>
-<p>Finally, once the loop terminates (because we got a 0 or <code>undef</code>
in the
-queue, which serves as a note to terminate), we pass on the notice to our
-child, and wait for it to exit if we’ve created a child (lines 27 and
-30).
-</p>
-<p>Meanwhile, back in the main thread, we first create a queue (line 33) and
-queue up all the numbers from 3 to 1000 for checking, plus a termination
-notice. Then all we have to do to get the ball rolling is pass the queue
-and the first prime to the <code>check_num()</code> subroutine (line 34).
-</p>
-<p>That’s how it works. It’s pretty simple; as with many Perl
programs,
-the explanation is much longer than the program.
-</p>
-<hr>
-<a name="perlthrtut-Different-implementations-of-threads"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Performance-considerations" accesskey="n"
rel="next">perlthrtut Performance considerations</a>, Previous: <a
href="#perlthrtut-A-Complete-Example" accesskey="p" rel="prev">perlthrtut A
Complete Example</a>, Up: <a href="#perlthrtut" accesskey="u"
rel="up">perlthrtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Different-implementations-of-threads"></a>
-<h3 class="section">75.12 Different implementations of threads</h3>
-
-<p>Some background on thread implementations from the operating system
-viewpoint. There are three basic categories of threads: user-mode threads,
-kernel threads, and multiprocessor kernel threads.
-</p>
-<p>User-mode threads are threads that live entirely within a program and
-its libraries. In this model, the OS knows nothing about threads. As
-far as it’s concerned, your process is just a process.
-</p>
-<p>This is the easiest way to implement threads, and the way most OSes
-start. The big disadvantage is that, since the OS knows nothing about
-threads, if one thread blocks they all do. Typical blocking activities
-include most system calls, most I/O, and things like <code>sleep()</code>.
-</p>
-<p>Kernel threads are the next step in thread evolution. The OS knows
-about kernel threads, and makes allowances for them. The main
-difference between a kernel thread and a user-mode thread is
-blocking. With kernel threads, things that block a single thread don’t
-block other threads. This is not the case with user-mode threads,
-where the kernel blocks at the process level and not the thread level.
-</p>
-<p>This is a big step forward, and can give a threaded program quite a
-performance boost over non-threaded programs. Threads that block
-performing I/O, for example, won’t block threads that are doing other
-things. Each process still has only one thread running at once,
-though, regardless of how many CPUs a system might have.
-</p>
-<p>Since kernel threading can interrupt a thread at any time, they will
-uncover some of the implicit locking assumptions you may make in your
-program. For example, something as simple as <code>$x = $x + 2</code> can
behave
-unpredictably with kernel threads if <code>$x</code> is visible to other
-threads, as another thread may have changed <code>$x</code> between the time it
-was fetched on the right hand side and the time the new value is
-stored.
-</p>
-<p>Multiprocessor kernel threads are the final step in thread
-support. With multiprocessor kernel threads on a machine with multiple
-CPUs, the OS may schedule two or more threads to run simultaneously on
-different CPUs.
-</p>
-<p>This can give a serious performance boost to your threaded program,
-since more than one thread will be executing at the same time. As a
-tradeoff, though, any of those nagging synchronization issues that
-might not have shown with basic kernel threads will appear with a
-vengeance.
-</p>
-<p>In addition to the different levels of OS involvement in threads,
-different OSes (and different thread implementations for a particular
-OS) allocate CPU cycles to threads in different ways.
-</p>
-<p>Cooperative multitasking systems have running threads give up control
-if one of two things happen. If a thread calls a yield function, it
-gives up control. It also gives up control if the thread does
-something that would cause it to block, such as perform I/O. In a
-cooperative multitasking implementation, one thread can starve all the
-others for CPU time if it so chooses.
-</p>
-<p>Preemptive multitasking systems interrupt threads at regular intervals
-while the system decides which thread should run next. In a preemptive
-multitasking system, one thread usually won’t monopolize the CPU.
-</p>
-<p>On some systems, there can be cooperative and preemptive threads
-running simultaneously. (Threads running with realtime priorities
-often behave cooperatively, for example, while threads running at
-normal priorities behave preemptively.)
-</p>
-<p>Most modern operating systems support preemptive multitasking nowadays.
-</p>
-<hr>
-<a name="perlthrtut-Performance-considerations"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Process_002dscope-Changes" accesskey="n"
rel="next">perlthrtut Process-scope Changes</a>, Previous: <a
href="#perlthrtut-Different-implementations-of-threads" accesskey="p"
rel="prev">perlthrtut Different implementations of threads</a>, Up: <a
href="#perlthrtut" accesskey="u" rel="up">perlthrtut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Performance-considerations"></a>
-<h3 class="section">75.13 Performance considerations</h3>
-
-<p>The main thing to bear in mind when comparing Perl’s
<em>ithreads</em> to other threading
-models is the fact that for each new thread created, a complete copy of
-all the variables and data of the parent thread has to be taken. Thus,
-thread creation can be quite expensive, both in terms of memory usage and
-time spent in creation. The ideal way to reduce these costs is to have a
-relatively short number of long-lived threads, all created fairly early
-on (before the base thread has accumulated too much data). Of course, this
-may not always be possible, so compromises have to be made. However, after
-a thread has been created, its performance and extra memory usage should
-be little different than ordinary code.
-</p>
-<p>Also note that under the current implementation, shared variables
-use a little more memory and are a little slower than ordinary variables.
-</p>
-<hr>
-<a name="perlthrtut-Process_002dscope-Changes"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Thread_002dSafety-of-System-Libraries"
accesskey="n" rel="next">perlthrtut Thread-Safety of System Libraries</a>,
Previous: <a href="#perlthrtut-Performance-considerations" accesskey="p"
rel="prev">perlthrtut Performance considerations</a>, Up: <a href="#perlthrtut"
accesskey="u" rel="up">perlthrtut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Process_002dscope-Changes"></a>
-<h3 class="section">75.14 Process-scope Changes</h3>
-
-<p>Note that while threads themselves are separate execution threads and
-Perl data is thread-private unless explicitly shared, the threads can
-affect process-scope state, affecting all the threads.
-</p>
-<p>The most common example of this is changing the current working
-directory using <code>chdir()</code>. One thread calls <code>chdir()</code>,
and the working
-directory of all the threads changes.
-</p>
-<p>Even more drastic example of a process-scope change is
<code>chroot()</code>:
-the root directory of all the threads changes, and no thread can
-undo it (as opposed to <code>chdir()</code>).
-</p>
-<p>Further examples of process-scope changes include <code>umask()</code> and
-changing uids and gids.
-</p>
-<p>Thinking of mixing <code>fork()</code> and threads? Please lie down and
wait
-until the feeling passes. Be aware that the semantics of <code>fork()</code>
vary
-between platforms. For example, some Unix systems copy all the current
-threads into the child process, while others only copy the thread that
-called <code>fork()</code>. You have been warned!
-</p>
-<p>Similarly, mixing signals and threads may be problematic.
-Implementations are platform-dependent, and even the POSIX
-semantics may not be what you expect (and Perl doesn’t even
-give you the full POSIX API). For example, there is no way to
-guarantee that a signal sent to a multi-threaded Perl application
-will get intercepted by any particular thread. (However, a recently
-added feature does provide the capability to send signals between
-threads. See <a href="threads.html#THREAD-SIGNALLING">(threads)THREAD
SIGNALLING</a> for more details.)
-</p>
-<hr>
-<a name="perlthrtut-Thread_002dSafety-of-System-Libraries"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Conclusion" accesskey="n" rel="next">perlthrtut
Conclusion</a>, Previous: <a href="#perlthrtut-Process_002dscope-Changes"
accesskey="p" rel="prev">perlthrtut Process-scope Changes</a>, Up: <a
href="#perlthrtut" accesskey="u" rel="up">perlthrtut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Thread_002dSafety-of-System-Libraries"></a>
-<h3 class="section">75.15 Thread-Safety of System Libraries</h3>
-
-<p>Whether various library calls are thread-safe is outside the control
-of Perl. Calls often suffering from not being thread-safe include:
-<code>localtime()</code>, <code>gmtime()</code>, functions fetching user,
group and
-network information (such as <code>getgrent()</code>,
<code>gethostent()</code>,
-<code>getnetent()</code> and so on), <code>readdir()</code>,
<code>rand()</code>, and <code>srand()</code>. In
-general, calls that depend on some global external state.
-</p>
-<p>If the system Perl is compiled in has thread-safe variants of such
-calls, they will be used. Beyond that, Perl is at the mercy of
-the thread-safety or -unsafety of the calls. Please consult your
-C library call documentation.
-</p>
-<p>On some platforms the thread-safe library interfaces may fail if the
-result buffer is too small (for example the user group databases may
-be rather large, and the reentrant interfaces may have to carry around
-a full snapshot of those databases). Perl will start with a small
-buffer, but keep retrying and growing the result buffer
-until the result fits. If this limitless growing sounds bad for
-security or memory consumption reasons you can recompile Perl with
-<code>PERL_REENTRANT_MAXSIZE</code> defined to the maximum number of bytes you
will
-allow.
-</p>
-<hr>
-<a name="perlthrtut-Conclusion"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-SEE-ALSO" accesskey="n" rel="next">perlthrtut SEE
ALSO</a>, Previous: <a href="#perlthrtut-Thread_002dSafety-of-System-Libraries"
accesskey="p" rel="prev">perlthrtut Thread-Safety of System Libraries</a>, Up:
<a href="#perlthrtut" accesskey="u" rel="up">perlthrtut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Conclusion"></a>
-<h3 class="section">75.16 Conclusion</h3>
-
-<p>A complete thread tutorial could fill a book (and has, many times),
-but with what we’ve covered in this introduction, you should be well
-on your way to becoming a threaded Perl expert.
-</p>
-<hr>
-<a name="perlthrtut-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Bibliography" accesskey="n" rel="next">perlthrtut
Bibliography</a>, Previous: <a href="#perlthrtut-Conclusion" accesskey="p"
rel="prev">perlthrtut Conclusion</a>, Up: <a href="#perlthrtut" accesskey="u"
rel="up">perlthrtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-38"></a>
-<h3 class="section">75.17 SEE ALSO</h3>
-
-<p>Annotated POD for <a href="threads.html#Top">(threads)</a>:
-<a
href="http://annocpan.org/?mode=search&field=Module&name=threads";>http://annocpan.org/?mode=search&field=Module&name=threads</a>
-</p>
-<p>Latest version of <a href="threads.html#Top">(threads)</a> on CPAN:
-<a
href="http://search.cpan.org/search?module=threads";>http://search.cpan.org/search?module=threads</a>
-</p>
-<p>Annotated POD for <a href="threads-shared.html#Top">(threads-shared)</a>:
-<a
href="http://annocpan.org/?mode=search&field=Module&name=threads%3A%3Ashared";>http://annocpan.org/?mode=search&field=Module&name=threads%3A%3Ashared</a>
-</p>
-<p>Latest version of <a href="threads-shared.html#Top">(threads-shared)</a> on
CPAN:
-<a
href="http://search.cpan.org/search?module=threads%3A%3Ashared";>http://search.cpan.org/search?module=threads%3A%3Ashared</a>
-</p>
-<p>Perl threads mailing list:
-<a
href="http://lists.perl.org/list/ithreads.html";>http://lists.perl.org/list/ithreads.html</a>
-</p>
-<hr>
-<a name="perlthrtut-Bibliography"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Acknowledgements" accesskey="n"
rel="next">perlthrtut Acknowledgements</a>, Previous: <a
href="#perlthrtut-SEE-ALSO" accesskey="p" rel="prev">perlthrtut SEE ALSO</a>,
Up: <a href="#perlthrtut" accesskey="u" rel="up">perlthrtut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Bibliography"></a>
-<h3 class="section">75.18 Bibliography</h3>
-
-<p>Here’s a short bibliography courtesy of Jürgen Christoffel:
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Introductory-Texts" accesskey="1">perlthrtut Introductory
Texts</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-OS_002dRelated-References" accesskey="2">perlthrtut
OS-Related References</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlthrtut-Other-References" accesskey="3">perlthrtut Other
References</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlthrtut-Introductory-Texts"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-OS_002dRelated-References" accesskey="n"
rel="next">perlthrtut OS-Related References</a>, Up: <a
href="#perlthrtut-Bibliography" accesskey="u" rel="up">perlthrtut
Bibliography</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Introductory-Texts"></a>
-<h4 class="subsection">75.18.1 Introductory Texts</h4>
-
-<p>Birrell, Andrew D. An Introduction to Programming with
-Threads. Digital Equipment Corporation, 1989, DEC-SRC Research Report
-#35 online as
-ftp://ftp.dec.com/pub/DEC/SRC/research-reports/SRC-035.pdf
-(highly recommended)
-</p>
-<p>Robbins, Kay. A., and Steven Robbins. Practical Unix Programming: A
-Guide to Concurrency, Communication, and
-Multithreading. Prentice-Hall, 1996.
-</p>
-<p>Lewis, Bill, and Daniel J. Berg. Multithreaded Programming with
-Pthreads. Prentice Hall, 1997, ISBN 0-13-443698-9 (a well-written
-introduction to threads).
-</p>
-<p>Nelson, Greg (editor). Systems Programming with Modula-3. Prentice
-Hall, 1991, ISBN 0-13-590464-1.
-</p>
-<p>Nichols, Bradford, Dick Buttlar, and Jacqueline Proulx Farrell.
-Pthreads Programming. O’Reilly & Associates, 1996, ISBN 156592-115-1
-(covers POSIX threads).
-</p>
-<hr>
-<a name="perlthrtut-OS_002dRelated-References"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Other-References" accesskey="n"
rel="next">perlthrtut Other References</a>, Previous: <a
href="#perlthrtut-Introductory-Texts" accesskey="p" rel="prev">perlthrtut
Introductory Texts</a>, Up: <a href="#perlthrtut-Bibliography" accesskey="u"
rel="up">perlthrtut Bibliography</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="OS_002dRelated-References"></a>
-<h4 class="subsection">75.18.2 OS-Related References</h4>
-
-<p>Boykin, Joseph, David Kirschen, Alan Langerman, and Susan
-LoVerso. Programming under Mach. Addison-Wesley, 1994, ISBN
-0-201-52739-1.
-</p>
-<p>Tanenbaum, Andrew S. Distributed Operating Systems. Prentice Hall,
-1995, ISBN 0-13-219908-4 (great textbook).
-</p>
-<p>Silberschatz, Abraham, and Peter B. Galvin. Operating System Concepts,
-4th ed. Addison-Wesley, 1995, ISBN 0-201-59292-4
-</p>
-<hr>
-<a name="perlthrtut-Other-References"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlthrtut-OS_002dRelated-References" accesskey="p"
rel="prev">perlthrtut OS-Related References</a>, Up: <a
href="#perlthrtut-Bibliography" accesskey="u" rel="up">perlthrtut
Bibliography</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Other-References"></a>
-<h4 class="subsection">75.18.3 Other References</h4>
-
-<p>Arnold, Ken and James Gosling. The Java Programming Language, 2nd
-ed. Addison-Wesley, 1998, ISBN 0-201-31006-6.
-</p>
-<p>comp.programming.threads FAQ,
-<a
href="http://www.serpentine.com/~bos/threads-faq/";>http://www.serpentine.com/~bos/threads-faq/</a>
-</p>
-<p>Le Sergent, T. and B. Berthomieu. "Incremental MultiThreaded Garbage
-Collection on Virtually Shared Memory Architectures" in Memory
-Management: Proc. of the International Workshop IWMM 92, St. Malo,
-France, September 1992, Yves Bekkers and Jacques Cohen, eds. Springer,
-1992, ISBN 3540-55940-X (real-life thread applications).
-</p>
-<p>Artur Bergman, "Where Wizards Fear To Tread", June 11, 2002,
-<a
href="http://www.perl.com/pub/a/2002/06/11/threads.html";>http://www.perl.com/pub/a/2002/06/11/threads.html</a>
-</p>
-<hr>
-<a name="perlthrtut-Acknowledgements"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-AUTHOR" accesskey="n" rel="next">perlthrtut
AUTHOR</a>, Previous: <a href="#perlthrtut-Bibliography" accesskey="p"
rel="prev">perlthrtut Bibliography</a>, Up: <a href="#perlthrtut" accesskey="u"
rel="up">perlthrtut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Acknowledgements"></a>
-<h3 class="section">75.19 Acknowledgements</h3>
-
-<p>Thanks (in no particular order) to Chaim Frenkel, Steve Fink, Gurusamy
-Sarathy, Ilya Zakharevich, Benjamin Sugars, Jürgen Christoffel, Joshua
-Pritikin, and Alan Burlison, for their help in reality-checking and
-polishing this article. Big thanks to Tom Christiansen for his rewrite
-of the prime number generator.
-</p>
-<hr>
-<a name="perlthrtut-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlthrtut-Copyrights" accesskey="n" rel="next">perlthrtut
Copyrights</a>, Previous: <a href="#perlthrtut-Acknowledgements" accesskey="p"
rel="prev">perlthrtut Acknowledgements</a>, Up: <a href="#perlthrtut"
accesskey="u" rel="up">perlthrtut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-27"></a>
-<h3 class="section">75.20 AUTHOR</h3>
-
-<p>Dan Sugalski <address@hidden<gt>
-</p>
-<p>Slightly modified by Arthur Bergman to fit the new thread model/module.
-</p>
-<p>Reworked slightly by Jörg Walter <address@hidden<gt> to be more
concise
-about thread-safety of Perl code.
-</p>
-<p>Rearranged slightly by Elizabeth Mattijsen <address@hidden<gt> to
put
-less emphasis on yield().
-</p>
-<hr>
-<a name="perlthrtut-Copyrights"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlthrtut-AUTHOR" accesskey="p" rel="prev">perlthrtut
AUTHOR</a>, Up: <a href="#perlthrtut" accesskey="u" rel="up">perlthrtut</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Copyrights-1"></a>
-<h3 class="section">75.21 Copyrights</h3>
-
-<p>The original version of this article originally appeared in The Perl
-Journal #10, and is copyright 1998 The Perl Journal. It appears courtesy
-of Jon Orwant and The Perl Journal. This document may be distributed
-under the same terms as Perl itself.
-</p>
-<hr>
-<a name="perltie"></a>
-<div class="header">
-<p>
-Next: <a href="#perltodo" accesskey="n" rel="next">perltodo</a>, Previous: <a
href="#perlthrtut" accesskey="p" rel="prev">perlthrtut</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perltie-1"></a>
-<h2 class="chapter">76 perltie</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perltie-NAME"
accesskey="1">perltie NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltie-SYNOPSIS"
accesskey="2">perltie SYNOPSIS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltie-DESCRIPTION"
accesskey="3">perltie DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltie-SEE-ALSO"
accesskey="4">perltie SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltie-BUGS"
accesskey="5">perltie BUGS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltie-AUTHOR"
accesskey="6">perltie AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perltie-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perltie-SYNOPSIS" accesskey="n" rel="next">perltie
SYNOPSIS</a>, Up: <a href="#perltie" accesskey="u" rel="up">perltie</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-75"></a>
-<h3 class="section">76.1 NAME</h3>
-
-<p>perltie - how to hide an object class in a simple variable
-</p>
-<hr>
-<a name="perltie-SYNOPSIS"></a>
-<div class="header">
-<p>
-Next: <a href="#perltie-DESCRIPTION" accesskey="n" rel="next">perltie
DESCRIPTION</a>, Previous: <a href="#perltie-NAME" accesskey="p"
rel="prev">perltie NAME</a>, Up: <a href="#perltie" accesskey="u"
rel="up">perltie</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SYNOPSIS-11"></a>
-<h3 class="section">76.2 SYNOPSIS</h3>
-
-<pre class="verbatim"> tie VARIABLE, CLASSNAME, LIST
-
- $object = tied VARIABLE
-
- untie VARIABLE
-</pre>
-<hr>
-<a name="perltie-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perltie-SEE-ALSO" accesskey="n" rel="next">perltie SEE
ALSO</a>, Previous: <a href="#perltie-SYNOPSIS" accesskey="p"
rel="prev">perltie SYNOPSIS</a>, Up: <a href="#perltie" accesskey="u"
rel="up">perltie</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-74"></a>
-<h3 class="section">76.3 DESCRIPTION</h3>
-
-<p>Prior to release 5.0 of Perl, a programmer could use dbmopen()
-to connect an on-disk database in the standard Unix dbm(3x)
-format magically to a %HASH in their program. However, their Perl was either
-built with one particular dbm library or another, but not both, and
-you couldn’t extend this mechanism to other packages or types of
variables.
-</p>
-<p>Now you can.
-</p>
-<p>The tie() function binds a variable to a class (package) that will provide
-the implementation for access methods for that variable. Once this magic
-has been performed, accessing a tied variable automatically triggers
-method calls in the proper class. The complexity of the class is
-hidden behind magic methods calls. The method names are in ALL CAPS,
-which is a convention that Perl uses to indicate that they’re called
-implicitly rather than explicitly–just like the BEGIN() and END()
-functions.
-</p>
-<p>In the tie() call, <code>VARIABLE</code> is the name of the variable to be
-enchanted. <code>CLASSNAME</code> is the name of a class implementing objects
of
-the correct type. Any additional arguments in the <code>LIST</code> are
passed to
-the appropriate constructor method for that class–meaning TIESCALAR(),
-TIEARRAY(), TIEHASH(), or TIEHANDLE(). (Typically these are arguments
-such as might be passed to the dbminit() function of C.) The object
-returned by the "new" method is also returned by the tie() function,
-which would be useful if you wanted to access other methods in
-<code>CLASSNAME</code>. (You don’t actually have to return a reference
to a right
-"type" (e.g., HASH or <code>CLASSNAME</code>) so long as it’s
a properly blessed
-object.) You can also retrieve a reference to the underlying object
-using the tied() function.
-</p>
-<p>Unlike dbmopen(), the tie() function will not <code>use</code> or
<code>require</code> a module
-for you–you need to do that explicitly yourself.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perltie-Tying-Scalars"
accesskey="1">perltie Tying Scalars</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltie-Tying-Arrays"
accesskey="2">perltie Tying Arrays</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltie-Tying-Hashes"
accesskey="3">perltie Tying Hashes</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltie-Tying-FileHandles"
accesskey="4">perltie Tying FileHandles</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltie-UNTIE-this-4"
accesskey="5">perltie UNTIE this 4</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltie-The-untie-Gotcha"
accesskey="6">perltie The <code>untie</code>
Gotcha</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perltie-Tying-Scalars"></a>
-<div class="header">
-<p>
-Next: <a href="#perltie-Tying-Arrays" accesskey="n" rel="next">perltie Tying
Arrays</a>, Up: <a href="#perltie-DESCRIPTION" accesskey="u" rel="up">perltie
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Tying-Scalars"></a>
-<h4 class="subsection">76.3.1 Tying Scalars</h4>
-
-<p>A class implementing a tied scalar should define the following methods:
-TIESCALAR, FETCH, STORE, and possibly UNTIE and/or DESTROY.
-</p>
-<p>Let’s look at each in turn, using as an example a tie class for
-scalars that allows the user to do something like:
-</p>
-<pre class="verbatim"> tie $his_speed, 'Nice', getppid();
- tie $my_speed, 'Nice', $$;
-</pre>
-<p>And now whenever either of those variables is accessed, its current
-system priority is retrieved and returned. If those variables are set,
-then the process’s priority is changed!
-</p>
-<p>We’ll use Jarkko Hietaniemi
<<samp>address@hidden</samp>>’s BSD::Resource class (not
-included) to access the PRIO_PROCESS, PRIO_MIN, and PRIO_MAX constants
-from your system, as well as the getpriority() and setpriority() system
-calls. Here’s the preamble of the class.
-</p>
-<pre class="verbatim"> package Nice;
- use Carp;
- use BSD::Resource;
- use strict;
- $Nice::DEBUG = 0 unless defined $Nice::DEBUG;
-</pre>
-<dl compact="compact">
-<dt>TIESCALAR classname, LIST</dt>
-<dd><a name="perltie-TIESCALAR-classname_002c-LIST"></a>
-<p>This is the constructor for the class. That means it is
-expected to return a blessed reference to a new scalar
-(probably anonymous) that it’s creating. For example:
-</p>
-<pre class="verbatim"> sub TIESCALAR {
- my $class = shift;
- my $pid = shift || $$; # 0 means me
-
- if ($pid !~ /^\d+$/) {
- carp "Nice::Tie::Scalar got non-numeric pid $pid" if $^W;
- return undef;
- }
-
- unless (kill 0, $pid) { # EPERM or ERSCH, no doubt
- carp "Nice::Tie::Scalar got bad pid $pid: $!" if $^W;
- return undef;
- }
-
- return bless \$pid, $class;
- }
-</pre>
-<p>This tie class has chosen to return an error rather than raising an
-exception if its constructor should fail. While this is how dbmopen() works,
-other classes may well not wish to be so forgiving. It checks the global
-variable <code>$^W</code> to see whether to emit a bit of noise anyway.
-</p>
-</dd>
-<dt>FETCH this</dt>
-<dd><a name="perltie-FETCH-this"></a>
-<p>This method will be triggered every time the tied variable is accessed
-(read). It takes no arguments beyond its self reference, which is the
-object representing the scalar we’re dealing with. Because in this case
-we’re using just a SCALAR ref for the tied scalar object, a simple $$self
-allows the method to get at the real value stored there. In our example
-below, that real value is the process ID to which we’ve tied our
variable.
-</p>
-<pre class="verbatim"> sub FETCH {
- my $self = shift;
- confess "wrong type" unless ref $self;
- croak "usage error" if @_;
- my $nicety;
- local($!) = 0;
- $nicety = getpriority(PRIO_PROCESS, $$self);
- if ($!) { croak "getpriority failed: $!" }
- return $nicety;
- }
-</pre>
-<p>This time we’ve decided to blow up (raise an exception) if the renice
-fails–there’s no place for us to return an error otherwise, and
it’s
-probably the right thing to do.
-</p>
-</dd>
-<dt>STORE this, value</dt>
-<dd><a name="perltie-STORE-this_002c-value"></a>
-<p>This method will be triggered every time the tied variable is set
-(assigned). Beyond its self reference, it also expects one (and only one)
-argument: the new value the user is trying to assign. Don’t worry about
-returning a value from STORE; the semantic of assignment returning the
-assigned value is implemented with FETCH.
-</p>
-<pre class="verbatim"> sub STORE {
- my $self = shift;
- confess "wrong type" unless ref $self;
- my $new_nicety = shift;
- croak "usage error" if @_;
-
- if ($new_nicety < PRIO_MIN) {
- carp sprintf
- "WARNING: priority %d less than minimum system priority
%d",
- $new_nicety, PRIO_MIN if $^W;
- $new_nicety = PRIO_MIN;
- }
-
- if ($new_nicety > PRIO_MAX) {
- carp sprintf
- "WARNING: priority %d greater than maximum system priority
%d",
- $new_nicety, PRIO_MAX if $^W;
- $new_nicety = PRIO_MAX;
- }
-
- unless (defined setpriority(PRIO_PROCESS, $$self, $new_nicety)) {
- confess "setpriority failed: $!";
- }
- }
-</pre>
-</dd>
-<dt>UNTIE this</dt>
-<dd><a name="perltie-UNTIE-this"></a>
-<p>This method will be triggered when the <code>untie</code> occurs. This can
be useful
-if the class needs to know when no further calls will be made. (Except DESTROY
-of course.) See <a href="#perltie-The-untie-Gotcha">The untie Gotcha</a> below
for more details.
-</p>
-</dd>
-<dt>DESTROY this</dt>
-<dd><a name="perltie-DESTROY-this"></a>
-<p>This method will be triggered when the tied variable needs to be destructed.
-As with other object classes, such a method is seldom necessary, because Perl
-deallocates its moribund object’s memory for you
automatically–this isn’t
-C++, you know. We’ll use a DESTROY method here for debugging purposes
only.
-</p>
-<pre class="verbatim"> sub DESTROY {
- my $self = shift;
- confess "wrong type" unless ref $self;
- carp "[ Nice::DESTROY pid $$self ]" if $Nice::DEBUG;
- }
-</pre>
-</dd>
-</dl>
-
-<p>That’s about all there is to it. Actually, it’s more than all
there
-is to it, because we’ve done a few nice things here for the sake
-of completeness, robustness, and general aesthetics. Simpler
-TIESCALAR classes are certainly possible.
-</p>
-<hr>
-<a name="perltie-Tying-Arrays"></a>
-<div class="header">
-<p>
-Next: <a href="#perltie-Tying-Hashes" accesskey="n" rel="next">perltie Tying
Hashes</a>, Previous: <a href="#perltie-Tying-Scalars" accesskey="p"
rel="prev">perltie Tying Scalars</a>, Up: <a href="#perltie-DESCRIPTION"
accesskey="u" rel="up">perltie DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Tying-Arrays"></a>
-<h4 class="subsection">76.3.2 Tying Arrays</h4>
-
-<p>A class implementing a tied ordinary array should define the following
-methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE, CLEAR
-and perhaps UNTIE and/or DESTROY.
-</p>
-<p>FETCHSIZE and STORESIZE are used to provide <code>$#array</code> and
-equivalent <code>scalar(@array)</code> access.
-</p>
-<p>The methods POP, PUSH, SHIFT, UNSHIFT, SPLICE, DELETE, and EXISTS are
-required if the perl operator with the corresponding (but lowercase) name
-is to operate on the tied array. The <strong>Tie::Array</strong> class can be
used as a
-base class to implement the first five of these in terms of the basic
-methods above. The default implementations of DELETE and EXISTS in
-<strong>Tie::Array</strong> simply <code>croak</code>.
-</p>
-<p>In addition EXTEND will be called when perl would have pre-extended
-allocation in a real array.
-</p>
-<p>For this discussion, we’ll implement an array whose elements are a
fixed
-size at creation. If you try to create an element larger than the fixed
-size, you’ll take an exception. For example:
-</p>
-<pre class="verbatim"> use FixedElem_Array;
- tie @array, 'FixedElem_Array', 3;
- $array[0] = 'cat'; # ok.
- $array[1] = 'dogs'; # exception, length('dogs') > 3.
-</pre>
-<p>The preamble code for the class is as follows:
-</p>
-<pre class="verbatim"> package FixedElem_Array;
- use Carp;
- use strict;
-</pre>
-<dl compact="compact">
-<dt>TIEARRAY classname, LIST</dt>
-<dd><a name="perltie-TIEARRAY-classname_002c-LIST"></a>
-<p>This is the constructor for the class. That means it is expected to
-return a blessed reference through which the new array (probably an
-anonymous ARRAY ref) will be accessed.
-</p>
-<p>In our example, just to show you that you don’t <em>really</em> have
to return an
-ARRAY reference, we’ll choose a HASH reference to represent our object.
-A HASH works out well as a generic record type: the <code>{ELEMSIZE}</code>
field will
-store the maximum element size allowed, and the <code>{ARRAY}</code> field
will hold the
-true ARRAY ref. If someone outside the class tries to dereference the
-object returned (doubtless thinking it an ARRAY ref), they’ll blow up.
-This just goes to show you that you should respect an object’s privacy.
-</p>
-<pre class="verbatim"> sub TIEARRAY {
- my $class = shift;
- my $elemsize = shift;
- if ( @_ || $elemsize =~ /\D/ ) {
- croak "usage: tie ARRAY, '" . __PACKAGE__ . "',
elem_size";
- }
- return bless {
- ELEMSIZE => $elemsize,
- ARRAY => [],
- }, $class;
- }
-</pre>
-</dd>
-<dt>FETCH this, index</dt>
-<dd><a name="perltie-FETCH-this_002c-index"></a>
-<p>This method will be triggered every time an individual element the tied
array
-is accessed (read). It takes one argument beyond its self reference: the
-index whose value we’re trying to fetch.
-</p>
-<pre class="verbatim"> sub FETCH {
- my $self = shift;
- my $index = shift;
- return $self->{ARRAY}->[$index];
- }
-</pre>
-<p>If a negative array index is used to read from an array, the index
-will be translated to a positive one internally by calling FETCHSIZE
-before being passed to FETCH. You may disable this feature by
-assigning a true value to the variable <code>$NEGATIVE_INDICES</code> in the
-tied array class.
-</p>
-<p>As you may have noticed, the name of the FETCH method (et al.) is the same
-for all accesses, even though the constructors differ in names (TIESCALAR
-vs TIEARRAY). While in theory you could have the same class servicing
-several tied types, in practice this becomes cumbersome, and it’s easiest
-to keep them at simply one tie type per class.
-</p>
-</dd>
-<dt>STORE this, index, value</dt>
-<dd><a name="perltie-STORE-this_002c-index_002c-value"></a>
-<p>This method will be triggered every time an element in the tied array is set
-(written). It takes two arguments beyond its self reference: the index at
-which we’re trying to store something and the value we’re trying
to put
-there.
-</p>
-<p>In our example, <code>undef</code> is really
<code>$self->{ELEMSIZE}</code> number of
-spaces so we have a little more work to do here:
-</p>
-<pre class="verbatim"> sub STORE {
- my $self = shift;
- my( $index, $value ) = @_;
- if ( length $value > $self->{ELEMSIZE} ) {
- croak "length of $value is greater than
$self->{ELEMSIZE}";
- }
- # fill in the blanks
- $self->EXTEND( $index ) if $index > $self->FETCHSIZE();
- # right justify to keep element size for smaller elements
- $self->{ARRAY}->[$index] = sprintf
"%$self->{ELEMSIZE}s", $value;
- }
-</pre>
-<p>Negative indexes are treated the same as with FETCH.
-</p>
-</dd>
-<dt>FETCHSIZE this</dt>
-<dd><a name="perltie-FETCHSIZE-this"></a>
-<p>Returns the total number of items in the tied array associated with
-object <em>this</em>. (Equivalent to <code>scalar(@array)</code>). For
example:
-</p>
-<pre class="verbatim"> sub FETCHSIZE {
- my $self = shift;
- return scalar @{$self->{ARRAY}};
- }
-</pre>
-</dd>
-<dt>STORESIZE this, count</dt>
-<dd><a name="perltie-STORESIZE-this_002c-count"></a>
-<p>Sets the total number of items in the tied array associated with
-object <em>this</em> to be <em>count</em>. If this makes the array larger then
-class’s mapping of <code>undef</code> should be returned for new
positions.
-If the array becomes smaller then entries beyond count should be
-deleted.
-</p>
-<p>In our example, ’undef’ is really an element containing
-<code>$self->{ELEMSIZE}</code> number of spaces. Observe:
-</p>
-<pre class="verbatim"> sub STORESIZE {
- my $self = shift;
- my $count = shift;
- if ( $count > $self->FETCHSIZE() ) {
- foreach ( $count - $self->FETCHSIZE() .. $count ) {
- $self->STORE( $_, '' );
- }
- } elsif ( $count < $self->FETCHSIZE() ) {
- foreach ( 0 .. $self->FETCHSIZE() - $count - 2 ) {
- $self->POP();
- }
- }
- }
-</pre>
-</dd>
-<dt>EXTEND this, count</dt>
-<dd><a name="perltie-EXTEND-this_002c-count"></a>
-<p>Informative call that array is likely to grow to have <em>count</em>
entries.
-Can be used to optimize allocation. This method need do nothing.
-</p>
-<p>In our example, we want to make sure there are no blank (<code>undef</code>)
-entries, so <code>EXTEND</code> will make use of <code>STORESIZE</code> to
fill elements
-as needed:
-</p>
-<pre class="verbatim"> sub EXTEND {
- my $self = shift;
- my $count = shift;
- $self->STORESIZE( $count );
- }
-</pre>
-</dd>
-<dt>EXISTS this, key</dt>
-<dd><a name="perltie-EXISTS-this_002c-key"></a>
-<p>Verify that the element at index <em>key</em> exists in the tied array
<em>this</em>.
-</p>
-<p>In our example, we will determine that if an element consists of
-<code>$self->{ELEMSIZE}</code> spaces only, it does not exist:
-</p>
-<pre class="verbatim"> sub EXISTS {
- my $self = shift;
- my $index = shift;
- return 0 if ! defined $self->{ARRAY}->[$index] ||
- $self->{ARRAY}->[$index] eq ' ' x $self->{ELEMSIZE};
- return 1;
- }
-</pre>
-</dd>
-<dt>DELETE this, key</dt>
-<dd><a name="perltie-DELETE-this_002c-key"></a>
-<p>Delete the element at index <em>key</em> from the tied array <em>this</em>.
-</p>
-<p>In our example, a deleted item is <code>$self->{ELEMSIZE}</code> spaces:
-</p>
-<pre class="verbatim"> sub DELETE {
- my $self = shift;
- my $index = shift;
- return $self->STORE( $index, '' );
- }
-</pre>
-</dd>
-<dt>CLEAR this</dt>
-<dd><a name="perltie-CLEAR-this"></a>
-<p>Clear (remove, delete, ...) all values from the tied array associated with
-object <em>this</em>. For example:
-</p>
-<pre class="verbatim"> sub CLEAR {
- my $self = shift;
- return $self->{ARRAY} = [];
- }
-</pre>
-</dd>
-<dt>PUSH this, LIST</dt>
-<dd><a name="perltie-PUSH-this_002c-LIST"></a>
-<p>Append elements of <em>LIST</em> to the array. For example:
-</p>
-<pre class="verbatim"> sub PUSH {
- my $self = shift;
- my @list = @_;
- my $last = $self->FETCHSIZE();
- $self->STORE( $last + $_, $list[$_] ) foreach 0 .. $#list;
- return $self->FETCHSIZE();
- }
-</pre>
-</dd>
-<dt>POP this</dt>
-<dd><a name="perltie-POP-this"></a>
-<p>Remove last element of the array and return it. For example:
-</p>
-<pre class="verbatim"> sub POP {
- my $self = shift;
- return pop @{$self->{ARRAY}};
- }
-</pre>
-</dd>
-<dt>SHIFT this</dt>
-<dd><a name="perltie-SHIFT-this"></a>
-<p>Remove the first element of the array (shifting other elements down)
-and return it. For example:
-</p>
-<pre class="verbatim"> sub SHIFT {
- my $self = shift;
- return shift @{$self->{ARRAY}};
- }
-</pre>
-</dd>
-<dt>UNSHIFT this, LIST</dt>
-<dd><a name="perltie-UNSHIFT-this_002c-LIST"></a>
-<p>Insert LIST elements at the beginning of the array, moving existing elements
-up to make room. For example:
-</p>
-<pre class="verbatim"> sub UNSHIFT {
- my $self = shift;
- my @list = @_;
- my $size = scalar( @list );
- # make room for our list
- @{$self->{ARRAY}}[ $size .. $#{$self->{ARRAY}} + $size ]
- = @{$self->{ARRAY}};
- $self->STORE( $_, $list[$_] ) foreach 0 .. $#list;
- }
-</pre>
-</dd>
-<dt>SPLICE this, offset, length, LIST</dt>
-<dd><a name="perltie-SPLICE-this_002c-offset_002c-length_002c-LIST"></a>
-<p>Perform the equivalent of <code>splice</code> on the array.
-</p>
-<p><em>offset</em> is optional and defaults to zero, negative values count
back
-from the end of the array.
-</p>
-<p><em>length</em> is optional and defaults to rest of the array.
-</p>
-<p><em>LIST</em> may be empty.
-</p>
-<p>Returns a list of the original <em>length</em> elements at <em>offset</em>.
-</p>
-<p>In our example, we’ll use a little shortcut if there is a
<em>LIST</em>:
-</p>
-<pre class="verbatim"> sub SPLICE {
- my $self = shift;
- my $offset = shift || 0;
- my $length = shift || $self->FETCHSIZE() - $offset;
- my @list = ();
- if ( @_ ) {
- tie @list, __PACKAGE__, $self->{ELEMSIZE};
- @list = @_;
- }
- return splice @{$self->{ARRAY}}, $offset, $length, @list;
- }
-</pre>
-</dd>
-<dt>UNTIE this</dt>
-<dd><a name="perltie-UNTIE-this-1"></a>
-<p>Will be called when <code>untie</code> happens. (See <a
href="#perltie-The-untie-Gotcha">The untie Gotcha</a> below.)
-</p>
-</dd>
-<dt>DESTROY this</dt>
-<dd><a name="perltie-DESTROY-this-1"></a>
-<p>This method will be triggered when the tied variable needs to be destructed.
-As with the scalar tie class, this is almost never needed in a
-language that does its own garbage collection, so this time we’ll
-just leave it out.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perltie-Tying-Hashes"></a>
-<div class="header">
-<p>
-Next: <a href="#perltie-Tying-FileHandles" accesskey="n" rel="next">perltie
Tying FileHandles</a>, Previous: <a href="#perltie-Tying-Arrays" accesskey="p"
rel="prev">perltie Tying Arrays</a>, Up: <a href="#perltie-DESCRIPTION"
accesskey="u" rel="up">perltie DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Tying-Hashes"></a>
-<h4 class="subsection">76.3.3 Tying Hashes</h4>
-
-<p>Hashes were the first Perl data type to be tied (see dbmopen()). A class
-implementing a tied hash should define the following methods: TIEHASH is
-the constructor. FETCH and STORE access the key and value pairs. EXISTS
-reports whether a key is present in the hash, and DELETE deletes one.
-CLEAR empties the hash by deleting all the key and value pairs. FIRSTKEY
-and NEXTKEY implement the keys() and each() functions to iterate over all
-the keys. SCALAR is triggered when the tied hash is evaluated in scalar
-context. UNTIE is called when <code>untie</code> happens, and DESTROY is
called when
-the tied variable is garbage collected.
-</p>
-<p>If this seems like a lot, then feel free to inherit from merely the
-standard Tie::StdHash module for most of your methods, redefining only the
-interesting ones. See <a href="Tie-Hash.html#Top">(Tie-Hash)</a> for details.
-</p>
-<p>Remember that Perl distinguishes between a key not existing in the hash,
-and the key existing in the hash but having a corresponding value of
-<code>undef</code>. The two possibilities can be tested with the
<code>exists()</code> and
-<code>defined()</code> functions.
-</p>
-<p>Here’s an example of a somewhat interesting tied hash class: it
gives you
-a hash representing a particular user’s dot files. You index into the
hash
-with the name of the file (minus the dot) and you get back that dot
file’s
-contents. For example:
-</p>
-<pre class="verbatim"> use DotFiles;
- tie %dot, 'DotFiles';
- if ( $dot{profile} =~ /MANPATH/ ||
- $dot{login} =~ /MANPATH/ ||
- $dot{cshrc} =~ /MANPATH/ )
- {
- print "you seem to set your MANPATH\n";
- }
-</pre>
-<p>Or here’s another sample of using our tied class:
-</p>
-<pre class="verbatim"> tie %him, 'DotFiles', 'daemon';
- foreach $f ( keys %him ) {
- printf "daemon dot file %s is size %d\n",
- $f, length $him{$f};
- }
-</pre>
-<p>In our tied hash DotFiles example, we use a regular
-hash for the object containing several important
-fields, of which only the <code>{LIST}</code> field will be what the
-user thinks of as the real hash.
-</p>
-<dl compact="compact">
-<dt>USER</dt>
-<dd><a name="perltie-USER"></a>
-<p>whose dot files this object represents
-</p>
-</dd>
-<dt>HOME</dt>
-<dd><a name="perltie-HOME"></a>
-<p>where those dot files live
-</p>
-</dd>
-<dt>CLOBBER</dt>
-<dd><a name="perltie-CLOBBER"></a>
-<p>whether we should try to change or remove those dot files
-</p>
-</dd>
-<dt>LIST</dt>
-<dd><a name="perltie-LIST"></a>
-<p>the hash of dot file names and content mappings
-</p>
-</dd>
-</dl>
-
-<p>Here’s the start of <samp>Dotfiles.pm</samp>:
-</p>
-<pre class="verbatim"> package DotFiles;
- use Carp;
- sub whowasi { (caller(1))[3] . '()' }
- my $DEBUG = 0;
- sub debug { $DEBUG = @_ ? shift : 1 }
-</pre>
-<p>For our example, we want to be able to emit debugging info to help in
tracing
-during development. We keep also one convenience function around
-internally to help print out warnings; whowasi() returns the function name
-that calls it.
-</p>
-<p>Here are the methods for the DotFiles tied hash.
-</p>
-<dl compact="compact">
-<dt>TIEHASH classname, LIST</dt>
-<dd><a name="perltie-TIEHASH-classname_002c-LIST"></a>
-<p>This is the constructor for the class. That means it is expected to
-return a blessed reference through which the new object (probably but not
-necessarily an anonymous hash) will be accessed.
-</p>
-<p>Here’s the constructor:
-</p>
-<pre class="verbatim"> sub TIEHASH {
- my $self = shift;
- my $user = shift || $>;
- my $dotdir = shift || '';
- croak "usage: @{[&whowasi]} [USER [DOTDIR]]" if @_;
- $user = getpwuid($user) if $user =~ /^\d+$/;
- my $dir = (getpwnam($user))[7]
- || croak "@{[&whowasi]}: no user $user";
- $dir .= "/$dotdir" if $dotdir;
-
- my $node = {
- USER => $user,
- HOME => $dir,
- LIST => {},
- CLOBBER => 0,
- };
-
- opendir(DIR, $dir)
- || croak "@{[&whowasi]}: can't opendir $dir: $!";
- foreach $dot ( grep /^\./ && -f "$dir/$_",
readdir(DIR)) {
- $dot =~ s/^\.//;
- $node->{LIST}{$dot} = undef;
- }
- closedir DIR;
- return bless $node, $self;
- }
-</pre>
-<p>It’s probably worth mentioning that if you’re going to filetest
the
-return values out of a readdir, you’d better prepend the directory
-in question. Otherwise, because we didn’t chdir() there, it would
-have been testing the wrong file.
-</p>
-</dd>
-<dt>FETCH this, key</dt>
-<dd><a name="perltie-FETCH-this_002c-key"></a>
-<p>This method will be triggered every time an element in the tied hash is
-accessed (read). It takes one argument beyond its self reference: the key
-whose value we’re trying to fetch.
-</p>
-<p>Here’s the fetch for our DotFiles example.
-</p>
-<pre class="verbatim"> sub FETCH {
- carp &whowasi if $DEBUG;
- my $self = shift;
- my $dot = shift;
- my $dir = $self->{HOME};
- my $file = "$dir/.$dot";
-
- unless (exists $self->{LIST}->{$dot} || -f $file) {
- carp "@{[&whowasi]}: no $dot file" if $DEBUG;
- return undef;
- }
-
- if (defined $self->{LIST}->{$dot}) {
- return $self->{LIST}->{$dot};
- } else {
- return $self->{LIST}->{$dot} = `cat $dir/.$dot`;
- }
- }
-</pre>
-<p>It was easy to write by having it call the Unix cat(1) command, but it
-would probably be more portable to open the file manually (and somewhat
-more efficient). Of course, because dot files are a Unixy concept, we’re
-not that concerned.
-</p>
-</dd>
-<dt>STORE this, key, value</dt>
-<dd><a name="perltie-STORE-this_002c-key_002c-value"></a>
-<p>This method will be triggered every time an element in the tied hash is set
-(written). It takes two arguments beyond its self reference: the index at
-which we’re trying to store something, and the value we’re trying
to put
-there.
-</p>
-<p>Here in our DotFiles example, we’ll be careful not to let
-them try to overwrite the file unless they’ve called the clobber()
-method on the original object reference returned by tie().
-</p>
-<pre class="verbatim"> sub STORE {
- carp &whowasi if $DEBUG;
- my $self = shift;
- my $dot = shift;
- my $value = shift;
- my $file = $self->{HOME} . "/.$dot";
- my $user = $self->{USER};
-
- croak "@{[&whowasi]}: $file not clobberable"
- unless $self->{CLOBBER};
-
- open(my $f, '>', $file) || croak "can't open $file: $!";
- print $f $value;
- close($f);
- }
-</pre>
-<p>If they wanted to clobber something, they might say:
-</p>
-<pre class="verbatim"> $ob = tie %daemon_dots, 'daemon';
- $ob->clobber(1);
- $daemon_dots{signature} = "A true daemon\n";
-</pre>
-<p>Another way to lay hands on a reference to the underlying object is to
-use the tied() function, so they might alternately have set clobber
-using:
-</p>
-<pre class="verbatim"> tie %daemon_dots, 'daemon';
- tied(%daemon_dots)->clobber(1);
-</pre>
-<p>The clobber method is simply:
-</p>
-<pre class="verbatim"> sub clobber {
- my $self = shift;
- $self->{CLOBBER} = @_ ? shift : 1;
- }
-</pre>
-</dd>
-<dt>DELETE this, key</dt>
-<dd><a name="perltie-DELETE-this_002c-key-1"></a>
-<p>This method is triggered when we remove an element from the hash,
-typically by using the delete() function. Again, we’ll
-be careful to check whether they really want to clobber files.
-</p>
-<pre class="verbatim"> sub DELETE {
- carp &whowasi if $DEBUG;
-
- my $self = shift;
- my $dot = shift;
- my $file = $self->{HOME} . "/.$dot";
- croak "@{[&whowasi]}: won't remove file $file"
- unless $self->{CLOBBER};
- delete $self->{LIST}->{$dot};
- my $success = unlink($file);
- carp "@{[&whowasi]}: can't unlink $file: $!" unless
$success;
- $success;
- }
-</pre>
-<p>The value returned by DELETE becomes the return value of the call
-to delete(). If you want to emulate the normal behavior of delete(),
-you should return whatever FETCH would have returned for this key.
-In this example, we have chosen instead to return a value which tells
-the caller whether the file was successfully deleted.
-</p>
-</dd>
-<dt>CLEAR this</dt>
-<dd><a name="perltie-CLEAR-this-1"></a>
-<p>This method is triggered when the whole hash is to be cleared, usually by
-assigning the empty list to it.
-</p>
-<p>In our example, that would remove all the user’s dot files!
It’s such a
-dangerous thing that they’ll have to set CLOBBER to something higher than
-1 to make it happen.
-</p>
-<pre class="verbatim"> sub CLEAR {
- carp &whowasi if $DEBUG;
- my $self = shift;
- croak "@{[&whowasi]}: won't remove all dot files for
$self->{USER}"
- unless $self->{CLOBBER} > 1;
- my $dot;
- foreach $dot ( keys %{$self->{LIST}}) {
- $self->DELETE($dot);
- }
- }
-</pre>
-</dd>
-<dt>EXISTS this, key</dt>
-<dd><a name="perltie-EXISTS-this_002c-key-1"></a>
-<p>This method is triggered when the user uses the exists() function
-on a particular hash. In our example, we’ll look at the
<code>{LIST}</code>
-hash element for this:
-</p>
-<pre class="verbatim"> sub EXISTS {
- carp &whowasi if $DEBUG;
- my $self = shift;
- my $dot = shift;
- return exists $self->{LIST}->{$dot};
- }
-</pre>
-</dd>
-<dt>FIRSTKEY this</dt>
-<dd><a name="perltie-FIRSTKEY-this"></a>
-<p>This method will be triggered when the user is going
-to iterate through the hash, such as via a keys(), values(), or each() call.
-</p>
-<pre class="verbatim"> sub FIRSTKEY {
- carp &whowasi if $DEBUG;
- my $self = shift;
- my $a = keys %{$self->{LIST}}; # reset each() iterator
- each %{$self->{LIST}}
- }
-</pre>
-<p>FIRSTKEY is always called in scalar context and it should just
-return the first key. values(), and each() in list context,
-will call FETCH for the returned keys.
-</p>
-</dd>
-<dt>NEXTKEY this, lastkey</dt>
-<dd><a name="perltie-NEXTKEY-this_002c-lastkey"></a>
-<p>This method gets triggered during a keys(), values(), or each() iteration.
It has a
-second argument which is the last key that had been accessed. This is
-useful if you’re caring about ordering or calling the iterator from more
-than one sequence, or not really storing things in a hash anywhere.
-</p>
-<p>NEXTKEY is always called in scalar context and it should just
-return the next key. values(), and each() in list context,
-will call FETCH for the returned keys.
-</p>
-<p>For our example, we’re using a real hash so we’ll do just the
simple
-thing, but we’ll have to go through the LIST field indirectly.
-</p>
-<pre class="verbatim"> sub NEXTKEY {
- carp &whowasi if $DEBUG;
- my $self = shift;
- return each %{ $self->{LIST} }
- }
-</pre>
-</dd>
-<dt>SCALAR this</dt>
-<dd><a name="perltie-SCALAR-this"></a>
-<p>This is called when the hash is evaluated in scalar context. In order
-to mimic the behaviour of untied hashes, this method should return a
-false value when the tied hash is considered empty. If this method does
-not exist, perl will make some educated guesses and return true when
-the hash is inside an iteration. If this isn’t the case, FIRSTKEY is
-called, and the result will be a false value if FIRSTKEY returns the empty
-list, true otherwise.
-</p>
-<p>However, you should <strong>not</strong> blindly rely on perl always doing
the right
-thing. Particularly, perl will mistakenly return true when you clear the
-hash by repeatedly calling DELETE until it is empty. You are therefore
-advised to supply your own SCALAR method when you want to be absolutely
-sure that your hash behaves nicely in scalar context.
-</p>
-<p>In our example we can just call <code>scalar</code> on the underlying hash
-referenced by <code>$self->{LIST}</code>:
-</p>
-<pre class="verbatim"> sub SCALAR {
- carp &whowasi if $DEBUG;
- my $self = shift;
- return scalar %{ $self->{LIST} }
- }
-</pre>
-</dd>
-<dt>UNTIE this</dt>
-<dd><a name="perltie-UNTIE-this-2"></a>
-<p>This is called when <code>untie</code> occurs. See <a
href="#perltie-The-untie-Gotcha">The untie Gotcha</a> below.
-</p>
-</dd>
-<dt>DESTROY this</dt>
-<dd><a name="perltie-DESTROY-this-2"></a>
-<p>This method is triggered when a tied hash is about to go out of
-scope. You don’t really need it unless you’re trying to add
debugging
-or have auxiliary state to clean up. Here’s a very simple function:
-</p>
-<pre class="verbatim"> sub DESTROY {
- carp &whowasi if $DEBUG;
- }
-</pre>
-</dd>
-</dl>
-
-<p>Note that functions such as keys() and values() may return huge lists
-when used on large objects, like DBM files. You may prefer to use the
-each() function to iterate over such. Example:
-</p>
-<pre class="verbatim"> # print out history file offsets
- use NDBM_File;
- tie(%HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
- while (($key,$val) = each %HIST) {
- print $key, ' = ', unpack('L',$val), "\n";
- }
- untie(%HIST);
-</pre>
-<hr>
-<a name="perltie-Tying-FileHandles"></a>
-<div class="header">
-<p>
-Next: <a href="#perltie-UNTIE-this-4" accesskey="n" rel="next">perltie UNTIE
this 4</a>, Previous: <a href="#perltie-Tying-Hashes" accesskey="p"
rel="prev">perltie Tying Hashes</a>, Up: <a href="#perltie-DESCRIPTION"
accesskey="u" rel="up">perltie DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Tying-FileHandles"></a>
-<h4 class="subsection">76.3.4 Tying FileHandles</h4>
-
-<p>This is partially implemented now.
-</p>
-<p>A class implementing a tied filehandle should define the following
-methods: TIEHANDLE, at least one of PRINT, PRINTF, WRITE, READLINE, GETC,
-READ, and possibly CLOSE, UNTIE and DESTROY. The class can also provide:
BINMODE,
-OPEN, EOF, FILENO, SEEK, TELL - if the corresponding perl operators are
-used on the handle.
-</p>
-<p>When STDERR is tied, its PRINT method will be called to issue warnings
-and error messages. This feature is temporarily disabled during the call,
-which means you can use <code>warn()</code> inside PRINT without starting a
recursive
-loop. And just like <code>__WARN__</code> and <code>__DIE__</code> handlers,
STDERR’s PRINT
-method may be called to report parser errors, so the caveats mentioned under
-<a href="#perlvar-_0025SIG">perlvar %SIG</a> apply.
-</p>
-<p>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.
-</p>
-<p>When tying a handle, the first argument to <code>tie</code> should begin
with an
-asterisk. So, if you are tying STDOUT, use <code>*STDOUT</code>. If you have
-assigned it to a scalar variable, say <code>$handle</code>, use
<code>*$handle</code>.
-<code>tie $handle</code> ties the scalar variable <code>$handle</code>, not
the handle inside
-it.
-</p>
-<p>In our example we’re going to create a shouting handle.
-</p>
-<pre class="verbatim"> package Shout;
-</pre>
-<dl compact="compact">
-<dt>TIEHANDLE classname, LIST</dt>
-<dd><a name="perltie-TIEHANDLE-classname_002c-LIST"></a>
-<p>This is the constructor for the class. That means it is expected to
-return a blessed reference of some sort. The reference can be used to
-hold some internal information.
-</p>
-<pre class="verbatim"> sub TIEHANDLE { print "<shout>\n";
my $i; bless \$i, shift }
-</pre>
-</dd>
-<dt>WRITE this, LIST</dt>
-<dd><a name="perltie-WRITE-this_002c-LIST"></a>
-<p>This method will be called when the handle is written to via the
-<code>syswrite</code> function.
-</p>
-<pre class="verbatim"> sub WRITE {
- $r = shift;
- my($buf,$len,$offset) = @_;
- print "WRITE called, \$buf=$buf, \$len=$len,
\$offset=$offset";
- }
-</pre>
-</dd>
-<dt>PRINT this, LIST</dt>
-<dd><a name="perltie-PRINT-this_002c-LIST"></a>
-<p>This method will be triggered every time the tied handle is printed to
-with the <code>print()</code> or <code>say()</code> functions. Beyond its
self reference
-it also expects the list that was passed to the print function.
-</p>
-<pre class="verbatim"> sub PRINT { $r = shift; $$r++; print
join($,,map(uc($_),@_)),$\ }
-</pre>
-<p><code>say()</code> acts just like <code>print()</code> except $\ will be
localized to <code>\n</code> so
-you need do nothing special to handle <code>say()</code> in
<code>PRINT()</code>.
-</p>
-</dd>
-<dt>PRINTF this, LIST</dt>
-<dd><a name="perltie-PRINTF-this_002c-LIST"></a>
-<p>This method will be triggered every time the tied handle is printed to
-with the <code>printf()</code> function.
-Beyond its self reference it also expects the format and list that was
-passed to the printf function.
-</p>
-<pre class="verbatim"> sub PRINTF {
- shift;
- my $fmt = shift;
- print sprintf($fmt, @_);
- }
-</pre>
-</dd>
-<dt>READ this, LIST</dt>
-<dd><a name="perltie-READ-this_002c-LIST"></a>
-<p>This method will be called when the handle is read from via the
<code>read</code>
-or <code>sysread</code> functions.
-</p>
-<pre class="verbatim"> sub READ {
- my $self = shift;
- my $bufref = \$_[0];
- my(undef,$len,$offset) = @_;
- print "READ called, \$buf=$bufref, \$len=$len,
\$offset=$offset";
- # add to $$bufref, set $len to number of characters read
- $len;
- }
-</pre>
-</dd>
-<dt>READLINE this</dt>
-<dd><a name="perltie-READLINE-this"></a>
-<p>This method is called when the handle is read via
<code><HANDLE></code>
-or <code>readline HANDLE</code>.
-</p>
-<p>As per <a href="#perlfunc-readline"><code>readline</code></a>, in scalar
context it should return
-the next line, or <code>undef</code> 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 <code>$/</code> (see <a
href="#perlvar-NAME">perlvar NAME</a>),
-unless it is <code>undef</code> (which means "slurp" mode).
-</p>
-<pre class="verbatim"> sub READLINE {
- my $r = shift;
- if (wantarray) {
- return ("all remaining\n",
- "lines up\n",
- "to eof\n");
- } else {
- return "READLINE called " . ++$$r . " times\n";
- }
- }
-</pre>
-</dd>
-<dt>GETC this</dt>
-<dd><a name="perltie-GETC-this"></a>
-<p>This method will be called when the <code>getc</code> function is called.
-</p>
-<pre class="verbatim"> sub GETC { print "Don't GETC, Get Perl";
return "a"; }
-</pre>
-</dd>
-<dt>EOF this</dt>
-<dd><a name="perltie-EOF-this"></a>
-<p>This method will be called when the <code>eof</code> function is called.
-</p>
-<p>Starting with Perl 5.12, an additional integer parameter will be passed. It
-will be zero if <code>eof</code> is called without parameter; <code>1</code>
if <code>eof</code> is given
-a filehandle as a parameter, e.g. <code>eof(FH)</code>; and <code>2</code> in
the very special
-case that the tied filehandle is <code>ARGV</code> and <code>eof</code> is
called with an empty
-parameter list, e.g. <code>eof()</code>.
-</p>
-<pre class="verbatim"> sub EOF { not length $stringbuf }
-</pre>
-</dd>
-<dt>CLOSE this</dt>
-<dd><a name="perltie-CLOSE-this"></a>
-<p>This method will be called when the handle is closed via the
<code>close</code>
-function.
-</p>
-<pre class="verbatim"> sub CLOSE { print "CLOSE called.\n" }
-</pre>
-</dd>
-<dt>UNTIE this</dt>
-<dd><a name="perltie-UNTIE-this-3"></a>
-<p>As with the other types of ties, this method will be called when
<code>untie</code> happens.
-It may be appropriate to "auto CLOSE" when this occurs. See
-<a href="#perltie-The-untie-Gotcha">The untie Gotcha</a> below.
-</p>
-</dd>
-<dt>DESTROY this</dt>
-<dd><a name="perltie-DESTROY-this-3"></a>
-<p>As with the other types of ties, this method will be called when the
-tied handle is about to be destroyed. This is useful for debugging and
-possibly cleaning up.
-</p>
-<pre class="verbatim"> sub DESTROY { print "</shout>\n" }
-</pre>
-</dd>
-</dl>
-
-<p>Here’s how to use our little example:
-</p>
-<pre class="verbatim"> tie(*FOO,'Shout');
- print FOO "hello\n";
- $a = 4; $b = 6;
- print FOO $a, " plus ", $b, " equals ", $a + $b,
"\n";
- print <FOO>;
-</pre>
-<hr>
-<a name="perltie-UNTIE-this-4"></a>
-<div class="header">
-<p>
-Next: <a href="#perltie-The-untie-Gotcha" accesskey="n" rel="next">perltie The
<code>untie</code> Gotcha</a>, Previous: <a href="#perltie-Tying-FileHandles"
accesskey="p" rel="prev">perltie Tying FileHandles</a>, Up: <a
href="#perltie-DESCRIPTION" accesskey="u" rel="up">perltie DESCRIPTION</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="UNTIE-this"></a>
-<h4 class="subsection">76.3.5 UNTIE this</h4>
-
-<p>You can define for all tie types an UNTIE method that will be called
-at untie(). See <a href="#perltie-The-untie-Gotcha">The untie Gotcha</a>
below.
-</p>
-<hr>
-<a name="perltie-The-untie-Gotcha"></a>
-<div class="header">
-<p>
-Previous: <a href="#perltie-UNTIE-this-4" accesskey="p" rel="prev">perltie
UNTIE this 4</a>, Up: <a href="#perltie-DESCRIPTION" accesskey="u"
rel="up">perltie DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="The-untie-Gotcha"></a>
-<h4 class="subsection">76.3.6 The <code>untie</code> Gotcha</h4>
-
-<p>If you intend making use of the object returned from either tie() or
-tied(), and if the tie’s target class defines a destructor, there is a
-subtle gotcha you <em>must</em> guard against.
-</p>
-<p>As setup, consider this (admittedly rather contrived) example of a
-tie; all it does is use a file to keep a log of the values assigned to
-a scalar.
-</p>
-<pre class="verbatim"> package Remember;
-
- use strict;
- use warnings;
- use IO::File;
-
- sub TIESCALAR {
- my $class = shift;
- my $filename = shift;
- my $handle = IO::File->new( "> $filename" )
- or die "Cannot open $filename: $!\n";
-
- print $handle "The Start\n";
- bless {FH => $handle, Value => 0}, $class;
- }
-
- sub FETCH {
- my $self = shift;
- return $self->{Value};
- }
-
- sub STORE {
- my $self = shift;
- my $value = shift;
- my $handle = $self->{FH};
- print $handle "$value\n";
- $self->{Value} = $value;
- }
-
- sub DESTROY {
- my $self = shift;
- my $handle = $self->{FH};
- print $handle "The End\n";
- close $handle;
- }
-
- 1;
-</pre>
-<p>Here is an example that makes use of this tie:
-</p>
-<pre class="verbatim"> use strict;
- use Remember;
-
- my $fred;
- tie $fred, 'Remember', 'myfile.txt';
- $fred = 1;
- $fred = 4;
- $fred = 5;
- untie $fred;
- system "cat myfile.txt";
-</pre>
-<p>This is the output when it is executed:
-</p>
-<pre class="verbatim"> The Start
- 1
- 4
- 5
- The End
-</pre>
-<p>So far so good. Those of you who have been paying attention will have
-spotted that the tied object hasn’t been used so far. So lets add an
-extra method to the Remember class to allow comments to be included in
-the file; say, something like this:
-</p>
-<pre class="verbatim"> sub comment {
- my $self = shift;
- my $text = shift;
- my $handle = $self->{FH};
- print $handle $text, "\n";
- }
-</pre>
-<p>And here is the previous example modified to use the <code>comment</code>
method
-(which requires the tied object):
-</p>
-<pre class="verbatim"> use strict;
- use Remember;
-
- my ($fred, $x);
- $x = tie $fred, 'Remember', 'myfile.txt';
- $fred = 1;
- $fred = 4;
- comment $x "changing...";
- $fred = 5;
- untie $fred;
- system "cat myfile.txt";
-</pre>
-<p>When this code is executed there is no output. Here’s why:
-</p>
-<p>When a variable is tied, it is associated with the object which is the
-return value of the TIESCALAR, TIEARRAY, or TIEHASH function. This
-object normally has only one reference, namely, the implicit reference
-from the tied variable. When untie() is called, that reference is
-destroyed. Then, as in the first example above, the object’s
-destructor (DESTROY) is called, which is normal for objects that have
-no more valid references; and thus the file is closed.
-</p>
-<p>In the second example, however, we have stored another reference to
-the tied object in $x. That means that when untie() gets called
-there will still be a valid reference to the object in existence, so
-the destructor is not called at that time, and thus the file is not
-closed. The reason there is no output is because the file buffers
-have not been flushed to disk.
-</p>
-<p>Now that you know what the problem is, what can you do to avoid it?
-Prior to the introduction of the optional UNTIE method the only way
-was the good old <code>-w</code> flag. Which will spot any instances where you
call
-untie() and there are still valid references to the tied object. If
-the second script above this near the top <code>use warnings 'untie'</code>
-or was run with the <code>-w</code> flag, Perl prints this
-warning message:
-</p>
-<pre class="verbatim"> untie attempted while 1 inner references still exist
-</pre>
-<p>To get the script to work properly and silence the warning make sure
-there are no valid references to the tied object <em>before</em> untie() is
-called:
-</p>
-<pre class="verbatim"> undef $x;
- untie $fred;
-</pre>
-<p>Now that UNTIE exists the class designer can decide which parts of the
-class functionality are really associated with <code>untie</code> and which
with
-the object being destroyed. What makes sense for a given class depends
-on whether the inner references are being kept so that non-tie-related
-methods can be called on the object. But in most cases it probably makes
-sense to move the functionality that would have been in DESTROY to the UNTIE
-method.
-</p>
-<p>If the UNTIE method exists then the warning above does not occur. Instead
the
-UNTIE method is passed the count of "extra" references and can issue
its own
-warning if appropriate. e.g. to replicate the no UNTIE case this method can
-be used:
-</p>
-<pre class="verbatim"> sub UNTIE
- {
- my ($obj,$count) = @_;
- carp "untie attempted while $count inner references still
exist" if $count;
- }
-</pre>
-<hr>
-<a name="perltie-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perltie-BUGS" accesskey="n" rel="next">perltie BUGS</a>,
Previous: <a href="#perltie-DESCRIPTION" accesskey="p" rel="prev">perltie
DESCRIPTION</a>, Up: <a href="#perltie" accesskey="u" rel="up">perltie</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-39"></a>
-<h3 class="section">76.4 SEE ALSO</h3>
-
-<p>See <a href="DB_File.html#Top">(DB_File)</a> or <a
href="Config.html#Top">(Config)</a> for some interesting tie() implementations.
-A good starting point for many tie() implementations is with one of the
-modules <a href="Tie-Scalar.html#Top">(Tie-Scalar)</a>, <a
href="Tie-Array.html#Top">(Tie-Array)</a>, <a
href="Tie-Hash.html#Top">(Tie-Hash)</a>, or <a
href="Tie-Handle.html#Top">(Tie-Handle)</a>.
-</p>
-<hr>
-<a name="perltie-BUGS"></a>
-<div class="header">
-<p>
-Next: <a href="#perltie-AUTHOR" accesskey="n" rel="next">perltie AUTHOR</a>,
Previous: <a href="#perltie-SEE-ALSO" accesskey="p" rel="prev">perltie SEE
ALSO</a>, Up: <a href="#perltie" accesskey="u" rel="up">perltie</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="BUGS-9"></a>
-<h3 class="section">76.5 BUGS</h3>
-
-<p>The bucket usage information provided by <code>scalar(%hash)</code> is not
-available. What this means is that using %tied_hash in boolean
-context doesn’t work right (currently this always tests false,
-regardless of whether the hash is empty or hash elements).
-</p>
-<p>Localizing tied arrays or hashes does not work. After exiting the
-scope the arrays or the hashes are not restored.
-</p>
-<p>Counting the number of entries in a hash via
<code>scalar(keys(%hash))</code>
-or <code>scalar(values(%hash)</code>) is inefficient since it needs to iterate
-through all the entries with FIRSTKEY/NEXTKEY.
-</p>
-<p>Tied hash/array slices cause multiple FETCH/STORE pairs, there are no
-tie methods for slice operations.
-</p>
-<p>You cannot easily tie a multilevel data structure (such as a hash of
-hashes) to a dbm file. The first problem is that all but GDBM and
-Berkeley DB have size limitations, but beyond that, you also have problems
-with how references are to be represented on disk. One
-module that does attempt to address this need is DBM::Deep. Check your
-nearest CPAN site as described in <a
href="perlmodlib.html#Top">(perlmodlib)</a> for source code. Note
-that despite its name, DBM::Deep does not use dbm. Another earlier attempt
-at solving the problem is MLDBM, which is also available on the CPAN, but
-which has some fairly serious limitations.
-</p>
-<p>Tied filehandles are still incomplete. sysopen(), truncate(),
-flock(), fcntl(), stat() and -X can’t currently be trapped.
-</p>
-<hr>
-<a name="perltie-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perltie-BUGS" accesskey="p" rel="prev">perltie BUGS</a>,
Up: <a href="#perltie" accesskey="u" rel="up">perltie</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-28"></a>
-<h3 class="section">76.6 AUTHOR</h3>
-
-<p>Tom Christiansen
-</p>
-<p>TIEHANDLE by Sven Verdoolaege <<samp>address@hidden</samp>> and Doug
MacEachern <<samp>address@hidden</samp>>
-</p>
-<p>UNTIE by Nick Ing-Simmons <<samp>address@hidden</samp>>
-</p>
-<p>SCALAR by Tassilo von Parseval <<samp>address@hidden</samp>>
-</p>
-<p>Tying Arrays by Casey West <<samp>address@hidden</samp>>
-</p>
-<hr>
-<a name="perltodo"></a>
-<div class="header">
-<p>
-Next: <a href="#perltooc" accesskey="n" rel="next">perltooc</a>, Previous: <a
href="#perltie" accesskey="p" rel="prev">perltie</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perltodo-1"></a>
-<h2 class="chapter">77 perltodo</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perltodo-NAME"
accesskey="1">perltodo NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltodo-DESCRIPTION"
accesskey="2">perltodo DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perltodo-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perltodo-DESCRIPTION" accesskey="n" rel="next">perltodo
DESCRIPTION</a>, Up: <a href="#perltodo" accesskey="u" rel="up">perltodo</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-76"></a>
-<h3 class="section">77.1 NAME</h3>
-
-<p>perltodo - Link to the Perl to-do list
-</p>
-<hr>
-<a name="perltodo-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perltodo-NAME" accesskey="p" rel="prev">perltodo NAME</a>,
Up: <a href="#perltodo" accesskey="u" rel="up">perltodo</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-75"></a>
-<h3 class="section">77.2 DESCRIPTION</h3>
-
-<p>The Perl 5 to-do list is maintained in the git repository, and can
-be viewed at <a
href="http://perl5.git.perl.org/perl.git/blob/HEAD:/Porting/todo.pod";>http://perl5.git.perl.org/perl.git/blob/HEAD:/Porting/todo.pod</a>
-</p>
-<p>(The to-do list used to be here in perltodo. That has stopped, as
installing a
-snapshot that becomes increasingly out of date isn’t that useful to
anyone.)
-</p>
-<hr>
-<a name="perltooc"></a>
-<div class="header">
-<p>
-Next: <a href="#perltoot" accesskey="n" rel="next">perltoot</a>, Previous: <a
href="#perltodo" accesskey="p" rel="prev">perltodo</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perltooc-1"></a>
-<h2 class="chapter">78 perltooc</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perltooc-NAME"
accesskey="1">perltooc NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltooc-DESCRIPTION"
accesskey="2">perltooc DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perltooc-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perltooc-DESCRIPTION" accesskey="n" rel="next">perltooc
DESCRIPTION</a>, Up: <a href="#perltooc" accesskey="u" rel="up">perltooc</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-77"></a>
-<h3 class="section">78.1 NAME</h3>
-
-<p>perltooc - Links to information on object-oriented programming in Perl
-</p>
-<hr>
-<a name="perltooc-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perltooc-NAME" accesskey="p" rel="prev">perltooc NAME</a>,
Up: <a href="#perltooc" accesskey="u" rel="up">perltooc</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-76"></a>
-<h3 class="section">78.2 DESCRIPTION</h3>
-
-<p>For information on OO programming with Perl, please see <a
href="#perlootut-NAME">perlootut NAME</a>
-and <a href="#perlobj-NAME">perlobj NAME</a>.
-</p>
-<p>(The above documents supersede the tutorial that was formerly here in
-perltooc.)
-</p>
-<hr>
-<a name="perltoot"></a>
-<div class="header">
-<p>
-Next: <a href="#perltrap" accesskey="n" rel="next">perltrap</a>, Previous: <a
href="#perltooc" accesskey="p" rel="prev">perltooc</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perltoot-1"></a>
-<h2 class="chapter">79 perltoot</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perltoot-NAME"
accesskey="1">perltoot NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltoot-DESCRIPTION"
accesskey="2">perltoot DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perltoot-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perltoot-DESCRIPTION" accesskey="n" rel="next">perltoot
DESCRIPTION</a>, Up: <a href="#perltoot" accesskey="u" rel="up">perltoot</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-78"></a>
-<h3 class="section">79.1 NAME</h3>
-
-<p>perltoot - Links to information on object-oriented programming in Perl
-</p>
-<hr>
-<a name="perltoot-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perltoot-NAME" accesskey="p" rel="prev">perltoot NAME</a>,
Up: <a href="#perltoot" accesskey="u" rel="up">perltoot</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-77"></a>
-<h3 class="section">79.2 DESCRIPTION</h3>
-
-<p>For information on OO programming with Perl, please see <a
href="#perlootut-NAME">perlootut NAME</a>
-and <a href="#perlobj-NAME">perlobj NAME</a>.
-</p>
-<p>(The above documents supersede the tutorial that was formerly here in
-perltoot.)
-</p>
-<hr>
-<a name="perltrap"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode" accesskey="n" rel="next">perlunicode</a>,
Previous: <a href="#perltoot" accesskey="p" rel="prev">perltoot</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perltrap-1"></a>
-<h2 class="chapter">80 perltrap</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perltrap-NAME"
accesskey="1">perltrap NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltrap-DESCRIPTION"
accesskey="2">perltrap DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perltrap-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perltrap-DESCRIPTION" accesskey="n" rel="next">perltrap
DESCRIPTION</a>, Up: <a href="#perltrap" accesskey="u" rel="up">perltrap</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-79"></a>
-<h3 class="section">80.1 NAME</h3>
-
-<p>perltrap - Perl traps for the unwary
-</p>
-<hr>
-<a name="perltrap-DESCRIPTION"></a>
-<div class="header">
-<p>
-Previous: <a href="#perltrap-NAME" accesskey="p" rel="prev">perltrap NAME</a>,
Up: <a href="#perltrap" accesskey="u" rel="up">perltrap</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-78"></a>
-<h3 class="section">80.2 DESCRIPTION</h3>
-
-<p>The biggest trap of all is forgetting to <code>use warnings</code> or use
the <strong>-w</strong>
-switch; see <a href="warnings.html#Top">(warnings)</a> and <a
href="#perlrun-NAME">perlrun NAME</a>. The second biggest trap is not
-making your entire program runnable under <code>use strict</code>. The third
biggest
-trap is not reading the list of changes in this version of Perl; see
-<a href="perldelta.html#Top">(perldelta)</a>.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perltrap-Awk-Traps"
accesskey="1">perltrap Awk Traps</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perltrap-C_002fC_002b_002b-Traps" accesskey="2">perltrap C/C++
Traps</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltrap-JavaScript-Traps"
accesskey="3">perltrap JavaScript Traps</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltrap-Sed-Traps"
accesskey="4">perltrap Sed Traps</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltrap-Shell-Traps"
accesskey="5">perltrap Shell Traps</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perltrap-Perl-Traps"
accesskey="6">perltrap Perl Traps</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perltrap-Awk-Traps"></a>
-<div class="header">
-<p>
-Next: <a href="#perltrap-C_002fC_002b_002b-Traps" accesskey="n"
rel="next">perltrap C/C++ Traps</a>, Up: <a href="#perltrap-DESCRIPTION"
accesskey="u" rel="up">perltrap DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Awk-Traps"></a>
-<h4 class="subsection">80.2.1 Awk Traps</h4>
-
-<p>Accustomed <strong>awk</strong> users should take special note of the
following:
-</p>
-<ul>
-<li> A Perl program executes only once, not once for each input line. You can
-do an implicit loop with <code>-n</code> or <code>-p</code>.
-
-</li><li> The English module, loaded via
-
-<pre class="verbatim"> use English;
-</pre>
-<p>allows you to refer to special variables (like <code>$/</code>) with names
(like
-$RS), as though they were in <strong>awk</strong>; see <a
href="#perlvar-NAME">perlvar NAME</a> for details.
-</p>
-</li><li> Semicolons are required after all simple statements in Perl (except
-at the end of a block). Newline is not a statement delimiter.
-
-</li><li> Curly brackets are required on <code>if</code>s and
<code>while</code>s.
-
-</li><li> Variables begin with "$", "@" or "%"
in Perl.
-
-</li><li> Arrays index from 0. Likewise string positions in substr() and
-index().
-
-</li><li> You have to decide whether your array has numeric or string indices.
-
-</li><li> Hash values do not spring into existence upon mere reference.
-
-</li><li> You have to decide whether you want to use string or numeric
-comparisons.
-
-</li><li> Reading an input line does not split it for you. You get to split it
-to an array yourself. And the split() operator has different
-arguments than <strong>awk</strong>’s.
-
-</li><li> The current input line is normally in $_, not $0. It generally does
-not have the newline stripped. ($0 is the name of the program
-executed.) See <a href="#perlvar-NAME">perlvar NAME</a>.
-
-</li><li> $<<em>digit</em>> does not refer to fields–it refers to
substrings matched
-by the last match pattern.
-
-</li><li> The print() statement does not add field and record separators unless
-you set <code>$,</code> and <code>$\</code>. You can set $OFS and $ORS if
you’re using
-the English module.
-
-</li><li> You must open your files before you print to them.
-
-</li><li> The range operator is "..", not comma. The comma operator
works as in
-C.
-
-</li><li> The match operator is "=~", not "~".
("~" is the one’s complement
-operator, as in C.)
-
-</li><li> The exponentiation operator is "**", not "^".
"^" is the XOR
-operator, as in C. (You know, one could get the feeling that
<strong>awk</strong> is
-basically incompatible with C.)
-
-</li><li> The concatenation operator is ".", not the null string.
(Using the
-null string would render <code>/pat/ /pat/</code> unparsable, because the
third slash
-would be interpreted as a division operator–the tokenizer is in fact
-slightly context sensitive for operators like "/", "?",
and ">".
-And in fact, "." itself can be the beginning of a number.)
-
-</li><li> The <code>next</code>, <code>exit</code>, and <code>continue</code>
keywords work differently.
-
-</li><li> The following variables work differently:
-
-<pre class="verbatim"> Awk Perl
- ARGC scalar @ARGV (compare with $#ARGV)
- ARGV[0] $0
- FILENAME $ARGV
- FNR $. - something
- FS (whatever you like)
- NF $#Fld, or some such
- NR $.
- OFMT $#
- OFS $,
- ORS $\
- RLENGTH length($&)
- RS $/
- RSTART length($`)
- SUBSEP $;
-</pre>
-</li><li> You cannot set $RS to a pattern, only a string.
-
-</li><li> When in doubt, run the <strong>awk</strong> construct through
<strong>a2p</strong> and see what it
-gives you.
-
-</li></ul>
-
-<hr>
-<a name="perltrap-C_002fC_002b_002b-Traps"></a>
-<div class="header">
-<p>
-Next: <a href="#perltrap-JavaScript-Traps" accesskey="n" rel="next">perltrap
JavaScript Traps</a>, Previous: <a href="#perltrap-Awk-Traps" accesskey="p"
rel="prev">perltrap Awk Traps</a>, Up: <a href="#perltrap-DESCRIPTION"
accesskey="u" rel="up">perltrap DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="C_002fC_002b_002b-Traps"></a>
-<h4 class="subsection">80.2.2 C/C++ Traps</h4>
-
-<p>Cerebral C and C++ programmers should take note of the following:
-</p>
-<ul>
-<li> Curly brackets are required on <code>if</code>’s and
<code>while</code>’s.
-
-</li><li> You must use <code>elsif</code> rather than <code>else if</code>.
-
-</li><li> The <code>break</code> and <code>continue</code> keywords from C
become in Perl <code>last</code>
-and <code>next</code>, respectively. Unlike in C, these do <em>not</em> work
within a
-<code>do { } while</code> construct. See <a
href="#perlsyn-Loop-Control">perlsyn Loop Control</a>.
-
-</li><li> The switch statement is called <code>given/when</code> and only
available in
-perl 5.10 or newer. See <a href="#perlsyn-Switch-Statements">perlsyn Switch
Statements</a>.
-
-</li><li> Variables begin with "$", "@" or "%"
in Perl.
-
-</li><li> Comments begin with "#", not "/*" or
"//". Perl may interpret C/C++
-comments as division operators, unterminated regular expressions or
-the defined-or operator.
-
-</li><li> You can’t take the address of anything, although a similar
operator
-in Perl is the backslash, which creates a reference.
-
-</li><li> <code>ARGV</code> must be capitalized. <code>$ARGV[0]</code> is
C’s <code>argv[1]</code>, and <code>argv[0]</code>
-ends up in <code>$0</code>.
-
-</li><li> System calls such as link(), unlink(), rename(), etc. return nonzero
for
-success, not 0. (system(), however, returns zero for success.)
-
-</li><li> Signal handlers deal with signal names, not numbers. Use <code>kill
-l</code>
-to find their names on your system.
-
-</li></ul>
-
-<hr>
-<a name="perltrap-JavaScript-Traps"></a>
-<div class="header">
-<p>
-Next: <a href="#perltrap-Sed-Traps" accesskey="n" rel="next">perltrap Sed
Traps</a>, Previous: <a href="#perltrap-C_002fC_002b_002b-Traps" accesskey="p"
rel="prev">perltrap C/C++ Traps</a>, Up: <a href="#perltrap-DESCRIPTION"
accesskey="u" rel="up">perltrap DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="JavaScript-Traps"></a>
-<h4 class="subsection">80.2.3 JavaScript Traps</h4>
-
-<p>Judicious JavaScript programmers should take note of the following:
-</p>
-<ul>
-<li> In Perl, binary <code>+</code> is always addition. <code>$string1 +
$string2</code> converts
-both strings to numbers and then adds them. To concatenate two strings,
-use the <code>.</code> operator.
-
-</li><li> The <code>+</code> unary operator doesn’t do anything in Perl.
It exists to avoid
-syntactic ambiguities.
-
-</li><li> Unlike <code>for...in</code>, Perl’s <code>for</code> (also
spelled <code>foreach</code>) does not allow
-the left-hand side to be an arbitrary expression. It must be a variable:
-
-<pre class="verbatim"> for my $variable (keys %hash) {
- ...
- }
-</pre>
-<p>Furthermore, don’t forget the <code>keys</code> in there, as
-<code>foreach my $kv (%hash) {}</code> iterates over the keys and values, and
is
-generally not useful ($kv would be a key, then a value, and so on).
-</p>
-</li><li> To iterate over the indices of an array, use <code>foreach my $i (0
.. $#array)
-{}</code>. <code>foreach my $v (@array) {}</code> iterates over the values.
-
-</li><li> Perl requires braces following <code>if</code>, <code>while</code>,
<code>foreach</code>, etc.
-
-</li><li> In Perl, <code>else if</code> is spelled <code>elsif</code>.
-
-</li><li> <code>? :</code> has higher precedence than assignment. In
JavaScript, one can
-write:
-
-<pre class="verbatim"> condition ? do_something() : variable = 3
-</pre>
-<p>and the variable is only assigned if the condition is false. In Perl, you
-need parentheses:
-</p>
-<pre class="verbatim"> $condition ? do_something() : ($variable = 3);
-</pre>
-<p>Or just use <code>if</code>.
-</p>
-</li><li> Perl requires semicolons to separate statements.
-
-</li><li> Variables declared with <code>my</code> only affect code
<em>after</em> the declaration.
-You cannot write <code>$x = 1; my $x;</code> and expect the first assignment to
-affect the same variable. It will instead assign to an <code>$x</code>
declared
-previously in an outer scope, or to a global variable.
-
-<p>Note also that the variable is not visible until the following
-<em>statement</em>. This means that in <code>my $x = 1 + $x</code> the second
$x refers
-to one declared previously.
-</p>
-</li><li> <code>my</code> variables are scoped to the current block, not to
the current
-function. If you write <code>{my $x;} $x;</code>, the second <code>$x</code>
does not refer to
-the one declared inside the block.
-
-</li><li> An object’s members cannot be made accessible as variables.
The closest
-Perl equivalent to <code>with(object) { method() }</code> is <code>for</code>,
which can alias
-<code>$_</code> to the object:
-
-<pre class="verbatim"> for ($object) {
- $_->method;
- }
-</pre>
-</li><li> The object or class on which a method is called is passed as one of
the
-method’s arguments, not as a separate <code>this</code> value.
-
-</li></ul>
-
-<hr>
-<a name="perltrap-Sed-Traps"></a>
-<div class="header">
-<p>
-Next: <a href="#perltrap-Shell-Traps" accesskey="n" rel="next">perltrap Shell
Traps</a>, Previous: <a href="#perltrap-JavaScript-Traps" accesskey="p"
rel="prev">perltrap JavaScript Traps</a>, Up: <a href="#perltrap-DESCRIPTION"
accesskey="u" rel="up">perltrap DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Sed-Traps"></a>
-<h4 class="subsection">80.2.4 Sed Traps</h4>
-
-<p>Seasoned <strong>sed</strong> programmers should take note of the following:
-</p>
-<ul>
-<li> A Perl program executes only once, not once for each input line. You can
-do an implicit loop with <code>-n</code> or <code>-p</code>.
-
-</li><li> Backreferences in substitutions use "$" rather than
"\".
-
-</li><li> The pattern matching metacharacters "(", ")",
and "|" do not have backslashes
-in front.
-
-</li><li> The range operator is <code>...</code>, rather than comma.
-
-</li></ul>
-
-<hr>
-<a name="perltrap-Shell-Traps"></a>
-<div class="header">
-<p>
-Next: <a href="#perltrap-Perl-Traps" accesskey="n" rel="next">perltrap Perl
Traps</a>, Previous: <a href="#perltrap-Sed-Traps" accesskey="p"
rel="prev">perltrap Sed Traps</a>, Up: <a href="#perltrap-DESCRIPTION"
accesskey="u" rel="up">perltrap DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Shell-Traps"></a>
-<h4 class="subsection">80.2.5 Shell Traps</h4>
-
-<p>Sharp shell programmers should take note of the following:
-</p>
-<ul>
-<li> The backtick operator does variable interpolation without regard to
-the presence of single quotes in the command.
-
-</li><li> The backtick operator does no translation of the return value,
unlike <strong>csh</strong>.
-
-</li><li> Shells (especially <strong>csh</strong>) do several levels of
substitution on each
-command line. Perl does substitution in only certain constructs
-such as double quotes, backticks, angle brackets, and search patterns.
-
-</li><li> Shells interpret scripts a little bit at a time. Perl compiles the
-entire program before executing it (except for <code>BEGIN</code> blocks, which
-execute at compile time).
-
-</li><li> The arguments are available via @ARGV, not $1, $2, etc.
-
-</li><li> The environment is not automatically made available as separate
scalar
-variables.
-
-</li><li> The shell’s <code>test</code> uses "=",
"!=", "<" etc for string comparisons and "-eq",
-"-ne", "-lt" etc for numeric comparisons. This is the
reverse of Perl, which
-uses <code>eq</code>, <code>ne</code>, <code>lt</code> for string comparisons,
and <code>==</code>, <code>!=</code> <code><</code> etc
-for numeric comparisons.
-
-</li></ul>
-
-<hr>
-<a name="perltrap-Perl-Traps"></a>
-<div class="header">
-<p>
-Previous: <a href="#perltrap-Shell-Traps" accesskey="p" rel="prev">perltrap
Shell Traps</a>, Up: <a href="#perltrap-DESCRIPTION" accesskey="u"
rel="up">perltrap DESCRIPTION</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Perl-Traps"></a>
-<h4 class="subsection">80.2.6 Perl Traps</h4>
-
-<p>Practicing Perl Programmers should take note of the following:
-</p>
-<ul>
-<li> Remember that many operations behave differently in a list
-context than they do in a scalar one. See <a href="#perldata-NAME">perldata
NAME</a> for details.
-
-</li><li> Avoid barewords if you can, especially all lowercase ones.
-You can’t tell by just looking at it whether a bareword is
-a function or a string. By using quotes on strings and
-parentheses on function calls, you won’t ever get them confused.
-
-</li><li> You cannot discern from mere inspection which builtins
-are unary operators (like chop() and chdir())
-and which are list operators (like print() and unlink()).
-(Unless prototyped, user-defined subroutines can <strong>only</strong> be list
-operators, never unary ones.) See <a href="#perlop-NAME">perlop NAME</a> and
<a href="#perlsub-NAME">perlsub NAME</a>.
-
-</li><li> People have a hard time remembering that some functions
-default to $_, or @ARGV, or whatever, but that others which
-you might expect to do not.
-
-</li><li> The <FH> construct is not the name of the filehandle, it is a
readline
-operation on that handle. The data read is assigned to $_ only if the
-file read is the sole condition in a while loop:
-
-<pre class="verbatim"> while (<FH>) { }
- while (defined($_ = <FH>)) { }..
- <FH>; # data discarded!
-</pre>
-</li><li> Remember not to use <code>=</code> when you need <code>=~</code>;
-these two constructs are quite different:
-
-<pre class="verbatim"> $x = /foo/;
- $x =~ /foo/;
-</pre>
-</li><li> The <code>do {}</code> construct isn’t a real loop that you
can use
-loop control on.
-
-</li><li> Use <code>my()</code> for local variables whenever you can get away
with
-it (but see <a href="#perlform-NAME">perlform NAME</a> for where you
can’t).
-Using <code>local()</code> actually gives a local value to a global
-variable, which leaves you open to unforeseen side-effects
-of dynamic scoping.
-
-</li><li> If you localize an exported variable in a module, its exported value
will
-not change. The local name becomes an alias to a new value but the
-external name is still an alias for the original.
-
-</li></ul>
-
-<p>As always, if any of these are ever officially declared as bugs,
-they’ll be fixed and removed.
-</p>
-<hr>
-<a name="perlunicode"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq" accesskey="n" rel="next">perlunifaq</a>, Previous:
<a href="#perltrap" accesskey="p" rel="prev">perltrap</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlunicode-1"></a>
-<h2 class="chapter">81 perlunicode</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlunicode-NAME"
accesskey="1">perlunicode NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunicode-DESCRIPTION"
accesskey="2">perlunicode DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunicode-BUGS"
accesskey="3">perlunicode BUGS</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunicode-SEE-ALSO"
accesskey="4">perlunicode SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlunicode-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-DESCRIPTION" accesskey="n" rel="next">perlunicode
DESCRIPTION</a>, Up: <a href="#perlunicode" accesskey="u"
rel="up">perlunicode</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-80"></a>
-<h3 class="section">81.1 NAME</h3>
-
-<p>perlunicode - Unicode support in Perl
-</p>
-<hr>
-<a name="perlunicode-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-BUGS" accesskey="n" rel="next">perlunicode
BUGS</a>, Previous: <a href="#perlunicode-NAME" accesskey="p"
rel="prev">perlunicode NAME</a>, Up: <a href="#perlunicode" accesskey="u"
rel="up">perlunicode</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-79"></a>
-<h3 class="section">81.2 DESCRIPTION</h3>
-
-<p>If you haven’t already, before reading this document, you should
become
-familiar with both <a href="#perlunitut-NAME">perlunitut NAME</a> and <a
href="#perluniintro-NAME">perluniintro NAME</a>.
-</p>
-<p>Unicode aims to <strong>UNI</strong>-fy the en-<strong>CODE</strong>-ings
of all the world’s
-character sets into a single Standard. For quite a few of the various
-coding standards that existed when Unicode was first created, converting
-from each to Unicode essentially meant adding a constant to each code
-point in the original standard, and converting back meant just
-subtracting that same constant. For ASCII and ISO-8859-1, the constant
-is 0. For ISO-8859-5, (Cyrillic) the constant is 864; for Hebrew
-(ISO-8859-8), it’s 1488; Thai (ISO-8859-11), 3424; and so forth. This
-made it easy to do the conversions, and facilitated the adoption of
-Unicode.
-</p>
-<p>And it worked; nowadays, those legacy standards are rarely used. Most
-everyone uses Unicode.
-</p>
-<p>Unicode is a comprehensive standard. It specifies many things outside
-the scope of Perl, such as how to display sequences of characters. For
-a full discussion of all aspects of Unicode, see
-<a href="http://www.unicode.org";>http://www.unicode.org</a>.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Important-Caveats" accesskey="1">perlunicode Important
Caveats</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Byte-and-Character-Semantics" accesskey="2">perlunicode Byte
and Character Semantics</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-ASCII-Rules-versus-Unicode-Rules" accesskey="3">perlunicode
ASCII Rules versus Unicode Rules</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Extended-Grapheme-Clusters-_0028Logical-characters_0029"
accesskey="4">perlunicode Extended Grapheme Clusters (Logical
characters)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Unicode-Character-Properties" accesskey="5">perlunicode
Unicode Character Properties</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-User_002dDefined-Character-Properties"
accesskey="6">perlunicode User-Defined Character
Properties</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-User_002dDefined-Case-Mappings-_0028for-serious-hackers-only_0029"
accesskey="7">perlunicode User-Defined Case Mappings (for serious hackers
only)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Character-Encodings-for-Input-and-Output"
accesskey="8">perlunicode Character Encodings for Input and
Output</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Unicode-Regular-Expression-Support-Level"
accesskey="9">perlunicode Unicode Regular Expression Support
Level</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Unicode-Encodings">perlunicode Unicode
Encodings</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Noncharacter-code-points">perlunicode Noncharacter code
points</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Beyond-Unicode-code-points">perlunicode Beyond Unicode code
points</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Security-Implications-of-Unicode">perlunicode Security
Implications of Unicode</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Unicode-in-Perl-on-EBCDIC">perlunicode Unicode in Perl on
EBCDIC</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Locales">perlunicode
Locales</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-When-Unicode-Does-Not-Happen">perlunicode When Unicode Does
Not Happen</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-The-_0022Unicode-Bug_0022">perlunicode The "Unicode
Bug"</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Forcing-Unicode-in-Perl-_0028Or-Unforcing-Unicode-in-Perl_0029">perlunicode
Forcing Unicode in Perl (Or Unforcing Unicode in
Perl)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Using-Unicode-in-XS">perlunicode Using Unicode in
XS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Hacking-Perl-to-work-on-earlier-Unicode-versions-_0028for-very-serious-hackers-only_0029">perlunicode
Hacking Perl to work on earlier Unicode versions (for very serious hackers
only)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Porting-code-from-perl_002d5_002e6_002eX">perlunicode
Porting code from perl-5.6.X</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlunicode-Important-Caveats"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Byte-and-Character-Semantics" accesskey="n"
rel="next">perlunicode Byte and Character Semantics</a>, Up: <a
href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Important-Caveats"></a>
-<h4 class="subsection">81.2.1 Important Caveats</h4>
-
-<p>Even though some of this section may not be understandable to you on
-first reading, we think it’s important enough to highlight some of the
-gotchas before delving further, so here goes:
-</p>
-<p>Unicode support is an extensive requirement. While Perl does not
-implement the Unicode standard or the accompanying technical reports
-from cover to cover, Perl does support many Unicode features.
-</p>
-<p>Also, the use of Unicode may present security issues that aren’t
obvious.
-Read <a href="http://www.unicode.org/reports/tr36";>Unicode Security
Considerations</a>.
-</p>
-<dl compact="compact">
-<dt>Safest if you <code>use feature 'unicode_strings'</code></dt>
-<dd><a
name="perlunicode-Safest-if-you-use-feature-_0027unicode_005fstrings_0027"></a>
-<p>In order to preserve backward compatibility, Perl does not turn
-on full internal Unicode support unless the pragma
-<a
href="feature.html#The-_0027unicode_005fstrings_0027-feature">(feature)<code>use feature <span
class="nolinebreak">'unicode_strings'</span></code><!-- /@w --></a>
-is specified. (This is automatically
-selected if you <code>use 5.012</code><!-- /@w --> or higher.) Failure
to do this can
-trigger unexpected surprises. See <a
href="#perlunicode-The-_0022Unicode-Bug_0022">The "Unicode Bug"</a>
below.
-</p>
-<p>This pragma doesn’t affect I/O. Nor does it change the internal
-representation of strings, only their interpretation. There are still
-several places where Unicode isn’t fully supported, such as in
-filenames.
-</p>
-</dd>
-<dt>Input and Output Layers</dt>
-<dd><a name="perlunicode-Input-and-Output-Layers"></a>
-<p>Use the <code>:encoding(...)</code> layer to read from and write to
-filehandles using the specified encoding. (See <a
href="open.html#Top">(open)</a>.)
-</p>
-</dd>
-<dt>You should convert your non-ASCII, non-UTF-8 Perl scripts to be UTF-8.</dt>
-<dd><a
name="perlunicode-You-should-convert-your-non_002dASCII_002c-non_002dUTF_002d8-Perl-scripts-to-be-UTF_002d8_002e"></a>
-<p>See <a href="encoding.html#Top">(encoding)</a>.
-</p>
-</dd>
-<dt><code>use utf8</code> still needed to enable <a
href="#perlunicode-Unicode-Encodings">UTF-8</a> in scripts</dt>
-<dd><a
name="perlunicode-use-utf8-still-needed-to-enable-perlunicode-Unicode-Encodings-in-scripts"></a>
-<p>If your Perl script is itself encoded in <a
href="#perlunicode-Unicode-Encodings">UTF-8</a>,
-the <code>use utf8</code><!-- /@w --> pragma must be explicitly included
to enable
-recognition of that (in string or regular expression literals, or in
-identifier names). <strong>This is the only time when an explicit
<code>use utf8</code><!-- /@w --> is needed.</strong> (See <a
href="utf8.html#Top">(utf8)</a>).
-</p>
-</dd>
-<dt><code>BOM</code>-marked scripts and <a
href="#perlunicode-Unicode-Encodings">UTF-16</a> scripts autodetected</dt>
-<dd><a
name="perlunicode-BOM_002dmarked-scripts-and-perlunicode-Unicode-Encodings-scripts-autodetected"></a>
-<p>However, if a Perl script begins with the Unicode <code>BOM</code>
(UTF-16LE,
-UTF16-BE, or UTF-8), or if the script looks like non-<code>BOM</code>-marked
-UTF-16 of either endianness, Perl will correctly read in the script as
-the appropriate Unicode encoding. (<code>BOM</code>-less UTF-8 cannot be
-effectively recognized or differentiated from ISO 8859-1 or other
-eight-bit encodings.)
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlunicode-Byte-and-Character-Semantics"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-ASCII-Rules-versus-Unicode-Rules" accesskey="n"
rel="next">perlunicode ASCII Rules versus Unicode Rules</a>, Previous: <a
href="#perlunicode-Important-Caveats" accesskey="p" rel="prev">perlunicode
Important Caveats</a>, Up: <a href="#perlunicode-DESCRIPTION" accesskey="u"
rel="up">perlunicode DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Byte-and-Character-Semantics"></a>
-<h4 class="subsection">81.2.2 Byte and Character Semantics</h4>
-
-<p>Before Unicode, most encodings used 8 bits (a single byte) to encode
-each character. Thus a character was a byte, and a byte was a
-character, and there could be only 256 or fewer possible characters.
-"Byte Semantics" in the title of this section refers to
-this behavior. There was no need to distinguish between "Byte" and
-"Character".
-</p>
-<p>Then along comes Unicode which has room for over a million characters
-(and Perl allows for even more). This means that a character may
-require more than a single byte to represent it, and so the two terms
-are no longer equivalent. What matter are the characters as whole
-entities, and not usually the bytes that comprise them. That’s what the
-term "Character Semantics" in the title of this section refers to.
-</p>
-<p>Perl had to change internally to decouple "bytes" from
"characters".
-It is important that you too change your ideas, if you haven’t already,
-so that "byte" and "character" no longer mean the same
thing in your
-mind.
-</p>
-<p>The basic building block of Perl strings has always been a
"character".
-The changes basically come down to that the implementation no longer
-thinks that a character is always just a single byte.
-</p>
-<p>There are various things to note:
-</p>
-<ul>
-<li> String handling functions, for the most part, continue to operate in
-terms of characters. <code>length()</code>, for example, returns the number of
-characters in a string, just as before. But that number no longer is
-necessarily the same as the number of bytes in the string (there may be
-more bytes than characters). The other such functions include
-<code>chop()</code>, <code>chomp()</code>, <code>substr()</code>,
<code>pos()</code>, <code>index()</code>, <code>rindex()</code>,
-<code>sort()</code>, <code>sprintf()</code>, and <code>write()</code>.
-
-<p>The exceptions are:
-</p>
-<ul>
-<li> the bit-oriented <code>vec</code>
-
-<p>ÃÂ
-</p>
-</li><li> the byte-oriented <code>pack</code>/<code>unpack</code>
<code>"C"</code> format
-
-<p>However, the <code>W</code> specifier does operate on whole characters, as
does the
-<code>U</code> specifier.
-</p>
-</li><li> some operators that interact with the platform’s operating
system
-
-<p>Operators dealing with filenames are examples.
-</p>
-</li><li> when the functions are called from within the scope of the
-<code><a href="bytes.html#Top">(bytes)use bytes</a></code><!-- /@w -->
pragma
-
-<p>Likely, you should use this only for debugging anyway.
-</p>
-</li></ul>
-
-</li><li> Strings–including hash keys–and regular expression
patterns may
-contain characters that have ordinal values larger than 255.
-
-<p>If you use a Unicode editor to edit your program, Unicode characters may
-occur directly within the literal strings in UTF-8 encoding, or UTF-16.
-(The former requires a <code>BOM</code> or <code>use utf8</code>, the latter
requires a <code>BOM</code>.)
-</p>
-<p><a href="#perluniintro-Creating-Unicode">perluniintro Creating Unicode</a>
gives other ways to place non-ASCII
-characters in your strings.
-</p>
-</li><li> The <code>chr()</code> and <code>ord()</code> functions work on
whole characters.
-
-</li><li> Regular expressions match whole characters. For example,
<code>"."</code> matches
-a whole character instead of only a single byte.
-
-</li><li> The <code>tr///</code> operator translates whole characters. (Note
that the
-<code>tr///CU</code> functionality has been removed. For similar
functionality to
-that, see <code>pack('U0', ...)</code> and <code>pack('C0', ...)</code>).
-
-</li><li> <code>scalar reverse()</code> reverses by character rather than by
byte.
-
-</li><li> The bit string operators, <code>& | ^ ~</code> and (starting in
v5.22)
-<code>&. |. ^. ~.</code> can operate on characters that don’t fit
into a byte.
-However, the current behavior is likely to change. You should not use
-these operators on strings that are encoded in UTF-8. If you’re not
-sure about the encoding of a string, downgrade it before using any of
-these operators; you can use
-<a
href="utf8.html#Utility-functions">(utf8)<code>utf8::utf8_downgrade()</code></a>.
-
-</li></ul>
-
-<p>The bottom line is that Perl has always practiced "Character
Semantics",
-but with the advent of Unicode, that is now different than "Byte
-Semantics".
-</p>
-<hr>
-<a name="perlunicode-ASCII-Rules-versus-Unicode-Rules"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunicode-Extended-Grapheme-Clusters-_0028Logical-characters_0029"
accesskey="n" rel="next">perlunicode Extended Grapheme Clusters (Logical
characters)</a>, Previous: <a href="#perlunicode-Byte-and-Character-Semantics"
accesskey="p" rel="prev">perlunicode Byte and Character Semantics</a>, Up: <a
href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="ASCII-Rules-versus-Unicode-Rules"></a>
-<h4 class="subsection">81.2.3 ASCII Rules versus Unicode Rules</h4>
-
-<p>Before Unicode, when a character was a byte was a character,
-Perl knew only about the 128 characters defined by ASCII, code points 0
-through 127 (except for under <code>use locale</code><!-- /@w -->). That
left the code
-points 128 to 255 as unassigned, and available for whatever use a
-program might want. The only semantics they have is their ordinal
-numbers, and that they are members of none of the non-negative character
-classes. None are considered to match <code>\w</code> for example, but all
match
-<code>\W</code>.
-</p>
-<p>Unicode, of course, assigns each of those code points a particular
-meaning (along with ones above 255). To preserve backward
-compatibility, Perl only uses the Unicode meanings when there is some
-indication that Unicode is what is intended; otherwise the non-ASCII
-code points remain treated as if they are unassigned.
-</p>
-<p>Here are the ways that Perl knows that a string should be treated as
-Unicode:
-</p>
-<ul>
-<li> Within the scope of <code>use utf8</code><!-- /@w -->
-
-<p>If the whole program is Unicode (signified by using 8-bit
<strong>U</strong>nicode
-<strong>T</strong>ransformation <strong>F</strong>ormat), then all strings
within it must be
-Unicode.
-</p>
-</li><li> Within the scope of
-<a
href="feature.html#The-_0027unicode_005fstrings_0027-feature">(feature)<code>use feature <span
class="nolinebreak">'unicode_strings'</span></code><!-- /@w --></a>
-
-<p>This pragma was created so you can explicitly tell Perl that operations
-executed within its scope are to use Unicode rules. More operations are
-affected with newer perls. See <a
href="#perlunicode-The-_0022Unicode-Bug_0022">The "Unicode Bug"</a>.
-</p>
-</li><li> Within the scope of <code>use 5.012</code><!-- /@w --> or higher
-
-<p>This implicitly turns on <code>use feature <span
class="nolinebreak">'unicode_strings'</span></code><!-- /@w -->.
-</p>
-</li><li> Within the scope of
-<a href="#perllocale-Unicode-and-UTF_002d8"><code>use locale <span
class="nolinebreak">'not_characters'</span></code><!-- /@w --></a>,
-or <a href="#perllocale-NAME"><code>use locale</code><!-- /@w --></a> and
the current
-locale is a UTF-8 locale.
-
-<p>The former is defined to imply Unicode handling; and the latter
-indicates a Unicode locale, hence a Unicode interpretation of all
-strings within it.
-</p>
-</li><li> When the string contains a Unicode-only code point
-
-<p>Perl has never accepted code points above 255 without them being
-Unicode, so their use implies Unicode for the whole string.
-</p>
-</li><li> When the string contains a Unicode named code point
<code>\N{...}</code>
-
-<p>The <code>\N{...}</code> construct explicitly refers to a Unicode code
point,
-even if it is one that is also in ASCII. Therefore the string
-containing it must be Unicode.
-</p>
-</li><li> When the string has come from an external source marked as
-Unicode
-
-<p>The <a href="#perlrun-_002dC-_005bnumber_002flist_005d"><code>-C</code></a>
command line option can
-specify that certain inputs to the program are Unicode, and the values
-of this can be read by your Perl code, see <a
href="#perlvar-_0024_007b_005eUNICODE_007d">perlvar ${^UNICODE}</a>.
-</p>
-</li><li> When the string has been upgraded to UTF-8
-
-<p>The function <a
href="utf8.html#Utility-functions">(utf8)<code>utf8::utf8_upgrade()</code></a>
-can be explicitly used to permanently (unless a subsequent
-<code>utf8::utf8_downgrade()</code> is called) cause a string to be treated as
-Unicode.
-</p>
-</li><li> There are additional methods for regular expression patterns
-
-<p>A pattern that is compiled with the <code>/u</code> or <code>/a</code>
modifiers is
-treated as Unicode (though there are some restrictions with <code>/a</code>).
-Under the <code>/d</code> and <code>/l</code> modifiers, there are several
other
-indications for Unicode; see <a href="#perlre-Character-set-modifiers">perlre
Character set modifiers</a>.
-</p>
-</li></ul>
-
-<p>Note that all of the above are overridden within the scope of
-<code><a href="bytes.html#Top">(bytes)use bytes</a></code>; but you should be
using this pragma only for
-debugging.
-</p>
-<p>Note also that some interactions with the platform’s operating system
-never use Unicode rules.
-</p>
-<p>When Unicode rules are in effect:
-</p>
-<ul>
-<li> Case translation operators use the Unicode case translation tables.
-
-<p>Note that <code>uc()</code>, or <code>\U</code> in interpolated strings,
translates to
-uppercase, while <code>ucfirst</code>, or <code>\u</code> in interpolated
strings,
-translates to titlecase in languages that make the distinction (which is
-equivalent to uppercase in languages without the distinction).
-</p>
-<p>There is a CPAN module, <code><a
href="Unicode-Casing.html#Top">(Unicode-Casing)</a></code>, which allows you to
-define your own mappings to be used in <code>lc()</code>,
<code>lcfirst()</code>, <code>uc()</code>,
-<code>ucfirst()</code>, and <code>fc</code> (or their double-quoted string
inlined versions
-such as <code>\U</code>). (Prior to Perl 5.16, this functionality was
partially
-provided in the Perl core, but suffered from a number of insurmountable
-drawbacks, so the CPAN module was written instead.)
-</p>
-</li><li> Character classes in regular expressions match based on the character
-properties specified in the Unicode properties database.
-
-<p><code>\w</code> can be used to match a Japanese ideograph, for instance; and
-<code>[[:digit:]]</code> a Bengali number.
-</p>
-</li><li> Named Unicode properties, scripts, and block ranges may be used (like
-bracketed character classes) by using the <code>\p{}</code> "matches
property"
-construct and the <code>\P{}</code> negation, "doesn’t match
property".
-
-<p>See <a href="#perlunicode-Unicode-Character-Properties">Unicode Character
Properties</a> for more details.
-</p>
-<p>You can define your own character properties and use them
-in the regular expression with the <code>\p{}</code> or <code>\P{}</code>
construct.
-See <a href="#perlunicode-User_002dDefined-Character-Properties">User-Defined
Character Properties</a> for more details.
-</p>
-</li></ul>
-
-<hr>
-<a
name="perlunicode-Extended-Grapheme-Clusters-_0028Logical-characters_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Unicode-Character-Properties" accesskey="n"
rel="next">perlunicode Unicode Character Properties</a>, Previous: <a
href="#perlunicode-ASCII-Rules-versus-Unicode-Rules" accesskey="p"
rel="prev">perlunicode ASCII Rules versus Unicode Rules</a>, Up: <a
href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Extended-Grapheme-Clusters-_0028Logical-characters_0029"></a>
-<h4 class="subsection">81.2.4 Extended Grapheme Clusters (Logical
characters)</h4>
-
-<p>Consider a character, say <code>H</code>. It could appear with various
marks around it,
-such as an acute accent, or a circumflex, or various hooks, circles, arrows,
-<em>etc.</em>, above, below, to one side or the other, <em>etc</em>. 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 <code>H</code>,
and a
-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.
-The Unicode standard calls these "extended grapheme clusters" (which
-is an improved version of the no-longer much used "grapheme
cluster");
-Perl furnishes the <code>\X</code> regular expression construct to match such
-sequences in their entirety.
-</p>
-<p>But Unicode’s intent is to unify the existing character set standards
and
-practices, and several pre-existing standards have single characters that
-mean the same thing as some of these combinations, like ISO-8859-1,
-which has quite a few of them. For example, <code>"LATIN CAPITAL LETTER E
-WITH ACUTE"</code> was already in this standard when Unicode came along.
-Unicode therefore added it to its repertoire as that single character.
-But this character is considered by Unicode to be equivalent to the
-sequence consisting of the character <code>"LATIN CAPITAL LETTER
E"</code>
-followed by the character <code>"COMBINING ACUTE ACCENT"</code>.
-</p>
-<p><code>"LATIN CAPITAL LETTER E WITH ACUTE"</code> is called a
"pre-composed"
-character, and its equivalence with the "E" and the "COMBINING
ACCENT"
-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. A string may be comprised
-as much as possible of precomposed characters, or it may be comprised of
-entirely decomposed characters. Unicode calls these respectively,
-"Normalization Form Composed" (NFC) and "Normalization Form
Decomposed".
-The <code><a href="Unicode-Normalize.html#Top">(Unicode-Normalize)</a></code>
module contains functions that convert
-between the two. A string may also have both composed characters and
-decomposed characters; this module can be used to make it all one or the
-other.
-</p>
-<p>You may be presented with strings in any of these equivalent forms.
-There is currently nothing in Perl 5 that ignores the differences. So
-you’ll have to specially hanlde it. The usual advice is to convert your
-inputs to <code>NFD</code> before processing further.
-</p>
-<p>For more detailed information, see <a
href="http://unicode.org/reports/tr15/";>http://unicode.org/reports/tr15/</a>.
-</p>
-<hr>
-<a name="perlunicode-Unicode-Character-Properties"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-User_002dDefined-Character-Properties"
accesskey="n" rel="next">perlunicode User-Defined Character Properties</a>,
Previous: <a
href="#perlunicode-Extended-Grapheme-Clusters-_0028Logical-characters_0029"
accesskey="p" rel="prev">perlunicode Extended Grapheme Clusters (Logical
characters)</a>, Up: <a href="#perlunicode-DESCRIPTION" accesskey="u"
rel="up">perlunicode DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-Character-Properties"></a>
-<h4 class="subsection">81.2.5 Unicode Character Properties</h4>
-
-<p>(The only time that Perl considers a sequence of individual code
-points as a single logical character is in the <code>\X</code> construct,
already
-mentioned above. Therefore "character" in this discussion means a
single
-Unicode code point.)
-</p>
-<p>Very nearly all Unicode character properties are accessible through
-regular expressions by using the <code>\p{}</code> "matches
property" construct
-and the <code>\P{}</code> "doesn’t match property" for its
negation.
-</p>
-<p>For instance, <code>\p{Uppercase}</code> matches any single character with
the Unicode
-<code>"Uppercase"</code> property, while <code>\p{L}</code> matches
any character with a
-<code>General_Category</code> of <code>"L"</code> (letter) property
(see
-<a href="#perlunicode-General_005fCategory">General_Category</a> below).
Brackets are not
-required for single letter property names, so <code>\p{L}</code> is equivalent
to <code>\pL</code>.
-</p>
-<p>More formally, <code>\p{Uppercase}</code> matches any single character
whose Unicode
-<code>Uppercase</code> property value is <code>True</code>, and
<code>\P{Uppercase}</code> matches any character
-whose <code>Uppercase</code> property value is <code>False</code>, and they
could have been written as
-<code>\p{Uppercase=True}</code> and <code>\p{Uppercase=False}</code>,
respectively.
-</p>
-<p>This formality is needed when properties are not binary; that is, if they
can
-take on more values than just <code>True</code> and <code>False</code>. For
example, the
-<code>Bidi_Class</code> property (see <a
href="#perlunicode-Bidirectional-Character-Types">Bidirectional Character
Types</a> below),
-can take on several different
-values, such as <code>Left</code>, <code>Right</code>,
<code>Whitespace</code>, and others. To match these, one needs
-to specify both the property name (<code>Bidi_Class</code>), AND the value
being
-matched against
-(<code>Left</code>, <code>Right</code>, <em>etc.</em>). This is done, as in
the examples above, by having the
-two components separated by an equal sign (or interchangeably, a colon), like
-<code>\p{Bidi_Class: Left}</code>.
-</p>
-<p>All Unicode-defined character properties may be written in these compound
forms
-of <code>\p{<em>property</em>=<em>value</em>}</code> or
<code>\p{<em>property</em>:<em>value</em>}</code>, but Perl provides some
-additional properties that are written only in the single form, as well as
-single-form short-cuts for all binary properties and certain others described
-below, in which you may omit the property name and the equals or colon
-separator.
-</p>
-<p>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 that is more
-descriptive and hence easier to understand. Thus the
<code>"L"</code> and
-<code>"Letter"</code> properties above are equivalent and can be used
-interchangeably. Likewise, <code>"Upper"</code> is a synonym for
<code>"Uppercase"</code>,
-and we could have written <code>\p{Uppercase}</code> equivalently as
<code>\p{Upper}</code>.
-Also, there are typically various synonyms for the values the property
-can be. For binary properties, <code>"True"</code> has 3 synonyms:
<code>"T"</code>,
-<code>"Yes"</code>, and <code>"Y"</code>; and
<code>"False"</code> has correspondingly <code>"F"</code>,
-<code>"No"</code>, and <code>"N"</code>. But be careful.
A short form of a value for one
-property may not mean the same thing as the same short form for another.
-Thus, for the <code><a
href="#perlunicode-General_005fCategory">General_Category</a></code> property,
<code>"L"</code> means
-<code>"Letter"</code>, but for the <a
href="#perlunicode-Bidirectional-Character-Types"><code>Bidi_Class</code></a>
-property, <code>"L"</code> means <code>"Left"</code>. A
complete list of properties and
-synonyms is in <a href="perluniprops.html#Top">(perluniprops)</a>.
-</p>
-<p>Upper/lower case differences in property names and values are irrelevant;
-thus <code>\p{Upper}</code> means the same thing as <code>\p{upper}</code> or
even <code>\p{UpPeR}</code>.
-Similarly, you can add or subtract underscores anywhere in the middle of a
-word, so that these are also equivalent to <code>\p{U_p_p_e_r}</code>. And
white space
-is irrelevant adjacent to non-word characters, such as the braces and the
equals
-or colon separators, so <code>\p{ Upper }</code> and <code>\p{ Upper_case :
Y }</code> are
-equivalent to these as well. In fact, white space and even
-hyphens can usually be added or deleted anywhere. So even <code>\p{ Up-per
case = Yes}</code> is
-equivalent. All this is called "loose-matching" by Unicode. The
few places
-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 non-word characters),
-hyphens, and non-interior underscores.
-</p>
-<p>You can also use negation in both <code>\p{}</code> and <code>\P{}</code>
by introducing a caret
-(<code>^</code>) between the first brace and the property name:
<code>\p{^Tamil}</code> is
-equal to <code>\P{Tamil}</code>.
-</p>
-<p>Almost all properties are immune to case-insensitive matching. That is,
-adding a <code>/i</code> regular expression modifier does not change what they
-match. There are two sets that are affected.
-The first set is
-<code>Uppercase_Letter</code>,
-<code>Lowercase_Letter</code>,
-and <code>Titlecase_Letter</code>,
-all of which match <code>Cased_Letter</code> under <code>/i</code> matching.
-And the second set is
-<code>Uppercase</code>,
-<code>Lowercase</code>,
-and <code>Titlecase</code>,
-all of which match <code>Cased</code> under <code>/i</code> matching.
-This set also includes its subsets <code>PosixUpper</code> and
<code>PosixLower</code> both
-of which under <code>/i</code> match <code>PosixAlpha</code>.
-(The difference between these sets is that some things, such as Roman
-numerals, come in both upper and lower case so they are <code>Cased</code>, but
-aren’t considered letters, so they aren’t
<code>Cased_Letter</code>’s.)
-</p>
-<p>See <a href="#perlunicode-Beyond-Unicode-code-points">Beyond Unicode code
points</a> for special considerations when
-matching Unicode properties against non-Unicode code points.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlunicode-General_005fCategory" accesskey="1">perlunicode
<strong>General_Category</strong></a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Bidirectional-Character-Types" accesskey="2">perlunicode
<strong>Bidirectional Character
Types</strong></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunicode-Scripts"
accesskey="3">perlunicode
<strong>Scripts</strong></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Use-of-the-_0022Is_0022-Prefix" accesskey="4">perlunicode
<strong>Use of the <code>"Is"</code>
Prefix</strong></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunicode-Blocks"
accesskey="5">perlunicode
<strong>Blocks</strong></a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Other-Properties" accesskey="6">perlunicode <strong>Other
Properties</strong></a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlunicode-General_005fCategory"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Bidirectional-Character-Types" accesskey="n"
rel="next">perlunicode <strong>Bidirectional Character Types</strong></a>, Up:
<a href="#perlunicode-Unicode-Character-Properties" accesskey="u"
rel="up">perlunicode Unicode Character Properties</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="General_005fCategory"></a>
-<h4 class="subsubsection">81.2.5.1 <strong>General_Category</strong></h4>
-
-<p>Every Unicode character is assigned a general category, which is the
"most
-usual categorization of a character" (from
-<a
href="http://www.unicode.org/reports/tr44";>http://www.unicode.org/reports/tr44</a>).
-</p>
-<p>The compound way of writing these is like
<code>\p{General_Category=Number}</code>
-(short: <code>\p{gc:n}</code>). But Perl furnishes shortcuts in which
everything up
-through the equal or colon separator is omitted. So you can instead just write
-<code>\pN</code>.
-</p>
-<p>Here are the short and long forms of the values the <code>General
Category</code> property
-can have:
-</p>
-<pre class="verbatim"> Short Long
-
- L Letter
- LC, L& Cased_Letter (that is: [\p{Ll}\p{Lu}\p{Lt}])
- Lu Uppercase_Letter
- Ll Lowercase_Letter
- Lt Titlecase_Letter
- Lm Modifier_Letter
- Lo Other_Letter
-
- M Mark
- Mn Nonspacing_Mark
- Mc Spacing_Mark
- Me Enclosing_Mark
-
- N Number
- Nd Decimal_Number (also Digit)
- Nl Letter_Number
- No Other_Number
-
- P Punctuation (also Punct)
- Pc Connector_Punctuation
- Pd Dash_Punctuation
- Ps Open_Punctuation
- Pe Close_Punctuation
- Pi Initial_Punctuation
- (may behave like Ps or Pe depending on usage)
- Pf Final_Punctuation
- (may behave like Ps or Pe depending on usage)
- Po Other_Punctuation
-
- S Symbol
- Sm Math_Symbol
- Sc Currency_Symbol
- Sk Modifier_Symbol
- So Other_Symbol
-
- Z Separator
- Zs Space_Separator
- Zl Line_Separator
- Zp Paragraph_Separator
-
- C Other
- Cc Control (also Cntrl)
- Cf Format
- Cs Surrogate
- Co Private_Use
- Cn Unassigned
-</pre>
-<p>Single-letter properties match all characters in any of the
-two-letter sub-properties starting with the same letter.
-<code>LC</code> and <code>L&</code> are special: both are aliases for the
set consisting of everything matched by <code>Ll</code>, <code>Lu</code>, and
<code>Lt</code>.
-</p>
-<hr>
-<a name="perlunicode-Bidirectional-Character-Types"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Scripts" accesskey="n" rel="next">perlunicode
<strong>Scripts</strong></a>, Previous: <a
href="#perlunicode-General_005fCategory" accesskey="p" rel="prev">perlunicode
<strong>General_Category</strong></a>, Up: <a
href="#perlunicode-Unicode-Character-Properties" accesskey="u"
rel="up">perlunicode Unicode Character Properties</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Bidirectional-Character-Types"></a>
-<h4 class="subsubsection">81.2.5.2 <strong>Bidirectional Character
Types</strong></h4>
-
-<p>Because scripts differ in their directionality (Hebrew and Arabic are
-written right to left, for example) Unicode supplies a <code>Bidi_Class</code>
property.
-Some of the values this property can have are:
-</p>
-<pre class="verbatim"> Value Meaning
-
- L Left-to-Right
- LRE Left-to-Right Embedding
- LRO Left-to-Right Override
- R Right-to-Left
- AL Arabic Letter
- RLE Right-to-Left Embedding
- RLO Right-to-Left Override
- PDF Pop Directional Format
- EN European Number
- ES European Separator
- ET European Terminator
- AN Arabic Number
- CS Common Separator
- NSM Non-Spacing Mark
- BN Boundary Neutral
- B Paragraph Separator
- S Segment Separator
- WS Whitespace
- ON Other Neutrals
-</pre>
-<p>This property is always written in the compound form.
-For example, <code>\p{Bidi_Class:R}</code> matches characters that are normally
-written right to left. Unlike the
-<code><a href="#perlunicode-General_005fCategory">General_Category</a></code>
property, this
-property can have more values added in a future Unicode release. Those
-listed above comprised the complete set for many Unicode releases, but
-others were added in Unicode 6.3; you can always find what the
-current ones are in in <a href="perluniprops.html#Top">(perluniprops)</a>. And
-<a
href="http://www.unicode.org/reports/tr9/";>http://www.unicode.org/reports/tr9/</a>
describes how to use them.
-</p>
-<hr>
-<a name="perlunicode-Scripts"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Use-of-the-_0022Is_0022-Prefix" accesskey="n"
rel="next">perlunicode <strong>Use of the <code>"Is"</code>
Prefix</strong></a>, Previous: <a
href="#perlunicode-Bidirectional-Character-Types" accesskey="p"
rel="prev">perlunicode <strong>Bidirectional Character Types</strong></a>, Up:
<a href="#perlunicode-Unicode-Character-Properties" accesskey="u"
rel="up">perlunicode Unicode Character Properties</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Scripts"></a>
-<h4 class="subsubsection">81.2.5.3 <strong>Scripts</strong></h4>
-
-<p>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 Cyrillic, and Greek is written in, well, Greek; Japanese mainly in
-Hiragana or Katakana. There are many more.
-</p>
-<p>The Unicode <code>Script</code> and <code>Script_Extensions</code>
properties give what script a
-given character is in. Either property can be specified with the
-compound form like
-<code>\p{Script=Hebrew}</code> (short: <code>\p{sc=hebr}</code>), or
-<code>\p{Script_Extensions=Javanese}</code> (short: <code>\p{scx=java}</code>).
-In addition, Perl furnishes shortcuts for all
-<code>Script</code> property names. You can omit everything up through the
equals
-(or colon), and simply write <code>\p{Latin}</code> or
<code>\P{Cyrillic}</code>.
-(This is not true for <code>Script_Extensions</code>, which is required to be
-written in the compound form.)
-</p>
-<p>The difference between these two properties involves characters that are
-used in multiple scripts. For example the digits ’0’ through
’9’ are
-used in many parts of the world. These are placed in a script named
-<code>Common</code>. Other characters are used in just a few scripts. For
-example, the <code>"KATAKANA-HIRAGANA DOUBLE HYPHEN"</code> is used
in both Japanese
-scripts, Katakana and Hiragana, but nowhere else. The <code>Script</code>
-property places all characters that are used in multiple scripts in the
-<code>Common</code> script, while the <code>Script_Extensions</code> property
places those
-that are used in only a few scripts into each of those scripts; while
-still using <code>Common</code> for those used in many scripts. Thus both
these
-match:
-</p>
-<pre class="verbatim"> "0" =~ /\p{sc=Common}/ # Matches
- "0" =~ /\p{scx=Common}/ # Matches
-</pre>
-<p>and only the first of these match:
-</p>
-<pre class="verbatim"> "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~
/\p{sc=Common} # Matches
- "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{scx=Common} # No match
-</pre>
-<p>And only the last two of these match:
-</p>
-<pre class="verbatim"> "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~
/\p{sc=Hiragana} # No match
- "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{sc=Katakana} # No
match
- "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{scx=Hiragana} # Matches
- "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{scx=Katakana} # Matches
-</pre>
-<p><code>Script_Extensions</code> is thus an improved <code>Script</code>, in
which there are
-fewer characters in the <code>Common</code> script, and correspondingly more in
-other scripts. It is new in Unicode version 6.0, and its data are likely
-to change significantly in later releases, as things get sorted out.
-New code should probably be using <code>Script_Extensions</code> and not plain
-<code>Script</code>.
-</p>
-<p>(Actually, besides <code>Common</code>, the <code>Inherited</code> script,
contains
-characters that are used in multiple scripts. These are modifier
-characters which inherit the script value
-of the controlling character. Some of these are used in many scripts,
-and so go into <code>Inherited</code> in both <code>Script</code> and
<code>Script_Extensions</code>.
-Others are used in just a few scripts, so are in <code>Inherited</code> in
-<code>Script</code>, but not in <code>Script_Extensions</code>.)
-</p>
-<p>It is worth stressing that there are several different sets of digits in
-Unicode that are equivalent to 0-9 and are matchable by <code>\d</code> in a
-regular expression. If they are used in a single language only, they
-are in that language’s <code>Script</code> and
<code>Script_Extension</code>. If they are
-used in more than one script, they will be in <code>sc=Common</code>, but only
-if they are used in many scripts should they be in <code>scx=Common</code>.
-</p>
-<p>A complete list of scripts and their shortcuts is in <a
href="perluniprops.html#Top">(perluniprops)</a>.
-</p>
-<hr>
-<a name="perlunicode-Use-of-the-_0022Is_0022-Prefix"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Blocks" accesskey="n" rel="next">perlunicode
<strong>Blocks</strong></a>, Previous: <a href="#perlunicode-Scripts"
accesskey="p" rel="prev">perlunicode <strong>Scripts</strong></a>, Up: <a
href="#perlunicode-Unicode-Character-Properties" accesskey="u"
rel="up">perlunicode Unicode Character Properties</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Use-of-the-_0022Is_0022-Prefix"></a>
-<h4 class="subsubsection">81.2.5.4 <strong>Use of the
<code>"Is"</code> Prefix</strong></h4>
-
-<p>For backward compatibility (with Perl 5.6), all properties writable
-without using the compound form mentioned
-so far may have <code>Is</code> or <code>Is_</code> prepended to their name,
so <code>\P{Is_Lu}</code>, for
-example, is equal to <code>\P{Lu}</code>, and <code>\p{IsScript:Arabic}</code>
is equal to
-<code>\p{Arabic}</code>.
-</p>
-<hr>
-<a name="perlunicode-Blocks"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Other-Properties" accesskey="n"
rel="next">perlunicode <strong>Other Properties</strong></a>, Previous: <a
href="#perlunicode-Use-of-the-_0022Is_0022-Prefix" accesskey="p"
rel="prev">perlunicode <strong>Use of the <code>"Is"</code>
Prefix</strong></a>, Up: <a href="#perlunicode-Unicode-Character-Properties"
accesskey="u" rel="up">perlunicode Unicode Character Properties</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Blocks"></a>
-<h4 class="subsubsection">81.2.5.5 <strong>Blocks</strong></h4>
-
-<p>In addition to <strong>scripts</strong>, Unicode also defines
<strong>blocks</strong> of
-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 <code>"Basic
Latin"</code>
-block is all the characters whose ordinals are between 0 and 127, inclusive; in
-other words, the ASCII characters. The <code>"Latin"</code> script
contains some letters
-from this as well as several other blocks, like <code>"Latin-1
Supplement"</code>,
-<code>"Latin Extended-A"</code>, <em>etc.</em>, but it does not
contain all the characters from
-those blocks. It does not, for example, contain the digits 0-9, because
-those digits are shared across many scripts, and hence are in the
-<code>Common</code> script.
-</p>
-<p>For more about scripts versus blocks, see UAX#24 "Unicode Script
Property":
-<a
href="http://www.unicode.org/reports/tr24";>http://www.unicode.org/reports/tr24</a>
-</p>
-<p>The <code>Script</code> or <code>Script_Extensions</code> properties are
likely to be the
-ones you want to use when processing
-natural language; the <code>Block</code> property may occasionally be useful
in working
-with the nuts and bolts of Unicode.
-</p>
-<p>Block names are matched in the compound form, like <code>\p{Block:
Arrows}</code> or
-<code>\p{Blk=Hebrew}</code>. Unlike most other properties, only a few block
names have a
-Unicode-defined short name. But Perl does provide a (slight, no longer
-recommended) shortcut: You can say, for example <code>\p{In_Arrows}</code> or
-<code>\p{In_Hebrew}</code>.
-</p>
-<p>For backwards compatibility, the <code>In</code> prefix may be
-omitted if there is no naming conflict with a script or any other
-property, and you can even use an <code>Is</code> prefix instead in those
cases.
-But don’t do this for new code because your code could break in new
-releases, and this has already happened: There was a time in very
-early Unicode releases when <code>\p{Hebrew}</code> would have matched the
-<em>block</em> Hebrew; now it doesn’t.
-</p>
-<p>Using the <code>In</code> prefix avoids this ambiguity, so far. But new
versions
-of Unicode continue to add new properties whose names begin with
<code>In</code>.
-There is a possibility that one of them someday will conflict with your
-usage. Since this is just a Perl extension, Unicode’s name will take
-precedence and your code will become broken. Also, Unicode is free to
-add a script whose name begins with <code>In</code>; that would cause problems.
-</p>
-<p>So it’s clearer and best to use the compound form when specifying
-blocks. And be sure that is what you really really want to do. In most
-cases scripts are what you want instead.
-</p>
-<p>A complete list of blocks and their shortcuts is in <a
href="perluniprops.html#Top">(perluniprops)</a>.
-</p>
-<hr>
-<a name="perlunicode-Other-Properties"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlunicode-Blocks" accesskey="p" rel="prev">perlunicode
<strong>Blocks</strong></a>, Up: <a
href="#perlunicode-Unicode-Character-Properties" accesskey="u"
rel="up">perlunicode Unicode Character Properties</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Other-Properties"></a>
-<h4 class="subsubsection">81.2.5.6 <strong>Other Properties</strong></h4>
-
-<p>There are many more properties than the very basic ones described here.
-A complete list is in <a href="perluniprops.html#Top">(perluniprops)</a>.
-</p>
-<p>Unicode defines all its properties in the compound form, so all single-form
-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 <a
href="http://www.unicode.org/reports/tr18";>http://www.unicode.org/reports/tr18</a>).
-</p>
-<p>This section gives some details on all extensions that aren’t just
-synonyms for compound-form Unicode properties
-(for those properties, you’ll have to refer to the
-<a href="http://www.unicode.org/reports/tr44";>Unicode Standard</a>.
-</p>
-<dl compact="compact">
-<dt><strong><code>\p{All}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bAll_007d"></a>
-<p>This matches every possible code point. It is equivalent to
<code>qr/./s</code>.
-Unlike all the other non-user-defined <code>\p{}</code> property matches, no
-warning is ever generated if this is property is matched against a
-non-Unicode code point (see <a
href="#perlunicode-Beyond-Unicode-code-points">Beyond Unicode code points</a>
below).
-</p>
-</dd>
-<dt><strong><code>\p{Alnum}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bAlnum_007d"></a>
-<p>This matches any <code>\p{Alphabetic}</code> or
<code>\p{Decimal_Number}</code> character.
-</p>
-</dd>
-<dt><strong><code>\p{Any}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bAny_007d"></a>
-<p>This matches any of the 1_114_112 Unicode code points. It is a synonym
-for <code>\p{Unicode}</code>.
-</p>
-</dd>
-<dt><strong><code>\p{ASCII}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bASCII_007d"></a>
-<p>This matches any of the 128 characters in the US-ASCII character set,
-which is a subset of Unicode.
-</p>
-</dd>
-<dt><strong><code>\p{Assigned}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bAssigned_007d"></a>
-<p>This matches any assigned code point; that is, any code point whose <a
href="#perlunicode-General_005fCategory">general
-category</a> is not <code>Unassigned</code> (or equivalently, not
<code>Cn</code>).
-</p>
-</dd>
-<dt><strong><code>\p{Blank}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bBlank_007d"></a>
-<p>This is the same as <code>\h</code> and <code>\p{HorizSpace}</code>: A
character that changes the
-spacing horizontally.
-</p>
-</dd>
-<dt><strong><code>\p{Decomposition_Type: Non_Canonical}</code></strong>
(Short: <code>\p{Dt=NonCanon}</code>)</dt>
-<dd><a
name="perlunicode-_005cp_007bDecomposition_005fType_003a-Non_005fCanonical_007d-_0028Short_003a-_005cp_007bDt_003dNonCanon_007d_0029"></a>
-<p>Matches a character that has a non-canonical decomposition.
-</p>
-<p>The <a
href="#perlunicode-Extended-Grapheme-Clusters-_0028Logical-characters_0029">Extended
Grapheme Clusters (Logical characters)</a> section above
-talked about canonical decompositions. 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 is the <code>"SUPERSCRIPT
ONE"</code>. 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 <a
href="http://www.unicode.org/reports/tr44";>http://www.unicode.org/reports/tr44</a>),
including
-one called "compat", which means some miscellaneous type of
-decomposition that doesn’t fit into the other decomposition categories
-that Unicode has chosen.
-</p>
-<p>Note that most Unicode characters don’t have a decomposition, so their
-decomposition type is <code>"None"</code>.
-</p>
-<p>For your convenience, Perl has added the <code>Non_Canonical</code>
decomposition
-type to mean any of the several compatibility decompositions.
-</p>
-</dd>
-<dt><strong><code>\p{Graph}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bGraph_007d"></a>
-<p>Matches any character that is graphic. Theoretically, this means a
character
-that on a printer would cause ink to be used.
-</p>
-</dd>
-<dt><strong><code>\p{HorizSpace}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bHorizSpace_007d"></a>
-<p>This is the same as <code>\h</code> and <code>\p{Blank}</code>: a
character that changes the
-spacing horizontally.
-</p>
-</dd>
-<dt><strong><code>\p{In=*}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bIn_003d_002a_007d"></a>
-<p>This is a synonym for <code>\p{Present_In=*}</code>
-</p>
-</dd>
-<dt><strong><code>\p{PerlSpace}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bPerlSpace_007d"></a>
-<p>This is the same as <code>\s</code>, restricted to ASCII, namely
<code>[ \f\n\r\t]<!-- /@w --></code>
-and starting in Perl v5.18, a vertical tab.
-</p>
-<p>Mnemonic: Perl’s (original) space
-</p>
-</dd>
-<dt><strong><code>\p{PerlWord}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bPerlWord_007d"></a>
-<p>This is the same as <code>\w</code>, restricted to ASCII, namely
<code>[A-Za-z0-9_]</code>
-</p>
-<p>Mnemonic: Perl’s (original) word.
-</p>
-</dd>
-<dt><strong><code>\p{Posix...}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bPosix_002e_002e_002e_007d"></a>
-<p>There are several of these, which are equivalents, using the
<code>\p{}</code>
-notation, for Posix classes and are described in
-<a href="#perlrecharclass-POSIX-Character-Classes">perlrecharclass POSIX
Character Classes</a>.
-</p>
-</dd>
-<dt><strong><code>\p{Present_In: *}</code></strong> (Short:
<code>\p{In=*}</code>)</dt>
-<dd><a
name="perlunicode-_005cp_007bPresent_005fIn_003a-_002a_007d-_0028Short_003a-_005cp_007bIn_003d_002a_007d_0029"></a>
-<p>This property is used when you need to know in what Unicode version(s) a
-character is.
-</p>
-<p>The "*" above stands for some two digit Unicode version number,
such as
-<code>1.1</code> or <code>4.0</code>; or the "*" can also be
<code>Unassigned</code>. This property will
-match the code points whose final disposition has been settled as of the
-Unicode release given by the version number; <code>\p{Present_In:
Unassigned}</code>
-will match those code points whose meaning has yet to be assigned.
-</p>
-<p>For example, <code>U+0041</code> <code>"LATIN CAPITAL LETTER
A"</code> was present in the very first
-Unicode release available, which is <code>1.1</code>, so this property is true
for all
-valid "*" versions. On the other hand, <code>U+1EFF</code> was not
assigned until version
-5.1 when it became <code>"LATIN SMALL LETTER Y WITH LOOP"</code>, so
the only "*" that
-would match it are 5.1, 5.2, and later.
-</p>
-<p>Unicode furnishes the <code>Age</code> property from which this is derived.
The problem
-with Age is that a strict interpretation of it (which Perl takes) has it
-matching the precise release a code point’s meaning is introduced in.
Thus
-<code>U+0041</code> would match only 1.1; and <code>U+1EFF</code> only 5.1.
This is not usually what
-you want.
-</p>
-<p>Some non-Perl implementations of the Age property may change its meaning to
be
-the same as the Perl <code>Present_In</code> property; just be aware of that.
-</p>
-<p>Another confusion with both these properties is that the definition is not
-that the code point has been <em>assigned</em>, but that the meaning of the
code point
-has been <em>determined</em>. This is because 66 code points will always be
-unassigned, and so the <code>Age</code> for them is the Unicode version in
which the decision
-to make them so was made. For example, <code>U+FDD0</code> is to be
permanently
-unassigned to a character, and the decision to do that was made in version 3.1,
-so <code>\p{Age=3.1}</code> matches this character, as also does
<code>\p{Present_In: 3.1}</code> and up.
-</p>
-</dd>
-<dt><strong><code>\p{Print}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bPrint_007d"></a>
-<p>This matches any character that is graphical or blank, except controls.
-</p>
-</dd>
-<dt><strong><code>\p{SpacePerl}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bSpacePerl_007d"></a>
-<p>This is the same as <code>\s</code>, including beyond ASCII.
-</p>
-<p>Mnemonic: Space, as modified by Perl. (It doesn’t include the
vertical tab
-until v5.18, which both the Posix standard and Unicode consider white space.)
-</p>
-</dd>
-<dt><strong><code>\p{Title}</code></strong> and
<strong><code>\p{Titlecase}</code></strong></dt>
-<dd><a
name="perlunicode-_005cp_007bTitle_007d-and-_005cp_007bTitlecase_007d"></a>
-<p>Under case-sensitive matching, these both match the same code points as
-<code>\p{General Category=Titlecase_Letter}</code> (<code>\p{gc=lt}</code>).
The difference
-is that under <code>/i</code> caseless matching, these match the same as
-<code>\p{Cased}</code>, whereas <code>\p{gc=lt}</code> matches
<code>\p{Cased_Letter</code>).
-</p>
-</dd>
-<dt><strong><code>\p{Unicode}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bUnicode_007d"></a>
-<p>This matches any of the 1_114_112 Unicode code points.
-<code>\p{Any}</code>.
-</p>
-</dd>
-<dt><strong><code>\p{VertSpace}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bVertSpace_007d"></a>
-<p>This is the same as <code>\v</code>: A character that changes the spacing
vertically.
-</p>
-</dd>
-<dt><strong><code>\p{Word}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bWord_007d"></a>
-<p>This is the same as <code>\w</code>, including over 100_000 characters
beyond ASCII.
-</p>
-</dd>
-<dt><strong><code>\p{XPosix...}</code></strong></dt>
-<dd><a name="perlunicode-_005cp_007bXPosix_002e_002e_002e_007d"></a>
-<p>There are several of these, which are the standard Posix classes
-extended to the full Unicode range. They are described in
-<a href="#perlrecharclass-POSIX-Character-Classes">perlrecharclass POSIX
Character Classes</a>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlunicode-User_002dDefined-Character-Properties"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunicode-User_002dDefined-Case-Mappings-_0028for-serious-hackers-only_0029"
accesskey="n" rel="next">perlunicode User-Defined Case Mappings (for serious
hackers only)</a>, Previous: <a
href="#perlunicode-Unicode-Character-Properties" accesskey="p"
rel="prev">perlunicode Unicode Character Properties</a>, Up: <a
href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="User_002dDefined-Character-Properties"></a>
-<h4 class="subsection">81.2.6 User-Defined Character Properties</h4>
-
-<p>You can define your own binary character properties by defining subroutines
-whose names begin with <code>"In"</code> or
<code>"Is"</code>. (The experimental feature
-<a href="#perlre-_0028_003f_005b-_005d_0029">perlre <code>(?[ ])</code></a>
provides an alternative which allows more complex
-definitions.) The subroutines can be defined in any
-package. The user-defined properties can be used in the regular expression
-<code>\p{}</code> and <code>\P{}</code> constructs; if you are using a
user-defined property from a
-package other than the one you are in, you must specify its package in the
-<code>\p{}</code> or <code>\P{}</code> construct.
-</p>
-<pre class="verbatim"> # assuming property Is_Foreign defined in Lang::
- package main; # property package name required
- if ($txt =~ /\p{Lang::IsForeign}+/) { ... }
-
- package Lang; # property package name not required
- if ($txt =~ /\p{IsForeign}+/) { ... }
-</pre>
-<p>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.
-</p>
-<p>Note that if the regular expression is tainted, then Perl will die rather
-than calling the subroutine when the name of the subroutine is
-determined by the tainted data.
-</p>
-<p>The subroutines must return a specially-formatted string, with one
-or more newline-separated lines. Each line must be one of the following:
-</p>
-<ul>
-<li> A single hexadecimal number denoting a code point to include.
-
-</li><li> Two hexadecimal numbers separated by horizontal whitespace (space or
-tabular characters) denoting a range of code points to include.
-
-</li><li> Something to include, prefixed by <code>"+"</code>: a
built-in character
-property (prefixed by <code>"utf8::"</code>) or a fully qualified
(including package
-name) user-defined character property,
-to represent all the characters in that property; two hexadecimal code
-points for a range; or a single hexadecimal code point.
-
-</li><li> Something to exclude, prefixed by <code>"-"</code>: an
existing character
-property (prefixed by <code>"utf8::"</code>) or a fully qualified
(including package
-name) user-defined character property,
-to represent all the characters in that property; two hexadecimal code
-points for a range; or a single hexadecimal code point.
-
-</li><li> Something to negate, prefixed <code>"!"</code>: an
existing character
-property (prefixed by <code>"utf8::"</code>) or a fully qualified
(including package
-name) user-defined character property,
-to represent all the characters in that property; two hexadecimal code
-points for a range; or a single hexadecimal code point.
-
-</li><li> Something to intersect with, prefixed by
<code>"&"</code>: an existing character
-property (prefixed by <code>"utf8::"</code>) or a fully qualified
(including package
-name) user-defined character property,
-for all the characters except the characters in the property; two
-hexadecimal code points for a range; or a single hexadecimal code point.
-
-</li></ul>
-
-<p>For example, to define a property that covers both the Japanese
-syllabaries (hiragana and katakana), you can define
-</p>
-<pre class="verbatim"> sub InKana {
- return <<END;
- 3040\t309F
- 30A0\t30FF
- END
- }
-</pre>
-<p>Imagine that the here-doc end marker is at the beginning of the line.
-Now you can use <code>\p{InKana}</code> and <code>\P{InKana}</code>.
-</p>
-<p>You could also have used the existing block property names:
-</p>
-<pre class="verbatim"> sub InKana {
- return <<'END';
- +utf8::InHiragana
- +utf8::InKatakana
- END
- }
-</pre>
-<p>Suppose you wanted to match only the allocated characters,
-not the raw block ranges: in other words, you want to remove
-the unassigned characters:
-</p>
-<pre class="verbatim"> sub InKana {
- return <<'END';
- +utf8::InHiragana
- +utf8::InKatakana
- -utf8::IsCn
- END
- }
-</pre>
-<p>The negation is useful for defining (surprise!) negated classes.
-</p>
-<pre class="verbatim"> sub InNotKana {
- return <<'END';
- !utf8::InHiragana
- -utf8::InKatakana
- +utf8::IsCn
- END
- }
-</pre>
-<p>This will match all non-Unicode code points, since every one of them is
-not in Kana. You can use intersection to exclude these, if desired, as
-this modified example shows:
-</p>
-<pre class="verbatim"> sub InNotKana {
- return <<'END';
- !utf8::InHiragana
- -utf8::InKatakana
- +utf8::IsCn
- &utf8::Any
- END
- }
-</pre>
-<p><code>&utf8::Any</code> must be the last line in the definition.
-</p>
-<p>Intersection is used generally for getting the common characters matched
-by two (or more) classes. It’s important to remember not to use
<code>"&"</code> for
-the first set; that would be intersecting with nothing, resulting in an
-empty set.
-</p>
-<p>Unlike non-user-defined <code>\p{}</code> property matches, no warning is
ever
-generated if these properties are matched against a non-Unicode code
-point (see <a href="#perlunicode-Beyond-Unicode-code-points">Beyond Unicode
code points</a> below).
-</p>
-<hr>
-<a
name="perlunicode-User_002dDefined-Case-Mappings-_0028for-serious-hackers-only_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Character-Encodings-for-Input-and-Output"
accesskey="n" rel="next">perlunicode Character Encodings for Input and
Output</a>, Previous: <a
href="#perlunicode-User_002dDefined-Character-Properties" accesskey="p"
rel="prev">perlunicode User-Defined Character Properties</a>, Up: <a
href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a
name="User_002dDefined-Case-Mappings-_0028for-serious-hackers-only_0029"></a>
-<h4 class="subsection">81.2.7 User-Defined Case Mappings (for serious hackers
only)</h4>
-
-<p><strong>This feature has been removed as of Perl 5.16.</strong>
-The CPAN module <code><a
href="Unicode-Casing.html#Top">(Unicode-Casing)</a></code> provides better
functionality without
-the drawbacks that this feature had. If you are using a Perl earlier
-than 5.16, this feature was most fully documented in the 5.14 version of
-this pod:
-<a
href="http://perldoc.perl.org/5.14.0/perlunicode.html#User-Defined-Case-Mappings-%28for-serious-hackers-only%29";>http://perldoc.perl.org/5.14.0/perlunicode.html#User-Defined-Case-Mappings-%28for-serious-hackers-only%29</a>
-</p>
-<hr>
-<a name="perlunicode-Character-Encodings-for-Input-and-Output"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Unicode-Regular-Expression-Support-Level"
accesskey="n" rel="next">perlunicode Unicode Regular Expression Support
Level</a>, Previous: <a
href="#perlunicode-User_002dDefined-Case-Mappings-_0028for-serious-hackers-only_0029"
accesskey="p" rel="prev">perlunicode User-Defined Case Mappings (for serious
hackers only)</a>, Up: <a href="#perlunicode-DESCRIPTION" accesskey="u"
rel="up">perlunicode DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Character-Encodings-for-Input-and-Output"></a>
-<h4 class="subsection">81.2.8 Character Encodings for Input and Output</h4>
-
-<p>See <a href="Encode.html#Top">(Encode)</a>.
-</p>
-<hr>
-<a name="perlunicode-Unicode-Regular-Expression-Support-Level"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Unicode-Encodings" accesskey="n"
rel="next">perlunicode Unicode Encodings</a>, Previous: <a
href="#perlunicode-Character-Encodings-for-Input-and-Output" accesskey="p"
rel="prev">perlunicode Character Encodings for Input and Output</a>, Up: <a
href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-Regular-Expression-Support-Level"></a>
-<h4 class="subsection">81.2.9 Unicode Regular Expression Support Level</h4>
-
-<p>The following list of Unicode supported features for regular expressions
describes
-all features currently directly supported by core Perl. The references to
"Level N"
-and the section numbers refer to the Unicode Technical Standard #18,
-"Unicode Regular Expressions", version 13, from August 2008.
-</p>
-<ul>
-<li> Level 1 - Basic Unicode Support
-
-<pre class="verbatim"> RL1.1 Hex Notation - done
[1]
- RL1.2 Properties - done [2][3]
- RL1.2a Compatibility Properties - done [4]
- RL1.3 Subtraction and Intersection - experimental [5]
- RL1.4 Simple Word Boundaries - done [6]
- RL1.5 Simple Loose Matches - done [7]
- RL1.6 Line Boundaries - MISSING [8][9]
- RL1.7 Supplementary Code Points - done [10]
-</pre>
-<dl compact="compact">
-<dt>[1] <code>\N{U+...}</code> and <code>\x{...}</code></dt>
-<dd><a
name="perlunicode-_005b1_005d-_005cN_007bU_002b_002e_002e_002e_007d-and-_005cx_007b_002e_002e_002e_007d"></a>
-</dd>
-<dt>[2] <code>\p{...}</code> <code>\P{...}</code></dt>
-<dd><a
name="perlunicode-_005b2_005d-_005cp_007b_002e_002e_002e_007d-_005cP_007b_002e_002e_002e_007d"></a>
-</dd>
-<dt>[3] supports not only minimal list, but all Unicode character properties
(see Unicode Character Properties above)</dt>
-<dd><a
name="perlunicode-_005b3_005d-supports-not-only-minimal-list_002c-but-all-Unicode-character-properties-_0028see-Unicode-Character-Properties-above_0029"></a>
-</dd>
-<dt>[4] <code>\d</code> <code>\D</code> <code>\s</code> <code>\S</code>
<code>\w</code> <code>\W</code> <code>\X</code> <code>[:<em>prop</em>:]</code>
<code>[:^<em>prop</em>:]</code></dt>
-<dd><a
name="perlunicode-_005b4_005d-_005cd-_005cD-_005cs-_005cS-_005cw-_005cW-_005cX-_005b_003aprop_003a_005d-_005b_003a_005eprop_003a_005d"></a>
-</dd>
-<dt>[5] The experimental feature starting in v5.18
<code>"(?[...])"</code> accomplishes this.</dt>
-<dd><a
name="perlunicode-_005b5_005d-The-experimental-feature-starting-in-v5_002e18-_0022_0028_003f_005b_002e_002e_002e_005d_0029_0022-accomplishes-this_002e"></a>
-<p>See <a href="#perlre-_0028_003f_005b-_005d_0029">perlre <code>(?[
])</code></a>. If you don’t want to use an experimental
-feature, you can use one of the following:
-</p>
-<ul>
-<li> Regular expression look-ahead
-
-<p>You can mimic class subtraction using lookahead.
-For example, what UTS#18 might write as
-</p>
-<pre class="verbatim"> [{Block=Greek}-[{UNASSIGNED}]]
-</pre>
-<p>in Perl can be written as:
-</p>
-<pre class="verbatim"> (?!\p{Unassigned})\p{Block=Greek}
- (?=\p{Assigned})\p{Block=Greek}
-</pre>
-<p>But in this particular example, you probably really want
-</p>
-<pre class="verbatim"> \p{Greek}
-</pre>
-<p>which will match assigned characters known to be part of the Greek script.
-</p>
-</li><li> CPAN module <code><a
href="Unicode-Regex-Set.html#Top">(Unicode-Regex-Set)</a></code>
-
-<p>It does implement the full UTS#18 grouping, intersection, union, and
-removal (subtraction) syntax.
-</p>
-</li><li> <a
href="#perlunicode-User_002dDefined-Character-Properties">User-Defined
Character Properties</a>
-
-<p><code>"+"</code> for union, <code>"-"</code> for
removal (set-difference), <code>"&"</code> for intersection
-</p>
-</li></ul>
-
-</dd>
-<dt>[6] <code>\b</code> <code>\B</code></dt>
-<dd><a name="perlunicode-_005b6_005d-_005cb-_005cB"></a>
-</dd>
-<dt>[7] Note that Perl does Full case-folding in matching, not Simple:</dt>
-<dd><a
name="perlunicode-_005b7_005d-Note-that-Perl-does-Full-case_002dfolding-in-matching_002c-not-Simple_003a"></a>
-<p>For example <code>U+1F88</code> is equivalent to <code>U+1F00
U+03B9</code>, instead of just
-<code>U+1F80</code>. 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.
-</p>
-</dd>
-<dt>[8] Perl treats <code>\n</code> as the start- and end-line delimiter.
Unicode specifies more characters that should be so-interpreted.</dt>
-<dd><a
name="perlunicode-_005b8_005d-Perl-treats-_005cn-as-the-start_002d-and-end_002dline-delimiter_002e-Unicode-specifies-more-characters-that-should-be-so_002dinterpreted_002e"></a>
-<p>These are:
-</p>
-<pre class="verbatim"> VT U+000B (\v in C)
- FF U+000C (\f)
- CR U+000D (\r)
- NEL U+0085
- LS U+2028
- PS U+2029
-</pre>
-<p><code>^</code> and <code>$</code> in regular expression patterns are
supposed to match all
-these, but don’t.
-These characters also don’t, but should, affect <code><></code>
<code>$.</code>, and
-script line numbers.
-</p>
-<p>Also, lines should not be split within <code>CRLF</code> (i.e. there is no
-empty line between <code>\r</code> and <code>\n</code>). For
<code>CRLF</code>, try the <code>:crlf</code>
-layer (see <a href="PerlIO.html#Top">(PerlIO)</a>).
-</p>
-</dd>
-<dt>[9] But <code><a
href="Unicode-LineBreak.html#Top">(Unicode-LineBreak)</a></code> is
available.</dt>
-<dd><a
name="perlunicode-_005b9_005d-But-Unicode_002dLineBreak-is-available_002e"></a>
-<p>This module supplies line breaking conformant with
-<a href="http://www.unicode.org/reports/tr14";>UAX#14 "Unicode Line
Breaking Algorithm"</a>.
-</p>
-</dd>
-<dt>[10] UTF-8/UTF-EBDDIC used in Perl allows not only <code>U+10000</code> to
<code>U+10FFFF</code> but also beyond <code>U+10FFFF</code></dt>
-<dd><a
name="perlunicode-_005b10_005d-UTF_002d8_002fUTF_002dEBDDIC-used-in-Perl-allows-not-only-U_002b10000-to-U_002b10FFFF-but-also-beyond-U_002b10FFFF"></a>
-</dd>
-</dl>
-
-</li><li> Level 2 - Extended Unicode Support
-
-<pre class="verbatim"> RL2.1 Canonical Equivalents - MISSING
[10][11]
- RL2.2 Default Grapheme Clusters - MISSING [12]
- RL2.3 Default Word Boundaries - DONE [14]
- RL2.4 Default Loose Matches - MISSING [15]
- RL2.5 Name Properties - DONE
- RL2.6 Wildcard Properties - MISSING
-
- [10] see UAX#15 "Unicode Normalization Forms"
- [11] have Unicode::Normalize but not integrated to regexes
- [12] have \X and \b{gcb} but we don't have a "Grapheme Cluster
- Mode"
- [14] see UAX#29, Word Boundaries
- [15] This is covered in Chapter 3.13 (in Unicode 6.0)
-</pre>
-</li><li> Level 3 - Tailored Support
-
-<pre class="verbatim"> RL3.1 Tailored Punctuation - MISSING
- RL3.2 Tailored Grapheme Clusters - MISSING [17][18]
- RL3.3 Tailored Word Boundaries - MISSING
- RL3.4 Tailored Loose Matches - MISSING
- RL3.5 Tailored Ranges - MISSING
- RL3.6 Context Matching - MISSING [19]
- RL3.7 Incremental Matches - MISSING
- ( RL3.8 Unicode Set Sharing )
- RL3.9 Possible Match Sets - MISSING
- RL3.10 Folded Matching - MISSING [20]
- RL3.11 Submatchers - MISSING
-
- [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")
-</pre>
-</li></ul>
-
-<hr>
-<a name="perlunicode-Unicode-Encodings"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Noncharacter-code-points" accesskey="n"
rel="next">perlunicode Noncharacter code points</a>, Previous: <a
href="#perlunicode-Unicode-Regular-Expression-Support-Level" accesskey="p"
rel="prev">perlunicode Unicode Regular Expression Support Level</a>, Up: <a
href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-Encodings"></a>
-<h4 class="subsection">81.2.10 Unicode Encodings</h4>
-
-<p>Unicode characters are assigned to <em>code points</em>, which are abstract
-numbers. To use these numbers, various encodings are needed.
-</p>
-<ul>
-<li> UTF-8
-
-<p>UTF-8 is a variable-length (1 to 4 bytes), byte-order independent
-encoding. In most of Perl’s documentation, including elsewhere in this
-document, the term "UTF-8" means also "UTF-EBCDIC". But
in this section,
-"UTF-8" refers only to the encoding used on ASCII platforms. It is a
-superset of 7-bit US-ASCII, so anything encoded in ASCII has the
-identical representation when encoded in UTF-8.
-</p>
-<p>The following table is from Unicode 3.2.
-</p>
-<pre class="verbatim"> Code Points 1st Byte 2nd Byte 3rd Byte 4th
Byte
-
- U+0000..U+007F 00..7F
- U+0080..U+07FF * C2..DF 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
-</pre>
-<p>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
-(and that is what Perl does).
-</p>
-<p>Another way to look at it is via bits:
-</p>
-<pre class="verbatim"> Code Points 1st Byte 2nd Byte 3rd
Byte 4th Byte
-
- 0aaaaaaa 0aaaaaaa
- 00000bbbbbaaaaaa 110bbbbb 10aaaaaa
- ccccbbbbbbaaaaaa 1110cccc 10bbbbbb 10aaaaaa
- 00000dddccccccbbbbbbaaaaaa 11110ddd 10cccccc 10bbbbbb 10aaaaaa
-</pre>
-<p>As you can see, the continuation bytes all begin with
<code>"10"</code>, and the
-leading bits of the start byte tell how many bytes there are in the
-encoded character.
-</p>
-<p>The original UTF-8 specification allowed up to 6 bytes, to allow
-encoding of numbers up to <code>0x7FFF_FFFF</code>. 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.
-</p>
-</li><li> UTF-EBCDIC
-
-<p>Like UTF-8, but EBCDIC-safe, in the way that UTF-8 is ASCII-safe.
-This means that all the basic characters (which includes all
-those that have ASCII equivalents (like <code>"A"</code>,
<code>"0"</code>, <code>"%"</code>, <em>etc.</em>)
-are the same in both EBCDIC and UTF-EBCDIC.)
-</p>
-<p>UTF-EBCDIC is used on EBCDIC platforms. The largest Unicode code points
-take 5 bytes to represent (instead of 4 in UTF-8), and Perl extends it
-to a maximum of 7 bytes to encode pode points up to what can fit in a
-32-bit word (instead of 13 bytes and a 64-bit word in UTF-8).
-</p>
-</li><li> UTF-16, UTF-16BE, UTF-16LE, Surrogates, and <code>BOM</code>’s
(Byte Order Marks)
-
-<p>The followings items are mostly for reference and general Unicode
-knowledge, Perl doesn’t use these constructs internally.
-</p>
-<p>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
-<code>U+0000..U+FFFF</code> are stored in a single 16-bit unit, and code
-points <code>U+10000..U+10FFFF</code> in two 16-bit units. The latter case is
-using <em>surrogates</em>, the first 16-bit unit being the <em>high
-surrogate</em>, and the second being the <em>low surrogate</em>.
-</p>
-<p>Surrogates are code points set aside to encode the
<code>U+10000..U+10FFFF</code>
-range of Unicode code points in pairs of 16-bit units. The <em>high
-surrogates</em> are the range <code>U+D800..U+DBFF</code> and the <em>low
surrogates</em>
-are the range <code>U+DC00..U+DFFF</code>. The surrogate encoding is
-</p>
-<pre class="verbatim"> $hi = ($uni - 0x10000) / 0x400 + 0xD800;
- $lo = ($uni - 0x10000) % 0x400 + 0xDC00;
-</pre>
-<p>and the decoding is
-</p>
-<pre class="verbatim"> $uni = 0x10000 + ($hi - 0xD800) * 0x400 + ($lo -
0xDC00);
-</pre>
-<p>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
-transfer is required either UTF-16BE (big-endian) or UTF-16LE
-(little-endian) encodings must be chosen.
-</p>
-<p>This introduces another problem: what if you just know that your data
-is UTF-16, but you don’t know which endianness? Byte Order Marks, or
-<code>BOM</code>’s, are a solution to this. A special character has
been reserved
-in Unicode to function as a byte order marker: the character with the
-code point <code>U+FEFF</code> is the <code>BOM</code>.
-</p>
-<p>The trick is that if you read a <code>BOM</code>, you will know the byte
order,
-since if it was written on a big-endian platform, you will read the
-bytes <code>0xFE 0xFF</code>, but if it was written on a little-endian
platform,
-you will read the bytes <code>0xFF 0xFE</code>. (And if the originating
platform
-was writing in ASCII platform UTF-8, you will read the bytes
-<code>0xEF 0xBB 0xBF</code>.)
-</p>
-<p>The way this trick works is that the character with the code point
-<code>U+FFFE</code> is not supposed to be in input streams, so the
-sequence of bytes <code>0xFF 0xFE</code> is unambiguously
"<code>BOM</code>, represented in
-little-endian format" and cannot be <code>U+FFFE</code>, represented in
big-endian
-format".
-</p>
-<p>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
-<code>chr(0xD801)</code>, so that all code points, not just those valid for
open
-interchange, are
-representable. Unicode does define semantics for them, such as their
-<code><a href="#perlunicode-General_005fCategory">General_Category</a></code>
is <code>"Cs"</code>. But because their use is somewhat dangerous,
-Perl will warn (using the warning category <code>"surrogate"</code>,
which is a
-sub-category of <code>"utf8"</code>) 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.)
-</p>
-</li><li> UTF-32, UTF-32BE, UTF-32LE
-
-<p>The UTF-32 family is pretty much like the UTF-16 family, except that
-the units are 32-bit, and therefore the surrogate scheme is not
-needed. UTF-32 is a fixed-width encoding. The <code>BOM</code> signatures are
-<code>0x00 0x00 0xFE 0xFF</code> for BE and <code>0xFF 0xFE 0x00 0x00</code>
for LE.
-</p>
-</li><li> UCS-2, UCS-4
-
-<p>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 <code>U+FFFF</code>,
-because it does not use surrogates. UCS-4 is a 32-bit encoding,
-functionally identical to UTF-32 (the difference being that
-UCS-4 forbids neither surrogates nor code points larger than
<code>0x10_FFFF</code>).
-</p>
-</li><li> UTF-7
-
-<p>A seven-bit safe (non-eight-bit) encoding, which is useful if the
-transport or storage is not eight-bit safe. Defined by RFC 2152.
-</p>
-</li></ul>
-
-<hr>
-<a name="perlunicode-Noncharacter-code-points"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Beyond-Unicode-code-points" accesskey="n"
rel="next">perlunicode Beyond Unicode code points</a>, Previous: <a
href="#perlunicode-Unicode-Encodings" accesskey="p" rel="prev">perlunicode
Unicode Encodings</a>, Up: <a href="#perlunicode-DESCRIPTION" accesskey="u"
rel="up">perlunicode DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Noncharacter-code-points"></a>
-<h4 class="subsection">81.2.11 Noncharacter code points</h4>
-
-<p>66 code points are set aside in Unicode as "noncharacter code
points".
-These all have the <code>Unassigned</code> (<code>Cn</code>) <code><a
href="#perlunicode-General_005fCategory">General_Category</a></code>, and
-no character will ever be assigned to any of them. They are the 32 code
-points between <code>U+FDD0</code> and <code>U+FDEF</code> inclusive, and the
34 code
-points:
-</p>
-<pre class="verbatim"> U+FFFE U+FFFF
- U+1FFFE U+1FFFF
- U+2FFFE U+2FFFF
- ...
- U+EFFFE U+EFFFF
- U+FFFFE U+FFFFF
- U+10FFFE U+10FFFF
-</pre>
-<p>Until Unicode 7.0, the noncharacters were "<strong>forbidden</strong>
for use in open
-interchange of Unicode text data", so that code that processed those
-streams could use these code points as sentinels that could be mixed in
-with character data, and would always be distinguishable from that data.
-(Emphasis above and in the next paragraph are added in this document.)
-</p>
-<p>Unicode 7.0 changed the wording so that they are "<strong>not
recommended</strong> for
-use in open interchange of Unicode text data". The 7.0 Standard goes on
-to say:
-</p>
-<blockquote>
-<p>"If a noncharacter is received in open interchange, an application is
-not required to interpret it in any way. It is good practice, however,
-to recognize it as a noncharacter and to take appropriate action, such
-as replacing it with <code>U+FFFD</code> replacement character, to indicate the
-problem in the text. It is not recommended to simply delete
-noncharacter code points from such text, because of the potential
-security issues caused by deleting uninterpreted characters. (See
-conformance clause C7 in Section 3.2, Conformance Requirements, and
-<a
href="http://www.unicode.org/reports/tr36/#Substituting_for_Ill_Formed_Subsequences";>Unicode
Technical Report #36, "Unicode Security
-Considerations"</a>)."
-</p>
-</blockquote>
-
-<p>This change was made because it was found that various commercial tools
-like editors, or for things like source code control, had been written
-so that they would not handle program files that used these code points,
-effectively precluding their use almost entirely! And that was never
-the intent. They’ve always been meant to be usable within an
-application, or cooperating set of applications, at will.
-</p>
-<p>If you’re writing code, such as an editor, that is supposed to be able
-to handle any Unicode text data, then you shouldn’t be using these code
-points yourself, and instead allow them in the input. If you need
-sentinels, they should instead be something that isn’t legal Unicode.
-For UTF-8 data, you can use the bytes 0xC1 and 0xC2 as sentinels, as
-they never appear in well-formed UTF-8. (There are equivalents for
-UTF-EBCDIC). You can also store your Unicode code points in integer
-variables and use negative values as sentinels.
-</p>
-<p>If you’re not writing such a tool, then whether you accept
noncharacters
-as input is up to you (though the Standard recommends that you not). If
-you do strict input stream checking with Perl, these code points
-continue to be forbidden. This is to maintain backward compatibility
-(otherwise potential security holes could open up, as an unsuspecting
-application that was written assuming the noncharacters would be
-filtered out before getting to it, could now, without warning, start
-getting them). To do strict checking, you can use the layer
-<code>:encoding('UTF-8')</code>.
-</p>
-<p>Perl continues to warn (using the warning category
<code>"nonchar"</code>, which
-is a sub-category of <code>"utf8"</code>) if an attempt is made to
output
-noncharacters.
-</p>
-<hr>
-<a name="perlunicode-Beyond-Unicode-code-points"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Security-Implications-of-Unicode" accesskey="n"
rel="next">perlunicode Security Implications of Unicode</a>, Previous: <a
href="#perlunicode-Noncharacter-code-points" accesskey="p"
rel="prev">perlunicode Noncharacter code points</a>, Up: <a
href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Beyond-Unicode-code-points"></a>
-<h4 class="subsection">81.2.12 Beyond Unicode code points</h4>
-
-<p>The maximum Unicode code point is <code>U+10FFFF</code>, and Unicode only
defines
-operations on code points up through that. But Perl works on 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
-<code>"non_unicode"</code>, which is a sub-category of
<code>"utf8"</code>) if any are output.
-</p>
-<p>Since Unicode rules are not defined on these code points, if a
-Unicode-defined operation is done on them, Perl uses what we believe are
-sensible rules, while generally warning, using the
<code>"non_unicode"</code>
-category. For example, <code>uc("\x{11_0000}")</code> will generate
such a
-warning, returning the input parameter as its result, since Perl defines
-the uppercase of every non-Unicode code point to be the code point
-itself. (All the case changing operations, not just uppercasing, work
-this way.)
-</p>
-<p>The situation with matching Unicode properties in regular expressions,
-the <code>\p{}</code> and <code>\P{}</code> constructs, against these code
points is not as
-clear cut, and how these are handled has changed as we’ve gained
-experience.
-</p>
-<p>One possibility is to treat any match against these code points as
-undefined. But since Perl doesn’t have the concept of a match being
-undefined, it converts this to failing or <code>FALSE</code>. This is almost,
but
-not quite, what Perl did from v5.14 (when use of these code points
-became generally reliable) through v5.18. The difference is that Perl
-treated all <code>\p{}</code> matches as failing, but all <code>\P{}</code>
matches as
-succeeding.
-</p>
-<p>One problem with this is that it leads to unexpected, and confusting
-results in some cases:
-</p>
-<pre class="verbatim"> chr(0x110000) =~ \p{ASCII_Hex_Digit=True} # Failed
on <= v5.18
- chr(0x110000) =~ \p{ASCII_Hex_Digit=False} # Failed! on <= v5.18
-</pre>
-<p>That is, it treated both matches as undefined, and converted that to
-false (raising a warning on each). The first case is the expected
-result, but the second is likely counterintuitive: "How could both be
-false when they are complements?" Another problem was that the
-implementation optimized many Unicode property matches down to already
-existing simpler, faster operations, which don’t raise the warning. We
-chose to not forgo those optimizations, which help the vast majority of
-matches, just to generate a warning for the unlikely event that an
-above-Unicode code point is being matched against.
-</p>
-<p>As a result of these problems, starting in v5.20, what Perl does is
-to treat non-Unicode code points as just typical unassigned Unicode
-characters, and matches accordingly. (Note: Unicode has atypical
-unassigned code points. For example, it has noncharacter code points,
-and ones that, when they do get assigned, are destined to be written
-Right-to-left, as Arabic and Hebrew are. Perl assumes that no
-non-Unicode code point has any atypical properties.)
-</p>
-<p>Perl, in most cases, will raise a warning when matching an above-Unicode
-code point against a Unicode property when the result is <code>TRUE</code> for
-<code>\p{}</code>, and <code>FALSE</code> for <code>\P{}</code>. For example:
-</p>
-<pre class="verbatim"> chr(0x110000) =~ \p{ASCII_Hex_Digit=True} # Fails,
no warning
- chr(0x110000) =~ \p{ASCII_Hex_Digit=False} # Succeeds, with warning
-</pre>
-<p>In both these examples, the character being matched is non-Unicode, so
-Unicode doesn’t define how it should match. It clearly isn’t an
ASCII
-hex digit, so the first example clearly should fail, and so it does,
-with no warning. But it is arguable that the second example should have
-an undefined, hence <code>FALSE</code>, result. So a warning is raised for it.
-</p>
-<p>Thus the warning is raised for many fewer cases than in earlier Perls,
-and only when what the result is could be arguable. It turns out that
-none of the optimizations made by Perl (or are ever likely to be made)
-cause the warning to be skipped, so it solves both problems of Perl’s
-earlier approach. The most commonly used property that is affected by
-this change is <code>\p{Unassigned}</code> which is a short form for
-<code>\p{General_Category=Unassigned}</code>. Starting in v5.20, all
non-Unicode
-code points are considered <code>Unassigned</code>. In earlier releases the
-matches failed because the result was considered undefined.
-</p>
-<p>The only place where the warning is not raised when it might ought to
-have been is if optimizations cause the whole pattern match to not even
-be attempted. For example, Perl may figure out that for a string to
-match a certain regular expression pattern, the string has to contain
-the substring <code>"foobar"</code>. Before attempting the match,
Perl may look
-for that substring, and if not found, immediately fail the match without
-actually trying it; so no warning gets generated even if the string
-contains an above-Unicode code point.
-</p>
-<p>This behavior is more "Do what I mean" than in earlier Perls for
most
-applications. But it catches fewer issues for code that needs to be
-strictly Unicode compliant. Therefore there is an additional mode of
-operation available to accommodate such code. This mode is enabled if a
-regular expression pattern is compiled within the lexical scope where
-the <code>"non_unicode"</code> warning class has been made fatal,
say by:
-</p>
-<pre class="verbatim"> use warnings FATAL => "non_unicode"
-</pre>
-<p>(see <a href="warnings.html#Top">(warnings)</a>). In this mode of
operation, Perl will raise the
-warning for all matches against a non-Unicode code point (not just the
-arguable ones), and it skips the optimizations that might cause the
-warning to not be output. (It currently still won’t warn if the match
-isn’t even attempted, like in the <code>"foobar"</code>
example above.)
-</p>
-<p>In summary, Perl now normally treats non-Unicode code points as typical
-Unicode unassigned code points for regular expression matches, raising a
-warning only when it is arguable what the result should be. However, if
-this warning has been made fatal, it isn’t skipped.
-</p>
-<p>There is one exception to all this. <code>\p{All}</code> looks like a
Unicode
-property, but it is a Perl extension that is defined to be true for all
-possible code points, Unicode or not, so no warning is ever generated
-when matching this against a non-Unicode code point. (Prior to v5.20,
-it was an exact synonym for <code>\p{Any}</code>, matching code points
<code>0</code>
-through <code>0x10FFFF</code>.)
-</p>
-<hr>
-<a name="perlunicode-Security-Implications-of-Unicode"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Unicode-in-Perl-on-EBCDIC" accesskey="n"
rel="next">perlunicode Unicode in Perl on EBCDIC</a>, Previous: <a
href="#perlunicode-Beyond-Unicode-code-points" accesskey="p"
rel="prev">perlunicode Beyond Unicode code points</a>, Up: <a
href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Security-Implications-of-Unicode"></a>
-<h4 class="subsection">81.2.13 Security Implications of Unicode</h4>
-
-<p>First, read
-<a href="http://www.unicode.org/reports/tr36";>Unicode Security
Considerations</a>.
-</p>
-<p>Also, note the following:
-</p>
-<ul>
-<li> Malformed UTF-8
-
-<p>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,
-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 Unicode code points valid for interchange.
-</p>
-</li><li> 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 <a
href="#perlre-Character-set-modifiers">perlre Character set modifiers</a>.
-
-</li></ul>
-
-<p>As discussed elsewhere, Perl has one foot (two hooves?) planted in
-each of two worlds: the old world of ASCII and single-byte locales, and
-the new world of Unicode, upgrading when necessary.
-If your legacy code does not explicitly use Unicode, no automatic
-switch-over to Unicode should happen.
-</p>
-<hr>
-<a name="perlunicode-Unicode-in-Perl-on-EBCDIC"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Locales" accesskey="n" rel="next">perlunicode
Locales</a>, Previous: <a href="#perlunicode-Security-Implications-of-Unicode"
accesskey="p" rel="prev">perlunicode Security Implications of Unicode</a>, Up:
<a href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-in-Perl-on-EBCDIC"></a>
-<h4 class="subsection">81.2.14 Unicode in Perl on EBCDIC</h4>
-
-<p>Unicode is supported on EBCDIC platforms. See <a
href="#perlebcdic-NAME">perlebcdic NAME</a>.
-</p>
-<p>Unless ASCII vs. EBCDIC issues are specifically being discussed,
-references to UTF-8 encoding in this document and elsewhere should be
-read as meaning UTF-EBCDIC on EBCDIC platforms.
-See <a href="#perlebcdic-Unicode-and-UTF">perlebcdic Unicode and UTF</a>.
-</p>
-<p>Because UTF-EBCDIC is so similar to UTF-8, the differences are mostly
-hidden from you; <code>use utf8</code><!-- /@w --> (and NOT something like
-<code>use utfebcdic</code><!-- /@w -->) declares the the script is in the
platform’s
-"native" 8-bit encoding of Unicode. (Similarly for the
<code>":utf8"</code>
-layer.)
-</p>
-<hr>
-<a name="perlunicode-Locales"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-When-Unicode-Does-Not-Happen" accesskey="n"
rel="next">perlunicode When Unicode Does Not Happen</a>, Previous: <a
href="#perlunicode-Unicode-in-Perl-on-EBCDIC" accesskey="p"
rel="prev">perlunicode Unicode in Perl on EBCDIC</a>, Up: <a
href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Locales"></a>
-<h4 class="subsection">81.2.15 Locales</h4>
-
-<p>See <a href="#perllocale-Unicode-and-UTF_002d8">perllocale Unicode and
UTF-8</a>
-</p>
-<hr>
-<a name="perlunicode-When-Unicode-Does-Not-Happen"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-The-_0022Unicode-Bug_0022" accesskey="n"
rel="next">perlunicode The "Unicode Bug"</a>, Previous: <a
href="#perlunicode-Locales" accesskey="p" rel="prev">perlunicode Locales</a>,
Up: <a href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="When-Unicode-Does-Not-Happen"></a>
-<h4 class="subsection">81.2.16 When Unicode Does Not Happen</h4>
-
-<p>There are still many places where Unicode (in some encoding or
-another) could be given as arguments or received as results, or both in
-Perl, but it is not, in spite of Perl having extensive ways to input and
-output in Unicode, and a few other "entry points" like the
<code>@ARGV</code>
-array (which can sometimes be interpreted as UTF-8).
-</p>
-<p>The following are such interfaces. Also, see <a
href="#perlunicode-The-_0022Unicode-Bug_0022">The "Unicode Bug"</a>.
-For all of these interfaces Perl
-currently (as of v5.16.0) simply assumes byte strings both as arguments
-and results, or UTF-8 strings if the (deprecated) <code>encoding</code> pragma
has been used.
-</p>
-<p>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 <code>qx</code> and <code>system</code>: how
well will the
-"command-line interface" (and which of them?) handle Unicode?
-</p>
-<ul>
-<li> <code>chdir</code>, <code>chmod</code>, <code>chown</code>,
<code>chroot</code>, <code>exec</code>, <code>link</code>, <code>lstat</code>,
<code>mkdir</code>,
-<code>rename</code>, <code>rmdir</code>, <code>stat</code>,
<code>symlink</code>, <code>truncate</code>, <code>unlink</code>,
<code>utime</code>, <code>-X</code>
-
-</li><li> <code>%ENV</code>
-
-</li><li> <code>glob</code> (aka the <code><*></code>)
-
-</li><li> <code>open</code>, <code>opendir</code>, <code>sysopen</code>
-
-</li><li> <code>qx</code> (aka the backtick operator), <code>system</code>
-
-</li><li> <code>readdir</code>, <code>readlink</code>
-
-</li></ul>
-
-<hr>
-<a name="perlunicode-The-_0022Unicode-Bug_0022"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunicode-Forcing-Unicode-in-Perl-_0028Or-Unforcing-Unicode-in-Perl_0029"
accesskey="n" rel="next">perlunicode Forcing Unicode in Perl (Or Unforcing
Unicode in Perl)</a>, Previous: <a
href="#perlunicode-When-Unicode-Does-Not-Happen" accesskey="p"
rel="prev">perlunicode When Unicode Does Not Happen</a>, Up: <a
href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-_0022Unicode-Bug_0022"></a>
-<h4 class="subsection">81.2.17 The "Unicode Bug"</h4>
-
-<p>The term, "Unicode bug" has been applied to an inconsistency with
the
-code points in the <code>Latin-1 Supplement</code> block, that is, between
-128 and 255. Without a locale specified, unlike all other characters or
-code points, these characters can have very different semantics
-depending on the rules in effect. (Characters whose code points are
-above 255 force Unicode rules; whereas the rules for ASCII characters
-are the same under both ASCII and Unicode rules.)
-</p>
-<p>Under Unicode rules, these upper-Latin1 characters are interpreted as
-Unicode code points, which means they have the same semantics as Latin-1
-(ISO-8859-1) and C1 controls.
-</p>
-<p>As explained in <a
href="#perlunicode-ASCII-Rules-versus-Unicode-Rules">ASCII Rules versus Unicode
Rules</a>, under ASCII rules,
-they are considered to be unassigned characters.
-</p>
-<p>This can lead to unexpected results. For example, a string’s
-semantics can suddenly change if a code point above 255 is appended to
-it, which changes the rules from ASCII to Unicode. As an
-example, consider the following program and its output:
-</p>
-<pre class="verbatim"> $ perl -le'
- no feature 'unicode_strings';
- $s1 = "\xC2";
- $s2 = "\x{2660}";
- for ($s1, $s2, $s1.$s2) {
- print /\w/ || 0;
- }
- '
- 0
- 0
- 1
-</pre>
-<p>If there’s no <code>\w</code> in <code>s1</code> nor in
<code>s2</code>, why does their concatenation
-have one?
-</p>
-<p>This anomaly stems from Perl’s attempt to not disturb older programs
that
-didn’t use Unicode, along with Perl’s desire to add Unicode support
-seamlessly. But the result turned out to not be seamless. (By the way,
-you can choose to be warned when things like this happen. See
-<code><a href="encoding-warnings.html#Top">(encoding-warnings)</a></code>.)
-</p>
-<p><a
href="feature.html#The-_0027unicode_005fstrings_0027-feature">(feature)<code>use feature <span
class="nolinebreak">'unicode_strings'</span></code><!-- /@w --></a>
-was added, starting in Perl v5.12, to address this problem. It affects
-these things:
-</p>
-<ul>
-<li> Changing the case of a scalar, that is, using <code>uc()</code>,
<code>ucfirst()</code>, <code>lc()</code>,
-and <code>lcfirst()</code>, or <code>\L</code>, <code>\U</code>,
<code>\u</code> and <code>\l</code> in double-quotish
-contexts, such as regular expression substitutions.
-
-<p>Under <code>unicode_strings</code> starting in Perl 5.12.0, Unicode rules
are
-generally used. See <a href="#perlfunc-lc">perlfunc lc</a> for details on how
this works
-in combination with various other pragmas.
-</p>
-</li><li> Using caseless (<code>/i</code>) regular expression matching.
-
-<p>Starting in Perl 5.14.0, regular expressions compiled within
-the scope of <code>unicode_strings</code> use Unicode rules
-even when executed or compiled into larger
-regular expressions outside the scope.
-</p>
-</li><li> Matching any of several properties in regular expressions.
-
-<p>These properties are <code>\b</code> (without braces), <code>\B</code>
(without braces),
-<code>\s</code>, <code>\S</code>, <code>\w</code>, <code>\W</code>, and all
the Posix character classes
-<em>except</em> <code>[[:ascii:]]</code>.
-</p>
-<p>Starting in Perl 5.14.0, regular expressions compiled within
-the scope of <code>unicode_strings</code> use Unicode rules
-even when executed or compiled into larger
-regular expressions outside the scope.
-</p>
-</li><li> In <code>quotemeta</code> or its inline equivalent <code>\Q</code>.
-
-<p>Starting in Perl 5.16.0, consistent quoting rules are used within the
-scope of <code>unicode_strings</code>, as described in <a
href="#perlfunc-quotemeta">perlfunc quotemeta</a>.
-Prior to that, or outside its scope, no code points above 127 are quoted
-in UTF-8 encoded strings, but in byte encoded strings, code points
-between 128-255 are always quoted.
-</p>
-</li></ul>
-
-<p>You can see from the above that the effect of <code>unicode_strings</code>
-increased over several Perl releases. (And Perl’s support for Unicode
-continues to improve; it’s best to use the latest available release in
-order to get the most complete and accurate results possible.) Note that
-<code>unicode_strings</code> is automatically chosen if you
<code>use 5.012</code><!-- /@w --> or
-higher.
-</p>
-<p>For Perls earlier than those described above, or when a string is passed
-to a function outside the scope of <code>unicode_strings</code>, see the next
section.
-</p>
-<hr>
-<a
name="perlunicode-Forcing-Unicode-in-Perl-_0028Or-Unforcing-Unicode-in-Perl_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Using-Unicode-in-XS" accesskey="n"
rel="next">perlunicode Using Unicode in XS</a>, Previous: <a
href="#perlunicode-The-_0022Unicode-Bug_0022" accesskey="p"
rel="prev">perlunicode The "Unicode Bug"</a>, Up: <a
href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Forcing-Unicode-in-Perl-_0028Or-Unforcing-Unicode-in-Perl_0029"></a>
-<h4 class="subsection">81.2.18 Forcing Unicode in Perl (Or Unforcing Unicode
in Perl)</h4>
-
-<p>Sometimes (see <a href="#perlunicode-When-Unicode-Does-Not-Happen">When
Unicode Does Not Happen</a> or <a
href="#perlunicode-The-_0022Unicode-Bug_0022">The "Unicode Bug"</a>)
-there are situations where you simply need to force a byte
-string into UTF-8, or vice versa. The standard module <a
href="Encode.html#Top">(Encode)</a> can be
-used for this, or the low-level calls
-<a
href="utf8.html#Utility-functions">(utf8)<code>utf8::upgrade($bytestring)</code></a>
and
-<a
href="utf8.html#Utility-functions">(utf8)<code>utf8::downgrade($utf8string[,
FAIL_OK])</code></a>.
-</p>
-<p>Note that <code>utf8::downgrade()</code> can fail if the string contains
characters
-that don’t fit into a byte.
-</p>
-<p>Calling either function on a string that already is in the desired state is
a
-no-op.
-</p>
-<p><a href="#perlunicode-ASCII-Rules-versus-Unicode-Rules">ASCII Rules versus
Unicode Rules</a> gives all the ways that a string is
-made to use Unicode rules.
-</p>
-<hr>
-<a name="perlunicode-Using-Unicode-in-XS"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunicode-Hacking-Perl-to-work-on-earlier-Unicode-versions-_0028for-very-serious-hackers-only_0029"
accesskey="n" rel="next">perlunicode Hacking Perl to work on earlier Unicode
versions (for very serious hackers only)</a>, Previous: <a
href="#perlunicode-Forcing-Unicode-in-Perl-_0028Or-Unforcing-Unicode-in-Perl_0029"
accesskey="p" rel="prev">perlunicode Forcing Unicode in Perl (Or Unforcing
Unicode in Perl)</a>, Up: <a href="#perlunicode-DESCRIPTION" accesskey="u"
rel="up">perlunicode DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Using-Unicode-in-XS"></a>
-<h4 class="subsection">81.2.19 Using Unicode in XS</h4>
-
-<p>See <a href="#perlguts-Unicode-Support">perlguts Unicode Support</a> for an
introduction to Unicode at
-the XS level, and <a href="perlapi.html#Unicode-Support">(perlapi)Unicode
Support</a> for the API details.
-</p>
-<hr>
-<a
name="perlunicode-Hacking-Perl-to-work-on-earlier-Unicode-versions-_0028for-very-serious-hackers-only_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Porting-code-from-perl_002d5_002e6_002eX"
accesskey="n" rel="next">perlunicode Porting code from perl-5.6.X</a>,
Previous: <a href="#perlunicode-Using-Unicode-in-XS" accesskey="p"
rel="prev">perlunicode Using Unicode in XS</a>, Up: <a
href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a
name="Hacking-Perl-to-work-on-earlier-Unicode-versions-_0028for-very-serious-hackers-only_0029"></a>
-<h4 class="subsection">81.2.20 Hacking Perl to work on earlier Unicode
versions (for very serious hackers only)</h4>
-
-<p>Perl by default comes with the latest supported Unicode version built-in,
but
-the goal is to allow you to change to use any earlier one. In Perls
-v5.20 and v5.22, however, the earliest usable version is Unicode 5.1.
-Perl v5.18 is able to handle all earlier versions.
-</p>
-<p>Download the files in the desired version of Unicode from the Unicode web
-site <a href="http://www.unicode.org";>http://www.unicode.org</a>). These
should replace the existing files in
-<samp>lib/unicore</samp> in the Perl source tree. Follow the instructions in
-<samp>README.perl</samp> in that directory to change some of their names, and
then build
-perl (see <a href="INSTALL.html#Top">(INSTALL)</a>).
-</p>
-<hr>
-<a name="perlunicode-Porting-code-from-perl_002d5_002e6_002eX"></a>
-<div class="header">
-<p>
-Previous: <a
href="#perlunicode-Hacking-Perl-to-work-on-earlier-Unicode-versions-_0028for-very-serious-hackers-only_0029"
accesskey="p" rel="prev">perlunicode Hacking Perl to work on earlier Unicode
versions (for very serious hackers only)</a>, Up: <a
href="#perlunicode-DESCRIPTION" accesskey="u" rel="up">perlunicode
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Porting-code-from-perl_002d5_002e6_002eX"></a>
-<h4 class="subsection">81.2.21 Porting code from perl-5.6.X</h4>
-
-<p>Perls starting in 5.8 have a different Unicode model from 5.6. In 5.6 the
-programmer was required to use the <code>utf8</code> pragma to declare that a
-given scope expected to deal with Unicode data and had to make sure that
-only Unicode data were reaching that scope. If you have code that is
-working with 5.6, you will need some of the following adjustments to
-your code. The examples are written such that the code will continue to
-work under 5.6, so you should be safe to try them out.
-</p>
-<ul>
-<li> A filehandle that should read or write UTF-8
-
-<pre class="verbatim"> if ($] > 5.008) {
- binmode $fh, ":encoding(utf8)";
- }
-</pre>
-</li><li> A scalar that is going to be passed to some extension
-
-<p>Be it <code>Compress::Zlib</code>, <code>Apache::Request</code> or any
extension that has no
-mention of Unicode in the manpage, you need to make sure that the
-UTF8 flag is stripped off. Note that at the time of this writing
-(January 2012) the mentioned modules are not UTF-8-aware. Please
-check the documentation to verify if this is still true.
-</p>
-<pre class="verbatim"> if ($] > 5.008) {
- require Encode;
- $val = Encode::encode_utf8($val); # make octets
- }
-</pre>
-</li><li> A scalar we got back from an extension
-
-<p>If you believe the scalar comes back as UTF-8, you will most likely
-want the UTF8 flag restored:
-</p>
-<pre class="verbatim"> if ($] > 5.008) {
- require Encode;
- $val = Encode::decode_utf8($val);
- }
-</pre>
-</li><li> Same thing, if you are really sure it is UTF-8
-
-<pre class="verbatim"> if ($] > 5.008) {
- require Encode;
- Encode::_utf8_on($val);
- }
-</pre>
-</li><li> A wrapper for <a href="DBI.html#Top">(DBI)</a>
<code>fetchrow_array</code> and <code>fetchrow_hashref</code>
-
-<p>When the database contains only UTF-8, a wrapper function or method is
-a convenient way to replace all your <code>fetchrow_array</code> and
-<code>fetchrow_hashref</code> calls. A wrapper function will also make it
easier to
-adapt to future enhancements in your database driver. Note that at the
-time of this writing (January 2012), the DBI has no standardized way
-to deal with UTF-8 data. Please check the <a href="DBI.html#Top">(DBI)DBI
documentation</a> to verify if
-that is still true.
-</p>
-<pre class="verbatim"> sub fetchrow {
- # $what is one of fetchrow_{array,hashref}
- my($self, $sth, $what) = @_;
- if ($] < 5.008) {
- return $sth->$what;
- } else {
- require Encode;
- if (wantarray) {
- my @arr = $sth->$what;
- for (@arr) {
- defined && /[^\000-\177]/ && Encode::_utf8_on($_);
- }
- return @arr;
- } else {
- my $ret = $sth->$what;
- if (ref $ret) {
- for my $k (keys %$ret) {
- defined
- && /[^\000-\177]/
- && Encode::_utf8_on($_) for $ret->{$k};
- }
- return $ret;
- } else {
- defined && /[^\000-\177]/ && Encode::_utf8_on($_)
for $ret;
- return $ret;
- }
- }
- }
- }
-</pre>
-</li><li> A large scalar that you know can only contain ASCII
-
-<p>Scalars that contain only ASCII and are marked as UTF-8 are sometimes
-a drag to your program. If you recognize such a situation, just remove
-the UTF8 flag:
-</p>
-<pre class="verbatim"> utf8::downgrade($val) if $] > 5.008;
-</pre>
-</li></ul>
-
-<hr>
-<a name="perlunicode-BUGS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-SEE-ALSO" accesskey="n" rel="next">perlunicode SEE
ALSO</a>, Previous: <a href="#perlunicode-DESCRIPTION" accesskey="p"
rel="prev">perlunicode DESCRIPTION</a>, Up: <a href="#perlunicode"
accesskey="u" rel="up">perlunicode</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="BUGS-10"></a>
-<h3 class="section">81.3 BUGS</h3>
-
-<p>See also <a href="#perlunicode-The-_0022Unicode-Bug_0022">The "Unicode
Bug"</a> above.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlunicode-Interaction-with-Extensions" accesskey="1">perlunicode
Interaction with Extensions</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunicode-Speed"
accesskey="2">perlunicode Speed</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlunicode-Interaction-with-Extensions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunicode-Speed" accesskey="n" rel="next">perlunicode
Speed</a>, Up: <a href="#perlunicode-BUGS" accesskey="u" rel="up">perlunicode
BUGS</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Interaction-with-Extensions"></a>
-<h4 class="subsection">81.3.1 Interaction with Extensions</h4>
-
-<p>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 recognize that flag, it’s likely that the
extension
-will return incorrectly-flagged data.
-</p>
-<p>So if you’re working with Unicode data, consult the documentation of
-every module you’re using if there are any issues with Unicode data
-exchange. If the documentation does not talk about Unicode at all,
-suspect the worst and probably look at the source to learn how the
-module is implemented. Modules written completely in Perl shouldn’t
-cause problems. Modules that directly or indirectly access code written
-in other programming languages are at risk.
-</p>
-<p>For affected functions, the simple strategy to avoid data corruption is
-to always make the encoding of the exchanged data explicit. Choose an
-encoding that you know the extension can handle. Convert arguments passed
-to the extensions to that encoding and convert results back from that
-encoding. Write wrapper functions that do the conversions for you, so
-you can later change the functions when the extension catches up.
-</p>
-<p>To provide an example, let’s say the popular
<code>Foo::Bar::escape_html</code>
-function doesn’t deal with Unicode data yet. The wrapper function
-would convert the argument to raw UTF-8 and convert the result back to
-Perl’s internal representation like so:
-</p>
-<pre class="verbatim"> sub my_escape_html ($) {
- my($what) = shift;
- return unless defined $what;
- Encode::decode_utf8(Foo::Bar::escape_html(
- Encode::encode_utf8($what)));
- }
-</pre>
-<p>Sometimes, when the extension does not convert data but just stores
-and retrieves it, you will be able to use the otherwise
-dangerous <a
href="Encode.html#g_t_005futf8_005fon">(Encode)<code>Encode::_utf8_on()</code></a>
function. Let’s say
-the popular <code>Foo::Bar</code> extension, written in C, provides a
<code>param</code>
-method that lets you store and retrieve data according to these prototypes:
-</p>
-<pre class="verbatim"> $self->param($name, $value); # set a
scalar
- $value = $self->param($name); # retrieve a scalar
-</pre>
-<p>If it does not yet provide support for any encoding, one could write a
-derived class with such a <code>param</code> method:
-</p>
-<pre class="verbatim"> sub param {
- my($self,$name,$value) = @_;
- utf8::upgrade($name); # make sure it is UTF-8 encoded
- if (defined $value) {
- utf8::upgrade($value); # make sure it is UTF-8 encoded
- return $self->SUPER::param($name,$value);
- } else {
- my $ret = $self->SUPER::param($name);
- Encode::_utf8_on($ret); # we know, it is UTF-8 encoded
- return $ret;
- }
- }
-</pre>
-<p>Some extensions provide filters on data entry/exit points, such as
-<code>DB_File::filter_store_key</code> and family. Look out for such filters in
-the documentation of your extensions; they can make the transition to
-Unicode data much easier.
-</p>
-<hr>
-<a name="perlunicode-Speed"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlunicode-Interaction-with-Extensions" accesskey="p"
rel="prev">perlunicode Interaction with Extensions</a>, Up: <a
href="#perlunicode-BUGS" accesskey="u" rel="up">perlunicode BUGS</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Speed"></a>
-<h4 class="subsection">81.3.2 Speed</h4>
-
-<p>Some functions are slower when working on UTF-8 encoded strings than
-on byte encoded strings. All functions that need to hop over
-characters such as <code>length()</code>, <code>substr()</code> or
<code>index()</code>, or matching
-regular expressions can work <strong>much</strong> faster when the underlying
data are
-byte-encoded.
-</p>
-<p>In Perl 5.8.0 the slowness was often quite spectacular; in Perl 5.8.1
-a caching scheme was introduced which improved the situation. In general,
-operations with UTF-8 encoded strings are still slower. As an example,
-the Unicode properties (character classes) like <code>\p{Nd}</code> are known
to
-be quite a bit slower (5-20 times) than their simpler counterparts
-like <code>[0-9]</code> (then again, there are hundreds of Unicode characters
matching
-<code>Nd</code> compared with the 10 ASCII characters matching
<code>[0-9]</code>).
-</p>
-<hr>
-<a name="perlunicode-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlunicode-BUGS" accesskey="p" rel="prev">perlunicode
BUGS</a>, Up: <a href="#perlunicode" accesskey="u" rel="up">perlunicode</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-40"></a>
-<h3 class="section">81.4 SEE ALSO</h3>
-
-<p><a href="#perlunitut-NAME">perlunitut NAME</a>, <a
href="#perluniintro-NAME">perluniintro NAME</a>, <a
href="perluniprops.html#Top">(perluniprops)</a>, <a
href="Encode.html#Top">(Encode)</a>, <a href="open.html#Top">(open)</a>, <a
href="utf8.html#Top">(utf8)</a>, <a href="bytes.html#Top">(bytes)</a>,
-<a href="#perlretut-NAME">perlretut NAME</a>, <a
href="#perlvar-_0024_007b_005eUNICODE_007d">perlvar ${^UNICODE}</a>,
-<a
href="http://www.unicode.org/reports/tr44";>http://www.unicode.org/reports/tr44</a>).
-</p>
-<hr>
-<a name="perlunifaq"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro" accesskey="n" rel="next">perluniintro</a>,
Previous: <a href="#perlunicode" accesskey="p" rel="prev">perlunicode</a>, Up:
<a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlunifaq-1"></a>
-<h2 class="chapter">82 perlunifaq</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlunifaq-NAME"
accesskey="1">perlunifaq NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunifaq-Q-and-A"
accesskey="2">perlunifaq Q and A</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunifaq-INTERNALS"
accesskey="3">perlunifaq INTERNALS</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunifaq-AUTHOR"
accesskey="4">perlunifaq AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunifaq-SEE-ALSO"
accesskey="5">perlunifaq SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlunifaq-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-Q-and-A" accesskey="n" rel="next">perlunifaq Q and
A</a>, Up: <a href="#perlunifaq" accesskey="u" rel="up">perlunifaq</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-81"></a>
-<h3 class="section">82.1 NAME</h3>
-
-<p>perlunifaq - Perl Unicode FAQ
-</p>
-<hr>
-<a name="perlunifaq-Q-and-A"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-INTERNALS" accesskey="n" rel="next">perlunifaq
INTERNALS</a>, Previous: <a href="#perlunifaq-NAME" accesskey="p"
rel="prev">perlunifaq NAME</a>, Up: <a href="#perlunifaq" accesskey="u"
rel="up">perlunifaq</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Q-and-A"></a>
-<h3 class="section">82.2 Q and A</h3>
-
-<p>This is a list of questions and answers about Unicode in Perl, intended to
be
-read after <a href="#perlunitut-NAME">perlunitut NAME</a>.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-perlunitut-isn_0027t-really-a-Unicode-tutorial_002c-is-it_003f"
accesskey="1">perlunifaq perlunitut isn't really a Unicode tutorial, is
it?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-character-encodings-does-Perl-support_003f"
accesskey="2">perlunifaq What character encodings does Perl
support?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-Which-version-of-perl-should-I-use_003f"
accesskey="3">perlunifaq Which version of perl should I
use?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-about-binary-data_002c-like-images_003f"
accesskey="4">perlunifaq What about binary data, like
images?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-When-should-I-decode-or-encode_003f" accesskey="5">perlunifaq
When should I decode or encode?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-if-I-don_0027t-decode_003f" accesskey="6">perlunifaq
What if I don't decode?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-if-I-don_0027t-encode_003f" accesskey="7">perlunifaq
What if I don't encode?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-Is-there-a-way-to-automatically-decode-or-encode_003f"
accesskey="8">perlunifaq Is there a way to automatically decode or
encode?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-if-I-don_0027t-know-which-encoding-was-used_003f"
accesskey="9">perlunifaq What if I don't know which encoding was
used?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-Can-I-use-Unicode-in-my-Perl-sources_003f">perlunifaq Can I
use Unicode in my Perl sources?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-Data_003a_003aDumper-doesn_0027t-restore-the-UTF8-flag_003b-is-it-broken_003f">perlunifaq
Data::Dumper doesn't restore the UTF8 flag; is it
broken?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-Why-do-regex-character-classes-sometimes-match-only-in-the-ASCII-range_003f">perlunifaq
Why do regex character classes sometimes match only in the ASCII
range?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-Why-do-some-characters-not-uppercase-or-lowercase-correctly_003f">perlunifaq
Why do some characters not uppercase or lowercase
correctly?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-How-can-I-determine-if-a-string-is-a-text-string-or-a-binary-string_003f">perlunifaq
How can I determine if a string is a text string or a binary
string?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-How-do-I-convert-from-encoding-FOO-to-encoding-BAR_003f">perlunifaq
How do I convert from encoding FOO to encoding
BAR?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-are-decode_005futf8-and-encode_005futf8_003f">perlunifaq
What are <code>decode_utf8</code> and
<code>encode_utf8</code>?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-is-a-_0022wide-character_0022_003f">perlunifaq What is a
"wide character"?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a
name="perlunifaq-perlunitut-isn_0027t-really-a-Unicode-tutorial_002c-is-it_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-What-character-encodings-does-Perl-support_003f"
accesskey="n" rel="next">perlunifaq What character encodings does Perl
support?</a>, Up: <a href="#perlunifaq-Q-and-A" accesskey="u"
rel="up">perlunifaq Q and A</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlunitut-isn_0027t-really-a-Unicode-tutorial_002c-is-it_003f"></a>
-<h4 class="subsection">82.2.1 perlunitut isn’t really a Unicode
tutorial, is it?</h4>
-
-<p>No, and this isn’t really a Unicode FAQ.
-</p>
-<p>Perl has an abstracted interface for all supported character encodings, so
this
-is actually a generic <code>Encode</code> tutorial and <code>Encode</code>
FAQ. But many people
-think that Unicode is special and magical, and I didn’t want to
disappoint
-them, so I decided to call the document a Unicode tutorial.
-</p>
-<hr>
-<a name="perlunifaq-What-character-encodings-does-Perl-support_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-Which-version-of-perl-should-I-use_003f"
accesskey="n" rel="next">perlunifaq Which version of perl should I use?</a>,
Previous: <a
href="#perlunifaq-perlunitut-isn_0027t-really-a-Unicode-tutorial_002c-is-it_003f"
accesskey="p" rel="prev">perlunifaq perlunitut isn't really a Unicode
tutorial, is it?</a>, Up: <a href="#perlunifaq-Q-and-A" accesskey="u"
rel="up">perlunifaq Q and A</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="What-character-encodings-does-Perl-support_003f"></a>
-<h4 class="subsection">82.2.2 What character encodings does Perl support?</h4>
-
-<p>To find out which character encodings your Perl supports, run:
-</p>
-<pre class="verbatim"> perl -MEncode -le "print for
Encode->encodings(':all')"
-</pre>
-<hr>
-<a name="perlunifaq-Which-version-of-perl-should-I-use_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-What-about-binary-data_002c-like-images_003f"
accesskey="n" rel="next">perlunifaq What about binary data, like images?</a>,
Previous: <a href="#perlunifaq-What-character-encodings-does-Perl-support_003f"
accesskey="p" rel="prev">perlunifaq What character encodings does Perl
support?</a>, Up: <a href="#perlunifaq-Q-and-A" accesskey="u"
rel="up">perlunifaq Q and A</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Which-version-of-perl-should-I-use_003f"></a>
-<h4 class="subsection">82.2.3 Which version of perl should I use?</h4>
-
-<p>Well, if you can, upgrade to the most recent, but certainly
<code>5.8.1</code> or newer.
-The tutorial and FAQ assume the latest release.
-</p>
-<p>You should also check your modules, and upgrade them if necessary. For
example,
-HTML::Entities requires version >= 1.32 to function correctly, even though
the
-changelog is silent about this.
-</p>
-<hr>
-<a name="perlunifaq-What-about-binary-data_002c-like-images_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-When-should-I-decode-or-encode_003f" accesskey="n"
rel="next">perlunifaq When should I decode or encode?</a>, Previous: <a
href="#perlunifaq-Which-version-of-perl-should-I-use_003f" accesskey="p"
rel="prev">perlunifaq Which version of perl should I use?</a>, Up: <a
href="#perlunifaq-Q-and-A" accesskey="u" rel="up">perlunifaq Q and A</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="What-about-binary-data_002c-like-images_003f"></a>
-<h4 class="subsection">82.2.4 What about binary data, like images?</h4>
-
-<p>Well, apart from a bare <code>binmode $fh</code>, you shouldn’t treat
them specially.
-(The binmode is needed because otherwise Perl may convert line endings on Win32
-systems.)
-</p>
-<p>Be careful, though, to never combine text strings with binary strings. If
you
-need text in a binary stream, encode your text strings first using the
-appropriate encoding, then join them with binary strings. See also: "What
if I
-don’t encode?".
-</p>
-<hr>
-<a name="perlunifaq-When-should-I-decode-or-encode_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-What-if-I-don_0027t-decode_003f" accesskey="n"
rel="next">perlunifaq What if I don't decode?</a>, Previous: <a
href="#perlunifaq-What-about-binary-data_002c-like-images_003f" accesskey="p"
rel="prev">perlunifaq What about binary data, like images?</a>, Up: <a
href="#perlunifaq-Q-and-A" accesskey="u" rel="up">perlunifaq Q and A</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="When-should-I-decode-or-encode_003f"></a>
-<h4 class="subsection">82.2.5 When should I decode or encode?</h4>
-
-<p>Whenever you’re communicating text with anything that is external to
your perl
-process, like a database, a text file, a socket, or another program. Even if
-the thing you’re communicating with is also written in Perl.
-</p>
-<hr>
-<a name="perlunifaq-What-if-I-don_0027t-decode_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-What-if-I-don_0027t-encode_003f" accesskey="n"
rel="next">perlunifaq What if I don't encode?</a>, Previous: <a
href="#perlunifaq-When-should-I-decode-or-encode_003f" accesskey="p"
rel="prev">perlunifaq When should I decode or encode?</a>, Up: <a
href="#perlunifaq-Q-and-A" accesskey="u" rel="up">perlunifaq Q and A</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="What-if-I-don_0027t-decode_003f"></a>
-<h4 class="subsection">82.2.6 What if I don’t decode?</h4>
-
-<p>Whenever your encoded, binary string is used together with a text string,
Perl
-will assume that your binary string was encoded with ISO-8859-1, also known as
-latin-1. If it wasn’t latin-1, then your data is unpleasantly converted.
For
-example, if it was UTF-8, the individual bytes of multibyte characters are seen
-as separate characters, and then again converted to UTF-8. Such double encoding
-can be compared to double HTML encoding (<code>&amp;gt;</code>), or double
URI encoding
-(<code>%253E</code>).
-</p>
-<p>This silent implicit decoding is known as "upgrading". That may
sound
-positive, but it’s best to avoid it.
-</p>
-<hr>
-<a name="perlunifaq-What-if-I-don_0027t-encode_003f"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunifaq-Is-there-a-way-to-automatically-decode-or-encode_003f"
accesskey="n" rel="next">perlunifaq Is there a way to automatically decode or
encode?</a>, Previous: <a href="#perlunifaq-What-if-I-don_0027t-decode_003f"
accesskey="p" rel="prev">perlunifaq What if I don't decode?</a>, Up: <a
href="#perlunifaq-Q-and-A" accesskey="u" rel="up">perlunifaq Q and A</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="What-if-I-don_0027t-encode_003f"></a>
-<h4 class="subsection">82.2.7 What if I don’t encode?</h4>
-
-<p>Your text string will be sent using the bytes in Perl’s internal
format. In
-some cases, Perl will warn you that you’re doing something wrong, with a
-friendly warning:
-</p>
-<pre class="verbatim"> Wide character in print at example.pl line 2.
-</pre>
-<p>Because the internal format is often UTF-8, these bugs are hard to spot,
-because UTF-8 is usually the encoding you wanted! But don’t be lazy, and
don’t
-use the fact that Perl’s internal format is UTF-8 to your advantage.
Encode
-explicitly to avoid weird bugs, and to show to maintenance programmers that you
-thought this through.
-</p>
-<hr>
-<a name="perlunifaq-Is-there-a-way-to-automatically-decode-or-encode_003f"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunifaq-What-if-I-don_0027t-know-which-encoding-was-used_003f"
accesskey="n" rel="next">perlunifaq What if I don't know which encoding was
used?</a>, Previous: <a href="#perlunifaq-What-if-I-don_0027t-encode_003f"
accesskey="p" rel="prev">perlunifaq What if I don't encode?</a>, Up: <a
href="#perlunifaq-Q-and-A" accesskey="u" rel="up">perlunifaq Q and A</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Is-there-a-way-to-automatically-decode-or-encode_003f"></a>
-<h4 class="subsection">82.2.8 Is there a way to automatically decode or
encode?</h4>
-
-<p>If all data that comes from a certain handle is encoded in exactly the same
-way, you can tell the PerlIO system to automatically decode everything, with
-the <code>encoding</code> layer. If you do this, you can’t accidentally
forget to decode
-or encode anymore, on things that use the layered handle.
-</p>
-<p>You can provide this layer when <code>open</code>ing the file:
-</p>
-<pre class="verbatim"> open my $fh, '>:encoding(UTF-8)', $filename; #
auto encoding on write
- open my $fh, '<:encoding(UTF-8)', $filename; # auto decoding on read
-</pre>
-<p>Or if you already have an open filehandle:
-</p>
-<pre class="verbatim"> binmode $fh, ':encoding(UTF-8)';
-</pre>
-<p>Some database drivers for DBI can also automatically encode and decode, but
-that is sometimes limited to the UTF-8 encoding.
-</p>
-<hr>
-<a name="perlunifaq-What-if-I-don_0027t-know-which-encoding-was-used_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-Can-I-use-Unicode-in-my-Perl-sources_003f"
accesskey="n" rel="next">perlunifaq Can I use Unicode in my Perl sources?</a>,
Previous: <a
href="#perlunifaq-Is-there-a-way-to-automatically-decode-or-encode_003f"
accesskey="p" rel="prev">perlunifaq Is there a way to automatically decode or
encode?</a>, Up: <a href="#perlunifaq-Q-and-A" accesskey="u"
rel="up">perlunifaq Q and A</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="What-if-I-don_0027t-know-which-encoding-was-used_003f"></a>
-<h4 class="subsection">82.2.9 What if I don’t know which encoding was
used?</h4>
-
-<p>Do whatever you can to find out, and if you have to: guess. (Don’t
forget to
-document your guess with a comment.)
-</p>
-<p>You could open the document in a web browser, and change the character set
or
-character encoding until you can visually confirm that all characters look the
-way they should.
-</p>
-<p>There is no way to reliably detect the encoding automatically, so if people
-keep sending you data without charset indication, you may have to educate them.
-</p>
-<hr>
-<a name="perlunifaq-Can-I-use-Unicode-in-my-Perl-sources_003f"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunifaq-Data_003a_003aDumper-doesn_0027t-restore-the-UTF8-flag_003b-is-it-broken_003f"
accesskey="n" rel="next">perlunifaq Data::Dumper doesn't restore the UTF8
flag; is it broken?</a>, Previous: <a
href="#perlunifaq-What-if-I-don_0027t-know-which-encoding-was-used_003f"
accesskey="p" rel="prev">perlunifaq What if I don't know which encoding was
used?</a>, Up: <a href="#perlunifaq-Q-and-A" accesskey="u" rel="up">perlunifaq
Q and A</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Can-I-use-Unicode-in-my-Perl-sources_003f"></a>
-<h4 class="subsection">82.2.10 Can I use Unicode in my Perl sources?</h4>
-
-<p>Yes, you can! If your sources are UTF-8 encoded, you can indicate that with
the
-<code>use utf8</code> pragma.
-</p>
-<pre class="verbatim"> use utf8;
-</pre>
-<p>This doesn’t do anything to your input, or to your output. It only
influences
-the way your sources are read. You can use Unicode in string literals, in
-identifiers (but they still have to be "word characters" according
to <code>\w</code>),
-and even in custom delimiters.
-</p>
-<hr>
-<a
name="perlunifaq-Data_003a_003aDumper-doesn_0027t-restore-the-UTF8-flag_003b-is-it-broken_003f"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunifaq-Why-do-regex-character-classes-sometimes-match-only-in-the-ASCII-range_003f"
accesskey="n" rel="next">perlunifaq Why do regex character classes sometimes
match only in the ASCII range?</a>, Previous: <a
href="#perlunifaq-Can-I-use-Unicode-in-my-Perl-sources_003f" accesskey="p"
rel="prev">perlunifaq Can I use Unicode in my Perl sources?</a>, Up: <a
href="#perlunifaq-Q-and-A" accesskey="u" rel="up">perlunifaq Q and A</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a
name="Data_003a_003aDumper-doesn_0027t-restore-the-UTF8-flag_003b-is-it-broken_003f"></a>
-<h4 class="subsection">82.2.11 Data::Dumper doesn’t restore the UTF8
flag; is it broken?</h4>
-
-<p>No, Data::Dumper’s Unicode abilities are as they should be. There
have been
-some complaints that it should restore the UTF8 flag when the data is read
-again with <code>eval</code>. However, you should really not look at the flag,
and
-nothing indicates that Data::Dumper should break this rule.
-</p>
-<p>Here’s what happens: when Perl reads in a string literal, it sticks
to 8 bit
-encoding as long as it can. (But perhaps originally it was internally encoded
-as UTF-8, when you dumped it.) When it has to give that up because other
-characters are added to the text string, it silently upgrades the string to
-UTF-8.
-</p>
-<p>If you properly encode your strings for output, none of this is of your
-concern, and you can just <code>eval</code> dumped data as always.
-</p>
-<hr>
-<a
name="perlunifaq-Why-do-regex-character-classes-sometimes-match-only-in-the-ASCII-range_003f"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunifaq-Why-do-some-characters-not-uppercase-or-lowercase-correctly_003f"
accesskey="n" rel="next">perlunifaq Why do some characters not uppercase or
lowercase correctly?</a>, Previous: <a
href="#perlunifaq-Data_003a_003aDumper-doesn_0027t-restore-the-UTF8-flag_003b-is-it-broken_003f"
accesskey="p" rel="prev">perlunifaq Data::Dumper doesn't restore the UTF8
flag; is it broken?</a>, Up: <a href="#perlunifaq-Q-and-A" accesskey="u"
rel="up">perlunifaq Q and A</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a
name="Why-do-regex-character-classes-sometimes-match-only-in-the-ASCII-range_003f"></a>
-<h4 class="subsection">82.2.12 Why do regex character classes sometimes match
only in the ASCII range?</h4>
-
-<p>Starting in Perl 5.14 (and partially in Perl 5.12), just put a
-<code>use feature 'unicode_strings'</code> near the beginning of your program.
-Within its lexical scope you shouldn’t have this problem. It also is
-automatically enabled under <code>use feature ':5.12'</code> or <code>use
v5.12</code> or
-using <code>-E</code> on the command line for Perl 5.12 or higher.
-</p>
-<p>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
-is wanted, and so those characters that are not ASCII
-characters aren’t recognized as to what they would be in Unicode.
-<code>use feature 'unicode_strings'</code> tells Perl to treat all characters
as
-Unicode, whether the string is encoded in UTF-8 or not, thus avoiding
-the problem.
-</p>
-<p>However, on earlier Perls, or if you pass strings to subroutines outside
-the feature’s scope, you can force Unicode rules by changing the
-encoding to UTF-8 by doing <code>utf8::upgrade($string)</code>. This can be
used
-safely on any string, as it checks and does not change strings that have
-already been upgraded.
-</p>
-<p>For a more detailed discussion, see <a
href="Unicode-Semantics.html#Top">(Unicode-Semantics)</a> on CPAN.
-</p>
-<hr>
-<a
name="perlunifaq-Why-do-some-characters-not-uppercase-or-lowercase-correctly_003f"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunifaq-How-can-I-determine-if-a-string-is-a-text-string-or-a-binary-string_003f"
accesskey="n" rel="next">perlunifaq How can I determine if a string is a text
string or a binary string?</a>, Previous: <a
href="#perlunifaq-Why-do-regex-character-classes-sometimes-match-only-in-the-ASCII-range_003f"
accesskey="p" rel="prev">perlunifaq Why do regex character classes sometimes
match only in the ASCII range?</a>, Up: <a href="#perlunifaq-Q-and-A"
accesskey="u" rel="up">perlunifaq Q and A</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Why-do-some-characters-not-uppercase-or-lowercase-correctly_003f"></a>
-<h4 class="subsection">82.2.13 Why do some characters not uppercase or
lowercase correctly?</h4>
-
-<p>See the answer to the previous question.
-</p>
-<hr>
-<a
name="perlunifaq-How-can-I-determine-if-a-string-is-a-text-string-or-a-binary-string_003f"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunifaq-How-do-I-convert-from-encoding-FOO-to-encoding-BAR_003f"
accesskey="n" rel="next">perlunifaq How do I convert from encoding FOO to
encoding BAR?</a>, Previous: <a
href="#perlunifaq-Why-do-some-characters-not-uppercase-or-lowercase-correctly_003f"
accesskey="p" rel="prev">perlunifaq Why do some characters not uppercase or
lowercase correctly?</a>, Up: <a href="#perlunifaq-Q-and-A" accesskey="u"
rel="up">perlunifaq Q and A</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a
name="How-can-I-determine-if-a-string-is-a-text-string-or-a-binary-string_003f"></a>
-<h4 class="subsection">82.2.14 How can I determine if a string is a text
string or a binary string?</h4>
-
-<p>You can’t. Some use the UTF8 flag for this, but that’s misuse,
and makes well
-behaved modules like Data::Dumper look bad. The flag is useless for this
-purpose, because it’s off when an 8 bit encoding (by default ISO-8859-1)
is
-used to store the string.
-</p>
-<p>This is something you, the programmer, has to keep track of; sorry. You
could
-consider adopting a kind of "Hungarian notation" to help with this.
-</p>
-<hr>
-<a
name="perlunifaq-How-do-I-convert-from-encoding-FOO-to-encoding-BAR_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-What-are-decode_005futf8-and-encode_005futf8_003f"
accesskey="n" rel="next">perlunifaq What are <code>decode_utf8</code> and
<code>encode_utf8</code>?</a>, Previous: <a
href="#perlunifaq-How-can-I-determine-if-a-string-is-a-text-string-or-a-binary-string_003f"
accesskey="p" rel="prev">perlunifaq How can I determine if a string is a text
string or a binary string?</a>, Up: <a href="#perlunifaq-Q-and-A" accesskey="u"
rel="up">perlunifaq Q and A</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="How-do-I-convert-from-encoding-FOO-to-encoding-BAR_003f"></a>
-<h4 class="subsection">82.2.15 How do I convert from encoding FOO to encoding
BAR?</h4>
-
-<p>By first converting the FOO-encoded byte string to a text string, and then
the
-text string to a BAR-encoded byte string:
-</p>
-<pre class="verbatim"> my $text_string = decode('FOO', $foo_string);
- my $bar_string = encode('BAR', $text_string);
-</pre>
-<p>or by skipping the text string part, and going directly from one binary
-encoding to the other:
-</p>
-<pre class="verbatim"> use Encode qw(from_to);
- from_to($string, 'FOO', 'BAR'); # changes contents of $string
-</pre>
-<p>or by letting automatic decoding and encoding do all the work:
-</p>
-<pre class="verbatim"> open my $foofh, '<:encoding(FOO)',
'example.foo.txt';
- open my $barfh, '>:encoding(BAR)', 'example.bar.txt';
- print { $barfh } $_ while <$foofh>;
-</pre>
-<hr>
-<a name="perlunifaq-What-are-decode_005futf8-and-encode_005futf8_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-What-is-a-_0022wide-character_0022_003f"
accesskey="n" rel="next">perlunifaq What is a "wide character"?</a>,
Previous: <a
href="#perlunifaq-How-do-I-convert-from-encoding-FOO-to-encoding-BAR_003f"
accesskey="p" rel="prev">perlunifaq How do I convert from encoding FOO to
encoding BAR?</a>, Up: <a href="#perlunifaq-Q-and-A" accesskey="u"
rel="up">perlunifaq Q and A</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="What-are-decode_005futf8-and-encode_005futf8_003f"></a>
-<h4 class="subsection">82.2.16 What are <code>decode_utf8</code> and
<code>encode_utf8</code>?</h4>
-
-<p>These are alternate syntaxes for <code>decode('utf8', ...)</code> and
<code>encode('utf8',
-...)</code>.
-</p>
-<hr>
-<a name="perlunifaq-What-is-a-_0022wide-character_0022_003f"></a>
-<div class="header">
-<p>
-Previous: <a
href="#perlunifaq-What-are-decode_005futf8-and-encode_005futf8_003f"
accesskey="p" rel="prev">perlunifaq What are <code>decode_utf8</code> and
<code>encode_utf8</code>?</a>, Up: <a href="#perlunifaq-Q-and-A" accesskey="u"
rel="up">perlunifaq Q and A</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="What-is-a-_0022wide-character_0022_003f"></a>
-<h4 class="subsection">82.2.17 What is a "wide character"?</h4>
-
-<p>This is a term used for characters occupying more than one byte.
-</p>
-<p>The Perl warning "Wide character in ..." is caused by such a
character.
-With no specified encoding layer, Perl tries to
-fit things into a single byte. When it can’t, it
-emits this warning (if warnings are enabled), and uses UTF-8 encoded data
-instead.
-</p>
-<p>To avoid this warning and to avoid having different output encodings in a
single
-stream, always specify an encoding explicitly, for example with a PerlIO layer:
-</p>
-<pre class="verbatim"> binmode STDOUT, ":encoding(UTF-8)";
-</pre>
-<hr>
-<a name="perlunifaq-INTERNALS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-AUTHOR" accesskey="n" rel="next">perlunifaq
AUTHOR</a>, Previous: <a href="#perlunifaq-Q-and-A" accesskey="p"
rel="prev">perlunifaq Q and A</a>, Up: <a href="#perlunifaq" accesskey="u"
rel="up">perlunifaq</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="INTERNALS"></a>
-<h3 class="section">82.3 INTERNALS</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-is-_0022the-UTF8-flag_0022_003f"
accesskey="1">perlunifaq What is "the UTF8
flag"?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-about-the-use-bytes-pragma_003f"
accesskey="2">perlunifaq What about the <code>use bytes</code>
pragma?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-about-the-use-encoding-pragma_003f"
accesskey="3">perlunifaq What about the <code>use encoding</code>
pragma?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What-is-the-difference-between-_003aencoding-and-_003autf8_003f"
accesskey="4">perlunifaq What is the difference between <code>:encoding</code>
and <code>:utf8</code>?</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-What_0027s-the-difference-between-UTF_002d8-and-utf8_003f"
accesskey="5">perlunifaq What's the difference between <code>UTF-8</code> and
<code>utf8</code>?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunifaq-I-lost-track_003b-what-encoding-is-the-internal-format-really_003f"
accesskey="6">perlunifaq I lost track; what encoding is the internal format
really?</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlunifaq-What-is-_0022the-UTF8-flag_0022_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-What-about-the-use-bytes-pragma_003f" accesskey="n"
rel="next">perlunifaq What about the <code>use bytes</code> pragma?</a>, Up: <a
href="#perlunifaq-INTERNALS" accesskey="u" rel="up">perlunifaq INTERNALS</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="What-is-_0022the-UTF8-flag_0022_003f"></a>
-<h4 class="subsection">82.3.1 What is "the UTF8 flag"?</h4>
-
-<p>Please, unless you’re hacking the internals, or debugging weirdness,
don’t
-think about the UTF8 flag at all. That means that you very probably
shouldn’t
-use <code>is_utf8</code>, <code>_utf8_on</code> or <code>_utf8_off</code> at
all.
-</p>
-<p>The UTF8 flag, also called SvUTF8, is an internal flag that indicates that
the
-current internal representation is UTF-8. Without the flag, it is assumed to be
-ISO-8859-1. Perl converts between these automatically. (Actually Perl usually
-assumes the representation is ASCII; see <a
href="#perlunifaq-Why-do-regex-character-classes-sometimes-match-only-in-the-ASCII-range_003f">Why
do regex character classes
-sometimes match only in the ASCII range?</a> above.)
-</p>
-<p>One of Perl’s internal formats happens to be UTF-8. Unfortunately,
Perl can’t
-keep a secret, so everyone knows about this. That is the source of much
-confusion. It’s better to pretend that the internal format is some
unknown
-encoding, and that you always have to encode and decode explicitly.
-</p>
-<hr>
-<a name="perlunifaq-What-about-the-use-bytes-pragma_003f"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-What-about-the-use-encoding-pragma_003f"
accesskey="n" rel="next">perlunifaq What about the <code>use encoding</code>
pragma?</a>, Previous: <a
href="#perlunifaq-What-is-_0022the-UTF8-flag_0022_003f" accesskey="p"
rel="prev">perlunifaq What is "the UTF8 flag"?</a>, Up: <a
href="#perlunifaq-INTERNALS" accesskey="u" rel="up">perlunifaq INTERNALS</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="What-about-the-use-bytes-pragma_003f"></a>
-<h4 class="subsection">82.3.2 What about the <code>use bytes</code>
pragma?</h4>
-
-<p>Don’t use it. It makes no sense to deal with bytes in a text string,
and it
-makes no sense to deal with characters in a byte string. Do the proper
-conversions (by decoding/encoding), and things will work out well: you get
-character counts for decoded data, and byte counts for encoded data.
-</p>
-<p><code>use bytes</code> is usually a failed attempt to do something useful.
Just forget
-about it.
-</p>
-<hr>
-<a name="perlunifaq-What-about-the-use-encoding-pragma_003f"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunifaq-What-is-the-difference-between-_003aencoding-and-_003autf8_003f"
accesskey="n" rel="next">perlunifaq What is the difference between
<code>:encoding</code> and <code>:utf8</code>?</a>, Previous: <a
href="#perlunifaq-What-about-the-use-bytes-pragma_003f" accesskey="p"
rel="prev">perlunifaq What about the <code>use bytes</code> pragma?</a>, Up: <a
href="#perlunifaq-INTERNALS" accesskey="u" rel="up">perlunifaq INTERNALS</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="What-about-the-use-encoding-pragma_003f"></a>
-<h4 class="subsection">82.3.3 What about the <code>use encoding</code>
pragma?</h4>
-
-<p>Don’t use it. Unfortunately, it assumes that the programmer’s
environment and
-that of the user will use the same encoding. It will use the same encoding for
-the source code and for STDIN and STDOUT. When a program is copied to another
-machine, the source code does not change, but the STDIO environment might.
-</p>
-<p>If you need non-ASCII characters in your source code, make it a UTF-8
encoded
-file and <code>use utf8</code>.
-</p>
-<p>If you need to set the encoding for STDIN, STDOUT, and STDERR, for example
-based on the user’s locale, <code>use open</code>.
-</p>
-<hr>
-<a
name="perlunifaq-What-is-the-difference-between-_003aencoding-and-_003autf8_003f"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunifaq-What_0027s-the-difference-between-UTF_002d8-and-utf8_003f"
accesskey="n" rel="next">perlunifaq What's the difference between
<code>UTF-8</code> and <code>utf8</code>?</a>, Previous: <a
href="#perlunifaq-What-about-the-use-encoding-pragma_003f" accesskey="p"
rel="prev">perlunifaq What about the <code>use encoding</code> pragma?</a>, Up:
<a href="#perlunifaq-INTERNALS" accesskey="u" rel="up">perlunifaq INTERNALS</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="What-is-the-difference-between-_003aencoding-and-_003autf8_003f"></a>
-<h4 class="subsection">82.3.4 What is the difference between
<code>:encoding</code> and <code>:utf8</code>?</h4>
-
-<p>Because UTF-8 is one of Perl’s internal formats, you can often just
skip the
-encoding or decoding step, and manipulate the UTF8 flag directly.
-</p>
-<p>Instead of <code>:encoding(UTF-8)</code>, you can simply use
<code>:utf8</code>, which skips the
-encoding step if the data was already represented as UTF8 internally. This is
-widely accepted as good behavior when you’re writing, but it can be
dangerous
-when reading, because it causes internal inconsistency when you have invalid
-byte sequences. Using <code>:utf8</code> for input can sometimes result in
security
-breaches, so please use <code>:encoding(UTF-8)</code> instead.
-</p>
-<p>Instead of <code>decode</code> and <code>encode</code>, you could use
<code>_utf8_on</code> and <code>_utf8_off</code>,
-but this is considered bad style. Especially <code>_utf8_on</code> can be
dangerous, for
-the same reason that <code>:utf8</code> can.
-</p>
-<p>There are some shortcuts for oneliners;
-see <a href="#perlrun-_002dC-_005bnumber_002flist_005d">-C</a> in <a
href="#perlrun-NAME">perlrun NAME</a>.
-</p>
-<hr>
-<a
name="perlunifaq-What_0027s-the-difference-between-UTF_002d8-and-utf8_003f"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunifaq-I-lost-track_003b-what-encoding-is-the-internal-format-really_003f"
accesskey="n" rel="next">perlunifaq I lost track; what encoding is the
internal format really?</a>, Previous: <a
href="#perlunifaq-What-is-the-difference-between-_003aencoding-and-_003autf8_003f"
accesskey="p" rel="prev">perlunifaq What is the difference between
<code>:encoding</code> and <code>:utf8</code>?</a>, Up: <a
href="#perlunifaq-INTERNALS" accesskey="u" rel="up">perlunifaq INTERNALS</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="What_0027s-the-difference-between-UTF_002d8-and-utf8_003f"></a>
-<h4 class="subsection">82.3.5 What’s the difference between
<code>UTF-8</code> and <code>utf8</code>?</h4>
-
-<p><code>UTF-8</code> is the official standard. <code>utf8</code> is
Perl’s way of being liberal in
-what it accepts. If you have to communicate with things that aren’t so
liberal,
-you may want to consider using <code>UTF-8</code>. If you have to communicate
with things
-that are too liberal, you may have to use <code>utf8</code>. The full
explanation is in
-<a href="Encode.html#Top">(Encode)</a>.
-</p>
-<p><code>UTF-8</code> is internally known as <code>utf-8-strict</code>. The
tutorial uses UTF-8
-consistently, even where utf8 is actually used internally, because the
-distinction can be hard to make, and is mostly irrelevant.
-</p>
-<p>For example, utf8 can be used for code points that don’t exist in
Unicode, like
-9999999, but if you encode that to UTF-8, you get a substitution character (by
-default; see <a href="Encode.html#Handling-Malformed-Data">(Encode)Handling
Malformed Data</a> for more ways of dealing with
-this.)
-</p>
-<p>Okay, if you insist: the "internal format" is utf8, not UTF-8.
(When it’s not
-some other encoding.)
-</p>
-<hr>
-<a
name="perlunifaq-I-lost-track_003b-what-encoding-is-the-internal-format-really_003f"></a>
-<div class="header">
-<p>
-Previous: <a
href="#perlunifaq-What_0027s-the-difference-between-UTF_002d8-and-utf8_003f"
accesskey="p" rel="prev">perlunifaq What's the difference between
<code>UTF-8</code> and <code>utf8</code>?</a>, Up: <a
href="#perlunifaq-INTERNALS" accesskey="u" rel="up">perlunifaq INTERNALS</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a
name="I-lost-track_003b-what-encoding-is-the-internal-format-really_003f"></a>
-<h4 class="subsection">82.3.6 I lost track; what encoding is the internal
format really?</h4>
-
-<p>It’s good that you lost track, because you shouldn’t depend on
the internal
-format being any specific encoding. But since you asked: by default, the
-internal format is either ISO-8859-1 (latin-1), or utf8, depending on the
-history of the string. On EBCDIC platforms, this may be different even.
-</p>
-<p>Perl knows how it stored the string internally, and will use that knowledge
-when you <code>encode</code>. In other words: don’t try to find out what
the internal
-encoding for a certain string is, but instead just encode it into the encoding
-that you want.
-</p>
-<hr>
-<a name="perlunifaq-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunifaq-SEE-ALSO" accesskey="n" rel="next">perlunifaq SEE
ALSO</a>, Previous: <a href="#perlunifaq-INTERNALS" accesskey="p"
rel="prev">perlunifaq INTERNALS</a>, Up: <a href="#perlunifaq" accesskey="u"
rel="up">perlunifaq</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-29"></a>
-<h3 class="section">82.4 AUTHOR</h3>
-
-<p>Juerd Waalboer <address@hidden>
-</p>
-<hr>
-<a name="perlunifaq-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlunifaq-AUTHOR" accesskey="p" rel="prev">perlunifaq
AUTHOR</a>, Up: <a href="#perlunifaq" accesskey="u" rel="up">perlunifaq</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-41"></a>
-<h3 class="section">82.5 SEE ALSO</h3>
-
-<p><a href="#perlunicode-NAME">perlunicode NAME</a>, <a
href="#perluniintro-NAME">perluniintro NAME</a>, <a
href="Encode.html#Top">(Encode)</a>
-</p>
-<hr>
-<a name="perluniintro"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunitut" accesskey="n" rel="next">perlunitut</a>, Previous:
<a href="#perlunifaq" accesskey="p" rel="prev">perlunifaq</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perluniintro-1"></a>
-<h2 class="chapter">83 perluniintro</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perluniintro-NAME"
accesskey="1">perluniintro NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perluniintro-DESCRIPTION"
accesskey="2">perluniintro DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-UNICODE-IN-OLDER-PERLS" accesskey="3">perluniintro UNICODE
IN OLDER PERLS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perluniintro-SEE-ALSO"
accesskey="4">perluniintro SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-ACKNOWLEDGMENTS" accesskey="5">perluniintro
ACKNOWLEDGMENTS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-AUTHOR_002c-COPYRIGHT_002c-AND-LICENSE"
accesskey="6">perluniintro AUTHOR, COPYRIGHT, AND
LICENSE</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perluniintro-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-DESCRIPTION" accesskey="n"
rel="next">perluniintro DESCRIPTION</a>, Up: <a href="#perluniintro"
accesskey="u" rel="up">perluniintro</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-82"></a>
-<h3 class="section">83.1 NAME</h3>
-
-<p>perluniintro - Perl Unicode introduction
-</p>
-<hr>
-<a name="perluniintro-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-UNICODE-IN-OLDER-PERLS" accesskey="n"
rel="next">perluniintro UNICODE IN OLDER PERLS</a>, Previous: <a
href="#perluniintro-NAME" accesskey="p" rel="prev">perluniintro NAME</a>, Up:
<a href="#perluniintro" accesskey="u" rel="up">perluniintro</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-80"></a>
-<h3 class="section">83.2 DESCRIPTION</h3>
-
-<p>This document gives a general idea of Unicode and how to use Unicode
-in Perl. See <a href="#perluniintro-Further-Resources">Further Resources</a>
for references to more in-depth
-treatments of Unicode.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perluniintro-Unicode"
accesskey="1">perluniintro Unicode</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Perl_0027s-Unicode-Support" accesskey="2">perluniintro
Perl's Unicode Support</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Perl_0027s-Unicode-Model" accesskey="3">perluniintro Perl's
Unicode Model</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Unicode-and-EBCDIC" accesskey="4">perluniintro Unicode and
EBCDIC</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Creating-Unicode" accesskey="5">perluniintro Creating
Unicode</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Handling-Unicode" accesskey="6">perluniintro Handling
Unicode</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Legacy-Encodings" accesskey="7">perluniintro Legacy
Encodings</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Unicode-I_002fO" accesskey="8">perluniintro Unicode
I/O</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Displaying-Unicode-As-Text" accesskey="9">perluniintro
Displaying Unicode As Text</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Special-Cases">perluniintro Special
Cases</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Advanced-Topics">perluniintro Advanced
Topics</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Miscellaneous">perluniintro
Miscellaneous</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Questions-With-Answers">perluniintro Questions With
Answers</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Hexadecimal-Notation">perluniintro Hexadecimal
Notation</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Further-Resources">perluniintro Further
Resources</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perluniintro-Unicode"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-Perl_0027s-Unicode-Support" accesskey="n"
rel="next">perluniintro Perl's Unicode Support</a>, Up: <a
href="#perluniintro-DESCRIPTION" accesskey="u" rel="up">perluniintro
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-2"></a>
-<h4 class="subsection">83.2.1 Unicode</h4>
-
-<p>Unicode is a character set standard which plans to codify all of the
-writing systems of the world, plus many other symbols.
-</p>
-<p>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 6.0 in October 2010.
-</p>
-<p>A Unicode <em>character</em> is an abstract entity. It is not bound to any
-particular integer width, especially not to the C language <code>char</code>.
-Unicode is language-neutral and display-neutral: it does not encode the
-language of the text, and it does not generally define fonts or other graphical
-layout details. Unicode operates on characters and on text built from
-those characters.
-</p>
-<p>Unicode defines characters like <code>LATIN CAPITAL LETTER A</code> or
<code>GREEK
-SMALL LETTER ALPHA</code> and unique numbers for the characters, in this
-case 0x0041 and 0x03B1, respectively. These unique numbers are called
-<em>code points</em>. A code point is essentially the position of the
-character within the set of all possible Unicode characters, and thus in
-Perl, the term <em>ordinal</em> is often used interchangeably with it.
-</p>
-<p>The Unicode standard prefers using hexadecimal notation for the code
-points. If numbers like <code>0x0041</code> are unfamiliar to you, take a peek
-at a later section, <a href="#perluniintro-Hexadecimal-Notation">Hexadecimal
Notation</a>. The Unicode standard
-uses the notation <code>U+0041 LATIN CAPITAL LETTER A</code>, to give the
-hexadecimal code point and the normative name of the character.
-</p>
-<p>Unicode also defines various <em>properties</em> for the characters, like
-"uppercase" or "lowercase", "decimal digit", or
"punctuation";
-these properties are independent of the names of the characters.
-Furthermore, various operations on the characters like uppercasing,
-lowercasing, and collating (sorting) are defined.
-</p>
-<p>A Unicode <em>logical</em> "character" can actually consist of
more than one internal
-<em>actual</em> "character" or code point. For Western languages,
this is adequately
-modelled by a <em>base character</em> (like <code>LATIN CAPITAL LETTER
A</code>) followed
-by one or more <em>modifiers</em> (like <code>COMBINING ACUTE ACCENT</code>).
This sequence of
-base character and modifiers is called a <em>combining character
-sequence</em>. Some non-western languages require more complicated
-models, so Unicode created the <em>grapheme cluster</em> concept, which was
-later further refined into the <em>extended grapheme cluster</em>. 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.
-</p>
-<p>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". 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.
-</p>
-<p>For some combinations of base character and modifiers, there are
-<em>precomposed</em> characters. There is a single character equivalent, for
-example, for the sequence <code>LATIN CAPITAL LETTER A</code> followed by
-<code>COMBINING ACUTE ACCENT</code>. It is called <code>LATIN CAPITAL LETTER
A WITH
-ACUTE</code>. 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 <em>normalization
-forms</em> are also defined. Thus, <code>LATIN CAPITAL LETTER A WITH
ACUTE</code> is
-in <em>Normalization Form Composed</em>, (abbreviated NFC), and the sequence
-<code>LATIN CAPITAL LETTER A</code> followed by <code>COMBINING ACUTE
ACCENT</code>
-represents the same character in <em>Normalization Form Decomposed</em> (NFD).
-</p>
-<p>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 not 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.
-</p>
-<p>When Unicode was first conceived, it was thought that all the world’s
-characters could be represented using a 16-bit word; that is a maximum of
-<code>0x10000</code> (or 65,536) characters would be needed, from
<code>0x0000</code> to
-<code>0xFFFF</code>. This soon proved to be wrong, and since Unicode 2.0 (July
-1996), Unicode has been defined all the way up to 21 bits
(<code>0x10FFFF</code>),
-and Unicode 3.1 (March 2001) defined the first characters above
<code>0xFFFF</code>.
-The first <code>0x10000</code> characters are called the <em>Plane 0</em>, or
the
-<em>Basic Multilingual Plane</em> (BMP). With Unicode 3.1, 17 (yes,
-seventeen) planes in all were defined–but they are nowhere near full of
-defined characters, yet.
-</p>
-<p>When a new language is being encoded, Unicode generally will choose a
-<code>block</code> of consecutive unallocated code points for its characters.
So
-far, the number of code points in these blocks has always been evenly
-divisible by 16. Extras in a block, not currently needed, are left
-unallocated, for future growth. But there have been occasions when
-a later release needed more code points than the available extras, and a
-new block had to allocated somewhere else, not contiguous to the initial
-one, to handle the overflow. Thus, it became apparent early on that
-"block" wasn’t an adequate organizing principal, and so the
<code>Script</code>
-property was created. (Later an improved script property was added as
-well, the <code>Script_Extensions</code> property.) Those code points that
are in
-overflow blocks can still
-have the same script as the original ones. The script concept fits more
-closely with natural language: there is <code>Latin</code> script,
<code>Greek</code>
-script, and so on; and there are several artificial scripts, like
-<code>Common</code> for characters that are used in multiple scripts, such as
-mathematical symbols. Scripts usually span varied parts of several
-blocks. For more information about scripts, see <a
href="#perlunicode-Scripts">perlunicode <strong>Scripts</strong></a>.
-The division into blocks exists, but it is almost completely
-accidental–an artifact of how the characters have been and still are
-allocated. (Note that this paragraph has oversimplified things for the
-sake of this being an introduction. Unicode doesn’t really encode
-languages, but the writing systems for them–their scripts; and one
-script can be used by many languages. Unicode also encodes things that
-aren’t really about languages, such as symbols like <code>BAGGAGE
CLAIM</code>.)
-</p>
-<p>The Unicode code points are just abstract numbers. To input and
-output these abstract numbers, the numbers must be <em>encoded</em> or
-<em>serialised</em> somehow. Unicode defines several <em>character encoding
-forms</em>, of which <em>UTF-8</em> is the most popular. UTF-8 is a
-variable length encoding that encodes Unicode characters as 1 to 4
-bytes. Other encodings
-include UTF-16 and UTF-32 and their big- and little-endian variants
-(UTF-8 is byte-order independent). The ISO/IEC 10646 defines the UCS-2
-and UCS-4 encoding forms.
-</p>
-<p>For more information about encodings–for instance, to learn what
-<em>surrogates</em> and <em>byte order marks</em> (BOMs) are–see <a
href="#perlunicode-NAME">perlunicode NAME</a>.
-</p>
-<hr>
-<a name="perluniintro-Perl_0027s-Unicode-Support"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-Perl_0027s-Unicode-Model" accesskey="n"
rel="next">perluniintro Perl's Unicode Model</a>, Previous: <a
href="#perluniintro-Unicode" accesskey="p" rel="prev">perluniintro Unicode</a>,
Up: <a href="#perluniintro-DESCRIPTION" accesskey="u" rel="up">perluniintro
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Perl_0027s-Unicode-Support"></a>
-<h4 class="subsection">83.2.2 Perl’s Unicode Support</h4>
-
-<p>Starting from Perl v5.6.0, Perl has had the capacity to handle Unicode
-natively. Perl v5.8.0, however, is the first recommended release for
-serious Unicode work. The maintenance release 5.6.1 fixed many of the
-problems of the initial Unicode implementation, but for example
-regular expressions still do not work with Unicode in 5.6.1.
-Perl v5.14.0 is the first release where Unicode support is
-(almost) seamlessly integrable without some gotchas (the exception being
-some differences in <a href="#perlfunc-quotemeta">quotemeta</a>, and that is
fixed
-starting in Perl 5.16.0). To enable this
-seamless support, you should <code>use feature 'unicode_strings'</code> (which
is
-automatically selected if you <code>use 5.012</code> or higher). See <a
href="feature.html#Top">(feature)</a>.
-(5.14 also fixes a number of bugs and departures from the Unicode
-standard.)
-</p>
-<p>Before Perl v5.8.0, the use of <code>use utf8</code> was used to declare
-that operations in the current block or file would be Unicode-aware.
-This model was found to be wrong, or at least clumsy: the
"Unicodeness"
-is now carried with the data, instead of being attached to the
-operations.
-Starting with Perl v5.8.0, only one case remains where an explicit <code>use
-utf8</code> 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 <code>use utf8</code>. This is not the default because
-scripts with legacy 8-bit data in them would break. See <a
href="utf8.html#Top">(utf8)</a>.
-</p>
-<hr>
-<a name="perluniintro-Perl_0027s-Unicode-Model"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-Unicode-and-EBCDIC" accesskey="n"
rel="next">perluniintro Unicode and EBCDIC</a>, Previous: <a
href="#perluniintro-Perl_0027s-Unicode-Support" accesskey="p"
rel="prev">perluniintro Perl's Unicode Support</a>, Up: <a
href="#perluniintro-DESCRIPTION" accesskey="u" rel="up">perluniintro
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Perl_0027s-Unicode-Model"></a>
-<h4 class="subsection">83.2.3 Perl’s Unicode Model</h4>
-
-<p>Perl supports both pre-5.6 strings of eight-bit native bytes, and
-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 v5.14.0, the upgrade was not completely
-transparent (see <a href="#perlunicode-The-_0022Unicode-Bug_0022">perlunicode
The "Unicode Bug"</a>), and for backwards
-compatibility, full transparency is not gained unless <code>use feature
-'unicode_strings'</code> (see <a href="feature.html#Top">(feature)</a>) or
<code>use 5.012</code> (or higher) is
-selected.
-</p>
-<p>Internally, Perl currently uses either whatever the native eight-bit
-character set of the platform (for example Latin-1) is, defaulting to
-UTF-8, to encode Unicode strings. Specifically, if all code points in
-the string are <code>0xFF</code> or less, Perl uses the native eight-bit
-character set. Otherwise, it uses UTF-8.
-</p>
-<p>A user of Perl does not normally need to know nor care how Perl
-happens to encode its internal strings, but it becomes relevant when
-outputting Unicode strings to a stream without a PerlIO layer (one with
-the "default" encoding). In such a case, the raw bytes used
internally
-(the native character set or UTF-8, as appropriate for each string)
-will be used, and a "Wide character" warning will be issued if those
-strings contain a character beyond 0x00FF.
-</p>
-<p>For example,
-</p>
-<pre class="verbatim"> perl -e 'print "\x{DF}\n",
"\x{0100}\x{DF}\n"'
-</pre>
-<p>produces a fairly useless mixture of native bytes and UTF-8, as well
-as a warning:
-</p>
-<pre class="verbatim"> Wide character in print at ...
-</pre>
-<p>To output UTF-8, use the <code>:encoding</code> or <code>:utf8</code>
output layer. Prepending
-</p>
-<pre class="verbatim"> binmode(STDOUT, ":utf8");
-</pre>
-<p>to this sample program ensures that the output is completely UTF-8,
-and removes the program’s warning.
-</p>
-<p>You can enable automatic UTF-8-ification of your standard file
-handles, default <code>open()</code> layer, and <code>@ARGV</code> by using
either
-the <code>-C</code> command line switch or the <code>PERL_UNICODE</code>
environment
-variable, see <a href="#perlrun-NAME">perlrun NAME</a> for the documentation
of the <code>-C</code> switch.
-</p>
-<p>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 likely
-complain about the malformed UTF-8.
-</p>
-<p>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:
-you can see whether yours is by running "perl -V" and looking for
-<code>useperlio=define</code>.
-</p>
-<hr>
-<a name="perluniintro-Unicode-and-EBCDIC"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-Creating-Unicode" accesskey="n"
rel="next">perluniintro Creating Unicode</a>, Previous: <a
href="#perluniintro-Perl_0027s-Unicode-Model" accesskey="p"
rel="prev">perluniintro Perl's Unicode Model</a>, Up: <a
href="#perluniintro-DESCRIPTION" accesskey="u" rel="up">perluniintro
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-and-EBCDIC"></a>
-<h4 class="subsection">83.2.4 Unicode and EBCDIC</h4>
-
-<p>Perl 5.8.0 added support for Unicode on EBCDIC platforms. This support
-was allowed to lapse in later releases, but was revived in 5.22.
-Unicode support is somewhat more complex to implement since additional
-conversions are needed. See <a href="#perlebcdic-NAME">perlebcdic NAME</a>
for more information.
-</p>
-<p>On EBCDIC platforms, the internal Unicode encoding form is UTF-EBCDIC
-instead of UTF-8. The difference is that as UTF-8 is "ASCII-safe" in
-that ASCII characters encode to UTF-8 as-is, while UTF-EBCDIC is
-"EBCDIC-safe", in that all the basic characters (which includes all
-those that have ASCII equivalents (like <code>"A"</code>,
<code>"0"</code>, <code>"%"</code>, <em>etc.</em>)
-are the same in both EBCDIC and UTF-EBCDIC. Often, documentation
-will use the term "UTF-8" to mean UTF-EBCDIC as well. This is the
case
-in this document.
-</p>
-<hr>
-<a name="perluniintro-Creating-Unicode"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-Handling-Unicode" accesskey="n"
rel="next">perluniintro Handling Unicode</a>, Previous: <a
href="#perluniintro-Unicode-and-EBCDIC" accesskey="p" rel="prev">perluniintro
Unicode and EBCDIC</a>, Up: <a href="#perluniintro-DESCRIPTION" accesskey="u"
rel="up">perluniintro DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Creating-Unicode"></a>
-<h4 class="subsection">83.2.5 Creating Unicode</h4>
-
-<p>This section applies fully to Perls starting with v5.22. Various
-caveats for earlier releases are in the <a
href="#perluniintro-Earlier-releases-caveats">Earlier releases caveats</a>
-subsection below.
-</p>
-<p>To create Unicode characters in literals,
-use the <code>\N{...}</code> notation in double-quoted strings:
-</p>
-<pre class="verbatim"> my $smiley_from_name = "\N{WHITE SMILING
FACE}";
- my $smiley_from_code_point = "\N{U+263a}";
-</pre>
-<p>Similarly, they can be used in regular expression literals
-</p>
-<pre class="verbatim"> $smiley =~ /\N{WHITE SMILING FACE}/;
- $smiley =~ /\N{U+263a}/;
-</pre>
-<p>At run-time you can use:
-</p>
-<pre class="verbatim"> use charnames ();
- my $hebrew_alef_from_name
- = charnames::string_vianame("HEBREW LETTER
ALEF");
- my $hebrew_alef_from_code_point =
charnames::string_vianame("U+05D0");
-</pre>
-<p>Naturally, <code>ord()</code> will do the reverse: it turns a character into
-a code point.
-</p>
-<p>There are other runtime options as well. You can use <code>pack()</code>:
-</p>
-<pre class="verbatim"> my $hebrew_alef_from_code_point = pack("U",
0x05d0);
-</pre>
-<p>Or you can use <code>chr()</code>, though it is less convenient in the
general
-case:
-</p>
-<pre class="verbatim"> $hebrew_alef_from_code_point =
chr(utf8::unicode_to_native(0x05d0));
- utf8::upgrade($hebrew_alef_from_code_point);
-</pre>
-<p>The <code>utf8::unicode_to_native()</code> and <code>utf8::upgrade()</code>
aren’t needed if
-the argument is above 0xFF, so the above could have been written as
-</p>
-<pre class="verbatim"> $hebrew_alef_from_code_point = chr(0x05d0);
-</pre>
-<p>since 0x5d0 is above 255.
-</p>
-<p><code>\x{}</code> and <code>\o{}</code> can also be used to specify code
points at compile
-time in double-quotish strings, but, for backward compatibility with
-older Perls, the same rules apply as with <code>chr()</code> for code points
less
-than 256.
-</p>
-<p><code>utf8::unicode_to_native()</code> is used so that the Perl code is
portable
-to EBCDIC platforms. You can omit it if you’re <em>really</em> sure no
one
-will ever want to use your code on a non-ASCII platform. Starting in
-Perl v5.22, calls to it on ASCII platforms are optimized out, so there’s
-no performance penalty at all in adding it. Or you can simply use the
-other constructs that don’t require it.
-</p>
-<p>See <a href="#perluniintro-Further-Resources">Further Resources</a> for how
to find all these names and numeric
-codes.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perluniintro-Earlier-releases-caveats" accesskey="1">perluniintro
Earlier releases caveats</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perluniintro-Earlier-releases-caveats"></a>
-<div class="header">
-<p>
-Up: <a href="#perluniintro-Creating-Unicode" accesskey="u"
rel="up">perluniintro Creating Unicode</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Earlier-releases-caveats"></a>
-<h4 class="subsubsection">83.2.5.1 Earlier releases caveats</h4>
-
-<p>On EBCDIC platforms, prior to v5.22, using <code>\N{U+...}</code>
doesn’t work
-properly.
-</p>
-<p>Prior to v5.16, using <code>\N{...}</code> with a character name (as
opposed to a
-<code>U+...</code> code point) required a
<code>use charnames :full</code><!-- /@w -->.
-</p>
-<p>Prior to v5.14, there were some bugs in <code>\N{...}</code> with a
character name
-(as opposed to a <code>U+...</code> code point).
-</p>
-<p><code>charnames::string_vianame()</code> was introduced in v5.14. Prior to
that,
-<code>charnames::vianame()</code> should work, but only if the argument is of
the
-form <code>"U+..."</code>. Your best bet there for runtime Unicode
by character
-name is probably:
-</p>
-<pre class="verbatim"> use charnames ();
- my $hebrew_alef_from_name
- = pack("U", charnames::vianame("HEBREW LETTER
ALEF"));
-</pre>
-<hr>
-<a name="perluniintro-Handling-Unicode"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-Legacy-Encodings" accesskey="n"
rel="next">perluniintro Legacy Encodings</a>, Previous: <a
href="#perluniintro-Creating-Unicode" accesskey="p" rel="prev">perluniintro
Creating Unicode</a>, Up: <a href="#perluniintro-DESCRIPTION" accesskey="u"
rel="up">perluniintro DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Handling-Unicode"></a>
-<h4 class="subsection">83.2.6 Handling Unicode</h4>
-
-<p>Handling Unicode is for the most part transparent: just use the
-strings as usual. Functions like <code>index()</code>, <code>length()</code>,
and
-<code>substr()</code> will work on the Unicode characters; regular expressions
-will work on the Unicode characters (see <a
href="#perlunicode-NAME">perlunicode NAME</a> and <a
href="#perlretut-NAME">perlretut NAME</a>).
-</p>
-<p>Note that Perl considers grapheme clusters to be separate characters, so for
-example
-</p>
-<pre class="verbatim"> print length("\N{LATIN CAPITAL LETTER
A}\N{COMBINING ACUTE ACCENT}"),
- "\n";
-</pre>
-<p>will print 2, not 1. The only exception is that regular expressions
-have <code>\X</code> for matching an extended grapheme cluster. (Thus
<code>\X</code> in a
-regular expression would match the entire sequence of both the example
-characters.)
-</p>
-<p>Life is not quite so transparent, however, when working with legacy
-encodings, I/O, and certain special cases:
-</p>
-<hr>
-<a name="perluniintro-Legacy-Encodings"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-Unicode-I_002fO" accesskey="n"
rel="next">perluniintro Unicode I/O</a>, Previous: <a
href="#perluniintro-Handling-Unicode" accesskey="p" rel="prev">perluniintro
Handling Unicode</a>, Up: <a href="#perluniintro-DESCRIPTION" accesskey="u"
rel="up">perluniintro DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Legacy-Encodings"></a>
-<h4 class="subsection">83.2.7 Legacy Encodings</h4>
-
-<p>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).
-</p>
-<p>The <code>Encode</code> module knows about many encodings and has interfaces
-for doing conversions between those encodings:
-</p>
-<pre class="verbatim"> use Encode 'decode';
- $data = decode("iso-8859-3", $data); # convert from legacy to
utf-8
-</pre>
-<hr>
-<a name="perluniintro-Unicode-I_002fO"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-Displaying-Unicode-As-Text" accesskey="n"
rel="next">perluniintro Displaying Unicode As Text</a>, Previous: <a
href="#perluniintro-Legacy-Encodings" accesskey="p" rel="prev">perluniintro
Legacy Encodings</a>, Up: <a href="#perluniintro-DESCRIPTION" accesskey="u"
rel="up">perluniintro DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-I_002fO"></a>
-<h4 class="subsection">83.2.8 Unicode I/O</h4>
-
-<p>Normally, writing out Unicode data
-</p>
-<pre class="verbatim"> print FH $some_string_with_unicode, "\n";
-</pre>
-<p>produces raw bytes that Perl happens to use to internally encode the
-Unicode string. Perl’s internal encoding depends on the system as
-well as what characters happen to be in the string at the time. If
-any of the characters are at code points <code>0x100</code> or above, you will
get
-a warning. To ensure that the output is explicitly rendered in the
-encoding you desire–and to avoid the warning–open the stream with
-the desired encoding. Some examples:
-</p>
-<pre class="verbatim"> open FH, ">:utf8", "file";
-
- open FH, ">:encoding(ucs2)", "file";
- open FH, ">:encoding(UTF-8)", "file";
- open FH, ">:encoding(shift_jis)", "file";
-</pre>
-<p>and on already open streams, use <code>binmode()</code>:
-</p>
-<pre class="verbatim"> binmode(STDOUT, ":utf8");
-
- binmode(STDOUT, ":encoding(ucs2)");
- binmode(STDOUT, ":encoding(UTF-8)");
- binmode(STDOUT, ":encoding(shift_jis)");
-</pre>
-<p>The matching of encoding names is loose: case does not matter, and
-many encodings have several aliases. Note that the <code>:utf8</code> layer
-must always be specified exactly like that; it is <em>not</em> subject to
-the loose matching of encoding names. Also note that currently
<code>:utf8</code> is unsafe for
-input, because it accepts the data without validating that it is indeed valid
-UTF-8; you should instead use <code>:encoding(utf-8)</code> (with or without a
-hyphen).
-</p>
-<p>See <a href="PerlIO.html#Top">(PerlIO)</a> for the <code>:utf8</code>
layer, <a href="PerlIO-encoding.html#Top">(PerlIO-encoding)</a> and
-<a href="Encode-PerlIO.html#Top">(Encode-PerlIO)</a> for the
<code>:encoding()</code> layer, and
-<a href="Encode-Supported.html#Top">(Encode-Supported)</a> for many encodings
supported by the <code>Encode</code>
-module.
-</p>
-<p>Reading in a file that you know happens to be encoded in one of the
-Unicode or legacy encodings does not magically turn the data into
-Unicode in Perl’s eyes. To do that, specify the appropriate
-layer when opening files
-</p>
-<pre class="verbatim"> open(my $fh,'<:encoding(utf8)', 'anything');
- my $line_of_unicode = <$fh>;
-
- open(my $fh,'<:encoding(Big5)', 'anything');
- my $line_of_unicode = <$fh>;
-</pre>
-<p>The I/O layers can also be specified more flexibly with
-the <code>open</code> pragma. See <a href="open.html#Top">(open)</a>, or look
at the following example.
-</p>
-<pre class="verbatim"> use open ':encoding(utf8)'; # input/output default
encoding will be
- # UTF-8
- open X, ">file";
- print X chr(0x100), "\n";
- close X;
- open Y, "<file";
- printf "%#x\n", ord(<Y>); # this should print 0x100
- close Y;
-</pre>
-<p>With the <code>open</code> pragma you can use the <code>:locale</code> layer
-</p>
-<pre class="verbatim"> BEGIN { $ENV{LC_ALL} = $ENV{LANG} = 'ru_RU.KOI8-R' }
- # 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
- close O;
- open(I, "<koi8");
- printf "%#x\n", ord(<I>), "\n"; # this should
print 0xc1
- close I;
-</pre>
-<p>These methods install a transparent filter on the I/O stream that
-converts data from the specified encoding when it is read in from the
-stream. The result is always Unicode.
-</p>
-<p>The <a href="open.html#Top">(open)</a> pragma affects all the
<code>open()</code> calls after the pragma by
-setting default layers. If you want to affect only certain
-streams, use explicit layers directly in the <code>open()</code> call.
-</p>
-<p>You can switch encodings on an already opened stream by using
-<code>binmode()</code>; see ‘perlfunc binmode’.
-</p>
-<p>The <code>:locale</code> does not currently work with
-<code>open()</code> and <code>binmode()</code>, only with the
<code>open</code> pragma. The
-<code>:utf8</code> and <code>:encoding(...)</code> methods do work with all of
<code>open()</code>,
-<code>binmode()</code>, and the <code>open</code> pragma.
-</p>
-<p>Similarly, you may use these I/O layers on output streams to
-automatically convert Unicode to the specified encoding when it is
-written to the stream. For example, the following snippet copies the
-contents of the file "text.jis" (encoded as ISO-2022-JP, aka JIS) to
-the file "text.utf8", encoded as UTF-8:
-</p>
-<pre class="verbatim"> open(my $nihongo, '<:encoding(iso-2022-jp)',
'text.jis');
- open(my $unicode, '>:utf8', 'text.utf8');
- while (<$nihongo>) { print $unicode $_ }
-</pre>
-<p>The naming of encodings, both by the <code>open()</code> and by the
<code>open</code>
-pragma allows for flexible names: <code>koi8-r</code> and <code>KOI8R</code>
will both be
-understood.
-</p>
-<p>Common encodings recognized by ISO, MIME, IANA, and various other
-standardisation organisations are recognised; for a more detailed
-list see <a href="Encode-Supported.html#Top">(Encode-Supported)</a>.
-</p>
-<p><code>read()</code> reads characters and returns the number of characters.
-<code>seek()</code> and <code>tell()</code> operate on byte counts, as do
<code>sysread()</code>
-and <code>sysseek()</code>.
-</p>
-<p>Notice that because of the default behaviour of not doing any
-conversion upon input if there is no default layer,
-it is easy to mistakenly write code that keeps on expanding a file
-by repeatedly encoding the data:
-</p>
-<pre class="verbatim"> # BAD CODE WARNING
- open F, "file";
- local $/; ## read in the whole file of 8-bit characters
- $t = <F>;
- close F;
- open F, ">:encoding(utf8)", "file";
- print F $t; ## convert to UTF-8 on output
- close F;
-</pre>
-<p>If you run this code twice, the contents of the <samp>file</samp> will be
twice
-UTF-8 encoded. A <code>use open ':encoding(utf8)'</code> would have avoided
the
-bug, or explicitly opening also the <samp>file</samp> for input as UTF-8.
-</p>
-<p><strong>NOTE</strong>: the <code>:utf8</code> and <code>:encoding</code>
features work only if your
-Perl has been built with <a href="PerlIO.html#Top">(PerlIO)</a>, which is the
default
-on most systems.
-</p>
-<hr>
-<a name="perluniintro-Displaying-Unicode-As-Text"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-Special-Cases" accesskey="n"
rel="next">perluniintro Special Cases</a>, Previous: <a
href="#perluniintro-Unicode-I_002fO" accesskey="p" rel="prev">perluniintro
Unicode I/O</a>, Up: <a href="#perluniintro-DESCRIPTION" accesskey="u"
rel="up">perluniintro DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Displaying-Unicode-As-Text"></a>
-<h4 class="subsection">83.2.9 Displaying Unicode As Text</h4>
-
-<p>Sometimes you might want to display Perl scalars containing Unicode as
-simple ASCII (or EBCDIC) text. The following subroutine converts
-its argument so that Unicode characters with code points greater than
-255 are displayed as <code>\x{...}</code>, control characters (like
<code>\n</code>) are
-displayed as <code>\x..</code>, and the rest of the characters as themselves:
-</p>
-<pre class="verbatim"> 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
- }
-</pre>
-<p>For example,
-</p>
-<pre class="verbatim"> nice_string("foo\x{100}bar\n")
-</pre>
-<p>returns the string
-</p>
-<pre class="verbatim"> 'foo\x{0100}bar\x0A'
-</pre>
-<p>which is ready to be printed.
-</p>
-<p>(<code>\\x{}</code> is used here instead of <code>\\N{}</code>, since
it’s most likely that
-you want to see what the native values are.)
-</p>
-<hr>
-<a name="perluniintro-Special-Cases"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-Advanced-Topics" accesskey="n"
rel="next">perluniintro Advanced Topics</a>, Previous: <a
href="#perluniintro-Displaying-Unicode-As-Text" accesskey="p"
rel="prev">perluniintro Displaying Unicode As Text</a>, Up: <a
href="#perluniintro-DESCRIPTION" accesskey="u" rel="up">perluniintro
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Special-Cases"></a>
-<h4 class="subsection">83.2.10 Special Cases</h4>
-
-<ul>
-<li> Bit Complement Operator ~ And vec()
-
-<p>The bit complement operator <code>~</code> may produce surprising results if
-used on strings containing characters with ordinal values above
-255. In such a case, the results are consistent with the internal
-encoding of the characters, but not with much else. So don’t do
-that. Similarly for <code>vec()</code>: you will be operating on the
-internally-encoded bit patterns of the Unicode characters, not on
-the code point values, which is very probably not what you want.
-</p>
-</li><li> Peeking At Perl’s Internal Encoding
-
-<p>Normal users of Perl should never care how Perl encodes any particular
-Unicode string (because the normal ways to get at the contents of a
-string with Unicode–via input and output–should always be via
-explicitly-defined I/O layers). But if you must, there are two
-ways of looking behind the scenes.
-</p>
-<p>One way of peeking inside the internal encoding of Unicode characters
-is to use <code>unpack("C*", ...</code> to get the bytes of whatever
the string
-encoding happens to be, or <code>unpack("U0..", ...)</code> to get
the bytes of the
-UTF-8 encoding:
-</p>
-<pre class="verbatim"> # this prints c4 80 for the UTF-8 bytes 0xc4 0x80
- print join(" ", unpack("U0(H2)*", pack("U",
0x100))), "\n";
-</pre>
-<p>Yet another way would be to use the Devel::Peek module:
-</p>
-<pre class="verbatim"> perl -MDevel::Peek -e 'Dump(chr(0x100))'
-</pre>
-<p>That shows the <code>UTF8</code> flag in FLAGS and both the UTF-8 bytes
-and Unicode characters in <code>PV</code>. See also later in this document
-the discussion about the <code>utf8::is_utf8()</code> function.
-</p>
-</li></ul>
-
-<hr>
-<a name="perluniintro-Advanced-Topics"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-Miscellaneous" accesskey="n"
rel="next">perluniintro Miscellaneous</a>, Previous: <a
href="#perluniintro-Special-Cases" accesskey="p" rel="prev">perluniintro
Special Cases</a>, Up: <a href="#perluniintro-DESCRIPTION" accesskey="u"
rel="up">perluniintro DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Advanced-Topics"></a>
-<h4 class="subsection">83.2.11 Advanced Topics</h4>
-
-<ul>
-<li> String Equivalence
-
-<p>The question of string equivalence turns somewhat complicated
-in Unicode: what do you mean by "equal"?
-</p>
-<p>(Is <code>LATIN CAPITAL LETTER A WITH ACUTE</code> equal to
-<code>LATIN CAPITAL LETTER A</code>?)
-</p>
-<p>The short answer is that by default Perl compares equivalence
(<code>eq</code>,
-<code>ne</code>) based only on code points of the characters. In the above
-case, the answer is no (because 0x00C1 != 0x0041). But sometimes, any
-CAPITAL LETTER A’s should be considered equal, or even A’s of any
case.
-</p>
-<p>The long answer is that you need to consider character normalization
-and casing issues: see <a
href="Unicode-Normalize.html#Top">(Unicode-Normalize)</a>, Unicode Technical
Report #15,
-<a href="http://www.unicode.org/unicode/reports/tr15";>Unicode Normalization
Forms</a> and
-sections on case mapping in the <a href="http://www.unicode.org";>Unicode
Standard</a>.
-</p>
-<p>As of Perl 5.8.0, the "Full" case-folding of <em>Case
-Mappings/SpecialCasing</em> is implemented, but bugs remain in
<code>qr//i</code> with them,
-mostly fixed by 5.14, and essentially entirely by 5.18.
-</p>
-</li><li> String Collation
-
-<p>People like to see their strings nicely sorted–or as Unicode
-parlance goes, collated. But again, what do you mean by collate?
-</p>
-<p>(Does <code>LATIN CAPITAL LETTER A WITH ACUTE</code> come before or after
-<code>LATIN CAPITAL LETTER A WITH GRAVE</code>?)
-</p>
-<p>The short answer is that by default, Perl compares strings (<code>lt</code>,
-<code>le</code>, <code>cmp</code>, <code>ge</code>, <code>gt</code>) based
only on the code points of the
-characters. In the above case, the answer is "after", since
-<code>0x00C1</code> > <code>0x00C0</code>.
-</p>
-<p>The long answer is that "it depends", and a good answer cannot be
-given without knowing (at the very least) the language context.
-See <a href="Unicode-Collate.html#Top">(Unicode-Collate)</a>, and <em>Unicode
Collation Algorithm</em>
-<a
href="http://www.unicode.org/unicode/reports/tr10/";>http://www.unicode.org/unicode/reports/tr10/</a>
-</p>
-</li></ul>
-
-<hr>
-<a name="perluniintro-Miscellaneous"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-Questions-With-Answers" accesskey="n"
rel="next">perluniintro Questions With Answers</a>, Previous: <a
href="#perluniintro-Advanced-Topics" accesskey="p" rel="prev">perluniintro
Advanced Topics</a>, Up: <a href="#perluniintro-DESCRIPTION" accesskey="u"
rel="up">perluniintro DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Miscellaneous-1"></a>
-<h4 class="subsection">83.2.12 Miscellaneous</h4>
-
-<ul>
-<li> Character Ranges and Classes
-
-<p>Character ranges in regular expression bracketed character classes ( e.g.,
-<code>/[a-z]/</code>) and in the <code>tr///</code> (also known as
<code>y///</code>) operator are not
-magically Unicode-aware. What this means is that <code>[A-Za-z]</code> will
not
-magically start to mean "all alphabetic letters" (not that it does
mean that
-even for 8-bit characters; for those, if you are using locales (<a
href="#perllocale-NAME">perllocale NAME</a>),
-use <code>/[[:alpha:]]/</code>; and if not, use the 8-bit-aware property
<code>\p{alpha}</code>).
-</p>
-<p>All the properties that begin with <code>\p</code> (and its inverse
<code>\P</code>) are actually
-character classes that are Unicode-aware. There are dozens of them, see
-<a href="perluniprops.html#Top">(perluniprops)</a>.
-</p>
-<p>Starting in v5.22, you can use Unicode code points as the end points of
-regular expression pattern character ranges, and the range will include
-all Unicode code points that lie between those end points, inclusive.
-</p>
-<pre class="verbatim"> qr/ [\N{U+03]-\N{U+20}] /x
-</pre>
-<p>includes the code points
-<code>\N{U+03}</code>, <code>\N{U+04}</code>, ..., <code>\N{U+20}</code>.
-</p>
-<p>(It is planned to extend this behavior to ranges in <code>tr///</code> in
Perl
-v5.24.)
-</p>
-</li><li> String-To-Number Conversions
-
-<p>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 <code>0</code> to <code>9</code> (and ASCII <code>a</code> to
<code>f</code> for hexadecimal).
-To get safe conversions from any Unicode string, use
-<a href="Unicode-UCD.html#num_0028_0029">(Unicode-UCD)num()</a>.
-</p>
-</li></ul>
-
-<hr>
-<a name="perluniintro-Questions-With-Answers"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-Hexadecimal-Notation" accesskey="n"
rel="next">perluniintro Hexadecimal Notation</a>, Previous: <a
href="#perluniintro-Miscellaneous" accesskey="p" rel="prev">perluniintro
Miscellaneous</a>, Up: <a href="#perluniintro-DESCRIPTION" accesskey="u"
rel="up">perluniintro DESCRIPTION</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Questions-With-Answers"></a>
-<h4 class="subsection">83.2.13 Questions With Answers</h4>
-
-<ul>
-<li> Will My Old Scripts Break?
-
-<p>Very probably not. Unless you are generating Unicode characters
-somehow, old behaviour should be preserved. About the only behaviour
-that has changed and which could start generating Unicode is the old
-behaviour of <code>chr()</code> where supplying an argument more than 255
-produced a character modulo 255. <code>chr(300)</code>, for example, was equal
-to <code>chr(45)</code> or "-" (in ASCII), now it is LATIN CAPITAL
LETTER I WITH
-BREVE.
-</p>
-</li><li> How Do I Make My Scripts Work With Unicode?
-
-<p>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
-<code>use feature 'unicode_strings'</code> (or <code>use 5.012</code> or
higher) to your
-script.
-</p>
-</li><li> How Do I Know Whether My String Is In Unicode?
-
-<p>You shouldn’t have to care. But you may if your Perl is before 5.14.0
-or you haven’t specified <code>use feature 'unicode_strings'</code> or
<code>use
-5.012</code> (or higher) because otherwise the rules for 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 <a href="#perlunicode-When-Unicode-Does-Not-Happen">perlunicode When
Unicode Does Not Happen</a>.)
-</p>
-<p>To determine if a string is in Unicode, use:
-</p>
-<pre class="verbatim"> print utf8::is_utf8($string) ? 1 : 0, "\n";
-</pre>
-<p>But note that this doesn’t mean that any of the characters in the
-string are necessary UTF-8 encoded, or that any of the characters have
-code points greater than 0xFF (255) or even 0x80 (128), or that the
-string has any characters at all. All the <code>is_utf8()</code> does is to
-return the value of the internal "utf8ness" flag attached to the
-<code>$string</code>. If the flag is off, the bytes in the scalar are
interpreted
-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, 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,
-</p>
-<pre class="verbatim"> $a = "ab\x80c";
- $b = "\x{100}";
- print "$a = $b\n";
-</pre>
-<p>the output string will be UTF-8-encoded <code>ab\x80c = \x{100}\n</code>,
but
-<code>$a</code> will stay byte-encoded.
-</p>
-<p>Sometimes you might really need to know the byte length of a string
-instead of the character length. For that use either the
-<code>Encode::encode_utf8()</code> function or the <code>bytes</code> pragma
-and the <code>length()</code> function:
-</p>
-<pre class="verbatim"> my $unicode = chr(0x100);
- print length($unicode), "\n"; # will print 1
- require Encode;
- print length(Encode::encode_utf8($unicode)),"\n"; # will print 2
- use bytes;
- print length($unicode), "\n"; # will also print 2
- # (the 0xC4 0x80 of the UTF-8)
- no bytes;
-</pre>
-</li><li> How Do I Find Out What Encoding a File Has?
-
-<p>You might try <a href="Encode-Guess.html#Top">(Encode-Guess)</a>, but it
has a number of limitations.
-</p>
-</li><li> How Do I Detect Data That’s Not Valid In a Particular Encoding?
-
-<p>Use the <code>Encode</code> package to try converting it.
-For example,
-</p>
-<pre class="verbatim"> use Encode 'decode_utf8';
-
- if (eval { decode_utf8($string, Encode::FB_CROAK); 1 }) {
- # $string is valid utf8
- } else {
- # $string is not valid utf8
- }
-</pre>
-<p>Or use <code>unpack</code> to try decoding it:
-</p>
-<pre class="verbatim"> use warnings;
- @chars = unpack("C0U*", $string_of_bytes_that_I_think_is_utf8);
-</pre>
-<p>If invalid, a <code>Malformed UTF-8 character</code> warning is produced.
The "C0" means
-"process the string character per character". Without that, the
-<code>unpack("U*", ...)</code> would work in <code>U0</code> mode
(the default if the format
-string starts with <code>U</code>) and it would return the bytes making up the
UTF-8
-encoding of the target string, something that will always work.
-</p>
-</li><li> How Do I Convert Binary Data Into a Particular Encoding, Or Vice
Versa?
-
-<p>This probably isn’t as useful as you might think.
-Normally, you shouldn’t need to.
-</p>
-<p>In one sense, what you are asking doesn’t make much sense: encodings
-are for characters, and binary data are not "characters", so
converting
-"data" into some encoding isn’t meaningful unless you know in
what
-character set and encoding the binary data is in, in which case it’s
-not just binary data, now is it?
-</p>
-<p>If you have a raw sequence of bytes that you know should be
-interpreted via a particular encoding, you can use <code>Encode</code>:
-</p>
-<pre class="verbatim"> use Encode 'from_to';
- from_to($data, "iso-8859-1", "utf-8"); # from latin-1
to utf-8
-</pre>
-<p>The call to <code>from_to()</code> changes the bytes in <code>$data</code>,
but nothing
-material about the nature of the string has changed as far as Perl is
-concerned. Both before and after the call, the string <code>$data</code>
-contains just a bunch of 8-bit bytes. As far as Perl is concerned,
-the encoding of the string remains as "system-native 8-bit bytes".
-</p>
-<p>You might relate this to a fictional ’Translate’ module:
-</p>
-<pre class="verbatim"> use Translate;
- my $phrase = "Yes";
- Translate::from_to($phrase, 'english', 'deutsch');
- ## phrase now contains "Ja"
-</pre>
-<p>The contents of the string changes, but not the nature of the string.
-Perl doesn’t know any more after the call than before that the
-contents of the string indicates the affirmative.
-</p>
-<p>Back to converting data. If you have (or want) data in your system’s
-native 8-bit encoding (e.g. Latin-1, EBCDIC, etc.), you can use
-pack/unpack to convert to/from Unicode.
-</p>
-<pre class="verbatim"> $native_string = pack("W*",
unpack("U*", $Unicode_string));
- $Unicode_string = pack("U*", unpack("W*",
$native_string));
-</pre>
-<p>If you have a sequence of bytes you <strong>know</strong> is valid UTF-8,
-but Perl doesn’t know it yet, you can make Perl a believer, too:
-</p>
-<pre class="verbatim"> use Encode 'decode_utf8';
- $Unicode = decode_utf8($bytes);
-</pre>
-<p>or:
-</p>
-<pre class="verbatim"> $Unicode = pack("U0a*", $bytes);
-</pre>
-<p>You can find the bytes that make up a UTF-8 sequence with
-</p>
-<pre class="verbatim"> @bytes = unpack("C*", $Unicode_string)
-</pre>
-<p>and you can create well-formed Unicode with
-</p>
-<pre class="verbatim"> $Unicode_string = pack("U*", 0xff, ...)
-</pre>
-</li><li> How Do I Display Unicode? How Do I Input Unicode?
-
-<p>See <a
href="http://www.alanwood.net/unicode/";>http://www.alanwood.net/unicode/</a> and
-<a
href="http://www.cl.cam.ac.uk/~mgk25/unicode.html";>http://www.cl.cam.ac.uk/~mgk25/unicode.html</a>
-</p>
-</li><li> How Does Unicode Work With Traditional Locales?
-
-<p>If your locale is a UTF-8 locale, starting in Perl v5.20, Perl works
-well for all categories except <code>LC_COLLATE</code> dealing with sorting and
-the <code>cmp</code> operator.
-</p>
-<p>For other locales, starting in Perl 5.16, you can specify
-</p>
-<pre class="verbatim"> use locale ':not_characters';
-</pre>
-<p>to get Perl to work well with them. The catch is that you
-have to translate from the locale character set to/from Unicode
-yourself. See <a href="#perluniintro-Unicode-I_002fO">Unicode I/O</a> above
for how to
-</p>
-<pre class="verbatim"> use open ':locale';
-</pre>
-<p>to accomplish this, but full details are in <a
href="#perllocale-Unicode-and-UTF_002d8">perllocale Unicode and UTF-8</a>,
including gotchas that happen if you don’t specify
-<code>:not_characters</code>.
-</p>
-</li></ul>
-
-<hr>
-<a name="perluniintro-Hexadecimal-Notation"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-Further-Resources" accesskey="n"
rel="next">perluniintro Further Resources</a>, Previous: <a
href="#perluniintro-Questions-With-Answers" accesskey="p"
rel="prev">perluniintro Questions With Answers</a>, Up: <a
href="#perluniintro-DESCRIPTION" accesskey="u" rel="up">perluniintro
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Hexadecimal-Notation"></a>
-<h4 class="subsection">83.2.14 Hexadecimal Notation</h4>
-
-<p>The Unicode standard prefers using hexadecimal notation because
-that more clearly shows the division of Unicode into blocks of 256 characters.
-Hexadecimal is also simply shorter than decimal. You can use decimal
-notation, too, but learning to use hexadecimal just makes life easier
-with the Unicode standard. The <code>U+HHHH</code> notation uses hexadecimal,
-for example.
-</p>
-<p>The <code>0x</code> prefix means a hexadecimal number, the digits are 0-9
<em>and</em>
-a-f (or A-F, case doesn’t matter). Each hexadecimal digit represents
-four bits, or half a byte. <code>print 0x..., "\n"</code> will show
a
-hexadecimal number in decimal, and <code>printf "%x\n",
$decimal</code> will
-show a decimal number in hexadecimal. If you have just the
-"hex digits" of a hexadecimal number, you can use the
<code>hex()</code> function.
-</p>
-<pre class="verbatim"> print 0x0009, "\n"; # 9
- print 0x000a, "\n"; # 10
- print 0x000f, "\n"; # 15
- print 0x0010, "\n"; # 16
- print 0x0011, "\n"; # 17
- print 0x0100, "\n"; # 256
-
- print 0x0041, "\n"; # 65
-
- printf "%x\n", 65; # 41
- printf "%#x\n", 65; # 0x41
-
- print hex("41"), "\n"; # 65
-</pre>
-<hr>
-<a name="perluniintro-Further-Resources"></a>
-<div class="header">
-<p>
-Previous: <a href="#perluniintro-Hexadecimal-Notation" accesskey="p"
rel="prev">perluniintro Hexadecimal Notation</a>, Up: <a
href="#perluniintro-DESCRIPTION" accesskey="u" rel="up">perluniintro
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Further-Resources"></a>
-<h4 class="subsection">83.2.15 Further Resources</h4>
-
-<ul>
-<li> Unicode Consortium
-
-<p><a href="http://www.unicode.org/";>http://www.unicode.org/</a>
-</p>
-</li><li> Unicode FAQ
-
-<p><a
href="http://www.unicode.org/unicode/faq/";>http://www.unicode.org/unicode/faq/</a>
-</p>
-</li><li> Unicode Glossary
-
-<p><a
href="http://www.unicode.org/glossary/";>http://www.unicode.org/glossary/</a>
-</p>
-</li><li> Unicode Recommended Reading List
-
-<p>The Unicode Consortium has a list of articles and books, some of which
-give a much more in depth treatment of Unicode:
-<a
href="http://unicode.org/resources/readinglist.html";>http://unicode.org/resources/readinglist.html</a>
-</p>
-</li><li> Unicode Useful Resources
-
-<p><a
href="http://www.unicode.org/unicode/onlinedat/resources.html";>http://www.unicode.org/unicode/onlinedat/resources.html</a>
-</p>
-</li><li> Unicode and Multilingual Support in HTML, Fonts, Web Browsers and
Other Applications
-
-<p><a
href="http://www.alanwood.net/unicode/";>http://www.alanwood.net/unicode/</a>
-</p>
-</li><li> UTF-8 and Unicode FAQ for Unix/Linux
-
-<p><a
href="http://www.cl.cam.ac.uk/~mgk25/unicode.html";>http://www.cl.cam.ac.uk/~mgk25/unicode.html</a>
-</p>
-</li><li> Legacy Character Sets
-
-<p><a href="http://www.czyborra.com/";>http://www.czyborra.com/</a>
-<a href="http://www.eki.ee/letter/";>http://www.eki.ee/letter/</a>
-</p>
-</li><li> You can explore various information from the Unicode data files using
-the <code>Unicode::UCD</code> module.
-
-</li></ul>
-
-<hr>
-<a name="perluniintro-UNICODE-IN-OLDER-PERLS"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-SEE-ALSO" accesskey="n" rel="next">perluniintro
SEE ALSO</a>, Previous: <a href="#perluniintro-DESCRIPTION" accesskey="p"
rel="prev">perluniintro DESCRIPTION</a>, Up: <a href="#perluniintro"
accesskey="u" rel="up">perluniintro</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="UNICODE-IN-OLDER-PERLS"></a>
-<h3 class="section">83.3 UNICODE IN OLDER PERLS</h3>
-
-<p>If you cannot upgrade your Perl to 5.8.0 or later, you can still
-do some Unicode processing by using the modules <code>Unicode::String</code>,
-<code>Unicode::Map8</code>, and <code>Unicode::Map</code>, available from CPAN.
-If you have the GNU recode installed, you can also use the
-Perl front-end <code>Convert::Recode</code> for character conversions.
-</p>
-<p>The following are fast conversions from ISO 8859-1 (Latin-1) bytes
-to UTF-8 bytes and back, the code works even with older Perl 5 versions.
-</p>
-<pre class="verbatim"> # ISO 8859-1 to UTF-8
- s/([\x80-\xFF])/chr(0xC0|ord($1)>>6).chr(0x80|ord($1)&0x3F)/eg;
-
- # UTF-8 to ISO 8859-1
-
s/([\xC2\xC3])([\x80-\xBF])/chr(ord($1)<<6&0xC0|ord($2)&0x3F)/eg;
-</pre>
-<hr>
-<a name="perluniintro-SEE-ALSO"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-ACKNOWLEDGMENTS" accesskey="n"
rel="next">perluniintro ACKNOWLEDGMENTS</a>, Previous: <a
href="#perluniintro-UNICODE-IN-OLDER-PERLS" accesskey="p"
rel="prev">perluniintro UNICODE IN OLDER PERLS</a>, Up: <a href="#perluniintro"
accesskey="u" rel="up">perluniintro</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-42"></a>
-<h3 class="section">83.4 SEE ALSO</h3>
-
-<p><a href="#perlunitut-NAME">perlunitut NAME</a>, <a
href="#perlunicode-NAME">perlunicode NAME</a>, <a
href="Encode.html#Top">(Encode)</a>, <a href="open.html#Top">(open)</a>, <a
href="utf8.html#Top">(utf8)</a>, <a href="bytes.html#Top">(bytes)</a>,
-<a href="#perlretut-NAME">perlretut NAME</a>, <a href="#perlrun-NAME">perlrun
NAME</a>, <a href="Unicode-Collate.html#Top">(Unicode-Collate)</a>, <a
href="Unicode-Normalize.html#Top">(Unicode-Normalize)</a>,
-<a href="Unicode-UCD.html#Top">(Unicode-UCD)</a>
-</p>
-<hr>
-<a name="perluniintro-ACKNOWLEDGMENTS"></a>
-<div class="header">
-<p>
-Next: <a href="#perluniintro-AUTHOR_002c-COPYRIGHT_002c-AND-LICENSE"
accesskey="n" rel="next">perluniintro AUTHOR, COPYRIGHT, AND LICENSE</a>,
Previous: <a href="#perluniintro-SEE-ALSO" accesskey="p"
rel="prev">perluniintro SEE ALSO</a>, Up: <a href="#perluniintro" accesskey="u"
rel="up">perluniintro</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="ACKNOWLEDGMENTS"></a>
-<h3 class="section">83.5 ACKNOWLEDGMENTS</h3>
-
-<p>Thanks to the kind readers of the address@hidden,
address@hidden, address@hidden, and address@hidden
-mailing lists for their valuable feedback.
-</p>
-<hr>
-<a name="perluniintro-AUTHOR_002c-COPYRIGHT_002c-AND-LICENSE"></a>
-<div class="header">
-<p>
-Previous: <a href="#perluniintro-ACKNOWLEDGMENTS" accesskey="p"
rel="prev">perluniintro ACKNOWLEDGMENTS</a>, Up: <a href="#perluniintro"
accesskey="u" rel="up">perluniintro</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR_002c-COPYRIGHT_002c-AND-LICENSE"></a>
-<h3 class="section">83.6 AUTHOR, COPYRIGHT, AND LICENSE</h3>
-
-<p>Copyright 2001-2011 Jarkko Hietaniemi <address@hidden>.
-Now maintained by Perl 5 Porters.
-</p>
-<p>This document may be distributed under the same terms as Perl itself.
-</p>
-<hr>
-<a name="perlunitut"></a>
-<div class="header">
-<p>
-Next: <a href="#perlutil" accesskey="n" rel="next">perlutil</a>, Previous: <a
href="#perluniintro" accesskey="p" rel="prev">perluniintro</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlunitut-1"></a>
-<h2 class="chapter">84 perlunitut</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlunitut-NAME"
accesskey="1">perlunitut NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunitut-DESCRIPTION"
accesskey="2">perlunitut DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunitut-SUMMARY"
accesskey="3">perlunitut SUMMARY</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-Q-and-A-_0028or-FAQ_0029" accesskey="4">perlunitut Q and A
(or FAQ)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-ACKNOWLEDGEMENTS" accesskey="5">perlunitut
ACKNOWLEDGEMENTS</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunitut-AUTHOR"
accesskey="6">perlunitut AUTHOR</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunitut-SEE-ALSO"
accesskey="7">perlunitut SEE ALSO</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlunitut-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunitut-DESCRIPTION" accesskey="n" rel="next">perlunitut
DESCRIPTION</a>, Up: <a href="#perlunitut" accesskey="u"
rel="up">perlunitut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-83"></a>
-<h3 class="section">84.1 NAME</h3>
-
-<p>perlunitut - Perl Unicode Tutorial
-</p>
-<hr>
-<a name="perlunitut-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunitut-SUMMARY" accesskey="n" rel="next">perlunitut
SUMMARY</a>, Previous: <a href="#perlunitut-NAME" accesskey="p"
rel="prev">perlunitut NAME</a>, Up: <a href="#perlunitut" accesskey="u"
rel="up">perlunitut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-81"></a>
-<h3 class="section">84.2 DESCRIPTION</h3>
-
-<p>The days of just flinging strings around are over. It’s well
established that
-modern programs need to be capable of communicating funny accented letters, and
-things like euro symbols. This means that programmers need new habits.
It’s
-easy to program Unicode capable software, but it does require discipline to do
-it right.
-</p>
-<p>There’s a lot to know about character sets, and text encodings.
It’s probably
-best to spend a full day learning all this, but the basics can be learned in
-minutes.
-</p>
-<p>These are not the very basics, though. It is assumed that you already
-know the difference between bytes and characters, and realise (and accept!)
-that there are many different character sets and encodings, and that your
-program has to be explicit about them. Recommended reading is "The
Absolute
-Minimum Every Software Developer Absolutely, Positively Must Know About Unicode
-and Character Sets (No Excuses!)" by Joel Spolsky, at
-<a
href="http://joelonsoftware.com/articles/Unicode.html";>http://joelonsoftware.com/articles/Unicode.html</a>.
-</p>
-<p>This tutorial speaks in rather absolute terms, and provides only a limited
view
-of the wealth of character string related features that Perl has to offer. For
-most projects, this information will probably suffice.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlunitut-Definitions"
accesskey="1">perlunitut Definitions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-Your-new-toolkit" accesskey="2">perlunitut Your new
toolkit</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-I_002fO-flow-_0028the-actual-5-minute-tutorial_0029"
accesskey="3">perlunitut I/O flow (the actual 5 minute
tutorial)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlunitut-Definitions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunitut-Your-new-toolkit" accesskey="n"
rel="next">perlunitut Your new toolkit</a>, Up: <a
href="#perlunitut-DESCRIPTION" accesskey="u" rel="up">perlunitut
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Definitions-1"></a>
-<h4 class="subsection">84.2.1 Definitions</h4>
-
-<p>It’s important to set a few things straight first. This is the most
important
-part of this tutorial. This view may conflict with other information that you
-may have found on the web, but that’s mostly because many sources are
wrong.
-</p>
-<p>You may have to re-read this entire section a few times...
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlunitut-Unicode"
accesskey="1">perlunitut Unicode</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunitut-UTF_002d8"
accesskey="2">perlunitut UTF-8</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-Text-strings-_0028character-strings_0029"
accesskey="3">perlunitut Text strings (character
strings)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlunitut-Binary-strings-_0028byte-strings_0029"
accesskey="4">perlunitut Binary strings (byte
strings)</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunitut-Encoding"
accesskey="5">perlunitut Encoding</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunitut-Decoding"
accesskey="6">perlunitut Decoding</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlunitut-Internal-format"
accesskey="7">perlunitut Internal format</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlunitut-Unicode"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunitut-UTF_002d8" accesskey="n" rel="next">perlunitut
UTF-8</a>, Up: <a href="#perlunitut-Definitions" accesskey="u"
rel="up">perlunitut Definitions</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Unicode-3"></a>
-<h4 class="subsubsection">84.2.1.1 Unicode</h4>
-
-<p><strong>Unicode</strong> is a character set with room for lots of
characters. The ordinal
-value of a character is called a <strong>code point</strong>. (But in
practice, the
-distinction between code point and character is blurred, so the terms often
-are used interchangeably.)
-</p>
-<p>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 than that,
-so you need a method to make these accessible.
-</p>
-<p>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
-store a single code point, or simply: character.
-</p>
-<hr>
-<a name="perlunitut-UTF_002d8"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunitut-Text-strings-_0028character-strings_0029"
accesskey="n" rel="next">perlunitut Text strings (character strings)</a>,
Previous: <a href="#perlunitut-Unicode" accesskey="p" rel="prev">perlunitut
Unicode</a>, Up: <a href="#perlunitut-Definitions" accesskey="u"
rel="up">perlunitut Definitions</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="UTF_002d8"></a>
-<h4 class="subsubsection">84.2.1.2 UTF-8</h4>
-
-<p><strong>UTF-8</strong> is a Unicode encoding. Many people think that
Unicode and UTF-8 are
-the same thing, but they’re not. There are more Unicode encodings, but
much of
-the world has standardized on UTF-8.
-</p>
-<p>UTF-8 treats the first 128 codepoints, 0..127, the same as ASCII. They take
-only one byte per character. All other characters are encoded as two to
-four bytes using a complex scheme. Fortunately, Perl handles this for
-us, so we don’t have to worry about this.
-</p>
-<hr>
-<a name="perlunitut-Text-strings-_0028character-strings_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunitut-Binary-strings-_0028byte-strings_0029"
accesskey="n" rel="next">perlunitut Binary strings (byte strings)</a>,
Previous: <a href="#perlunitut-UTF_002d8" accesskey="p" rel="prev">perlunitut
UTF-8</a>, Up: <a href="#perlunitut-Definitions" accesskey="u"
rel="up">perlunitut Definitions</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Text-strings-_0028character-strings_0029"></a>
-<h4 class="subsubsection">84.2.1.3 Text strings (character strings)</h4>
-
-<p><strong>Text strings</strong>, or <strong>character strings</strong> are
made of characters. Bytes are
-irrelevant here, and so are encodings. Each character is just that: the
-character.
-</p>
-<p>On a text string, you would do things like:
-</p>
-<pre class="verbatim"> $text =~ s/foo/bar/;
- if ($string =~ /^\d+$/) { ... }
- $text = ucfirst $text;
- my $character_count = length $text;
-</pre>
-<p>The value of a character (<code>ord</code>, <code>chr</code>) is the
corresponding Unicode code
-point.
-</p>
-<hr>
-<a name="perlunitut-Binary-strings-_0028byte-strings_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunitut-Encoding" accesskey="n" rel="next">perlunitut
Encoding</a>, Previous: <a
href="#perlunitut-Text-strings-_0028character-strings_0029" accesskey="p"
rel="prev">perlunitut Text strings (character strings)</a>, Up: <a
href="#perlunitut-Definitions" accesskey="u" rel="up">perlunitut
Definitions</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Binary-strings-_0028byte-strings_0029"></a>
-<h4 class="subsubsection">84.2.1.4 Binary strings (byte strings)</h4>
-
-<p><strong>Binary strings</strong>, or <strong>byte strings</strong> are made
of bytes. Here, you don’t have
-characters, just bytes. All communication with the outside world (anything
-outside of your current Perl process) is done in binary.
-</p>
-<p>On a binary string, you would do things like:
-</p>
-<pre class="verbatim"> my (@length_content) = unpack "(V/a)*",
$binary;
- $binary =~ s/\x00\x0F/\xFF\xF0/; # for the brave :)
- print {$fh} $binary;
- my $byte_count = length $binary;
-</pre>
-<hr>
-<a name="perlunitut-Encoding"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunitut-Decoding" accesskey="n" rel="next">perlunitut
Decoding</a>, Previous: <a
href="#perlunitut-Binary-strings-_0028byte-strings_0029" accesskey="p"
rel="prev">perlunitut Binary strings (byte strings)</a>, Up: <a
href="#perlunitut-Definitions" accesskey="u" rel="up">perlunitut
Definitions</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Encoding"></a>
-<h4 class="subsubsection">84.2.1.5 Encoding</h4>
-
-<p><strong>Encoding</strong> (as a verb) is the conversion from <em>text</em>
to <em>binary</em>. To encode,
-you have to supply the target encoding, for example <code>iso-8859-1</code> or
<code>UTF-8</code>.
-Some encodings, like the <code>iso-8859</code> ("latin") range, do
not support the full
-Unicode standard; characters that can’t be represented are lost in the
-conversion.
-</p>
-<hr>
-<a name="perlunitut-Decoding"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunitut-Internal-format" accesskey="n"
rel="next">perlunitut Internal format</a>, Previous: <a
href="#perlunitut-Encoding" accesskey="p" rel="prev">perlunitut Encoding</a>,
Up: <a href="#perlunitut-Definitions" accesskey="u" rel="up">perlunitut
Definitions</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Decoding"></a>
-<h4 class="subsubsection">84.2.1.6 Decoding</h4>
-
-<p><strong>Decoding</strong> is the conversion from <em>binary</em> to
<em>text</em>. To decode, you have to
-know what encoding was used during the encoding phase. And most of all, it must
-be something decodable. It doesn’t make much sense to decode a PNG image
into a
-text string.
-</p>
-<hr>
-<a name="perlunitut-Internal-format"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlunitut-Decoding" accesskey="p" rel="prev">perlunitut
Decoding</a>, Up: <a href="#perlunitut-Definitions" accesskey="u"
rel="up">perlunitut Definitions</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Internal-format"></a>
-<h4 class="subsubsection">84.2.1.7 Internal format</h4>
-
-<p>Perl has an <strong>internal format</strong>, an encoding that it uses to
encode text strings
-so it can store them in memory. All text strings are in this internal format.
-In fact, text strings are never in any other format!
-</p>
-<p>You shouldn’t worry about what this format is, because conversion is
-automatically done when you decode or encode.
-</p>
-<hr>
-<a name="perlunitut-Your-new-toolkit"></a>
-<div class="header">
-<p>
-Next: <a
href="#perlunitut-I_002fO-flow-_0028the-actual-5-minute-tutorial_0029"
accesskey="n" rel="next">perlunitut I/O flow (the actual 5 minute
tutorial)</a>, Previous: <a href="#perlunitut-Definitions" accesskey="p"
rel="prev">perlunitut Definitions</a>, Up: <a href="#perlunitut-DESCRIPTION"
accesskey="u" rel="up">perlunitut DESCRIPTION</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Your-new-toolkit"></a>
-<h4 class="subsection">84.2.2 Your new toolkit</h4>
-
-<p>Add to your standard heading the following line:
-</p>
-<pre class="verbatim"> use Encode qw(encode decode);
-</pre>
-<p>Or, if you’re lazy, just:
-</p>
-<pre class="verbatim"> use Encode;
-</pre>
-<hr>
-<a name="perlunitut-I_002fO-flow-_0028the-actual-5-minute-tutorial_0029"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlunitut-Your-new-toolkit" accesskey="p"
rel="prev">perlunitut Your new toolkit</a>, Up: <a
href="#perlunitut-DESCRIPTION" accesskey="u" rel="up">perlunitut
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="I_002fO-flow-_0028the-actual-5-minute-tutorial_0029"></a>
-<h4 class="subsection">84.2.3 I/O flow (the actual 5 minute tutorial)</h4>
-
-<p>The typical input/output flow of a program is:
-</p>
-<pre class="verbatim"> 1. Receive and decode
- 2. Process
- 3. Encode and output
-</pre>
-<p>If your input is binary, and is supposed to remain binary, you
shouldn’t decode
-it to a text string, of course. But in all other cases, you should decode it.
-</p>
-<p>Decoding can’t happen reliably if you don’t know how the data
was encoded. If
-you get to choose, it’s a good idea to standardize on UTF-8.
-</p>
-<pre class="verbatim"> my $foo = decode('UTF-8', get
'http://example.com/');
- my $bar = decode('ISO-8859-1', readline STDIN);
- my $xyzzy = decode('Windows-1251', $cgi->param('foo'));
-</pre>
-<p>Processing happens as you knew before. The only difference is that
you’re now
-using characters instead of bytes. That’s very useful if you use things
like
-<code>substr</code>, or <code>length</code>.
-</p>
-<p>It’s important to realize that there are no bytes in a text string.
Of course,
-Perl has its internal encoding to store the string in memory, but ignore that.
-If you have to do anything with the number of bytes, it’s probably best
to move
-that part to step 3, just after you’ve encoded the string. Then you know
-exactly how many bytes it will be in the destination string.
-</p>
-<p>The syntax for encoding text strings to binary strings is as simple as
decoding:
-</p>
-<pre class="verbatim"> $body = encode('UTF-8', $body);
-</pre>
-<p>If you needed to know the length of the string in bytes, now’s the
perfect time
-for that. Because <code>$body</code> is now a byte string, <code>length</code>
will report the
-number of bytes, instead of the number of characters. The number of
-characters is no longer known, because characters only exist in text strings.
-</p>
-<pre class="verbatim"> my $byte_count = length $body;
-</pre>
-<p>And if the protocol you’re using supports a way of letting the
recipient know
-which character encoding you used, please help the receiving end by using that
-feature! For example, E-mail and HTTP support MIME headers, so you can use the
-<code>Content-Type</code> header. They can also have
<code>Content-Length</code> to indicate the
-number of <em>bytes</em>, which is always a good idea to supply if the number
is
-known.
-</p>
-<pre class="verbatim"> "Content-Type: text/plain; charset=UTF-8",
- "Content-Length: $byte_count"
-</pre>
-<hr>
-<a name="perlunitut-SUMMARY"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunitut-Q-and-A-_0028or-FAQ_0029" accesskey="n"
rel="next">perlunitut Q and A (or FAQ)</a>, Previous: <a
href="#perlunitut-DESCRIPTION" accesskey="p" rel="prev">perlunitut
DESCRIPTION</a>, Up: <a href="#perlunitut" accesskey="u"
rel="up">perlunitut</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SUMMARY-1"></a>
-<h3 class="section">84.3 SUMMARY</h3>
-
-<p>Decode everything you receive, encode everything you send out. (If
it’s text
-data.)
-</p>
-<hr>
-<a name="perlunitut-Q-and-A-_0028or-FAQ_0029"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunitut-ACKNOWLEDGEMENTS" accesskey="n"
rel="next">perlunitut ACKNOWLEDGEMENTS</a>, Previous: <a
href="#perlunitut-SUMMARY" accesskey="p" rel="prev">perlunitut SUMMARY</a>, Up:
<a href="#perlunitut" accesskey="u" rel="up">perlunitut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Q-and-A-_0028or-FAQ_0029"></a>
-<h3 class="section">84.4 Q and A (or FAQ)</h3>
-
-<p>After reading this document, you ought to read <a
href="#perlunifaq-NAME">perlunifaq NAME</a> too, then
-<a href="#perluniintro-NAME">perluniintro NAME</a>.
-</p>
-<hr>
-<a name="perlunitut-ACKNOWLEDGEMENTS"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunitut-AUTHOR" accesskey="n" rel="next">perlunitut
AUTHOR</a>, Previous: <a href="#perlunitut-Q-and-A-_0028or-FAQ_0029"
accesskey="p" rel="prev">perlunitut Q and A (or FAQ)</a>, Up: <a
href="#perlunitut" accesskey="u" rel="up">perlunitut</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="ACKNOWLEDGEMENTS-1"></a>
-<h3 class="section">84.5 ACKNOWLEDGEMENTS</h3>
-
-<p>Thanks to Johan Vromans from Squirrel Consultancy. His UTF-8 rants during
the
-Amsterdam Perl Mongers meetings got me interested and determined to find out
-how to use character encodings in Perl in ways that don’t break easily.
-</p>
-<p>Thanks to Gerard Goossen from TTY. His presentation "UTF-8 in the
wild" (Dutch
-Perl Workshop 2006) inspired me to publish my thoughts and write this tutorial.
-</p>
-<p>Thanks to the people who asked about this kind of stuff in several Perl IRC
-channels, and have constantly reminded me that a simpler explanation was
-needed.
-</p>
-<p>Thanks to the people who reviewed this document for me, before it went
public.
-They are: Benjamin Smith, Jan-Pieter Cornet, Johan Vromans, Lukas Mai, Nathan
-Gray.
-</p>
-<hr>
-<a name="perlunitut-AUTHOR"></a>
-<div class="header">
-<p>
-Next: <a href="#perlunitut-SEE-ALSO" accesskey="n" rel="next">perlunitut SEE
ALSO</a>, Previous: <a href="#perlunitut-ACKNOWLEDGEMENTS" accesskey="p"
rel="prev">perlunitut ACKNOWLEDGEMENTS</a>, Up: <a href="#perlunitut"
accesskey="u" rel="up">perlunitut</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-30"></a>
-<h3 class="section">84.6 AUTHOR</h3>
-
-<p>Juerd Waalboer <address@hidden>
-</p>
-<hr>
-<a name="perlunitut-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlunitut-AUTHOR" accesskey="p" rel="prev">perlunitut
AUTHOR</a>, Up: <a href="#perlunitut" accesskey="u" rel="up">perlunitut</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-43"></a>
-<h3 class="section">84.7 SEE ALSO</h3>
-
-<p><a href="#perlunifaq-NAME">perlunifaq NAME</a>, <a
href="#perlunicode-NAME">perlunicode NAME</a>, <a
href="#perluniintro-NAME">perluniintro NAME</a>, <a
href="Encode.html#Top">(Encode)</a>
-</p>
-<hr>
-<a name="perlutil"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvar" accesskey="n" rel="next">perlvar</a>, Previous: <a
href="#perlunitut" accesskey="p" rel="prev">perlunitut</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlutil-1"></a>
-<h2 class="chapter">85 perlutil</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlutil-NAME"
accesskey="1">perlutil NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlutil-DESCRIPTION"
accesskey="2">perlutil DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlutil-LIST-OF-UTILITIES"
accesskey="3">perlutil LIST OF UTILITIES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlutil-SEE-ALSO"
accesskey="4">perlutil SEE ALSO</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlutil-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlutil-DESCRIPTION" accesskey="n" rel="next">perlutil
DESCRIPTION</a>, Up: <a href="#perlutil" accesskey="u" rel="up">perlutil</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-84"></a>
-<h3 class="section">85.1 NAME</h3>
-
-<p>perlutil - utilities packaged with the Perl distribution
-</p>
-<hr>
-<a name="perlutil-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlutil-LIST-OF-UTILITIES" accesskey="n" rel="next">perlutil
LIST OF UTILITIES</a>, Previous: <a href="#perlutil-NAME" accesskey="p"
rel="prev">perlutil NAME</a>, Up: <a href="#perlutil" accesskey="u"
rel="up">perlutil</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-82"></a>
-<h3 class="section">85.2 DESCRIPTION</h3>
-
-<p>Along with the Perl interpreter itself, the Perl distribution installs a
-range of utilities on your system. There are also several utilities
-which are used by the Perl distribution itself as part of the install
-process. This document exists to list all of these utilities, explain
-what they are for and provide pointers to each module’s documentation,
-if appropriate.
-</p>
-<hr>
-<a name="perlutil-LIST-OF-UTILITIES"></a>
-<div class="header">
-<p>
-Next: <a href="#perlutil-SEE-ALSO" accesskey="n" rel="next">perlutil SEE
ALSO</a>, Previous: <a href="#perlutil-DESCRIPTION" accesskey="p"
rel="prev">perlutil DESCRIPTION</a>, Up: <a href="#perlutil" accesskey="u"
rel="up">perlutil</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="LIST-OF-UTILITIES"></a>
-<h3 class="section">85.3 LIST OF UTILITIES</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlutil-Documentation"
accesskey="1">perlutil Documentation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlutil-Converters"
accesskey="2">perlutil Converters</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlutil-Administration"
accesskey="3">perlutil Administration</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlutil-Development"
accesskey="4">perlutil Development</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlutil-General-tools"
accesskey="5">perlutil General tools</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlutil-Installation"
accesskey="6">perlutil Installation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlutil-Documentation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlutil-Converters" accesskey="n" rel="next">perlutil
Converters</a>, Up: <a href="#perlutil-LIST-OF-UTILITIES" accesskey="u"
rel="up">perlutil LIST OF UTILITIES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Documentation-2"></a>
-<h4 class="subsection">85.3.1 Documentation</h4>
-
-<dl compact="compact">
-<dt><a href="perldoc.html#Top">(perldoc)perldoc</a></dt>
-<dd><a name="perlutil-perldoc"></a>
-<p>The main interface to Perl’s documentation is <code>perldoc</code>,
although
-if you’re reading this, it’s more than likely that you’ve
already found
-it. <samp>perldoc</samp> will extract and format the documentation from any
file
-in the current directory, any Perl module installed on the system, or
-any of the standard documentation pages, such as this one. Use
-<code>perldoc <name></code> to get information on any of the utilities
-described in this document.
-</p>
-</dd>
-<dt><a href="pod2man.html#Top">(pod2man)pod2man</a> and <a
href="pod2text.html#Top">(pod2text)pod2text</a></dt>
-<dd><a name="perlutil-pod2man-and-pod2text"></a>
-<p>If it’s run from a terminal, <samp>perldoc</samp> will usually call
<samp>pod2man</samp> to
-translate POD (Plain Old Documentation - see <a href="#perlpod-NAME">perlpod
NAME</a> for an
-explanation) into a manpage, and then run <samp>man</samp> to display it; if
-<samp>man</samp> isn’t available, <samp>pod2text</samp> will be used
instead and the output
-piped through your favourite pager.
-</p>
-</dd>
-<dt><a href="pod2html.html#Top">(pod2html)pod2html</a></dt>
-<dd><a name="perlutil-pod2html"></a>
-<p>As well as these two, there is another converter: <samp>pod2html</samp> will
-produce HTML pages from POD.
-</p>
-</dd>
-<dt><a href="pod2usage.html#Top">(pod2usage)pod2usage</a></dt>
-<dd><a name="perlutil-pod2usage"></a>
-<p>If you just want to know how to use the utilities described here,
-<samp>pod2usage</samp> will just extract the "USAGE" section; some of
-the utilities will automatically call <samp>pod2usage</samp> on themselves when
-you call them with <code>-help</code>.
-</p>
-</dd>
-<dt><a href="podselect.html#Top">(podselect)podselect</a></dt>
-<dd><a name="perlutil-podselect"></a>
-<p><samp>pod2usage</samp> is a special case of <samp>podselect</samp>, a
utility to extract
-named sections from documents written in POD. For instance, while
-utilities have "USAGE" sections, Perl modules usually have
"SYNOPSIS"
-sections: <code>podselect -s "SYNOPSIS" ...</code> will extract this
section for
-a given file.
-</p>
-</dd>
-<dt><a href="podchecker.html#Top">(podchecker)podchecker</a></dt>
-<dd><a name="perlutil-podchecker"></a>
-<p>If you’re writing your own documentation in POD, the
<samp>podchecker</samp>
-utility will look for errors in your markup.
-</p>
-</dd>
-<dt><a href="splain.html#Top">(splain)splain</a></dt>
-<dd><a name="perlutil-splain"></a>
-<p><samp>splain</samp> is an interface to <a href="#perldiag-NAME">perldiag
NAME</a> - paste in your error message
-to it, and it’ll explain it for you.
-</p>
-</dd>
-<dt><code>roffitall</code></dt>
-<dd><a name="perlutil-roffitall"></a>
-<p>The <code>roffitall</code> utility is not installed on your system but
lives in
-the <samp>pod/</samp> directory of your Perl source kit; it converts all the
-documentation from the distribution to <samp>*roff</samp> format, and produces
a
-typeset PostScript or text file of the whole lot.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlutil-Converters"></a>
-<div class="header">
-<p>
-Next: <a href="#perlutil-Administration" accesskey="n" rel="next">perlutil
Administration</a>, Previous: <a href="#perlutil-Documentation" accesskey="p"
rel="prev">perlutil Documentation</a>, Up: <a
href="#perlutil-LIST-OF-UTILITIES" accesskey="u" rel="up">perlutil LIST OF
UTILITIES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Converters"></a>
-<h4 class="subsection">85.3.2 Converters</h4>
-
-<p>To help you convert legacy programs to more modern Perl, the
-<a href="pl2pm.html#Top">(pl2pm)pl2pm</a> utility will help you convert
old-style Perl 4 libraries
-to new-style Perl5 modules.
-</p>
-<hr>
-<a name="perlutil-Administration"></a>
-<div class="header">
-<p>
-Next: <a href="#perlutil-Development" accesskey="n" rel="next">perlutil
Development</a>, Previous: <a href="#perlutil-Converters" accesskey="p"
rel="prev">perlutil Converters</a>, Up: <a href="#perlutil-LIST-OF-UTILITIES"
accesskey="u" rel="up">perlutil LIST OF UTILITIES</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Administration"></a>
-<h4 class="subsection">85.3.3 Administration</h4>
-
-<dl compact="compact">
-<dt><a href="libnetcfg.html#Top">(libnetcfg)libnetcfg</a></dt>
-<dd><a name="perlutil-libnetcfg"></a>
-<p>To display and change the libnet configuration run the libnetcfg command.
-</p>
-</dd>
-<dt><a href="perlivp.html#Top">(perlivp)</a></dt>
-<dd><a name="perlutil-perlivp"></a>
-<p>The <samp>perlivp</samp> program is set up at Perl source code build time
to test
-the Perl version it was built under. It can be used after running <code>make
-install</code> (or your platform’s equivalent procedure) to verify that
perl
-and its libraries have been installed correctly.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlutil-Development"></a>
-<div class="header">
-<p>
-Next: <a href="#perlutil-General-tools" accesskey="n" rel="next">perlutil
General tools</a>, Previous: <a href="#perlutil-Administration" accesskey="p"
rel="prev">perlutil Administration</a>, Up: <a
href="#perlutil-LIST-OF-UTILITIES" accesskey="u" rel="up">perlutil LIST OF
UTILITIES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Development"></a>
-<h4 class="subsection">85.3.4 Development</h4>
-
-<p>There are a set of utilities which help you in developing Perl programs,
-and in particular, extending Perl with C.
-</p>
-<dl compact="compact">
-<dt><a href="perlbug.html#Top">(perlbug)perlbug</a></dt>
-<dd><a name="perlutil-perlbug"></a>
-<p><samp>perlbug</samp> is the recommended way to report bugs in the perl
interpreter
-itself or any of the standard library modules back to the developers;
-please read through the documentation for <samp>perlbug</samp> thoroughly
before
-using it to submit a bug report.
-</p>
-</dd>
-<dt><a href="perlbug.html#Top">(perlbug)perlthanks</a></dt>
-<dd><a name="perlutil-perlthanks"></a>
-<p>This program provides an easy way to send a thank-you message back to the
-authors and maintainers of perl. It’s just <samp>perlbug</samp>
installed under
-another name.
-</p>
-</dd>
-<dt><a href="h2ph.html#Top">(h2ph)h2ph</a></dt>
-<dd><a name="perlutil-h2ph"></a>
-<p>Back before Perl had the XS system for connecting with C libraries,
-programmers used to get library constants by reading through the C
-header files. You may still see <code>require 'syscall.ph'</code> or similar
-around - the <samp>.ph</samp> file should be created by running
<samp>h2ph</samp> on the
-corresponding <samp>.h</samp> file. See the <samp>h2ph</samp> documentation
for more on how
-to convert a whole bunch of header files at once.
-</p>
-</dd>
-<dt><a href="c2ph.html#Top">(c2ph)c2ph</a> and <a
href="pstruct.html#Top">(pstruct)pstruct</a></dt>
-<dd><a name="perlutil-c2ph-and-pstruct"></a>
-<p><samp>c2ph</samp> and <samp>pstruct</samp>, which are actually the same
program but behave
-differently depending on how they are called, provide another way of
-getting at C with Perl - they’ll convert C structures and union
declarations
-to Perl code. This is deprecated in favour of <samp>h2xs</samp> these days.
-</p>
-</dd>
-<dt><a href="h2xs.html#Top">(h2xs)h2xs</a></dt>
-<dd><a name="perlutil-h2xs"></a>
-<p><samp>h2xs</samp> converts C header files into XS modules, and will try and
write
-as much glue between C libraries and Perl modules as it can. It’s also
-very useful for creating skeletons of pure Perl modules.
-</p>
-</dd>
-<dt><a href="enc2xs.html#Top">(enc2xs)</a></dt>
-<dd><a name="perlutil-enc2xs"></a>
-<p><samp>enc2xs</samp> builds a Perl extension for use by Encode from either
-Unicode Character Mapping files (.ucm) or Tcl Encoding Files (.enc).
-Besides being used internally during the build process of the Encode
-module, you can use <samp>enc2xs</samp> to add your own encoding to perl.
-No knowledge of XS is necessary.
-</p>
-</dd>
-<dt><a href="xsubpp.html#Top">(xsubpp)</a></dt>
-<dd><a name="perlutil-xsubpp"></a>
-<p><samp>xsubpp</samp> is a compiler to convert Perl XS code into C code.
-It is typically run by the makefiles created by <a
href="ExtUtils-MakeMaker.html#Top">(ExtUtils-MakeMaker)</a>.
-</p>
-<p><samp>xsubpp</samp> will compile XS code into C code by embedding the
constructs
-necessary to let C functions manipulate Perl values and creates the glue
-necessary to let Perl access those functions.
-</p>
-</dd>
-<dt><a href="prove.html#Top">(prove)</a></dt>
-<dd><a name="perlutil-prove"></a>
-<p><samp>prove</samp> is a command-line interface to the test-running
functionality
-of <samp>Test::Harness</samp>. It’s an alternative to <code>make
test</code>.
-</p>
-</dd>
-<dt><a href="corelist.html#Top">(corelist)</a></dt>
-<dd><a name="perlutil-corelist"></a>
-<p>A command-line front-end to <code>Module::CoreList</code>, to query what
modules
-were shipped with given versions of perl.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlutil-General-tools"></a>
-<div class="header">
-<p>
-Next: <a href="#perlutil-Installation" accesskey="n" rel="next">perlutil
Installation</a>, Previous: <a href="#perlutil-Development" accesskey="p"
rel="prev">perlutil Development</a>, Up: <a href="#perlutil-LIST-OF-UTILITIES"
accesskey="u" rel="up">perlutil LIST OF UTILITIES</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="General-tools"></a>
-<h4 class="subsection">85.3.5 General tools</h4>
-
-<p>A few general-purpose tools are shipped with perl, mostly because they
-came along modules included in the perl distribution.
-</p>
-<dl compact="compact">
-<dt><a href="piconv.html#Top">(piconv)</a></dt>
-<dd><a name="perlutil-piconv"></a>
-<p><strong>piconv</strong> is a Perl version of <strong>iconv</strong>, a
character encoding converter
-widely available for various Unixen today. This script was primarily a
-technology demonstrator for Perl v5.8.0, but you can use piconv in the
-place of iconv for virtually any case.
-</p>
-</dd>
-<dt><a href="ptar.html#Top">(ptar)</a></dt>
-<dd><a name="perlutil-ptar"></a>
-<p><samp>ptar</samp> is a tar-like program, written in pure Perl.
-</p>
-</dd>
-<dt><a href="ptardiff.html#Top">(ptardiff)</a></dt>
-<dd><a name="perlutil-ptardiff"></a>
-<p><samp>ptardiff</samp> is a small utility that produces a diff between an
extracted
-archive and an unextracted one. (Note that this utility requires the
-<code>Text::Diff</code> module to function properly; this module isn’t
distributed
-with perl, but is available from the CPAN.)
-</p>
-</dd>
-<dt><a href="ptargrep.html#Top">(ptargrep)</a></dt>
-<dd><a name="perlutil-ptargrep"></a>
-<p><samp>ptargrep</samp> is a utility to apply pattern matching to the
contents of files
-in a tar archive.
-</p>
-</dd>
-<dt><a href="shasum.html#Top">(shasum)</a></dt>
-<dd><a name="perlutil-shasum"></a>
-<p>This utility, that comes with the <code>Digest::SHA</code> module, is used
to print
-or verify SHA checksums.
-</p>
-</dd>
-<dt><a href="zipdetails.html#Top">(zipdetails)</a></dt>
-<dd><a name="perlutil-zipdetails"></a>
-<p><a href="zipdetails.html#Top">(zipdetails)</a> displays information about
the internal record structure of the zip file.
-It is not concerned with displaying any details of the compressed data stored
in the zip file.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlutil-Installation"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlutil-General-tools" accesskey="p" rel="prev">perlutil
General tools</a>, Up: <a href="#perlutil-LIST-OF-UTILITIES" accesskey="u"
rel="up">perlutil LIST OF UTILITIES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Installation"></a>
-<h4 class="subsection">85.3.6 Installation</h4>
-
-<p>These utilities help manage extra Perl modules that don’t come with
the perl
-distribution.
-</p>
-<dl compact="compact">
-<dt><a href="cpan.html#Top">(cpan)</a></dt>
-<dd><a name="perlutil-cpan"></a>
-<p><samp>cpan</samp> is a command-line interface to CPAN.pm. It allows you to
install
-modules or distributions from CPAN, or just get information about them, and
-a lot more. It is similar to the command line mode of the <a
href="CPAN.html#Top">(CPAN)</a> module,
-</p>
-<pre class="verbatim"> perl -MCPAN -e shell
-</pre>
-</dd>
-<dt><a href="instmodsh.html#Top">(instmodsh)</a></dt>
-<dd><a name="perlutil-instmodsh"></a>
-<p>A little interface to ExtUtils::Installed to examine installed modules,
-validate your packlists and even create a tarball from an installed module.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlutil-SEE-ALSO"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlutil-LIST-OF-UTILITIES" accesskey="p"
rel="prev">perlutil LIST OF UTILITIES</a>, Up: <a href="#perlutil"
accesskey="u" rel="up">perlutil</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="SEE-ALSO-44"></a>
-<h3 class="section">85.4 SEE ALSO</h3>
-
-<p><a href="perldoc.html#Top">(perldoc)perldoc</a>, <a
href="pod2man.html#Top">(pod2man)pod2man</a>, <a href="#perlpod-NAME">perlpod
NAME</a>,
-<a href="pod2html.html#Top">(pod2html)pod2html</a>, <a
href="pod2usage.html#Top">(pod2usage)pod2usage</a>, <a
href="podselect.html#Top">(podselect)podselect</a>,
-<a href="podchecker.html#Top">(podchecker)podchecker</a>, <a
href="splain.html#Top">(splain)splain</a>, <a href="#perldiag-NAME">perldiag
NAME</a>,
-<code>roffitall|roffitall</code>, <a
href="File-Find.html#Top">(File-Find)File::Find</a>, <a
href="pl2pm.html#Top">(pl2pm)pl2pm</a>,
-<a href="perlbug.html#Top">(perlbug)perlbug</a>, <a
href="h2ph.html#Top">(h2ph)h2ph</a>, <a href="c2ph.html#Top">(c2ph)c2ph</a>, <a
href="h2xs.html#Top">(h2xs)h2xs</a>, <a href="enc2xs.html#Top">(enc2xs)</a>,
-<a href="xsubpp.html#Top">(xsubpp)</a>, <a href="cpan.html#Top">(cpan)</a>, <a
href="instmodsh.html#Top">(instmodsh)</a>, <a
href="piconv.html#Top">(piconv)</a>, <a href="prove.html#Top">(prove)</a>, <a
href="corelist.html#Top">(corelist)</a>, <a href="ptar.html#Top">(ptar)</a>,
-<a href="ptardiff.html#Top">(ptardiff)</a>, <a
href="shasum.html#Top">(shasum)</a>, <a
href="zipdetails.html#Top">(zipdetails)</a>
-</p>
-<hr>
-<a name="perlvar"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms" accesskey="n" rel="next">perlvms</a>, Previous: <a
href="#perlutil" accesskey="p" rel="prev">perlutil</a>, Up: <a href="#Top"
accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlvar-1"></a>
-<h2 class="chapter">86 perlvar</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlvar-NAME"
accesskey="1">perlvar NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlvar-DESCRIPTION"
accesskey="2">perlvar DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlvar-SPECIAL-VARIABLES"
accesskey="3">perlvar SPECIAL VARIABLES</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlvar-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvar-DESCRIPTION" accesskey="n" rel="next">perlvar
DESCRIPTION</a>, Up: <a href="#perlvar" accesskey="u" rel="up">perlvar</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-85"></a>
-<h3 class="section">86.1 NAME</h3>
-
-<p>perlvar - Perl predefined variables
-</p>
-<hr>
-<a name="perlvar-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvar-SPECIAL-VARIABLES" accesskey="n" rel="next">perlvar
SPECIAL VARIABLES</a>, Previous: <a href="#perlvar-NAME" accesskey="p"
rel="prev">perlvar NAME</a>, Up: <a href="#perlvar" accesskey="u"
rel="up">perlvar</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-83"></a>
-<h3 class="section">86.2 DESCRIPTION</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlvar-The-Syntax-of-Variable-Names" accesskey="1">perlvar The Syntax
of Variable Names</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlvar-The-Syntax-of-Variable-Names"></a>
-<div class="header">
-<p>
-Up: <a href="#perlvar-DESCRIPTION" accesskey="u" rel="up">perlvar
DESCRIPTION</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-Syntax-of-Variable-Names"></a>
-<h4 class="subsection">86.2.1 The Syntax of Variable Names</h4>
-
-<p>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
-<code>::</code> or <code>'</code>. In this case, the part before the last
<code>::</code> or
-<code>'</code> is taken to be a <em>package qualifier</em>; see <a
href="#perlmod-NAME">perlmod NAME</a>.
-</p>
-<p>Perl variable names may also be a sequence of digits or a single
-punctuation or control character (with the literal control character
-form deprecated). 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 <code>^X</code> (caret <code>X</code>) to mean the
control-<code>X</code>
-character. For example, the notation <code>$^W</code> (dollar-sign caret
-<code>W</code>) is the scalar variable whose name is the single character
-control-<code>W</code>. This is better than typing a literal
control-<code>W</code>
-into your program.
-</p>
-<p>Since Perl v5.6.0, Perl variable names may be alphanumeric strings that
-begin with a caret (or a control character, but this form is
-deprecated).
-These variables must be written in the form <code>${^Foo}</code>; the braces
-are not optional. <code>${^Foo}</code> denotes the scalar variable whose
-name is a control-<code>F</code> followed by two <code>o</code>’s.
These variables are
-reserved for future special uses by Perl, except for the ones that
-begin with <code>^_</code> (control-underscore or caret-underscore). No
-control-character name that begins with <code>^_</code> will acquire a special
-meaning in any future version of Perl; such names may therefore be
-used safely in programs. <code>$^_</code> itself, however, <em>is</em>
reserved.
-</p>
-<p>Perl identifiers that begin with digits, control characters, or
-punctuation characters are exempt from the effects of the <code>package</code>
-declaration and are always forced to be in package <code>main</code>; they are
-also exempt from <code>strict 'vars'</code> errors. A few other names are also
-exempt in these ways:
-</p>
-<pre class="verbatim"> ENV STDIN
- INC STDOUT
- ARGV STDERR
- ARGVOUT
- SIG
-</pre>
-<p>In particular, the special <code>${^_XYZ}</code> variables are always taken
-to be in package <code>main</code>, regardless of any <code>package</code>
declarations
-presently in scope.
-</p>
-<hr>
-<a name="perlvar-SPECIAL-VARIABLES"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlvar-DESCRIPTION" accesskey="p" rel="prev">perlvar
DESCRIPTION</a>, Up: <a href="#perlvar" accesskey="u" rel="up">perlvar</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SPECIAL-VARIABLES"></a>
-<h3 class="section">86.3 SPECIAL VARIABLES</h3>
-
-<p>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:
-</p>
-<pre class="verbatim"> use English;
-</pre>
-<p>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 <strong>awk</strong>. For more info, please see <a
href="English.html#Top">(English)</a>.
-</p>
-<p>Before you continue, note the sort order for variables. In general, we
-first list the variables in case-insensitive, almost-lexigraphical
-order (ignoring the <code>{</code> or <code>^</code> preceding words, as in
<code>${^UNICODE}</code>
-or <code>$^T</code>), although <code>$_</code> and <code>@_</code> 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.
-</p>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlvar-General-Variables"
accesskey="1">perlvar General Variables</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvar-Variables-related-to-regular-expressions" accesskey="2">perlvar
Variables related to regular expressions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvar-Variables-related-to-filehandles" accesskey="3">perlvar
Variables related to filehandles</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlvar-Error-Variables"
accesskey="4">perlvar Error Variables</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvar-Variables-related-to-the-interpreter-state"
accesskey="5">perlvar Variables related to the interpreter
state</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvar-Deprecated-and-removed-variables" accesskey="6">perlvar
Deprecated and removed variables</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlvar-General-Variables"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvar-Variables-related-to-regular-expressions"
accesskey="n" rel="next">perlvar Variables related to regular expressions</a>,
Up: <a href="#perlvar-SPECIAL-VARIABLES" accesskey="u" rel="up">perlvar SPECIAL
VARIABLES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="General-Variables"></a>
-<h4 class="subsection">86.3.1 General Variables</h4>
-
-<dl compact="compact">
-<dt>$ARG</dt>
-<dd><a name="perlvar-_0024ARG"></a>
-</dd>
-<dt>$_</dt>
-<dd><a name="perlvar-_0024_005f"></a>
-<p>The default input and pattern-searching space. The following pairs are
-equivalent:
-</p>
-<pre class="verbatim"> while (<>) {...} # equivalent only in while!
- while (defined($_ = <>)) {...}
-
- /^Subject:/
- $_ =~ /^Subject:/
-
- tr/a-z/A-Z/
- $_ =~ tr/a-z/A-Z/
-
- chomp
- chomp($_)
-</pre>
-<p>Here are the places where Perl will assume <code>$_</code> even if you
don’t use it:
-</p>
-<ul>
-<li> The following functions use <code>$_</code> as a default argument:
-
-<p>abs, alarm, chomp, chop, chr, chroot,
-cos, defined, eval, evalbytes, exp, fc, glob, hex, int, lc,
-lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, printf,
-quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only),
-rmdir, say, sin, split (for its second
-argument), sqrt, stat, study, uc, ucfirst,
-unlink, unpack.
-</p>
-</li><li> All file tests (<code>-f</code>, <code>-d</code>) except for
<code>-t</code>, which defaults to STDIN.
-See <a href="#perlfunc-_002dX">perlfunc -X</a>
-
-</li><li> The pattern matching operations <code>m//</code>, <code>s///</code>
and <code>tr///</code> (aka <code>y///</code>)
-when used without an <code>=~</code> operator.
-
-</li><li> The default iterator variable in a <code>foreach</code> loop if no
other
-variable is supplied.
-
-</li><li> The implicit iterator variable in the <code>grep()</code> and
<code>map()</code> functions.
-
-</li><li> The implicit variable of <code>given()</code>.
-
-</li><li> The default place to put the next value or input record
-when a <code><FH></code>, <code>readline</code>, <code>readdir</code> or
<code>each</code>
-operation’s result is tested by itself as the sole criterion of a
<code>while</code>
-test. Outside a <code>while</code> test, this will not happen.
-
-</li></ul>
-
-<p><code>$_</code> is by default a global variable. However, as
-of perl v5.10.0, you can use a lexical version of
-<code>$_</code> by declaring it in a file or in a block with <code>my</code>.
Moreover,
-declaring <code>our $_</code> restores the global <code>$_</code> in the
current scope. Though
-this seemed like a good idea at the time it was introduced, lexical
<code>$_</code>
-actually causes more problems than it solves. If you call a function that
-expects to be passed information via <code>$_</code>, it may or may not work,
-depending on how the function is written, there not being any easy way to
-solve this. Just avoid lexical <code>$_</code>, unless you are feeling
particularly
-masochistic. For this reason lexical <code>$_</code> is still experimental
and will
-produce a warning unless warnings have been disabled. As with other
-experimental features, the behavior of lexical <code>$_</code> is subject to
change
-without notice, including change into a fatal error.
-</p>
-<p>Mnemonic: underline is understood in certain operations.
-</p>
-</dd>
-<dt>@ARG</dt>
-<dd><a name="perlvar-_0040ARG"></a>
-</dd>
-<dt>@_</dt>
-<dd><a name="perlvar-_0040_005f"></a>
-<p>Within a subroutine the array <code>@_</code> contains the parameters
passed to
-that subroutine. Inside a subroutine, <code>@_</code> is the default array for
-the array operators <code>pop</code> and <code>shift</code>.
-</p>
-<p>See <a href="#perlsub-NAME">perlsub NAME</a>.
-</p>
-</dd>
-<dt>$LIST_SEPARATOR</dt>
-<dd><a name="perlvar-_0024LIST_005fSEPARATOR"></a>
-</dd>
-<dt>$"</dt>
-<dd><a name="perlvar-_0024_0022"></a>
-<p>When an array or an array slice is interpolated into a double-quoted
-string or a similar context such as <code>/.../</code>, its elements are
-separated by this value. Default is a space. For example, this:
-</p>
-<pre class="verbatim"> print "The array is: @array\n";
-</pre>
-<p>is equivalent to this:
-</p>
-<pre class="verbatim"> print "The array is: " . join($",
@array) . "\n";
-</pre>
-<p>Mnemonic: works in double-quoted context.
-</p>
-</dd>
-<dt>$PROCESS_ID</dt>
-<dd><a name="perlvar-_0024PROCESS_005fID"></a>
-</dd>
-<dt>$PID</dt>
-<dd><a name="perlvar-_0024PID"></a>
-</dd>
-<dt>$$</dt>
-<dd><a name="perlvar-_0024_0024"></a>
-<p>The process number of the Perl running this script. Though you
<em>can</em> set
-this variable, doing so is generally discouraged, although it can be
-invaluable for some testing purposes. It will be reset automatically
-across <code>fork()</code> calls.
-</p>
-<p>Note for Linux and Debian GNU/kFreeBSD users: Before Perl v5.16.0 perl
-would emulate POSIX semantics on Linux systems using LinuxThreads, a
-partial implementation of POSIX Threads that has since been superseded
-by the Native POSIX Thread Library (NPTL).
-</p>
-<p>LinuxThreads is now obsolete on Linux, and caching <code>getpid()</code>
-like this made embedding perl unnecessarily complex (since you’d have
-to manually update the value of $$), so now <code>$$</code> and
<code>getppid()</code>
-will always return the same values as the underlying C library.
-</p>
-<p>Debian GNU/kFreeBSD systems also used LinuxThreads up until and
-including the 6.0 release, but after that moved to FreeBSD thread
-semantics, which are POSIX-like.
-</p>
-<p>To see if your system is affected by this discrepancy check if
-<code>getconf GNU_LIBPTHREAD_VERSION | grep -q NPTL</code> returns a false
-value. NTPL threads preserve the POSIX semantics.
-</p>
-<p>Mnemonic: same as shells.
-</p>
-</dd>
-<dt>$PROGRAM_NAME</dt>
-<dd><a name="perlvar-_0024PROGRAM_005fNAME"></a>
-</dd>
-<dt>$0</dt>
-<dd><a name="perlvar-_00240"></a>
-<p>Contains the name of the program being executed.
-</p>
-<p>On some (but not all) operating systems assigning to <code>$0</code>
modifies
-the argument area that the <code>ps</code> program sees. On some platforms you
-may have to use special <code>ps</code> options or a different <code>ps</code>
to see the
-changes. Modifying the <code>$0</code> is more useful as a way of indicating
the
-current program state than it is for hiding the program you’re
-running.
-</p>
-<p>Note that there are platform-specific limitations on the maximum
-length of <code>$0</code>. In the most extreme case it may be limited to the
-space occupied by the original <code>$0</code>.
-</p>
-<p>In some platforms there may be arbitrary amount of padding, for
-example space characters, after the modified name as shown by <code>ps</code>.
-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).
-</p>
-<p>Note for BSD users: setting <code>$0</code> does not completely remove
"perl"
-from the ps(1) output. For example, setting <code>$0</code> to
<code>"foobar"</code> may
-result in <code>"perl: foobar (perl)"</code> (whether both the
<code>"perl: "</code> 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.
-</p>
-<p>In multithreaded scripts Perl coordinates the threads so that any
-thread may modify its copy of the <code>$0</code> and the change becomes
visible
-to ps(1) (assuming the operating system plays along). Note that
-the view of <code>$0</code> the other threads have will not change since they
-have their own copies of it.
-</p>
-<p>If the program has been given to perl via the switches <code>-e</code> or
<code>-E</code>,
-<code>$0</code> will contain the string <code>"-e"</code>.
-</p>
-<p>On Linux as of perl v5.14.0 the legacy process name will be set with
-<code>prctl(2)</code>, in addition to altering the POSIX name via
<code>argv[0]</code> 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 <code>$0</code>. The string you supply will be
-cut off at 16 bytes, this is a limitation imposed by Linux.
-</p>
-<p>Mnemonic: same as <strong>sh</strong> and <strong>ksh</strong>.
-</p>
-</dd>
-<dt>$REAL_GROUP_ID</dt>
-<dd><a name="perlvar-_0024REAL_005fGROUP_005fID"></a>
-</dd>
-<dt>$GID</dt>
-<dd><a name="perlvar-_0024GID"></a>
-</dd>
-<dt>$(</dt>
-<dd><a name="perlvar-_0024_0028"></a>
-<p>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
-<code>getgid()</code>, and the subsequent ones by <code>getgroups()</code>,
one of which may be
-the same as the first number.
-</p>
-<p>However, a value assigned to <code>$(</code> must be a single number used to
-set the real gid. So the value given by <code>$(</code> should <em>not</em>
be assigned
-back to <code>$(</code> without being forced numeric, such as by adding zero.
Note
-that this is different to the effective gid (<code>$)</code>) which does take a
-list.
-</p>
-<p>You can change both the real gid and the effective gid at the same
-time by using <code>POSIX::setgid()</code>. Changes
-to <code>$(</code> require a check to <code>$!</code>
-to detect any possible errors after an attempted change.
-</p>
-<p>Mnemonic: parentheses are used to <em>group</em> things. The real gid is
the
-group you <em>left</em>, if you’re running setgid.
-</p>
-</dd>
-<dt>$EFFECTIVE_GROUP_ID</dt>
-<dd><a name="perlvar-_0024EFFECTIVE_005fGROUP_005fID"></a>
-</dd>
-<dt>$EGID</dt>
-<dd><a name="perlvar-_0024EGID"></a>
-</dd>
-<dt>$)</dt>
-<dd><a name="perlvar-_0024_0029"></a>
-<p>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 <code>getegid()</code>, and the subsequent ones by
<code>getgroups()</code>,
-one of which may be the same as the first number.
-</p>
-<p>Similarly, a value assigned to <code>$)</code> must also be a
space-separated
-list of numbers. The first number sets the effective gid, and
-the rest (if any) are passed to <code>setgroups()</code>. To get the effect
of an
-empty list for <code>setgroups()</code>, just repeat the new effective gid;
that is,
-to force an effective gid of 5 and an effectively empty
<code>setgroups()</code>
-list, say <code> $) = "5 5" </code>.
-</p>
-<p>You can change both the effective gid and the real gid at the same
-time by using <code>POSIX::setgid()</code> (use only a single numeric
argument).
-Changes to <code>$)</code> require a check to <code>$!</code> to detect any
possible errors
-after an attempted change.
-</p>
-<p><code>$<</code>, <code>$></code>, <code>$(</code> and <code>$)</code>
can be set only on
-machines that support the corresponding <em>set[re][ug]id()</em> routine.
<code>$(</code>
-and <code>$)</code> can be swapped only on machines supporting
<code>setregid()</code>.
-</p>
-<p>Mnemonic: parentheses are used to <em>group</em> things. The effective gid
-is the group that’s <em>right</em> for you, if you’re running
setgid.
-</p>
-</dd>
-<dt>$REAL_USER_ID</dt>
-<dd><a name="perlvar-_0024REAL_005fUSER_005fID"></a>
-</dd>
-<dt>$UID</dt>
-<dd><a name="perlvar-_0024UID"></a>
-</dd>
-<dt>$<</dt>
-<dd><a name="perlvar-_0024_003c"></a>
-<p>The real uid of this process. You can change both the real uid and the
-effective uid at the same time by using <code>POSIX::setuid()</code>. Since
-changes to <code>$<</code> require a system call, check <code>$!</code>
after a change
-attempt to detect any possible errors.
-</p>
-<p>Mnemonic: it’s the uid you came <em>from</em>, if you’re
running setuid.
-</p>
-</dd>
-<dt>$EFFECTIVE_USER_ID</dt>
-<dd><a name="perlvar-_0024EFFECTIVE_005fUSER_005fID"></a>
-</dd>
-<dt>$EUID</dt>
-<dd><a name="perlvar-_0024EUID"></a>
-</dd>
-<dt>$> >></dt>
-<dd><a name="perlvar-_0024_003e-_003e_003e"></a>
-<p>The effective uid of this process. For example:
-</p>
-<pre class="verbatim"> $< = $>; # set real to effective uid
- ($<,$>) = ($>,$<); # swap real and effective uids
-</pre>
-<p>You can change both the effective uid and the real uid at the same
-time by using <code>POSIX::setuid()</code>. Changes to <code>$></code>
require a check
-to <code>$!</code> to detect any possible errors after an attempted change.
-</p>
-<p><code>$<</code> and <code>$></code> can be swapped only on machines
-supporting <code>setreuid()</code>.
-</p>
-<p>Mnemonic: it’s the uid you went <em>to</em>, if you’re running
setuid.
-</p>
-</dd>
-<dt>$SUBSCRIPT_SEPARATOR</dt>
-<dd><a name="perlvar-_0024SUBSCRIPT_005fSEPARATOR"></a>
-</dd>
-<dt>$SUBSEP</dt>
-<dd><a name="perlvar-_0024SUBSEP"></a>
-</dd>
-<dt>$;</dt>
-<dd><a name="perlvar-_0024_003b"></a>
-<p>The subscript separator for multidimensional array emulation. If you
-refer to a hash element as
-</p>
-<pre class="verbatim"> $foo{$x,$y,$z}
-</pre>
-<p>it really means
-</p>
-<pre class="verbatim"> $foo{join($;, $x, $y, $z)}
-</pre>
-<p>But don’t put
-</p>
-<pre class="verbatim"> @foo{$x,$y,$z} # a slice--note the @
-</pre>
-<p>which means
-</p>
-<pre class="verbatim"> ($foo{$x},$foo{$y},$foo{$z})
-</pre>
-<p>Default is "\034", the same as SUBSEP in <strong>awk</strong>.
If your keys contain
-binary data there might not be any safe value for <code>$;</code>.
-</p>
-<p>Consider using "real" multidimensional arrays as described
-in <a href="#perllol-NAME">perllol NAME</a>.
-</p>
-<p>Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon.
-</p>
-</dd>
-<dt>$a</dt>
-<dd><a name="perlvar-_0024a"></a>
-</dd>
-<dt>$b</dt>
-<dd><a name="perlvar-_0024b"></a>
-<p>Special package variables when using <code>sort()</code>, see
‘perlfunc sort’.
-Because of this specialness <code>$a</code> and <code>$b</code> don’t
need to be declared
-(using <code>use vars</code>, or <code>our()</code>) even when using the
<code>strict 'vars'</code>
-pragma. Don’t lexicalize them with <code>my $a</code> or <code>my
$b</code> if you want to
-be able to use them in the <code>sort()</code> comparison block or function.
-</p>
-</dd>
-<dt>%ENV</dt>
-<dd><a name="perlvar-_0025ENV"></a>
-<p>The hash <code>%ENV</code> contains your current environment. Setting a
-value in <code>ENV</code> changes the environment for any child processes
-you subsequently <code>fork()</code> off.
-</p>
-<p>As of v5.18.0, both keys and values stored in <code>%ENV</code> are
stringified.
-</p>
-<pre class="verbatim"> my $foo = 1;
- $ENV{'bar'} = \$foo;
- if( ref $ENV{'bar'} ) {
- say "Pre 5.18.0 Behaviour";
- } else {
- say "Post 5.18.0 Behaviour";
- }
-</pre>
-<p>Previously, only child processes received stringified values:
-</p>
-<pre class="verbatim"> my $foo = 1;
- $ENV{'bar'} = \$foo;
-
- # Always printed 'non ref'
- system($^X, '-e',
- q/print ( ref $ENV{'bar'} ? 'ref' : 'non ref' ) /);
-</pre>
-<p>This happens because you can’t really share arbitrary data structures
with
-foreign processes.
-</p>
-</dd>
-<dt>$OLD_PERL_VERSION</dt>
-<dd><a name="perlvar-_0024OLD_005fPERL_005fVERSION"></a>
-</dd>
-<dt>$]</dt>
-<dd><a name="perlvar-_0024_005d"></a>
-<p>The revision, version, and subversion of the Perl interpreter, represented
-as a decimal of the form 5.XXXYYY, where XXX is the version / 1e3 and YYY
-is the subversion / 1e6. For example, Perl v5.10.1 would be
"5.010001".
-</p>
-<p>This variable can be used to determine whether the Perl interpreter
-executing a script is in the right range of versions:
-</p>
-<pre class="verbatim"> warn "No PerlIO!\n" if $] lt '5.008';
-</pre>
-<p>When comparing <code>$]</code>, string comparison operators are
<strong>highly
-recommended</strong>. The inherent limitations of binary floating point
-representation can sometimes lead to incorrect comparisons for some
-numbers on some architectures.
-</p>
-<p>See also the documentation of <code>use VERSION</code> and <code>require
VERSION</code>
-for a convenient way to fail if the running Perl interpreter is too old.
-</p>
-<p>See <a href="#perlvar-_0024_005eV">$^V</a> for a representation of the Perl
version as a <a href="version.html#Top">(version)</a>
-object, which allows more flexible string comparisons.
-</p>
-<p>The main advantage of <code>$]</code> over <code>$^V</code> is that it
works the same on any
-version of Perl. The disadvantages are that it can’t easily be compared
-to versions in other formats (e.g. literal v-strings, "v1.2.3" or
-version objects) and numeric comparisons can occasionally fail; it’s good
-for string literal version checks and bad for comparing to a variable
-that hasn’t been sanity-checked.
-</p>
-<p>The <code>$OLD_PERL_VERSION</code> form was added in Perl v5.20.0 for
historical
-reasons but its use is discouraged. (If your reason to use <code>$]</code> is
to
-run code on old perls then referring to it as <code>$OLD_PERL_VERSION</code>
would
-be self-defeating.)
-</p>
-<p>Mnemonic: Is this version of perl in the right bracket?
-</p>
-</dd>
-<dt>$SYSTEM_FD_MAX</dt>
-<dd><a name="perlvar-_0024SYSTEM_005fFD_005fMAX"></a>
-</dd>
-<dt>$^F</dt>
-<dd><a name="perlvar-_0024_005eF"></a>
-<p>The maximum system file descriptor, ordinarily 2. System file
-descriptors are passed to <code>exec()</code>ed processes, while higher file
-descriptors are not. Also, during an
-<code>open()</code>, system file descriptors are
-preserved even if the <code>open()</code> fails (ordinary file descriptors are
-closed before the <code>open()</code> is attempted). The close-on-exec
-status of a file descriptor will be decided according to the value of
-<code>$^F</code> when the corresponding file, pipe, or socket was opened, not
the
-time of the <code>exec()</code>.
-</p>
-</dd>
-<dt>@F</dt>
-<dd><a name="perlvar-_0040F"></a>
-<p>The array <code>@F</code> contains the fields of each line read in when
autosplit
-mode is turned on. See <a href="#perlrun-NAME">perlrun NAME</a> for the
<strong>-a</strong> switch. This array
-is package-specific, and must be declared or given a full package name
-if not in package main when running under <code>strict 'vars'</code>.
-</p>
-</dd>
-<dt>@INC</dt>
-<dd><a name="perlvar-_0040INC"></a>
-<p>The array <code>@INC</code> contains the list of places that the <code>do
EXPR</code>,
-<code>require</code>, or <code>use</code> constructs look for their library
files. It
-initially consists of the arguments to any <strong>-I</strong> command-line
-switches, followed by the default Perl library, probably
-<samp>/usr/local/lib/perl</samp>, followed by ".", to represent the
current
-directory. ("." will not be appended if taint checks are enabled,
-either by <code>-T</code> or by <code>-t</code>.) If you need to modify this
at runtime,
-you should use the <code>use lib</code> pragma to get the machine-dependent
-library properly loaded also:
-</p>
-<pre class="verbatim"> use lib '/mypath/libdir/';
- use SomeMod;
-</pre>
-<p>You can also insert hooks into the file inclusion system by putting Perl
-code directly into <code>@INC</code>. Those hooks may be subroutine
references,
-array references or blessed objects. See <a href="#perlfunc-require">perlfunc
require</a> for details.
-</p>
-</dd>
-<dt>%INC</dt>
-<dd><a name="perlvar-_0025INC"></a>
-<p>The hash <code>%INC</code> contains entries for each filename included via
the
-<code>do</code>, <code>require</code>, or <code>use</code> 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 <code>require</code>
-operator uses this hash to determine whether a particular file has
-already been included.
-</p>
-<p>If the file was loaded via a hook (e.g. a subroutine reference, see
-<a href="#perlfunc-require">perlfunc require</a> for a description of these
hooks), this hook is
-by default inserted into <code>%INC</code> in place of a filename. Note,
however,
-that the hook may have set the <code>%INC</code> entry by itself to provide
some more
-specific info.
-</p>
-</dd>
-<dt>$INPLACE_EDIT</dt>
-<dd><a name="perlvar-_0024INPLACE_005fEDIT"></a>
-</dd>
-<dt>$^I</dt>
-<dd><a name="perlvar-_0024_005eI"></a>
-<p>The current value of the inplace-edit extension. Use <code>undef</code> to
disable
-inplace editing.
-</p>
-<p>Mnemonic: value of <strong>-i</strong> switch.
-</p>
-</dd>
-<dt>$^M</dt>
-<dd><a name="perlvar-_0024_005eM"></a>
-<p>By default, running out of memory is an untrappable, fatal error.
-However, if suitably built, Perl can use the contents of <code>$^M</code>
-as an emergency memory pool after <code>die()</code>ing. Suppose that your
Perl
-were compiled with <code>-DPERL_EMERGENCY_SBRK</code> and used Perl’s
malloc.
-Then
-</p>
-<pre class="verbatim"> $^M = 'a' x (1 << 16);
-</pre>
-<p>would allocate a 64K buffer for use in an emergency. See the
-<samp>INSTALL</samp> 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 <a
href="English.html#Top">(English)English</a> long name for
-this variable.
-</p>
-<p>This variable was added in Perl 5.004.
-</p>
-</dd>
-<dt>$OSNAME</dt>
-<dd><a name="perlvar-_0024OSNAME"></a>
-</dd>
-<dt>$^O</dt>
-<dd><a name="perlvar-_0024_005eO"></a>
-<p>The name of the operating system under which this copy of Perl was
-built, as determined during the configuration process. For examples
-see <a href="#perlport-PLATFORMS">perlport PLATFORMS</a>.
-</p>
-<p>The value is identical to <code>$Config{'osname'}</code>. See also <a
href="Config.html#Top">(Config)</a>
-and the <strong>-V</strong> command-line switch documented in <a
href="#perlrun-NAME">perlrun NAME</a>.
-</p>
-<p>In Windows platforms, <code>$^O</code> is not very helpful: since it is
always
-<code>MSWin32</code>, it doesn’t tell the difference between
-95/98/ME/NT/2000/XP/CE/.NET. Use <code>Win32::GetOSName()</code> or
-Win32::GetOSVersion() (see <a href="Win32.html#Top">(Win32)</a> and <a
href="#perlport-NAME">perlport NAME</a>) to distinguish
-between the variants.
-</p>
-<p>This variable was added in Perl 5.003.
-</p>
-</dd>
-<dt>%SIG</dt>
-<dd><a name="perlvar-_0025SIG"></a>
-<p>The hash <code>%SIG</code> contains signal handlers for signals. For
example:
-</p>
-<pre class="verbatim"> sub handler { # 1st argument is signal name
- my($sig) = @_;
- print "Caught a SIG$sig--shutting down\n";
- close(LOG);
- exit(0);
- }
-
- $SIG{'INT'} = \&handler;
- $SIG{'QUIT'} = \&handler;
- ...
- $SIG{'INT'} = 'DEFAULT'; # restore default action
- $SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT
-</pre>
-<p>Using a value of <code>'IGNORE'</code> usually has the effect of ignoring
the
-signal, except for the <code>CHLD</code> signal. See <a
href="#perlipc-NAME">perlipc NAME</a> for more about
-this special case.
-</p>
-<p>Here are some other examples:
-</p>
-<pre class="verbatim"> $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??
-</pre>
-<p>Be sure not to use a bareword as the name of a signal handler,
-lest you inadvertently call it.
-</p>
-<p>If your system has the <code>sigaction()</code> function then signal
handlers
-are installed using it. This means you get reliable signal handling.
-</p>
-<p>The default delivery policy of signals changed in Perl v5.8.0 from
-immediate (also known as "unsafe") to deferred, also known as
"safe
-signals". See <a href="#perlipc-NAME">perlipc NAME</a> for more
information.
-</p>
-<p>Certain internal hooks can be also set using the <code>%SIG</code> hash.
The
-routine indicated by <code>$SIG{__WARN__}</code> is called when a warning
-message is about to be printed. The warning message is passed as the
-first argument. The presence of a <code>__WARN__</code> hook causes the
-ordinary printing of warnings to <code>STDERR</code> to be suppressed. You can
-use this to save warnings in a variable, or turn warnings into fatal
-errors, like this:
-</p>
-<pre class="verbatim"> local $SIG{__WARN__} = sub { die $_[0] };
- eval $proggie;
-</pre>
-<p>As the <code>'IGNORE'</code> hook is not supported by
<code>__WARN__</code>, you can
-disable warnings using the empty subroutine:
-</p>
-<pre class="verbatim"> local $SIG{__WARN__} = sub {};
-</pre>
-<p>The routine indicated by <code>$SIG{__DIE__}</code> is called when a fatal
-exception is about to be thrown. The error message is passed as the
-first argument. When a <code>__DIE__</code> 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 <code>goto &sub</code>, a loop
exit,
-or a <code>die()</code>. The <code>__DIE__</code> handler is explicitly
disabled during
-the call, so that you can die from a <code>__DIE__</code> handler. Similarly
-for <code>__WARN__</code>.
-</p>
-<p>Due to an implementation glitch, the <code>$SIG{__DIE__}</code> hook is
called
-even inside an <code>eval()</code>. Do not use this to rewrite a pending
-exception in <code>$@</code>, or as a bizarre substitute for overriding
-<code>CORE::GLOBAL::die()</code>. This strange action at a distance may be
fixed
-in a future release so that <code>$SIG{__DIE__}</code> is only called if your
-program is about to exit, as was the original intent. Any other use is
-deprecated.
-</p>
-<p><code>__DIE__</code>/<code>__WARN__</code> 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:
-</p>
-<pre class="verbatim"> require Carp if defined $^S;
- Carp::confess("Something wrong") if defined &Carp::confess;
- die "Something wrong, but could not load Carp to give "
- . "backtrace...\n\t"
- . "To see backtrace try starting Perl with -MCarp switch";
-</pre>
-<p>Here the first line will load <code>Carp</code> <em>unless</em> it is the
parser who
-called the handler. The second line will print backtrace and die if
-<code>Carp</code> was available. The third line will be executed only if
<code>Carp</code> was
-not available.
-</p>
-<p>Having to even think about the <code>$^S</code> variable in your exception
-handlers is simply wrong. <code>$SIG{__DIE__}</code> as currently implemented
-invites grievous and difficult to track down errors. Avoid it
-and use an <code>END{}</code> or CORE::GLOBAL::die override instead.
-</p>
-<p>See ‘perlfunc die’, ‘perlfunc warn’, <a
href="#perlfunc-eval">perlfunc eval</a>, and
-<a href="warnings.html#Top">(warnings)</a> for additional information.
-</p>
-</dd>
-<dt>$BASETIME</dt>
-<dd><a name="perlvar-_0024BASETIME"></a>
-</dd>
-<dt>$^T</dt>
-<dd><a name="perlvar-_0024_005eT"></a>
-<p>The time at which the program began running, in seconds since the
-epoch (beginning of 1970). The values returned by the <strong>-M</strong>,
<strong>-A</strong>,
-and <strong>-C</strong> filetests are based on this value.
-</p>
-</dd>
-<dt>$PERL_VERSION</dt>
-<dd><a name="perlvar-_0024PERL_005fVERSION"></a>
-</dd>
-<dt>$^V</dt>
-<dd><a name="perlvar-_0024_005eV"></a>
-<p>The revision, version, and subversion of the Perl interpreter,
-represented as a <a href="version.html#Top">(version)</a> object.
-</p>
-<p>This variable first appeared in perl v5.6.0; earlier versions of perl
-will see an undefined value. Before perl v5.10.0 <code>$^V</code> was
represented
-as a v-string rather than a <a href="version.html#Top">(version)</a> object.
-</p>
-<p><code>$^V</code> can be used to determine whether the Perl interpreter
executing
-a script is in the right range of versions. For example:
-</p>
-<pre class="verbatim"> warn "Hashes not randomized!\n" if !$^V or
$^V lt v5.8.1
-</pre>
-<p>While version objects overload stringification, to portably convert
-<code>$^V</code> into its string representation, use
<code>sprintf()</code>’s <code>"%vd"</code>
-conversion, which works for both v-strings or version objects:
-</p>
-<pre class="verbatim"> printf "version is v%vd\n", $^V; # Perl's
version
-</pre>
-<p>See the documentation of <code>use VERSION</code> and <code>require
VERSION</code>
-for a convenient way to fail if the running Perl interpreter is too old.
-</p>
-<p>See also <code>$]</code> for a decimal representation of the Perl version.
-</p>
-<p>The main advantage of <code>$^V</code> over <code>$]</code> is that, for
Perl v5.10.0 or
-later, it overloads operators, allowing easy comparison against other
-version representations (e.g. decimal, literal v-string, "v1.2.3", or
-objects). The disadvantage is that prior to v5.10.0, it was only a
-literal v-string, which can’t be easily printed or compared.
-</p>
-<p>Mnemonic: use ^V for a version object.
-</p>
-</dd>
-<dt>${^WIN32_SLOPPY_STAT}</dt>
-<dd><a name="perlvar-_0024_007b_005eWIN32_005fSLOPPY_005fSTAT_007d"></a>
-<p>If this variable is set to a true value, then <code>stat()</code> 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.
-</p>
-<p>This variable could be set in the <samp>sitecustomize.pl</samp> file to
-configure the local Perl installation to use "sloppy"
<code>stat()</code> by
-default. See the documentation for <strong>-f</strong> in
-<a href="#perlrun-Command-Switches">perlrun</a> for more information about site
-customization.
-</p>
-<p>This variable was added in Perl v5.10.0.
-</p>
-</dd>
-<dt>$EXECUTABLE_NAME</dt>
-<dd><a name="perlvar-_0024EXECUTABLE_005fNAME"></a>
-</dd>
-<dt>$^X</dt>
-<dd><a name="perlvar-_0024_005eX"></a>
-<p>The name used to execute the current copy of Perl, from C’s
-<code>argv[0]</code> or (where supported) <samp>/proc/self/exe</samp>.
-</p>
-<p>Depending on the host operating system, the value of <code>$^X</code> 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 <code>$^X</code> is in PATH. For VMS, the
-value may or may not include a version number.
-</p>
-<p>You usually can use the value of <code>$^X</code> to re-invoke an
independent
-copy of the same perl that is currently running, e.g.,
-</p>
-<pre class="verbatim"> @first_run = `$^X -le "print int rand 100 for
1..100"`;
-</pre>
-<p>But recall that not all operating systems support forking or
-capturing of the output of commands, so this complex statement
-may not be portable.
-</p>
-<p>It is not safe to use the value of <code>$^X</code> 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 <code>$^X</code> to a path name, use the
-following statements:
-</p>
-<pre class="verbatim"> # 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;
- }
-</pre>
-<p>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 <code>$^X</code>. The following statements accomplish
-this goal, and produce a pathname that can be invoked as a
-command or referenced as a file.
-</p>
-<pre class="verbatim"> 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;
- }
-</pre>
-</dd>
-</dl>
-
-<hr>
-<a name="perlvar-Variables-related-to-regular-expressions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvar-Variables-related-to-filehandles" accesskey="n"
rel="next">perlvar Variables related to filehandles</a>, Previous: <a
href="#perlvar-General-Variables" accesskey="p" rel="prev">perlvar General
Variables</a>, Up: <a href="#perlvar-SPECIAL-VARIABLES" accesskey="u"
rel="up">perlvar SPECIAL VARIABLES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Variables-related-to-regular-expressions"></a>
-<h4 class="subsection">86.3.2 Variables related to regular expressions</h4>
-
-<p>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:
-</p>
-<pre class="verbatim"> if( /P(A)TT(ER)N/ ) {
- print "I found $1 and $2\n";
- }
-</pre>
-<p>These variables are read-only and dynamically-scoped, unless we note
-otherwise.
-</p>
-<p>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:
-</p>
-<pre class="verbatim"> my $outer = 'Wallace and Grommit';
- my $inner = 'Mutt and Jeff';
-
- my $pattern = qr/(\S+) and (\S+)/;
-
- sub show_n { print "\$1 is $1; \$2 is $2\n" }
-
- {
- OUTER:
- show_n() if $outer =~ m/$pattern/;
-
- INNER: {
- show_n() if $inner =~ m/$pattern/;
- }
-
- show_n();
- }
-</pre>
-<p>The output shows that while in the <code>OUTER</code> block, the values of
<code>$1</code>
-and <code>$2</code> are from the match against <code>$outer</code>. Inside
the <code>INNER</code>
-block, the values of <code>$1</code> and <code>$2</code> are from the match
against
-<code>$inner</code>, but only until the end of the block (i.e. the dynamic
-scope). After the <code>INNER</code> block completes, the values of
<code>$1</code> and
-<code>$2</code> return to the values for the match against <code>$outer</code>
even though
-we have not made another match:
-</p>
-<pre class="verbatim"> $1 is Wallace; $2 is Grommit
- $1 is Mutt; $2 is Jeff
- $1 is Wallace; $2 is Grommit
-</pre>
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlvar-Performance-issues"
accesskey="1">perlvar Performance issues</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlvar-Performance-issues"></a>
-<div class="header">
-<p>
-Up: <a href="#perlvar-Variables-related-to-regular-expressions" accesskey="u"
rel="up">perlvar Variables related to regular expressions</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Performance-issues"></a>
-<h4 class="subsubsection">86.3.2.1 Performance issues</h4>
-
-<p>Traditionally in Perl, any use of any of the three variables
<code>$`</code>, <code>$&</code>
-or <code>$'</code> (or their <code>use English</code> equivalents) anywhere in
the code, caused
-all subsequent successful pattern matches to make a copy of the matched
-string, in case the code might subsequently access one of those variables.
-This imposed a considerable performance penalty across the whole program,
-so generally the use of these variables has been discouraged.
-</p>
-<p>In Perl 5.6.0 the <code>@-</code> and <code>@+</code> dynamic arrays were
introduced that
-supply the indices of successful matches. So you could for example do
-this:
-</p>
-<pre class="verbatim"> $str =~ /pattern/;
-
- print $`, $&, $'; # bad: perfomance hit
-
- print # good: no perfomance hit
- substr($str, 0, $-[0]),
- substr($str, $-[0], $+[0]-$-[0]),
- substr($str, $+[0]);
-</pre>
-<p>In Perl 5.10.0 the <code>/p</code> match operator flag and the
<code>${^PREMATCH}</code>,
-<code>${^MATCH}</code>, and <code>${^POSTMATCH}</code> variables were
introduced, that allowed
-you to suffer the penalties only on patterns marked with <code>/p</code>.
-</p>
-<p>In Perl 5.18.0 onwards, perl started noting the presence of each of the
-three variables separately, and only copied that part of the string
-required; so in
-</p>
-<pre class="verbatim"> $`; $&; "abcdefgh" =~ /d/
-</pre>
-<p>perl would only copy the "abcd" part of the string. That could
make a big
-difference in something like
-</p>
-<pre class="verbatim"> $str = 'x' x 1_000_000;
- $&; # whoops
- $str =~ /x/g # one char copied a million times, not a million chars
-</pre>
-<p>In Perl 5.20.0 a new copy-on-write system was enabled by default, which
-finally fixes all performance issues with these three variables, and makes
-them safe to use anywhere.
-</p>
-<p>The <code>Devel::NYTProf</code> and <code>Devel::FindAmpersand</code>
modules can help you
-find uses of these problematic match variables in your code.
-</p>
-<dl compact="compact">
-<dt>$<<em>digits</em>> ($1, $2, ...)</dt>
-<dd><a
name="perlvar-_0024_003cdigits_003e-_0028_00241_002c-_00242_002c-_002e_002e_002e_0029"></a>
-<p>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.
-</p>
-<p>These variables are read-only and dynamically-scoped.
-</p>
-<p>Mnemonic: like \digits.
-</p>
-</dd>
-<dt>$MATCH</dt>
-<dd><a name="perlvar-_0024MATCH"></a>
-</dd>
-<dt>$&</dt>
-<dd><a name="perlvar-_0024_0026"></a>
-<p>The string matched by the last successful pattern match (not counting
-any matches hidden within a BLOCK or <code>eval()</code> enclosed by the
current
-BLOCK).
-</p>
-<p>See <a href="#perlvar-Performance-issues">Performance issues</a> above for
the serious performance implications
-of using this variable (even once) in your code.
-</p>
-<p>This variable is read-only and dynamically-scoped.
-</p>
-<p>Mnemonic: like <code>&</code> in some editors.
-</p>
-</dd>
-<dt>${^MATCH}</dt>
-<dd><a name="perlvar-_0024_007b_005eMATCH_007d"></a>
-<p>This is similar to <code>$&</code> (<code>$MATCH</code>) except that it
does not incur the
-performance penalty associated with that variable.
-</p>
-<p>See <a href="#perlvar-Performance-issues">Performance issues</a> above.
-</p>
-<p>In Perl v5.18 and earlier, it is only guaranteed
-to return a defined value when the pattern was compiled or executed with
-the <code>/p</code> modifier. In Perl v5.20, the <code>/p</code> modifier
does nothing, so
-<code>${^MATCH}</code> does the same thing as <code>$MATCH</code>.
-</p>
-<p>This variable was added in Perl v5.10.0.
-</p>
-<p>This variable is read-only and dynamically-scoped.
-</p>
-</dd>
-<dt>$PREMATCH</dt>
-<dd><a name="perlvar-_0024PREMATCH"></a>
-</dd>
-<dt>$‘</dt>
-<dd><a name="perlvar-_0024_0060"></a>
-<p>The string preceding whatever was matched by the last successful
-pattern match, not counting any matches hidden within a BLOCK or
<code>eval</code>
-enclosed by the current BLOCK.
-</p>
-<p>See <a href="#perlvar-Performance-issues">Performance issues</a> above for
the serious performance implications
-of using this variable (even once) in your code.
-</p>
-<p>This variable is read-only and dynamically-scoped.
-</p>
-<p>Mnemonic: <code>`</code> often precedes a quoted string.
-</p>
-</dd>
-<dt>${^PREMATCH}</dt>
-<dd><a name="perlvar-_0024_007b_005ePREMATCH_007d"></a>
-<p>This is similar to <code>$`</code> ($PREMATCH) except that it does not
incur the
-performance penalty associated with that variable.
-</p>
-<p>See <a href="#perlvar-Performance-issues">Performance issues</a> above.
-</p>
-<p>In Perl v5.18 and earlier, it is only guaranteed
-to return a defined value when the pattern was compiled or executed with
-the <code>/p</code> modifier. In Perl v5.20, the <code>/p</code> modifier
does nothing, so
-<code>${^PREMATCH}</code> does the same thing as <code>$PREMATCH</code>.
-</p>
-<p>This variable was added in Perl v5.10.0.
-</p>
-<p>This variable is read-only and dynamically-scoped.
-</p>
-</dd>
-<dt>$POSTMATCH</dt>
-<dd><a name="perlvar-_0024POSTMATCH"></a>
-</dd>
-<dt>$’</dt>
-<dd><a name="perlvar-_0024_0027"></a>
-<p>The string following whatever was matched by the last successful
-pattern match (not counting any matches hidden within a BLOCK or
<code>eval()</code>
-enclosed by the current BLOCK). Example:
-</p>
-<pre class="verbatim"> local $_ = 'abcdefghi';
- /def/;
- print "$`:$&:$'\n"; # prints abc:def:ghi
-</pre>
-<p>See <a href="#perlvar-Performance-issues">Performance issues</a> above for
the serious performance implications
-of using this variable (even once) in your code.
-</p>
-<p>This variable is read-only and dynamically-scoped.
-</p>
-<p>Mnemonic: <code>'</code> often follows a quoted string.
-</p>
-</dd>
-<dt>${^POSTMATCH}</dt>
-<dd><a name="perlvar-_0024_007b_005ePOSTMATCH_007d"></a>
-<p>This is similar to <code>$'</code> (<code>$POSTMATCH</code>) except that it
does not incur the
-performance penalty associated with that variable.
-</p>
-<p>See <a href="#perlvar-Performance-issues">Performance issues</a> above.
-</p>
-<p>In Perl v5.18 and earlier, it is only guaranteed
-to return a defined value when the pattern was compiled or executed with
-the <code>/p</code> modifier. In Perl v5.20, the <code>/p</code> modifier
does nothing, so
-<code>${^POSTMATCH}</code> does the same thing as <code>$POSTMATCH</code>.
-</p>
-<p>This variable was added in Perl v5.10.0.
-</p>
-<p>This variable is read-only and dynamically-scoped.
-</p>
-</dd>
-<dt>$LAST_PAREN_MATCH</dt>
-<dd><a name="perlvar-_0024LAST_005fPAREN_005fMATCH"></a>
-</dd>
-<dt>$+</dt>
-<dd><a name="perlvar-_0024_002b"></a>
-<p>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:
-</p>
-<pre class="verbatim"> /Version: (.*)|Revision: (.*)/ && ($rev =
$+);
-</pre>
-<p>This variable is read-only and dynamically-scoped.
-</p>
-<p>Mnemonic: be positive and forward looking.
-</p>
-</dd>
-<dt>$LAST_SUBMATCH_RESULT</dt>
-<dd><a name="perlvar-_0024LAST_005fSUBMATCH_005fRESULT"></a>
-</dd>
-<dt>$^N</dt>
-<dd><a name="perlvar-_0024_005eN"></a>
-<p>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.
-</p>
-<p>This is primarily used inside <code>(?{...})</code> blocks for examining
text
-recently matched. For example, to effectively capture text to a variable
-(in addition to <code>$1</code>, <code>$2</code>, etc.), replace
<code>(...)</code> with
-</p>
-<pre class="verbatim"> (?:(...)(?{ $var = $^N }))
-</pre>
-<p>By setting and then using <code>$var</code> in this way relieves you from
having to
-worry about exactly which numbered set of parentheses they are.
-</p>
-<p>This variable was added in Perl v5.8.0.
-</p>
-<p>Mnemonic: the (possibly) Nested parenthesis that most recently closed.
-</p>
-</dd>
-<dt>@LAST_MATCH_END</dt>
-<dd><a name="perlvar-_0040LAST_005fMATCH_005fEND"></a>
-</dd>
-<dt>@+</dt>
-<dd><a name="perlvar-_0040_002b"></a>
-<p>This array holds the offsets of the ends of the last successful
-submatches in the currently active dynamic scope. <code>$+[0]</code> is
-the offset into the string of the end of the entire match. This
-is the same value as what the <code>pos</code> function returns when called
-on the variable that was matched against. The <em>n</em>th element
-of this array holds the offset of the <em>n</em>th submatch, so
-<code>$+[1]</code> is the offset past where <code>$1</code> ends,
<code>$+[2]</code> the offset
-past where <code>$2</code> ends, and so on. You can use <code>$#+</code> to
determine
-how many subgroups were in the last successful match. See the
-examples given for the <code>@-</code> variable.
-</p>
-<p>This variable was added in Perl v5.6.0.
-</p>
-</dd>
-<dt>%LAST_PAREN_MATCH</dt>
-<dd><a name="perlvar-_0025LAST_005fPAREN_005fMATCH"></a>
-</dd>
-<dt>%+</dt>
-<dd><a name="perlvar-_0025_002b"></a>
-<p>Similar to <code>@+</code>, the <code>%+</code> hash allows access to the
named capture
-buffers, should they exist, in the last successful match in the
-currently active dynamic scope.
-</p>
-<p>For example, <code>$+{foo}</code> is equivalent to <code>$1</code> after
the following match:
-</p>
-<pre class="verbatim"> 'foo' =~ /(?<foo>foo)/;
-</pre>
-<p>The keys of the <code>%+</code> hash list only the names of buffers that
have
-captured (and that are thus associated to defined values).
-</p>
-<p>The underlying behaviour of <code>%+</code> is provided by the
-<a href="Tie-Hash-NamedCapture.html#Top">(Tie-Hash-NamedCapture)</a> module.
-</p>
-<p><strong>Note:</strong> <code>%-</code> and <code>%+</code> are tied views
into a common internal hash
-associated with the last successful regular expression. Therefore mixing
-iterative access to them via <code>each</code> may have unpredictable results.
-Likewise, if the last successful match changes, then the results may be
-surprising.
-</p>
-<p>This variable was added in Perl v5.10.0.
-</p>
-<p>This variable is read-only and dynamically-scoped.
-</p>
-</dd>
-<dt>@LAST_MATCH_START</dt>
-<dd><a name="perlvar-_0040LAST_005fMATCH_005fSTART"></a>
-</dd>
-<dt>@-</dt>
-<dd><a name="perlvar-_0040_002d"></a>
-<p><code>$-[0]</code> is the offset of the start of the last successful match.
-<code>$-[</code><em>n</em><code>]</code> is the offset of the start of the
substring matched by
-<em>n</em>-th subpattern, or undef if the subpattern did not match.
-</p>
-<p>Thus, after a match against <code>$_</code>, <code>$&</code> coincides
with <code>substr $_, $-[0],
-$+[0] - $-[0]</code>. Similarly, $<em>n</em> coincides with <code>substr $_,
$-[n],
-$+[n] - $-[n]</code> if <code>$-[n]</code> is defined, and $+ coincides with
-<code>substr $_, $-[$#-], $+[$#-] - $-[$#-]</code>. One can use
<code>$#-</code> to find the
-last matched subgroup in the last successful match. Contrast with
-<code>$#+</code>, the number of subgroups in the regular expression. Compare
-with <code>@+</code>.
-</p>
-<p>This array holds the offsets of the beginnings of the last
-successful submatches in the currently active dynamic scope.
-<code>$-[0]</code> is the offset into the string of the beginning of the
-entire match. The <em>n</em>th element of this array holds the offset
-of the <em>n</em>th submatch, so <code>$-[1]</code> is the offset where
<code>$1</code>
-begins, <code>$-[2]</code> the offset where <code>$2</code> begins, and so on.
-</p>
-<p>After a match against some variable <code>$var</code>:
-</p>
-<dl compact="compact">
-<dt><code>$`</code> is the same as <code>substr($var, 0, $-[0])</code></dt>
-<dd><a
name="perlvar-_0024_0060-is-the-same-as-substr_0028_0024var_002c-0_002c-_0024_002d_005b0_005d_0029"></a>
-</dd>
-<dt><code>$&</code> is the same as <code>substr($var, $-[0], $+[0] -
$-[0])</code></dt>
-<dd><a
name="perlvar-_0024_0026-is-the-same-as-substr_0028_0024var_002c-_0024_002d_005b0_005d_002c-_0024_002b_005b0_005d-_002d-_0024_002d_005b0_005d_0029"></a>
-</dd>
-<dt><code>$'</code> is the same as <code>substr($var, $+[0])</code></dt>
-<dd><a
name="perlvar-_0024_0027-is-the-same-as-substr_0028_0024var_002c-_0024_002b_005b0_005d_0029"></a>
-</dd>
-<dt><code>$1</code> is the same as <code>substr($var, $-[1], $+[1] -
$-[1])</code></dt>
-<dd><a
name="perlvar-_00241-is-the-same-as-substr_0028_0024var_002c-_0024_002d_005b1_005d_002c-_0024_002b_005b1_005d-_002d-_0024_002d_005b1_005d_0029"></a>
-</dd>
-<dt><code>$2</code> is the same as <code>substr($var, $-[2], $+[2] -
$-[2])</code></dt>
-<dd><a
name="perlvar-_00242-is-the-same-as-substr_0028_0024var_002c-_0024_002d_005b2_005d_002c-_0024_002b_005b2_005d-_002d-_0024_002d_005b2_005d_0029"></a>
-</dd>
-<dt><code>$3</code> is the same as <code>substr($var, $-[3], $+[3] -
$-[3])</code></dt>
-<dd><a
name="perlvar-_00243-is-the-same-as-substr_0028_0024var_002c-_0024_002d_005b3_005d_002c-_0024_002b_005b3_005d-_002d-_0024_002d_005b3_005d_0029"></a>
-</dd>
-</dl>
-
-<p>This variable was added in Perl v5.6.0.
-</p>
-</dd>
-<dt>%LAST_MATCH_START</dt>
-<dd><a name="perlvar-_0025LAST_005fMATCH_005fSTART"></a>
-</dd>
-<dt>%-</dt>
-<dd><a name="perlvar-_0025_002d"></a>
-<p>Similar to <code>%+</code>, 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.
-</p>
-<p>Here’s an example:
-</p>
-<pre class="verbatim"> 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";
- }
- }
- }
-</pre>
-<p>would print out:
-</p>
-<pre class="verbatim"> $-{A}[0] : '1'
- $-{A}[1] : '3'
- $-{B}[0] : '2'
- $-{B}[1] : '4'
-</pre>
-<p>The keys of the <code>%-</code> hash correspond to all buffer names found in
-the regular expression.
-</p>
-<p>The behaviour of <code>%-</code> is implemented via the
-<a href="Tie-Hash-NamedCapture.html#Top">(Tie-Hash-NamedCapture)</a> module.
-</p>
-<p><strong>Note:</strong> <code>%-</code> and <code>%+</code> are tied views
into a common internal hash
-associated with the last successful regular expression. Therefore mixing
-iterative access to them via <code>each</code> may have unpredictable results.
-Likewise, if the last successful match changes, then the results may be
-surprising.
-</p>
-<p>This variable was added in Perl v5.10.0.
-</p>
-<p>This variable is read-only and dynamically-scoped.
-</p>
-</dd>
-<dt>$LAST_REGEXP_CODE_RESULT</dt>
-<dd><a name="perlvar-_0024LAST_005fREGEXP_005fCODE_005fRESULT"></a>
-</dd>
-<dt>$^R</dt>
-<dd><a name="perlvar-_0024_005eR"></a>
-<p>The result of evaluation of the last successful <code>(?{ code })</code>
-regular expression assertion (see <a href="#perlre-NAME">perlre NAME</a>).
May be written to.
-</p>
-<p>This variable was added in Perl 5.005.
-</p>
-</dd>
-<dt>${^RE_DEBUG_FLAGS}</dt>
-<dd><a name="perlvar-_0024_007b_005eRE_005fDEBUG_005fFLAGS_007d"></a>
-<p>The current value of the regex debugging flags. Set to 0 for no debug
output
-even when the <code>re 'debug'</code> module is loaded. See <a
href="re.html#Top">(re)</a> for details.
-</p>
-<p>This variable was added in Perl v5.10.0.
-</p>
-</dd>
-<dt>${^RE_TRIE_MAXBUF}</dt>
-<dd><a name="perlvar-_0024_007b_005eRE_005fTRIE_005fMAXBUF_007d"></a>
-<p>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.
-</p>
-<p>This variable was added in Perl v5.10.0.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlvar-Variables-related-to-filehandles"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvar-Error-Variables" accesskey="n" rel="next">perlvar
Error Variables</a>, Previous: <a
href="#perlvar-Variables-related-to-regular-expressions" accesskey="p"
rel="prev">perlvar Variables related to regular expressions</a>, Up: <a
href="#perlvar-SPECIAL-VARIABLES" accesskey="u" rel="up">perlvar SPECIAL
VARIABLES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Variables-related-to-filehandles"></a>
-<h4 class="subsection">86.3.3 Variables related to filehandles</h4>
-
-<p>Variables that depend on the currently selected filehandle may be set
-by calling an appropriate object method on the <code>IO::Handle</code> 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
-</p>
-<pre class="verbatim"> use IO::Handle;
-</pre>
-<p>after which you may use either
-</p>
-<pre class="verbatim"> method HANDLE EXPR
-</pre>
-<p>or more safely,
-</p>
-<pre class="verbatim"> HANDLE->method(EXPR)
-</pre>
-<p>Each method returns the old value of the <code>IO::Handle</code> attribute.
The
-methods each take an optional EXPR, which, if supplied, specifies the
-new value for the <code>IO::Handle</code> attribute in question. If not
-supplied, most methods do nothing to the current value–except for
-<code>autoflush()</code>, which will assume a 1 for you, just to be different.
-</p>
-<p>Because loading in the <code>IO::Handle</code> class is an expensive
operation,
-you should learn how to use the regular built-in variables.
-</p>
-<p>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.
-</p>
-<p>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:
-</p>
-<pre class="verbatim"> open my $fh, "<", "foo" or
die $!;
- local $/; # enable localized slurp mode
- my $content = <$fh>;
- close $fh;
-</pre>
-<p>But the following code is quite bad:
-</p>
-<pre class="verbatim"> open my $fh, "<", "foo" or
die $!;
- undef $/; # enable slurp mode
- my $content = <$fh>;
- close $fh;
-</pre>
-<p>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 <code>$/</code> is now changed for any other code
-running inside the same Perl interpreter.
-</p>
-<p>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 <code>{}</code> block, you should create one yourself. For
-example:
-</p>
-<pre class="verbatim"> my $content = '';
- open my $fh, "<", "foo" or die $!;
- {
- local $/;
- $content = <$fh>;
- }
- close $fh;
-</pre>
-<p>Here is an example of how your own code can go broken:
-</p>
-<pre class="verbatim"> for ( 1..3 ){
- $\ = "\r\n";
- nasty_break();
- print "$_";
- }
-
- sub nasty_break {
- $\ = "\f";
- # do something with $_
- }
-</pre>
-<p>You probably expect this code to print the equivalent of
-</p>
-<pre class="verbatim"> "1\r\n2\r\n3\r\n"
-</pre>
-<p>but instead you get:
-</p>
-<pre class="verbatim"> "1\f2\f3\f"
-</pre>
-<p>Why? Because <code>nasty_break()</code> modifies <code>$\</code> without
localizing it
-first. The value you set in <code>nasty_break()</code> is still there when
you
-return. The fix is to add <code>local()</code> so the value doesn’t
leak out of
-<code>nasty_break()</code>:
-</p>
-<pre class="verbatim"> local $\ = "\f";
-</pre>
-<p>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.
-</p>
-<dl compact="compact">
-<dt>$ARGV</dt>
-<dd><a name="perlvar-_0024ARGV"></a>
-<p>Contains the name of the current file when reading from
<code><></code>.
-</p>
-</dd>
-<dt>@ARGV</dt>
-<dd><a name="perlvar-_0040ARGV"></a>
-<p>The array <code>@ARGV</code> contains the command-line arguments intended
for
-the script. <code>$#ARGV</code> is generally the number of arguments minus
-one, because <code>$ARGV[0]</code> is the first argument, <em>not</em> the
program’s
-command name itself. See <a href="#perlvar-_00240">$0</a> for the command
name.
-</p>
-</dd>
-<dt>ARGV</dt>
-<dd><a name="perlvar-ARGV"></a>
-<p>The special filehandle that iterates over command-line filenames in
-<code>@ARGV</code>. Usually written as the null filehandle in the angle
operator
-<code><></code>. Note that currently <code>ARGV</code> only has its
magical effect
-within the <code><></code> operator; elsewhere it is just a plain
filehandle
-corresponding to the last file opened by <code><></code>. In particular,
-passing <code>\*ARGV</code> 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 <code>@ARGV</code>.
-</p>
-</dd>
-<dt>ARGVOUT</dt>
-<dd><a name="perlvar-ARGVOUT"></a>
-<p>The special filehandle that points to the currently open output file
-when doing edit-in-place processing with <strong>-i</strong>. Useful when you
have
-to do a lot of inserting and don’t want to keep modifying
<code>$_</code>. See
-<a href="#perlrun-NAME">perlrun NAME</a> for the <strong>-i</strong> switch.
-</p>
-</dd>
-<dt>IO::Handle->output_field_separator( EXPR )</dt>
-<dd><a
name="perlvar-IO_003a_003aHandle_002d_003eoutput_005ffield_005fseparator_0028-EXPR-_0029"></a>
-</dd>
-<dt>$OUTPUT_FIELD_SEPARATOR</dt>
-<dd><a name="perlvar-_0024OUTPUT_005fFIELD_005fSEPARATOR"></a>
-</dd>
-<dt>$OFS</dt>
-<dd><a name="perlvar-_0024OFS"></a>
-</dd>
-<dt>$,</dt>
-<dd><a name="perlvar-_0024_002c"></a>
-<p>The output field separator for the print operator. If defined, this
-value is printed between each of print’s arguments. Default is
<code>undef</code>.
-</p>
-<p>You cannot call <code>output_field_separator()</code> on a handle, only as a
-static method. See <a href="IO-Handle.html#Top">(IO-Handle)IO::Handle</a>.
-</p>
-<p>Mnemonic: what is printed when there is a "," in your print
statement.
-</p>
-</dd>
-<dt>HANDLE->input_line_number( EXPR )</dt>
-<dd><a
name="perlvar-HANDLE_002d_003einput_005fline_005fnumber_0028-EXPR-_0029"></a>
-</dd>
-<dt>$INPUT_LINE_NUMBER</dt>
-<dd><a name="perlvar-_0024INPUT_005fLINE_005fNUMBER"></a>
-</dd>
-<dt>$NR</dt>
-<dd><a name="perlvar-_0024NR"></a>
-</dd>
-<dt>$.</dt>
-<dd><a name="perlvar-_0024_002e"></a>
-<p>Current line number for the last filehandle accessed.
-</p>
-<p>Each filehandle in Perl counts the number of lines that have been read
-from it. (Depending on the value of <code>$/</code>, Perl’s idea of what
-constitutes a line may not match yours.) When a line is read from a
-filehandle (via <code>readline()</code> or <code><></code>), or when
<code>tell()</code> or
-<code>seek()</code> is called on it, <code>$.</code> becomes an alias to the
line counter
-for that filehandle.
-</p>
-<p>You can adjust the counter by assigning to <code>$.</code>, but this will
not
-actually move the seek pointer. <em>Localizing <code>$.</code> will not
localize
-the filehandle’s line count</em>. Instead, it will localize
perl’s notion
-of which filehandle <code>$.</code> is currently aliased to.
-</p>
-<p><code>$.</code> is reset when the filehandle is closed, but
<strong>not</strong> when an open
-filehandle is reopened without an intervening <code>close()</code>. For more
-details, see <a href="#perlop-I_002fO-Operators">perlop I/O Operators</a>.
Because <code><></code> never does
-an explicit close, line numbers increase across <code>ARGV</code> files (but
see
-examples in <a href="#perlfunc-eof">perlfunc eof</a>).
-</p>
-<p>You can also use <code>HANDLE->input_line_number(EXPR)</code> to access
the
-line counter for a given filehandle without having to worry about
-which handle you last accessed.
-</p>
-<p>Mnemonic: many programs use "." to mean the current line number.
-</p>
-</dd>
-<dt>IO::Handle->input_record_separator( EXPR )</dt>
-<dd><a
name="perlvar-IO_003a_003aHandle_002d_003einput_005frecord_005fseparator_0028-EXPR-_0029"></a>
-</dd>
-<dt>$INPUT_RECORD_SEPARATOR</dt>
-<dd><a name="perlvar-_0024INPUT_005fRECORD_005fSEPARATOR"></a>
-</dd>
-<dt>$RS</dt>
-<dd><a name="perlvar-_0024RS"></a>
-</dd>
-<dt>$/</dt>
-<dd><a name="perlvar-_0024_002f"></a>
-<p>The input record separator, newline by default. This influences
Perl’s
-idea of what a "line" is. Works like <strong>awk</strong>’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
-<code>undef</code> to read through the end of file. Setting it to
<code>"\n\n"</code>
-means something slightly different than setting to <code>""</code>,
if the file
-contains consecutive empty lines. Setting to <code>""</code> will
treat two or
-more consecutive empty lines as a single empty line. Setting to
-<code>"\n\n"</code> will blindly assume that the next input
character belongs to
-the next paragraph, even if it’s a newline.
-</p>
-<pre class="verbatim"> local $/; # enable "slurp" mode
- local $_ = <FH>; # whole file now here
- s/\n[ \t]+/ /g;
-</pre>
-<p>Remember: the value of <code>$/</code> is a string, not a regex.
<strong>awk</strong> has to
-be better for something. :-)
-</p>
-<p>Setting <code>$/</code> 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 number of characters. So this:
-</p>
-<pre class="verbatim"> local $/ = \32768; # or \"32768", or
\$var_containing_32768
- open my $fh, "<", $myfile or die $!;
- local $_ = <$fh>;
-</pre>
-<p>will read a record of no more than 32768 characters from $fh. If
you’re
-not reading from a record-oriented file (or your OS doesn’t have
-record-oriented files), then you’ll likely get a full chunk of data
-with every read. If a record is larger than the record size you’ve
-set, you’ll get the record back in pieces. Trying to set the record
-size to zero or less is deprecated and will cause $/ to have the value
-of "undef", which will cause reading in the (rest of the) whole file.
-</p>
-<p>As of 5.19.9 setting <code>$/</code> to any other form of reference will
throw a
-fatal exception. This is in preparation for supporting new ways to set
-<code>$/</code> in the future.
-</p>
-<p>On VMS only, record reads bypass PerlIO layers and any associated
-buffering, so you must not mix record and non-record reads on the
-same filehandle. Record mode mixes with line mode only when the
-same buffering layer is in use for both modes.
-</p>
-<p>You cannot call <code>input_record_separator()</code> on a handle, only as a
-static method. See <a href="IO-Handle.html#Top">(IO-Handle)IO::Handle</a>.
-</p>
-<p>See also <a href="#perlport-Newlines">perlport Newlines</a>. Also see <a
href="#perlvar-_0024_002e">$.</a>.
-</p>
-<p>Mnemonic: / delimits line boundaries when quoting poetry.
-</p>
-</dd>
-<dt>IO::Handle->output_record_separator( EXPR )</dt>
-<dd><a
name="perlvar-IO_003a_003aHandle_002d_003eoutput_005frecord_005fseparator_0028-EXPR-_0029"></a>
-</dd>
-<dt>$OUTPUT_RECORD_SEPARATOR</dt>
-<dd><a name="perlvar-_0024OUTPUT_005fRECORD_005fSEPARATOR"></a>
-</dd>
-<dt>$ORS</dt>
-<dd><a name="perlvar-_0024ORS"></a>
-</dd>
-<dt>$\</dt>
-<dd><a name="perlvar-_0024_005c"></a>
-<p>The output record separator for the print operator. If defined, this
-value is printed after the last of print’s arguments. Default is
<code>undef</code>.
-</p>
-<p>You cannot call <code>output_record_separator()</code> on a handle, only as
a
-static method. See <a href="IO-Handle.html#Top">(IO-Handle)IO::Handle</a>.
-</p>
-<p>Mnemonic: you set <code>$\</code> instead of adding "\n" at the
end of the print.
-Also, it’s just like <code>$/</code>, but it’s what you get
"back" from Perl.
-</p>
-</dd>
-<dt>HANDLE->autoflush( EXPR )</dt>
-<dd><a name="perlvar-HANDLE_002d_003eautoflush_0028-EXPR-_0029"></a>
-</dd>
-<dt>$OUTPUT_AUTOFLUSH</dt>
-<dd><a name="perlvar-_0024OUTPUT_005fAUTOFLUSH"></a>
-</dd>
-<dt>$|</dt>
-<dd><a name="perlvar-_0024_007c"></a>
-<p>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; <code>$|</code> 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 <strong>rsh</strong>
and
-want to see the output as it’s happening. This has no effect on input
-buffering. See <a href="#perlfunc-getc">perlfunc getc</a> for that. See <a
href="#perlfunc-select">perlfunc select</a> on
-how to select the output channel. See also <a
href="IO-Handle.html#Top">(IO-Handle)</a>.
-</p>
-<p>Mnemonic: when you want your pipes to be piping hot.
-</p>
-</dd>
-<dt>${^LAST_FH}</dt>
-<dd><a name="perlvar-_0024_007b_005eLAST_005fFH_007d"></a>
-<p>This read-only variable contains a reference to the last-read filehandle.
-This is set by <code><HANDLE></code>, <code>readline</code>,
<code>tell</code>, <code>eof</code> and <code>seek</code>.
-This is the same handle that <code>$.</code> and <code>tell</code> and
<code>eof</code> without arguments
-use. It is also the handle used when Perl appends ", <STDIN> line
1" to
-an error or warning message.
-</p>
-<p>This variable was added in Perl v5.18.0.
-</p>
-</dd>
-</dl>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlvar-Variables-related-to-formats" accesskey="1">perlvar Variables
related to formats</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlvar-Variables-related-to-formats"></a>
-<div class="header">
-<p>
-Up: <a href="#perlvar-Variables-related-to-filehandles" accesskey="u"
rel="up">perlvar Variables related to filehandles</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Variables-related-to-formats"></a>
-<h4 class="subsubsection">86.3.3.1 Variables related to formats</h4>
-
-<p>The special variables for formats are a subset of those for
-filehandles. See <a href="#perlform-NAME">perlform NAME</a> for more
information about Perl’s
-formats.
-</p>
-<dl compact="compact">
-<dt>$ACCUMULATOR</dt>
-<dd><a name="perlvar-_0024ACCUMULATOR"></a>
-</dd>
-<dt>$^A</dt>
-<dd><a name="perlvar-_0024_005eA"></a>
-<p>The current value of the <code>write()</code> accumulator for
<code>format()</code> lines.
-A format contains <code>formline()</code> calls that put their result into
-<code>$^A</code>. After calling its format, <code>write()</code> prints out
the contents
-of <code>$^A</code> and empties. So you never really see the contents of
<code>$^A</code>
-unless you call <code>formline()</code> yourself and then look at it. See
-<a href="#perlform-NAME">perlform NAME</a> and <a
href="#perlfunc-formline-PICTURE_002cLIST">perlfunc formline PICTURE,LIST</a>.
-</p>
-</dd>
-<dt>IO::Handle->format_formfeed(EXPR)</dt>
-<dd><a
name="perlvar-IO_003a_003aHandle_002d_003eformat_005fformfeed_0028EXPR_0029"></a>
-</dd>
-<dt>$FORMAT_FORMFEED</dt>
-<dd><a name="perlvar-_0024FORMAT_005fFORMFEED"></a>
-</dd>
-<dt>$^L</dt>
-<dd><a name="perlvar-_0024_005eL"></a>
-<p>What formats output as a form feed. The default is <code>\f</code>.
-</p>
-<p>You cannot call <code>format_formfeed()</code> on a handle, only as a static
-method. See <a href="IO-Handle.html#Top">(IO-Handle)IO::Handle</a>.
-</p>
-</dd>
-<dt>HANDLE->format_page_number(EXPR)</dt>
-<dd><a
name="perlvar-HANDLE_002d_003eformat_005fpage_005fnumber_0028EXPR_0029"></a>
-</dd>
-<dt>$FORMAT_PAGE_NUMBER</dt>
-<dd><a name="perlvar-_0024FORMAT_005fPAGE_005fNUMBER"></a>
-</dd>
-<dt>$%</dt>
-<dd><a name="perlvar-_0024_0025"></a>
-<p>The current page number of the currently selected output channel.
-</p>
-<p>Mnemonic: <code>%</code> is page number in <strong>nroff</strong>.
-</p>
-</dd>
-<dt>HANDLE->format_lines_left(EXPR)</dt>
-<dd><a
name="perlvar-HANDLE_002d_003eformat_005flines_005fleft_0028EXPR_0029"></a>
-</dd>
-<dt>$FORMAT_LINES_LEFT</dt>
-<dd><a name="perlvar-_0024FORMAT_005fLINES_005fLEFT"></a>
-</dd>
-<dt>$-</dt>
-<dd><a name="perlvar-_0024_002d"></a>
-<p>The number of lines left on the page of the currently selected output
-channel.
-</p>
-<p>Mnemonic: lines_on_page - lines_printed.
-</p>
-</dd>
-<dt>IO::Handle->format_line_break_characters EXPR</dt>
-<dd><a
name="perlvar-IO_003a_003aHandle_002d_003eformat_005fline_005fbreak_005fcharacters-EXPR"></a>
-</dd>
-<dt>$FORMAT_LINE_BREAK_CHARACTERS</dt>
-<dd><a name="perlvar-_0024FORMAT_005fLINE_005fBREAK_005fCHARACTERS"></a>
-</dd>
-<dt>$:</dt>
-<dd><a name="perlvar-_0024_003a"></a>
-<p>The current set of characters after which a string may be broken to
-fill continuation fields (starting with <code>^</code>) in a format. The
default is
-" <span class="nolinebreak">\n-"</span><!-- /@w -->, to break
on a space, newline, or a hyphen.
-</p>
-<p>You cannot call <code>format_line_break_characters()</code> on a handle,
only as
-a static method. See <a href="IO-Handle.html#Top">(IO-Handle)IO::Handle</a>.
-</p>
-<p>Mnemonic: a "colon" in poetry is a part of a line.
-</p>
-</dd>
-<dt>HANDLE->format_lines_per_page(EXPR)</dt>
-<dd><a
name="perlvar-HANDLE_002d_003eformat_005flines_005fper_005fpage_0028EXPR_0029"></a>
-</dd>
-<dt>$FORMAT_LINES_PER_PAGE</dt>
-<dd><a name="perlvar-_0024FORMAT_005fLINES_005fPER_005fPAGE"></a>
-</dd>
-<dt>$=</dt>
-<dd><a name="perlvar-_0024_003d"></a>
-<p>The current page length (printable lines) of the currently selected
-output channel. The default is 60.
-</p>
-<p>Mnemonic: = has horizontal lines.
-</p>
-</dd>
-<dt>HANDLE->format_top_name(EXPR)</dt>
-<dd><a
name="perlvar-HANDLE_002d_003eformat_005ftop_005fname_0028EXPR_0029"></a>
-</dd>
-<dt>$FORMAT_TOP_NAME</dt>
-<dd><a name="perlvar-_0024FORMAT_005fTOP_005fNAME"></a>
-</dd>
-<dt>$^</dt>
-<dd><a name="perlvar-_0024_005e"></a>
-<p>The name of the current top-of-page format for the currently selected
-output channel. The default is the name of the filehandle with
<code>_TOP</code>
-appended. For example, the default format top name for the <code>STDOUT</code>
-filehandle is <code>STDOUT_TOP</code>.
-</p>
-<p>Mnemonic: points to top of page.
-</p>
-</dd>
-<dt>HANDLE->format_name(EXPR)</dt>
-<dd><a name="perlvar-HANDLE_002d_003eformat_005fname_0028EXPR_0029"></a>
-</dd>
-<dt>$FORMAT_NAME</dt>
-<dd><a name="perlvar-_0024FORMAT_005fNAME"></a>
-</dd>
-<dt>$~</dt>
-<dd><a name="perlvar-_0024_007e"></a>
-<p>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 <code>STDOUT</code>
-filehandle is just <code>STDOUT</code>.
-</p>
-<p>Mnemonic: brother to <code>$^</code>.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlvar-Error-Variables"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvar-Variables-related-to-the-interpreter-state"
accesskey="n" rel="next">perlvar Variables related to the interpreter
state</a>, Previous: <a href="#perlvar-Variables-related-to-filehandles"
accesskey="p" rel="prev">perlvar Variables related to filehandles</a>, Up: <a
href="#perlvar-SPECIAL-VARIABLES" accesskey="u" rel="up">perlvar SPECIAL
VARIABLES</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Error-Variables"></a>
-<h4 class="subsection">86.3.4 Error Variables</h4>
-
-<p>The variables <code>$@</code>, <code>$!</code>, <code>$^E</code>, and
<code>$?</code> contain information
-about different types of error conditions that may appear during
-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
-interpreter, C library, operating system, or an external program,
-respectively.
-</p>
-<p>To illustrate the differences between these variables, consider the
-following Perl expression, which uses a single-quoted string. After
-execution of this statement, perl may have set all four special error
-variables:
-</p>
-<pre class="verbatim"> eval q{
- open my $pipe, "/cdrom/install |" or die $!;
- my @res = <$pipe>;
- close $pipe or die "bad pipe: $?, $!";
- };
-</pre>
-<p>When perl executes the <code>eval()</code> expression, it translates the
-<code>open()</code>, <code><PIPE></code>, and <code>close</code> calls
in the C run-time library
-and thence to the operating system kernel. perl sets <code>$!</code> to
-the C library’s <code>errno</code> if one of these calls fails.
-</p>
-<p><code>$@</code> is set if the string to be <code>eval</code>-ed did not
compile (this may
-happen if <code>open</code> or <code>close</code> were imported with bad
prototypes), or
-if Perl code executed during evaluation <code>die()</code>d. In these cases
the
-value of <code>$@</code> is the compile error, or the argument to
<code>die</code> (which
-will interpolate <code>$!</code> and <code>$?</code>). (See also <a
href="Fatal.html#Top">(Fatal)</a>, though.)
-</p>
-<p>Under a few operating systems, <code>$^E</code> 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 <code>$^E</code> the same as
<code>$!</code>.
-</p>
-<p>Finally, <code>$?</code> may be set to non-0 value if the external program
-<samp>/cdrom/install</samp> fails. The upper eight bits reflect specific error
-conditions encountered by the program (the program’s <code>exit()</code>
value).
-The lower eight bits reflect mode of failure, like signal death and
-core dump information. See <a href="http://man.he.net/man2/wait";>wait(2)</a>
for details. In contrast to
-<code>$!</code> and <code>$^E</code>, which are set only if error condition is
detected,
-the variable <code>$?</code> is set on each <code>wait</code> or pipe
<code>close</code>,
-overwriting the old value. This is more like <code>$@</code>, which on every
-<code>eval()</code> is always set on failure and cleared on success.
-</p>
-<p>For more details, see the individual descriptions at <code>$@</code>,
<code>$!</code>,
-<code>$^E</code>, and <code>$?</code>.
-</p>
-<dl compact="compact">
-<dt>${^CHILD_ERROR_NATIVE}</dt>
-<dd><a name="perlvar-_0024_007b_005eCHILD_005fERROR_005fNATIVE_007d"></a>
-<p>The native status returned by the last pipe close, backtick
(<code>``</code>)
-command, successful call to <code>wait()</code> or <code>waitpid()</code>, or
from the
-<code>system()</code> operator. On POSIX-like systems this value can be
decoded
-with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED,
-WSTOPSIG and WIFCONTINUED functions provided by the <a
href="POSIX.html#Top">(POSIX)</a> module.
-</p>
-<p>Under VMS this reflects the actual VMS exit status; i.e. it is the
-same as <code>$?</code> when the pragma <code>use vmsish 'status'</code> is in
effect.
-</p>
-<p>This variable was added in Perl v5.10.0.
-</p>
-</dd>
-<dt>$EXTENDED_OS_ERROR</dt>
-<dd><a name="perlvar-_0024EXTENDED_005fOS_005fERROR"></a>
-</dd>
-<dt>$^E</dt>
-<dd><a name="perlvar-_0024_005eE"></a>
-<p>Error information specific to the current operating system. At the
-moment, this differs from <code>$!</code> under only VMS, OS/2, and Win32 (and
-for MacPerl). On all other platforms, <code>$^E</code> is always just the same
-as <code>$!</code>.
-</p>
-<p>Under VMS, <code>$^E</code> provides the VMS status value from the last
system
-error. This is more specific information about the last system error
-than that provided by <code>$!</code>. This is particularly important when
<code>$!</code>
-is set to <strong>EVMSERR</strong>.
-</p>
-<p>Under OS/2, <code>$^E</code> is set to the error code of the last call to
OS/2
-API either via CRT, or directly from perl.
-</p>
-<p>Under Win32, <code>$^E</code> always returns the last error information
reported
-by the Win32 call <code>GetLastError()</code> which describes the last error
-from within the Win32 API. Most Win32-specific code will report errors
-via <code>$^E</code>. ANSI C and Unix-like calls set <code>errno</code> and
so most
-portable Perl code will report errors via <code>$!</code>.
-</p>
-<p>Caveats mentioned in the description of <code>$!</code> generally apply to
-<code>$^E</code>, also.
-</p>
-<p>This variable was added in Perl 5.003.
-</p>
-<p>Mnemonic: Extra error explanation.
-</p>
-</dd>
-<dt>$EXCEPTIONS_BEING_CAUGHT</dt>
-<dd><a name="perlvar-_0024EXCEPTIONS_005fBEING_005fCAUGHT"></a>
-</dd>
-<dt>$^S</dt>
-<dd><a name="perlvar-_0024_005eS"></a>
-<p>Current state of the interpreter.
-</p>
-<pre class="verbatim"> $^S State
- --------- -------------------------------------
- undef Parsing module, eval, or main program
- true (1) Executing an eval
- false (0) Otherwise
-</pre>
-<p>The first state may happen in <code>$SIG{__DIE__}</code> and
<code>$SIG{__WARN__}</code>
-handlers.
-</p>
-<p>The English name $EXCEPTIONS_BEING_CAUGHT is slightly misleading, because
-the <code>undef</code> value does not indicate whether exceptions are being
caught,
-since compilation of the main program does not catch exceptions.
-</p>
-<p>This variable was added in Perl 5.004.
-</p>
-</dd>
-<dt>$WARNING</dt>
-<dd><a name="perlvar-_0024WARNING"></a>
-</dd>
-<dt>$^W</dt>
-<dd><a name="perlvar-_0024_005eW"></a>
-<p>The current value of the warning switch, initially true if
<strong>-w</strong> was
-used, false otherwise, but directly modifiable.
-</p>
-<p>See also <a href="warnings.html#Top">(warnings)</a>.
-</p>
-<p>Mnemonic: related to the <strong>-w</strong> switch.
-</p>
-</dd>
-<dt>${^WARNING_BITS}</dt>
-<dd><a name="perlvar-_0024_007b_005eWARNING_005fBITS_007d"></a>
-<p>The current set of warning checks enabled by the <code>use warnings</code>
pragma.
-It has the same scoping as the <code>$^H</code> and <code>%^H</code>
variables. The exact
-values are considered internal to the <a
href="warnings.html#Top">(warnings)</a> pragma and may change
-between versions of Perl.
-</p>
-<p>This variable was added in Perl v5.6.0.
-</p>
-</dd>
-<dt>$OS_ERROR</dt>
-<dd><a name="perlvar-_0024OS_005fERROR"></a>
-</dd>
-<dt>$ERRNO</dt>
-<dd><a name="perlvar-_0024ERRNO"></a>
-</dd>
-<dt>$!</dt>
-<dd><a name="perlvar-_0024_0021"></a>
-<p>When referenced, <code>$!</code> retrieves the current value
-of the C <code>errno</code> integer variable.
-If <code>$!</code> is assigned a numerical value, that value is stored in
<code>errno</code>.
-When referenced as a string, <code>$!</code> yields the system error string
-corresponding to <code>errno</code>.
-</p>
-<p>Many system or library calls set <code>errno</code> if they fail,
-to indicate the cause of failure. They usually do <strong>not</strong>
-set <code>errno</code> to zero if they succeed. This means <code>errno</code>,
-hence <code>$!</code>, is meaningful only <em>immediately</em> after a
<strong>failure</strong>:
-</p>
-<pre class="verbatim"> 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,
- # $! is meaningless.
-</pre>
-<p>Here, <em>meaningless</em> means that <code>$!</code> may be unrelated to
the outcome
-of the <code>open()</code> operator. Assignment to <code>$!</code> is
similarly ephemeral.
-It can be used immediately before invoking the <code>die()</code> operator,
-to set the exit value, or to inspect the system error string
-corresponding to error <em>n</em>, or to restore <code>$!</code> to a
meaningful state.
-</p>
-<p>Mnemonic: What just went bang?
-</p>
-</dd>
-<dt>%OS_ERROR</dt>
-<dd><a name="perlvar-_0025OS_005fERROR"></a>
-</dd>
-<dt>%ERRNO</dt>
-<dd><a name="perlvar-_0025ERRNO"></a>
-</dd>
-<dt>%!</dt>
-<dd><a name="perlvar-_0025_0021"></a>
-<p>Each element of <code>%!</code> has a true value only if <code>$!</code> is
set to that
-value. For example, <code>$!{ENOENT}</code> is true if and only if the current
-value of <code>$!</code> is <code>ENOENT</code>; 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). The
-specific true value is not guaranteed, but in the past has generally
-been the numeric value of <code>$!</code>. To check if a particular key is
-meaningful on your system, use <code>exists $!{the_key}</code>; for a list of
legal
-keys, use <code>keys %!</code>. See <a href="Errno.html#Top">(Errno)</a> for
more information, and also see
-<a href="#perlvar-_0024_0021">$!</a>.
-</p>
-<p>This variable was added in Perl 5.005.
-</p>
-</dd>
-<dt>$CHILD_ERROR</dt>
-<dd><a name="perlvar-_0024CHILD_005fERROR"></a>
-</dd>
-<dt>$?</dt>
-<dd><a name="perlvar-_0024_003f"></a>
-<p>The status returned by the last pipe close, backtick (<code>``</code>)
command,
-successful call to <code>wait()</code> or <code>waitpid()</code>, or from the
<code>system()</code>
-operator. This is just the 16-bit status word returned by the
-traditional Unix <code>wait()</code> system call (or else is made up to look
-like it). Thus, the exit value of the subprocess is really (<code>$? >>
-8</code>), and <code>$? & 127</code> gives which signal, if any, the
process died
-from, and <code>$? & 128</code> reports whether there was a core dump.
-</p>
-<p>Additionally, if the <code>h_errno</code> variable is supported in C, its
value
-is returned via <code>$?</code> if any <code>gethost*()</code> function fails.
-</p>
-<p>If you have installed a signal handler for <code>SIGCHLD</code>, the
-value of <code>$?</code> will usually be wrong outside that handler.
-</p>
-<p>Inside an <code>END</code> subroutine <code>$?</code> contains the value
that is going to be
-given to <code>exit()</code>. You can modify <code>$?</code> in an
<code>END</code> subroutine to
-change the exit status of your program. For example:
-</p>
-<pre class="verbatim"> END {
- $? = 1 if $? == 255; # die would make it 255
- }
-</pre>
-<p>Under VMS, the pragma <code>use vmsish 'status'</code> makes
<code>$?</code> reflect the
-actual VMS exit status, instead of the default emulation of POSIX
-status; see <a href="#perlvms-_0024_003f">perlvms $?</a> for details.
-</p>
-<p>Mnemonic: similar to <strong>sh</strong> and <strong>ksh</strong>.
-</p>
-</dd>
-<dt>$EVAL_ERROR</dt>
-<dd><a name="perlvar-_0024EVAL_005fERROR"></a>
-</dd>
-<dt>$@</dt>
-<dd><a name="perlvar-_0024_0040"></a>
-<p>The Perl syntax error message from the
-last <code>eval()</code> operator. If <code>$@</code> is
-the null string, the last <code>eval()</code> parsed and executed correctly
-(although the operations you invoked may have failed in the normal
-fashion).
-</p>
-<p>Warning messages are not collected in this variable. You can, however,
-set up a routine to process warnings by setting <code>$SIG{__WARN__}</code> as
-described in <a href="#perlvar-_0025SIG">%SIG</a>.
-</p>
-<p>Mnemonic: Where was the syntax error "at"?
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlvar-Variables-related-to-the-interpreter-state"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvar-Deprecated-and-removed-variables" accesskey="n"
rel="next">perlvar Deprecated and removed variables</a>, Previous: <a
href="#perlvar-Error-Variables" accesskey="p" rel="prev">perlvar Error
Variables</a>, Up: <a href="#perlvar-SPECIAL-VARIABLES" accesskey="u"
rel="up">perlvar SPECIAL VARIABLES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Variables-related-to-the-interpreter-state"></a>
-<h4 class="subsection">86.3.5 Variables related to the interpreter state</h4>
-
-<p>These variables provide information about the current interpreter state.
-</p>
-<dl compact="compact">
-<dt>$COMPILING</dt>
-<dd><a name="perlvar-_0024COMPILING"></a>
-</dd>
-<dt>$^C</dt>
-<dd><a name="perlvar-_0024_005eC"></a>
-<p>The current value of the flag associated with the <strong>-c</strong>
switch.
-Mainly of use with <strong>-MO=...</strong> to allow code to alter its behavior
-when being compiled, such as for example to <code>AUTOLOAD</code> at compile
-time rather than normal, deferred loading. Setting
-<code>$^C = 1</code> is similar to calling <code>B::minus_c</code>.
-</p>
-<p>This variable was added in Perl v5.6.0.
-</p>
-</dd>
-<dt>$DEBUGGING</dt>
-<dd><a name="perlvar-_0024DEBUGGING"></a>
-</dd>
-<dt>$^D</dt>
-<dd><a name="perlvar-_0024_005eD"></a>
-<p>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
-<code>$^D = 10</code> or <code>$^D = "st"</code>.
-</p>
-<p>Mnemonic: value of <strong>-D</strong> switch.
-</p>
-</dd>
-<dt>${^ENCODING}</dt>
-<dd><a name="perlvar-_0024_007b_005eENCODING_007d"></a>
-<p>DEPRECATED!!!
-</p>
-<p>The <em>object reference</em> to the <code>Encode</code> 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 <code>undef</code>.
-</p>
-<p>Setting this variable to any other value than <code>undef</code> is
deprecated due
-to fundamental defects in its design and implementation. It is planned
-to remove it from a future Perl version. Its purpose was to allow your
-non-ASCII Perl scripts to not have to be written in UTF-8; this was
-useful before editors that worked on UTF-8 encoded text were common, but
-that was long ago. It causes problems, such as affecting the operation
-of other modules that aren’t expecting it, causing general mayhem. Its
-use can lead to segfaults.
-</p>
-<p>If you need something like this functionality, you should use the
-<a href="encoding.html#Top">(encoding)</a> pragma, which is also deprecated,
but has fewer nasty side
-effects.
-</p>
-<p>If you are coming here because code of yours is being adversely affected
-by someone’s use of this variable, you can usually work around it by
-doing this:
-</p>
-<pre class="verbatim"> local ${^ENCODING};
-</pre>
-<p>near the beginning of the functions that are getting broken. This
-undefines the variable during the scope of execution of the including
-function.
-</p>
-<p>This variable was added in Perl 5.8.2.
-</p>
-</dd>
-<dt>${^GLOBAL_PHASE}</dt>
-<dd><a name="perlvar-_0024_007b_005eGLOBAL_005fPHASE_007d"></a>
-<p>The current phase of the perl interpreter.
-</p>
-<p>Possible values are:
-</p>
-<dl compact="compact">
-<dt>CONSTRUCT</dt>
-<dd><a name="perlvar-CONSTRUCT"></a>
-<p>The <code>PerlInterpreter*</code> is being constructed via
<code>perl_construct</code>. This
-value is mostly there for completeness and for use via the
-underlying C variable <code>PL_phase</code>. It’s not really possible
for Perl
-code to be executed unless construction of the interpreter is
-finished.
-</p>
-</dd>
-<dt>START</dt>
-<dd><a name="perlvar-START"></a>
-<p>This is the global compile-time. That includes, basically, every
-<code>BEGIN</code> block executed directly or indirectly from during the
-compile-time of the top-level program.
-</p>
-<p>This phase is not called "BEGIN" to avoid confusion with
-<code>BEGIN</code>-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
-<code>eval "use SomeModule"</code> are not global interpreter
phases, and
-therefore aren’t reflected by <code>${^GLOBAL_PHASE}</code>.
-</p>
-</dd>
-<dt>CHECK</dt>
-<dd><a name="perlvar-CHECK"></a>
-<p>Execution of any <code>CHECK</code> blocks.
-</p>
-</dd>
-<dt>INIT</dt>
-<dd><a name="perlvar-INIT"></a>
-<p>Similar to "CHECK", but for <code>INIT</code>-blocks, not
<code>CHECK</code> blocks.
-</p>
-</dd>
-<dt>RUN</dt>
-<dd><a name="perlvar-RUN"></a>
-<p>The main run-time, i.e. the execution of <code>PL_main_root</code>.
-</p>
-</dd>
-<dt>END</dt>
-<dd><a name="perlvar-END"></a>
-<p>Execution of any <code>END</code> blocks.
-</p>
-</dd>
-<dt>DESTRUCT</dt>
-<dd><a name="perlvar-DESTRUCT"></a>
-<p>Global destruction.
-</p>
-</dd>
-</dl>
-
-<p>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.
-</p>
-<p>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.
-</p>
-<p>An example of all of the phases Perl code can see:
-</p>
-<pre class="verbatim"> BEGIN { print "compile-time:
${^GLOBAL_PHASE}\n" }
-
- INIT { print "init-time: ${^GLOBAL_PHASE}\n" }
-
- CHECK { print "check-time: ${^GLOBAL_PHASE}\n" }
-
- {
- package Print::Phase;
-
- sub new {
- my ($class, $time) = @_;
- return bless \$time, $class;
- }
-
- sub DESTROY {
- my $self = shift;
- print "$$self: ${^GLOBAL_PHASE}\n";
- }
- }
-
- print "run-time: ${^GLOBAL_PHASE}\n";
-
- my $runtime = Print::Phase->new(
- "lexical variables are garbage collected before END"
- );
-
- END { print "end-time: ${^GLOBAL_PHASE}\n" }
-
- our $destruct = Print::Phase->new(
- "package variables are garbage collected after END"
- );
-</pre>
-<p>This will print out
-</p>
-<pre class="verbatim"> 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
-</pre>
-<p>This variable was added in Perl 5.14.0.
-</p>
-</dd>
-<dt>$^H</dt>
-<dd><a name="perlvar-_0024_005eH"></a>
-<p>WARNING: This variable is strictly for
-internal use only. Its availability,
-behavior, and contents are subject to change without notice.
-</p>
-<p>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.
-</p>
-<p>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 <code>$^H</code> 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 <code>$^H</code>.
-</p>
-<p>This behavior provides the semantic of lexical scoping, and is used in,
-for instance, the <code>use strict</code> pragma.
-</p>
-<p>The contents should be an integer; different bits of it are used for
-different pragmatic flags. Here’s an example:
-</p>
-<pre class="verbatim"> sub add_100 { $^H |= 0x100 }
-
- sub foo {
- BEGIN { add_100() }
- bar->baz($boon);
- }
-</pre>
-<p>Consider what happens during execution of the BEGIN block. At this point
-the BEGIN block has already been compiled, but the body of <code>foo()</code>
is still
-being compiled. The new value of <code>$^H</code>
-will therefore be visible only while
-the body of <code>foo()</code> is being compiled.
-</p>
-<p>Substitution of <code>BEGIN { add_100() }</code> block with:
-</p>
-<pre class="verbatim"> BEGIN { require strict; strict->import('vars') }
-</pre>
-<p>demonstrates how <code>use strict 'vars'</code> is implemented.
Here’s a conditional
-version of the same lexical pragma:
-</p>
-<pre class="verbatim"> BEGIN {
- require strict; strict->import('vars') if $condition
- }
-</pre>
-<p>This variable was added in Perl 5.003.
-</p>
-</dd>
-<dt>%^H</dt>
-<dd><a name="perlvar-_0025_005eH"></a>
-<p>The <code>%^H</code> hash provides the same scoping semantic as
<code>$^H</code>. This makes
-it useful for implementation of lexically scoped pragmas. See
-<a href="#perlpragma-NAME">perlpragma NAME</a>. All the entries are
stringified when accessed at
-runtime, so only simple values can be accommodated. This means no
-pointers to objects, for example.
-</p>
-<p>When putting items into <code>%^H</code>, in order to avoid conflicting
with other
-users of the hash there is a convention regarding which keys to use.
-A module should use only keys that begin with the module’s name (the
-name of its main package) and a "/" character. For example, a module
-<code>Foo::Bar</code> should use keys such as <code>Foo::Bar/baz</code>.
-</p>
-<p>This variable was added in Perl v5.6.0.
-</p>
-</dd>
-<dt>${^OPEN}</dt>
-<dd><a name="perlvar-_0024_007b_005eOPEN_007d"></a>
-<p>An internal variable used by PerlIO. A string in two parts, separated
-by a <code>\0</code> byte, the first part describes the input layers, the
second
-part describes the output layers.
-</p>
-<p>This variable was added in Perl v5.8.0.
-</p>
-</dd>
-<dt>$PERLDB</dt>
-<dd><a name="perlvar-_0024PERLDB"></a>
-</dd>
-<dt>$^P</dt>
-<dd><a name="perlvar-_0024_005eP"></a>
-<p>The internal variable for debugging support. The meanings of the
-various bits are subject to change, but currently indicate:
-</p>
-<dl compact="compact">
-<dt>0x01</dt>
-<dd><a name="perlvar-0x01"></a>
-<p>Debug subroutine enter/exit.
-</p>
-</dd>
-<dt>0x02</dt>
-<dd><a name="perlvar-0x02"></a>
-<p>Line-by-line debugging. Causes <code>DB::DB()</code> subroutine to be
called for
-each statement executed. Also causes saving source code lines (like
-0x400).
-</p>
-</dd>
-<dt>0x04</dt>
-<dd><a name="perlvar-0x04"></a>
-<p>Switch off optimizations.
-</p>
-</dd>
-<dt>0x08</dt>
-<dd><a name="perlvar-0x08"></a>
-<p>Preserve more data for future interactive inspections.
-</p>
-</dd>
-<dt>0x10</dt>
-<dd><a name="perlvar-0x10"></a>
-<p>Keep info about source lines on which a subroutine is defined.
-</p>
-</dd>
-<dt>0x20</dt>
-<dd><a name="perlvar-0x20"></a>
-<p>Start with single-step on.
-</p>
-</dd>
-<dt>0x40</dt>
-<dd><a name="perlvar-0x40"></a>
-<p>Use subroutine address instead of name when reporting.
-</p>
-</dd>
-<dt>0x80</dt>
-<dd><a name="perlvar-0x80"></a>
-<p>Report <code>goto &subroutine</code> as well.
-</p>
-</dd>
-<dt>0x100</dt>
-<dd><a name="perlvar-0x100"></a>
-<p>Provide informative "file" names for evals based on the place
they were compiled.
-</p>
-</dd>
-<dt>0x200</dt>
-<dd><a name="perlvar-0x200"></a>
-<p>Provide informative names to anonymous subroutines based on the place they
-were compiled.
-</p>
-</dd>
-<dt>0x400</dt>
-<dd><a name="perlvar-0x400"></a>
-<p>Save source code lines into <code>@{"_<$filename"}</code>.
-</p>
-</dd>
-<dt>0x800</dt>
-<dd><a name="perlvar-0x800"></a>
-<p>When saving source, include evals that generate no subroutines.
-</p>
-</dd>
-<dt>0x1000</dt>
-<dd><a name="perlvar-0x1000"></a>
-<p>When saving source, include source that did not compile.
-</p>
-</dd>
-</dl>
-
-<p>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 <a href="#perldebguts-NAME">perldebguts NAME</a>.
-</p>
-</dd>
-<dt>${^TAINT}</dt>
-<dd><a name="perlvar-_0024_007b_005eTAINT_007d"></a>
-<p>Reflects if taint mode is on or off. 1 for on (the program was run with
-<strong>-T</strong>), 0 for off, -1 when only taint warnings are enabled (i.e.
with
-<strong>-t</strong> or <strong>-TU</strong>).
-</p>
-<p>This variable is read-only.
-</p>
-<p>This variable was added in Perl v5.8.0.
-</p>
-</dd>
-<dt>${^UNICODE}</dt>
-<dd><a name="perlvar-_0024_007b_005eUNICODE_007d"></a>
-<p>Reflects certain Unicode settings of Perl. See <a
href="#perlrun-NAME">perlrun NAME</a>
-documentation for the <code>-C</code> switch for more information about
-the possible values.
-</p>
-<p>This variable is set during Perl startup and is thereafter read-only.
-</p>
-<p>This variable was added in Perl v5.8.2.
-</p>
-</dd>
-<dt>${^UTF8CACHE}</dt>
-<dd><a name="perlvar-_0024_007b_005eUTF8CACHE_007d"></a>
-<p>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.
-</p>
-<p>This variable was added in Perl v5.8.9. It is subject to change or
-removal without notice, but is currently used to avoid recalculating the
-boundaries of multi-byte UTF-8-encoded characters.
-</p>
-</dd>
-<dt>${^UTF8LOCALE}</dt>
-<dd><a name="perlvar-_0024_007b_005eUTF8LOCALE_007d"></a>
-<p>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 <code>-CL</code>
command-line
-switch); see <a href="#perlrun-NAME">perlrun NAME</a> for more info on this.
-</p>
-<p>This variable was added in Perl v5.8.8.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlvar-Deprecated-and-removed-variables"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlvar-Variables-related-to-the-interpreter-state"
accesskey="p" rel="prev">perlvar Variables related to the interpreter
state</a>, Up: <a href="#perlvar-SPECIAL-VARIABLES" accesskey="u"
rel="up">perlvar SPECIAL VARIABLES</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Deprecated-and-removed-variables"></a>
-<h4 class="subsection">86.3.6 Deprecated and removed variables</h4>
-
-<p>Deprecating a variable announces the intent of the perl maintainers to
-eventually remove the variable from the language. It may still be
-available despite its status. Using a deprecated variable triggers
-a warning.
-</p>
-<p>Once a variable is removed, its use triggers an error telling you
-the variable is unsupported.
-</p>
-<p>See <a href="#perldiag-NAME">perldiag NAME</a> for details about error
messages.
-</p>
-<dl compact="compact">
-<dt>$#</dt>
-<dd><a name="perlvar-_0024_0023"></a>
-<p><code>$#</code> was a variable that could be used to format printed numbers.
-After a deprecation cycle, its magic was removed in Perl v5.10.0 and
-using it now triggers a warning: <code>$# is no longer supported</code>.
-</p>
-<p>This is not the sigil you use in front of an array name to get the
-last index, like <code>$#array</code>. That’s still how you get the
last index
-of an array in Perl. The two have nothing to do with each other.
-</p>
-<p>Deprecated in Perl 5.
-</p>
-<p>Removed in Perl v5.10.0.
-</p>
-</dd>
-<dt>$*</dt>
-<dd><a name="perlvar-_0024_002a"></a>
-<p><code>$*</code> was a variable that you could use to enable multiline
matching.
-After a deprecation cycle, its magic was removed in Perl v5.10.0.
-Using it now triggers a warning: <code>$* is no longer supported</code>.
-You should use the <code>/s</code> and <code>/m</code> regexp modifiers
instead.
-</p>
-<p>Deprecated in Perl 5.
-</p>
-<p>Removed in Perl v5.10.0.
-</p>
-</dd>
-<dt>$[</dt>
-<dd><a name="perlvar-_0024_005b"></a>
-<p>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 <strong>awk</strong>
(or Fortran)
-when subscripting and when evaluating the index() and substr() functions.
-</p>
-<p>As of release 5 of Perl, assignment to <code>$[</code> 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.
-</p>
-<p>Prior to Perl v5.10.0, assignment to <code>$[</code> could be seen from
outer lexical
-scopes in the same file, unlike other compile-time directives (such as
-<a href="strict.html#Top">(strict)</a>). Using local() on it would bind its
value strictly to a lexical
-block. Now it is always lexically scoped.
-</p>
-<p>As of Perl v5.16.0, it is implemented by the <a
href="arybase.html#Top">(arybase)</a> module. See
-<a href="arybase.html#Top">(arybase)</a> for more details on its behaviour.
-</p>
-<p>Under <code>use v5.16</code>, or <code>no feature
"array_base"</code>, <code>$[</code> no longer has any
-effect, and always contains 0. Assigning 0 to it is permitted, but any
-other value will produce an error.
-</p>
-<p>Mnemonic: [ begins subscripts.
-</p>
-<p>Deprecated in Perl v5.12.0.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlvms"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlvar" accesskey="p" rel="prev">perlvar</a>, Up: <a
href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="perlvms-1"></a>
-<h2 class="chapter">87 perlvms</h2>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlvms-NAME"
accesskey="1">perlvms NAME</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlvms-DESCRIPTION"
accesskey="2">perlvms DESCRIPTION</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlvms-Installation"
accesskey="3">perlvms Installation</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Organization-of-Perl-Images" accesskey="4">perlvms Organization
of Perl Images</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-File-specifications" accesskey="5">perlvms File
specifications</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-PERL5LIB-and-PERLLIB" accesskey="6">perlvms PERL5LIB and
PERLLIB</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-The-Perl-Forked-Debugger" accesskey="7">perlvms The Perl Forked
Debugger</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-PERL_005fVMS_005fEXCEPTION_005fDEBUG" accesskey="8">perlvms
PERL_VMS_EXCEPTION_DEBUG</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlvms-Command-line"
accesskey="9">perlvms Command line</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Perl-functions">perlvms Perl
functions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Perl-variables">perlvms Perl
variables</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Standard-modules-with-VMS_002dspecific-differences">perlvms
Standard modules with VMS-specific
differences</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Revision-date">perlvms Revision
date</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlvms-AUTHOR">perlvms
AUTHOR</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlvms-NAME"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-DESCRIPTION" accesskey="n" rel="next">perlvms
DESCRIPTION</a>, Up: <a href="#perlvms" accesskey="u" rel="up">perlvms</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="NAME-86"></a>
-<h3 class="section">87.1 NAME</h3>
-
-<p>perlvms - VMS-specific documentation for Perl
-</p>
-<hr>
-<a name="perlvms-DESCRIPTION"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Installation" accesskey="n" rel="next">perlvms
Installation</a>, Previous: <a href="#perlvms-NAME" accesskey="p"
rel="prev">perlvms NAME</a>, Up: <a href="#perlvms" accesskey="u"
rel="up">perlvms</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="DESCRIPTION-84"></a>
-<h3 class="section">87.2 DESCRIPTION</h3>
-
-<p>Gathered below are notes describing details of Perl 5’s
-behavior on VMS. They are a supplement to the regular Perl 5
-documentation, so we have focussed on the ways in which Perl
-5 functions differently under VMS than it does under Unix,
-and on the interactions between Perl and the rest of the
-operating system. We haven’t tried to duplicate complete
-descriptions of Perl features from the main Perl
-documentation, which can be found in the <samp>[.pod]</samp>
-subdirectory of the Perl distribution.
-</p>
-<p>We hope these notes will save you from confusion and lost
-sleep when writing Perl scripts on VMS. If you find we’ve
-missed something you think should appear here, please don’t
-hesitate to drop a line to address@hidden
-</p>
-<hr>
-<a name="perlvms-Installation"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Organization-of-Perl-Images" accesskey="n"
rel="next">perlvms Organization of Perl Images</a>, Previous: <a
href="#perlvms-DESCRIPTION" accesskey="p" rel="prev">perlvms DESCRIPTION</a>,
Up: <a href="#perlvms" accesskey="u" rel="up">perlvms</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Installation-1"></a>
-<h3 class="section">87.3 Installation</h3>
-
-<p>Directions for building and installing Perl 5 can be found in
-the file <samp>README.vms</samp> in the main source directory of the
-Perl distribution.
-</p>
-<hr>
-<a name="perlvms-Organization-of-Perl-Images"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-File-specifications" accesskey="n" rel="next">perlvms
File specifications</a>, Previous: <a href="#perlvms-Installation"
accesskey="p" rel="prev">perlvms Installation</a>, Up: <a href="#perlvms"
accesskey="u" rel="up">perlvms</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Organization-of-Perl-Images"></a>
-<h3 class="section">87.4 Organization of Perl Images</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlvms-Core-Images"
accesskey="1">perlvms Core Images</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlvms-Perl-Extensions"
accesskey="2">perlvms Perl Extensions</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Installing-static-extensions" accesskey="3">perlvms Installing
static extensions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Installing-dynamic-extensions" accesskey="4">perlvms Installing
dynamic extensions</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlvms-Core-Images"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Perl-Extensions" accesskey="n" rel="next">perlvms Perl
Extensions</a>, Up: <a href="#perlvms-Organization-of-Perl-Images"
accesskey="u" rel="up">perlvms Organization of Perl Images</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Core-Images"></a>
-<h4 class="subsection">87.4.1 Core Images</h4>
-
-<p>During the build process, three Perl images are produced.
-<samp>Miniperl.Exe</samp> is an executable image which contains all of
-the basic functionality of Perl, but cannot take advantage of
-Perl XS extensions and has a hard-wired list of library locations
-for loading pure-Perl modules. It is used extensively to build and
-test Perl and various extensions, but is not installed.
-</p>
-<p>Most of the complete Perl resides in the shareable image
<samp>PerlShr.Exe</samp>,
-which provides a core to which the Perl executable image and all Perl
-extensions are linked. It is generally located via the logical name
-<samp>PERLSHR</samp>. While it’s possible to put the image in
<samp>SYS$SHARE</samp> to
-make it loadable, that’s not recommended. And while you may wish to
-INSTALL the image for performance reasons, you should not install it
-with privileges; if you do, the result will not be what you expect as
-image privileges are disabled during Perl start-up.
-</p>
-<p>Finally, <samp>Perl.Exe</samp> is an executable image containing the main
-entry point for Perl, as well as some initialization code. It
-should be placed in a public directory, and made world executable.
-In order to run Perl with command line arguments, you should
-define a foreign command to invoke this image.
-</p>
-<hr>
-<a name="perlvms-Perl-Extensions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Installing-static-extensions" accesskey="n"
rel="next">perlvms Installing static extensions</a>, Previous: <a
href="#perlvms-Core-Images" accesskey="p" rel="prev">perlvms Core Images</a>,
Up: <a href="#perlvms-Organization-of-Perl-Images" accesskey="u"
rel="up">perlvms Organization of Perl Images</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Perl-Extensions"></a>
-<h4 class="subsection">87.4.2 Perl Extensions</h4>
-
-<p>Perl extensions are packages which provide both XS and Perl code
-to add new functionality to perl. (XS is a meta-language which
-simplifies writing C code which interacts with Perl, see
-<a href="perlxs.html#Top">(perlxs)</a> for more details.) The Perl code for an
-extension is treated like any other library module - it’s
-made available in your script through the appropriate
-<code>use</code> or <code>require</code> statement, and usually defines a Perl
-package containing the extension.
-</p>
-<p>The portion of the extension provided by the XS code may be
-connected to the rest of Perl in either of two ways. In the
-<strong>static</strong> configuration, the object code for the extension is
-linked directly into <samp>PerlShr.Exe</samp>, and is initialized whenever
-Perl is invoked. In the <strong>dynamic</strong> configuration, the
extension’s
-machine code is placed into a separate shareable image, which is
-mapped by Perl’s DynaLoader when the extension is <code>use</code>d or
-<code>require</code>d in your script. This allows you to maintain the
-extension as a separate entity, at the cost of keeping track of the
-additional shareable image. Most extensions can be set up as either
-static or dynamic.
-</p>
-<p>The source code for an extension usually resides in its own
-directory. At least three files are generally provided:
-<em>Extshortname</em><samp>.xs</samp> (where <em>Extshortname</em> is the
portion of
-the extension’s name following the last <code>::</code>), containing
-the XS code, <em>Extshortname</em><samp>.pm</samp>, the Perl library module
-for the extension, and <samp>Makefile.PL</samp>, a Perl script which uses
-the <code>MakeMaker</code> library modules supplied with Perl to generate
-a <samp>Descrip.MMS</samp> file for the extension.
-</p>
-<hr>
-<a name="perlvms-Installing-static-extensions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Installing-dynamic-extensions" accesskey="n"
rel="next">perlvms Installing dynamic extensions</a>, Previous: <a
href="#perlvms-Perl-Extensions" accesskey="p" rel="prev">perlvms Perl
Extensions</a>, Up: <a href="#perlvms-Organization-of-Perl-Images"
accesskey="u" rel="up">perlvms Organization of Perl Images</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Installing-static-extensions"></a>
-<h4 class="subsection">87.4.3 Installing static extensions</h4>
-
-<p>Since static extensions are incorporated directly into
-<samp>PerlShr.Exe</samp>, you’ll have to rebuild Perl to incorporate a
-new extension. You should edit the main <samp>Descrip.MMS</samp> or
<samp>Makefile</samp>
-you use to build Perl, adding the extension’s name to the
<code>ext</code>
-macro, and the extension’s object file to the <code>extobj</code> macro.
-You’ll also need to build the extension’s object file, either
-by adding dependencies to the main <samp>Descrip.MMS</samp>, or using a
-separate <samp>Descrip.MMS</samp> for the extension. Then, rebuild
-<samp>PerlShr.Exe</samp> to incorporate the new code.
-</p>
-<p>Finally, you’ll need to copy the extension’s Perl library
-module to the <samp>[.</samp><em>Extname</em><samp>]</samp> subdirectory under
one
-of the directories in <code>@INC</code>, where <em>Extname</em> is the name
-of the extension, with all <code>::</code> replaced by <code>.</code> (e.g.
-the library module for extension Foo::Bar would be copied
-to a <samp>[.Foo.Bar]</samp> subdirectory).
-</p>
-<hr>
-<a name="perlvms-Installing-dynamic-extensions"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlvms-Installing-static-extensions" accesskey="p"
rel="prev">perlvms Installing static extensions</a>, Up: <a
href="#perlvms-Organization-of-Perl-Images" accesskey="u" rel="up">perlvms
Organization of Perl Images</a> [<a href="#SEC_Contents" title="Table of
contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Installing-dynamic-extensions"></a>
-<h4 class="subsection">87.4.4 Installing dynamic extensions</h4>
-
-<p>In general, the distributed kit for a Perl extension includes
-a file named Makefile.PL, which is a Perl program which is used
-to create a <samp>Descrip.MMS</samp> file which can be used to build and
-install the files required by the extension. The kit should be
-unpacked into a directory tree <strong>not</strong> under the main Perl source
-directory, and the procedure for building the extension is simply
-</p>
-<pre class="verbatim"> $ perl Makefile.PL ! Create Descrip.MMS
- $ mmk ! Build necessary files
- $ mmk test ! Run test code, if supplied
- $ mmk install ! Install into public Perl tree
-</pre>
-<p>VMS support for this process in the current release of Perl
-is sufficient to handle most extensions. (See the MakeMaker
-documentation for more details on installation options for
-extensions.)
-</p>
-<ul>
-<li> the
<samp>[.Lib.Auto.</samp><em>Arch</em><em>$PVers</em><em>Extname</em><samp>]</samp>
subdirectory
-of one of the directories in <code>@INC</code> (where <em>PVers</em>
-is the version of Perl you’re using, as supplied in <code>$]</code>,
-with ’.’ converted to ’_’), or
-
-</li><li> one of the directories in <code>@INC</code>, or
-
-</li><li> a directory which the extensions Perl library module
-passes to the DynaLoader when asking it to map
-the shareable image, or
-
-</li><li> <samp>Sys$Share</samp> or <samp>Sys$Library</samp>.
-
-</li></ul>
-
-<p>If the shareable image isn’t in any of these places, you’ll need
-to define a logical name <em>Extshortname</em>, where <em>Extshortname</em>
-is the portion of the extension’s name after the last <code>::</code>,
which
-translates to the full file specification of the shareable image.
-</p>
-<hr>
-<a name="perlvms-File-specifications"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-PERL5LIB-and-PERLLIB" accesskey="n" rel="next">perlvms
PERL5LIB and PERLLIB</a>, Previous: <a
href="#perlvms-Organization-of-Perl-Images" accesskey="p" rel="prev">perlvms
Organization of Perl Images</a>, Up: <a href="#perlvms" accesskey="u"
rel="up">perlvms</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="File-specifications"></a>
-<h3 class="section">87.5 File specifications</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlvms-Syntax"
accesskey="1">perlvms Syntax</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlvms-Filename-Case"
accesskey="2">perlvms Filename Case</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlvms-Symbolic-Links"
accesskey="3">perlvms Symbolic Links</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlvms-Wildcard-expansion"
accesskey="4">perlvms Wildcard expansion</a>:</td><td> </td><td
align="left" valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a href="#perlvms-Pipes"
accesskey="5">perlvms Pipes</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlvms-Syntax"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Filename-Case" accesskey="n" rel="next">perlvms
Filename Case</a>, Up: <a href="#perlvms-File-specifications" accesskey="u"
rel="up">perlvms File specifications</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Syntax-1"></a>
-<h4 class="subsection">87.5.1 Syntax</h4>
-
-<p>We have tried to make Perl aware of both VMS-style and Unix-style file
-specifications wherever possible. You may use either style, or both,
-on the command line and in scripts, but you may not combine the two
-styles within a single file specification. VMS Perl interprets Unix
-pathnames in much the same way as the CRTL (<em>e.g.</em> the first component
-of an absolute path is read as the device name for the VMS file
-specification). There are a set of functions provided in the
-<code>VMS::Filespec</code> package for explicit interconversion between VMS and
-Unix syntax; its documentation provides more details.
-</p>
-<p>We’ve tried to minimize the dependence of Perl library
-modules on Unix syntax, but you may find that some of these,
-as well as some scripts written for Unix systems, will
-require that you use Unix syntax, since they will assume that
-’/’ is the directory separator, <em>etc.</em> If you find
instances
-of this in the Perl distribution itself, please let us know,
-so we can try to work around them.
-</p>
-<p>Also when working on Perl programs on VMS, if you need a syntax
-in a specific operating system format, then you need either to
-check the appropriate DECC$ feature logical, or call a conversion
-routine to force it to that format.
-</p>
-<p>The feature logical name DECC$FILENAME_UNIX_REPORT modifies traditional
-Perl behavior in the conversion of file specifications from Unix to VMS
-format in order to follow the extended character handling rules now
-expected by the CRTL. Specifically, when this feature is in effect, the
-<code>./.../</code> in a Unix path is now translated to <code>[.^.^.^.]</code>
instead of
-the traditional VMS <code>[...]</code>. To be compatible with what MakeMaker
-expects, if a VMS path cannot be translated to a Unix path, it is
-passed through unchanged, so <code>unixify("[...]")</code> will
return <code>[...]</code>.
-</p>
-<p>There are several ambiguous cases where a conversion routine cannot
-determine whether an input filename is in Unix format or in VMS format,
-since now both VMS and Unix file specifications may have characters in
-them that could be mistaken for syntax delimiters of the other type. So
-some pathnames simply cannot be used in a mode that allows either type
-of pathname to be present. Perl will tend to assume that an ambiguous
-filename is in Unix format.
-</p>
-<p>Allowing "." as a version delimiter is simply incompatible with
-determining whether a pathname is in VMS format or in Unix format with
-extended file syntax. There is no way to know whether "perl-5.8.6"
is a
-Unix "perl-5.8.6" or a VMS "perl-5.8;6" when passing it to
unixify() or
-vmsify().
-</p>
-<p>The DECC$FILENAME_UNIX_REPORT logical name controls how Perl interprets
-filenames to the extent that Perl uses the CRTL internally for many
-purposes, and attempts to follow CRTL conventions for reporting
-filenames. The DECC$FILENAME_UNIX_ONLY feature differs in that it
-expects all filenames passed to the C run-time to be already in Unix
-format. This feature is not yet supported in Perl since Perl uses
-traditional OpenVMS file specifications internally and in the test
-harness, and it is not yet clear whether this mode will be useful or
-useable. The feature logical name DECC$POSIX_COMPLIANT_PATHNAMES is new
-with the RMS Symbolic Link SDK and included with OpenVMS v8.3, but is
-not yet supported in Perl.
-</p>
-<hr>
-<a name="perlvms-Filename-Case"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Symbolic-Links" accesskey="n" rel="next">perlvms
Symbolic Links</a>, Previous: <a href="#perlvms-Syntax" accesskey="p"
rel="prev">perlvms Syntax</a>, Up: <a href="#perlvms-File-specifications"
accesskey="u" rel="up">perlvms File specifications</a> [<a
href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Filename-Case"></a>
-<h4 class="subsection">87.5.2 Filename Case</h4>
-
-<p>Perl enables DECC$EFS_CASE_PRESERVE and DECC$ARGV_PARSE_STYLE by
-default. Note that the latter only takes effect when extended parse
-is set in the process in which Perl is running. When these features
-are explicitly disabled in the environment or the CRTL does not support
-them, Perl follows the traditional CRTL behavior of downcasing command-line
-arguments and returning file specifications in lower case only.
-</p>
-<p><em>N. B.</em> It is very easy to get tripped up using a mixture of other
-programs, external utilities, and Perl scripts that are in varying
-states of being able to handle case preservation. For example, a file
-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 expectations 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.
-</p>
-<p>OpenVMS Alpha v7.3-1 and later and all version of OpenVMS I64 support
-case sensitivity as a process setting (see <code>SET PROCESS
-/CASE_LOOKUP=SENSITIVE</code>). Perl does not currently support case
-sensitivity on VMS, but it may in the future, so Perl programs should
-use the <code>File::Spec->case_tolerant</code> method to determine the
state, and
-not the <code>$^O</code> variable.
-</p>
-<hr>
-<a name="perlvms-Symbolic-Links"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Wildcard-expansion" accesskey="n" rel="next">perlvms
Wildcard expansion</a>, Previous: <a href="#perlvms-Filename-Case"
accesskey="p" rel="prev">perlvms Filename Case</a>, Up: <a
href="#perlvms-File-specifications" accesskey="u" rel="up">perlvms File
specifications</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Symbolic-Links"></a>
-<h4 class="subsection">87.5.3 Symbolic Links</h4>
-
-<p>When built on an ODS-5 volume with symbolic links enabled, Perl by
-default supports symbolic links when the requisite support is available
-in the filesystem and CRTL (generally 64-bit OpenVMS v8.3 and later).
-There are a number of limitations and caveats to be aware of when
-working with symbolic links on VMS. Most notably, the target of a valid
-symbolic link must be expressed as a Unix-style path and it must exist
-on a volume visible from your POSIX root (see the <code>SHOW ROOT</code>
command
-in DCL help). For further details on symbolic link capabilities and
-requirements, see chapter 12 of the CRTL manual that ships with OpenVMS
-v8.3 or later.
-</p>
-<hr>
-<a name="perlvms-Wildcard-expansion"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Pipes" accesskey="n" rel="next">perlvms Pipes</a>,
Previous: <a href="#perlvms-Symbolic-Links" accesskey="p" rel="prev">perlvms
Symbolic Links</a>, Up: <a href="#perlvms-File-specifications" accesskey="u"
rel="up">perlvms File specifications</a> [<a href="#SEC_Contents"
title="Table of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Wildcard-expansion"></a>
-<h4 class="subsection">87.5.4 Wildcard expansion</h4>
-
-<p>File specifications containing wildcards are allowed both on
-the command line and within Perl globs (e.g. <code><*.c></code>). If
-the wildcard filespec uses VMS syntax, the resultant
-filespecs will follow VMS syntax; if a Unix-style filespec is
-passed in, Unix-style filespecs will be returned.
-Similar to the behavior of wildcard globbing for a Unix shell,
-one can escape command line wildcards with double quotation
-marks <code>"</code> around a perl program command line argument.
However,
-owing to the stripping of <code>"</code> characters carried out by the C
-handling of argv you will need to escape a construct such as
-this one (in a directory containing the files <samp>PERL.C</samp>,
<samp>PERL.EXE</samp>,
-<samp>PERL.H</samp>, and <samp>PERL.OBJ</samp>):
-</p>
-<pre class="verbatim"> $ perl -e "print join(' ',@ARGV)" perl.*
- perl.c perl.exe perl.h perl.obj
-</pre>
-<p>in the following triple quoted manner:
-</p>
-<pre class="verbatim"> $ perl -e "print join(' ',@ARGV)"
"""perl.*"""
- perl.*
-</pre>
-<p>In both the case of unquoted command line arguments or in calls
-to <code>glob()</code> VMS wildcard expansion is performed. (csh-style
-wildcard expansion is available if you use <code>File::Glob::glob</code>.)
-If the wildcard filespec contains a device or directory
-specification, then the resultant filespecs will also contain
-a device and directory; otherwise, device and directory
-information are removed. VMS-style resultant filespecs will
-contain a full device and directory, while Unix-style
-resultant filespecs will contain only as much of a directory
-path as was present in the input filespec. For example, if
-your default directory is Perl_Root:[000000], the expansion
-of <code>[.t]*.*</code> will yield filespecs like
-"perl_root:[t]base.dir", while the expansion of <code>t/*/*</code>
will
-yield filespecs like "t/base.dir". (This is done to match
-the behavior of glob expansion performed by Unix shells.)
-</p>
-<p>Similarly, the resultant filespec will contain the file version
-only if one was present in the input filespec.
-</p>
-<hr>
-<a name="perlvms-Pipes"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlvms-Wildcard-expansion" accesskey="p"
rel="prev">perlvms Wildcard expansion</a>, Up: <a
href="#perlvms-File-specifications" accesskey="u" rel="up">perlvms File
specifications</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Pipes"></a>
-<h4 class="subsection">87.5.5 Pipes</h4>
-
-<p>Input and output pipes to Perl filehandles are supported; the
-"file name" is passed to lib$spawn() for asynchronous
-execution. You should be careful to close any pipes you have
-opened in a Perl script, lest you leave any "orphaned"
-subprocesses around when Perl exits.
-</p>
-<p>You may also use backticks to invoke a DCL subprocess, whose
-output is used as the return value of the expression. The
-string between the backticks is handled as if it were the
-argument to the <code>system</code> operator (see below). In this case,
-Perl will wait for the subprocess to complete before continuing.
-</p>
-<p>The mailbox (MBX) that perl can create to communicate with a pipe
-defaults to a buffer size of 8192 on 64-bit systems, 512 on VAX. The
-default buffer size is adjustable via the logical name PERL_MBX_SIZE
-provided that the value falls between 128 and the SYSGEN parameter
-MAXBUF inclusive. For example, to set the mailbox size to 32767 use
-<code>$ENV{'PERL_MBX_SIZE'} = 32767;</code> and then open and use pipe
constructs.
-An alternative would be to issue the command:
-</p>
-<pre class="verbatim"> $ Define PERL_MBX_SIZE 32767
-</pre>
-<p>before running your wide record pipe program. A larger value may
-improve performance at the expense of the BYTLM UAF quota.
-</p>
-<hr>
-<a name="perlvms-PERL5LIB-and-PERLLIB"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-The-Perl-Forked-Debugger" accesskey="n"
rel="next">perlvms The Perl Forked Debugger</a>, Previous: <a
href="#perlvms-File-specifications" accesskey="p" rel="prev">perlvms File
specifications</a>, Up: <a href="#perlvms" accesskey="u" rel="up">perlvms</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="PERL5LIB-and-PERLLIB"></a>
-<h3 class="section">87.6 PERL5LIB and PERLLIB</h3>
-
-<p>The PERL5LIB and PERLLIB logical names work as documented in <a
href="#perl-NAME">perl NAME</a>,
-except that the element separator is ’|’ instead of
’:’. The
-directory specifications may use either VMS or Unix syntax.
-</p>
-<hr>
-<a name="perlvms-The-Perl-Forked-Debugger"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-PERL_005fVMS_005fEXCEPTION_005fDEBUG" accesskey="n"
rel="next">perlvms PERL_VMS_EXCEPTION_DEBUG</a>, Previous: <a
href="#perlvms-PERL5LIB-and-PERLLIB" accesskey="p" rel="prev">perlvms PERL5LIB
and PERLLIB</a>, Up: <a href="#perlvms" accesskey="u" rel="up">perlvms</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="The-Perl-Forked-Debugger"></a>
-<h3 class="section">87.7 The Perl Forked Debugger</h3>
-
-<p>The Perl forked debugger places the debugger commands and output in a
-separate X-11 terminal window so that commands and output from multiple
-processes are not mixed together.
-</p>
-<p>Perl on VMS supports an emulation of the forked debugger when Perl is
-run on a VMS system that has X11 support installed.
-</p>
-<p>To use the forked debugger, you need to have the default display set to an
-X-11 Server and some environment variables set that Unix expects.
-</p>
-<p>The forked debugger requires the environment variable <code>TERM</code> to
be <code>xterm</code>,
-and the environment variable <code>DISPLAY</code> to exist.
<code>xterm</code> must be in
-lower case.
-</p>
-<pre class="verbatim"> $define TERM "xterm"
-
- $define DISPLAY "hostname:0.0"
-</pre>
-<p>Currently the value of <code>DISPLAY</code> is ignored. It is recommended
that it be set
-to be the hostname of the display, the server and screen in Unix notation. In
-the future the value of DISPLAY may be honored by Perl instead of using the
-default display.
-</p>
-<p>It may be helpful to always use the forked debugger so that script I/O is
-separated from debugger I/O. You can force the debugger to be forked by
-assigning a value to the logical name <PERLDB_PIDS> that is not a process
-identification number.
-</p>
-<pre class="verbatim"> $define PERLDB_PIDS XXXX
-</pre>
-<hr>
-<a name="perlvms-PERL_005fVMS_005fEXCEPTION_005fDEBUG"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Command-line" accesskey="n" rel="next">perlvms Command
line</a>, Previous: <a href="#perlvms-The-Perl-Forked-Debugger" accesskey="p"
rel="prev">perlvms The Perl Forked Debugger</a>, Up: <a href="#perlvms"
accesskey="u" rel="up">perlvms</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="PERL_005fVMS_005fEXCEPTION_005fDEBUG"></a>
-<h3 class="section">87.8 PERL_VMS_EXCEPTION_DEBUG</h3>
-
-<p>The PERL_VMS_EXCEPTION_DEBUG being defined as "ENABLE" will cause
the VMS
-debugger to be invoked if a fatal exception that is not otherwise
-handled is raised. The purpose of this is to allow debugging of
-internal Perl problems that would cause such a condition.
-</p>
-<p>This allows the programmer to look at the execution stack and variables to
-find out the cause of the exception. As the debugger is being invoked as
-the Perl interpreter is about to do a fatal exit, continuing the execution
-in debug mode is usually not practical.
-</p>
-<p>Starting Perl in the VMS debugger may change the program execution
-profile in a way that such problems are not reproduced.
-</p>
-<p>The <code>kill</code> function can be used to test this functionality from
within
-a program.
-</p>
-<p>In typical VMS style, only the first letter of the value of this logical
-name is actually checked in a case insensitive mode, and it is considered
-enabled if it is the value "T","1" or "E".
-</p>
-<p>This logical name must be defined before Perl is started.
-</p>
-<hr>
-<a name="perlvms-Command-line"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Perl-functions" accesskey="n" rel="next">perlvms Perl
functions</a>, Previous: <a
href="#perlvms-PERL_005fVMS_005fEXCEPTION_005fDEBUG" accesskey="p"
rel="prev">perlvms PERL_VMS_EXCEPTION_DEBUG</a>, Up: <a href="#perlvms"
accesskey="u" rel="up">perlvms</a> [<a href="#SEC_Contents" title="Table
of contents" rel="contents">Contents</a>]</p>
-</div>
-<a name="Command-line"></a>
-<h3 class="section">87.9 Command line</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a
href="#perlvms-I_002fO-redirection-and-backgrounding" accesskey="1">perlvms I/O
redirection and backgrounding</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-<tr><td align="left" valign="top">• <a
href="#perlvms-Command-line-switches" accesskey="2">perlvms Command line
switches</a>:</td><td> </td><td align="left" valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlvms-I_002fO-redirection-and-backgrounding"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Command-line-switches" accesskey="n"
rel="next">perlvms Command line switches</a>, Up: <a
href="#perlvms-Command-line" accesskey="u" rel="up">perlvms Command line</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="I_002fO-redirection-and-backgrounding"></a>
-<h4 class="subsection">87.9.1 I/O redirection and backgrounding</h4>
-
-<p>Perl for VMS supports redirection of input and output on the
-command line, using a subset of Bourne shell syntax:
-</p>
-<ul>
-<li> <code><file</code> reads stdin from <code>file</code>,
-
-</li><li> <code>>file</code> writes stdout to <code>file</code>,
-
-</li><li> <code>>>file</code> appends stdout to <code>file</code>,
-
-</li><li> <code>2>file</code> writes stderr to <code>file</code>,
-
-</li><li> <code>2>>file</code> appends stderr to <code>file</code>, and
-
-</li><li> <code>2>&1</code> redirects stderr to stdout.
-
-</li></ul>
-
-<p>In addition, output may be piped to a subprocess, using the
-character ’|’. Anything after this character on the command
-line is passed to a subprocess for execution; the subprocess
-takes the output of Perl as its input.
-</p>
-<p>Finally, if the command line ends with ’&’, the entire
-command is run in the background as an asynchronous
-subprocess.
-</p>
-<hr>
-<a name="perlvms-Command-line-switches"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlvms-I_002fO-redirection-and-backgrounding"
accesskey="p" rel="prev">perlvms I/O redirection and backgrounding</a>, Up: <a
href="#perlvms-Command-line" accesskey="u" rel="up">perlvms Command line</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Command-line-switches"></a>
-<h4 class="subsection">87.9.2 Command line switches</h4>
-
-<p>The following command line switches behave differently under
-VMS than described in <a href="#perlrun-NAME">perlrun NAME</a>. Note also
that in order
-to pass uppercase switches to Perl, you need to enclose
-them in double-quotes on the command line, since the CRTL
-downcases all unquoted strings.
-</p>
-<p>On newer 64 bit versions of OpenVMS, a process setting now
-controls if the quoting is needed to preserve the case of
-command line arguments.
-</p>
-<dl compact="compact">
-<dt>-i</dt>
-<dd><a name="perlvms-_002di"></a>
-<p>If the <code>-i</code> switch is present but no extension for a backup
-copy is given, then inplace editing creates a new version of
-a file; the existing copy is not deleted. (Note that if
-an extension is given, an existing file is renamed to the backup
-file, as is the case under other operating systems, so it does
-not remain as a previous version under the original filename.)
-</p>
-</dd>
-<dt>-S</dt>
-<dd><a name="perlvms-_002dS"></a>
-<p>If the <code>"-S"</code> or <code>-"S"</code> switch is
present <em>and</em> the script
-name does not contain a directory, then Perl translates the
-logical name DCL$PATH as a searchlist, using each translation
-as a directory in which to look for the script. In addition,
-if no file type is specified, Perl looks in each directory
-for a file matching the name specified, with a blank type,
-a type of <samp>.pl</samp>, and a type of <samp>.com</samp>, in that order.
-</p>
-</dd>
-<dt>-u</dt>
-<dd><a name="perlvms-_002du"></a>
-<p>The <code>-u</code> switch causes the VMS debugger to be invoked
-after the Perl program is compiled, but before it has
-run. It does not create a core dump file.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlvms-Perl-functions"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Perl-variables" accesskey="n" rel="next">perlvms Perl
variables</a>, Previous: <a href="#perlvms-Command-line" accesskey="p"
rel="prev">perlvms Command line</a>, Up: <a href="#perlvms" accesskey="u"
rel="up">perlvms</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Perl-functions"></a>
-<h3 class="section">87.10 Perl functions</h3>
-
-<p>As of the time this document was last revised, the following
-Perl functions were implemented in the VMS port of Perl
-(functions marked with * are discussed in more detail below):
-</p>
-<pre class="verbatim"> file tests*, abs, alarm, atan, backticks*, binmode*,
bless,
- caller, chdir, chmod, chown, chomp, chop, chr,
- close, closedir, cos, crypt*, defined, delete, die, do, dump*,
- each, endgrent, endpwent, eof, eval, exec*, exists, exit, exp,
- fileno, flock getc, getgrent*, getgrgid*, getgrnam, getlogin,
- getppid, getpwent*, getpwnam*, getpwuid*, glob, gmtime*, goto,
- grep, hex, ioctl, import, index, int, join, keys, kill*,
- last, lc, lcfirst, lchown*, length, link*, local, localtime, log,
- lstat, m//, map, mkdir, my, next, no, oct, open, opendir, ord,
- pack, pipe, pop, pos, print, printf, push, q//, qq//, qw//,
- qx//*, quotemeta, rand, read, readdir, readlink*, redo, ref,
- rename, require, reset, return, reverse, rewinddir, rindex,
- rmdir, s///, scalar, seek, seekdir, select(internal),
- select (system call)*, setgrent, setpwent, shift, sin, sleep,
- socketpair, sort, splice, split, sprintf, sqrt, srand, stat,
- study, substr, symlink*, sysread, system*, syswrite, tell,
- telldir, tie, time, times*, tr///, uc, ucfirst, umask,
- undef, unlink*, unpack, untie, unshift, use, utime*,
- values, vec, wait, waitpid*, wantarray, warn, write, y///
-</pre>
-<p>The following functions were not implemented in the VMS port,
-and calling them produces a fatal error (usually) or
-undefined behavior (rarely, we hope):
-</p>
-<pre class="verbatim"> chroot, dbmclose, dbmopen, fork*, getpgrp,
getpriority,
- msgctl, msgget, msgsend, msgrcv, semctl,
- semget, semop, setpgrp, setpriority, shmctl, shmget,
- shmread, shmwrite, syscall
-</pre>
-<p>The following functions are available on Perls compiled with Dec C
-5.2 or greater and running VMS 7.0 or greater:
-</p>
-<pre class="verbatim"> truncate
-</pre>
-<p>The following functions are available on Perls built on VMS 7.2 or
-greater:
-</p>
-<pre class="verbatim"> fcntl (without locking)
-</pre>
-<p>The following functions may or may not be implemented,
-depending on what type of socket support you’ve built into
-your copy of Perl:
-</p>
-<pre class="verbatim"> accept, bind, connect, getpeername,
- gethostbyname, getnetbyname, getprotobyname,
- getservbyname, gethostbyaddr, getnetbyaddr,
- getprotobynumber, getservbyport, gethostent,
- getnetent, getprotoent, getservent, sethostent,
- setnetent, setprotoent, setservent, endhostent,
- endnetent, endprotoent, endservent, getsockname,
- getsockopt, listen, recv, select(system call)*,
- send, setsockopt, shutdown, socket
-</pre>
-<p>The following function is available on Perls built on 64 bit OpenVMS v8.2
-with hard links enabled on an ODS-5 formatted build disk. CRTL support
-is in principle available as of OpenVMS v7.3-1, and better configuration
-support could detect this.
-</p>
-<pre class="verbatim"> link
-</pre>
-<p>The following functions are available on Perls built on 64 bit OpenVMS
-v8.2 and later. CRTL support is in principle available as of OpenVMS
-v7.3-2, and better configuration support could detect this.
-</p>
-<pre class="verbatim"> getgrgid, getgrnam, getpwnam, getpwuid,
- setgrent, ttyname
-</pre>
-<p>The following functions are available on Perls built on 64 bit OpenVMS v8.2
-and later.
-</p>
-<pre class="verbatim"> statvfs, socketpair
-</pre>
-<dl compact="compact">
-<dt>File tests</dt>
-<dd><a name="perlvms-File-tests"></a>
-<p>The tests <code>-b</code>, <code>-B</code>, <code>-c</code>,
<code>-C</code>, <code>-d</code>, <code>-e</code>, <code>-f</code>,
-<code>-o</code>, <code>-M</code>, <code>-s</code>, <code>-S</code>,
<code>-t</code>, <code>-T</code>, and <code>-z</code> work as
-advertised. The return values for <code>-r</code>, <code>-w</code>, and
<code>-x</code>
-tell you whether you can actually access the file; this may
-not reflect the UIC-based file protections. Since real and
-effective UIC don’t differ under VMS, <code>-O</code>, <code>-R</code>,
<code>-W</code>,
-and <code>-X</code> are equivalent to <code>-o</code>, <code>-r</code>,
<code>-w</code>, and <code>-x</code>.
-Similarly, several other tests, including <code>-A</code>, <code>-g</code>,
<code>-k</code>,
-<code>-l</code>, <code>-p</code>, and <code>-u</code>, aren’t
particularly meaningful under
-VMS, and the values returned by these tests reflect whatever
-your CRTL <code>stat()</code> routine does to the equivalent bits in the
-st_mode field. Finally, <code>-d</code> returns true if passed a device
-specification without an explicit directory (e.g. <code>DUA1:</code>), as
-well as if passed a directory.
-</p>
-<p>There are DECC feature logical names AND ODS-5 volume attributes that
-also control what values are returned for the date fields.
-</p>
-<p>Note: Some sites have reported problems when using the file-access
-tests (<code>-r</code>, <code>-w</code>, and <code>-x</code>) on files
accessed via DEC’s DFS.
-Specifically, since DFS does not currently provide access to the
-extended file header of files on remote volumes, attempts to
-examine the ACL fail, and the file tests will return false,
-with <code>$!</code> indicating that the file does not exist. You can
-use <code>stat</code> on these files, since that checks UIC-based protection
-only, and then manually check the appropriate bits, as defined by
-your C compiler’s <samp>stat.h</samp>, in the mode value it returns, if
you
-need an approximation of the file’s protections.
-</p>
-</dd>
-<dt>backticks</dt>
-<dd><a name="perlvms-backticks"></a>
-<p>Backticks create a subprocess, and pass the enclosed string
-to it for execution as a DCL command. Since the subprocess is
-created directly via <code>lib$spawn()</code>, any valid DCL command string
-may be specified.
-</p>
-</dd>
-<dt>binmode FILEHANDLE</dt>
-<dd><a name="perlvms-binmode-FILEHANDLE"></a>
-<p>The <code>binmode</code> operator will attempt to insure that no translation
-of carriage control occurs on input from or output to this filehandle.
-Since this involves reopening the file and then restoring its
-file position indicator, if this function returns FALSE, the
-underlying filehandle may no longer point to an open file, or may
-point to a different position in the file than before <code>binmode</code>
-was called.
-</p>
-<p>Note that <code>binmode</code> is generally not necessary when using normal
-filehandles; it is provided so that you can control I/O to existing
-record-structured files when necessary. You can also use the
-<code>vmsfopen</code> function in the VMS::Stdio extension to gain finer
-control of I/O to files and devices with different record structures.
-</p>
-</dd>
-<dt>crypt PLAINTEXT, USER</dt>
-<dd><a name="perlvms-crypt-PLAINTEXT_002c-USER"></a>
-<p>The <code>crypt</code> operator uses the <code>sys$hash_password</code>
system
-service to generate the hashed representation of PLAINTEXT.
-If USER is a valid username, the algorithm and salt values
-are taken from that user’s UAF record. If it is not, then
-the preferred algorithm and a salt of 0 are used. The
-quadword encrypted value is returned as an 8-character string.
-</p>
-<p>The value returned by <code>crypt</code> may be compared against
-the encrypted password from the UAF returned by the <code>getpw*</code>
-functions, in order to authenticate users. If you’re
-going to do this, remember that the encrypted password in
-the UAF was generated using uppercase username and
-password strings; you’ll have to upcase the arguments to
-<code>crypt</code> to insure that you’ll get the proper value:
-</p>
-<pre class="verbatim"> sub validate_passwd {
- my($user,$passwd) = @_;
- my($pwdhash);
- if ( !($pwdhash = (getpwnam($user))[1]) ||
- $pwdhash ne crypt("\U$passwd","\U$name") ) {
- intruder_alert($name);
- }
- return 1;
- }
-</pre>
-</dd>
-<dt>die</dt>
-<dd><a name="perlvms-die"></a>
-<p><code>die</code> will force the native VMS exit status to be an SS$_ABORT
code
-if neither of the $! or $? status values are ones that would cause
-the native status to be interpreted as being what VMS classifies as
-SEVERE_ERROR severity for DCL error handling.
-</p>
-<p>When <code>PERL_VMS_POSIX_EXIT</code> is active (see <a
href="#perlvms-_0024_003f">$?</a> below), the native VMS exit
-status value will have either one of the <code>$!</code> or <code>$?</code> or
<code>$^E</code> or
-the Unix value 255 encoded into it in a way that the effective original
-value can be decoded by other programs written in C, including Perl
-and the GNV package. As per the normal non-VMS behavior of <code>die</code> if
-either <code>$!</code> or <code>$?</code> are non-zero, one of those values
will be
-encoded into a native VMS status value. If both of the Unix status
-values are 0, and the <code>$^E</code> value is set one of ERROR or
SEVERE_ERROR
-severity, then the <code>$^E</code> value will be used as the exit code as is.
-If none of the above apply, the Unix value of 255 will be encoded into
-a native VMS exit status value.
-</p>
-<p>Please note a significant difference in the behavior of <code>die</code> in
-the <code>PERL_VMS_POSIX_EXIT</code> mode is that it does not force a VMS
-SEVERE_ERROR status on exit. The Unix exit values of 2 through
-255 will be encoded in VMS status values with severity levels of
-SUCCESS. The Unix exit value of 1 will be encoded in a VMS status
-value with a severity level of ERROR. This is to be compatible with
-how the VMS C library encodes these values.
-</p>
-<p>The minimum severity level set by <code>die</code> in
<code>PERL_VMS_POSIX_EXIT</code> mode
-may be changed to be ERROR or higher in the future depending on the
-results of testing and further review.
-</p>
-<p>See <a href="#perlvms-_0024_003f">$?</a> for a description of the encoding
of the Unix value to
-produce a native VMS status containing it.
-</p>
-</dd>
-<dt>dump</dt>
-<dd><a name="perlvms-dump"></a>
-<p>Rather than causing Perl to abort and dump core, the <code>dump</code>
-operator invokes the VMS debugger. If you continue to
-execute the Perl program under the debugger, control will
-be transferred to the label specified as the argument to
-<code>dump</code>, or, if no label was specified, back to the
-beginning of the program. All other state of the program
-(<em>e.g.</em> values of variables, open file handles) are not
-affected by calling <code>dump</code>.
-</p>
-</dd>
-<dt>exec LIST</dt>
-<dd><a name="perlvms-exec-LIST"></a>
-<p>A call to <code>exec</code> will cause Perl to exit, and to invoke the
command
-given as an argument to <code>exec</code> via <code>lib$do_command</code>. If
the
-argument begins with ’@’ or ’$’ (other than as part of
a filespec),
-then it is executed as a DCL command. Otherwise, the first token on
-the command line is treated as the filespec of an image to run, and
-an attempt is made to invoke it (using <samp>.Exe</samp> and the process
-defaults to expand the filespec) and pass the rest of <code>exec</code>’s
-argument to it as parameters. If the token has no file type, and
-matches a file with null type, then an attempt is made to determine
-whether the file is an executable image which should be invoked
-using <code>MCR</code> or a text file which should be passed to DCL as a
-command procedure.
-</p>
-</dd>
-<dt>fork</dt>
-<dd><a name="perlvms-fork"></a>
-<p>While in principle the <code>fork</code> operator could be implemented via
-(and with the same rather severe limitations as) the CRTL <code>vfork()</code>
-routine, and while some internal support to do just that is in
-place, the implementation has never been completed, making <code>fork</code>
-currently unavailable. A true kernel <code>fork()</code> is expected in a
-future version of VMS, and the pseudo-fork based on interpreter
-threads may be available in a future version of Perl on VMS (see
-<a href="#perlfork-NAME">perlfork NAME</a>). In the meantime, use
<code>system</code>, backticks, or piped
-filehandles to create subprocesses.
-</p>
-</dd>
-<dt>getpwent</dt>
-<dd><a name="perlvms-getpwent"></a>
-</dd>
-<dt>getpwnam</dt>
-<dd><a name="perlvms-getpwnam"></a>
-</dd>
-<dt>getpwuid</dt>
-<dd><a name="perlvms-getpwuid"></a>
-<p>These operators obtain the information described in <a
href="#perlfunc-NAME">perlfunc NAME</a>,
-if you have the privileges necessary to retrieve the named user’s
-UAF information via <code>sys$getuai</code>. If not, then only the
<code>$name</code>,
-<code>$uid</code>, and <code>$gid</code> items are returned. The
<code>$dir</code> item contains
-the login directory in VMS syntax, while the <code>$comment</code> item
-contains the login directory in Unix syntax. The <code>$gcos</code> item
-contains the owner field from the UAF record. The <code>$quota</code>
-item is not used.
-</p>
-</dd>
-<dt>gmtime</dt>
-<dd><a name="perlvms-gmtime"></a>
-<p>The <code>gmtime</code> operator will function properly if you have a
-working CRTL <code>gmtime()</code> routine, or if the logical name
-SYS$TIMEZONE_DIFFERENTIAL is defined as the number of seconds
-which must be added to UTC to yield local time. (This logical
-name is defined automatically if you are running a version of
-VMS with built-in UTC support.) If neither of these cases is
-true, a warning message is printed, and <code>undef</code> is returned.
-</p>
-</dd>
-<dt>kill</dt>
-<dd><a name="perlvms-kill"></a>
-<p>In most cases, <code>kill</code> is implemented via the undocumented system
-service <code>$SIGPRC</code>, which has the same calling sequence as
<code>$FORCEX</code>, but
-throws an exception in the target process rather than forcing it to call
-<code>$EXIT</code>. Generally speaking, <code>kill</code> follows the
behavior of the
-CRTL’s <code>kill()</code> function, but unlike that function can be
called from
-within a signal handler. Also, unlike the <code>kill</code> in some versions
of
-the CRTL, Perl’s <code>kill</code> checks the validity of the signal
passed in and
-returns an error rather than attempting to send an unrecognized signal.
-</p>
-<p>Also, negative signal values don’t do anything special under
-VMS; they’re just converted to the corresponding positive value.
-</p>
-</dd>
-<dt>qx//</dt>
-<dd><a name="perlvms-qx_002f_002f"></a>
-<p>See the entry on <code>backticks</code> above.
-</p>
-</dd>
-<dt>select (system call)</dt>
-<dd><a name="perlvms-select-_0028system-call_0029"></a>
-<p>If Perl was not built with socket support, the system call
-version of <code>select</code> is not available at all. If socket
-support is present, then the system call version of
-<code>select</code> functions only for file descriptors attached
-to sockets. It will not provide information about regular
-files or pipes, since the CRTL <code>select()</code> routine does not
-provide this functionality.
-</p>
-</dd>
-<dt>stat EXPR</dt>
-<dd><a name="perlvms-stat-EXPR"></a>
-<p>Since VMS keeps track of files according to a different scheme
-than Unix, it’s not really possible to represent the file’s ID
-in the <code>st_dev</code> and <code>st_ino</code> fields of a <code>struct
stat</code>. Perl
-tries its best, though, and the values it uses are pretty unlikely
-to be the same for two different files. We can’t guarantee this,
-though, so caveat scriptor.
-</p>
-</dd>
-<dt>system LIST</dt>
-<dd><a name="perlvms-system-LIST"></a>
-<p>The <code>system</code> operator creates a subprocess, and passes its
-arguments to the subprocess for execution as a DCL command.
-Since the subprocess is created directly via <code>lib$spawn()</code>, any
-valid DCL command string may be specified. If the string begins with
-’@’, it is treated as a DCL command unconditionally. Otherwise, if
-the first token contains a character used as a delimiter in file
-specification (e.g. <code>:</code> or <code>]</code>), an attempt is made to
expand it
-using a default type of <samp>.Exe</samp> and the process defaults, and if
-successful, the resulting file is invoked via <code>MCR</code>. This allows you
-to invoke an image directly simply by passing the file specification
-to <code>system</code>, a common Unixish idiom. If the token has no file type,
-and matches a file with null type, then an attempt is made to
-determine whether the file is an executable image which should be
-invoked using <code>MCR</code> or a text file which should be passed to DCL
-as a command procedure.
-</p>
-<p>If LIST consists of the empty string, <code>system</code> spawns an
-interactive DCL subprocess, in the same fashion as typing
-<strong>SPAWN</strong> at the DCL prompt.
-</p>
-<p>Perl waits for the subprocess to complete before continuing
-execution in the current process. As described in <a
href="#perlfunc-NAME">perlfunc NAME</a>,
-the return value of <code>system</code> is a fake "status" which
follows
-POSIX semantics unless the pragma <code>use vmsish 'status'</code> is in
-effect; see the description of <code>$?</code> in this document for more
-detail.
-</p>
-</dd>
-<dt>time</dt>
-<dd><a name="perlvms-time"></a>
-<p>The value returned by <code>time</code> is the offset in seconds from
-01-JAN-1970 00:00:00 (just like the CRTL’s times() routine), in order
-to make life easier for code coming in from the POSIX/Unix world.
-</p>
-</dd>
-<dt>times</dt>
-<dd><a name="perlvms-times"></a>
-<p>The array returned by the <code>times</code> operator is divided up
-according to the same rules the CRTL <code>times()</code> routine.
-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 <code>times()</code> keeps track of subprocesses separately. Note
-especially that the VAXCRTL (at least) keeps track only of
-subprocesses spawned using <code>fork()</code> and <code>exec()</code>; it
will not
-accumulate the times of subprocesses spawned via pipes, <code>system()</code>,
-or backticks.
-</p>
-</dd>
-<dt>unlink LIST</dt>
-<dd><a name="perlvms-unlink-LIST"></a>
-<p><code>unlink</code> will delete the highest version of a file only; in
-order to delete all versions, you need to say
-</p>
-<pre class="verbatim"> 1 while unlink LIST;
-</pre>
-<p>You may need to make this change to scripts written for a
-Unix system which expect that after a call to <code>unlink</code>,
-no files with the names passed to <code>unlink</code> will exist.
-(Note: This can be changed at compile time; if you
-<code>use Config</code> and <code>$Config{'d_unlink_all_versions'}</code> is
-<code>define</code>, then <code>unlink</code> will delete all versions of a
-file on the first call.)
-</p>
-<p><code>unlink</code> will delete a file if at all possible, even if it
-requires changing file protection (though it won’t try to
-change the protection of the parent directory). You can tell
-whether you’ve got explicit delete access to a file by using the
-<code>VMS::Filespec::candelete</code> operator. For instance, in order
-to delete only files to which you have delete access, you could
-say something like
-</p>
-<pre class="verbatim"> sub safe_unlink {
- my($file,$num);
- foreach $file (@_) {
- next unless VMS::Filespec::candelete($file);
- $num += unlink $file;
- }
- $num;
- }
-</pre>
-<p>(or you could just use <code>VMS::Stdio::remove</code>, if you’ve
installed
-the VMS::Stdio extension distributed with Perl). If <code>unlink</code> has to
-change the file protection to delete the file, and you interrupt it
-in midstream, the file may be left intact, but with a changed ACL
-allowing you delete access.
-</p>
-<p>This behavior of <code>unlink</code> is to be compatible with POSIX behavior
-and not traditional VMS behavior.
-</p>
-</dd>
-<dt>utime LIST</dt>
-<dd><a name="perlvms-utime-LIST"></a>
-<p>This operator changes only the modification time of the file (VMS
-revision date) on ODS-2 volumes and ODS-5 volumes without access
-dates enabled. On ODS-5 volumes with access dates enabled, the
-true access time is modified.
-</p>
-</dd>
-<dt>waitpid PID,FLAGS</dt>
-<dd><a name="perlvms-waitpid-PID_002cFLAGS"></a>
-<p>If PID is a subprocess started by a piped <code>open()</code> (see <a
href="open.html#Top">(open)</a>),
-<code>waitpid</code> will wait for that subprocess, and return its final status
-value in <code>$?</code>. If PID is a subprocess created in some other way
(e.g.
-SPAWNed before Perl was invoked), <code>waitpid</code> will simply check once
per
-second whether the process has completed, and return when it has. (If
-PID specifies a process that isn’t a subprocess of the current process,
-and you invoked Perl with the <code>-w</code> switch, a warning will be
issued.)
-</p>
-<p>Returns PID on success, -1 on error. The FLAGS argument is ignored
-in all cases.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlvms-Perl-variables"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Standard-modules-with-VMS_002dspecific-differences"
accesskey="n" rel="next">perlvms Standard modules with VMS-specific
differences</a>, Previous: <a href="#perlvms-Perl-functions" accesskey="p"
rel="prev">perlvms Perl functions</a>, Up: <a href="#perlvms" accesskey="u"
rel="up">perlvms</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Perl-variables"></a>
-<h3 class="section">87.11 Perl variables</h3>
-
-<p>The following VMS-specific information applies to the indicated
-"special" Perl variables, in addition to the general information
-in <a href="#perlvar-NAME">perlvar NAME</a>. Where there is a conflict, this
information
-takes precedence.
-</p>
-<dl compact="compact">
-<dt>%ENV</dt>
-<dd><a name="perlvms-_0025ENV"></a>
-<p>The operation of the <code>%ENV</code> array depends on the translation
-of the logical name <samp>PERL_ENV_TABLES</samp>. If defined, it should
-be a search list, each element of which specifies a location
-for <code>%ENV</code> elements. If you tell Perl to read or set the
-element <code>$ENV{</code><em>name</em><code>}</code>, then Perl uses the
translations of
-<samp>PERL_ENV_TABLES</samp> as follows:
-</p>
-<dl compact="compact">
-<dt>CRTL_ENV</dt>
-<dd><a name="perlvms-CRTL_005fENV"></a>
-<p>This string tells Perl to consult the CRTL’s internal
<code>environ</code> array
-of key-value pairs, using <em>name</em> as the key. In most cases, this
-contains only a few keys, but if Perl was invoked via the C
-<code>exec[lv]e()</code> function, as is the case for some embedded Perl
-applications or when running under a shell such as GNV bash, the
-<code>environ</code> array may have been populated by the calling program.
-</p>
-</dd>
-<dt>CLISYM_[LOCAL]</dt>
-<dd><a name="perlvms-CLISYM_005f_005bLOCAL_005d"></a>
-<p>A string beginning with <code>CLISYM_</code>tells Perl to consult the
CLI’s
-symbol tables, using <em>name</em> as the name of the symbol. When reading
-an element of <code>%ENV</code>, the local symbol table is scanned first,
followed
-by the global symbol table.. The characters following <code>CLISYM_</code> are
-significant when an element of <code>%ENV</code> is set or deleted: if the
-complete string is <code>CLISYM_LOCAL</code>, the change is made in the local
-symbol table; otherwise the global symbol table is changed.
-</p>
-</dd>
-<dt>Any other string</dt>
-<dd><a name="perlvms-Any-other-string"></a>
-<p>If an element of <samp>PERL_ENV_TABLES</samp> translates to any other
string,
-that string is used as the name of a logical name table, which is
-consulted using <em>name</em> as the logical name. The normal search
-order of access modes is used.
-</p>
-</dd>
-</dl>
-
-<p><samp>PERL_ENV_TABLES</samp> is translated once when Perl starts up; any
changes
-you make while Perl is running do not affect the behavior of <code>%ENV</code>.
-If <samp>PERL_ENV_TABLES</samp> is not defined, then Perl defaults to
consulting
-first the logical name tables specified by <samp>LNM$FILE_DEV</samp>, and then
-the CRTL <code>environ</code> array. This default order is reversed when the
-logical name <samp>GNV$UNIX_SHELL</samp> is defined, such as when running under
-GNV bash.
-</p>
-<p>In all operations on %ENV, the key string is treated as if it
-were entirely uppercase, regardless of the case actually
-specified in the Perl expression.
-</p>
-<p>When an element of <code>%ENV</code> is read, the locations to which
-<samp>PERL_ENV_TABLES</samp> points are checked in order, and the value
-obtained from the first successful lookup is returned. If the
-name of the <code>%ENV</code> element contains a semi-colon, it and
-any characters after it are removed. These are ignored when
-the CRTL <code>environ</code> array or a CLI symbol table is consulted.
-However, the name is looked up in a logical name table, the
-suffix after the semi-colon is treated as the translation index
-to be used for the lookup. This lets you look up successive values
-for search list logical names. For instance, if you say
-</p>
-<pre class="verbatim"> $ Define STORY once,upon,a,time,there,was
- $ perl -e "for ($i = 0; $i <= 6; $i++) " -
- _$ -e "{ print $ENV{'story;'.$i},' '}"
-</pre>
-<p>Perl will print <code>ONCE UPON A TIME THERE WAS</code>, assuming, of
course,
-that <samp>PERL_ENV_TABLES</samp> is set up so that the logical name
<code>story</code>
-is found, rather than a CLI symbol or CRTL <code>environ</code> element with
-the same name.
-</p>
-<p>When an element of <code>%ENV</code> is set to a defined string, the
-corresponding definition is made in the location to which the
-first translation of <samp>PERL_ENV_TABLES</samp> points. If this causes a
-logical name to be created, it is defined in supervisor mode.
-(The same is done if an existing logical name was defined in
-executive or kernel mode; an existing user or supervisor mode
-logical name is reset to the new value.) If the value is an empty
-string, the logical name’s translation is defined as a single
<code>NUL</code>
-(ASCII <code>\0</code>) character, since a logical name cannot translate to a
-zero-length string. (This restriction does not apply to CLI symbols
-or CRTL <code>environ</code> values; they are set to the empty string.)
-</p>
-<p>When an element of <code>%ENV</code> is set to <code>undef</code>, the
element is looked
-up as if it were being read, and if it is found, it is deleted. (An
-item "deleted" from the CRTL <code>environ</code> array is set to
the empty
-string.) Using <code>delete</code> to remove an element from
<code>%ENV</code> has a
-similar effect, but after the element is deleted, another attempt is
-made to look up the element, so an inner-mode logical name or a name
-in another location will replace the logical name just deleted. In
-either case, only the first value found searching PERL_ENV_TABLES is
-altered. It is not possible at present to define a search list
-logical name via %ENV.
-</p>
-<p>The element <code>$ENV{DEFAULT}</code> is special: when read, it returns
-Perl’s current default device and directory, and when set, it
-resets them, regardless of the definition of <samp>PERL_ENV_TABLES</samp>.
-It cannot be cleared or deleted; attempts to do so are silently
-ignored.
-</p>
-<p>Note that if you want to pass on any elements of the
-C-local environ array to a subprocess which isn’t
-started by fork/exec, or isn’t running a C program, you
-can "promote" them to logical names in the current
-process, which will then be inherited by all subprocesses,
-by saying
-</p>
-<pre class="verbatim"> foreach my $key (qw[C-local keys you want promoted])
{
- my $temp = $ENV{$key}; # read from C-local array
- $ENV{$key} = $temp; # and define as logical name
- }
-</pre>
-<p>(You can’t just say <code>$ENV{$key} = $ENV{$key}</code>, since the
-Perl optimizer is smart enough to elide the expression.)
-</p>
-<p>Don’t try to clear <code>%ENV</code> by saying <code>%ENV =
();</code>, it will throw
-a fatal error. This is equivalent to doing the following from DCL:
-</p>
-<pre class="verbatim"> DELETE/LOGICAL *
-</pre>
-<p>You can imagine how bad things would be if, for example, the SYS$MANAGER
-or SYS$SYSTEM logical names were deleted.
-</p>
-<p>At present, the first time you iterate over %ENV using
-<code>keys</code>, or <code>values</code>, you will incur a time penalty as
all
-logical names are read, in order to fully populate %ENV.
-Subsequent iterations will not reread logical names, so they
-won’t be as slow, but they also won’t reflect any changes
-to logical name tables caused by other programs.
-</p>
-<p>You do need to be careful with the logical names representing
-process-permanent files, such as <code>SYS$INPUT</code> and
<code>SYS$OUTPUT</code>.
-The translations for these logical names are prepended with a
-two-byte binary value (0x1B 0x00) that needs to be stripped off
-if you want to use it. (In previous versions of Perl it wasn’t
-possible to get the values of these logical names, as the null
-byte acted as an end-of-string marker)
-</p>
-</dd>
-<dt>$!</dt>
-<dd><a name="perlvms-_0024_0021"></a>
-<p>The string value of <code>$!</code> is that returned by the CRTL’s
-strerror() function, so it will include the VMS message for
-VMS-specific errors. The numeric value of <code>$!</code> is the
-value of <code>errno</code>, except if errno is EVMSERR, in which
-case <code>$!</code> contains the value of vaxc$errno. Setting <code>$!</code>
-always sets errno to the value specified. If this value is
-EVMSERR, it also sets vaxc$errno to 4 (NONAME-F-NOMSG), so
-that the string value of <code>$!</code> won’t reflect the VMS error
-message from before <code>$!</code> was set.
-</p>
-</dd>
-<dt>$^E</dt>
-<dd><a name="perlvms-_0024_005eE"></a>
-<p>This variable provides direct access to VMS status values
-in vaxc$errno, which are often more specific than the
-generic Unix-style error messages in <code>$!</code>. Its numeric value
-is the value of vaxc$errno, and its string value is the
-corresponding VMS message string, as retrieved by sys$getmsg().
-Setting <code>$^E</code> sets vaxc$errno to the value specified.
-</p>
-<p>While Perl attempts to keep the vaxc$errno value to be current, if
-errno is not EVMSERR, it may not be from the current operation.
-</p>
-</dd>
-<dt>$?</dt>
-<dd><a name="perlvms-_0024_003f"></a>
-<p>The "status value" returned in <code>$?</code> is synthesized
from the
-actual exit status of the subprocess in a way that approximates
-POSIX wait(5) semantics, in order to allow Perl programs to
-portably test for successful completion of subprocesses. The
-low order 8 bits of <code>$?</code> are always 0 under VMS, since the
-termination status of a process may or may not have been
-generated by an exception.
-</p>
-<p>The next 8 bits contain the termination status of the program.
-</p>
-<p>If the child process follows the convention of C programs
-compiled with the _POSIX_EXIT macro set, the status value will
-contain the actual value of 0 to 255 returned by that program
-on a normal exit.
-</p>
-<p>With the _POSIX_EXIT macro set, the Unix exit value of zero is
-represented as a VMS native status of 1, and the Unix values
-from 2 to 255 are encoded by the equation:
-</p>
-<pre class="verbatim"> VMS_status = 0x35a000 + (unix_value * 8) + 1.
-</pre>
-<p>And in the special case of Unix value 1 the encoding is:
-</p>
-<pre class="verbatim"> VMS_status = 0x35a000 + 8 + 2 + 0x10000000.
-</pre>
-<p>For other termination statuses, the severity portion of the
-subprocess’s exit status is used: if the severity was success or
-informational, these bits are all 0; if the severity was
-warning, they contain a value of 1; if the severity was
-error or fatal error, they contain the actual severity bits,
-which turns out to be a value of 2 for error and 4 for severe_error.
-Fatal is another term for the severe_error status.
-</p>
-<p>As a result, <code>$?</code> will always be zero if the subprocess’s
exit
-status indicated successful completion, and non-zero if a
-warning or error occurred or a program compliant with encoding
-_POSIX_EXIT values was run and set a status.
-</p>
-<p>How can you tell the difference between a non-zero status that is
-the result of a VMS native error status or an encoded Unix status?
-You can not unless you look at the ${^CHILD_ERROR_NATIVE} value.
-The ${^CHILD_ERROR_NATIVE} value returns the actual VMS status value
-and check the severity bits. If the severity bits are equal to 1,
-then if the numeric value for <code>$?</code> is between 2 and 255 or 0, then
-<code>$?</code> accurately reflects a value passed back from a Unix
application.
-If <code>$?</code> is 1, and the severity bits indicate a VMS error (2), then
-<code>$?</code> is from a Unix application exit value.
-</p>
-<p>In practice, Perl scripts that call programs that return _POSIX_EXIT
-type status values will be expecting those values, and programs that
-call traditional VMS programs will either be expecting the previous
-behavior or just checking for a non-zero status.
-</p>
-<p>And success is always the value 0 in all behaviors.
-</p>
-<p>When the actual VMS termination status of the child is an error,
-internally the <code>$!</code> value will be set to the closest Unix errno
-value to that error so that Perl scripts that test for error
-messages will see the expected Unix style error message instead
-of a VMS message.
-</p>
-<p>Conversely, when setting <code>$?</code> in an END block, an attempt is made
-to convert the POSIX value into a native status intelligible to
-the operating system upon exiting Perl. What this boils down to
-is that setting <code>$?</code> to zero results in the generic success value
-SS$_NORMAL, and setting <code>$?</code> to a non-zero value results in the
-generic failure status SS$_ABORT. See also <a href="#perlport-exit">perlport
exit</a>.
-</p>
-<p>With the <code>PERL_VMS_POSIX_EXIT</code> logical name defined as
"ENABLE",
-setting <code>$?</code> will cause the new value to be encoded into
<code>$^E</code>
-so that either the original parent or child exit status values
- 0 to 255 can be automatically recovered by C programs expecting
-_POSIX_EXIT behavior. If both a parent and a child exit value are
-non-zero, then it will be assumed that this is actually a VMS native
-status value to be passed through. The special value of 0xFFFF is
-almost a NOOP as it will cause the current native VMS status in the
-C library to become the current native Perl VMS status, and is handled
-this way as it is known to not be a valid native VMS status value.
-It is recommend that only values in the range of normal Unix parent or
-child status numbers, 0 to 255 are used.
-</p>
-<p>The pragma <code>use vmsish 'status'</code> makes <code>$?</code> reflect
the actual
-VMS exit status instead of the default emulation of POSIX status
-described above. This pragma also disables the conversion of
-non-zero values to SS$_ABORT when setting <code>$?</code> in an END
-block (but zero will still be converted to SS$_NORMAL).
-</p>
-<p>Do not use the pragma <code>use vmsish 'status'</code> with
<code>PERL_VMS_POSIX_EXIT</code>
-enabled, as they are at times requesting conflicting actions and the
-consequence of ignoring this advice will be undefined to allow future
-improvements in the POSIX exit handling.
-</p>
-<p>In general, with <code>PERL_VMS_POSIX_EXIT</code> enabled, more detailed
information
-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.
-</p>
-<p>N.B. Setting <code>DECC$FILENAME_UNIX_REPORT</code> implicitly enables
-<code>PERL_VMS_POSIX_EXIT</code>.
-</p>
-</dd>
-<dt>$|</dt>
-<dd><a name="perlvms-_0024_007c"></a>
-<p>Setting <code>$|</code> for an I/O stream causes data to be flushed
-all the way to disk on each write (<em>i.e.</em> not just to
-the underlying RMS buffers for a file). In other words,
-it’s equivalent to calling fflush() and fsync() from C.
-</p>
-</dd>
-</dl>
-
-<hr>
-<a name="perlvms-Standard-modules-with-VMS_002dspecific-differences"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-Revision-date" accesskey="n" rel="next">perlvms
Revision date</a>, Previous: <a href="#perlvms-Perl-variables" accesskey="p"
rel="prev">perlvms Perl variables</a>, Up: <a href="#perlvms" accesskey="u"
rel="up">perlvms</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Standard-modules-with-VMS_002dspecific-differences"></a>
-<h3 class="section">87.12 Standard modules with VMS-specific differences</h3>
-
-<table class="menu" border="0" cellspacing="0">
-<tr><td align="left" valign="top">• <a href="#perlvms-SDBM_005fFile"
accesskey="1">perlvms SDBM_File</a>:</td><td> </td><td align="left"
valign="top">
-</td></tr>
-</table>
-
-<hr>
-<a name="perlvms-SDBM_005fFile"></a>
-<div class="header">
-<p>
-Up: <a href="#perlvms-Standard-modules-with-VMS_002dspecific-differences"
accesskey="u" rel="up">perlvms Standard modules with VMS-specific
differences</a> [<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="SDBM_005fFile"></a>
-<h4 class="subsection">87.12.1 SDBM_File</h4>
-
-<p>SDBM_File works properly on VMS. It has, however, one minor
-difference. The database directory file created has a <samp>.sdbm_dir</samp>
-extension rather than a <samp>.dir</samp> extension. <samp>.dir</samp> files
are VMS filesystem
-directory files, and using them for other purposes could cause unacceptable
-problems.
-</p>
-<hr>
-<a name="perlvms-Revision-date"></a>
-<div class="header">
-<p>
-Next: <a href="#perlvms-AUTHOR" accesskey="n" rel="next">perlvms AUTHOR</a>,
Previous: <a href="#perlvms-Standard-modules-with-VMS_002dspecific-differences"
accesskey="p" rel="prev">perlvms Standard modules with VMS-specific
differences</a>, Up: <a href="#perlvms" accesskey="u" rel="up">perlvms</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="Revision-date"></a>
-<h3 class="section">87.13 Revision date</h3>
-
-<p>Please see the git repository for revision history.
-</p>
-<hr>
-<a name="perlvms-AUTHOR"></a>
-<div class="header">
-<p>
-Previous: <a href="#perlvms-Revision-date" accesskey="p" rel="prev">perlvms
Revision date</a>, Up: <a href="#perlvms" accesskey="u" rel="up">perlvms</a>
[<a href="#SEC_Contents" title="Table of contents"
rel="contents">Contents</a>]</p>
-</div>
-<a name="AUTHOR-31"></a>
-<h3 class="section">87.14 AUTHOR</h3>
-
-<p>Charles Bailey address@hidden
-Craig Berry address@hidden
-Dan Sugalski address@hidden
-John Malmberg address@hidden
-</p>
-
-<hr>
-
-
-
-</body>
-</html>
Index: manual/perldoc-all.html.gz
===================================================================
RCS file: manual/perldoc-all.html.gz
diff -N manual/perldoc-all.html.gz
Binary files /tmp/cvscTYpOM and /dev/null differ
Index: manual/perldoc-all.html_chapter.tar.gz
===================================================================
RCS file: manual/perldoc-all.html_chapter.tar.gz
diff -N manual/perldoc-all.html_chapter.tar.gz
Binary files /tmp/cvsjJxLEP and /dev/null differ
Index: manual/perldoc-all.info.tar.gz
===================================================================
RCS file: manual/perldoc-all.info.tar.gz
diff -N manual/perldoc-all.info.tar.gz
Binary files /tmp/cvs0sMwoQ and /dev/null differ
Index: manual/perldoc-all.pdf
===================================================================
RCS file: manual/perldoc-all.pdf
diff -N manual/perldoc-all.pdf
Binary files /tmp/cvsfuc5MS and /dev/null differ
Index: manual/perldoc-all.texi.tar.gz
===================================================================
RCS file: manual/perldoc-all.texi.tar.gz
diff -N manual/perldoc-all.texi.tar.gz
Binary files /tmp/cvsB6ijx1 and /dev/null differ
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- www/software/perl perl.html manual/index.html m...,
karl <=