diff options
Diffstat (limited to 'contrib/perl5/pod')
69 files changed, 16534 insertions, 7210 deletions
diff --git a/contrib/perl5/pod/perl.pod b/contrib/perl5/pod/perl.pod index 59ca0e0368dc..b7e88fb24202 100644 --- a/contrib/perl5/pod/perl.pod +++ b/contrib/perl5/pod/perl.pod @@ -12,83 +12,114 @@ B<perl> S<[ B<-sTuU> ]> S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]> S<[ B<-i>[I<extension>] ]> S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...> -For ease of access, the Perl manual has been split up into several -sections: +For ease of access, the Perl manual has been split up into several sections: perl Perl overview (this section) - perldelta Perl changes since previous version - perl5005delta Perl changes in version 5.005 - perl5004delta Perl changes in version 5.004 perlfaq Perl frequently asked questions perltoc Perl documentation table of contents + perlbook Perl book information - perldata Perl data structures perlsyn Perl syntax + perldata Perl data structures perlop Perl operators and precedence - perlre Perl regular expressions - perlrun Perl execution and options - perlfunc Perl builtin functions - perlopentut Perl open() tutorial - perlvar Perl predefined variables perlsub Perl subroutines - perlmod Perl modules: how they work - perlmodlib Perl modules: how to write and use - perlmodinstall Perl modules: how to install from CPAN - perlform Perl formats - perlunicode Perl unicode support - perllocale Perl locale support - + perlfunc Perl builtin functions perlreftut Perl references short introduction - perlref Perl references, the rest of the story perldsc Perl data structures intro + perlrequick Perl regular expressions quick start + perlpod Perl plain old documentation + perlstyle Perl style guide + perltrap Perl traps for the unwary + + perlrun Perl execution and options + perldiag Perl diagnostic messages + perllexwarn Perl warnings and their control + perldebtut Perl debugging tutorial + perldebug Perl debugging + + perlvar Perl predefined variables perllol Perl data structures: arrays of arrays + perlopentut Perl open() tutorial + perlretut Perl regular expressions tutorial + + perlre Perl regular expressions, the rest of the story + perlref Perl references, the rest of the story + + perlform Perl formats + perlboot Perl OO tutorial for beginners perltoot Perl OO tutorial, part 1 perltootc Perl OO tutorial, part 2 perlobj Perl objects - perltie Perl objects hidden behind simple variables perlbot Perl OO tricks and examples + perltie Perl objects hidden behind simple variables + perlipc Perl interprocess communication perlfork Perl fork() information + perlnumber Perl number semantics perlthrtut Perl threads tutorial - perllexwarn Perl warnings and their control - perlfilter Perl source filters - perldbmfilter Perl DBM filters - perlcompile Perl compiler suite intro - perldebug Perl debugging - perldiag Perl diagnostic messages - perlnumber Perl number semantics - perlsec Perl security - perltrap Perl traps for the unwary perlport Perl portability guide - perlstyle Perl style guide + perllocale Perl locale support + perlunicode Perl unicode support + perlebcdic Considerations for running Perl on EBCDIC platforms - perlpod Perl plain old documentation - perlbook Perl book information + perlsec Perl security + + perlmod Perl modules: how they work + perlmodlib Perl modules: how to write and use + perlmodinstall Perl modules: how to install from CPAN + perlnewmod Perl modules: preparing a new module for distribution + + 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 + + perlcompile Perl compiler suite intro perlembed Perl ways to embed perl in your C or C++ application - perlapio Perl internal IO abstraction interface perldebguts Perl debugging guts and tips - perlxs Perl XS application programming interface perlxstut Perl XS tutorial + perlxs Perl XS application programming interface + perlclib Internal replacements for standard C library functions perlguts Perl internal functions for those doing extensions perlcall Perl calling conventions from C + perlutil utilities packaged with the Perl distribution + perlfilter Perl source filters + perldbmfilter Perl DBM filters perlapi Perl API listing (autogenerated) perlintern Perl internal functions (autogenerated) - + perlapio Perl internal IO abstraction interface perltodo Perl things to do perlhack Perl hackers guide + perlhist Perl history records + perldelta Perl changes since previous version + perl5005delta Perl changes in version 5.005 + perl5004delta Perl changes in version 5.004 + perlaix Perl notes for AIX perlamiga Perl notes for Amiga + perlbs2000 Perl notes for POSIX-BC BS2000 perlcygwin Perl notes for Cygwin perldos Perl notes for DOS + perlepoc Perl notes for EPOC perlhpux Perl notes for HP-UX perlmachten Perl notes for Power MachTen + perlmacos Perl notes for Mac OS (Classic) + perlmpeix Perl notes for MPE/iX perlos2 Perl notes for OS/2 perlos390 Perl notes for OS/390 + perlsolaris Perl notes for Solaris + perlvmesa Perl notes for VM/ESA perlvms Perl notes for VMS + perlvos Perl notes for Stratus VOS perlwin32 Perl notes for Windows (If you're intending to read these straight through for the first time, @@ -162,58 +193,85 @@ But wait, there's more... Begun in 1993 (see L<perlhist>), Perl version 5 is nearly a complete rewrite that provides the following additional benefits: -=over +=over 4 + +=item * -=item * modularity and reusability using innumerable modules +modularity and reusability using innumerable modules Described in L<perlmod>, L<perlmodlib>, and L<perlmodinstall>. -=item * embeddable and extensible +=item * + +embeddable and extensible Described in L<perlembed>, L<perlxstut>, L<perlxs>, L<perlcall>, L<perlguts>, and L<xsubpp>. -=item * roll-your-own magic variables (including multiple simultaneous DBM implementations) +=item * + +roll-your-own magic variables (including multiple simultaneous DBM implementations) Described in L<perltie> and L<AnyDBM_File>. -=item * subroutines can now be overridden, autoloaded, and prototyped +=item * + +subroutines can now be overridden, autoloaded, and prototyped Described in L<perlsub>. -=item * arbitrarily nested data structures and anonymous functions +=item * + +arbitrarily nested data structures and anonymous functions Described in L<perlreftut>, L<perlref>, L<perldsc>, and L<perllol>. -=item * object-oriented programming +=item * + +object-oriented programming Described in L<perlobj>, L<perltoot>, and L<perlbot>. -=item * compilability into C code or Perl bytecode +=item * + +compilability into C code or Perl bytecode Described in L<B> and L<B::Bytecode>. -=item * support for light-weight processes (threads) +=item * + +support for light-weight processes (threads) Described in L<perlthrtut> and L<Thread>. -=item * support for internationalization, localization, and Unicode +=item * + +support for internationalization, localization, and Unicode Described in L<perllocale> and L<utf8>. -=item * lexical scoping +=item * + +lexical scoping Described in L<perlsub>. -=item * regular expression enhancements +=item * + +regular expression enhancements Described in L<perlre>, with additional examples in L<perlop>. -=item * enhanced debugger and interactive Perl environment, with integrated editor support +=item * + +enhanced debugger and interactive Perl environment, +with integrated editor support Described in L<perldebug>. -=item * POSIX 1003.1 compliant library +=item * + +POSIX 1003.1 compliant library Described in L<POSIX>. @@ -293,7 +351,7 @@ affected by wraparound). You may mail your bug reports (be sure to include full configuration information as output by the myconfig program in the perl source -tree, or by C<perl -V>) to perlbug@perl.com . If you've succeeded +tree, or by C<perl -V>) to perlbug@perl.org . If you've succeeded in compiling perl, the B<perlbug> script in the F<utils/> subdirectory can be used to help mail in a bug report. diff --git a/contrib/perl5/pod/perl5004delta.pod b/contrib/perl5/pod/perl5004delta.pod index 85a8f96161be..429cba93ced7 100644 --- a/contrib/perl5/pod/perl5004delta.pod +++ b/contrib/perl5/pod/perl5004delta.pod @@ -24,7 +24,10 @@ problems. See the F<Changes> file in the distribution for details. C<%ENV = ()> and C<%ENV = @list> now work as expected (except on VMS where it generates a fatal error). -=head2 "Can't locate Foo.pm in @INC" error now lists @INC +=head2 Change to "Can't locate Foo.pm in @INC" error + +The error "Can't locate Foo.pm in @INC" now lists the contents of @INC +for easier debugging. =head2 Compilation option: Binary compatibility with 5.003 @@ -198,7 +201,7 @@ hole was just plugged. The new restrictions when tainting include: -=over +=over 4 =item No glob() or <*> @@ -258,7 +261,7 @@ the F<INSTALL> file for how to use it. =head2 New and changed syntax -=over +=over 4 =item $coderef->(PARAMS) @@ -276,7 +279,7 @@ S<C<< $table->{FOO}->($bar) >>>. =head2 New and changed builtin constants -=over +=over 4 =item __PACKAGE__ @@ -289,7 +292,7 @@ into strings. =head2 New and changed builtin variables -=over +=over 4 =item $^E @@ -322,7 +325,7 @@ there is no C<use English> long name for this variable. =head2 New and changed builtin functions -=over +=over 4 =item delete on slices @@ -544,7 +547,7 @@ subroutine: The C<UNIVERSAL> package automatically contains the following methods that are inherited by all other classes: -=over +=over 4 =item isa(CLASS) @@ -593,7 +596,7 @@ have C<isa> available as a plain subroutine in the current package. See L<perltie> for other kinds of tie()s. -=over +=over 4 =item TIEHANDLE classname, LIST @@ -687,7 +690,7 @@ install the optional module Devel::Peek.) Three new compilation flags are recognized by malloc.c. (They have no effect if perl is compiled with system malloc().) -=over +=over 4 =item -DPERL_EMERGENCY_SBRK @@ -779,7 +782,7 @@ See F<README.amigaos> in the perl distribution. Six new pragmatic modules exist: -=over +=over 4 =item use autouse MODULE => qw(sub1 sub2 sub3) @@ -810,7 +813,7 @@ builtin operations. When C<use locale> is in effect, the current LC_CTYPE locale is used for regular expressions and case mapping; LC_COLLATE for string -ordering; and LC_NUMERIC for numeric formating in printf and sprintf +ordering; and LC_NUMERIC for numeric formatting in printf and sprintf (but B<not> in print). LC_NUMERIC is always used in write, since lexical scoping of formats is problematic at best. @@ -979,7 +982,7 @@ those who need trigonometric functions only for real numbers. There have been quite a few changes made to DB_File. Here are a few of the highlights: -=over +=over 4 =item * @@ -1045,7 +1048,7 @@ For example, you can now say =head2 pod2html -=over +=over 4 =item Sends converted HTML to standard output @@ -1058,7 +1061,7 @@ Use the B<--outfile=FILENAME> option to write to a file. =head2 xsubpp -=over +=over 4 =item C<void> XSUBs now default to returning nothing @@ -1083,7 +1086,7 @@ XSUB's return type is really C<SV *>. =head1 C Language API Changes -=over +=over 4 =item C<gv_fetchmethod> and C<perl_call_sv> @@ -1124,7 +1127,7 @@ which can be more efficient. See L<perlguts> for details. Many of the base and library pods were updated. These new pods are included in section 1: -=over +=over 4 =item L<perldelta> @@ -1177,7 +1180,7 @@ increasing order of desperation): (X) A very fatal error (nontrappable). (A) An alien error message (not generated by Perl). -=over +=over 4 =item "my" variable %s masks earlier declaration in same scope @@ -1429,7 +1432,7 @@ assigning to it and when evaluating its argument, while C<@foo{&bar}> 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. -=item Stub found while resolving method `%s' overloading `%s' in package `%s' +=item Stub found while resolving method `%s' overloading `%s' in %s (P) Overloading resolution over @ISA tree may be broken by importing stubs. Stubs should never be implicitly created, but explicit calls to C<can> diff --git a/contrib/perl5/pod/perl5005delta.pod b/contrib/perl5/pod/perl5005delta.pod index b133c0dd813d..78bf90f616b9 100644 --- a/contrib/perl5/pod/perl5005delta.pod +++ b/contrib/perl5/pod/perl5005delta.pod @@ -63,11 +63,15 @@ the new features in this release. =over 4 -=item Core sources now require ANSI C compiler +=item * + +Core sources now require ANSI C compiler An ANSI C compiler is now B<required> to build perl. See F<INSTALL>. -=item All Perl global variables must now be referenced with an explicit prefix +=item * + +All Perl global variables must now be referenced with an explicit prefix All Perl global variables that are visible for use by extensions now have a C<PL_> prefix. New extensions should C<not> refer to perl globals @@ -87,7 +91,9 @@ support may cease in a future release. See L<perlguts/"API LISTING">. -=item Enabling threads has source compatibility issues +=item * + +Enabling threads has source compatibility issues Perl built with threading enabled requires extensions to use the new C<dTHR> macro to initialize the handle to access per-thread data. @@ -525,7 +531,7 @@ The hints files for most Unix platforms have seen incremental improvements. =head2 New Modules -=over +=over 4 =item B @@ -596,13 +602,15 @@ Various pragmata to control behavior of regular expressions. =head2 Changes in existing modules -=over +=over 4 =item Benchmark You can now run tests for I<x> seconds instead of guessing the right number of tests to run. +Keeps better time. + =item Carp Carp has a new function cluck(). cluck() warns, like carp(), but also adds @@ -660,10 +668,6 @@ See <perlmodinstall> and L<CPAN>. Cwd::cwd is faster on most platforms. -=item Benchmark - -Keeps better time. - =back =head1 Utility Changes @@ -702,7 +706,7 @@ L<perlthrtut> gives a tutorial on threads. =head1 New Diagnostics -=over +=over 4 =item Ambiguous call resolved as CORE::%s(), qualify as such or use & @@ -859,7 +863,7 @@ 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. -=item Recursive inheritance detected while looking for method '%s' in package '%s' +=item Recursive inheritance detected while looking for method '%s' %s (F) More than 100 levels of inheritance were encountered while invoking a method. Probably indicates an unintended loop in your inheritance hierarchy. @@ -916,7 +920,7 @@ fix the problem can be found in L<perllocale/"LOCALE PROBLEMS">. =head1 Obsolete Diagnostics -=over +=over 4 =item Can't mktemp() diff --git a/contrib/perl5/pod/perlapi.pod b/contrib/perl5/pod/perlapi.pod index e0ae4cfb5814..67009d0fad48 100644 --- a/contrib/perl5/pod/perlapi.pod +++ b/contrib/perl5/pod/perlapi.pod @@ -25,6 +25,9 @@ Same as C<av_len()>. Deprecated, use C<av_len()> instead. int AvFILL(AV* av) +=for hackers +Found in file av.h + =item av_clear Clears an array, making it empty. Does not free the memory used by the @@ -32,6 +35,31 @@ array itself. void av_clear(AV* ar) +=for hackers +Found in file av.c + +=item av_delete + +Deletes the element indexed by C<key> from the array. Returns the +deleted element. C<flags> is currently ignored. + + SV* av_delete(AV* ar, I32 key, I32 flags) + +=for hackers +Found in file av.c + +=item av_exists + +Returns true if the element indexed by C<key> has been initialized. + +This relies on the fact that uninitialized array elements are set to +C<&PL_sv_undef>. + + bool av_exists(AV* ar, I32 key) + +=for hackers +Found in file av.c + =item av_extend Pre-extend an array. The C<key> is the index to which the array should be @@ -39,6 +67,9 @@ extended. void av_extend(AV* ar, I32 key) +=for hackers +Found in file av.c + =item av_fetch Returns the SV at the specified index in the array. The C<key> is the @@ -50,6 +81,19 @@ more information on how to use this function on tied arrays. SV** av_fetch(AV* ar, I32 key, I32 lval) +=for hackers +Found in file av.c + +=item av_fill + +Ensure than an array has a given number of elements, equivalent to +Perl's C<$#array = $fill;>. + + void av_fill(AV* ar, I32 fill) + +=for hackers +Found in file av.c + =item av_len Returns the highest index in the array. Returns -1 if the array is @@ -57,6 +101,9 @@ empty. I32 av_len(AV* ar) +=for hackers +Found in file av.c + =item av_make Creates a new AV and populates it with a list of SVs. The SVs are copied @@ -65,6 +112,9 @@ will have a reference count of 1. AV* av_make(I32 size, SV** svp) +=for hackers +Found in file av.c + =item av_pop Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array @@ -72,6 +122,9 @@ is empty. SV* av_pop(AV* ar) +=for hackers +Found in file av.c + =item av_push Pushes an SV onto the end of the array. The array will grow automatically @@ -79,12 +132,18 @@ to accommodate the addition. void av_push(AV* ar, SV* val) +=for hackers +Found in file av.c + =item av_shift Shifts an SV off the beginning of the array. SV* av_shift(AV* ar) +=for hackers +Found in file av.c + =item av_store Stores an SV in an array. The array index is specified as C<key>. The @@ -100,12 +159,18 @@ more information on how to use this function on tied arrays. SV** av_store(AV* ar, I32 key, SV* val) +=for hackers +Found in file av.c + =item av_undef Undefines the array. Frees the memory used by the array itself. void av_undef(AV* ar) +=for hackers +Found in file av.c + =item av_unshift Unshift the given number of C<undef> values onto the beginning of the @@ -114,6 +179,40 @@ must then use C<av_store> to assign values to these new elements. void av_unshift(AV* ar, I32 num) +=for hackers +Found in file av.c + +=item bytes_from_utf8 + +Converts a string C<s> of length C<len> from UTF8 into byte encoding. +Unlike <utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to +the newly-created string, and updates C<len> to contain the new +length. Returns the original string if no conversion occurs, C<len> +is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to +0 if C<s> is converted or contains all 7bit characters. + +NOTE: this function is experimental and may change or be +removed without notice. + + U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8) + +=for hackers +Found in file utf8.c + +=item bytes_to_utf8 + +Converts a string C<s> of length C<len> from ASCII into UTF8 encoding. +Returns a pointer to the newly-created string, and sets C<len> to +reflect the new length. + +NOTE: this function is experimental and may change or be +removed without notice. + + U8* bytes_to_utf8(U8 *s, STRLEN *len) + +=for hackers +Found in file utf8.c + =item call_argv Performs a callback to the specified Perl sub. See L<perlcall>. @@ -122,6 +221,9 @@ NOTE: the perl_ form of this function is deprecated. I32 call_argv(const char* sub_name, I32 flags, char** argv) +=for hackers +Found in file perl.c + =item call_method Performs a callback to the specified Perl method. The blessed object must @@ -131,6 +233,9 @@ NOTE: the perl_ form of this function is deprecated. I32 call_method(const char* methname, I32 flags) +=for hackers +Found in file perl.c + =item call_pv Performs a callback to the specified Perl sub. See L<perlcall>. @@ -139,6 +244,9 @@ NOTE: the perl_ form of this function is deprecated. I32 call_pv(const char* sub_name, I32 flags) +=for hackers +Found in file perl.c + =item call_sv Performs a callback to the Perl sub whose name is in the SV. See @@ -148,6 +256,9 @@ NOTE: the perl_ form of this function is deprecated. I32 call_sv(SV* sv, I32 flags) +=for hackers +Found in file perl.c + =item CLASS Variable which is setup by C<xsubpp> to indicate the @@ -155,6 +266,9 @@ class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>. char* CLASS +=for hackers +Found in file XSUB.h + =item Copy The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the @@ -163,20 +277,36 @@ the type. May fail on overlapping copies. See also C<Move>. void Copy(void* src, void* dest, int nitems, type) +=for hackers +Found in file handy.h + =item croak -This is the XSUB-writer's interface to Perl's C<die> function. Use this -function the same way you use the C C<printf> function. See -C<warn>. +This is the XSUB-writer's interface to Perl's C<die> function. +Normally use this function the same way you use the C C<printf> +function. See C<warn>. + +If you want to throw an exception object, assign the object to +C<$@> and then pass C<Nullch> to croak(): + + errsv = get_sv("@", TRUE); + sv_setsv(errsv, exception_object); + croak(Nullch); void croak(const char* pat, ...) +=for hackers +Found in file util.c + =item CvSTASH Returns the stash of the CV. HV* CvSTASH(CV* cv) +=for hackers +Found in file cv.h + =item dMARK Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and @@ -184,12 +314,18 @@ C<dORIGMARK>. dMARK; +=for hackers +Found in file pp.h + =item dORIGMARK Saves the original stack mark for the XSUB. See C<ORIGMARK>. dORIGMARK; +=for hackers +Found in file pp.h + =item dSP Declares a local copy of perl's stack pointer for the XSUB, available via @@ -197,6 +333,9 @@ the C<SP> macro. See C<SP>. dSP; +=for hackers +Found in file pp.h + =item dXSARGS Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This @@ -205,6 +344,9 @@ variable to indicate the number of items on the stack. dXSARGS; +=for hackers +Found in file XSUB.h + =item dXSI32 Sets up the C<ix> variable for an XSUB which has aliases. This is usually @@ -212,12 +354,18 @@ handled automatically by C<xsubpp>. dXSI32; +=for hackers +Found in file XSUB.h + =item ENTER Opening bracket on a callback. See C<LEAVE> and L<perlcall>. ENTER; +=for hackers +Found in file scope.h + =item eval_pv Tells Perl to C<eval> the given string and return an SV* result. @@ -226,6 +374,9 @@ NOTE: the perl_ form of this function is deprecated. SV* eval_pv(const char* p, I32 croak_on_error) +=for hackers +Found in file perl.c + =item eval_sv Tells Perl to C<eval> the string in the SV. @@ -234,14 +385,20 @@ NOTE: the perl_ form of this function is deprecated. I32 eval_sv(SV* sv, I32 flags) +=for hackers +Found in file perl.c + =item EXTEND Used to extend the argument stack for an XSUB's return values. Once -used, guarrantees that there is room for at least C<nitems> to be pushed +used, guarantees that there is room for at least C<nitems> to be pushed onto the stack. void EXTEND(SP, int nitems) +=for hackers +Found in file pp.h + =item fbm_compile Analyses the string in order to make fast searches on it using fbm_instr() @@ -249,6 +406,9 @@ Analyses the string in order to make fast searches on it using fbm_instr() void fbm_compile(SV* sv, U32 flags) +=for hackers +Found in file util.c + =item fbm_instr Returns the location of the SV in the string delimited by C<str> and @@ -258,6 +418,9 @@ then. char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags) +=for hackers +Found in file util.c + =item FREETMPS Closing bracket for temporaries on a callback. See C<SAVETMPS> and @@ -265,6 +428,9 @@ L<perlcall>. FREETMPS; +=for hackers +Found in file scope.h + =item get_av Returns the AV of the specified Perl array. If C<create> is set and the @@ -275,6 +441,9 @@ NOTE: the perl_ form of this function is deprecated. AV* get_av(const char* name, I32 create) +=for hackers +Found in file perl.c + =item get_cv Returns the CV of the specified Perl subroutine. If C<create> is set and @@ -286,6 +455,9 @@ NOTE: the perl_ form of this function is deprecated. CV* get_cv(const char* name, I32 create) +=for hackers +Found in file perl.c + =item get_hv Returns the HV of the specified Perl hash. If C<create> is set and the @@ -296,6 +468,9 @@ NOTE: the perl_ form of this function is deprecated. HV* get_hv(const char* name, I32 create) +=for hackers +Found in file perl.c + =item get_sv Returns the SV of the specified Perl scalar. If C<create> is set and the @@ -306,6 +481,9 @@ NOTE: the perl_ form of this function is deprecated. SV* get_sv(const char* name, I32 create) +=for hackers +Found in file perl.c + =item GIMME A backward-compatible version of C<GIMME_V> which can only return @@ -314,71 +492,89 @@ Deprecated. Use C<GIMME_V> instead. U32 GIMME +=for hackers +Found in file op.h + =item GIMME_V The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>, -C<G_SCALAR> or C<G_ARRAY> for void, scalar or array context, +C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context, respectively. U32 GIMME_V +=for hackers +Found in file op.h + =item GvSV Return the SV from the GV. SV* GvSV(GV* gv) +=for hackers +Found in file gv.h + =item gv_fetchmeth Returns the glob with the given C<name> and a defined subroutine or C<NULL>. The glob lives in the given C<stash>, or in the stashes -accessible via @ISA and @UNIVERSAL. +accessible via @ISA and @UNIVERSAL. The argument C<level> should be either 0 or -1. If C<level==0>, as a side-effect creates a glob with the given C<name> in the given C<stash> which in the case of success contains an alias for the subroutine, and sets -up caching info for this glob. Similarly for all the searched stashes. +up caching info for this glob. Similarly for all the searched stashes. This function grants C<"SUPER"> token as a postfix of the stash name. The GV returned from C<gv_fetchmeth> may be a method cache entry, which is not visible to Perl code. So when calling C<call_sv>, you should not use the GV directly; instead, you should use the method's CV, which can be -obtained from the GV with the C<GvCV> macro. +obtained from the GV with the C<GvCV> macro. GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level) +=for hackers +Found in file gv.c + =item gv_fetchmethod See L<gv_fetchmethod_autoload>. GV* gv_fetchmethod(HV* stash, const char* name) +=for hackers +Found in file gv.c + =item gv_fetchmethod_autoload Returns the glob which contains the subroutine to call to invoke the method on the C<stash>. In fact in the presence of autoloading this may be the glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is -already setup. +already setup. The third parameter of C<gv_fetchmethod_autoload> determines whether AUTOLOAD lookup is performed if the given method is not present: non-zero -means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD. +means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD. Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload> -with a non-zero C<autoload> parameter. +with a non-zero C<autoload> parameter. These functions grant C<"SUPER"> token as a prefix of the method name. Note that if you want to keep the returned glob for a long time, you need to check for it being "AUTOLOAD", since at the later time the call may load a different subroutine due to $AUTOLOAD changing its value. Use the glob -created via a side effect to do this. +created via a side effect to do this. These functions have the same side-effects and as C<gv_fetchmeth> with C<level==0>. C<name> should be writable if contains C<':'> or C<' ''>. The warning against passing the GV returned by C<gv_fetchmeth> to -C<call_sv> apply equally to these functions. +C<call_sv> apply equally to these functions. GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload) +=for hackers +Found in file gv.c + =item gv_stashpv Returns a pointer to the stash for a specified package. C<name> should @@ -388,6 +584,9 @@ package does not exist then NULL is returned. HV* gv_stashpv(const char* name, I32 create) +=for hackers +Found in file gv.c + =item gv_stashsv Returns a pointer to the stash for a specified package, which must be a @@ -395,47 +594,74 @@ valid UTF-8 string. See C<gv_stashpv>. HV* gv_stashsv(SV* sv, I32 create) +=for hackers +Found in file gv.c + =item G_ARRAY -Used to indicate array context. See C<GIMME_V>, C<GIMME> and +Used to indicate list context. See C<GIMME_V>, C<GIMME> and L<perlcall>. +=for hackers +Found in file cop.h + =item G_DISCARD Indicates that arguments returned from a callback should be discarded. See L<perlcall>. +=for hackers +Found in file cop.h + =item G_EVAL Used to force a Perl C<eval> wrapper around a callback. See L<perlcall>. +=for hackers +Found in file cop.h + =item G_NOARGS Indicates that no arguments are being sent to a callback. See L<perlcall>. +=for hackers +Found in file cop.h + =item G_SCALAR Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and L<perlcall>. +=for hackers +Found in file cop.h + =item G_VOID Used to indicate void context. See C<GIMME_V> and L<perlcall>. +=for hackers +Found in file cop.h + =item HEf_SVKEY This flag, used in the length slot of hash entries and magic structures, specifies the structure contains a C<SV*> pointer where a C<char*> pointer is to be expected. (For information only--not to be used). +=for hackers +Found in file hv.h + =item HeHASH Returns the computed hash stored in the hash entry. U32 HeHASH(HE* he) +=for hackers +Found in file hv.h + =item HeKEY Returns the actual pointer stored in the key slot of the hash entry. The @@ -445,6 +671,9 @@ usually preferable for finding the value of a key. void* HeKEY(HE* he) +=for hackers +Found in file hv.h + =item HeKLEN If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry @@ -454,6 +683,9 @@ lengths. STRLEN HeKLEN(HE* he) +=for hackers +Found in file hv.h + =item HePV Returns the key slot of the hash entry as a C<char*> value, doing any @@ -468,6 +700,9 @@ described elsewhere in this document. char* HePV(HE* he, STRLEN len) +=for hackers +Found in file hv.h + =item HeSVKEY Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not @@ -475,6 +710,9 @@ contain an C<SV*> key. SV* HeSVKEY(HE* he) +=for hackers +Found in file hv.h + =item HeSVKEY_force Returns the key as an C<SV*>. Will create and return a temporary mortal @@ -482,6 +720,9 @@ C<SV*> if the hash entry contains only a C<char*> key. SV* HeSVKEY_force(HE* he) +=for hackers +Found in file hv.h + =item HeSVKEY_set Sets the key to a given C<SV*>, taking care to set the appropriate flags to @@ -490,24 +731,36 @@ C<SV*>. SV* HeSVKEY_set(HE* he, SV* sv) +=for hackers +Found in file hv.h + =item HeVAL Returns the value slot (type C<SV*>) stored in the hash entry. SV* HeVAL(HE* he) +=for hackers +Found in file hv.h + =item HvNAME Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>. char* HvNAME(HV* stash) +=for hackers +Found in file hv.h + =item hv_clear Clears a hash, making it empty. void hv_clear(HV* tb) +=for hackers +Found in file hv.c + =item hv_delete Deletes a key/value pair in the hash. The value SV is removed from the @@ -517,6 +770,9 @@ will be returned. SV* hv_delete(HV* tb, const char* key, U32 klen, I32 flags) +=for hackers +Found in file hv.c + =item hv_delete_ent Deletes a key/value pair in the hash. The value SV is removed from the @@ -526,6 +782,9 @@ precomputed hash value, or 0 to ask for it to be computed. SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash) +=for hackers +Found in file hv.c + =item hv_exists Returns a boolean indicating whether the specified hash key exists. The @@ -533,6 +792,9 @@ C<klen> is the length of the key. bool hv_exists(HV* tb, const char* key, U32 klen) +=for hackers +Found in file hv.c + =item hv_exists_ent Returns a boolean indicating whether the specified hash key exists. C<hash> @@ -541,6 +803,9 @@ computed. bool hv_exists_ent(HV* tb, SV* key, U32 hash) +=for hackers +Found in file hv.c + =item hv_fetch Returns the SV which corresponds to the specified key in the hash. The @@ -553,6 +818,9 @@ information on how to use this function on tied hashes. SV** hv_fetch(HV* tb, const char* key, U32 klen, I32 lval) +=for hackers +Found in file hv.c + =item hv_fetch_ent Returns the hash entry which corresponds to the specified key in the hash. @@ -568,6 +836,9 @@ information on how to use this function on tied hashes. HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash) +=for hackers +Found in file hv.c + =item hv_iterinit Prepares a starting point to traverse a hash table. Returns the number of @@ -580,6 +851,9 @@ value, you can get it through the macro C<HvFILL(tb)>. I32 hv_iterinit(HV* tb) +=for hackers +Found in file hv.c + =item hv_iterkey Returns the key from the current position of the hash iterator. See @@ -587,6 +861,9 @@ C<hv_iterinit>. char* hv_iterkey(HE* entry, I32* retlen) +=for hackers +Found in file hv.c + =item hv_iterkeysv Returns the key as an C<SV*> from the current position of the hash @@ -595,12 +872,18 @@ see C<hv_iterinit>. SV* hv_iterkeysv(HE* entry) +=for hackers +Found in file hv.c + =item hv_iternext Returns entries from a hash iterator. See C<hv_iterinit>. HE* hv_iternext(HV* tb) +=for hackers +Found in file hv.c + =item hv_iternextsv Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one @@ -608,6 +891,9 @@ operation. SV* hv_iternextsv(HV* hv, char** key, I32* retlen) +=for hackers +Found in file hv.c + =item hv_iterval Returns the value from the current position of the hash iterator. See @@ -615,12 +901,18 @@ C<hv_iterkey>. SV* hv_iterval(HV* tb, HE* entry) +=for hackers +Found in file hv.c + =item hv_magic Adds magic to a hash. See C<sv_magic>. void hv_magic(HV* hv, GV* gv, int how) +=for hackers +Found in file hv.c + =item hv_store Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is @@ -637,6 +929,9 @@ information on how to use this function on tied hashes. SV** hv_store(HV* tb, const char* key, U32 klen, SV* val, U32 hash) +=for hackers +Found in file hv.c + =item hv_store_ent Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash> @@ -654,33 +949,48 @@ information on how to use this function on tied hashes. HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash) +=for hackers +Found in file hv.c + =item hv_undef Undefines the hash. void hv_undef(HV* tb) +=for hackers +Found in file hv.c + =item isALNUM -Returns a boolean indicating whether the C C<char> is an ascii alphanumeric -character or digit. +Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric +character (including underscore) or digit. bool isALNUM(char ch) +=for hackers +Found in file handy.h + =item isALPHA -Returns a boolean indicating whether the C C<char> is an ascii alphabetic +Returns a boolean indicating whether the C C<char> is an ASCII alphabetic character. bool isALPHA(char ch) +=for hackers +Found in file handy.h + =item isDIGIT -Returns a boolean indicating whether the C C<char> is an ascii +Returns a boolean indicating whether the C C<char> is an ASCII digit. bool isDIGIT(char ch) +=for hackers +Found in file handy.h + =item isLOWER Returns a boolean indicating whether the C C<char> is a lowercase @@ -688,12 +998,18 @@ character. bool isLOWER(char ch) +=for hackers +Found in file handy.h + =item isSPACE Returns a boolean indicating whether the C C<char> is whitespace. bool isSPACE(char ch) +=for hackers +Found in file handy.h + =item isUPPER Returns a boolean indicating whether the C C<char> is an uppercase @@ -701,6 +1017,30 @@ character. bool isUPPER(char ch) +=for hackers +Found in file handy.h + +=item is_utf8_char + +Tests if some arbitrary number of bytes begins in a valid UTF-8 character. +The actual number of bytes in the UTF-8 character will be returned if it +is valid, otherwise 0. + + STRLEN is_utf8_char(U8 *p) + +=for hackers +Found in file utf8.c + +=item is_utf8_string + +Returns true if first C<len> bytes of the given string form valid a UTF8 +string, false otherwise. + + bool is_utf8_string(U8 *s, STRLEN len) + +=for hackers +Found in file utf8.c + =item items Variable which is setup by C<xsubpp> to indicate the number of @@ -708,6 +1048,9 @@ items on the stack. See L<perlxs/"Variable-length Parameter Lists">. I32 items +=for hackers +Found in file XSUB.h + =item ix Variable which is setup by C<xsubpp> to indicate which of an @@ -715,12 +1058,18 @@ XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">. I32 ix +=for hackers +Found in file XSUB.h + =item LEAVE Closing bracket on a callback. See C<ENTER> and L<perlcall>. LEAVE; +=for hackers +Found in file scope.h + =item looks_like_number Test if an the content of an SV looks like a number (or is a @@ -728,58 +1077,88 @@ number). I32 looks_like_number(SV* sv) +=for hackers +Found in file sv.c + =item MARK Stack marker variable for the XSUB. See C<dMARK>. +=for hackers +Found in file pp.h + =item mg_clear Clear something magical that the SV represents. See C<sv_magic>. int mg_clear(SV* sv) +=for hackers +Found in file mg.c + =item mg_copy Copies the magic from one SV to another. See C<sv_magic>. int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen) +=for hackers +Found in file mg.c + =item mg_find Finds the magic pointer for type matching the SV. See C<sv_magic>. MAGIC* mg_find(SV* sv, int type) +=for hackers +Found in file mg.c + =item mg_free Free any magic storage used by the SV. See C<sv_magic>. int mg_free(SV* sv) +=for hackers +Found in file mg.c + =item mg_get Do magic after a value is retrieved from the SV. See C<sv_magic>. int mg_get(SV* sv) +=for hackers +Found in file mg.c + =item mg_length Report on the SV's length. See C<sv_magic>. U32 mg_length(SV* sv) +=for hackers +Found in file mg.c + =item mg_magical Turns on the magical status of an SV. See C<sv_magic>. void mg_magical(SV* sv) +=for hackers +Found in file mg.c + =item mg_set Do magic after a value is assigned to the SV. See C<sv_magic>. int mg_set(SV* sv) +=for hackers +Found in file mg.c + =item Move The XSUB-writer's interface to the C C<memmove> function. The C<src> is the @@ -788,18 +1167,27 @@ the type. Can do overlapping moves. See also C<Copy>. void Move(void* src, void* dest, int nitems, type) +=for hackers +Found in file handy.h + =item New The XSUB-writer's interface to the C C<malloc> function. void New(int id, void* ptr, int nitems, type) +=for hackers +Found in file handy.h + =item newAV Creates a new AV. The reference count is set to 1. AV* newAV() +=for hackers +Found in file av.c + =item Newc The XSUB-writer's interface to the C C<malloc> function, with @@ -807,6 +1195,9 @@ cast. void Newc(int id, void* ptr, int nitems, type, cast) +=for hackers +Found in file handy.h + =item newCONSTSUB Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is @@ -814,12 +1205,18 @@ eligible for inlining at compile-time. void newCONSTSUB(HV* stash, char* name, SV* sv) +=for hackers +Found in file op.c + =item newHV Creates a new HV. The reference count is set to 1. HV* newHV() +=for hackers +Found in file hv.c + =item newRV_inc Creates an RV wrapper for an SV. The reference count for the original SV is @@ -827,6 +1224,9 @@ incremented. SV* newRV_inc(SV* sv) +=for hackers +Found in file sv.h + =item newRV_noinc Creates an RV wrapper for an SV. The reference count for the original @@ -834,16 +1234,22 @@ SV is B<not> incremented. SV* newRV_noinc(SV *sv) +=for hackers +Found in file sv.c + =item NEWSV Creates a new SV. A non-zero C<len> parameter indicates the number of bytes of preallocated string space the SV should have. An extra byte for a tailing NUL is also reserved. (SvPOK is not set for the SV even if string -space is allocated.) The reference count for the new SV is set to 1. +space is allocated.) The reference count for the new SV is set to 1. C<id> is an integer id between 0 and 1299 (used to identify leaks). SV* NEWSV(int id, STRLEN len) +=for hackers +Found in file handy.h + =item newSViv Creates a new SV and copies an integer into it. The reference count for the @@ -851,6 +1257,9 @@ SV is set to 1. SV* newSViv(IV i) +=for hackers +Found in file sv.c + =item newSVnv Creates a new SV and copies a floating point value into it. @@ -858,6 +1267,9 @@ The reference count for the SV is set to 1. SV* newSVnv(NV n) +=for hackers +Found in file sv.c + =item newSVpv Creates a new SV and copies a string into it. The reference count for the @@ -866,6 +1278,9 @@ strlen(). For efficiency, consider using C<newSVpvn> instead. SV* newSVpv(const char* s, STRLEN len) +=for hackers +Found in file sv.c + =item newSVpvf Creates a new SV an initialize it with the string formatted like @@ -873,6 +1288,9 @@ C<sprintf>. SV* newSVpvf(const char* pat, ...) +=for hackers +Found in file sv.c + =item newSVpvn Creates a new SV and copies a string into it. The reference count for the @@ -882,6 +1300,9 @@ C<len> bytes long. SV* newSVpvn(const char* s, STRLEN len) +=for hackers +Found in file sv.c + =item newSVrv Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then @@ -891,12 +1312,18 @@ reference count is 1. SV* newSVrv(SV* rv, const char* classname) +=for hackers +Found in file sv.c + =item newSVsv Creates a new SV which is an exact duplicate of the original SV. SV* newSVsv(SV* old) +=for hackers +Found in file sv.c + =item newSVuv Creates a new SV and copies an unsigned integer into it. @@ -904,15 +1331,24 @@ The reference count for the SV is set to 1. SV* newSVuv(UV u) +=for hackers +Found in file sv.c + =item newXS Used by C<xsubpp> to hook up XSUBs as Perl subs. +=for hackers +Found in file op.c + =item newXSproto Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to the subs. +=for hackers +Found in file XSUB.h + =item Newz The XSUB-writer's interface to the C C<malloc> function. The allocated @@ -920,98 +1356,104 @@ memory is zeroed with C<memzero>. void Newz(int id, void* ptr, int nitems, type) +=for hackers +Found in file handy.h + =item Nullav Null AV pointer. +=for hackers +Found in file av.h + =item Nullch Null character pointer. +=for hackers +Found in file handy.h + =item Nullcv Null CV pointer. +=for hackers +Found in file cv.h + =item Nullhv Null HV pointer. +=for hackers +Found in file hv.h + =item Nullsv Null SV pointer. +=for hackers +Found in file handy.h + =item ORIGMARK The original stack mark for the XSUB. See C<dORIGMARK>. +=for hackers +Found in file pp.h + =item perl_alloc Allocates a new Perl interpreter. See L<perlembed>. PerlInterpreter* perl_alloc() +=for hackers +Found in file perl.c + =item perl_construct Initializes a new Perl interpreter. See L<perlembed>. void perl_construct(PerlInterpreter* interp) +=for hackers +Found in file perl.c + =item perl_destruct Shuts down a Perl interpreter. See L<perlembed>. void perl_destruct(PerlInterpreter* interp) +=for hackers +Found in file perl.c + =item perl_free Releases a Perl interpreter. See L<perlembed>. void perl_free(PerlInterpreter* interp) +=for hackers +Found in file perl.c + =item perl_parse Tells a Perl interpreter to parse a Perl script. See L<perlembed>. int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env) +=for hackers +Found in file perl.c + =item perl_run Tells a Perl interpreter to run. See L<perlembed>. int perl_run(PerlInterpreter* interp) -=item PL_DBsingle - -When Perl is run in debugging mode, with the B<-d> switch, this SV is a -boolean which indicates whether subs are being single-stepped. -Single-stepping is automatically turned on after every step. This is the C -variable which corresponds to Perl's $DB::single variable. See -C<PL_DBsub>. - - SV * PL_DBsingle - -=item PL_DBsub - -When Perl is run in debugging mode, with the B<-d> switch, this GV contains -the SV which holds the name of the sub being debugged. This is the C -variable which corresponds to Perl's $DB::sub variable. See -C<PL_DBsingle>. - - GV * PL_DBsub - -=item PL_DBtrace - -Trace variable used when Perl is run in debugging mode, with the B<-d> -switch. This is the C variable which corresponds to Perl's $DB::trace -variable. See C<PL_DBsingle>. - - SV * PL_DBtrace - -=item PL_dowarn - -The C variable which corresponds to Perl's $^W warning variable. - - bool PL_dowarn +=for hackers +Found in file perl.c =item PL_modglobal @@ -1023,6 +1465,9 @@ prefixed by the package name of the extension that owns the data. HV* PL_modglobal +=for hackers +Found in file intrpvar.h + =item PL_na A convenience variable which is typically used with C<SvPV> when one @@ -1032,6 +1477,9 @@ C<SvPV_nolen> macro. STRLEN PL_na +=for hackers +Found in file thrdvar.h + =item PL_sv_no This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as @@ -1039,12 +1487,18 @@ C<&PL_sv_no>. SV PL_sv_no +=for hackers +Found in file intrpvar.h + =item PL_sv_undef This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>. SV PL_sv_undef +=for hackers +Found in file intrpvar.h + =item PL_sv_yes This is the C<true> SV. See C<PL_sv_no>. Always refer to this as @@ -1052,36 +1506,54 @@ C<&PL_sv_yes>. SV PL_sv_yes +=for hackers +Found in file intrpvar.h + =item POPi Pops an integer off the stack. IV POPi +=for hackers +Found in file pp.h + =item POPl Pops a long off the stack. long POPl +=for hackers +Found in file pp.h + =item POPn Pops a double off the stack. NV POPn +=for hackers +Found in file pp.h + =item POPp Pops a string off the stack. char* POPp +=for hackers +Found in file pp.h + =item POPs Pops an SV off the stack. SV* POPs +=for hackers +Found in file pp.h + =item PUSHi Push an integer onto the stack. The stack must have room for this element. @@ -1089,6 +1561,9 @@ Handles 'set' magic. See C<XPUSHi>. void PUSHi(IV iv) +=for hackers +Found in file pp.h + =item PUSHMARK Opening bracket for arguments on a callback. See C<PUTBACK> and @@ -1096,6 +1571,9 @@ L<perlcall>. PUSHMARK; +=for hackers +Found in file pp.h + =item PUSHn Push a double onto the stack. The stack must have room for this element. @@ -1103,6 +1581,9 @@ Handles 'set' magic. See C<XPUSHn>. void PUSHn(NV nv) +=for hackers +Found in file pp.h + =item PUSHp Push a string onto the stack. The stack must have room for this element. @@ -1111,13 +1592,19 @@ C<XPUSHp>. void PUSHp(char* str, STRLEN len) +=for hackers +Found in file pp.h + =item PUSHs -Push an SV onto the stack. The stack must have room for this element. +Push an SV onto the stack. The stack must have room for this element. Does not handle 'set' magic. See C<XPUSHs>. void PUSHs(SV* sv) +=for hackers +Found in file pp.h + =item PUSHu Push an unsigned integer onto the stack. The stack must have room for this @@ -1125,6 +1612,9 @@ element. See C<XPUSHu>. void PUSHu(UV uv) +=for hackers +Found in file pp.h + =item PUTBACK Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>. @@ -1132,12 +1622,18 @@ See C<PUSHMARK> and L<perlcall> for other uses. PUTBACK; +=for hackers +Found in file pp.h + =item Renew The XSUB-writer's interface to the C C<realloc> function. void Renew(void* ptr, int nitems, type) +=for hackers +Found in file handy.h + =item Renewc The XSUB-writer's interface to the C C<realloc> function, with @@ -1145,6 +1641,9 @@ cast. void Renewc(void* ptr, int nitems, type, cast) +=for hackers +Found in file handy.h + =item require_pv Tells Perl to C<require> a module. @@ -1153,6 +1652,9 @@ NOTE: the perl_ form of this function is deprecated. void require_pv(const char* pv) +=for hackers +Found in file perl.c + =item RETVAL Variable which is setup by C<xsubpp> to hold the return value for an @@ -1161,11 +1663,17 @@ L<perlxs/"The RETVAL Variable">. (whatever) RETVAL +=for hackers +Found in file XSUB.h + =item Safefree The XSUB-writer's interface to the C C<free> function. - void Safefree(void* src, void* dest, int nitems, type) + void Safefree(void* ptr) + +=for hackers +Found in file handy.h =item savepv @@ -1173,6 +1681,9 @@ Copy a string to a safe spot. This does not use an SV. char* savepv(const char* sv) +=for hackers +Found in file util.c + =item savepvn Copy a string to a safe spot. The C<len> indicates number of bytes to @@ -1180,6 +1691,9 @@ copy. This does not use an SV. char* savepvn(const char* sv, I32 len) +=for hackers +Found in file util.c + =item SAVETMPS Opening bracket for temporaries on a callback. See C<FREETMPS> and @@ -1187,29 +1701,44 @@ L<perlcall>. SAVETMPS; +=for hackers +Found in file scope.h + =item SP Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and C<SPAGAIN>. +=for hackers +Found in file pp.h + =item SPAGAIN Refetch the stack pointer. Used after a callback. See L<perlcall>. SPAGAIN; +=for hackers +Found in file pp.h + =item ST Used to access elements on the XSUB's stack. SV* ST(int ix) +=for hackers +Found in file XSUB.h + =item strEQ Test two strings to see if they are equal. Returns true or false. bool strEQ(char* s1, char* s2) +=for hackers +Found in file handy.h + =item strGE Test two strings to see if the first, C<s1>, is greater than or equal to @@ -1217,6 +1746,9 @@ the second, C<s2>. Returns true or false. bool strGE(char* s1, char* s2) +=for hackers +Found in file handy.h + =item strGT Test two strings to see if the first, C<s1>, is greater than the second, @@ -1224,6 +1756,9 @@ C<s2>. Returns true or false. bool strGT(char* s1, char* s2) +=for hackers +Found in file handy.h + =item strLE Test two strings to see if the first, C<s1>, is less than or equal to the @@ -1231,6 +1766,9 @@ second, C<s2>. Returns true or false. bool strLE(char* s1, char* s2) +=for hackers +Found in file handy.h + =item strLT Test two strings to see if the first, C<s1>, is less than the second, @@ -1238,6 +1776,9 @@ C<s2>. Returns true or false. bool strLT(char* s1, char* s2) +=for hackers +Found in file handy.h + =item strNE Test two strings to see if they are different. Returns true or @@ -1245,6 +1786,9 @@ false. bool strNE(char* s1, char* s2) +=for hackers +Found in file handy.h + =item strnEQ Test two strings to see if they are equal. The C<len> parameter indicates @@ -1253,6 +1797,9 @@ C<strncmp>). bool strnEQ(char* s1, char* s2, STRLEN len) +=for hackers +Found in file handy.h + =item strnNE Test two strings to see if they are different. The C<len> parameter @@ -1261,24 +1808,36 @@ wrapper for C<strncmp>). bool strnNE(char* s1, char* s2, STRLEN len) +=for hackers +Found in file handy.h + =item StructCopy -This is an architecture-independant macro to copy one structure to another. +This is an architecture-independent macro to copy one structure to another. void StructCopy(type src, type dest, type) +=for hackers +Found in file handy.h + =item SvCUR Returns the length of the string which is in the SV. See C<SvLEN>. STRLEN SvCUR(SV* sv) +=for hackers +Found in file sv.h + =item SvCUR_set Set the length of the string which is in the SV. See C<SvCUR>. void SvCUR_set(SV* sv, STRLEN len) +=for hackers +Found in file sv.h + =item SvEND Returns a pointer to the last character in the string which is in the SV. @@ -1286,6 +1845,9 @@ See C<SvCUR>. Access the character as *(SvEND(sv)). char* SvEND(SV* sv) +=for hackers +Found in file sv.h + =item SvGETMAGIC Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its @@ -1293,6 +1855,9 @@ argument more than once. void SvGETMAGIC(SV* sv) +=for hackers +Found in file sv.h + =item SvGROW Expands the character buffer in the SV so that it has room for the @@ -1302,12 +1867,18 @@ Returns a pointer to the character buffer. void SvGROW(SV* sv, STRLEN len) +=for hackers +Found in file sv.h + =item SvIOK Returns a boolean indicating whether the SV contains an integer. bool SvIOK(SV* sv) +=for hackers +Found in file sv.h + =item SvIOKp Returns a boolean indicating whether the SV contains an integer. Checks @@ -1315,30 +1886,72 @@ the B<private> setting. Use C<SvIOK>. bool SvIOKp(SV* sv) +=for hackers +Found in file sv.h + +=item SvIOK_notUV + +Returns a boolean indicating whether the SV contains an signed integer. + + void SvIOK_notUV(SV* sv) + +=for hackers +Found in file sv.h + =item SvIOK_off Unsets the IV status of an SV. void SvIOK_off(SV* sv) +=for hackers +Found in file sv.h + =item SvIOK_on Tells an SV that it is an integer. void SvIOK_on(SV* sv) +=for hackers +Found in file sv.h + =item SvIOK_only Tells an SV that it is an integer and disables all other OK bits. void SvIOK_only(SV* sv) +=for hackers +Found in file sv.h + +=item SvIOK_only_UV + +Tells and SV that it is an unsigned integer and disables all other OK bits. + + void SvIOK_only_UV(SV* sv) + +=for hackers +Found in file sv.h + +=item SvIOK_UV + +Returns a boolean indicating whether the SV contains an unsigned integer. + + void SvIOK_UV(SV* sv) + +=for hackers +Found in file sv.h + =item SvIV Coerces the given SV to an integer and returns it. IV SvIV(SV* sv) +=for hackers +Found in file sv.h + =item SvIVX Returns the integer which is stored in the SV, assuming SvIOK is @@ -1346,12 +1959,19 @@ true. IV SvIVX(SV* sv) +=for hackers +Found in file sv.h + =item SvLEN -Returns the size of the string buffer in the SV. See C<SvCUR>. +Returns the size of the string buffer in the SV, not including any part +attributable to C<SvOOK>. See C<SvCUR>. STRLEN SvLEN(SV* sv) +=for hackers +Found in file sv.h + =item SvNIOK Returns a boolean indicating whether the SV contains a number, integer or @@ -1359,6 +1979,9 @@ double. bool SvNIOK(SV* sv) +=for hackers +Found in file sv.h + =item SvNIOKp Returns a boolean indicating whether the SV contains a number, integer or @@ -1366,18 +1989,27 @@ double. Checks the B<private> setting. Use C<SvNIOK>. bool SvNIOKp(SV* sv) +=for hackers +Found in file sv.h + =item SvNIOK_off Unsets the NV/IV status of an SV. void SvNIOK_off(SV* sv) +=for hackers +Found in file sv.h + =item SvNOK Returns a boolean indicating whether the SV contains a double. bool SvNOK(SV* sv) +=for hackers +Found in file sv.h + =item SvNOKp Returns a boolean indicating whether the SV contains a double. Checks the @@ -1385,30 +2017,45 @@ B<private> setting. Use C<SvNOK>. bool SvNOKp(SV* sv) +=for hackers +Found in file sv.h + =item SvNOK_off Unsets the NV status of an SV. void SvNOK_off(SV* sv) +=for hackers +Found in file sv.h + =item SvNOK_on Tells an SV that it is a double. void SvNOK_on(SV* sv) +=for hackers +Found in file sv.h + =item SvNOK_only Tells an SV that it is a double and disables all other OK bits. void SvNOK_only(SV* sv) +=for hackers +Found in file sv.h + =item SvNV Coerce the given SV to a double and return it. NV SvNV(SV* sv) +=for hackers +Found in file sv.h + =item SvNVX Returns the double which is stored in the SV, assuming SvNOK is @@ -1416,12 +2063,18 @@ true. NV SvNVX(SV* sv) +=for hackers +Found in file sv.h + =item SvOK Returns a boolean indicating whether the value is an SV. bool SvOK(SV* sv) +=for hackers +Found in file sv.h + =item SvOOK Returns a boolean indicating whether the SvIVX is a valid offset value for @@ -1431,6 +2084,9 @@ allocated string buffer is really (SvPVX - SvIVX). bool SvOOK(SV* sv) +=for hackers +Found in file sv.h + =item SvPOK Returns a boolean indicating whether the SV contains a character @@ -1438,6 +2094,9 @@ string. bool SvPOK(SV* sv) +=for hackers +Found in file sv.h + =item SvPOKp Returns a boolean indicating whether the SV contains a character string. @@ -1445,24 +2104,46 @@ Checks the B<private> setting. Use C<SvPOK>. bool SvPOKp(SV* sv) +=for hackers +Found in file sv.h + =item SvPOK_off Unsets the PV status of an SV. void SvPOK_off(SV* sv) +=for hackers +Found in file sv.h + =item SvPOK_on Tells an SV that it is a string. void SvPOK_on(SV* sv) +=for hackers +Found in file sv.h + =item SvPOK_only Tells an SV that it is a string and disables all other OK bits. void SvPOK_only(SV* sv) +=for hackers +Found in file sv.h + +=item SvPOK_only_UTF8 + +Tells an SV that it is a UTF8 string (do not use frivolously) +and disables all other OK bits. + + void SvPOK_only_UTF8(SV* sv) + +=for hackers +Found in file sv.h + =item SvPV Returns a pointer to the string in the SV, or a stringified form of the SV @@ -1470,6 +2151,9 @@ if the SV does not contain a string. Handles 'get' magic. char* SvPV(SV* sv, STRLEN len) +=for hackers +Found in file sv.h + =item SvPVX Returns a pointer to the string in the SV. The SV must contain a @@ -1477,6 +2161,9 @@ string. char* SvPVX(SV* sv) +=for hackers +Found in file sv.h + =item SvPV_force Like <SvPV> but will force the SV into becoming a string (SvPOK). You want @@ -1484,6 +2171,9 @@ force if you are going to update the SvPVX directly. char* SvPV_force(SV* sv, STRLEN len) +=for hackers +Found in file sv.h + =item SvPV_nolen Returns a pointer to the string in the SV, or a stringified form of the SV @@ -1491,48 +2181,72 @@ if the SV does not contain a string. Handles 'get' magic. char* SvPV_nolen(SV* sv) +=for hackers +Found in file sv.h + =item SvREFCNT Returns the value of the object's reference count. U32 SvREFCNT(SV* sv) +=for hackers +Found in file sv.h + =item SvREFCNT_dec Decrements the reference count of the given SV. void SvREFCNT_dec(SV* sv) +=for hackers +Found in file sv.h + =item SvREFCNT_inc Increments the reference count of the given SV. SV* SvREFCNT_inc(SV* sv) +=for hackers +Found in file sv.h + =item SvROK Tests if the SV is an RV. bool SvROK(SV* sv) +=for hackers +Found in file sv.h + =item SvROK_off Unsets the RV status of an SV. void SvROK_off(SV* sv) +=for hackers +Found in file sv.h + =item SvROK_on Tells an SV that it is an RV. void SvROK_on(SV* sv) +=for hackers +Found in file sv.h + =item SvRV Dereferences an RV to return the SV. SV* SvRV(SV* sv) +=for hackers +Found in file sv.h + =item SvSETMAGIC Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its @@ -1540,6 +2254,9 @@ argument more than once. void SvSETMAGIC(SV* sv) +=for hackers +Found in file sv.h + =item SvSetSV Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments @@ -1547,6 +2264,9 @@ more than once. void SvSetSV(SV* dsb, SV* ssv) +=for hackers +Found in file sv.h + =item SvSetSV_nosteal Calls a non-destructive version of C<sv_setsv> if dsv is not the same as @@ -1554,18 +2274,27 @@ ssv. May evaluate arguments more than once. void SvSetSV_nosteal(SV* dsv, SV* ssv) +=for hackers +Found in file sv.h + =item SvSTASH Returns the stash of the SV. HV* SvSTASH(SV* sv) +=for hackers +Found in file sv.h + =item SvTAINT Taints an SV if tainting is enabled void SvTAINT(SV* sv) +=for hackers +Found in file sv.h + =item SvTAINTED Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if @@ -1573,6 +2302,9 @@ not. bool SvTAINTED(SV* sv) +=for hackers +Found in file sv.h + =item SvTAINTED_off Untaints an SV. Be I<very> careful with this routine, as it short-circuits @@ -1584,12 +2316,18 @@ untainting variables. void SvTAINTED_off(SV* sv) +=for hackers +Found in file sv.h + =item SvTAINTED_on Marks an SV as tainted. void SvTAINTED_on(SV* sv) +=for hackers +Found in file sv.h + =item SvTRUE Returns a boolean indicating whether Perl would evaluate the SV as true or @@ -1597,45 +2335,75 @@ false, defined or undefined. Does not handle 'get' magic. bool SvTRUE(SV* sv) +=for hackers +Found in file sv.h + +=item svtype + +An enum of flags for Perl types. These are found in the file B<sv.h> +in the C<svtype> enum. Test these flags with the C<SvTYPE> macro. + +=for hackers +Found in file sv.h + =item SvTYPE Returns the type of the SV. See C<svtype>. svtype SvTYPE(SV* sv) -=item svtype - -An enum of flags for Perl types. These are found in the file B<sv.h> -in the C<svtype> enum. Test these flags with the C<SvTYPE> macro. +=for hackers +Found in file sv.h =item SVt_IV Integer type flag for scalars. See C<svtype>. +=for hackers +Found in file sv.h + =item SVt_NV Double type flag for scalars. See C<svtype>. +=for hackers +Found in file sv.h + =item SVt_PV Pointer type flag for scalars. See C<svtype>. +=for hackers +Found in file sv.h + =item SVt_PVAV Type flag for arrays. See C<svtype>. +=for hackers +Found in file sv.h + =item SVt_PVCV Type flag for code refs. See C<svtype>. +=for hackers +Found in file sv.h + =item SVt_PVHV Type flag for hashes. See C<svtype>. +=for hackers +Found in file sv.h + =item SVt_PVMG Type flag for blessed scalars. See C<svtype>. +=for hackers +Found in file sv.h + =item SvUPGRADE Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to @@ -1643,12 +2411,45 @@ perform the upgrade if necessary. See C<svtype>. void SvUPGRADE(SV* sv, svtype type) +=for hackers +Found in file sv.h + +=item SvUTF8 + +Returns a boolean indicating whether the SV contains UTF-8 encoded data. + + void SvUTF8(SV* sv) + +=for hackers +Found in file sv.h + +=item SvUTF8_off + +Unsets the UTF8 status of an SV. + + void SvUTF8_off(SV *sv) + +=for hackers +Found in file sv.h + +=item SvUTF8_on + +Tells an SV that it is a string and encoded in UTF8. Do not use frivolously. + + void SvUTF8_on(SV *sv) + +=for hackers +Found in file sv.h + =item SvUV Coerces the given SV to an unsigned integer and returns it. UV SvUV(SV* sv) +=for hackers +Found in file sv.h + =item SvUVX Returns the unsigned integer which is stored in the SV, assuming SvIOK is @@ -1656,6 +2457,9 @@ true. UV SvUVX(SV* sv) +=for hackers +Found in file sv.h + =item sv_2mortal Marks an SV as mortal. The SV will be destroyed when the current context @@ -1663,6 +2467,9 @@ ends. SV* sv_2mortal(SV* sv) +=for hackers +Found in file sv.c + =item sv_bless Blesses an SV into a specified package. The SV must be an RV. The package @@ -1671,6 +2478,9 @@ of the SV is unaffected. SV* sv_bless(SV* sv, HV* stash) +=for hackers +Found in file sv.c + =item sv_catpv Concatenates the string onto the end of the string which is in the SV. @@ -1678,6 +2488,9 @@ Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>. void sv_catpv(SV* sv, const char* ptr) +=for hackers +Found in file sv.c + =item sv_catpvf Processes its arguments like C<sprintf> and appends the formatted output @@ -1686,12 +2499,18 @@ typically be called after calling this function to handle 'set' magic. void sv_catpvf(SV* sv, const char* pat, ...) +=for hackers +Found in file sv.c + =item sv_catpvf_mg Like C<sv_catpvf>, but also handles 'set' magic. void sv_catpvf_mg(SV *sv, const char* pat, ...) +=for hackers +Found in file sv.c + =item sv_catpvn Concatenates the string onto the end of the string which is in the SV. The @@ -1700,31 +2519,47 @@ C<len> indicates number of bytes to copy. Handles 'get' magic, but not void sv_catpvn(SV* sv, const char* ptr, STRLEN len) +=for hackers +Found in file sv.c + =item sv_catpvn_mg Like C<sv_catpvn>, but also handles 'set' magic. void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len) +=for hackers +Found in file sv.c + =item sv_catpv_mg Like C<sv_catpv>, but also handles 'set' magic. void sv_catpv_mg(SV *sv, const char *ptr) +=for hackers +Found in file sv.c + =item sv_catsv -Concatenates the string from SV C<ssv> onto the end of the string in SV -C<dsv>. Handles 'get' magic, but not 'set' magic. See C<sv_catsv_mg>. +Concatenates the string from SV C<ssv> onto the end of the string in +SV C<dsv>. Modifies C<dsv> but not C<ssv>. Handles 'get' magic, but +not 'set' magic. See C<sv_catsv_mg>. void sv_catsv(SV* dsv, SV* ssv) +=for hackers +Found in file sv.c + =item sv_catsv_mg Like C<sv_catsv>, but also handles 'set' magic. void sv_catsv_mg(SV *dstr, SV *sstr) +=for hackers +Found in file sv.c + =item sv_chop Efficient removal of characters from the beginning of the string buffer. @@ -1734,6 +2569,19 @@ string. void sv_chop(SV* sv, char* ptr) +=for hackers +Found in file sv.c + +=item sv_clear + +Clear an SV, making it empty. Does not free the memory used by the SV +itself. + + void sv_clear(SV* sv) + +=for hackers +Found in file sv.c + =item sv_cmp Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the @@ -1742,12 +2590,28 @@ C<sv2>. I32 sv_cmp(SV* sv1, SV* sv2) +=for hackers +Found in file sv.c + +=item sv_cmp_locale + +Compares the strings in two SVs in a locale-aware manner. See +L</sv_cmp_locale> + + I32 sv_cmp_locale(SV* sv1, SV* sv2) + +=for hackers +Found in file sv.c + =item sv_dec Auto-decrement of the value in the SV. void sv_dec(SV* sv) +=for hackers +Found in file sv.c + =item sv_derived_from Returns a boolean indicating whether the SV is derived from the specified @@ -1756,6 +2620,9 @@ for class names as well as for objects. bool sv_derived_from(SV* sv, const char* name) +=for hackers +Found in file universal.c + =item sv_eq Returns a boolean indicating whether the strings in the two SVs are @@ -1763,6 +2630,28 @@ identical. I32 sv_eq(SV* sv1, SV* sv2) +=for hackers +Found in file sv.c + +=item sv_free + +Free the memory used by an SV. + + void sv_free(SV* sv) + +=for hackers +Found in file sv.c + +=item sv_gets + +Get a line from the filehandle and store it into the SV, optionally +appending to the currently-stored string. + + char* sv_gets(SV* sv, PerlIO* fp, I32 append) + +=for hackers +Found in file sv.c + =item sv_grow Expands the character buffer in the SV. This will use C<sv_unref> and will @@ -1771,12 +2660,18 @@ Use C<SvGROW>. char* sv_grow(SV* sv, STRLEN newlen) +=for hackers +Found in file sv.c + =item sv_inc Auto-increment of the value in the SV. void sv_inc(SV* sv) +=for hackers +Found in file sv.c + =item sv_insert Inserts a string at the specified offset/length within the SV. Similar to @@ -1784,6 +2679,9 @@ the Perl substr() function. void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen) +=for hackers +Found in file sv.c + =item sv_isa Returns a boolean indicating whether the SV is blessed into the specified @@ -1792,6 +2690,9 @@ an inheritance relationship. int sv_isa(SV* sv, const char* name) +=for hackers +Found in file sv.c + =item sv_isobject Returns a boolean indicating whether the SV is an RV pointing to a blessed @@ -1800,18 +2701,37 @@ will return false. int sv_isobject(SV* sv) +=for hackers +Found in file sv.c + =item sv_len Returns the length of the string in the SV. See also C<SvCUR>. STRLEN sv_len(SV* sv) +=for hackers +Found in file sv.c + +=item sv_len_utf8 + +Returns the number of characters in the string in an SV, counting wide +UTF8 bytes as a single character. + + STRLEN sv_len_utf8(SV* sv) + +=for hackers +Found in file sv.c + =item sv_magic Adds magic to an SV. void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen) +=for hackers +Found in file sv.c + =item sv_mortalcopy Creates a new SV which is a copy of the original SV. The new SV is marked @@ -1819,12 +2739,64 @@ as mortal. SV* sv_mortalcopy(SV* oldsv) +=for hackers +Found in file sv.c + =item sv_newmortal Creates a new SV which is mortal. The reference count of the SV is set to 1. SV* sv_newmortal() +=for hackers +Found in file sv.c + +=item sv_pvn_force + +Get a sensible string out of the SV somehow. + + char* sv_pvn_force(SV* sv, STRLEN* lp) + +=for hackers +Found in file sv.c + +=item sv_pvutf8n_force + +Get a sensible UTF8-encoded string out of the SV somehow. See +L</sv_pvn_force>. + + char* sv_pvutf8n_force(SV* sv, STRLEN* lp) + +=for hackers +Found in file sv.c + +=item sv_reftype + +Returns a string describing what the SV is a reference to. + + char* sv_reftype(SV* sv, int ob) + +=for hackers +Found in file sv.c + +=item sv_replace + +Make the first argument a copy of the second, then delete the original. + + void sv_replace(SV* sv, SV* nsv) + +=for hackers +Found in file sv.c + +=item sv_rvweaken + +Weaken a reference. + + SV* sv_rvweaken(SV *sv) + +=for hackers +Found in file sv.c + =item sv_setiv Copies an integer into the given SV. Does not handle 'set' magic. See @@ -1832,12 +2804,18 @@ C<sv_setiv_mg>. void sv_setiv(SV* sv, IV num) +=for hackers +Found in file sv.c + =item sv_setiv_mg Like C<sv_setiv>, but also handles 'set' magic. void sv_setiv_mg(SV *sv, IV i) +=for hackers +Found in file sv.c + =item sv_setnv Copies a double into the given SV. Does not handle 'set' magic. See @@ -1845,12 +2823,18 @@ C<sv_setnv_mg>. void sv_setnv(SV* sv, NV num) +=for hackers +Found in file sv.c + =item sv_setnv_mg Like C<sv_setnv>, but also handles 'set' magic. void sv_setnv_mg(SV *sv, NV num) +=for hackers +Found in file sv.c + =item sv_setpv Copies a string into an SV. The string must be null-terminated. Does not @@ -1858,6 +2842,9 @@ handle 'set' magic. See C<sv_setpv_mg>. void sv_setpv(SV* sv, const char* ptr) +=for hackers +Found in file sv.c + =item sv_setpvf Processes its arguments like C<sprintf> and sets an SV to the formatted @@ -1865,12 +2852,18 @@ output. Does not handle 'set' magic. See C<sv_setpvf_mg>. void sv_setpvf(SV* sv, const char* pat, ...) +=for hackers +Found in file sv.c + =item sv_setpvf_mg Like C<sv_setpvf>, but also handles 'set' magic. void sv_setpvf_mg(SV *sv, const char* pat, ...) +=for hackers +Found in file sv.c + =item sv_setpviv Copies an integer into the given SV, also updating its string value. @@ -1878,12 +2871,18 @@ Does not handle 'set' magic. See C<sv_setpviv_mg>. void sv_setpviv(SV* sv, IV num) +=for hackers +Found in file sv.c + =item sv_setpviv_mg Like C<sv_setpviv>, but also handles 'set' magic. void sv_setpviv_mg(SV *sv, IV iv) +=for hackers +Found in file sv.c + =item sv_setpvn Copies a string into an SV. The C<len> parameter indicates the number of @@ -1891,18 +2890,27 @@ bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>. void sv_setpvn(SV* sv, const char* ptr, STRLEN len) +=for hackers +Found in file sv.c + =item sv_setpvn_mg Like C<sv_setpvn>, but also handles 'set' magic. void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len) +=for hackers +Found in file sv.c + =item sv_setpv_mg Like C<sv_setpv>, but also handles 'set' magic. void sv_setpv_mg(SV *sv, const char *ptr) +=for hackers +Found in file sv.c + =item sv_setref_iv Copies an integer into a new SV, optionally blessing the SV. The C<rv> @@ -1913,6 +2921,9 @@ will be returned and will have a reference count of 1. SV* sv_setref_iv(SV* rv, const char* classname, IV iv) +=for hackers +Found in file sv.c + =item sv_setref_nv Copies a double into a new SV, optionally blessing the SV. The C<rv> @@ -1923,6 +2934,9 @@ will be returned and will have a reference count of 1. SV* sv_setref_nv(SV* rv, const char* classname, NV nv) +=for hackers +Found in file sv.c + =item sv_setref_pv Copies a pointer into a new SV, optionally blessing the SV. The C<rv> @@ -1939,6 +2953,9 @@ Note that C<sv_setref_pvn> copies the string while this copies the pointer. SV* sv_setref_pv(SV* rv, const char* classname, void* pv) +=for hackers +Found in file sv.c + =item sv_setref_pvn Copies a string into a new SV, optionally blessing the SV. The length of the @@ -1952,6 +2969,9 @@ Note that C<sv_setref_pv> copies the pointer while this copies the string. SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n) +=for hackers +Found in file sv.c + =item sv_setsv Copies the contents of the source SV C<ssv> into the destination SV C<dsv>. @@ -1961,12 +2981,18 @@ C<sv_setsv_mg>. void sv_setsv(SV* dsv, SV* ssv) +=for hackers +Found in file sv.c + =item sv_setsv_mg Like C<sv_setsv>, but also handles 'set' magic. void sv_setsv_mg(SV *dstr, SV *sstr) +=for hackers +Found in file sv.c + =item sv_setuv Copies an unsigned integer into the given SV. Does not handle 'set' magic. @@ -1974,12 +3000,36 @@ See C<sv_setuv_mg>. void sv_setuv(SV* sv, UV num) +=for hackers +Found in file sv.c + =item sv_setuv_mg Like C<sv_setuv>, but also handles 'set' magic. void sv_setuv_mg(SV *sv, UV u) +=for hackers +Found in file sv.c + +=item sv_true + +Returns true if the SV has a true value by Perl's rules. + + I32 sv_true(SV *sv) + +=for hackers +Found in file sv.c + +=item sv_unmagic + +Removes magic from an SV. + + int sv_unmagic(SV* sv, int type) + +=for hackers +Found in file sv.c + =item sv_unref Unsets the RV status of the SV, and decrements the reference count of @@ -1988,6 +3038,9 @@ as a reversal of C<newSVrv>. See C<SvROK_off>. void sv_unref(SV* sv) +=for hackers +Found in file sv.c + =item sv_upgrade Upgrade an SV to a more complex form. Use C<SvUPGRADE>. See @@ -1995,6 +3048,9 @@ C<svtype>. bool sv_upgrade(SV* sv, U32 mt) +=for hackers +Found in file sv.c + =item sv_usepvn Tells an SV to use C<ptr> to find its string value. Normally the string is @@ -2007,12 +3063,58 @@ See C<sv_usepvn_mg>. void sv_usepvn(SV* sv, char* ptr, STRLEN len) +=for hackers +Found in file sv.c + =item sv_usepvn_mg Like C<sv_usepvn>, but also handles 'set' magic. void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len) +=for hackers +Found in file sv.c + +=item sv_utf8_downgrade + +Attempt to convert the PV of an SV from UTF8-encoded to byte encoding. +This may not be possible if the PV contains non-byte encoding characters; +if this is the case, either returns false or, if C<fail_ok> is not +true, croaks. + +NOTE: this function is experimental and may change or be +removed without notice. + + bool sv_utf8_downgrade(SV *sv, bool fail_ok) + +=for hackers +Found in file sv.c + +=item sv_utf8_encode + +Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8> +flag so that it looks like bytes again. Nothing calls this. + +NOTE: this function is experimental and may change or be +removed without notice. + + void sv_utf8_encode(SV *sv) + +=for hackers +Found in file sv.c + +=item sv_utf8_upgrade + +Convert the PV of an SV to its UTF8-encoded form. + +NOTE: this function is experimental and may change or be +removed without notice. + + void sv_utf8_upgrade(SV *sv) + +=for hackers +Found in file sv.c + =item sv_vcatpvfn Processes its arguments like C<vsprintf> and appends the formatted output @@ -2023,6 +3125,9 @@ locales). void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) +=for hackers +Found in file sv.c + =item sv_vsetpvfn Works like C<vcatpvfn> but copies the text into the SV instead of @@ -2030,6 +3135,9 @@ appending it. void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) +=for hackers +Found in file sv.c + =item THIS Variable which is setup by C<xsubpp> to designate the object in a C++ @@ -2038,18 +3146,152 @@ L<perlxs/"Using XS With C++">. (whatever) THIS +=for hackers +Found in file XSUB.h + =item toLOWER Converts the specified character to lowercase. char toLOWER(char ch) +=for hackers +Found in file handy.h + =item toUPPER Converts the specified character to uppercase. char toUPPER(char ch) +=for hackers +Found in file handy.h + +=item utf8_distance + +Returns the number of UTF8 characters between the UTF-8 pointers C<a> +and C<b>. + +WARNING: use only if you *know* that the pointers point inside the +same UTF-8 buffer. + +NOTE: this function is experimental and may change or be +removed without notice. + + IV utf8_distance(U8 *a, U8 *b) + +=for hackers +Found in file utf8.c + +=item utf8_hop + +Return the UTF-8 pointer C<s> displaced by C<off> characters, either +forward or backward. + +WARNING: do not use the following unless you *know* C<off> is within +the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned +on the first byte of character or just after the last byte of a character. + +NOTE: this function is experimental and may change or be +removed without notice. + + U8* utf8_hop(U8 *s, I32 off) + +=for hackers +Found in file utf8.c + +=item utf8_length + +Return the length of the UTF-8 char encoded string C<s> in characters. +Stops at C<e> (inclusive). If C<e E<lt> s> or if the scan would end +up past C<e>, croaks. + +NOTE: this function is experimental and may change or be +removed without notice. + + STRLEN utf8_length(U8* s, U8 *e) + +=for hackers +Found in file utf8.c + +=item utf8_to_bytes + +Converts a string C<s> of length C<len> from UTF8 into byte encoding. +Unlike C<bytes_to_utf8>, this over-writes the original string, and +updates len to contain the new length. +Returns zero on failure, setting C<len> to -1. + +NOTE: this function is experimental and may change or be +removed without notice. + + U8* utf8_to_bytes(U8 *s, STRLEN *len) + +=for hackers +Found in file utf8.c + +=item utf8_to_uv + +Returns the character value of the first character in the string C<s> +which is assumed to be in UTF8 encoding and no longer than C<curlen>; +C<retlen> will be set to the length, in bytes, of that character. + +If C<s> does not point to a well-formed UTF8 character, the behaviour +is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY, +it is assumed that the caller will raise a warning, and this function +will silently just set C<retlen> to C<-1> and return zero. If the +C<flags> does not contain UTF8_CHECK_ONLY, warnings about +malformations will be given, C<retlen> will be set to the expected +length of the UTF-8 character in bytes, and zero will be returned. + +The C<flags> can also contain various flags to allow deviations from +the strict UTF-8 encoding (see F<utf8.h>). + +NOTE: this function is experimental and may change or be +removed without notice. + + UV utf8_to_uv(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags) + +=for hackers +Found in file utf8.c + +=item utf8_to_uv_simple + +Returns the character value of the first character in the string C<s> +which is assumed to be in UTF8 encoding; C<retlen> will be set to the +length, in bytes, of that character. + +If C<s> does not point to a well-formed UTF8 character, zero is +returned and retlen is set, if possible, to -1. + +NOTE: this function is experimental and may change or be +removed without notice. + + UV utf8_to_uv_simple(U8 *s, STRLEN* retlen) + +=for hackers +Found in file utf8.c + +=item uv_to_utf8 + +Adds the UTF8 representation of the Unicode codepoint C<uv> to the end +of the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free +bytes available. The return value is the pointer to the byte after the +end of the new character. In other words, + + d = uv_to_utf8(d, uv); + +is the recommended Unicode-aware way of saying + + *(d++) = uv; + +NOTE: this function is experimental and may change or be +removed without notice. + + U8* uv_to_utf8(U8 *d, UV uv) + +=for hackers +Found in file utf8.c + =item warn This is the XSUB-writer's interface to Perl's C<warn> function. Use this @@ -2058,6 +3300,9 @@ C<croak>. void warn(const char* pat, ...) +=for hackers +Found in file util.c + =item XPUSHi Push an integer onto the stack, extending the stack if necessary. Handles @@ -2065,6 +3310,9 @@ Push an integer onto the stack, extending the stack if necessary. Handles void XPUSHi(IV iv) +=for hackers +Found in file pp.h + =item XPUSHn Push a double onto the stack, extending the stack if necessary. Handles @@ -2072,6 +3320,9 @@ Push a double onto the stack, extending the stack if necessary. Handles void XPUSHn(NV nv) +=for hackers +Found in file pp.h + =item XPUSHp Push a string onto the stack, extending the stack if necessary. The C<len> @@ -2080,6 +3331,9 @@ C<PUSHp>. void XPUSHp(char* str, STRLEN len) +=for hackers +Found in file pp.h + =item XPUSHs Push an SV onto the stack, extending the stack if necessary. Does not @@ -2087,18 +3341,27 @@ handle 'set' magic. See C<PUSHs>. void XPUSHs(SV* sv) +=for hackers +Found in file pp.h + =item XPUSHu -Push an unsigned integer onto the stack, extending the stack if necessary. +Push an unsigned integer onto the stack, extending the stack if necessary. See C<PUSHu>. void XPUSHu(UV uv) +=for hackers +Found in file pp.h + =item XS Macro to declare an XSUB and its C parameter list. This is handled by C<xsubpp>. +=for hackers +Found in file XSUB.h + =item XSRETURN Return from XSUB, indicating number of items on the stack. This is usually @@ -2106,48 +3369,72 @@ handled by C<xsubpp>. void XSRETURN(int nitems) +=for hackers +Found in file XSUB.h + =item XSRETURN_EMPTY Return an empty list from an XSUB immediately. XSRETURN_EMPTY; +=for hackers +Found in file XSUB.h + =item XSRETURN_IV Return an integer from an XSUB immediately. Uses C<XST_mIV>. void XSRETURN_IV(IV iv) +=for hackers +Found in file XSUB.h + =item XSRETURN_NO Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>. XSRETURN_NO; +=for hackers +Found in file XSUB.h + =item XSRETURN_NV Return an double from an XSUB immediately. Uses C<XST_mNV>. void XSRETURN_NV(NV nv) +=for hackers +Found in file XSUB.h + =item XSRETURN_PV Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>. void XSRETURN_PV(char* str) +=for hackers +Found in file XSUB.h + =item XSRETURN_UNDEF Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>. XSRETURN_UNDEF; +=for hackers +Found in file XSUB.h + =item XSRETURN_YES Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>. XSRETURN_YES; +=for hackers +Found in file XSUB.h + =item XST_mIV Place an integer into the specified position C<pos> on the stack. The @@ -2155,6 +3442,9 @@ value is stored in a new mortal SV. void XST_mIV(int pos, IV iv) +=for hackers +Found in file XSUB.h + =item XST_mNO Place C<&PL_sv_no> into the specified position C<pos> on the @@ -2162,6 +3452,9 @@ stack. void XST_mNO(int pos) +=for hackers +Found in file XSUB.h + =item XST_mNV Place a double into the specified position C<pos> on the stack. The value @@ -2169,6 +3462,9 @@ is stored in a new mortal SV. void XST_mNV(int pos, NV nv) +=for hackers +Found in file XSUB.h + =item XST_mPV Place a copy of a string into the specified position C<pos> on the stack. @@ -2176,6 +3472,9 @@ The value is stored in a new mortal SV. void XST_mPV(int pos, char* str) +=for hackers +Found in file XSUB.h + =item XST_mUNDEF Place C<&PL_sv_undef> into the specified position C<pos> on the @@ -2183,6 +3482,9 @@ stack. void XST_mUNDEF(int pos) +=for hackers +Found in file XSUB.h + =item XST_mYES Place C<&PL_sv_yes> into the specified position C<pos> on the @@ -2190,11 +3492,17 @@ stack. void XST_mYES(int pos) +=for hackers +Found in file XSUB.h + =item XS_VERSION The version identifier for an XS module. This is usually handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>. +=for hackers +Found in file XSUB.h + =item XS_VERSION_BOOTCHECK Macro to verify that a PM module's $VERSION variable matches the XS @@ -2203,6 +3511,9 @@ C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">. XS_VERSION_BOOTCHECK; +=for hackers +Found in file XSUB.h + =item Zero The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the @@ -2210,6 +3521,9 @@ destination, C<nitems> is the number of items, and C<type> is the type. void Zero(void* dest, int nitems, type) +=for hackers +Found in file handy.h + =back =head1 AUTHORS diff --git a/contrib/perl5/pod/perlbook.pod b/contrib/perl5/pod/perlbook.pod index 3a693ddd8e54..44f0233ee1e1 100644 --- a/contrib/perl5/pod/perlbook.pod +++ b/contrib/perl5/pod/perlbook.pod @@ -4,12 +4,13 @@ perlbook - Perl book information =head1 DESCRIPTION -The Camel Book, officially known as I<Programming Perl, Second Edition>, -by Larry Wall et al, is the definitive reference work covering nearly -all of Perl. You can order it and other Perl books from O'Reilly & -Associates, 1-800-998-9938. Local/overseas is +1 707 829 0515. If you -can locate an O'Reilly order form, you can also fax to +1 707 829 0104. -If you're web-connected, you can even mosey on over to http://www.ora.com/ +The Camel Book, officially known as I<Programming Perl, Third Edition, +July 2000>, by Larry Wall et al, ISBN 0-596-00027-8, is the definitive +reference work covering nearly all of Perl. You can order it and +other Perl books from O'Reilly & Associates, 1-800-998-9938. +Local/overseas is +1 707 829 0515. If you can locate an O'Reilly +order form, you can also fax to +1 707 829 0104. If you're +web-connected, you can even mosey on over to http://www.oreilly.com/ for an online order form. Other Perl books from various publishers and authors diff --git a/contrib/perl5/pod/perlboot.pod b/contrib/perl5/pod/perlboot.pod index b549f45e490d..3c18246f0ca4 100644 --- a/contrib/perl5/pod/perlboot.pod +++ b/contrib/perl5/pod/perlboot.pod @@ -790,9 +790,13 @@ Hopefully, this gets you started, though. For more information, see L<perlobj> (for all the gritty details about Perl objects, now that you've seen the basics), L<perltoot> (the -tutorial for those who already know objects), L<perlbot> (for some -more tricks), and books such as Damian Conway's excellent I<Object -Oriented Perl>. +tutorial for those who already know objects), L<perltootc> (dealing +with class data), L<perlbot> (for some more tricks), and books such as +Damian Conway's excellent I<Object Oriented Perl>. + +Some modules which might prove interesting are Class::Accessor, +Class::Class, Class::Contract, Class::Data::Inheritable, +Class::MethodMaker and Tie::SecureHash =head1 COPYRIGHT diff --git a/contrib/perl5/pod/perlcall.pod b/contrib/perl5/pod/perlcall.pod index 148b24b51bdd..40f1d65a7beb 100644 --- a/contrib/perl5/pod/perlcall.pod +++ b/contrib/perl5/pod/perlcall.pod @@ -201,8 +201,8 @@ As with G_SCALAR, this flag has 2 effects: =item 1. -It indicates to the subroutine being called that it is executing in an -array context (if it executes I<wantarray> the result will be true). +It indicates to the subroutine being called that it is executing in a +list context (if it executes I<wantarray> the result will be true). =item 2. @@ -355,7 +355,7 @@ use of this flag. As mentioned above, you can determine the context of the currently executing subroutine in Perl with I<wantarray>. The equivalent test can be made in C by using the C<GIMME_V> macro, which returns -C<G_ARRAY> if you have been called in an array context, C<G_SCALAR> if +C<G_ARRAY> if you have been called in a list context, C<G_SCALAR> if in a scalar context, or C<G_VOID> if in a void context (i.e. the return value will not be used). An older version of this macro is called C<GIMME>; in a void context it returns C<G_SCALAR> instead of @@ -589,12 +589,6 @@ local copy, I<not> the global copy. =item 4. -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. - -=item 5. - 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. @@ -602,7 +596,7 @@ integer. See L<perlguts/"XSUBs and the Argument Stack"> for details on how the XPUSH macros work. -=item 6. +=item 5. 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. @@ -632,10 +626,12 @@ to limit the scope of local variables. See the section I<Using Perl to dispose of temporaries> for details of an alternative to using these macros. -=item 7. +=item 6. -Finally, I<LeftString> can now be called via the I<call_pv> -function. +Finally, I<LeftString> can now be called via the I<call_pv> 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. =back @@ -806,7 +802,7 @@ Notes =item 1. -We wanted array context, so G_ARRAY was used. +We wanted list context, so G_ARRAY was used. =item 2. diff --git a/contrib/perl5/pod/perlcompile.pod b/contrib/perl5/pod/perlcompile.pod index 697cb80d4096..282592e9fb16 100644 --- a/contrib/perl5/pod/perlcompile.pod +++ b/contrib/perl5/pod/perlcompile.pod @@ -183,9 +183,6 @@ one-liners: rename $was, $_ unless $was eq $_; } -(this is the I<rename> program that comes in the I<eg/> directory -of the Perl source distribution). - The decompiler has several options for the code it generates. For instance, you can set the size of each indent from 4 (as above) to 2 with: @@ -308,7 +305,7 @@ I<assemble> program that produces bytecode. This module is used by the B::CC back end. It walks "basic blocks". A basic block is a series of operations which is known to execute from -start to finish, with no possiblity of branching or halting. +start to finish, with no possibility of branching or halting. =item B::Bytecode @@ -369,12 +366,12 @@ can identify. See L</"The Lint Back End"> for details about usage. =item B::Showlex This module prints out the my() variables used in a function or a -file. To gt a list of the my() variables used in the subroutine +file. To get a list of the my() variables used in the subroutine mysub() defined in the file myperlprogram: $ perl -MO=Showlex,mysub myperlprogram -To gt a list of the my() variables used in the file myperlprogram: +To get a list of the my() variables used in the file myperlprogram: $ perl -MO=Showlex myperlprogram @@ -419,7 +416,7 @@ names. The optimized C backend outputs code for more modules than it should (e.g., DirHandle). It also has little hope of properly handling -C<goto LABEL> outside the running subroutine (C<goto &sub> is ok). +C<goto LABEL> outside the running subroutine (C<goto &sub> is okay). C<goto LABEL> currently does not work at all in this backend. It also creates a huge initialization function that gives C compilers headaches. Splitting the initialization function gives diff --git a/contrib/perl5/pod/perldata.pod b/contrib/perl5/pod/perldata.pod index ac444fa17c4f..315f716ed876 100644 --- a/contrib/perl5/pod/perldata.pod +++ b/contrib/perl5/pod/perldata.pod @@ -209,9 +209,9 @@ with a regular expression (as documented in L<perlre>). unless /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/; The length of an array is a scalar value. You may find the length -of array @days by evaluating C<$#days>, as in B<csh>. Technically -speaking, this isn't the length of the array; it's the subscript -of the last element, since there is ordinarily a 0th element. +of array @days by evaluating C<$#days>, as in B<csh>. 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 C<$#days> actually changes the length of the array. Shortening an array this way destroys intervening values. Lengthening an array that was previously shortened does not recover values @@ -259,7 +259,7 @@ of sixteen buckets has been touched, and presumably contains all 10,000 of your items. This isn't supposed to happen. You can preallocate space for a hash by assigning to the keys() function. -This rounds up the allocated bucked to the next power of two: +This rounds up the allocated buckets to the next power of two: keys(%users) = 1000; # allocate 1024 buckets @@ -303,7 +303,8 @@ price is $Z<>100." print "The price is $Price.\n"; # interpreted As in some shells, you can enclose the variable name in braces to -disambiguate it from following alphanumerics. You must also do +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: @@ -412,20 +413,20 @@ string may be either an identifier (a word), or some quoted text. If quoted, the type of quotes you use determines the treatment of the text, just as in regular quoting. An unquoted identifier works like double quotes. There must be no space between the C<< << >> and -the identifier. (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. +the identifier, unless the identifier is 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. print <<EOF; The price is $Price. EOF - print <<"EOF"; # same as above + print << "EOF"; # same as above The price is $Price. EOF - print <<`EOC`; # execute commands + print << `EOC`; # execute commands echo hi there echo lo there EOC @@ -436,7 +437,7 @@ surrounding whitespace) on the terminating line. I said bar. bar - myfunc(<<"THIS", 23, <<'THAT'); + myfunc(<< "THIS", 23, <<'THAT'); Here's a line or two. THIS @@ -461,6 +462,39 @@ from each line manually: down from the door where it began. FINIS +If you use a here-doc within a delimited construct, such as in C<s///eg>, +the quoted material must come on the lines following the final delimiter. +So instead of + + s/this/<<E . 'that' + the other + E + . 'more '/eg; + +you have to write + + s/this/<<E . 'that' + . 'more '/eg; + the other + E + +If the terminating identifier is on the last line of the program, you +must be sure there is a newline after it; otherwise, Perl will give the +warning B<Can't find string terminator "END" anywhere before EOF...>. + +Additionally, the quoting rules for the identifier are not related to +Perl's quoting rules -- C<q()>, C<qq()>, and the like are not supported +in place of C<''> and C<"">, and the only interpolation is for backslashing +the quoting character: + + print << "abc\"def"; + testing... + abc"def + +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. + =head2 List value constructors List values are denoted by separating individual values by commas @@ -523,6 +557,15 @@ 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. +This interpolation combines with the facts that the opening +and closing parentheses are optional (except necessary for +precedence) and lists may end with an optional comma to mean that +multiple commas within lists are legal syntax. The list C<1,,3> is a +concatenation of two lists, C<1,> and C<3>, the first of which ends +with that optional comma. C<1,,3> is C<(1,),(3)> is C<1,3> (And +similarly for C<1,,,3> is C<(1,),(,),3> is C<1,3> and so on.) Not that +we'd advise you to use this obfuscation. + A list value may also be subscripted like a normal array. You must put the list in parentheses to avoid ambiguity. For example: diff --git a/contrib/perl5/pod/perldbmfilter.pod b/contrib/perl5/pod/perldbmfilter.pod index 3350596aab83..8384999e6a78 100644 --- a/contrib/perl5/pod/perldbmfilter.pod +++ b/contrib/perl5/pod/perldbmfilter.pod @@ -124,7 +124,7 @@ 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: - $hash{12345} = "soemthing" ; + $hash{12345} = "something" ; 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 diff --git a/contrib/perl5/pod/perldebguts.pod b/contrib/perl5/pod/perldebguts.pod index b74f3efb6bab..20cc5460fd44 100644 --- a/contrib/perl5/pod/perldebguts.pod +++ b/contrib/perl5/pod/perldebguts.pod @@ -13,17 +13,17 @@ intimate with Perl's guts to understand. Caveat lector. 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 I<perl -Dxxx> command described in L<perlrun>, which are -usable only if a special Perl built per the instructions the +with the I<perl -Dxxx> command described in L<perlrun>, which is +usable only if a special Perl is built per the instructions in the F<INSTALL> podpage in the Perl source tree. For example, whenever you call Perl's built-in C<caller> function from the package DB, the arguments that the corresponding stack -frame was called with are copied to the the @DB::args array. The +frame was called with are copied to the @DB::args array. The general mechanisms is enabled by calling Perl with the B<-d> switch, the following additional features are enabled (cf. L<perlvar/$^P>): -=over +=over 4 =item * @@ -32,20 +32,22 @@ Perl inserts the contents of C<$ENV{PERL5DB}> (or C<BEGIN {require =item * -The array C<@{"_<$filename"}> holds the lines of $filename for all -files compiled by Perl. The same for C<eval>ed strings that contain +Each array C<@{"_<$filename"}> holds the lines of $filename for a +file compiled by Perl. The same for C<eval>ed strings that contain subroutines, or which are currently being executed. The $filename for C<eval>ed strings looks like C<(eval 34)>. Code assertions -in regexes look like C<(re_eval 19)>. +in regexes look like C<(re_eval 19)>. + +Values in this array are magical in numeric context: they compare +equal to zero only if the line is not breakable. =item * -The hash C<%{"_<$filename"}> contains breakpoints and actions keyed +Each hash C<%{"_<$filename"}> 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 F<perl5db.pl> have the form -C<"$break_condition\0$action">. Values in this hash are magical -in numeric context: they are zeros if the line is not breakable. +C<"$break_condition\0$action">. The same holds for evaluated strings that contain subroutines, or which are currently being executed. The $filename for C<eval>ed strings @@ -53,7 +55,7 @@ looks like C<(eval 34)> or C<(re_eval 19)>. =item * -The scalar C<${"_<$filename"}> contains C<"_<$filename">. This is +Each scalar C<${"_<$filename"}> contains C<"_<$filename">. This is also the case for evaluated strings that contain subroutines, or which are currently being executed. The $filename for C<eval>ed strings looks like C<(eval 34)> or C<(re_eval 19)>. @@ -154,7 +156,7 @@ L<perldebug/"Options"> for description of options parsed by C<DB::parse_options(string)>. The function C<DB::dump_trace(skip[, count])> skips the specified number of frames and returns a list containing information about the calling frames (all of them, if -C<count> is missing). Each entry is reference to a a hash with +C<count> is missing). Each entry is reference to a hash with keys C<context> (either C<.>, C<$>, or C<@>), C<sub> (subroutine name, or info about C<eval>), C<args> (C<undef> or a reference to an array), C<file>, and C<line>. @@ -400,7 +402,7 @@ shorter than 7 chars. The fields of interest which may appear in the last line are -=over +=over 4 =item C<anchored> I<STRING> C<at> I<POS> @@ -630,7 +632,7 @@ 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 prvide a good +astonished. This is not absolutely true, but may provide a good grasp of what happens. Assume that an integer cannot take less than 20 bytes of memory, a @@ -639,7 +641,7 @@ 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 make inflate these +20 bytes. A sloppy malloc(3) implementation can inflate these numbers dramatically. On the opposite end of the scale, a declaration like @@ -666,7 +668,7 @@ the top level of the Perl source tree. 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 hwen C<< $ENV{PERL_DEBUG_MSTATS} +usage statistics after compiling your code when C<< $ENV{PERL_DEBUG_MSTATS} > 1 >>, and before termination of the program when C<< $ENV{PERL_DEBUG_MSTATS} >= 1 >>. The report format is similar to the following example: @@ -686,12 +688,12 @@ the following example: Total sbrk(): 215040/47:145. Odd ends: pad+heads+chain+tail: 0+2192+0+6144. It is possible to ask for such a statistic at arbitrary points in -your execution using the mstats() function out of the standard +your execution using the mstat() function out of the standard Devel::Peek module. Here is some explanation of that format: -=over +=over 4 =item C<buckets SMALLEST(APPROX)..GREATEST(APPROX)> @@ -720,7 +722,7 @@ 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". -For example, suppose under the pervious example, the memory footprints +For example, suppose under the previous example, the memory footprints were free: 8 16 32 64 128 256 512 1024 2048 4096 8192 @@ -804,7 +806,7 @@ To see this list, insert two C<warn('!...')> statements around the call: do 'lib/auto/POSIX/autosplit.ix'; warn('!!! "after"'); -and run it with PErl's B<-DL> option. The first warn() will print +and run it with Perl's B<-DL> option. The first warn() will print memory allocation info before parsing the file and will memorize the statistics at this point (we ignore what it prints). The second warn() prints increments with respect to these memorized data. This @@ -838,11 +840,11 @@ per glob - for glob name, and glob stringification magic. Here are explanations for other I<Id>s above: -=over +=over 4 =item C<717> -CReates bigger C<XPV*> structures. In the case above, it +Creates bigger C<XPV*> structures. In the case above, it creates 3 C<AV>s per subroutine, one for a list of lexical variable names, one for a scratchpad (which contains lexical variables and C<targets>), and one for the array of scratchpads needed for @@ -892,7 +894,7 @@ these categories. If warn() string starts with -=over +=over 4 =item C<!!!> diff --git a/contrib/perl5/pod/perldebug.pod b/contrib/perl5/pod/perldebug.pod index c8ef60fa45ff..0aff91a558e0 100644 --- a/contrib/perl5/pod/perldebug.pod +++ b/contrib/perl5/pod/perldebug.pod @@ -82,7 +82,7 @@ recursively, unlike the real C<print> function in Perl. See L<Dumpvalue> if you'd like to do this yourself. The output format is governed by multiple options described under -L<"Options">. +L<"Configurable Options">. =item V [pkg [vars]] @@ -308,8 +308,8 @@ For historical reasons, the C<=value> 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 C<=>. The C<option> can be abbreviated, but for clarity probably should -not be. Several options can be set together. See L<"Options"> for -a list of these. +not be. Several options can be set together. See L<"Configurable Options"> +for a list of these. =item < ? @@ -342,7 +342,7 @@ missing, all actions are wiped out! 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 slackbashing the newlines. +command may be entered by backslashing the newlines. =item { ? @@ -465,6 +465,8 @@ working example of something along the lines of: The debugger has numerous options settable using the C<O> command, either interactively or from the environment or an rc file. +(./.perldb or ~/.perldb under Unix.) + =over 12 @@ -600,9 +602,11 @@ include lexicals in a module's file scope, or lost in closures. =back -During startup, options are initialized from C<$ENV{PERLDB_OPTS}>. -You may place the initialization options C<TTY>, C<noTTY>, -C<ReadLine>, and C<NonStop> there. +After the rc file is read, the debugger reads the C<$ENV{PERLDB_OPTS}> +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 C<TTY>, C<noTTY>, C<ReadLine>, and C<NonStop> +there. If your rc file contains: @@ -767,6 +771,11 @@ Breakable lines are marked with C<:>. Lines with breakpoints are marked by C<b> and those with actions by C<a>. The line that's about to be executed is marked by C<< ==> >>. +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. + =item Frame listing When the C<frame> option is set, the debugger would print entered (and diff --git a/contrib/perl5/pod/perldelta.pod b/contrib/perl5/pod/perldelta.pod index 4a1a14201e66..86235f03870d 100644 --- a/contrib/perl5/pod/perldelta.pod +++ b/contrib/perl5/pod/perldelta.pod @@ -1,16 +1,612 @@ =head1 NAME -perldelta - what's new for perl v5.6.0 +perldelta - what's new for perl v5.6.x =head1 DESCRIPTION -This document describes differences between the 5.005 release and this one. +This document describes differences between the 5.005 release and the 5.6.1 +release. +=head1 Summary of changes between 5.6.0 and 5.6.1 + +This section contains a summary of the changes between the 5.6.0 release +and the 5.6.1 release. More details about the changes mentioned here +may be found in the F<Changes> files that accompany the Perl source +distribution. See L<perlhack> for pointers to online resources where you +can inspect the individual patches described by these changes. + +=head2 Security Issues + +suidperl will not run /bin/mail anymore, because some platforms have +a /bin/mail that is vulnerable to buffer overflow attacks. + +Note that suidperl is neither built nor installed by default in +any recent version of perl. Use of suidperl is highly discouraged. +If you think you need it, try alternatives such as sudo first. +See http://www.courtesan.com/sudo/. + +=head2 Core bug fixes + +This is not an exhaustive list. It is intended to cover only the +significant user-visible changes. + +=over + +=item C<UNIVERSAL::isa()> + +A bug in the caching mechanism used by C<UNIVERSAL::isa()> that affected +base.pm has been fixed. The bug has existed since the 5.005 releases, +but wasn't tickled by base.pm in those releases. + +=item Memory leaks + +Various cases of memory leaks and attempts to access uninitialized memory +have been cured. See L</"Known Problems"> below for further issues. + +=item Numeric conversions + +Numeric conversions did not recognize changes in the string value +properly in certain circumstances. + +In other situations, large unsigned numbers (those above 2**31) could +sometimes lose their unsignedness, causing bogus results in arithmetic +operations. + +Integer modulus on large unsigned integers sometimes returned +incorrect values. + +Perl 5.6.0 generated "not a number" warnings on certain conversions where +previous versions didn't. + +These problems have all been rectified. + +Infinity is now recognized as a number. + +=item qw(a\\b) + +In Perl 5.6.0, qw(a\\b) produced a string with two backslashes instead +of one, in a departure from the behavior in previous versions. The +older behavior has been reinstated. + +=item caller() + +caller() could cause core dumps in certain situations. Carp was sometimes +affected by this problem. + +=item Bugs in regular expressions + +Pattern matches on overloaded values are now handled correctly. + +Perl 5.6.0 parsed m/\x{ab}/ incorrectly, leading to spurious warnings. +This has been corrected. + +The RE engine found in Perl 5.6.0 accidentally pessimised certain kinds +of simple pattern matches. These are now handled better. + +Regular expression debug output (whether through C<use re 'debug'> +or via C<-Dr>) now looks better. + +Multi-line matches like C<"a\nxb\n" =~ /(?!\A)x/m> were flawed. The +bug has been fixed. + +Use of $& could trigger a core dump under some situations. This +is now avoided. + +Match variables $1 et al., weren't being unset when a pattern match +was backtracking, and the anomaly showed up inside C</...(?{ ... }).../> +etc. These variables are now tracked correctly. + +pos() did not return the correct value within s///ge in earlier +versions. This is now handled correctly. + +=item "slurp" mode + +readline() on files opened in "slurp" mode could return an extra "" at +the end in certain situations. This has been corrected. + +=item Autovivification of symbolic references to special variables + +Autovivification of symbolic references of special variables described +in L<perlvar> (as in C<${$num}>) was accidentally disabled. This works +again now. + +=item Lexical warnings + +Lexical warnings now propagate correctly into C<eval "...">. + +C<use warnings qw(FATAL all)> did not work as intended. This has been +corrected. + +Lexical warnings could leak into other scopes in some situations. +This is now fixed. + +warnings::enabled() now reports the state of $^W correctly if the caller +isn't using lexical warnings. + +=item Spurious warnings and errors + +Perl 5.6.0 could emit spurious warnings about redefinition of dl_error() +when statically building extensions into perl. This has been corrected. + +"our" variables could result in bogus "Variable will not stay shared" +warnings. This is now fixed. + +"our" variables of the same name declared in two sibling blocks +resulted in bogus warnings about "redeclaration" of the variables. +The problem has been corrected. + +=item glob() + +Compatibility of the builtin glob() with old csh-based glob has been +improved with the addition of GLOB_ALPHASORT option. See C<File::Glob>. + +File::Glob::glob() has been renamed to File::Glob::bsd_glob() +because the name clashes with the builtin glob(). The older +name is still available for compatibility, but is deprecated. + +Spurious syntax errors generated in certain situations, when glob() +caused File::Glob to be loaded for the first time, have been fixed. + +=item Tainting + +Some cases of inconsistent taint propagation (such as within hash +values) have been fixed. + +The tainting behavior of sprintf() has been rationalized. It does +not taint the result of floating point formats anymore, making the +behavior consistent with that of string interpolation. + +=item sort() + +Arguments to sort() weren't being provided the right wantarray() context. +The comparison block is now run in scalar context, and the arguments to +be sorted are always provided list context. + +sort() is also fully reentrant, in the sense that the sort function +can itself call sort(). This did not work reliably in previous releases. + +=item #line directives + +#line directives now work correctly when they appear at the very +beginning of C<eval "...">. + +=item Subroutine prototypes + +The (\&) prototype now works properly. + +=item map() + +map() could get pathologically slow when the result list it generates +is larger than the source list. The performance has been improved for +common scenarios. + +=item Debugger + +Debugger exit code now reflects the script exit code. + +Condition C<"0"> in breakpoints is now treated correctly. + +The C<d> command now checks the line number. + +C<$.> is no longer corrupted by the debugger. + +All debugger output now correctly goes to the socket if RemotePort +is set. + +=item PERL5OPT + +PERL5OPT can be set to more than one switch group. Previously, +it used to be limited to one group of options only. + +=item chop() + +chop(@list) in list context returned the characters chopped in reverse +order. This has been reversed to be in the right order. + +=item Unicode support + +Unicode support has seen a large number of incremental improvements, +but continues to be highly experimental. It is not expected to be +fully supported in the 5.6.x maintenance releases. + +substr(), join(), repeat(), reverse(), quotemeta() and string +concatenation were all handling Unicode strings incorrectly in +Perl 5.6.0. This has been corrected. + +Support for C<tr///CU> and C<tr///UC> etc., have been removed since +we realized the interface is broken. For similar functionality, +see L<perlfunc/pack>. + +The Unicode Character Database has been updated to version 3.0.1 +with additions made available to the public as of August 30, 2000. + +The Unicode character classes \p{Blank} and \p{SpacePerl} have been +added. "Blank" is like C isblank(), that is, it contains only +"horizontal whitespace" (the space character is, the newline isn't), +and the "SpacePerl" is the Unicode equivalent of C<\s> (\p{Space} +isn't, since that includes the vertical tabulator character, whereas +C<\s> doesn't.) + +If you are experimenting with Unicode support in perl, the development +versions of Perl may have more to offer. In particular, I/O layers +are now available in the development track, but not in the maintenance +track, primarily to do backward compatibility issues. Unicode support +is also evolving rapidly on a daily basis in the development track--the +maintenance track only reflects the most conservative of these changes. + +=item 64-bit support + +Support for 64-bit platforms has been improved, but continues to be +experimental. The level of support varies greatly among platforms. + +=item Compiler + +The B Compiler and its various backends have had many incremental +improvements, but they continue to remain highly experimental. Use in +production environments is discouraged. + +The perlcc tool has been rewritten so that the user interface is much +more like that of a C compiler. + +The perlbc tools has been removed. Use C<perlcc -B> instead. + +=item Lvalue subroutines + +There have been various bugfixes to support lvalue subroutines better. +However, the feature still remains experimental. + +=item IO::Socket + +IO::Socket::INET failed to open the specified port if the service +name was not known. It now correctly uses the supplied port number +as is. + +=item File::Find + +File::Find now chdir()s correctly when chasing symbolic links. + +=item xsubpp + +xsubpp now tolerates embedded POD sections. + +=item C<no Module;> + +C<no Module;> does not produce an error even if Module does not have an +unimport() method. This parallels the behavior of C<use> vis-a-vis +C<import>. + +=item Tests + +A large number of tests have been added. + +=back + +=head2 Core features + +untie() will now call an UNTIE() hook if it exists. See L<perltie> +for details. + +The C<-DT> command line switch outputs copious tokenizing information. +See L<perlrun>. + +Arrays are now always interpolated in double-quotish strings. Previously, +C<"foo@bar.com"> used to be a fatal error at compile time, if an array +C<@bar> was not used or declared. This transitional behavior was +intended to help migrate perl4 code, and is deemed to be no longer useful. +See L</"Arrays now always interpolate into double-quoted strings">. + +keys(), each(), pop(), push(), shift(), splice() and unshift() +can all be overridden now. + +C<my __PACKAGE__ $obj> now does the expected thing. + +=head2 Configuration issues + +On some systems (IRIX and Solaris among them) the system malloc is demonstrably +better. While the defaults haven't been changed in order to retain binary +compatibility with earlier releases, you may be better off building perl +with C<Configure -Uusemymalloc ...> as discussed in the F<INSTALL> file. + +C<Configure> has been enhanced in various ways: + +=over + +=item * + +Minimizes use of temporary files. + +=item * + +By default, does not link perl with libraries not used by it, such as +the various dbm libraries. SunOS 4.x hints preserve behavior on that +platform. + +=item * + +Support for pdp11-style memory models has been removed due to obsolescence. + +=item * + +Building outside the source tree is supported on systems that have +symbolic links. This is done by running + + sh /path/to/source/Configure -Dmksymlinks ... + make all test install + +in a directory other than the perl source directory. See F<INSTALL>. + +=item * + +C<Configure -S> can be run non-interactively. + +=back + +=head2 Documentation + +README.aix, README.solaris and README.macos have been added. README.posix-bc +has been renamed to README.bs2000. These are installed as L<perlaix>, +L<perlsolaris>, L<perlmacos>, and L<perlbs2000> respectively. + +The following pod documents are brand new: + + perlclib Internal replacements for standard C library functions + perldebtut Perl debugging tutorial + perlebcdic Considerations for running Perl on EBCDIC platforms + perlnewmod Perl modules: preparing a new module for distribution + perlrequick Perl regular expressions quick start + perlretut Perl regular expressions tutorial + perlutil utilities packaged with the Perl distribution + +The F<INSTALL> file has been expanded to cover various issues, such as +64-bit support. + +A longer list of contributors has been added to the source distribution. +See the file C<AUTHORS>. + +Numerous other changes have been made to the included documentation and FAQs. + +=head2 Bundled modules + +The following modules have been added. + +=over + +=item B::Concise + +Walks Perl syntax tree, printing concise info about ops. See L<B::Concise>. + +=item File::Temp + +Returns name and handle of a temporary file safely. See L<File::Temp>. + +=item Pod::LaTeX + +Converts Pod data to formatted LaTeX. See L<Pod::LaTeX>. + +=item Pod::Text::Overstrike + +Converts POD data to formatted overstrike text. See L<Pod::Text::Overstrike>. + +=back + +The following modules have been upgraded. + +=over + +=item CGI + +CGI v2.752 is now included. + +=item CPAN + +CPAN v1.59_54 is now included. + +=item Class::Struct + +Various bugfixes have been added. + +=item DB_File + +DB_File v1.75 supports newer Berkeley DB versions, among other +improvements. + +=item Devel::Peek + +Devel::Peek has been enhanced to support dumping of memory statistics, +when perl is built with the included malloc(). + +=item File::Find + +File::Find now supports pre and post-processing of the files in order +to sort() them, etc. + +=item Getopt::Long + +Getopt::Long v2.25 is included. + +=item IO::Poll + +Various bug fixes have been included. + +=item IPC::Open3 + +IPC::Open3 allows use of numeric file descriptors. + +=item Math::BigFloat + +The fmod() function supports modulus operations. Various bug fixes +have also been included. + +=item Math::Complex + +Math::Complex handles inf, NaN etc., better. + +=item Net::Ping + +ping() could fail on odd number of data bytes, and when the echo service +isn't running. This has been corrected. + +=item Opcode + +A memory leak has been fixed. + +=item Pod::Parser + +Version 1.13 of the Pod::Parser suite is included. + +=item Pod::Text + +Pod::Text and related modules have been upgraded to the versions +in podlators suite v2.08. + +=item SDBM_File + +On dosish platforms, some keys went missing because of lack of support for +files with "holes". A workaround for the problem has been added. + +=item Sys::Syslog + +Various bug fixes have been included. + +=item Tie::RefHash + +Now supports Tie::RefHash::Nestable to automagically tie hashref values. + +=item Tie::SubstrHash + +Various bug fixes have been included. + +=back + +=head2 Platform-specific improvements + +The following new ports are now available. + +=over + +=item NCR MP-RAS + +=item NonStop-UX + +=back + +Perl now builds under Amdahl UTS. + +Perl has also been verified to build under Amiga OS. + +Support for EPOC has been much improved. See README.epoc. + +Building perl with -Duseithreads or -Duse5005threads now works +under HP-UX 10.20 (previously it only worked under 10.30 or later). +You will need a thread library package installed. See README.hpux. + +Long doubles should now work under Linux. + +MacOS Classic is now supported in the mainstream source package. +See README.macos. + +Support for MPE/iX has been updated. See README.mpeix. + +Support for OS/2 has been improved. See C<os2/Changes> and README.os2. + +Dynamic loading on z/OS (formerly OS/390) has been improved. See +README.os390. + +Support for VMS has seen many incremental improvements, including +better support for operators like backticks and system(), and better +%ENV handling. See C<README.vms> and L<perlvms>. + +Support for Stratus VOS has been improved. See C<vos/Changes> and README.vos. + +Support for Windows has been improved. + +=over + +=item * + +fork() emulation has been improved in various ways, but still continues +to be experimental. See L<perlfork> for known bugs and caveats. + +=item * + +%SIG has been enabled under USE_ITHREADS, but its use is completely +unsupported under all configurations. + +=item * + +Borland C++ v5.5 is now a supported compiler that can build Perl. +However, the generated binaries continue to be incompatible with those +generated by the other supported compilers (GCC and Visual C++). + +=item * + +Non-blocking waits for child processes (or pseudo-processes) are +supported via C<waitpid($pid, &POSIX::WNOHANG)>. + +=item * + +A memory leak in accept() has been fixed. + +=item * + +wait(), waitpid() and backticks now return the correct exit status under +Windows 9x. + +=item * + +Trailing new %ENV entries weren't propagated to child processes. This +is now fixed. + +=item * + +Current directory entries in %ENV are now correctly propagated to child +processes. + +=item * + +Duping socket handles with open(F, ">&MYSOCK") now works under Windows 9x. + +=item * + +The makefiles now provide a single switch to bulk-enable all the features +enabled in ActiveState ActivePerl (a popular binary distribution). + +=item * + +Win32::GetCwd() correctly returns C:\ instead of C: when at the drive root. +Other bugs in chdir() and Cwd::cwd() have also been fixed. + +=item * + +fork() correctly returns undef and sets EAGAIN when it runs out of +pseudo-process handles. + +=item * + +ExtUtils::MakeMaker now uses $ENV{LIB} to search for libraries. + +=item * + +UNC path handling is better when perl is built to support fork(). + +=item * + +A handle leak in socket handling has been fixed. + +=item * + +send() works from within a pseudo-process. + +=back + +Unless specifically qualified otherwise, the remainder of this document +covers changes between the 5.005 and 5.6.0 releases. + =head1 Core Enhancements =head2 Interpreter cloning, threads, and concurrency -Perl 5.005_63 introduces the beginnings of support for running multiple +Perl 5.6.0 introduces the beginnings of support for running multiple interpreters concurrently in different threads. In conjunction with the perl_clone() API call, which can be used to selectively duplicate the state of any given interpreter, it is possible to compile a @@ -76,7 +672,7 @@ will be needed to complete the toolkit for dealing with Unicode. The new C<\N> escape interpolates named characters within strings. For example, C<"Hi! \N{WHITE SMILING FACE}"> evaluates to a string -with a unicode smiley face at the end. +with a Unicode smiley face at the end. =head2 "our" declarations @@ -91,7 +687,7 @@ variables. See L<perlfunc/our>. Literals of the form C<v1.2.3.4> are now parsed as a string composed of characters with the specified ordinals. This is an alternative, more -readable way to construct (possibly unicode) strings instead of +readable way to construct (possibly Unicode) strings instead of interpolating characters, as in C<"\x{1}\x{2}\x{3}\x{4}">. The leading C<v> may be omitted if there are more than two ordinals, so C<1.2.3> is parsed the same as C<v1.2.3>. @@ -375,7 +971,7 @@ problems associated with it. NOTE: This is currently an experimental feature. Interfaces and implementation are subject to change. -=item Support for CHECK blocks +=head2 Support for CHECK blocks In addition to C<BEGIN>, C<INIT>, C<END>, C<DESTROY> and C<AUTOLOAD>, subroutines named C<CHECK> are now special. These are queued up during @@ -388,7 +984,7 @@ be called directly. For example to match alphabetic characters use /[[:alpha:]]/. See L<perlre> for details. -=item Better pseudo-random number generator +=head2 Better pseudo-random number generator In 5.005_0x and earlier, perl's rand() function used the C library rand(3) function. As of 5.005_52, Configure tests for drand48(), @@ -409,7 +1005,7 @@ Thus: now correctly prints "3|a", instead of "2|a". -=item Better worst-case behavior of hashes +=head2 Better worst-case behavior of hashes Small changes in the hashing algorithm have been implemented in order to improve the distribution of lower order bits in the @@ -506,7 +1102,7 @@ If the array is tied, the EXISTS() method in the corresponding tied package will be invoked. delete() may be used to remove an element from the array and return -it. The array element at that position returns to its unintialized +it. The array element at that position returns to its uninitialized state, so that testing for the same element with exists() will return false. If the element happens to be the one at the end, the size of the array also shrinks up to the highest element that tests true for @@ -632,7 +1228,7 @@ Diagnostic output now goes to whichever file the C<STDERR> handle is pointing at, instead of always going to the underlying C runtime library's C<stderr>. -=item More consistent close-on-exec behavior +=head2 More consistent close-on-exec behavior On systems that support a close-on-exec flag on filehandles, the flag is now set for any handles created by pipe(), socketpair(), @@ -693,7 +1289,7 @@ The variable modified by shmread(), and messages returned by msgrcv() because other untrusted processes can modify messages and shared memory segments for their own nefarious purposes. -=item More functional bareword prototype (*) +=head2 More functional bareword prototype (*) Bareword prototypes have been rationalized to enable them to be used to override builtins that accept barewords and interpret them in @@ -760,6 +1356,37 @@ with another number. This behavior must be specifically enabled when running Configure. See F<INSTALL> and F<README.Y2K>. +=head2 Arrays now always interpolate into double-quoted strings + +In double-quoted strings, arrays now interpolate, no matter what. The +behavior in earlier versions of perl 5 was that arrays would interpolate +into strings if the array had been mentioned before the string was +compiled, and otherwise Perl would raise a fatal compile-time error. +In versions 5.000 through 5.003, the error was + + Literal @example now requires backslash + +In versions 5.004_01 through 5.6.0, the error was + + In string, @example now must be written as \@example + +The idea here was to get people into the habit of writing +C<"fred\@example.com"> when they wanted a literal C<@> sign, just as +they have always written C<"Give me back my \$5"> when they wanted a +literal C<$> sign. + +Starting with 5.6.1, when Perl now sees an C<@> sign in a +double-quoted string, it I<always> attempts to interpolate an array, +regardless of whether or not the array has been used or declared +already. The fatal error has been downgraded to an optional warning: + + Possible unintended interpolation of @example in string + +This warns you that C<"fred@example.com"> is going to turn into +C<fred.com> if you don't backslash the C<@>. +See http://www.plover.com/~mjd/perl/at-error.html for more details +about the history here. + =head1 Modules and Pragmata =head2 Modules @@ -780,7 +1407,7 @@ under the Compiler, but there is still a significant way to go to achieve production quality compiled executables. NOTE: The Compiler suite remains highly experimental. The - generated code may not be correct, even it manages to execute + generated code may not be correct, even when it manages to execute without errors. =item Benchmark @@ -1007,7 +1634,7 @@ messages. For example: =head1 DESCRIPTION - B<This program> will read the given input file(s) and do someting + B<This program> will read the given input file(s) and do something useful with the contents thereof. =cut @@ -1039,7 +1666,7 @@ IO::Socket::accept now uses select() instead of alarm() for doing timeouts. IO::Socket::INET->new now sets $! correctly on failure. $@ is -still set for backwards compatability. +still set for backwards compatibility. =item JPL @@ -1409,7 +2036,7 @@ eliminating redundant copying overheads. Minor changes in how subroutine calls are handled internally provide marginal improvements in performance. -=item delete(), each(), values() and hash iteration are faster +=head2 delete(), each(), values() and hash iteration are faster The hash values returned by delete(), each(), values() and hashes in a list context are the actual values in the hash, instead of copies. @@ -1518,6 +2145,13 @@ config.sh file from an earlier version of perl, you should be sure to check that Configure makes sensible choices for the new directories. See INSTALL for complete details. +=head2 gcc automatically tried if 'cc' does not seem to be working + +In many platforms the vendor-supplied 'cc' is too stripped-down to +build Perl (basically, the 'cc' doesn't do ANSI C). If this seems +to be the case and the 'cc' does not seem to be the GNU C compiler +'gcc', an automatic attempt is made to find and use 'gcc' instead. + =head1 Platform specific changes =head2 Supported platforms @@ -1526,14 +2160,6 @@ See INSTALL for complete details. =item * -VM/ESA is now supported. - -=item * - -Siemens BS2000 is now supported under the POSIX Shell. - -=item * - The Mach CThreads (NEXTSTEP, OPENSTEP) are now supported by the Thread extension. @@ -1547,7 +2173,7 @@ Rhapsody/Darwin is now supported. =item * -EPOC is is now supported (on Psion 5). +EPOC is now supported (on Psion 5). =item * @@ -1590,7 +2216,7 @@ platform, but the possibility exists. =head2 VMS Numerous revisions and extensions to configuration, build, testing, and -installation process to accomodate core changes and VMS-specific options. +installation process to accommodate core changes and VMS-specific options. Expand %ENV-handling code to allow runtime mapping to logical names, CLI symbols, and CRTL environ array. @@ -1703,7 +2329,7 @@ been fixed. =head2 All compilation errors are true errors -Some "errors" encountered at compile time were by neccessity +Some "errors" encountered at compile time were by necessity generated as warnings followed by eventual termination of the program. This enabled more such errors to be reported in a single run, rather than causing a hard stop at the first error @@ -1811,9 +2437,10 @@ cause silent failures. This has been fixed. Prior versions used to run BEGIN B<and> END blocks when Perl was run in compile-only mode. Since this is typically not the expected behavior, END blocks are not executed anymore when the C<-c> switch -is used. +is used, or if compilation fails. -See L<CHECK blocks> for how to run things when the compile phase ends. +See L</"Support for CHECK blocks"> for how to run things when the compile +phase ends. =head2 Potential to leak DATA filehandles @@ -2155,7 +2782,7 @@ L<perlport> for more on portability concerns. (W internal) A warning peculiar to VMS. Perl tried to read the CRTL's internal environ array, and encountered an element without the C<=> delimiter -used to spearate keys from values. The element is ignored. +used to separate keys from values. The element is ignored. =item Ill-formed message in prime_env_iter: |%s| @@ -2306,6 +2933,20 @@ when you meant Remember that "my", "our", and "local" bind tighter than comma. +=item Possible unintended interpolation of %s in string + +(W ambiguous) It used to be that Perl would try to guess whether you +wanted an array interpolated or a literal @. It no longer does this; +arrays are now I<always> interpolated into strings. This means that +if you try something like: + + print "fred@example.com"; + +and the array C<@example> doesn't exist, Perl is going to print +C<fred.com>, which is probably not what you wanted. To get a literal +C<@> sign in a string, put a backslash before it, just as you would +to get a literal C<$> sign. + =item Possible Y2K bug: %s (W y2k) You are concatenating the number 19 with another number, which @@ -2313,7 +2954,7 @@ could be a potential Year 2000 problem. =item pragma "attrs" is deprecated, use "sub NAME : ATTRS" instead -(W deprecated) You have written somehing like this: +(W deprecated) You have written something like this: sub doit { @@ -2530,7 +3171,7 @@ There is a potential incompatibility in the behavior of list slices that are comprised entirely of undefined values. See L</"Behavior of list slices is more consistent">. -=head2 Format of $English::PERL_VERSION is different +=item Format of $English::PERL_VERSION is different The English module now sets $PERL_VERSION to $^V (a string value) rather than C<$]> (a numeric value). This is a potential incompatibility. @@ -2592,9 +3233,12 @@ but still allowed it. In Perl 5.6.0 and later, C<"$$1"> always means C<"${$1}">. -=item delete(), values() and C<\(%h)> operate on aliases to values, not copies +=item delete(), each(), values() and C<\(%h)> + +operate on aliases to values, not copies -delete(), each(), values() and hashes in a list context return the actual +delete(), each(), values() and hashes (e.g. C<\(%h)>) +in a list context return the actual values in the hash, instead of copies (as they used to in earlier versions). Typical idioms for using these constructs copy the returned values, but this can make a significant difference when @@ -2655,7 +3299,7 @@ a simple scalar or as a reference to a typeglob. See L</"More functional bareword prototype (*)">. -=head2 Semantics of bit operators may have changed on 64-bit platforms +=item Semantics of bit operators may have changed on 64-bit platforms If your platform is either natively 64-bit or if Perl has been configured to used 64-bit integers, i.e., $Config{ivsize} is 8, @@ -2669,7 +3313,7 @@ the excess bits in the result of unary C<~>, e.g., C<~$x & 0xffffffff>. See L</"Bit operators support full native integer width">. -=head2 More builtins taint their results +=item More builtins taint their results As described in L</"Improved security features">, there may be more sources of taint in a Perl program. @@ -2744,7 +3388,7 @@ See L<perlguts/"Memory Allocation"> for further information about that. =head2 Compatible C Source API Changes -=over +=over 4 =item C<PATCHLEVEL> is now C<PERL_VERSION> @@ -2784,21 +3428,26 @@ For the full list of public API functions, see L<perlapi>. =head1 Known Problems -=head2 Thread test failures +=head2 Localizing a tied hash element may leak memory -The subtests 19 and 20 of lib/thr5005.t test are known to fail due to -fundamental problems in the 5.005 threading implementation. These are -not new failures--Perl 5.005_0x has the same bugs, but didn't have these -tests. +As of the 5.6.1 release, there is a known leak when code such as this +is executed: -=head2 EBCDIC platforms not supported + use Tie::Hash; + tie my %tie_hash => 'Tie::StdHash'; -In earlier releases of Perl, EBCDIC environments like OS390 (also -known as Open Edition MVS) and VM-ESA were supported. Due to changes -required by the UTF-8 (Unicode) support, the EBCDIC platforms are not -supported in Perl 5.6.0. + ... + + local($tie_hash{Foo}) = 1; # leaks -=head2 In 64-bit HP-UX the lib/io_multihomed test may hang +=head2 Known test failures + +=over + +=item 64-bit builds + +Subtest #15 of lib/b.t may fail under 64-bit builds on platforms such +as HP-UX PA64 and Linux IA64. The issue is still being investigated. The lib/io_multihomed test may hang in HP-UX if Perl has been configured to be 64-bit. Because other 64-bit platforms do not @@ -2806,19 +3455,40 @@ hang in this test, HP-UX is suspect. All other tests pass in 64-bit HP-UX. The test attempts to create and connect to "multihomed" sockets (sockets which have multiple IP addresses). -=head2 NEXTSTEP 3.3 POSIX test failure +Note that 64-bit support is still experimental. + +=item Failure of Thread tests + +The subtests 19 and 20 of lib/thr5005.t test are known to fail due to +fundamental problems in the 5.005 threading implementation. These are +not new failures--Perl 5.005_0x has the same bugs, but didn't have these +tests. (Note that support for 5.005-style threading remains experimental.) + +=item NEXTSTEP 3.3 POSIX test failure In NEXTSTEP 3.3p2 the implementation of the strftime(3) in the operating system libraries is buggy: the %j format numbers the days of a month starting from zero, which, while being logical to programmers, will cause the subtests 19 to 27 of the lib/posix test may fail. -=head2 Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc +=item Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc If compiled with gcc 2.95 the lib/sdbm test will fail (dump core). The cure is to use the vendor cc, it comes with the operating system and produces good code. +=back + +=head2 EBCDIC platforms not fully supported + +In earlier releases of Perl, EBCDIC environments like OS390 (also +known as Open Edition MVS) and VM-ESA were supported. Due to changes +required by the UTF-8 (Unicode) support, the EBCDIC platforms are not +supported in Perl 5.6.0. + +The 5.6.1 release improves support for EBCDIC platforms, but they +are not fully supported yet. + =head2 UNICOS/mk CC failures during Configure run In UNICOS/mk the following errors may appear during the Configure run: @@ -2847,11 +3517,6 @@ operation must be considered erroneous. For example: These expressions will get run-time errors in some future release of Perl. -=head2 Windows 2000 - -Windows 2000 is known to fail test 22 in lib/open3.t (cause unknown at -this time). That test passes under Windows NT. - =head2 Experimental features As discussed above, many features are still experimental. Interfaces and @@ -2879,7 +3544,9 @@ include the following: =item The DB module -=item The regular expression constructs C<(?{ code })> and C<(??{ code })> +=item The regular expression code constructs: + +C<(?{ code })> and C<(??{ code })> =back @@ -2904,6 +3571,18 @@ appear in %ENV. This may be a benign occurrence, as some software packages might directly modify logical name tables and introduce nonstandard names, or it may indicate that a logical name table has been corrupted. +=item In string, @%s now must be written as \@%s + +The description of this error used to say: + + (Someday it will simply assume that an unbackslashed @ + interpolates an array.) + +That day has come, and this fatal error has been removed. It has been +replaced by a non-fatal warning instead. +See L</Arrays now always interpolate into double-quoted strings> for +details. + =item Probable precedence problem on %s (W) The compiler found a bareword where it expected a conditional, @@ -2938,13 +3617,13 @@ warning. And in Perl 5.005, this special treatment will cease. If you find what you think is a bug, you might check the articles recently posted to the comp.lang.perl.misc newsgroup. -There may also be information at http://www.perl.com/perl/, the Perl +There may also be information at http://www.perl.com/, the Perl Home Page. If you believe you have an unreported bug, please run the B<perlbug> program included with your release. Be sure to trim your bug down to a tiny but sufficient test case. Your bug report, along with the -output of C<perl -V>, will be sent off to perlbug@perl.com to be +output of C<perl -V>, will be sent off to perlbug@perl.org to be analysed by the Perl porting team. =head1 SEE ALSO @@ -2959,9 +3638,9 @@ The F<Artistic> and F<Copying> files for copyright information. =head1 HISTORY -Written by Gurusamy Sarathy <F<gsar@activestate.com>>, with many +Written by Gurusamy Sarathy <F<gsar@ActiveState.com>>, with many contributions from The Perl Porters. -Send omissions or corrections to <F<perlbug@perl.com>>. +Send omissions or corrections to <F<perlbug@perl.org>>. =cut diff --git a/contrib/perl5/pod/perldiag.pod b/contrib/perl5/pod/perldiag.pod index 9ed75526044a..b842c1c5eaec 100644 --- a/contrib/perl5/pod/perldiag.pod +++ b/contrib/perl5/pod/perldiag.pod @@ -15,8 +15,8 @@ desperation): (X) A very fatal error (nontrappable). (A) An alien error message (not generated by Perl). -The majority of messages from the first three classifications above (W, -D & S) can be controlled using the C<warnings> pragma. +The majority of messages from the first three classifications above +(W, D & S) can be controlled using the C<warnings> pragma. If a message can be controlled by the C<warnings> pragma, its warning category is included with the classification letter in the description @@ -35,116 +35,94 @@ L<perlfunc/eval>. In almost all cases, warnings may be selectively disabled or promoted to fatal errors using the C<warnings> pragma. See L<warnings>. -Some of these messages are generic. Spots that vary are denoted with a %s, -just as in a printf format. Note that some messages start with a %s! -Since the messages are listed in alphabetical order, the symbols -C<"%(-?@> sort before the letters, while C<[> and C<\> sort after. +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. =over 4 -=item "%s" variable %s masks earlier declaration in same %s - -(W misc) A "my" or "our" variable has been redeclared in the current scope or statement, -effectively eliminating all access to the previous instance. This is almost -always a typographical error. Note that the earlier variable will still exist -until the end of the scope or until all closure referents to it are -destroyed. - -=item "my sub" not yet implemented - -(F) Lexically scoped subroutines are not yet implemented. Don't try that -yet. - -=item "my" variable %s can't be in a package - -(F) Lexically scoped variables aren't in a package, so it doesn't make sense -to try to declare one with a package qualifier on the front. Use local() -if you want to localize a package variable. - -=item "no" not allowed in expression - -(F) The "no" keyword is recognized and executed at compile time, and returns -no useful value. See L<perlmod>. - -=item "our" variable %s redeclared +=item accept() on closed socket %s -(W misc) You seem to have already declared the same global once before in the -current lexical scope. +(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 +L<perlfunc/accept>. -=item "use" not allowed in expression +=item Allocation too large: %lx -(F) The "use" keyword is recognized and executed at compile time, and returns -no useful value. See L<perlmod>. +(X) You can't allocate more than 64K on an MS-DOS machine. =item '!' allowed only after types %s (F) The '!' is allowed in pack() and unpack() only after certain types. See L<perlfunc/pack>. -=item / cannot take a count - -(F) You had an unpack template indicating a counted-length string, -but you have also specified an explicit size for the string. -See L<perlfunc/pack>. - -=item / must be followed by a, A or Z - -(F) You had an unpack template indicating a counted-length string, -which must be followed by one of the letters a, A or Z -to indicate what sort of string is to be unpacked. -See L<perlfunc/pack>. +=item Ambiguous call resolved as CORE::%s(), qualify as such or use & -=item / must be followed by a*, A* or Z* +(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. -(F) You had a pack template indicating a counted-length string, -Currently the only things that can have their length counted are a*, A* or Z*. -See L<perlfunc/pack>. +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 C<use subs> pragma). -=item / must follow a numeric type +To silently interpret it as the Perl operator, use the C<CORE::> prefix +on the operator (e.g. C<CORE::log($x)>) or by declaring the subroutine +to be an object method (see L<perlsub/"Subroutine Attributes"> or +L<attributes>). -(F) You had an unpack template that contained a '#', -but this did not follow some numeric unpack specification. -See L<perlfunc/pack>. +=item Ambiguous use of %s resolved as %s -=item % may only be used in unpack +(W ambiguous)(S) 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. -(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 L<perlfunc/unpack>. +=item '|' and '<' may not both be specified on command line -=item /%s/: Unrecognized escape \\%c passed through +(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. -(W regexp) You used a backslash-character combination which is not recognized -by Perl. This combination appears in an interpolated variable or a -C<'>-delimited regular expression. The character was understood literally. +=item '|' and '>' may not both be specified on command line -=item /%s/: Unrecognized escape \\%c in character class passed through +(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 -(W regexp) You used a backslash-character combination which is not recognized -by Perl inside character classes. The character was understood literally. + open(OUT,">$ARGV[0]") or die "Can't write to $ARGV[0]: $!"; + while (<STDIN>) { + print; + print OUT; + } + close OUT; -=item /%s/ should probably be written as "%s" +=item Applying %s to %s will act on scalar(%s) -(W syntax) You have used a pattern where Perl expected to find a string, -as in the first argument to C<join>. 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. +(W misc) The pattern match (//), substitution (s///), and +transliteration (tr///) 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 L<perlfunc/grep> and L<perlfunc/map> for +alternatives. -=item %s (...) interpreted as function +=item Args must match #! line -(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 L<perlop/Terms and List Operators (Leftward)>. +(F) The setuid emulator requires that the arguments Perl was invoked +with match the arguments specified on the #! line. Since some systems +impose a one-argument limit on the #! line, try combining switches; +for example, turn C<-w -U> into C<-wU>. -=item %s() called too early to check prototype +=item Arg too short for msgsnd -(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 L<perlsub>. +(F) msgsnd() requires a string at least as long as sizeof(long). =item %s argument is not a HASH or ARRAY element @@ -155,7 +133,8 @@ an ampersand before the name to avoid the warning. See L<perlsub>. =item %s argument is not a HASH or ARRAY element or slice -(F) The argument to delete() must be either a hash or array element, such as: +(F) The argument to delete() must be either a hash or array element, +such as: $foo{$bar} $ref->{"susie"}[12] @@ -168,191 +147,19 @@ or a hash or array slice, such as: =item %s argument is not a subroutine name (F) The argument to exists() for C<exists &sub> must be a subroutine -name, and not a subroutine call. C<exists &sub()> will generate this error. - -=item %s did not return a true value - -(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 L<perlfunc/require>. - -=item %s found where operator expected - -(S) 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. - -=item %s had compilation errors - -(F) The final summary message when a C<perl -c> fails. - -=item %s has too many errors - -(F) The parser has given up trying to parse the program after 10 errors. -Further error messages would likely be uninformative. - -=item %s matches null string many times - -(W regexp) The pattern you've specified would be an infinite loop if the -regular expression engine didn't specifically check for that. See L<perlre>. - -=item %s never introduced - -(S internal) The symbol in question was declared but somehow went out of scope -before it could possibly have been used. - -=item %s package attribute may clash with future reserved word: %s - -(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 L<attributes>. - -=item %s syntax OK - -(F) The final summary message when a C<perl -c> succeeds. - -=item %s: Command not found - -(A) You've accidentally run your script through B<csh> instead -of Perl. Check the #! line, or manually feed your script into -Perl yourself. - -=item %s: Expression syntax - -(A) You've accidentally run your script through B<csh> instead -of Perl. Check the #! line, or manually feed your script into -Perl yourself. - -=item %s: Undefined variable - -(A) You've accidentally run your script through B<csh> instead -of Perl. Check the #! line, or manually feed your script into -Perl yourself. - -=item %s: not found - -(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. - -=item (in cleanup) %s - -(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. - -Failure of user callbacks dispatched using the C<G_KEEPERR> flag -could also result in this warning. See L<perlcall/G_KEEPERR>. - -=item (Missing semicolon on previous line?) - -(S) 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. - -=item B<-P> not allowed for setuid/setgid script - -(F) The script would have to be opened by the C preprocessor by name, -which provides a race condition that breaks security. - -=item C<-T> and C<-B> not implemented on filehandles - -(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. - -=item C<-p> destination: %s - -(F) An error occurred during the implicit output invoked by the C<-p> -command-line switch. (This output goes to STDOUT unless you've -redirected it with select().) - -=item 500 Server error - -See Server error. - -=item ?+* follows nothing in regexp - -(F) You started a regular expression with a quantifier. Backslash it -if you meant it literally. See L<perlre>. - -=item @ outside of string - -(F) You had a pack template that specified an absolute position outside -the string being unpacked. See L<perlfunc/pack>. - -=item <> should be quotes - -(F) You wrote C<< require <file> >> when you should have written -C<require 'file'>. - -=item accept() on closed socket %s - -(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 L<perlfunc/accept>. - -=item Allocation too large: %lx - -(X) You can't allocate more than 64K on an MS-DOS machine. - -=item Applying %s to %s will act on scalar(%s) - -(W misc) The pattern match (//), substitution (s///), and transliteration (tr///) -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 -L<perlfunc/grep> and L<perlfunc/map> for alternatives. - -=item Arg too short for msgsnd - -(F) msgsnd() requires a string at least as long as sizeof(long). - -=item Ambiguous use of %s resolved as %s - -(W ambiguous)(S) You said something that may not be interpreted the way -you thought. Normally it's pretty easy to disambiguate it by supplying -a missing quote, operator, parenthesis pair or declaration. - -=item Ambiguous call resolved as CORE::%s(), qualify as such or use & - -(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. - -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 C<use subs> pragma). - -To silently interpret it as the Perl operator, use the C<CORE::> prefix -on the operator (e.g. C<CORE::log($x)>) or by declaring the subroutine -to be an object method (see L<perlsub/"Subroutine Attributes"> -or L<attributes>). - -=item Args must match #! line - -(F) The setuid emulator requires that the arguments Perl was invoked -with match the arguments specified on the #! line. Since some systems -impose a one-argument limit on the #! line, try combining switches; -for example, turn C<-w -U> into C<-wU>. +name, and not a subroutine call. C<exists &sub()> will generate this +error. =item Argument "%s" isn't numeric%s -(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 +(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. =item Array @%s missing the @ in argument %d of %s() -(D deprecated) Really old Perl let you omit the @ on array names in some spots. This -is now heavily deprecated. +(D deprecated) Really old Perl let you omit the @ on array names in some +spots. This is now heavily deprecated. =item assertion botched: %s @@ -368,26 +175,31 @@ is now heavily deprecated. must either both be scalars or both be lists. Otherwise Perl won't know which context to supply to the right side. +=item Negative offset to vec in lvalue context + +(F) When vec is called in an lvalue context, the second argument must be +greater than or equal to zero. + =item Attempt to free non-arena SV: 0x%lx -(P internal) All SV objects are supposed to be allocated from arenas that will -be garbage collected on exit. An SV was discovered to be outside any -of those arenas. +(P internal) All SV objects are supposed to be allocated from arenas +that will be garbage collected on exit. An SV was discovered to be +outside any of those arenas. =item Attempt to free nonexistent shared string -(P internal) Perl maintains a reference counted internal table of strings to -optimize the storage and access of hash keys and other strings. This -indicates someone tried to decrement the reference count of a string -that can no longer be found in the table. +(P internal) Perl maintains a reference counted internal table of +strings to optimize the storage and access of hash keys and other +strings. This indicates someone tried to decrement the reference count +of a string that can no longer be found in the table. =item Attempt to free temp prematurely -(W 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. +(W 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. =item Attempt to free unreferenced glob pointers @@ -395,18 +207,19 @@ it. =item Attempt to free unreferenced scalar -(W 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. +(W 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. =item Attempt to join self (F) You tried to join a thread from within itself, which is an -impossible task. You may be joining the wrong thread, or you may -need to move the join() to some other thread. +impossible task. You may be joining the wrong thread, or you may need +to move the join() to some other thread. =item Attempt to pack pointer to temporary value @@ -419,14 +232,14 @@ avoid this warning. =item Attempt to use reference as lvalue in substr -(W substr) You supplied a reference as the first argument to substr() used -as an lvalue, which is pretty strange. Perhaps you forgot to +(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 L<perlfunc/substr>. =item Bad arg length for %s, is %d, should be %d -(F) You passed a buffer of the wrong size to one of msgctl(), semctl() or -shmctl(). In C parlance, the correct sizes are, respectively, +(F) You passed a buffer of the wrong size to one of msgctl(), semctl() +or shmctl(). In C parlance, the correct sizes are, respectively, S<sizeof(struct msqid_ds *)>, S<sizeof(struct semid_ds *)>, and S<sizeof(struct shmid_ds *)>. @@ -438,20 +251,19 @@ most likely an unexpected right brace '}'. =item Bad filehandle: %s -(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. +(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. =item Bad free() ignored -(S malloc) An internal routine called free() on something that had never been -malloc()ed in the first place. Mandatory, but can be disabled by -setting environment variable C<PERL_BADFREE> to 1. +(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 C<PERL_BADFREE> to 0. -This message can be quite often seen with DB_File on systems with -"hard" dynamic linking, like C<AIX> and C<OS/2>. It is a bug of -C<Berkeley DB> which is left unnoticed if C<DB> uses I<forgiving> -system malloc(). +This message can be seen quite often with DB_File on systems with "hard" +dynamic linking, like C<AIX> and C<OS/2>. It is a bug of C<Berkeley DB> +which is left unnoticed if C<DB> uses I<forgiving> system malloc(). =item Bad hash @@ -463,11 +275,17 @@ system malloc(). pseudo-hash is not legal. Index values must be at 1 or greater. See L<perlref>. +=item Badly placed ()'s + +(A) You've accidentally run your script through B<csh> instead +of Perl. Check the #! line, or manually feed your script into +Perl yourself. + =item Bad name after %s:: -(F) You started to name a symbol by using a package prefix, and then didn't -finish the symbol. In particular, you can't interpolate outside of quotes, -so +(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 $var = 'myvar'; $sym = mypack::$var; @@ -479,9 +297,9 @@ is not the same as =item Bad realloc() ignored -(S malloc) An internal routine called realloc() on something that had never been -malloc()ed in the first place. Mandatory, but can be disabled by -setting environment variable C<PERL_BADFREE> to 1. +(S malloc) An internal routine called realloc() on something that had +never been malloc()ed in the first place. Mandatory, but can be disabled +by setting environment variable C<PERL_BADFREE> to 1. =item Bad symbol for array @@ -490,60 +308,63 @@ wasn't a symbol table entry. =item Bad symbol for filehandle -(P) An internal request asked to add a filehandle entry to something that -wasn't a symbol table entry. +(P) An internal request asked to add a filehandle entry to something +that wasn't a symbol table entry. =item Bad symbol for hash (P) An internal request asked to add a hash entry to something that wasn't a symbol table entry. -=item Badly placed ()'s - -(A) You've accidentally run your script through B<csh> instead -of Perl. Check the #! line, or manually feed your script into -Perl yourself. - -=item Bareword "%s" not allowed while "strict subs" in use - -(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? - -=item Bareword "%s" refers to nonexistent package - -(W bareword) You used a qualified bareword of the form C<Foo::>, but -the compiler saw no other uses of that namespace before that point. -Perhaps you need to predeclare a package? - =item Bareword found in conditional -(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: +(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: open FOO || die; -It may also indicate a misspelled constant that has been interpreted -as a bareword: +It may also indicate a misspelled constant that has been interpreted as +a bareword: use constant TYPO => 1; if (TYOP) { print "foo" } The C<strict> pragma is useful in avoiding such errors. +=item Bareword "%s" not allowed while "strict subs" in use + +(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? + +=item Bareword "%s" refers to nonexistent package + +(W bareword) You used a qualified bareword of the form C<Foo::>, but the +compiler saw no other uses of that namespace before that point. Perhaps +you need to predeclare a package? + =item BEGIN failed--compilation aborted -(F) An untrapped exception was raised while executing a BEGIN subroutine. -Compilation stops immediately and the interpreter is exited. +(F) An untrapped exception was raised while executing a BEGIN +subroutine. Compilation stops immediately and the interpreter is +exited. =item BEGIN not safe after errors--compilation aborted (F) Perl found a C<BEGIN {}> subroutine (or a C<use> directive, which -implies a C<BEGIN {}>) after one or more compilation errors had -already occurred. Since the intended environment for the C<BEGIN {}> -could not be guaranteed (due to the errors), and since subsequent code -likely depends on its correct operation, Perl just gave up. +implies a C<BEGIN {}>) after one or more compilation errors had already +occurred. Since the intended environment for the C<BEGIN {}> could not +be guaranteed (due to the errors), and since subsequent code likely +depends on its correct operation, Perl just gave up. + +=item \1 better written as $1 + +(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. =item Binary number > 0b11111111111111111111111111111111 non-portable @@ -553,8 +374,8 @@ L<perlport> for more on portability concerns. =item bind() on closed socket %s -(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 L<perlfunc/bind>. +(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 L<perlfunc/bind>. =item Bit vector size > 32 non-portable @@ -562,108 +383,78 @@ the return value of your socket() call? See L<perlfunc/bind>. =item Bizarre copy of %s in %s -(P) Perl detected an attempt to copy an internal value that is not copiable. +(P) Perl detected an attempt to copy an internal value that is not +copyable. + +=item B<-P> not allowed for setuid/setgid script + +(F) The script would have to be opened by the C preprocessor by name, +which provides a race condition that breaks security. =item Buffer overflow in prime_env_iter: %s -(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. +(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. =item Callback called exit (F) A subroutine invoked from an external package via call_sv() exited by calling exit. -=item Can't "goto" out of a pseudo block - -(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 L<perlfunc/goto>. - -=item Can't "goto" into the middle of a foreach loop - -(F) A "goto" statement was executed to jump into the middle of a -foreach loop. You can't get there from here. See L<perlfunc/goto>. - -=item Can't "last" outside a loop block - -(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 L<perlfunc/last>. - -=item Can't "next" outside a loop block - -(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 L<perlfunc/next>. - -=item Can't read CRTL environ +=item %s() called too early to check prototype -(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 F<PERL_ENV_TABLES> (see L<perlvms>) so that environ is not searched. +(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 L<perlsub>. -=item Can't "redo" outside a loop block +=item / cannot take a count -(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 L<perlfunc/redo>. +(F) You had an unpack template indicating a counted-length string, but +you have also specified an explicit size for the string. See +L<perlfunc/pack>. =item Can't bless non-reference value (F) Only hard references may be blessed. This is how Perl "enforces" encapsulation of objects. See L<perlobj>. -=item Can't break at that line - -(S internal) A warning intended to only be printed while running within the debugger, indicating -the line number specified wasn't the location of a statement that could -be stopped at. - =item Can't call method "%s" in empty package "%s" (F) You called a method correctly, and it correctly indicated a package functioning as a class, but that package doesn't have ANYTHING defined in it, let alone methods. See L<perlobj>. -=item Can't call method "%s" on unblessed reference - -(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 L<perlobj>. - -=item Can't call method "%s" without a package or object reference +=item Can't call method "%s" on an undefined value (F) You used the syntax of a method call, but the slot filled by the -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: +object reference or package name contains an undefined value. Something +like this will reproduce the error: - $BADREF = 42; + $BADREF = undef; process $BADREF 1,2,3; $BADREF->process(1,2,3); -=item Can't call method "%s" on an undefined value +=item Can't call method "%s" on unblessed reference + +(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 L<perlobj>. + +=item Can't call method "%s" without a package or object reference (F) You used the syntax of a method call, but the slot filled by the -object reference or package name contains an undefined value. +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: - $BADREF = undef; + $BADREF = 42; process $BADREF 1,2,3; $BADREF->process(1,2,3); @@ -674,7 +465,14 @@ that you can chdir to, possibly because it doesn't exist. =item Can't check filesystem of script "%s" for nosuid -(P) For some reason you can't check the filesystem of the script for nosuid. +(P) For some reason you can't check the filesystem of the script for +nosuid. + +=item Can't coerce array into hash + +(F) You used an array where a hash was expected, but the array has no +information on how to map from keys to array indices. You can do that +only with arrays that have a hash reference at index 0. =item Can't coerce %s to integer in %s @@ -701,16 +499,10 @@ but then $foo no longer contains a glob. (F) Certain types of SVs, in particular real symbol table entries (typeglobs), can't be forced to stop being what they are. -=item Can't coerce array into hash - -(F) You used an array where a hash was expected, but the array has no -information on how to map from keys to array indices. You can do that -only with arrays that have a hash reference at index 0. - =item Can't create pipe mailbox -(P) An error peculiar to VMS. The process is suffering from exhausted quotas -or other plumbing problems. +(P) An error peculiar to VMS. The process is suffering from exhausted +quotas or other plumbing problems. =item Can't declare class for non-scalar %s in "%s" @@ -723,15 +515,21 @@ for other types of variables in future. (F) Only scalar, array, and hash variables may be declared as "my" or "our" variables. They must have ordinary identifiers as names. +=item Can't do inplace edit: %s is not a regular file + +(S inplace) You tried to use the B<-i> switch on a special file, such as +a file in /dev, or a FIFO. The file was ignored. + =item Can't do inplace edit on %s: %s -(S inplace) The creation of the new file failed for the indicated reason. +(S inplace) The creation of the new file failed for the indicated +reason. =item Can't do inplace edit without backup -(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 C<-i.bak>, or some -such. +(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 +C<-i.bak>, or some such. =item Can't do inplace edit: %s would not be unique @@ -739,15 +537,16 @@ such. characters and Perl was unable to create a unique filename during inplace editing with the B<-i> switch. The file was ignored. -=item Can't do inplace edit: %s is not a regular file +=item Can't do {n,m} with n > m before << HERE in regex m/%s/ -(S inplace) You tried to use the B<-i> switch on a special file, such as a file in -/dev, or a FIFO. The file was ignored. +(F) Minima must be less than or equal to maxima. If you really want your +regexp to match something 0 times, just put {0}. The << HERE shows in the +regular expression about where the problem was discovered. See L<perlre>. =item Can't do setegid! -(P) The setegid() call failed for some reason in the setuid emulator -of suidperl. +(P) The setegid() call failed for some reason in the setuid emulator of +suidperl. =item Can't do seteuid! @@ -755,134 +554,161 @@ of suidperl. =item Can't do setuid -(F) This typically means that ordinary perl tried to exec suidperl to -do setuid emulation, but couldn't exec it. It looks for a name of the -form sperl5.000 in the same directory that the perl executable resides -under the name perl5.000, typically /usr/local/bin on Unix machines. -If the file is there, check the execute permissions. If it isn't, ask -your sysadmin why he and/or she removed it. +(F) This typically means that ordinary perl tried to exec suidperl to do +setuid emulation, but couldn't exec it. It looks for a name of the form +sperl5.000 in the same directory that the perl executable resides under +the name perl5.000, typically /usr/local/bin on Unix machines. If the +file is there, check the execute permissions. If it isn't, ask your +sysadmin why he and/or she removed it. =item Can't do waitpid with flags -(F) This machine doesn't have either waitpid() or wait4(), so only waitpid() -without flags is emulated. - -=item Can't do {n,m} with n > m - -(F) Minima must be less than or equal to maxima. If you really want -your regexp to match something 0 times, just put {0}. See L<perlre>. +(F) This machine doesn't have either waitpid() or wait4(), so only +waitpid() without flags is emulated. =item Can't emulate -%s on #! line -(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 B<-x> on the #! line. +(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 B<-x> on the #! +line. =item Can't exec "%s": %s -(W exec) An 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 C<$ENV{PATH}>, 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.) +(W exec) An 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 +C<$ENV{PATH}>, 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.) =item Can't exec %s -(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. +(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. =item Can't execute %s -(F) You used the B<-S> switch, but the copies of the script to execute found -in the PATH did not have correct permissions. +(F) You used the B<-S> switch, but the copies of the script to execute +found in the PATH did not have correct permissions. -=item Can't find %s on PATH, '.' not in PATH +=item Can't find an opnumber for "%s" -(F) You used the B<-S> 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. +(F) A string of a form C<CORE::word> was given to prototype(), but there +is no builtin with the name C<word>. + +=item Can't find label %s + +(F) You said to goto a label that isn't mentioned anywhere that it's +possible for us to go to. See L<perlfunc/goto>. =item Can't find %s on PATH -(F) You used the B<-S> switch, but the script to execute could not be found -in the PATH. +(F) You used the B<-S> switch, but the script to execute could not be +found in the PATH. -=item Can't find label %s +=item Can't find %s on PATH, '.' not in PATH -(F) You said to goto a label that isn't mentioned anywhere that it's possible -for us to go to. See L<perlfunc/goto>. +(F) You used the B<-S> 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. =item Can't find string terminator %s anywhere before EOF -(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: +(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: print q(The character '(' starts a side comment.); -If you're getting this error from a here-document, you may have -included unseen whitespace before or after your closing tag. A good -programmer's editor will have a way to help you find these characters. +If you're getting this error from a here-document, you may have included +unseen whitespace before or after your closing tag. A good programmer's +editor will have a way to help you find these characters. + +=item Can't find %s property definition %s + +(F) You may have tried to use C<\p> which means a Unicode property for +example \p{Lu} is all uppercase letters. Escape the C<\p>, either +C<\\p> (just the C<\p>) or by C<\Q\p> (the rest of the string, until +possible C<\E>). =item Can't fork -(F) A fatal error occurred while trying to fork while opening a pipeline. +(F) A fatal error occurred while trying to fork while opening a +pipeline. =item Can't get filespec - stale stat buffer? -(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 C<stat> operator and file tests, so you shouldn't ever -see this warning in response to a Perl command; it arises only if some internal -code takes stat buffers lightly.) +(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 C<stat> operator and file tests, so you +shouldn't ever see this warning in response to a Perl command; it arises +only if some internal code takes stat buffers lightly.) =item Can't get pipe mailbox device name -(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) An error peculiar to VMS. After creating a mailbox to act as a +pipe, Perl can't retrieve its name for later use. =item Can't get SYSGEN parameter value for MAXBUF (P) An error peculiar to VMS. Perl asked $GETSYI how big you want your mailbox buffers to be, and didn't get an answer. -=item Can't goto subroutine outside a subroutine +=item Can't "goto" into the middle of a foreach loop -(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 -L<perlfunc/goto>. +(F) A "goto" statement was executed to jump into the middle of a foreach +loop. You can't get there from here. See L<perlfunc/goto>. + +=item Can't "goto" out of a pseudo block + +(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 L<perlfunc/goto>. =item Can't goto subroutine from an eval-string -(F) The "goto subroutine" call can't be used to jump out of an eval "string". -(You can use it to jump out of an eval {BLOCK}, but you probably don't want to.) +(F) The "goto subroutine" call can't be used to jump out of an eval +"string". (You can use it to jump out of an eval {BLOCK}, but you +probably don't want to.) + +=item Can't goto subroutine outside a subroutine + +(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 L<perlfunc/goto>. =item Can't ignore signal CHLD, forcing to default -(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. +(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. -=item Can't localize through a reference +=item Can't "last" outside a loop block -(F) You said something like C<local $$ref>, 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. +(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 +L<perlfunc/last>. =item Can't localize lexical variable %s @@ -893,27 +719,34 @@ package name. =item Can't localize pseudo-hash element -(F) You said something like C<< local $ar->{'key'} >>, where $ar is -a reference to a pseudo-hash. That hasn't been implemented yet, but -you can get a similar effect by localizing the corresponding array -element directly -- C<< local $ar->[$ar->[0]{'key'}] >>. +(F) You said something like C<< local $ar->{'key'} >>, where $ar is a +reference to a pseudo-hash. That hasn't been implemented yet, but you +can get a similar effect by localizing the corresponding array element +directly -- C<< local $ar->[$ar->[0]{'key'}] >>. -=item Can't locate auto/%s.al in @INC +=item Can't localize through a reference -(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 C<AutoSplit> the file, say, by -doing C<make install>. +(F) You said something like C<local $$ref>, 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. =item Can't locate %s (F) You said to C<do> (or C<require>, or C<use>) a file that couldn't be found. Perl looks for the file in all the locations mentioned in @INC, -unless the file name included the full path to the file. Perhaps you need -to set the PERL5LIB or PERL5OPT environment variable to say where the extra -library is, or maybe the script needs to add the library name to @INC. Or -maybe you just misspelled the name of the file. See L<perlfunc/require> -and L<lib>. +unless the file name included the full path to the file. Perhaps you +need to set the PERL5LIB or PERL5OPT environment variable to say where +the extra library is, or maybe the script needs to add the library name +to @INC. Or maybe you just misspelled the name of the file. See +L<perlfunc/require> and L<lib>. + +=item Can't locate auto/%s.al in @INC + +(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 C<AutoSplit> +the file, say, by doing C<make install>. =item Can't locate object method "%s" via package "%s" @@ -921,88 +754,123 @@ and L<lib>. functioning as a class, but that package doesn't define that particular method, nor does any of its base classes. See L<perlobj>. +=item (perhaps you forgot to load "%s"?) + +(F) This is an educated guess made in conjunction with the message +"Can't locate object method \"%s\" via package \"%s\"". It often means +that a method requires a package that has not been loaded. + =item Can't locate package %s for @%s::ISA -(W syntax) The @ISA array contained the name of another package that doesn't seem -to exist. +(W syntax) The @ISA array contained the name of another package that +doesn't seem to exist. =item Can't make list assignment to \%ENV on this system -(F) List assignment to %ENV is not supported on some systems, notably VMS. +(F) List assignment to %ENV is not supported on some systems, notably +VMS. =item Can't modify %s in %s -(F) You aren't allowed to assign to the item indicated, or otherwise try to -change it, such as with an auto-increment. - -=item Can't modify non-lvalue subroutine call - -(F) Subroutines meant to be used in lvalue context should be declared as -such, see L<perlsub/"Lvalue subroutines">. +(F) You aren't allowed to assign to the item indicated, or otherwise try +to change it, such as with an auto-increment. =item Can't modify nonexistent substring (P) The internal routine that does assignment to a substr() was handed a NULL. +=item Can't modify non-lvalue subroutine call + +(F) Subroutines meant to be used in lvalue context should be declared as +such, see L<perlsub/"Lvalue subroutines">. + =item Can't msgrcv to read-only var (F) The target of a msgrcv must be modifiable to be used as a receive buffer. +=item Can't "next" outside a loop block + +(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 L<perlfunc/next>. + =item Can't open %s: %s (S inplace) The implicit opening of a file through use of the C<< <> >> filehandle, either implicitly under the C<-n> or C<-p> command-line switches, or explicitly, failed for the indicated reason. Usually this -is because you don't have read permission for a file which you named -on the command line. +is because you don't have read permission for a file which you named on +the command line. =item Can't open bidirectional pipe -(W pipe) You tried to say C<open(CMD, "|cmd|")>, 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. +(W pipe) You tried to say C<open(CMD, "|cmd|")>, 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. =item Can't open error file %s as stderr -(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. +(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. =item Can't open input file %s as stdin -(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. +(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. =item Can't open output file %s as stdout -(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. +(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. =item Can't open output pipe (name: %s) -(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) 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. =item Can't open perl script "%s": %s (F) The script you specified can't be opened for the indicated reason. +=item Can't read CRTL environ + +(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 F<PERL_ENV_TABLES> (see L<perlvms>) so that environ is not +searched. + =item Can't redefine active sort subroutine %s (F) Perl optimizes the internal handling of sort subroutines and keeps -pointers into them. You tried to redefine one such sort subroutine when it -was currently active, which is not allowed. If you really want to do +pointers into them. You tried to redefine one such sort subroutine when +it was currently active, which is not allowed. If you really want to do this, you should write C<sort { &func } @x> instead of C<sort func @x>. +=item Can't "redo" outside a loop block + +(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 L<perlfunc/redo>. + =item Can't remove %s: %s, skipping file -(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. +(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. =item Can't rename %s to %s: %s, skipping file @@ -1011,41 +879,55 @@ probably because you don't have write permission to the directory. =item Can't reopen input pipe (name: %s) in binary mode -(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) An error peculiar to VMS. Perl thought stdin was a pipe, and tried +to reopen it to accept binary data. Alas, it failed. + +=item Can't resolve method `%s' overloading `%s' in package `%s' + +(F|P) Error resolving overloading specified by a method name (as opposed +to a subroutine reference): no such method callable via the package. If +method name is C<???>, this is an internal error. =item Can't reswap uid and euid -(P) The setreuid() call failed for some reason in the setuid emulator -of suidperl. +(P) The setreuid() call failed for some reason in the setuid emulator of +suidperl. + +=item Can't return %s from lvalue subroutine + +(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. + +=item Can't return %s to lvalue scalar context + +(F) You tried to return a complete array or hash from an lvalue subroutine, +but you called the subroutine in a way that made Perl think you meant +to return only one value. You probably meant to write parentheses around +the call to the subroutine, which tell Perl that the call should be in +list context. =item Can't return outside a subroutine (F) The return statement was executed in mainline code, that is, where there was no subroutine call to return out of. See L<perlsub>. -=item Can't return %s from lvalue subroutine - -(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. - =item Can't stat script "%s" -(P) For some reason you can't fstat() the script even though you have -it open already. Bizarre. +(P) For some reason you can't fstat() the script even though you have it +open already. Bizarre. =item Can't swap uid and euid -(P) The setreuid() call failed for some reason in the setuid emulator -of suidperl. +(P) The setreuid() call failed for some reason in the setuid emulator of +suidperl. =item Can't take log of %g (F) For ordinary real numbers, you can't take the logarithm of a negative number or zero. There's a Math::Complex package that comes -standard with Perl, though, if you really want to do that for -the negative numbers. +standard with Perl, though, if you really want to do that for the +negative numbers. =item Can't take sqrt of %g @@ -1066,23 +948,46 @@ as the main Perl stack. =item Can't upgrade that kind of scalar -(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) 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. =item Can't upgrade to undef -(P) The undefined SV is the bottom of the totem pole, in the scheme -of upgradability. Upgrading to undef indicates an error in the -code calling sv_upgrade. +(P) The undefined SV is the bottom of the totem pole, in the scheme of +upgradability. Upgrading to undef indicates an error in the code +calling sv_upgrade. -=item Can't use %%! because Errno.pm is not available +=item Can't use an undefined value as %s reference + +(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. + +=item Can't use bareword ("%s") as %s ref while "strict refs" in use + +(F) Only hard references are allowed by "strict refs". Symbolic +references are disallowed. See L<perlref>. + +=item Can't use %! because Errno.pm is not available (F) The first time the %! hash is used, perl automatically loads the Errno.pm module. The Errno module is expected to tie the %! hash to provide symbolic names for C<$!> errno values. +=item Can't use %s for loop variable + +(F) Only a simple scalar variable may be used as a loop variable on a +foreach. + +=item Can't use global %s in "my" + +(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. + =item Can't use "my %s" in sort comparison (F) The global variables $a and $b are reserved for sort comparisons. @@ -1091,46 +996,16 @@ and the variable had earlier been declared as a lexical variable. Either qualify the sort variable with the package name, or rename the lexical variable. -=item Can't use %s for loop variable - -(F) Only a simple scalar variable may be used as a loop variable on a foreach. - =item Can't use %s ref as %s ref (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. -=item Can't use \%c to mean $%c in expression - -(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. - -=item Can't use bareword ("%s") as %s ref while "strict refs" in use - -(F) Only hard references are allowed by "strict refs". Symbolic references -are disallowed. See L<perlref>. - =item Can't use string ("%s") as %s ref while "strict refs" in use -(F) Only hard references are allowed by "strict refs". Symbolic references -are disallowed. See L<perlref>. - -=item Can't use an undefined value as %s reference - -(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. - -=item Can't use global %s in "my" - -(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. +(F) Only hard references are allowed by "strict refs". Symbolic +references are disallowed. See L<perlref>. =item Can't use subscript on %s @@ -1138,6 +1013,15 @@ weren't. subscript. But to the left of the brackets was an expression that didn't look like an array reference, or anything else subscriptable. +=item Can't use \%c to mean $%c in expression + +(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. + =item Can't weaken a nonreference (F) You attempted to weaken something that was not a reference. Only @@ -1145,125 +1029,90 @@ references can be weakened. =item Can't x= to read-only value -(F) You tried to repeat a constant value (often the undefined value) with -an assignment operator, which implies modifying the value itself. +(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. -=item Can't find an opnumber for "%s" - -(F) A string of a form C<CORE::word> was given to prototype(), but -there is no builtin with the name C<word>. - -=item Can't resolve method `%s' overloading `%s' in package `%s' - -(F|P) Error resolving overloading specified by a method name (as -opposed to a subroutine reference): no such method callable via the -package. If method name is C<???>, this is an internal error. - -=item Character class [:%s:] unknown - -(F) The class in the character class [: :] syntax is unknown. -See L<perlre>. - -=item Character class syntax [%s] belongs inside character classes - -(W unsafe) The character class constructs [: :], [= =], and [. .] go -I<inside> character classes, the [] are part of the construct, -for example: /[012[:alpha:]345]/. Note that [= =] and [. .] -are not currently implemented; they are simply placeholders for -future extensions. - -=item Character class syntax [. .] is reserved for future extensions - -(W regexp) Within regular expression character classes ([]) the syntax beginning -with "[." and ending with ".]" is reserved for future extensions. -If you need to represent those character sequences inside a regular -expression character class, just quote the square brackets with the -backslash: "\[." and ".\]". - -=item Character class syntax [= =] is reserved for future extensions - -(W regexp) Within regular expression character classes ([]) the syntax -beginning with "[=" and ending with "=]" is reserved for future extensions. -If you need to represent those character sequences inside a regular -expression character class, just quote the square brackets with the -backslash: "\[=" and "=\]". - =item chmod() mode argument is missing initial 0 (W chmod) A novice will sometimes say chmod 777, $filename -not realizing that 777 will be interpreted as a decimal number, equivalent -to 01411. Octal constants are introduced with a leading 0 in Perl, as in C. +not realizing that 777 will be interpreted as a decimal number, +equivalent to 01411. Octal constants are introduced with a leading 0 in +Perl, as in C. -=item Close on unopened file <%s> +=item close() on unopened filehandle %s (W unopened) You tried to close a filehandle that was never opened. +=item %s: Command not found + +(A) You've accidentally run your script through B<csh> instead of Perl. +Check the #! line, or manually feed your script into Perl yourself. + =item Compilation failed in require (F) Perl could not compile a file specified in a C<require> statement. -Perl uses this generic message when none of the errors that it encountered -were severe enough to halt compilation immediately. +Perl uses this generic message when none of the errors that it +encountered were severe enough to halt compilation immediately. =item Complex regular subexpression recursion limit (%d) exceeded -(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 +(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 C<while>) rather -than in the regular expression engine; or rewriting the regular -expression so that it is simpler or backtracks less. (See L<perlbook> -for information on I<Mastering Regular Expressions>.) +under examination; looping in Perl code (e.g. with C<while>) rather than +in the regular expression engine; or rewriting the regular expression so +that it is simpler or backtracks less. (See L<perlfaq2> for information +on I<Mastering Regular Expressions>.) =item connect() on closed socket %s -(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 L<perlfunc/connect>. +(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 +L<perlfunc/connect>. + +=item Constant(%s)%s: %s + +(F) The parser found inconsistencies either while attempting to define +an overloaded constant, or when trying to find the character name +specified in the C<\N{...}> escape. Perhaps you forgot to load the +corresponding C<overload> or C<charnames> pragma? See L<charnames> and +L<overload>. =item Constant is not %s reference (F) A constant value (perhaps declared using the C<use constant> pragma) -is being dereferenced, but it amounts to the wrong type of reference. The -message indicates the type of reference that was expected. This usually -indicates a syntax error in dereferencing the constant value. +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 L<perlsub/"Constant Functions"> and L<constant>. =item Constant subroutine %s redefined -(S|W redefine) You redefined a subroutine which had previously been eligible for -inlining. See L<perlsub/"Constant Functions"> for commentary and -workarounds. +(S|W redefine) You redefined a subroutine which had previously been +eligible for inlining. See L<perlsub/"Constant Functions"> for +commentary and workarounds. =item Constant subroutine %s undefined -(W misc) You undefined a subroutine which had previously been eligible for -inlining. See L<perlsub/"Constant Functions"> for commentary and +(W misc) You undefined a subroutine which had previously been eligible +for inlining. See L<perlsub/"Constant Functions"> for commentary and workarounds. -=item constant(%s): %s - -(F) The parser found inconsistencies either while attempting to define an -overloaded constant, or when trying to find the character name specified -in the C<\N{...}> escape. Perhaps you forgot to load the corresponding -C<overload> or C<charnames> pragma? See L<charnames> and L<overload>. - =item Copy method did not return a reference -(F) The method which overloads "=" is buggy. See L<overload/Copy Constructor>. +(F) The method which overloads "=" is buggy. See +L<overload/Copy Constructor>. =item CORE::%s is not a keyword (F) The CORE:: namespace is reserved for Perl keywords. -=item Corrupt malloc ptr 0x%lx at 0x%lx - -(P) The malloc package that comes with Perl had an internal failure. - =item corrupted regexp pointers (P) The regular expression engine got confused by what the regular @@ -1271,69 +1120,82 @@ expression compiler gave it. =item corrupted regexp program -(P) The regular expression engine got passed a regexp program without -a valid magic number. +(P) The regular expression engine got passed a regexp program without a +valid magic number. + +=item Corrupt malloc ptr 0x%lx at 0x%lx + +(P) The malloc package that comes with Perl had an internal failure. + +=item C<-p> destination: %s + +(F) An error occurred during the implicit output invoked by the C<-p> +command-line switch. (This output goes to STDOUT unless you've +redirected it with select().) + +=item C<-T> and C<-B> not implemented on filehandles + +(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. =item Deep recursion on subroutine "%s" -(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. +(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. =item defined(@array) is deprecated -(D deprecated) defined() is not usually useful on arrays because it checks for an -undefined I<scalar> value. If you want to see if the array is empty, -just use C<if (@array) { # not empty }> for example. +(D deprecated) defined() is not usually useful on arrays because it +checks for an undefined I<scalar> value. If you want to see if the +array is empty, just use C<if (@array) { # not empty }> for example. =item defined(%hash) is deprecated -(D deprecated) defined() is not usually useful on hashes because it checks for an -undefined I<scalar> value. If you want to see if the hash is empty, -just use C<if (%hash) { # not empty }> for example. +(D deprecated) defined() is not usually useful on hashes because it +checks for an undefined I<scalar> value. If you want to see if the hash +is empty, just use C<if (%hash) { # not empty }> for example. =item Delimiter for here document is too long -(F) In a here document construct like C<<<FOO>, the label -C<FOO> is too long for Perl to handle. You have to be seriously -twisted to write code that triggers this error. +(F) In a here document construct like C<<<FOO>, the label C<FOO> is too +long for Perl to handle. You have to be seriously twisted to write code +that triggers this error. =item Did not produce a valid header See Server error. +=item %s did not return a true value + +(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 L<perlfunc/require>. + =item (Did you mean &%s instead?) -(W) You probably referred to an imported subroutine &FOO as $FOO or some such. +(W) You probably referred to an imported subroutine &FOO as $FOO or some +such. =item (Did you mean "local" instead of "our"?) -(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. +(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. =item (Did you mean $ or @ instead of %?) -(W) You probably said %hash{$key} when you meant $hash{$key} or @hash{@keys}. -On the other hand, maybe you just meant %hash and got carried away. +(W) You probably said %hash{$key} when you meant $hash{$key} or +@hash{@keys}. On the other hand, maybe you just meant %hash and got +carried away. =item Died (F) You passed die() an empty string (the equivalent of C<die "">) or you called it with no args and both C<$@> and C<$_> were empty. -=item (Do you need to predeclare %s?) - -(S) 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. - =item Document contains no data See Server error. @@ -1346,24 +1208,29 @@ See Server error. (P) This should have been caught by safemalloc() instead. +=item (Do you need to predeclare %s?) + +(S) 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. + =item Duplicate free() ignored -(S malloc) An internal routine called free() on something that had already -been freed. +(S malloc) An internal routine called free() on something that had +already been freed. =item elseif should be elsif -(S) There is no keyword "elseif" in Perl because Larry thinks it's -ugly. Your code will be interpreted as an attempt to call a method -named "elseif" for the class returned by the following block. This is +(S) There is no keyword "elseif" in Perl because Larry thinks it's ugly. +Your code will be interpreted as an attempt to call a method named +"elseif" for the class returned by the following block. This is unlikely to be what you want. -=item %s failed--call queue aborted - -(F) An untrapped exception was raised while executing a CHECK, INIT, or -END subroutine. Processing of the remainder of the queue of such -routines has been prematurely ended. - =item entering effective %s failed (F) While under the C<use filetest> pragma, switching the real and @@ -1373,30 +1240,30 @@ effective uids or gids failed. (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. +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. =item %s: Eval-group in insecure regular expression -(F) Perl detected tainted data when trying to compile a regular expression -that contains the C<(?{ ... })> zero-width assertion, which is unsafe. -See L<perlre/(?{ code })>, and L<perlsec>. +(F) Perl detected tainted data when trying to compile a regular +expression that contains the C<(?{ ... })> zero-width assertion, which +is unsafe. See L<perlre/(?{ code })>, and L<perlsec>. -=item %s: Eval-group not allowed, use re 'eval' +=item %s: Eval-group not allowed at run time -(F) A regular expression contained the C<(?{ ... })> zero-width assertion, -but that construct is only allowed when the C<use re 'eval'> pragma is -in effect. See L<perlre/(?{ code })>. +(F) Perl tried to compile a regular expression containing the +C<(?{ ... })> zero-width assertion at run time, as it would when the +pattern contains interpolated values. Since that is a security risk, it +is not allowed. If you insist, you may still do this by explicitly +building the pattern from an interpolated string at run time and using +that in an eval(). See L<perlre/(?{ code })>. -=item %s: Eval-group not allowed at run time +=item %s: Eval-group not allowed, use re 'eval' -(F) Perl tried to compile a regular expression containing the C<(?{ ... })> -zero-width assertion at run time, as it would when the pattern contains -interpolated values. Since that is a security risk, it is not allowed. -If you insist, you may still do this by explicitly building the pattern -from an interpolated string at run time and using that in an eval(). -See L<perlre/(?{ code })>. +(F) A regular expression contained the C<(?{ ... })> zero-width +assertion, but that construct is only allowed when the C<use re 'eval'> +pragma is in effect. See L<perlre/(?{ code })>. =item Excessively long <> operator @@ -1411,97 +1278,112 @@ variable and glob that. =item Exiting eval via %s -(W exiting) You are exiting an eval by unconventional means, such as -a goto, or a loop control statement. +(W exiting) You are exiting an eval by unconventional means, such as a +goto, or a loop control statement. =item Exiting format via %s -(W exiting) You are exiting an eval by unconventional means, such as -a goto, or a loop control statement. +(W exiting) You are exiting an eval by unconventional means, such as a +goto, or a loop control statement. =item Exiting pseudo-block via %s -(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 L<perlfunc/sort>. +(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 L<perlfunc/sort>. =item Exiting subroutine via %s -(W exiting) You are exiting a subroutine by unconventional means, such as -a goto, or a loop control statement. +(W exiting) You are exiting a subroutine by unconventional means, such +as a goto, or a loop control statement. =item Exiting substitution via %s -(W exiting) You are exiting a substitution by unconventional means, such as -a return, a goto, or a loop control statement. +(W exiting) You are exiting a substitution by unconventional means, such +as a return, a goto, or a loop control statement. =item Explicit blessing to '' (assuming package main) (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'); +usually not what you want. Consider providing a default target package, +e.g. bless($ref, $p || 'MyPackage'); + +=item %s: Expression syntax + +(A) You've accidentally run your script through B<csh> instead of Perl. +Check the #! line, or manually feed your script into Perl yourself. + +=item %s failed--call queue aborted + +(F) An untrapped exception was raised while executing a CHECK, INIT, or +END subroutine. Processing of the remainder of the queue of such +routines has been prematurely ended. =item false [] range "%s" in regexp -(W regexp) A character class range must start and end at a literal character, not -another character class like C<\d> or C<[:alpha:]>. The "-" in your false -range is interpreted as a literal "-". Consider quoting the "-", "\-". -See L<perlre>. +(W regexp) A character class range must start and end at a literal +character, not another character class like C<\d> or C<[:alpha:]>. The +"-" in your false range is interpreted as a literal "-". Consider +quoting the "-", "\-". See L<perlre>. =item Fatal VMS error at %s, line %d -(P) An error peculiar to VMS. Something untoward happened in a VMS system -service or RTL routine; Perl's exit status should provide more 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) 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. =item fcntl is not implemented (F) Your machine apparently doesn't implement fcntl(). What is this, a PDP-11 or something? -=item Filehandle %s never opened - -(W unopened) An I/O operation was attempted on a filehandle that was never initialized. -You need to do an open() or a socket() call, or call a constructor from -the FileHandle package. - =item Filehandle %s opened only for input -(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 -L<perlfunc/open>. +(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 L<perlfunc/open>. =item Filehandle %s opened only for output -(W io) You tried to read from a filehandle opened only for writing. If you -intended it to be a read/write filehandle, you needed to open it with -"+<" or "+>" or "+>>" instead of with "<" or nothing. If -you intended only to read from the file, use "<". See -L<perlfunc/open>. +(W io) You tried to read from a filehandle opened only for writing. If +you intended it to be a read/write filehandle, you needed to open it +with "+<" or "+>" or "+>>" instead of with "<" or nothing. If you +intended only to read from the file, use "<". See L<perlfunc/open>. =item Final $ should be \$ or $name (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. +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. =item Final @ should be \@ or @name (F) You must now decide whether the final @ in a string was meant to be -a literal "at" 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. +a literal "at" 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. =item flock() on closed filehandle %s -(W closed) The filehandle you're attempting to flock() got itself closed some -time before now. Check your logic flow. flock() operates on filehandles. -Are you attempting to call flock() on a dirhandle by the same name? +(W closed) The filehandle you're attempting to flock() got itself closed +some time before now. Check your logic flow. flock() operates on +filehandles. Are you attempting to call flock() on a dirhandle by the +same name? + +=item Quantifier follows nothing before << HERE in regex m/%s/ + +(F) You started a regular expression with a quantifier. Backslash it if you +meant it literally. The << HERE shows in the regular expression about where the +problem was discovered. See L<perlre>. + +=item Format not terminated + +(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. =item Format %s redefined @@ -1512,11 +1394,6 @@ Are you attempting to call flock() on a dirhandle by the same name? eval "format NAME =..."; } -=item Format not terminated - -(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. - =item Found = in conditional, should be == (W syntax) You said @@ -1529,6 +1406,13 @@ when you meant (or something like that). +=item %s found where operator expected + +(S) 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. + =item gdbm store returned %d, errno %d, key "%s" (S) A warning from the GDBM_File extension that a store failed. @@ -1541,34 +1425,19 @@ on the Internet. =item get%sname() on closed socket %s -(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? +(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? =item getpwnam returned invalid UIC %#o for user "%s" (S) A warning peculiar to VMS. The call to C<sys$getuai> underlying the C<getpwnam> operator returned an invalid UIC. -=item glob failed (%s) - -(W glob) Something went wrong with the external program(s) used for C<glob> -and C<< <*.c> >>. Usually, this means that you supplied a C<glob> -pattern that caused the external program to fail and exit with a nonzero -status. If the message indicates that the abnormal exit resulted in a -coredump, this may also mean that your csh (C shell) is broken. If so, -you should change all of the csh-related variables in config.sh: If you -have tcsh, make the variables refer to it as if it were csh (e.g. -C<full_csh='/usr/bin/tcsh'>); otherwise, make them all empty (except that -C<d_csh> should be C<'undef'>) so that Perl will think csh is missing. -In either case, after editing config.sh, run C<./Configure -S> and -rebuild Perl. +=item getsockopt() on closed socket %s -=item Glob not terminated - -(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". +(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 +L<perlfunc/getsockopt>. =item Global symbol "%s" requires explicit package name @@ -1577,21 +1446,56 @@ must either be lexically scoped (using "my"), declared beforehand using "our", or explicitly qualified to say which package the global variable is in (using "::"). +=item glob failed (%s) + +(W glob) Something went wrong with the external program(s) used for +C<glob> and C<< <*.c> >>. Usually, this means that you supplied a +C<glob> pattern that caused the external program to fail and exit with a +nonzero status. If the message indicates that the abnormal exit +resulted in a coredump, this may also mean that your csh (C shell) is +broken. If so, you should change all of the csh-related variables in +config.sh: If you have tcsh, make the variables refer to it as if it +were csh (e.g. C<full_csh='/usr/bin/tcsh'>); otherwise, make them all +empty (except that C<d_csh> should be C<'undef'>) so that Perl will +think csh is missing. In either case, after editing config.sh, run +C<./Configure -S> and rebuild Perl. + +=item Glob not terminated + +(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". + +=item Got an error from DosAllocMem + +(P) An error peculiar to OS/2. Most probably you're using an obsolete +version of Perl, and this should not happen anyway. + =item goto must have label (F) Unlike with "next" or "last", you're not allowed to goto an unspecified destination. See L<perlfunc/goto>. +=item %s had compilation errors + +(F) The final summary message when a C<perl -c> fails. + =item Had to create %s unexpectedly -(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. +(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. =item Hash %%s missing the % in argument %d of %s() -(D deprecated) Really old Perl let you omit the % on hash names in some spots. This -is now heavily deprecated. +(D deprecated) Really old Perl let you omit the % on hash names in some +spots. This is now heavily deprecated. + +=item %s has too many errors + +(F) The parser has given up trying to parse the program after 10 errors. +Further error messages would likely be uninformative. =item Hexadecimal number > 0xffffffff non-portable @@ -1603,99 +1507,102 @@ L<perlport> for more on portability concerns. (F) Perl limits identifiers (names for variables, functions, etc.) to about 250 characters for simple names, and somewhat more for compound -names (like C<$A::B>). You've exceeded Perl's limits. Future -versions of Perl are likely to eliminate these arbitrary limitations. +names (like C<$A::B>). You've exceeded Perl's limits. Future versions +of Perl are likely to eliminate these arbitrary limitations. -=item Ill-formed CRTL environ value "%s" +=item Illegal binary digit %s -(W internal) A warning peculiar to VMS. Perl tried to read the CRTL's internal -environ array, and encountered an element without the C<=> delimiter -used to spearate keys from values. The element is ignored. +(F) You used a digit other than 0 or 1 in a binary number. -=item Ill-formed message in prime_env_iter: |%s| +=item Illegal binary digit %s ignored -(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. +(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. =item Illegal character %s (carriage return) (F) Perl normally treats carriage returns in the program text as it -would any other whitespace, which means you should never see this -error 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. +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. =item Illegal division by zero -(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. +(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. + +=item Illegal hexadecimal digit %s ignored + +(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. =item Illegal modulus zero -(F) You tried to divide a number by 0 to get the remainder. Most numbers -don't take to this kindly. +(F) You tried to divide a number by 0 to get the remainder. Most +numbers don't take to this kindly. -=item Illegal binary digit %s +=item Illegal number of bits in vec -(F) You used a digit other than 0 or 1 in a binary number. +(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). =item Illegal octal digit %s (F) You used an 8 or 9 in a octal number. -=item Illegal binary digit %s ignored - -(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. - =item Illegal octal digit %s ignored -(W digit) You may have tried to use an 8 or 9 in a octal number. Interpretation -of the octal number stopped before the 8 or 9. +(W digit) You may have tried to use an 8 or 9 in a octal number. +Interpretation of the octal number stopped before the 8 or 9. -=item Illegal hexadecimal digit %s ignored +=item Illegal switch in PERL5OPT: %s -(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. +(X) The PERL5OPT environment variable may only be used to set the +following switches: B<-[DIMUdmw]>. -=item Illegal number of bits in vec +=item Ill-formed CRTL environ value "%s" -(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). +(W internal) A warning peculiar to VMS. Perl tried to read the CRTL's +internal environ array, and encountered an element without the C<=> +delimiter used to separate keys from values. The element is ignored. -=item Illegal switch in PERL5OPT: %s +=item Ill-formed message in prime_env_iter: |%s| -(X) The PERL5OPT environment variable may only be used to set the -following switches: B<-[DIMUdmw]>. +(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. + +=item (in cleanup) %s -=item In string, @%s now must be written as \@%s +(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. -(F) It used to be that Perl would try to guess whether you wanted an -array interpolated or a literal @. It did this when the string was first -used at runtime. Now strings are parsed at compile time, and ambiguous -instances of @ must be disambiguated, either by prepending a backslash to -indicate a literal, or by declaring (or using) the array within the -program before the string (lexically). (Someday it will simply assume -that an unbackslashed @ interpolates an array.) +Failure of user callbacks dispatched using the C<G_KEEPERR> flag could +also result in this warning. See L<perlcall/G_KEEPERR>. =item Insecure dependency in %s (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 B<-T> 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 L<perlsec> -for more information. +The tainting mechanism is turned on when you're running setuid or +setgid, or when you specify B<-T> 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 +L<perlsec> for more information. =item Insecure directory in %s -(F) You can't use system(), exec(), or a piped open in a setuid or setgid -script if C<$ENV{PATH}> contains a directory that is writable by the world. -See L<perlsec>. +(F) You can't use system(), exec(), or a piped open in a setuid or +setgid script if C<$ENV{PATH}> contains a directory that is writable by +the world. See L<perlsec>. =item Insecure $ENV{%s} while running %s @@ -1707,33 +1614,44 @@ known value, using trustworthy data. See L<perlsec>. =item Integer overflow in %s number -(W 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 +(W 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. +=item Internal disaster before << HERE in regex m/%s/ + +(P) Something went badly wrong in the regular expression parser. +The << HERE shows in the regular expression about where the problem was +discovered. + + =item Internal inconsistency in tracking vforks -(S) A warning peculiar to VMS. Perl keeps track of the number -of times you've called C<fork> and C<exec>, to determine -whether the current call to C<exec> should affect the current -script or a subprocess (see L<perlvms/"exec LIST">). Somehow, this count -has become scrambled, so Perl is making a guess and treating -this C<exec> as a request to terminate the Perl script -and execute the specified command. +(S) A warning peculiar to VMS. Perl keeps track of the number of times +you've called C<fork> and C<exec>, to determine whether the current call +to C<exec> should affect the current script or a subprocess (see +L<perlvms/"exec LIST">). Somehow, this count has become scrambled, so +Perl is making a guess and treating this C<exec> as a request to +terminate the Perl script and execute the specified command. -=item internal disaster in regexp +=item Internal urp before << HERE in regex m/%s/ -(P) Something went badly wrong in the regular expression parser. +(P) Something went badly awry in the regular expression parser. The <<<HERE +shows in the regular expression about where the problem was discovered. -=item internal urp in regexp at /%s/ -(P) Something went badly awry in the regular expression parser. +=item %s (...) interpreted as function + +(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 +L<perlop/Terms and List Operators (Leftward)>. =item Invalid %s attribute: %s @@ -1742,52 +1660,63 @@ by Perl or by a user-supplied handler. See L<attributes>. =item Invalid %s attributes: %s -The indicated attributes for a subroutine or variable were not recognized -by Perl or by a user-supplied handler. See L<attributes>. +The indicated attributes for a subroutine or variable were not +recognized by Perl or by a user-supplied handler. See L<attributes>. + +=item Invalid conversion in %s: "%s" + +(W printf) Perl does not understand the given format conversion. See +L<perlfunc/sprintf>. =item invalid [] range "%s" in regexp (F) The range specified in a character class had a minimum character greater than the maximum character. See L<perlre>. -=item Invalid conversion in %s: "%s" - -(W printf) Perl does not understand the given format conversion. -See L<perlfunc/sprintf>. - =item Invalid separator character %s in attribute list (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 L<attributes>. +elements of an attribute list. If the previous attribute had a +parenthesised parameter list, perhaps that list was terminated too soon. +See L<attributes>. =item Invalid type in pack: '%s' (F) The given character is not a valid pack type. See L<perlfunc/pack>. -(W pack) The given character is not a valid pack type but used to be silently -ignored. +(W pack) The given character is not a valid pack type but used to be +silently ignored. =item Invalid type in unpack: '%s' -(F) The given character is not a valid unpack type. See L<perlfunc/unpack>. -(W unpack) The given character is not a valid unpack type but used to be silently -ignored. +(F) The given character is not a valid unpack type. See +L<perlfunc/unpack>. +(W unpack) The given character is not a valid unpack type but used to be +silently ignored. =item ioctl is not implemented (F) Your machine apparently doesn't implement ioctl(), which is pretty strange for a machine that supports C. +=item `%s' is not a code reference + +(W) The second (fourth, sixth, ...) argument of overload::constant needs +to be a code reference. Either an anonymous subroutine, or a reference +to a subroutine. + +=item `%s' is not an overloadable type + +(W) You tried to overload a constant type the overload package is unaware of. + =item junk on end of regexp (P) The regular expression parser is confused. =item Label not found for "last %s" -(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 L<perlfunc/last>. +(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 +L<perlfunc/last>. =item Label not found for "next %s" @@ -1808,14 +1737,62 @@ effective uids or gids failed. =item listen() on closed socket %s -(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 L<perlfunc/listen>. +(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 +L<perlfunc/listen>. + +=item Lookbehind longer than %d not implemented at {#} mark in regex %s + +There is an upper limit to the depth of lookbehind in the (?<= +regular expression construct. =item Lvalue subs returning %s not implemented yet (F) Due to limitations in the current implementation, array and hash -values cannot be returned in subroutines used in lvalue context. -See L<perlsub/"Lvalue subroutines">. +values cannot be returned in subroutines used in lvalue context. See +L<perlsub/"Lvalue subroutines">. + +=item Lookbehind longer than %d not implemented before << HERE %s + +(F) There is currently a limit on the length of string which lookbehind can +handle. This restriction may be eased in a future release. The << HERE shows in +the regular expression about where the problem was discovered. + +=item Malformed PERLLIB_PREFIX + +(F) An error peculiar to OS/2. PERLLIB_PREFIX should be of the form + + prefix1;prefix2 + +or + + prefix1 prefix2 + +with nonempty prefix1 and prefix2. If C<prefix1> 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 L<perlos2>. + +=item Malformed UTF-8 character (%s) + +Perl detected something that didn't comply with UTF-8 encoding rules. + +=item Malformed UTF-16 surrogate + +Perl thought it was reading UTF-16 encoded character data but while +doing it Perl met a malformed Unicode surrogate. + +=item %s matches null string many times + +(W regexp) The pattern you've specified would be an infinite loop if the +regular expression engine didn't specifically check for that. See +L<perlre>. + +=item % may only be used in unpack + +(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 L<perlfunc/unpack>. =item Method for operation %s not found in package %s during blessing @@ -1836,12 +1813,6 @@ ended earlier on the current line. (W syntax) An underline in a decimal constant wasn't on a 3-digit boundary. -=item Missing $ on loop variable - -(F) Apparently you've been programming in B<csh> too much. Variables are always -mentioned with the $ in Perl, unlike in the shells, where it can vary from -one line to the next. - =item Missing %sbrace%s on \N{} (F) Wrong syntax of character name literal C<\N{charname}> within @@ -1854,8 +1825,20 @@ double-quotish context. =item Missing command in piped open -(W pipe) You used the C<open(FH, "| command")> or C<open(FH, "command |")> -construction, but the command was missing or blank. +(W pipe) You used the C<open(FH, "| command")> or +C<open(FH, "command |")> construction, but the command was missing or +blank. + +=item Missing name in "my sub" + +(F) The reserved syntax for lexically scoped subroutines requires that +they have a name with which they can be found. + +=item Missing $ on loop variable + +(F) Apparently you've been programming in B<csh> too much. Variables +are always mentioned with the $ in Perl, unlike in the shells, where it +can vary from one line to the next. =item (Missing operator before %s?) @@ -1864,9 +1847,15 @@ found where operator expected". Often the missing operator is a comma. =item Missing right curly or square bracket -(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. +(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. + +=item (Missing semicolon on previous line?) + +(S) 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. =item Modification of a read-only value attempted @@ -1879,76 +1868,110 @@ catches that. But an easy way to do the same thing is: Another way is to assign to a substr() that's off the end of the string. -=item Modification of non-creatable array value attempted, subscript %d +Yet another way is to assign to a C<foreach> loop I<VAR> when I<VAR> +is aliased to a constant in the look I<LIST>: + + $x = 1; + foreach my $n ($x, 2) { + $n *= 2; # modifies the $x, but fails on attempt to modify the 2 + } + +=item Modification of non-creatable array value attempted, %s (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. -=item Modification of non-creatable hash value attempted, subscript "%s" +=item Modification of non-creatable hash value attempted, %s -(P) You tried to make a hash value spring into existence, and it couldn't -be created for some peculiar reason. +(P) You tried to make a hash value spring into existence, and it +couldn't be created for some peculiar reason. =item Module name must be constant (F) Only a bare module name is allowed as the first argument to a "use". +=item Module name required with -%c option + +(F) The C<-M> or C<-m> options say that Perl should load some module, but +you omitted the name of the module. Consult L<perlrun> for full details +about C<-M> and C<-m>. + =item msg%s not implemented (F) You don't have System V message IPC on your system. =item Multidimensional syntax %s not supported -(W syntax) Multidimensional arrays aren't written like C<$foo[1,2,3]>. They're written -like C<$foo[1][2][3]>, as in C. +(W syntax) Multidimensional arrays aren't written like C<$foo[1,2,3]>. +They're written like C<$foo[1][2][3]>, as in C. -=item Missing name in "my sub" +=item / must be followed by a*, A* or Z* + +(F) You had a pack template indicating a counted-length string, +Currently the only things that can have their length counted are a*, A* +or Z*. See L<perlfunc/pack>. -(F) The reserved syntax for lexically scoped subroutines requires that they -have a name with which they can be found. +=item / must be followed by a, A or Z + +(F) You had an unpack template indicating a counted-length string, which +must be followed by one of the letters a, A or Z to indicate what sort +of string is to be unpacked. See L<perlfunc/pack>. + +=item / must follow a numeric type + +(F) You had an unpack template that contained a '#', but this did not +follow some numeric unpack specification. See L<perlfunc/pack>. + +=item "my sub" not yet implemented + +(F) Lexically scoped subroutines are not yet implemented. Don't try +that yet. + +=item "my" variable %s can't be in a package + +(F) Lexically scoped variables aren't in a package, so it doesn't make +sense to try to declare one with a package qualifier on the front. Use +local() if you want to localize a package variable. =item Name "%s::%s" used only once: possible typo (W once) Typographical errors often show up as unique variable names. -If you had a good reason for having a unique name, then just mention -it again somehow to suppress the message. The C<our> declaration is +If you had a good reason for having a unique name, then just mention it +again somehow to suppress the message. The C<our> declaration is provided for this purpose. =item Negative length -(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. +(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. -=item nested *?+ in regexp +=item Nested quantifiers before << HERE in regex m/%s/ -(F) You can't quantify a quantifier without intervening parentheses. So -things like ** or +* or ?* are illegal. +(F) You can't quantify a quantifier without intervening parentheses. So +things like ** or +* or ?* are illegal. The << HERE shows in the regular +expression about where the problem was discovered. -Note, however, that the minimal matching quantifiers, C<*?>, C<+?>, and C<??> appear -to be nested quantifiers, but aren't. See L<perlre>. +Note, however, that the minimal matching quantifiers, C<*?>, C<+?>, and +C<??> appear to be nested quantifiers, but aren't. See L<perlre>. -=item No #! line -(F) The setuid emulator requires that scripts have a well-formed #! line -even on machines that don't support the #! construct. +=item %s never introduced + +(S internal) The symbol in question was declared but somehow went out of +scope before it could possibly have been used. =item No %s allowed while running setuid -(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 L<perlsec>. +(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 L<perlsec>. =item No B<-e> allowed in setuid scripts (F) A setuid script can't be specified by the user. -=item No %s specified for -%c - -(F) The indicated command line switch needs a mandatory argument, but -you haven't specified one. - =item No comma allowed after %s (F) A list operator that has a filehandle or "indirect object" is not @@ -1969,18 +1992,17 @@ this error was triggered? =item No command into which to pipe on command line -(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. +(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. =item No DB::DB routine defined -(F) The currently executing code was compiled with the B<-d> switch, -but for some reason the perl5db.pl file (or some facsimile thereof) -didn't define a routine to be called at the beginning of each -statement. Which is odd, because the file should have been required -automatically, and should have blown up the require if it didn't parse -right. +(F) The currently executing code was compiled with the B<-d> switch, but +for some reason the perl5db.pl file (or some facsimile thereof) didn't +define a routine to be called at the beginning of each statement. Which +is odd, because the file should have been required automatically, and +should have blown up the require if it didn't parse right. =item No dbm on this machine @@ -1996,33 +2018,43 @@ ordinary subroutine call. =item No error file after 2> or 2>> on command line -(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. +(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. =item No input file after < on command line -(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. +(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. + +=item No #! line + +(F) The setuid emulator requires that scripts have a well-formed #! line +even on machines that don't support the #! construct. + +=item "no" not allowed in expression + +(F) The "no" keyword is recognized and executed at compile time, and +returns no useful value. See L<perlmod>. =item No output file after > on command line -(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. +(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. =item No output file after > or >> on command line -(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. +(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. =item No package name allowed for variable %s in "our" -(F) Fully qualified variable names are not allowed in "our" declarations, -because that doesn't make much sense under existing semantics. Such -syntax is reserved for future extensions. +(F) Fully qualified variable names are not allowed in "our" +declarations, because that doesn't make much sense under existing +semantics. Such syntax is reserved for future extensions. =item No Perl script found in input @@ -2041,8 +2073,19 @@ your system. =item No space allowed after -%c -(F) The argument to the indicated command line switch must follow immediately -after the switch, without intervening spaces. +(F) The argument to the indicated command line switch must follow +immediately after the switch, without intervening spaces. + +=item No %s specified for -%c + +(F) The indicated command line switch needs a mandatory argument, but +you haven't specified one. + +=item No such pipe open + +(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. =item No such pseudo-hash field "%s" @@ -2052,36 +2095,23 @@ array indices for that to work. =item No such pseudo-hash field "%s" in variable %s of type %s -(F) You tried to access a field of a typed variable where the type -does not know about the field name. The field names are looked up in -the %FIELDS hash in the type package at compile time. The %FIELDS hash -is usually set up with the 'fields' pragma. - -=item No such pipe open - -(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. +(F) You tried to access a field of a typed variable where the type does +not know about the field name. The field names are looked up in the +%FIELDS hash in the type package at compile time. The %FIELDS hash is +%usually set up with the 'fields' pragma. =item No such signal: SIG%s -(W signal) You specified a signal name as a subscript to %SIG that was not recognized. -Say C<kill -l> in your shell to see the valid signal names on your system. - -=item no UTC offset information; assuming local time is UTC - -(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 F<SYS$TIMEZONE_DIFFERENTIAL> -to translate to the number of seconds which need to be added to UTC to -get local time. +(W signal) You specified a signal name as a subscript to %SIG that was +not recognized. Say C<kill -l> in your shell to see the valid signal +names on your system. =item Not a CODE reference (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 L<perlref>. +use the ref() function to find out what kind of ref it really was. See +also L<perlref>. =item Not a format reference @@ -2090,16 +2120,22 @@ format, but this indicates you did, and that it didn't exist. =item Not a GLOB reference -(F) Perl was trying to evaluate a reference to a "typeglob" (that is, -a symbol table entry that looks like C<*foo>), 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 L<perlref>. +(F) Perl was trying to evaluate a reference to a "typeglob" (that is, a +symbol table entry that looks like C<*foo>), 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 L<perlref>. =item Not a HASH reference -(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 L<perlref>. +(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 L<perlref>. + +=item Not an ARRAY reference + +(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 L<perlref>. =item Not a perl script @@ -2109,41 +2145,54 @@ mention perl. =item Not a SCALAR reference -(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 L<perlref>. +(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 L<perlref>. =item Not a subroutine reference (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 L<perlref>. +use the ref() function to find out what kind of ref it really was. See +also L<perlref>. =item Not a subroutine reference in overload table (F) An attempt was made to specify an entry in an overloading table that doesn't somehow point to a valid subroutine. See L<overload>. -=item Not an ARRAY reference - -(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 L<perlref>. - =item Not enough arguments for %s (F) The function requires more arguments than you specified. =item Not enough format arguments -(W syntax) A format specified more picture fields than the next line supplied. -See L<perlform>. +(W syntax) A format specified more picture fields than the next line +supplied. See L<perlform>. + +=item %s: not found + +(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. + +=item no UTC offset information; assuming local time is UTC + +(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 +F<SYS$TIMEZONE_DIFFERENTIAL> to translate to the number of seconds which +need to be added to UTC to get local time. =item Null filename used -(F) You can't require the null filename, especially because on many machines -that means the current directory! See L<perlfunc/require>. +(F) You can't require the null filename, especially because on many +machines that means the current directory! See L<perlfunc/require>. + +=item NULL OP IN RUN + +(P debugging) Some internal routine called run() with a null opcode +pointer. =item Null picture in formline @@ -2151,10 +2200,6 @@ that means the current directory! See L<perlfunc/require>. specification. It was found to be empty, which probably means you supplied it an uninitialized value. See L<perlform>. -=item NULL OP IN RUN - -(P debugging) Some internal routine called run() with a null opcode pointer. - =item Null realloc (P) An attempt was made to realloc NULL. @@ -2169,36 +2214,53 @@ supplied it an uninitialized value. See L<perlform>. =item Number too long -(F) Perl limits the representation of decimal numbers in programs to about -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"). +(F) Perl limits the representation of decimal numbers in programs to +about 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"). + +=item Octal number in vector unsupported + +(F) Numbers with a leading C<0> are not currently allowed in vectors. +The octal number interpretation of such numbers may be supported in a +future version. =item Octal number > 037777777777 non-portable -(W portable) The octal number you specified is larger than 2**32-1 (4294967295) -and therefore non-portable between systems. See L<perlport> for more -on portability concerns. +(W portable) The octal number you specified is larger than 2**32-1 +(4294967295) and therefore non-portable between systems. See +L<perlport> for more on portability concerns. See also L<perlport> for writing portable code. -=item Octal number in vector unsupported +=item Odd number of arguments for overload::constant -(F) Numbers with a leading C<0> are not currently allowed in vectors. The -octal number interpretation of such numbers may be supported in a future -version. +(W) The call to overload::constant contained an odd number of arguments. +The arguments should come in pairs. =item Odd number of elements in hash assignment -(W misc) You specified an odd number of elements to initialize a hash, which -is odd, because hashes come in key/value pairs. +(W misc) You specified an odd number of elements to initialize a hash, +which is odd, because hashes come in key/value pairs. =item Offset outside string (F) You tried to do a read/write/send/recv operation with an offset -pointing outside the buffer. This is difficult to imagine. -The sole exception to this is that C<sysread()>ing past the buffer -will extend the buffer and zero pad the new area. +pointing outside the buffer. This is difficult to imagine. The sole +exception to this is that C<sysread()>ing past the buffer will extend +the buffer and zero pad the new area. + +=item -%s on unopened filehandle %s + +(W unopened) You tried to invoke a file test operator on a filehandle +that isn't open. Check your logic. See also L<perlfunc/-X>. + +=item %s() on unopened %s %s + +(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. =item oops: oopsAV @@ -2210,59 +2272,82 @@ will extend the buffer and zero pad the new area. =item Operation `%s': no method found, %s -(F) An attempt was made to perform an overloaded operation for which -no handler was defined. While some handlers can be autogenerated in -terms of other handlers, there is no default handler for any -operation, unless C<fallback> overloading key is specified to be -true. See L<overload>. +(F) An attempt was made to perform an overloaded operation for which no +handler was defined. While some handlers can be autogenerated in terms +of other handlers, there is no default handler for any operation, unless +C<fallback> overloading key is specified to be true. See L<overload>. =item Operator or semicolon missing before %s -(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'". +(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'". + +=item "our" variable %s redeclared + +(W misc) You seem to have already declared the same global once before +in the current lexical scope. =item Out of memory! (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. +remaining memory (or virtual memory) to satisfy the request. Perl has +no option but to exit immediately. -=item Out of memory for yacc stack +=item Out of memory during "large" request for %s -(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. +(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. =item Out of memory during request for %s -(X|F) The malloc() function returned 0, indicating there was insufficient -remaining memory (or virtual memory) to satisfy the request. +(X|F) The malloc() function returned 0, indicating there was +insufficient remaining memory (or virtual memory) to satisfy the +request. 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 C<$^M> as -an emergency pool after die()ing with this message. In this case the -error is trappable I<once>. - -=item Out of memory during "large" request for %s - -(F) The malloc() function returned 0, indicating there was insufficient -remaining memory (or virtual memory) to satisfy the request. However, -the request was judged large enough (compile-time default is 64K), so -a possibility to shut down by trapping this error is granted. +However, if compiled for this, Perl may use the contents of C<$^M> as an +emergency pool after die()ing with this message. In this case the error +is trappable I<once>, and the error message will include the line and file +where the failed request happened. =item Out of memory during ridiculously large request (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., C<$arr[time]> -instead of C<$arr[$time]>. +is most likely to be caused by a typo in the Perl program. e.g., +C<$arr[time]> instead of C<$arr[$time]>. + +=item Out of memory for yacc stack + +(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. + +=item @ outside of string + +(F) You had a pack template that specified an absolute position outside +the string being unpacked. See L<perlfunc/pack>. + +=item %s package attribute may clash with future reserved word: %s + +(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 L<attributes>. =item page overflow -(W io) A single call to write() produced more lines than can fit on a page. -See L<perlform>. +(W io) A single call to write() produced more lines than can fit on a +page. See L<perlform>. + +=item panic: %s + +(P) An internal error. =item panic: ck_grep @@ -2274,8 +2359,8 @@ See L<perlform>. =item panic: corrupt saved stack index -(P) The savestack was requested to restore more localized values than there -are in the savestack. +(P) The savestack was requested to restore more localized values than +there are in the savestack. =item panic: del_backref @@ -2287,21 +2372,20 @@ reference. (P) We popped the context stack to an eval context, and then discovered it wasn't an eval context. -=item panic: do_match +=item panic: pp_match -(P) The internal pp_match() routine was called with invalid operational data. - -=item panic: do_split - -(P) Something terrible went wrong in setting up for the split. +(P) The internal pp_match() routine was called with invalid operational +data. =item panic: do_subst -(P) The internal pp_subst() routine was called with invalid operational data. +(P) The internal pp_subst() routine was called with invalid operational +data. -=item panic: do_trans +=item panic: do_trans_%s -(P) The internal do_trans() routine was called with invalid operational data. +(P) The internal do_trans routines were called with invalid operational +data. =item panic: frexp @@ -2331,22 +2415,23 @@ it wasn't a block context. =item panic: leave_scope clearsv -(P) A writable lexical variable became read-only somehow within the scope. +(P) A writable lexical variable became read-only somehow within the +scope. =item panic: leave_scope inconsistency (P) The savestack probably got out of sync. At least, there was an invalid enum on the top of it. -=item panic: malloc - -(P) Something requested a negative number of bytes of malloc. - =item panic: magic_killbackrefs (P) Failed an internal consistency check while trying to reset all weak references to an object. +=item panic: malloc + +(P) Something requested a negative number of bytes of malloc. + =item panic: mapstart (P) The compiler is screwed up with respect to the map() function. @@ -2391,6 +2476,10 @@ and freeing temporaries and lexicals from. (P) The foreach iterator got called in a non-loop context frame. +=item panic: pp_split + +(P) Something terrible went wrong in setting up for the split. + =item panic: realloc (P) Something requested a negative number of bytes of realloc. @@ -2422,9 +2511,10 @@ was string. (P) The lexer got into a bad state while processing a case modifier. -=item panic: %s +=item panic: utf16_to_utf8: odd bytelen -(P) An internal error. +(P) Something tried to call utf16_to_utf8 with an odd (as opposed +to even) byte length. =item Parentheses missing around "%s" list @@ -2438,11 +2528,38 @@ when you meant Remember that "my", "our", and "local" bind tighter than comma. -=item Perl %3.3f required--this is only version %s, stopped +=item Perl %s required--this is only version %s, stopped + +(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 L<perlfunc/require>. -(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 L<perlfunc/require>. +=item PERL_SH_DIR too long + +(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the +C<sh>-shell in. See "PERL_SH_DIR" in L<perlos2>. + +=item perl: warning: Setting locale failed. + +(S) The whole warning message will look something like: + + 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"). + +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, the script will be run. Before you really fix +the problem, however, you will get the same error message each time +you run Perl. How to really fix the problem can be found in +L<perllocale> section B<LOCALE PROBLEMS>. =item Permission denied @@ -2450,25 +2567,49 @@ anyway? See L<perlfunc/require>. =item pid %x not a child -(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. +(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. + +=item POSIX syntax [%s] belongs inside character classes + +(W unsafe) The character class constructs [: :], [= =], and [. .] go +I<inside> character classes, the [] are part of the construct, for +example: /[012[:alpha:]345]/. Note that [= =] and [. .] are not +currently implemented; they are simply placeholders for future +extensions and will cause fatal errors. + +=item POSIX syntax [. .] is reserved for future extensions + +(F regexp) Within regular expression character classes ([]) the syntax +beginning with "[." and ending with ".]" is reserved for future +extensions. If you need to represent those character sequences inside +a regular expression character class, just quote the square brackets +with the backslash: "\[." and ".\]". + +=item POSIX syntax [= =] is reserved for future extensions + +(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 "=\]". + +=item POSIX class [:%s:] unknown + +(F) The class in the character class [: :] syntax is unknown. See +L<perlre>. =item POSIX getpgrp can't take an argument (F) Your system has POSIX getpgrp(), which takes no argument, unlike the BSD version, which takes a pid. -=item Possible Y2K bug: %s - -(W y2k) You are concatenating the number 19 with another number, which -could be a potential Year 2000 problem. - =item Possible attempt to put comments in qw() list (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 +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.) You probably wrote something like this: @@ -2495,10 +2636,10 @@ old-fashioned way, with quotes and commas: =item Possible attempt to separate words with commas -(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.) +(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.) You probably wrote something like this: @@ -2516,9 +2657,14 @@ 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 L<perlfunc/ioctl>. +=item Possible Y2K bug: %s + +(W y2k) You are concatenating the number 19 with another number, which +could be a potential Year 2000 problem. + =item pragma "attrs" is deprecated, use "sub NAME : ATTRS" instead -(W deprecated) You have written somehing like this: +(W deprecated) You have written something like this: sub doit { @@ -2544,55 +2690,77 @@ is now misinterpreted as open(FOO || die); -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 "||". +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 "||". =item Premature end of script headers See Server error. +=item printf() on closed filehandle %s + +(W closed) The filehandle you're writing to got itself closed sometime +before now. Check your logic flow. + =item print() on closed filehandle %s -(W closed) The filehandle you're printing on got itself closed sometime before now. -Check your logic flow. +(W closed) The filehandle you're printing on got itself closed sometime +before now. Check your logic flow. -=item printf() on closed filehandle %s +=item Process terminated by SIG%s -(W closed) The filehandle you're writing to got itself closed sometime before now. -Check your logic flow. +(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 +L<perlipc/"Signals">. See also "Process terminated by SIGTERM/SIGINT" +in L<perlos2>. =item Prototype mismatch: %s vs %s -(S unsafe) The subroutine being declared or defined had previously been declared -or defined with a different function prototype. +(S unsafe) The subroutine being declared or defined had previously been +declared or defined with a different function prototype. + +=item Quantifier in {,} bigger than %d before << HERE in regex m/%s/ + +(F) There is currently a limit to the size of the min and max values of the +{min,max} construct. The << HERE shows in the regular expression about where +the problem was discovered. See L<perlre>. + +=item Quantifier unexpected on zero-length expression before << HERE %s + +(W regexp) You applied a regular expression quantifier in a place where +it makes no sense, such as on a zero-width assertion. Try putting the +quantifier inside the assertion instead. For example, the way to match +"abc" provided that it is followed by three repetitions of "xyz" is +C</abc(?=(?:xyz){3})/>, not C</abc(?=xyz){3}/>. =item Range iterator outside integer range (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. +One possible workaround is to force Perl to use magical string increment +by prepending "0" to your numbers. =item readline() on closed filehandle %s -(W closed) The filehandle you're reading from got itself closed sometime before now. -Check your logic flow. - -=item realloc() of freed memory ignored - -(S malloc) An internal routine called realloc() on something that had already -been freed. +(W closed) The filehandle you're reading from got itself closed sometime +before now. Check your logic flow. =item Reallocation too large: %lx (F) You can't allocate more than 64K on an MS-DOS machine. +=item realloc() of freed memory ignored + +(S malloc) An internal routine called realloc() on something that had +already been freed. + =item Recompile perl with B<-D>DEBUGGING to use B<-D> switch -(F debugging) You can't use the B<-D> option unless the code to produce the -desired output is compiled into Perl, which entails some overhead, +(F debugging) You can't use the B<-D> option unless the code to produce +the desired output is compiled into Perl, which entails some overhead, which is why it's currently left out of your copy. =item Recursive inheritance detected in package '%s' @@ -2600,17 +2768,18 @@ which is why it's currently left out of your copy. (F) More than 100 levels of inheritance were used. Probably indicates an unintended loop in your inheritance hierarchy. -=item Recursive inheritance detected while looking for method '%s' in package '%s' +=item Recursive inheritance detected while looking for method %s -(F) More than 100 levels of inheritance were encountered while invoking a -method. Probably indicates an unintended loop in your inheritance hierarchy. +(F) More than 100 levels of inheritance were encountered while invoking +a method. Probably indicates an unintended loop in your inheritance +hierarchy. =item Reference found where even-sized list expected -(W misc) You gave a single reference where Perl was expecting a list with -an even number of elements (for assignment to a hash). This -usually means that you used the anon hash constructor when you meant -to use parens. In any case, a hash requires key/value B<pairs>. +(W misc) You gave a single reference where Perl was expecting a list +with an even number of elements (for assignment to a hash). This usually +means that you used the anon hash constructor when you meant to use +parens. In any case, a hash requires key/value B<pairs>. %hash = { one => 1, two => 2, }; # WRONG %hash = [ qw/ an anon array / ]; # WRONG @@ -2624,37 +2793,43 @@ Doing so has no effect. =item Reference miscount in sv_replace() -(W internal) The internal sv_replace() function was handed a new SV with a -reference count of other than 1. +(W internal) The internal sv_replace() function was handed a new SV with +a reference count of other than 1. + +=item Reference to nonexistent group before << HERE in regex m/%s/ -=item regexp *+ operand could be empty +(F) You used something like C<\7> in your regular expression, but there are +not at least seven sets of capturing parentheses in the expression. If you +wanted to have the character with value 7 inserted into the regular expression, +prepend a zero to make the number at least two digits: C<\07> -(F) The part of the regexp subject to either the * or + quantifier -could match an empty string. +The << HERE shows in the regular expression about where the problem was +discovered. =item regexp memory corruption (P) The regular expression engine got confused by what the regular expression compiler gave it. -=item regexp out of space +=item Regexp out of space -(P) A "can't happen" error, because safemalloc() should have caught it earlier. +(P) A "can't happen" error, because safemalloc() should have caught it +earlier. =item Repeat count in pack overflows -(F) You can't specify a repeat count so large that it overflows -your signed integers. See L<perlfunc/pack>. +(F) You can't specify a repeat count so large that it overflows your +signed integers. See L<perlfunc/pack>. =item Repeat count in unpack overflows -(F) You can't specify a repeat count so large that it overflows -your signed integers. See L<perlfunc/unpack>. +(F) You can't specify a repeat count so large that it overflows your +signed integers. See L<perlfunc/unpack>. =item Reversed %s= operator -(W syntax) You wrote your assignment operator backwards. The = must always -comes last, to avoid ambiguity with subsequent unary operators. +(W syntax) You wrote your assignment operator backwards. The = must +always comes last, to avoid ambiguity with subsequent unary operators. =item Runaway format @@ -2666,12 +2841,13 @@ shifting or popping (for array variables). See L<perlform>. =item Scalar value @%s[%s] better written as $%s[%s] -(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 C<$foo[&bar]> always behaves like a scalar, both when -assigning to it and when evaluating its argument, while C<@foo[&bar]> 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. +(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 C<$foo[&bar]> always +behaves like a scalar, both when assigning to it and when evaluating its +argument, while C<@foo[&bar]> 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. 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 @@ -2680,18 +2856,26 @@ L<perlref>. =item Scalar value @%s{%s} better written as $%s{%s} -(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 C<$foo{&bar}> always behaves like a scalar, both when -assigning to it and when evaluating its argument, while C<@foo{&bar}> 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. - -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 +(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 C<$foo{&bar}> always behaves +like a scalar, both when assigning to it and when evaluating its +argument, while C<@foo{&bar}> 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. + +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 L<perlref>. +=item Scalars leaked: %d + +(P) Something went wrong in Perl's internal bookkeeping of scalars: +not all scalar variables were deallocated by the time Perl exited. +What this usually indicates is a memory leak, which is of course bad, +especially if the Perl program is intended to be long-running. + =item Script is not setuid/setgid in suidperl (F) Oddly, the suidperl program was invoked on a script without a setuid @@ -2703,71 +2887,84 @@ or setgid bit set. This doesn't make much sense. construct. Remember that bracketing delimiters count nesting level. Missing the leading C<$> from a variable C<$m> may cause this error. -=item %sseek() on unopened file +=item %sseek() on unopened filehandle -(W unopened) You tried to use the seek() or sysseek() function on a filehandle that -was either never opened or has since been closed. +(W unopened) You tried to use the seek() or sysseek() function on a +filehandle that was either never opened or has since been closed. =item select not implemented (F) This machine doesn't implement the select() system call. -=item sem%s not implemented +=item Semicolon seems to be missing -(F) You don't have System V semaphore IPC on your system. +(W semicolon) A nearby syntax error was probably caused by a missing +semicolon, or possibly some other missing operator, such as a comma. =item semi-panic: attempt to dup freed string -(S internal) The internal newSVsv() routine was called to duplicate a scalar -that had previously been marked as free. +(S internal) The internal newSVsv() routine was called to duplicate a +scalar that had previously been marked as free. -=item Semicolon seems to be missing +=item sem%s not implemented -(W semicolon) A nearby syntax error was probably caused by a missing semicolon, -or possibly some other missing operator, such as a comma. +(F) You don't have System V semaphore IPC on your system. =item send() on closed socket %s -(W closed) The socket you're sending to got itself closed sometime before now. -Check your logic flow. +(W closed) The socket you're sending to got itself closed sometime +before now. Check your logic flow. -=item Sequence (? incomplete +=item Sequence (? incomplete before << HERE mark in regex m/%s/ -(F) A regular expression ended with an incomplete extension (?. -See L<perlre>. +(F) A regular expression ended with an incomplete extension (?. The <<<HERE +shows in the regular expression about where the problem was discovered. See +L<perlre>. -=item Sequence (?#... not terminated +=item Sequence (?{...}) not terminated or not {}-balanced in %s -(F) A regular expression comment must be terminated by a closing -parenthesis. Embedded parentheses aren't allowed. See L<perlre>. +(F) If the contents of a (?{...}) clause contains braces, they must balance +for Perl to properly detect the end of the clause. See L<perlre>. -=item Sequence (?%s...) not implemented +=item Sequence (?%s...) not implemented before << HERE mark in %s -(F) A proposed regular expression extension has the character reserved -but has not yet been written. See L<perlre>. +(F) A proposed regular expression extension has the character reserved but +has not yet been written. The << HERE shows in the regular expression about +where the problem was discovered. See L<perlre>. -=item Sequence (?%s...) not recognized +=item Sequence (?%s...) not recognized before << HERE mark in %s (F) You used a regular expression extension that doesn't make sense. +The << HERE shows in the regular expression about +where the problem was discovered. See L<perlre>. +=item Sequence (?#... not terminated in regex m/%s/ + +(F) A regular expression comment must be terminated by a closing +parenthesis. Embedded parentheses aren't allowed. See L<perlre>. + +=item 500 Server error + +See Server error. + =item Server error 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". +to run a CGI program (including SSI) over the web. The actual error text +varies widely from server to server. The most frequently-seen variants +are "500 Server error", "Method (something) not permitted", "Document +contains no data", "Premature end of script headers", and "Did not +produce a valid header". B<This is a CGI error, not a Perl error>. -You need to make sure your script is executable, is accessible by the user -CGI is running the script under (which is probably not the user account you -tested it under), does not rely on any environment variables (like PATH) -from the user it isn't running under, and isn't in a location where the CGI -server can't find it, basically, more or less. Please see the following -for more information: +You need to make sure your script is executable, is accessible by the +user CGI is running the script under (which is probably not the user +account you tested it under), does not rely on any environment variables +(like PATH) from the user it isn't running under, and isn't in a +location where the CGI server can't find it, basically, more or less. +Please see the following for more information: http://www.perl.com/CPAN/doc/FAQs/cgi/idiots-guide.html http://www.perl.com/CPAN/doc/FAQs/cgi/perl-cgi-faq.html @@ -2779,50 +2976,70 @@ You should also look at L<perlfaq9>. =item setegid() not implemented -(F) You tried to assign to C<$)>, and your operating system doesn't support -the setegid() system call (or equivalent), or at least Configure didn't -think so. +(F) You tried to assign to C<$)>, and your operating system doesn't +support the setegid() system call (or equivalent), or at least Configure +didn't think so. =item seteuid() not implemented -(F) You tried to assign to C<< $> >>, and your operating system doesn't support -the seteuid() system call (or equivalent), or at least Configure didn't -think so. +(F) You tried to assign to C<< $> >>, and your operating system doesn't +support the seteuid() system call (or equivalent), or at least Configure +didn't think so. =item setpgrp can't take arguments -(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. +(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. =item setrgid() not implemented -(F) You tried to assign to C<$(>, and your operating system doesn't support -the setrgid() system call (or equivalent), or at least Configure didn't -think so. +(F) You tried to assign to C<$(>, and your operating system doesn't +support the setrgid() system call (or equivalent), or at least Configure +didn't think so. =item setruid() not implemented -(F) You tried to assign to C<$<>, and your operating system doesn't support -the setruid() system call (or equivalent), or at least Configure didn't -think so. +(F) You tried to assign to C<$<>, and your operating system doesn't +support the setruid() system call (or equivalent), or at least Configure +didn't think so. + +=item setsockopt() on closed socket %s + +(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 +L<perlfunc/setsockopt>. =item Setuid/gid script is writable by world -(F) The setuid emulator won't run a script that is writable by the world, -because the world might have written on it already. +(F) The setuid emulator won't run a script that is writable by the +world, because the world might have written on it already. =item shm%s not implemented (F) You don't have System V shared memory IPC on your system. +=item <> should be quotes + +(F) You wrote C<< require <file> >> when you should have written +C<require 'file'>. + +=item /%s/ should probably be written as "%s" + +(W syntax) You have used a pattern where Perl expected to find a string, +as in the first argument to C<join>. 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. + =item shutdown() on closed socket %s -(W closed) You tried to do a shutdown on a closed socket. Seems a bit superfluous. +(W closed) You tried to do a shutdown on a closed socket. Seems a bit +superfluous. =item SIG%s handler "%s" not defined -(W signal) The signal handler named in %SIG doesn't, in fact, exist. Perhaps you -put it into the wrong package? +(W signal) The signal handler named in %SIG doesn't, in fact, exist. +Perhaps you put it into the wrong package? =item sort is now a reserved word @@ -2842,36 +3059,28 @@ or less than one element. See L<perlfunc/sort>. =item Split loop -(P) The split was looping infinitely. (Obviously, a split shouldn't iterate -more times than there are characters of input, which is what happened.) -See L<perlfunc/split>. - -=item Stat on unopened file <%s> - -(W unopened) You tried to use the stat() function (or an equivalent file test) -on a filehandle that was either never opened or has since been closed. +(P) The split was looping infinitely. (Obviously, a split shouldn't +iterate more times than there are characters of input, which is what +happened.) See L<perlfunc/split>. =item Statement unlikely to be reached -(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. +(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. -=item Strange *+?{} on zero-length expression +=item stat() on unopened filehandle %s -(W regexp) You applied a regular expression quantifier in a place where it -makes no sense, such as on a zero-width assertion. -Try putting the quantifier inside the assertion instead. For example, -the way to match "abc" provided that it is followed by three -repetitions of "xyz" is C</abc(?=(?:xyz){3})/>, not C</abc(?=xyz){3}/>. +(W unopened) You tried to use the stat() function on a filehandle that +was either never opened or has since been closed. -=item Stub found while resolving method `%s' overloading `%s' in package `%s' +=item Stub found while resolving method `%s' overloading %s -(P) Overloading resolution over @ISA tree may be broken by importation stubs. -Stubs should never be implicitely created, but explicit calls to C<can> -may break this. +(P) Overloading resolution over @ISA tree may be broken by importation +stubs. Stubs should never be implicitly created, but explicit calls to +C<can> may break this. =item Subroutine %s redefined @@ -2884,9 +3093,9 @@ may break this. =item Substitution loop -(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 +(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 L<perlop/"Quote and Quote-like Operators">. =item Substitution pattern not terminated @@ -2903,21 +3112,39 @@ Missing the leading C<$> from variable C<$s> may cause this error. =item substr outside of string -(W substr),(F) You tried to reference a substr() that pointed outside of a -string. That is, the absolute value of the offset was larger than the -length of the string. See L<perlfunc/substr>. This warning is -fatal if substr is used in an lvalue context (as the left hand side -of an assignment or as a subroutine argument for example). +(W substr),(F) You tried to reference a substr() that pointed outside of +a string. That is, the absolute value of the offset was larger than the +length of the string. See L<perlfunc/substr>. This warning is fatal if +substr is used in an lvalue context (as the left hand side of an +assignment or as a subroutine argument for example). =item suidperl is no longer needed since %s -(F) Your Perl was compiled with B<-D>SETUID_SCRIPTS_ARE_SECURE_NOW, but a -version of the setuid emulator somehow got run anyway. +(F) Your Perl was compiled with B<-D>SETUID_SCRIPTS_ARE_SECURE_NOW, but +a version of the setuid emulator somehow got run anyway. + +=item Switch (?(condition)... contains too many branches before << HE%s + +(F) A (?(condition)if-clause|else-clause) construct can have at most two +branches (the if-clause and the else-clause). If you want one or both to +contain alternation, such as using C<this|that|other>, enclose it in +clustering parentheses: + + (?(condition)(?:this|that|other)|else-clause) + +The << HERE shows in the regular expression about where the problem was +discovered. See L<perlre>. + +=item Switch condition not recognized before << HERE in regex m/%s/ + +(F) If the argument to the (?(...)if-clause|else-clause) construct is a +number, it can be only a number. The << HERE shows in the regular expression +about where the problem was discovered. See L<perlre>. =item switching effective %s is not implemented -(F) While under the C<use filetest> pragma, we cannot switch the -real and effective uids or gids. +(F) While under the C<use filetest> pragma, we cannot switch the real +and effective uids or gids. =item syntax error @@ -2938,13 +3165,18 @@ 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 C<perl -c> repeatedly, chopping away half the program each time to see -if the error went away. Sort of the cybernetic version of S<20 questions>. +if the error went away. Sort of the cybernetic version of S<20 +questions>. =item syntax error at line %d: `%s' unexpected -(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. +(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. + +=item %s syntax OK + +(F) The final summary message when a C<perl -c> succeeds. =item System V %s is not implemented on this machine @@ -2955,28 +3187,23 @@ unconfigured. Consult your system support. =item syswrite() on closed filehandle %s -(W closed) The filehandle you're writing to got itself closed sometime before now. -Check your logic flow. +(W closed) The filehandle you're writing to got itself closed sometime +before now. Check your logic flow. =item Target of goto is too deeply nested -(F) You tried to use C<goto> to reach a label that was too deeply -nested for Perl to reach. Perl is doing you a favor by refusing. - -=item tell() on unopened file - -(W unopened) You tried to use the tell() function on a filehandle that was either -never opened or has since been closed. +(F) You tried to use C<goto> to reach a label that was too deeply nested +for Perl to reach. Perl is doing you a favor by refusing. -=item Test on unopened file <%s> +=item tell() on unopened filehandle -(W unopened) You tried to invoke a file test operator on a filehandle that isn't -open. Check your logic. See also L<perlfunc/-X>. +(W unopened) You tried to use the tell() function on a filehandle that +was either never opened or has since been closed. =item That use of $[ is unsupported -(F) Assignment to C<$[> is now strictly circumscribed, and interpreted as -a compiler directive. You may say only one of +(F) Assignment to C<$[> is now strictly circumscribed, and interpreted +as a compiler directive. You may say only one of $[ = 0; $[ = 1; @@ -2985,13 +3212,8 @@ a compiler directive. You may say only one of local $[ = 1; ... -This is to prevent the problem of one module changing the array base -out from under another module inadvertently. See L<perlvar/$[>. - -=item The %s function is unimplemented - -The function indicated isn't implemented on this architecture, according -to the probings of Configure. +This is to prevent the problem of one module changing the array base out +from under another module inadvertently. See L<perlvar/$[>. =item The crypt() function is unimplemented due to excessive paranoia @@ -3001,27 +3223,34 @@ 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. +=item The %s function is unimplemented + +The function indicated isn't implemented on this architecture, according +to the probings of Configure. + =item The stat preceding C<-l _> wasn't an lstat -(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. +(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. =item This Perl can't reset CRTL environ elements (%s) =item This Perl can't set CRTL environ elements (%s=%s) -(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 F<PERL_ENV_TABLES> (see -L<perlvms>) so that the environ array isn't the target of the change to +(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 +F<PERL_ENV_TABLES> (see L<perlvms>) so that the environ array isn't the +target of the change to %ENV which produced the warning. =item times not implemented -(F) Your version of the C library apparently doesn't do times(). I suspect -you're not running on Unix. +(F) Your version of the C library apparently doesn't do times(). I +suspect you're not running on Unix. =item Too few args to syscall @@ -3037,9 +3266,9 @@ script, it's too late to properly taint everything from the environment. So Perl gives up. If the Perl script is being executed as a command using the #! -mechanism (or its local equivalent), this error can usually be fixed -by editing the #! line so that the B<-T> option is a part of Perl's -first argument: e.g. change C<perl -n -T> to C<perl -T -n>. +mechanism (or its local equivalent), this error can usually be fixed by +editing the #! line so that the B<-T> option is a part of Perl's first +argument: e.g. change C<perl -n -T> to C<perl -T -n>. If the Perl script is being executed as C<perl scriptname>, then the B<-T> option must appear on the command line: C<perl -T scriptname>. @@ -3054,17 +3283,9 @@ are not intended for use inside scripts. Use the C<use> pragma instead. (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 C<require> or C<do> when you should be using -C<use> instead. Or perhaps you should put the C<require> or C<do> -inside a BEGIN block. - -=item Too many ('s - -=item Too many )'s - -(A) You've accidentally run your script through B<csh> instead -of Perl. Check the #! line, or manually feed your script into -Perl yourself. +loading a file with C<require> or C<do> when you should be using C<use> +instead. Or perhaps you should put the C<require> or C<do> inside a +BEGIN block. =item Too many args to syscall @@ -3074,10 +3295,17 @@ Perl yourself. (F) The function requires fewer arguments than you specified. +=item Too many )'s + +(A) You've accidentally run your script through B<csh> instead of Perl. +Check the #! line, or manually feed your script into Perl yourself. + +=item Too many ('s + =item trailing \ in regexp -(F) The regular expression ends with an unbackslashed backslash. Backslash -it. See L<perlre>. +(F) The regular expression ends with an unbackslashed backslash. +Backslash it. See L<perlre>. =item Transliteration pattern not terminated @@ -3109,8 +3337,8 @@ literals always start with 0 in Perl, as in C. =item umask not implemented -(F) Your machine doesn't implement the umask function and you tried -to use it to restrict permissions for yourself (EXPR & 0700). +(F) Your machine doesn't implement the umask function and you tried to +use it to restrict permissions for yourself (EXPR & 0700). =item Unable to create sub named "%s" @@ -3118,23 +3346,23 @@ to use it to restrict permissions for yourself (EXPR & 0700). =item Unbalanced context: %d more PUSHes than POPs -(W internal) The exit code detected an internal inconsistency in how many execution -contexts were entered and left. +(W internal) The exit code detected an internal inconsistency in how +many execution contexts were entered and left. =item Unbalanced saves: %d more saves than restores -(W internal) The exit code detected an internal inconsistency in how many -values were temporarily localized. +(W internal) The exit code detected an internal inconsistency in how +many values were temporarily localized. =item Unbalanced scopes: %d more ENTERs than LEAVEs -(W internal) The exit code detected an internal inconsistency in how many blocks -were entered and left. +(W internal) The exit code detected an internal inconsistency in how +many blocks were entered and left. =item Unbalanced tmps: %d more allocs than frees -(W internal) The exit code detected an internal inconsistency in how many mortal -scalars were allocated and freed. +(W internal) The exit code detected an internal inconsistency in how +many mortal scalars were allocated and freed. =item Undefined format "%s" called @@ -3143,13 +3371,13 @@ another package? See L<perlform>. =item Undefined sort subroutine "%s" called -(F) The sort comparison routine specified doesn't seem to exist. Perhaps -it's in a different package? See L<perlfunc/sort>. +(F) The sort comparison routine specified doesn't seem to exist. +Perhaps it's in a different package? See L<perlfunc/sort>. =item Undefined subroutine &%s called -(F) The subroutine indicated hasn't been defined, or if it was, it -has since been undefined. +(F) The subroutine indicated hasn't been defined, or if it was, it has +since been undefined. =item Undefined subroutine called @@ -3158,8 +3386,8 @@ or if it was, it has since been undefined. =item Undefined subroutine in sort -(F) The sort comparison routine specified is declared but doesn't seem to -have been defined yet. See L<perlfunc/sort>. +(F) The sort comparison routine specified is declared but doesn't seem +to have been defined yet. See L<perlfunc/sort>. =item Undefined top format "%s" called @@ -3168,17 +3396,36 @@ another package? See L<perlform>. =item Undefined value assigned to typeglob -(W misc) An undefined value was assigned to a typeglob, a la C<*foo = undef>. -This does nothing. It's possible that you really mean C<undef *foo>. +(W misc) An undefined value was assigned to a typeglob, a la +C<*foo = undef>. This does nothing. It's possible that you really mean +C<undef *foo>. + +=item %s: Undefined variable + +(A) You've accidentally run your script through B<csh> instead of Perl. +Check the #! line, or manually feed your script into Perl yourself. =item unexec of %s into %s failed! (F) The unexec() routine failed for some reason. See your local FSF representative, who probably put it there in the first place. + =item Unknown BYTEORDER -(F) There are no byte-swapping functions for a machine with this byte order. +(F) There are no byte-swapping functions for a machine with this byte +order. + +=item Unknown switch condition (?(%.2s before << HERE in regex m/%s/ + +(F) The condition of a (?(condition)if-clause|else-clause) construct is not +known. The condition may be lookaround (the condition is true if the +lookaround is true), a (?{...}) construct (the condition is true if the +code evaluates to a true value), or a number (the condition is true if the +set of capturing parentheses named by the number is defined). + +The << HERE shows in the regular expression about where the problem was +discovered. See L<perlre>. =item Unknown open() mode '%s' @@ -3193,30 +3440,32 @@ 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. -=item unmatched () in regexp +=item unmatched [ before << HERE mark in regex m/%s/ -(F) Unbackslashed parentheses must always be balanced in regular -expressions. If you're a vi user, the % key is valuable for finding -the matching parenthesis. See L<perlre>. +(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. See L<perlre>. The << HERE shows in the regular expression about +where the escape was discovered. -=item Unmatched right %s bracket +=item unmatched ( in regexp before << HERE mark in regex m/%s/ -(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. +(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. See L<perlre>. -=item unmatched [] in regexp +=item Unmatched right %s bracket -(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. -See L<perlre>. +(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. =item Unquoted string "%s" may clash with future reserved word -(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. +(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. =item Unrecognized character %s @@ -3224,238 +3473,295 @@ an underbar into it. You might also declare it as a subroutine. in your Perl script (or eval). Perhaps you tried to run a compressed script, a binary program, or a directory as a Perl program. +=item /%s/: Unrecognized escape \\%c in character class passed through + +(W regexp) You used a backslash-character combination which is not +recognized by Perl inside character classes. The character was +understood literally. + +=item Unrecognized escape \\%c passed through before << HERE in m/%s/ + +(W regexp) You used a backslash-character combination which is not +recognized by Perl. This combination appears in an interpolated variable or +a C<'>-delimited regular expression. The character was understood +literally. The << HERE shows in the regular expression about where the escape +was discovered. + + =item Unrecognized escape \\%c passed through -(W misc) You used a backslash-character combination which is not recognized -by Perl. +(W misc) You used a backslash-character combination which is not +recognized by Perl. =item Unrecognized signal name "%s" -(F) You specified a signal name to the kill() function that was not recognized. -Say C<kill -l> in your shell to see the valid signal names on your system. +(F) You specified a signal name to the kill() function that was not +recognized. Say C<kill -l> in your shell to see the valid signal names +on your system. =item Unrecognized switch: -%s (-h will show valid options) -(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.) +(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.) =item Unsuccessful %s on filename containing newline -(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 chop() or chomp() it off. See L<perlfunc/chomp>. +(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 L<perlfunc/chomp>. =item Unsupported directory function "%s" called (F) Your machine doesn't support opendir() and readdir(). +=item Unsupported function %s + +(F) This machine doesn't implement the indicated function, apparently. +At least, Configure doesn't think so. + =item Unsupported function fork (F) Your version of executable does not support forking. -Note that under some systems, like OS/2, there may be different flavors of -Perl executables, some of which may support fork, some not. Try changing -the name you call Perl by to C<perl_>, C<perl__>, and so on. +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 C<perl_>, C<perl__>, and so on. -=item Unsupported function %s +=item Unsupported script encoding -(F) This machine doesn't implement the indicated function, apparently. -At least, Configure doesn't think so. +(F) Your program file begins with a Unicode Byte Order Mark (BOM) which +declares it to be in a Unicode encoding that Perl cannot yet read. =item Unsupported socket function "%s" called (F) Your machine doesn't support the Berkeley socket mechanism, or at least that's what Configure thought. -=item Unterminated <> operator +=item Unterminated attribute list -(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". +(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 L<attributes>. =item Unterminated attribute parameter in attribute list -(F) The lexer saw an opening (left) parenthesis character while parsing an -attribute list, but the matching closing (right) parenthesis +(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 L<attributes>. -=item Unterminated attribute list +=item Unterminated compressed integer -(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 L<attributes>. +(F) An argument to unpack("w",...) was incompatible with the BER +compressed integer format and could not be converted to an integer. +See L<perlfunc/pack>. -=item Use of $# is deprecated +=item Unterminated <> operator -(D deprecated) This was an ill-advised attempt to emulate a poorly defined B<awk> feature. -Use an explicit printf() or sprintf() instead. +(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". -=item Use of $* is deprecated +=item untie attempted while %d inner references still exist -(D deprecated) This variable magically turned on multi-line pattern matching, both for -you and for any luckless subroutine that you happen to call. You should -use the new C<//m> and C<//s> modifiers now to do that without the dangerous -action-at-a-distance effects of C<$*>. +(W untie) A copy of the object returned from C<tie> (or C<tied>) was +still valid when C<untie> was called. -=item Use of %s in printf format not supported +=item Useless use of %s in void context -(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. +(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 -=item Use of bare << to mean <<"" is deprecated + $one, $two = 1, 2; -(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. +when you meant to say -=item Use of implicit split to @_ is deprecated + ($one, $two) = (1, 2); -(D deprecated) It makes a lot of work for the compiler when you clobber a -subroutine's argument list, so it's better if you assign the results of -a split() explicitly to an array (or list). +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 -=item Use of inherited AUTOLOAD for non-method %s() is deprecated + $array = (1,2); -(D deprecated) As an (ahem) accidental feature, C<AUTOLOAD> subroutines are -looked up as methods (using the C<@ISA> hierarchy) even when the subroutines -to be autoloaded were called as plain functions (e.g. C<Foo::bar()>), -not as methods (e.g. C<< Foo->bar() >> or C<< $obj->bar() >>). +when you should have said -This bug will be rectified in Perl 5.005, which will use method lookup -only for methods' C<AUTOLOAD>s. However, there is a significant base -of existing code that may be using the old behavior. So, as an -interim step, Perl 5.004 issues an optional warning when non-methods -use inherited C<AUTOLOAD>s. + $array = [1,2]; -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 C<AUTOLOAD> for non-methods from a base class named -C<BaseClass>, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during startup. +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 +L<perlref> for more on this. -In code that currently says C<use AutoLoader; @ISA = qw(AutoLoader);> you -should remove AutoLoader from @ISA and change C<use AutoLoader;> to -C<use AutoLoader 'AUTOLOAD';>. +=item Useless use of "re" pragma -=item Use of reserved word "%s" is deprecated +(W) You did C<use re;> without any arguments. That isn't very useful. -(D deprecated) The indicated bareword is a reserved word. Future versions of perl -may use it as a keyword, so you're better off either explicitly quoting -the word in a manner appropriate for its context of use, or using a -different name altogether. The warning can be suppressed for subroutine -names by either adding a C<&> prefix, or using a package qualifier, -e.g. C<&our()>, or C<Foo::our()>. +=item "use" not allowed in expression -=item Use of %s is deprecated +(F) The "use" keyword is recognized and executed at compile time, and +returns no useful value. See L<perlmod>. -(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. +=item Use of bare << to mean <<"" is deprecated -=item Use of uninitialized value%s +(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. -(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. +=item Use of implicit split to @_ is deprecated -=item Useless use of "re" pragma +(D deprecated) It makes a lot of work for the compiler when you clobber +a subroutine's argument list, so it's better if you assign the results +of a split() explicitly to an array (or list). -(W) You did C<use re;> without any arguments. That isn't very useful. +=item Use of inherited AUTOLOAD for non-method %s() is deprecated -=item Useless use of %s in void context +(D deprecated) As an (ahem) accidental feature, C<AUTOLOAD> subroutines +are looked up as methods (using the C<@ISA> hierarchy) even when the +subroutines to be autoloaded were called as plain functions (e.g. +C<Foo::bar()>), not as methods (e.g. C<< Foo->bar() >> or C<< +$obj->bar() >>). -(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 +This bug will be rectified in future by using method lookup only for +methods' C<AUTOLOAD>s. However, there is a significant base of existing +code that may be using the old behavior. So, as an interim step, Perl +currently issues an optional warning when non-methods use inherited +C<AUTOLOAD>s. - $one, $two = 1, 2; +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 C<AUTOLOAD> for non-methods from a base class +named C<BaseClass>, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during +startup. -when you meant to say +In code that currently says C<use AutoLoader; @ISA = qw(AutoLoader);> +you should remove AutoLoader from @ISA and change C<use AutoLoader;> to +C<use AutoLoader 'AUTOLOAD';>. - ($one, $two) = (1, 2); +=item Use of %s in printf format not supported -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 +(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. - $array = (1,2); +=item Use of $* is deprecated -when you should have said +(D deprecated) This variable magically turned on multi-line pattern +matching, both for you and for any luckless subroutine that you happen +to call. You should use the new C<//m> and C<//s> modifiers now to do +that without the dangerous action-at-a-distance effects of C<$*>. - $array = [1,2]; +=item Use of %s is deprecated -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 -L<perlref> for more on this. +(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. -=item untie attempted while %d inner references still exist +=item Use of $# is deprecated + +(D deprecated) This was an ill-advised attempt to emulate a poorly +defined B<awk> feature. Use an explicit printf() or sprintf() instead. -(W untie) A copy of the object returned from C<tie> (or C<tied>) was still -valid when C<untie> was called. +=item Use of reserved word "%s" is deprecated + +(D deprecated) The indicated bareword is a reserved word. Future +versions of perl may use it as a keyword, so you're better off either +explicitly quoting the word in a manner appropriate for its context of +use, or using a different name altogether. The warning can be +suppressed for subroutine names by either adding a C<&> prefix, or using +a package qualifier, e.g. C<&our()>, or C<Foo::our()>. + +=item Use of uninitialized value%s + +(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. + +To help you figure out what was undefined, perl tells you what operation +you used the undefined value in. Note, however, that perl optimizes your +program and the operation displayed in the warning may not necessarily +appear literally in your program. For example, C<"that $foo"> is +usually optimized into C<"that " . $foo>, and the warning will refer to +the C<concatenation (.)> operator, even though there is no C<.> in your +program. =item Value of %s can be "0"; test with defined() -(W misc) In a conditional expression, you used <HANDLE>, <*> (glob), C<each()>, -or C<readdir()> 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 C<defined> operator. +(W misc) In a conditional expression, you used <HANDLE>, <*> (glob), +C<each()>, or C<readdir()> 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 +C<defined> operator. =item Value of CLI symbol "%s" too long -(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. +(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. =item Variable "%s" is not imported%s -(F) While "use strict" in effect, you referred to a global variable -that you apparently thought was imported from another module, because -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. +(F) While "use strict" in effect, you referred to a global variable that +you apparently thought was imported from another module, because +something else of the same name (usually a subroutine) is exported by +that module. It usually means you put the wrong funny character on the +front of your variable. + +=item "%s" variable %s masks earlier declaration in same %s + +(W misc) A "my" or "our" variable has been redeclared in the current +scope or statement, effectively eliminating all access to the previous +instance. This is almost always a typographical error. Note that the +earlier variable will still exist until the end of the scope or until +all closure referents to it are destroyed. =item Variable "%s" may be unavailable -(W closure) An inner (nested) I<anonymous> subroutine is inside a I<named> -subroutine, and outside that is another subroutine; and the anonymous -(innermost) subroutine is referencing a lexical variable defined in -the outermost subroutine. For example: +(W closure) An inner (nested) I<anonymous> subroutine is inside a +I<named> subroutine, and outside that is another subroutine; and the +anonymous (innermost) subroutine is referencing a lexical variable +defined in the outermost subroutine. For example: sub outermost { my $a; sub middle { sub { $a } } } If the anonymous subroutine is called or referenced (directly or -indirectly) from the outermost subroutine, it will share the variable -as you would expect. But if the anonymous subroutine is called or -referenced when the outermost subroutine is not active, it will see -the value of the shared variable as it was before and during the -*first* call to the outermost subroutine, which is probably not what -you want. - -In these circumstances, it is usually best to make the middle -subroutine anonymous, using the C<sub {}> syntax. Perl has specific -support for shared variables in nested anonymous subroutines; a named -subroutine in between interferes with this feature. +indirectly) from the outermost subroutine, it will share the variable as +you would expect. But if the anonymous subroutine is called or +referenced when the outermost subroutine is not active, it will see the +value of the shared variable as it was before and during the *first* +call to the outermost subroutine, which is probably not what you want. + +In these circumstances, it is usually best to make the middle subroutine +anonymous, using the C<sub {}> syntax. Perl has specific support for +shared variables in nested anonymous subroutines; a named subroutine in +between interferes with this feature. + +=item Variable syntax + +(A) You've accidentally run your script through B<csh> instead +of Perl. Check the #! line, or manually feed your script into +Perl yourself. =item Variable "%s" will not stay shared -(W closure) An inner (nested) I<named> subroutine is referencing a lexical -variable defined in an outer subroutine. +(W closure) An inner (nested) I<named> subroutine is referencing a +lexical variable defined in an outer subroutine. When the inner subroutine is called, it will probably 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. +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. Furthermore, if the outer subroutine is anonymous and references a lexical variable outside itself, then the outer and inner subroutines @@ -3463,15 +3769,14 @@ will I<never> share the given variable. This problem can usually be solved by making the inner subroutine anonymous, using the C<sub {}> syntax. When inner anonymous subs that -reference variables in outer subroutines are called or referenced, -they are automatically rebound to the current values of such -variables. +reference variables in outer subroutines are called or referenced, they +are automatically rebound to the current values of such variables. -=item Variable syntax +=item Variable length lookbehind not implemented before << HERE in %s -(A) You've accidentally run your script through B<csh> instead -of Perl. Check the #! line, or manually feed your script into -Perl yourself. +(F) Lookbehind is allowed only for subexpressions whose length is fixed and +known at compile time. The << HERE shows in the regular expression about where +the problem was discovered. =item Version number must be a constant number @@ -3479,27 +3784,6 @@ Perl yourself. its equivalent C<BEGIN> block found an internal inconsistency with the version number. -=item perl: warning: Setting locale failed. - -(S) The whole warning message will look something like: - - 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"). - -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 system -administrator have set up the so-called variable system but Perl could -not use those settings. This was not dead serious, fortunately: there -is a "default locale" called "C" that Perl can and will use, the -script will be run. Before you really fix the problem, however, you -will get the same error message each time you run Perl. How to really -fix the problem can be found in L<perllocale> section B<LOCALE PROBLEMS>. - =item Warning: something's wrong (W) You passed warn() an empty string (the equivalent of C<warn "">) or @@ -3507,15 +3791,16 @@ you called it with no args and C<$_> was empty. =item Warning: unable to close filehandle %s properly -(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. +(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. =item Warning: Use of "%s" without parentheses is ambiguous -(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 +(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 rand + 5; @@ -3529,10 +3814,14 @@ but in actual fact, you got So put in parentheses to say what you really mean. +=item Wide character in %s + +(F) Perl met a wide character (>255) when it wasn't expecting one. + =item write() on closed filehandle %s -(W closed) The filehandle you're writing to got itself closed sometime before now. -Check your logic flow. +(W closed) The filehandle you're writing to got itself closed sometime +before now. Check your logic flow. =item X outside of string @@ -3546,99 +3835,34 @@ the end of the string being unpacked. See L<perlfunc/pack>. =item Xsub "%s" called in sort -(F) The use of an external subroutine as a sort comparison is not yet supported. +(F) The use of an external subroutine as a sort comparison is not yet +supported. =item Xsub called in sort -(F) The use of an external subroutine as a sort comparison is not yet supported. +(F) The use of an external subroutine as a sort comparison is not yet +supported. =item You can't use C<-l> on a filehandle -(F) 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. +(F) 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. Use a filename instead. =item YOU HAVEN'T DISABLED SET-ID SCRIPTS IN THE KERNEL YET! (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 use the wrapsuid script in -the eg directory to put a setuid C wrapper around your script. +about what you want. Your best bet is to use the wrapsuid script in the +eg directory to put a setuid C wrapper around your script. =item You need to quote "%s" -(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.) - -=item %cetsockopt() on closed socket %s - -(W closed) You tried to get or set a socket option on a closed socket. -Did you forget to check the return value of your socket() call? -See L<perlfunc/getsockopt> and L<perlfunc/setsockopt>. - -=item \1 better written as $1 - -(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. - -=item '|' and '<' may not both be specified on command line - -(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. - -=item '|' and '>' may not both be specified on command line - -(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 - - open(OUT,">$ARGV[0]") or die "Can't write to $ARGV[0]: $!"; - while (<STDIN>) { - print; - print OUT; - } - close OUT; - -=item Got an error from DosAllocMem - -(P) An error peculiar to OS/2. Most probably you're using an obsolete -version of Perl, and this should not happen anyway. - -=item Malformed PERLLIB_PREFIX - -(F) An error peculiar to OS/2. PERLLIB_PREFIX should be of the form - - prefix1;prefix2 - -or - - prefix1 prefix2 - -with nonempty prefix1 and prefix2. If C<prefix1> 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 F<README.os2>. - -=item PERL_SH_DIR too long - -(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the -C<sh>-shell in. See "PERL_SH_DIR" in F<README.os2>. - -=item Process terminated by SIG%s - -(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 -L<perlipc/"Signals">. See also "Process terminated by SIGTERM/SIGINT" -in F<README.os2>. +(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.) =back diff --git a/contrib/perl5/pod/perlembed.pod b/contrib/perl5/pod/perlembed.pod index c4df676b19c0..ecbe1f6706c0 100644 --- a/contrib/perl5/pod/perlembed.pod +++ b/contrib/perl5/pod/perlembed.pod @@ -37,25 +37,45 @@ Read on... =over 5 -L<Compiling your C program> +=item * -L<Adding a Perl interpreter to your C program> +Compiling your C program -L<Calling a Perl subroutine from your C program> +=item * -L<Evaluating a Perl statement from your C program> +Adding a Perl interpreter to your C program -L<Performing Perl pattern matches and substitutions from your C program> +=item * -L<Fiddling with the Perl stack from your C program> +Calling a Perl subroutine from your C program -L<Maintaining a persistent interpreter> +=item * -L<Maintaining multiple interpreter instances> +Evaluating a Perl statement from your C program -L<Using Perl modules, which themselves use C libraries, from your C program> +=item * -L<Embedding Perl under Win32> +Performing Perl pattern matches and substitutions from your C program + +=item * + +Fiddling with the Perl stack from your C program + +=item * + +Maintaining a persistent interpreter + +=item * + +Maintaining multiple interpreter instances + +=item * + +Using Perl modules, which themselves use C libraries, from your C program + +=item * + +Embedding Perl under Win32 =back @@ -258,9 +278,8 @@ and package C<END {}> blocks. If you want to pass arguments to the Perl subroutine, you can add strings to the C<NULL>-terminated C<args> list passed to I<call_argv>. For other data types, or to examine return values, -you'll need to manipulate the Perl stack. That's demonstrated in the -last section of this document: L<Fiddling with the Perl stack from -your C program>. +you'll need to manipulate the Perl stack. That's demonstrated in +L<Fiddling with the Perl stack from your C program>. =head2 Evaluating a Perl statement from your C program @@ -356,7 +375,7 @@ made. int matches(SV *string, char *pattern, AV **matches); Given an C<SV>, a pattern, and a pointer to an empty C<AV>, -matches() evaluates C<$string =~ $pattern> in an array context, and +matches() evaluates C<$string =~ $pattern> in a list context, and fills in I<matches> with the array elements, returning the number of matches found. Here's a sample program, I<match.c>, that uses all three (long lines have @@ -434,7 +453,7 @@ been wrapped here): /** matches(string, pattern, matches) ** - ** Used for matches in an array context. + ** Used for matches in a list context. ** ** Returns the number of matches, ** and fills in **matches with the matching substrings @@ -796,9 +815,11 @@ during a session. Such an application might sporadically decide to release any resources associated with the interpreter. The program must take care to ensure that this takes place I<before> -the next interpreter is constructed. By default, the global variable +the next interpreter is constructed. By default, when perl is not +built with any special options, the global variable C<PL_perl_destruct_level> is set to C<0>, since extra cleaning isn't -needed when a program has only one interpreter. +usually needed when a program only ever creates a single interpreter +in its entire lifetime. Setting C<PL_perl_destruct_level> to C<1> makes everything squeaky clean: @@ -820,9 +841,16 @@ When I<perl_destruct()> is called, the interpreter's syntax parse tree and symbol tables are cleaned up, and global variables are reset. Now suppose we have more than one interpreter instance running at the -same time. This is feasible, but only if you used the -C<-DMULTIPLICITY> flag when building Perl. By default, that sets -C<PL_perl_destruct_level> to C<1>. +same time. This is feasible, but only if you used the Configure option +C<-Dusemultiplicity> or the options C<-Dusethreads -Duseithreads> when +building Perl. By default, enabling one of these Configure options +sets the per-interpreter global variable C<PL_perl_destruct_level> to +C<1>, so that thorough cleaning is automatic. + +Using C<-Dusethreads -Duseithreads> rather than C<-Dusemultiplicity> +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. Let's give it a try: @@ -843,22 +871,41 @@ Let's give it a try: char *one_args[] = { "one_perl", SAY_HELLO }; char *two_args[] = { "two_perl", SAY_HELLO }; + 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); } +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. + +PERL_SET_CONTEXT(interp) should also be called whenever C<interp> is +used by a thread that did not create it (using either perl_alloc(), or +the more esoteric perl_clone()). Compile as usual: @@ -894,21 +941,14 @@ 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 I<perlmain.c> to see how Perl does this: + static void xs_init (pTHX); - #ifdef __cplusplus - # define EXTERN_C extern "C" - #else - # define EXTERN_C extern - #endif - - static void xs_init (void); - - EXTERN_C void boot_DynaLoader (CV* cv); - EXTERN_C void boot_Socket (CV* cv); + EXTERN_C void boot_DynaLoader (pTHX_ CV* cv); + EXTERN_C void boot_Socket (pTHX_ CV* cv); EXTERN_C void - xs_init() + xs_init(pTHX) { char *file = __FILE__; /* DynaLoader is a special case */ @@ -957,19 +997,11 @@ Consult L<perlxs>, L<perlguts>, and L<perlapi> for more details. =head1 Embedding Perl under Win32 -At the time of this writing (5.004), there are two versions of Perl -which run under Win32. (The two versions are merging in 5.005.) -Interfacing to ActiveState's Perl library is quite different from the -examples in this documentation, as significant changes were made to -the internal Perl API. However, it is possible to embed ActiveState's -Perl runtime. For details, see the Perl for Win32 FAQ at -http://www.perl.com/CPAN/doc/FAQs/win32/perlwin32faq.html. - -With the "official" Perl version 5.004 or higher, all the examples -within this documentation will compile and run untouched, although -the build process is slightly different between Unix and Win32. +In general, all of the source code shown here should work unmodified under +Windows. -For starters, backticks don't work under the Win32 native command shell. +However, there are some caveats about the command-line examples shown. +For starters, backticks won't work under the Win32 native command shell. The ExtUtils::Embed kit on CPAN ships with a script called B<genmake>, which generates a simple makefile to build a program from a single C source file. It can be used like this: diff --git a/contrib/perl5/pod/perlfaq.pod b/contrib/perl5/pod/perlfaq.pod index fa6943f0db0e..bc29c694f2c5 100644 --- a/contrib/perl5/pod/perlfaq.pod +++ b/contrib/perl5/pod/perlfaq.pod @@ -4,710 +4,1303 @@ perlfaq - frequently asked questions about Perl ($Date: 1999/05/23 20:38:02 $) =head1 DESCRIPTION -This document is structured into the following sections: +The perlfaq is structured into the following documents: -=over -=item perlfaq: Structural overview of the FAQ. +=head2 perlfaq: Structural overview of the FAQ. This document. -=item L<perlfaq1>: General Questions About Perl +=head2 L<perlfaq1>: General Questions About Perl Very general, high-level information about Perl. =over 4 -=item * What is Perl? +=item * -=item * Who supports Perl? Who develops it? Why is it free? +What is Perl? -=item * Which version of Perl should I use? +=item * -=item * What are perl4 and perl5? +Who supports Perl? Who develops it? Why is it free? -=item * What is perl6? +=item * -=item * How stable is Perl? +Which version of Perl should I use? -=item * Is Perl difficult to learn? +=item * -=item * How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl? +What are perl4 and perl5? -=item * Can I do [task] in Perl? +=item * -=item * When shouldn't I program in Perl? +What is perl6? -=item * What's the difference between "perl" and "Perl"? +=item * -=item * Is it a Perl program or a Perl script? +How stable is Perl? -=item * What is a JAPH? +=item * -=item * Where can I get a list of Larry Wall witticisms? +Is Perl difficult to learn? -=item * How can I convince my sysadmin/supervisor/employees to use version (5/5.005/Perl instead of some other language)? +=item * + +How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl? + +=item * + +Can I do [task] in Perl? + +=item * + +When shouldn't I program in Perl? + +=item * + +What's the difference between "perl" and "Perl"? + +=item * + +Is it a Perl program or a Perl script? + +=item * + +What is a JAPH? + +=item * + +Where can I get a list of Larry Wall witticisms? + +=item * + +How can I convince my sysadmin/supervisor/employees to use version 5/5.005/Perl instead of some other language? =back -=item L<perlfaq2>: Obtaining and Learning about Perl +=head2 L<perlfaq2>: Obtaining and Learning about Perl Where to find source and documentation to Perl, support, and related matters. =over 4 -=item * What machines support Perl? Where do I get it? +=item * + +What machines support Perl? Where do I get it? + +=item * + +How can I get a binary version of Perl? + +=item * -=item * How can I get a binary version of Perl? +I don't have a C compiler on my system. How can I compile perl? -=item * I don't have a C compiler on my system. How can I compile perl? +=item * -=item * I copied the Perl binary from one machine to another, but scripts don't work. +I copied the Perl binary from one machine to another, but scripts don't work. -=item * I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work? +=item * -=item * What modules and extensions are available for Perl? What is CPAN? What does CPAN/src/... mean? +I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work? -=item * Is there an ISO or ANSI certified version of Perl? +=item * -=item * Where can I get information on Perl? +What modules and extensions are available for Perl? What is CPAN? What does CPAN/src/... mean? -=item * What are the Perl newsgroups on USENET? Where do I post questions? +=item * -=item * Where should I post source code? +Is there an ISO or ANSI certified version of Perl? -=item * Perl Books +=item * -=item * Perl in Magazines +Where can I get information on Perl? -=item * Perl on the Net: FTP and WWW Access +=item * -=item * What mailing lists are there for perl? +What are the Perl newsgroups on Usenet? Where do I post questions? -=item * Archives of comp.lang.perl.misc +=item * -=item * Where can I buy a commercial version of Perl? +Where should I post source code? -=item * Where do I send bug reports? +=item * -=item * What is perl.com? +Perl Books + +=item * + +Perl in Magazines + +=item * + +Perl on the Net: FTP and WWW Access + +=item * + +What mailing lists are there for Perl? + +=item * + +Archives of comp.lang.perl.misc + +=item * + +Where can I buy a commercial version of Perl? + +=item * + +Where do I send bug reports? + +=item * + +What is perl.com? Perl Mongers? pm.org? perl.org? =back -=item L<perlfaq3>: Programming Tools +=head2 L<perlfaq3>: Programming Tools Programmer tools and programming support. =over 4 -=item * How do I do (anything)? +=item * + +How do I do (anything)? + +=item * + +How can I use Perl interactively? + +=item * + +Is there a Perl shell? -=item * How can I use Perl interactively? +=item * -=item * Is there a Perl shell? +How do I debug my Perl programs? -=item * How do I debug my Perl programs? +=item * -=item * How do I profile my Perl programs? +How do I profile my Perl programs? -=item * How do I cross-reference my Perl programs? +=item * -=item * Is there a pretty-printer (formatter) for Perl? +How do I cross-reference my Perl programs? -=item * Is there a ctags for Perl? +=item * -=item * Is there an IDE or Windows Perl Editor? +Is there a pretty-printer (formatter) for Perl? -=item * Where can I get Perl macros for vi? +=item * -=item * Where can I get perl-mode for emacs? +Is there a ctags for Perl? -=item * How can I use curses with Perl? +=item * -=item * How can I use X or Tk with Perl? +Is there an IDE or Windows Perl Editor? -=item * How can I generate simple menus without using CGI or Tk? +=item * -=item * What is undump? +Where can I get Perl macros for vi? -=item * How can I make my Perl program run faster? +=item * -=item * How can I make my Perl program take less memory? +Where can I get perl-mode for emacs? -=item * Is it unsafe to return a pointer to local data? +=item * -=item * How can I free an array or hash so my program shrinks? +How can I use curses with Perl? -=item * How can I make my CGI script more efficient? +=item * -=item * How can I hide the source for my Perl program? +How can I use X or Tk with Perl? -=item * How can I compile my Perl program into byte code or C? +=item * -=item * How can I compile Perl into Java? +How can I generate simple menus without using CGI or Tk? -=item * How can I get C<#!perl> to work on [MS-DOS,NT,...]? +=item * -=item * Can I write useful perl programs on the command line? +What is undump? -=item * Why don't perl one-liners work on my DOS/Mac/VMS system? +=item * -=item * Where can I learn about CGI or Web programming in Perl? +How can I make my Perl program run faster? -=item * Where can I learn about object-oriented Perl programming? +=item * -=item * Where can I learn about linking C with Perl? [h2xs, xsubpp] +How can I make my Perl program take less memory? -=item * I've read perlembed, perlguts, etc., but I can't embed perl in -my C program, what am I doing wrong? +=item * -=item * When I tried to run my script, I got this message. What does it +Is it unsafe to return a pointer to local data? + +=item * + +How can I free an array or hash so my program shrinks? + +=item * + +How can I make my CGI script more efficient? + +=item * + +How can I hide the source for my Perl program? + +=item * + +How can I compile my Perl program into byte code or C? + +=item * + +How can I compile Perl into Java? + +=item * + +How can I get C<#!perl> to work on [MS-DOS,NT,...]? + +=item * + +Can I write useful Perl programs on the command line? + +=item * + +Why don't Perl one-liners work on my DOS/Mac/VMS system? + +=item * + +Where can I learn about CGI or Web programming in Perl? + +=item * + +Where can I learn about object-oriented Perl programming? + +=item * + +Where can I learn about linking C with Perl? [h2xs, xsubpp] + +=item * + +I've read perlembed, perlguts, etc., but I can't embed perl in +my C program; what am I doing wrong? + +=item * + +When I tried to run my script, I got this message. What does it mean? -=item * What's MakeMaker? +=item * + +What's MakeMaker? =back -=item L<perlfaq4>: Data Manipulation +=head2 L<perlfaq4>: Data Manipulation Manipulating numbers, dates, strings, arrays, hashes, and miscellaneous data issues. =over 4 -=item * Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)? +=item * + +Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)? + +=item * + +Why isn't my octal data interpreted correctly? + +=item * + +Does Perl have a round() function? What about ceil() and floor()? Trig functions? + +=item * + +How do I convert bits into ints? + +=item * + +Why doesn't & work the way I want it to? + +=item * -=item * Why isn't my octal data interpreted correctly? +How do I multiply matrices? -=item * Does Perl have a round() function? What about ceil() and floor()? Trig functions? +=item * -=item * How do I convert bits into ints? +How do I perform an operation on a series of integers? -=item * Why doesn't & work the way I want it to? +=item * -=item * How do I multiply matrices? +How can I output Roman numerals? -=item * How do I perform an operation on a series of integers? +=item * -=item * How can I output Roman numerals? +Why aren't my random numbers random? -=item * Why aren't my random numbers random? +=item * -=item * How do I find the week-of-the-year/day-of-the-year? +How do I find the week-of-the-year/day-of-the-year? -=item * How do I find the current century or millennium? +=item * -=item * How can I compare two dates and find the difference? +How do I find the current century or millennium? -=item * How can I take a string and turn it into epoch seconds? +=item * -=item * How can I find the Julian Day? +How can I compare two dates and find the difference? -=item * How do I find yesterday's date? +=item * -=item * Does Perl have a year 2000 problem? Is Perl Y2K compliant? +How can I take a string and turn it into epoch seconds? -=item * How do I validate input? +=item * -=item * How do I unescape a string? +How can I find the Julian Day? -=item * How do I remove consecutive pairs of characters? +=item * -=item * How do I expand function calls in a string? +How do I find yesterday's date? -=item * How do I find matching/nesting anything? +=item * -=item * How do I reverse a string? +Does Perl have a Year 2000 problem? Is Perl Y2K compliant? -=item * How do I expand tabs in a string? +=item * -=item * How do I reformat a paragraph? +How do I validate input? -=item * How can I access/change the first N letters of a string? +=item * -=item * How do I change the Nth occurrence of something? +How do I unescape a string? -=item * How can I count the number of occurrences of a substring within a string? +=item * -=item * How do I capitalize all the words on one line? +How do I remove consecutive pairs of characters? -=item * How can I split a [character] delimited string except when inside +=item * + +How do I expand function calls in a string? + +=item * + +How do I find matching/nesting anything? + +=item * + +How do I reverse a string? + +=item * + +How do I expand tabs in a string? + +=item * + +How do I reformat a paragraph? + +=item * + +How can I access/change the first N letters of a string? + +=item * + +How do I change the Nth occurrence of something? + +=item * + +How can I count the number of occurrences of a substring within a string? + +=item * + +How do I capitalize all the words on one line? + +=item * + +How can I split a [character] delimited string except when inside [character]? (Comma-separated files) -=item * How do I strip blank space from the beginning/end of a string? +=item * + +How do I strip blank space from the beginning/end of a string? + +=item * + +How do I pad a string with blanks or pad a number with zeroes? + +=item * + +How do I extract selected columns from a string? + +=item * + +How do I find the soundex value of a string? + +=item * + +How can I expand variables in text strings? + +=item * + +What's wrong with always quoting "$vars"? + +=item * + +Why don't my <<HERE documents work? + +=item * + +What is the difference between a list and an array? + +=item * + +What is the difference between $array[1] and @array[1]? + +=item * + +How can I remove duplicate elements from a list or array? -=item * How do I pad a string with blanks or pad a number with zeroes? +=item * -=item * How do I extract selected columns from a string? +How can I tell whether a list or array contains a certain element? -=item * How do I find the soundex value of a string? +=item * -=item * How can I expand variables in text strings? +How do I compute the difference of two arrays? How do I compute the intersection of two arrays? -=item * What's wrong with always quoting "$vars"? +=item * -=item * Why don't my <<HERE documents work? +How do I test whether two arrays or hashes are equal? -=item * What is the difference between a list and an array? +=item * -=item * What is the difference between $array[1] and @array[1]? +How do I find the first array element for which a condition is true? -=item * How can I remove duplicate elements from a list or array? +=item * -=item * How can I tell whether a list or array contains a certain element? +How do I handle linked lists? -=item * How do I compute the difference of two arrays? How do I compute the intersection of two arrays? +=item * -=item * How do I test whether two arrays or hashes are equal? +How do I handle circular lists? -=item * How do I find the first array element for which a condition is true? +=item * -=item * How do I handle linked lists? +How do I shuffle an array randomly? -=item * How do I handle circular lists? +=item * -=item * How do I shuffle an array randomly? +How do I process/modify each element of an array? -=item * How do I process/modify each element of an array? +=item * -=item * How do I select a random element from an array? +How do I select a random element from an array? -=item * How do I permute N elements of a list? +=item * -=item * How do I sort an array by (anything)? +How do I permute N elements of a list? -=item * How do I manipulate arrays of bits? +=item * -=item * Why does defined() return true on empty arrays and hashes? +How do I sort an array by (anything)? -=item * How do I process an entire hash? +=item * -=item * What happens if I add or remove keys from a hash while iterating over it? +How do I manipulate arrays of bits? -=item * How do I look up a hash element by value? +=item * -=item * How can I know how many entries are in a hash? +Why does defined() return true on empty arrays and hashes? -=item * How do I sort a hash (optionally by value instead of key)? +=item * -=item * How can I always keep my hash sorted? +How do I process an entire hash? -=item * What's the difference between "delete" and "undef" with hashes? +=item * -=item * Why don't my tied hashes make the defined/exists distinction? +What happens if I add or remove keys from a hash while iterating over it? -=item * How do I reset an each() operation part-way through? +=item * -=item * How can I get the unique keys from two hashes? +How do I look up a hash element by value? -=item * How can I store a multidimensional array in a DBM file? +=item * -=item * How can I make my hash remember the order I put elements into it? +How can I know how many entries are in a hash? -=item * Why does passing a subroutine an undefined element in a hash create it? +=item * -=item * How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays? +How do I sort a hash (optionally by value instead of key)? -=item * How can I use a reference as a hash key? +=item * -=item * How do I handle binary data correctly? +How can I always keep my hash sorted? -=item * How do I determine whether a scalar is a number/whole/integer/float? +=item * -=item * How do I keep persistent data across program calls? +What's the difference between "delete" and "undef" with hashes? -=item * How do I print out or copy a recursive data structure? +=item * -=item * How do I define methods for every class/object? +Why don't my tied hashes make the defined/exists distinction? -=item * How do I verify a credit card checksum? +=item * -=item * How do I pack arrays of doubles or floats for XS code? +How do I reset an each() operation part-way through? + +=item * + +How can I get the unique keys from two hashes? + +=item * + +How can I store a multidimensional array in a DBM file? + +=item * + +How can I make my hash remember the order I put elements into it? + +=item * + +Why does passing a subroutine an undefined element in a hash create it? + +=item * + +How can I make the Perl equivalent of a C structure/C++ class/hash or array of hashes or arrays? + +=item * + +How can I use a reference as a hash key? + +=item * + +How do I handle binary data correctly? + +=item * + +How do I determine whether a scalar is a number/whole/integer/float? + +=item * + +How do I keep persistent data across program calls? + +=item * + +How do I print out or copy a recursive data structure? + +=item * + +How do I define methods for every class/object? + +=item * + +How do I verify a credit card checksum? + +=item * + +How do I pack arrays of doubles or floats for XS code? =back -=item L<perlfaq5>: Files and Formats +=head2 L<perlfaq5>: Files and Formats I/O and the "f" issues: filehandles, flushing, formats and footers. =over 4 -=item * How do I flush/unbuffer an output filehandle? Why must I do this? +=item * + +How do I flush/unbuffer an output filehandle? Why must I do this? + +=item * + +How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file? + +=item * + +How do I count the number of lines in a file? + +=item * + +How do I make a temporary file name? + +=item * + +How can I manipulate fixed-record-length files? + +=item * + +How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles? -=item * How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file? +=item * -=item * How do I count the number of lines in a file? +How can I use a filehandle indirectly? -=item * How do I make a temporary file name? +=item * -=item * How can I manipulate fixed-record-length files? +How can I set up a footer format to be used with write()? -=item * How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles? +=item * -=item * How can I use a filehandle indirectly? +How can I write() into a string? -=item * How can I set up a footer format to be used with write()? +=item * -=item * How can I write() into a string? +How can I output my numbers with commas added? -=item * How can I output my numbers with commas added? +=item * -=item * How can I translate tildes (~) in a filename? +How can I translate tildes (~) in a filename? -=item * How come when I open a file read-write it wipes it out? +=item * -=item * Why do I sometimes get an "Argument list too long" when I use <*>? +How come when I open a file read-write it wipes it out? -=item * Is there a leak/bug in glob()? +=item * -=item * How can I open a file with a leading ">" or trailing blanks? +Why do I sometimes get an "Argument list too long" when I use <*>? -=item * How can I reliably rename a file? +=item * -=item * How can I lock a file? +Is there a leak/bug in glob()? -=item * Why can't I just open(FH, ">file.lock")? +=item * -=item * I still don't get locking. I just want to increment the number in the file. How can I do this? +How can I open a file with a leading ">" or trailing blanks? -=item * How do I randomly update a binary file? +=item * -=item * How do I get a file's timestamp in perl? +How can I reliably rename a file? -=item * How do I set a file's timestamp in perl? +=item * -=item * How do I print to more than one file at once? +How can I lock a file? -=item * How can I read in an entire file all at once? +=item * -=item * How can I read in a file by paragraphs? +Why can't I just open(FH, ">file.lock")? -=item * How can I read a single character from a file? From the keyboard? +=item * -=item * How can I tell whether there's a character waiting on a filehandle? +I still don't get locking. I just want to increment the number in the file. How can I do this? -=item * How do I do a C<tail -f> in perl? +=item * -=item * How do I dup() a filehandle in Perl? +How do I randomly update a binary file? -=item * How do I close a file descriptor by number? +=item * -=item * Why can't I use "C:\temp\foo" in DOS paths? What doesn't `C:\temp\foo.exe` work? +How do I get a file's timestamp in perl? -=item * Why doesn't glob("*.*") get all the files? +=item * -=item * Why does Perl let me delete read-only files? Why does C<-i> clobber protected files? Isn't this a bug in Perl? +How do I set a file's timestamp in perl? -=item * How do I select a random line from a file? +=item * -=item * Why do I get weird spaces when I print an array of lines? +How do I print to more than one file at once? + +=item * + +How can I read in an entire file all at once? + +=item * + +How can I read in a file by paragraphs? + +=item * + +How can I read a single character from a file? From the keyboard? + +=item * + +How can I tell whether there's a character waiting on a filehandle? + +=item * + +How do I do a C<tail -f> in perl? + +=item * + +How do I dup() a filehandle in Perl? + +=item * + +How do I close a file descriptor by number? + +=item * + +Why can't I use "C:\temp\foo" in DOS paths? What doesn't `C:\temp\foo.exe` work? + +=item * + +Why doesn't glob("*.*") get all the files? + +=item * + +Why does Perl let me delete read-only files? Why does C<-i> clobber protected files? Isn't this a bug in Perl? + +=item * + +How do I select a random line from a file? + +=item * + +Why do I get weird spaces when I print an array of lines? =back -=item L<perlfaq6>: Regexps +=head2 L<perlfaq6>: Regexps Pattern matching and regular expressions. =over 4 -=item * How can I hope to use regular expressions without creating illegible and unmaintainable code? +=item * + +How can I hope to use regular expressions without creating illegible and unmaintainable code? + +=item * + +I'm having trouble matching over more than one line. What's wrong? + +=item * + +How can I pull out lines between two patterns that are themselves on different lines? + +=item * + +I put a regular expression into $/ but it didn't work. What's wrong? + +=item * + +How do I substitute case insensitively on the LHS while preserving case on the RHS? + +=item * + +How can I make C<\w> match national character sets? + +=item * + +How can I match a locale-smart version of C</[a-zA-Z]/>? + +=item * -=item * I'm having trouble matching over more than one line. What's wrong? +How can I quote a variable to use in a regex? -=item * How can I pull out lines between two patterns that are themselves on different lines? +=item * -=item * I put a regular expression into $/ but it didn't work. What's wrong? +What is C</o> really for? -=item * How do I substitute case insensitively on the LHS, but preserving case on the RHS? +=item * -=item * How can I make C<\w> match national character sets? +How do I use a regular expression to strip C style comments from a file? -=item * How can I match a locale-smart version of C</[a-zA-Z]/>? +=item * -=item * How can I quote a variable to use in a regex? +Can I use Perl regular expressions to match balanced text? -=item * What is C</o> really for? +=item * -=item * How do I use a regular expression to strip C style comments from a file? +What does it mean that regexes are greedy? How can I get around it? -=item * Can I use Perl regular expressions to match balanced text? +=item * -=item * What does it mean that regexes are greedy? How can I get around it? +How do I process each word on each line? -=item * How do I process each word on each line? +=item * -=item * How can I print out a word-frequency or line-frequency summary? +How can I print out a word-frequency or line-frequency summary? -=item * How can I do approximate matching? +=item * -=item * How do I efficiently match many regular expressions at once? +How can I do approximate matching? -=item * Why don't word-boundary searches with C<\b> work for me? +=item * -=item * Why does using $&, $`, or $' slow my program down? +How do I efficiently match many regular expressions at once? -=item * What good is C<\G> in a regular expression? +=item * -=item * Are Perl regexes DFAs or NFAs? Are they POSIX compliant? +Why don't word-boundary searches with C<\b> work for me? -=item * What's wrong with using grep or map in a void context? +=item * -=item * How can I match strings with multibyte characters? +Why does using $&, $`, or $' slow my program down? -=item * How do I match a pattern that is supplied by the user? +=item * + +What good is C<\G> in a regular expression? + +=item * + +Are Perl regexes DFAs or NFAs? Are they POSIX compliant? + +=item * + +What's wrong with using grep or map in a void context? + +=item * + +How can I match strings with multibyte characters? + +=item * + +How do I match a pattern that is supplied by the user? =back -=item L<perlfaq7>: General Perl Language Issues +=head2 L<perlfaq7>: General Perl Language Issues General Perl language issues that don't clearly fit into any of the other sections. =over 4 -=item * Can I get a BNF/yacc/RE for the Perl language? +=item * + +Can I get a BNF/yacc/RE for the Perl language? + +=item * + +What are all these $@%&* punctuation signs, and how do I know when to use them? + +=item * + +Do I always/never have to quote my strings or use semicolons and commas? + +=item * + +How do I skip some return values? + +=item * + +How do I temporarily block warnings? + +=item * + +What's an extension? + +=item * + +Why do Perl operators have different precedence than C operators? + +=item * + +How do I declare/create a structure? + +=item * + +How do I create a module? + +=item * + +How do I create a class? + +=item * + +How can I tell if a variable is tainted? + +=item * + +What's a closure? + +=item * + +What is variable suicide and how can I prevent it? + +=item * + +How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}? + +=item * -=item * What are all these $@%&* punctuation signs, and how do I know when to use them? +How do I create a static variable? -=item * Do I always/never have to quote my strings or use semicolons and commas? +=item * -=item * How do I skip some return values? +What's the difference between dynamic and lexical (static) scoping? Between local() and my()? -=item * How do I temporarily block warnings? +=item * -=item * What's an extension? +How can I access a dynamic variable while a similarly named lexical is in scope? -=item * Why do Perl operators have different precedence than C operators? +=item * -=item * How do I declare/create a structure? +What's the difference between deep and shallow binding? -=item * How do I create a module? +=item * -=item * How do I create a class? +Why doesn't "my($foo) = <FILE>;" work right? -=item * How can I tell if a variable is tainted? +=item * -=item * What's a closure? +How do I redefine a builtin function, operator, or method? -=item * What is variable suicide and how can I prevent it? +=item * -=item * How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regex}? +What's the difference between calling a function as &foo and foo()? -=item * How do I create a static variable? +=item * -=item * What's the difference between dynamic and lexical (static) scoping? Between local() and my()? +How do I create a switch or case statement? -=item * How can I access a dynamic variable while a similarly named lexical is in scope? +=item * -=item * What's the difference between deep and shallow binding? +How can I catch accesses to undefined variables/functions/methods? -=item * Why doesn't "my($foo) = <FILE>;" work right? +=item * -=item * How do I redefine a builtin function, operator, or method? +Why can't a method included in this same file be found? -=item * What's the difference between calling a function as &foo and foo()? +=item * -=item * How do I create a switch or case statement? +How can I find out my current package? -=item * How can I catch accesses to undefined variables/functions/methods? +=item * -=item * Why can't a method included in this same file be found? +How can I comment out a large block of perl code? -=item * How can I find out my current package? +=item * -=item * How can I comment out a large block of perl code? +How do I clear a package? -=item * How do I clear a package? +=item * -=item * How can I use a variable as a variable name? +How can I use a variable as a variable name? =back -=item L<perlfaq8>: System Interaction +=head2 L<perlfaq8>: System Interaction Interprocess communication (IPC), control over the user-interface (keyboard, screen and pointing devices). =over 4 -=item * How do I find out which operating system I'm running under? +=item * -=item * How come exec() doesn't return? +How do I find out which operating system I'm running under? -=item * How do I do fancy stuff with the keyboard/screen/mouse? +=item * -=item * How do I print something out in color? +How come exec() doesn't return? -=item * How do I read just one key without waiting for a return key? +=item * -=item * How do I check whether input is ready on the keyboard? +How do I do fancy stuff with the keyboard/screen/mouse? -=item * How do I clear the screen? +=item * -=item * How do I get the screen size? +How do I print something out in color? -=item * How do I ask the user for a password? +=item * -=item * How do I read and write the serial port? +How do I read just one key without waiting for a return key? -=item * How do I decode encrypted password files? +=item * -=item * How do I start a process in the background? +How do I check whether input is ready on the keyboard? -=item * How do I trap control characters/signals? +=item * -=item * How do I modify the shadow password file on a Unix system? +How do I clear the screen? -=item * How do I set the time and date? +=item * -=item * How can I sleep() or alarm() for under a second? +How do I get the screen size? -=item * How can I measure time under a second? +=item * -=item * How can I do an atexit() or setjmp()/longjmp()? (Exception handling) +How do I ask the user for a password? -=item * Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean? +=item * -=item * How can I call my system's unique C functions from Perl? +How do I read and write the serial port? -=item * Where do I get the include files to do ioctl() or syscall()? +=item * -=item * Why do setuid perl scripts complain about kernel problems? +How do I decode encrypted password files? -=item * How can I open a pipe both to and from a command? +=item * -=item * Why can't I get the output of a command with system()? +How do I start a process in the background? -=item * How can I capture STDERR from an external command? +=item * -=item * Why doesn't open() return an error when a pipe open fails? +How do I trap control characters/signals? -=item * What's wrong with using backticks in a void context? +=item * -=item * How can I call backticks without shell processing? +How do I modify the shadow password file on a Unix system? -=item * Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)? +=item * -=item * How can I convert my shell script to perl? +How do I set the time and date? -=item * Can I use perl to run a telnet or ftp session? +=item * -=item * How can I write expect in Perl? +How can I sleep() or alarm() for under a second? -=item * Is there a way to hide perl's command line from programs such as "ps"? +=item * -=item * I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible? +How can I measure time under a second? -=item * How do I close a process's filehandle without waiting for it to complete? +=item * -=item * How do I fork a daemon process? +How can I do an atexit() or setjmp()/longjmp()? (Exception handling) -=item * How do I make my program run with sh and csh? +=item * -=item * How do I find out if I'm running interactively or not? +Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean? -=item * How do I timeout a slow event? +=item * -=item * How do I set CPU limits? +How can I call my system's unique C functions from Perl? -=item * How do I avoid zombies on a Unix system? +=item * -=item * How do I use an SQL database? +Where do I get the include files to do ioctl() or syscall()? -=item * How do I make a system() exit on control-C? +=item * -=item * How do I open a file without blocking? +Why do setuid perl scripts complain about kernel problems? -=item * How do I install a module from CPAN? +=item * -=item * What's the difference between require and use? +How can I open a pipe both to and from a command? -=item * How do I keep my own module/library directory? +=item * -=item * How do I add the directory my program lives in to the module/library search path? +Why can't I get the output of a command with system()? -=item * How do I add a directory to my include path at runtime? +=item * -=item * What is socket.ph and where do I get it? +How can I capture STDERR from an external command? + +=item * + +Why doesn't open() return an error when a pipe open fails? + +=item * + +What's wrong with using backticks in a void context? + +=item * + +How can I call backticks without shell processing? + +=item * + +Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)? + +=item * + +How can I convert my shell script to perl? + +=item * + +Can I use perl to run a telnet or ftp session? + +=item * + +How can I write expect in Perl? + +=item * + +Is there a way to hide perl's command line from programs such as "ps"? + +=item * + +I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible? + +=item * + +How do I close a process's filehandle without waiting for it to complete? + +=item * + +How do I fork a daemon process? + +=item * + +How do I find out if I'm running interactively or not? + +=item * + +How do I timeout a slow event? + +=item * + +How do I set CPU limits? + +=item * + +How do I avoid zombies on a Unix system? + +=item * + +How do I use an SQL database? + +=item * + +How do I make a system() exit on control-C? + +=item * + +How do I open a file without blocking? + +=item * + +How do I install a module from CPAN? + +=item * + +What's the difference between require and use? + +=item * + +How do I keep my own module/library directory? + +=item * + +How do I add the directory my program lives in to the module/library search path? + +=item * + +How do I add a directory to my include path at runtime? + +=item * + +What is socket.ph and where do I get it? =back -=item L<perlfaq9>: Networking +=head2 L<perlfaq9>: Networking Networking, the Internet, and a few on the web. =over 4 -=item * My CGI script runs from the command line but not the browser. (500 Server Error) +=item * -=item * How can I get better error messages from a CGI program? +My CGI script runs from the command line but not the browser. (500 Server Error) -=item * How do I remove HTML from a string? +=item * -=item * How do I extract URLs? +How can I get better error messages from a CGI program? -=item * How do I download a file from the user's machine? How do I open a file on another machine? +=item * -=item * How do I make a pop-up menu in HTML? +How do I remove HTML from a string? -=item * How do I fetch an HTML file? +=item * -=item * How do I automate an HTML form submission? +How do I extract URLs? -=item * How do I decode or create those %-encodings on the web? +=item * -=item * How do I redirect to another page? +How do I download a file from the user's machine? How do I open a file on another machine? -=item * How do I put a password on my web pages? +=item * -=item * How do I edit my .htpasswd and .htgroup files with Perl? +How do I make a pop-up menu in HTML? -=item * How do I make sure users can't enter values into a form that cause my CGI script to do bad things? +=item * -=item * How do I parse a mail header? +How do I fetch an HTML file? -=item * How do I decode a CGI form? +=item * -=item * How do I check a valid mail address? +How do I automate an HTML form submission? -=item * How do I decode a MIME/BASE64 string? +=item * -=item * How do I return the user's mail address? +How do I decode or create those %-encodings on the web? -=item * How do I send mail? +=item * -=item * How do I read mail? +How do I redirect to another page? -=item * How do I find out my hostname/domainname/IP address? +=item * -=item * How do I fetch a news article or the active newsgroups? +How do I put a password on my web pages? -=item * How do I fetch/put an FTP file? +=item * -=item * How can I do RPC in Perl? +How do I edit my .htpasswd and .htgroup files with Perl? -=back +=item * + +How do I make sure users can't enter values into a form that cause my CGI script to do bad things? + +=item * + +How do I parse a mail header? + +=item * + +How do I decode a CGI form? + +=item * + +How do I check a valid mail address? + +=item * +How do I decode a MIME/BASE64 string? + +=item * + +How do I return the user's mail address? + +=item * + +How do I send mail? + +=item * + +How do I read mail? + +=item * + +How do I find out my hostname/domainname/IP address? + +=item * + +How do I fetch a news article or the active newsgroups? + +=item * + +How do I fetch/put an FTP file? + +=item * + +How can I do RPC in Perl? =back -=head2 Where to get this document + +=head1 About the perlfaq documents + +=head2 Where to get the perlfaq This document is posted regularly to comp.lang.perl.announce and several other related newsgroups. It is available in a variety of -formats from CPAN in the /CPAN/doc/FAQs/FAQ/ directory, or on the web +formats from CPAN in the /CPAN/doc/FAQs/FAQ/ directory or on the web at http://www.perl.com/perl/faq/ . -=head2 How to contribute to this document +=head2 How to contribute to the perlfaq You may mail corrections, additions, and suggestions to perlfaq-suggestions@perl.com . This alias should not be @@ -740,11 +1333,11 @@ All rights reserved. =head2 Bundled Distributions -When included as part of the Standard Version of Perl, or as part of +When included as part of the Standard Version of Perl or as part of its complete documentation whether printed or otherwise, this work may be distributed only under the terms of Perl's Artistic License. Any distribution of this file or derivatives thereof I<outside> -of that package require that special arrangements be made with +of that package requires that special arrangements be made with copyright holder. Irrespective of its distribution, all code examples in these files @@ -764,6 +1357,10 @@ in respect of this information or its use. =over 4 +=item 1/November/2000 + +A few grammatical fixes and updates implemented by John Borwick. + =item 23/May/99 Extensive updates from the net in preparation for 5.6 release. diff --git a/contrib/perl5/pod/perlfaq1.pod b/contrib/perl5/pod/perlfaq1.pod index af4d7cbd04c3..68c6bfd92889 100644 --- a/contrib/perl5/pod/perlfaq1.pod +++ b/contrib/perl5/pod/perlfaq1.pod @@ -36,7 +36,7 @@ In particular, the core development team (known as the Perl Porters) are a rag-tag band of highly altruistic individuals committed to producing better software for free than you could hope to purchase for money. You may snoop on pending developments via -news://news.perl.com/perl.porters-gw/ and the Deja archive at +nntp://news.perl.com/perl.porters-gw/ and the Deja archive at http://www.deja.com/ using the perl.porters-gw newsgroup, or you can subscribe to the mailing list by sending perl5-porters-request@perl.org a subscription request. @@ -56,8 +56,8 @@ You should definitely use version 5. Version 4 is old, limited, and no longer maintained; its last patch (4.036) was in 1992, long ago and far away. Sure, it's stable, but so is anything that's dead; in fact, perl4 had been called a dead, flea-bitten camel carcass. The most recent -production release is 5.005_03 (although 5.004_05 is still supported). -The most cutting-edge development release is 5.005_57. Further references +production release is 5.6 (although 5.005_03 is still supported). +The most cutting-edge development release is 5.7. Further references to the Perl language in this document refer to the production release unless otherwise specified. There may be one or more official bug fixes by the time you read this, and also perhaps some experimental versions @@ -78,8 +78,8 @@ The 5.0 release is, essentially, a ground-up rewrite of the original perl source code from releases 1 through 4. It has been modularized, object-oriented, tweaked, trimmed, and optimized until it almost doesn't look like the old code. However, the interface is mostly the same, and -compatibility with previous releases is very high. See L<perltrap/"Perl4 -to Perl5 Traps">. +compatibility with previous releases is very high. +See L<perltrap/"Perl4 to Perl5 Traps">. To avoid the "what language is perl5?" confusion, some people prefer to simply use "perl" to refer to the latest version of perl and avoid using @@ -89,24 +89,21 @@ See L<perlhist> for a history of Perl revisions. =head2 What is perl6? -Perl6 is a semi-jocular reference to the Topaz project. Headed by Chip -Salzenberg, Topaz is yet-another ground-up rewrite of the current release -of Perl, one whose major goal is to create a more maintainable core than -found in release 5. Written in nominally portable C++, Topaz hopes to -maintain 100% source-compatibility with previous releases of Perl but to -run significantly faster and smaller. The Topaz team hopes to provide -an XS compatibility interface to allow most XS modules to work unchanged, -albeit perhaps without the efficiency that the new interface would allow. -New features in Topaz are as yet undetermined, and will be addressed -once compatibility and performance goals are met. - -If you are a hard-working C++ wizard with a firm command of Perl's -internals, and you would like to work on the project, send a request to -perl6-porters-request@perl.org to subscribe to the Topaz mailing list. - -There is no ETA for Topaz. It is expected to be several years before it -achieves enough robustness, compatibility, portability, and performance -to replace perl5 for ordinary use by mere mortals. +At The Second O'Reilly Open Source Software Convention, Larry Wall +announced Perl6 development would begin in earnest. Perl6 was an oft +used term for Chip Salzenberg's project to rewrite Perl in C++ named +Topaz. However, Topaz should not be confused with the nisus to rewrite +Perl while keeping the lessons learned from other software, as well as +Perl5, in mind. + +If you have a desire to help in the crusade to make Perl a better place +then peruse the Perl6 developers page at http://www.perl.org/perl6/ and +get involved. + +The first alpha release is expected by Summer 2001. + +"We're really serious about reinventing everything that needs reinventing." +--Larry Wall =head2 How stable is Perl? @@ -123,10 +120,10 @@ and the rare new keyword). =head2 Is Perl difficult to learn? -No, Perl is easy to start learning -- and easy to keep learning. It looks +No, Perl is easy to start learning--and easy to keep learning. It looks like most programming languages you're likely to have experience with, so if you've ever written a C program, an awk script, a shell -script, or even a BASIC program, you're already part way there. +script, or even a BASIC program, you're already partway there. Most tasks only require a small subset of the Perl language. One of the guiding mottos for Perl development is "there's more than one way @@ -186,7 +183,7 @@ languages that come to mind include prolog and matlab. =head2 When shouldn't I program in Perl? -When your manager forbids it -- but do consider replacing them :-). +When your manager forbids it--but do consider replacing them :-). Actually, one good reason is when you already have an existing application written in another language that's all done (and done @@ -204,7 +201,7 @@ limitations given in the previous statement to some degree, but understand that Perl remains fundamentally a dynamically typed language, not a statically typed one. You certainly won't be chastised if you don't trust nuclear-plant or brain-surgery monitoring code to it. And Larry -will sleep easier, too -- Wall Street programs not withstanding. :-) +will sleep easier, too--Wall Street programs not withstanding. :-) =head2 What's the difference between "perl" and "Perl"? @@ -223,17 +220,17 @@ Larry doesn't really care. He says (half in jest) that "a script is what you give the actors. A program is what you give the audience." Originally, a script was a canned sequence of normally interactive -commands, that is, a chat script. Something like a UUCP or PPP chat +commands--that is, a chat script. Something like a UUCP or PPP chat script or an expect script fits the bill nicely, as do configuration scripts run by a program at its start up, such F<.cshrc> or F<.ircrc>, for example. Chat scripts were just drivers for existing programs, not stand-alone programs in their own right. A computer scientist will correctly explain that all programs are -interpreted, and that the only question is at what level. But if you +interpreted and that the only question is at what level. But if you ask this question of someone who isn't a computer scientist, they might tell you that a I<program> has been compiled to physical machine code -once, and can then be run multiple times, whereas a I<script> must be +once and can then be run multiple times, whereas a I<script> must be translated by a program each time it's used. Perl programs are (usually) neither strictly compiled nor strictly @@ -266,7 +263,7 @@ Newer examples can be found by perusing Larry's postings: http://x1.dejanews.com/dnquery.xp?QRY=*&DBS=2&ST=PS&defaultOp=AND&LNG=ALL&format=terse&showsort=date&maxhits=100&subjects=&groups=&authors=larry@*wall.org&fromdate=&todate= -=head2 How can I convince my sysadmin/supervisor/employees to use version (5/5.005/Perl instead of some other language)? +=head2 How can I convince my sysadmin/supervisor/employees to use version 5/5.005/Perl instead of some other language? If your manager or employees are wary of unsupported software, or software which doesn't officially ship with your operating system, you @@ -275,15 +272,15 @@ more productive using and utilizing Perl constructs, functionality, simplicity, and power, then the typical manager/supervisor/employee may be persuaded. Regarding using Perl in general, it's also sometimes helpful to point out that delivery times may be reduced -using Perl, as compared to other languages. +using Perl compared to other languages. If you have a project which has a bottleneck, especially in terms of translation or testing, Perl almost certainly will provide a viable, -and quick solution. In conjunction with any persuasion effort, you +quick solution. In conjunction with any persuasion effort, you should not fail to point out that Perl is used, quite extensively, and with extremely reliable and valuable results, at many large computer -software and/or hardware companies throughout the world. In fact, -many Unix vendors now ship Perl by default, and support is usually +software and hardware companies throughout the world. In fact, +many Unix vendors now ship Perl by default. Support is usually just a news-posting away, if you can't find the answer in the I<comprehensive> documentation, including this FAQ. @@ -295,22 +292,29 @@ by the Perl Development Team. Another big sell for Perl5 is the large number of modules and extensions which greatly reduce development time for any given task. Also mention that the difference between version 4 and version 5 of Perl is like the difference between awk and C++. -(Well, OK, maybe not quite that distinct, but you get the idea.) If you -want support and a reasonable guarantee that what you're developing -will continue to work in the future, then you have to run the supported -version. That probably means running the 5.005 release, although 5.004 -isn't that bad. Several important bugs were fixed from the 5.000 through -5.003 versions, though, so try upgrading past them if possible. +(Well, OK, maybe it's not quite that distinct, but you get the idea.) +If you want support and a reasonable guarantee that what you're +developing will continue to work in the future, then you have to run +the supported version. As of April 2001 that probably means +running either of the releases 5.6.1 (released in April 2001) or +5.005_03 (released in March 1999), although 5.004_05 isn't that bad +if you B<absolutely> need such an old version (released in April 1999) +for stability reasons. Anything older than 5.004_05 shouldn't be used. Of particular note is the massive bug hunt for buffer overflow problems that went into the 5.004 release. All releases prior to that, including perl4, are considered insecure and should be upgraded as soon as possible. +In August 2000 in all Linux distributions a new security problem was +found in the optional 'suidperl' (not built or installed by default) +in all the Perl branches 5.6, 5.005, and 5.004, see +http://www.cpan.org/src/5.0/sperl-2000-08-05/ + =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997, 1998, 1999 Tom Christiansen and Nathan Torkington. -All rights reserved. +Copyright (c) 1997, 1998, 1999, 2000, 2001 Tom Christiansen and Nathan +Torkington. All rights reserved. When included as an integrated part of the Standard Distribution of Perl or of its documentation (printed or otherwise), this works is diff --git a/contrib/perl5/pod/perlfaq2.pod b/contrib/perl5/pod/perlfaq2.pod index af9178dee1ba..aecc1fc4c3be 100644 --- a/contrib/perl5/pod/perlfaq2.pod +++ b/contrib/perl5/pod/perlfaq2.pod @@ -12,17 +12,16 @@ related matters. The standard release of Perl (the one maintained by the perl development team) is distributed only in source code form. You -can find this at http://www.perl.com/CPAN/src/latest.tar.gz , which -in standard Internet format (a gzipped archive in POSIX tar format). +can find this at http://www.cpan.org/src/latest.tar.gz , which +is in a standard Internet format (a gzipped archive in POSIX tar format). Perl builds and runs on a bewildering number of platforms. Virtually all known and current Unix derivatives are supported (Perl's native platform), as are other systems like VMS, DOS, OS/2, Windows, -QNX, BeOS, and the Amiga. There are also the beginnings of support -for MPE/iX. +QNX, BeOS, OS X, MPE/iX and the Amiga. Binary distributions for some proprietary platforms, including -Apple systems, can be found http://www.perl.com/CPAN/ports/ directory. +Apple systems, can be found http://www.cpan.org/ports/ directory. Because these are not part of the standard distribution, they may and in fact do differ from the base Perl port in a variety of ways. You'll have to check their respective release notes to see just @@ -41,12 +40,11 @@ get free compilers for, not for Unix systems. Some URLs that might help you are: + http://www.cpan.org/ports/ http://language.perl.com/info/software.html - http://www.perl.com/pub/language/info/software.html#binary - http://www.perl.com/CPAN/ports/ Someone looking for a Perl for Win16 might look to Laszlo Molnar's djgpp -port in http://www.perl.com/CPAN/ports/msdos/ , which comes with clear +port in http://www.cpan.org/ports/#msdos , which comes with clear installation instructions. A simple installation guide for MS-DOS using Ilya Zakharevich's OS/2 port is available at http://www.cs.ruu.nl/%7Epiet/perl5dos.html @@ -69,19 +67,19 @@ eventually live on, and then type C<make install>. Most other approaches are doomed to failure. One simple way to check that things are in the right place is to print out -the hard-coded @INC which perl is looking for. +the hard-coded @INC that perl looks through for libraries: % perl -e 'print join("\n",@INC)' -If this command lists any paths which don't exist on your system, then you +If this command lists any paths that don't exist on your system, then you may need to move the appropriate libraries to these locations, or create symbolic links, aliases, or shortcuts appropriately. @INC is also printed as part of the output of % perl -V -You might also want to check out L<perlfaq8/"How do I keep my own -module/library directory?">. +You might also want to check out +L<perlfaq8/"How do I keep my own module/library directory?">. =head2 I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make it work? @@ -92,26 +90,32 @@ architecture. =head2 What modules and extensions are available for Perl? What is CPAN? What does CPAN/src/... mean? -CPAN stands for Comprehensive Perl Archive Network, a huge archive -replicated on dozens of machines all over the world. CPAN contains +CPAN stands for Comprehensive Perl Archive Network, a ~700mb archive +replicated on nearly 200 machines all over the world. CPAN contains source code, non-native ports, documentation, scripts, and many third-party modules and extensions, designed for everything from commercial database interfaces to keyboard/screen control to web -walking and CGI scripts. The master machine for CPAN is -ftp://ftp.funet.fi/pub/languages/perl/CPAN/, but you can use the -address http://www.perl.com/CPAN/CPAN.html to fetch a copy from a -"site near you". See http://www.perl.com/CPAN (without a slash at the -end) for how this process works. +walking and CGI scripts. The master web site for CPAN is +http://www.cpan.org/ and there is the CPAN Multiplexer at +http://www.perl.com/CPAN/CPAN.html which will choose a mirror near you +via DNS. See http://www.perl.com/CPAN (without a slash at the +end) for how this process works. Also, http://mirror.cpan.org/ +has a nice interface to the http://www.cpan.org/MIRRORED.BY +mirror directory. + +See the CPAN FAQ at http://www.cpan.org/misc/cpan-faq.html for +answers to the most frequently asked questions about CPAN +including how to become a mirror. CPAN/path/... is a naming convention for files available on CPAN sites. CPAN indicates the base directory of a CPAN mirror, and the rest of the path is the path from that directory to the file. For instance, if you're using ftp://ftp.funet.fi/pub/languages/perl/CPAN -as your CPAN site, the file CPAN/misc/japh file is downloadable as +as your CPAN site, the file CPAN/misc/japh is downloadable as ftp://ftp.funet.fi/pub/languages/perl/CPAN/misc/japh . -Considering that there are hundreds of existing modules in the -archive, one probably exists to do nearly anything you can think of. +Considering that there are close to two thousand existing modules in +the archive, one probably exists to do nearly anything you can think of. Current categories under CPAN/modules/by-category/ include Perl core modules; development support; operating system interfaces; networking, devices, and interprocess communication; data type utilities; database @@ -122,6 +126,10 @@ compression; image manipulation; mail and news; control flow utilities; filehandle and I/O; Microsoft Windows modules; and miscellaneous modules. +See http://www.cpan.org/modules/00modlist.long.html or +http://search.cpan.org/ for a more complete list of modules by category. + + =head2 Is there an ISO or ANSI certified version of Perl? Certainly not. Larry expects that he'll be certified before Perl is. @@ -133,30 +141,33 @@ If you have Perl installed locally, you probably have the documentation installed as well: type C<man perl> if you're on a system resembling Unix. This will lead you to other important man pages, including how to set your $MANPATH. If you're not on a Unix system, access to the documentation -will be different; for example, it might be only in HTML format. But all +will be different; for example, documentation might only be in HTML format. All proper Perl installations have fully-accessible documentation. You might also try C<perldoc perl> in case your system doesn't have a proper man command, or it's been misinstalled. If that doesn't work, try looking in /usr/local/lib/perl5/pod for documentation. -If all else fails, consult the CPAN/doc directory, which contains the -complete documentation in various formats, including native pod, -troff, html, and plain text. There's also a web page at -http://www.perl.com/perl/info/documentation.html that might help. +If all else fails, consult http://perldoc.cpan.org/ or +http://www.perldoc.com/ both offer the complete documentation +in html format. -Many good books have been written about Perl -- see the section below +Many good books have been written about Perl--see the section below for more details. Tutorial documents are included in current or upcoming Perl releases -include L<perltoot> for objects, L<perlopentut> for file opening -semantics, L<perlreftut> for managing references, and L<perlxstut> -for linking C and Perl together. There may be more by the -time you read this. The following URLs might also be of +include L<perltoot> for objects or L<perlboot> for a beginner's +approach to objects, L<perlopentut> for file opening semantics, +L<perlreftut> for managing references, L<perlretut> for regular +expressions, L<perlthrtut> for threads, L<perldebtut> for debugging, +and L<perlxstut> for linking C and Perl together. There may be more +by the time you read this. The following URLs might also be of assistance: - http://language.perl.com/info/documentation.html + http://perldoc.cpan.org/ + http://www.perldoc.com/ http://reference.perl.com/query.cgi?tutorials + http://bookmarks.cpan.org/search.cgi?cat=Training%2FTutorials =head2 What are the Perl newsgroups on Usenet? Where do I post questions? @@ -183,53 +194,49 @@ to alt.sources, please make sure it follows their posting standards, including setting the Followup-To header line to NOT include alt.sources; see their FAQ (http://www.faqs.org/faqs/alt-sources-intro/) for details. -If you're just looking for software, first use AltaVista -(http://www.altavista.com), Deja (http://www.deja.com), and -search CPAN. This is faster and more productive than just posting -a request. +If you're just looking for software, first use Google +(http://www.google.com), Deja (http://www.deja.com), and +CPAN Search (http://search.cpan.org). This is faster and more +productive than just posting a request. =head2 Perl Books A number of books on Perl and/or CGI programming are available. A few of these are good, some are OK, but many aren't worth your money. Tom Christiansen maintains a list of these books, some with extensive -reviews, at http://www.perl.com/perl/critiques/index.html. +reviews, at http://www.perl.com/perl/critiques/index.html . The incontestably definitive reference book on Perl, written by -the creator of Perl, is now in its second edition: +the creator of Perl, is now (July 2000) in its third edition: Programming Perl (the "Camel Book"): - by Larry Wall, Tom Christiansen, and Randal Schwartz - ISBN 1-56592-149-6 (English) - ISBN 4-89052-384-7 (Japanese) - URL: http://www.oreilly.com/catalog/pperl2/ - (French, German, Italian, and Hungarian translations also - available) + by Larry Wall, Tom Christiansen, and Jon Orwant + 0-596-00027-8 [3rd edition July 2000] + http://www.oreilly.com/catalog/pperl3/ + (English, translations to several languages are also available) The companion volume to the Camel containing thousands -of real-world examples, mini-tutorials, and complete programs -(first premiering at the 1998 Perl Conference), is: +of real-world examples, mini-tutorials, and complete programs is: The Perl Cookbook (the "Ram Book"): - by Tom Christiansen and Nathan Torkington, - with Foreword by Larry Wall - ISBN: 1-56592-243-3 - URL: http://perl.oreilly.com/cookbook/ + by Tom Christiansen and Nathan Torkington, + with Foreword by Larry Wall + ISBN 1-56592-243-3 [1st Edition August 1998] + http://perl.oreilly.com/cookbook/ If you're already a hard-core systems programmer, then the Camel Book -might suffice for you to learn Perl from. But if you're not, check -out: +might suffice for you to learn Perl from. If you're not, check out Learning Perl (the "Llama Book"): - by Randal Schwartz and Tom Christiansen + by Randal Schwartz and Tom Christiansen with Foreword by Larry Wall - ISBN: 1-56592-284-0 - URL: http://www.oreilly.com/catalog/lperl2/ + ISBN 1-56592-284-0 [2nd Edition July 1997] + http://www.oreilly.com/catalog/lperl2/ Despite the picture at the URL above, the second edition of "Llama -Book" really has a blue cover, and is updated for the 5.004 release +Book" really has a blue cover and was updated for the 5.004 release of Perl. Various foreign language editions are available, including -I<Learning Perl on Win32 Systems> (the Gecko Book). +I<Learning Perl on Win32 Systems> (the "Gecko Book"). If you're not an accidental programmer, but a more serious and possibly even degreed computer scientist who doesn't need as much hand-holding as @@ -237,126 +244,174 @@ we try to provide in the Llama or its defurred cousin the Gecko, please check out the delightful book, I<Perl: The Programmer's Companion>, written by Nigel Chapman. -You can order O'Reilly books directly from O'Reilly & Associates, -1-800-998-9938. Local/overseas is 1-707-829-0515. If you can -locate an O'Reilly order form, you can also fax to 1-707-829-0104. -See http://www.ora.com/ on the Web. +Addison-Wesley (http://www.awlonline.com/) and Manning +(http://www.manning.com/) are also publishers of some fine Perl books +such as Object Oriented Programming with Perl by Damian Conway and +Network Programming with Perl by Lincoln Stein. + +An excellent technical book discounter is Bookpool at +http://www.bookpool.com/ where a 30% discount or more is not unusual. What follows is a list of the books that the FAQ authors found personally useful. Your mileage may (but, we hope, probably won't) vary. -Recommended books on (or mostly on) Perl follow; those marked with -a star may be ordered from O'Reilly. +Recommended books on (or mostly on) Perl follow. -=over +=over 4 =item References - *Programming Perl - by Larry Wall, Tom Christiansen, and Randal L. Schwartz + Programming Perl + by Larry Wall, Tom Christiansen, and Jon Orwant + ISBN 0-596-00027-8 [3rd edition July 2000] + http://www.oreilly.com/catalog/pperl3/ - *Perl 5 Desktop Reference + Perl 5 Pocket Reference by Johan Vromans + ISBN 0-596-00032-4 [3rd edition May 2000] + http://www.oreilly.com/catalog/perlpr3/ - *Perl in a Nutshell + Perl in a Nutshell by Ellen Siever, Stephan Spainhour, and Nathan Patwardhan + ISBN 1-56592-286-7 [1st edition December 1998] + http://www.oreilly.com/catalog/perlnut/ =item Tutorials - *Learning Perl [2nd edition] + Elements of Programming with Perl + by Andrew L. Johnson + ISBN 1884777805 [1st edition October 1999] + http://www.manning.com/Johnson/ + + Learning Perl by Randal L. Schwartz and Tom Christiansen with foreword by Larry Wall + ISBN 1-56592-284-0 [2nd edition July 1997] + http://www.oreilly.com/catalog/lperl2/ - *Learning Perl on Win32 Systems + Learning Perl on Win32 Systems by Randal L. Schwartz, Erik Olson, and Tom Christiansen, with foreword by Larry Wall + ISBN 1-56592-324-3 [1st edition August 1997] + http://www.oreilly.com/catalog/lperlwin/ Perl: The Programmer's Companion by Nigel Chapman + ISBN 0-471-97563-X [1st edition October 1997] + http://catalog.wiley.com/title.cgi?isbn=047197563X - Cross-Platform Perl - by Eric F. Johnson + Cross-Platform Perl + by Eric Foster-Johnson + ISBN 1-55851-483-X [2nd edition September 2000] + http://www.pconline.com/~erc/perlbook.htm - MacPerl: Power and Ease - by Vicki Brown and Chris Nandor, foreword by Matthias Neeracher + MacPerl: Power and Ease + by Vicki Brown and Chris Nandor, + with foreword by Matthias Neeracher + ISBN 1-881957-32-2 [1st edition May 1998] + http://www.macperl.com/ptf_book/ -=item Task-Oriented +=item Task-Oriented - *The Perl Cookbook + The Perl Cookbook by Tom Christiansen and Nathan Torkington with foreword by Larry Wall + ISBN 1-56592-243-3 [1st edition August 1998] + http://www.oreilly.com/catalog/cookbook/ - Perl5 Interactive Course [2nd edition] - by Jon Orwant - - *Advanced Perl Programming - by Sriram Srinivasan - - Effective Perl Programming + Effective Perl Programming by Joseph Hall + ISBN 0-201-41975-0 [1st edition 1998] + http://www.awl.com/ + =item Special Topics - *Mastering Regular Expressions - by Jeffrey Friedl + Mastering Regular Expressions + by Jeffrey E. F. Friedl + ISBN 1-56592-257-3 [1st edition January 1997] + http://www.oreilly.com/catalog/regex/ - How to Set up and Maintain a World Wide Web Site [2nd edition] + Network Programming with Perl by Lincoln Stein + ISBN 0-201-61571-1 [1st edition 2001] + http://www.awlonline.com/ + + Object Oriented Perl + Damian Conway + with foreword by Randal L. Schwartz + ISBN 1884777791 [1st edition August 1999] + http://www.manning.com/Conway/ - *Learning Perl/Tk + Data Munging with Perl + Dave Cross + ISBN 1930110006 [1st edition 2001] + http://www.manning.com/cross + + Learning Perl/Tk by Nancy Walsh + ISBN 1-56592-314-6 [1st edition January 1999] + http://www.oreilly.com/catalog/lperltk/ =back =head2 Perl in Magazines The first and only periodical devoted to All Things Perl, I<The -Perl Journal> contains tutorials, demonstrations, case studies, -announcements, contests, and much more. TPJ has columns on web +Perl Journal> contained tutorials, demonstrations, case studies, +announcements, contests, and much more. I<TPJ> had columns on web development, databases, Win32 Perl, graphical programming, regular -expressions, and networking, and sponsors the Obfuscated Perl -Contest. It is published quarterly under the gentle hand of its -editor, Jon Orwant. See http://www.tpj.com/ or send mail to -subscriptions@tpj.com . +expressions, and networking, and sponsored the Obfuscated Perl +Contest. Sadly, this publication is no longer in circulation, but +should it be resurrected, it will most likely be announced on +http://use.perl.org/ . Beyond this, magazines that frequently carry high-quality articles on Perl are I<Web Techniques> (see http://www.webtechniques.com/), I<Performance Computing> (http://www.performance-computing.com/), and Usenix's newsletter/magazine to its members, I<login:>, at http://www.usenix.org/. Randal's Web Technique's columns are available on the web at -http://www.stonehenge.com/merlyn/WebTechniques/. +http://www.stonehenge.com/merlyn/WebTechniques/ . =head2 Perl on the Net: FTP and WWW Access -To get the best (and possibly cheapest) performance, pick a site from -the list below and use it to grab the complete list of mirror sites. +To get the best performance, pick a site from +the list below and use it to grab the complete list of mirror sites +which is at /CPAN/MIRRORED.BY or at http://mirror.cpan.org/. From there you can find the quickest site for you. Remember, the -following list is I<not> the complete list of CPAN mirrors. - - http://www.perl.com/CPAN-local - http://www.perl.com/CPAN (redirects to an ftp mirror) - ftp://cpan.valueclick.com/pub/CPAN/ +following list is I<not> the complete list of CPAN mirrors +(the complete list contains 165 sites as of January 2001): + + http://www.cpan.org/ + http://www.perl.com/CPAN/ + http://download.sourceforge.net/mirrors/CPAN/ + ftp://ftp.digital.com/pub/plan/perl/CPAN/ + ftp://ftp.flirble.org/pub/languages/perl/CPAN/ + ftp://ftp.uvsq.fr/pub/perl/CPAN/ ftp://ftp.funet.fi/pub/languages/perl/CPAN/ - http://www.cs.ruu.nl/pub/PERL/CPAN/ - ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ + ftp://ftp.dti.ad.jp/pub/lang/CPAN/ + ftp://mirror.aarnet.edu.au/pub/perl/CPAN/ + ftp://cpan.if.usp.br/pub/mirror/CPAN/ + +One may also use xx.cpan.org where "xx" is the 2-letter country code +for your domain; e.g. Australia would use au.cpan.org. =head2 What mailing lists are there for Perl? Most of the major modules (Tk, CGI, libwww-perl) have their own mailing lists. Consult the documentation that came with the module for -subscription information. The Perl Mongers attempt to maintain a -list of mailing lists at: +subscription information. - http://www.perl.org/support/online_support.html#mail + http://lists.cpan.org/ =head2 Archives of comp.lang.perl.misc -Have you tried Deja or AltaVista? Those are the +Have you tried Deja or AltaVista? Those are the best archives. Just look up "*perl*" as a newsgroup. http://www.deja.com/dnquery.xp?QRY=&DBS=2&ST=PS&defaultOp=AND&LNG=ALL&format=terse&showsort=date&maxhits=25&subjects=&groups=*perl*&authors=&fromdate=&todate= -You'll probably want to trim that down a bit, though. +You might want to trim that down a bit, though. You'll probably want more a sophisticated query and retrieval mechanism than a file listing, preferably one that allows you to retrieve @@ -370,7 +425,7 @@ let perlfaq-suggestions@perl.com know. =head2 Where can I buy a commercial version of Perl? -In a real sense, Perl already I<is> commercial software: It has a license +In a real sense, Perl already I<is> commercial software: it has a license that you can grab and carefully read to your manager. It is distributed in releases and comes in well-defined packages. There is a very large user community and an extensive literature. The comp.lang.perl.* @@ -384,13 +439,13 @@ However, these answers may not suffice for managers who require a purchase order from a company whom they can sue should anything go awry. Or maybe they need very serious hand-holding and contractual obligations. Shrink-wrapped CDs with Perl on them are available from several sources if -that will help. For example, many Perl books carry a Perl distribution -on them, as do the O'Reilly Perl Resource Kits (in both the Unix flavor +that will help. For example, many Perl books include a distribution of Perl, +as do the O'Reilly Perl Resource Kits (in both the Unix flavor and in the proprietary Microsoft flavor); the free Unix distributions also all come with Perl. -Or you can purchase commercial incidence based support through the Perl -Clinic. The following is a commercial from them: +Alternatively, you can purchase commercial incidence based support +through the Perl Clinic. The following is a commercial from them: "The Perl Clinic is a commercial Perl support service operated by ActiveState Tool Corp. and The Ingram Group. The operators have many @@ -401,7 +456,7 @@ on a wide range of platforms. we will put our best effort into understanding your problem, providing an explanation of the situation, and a recommendation on how to proceed." -Contact The Perl Clinic at: +Contact The Perl Clinic at www.PerlClinic.com @@ -419,7 +474,7 @@ See also www.perl.com for updates on tutorials, training, and support. If you are reporting a bug in the perl interpreter or the modules shipped with Perl, use the I<perlbug> program in the Perl distribution or -mail your report to perlbug@perl.com . +mail your report to perlbug@perl.org . If you are posting a bug with a non-standard port (see the answer to "What platforms is Perl available for?"), a binary distribution, or a @@ -431,40 +486,38 @@ Read the perlbug(1) man page (perl5.004 or later) for more information. =head2 What is perl.com? Perl Mongers? pm.org? perl.org? -The perl.com domain is owned by Tom Christiansen, who created it as a -public service long before perl.org came about. Despite the name, it's a -pretty non-commercial site meant to be a clearinghouse for information -about all things Perlian, accepting no paid advertisements, bouncy -happy GIFs, or silly Java applets on its pages. The Perl Home Page at -http://www.perl.com/ is currently hosted on a T3 line courtesy of Songline -Systems, a software-oriented subsidiary of O'Reilly and Associates. -Other starting points include +The Perl Home Page at http://www.perl.com/ is currently hosted on a +T3 line courtesy of Songline Systems, a software-oriented subsidiary of +O'Reilly and Associates. Other starting points include http://language.perl.com/ http://conference.perl.com/ http://reference.perl.com/ -Perl Mongers is an advocacy organization for the Perl language. For -details, see the Perl Mongers web site at http://www.perlmongers.org/. +Perl Mongers is an advocacy organization for the Perl language which +maintains the web site http://www.perl.org/ as a general advocacy +site for the Perl language. Perl Mongers uses the pm.org domain for services related to Perl user -groups. See the Perl user group web site at http://www.pm.org/ for more -information about joining, starting, or requesting services for a Perl -user group. +groups, including the hosting of mailing lists and web sites. See the +Perl user group web site at http://www.pm.org/ for more information about +joining, starting, or requesting services for a Perl user group. -Perl Mongers also maintains the perl.org domain to provide general +Perl Mongers also maintain the perl.org domain to provide general support services to the Perl community, including the hosting of mailing lists, web sites, and other services. The web site http://www.perl.org/ is a general advocacy site for the Perl language, and there are many other sub-domains for special topics, such as - http://history.perl.org/ http://bugs.perl.org/ - http://www.news.perl.org/ + http://history.perl.org/ + http://lists.perl.org/ + http://news.perl.org/ + http://use.perl.org/ =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-1999 Tom Christiansen and Nathan Torkington. +Copyright (c) 1997-2001 Tom Christiansen and Nathan Torkington. All rights reserved. When included as an integrated part of the Standard Distribution diff --git a/contrib/perl5/pod/perlfaq3.pod b/contrib/perl5/pod/perlfaq3.pod index b05b7361c0f5..49cae1a2093e 100644 --- a/contrib/perl5/pod/perlfaq3.pod +++ b/contrib/perl5/pod/perlfaq3.pod @@ -49,22 +49,22 @@ uninteresting, but may still be what you want. =head2 How do I debug my Perl programs? Have you tried C<use warnings> or used C<-w>? They enable warnings -for dubious practices. +to detect dubious practices. Have you tried C<use strict>? It prevents you from using symbolic references, makes you predeclare any subroutines that you call as bare words, and (probably most importantly) forces you to predeclare your -variables with C<my> or C<our> or C<use vars>. +variables with C<my>, C<our>, or C<use vars>. -Did you check the returns of each and every system call? The operating -system (and thus Perl) tells you whether they worked or not, and if not +Did you check the return values of each and every system call? The operating +system (and thus Perl) tells you whether they worked, and if not why. open(FH, "> /etc/cantwrite") or die "Couldn't write to /etc/cantwrite: $!\n"; Did you read L<perltrap>? It's full of gotchas for old and new Perl -programmers, and even has sections for those of you who are upgrading +programmers and even has sections for those of you who are upgrading from languages like I<awk> and I<C>. Have you tried the Perl debugger, described in L<perldebug>? You can @@ -73,10 +73,11 @@ why what it's doing isn't what it should be doing. =head2 How do I profile my Perl programs? -You should get the Devel::DProf module from CPAN, and also use -Benchmark.pm from the standard distribution. Benchmark lets you time -specific portions of your code, while Devel::DProf gives detailed -breakdowns of where your code spends its time. +You should get the Devel::DProf module from the standard distribution +(or separately on CPAN) and also use Benchmark.pm from the standard +distribution. The Benchmark module lets you time specific portions of +your code, while Devel::DProf gives detailed breakdowns of where your +code spends its time. Here's a sample use of Benchmark: @@ -104,7 +105,7 @@ on your hardware, operating system, and the load on your machine): map: 6 secs ( 4.97 usr 0.00 sys = 4.97 cpu) Be aware that a good benchmark is very hard to write. It only tests the -data you give it, and really proves little about differing complexities +data you give it and proves little about the differing complexities of contrasting algorithms. =head2 How do I cross-reference my Perl programs? @@ -125,17 +126,17 @@ challenging at best to write a stand-alone Perl parser. Of course, if you simply follow the guidelines in L<perlstyle>, you shouldn't need to reformat. The habit of formatting your code as you write it will help prevent bugs. Your editor can and should help you -with this. The perl-mode for emacs can provide a remarkable amount of -help with most (but not all) code, and even less programmable editors -can provide significant assistance. Tom swears by the following -settings in vi and its clones: +with this. The perl-mode or newer cperl-mode for emacs can provide +remarkable amounts of help with most (but not all) code, and even less +programmable editors can provide significant assistance. Tom swears +by the following settings in vi and its clones: set ai sw=4 map! ^O {^M}^[O^T Now put that in your F<.exrc> file (replacing the caret characters with control characters) and away you go. In insert mode, ^T is -for indenting, ^D is for undenting, and ^O is for blockdenting -- +for indenting, ^D is for undenting, and ^O is for blockdenting-- as it were. If you haven't used the last one, you're missing a lot. A more complete example, with comments, can be found at http://www.perl.com/CPAN-local/authors/id/TOMC/scripts/toms.exrc.gz @@ -156,42 +157,192 @@ the trick. And if not, it's easy to hack into what you want. =head2 Is there an IDE or Windows Perl Editor? -If you're on Unix, you already have an IDE -- Unix itself. This powerful -IDE derives from its interoperability, flexibility, and configurability. -If you really want to get a feel for Unix-qua-IDE, the best thing to do -is to find some high-powered programmer whose native language is Unix. -Find someone who has been at this for many years, and just sit back -and watch them at work. They have created their own IDE, one that -suits their own tastes and aptitudes. Quietly observe them edit files, -move them around, compile them, debug them, test them, etc. The entire -development *is* integrated, like a top-of-the-line German sports car: -functional, powerful, and elegant. You will be absolutely astonished -at the speed and ease exhibited by the native speaker of Unix in his -home territory. The art and skill of a virtuoso can only be seen to be -believed. That is the path to mastery -- all these cobbled little IDEs -are expensive toys designed to sell a flashy demo using cheap tricks, -and being optimized for immediate but shallow understanding rather than -enduring use, are but a dim palimpsest of real tools. - -In short, you just have to learn the toolbox. However, if you're not -on Unix, then your vendor probably didn't bother to provide you with -a proper toolbox on the so-called complete system that you forked out -your hard-earned cash on. - -PerlBuilder (XXX URL to follow) is an integrated development environment -for Windows that supports Perl development. Perl programs are just plain -text, though, so you could download emacs for Windows (???) or a vi clone -(vim) which runs on for win32 (http://www.cs.vu.nl/%7Etmgil/vi.html). -If you're transferring Windows files to Unix, be sure to transfer in -ASCII mode so the ends of lines are appropriately mangled. +Perl programs are just plain text, so any editor will do. + +If you're on Unix, you already have an IDE--Unix itself. The UNIX +philosophy is the philosophy of several small tools that each do one +thing and do it well. It's like a carpenter's toolbox. + +If you want a Windows IDE, check the following: + +=over 4 + +=item CodeMagicCD + +http://www.codemagiccd.com/ + +=item Komodo + +ActiveState's cross-platform, multi-language IDE has Perl support, +including a regular expression debugger and remote debugging +(http://www.ActiveState.com/Products/Komodo/index.html). +(Visual Perl, a Visual Studio.NET plug-in is currently (early 2001) +in beta (http://www.ActiveState.com/Products/VisualPerl/index.html)). + +=item The Object System + +(http://www.castlelink.co.uk/object_system/) is a Perl web +applications development IDE. + +=item PerlBuilder + +(http://www.solutionsoft.com/perl.htm) is an integrated development +environment for Windows that supports Perl development. + +=item Perl code magic + +(http://www.petes-place.com/codemagic.html). + +=item visiPerl+ + +http://helpconsulting.net/visiperl/, from Help Consulting. + +=back + +For editors: if you're on Unix you probably have vi or a vi clone already, +and possibly an emacs too, so you may not need to download anything. +In any emacs the cperl-mode (M-x cperl-mode) gives you perhaps the +best available Perl editing mode in any editor. + +For Windows editors: you can download an Emacs + +=over 4 + +=item GNU Emacs + +http://www.gnu.org/software/emacs/windows/ntemacs.html + +=item MicroEMACS + +http://members.nbci.com/uemacs/ + +=item XEmacs + +http://www.xemacs.org/Download/index.html + +=back + +or a vi clone such as + +=over 4 + +=item Elvis + +ftp://ftp.cs.pdx.edu/pub/elvis/ http://www.fh-wedel.de/elvis/ + +=item Vile + +http://vile.cx/ + +=item Vim + +http://www.vim.org/ + +win32: http://www.cs.vu.nl/%7Etmgil/vi.html + +=back + +For vi lovers in general, Windows or elsewhere: +http://www.thomer.com/thomer/vi/vi.html. + +nvi (http://www.bostic.com/vi/, available from CPAN in src/misc/) is +yet another vi clone, unfortunately not available for Windows, but in +UNIX platforms you might be interested in trying it out, firstly because +strictly speaking it is not a vi clone, it is the real vi, or the new +incarnation of it, and secondly because you can embed Perl inside it +to use Perl as the scripting language. nvi is not alone in this, +though: at least also vim and vile offer an embedded Perl. + +The following are Win32 multilanguage editor/IDESs that support Perl: + +=over 4 + +=item Codewright + +http://www.starbase.com/ + +=item MultiEdit + +http://www.MultiEdit.com/ + +=item SlickEdit + +http://www.slickedit.com/ + +=back + +There is also a toyedit Text widget based editor written in Perl +that is distributed with the Tk module on CPAN. The ptkdb +(http://world.std.com/~aep/ptkdb/) is a Perl/tk based debugger that +acts as a development environment of sorts. Perl Composer +(http://perlcomposer.sourceforge.net/vperl.html) is an IDE for Perl/Tk +GUI creation. + +In addition to an editor/IDE you might be interested in a more +powerful shell environment for Win32. Your options include + +=over 4 + +=item Bash + +from the Cygwin package (http://sources.redhat.com/cygwin/) + +=item Ksh + +from the MKS Toolkit (http://www.mks.com/), or the Bourne shell of +the U/WIN environment (http://www.research.att.com/sw/tools/uwin/) + +=item Tcsh + +ftp://ftp.astron.com/pub/tcsh/, see also +http://www.primate.wisc.edu/software/csh-tcsh-book/ + +=item Zsh + +ftp://ftp.blarg.net/users/amol/zsh/, see also http://www.zsh.org/ + +=back + +MKS and U/WIN are commercial (U/WIN is free for educational and +research purposes), Cygwin is covered by the GNU Public License (but +that shouldn't matter for Perl use). The Cygwin, MKS, and U/WIN all +contain (in addition to the shells) a comprehensive set of standard +UNIX toolkit utilities. + +If you're transferring text files between Unix and Windows using FTP +be sure to transfer them in ASCII mode so the ends of lines are +appropriately converted. + +On Mac OS the MacPerl Application comes with a simple 32k text editor +that behaves like a rudimentary IDE. In contrast to the MacPerl Application +the MPW Perl tool can make use of the MPW Shell itself as an editor (with +no 32k limit). + +=over 4 + +=item BBEdit and BBEdit Lite + +are text editors for Mac OS that have a Perl sensitivity mode +(http://web.barebones.com/). + +=item Alpha + +is an editor, written and extensible in Tcl, that nonetheless has +built in support for several popular markup and programming languages +including Perl and HTML (http://alpha.olm.net/). + +=back + +Pepper and Pe are programming language sensitive text editors for Mac +OS X and BeOS respectively (http://www.hekkelman.com/). =head2 Where can I get Perl macros for vi? For a complete version of Tom Christiansen's vi configuration file, -see http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/toms.exrc.gz, -the standard benchmark file for vi emulators. This runs best with nvi, +see http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/toms.exrc.gz , +the standard benchmark file for vi emulators. The file runs best with nvi, the current version of vi out of Berkeley, which incidentally can be built -with an embedded Perl interpreter -- see http://www.perl.com/CPAN/src/misc. +with an embedded Perl interpreter--see http://www.perl.com/CPAN/src/misc. =head2 Where can I get perl-mode for emacs? @@ -223,7 +374,7 @@ that doesn't force you to use Tcl just to get at Tk. Sx is an interface to the Athena Widget set. Both are available from CPAN. See the directory http://www.perl.com/CPAN/modules/by-category/08_User_Interfaces/ -Invaluable for Perl/Tk programming are: the Perl/Tk FAQ at +Invaluable for Perl/Tk programming are the Perl/Tk FAQ at http://w4.lns.cornell.edu/%7Epvhp/ptk/ptkTOC.html , the Perl/Tk Reference Guide available at http://www.perl.com/CPAN-local/authors/Stephen_O_Lidie/ , and the @@ -237,13 +388,12 @@ module, which is curses-based, can help with this. =head2 What is undump? -See the next questions. +See the next question on ``How can I make my Perl program run faster?'' =head2 How can I make my Perl program run faster? The best way to do this is to come up with a better algorithm. This -can often make a dramatic difference. Chapter 8 in the Camel has some -efficiency tips in it you might want to look at. Jon Bentley's book +can often make a dramatic difference. Jon Bentley's book ``Programming Pearls'' (that's not a misspelling!) has some good tips on optimization, too. Advice on benchmarking boils down to: benchmark and profile to make sure you're optimizing the right part, look for @@ -254,8 +404,8 @@ A different approach is to autoload seldom-used Perl code. See the AutoSplit and AutoLoader modules in the standard distribution for that. Or you could locate the bottleneck and think about writing just that part in C, the way we used to take bottlenecks in C code and -write them in assembler. Similar to rewriting in C is the use of -modules that have critical sections written in C (for instance, the +write them in assembler. Similar to rewriting in C, +modules that have critical sections can be written in C (for instance, the PDL module from CPAN). In some cases, it may be worth it to use the backend compiler to @@ -294,7 +444,7 @@ shared amongst all hashes using them, so require no reallocation. In some cases, using substr() or vec() to simulate arrays can be highly beneficial. For example, an array of a thousand booleans will take at least 20,000 bytes of space, but it can be turned into one -125-byte bit vector for a considerable memory savings. The standard +125-byte bit vector--a considerable memory savings. The standard Tie::SubstrHash module can also help for certain types of data structure. If you're working with specialist data structures (matrices, for instance) modules that implement these in C may use @@ -339,7 +489,7 @@ $scalar> will return memory to the system, while on Solaris 2.6 it won't. In general, try it yourself and see. However, judicious use of my() on your variables will help make sure -that they go out of scope so that Perl can free up their storage for +that they go out of scope so that Perl can free up that space for use in other parts of your program. A global variable, of course, never goes out of scope, so you can't get its space automatically reclaimed, although undef()ing and/or delete()ing it will achieve the same effect. @@ -380,12 +530,13 @@ care. See http://www.perl.com/CPAN/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI/ . A non-free, commercial product, ``The Velocity Engine for Perl'', -(http://www.binevolve.com/ or http://www.binevolve.com/velocigen/) might -also be worth looking at. It will allow you to increase the performance -of your Perl programs, up to 25 times faster than normal CGI Perl by -running in persistent Perl mode, or 4 to 5 times faster without any -modification to your existing CGI programs. Fully functional evaluation -copies are available from the web site. +(http://www.binevolve.com/ or http://www.binevolve.com/velocigen/ ) +might also be worth looking at. It will allow you to increase the +performance of your Perl programs, running programs up to 25 times +faster than normal CGI Perl when running in persistent Perl mode or 4 +to 5 times faster without any modification to your existing CGI +programs. Fully functional evaluation copies are available from the +web site. =head2 How can I hide the source for my Perl program? @@ -395,12 +546,12 @@ unsatisfactory) solutions with varying levels of ``security''. First of all, however, you I<can't> 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, only by people with access to -the filesystem) So you have to leave the permissions at the socially +readable by people on the web, though--only by people with access to +the filesystem.) So you have to leave the permissions at the socially friendly 0755 level. Some people regard this as a security problem. If your program does -insecure things, and relies on people not knowing how to exploit those +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 @@ -412,7 +563,7 @@ the byte code compiler and interpreter described below, but the curious might still 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 +your code, but none can definitively conceal it (true of every language, not just Perl). If you're concerned about people profiting from your code, then the @@ -434,10 +585,10 @@ really for people looking for turn-key solutions. Merely compiling into C does not in and of itself guarantee that your code will run very much faster. That's because except for lucky cases where a lot of native type inferencing is possible, the normal Perl -run time system is still present and so your program will take just as +run-time system is still present and so your program will take just as long to run and be just as big. Most programs save little more than compilation time, leaving execution no more than 10-30% faster. A few -rare programs actually benefit significantly (like several times +rare programs actually benefit significantly (even running several times faster), but this takes some tweaking of your code. You'll probably be astonished to learn that the current version of the @@ -452,8 +603,8 @@ For example, on one author's system, F</usr/bin/perl> is only 11k in size! In general, the compiler will do nothing to make a Perl program smaller, -faster, more portable, or more secure. In fact, it will usually hurt -all of those. The executable will be bigger, your VM system may take +faster, more portable, or more secure. In fact, it can make your +situation worse. The executable will be bigger, your VM system may take longer to load the whole thing, the binary is fragile and hard to fix, and compilation never stopped software piracy in the form of crackers, viruses, or bootleggers. The real advantage of the compiler is merely @@ -463,11 +614,13 @@ Perl install anyway. =head2 How can I compile Perl into Java? -You can't. Not yet, anyway. You can integrate Java and Perl with the +You can also integrate Java and Perl with the Perl Resource Kit from O'Reilly and Associates. See -http://www.oreilly.com/catalog/prkunix/ for more information. -The Java interface will be supported in the core 5.6 release -of Perl. +http://www.oreilly.com/catalog/prkunix/ . + +Perl 5.6 comes with Java Perl Lingo, or JPL. JPL, still in +development, allows Perl code to be called from Java. See jpl/README +in the Perl source tree. =head2 How can I get C<#!perl> to work on [MS-DOS,NT,...]? @@ -477,7 +630,7 @@ For OS/2 just use as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's `extproc' handling). For DOS one should first invent a corresponding -batch file, and codify it in C<ALTERNATIVE_SHEBANG> (see the +batch file and codify it in C<ALTERNATIVE_SHEBANG> (see the F<INSTALL> file in the source distribution for more information). The Win95/NT installation, when using the ActiveState port of Perl, @@ -546,9 +699,9 @@ For example: # VMS perl -e "print ""Hello world\n""" -The problem is that none of this is reliable: it depends on the +The problem is that none of these examples are reliable: they depend on the command interpreter. Under Unix, the first two often work. Under DOS, -it's entirely possible neither works. If 4DOS was the command shell, +it's entirely possible that neither works. If 4DOS was the command shell, you'd probably have better luck like this: perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>"" @@ -596,13 +749,12 @@ when it runs fine on the command line'', see these sources: CGI Security FAQ http://www.go2net.com/people/paulp/cgi-security/safe-cgi.txt - =head2 Where can I learn about object-oriented Perl programming? -A good place to start is L<perltoot>, and you can use L<perlobj> and -L<perlbot> for reference. Perltoot didn't come out until the 5.004 -release, but you can get a copy (in pod, html, or postscript) from -http://www.perl.com/CPAN/doc/FMTEYEWTK/ . +A good place to start is L<perltoot>, and you can use L<perlobj>, +L<perlboot>, and L<perlbot> for reference. Perltoot didn't come out +until the 5.004 release; you can get a copy (in pod, html, or +postscript) from http://www.perl.com/CPAN/doc/FMTEYEWTK/ . =head2 Where can I learn about linking C with Perl? [h2xs, xsubpp] @@ -614,7 +766,7 @@ how the authors of existing extension modules wrote their code and solved their problems. =head2 I've read perlembed, perlguts, etc., but I can't embed perl in -my C program, what am I doing wrong? +my C program; what am I doing wrong? Download the ExtUtils::Embed kit from CPAN and run `make test'. If the tests pass, read the pods again and again and again. If they diff --git a/contrib/perl5/pod/perlfaq4.pod b/contrib/perl5/pod/perlfaq4.pod index e997a8fcb96a..8c570c268331 100644 --- a/contrib/perl5/pod/perlfaq4.pod +++ b/contrib/perl5/pod/perlfaq4.pod @@ -4,7 +4,7 @@ perlfaq4 - Data Manipulation ($Revision: 1.49 $, $Date: 1999/05/23 20:37:49 $) =head1 DESCRIPTION -The section of the FAQ answers question related to the manipulation +The section of the FAQ answers questions related to the manipulation of data as numbers, dates, strings, arrays, hashes, and miscellaneous data issues. @@ -13,13 +13,13 @@ data issues. =head2 Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)? The infinite set that a mathematician thinks of as the real numbers can -only be approximate on a computer, since the computer only has a finite +only be approximated on a computer, since the computer only has a finite number of bits to store an infinite number of, um, numbers. Internally, your computer represents floating-point numbers in binary. Floating-point numbers read in from a file or appearing as literals in your program are converted from their decimal floating-point -representation (eg, 19.95) to the internal binary representation. +representation (eg, 19.95) to an internal binary representation. However, 19.95 can't be precisely represented as a binary floating-point number, just like 1/3 can't be exactly represented as a @@ -29,7 +29,7 @@ of 19.95, therefore, isn't exactly 19.95. When a floating-point number gets printed, the binary floating-point representation is converted back to decimal. These decimal numbers are displayed in either the format you specify with printf(), or the -current output format for numbers (see L<perlvar/"$#"> if you use +current output format for numbers. (See L<perlvar/"$#"> if you use print. C<$#> has a different default value in Perl5 than it did in Perl4. Changing C<$#> yourself is deprecated.) @@ -75,7 +75,7 @@ functions. $ceil = ceil(3.5); # 4 $floor = floor(3.5); # 3 -In 5.000 to 5.003 Perls, trigonometry was done in the Math::Complex +In 5.000 to 5.003 perls, trigonometry was done in the Math::Complex module. With 5.004, the Math::Trig module (part of the standard Perl distribution) implements the trigonometric functions. Internally it uses the Math::Complex module and some functions can break out from @@ -206,8 +206,8 @@ than more. Computers are good at being predictable and bad at being random (despite appearances caused by bugs in your programs :-). -http://www.perl.com/CPAN/doc/FMTEYEWTK/random, courtesy of Tom -Phoenix, talks more about this.. John von Neumann said, ``Anyone who +http://www.perl.com/CPAN/doc/FMTEYEWTK/random , courtesy of Tom +Phoenix, talks more about this. John von Neumann said, ``Anyone who attempts to generate random numbers by deterministic means is, of course, living in a state of sin.'' @@ -286,7 +286,7 @@ Use the Time::JulianDay module (part of the Time-modules bundle available from CPAN.) Before you immerse yourself too deeply in this, be sure to verify that it -is the I<Julian> Day you really want. Are they really just interested in +is the I<Julian> Day you really want. Are you really just interested in a way of getting serial days so that they can do date arithmetic? If you are interested in performing date arithmetic, this can be done using either Date::Manip or Date::Calc, without converting to Julian Day first. @@ -370,7 +370,7 @@ you can. Is that the pencil's fault? Of course it isn't. The date and time functions supplied with Perl (gmtime and localtime) supply adequate information to determine the year well beyond 2000 (2038 is when trouble strikes for 32-bit machines). The year returned -by these functions when used in an array context is the year minus 1900. +by these functions when used in a list context is the year minus 1900. For years between 1910 and 1999 this I<happens> to be a 2-digit decimal number. To avoid the year 2000 problem simply do not treat the year as a 2-digit number. It isn't. @@ -398,7 +398,7 @@ addresses, etc.) for details. It depends just what you mean by ``escape''. URL escapes are dealt with in L<perlfaq9>. Shell escapes with the backslash (C<\>) -character are removed with: +character are removed with s/\\(.)/$1/g; @@ -512,7 +512,7 @@ use substr() as an lvalue: substr($a, 0, 3) = "Tom"; Although those with a pattern matching kind of thought process will -likely prefer: +likely prefer $a =~ s/^.../Tom/; @@ -549,7 +549,7 @@ repetition count and repeated pattern like this: =head2 How can I count the number of occurrences of a substring within a string? -There are a number of ways, with varying efficiency: If you want a +There are a number of ways, with varying efficiency. If you want a count of a certain single character (X) within a string, you can use the C<tr///> function like so: @@ -574,8 +574,8 @@ To make the first letter of each word upper case: $line =~ s/\b(\w)/\U$1/g; This has the strange effect of turning "C<don't do it>" into "C<Don'T -Do It>". Sometimes you might want this, instead (Suggested by brian d. -foy): +Do It>". Sometimes you might want this. Other times you might need a +more thorough solution (Suggested by brian d. foy): $string =~ s/ ( (^\w) #at the beginning of the line @@ -637,15 +637,15 @@ distribution) lets you say: use Text::ParseWords; @new = quotewords(",", 0, $text); -There's also a Text::CSV module on CPAN. +There's also a Text::CSV (Comma-Separated Values) module on CPAN. =head2 How do I strip blank space from the beginning/end of a string? -Although the simplest approach would seem to be: +Although the simplest approach would seem to be $string =~ s/^\s*(.*?)\s*$/$1/; -Not only is this unnecessarily slow and destructive, it also fails with +not only is this unnecessarily slow and destructive, it also fails with embedded newlines. It is much faster to do this operation in two steps: $string =~ s/^\s+//; @@ -740,7 +740,7 @@ you can use this kind of thing: =head2 How do I find the soundex value of a string? Use the standard Text::Soundex module distributed with Perl. -But before you do so, you may want to determine whether `soundex' is in +Before you do so, you may want to determine whether `soundex' is in fact what you think it is. Knuth's soundex algorithm compresses words into a small space, and so it does not necessarily distinguish between two words which you might want to appear separately. For example, the @@ -779,9 +779,9 @@ of the FAQ. =head2 What's wrong with always quoting "$vars"? -The problem is that those double-quotes force stringification, -coercing numbers and references into strings, even when you -don't want them to be. Think of it this way: double-quote +The problem is that those double-quotes force stringification-- +coercing numbers and references into strings--even when you +don't want them to be strings. Think of it this way: double-quote expansion is used to produce new strings. If you already have a string, why do you need more? @@ -857,13 +857,13 @@ in the indentation. A nice general-purpose fixer-upper function for indented here documents follows. It expects to be called with a here document as its argument. It looks to see whether each line begins with a common substring, and -if so, strips that off. Otherwise, it takes the amount of leading -white space found on the first line and removes that much off each +if so, strips that substring off. Otherwise, it takes the amount of leading +whitespace found on the first line and removes that much off each subsequent line. sub fix { local $_ = shift; - my ($white, $leader); # common white space and common leading string + my ($white, $leader); # common whitespace and common leading string if (/^\s*(?:([^\w\s]+)(\s*).*\n)(?:\s*\1\2?.*\n)+$/) { ($white, $leader) = ($2, quotemeta($1)); } else { @@ -886,7 +886,7 @@ This works with leading special strings, dynamically determined: @@@ } MAIN_INTERPRETER_LOOP -Or with a fixed amount of leading white space, with remaining +Or with a fixed amount of leading whitespace, with remaining indentation correctly preserved: $poem = fix<<EVER_ON_AND_ON; @@ -910,7 +910,7 @@ Subroutines are passed and return lists, you put things into list context, you initialize arrays with lists, and you foreach() across a list. C<@> variables are arrays, anonymous arrays are arrays, arrays in scalar context behave like the number of elements in them, subroutines -access their arguments through the array C<@_>, push/pop/shift only work +access their arguments through the array C<@_>, and push/pop/shift only work on arrays. As a side note, there's no such thing as a list in scalar context. @@ -924,7 +924,7 @@ last value to be returned: 9. =head2 What is the difference between $array[1] and @array[1]? -The former is a scalar value, the latter an array slice, which makes +The former is a scalar value; the latter an array slice, making it a list with one (scalar) value. You should use $ when you want a scalar value (most of the time) and @ when you want a list with one scalar value in it (very, very rarely; nearly never, in fact). @@ -948,33 +948,43 @@ ordered and whether you wish to preserve the ordering. =over 4 -=item a) If @in is sorted, and you want @out to be sorted: +=item a) + +If @in is sorted, and you want @out to be sorted: (this assumes all true values in the array) - $prev = 'nonesuch'; - @out = grep($_ ne $prev && ($prev = $_), @in); + $prev = "not equal to $in[0]"; + @out = grep($_ ne $prev && ($prev = $_, 1), @in); This is nice in that it doesn't use much extra memory, simulating -uniq(1)'s behavior of removing only adjacent duplicates. It's less -nice in that it won't work with false values like undef, 0, or ""; -"0 but true" is OK, though. +uniq(1)'s behavior of removing only adjacent duplicates. The ", 1" +guarantees that the expression is true (so that grep picks it up) +even if the $_ is 0, "", or undef. + +=item b) -=item b) If you don't know whether @in is sorted: +If you don't know whether @in is sorted: undef %saw; @out = grep(!$saw{$_}++, @in); -=item c) Like (b), but @in contains only small integers: +=item c) + +Like (b), but @in contains only small integers: @out = grep(!$saw[$_]++, @in); -=item d) A way to do (b) without any loops or greps: +=item d) + +A way to do (b) without any loops or greps: undef %saw; @saw{@in} = (); @out = sort keys %saw; # remove sort if undesired -=item e) Like (d), but @in contains only small positive integers: +=item e) + +Like (d), but @in contains only small positive integers: undef @ary; @ary[@in] = @in; @@ -1023,11 +1033,11 @@ Now check whether C<vec($read,$n,1)> is true for some C<$n>. Please do not use - $is_there = grep $_ eq $whatever, @array; + ($is_there) = grep $_ eq $whatever, @array; or worse yet - $is_there = grep /$whatever/, @array; + ($is_there) = grep /$whatever/, @array; These are slow (checks every element even if the first matches), inefficient (same reason), and potentially buggy (what if there are @@ -1057,7 +1067,7 @@ each element is unique in a given array: } Note that this is the I<symmetric difference>, that is, all elements in -either A or in B, but not in both. Think of it as an xor operation. +either A or in B but not in both. Think of it as an xor operation. =head2 How do I test whether two arrays or hashes are equal? @@ -1148,7 +1158,7 @@ You could walk the list this way: } print "\n"; -You could grow the list this way: +You could add to the list this way: my ($head, $tail); $tail = append($head, 1); # grow a new head @@ -1189,7 +1199,6 @@ Use this: my $i; for ($i = @$array; --$i; ) { my $j = int rand ($i+1); - next if $i == $j; @$array[$i,$j] = @$array[$j,$i]; } } @@ -1197,7 +1206,7 @@ Use this: fisher_yates_shuffle( \@array ); # permutes @array in place You've probably seen shuffling algorithms that work using splice, -randomly picking another element to swap the current element with: +randomly picking another element to swap the current element with srand; @new = (); @@ -1298,7 +1307,7 @@ case-insensitively. } @sorted = @data[ sort { $idx[$a] cmp $idx[$b] } 0 .. $#idx ]; -Which could also be written this way, using a trick +which could also be written this way, using a trick that's come to be known as the Schwartzian Transform: @sorted = map { $_->[0] } @@ -1439,7 +1448,7 @@ table, at which point you've totally bamboozled the iterator code. Even if the table doesn't double, there's no telling whether your new entry will be inserted before or after the current iterator position. -Either treasure up your changes and make them after the iterator finishes, +Either treasure up your changes and make them after the iterator finishes or use keys to fetch all the old keys at once, and iterate over the list of keys. @@ -1472,7 +1481,7 @@ take the scalar sense of the keys() function: $num_keys = scalar keys %hash; -In void context, the keys() function just resets the iterator, which is +The keys() function also resets the iterator, which in void context is faster for tied hashes than would be iterating through the whole hash, one key-value pair at a time. @@ -1488,8 +1497,8 @@ keys or values: } keys %hash; # and by value Here we'll do a reverse numeric sort by value, and if two keys are -identical, sort by length of key, and if that fails, by straight ASCII -comparison of the keys (well, possibly modified by your locale -- see +identical, sort by length of key, or if that fails, by straight ASCII +comparison of the keys (well, possibly modified by your locale--see L<perllocale>). @keys = sort { @@ -1746,7 +1755,7 @@ if you just want to say, ``Is this a float?'' Or you could check out the String::Scanf module on CPAN instead. The POSIX module (part of the standard Perl distribution) provides the -C<strtol> and C<strtod> for converting strings to double and longs, +C<strtod> and C<strtol> for converting strings to double and longs, respectively. =head2 How do I keep persistent data across program calls? diff --git a/contrib/perl5/pod/perlfaq5.pod b/contrib/perl5/pod/perlfaq5.pod index 6ae7755f8b72..4ae7407e96f9 100644 --- a/contrib/perl5/pod/perlfaq5.pod +++ b/contrib/perl5/pod/perlfaq5.pod @@ -10,7 +10,7 @@ formats, and footers. =head2 How do I flush/unbuffer an output filehandle? Why must I do this? The C standard I/O library (stdio) normally buffers characters sent to -devices. This is done for efficiency reasons, so that there isn't a +devices. This is done for efficiency reasons so that there isn't a system call for each byte. Any time you use print() or write() in Perl, you go though this buffering. syswrite() circumvents stdio and buffering. @@ -83,16 +83,17 @@ Perl is a programming language. You have to decompose the problem into low-level calls to read, write, open, close, and seek. Although humans have an easy time thinking of a text file as being a -sequence of lines that operates much like a stack of playing cards -- or -punch cards -- computers usually see the text file as a sequence of bytes. +sequence of lines that operates much like a stack of playing cards--or +punch cards--computers usually see the text file as a sequence of bytes. In general, there's no direct way for Perl to seek to a particular line of a file, insert text into a file, or remove text from a file. -(There are exceptions in special circumstances. You can add or remove at -the very end of the file. Another is replacing a sequence of bytes with -another sequence of the same length. Another is using the C<$DB_RECNO> -array bindings as documented in L<DB_File>. Yet another is manipulating -files with all lines the same length.) +(There are exceptions in special circumstances. You can add or remove +data at the very end of the file. A sequence of bytes can be replaced +with another sequence of the same length. The C<$DB_RECNO> array +bindings as documented in L<DB_File> also provide a direct way of +modifying a file. Files where all lines are the same length are also +easy to alter.) The general solution is to create a temporary copy of the text file with the changes you want, then copy that over the original. This assumes @@ -174,16 +175,17 @@ This assumes no funny games with newline translations. =head2 How do I make a temporary file name? Use the C<new_tmpfile> class method from the IO::File module to get a -filehandle opened for reading and writing. Use this if you don't -need to know the file's name. +filehandle opened for reading and writing. Use it if you don't +need to know the file's name: use IO::File; $fh = IO::File->new_tmpfile() or die "Unable to make new temporary file: $!"; -Or you can use the C<tmpnam> function from the POSIX module to get a -filename that you then open yourself. Use this if you do need to know -the file's name. +If you do need to know the file's name, you can use the C<tmpnam> +function from the POSIX module to get a filename that you then open +yourself: + use Fcntl; use POSIX qw(tmpnam); @@ -199,9 +201,9 @@ the file's name. # now go on to use the file ... -If you're committed to doing this by hand, use the process ID and/or -the current time-value. If you need to have many temporary files in -one process, use a counter: +If you're committed to creating a temporary file by hand, use the +process ID and/or the current time-value. If you need to have many +temporary files in one process, use a counter: BEGIN { use Fcntl; @@ -272,7 +274,7 @@ had, for example, a function named TmpHandle(), or a variable named # *HostFile automatically closes/disappears here } -Here's how to use this in a loop to open and store a bunch of +Here's how to use typeglobs in a loop to open and store a bunch of filehandles. We'll use as values of the hash an ordered pair to make it easy to sort the hash in insertion order. @@ -292,8 +294,8 @@ pair to make it easy to sort the hash in insertion order. } For passing filehandles to functions, the easiest way is to -preface them with a star, as in func(*STDIN). See L<perlfaq7/"Passing -Filehandles"> for details. +preface them with a star, as in func(*STDIN). +See L<perlfaq7/"Passing Filehandles"> for details. If you want to create many anonymous handles, you should check out the Symbol, FileHandle, or IO::Handle (etc.) modules. Here's the equivalent @@ -306,7 +308,7 @@ code with Symbol::gensym, which is reasonably light-weight: $file{$filename} = [ $i++, $fh ]; } -Or here using the semi-object-oriented FileHandle module, which certainly +Here's using the semi-object-oriented FileHandle module, which certainly isn't light-weight: use FileHandle; @@ -317,7 +319,7 @@ isn't light-weight: } Please understand that whether the filehandle happens to be a (probably -localized) typeglob or an anonymous handle from one of the modules, +localized) typeglob or an anonymous handle from one of the modules in no way affects the bizarre rules for managing indirect handles. See the next question. @@ -325,7 +327,7 @@ See the next question. An indirect filehandle is using something other than a symbol in a place that a filehandle is expected. Here are ways -to get those: +to get indirect filehandles: $fh = SOME_FH; # bareword is strict-subs hostile $fh = "SOME_FH"; # strict-refs hostile; same package only @@ -333,7 +335,7 @@ to get those: $fh = \*SOME_FH; # ref to typeglob (bless-able) $fh = *SOME_FH{IO}; # blessed IO::Handle from *SOME_FH typeglob -Or to use the C<new> method from the FileHandle or IO modules to +Or, you can use the C<new> method from the FileHandle or IO modules to create an anonymous filehandle, store that in a scalar variable, and use it as though it were a normal filehandle. @@ -378,9 +380,10 @@ is risky.) accept_fh($handle); In the examples above, we assigned the filehandle to a scalar variable -before using it. That is because only simple scalar variables, -not expressions or subscripts into hashes or arrays, can be used with -built-ins like C<print>, C<printf>, or the diamond operator. These are +before using it. That is because only simple scalar variables, not +expressions or subscripts of hashes or arrays, can be used with +built-ins like C<print>, C<printf>, or the diamond operator. Using +something other than a simple scalar varaible as a filehandle is illegal and won't even compile: @fd = (*STDIN, *STDOUT, *STDERR); @@ -449,7 +452,7 @@ You can't just: because you have to put the comma in and then recalculate your position. -Alternatively, this commifies all numbers in a line regardless of +Alternatively, this code commifies all numbers in a line regardless of whether they have decimal portions, are preceded by + or -, or whatever: @@ -463,11 +466,11 @@ whatever: =head2 How can I translate tildes (~) in a filename? -Use the <> (glob()) operator, documented in L<perlfunc>. This -requires that you have a shell installed that groks tildes, meaning -csh or tcsh or (some versions of) ksh, and thus may have portability -problems. The Glob::KGlob module (available from CPAN) gives more -portable glob functionality. +Use the <> (glob()) operator, documented in L<perlfunc>. Older +versions of Perl require that you have a shell installed that groks +tildes. Recent perl versions have this feature built in. The +Glob::KGlob module (available from CPAN) gives more portable glob +functionality. Within Perl, you may use this directly: @@ -551,8 +554,8 @@ To open a file without blocking, creating if necessary: Be warned that neither creation nor deletion of files is guaranteed to be an atomic operation over NFS. That is, two processes might both -successful create or unlink the same file! Therefore O_EXCL -isn't so exclusive as you might wish. +successfully create or unlink the same file! Therefore O_EXCL +isn't as exclusive as you might wish. See also the new L<perlopentut> if you have it (new for 5.6). @@ -573,15 +576,15 @@ one that doesn't use the shell to do globbing. Due to the current implementation on some operating systems, when you use the glob() function or its angle-bracket alias in a scalar -context, you may cause a leak and/or unpredictable behavior. It's +context, you may cause a memory leak and/or unpredictable behavior. It's best therefore to use glob() only in list context. =head2 How can I open a file with a leading ">" or trailing blanks? Normally perl ignores trailing blanks in filenames, and interprets certain leading characters (or a trailing "|") to mean something -special. To avoid this, you might want to use a routine like this. -It makes incomplete pathnames into explicit relative ones, and tacks a +special. To avoid this, you might want to use a routine like the one below. +It turns incomplete pathnames into explicit relative ones, and tacks a trailing null byte on the name to make perl leave it alone: sub safe_filename { @@ -603,7 +606,7 @@ It would be a lot clearer to use sysopen(), though: use Fcntl; $badpath = "<<<something really wicked "; - open (FH, $badpath, O_WRONLY | O_CREAT | O_TRUNC) + sysopen (FH, $badpath, O_WRONLY | O_CREAT | O_TRUNC) or die "can't open $badpath: $!"; For more information, see also the new L<perlopentut> if you have it @@ -611,10 +614,10 @@ For more information, see also the new L<perlopentut> if you have it =head2 How can I reliably rename a file? -Well, usually you just use Perl's rename() function. But that may not -work everywhere, in particular, renaming files across file systems. +Well, usually you just use Perl's rename() function. That may not +work everywhere, though, particularly when renaming files across file systems. Some sub-Unix systems have broken ports that corrupt the semantics of -rename() -- for example, WinNT does this right, but Win95 and Win98 +rename()--for example, WinNT does this right, but Win95 and Win98 are broken. (The last two parts are not surprising, but the first is. :-) If your operating system supports a proper mv(1) program or its moral @@ -624,11 +627,11 @@ equivalent, this works: It may be more compelling to use the File::Copy module instead. You just copy to the new file to the new name (checking return values), -then delete the old one. This isn't really the same semantics as a +then delete the old one. This isn't really the same semantically as a real rename(), though, which preserves metainformation like permissions, timestamps, inode info, etc. -The newer version of File::Copy exports a move() function. +Newer versions of File::Copy exports a move() function. =head2 How can I lock a file? @@ -654,12 +657,12 @@ filehandle be open for writing (or appending, or read/writing). Some versions of flock() can't lock files over a network (e.g. on NFS file systems), so you'd need to force the use of fcntl(2) when you build Perl. -But even this is dubious at best. See the flock entry of L<perlfunc>, +But even this is dubious at best. See the flock entry of L<perlfunc> and the F<INSTALL> file in the source distribution for information on building Perl to do this. Two potentially non-obvious but traditional flock semantics are that -it waits indefinitely until the lock is granted, and that its locks +it waits indefinitely until the lock is granted, and that its locks are I<merely advisory>. Such discretionary locks are more flexible, but offer fewer guarantees. This means that files locked with flock() may be modified by programs that do not also use flock(). Cars that stop @@ -667,13 +670,13 @@ for red lights get on well with each other, but not with cars that don't stop for red lights. See the perlport manpage, your port's specific documentation, or 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 +(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.) -For more information on file locking, see also L<perlopentut/"File -Locking"> if you have it (new for 5.6). +For more information on file locking, see also +L<perlopentut/"File Locking"> if you have it (new for 5.6). =back @@ -700,20 +703,18 @@ these tend to involve busy-wait, which is also subdesirable. Didn't anyone ever tell you web-page hit counters were useless? They don't count number of hits, they're a waste of time, and they serve -only to stroke the writer's vanity. Better to pick a random number. -It's more realistic. +only to stroke the writer's vanity. It's better to pick a random number; +they're more realistic. Anyway, this is what you can do if you can't help yourself. - use Fcntl ':flock'; + use Fcntl qw(:DEFAULT :flock); sysopen(FH, "numfile", O_RDWR|O_CREAT) or die "can't open numfile: $!"; flock(FH, LOCK_EX) or die "can't flock numfile: $!"; $num = <FH> || 0; seek(FH, 0, 0) or die "can't rewind numfile: $!"; truncate(FH, 0) or die "can't truncate numfile: $!"; (print FH $num+1, "\n") or die "can't write numfile: $!"; - # Perl as of 5.004 automatically flushes before unlocking - flock(FH, LOCK_UN) or die "can't flock numfile: $!"; close FH or die "can't close numfile: $!"; Here's a much better web-page hit counter: @@ -743,7 +744,7 @@ like this: close FH; Locking and error checking are left as an exercise for the reader. -Don't forget them, or you'll be quite sorry. +Don't forget them or you'll be quite sorry. =head2 How do I get a file's timestamp in perl? @@ -793,7 +794,7 @@ Error checking is, as usual, left as an exercise for the reader. Note that utime() currently doesn't work correctly with Win95/NT ports. A bug has been reported. Check it carefully before using -it on those platforms. +utime() on those platforms. =head2 How do I print to more than one file at once? @@ -815,8 +816,8 @@ Or even: close(STDOUT) or die "Closing: $!\n"; Otherwise you'll have to write your own multiplexing print -function -- or your own tee program -- or use Tom Christiansen's, -at http://www.perl.com/CPAN/authors/id/TOMC/scripts/tct.gz, which is +function--or your own tee program--or use Tom Christiansen's, +at http://www.perl.com/CPAN/authors/id/TOMC/scripts/tct.gz , which is written in Perl and offers much greater functionality than the stock version. @@ -834,20 +835,20 @@ do so one line at a time: This is tremendously more efficient than reading the entire file into memory as an array of lines and then processing it one element at a time, -which is often -- if not almost always -- the wrong approach. Whenever +which is often--if not almost always--the wrong approach. Whenever you see someone do this: @lines = <INPUT>; -You should think long and hard about why you need everything loaded +you should think long and hard about why you need everything loaded at once. It's just not a scalable solution. You might also find it -more fun to use the the standard DB_File module's $DB_RECNO bindings, +more fun to use the standard DB_File module's $DB_RECNO bindings, which allow you to tie an array to a file so that accessing an element the array actually accesses the corresponding line in the file. On very rare occasion, you may have an algorithm that demands that the entire file be in memory at once as one scalar. The simplest solution -to that is: +to that is $var = `cat $file`; @@ -886,7 +887,7 @@ Note that a blank line must have no blanks in it. Thus C<"fred\n You can use the builtin C<getc()> function for most filehandles, but it won't (easily) work on a terminal device. For STDIN, either use -the Term::ReadKey module from CPAN, or use the sample code in +the Term::ReadKey module from CPAN or use the sample code in L<perlfunc/getc>. If your system supports the portable operating system programming @@ -942,7 +943,7 @@ turns off echo processing as well. END { cooked() } -The Term::ReadKey module from CPAN may be easier to use. Recent version +The Term::ReadKey module from CPAN may be easier to use. Recent versions include also support for non-portable systems as well. use Term::ReadKey; @@ -997,8 +998,8 @@ table: # 78-83 ALT 1234567890-= # 84 CTR PgUp -This is all trial and error I did a long time ago, I hope I'm reading the -file that worked. +This is all trial and error I did a long time ago; I hope I'm reading the +file that worked... =head2 How can I tell whether there's a character waiting on a filehandle? @@ -1056,7 +1057,7 @@ And then hard-code it, leaving porting as an exercise to your successor. ioctl(FH, $FIONREAD, $size) or die "Couldn't call ioctl: $!\n"; $size = unpack("L", $size); -FIONREAD requires a filehandle connected to a stream, meaning sockets, +FIONREAD requires a filehandle connected to a stream, meaning that sockets, pipes, and tty devices work, but I<not> files. =head2 How do I do a C<tail -f> in perl? @@ -1111,14 +1112,14 @@ Error checking, as always, has been left as an exercise for the reader. This should rarely be necessary, as the Perl close() function is to be used for things that Perl opened itself, even if it was a dup of a -numeric descriptor, as with MHCONTEXT above. But if you really have +numeric descriptor as with MHCONTEXT above. But if you really have to, you may be able to do this: require 'sys/syscall.ph'; $rc = syscall(&SYS_close, $fd + 0); # must force numeric die "can't sysclose $fd: $!" unless $rc == -1; -Or just use the fdopen(3S) feature of open(): +Or, just use the fdopen(3S) feature of open(): { local *F; @@ -1138,7 +1139,7 @@ have a file called "c:(tab)emp(formfeed)oo" or Either single-quote your strings, or (preferably) use forward slashes. Since all DOS and Windows versions since something like MS-DOS 2.0 or so have treated C</> and C<\> the same in a path, you might as well use the -one that doesn't clash with Perl -- or the POSIX shell, ANSI C and C++, +one that doesn't clash with Perl--or the POSIX shell, ANSI C and C++, awk, Tcl, Java, or Python, just to mention a few. POSIX paths are more portable, too. @@ -1173,7 +1174,7 @@ Here's an algorithm from the Camel Book: This has a significant advantage in space over reading the whole file in. A simple proof by induction is available upon -request if you doubt its correctness. +request if you doubt the algorithm's correctness. =head2 Why do I get weird spaces when I print an array of lines? @@ -1183,7 +1184,7 @@ Saying joins together the elements of C<@lines> with a space between them. If C<@lines> were C<("little", "fluffy", "clouds")> then the above -statement would print: +statement would print little fluffy clouds diff --git a/contrib/perl5/pod/perlfaq6.pod b/contrib/perl5/pod/perlfaq6.pod index bf007ee26be4..ed6c01b31b18 100644 --- a/contrib/perl5/pod/perlfaq6.pod +++ b/contrib/perl5/pod/perlfaq6.pod @@ -8,8 +8,9 @@ This section is surprisingly small because the rest of the FAQ is littered with answers involving regular expressions. For example, decoding a URL and checking whether something is a number are handled with regular expressions, but those answers are found elsewhere in -this document (in the section on Data and the Networking one on -networking, to be precise). +this document (in L<perlfaq9>: ``How do I decode or create those %-encodings +on the web'' and L<perfaq4>: ``How do I determine whether a scalar is +a number/whole/integer/float'', to be precise). =head2 How can I hope to use regular expressions without creating illegible and unmaintainable code? @@ -175,7 +176,7 @@ appear within a certain time. $file->waitfor('/second line\n/'); print $file->getline; -=head2 How do I substitute case insensitively on the LHS, but preserving case on the RHS? +=head2 How do I substitute case insensitively on the LHS while preserving case on the RHS? Here's a lovely Perlish solution by Larry Rosler. It exploits properties of bitwise xor on ASCII strings. @@ -185,7 +186,7 @@ properties of bitwise xor on ASCII strings. $old = 'test'; $new = 'success'; - s{(\Q$old\E} + s{(\Q$old\E)} { uc $new | (uc $1 ^ $1) . (uc(substr $1, -1) ^ substr $1, -1) x (length($new) - length $1) @@ -280,10 +281,11 @@ Without the \Q, the regex would also spuriously match "di". =head2 What is C</o> really for? Using a variable in a regular expression match forces a re-evaluation -(and perhaps recompilation) each time through. The C</o> modifier -locks in the regex the first time it's used. This always happens in a -constant regular expression, and in fact, the pattern was compiled -into the internal format at the same time your entire program was. +(and perhaps recompilation) each time the regular expression is +encountered. The C</o> modifier locks in the regex the first time +it's used. This always happens in a constant regular expression, and +in fact, the pattern was compiled into the internal format at the same +time your entire program was. Use of C</o> is irrelevant unless variable interpolation is used in the pattern, and if so, the regex engine will neither know nor care @@ -367,8 +369,8 @@ A slight modification also removes C++ comments: =head2 Can I use Perl regular expressions to match balanced text? Although Perl regular expressions are more powerful than "mathematical" -regular expressions, because they feature conveniences like backreferences -(C<\1> and its ilk), they still aren't powerful enough -- with +regular expressions because they feature conveniences like backreferences +(C<\1> and its ilk), they still aren't powerful enough--with the possible exception of bizarre and experimental features in the development-track releases of Perl. You still need to use non-regex techniques to parse balanced text, such as the text enclosed between @@ -379,7 +381,7 @@ and possibly nested single chars, like C<`> and C<'>, C<{> and C<}>, or C<(> and C<)> can be found in http://www.perl.com/CPAN/authors/id/TOMC/scripts/pull_quotes.gz . -The C::Scan module from CPAN contains such subs for internal usage, +The C::Scan module from CPAN contains such subs for internal use, but they are undocumented. =head2 What does it mean that regexes are greedy? How can I get around it? @@ -402,7 +404,7 @@ expression engine to find a match as quickly as possible and pass control on to whatever is next in line, like you would if you were playing hot potato. -=head2 How do I process each word on each line? +=head2 How do I process each word on each line? Use the split function: @@ -415,7 +417,8 @@ Use the split function: Note that this isn't really a word in the English sense; it's just chunks of consecutive non-whitespace characters. -To work with only alphanumeric sequences, you might consider +To work with only alphanumeric sequences (including underscores), you +might consider while (<>) { foreach $word (m/(\w+)/g) { @@ -449,7 +452,8 @@ regular expression: print "$count $line"; } -If you want these output in a sorted order, see the section on Hashes. +If you want these output in a sorted order, see L<perlfaq4>: ``How do I +sort a hash (optionally by value instead of key)?''. =head2 How can I do approximate matching? @@ -486,7 +490,7 @@ approach, one which makes use of the new C<qr//> operator: =head2 Why don't word-boundary searches with C<\b> work for me? -Two common misconceptions are that C<\b> is a synonym for C<\s+>, and +Two common misconceptions are that C<\b> is a synonym for C<\s+> and that it's the edge between whitespace characters and non-whitespace characters. Neither is correct. C<\b> is the place between a C<\w> character and a C<\W> character (that is, C<\b> is the edge of a @@ -513,11 +517,11 @@ not "this" or "island". =head2 Why does using $&, $`, or $' slow my program down? -Because once Perl sees that you need one of these variables anywhere in -the program, it has to provide them on each and every pattern match. +Once Perl sees that you need one of these variables anywhere in +the program, it provides them on each and every pattern match. The same mechanism that handles these provides for the use of $1, $2, etc., so you pay the same price for each regex that contains capturing -parentheses. But if you never use $&, etc., in your script, then regexes +parentheses. If you never use $&, etc., in your script, then regexes I<without> capturing parentheses won't be penalized. So avoid $&, $', and $` if you can, but if you can't, once you've used them at all, use them at will because you've already paid the price. Remember that some @@ -526,11 +530,16 @@ variable is no longer "expensive" the way the other two are. =head2 What good is C<\G> in a regular expression? -The notation C<\G> is used in a match or substitution in conjunction the -C</g> modifier (and ignored if there's no C</g>) to anchor the regular -expression to the point just past where the last match occurred, i.e. the -pos() point. A failed match resets the position of C<\G> unless the -C</c> modifier is in effect. +The notation C<\G> is used in a match or substitution in conjunction with +the C</g> modifier to anchor the regular expression to the point just past +where the last match occurred, i.e. the pos() point. A failed match resets +the position of C<\G> unless the C</c> modifier is in effect. C<\G> can be +used in a match without the C</g> modifier; it acts the same (i.e. still +anchors at the pos() point) but of course only matches once and does not +update pos(), as non-C</g> expressions never do. C<\G> in an expression +applied to a target string that has never been matched against a C</g> +expression before or has had its pos() reset is functionally equivalent to +C<\A>, which matches at the beginning of the string. For example, suppose you had a line of text quoted in standard mail and Usenet notation, (that is, with leading C<< > >> characters), and @@ -583,7 +592,7 @@ Of course, that could have been written as } } -But then you lose the vertical alignment of the regular expressions. +but then you lose the vertical alignment of the regular expressions. =head2 Are Perl regexes DFAs or NFAs? Are they POSIX compliant? @@ -664,12 +673,12 @@ Well, if it's really a pattern, then just use chomp($pattern = <STDIN>); if ($line =~ /$pattern/) { } -Or, since you have no guarantee that your user entered +Alternatively, since you have no guarantee that your user entered a valid regular expression, trap the exception this way: if (eval { $line =~ /$pattern/ }) { } -But if all you really want to search for a string, not a pattern, +If all you really want to search for a string, not a pattern, then you should either use the index() function, which is made for string searching, or if you can't be disabused of using a pattern match on a non-pattern, then be sure to use C<\Q>...C<\E>, documented diff --git a/contrib/perl5/pod/perlfaq7.pod b/contrib/perl5/pod/perlfaq7.pod index 1ca7893f13db..0299c2d8934a 100644 --- a/contrib/perl5/pod/perlfaq7.pod +++ b/contrib/perl5/pod/perlfaq7.pod @@ -29,18 +29,18 @@ They are type specifiers, as detailed in L<perldata>: * for all types of that symbol name. In version 4 you used them like pointers, but in modern perls you can just use references. -A couple of others that you're likely to encounter that aren't -really type specifiers are: +There are couple of other symbols that you're likely to encounter that aren't +really type specifiers: <> are used for inputting a record from a filehandle. \ takes a reference to something. Note that <FILE> is I<neither> the type specifier for files nor the name of the handle. It is the C<< <> >> operator applied -to the handle FILE. It reads one line (well, record - see +to the handle FILE. It reads one line (well, record--see L<perlvar/$/>) from the handle FILE in scalar context, or I<all> lines in list context. When performing open, close, or any other operation -besides C<< <> >> on files, or even talking about the handle, do +besides C<< <> >> on files, or even when talking about the handle, do I<not> use the brackets. These are correct: C<eof(FH)>, C<seek(FH, 0, 2)> and "copying from STDIN to FILE". @@ -106,15 +106,15 @@ use my() on C<$^W>, only local(). =head2 What's an extension? -A way of calling compiled C code from Perl. Reading L<perlxstut> -is a good place to learn more about extensions. +An extension is a way of calling compiled C code from Perl. Reading +L<perlxstut> is a good place to learn more about extensions. =head2 Why do Perl operators have different precedence than C operators? Actually, they don't. All C operators that Perl copies have the same precedence in Perl as they do in C. The problem is with operators that C doesn't have, especially functions that give a list context to everything -on their right, eg print, chmod, exec, and so on. Such functions are +on their right, eg. print, chmod, exec, and so on. Such functions are called "list operators" and appear as such in the precedence table in L<perlop>. @@ -196,6 +196,10 @@ own module. Make sure to change the names appropriately. } our @EXPORT_OK; + # exported package globals go here + our $Var1; + our %Hashit; + # non-exported package globals go here our @more; our $stuff; @@ -254,7 +258,7 @@ is given no processes to signal): } This is not C<-w> clean, however. There is no C<-w> clean way to -detect taintedness - take this as a hint that you should untaint +detect taintedness--take this as a hint that you should untaint all possibly-tainted data. =head2 What's a closure? @@ -270,7 +274,7 @@ around when the subroutine was defined (deep binding). Closures make sense in any programming language where you can have the return value of a function be itself a function, as you can in Perl. Note that some languages provide anonymous functions but are not -capable of providing proper closures; the Python language, for +capable of providing proper closures: the Python language, for example. For more information on closures, check out any textbook on functional programming. Scheme is a language that not only supports but encourages closures. @@ -345,11 +349,14 @@ With the exception of regexes, you need to pass references to these objects. See L<perlsub/"Pass by Reference"> for this particular question, and L<perlref> for information on references. +See ``Passing Regexes'', below, for information on passing regular +expressions. + =over 4 =item Passing Variables and Functions -Regular variables and functions are quite easy: just pass in a +Regular variables and functions are quite easy to pass: just pass in a reference to an existing or anonymous variable or function: func( \$some_scalar ); @@ -366,7 +373,7 @@ reference to an existing or anonymous variable or function: =item Passing Filehandles To pass filehandles to subroutines, use the C<*FH> or C<\*FH> notations. -These are "typeglobs" - see L<perldata/"Typeglobs and Filehandles"> +These are "typeglobs"--see L<perldata/"Typeglobs and Filehandles"> and especially L<perlsub/"Pass by Reference"> for more information. Here's an excerpt: @@ -390,7 +397,7 @@ they'll still work properly under C<use strict 'refs'>. For example: If you're planning on generating new filehandles, you could do this: sub openit { - my $name = shift; + my $path = shift; local *FH; return open (FH, $path) ? *FH : undef; } @@ -456,8 +463,8 @@ To pass an object method into a subroutine, you can do this: } } -Or you can use a closure to bundle up the object and its method call -and arguments: +Or, you can use a closure to bundle up the object, its +method call, and arguments: my $whatnot = sub { $some_obj->obfuscate(@args) }; func($whatnot); @@ -491,8 +498,8 @@ Now prev_counter() and next_counter() share a private variable $counter that was initialized at compile time. To declare a file-private variable, you'll still use a my(), putting -it at the outer scope level at the top of the file. Assume this is in -file Pax.pm: +the declaration at the outer scope level at the top of the file. +Assume this is in file Pax.pm: package Pax; my $started = scalar(localtime(time())); @@ -512,14 +519,14 @@ See L<perlsub/"Persistent Private Variables"> for details. =head2 What's the difference between dynamic and lexical (static) scoping? Between local() and my()? -C<local($x)> saves away the old value of the global variable C<$x>, -and assigns a new value for the duration of the subroutine, I<which is +C<local($x)> saves away the old value of the global variable C<$x> +and assigns a new value for the duration of the subroutine I<which is visible in other functions called from that subroutine>. This is done at run-time, so is called dynamic scoping. local() always affects global variables, also called package variables or dynamic variables. C<my($x)> creates a new variable that is only visible in the current -subroutine. This is done at compile-time, so is called lexical or +subroutine. This is done at compile-time, so it is called lexical or static scoping. my() always affects private variables, also called lexical variables or (improperly) static(ly scoped) variables. @@ -553,8 +560,8 @@ In summary, local() doesn't make what you think of as private, local variables. It gives a global variable a temporary value. my() is what you're looking for if you want private variables. -See L<perlsub/"Private Variables via my()"> and L<perlsub/"Temporary -Values via local()"> for excruciating details. +See L<perlsub/"Private Variables via my()"> and +L<perlsub/"Temporary Values via local()"> for excruciating details. =head2 How can I access a dynamic variable while a similarly named lexical is in scope? @@ -630,8 +637,8 @@ see L<perltoot/"Overridden Methods">. =head2 What's the difference between calling a function as &foo and foo()? When you call a function as C<&foo>, you allow that function access to -your current @_ values, and you by-pass prototypes. That means that -the function doesn't get an empty @_, it gets yours! While not +your current @_ values, and you bypass prototypes. +The function doesn't get an empty @_--it gets yours! While not strictly speaking a bug (it's documented that way in L<perlsub>), it would be hard to consider this a feature in most cases. @@ -705,7 +712,7 @@ Sometimes you should change the positions of the constant and the variable. For example, let's say you wanted to test which of many answers you were given, but in a case-insensitive way that also allows abbreviations. You can use the following technique if the strings all start with -different characters, or if you want to arrange the matches so that +different characters or if you want to arrange the matches so that one takes precedence over another, as C<"SEND"> has precedence over C<"STOP"> here: @@ -763,15 +770,16 @@ C<__WARN__> like this: Some possible reasons: your inheritance is getting confused, you've misspelled the method name, or the object is of the wrong type. Check -out L<perltoot> for details on these. You may also use C<print -ref($object)> to find out the class C<$object> was blessed into. +out L<perltoot> for details about any of the above cases. You may +also use C<print ref($object)> to find out the class C<$object> was +blessed into. Another possible reason for problems is because you've used the indirect object syntax (eg, C<find Guru "Samy">) on a class name before Perl has seen that such a package exists. It's wisest to make sure your packages are all defined before you start using them, which will be taken care of if you use the C<use> statement instead of -C<require>. If not, make sure to use arrow notation (eg, +C<require>. If not, make sure to use arrow notation (eg., C<< Guru->find("Samy") >>) instead. Object notation is explained in L<perlobj>. @@ -785,7 +793,7 @@ out what the currently compiled package is: my $packname = __PACKAGE__; -But if you're a method and you want to print an error message +But, if you're a method and you want to print an error message that includes the kind of object you were called on (which is not necessarily the same as the one in which you were compiled): @@ -857,19 +865,19 @@ of a variable. This works I<sometimes>, but it is a very bad idea for two reasons. -The first reason is that they I<only work on global variables>. -That means above that if $fred is a lexical variable created with my(), -that the code won't work at all: you'll accidentally access the global -and skip right over the private lexical altogether. Global variables -are bad because they can easily collide accidentally and in general make -for non-scalable and confusing code. +The first reason is that this technique I<only works on global +variables>. That means that if $fred is a lexical variable created +with my() in the above example, the code wouldn't work at all: you'd +accidentally access the global and skip right over the private lexical +altogether. Global variables are bad because they can easily collide +accidentally and in general make for non-scalable and confusing code. Symbolic references are forbidden under the C<use strict> pragma. They are not true references and consequently are not reference counted or garbage collected. The other reason why using a variable to hold the name of another -variable a bad idea is that the question often stems from a lack of +variable is a bad idea is that the question often stems from a lack of understanding of Perl data structures, particularly hashes. By using symbolic references, you are just using the package's symbol-table hash (like C<%main::>) instead of a user-defined hash. The solution is to @@ -890,7 +898,7 @@ own variables: $str = 'this has a $fred and $barney in it'; $str =~ s/(\$\w+)/$1/eeg; # need double eval -Instead, it would be better to keep a hash around like %USER_VARS and have +it would be better to keep a hash around like %USER_VARS and have variable references actually refer to entries in that hash: $str =~ s/\$(\w+)/$USER_VARS{$1}/g; # no /e here at all @@ -902,11 +910,11 @@ make it less confusing, like bracketed percent symbols, etc. $str = 'this has a %fred% and %barney% in it'; $str =~ s/%(\w+)%/$USER_VARS{$1}/g; # no /e here at all -Another reason that folks sometimes think they want a variable to contain -the name of a variable is because they don't know how to build proper -data structures using hashes. For example, let's say they wanted two -hashes in their program: %fred and %barney, and to use another scalar -variable to refer to those by name. +Another reason that folks sometimes think they want a variable to +contain the name of a variable is because they don't know how to build +proper data structures using hashes. For example, let's say they +wanted two hashes in their program: %fred and %barney, and that they +wanted to use another scalar variable to refer to those by name. $name = "fred"; $$name{WIFE} = "wilma"; # set %fred @@ -942,9 +950,9 @@ but the real code in the closure actually was compiled only once. So, sometimes you might want to use symbolic references to directly manipulate the symbol table. This doesn't matter for formats, handles, and -subroutines, because they are always global -- you can't use my() on them. -But for scalars, arrays, and hashes -- and usually for subroutines -- -you probably want to use hard references only. +subroutines, because they are always global--you can't use my() on them. +For scalars, arrays, and hashes, though--and usually for subroutines-- +you probably only want to use hard references. =head1 AUTHOR AND COPYRIGHT @@ -963,3 +971,4 @@ 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. + diff --git a/contrib/perl5/pod/perlfaq8.pod b/contrib/perl5/pod/perlfaq8.pod index ed22ba0c59fa..1df3b6ac0ab1 100644 --- a/contrib/perl5/pod/perlfaq8.pod +++ b/contrib/perl5/pod/perlfaq8.pod @@ -5,7 +5,7 @@ perlfaq8 - System Interaction ($Revision: 1.39 $, $Date: 1999/05/23 18:37:57 $) =head1 DESCRIPTION This section of the Perl FAQ covers questions involving operating -system interaction. This involves interprocess communication (IPC), +system interaction. Topics include interprocess communication (IPC), control over the user-interface (keyboard, screen and pointing devices), and most anything else not related to data manipulation. @@ -95,10 +95,10 @@ It even includes limited support for Windows. $key = ReadKey(0); ReadMode('normal'); -However, that requires that you have a working C compiler and can use it -to build and install a CPAN module. Here's a solution using -the standard POSIX module, which is already on your systems (assuming -your system supports POSIX). +However, using the code requires that you have a working C compiler +and can use it to build and install a CPAN module. Here's a solution +using the standard POSIX module, which is already on your systems +(assuming your system supports POSIX). use HotKey; $key = readkey(); @@ -214,10 +214,10 @@ illustrative: (This question has nothing to do with the web. See a different FAQ for that.) -There's an example of this in L<perlfunc/crypt>). First, you put -the terminal into "no echo" mode, then just read the password -normally. You may do this with an old-style ioctl() function, POSIX -terminal control (see L<POSIX>, and Chapter 7 of the Camel), or a call +There's an example of this in L<perlfunc/crypt>). First, you put the +terminal into "no echo" mode, then just read the password normally. +You may do this with an old-style ioctl() function, POSIX terminal +control (see L<POSIX> or its documentation the Camel Book), or a call to the B<stty> program, with varying degrees of portability. You can also do this for most systems using the Term::ReadKey module @@ -232,16 +232,16 @@ from CPAN, which is easier to use and in theory more portable. This depends on which operating system your program is running on. In the case of Unix, the serial ports will be accessible through files in -/dev; on other systems, the devices names will doubtless differ. +/dev; on other systems, device names will doubtless differ. Several problem areas common to all device interaction are the -following +following: =over 4 =item lockfiles Your system may use lockfiles to control multiple access. Make sure -you follow the correct protocol. Unpredictable behaviour can result +you follow the correct protocol. Unpredictable behavior can result from multiple processes reading from one device. =item open mode @@ -264,7 +264,7 @@ give the numeric values you want directly, using octal ("\015"), hex print DEV "atv1\012"; # wrong, for some devices print DEV "atv1\015"; # right, for some devices -Even though with normal text files, a "\n" will do the trick, there is +Even though with normal text files a "\n" will do the trick, there is still no unified scheme for terminating a line that is portable between Unix, DOS/Win, and Macintosh, except to terminate I<ALL> line ends with "\015\012", and strip what you don't need from the output. @@ -276,7 +276,8 @@ next. If you expect characters to get to your device when you print() them, you'll want to autoflush that filehandle. You can use select() and the C<$|> variable to control autoflushing (see L<perlvar/$|> -and L<perlfunc/select>): +and L<perlfunc/select>, or L<perlfaq5>, ``How do I flush/unbuffer an +output filehandle? Why must I do this?''): $oldh = select(DEV); $| = 1; @@ -320,7 +321,7 @@ go bump in the night, finally came up with this: # been opened on a pipe... system("/bin/stty $stty"); $_ = <MODEM_IN>; - chop; + chomp; if ( !m/^Connected/ ) { print STDERR "$0: cu printed `$_' instead of `Connected'\n"; } @@ -331,7 +332,7 @@ go bump in the night, finally came up with this: You spend lots and lots of money on dedicated hardware, but this is bound to get you talked about. -Seriously, you can't if they are Unix password files - the Unix +Seriously, you can't if they are Unix password files--the Unix password system employs one-way encryption. It's more like hashing than encryption. The best you can check is whether something else hashes to the same string. You can't turn a hash back into the original string. @@ -388,7 +389,8 @@ Zombies are not an issue with C<system("prog &")>. You don't actually "trap" a control character. Instead, that character generates a signal which is sent to your terminal's currently foregrounded process group, which you then trap in your process. -Signals are documented in L<perlipc/"Signals"> and chapter 6 of the Camel. +Signals are documented in L<perlipc/"Signals"> and the +section on ``Signals'' in the Camel. Be warned that very few C libraries are re-entrant. Therefore, if you attempt to print() in a handler that got invoked during another stdio @@ -397,7 +399,7 @@ inconsistent state, and your program will dump core. You can sometimes avoid this by using syswrite() instead of print(). Unless you're exceedingly careful, the only safe things to do inside a -signal handler are: set a variable and exit. And in the first case, +signal handler are (1) set a variable and (2) exit. In the first case, you should only set a variable in such a way that malloc() is not called (eg, by setting a variable that already has a value). @@ -413,15 +415,16 @@ However, because syscalls restart by default, you'll find that if you're in a "slow" call, such as <FH>, read(), connect(), or wait(), that the only way to terminate them is by "longjumping" out; that is, by raising an exception. See the time-out handler for a -blocking flock() in L<perlipc/"Signals"> or chapter 6 of the Camel. +blocking flock() in L<perlipc/"Signals"> or the section on ``Signals'' +in the Camel book. =head2 How do I modify the shadow password file on a Unix system? -If perl was installed correctly, and your shadow library was written +If perl was installed correctly and your shadow library was written properly, the getpw*() functions described in L<perlfunc> should in theory provide (read-only) access to entries in the shadow password file. To change the file, make a new shadow password file (the format -varies from system to system - see L<passwd(5)> for specifics) and use +varies from system to system--see L<passwd(5)> for specifics) and use pwd_mkdb(8) to install it (see L<pwd_mkdb(8)> for more details). =head2 How do I set the time and date? @@ -443,9 +446,8 @@ probably get away with setting an environment variable: If you want finer granularity than the 1 second that the sleep() function provides, the easiest way is to use the select() function as -documented in L<perlfunc/"select">. If your system has itimers and -syscall() support, you can check out the old example in -http://www.perl.com/CPAN/doc/misc/ancient/tutorial/eg/itimers.pl . +documented in L<perlfunc/"select">. Try the Time::HiRes and +the BSD::Itimer modules (available from CPAN). =head2 How can I measure time under a second? @@ -495,15 +497,16 @@ managed to finish its output without filling up the disk: close(STDOUT) || die "stdout close failed: $!"; } -The END block isn't called when untrapped signals kill the program, though, so if -you use END blocks you should also use +The END block isn't called when untrapped signals kill the program, +though, so if you use END blocks you should also use use sigtrap qw(die normal-signals); Perl's exception-handling mechanism is its eval() operator. You can use eval() as setjmp and die() as longjmp. For details of this, see the section on signals, especially the time-out handler for a blocking -flock() in L<perlipc/"Signals"> and chapter 6 of the Camel. +flock() in L<perlipc/"Signals"> or the section on ``Signals'' in +the Camel Book. If exception handling is all you're interested in, try the exceptions.pl library (part of the standard perl distribution). @@ -511,7 +514,7 @@ exceptions.pl library (part of the standard perl distribution). If you want the atexit() syntax (and an rmexit() as well), try the AtExit module available from CPAN. -=head2 Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean? +=head2 Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean? Some Sys-V based systems, notably Solaris 2.X, redefined some of the standard socket constants. Since these were constant across all @@ -523,14 +526,14 @@ values are different. Go figure. =head2 How can I call my system's unique C functions from Perl? -In most cases, you write an external module to do it - see the answer +In most cases, you write an external module to do it--see the answer to "Where can I learn about linking C with Perl? [h2xs, xsubpp]". However, if the function is a system call, and your system supports syscall(), you can use the syscall function (documented in L<perlfunc>). Remember to check the modules that came with your distribution, and -CPAN as well - someone may already have written a module to do it. +CPAN as well--someone may already have written a module to do it. =head2 Where do I get the include files to do ioctl() or syscall()? @@ -568,9 +571,9 @@ scripts inherently insecure. Perl gives you a number of options The IPC::Open2 module (part of the standard perl distribution) is an easy-to-use approach that internally uses pipe(), fork(), and exec() to do the job. Make sure you read the deadlock warnings in its documentation, -though (see L<IPC::Open2>). See L<perlipc/"Bidirectional Communication -with Another Process"> and L<perlipc/"Bidirectional Communication with -Yourself"> +though (see L<IPC::Open2>). See +L<perlipc/"Bidirectional Communication with Another Process"> and +L<perlipc/"Bidirectional Communication with Yourself"> You may also use the IPC::Open3 module (part of the standard perl distribution), but be warned that it has a different order of @@ -596,7 +599,7 @@ There are three basic ways of running external commands: open (PIPE, "cmd |"); # using open() With system(), both STDOUT and STDERR will go the same place as the -script's versions of these, unless the command redirects them. +script's STDOUT and STDERR, unless the system() command redirects them. Backticks and open() read B<only> the STDOUT of your command. With any of these, you can change file descriptors before the call: @@ -689,7 +692,7 @@ In some cases, even this won't work. If the second argument to a piped open() contains shell metacharacters, perl fork()s, then exec()s a shell to decode the metacharacters and eventually run the desired program. Now when you call wait(), you only learn whether or not the -I<shell> could be successfully started. Best to avoid shell +I<shell> could be successfully started...it's best to avoid shell metacharacters. On systems that follow the spawn() paradigm, open() I<might> do what @@ -716,17 +719,17 @@ Consider this line: `cat /etc/termcap`; You haven't assigned the output anywhere, so it just wastes memory -(for a little while). Plus you forgot to check C<$?> to see whether -the program even ran correctly. Even if you wrote +(for a little while). You forgot to check C<$?> to see whether +the program even ran correctly, too. Even if you wrote print `cat /etc/termcap`; -In most cases, this could and probably should be written as +this code could and probably should be written as system("cat /etc/termcap") == 0 or die "cat program failed!"; -Which will get the output quickly (as it is generated, instead of only +which will get the output quickly (as it is generated, instead of only at the end) and also check the return value. system() also provides direct control over whether shell wildcard @@ -763,7 +766,7 @@ and fix it for you. =head2 Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)? -Because some stdio's set error and eof flags that need clearing. The +Some stdio's set error and eof flags that need clearing. The POSIX module defines clearerr() that you can use. That is the technically correct way to do it. Here are some less reliable workarounds: @@ -856,9 +859,9 @@ state there, as in: =item Unix -In the strictest sense, it can't be done -- the script executes as a +In the strictest sense, it can't be done--the script executes as a different process from the shell it was started from. Changes to a -process are not reflected in its parent, only in its own children +process are not reflected in its parent--only in any children created after the change. There is shell magic that may allow you to fake it by eval()ing the script's output in your shell; check out the comp.unix.questions FAQ for details. @@ -868,7 +871,7 @@ comp.unix.questions FAQ for details. =head2 How do I close a process's filehandle without waiting for it to complete? Assuming your system supports such things, just send an appropriate signal -to the process (see L<perlfunc/"kill">. It's common to first send a TERM +to the process (see L<perlfunc/"kill">). It's common to first send a TERM signal, wait a little bit, and then send a KILL signal to finish it off. =head2 How do I fork a daemon process? @@ -906,10 +909,6 @@ Background yourself like this: The Proc::Daemon module, available from CPAN, provides a function to perform these actions for you. -=head2 How do I make my program run with sh and csh? - -See the F<eg/nih> script (part of the perl source distribution). - =head2 How do I find out if I'm running interactively or not? Good question. Sometimes C<-t STDIN> and C<-t STDOUT> can give clues, @@ -935,9 +934,9 @@ the current process group of your controlling terminal as follows: =head2 How do I timeout a slow event? Use the alarm() function, probably in conjunction with a signal -handler, as documented in L<perlipc/"Signals"> and chapter 6 of the -Camel. You may instead use the more flexible Sys::AlarmCall module -available from CPAN. +handler, as documented in L<perlipc/"Signals"> and the section on +``Signals'' in the Camel. You may instead use the more flexible +Sys::AlarmCall module available from CPAN. =head2 How do I set CPU limits? @@ -976,9 +975,6 @@ sysopen(): sysopen(FH, "/tmp/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644) or die "can't open /tmp/somefile: $!": - - - =head2 How do I install a module from CPAN? The easiest way is to have a module also named CPAN do it for you. @@ -1015,26 +1011,27 @@ just need to replace step 3 (B<make>) with B<make perl> and you will get a new F<perl> binary with your extension linked in. See L<ExtUtils::MakeMaker> for more details on building extensions. -See also the next question. +See also the next question, ``What's the difference between require +and use?''. =head2 What's the difference between require and use? Perl offers several different ways to include code from one file into another. Here are the deltas between the various inclusion constructs: - 1) do $file is like eval `cat $file`, except the former: + 1) do $file is like eval `cat $file`, except the former 1.1: searches @INC and updates %INC. 1.2: bequeaths an *unrelated* lexical scope on the eval'ed code. - 2) require $file is like do $file, except the former: + 2) require $file is like do $file, except the former 2.1: checks for redundant loading, skipping already loaded files. 2.2: raises an exception on failure to find, compile, or execute $file. - 3) require Module is like require "Module.pm", except the former: + 3) require Module is like require "Module.pm", except the former 3.1: translates each "::" into your system's directory separator. 3.2: primes the parser to disambiguate class Module as an indirect object. - 4) use Module is like require Module, except the former: + 4) use Module is like require Module, except the former 4.1: loads the module at compile time, not run-time. 4.2: imports symbols and semantics from that package to the current one. @@ -1052,7 +1049,7 @@ scripts that use the modules/libraries (see L<perlrun>) or say use lib '/u/mydir/perl'; -This is almost the same as: +This is almost the same as BEGIN { unshift(@INC, '/u/mydir/perl'); diff --git a/contrib/perl5/pod/perlfaq9.pod b/contrib/perl5/pod/perlfaq9.pod index 16a803c997c2..96763802c527 100644 --- a/contrib/perl5/pod/perlfaq9.pod +++ b/contrib/perl5/pod/perlfaq9.pod @@ -7,7 +7,7 @@ perlfaq9 - Networking ($Revision: 1.26 $, $Date: 1999/05/23 16:08:30 $) This section deals with questions related to networking, the internet, and a few on the web. -=head2 My CGI script runs from the command line but not the browser. (500 Server Error) +=head2 My CGI script runs from the command line but not the browser. (500 Server Error) If you can demonstrate that you've read the following FAQs and that your problem isn't something simple that can be easily answered, you'll @@ -84,8 +84,8 @@ attempts to do a little simple formatting of the resulting plain text. Many folks attempt a simple-minded regular expression approach, like C<< s/<.*?>//g >>, but that fails in many cases because the tags may continue over line breaks, they may contain quoted angle-brackets, -or HTML comment may be present. Plus folks forget to convert -entities, like C<<> for example. +or HTML comment may be present. Plus, folks forget to convert +entities--like C<<> for example. Here's one "simple-minded" approach, that works for most files: @@ -209,27 +209,35 @@ the content appropriately. =head2 How do I decode or create those %-encodings on the web? -Here's an example of decoding: - $string = "http://altavista.digital.com/cgi-bin/query?pg=q&what=news&fmt=.&q=%2Bcgi-bin+%2Bperl.exe"; - $string =~ s/%([a-fA-F0-9]{2})/chr(hex($1))/ge; +If you are writing a CGI script, you should be using the CGI.pm module +that comes with perl, or some other equivalent module. The CGI module +automatically decodes queries for you, and provides an escape() +function to handle encoding. -Encoding is a bit harder, because you can't just blindly change -all the non-alphanumunder character (C<\W>) into their hex escapes. -It's important that characters with special meaning like C</> and C<?> -I<not> be translated. Probably the easiest way to get this right is -to avoid reinventing the wheel and just use the URI::Escape module, -available from CPAN. + +The best source of detailed information on URI encoding is RFC 2396. +Basically, the following substitutions do it: + + s/([^\w()'*~!.-])/sprintf '%%%02x', $1/eg; # encode + + s/%([A-Fa-f\d]{2})/chr hex $1/eg; # decode + +However, you should only apply them to individual URI components, not +the entire URI, otherwise you'll lose information and generally mess +things up. If that didn't explain it, don't worry. Just go read +section 2 of the RFC, it's probably the best explanation there is. + +RFC 2396 also contains a lot of other useful information, including a +regexp for breaking any arbitrary URI into components (Appendix B). =head2 How do I redirect to another page? -Instead of sending back a C<Content-Type> as the headers of your -reply, send back a C<Location:> header. Officially this should be a -C<URI:> header, so the CGI.pm module (available from CPAN) sends back -both: +According to RFC 2616, "Hypertext Transfer Protocol -- HTTP/1.1", the +preferred method is to send a C<Location:> header instead of a +C<Content-Type:> header: Location: http://www.domain.com/newpage - URI: http://www.domain.com/newpage Note that relative URLs in these headers can cause strange effects because of "optimizations" that servers do. @@ -247,12 +255,12 @@ in the header. EOF -To be correct to the spec, each of those virtual newlines should really be -physical C<"\015\012"> sequences by the time you hit the client browser. -Except for NPH scripts, though, that local newline should get translated -by your server into standard form, so you shouldn't have a problem -here, even if you are stuck on MacOS. Everybody else probably won't -even notice. +To be correct to the spec, each of those virtual newlines should +really be physical C<"\015\012"> sequences by the time your message is +received by the client browser. Except for NPH scripts, though, that +local newline should get translated by your server into standard form, +so you shouldn't have a problem here, even if you are stuck on MacOS. +Everybody else probably won't even notice. =head2 How do I put a password on my web pages? @@ -275,9 +283,9 @@ DBI compatible driver. HTTPD::UserAdmin supports files used by the =head2 How do I make sure users can't enter values into a form that cause my CGI script to do bad things? Read the CGI security FAQ, at -http://www-genome.wi.mit.edu/WWW/faqs/www-security-faq.html, and the +http://www-genome.wi.mit.edu/WWW/faqs/www-security-faq.html , and the Perl/CGI FAQ at -http://www.perl.com/CPAN/doc/FAQs/cgi/perl-cgi-faq.html. +http://www.perl.com/CPAN/doc/FAQs/cgi/perl-cgi-faq.html . In brief: use tainting (see L<perlsec>), which makes sure that data from outside your script (eg, CGI parameters) are never used in @@ -288,7 +296,7 @@ command and arguments as a list, which prevents shell globbing. =head2 How do I parse a mail header? For a quick-and-dirty solution, try this solution derived -from page 222 of the 2nd edition of "Programming Perl": +from L<perlfunc/split>: $/ = ''; $header = <MSG>; @@ -344,10 +352,10 @@ deliverable which are compliant. Many are tempted to try to eliminate many frequently-invalid mail addresses with a simple regex, such as -C</^[\w.-]+\@([\w.-]\.)+\w+$/>. It's a very bad idea. However, +C</^[\w.-]+\@(?:[\w-]+\.)+\w+$/>. It's a very bad idea. However, this also throws out many valid ones, and says nothing about -potential deliverability, so is not suggested. Instead, see -http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/ckaddr.gz , +potential deliverability, so it is not suggested. Instead, see +http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/ckaddr.gz, which actually checks against the full RFC spec (except for nested comments), looks for addresses you may not wish to accept mail to (say, Bill Clinton or your postmaster), and then makes sure that the @@ -380,13 +388,18 @@ with the characters reversed, one added or subtracted to each digit, etc. =head2 How do I decode a MIME/BASE64 string? -The MIME-tools package (available from CPAN) handles this and a lot -more. Decoding BASE64 becomes as simple as: +The MIME-Base64 package (available from CPAN) handles this as well as +the MIME/QP encoding. Decoding BASE64 becomes as simple as: - use MIME::base64; + use MIME::Base64; $decoded = decode_base64($encoded); -A more direct approach is to use the unpack() function's "u" +The MIME-Tools package (available from CPAN) supports extraction with +decoding of BASE64 encoded attachments and content directly from email +messages. + +If the string to decode is short (less than 84 bytes long) +a more direct approach is to use the unpack() function's "u" format after minor transliterations: tr#A-Za-z0-9+/##cd; # remove non-base64 chars @@ -396,7 +409,7 @@ format after minor transliterations: =head2 How do I return the user's mail address? -On systems that support getpwuid, the $< variable and the +On systems that support getpwuid, the $< variable, and the Sys::Hostname module (which is part of the standard perl distribution), you can probably try using something like this: @@ -460,11 +473,45 @@ Mail::Mailer, but less reliable. Avoid raw SMTP commands. There are many reasons to use a mail transport agent like sendmail. These include queueing, MX records, and security. +=head2 How do I use MIME to make an attachment to a mail message? + +This answer is extracted directly from the MIME::Lite documentation. +Create a multipart message (i.e., one with attachments). + + use MIME::Lite; + + ### Create a new multipart message: + $msg = MIME::Lite->new( + From =>'me@myhost.com', + To =>'you@yourhost.com', + Cc =>'some@other.com, some@more.com', + Subject =>'A message with 2 parts...', + Type =>'multipart/mixed' + ); + + ### Add parts (each "attach" has same arguments as "new"): + $msg->attach(Type =>'TEXT', + Data =>"Here's the GIF file you wanted" + ); + $msg->attach(Type =>'image/gif', + Path =>'aaa000123.gif', + Filename =>'logo.gif' + ); + + $text = $msg->as_string; + +MIME::Lite also includes a method for sending these things. + + $msg->send; + +This defaults to using L<sendmail(1)> but can be customized to use +SMTP via L<Net::SMTP>. + =head2 How do I read mail? While you could use the Mail::Folder module from CPAN (part of the MailFolder package) or the Mail::Internet module from CPAN (also part -of the MailTools package), often a module is overkill, though. Here's a +of the MailTools package), often a module is overkill. Here's a mail sorter. #!/usr/bin/perl @@ -519,7 +566,7 @@ systems.) =head2 How do I fetch a news article or the active newsgroups? Use the Net::NNTP or News::NNTPClient modules, both available from CPAN. -This can make tasks like fetching the newsgroup list as simple as: +This can make tasks like fetching the newsgroup list as simple as perl -MNews::NNTPClient -e 'print News::NNTPClient->new->list("newsgroups")' @@ -531,7 +578,7 @@ available from CPAN) is more complex but can put as well as fetch. =head2 How can I do RPC in Perl? -A DCE::RPC module is being developed (but is not yet available), and +A DCE::RPC module is being developed (but is not yet available) and will be released as part of the DCE-Perl package (available from CPAN). The rpcgen suite, available from CPAN/authors/id/JAKE/, is an RPC stub generator and includes an RPC::ONC module. diff --git a/contrib/perl5/pod/perlfilter.pod b/contrib/perl5/pod/perlfilter.pod index c3c83153adfa..4327809ec95a 100644 --- a/contrib/perl5/pod/perlfilter.pod +++ b/contrib/perl5/pod/perlfilter.pod @@ -2,7 +2,6 @@ perlfilter - Source Filters - =head1 DESCRIPTION This article is about a little-known feature of Perl called diff --git a/contrib/perl5/pod/perlfork.pod b/contrib/perl5/pod/perlfork.pod index d930e9396e87..dc0a82bfd642 100644 --- a/contrib/perl5/pod/perlfork.pod +++ b/contrib/perl5/pod/perlfork.pod @@ -1,9 +1,14 @@ =head1 NAME -perlfork - Perl's fork() emulation +perlfork - Perl's fork() emulation (EXPERIMENTAL, subject to change) =head1 SYNOPSIS + WARNING: As of the 5.6.1 release, the fork() emulation continues + to be an experimental feature. Use in production applications is + not recommended. See the "BUGS" and "CAVEATS AND LIMITATIONS" + sections below. + 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. @@ -11,7 +16,7 @@ call is available, Perl's fork() simply calls it. 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 the level of the Perl program, there are certain +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. @@ -51,7 +56,7 @@ pseudo-processes are launched after others have been wait()-ed on. =item %ENV -Each pseudo-process maintains its own virtual enviroment. Modifications +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. @@ -274,6 +279,17 @@ are expected to be fixed for thread-safety. =item * +Perl's regular expression engine currently does not play very nicely +with the fork() emulation. There are known race conditions arising +from the regular expression engine modifying state carried in the opcode +tree at run time (the fork() emulation relies on the opcode tree being +immutable). This typically happens when the regex contains paren groups +or variables interpolated within it that force a run time recompilation +of the regex. Due to this major bug, the fork() emulation is not +recommended for use in production applications at this time. + +=item * + Having pseudo-process IDs be negative integers breaks down for the integer C<-1> because the wait() and waitpid() functions treat this number as being special. The tacit assumption in the current implementation is that diff --git a/contrib/perl5/pod/perlfunc.pod b/contrib/perl5/pod/perlfunc.pod index 5396fd19450e..e959abc3ffec 100644 --- a/contrib/perl5/pod/perlfunc.pod +++ b/contrib/perl5/pod/perlfunc.pod @@ -91,7 +91,7 @@ functions, like some keywords and named operators) arranged by category. Some functions appear in more than one place. -=over +=over 4 =item Functions for SCALARs or strings @@ -146,11 +146,11 @@ C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray> =item Keywords related to scoping -C<caller>, C<import>, C<local>, C<my>, C<package>, C<use> +C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<use> =item Miscellaneous functions -C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<reset>, +C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>, C<reset>, C<scalar>, C<undef>, C<wantarray> =item Functions for processes and process groups @@ -200,8 +200,8 @@ C<gmtime>, C<localtime>, C<time>, C<times> =item Functions new in perl5 C<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>, -C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<prototype>, C<qx>, -C<qw>, C<readline>, C<readpipe>, C<ref>, C<sub*>, C<sysopen>, C<tie>, +C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<our>, C<prototype>, +C<qx>, C<qw>, C<readline>, C<readpipe>, C<ref>, C<sub*>, C<sysopen>, C<tie>, C<tied>, C<uc>, C<ucfirst>, C<untie>, C<use> * - C<sub> was a keyword in perl4, but in perl5 it is an @@ -274,8 +274,8 @@ X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C> -O File is owned by real uid. -e File exists. - -z File has zero size. - -s File has nonzero size (returns size). + -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. @@ -300,7 +300,7 @@ X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C> Example: while (<>) { - chop; + chomp; next unless -f $_; # ignore specials #... } @@ -488,7 +488,7 @@ files, but it can be disastrous for binary files. Another consequence of using binmode() (on some systems) is that special end-of-file markers will be seen as part of the data stream. For systems from the Microsoft family this means that if your binary -data contains C<\cZ>, the I/O subsystem will ragard it as the end of +data contains C<\cZ>, the I/O subsystem will regard it as the end of the file, unless you use binmode(). binmode() is not only important for readline() and print() operations, @@ -539,9 +539,10 @@ Here $subroutine may be C<(eval)> if the frame is not a subroutine call, but an C<eval>. In such a case additional elements $evaltext and C<$is_require> are set: C<$is_require> is true if the frame is created by a C<require> or C<use> statement, $evaltext contains the text of the -C<eval EXPR> statement. In particular, for a C<eval BLOCK> statement, +C<eval EXPR> statement. In particular, for an C<eval BLOCK> statement, $filename is C<(eval)>, but $evaltext is undefined. (Note also that each C<use> statement creates a C<require> frame inside an C<eval EXPR>) +frame. C<$hasargs> is true if a new instance of C<@_> was set up for the frame. C<$hints> and C<$bitmask> contain pragmatic hints that the caller was compiled with. The C<$hints> and C<$bitmask> values are subject to change between versions of Perl, and are not meant for external use. @@ -611,6 +612,8 @@ If VARIABLE is omitted, it chomps C<$_>. Example: # ... } +If VARIABLE is a hash, it chomps the hash's values, but not its keys. + You can actually chomp anything that's an lvalue, including an assignment: chomp($cwd = `pwd`); @@ -626,21 +629,11 @@ characters removed is returned. =item chop Chops off the last character of a string and returns the character -chopped. It's used primarily to remove the newline from the end of an -input record, but is much more efficient than C<s/\n//> because it neither +chopped. It is much more efficient than C<s/.$//s> because it neither scans nor copies the string. If VARIABLE is omitted, chops C<$_>. -Example: +If VARIABLE is a hash, it chops the hash's values, but not its keys. - while (<>) { - chop; # avoid \n on last field - @array = split(/:/); - #... - } - -You can actually chop anything that's an lvalue, including an assignment: - - chop($cwd = `pwd`); - chop($answer = <STDIN>); +You can actually chop anything that's an lvalue, including an assignment. If you chop a list, each element is chopped. Only the value of the last C<chop> is returned. @@ -791,6 +784,8 @@ to check the condition at the top of the loop. =item cos EXPR +=item cos + Returns the cosine of EXPR (expressed in radians). If EXPR is omitted, takes cosine of C<$_>. @@ -913,7 +908,10 @@ element to return happens to be C<undef>. You may also use C<defined(&func)> to check whether subroutine C<&func> has ever been defined. The return value is unaffected by any forward -declarations of C<&foo>. +declarations of C<&foo>. Note that a subroutine which is not defined +may still be callable: its package may have an C<AUTOLOAD> method that +makes it spring into existence the first time that it is called -- see +L<perlsub>. Use of C<defined> on aggregates (hashes and arrays) is deprecated. It used to report whether memory for that aggregate has ever been @@ -1055,7 +1053,7 @@ If C<$@> is empty then the string C<"Died"> is used. die() can also be called with a reference argument. If this happens to be trapped within an eval(), $@ contains the reference. This behavior permits a more elaborate exception handling implementation using objects that -maintain arbitary state about the nature of the exception. Such a scheme +maintain arbitrary state about the nature of the exception. Such a scheme is sometimes preferable to matching particular string values of $@ using regular expressions. Here's an example: @@ -1183,7 +1181,7 @@ make your program I<appear> to run faster. When called in list context, returns a 2-element list consisting of the key and value for the next element of a hash, so that you can iterate over -it. When called in scalar context, returns the key for only the "next" +it. When called in scalar context, returns only the key for the next element in the hash. Entries are returned in an apparently random order. The actual random @@ -1198,7 +1196,14 @@ again. There is a single iterator for each hash, shared by all C<each>, C<keys>, and C<values> function calls in the program; it can be reset by reading all the elements from the hash, or by evaluating C<keys HASH> or C<values HASH>. If you add or delete elements of a hash while you're -iterating over it, you may get entries skipped or duplicated, so don't. +iterating over it, you may get entries skipped or duplicated, so +don't. Exception: It is always safe to delete the item most recently +returned by C<each()>, which means that the following code will work: + + while (($key, $value) = each %hash) { + print $key, "\n"; + delete $hash{$key}; # This is safe + } The following prints out your environment like the printenv(1) program, only in a different order: @@ -1264,11 +1269,11 @@ there was an error. In the first form, the return value of EXPR is parsed and executed as if it were a little Perl program. The value of the expression (which is itself determined within scalar context) is first parsed, and if there weren't any -errors, executed in the context of the current Perl program, so that any -variable settings or subroutine and format definitions remain afterwards. -Note that the value is parsed every time the eval executes. If EXPR is -omitted, evaluates C<$_>. This form is typically used to delay parsing -and subsequent execution of the text of EXPR until run time. +errors, executed in the lexical context of the current Perl program, so +that any variable settings or subroutine and format definitions remain +afterwards. Note that the value is parsed every time the eval executes. +If EXPR is omitted, evaluates C<$_>. This form is typically used to +delay parsing and subsequent execution of the text of EXPR until run time. In the second form, the code within the BLOCK is parsed only once--at the same time the code surrounding the eval itself was parsed--and executed @@ -1462,7 +1467,10 @@ it exists, but the reverse doesn't necessarily hold true. 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. +does not count as declaring it. Note that a subroutine which does not +exist may still be callable: its package may have an C<AUTOLOAD> +method that makes it spring into existence the first time that it is +called -- see L<perlsub>. print "Exists\n" if exists &subroutine; print "Defined\n" if defined &subroutine; @@ -1863,7 +1871,7 @@ 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 is tainted (see +cannot be trusted and therefore the $gcos is tainted (see L<perlsec>). The $passwd and $shell, user's encrypted password and login shell, are also tainted, because of the same reason. @@ -1896,8 +1904,10 @@ by using the C<Config> module and the values C<d_pwquota>, C<d_pwage>, C<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>. Shadow password files are only supported 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. Those that -incorrectly implement a separate library call are not supported. +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 which implement a proprietary shadow password +facility are unlikely to be supported. The $members value returned by I<getgr*()> is a space separated list of the login names of the members of the group. @@ -1983,7 +1993,7 @@ itself, in the range C<0..11> with 0 indicating January and 11 indicating December. $year is the number of years since 1900. That is, $year is C<123> in year 2023. $wday is the day of the week, with 0 indicating Sunday and 3 indicating Wednesday. $yday is the day of -the year, in the range C<1..365> (or C<1..366> in leap years.) +the year, in the range C<0..364> (or C<0..365> in leap years.) Note that the $year element is I<not> simply the last two digits of the year. If you assume it is, then you create non-Y2K-compliant @@ -2075,9 +2085,9 @@ or equivalently, @foo = grep {!/^#/} @bar; # weed out comments -Note that, because C<$_> is a reference into the list value, it can -be used to modify the elements of the array. While this is useful and -supported, it can cause bizarre results if the LIST is not a named array. +Note that C<$_> 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 C<foreach>, C<map> @@ -2105,7 +2115,7 @@ integer overflow trigger a warning. There is no builtin C<import> function. It is just an ordinary method (subroutine) defined (or inherited) by modules that wish to export names to another module. The C<use> function calls the C<import> method -for the package used. See also L</use()>, L<perlmod>, and L<Exporter>. +for the package used. See also L</use>, L<perlmod>, and L<Exporter>. =item index STR,SUBSTR,POSITION @@ -2214,6 +2224,9 @@ or how about sorted by key: print $key, '=', $ENV{$key}, "\n"; } +The returned values are copies of the original keys in the hash, so +modifying them will not affect the original hash. Compare L</values>. + To sort a hash by value, you'll need to use a C<sort> function. Here's a descending numeric sort of a hash by its values: @@ -2321,13 +2334,14 @@ success, false otherwise. =item listen SOCKET,QUEUESIZE Does the same thing that the listen system call does. Returns true if -it succeeded, false otherwise. See the example in L<perlipc/"Sockets: Client/Server Communication">. +it succeeded, false otherwise. See the example in +L<perlipc/"Sockets: Client/Server Communication">. =item local EXPR You really probably want to be using C<my> instead, because C<local> isn't -what most people think of as "local". See L<perlsub/"Private Variables -via my()"> for details. +what most people think of as "local". See +L<perlsub/"Private Variables via my()"> for details. 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 @@ -2351,7 +2365,7 @@ itself, in the range C<0..11> with 0 indicating January and 11 indicating December. $year is the number of years since 1900. That is, $year is C<123> in year 2023. $wday is the day of the week, with 0 indicating Sunday and 3 indicating Wednesday. $yday is the day of -the year, in the range C<1..365> (or C<1..366> in leap years.) $isdst +the year, in the range C<0..364> (or C<0..365> in leap years.) $isdst is true if the specified time occurs during daylight savings time, false otherwise. @@ -2456,13 +2470,36 @@ is just a funny way to write $hash{getkey($_)} = $_; } -Note that, because C<$_> is a reference into the list value, it can -be used to modify the elements of the array. While this is useful and -supported, it can cause bizarre results if the LIST is not a named array. +Note that C<$_> 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 C<foreach> loop for this purpose would be clearer in most cases. See also L</grep> for an array composed of those items of the original list for which the BLOCK or EXPR evaluates to true. +C<{> starts both hash references and blocks, so C<map { ...> could be either +the start of map BLOCK LIST or map EXPR, LIST. Because perl doesn't look +ahead for the closing C<}> it has to take a guess at which its dealing with +based what it finds just after the C<{>. Usually it gets it right, but if it +doesn't it won't realize something is wrong until it gets to the C<}> and +encounters the missing (or unexpected) comma. The syntax error will be +reported close to the C<}> but you'll need to change something near the C<{> +such as using a unary C<+> to give perl some help: + + %hash = map { "\L$_", 1 } @array # perl guesses EXPR. wrong + %hash = map { +"\L$_", 1 } @array # perl guesses BLOCK. right + %hash = map { ("\L$_", 1) } @array # this also works + %hash = map { lc($_), 1 } @array # as does this. + %hash = map +( lc($_), 1 ), @array # this is EXPR and works! + + %hash = map ( lc($_), 1 ), @array # evaluates to (1, @array) + +or to force an anon hash constructor use C<+{> + + @hashes = map +{ lc($_), 1 }, @array # EXPR, so needs , at end + +and you get list of anonymous hashes each with only 1 entry. + =item mkdir FILENAME,MASK =item mkdir FILENAME @@ -2489,13 +2526,13 @@ first to get the correct constant definitions. If CMD is C<IPC_STAT>, then ARG must be a variable which will hold the returned C<msqid_ds> structure. Returns like C<ioctl>: the undefined value for error, C<"0 but true"> for zero, or the actual return value otherwise. See also -C<IPC::SysV> and C<IPC::Semaphore> documentation. +L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::Semaphore> documentation. =item msgget KEY,FLAGS Calls the System V IPC function msgget(2). Returns the message queue -id, or the undefined value if there is an error. See also C<IPC::SysV> -and C<IPC::Msg> documentation. +id, or the undefined value if there is an error. See also +L<perlipc/"SysV IPC"> and C<IPC::SysV> and C<IPC::Msg> documentation. =item msgrcv ID,VAR,SIZE,TYPE,FLAGS @@ -2505,7 +2542,8 @@ SIZE. Note that when a message is received, the message type as a native long integer will be the first thing in VAR, followed by the actual message. This packing may be opened with C<unpack("l! a*")>. Taints the variable. Returns true if successful, or false if there is -an error. See also C<IPC::SysV> and C<IPC::SysV::Msg> documentation. +an error. See also L<perlipc/"SysV IPC">, C<IPC::SysV>, and +C<IPC::SysV::Msg> documentation. =item msgsnd ID,MSG,FLAGS @@ -2809,8 +2847,8 @@ otherwise it's necessary to protect any leading and trailing whitespace: $file =~ s#^(\s)#./$1#; open(FOO, "< $file\0"); -(this may not work on some bizzare filesystems). One should -conscientiously choose between the the I<magic> and 3-arguments form +(this may not work on some bizarre filesystems). One should +conscientiously choose between the I<magic> and 3-arguments form of open(): open IN, $ARGV[0]; @@ -2832,7 +2870,7 @@ another way to protect your filenames from interpretation. For example: sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL) or die "sysopen $path: $!"; $oldfh = select(HANDLE); $| = 1; select($oldfh); - print HANDLE "stuff $$\n"); + print HANDLE "stuff $$\n"; seek(HANDLE, 0, 0); print "File contains: ", <HANDLE>; @@ -2923,7 +2961,7 @@ sequence of characters that give the order and type of values, as follows: a A string with arbitrary binary data, will be null padded. - A An ascii string, will be space padded. + A An 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()). @@ -3143,13 +3181,13 @@ because they obey the native byteorder and endianness. For example a 4-byte integer 0x12345678 (305419896 decimal) be ordered natively (arranged in and handled by the CPU registers) into bytes as - 0x12 0x34 0x56 0x78 # little-endian - 0x78 0x56 0x34 0x12 # big-endian + 0x12 0x34 0x56 0x78 # big-endian + 0x78 0x56 0x34 0x12 # little-endian -Basically, the Intel, Alpha, and VAX CPUs are little-endian, while -everybody else, for example Motorola m68k/88k, PPC, Sparc, HP PA, -Power, and Cray are big-endian. MIPS can be either: Digital used it -in little-endian mode; SGI uses it in big-endian mode. +Basically, the Intel and VAX CPUs are little-endian, while everybody +else, for example Motorola m68k/88k, PPC, Sparc, HP PA, Power, and +Cray are big-endian. Alpha and MIPS can be either: Digital/Compaq +used/uses them in little-endian mode; SGI/Cray uses them in big-endian mode. The names `big-endian' and `little-endian' are comic references to the classic "Gulliver's Travels" (via the paper "On Holy Wars and a @@ -3196,6 +3234,15 @@ equal $foo). =item * +If the pattern begins with a C<U>, the resulting string will be treated +as Unicode-encoded. You can force UTF8 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 UTF8 encode your +string, and then follow this with a C<U*> somewhere in your pattern. + +=item * + You must yourself do any alignment or padding by inserting for example enough C<'x'>es while packing. There is no way to pack() and unpack() could know where the bytes are going to or coming from. Therefore @@ -3266,10 +3313,10 @@ Examples: The same template may generally also be used in unpack(). -=item package - =item package NAMESPACE +=item package + Declares the compilation unit as being in the given namespace. The scope of the package declaration is from the declaration itself through the end of the enclosing block, file, or eval (the same as the C<my> operator). @@ -3327,7 +3374,7 @@ array in subroutines, just like C<shift>. =item pos Returns the offset of where the last C<m//g> search left off for the variable -is in question (C<$_> is used when the variable is not specified). May be +in question (C<$_> is used when the variable is not specified). May be modified to change that offset. Such modification will also influence the C<\G> zero-width assertion in regular expressions. See L<perlre> and L<perlop>. @@ -3420,7 +3467,7 @@ Generalized quotes. See L<perlop/"Regexp Quote-Like Operators">. =item quotemeta -Returns the value of EXPR with all non-alphanumeric +Returns the value of EXPR with all non-"word" characters backslashed. (That is, all characters not matching C</[A-Za-z_0-9]/> will be preceded by a backslash in the returned string, regardless of any locale settings.) @@ -3447,12 +3494,13 @@ with the wrong number of RANDBITS.) =item read FILEHANDLE,SCALAR,LENGTH Attempts to read LENGTH bytes of data into variable SCALAR from the -specified FILEHANDLE. Returns the number of bytes actually read, -C<0> at end of file, or undef if there was an error. SCALAR will be grown -or shrunk to the length actually read. An OFFSET may be specified to -place the read data at some other place than the beginning of the -string. This call is actually implemented in terms of stdio's fread(3) -call. To get a true read(2) system call, see C<sysread>. +specified FILEHANDLE. Returns the number of bytes actually read, C<0> +at end of file, or undef if there was an error. SCALAR will be grown +or shrunk to the length actually read. If SCALAR needs growing, the +new bytes will be zero bytes. An OFFSET may be specified to place +the read data into some other place in SCALAR than the beginning. +The call is actually implemented in terms of stdio's fread(3) call. +To get a true read(2) system call, see C<sysread>. =item readdir DIRHANDLE @@ -3927,14 +3975,16 @@ GETALL, then ARG must be a variable which will hold the returned semid_ds structure or semaphore value array. Returns like C<ioctl>: the undefined value for error, "C<0 but true>" for zero, or the actual return value otherwise. The ARG must consist of a vector of native -short integers, which may may be created with C<pack("s!",(0)x$nsem)>. -See also C<IPC::SysV> and C<IPC::Semaphore> documentation. +short integers, which may be created with C<pack("s!",(0)x$nsem)>. +See also L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::Semaphore> +documentation. =item semget KEY,NSEMS,FLAGS Calls the System V IPC function semget. Returns the semaphore id, or -the undefined value if there is an error. See also C<IPC::SysV> and -C<IPC::SysV::Semaphore> documentation. +the undefined value if there is an error. See also +L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::SysV::Semaphore> +documentation. =item semop KEY,OPSTRING @@ -3949,8 +3999,9 @@ following code waits on semaphore $semnum of semaphore id $semid: $semop = pack("sss", $semnum, -1, 0); die "Semaphore trouble: $!\n" unless semop($semid, $semop); -To signal the semaphore, replace C<-1> with C<1>. See also C<IPC::SysV> -and C<IPC::SysV::Semaphore> documentation. +To signal the semaphore, replace C<-1> with C<1>. See also +L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::SysV::Semaphore> +documentation. =item send SOCKET,MSG,FLAGS,TO @@ -3996,7 +4047,7 @@ C<@ARGV> array at file scopes or within the lexical scopes established by the C<eval ''>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>, and C<END {}> constructs. -See also C<unshift>, C<push>, and C<pop>. C<Shift()> and C<unshift> do the +See also C<unshift>, C<push>, and C<pop>. C<shift> and C<unshift> do the same thing to the left end of an array that C<pop> and C<push> do to the right end. @@ -4010,13 +4061,13 @@ first to get the correct constant definitions. If CMD is C<IPC_STAT>, then ARG must be a variable which will hold the returned C<shmid_ds> structure. Returns like ioctl: the undefined value for error, "C<0> but true" for zero, or the actual return value otherwise. -See also C<IPC::SysV> documentation. +See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation. =item shmget KEY,SIZE,FLAGS Calls the System V IPC function shmget. Returns the shared memory segment id, or the undefined value if there is an error. -See also C<IPC::SysV> documentation. +See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation. =item shmread ID,VAR,POS,SIZE @@ -4028,8 +4079,8 @@ detaching from it. When reading, VAR must be a variable that will hold the data read. When writing, if STRING is too long, only SIZE bytes are used; if STRING is too short, nulls are written to fill out SIZE bytes. Return true if successful, or false if there is an error. -shmread() taints the variable. See also C<IPC::SysV> documentation and -the C<IPC::Shareable> module from CPAN. +shmread() taints the variable. See also L<perlipc/"SysV IPC">, +C<IPC::SysV> documentation, and the C<IPC::Shareable> module from CPAN. =item shutdown SOCKET,HOW @@ -4079,7 +4130,7 @@ C<syscall> interface to access setitimer(2) if your system supports it, or else see L</select> above. The Time::HiRes module from CPAN may also help. -See also the POSIX module's C<sigpause> function. +See also the POSIX module's C<pause> function. =item socket SOCKET,DOMAIN,TYPE,PROTOCOL @@ -4231,15 +4282,12 @@ Examples: If you're using strict, you I<must not> declare $a and $b as lexicals. They are package globals. That means -if you're in the C<main> package, it's - - @articles = sort {$main::b <=> $main::a} @files; +if you're in the C<main> package and type -or just - - @articles = sort {$::b <=> $::a} @files; + @articles = sort {$b <=> $a} @files; -but if you're in the C<FooPack> package, it's +then C<$a> and C<$b> are C<$main::a> and C<$main::b> (or C<$::a> and C<$::b>), +but if you're in the C<FooPack> package, it's the same as typing @articles = sort {$FooPack::b <=> $FooPack::a} @files; @@ -4298,11 +4346,9 @@ Example, assuming array lengths are passed before arrays: Splits a string into a list of strings and returns that list. By default, empty leading fields are preserved, and empty trailing ones are deleted. -If not in list context, returns the number of fields found and splits into -the C<@_> array. (In list context, you can force the split into C<@_> by -using C<??> as the pattern delimiters, but it still returns the list -value.) The use of implicit split to C<@_> is deprecated, however, because -it clobbers your subroutine arguments. +In scalar context, returns the number of fields found and splits into +the C<@_> array. Use of split in scalar context is deprecated, however, +because it clobbers your subroutine arguments. If EXPR is omitted, splits the C<$_> string. If PATTERN is also omitted, splits on whitespace (after skipping any leading whitespace). Anything @@ -4324,6 +4370,15 @@ characters at each point it matches that way. For example: produces the output 'h:i:t:h:e:r:e'. +Empty leading (or trailing) fields are produced when there positive width +matches at the beginning (or end) of the string; a zero-width match at the +beginning (or end) of the string does not produce an empty field. For +example: + + print join(':', split(/(?=\w)/, 'hi there!')); + +produces the output 'h:i :t:h:e:r:e!'. + The LIMIT parameter can be used to split a line partially ($login, $passwd, $remainder) = split(/:/, $_, 3); @@ -4361,23 +4416,34 @@ A C<split> on C</\s+/> is like a C<split(' ')> except that any leading whitespace produces a null first field. A C<split> with no arguments really does a C<split(' ', $_)> internally. +A PATTERN of C</^/> is treated as if it were C</^/m>, since it isn't +much use otherwise. + Example: open(PASSWD, '/etc/passwd'); while (<PASSWD>) { - ($login, $passwd, $uid, $gid, + chomp; + ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(/:/); #... } -(Note that $shell above will still have a newline on it. See L</chop>, -L</chomp>, and L</join>.) =item sprintf FORMAT, LIST -Returns a string formatted by the usual C<printf> conventions of the -C library function C<sprintf>. See L<sprintf(3)> or L<printf(3)> -on your system for an explanation of the general principles. +Returns a string formatted by the usual C<printf> conventions of the C +library function C<sprintf>. See below for more details +and see L<sprintf(3)> or L<printf(3)> on your system for an explanation of +the general principles. + +For example: + + # Format number with up to 8 leading zeroes + $result = sprintf("%08d", $number); + + # Round number to 3 digits after decimal point + $rounded = sprintf("%.3f", $number); Perl does its own C<sprintf> formatting--it emulates the C function C<sprintf>, but it doesn't use it (except for floating-point @@ -4385,6 +4451,12 @@ numbers, and even then only the standard modifiers are allowed). As a result, any non-standard extensions in your local C<sprintf> are not available from Perl. +Unlike C<printf>, C<sprintf> does not do what you probably mean when you +pass it an array as your first argument. The array is given scalar context, +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. + Perl's C<sprintf> permits the following universally-known conversions: %% a percent sign @@ -4417,6 +4489,12 @@ permits these unnecessary but widely-supported conversions: %O a synonym for %lo %F a synonym for %f +Note that the number of exponent digits in the scientific notation by +C<%e>, C<%E>, C<%g> and C<%G> 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". + Perl permits the following universally-known flags between the C<%> and the conversion letter: @@ -4654,7 +4732,7 @@ The commonly available S_IF* constants are and the S_IF* functions are - S_IFMODE($mode) the part of $mode containg the permission bits + S_IFMODE($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 @@ -4998,9 +5076,13 @@ case the SCALAR is empty you can use OFFSET but only zero offset. =item tell -Returns the current position for FILEHANDLE. FILEHANDLE may be an -expression whose value gives the name of the actual filehandle. If -FILEHANDLE is omitted, assumes the file last read. +Returns the current position 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. + +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. There is no C<systell> function. Use C<sysseek(FH, 0, 1)> for that. @@ -5046,6 +5128,7 @@ A class implementing a hash should have the following methods: FIRSTKEY this NEXTKEY this, lastkey DESTROY this + UNTIE this A class implementing an ordinary array should have the following methods: @@ -5062,6 +5145,7 @@ A class implementing an ordinary array should have the following methods: SPLICE this, offset, length, LIST EXTEND this, count DESTROY this + UNTIE this A class implementing a file handle should have the following methods: @@ -5072,8 +5156,15 @@ A class implementing a file handle should have the following methods: 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 A class implementing a scalar should have the following methods: @@ -5081,6 +5172,7 @@ A class implementing a scalar should have the following methods: FETCH this, STORE this, value DESTROY this + UNTIE this Not all methods indicated above need be implemented. See L<perltie>, L<Tie::Hash>, L<Tie::Array>, L<Tie::Scalar>, and L<Tie::Handle>. @@ -5349,7 +5441,8 @@ derive their C<import> method via inheritance from the C<Exporter> class that is defined in the C<Exporter> module. See L<Exporter>. If no C<import> method can be found then the call is skipped. -If you don't want your namespace altered, explicitly supply an empty list: +If you do not want to call the package's C<import> method (for instance, +to stop your namespace from being altered), explicitly supply the empty list: use Module (); @@ -5370,8 +5463,9 @@ called). Note that there is no comma after VERSION! Because this is a wide-open interface, pragmas (compiler directives) are also implemented this way. Currently implemented pragmas are: - use integer; + use constant; use diagnostics; + use integer; use sigtrap qw(SEGV BUS); use strict qw(subs vars refs); use subs qw(afunc blurfl); @@ -5391,7 +5485,9 @@ by C<use>, i.e., it calls C<unimport Module LIST> instead of C<import>. If no C<unimport> method can be found the call fails with a fatal error. -See L<perlmod> for a list of standard modules and pragmas. +See L<perlmodlib> for a list of standard modules and pragmas. See L<perlrun> +for the C<-M> and C<-m> command-line options to perl that give C<use> +functionality from the command-line. =item utime LIST @@ -5415,12 +5511,11 @@ subject to change in future versions of perl, but it is guaranteed to be the same order as either the C<keys> or C<each> function would produce on the same (unmodified) hash. -Note that you cannot modify the values of a hash this way, because the -returned list is just a copy. You need to use a hash slice for that, -since it's lvaluable in a way that values() is not. +Note that the values are not copied, which means modifying them will +modify the contents of the hash: - for (values %hash) { s/foo/bar/g } # FAILS! - for (@hash{keys %hash}) { s/foo/bar/g } # ok + for (values %hash) { s/foo/bar/g } # modifies %hash values + for (@hash{keys %hash}) { s/foo/bar/g } # same As a side effect, calling values() resets the HASH's internal iterator. See also C<keys>, C<each>, and C<sort>. @@ -5438,7 +5533,7 @@ If BITS is 8, "elements" coincide with bytes of the input string. 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 C<n>/C<N> (and analoguously +pack()/unpack() with big-endian formats C<n>/C<N> (and analogously for BITS==64). See L<"pack"> for details. If bits is 4 or less, the string is broken into bytes, then the bits @@ -5453,9 +5548,18 @@ to give the expression the correct precedence as in vec($image, $max_x * $x + $y, 8) = 3; -If the selected element is off the end of 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. +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). + +The string should not contain any character with the value > 255 (which +can only happen if you're using UTF8 encoding). If it does, it will be +treated as something which is not UTF8 encoded. When the C<vec> was +assigned to, other parts of your program will also no longer consider the +string to be UTF8 encoded. In other words, if you do have such characters +in your string, vec() will operate on the actual byte string, and not the +conceptual character string. Strings created with C<vec> can also be manipulated with the logical operators C<|>, C<&>, C<^>, and C<~>. These operators will assume a bit diff --git a/contrib/perl5/pod/perlguts.pod b/contrib/perl5/pod/perlguts.pod index 2900b442eb71..9993cc114ea6 100644 --- a/contrib/perl5/pod/perlguts.pod +++ b/contrib/perl5/pod/perlguts.pod @@ -4,10 +4,10 @@ perlguts - Introduction to the Perl API =head1 DESCRIPTION -This document attempts to describe how to use the Perl API, as well as containing -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. +This document attempts to describe how to use the Perl API, as well as +containing 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. =head1 Variables @@ -34,8 +34,8 @@ as well.) =head2 Working with SVs An SV can be created and loaded with one command. There are four types of -values that can be loaded: an integer value (IV), a double (NV), a string, -(PV), and another scalar (SV). +values that can be loaded: an integer value (IV), a double (NV), +a string (PV), and another scalar (SV). The six routines are: @@ -76,6 +76,10 @@ L<perlsec>). This pointer may be NULL if that information is not important. Note that this function requires you to specify the length of the format. +STRLEN is an integer type (Size_t, usually defined as size_t in +config.h) guaranteed to be large enough to represent the size of +any string that perl can handle. + The C<sv_set*()> functions are not generic enough to operate on values that have "magic". See L<Magic Virtual Tables> later in this document. @@ -210,6 +214,48 @@ line and all will be well. To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this call is not necessary (see L<Reference Counts and Mortality>). +=head2 Offsets + +Perl provides the function C<sv_chop> to efficiently remove characters +from the beginning of a string; you give it an SV and a pointer to +somewhere inside the the PV, and it discards everything before the +pointer. The efficiency comes by means of a little hack: instead of +actually removing the characters, C<sv_chop> sets the flag C<OOK> +(offset OK) to signal to other functions that the offset hack is in +effect, and it puts the number of bytes chopped off into the IV field +of the SV. It then moves the PV pointer (called C<SvPVX>) forward that +many bytes, and adjusts C<SvCUR> and C<SvLEN>. + +Hence, at this point, the start of the buffer that we allocated lives +at C<SvPVX(sv) - SvIV(sv)> in memory and the PV pointer is pointing +into the middle of this allocated storage. + +This is best demonstrated by example: + + % ./perl -Ilib -MDevel::Peek -le '$a="12345"; $a=~s/.//; Dump($a)' + SV = PVIV(0x8128450) at 0x81340f0 + REFCNT = 1 + FLAGS = (POK,OOK,pPOK) + IV = 1 (OFFSET) + PV = 0x8135781 ( "1" . ) "2345"\0 + CUR = 4 + LEN = 5 + +Here the number of bytes chopped off (1) is put into IV, and +C<Devel::Peek::Dump> helpfully reminds us that this is an offset. The +portion of the string between the "real" and the "fake" beginnings is +shown in parentheses, and the values of C<SvCUR> and C<SvLEN> reflect +the fake beginning, not the real one. + +Something similar to the offset hack is perfomed on AVs to enable +efficient shifting and splicing off the beginning of the array; while +C<AvARRAY> points to the first element in the array that is visible from +Perl, C<AvALLOC> points to the real start of the C array. These are +usually the same, but a C<shift> operation can be carried out by +increasing C<AvARRAY> by one and decreasing C<AvFILL> and C<AvLEN>. +Again, the location of the real start of the C array only comes into +play when freeing the array. See C<av_shift> in F<av.c>. + =head2 What's Really Stored in an SV? Recall that the usual method of determining the type of scalar you have is @@ -832,6 +878,8 @@ The current kinds of Magic Virtual Tables are: a vtbl_amagicelem %OVERLOAD hash element c (none) Holds overload table (AMT) on stash B vtbl_bm Boyer-Moore (fast string search) + D vtbl_regdata Regex match position data (@+ and @- vars) + d vtbl_regdatum Regex match position data element E vtbl_env %ENV hash e vtbl_envelem %ENV hash element f vtbl_fm Formline ('compiled' format) @@ -1053,7 +1101,7 @@ an C<ENTER>/C<LEAVE> pair. Inside such a I<pseudo-block> the following service is available: -=over +=over 4 =item C<SAVEINT(int i)> @@ -1078,8 +1126,20 @@ and back. =item C<SAVEFREESV(SV *sv)> The refcount of C<sv> would be decremented at the end of -I<pseudo-block>. This is similar to C<sv_2mortal>, which should (?) be -used instead. +I<pseudo-block>. This is similar to C<sv_2mortal> in that it is also a +mechanism for doing a delayed C<SvREFCNT_dec>. However, while C<sv_2mortal> +extends the lifetime of C<sv> until the beginning of the next statement, +C<SAVEFREESV> extends it until the end of the enclosing scope. These +lifetimes can be wildly different. + +Also compare C<SAVEMORTALIZESV>. + +=item C<SAVEMORTALIZESV(SV *sv)> + +Just like C<SAVEFREESV>, but mortalizes C<sv> at the end of the current +scope instead of decrementing its reference count. This usually has the +effect of keeping C<sv> alive until the statement that called the currently +live scope has finished executing. =item C<SAVEFREEOP(OP *op)> @@ -1126,7 +1186,7 @@ provide pointers to the modifiable data explicitly (either C pointers, or Perlish C<GV *>s). Where the above macros take C<int>, a similar function takes C<int *>. -=over +=over 4 =item C<SV* save_scalar(GV *gv)> @@ -1215,6 +1275,7 @@ to use the macros: These macros automatically adjust the stack for you, if needed. Thus, you do not need to call C<EXTEND> to extend the stack. +However, see L</Putting a C value on Perl stack> For more information, consult L<perlxs> and L<perlxstut>. @@ -1344,6 +1405,23 @@ The macro to put this target on stack is C<PUSHTARG>, and it is directly used in some opcodes, as well as indirectly in zillions of others, which use it via C<(X)PUSH[pni]>. +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: + + XPUSHi(10); + XPUSHi(20); + +This translates as "set C<TARG> to 10, push a pointer to C<TARG> onto +the stack; set C<TARG> to 20, push a pointer to C<TARG> 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 C<TARG>, which we have set +to 20. If you need to push multiple different values, use C<XPUSHs>, +which bypasses C<TARG>. + +On a related note, if you do use C<(X)PUSH[npi]>, then you're going to +need a C<dTARG> in your variable declarations so that the C<*PUSH*> +macros can make use of the local variable C<TARG>. + =head2 Scratchpads The question remains on when the SVs which are I<target>s for opcodes @@ -1461,15 +1539,40 @@ The execution order is indicated by C<===E<gt>> marks, thus it is C<3 4 5 6> (node C<6> is not included into above listing), i.e., C<gvsv gvsv add whatever>. +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 +F<pp*.c> files; the function which implements the op with type C<gvsv> +is C<pp_gvsv>, and so on. As the tree above shows, different ops have +different numbers of children: C<add> 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. + +The simplest type of op structure is C<OP>: this has no children. Unary +operators, C<UNOP>s, have one child, and this is pointed to by the +C<op_first> field. Binary operators (C<BINOP>s) have not only an +C<op_first> field but also an C<op_last> field. The most complex type of +op is a C<LISTOP>, which has any number of children. In this case, the +first child is pointed to by C<op_first> and the last child by +C<op_last>. The children in between can be found by iteratively +following the C<op_sibling> pointer from the first child to the last. + +There are also two other op types: a C<PMOP> holds a regular expression, +and has no children, and a C<LOOP> may or may not have children. If the +C<op_children> field is non-zero, it behaves like a C<LISTOP>. To +complicate matters, if a C<UNOP> is actually a C<null> op after +optimization (see L</Compile pass 2: context propagation>) it will still +have children in accordance with its former type. + =head2 Compile pass 1: check routines -The tree is created by the I<pseudo-compiler> while yacc code feeds it -the constructions it recognizes. Since yacc works bottom-up, so does +The tree is created by the compiler while I<yacc> code feeds it +the constructions it recognizes. Since I<yacc> works bottom-up, so does the first pass of perl compilation. What makes this pass interesting for perl developers is that some optimization may be performed on this pass. This is optimization by -so-called I<check routines>. The correspondence between node names +so-called "check routines". The correspondence between node names and corresponding check routines is described in F<opcode.pl> (do not forget to run C<make regen_headers> if you modify this file). @@ -1521,10 +1624,42 @@ additional complications for conditionals). These optimizations are done in the subroutine peep(). Optimizations performed at this stage are subject to the same restrictions as in the pass 2. -=head1 How multiple interpreters and concurrency are supported +=head1 Examining internal data structures with the C<dump> functions + +To aid debugging, the source file F<dump.c> contains a number of +functions which produce formatted output of internal data structures. + +The most commonly used of these functions is C<Perl_sv_dump>; it's used +for dumping SVs, AVs, HVs, and CVs. The C<Devel::Peek> module calls +C<sv_dump> to produce debugging output from Perl-space, so users of that +module should already be familiar with its format. + +C<Perl_op_dump> can be used to dump an C<OP> structure or any of its +derivatives, and produces output similiar to C<perl -Dx>; in fact, +C<Perl_dump_eval> will dump the main root of the code being evaluated, +exactly like C<-Dx>. + +Other useful functions are C<Perl_dump_sub>, which turns a C<GV> into an +op tree, C<Perl_dump_packsubs> which calls C<Perl_dump_sub> on all the +subroutines in a package like so: (Thankfully, these are all xsubs, so +there is no op tree) + + (gdb) print Perl_dump_packsubs(PL_defstash) + + SUB attributes::bootstrap = (xsub 0x811fedc 0) + + SUB UNIVERSAL::can = (xsub 0x811f50c 0) -WARNING: This information is subject to radical changes prior to -the Perl 5.6 release. Use with caution. + SUB UNIVERSAL::isa = (xsub 0x811f304 0) + + SUB UNIVERSAL::VERSION = (xsub 0x811f7ac 0) + + SUB DynaLoader::boot_DynaLoader = (xsub 0x805b188 0) + +and C<Perl_dump_all>, which dumps all the subroutines in the stash and +the op tree of the main root. + +=head1 How multiple interpreters and concurrency are supported =head2 Background and PERL_IMPLICIT_CONTEXT @@ -1540,8 +1675,8 @@ interpreter. Three macros control the major Perl build flavors: MULTIPLICITY, USE_THREADS and PERL_OBJECT. The MULTIPLICITY build has a C structure that packages all the interpreter state, there is a similar thread-specific -data structure under USE_THREADS, and the PERL_OBJECT build has a C++ -class to maintain interpreter state. In all three cases, +data structure under USE_THREADS, and the (now deprecated) PERL_OBJECT +build has a C++ class to maintain interpreter state. In all three cases, PERL_IMPLICIT_CONTEXT is also normally defined, and enables the support for passing in a "hidden" first argument that represents all three data structures. @@ -1557,17 +1692,11 @@ First problem: deciding which functions will be public API functions and which will be private. All functions whose names begin C<S_> 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. The easiest way to be B<sure> a function is part of the API -is to find its entry in L<perlapi>. If it exists in L<perlapi>, it's part -of the API. If it doesn't, and you think it should be (i.e., you need it fo -r your extension), send mail via L<perlbug> explaining why you think it -should be. - -(L<perlapi> itself is generated by embed.pl, a Perl script that generates -significant portions of the Perl source code. It has a list of almost -all the functions defined by the Perl interpreter along with their calling -characteristics and some flags. Functions that are part of the public API -are marked with an 'A' in its flags.) +part of the API. (See L</Internal Functions>.) The easiest way to be B<sure> a +function is part of the API is to find its entry in L<perlapi>. +If it exists in L<perlapi>, 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 +L<perlbug> explaining why you think it should be. Second problem: there must be a syntax so that the same subroutine declarations and calls can pass a structure as their first argument, @@ -1590,10 +1719,11 @@ C<pTHX_> is one of a number of macros (in perl.h) that hide the details of the interpreter's context. THX stands for "thread", "this", or "thingy", as the case may be. (And no, George Lucas is not involved. :-) The first character could be 'p' for a B<p>rototype, 'a' for B<a>rgument, -or 'd' for B<d>eclaration. +or 'd' for B<d>eclaration, so we have C<pTHX>, C<aTHX> and C<dTHX>, and +their variants. -When Perl is built without PERL_IMPLICIT_CONTEXT, there is no first -argument containing the interpreter's context. The trailing underscore +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 @@ -1602,14 +1732,14 @@ macro without the trailing underscore is used when there are no additional explicit arguments. When a core function calls another, it must pass the context. This -is normally hidden via macros. Consider C<sv_setsv>. It expands +is normally hidden via macros. Consider C<sv_setsv>. It expands into something like this: ifdef PERL_IMPLICIT_CONTEXT - define sv_setsv(a,b) Perl_sv_setsv(aTHX_ a, b) + define sv_setsv(a,b) Perl_sv_setsv(aTHX_ a, b) /* can't do this for vararg functions, see below */ else - define sv_setsv Perl_sv_setsv + define sv_setsv Perl_sv_setsv endif This works well, and means that XS authors can gleefully write: @@ -1629,8 +1759,8 @@ Under PERL_OBJECT in the core, that will translate to either: # see objXSUB.h Under PERL_OBJECT in extensions (aka PERL_CAPI), or under -MULTIPLICITY/USE_THREADS w/ PERL_IMPLICIT_CONTEXT in both core -and extensions, it will be: +MULTIPLICITY/USE_THREADS with PERL_IMPLICIT_CONTEXT in both core +and extensions, it will become: Perl_sv_setsv(aTHX_ foo, bar); # the canonical Perl "API" # for all build flavors @@ -1652,6 +1782,14 @@ You can ignore [pad]THX[xo] when browsing the Perl headers/sources. Those are strictly for use within the core. Extensions and embedders need only be aware of [pad]THX. +=head2 So what happened to dTHR? + +C<dTHR> was introduced in perl 5.005 to support the older thread model. +The older thread model now uses the C<THX> mechanism to pass context +pointers around, so C<dTHR> 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. + =head2 How do I use all this in extensions? When Perl is built with PERL_IMPLICIT_CONTEXT, extensions that call @@ -1668,7 +1806,7 @@ Thus, something like: sv_setsv(asv, bsv); -in your extesion will translate to this when PERL_IMPLICIT_CONTEXT is +in your extension will translate to this when PERL_IMPLICIT_CONTEXT is in effect: Perl_sv_setsv(Perl_get_context(), asv, bsv); @@ -1684,31 +1822,31 @@ work. The second, more efficient way is to use the following template for your Foo.xs: - #define PERL_NO_GET_CONTEXT /* we want efficiency */ - #include "EXTERN.h" - #include "perl.h" - #include "XSUB.h" + #define PERL_NO_GET_CONTEXT /* we want efficiency */ + #include "EXTERN.h" + #include "perl.h" + #include "XSUB.h" static my_private_function(int arg1, int arg2); - static SV * - my_private_function(int arg1, int arg2) - { - dTHX; /* fetch context */ - ... call many Perl API functions ... - } + static SV * + my_private_function(int arg1, int arg2) + { + dTHX; /* fetch context */ + ... call many Perl API functions ... + } [... etc ...] - MODULE = Foo PACKAGE = Foo + MODULE = Foo PACKAGE = Foo - /* typical XSUB */ + /* typical XSUB */ - void - my_xsub(arg) - int arg - CODE: - my_private_function(arg, 10); + void + my_xsub(arg) + int arg + CODE: + my_private_function(arg, 10); Note that the only two changes from the normal way of writing an extension is the addition of a C<#define PERL_NO_GET_CONTEXT> before @@ -1723,32 +1861,32 @@ The third, even more efficient way is to ape how it is done within the Perl guts: - #define PERL_NO_GET_CONTEXT /* we want efficiency */ - #include "EXTERN.h" - #include "perl.h" - #include "XSUB.h" + #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 my_private_function(pTHX_ int arg1, int arg2); - static SV * - my_private_function(pTHX_ int arg1, int arg2) - { - /* dTHX; not needed here, because THX is an argument */ - ... call Perl API functions ... - } + static SV * + 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 + MODULE = Foo PACKAGE = Foo - /* typical XSUB */ + /* typical XSUB */ - void - my_xsub(arg) - int arg - CODE: - my_private_function(aTHX_ arg, 10); + void + my_xsub(arg) + int arg + CODE: + my_private_function(aTHX_ arg, 10); This implementation never has to fetch the context using a function call, since it is always passed as an extra argument. Depending on @@ -1759,15 +1897,34 @@ Never add a comma after C<pTHX> 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. +=head2 Should I do anything special if I call perl from multiple threads? + +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. + +The C<perl_alloc> and C<perl_clone> 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 C<PERL_SET_CONTEXT> macro in that +thread as the first thing you do: + + /* do this before doing anything else with some_perl */ + PERL_SET_CONTEXT(some_perl); + + ... other Perl API calls on some_perl go here ... + =head2 Future Plans and PERL_IMPLICIT_SYS 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 PERL_OBJECT, -but is mostly there for MULTIPLICITY and USE_THREADS (see inside -iperlsys.h). +PERL_IMPLICIT_SYS macro. Currently it only works with PERL_OBJECT +and USE_THREADS on Windows (see inside iperlsys.h). This allows the ability to provide an extra pointer (called the "host" environment) for all the system calls. This makes it possible for @@ -1782,6 +1939,364 @@ 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. +=head1 Internal Functions + +All of Perl's internal functions which will be exposed to the outside +world are be prefixed by C<Perl_> 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 C<PL_>. (By convention, +static functions start with C<S_>) + +Inside the Perl core, you can get at the functions either with or +without the C<Perl_> prefix, thanks to a bunch of defines that live in +F<embed.h>. This header file is generated automatically from +F<embed.pl>. F<embed.pl> 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 at the +end of F<embed.pl> as well. Here's a sample entry from that table: + + Apd |SV** |av_fetch |AV* ar|I32 key|I32 lval + +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: + +=over 3 + +=item A + +This function is a part of the public API. + +=item p + +This function has a C<Perl_> prefix; ie, it is defined as C<Perl_av_fetch> + +=item d + +This function has documentation using the C<apidoc> feature which we'll +look at in a second. + +=back + +Other available flags are: + +=over 3 + +=item s + +This is a static function and is defined as C<S_whatever>, and usually +called within the sources as C<whatever(...)>. + +=item n + +This does not use C<aTHX_> and C<pTHX> to pass interpreter context. (See +L<perlguts/Background and PERL_IMPLICIT_CONTEXT>.) + +=item r + +This function never returns; C<croak>, C<exit> and friends. + +=item f + +This function takes a variable number of arguments, C<printf> style. +The argument list should end with C<...>, like this: + + Afprd |void |croak |const char* pat|... + +=item M + +This function is part of the experimental development API, and may change +or disappear without notice. + +=item o + +This function should not have a compatibility macro to define, say, +C<Perl_parse> to C<parse>. It must be called as C<Perl_parse>. + +=item j + +This function is not a member of C<CPerlObj>. If you don't know +what this means, don't use it. + +=item x + +This function isn't exported out of the Perl core. + +=back + +If you edit F<embed.pl>, you will need to run C<make regen_headers> to +force a rebuild of F<embed.h> and other auto-generated files. + +=head2 Formatted Printing of IVs, UVs, and NVs + +If you are printing IVs, UVs, or NVS instead of the stdio(3) style +formatting codes like C<%d>, C<%ld>, C<%f>, you should use the +following macros for portability + + 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 + +These will take care of 64-bit integers and long doubles. +For example: + + printf("IV is %"IVdf"\n", iv); + +The IVdf will expand to whatever is the correct format for the IVs. + +If you are printing addresses of pointers, use UVxf combined +with PTR2UV(), do not use %lx or %p. + +=head2 Pointer-To-Integer and Integer-To-Pointer + +Because pointer size does not necessarily equal integer size, +use the follow macros to do it right. + + PTR2UV(pointer) + PTR2IV(pointer) + PTR2NV(pointer) + INT2PTR(pointertotype, integer) + +For example: + + IV iv = ...; + SV *sv = INT2PTR(SV*, iv); + +and + + AV *av = ...; + UV uv = PTR2UV(av); + +=head2 Source Documentation + +There's an effort going on to document the internal functions and +automatically produce reference manuals from them - L<perlapi> is one +such manual which details all the functions which are available to XS +writers. L<perlintern> is the autogenerated manual for the functions +which are not part of the API and are supposedly for internal use only. + +Source documentation is created by putting POD comments into the C +source, like this: + + /* + =for apidoc sv_setiv + + Copies an integer into the given SV. Does not handle 'set' magic. See + C<sv_setiv_mg>. + + =cut + */ + +Please try and supply some documentation if you add functions to the +Perl core. + +=head1 Unicode Support + +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. + +=head2 What B<is> Unicode, anyway? + +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. + +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. + +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 UTF8. UTF8 uses +a variable number of bytes to represent a character, instead of just +one. You can learn more about Unicode at http://www.unicode.org/ + +=head2 How can I recognise a UTF8 string? + +You can't. This is because UTF8 data is stored in bytes just like +non-UTF8 data. The Unicode character 200, (C<0xC8> for you hex types) +capital E with a grave accent, is represented by the two bytes +C<v196.172>. Unfortunately, the non-Unicode string C<chr(196).chr(172)> +has that byte sequence as well. So you can't tell just by looking - this +is what makes Unicode input an interesting problem. + +The API function C<is_utf8_string> can help; it'll tell you if a string +contains only valid UTF8 characters. However, it can't do the work for +you. On a character-by-character basis, C<is_utf8_char> will tell you +whether the current character in a string is valid UTF8. + +=head2 How does UTF8 represent Unicode characters? + +As mentioned above, UTF8 uses a variable number of bytes to store a +character. Characters with values 1...128 are stored in one byte, just +like good ol' ASCII. Character 129 is stored as C<v194.129>; this +continues up to character 191, which is C<v194.191>. Now we've run out of +bits (191 is binary C<10111111>) so we move on; 192 is C<v195.128>. And +so it goes on, moving to three bytes at character 2048. + +Assuming you know you're dealing with a UTF8 string, you can find out +how long the first character in it is with the C<UTF8SKIP> macro: + + 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 */ + +Another way to skip over characters in a UTF8 string is to use +C<utf8_hop>, 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. + +All bytes in a multi-byte UTF8 character will have the high bit set, so +you can test if you need to do something special with this character +like this: + + UV uv; + + if (utf & 0x80) + /* Must treat this as UTF8 */ + uv = utf8_to_uv(utf); + else + /* OK to treat this character as a byte */ + uv = *utf; + +You can also see in that example that we use C<utf8_to_uv> to get the +value of the character; the inverse function C<uv_to_utf8> is available +for putting a UV into UTF8: + + if (uv > 0x80) + /* Must treat this as UTF8 */ + utf8 = uv_to_utf8(utf8, uv); + else + /* OK to treat this character as a byte */ + *utf8++ = uv; + +You B<must> convert characters to UVs using the above functions if +you're ever in a situation where you have to match UTF8 and non-UTF8 +characters. You may not skip over UTF8 characters in this case. If you +do this, you'll lose the ability to match hi-bit non-UTF8 characters; +for instance, if your UTF8 string contains C<v196.172>, and you skip +that character, you can never match a C<chr(200)> in a non-UTF8 string. +So don't do that! + +=head2 How does Perl store UTF8 strings? + +Currently, Perl deals with Unicode strings and non-Unicode strings +slightly differently. If a string has been identified as being UTF-8 +encoded, Perl will set a flag in the SV, C<SVf_UTF8>. You can check and +manipulate this flag with the following macros: + + SvUTF8(sv) + SvUTF8_on(sv) + SvUTF8_off(sv) + +This flag has an important effect on Perl's treatment of the string: if +Unicode data is not properly distinguished, regular expressions, +C<length>, C<substr> and other string handling operations will have +undesirable results. + +The problem comes when you have, for instance, a string that isn't +flagged is UTF8, and contains a byte sequence that could be UTF8 - +especially when combining non-UTF8 and UTF8 strings. + +Never forget that the C<SVf_UTF8> flag is separate to the PV value; you +need be sure you don't accidentally knock it off while you're +manipulating SVs. More specifically, you cannot expect to do this: + + SV *sv; + SV *nsv; + STRLEN len; + char *p; + + p = SvPV(sv, len); + frobnicate(p); + nsv = newSVpvn(p, len); + +The C<char*> 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, and act accordingly: + + p = SvPV(sv, len); + frobnicate(p); + nsv = newSVpvn(p, len); + if (SvUTF8(sv)) + SvUTF8_on(nsv); + +In fact, your C<frobnicate> function should be made aware of whether or +not it's dealing with UTF8 data, so that it can handle the string +appropriately. + +=head2 How do I convert a string to UTF8? + +If you're mixing UTF8 and non-UTF8 strings, you might find it necessary +to upgrade one of the strings to UTF8. If you've got an SV, the easiest +way to do this is: + + sv_utf8_upgrade(sv); + +However, you must not do this, for example: + + if (!SvUTF8(left)) + sv_utf8_upgrade(left); + +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. + +Instead, C<bytes_to_utf8> will give you a UTF8-encoded B<copy> 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 +C<utf8_to_bytes> 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. + +=head2 Is there anything else I need to know? + +Not really. Just remember these things: + +=over 3 + +=item * + +There's no way to tell if a string is UTF8 or not. You can tell if an SV +is UTF8 by looking at is C<SvUTF8> flag. Don't forget to set the flag if +something should be UTF8. Treat the flag as part of the PV, even though +it's not - if you pass on the PV to somewhere, pass on the flag too. + +=item * + +If a string is UTF8, B<always> use C<utf8_to_uv> to get at the value, +unless C<!(*s & 0x80)> in which case you can use C<*s>. + +=item * + +When writing to a UTF8 string, B<always> use C<uv_to_utf8>, unless +C<uv < 0x80> in which case you can use C<*s = uv>. + +=item * + +Mixing UTF8 and non-UTF8 strings is tricky. Use C<bytes_to_utf8> to get +a new string which is UTF8 encoded. There are tricks you can use to +delay deciding whether you need to use a UTF8 string until you get to a +high character - C<HALF_UPGRADE> is one of those. + +=back + =head1 AUTHORS Until May 1997, this document was maintained by Jeff Okamoto diff --git a/contrib/perl5/pod/perlhack.pod b/contrib/perl5/pod/perlhack.pod index c64087026412..d524fe55f5fd 100644 --- a/contrib/perl5/pod/perlhack.pod +++ b/contrib/perl5/pod/perlhack.pod @@ -194,6 +194,8 @@ around. It refers to the standard distribution. ``Hacking on the core'' means you're changing the C source code to the Perl interpreter. ``A core module'' is one that ships with Perl. +=head2 Keeping in sync + The source code to the Perl interpreter, in its different versions, is kept in a repository managed by a revision control system (which is currently the Perforce program, see http://perforce.com/). The @@ -206,20 +208,256 @@ public release are available at this location: ftp://ftp.linux.activestate.com/pub/staff/gsar/APC/ -Selective parts are also visible via the rsync protocol. To get all -the individual changes to the mainline since the last development -release, use the following command: - - rsync -avuz rsync://ftp.linux.activestate.com/perl-diffs perl-diffs - -Use this to get the latest source tree in full: - - rsync -avuz rsync://ftp.linux.activestate.com/perl-current perl-current +If you are a member of the perl5-porters mailing list, it is a good +thing to keep in touch with the most recent changes. If not only to +verify if what you would have posted as a bug report isn't already +solved in the most recent available perl development branch, also +known as perl-current, bleading edge perl, bleedperl or bleadperl. Needless to say, the source code in perl-current is usually in a perpetual state of evolution. You should expect it to be very buggy. Do B<not> use it for any purpose other than testing and development. +Keeping in sync with the most recent branch can be done in several ways, +but the most convenient and reliable way is using B<rsync>, available at +ftp://rsync.samba.org/pub/rsync/ . (You can also get the most recent +branch by FTP.) + +If you choose to keep in sync using rsync, there are two approaches +to doing so: + +=over 4 + +=item rsync'ing the source tree + +Presuming you are in the directory where your perl source resides +and you have rsync installed and available, you can `upgrade' to +the bleadperl using: + + # rsync -avz rsync://ftp.linux.activestate.com/perl-current/ . + +This takes care of updating every single item in the source tree to +the latest applied patch level, creating files that are new (to your +distribution) and setting date/time stamps of existing files to +reflect the bleadperl status. + +You can than check what patch was the latest that was applied by +looking in the file B<.patch>, which will show the number of the +latest patch. + +If you have more than one machine to keep in sync, and not all of +them have access to the WAN (so you are not able to rsync all the +source trees to the real source), there are some ways to get around +this problem. + +=over 4 + +=item Using rsync over the LAN + +Set up a local rsync server which makes the rsynced source tree +available to the LAN and sync the other machines against this +directory. + +From http://rsync.samba.org/README.html: + + "Rsync uses rsh or ssh for communication. It does not need to be + setuid and requires no special privileges for installation. It + does not require a inetd entry or a deamon. You must, however, + have a working rsh or ssh system. Using ssh is recommended for + its security features." + +=item Using pushing over the NFS + +Having the other systems mounted over the NFS, you can take an +active pushing approach by checking the just updated tree against +the other not-yet synced trees. An example would be + + #!/usr/bin/perl -w + + use strict; + use File::Copy; + + my %MF = map { + m/(\S+)/; + $1 => [ (stat $1)[2, 7, 9] ]; # mode, size, mtime + } `cat MANIFEST`; + + my %remote = map { $_ => "/$_/pro/3gl/CPAN/perl-5.7.1" } qw(host1 host2); + + foreach my $host (keys %remote) { + unless (-d $remote{$host}) { + print STDERR "Cannot Xsync for host $host\n"; + next; + } + foreach my $file (keys %MF) { + my $rfile = "$remote{$host}/$file"; + my ($mode, $size, $mtime) = (stat $rfile)[2, 7, 9]; + defined $size or ($mode, $size, $mtime) = (0, 0, 0); + $size == $MF{$file}[1] && $mtime == $MF{$file}[2] and next; + printf "%4s %-34s %8d %9d %8d %9d\n", + $host, $file, $MF{$file}[1], $MF{$file}[2], $size, $mtime; + unlink $rfile; + copy ($file, $rfile); + utime time, $MF{$file}[2], $rfile; + chmod $MF{$file}[0], $rfile; + } + } + +though this is not perfect. It could be improved with checking +file checksums before updating. Not all NFS systems support +reliable utime support (when used over the NFS). + +=back + +=item rsync'ing the patches + +The source tree is maintained by the pumpking who applies patches to +the files in the tree. These patches are either created by the +pumpking himself using C<diff -c> after updating the file manually or +by applying patches sent in by posters on the perl5-porters list. +These patches are also saved and rsync'able, so you can apply them +yourself to the source files. + +Presuming you are in a directory where your patches reside, you can +get them in sync with + + # rsync -avz rsync://ftp.linux.activestate.com/perl-current-diffs/ . + +This makes sure the latest available patch is downloaded to your +patch directory. + +It's then up to you to apply these patches, using something like + + # last=`ls -rt1 *.gz | tail -1` + # rsync -avz rsync://ftp.linux.activestate.com/perl-current-diffs/ . + # find . -name '*.gz' -newer $last -exec gzcat {} \; >blead.patch + # cd ../perl-current + # patch -p1 -N <../perl-current-diffs/blead.patch + +or, since this is only a hint towards how it works, use CPAN-patchaperl +from Andreas König to have better control over the patching process. + +=back + +=head2 Why rsync the source tree + +=over 4 + +=item It's easier + +Since you don't have to apply the patches yourself, you are sure all +files in the source tree are in the right state. + +=item It's more recent + +According to Gurusamy Sarathy: + + "... The rsync mirror is automatic and syncs with the repository + every five minutes. + + "Updating the patch area still requires manual intervention + (with all the goofiness that implies, which you've noted) and + is typically on a daily cycle. Making this process automatic + is on my tuit list, but don't ask me when." + +=item It's more reliable + +Well, since the patches are updated by hand, I don't have to say any +more ... (see Sarathy's remark). + +=back + +=head2 Why rsync the patches + +=over 4 + +=item It's easier + +If you have more than one machine that you want to keep in track with +bleadperl, it's easier to rsync the patches only once and then apply +them to all the source trees on the different machines. + +In case you try to keep in pace on 5 different machines, for which +only one of them has access to the WAN, rsync'ing all the source +trees should than be done 5 times over the NFS. Having +rsync'ed the patches only once, I can apply them to all the source +trees automatically. Need you say more ;-) + +=item It's a good reference + +If you do not only like to have the most recent development branch, +but also like to B<fix> bugs, or extend features, you want to dive +into the sources. If you are a seasoned perl core diver, you don't +need no manuals, tips, roadmaps, perlguts.pod or other aids to find +your way around. But if you are a starter, the patches may help you +in finding where you should start and how to change the bits that +bug you. + +The file B<Changes> is updated on occasions the pumpking sees as his +own little sync points. On those occasions, he releases a tar-ball of +the current source tree (i.e. perl@7582.tar.gz), which will be an +excellent point to start with when choosing to use the 'rsync the +patches' scheme. Starting with perl@7582, which means a set of source +files on which the latest applied patch is number 7582, you apply all +succeeding patches available from then on (7583, 7584, ...). + +You can use the patches later as a kind of search archive. + +=over 4 + +=item Finding a start point + +If you want to fix/change the behaviour of function/feature Foo, just +scan the patches for patches that mention Foo either in the subject, +the comments, or the body of the fix. A good chance the patch shows +you the files that are affected by that patch which are very likely +to be the starting point of your journey into the guts of perl. + +=item Finding how to fix a bug + +If you've found I<where> the function/feature Foo misbehaves, but you +don't know how to fix it (but you do know the change you want to +make), you can, again, peruse the patches for similar changes and +look how others apply the fix. + +=item Finding the source of misbehaviour + +When you keep in sync with bleadperl, the pumpking would love to +I<see> that the community efforts realy work. So after each of his +sync points, you are to 'make test' to check if everything is still +in working order. If it is, you do 'make ok', which will send an OK +report to perlbug@perl.org. (If you do not have access to a mailer +from the system you just finished successfully 'make test', you can +do 'make okfile', which creates the file C<perl.ok>, which you can +than take to your favourite mailer and mail yourself). + +But of course, as always, things will not allways lead to a success +path, and one or more test do not pass the 'make test'. Before +sending in a bug report (using 'make nok' or 'make nokfile'), check +the mailing list if someone else has reported the bug already and if +so, confirm it by replying to that message. If not, you might want to +trace the source of that misbehaviour B<before> sending in the bug, +which will help all the other porters in finding the solution. + +Here the saved patches come in very handy. You can check the list of +patches to see which patch changed what file and what change caused +the misbehaviour. If you note that in the bug report, it saves the +one trying to solve it, looking for that point. + +=back + +If searching the patches is too bothersome, you might consider using +perl's bugtron to find more information about discussions and +ramblings on posted bugs. + +=back + +If you want to get the best of both worlds, rsync both the source +tree for convenience, reliability and ease and rsync the patches +for reference. + +=head2 Submitting patches + Always submit patches to I<perl5-porters@perl.org>. This lets other porters review your patch, which catches a surprising number of errors in patches. Either use the diff program (available in source code @@ -237,7 +475,7 @@ Your patch should update the documentation and test suite. To report a bug in Perl, use the program I<perlbug> which comes with Perl (if you can't get Perl to work, send mail to the address -I<perlbug@perl.com> or I<perlbug@perl.org>). Reporting bugs through +I<perlbug@perl.org> or I<perlbug@perl.com>). Reporting bugs through I<perlbug> feeds into the automated bug-tracking system, access to which is provided through the web at I<http://bugs.perl.org/>. It often pays to check the archives of the perl5-porters mailing list to @@ -251,31 +489,6 @@ volunteers who test CPAN modules on a variety of platforms. Perl Labs platforms and gives feedback to the CPAN testers mailing list. Both efforts welcome volunteers. -To become an active and patching Perl porter, you'll need to learn how -Perl works on the inside. Chip Salzenberg, a pumpking, has written -articles on Perl internals for The Perl Journal -(I<http://www.tpj.com/>) which explain how various parts of the Perl -interpreter work. The C<perlguts> manpage explains the internal data -structures. And, of course, the C source code (sometimes sparsely -commented, sometimes commented well) is a great place to start (begin -with C<perl.c> and see where it goes from there). A lot of the style -of the Perl source is explained in the I<Porting/pumpkin.pod> file in -the source distribution. - -It is essential that you be comfortable using a good debugger -(e.g. gdb, dbx) before you can patch perl. Stepping through perl -as it executes a script is perhaps the best (if sometimes tedious) -way to gain a precise understanding of the overall architecture of -the language. - -If you build a version of the Perl interpreter with C<-DDEBUGGING>, -Perl's B<-D> command line flag will cause copious debugging information -to be emitted (see the C<perlrun> manpage). If you build a version of -Perl with compiler debugging information (e.g. with the C compiler's -C<-g> option instead of C<-O>) then you can step through the execution -of the interpreter with your favourite C symbolic debugger, setting -breakpoints on particular functions. - It's a good idea to read and lurk for a while before chipping in. That way you'll get to see the dynamic of the conversations, learn the personalities of the players, and hopefully be better prepared to make @@ -285,6 +498,1223 @@ If after all this you still think you want to join the perl5-porters mailing list, send mail to I<perl5-porters-subscribe@perl.org>. To unsubscribe, send mail to I<perl5-porters-unsubscribe@perl.org>. +To hack on the Perl guts, you'll need to read the following things: + +=over 3 + +=item L<perlguts> + +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. + +You might also want to look at Gisle Aas's illustrated perlguts - +there's no guarantee that this will be absolutely up-to-date with the +latest documentation in the Perl core, but the fundamentals will be +right. (http://gisle.aas.no/perl/illguts/) + +=item L<perlxstut> and L<perlxs> + +A working knowledge of XSUB programming is incredibly useful for core +hacking; XSUBs use techniques drawn from the PP code, the portion of the +guts that actually executes a Perl program. It's a lot gentler to learn +those techniques from simple examples and explanation than from the core +itself. + +=item L<perlapi> + +The documentation for the Perl API explains what some of the internal +functions do, as well as the many macros used in the source. + +=item F<Porting/pumpkin.pod> + +This is a collection of words of wisdom for a Perl porter; some of it is +only useful to the pumpkin holder, but most of it applies to anyone +wanting to go about Perl development. + +=item The perl5-porters FAQ + +This is posted to perl5-porters at the beginning on every month, and +should be available from http://perlhacker.org/p5p-faq; alternatively, +you can get the FAQ emailed to you by sending mail to +C<perl5-porters-faq@perl.org>. It contains hints on reading +perl5-porters, information on how perl5-porters works and how Perl +development in general works. + +=back + +=head2 Finding Your Way Around + +Perl maintenance can be split into a number of areas, and certain people +(pumpkins) will have responsibility for each area. These areas sometimes +correspond to files or directories in the source kit. Among the areas are: + +=over 3 + +=item Core modules + +Modules shipped as part of the Perl core live in the F<lib/> and F<ext/> +subdirectories: F<lib/> is for the pure-Perl modules, and F<ext/> +contains the core XS modules. + +=item Documentation + +Documentation maintenance includes looking after everything in the +F<pod/> directory, (as well as contributing new documentation) and +the documentation to the modules in core. + +=item Configure + +The configure process is the way we make Perl portable across the +myriad of operating systems it supports. Responsibility for the +configure, build and installation process, as well as the overall +portability of the core code rests with the configure pumpkin - others +help out with individual operating systems. + +The files involved are the operating system directories, (F<win32/>, +F<os2/>, F<vms/> and so on) the shell scripts which generate F<config.h> +and F<Makefile>, as well as the metaconfig files which generate +F<Configure>. (metaconfig isn't included in the core distribution.) + +=item Interpreter + +And of course, there's the core of the Perl interpreter itself. Let's +have a look at that in a little more detail. + +=back + +Before we leave looking at the layout, though, don't forget that +F<MANIFEST> contains not only the file names in the Perl distribution, +but short descriptions of what's in them, too. For an overview of the +important files, try this: + + perl -lne 'print if /^[^\/]+\.[ch]\s+/' MANIFEST + +=head2 Elements of the interpreter + +The work of the interpreter has two main stages: compiling the code +into the internal representation, or bytecode, and then executing it. +L<perlguts/Compiled code> explains exactly how the compilation stage +happens. + +Here is a short breakdown of perl's operation: + +=over 3 + +=item Startup + +The action begins in F<perlmain.c>. (or F<miniperlmain.c> for miniperl) +This is very high-level code, enough to fit on a single screen, and it +resembles the code found in L<perlembed>; most of the real action takes +place in F<perl.c> + +First, F<perlmain.c> allocates some memory and constructs a Perl +interpreter: + + 1 PERL_SYS_INIT3(&argc,&argv,&env); + 2 + 3 if (!PL_do_undump) { + 4 my_perl = perl_alloc(); + 5 if (!my_perl) + 6 exit(1); + 7 perl_construct(my_perl); + 8 PL_perl_destruct_level = 0; + 9 } + +Line 1 is a macro, and its definition is dependent on your operating +system. Line 3 references C<PL_do_undump>, a global variable - all +global variables in Perl start with C<PL_>. This tells you whether the +current running program was created with the C<-u> flag to perl and then +F<undump>, which means it's going to be false in any sane context. + +Line 4 calls a function in F<perl.c> to allocate memory for a Perl +interpreter. It's quite a simple function, and the guts of it looks like +this: + + my_perl = (PerlInterpreter*)PerlMem_malloc(sizeof(PerlInterpreter)); + +Here you see an example of Perl's system abstraction, which we'll see +later: C<PerlMem_malloc> is either your system's C<malloc>, or Perl's +own C<malloc> as defined in F<malloc.c> if you selected that option at +configure time. + +Next, in line 7, we construct the interpreter; this sets up all the +special variables that Perl needs, the stacks, and so on. + +Now we pass Perl the command line options, and tell it to go: + + exitstatus = perl_parse(my_perl, xs_init, argc, argv, (char **)NULL); + if (!exitstatus) { + exitstatus = perl_run(my_perl); + } + + +C<perl_parse> is actually a wrapper around C<S_parse_body>, as defined +in F<perl.c>, which processes the command line options, sets up any +statically linked XS modules, opens the program and calls C<yyparse> to +parse it. + +=item Parsing + +The aim of this stage is to take the Perl source, and turn it into an op +tree. We'll see what one of those looks like later. Strictly speaking, +there's three things going on here. + +C<yyparse>, the parser, lives in F<perly.c>, although you're better off +reading the original YACC input in F<perly.y>. (Yes, Virginia, there +B<is> a YACC grammar for Perl!) The job of the parser is to take your +code and `understand' it, splitting it into sentences, deciding which +operands go with which operators and so on. + +The parser is nobly assisted by the lexer, which chunks up your input +into tokens, and decides what type of thing each token is: a variable +name, an operator, a bareword, a subroutine, a core function, and so on. +The main point of entry to the lexer is C<yylex>, and that and its +associated routines can be found in F<toke.c>. Perl isn't much like +other computer languages; it's highly context sensitive at times, it can +be tricky to work out what sort of token something is, or where a token +ends. As such, there's a lot of interplay between the tokeniser and the +parser, which can get pretty frightening if you're not used to it. + +As the parser understands a Perl program, it builds up a tree of +operations for the interpreter to perform during execution. The routines +which construct and link together the various operations are to be found +in F<op.c>, and will be examined later. + +=item Optimization + +Now the parsing stage is complete, and the finished tree represents +the operations that the Perl interpreter needs to perform to execute our +program. Next, Perl does a dry run over the tree looking for +optimisations: constant expressions such as C<3 + 4> will be computed +now, and the optimizer will also see if any multiple operations can be +replaced with a single one. For instance, to fetch the variable C<$foo>, +instead of grabbing the glob C<*foo> and looking at the scalar +component, the optimizer fiddles the op tree to use a function which +directly looks up the scalar in question. The main optimizer is C<peep> +in F<op.c>, and many ops have their own optimizing functions. + +=item Running + +Now we're finally ready to go: we have compiled Perl byte code, and all +that's left to do is run it. The actual execution is done by the +C<runops_standard> function in F<run.c>; more specifically, it's done by +these three innocent looking lines: + + while ((PL_op = CALL_FPTR(PL_op->op_ppaddr)(aTHX))) { + PERL_ASYNC_CHECK(); + } + +You may be more comfortable with the Perl version of that: + + PERL_ASYNC_CHECK() while $Perl::op = &{$Perl::op->{function}}; + +Well, maybe not. Anyway, each op contains a function pointer, which +stipulates the function which will actually carry out the operation. +This function will return the next op in the sequence - this allows for +things like C<if> which choose the next op dynamically at run time. +The C<PERL_ASYNC_CHECK> makes sure that things like signals interrupt +execution if required. + +The actual functions called are known as PP code, and they're spread +between four files: F<pp_hot.c> contains the `hot' code, which is most +often used and highly optimized, F<pp_sys.c> contains all the +system-specific functions, F<pp_ctl.c> contains the functions which +implement control structures (C<if>, C<while> and the like) and F<pp.c> +contains everything else. These are, if you like, the C code for Perl's +built-in functions and operators. + +=back + +=head2 Internal Variable Types + +You should by now have had a look at L<perlguts>, which tells you about +Perl's internal variable types: SVs, HVs, AVs and the rest. If not, do +that now. + +These variables are used not only to represent Perl-space variables, but +also any constants in the code, as well as some structures completely +internal to Perl. The symbol table, for instance, is an ordinary Perl +hash. Your code is represented by an SV as it's read into the parser; +any program files you call are opened via ordinary Perl filehandles, and +so on. + +The core L<Devel::Peek|Devel::Peek> module lets us examine SVs from a +Perl program. Let's see, for instance, how Perl treats the constant +C<"hello">. + + % perl -MDevel::Peek -e 'Dump("hello")' + 1 SV = PV(0xa041450) at 0xa04ecbc + 2 REFCNT = 1 + 3 FLAGS = (POK,READONLY,pPOK) + 4 PV = 0xa0484e0 "hello"\0 + 5 CUR = 5 + 6 LEN = 6 + +Reading C<Devel::Peek> output takes a bit of practise, so let's go +through it line by line. + +Line 1 tells us we're looking at an SV which lives at C<0xa04ecbc> in +memory. SVs themselves are very simple structures, but they contain a +pointer to a more complex structure. In this case, it's a PV, a +structure which holds a string value, at location C<0xa041450>. Line 2 +is the reference count; there are no other references to this data, so +it's 1. + +Line 3 are the flags for this SV - it's OK to use it as a PV, it's a +read-only SV (because it's a constant) and the data is a PV internally. +Next we've got the contents of the string, starting at location +C<0xa0484e0>. + +Line 5 gives us the current length of the string - note that this does +B<not> include the null terminator. Line 6 is not the length of the +string, but the length of the currently allocated buffer; as the string +grows, Perl automatically extends the available storage via a routine +called C<SvGROW>. + +You can get at any of these quantities from C very easily; just add +C<Sv> to the name of the field shown in the snippet, and you've got a +macro which will return the value: C<SvCUR(sv)> returns the current +length of the string, C<SvREFCOUNT(sv)> returns the reference count, +C<SvPV(sv, len)> returns the string itself with its length, and so on. +More macros to manipulate these properties can be found in L<perlguts>. + +Let's take an example of manipulating a PV, from C<sv_catpvn>, in F<sv.c> + + 1 void + 2 Perl_sv_catpvn(pTHX_ register SV *sv, register const char *ptr, register STRLEN len) + 3 { + 4 STRLEN tlen; + 5 char *junk; + + 6 junk = SvPV_force(sv, tlen); + 7 SvGROW(sv, tlen + len + 1); + 8 if (ptr == junk) + 9 ptr = SvPVX(sv); + 10 Move(ptr,SvPVX(sv)+tlen,len,char); + 11 SvCUR(sv) += len; + 12 *SvEND(sv) = '\0'; + 13 (void)SvPOK_only_UTF8(sv); /* validate pointer */ + 14 SvTAINT(sv); + 15 } + +This is a function which adds a string, C<ptr>, of length C<len> onto +the end of the PV stored in C<sv>. The first thing we do in line 6 is +make sure that the SV B<has> a valid PV, by calling the C<SvPV_force> +macro to force a PV. As a side effect, C<tlen> gets set to the current +value of the PV, and the PV itself is returned to C<junk>. + +In line 7, we make sure that the SV will have enough room to accommodate +the old string, the new string and the null terminator. If C<LEN> isn't +big enough, C<SvGROW> will reallocate space for us. + +Now, if C<junk> is the same as the string we're trying to add, we can +grab the string directly from the SV; C<SvPVX> is the address of the PV +in the SV. + +Line 10 does the actual catenation: the C<Move> macro moves a chunk of +memory around: we move the string C<ptr> to the end of the PV - that's +the start of the PV plus its current length. We're moving C<len> bytes +of type C<char>. After doing so, we need to tell Perl we've extended the +string, by altering C<CUR> to reflect the new length. C<SvEND> is a +macro which gives us the end of the string, so that needs to be a +C<"\0">. + +Line 13 manipulates the flags; since we've changed the PV, any IV or NV +values will no longer be valid: if we have C<$a=10; $a.="6";> we don't +want to use the old IV of 10. C<SvPOK_only_utf8> is a special UTF8-aware +version of C<SvPOK_only>, a macro which turns off the IOK and NOK flags +and turns on POK. The final C<SvTAINT> is a macro which launders tainted +data if taint mode is turned on. + +AVs and HVs are more complicated, but SVs are by far the most common +variable type being thrown around. Having seen something of how we +manipulate these, let's go on and look at how the op tree is +constructed. + +=head2 Op Trees + +First, what is the op tree, anyway? The op tree is the parsed +representation of your program, as we saw in our section on parsing, and +it's the sequence of operations that Perl goes through to execute your +program, as we saw in L</Running>. + +An op is a fundamental operation that Perl can perform: all the built-in +functions and operators are ops, and there are a series of ops which +deal with concepts the interpreter needs internally - entering and +leaving a block, ending a statement, fetching a variable, and so on. + +The op tree is connected in two ways: you can imagine that there are two +"routes" through it, two orders in which you can traverse the tree. +First, parse order reflects how the parser understood the code, and +secondly, execution order tells perl what order to perform the +operations in. + +The easiest way to examine the op tree is to stop Perl after it has +finished parsing, and get it to dump out the tree. This is exactly what +the compiler backends L<B::Terse|B::Terse> and L<B::Debug|B::Debug> do. + +Let's have a look at how Perl sees C<$a = $b + $c>: + + % perl -MO=Terse -e '$a=$b+$c' + 1 LISTOP (0x8179888) leave + 2 OP (0x81798b0) enter + 3 COP (0x8179850) nextstate + 4 BINOP (0x8179828) sassign + 5 BINOP (0x8179800) add [1] + 6 UNOP (0x81796e0) null [15] + 7 SVOP (0x80fafe0) gvsv GV (0x80fa4cc) *b + 8 UNOP (0x81797e0) null [15] + 9 SVOP (0x8179700) gvsv GV (0x80efeb0) *c + 10 UNOP (0x816b4f0) null [15] + 11 SVOP (0x816dcf0) gvsv GV (0x80fa460) *a + +Let's start in the middle, at line 4. This is a BINOP, a binary +operator, which is at location C<0x8179828>. The specific operator in +question is C<sassign> - scalar assignment - and you can find the code +which implements it in the function C<pp_sassign> in F<pp_hot.c>. As a +binary operator, it has two children: the add operator, providing the +result of C<$b+$c>, is uppermost on line 5, and the left hand side is on +line 10. + +Line 10 is the null op: this does exactly nothing. What is that doing +there? If you see the null op, it's a sign that something has been +optimized away after parsing. As we mentioned in L</Optimization>, +the optimization stage sometimes converts two operations into one, for +example when fetching a scalar variable. When this happens, instead of +rewriting the op tree and cleaning up the dangling pointers, it's easier +just to replace the redundant operation with the null op. Originally, +the tree would have looked like this: + + 10 SVOP (0x816b4f0) rv2sv [15] + 11 SVOP (0x816dcf0) gv GV (0x80fa460) *a + +That is, fetch the C<a> entry from the main symbol table, and then look +at the scalar component of it: C<gvsv> (C<pp_gvsv> into F<pp_hot.c>) +happens to do both these things. + +The right hand side, starting at line 5 is similar to what we've just +seen: we have the C<add> op (C<pp_add> also in F<pp_hot.c>) add together +two C<gvsv>s. + +Now, what's this about? + + 1 LISTOP (0x8179888) leave + 2 OP (0x81798b0) enter + 3 COP (0x8179850) nextstate + +C<enter> and C<leave> are scoping ops, and their job is to perform any +housekeeping every time you enter and leave a block: lexical variables +are tidied up, unreferenced variables are destroyed, and so on. Every +program will have those first three lines: C<leave> is a list, and its +children are all the statements in the block. Statements are delimited +by C<nextstate>, so a block is a collection of C<nextstate> ops, with +the ops to be performed for each statement being the children of +C<nextstate>. C<enter> is a single op which functions as a marker. + +That's how Perl parsed the program, from top to bottom: + + Program + | + Statement + | + = + / \ + / \ + $a + + / \ + $b $c + +However, it's impossible to B<perform> the operations in this order: +you have to find the values of C<$b> and C<$c> before you add them +together, for instance. So, the other thread that runs through the op +tree is the execution order: each op has a field C<op_next> which points +to the next op to be run, so following these pointers tells us how perl +executes the code. We can traverse the tree in this order using +the C<exec> option to C<B::Terse>: + + % perl -MO=Terse,exec -e '$a=$b+$c' + 1 OP (0x8179928) enter + 2 COP (0x81798c8) nextstate + 3 SVOP (0x81796c8) gvsv GV (0x80fa4d4) *b + 4 SVOP (0x8179798) gvsv GV (0x80efeb0) *c + 5 BINOP (0x8179878) add [1] + 6 SVOP (0x816dd38) gvsv GV (0x80fa468) *a + 7 BINOP (0x81798a0) sassign + 8 LISTOP (0x8179900) leave + +This probably makes more sense for a human: enter a block, start a +statement. Get the values of C<$b> and C<$c>, and add them together. +Find C<$a>, and assign one to the other. Then leave. + +The way Perl builds up these op trees in the parsing process can be +unravelled by examining F<perly.y>, the YACC grammar. Let's take the +piece we need to construct the tree for C<$a = $b + $c> + + 1 term : term ASSIGNOP term + 2 { $$ = newASSIGNOP(OPf_STACKED, $1, $2, $3); } + 3 | term ADDOP term + 4 { $$ = newBINOP($2, 0, scalar($1), scalar($3)); } + +If you're not used to reading BNF grammars, this is how it works: You're +fed certain things by the tokeniser, which generally end up in upper +case. Here, C<ADDOP>, is provided when the tokeniser sees C<+> in your +code. C<ASSIGNOP> is provided when C<=> is used for assigning. These are +`terminal symbols', because you can't get any simpler than them. + +The grammar, lines one and three of the snippet above, tells you how to +build up more complex forms. These complex forms, `non-terminal symbols' +are generally placed in lower case. C<term> here is a non-terminal +symbol, representing a single expression. + +The grammar gives you the following rule: you can make the thing on the +left of the colon if you see all the things on the right in sequence. +This is called a "reduction", and the aim of parsing is to completely +reduce the input. There are several different ways you can perform a +reduction, separated by vertical bars: so, C<term> followed by C<=> +followed by C<term> makes a C<term>, and C<term> followed by C<+> +followed by C<term> can also make a C<term>. + +So, if you see two terms with an C<=> or C<+>, between them, you can +turn them into a single expression. When you do this, you execute the +code in the block on the next line: if you see C<=>, you'll do the code +in line 2. If you see C<+>, you'll do the code in line 4. It's this code +which contributes to the op tree. + + | term ADDOP term + { $$ = newBINOP($2, 0, scalar($1), scalar($3)); } + +What this does is creates a new binary op, and feeds it a number of +variables. The variables refer to the tokens: C<$1> is the first token in +the input, C<$2> the second, and so on - think regular expression +backreferences. C<$$> is the op returned from this reduction. So, we +call C<newBINOP> to create a new binary operator. The first parameter to +C<newBINOP>, a function in F<op.c>, is the op type. It's an addition +operator, so we want the type to be C<ADDOP>. We could specify this +directly, but it's right there as the second token in the input, so we +use C<$2>. The second parameter is the op's flags: 0 means `nothing +special'. Then the things to add: the left and right hand side of our +expression, in scalar context. + +=head2 Stacks + +When perl executes something like C<addop>, how does it pass on its +results to the next op? The answer is, through the use of stacks. Perl +has a number of stacks to store things it's currently working on, and +we'll look at the three most important ones here. + +=over 3 + +=item Argument stack + +Arguments are passed to PP code and returned from PP code using the +argument stack, C<ST>. The typical way to handle arguments is to pop +them off the stack, deal with them how you wish, and then push the result +back onto the stack. This is how, for instance, the cosine operator +works: + + NV value; + value = POPn; + value = Perl_cos(value); + XPUSHn(value); + +We'll see a more tricky example of this when we consider Perl's macros +below. C<POPn> gives you the NV (floating point value) of the top SV on +the stack: the C<$x> in C<cos($x)>. Then we compute the cosine, and push +the result back as an NV. The C<X> in C<XPUSHn> means that the stack +should be extended if necessary - it can't be necessary here, because we +know there's room for one more item on the stack, since we've just +removed one! The C<XPUSH*> macros at least guarantee safety. + +Alternatively, you can fiddle with the stack directly: C<SP> gives you +the first element in your portion of the stack, and C<TOP*> gives you +the top SV/IV/NV/etc. on the stack. So, for instance, to do unary +negation of an integer: + + SETi(-TOPi); + +Just set the integer value of the top stack entry to its negation. + +Argument stack manipulation in the core is exactly the same as it is in +XSUBs - see L<perlxstut>, L<perlxs> and L<perlguts> for a longer +description of the macros used in stack manipulation. + +=item Mark stack + +I say `your portion of the stack' above because PP code doesn't +necessarily get the whole stack to itself: if your function calls +another function, you'll only want to expose the arguments aimed for the +called function, and not (necessarily) let it get at your own data. The +way we do this is to have a `virtual' bottom-of-stack, exposed to each +function. The mark stack keeps bookmarks to locations in the argument +stack usable by each function. For instance, when dealing with a tied +variable, (internally, something with `P' magic) Perl has to call +methods for accesses to the tied variables. However, we need to separate +the arguments exposed to the method to the argument exposed to the +original function - the store or fetch or whatever it may be. Here's how +the tied C<push> is implemented; see C<av_push> in F<av.c>: + + 1 PUSHMARK(SP); + 2 EXTEND(SP,2); + 3 PUSHs(SvTIED_obj((SV*)av, mg)); + 4 PUSHs(val); + 5 PUTBACK; + 6 ENTER; + 7 call_method("PUSH", G_SCALAR|G_DISCARD); + 8 LEAVE; + 9 POPSTACK; + +The lines which concern the mark stack are the first, fifth and last +lines: they save away, restore and remove the current position of the +argument stack. + +Let's examine the whole implementation, for practice: + + 1 PUSHMARK(SP); + +Push the current state of the stack pointer onto the mark stack. This is +so that when we've finished adding items to the argument stack, Perl +knows how many things we've added recently. + + 2 EXTEND(SP,2); + 3 PUSHs(SvTIED_obj((SV*)av, mg)); + 4 PUSHs(val); + +We're going to add two more items onto the argument stack: when you have +a tied array, the C<PUSH> subroutine receives the object and the value +to be pushed, and that's exactly what we have here - the tied object, +retrieved with C<SvTIED_obj>, and the value, the SV C<val>. + + 5 PUTBACK; + +Next we tell Perl to make the change to the global stack pointer: C<dSP> +only gave us a local copy, not a reference to the global. + + 6 ENTER; + 7 call_method("PUSH", G_SCALAR|G_DISCARD); + 8 LEAVE; + +C<ENTER> and C<LEAVE> localise a block of code - they make sure that all +variables are tidied up, everything that has been localised gets +its previous value returned, and so on. Think of them as the C<{> and +C<}> of a Perl block. + +To actually do the magic method call, we have to call a subroutine in +Perl space: C<call_method> takes care of that, and it's described in +L<perlcall>. We call the C<PUSH> method in scalar context, and we're +going to discard its return value. + + 9 POPSTACK; + +Finally, we remove the value we placed on the mark stack, since we +don't need it any more. + +=item Save stack + +C doesn't have a concept of local scope, so perl provides one. We've +seen that C<ENTER> and C<LEAVE> are used as scoping braces; the save +stack implements the C equivalent of, for example: + + { + local $foo = 42; + ... + } + +See L<perlguts/Localising Changes> for how to use the save stack. + +=back + +=head2 Millions of Macros + +One thing you'll notice about the Perl source is that it's full of +macros. Some have called the pervasive use of macros the hardest thing +to understand, others find it adds to clarity. Let's take an example, +the code which implements the addition operator: + + 1 PP(pp_add) + 2 { + 3 dSP; dATARGET; tryAMAGICbin(add,opASSIGN); + 4 { + 5 dPOPTOPnnrl_ul; + 6 SETn( left + right ); + 7 RETURN; + 8 } + 9 } + +Every line here (apart from the braces, of course) contains a macro. The +first line sets up the function declaration as Perl expects for PP code; +line 3 sets up variable declarations for the argument stack and the +target, the return value of the operation. Finally, it tries to see if +the addition operation is overloaded; if so, the appropriate subroutine +is called. + +Line 5 is another variable declaration - all variable declarations start +with C<d> - which pops from the top of the argument stack two NVs (hence +C<nn>) and puts them into the variables C<right> and C<left>, hence the +C<rl>. These are the two operands to the addition operator. Next, we +call C<SETn> to set the NV of the return value to the result of adding +the two values. This done, we return - the C<RETURN> macro makes sure +that our return value is properly handled, and we pass the next operator +to run back to the main run loop. + +Most of these macros are explained in L<perlapi>, and some of the more +important ones are explained in L<perlxs> as well. Pay special attention +to L<perlguts/Background and PERL_IMPLICIT_CONTEXT> for information on +the C<[pad]THX_?> macros. + + +=head2 Poking at Perl + +To really poke around with Perl, you'll probably want to build Perl for +debugging, like this: + + ./Configure -d -D optimize=-g + make + +C<-g> is a flag to the C compiler to have it produce debugging +information which will allow us to step through a running program. +F<Configure> will also turn on the C<DEBUGGING> compilation symbol which +enables all the internal debugging code in Perl. There are a whole bunch +of things you can debug with this: L<perlrun> lists them all, and the +best way to find out about them is to play about with them. The most +useful options are probably + + l Context (loop) stack processing + t Trace execution + o Method and overloading resolution + c String/numeric conversions + +Some of the functionality of the debugging code can be achieved using XS +modules. + + -Dr => use re 'debug' + -Dx => use O 'Debug' + +=head2 Using a source-level debugger + +If the debugging output of C<-D> doesn't help you, it's time to step +through perl's execution with a source-level debugger. + +=over 3 + +=item * + +We'll use C<gdb> for our examples here; the principles will apply to any +debugger, but check the manual of the one you're using. + +=back + +To fire up the debugger, type + + gdb ./perl + +You'll want to do that in your Perl source tree so the debugger can read +the source code. You should see the copyright message, followed by the +prompt. + + (gdb) + +C<help> will get you into the documentation, but here are the most +useful commands: + +=over 3 + +=item run [args] + +Run the program with the given arguments. + +=item break function_name + +=item break source.c:xxx + +Tells the debugger that we'll want to pause execution when we reach +either the named function (but see L<perlguts/Internal Functions>!) or the given +line in the named source file. + +=item step + +Steps through the program a line at a time. + +=item next + +Steps through the program a line at a time, without descending into +functions. + +=item continue + +Run until the next breakpoint. + +=item finish + +Run until the end of the current function, then stop again. + +=item 'enter' + +Just pressing Enter will do the most recent operation again - it's a +blessing when stepping through miles of source code. + +=item print + +Execute the given C code and print its results. B<WARNING>: Perl makes +heavy use of macros, and F<gdb> is not aware of macros. You'll have to +substitute them yourself. So, for instance, you can't say + + print SvPV_nolen(sv) + +but you have to say + + print Perl_sv_2pv_nolen(sv) + +You may find it helpful to have a "macro dictionary", which you can +produce by saying C<cpp -dM perl.c | sort>. Even then, F<cpp> won't +recursively apply the macros for you. + +=back + +=head2 Dumping Perl Data Structures + +One way to get around this macro hell is to use the dumping functions in +F<dump.c>; these work a little like an internal +L<Devel::Peek|Devel::Peek>, but they also cover OPs and other structures +that you can't get at from Perl. Let's take an example. We'll use the +C<$a = $b + $c> we used before, but give it a bit of context: +C<$b = "6XXXX"; $c = 2.3;>. Where's a good place to stop and poke around? + +What about C<pp_add>, the function we examined earlier to implement the +C<+> operator: + + (gdb) break Perl_pp_add + Breakpoint 1 at 0x46249f: file pp_hot.c, line 309. + +Notice we use C<Perl_pp_add> and not C<pp_add> - see L<perlguts/Internal Functions>. +With the breakpoint in place, we can run our program: + + (gdb) run -e '$b = "6XXXX"; $c = 2.3; $a = $b + $c' + +Lots of junk will go past as gdb reads in the relevant source files and +libraries, and then: + + Breakpoint 1, Perl_pp_add () at pp_hot.c:309 + 309 dSP; dATARGET; tryAMAGICbin(add,opASSIGN); + (gdb) step + 311 dPOPTOPnnrl_ul; + (gdb) + +We looked at this bit of code before, and we said that C<dPOPTOPnnrl_ul> +arranges for two C<NV>s to be placed into C<left> and C<right> - let's +slightly expand it: + + #define dPOPTOPnnrl_ul NV right = POPn; \ + SV *leftsv = TOPs; \ + NV left = USE_LEFT(leftsv) ? SvNV(leftsv) : 0.0 + +C<POPn> takes the SV from the top of the stack and obtains its NV either +directly (if C<SvNOK> is set) or by calling the C<sv_2nv> function. +C<TOPs> takes the next SV from the top of the stack - yes, C<POPn> uses +C<TOPs> - but doesn't remove it. We then use C<SvNV> to get the NV from +C<leftsv> in the same way as before - yes, C<POPn> uses C<SvNV>. + +Since we don't have an NV for C<$b>, we'll have to use C<sv_2nv> to +convert it. If we step again, we'll find ourselves there: + + Perl_sv_2nv (sv=0xa0675d0) at sv.c:1669 + 1669 if (!sv) + (gdb) + +We can now use C<Perl_sv_dump> to investigate the SV: + + SV = PV(0xa057cc0) at 0xa0675d0 + REFCNT = 1 + FLAGS = (POK,pPOK) + PV = 0xa06a510 "6XXXX"\0 + CUR = 5 + LEN = 6 + $1 = void + +We know we're going to get C<6> from this, so let's finish the +subroutine: + + (gdb) finish + Run till exit from #0 Perl_sv_2nv (sv=0xa0675d0) at sv.c:1671 + 0x462669 in Perl_pp_add () at pp_hot.c:311 + 311 dPOPTOPnnrl_ul; + +We can also dump out this op: the current op is always stored in +C<PL_op>, and we can dump it with C<Perl_op_dump>. This'll give us +similar output to L<B::Debug|B::Debug>. + + { + 13 TYPE = add ===> 14 + TARG = 1 + FLAGS = (SCALAR,KIDS) + { + TYPE = null ===> (12) + (was rv2sv) + FLAGS = (SCALAR,KIDS) + { + 11 TYPE = gvsv ===> 12 + FLAGS = (SCALAR) + GV = main::b + } + } + +< finish this later > + +=head2 Patching + +All right, we've now had a look at how to navigate the Perl sources and +some things you'll need to know when fiddling with them. Let's now get +on and create a simple patch. Here's something Larry suggested: if a +C<U> is the first active format during a C<pack>, (for example, +C<pack "U3C8", @stuff>) then the resulting string should be treated as +UTF8 encoded. + +How do we prepare to fix this up? First we locate the code in question - +the C<pack> happens at runtime, so it's going to be in one of the F<pp> +files. Sure enough, C<pp_pack> is in F<pp.c>. Since we're going to be +altering this file, let's copy it to F<pp.c~>. + +Now let's look over C<pp_pack>: we take a pattern into C<pat>, and then +loop over the pattern, taking each format character in turn into +C<datum_type>. Then for each possible format character, we swallow up +the other arguments in the pattern (a field width, an asterisk, and so +on) and convert the next chunk input into the specified format, adding +it onto the output SV C<cat>. + +How do we know if the C<U> is the first format in the C<pat>? Well, if +we have a pointer to the start of C<pat> then, if we see a C<U> we can +test whether we're still at the start of the string. So, here's where +C<pat> is set up: + + STRLEN fromlen; + register char *pat = SvPVx(*++MARK, fromlen); + register char *patend = pat + fromlen; + register I32 len; + I32 datumtype; + SV *fromstr; + +We'll have another string pointer in there: + + STRLEN fromlen; + register char *pat = SvPVx(*++MARK, fromlen); + register char *patend = pat + fromlen; + + char *patcopy; + register I32 len; + I32 datumtype; + SV *fromstr; + +And just before we start the loop, we'll set C<patcopy> to be the start +of C<pat>: + + items = SP - MARK; + MARK++; + sv_setpvn(cat, "", 0); + + patcopy = pat; + while (pat < patend) { + +Now if we see a C<U> which was at the start of the string, we turn on +the UTF8 flag for the output SV, C<cat>: + + + if (datumtype == 'U' && pat==patcopy+1) + + SvUTF8_on(cat); + if (datumtype == '#') { + while (pat < patend && *pat != '\n') + pat++; + +Remember that it has to be C<patcopy+1> because the first character of +the string is the C<U> which has been swallowed into C<datumtype!> + +Oops, we forgot one thing: what if there are spaces at the start of the +pattern? C<pack(" U*", @stuff)> will have C<U> as the first active +character, even though it's not the first thing in the pattern. In this +case, we have to advance C<patcopy> along with C<pat> when we see spaces: + + if (isSPACE(datumtype)) + continue; + +needs to become + + if (isSPACE(datumtype)) { + patcopy++; + continue; + } + +OK. That's the C part done. Now we must do two additional things before +this patch is ready to go: we've changed the behaviour of Perl, and so +we must document that change. We must also provide some more regression +tests to make sure our patch works and doesn't create a bug somewhere +else along the line. + +The regression tests for each operator live in F<t/op/>, and so we make +a copy of F<t/op/pack.t> to F<t/op/pack.t~>. Now we can add our tests +to the end. First, we'll test that the C<U> does indeed create Unicode +strings: + + print 'not ' unless "1.20.300.4000" eq sprintf "%vd", pack("U*",1,20,300,4000); + print "ok $test\n"; $test++; + +Now we'll test that we got that space-at-the-beginning business right: + + print 'not ' unless "1.20.300.4000" eq + sprintf "%vd", pack(" U*",1,20,300,4000); + print "ok $test\n"; $test++; + +And finally we'll test that we don't make Unicode strings if C<U> is B<not> +the first active format: + + print 'not ' unless v1.20.300.4000 ne + sprintf "%vd", pack("C0U*",1,20,300,4000); + print "ok $test\n"; $test++; + +Mustn't forget to change the number of tests which appears at the top, or +else the automated tester will get confused: + + -print "1..156\n"; + +print "1..159\n"; + +We now compile up Perl, and run it through the test suite. Our new +tests pass, hooray! + +Finally, the documentation. The job is never done until the paperwork is +over, so let's describe the change we've just made. The relevant place +is F<pod/perlfunc.pod>; again, we make a copy, and then we'll insert +this text in the description of C<pack>: + + =item * + + If the pattern begins with a C<U>, the resulting string will be treated + as Unicode-encoded. You can force UTF8 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 UTF8 encode your + string, and then follow this with a C<U*> somewhere in your pattern. + +All done. Now let's create the patch. F<Porting/patching.pod> tells us +that if we're making major changes, we should copy the entire directory +to somewhere safe before we begin fiddling, and then do + + diff -ruN old new > patch + +However, we know which files we've changed, and we can simply do this: + + diff -u pp.c~ pp.c > patch + diff -u t/op/pack.t~ t/op/pack.t >> patch + diff -u pod/perlfunc.pod~ pod/perlfunc.pod >> patch + +We end up with a patch looking a little like this: + + --- pp.c~ Fri Jun 02 04:34:10 2000 + +++ pp.c Fri Jun 16 11:37:25 2000 + @@ -4375,6 +4375,7 @@ + register I32 items; + STRLEN fromlen; + register char *pat = SvPVx(*++MARK, fromlen); + + char *patcopy; + register char *patend = pat + fromlen; + register I32 len; + I32 datumtype; + @@ -4405,6 +4406,7 @@ + ... + +And finally, we submit it, with our rationale, to perl5-porters. Job +done! + +=head1 EXTERNAL TOOLS FOR DEBUGGING PERL + +Sometimes it helps to use external tools while debugging and +testing Perl. This section tries to guide you through using +some common testing and debugging tools with Perl. This is +meant as a guide to interfacing these tools with Perl, not +as any kind of guide to the use of the tools themselves. + +=head2 Rational Software's Purify + +Purify is a commercial tool that is helpful in identifying +memory overruns, wild pointers, memory leaks and other such +badness. Perl must be compiled in a specific way for +optimal testing with Purify. Purify is available under +Windows NT, Solaris, HP-UX, SGI, and Siemens Unix. + +The only currently known leaks happen when there are +compile-time errors within eval or require. (Fixing these +is non-trivial, unfortunately, but they must be fixed +eventually.) + +=head2 Purify on Unix + +On Unix, Purify creates a new Perl binary. To get the most +benefit out of Purify, you should create the perl to Purify +using: + + sh Configure -Accflags=-DPURIFY -Doptimize='-g' \ + -Uusemymalloc -Dusemultiplicity + +where these arguments mean: + +=over 4 + +=item -Accflags=-DPURIFY + +Disables Perl's arena memory allocation functions, as well as +forcing use of memory allocation functions derived from the +system malloc. + +=item -Doptimize='-g' + +Adds debugging information so that you see the exact source +statements where the problem occurs. Without this flag, all +you will see is the source filename of where the error occurred. + +=item -Uusemymalloc + +Disable Perl's malloc so that Purify can more closely monitor +allocations and leaks. Using Perl's malloc will make Purify +report most leaks in the "potential" leaks category. + +=item -Dusemultiplicity + +Enabling the multiplicity option allows perl to clean up +thoroughly when the interpreter shuts down, which reduces the +number of bogus leak reports from Purify. + +=back + +Once you've compiled a perl suitable for Purify'ing, then you +can just: + + make pureperl + +which creates a binary named 'pureperl' that has been Purify'ed. +This binary is used in place of the standard 'perl' binary +when you want to debug Perl memory problems. + +As an example, to show any memory leaks produced during the +standard Perl testset you would create and run the Purify'ed +perl as: + + make pureperl + cd t + ../pureperl -I../lib harness + +which would run Perl on test.pl and report any memory problems. + +Purify outputs messages in "Viewer" windows by default. If +you don't have a windowing environment or if you simply +want the Purify output to unobtrusively go to a log file +instead of to the interactive window, use these following +options to output to the log file "perl.log": + + setenv PURIFYOPTIONS "-chain-length=25 -windows=no \ + -log-file=perl.log -append-logfile=yes" + +If you plan to use the "Viewer" windows, then you only need this option: + + setenv PURIFYOPTIONS "-chain-length=25" + +=head2 Purify on NT + +Purify on Windows NT instruments the Perl binary 'perl.exe' +on the fly. There are several options in the makefile you +should change to get the most use out of Purify: + +=over 4 + +=item DEFINES + +You should add -DPURIFY to the DEFINES line so the DEFINES +line looks something like: + + DEFINES = -DWIN32 -D_CONSOLE -DNO_STRICT $(CRYPT_FLAG) -DPURIFY=1 + +to disable Perl's arena memory allocation functions, as +well as to force use of memory allocation functions derived +from the system malloc. + +=item USE_MULTI = define + +Enabling the multiplicity option allows perl to clean up +thoroughly when the interpreter shuts down, which reduces the +number of bogus leak reports from Purify. + +=item #PERL_MALLOC = define + +Disable Perl's malloc so that Purify can more closely monitor +allocations and leaks. Using Perl's malloc will make Purify +report most leaks in the "potential" leaks category. + +=item CFG = Debug + +Adds debugging information so that you see the exact source +statements where the problem occurs. Without this flag, all +you will see is the source filename of where the error occurred. + +=back + +As an example, to show any memory leaks produced during the +standard Perl testset you would create and run Purify as: + + cd win32 + make + cd ../t + purify ../perl -I../lib harness + +which would instrument Perl in memory, run Perl on test.pl, +then finally report any memory problems. + +=head2 CONCLUSION + +We've had a brief look around the Perl source, an overview of the stages +F<perl> goes through when it's running your code, and how to use a +debugger to poke at the Perl guts. We took a very simple problem and +demonstrated how to solve it fully - with documentation, regression +tests, and finally a patch for submission to p5p. Finally, we talked +about how to use external tools to debug and test Perl. + +I'd now suggest you read over those references again, and then, as soon +as possible, get your hands dirty. The best way to learn is by doing, +so: + +=over 3 + +=item * + +Subscribe to perl5-porters, follow the patches and try and understand +them; don't be afraid to ask if there's a portion you're not clear on - +who knows, you may unearth a bug in the patch... + +=item * + +Keep up to date with the bleeding edge Perl distributions and get +familiar with the changes. Try and get an idea of what areas people are +working on and the changes they're making. + +=item * + +Do read the README associated with your operating system, e.g. README.aix +on the IBM AIX OS. Don't hesitate to supply patches to that README if +you find anything missing or changed over a new OS release. + +=item * + +Find an area of Perl that seems interesting to you, and see if you can +work out how it works. Scan through the source, and step over it in the +debugger. Play, poke, investigate, fiddle! You'll probably get to +understand not just your chosen area but a much wider range of F<perl>'s +activity as well, and probably sooner than you'd think. + +=back + +=over 3 + +=item I<The Road goes ever on and on, down from the door where it began.> + +=back + +If you can do these things, you've started on the long road to Perl porting. +Thanks for wanting to help make Perl better - and happy hacking! + =head1 AUTHOR This document was written by Nathan Torkington, and is maintained by diff --git a/contrib/perl5/pod/perlhist.pod b/contrib/perl5/pod/perlhist.pod index 4311ee28137c..914c9639ed43 100644 --- a/contrib/perl5/pod/perlhist.pod +++ b/contrib/perl5/pod/perlhist.pod @@ -1,5 +1,3 @@ -=pod - =head1 NAME perlhist - the Perl history records @@ -36,7 +34,7 @@ Perl history in brief, by Larry Wall: Larry Wall, Andy Dougherty, Tom Christiansen, Charles Bailey, Nick Ing-Simmons, Chip Salzenberg, Tim Bunce, Malcolm Beattie, Gurusamy -Sarathy, Graham Barr. +Sarathy, Graham Barr, Jarkko Hietaniemi. =head2 PUMPKIN? @@ -341,6 +339,14 @@ the strings?). 5.6.0-RC3 2000-Mar-21 release candidate 3 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 + + Jarkko 5.7.0 2000-Sep-02 The 5.7 track: Development. + =head2 SELECTED RELEASE SIZES For example the notation "core: 212 29" in the release 1.000 means that diff --git a/contrib/perl5/pod/perlintern.pod b/contrib/perl5/pod/perlintern.pod index 58eeac6e954c..e50be288287e 100644 --- a/contrib/perl5/pod/perlintern.pod +++ b/contrib/perl5/pod/perlintern.pod @@ -6,17 +6,111 @@ perlintern - autogenerated documentation of purely B<internal> =head1 DESCRIPTION This file is the autogenerated documentation of functions in the -Perl intrepreter that are documented using Perl's internal documentation +Perl interpreter that are documented using Perl's internal documentation format but are not marked as part of the Perl API. In other words, B<they are not for use in extensions>! =over 8 +=item is_gv_magical + +Returns C<TRUE> if given the name of a magical GV. + +Currently only useful internally when determining if a GV should be +created even in rvalue contexts. + +C<flags> is not used at present but available for future extension to +allow selecting particular classes of magical variable. + + bool is_gv_magical(char *name, STRLEN len, U32 flags) + +=for hackers +Found in file gv.c + +=item LVRET + +True if this op will be the return value of an lvalue subroutine + +=for hackers +Found in file pp.h + +=item PL_DBsingle + +When Perl is run in debugging mode, with the B<-d> switch, this SV is a +boolean which indicates whether subs are being single-stepped. +Single-stepping is automatically turned on after every step. This is the C +variable which corresponds to Perl's $DB::single variable. See +C<PL_DBsub>. + + SV * PL_DBsingle + +=for hackers +Found in file intrpvar.h + +=item PL_DBsub + +When Perl is run in debugging mode, with the B<-d> switch, this GV contains +the SV which holds the name of the sub being debugged. This is the C +variable which corresponds to Perl's $DB::sub variable. See +C<PL_DBsingle>. + + GV * PL_DBsub + +=for hackers +Found in file intrpvar.h + +=item PL_DBtrace + +Trace variable used when Perl is run in debugging mode, with the B<-d> +switch. This is the C variable which corresponds to Perl's $DB::trace +variable. See C<PL_DBsingle>. + + SV * PL_DBtrace + +=for hackers +Found in file intrpvar.h + +=item PL_dowarn + +The C variable which corresponds to Perl's $^W warning variable. + + bool PL_dowarn + +=for hackers +Found in file intrpvar.h + +=item PL_last_in_gv + +The GV which was last used for a filehandle input operation. (C<< <FH> >>) + + GV* PL_last_in_gv + +=for hackers +Found in file thrdvar.h + +=item PL_ofs_sv + +The output field separator - C<$,> in Perl space. + + SV* PL_ofs_sv + +=for hackers +Found in file thrdvar.h + +=item PL_rs + +The input record separator - C<$/> in Perl space. + + SV* PL_rs + +=for hackers +Found in file thrdvar.h + =back =head1 AUTHORS -The autodocumentation system was orignally added to the Perl core by +The autodocumentation system was originally added to the Perl core by Benjamin Stuhl. Documentation is by whoever was kind enough to document their functions. diff --git a/contrib/perl5/pod/perlipc.pod b/contrib/perl5/pod/perlipc.pod index 87602578218d..a1df3e42e015 100644 --- a/contrib/perl5/pod/perlipc.pod +++ b/contrib/perl5/pod/perlipc.pod @@ -234,8 +234,7 @@ prepared to clean up core dumps now and again. To forbid signal handlers altogether would bars you from many interesting programs, including virtually everything in this manpage, -since you could no longer even write SIGCHLD handlers. Their dodginess -is expected to be addresses in the 5.005 release. +since you could no longer even write SIGCHLD handlers. =head1 Using open() for IPC @@ -661,13 +660,14 @@ instead. BEGIN { $ENV{PATH} = '/usr/ucb:/bin' } use Socket; use Carp; - $EOL = "\015\012"; + my $EOL = "\015\012"; sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" } my $port = shift || 2345; my $proto = getprotobyname('tcp'); - $port = $1 if $port =~ /(\d+)/; # untaint port number + + ($port) = $port =~ /^(\d+)$/ or die "invalid port"; socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, @@ -703,14 +703,15 @@ go back to service a new client. BEGIN { $ENV{PATH} = '/usr/ucb:/bin' } use Socket; use Carp; - $EOL = "\015\012"; + my $EOL = "\015\012"; sub spawn; # forward declaration sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" } my $port = shift || 2345; my $proto = getprotobyname('tcp'); - $port = $1 if $port =~ /(\d+)/; # untaint port number + + ($port) = $port =~ /^(\d+)$/ or die "invalid port"; socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!"; setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, @@ -744,6 +745,7 @@ go back to service a new client. at port $port"; spawn sub { + $|=1; print "Hello there, $name, it's now ", scalar localtime, $EOL; exec '/usr/games/fortune' # XXX: `wrong' line terminators or confess "can't exec fortune: $!"; @@ -835,7 +837,7 @@ domain sockets can show up in the file system with an ls(1) listing. You can test for these with Perl's B<-S> file test: unless ( -S '/dev/log' ) { - die "something's wicked with the print system"; + die "something's wicked with the log system"; } Here's a sample Unix-domain client: @@ -863,6 +865,7 @@ to be on the localhost, and thus everything works right. use Carp; BEGIN { $ENV{PATH} = '/usr/ucb:/bin' } + sub spawn; # forward declaration sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" } my $NAME = '/tmp/catsock'; @@ -899,6 +902,29 @@ to be on the localhost, and thus everything works right. }; } + sub spawn { + my $coderef = shift; + + unless (@_ == 0 && $coderef && ref($coderef) eq 'CODE') { + confess "usage: spawn CODEREF"; + } + + my $pid; + if (!defined($pid = fork)) { + logmsg "cannot fork: $!"; + return; + } elsif ($pid) { + logmsg "begat $pid"; + return; # I'm the parent + } + # else I'm the child -- go spawn + + open(STDIN, "<&Client") || die "can't dup client to stdin"; + open(STDOUT, ">&Client") || die "can't dup client to stdout"; + ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr"; + exit &$coderef(); + } + As you see, it's remarkably similar to the Internet domain TCP server, so much so, in fact, that we've omitted several duplicate functions--spawn(), logmsg(), ctime(), and REAPER()--which are exactly the same as in the @@ -922,7 +948,7 @@ For those preferring a higher-level interface to socket programming, the IO::Socket module provides an object-oriented approach. IO::Socket is included as part of the standard Perl distribution as of the 5.004 release. If you're running an earlier version of Perl, just fetch -IO::Socket from CPAN, where you'll also find find modules providing easy +IO::Socket from CPAN, where you'll also find modules providing easy interfaces to the following systems: DNS, FTP, Ident (RFC 931), NIS and NISPlus, NNTP, Ping, POP3, SMTP, SNMP, SSLeay, Telnet, and Time--just to name a few. @@ -950,7 +976,7 @@ looks like this: Here are what those parameters to the C<new> constructor mean: -=over +=over 4 =item C<Proto> @@ -1022,7 +1048,7 @@ something to the server before fetching the server's response. } The web server handing the "http" service, which is assumed to be at -its standard port, number 80. If your the web server you're trying to +its standard port, number 80. If the web server you're trying to connect to is at a different port (like 1080 or 8080), you should specify as the named-parameter pair, C<< PeerPort => 8080 >>. The C<autoflush> method is used on the socket because otherwise the system would buffer @@ -1145,7 +1171,7 @@ does nothing but listen on a particular port for incoming connections. It does this by calling the C<< IO::Socket::INET->new() >> method with slightly different arguments than the client did. -=over +=over 4 =item Proto @@ -1245,6 +1271,11 @@ find yourself overly concerned about reliability and start building checks into your message system, then you probably should use just TCP to start with. +Note that UDP datagrams are I<not> a bytestream and should not be treated +as such. This makes using I/O mechanisms with internal buffering +like stdio (i.e. print() and friends) especially cumbersome. Use syswrite(), +or better send(), like in the example below. + 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 @@ -1295,6 +1326,11 @@ with TCP, you'd have to use a different socket handle for each host. $count--; } +Note that this example does not include any retries and may consequently +fail to contact a reachable host. The most prominent reason for this +is congestion of the queues on the sending host if the number of +list of hosts to contact is sufficiently large. + =head1 SysV IPC While System V IPC isn't so widely used as sockets, it still has some diff --git a/contrib/perl5/pod/perllexwarn.pod b/contrib/perl5/pod/perllexwarn.pod index cee16875377f..951a470b2e59 100644 --- a/contrib/perl5/pod/perllexwarn.pod +++ b/contrib/perl5/pod/perllexwarn.pod @@ -9,7 +9,7 @@ flag B<-w> and the equivalent Perl variable, C<$^W>. The pragma works just like the existing "strict" pragma. This means that the scope of the warning pragma is limited to the -enclosing block. It also means that that the pragma setting will not +enclosing block. It also means that the pragma setting will not leak across files (via C<use>, C<require> or C<do>). This allows authors to independently define the degree of warning checks that will be applied to their module. @@ -30,18 +30,17 @@ Similarly all warnings are disabled in a block by either of these: For example, consider the code below: use warnings ; - my $a ; - my $b ; + my @a ; { no warnings ; - $b = 2 if $a EQ 3 ; + my $b = @a[0] ; } - $b = 1 if $a NE 3 ; + my $c = @a[0]; The code in the enclosing block has warnings enabled, but the inner -block has them disabled. In this case that means that the use of the C<EQ> -operator won't trip a C<"Use of EQ is deprecated"> warning, but the use of -C<NE> will produce a C<"Use of NE is deprecated"> warning. +block has them disabled. In this case that means the assignment to the +scalar C<$c> will trip the C<"Scalar value @a[0] better written as $a[0]"> +warning, but the assignment to the scalar C<$b> will not. =head2 Default Warnings and Optional Warnings @@ -100,7 +99,7 @@ disable compile-time warnings you need to rewrite the code like this: my $b ; chop $b ; } -The other big problem with C<$^W> is that way you can inadvertently +The other big problem with C<$^W> is the way you can inadvertently change the warning setting in unexpected places in your code. For example, when the code below is run (without the B<-w> flag), the second call to C<doit> will trip a C<"Use of uninitialized value"> warning, whereas @@ -195,7 +194,7 @@ or B<-X> command line flags. =back -The combined effect of 3 & 4 is that it will will allow code which uses +The combined effect of 3 & 4 is that it will allow code which uses the C<warnings> pragma to control the warning behavior of $^W-type code (using a C<local $^W=0>) if it really wants to, but not vice-versa. @@ -321,27 +320,38 @@ L<perldiag>. The presence of the word "FATAL" in the category list will escalate any warnings detected from the categories specified in the lexical scope -into fatal errors. In the code below, there are 3 places where a -deprecated warning will be detected, the middle one will produce a -fatal error. - +into fatal errors. In the code below, the use of C<time>, C<length> +and C<join> can all produce a C<"Useless use of xxx in void context"> +warning. use warnings ; - $a = 1 if $a EQ $b ; + time ; { - use warnings FATAL => qw(deprecated) ; - $a = 1 if $a EQ $b ; + use warnings FATAL => qw(void) ; + length "abc" ; } - $a = 1 if $a EQ $b ; + join "", 1,2,3 ; + + print "done\n" ; + +When run it produces this output + + Useless use of time in void context at fatal line 3. + Useless use of length in void context at fatal line 7. + +The scope where C<length> is used has escalated the C<void> warnings +category into a fatal error, so the program terminates immediately it +encounters the warning. + =head2 Reporting Warnings from a Module The C<warnings> pragma provides a number of functions that are useful for module authors. These are used when you want to report a module-specific -warning when the calling module has enabled warnings via the C<warnings> +warning to a calling module has enabled warnings via the C<warnings> pragma. Consider the module C<MyMod::Abc> below. @@ -361,11 +371,11 @@ Consider the module C<MyMod::Abc> below. 1 ; The call to C<warnings::register> will create a new warnings category -called "MyMod::abc", i.e. the new category name matches the module -name. The C<open> function in the module will display a warning message -if it gets given a relative path as a parameter. This warnings will only -be displayed if the code that uses C<MyMod::Abc> has actually enabled -them with the C<warnings> pragma like below. +called "MyMod::abc", i.e. the new category name matches the current +package name. The C<open> function in the module will display a warning +message if it gets given a relative path as a parameter. This warnings +will only be displayed if the code that uses C<MyMod::Abc> has actually +enabled them with the C<warnings> pragma like below. use MyMod::Abc; use warnings 'MyMod::Abc'; @@ -379,10 +389,8 @@ this snippet of code: package MyMod::Abc; sub open { - if (warnings::enabled("deprecated")) { - warnings::warn("deprecated", - "open is deprecated, use new instead") ; - } + warnings::warnif("deprecated", + "open is deprecated, use new instead") ; new(@_) ; } @@ -399,18 +407,89 @@ display a warning message whenever the calling module has (at least) the ... MyMod::Abc::open($filename) ; -The C<warnings::warn> function should be used to actually display the -warnings message. This is because they can make use of the feature that -allows warnings to be escalated into fatal errors. So in this case +Either the C<warnings::warn> or C<warnings::warnif> function should be +used to actually display the warnings message. This is because they can +make use of the feature that allows warnings to be escalated into fatal +errors. So in this case use MyMod::Abc; use warnings FATAL => 'MyMod::Abc'; ... MyMod::Abc::open('../fred.txt'); -the C<warnings::warn> function will detect this and die after +the C<warnings::warnif> function will detect this and die after displaying the warning message. +The three warnings functions, C<warnings::warn>, C<warnings::warnif> +and C<warnings::enabled> can optionally take an object reference in place +of a category name. In this case the functions will use the class name +of the object as the warnings category. + +Consider this example: + + package Original ; + + no warnings ; + use warnings::register ; + + sub new + { + my $class = shift ; + bless [], $class ; + } + + sub check + { + my $self = shift ; + my $value = shift ; + + if ($value % 2 && warnings::enabled($self)) + { warnings::warn($self, "Odd numbers are unsafe") } + } + + sub doit + { + my $self = shift ; + my $value = shift ; + $self->check($value) ; + # ... + } + + 1 ; + + package Derived ; + + use warnings::register ; + use Original ; + our @ISA = qw( Original ) ; + sub new + { + my $class = shift ; + bless [], $class ; + } + + + 1 ; + +The code below makes use of both modules, but it only enables warnings from +C<Derived>. + + use Original ; + use Derived ; + use warnings 'Derived'; + my $a = new Original ; + $a->doit(1) ; + my $b = new Derived ; + $a->doit(1) ; + +When this code is run only the C<Derived> object, C<$b>, will generate +a warning. + + Odd numbers are unsafe at main.pl line 7 + +Notice also that the warning is reported at the line where the object is first +used. + =head1 TODO perl5db.pl @@ -424,6 +503,8 @@ displaying the warning message. around the limitations of C<$^W>. Now that those limitations are gone, the module should be revisited. + document calling the warnings::* functions from XS + =head1 SEE ALSO L<warnings>, L<perldiag>. diff --git a/contrib/perl5/pod/perllocale.pod b/contrib/perl5/pod/perllocale.pod index be3738573cb8..9964b331c35c 100644 --- a/contrib/perl5/pod/perllocale.pod +++ b/contrib/perl5/pod/perllocale.pod @@ -124,8 +124,8 @@ B<The POSIX date formatting function> (strftime()) uses C<LC_TIME>. =back -C<LC_COLLATE>, C<LC_CTYPE>, and so on, are discussed further in L<LOCALE -CATEGORIES>. +C<LC_COLLATE>, C<LC_CTYPE>, and so on, are discussed further in +L<LOCALE CATEGORIES>. The default behavior is restored with the S<C<no locale>> pragma, or upon reaching the end of block enclosing C<use locale>. @@ -289,7 +289,7 @@ than the PERL_BADLANG approach, but setting LC_ALL (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 L<ENVIRONMENT> for for +programs you run see the changes. See L<ENVIRONMENT> for the full list of relevant environment variables and L<USING LOCALES> for their effects in Perl. Effects in other programs are easily deducible. For example, the variable LC_COLLATE may well affect @@ -348,8 +348,8 @@ 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 L<Finding -locales> about general rules. +standardization is weak in this area. See again the +L<Finding locales> about general rules. =head2 Fixing system locale configuration @@ -381,7 +381,7 @@ with a single parameter--see L<The setlocale function>.) localeconv() takes no arguments, and returns B<a reference to> a hash. The keys of this hash are variable names for formatting, such as C<decimal_point> and C<thousands_sep>. The values are the -corresponding, er, values. See L<POSIX (3)/localeconv> for a longer +corresponding, er, values. See L<POSIX/localeconv> 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 C<use locale>, because localeconv() always observes the @@ -445,21 +445,21 @@ The following collations all make sense and you may meet any of them if you "use locale". A B C D E a b c d e - A a B b C c D d 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 -Here is a code snippet to tell what alphanumeric +Here is a code snippet to tell what "word" characters are in the current locale, in that locale's order: use locale; - print +(sort grep /\w/, map { chr() } 0..255), "\n"; + print +(sort grep /\w/, map { chr } 0..255), "\n"; Compare this with the characters that you see and their order if you state explicitly that the locale should be ignored: no locale; - print +(sort grep /\w/, map { chr() } 0..255), "\n"; + print +(sort grep /\w/, map { chr } 0..255), "\n"; This machine-native collation (which is what you get unless S<C<use locale>> has appeared earlier in the same block) must be used for @@ -518,8 +518,9 @@ results, and so always obey the current C<LC_COLLATE> locale. In the scope of S<C<use locale>>, Perl obeys the C<LC_CTYPE> locale setting. This controls the application's notion of which characters are alphabetic. This affects Perl's C<\w> regular expression metanotation, -which stands for alphanumeric characters--that is, alphabetic and -numeric characters. (Consult L<perlre> for more information about +which stands for alphanumeric characters--that is, alphabetic, +numeric, and including other special characters such as the underscore or +hyphen. (Consult L<perlre> for more information about regular expressions.) Thanks to C<LC_CTYPE>, depending on your locale setting, characters like 'E<aelig>', 'E<eth>', 'E<szlig>', and 'E<oslash>' may be understood as C<\w> characters. @@ -553,20 +554,20 @@ change the character used for the decimal point--perhaps from '.' to ','. These functions aren't aware of such niceties as thousands separation and so on. (See L<The localeconv function> if you care about these things.) -Output produced by print() is B<never> affected by the -current locale: it is independent of whether C<use locale> or C<no -locale> is in effect, and corresponds to what you'd get from printf() -in the "C" locale. The same is true for Perl's internal conversions -between numeric and string formats: +Output produced by print() is also affected by the current locale: it +depends on whether C<use locale> or C<no locale> is in effect, and +corresponds to what you'd get from printf() in the "C" locale. The +same is true for Perl's internal conversions between numeric and +string formats: use POSIX qw(strtod); use locale; $n = 5/2; # Assign numeric 2.5 to $n - $a = " $n"; # Locale-independent conversion to string + $a = " $n"; # Locale-dependent conversion to string - print "half five is $n\n"; # Locale-independent output + print "half five is $n\n"; # Locale-dependent output printf "half five is %g\n", $n; # Locale-dependent output @@ -579,11 +580,12 @@ The C standard defines the C<LC_MONETARY> category, but no function that is affected by its contents. (Those with experience of standards committees will recognize that the working group decided to punt on the issue.) Consequently, Perl takes no notice of it. If you really want -to use C<LC_MONETARY>, you can query its contents--see L<The localeconv -function>--and use the information that it returns in your application's -own formatting of currency amounts. However, you may well find that -the information, voluminous and complex though it may be, still does not -quite meet your requirements: currency formatting is a hard nut to crack. +to use C<LC_MONETARY>, you can query its contents--see +L<The localeconv function>--and use the information that it returns in your +application's own formatting of currency amounts. However, you may well +find that the information, voluminous and complex though it may be, still +does not quite meet your requirements: currency formatting is a hard nut +to crack. =head2 LC_TIME @@ -641,15 +643,6 @@ case-mapping table is in effect. =item * -Some systems are broken in that they allow the "C" locale to be -overridden by users. If the decimal point character in the -C<LC_NUMERIC> category of the "C" locale is surreptitiously changed -from a dot to a comma, C<sprintf("%g", 0.123456e3)> produces a -string result of "123,456". Many people would interpret this as -one hundred and twenty-three thousand, four hundred and fifty-six. - -=item * - A sneaky C<LC_COLLATE> locale could result in the names of students with "D" grades appearing ahead of those with "A"s. @@ -685,16 +678,22 @@ the locale: =over 4 -=item B<Comparison operators> (C<lt>, C<le>, C<ge>, C<gt> and C<cmp>): +=item * + +B<Comparison operators> (C<lt>, C<le>, C<ge>, C<gt> and C<cmp>): Scalar true/false (or less/equal/greater) result is never tainted. -=item B<Case-mapping interpolation> (with C<\l>, C<\L>, C<\u> or C<\U>) +=item * + +B<Case-mapping interpolation> (with C<\l>, C<\L>, C<\u> or C<\U>) Result string containing interpolated material is tainted if C<use locale> is in effect. -=item B<Matching operator> (C<m//>): +=item * + +B<Matching operator> (C<m//>): Scalar true/false result never tainted. @@ -707,7 +706,9 @@ expression contains C<\w> (to match an alphanumeric character), C<\W> C<use locale> is in effect and the regular expression contains C<\w>, C<\W>, C<\s>, or C<\S>. -=item B<Substitution operator> (C<s///>): +=item * + +B<Substitution operator> (C<s///>): Has the same behavior as the match operator. Also, the left operand of C<=~> becomes tainted when C<use locale> in effect @@ -715,20 +716,30 @@ if modified as a result of a substitution based on a regular expression match involving C<\w>, C<\W>, C<\s>, or C<\S>; or of case-mapping with C<\l>, C<\L>,C<\u> or C<\U>. -=item B<Output formatting functions> (printf() and write()): +=item * -Success/failure result is never tainted. +B<Output formatting functions> (printf() and write()): -=item B<Case-mapping functions> (lc(), lcfirst(), uc(), ucfirst()): +Results are never tainted because otherwise even output from print, +for example C<print(1/7)>, should be tainted if C<use locale> is in +effect. + +=item * + +B<Case-mapping functions> (lc(), lcfirst(), uc(), ucfirst()): Results are tainted if C<use locale> is in effect. -=item B<POSIX locale-dependent functions> (localeconv(), strcoll(), +=item * + +B<POSIX locale-dependent functions> (localeconv(), strcoll(), strftime(), strxfrm()): Results are never tainted. -=item B<POSIX character class tests> (isalnum(), isalpha(), isdigit(), +=item * + +B<POSIX character class tests> (isalnum(), isalpha(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit()): @@ -946,44 +957,19 @@ In certain systems, the operating system's locale support is broken and cannot be fixed or used by Perl. Such deficiencies can and will result in mysterious hangs and/or Perl core dumps when the C<use locale> is in effect. When confronted with such a system, -please report in excruciating detail to <F<perlbug@perl.com>>, and +please report in excruciating detail to <F<perlbug@perl.org>>, and complain to your vendor: bug fixes may exist for these problems in your operating system. Sometimes such bug fixes are called an operating system upgrade. =head1 SEE ALSO -L<POSIX (3)/isalnum> - -L<POSIX (3)/isalpha> - -L<POSIX (3)/isdigit> - -L<POSIX (3)/isgraph> - -L<POSIX (3)/islower> - -L<POSIX (3)/isprint>, - -L<POSIX (3)/ispunct> - -L<POSIX (3)/isspace> - -L<POSIX (3)/isupper>, - -L<POSIX (3)/isxdigit> - -L<POSIX (3)/localeconv> - -L<POSIX (3)/setlocale>, - -L<POSIX (3)/strcoll> - -L<POSIX (3)/strftime> - -L<POSIX (3)/strtod>, - -L<POSIX (3)/strxfrm> +L<POSIX/isalnum>, L<POSIX/isalpha>, L<POSIX/isdigit>, +L<POSIX/isgraph>, L<POSIX/islower>, L<POSIX/isprint>, +L<POSIX/ispunct>, L<POSIX/isspace>, L<POSIX/isupper>, +L<POSIX/isxdigit>, L<POSIX/localeconv>, L<POSIX/setlocale>, +L<POSIX/strcoll>, L<POSIX/strftime>, L<POSIX/strtod>, +L<POSIX/strxfrm>. =head1 HISTORY diff --git a/contrib/perl5/pod/perllol.pod b/contrib/perl5/pod/perllol.pod index f015a20bc4eb..5c16bfddff74 100644 --- a/contrib/perl5/pod/perllol.pod +++ b/contrib/perl5/pod/perllol.pod @@ -4,7 +4,7 @@ perllol - Manipulating Arrays of Arrays in Perl =head1 DESCRIPTION -=head1 Declaration and Access of Arrays of Arrays +=head2 Declaration and Access of Arrays of Arrays The simplest thing to build an array of arrays (sometimes imprecisely called a list of lists). It's reasonably easy to understand, and @@ -58,7 +58,7 @@ 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. -=head1 Growing Your Own +=head2 Growing Your Own 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 @@ -174,7 +174,7 @@ Notice that I I<couldn't> say just: In fact, that wouldn't even compile. How come? Because the argument to push() must be a real array, not just a reference to such. -=head1 Access and Printing +=head2 Access and Printing Now it's time to print your data structure out. How are you going to do that? Well, if you want only one @@ -231,7 +231,7 @@ Hmm... that's still a bit ugly. How about this: } } -=head1 Slices +=head2 Slices If you want to get at a slice (part of a row) in a multidimensional array, you're going to have to do some fancy subscripting. That's diff --git a/contrib/perl5/pod/perlmod.pod b/contrib/perl5/pod/perlmod.pod index 63324a41f45c..01056f1d98a1 100644 --- a/contrib/perl5/pod/perlmod.pod +++ b/contrib/perl5/pod/perlmod.pod @@ -8,7 +8,7 @@ perlmod - Perl modules (packages and symbol tables) 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 +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, C<eval>, @@ -61,8 +61,8 @@ as a pattern match, a substitution, or a transliteration. 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. -$_ is still global though. See also L<perlvar/"Technical Note on the -Syntax of Variable Names">. +$_ is still global though. See also +L<perlvar/"Technical Note on the Syntax of Variable Names">. C<eval>ed strings are compiled in the package in which the eval() was compiled. (Assignments to C<$SIG{}>, however, assume the signal @@ -85,7 +85,7 @@ and L<perlref> regarding closures. 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 -C<%main::>, or C<%::> for short. Likewise symbol table for the nested +C<%main::>, or C<%::> for short. Likewise the symbol table for the nested package mentioned earlier is named C<%OUTER::INNER::>. The value in each entry of the hash is what you are referring to when you @@ -96,8 +96,14 @@ table lookups at compile time: local *main::foo = *main::bar; local $main::{foo} = $main::{bar}; +(Be sure to note the B<vast> difference between the second line above +and C<local $main::foo = $main::bar>. The former is accessing the hash +C<%main::>, which is the symbol table of package C<main>. The latter is +simply assigning scalar C<$bar> in package C<main> to scalar C<$foo> of +the same package.) + You can use this to print out all the variables in a package, for -instance. The standard but antequated F<dumpvar.pl> library and +instance. The standard but antiquated F<dumpvar.pl> library and the CPAN module Devel::Symdump make use of this. Assignment to a typeglob performs an aliasing operation, i.e., @@ -115,7 +121,7 @@ Which makes $richard and $dick the same variable, but leaves @richard and @dick as separate arrays. Tricky, eh? This mechanism may be used to pass and return cheap references -into or from subroutines if you won't want to copy the whole +into or from subroutines if you don't want to copy the whole thing. It only works when assigning to dynamic variables, not lexicals. @@ -132,18 +138,18 @@ lexicals. 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 won't want to have to remember to dereference variables +when you don't want to have to remember to dereference variables explicitly. Another use of symbol tables is for making "constant" scalars. *PI = \3.14159265358979; -Now you cannot alter $PI, which is probably a good thing all in all. +Now you cannot alter C<$PI>, 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. This isn't. A constant subroutine is one -prototyped to take no arguments and to return a constant expression. -See L<perlsub> for details on these. The C<use constant> pragma is a +optimization at compile-time. A constant subroutine is one prototyped +to take no arguments and to return a constant expression. See +L<perlsub> for details on these. The C<use constant> pragma is a convenient shorthand for these. You can say C<*foo{PACKAGE}> and C<*foo{NAME}> to find out what name and @@ -163,7 +169,7 @@ This prints You gave me bar::baz The C<*foo{THING}> notation can also be used to obtain references to the -individual elements of *foo, see L<perlref>. +individual elements of *foo. See L<perlref>. Subroutine definitions (and declarations, for that matter) need not necessarily be situated in the package whose symbol table they @@ -233,7 +239,7 @@ being blown out of the water by a signal--you have to trap that yourself (if you can).) You may have multiple C<END> blocks within a file--they will execute in reverse order of definition; that is: last in, first out (LIFO). C<END> blocks are not executed when you run perl with the -C<-c> switch. +C<-c> switch, or if compilation fails. Inside an C<END> subroutine, C<$?> contains the value that the program is going to pass to C<exit()>. You can modify C<$?> to change the exit @@ -251,10 +257,10 @@ LIFO order. C<CHECK> blocks are again useful in the Perl compiler suite to save the compiled state of the program. When you use the B<-n> and B<-p> switches to Perl, C<BEGIN> and -C<END> work just as they do in B<awk>, as a degenerate case. As currently -implemented (and subject to change, since its inconvenient at best), -both C<BEGIN> and<END> blocks are run when you use the B<-c> switch -for a compile-only syntax check, although your main code is not. +C<END> work just as they do in B<awk>, as a degenerate case. +Both C<BEGIN> and C<CHECK> blocks are run when you use the B<-c> +switch for a compile-only syntax check, although your main code +is not. =head2 Perl Classes @@ -268,14 +274,14 @@ For more on this, see L<perltoot> and L<perlobj>. =head2 Perl Modules -A module is just a set of related function in a library file 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 +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 -exportating anything. Or it can do a little of both. +exporting anything. Or it can do a little of both. For example, to start a traditional, non-OO module called Some::Module, create a file called F<Some/Module.pm> and start with this template: @@ -304,6 +310,10 @@ create a file called F<Some/Module.pm> and start with this template: } our @EXPORT_OK; + # exported package globals go here + our $Var1; + our %Hashit; + # non-exported package globals go here our @more; our $stuff; @@ -419,19 +429,19 @@ that other module. In that case, it's easy to use C<require>s instead. Perl packages may be nested inside other package names, so we can have package names containing C<::>. But if we used that package name -directly as a filename it would makes for unwieldy or impossible +directly as a filename it would make for unwieldy or impossible filenames on some systems. Therefore, if a module's name is, say, C<Text::Soundex>, then its definition is actually found in the library file F<Text/Soundex.pm>. Perl modules always have a F<.pm> file, but there may also be dynamically linked executables (often ending in F<.so>) or autoloaded -subroutine definitions (often ending in F<.al> associated with the +subroutine definitions (often ending in F<.al>) associated with the module. If so, these will be entirely transparent to the user of the module. It is the responsibility of the F<.pm> file to load (or arrange to autoload) any additional functionality. For example, although the POSIX module happens to do both dynamic loading and -autoloading, but the user can say just C<use POSIX> to get it all. +autoloading, the user can say just C<use POSIX> to get it all. =head1 SEE ALSO diff --git a/contrib/perl5/pod/perlmodinstall.pod b/contrib/perl5/pod/perlmodinstall.pod index 19ffac98c9ca..0fc359e913d8 100644 --- a/contrib/perl5/pod/perlmodinstall.pod +++ b/contrib/perl5/pod/perlmodinstall.pod @@ -47,7 +47,7 @@ Makefile.PL PREFIX=/my/perl_directory> to install the modules into C</my/perl_directory>. Then you can use the modules from your Perl programs with C<use lib "/my/perl_directory/lib/site_perl"> or sometimes just C<use -"/my/perl_directory">. +"/my/perl_directory">. =over 4 @@ -55,16 +55,16 @@ from your Perl programs with C<use lib B<If you're on Unix,> -You can use Andreas Koenig's CPAN module +You can use Andreas Koenig's CPAN module (which comes standard with Perl, or can itself be downloaded -from http://www.perl.com/CPAN/modules/by-module/CPAN) +from http://www.perl.com/CPAN/modules/by-module/CPAN) to automate the following steps, from DECOMPRESS through INSTALL. -A. DECOMPRESS +A. DECOMPRESS Decompress the file with C<gzip -d yourmodule.tar.gz> -You can get gzip from ftp://prep.ai.mit.edu/pub/gnu. +You can get gzip from ftp://prep.ai.mit.edu/pub/gnu. Or, you can combine this step with the next to save disk space: @@ -126,13 +126,14 @@ CPAN for others to use. If it doesn't, go to INSTALL. D. INSTALL Copy the module into your Perl's I<lib> directory. That'll be one -of the directories you see when you type +of the directories you see when you type perl -e 'print "@INC"' =item * -B<If you're running Windows 95 or NT with the core Windows distribution of Perl,> +B<If you're running Windows 95 or NT with the core Windows distribution of +Perl,> A. DECOMPRESS @@ -185,63 +186,66 @@ B<If you're using a Macintosh,> A. DECOMPRESS -In general, all Macintosh decompression utilities mentioned here -can be found in the Info-Mac Hyperarchive -( http://hyperarchive.lcs.mit.edu/HyperArchive.html ). -Specificly the "Commpress & Translate" listing -( http://hyperarchive.lcs.mit.edu/HyperArchive/Abstracts/cmp/HyperArchive.html ). +First thing you should do is make sure you have the latest B<cpan-mac> +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. +After installing cpan-mac, drop the module archive on the +B<untarzipme> droplet, which will decompress and unpack for you. -You can either use the shareware B<StuffIt Expander> program -( http://www.aladdinsys.com/expander/ ) -in combination with I<DropStuff with Expander Enhancer> -( http://www.aladdinsys.com/dropstuff/ ) +B<Or>, you can either use the shareware B<StuffIt Expander> program +( http://www.aladdinsys.com/expander/ ) +in combination with B<DropStuff with Expander Enhancer> +( http://www.aladdinsys.com/dropstuff/ ) or the freeware B<MacGzip> program ( http://persephone.cps.unizar.es/general/gente/spd/gzip/gzip.html ). - B. UNPACK -If you're using DropStuff or Stuffit, you can just extract the tar -archive. Otherwise, you can use the freeware B<suntar> or I<Tar> ( +If you're using untarzipme or StuffIt, the archive should be extracted +now. B<Or>, you can use the freeware B<suntar> or I<Tar> ( http://hyperarchive.lcs.mit.edu/HyperArchive/Archive/cmp/ ). C. BUILD -Does the module require compilation? - -1. If it does, +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 +F<.xs> and F<.c> files, which normally denote that the distribution +must be compiled, and you cannot install it "out of the box." +(See L<"PORTABILITY">.) + +If a module does not work on MacPerl but should, or needs to be +compiled, see if the module exists already as a port on the +MacPerl Module Porters site (http://pudge.net/mmp/). +For more information on doing XS with MacPerl yourself, see +Arved Sandstrom's XS tutorial (http://macperl.com/depts/Tutorials/), +and then consider uploading your binary to the CPAN and +registering it on the MMP site. -Overview: You need MPW and a combination of new and old CodeWarrior -compilers for MPW and libraries. Makefiles created for building under -MPW use Metrowerks compilers. It's most likely possible to build -without other compilers, but it has not been done successfully, to our -knowledge. Read the documentation in I<MacPerl: Power and Ease> ( -http://www.ptf.com/macperl/ ) on porting/building extensions, or find -an existing precompiled binary, or hire someone to build it for you. +D. INSTALL -Or, ask someone on the mac-perl mailing list (mac-perl@iis.ee.ethz.ch) -to build it for you. To subscribe to the mac-perl mailing list, send -mail to mac-perl-request@iis.ee.ethz.ch. +If you are using cpan-mac, just drop the folder on the +B<installme> droplet, and use the module. -2. If the module doesn't require compilation, go to INSTALL. - -D. INSTALL +B<Or>, if you aren't using cpan-mac, do some manual labor. 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. -As a last resort, you can use the perl one-liner: +As a last resort, you can use the perl one-liner: - perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames> + perl -i.bak -pe 's/(?:\015)?\012/\015/g' <filenames> on the source files. -Move the files manually into the correct folders. - -Move the files to their final destination: This will +Then move the files (probably just the F<.pm> files, though there +may be some additional ones, too; check the module documentation) +to their final destination: This will most likely be in C<$ENV{MACPERL}site_lib:> (i.e., C<HD:MacPerl folder:site_lib:>). You can add new paths to the default C<@INC> in the Preferences menu item in the @@ -251,16 +255,13 @@ automagically). Create whatever directory structures are required C<$ENV{MACPERL}site_lib:Some:> and put C<Module.pm> in that directory). -Run the following script (or something like it): +Then run the following script (or something like it): #!perl -w use AutoSplit; my $dir = "${MACPERL}site_perl"; autosplit("$dir:Some:Module.pm", "$dir:auto", 0, 1, 1); -Eventually there should be a way to automate the installation process; some -solutions exist, but none are ready for the general public yet. - =item * B<If you're on the DJGPP port of DOS,> @@ -268,7 +269,7 @@ B<If you're on the DJGPP port of DOS,> A. DECOMPRESS djtarx ( ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/ ) -will both uncompress and unpack. +will both uncompress and unpack. B. UNPACK @@ -289,7 +290,7 @@ in the Perl distribution. While still in that directory, type: - make install + make install You will need the packages mentioned in F<README.dos> in the Perl distribution. @@ -313,17 +314,17 @@ C<Your-Module-1_33.tgz>. A. DECOMPRESS -Type +Type gzip -d Your-Module.tgz -or, for zipped modules, type +or, for zipped modules, type unzip Your-Module.zip Executables for gzip, zip, and VMStar ( Alphas: http://www.openvms.digital.com/freeware/000TOOLS/ALPHA/ and Vaxen: -http://www.openvms.digital.com/freeware/000TOOLS/VAX/ ). +http://www.openvms.digital.com/freeware/000TOOLS/VAX/ ). gzip and tar are also available at ftp://ftp.digital.com/pub/VMS. @@ -342,10 +343,11 @@ Or, if you're fond of VMS command syntax: tar/extract/verbose Your_Module.tar -C. BUILD +C. BUILD -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: +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: perl Makefile.PL @@ -358,7 +360,7 @@ Substitute C<mmk> for C<mms> above if you're using MMK. D. INSTALL -Type +Type mms install @@ -371,16 +373,16 @@ B<If you're on MVS>, Introduce the F<.tar.gz> file into an HFS as binary; don't translate from ASCII to EBCDIC. -A. DECOMPRESS +A. DECOMPRESS Decompress the file with C<gzip -d yourmodule.tar.gz> - You can get gzip from + You can get gzip from http://www.s390.ibm.com/products/oe/bpxqp1.html. B. UNPACK -Unpack the result with +Unpack the result with pax -o to=IBM-1047,from=ISO8859-1 -r < yourmodule.tar @@ -390,6 +392,52 @@ available from http://www.mks.com/s390/gnu/index.htm. =back + +=head1 PORTABILITY + +Note that not all modules will work with on all platforms. +See L<perlport> 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): + +=over 4 + +=item * + +B<Those that should, but don't.> These need to be fixed; consider +contacting the author and possibly writing a patch. + +=item * + +B<Those that need to be compiled, where the target platform +doesn't have compilers readily available.> (These modules contain +F<.xs> or F<.c> 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. + +=item * + +B<Those that are targeted at a specific platform.> +(Such as the Win32:: modules.) If the module is targeted +specifically at a platform other than yours, you're out +of luck, most likely. + +=back + + + +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. + + http://testers.cpan.org/ + + =head1 HEY If you have any suggested changes for this page, let me know. Please @@ -401,7 +449,7 @@ familiar with Perl on your operating system. =head1 AUTHOR -Jon Orwant +Jon Orwant orwant@tpj.com @@ -413,11 +461,13 @@ Nick Ing-Simmons, Tuomas J. Lukka, Laszlo Molnar, Chris Nandor, Alan Olsen, Peter Prymmer, Gurusamy Sarathy, Christoph Spalinger, Dan Sugalski, Larry Virden, and Ilya Zakharevich. -July 22, 1998 +First version July 22, 1998 + +Last Modified August 22, 2000 =head1 COPYRIGHT -Copyright (C) 1998 Jon Orwant. All Rights Reserved. +Copyright (C) 1998, 2000 Jon Orwant. All Rights Reserved. Permission is granted to make and distribute verbatim copies of this documentation provided the copyright notice and this permission notice are @@ -434,4 +484,3 @@ to this one. Permission is granted to copy and distribute translations of this documentation into another language, under the above conditions for modified versions. - diff --git a/contrib/perl5/pod/perlmodlib.pod b/contrib/perl5/pod/perlmodlib.pod index b42a2d881ca2..90bdb4395044 100644 --- a/contrib/perl5/pod/perlmodlib.pod +++ b/contrib/perl5/pod/perlmodlib.pod @@ -1,3 +1,5 @@ +# Generated by perlmodlib.PL DO NOT EDIT! + =head1 NAME perlmodlib - constructing new Perl modules and finding existing ones @@ -66,9 +68,9 @@ Establish IS-A relationship with base class at compile time Use MakeMaker's uninstalled version of a package -=item caller +=item bytes -Inherit pragmatic attributes from caller's context +Force byte semantics rather than character semantics =item charnames @@ -80,23 +82,23 @@ Declare constants =item diagnostics -Force verbose warning diagnostics +Perl compiler pragma to force verbose warning diagnostics =item fields -Declare a class's attribute fields at compile-time +Compile-time class fields =item filetest -Control the filetest operators like C<-r>, C<-w> for AFS, etc. +Control the filetest permission operators =item integer -Compute arithmetic in integer instead of double +Use integer arithmetic instead of floating point =item less -Request less of something from the compiler (unimplemented) +Request less of something from the compiler =item lib @@ -104,7 +106,11 @@ Manipulate @INC at compile time =item locale -Use or avoid POSIX locales for built-in operations +Use and avoid POSIX locales for built-in operations + +=item open + +Set default disciplines for input and output =item ops @@ -112,11 +118,11 @@ Restrict unsafe operations when compiling =item overload -Overload Perl operations +Package for overloading perl operations =item re -Alter regular expression behavior +Alter regular expression behaviour =item sigtrap @@ -128,20 +134,24 @@ Restrict unsafe constructs =item subs -Predeclare subroutine names +Predeclare sub names =item utf8 -Turn on UTF-8 and Unicode support +Enable/disable UTF-8 in source code =item vars -Predeclare global variable names (obsoleted by our()) +Predeclare global variable names (obsolete) =item warnings Control optional warnings +=item warnings::register + +Warnings import function + =back =head2 Standard Modules @@ -154,7 +164,7 @@ Exporter module. See their own documentation for details. =item AnyDBM_File -Provide framework for multiple DBM libraries +Provide framework for multiple DBMs =item AutoLoader @@ -166,7 +176,7 @@ Split a package for autoloading =item B -Guts of the Perl code generator (aka compiler) +The Perl Compiler =item B::Asmdata @@ -192,13 +202,17 @@ Perl compiler's C backend Perl compiler's optimized C translation backend +=item B::Concise + +Walk Perl syntax tree, printing concise info about ops + =item B::Debug Walk Perl syntax tree, printing debug info about ops =item B::Deparse -Perl compiler backend to produce Perl code +Perl compiler backend to produce perl code =item B::Disassembler @@ -206,7 +220,7 @@ Disassemble Perl bytecode =item B::Lint -Module to catch dubious constructs +Perl lint =item B::Showlex @@ -216,7 +230,9 @@ Show lexical variables used in functions or files Helper module for CC backend -B::Stash -- XXX NFI XXX +=item B::Stash + +Show what stashes are loaded =item B::Terse @@ -228,19 +244,19 @@ Generates cross reference reports for Perl programs =item Benchmark -Benchmark running times of code +Benchmark running times of Perl code =item ByteLoader -Load byte-compiled Perl code +Load byte compiled perl code =item CGI -Simple Common Gateway Interface class +Simple Common Gateway Interface Class =item CGI::Apache -Make things work with CGI.pm against Perl-Apache API +Backward compatibility module for CGI.pm =item CGI::Carp @@ -264,15 +280,19 @@ Simple Interface to Server Push =item CGI::Switch -Try more than one constructors and return the first object available +Backward compatibility module for defunct CGI::Switch + +=item CGI::Util + +Internal utilities used by CGI module =item CPAN -Query, download, and build Perl modules from CPAN sites +Query, download and build perl modules from CPAN sites =item CPAN::FirstTime -Utility for CPAN::Config file initialization +Utility for CPAN::Config file Initialization =item CPAN::Nox @@ -280,7 +300,7 @@ Wrapper around CPAN.pm without using any XS module =item Carp -Act like warn/die from perspective of caller +Warn of errors (from perspective of caller) =item Carp::Heavy @@ -290,34 +310,18 @@ Carp guts Declare struct-like datatypes as Perl classes -=item Config - -Access Perl configuration information - =item Cwd Get pathname of current working directory =item DB -Programmatic interface to the Perl debugging API (experimental) +Programmatic interface to the Perl debugging API (draft, subject to =item DB_File Perl5 access to Berkeley DB version 1.x -=item Data::Dumper - -Serialize Perl data structures - -=item Devel::DProf - -A Perl execution profiler - -=item Devel::Peek - -A data debugging tool for the XS programmer - =item Devel::SelfStubber Generate stubs for a SelfLoading module @@ -328,27 +332,19 @@ Supply object methods for directory handles =item Dumpvalue -Provide screen dump of Perl data - -=item DynaLoader - -Dynamically load C libraries into Perl code +Provides screen dump of Perl data. =item English -Use English (or awk) names for ugly punctuation variables +Use nice English (or awk) names for ugly punctuation variables =item Env -Access environment variables as regular ones - -=item Errno - -Load the libc errno.h defines +Perl module that imports environment variables as scalars or arrays =item Exporter -Implement default import method for modules +Implements default import method for modules =item Exporter::Heavy @@ -356,11 +352,11 @@ Exporter guts =item ExtUtils::Command -Utilities to replace common Unix commands in Makefiles etc. +Utilities to replace common UNIX commands in Makefiles etc. =item ExtUtils::Embed -Utilities for embedding Perl in C/C++ programs +Utilities for embedding Perl in C/C++ applications =item ExtUtils::Install @@ -376,11 +372,11 @@ Determine libraries to use and how to use them =item ExtUtils::MM_Cygwin -Methods to override Unix behavior in ExtUtils::MakeMaker +Methods to override UN*X behaviour in ExtUtils::MakeMaker =item ExtUtils::MM_OS2 -Methods to override Unix behavior in ExtUtils::MakeMaker +Methods to override UN*X behaviour in ExtUtils::MakeMaker =item ExtUtils::MM_Unix @@ -388,11 +384,11 @@ Methods used by ExtUtils::MakeMaker =item ExtUtils::MM_VMS -Methods to override Unix behavior in ExtUtils::MakeMaker +Methods to override UN*X behaviour in ExtUtils::MakeMaker =item ExtUtils::MM_Win32 -Methods to override Unix behavior in ExtUtils::MakeMaker +Methods to override UN*X behaviour in ExtUtils::MakeMaker =item ExtUtils::MakeMaker @@ -402,8 +398,6 @@ Create an extension Makefile Utilities to write and check a MANIFEST file -ExtUtils::Miniperl, writemain - Write the C code for perlmain.c - =item ExtUtils::Mkbootstrap Make a bootstrap file for use by DynaLoader @@ -426,7 +420,7 @@ Replace functions with equivalents which succeed or die =item Fcntl -Load the libc fcntl.h defines +Load the C Fcntl.h defines =item File::Basename @@ -446,24 +440,24 @@ Copy files or filehandles =item File::DosGlob -DOS-like globbing and then some +DOS like globbing and then some =item File::Find -Traverse a file tree - -=item File::Glob - -Perl extension for BSD filename globbing +Traverse a file tree =item File::Path -Create or remove a series of directories +Create or remove directory trees =item File::Spec Portably perform operations on file names +=item File::Spec::Epoc + +Methods for Epoc file specs + =item File::Spec::Functions Portably perform operations on file names @@ -488,6 +482,10 @@ Methods for VMS file specs Methods for Win32 file specs +=item File::Temp + +Return name and handle of a temporary file safely + =item File::stat By-name interface to Perl's built-in stat() functions @@ -502,11 +500,11 @@ Supply object methods for filehandles =item FindBin -Locate installation directory of running Perl program +Locate directory of original perl script =item GDBM_File -Access to the gdbm library +Perl5 access to the gdbm library. =item Getopt::Long @@ -518,55 +516,11 @@ Process single-character switches with switch clustering =item I18N::Collate -Compare 8-bit scalar data according to current locale +Compare 8-bit scalar data according to the current locale =item IO -Front-end to load various IO modules - -=item IO::Dir - -Supply object methods for directory handles - -=item IO::File - -Supply object methods for filehandles - -=item IO::Handle - -Supply object methods for I/O handles - -=item IO::Pipe - -Supply object methods for pipes - -=item IO::Poll - -Object interface to system poll call - -=item IO::Seekable - -Supply seek based methods for I/O objects - -=item IO::Select - -OO interface to the select system call - -=item IO::Socket - -Object interface to socket communications - -=item IO::Socket::INET - -Object interface for AF_INET domain sockets - -=item IO::Socket::UNIX - -Object interface for AF_UNIX domain sockets - -=item IPC::Msg - -SysV Msg IPC object class +Load various IO modules =item IPC::Open2 @@ -576,14 +530,6 @@ Open a process for both reading and writing Open a process for reading, writing, and error handling -=item IPC::Semaphore - -SysV Semaphore IPC object class - -=item IPC::SysV - -SysV IPC constants - =item Math::BigFloat Arbitrary length float math package @@ -626,7 +572,7 @@ Generic interface to Perl Compiler backends =item Opcode -Disable named opcodes when compiling Perl code +Disable named opcodes when compiling perl code =item POSIX @@ -636,22 +582,38 @@ Perl interface to IEEE Std 1003.1 Check pod documents for syntax errors +=item Pod::Find + +Find POD documents in directory trees + =item Pod::Html Module to convert pod files to HTML =item Pod::InputObjects -Manage POD objects +Objects representing POD input paragraphs, commands, etc. + +=item Pod::LaTeX + +Convert Pod data to formatted Latex =item Pod::Man Convert POD data to formatted *roff input +=item Pod::ParseUtils + +Helpers for POD parsing and conversion + =item Pod::Parser Base class for creating POD filters and translators +=item Pod::Plainer + +Perl extension for converting Pod to old style Pod. + =item Pod::Select Extract selected sections of POD from input @@ -664,6 +626,14 @@ Convert POD data to formatted ASCII text Convert POD data to formatted color ASCII text +=item Pod::Text::Overstrike + +Convert POD data to formatted overstrike text + +=item Pod::Text::Termcap + +Convert POD data to ASCII text with format escapes + =item Pod::Usage Print a usage message from embedded pod documentation @@ -690,35 +660,31 @@ Load functions only on demand =item Shell -Run shell commands transparently within Perl +Run shell commands transparently within perl =item Socket -Load the libc socket.h defines and structure manipulators +Load the C socket.h defines and structure manipulators =item Symbol Manipulate Perl symbols and their names -=item Sys::Hostname - -Try every conceivable way to get hostname +=item Term::ANSIColor -=item Sys::Syslog - -Interface to the libc syslog(3) calls +Color screen output using ANSI escape sequences =item Term::Cap -Termcap interface +Perl termcap interface =item Term::Complete -Word completion module +Perl word completion module =item Term::ReadLine -Interface to various `readline' packages. +Perl interface to various C<readline> packages. If =item Test @@ -726,7 +692,7 @@ Provides a simple framework for writing test scripts =item Test::Harness -Run Perl standard test scripts with statistics +Run perl standard test scripts with statistics =item Text::Abbrev @@ -734,18 +700,40 @@ Create an abbreviation table from a list =item Text::ParseWords -Parse text into a list of tokens or array of arrays +Parse text into an array of tokens or array of arrays =item Text::Soundex -Implementation of the Soundex Algorithm as described by Knuth +Implementation of the Soundex Algorithm as Described by Knuth + +=item Text::Tabs -Text::Tabs -- expand and unexpand tabs per expand(1) and unexpand(1) +Expand and unexpand tabs per the unix expand(1) and unexpand(1) =item Text::Wrap Line wrapping to form simple paragraphs +=item Thread + +Manipulate threads in Perl (EXPERIMENTAL, subject to change) + +=item Thread::Queue + +Thread-safe queues + +=item Thread::Semaphore + +Thread-safe semaphores + +=item Thread::Signal + +Start a thread which runs signal handlers reliably + +=item Thread::Specific + +Thread-specific keys + =item Tie::Array Base class for tied arrays @@ -798,26 +786,25 @@ By-name interface to Perl's built-in getgr*() functions By-name interface to Perl's built-in getpw*() functions +=item Win32 + +Interfaces to some Win32 API Functions + =back To find out I<all> modules installed on your system, including -those without documentation or outside the standard release, +those without documentation or outside the standard release, just do this: % find `perl -e 'print "@INC"'` -name '*.pm' -print -To get a log of all module distributions which have been installed -since perl was installed, just do: - - % perldoc perllocal - -Modules should all have their own documentation installed and accessible -via your system man(1) command, or via the C<perldoc> program. If you do -not have a B<find> +They should all have their own documentation installed and accessible +via your system man(1) command. If you do not have a B<find> program, you can use the Perl B<find2perl> program instead, which generates Perl code as output you can run through perl. If you have a B<man> program but it doesn't find your modules, you'll have -to fix your manpath. See L<perl> for details. +to fix your manpath. See L<perl> for details. If you have no +system B<man> command, you might try the B<perldoc> program. =head2 Extension Modules @@ -837,7 +824,7 @@ like Alta Vista or Deja News. CPAN stands for Comprehensive Perl Archive Network; it's a globally replicated trove of Perl materials, including documentation, style -guides, tricks and trap, alternate ports to non-Unix systems and +guides, tricks and traps, alternate ports to non-Unix systems and occasional binary distributions for these. Search engines for CPAN can be found at http://cpan.perl.com/ and at http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl . @@ -849,66 +836,87 @@ modules are: =over =item * + Language Extensions and Documentation Tools =item * + Development Support =item * + Operating System Interfaces =item * + Networking, Device Control (modems) and InterProcess Communication =item * + Data Types and Data Type Utilities =item * + Database Interfaces =item * + User Interfaces =item * + Interfaces to / Emulations of Other Programming Languages =item * + File Names, File Systems and File Locking (see also File Handles) =item * + String Processing, Language Text Processing, Parsing, and Searching =item * + Option, Argument, Parameter, and Configuration File Processing =item * + Internationalization and Locale =item * + Authentication, Security, and Encryption =item * + World Wide Web, HTML, HTTP, CGI, MIME =item * + Server and Daemon Utilities =item * + Archiving and Compression =item * + Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing =item * + Mail and Usenet News =item * + Control Flow Utilities (callbacks and exceptions etc) =item * + File Handle and Input/Output Stream Utilities =item * + Miscellaneous Modules =back @@ -916,172 +924,645 @@ Miscellaneous Modules Registered CPAN sites as of this writing include the following. You should try to choose one close to you: -=over +=head2 Africa + +=over 4 + +=item * -=item Africa - - South Africa ftp://ftp.is.co.za/programming/perl/CPAN/ - ftp://ftp.saix.net/pub/CPAN/ - ftp://ftp.sun.ac.za/CPAN/ - ftp://ftpza.co.za/pub/mirrors/cpan/ - - -=item Asia - - China ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/ - Hong Kong ftp://ftp.pacific.net.hk/pub/mirror/CPAN/ - Indonesia ftp://malone.piksi.itb.ac.id/pub/CPAN/ - Israel ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/ - Japan ftp://ftp.dti.ad.jp/pub/lang/CPAN/ - ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/ - ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/ - ftp://ftp.meisei-u.ac.jp/pub/CPAN/ - ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/ - ftp://mirror.nucba.ac.jp/mirror/Perl/ - Saudi-Arabia ftp://ftp.isu.net.sa/pub/CPAN/ - Singapore ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/ - South Korea ftp://ftp.bora.net/pub/CPAN/ - ftp://ftp.kornet.net/pub/CPAN/ - ftp://ftp.nuri.net/pub/CPAN/ - Taiwan ftp://coda.nctu.edu.tw/computer-languages/perl/CPAN/ - ftp://ftp.ee.ncku.edu.tw/pub3/perl/CPAN/ - ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/ - Thailand ftp://ftp.nectec.or.th/pub/mirrors/CPAN/ - - -=item Australasia - - Australia ftp://cpan.topend.com.au/pub/CPAN/ - ftp://ftp.labyrinth.net.au/pub/perl-CPAN/ - ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/ - ftp://mirror.aarnet.edu.au/pub/perl/CPAN/ - New Zealand ftp://ftp.auckland.ac.nz/pub/perl/CPAN/ - ftp://sunsite.net.nz/pub/languages/perl/CPAN/ - - -=item Central America - - Costa Rica ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/ - - -=item Europe - - Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/ - Belgium ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/ - Bulgaria ftp://ftp.ntrl.net/pub/mirrors/CPAN/ - Croatia ftp://ftp.linux.hr/pub/CPAN/ - Czech Republic ftp://ftp.fi.muni.cz/pub/perl/ - ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/ - Denmark ftp://sunsite.auc.dk/pub/languages/perl/CPAN/ - Estonia ftp://ftp.ut.ee/pub/languages/perl/CPAN/ - Finland ftp://ftp.funet.fi/pub/languages/perl/CPAN/ - France ftp://ftp.grolier.fr/pub/perl/CPAN/ - ftp://ftp.lip6.fr/pub/perl/CPAN/ - ftp://ftp.oleane.net/pub/mirrors/CPAN/ - ftp://ftp.pasteur.fr/pub/computing/CPAN/ - ftp://ftp.uvsq.fr/pub/perl/CPAN/ - German ftp://ftp.gigabell.net/pub/CPAN/ - Germany ftp://ftp.archive.de.uu.net/pub/CPAN/ - ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/ - ftp://ftp.gmd.de/packages/CPAN/ - ftp://ftp.gwdg.de/pub/languages/perl/CPAN/ - ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/ - ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/ - ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/ - ftp://ftp.uni-erlangen.de/pub/source/CPAN/ - ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/ - Germany ftp://ftp.archive.de.uu.net/pub/CPAN/ - ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/ - ftp://ftp.gmd.de/packages/CPAN/ - ftp://ftp.gwdg.de/pub/languages/perl/CPAN/ - ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/ - ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/ - ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/ - ftp://ftp.uni-erlangen.de/pub/source/CPAN/ - ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/ - Greece ftp://ftp.ntua.gr/pub/lang/perl/ - Hungary ftp://ftp.kfki.hu/pub/packages/perl/CPAN/ - Iceland ftp://ftp.gm.is/pub/CPAN/ - Ireland ftp://cpan.indigo.ie/pub/CPAN/ - ftp://sunsite.compapp.dcu.ie/pub/perl/ - Italy ftp://cis.uniRoma2.it/CPAN/ - ftp://ftp.flashnet.it/pub/CPAN/ - ftp://ftp.unina.it/pub/Other/CPAN/ - ftp://ftp.unipi.it/pub/mirror/perl/CPAN/ - Netherlands ftp://ftp.cs.uu.nl/mirror/CPAN/ - ftp://ftp.nluug.nl/pub/languages/perl/CPAN/ - Norway ftp://ftp.uit.no/pub/languages/perl/cpan/ - ftp://sunsite.uio.no/pub/languages/perl/CPAN/ - Poland ftp://ftp.man.torun.pl/pub/CPAN/ - ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/ - ftp://sunsite.icm.edu.pl/pub/CPAN/ - Portugal ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/ - ftp://ftp.ist.utl.pt/pub/CPAN/ - ftp://ftp.ua.pt/pub/CPAN/ - Romania ftp://ftp.dnttm.ro/pub/CPAN/ - Russia ftp://ftp.chg.ru/pub/lang/perl/CPAN/ - ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/ - Slovakia ftp://ftp.entry.sk/pub/languages/perl/CPAN/ - Slovenia ftp://ftp.arnes.si/software/perl/CPAN/ - Spain ftp://ftp.etse.urv.es/pub/perl/ - ftp://ftp.rediris.es/mirror/CPAN/ - Sweden ftp://ftp.sunet.se/pub/lang/perl/CPAN/ - Switzerland ftp://sunsite.cnlab-switch.ch/mirror/CPAN/ - Turkey ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/ - United Kingdom ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/ - ftp://ftp.flirble.org/pub/languages/perl/CPAN/ - ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/ - ftp://ftp.plig.org/pub/CPAN/ - ftp://sunsite.doc.ic.ac.uk/packages/CPAN/ - - -=item North America - - Alberta ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/ - California ftp://cpan.nas.nasa.gov/pub/perl/CPAN/ - ftp://cpan.valueclick.com/CPAN/ - ftp://ftp.cdrom.com/pub/perl/CPAN/ - http://download.sourceforge.net/mirrors/CPAN/ - Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ - Florida ftp://ftp.cise.ufl.edu/pub/perl/CPAN/ - Georgia ftp://ftp.twoguys.org/CPAN/ - Illinois ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/ - Indiana ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/ - ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/ - Kentucky ftp://ftp.uky.edu/CPAN/ - Manitoba ftp://theoryx5.uwinnipeg.ca/pub/CPAN/ - Massachusetts ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/ - ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/ - Mexico ftp://ftp.msg.com.mx/pub/CPAN/ - New York ftp://ftp.deao.net/pub/CPAN/ - ftp://ftp.rge.com/pub/languages/perl/ - North Carolina ftp://ftp.duke.edu/pub/perl/ - Nova Scotia ftp://cpan.chebucto.ns.ca/pub/CPAN/ - Oklahoma ftp://ftp.ou.edu/mirrors/CPAN/ - Ontario ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/ - Oregon ftp://ftp.orst.edu/pub/packages/CPAN/ - Pennsylvania ftp://ftp.epix.net/pub/languages/perl/ - Tennessee ftp://ftp.sunsite.utk.edu/pub/CPAN/ - Texas ftp://ftp.sedl.org/pub/mirrors/CPAN/ - ftp://jhcloos.com/pub/mirror/CPAN/ - Utah ftp://mirror.xmission.com/CPAN/ - Virginia ftp://ftp.perl.org/pub/perl/CPAN/ - ftp://ruff.cs.jmu.edu/pub/CPAN/ - Washington ftp://ftp-mirror.internap.com/pub/CPAN/ - ftp://ftp.llarian.net/pub/CPAN/ - ftp://ftp.spu.edu/pub/CPAN/ - - -=item South America - - Brazil ftp://cpan.if.usp.br/pub/mirror/CPAN/ - ftp://ftp.matrix.com.br/pub/perl/ - Chile ftp://sunsite.dcc.uchile.cl/pub/Lang/PERL/ +South Africa + + ftp://ftp.is.co.za/programming/perl/CPAN/ + ftp://ftp.saix.net/pub/CPAN/ + ftp://ftpza.co.za/pub/mirrors/cpan/ + ftp://ftp.sun.ac.za/CPAN/ + +=back + +=head2 Asia + +=over 4 + +=item * + +China + + ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/ + http://www2.linuxforum.net/mirror/CPAN/ + http://cpan.shellhung.org/ + ftp://ftp.shellhung.org/pub/CPAN + +=item * + +Hong Kong + + http://CPAN.pacific.net.hk/ + ftp://ftp.pacific.net.hk/pub/mirror/CPAN/ + +=item * + +Indonesia + + http://piksi.itb.ac.id/CPAN/ + ftp://mirrors.piksi.itb.ac.id/CPAN/ + http://CPAN.mweb.co.id/ + ftp://ftp.mweb.co.id/pub/languages/perl/CPAN/ + +=item * + +Israel + + http://www.iglu.org.il:/pub/CPAN/ + ftp://ftp.iglu.org.il/pub/CPAN/ + http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/ + ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/ + +=item * + +Japan + + ftp://ftp.u-aizu.ac.jp/pub/lang/perl/CPAN/ + ftp://ftp.kddlabs.co.jp/CPAN/ + http://mirror.nucba.ac.jp/mirror/Perl/ + ftp://mirror.nucba.ac.jp/mirror/Perl/ + ftp://ftp.meisei-u.ac.jp/pub/CPAN/ + ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/ + ftp://ftp.dti.ad.jp/pub/lang/CPAN/ + ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/ + +=item * + +Saudi Arabia + + ftp://ftp.isu.net.sa/pub/CPAN/ + +=item * + +Singapore + + http://cpan.hjc.edu.sg + http://ftp.nus.edu.sg/unix/perl/CPAN/ + ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/ + +=item * + +South Korea + + http://CPAN.bora.net/ + ftp://ftp.bora.net/pub/CPAN/ + http://ftp.kornet.net/CPAN/ + ftp://ftp.kornet.net/pub/CPAN/ + ftp://ftp.nuri.net/pub/CPAN/ + +=item * + +Taiwan + + ftp://coda.nctu.edu.tw/UNIX/perl/CPAN + ftp://ftp.ee.ncku.edu.tw/pub/perl/CPAN/ + ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/ + +=item * + +Thailand + + http://download.nectec.or.th/CPAN/ + ftp://ftp.nectec.or.th/pub/languages/CPAN/ + ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/ + +=back + +=head2 Central America + +=over 4 + +=item * + +Costa Rica + + ftp://ftp.linux.co.cr/mirrors/CPAN/ + http://ftp.ucr.ac.cr/Unix/CPAN/ + ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/ + +=back + +=head2 Europe + +=over 4 + +=item * + +Austria + + ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/ + +=item * + +Belgium + + http://ftp.easynet.be/CPAN/ + ftp://ftp.easynet.be/CPAN/ + ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/ + +=item * + +Bulgaria + + ftp://ftp.ntrl.net/pub/mirrors/CPAN/ + +=item * + +Croatia + + ftp://ftp.linux.hr/pub/CPAN/ + +=item * + +Czech Republic + + http://www.fi.muni.cz/pub/perl/ + ftp://ftp.fi.muni.cz/pub/perl/ + ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/ + +=item * + +Denmark + + ftp://sunsite.auc.dk/pub/languages/perl/CPAN/ + http://www.cpan.dk/CPAN/ + ftp://www.cpan.dk/ftp.cpan.org/CPAN/ + +=item * + +England + + http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN + ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/ + ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/ + ftp://ftp.flirble.org/pub/languages/perl/CPAN/ + ftp://ftp.plig.org/pub/CPAN/ + ftp://sunsite.doc.ic.ac.uk/packages/CPAN/ + http://mirror.uklinux.net/CPAN/ + ftp://mirror.uklinux.net/pub/CPAN/ + ftp://usit.shef.ac.uk/pub/packages/CPAN/ + +=item * + +Estonia + + ftp://ftp.ut.ee/pub/languages/perl/CPAN/ + +=item * + +Finland + + ftp://ftp.funet.fi/pub/languages/perl/CPAN/ + +=item * + +France + + ftp://cpan.ftp.worldonline.fr/pub/CPAN/ + ftp://ftp.club-internet.fr/pub/perl/CPAN/ + ftp://ftp.lip6.fr/pub/perl/CPAN/ + ftp://ftp.oleane.net/pub/mirrors/CPAN/ + ftp://ftp.pasteur.fr/pub/computing/CPAN/ + ftp://cpan.cict.fr/pub/CPAN/ + ftp://ftp.uvsq.fr/pub/perl/CPAN/ + +=item * + +Germany + + ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/ + ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/ + ftp://ftp.uni-erlangen.de/pub/source/CPAN/ + ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN + ftp://ftp.gigabell.net/pub/CPAN/ + http://ftp.gwdg.de/pub/languages/perl/CPAN/ + ftp://ftp.gwdg.de/pub/languages/perl/CPAN/ + ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/ + ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/ + ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/ + ftp://ftp.gmd.de/mirrors/CPAN/ + +=item * + +Greece + + ftp://ftp.forthnet.gr/pub/languages/perl/CPAN + ftp://ftp.ntua.gr/pub/lang/perl/ + +=item * + +Hungary + + http://cpan.artifact.hu/ + ftp://cpan.artifact.hu/CPAN/ + ftp://ftp.kfki.hu/pub/packages/perl/CPAN/ + +=item * + +Iceland + + http://cpan.gm.is/ + ftp://ftp.gm.is/pub/CPAN/ + +=item * + +Ireland + + http://cpan.indigo.ie/ + ftp://cpan.indigo.ie/pub/CPAN/ + http://sunsite.compapp.dcu.ie/pub/perl/ + ftp://sunsite.compapp.dcu.ie/pub/perl/ + +=item * + +Italy + + http://cpan.nettuno.it/ + http://gusp.dyndns.org/CPAN/ + ftp://gusp.dyndns.org/pub/CPAN + http://softcity.iol.it/cpan + ftp://softcity.iol.it/pub/cpan + ftp://ftp.unina.it/pub/Other/CPAN/ + ftp://ftp.unipi.it/pub/mirror/perl/CPAN/ + ftp://cis.uniRoma2.it/CPAN/ + ftp://ftp.edisontel.it/pub/CPAN_Mirror/ + ftp://ftp.flashnet.it/pub/CPAN/ + +=item * + +Latvia + + http://kvin.lv/pub/CPAN/ + +=item * + +Netherlands + + ftp://download.xs4all.nl/pub/mirror/CPAN/ + ftp://ftp.nl.uu.net/pub/CPAN/ + ftp://ftp.nluug.nl/pub/languages/perl/CPAN/ + ftp://ftp.cpan.nl/pub/CPAN/ + http://www.cs.uu.nl/mirror/CPAN/ + ftp://ftp.cs.uu.nl/mirror/CPAN/ + +=item * + +Norway + + ftp://sunsite.uio.no/pub/languages/perl/CPAN/ + ftp://ftp.uit.no/pub/languages/perl/cpan/ + +=item * + +Poland + + ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/ + ftp://ftp.mega.net.pl/pub/mirrors/ftp.perl.com/ + ftp://ftp.man.torun.pl/pub/doc/CPAN/ + ftp://sunsite.icm.edu.pl/pub/CPAN/ + +=item * + +Portugal + + ftp://ftp.ua.pt/pub/CPAN/ + ftp://perl.di.uminho.pt/pub/CPAN/ + ftp://ftp.ist.utl.pt/pub/CPAN/ + ftp://ftp.netc.pt/pub/CPAN/ + +=item * + +Romania + + ftp://archive.logicnet.ro/mirrors/ftp.cpan.org/CPAN/ + ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/ + ftp://ftp.dntis.ro/pub/cpan/ + ftp://ftp.opsynet.com/cpan/ + ftp://ftp.dnttm.ro/pub/CPAN/ + ftp://ftp.timisoara.roedu.net/mirrors/CPAN/ + +=item * + +Russia + + ftp://ftp.chg.ru/pub/lang/perl/CPAN/ + http://cpan.rinet.ru/ + ftp://cpan.rinet.ru/pub/mirror/CPAN/ + ftp://ftp.aha.ru/pub/CPAN/ + ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/ + +=item * + +Slovakia + + ftp://ftp.entry.sk/pub/languages/perl/CPAN/ + +=item * + +Slovenia + + ftp://ftp.arnes.si/software/perl/CPAN/ + +=item * + +Spain + + ftp://ftp.rediris.es/mirror/CPAN/ + ftp://ftp.etse.urv.es/pub/perl/ + +=item * + +Sweden + + http://ftp.du.se/CPAN/ + ftp://ftp.du.se/pub/CPAN/ + ftp://ftp.sunet.se/pub/lang/perl/CPAN/ + +=item * + +Switzerland + + ftp://ftp.danyk.ch/CPAN/ + ftp://sunsite.cnlab-switch.ch/mirror/CPAN/ + +=item * + +Turkey + + ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/ + +=back + +=head2 North America + +=over 4 + +=item * + +Canada + +=over 8 + +=item * + +Alberta + + http://sunsite.ualberta.ca/pub/Mirror/CPAN/ + ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/ + +=item * + +Manitoba + + http://theoryx5.uwinnipeg.ca/pub/CPAN/ + ftp://theoryx5.uwinnipeg.ca/pub/CPAN/ + +=item * + +Nova Scotia + + ftp://cpan.chebucto.ns.ca/pub/CPAN/ + +=item * + +Ontario + + ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/ + +=item * + +Mexico + + http://www.msg.com.mx/CPAN/ + ftp://ftp.msg.com.mx/pub/CPAN/ + +=back + +=item * + +United States + +=over 8 + +=item * + +Alabama + + http://mirror.hiwaay.net/CPAN/ + ftp://mirror.hiwaay.net/CPAN/ + +=item * + +California + + http://www.cpan.org/ + ftp://ftp.cpan.org/CPAN/ + ftp://cpan.nas.nasa.gov/pub/perl/CPAN/ + ftp://ftp.digital.com/pub/plan/perl/CPAN/ + http://www.kernel.org/pub/mirrors/cpan/ + ftp://ftp.kernel.org/pub/mirrors/cpan/ + http://www.perl.com/CPAN/ + http://download.sourceforge.net/mirrors/CPAN/ + +=item * + +Colorado + + ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ + +=item * + +Florida + + ftp://ftp.cise.ufl.edu/pub/perl/CPAN/ + +=item * + +Georgia + + ftp://ftp.twoguys.org/CPAN/ + +=item * + +Illinois + + http://www.neurogames.com/mirrors/CPAN + http://uiarchive.uiuc.edu/mirrors/ftp/ftp.cpan.org/pub/CPAN/ + ftp://uiarchive.uiuc.edu/mirrors/ftp/ftp.cpan.org/pub/CPAN/ + +=item * + +Indiana + + ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/ + http://cpan.nitco.com/ + ftp://cpan.nitco.com/pub/CPAN/ + ftp://cpan.in-span.net/ + http://csociety-ftp.ecn.purdue.edu/pub/CPAN + ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN + +=item * + +Kentucky + + http://cpan.uky.edu/ + ftp://cpan.uky.edu/pub/CPAN/ + +=item * + +Massachusetts + + ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/ + ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/ + +=item * + +New Jersey + + ftp://ftp.cpanel.net/pub/CPAN/ + +=item * + +New York + + ftp://ftp.freesoftware.com/pub/perl/CPAN/ + http://www.deao.net/mirrors/CPAN/ + ftp://ftp.deao.net/pub/CPAN/ + ftp://ftp.stealth.net/pub/mirrors/ftp.cpan.org/pub/CPAN/ + http://mirror.nyc.anidea.com/CPAN/ + ftp://mirror.nyc.anidea.com/pub/CPAN/ + http://www.rge.com/pub/languages/perl/ + ftp://ftp.rge.com/pub/languages/perl/ + ftp://mirrors.cloud9.net/pub/mirrors/CPAN/ + +=item * + +North Carolina + + ftp://ftp.duke.edu/pub/perl/ + +=item * + +Ohio + + ftp://ftp.loaded.net/pub/CPAN/ + +=item * + +Oklahoma + + ftp://ftp.ou.edu/mirrors/CPAN/ + +=item * + +Oregon + + ftp://ftp.orst.edu/pub/packages/CPAN/ + +=item * + +Pennsylvania + + http://ftp.epix.net/CPAN/ + ftp://ftp.epix.net/pub/languages/perl/ + ftp://carroll.cac.psu.edu/pub/CPAN/ + +=item * + +Tennessee + + ftp://ftp.sunsite.utk.edu/pub/CPAN/ + +=item * + +Texas + + http://ftp.sedl.org/pub/mirrors/CPAN/ + http://jhcloos.com/pub/mirror/CPAN/ + ftp://jhcloos.com/pub/mirror/CPAN/ + +=item * + +Utah + + ftp://mirror.xmission.com/CPAN/ + +=item * + +Virginia + + http://mirrors.rcn.net/pub/lang/CPAN/ + ftp://mirrors.rcn.net/pub/lang/CPAN/ + ftp://ruff.cs.jmu.edu/pub/CPAN/ + http://perl.Liquidation.com/CPAN/ + +=item * + +Washington + + http://cpan.llarian.net/ + ftp://cpan.llarian.net/pub/CPAN/ + ftp://ftp-mirror.internap.com/pub/CPAN/ + ftp://ftp.spu.edu/pub/CPAN/ + +=back + +=back + +=head2 Oceania + +=over 4 + +=item * + +Australia + + http://ftp.planetmirror.com/pub/CPAN/ + ftp://ftp.planetmirror.com/pub/CPAN/ + ftp://mirror.aarnet.edu.au/pub/perl/CPAN/ + ftp://cpan.topend.com.au/pub/CPAN/ + +=item * + +New Zealand + + ftp://ftp.auckland.ac.nz/pub/perl/CPAN/ + +=back + +=head2 South America + +=over 4 + +=item * + +Argentina + + ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/ + +=item * + +Brazil + + ftp://cpan.pop-mg.com.br/pub/CPAN/ + ftp://ftp.matrix.com.br/pub/perl/ + ftp://cpan.if.usp.br/pub/mirror/CPAN/ + +=item * + +Chile + + ftp://ftp.psinet.cl/pub/programming/perl/CPAN/ + ftp://sunsite.dcc.uchile.cl/pub/lang/perl/ =back For an up-to-date listing of CPAN sites, -see http://www.perl.com/perl/CPAN/SITES or ftp://www.perl.com/CPAN/SITES . +see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES . =head1 Modules: Creation, Use, and Abuse @@ -1102,14 +1583,16 @@ its methods by loading dynamic C or C++ objects, but that should be totally transparent to the user of the module. Likewise, the module might set up an AUTOLOAD function to slurp in subroutine definitions on demand, but this is also transparent. Only the F<.pm> file is required to -exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about +exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about the AUTOLOAD mechanism. =head2 Guidelines for Module Creation =over 4 -=item Do similar modules already exist in some form? +=item * + +Do similar modules already exist in some form? If so, please try to reuse the existing modules either in whole or by inheriting useful features into a new class. If this is not @@ -1123,28 +1606,30 @@ modules, please coordinate with the author of the package. It helps if you follow the same naming scheme and module interaction scheme as the original author. -=item Try to design the new module to be easy to extend and reuse. +=item * + +Try to design the new module to be easy to extend and reuse. Try to C<use warnings;> (or C<use warnings qw(...);>). Remember that you can add C<no warnings qw(...);> to individual blocks -of code that need less warnings. +of code that need less warnings. Use blessed references. Use the two argument form of bless to bless into the class name given as the first parameter of the constructor, e.g.,: sub new { - my $class = shift; - return bless {}, $class; + my $class = shift; + return bless {}, $class; } or even this if you'd like it to be used as either a static or a virtual method. sub new { - my $self = shift; - my $class = ref($self) || $self; - return bless {}, $class; + my $self = shift; + my $class = ref($self) || $self; + return bless {}, $class; } Pass arrays as references so more parameters can be added later @@ -1176,19 +1661,21 @@ Avoid keeping any state information in your packages. It makes it difficult for multiple other packages to use yours. Keep state information in objects. -Always use B<-w>. +Always use B<-w>. Try to C<use strict;> (or C<use strict qw(...);>). Remember that you can add C<no strict qw(...);> to individual blocks -of code that need less strictness. +of code that need less strictness. -Always use B<-w>. +Always use B<-w>. Follow the guidelines in the perlstyle(1) manual. Always use B<-w>. -=item Some simple style guidelines +=item * + +Some simple style guidelines The perlstyle manual supplied with Perl has many helpful points. @@ -1220,7 +1707,9 @@ e.g., C<< $obj->as_string() >>. You can use a leading underscore to indicate that a variable or function should not be used outside the package that defined it. -=item Select what to export. +=item * + +Select what to export. Do NOT export method names! @@ -1244,7 +1733,9 @@ As a general rule, if the module is trying to be object oriented then export nothing. If it's just a collection of functions then @EXPORT_OK anything but use @EXPORT with caution. -=item Select a name for the module. +=item * + +Select a name for the module. This name should be as descriptive, accurate, and complete as possible. Avoid any risk of ambiguity. Always try to use two or @@ -1268,11 +1759,19 @@ If adding a new module to a set, follow the original author's standards for naming modules and the interface to methods in those modules. +If developing modules for private internal or project specific use, +that will never be released to the public, then you should ensure +that their names will not clash with any future public module. You +can do this either by using the reserved Local::* category or by +using a category name that includes an underscore like Foo_Corp::*. + To be portable each component of a module name should be limited to 11 characters. If it might be used on MS-DOS then try to ensure each is unique in the first 8 characters. Nested modules make this easier. -=item Have you got it right? +=item * + +Have you got it right? How do you know that you've made the right decisions? Have you picked an interface design that will cause problems later? Have @@ -1291,7 +1790,9 @@ Don't worry about posting if you can't say when the module will be ready - just say so in the message. It might be worth inviting others to help you, they may be able to complete it for you! -=item README and other Additional Files. +=item * + +README and other Additional Files. It's well known that software developers usually fully document the software they write. If, however, the world is in urgent need of @@ -1301,24 +1802,31 @@ documentation please at least provide a README file containing: =over 10 =item * + A description of the module/package/extension etc. =item * + A copyright notice - see below. =item * + Prerequisites - what else you may need to have. =item * + How to build it - possible changes to Makefile.PL etc. =item * + How to install it. =item * + Recent changes in this release, especially incompatibilities =item * + Changes / enhancements you plan to make in the future. =back @@ -1331,6 +1839,7 @@ Copying, ToDo etc. =item Adding a Copyright Notice. + How you choose to license your work is a personal decision. The general mechanism is to assert your Copyright and then make a declaration of how others may copy/use/modify your work. @@ -1350,7 +1859,9 @@ This statement should at least appear in the README file. You may also wish to include it in a Copying file and your source files. Remember to include the other words in addition to the Copyright. -=item Give the module a version/issue/release number. +=item * + +Give the module a version/issue/release number. To be fully compatible with the Exporter and MakeMaker modules you should store your module's version number in a non-my package @@ -1364,14 +1875,16 @@ Use the number in announcements and archive file names when releasing the module (ModuleName-1.02.tar.Z). See perldoc ExtUtils::MakeMaker.pm for details. -=item How to release and distribute a module. +=item * + +How to release and distribute a module. It's good idea to post an announcement of the availability of your module (or the module itself if small) to the comp.lang.perl.announce Usenet newsgroup. This will at least ensure very wide once-off distribution. -If possible, register the module with CPAN. You should +If possible, register the module with CPAN. You should include details of its location in your announcement. Some notes about ftp archives: Please use a long descriptive file @@ -1387,8 +1900,8 @@ FTP Archives for Perl Modules: Follow the instructions and links on: - http://www.perl.com/CPAN/modules/00modlist.long.html - http://www.perl.com/CPAN/modules/04pause.html + http://www.cpan.org/modules/00modlist.long.html + http://www.cpan.org/modules/04pause.html or upload to one of these sites: @@ -1403,7 +1916,9 @@ CPAN! Please remember to send me an updated entry for the Module list! -=item Take care when changing a released module. +=item * + +Take care when changing a released module. Always strive to remain compatible with previous released versions. Otherwise try to add a mechanism to revert to the @@ -1417,26 +1932,34 @@ old behavior if people rely on it. Document incompatible changes. =over 4 -=item There is no requirement to convert anything. +=item * + +There is no requirement to convert anything. If it ain't broke, don't fix it! Perl 4 library scripts should continue to work with no problems. You may need to make some minor changes (like escaping non-array @'s in double quoted strings) but there is no need to convert a .pl file into a Module for just that. -=item Consider the implications. +=item * + +Consider the implications. All Perl applications that make use of the script will need to be changed (slightly) if the script is converted into a module. Is it worth it unless you plan to make other changes at the same time? -=item Make the most of the opportunity. +=item * + +Make the most of the opportunity. If you are going to convert the script to a module you can use the opportunity to redesign the interface. The guidelines for module creation above include many of the issues you should consider. -=item The pl2pm utility will get you started. +=item * + +The pl2pm utility will get you started. This utility will read *.pl files (given as parameters) and write corresponding *.pm files. The pl2pm utilities does the following: @@ -1444,15 +1967,19 @@ corresponding *.pm files. The pl2pm utilities does the following: =over 10 =item * + Adds the standard Module prologue lines =item * + Converts package specifiers from ' to :: =item * + Converts die(...) to croak(...) =item * + Several other minor changes =back @@ -1467,18 +1994,28 @@ Don't delete the original .pl file till the new .pm one works! =over 4 -=item Complete applications rarely belong in the Perl Module Library. +=item * + +Complete applications rarely belong in the Perl Module Library. + +=item * -=item Many applications contain some Perl code that could be reused. +Many applications contain some Perl code that could be reused. Help save the world! Share your code in a form that makes it easy to reuse. -=item Break-out the reusable code into one or more separate module files. +=item * + +Break-out the reusable code into one or more separate module files. + +=item * + +Take the opportunity to reconsider and redesign the interfaces. -=item Take the opportunity to reconsider and redesign the interfaces. +=item * -=item In some cases the 'application' can then be reduced to a small +In some cases the 'application' can then be reduced to a small fragment of code built on top of the reusable modules. In these cases the application could invoked as: diff --git a/contrib/perl5/pod/perlnumber.pod b/contrib/perl5/pod/perlnumber.pod index c83e053203d5..44d921cfe633 100644 --- a/contrib/perl5/pod/perlnumber.pod +++ b/contrib/perl5/pod/perlnumber.pod @@ -39,7 +39,7 @@ 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 respresented by a native float, since the binary fraction +0.9 cannot be represented by a native float, since the binary fraction for 0.9 is infinite: binary0.1110011001100... @@ -59,7 +59,7 @@ 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 I<storage> of these numbers. The fact that you can store such "large" numbers -does not mean that that the I<operations> over these numbers will use all +does not mean that the I<operations> over these numbers will use all of the significant digits. See L<"Numeric operators and numeric conversions"> for details.) @@ -91,7 +91,7 @@ Six such conversions are possible: These conversions are governed by the following general rules: -=over +=over 4 =item * @@ -141,7 +141,7 @@ argument as in modular arithmetic, e.g., C<mod 2**32> on a 32-bit architecture. C<sprintf "%u", -1> therefore provides the same result as C<sprintf "%u", ~0>. -=over +=over 4 =item Arithmetic operators except, C<no integer> diff --git a/contrib/perl5/pod/perlobj.pod b/contrib/perl5/pod/perlobj.pod index 4e45aff7c6a4..285ed9975eda 100644 --- a/contrib/perl5/pod/perlobj.pod +++ b/contrib/perl5/pod/perlobj.pod @@ -168,6 +168,12 @@ the method that was intended to be called. If none of that works, Perl finally gives up and complains. +If you want to stop the AUTOLOAD inheritance say simply + + sub AUTOLOAD; + +and the call will die using the name of the sub being called. + Perl classes do method inheritance only. Data inheritance is left up to the class itself. By and large, this is not a problem in Perl, because most classes model the attributes of their object using an @@ -553,8 +559,8 @@ breaks the circularities in the self-referential structure. =head1 SEE ALSO -A kinder, gentler tutorial on object-oriented programming in Perl -can be found in L<perltoot> and L<perltootc>. You should also check -out L<perlbot> for other object tricks, traps, and tips, as well -as L<perlmodlib> for some style guides on constructing both modules -and classes. +A kinder, gentler tutorial on object-oriented programming in Perl can +be found in L<perltoot>, L<perlbootc> and L<perltootc>. You should +also check out L<perlbot> for other object tricks, traps, and tips, as +well as L<perlmodlib> for some style guides on constructing both +modules and classes. diff --git a/contrib/perl5/pod/perlop.pod b/contrib/perl5/pod/perlop.pod index ce6fb66bc99d..9cae3a216365 100644 --- a/contrib/perl5/pod/perlop.pod +++ b/contrib/perl5/pod/perlop.pod @@ -119,7 +119,7 @@ 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 -C</^[a-zA-Z]*[0-9]*$/>, the increment is done as a string, preserving each +C</^[a-zA-Z]*[0-9]*\z/>, the increment is done as a string, preserving each character within its range, with carry: print ++($foo = '99'); # prints '100' @@ -196,7 +196,7 @@ C<$a> minus the largest multiple of C<$b> that is not greater than C<$a>. If C<$b> is negative, then C<$a % $b> is C<$a> minus the smallest multiple of C<$b> that is not less than C<$a> (i.e. the result will be less than or equal to zero). -Note than when C<use integer> is in scope, "%" give you direct access +Note than when C<use integer> is in scope, "%" gives you direct access to the modulus operator as implemented by your C compiler. This operator is not as well defined for negative operands, but it will execute faster. @@ -242,14 +242,15 @@ operators, like C<-f>, C<-M>, etc. See L<perlfunc>. If any list operator (print(), etc.) or any unary operator (chdir(), 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. Examples: +just like a normal function call. For example, +because named unary operators are higher precedence than ||: chdir $foo || die; # (chdir $foo) || die chdir($foo) || die; # (chdir $foo) || die chdir ($foo) || die; # (chdir $foo) || die chdir +($foo) || die; # (chdir $foo) || die -but, because * is higher precedence than ||: +but, because * is higher precedence than named operators: chdir $foo * 20; # chdir ($foo * 20) chdir($foo) * 20; # (chdir $foo) * 20 @@ -299,7 +300,14 @@ to the right argument. Binary "<=>" returns -1, 0, or 1 depending on whether the left argument is numerically less than, equal to, or greater than the right -argument. +argument. If your platform supports NaNs (not-a-numbers) as numeric +values, using them with "<=>" returns undef. NaN is not "<", "==", ">", +"<=" or ">=" anything (even NaN), so those 5 return false. NaN != NaN +returns true, as does NaN != anything else. If your platform doesn't +support NaNs then NaN is just a string with numeric value 0. + + perl -le '$a = NaN; print "No NaN support here" if $a == $a' + perl -le '$a = NaN; print "NaN support here" if $a != $a' Binary "eq" returns true if the left argument is stringwise equal to the right argument. @@ -307,8 +315,9 @@ the right argument. Binary "ne" returns true if the left argument is stringwise not equal to the right argument. -Binary "cmp" returns -1, 0, or 1 depending on whether the left argument is stringwise -less than, equal to, or greater than the right argument. +Binary "cmp" returns -1, 0, or 1 depending on whether the left +argument is stringwise less than, equal to, or greater than the right +argument. "lt", "le", "ge", "gt" and "cmp" use the collation (sort) order specified by the current locale if C<use locale> is in effect. See L<perllocale>. @@ -707,7 +716,7 @@ on a Mac, these are reversed, and on systems without line terminator, printing C<"\n"> may emit no actual data. In general, use C<"\n"> when you mean a "newline" for your system, but use the literal ASCII when you need an exact character. For example, most networking protocols expect -and prefer a CR+LF (C<"\012\015"> or C<"\cJ\cM">) for line terminators, +and prefer a CR+LF (C<"\015\012"> or C<"\cM\cJ">) for line terminators, and although they often accept just C<"\012">, they seldom tolerate just C<"\015">. If you get in the habit of using C<"\n"> for networking, you may be burned some day. @@ -752,7 +761,7 @@ patterns local to the current package are reset. reset if eof; # clear ?? status for next file } -This usage is vaguely depreciated, which means it just might possibly +This usage is vaguely deprecated, which means it just might possibly be removed in some distant future version of Perl, perhaps somewhere around the year 2168. @@ -788,14 +797,14 @@ If "'" is the delimiter, no interpolation is performed on the PATTERN. PATTERN may contain variables, which will be interpolated (and the pattern recompiled) every time the pattern search is evaluated, except -for when the delimiter is a single quote. (Note that C<$)> and C<$|> -might not be interpolated because they look like end-of-string tests.) +for when the delimiter is a single quote. (Note that C<$(>, C<$)>, and +C<$|> are not interpolated because they look like end-of-string tests.) If you want such a pattern to be compiled only once, add a C</o> after the trailing delimiter. This avoids expensive run-time recompilations, and is useful when the value you are interpolating won't change over the life of the script. However, mentioning C</o> constitutes a promise that you won't change the variables in the pattern. If you change them, -Perl won't even notice. See also L<"qr//">. +Perl won't even notice. See also L<"qr/STRING/imosx">. If the PATTERN evaluates to the empty string, the last I<successfully> matched regular expression is used instead. @@ -848,9 +857,11 @@ string also resets the search position. You can intermix C<m//g> matches with C<m/\G.../g>, where C<\G> is a zero-width assertion that matches the exact position where the previous -C<m//g>, if any, left off. The C<\G> assertion is not supported without -the C</g> modifier. (Currently, without C</g>, C<\G> behaves just like -C<\A>, but that's accidental and may change in the future.) +C<m//g>, if any, left off. Without the C</g> modifier, the C<\G> assertion +still anchors at pos(), but the match is of course only attempted once. +Using C<\G> without C</g> on a target string that has not previously had a +C</g> match applied to it is the same as using the C<\A> assertion to match +the beginning of the string. Examples: @@ -858,7 +869,7 @@ Examples: ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g); # scalar context - $/ = ""; $* = 1; # $* deprecated in modern perls + $/ = ""; while (defined($paragraph = <>)) { while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) { $sentences++; @@ -876,6 +887,7 @@ Examples: print "3: '"; print $1 while /(p)/gc; print "', pos=", pos, "\n"; } + print "Final: '$1', pos=",pos,"\n" if /\G(.)/; The last example should print: @@ -885,6 +897,13 @@ The last example should print: 1: '', pos=7 2: 'q', pos=8 3: '', pos=8 + Final: 'q', pos=8 + +Notice that the final match matched C<q> instead of C<p>, which a match +without the C<\G> anchor would have done. Also note that the final match +did not update C<pos> -- C<pos> is only updated on a C</g> match. If the +final match did indeed match C<p>, it's a good bet that you're running an +older (pre-5.6.0) Perl. A useful idiom for C<lex>-like scanners is C</\G.../gc>. You can combine several regexps like this to process a string part-by-part, @@ -938,7 +957,7 @@ A double-quoted, interpolated string. =item qr/STRING/imosx -This operators quotes--and compiles--its I<STRING> as a regular +This operator quotes (and possibly compiles) its I<STRING> as a regular expression. I<STRING> is interpolated the same way as I<PATTERN> in C<m/PATTERN/>. If "'" is used as the delimiter, no interpolation is done. Returns a Perl value which may be used instead of the @@ -997,13 +1016,14 @@ for a detailed look at the semantics of regular expressions. =item `STRING` -A string which is (possibly) interpolated and then executed as a system -command with C</bin/sh> or its equivalent. Shell wildcards, pipes, -and redirections will be honored. The collected standard output of the -command is returned; standard error is unaffected. In scalar context, -it comes back as a single (potentially multi-line) string. In list -context, returns a list of lines (however you've defined lines with $/ -or $INPUT_RECORD_SEPARATOR). +A string which is (possibly) interpolated and then executed as a +system command with C</bin/sh> or its equivalent. Shell wildcards, +pipes, and redirections will be honored. The collected standard +output of the command is returned; standard error is unaffected. In +scalar context, it comes back as a single (potentially multi-line) +string, or undef if the command failed. In list context, returns a +list of lines (however you've defined lines with $/ or +$INPUT_RECORD_SEPARATOR), or an empty list if the command failed. Because backticks do not affect standard error, use shell file descriptor syntax (assuming the shell supports this) if you care to address this. @@ -1207,9 +1227,9 @@ to occur that you might want. Here are two common cases: # expand tabs to 8-column spacing 1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e; -=item tr/SEARCHLIST/REPLACEMENTLIST/cdsUC +=item tr/SEARCHLIST/REPLACEMENTLIST/cds -=item y/SEARCHLIST/REPLACEMENTLIST/cdsUC +=item y/SEARCHLIST/REPLACEMENTLIST/cds Transliterates all occurrences of the characters found in the search list with the corresponding character in the replacement list. It returns @@ -1225,6 +1245,12 @@ SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has its own pair of quotes, which may or may not be bracketing quotes, e.g., C<tr[A-Z][a-z]> or C<tr(+\-*/)/ABCD/>. +Note that C<tr> does B<not> do regular expression character classes +such as C<\d> or C<[:lower:]>. The <tr> operator is not equivalent to +the tr(1) utility. If you want to map strings between lower/upper +cases, see L<perlfunc/lc> and L<perlfunc/uc>, and in general consider +using the C<s> operator if you need regular expressions. + 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 @@ -1237,8 +1263,6 @@ Options: c Complement the SEARCHLIST. d Delete found but unreplaced characters. s Squash duplicate replaced characters. - U Translate to/from UTF-8. - C Translate to/from 8-bit char (octet). If the C</c> modifier is specified, the SEARCHLIST character set is complemented. If the C</d> modifier is specified, any characters @@ -1256,10 +1280,6 @@ enough. If the REPLACEMENTLIST is empty, the SEARCHLIST is replicated. This latter is useful for counting characters in a class or for squashing character sequences in a class. -The first C</U> or C</C> modifier applies to the left side of the translation. -The second one applies to the right side. If present, these modifiers override -the current utf8 state. - Examples: $ARGV[1] =~ tr/A-Z/a-z/; # canonicalize to lower case @@ -1279,9 +1299,6 @@ Examples: tr [\200-\377] [\000-\177]; # delete 8th bit - tr/\0-\xFF//CU; # change Latin-1 to Unicode - tr/\0-\x{FF}//UC; # change Unicode to Latin-1 - If multiple transliterations are given for a character, only the first one is used: @@ -1327,7 +1344,7 @@ their results are the same, we consider them individually. For different quoting constructs, Perl performs different numbers of passes, from one to five, but these passes are always performed in the same order. -=over +=over 4 =item Finding the end @@ -1381,7 +1398,7 @@ used in parsing. The next step is interpolation in the text obtained, which is now delimiter-independent. There are four different cases. -=over +=over 4 =item C<<<'EOF'>, C<m''>, C<s'''>, C<tr///>, C<y///> @@ -1412,7 +1429,7 @@ as C<"\\\t"> (since TAB is not alphanumeric). Note also that: may be closer to the conjectural I<intention> of the writer of C<"\Q\t\E">. Interpolated scalars and arrays are converted internally to the C<join> and -C<.> catentation operations. Thus, C<"$foo XXX '@arr'"> becomes: +C<.> catenation operations. Thus, C<"$foo XXX '@arr'"> becomes: $foo . " XXX '" . (join $", @arr) . "'"; @@ -1546,19 +1563,19 @@ There are several I/O operators you should know about. 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 -pseudo-literal, j -string consisting of all output is returned. In list context, a -list of values is returned, one per line of output. (You can set -C<$/> 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 C<$?> (see L<perlvar> for the interpretation -of C<$?>). Unlike in B<csh>, 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 C<qx//>. -(Because backticks always undergo shell expansion as well, see -L<perlsec> for security concerns.) +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 C<$/> 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 C<$?> (see L<perlvar> for the interpretation of C<$?>). +Unlike in B<csh>, 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 C<qx//>. (Because +backticks always undergo shell expansion as well, see L<perlsec> for +security concerns.) In scalar context, evaluating a filehandle in angle brackets yields the next line from that file (the newline, if any, included), or @@ -1573,7 +1590,7 @@ of a C<while> statement (even if disguised as a C<for(;;)> loop), the value is automatically assigned to the global variable $_, 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 $_ variables is not implicitly localized. +script you write.) The $_ variable is not implicitly localized. You'll have to put a C<local $_;> before the loop if you want that to happen. @@ -1718,7 +1735,7 @@ is roughly equivalent to: open(FOO, "echo *.c | tr -s ' \t\r\f' '\\012\\012\\012\\012'|"); while (<FOO>) { - chop; + chomp; chmod 0644, $_; } @@ -1731,7 +1748,7 @@ 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 C +the next value each time it's called, or C<undef> when the list has run out. As with filehandle reads, an automatic C<defined> is generated when the glob occurs in the test part of a C<while>, because legal glob returns (e.g. a file called F<0>) would otherwise @@ -1831,8 +1848,8 @@ integer>, if you take the C<sqrt(2)>, you'll still get C<1.4142135623731> or so. Used on numbers, the bitwise operators ("&", "|", "^", "~", "<<", -and ">>") always produce integral results. (But see also L<Bitwise -String Operators>.) However, C<use integer> still has meaning for +and ">>") always produce integral results. (But see also +L<Bitwise String Operators>.) However, C<use integer> still has meaning for them. By default, their results are interpreted as unsigned integers, but if C<use integer> is in effect, their results are interpreted as signed integers. For example, C<~0> usually evaluates to a large @@ -1885,7 +1902,7 @@ need yourself. The standard Math::BigInt and Math::BigFloat modules provide variable-precision arithmetic and overloaded operators, although -they're currently pretty slow. At the cost of some space and +they're currently pretty slow. At the cost of some space and considerable speed, they avoid the normal pitfalls associated with limited-precision representations. @@ -1895,8 +1912,25 @@ limited-precision representations. # prints +15241578780673678515622620750190521 -The non-standard modules SSLeay::BN and Math::Pari provide -equivalent functionality (and much more) with a substantial -performance savings. +There are several modules that let you calculate with (bound only by +memory and cpu-time) unlimited or fixed precision. There are also +some non-standard modules that provide faster implementations via +external C libraries. + +Here is a short, but incomplete summary: + + Math::Fraction big, unlimited fractions like 9973 / 12967 + Math::String treat string sequences like numbers + Math::FixedPrecision calculate with a fixed precision + Math::Currency for currency calculations + Bit::Vector manipulate bit vectors fast (uses C) + Math::BigIntFast Bit::Vector wrapper for big numbers + Math::Pari provides access to the Pari C library + Math::BigInteger uses an external C library + Math::Cephes uses external Cephes C library (no big numbers) + Math::Cephes::Fraction fractions via the Cephes library + Math::GMP another one using an external C library + +Choose wisely. =cut diff --git a/contrib/perl5/pod/perlopentut.pod b/contrib/perl5/pod/perlopentut.pod index 9cb9f6738a7a..b4003f4f2efb 100644 --- a/contrib/perl5/pod/perlopentut.pod +++ b/contrib/perl5/pod/perlopentut.pod @@ -73,8 +73,8 @@ from a different file, and forget to trim it before opening: This is not a bug, but a feature. Because C<open> mimics the shell in its style of using redirection arrows to specify how to open the file, it also does so with respect to extra white space around the filename itself -as well. For accessing files with naughty names, see L<"Dispelling -the Dweomer">. +as well. For accessing files with naughty names, see +L<"Dispelling the Dweomer">. =head2 Pipe Opens @@ -107,13 +107,13 @@ In most systems, such an C<open> will not return an error. That's because in the traditional C<fork>/C<exec> model, running the other program happens only in the forked child process, which means that the failed C<exec> can't be reflected in the return value of C<open>. -Only a failed C<fork> shows up there. See L<perlfaq8/"Why doesn't open() -return an error when a pipe open fails?"> to see how to cope with this. -There's also an explanation in L<perlipc>. +Only a failed C<fork> shows up there. See +L<perlfaq8/"Why doesn't open() return an error when a pipe open fails?"> +to see how to cope with this. There's also an explanation in L<perlipc>. If you would like to open a bidirectional pipe, the IPC::Open2 -library will handle this for you. Check out L<perlipc/"Bidirectional -Communication with Another Process"> +library will handle this for you. Check out +L<perlipc/"Bidirectional Communication with Another Process"> =head2 The Minus File @@ -126,8 +126,8 @@ access the standard output. If minus can be used as the default input or default output, what happens if you open a pipe into or out of minus? What's the default command it would run? The same script as you're currently running! This is actually -a stealth C<fork> hidden inside an C<open> call. See L<perlipc/"Safe Pipe -Opens"> for details. +a stealth C<fork> hidden inside an C<open> call. See +L<perlipc/"Safe Pipe Opens"> for details. =head2 Mixing Reads and Writes @@ -309,7 +309,7 @@ C<O_DEFER>, C<O_SYNC>, C<O_ASYNC>, C<O_DSYNC>, C<O_RSYNC>, C<O_NOCTTY>, C<O_NDELAY> and C<O_LARGEFILE>. Consult your open(2) manpage or its local equivalent for details. (Note: starting from Perl release 5.6 the O_LARGEFILE flag, if available, is automatically -added to the sysopen() flags because large files are the the default.) +added to the sysopen() flags because large files are the default.) Here's how to use C<sysopen> to emulate the simple C<open> calls we had before. We'll omit the C<|| die $!> checks for clarity, but make sure @@ -684,9 +684,9 @@ also some high-level modules on CPAN that can help you with these games. Check out Term::ReadKey and Term::ReadLine. What else can you open? To open a connection using sockets, you won't use -one of Perl's two open functions. See L<perlipc/"Sockets: Client/Server -Communication"> for that. Here's an example. Once you have it, -you can use FH as a bidirectional filehandle. +one of Perl's two open functions. See +L<perlipc/"Sockets: Client/Server Communication"> for that. Here's an +example. Once you have it, you can use FH as a bidirectional filehandle. use IO::Socket; local *FH = IO::Socket::INET->new("www.perl.com:80"); diff --git a/contrib/perl5/pod/perlpod.pod b/contrib/perl5/pod/perlpod.pod index 6c0c5348c4db..1076ffe4cb03 100644 --- a/contrib/perl5/pod/perlpod.pod +++ b/contrib/perl5/pod/perlpod.pod @@ -63,15 +63,17 @@ Item, over, and back require a little more explanation: "=over" starts a section specifically for the generation of a list using "=item" commands. At the end of your list, use "=back" to end it. You will probably want to give "4" as the number to "=over", as some formatters will use this for indentation. -This should probably be a default. Note also that there are some basic rules -to using =item: don't use them outside of an =over/=back block, use at least -one inside an =over/=back block, you don't _have_ to include the =back if -the list just runs off the document, 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., i.e., things that looks nothing like bullets -or numbers. If you start with bullets or numbers, stick with them, as many -formatters use the first "=item" type to decide how to format the list. +The unit of indentation is optional. If the unit is not given the natural +indentation of the formatting system applied will be used. Note also that +there are some basic rules to using =item: don't use them outside of +an =over/=back block, use at least one inside an =over/=back block, you don't +_have_ to include the =back if the list just runs off the document, 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., i.e., things +that looks nothing like bullets or numbers. If you start with bullets or +numbers, stick with them, as many formatters use the first "=item" type to +decide how to format the list. =item =for diff --git a/contrib/perl5/pod/perlport.pod b/contrib/perl5/pod/perlport.pod index 6892b6a777f2..9ae89e0799a0 100644 --- a/contrib/perl5/pod/perlport.pod +++ b/contrib/perl5/pod/perlport.pod @@ -94,6 +94,26 @@ from) C<\015\012>, depending on whether you're reading or writing. Unix does the same thing on ttys in canonical mode. C<\015\012> is commonly referred to as CRLF. +A common cause of unportable programs is the misuse of chop() to trim +newlines: + + # XXX UNPORTABLE! + while(<FILE>) { + chop; + @array = split(/:/); + #... + } + +You can get away with this on Unix and MacOS (they have a single +character end-of-line), but the same program will break under DOSish +perls because you're only chop()ing half the end-of-line. Instead, +chomp() should be used to trim newlines. The Dunce::Files module can +help audit your code for misuses of chop(). + +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 chomp(). + Because of the "text" mode translation, DOSish perls have limitations in using C<seek> and C<tell> on a file accessed in "text" mode. Stick to C<seek>-ing to locations you got from C<tell> (and no @@ -181,10 +201,12 @@ numbers to secondary storage such as a disk file or tape. Conflicting storage orders make utter mess out of the numbers. If a little-endian host (Intel, VAX) stores 0x12345678 (305419896 in -decimal), a big-endian host (Motorola, MIPS, Sparc, PA) reads it as -0x78563412 (2018915346 in decimal). To avoid this problem in network -(socket) connections use the C<pack> and C<unpack> formats C<n> -and C<N>, the "network" orders. These are guaranteed to be portable. +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 C<pack> and C<unpack> formats C<n> and C<N>, the +"network" orders. These are guaranteed to be portable. You can explore the endianness of your platform by unpacking a data structure packed in native format such as: @@ -197,7 +219,7 @@ If you need to distinguish between endian architectures you could use either of the variables set like so: $is_big_endian = unpack("h*", pack("s", 1)) =~ /01/; - $is_litte_endian = unpack("h*", pack("s", 1)) =~ /^1/; + $is_little_endian = unpack("h*", pack("s", 1)) =~ /^1/; Differing widths can cause truncation even between platforms of equal endianness. The platform of shorter width loses the upper parts of the @@ -217,7 +239,7 @@ 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. -Atlhough similar, file path specifications differ between Unix, +Although similar, file path specifications differ between Unix, Windows, S<Mac OS>, OS/2, VMS, VOS, S<RISC OS>, and probably others. Unix, for example, is one of the few OSes that has the elegant idea of a single root directory. @@ -332,7 +354,10 @@ operating systems put mandatory locks on such files. Don't count on a specific environment variable existing in C<%ENV>. Don't count on C<%ENV> entries being case-sensitive, or even -case-preserving. +case-preserving. Don't try to clear %ENV by saying C<%ENV = ();>, or, +if you really have to, make it conditional on C<$^O ne 'VMS'> since in +VMS the C<%ENV> table is much more than a per-process key-value string +table. Don't count on signals or C<%SIG> for anything. @@ -355,7 +380,7 @@ 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, migth accept +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 @@ -650,6 +675,15 @@ DOSish perls are as follows: Windows NT MSWin32 MSWin32-ppc Cygwin cygwin +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 +Win32::GetOSVersion(). For example: + + if ($^O eq 'MSWin32') { + my @os_version_info = Win32::GetOSVersion(); + print +('3.1','95','NT')[$os_version_info[4]],"\n"; + } + Also see: =over 4 @@ -681,15 +715,16 @@ The ActiveState Pages, http://www.activestate.com/ =item * The Cygwin environment for Win32; F<README.cygwin> (installed -as L<perlcygwin>), http://sourceware.cygnus.com/cygwin/ +as L<perlcygwin>), http://www.cygwin.com/ =item * The U/WIN environment for Win32, -<http://www.research.att.com/sw/tools/uwin/ +http://www.research.att.com/sw/tools/uwin/ -=item Build instructions for OS/2, L<perlos2> +=item * +Build instructions for OS/2, L<perlos2> =back @@ -888,9 +923,9 @@ vmsperl on the web, http://www.sidhe.org/vmsperl/index.html =head2 VOS -Perl on VOS is discussed in F<README.vos> in the perl distribution. -Perl on VOS can accept either VOS- or Unix-style file -specifications as in either of the following: +Perl on VOS is discussed in F<README.vos> in the perl distribution +(installed as L<perlvos>). Perl on VOS can accept either VOS- or +Unix-style file specifications as in either of the following: $ perl -ne "print if /perl_setup/i" >system>notices $ perl -ne "print if /perl_setup/i" /system/notices @@ -906,12 +941,11 @@ contain a slash character cannot be processed. Such files must be renamed before they can be processed by Perl. Note that VOS limits file names to 32 or fewer characters. -The following C functions are unimplemented on VOS, and any attempt by -Perl to use them will result in a fatal error message and an immediate -exit from Perl: dup, do_aspawn, do_spawn, fork, waitpid. Once these -functions become available in the VOS POSIX.1 implementation, you can -either recompile and rebind Perl, or you can download a newer port from -ftp.stratus.com. +See F<README.vos> for restrictions that apply when Perl is built +with the alpha version of VOS POSIX.1 support. + +Perl on VOS is built without any extensions and does not support +dynamic loading. The value of C<$^O> on VOS is "VOS". To determine the architecture that you are running on without resorting to loading all of C<%Config> you @@ -1042,7 +1076,8 @@ Also see: * -L<perlos390>, F<README.os390>, F<README.posix-bc>, F<README.vmesa> +L<perlos390>, F<README.os390>, F<perlbs2000>, F<README.vmesa>, +L<perlebcdic>. =item * @@ -1053,7 +1088,7 @@ general usage issues for all EBCDIC Perls. Send a message body of =item * AS/400 Perl information at -ttp://as400.rochester.ibm.com/ +http://as400.rochester.ibm.com/ as well as on CPAN in the F<ports/> directory. =back @@ -1200,7 +1235,7 @@ Be OS, F<README.beos> =item * HP 300 MPE/iX, F<README.mpeix> and Mark Bixby's web page -http://www.cccd.edu/~markb/perlix.html +http://www.bixby.org/mark/perlix.html =item * @@ -1208,7 +1243,7 @@ A free perl5-based PERL.NLM for Novell Netware is available in precompiled binary and source code form from http://www.novell.com/ as well as from CPAN. -=item +=item * Plan 9, F<README.plan9> @@ -1640,6 +1675,10 @@ Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS, VM/ESA) =item stat +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. + mtime and atime are the same thing, and ctime is creation time instead of inode change time. (S<Mac OS>) @@ -1650,6 +1689,9 @@ device and inode are not necessarily reliable. (VMS) mtime, atime and ctime all return the last modification time. Device and inode are not necessarily reliable. (S<RISC OS>) +dev, rdev, blksize, and blocks are not available. inode is not +meaningful and will differ between stat calls on the same file. (os2) + =item symlink OLDFILE,NEWFILE Not implemented. (Win32, VMS, S<RISC OS>) @@ -1746,7 +1788,7 @@ two seconds. (Win32) Not implemented. (S<Mac OS>, VOS) Can only be applied to process handles returned for processes spawned -using C<system(1, ...)>. (Win32) +using C<system(1, ...)> or pseudo processes created with C<fork()>. (Win32) Not useful. (S<RISC OS>) @@ -1756,6 +1798,11 @@ Not useful. (S<RISC OS>) =over 4 +=item v1.48, 02 February 2001 + +Various updates from perl5-porters over the past year, supported +platforms update from Jarkko Hietaniemi. + =item v1.47, 22 March 2000 Various cleanups from Tom Christiansen, including migration of @@ -1838,96 +1885,98 @@ First public release with perl5.005. =head1 Supported Platforms -As of early March 2000 (the Perl release 5.6.0), the following -platforms are able to build Perl from the standard source code -distribution available at http://www.perl.com/CPAN/src/index.html +As of early 2001 (the Perl release 5.6.1), the following platforms are +able to build Perl from the standard source code distribution +available at http://www.perl.com/CPAN/src/index.html AIX + AmigaOS + Darwin (Rhapsody) + DG/UX DOS DJGPP 1) + DYNIX/ptx + EPOC FreeBSD HP-UX IRIX Linux - LynxOS MachTen - MPE/iX - NetBSD + MacOS Classic 2) + NonStop-UX + ReliantUNIX (SINIX) OpenBSD + OpenVMS (VMS) OS/2 + OS X QNX - Rhapsody/Darwin 2) - SCO SV - SINIX Solaris - SVR4 - Tru64 UNIX 3) + Tru64 UNIX (DEC OSF/1, Digital UNIX) UNICOS UNICOS/mk - Unixware - VMS VOS - Windows 3.1 1) - Windows 95 1) 4) - Windows 98 1) 4) - Windows NT 1) 4) + Win32/NT/2K 3) 1) in DOS mode either the DOS or OS/2 ports can be used - 2) new in 5.6.0: the BSD/NeXT-based UNIX of Mac OS X - 3) formerly known as Digital UNIX and before that DEC OSF/1 - 4) compilers: Borland, Cygwin, Mingw32 EGCS/GCC, VC++ + 2) Mac OS Classic (pre-X) is almost 5.6.1-ready; building from + the source does work with 5.6.1, but additional MacOS specific + source code is needed for a complete build. Contact the mailing + list macperl-porters@macperl.org for more information. + 3) compilers: Borland, Cygwin, Mingw32 EGCS/GCC, VC++ -The following platforms worked for the previous major release -(5.005_03 being the latest maintenance release of that, as of early -March 2000), but be did not manage to test these in time for the 5.6.0 -release of Perl. There is a very good chance that these will work -just fine with 5.6.0. +The following platforms worked for the previous release (5.6.0), +but we did not manage to test these in time for the 5.6.1 release. +There is a very good chance that these will work fine with 5.6.1. - A/UX - BeOS - BSD/OS - DG/UX - DYNIX/ptx DomainOS Hurd - NextSTEP - OpenSTEP + LynxOS + MinGW + MPE/iX + NetBSD PowerMAX - SCO ODT/OSR + SCO SV SunOS - Ultrix + SVR4 + Unixware + Windows 3.1 + Windows 95 + Windows 98 + Windows Me -The following platform worked for the previous major release (5.005_03 -being the latest maintenance release of that, as of early March 2000). -However, standardization on UTF-8 as the internal string representation -in 5.6.0 has introduced incompatibilities in this EBCDIC platform. -Support for this platform may be enabled in a future release: +The following platform worked for the 5.005_03 major release but not +5.6.0. Standardization on UTF-8 as the internal string representation +in 5.6.0 and 5.6.1 has introduced incompatibilities in this EBCDIC +platform. While Perl 5.6.1 will build on this platform some +regression tests may fail and the C<use utf8;> pragma typically +introduces text handling errors. UTF-8 support for this platform may +be enabled in a future release: - OS390 1) + OS/390 1) - 1) Previously known as MVS, or OpenEdition MVS. + 1) previously known as MVS, about to become z/OS. -Strongly related to the OS390 platform by also being EBCDIC-based +Strongly related to the OS/390 platform by also being EBCDIC-based mainframe platforms are the following platforms: - BS2000 + POSIX-BC (BS2000) VM/ESA -These are also not expected to work under 5.6.0 for the same reasons -as OS390. Contact the mailing list perl-mvs@perl.org for more details. - -MacOS (Classic, pre-X) is almost 5.6.0-ready; building from the source -does work with 5.6.0, but additional MacOS specific source code is needed -for a complete port. Contact the mailing list macperl-porters@macperl.org -for more information. +These are also expected to work, albeit with no UTF-8 support, under 5.6.1 +for the same reasons as OS/390. Contact the mailing list perl-mvs@perl.org +for more details. The following platforms have been known to build Perl from source in -the past, 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: +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 perlbug@perl.org +of any trouble. 3b1 - AmigaOS + A/UX + BeOS + BSD/OS ConvexOS CX/UX DC/OSx @@ -1944,16 +1993,21 @@ platforms--or both: MiNT MPC NEWS-OS + NextSTEP + OpenSTEP Opus Plan 9 PowerUX RISC/os + SCO ODT/OSR Stellar SVR2 TI1500 TitanOS + Ultrix Unisys Dynix Unixware + UTS Support for the following platform is planned for a future Perl release: @@ -1964,8 +2018,8 @@ binaries available via http://www.perl.com/CPAN/ports/index.html: Perl release - AS/400 5.003 Netware 5.003_07 + OS/400 5.005_02 Tandem Guardian 5.004 The following platforms have only binaries available via @@ -1984,8 +2038,9 @@ http://www.perl.com/CPAN/ports/index.html for binary distributions. =head1 SEE ALSO -L<perlamiga>, L<perlcygwin>, L<perldos>, L<perlhpux>, L<perlos2>, -L<perlos390>, L<perlwin32>, L<perlvms>, and L<Win32>. +L<perlaix>, L<perlamiga>, L<perlcygwin>, L<perldos>, L<perlepoc>, +L<perlebcdic>, L<perlhpux>, L<perlos2>, L<perlos390>, L<perlbs2000>, +L<perlwin32>, L<perlvms>, L<perlvos>, and L<Win32>. =head1 AUTHORS / CONTRIBUTORS @@ -2001,7 +2056,7 @@ Neale Ferguson <neale@mailbox.tabnsw.com.au>, David J. Fiander <davidf@mks.com>, Paul Green <Paul_Green@stratus.com>, M.J.T. Guy <mjtg@cus.cam.ac.uk>, -Jarkko Hietaniemi <jhi@iki.fi<gt>, +Jarkko Hietaniemi <jhi@iki.fi>, Luther Huffman <lutherh@stratcom.com>, Nick Ing-Simmons <nick@ni-s.u-net.com>, Andreas J. KE<ouml>nig <koenig@kulturbox.de>, diff --git a/contrib/perl5/pod/perlre.pod b/contrib/perl5/pod/perlre.pod index e1f30a324aff..ce2b9bd952e6 100644 --- a/contrib/perl5/pod/perlre.pod +++ b/contrib/perl5/pod/perlre.pod @@ -40,7 +40,7 @@ is, no matter what C<$*> contains, C</s> without C</m> will force "^" to match only at the beginning of the string and "$" to match only at the end (or just before a newline at the end) of the string. Together, as /ms, they let the "." match any character whatsoever, -while yet allowing "^" and "$" to match, respectively, just after +while still allowing "^" and "$" to match, respectively, just after and just before newlines within the string. =item x @@ -169,7 +169,7 @@ You'll need to write something like C<m/\Quser\E\@\Qhost/>. In addition, Perl defines the following: \w Match a "word" character (alphanumeric plus "_") - \W Match a non-word character + \W Match a non-"word" character \s Match a whitespace character \S Match a non-whitespace character \d Match a digit character @@ -180,7 +180,7 @@ In addition, Perl defines the following: equivalent to C<(?:\PM\pM*)> \C Match a single C char (octet) even under utf8. -A C<\w> matches a single alphanumeric character, not a whole word. +A C<\w> matches a single alphanumeric character or C<_>, not a whole word. Use C<\w+> to match a string of Perl-identifier characters (which isn't the same as matching an English word). If C<use locale> is in effect, the list of alphabetic characters generated by C<\w> is taken from the @@ -199,38 +199,47 @@ equivalents (if available) are as follows: alpha alnum ascii + blank [1] cntrl digit \d graph lower print punct - space \s + space \s [2] upper - word \w + word \w [3] xdigit + [1] A GNU extension equivalent to C<[ \t]>, `all horizontal whitespace'. + [2] Not I<exactly equivalent> to C<\s> since the C<[[:space:]]> includes + also the (very rare) `vertical tabulator', "\ck", chr(11). + [3] A Perl extension. + For example use C<[:upper:]> to match all the uppercase characters. -Note that the C<[]> are part of the C<[::]> construct, not part of the whole -character class. For example: +Note that the C<[]> are part of the C<[::]> construct, not part of the +whole character class. For example: [01[:alpha:]%] -matches one, zero, any alphabetic character, and the percentage sign. +matches zero, one, any alphabetic character, and the percentage sign. If the C<utf8> pragma is used, the following equivalences to Unicode -\p{} constructs hold: +\p{} constructs and equivalent backslash character classes (if available), +will hold: alpha IsAlpha alnum IsAlnum ascii IsASCII + blank IsSpace cntrl IsCntrl - digit IsDigit + digit IsDigit \d graph IsGraph lower IsLower print IsPrint punct IsPunct space IsSpace + IsSpacePerl \s upper IsUpper word IsWord xdigit IsXDigit @@ -238,8 +247,8 @@ If the C<utf8> pragma is used, the following equivalences to Unicode For example C<[:lower:]> and C<\p{IsLower}> are equivalent. If the C<utf8> pragma is not used but the C<locale> pragma is, the -classes correlate with the isalpha(3) interface (except for `word', -which is a Perl extension, mirroring C<\w>). +classes correlate with the usual isalpha(3) interface (except for +`word' and `blank'). The assumedly non-obviously named classes are: @@ -250,23 +259,24 @@ The assumedly non-obviously named classes are: Any control character. Usually characters that don't produce output as such but instead control the terminal somehow: for example newline and backspace are control characters. All characters with ord() less than -32 are most often classified as control characters. +32 are most often classified as control characters (assuming ASCII, +the ISO Latin character sets, and Unicode). =item graph -Any alphanumeric or punctuation character. +Any alphanumeric or punctuation (special) character. =item print -Any alphanumeric or punctuation character or space. +Any alphanumeric or punctuation (special) character or space. =item punct -Any punctuation character. +Any punctuation (special) character. =item xdigit -Any hexadecimal digit. Though this may feel silly (/0-9a-f/i would +Any hexadecimal digit. Though this may feel silly ([0-9A-Fa-f] would work just fine) it is included for completeness. =back @@ -323,12 +333,14 @@ I<backreference>. There is no limit to the number of captured substrings that you may use. However Perl also uses \10, \11, etc. as aliases for \010, -\011, etc. (Recall that 0 means octal, so \011 is the 9'th ASCII -character, a tab.) Perl resolves this ambiguity by interpreting -\10 as a backreference only if at least 10 left parentheses have -opened before it. Likewise \11 is a backreference only if at least -11 left parentheses have opened before it. And so on. \1 through -\9 are always interpreted as backreferences." +\011, etc. (Recall that 0 means octal, so \011 is the character at +number 9 in your coded character set; which would be the 10th character, +a horizontal tab under ASCII.) Perl resolves this +ambiguity by interpreting \10 as a backreference only if at least 10 +left parentheses have opened before it. Likewise \11 is a +backreference only if at least 11 left parentheses have opened +before it. And so on. \1 through \9 are always interpreted as +backreferences. Examples: @@ -352,7 +364,7 @@ everything before the matched string. And C<$'> returns everything after the matched string. The numbered variables ($1, $2, $3, etc.) and the related punctuation -set (C<<$+>, C<$&>, C<$`>, and C<$'>) are all dynamically scoped +set (C<$+>, C<$&>, C<$`>, and C<$'>) are all dynamically scoped until the end of the enclosing block or until the next successful match, whichever comes first. (See L<perlsyn/"Compound Statements">.) @@ -377,10 +389,11 @@ 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-alphanumeric characters: +use for a pattern. Simply quote all non-"word" characters: $pattern =~ s/(\W)/\\$1/g; +(If C<use locale> is set, then this depends on the current locale.) Today it is more common to use the quotemeta() function or the C<\Q> metaquoting escape sequence to disable all metacharacters' special meanings like this: @@ -673,7 +686,7 @@ The "grab all you can, and do not give anything back" semantic is desirable in many situations where on the first sight a simple C<()*> looks like the correct solution. Suppose we parse text with comments being delimited by C<#> followed by some optional (horizontal) whitespace. Contrary to -its appearence, C<#[ \t]*> I<is not> the correct subexpression to match +its appearance, C<#[ \t]*> I<is not> 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: @@ -901,10 +914,14 @@ ways they can use backtracking to try match. For example, without internal optimizations done by the regular expression engine, this will take a painfully long time to run: - 'aaaaaaaaaaaa' =~ /((a{0,5}){0,5}){0,5}[c]/ + 'aaaaaaaaaaaa' =~ /((a{0,5}){0,5})*[c]/ -And if you used C<*>'s instead of limiting it to 0 through 5 matches, -then it would take forever--or until you ran out of stack space. +And if you used C<*>'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 C<{0,5}> instead of C<*> +on the external group, no current optimization is applicable, and the +match takes a long time to finish. A powerful tool for optimizing such beasts is what is known as an "independent group", @@ -939,10 +956,10 @@ 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: C<[-az]>, C<[az-]>, and C<[a\-z]>. All are different from C<[a-z]>, which -specifies a class containing twenty-six characters.) -Also, if you try to use the character classes C<\w>, C<\W>, C<\s>, -C<\S>, C<\d>, or C<\D> as endpoints of a range, that's not a range, -the "-" is understood literally. +specifies a class containing twenty-six characters, even on EBCDIC +based coded character sets.) Also, if you try to use the character +classes C<\w>, C<\W>, C<\s>, C<\S>, C<\d>, or C<\D> as endpoints of +a range, that's not a range, the "-" is understood literally. Note also that the whole range idea is rather unportable between character sets--and even within character sets they may cause results @@ -954,11 +971,11 @@ spell out the character sets in full. Characters may be specified using a metacharacter syntax much like that used in C: "\n" matches a newline, "\t" a tab, "\r" a carriage return, "\f" a form feed, etc. More generally, \I<nnn>, where I<nnn> is a string -of octal digits, matches the character whose ASCII value is I<nnn>. -Similarly, \xI<nn>, where I<nn> are hexadecimal digits, matches the -character whose ASCII value is I<nn>. The expression \cI<x> matches the -ASCII character control-I<x>. Finally, the "." metacharacter matches any -character except "\n" (unless you use C</s>). +of octal digits, matches the character whose coded character set value +is I<nnn>. Similarly, \xI<nn>, where I<nn> are hexadecimal digits, +matches the character whose numeric value is I<nn>. The expression \cI<x> +matches the character control-I<x>. Finally, the "." metacharacter +matches any character except "\n" (unless you use C</s>). You can specify a series of alternatives for a pattern using "|" to separate them, so that C<fee|fie|foe> will match any of "fee", "fie", @@ -1080,7 +1097,7 @@ For example: $_ = 'bar'; s/\w??/<$&>/g; -results in C<"<><b><><a><><r><>">. At each position of the string the best +results in C<< <><b><><a><><r><> >>. At each position of the string the best match given by non-greedy C<??> is the zero-length match, and the I<second best> match is what is matched by C<\w>. Thus zero-length matches alternate with one-character-long matches. @@ -1120,7 +1137,7 @@ one match at a given position is possible. This section describes the notion of better/worse for combining operators. In the description below C<S> and C<T> are regular subexpressions. -=over +=over 4 =item C<ST> @@ -1262,5 +1279,7 @@ L<perlfunc/pos>. L<perllocale>. +L<perlebcdic>. + I<Mastering Regular Expressions> by Jeffrey Friedl, published by O'Reilly and Associates. diff --git a/contrib/perl5/pod/perlreftut.pod b/contrib/perl5/pod/perlreftut.pod index c8593fb1ce68..073d358da55e 100644 --- a/contrib/perl5/pod/perlreftut.pod +++ b/contrib/perl5/pod/perlreftut.pod @@ -386,7 +386,7 @@ to do with references. =head1 Credits -Author: Mark-Jason Dominus, Plover Systems (C<mjd-perl-ref@plover.com>) +Author: Mark-Jason Dominus, Plover Systems (C<mjd-perl-ref+@plover.com>) This article originally appeared in I<The Perl Journal> (http://tpj.com) volume 3, #2. Reprinted with permission. diff --git a/contrib/perl5/pod/perlrun.pod b/contrib/perl5/pod/perlrun.pod index f1e2c9a62ecb..30e82fc1b8c8 100644 --- a/contrib/perl5/pod/perlrun.pod +++ b/contrib/perl5/pod/perlrun.pod @@ -284,11 +284,15 @@ be skipped. runs the program under the Perl debugger. See L<perldebug>. -=item B<-d:>I<foo> +=item B<-d:>I<foo[=bar,baz]> runs the program under the control of a debugging, profiling, or tracing module installed as Devel::foo. E.g., B<-d:DProf> executes -the program using the Devel::DProf profiler. See L<perldebug>. +the program using the Devel::DProf profiler. As with the B<-M> +flag, options may be passed to the Devel::foo package where they +will be received and interpreted by the Devel::foo::import routine. +The comma-separated list of options must follow a C<=> character. +See L<perldebug>. =item B<-D>I<letters> @@ -307,7 +311,7 @@ equivalent to B<-Dtls>): 8 t Trace execution 16 o Method and overloading resolution 32 c String/numeric conversions - 64 P Print preprocessor command for -P + 64 P Print preprocessor command for -P, source file input state 128 m Memory allocation 256 f Format processing 512 r Regular expression parsing and execution @@ -318,6 +322,7 @@ equivalent to B<-Dtls>): 16384 X Scratchpad allocation 32768 D Cleaning up 65536 S Thread synchronization + 131072 T Tokenising All these flags require B<-DDEBUGGING> when you compile the Perl executable. See the F<INSTALL> file in the Perl source distribution @@ -445,8 +450,7 @@ specified in the extension then it will skip that file and continue on with the next one (if it exists). For a discussion of issues surrounding file permissions and B<-i>, -see L<perlfaq5/Why does Perl let me delete read-only files? Why -does -i clobber protected files? Isn't this a bug in Perl?>. +see L<perlfaq5/Why does Perl let me delete read-only files? Why does -i clobber protected files? Isn't this a bug in Perl?>. You cannot use B<-i> to create directories or to strip extensions from files. @@ -565,15 +569,30 @@ the implicit loop, just as in B<awk>. =item B<-P> causes your program to be run through the C preprocessor before -compilation by Perl. (Because both comments and B<cpp> directives begin +compilation by Perl. Because both comments and B<cpp> directives begin with the # character, you should avoid starting comments with any words -recognized by the C preprocessor such as "if", "else", or "define".) +recognized by the C preprocessor such as C<"if">, C<"else">, or C<"define">. +Also, in some platforms the C preprocessor knows too much: it knows +about the C++ -style until-end-of-line comments starting with C<"//">. +This will cause problems with common Perl constructs like + + s/foo//; + +because after -P this will became illegal code + + s/foo + +The workaround is to use some other quoting separator than C<"/">, +like for example C<"!">: + + s!foo!!; =item B<-s> enables rudimentary switch parsing for switches on the command line after the program name but before any filename arguments (or before -a B<-->). Any switch found there is removed from @ARGV and sets the +an argument of B<-->). This means you can have switches with two leading +dashes (B<--help>). 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 B<-xyz> switch, and "abc" if it is invoked with B<-xyz=abc>. @@ -581,6 +600,9 @@ if it is invoked with B<-xyz=abc>. #!/usr/bin/perl -s if ($xyz) { print "$xyz\n" } +Do note that B<--help> creates the variable ${-help}, which is not compliant +with C<strict refs>. + =item B<-S> makes Perl use the PATH environment variable to search for the @@ -809,6 +831,18 @@ Relevant only if your perl executable was built with B<-DDEBUGGING>, this controls the behavior of global destruction of objects and other references. +=item PERL_ROOT (specific to the VMS port) + +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 +L<perlvms> and in F<README.vms> in the Perl source distribution. + +=item SYS$LOGIN (specific to the VMS port) + +Used if chdir has no argument and HOME and LOGDIR are not set. + =back Perl also has environment variables that control how Perl handles data diff --git a/contrib/perl5/pod/perlsec.pod b/contrib/perl5/pod/perlsec.pod index 4185e848036f..3870c2ef709d 100644 --- a/contrib/perl5/pod/perlsec.pod +++ b/contrib/perl5/pod/perlsec.pod @@ -38,9 +38,22 @@ msgrcv(), the password, gcos and shell fields returned by the getpwxxx() 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. (B<Important exception>: If you pass a list -of arguments to either C<system> or C<exec>, the elements of that list -are B<NOT> checked for taintedness.) Any variable set to a value +directories, or processes, B<with the following exceptions>: + +=over 4 + +=item * + +If you pass a list of arguments to either C<system> or C<exec>, +the elements of that list are B<not> checked for taintedness. + +=item * + +Arguments to C<print> and C<syswrite> are B<not> checked for taintedness. + +=back + +Any variable set to a value derived from tainted data will itself be tainted, even if it is logically impossible for the tainted data to alter the variable. Because taintedness is associated with each scalar value, some @@ -217,25 +230,31 @@ 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. - 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); - $EUID = $UID; - $EGID = $GID; # initgroups() also called! - # 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"; - exec 'myprog', 'arg1', 'arg2' - or die "can't exec myprog: $!"; - } + 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: $!"; + } A similar strategy would work for wildcard expansion via C<glob>, although you can use C<readdir> instead. @@ -291,12 +310,6 @@ in C: Compile this wrapper into a binary executable and then make I<it> rather than your script setuid or setgid. -See the program B<wrapsuid> in the F<eg> directory of your Perl -distribution for a convenient way to do this automatically for all your -setuid Perl programs. It moves setuid scripts into files with the same -name plus a leading dot, and then compiles a wrapper like the one above -for each of them. - 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 @@ -308,9 +321,8 @@ 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. -Prior to release 5.003 of Perl, a bug in the code of B<suidperl> could -introduce a security hole in systems compiled with strict POSIX -compliance. +Prior to release 5.6.1 of Perl, bugs in the code of B<suidperl> could +introduce a security hole. =head2 Protecting Your Programs diff --git a/contrib/perl5/pod/perlsub.pod b/contrib/perl5/pod/perlsub.pod index 46d1a2a2b0e0..b440cd1d9302 100644 --- a/contrib/perl5/pod/perlsub.pod +++ b/contrib/perl5/pod/perlsub.pod @@ -39,7 +39,7 @@ To call subroutines: 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 C<do>, C<require>, or C<use> keywords, or -generated on the fly using C<eval> or anonymous subroutines (closures). +generated on the fly using C<eval> or anonymous subroutines. You can even call a function indirectly using a variable containing its name or a CODE reference. @@ -154,7 +154,7 @@ of changing them in place: } Notice how this (unprototyped) function doesn't care whether it was -passed real scalars or arrays. Perl sees all arugments as one big, +passed real scalars or arrays. Perl sees all arguments as one big, long, flat parameter list in C<@_>. This is one area where Perl's simple argument-passing style shines. The C<upcase()> function would work perfectly well without changing the C<upcase()> @@ -169,8 +169,8 @@ Do not, however, be tempted to do this: 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 C<@a> and made C<@b> an empty list. See L<Pass by -Reference> for alternatives. +everything in C<@a> and made C<@b> an empty list. See +L<Pass by Reference> for alternatives. A subroutine may be called using an explicit C<&> prefix. The C<&> is optional in modern Perl, as are parentheses if the @@ -357,7 +357,7 @@ A compilation error results otherwise. An inner block may countermand this with C<no strict 'vars'>. A C<my> has both a compile-time and a run-time effect. At compile -time, the compiler takes notice of it. The principle usefulness +time, the compiler takes notice of it. The principal usefulness of this is to quiet C<use strict 'vars'>, but it is also essential for generation of closures as detailed in L<perlref>. Actual initialization is delayed until run time, though, so it gets executed @@ -645,10 +645,6 @@ and in: all the subroutines are called in a list context. -The current implementation does not allow arrays and hashes to be -returned from lvalue subroutines directly. You may return a -reference instead. This restriction may be lifted in future. - =head2 Passing Symbol Table Entries (typeglobs) B<WARNING>: The mechanism described in this section was originally @@ -697,9 +693,11 @@ Despite the existence of C<my>, there are still three places where the C<local> operator still shines. In fact, in these three places, you I<must> use C<local> instead of C<my>. -=over +=over 4 + +=item 1. -=item 1. You need to give a global variable a temporary value, especially $_. +You need to give a global variable a temporary value, especially $_. The global variables, like C<@ARGV> or the punctuation variables, must be C<local>ized with C<local()>. This block reads in F</etc/motd>, and splits @@ -716,7 +714,9 @@ in C<@Fields>. It particular, it's important to C<local>ize $_ in any routine that assigns to it. Look out for implicit assignments in C<while> conditionals. -=item 2. You need to create a local file or directory handle or a local function. +=item 2. + +You need to create a local file or directory handle or a local function. A function that needs a filehandle of its own must use C<local()> on a complete typeglob. This can be used to create new symbol @@ -746,7 +746,9 @@ a local alias. See L<perlref/"Function Templates"> for more about manipulating functions by name in this way. -=item 3. You want to temporarily change just one element of an array or hash. +=item 3. + +You want to temporarily change just one element of an array or hash. You can C<local>ize just one element of an aggregate. Usually this is done on dynamics: @@ -1270,7 +1272,7 @@ see L<attributes>. See L<perlref/"Function Templates"> for more about references and closures. See L<perlxs> if you'd like to learn about calling C subroutines from Perl. -See L<perlembed> if you'd like to learn about calling PErl subroutines from C. +See L<perlembed> if you'd like to learn about calling Perl subroutines from C. See L<perlmod> to learn about bundling up your functions in separate files. See L<perlmodlib> to learn what library modules come standard on your system. See L<perltoot> to learn how to make object method calls. diff --git a/contrib/perl5/pod/perlsyn.pod b/contrib/perl5/pod/perlsyn.pod index 724ba12ac0fa..aad4efd2f771 100644 --- a/contrib/perl5/pod/perlsyn.pod +++ b/contrib/perl5/pod/perlsyn.pod @@ -53,8 +53,8 @@ subroutine without defining it by saying C<sub name>, thus: sub myname; $me = myname $0 or die "can't get myname"; -Note that my() functions as a list operator, not as a unary operator; so -be careful to use C<or> instead of C<||> in this case. However, if +Note that myname() functions as a list operator, not as a unary operator; +so be careful to use C<or> instead of C<||> in this case. However, if you were to declare the subroutine as C<sub myname ($)>, then C<myname> would function as a unary operator, so either C<or> or C<||> would work. @@ -172,7 +172,7 @@ 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 C<use warnings> -praga or the B<-w> flag. +pragma or the B<-w> flag. Unlike a C<foreach> statement, a C<while> statement never implicitly localises any variables. @@ -263,7 +263,7 @@ available. Replace any occurrence of C<if BLOCK> by C<if (do BLOCK)>. =head2 For Loops -Perl's C-style C<for> loop works exactly like the corresponding C<while> loop; +Perl's C-style C<for> loop works like the corresponding C<while> loop; that means that this: for ($i = 1; $i < 10; $i++) { @@ -279,8 +279,10 @@ is the same as this: $i++; } -(There is one minor difference: The first form implies a lexical scope -for variables declared with C<my> in the initialization expression.) +There is one minor difference: if variables are declared with C<my> +in the initialization section of the C<for>, the lexical scope of +those variables is exactly the C<for> loop (the body of the loop +and the control sections). Besides the normal array index looping, C<for> can lend itself to many other interesting applications. Here's one that avoids the @@ -309,9 +311,12 @@ The C<foreach> keyword is actually a synonym for the C<for> keyword, so you can use C<foreach> for readability or C<for> for brevity. (Or because the Bourne shell is more familiar to you than I<csh>, so writing C<for> comes more naturally.) If VAR is omitted, C<$_> is set to each value. -If any element of LIST is an lvalue, you can modify it by modifying VAR -inside the loop. That's because the C<foreach> loop index variable is -an implicit alias for each item in the list that you're looping over. + +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 C<foreach> loop index variable is an implicit alias for each item +in the list that you're looping over. If any part of LIST is an array, C<foreach> will get very confused if you add or remove elements within the loop body, for example with @@ -483,7 +488,7 @@ Or Or if you are certainly that all the C<&&> clauses are true, you can use something like this, which "switches" on the value of the -C<HTTP_USER_AGENT> envariable. +C<HTTP_USER_AGENT> environment variable. #!/usr/bin/perl # pick out jargon file page based on browser @@ -598,6 +603,11 @@ C</^#\s*line\s+(\d+)\s*(?:\s"([^"]+)")?\s*$/> with C<$1> being the line number for the next line, and C<$2> being the optional filename (specified within quotes). +There is a fairly obvious gotcha included with the line directive: +Debuggers and profilers will only show the last source line to appear +at a particular line number in a given file. Care should be taken not +to cause line number collisions in code you'd like to debug later. + Here are some examples that you should be able to type into your command shell: diff --git a/contrib/perl5/pod/perlthrtut.pod b/contrib/perl5/pod/perlthrtut.pod index 0f15d57de76e..0b7092b39dca 100644 --- a/contrib/perl5/pod/perlthrtut.pod +++ b/contrib/perl5/pod/perlthrtut.pod @@ -718,7 +718,7 @@ In addition to synchronizing access to data or resources, you might find it useful to synchronize access to subroutines. You may be accessing a singular machine resource (perhaps a vector processor), or find it easier to serialize calls to a particular subroutine than to -have a set of locks and sempahores. +have a set of locks and semaphores. One of the additions to Perl 5.005 is subroutine attributes. The Thread package uses these to provide several flavors of @@ -991,7 +991,7 @@ the explanation is much longer than the program. A complete thread tutorial could fill a book (and has, many times), but this should get you well on your way. The final authority on how -Perl's threads behave is the documention bundled with the Perl +Perl's threads behave is the documentation bundled with the Perl distribution, but with what we've covered in this article, you should be well on your way to becoming a threaded Perl expert. @@ -1029,7 +1029,7 @@ LoVerso. Programming under Mach. Addison-Wesley, 1994, ISBN 0-201-52739-1. Tanenbaum, Andrew S. Distributed Operating Systems. Prentice Hall, -1995, ISBN 0-13-143934-0 (great textbook). +1995, ISBN 0-13-219908-4 (great textbook). Silberschatz, Abraham, and Peter B. Galvin. Operating System Concepts, 4th ed. Addison-Wesley, 1995, ISBN 0-201-59292-4 diff --git a/contrib/perl5/pod/perltie.pod b/contrib/perl5/pod/perltie.pod index c835738573f9..1bba005be59f 100644 --- a/contrib/perl5/pod/perltie.pod +++ b/contrib/perl5/pod/perltie.pod @@ -48,7 +48,7 @@ for you--you need to do that explicitly yourself. =head2 Tying Scalars A class implementing a tied scalar should define the following methods: -TIESCALAR, FETCH, STORE, and possibly DESTROY. +TIESCALAR, FETCH, STORE, and possibly UNTIE and/or DESTROY. Let's look at each in turn, using as an example a tie class for scalars that allows the user to do something like: @@ -71,7 +71,7 @@ calls. Here's the preamble of the class. use strict; $Nice::DEBUG = 0 unless defined $Nice::DEBUG; -=over +=over 4 =item TIESCALAR classname, LIST @@ -157,6 +157,12 @@ argument--the new value the user is trying to assign. return $new_nicety; } +=item UNTIE this + +This method will be triggered when the C<untie> occurs. This can be useful +if the class needs to know when no further calls will be made. (Except DESTROY +of course.) See below for more details. + =item DESTROY this This method will be triggered when the tied variable needs to be destructed. @@ -180,7 +186,7 @@ TIESCALAR classes are certainly possible. =head2 Tying Arrays A class implementing a tied ordinary array should define the following -methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps DESTROY. +methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps UNTIE and/or DESTROY. FETCHSIZE and STORESIZE are used to provide C<$#array> and equivalent C<scalar(@array)> access. @@ -192,34 +198,25 @@ base class to implement the first five of these in terms of the basic methods above. The default implementations of DELETE and EXISTS in B<Tie::Array> simply C<croak>. -In addition EXTEND will be called when perl would have pre-extended +In addition EXTEND will be called when perl would have pre-extended allocation in a real array. -This means that tied arrays are now I<complete>. The example below needs -upgrading to illustrate this. (The documentation in B<Tie::Array> is more -complete.) - -For this discussion, we'll implement an array whose indices are fixed at -its creation. If you try to access anything beyond those bounds, you'll -take an exception. For example: +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: - require Bounded_Array; - tie @ary, 'Bounded_Array', 2; - $| = 1; - for $i (0 .. 10) { - print "setting index $i: "; - $ary[$i] = 10 * $i; - $ary[$i] = 10 * $i; - print "value of elt $i now $ary[$i]\n"; - } + use FixedElem_Array; + tie @array, 'FixedElem_Array', 3; + $array[0] = 'cat'; # ok. + $array[1] = 'dogs'; # exception, length('dogs') > 3. The preamble code for the class is as follows: - package Bounded_Array; + package FixedElem_Array; use Carp; use strict; -=over +=over 4 =item TIEARRAY classname, LIST @@ -229,21 +226,22 @@ anonymous ARRAY ref) will be accessed. In our example, just to show you that you don't I<really> 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 C<{BOUND}> field will -store the maximum bound allowed, and the C<{ARRAY}> field will hold the +A HASH works out well as a generic record type: the C<{ELEMSIZE}> field will +store the maximum element size allowed, and the C<{ARRAY}> 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. sub TIEARRAY { - my $class = shift; - my $bound = shift; - confess "usage: tie(\@ary, 'Bounded_Array', max_subscript)" - if @_ || $bound =~ /\D/; - return bless { - BOUND => $bound, - ARRAY => [], - }, $class; + my $class = shift; + my $elemsize = shift; + if ( @_ || $elemsize =~ /\D/ ) { + croak "usage: tie ARRAY, '" . __PACKAGE__ . "', elem_size"; + } + return bless { + ELEMSIZE => $elemsize, + ARRAY => [], + }, $class; } =item FETCH this, index @@ -253,13 +251,15 @@ is accessed (read). It takes one argument beyond its self reference: the index whose value we're trying to fetch. sub FETCH { - my($self,$idx) = @_; - if ($idx > $self->{BOUND}) { - confess "Array OOB: $idx > $self->{BOUND}"; - } - return $self->{ARRAY}[$idx]; + my $self = shift; + my $index = shift; + return $self->{ARRAY}->[$index]; } +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. + 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 @@ -271,17 +271,189 @@ to keep them at simply one tie type per class. 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. For example: +there. + +In our example, C<undef> is really C<$self-E<gt>{ELEMSIZE}> number of +spaces so we have a little more work to do here: sub STORE { - my($self, $idx, $value) = @_; - print "[STORE $value at $idx]\n" if _debug; - if ($idx > $self->{BOUND} ) { - confess "Array OOB: $idx > $self->{BOUND}"; + 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; + } + +Negative indexes are treated the same as with FETCH. + +=item FETCHSIZE this + +Returns the total number of items in the tied array associated with +object I<this>. (Equivalent to C<scalar(@array)>). For example: + + sub FETCHSIZE { + my $self = shift; + return scalar @{$self->{ARRAY}}; + } + +=item STORESIZE this, count + +Sets the total number of items in the tied array associated with +object I<this> to be I<count>. If this makes the array larger then +class's mapping of C<undef> should be returned for new positions. +If the array becomes smaller then entries beyond count should be +deleted. + +In our example, 'undef' is really an element containing +C<$self-E<gt>{ELEMSIZE}> number of spaces. Observe: + + 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(); + } + } + } + +=item EXTEND this, count + +Informative call that array is likely to grow to have I<count> entries. +Can be used to optimize allocation. This method need do nothing. + +In our example, we want to make sure there are no blank (C<undef>) +entries, so C<EXTEND> will make use of C<STORESIZE> to fill elements +as needed: + + sub EXTEND { + my $self = shift; + my $count = shift; + $self->STORESIZE( $count ); + } + +=item EXISTS this, key + +Verify that the element at index I<key> exists in the tied array I<this>. + +In our example, we will determine that if an element consists of +C<$self-E<gt>{ELEMSIZE}> spaces only, it does not exist: + + sub EXISTS { + my $self = shift; + my $index = shift; + return 0 if ! defined $self->{ARRAY}->[$index] || + $self->{ARRAY}->[$index] eq ' ' x $self->{ELEMSIZE}; + return 1; + } + +=item DELETE this, key + +Delete the element at index I<key> from the tied array I<this>. + +In our example, a deleted item is C<$self->{ELEMSIZE}> spaces: + + sub DELETE { + my $self = shift; + my $index = shift; + return $self->STORE( $index, '' ); + } + +=item CLEAR this + +Clear (remove, delete, ...) all values from the tied array associated with +object I<this>. For example: + + sub CLEAR { + my $self = shift; + return $self->{ARRAY} = []; + } + +=item PUSH this, LIST + +Append elements of I<LIST> to the array. For example: + + sub PUSH { + my $self = shift; + my @list = @_; + my $last = $self->FETCHSIZE(); + $self->STORE( $last + $_, $list[$_] ) foreach 0 .. $#list; + return $self->FETCHSIZE(); + } + +=item POP this + +Remove last element of the array and return it. For example: + + sub POP { + my $self = shift; + return pop @{$self->{ARRAY}}; + } + +=item SHIFT this + +Remove the first element of the array (shifting other elements down) +and return it. For example: + + sub SHIFT { + my $self = shift; + return shift @{$self->{ARRAY}}; + } + +=item UNSHIFT this, LIST + +Insert LIST elements at the beginning of the array, moving existing elements +up to make room. For example: + + 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; + } + +=item SPLICE this, offset, length, LIST + +Perform the equivalent of C<splice> on the array. + +I<offset> is optional and defaults to zero, negative values count back +from the end of the array. + +I<length> is optional and defaults to rest of the array. + +I<LIST> may be empty. + +Returns a list of the original I<length> elements at I<offset>. + +In our example, we'll use a little shortcut if there is a I<LIST>: + + 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 $self->{ARRAY}[$idx] = $value; + return splice @{$self->{ARRAY}}, $offset, $length, @list; } +=item UNTIE this + +Will be called when C<untie> happens. (See below.) + =item DESTROY this This method will be triggered when the tied variable needs to be destructed. @@ -291,27 +463,16 @@ just leave it out. =back -The code we presented at the top of the tied array class accesses many -elements of the array, far more than we've set the bounds to. Therefore, -it will blow up once they try to access beyond the 2nd element of @ary, as -the following output demonstrates: - - setting index 0: value of elt 0 now 0 - setting index 1: value of elt 1 now 10 - setting index 2: value of elt 2 now 20 - setting index 3: Array OOB: 3 > 2 at Bounded_Array.pm line 39 - Bounded_Array::FETCH called at testba line 12 - =head2 Tying Hashes -As the first Perl data type to be tied (see dbmopen()), hashes have the -most complete and useful tie() implementation. 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. -And DESTROY is called when the tied variable is garbage collected. +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. UNTIE is called when C<untie> happens, and DESTROY is called when +the tied variable is garbage collected. If this seems like a lot, then feel free to inherit from merely the standard Tie::Hash module for most of your methods, redefining only the @@ -384,7 +545,7 @@ that calls it. Here are the methods for the DotFiles tied hash. -=over +=over 4 =item TIEHASH classname, LIST @@ -593,6 +754,10 @@ thing, but we'll have to go through the LIST field indirectly. return each %{ $self->{LIST} } } +=item UNTIE this + +This is called when C<untie> occurs. + =item DESTROY this This method is triggered when a tied hash is about to go out of @@ -623,7 +788,7 @@ This is partially implemented now. 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 and DESTROY. The class can also provide: BINMODE, +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. @@ -635,7 +800,7 @@ In our example we're going to create a shouting handle. package Shout; -=over +=over 4 =item TIEHANDLE classname, LIST @@ -712,6 +877,11 @@ function. sub CLOSE { print "CLOSE called.\n" } +=item UNTIE this + +As with the other types of ties, this method will be called when C<untie> happens. +It may be appropriate to "auto CLOSE" when this occurs. + =item DESTROY this As with the other types of ties, this method will be called when the @@ -730,6 +900,11 @@ Here's how to use our little example: print FOO $a, " plus ", $b, " equals ", $a + $b, "\n"; print <FOO>; +=head2 UNTIE this + +You can define for all tie types an UNTIE method that will be called +at untie(). + =head2 The C<untie> Gotcha If you intend making use of the object returned from either tie() or @@ -844,7 +1019,8 @@ closed. The reason there is no output is because the file buffers have not been flushed to disk. Now that you know what the problem is, what can you do to avoid it? -Well, the good old C<-w> flag will spot any instances where you call +Prior to the introduction of the optional UNTIE method the only way +was the good old C<-w> 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 C<use warnings 'untie'> or was run with the C<-w> flag, Perl prints this @@ -859,17 +1035,33 @@ called: undef $x; untie $fred; +Now that UNTIE exists the class designer can decide which parts of the +class functionality are really associated with C<untie> 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. + +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: + + sub UNTIE + { + my ($obj,$count) = @_; + carp "untie attempted while $count inner references still exist" if $count; + } + =head1 SEE ALSO See L<DB_File> or L<Config> for some interesting tie() implementations. +A good starting point for many tie() implementations is with one of the +modules L<Tie::Scalar>, L<Tie::Array>, L<Tie::Hash>, or L<Tie::Handle>. =head1 BUGS -Tied arrays are I<incomplete>. They are also distinctly lacking something -for the C<$#ARRAY> access (which is hard, as it's an lvalue), as well as -the other obvious array functions, like push(), pop(), shift(), unshift(), -and splice(). - 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 @@ -878,8 +1070,15 @@ module that does attempt to address this need partially is the MLDBM module. Check your nearest CPAN site as described in L<perlmodlib> for source code to MLDBM. +Tied filehandles are still incomplete. sysopen(), truncate(), +flock(), fcntl(), stat() and -X can't currently be trapped. + =head1 AUTHOR Tom Christiansen TIEHANDLE by Sven Verdoolaege <F<skimo@dns.ufsia.ac.be>> and Doug MacEachern <F<dougm@osf.org>> + +UNTIE by Nick Ing-Simmons <F<nick@ing-simmons.net>> + +Tying Arrays by Casey Tweten <F<crt@kiski.net>> diff --git a/contrib/perl5/pod/perltoc.pod b/contrib/perl5/pod/perltoc.pod index 798a24d19363..7bae86ed639f 100644 --- a/contrib/perl5/pod/perltoc.pod +++ b/contrib/perl5/pod/perltoc.pod @@ -13,22 +13,12 @@ through to locate the proper section you're looking for. =head2 perl - Practical Extraction and Report Language -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -modularity and reusability using innumerable modules, embeddable and -extensible, roll-your-own magic variables (including multiple simultaneous -DBM implementations), subroutines can now be overridden, autoloaded, and -prototyped, arbitrarily nested data structures and anonymous functions, -object-oriented programming, compilability into C code or Perl bytecode, -support for light-weight processes (threads), support for -internationalization, localization, and Unicode, lexical scoping, regular -expression enhancements, enhanced debugger and interactive Perl -environment, with integrated editor support, POSIX 1003.1 compliant library - =item AVAILABILITY =item ENVIRONMENT @@ -50,232 +40,41 @@ environment, with integrated editor support, POSIX 1003.1 compliant library =head2 perlfaq - frequently asked questions about Perl ($Date: 1999/05/23 20:38:02 $) -=over - -=item DESCRIPTION - -perlfaq: Structural overview of the FAQ, L<perlfaq1>: General Questions -About Perl, What is Perl?, Who supports Perl? Who develops it? Why is it -free?, Which version of Perl should I use?, What are perl4 and perl5?, What -is perl6?, How stable is Perl?, Is Perl difficult to learn?, How does Perl -compare with other languages like Java, Python, REXX, Scheme, or Tcl?, Can -I do [task] in Perl?, When shouldn't I program in Perl?, What's the -difference between "perl" and "Perl"?, Is it a Perl program or a Perl -script?, What is a JAPH?, Where can I get a list of Larry Wall witticisms?, -How can I convince my sysadmin/supervisor/employees to use version -(5/5.005/Perl instead of some other language)?, L<perlfaq2>: Obtaining and -Learning about Perl, What machines support Perl? Where do I get it?, How -can I get a binary version of Perl?, I don't have a C compiler on my -system. How can I compile perl?, I copied the Perl binary from one machine -to another, but scripts don't work, I grabbed the sources and tried to -compile but gdbm/dynamic loading/malloc/linking/... failed. How do I make -it work?, What modules and extensions are available for Perl? What is -CPAN? What does CPAN/src/... mean?, Is there an ISO or ANSI certified -version of Perl?, Where can I get information on Perl?, What are the Perl -newsgroups on USENET? Where do I post questions?, Where should I post -source code?, Perl Books, Perl in Magazines, Perl on the Net: FTP and WWW -Access, What mailing lists are there for perl?, Archives of -comp.lang.perl.misc, Where can I buy a commercial version of Perl?, Where -do I send bug reports?, What is perl.com?, L<perlfaq3>: Programming Tools, -How do I do (anything)?, How can I use Perl interactively?, Is there a Perl -shell?, How do I debug my Perl programs?, How do I profile my Perl -programs?, How do I cross-reference my Perl programs?, Is there a -pretty-printer (formatter) for Perl?, Is there a ctags for Perl?, Is there -an IDE or Windows Perl Editor?, Where can I get Perl macros for vi?, Where -can I get perl-mode for emacs?, How can I use curses with Perl?, How can I -use X or Tk with Perl?, How can I generate simple menus without using CGI -or Tk?, What is undump?, How can I make my Perl program run faster?, How -can I make my Perl program take less memory?, Is it unsafe to return a -pointer to local data?, How can I free an array or hash so my program -shrinks?, How can I make my CGI script more efficient?, How can I hide the -source for my Perl program?, How can I compile my Perl program into byte -code or C?, How can I compile Perl into Java?, How can I get C<#!perl> to -work on [MS-DOS,NT,...]?, Can I write useful perl programs on the command -line?, Why don't perl one-liners work on my DOS/Mac/VMS system?, Where can -I learn about CGI or Web programming in Perl?, Where can I learn about -object-oriented Perl programming?, Where can I learn about linking C with -Perl? [h2xs, xsubpp], I've read perlembed, perlguts, etc., but I can't -embed perl inmy C program, what am I doing wrong?, When I tried to run my -script, I got this message. What does itmean?, What's MakeMaker?, -L<perlfaq4>: Data Manipulation, Why am I getting long decimals (eg, -19.9499999999999) instead of the numbers I should be getting (eg, 19.95)?, -Why isn't my octal data interpreted correctly?, Does Perl have a round() -function? What about ceil() and floor()? Trig functions?, How do I -convert bits into ints?, Why doesn't & work the way I want it to?, How do I -multiply matrices?, How do I perform an operation on a series of integers?, -How can I output Roman numerals?, Why aren't my random numbers random?, How -do I find the week-of-the-year/day-of-the-year?, How do I find the current -century or millennium?, How can I compare two dates and find the -difference?, How can I take a string and turn it into epoch seconds?, How -can I find the Julian Day?, How do I find yesterday's date?, Does Perl have -a year 2000 problem? Is Perl Y2K compliant?, How do I validate input?, How -do I unescape a string?, How do I remove consecutive pairs of characters?, -How do I expand function calls in a string?, How do I find matching/nesting -anything?, How do I reverse a string?, How do I expand tabs in a string?, -How do I reformat a paragraph?, How can I access/change the first N letters -of a string?, How do I change the Nth occurrence of something?, How can I -count the number of occurrences of a substring within a string?, How do I -capitalize all the words on one line?, How can I split a [character] -delimited string except when inside[character]? (Comma-separated files), -How do I strip blank space from the beginning/end of a string?, How do I -pad a string with blanks or pad a number with zeroes?, How do I extract -selected columns from a string?, How do I find the soundex value of a -string?, How can I expand variables in text strings?, What's wrong with -always quoting "$vars"?, Why don't my <<HERE documents work?, What is the -difference between a list and an array?, What is the difference between -$array[1] and @array[1]?, How can I remove duplicate elements from a list -or array?, How can I tell whether a list or array contains a certain -element?, How do I compute the difference of two arrays? How do I compute -the intersection of two arrays?, How do I test whether two arrays or hashes -are equal?, How do I find the first array element for which a condition is -true?, How do I handle linked lists?, How do I handle circular lists?, How -do I shuffle an array randomly?, How do I process/modify each element of an -array?, How do I select a random element from an array?, How do I permute N -elements of a list?, How do I sort an array by (anything)?, How do I -manipulate arrays of bits?, Why does defined() return true on empty arrays -and hashes?, How do I process an entire hash?, What happens if I add or -remove keys from a hash while iterating over it?, How do I look up a hash -element by value?, How can I know how many entries are in a hash?, How do I -sort a hash (optionally by value instead of key)?, How can I always keep my -hash sorted?, What's the difference between "delete" and "undef" with -hashes?, Why don't my tied hashes make the defined/exists distinction?, How -do I reset an each() operation part-way through?, How can I get the unique -keys from two hashes?, How can I store a multidimensional array in a DBM -file?, How can I make my hash remember the order I put elements into it?, -Why does passing a subroutine an undefined element in a hash create it?, -How can I make the Perl equivalent of a C structure/C++ class/hash or array -of hashes or arrays?, How can I use a reference as a hash key?, How do I -handle binary data correctly?, How do I determine whether a scalar is a -number/whole/integer/float?, How do I keep persistent data across program -calls?, How do I print out or copy a recursive data structure?, How do I -define methods for every class/object?, How do I verify a credit card -checksum?, How do I pack arrays of doubles or floats for XS code?, -L<perlfaq5>: Files and Formats, How do I flush/unbuffer an output -filehandle? Why must I do this?, How do I change one line in a file/delete -a line in a file/insert a line in the middle of a file/append to the -beginning of a file?, How do I count the number of lines in a file?, How do -I make a temporary file name?, How can I manipulate fixed-record-length -files?, How can I make a filehandle local to a subroutine? How do I pass -filehandles between subroutines? How do I make an array of filehandles?, -How can I use a filehandle indirectly?, How can I set up a footer format to -be used with write()?, How can I write() into a string?, How can I output -my numbers with commas added?, How can I translate tildes (~) in a -filename?, How come when I open a file read-write it wipes it out?, Why do -I sometimes get an "Argument list too long" when I use <*>?, Is there a -leak/bug in glob()?, How can I open a file with a leading ">" or trailing -blanks?, How can I reliably rename a file?, How can I lock a file?, Why -can't I just open(FH, ">file.lock")?, I still don't get locking. I just -want to increment the number in the file. How can I do this?, How do I -randomly update a binary file?, How do I get a file's timestamp in perl?, -How do I set a file's timestamp in perl?, How do I print to more than one -file at once?, How can I read in an entire file all at once?, How can I -read in a file by paragraphs?, How can I read a single character from a -file? From the keyboard?, How can I tell whether there's a character -waiting on a filehandle?, How do I do a C<tail -f> in perl?, How do I dup() -a filehandle in Perl?, How do I close a file descriptor by number?, Why -can't I use "C:\temp\foo" in DOS paths? What doesn't `C:\temp\foo.exe` -work?, Why doesn't glob("*.*") get all the files?, Why does Perl let me -delete read-only files? Why does C<-i> clobber protected files? Isn't -this a bug in Perl?, How do I select a random line from a file?, Why do I -get weird spaces when I print an array of lines?, L<perlfaq6>: Regexps, How -can I hope to use regular expressions without creating illegible and -unmaintainable code?, I'm having trouble matching over more than one line. -What's wrong?, How can I pull out lines between two patterns that are -themselves on different lines?, I put a regular expression into $/ but it -didn't work. What's wrong?, How do I substitute case insensitively on the -LHS, but preserving case on the RHS?, How can I make C<\w> match national -character sets?, How can I match a locale-smart version of C</[a-zA-Z]/>?, -How can I quote a variable to use in a regex?, What is C</o> really for?, -How do I use a regular expression to strip C style comments from a file?, -Can I use Perl regular expressions to match balanced text?, What does it -mean that regexes are greedy? How can I get around it?, How do I process -each word on each line?, How can I print out a word-frequency or -line-frequency summary?, How can I do approximate matching?, How do I -efficiently match many regular expressions at once?, Why don't -word-boundary searches with C<\b> work for me?, Why does using $&, $`, or -$' slow my program down?, What good is C<\G> in a regular expression?, Are -Perl regexes DFAs or NFAs? Are they POSIX compliant?, What's wrong with -using grep or map in a void context?, How can I match strings with -multibyte characters?, How do I match a pattern that is supplied by the -user?, L<perlfaq7>: General Perl Language Issues, Can I get a BNF/yacc/RE -for the Perl language?, What are all these $@%&* punctuation signs, and how -do I know when to use them?, Do I always/never have to quote my strings or -use semicolons and commas?, How do I skip some return values?, How do I -temporarily block warnings?, What's an extension?, Why do Perl operators -have different precedence than C operators?, How do I declare/create a -structure?, How do I create a module?, How do I create a class?, How can I -tell if a variable is tainted?, What's a closure?, What is variable suicide -and how can I prevent it?, How can I pass/return a {Function, FileHandle, -Array, Hash, Method, Regex}?, How do I create a static variable?, What's -the difference between dynamic and lexical (static) scoping? Between -local() and my()?, How can I access a dynamic variable while a similarly -named lexical is in scope?, What's the difference between deep and shallow -binding?, Why doesn't "my($foo) = <FILE>;" work right?, How do I redefine a -builtin function, operator, or method?, What's the difference between -calling a function as &foo and foo()?, How do I create a switch or case -statement?, How can I catch accesses to undefined -variables/functions/methods?, Why can't a method included in this same file -be found?, How can I find out my current package?, How can I comment out a -large block of perl code?, How do I clear a package?, How can I use a -variable as a variable name?, L<perlfaq8>: System Interaction, How do I -find out which operating system I'm running under?, How come exec() doesn't -return?, How do I do fancy stuff with the keyboard/screen/mouse?, How do I -print something out in color?, How do I read just one key without waiting -for a return key?, How do I check whether input is ready on the keyboard?, -How do I clear the screen?, How do I get the screen size?, How do I ask the -user for a password?, How do I read and write the serial port?, How do I -decode encrypted password files?, How do I start a process in the -background?, How do I trap control characters/signals?, How do I modify the -shadow password file on a Unix system?, How do I set the time and date?, -How can I sleep() or alarm() for under a second?, How can I measure time -under a second?, How can I do an atexit() or setjmp()/longjmp()? (Exception -handling), Why doesn't my sockets program work under System V (Solaris)? -What does the error message "Protocol not supported" mean?, How can I call -my system's unique C functions from Perl?, Where do I get the include files -to do ioctl() or syscall()?, Why do setuid perl scripts complain about -kernel problems?, How can I open a pipe both to and from a command?, Why -can't I get the output of a command with system()?, How can I capture -STDERR from an external command?, Why doesn't open() return an error when a -pipe open fails?, What's wrong with using backticks in a void context?, How -can I call backticks without shell processing?, Why can't my script read -from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)?, How can I -convert my shell script to perl?, Can I use perl to run a telnet or ftp -session?, How can I write expect in Perl?, Is there a way to hide perl's -command line from programs such as "ps"?, I {changed directory, modified my -environment} in a perl script. How come the change disappeared when I -exited the script? How do I get my changes to be visible?, How do I close -a process's filehandle without waiting for it to complete?, How do I fork a -daemon process?, How do I make my program run with sh and csh?, How do I -find out if I'm running interactively or not?, How do I timeout a slow -event?, How do I set CPU limits?, How do I avoid zombies on a Unix system?, -How do I use an SQL database?, How do I make a system() exit on control-C?, -How do I open a file without blocking?, How do I install a module from -CPAN?, What's the difference between require and use?, How do I keep my own -module/library directory?, How do I add the directory my program lives in -to the module/library search path?, How do I add a directory to my include -path at runtime?, What is socket.ph and where do I get it?, L<perlfaq9>: -Networking, My CGI script runs from the command line but not the browser. -(500 Server Error), How can I get better error messages from a CGI -program?, How do I remove HTML from a string?, How do I extract URLs?, How -do I download a file from the user's machine? How do I open a file on -another machine?, How do I make a pop-up menu in HTML?, How do I fetch an -HTML file?, How do I automate an HTML form submission?, How do I decode or -create those %-encodings on the web?, How do I redirect to another page?, -How do I put a password on my web pages?, How do I edit my .htpasswd and -.htgroup files with Perl?, How do I make sure users can't enter values into -a form that cause my CGI script to do bad things?, How do I parse a mail -header?, How do I decode a CGI form?, How do I check a valid mail address?, -How do I decode a MIME/BASE64 string?, How do I return the user's mail -address?, How do I send mail?, How do I read mail?, How do I find out my -hostname/domainname/IP address?, How do I fetch a news article or the -active newsgroups?, How do I fetch/put an FTP file?, How can I do RPC in -Perl? - -=over - -=item Where to get this document - -=item How to contribute to this document +=over 4 + +=item DESCRIPTION + +=over 4 + +=item perlfaq: Structural overview of the FAQ. + +=item L<perlfaq1>: General Questions About Perl + +=item L<perlfaq2>: Obtaining and Learning about Perl + +=item L<perlfaq3>: Programming Tools + +=item L<perlfaq4>: Data Manipulation + +=item L<perlfaq5>: Files and Formats + +=item L<perlfaq6>: Regexps + +=item L<perlfaq7>: General Perl Language Issues + +=item L<perlfaq8>: System Interaction + +=item L<perlfaq9>: Networking + +=back + +=item About the perlfaq documents + +=over 4 + +=item Where to get the perlfaq + +=item How to contribute to the perlfaq =item What will happen if you mail your Perl programming problems to the authors @@ -286,7 +85,7 @@ authors =item Author and Copyright Information -=over +=over 4 =item Bundled Distributions @@ -296,19 +95,2244 @@ authors =item Changes -23/May/99, 13/April/99, 7/January/99, 22/June/98, 24/April/97, 23/April/97, -25/March/97, 18/March/97, 17/March/97 Version, Initial Release: 11/March/97 +1/November/2000, 23/May/99, 13/April/99, 7/January/99, 22/June/98, +24/April/97, 23/April/97, 25/March/97, 18/March/97, 17/March/97 Version, +Initial Release: 11/March/97 + +=back + +=head2 perlbook - Perl book information + +=over 4 + +=item DESCRIPTION + +=back + +=head2 perlsyn - Perl syntax + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Declarations + +=item Simple statements + +=item Compound statements + +=item Loop Control + +=item For Loops + +=item Foreach Loops + +=item Basic BLOCKs and Switch Statements + +=item Goto + +=item PODs: Embedded Documentation + +=item Plain Old Comments (Not!) + +=back + +=back + +=head2 perldata - Perl data types + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Variable names + +=item Context + +=item Scalar values + +=item Scalar value constructors + +=item List value constructors + +=item Slices + +=item Typeglobs and Filehandles + +=back + +=item SEE ALSO + +=back + +=head2 perlop - Perl operators and precedence + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Terms and List Operators (Leftward) + +=item The Arrow Operator + +=item Auto-increment and Auto-decrement + +=item Exponentiation + +=item Symbolic Unary Operators + +=item Binding Operators + +=item Multiplicative Operators + +=item Additive Operators + +=item Shift Operators + +=item Named Unary Operators + +=item Relational Operators + +=item Equality Operators + +=item Bitwise And + +=item Bitwise Or and Exclusive Or + +=item C-style Logical And + +=item C-style Logical Or + +=item Range Operators + +=item Conditional Operator + +=item Assignment Operators + +=item Comma Operator + +=item List Operators (Rightward) + +=item Logical Not + +=item Logical And + +=item Logical or and Exclusive Or + +=item C Operators Missing From Perl + +unary &, unary *, (TYPE) + +=item Quote and Quote-like Operators + +=item Regexp Quote-Like Operators + +?PATTERN?, m/PATTERN/cgimosx, /PATTERN/cgimosx, q/STRING/, C<'STRING'>, +qq/STRING/, "STRING", qr/STRING/imosx, qx/STRING/, `STRING`, qw/STRING/, +s/PATTERN/REPLACEMENT/egimosx, tr/SEARCHLIST/REPLACEMENTLIST/cds, +y/SEARCHLIST/REPLACEMENTLIST/cds + +=item Gory details of parsing quoted constructs + +Finding the end, Removal of backslashes before delimiters, Interpolation, +C<<<'EOF'>, C<m''>, C<s'''>, C<tr///>, C<y///>, C<''>, C<q//>, C<"">, +C<``>, C<qq//>, C<qx//>, C<< <file*glob> >>, C<?RE?>, C</RE/>, C<m/RE/>, +C<s/RE/foo/>,, Interpolation of regular expressions, Optimization of +regular expressions + +=item I/O Operators + +=item Constant Folding + +=item Bitwise String Operators + +=item Integer Arithmetic + +=item Floating-point Arithmetic + +=item Bigger Numbers + +=back + +=back + +=head2 perlsub - Perl subroutines + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Private Variables via my() + +=item Persistent Private Variables + +=item Temporary Values via local() + +=item Lvalue subroutines + +=item Passing Symbol Table Entries (typeglobs) + +=item When to Still Use local() + +=item Pass by Reference + +=item Prototypes + +=item Constant Functions + +=item Overriding Built-in Functions + +=item Autoloading + +=item Subroutine Attributes + +=back + +=item SEE ALSO + +=back + +=head2 perlfunc - Perl builtin functions + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Perl Functions by Category + +Functions for SCALARs or strings, Regular expressions and pattern matching, +Numeric functions, Functions for real @ARRAYs, Functions for list data, +Functions for real %HASHes, Input and output functions, Functions for fixed +length data or records, Functions for filehandles, files, or directories, +Keywords related to the control flow of your perl program, Keywords related +to scoping, Miscellaneous functions, Functions for processes and process +groups, Keywords related to perl modules, Keywords related to classes and +object-orientedness, Low-level socket functions, System V interprocess +communication functions, Fetching user and group info, Fetching network +info, Time-related functions, Functions new in perl5, Functions obsoleted +in perl5 + +=item Portability + +=item Alphabetical Listing of Perl Functions + +I<-X> FILEHANDLE, I<-X> EXPR, I<-X>, abs VALUE, abs, accept +NEWSOCKET,GENERICSOCKET, alarm SECONDS, alarm, atan2 Y,X, bind SOCKET,NAME, +binmode FILEHANDLE, DISCIPLINE, binmode FILEHANDLE, bless REF,CLASSNAME, +bless REF, caller EXPR, caller, chdir EXPR, chmod LIST, chomp VARIABLE, +chomp LIST, chomp, chop VARIABLE, chop LIST, chop, chown LIST, chr NUMBER, +chr, chroot FILENAME, chroot, close FILEHANDLE, close, closedir DIRHANDLE, +connect SOCKET,NAME, continue BLOCK, cos EXPR, cos, crypt PLAINTEXT,SALT, +dbmclose HASH, dbmopen HASH,DBNAME,MASK, defined EXPR, defined, delete +EXPR, die LIST, do BLOCK, do SUBROUTINE(LIST), do EXPR, dump LABEL, dump, +each HASH, eof FILEHANDLE, eof (), eof, eval EXPR, eval BLOCK, exec LIST, +exec PROGRAM LIST, exists EXPR, exit EXPR, exp EXPR, exp, fcntl +FILEHANDLE,FUNCTION,SCALAR, fileno FILEHANDLE, flock FILEHANDLE,OPERATION, +fork, format, formline PICTURE,LIST, getc FILEHANDLE, getc, getlogin, +getpeername SOCKET, getpgrp PID, getppid, getpriority WHICH,WHO, getpwnam +NAME, getgrnam NAME, gethostbyname NAME, getnetbyname NAME, getprotobyname +NAME, getpwuid UID, getgrgid GID, getservbyname NAME,PROTO, gethostbyaddr +ADDR,ADDRTYPE, getnetbyaddr ADDR,ADDRTYPE, getprotobynumber NUMBER, +getservbyport PORT,PROTO, getpwent, getgrent, gethostent, getnetent, +getprotoent, getservent, setpwent, setgrent, sethostent STAYOPEN, setnetent +STAYOPEN, setprotoent STAYOPEN, setservent STAYOPEN, endpwent, endgrent, +endhostent, endnetent, endprotoent, endservent, getsockname SOCKET, +getsockopt SOCKET,LEVEL,OPTNAME, glob EXPR, glob, gmtime EXPR, goto LABEL, +goto EXPR, goto &NAME, grep BLOCK LIST, grep EXPR,LIST, hex EXPR, hex, +import, index STR,SUBSTR,POSITION, index STR,SUBSTR, int EXPR, int, ioctl +FILEHANDLE,FUNCTION,SCALAR, join EXPR,LIST, keys HASH, kill SIGNAL, LIST, +last LABEL, last, lc EXPR, lc, lcfirst EXPR, lcfirst, length EXPR, length, +link OLDFILE,NEWFILE, listen SOCKET,QUEUESIZE, local EXPR, localtime EXPR, +lock, log EXPR, log, lstat FILEHANDLE, lstat EXPR, lstat, m//, map BLOCK +LIST, map EXPR,LIST, mkdir FILENAME,MASK, mkdir FILENAME, msgctl +ID,CMD,ARG, msgget KEY,FLAGS, msgrcv ID,VAR,SIZE,TYPE,FLAGS, msgsnd +ID,MSG,FLAGS, my EXPR, my EXPR : ATTRIBUTES, next LABEL, next, no Module +LIST, oct EXPR, oct, open FILEHANDLE,MODE,LIST, open FILEHANDLE,EXPR, open +FILEHANDLE, opendir DIRHANDLE,EXPR, ord EXPR, ord, our EXPR, pack +TEMPLATE,LIST, package NAMESPACE, package, pipe READHANDLE,WRITEHANDLE, pop +ARRAY, pop, pos SCALAR, pos, print FILEHANDLE LIST, print LIST, print, +printf FILEHANDLE FORMAT, LIST, printf FORMAT, LIST, prototype FUNCTION, +push ARRAY,LIST, q/STRING/, qq/STRING/, qr/STRING/, qx/STRING/, qw/STRING/, +quotemeta EXPR, quotemeta, rand EXPR, rand, read +FILEHANDLE,SCALAR,LENGTH,OFFSET, read FILEHANDLE,SCALAR,LENGTH, readdir +DIRHANDLE, readline EXPR, readlink EXPR, readlink, readpipe EXPR, recv +SOCKET,SCALAR,LENGTH,FLAGS, redo LABEL, redo, ref EXPR, ref, rename +OLDNAME,NEWNAME, require VERSION, require EXPR, require, reset EXPR, reset, +return EXPR, return, reverse LIST, rewinddir DIRHANDLE, rindex +STR,SUBSTR,POSITION, rindex STR,SUBSTR, rmdir FILENAME, rmdir, s///, scalar +EXPR, seek FILEHANDLE,POSITION,WHENCE, seekdir DIRHANDLE,POS, select +FILEHANDLE, select, select RBITS,WBITS,EBITS,TIMEOUT, semctl +ID,SEMNUM,CMD,ARG, semget KEY,NSEMS,FLAGS, semop KEY,OPSTRING, send +SOCKET,MSG,FLAGS,TO, send SOCKET,MSG,FLAGS, setpgrp PID,PGRP, setpriority +WHICH,WHO,PRIORITY, setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL, shift ARRAY, +shift, shmctl ID,CMD,ARG, shmget KEY,SIZE,FLAGS, shmread ID,VAR,POS,SIZE, +shmwrite ID,STRING,POS,SIZE, shutdown SOCKET,HOW, sin EXPR, sin, sleep +EXPR, sleep, socket SOCKET,DOMAIN,TYPE,PROTOCOL, socketpair +SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL, sort SUBNAME LIST, sort BLOCK LIST, +sort LIST, splice ARRAY,OFFSET,LENGTH,LIST, splice ARRAY,OFFSET,LENGTH, +splice ARRAY,OFFSET, splice ARRAY, split /PATTERN/,EXPR,LIMIT, split +/PATTERN/,EXPR, split /PATTERN/, split, sprintf FORMAT, LIST, sqrt EXPR, +sqrt, srand EXPR, srand, stat FILEHANDLE, stat EXPR, stat, study SCALAR, +study, sub BLOCK, sub NAME, sub NAME BLOCK, substr +EXPR,OFFSET,LENGTH,REPLACEMENT, substr EXPR,OFFSET,LENGTH, substr +EXPR,OFFSET, symlink OLDFILE,NEWFILE, syscall LIST, sysopen +FILEHANDLE,FILENAME,MODE, sysopen FILEHANDLE,FILENAME,MODE,PERMS, sysread +FILEHANDLE,SCALAR,LENGTH,OFFSET, sysread FILEHANDLE,SCALAR,LENGTH, sysseek +FILEHANDLE,POSITION,WHENCE, system LIST, system PROGRAM LIST, syswrite +FILEHANDLE,SCALAR,LENGTH,OFFSET, syswrite FILEHANDLE,SCALAR,LENGTH, +syswrite FILEHANDLE,SCALAR, tell FILEHANDLE, tell, telldir DIRHANDLE, tie +VARIABLE,CLASSNAME,LIST, tied VARIABLE, time, times, tr///, truncate +FILEHANDLE,LENGTH, truncate EXPR,LENGTH, uc EXPR, uc, ucfirst EXPR, +ucfirst, umask EXPR, umask, undef EXPR, undef, unlink LIST, unlink, unpack +TEMPLATE,EXPR, untie VARIABLE, unshift ARRAY,LIST, use Module VERSION LIST, +use Module VERSION, use Module LIST, use Module, use VERSION, utime LIST, +values HASH, vec EXPR,OFFSET,BITS, wait, waitpid PID,FLAGS, wantarray, warn +LIST, write FILEHANDLE, write EXPR, write, y/// + +=back + +=back + +=head2 perlreftut - Mark's very short tutorial about references + +=over 4 + +=item DESCRIPTION + +=item Who Needs Complicated Data Structures? + +=item The Solution + +=item Syntax + +=over 4 + +=item Making References + +=item Using References + +=back + +=item An Example + +=item Arrow Rule + +=item Solution + +=item The Rest + +=item Summary + +=item Credits + +=over 4 + +=item Distribution Conditions + +=back + +=back + +=head2 perldsc - Perl Data Structures Cookbook + +=over 4 + +=item DESCRIPTION + +arrays of arrays, hashes of arrays, arrays of hashes, hashes of hashes, +more elaborate constructs + +=item REFERENCES + +=item COMMON MISTAKES + +=item CAVEAT ON PRECEDENCE + +=item WHY YOU SHOULD ALWAYS C<use strict> + +=item DEBUGGING + +=item CODE EXAMPLES + +=item ARRAYS OF ARRAYS + +=over 4 + +=item Declaration of a ARRAY OF ARRAYS + +=item Generation of a ARRAY OF ARRAYS + +=item Access and Printing of a ARRAY OF ARRAYS + +=back + +=item HASHES OF ARRAYS + +=over 4 + +=item Declaration of a HASH OF ARRAYS + +=item Generation of a HASH OF ARRAYS + +=item Access and Printing of a HASH OF ARRAYS + +=back + +=item ARRAYS OF HASHES + +=over 4 + +=item Declaration of a ARRAY OF HASHES + +=item Generation of a ARRAY OF HASHES + +=item Access and Printing of a ARRAY OF HASHES + +=back + +=item HASHES OF HASHES + +=over 4 + +=item Declaration of a HASH OF HASHES + +=item Generation of a HASH OF HASHES + +=item Access and Printing of a HASH OF HASHES + +=back + +=item MORE ELABORATE RECORDS + +=over 4 + +=item Declaration of MORE ELABORATE RECORDS + +=item Declaration of a HASH OF COMPLEX RECORDS + +=item Generation of a HASH OF COMPLEX RECORDS + +=back + +=item Database Ties + +=item SEE ALSO + +=item AUTHOR + +=back + +=head2 perlrequick - Perl regular expressions quick start + +=over 4 + +=item DESCRIPTION + +=item The Guide + +=over 4 + +=item Simple word matching + +=item Using character classes + +=item Matching this or that + +=item Grouping things and hierarchical matching + +=item Extracting matches + +=item Matching repetitions + +=item More matching + +=item Search and replace + +=item The split operator + +=back + +=item BUGS + +=item SEE ALSO + +=item AUTHOR AND COPYRIGHT + +=over 4 + +=item Acknowledgments + +=back + +=back + +=head2 perlpod - plain old documentation + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Verbatim Paragraph + +=item Command Paragraph + +=item Ordinary Block of Text + +=item The Intent + +=item Embedding Pods in Perl Modules + +=item Common Pod Pitfalls + +=back + +=item SEE ALSO + +=item AUTHOR + +=back + +=head2 perlstyle - Perl style guide + +=over 4 + +=item DESCRIPTION + +=back + +=head2 perltrap - Perl traps for the unwary + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Awk Traps + +=item C Traps + +=item Sed Traps + +=item Shell Traps + +=item Perl Traps + +=item Perl4 to Perl5 Traps + +Discontinuance, Deprecation, and BugFix traps, Parsing Traps, Numerical +Traps, General data type traps, Context Traps - scalar, list contexts, +Precedence Traps, General Regular Expression Traps using s///, etc, +Subroutine, Signal, Sorting Traps, OS Traps, DBM Traps, Unclassified Traps + +=item Discontinuance, Deprecation, and BugFix traps + +Discontinuance, Deprecation, BugFix, Discontinuance, Discontinuance, +Discontinuance, BugFix, Discontinuance, Discontinuance, BugFix, +Discontinuance, Deprecation, Discontinuance, Discontinuance + +=item Parsing Traps + +Parsing, Parsing, Parsing, Parsing + +=item Numerical Traps + +Numerical, Numerical, Numerical, Bitwise string ops + +=item General data type traps + +(Arrays), (Arrays), (Hashes), (Globs), (Globs), (Scalar String), +(Constants), (Scalars), (Variable Suicide) + +=item Context Traps - scalar, list contexts + +(list context), (scalar context), (scalar context), (list, builtin) + +=item Precedence Traps + +Precedence, Precedence, Precedence, Precedence, Precedence, Precedence, +Precedence + +=item General Regular Expression Traps using s///, etc. + +Regular Expression, Regular Expression, Regular Expression, Regular +Expression, Regular Expression, Regular Expression, Regular Expression, +Regular Expression + +=item Subroutine, Signal, Sorting Traps + +(Signals), (Sort Subroutine), warn() won't let you specify a filehandle + +=item OS Traps + +(SysV), (SysV) + +=item Interpolation Traps + +Interpolation, Interpolation, Interpolation, Interpolation, Interpolation, +Interpolation, Interpolation, Interpolation, Interpolation + +=item DBM Traps + +DBM, DBM + +=item Unclassified Traps + +C<require>/C<do> trap using returned value, C<split> on empty string with +LIMIT specified + +=back + +=back + +=head2 perlrun - how to execute the Perl interpreter + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item #! and quoting on non-Unix systems + +OS/2, MS-DOS, Win95/NT, Macintosh, VMS + +=item Location of Perl + +=item Command Switches + +B<-0>[I<digits>], B<-a>, B<-C>, B<-c>, B<-d>, B<-d:>I<foo[=bar,baz]>, +B<-D>I<letters>, B<-D>I<number>, B<-e> I<commandline>, B<-F>I<pattern>, +B<-h>, B<-i>[I<extension>], B<-I>I<directory>, B<-l>[I<octnum>], +B<-m>[B<->]I<module>, B<-M>[B<->]I<module>, B<-M>[B<->]I<'module ...'>, +B<-[mM]>[B<->]I<module=arg[,arg]...>, B<-n>, B<-p>, B<-P>, B<-s>, B<-S>, +B<-T>, B<-u>, B<-U>, B<-v>, B<-V>, B<-V:>I<name>, B<-w>, B<-W>, B<-X>, +B<-x> I<directory> + +=back + +=item ENVIRONMENT + +HOME, LOGDIR, PATH, PERL5LIB, PERL5OPT, PERLLIB, PERL5DB, PERL5SHELL +(specific to the Win32 port), PERL_DEBUG_MSTATS, PERL_DESTRUCT_LEVEL, +PERL_ROOT (specific to the VMS port), SYS$LOGIN (specific to the VMS port) + +=back + +=head2 perldiag - various Perl diagnostics + +=over 4 + +=item DESCRIPTION + +=back + +=head2 perllexwarn - Perl Lexical Warnings + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Default Warnings and Optional Warnings + +=item What's wrong with B<-w> and C<$^W> + +=item Controlling Warnings from the Command Line + +B<-w>, B<-W>, B<-X> + +=item Backward Compatibility + +=item Category Hierarchy + +=item Fatal Warnings + +=item Reporting Warnings from a Module + +=back + +=item TODO + +=item SEE ALSO + +=item AUTHOR + +=back + +=head2 perldebtut - Perl debugging tutorial + +=over 4 + +=item DESCRIPTION + +=item use strict + +=item Looking at data and -w and w + +=item help + +=item Stepping through code + +=item Placeholder for a, w, t, T + +=item REGULAR EXPRESSIONS + +=item OUTPUT TIPS + +=item CGI + +=item GUIs + +=item SUMMARY + +=item SEE ALSO + +=item AUTHOR + +=item CONTRIBUTORS + +=back + +=head2 perldebug - Perl debugging + +=over 4 + +=item DESCRIPTION + +=item The Perl Debugger + +=over 4 + +=item Debugger Commands + +h [command], p expr, x expr, V [pkg [vars]], X [vars], T, s [expr], n +[expr], r, <CR>, c [line|sub], l, l min+incr, l min-max, l line, l subname, +-, w [line], f filename, /pattern/, ?pattern?, L, S [[!]regex], t, t expr, +b [line] [condition], b subname [condition], b postpone subname +[condition], b load filename, b compile subname, d [line], D, a [line] +command, a [line], A, W expr, W, O booloption .., O anyoption? .., O +option=value .., < ?, < [ command ], << command, > ?, > command, >> +command, { ?, { [ command ], {{ command, ! number, ! -number, ! pattern, !! +cmd, H -number, q or ^D, R, |dbcmd, ||dbcmd, command, m expr, man [manpage] + +=item Configurable Options + +C<recallCommand>, C<ShellBang>, C<pager>, C<tkRunning>, C<signalLevel>, +C<warnLevel>, C<dieLevel>, C<AutoTrace>, C<LineInfo>, C<inhibit_exit>, +C<PrintRet>, C<ornaments>, C<frame>, C<maxTraceLen>, C<arrayDepth>, +C<hashDepth>, C<compactDump>, C<veryCompact>, C<globPrint>, C<DumpDBFiles>, +C<DumpPackages>, C<DumpReused>, C<quote>, C<HighBit>, C<undefPrint>, +C<UsageOnly>, C<TTY>, C<noTTY>, C<ReadLine>, C<NonStop> + +=item Debugger input/output + +Prompt, Multiline commands, Stack backtrace, Line Listing Format, Frame +listing + +=item Debugging compile-time statements + +=item Debugger Customization + +=item Readline Support + +=item Editor Support for Debugging + +=item The Perl Profiler + +=back + +=item Debugging regular expressions + +=item Debugging memory usage + +=item SEE ALSO + +=item BUGS + +=back + +=head2 perlvar - Perl predefined variables + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Predefined Names + +$ARG, $_, $<I<digits>>, $MATCH, $&, $PREMATCH, $`, $POSTMATCH, $', +$LAST_PAREN_MATCH, $+, @LAST_MATCH_END, @+, $MULTILINE_MATCHING, $*, +input_line_number HANDLE EXPR, $INPUT_LINE_NUMBER, $NR, $, +input_record_separator HANDLE EXPR, $INPUT_RECORD_SEPARATOR, $RS, $/, +autoflush HANDLE EXPR, $OUTPUT_AUTOFLUSH, $|, output_field_separator HANDLE +EXPR, $OUTPUT_FIELD_SEPARATOR, $OFS, $,, output_record_separator HANDLE +EXPR, $OUTPUT_RECORD_SEPARATOR, $ORS, $\, $LIST_SEPARATOR, $", +$SUBSCRIPT_SEPARATOR, $SUBSEP, $;, $OFMT, $#, format_page_number HANDLE +EXPR, $FORMAT_PAGE_NUMBER, $%, format_lines_per_page HANDLE EXPR, +$FORMAT_LINES_PER_PAGE, $=, format_lines_left HANDLE EXPR, +$FORMAT_LINES_LEFT, $-, @LAST_MATCH_START, @-, C<$`> is the same as +C<substr($var, 0, $-[0])>, C<$&> is the same as C<substr($var, $-[0], $+[0] +- $-[0])>, C<$'> is the same as C<substr($var, $+[0])>, C<$1> is the same +as C<substr($var, $-[1], $+[1] - $-[1])>, C<$2> is the same as +C<substr($var, $-[2], $+[2] - $-[2])>, C<$3> is the same as C<substr $var, +$-[3], $+[3] - $-[3])>, format_name HANDLE EXPR, $FORMAT_NAME, $~, +format_top_name HANDLE EXPR, $FORMAT_TOP_NAME, $^, +format_line_break_characters HANDLE EXPR, $FORMAT_LINE_BREAK_CHARACTERS, +$:, format_formfeed HANDLE EXPR, $FORMAT_FORMFEED, $^L, $ACCUMULATOR, $^A, +$CHILD_ERROR, $?, $OS_ERROR, $ERRNO, $!, $EXTENDED_OS_ERROR, $^E, +$EVAL_ERROR, $@, $PROCESS_ID, $PID, $$, $REAL_USER_ID, $UID, $<, +$EFFECTIVE_USER_ID, $EUID, $>, $REAL_GROUP_ID, $GID, $(, +$EFFECTIVE_GROUP_ID, $EGID, $), $PROGRAM_NAME, $0, $[, $], $COMPILING, $^C, +$DEBUGGING, $^D, $SYSTEM_FD_MAX, $^F, $^H, %^H, $INPLACE_EDIT, $^I, $^M, +$OSNAME, $^O, $PERLDB, $^P, 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80, +0x100, 0x200, $LAST_REGEXP_CODE_RESULT, $^R, $EXCEPTIONS_BEING_CAUGHT, $^S, +$BASETIME, $^T, $PERL_VERSION, $^V, $WARNING, $^W, ${^WARNING_BITS}, +${^WIDE_SYSTEM_CALLS}, $EXECUTABLE_NAME, $^X, $ARGV, @ARGV, @INC, @_, %INC, +%ENV, $ENV{expr}, %SIG, $SIG{expr} + +=item Error Indicators + +=item Technical Note on the Syntax of Variable Names + +=back + +=item BUGS + +=back + +=head2 perllol - Manipulating Arrays of Arrays in Perl + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Declaration and Access of Arrays of Arrays + +=item Growing Your Own + +=item Access and Printing + +=item Slices + +=back + +=item SEE ALSO + +=item AUTHOR + +=back + +=head2 perlopentut - tutorial on opening things in Perl + +=over 4 + +=item DESCRIPTION + +=item Open E<agrave> la shell + +=over 4 + +=item Simple Opens + +=item Pipe Opens + +=item The Minus File + +=item Mixing Reads and Writes + +=item Filters + +=back + +=item Open E<agrave> la C + +=over 4 + +=item Permissions E<agrave> la mode + +=back + +=item Obscure Open Tricks + +=over 4 + +=item Re-Opening Files (dups) + +=item Dispelling the Dweomer + +=item Paths as Opens + +=item Single Argument Open + +=item Playing with STDIN and STDOUT + +=back + +=item Other I/O Issues + +=over 4 + +=item Opening Non-File Files + +=item Binary Files + +=item File Locking + +=back + +=item SEE ALSO + +=item AUTHOR and COPYRIGHT + +=item HISTORY + +=back + +=head2 perlretut - Perl regular expressions tutorial + +=over 4 + +=item DESCRIPTION + +=item Part 1: The basics + +=over 4 + +=item Simple word matching + +=item Using character classes + +=item Matching this or that + +=item Grouping things and hierarchical matching + +=item Extracting matches + +=item Matching repetitions + +=item Building a regexp + +=item Using regular expressions in Perl + +=back + +=item Part 2: Power tools + +=over 4 + +=item More on characters, strings, and character classes + +=item Compiling and saving regular expressions + +=item Embedding comments and modifiers in a regular expression + +=item Non-capturing groupings + +=item Looking ahead and looking behind + +=item Using independent subexpressions to prevent backtracking + +=item Conditional expressions + +=item A bit of magic: executing Perl code in a regular expression + +=item Pragmas and debugging + +=back + +=item BUGS + +=item SEE ALSO + +=item AUTHOR AND COPYRIGHT + +=over 4 + +=item Acknowledgments + +=back + +=back + +=head2 perlre - Perl regular expressions + +=over 4 + +=item DESCRIPTION + +i, m, s, x + +=over 4 + +=item Regular Expressions + +cntrl, graph, print, punct, xdigit + +=item Extended Patterns + +C<(?#text)>, C<(?imsx-imsx)>, C<(?:pattern)>, C<(?imsx-imsx:pattern)>, +C<(?=pattern)>, C<(?!pattern)>, C<(?<=pattern)>, C<(?<!pattern)>, C<(?{ +code })>, C<(??{ code })>, C<< (?>pattern) >>, +C<(?(condition)yes-pattern|no-pattern)>, C<(?(condition)yes-pattern)> + +=item Backtracking + +=item Version 8 Regular Expressions + +=item Warning on \1 vs $1 + +=item Repeated patterns matching zero-length substring + +=item Combining pieces together + +C<ST>, C<S|T>, C<S{REPEAT_COUNT}>, C<S{min,max}>, C<S{min,max}?>, C<S?>, +C<S*>, C<S+>, C<S??>, C<S*?>, C<S+?>, C<< (?>S) >>, C<(?=S)>, C<(?<=S)>, +C<(?!S)>, C<(?<!S)>, C<(??{ EXPR })>, +C<(?(condition)yes-pattern|no-pattern)> + +=item Creating custom RE engines + +=back + +=item BUGS + +=item SEE ALSO + +=back + +=head2 perlref - Perl references and nested data structures + +=over 4 + +=item NOTE + +=item DESCRIPTION + +=over 4 + +=item Making References + +=item Using References + +=item Symbolic references + +=item Not-so-symbolic references + +=item Pseudo-hashes: Using an array as a hash + +=item Function Templates + +=back + +=item WARNING + +=item SEE ALSO + +=back + +=head2 perlform - Perl formats + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Format Variables + +=back + +=item NOTES + +=over 4 + +=item Footers + +=item Accessing Formatting Internals + +=back + +=item WARNINGS + +=back + +=head2 perlboot - Beginner's Object-Oriented Tutorial + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item If we could talk to the animals... + +=item Introducing the method invocation arrow + +=item Invoking a barnyard + +=item The extra parameter of method invocation + +=item Calling a second method to simplify things + +=item Inheriting the windpipes + +=item A few notes about @ISA + +=item Overriding the methods + +=item Starting the search from a different place + +=item The SUPER way of doing things + +=item Where we're at so far... + +=item A horse is a horse, of course of course -- or is it? + +=item Invoking an instance method + +=item Accessing the instance data + +=item How to build a horse + +=item Inheriting the constructor + +=item Making a method work with either classes or instances + +=item Adding parameters to a method + +=item More interesting instances + +=item A horse of a different color + +=item Summary + +=back + +=item SEE ALSO + +=item COPYRIGHT + +=back + +=head2 perltoot - Tom's object-oriented tutorial for perl + +=over 4 + +=item DESCRIPTION + +=item Creating a Class + +=over 4 + +=item Object Representation + +=item Class Interface + +=item Constructors and Instance Methods + +=item Planning for the Future: Better Constructors + +=item Destructors + +=item Other Object Methods + +=back + +=item Class Data + +=over 4 + +=item Accessing Class Data + +=item Debugging Methods + +=item Class Destructors + +=item Documenting the Interface + +=back + +=item Aggregation + +=item Inheritance + +=over 4 + +=item Overridden Methods + +=item Multiple Inheritance + +=item UNIVERSAL: The Root of All Objects + +=back + +=item Alternate Object Representations + +=over 4 + +=item Arrays as Objects + +=item Closures as Objects + +=back + +=item AUTOLOAD: Proxy Methods + +=over 4 + +=item Autoloaded Data Methods + +=item Inherited Autoloaded Data Methods + +=back + +=item Metaclassical Tools + +=over 4 + +=item Class::Struct + +=item Data Members as Variables + +=back + +=item NOTES + +=over 4 + +=item Object Terminology + +=back + +=item SEE ALSO + +=item AUTHOR AND COPYRIGHT + +=item COPYRIGHT + +=over 4 + +=item Acknowledgments + +=back + +=back + +=head2 perltootc - Tom's OO Tutorial for Class Data in Perl + +=over 4 + +=item DESCRIPTION + +=item Class Data in a Can + +=item Class Data as Package Variables + +=over 4 + +=item Putting All Your Eggs in One Basket + +=item Inheritance Concerns + +=item The Eponymous Meta-Object + +=item Indirect References to Class Data + +=item Monadic Classes + +=item Translucent Attributes + +=back + +=item Class Data as Lexical Variables + +=over 4 + +=item Privacy and Responsibility + +=item File-Scoped Lexicals + +=item More Inheritance Concerns + +=item Locking the Door and Throwing Away the Key + +=item Translucency Revisited + +=back + +=item NOTES + +=item SEE ALSO + +=item AUTHOR AND COPYRIGHT + +=item ACKNOWLEDGEMENTS + +=item HISTORY + +=back + +=head2 perlobj - Perl objects + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item An Object is Simply a Reference + +=item A Class is Simply a Package + +=item A Method is Simply a Subroutine + +=item Method Invocation + +=item WARNING + +=item Default UNIVERSAL methods + +isa(CLASS), can(METHOD), VERSION( [NEED] ) + +=item Destructors + +=item Summary + +=item Two-Phased Garbage Collection + +=back + +=item SEE ALSO + +=back + +=head2 perlbot - Bag'o Object Tricks (the BOT) + +=over 4 + +=item DESCRIPTION + +=item OO SCALING TIPS + +=item INSTANCE VARIABLES + +=item SCALAR INSTANCE VARIABLES + +=item INSTANCE VARIABLE INHERITANCE + +=item OBJECT RELATIONSHIPS + +=item OVERRIDING SUPERCLASS METHODS + +=item USING RELATIONSHIP WITH SDBM + +=item THINKING OF CODE REUSE + +=item CLASS CONTEXT AND THE OBJECT + +=item INHERITING A CONSTRUCTOR + +=item DELEGATION + +=back + +=head2 perltie - how to hide an object class in a simple variable + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Tying Scalars + +TIESCALAR classname, LIST, FETCH this, STORE this, value, UNTIE this, +DESTROY this + +=item Tying Arrays + +TIEARRAY classname, LIST, FETCH this, index, STORE this, index, value, +FETCHSIZE this, STORESIZE this, count, EXTEND this, count, EXISTS this, +key, DELETE this, key, CLEAR this, PUSH this, LIST, POP this, SHIFT this, +UNSHIFT this, LIST, SPLICE this, offset, length, LIST, UNTIE this, DESTROY +this + +=item Tying Hashes + +USER, HOME, CLOBBER, LIST, TIEHASH classname, LIST, FETCH this, key, STORE +this, key, value, DELETE this, key, CLEAR this, EXISTS this, key, FIRSTKEY +this, NEXTKEY this, lastkey, UNTIE this, DESTROY this + +=item Tying FileHandles + +TIEHANDLE classname, LIST, WRITE this, LIST, PRINT this, LIST, PRINTF this, +LIST, READ this, LIST, READLINE this, GETC this, CLOSE this, UNTIE this, +DESTROY this + +=item UNTIE this + +=item The C<untie> Gotcha + +=back + +=item SEE ALSO + +=item BUGS + +=item AUTHOR + +=back + +=head2 perlipc - Perl interprocess communication (signals, fifos, pipes, +safe subprocesses, sockets, and semaphores) + +=over 4 + +=item DESCRIPTION + +=item Signals + +=item Named Pipes + +=over 4 + +=item WARNING + +=back + +=item Using open() for IPC + +=over 4 + +=item Filehandles + +=item Background Processes + +=item Complete Dissociation of Child from Parent + +=item Safe Pipe Opens + +=item Bidirectional Communication with Another Process + +=item Bidirectional Communication with Yourself + +=back + +=item Sockets: Client/Server Communication + +=over 4 + +=item Internet Line Terminators + +=item Internet TCP Clients and Servers + +=item Unix-Domain TCP Clients and Servers + +=back + +=item TCP Clients with IO::Socket + +=over 4 + +=item A Simple Client + +C<Proto>, C<PeerAddr>, C<PeerPort> + +=item A Webget Client + +=item Interactive Client with IO::Socket + +=back + +=item TCP Servers with IO::Socket + +Proto, LocalPort, Listen, Reuse + +=item UDP: Message Passing + +=item SysV IPC + +=item NOTES + +=item BUGS + +=item AUTHOR + +=item SEE ALSO + +=back + +=head2 perlfork - Perl's fork() emulation (EXPERIMENTAL, subject to change) + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Behavior of other Perl features in forked pseudo-processes + +$$ or $PROCESS_ID, %ENV, chdir() and all other builtins that accept +filenames, wait() and waitpid(), kill(), exec(), exit(), Open handles to +files, directories and network sockets + +=item Resource limits + +=item Killing the parent process + +=item Lifetime of the parent process and pseudo-processes + +=item CAVEATS AND LIMITATIONS + +BEGIN blocks, Open filehandles, Forking pipe open() not yet implemented, +Global state maintained by XSUBs, Interpreter embedded in larger +application, Thread-safety of extensions + +=back + +=item BUGS + +=item AUTHOR + +=item SEE ALSO + +=back + +=head2 perlnumber - semantics of numbers and numeric operations in Perl + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item Storing numbers + +=item Numeric operators and numeric conversions + +=item Flavors of Perl numeric operations + +Arithmetic operators except, C<no integer>, Arithmetic operators except, +C<use integer>, Bitwise operators, C<no integer>, Bitwise operators, C<use +integer>, Operators which expect an integer, Operators which expect a +string + +=item AUTHOR + +=item SEE ALSO + +=back + +=head2 perlthrtut - tutorial on threads in Perl + +=over 4 + +=item DESCRIPTION + +=item What Is A Thread Anyway? + +=item Threaded Program Models + +=over 4 + +=item Boss/Worker + +=item Work Crew + +=item Pipeline + +=back + +=item Native threads + +=item What kind of threads are perl threads? + +=item Threadsafe Modules + +=item Thread Basics + +=over 4 + +=item Basic Thread Support + +=item Creating Threads + +=item Giving up control + +=item Waiting For A Thread To Exit + +=item Errors In Threads + +=item Ignoring A Thread + +=back + +=item Threads And Data + +=over 4 + +=item Shared And Unshared Data + +=item Thread Pitfall: Races + +=item Controlling access: lock() + +=item Thread Pitfall: Deadlocks + +=item Queues: Passing Data Around + +=back + +=item Threads And Code + +=over 4 + +=item Semaphores: Synchronizing Data Access + +Basic semaphores, Advanced Semaphores + +=item Attributes: Restricting Access To Subroutines + +=item Subroutine Locks + +=item Methods + +=item Locking A Subroutine + +=back + +=item General Thread Utility Routines + +=over 4 + +=item What Thread Am I In? + +=item Thread IDs + +=item Are These Threads The Same? + +=item What Threads Are Running? + +=back + +=item A Complete Example + +=item Conclusion + +=item Bibliography + +=over 4 + +=item Introductory Texts + +=item OS-Related References + +=item Other References + +=back + +=item Acknowledgements + +=item AUTHOR + +=item Copyrights + +=back + +=head2 perlport - Writing portable Perl + +=over 4 + +=item DESCRIPTION + +Not all Perl programs have to be portable, Nearly all of Perl already I<is> +portable + +=item ISSUES + +=over 4 + +=item Newlines + +=item Numbers endianness and Width + +=item Files and Filesystems + +=item System Interaction + +=item Interprocess Communication (IPC) + +=item External Subroutines (XS) + +=item Standard Modules + +=item Time and Date + +=item Character sets and character encoding + +=item Internationalisation + +=item System Resources + +=item Security + +=item Style + +=back + +=item CPAN Testers + +Mailing list: cpan-testers@perl.org, Testing results: +http://testers.cpan.org/ + +=item PLATFORMS + +=over 4 + +=item Unix + +=item DOS and Derivatives + +=item S<Mac OS> + +=item VMS + +=item VOS + +=item EBCDIC Platforms + +=item Acorn RISC OS + +=item Other perls + +=back + +=item FUNCTION IMPLEMENTATIONS + +=over 4 + +=item Alphabetical Listing of Perl Functions + +-I<X> FILEHANDLE, -I<X> EXPR, -I<X>, alarm SECONDS, alarm, binmode +FILEHANDLE, chmod LIST, chown LIST, chroot FILENAME, chroot, crypt +PLAINTEXT,SALT, dbmclose HASH, dbmopen HASH,DBNAME,MODE, dump LABEL, exec +LIST, fcntl FILEHANDLE,FUNCTION,SCALAR, flock FILEHANDLE,OPERATION, fork, +getlogin, getpgrp PID, getppid, getpriority WHICH,WHO, getpwnam NAME, +getgrnam NAME, getnetbyname NAME, getpwuid UID, getgrgid GID, getnetbyaddr +ADDR,ADDRTYPE, getprotobynumber NUMBER, getservbyport PORT,PROTO, getpwent, +getgrent, gethostent, getnetent, getprotoent, getservent, setpwent, +setgrent, sethostent STAYOPEN, setnetent STAYOPEN, setprotoent STAYOPEN, +setservent STAYOPEN, endpwent, endgrent, endhostent, endnetent, +endprotoent, endservent, getsockopt SOCKET,LEVEL,OPTNAME, glob EXPR, glob, +ioctl FILEHANDLE,FUNCTION,SCALAR, kill SIGNAL, LIST, link OLDFILE,NEWFILE, +lstat FILEHANDLE, lstat EXPR, lstat, msgctl ID,CMD,ARG, msgget KEY,FLAGS, +msgsnd ID,MSG,FLAGS, msgrcv ID,VAR,SIZE,TYPE,FLAGS, open FILEHANDLE,EXPR, +open FILEHANDLE, pipe READHANDLE,WRITEHANDLE, readlink EXPR, readlink, +select RBITS,WBITS,EBITS,TIMEOUT, semctl ID,SEMNUM,CMD,ARG, semget +KEY,NSEMS,FLAGS, semop KEY,OPSTRING, setgrent, setpgrp PID,PGRP, +setpriority WHICH,WHO,PRIORITY, setpwent, setsockopt +SOCKET,LEVEL,OPTNAME,OPTVAL, shmctl ID,CMD,ARG, shmget KEY,SIZE,FLAGS, +shmread ID,VAR,POS,SIZE, shmwrite ID,STRING,POS,SIZE, socketpair +SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL, stat FILEHANDLE, stat EXPR, stat, +symlink OLDFILE,NEWFILE, syscall LIST, sysopen +FILEHANDLE,FILENAME,MODE,PERMS, system LIST, times, truncate +FILEHANDLE,LENGTH, truncate EXPR,LENGTH, umask EXPR, umask, utime LIST, +wait, waitpid PID,FLAGS + +=back + +=item CHANGES + +v1.48, 02 February 2001, v1.47, 22 March 2000, v1.46, 12 February 2000, +v1.45, 20 December 1999, v1.44, 19 July 1999, v1.43, 24 May 1999, v1.42, 22 +May 1999, v1.41, 19 May 1999, v1.40, 11 April 1999, v1.39, 11 February +1999, v1.38, 31 December 1998, v1.37, 19 December 1998, v1.36, 9 September +1998, v1.35, 13 August 1998, v1.33, 06 August 1998, v1.32, 05 August 1998, +v1.30, 03 August 1998, v1.23, 10 July 1998 + +=item Supported Platforms + +=item SEE ALSO + +=item AUTHORS / CONTRIBUTORS + +=item VERSION + +=back + +=head2 perllocale - Perl locale handling (internationalization and +localization) + +=over 4 + +=item DESCRIPTION + +=item PREPARING TO USE LOCALES + +=item USING LOCALES + +=over 4 + +=item The use locale pragma + +=item The setlocale function + +=item Finding locales + +=item LOCALE PROBLEMS + +=item Temporarily fixing locale problems + +=item Permanently fixing locale problems + +=item Permanently fixing your system's locale configuration + +=item Fixing system locale configuration + +=item The localeconv function + +=back + +=item LOCALE CATEGORIES + +=over 4 + +=item Category LC_COLLATE: Collation + +=item Category LC_CTYPE: Character Types + +=item Category LC_NUMERIC: Numeric Formatting + +=item Category LC_MONETARY: Formatting of monetary amounts + +=item LC_TIME + +=item Other categories + +=back + +=item SECURITY + +=item ENVIRONMENT + +PERL_BADLANG, LC_ALL, LANGUAGE, LC_CTYPE, LC_COLLATE, LC_MONETARY, +LC_NUMERIC, LC_TIME, LANG + +=item NOTES + +=over 4 + +=item Backward compatibility + +=item I18N:Collate obsolete + +=item Sort speed and memory use impacts + +=item write() and LC_NUMERIC + +=item Freely available locale definitions + +=item I18n and l10n + +=item An imperfect standard + +=back + +=item BUGS + +=over 4 + +=item Broken systems + +=back + +=item SEE ALSO + +=item HISTORY + +=back + +=head2 perlunicode - Unicode support in Perl (EXPERIMENTAL, subject to +change) + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Important Caveat + +Input and Output Disciplines, Regular Expressions, C<use utf8> still needed +to enable a few features + +=item Byte and Character semantics + +=item Effects of character semantics + +=item Character encodings for input and output + +=back + +=item CAVEATS + +=item SEE ALSO + +=back + +=head2 perlebcdic - Considerations for running Perl on EBCDIC platforms + +=over 4 + +=item DESCRIPTION + +=item COMMON CHARACTER CODE SETS + +=over 4 + +=item ASCII + +=item ISO 8859 + +=item Latin 1 (ISO 8859-1) + +=item EBCDIC + +=item 13 variant characters + +=item 0037 + +=item 1047 + +=item POSIX-BC + +=back + +=item SINGLE OCTET TABLES + +recipe 0, recipe 1, recipe 2, recipe 3, recipe 4 + +=item IDENTIFYING CHARACTER CODE SETS + +=item CONVERSIONS + +=over 4 + +=item tr/// + +=item iconv + +=item C RTL + +=back + +=item OPERATOR DIFFERENCES + +=item FUNCTION DIFFERENCES + +chr(), ord(), pack(), print(), printf(), sort(), sprintf(), unpack() + +=item REGULAR EXPRESSION DIFFERENCES + +=item SOCKETS + +=item SORTING + +=over 4 + +=item Ignore ASCII vs. EBCDIC sort differences. + +=item MONO CASE then sort data. + +=item Convert, sort data, then re convert. + +=item Perform sorting on one type of machine only. + +=back + +=item TRANFORMATION FORMATS + +=over 4 + +=item URL decoding and encoding + +=item uu encoding and decoding + +=item Quoted-Printable encoding and decoding + +=item Caesarian cyphers + +=back + +=item Hashing order and checksums + +=item I18N AND L10N + +=item MULTI OCTET CHARACTER SETS + +=item OS ISSUES + +=over 4 + +=item OS/400 + +IFS access + +=item OS/390 + +chcp, dataset access, OS/390 iconv, locales + +=item VM/ESA? + +=item POSIX-BC? + +=back + +=item BUGS + +=item SEE ALSO + +=item REFERENCES + +=item AUTHOR + +=back + +=head2 perlsec - Perl security + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Laundering and Detecting Tainted Data + +=item Switches On the "#!" Line + +=item Cleaning Up Your Path + +=item Security Bugs + +=item Protecting Your Programs + +=back + +=item SEE ALSO + +=back + +=head2 perlmod - Perl modules (packages and symbol tables) + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Packages + +=item Symbol Tables + +=item Package Constructors and Destructors + +=item Perl Classes + +=item Perl Modules + +=back + +=item SEE ALSO + +=back + +=head2 perlmodlib - constructing new Perl modules and finding existing ones + +=over 4 + +=item DESCRIPTION + +=item THE PERL MODULE LIBRARY + +=over 4 + +=item Pragmatic Modules + +attributes, attrs, autouse, base, blib, bytes, charnames, constant, +diagnostics, fields, filetest, integer, less, lib, locale, open, ops, +overload, re, sigtrap, strict, subs, utf8, vars, warnings, +warnings::register + +=item Standard Modules + +AnyDBM_File, AutoLoader, AutoSplit, B, B::Asmdata, B::Assembler, B::Bblock, +B::Bytecode, B::C, B::CC, B::Concise, B::Debug, B::Deparse, +B::Disassembler, B::Lint, B::Showlex, B::Stackobj, B::Stash, B::Terse, +B::Xref, Benchmark, ByteLoader, CGI, CGI::Apache, CGI::Carp, CGI::Cookie, +CGI::Fast, CGI::Pretty, CGI::Push, CGI::Switch, CGI::Util, CPAN, +CPAN::FirstTime, CPAN::Nox, Carp, Carp::Heavy, Class::Struct, Cwd, DB, +DB_File, Devel::SelfStubber, DirHandle, Dumpvalue, English, Env, Exporter, +Exporter::Heavy, ExtUtils::Command, ExtUtils::Embed, ExtUtils::Install, +ExtUtils::Installed, ExtUtils::Liblist, ExtUtils::MM_Cygwin, +ExtUtils::MM_OS2, ExtUtils::MM_Unix, ExtUtils::MM_VMS, ExtUtils::MM_Win32, +ExtUtils::MakeMaker, ExtUtils::Manifest, ExtUtils::Mkbootstrap, +ExtUtils::Mksymlists, ExtUtils::Packlist, ExtUtils::testlib, Fatal, Fcntl, +File::Basename, File::CheckTree, File::Compare, File::Copy, File::DosGlob, +File::Find, File::Path, File::Spec, File::Spec::Epoc, +File::Spec::Functions, File::Spec::Mac, File::Spec::OS2, File::Spec::Unix, +File::Spec::VMS, File::Spec::Win32, File::Temp, File::stat, FileCache, +FileHandle, FindBin, GDBM_File, Getopt::Long, Getopt::Std, I18N::Collate, +IO, IPC::Open2, IPC::Open3, Math::BigFloat, Math::BigInt, Math::Complex, +Math::Trig, Net::Ping, Net::hostent, Net::netent, Net::protoent, +Net::servent, O, Opcode, POSIX, Pod::Checker, Pod::Find, Pod::Html, +Pod::InputObjects, Pod::LaTeX, Pod::Man, Pod::ParseUtils, Pod::Parser, +Pod::Plainer, Pod::Select, Pod::Text, Pod::Text::Color, +Pod::Text::Overstrike, Pod::Text::Termcap, Pod::Usage, SDBM_File, Safe, +Search::Dict, SelectSaver, SelfLoader, Shell, Socket, Symbol, +Term::ANSIColor, Term::Cap, Term::Complete, Term::ReadLine, Test, +Test::Harness, Text::Abbrev, Text::ParseWords, Text::Soundex, Text::Tabs, +Text::Wrap, Thread, Thread::Queue, Thread::Semaphore, Thread::Signal, +Thread::Specific, Tie::Array, Tie::Handle, Tie::Hash, Tie::RefHash, +Tie::Scalar, Tie::SubstrHash, Time::Local, Time::gmtime, Time::localtime, +Time::tm, UNIVERSAL, User::grent, User::pwent, Win32 + +=item Extension Modules + +=back + +=item CPAN + +=over 4 + +=item Africa + +=item Asia + +=item Central America + +=item Europe + +=item North America + +=item Oceania + +=item South America + +=back + +=item Modules: Creation, Use, and Abuse + +=over 4 + +=item Guidelines for Module Creation + +Adding a Copyright Notice + +=item Guidelines for Converting Perl 4 Library Scripts into Modules + +=item Guidelines for Reusing Application Code + +=back + +=item NOTE + +=back + +=head2 perlmodinstall - Installing CPAN Modules + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item PREAMBLE + +B<DECOMPRESS> the file, B<UNPACK> the file into a directory, B<BUILD> the +module (sometimes unnecessary), B<INSTALL> the module + +=back + +=item PORTABILITY + +=item HEY + +=item AUTHOR + +=item COPYRIGHT + +=back + +=head2 perlnewmod - preparing a new module for distribution + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Warning + +=item What should I make into a module? + +=item Step-by-step: Preparing the ground + +Look around, Check it's new, Discuss the need, Choose a name, Check again + +=item Step-by-step: Making the module + +Start with F<h2xs>, Use L<strict|strict> and L<warnings|warnings>, Use +L<Carp|Carp>, Use L<Exporter|Exporter> - wisely!, Use L<plain old +documentation|perlpod>, Write tests, Write the README + +=item Step-by-step: Distributing your module + +Get a CPAN user ID, C<perl Makefile.PL; make test; make dist>, Upload the +tarball, Announce to the modules list, Announce to clpa, Fix bugs! + +=back + +=item AUTHOR + +=item SEE ALSO =back =head2 perlfaq1 - General Questions About Perl ($Revision: 1.23 $, $Date: 1999/05/23 16:08:30 $) -=over +=over 4 =item DESCRIPTION -=over +=over 4 =item What is Perl? @@ -340,7 +2364,7 @@ Scheme, or Tcl? =item Where can I get a list of Larry Wall witticisms? =item How can I convince my sysadmin/supervisor/employees to use version -(5/5.005/Perl instead of some other language)? +5/5.005/Perl instead of some other language? =back @@ -351,11 +2375,11 @@ Scheme, or Tcl? =head2 perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.32 $, $Date: 1999/10/14 18:46:09 $) -=over +=over 4 =item DESCRIPTION -=over +=over 4 =item What machines support Perl? Where do I get it? @@ -407,11 +2431,11 @@ References, Tutorials, Task-Oriented, Special Topics =head2 perlfaq3 - Programming Tools ($Revision: 1.38 $, $Date: 1999/05/23 16:08:30 $) -=over +=over 4 =item DESCRIPTION -=over +=over 4 =item How do I do (anything)? @@ -431,6 +2455,10 @@ References, Tutorials, Task-Oriented, Special Topics =item Is there an IDE or Windows Perl Editor? +CodeMagicCD, Komodo, The Object System, PerlBuilder, Perl code magic, +visiPerl+, GNU Emacs, MicroEMACS, XEmacs, Elvis, Vile, Vim, Codewright, +MultiEdit, SlickEdit, Bash, Ksh, Tcsh, Zsh, BBEdit and BBEdit Lite, Alpha + =item Where can I get Perl macros for vi? =item Where can I get perl-mode for emacs? @@ -472,7 +2500,7 @@ References, Tutorials, Task-Oriented, Special Topics =item Where can I learn about linking C with Perl? [h2xs, xsubpp] =item I've read perlembed, perlguts, etc., but I can't embed perl in -my C program, what am I doing wrong? +my C program; what am I doing wrong? =item When I tried to run my script, I got this message. What does it mean? @@ -488,13 +2516,13 @@ mean? =head2 perlfaq4 - Data Manipulation ($Revision: 1.49 $, $Date: 1999/05/23 20:37:49 $) -=over +=over 4 =item DESCRIPTION =item Data: Numbers -=over +=over 4 =item Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)? @@ -520,7 +2548,7 @@ Trig functions? =item Data: Dates -=over +=over 4 =item How do I find the week-of-the-year/day-of-the-year? @@ -540,7 +2568,7 @@ Trig functions? =item Data: Strings -=over +=over 4 =item How do I validate input? @@ -592,7 +2620,7 @@ the tag =item Data: Arrays -=over +=over 4 =item What is the difference between a list and an array? @@ -600,11 +2628,7 @@ the tag =item How can I remove duplicate elements from a list or array? -a) If @in is sorted, and you want @out to be sorted:(this assumes all true -values in the array), b) If you don't know whether @in is sorted:, c) Like -(b), but @in contains only small integers:, d) A way to do (b) without any -loops or greps:, e) Like (d), but @in contains only small positive -integers: +a), b), c), d), e) =item How can I tell whether a list or array contains a certain element? @@ -637,7 +2661,7 @@ intersection of two arrays? =item Data: Hashes (Associative Arrays) -=over +=over 4 =item How do I process an entire hash? @@ -676,7 +2700,7 @@ array of hashes or arrays? =item Data: Misc -=over +=over 4 =item How do I handle binary data correctly? @@ -701,11 +2725,11 @@ array of hashes or arrays? =head2 perlfaq5 - Files and Formats ($Revision: 1.38 $, $Date: 1999/05/23 16:08:30 $) -=over +=over 4 =item DESCRIPTION -=over +=over 4 =item How do I flush/unbuffer an output filehandle? Why must I do this? @@ -790,11 +2814,11 @@ protected files? Isn't this a bug in Perl? =head2 perlfaq6 - Regexes ($Revision: 1.27 $, $Date: 1999/05/23 16:08:30 $) -=over +=over 4 =item DESCRIPTION -=over +=over 4 =item How can I hope to use regular expressions without creating illegible and unmaintainable code? @@ -808,7 +2832,7 @@ different lines? =item I put a regular expression into $/ but it didn't work. What's wrong? -=item How do I substitute case insensitively on the LHS, but preserving +=item How do I substitute case insensitively on the LHS while preserving case on the RHS? =item How can I make C<\w> match national character sets? @@ -826,7 +2850,7 @@ file? =item What does it mean that regexes are greedy? How can I get around it? -=item How do I process each word on each line? +=item How do I process each word on each line? =item How can I print out a word-frequency or line-frequency summary? @@ -857,11 +2881,11 @@ file? =head2 perlfaq7 - Perl Language Issues ($Revision: 1.28 $, $Date: 1999/05/23 20:36:18 $) -=over +=over 4 =item DESCRIPTION -=over +=over 4 =item Can I get a BNF/yacc/RE for the Perl language? @@ -936,11 +2960,11 @@ is in scope? =head2 perlfaq8 - System Interaction ($Revision: 1.39 $, $Date: 1999/05/23 18:37:57 $) -=over +=over 4 =item DESCRIPTION -=over +=over 4 =item How do I find out which operating system I'm running under? @@ -984,7 +3008,7 @@ STDIN, STDOUT, and STDERR are shared, Signals, Zombies =item How can I do an atexit() or setjmp()/longjmp()? (Exception handling) -=item Why doesn't my sockets program work under System V (Solaris)? What +=item Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean? =item How can I call my system's unique C functions from Perl? @@ -1028,8 +3052,6 @@ complete? =item How do I fork a daemon process? -=item How do I make my program run with sh and csh? - =item How do I find out if I'm running interactively or not? =item How do I timeout a slow event? @@ -1066,13 +3088,13 @@ search path? =head2 perlfaq9 - Networking ($Revision: 1.26 $, $Date: 1999/05/23 16:08:30 $) -=over +=over 4 =item DESCRIPTION -=over +=over 4 -=item My CGI script runs from the command line but not the browser. (500 +=item My CGI script runs from the command line but not the browser. (500 Server Error) =item How can I get better error messages from a CGI program? @@ -1113,6 +3135,8 @@ CGI script to do bad things? =item How do I send mail? +=item How do I use MIME to make an attachment to a mail message? + =item How do I read mail? =item How do I find out my hostname/domainname/IP address? @@ -1129,417 +3153,370 @@ CGI script to do bad things? =back -=head2 perldelta - what's new for perl v5.6.0 +=head2 perlcompile - Introduction to the Perl Compiler-Translator -=over +=over 4 =item DESCRIPTION -=item Core Enhancements +=over 4 -=over +=item Layout -=item Interpreter cloning, threads, and concurrency +B::Bytecode, B::C, B::CC, B::Lint, B::Deparse, B::Xref -=item Lexically scoped warning categories +=back -=item Unicode and UTF-8 support +=item Using The Back Ends -=item Support for interpolating named characters +=over 4 -=item "our" declarations +=item The Cross Referencing Back End -=item Support for strings represented as a vector of ordinals +i, &, s, r -=item Improved Perl version numbering system +=item The Decompiling Back End -=item New syntax for declaring subroutine attributes +=item The Lint Back End -=item File and directory handles can be autovivified +=item The Simple C Back End -=item open() with more than two arguments +=item The Bytecode Back End -=item 64-bit support +=item The Optimized C Back End -=item Large file support +B, O, B::Asmdata, B::Assembler, B::Bblock, B::Bytecode, B::C, B::CC, +B::Debug, B::Deparse, B::Disassembler, B::Lint, B::Showlex, B::Stackobj, +B::Stash, B::Terse, B::Xref -=item Long doubles +=back -=item "more bits" +=item KNOWN PROBLEMS -=item Enhanced support for sort() subroutines +=item AUTHOR -=item C<sort $coderef @foo> allowed +=back -=item File globbing implemented internally +=head2 perlembed - how to embed perl in your C program -Support for CHECK blocks +=over 4 -=item POSIX character class syntax [: :] supported +=item DESCRIPTION -Better pseudo-random number generator +=over 4 -=item Improved C<qw//> operator +=item PREAMBLE -Better worst-case behavior of hashes +B<Use C from Perl?>, B<Use a Unix program from Perl?>, B<Use Perl from +Perl?>, B<Use C from C?>, B<Use Perl from C?> -=item pack() format 'Z' supported +=item ROADMAP -=item pack() format modifier '!' supported +=item Compiling your C program -=item pack() and unpack() support counted strings +=item Adding a Perl interpreter to your C program -=item Comments in pack() templates +=item Calling a Perl subroutine from your C program -=item Weak references +=item Evaluating a Perl statement from your C program -=item Binary numbers supported +=item Performing Perl pattern matches and substitutions from your C program -=item Lvalue subroutines +=item Fiddling with the Perl stack from your C program -=item Some arrows may be omitted in calls through references +=item Maintaining a persistent interpreter -=item Boolean assignment operators are legal lvalues +=item Maintaining multiple interpreter instances -=item exists() is supported on subroutine names +=item Using Perl modules, which themselves use C libraries, from your C +program -=item exists() and delete() are supported on array elements +=back -=item Pseudo-hashes work better +=item Embedding Perl under Win32 -=item Automatic flushing of output buffers +=item MORAL -=item Better diagnostics on meaningless filehandle operations +=item AUTHOR -=item Where possible, buffered data discarded from duped input filehandle +=item COPYRIGHT -=item eof() has the same old magic as <> +=back -=item binmode() can be used to set :crlf and :raw modes +=head2 perldebguts - Guts of Perl debugging -=item C<-T> filetest recognizes UTF-8 encoded files as "text" +=over 4 -=item system(), backticks and pipe open now reflect exec() failure +=item DESCRIPTION -=item Improved diagnostics +=item Debugger Internals -=item Diagnostics follow STDERR +=over 4 -More consistent close-on-exec behavior +=item Writing Your Own Debugger -=item syswrite() ease-of-use +=back -=item Better syntax checks on parenthesized unary operators +=item Frame Listing Output Examples -=item Bit operators support full native integer width +=item Debugging regular expressions -=item Improved security features +=over 4 -More functional bareword prototype (*) +=item Compile-time output -=item C<require> and C<do> may be overridden +C<anchored> I<STRING> C<at> I<POS>, C<floating> I<STRING> C<at> +I<POS1..POS2>, C<matching floating/anchored>, C<minlen>, C<stclass> +I<TYPE>, C<noscan>, C<isall>, C<GPOS>, C<plus>, C<implicit>, C<with eval>, +C<anchored(TYPE)> -=item $^X variables may now have names longer than one character +=item Types of nodes -=item New variable $^C reflects C<-c> switch +=item Run-time output -=item New variable $^V contains Perl version as a string +=back -=item Optional Y2K warnings +=item Debugging Perl memory usage -=back +=over 4 -=item Modules and Pragmata +=item Using C<$ENV{PERL_DEBUG_MSTATS}> -=over +C<buckets SMALLEST(APPROX)..GREATEST(APPROX)>, Free/Used, C<Total sbrk(): +SBRKed/SBRKs:CONTINUOUS>, C<pad: 0>, C<heads: 2192>, C<chain: 0>, C<tail: +6144> -=item Modules +=item Example of using B<-DL> switch -attributes, B, Benchmark, ByteLoader, constant, charnames, Data::Dumper, -DB, DB_File, Devel::DProf, Devel::Peek, Dumpvalue, DynaLoader, English, -Env, Fcntl, File::Compare, File::Find, File::Glob, File::Spec, -File::Spec::Functions, Getopt::Long, IO, JPL, lib, Math::BigInt, -Math::Complex, Math::Trig, Pod::Parser, Pod::InputObjects, Pod::Checker, -podchecker, Pod::ParseUtils, Pod::Find, Pod::Select, podselect, Pod::Usage, -pod2usage, Pod::Text and Pod::Man, SDBM_File, Sys::Syslog, Sys::Hostname, -Term::ANSIColor, Time::Local, Win32, XSLoader, DBM Filters +C<717>, C<002>, C<054>, C<602>, C<702>, C<704> -=item Pragmata +=item B<-DL> details + +C<!!!>, C<!!>, C<!> + +=item Limitations of B<-DL> statistics =back -=item Utility Changes +=item SEE ALSO -=over +=back -=item dprofpp +=head2 perlxstut, perlXStut - Tutorial for writing XSUBs -=item find2perl +=over 4 -=item h2xs +=item DESCRIPTION -=item perlcc +=item SPECIAL NOTES -=item perldoc +=over 4 -=item The Perl Debugger +=item make + +=item Version caveat + +=item Dynamic Loading versus Static Loading =back -=item Improved Documentation +=item TUTORIAL -perlapi.pod, perlboot.pod, perlcompile.pod, perldbmfilter.pod, -perldebug.pod, perldebguts.pod, perlfork.pod, perlfilter.pod, perlhack.pod, -perlintern.pod, perllexwarn.pod, perlnumber.pod, perlopentut.pod, -perlreftut.pod, perltootc.pod, perltodo.pod, perlunicode.pod +=over 4 -=item Performance enhancements +=item EXAMPLE 1 -=over +=item EXAMPLE 2 -=item Simple sort() using { $a <=> $b } and the like are optimized +=item What has gone on? -=item Optimized assignments to lexical variables +=item Writing good test scripts -=item Faster subroutine calls +=item EXAMPLE 3 -delete(), each(), values() and hash iteration are faster +=item What's new here? -=back +=item Input and Output Parameters -=item Installation and Configuration Improvements +=item The XSUBPP Program -=over +=item The TYPEMAP file -=item -Dusethreads means something different +=item Warning about Output Arguments -=item New Configure flags +=item EXAMPLE 4 -=item Threadedness and 64-bitness now more daring +=item What has happened here? -=item Long Doubles +=item Anatomy of .xs file -=item -Dusemorebits +=item Getting the fat out of XSUBs -=item -Duselargefiles +=item More about XSUB arguments -=item installusrbinperl +=item The Argument Stack -=item SOCKS support +=item Extending your Extension -=item C<-A> flag +=item Documenting your Extension -=item Enhanced Installation Directories +=item Installing your Extension -=back +=item EXAMPLE 5 -=item Platform specific changes +=item New Things in this Example -=over +=item EXAMPLE 6 -=item Supported platforms +=item New Things in this Example -=item DOS +=item EXAMPLE 7 (Coming Soon) -=item OS390 (OpenEdition MVS) +=item EXAMPLE 8 (Coming Soon) -=item VMS +=item EXAMPLE 9 (Coming Soon) -=item Win32 +=item Troubleshooting these Examples =back -=item Significant bug fixes +=item See also -=over +=item Author -=item <HANDLE> on empty files +=over 4 -=item C<eval '...'> improvements +=item Last Changed -=item All compilation errors are true errors +=back -=item Implicitly closed filehandles are safer +=back -=item Behavior of list slices is more consistent +=head2 perlxs - XS language reference manual -=item C<(\$)> prototype and C<$foo{a}> +=over 4 -=item C<goto &sub> and AUTOLOAD +=item DESCRIPTION -=item C<-bareword> allowed under C<use integer> +=over 4 -=item Failures in DESTROY() +=item Introduction -=item Locale bugs fixed +=item On The Road -=item Memory leaks +=item The Anatomy of an XSUB -=item Spurious subroutine stubs after failed subroutine calls +=item The Argument Stack -=item Taint failures under C<-U> +=item The RETVAL Variable -=item END blocks and the C<-c> switch +=item The MODULE Keyword -=item Potential to leak DATA filehandles +=item The PACKAGE Keyword -=back +=item The PREFIX Keyword -=item New or Changed Diagnostics +=item The OUTPUT: Keyword -"%s" variable %s masks earlier declaration in same %s, "my sub" not yet -implemented, "our" variable %s redeclared, '!' allowed only after types %s, -/ cannot take a count, / must be followed by a, A or Z, / must be followed -by a*, A* or Z*, / must follow a numeric type, /%s/: Unrecognized escape -\\%c passed through, /%s/: Unrecognized escape \\%c in character class -passed through, /%s/ should probably be written as "%s", %s() called too -early to check prototype, %s argument is not a HASH or ARRAY element, %s -argument is not a HASH or ARRAY element or slice, %s argument is not a -subroutine name, %s package attribute may clash with future reserved word: -%s, (in cleanup) %s, <> should be quotes, Attempt to join self, Bad evalled -substitution pattern, Bad realloc() ignored, Bareword found in conditional, -Binary number > 0b11111111111111111111111111111111 non-portable, Bit vector -size > 32 non-portable, Buffer overflow in prime_env_iter: %s, Can't check -filesystem of script "%s", Can't declare class for non-scalar %s in "%s", -Can't declare %s in "%s", Can't ignore signal CHLD, forcing to default, -Can't modify non-lvalue subroutine call, Can't read CRTL environ, Can't -remove %s: %s, skipping file, Can't return %s from lvalue subroutine, Can't -weaken a nonreference, Character class [:%s:] unknown, Character class -syntax [%s] belongs inside character classes, Constant is not %s reference, -constant(%s): %s, CORE::%s is not a keyword, defined(@array) is deprecated, -defined(%hash) is deprecated, Did not produce a valid header, (Did you mean -"local" instead of "our"?), Document contains no data, entering effective -%s failed, false [] range "%s" in regexp, Filehandle %s opened only for -output, flock() on closed filehandle %s, Global symbol "%s" requires -explicit package name, Hexadecimal number > 0xffffffff non-portable, -Ill-formed CRTL environ value "%s", Ill-formed message in prime_env_iter: -|%s|, Illegal binary digit %s, Illegal binary digit %s ignored, Illegal -number of bits in vec, Integer overflow in %s number, Invalid %s attribute: -%s, Invalid %s attributes: %s, invalid [] range "%s" in regexp, Invalid -separator character %s in attribute list, Invalid separator character %s in -subroutine attribute list, leaving effective %s failed, Lvalue subs -returning %s not implemented yet, Method %s not permitted, Missing -%sbrace%s on \N{}, Missing command in piped open, Missing name in "my sub", -No %s specified for -%c, No package name allowed for variable %s in "our", -No space allowed after -%c, no UTC offset information; assuming local time -is UTC, Octal number > 037777777777 non-portable, panic: del_backref, -panic: kid popen errno read, panic: magic_killbackrefs, Parentheses missing -around "%s" list, Possible Y2K bug: %s, pragma "attrs" is deprecated, use -"sub NAME : ATTRS" instead, Premature end of script headers, Repeat count -in pack overflows, Repeat count in unpack overflows, realloc() of freed -memory ignored, Reference is already weak, setpgrp can't take arguments, -Strange *+?{} on zero-length expression, switching effective %s is not -implemented, This Perl can't reset CRTL environ elements (%s), This Perl -can't set CRTL environ elements (%s=%s), Too late to run %s block, Unknown -open() mode '%s', Unknown process %x sent message to prime_env_iter: %s, -Unrecognized escape \\%c passed through, Unterminated attribute parameter -in attribute list, Unterminated attribute list, Unterminated attribute -parameter in subroutine attribute list, Unterminated subroutine attribute -list, Value of CLI symbol "%s" too long, Version number must be a constant -number +=item The NO_OUTPUT Keyword -=item New tests +=item The CODE: Keyword -=item Incompatible Changes +=item The INIT: Keyword -=over +=item The NO_INIT Keyword -=item Perl Source Incompatibilities +=item Initializing Function Parameters -CHECK is a new keyword, Treatment of list slices of undef has changed +=item Default Parameter Values -=item Format of $English::PERL_VERSION is different +=item The PREINIT: Keyword -Literals of the form C<1.2.3> parse differently, Possibly changed -pseudo-random number generator, Hashing function for hash keys has changed, -C<undef> fails on read only values, Close-on-exec bit may be set on pipe -and socket handles, Writing C<"$$1"> to mean C<"${$}1"> is unsupported, -delete(), values() and C<\(%h)> operate on aliases to values, not copies, -vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS, Text of some diagnostic -output has changed, C<%@> has been removed, Parenthesized not() behaves -like a list operator, Semantics of bareword prototype C<(*)> have changed +=item The SCOPE: Keyword -=item Semantics of bit operators may have changed on 64-bit platforms +=item The INPUT: Keyword -=item More builtins taint their results +=item The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords -=item C Source Incompatibilities +=item Variable-length Parameter Lists -C<PERL_POLLUTE>, C<PERL_IMPLICIT_CONTEXT>, C<PERL_POLLUTE_MALLOC> +=item The C_ARGS: Keyword -=item Compatible C Source API Changes +=item The PPCODE: Keyword -C<PATCHLEVEL> is now C<PERL_VERSION> +=item Returning Undef And Empty Lists -=item Binary Incompatibilities +=item The REQUIRE: Keyword -=back +=item The CLEANUP: Keyword -=item Known Problems +=item The POST_CALL: Keyword -=over +=item The BOOT: Keyword -=item Thread test failures +=item The VERSIONCHECK: Keyword -=item EBCDIC platforms not supported +=item The PROTOTYPES: Keyword -=item In 64-bit HP-UX the lib/io_multihomed test may hang +=item The PROTOTYPE: Keyword -=item NEXTSTEP 3.3 POSIX test failure +=item The ALIAS: Keyword -=item Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with -gcc +=item The INTERFACE: Keyword -=item UNICOS/mk CC failures during Configure run +=item The INTERFACE_MACRO: Keyword -=item Arrow operator and arrays +=item The INCLUDE: Keyword -=item Windows 2000 +=item The CASE: Keyword -=item Experimental features +=item The & Unary Operator -Threads, Unicode, 64-bit support, Lvalue subroutines, Weak references, The -pseudo-hash data type, The Compiler suite, Internal implementation of file -globbing, The DB module, The regular expression constructs C<(?{ code })> -and C<(??{ code })> +=item Inserting POD, Comments and C Preprocessor Directives -=back +=item Using XS With C++ -=item Obsolete Diagnostics +=item Interface Strategy -Character class syntax [: :] is reserved for future extensions, Ill-formed -logical name |%s| in prime_env_iter, Probable precedence problem on %s, -regexp too big, Use of "$$<digit>" to mean "${$}<digit>" is deprecated +=item Perl Objects And C Structures -=item Reporting Bugs +=item The Typemap -=item SEE ALSO +=back -=item HISTORY +=item EXAMPLES + +=item XS VERSION + +=item AUTHOR =back -=head2 perldata - Perl data types +=head2 perlclib - Internal replacements for standard C library functions -=over +=over 4 =item DESCRIPTION -=over +=over 4 -=item Variable names +=item Conventions -=item Context +C<t>, C<p>, C<n>, C<s> -=item Scalar values +=item File Operations -=item Scalar value constructors +=item File Input and Output -=item List value constructors +=item File Positioning -=item Slices +=item Memory Management and String Handling -=item Typeglobs and Filehandles +=item Character Class Tests + +=item F<stdlib.h> functions + +=item Miscellaneous functions =back @@ -1547,2128 +3524,2362 @@ regexp too big, Use of "$$<digit>" to mean "${$}<digit>" is deprecated =back -=head2 perlsyn - Perl syntax +=head2 perlguts - Introduction to the Perl API -=over +=over 4 =item DESCRIPTION -=over +=item Variables -=item Declarations +=over 4 -=item Simple statements +=item Datatypes -=item Compound statements +=item What is an "IV"? -=item Loop Control +=item Working with SVs -=item For Loops +=item Offsets -=item Foreach Loops +=item What's Really Stored in an SV? -=item Basic BLOCKs and Switch Statements +=item Working with AVs -=item Goto +=item Working with HVs -=item PODs: Embedded Documentation +=item Hash API Extensions -=item Plain Old Comments (Not!) +=item References -=back +=item Blessed References and Class Objects + +=item Creating New Variables + +=item Reference Counts and Mortality + +=item Stashes and Globs + +=item Double-Typed SVs + +=item Magic Variables + +=item Assigning Magic + +=item Magic Virtual Tables + +=item Finding Magic + +=item Understanding the Magic of Tied Hashes and Arrays + +=item Localizing changes + +C<SAVEINT(int i)>, C<SAVEIV(IV i)>, C<SAVEI32(I32 i)>, C<SAVELONG(long i)>, +C<SAVESPTR(s)>, C<SAVEPPTR(p)>, C<SAVEFREESV(SV *sv)>, C<SAVEMORTALIZESV(SV +*sv)>, C<SAVEFREEOP(OP *op)>, C<SAVEFREEPV(p)>, C<SAVECLEARSV(SV *sv)>, +C<SAVEDELETE(HV *hv, char *key, I32 length)>, +C<SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)>, +C<SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)>, C<SAVESTACK_POS()>, C<SV* +save_scalar(GV *gv)>, C<AV* save_ary(GV *gv)>, C<HV* save_hash(GV *gv)>, +C<void save_item(SV *item)>, C<void save_list(SV **sarg, I32 maxsarg)>, +C<SV* save_svref(SV **sptr)>, C<void save_aptr(AV **aptr)>, C<void +save_hptr(HV **hptr)> =back -=head2 perlop - Perl operators and precedence +=item Subroutines -=over +=over 4 -=item SYNOPSIS +=item XSUBs and the Argument Stack -=item DESCRIPTION +=item Calling Perl Routines from within C Programs -=over +=item Memory Allocation -=item Terms and List Operators (Leftward) +=item PerlIO -=item The Arrow Operator +=item Putting a C value on Perl stack -=item Auto-increment and Auto-decrement +=item Scratchpads -=item Exponentiation +=item Scratchpads and recursion -=item Symbolic Unary Operators +=back -=item Binding Operators +=item Compiled code -=item Multiplicative Operators +=over 4 -=item Additive Operators +=item Code tree -=item Shift Operators +=item Examining the tree -=item Named Unary Operators +=item Compile pass 1: check routines -=item Relational Operators +=item Compile pass 1a: constant folding -=item Equality Operators +=item Compile pass 2: context propagation -=item Bitwise And +=item Compile pass 3: peephole optimization -=item Bitwise Or and Exclusive Or +=back -=item C-style Logical And +=item Examining internal data structures with the C<dump> functions -=item C-style Logical Or +=item How multiple interpreters and concurrency are supported -=item Range Operators +=over 4 -=item Conditional Operator +=item Background and PERL_IMPLICIT_CONTEXT -=item Assignment Operators +=item So what happened to dTHR? -=item Comma Operator +=item How do I use all this in extensions? -=item List Operators (Rightward) +=item Should I do anything special if I call perl from multiple threads? -=item Logical Not +=item Future Plans and PERL_IMPLICIT_SYS -=item Logical And +=back -=item Logical or and Exclusive Or +=item Internal Functions -=item C Operators Missing From Perl +A, p, d, s, n, r, f, M, o, j, x -unary &, unary *, (TYPE) +=over 4 -=item Quote and Quote-like Operators +=item Formatted Printing of IVs, UVs, and NVs -=item Regexp Quote-Like Operators +=item Pointer-To-Integer and Integer-To-Pointer -?PATTERN?, m/PATTERN/cgimosx, /PATTERN/cgimosx, q/STRING/, C<'STRING'>, -qq/STRING/, "STRING", qr/STRING/imosx, qx/STRING/, `STRING`, qw/STRING/, -s/PATTERN/REPLACEMENT/egimosx, tr/SEARCHLIST/REPLACEMENTLIST/cdsUC, -y/SEARCHLIST/REPLACEMENTLIST/cdsUC +=item Source Documentation -=item Gory details of parsing quoted constructs +=back -Finding the end, Removal of backslashes before delimiters, Interpolation, -C<<<'EOF'>, C<m''>, C<s'''>, C<tr///>, C<y///>, C<''>, C<q//>, C<"">, -C<``>, C<qq//>, C<qx//>, C<< <file*glob> >>, C<?RE?>, C</RE/>, C<m/RE/>, -C<s/RE/foo/>,, Interpolation of regular expressions, Optimization of -regular expressions +=item Unicode Support -=item I/O Operators +=over 4 -=item Constant Folding +=item What B<is> Unicode, anyway? -=item Bitwise String Operators +=item How can I recognise a UTF8 string? -=item Integer Arithmetic +=item How does UTF8 represent Unicode characters? -=item Floating-point Arithmetic +=item How does Perl store UTF8 strings? -=item Bigger Numbers +=item How do I convert a string to UTF8? + +=item Is there anything else I need to know? =back +=item AUTHORS + +=item SEE ALSO + =back -=head2 perlre - Perl regular expressions +=head2 perlcall - Perl calling conventions from C -=over +=over 4 =item DESCRIPTION -i, m, s, x +An Error Handler, An Event Driven Program -=over +=item THE CALL_ FUNCTIONS -=item Regular Expressions +call_sv, call_pv, call_method, call_argv -cntrl, graph, print, punct, xdigit +=item FLAG VALUES -=item Extended Patterns +=over 4 -C<(?#text)>, C<(?imsx-imsx)>, C<(?:pattern)>, C<(?imsx-imsx:pattern)>, -C<(?=pattern)>, C<(?!pattern)>, C<(?<=pattern)>, C<(?<!pattern)>, C<(?{ -code })>, C<(??{ code })>, C<< (?>pattern) >>, -C<(?(condition)yes-pattern|no-pattern)>, C<(?(condition)yes-pattern)> +=item G_VOID -=item Backtracking +=item G_SCALAR -=item Version 8 Regular Expressions +=item G_ARRAY -=item Warning on \1 vs $1 +=item G_DISCARD -=item Repeated patterns matching zero-length substring +=item G_NOARGS -=item Combining pieces together +=item G_EVAL -C<ST>, C<S|T>, C<S{REPEAT_COUNT}>, C<S{min,max}>, C<S{min,max}?>, C<S?>, -C<S*>, C<S+>, C<S??>, C<S*?>, C<S+?>, C<< (?>S) >>, C<(?=S)>, C<(?<=S)>, -C<(?!S)>, C<(?<!S)>, C<(??{ EXPR })>, -C<(?(condition)yes-pattern|no-pattern)> +=item G_KEEPERR -=item Creating custom RE engines +=item Determining the Context =back -=item BUGS +=item KNOWN PROBLEMS -=item SEE ALSO +=item EXAMPLES -=back +=over 4 -=head2 perlrun - how to execute the Perl interpreter +=item No Parameters, Nothing returned -=over +=item Passing Parameters -=item SYNOPSIS +=item Returning a Scalar -=item DESCRIPTION +=item Returning a list of values -=over +=item Returning a list in a scalar context -=item #! and quoting on non-Unix systems +=item Returning Data from Perl via the parameter list -OS/2, MS-DOS, Win95/NT, Macintosh, VMS +=item Using G_EVAL -=item Location of Perl +=item Using G_KEEPERR -=item Command Switches +=item Using call_sv -B<-0>[I<digits>], B<-a>, B<-C>, B<-c>, B<-d>, B<-d:>I<foo>, -B<-D>I<letters>, B<-D>I<number>, B<-e> I<commandline>, B<-F>I<pattern>, -B<-h>, B<-i>[I<extension>], B<-I>I<directory>, B<-l>[I<octnum>], -B<-m>[B<->]I<module>, B<-M>[B<->]I<module>, B<-M>[B<->]I<'module ...'>, -B<-[mM]>[B<->]I<module=arg[,arg]...>, B<-n>, B<-p>, B<-P>, B<-s>, B<-S>, -B<-T>, B<-u>, B<-U>, B<-v>, B<-V>, B<-V:>I<name>, B<-w>, B<-W>, B<-X>, -B<-x> I<directory> +=item Using call_argv + +=item Using call_method + +=item Using GIMME_V + +=item Using Perl to dispose of temporaries + +=item Strategies for storing Callback Context Information + +1. Ignore the problem - Allow only 1 callback, 2. Create a sequence of +callbacks - hard wired limit, 3. Use a parameter to map to the Perl +callback + +=item Alternate Stack Manipulation + +=item Creating and calling an anonymous subroutine in C =back -=item ENVIRONMENT +=item SEE ALSO -HOME, LOGDIR, PATH, PERL5LIB, PERL5OPT, PERLLIB, PERL5DB, PERL5SHELL -(specific to the Win32 port), PERL_DEBUG_MSTATS, PERL_DESTRUCT_LEVEL +=item AUTHOR + +=item DATE =back -=head2 perlfunc - Perl builtin functions +=head2 perlutil - utilities packaged with the Perl distribution -=over +=over 4 =item DESCRIPTION -=over +=over 4 -=item Perl Functions by Category +=item DOCUMENTATION -Functions for SCALARs or strings, Regular expressions and pattern matching, -Numeric functions, Functions for real @ARRAYs, Functions for list data, -Functions for real %HASHes, Input and output functions, Functions for fixed -length data or records, Functions for filehandles, files, or directories, -Keywords related to the control flow of your perl program, Keywords related -to scoping, Miscellaneous functions, Functions for processes and process -groups, Keywords related to perl modules, Keywords related to classes and -object-orientedness, Low-level socket functions, System V interprocess -communication functions, Fetching user and group info, Fetching network -info, Time-related functions, Functions new in perl5, Functions obsoleted -in perl5 +L<perldoc|perldoc>, L<pod2man|pod2man> and L<pod2text|pod2text>, +L<pod2html|pod2html> and L<pod2latex|pod2latex>, L<pod2usage|pod2usage>, +L<podselect|podselect>, L<podchecker|podchecker>, L<splain|splain>, +L<roffitall|roffitall> -=item Portability +=item CONVERTORS -=item Alphabetical Listing of Perl Functions +L<a2p|a2p>, L<s2p|s2p>, L<find2perl|find2perl> -I<-X> FILEHANDLE, I<-X> EXPR, I<-X>, abs VALUE, abs, accept -NEWSOCKET,GENERICSOCKET, alarm SECONDS, alarm, atan2 Y,X, bind SOCKET,NAME, -binmode FILEHANDLE, DISCIPLINE, binmode FILEHANDLE, bless REF,CLASSNAME, -bless REF, caller EXPR, caller, chdir EXPR, chmod LIST, chomp VARIABLE, -chomp LIST, chomp, chop VARIABLE, chop LIST, chop, chown LIST, chr NUMBER, -chr, chroot FILENAME, chroot, close FILEHANDLE, close, closedir DIRHANDLE, -connect SOCKET,NAME, continue BLOCK, cos EXPR, crypt PLAINTEXT,SALT, -dbmclose HASH, dbmopen HASH,DBNAME,MASK, defined EXPR, defined, delete -EXPR, die LIST, do BLOCK, do SUBROUTINE(LIST), do EXPR, dump LABEL, dump, -each HASH, eof FILEHANDLE, eof (), eof, eval EXPR, eval BLOCK, exec LIST, -exec PROGRAM LIST, exists EXPR, exit EXPR, exp EXPR, exp, fcntl -FILEHANDLE,FUNCTION,SCALAR, fileno FILEHANDLE, flock FILEHANDLE,OPERATION, -fork, format, formline PICTURE,LIST, getc FILEHANDLE, getc, getlogin, -getpeername SOCKET, getpgrp PID, getppid, getpriority WHICH,WHO, getpwnam -NAME, getgrnam NAME, gethostbyname NAME, getnetbyname NAME, getprotobyname -NAME, getpwuid UID, getgrgid GID, getservbyname NAME,PROTO, gethostbyaddr -ADDR,ADDRTYPE, getnetbyaddr ADDR,ADDRTYPE, getprotobynumber NUMBER, -getservbyport PORT,PROTO, getpwent, getgrent, gethostent, getnetent, -getprotoent, getservent, setpwent, setgrent, sethostent STAYOPEN, setnetent -STAYOPEN, setprotoent STAYOPEN, setservent STAYOPEN, endpwent, endgrent, -endhostent, endnetent, endprotoent, endservent, getsockname SOCKET, -getsockopt SOCKET,LEVEL,OPTNAME, glob EXPR, glob, gmtime EXPR, goto LABEL, -goto EXPR, goto &NAME, grep BLOCK LIST, grep EXPR,LIST, hex EXPR, hex, -import, index STR,SUBSTR,POSITION, index STR,SUBSTR, int EXPR, int, ioctl -FILEHANDLE,FUNCTION,SCALAR, join EXPR,LIST, keys HASH, kill SIGNAL, LIST, -last LABEL, last, lc EXPR, lc, lcfirst EXPR, lcfirst, length EXPR, length, -link OLDFILE,NEWFILE, listen SOCKET,QUEUESIZE, local EXPR, localtime EXPR, -lock, log EXPR, log, lstat FILEHANDLE, lstat EXPR, lstat, m//, map BLOCK -LIST, map EXPR,LIST, mkdir FILENAME,MASK, mkdir FILENAME, msgctl -ID,CMD,ARG, msgget KEY,FLAGS, msgrcv ID,VAR,SIZE,TYPE,FLAGS, msgsnd -ID,MSG,FLAGS, my EXPR, my EXPR : ATTRIBUTES, next LABEL, next, no Module -LIST, oct EXPR, oct, open FILEHANDLE,MODE,LIST, open FILEHANDLE,EXPR, open -FILEHANDLE, opendir DIRHANDLE,EXPR, ord EXPR, ord, our EXPR, pack -TEMPLATE,LIST, package, package NAMESPACE, pipe READHANDLE,WRITEHANDLE, pop -ARRAY, pop, pos SCALAR, pos, print FILEHANDLE LIST, print LIST, print, -printf FILEHANDLE FORMAT, LIST, printf FORMAT, LIST, prototype FUNCTION, -push ARRAY,LIST, q/STRING/, qq/STRING/, qr/STRING/, qx/STRING/, qw/STRING/, -quotemeta EXPR, quotemeta, rand EXPR, rand, read -FILEHANDLE,SCALAR,LENGTH,OFFSET, read FILEHANDLE,SCALAR,LENGTH, readdir -DIRHANDLE, readline EXPR, readlink EXPR, readlink, readpipe EXPR, recv -SOCKET,SCALAR,LENGTH,FLAGS, redo LABEL, redo, ref EXPR, ref, rename -OLDNAME,NEWNAME, require VERSION, require EXPR, require, reset EXPR, reset, -return EXPR, return, reverse LIST, rewinddir DIRHANDLE, rindex -STR,SUBSTR,POSITION, rindex STR,SUBSTR, rmdir FILENAME, rmdir, s///, scalar -EXPR, seek FILEHANDLE,POSITION,WHENCE, seekdir DIRHANDLE,POS, select -FILEHANDLE, select, select RBITS,WBITS,EBITS,TIMEOUT, semctl -ID,SEMNUM,CMD,ARG, semget KEY,NSEMS,FLAGS, semop KEY,OPSTRING, send -SOCKET,MSG,FLAGS,TO, send SOCKET,MSG,FLAGS, setpgrp PID,PGRP, setpriority -WHICH,WHO,PRIORITY, setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL, shift ARRAY, -shift, shmctl ID,CMD,ARG, shmget KEY,SIZE,FLAGS, shmread ID,VAR,POS,SIZE, -shmwrite ID,STRING,POS,SIZE, shutdown SOCKET,HOW, sin EXPR, sin, sleep -EXPR, sleep, socket SOCKET,DOMAIN,TYPE,PROTOCOL, socketpair -SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL, sort SUBNAME LIST, sort BLOCK LIST, -sort LIST, splice ARRAY,OFFSET,LENGTH,LIST, splice ARRAY,OFFSET,LENGTH, -splice ARRAY,OFFSET, splice ARRAY, split /PATTERN/,EXPR,LIMIT, split -/PATTERN/,EXPR, split /PATTERN/, split, sprintf FORMAT, LIST, sqrt EXPR, -sqrt, srand EXPR, srand, stat FILEHANDLE, stat EXPR, stat, study SCALAR, -study, sub BLOCK, sub NAME, sub NAME BLOCK, substr -EXPR,OFFSET,LENGTH,REPLACEMENT, substr EXPR,OFFSET,LENGTH, substr -EXPR,OFFSET, symlink OLDFILE,NEWFILE, syscall LIST, sysopen -FILEHANDLE,FILENAME,MODE, sysopen FILEHANDLE,FILENAME,MODE,PERMS, sysread -FILEHANDLE,SCALAR,LENGTH,OFFSET, sysread FILEHANDLE,SCALAR,LENGTH, sysseek -FILEHANDLE,POSITION,WHENCE, system LIST, system PROGRAM LIST, syswrite -FILEHANDLE,SCALAR,LENGTH,OFFSET, syswrite FILEHANDLE,SCALAR,LENGTH, -syswrite FILEHANDLE,SCALAR, tell FILEHANDLE, tell, telldir DIRHANDLE, tie -VARIABLE,CLASSNAME,LIST, tied VARIABLE, time, times, tr///, truncate -FILEHANDLE,LENGTH, truncate EXPR,LENGTH, uc EXPR, uc, ucfirst EXPR, -ucfirst, umask EXPR, umask, undef EXPR, undef, unlink LIST, unlink, unpack -TEMPLATE,EXPR, untie VARIABLE, unshift ARRAY,LIST, use Module VERSION LIST, -use Module VERSION, use Module LIST, use Module, use VERSION, utime LIST, -values HASH, vec EXPR,OFFSET,BITS, wait, waitpid PID,FLAGS, wantarray, warn -LIST, write FILEHANDLE, write EXPR, write, y/// +=item Development + +L<perlbug|perlbug>, L<h2ph|h2ph>, L<c2ph|c2ph> and L<pstruct|pstruct>, +L<h2xs|h2xs>, L<dprofpp|dprofpp>, L<perlcc|perlcc> + +=item SEE ALSO =back =back -=head2 perlvar - Perl predefined variables +=head2 perlfilter - Source Filters -=over +=over 4 =item DESCRIPTION -=over +=item CONCEPTS -=item Predefined Names +=item USING FILTERS -$ARG, $_, $<I<digits>>, $MATCH, $&, $PREMATCH, $`, $POSTMATCH, $', -$LAST_PAREN_MATCH, $+, @+, $MULTILINE_MATCHING, $*, input_line_number -HANDLE EXPR, $INPUT_LINE_NUMBER, $NR, $, input_record_separator HANDLE -EXPR, $INPUT_RECORD_SEPARATOR, $RS, $/, autoflush HANDLE EXPR, -$OUTPUT_AUTOFLUSH, $|, output_field_separator HANDLE EXPR, -$OUTPUT_FIELD_SEPARATOR, $OFS, $,, output_record_separator HANDLE EXPR, -$OUTPUT_RECORD_SEPARATOR, $ORS, $\, $LIST_SEPARATOR, $", -$SUBSCRIPT_SEPARATOR, $SUBSEP, $;, $OFMT, $#, format_page_number HANDLE -EXPR, $FORMAT_PAGE_NUMBER, $%, format_lines_per_page HANDLE EXPR, -$FORMAT_LINES_PER_PAGE, $=, format_lines_left HANDLE EXPR, -$FORMAT_LINES_LEFT, $-, @-, C<$`> is the same as C<substr($var, 0, $-[0]>), -C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0]>), C<$'> is the -same as C<substr($var, $+[0]>), C<$1> is the same as C<substr($var, $-[1], -$+[1] - $-[1])>, C<$2> is the same as C<substr($var, $-[2], $+[2] - -$-[2])>, C<$3> is the same as C<substr $var, $-[3], $+[3] - $-[3]>), -format_name HANDLE EXPR, $FORMAT_NAME, $~, format_top_name HANDLE EXPR, -$FORMAT_TOP_NAME, $^, format_line_break_characters HANDLE EXPR, -$FORMAT_LINE_BREAK_CHARACTERS, $:, format_formfeed HANDLE EXPR, -$FORMAT_FORMFEED, $^L, $ACCUMULATOR, $^A, $CHILD_ERROR, $?, $OS_ERROR, -$ERRNO, $!, $EXTENDED_OS_ERROR, $^E, $EVAL_ERROR, $@, $PROCESS_ID, $PID, -$$, $REAL_USER_ID, $UID, $<, $EFFECTIVE_USER_ID, $EUID, $>, $REAL_GROUP_ID, -$GID, $(, $EFFECTIVE_GROUP_ID, $EGID, $), $PROGRAM_NAME, $0, $[, $], -$COMPILING, $^C, $DEBUGGING, $^D, $SYSTEM_FD_MAX, $^F, $^H, %^H, -$INPLACE_EDIT, $^I, $^M, $OSNAME, $^O, $PERLDB, $^P, 0x01, 0x02, 0x04, -0x08, 0x10, 0x20, 0x40, 0x80, 0x100, 0x200, $LAST_REGEXP_CODE_RESULT, $^R, -$EXCEPTIONS_BEING_CAUGHT, $^S, $BASETIME, $^T, $PERL_VERSION, $^V, -$WARNING, $^W, ${^WARNING_BITS}, ${^WIDE_SYSTEM_CALLS}, $EXECUTABLE_NAME, -$^X, $ARGV, @ARGV, @INC, @_, %INC, %ENV, $ENV{expr}, %SIG, $SIG{expr} +=item WRITING A SOURCE FILTER -=item Error Indicators +=item WRITING A SOURCE FILTER IN C -=item Technical Note on the Syntax of Variable Names +B<Decryption Filters> -=back +=item CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE -=item BUGS +=item WRITING A SOURCE FILTER IN PERL + +=item USING CONTEXT: THE DEBUG FILTER + +=item CONCLUSION + +=item REQUIREMENTS + +=item AUTHOR + +=item Copyrights =back -=head2 perlsub - Perl subroutines +=head2 perldbmfilter - Perl DBM Filters -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over - -=item Private Variables via my() +B<filter_store_key>, B<filter_store_value>, B<filter_fetch_key>, +B<filter_fetch_value> -=item Persistent Private Variables +=over 4 -=item Temporary Values via local() +=item The Filter -=item Lvalue subroutines +=item An Example -- the NULL termination problem. -=item Passing Symbol Table Entries (typeglobs) +=item Another Example -- Key is a C int. -=item When to Still Use local() +=back -1. You need to give a global variable a temporary value, especially $_, 2. -You need to create a local file or directory handle or a local function, 3. -You want to temporarily change just one element of an array or hash +=item SEE ALSO -=item Pass by Reference +=item AUTHOR -=item Prototypes +=back -=item Constant Functions +=head2 perlapi - autogenerated documentation for the perl public API -=item Overriding Built-in Functions +=over 4 -=item Autoloading +=item DESCRIPTION -=item Subroutine Attributes +AvFILL, av_clear, av_delete, av_exists, av_extend, av_fetch, av_fill, +av_len, av_make, av_pop, av_push, av_shift, av_store, av_undef, av_unshift, +bytes_from_utf8, bytes_to_utf8, call_argv, call_method, call_pv, call_sv, +CLASS, Copy, croak, CvSTASH, dMARK, dORIGMARK, dSP, dXSARGS, dXSI32, ENTER, +eval_pv, eval_sv, EXTEND, fbm_compile, fbm_instr, FREETMPS, get_av, get_cv, +get_hv, get_sv, GIMME, GIMME_V, GvSV, gv_fetchmeth, gv_fetchmethod, +gv_fetchmethod_autoload, gv_stashpv, gv_stashsv, G_ARRAY, G_DISCARD, +G_EVAL, G_NOARGS, G_SCALAR, G_VOID, HEf_SVKEY, HeHASH, HeKEY, HeKLEN, HePV, +HeSVKEY, HeSVKEY_force, HeSVKEY_set, HeVAL, HvNAME, hv_clear, hv_delete, +hv_delete_ent, hv_exists, hv_exists_ent, hv_fetch, hv_fetch_ent, +hv_iterinit, hv_iterkey, hv_iterkeysv, hv_iternext, hv_iternextsv, +hv_iterval, hv_magic, hv_store, hv_store_ent, hv_undef, isALNUM, isALPHA, +isDIGIT, isLOWER, isSPACE, isUPPER, is_utf8_char, is_utf8_string, items, +ix, LEAVE, looks_like_number, MARK, mg_clear, mg_copy, mg_find, mg_free, +mg_get, mg_length, mg_magical, mg_set, Move, New, newAV, Newc, newCONSTSUB, +newHV, newRV_inc, newRV_noinc, NEWSV, newSViv, newSVnv, newSVpv, newSVpvf, +newSVpvn, newSVrv, newSVsv, newSVuv, newXS, newXSproto, Newz, Nullav, +Nullch, Nullcv, Nullhv, Nullsv, ORIGMARK, perl_alloc, perl_construct, +perl_destruct, perl_free, perl_parse, perl_run, PL_modglobal, PL_na, +PL_sv_no, PL_sv_undef, PL_sv_yes, POPi, POPl, POPn, POPp, POPs, PUSHi, +PUSHMARK, PUSHn, PUSHp, PUSHs, PUSHu, PUTBACK, Renew, Renewc, require_pv, +RETVAL, Safefree, savepv, savepvn, SAVETMPS, SP, SPAGAIN, ST, strEQ, strGE, +strGT, strLE, strLT, strNE, strnEQ, strnNE, StructCopy, SvCUR, SvCUR_set, +SvEND, SvGETMAGIC, SvGROW, SvIOK, SvIOKp, SvIOK_notUV, SvIOK_off, SvIOK_on, +SvIOK_only, SvIOK_only_UV, SvIOK_UV, SvIV, SvIVX, SvLEN, SvNIOK, SvNIOKp, +SvNIOK_off, SvNOK, SvNOKp, SvNOK_off, SvNOK_on, SvNOK_only, SvNV, SvNVX, +SvOK, SvOOK, SvPOK, SvPOKp, SvPOK_off, SvPOK_on, SvPOK_only, +SvPOK_only_UTF8, SvPV, SvPVX, SvPV_force, SvPV_nolen, SvREFCNT, +SvREFCNT_dec, SvREFCNT_inc, SvROK, SvROK_off, SvROK_on, SvRV, SvSETMAGIC, +SvSetSV, SvSetSV_nosteal, SvSTASH, SvTAINT, SvTAINTED, SvTAINTED_off, +SvTAINTED_on, SvTRUE, svtype, SvTYPE, SVt_IV, SVt_NV, SVt_PV, SVt_PVAV, +SVt_PVCV, SVt_PVHV, SVt_PVMG, SvUPGRADE, SvUTF8, SvUTF8_off, SvUTF8_on, +SvUV, SvUVX, sv_2mortal, sv_bless, sv_catpv, sv_catpvf, sv_catpvf_mg, +sv_catpvn, sv_catpvn_mg, sv_catpv_mg, sv_catsv, sv_catsv_mg, sv_chop, +sv_clear, sv_cmp, sv_cmp_locale, sv_dec, sv_derived_from, sv_eq, sv_free, +sv_gets, sv_grow, sv_inc, sv_insert, sv_isa, sv_isobject, sv_len, +sv_len_utf8, sv_magic, sv_mortalcopy, sv_newmortal, sv_pvn_force, +sv_pvutf8n_force, sv_reftype, sv_replace, sv_rvweaken, sv_setiv, +sv_setiv_mg, sv_setnv, sv_setnv_mg, sv_setpv, sv_setpvf, sv_setpvf_mg, +sv_setpviv, sv_setpviv_mg, sv_setpvn, sv_setpvn_mg, sv_setpv_mg, +sv_setref_iv, sv_setref_nv, sv_setref_pv, sv_setref_pvn, sv_setsv, +sv_setsv_mg, sv_setuv, sv_setuv_mg, sv_true, sv_unmagic, sv_unref, +sv_upgrade, sv_usepvn, sv_usepvn_mg, sv_utf8_downgrade, sv_utf8_encode, +sv_utf8_upgrade, sv_vcatpvfn, sv_vsetpvfn, THIS, toLOWER, toUPPER, +utf8_distance, utf8_hop, utf8_length, utf8_to_bytes, utf8_to_uv, +utf8_to_uv_simple, uv_to_utf8, warn, XPUSHi, XPUSHn, XPUSHp, XPUSHs, +XPUSHu, XS, XSRETURN, XSRETURN_EMPTY, XSRETURN_IV, XSRETURN_NO, +XSRETURN_NV, XSRETURN_PV, XSRETURN_UNDEF, XSRETURN_YES, XST_mIV, XST_mNO, +XST_mNV, XST_mPV, XST_mUNDEF, XST_mYES, XS_VERSION, XS_VERSION_BOOTCHECK, +Zero -=back +=item AUTHORS =item SEE ALSO =back -=head2 perlmod - Perl modules (packages and symbol tables) +=head2 perlintern - autogenerated documentation of purely B<internal> + Perl functions -=over +=over 4 =item DESCRIPTION -=over +is_gv_magical, LVRET, PL_DBsingle, PL_DBsub, PL_DBtrace, PL_dowarn, +PL_last_in_gv, PL_ofs_sv, PL_rs -=item Packages +=item AUTHORS -=item Symbol Tables +=item SEE ALSO -=item Package Constructors and Destructors +=back -=item Perl Classes +=head2 perlapio - perl's IO abstraction interface. -=item Perl Modules +=over 4 -=back +=item SYNOPSIS -=item SEE ALSO +=item DESCRIPTION + +B<PerlIO *>, B<PerlIO_stdin()>, B<PerlIO_stdout()>, B<PerlIO_stderr()>, +B<PerlIO_open(path, mode)>, B<PerlIO_fdopen(fd,mode)>, +B<PerlIO_printf(f,fmt,...)>, B<PerlIO_vprintf(f,fmt,a)>, +B<PerlIO_stdoutf(fmt,...)>, B<PerlIO_read(f,buf,count)>, +B<PerlIO_write(f,buf,count)>, B<PerlIO_close(f)>, B<PerlIO_puts(f,s)>, +B<PerlIO_putc(f,c)>, B<PerlIO_ungetc(f,c)>, B<PerlIO_getc(f)>, +B<PerlIO_eof(f)>, B<PerlIO_error(f)>, B<PerlIO_fileno(f)>, +B<PerlIO_clearerr(f)>, B<PerlIO_flush(f)>, B<PerlIO_tell(f)>, +B<PerlIO_seek(f,o,w)>, B<PerlIO_getpos(f,p)>, B<PerlIO_setpos(f,p)>, +B<PerlIO_rewind(f)>, B<PerlIO_tmpfile()> + +=over 4 + +=item Co-existence with stdio + +B<PerlIO_importFILE(f,flags)>, B<PerlIO_exportFILE(f,flags)>, +B<PerlIO_findFILE(f)>, B<PerlIO_releaseFILE(p,f)>, B<PerlIO_setlinebuf(f)>, +B<PerlIO_has_cntptr(f)>, B<PerlIO_get_ptr(f)>, B<PerlIO_get_cnt(f)>, +B<PerlIO_canset_cnt(f)>, B<PerlIO_fast_gets(f)>, +B<PerlIO_set_ptrcnt(f,p,c)>, B<PerlIO_set_cnt(f,c)>, B<PerlIO_has_base(f)>, +B<PerlIO_get_base(f)>, B<PerlIO_get_bufsiz(f)> =back -=head2 perlmodlib - constructing new Perl modules and finding existing ones +=back -=over +=head2 perltodo - Perl TO-DO List -=item DESCRIPTION +=over 4 -=item THE PERL MODULE LIBRARY +=item DESCRIPTION -=over +=item Infrastructure -=item Pragmatic Modules +=over 4 -attributes, attrs, autouse, base, blib, caller, charnames, constant, -diagnostics, fields, filetest, integer, less, lib, locale, ops, overload, -re, sigtrap, strict, subs, utf8, vars, warnings +=item Mailing list archives -=item Standard Modules +=item Bug tracking system -AnyDBM_File, AutoLoader, AutoSplit, B, B::Asmdata, B::Assembler, B::Bblock, -B::Bytecode, B::C, B::CC, B::Debug, B::Deparse, B::Disassembler, B::Lint, -B::Showlex, B::Stackobj, B::Terse, B::Xref, Benchmark, ByteLoader, CGI, -CGI::Apache, CGI::Carp, CGI::Cookie, CGI::Fast, CGI::Pretty, CGI::Push, -CGI::Switch, CPAN, CPAN::FirstTime, CPAN::Nox, Carp, Carp::Heavy, -Class::Struct, Config, Cwd, DB, DB_File, Data::Dumper, Devel::DProf, -Devel::Peek, Devel::SelfStubber, DirHandle, Dumpvalue, DynaLoader, English, -Env, Errno, Exporter, Exporter::Heavy, ExtUtils::Command, ExtUtils::Embed, -ExtUtils::Install, ExtUtils::Installed, ExtUtils::Liblist, -ExtUtils::MM_Cygwin, ExtUtils::MM_OS2, ExtUtils::MM_Unix, ExtUtils::MM_VMS, -ExtUtils::MM_Win32, ExtUtils::MakeMaker, ExtUtils::Manifest, -ExtUtils::Mkbootstrap, ExtUtils::Mksymlists, ExtUtils::Packlist, -ExtUtils::testlib, Fatal, Fcntl, File::Basename, File::CheckTree, -File::Compare, File::Copy, File::DosGlob, File::Find, File::Glob, -File::Path, File::Spec, File::Spec::Functions, File::Spec::Mac, -File::Spec::OS2, File::Spec::Unix, File::Spec::VMS, File::Spec::Win32, -File::stat, FileCache, FileHandle, FindBin, GDBM_File, Getopt::Long, -Getopt::Std, I18N::Collate, IO, IO::Dir, IO::File, IO::Handle, IO::Pipe, -IO::Poll, IO::Seekable, IO::Select, IO::Socket, IO::Socket::INET, -IO::Socket::UNIX, IPC::Msg, IPC::Open2, IPC::Open3, IPC::Semaphore, -IPC::SysV, Math::BigFloat, Math::BigInt, Math::Complex, Math::Trig, -Net::Ping, Net::hostent, Net::netent, Net::protoent, Net::servent, O, -Opcode, POSIX, Pod::Checker, Pod::Html, Pod::InputObjects, Pod::Man, -Pod::Parser, Pod::Select, Pod::Text, Pod::Text::Color, Pod::Usage, -SDBM_File, Safe, Search::Dict, SelectSaver, SelfLoader, Shell, Socket, -Symbol, Sys::Hostname, Sys::Syslog, Term::Cap, Term::Complete, -Term::ReadLine, Test, Test::Harness, Text::Abbrev, Text::ParseWords, -Text::Soundex, Text::Wrap, Tie::Array, Tie::Handle, Tie::Hash, -Tie::RefHash, Tie::Scalar, Tie::SubstrHash, Time::Local, Time::gmtime, -Time::localtime, Time::tm, UNIVERSAL, User::grent, User::pwent +=item Regression Tests -=item Extension Modules +Coverage, Regression, __DIE__, suidperl, The 25% slowdown from perl4 to +perl5 =back -=item CPAN - -Language Extensions and Documentation Tools, Development Support, Operating -System Interfaces, Networking, Device Control (modems) and InterProcess -Communication, Data Types and Data Type Utilities, Database Interfaces, -User Interfaces, Interfaces to / Emulations of Other Programming Languages, -File Names, File Systems and File Locking (see also File Handles), String -Processing, Language Text Processing, Parsing, and Searching, Option, -Argument, Parameter, and Configuration File Processing, -Internationalization and Locale, Authentication, Security, and Encryption, -World Wide Web, HTML, HTTP, CGI, MIME, Server and Daemon Utilities, -Archiving and Compression, Images, Pixmap and Bitmap Manipulation, Drawing, -and Graphing, Mail and Usenet News, Control Flow Utilities (callbacks and -exceptions etc), File Handle and Input/Output Stream Utilities, -Miscellaneous Modules, Africa, Asia, Australasia, Central America, Europe, -North America, South America +=item Configure -=item Modules: Creation, Use, and Abuse +=over 4 -=over +=item Install HTML -=item Guidelines for Module Creation +=back -Do similar modules already exist in some form?, Try to design the new -module to be easy to extend and reuse, Some simple style guidelines, Select -what to export, Select a name for the module, Have you got it right?, -README and other Additional Files, A description of the -module/package/extension etc, A copyright notice - see below, Prerequisites -- what else you may need to have, How to build it - possible changes to -Makefile.PL etc, How to install it, Recent changes in this release, -especially incompatibilities, Changes / enhancements you plan to make in -the future, Adding a Copyright Notice, Give the module a -version/issue/release number, How to release and distribute a module, Take -care when changing a released module +=item Perl Language -=item Guidelines for Converting Perl 4 Library Scripts into Modules +=over 4 -There is no requirement to convert anything, Consider the implications, -Make the most of the opportunity, The pl2pm utility will get you started, -Adds the standard Module prologue lines, Converts package specifiers from ' -to ::, Converts die(...) to croak(...), Several other minor changes +=item 64-bit Perl -=item Guidelines for Reusing Application Code +=item Prototypes -Complete applications rarely belong in the Perl Module Library, Many -applications contain some Perl code that could be reused, Break-out the -reusable code into one or more separate module files, Take the opportunity -to reconsider and redesign the interfaces, In some cases the 'application' -can then be reduced to a small +Named prototypes, Indirect objects, Method calls, Context, Scoped subs =back -=item NOTE +=item Perl Internals -=back +=over 4 -=head2 perlmodinstall - Installing CPAN Modules +=item magic_setisa -=over +=item Garbage Collection -=item DESCRIPTION +=item Reliable signals -=over +Alternate runops() for signal despatch, Figure out how to die() in delayed +sighandler, Add tests for Thread::Signal, Automatic tests against CPAN -=item PREAMBLE +=item Interpolated regex performance bugs -B<DECOMPRESS> the file, B<UNPACK> the file into a directory, B<BUILD> the -module (sometimes unnecessary), B<INSTALL> the module +=item Memory leaks from failed eval/regcomp -=back +=item Make XS easier to use -=item HEY +=item Make embedded Perl easier to use -=item AUTHOR +=item Namespace cleanup -=item COPYRIGHT +=item MULTIPLICITY + +=item MacPerl =back -=head2 perlfork - Perl's fork() emulation +=item Documentation -=over +=over 4 -=item SYNOPSIS +=item A clear division into tutorial and reference -=item DESCRIPTION +=item Remove the artificial distinction between operators and functions -=over +=item More tutorials -=item Behavior of other Perl features in forked pseudo-processes +Regular expressions, I/O, pack/unpack, Debugging -$$ or $PROCESS_ID, %ENV, chdir() and all other builtins that accept -filenames, wait() and waitpid(), kill(), exec(), exit(), Open handles to -files, directories and network sockets +=item Include a search tool -=item Resource limits +=item Include a locate tool -=item Killing the parent process +=item Separate function manpages by default -=item Lifetime of the parent process and pseudo-processes +=item Users can't find the manpages -=item CAVEATS AND LIMITATIONS +=item Install ALL Documentation -BEGIN blocks, Open filehandles, Forking pipe open() not yet implemented, -Global state maintained by XSUBs, Interpreter embedded in larger -application, Thread-safety of extensions - -=back +=item Outstanding issues to be documented -=item BUGS +=item Adapt www.linuxhq.com for Perl -=item AUTHOR +=item Replace man with a perl program -=item SEE ALSO +=item Unicode tutorial =back -=head2 perlform - Perl formats +=item Modules -=over +=over 4 -=item DESCRIPTION +=item Update the POSIX extension to conform with the POSIX 1003.1 Edition 2 -=over +=item Module versions -=item Format Variables +=item New modules -=back +=item Profiler -=item NOTES +=item Tie Modules -=over +VecArray, SubstrArray, VirtualArray, ShiftSplice -=item Footers +=item Procedural options -=item Accessing Formatting Internals +=item RPC -=back +=item y2k localtime/gmtime -=item WARNINGS +=item Export File::Find variables -=back +=item Ioctl -=head2 perllocale - Perl locale handling (internationalization and -localization) +=item Debugger attach/detach -=over +=item Regular Expression debugger -=item DESCRIPTION +=item Alternative RE Syntax -=item PREPARING TO USE LOCALES +=item Bundled modules -=item USING LOCALES +=item Expect -=over +=item GUI::Native -=item The use locale pragma +=item Update semibroken auxiliary tools; h2ph, a2p, etc. -=item The setlocale function +=item pod2html -=item Finding locales +=item Podchecker -=item LOCALE PROBLEMS +=back -=item Temporarily fixing locale problems +=item Tom's Wishes -=item Permanently fixing locale problems +=over 4 -=item Permanently fixing your system's locale configuration +=item Webperl -=item Fixing system locale configuration +=item Mobile agents -=item The localeconv function +=item POSIX on non-POSIX + +=item Portable installations =back -=item LOCALE CATEGORIES +=item Win32 Stuff -=over +=over 4 -=item Category LC_COLLATE: Collation +=item Rename new headers to be consistent with the rest -=item Category LC_CTYPE: Character Types +=item Sort out the spawnvp() mess -=item Category LC_NUMERIC: Numeric Formatting +=item Work out DLL versioning -=item Category LC_MONETARY: Formatting of monetary amounts +=item Style-check -=item LC_TIME +=back -=item Other categories +=item Would be nice to have -=back +C<pack "(stuff)*">, Contiguous bitfields in pack/unpack, lexperl, Bundled +perl preprocessor, Use posix calls internally where possible, format +BOTTOM, -i rename file only when successfully changed, All ARGV input +should act like <>, report HANDLE [formats], support in perlmain to rerun +debugger, lvalue functions -=item SECURITY +=item Possible pragmas -B<Comparison operators> (C<lt>, C<le>, C<ge>, C<gt> and C<cmp>):, -B<Case-mapping interpolation> (with C<\l>, C<\L>, C<\u> or C<\U>), -B<Matching operator> (C<m//>):, B<Substitution operator> (C<s///>):, -B<Output formatting functions> (printf() and write()):, B<Case-mapping -functions> (lc(), lcfirst(), uc(), ucfirst()):, B<POSIX locale-dependent -functions> (localeconv(), strcoll(),strftime(), strxfrm()):, B<POSIX -character class tests> (isalnum(), isalpha(), isdigit(),isgraph(), -islower(), isprint(), ispunct(), isspace(), isupper(), -isxdigit()): +=over 4 -=item ENVIRONMENT +=item 'less' -PERL_BADLANG, LC_ALL, LANGUAGE, LC_CTYPE, LC_COLLATE, LC_MONETARY, -LC_NUMERIC, LC_TIME, LANG +=back -=item NOTES +=item Optimizations -=over +=over 4 -=item Backward compatibility +=item constant function cache -=item I18N:Collate obsolete +=item foreach(reverse...) -=item Sort speed and memory use impacts +=item Cache eval tree -=item write() and LC_NUMERIC +=item rcatmaybe -=item Freely available locale definitions +=item Shrink opcode tables -=item I18n and l10n +=item Cache hash value -=item An imperfect standard +=item Optimize away @_ where possible + +=item Optimize sort by { $a <=> $b } + +=item Rewrite regexp parser for better integrated optimization =back -=item BUGS +=item Vague possibilities -=over +ref function in list context, make tr/// return histogram in list context?, +Loop control on do{} et al, Explicit switch statements, compile to real +threaded code, structured types, Modifiable $1 et al -=item Broken systems +=item To Do Or Not To Do -=back +=over 4 -=item SEE ALSO +=item Making my() work on "package" variables -=item HISTORY +=item "or" testing defined not truth -=back +=item "dynamic" lexicals -=head2 perlref - Perl references and nested data structures +=item "class"-based, rather than package-based "lexicals" -=over +=back -=item NOTE +=item Threading -=item DESCRIPTION +=over 4 -=over +=item Modules -=item Making References +=item Testing -=item Using References +=item $AUTOLOAD -=item Symbolic references +=item exit/die -=item Not-so-symbolic references +=item External threads -=item Pseudo-hashes: Using an array as a hash +=item Thread::Pool -=item Function Templates +=item thread-safety + +=item Per-thread GVs =back -=item WARNING +=item Compiler -=item SEE ALSO +=over 4 -=back +=item Optimization -=head2 perlreftut - Mark's very short tutorial about references +=item Byteperl -=over +=item Precompiled modules -=item DESCRIPTION +=item Executables -=item Who Needs Complicated Data Structures? +=item Typed lexicals -=item The Solution +=item Win32 -=item Syntax +=item END blocks -=over +=item _AUTOLOAD -=item Making References +=item comppadlist -=item Using References +=item Cached compilation =back -=item An Example +=item Recently Finished Tasks -=item Arrow Rule +=over 4 -=item Solution +=item Figure a way out of $^(capital letter) -=item The Rest +=item Filenames -=item Summary +=item Foreign lines -=item Credits +=item Namespace cleanup -=over +=item ISA.pm -=item Distribution Conditions +=item gettimeofday + +=item autocroak? =back =back -=head2 perldsc - Perl Data Structures Cookbook +=head2 perlhack - How to hack at the Perl internals -=over +=over 4 =item DESCRIPTION -arrays of arrays, hashes of arrays, arrays of hashes, hashes of hashes, -more elaborate constructs +Does concept match the general goals of Perl?, Where is the +implementation?, Backwards compatibility, Could it be a module instead?, Is +the feature generic enough?, Does it potentially introduce new bugs?, Does +it preclude other desirable features?, Is the implementation robust?, Is +the implementation generic enough to be portable?, Is there enough +documentation?, Is there another way to do it?, Does it create too much +work?, Patches speak louder than words -=item REFERENCES +=over 4 -=item COMMON MISTAKES +=item Keeping in sync -=item CAVEAT ON PRECEDENCE +rsync'ing the source tree, Using rsync over the LAN, Using pushing over the +NFS, rsync'ing the patches -=item WHY YOU SHOULD ALWAYS C<use strict> +=item Why rsync the source tree -=item DEBUGGING +It's easier, It's more recent, It's more reliable -=item CODE EXAMPLES +=item Why rsync the patches -=item ARRAYS OF ARRAYS +It's easier, It's a good reference, Finding a start point, Finding how to +fix a bug, Finding the source of misbehaviour -=over +=item Submitting patches -=item Declaration of a ARRAY OF ARRAYS +L<perlguts>, L<perlxstut> and L<perlxs>, L<perlapi>, +F<Porting/pumpkin.pod>, The perl5-porters FAQ -=item Generation of a ARRAY OF ARRAYS +=item Finding Your Way Around -=item Access and Printing of a ARRAY OF ARRAYS +Core modules, Documentation, Configure, Interpreter -=back +=item Elements of the interpreter -=item HASHES OF ARRAYS +Startup, Parsing, Optimization, Running -=over +=item Internal Variable Types -=item Declaration of a HASH OF ARRAYS +=item Op Trees -=item Generation of a HASH OF ARRAYS +=item Stacks -=item Access and Printing of a HASH OF ARRAYS +Argument stack, Mark stack, Save stack -=back +=item Millions of Macros -=item ARRAYS OF HASHES +=item Poking at Perl -=over +=item Using a source-level debugger -=item Declaration of a ARRAY OF HASHES +run [args], break function_name, break source.c:xxx, step, next, continue, +finish, 'enter', print -=item Generation of a ARRAY OF HASHES +=item Dumping Perl Data Structures -=item Access and Printing of a ARRAY OF HASHES +=item Patching =back -=item HASHES OF HASHES +=item EXTERNAL TOOLS FOR DEBUGGING PERL -=over +=over 4 -=item Declaration of a HASH OF HASHES +=item Rational Software's Purify -=item Generation of a HASH OF HASHES +=item Purify on Unix -=item Access and Printing of a HASH OF HASHES +-Accflags=-DPURIFY, -Doptimize='-g', -Uusemymalloc, -Dusemultiplicity + +=item Purify on NT + +DEFINES, USE_MULTI = define, #PERL_MALLOC = define, CFG = Debug + +=item CONCLUSION + +I<The Road goes ever on and on, down from the door where it began.> =back -=item MORE ELABORATE RECORDS +=item AUTHOR -=over +=back -=item Declaration of MORE ELABORATE RECORDS +=head2 perlhist - the Perl history records -=item Declaration of a HASH OF COMPLEX RECORDS +=over 4 -=item Generation of a HASH OF COMPLEX RECORDS +=item DESCRIPTION + +=item INTRODUCTION + +=item THE KEEPERS OF THE PUMPKIN + +=over 4 + +=item PUMPKIN? =back -=item Database Ties +=item THE RECORDS -=item SEE ALSO +=over 4 -=item AUTHOR +=item SELECTED RELEASE SIZES + +=item SELECTED PATCH SIZES =back -=head2 perllol - Manipulating Arrays of Arrays in Perl +=item THE KEEPERS OF THE RECORDS + +=back + +=head2 perldelta - what's new for perl v5.6 -=over +=over 4 =item DESCRIPTION -=item Declaration and Access of Arrays of Arrays +=item Summary of changes between 5.6.0 and 5.6.1 -=item Growing Your Own +=over 4 -=item Access and Printing +=item Security Issues -=item Slices +=item Core bug fixes -=item SEE ALSO +C<UNIVERSAL::isa()>, Memory leaks, Numeric conversions, qw(a\\b), caller(), +Bugs in regular expressions, "slurp" mode, Autovivification of symbolic +references to special variables, Lexical warnings, Spurious warnings and +errors, glob(), Tainting, sort(), #line directives, Subroutine prototypes, +map(), Debugger, Locales, PERL5OPT, chop(), Unicode support, 64-bit +support, Compiler, Lvalue subroutines, IO::Socket, File::Find, xsubpp, C<no +Module;>, Tests -=item AUTHOR +=item Core features -=back +=item Configuration issues -=head2 perlboot - Beginner's Object-Oriented Tutorial +=item Documentation -=over +=item Bundled modules -=item DESCRIPTION +B::Concise, File::Temp, Pod::LaTeX, Pod::Text::Overstrike, CGI, CPAN, +Class::Struct, DB_File, Devel::Peek, File::Find, Getopt::Long, IO::Poll, +IPC::Open3, Math::BigFloat, Math::Complex, Net::Ping, Opcode, Pod::Parser, +Pod::Text, SDBM_File, Sys::Syslog, Tie::RefHash, Tie::SubstrHash -=over +=item Platform-specific improvements -=item If we could talk to the animals... +NCR MP-RAS, NonStop-UX -=item Introducing the method invocation arrow +=item Interpreter cloning, threads, and concurrency -=item Invoking a barnyard +=item Lexically scoped warning categories -=item The extra parameter of method invocation +=item Unicode and UTF-8 support -=item Calling a second method to simplify things +=item Support for interpolating named characters -=item Inheriting the windpipes +=item "our" declarations -=item A few notes about @ISA +=item Support for strings represented as a vector of ordinals -=item Overriding the methods +=item Improved Perl version numbering system -=item Starting the search from a different place +=item New syntax for declaring subroutine attributes -=item The SUPER way of doing things +=item File and directory handles can be autovivified -=item Where we're at so far... +=item open() with more than two arguments -=item A horse is a horse, of course of course -- or is it? +=item 64-bit support -=item Invoking an instance method +=item Large file support -=item Accessing the instance data +=item Long doubles -=item How to build a horse +=item "more bits" -=item Inheriting the constructor +=item Enhanced support for sort() subroutines -=item Making a method work with either classes or instances +=item C<sort $coderef @foo> allowed -=item Adding parameters to a method +=item File globbing implemented internally -=item More interesting instances +=item Support for CHECK blocks -=item A horse of a different color +=item POSIX character class syntax [: :] supported -=item Summary +=item Better pseudo-random number generator -=back +=item Improved C<qw//> operator -=item SEE ALSO +=item Better worst-case behavior of hashes -=item COPYRIGHT +=item pack() format 'Z' supported -=back +=item pack() format modifier '!' supported -=head2 perltoot - Tom's object-oriented tutorial for perl +=item pack() and unpack() support counted strings -=over +=item Comments in pack() templates -=item DESCRIPTION +=item Weak references -=item Creating a Class +=item Binary numbers supported -=over +=item Lvalue subroutines -=item Object Representation +=item Some arrows may be omitted in calls through references -=item Class Interface +=item Boolean assignment operators are legal lvalues -=item Constructors and Instance Methods +=item exists() is supported on subroutine names -=item Planning for the Future: Better Constructors +=item exists() and delete() are supported on array elements -=item Destructors +=item Pseudo-hashes work better -=item Other Object Methods +=item Automatic flushing of output buffers -=back +=item Better diagnostics on meaningless filehandle operations -=item Class Data +=item Where possible, buffered data discarded from duped input filehandle -=over +=item eof() has the same old magic as <> -=item Accessing Class Data +=item binmode() can be used to set :crlf and :raw modes -=item Debugging Methods +=item C<-T> filetest recognizes UTF-8 encoded files as "text" -=item Class Destructors +=item system(), backticks and pipe open now reflect exec() failure -=item Documenting the Interface +=item Improved diagnostics -=back +=item Diagnostics follow STDERR -=item Aggregation +=item More consistent close-on-exec behavior -=item Inheritance +=item syswrite() ease-of-use -=over +=item Better syntax checks on parenthesized unary operators -=item Overridden Methods +=item Bit operators support full native integer width -=item Multiple Inheritance +=item Improved security features -=item UNIVERSAL: The Root of All Objects +=item More functional bareword prototype (*) -=back +=item C<require> and C<do> may be overridden -=item Alternate Object Representations +=item $^X variables may now have names longer than one character -=over +=item New variable $^C reflects C<-c> switch -=item Arrays as Objects +=item New variable $^V contains Perl version as a string -=item Closures as Objects +=item Optional Y2K warnings + +=item Arrays now always interpolate into double-quoted strings =back -=item AUTOLOAD: Proxy Methods +=item Modules and Pragmata -=over +=over 4 -=item Autoloaded Data Methods +=item Modules -=item Inherited Autoloaded Data Methods +attributes, B, Benchmark, ByteLoader, constant, charnames, Data::Dumper, +DB, DB_File, Devel::DProf, Devel::Peek, Dumpvalue, DynaLoader, English, +Env, Fcntl, File::Compare, File::Find, File::Glob, File::Spec, +File::Spec::Functions, Getopt::Long, IO, JPL, lib, Math::BigInt, +Math::Complex, Math::Trig, Pod::Parser, Pod::InputObjects, Pod::Checker, +podchecker, Pod::ParseUtils, Pod::Find, Pod::Select, podselect, Pod::Usage, +pod2usage, Pod::Text and Pod::Man, SDBM_File, Sys::Syslog, Sys::Hostname, +Term::ANSIColor, Time::Local, Win32, XSLoader, DBM Filters + +=item Pragmata =back -=item Metaclassical Tools +=item Utility Changes -=over +=over 4 -=item Class::Struct +=item dprofpp -=item Data Members as Variables +=item find2perl -=item NOTES +=item h2xs -=item Object Terminology +=item perlcc + +=item perldoc + +=item The Perl Debugger =back -=item SEE ALSO +=item Improved Documentation -=item AUTHOR AND COPYRIGHT +perlapi.pod, perlboot.pod, perlcompile.pod, perldbmfilter.pod, +perldebug.pod, perldebguts.pod, perlfork.pod, perlfilter.pod, perlhack.pod, +perlintern.pod, perllexwarn.pod, perlnumber.pod, perlopentut.pod, +perlreftut.pod, perltootc.pod, perltodo.pod, perlunicode.pod -=item COPYRIGHT +=item Performance enhancements -=over +=over 4 -=item Acknowledgments +=item Simple sort() using { $a <=> $b } and the like are optimized -=back +=item Optimized assignments to lexical variables + +=item Faster subroutine calls + +=item delete(), each(), values() and hash iteration are faster =back -=head2 perltootc - Tom's OO Tutorial for Class Data in Perl +=item Installation and Configuration Improvements -=over +=over 4 -=item DESCRIPTION +=item -Dusethreads means something different -=item Class Data as Package Variables +=item New Configure flags -=over +=item Threadedness and 64-bitness now more daring -=item Putting All Your Eggs in One Basket +=item Long Doubles -=item Inheritance Concerns +=item -Dusemorebits -=item The Eponymous Meta-Object +=item -Duselargefiles -=item Indirect References to Class Data +=item installusrbinperl -=item Monadic Classes +=item SOCKS support -=item Translucent Attributes +=item C<-A> flag + +=item Enhanced Installation Directories + +=item gcc automatically tried if 'cc' does not seem to be working =back -=item Class Data as Lexical Variables +=item Platform specific changes -=over +=over 4 -=item Privacy and Responsibility +=item Supported platforms -=item File-Scoped Lexicals +=item DOS -=item More Inheritance Concerns +=item OS390 (OpenEdition MVS) -=item Locking the Door and Throwing Away the Key +=item VMS -=item Translucency Revisited +=item Win32 =back -=item NOTES +=item Significant bug fixes -=item SEE ALSO +=over 4 -=item AUTHOR AND COPYRIGHT +=item <HANDLE> on empty files -=item ACKNOWLEDGEMENTS +=item C<eval '...'> improvements -=item HISTORY +=item All compilation errors are true errors -=back +=item Implicitly closed filehandles are safer -=head2 perlobj - Perl objects +=item Behavior of list slices is more consistent -=over +=item C<(\$)> prototype and C<$foo{a}> -=item DESCRIPTION +=item C<goto &sub> and AUTOLOAD -=over +=item C<-bareword> allowed under C<use integer> -=item An Object is Simply a Reference +=item Failures in DESTROY() -=item A Class is Simply a Package +=item Locale bugs fixed -=item A Method is Simply a Subroutine +=item Memory leaks -=item Method Invocation +=item Spurious subroutine stubs after failed subroutine calls -=item WARNING +=item Taint failures under C<-U> -=item Default UNIVERSAL methods +=item END blocks and the C<-c> switch -isa(CLASS), can(METHOD), VERSION( [NEED] ) +=item Potential to leak DATA filehandles -=item Destructors +=back -=item Summary +=item New or Changed Diagnostics -=item Two-Phased Garbage Collection +"%s" variable %s masks earlier declaration in same %s, "my sub" not yet +implemented, "our" variable %s redeclared, '!' allowed only after types %s, +/ cannot take a count, / must be followed by a, A or Z, / must be followed +by a*, A* or Z*, / must follow a numeric type, /%s/: Unrecognized escape +\\%c passed through, /%s/: Unrecognized escape \\%c in character class +passed through, /%s/ should probably be written as "%s", %s() called too +early to check prototype, %s argument is not a HASH or ARRAY element, %s +argument is not a HASH or ARRAY element or slice, %s argument is not a +subroutine name, %s package attribute may clash with future reserved word: +%s, (in cleanup) %s, <> should be quotes, Attempt to join self, Bad evalled +substitution pattern, Bad realloc() ignored, Bareword found in conditional, +Binary number > 0b11111111111111111111111111111111 non-portable, Bit vector +size > 32 non-portable, Buffer overflow in prime_env_iter: %s, Can't check +filesystem of script "%s", Can't declare class for non-scalar %s in "%s", +Can't declare %s in "%s", Can't ignore signal CHLD, forcing to default, +Can't modify non-lvalue subroutine call, Can't read CRTL environ, Can't +remove %s: %s, skipping file, Can't return %s from lvalue subroutine, Can't +weaken a nonreference, Character class [:%s:] unknown, Character class +syntax [%s] belongs inside character classes, Constant is not %s reference, +constant(%s): %s, CORE::%s is not a keyword, defined(@array) is deprecated, +defined(%hash) is deprecated, Did not produce a valid header, (Did you mean +"local" instead of "our"?), Document contains no data, entering effective +%s failed, false [] range "%s" in regexp, Filehandle %s opened only for +output, flock() on closed filehandle %s, Global symbol "%s" requires +explicit package name, Hexadecimal number > 0xffffffff non-portable, +Ill-formed CRTL environ value "%s", Ill-formed message in prime_env_iter: +|%s|, Illegal binary digit %s, Illegal binary digit %s ignored, Illegal +number of bits in vec, Integer overflow in %s number, Invalid %s attribute: +%s, Invalid %s attributes: %s, invalid [] range "%s" in regexp, Invalid +separator character %s in attribute list, Invalid separator character %s in +subroutine attribute list, leaving effective %s failed, Lvalue subs +returning %s not implemented yet, Method %s not permitted, Missing +%sbrace%s on \N{}, Missing command in piped open, Missing name in "my sub", +No %s specified for -%c, No package name allowed for variable %s in "our", +No space allowed after -%c, no UTC offset information; assuming local time +is UTC, Octal number > 037777777777 non-portable, panic: del_backref, +panic: kid popen errno read, panic: magic_killbackrefs, Parentheses missing +around "%s" list, Possible unintended interpolation of %s in string, +Possible Y2K bug: %s, pragma "attrs" is deprecated, use "sub NAME : ATTRS" +instead, Premature end of script headers, Repeat count in pack overflows, +Repeat count in unpack overflows, realloc() of freed memory ignored, +Reference is already weak, setpgrp can't take arguments, Strange *+?{} on +zero-length expression, switching effective %s is not implemented, This +Perl can't reset CRTL environ elements (%s), This Perl can't set CRTL +environ elements (%s=%s), Too late to run %s block, Unknown open() mode +'%s', Unknown process %x sent message to prime_env_iter: %s, Unrecognized +escape \\%c passed through, Unterminated attribute parameter in attribute +list, Unterminated attribute list, Unterminated attribute parameter in +subroutine attribute list, Unterminated subroutine attribute list, Value of +CLI symbol "%s" too long, Version number must be a constant number -=back +=item New tests -=item SEE ALSO +=item Incompatible Changes -=back +=over 4 -=head2 perltie - how to hide an object class in a simple variable +=item Perl Source Incompatibilities -=over +CHECK is a new keyword, Treatment of list slices of undef has changed, +Format of $English::PERL_VERSION is different, Literals of the form +C<1.2.3> parse differently, Possibly changed pseudo-random number +generator, Hashing function for hash keys has changed, C<undef> fails on +read only values, Close-on-exec bit may be set on pipe and socket handles, +Writing C<"$$1"> to mean C<"${$}1"> is unsupported, delete(), each(), +values() and C<\(%h)>, vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS, +Text of some diagnostic output has changed, C<%@> has been removed, +Parenthesized not() behaves like a list operator, Semantics of bareword +prototype C<(*)> have changed, Semantics of bit operators may have changed +on 64-bit platforms, More builtins taint their results -=item SYNOPSIS +=item C Source Incompatibilities -=item DESCRIPTION +C<PERL_POLLUTE>, C<PERL_IMPLICIT_CONTEXT>, C<PERL_POLLUTE_MALLOC> -=over +=item Compatible C Source API Changes -=item Tying Scalars +C<PATCHLEVEL> is now C<PERL_VERSION> -TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this +=item Binary Incompatibilities -=item Tying Arrays +=back -TIEARRAY classname, LIST, FETCH this, index, STORE this, index, value, -DESTROY this +=item Known Problems -=item Tying Hashes +=over 4 -USER, HOME, CLOBBER, LIST, TIEHASH classname, LIST, FETCH this, key, STORE -this, key, value, DELETE this, key, CLEAR this, EXISTS this, key, FIRSTKEY -this, NEXTKEY this, lastkey, DESTROY this +=item Localizing a tied hash element may leak memory -=item Tying FileHandles +=item Known test failures -TIEHANDLE classname, LIST, WRITE this, LIST, PRINT this, LIST, PRINTF this, -LIST, READ this, LIST, READLINE this, GETC this, CLOSE this, DESTROY this +64-bit builds, Failure of Thread tests, NEXTSTEP 3.3 POSIX test failure, +Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with gcc -=item The C<untie> Gotcha +=item EBCDIC platforms not fully supported + +=item UNICOS/mk CC failures during Configure run + +=item Arrow operator and arrays + +=item Experimental features + +Threads, Unicode, 64-bit support, Lvalue subroutines, Weak references, The +pseudo-hash data type, The Compiler suite, Internal implementation of file +globbing, The DB module, The regular expression code constructs: =back -=item SEE ALSO +=item Obsolete Diagnostics -=item BUGS +Character class syntax [: :] is reserved for future extensions, Ill-formed +logical name |%s| in prime_env_iter, In string, @%s now must be written as +\@%s, Probable precedence problem on %s, regexp too big, Use of "$$<digit>" +to mean "${$}<digit>" is deprecated -=item AUTHOR +=item Reporting Bugs + +=item SEE ALSO + +=item HISTORY =back -=head2 perlbot - Bag'o Object Tricks (the BOT) +=head2 perl5005delta, perldelta - what's new for perl5.005 -=over +=over 4 =item DESCRIPTION -=item OO SCALING TIPS +=item About the new versioning system -=item INSTANCE VARIABLES +=item Incompatible Changes -=item SCALAR INSTANCE VARIABLES +=over 4 -=item INSTANCE VARIABLE INHERITANCE +=item WARNING: This version is not binary compatible with Perl 5.004. -=item OBJECT RELATIONSHIPS +=item Default installation structure has changed -=item OVERRIDING SUPERCLASS METHODS +=item Perl Source Compatibility -=item USING RELATIONSHIP WITH SDBM +=item C Source Compatibility -=item THINKING OF CODE REUSE +=item Binary Compatibility -=item CLASS CONTEXT AND THE OBJECT +=item Security fixes may affect compatibility -=item INHERITING A CONSTRUCTOR +=item Relaxed new mandatory warnings introduced in 5.004 -=item DELEGATION +=item Licensing =back -=head2 perlipc - Perl interprocess communication (signals, fifos, pipes, -safe subprocesses, sockets, and semaphores) +=item Core Changes -=over +=over 4 -=item DESCRIPTION +=item Threads -=item Signals +=item Compiler -=item Named Pipes +=item Regular Expressions -=over +Many new and improved optimizations, Many bug fixes, New regular expression +constructs, New operator for precompiled regular expressions, Other +improvements, Incompatible changes -=item WARNING +=item Improved malloc() -=back +=item Quicksort is internally implemented -=item Using open() for IPC +=item Reliable signals -=over +=item Reliable stack pointers -=item Filehandles +=item More generous treatment of carriage returns -=item Background Processes +=item Memory leaks -=item Complete Dissociation of Child from Parent +=item Better support for multiple interpreters -=item Safe Pipe Opens +=item Behavior of local() on array and hash elements is now well-defined -=item Bidirectional Communication with Another Process +=item C<%!> is transparently tied to the L<Errno> module -=item Bidirectional Communication with Yourself +=item Pseudo-hashes are supported -=back +=item C<EXPR foreach EXPR> is supported -=item Sockets: Client/Server Communication +=item Keywords can be globally overridden -=over +=item C<$^E> is meaningful on Win32 -=item Internet Line Terminators +=item C<foreach (1..1000000)> optimized -=item Internet TCP Clients and Servers +=item C<Foo::> can be used as implicitly quoted package name -=item Unix-Domain TCP Clients and Servers +=item C<exists $Foo::{Bar::}> tests existence of a package -=back +=item Better locale support -=item TCP Clients with IO::Socket +=item Experimental support for 64-bit platforms -=over +=item prototype() returns useful results on builtins -=item A Simple Client +=item Extended support for exception handling -C<Proto>, C<PeerAddr>, C<PeerPort> +=item Re-blessing in DESTROY() supported for chaining DESTROY() methods -=item A Webget Client +=item All C<printf> format conversions are handled internally -=item Interactive Client with IO::Socket +=item New C<INIT> keyword -=back +=item New C<lock> keyword -=item TCP Servers with IO::Socket +=item New C<qr//> operator -Proto, LocalPort, Listen, Reuse +=item C<our> is now a reserved word -=item UDP: Message Passing +=item Tied arrays are now fully supported -=item SysV IPC +=item Tied handles support is better -=item NOTES +=item 4th argument to substr -=item BUGS +=item Negative LENGTH argument to splice -=item AUTHOR +=item Magic lvalues are now more magical -=item SEE ALSO +=item <> now reads in records =back -=head2 perldbmfilter - Perl DBM Filters +=item Supported Platforms -=over +=over 4 -=item SYNOPSIS +=item New Platforms -=item DESCRIPTION +=item Changes in existing support -B<filter_store_key>, B<filter_store_value>, B<filter_fetch_key>, -B<filter_fetch_value> +=back -=over +=item Modules and Pragmata -=item The Filter +=over 4 -=item An Example -- the NULL termination problem. +=item New Modules -=item Another Example -- Key is a C int. +B, Data::Dumper, Dumpvalue, Errno, File::Spec, ExtUtils::Installed, +ExtUtils::Packlist, Fatal, IPC::SysV, Test, Tie::Array, Tie::Handle, +Thread, attrs, fields, re + +=item Changes in existing modules + +Benchmark, Carp, CGI, Fcntl, Math::Complex, Math::Trig, POSIX, DB_File, +MakeMaker, CPAN, Cwd =back +=item Utility Changes + +=item Documentation Changes + +=item New Diagnostics + +Ambiguous call resolved as CORE::%s(), qualify as such or use &, Bad index +while coercing array into hash, Bareword "%s" refers to nonexistent +package, Can't call method "%s" on an undefined value, Can't check +filesystem of script "%s" for nosuid, Can't coerce array into hash, Can't +goto subroutine from an eval-string, Can't localize pseudo-hash element, +Can't use %%! because Errno.pm is not available, Cannot find an opnumber +for "%s", Character class syntax [. .] is reserved for future extensions, +Character class syntax [: :] is reserved for future extensions, Character +class syntax [= =] is reserved for future extensions, %s: Eval-group in +insecure regular expression, %s: Eval-group not allowed, use re 'eval', %s: +Eval-group not allowed at run time, Explicit blessing to '' (assuming +package main), Illegal hex digit ignored, No such array field, No such +field "%s" in variable %s of type %s, Out of memory during ridiculously +large request, Range iterator outside integer range, Recursive inheritance +detected while looking for method '%s' %s, Reference found where even-sized +list expected, Undefined value assigned to typeglob, Use of reserved word +"%s" is deprecated, perl: warning: Setting locale failed + +=item Obsolete Diagnostics + +Can't mktemp(), Can't write to temp file for B<-e>: %s, Cannot open +temporary file, regexp too big + +=item Configuration Changes + +=item BUGS + =item SEE ALSO -=item AUTHOR +=item HISTORY =back -=head2 perldebug - Perl debugging +=head2 perl5004delta, perldelta - what's new for perl5.004 -=over +=over 4 =item DESCRIPTION -=item The Perl Debugger +=item Supported Environments -=over +=item Core Changes -=item Debugger Commands +=over 4 -h [command], p expr, x expr, V [pkg [vars]], X [vars], T, s [expr], n -[expr], r, <CR>, c [line|sub], l, l min+incr, l min-max, l line, l subname, --, w [line], f filename, /pattern/, ?pattern?, L, S [[!]regex], t, t expr, -b [line] [condition], b subname [condition], b postpone subname -[condition], b load filename, b compile subname, d [line], D, a [line] -command, a [line], A, W expr, W, O booloption .., O anyoption? .., O -option=value .., < ?, < [ command ], << command, > ?, > command, >> -command, { ?, { [ command ], {{ command, ! number, ! -number, ! pattern, !! -cmd, H -number, q or ^D, R, |dbcmd, ||dbcmd, command, m expr, man [manpage] +=item List assignment to %ENV works -=item Configurable Options +=item Change to "Can't locate Foo.pm in @INC" error -C<recallCommand>, C<ShellBang>, C<pager>, C<tkRunning>, C<signalLevel>, -C<warnLevel>, C<dieLevel>, C<AutoTrace>, C<LineInfo>, C<inhibit_exit>, -C<PrintRet>, C<ornaments>, C<frame>, C<maxTraceLen>, C<arrayDepth>, -C<hashDepth>, C<compactDump>, C<veryCompact>, C<globPrint>, C<DumpDBFiles>, -C<DumpPackages>, C<DumpReused>, C<quote>, C<HighBit>, C<undefPrint>, -C<UsageOnly>, C<TTY>, C<noTTY>, C<ReadLine>, C<NonStop> +=item Compilation option: Binary compatibility with 5.003 -=item Debugger input/output +=item $PERL5OPT environment variable -Prompt, Multiline commands, Stack backtrace, Line Listing Format, Frame -listing +=item Limitations on B<-M>, B<-m>, and B<-T> options -=item Debugging compile-time statements +=item More precise warnings -=item Debugger Customization +=item Deprecated: Inherited C<AUTOLOAD> for non-methods -=item Readline Support +=item Previously deprecated %OVERLOAD is no longer usable -=item Editor Support for Debugging +=item Subroutine arguments created only when they're modified -=item The Perl Profiler +=item Group vector changeable with C<$)> -=back +=item Fixed parsing of $$<digit>, &$<digit>, etc. -=item Debugging regular expressions +=item Fixed localization of $<digit>, $&, etc. -=item Debugging memory usage +=item No resetting of $. on implicit close -=item SEE ALSO +=item C<wantarray> may return undef -=item BUGS +=item C<eval EXPR> determines value of EXPR in scalar context -=back +=item Changes to tainting checks -=head2 perlnumber - semantics of numbers and numeric operations in Perl +No glob() or <*>, No spawning if tainted $CDPATH, $ENV, $BASH_ENV, No +spawning if tainted $TERM doesn't look like a terminal name -=over +=item New Opcode module and revised Safe module -=item SYNOPSIS +=item Embedding improvements -=item DESCRIPTION +=item Internal change: FileHandle class based on IO::* classes -=item Storing numbers +=item Internal change: PerlIO abstraction interface -=item Numeric operators and numeric conversions +=item New and changed syntax -=item Flavors of Perl numeric operations +$coderef->(PARAMS) -Arithmetic operators except, C<no integer>, Arithmetic operators except, -C<use integer>, Bitwise operators, C<no integer>, Bitwise operators, C<use -integer>, Operators which expect an integer, Operators which expect a -string +=item New and changed builtin constants -=item AUTHOR +__PACKAGE__ -=item SEE ALSO +=item New and changed builtin variables -=back +$^E, $^H, $^M -=head2 perldebguts - Guts of Perl debugging +=item New and changed builtin functions -=over +delete on slices, flock, printf and sprintf, keys as an lvalue, my() in +Control Structures, pack() and unpack(), sysseek(), use VERSION, use Module +VERSION LIST, prototype(FUNCTION), srand, $_ as Default, C<m//gc> does not +reset search position on failure, C<m//x> ignores whitespace before ?*+{}, +nested C<sub{}> closures work now, formats work right on changing lexicals -=item DESCRIPTION +=item New builtin methods -=item Debugger Internals +isa(CLASS), can(METHOD), VERSION( [NEED] ) -=over +=item TIEHANDLE now supported -=item Writing Your Own Debugger +TIEHANDLE classname, LIST, PRINT this, LIST, PRINTF this, LIST, READ this +LIST, READLINE this, GETC this, DESTROY this -=back +=item Malloc enhancements -=item Frame Listing Output Examples +-DPERL_EMERGENCY_SBRK, -DPACK_MALLOC, -DTWO_POT_OPTIMIZE -=item Debugging regular expressions +=item Miscellaneous efficiency enhancements -=over +=back -=item Compile-time output +=item Support for More Operating Systems -C<anchored> I<STRING> C<at> I<POS>, C<floating> I<STRING> C<at> -I<POS1..POS2>, C<matching floating/anchored>, C<minlen>, C<stclass> -I<TYPE>, C<noscan>, C<isall>, C<GPOS>, C<plus>, C<implicit>, C<with eval>, -C<anchored(TYPE)> +=over 4 -=item Types of nodes +=item Win32 -=item Run-time output +=item Plan 9 + +=item QNX + +=item AmigaOS =back -=item Debugging Perl memory usage +=item Pragmata -=over +use autouse MODULE => qw(sub1 sub2 sub3), use blib, use blib 'dir', use +constant NAME => VALUE, use locale, use ops, use vmsish -=item Using C<$ENV{PERL_DEBUG_MSTATS}> +=item Modules -C<buckets SMALLEST(APPROX)..GREATEST(APPROX)>, Free/Used, C<Total sbrk(): -SBRKed/SBRKs:CONTINUOUS>, C<pad: 0>, C<heads: 2192>, C<chain: 0>, C<tail: -6144> +=over 4 -=item Example of using B<-DL> switch +=item Required Updates -C<717>, C<002>, C<054>, C<602>, C<702>, C<704> +=item Installation directories -=item B<-DL> details +=item Module information summary -C<!!!>, C<!!>, C<!> +=item Fcntl -=item Limitations of B<-DL> statistics +=item IO -=back +=item Math::Complex -=item SEE ALSO +=item Math::Trig + +=item DB_File + +=item Net::Ping + +=item Object-oriented overrides for builtin operators =back -=head2 perldiag - various Perl diagnostics +=item Utility Changes -=over +=over 4 -=item DESCRIPTION +=item pod2html -=back +Sends converted HTML to standard output -=head2 perlsec - Perl security +=item xsubpp -=over +C<void> XSUBs now default to returning nothing -=item DESCRIPTION +=back -=over +=item C Language API Changes -=item Laundering and Detecting Tainted Data +C<gv_fetchmethod> and C<perl_call_sv>, C<perl_eval_pv>, Extended API for +manipulating hashes -=item Switches On the "#!" Line +=item Documentation Changes -=item Cleaning Up Your Path +L<perldelta>, L<perlfaq>, L<perllocale>, L<perltoot>, L<perlapio>, +L<perlmodlib>, L<perldebug>, L<perlsec> -=item Security Bugs +=item New Diagnostics -=item Protecting Your Programs +"my" variable %s masks earlier declaration in same scope, %s argument is +not a HASH element or slice, Allocation too large: %lx, Allocation too +large, Applying %s to %s will act on scalar(%s), Attempt to free +nonexistent shared string, Attempt to use reference as lvalue in substr, +Bareword "%s" refers to nonexistent package, Can't redefine active sort +subroutine %s, Can't use bareword ("%s") as %s ref while "strict refs" in +use, Cannot resolve method `%s' overloading `%s' in package `%s', Constant +subroutine %s redefined, Constant subroutine %s undefined, Copy method did +not return a reference, Died, Exiting pseudo-block via %s, Identifier too +long, Illegal character %s (carriage return), Illegal switch in PERL5OPT: +%s, Integer overflow in hex number, Integer overflow in octal number, +internal error: glob failed, Invalid conversion in %s: "%s", Invalid type +in pack: '%s', Invalid type in unpack: '%s', Name "%s::%s" used only once: +possible typo, Null picture in formline, Offset outside string, Out of +memory!, Out of memory during request for %s, panic: frexp, Possible +attempt to put comments in qw() list, Possible attempt to separate words +with commas, Scalar value @%s{%s} better written as $%s{%s}, Stub found +while resolving method `%s' overloading `%s' in %s, Too late for "B<-T>" +option, untie attempted while %d inner references still exist, Unrecognized +character %s, Unsupported function fork, Use of "$$<digit>" to mean +"${$}<digit>" is deprecated, Value of %s can be "0"; test with defined(), +Variable "%s" may be unavailable, Variable "%s" will not stay shared, +Warning: something's wrong, Ill-formed logical name |%s| in prime_env_iter, +Got an error from DosAllocMem, Malformed PERLLIB_PREFIX, PERL_SH_DIR too +long, Process terminated by SIG%s -=back +=item BUGS =item SEE ALSO +=item HISTORY + =back -=head2 perltrap - Perl traps for the unwary +=head2 perlaix, README.aix - Perl version 5 on IBM Unix (AIX) systems -=over +=over 4 =item DESCRIPTION -=over +=over 4 -=item Awk Traps +=item Compiling Perl 5 on AIX -=item C Traps +=item OS level -=item Sed Traps +=item Building Dynamic Extensions on AIX -=item Shell Traps +=item The IBM ANSI C Compiler -=item Perl Traps +=item Using GNU's gcc for building perl -=item Perl4 to Perl5 Traps +=item Using Large Files with Perl -Discontinuance, Deprecation, and BugFix traps, Parsing Traps, Numerical -Traps, General data type traps, Context Traps - scalar, list contexts, -Precedence Traps, General Regular Expression Traps using s///, etc, -Subroutine, Signal, Sorting Traps, OS Traps, DBM Traps, Unclassified Traps +=item Threaded Perl -=item Discontinuance, Deprecation, and BugFix traps +=item 64-bit Perl -Discontinuance, Deprecation, BugFix, Discontinuance, Discontinuance, -Discontinuance, BugFix, Discontinuance, Discontinuance, BugFix, -Discontinuance, Deprecation, Discontinuance +=item GDBM and Threads -=item Parsing Traps +=item NFS filesystems and utime(2) -Parsing, Parsing, Parsing, Parsing +=back -=item Numerical Traps +=item AUTHOR -Numerical, Numerical, Numerical, Bitwise string ops +=item DATE -=item General data type traps +=back -(Arrays), (Arrays), (Hashes), (Globs), (Globs), (Scalar String), -(Constants), (Scalars), (Variable Suicide) +=head2 perlamiga - Perl under Amiga OS -=item Context Traps - scalar, list contexts +=over 4 -(list context), (scalar context), (scalar context), (list, builtin) +=item SYNOPSIS -=item Precedence Traps +=back -Precedence, Precedence, Precedence, Precedence, Precedence, Precedence, -Precedence +=over 4 -=item General Regular Expression Traps using s///, etc. +=item DESCRIPTION -Regular Expression, Regular Expression, Regular Expression, Regular -Expression, Regular Expression, Regular Expression, Regular Expression, -Regular Expression +=over 4 -=item Subroutine, Signal, Sorting Traps +=item Prerequisites -(Signals), (Sort Subroutine), warn() won't let you specify a filehandle +B<Unix emulation for AmigaOS: ixemul.library>, B<Version of Amiga OS> -=item OS Traps +=item Starting Perl programs under AmigaOS -(SysV), (SysV) +=item Shortcomings of Perl under AmigaOS -=item Interpolation Traps +=back -Interpolation, Interpolation, Interpolation, Interpolation, Interpolation, -Interpolation, Interpolation, Interpolation, Interpolation +=item INSTALLATION -=item DBM Traps +=item Accessing documentation -DBM, DBM +=over 4 -=item Unclassified Traps +=item Manpages -C<require>/C<do> trap using returned value, C<split> on empty string with -LIMIT specified +=item B<HTML> + +=item B<GNU> C<info> files + +=item C<LaTeX> docs =back +=item BUILD + +=over 4 + +=item Prerequisites + +=item Getting the perl source + +=item Making + +sh Configure -Dprefix=/ade -Dloclibpth=/ade/lib + +=item Testing + +=item Installing the built perl + =back -=head2 perlport - Writing portable Perl +=item AUTHORS -=over +=item SEE ALSO + +=back + +=head2 perlbs2000, README.BS2000 - building and installing Perl for BS2000. + +=over 4 + +=item SYNOPSIS =item DESCRIPTION -Not all Perl programs have to be portable, Nearly all of Perl already I<is> -portable +=over 4 -=item ISSUES +=item gzip -=over +=item bison -=item Newlines +=item Unpacking -=item Numbers endianness and Width +=item Compiling -=item Files and Filesystems +=item Testing -=item System Interaction +=item Install -=item Interprocess Communication (IPC) +=item Using Perl in the Posix-Shell -=item External Subroutines (XS) +=item Using Perl in "native" BS2000 -=item Standard Modules +=item Floating point anomalies -=item Time and Date +=back -=item Character sets and character encoding +=item AUTHORS -=item Internationalisation +=item SEE ALSO -=item System Resources +=over 4 -=item Security +=item Mailing list -=item Style +=back + +=item HISTORY =back -=item CPAN Testers +=head2 perlcygwin, README.cygwin - Perl for Cygwin -Mailing list: cpan-testers@perl.org, Testing results: -http://testers.cpan.org/ +=over 4 -=item PLATFORMS +=item SYNOPSIS -=over +=item PREREQUISITES -=item Unix +=over 4 -=item DOS and Derivatives +=item Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it) -Build instructions for OS/2, L<perlos2> +=item Cygwin Configuration -=item S<Mac OS> +C<PATH>, I<nroff>, Permissions -=item VMS +=back -=item VOS +=item CONFIGURE -=item EBCDIC Platforms +=over 4 -=item Acorn RISC OS +=item Strip Binaries -=item Other perls +=item Optional Libraries + +C<-lcrypt>, C<-lgdbm> (C<use GDBM_File>), C<-ldb> (C<use DB_File>), +C<-lcygipc> (C<use IPC::SysV>) + +=item Configure-time Options + +C<-Uusedl>, C<-Uusemymalloc>, C<-Dusemultiplicity>, C<-Duseperlio>, +C<-Duse64bitint>, C<-Duselongdouble>, C<-Dusethreads>, C<-Duselargefiles> + +=item Suspicious Warnings + +I<dlsym()>, Win9x and C<d_eofnblk>, Compiler/Preprocessor defines =back -=item FUNCTION IMPLEMENTATIONS +=item MAKE -=over +=over 4 -=item Alphabetical Listing of Perl Functions +=item Warnings --I<X> FILEHANDLE, -I<X> EXPR, -I<X>, alarm SECONDS, alarm, binmode -FILEHANDLE, chmod LIST, chown LIST, chroot FILENAME, chroot, crypt -PLAINTEXT,SALT, dbmclose HASH, dbmopen HASH,DBNAME,MODE, dump LABEL, exec -LIST, fcntl FILEHANDLE,FUNCTION,SCALAR, flock FILEHANDLE,OPERATION, fork, -getlogin, getpgrp PID, getppid, getpriority WHICH,WHO, getpwnam NAME, -getgrnam NAME, getnetbyname NAME, getpwuid UID, getgrgid GID, getnetbyaddr -ADDR,ADDRTYPE, getprotobynumber NUMBER, getservbyport PORT,PROTO, getpwent, -getgrent, gethostent, getnetent, getprotoent, getservent, setpwent, -setgrent, sethostent STAYOPEN, setnetent STAYOPEN, setprotoent STAYOPEN, -setservent STAYOPEN, endpwent, endgrent, endhostent, endnetent, -endprotoent, endservent, getsockopt SOCKET,LEVEL,OPTNAME, glob EXPR, glob, -ioctl FILEHANDLE,FUNCTION,SCALAR, kill SIGNAL, LIST, link OLDFILE,NEWFILE, -lstat FILEHANDLE, lstat EXPR, lstat, msgctl ID,CMD,ARG, msgget KEY,FLAGS, -msgsnd ID,MSG,FLAGS, msgrcv ID,VAR,SIZE,TYPE,FLAGS, open FILEHANDLE,EXPR, -open FILEHANDLE, pipe READHANDLE,WRITEHANDLE, readlink EXPR, readlink, -select RBITS,WBITS,EBITS,TIMEOUT, semctl ID,SEMNUM,CMD,ARG, semget -KEY,NSEMS,FLAGS, semop KEY,OPSTRING, setgrent, setpgrp PID,PGRP, -setpriority WHICH,WHO,PRIORITY, setpwent, setsockopt -SOCKET,LEVEL,OPTNAME,OPTVAL, shmctl ID,CMD,ARG, shmget KEY,SIZE,FLAGS, -shmread ID,VAR,POS,SIZE, shmwrite ID,STRING,POS,SIZE, socketpair -SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL, stat FILEHANDLE, stat EXPR, stat, -symlink OLDFILE,NEWFILE, syscall LIST, sysopen -FILEHANDLE,FILENAME,MODE,PERMS, system LIST, times, truncate -FILEHANDLE,LENGTH, truncate EXPR,LENGTH, umask EXPR, umask, utime LIST, -wait, waitpid PID,FLAGS +=item ld2 =back -=item CHANGES +=item TEST -v1.47, 22 March 2000, v1.46, 12 February 2000, v1.45, 20 December 1999, -v1.44, 19 July 1999, v1.43, 24 May 1999, v1.42, 22 May 1999, v1.41, 19 May -1999, v1.40, 11 April 1999, v1.39, 11 February 1999, v1.38, 31 December -1998, v1.37, 19 December 1998, v1.36, 9 September 1998, v1.35, 13 August -1998, v1.33, 06 August 1998, v1.32, 05 August 1998, v1.30, 03 August 1998, -v1.23, 10 July 1998 +=over 4 -=item Supported Platforms +=item File Permissions -=item SEE ALSO +=item Hard Links -=item AUTHORS / CONTRIBUTORS +=item Filetime Granularity -=item VERSION +=item Tainting Checks + +=item /etc/group + +=item Script Portability + +Pathnames, Text/Binary, F<.exe>, chown(), Miscellaneous =back -=head2 perlstyle - Perl style guide +=item INSTALL -=over +=item MANIFEST -=item DESCRIPTION +Documentation, Build, Configure, Make, Install, Tests, Compiled Perl +Source, Compiled Module Source, Perl Modules/Scripts + +=item BUGS + +=item AUTHORS + +=item HISTORY =back -=head2 perlpod - plain old documentation +=head2 perldos - Perl under DOS, W31, W95. + +=over 4 -=over +=item SYNOPSIS =item DESCRIPTION -=over +=over 4 -=item Verbatim Paragraph +=item Prerequisites -=item Command Paragraph +DJGPP, Pthreads -=item Ordinary Block of Text +=item Shortcomings of Perl under DOS -=item The Intent +=item Building -=item Embedding Pods in Perl Modules +=item Testing -=item Common Pod Pitfalls +=item Installation =back -=item SEE ALSO +=item BUILDING AND INSTALLING MODULES + +=over 4 + +=item Prerequisites + +=item Unpacking CPAN Modules + +=item Building Non-XS Modules + +=item Building XS Modules + +=back =item AUTHOR +=item SEE ALSO + =back -=head2 perlbook - Perl book information +=head2 perlepoc, README.epoc - Perl for EPOC -=over +=over 4 -=item DESCRIPTION +=item SYNOPSIS + +=item INTRODUCTION + +=item INSTALLING PERL ON EPOC + +=item STARTING PERL ON EPOC + +=item STOPPING PERL ON EPOC + +=item USING PERL ON EPOC + +=over 4 + +=item I/O Redirection + +=item PATH Names + +=item Editors + +=item Features + +=item Restrictions + +=item Compiling Perl 5 on the EPOC cross compiling environment =back -=head2 perlembed - how to embed perl in your C program +=item SUPPORT STATUS -=over +=item AUTHOR + +=item LAST UPDATE + +=back + +=head2 perlhpux, README.hpux - Perl version 5 on Hewlett-Packard Unix +(HP-UX) systems + +=over 4 =item DESCRIPTION -=over +=over 4 -=item PREAMBLE +=item Compiling Perl 5 on HP-UX -B<Use C from Perl?>, B<Use a Unix program from Perl?>, B<Use Perl from -Perl?>, B<Use C from C?>, B<Use Perl from C?> +=item PA-RISC -=item ROADMAP +=item PA-RISC 1.0 -=item Compiling your C program +=item PA-RISC 1.1 -=item Adding a Perl interpreter to your C program +=item PA-RISC 2.0 -=item Calling a Perl subroutine from your C program +=item Portability Between PA-RISC Versions -=item Evaluating a Perl statement from your C program +=item Building Dynamic Extensions on HP-UX -=item Performing Perl pattern matches and substitutions from your C program +=item The HP ANSI C Compiler -=item Fiddling with the Perl stack from your C program +=item Using Large Files with Perl -=item Maintaining a persistent interpreter +=item Threaded Perl -=item Maintaining multiple interpreter instances +=item 64-bit Perl -=item Using Perl modules, which themselves use C libraries, from your C -program +=item GDBM and Threads -=back +=item NFS filesystems and utime(2) -=item Embedding Perl under Win32 +=item perl -P and // -=item MORAL +=back =item AUTHOR -=item COPYRIGHT +=item DATE =back -=head2 perlapio - perl's IO abstraction interface. - -=over +=head2 perlmachten, README.machten - Perl version 5 on Power MachTen +systems -=item SYNOPSIS +=over 4 =item DESCRIPTION -B<PerlIO *>, B<PerlIO_stdin()>, B<PerlIO_stdout()>, B<PerlIO_stderr()>, -B<PerlIO_open(path, mode)>, B<PerlIO_fdopen(fd,mode)>, -B<PerlIO_printf(f,fmt,...)>, B<PerlIO_vprintf(f,fmt,a)>, -B<PerlIO_stdoutf(fmt,...)>, B<PerlIO_read(f,buf,count)>, -B<PerlIO_write(f,buf,count)>, B<PerlIO_close(f)>, B<PerlIO_puts(f,s)>, -B<PerlIO_putc(f,c)>, B<PerlIO_ungetc(f,c)>, B<PerlIO_getc(f)>, -B<PerlIO_eof(f)>, B<PerlIO_error(f)>, B<PerlIO_fileno(f)>, -B<PerlIO_clearerr(f)>, B<PerlIO_flush(f)>, B<PerlIO_tell(f)>, -B<PerlIO_seek(f,o,w)>, B<PerlIO_getpos(f,p)>, B<PerlIO_setpos(f,p)>, -B<PerlIO_rewind(f)>, B<PerlIO_tmpfile()> +=over 4 -=over +=item Compiling Perl 5 on MachTen -=item Co-existence with stdio +=item Failures during C<make test> -B<PerlIO_importFILE(f,flags)>, B<PerlIO_exportFILE(f,flags)>, -B<PerlIO_findFILE(f)>, B<PerlIO_releaseFILE(p,f)>, B<PerlIO_setlinebuf(f)>, -B<PerlIO_has_cntptr(f)>, B<PerlIO_get_ptr(f)>, B<PerlIO_get_cnt(f)>, -B<PerlIO_canset_cnt(f)>, B<PerlIO_fast_gets(f)>, -B<PerlIO_set_ptrcnt(f,p,c)>, B<PerlIO_set_cnt(f,c)>, B<PerlIO_has_base(f)>, -B<PerlIO_get_base(f)>, B<PerlIO_get_bufsiz(f)> +op/lexassign.t, pragma/warnings.t + +=item Building external modules =back +=item AUTHOR + +=item DATE + =back -=head2 perlxs - XS language reference manual +=head2 perlmacos, README.macos - Perl under Mac OS (Classic) + +=over 4 -=over +=item SYNOPSIS =item DESCRIPTION -=over +=item AUTHOR -=item Introduction +=item DATE -=item On The Road +=back -=item The Anatomy of an XSUB +=head2 perlmpeix, README.mpeix - Perl/iX for HP e3000 MPE -=item The Argument Stack +=head1 SYNOPSIS -=item The RETVAL Variable +=over 4 -=item The MODULE Keyword +=item What's New -=item The PACKAGE Keyword +=item System Requirements -=item The PREFIX Keyword +=item How to Obtain Perl/iX -=item The OUTPUT: Keyword +=item Distribution Contents Highlights -=item The CODE: Keyword +README, public_html/feedback.cgi, 4, 6 -=item The INIT: Keyword +=item Getting Started with Perl/iX -=item The NO_INIT Keyword +=item MPE/iX Implementation Considerations -=item Initializing Function Parameters +=item Change History -=item Default Parameter Values +=back -=item The PREINIT: Keyword +=head2 perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. -=item The SCOPE: Keyword +=over 4 -=item The INPUT: Keyword +=item SYNOPSIS -=item Variable-length Parameter Lists +=back -=item The C_ARGS: Keyword +=over 4 -=item The PPCODE: Keyword +=item DESCRIPTION -=item Returning Undef And Empty Lists +=over 4 -=item The REQUIRE: Keyword +=item Target -=item The CLEANUP: Keyword +=item Other OSes -=item The BOOT: Keyword +=item Prerequisites -=item The VERSIONCHECK: Keyword +EMX, RSX, HPFS, pdksh -=item The PROTOTYPES: Keyword +=item Starting Perl programs under OS/2 (and DOS and...) -=item The PROTOTYPE: Keyword +=item Starting OS/2 (and DOS) programs under Perl -=item The ALIAS: Keyword +=back -=item The INTERFACE: Keyword +=item Frequently asked questions -=item The INTERFACE_MACRO: Keyword +=over 4 -=item The INCLUDE: Keyword +=item "It does not work" -=item The CASE: Keyword +=item I cannot run external programs -=item The & Unary Operator +=item I cannot embed perl into my program, or use F<perl.dll> from my +program. -=item Inserting Comments and C Preprocessor Directives +Is your program EMX-compiled with C<-Zmt -Zcrtdll>?, Did you use +L<ExtUtils::Embed>? -=item Using XS With C++ +=item C<``> and pipe-C<open> do not work under DOS. -=item Interface Strategy +=item Cannot start C<find.exe "pattern" file> -=item Perl Objects And C Structures +=back -=item The Typemap +=item INSTALLATION -=back +=over 4 -=item EXAMPLES +=item Automatic binary installation -=item XS VERSION +C<PERL_BADLANG>, C<PERL_BADFREE>, F<Config.pm> -=item AUTHOR +=item Manual binary installation + +Perl VIO and PM executables (dynamically linked), Perl_ VIO executable +(statically linked), Executables for Perl utilities, Main Perl library, +Additional Perl modules, Tools to compile Perl modules, Manpages for Perl +and utilities, Manpages for Perl modules, Source for Perl documentation, +Perl manual in F<.INF> format, Pdksh + +=item B<Warning> =back -=head2 perlxstut, perlXStut - Tutorial for writing XSUBs +=item Accessing documentation -=over +=over 4 -=item DESCRIPTION +=item OS/2 F<.INF> file -=item SPECIAL NOTES +=item Plain text -=over +=item Manpages -=item make +=item HTML -=item Version caveat +=item GNU C<info> files -=item Dynamic Loading versus Static Loading +=item F<.PDF> files + +=item C<LaTeX> docs =back -=item TUTORIAL +=item BUILD -=over +=over 4 -=item EXAMPLE 1 +=item The short story -=item EXAMPLE 2 +=item Prerequisites -=item What has gone on? +=item Getting perl source -=item Writing good test scripts +=item Application of the patches -=item EXAMPLE 3 +=item Hand-editing -=item What's new here? +=item Making -=item Input and Output Parameters +=item Testing -=item The XSUBPP Program +A lot of C<bad free>, Process terminated by SIGTERM/SIGINT, F<op/fs.t>, +F<op/stat.t> -=item The TYPEMAP file +=item Installing the built perl -=item Warning about Output Arguments +=item C<a.out>-style build -=item EXAMPLE 4 +=back -=item What has happened here? +=item Build FAQ -=item Anatomy of .xs file +=over 4 -=item Getting the fat out of XSUBs +=item Some C</> became C<\> in pdksh. -=item More about XSUB arguments +=item C<'errno'> - unresolved external -=item The Argument Stack +=item Problems with tr or sed -=item Extending your Extension +=item Some problem (forget which ;-) -=item Documenting your Extension +=item Library ... not found -=item Installing your Extension +=item Segfault in make -=item EXAMPLE 5 +=item op/sprintf test failure -=item New Things in this Example +=back -=item EXAMPLE 6 (Coming Soon) +=item Specific (mis)features of OS/2 port -=item EXAMPLE 7 (Coming Soon) +=over 4 -=item EXAMPLE 8 (Coming Soon) +=item C<setpriority>, C<getpriority> -=item EXAMPLE 9 (Coming Soon) +=item C<system()> -=item Troubleshooting these Examples +=item C<extproc> on the first line -=back +=item Additional modules: -=item See also +=item Prebuilt methods: -=item Author +C<File::Copy::syscopy>, C<DynaLoader::mod2fname>, C<Cwd::current_drive()>, + C<Cwd::sys_chdir(name)>, C<Cwd::change_drive(name)>, +C<Cwd::sys_is_absolute(name)>, C<Cwd::sys_is_rooted(name)>, +C<Cwd::sys_is_relative(name)>, C<Cwd::sys_cwd(name)>, +C<Cwd::sys_abspath(name, dir)>, C<Cwd::extLibpath([type])>, +C<Cwd::extLibpath_set( path [, type ] )>, +C<OS2::Error(do_harderror,do_exception)>, C<OS2::Errors2Drive(drive)>, +OS2::SysInfo(), OS2::BootDrive(), C<OS2::MorphPM(serve)>, +C<OS2::UnMorphPM(serve)>, C<OS2::Serve_Messages(force)>, +C<OS2::Process_Messages(force [, cnt])>, C<OS2::_control87(new,mask)>, +OS2::get_control87(), C<OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)> -=over +=item Prebuilt variables: -=item Last Changed +$OS2::emx_rev, $OS2::emx_env, $OS2::os_ver -=back +=item Misfeatures -=back +=item Modifications -=head2 perlguts - Introduction to the Perl API +C<popen>, C<tmpnam>, C<tmpfile>, C<ctermid>, C<stat>, C<mkdir>, C<rmdir>, +C<flock> -=over +=item Identifying DLLs -=item DESCRIPTION +=item Centralized management of resources -=item Variables +C<HAB>, C<HMQ> -=over +=back -=item Datatypes +=item Perl flavors -=item What is an "IV"? +=over 4 -=item Working with SVs +=item F<perl.exe> -=item What's Really Stored in an SV? +=item F<perl_.exe> -=item Working with AVs +=item F<perl__.exe> -=item Working with HVs +=item F<perl___.exe> -=item Hash API Extensions +=item Why strange names? -=item References +=item Why dynamic linking? -=item Blessed References and Class Objects +=item Why chimera build? -=item Creating New Variables +=back -=item Reference Counts and Mortality +=item ENVIRONMENT -=item Stashes and Globs +=over 4 -=item Double-Typed SVs +=item C<PERLLIB_PREFIX> -=item Magic Variables +=item C<PERL_BADLANG> -=item Assigning Magic +=item C<PERL_BADFREE> -=item Magic Virtual Tables +=item C<PERL_SH_DIR> -=item Finding Magic +=item C<USE_PERL_FLOCK> -=item Understanding the Magic of Tied Hashes and Arrays +=item C<TMP> or C<TEMP> -=item Localizing changes +=back -C<SAVEINT(int i)>, C<SAVEIV(IV i)>, C<SAVEI32(I32 i)>, C<SAVELONG(long i)>, -C<SAVESPTR(s)>, C<SAVEPPTR(p)>, C<SAVEFREESV(SV *sv)>, C<SAVEFREEOP(OP -*op)>, C<SAVEFREEPV(p)>, C<SAVECLEARSV(SV *sv)>, C<SAVEDELETE(HV *hv, char -*key, I32 length)>, C<SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void -*p)>, C<SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)>, C<SAVESTACK_POS()>, -C<SV* save_scalar(GV *gv)>, C<AV* save_ary(GV *gv)>, C<HV* save_hash(GV -*gv)>, C<void save_item(SV *item)>, C<void save_list(SV **sarg, I32 -maxsarg)>, C<SV* save_svref(SV **sptr)>, C<void save_aptr(AV **aptr)>, -C<void save_hptr(HV **hptr)> +=item Evolution -=back +=over 4 -=item Subroutines +=item Priorities -=over +=item DLL name mangling -=item XSUBs and the Argument Stack +=item Threading -=item Calling Perl Routines from within C Programs +=item Calls to external programs -=item Memory Allocation +=item Memory allocation -=item PerlIO +=item Threads -=item Putting a C value on Perl stack +C<COND_WAIT>, F<os2.c> -=item Scratchpads +=back -=item Scratchpads and recursion +=back + +=over 4 + +=item AUTHOR + +=item SEE ALSO =back -=item Compiled code +=head2 perlos390, README.os390 - building and installing Perl for OS/390. -=over +=over 4 -=item Code tree +=item SYNOPSIS -=item Examining the tree +=item DESCRIPTION -=item Compile pass 1: check routines +=over 4 -=item Compile pass 1a: constant folding +=item Unpacking -=item Compile pass 2: context propagation +=item Setup and utilities -=item Compile pass 3: peephole optimization +=item Configure -=back +=item Build, test, install -=item How multiple interpreters and concurrency are supported +=item build anomalies -=over +=item testing anomalies -=item Background and PERL_IMPLICIT_CONTEXT +=item installation anomalies -=item How do I use all this in extensions? +=item Usage Hints -=item Future Plans and PERL_IMPLICIT_SYS +=item Floating point anomalies + +=item Modules and Extensions =back @@ -3676,234 +5887,297 @@ C<void save_hptr(HV **hptr)> =item SEE ALSO +=over 4 + +=item Mailing list + =back -=head2 perlcall - Perl calling conventions from C +=item HISTORY -=over +=back + +=head2 perlsolaris, README.solaris - Perl version 5 on Solaris systems + +=over 4 =item DESCRIPTION -An Error Handler, An Event Driven Program +=over 4 -=item THE CALL_ FUNCTIONS +=item Solaris Version Numbers. -call_sv, call_pv, call_method, call_argv +=back -=item FLAG VALUES +=item RESOURCES -=over +Solaris FAQ, Precompiled Binaries, Solaris Documentation -=item G_VOID +=item SETTING UP -=item G_SCALAR +=over 4 -=item G_ARRAY +=item File Extraction Problems. -=item G_DISCARD +=item Compiler and Related Tools. -=item G_NOARGS +=item Environment -=item G_EVAL +=back -=item G_KEEPERR +=item RUN CONFIGURE. -=item Determining the Context +=over 4 + +=item 64-bit Issues. + +=item Threads. + +=item Malloc Issues. =back -=item KNOWN PROBLEMS +=item MAKE PROBLEMS. -=item EXAMPLES +Dynamic Loading Problems With GNU as and GNU ld, ld.so.1: ./perl: fatal: +relocation error:, dlopen: stub interception failed, #error "No +DATAMODEL_NATIVE specified", sh: ar: not found -=over +=item MAKE TEST -=item No Parameters, Nothing returned +=over 4 -=item Passing Parameters +=item op/stat.t test 4 -=item Returning a Scalar +=back -=item Returning a list of values +=item PREBUILT BINARIES. -=item Returning a list in a scalar context +=item RUNTIME ISSUES. -=item Returning Data from Perl via the parameter list +=over 4 -=item Using G_EVAL +=item Limits on Numbers of Open Files. -=item Using G_KEEPERR +=back -=item Using call_sv +=item SOLARIS-SPECIFIC MODULES. -=item Using call_argv +=item SOLARIS-SPECIFIC PROBLEMS WITH MODULES. -=item Using call_method +=over 4 -=item Using GIMME_V +=item Proc::ProcessTable -=item Using Perl to dispose of temporaries +=item BSD::Resource -=item Strategies for storing Callback Context Information +=item Net::SSLeay -1. Ignore the problem - Allow only 1 callback, 2. Create a sequence of -callbacks - hard wired limit, 3. Use a parameter to map to the Perl -callback +=back -=item Alternate Stack Manipulation +=item AUTHOR -=item Creating and calling an anonymous subroutine in C +=item LAST MODIFIED + +=back + +=head2 perlvmesa, README.vmesa - building and installing Perl for VM/ESA. + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Unpacking + +=item Setup and utilities + +=item Configure + +Don't turn on the compiler optimization flag "-O". There's a bug in the +compiler (APAR PQ18812) that generates some bad code the optimizer is on, +As VM/ESA doesn't fully support the fork() API programs relying on this +call will not work. I've replaced fork()/exec() with spawn() and the +standalone exec() with spawn(). This has a side effect when opening unnamed +pipes in a shell script: there is no child process generated under + +=item testing anomalies + +=item Usage Hints + +When using perl on VM/ESA please keep in mind that the EBCDIC and ASCII +character sets are different. Perl builtin functions that may behave +differently under EBCDIC are mentioned in the perlport.pod document. =back +=item AUTHORS + =item SEE ALSO -=item AUTHOR +=over 4 -=item DATE +=item Mailing list =back -=head2 perlcompile - Introduction to the Perl Compiler-Translator +=back -=over +=head2 perlvms - VMS-specific documentation for Perl + +=over 4 =item DESCRIPTION -=over +=item Installation -=item Layout +=item Organization of Perl Images -B::Bytecode, B::C, B::CC, B::Lint, B::Deparse, B::Xref +=over 4 + +=item Core Images + +=item Perl Extensions + +=item Installing static extensions + +=item Installing dynamic extensions =back -=item Using The Back Ends +=item File specifications -=over +=over 4 -=item The Cross Referencing Back End +=item Syntax -i, &, s, r +=item Wildcard expansion -=item The Decompiling Back End +=item Pipes -=item The Lint Back End +=back -=item The Simple C Back End +=item PERL5LIB and PERLLIB -=item The Bytecode Back End +=item Command line -=item The Optimized C Back End +=over 4 -B, O, B::Asmdata, B::Assembler, B::Bblock, B::Bytecode, B::C, B::CC, -B::Debug, B::Deparse, B::Disassembler, B::Lint, B::Showlex, B::Stackobj, -B::Stash, B::Terse, B::Xref +=item I/O redirection and backgrounding + +=item Command line switches + +-i, -S, -u =back -=item KNOWN PROBLEMS +=item Perl functions + +File tests, backticks, binmode FILEHANDLE, crypt PLAINTEXT, USER, dump, +exec LIST, fork, getpwent, getpwnam, getpwuid, gmtime, kill, qx//, select +(system call), stat EXPR, system LIST, time, times, unlink LIST, utime +LIST, waitpid PID,FLAGS + +=item Perl variables + +%ENV, CRTL_ENV, CLISYM_[LOCAL], Any other string, $!, $^E, $?, $^S, $| + +=item Standard modules with VMS-specific differences + +=over 4 + +=item SDBM_File + +=back + +=item Revision date =item AUTHOR =back -=head2 perlapi - autogenerated documentation for the perl public API +=head2 perlvos, README.vos - Perl for Stratus VOS -=over +=over 4 -=item DESCRIPTION +=item SYNOPSIS -AvFILL, av_clear, av_extend, av_fetch, av_len, av_make, av_pop, av_push, -av_shift, av_store, av_undef, av_unshift, call_argv, call_method, call_pv, -call_sv, CLASS, Copy, croak, CvSTASH, dMARK, dORIGMARK, dSP, dXSARGS, -dXSI32, ENTER, eval_pv, eval_sv, EXTEND, fbm_compile, fbm_instr, FREETMPS, -get_av, get_cv, get_hv, get_sv, GIMME, GIMME_V, GvSV, gv_fetchmeth, -gv_fetchmethod, gv_fetchmethod_autoload, gv_stashpv, gv_stashsv, G_ARRAY, -G_DISCARD, G_EVAL, G_NOARGS, G_SCALAR, G_VOID, HEf_SVKEY, HeHASH, HeKEY, -HeKLEN, HePV, HeSVKEY, HeSVKEY_force, HeSVKEY_set, HeVAL, HvNAME, hv_clear, -hv_delete, hv_delete_ent, hv_exists, hv_exists_ent, hv_fetch, hv_fetch_ent, -hv_iterinit, hv_iterkey, hv_iterkeysv, hv_iternext, hv_iternextsv, -hv_iterval, hv_magic, hv_store, hv_store_ent, hv_undef, isALNUM, isALPHA, -isDIGIT, isLOWER, isSPACE, isUPPER, items, ix, LEAVE, looks_like_number, -MARK, mg_clear, mg_copy, mg_find, mg_free, mg_get, mg_length, mg_magical, -mg_set, Move, New, newAV, Newc, newCONSTSUB, newHV, newRV_inc, newRV_noinc, -NEWSV, newSViv, newSVnv, newSVpv, newSVpvf, newSVpvn, newSVrv, newSVsv, -newSVuv, newXS, newXSproto, Newz, Nullav, Nullch, Nullcv, Nullhv, Nullsv, -ORIGMARK, perl_alloc, perl_construct, perl_destruct, perl_free, perl_parse, -perl_run, PL_DBsingle, PL_DBsub, PL_DBtrace, PL_dowarn, PL_modglobal, -PL_na, PL_sv_no, PL_sv_undef, PL_sv_yes, POPi, POPl, POPn, POPp, POPs, -PUSHi, PUSHMARK, PUSHn, PUSHp, PUSHs, PUSHu, PUTBACK, Renew, Renewc, -require_pv, RETVAL, Safefree, savepv, savepvn, SAVETMPS, SP, SPAGAIN, ST, -strEQ, strGE, strGT, strLE, strLT, strNE, strnEQ, strnNE, StructCopy, -SvCUR, SvCUR_set, SvEND, SvGETMAGIC, SvGROW, SvIOK, SvIOKp, SvIOK_off, -SvIOK_on, SvIOK_only, SvIV, SvIVX, SvLEN, SvNIOK, SvNIOKp, SvNIOK_off, -SvNOK, SvNOKp, SvNOK_off, SvNOK_on, SvNOK_only, SvNV, SvNVX, SvOK, SvOOK, -SvPOK, SvPOKp, SvPOK_off, SvPOK_on, SvPOK_only, SvPV, SvPVX, SvPV_force, -SvPV_nolen, SvREFCNT, SvREFCNT_dec, SvREFCNT_inc, SvROK, SvROK_off, -SvROK_on, SvRV, SvSETMAGIC, SvSetSV, SvSetSV_nosteal, SvSTASH, SvTAINT, -SvTAINTED, SvTAINTED_off, SvTAINTED_on, SvTRUE, SvTYPE, svtype, SVt_IV, -SVt_NV, SVt_PV, SVt_PVAV, SVt_PVCV, SVt_PVHV, SVt_PVMG, SvUPGRADE, SvUV, -SvUVX, sv_2mortal, sv_bless, sv_catpv, sv_catpvf, sv_catpvf_mg, sv_catpvn, -sv_catpvn_mg, sv_catpv_mg, sv_catsv, sv_catsv_mg, sv_chop, sv_cmp, sv_dec, -sv_derived_from, sv_eq, sv_grow, sv_inc, sv_insert, sv_isa, sv_isobject, -sv_len, sv_magic, sv_mortalcopy, sv_newmortal, sv_setiv, sv_setiv_mg, -sv_setnv, sv_setnv_mg, sv_setpv, sv_setpvf, sv_setpvf_mg, sv_setpviv, -sv_setpviv_mg, sv_setpvn, sv_setpvn_mg, sv_setpv_mg, sv_setref_iv, -sv_setref_nv, sv_setref_pv, sv_setref_pvn, sv_setsv, sv_setsv_mg, sv_setuv, -sv_setuv_mg, sv_unref, sv_upgrade, sv_usepvn, sv_usepvn_mg, sv_vcatpvfn, -sv_vsetpvfn, THIS, toLOWER, toUPPER, warn, XPUSHi, XPUSHn, XPUSHp, XPUSHs, -XPUSHu, XS, XSRETURN, XSRETURN_EMPTY, XSRETURN_IV, XSRETURN_NO, -XSRETURN_NV, XSRETURN_PV, XSRETURN_UNDEF, XSRETURN_YES, XST_mIV, XST_mNO, -XST_mNV, XST_mPV, XST_mUNDEF, XST_mYES, XS_VERSION, XS_VERSION_BOOTCHECK, -Zero +=over 4 -=item AUTHORS +=item Stratus POSIX Support -=item SEE ALSO +=back + +=item INSTALLING PERL IN VOS + +=over 4 + +=item Compiling Perl 5 on VOS + +=item Installing Perl 5 on VOS =back -=head2 perlintern - autogenerated documentation of purely B<internal> - Perl functions +=item USING PERL IN VOS -=over +=over 4 -=item DESCRIPTION +=item Unimplemented Features -=item AUTHORS +=item Restrictions -=item SEE ALSO +=back + +=item SUPPORT STATUS + +=item AUTHOR + +=item LAST UPDATE =back -=head2 perlhist - the Perl history records +=head2 perlwin32 - Perl under Win32 -=over +=over 4 + +=item SYNOPSIS =item DESCRIPTION -=item INTRODUCTION +=over 4 -=item THE KEEPERS OF THE PUMPKIN +=item Setting Up -=over +Make, Command Shell, Borland C++, Microsoft Visual C++, Mingw32 with GCC -=item PUMPKIN? - -=back +=item Building -=item THE RECORDS +=item Testing -=over +=item Installation -=item SELECTED RELEASE SIZES +=item Usage Hints -=item SELECTED PATCH SIZES +Environment Variables, File Globbing, Using perl from the command line, +Building Extensions, Command-line Wildcard Expansion, Win32 Specific +Extensions, Running Perl Scripts, Miscellaneous Things =back -=item THE KEEPERS OF THE RECORDS +=item BUGS AND CAVEATS + +=item AUTHORS + +Gary Ng E<lt>71564.1743@CompuServe.COME<gt>, Gurusamy Sarathy +E<lt>gsar@activestate.comE<gt>, Nick Ing-Simmons +E<lt>nick@ni-s.u-net.comE<gt> + +=item SEE ALSO + +=item HISTORY =back @@ -3911,7 +6185,7 @@ Zero =head2 attrs - set/get attributes of a subroutine (deprecated) -=over +=over 4 =item SYNOPSIS @@ -3923,7 +6197,7 @@ method, locked =head2 re - Perl pragma to alter regular expression behaviour -=over +=over 4 =item SYNOPSIS @@ -3933,13 +6207,13 @@ method, locked =head2 attributes - get/set subroutine or variable attributes -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Built-in Attributes @@ -3959,7 +6233,7 @@ FETCH_I<type>_ATTRIBUTES, MODIFY_I<type>_ATTRIBUTES =item EXPORTS -=over +=over 4 =item Default exports @@ -3977,7 +6251,7 @@ FETCH_I<type>_ATTRIBUTES, MODIFY_I<type>_ATTRIBUTES =head2 attrs - set/get attributes of a subroutine (deprecated) -=over +=over 4 =item SYNOPSIS @@ -3989,7 +6263,7 @@ method, locked =head2 autouse - postpone load of modules until a function is used -=over +=over 4 =item SYNOPSIS @@ -4005,7 +6279,7 @@ method, locked =head2 base - Establish IS-A relationship with base class at compile time -=over +=over 4 =item SYNOPSIS @@ -4019,7 +6293,7 @@ method, locked =head2 blib - Use MakeMaker's uninstalled version of a package -=over +=over 4 =item SYNOPSIS @@ -4034,7 +6308,7 @@ method, locked =head2 bytes - Perl pragma to force byte semantics rather than character semantics -=over +=over 4 =item SYNOPSIS @@ -4047,7 +6321,7 @@ semantics =head2 charnames - define character names for C<\N{named}> string literal escape. -=over +=over 4 =item SYNOPSIS @@ -4061,7 +6335,7 @@ escape. =head2 constant - Perl pragma to declare constants -=over +=over 4 =item SYNOPSIS @@ -4082,13 +6356,13 @@ escape. =head2 diagnostics - Perl compiler pragma to force verbose warning diagnostics -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item The C<diagnostics> Pragma @@ -4108,7 +6382,7 @@ diagnostics =head2 fields - compile-time class fields -=over +=over 4 =item SYNOPSIS @@ -4122,13 +6396,13 @@ new, phash =head2 filetest - Perl pragma to control the filetest permission operators -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item subpragma access @@ -4136,10 +6410,10 @@ new, phash =back -=head2 integer - Perl pragma to compute arithmetic in integer instead of -double +=head2 integer - Perl pragma to use integer arithmetic instead of floating +point -=over +=over 4 =item SYNOPSIS @@ -4149,7 +6423,7 @@ double =head2 less - perl pragma to request less of something from the compiler -=over +=over 4 =item SYNOPSIS @@ -4159,13 +6433,13 @@ double =head2 lib - manipulate @INC at compile time -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Adding directories to @INC @@ -4184,7 +6458,7 @@ double =head2 locale - Perl pragma to use and avoid POSIX locales for built-in operations -=over +=over 4 =item SYNOPSIS @@ -4194,7 +6468,7 @@ operations =head2 open - perl pragma to set default disciplines for input and output -=over +=over 4 =item SYNOPSIS @@ -4208,7 +6482,7 @@ operations =head2 ops - Perl pragma to restrict unsafe operations when compiling -=over +=over 4 =item SYNOPSIS @@ -4220,13 +6494,13 @@ operations =head2 overload - Package for overloading perl operations -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Declaration of overloaded functions @@ -4255,11 +6529,11 @@ is inherited by derived classes =item SPECIAL SYMBOLS FOR C<use overload> -=over +=over 4 =item Last Resort -=item Fallback +=item Fallback C<undef>, TRUE, defined, but FALSE @@ -4294,7 +6568,7 @@ integer, float, binary, q, qr =item Cookbook -=over +=over 4 =item Two-face scalars @@ -4310,13 +6584,16 @@ integer, float, binary, q, qr =item DIAGNOSTICS +Odd number of arguments for overload::constant, `%s' is not an overloadable +type, `%s' is not a code reference + =item BUGS =back =head2 re - Perl pragma to alter regular expression behaviour -=over +=over 4 =item SYNOPSIS @@ -4326,7 +6603,7 @@ integer, float, binary, q, qr =head2 sigtrap - Perl pragma to enable simple signal handling -=over +=over 4 =item SYNOPSIS @@ -4334,7 +6611,7 @@ integer, float, binary, q, qr =item OPTIONS -=over +=over 4 =item SIGNAL HANDLERS @@ -4356,7 +6633,7 @@ B<untrapped>, B<any>, I<signal>, I<number> =head2 strict - Perl pragma to restrict unsafe constructs -=over +=over 4 =item SYNOPSIS @@ -4368,7 +6645,7 @@ C<strict refs>, C<strict vars>, C<strict subs> =head2 subs - Perl pragma to predeclare sub names -=over +=over 4 =item SYNOPSIS @@ -4378,7 +6655,7 @@ C<strict refs>, C<strict vars>, C<strict subs> =head2 utf8 - Perl pragma to enable/disable UTF-8 in source code -=over +=over 4 =item SYNOPSIS @@ -4390,7 +6667,7 @@ C<strict refs>, C<strict vars>, C<strict subs> =head2 vars - Perl pragma to predeclare global variable names (obsolete) -=over +=over 4 =item SYNOPSIS @@ -4400,28 +6677,33 @@ C<strict refs>, C<strict vars>, C<strict subs> =head2 warnings - Perl pragma to control optional warnings -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -use warnings::register, warnings::enabled([$category]), -warnings::warn([$category,] $message) +use warnings::register, warnings::enabled(), warnings::enabled($category), +warnings::enabled($object), warnings::warn($message), +warnings::warn($category, $message), warnings::warn($object, $message), +warnings::warnif($message), warnings::warnif($category, $message), +warnings::warnif($object, $message) =back +=head2 warnings::register - warnings import function + =head1 MODULE DOCUMENTATION =head2 AnyDBM_File - provide framework for multiple DBMs -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item DBM Comparisons @@ -4435,13 +6717,13 @@ warnings::warn([$category,] $message) =head2 AutoLoader - load subroutines only on demand -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Subroutine Stubs @@ -4451,6 +6733,8 @@ warnings::warn([$category,] $message) =item Package Lexicals +=item Not Using AutoLoader + =item B<AutoLoader> vs. B<SelfLoader> =back @@ -4463,7 +6747,7 @@ warnings::warn([$category,] $message) =head2 AutoSplit - split a package for autoloading -=over +=over 4 =item SYNOPSIS @@ -4471,7 +6755,7 @@ warnings::warn([$category,] $message) $keep, $check, $modtime -=over +=over 4 =item Multiple packages @@ -4483,7 +6767,7 @@ $keep, $check, $modtime =head2 B - The Perl Compiler -=over +=over 4 =item SYNOPSIS @@ -4491,7 +6775,7 @@ $keep, $check, $modtime =item OVERVIEW OF CLASSES -=over +=over 4 =item SV-RELATED CLASSES @@ -4501,7 +6785,7 @@ REFCNT, FLAGS =item B::IV METHODS -IV, IVX, needs64bits, packiv +IV, IVX, UVX, int_value, needs64bits, packiv =item B::NV METHODS @@ -4513,7 +6797,7 @@ RV =item B::PV METHODS -PV +PV, PVX =item B::PVMG METHODS @@ -4533,8 +6817,8 @@ USEFUL, PREVIOUS, RARE, TABLE =item B::GV METHODS -is_empty, NAME, STASH, SV, IO, FORM, AV, HV, EGV, CV, CVGEN, LINE, FILE, -FILEGV, GvREFCNT, FLAGS +is_empty, NAME, SAFENAME, STASH, SV, IO, FORM, AV, HV, EGV, CV, CVGEN, +LINE, FILE, FILEGV, GvREFCNT, FLAGS =item B::IO METHODS @@ -4616,7 +6900,7 @@ hash(STR), cast_I32(I), minus_c, cstring(STR), class(OBJ), threadsv_names =head2 B::Asmdata - Autogenerated data about Perl ops, used to generate bytecode -=over +=over 4 =item SYNOPSIS @@ -4628,19 +6912,19 @@ bytecode =head2 B::Assembler - Assemble Perl bytecode -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=item AUTHOR +=item AUTHORS =back =head2 B::Bblock - Walk basic blocks -=over +=over 4 =item SYNOPSIS @@ -4652,7 +6936,7 @@ bytecode =head2 B::Bytecode - Perl compiler's bytecode backend -=over +=over 4 =item SYNOPSIS @@ -4661,20 +6945,21 @@ bytecode =item OPTIONS B<-ofilename>, B<-afilename>, B<-->, B<-f>, B<-fcompress-nullops>, -B<-fomit-sequence-numbers>, B<-fbypass-nullops>, B<-fstrip-syntax-tree>, -B<-On>, B<-D>, B<-Do>, B<-Db>, B<-Da>, B<-DC>, B<-S>, B<-m> +B<-fomit-sequence-numbers>, B<-fbypass-nullops>, B<-On>, B<-D>, B<-Do>, +B<-Db>, B<-Da>, B<-DC>, B<-S>, B<-upackage> Stores package in the +output. =back =item EXAMPLES =item BUGS -=item AUTHOR +=item AUTHORS =back =head2 B::C - Perl compiler's C backend -=over +=over 4 =item SYNOPSIS @@ -4695,7 +6980,7 @@ B<-DC>, B<-DM>, B<-f>, B<-fcog>, B<-fno-cog>, B<-On>, B<-llimit> =head2 B::CC - Perl compiler's optimized C translation backend -=over +=over 4 =item SYNOPSIS @@ -4713,7 +6998,7 @@ B<-ffreetmps-each-bblock>, B<-ffreetmps-each-loop>, B<-fomit-taint>, B<-On> =item DIFFERENCES -=over +=over 4 =item Loops @@ -4729,9 +7014,48 @@ B<-ffreetmps-each-bblock>, B<-ffreetmps-each-loop>, B<-fomit-taint>, B<-On> =back +=head2 B::Concise - Walk Perl syntax tree, printing concise info about ops + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item OPTIONS + +B<-basic>, B<-exec>, B<-tree>, B<-compact>, B<-loose>, B<-vt>, B<-ascii>, +B<-main>, B<-base>I<n>, B<-bigendian>, B<-littleendian>, B<-concise>, +B<-terse>, B<-linenoise>, B<-debug>, B<-env> + +=item FORMATTING SPECIFICATIONS + +B<(x(>I<exec_text>B<;>I<basic_text>B<)x)>, B<(*(>I<text>B<)*)>, +B<(*(>I<text1>B<;>I<text2>B<)*)>, B<(?(>I<text1>B<#>I<var>I<Text2>B<)?)>, +B<#>I<var>, B<#>I<var>I<N>, B<~>, B<#addr>, B<#arg>, B<#class>, +B<#classym>, B<#coplabel>, B<#exname>, B<#extarg>, B<#firstaddr>, +B<#flags>, B<#flagval>, B<#hyphenseq>, B<#label>, B<#lastaddr>, B<#name>, +B<#NAME>, B<#next>, B<#nextaddr>, B<#noise>, B<#private>, B<#privval>, +B<#seq>, B<#seqnum>, B<#sibaddr>, B<#svaddr>, B<#svclass>, B<#svval>, +B<#targ>, B<#targarg>, B<#targarglife>, B<#typenum> + +=item ABBREVIATIONS + +=over 4 + +=item OP flags abbreviations + +=item OP class abbreviations + +=back + +=item AUTHOR + +=back + =head2 B::Debug - Walk Perl syntax tree, printing debug info about ops -=over +=over 4 =item SYNOPSIS @@ -4743,7 +7067,7 @@ B<-ffreetmps-each-bblock>, B<-ffreetmps-each-loop>, B<-fomit-taint>, B<-On> =head2 B::Deparse - Perl compiler backend to produce perl code -=over +=over 4 =item SYNOPSIS @@ -4752,11 +7076,11 @@ B<-ffreetmps-each-bblock>, B<-ffreetmps-each-loop>, B<-fomit-taint>, B<-On> =item OPTIONS B<-l>, B<-p>, B<-q>, B<-u>I<PACKAGE>, B<-s>I<LETTERS>, B<C>, B<i>I<NUMBER>, -B<T>, B<v>I<STRING>B<.> +B<T>, B<v>I<STRING>B<.>, B<-x>I<LEVEL> =item USING B::Deparse AS A MODULE -=over +=over 4 =item Synopsis @@ -4776,7 +7100,7 @@ B<T>, B<v>I<STRING>B<.> =head2 B::Disassembler - Disassemble Perl bytecode -=over +=over 4 =item SYNOPSIS @@ -4788,7 +7112,7 @@ B<T>, B<v>I<STRING>B<.> =head2 B::Lint - Perl lint -=over +=over 4 =item SYNOPSIS @@ -4811,7 +7135,7 @@ B<-u Package> =head2 B::O, O - Generic interface to Perl Compiler backends -=over +=over 4 =item SYNOPSIS @@ -4827,7 +7151,7 @@ B<-u Package> =head2 B::Showlex - Show lexical variables used in functions or files -=over +=over 4 =item SYNOPSIS @@ -4839,7 +7163,7 @@ B<-u Package> =head2 B::Stackobj - Helper module for CC backend -=over +=over 4 =item SYNOPSIS @@ -4849,9 +7173,11 @@ B<-u Package> =back +=head2 B::Stash - show what stashes are loaded + =head2 B::Terse - Walk Perl syntax tree, printing terse info about ops -=over +=over 4 =item SYNOPSIS @@ -4863,7 +7189,7 @@ B<-u Package> =head2 B::Xref - Generates cross reference reports for Perl programs -=over +=over 4 =item SYNOPSIS @@ -4881,7 +7207,7 @@ C<-oFILENAME>, C<-r>, C<-D[tO]> =head2 Bblock, B::Bblock - Walk basic blocks -=over +=over 4 =item SYNOPSIS @@ -4893,13 +7219,13 @@ C<-oFILENAME>, C<-r>, C<-D[tO]> =head2 Benchmark - benchmark running times of Perl code -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Methods @@ -4937,7 +7263,7 @@ STYLE ] ), cmpthese ( RESULTSHASHREF ), countit(TIME, CODE), disablecache ( =head2 ByteLoader - load byte compiled perl code -=over +=over 4 =item SYNOPSIS @@ -4951,7 +7277,7 @@ STYLE ] ), cmpthese ( RESULTSHASHREF ), countit(TIME, CODE), disablecache ( =head2 Bytecode, B::Bytecode - Perl compiler's bytecode backend -=over +=over 4 =item SYNOPSIS @@ -4960,20 +7286,21 @@ STYLE ] ), cmpthese ( RESULTSHASHREF ), countit(TIME, CODE), disablecache ( =item OPTIONS B<-ofilename>, B<-afilename>, B<-->, B<-f>, B<-fcompress-nullops>, -B<-fomit-sequence-numbers>, B<-fbypass-nullops>, B<-fstrip-syntax-tree>, -B<-On>, B<-D>, B<-Do>, B<-Db>, B<-Da>, B<-DC>, B<-S>, B<-m> +B<-fomit-sequence-numbers>, B<-fbypass-nullops>, B<-On>, B<-D>, B<-Do>, +B<-Db>, B<-Da>, B<-DC>, B<-S>, B<-upackage> Stores package in the +output. =back =item EXAMPLES =item BUGS -=item AUTHOR +=item AUTHORS =back =head2 CGI - Simple Common Gateway Interface Class -=over +=over 4 =item SYNOPSIS @@ -4981,16 +7308,12 @@ B<-On>, B<-D>, B<-Do>, B<-Db>, B<-Da>, B<-DC>, B<-S>, B<-m> =item DESCRIPTION -=over +=over 4 =item PROGRAMMING STYLE =item CALLING CGI.PM ROUTINES -1. Use another name for the argument, if one is available. Forexample, --value is an alias for -values, 2. Change the capitalization, e.g. -Values, -3. Put quotes around the argument name, e.g. '-values' - =item CREATING A NEW QUERY OBJECT (OBJECT-ORIENTED STYLE): =item CREATING A NEW QUERY OBJECT FROM AN INPUT FILE @@ -5026,8 +7349,8 @@ B<:standard>, B<:all> =item PRAGMAS --any, -compile, -nph, -newstyle_urls, -autoload, -no_debug, --private_tempfiles +-any, -compile, -nosticky, -no_xhtml, -nph, -newstyle_urls, -oldstyle_urls, +-autoload, -no_debug, -debug, -private_tempfiles =item SPECIAL FORMS FOR IMPORTING HTML-TAG FUNCTIONS @@ -5039,7 +7362,7 @@ a </UL> tag) =item GENERATING DYNAMIC DOCUMENTS -=over +=over 4 =item CREATING A STANDARD HTTP HEADER: @@ -5056,7 +7379,7 @@ B<Parameters:>, 4, 5, 6.. =item OBTAINING THE SCRIPT'S URL B<-absolute>, B<-relative>, B<-full>, B<-path> (B<-path_info>), B<-query> -(B<-query_string>) +(B<-query_string>), B<-base> =item MIXING POST AND URL PARAMETERS @@ -5064,7 +7387,7 @@ B<-absolute>, B<-relative>, B<-full>, B<-path> (B<-path_info>), B<-query> =item CREATING STANDARD HTML ELEMENTS: -=over +=over 4 =item PROVIDING ARGUMENTS TO HTML SHORTCUTS @@ -5074,13 +7397,18 @@ B<-absolute>, B<-relative>, B<-full>, B<-path> (B<-path_info>), B<-query> =item NON-STANDARD HTML SHORTCUTS +=item AUTOESCAPING HTML + +$escaped_string = escapeHTML("unescaped string");, $charset = +charset([$charset]);, $flag = autoEscape([$flag]); + =item PRETTY-PRINTING HTML =back =item CREATING FILL-OUT FORMS: -=over +=over 4 =item CREATING AN ISINDEX TAG @@ -5132,9 +7460,7 @@ B<Parameters:> =item CREATING A CLICKABLE IMAGE BUTTON -B<Parameters:>, 3.The third option (-align, optional) is an alignment type, -and may be -TOP, BOTTOM or MIDDLE +B<Parameters:> =item CREATING A JAVASCRIPT ACTION BUTTON @@ -5155,7 +7481,7 @@ the <FORM> tag =item DEBUGGING -=over +=over 4 =item DUMPING OUT ALL THE NAME/VALUE PAIRS @@ -5164,20 +7490,19 @@ the <FORM> tag =item FETCHING ENVIRONMENT VARIABLES B<Accept()>, B<raw_cookie()>, B<user_agent()>, B<path_info()>, -B<path_translated()>, B<remote_host()>, B<script_name()>Return the script -name as a partial URL, for self-refering -scripts, B<referer()>, B<auth_type ()>, B<server_name ()>, B<virtual_host -()>, B<server_software ()>, B<remote_user ()>, B<user_name ()>, +B<path_translated()>, B<remote_host()>, B<script_name()>, B<referer()>, +B<auth_type ()>, B<server_name ()>, B<virtual_host ()>, B<server_port ()>, +B<server_software ()>, B<remote_user ()>, B<user_name ()>, B<request_method()>, B<content_type()>, B<http()>, B<https()> =item USING NPH SCRIPTS In the B<use> statement, By calling the B<nph()> method:, By using B<-nph> -parameters in the B<header()> and B<redirect()> statements: +parameters =item Server Push -multipart_init(), multipart_start(), multipart_end() +multipart_init(), multipart_start(), multipart_end(), multipart_final() =item Avoiding Denial of Service Attacks @@ -5213,7 +7538,7 @@ MacEachern (dougm@opengroup.org), Robin Houston (robin@oneworld.org), =head2 CGI::Apache - Backward compatibility module for CGI.pm -=over +=over 4 =item SYNOPSIS @@ -5232,7 +7557,7 @@ MacEachern (dougm@opengroup.org), Robin Houston (robin@oneworld.org), =head2 CGI::Carp, B<CGI::Carp> - CGI routines for writing to the HTTPD (or other) error log -=over +=over 4 =item SYNOPSIS @@ -5242,12 +7567,14 @@ other) error log =item MAKING PERL ERRORS APPEAR IN THE BROWSER WINDOW -=over +=over 4 =item Changing the default message =back +=item MAKING WARNINGS APPEAR AS HTML COMMENTS + =item CHANGE LOG =item AUTHORS @@ -5258,7 +7585,7 @@ other) error log =head2 CGI::Cookie - Interface to Netscape Cookies -=over +=over 4 =item SYNOPSIS @@ -5268,7 +7595,7 @@ other) error log B<1. expiration date>, B<2. domain>, B<3. path>, B<4. secure flag> -=over +=over 4 =item Creating New Cookies @@ -5292,7 +7619,7 @@ B<name()>, B<value()>, B<domain()>, B<path()>, B<expires()> =head2 CGI::Fast - CGI Interface for Fast CGI -=over +=over 4 =item SYNOPSIS @@ -5318,13 +7645,13 @@ B<name()>, B<value()>, B<domain()>, B<path()>, B<expires()> =head2 CGI::Pretty - module to produce nicely formatted HTML code -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Tags that won't be formatted @@ -5342,7 +7669,7 @@ B<name()>, B<value()>, B<domain()>, B<path()>, B<expires()> =head2 CGI::Push - Simple Interface to Server Push -=over +=over 4 =item SYNOPSIS @@ -5350,9 +7677,9 @@ B<name()>, B<value()>, B<domain()>, B<path()>, B<expires()> =item USING CGI::Push --next_page, -last_page, -type, -delay, -cookie, -target, -expires +-next_page, -last_page, -type, -delay, -cookie, -target, -expires, -nph -=over +=over 4 =item Heterogeneous Pages @@ -5372,7 +7699,7 @@ B<name()>, B<value()>, B<domain()>, B<path()>, B<expires()> =head2 CGI::Switch - Backward compatibility module for defunct CGI::Switch -=over +=over 4 =item SYNOPSIS @@ -5388,21 +7715,35 @@ B<name()>, B<value()>, B<domain()>, B<path()>, B<expires()> =back +=head2 CGI::Util - Internal utilities used by CGI module + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item AUTHOR INFORMATION + +=item SEE ALSO + +=back + =head2 CPAN - query, download and build perl modules from CPAN sites -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Interactive Mode Searching for authors, bundles, distribution files and modules, make, test, install, clean modules or distributions, get, readme, look module or -distribution, Signals +distribution, ls author, Signals =item CPAN::Shell @@ -5412,11 +7753,38 @@ distribution, Signals =item The four C<CPAN::*> Classes: Author, Bundle, Module, Distribution -=item ProgrammerE<39>s interface - -expand($type,@things), Programming Examples - -=item Methods in the four Classes +=item Programmer's interface + +expand($type,@things), expandany(@things), Programming Examples + +=item Methods in the other Classes + +CPAN::Author::as_glimpse(), CPAN::Author::as_string(), +CPAN::Author::email(), CPAN::Author::fullname(), CPAN::Author::name(), +CPAN::Bundle::as_glimpse(), CPAN::Bundle::as_string(), +CPAN::Bundle::clean(), CPAN::Bundle::contains(), +CPAN::Bundle::force($method,@args), CPAN::Bundle::get(), +CPAN::Bundle::inst_file(), CPAN::Bundle::inst_version(), +CPAN::Bundle::uptodate(), CPAN::Bundle::install(), CPAN::Bundle::make(), +CPAN::Bundle::readme(), CPAN::Bundle::test(), +CPAN::Distribution::as_glimpse(), CPAN::Distribution::as_string(), +CPAN::Distribution::clean(), CPAN::Distribution::containsmods(), +CPAN::Distribution::cvs_import(), CPAN::Distribution::dir(), +CPAN::Distribution::force($method,@args), CPAN::Distribution::get(), +CPAN::Distribution::install(), CPAN::Distribution::isa_perl(), +CPAN::Distribution::look(), CPAN::Distribution::make(), +CPAN::Distribution::prereq_pm(), CPAN::Distribution::readme(), +CPAN::Distribution::test(), CPAN::Distribution::uptodate(), +CPAN::Index::force_reload(), CPAN::Index::reload(), CPAN::InfoObj::dump(), +CPAN::Module::as_glimpse(), CPAN::Module::as_string(), +CPAN::Module::clean(), CPAN::Module::cpan_file(), +CPAN::Module::cpan_version(), CPAN::Module::cvs_import(), +CPAN::Module::description(), CPAN::Module::force($method,@args), +CPAN::Module::get(), CPAN::Module::inst_file(), +CPAN::Module::inst_version(), CPAN::Module::install(), +CPAN::Module::look(), CPAN::Module::make(), +CPAN::Module::manpage_headline(), CPAN::Module::readme(), +CPAN::Module::test(), CPAN::Module::uptodate(), CPAN::Module::userid() =item Cache Manager @@ -5439,7 +7807,7 @@ E<lt>valueE<gt>>, C<o conf E<lt>list optionE<gt>>, C<o conf E<lt>list optionE<gt> [shift|pop]>, C<o conf E<lt>list optionE<gt> [unshift|push|splice] E<lt>listE<gt>> -=over +=over 4 =item Note on urllist parameter's format @@ -5455,19 +7823,33 @@ optionE<gt> [shift|pop]>, C<o conf E<lt>list optionE<gt> =item WORKING WITH CPAN.pm BEHIND FIREWALLS +=over 4 + +=item Three basic types of firewalls + http firewall, ftp firewall, One way visibility, SOCKS, IP Masquerade +=item Configuring lynx or ncftp for going through a firewall + +=back + +=item FAQ + +1), 2), 3), 4), 5), 6), 7), 8), 9), 10) + =item BUGS =item AUTHOR +=item TRANSLATIONS + =item SEE ALSO =back =head2 CPAN::FirstTime - Utility for CPAN::Config file Initialization -=over +=over 4 =item SYNOPSIS @@ -5478,7 +7860,7 @@ http firewall, ftp firewall, One way visibility, SOCKS, IP Masquerade =head2 CPANox, CPAN::Nox - Wrapper around CPAN.pm without using any XS module -=over +=over 4 =item SYNOPSIS @@ -5490,13 +7872,13 @@ module =head2 Carp, carp - warn of errors (from perspective of caller) -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Forcing a Stack Trace @@ -5508,7 +7890,7 @@ module =head2 Carp::Heavy - Carp guts -=over +=over 4 =item SYNOPIS @@ -5518,16 +7900,18 @@ module =head2 Class::Struct - declare struct-like datatypes as Perl classes -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item The C<struct()> function +=item Class Creation at Compile Time + =item Element Types and Accessor Methods Scalar (C<'$'> or C<'*$'>), Array (C<'@'> or C<'*@'>), Hash (C<'%'> or @@ -5547,7 +7931,7 @@ Example 1, Example 2, Example 3 =head2 Config - access Perl configuration information -=over +=over 4 =item SYNOPSIS @@ -5561,7 +7945,7 @@ myconfig(), config_sh(), config_vars(@names) =item GLOSSARY -=over +=over 4 =item _ @@ -5581,8 +7965,9 @@ C<byacc>, C<byteorder> =item c C<c>, C<castflags>, C<cat>, C<cc>, C<cccdlflags>, C<ccdlflags>, C<ccflags>, -C<ccsymbols>, C<cf_by>, C<cf_email>, C<cf_time>, C<charsize>, C<chgrp>, -C<chmod>, C<chown>, C<clocktype>, C<comm>, C<compress> +C<ccflags_uselargefiles>, C<ccname>, C<ccsymbols>, C<ccversion>, C<cf_by>, +C<cf_email>, C<cf_time>, C<charsize>, C<chgrp>, C<chmod>, C<chown>, +C<clocktype>, C<comm>, C<compress> =item C @@ -5592,63 +7977,68 @@ C<cppstdin>, C<cppsymbols>, C<crosscompile>, C<cryptlib>, C<csh> =item d -C<d_access>, C<d_accessx>, C<d_alarm>, C<d_archlib>, C<d_atolf>, -C<d_atoll>, C<d_attribut>, C<d_bcmp>, C<d_bcopy>, C<d_bincompat5005>, -C<d_bsd>, C<d_bsdgetpgrp>, C<d_bsdsetpgrp>, C<d_bzero>, C<d_casti32>, -C<d_castneg>, C<d_charvspr>, C<d_chown>, C<d_chroot>, C<d_chsize>, -C<d_closedir>, C<d_const>, C<d_crypt>, C<d_csh>, C<d_cuserid>, +C<d__fwalk>, C<d_access>, C<d_accessx>, C<d_alarm>, C<d_archlib>, +C<d_atolf>, C<d_atoll>, C<d_attribut>, C<d_bcmp>, C<d_bcopy>, +C<d_bincompat5005>, C<d_bsd>, C<d_bsdgetpgrp>, C<d_bsdsetpgrp>, C<d_bzero>, +C<d_casti32>, C<d_castneg>, C<d_charvspr>, C<d_chown>, C<d_chroot>, +C<d_chsize>, C<d_closedir>, C<d_const>, C<d_crypt>, C<d_csh>, C<d_cuserid>, C<d_dbl_dig>, C<d_difftime>, C<d_dirnamlen>, C<d_dlerror>, C<d_dlopen>, C<d_dlsymun>, C<d_dosuid>, C<d_drand48proto>, C<d_dup2>, C<d_eaccess>, C<d_endgrent>, C<d_endhent>, C<d_endnent>, C<d_endpent>, C<d_endpwent>, -C<d_endsent>, C<d_endspent>, C<d_eofnblk>, C<d_eunice>, C<d_fchmod>, -C<d_fchown>, C<d_fcntl>, C<d_fd_macros>, C<d_fd_set>, C<d_fds_bits>, -C<d_fgetpos>, C<d_flexfnam>, C<d_flock>, C<d_fork>, C<d_fpathconf>, -C<d_fpos64_t>, C<d_fs_data_s>, C<d_fseeko>, C<d_fsetpos>, C<d_fstatfs>, -C<d_fstatvfs>, C<d_ftello>, C<d_ftime>, C<d_Gconvert>, C<d_getcwd>, -C<d_getfsstat>, C<d_getgrent>, C<d_getgrps>, C<d_gethbyaddr>, -C<d_gethbyname>, C<d_gethent>, C<d_gethname>, C<d_gethostprotos>, -C<d_getlogin>, C<d_getmnt>, C<d_getmntent>, C<d_getnbyaddr>, -C<d_getnbyname>, C<d_getnent>, C<d_getnetprotos>, C<d_getpbyname>, +C<d_endsent>, C<d_eofnblk>, C<d_eunice>, C<d_fchmod>, C<d_fchown>, +C<d_fcntl>, C<d_fcntl_can_lock>, C<d_fd_macros>, C<d_fd_set>, +C<d_fds_bits>, C<d_fgetpos>, C<d_flexfnam>, C<d_flock>, C<d_fork>, +C<d_fpathconf>, C<d_fpos64_t>, C<d_frexpl>, C<d_fs_data_s>, C<d_fseeko>, +C<d_fsetpos>, C<d_fstatfs>, C<d_fstatvfs>, C<d_fsync>, C<d_ftello>, +C<d_ftime>, C<d_Gconvert>, C<d_getcwd>, C<d_getespwnam>, C<d_getfsstat>, +C<d_getgrent>, C<d_getgrps>, C<d_gethbyaddr>, C<d_gethbyname>, +C<d_gethent>, C<d_gethname>, C<d_gethostprotos>, C<d_getlogin>, +C<d_getmnt>, C<d_getmntent>, C<d_getnbyaddr>, C<d_getnbyname>, +C<d_getnent>, C<d_getnetprotos>, C<d_getpagsz>, C<d_getpbyname>, C<d_getpbynumber>, C<d_getpent>, C<d_getpgid>, C<d_getpgrp2>, C<d_getpgrp>, -C<d_getppid>, C<d_getprior>, C<d_getprotoprotos>, C<d_getpwent>, -C<d_getsbyname>, C<d_getsbyport>, C<d_getsent>, C<d_getservprotos>, -C<d_getspent>, C<d_getspnam>, C<d_gettimeod>, C<d_gnulibc>, C<d_grpasswd>, -C<d_hasmntopt>, C<d_htonl>, C<d_iconv>, C<d_index>, C<d_inetaton>, -C<d_int64_t>, C<d_isascii>, C<d_killpg>, C<d_lchown>, C<d_ldbl_dig>, -C<d_link>, C<d_locconv>, C<d_lockf>, C<d_longdbl>, C<d_longlong>, -C<d_lseekproto>, C<d_lstat>, C<d_madvise>, C<d_mblen>, C<d_mbstowcs>, -C<d_mbtowc>, C<d_memchr>, C<d_memcmp>, C<d_memcpy>, C<d_memmove>, -C<d_memset>, C<d_mkdir>, C<d_mkdtemp>, C<d_mkfifo>, C<d_mkstemp>, -C<d_mkstemps>, C<d_mktime>, C<d_mmap>, C<d_mprotect>, C<d_msg>, -C<d_msg_ctrunc>, C<d_msg_dontroute>, C<d_msg_oob>, C<d_msg_peek>, -C<d_msg_proxy>, C<d_msgctl>, C<d_msgget>, C<d_msgrcv>, C<d_msgsnd>, -C<d_msync>, C<d_munmap>, C<d_mymalloc>, C<d_nice>, C<d_nv_preserves_uv>, -C<d_off64_t>, C<d_old_pthread_create_joinable>, C<d_oldpthreads>, -C<d_oldsock>, C<d_open3>, C<d_pathconf>, C<d_pause>, C<d_phostname>, -C<d_pipe>, C<d_poll>, C<d_portable>, C<d_PRId64>, C<d_PRIeldbl>, -C<d_PRIEldbl>, C<d_PRIfldbl>, C<d_PRIFldbl>, C<d_PRIgldbl>, C<d_PRIGldbl>, -C<d_PRIi64>, C<d_PRIo64>, C<d_PRIu64>, C<d_PRIx64>, C<d_PRIX64>, -C<d_pthread_yield>, C<d_pwage>, C<d_pwchange>, C<d_pwclass>, -C<d_pwcomment>, C<d_pwexpire>, C<d_pwgecos>, C<d_pwpasswd>, C<d_pwquota>, -C<d_qgcvt>, C<d_quad>, C<d_readdir>, C<d_readlink>, C<d_rename>, -C<d_rewinddir>, C<d_rmdir>, C<d_safebcpy>, C<d_safemcpy>, C<d_sanemcmp>, -C<d_sched_yield>, C<d_scm_rights>, C<d_seekdir>, C<d_select>, C<d_sem>, +C<d_getppid>, C<d_getprior>, C<d_getprotoprotos>, C<d_getprpwnam>, +C<d_getpwent>, C<d_getsbyname>, C<d_getsbyport>, C<d_getsent>, +C<d_getservprotos>, C<d_getspnam>, C<d_gettimeod>, C<d_gnulibc>, +C<d_grpasswd>, C<d_hasmntopt>, C<d_htonl>, C<d_iconv>, C<d_index>, +C<d_inetaton>, C<d_int64_t>, C<d_isascii>, C<d_isnan>, C<d_isnanl>, +C<d_killpg>, C<d_lchown>, C<d_ldbl_dig>, C<d_link>, C<d_locconv>, +C<d_lockf>, C<d_longdbl>, C<d_longlong>, C<d_lseekproto>, C<d_lstat>, +C<d_madvise>, C<d_mblen>, C<d_mbstowcs>, C<d_mbtowc>, C<d_memchr>, +C<d_memcmp>, C<d_memcpy>, C<d_memmove>, C<d_memset>, C<d_mkdir>, +C<d_mkdtemp>, C<d_mkfifo>, C<d_mkstemp>, C<d_mkstemps>, C<d_mktime>, +C<d_mmap>, C<d_modfl>, C<d_mprotect>, C<d_msg>, C<d_msg_ctrunc>, +C<d_msg_dontroute>, C<d_msg_oob>, C<d_msg_peek>, C<d_msg_proxy>, +C<d_msgctl>, C<d_msgget>, C<d_msgrcv>, C<d_msgsnd>, C<d_msync>, +C<d_munmap>, C<d_mymalloc>, C<d_nice>, C<d_nv_preserves_uv>, +C<d_nv_preserves_uv_bits>, C<d_off64_t>, C<d_old_pthread_create_joinable>, +C<d_oldpthreads>, C<d_oldsock>, C<d_open3>, C<d_pathconf>, C<d_pause>, +C<d_perl_otherlibdirs>, C<d_phostname>, C<d_pipe>, C<d_poll>, +C<d_portable>, C<d_PRId64>, C<d_PRIeldbl>, C<d_PRIEUldbl>, C<d_PRIfldbl>, +C<d_PRIFUldbl>, C<d_PRIgldbl>, C<d_PRIGUldbl>, C<d_PRIi64>, C<d_PRIo64>, +C<d_PRIu64>, C<d_PRIx64>, C<d_PRIXU64>, C<d_pthread_yield>, C<d_pwage>, +C<d_pwchange>, C<d_pwclass>, C<d_pwcomment>, C<d_pwexpire>, C<d_pwgecos>, +C<d_pwpasswd>, C<d_pwquota>, C<d_qgcvt>, C<d_quad>, C<d_readdir>, +C<d_readlink>, C<d_rename>, C<d_rewinddir>, C<d_rmdir>, C<d_safebcpy>, +C<d_safemcpy>, C<d_sanemcmp>, C<d_sbrkproto>, C<d_sched_yield>, +C<d_scm_rights>, C<d_SCNfldbl>, C<d_seekdir>, C<d_select>, C<d_sem>, C<d_semctl>, C<d_semctl_semid_ds>, C<d_semctl_semun>, C<d_semget>, C<d_semop>, C<d_setegid>, C<d_seteuid>, C<d_setgrent>, C<d_setgrps>, C<d_sethent>, C<d_setlinebuf>, C<d_setlocale>, C<d_setnent>, C<d_setpent>, -C<d_setpgid>, C<d_setpgrp2>, C<d_setpgrp>, C<d_setprior>, C<d_setpwent>, -C<d_setregid>, C<d_setresgid>, C<d_setresuid>, C<d_setreuid>, C<d_setrgid>, -C<d_setruid>, C<d_setsent>, C<d_setsid>, C<d_setspent>, C<d_setvbuf>, -C<d_sfio>, C<d_shm>, C<d_shmat>, C<d_shmatprototype>, C<d_shmctl>, -C<d_shmdt>, C<d_shmget>, C<d_sigaction>, C<d_sigsetjmp>, C<d_socket>, -C<d_socklen_t>, C<d_sockpair>, C<d_sqrtl>, C<d_statblks>, +C<d_setpgid>, C<d_setpgrp2>, C<d_setpgrp>, C<d_setprior>, +C<d_setproctitle>, C<d_setpwent>, C<d_setregid>, C<d_setresgid>, +C<d_setresuid>, C<d_setreuid>, C<d_setrgid>, C<d_setruid>, C<d_setsent>, +C<d_setsid>, C<d_setvbuf>, C<d_sfio>, C<d_shm>, C<d_shmat>, +C<d_shmatprototype>, C<d_shmctl>, C<d_shmdt>, C<d_shmget>, C<d_sigaction>, +C<d_sigprocmask>, C<d_sigsetjmp>, C<d_socket>, C<d_socklen_t>, +C<d_sockpair>, C<d_socks5_init>, C<d_sqrtl>, C<d_statblks>, C<d_statfs_f_flags>, C<d_statfs_s>, C<d_statvfs>, C<d_stdio_cnt_lval>, -C<d_stdio_ptr_lval>, C<d_stdio_stream_array>, C<d_stdiobase>, +C<d_stdio_ptr_lval>, C<d_stdio_ptr_lval_nochange_cnt>, +C<d_stdio_ptr_lval_sets_cnt>, C<d_stdio_stream_array>, C<d_stdiobase>, C<d_stdstdio>, C<d_strchr>, C<d_strcoll>, C<d_strctcpy>, C<d_strerrm>, C<d_strerror>, C<d_strtod>, C<d_strtol>, C<d_strtold>, C<d_strtoll>, -C<d_strtoul>, C<d_strtoull>, C<d_strtouq>, C<d_strxfrm>, C<d_suidsafe>, -C<d_symlink>, C<d_syscall>, C<d_sysconf>, C<d_sysernlst>, C<d_syserrlst>, -C<d_system>, C<d_tcgetpgrp>, C<d_tcsetpgrp>, C<d_telldir>, +C<d_strtoq>, C<d_strtoul>, C<d_strtoull>, C<d_strtouq>, C<d_strxfrm>, +C<d_suidsafe>, C<d_symlink>, C<d_syscall>, C<d_sysconf>, C<d_sysernlst>, +C<d_syserrlst>, C<d_system>, C<d_tcgetpgrp>, C<d_tcsetpgrp>, C<d_telldir>, C<d_telldirproto>, C<d_time>, C<d_times>, C<d_truncate>, C<d_tzname>, C<d_umask>, C<d_uname>, C<d_union_semun>, C<d_ustat>, C<d_vendorarch>, C<d_vendorbin>, C<d_vendorlib>, C<d_vfork>, C<d_void_closedir>, @@ -5669,38 +8059,39 @@ C<fpossize>, C<fpostype>, C<freetype>, C<full_ar>, C<full_csh>, C<full_sed> =item g -C<gccversion>, C<gidformat>, C<gidsign>, C<gidsize>, C<gidtype>, -C<glibpth>, C<grep>, C<groupcat>, C<groupstype>, C<gzip> +C<gccosandvers>, C<gccversion>, C<gidformat>, C<gidsign>, C<gidsize>, +C<gidtype>, C<glibpth>, C<grep>, C<groupcat>, C<groupstype>, C<gzip> =item h -C<h_fcntl>, C<h_sysfile>, C<hint>, C<hostcat>, C<huge> +C<h_fcntl>, C<h_sysfile>, C<hint>, C<hostcat> =item i C<i16size>, C<i16type>, C<i32size>, C<i32type>, C<i64size>, C<i64type>, C<i8size>, C<i8type>, C<i_arpainet>, C<i_bsdioctl>, C<i_db>, C<i_dbm>, C<i_dirent>, C<i_dld>, C<i_dlfcn>, C<i_fcntl>, C<i_float>, C<i_gdbm>, -C<i_grp>, C<i_iconv>, C<i_ieeefp>, C<i_inttypes>, C<i_limits>, C<i_locale>, -C<i_machcthr>, C<i_malloc>, C<i_math>, C<i_memory>, C<i_mntent>, C<i_ndbm>, -C<i_netdb>, C<i_neterrno>, C<i_netinettcp>, C<i_niin>, C<i_poll>, -C<i_pthread>, C<i_pwd>, C<i_rpcsvcdbm>, C<i_sfio>, C<i_sgtty>, C<i_shadow>, -C<i_socks>, C<i_stdarg>, C<i_stddef>, C<i_stdlib>, C<i_string>, -C<i_sunmath>, C<i_sysaccess>, C<i_sysdir>, C<i_sysfile>, C<i_sysfilio>, -C<i_sysin>, C<i_sysioctl>, C<i_syslog>, C<i_sysmman>, C<i_sysmode>, -C<i_sysmount>, C<i_sysndir>, C<i_sysparam>, C<i_sysresrc>, C<i_syssecrt>, -C<i_sysselct>, C<i_syssockio>, C<i_sysstat>, C<i_sysstatfs>, -C<i_sysstatvfs>, C<i_systime>, C<i_systimek>, C<i_systimes>, C<i_systypes>, -C<i_sysuio>, C<i_sysun>, C<i_sysutsname>, C<i_sysvfs>, C<i_syswait>, -C<i_termio>, C<i_termios>, C<i_time>, C<i_unistd>, C<i_ustat>, C<i_utime>, -C<i_values>, C<i_varargs>, C<i_varhdr>, C<i_vfork>, -C<ignore_versioned_solibs>, C<inc_version_list>, C<inc_version_list_init>, -C<incpath>, C<inews>, C<installarchlib>, C<installbin>, C<installman1dir>, -C<installman3dir>, C<installprefix>, C<installprefixexp>, -C<installprivlib>, C<installscript>, C<installsitearch>, C<installsitebin>, -C<installsitelib>, C<installstyle>, C<installusrbinperl>, -C<installvendorarch>, C<installvendorbin>, C<installvendorlib>, C<intsize>, -C<ivdformat>, C<ivsize>, C<ivtype> +C<i_grp>, C<i_iconv>, C<i_ieeefp>, C<i_inttypes>, C<i_libutil>, +C<i_limits>, C<i_locale>, C<i_machcthr>, C<i_malloc>, C<i_math>, +C<i_memory>, C<i_mntent>, C<i_ndbm>, C<i_netdb>, C<i_neterrno>, +C<i_netinettcp>, C<i_niin>, C<i_poll>, C<i_prot>, C<i_pthread>, C<i_pwd>, +C<i_rpcsvcdbm>, C<i_sfio>, C<i_sgtty>, C<i_shadow>, C<i_socks>, +C<i_stdarg>, C<i_stddef>, C<i_stdlib>, C<i_string>, C<i_sunmath>, +C<i_sysaccess>, C<i_sysdir>, C<i_sysfile>, C<i_sysfilio>, C<i_sysin>, +C<i_sysioctl>, C<i_syslog>, C<i_sysmman>, C<i_sysmode>, C<i_sysmount>, +C<i_sysndir>, C<i_sysparam>, C<i_sysresrc>, C<i_syssecrt>, C<i_sysselct>, +C<i_syssockio>, C<i_sysstat>, C<i_sysstatfs>, C<i_sysstatvfs>, +C<i_systime>, C<i_systimek>, C<i_systimes>, C<i_systypes>, C<i_sysuio>, +C<i_sysun>, C<i_sysutsname>, C<i_sysvfs>, C<i_syswait>, C<i_termio>, +C<i_termios>, C<i_time>, C<i_unistd>, C<i_ustat>, C<i_utime>, C<i_values>, +C<i_varargs>, C<i_varhdr>, C<i_vfork>, C<ignore_versioned_solibs>, +C<inc_version_list>, C<inc_version_list_init>, C<incpath>, C<inews>, +C<installarchlib>, C<installbin>, C<installman1dir>, C<installman3dir>, +C<installprefix>, C<installprefixexp>, C<installprivlib>, C<installscript>, +C<installsitearch>, C<installsitebin>, C<installsitelib>, C<installstyle>, +C<installusrbinperl>, C<installvendorarch>, C<installvendorbin>, +C<installvendorlib>, C<intsize>, C<issymlink>, C<ivdformat>, C<ivsize>, +C<ivtype> =item k @@ -5708,12 +8099,12 @@ C<known_extensions>, C<ksh> =item l -C<large>, C<ld>, C<lddlflags>, C<ldflags>, C<ldlibpthname>, C<less>, -C<lib_ext>, C<libc>, C<libperl>, C<libpth>, C<libs>, C<libsdirs>, -C<libsfiles>, C<libsfound>, C<libspath>, C<libswanted>, C<line>, C<lint>, -C<lkflags>, C<ln>, C<lns>, C<locincpth>, C<loclibpth>, C<longdblsize>, -C<longlongsize>, C<longsize>, C<lp>, C<lpr>, C<ls>, C<lseeksize>, -C<lseektype> +C<ld>, C<lddlflags>, C<ldflags>, C<ldflags_uselargefiles>, C<ldlibpthname>, +C<less>, C<lib_ext>, C<libc>, C<libperl>, C<libpth>, C<libs>, C<libsdirs>, +C<libsfiles>, C<libsfound>, C<libspath>, C<libswanted>, +C<libswanted_uselargefiles>, C<line>, C<lint>, C<lkflags>, C<ln>, C<lns>, +C<locincpth>, C<loclibpth>, C<longdblsize>, C<longlongsize>, C<longsize>, +C<lp>, C<lpr>, C<ls>, C<lseeksize>, C<lseektype> =item m @@ -5723,20 +8114,20 @@ C<man3direxp>, C<man3ext> =item M -C<Mcc>, C<medium>, C<mips_type>, C<mkdir>, C<mmaptype>, C<models>, -C<modetype>, C<more>, C<multiarch>, C<mv>, C<myarchname>, C<mydomain>, -C<myhostname>, C<myuname> +C<Mcc>, C<mips_type>, C<mkdir>, C<mmaptype>, C<modetype>, C<more>, +C<multiarch>, C<mv>, C<myarchname>, C<mydomain>, C<myhostname>, C<myuname> =item n -C<n>, C<netdb_hlen_type>, C<netdb_host_type>, C<netdb_name_type>, -C<netdb_net_type>, C<nm>, C<nm_opt>, C<nm_so_opt>, C<nonxs_ext>, C<nroff>, -C<nvsize>, C<nvtype> +C<n>, C<need_va_copy>, C<netdb_hlen_type>, C<netdb_host_type>, +C<netdb_name_type>, C<netdb_net_type>, C<nm>, C<nm_opt>, C<nm_so_opt>, +C<nonxs_ext>, C<nroff>, C<nveformat>, C<nvEUformat>, C<nvfformat>, +C<nvFUformat>, C<nvgformat>, C<nvGUformat>, C<nvsize>, C<nvtype> =item o C<o_nonblock>, C<obj_ext>, C<old_pthread_create_joinable>, C<optimize>, -C<orderlib>, C<osname>, C<osvers> +C<orderlib>, C<osname>, C<osvers>, C<otherlibdirs> =item p @@ -5746,9 +8137,9 @@ C<perl> =item P C<PERL_REVISION>, C<PERL_SUBVERSION>, C<PERL_VERSION>, C<perladmin>, -C<perlpath>, C<pg>, C<phostname>, C<pidtype>, C<plibpth>, C<pm_apiversion>, -C<pmake>, C<pr>, C<prefix>, C<prefixexp>, C<privlib>, C<privlibexp>, -C<prototype>, C<ptrsize> +C<perllibs>, C<perlpath>, C<pg>, C<phostname>, C<pidtype>, C<plibpth>, +C<pm_apiversion>, C<pmake>, C<pr>, C<prefix>, C<prefixexp>, C<privlib>, +C<privlibexp>, C<prototype>, C<ptrsize> =item q @@ -5764,14 +8155,14 @@ C<revision>, C<rm>, C<rmail>, C<runnm> C<sched_yield>, C<scriptdir>, C<scriptdirexp>, C<sed>, C<seedfunc>, C<selectminbits>, C<selecttype>, C<sendmail>, C<sh>, C<shar>, C<sharpbang>, C<shmattype>, C<shortsize>, C<shrpenv>, C<shsharp>, C<sig_count>, -C<sig_name>, C<sig_name_init>, C<sig_num>, C<sig_num_init>, C<signal_t>, -C<sitearch>, C<sitearchexp>, C<sitebin>, C<sitebinexp>, C<sitelib>, -C<sitelib_stem>, C<sitelibexp>, C<siteprefix>, C<siteprefixexp>, -C<sizesize>, C<sizetype>, C<sleep>, C<smail>, C<small>, C<so>, +C<sig_name>, C<sig_name_init>, C<sig_num>, C<sig_num_init>, C<sig_size>, +C<signal_t>, C<sitearch>, C<sitearchexp>, C<sitebin>, C<sitebinexp>, +C<sitelib>, C<sitelib_stem>, C<sitelibexp>, C<siteprefix>, +C<siteprefixexp>, C<sizesize>, C<sizetype>, C<sleep>, C<smail>, C<so>, C<sockethdr>, C<socketlib>, C<socksizetype>, C<sort>, C<spackage>, -C<spitshell>, C<split>, C<sPRId64>, C<sPRIeldbl>, C<sPRIEldbl>, -C<sPRIfldbl>, C<sPRIFldbl>, C<sPRIgldbl>, C<sPRIGldbl>, C<sPRIi64>, -C<sPRIo64>, C<sPRIu64>, C<sPRIx64>, C<sPRIX64>, C<src>, C<ssizetype>, +C<spitshell>, C<sPRId64>, C<sPRIeldbl>, C<sPRIEUldbl>, C<sPRIfldbl>, +C<sPRIFUldbl>, C<sPRIgldbl>, C<sPRIGUldbl>, C<sPRIi64>, C<sPRIo64>, +C<sPRIu64>, C<sPRIx64>, C<sPRIXU64>, C<src>, C<sSCNfldbl>, C<ssizetype>, C<startperl>, C<startsh>, C<static_ext>, C<stdchar>, C<stdio_base>, C<stdio_bufsiz>, C<stdio_cnt>, C<stdio_filbuf>, C<stdio_ptr>, C<stdio_stream_array>, C<strings>, C<submit>, C<subversion>, C<sysman> @@ -5791,13 +8182,13 @@ C<uselongdouble>, C<usemorebits>, C<usemultiplicity>, C<usemymalloc>, C<usenm>, C<useopcode>, C<useperlio>, C<useposix>, C<usesfio>, C<useshrplib>, C<usesocks>, C<usethreads>, C<usevendorprefix>, C<usevfork>, C<usrinc>, C<uuname>, C<uvoformat>, C<uvsize>, C<uvtype>, C<uvuformat>, -C<uvxformat> +C<uvxformat>, C<uvXUformat> =item v C<vendorarch>, C<vendorarchexp>, C<vendorbin>, C<vendorbinexp>, C<vendorlib>, C<vendorlib_stem>, C<vendorlibexp>, C<vendorprefix>, -C<vendorprefixexp>, C<version>, C<vi>, C<voidflags> +C<vendorprefixexp>, C<version>, C<versiononly>, C<vi>, C<voidflags> =item x @@ -5813,9 +8204,9 @@ C<zcat>, C<zip> =back -=head2 Cwd, getcwd - get pathname of current working directory +=head2 Cwd - get pathname of current working directory -=over +=over 4 =item SYNOPSIS @@ -5827,13 +8218,13 @@ C<zcat>, C<zip> subject to change) -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Global Variables @@ -5862,7 +8253,7 @@ CLIENT->output(LIST) =head2 DB_File - Perl5 access to Berkeley DB version 1.x -=over +=over 4 =item SYNOPSIS @@ -5870,7 +8261,7 @@ CLIENT->output(LIST) B<DB_HASH>, B<DB_BTREE>, B<DB_RECNO> -=over +=over 4 =item Using DB_File with Berkeley DB version 2 or 3 @@ -5886,7 +8277,7 @@ B<DB_HASH>, B<DB_BTREE>, B<DB_RECNO> =item DB_HASH -=over +=over 4 =item A Simple Example @@ -5894,7 +8285,7 @@ B<DB_HASH>, B<DB_BTREE>, B<DB_RECNO> =item DB_BTREE -=over +=over 4 =item Changing the BTREE sort order @@ -5912,7 +8303,7 @@ B<DB_HASH>, B<DB_BTREE>, B<DB_RECNO> =item DB_RECNO -=over +=over 4 =item The 'bval' Option @@ -5939,7 +8330,7 @@ $value, $flags) ;>, B<$status = $X-E<gt>sync([$flags]) ;> B<filter_store_key>, B<filter_store_value>, B<filter_fetch_key>, B<filter_fetch_value> -=over +=over 4 =item The Filter @@ -5951,7 +8342,7 @@ B<filter_fetch_value> =item HINTS AND TIPS -=over +=over 4 =item Locking: The Trouble with fd @@ -5967,7 +8358,7 @@ B<Tie::DB_Lock>, B<Tie::DB_LockFile>, B<DB_File::Lock> =item COMMON QUESTIONS -=over +=over 4 =item Why is there Perl source in my database? @@ -5998,13 +8389,13 @@ B<Tie::DB_Lock>, B<Tie::DB_LockFile>, B<DB_File::Lock> =head2 Data::Dumper - stringified perl data structures, suitable for both printing and C<eval> -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Methods @@ -6052,7 +8443,7 @@ Dumper =head2 Devel::DProf - a Perl code profiler -=over +=over 4 =item SYNOPSIS @@ -6072,15 +8463,21 @@ Dumper =head2 Devel::Peek - A data debugging tool for the XS programmer -=over +=over 4 =item SYNOPSIS =item DESCRIPTION +=over 4 + +=item Memory footprint debugging + +=back + =item EXAMPLES -=over +=over 4 =item A simple scalar string @@ -6114,7 +8511,7 @@ Dumper =head2 Devel::SelfStubber - generate stubs for a SelfLoading module -=over +=over 4 =item SYNOPSIS @@ -6124,7 +8521,7 @@ Dumper =head2 DirHandle - supply object methods for directory handles -=over +=over 4 =item SYNOPSIS @@ -6134,13 +8531,13 @@ Dumper =head2 Dumpvalue - provides screen dump of Perl data. -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Creation @@ -6160,7 +8557,7 @@ veryCompact, set, get =head2 DynaLoader - Dynamically load C libraries into Perl code -=over +=over 4 =item SYNOPSIS @@ -6179,7 +8576,7 @@ bootstrap() =head2 DynaLoader::XSLoader, XSLoader - Dynamically load C libraries into Perl code -=over +=over 4 =item SYNOPSIS @@ -6192,7 +8589,7 @@ Perl code =head2 English - use nice English (or awk) names for ugly punctuation variables -=over +=over 4 =item SYNOPSIS @@ -6205,7 +8602,7 @@ variables =head2 Env - perl module that imports environment variables as scalars or arrays -=over +=over 4 =item SYNOPSIS @@ -6219,7 +8616,7 @@ arrays =head2 Errno - System errno constants -=over +=over 4 =item SYNOPSIS @@ -6235,13 +8632,13 @@ arrays =head2 Exporter - Implements default import method for modules -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item How to Export @@ -6263,7 +8660,7 @@ arrays =head2 Exporter::Heavy - Exporter guts -=over +=over 4 =item SYNOPIS @@ -6274,7 +8671,7 @@ arrays =head2 ExtUtils::Command - utilities to replace common UNIX commands in Makefiles etc. -=over +=over 4 =item SYNOPSIS @@ -6302,7 +8699,7 @@ mkpath directory.. test_f file -=over +=over 4 =item BUGS @@ -6314,7 +8711,7 @@ test_f file =head2 ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications -=over +=over 4 =item SYNOPSIS @@ -6337,7 +8734,7 @@ ccopts(), xsi_header(), xsi_protos(@modules), xsi_body(@modules) =head2 ExtUtils::Install - install files from here to there -=over +=over 4 =item SYNOPSIS @@ -6347,7 +8744,7 @@ ccopts(), xsi_header(), xsi_protos(@modules), xsi_body(@modules) =head2 ExtUtils::Installed - Inventory management of installed modules -=over +=over 4 =item SYNOPSIS @@ -6368,7 +8765,7 @@ packlist(), version() =head2 ExtUtils::Liblist - determine libraries to use and how to use them -=over +=over 4 =item SYNOPSIS @@ -6376,7 +8773,7 @@ packlist(), version() For static extensions, For dynamic extensions, For dynamic extensions -=over +=over 4 =item EXTRALIBS @@ -6388,7 +8785,7 @@ For static extensions, For dynamic extensions, For dynamic extensions =item PORTABILITY -=over +=over 4 =item VMS implementation @@ -6403,7 +8800,7 @@ For static extensions, For dynamic extensions, For dynamic extensions =head2 ExtUtils::MM_Cygwin - methods to override UN*X behaviour in ExtUtils::MakeMaker -=over +=over 4 =item SYNOPSIS @@ -6413,10 +8810,12 @@ canonpath, cflags, manifypods, perl_archive =back +perl_archive_after + =head2 ExtUtils::MM_OS2 - methods to override UN*X behaviour in ExtUtils::MakeMaker -=over +=over 4 =item SYNOPSIS @@ -6426,7 +8825,7 @@ ExtUtils::MakeMaker =head2 ExtUtils::MM_Unix - methods used by ExtUtils::MakeMaker -=over +=over 4 =item SYNOPSIS @@ -6434,7 +8833,7 @@ ExtUtils::MakeMaker =item METHODS -=over +=over 4 =item Preloaded methods @@ -6454,7 +8853,7 @@ rootdir updir -=over +=over 4 =item SelfLoaded methods @@ -6506,7 +8905,7 @@ file_name_is_absolute find_perl -=over +=over 4 =item Methods to actually produce chunks of text for the Makefile @@ -6622,9 +9021,11 @@ xs_o (o) perl_archive +perl_archive_after + export_list -=over +=over 4 =item SEE ALSO @@ -6633,13 +9034,13 @@ export_list =head2 ExtUtils::MM_VMS - methods to override UN*X behaviour in ExtUtils::MakeMaker -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Methods always loaded @@ -6651,7 +9052,7 @@ wraplist rootdir (override) -=over +=over 4 =item SelfLoaded methods @@ -6748,7 +9149,7 @@ nicetext (override) =head2 ExtUtils::MM_Win32 - methods to override UN*X behaviour in ExtUtils::MakeMaker -=over +=over 4 =item SYNOPSIS @@ -6794,13 +9195,13 @@ pasthru (o) =head2 ExtUtils::MakeMaker - create an extension Makefile -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item How To Write A Makefile.PL @@ -6824,21 +9225,21 @@ pasthru (o) =item Using Attributes and Parameters -AUTHOR, ABSTRACT, ABSTRACT_FROM, BINARY_LOCATION, C, CAPI, CCFLAGS, CONFIG, +ABSTRACT, ABSTRACT_FROM, AUTHOR, BINARY_LOCATION, C, CAPI, CCFLAGS, CONFIG, CONFIGURE, DEFINE, DIR, DISTNAME, DL_FUNCS, DL_VARS, EXCLUDE_EXT, EXE_FILES, FIRST_MAKEFILE, FULLPERL, FUNCLIST, H, HTMLLIBPODS, HTMLSCRIPTPODS, IMPORTS, INC, INCLUDE_EXT, INSTALLARCHLIB, INSTALLBIN, INSTALLDIRS, INSTALLHTMLPRIVLIBDIR, INSTALLHTMLSCRIPTDIR, INSTALLHTMLSITELIBDIR, INSTALLMAN1DIR, INSTALLMAN3DIR, INSTALLPRIVLIB, INSTALLSCRIPT, INSTALLSITEARCH, INSTALLSITELIB, INST_ARCHLIB, INST_BIN, -INST_EXE, INST_LIB, INST_HTMLLIBDIR, INST_HTMLSCRIPTDIR, INST_MAN1DIR, -INST_MAN3DIR, INST_SCRIPT, PERL_MALLOC_OK, LDFROM, LIB, LIBPERL_A, LIBS, -LINKTYPE, MAKEAPERL, MAKEFILE, MAN1PODS, MAN3PODS, MAP_TARGET, MYEXTLIB, -NAME, NEEDS_LINKING, NOECHO, NORECURS, NO_VC, OBJECT, OPTIMIZE, PERL, -PERLMAINCC, PERL_ARCHLIB, PERL_LIB, PERL_SRC, PERM_RW, PERM_RWX, PL_FILES, -PM, PMLIBDIRS, POLLUTE, PPM_INSTALL_EXEC, PPM_INSTALL_SCRIPT, PREFIX, -PREREQ_PM, SKIP, TYPEMAPS, VERSION, VERSION_FROM, XS, XSOPT, XSPROTOARG, -XS_VERSION +INST_EXE, INST_HTMLLIBDIR, INST_HTMLSCRIPTDIR, INST_LIB, INST_MAN1DIR, +INST_MAN3DIR, INST_SCRIPT, LDFROM, LIB, LIBPERL_A, LIBS, LINKTYPE, +MAKEAPERL, MAKEFILE, MAN1PODS, MAN3PODS, MAP_TARGET, MYEXTLIB, NAME, +NEEDS_LINKING, NOECHO, NORECURS, NO_VC, OBJECT, OPTIMIZE, PERL, PERLMAINCC, +PERL_ARCHLIB, PERL_LIB, PERL_MALLOC_OK, PERL_SRC, PERM_RW, PERM_RWX, +PL_FILES, PM, PMLIBDIRS, PM_FILTER, POLLUTE, PPM_INSTALL_EXEC, +PPM_INSTALL_SCRIPT, PREFIX, PREREQ_PM, SKIP, TYPEMAPS, VERSION, +VERSION_FROM, XS, XSOPT, XSPROTOARG, XS_VERSION =item Additional lowercase attributes @@ -6871,7 +9272,7 @@ PERL_MM_OPT =head2 ExtUtils::Manifest - utilities to write and check a MANIFEST file -=over +=over 4 =item SYNOPSIS @@ -6896,7 +9297,7 @@ C<Added to MANIFEST:> I<file> =head2 ExtUtils::Miniperl, writemain - write the C code for perlmain.c -=over +=over 4 =item SYNOPSIS @@ -6908,7 +9309,7 @@ C<Added to MANIFEST:> I<file> =head2 ExtUtils::Mkbootstrap - make a bootstrap file for use by DynaLoader -=over +=over 4 =item SYNOPSIS @@ -6919,7 +9320,7 @@ C<Added to MANIFEST:> I<file> =head2 ExtUtils::Mksymlists - write linker options files for dynamic extension -=over +=over 4 =item SYNOPSIS @@ -6935,7 +9336,7 @@ DLBASE, DL_FUNCS, DL_VARS, FILE, FUNCLIST, IMPORTS, NAME =head2 ExtUtils::Packlist - manage .packlist files -=over +=over 4 =item SYNOPSIS @@ -6955,7 +9356,7 @@ new(), read(), write(), validate(), packlist_file() =head2 ExtUtils::testlib - add blib/* directories to @INC -=over +=over 4 =item SYNOPSIS @@ -6965,7 +9366,7 @@ new(), read(), write(), validate(), packlist_file() =head2 Fatal - replace functions with equivalents which succeed or die -=over +=over 4 =item SYNOPSIS @@ -6977,7 +9378,7 @@ new(), read(), write(), validate(), packlist_file() =head2 Fcntl - load the C Fcntl.h defines -=over +=over 4 =item SYNOPSIS @@ -6991,7 +9392,7 @@ new(), read(), write(), validate(), packlist_file() =head2 File::Basename, fileparse - split a pathname into pieces -=over +=over 4 =item SYNOPSIS @@ -7007,7 +9408,7 @@ C<basename>, C<dirname> =head2 File::CheckTree, validate - run many filetest checks on a tree -=over +=over 4 =item SYNOPSIS @@ -7017,7 +9418,7 @@ C<basename>, C<dirname> =head2 File::Compare - Compare files or filehandles -=over +=over 4 =item SYNOPSIS @@ -7031,13 +9432,13 @@ C<basename>, C<dirname> =head2 File::Copy - Copy files or filehandles -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Special behaviour if C<syscopy> is defined (OS/2, VMS and Win32) @@ -7053,7 +9454,7 @@ rmscopy($from,$to[,$date_flag]) =head2 File::DosGlob - DOS like globbing and then some -=over +=over 4 =item SYNOPSIS @@ -7073,14 +9474,15 @@ rmscopy($from,$to[,$date_flag]) =head2 File::Find, find - traverse a file tree -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -C<wanted>, C<bydepth>, C<follow>, C<follow_fast>, C<follow_skip>, -C<no_chdir>, C<untaint>, C<untaint_pattern>, C<untaint_skip> +C<wanted>, C<bydepth>, C<preprocess>, C<postprocess>, C<follow>, +C<follow_fast>, C<follow_skip>, C<no_chdir>, C<untaint>, +C<untaint_pattern>, C<untaint_skip> =item CAVEAT @@ -7088,14 +9490,15 @@ C<no_chdir>, C<untaint>, C<untaint_pattern>, C<untaint_skip> =head2 File::Glob - Perl extension for BSD glob routine -=over +=over 4 =item SYNOPSIS =item DESCRIPTION C<GLOB_ERR>, C<GLOB_MARK>, C<GLOB_NOCASE>, C<GLOB_NOCHECK>, C<GLOB_NOSORT>, -C<GLOB_BRACE>, C<GLOB_NOMAGIC>, C<GLOB_QUOTE>, C<GLOB_TILDE>, C<GLOB_CSH> +C<GLOB_BRACE>, C<GLOB_NOMAGIC>, C<GLOB_QUOTE>, C<GLOB_TILDE>, C<GLOB_CSH>, +C<GLOB_ALPHASORT> =item DIAGNOSTICS @@ -7109,7 +9512,7 @@ C<GLOB_NOSPACE>, C<GLOB_ABEND> =head2 File::Path - create or remove directory trees -=over +=over 4 =item SYNOPSIS @@ -7121,7 +9524,7 @@ C<GLOB_NOSPACE>, C<GLOB_ABEND> =head2 File::Spec - portably perform operations on file names -=over +=over 4 =item SYNOPSIS @@ -7133,15 +9536,49 @@ C<GLOB_NOSPACE>, C<GLOB_ABEND> =back +=head2 File::Spec::Epoc - methods for Epoc file specs + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +devnull + +=back + +tmpdir + +path + +canonpath + +splitpath + +splitdir + +catpath + +abs2rel + +rel2abs + +=over 4 + +=item SEE ALSO + +=back + =head2 File::Spec::Functions - portably perform operations on file names -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Exports @@ -7153,7 +9590,7 @@ C<GLOB_NOSPACE>, C<GLOB_ABEND> =head2 File::Spec::Mac - File::Spec for MacOS -=over +=over 4 =item SYNOPSIS @@ -7193,7 +9630,7 @@ abs2rel rel2abs -=over +=over 4 =item SEE ALSO @@ -7201,7 +9638,7 @@ rel2abs =head2 File::Spec::OS2 - methods for OS/2 file specs -=over +=over 4 =item SYNOPSIS @@ -7211,7 +9648,7 @@ rel2abs =head2 File::Spec::Unix - methods used by File::Spec -=over +=over 4 =item SYNOPSIS @@ -7257,7 +9694,7 @@ abs2rel rel2abs -=over +=over 4 =item SEE ALSO @@ -7265,7 +9702,7 @@ rel2abs =head2 File::Spec::VMS - methods for VMS file specs -=over +=over 4 =item SYNOPSIS @@ -7277,7 +9714,7 @@ eliminate_macros fixpath -=over +=over 4 =item Methods always loaded @@ -7315,7 +9752,7 @@ abs2rel (override) rel2abs (override) -=over +=over 4 =item SEE ALSO @@ -7323,7 +9760,7 @@ rel2abs (override) =head2 File::Spec::Win32 - methods for Win32 file specs -=over +=over 4 =item SYNOPSIS @@ -7345,19 +9782,105 @@ splitdir catpath -abs2rel +=over 4 -rel2abs +=item SEE ALSO -=over +=back + +=head2 File::Temp - return name and handle of a temporary file safely + +=over 4 + +=item PORTABILITY + +=item SYNOPSIS + +=item DESCRIPTION + +=back + +=over 4 + +=item FUNCTIONS + +B<tempfile> + +=back + +B<tempdir> + +=over 4 + +=item MKTEMP FUNCTIONS + +B<mkstemp> + +=back + +B<mkstemps> + +B<mkdtemp> + +B<mktemp> + +=over 4 + +=item POSIX FUNCTIONS + +B<tmpnam> + +=back + +B<tmpfile> + +=over 4 + +=item ADDITIONAL FUNCTIONS + +B<tempnam> + +=back + +=over 4 + +=item UTILITY FUNCTIONS + +B<unlink0> + +=back + +=over 4 + +=item PACKAGE VARIABLES + +B<safe_level>, STANDARD, MEDIUM, HIGH + +=back + +TopSystemUID + +=over 4 + +=item WARNING + +=over 4 + +=item Temporary files and NFS + +=back + +=item HISTORY =item SEE ALSO +=item AUTHOR + =back =head2 File::stat - by-name interface to Perl's built-in stat() functions -=over +=over 4 =item SYNOPSIS @@ -7371,7 +9894,7 @@ rel2abs =head2 FileCache - keep more files open than the system permits -=over +=over 4 =item SYNOPSIS @@ -7383,7 +9906,7 @@ rel2abs =head2 FileHandle - supply object methods for filehandles -=over +=over 4 =item SYNOPSIS @@ -7397,7 +9920,7 @@ $fh->print, $fh->printf, $fh->getline, $fh->getlines =head2 FindBin - Locate directory of original perl script -=over +=over 4 =item SYNOPSIS @@ -7415,7 +9938,7 @@ $fh->print, $fh->printf, $fh->getline, $fh->getlines =head2 GDBM_File - Perl5 access to the gdbm library. -=over +=over 4 =item SYNOPSIS @@ -7431,7 +9954,7 @@ $fh->print, $fh->printf, $fh->getline, $fh->getlines =head2 Getopt::Long - Extended processing of command line options -=over +=over 4 =item SYNOPSIS @@ -7441,7 +9964,7 @@ $fh->print, $fh->printf, $fh->getline, $fh->getlines =item Getting Started with Getopt::Long -=over +=over 4 =item Simple options @@ -7469,7 +9992,9 @@ $fh->print, $fh->printf, $fh->getline, $fh->getlines =item Advanced Possibilities -=over +=over 4 + +=item Object oriented interface =item Documentation and help texts @@ -7485,16 +10010,17 @@ $fh->print, $fh->printf, $fh->getline, $fh->getlines =item Configuring Getopt::Long -default, auto_abbrev, getopt_compat, require_order, permute, bundling -(default: reset), bundling_override (default: reset), ignore_case -(default: set), ignore_case_always (default: reset), pass_through (default: -reset), prefix, prefix_pattern, debug (default: reset) +default, posix_default, auto_abbrev, getopt_compat, gnu_compat, gnu_getopt, +require_order, permute, bundling (default: disabled), bundling_override +(default: disabled), ignore_case (default: enabled), ignore_case_always +(default: disabled), pass_through (default: disabled), prefix, +prefix_pattern, debug (default: disabled) =item Return values and Errors =item Legacy -=over +=over 4 =item Default destinations @@ -7504,6 +10030,17 @@ reset), prefix, prefix_pattern, debug (default: reset) =back +=item Trouble Shooting + +=over 4 + +=item Warning: Ignoring '!' modifier for short option + +=item GetOptions does not return a false result when an option is not +supplied + +=back + =item AUTHOR =item COPYRIGHT AND DISCLAIMER @@ -7513,7 +10050,7 @@ reset), prefix, prefix_pattern, debug (default: reset) =head2 Getopt::Std, getopt - Process single-character switches with switch clustering -=over +=over 4 =item SYNOPSIS @@ -7524,7 +10061,7 @@ clustering =head2 I18N::Collate - compare 8-bit scalar data according to the current locale -=over +=over 4 =item SYNOPSIS @@ -7534,7 +10071,7 @@ locale =head2 IO - load various IO modules -=over +=over 4 =item SYNOPSIS @@ -7544,7 +10081,7 @@ locale =head2 IO::Dir - supply object methods for directory handles -=over +=over 4 =item SYNOPSIS @@ -7563,7 +10100,7 @@ rewind (), close (), tie %hash, IO::Dir, DIRNAME [, OPTIONS ] =head2 IO::File - supply object methods for filehandles -=over +=over 4 =item SYNOPSIS @@ -7585,7 +10122,7 @@ open( FILENAME [,MODE [,PERMS]] ) =head2 IO::Handle - supply object methods for I/O handles -=over +=over 4 =item SYNOPSIS @@ -7614,7 +10151,7 @@ $io->blocking ( [ BOOL ] ), $io->untaint =head2 IO::Pipe - supply object methods for pipes -=over +=over 4 =item SYNOPSIS @@ -7638,7 +10175,7 @@ reader ([ARGS]), writer ([ARGS]), handles () =head2 IO::Poll - Object interface to system poll call -=over +=over 4 =item SYNOPSIS @@ -7659,13 +10196,15 @@ IO ), handles( [ EVENT_MASK ] ) =head2 IO::Seekable - supply seek based methods for I/O objects -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=item SEE ALSO +$io->getpos, $io->setpos, $io->setpos ( POS, WHENCE ), WHENCE=0 (SEEK_SET), +WHENCE=1 (SEEK_CUR), WHENCE=1 (SEEK_END), $io->sysseek( POS, WHENCE ), +$io->tell =item HISTORY @@ -7673,7 +10212,7 @@ IO ), handles( [ EVENT_MASK ] ) =head2 IO::Select - OO interface to the select system call -=over +=over 4 =item SYNOPSIS @@ -7699,7 +10238,7 @@ count (), bits(), select ( READ, WRITE, ERROR [, TIMEOUT ] ) =head2 IO::Socket - Object interface to socket communications -=over +=over 4 =item SYNOPSIS @@ -7724,7 +10263,7 @@ sockopt(OPT [, VAL]), sockdomain, socktype, protocol, connected =head2 IO::Socket::INET - Object interface for AF_INET domain sockets -=over +=over 4 =item SYNOPSIS @@ -7734,7 +10273,7 @@ sockopt(OPT [, VAL]), sockdomain, socktype, protocol, connected new ( [ARGS] ) -=over +=over 4 =item METHODS @@ -7753,7 +10292,7 @@ sockaddr (), sockport (), sockhost (), peeraddr (), peerport (), peerhost =head2 IO::Socket::UNIX - Object interface for AF_UNIX domain sockets -=over +=over 4 =item SYNOPSIS @@ -7778,7 +10317,7 @@ hostpath(), peerpath() =head2 IO::lib::IO::Dir, IO::Dir - supply object methods for directory handles -=over +=over 4 =item SYNOPSIS @@ -7797,7 +10336,7 @@ rewind (), close (), tie %hash, IO::Dir, DIRNAME [, OPTIONS ] =head2 IO::lib::IO::File, IO::File - supply object methods for filehandles -=over +=over 4 =item SYNOPSIS @@ -7820,7 +10359,7 @@ open( FILENAME [,MODE [,PERMS]] ) =head2 IO::lib::IO::Handle, IO::Handle - supply object methods for I/O handles -=over +=over 4 =item SYNOPSIS @@ -7849,7 +10388,7 @@ $io->blocking ( [ BOOL ] ), $io->untaint =head2 IO::lib::IO::Pipe, IO::Pipe - supply object methods for pipes -=over +=over 4 =item SYNOPSIS @@ -7873,7 +10412,7 @@ reader ([ARGS]), writer ([ARGS]), handles () =head2 IO::lib::IO::Poll, IO::Poll - Object interface to system poll call -=over +=over 4 =item SYNOPSIS @@ -7895,13 +10434,15 @@ IO ), handles( [ EVENT_MASK ] ) =head2 IO::lib::IO::Seekable, IO::Seekable - supply seek based methods for I/O objects -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=item SEE ALSO +$io->getpos, $io->setpos, $io->setpos ( POS, WHENCE ), WHENCE=0 (SEEK_SET), +WHENCE=1 (SEEK_CUR), WHENCE=1 (SEEK_END), $io->sysseek( POS, WHENCE ), +$io->tell =item HISTORY @@ -7910,7 +10451,7 @@ I/O objects =head2 IO::lib::IO::Select, IO::Select - OO interface to the select system call -=over +=over 4 =item SYNOPSIS @@ -7937,7 +10478,7 @@ count (), bits(), select ( READ, WRITE, ERROR [, TIMEOUT ] ) =head2 IO::lib::IO::Socket, IO::Socket - Object interface to socket communications -=over +=over 4 =item SYNOPSIS @@ -7963,7 +10504,7 @@ sockopt(OPT [, VAL]), sockdomain, socktype, protocol, connected =head2 IO::lib::IO::Socket::INET, IO::Socket::INET - Object interface for AF_INET domain sockets -=over +=over 4 =item SYNOPSIS @@ -7973,7 +10514,7 @@ AF_INET domain sockets new ( [ARGS] ) -=over +=over 4 =item METHODS @@ -7993,7 +10534,7 @@ sockaddr (), sockport (), sockhost (), peeraddr (), peerport (), peerhost =head2 IO::lib::IO::Socket::UNIX, IO::Socket::UNIX - Object interface for AF_UNIX domain sockets -=over +=over 4 =item SYNOPSIS @@ -8017,7 +10558,7 @@ hostpath(), peerpath() =head2 IPC::Msg - SysV Msg IPC object class -=over +=over 4 =item SYNOPSIS @@ -8039,7 +10580,7 @@ FLAGS ] ), stat =head2 IPC::Open2, open2 - open a process for both reading and writing -=over +=over 4 =item SYNOPSIS @@ -8054,7 +10595,7 @@ FLAGS ] ), stat =head2 IPC::Open3, open3 - open a process for reading, writing, and error handling -=over +=over 4 =item SYNOPSIS @@ -8066,7 +10607,7 @@ handling =head2 IPC::Semaphore - SysV Semaphore IPC object class -=over +=over 4 =item SYNOPSIS @@ -8089,7 +10630,7 @@ set ( NAME => VALUE [, NAME => VALUE ...] ), setall ( VALUES ), setval ( N =head2 IPC::SysV - SysV IPC constants -=over +=over 4 =item SYNOPSIS @@ -8107,7 +10648,7 @@ ftok( PATH, ID ) =head2 IPC::SysV::Msg, IPC::Msg - SysV Msg IPC object class -=over +=over 4 =item SYNOPSIS @@ -8130,7 +10671,7 @@ FLAGS ] ), stat =head2 IPC::SysV::Semaphore, IPC::Semaphore - SysV Semaphore IPC object class -=over +=over 4 =item SYNOPSIS @@ -8153,7 +10694,7 @@ set ( NAME => VALUE [, NAME => VALUE ...] ), setall ( VALUES ), setval ( N =head2 Math::BigFloat - Arbitrary length float math package -=over +=over 4 =item SYNOPSIS @@ -8170,7 +10711,7 @@ performed =head2 Math::BigInt - Arbitrary size integer math package -=over +=over 4 =item SYNOPSIS @@ -8188,9 +10729,42 @@ Canonical notation, Input, Output =back +=head2 Math::Complex - complex numbers and associated mathematical +functions + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item OPERATIONS + +=item CREATION + +=item STRINGIFICATION + +=over 4 + +=item CHANGED IN PERL 5.6 + +=back + +=item USAGE + +=item ERRORS DUE TO DIVISION BY ZERO OR LOGARITHM OF ZERO + +=item ERRORS DUE TO INDIGESTIBLE ARGUMENTS + +=item BUGS + +=item AUTHORS + +=back + =head2 Math::Trig - trigonometric functions -=over +=over 4 =item SYNOPSIS @@ -8200,7 +10774,7 @@ Canonical notation, Input, Output B<tan> -=over +=over 4 =item ERRORS DUE TO DIVISION BY ZERO @@ -8212,7 +10786,7 @@ B<tan> =item RADIAL COORDINATE CONVERSIONS -=over +=over 4 =item COORDINATE SYSTEMS @@ -8235,23 +10809,33 @@ cylindrical_to_spherical, spherical_to_cartesian, spherical_to_cylindrical =head2 NDBM_File - Tied access to ndbm files -=over +=over 4 =item SYNOPSIS -=item DESCRIPTION +C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR> + +=item DIAGNOSTICS + +=over 4 + +=item C<ndbm store returned -1, errno 22, key "..." at ...> + +=back + +=item BUGS AND WARNINGS =back =head2 Net::Ping - check a remote host for reachability -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item Functions @@ -8269,7 +10853,7 @@ $timeout]);, $p->close();, pingecho($host [, $timeout]); =head2 Net::hostent - by-name interface to Perl's built-in gethost*() functions -=over +=over 4 =item SYNOPSIS @@ -8286,7 +10870,7 @@ functions =head2 Net::netent - by-name interface to Perl's built-in getnet*() functions -=over +=over 4 =item SYNOPSIS @@ -8303,7 +10887,7 @@ functions =head2 Net::protoent - by-name interface to Perl's built-in getproto*() functions -=over +=over 4 =item SYNOPSIS @@ -8318,7 +10902,7 @@ functions =head2 Net::servent - by-name interface to Perl's built-in getserv*() functions -=over +=over 4 =item SYNOPSIS @@ -8334,7 +10918,7 @@ functions =head2 O - Generic interface to Perl Compiler backends -=over +=over 4 =item SYNOPSIS @@ -8350,17 +10934,27 @@ functions =head2 ODBM_File - Tied access to odbm files -=over +=over 4 =item SYNOPSIS -=item DESCRIPTION +C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR> + +=item DIAGNOSTICS + +=over 4 + +=item C<odbm store returned -1, errno 22, key "..." at ...> + +=back + +=item BUGS AND WARNINGS =back =head2 Opcode - Disable named opcodes when compiling perl code -=over +=over 4 =item SYNOPSIS @@ -8388,7 +10982,7 @@ opdump (PAT) =back -=over +=over 4 =item Predefined Opcode Tags @@ -8406,7 +11000,7 @@ opdump (PAT) =head2 Opcode::Safe, Safe - Compile and execute code in restricted compartments -=over +=over 4 =item SYNOPSIS @@ -8416,7 +11010,7 @@ a new namespace, an operator mask =item WARNING -=over +=over 4 =item RECENT CHANGES @@ -8440,7 +11034,7 @@ Memory, CPU, Snooping, Signals, State Changes =head2 Opcode::ops, ops - Perl pragma to restrict unsafe operations when compiling -=over +=over 4 =item SYNOPSIS @@ -8452,7 +11046,7 @@ compiling =head2 POSIX - Perl interface to IEEE Std 1003.1 -=over +=over 4 =item SYNOPSIS @@ -8484,16 +11078,16 @@ rewinddir, rmdir, scanf, setgid, setjmp, setlocale, setpgid, setsid, setuid, sigaction, siglongjmp, sigpending, sigprocmask, sigsetjmp, sigsuspend, sin, sinh, sleep, sprintf, sqrt, srand, sscanf, stat, strcat, strchr, strcmp, strcoll, strcpy, strcspn, strerror, strftime, strlen, -strncat, strncmp, strncpy, stroul, strpbrk, strrchr, strspn, strstr, -strtod, strtok, strtol, strtoul, strxfrm, sysconf, system, tan, tanh, -tcdrain, tcflow, tcflush, tcgetpgrp, tcsendbreak, tcsetpgrp, time, times, -tmpfile, tmpnam, tolower, toupper, ttyname, tzname, tzset, umask, uname, -ungetc, unlink, utime, vfprintf, vprintf, vsprintf, wait, waitpid, -wcstombs, wctomb, write +strncat, strncmp, strncpy, strpbrk, strrchr, strspn, strstr, strtod, +strtok, strtol, strtoul, strxfrm, sysconf, system, tan, tanh, tcdrain, +tcflow, tcflush, tcgetpgrp, tcsendbreak, tcsetpgrp, time, times, tmpfile, +tmpnam, tolower, toupper, ttyname, tzname, tzset, umask, uname, ungetc, +unlink, utime, vfprintf, vprintf, vsprintf, wait, waitpid, wcstombs, +wctomb, write =item CLASSES -=over +=over 4 =item POSIX::SigAction @@ -8577,19 +11171,17 @@ Constants Constants, Macros -=item CREATION - =back =head2 Pod::Checker, podchecker() - check pod documents for syntax errors -=over +=over 4 =item SYNOPSIS =item OPTIONS/ARGUMENTS -=over +=over 4 =item podchecker() @@ -8601,7 +11193,7 @@ B<-warnings> =E<gt> I<val> =item DIAGNOSTICS -=over +=over 4 =item Errors @@ -8618,12 +11210,16 @@ after =back =item Warnings multiple occurence of link target I<name>, line containing nothing but -whitespace in paragraph, file does not start with =head, No numeric -argument for =over, previous =item has no contents, preceding non-item -paragraph(s), =item type mismatch (I<one> vs. I<two>), I<N> unescaped -C<E<lt>E<gt>> in paragraph, Unknown entity, No items in =over, No argument -for =item, empty section in previous paragraph, Verbatim paragraph in NAME -section, Hyperlinks +whitespace in paragraph, file does not start with =head, previous =item has +no contents, preceding non-item paragraph(s), =item type mismatch (I<one> +vs. I<two>), I<N> unescaped C<E<lt>E<gt>> in paragraph, Unknown entity, No +items in =over, No argument for =item, empty section in previous paragraph, +Verbatim paragraph in NAME section + +=item Hyperlinks + +ignoring leading/trailing whitespace in link, (section) in '$page' +deprecated, alternative text/node '%s' contains non-escaped | or / =back @@ -8635,6 +11231,8 @@ section, Hyperlinks =back +C<Pod::Checker-E<gt>new( %options )> + C<$checker-E<gt>poderror( @args )>, C<$checker-E<gt>poderror( {%opts}, @args )> @@ -8648,7 +11246,7 @@ C<$checker-E<gt>idx()> C<$checker-E<gt>hyperlink()> -=over +=over 4 =item AUTHOR @@ -8656,15 +11254,45 @@ C<$checker-E<gt>hyperlink()> =head2 Pod::Find - find POD documents in directory trees -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=item OPTIONS +=back + +=over 4 + +=item C<pod_find( { %opts } , @directories )> + +C<-verbose =E<gt> 1>, C<-perl =E<gt> 1>, C<-script =E<gt> 1>, C<-inc =E<gt> +1> + +=back + +=over 4 + +=item C<simplify_name( $str )> + +=back + +=over 4 + +=item C<pod_where( { %opts }, $pod )> + +C<-inc =E<gt> 1>, C<-dirs =E<gt> [ $dir1, $dir2, ... ]>, C<-verbose =E<gt> +1> + +=back -B<-verbose>, B<-perl>, B<-script>, B<-inc> +=over 4 + +=item C<contains_pod( $file , $verbose )> + +=back + +=over 4 =item AUTHOR @@ -8674,7 +11302,7 @@ B<-verbose>, B<-perl>, B<-script>, B<-inc> =head2 Pod::Html - module to convert pod files to HTML -=over +=over 4 =item SYNOPSIS @@ -8701,7 +11329,7 @@ verbose =head2 Pod::InputObjects - objects representing POD input paragraphs, commands, etc. -=over +=over 4 =item SYNOPSIS @@ -8711,216 +11339,216 @@ commands, etc. =item DESCRIPTION -B<Pod::InputSource>, B<Pod::Paragraph>, B<Pod::InteriorSequence>, -B<Pod::ParseTree> +package B<Pod::InputSource>, package B<Pod::Paragraph>, package +B<Pod::InteriorSequence>, package B<Pod::ParseTree> =back -=over +=over 4 =item B<Pod::InputSource> =back -=over +=over 4 =item B<new()> =back -=over +=over 4 =item B<name()> =back -=over +=over 4 =item B<handle()> =back -=over +=over 4 =item B<was_cutting()> =back -=over +=over 4 =item B<Pod::Paragraph> =back -=over +=over 4 -=item B<new()> +=item Pod::Paragraph-E<gt>B<new()> =back -=over +=over 4 -=item B<cmd_name()> +=item $pod_para-E<gt>B<cmd_name()> =back -=over +=over 4 -=item B<text()> +=item $pod_para-E<gt>B<text()> =back -=over +=over 4 -=item B<raw_text()> +=item $pod_para-E<gt>B<raw_text()> =back -=over +=over 4 -=item B<cmd_prefix()> +=item $pod_para-E<gt>B<cmd_prefix()> =back -=over +=over 4 -=item B<cmd_separator()> +=item $pod_para-E<gt>B<cmd_separator()> =back -=over +=over 4 -=item B<parse_tree()> +=item $pod_para-E<gt>B<parse_tree()> =back -=over +=over 4 -=item B<file_line()> +=item $pod_para-E<gt>B<file_line()> =back -=over +=over 4 =item B<Pod::InteriorSequence> =back -=over +=over 4 -=item B<new()> +=item Pod::InteriorSequence-E<gt>B<new()> =back -=over +=over 4 -=item B<cmd_name()> +=item $pod_seq-E<gt>B<cmd_name()> =back -=over +=over 4 -=item B<prepend()> +=item $pod_seq-E<gt>B<prepend()> =back -=over +=over 4 -=item B<append()> +=item $pod_seq-E<gt>B<append()> =back -=over +=over 4 -=item B<nested()> +=item $pod_seq-E<gt>B<nested()> =back -=over +=over 4 -=item B<raw_text()> +=item $pod_seq-E<gt>B<raw_text()> =back -=over +=over 4 -=item B<left_delimiter()> +=item $pod_seq-E<gt>B<left_delimiter()> =back -=over +=over 4 -=item B<right_delimiter()> +=item $pod_seq-E<gt>B<right_delimiter()> =back -=over +=over 4 -=item B<parse_tree()> +=item $pod_seq-E<gt>B<parse_tree()> =back -=over +=over 4 -=item B<file_line()> +=item $pod_seq-E<gt>B<file_line()> =back -=over +=over 4 -=item B<DESTROY()> +=item Pod::InteriorSequence::B<DESTROY()> =back -=over +=over 4 =item B<Pod::ParseTree> =back -=over +=over 4 -=item B<new()> +=item Pod::ParseTree-E<gt>B<new()> =back -=over +=over 4 -=item B<top()> +=item $ptree-E<gt>B<top()> =back -=over +=over 4 -=item B<children()> +=item $ptree-E<gt>B<children()> =back -=over +=over 4 -=item B<prepend()> +=item $ptree-E<gt>B<prepend()> =back -=over +=over 4 -=item B<append()> +=item $ptree-E<gt>B<append()> =back -=over +=over 4 -=item B<raw_text()> +=item $ptree-E<gt>B<raw_text()> =back -=over +=over 4 -=item B<DESTROY()> +=item Pod::ParseTree::B<DESTROY()> =back -=over +=over 4 =item SEE ALSO @@ -8928,21 +11556,141 @@ B<Pod::ParseTree> =back +=head2 Pod::LaTeX - Convert Pod data to formatted Latex + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=back + +=over 4 + +=item OBJECT METHODS + +C<initialize> + +=back + +=over 4 + +=item Data Accessors + +B<AddPreamble> + +=back + +B<AddPostamble> + +B<Head1Level> + +B<Label> + +B<LevelNoNum> + +B<MakeIndex> + +B<ReplaceNAMEwithSection> + +B<StartWithNewPage> + +B<TableOfContents> + +B<UniqueLabels> + +B<UserPreamble> + +B<UserPostamble> + +B<Lists> + +=over 4 + +=item Subclassed methods + +=back + +B<begin_pod> + +B<end_pod> + +B<command> + +B<verbatim> + +B<textblock> + +B<interior_sequence> + +=over 4 + +=item List Methods + +B<begin_list> + +=back + +B<end_list> + +B<add_item> + +=over 4 + +=item Methods for headings + +B<head> + +=back + +=over 4 + +=item Internal methods + +B<_output> + +=back + +B<_replace_special_chars> + +B<_create_label> + +B<_create_index> + +B<_clean_latex_commands> + +=over 4 + +=item NOTES + +=item SEE ALSO + +=item AUTHORS + +=item COPYRIGHT + +=item REVISION + +=back + =head2 Pod::Man - Convert POD data to formatted *roff input -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -center, date, fixed, fixedbold, fixeditalic, fixedbolditalic, release, -section +center, date, fixed, fixedbold, fixeditalic, fixedbolditalic, quotes, +release, section =item DIAGNOSTICS -roff font should be 1 or 2 chars, not `%s', Invalid link %s, Unknown escape -EE<lt>%sE<gt>, Unknown sequence %s, Unmatched =back +roff font should be 1 or 2 chars, not "%s", Invalid link %s, Invalid quote +specification "%s", %s:%d: Unknown command paragraph "%s", Unknown escape +EE<lt>%sE<gt>, Unknown sequence %s, %s: Unknown command paragraph "%s" on +line %d, Unmatched =back =item BUGS @@ -8954,7 +11702,7 @@ EE<lt>%sE<gt>, Unknown sequence %s, Unmatched =back =head2 Pod::ParseUtils - helpers for POD parsing and conversion -=over +=over 4 =item SYNOPSIS @@ -8962,93 +11710,93 @@ EE<lt>%sE<gt>, Unknown sequence %s, Unmatched =back =back -=over +=over 4 =item Pod::List -new() +Pod::List-E<gt>new() =back -file() +$list-E<gt>file() -start() +$list-E<gt>start() -indent() +$list-E<gt>indent() -type() +$list-E<gt>type() -rx() +$list-E<gt>rx() -item() +$list-E<gt>item() -parent() +$list-E<gt>parent() -tag() +$list-E<gt>tag() -=over +=over 4 =item Pod::Hyperlink -new() +Pod::Hyperlink-E<gt>new() =back -parse($string) +$link-E<gt>parse($string) -markup($string) +$link-E<gt>markup($string) -text() +$link-E<gt>text() -warning() +$link-E<gt>warning() -line(), file() +$link-E<gt>file(), $link-E<gt>line() -page() +$link-E<gt>page() -node() +$link-E<gt>node() -alttext() +$link-E<gt>alttext() -type() +$link-E<gt>type() -link() +$link-E<gt>link() -=over +=over 4 =item Pod::Cache -new() +Pod::Cache-E<gt>new() =back -item() +$cache-E<gt>item() -find_page($name) +$cache-E<gt>find_page($name) -=over +=over 4 =item Pod::Cache::Item -new() +Pod::Cache::Item-E<gt>new() =back -page() +$cacheitem-E<gt>page() -description() +$cacheitem-E<gt>description() -path() +$cacheitem-E<gt>path() -file() +$cacheitem-E<gt>file() -nodes() +$cacheitem-E<gt>nodes() -find_node($name) +$cacheitem-E<gt>find_node($name) -idx() +$cacheitem-E<gt>idx() -=over +=over 4 =item AUTHOR @@ -9058,7 +11806,7 @@ idx() =head2 Pod::Parser - base class for creating POD filters and translators -=over +=over 4 =item SYNOPSIS @@ -9077,13 +11825,13 @@ B<-warnings> (default: unset) =back -=over +=over 4 =item RECOMMENDED SUBROUTINE/METHOD OVERRIDES =back -=over +=over 4 =item B<command()> @@ -9091,7 +11839,7 @@ C<$cmd>, C<$text>, C<$line_num>, C<$pod_para> =back -=over +=over 4 =item B<verbatim()> @@ -9099,7 +11847,7 @@ C<$text>, C<$line_num>, C<$pod_para> =back -=over +=over 4 =item B<textblock()> @@ -9107,73 +11855,73 @@ C<$text>, C<$line_num>, C<$pod_para> =back -=over +=over 4 =item B<interior_sequence()> =back -=over +=over 4 =item OPTIONAL SUBROUTINE/METHOD OVERRIDES =back -=over +=over 4 =item B<new()> =back -=over +=over 4 =item B<initialize()> =back -=over +=over 4 =item B<begin_pod()> =back -=over +=over 4 =item B<begin_input()> =back -=over +=over 4 =item B<end_input()> =back -=over +=over 4 =item B<end_pod()> =back -=over +=over 4 =item B<preprocess_line()> =back -=over +=over 4 =item B<preprocess_paragraph()> =back -=over +=over 4 =item METHODS FOR PARSING AND PROCESSING =back -=over +=over 4 =item B<parse_text()> @@ -9183,109 +11931,109 @@ I<code-ref>|I<method-name> =back -=over +=over 4 =item B<interpolate()> =back -=over +=over 4 =item B<parse_paragraph()> =back -=over +=over 4 =item B<parse_from_filehandle()> =back -=over +=over 4 =item B<parse_from_file()> =back -=over +=over 4 =item ACCESSOR METHODS =back -=over +=over 4 =item B<errorsub()> =back -=over +=over 4 =item B<cutting()> =back -=over +=over 4 =item B<parseopts()> =back -=over +=over 4 =item B<output_file()> =back -=over +=over 4 =item B<output_handle()> =back -=over +=over 4 =item B<input_file()> =back -=over +=over 4 =item B<input_handle()> =back -=over +=over 4 =item B<input_streams()> =back -=over +=over 4 =item B<top_stream()> =back -=over +=over 4 =item PRIVATE METHODS AND DATA =back -=over +=over 4 =item B<_push_input_stream()> =back -=over +=over 4 =item B<_pop_input_stream()> =back -=over +=over 4 =item TREE-BASED PARSING @@ -9297,13 +12045,13 @@ I<code-ref>|I<method-name> =head2 Pod::Plainer - Perl extension for converting Pod to old style Pod. -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item EXPORT @@ -9318,7 +12066,7 @@ I<code-ref>|I<method-name> =head2 Pod::Select, podselect() - extract selected sections of POD from input -=over +=over 4 =item SYNOPSIS @@ -9334,55 +12082,55 @@ input =back -=over +=over 4 =item OBJECT METHODS =back -=over +=over 4 =item B<curr_headings()> =back -=over +=over 4 =item B<select()> =back -=over +=over 4 =item B<add_selection()> =back -=over +=over 4 =item B<clear_selections()> =back -=over +=over 4 =item B<match_section()> =back -=over +=over 4 =item B<is_selected()> =back -=over +=over 4 =item EXPORTED FUNCTIONS =back -=over +=over 4 =item B<podselect()> @@ -9390,31 +12138,31 @@ B<-output>, B<-sections>, B<-ranges> =back -=over +=over 4 =item PRIVATE METHODS AND DATA =back -=over +=over 4 =item B<_compile_section_spec()> =back -=over +=over 4 =item $self->{_SECTION_HEADINGS} =back -=over +=over 4 =item $self->{_SELECTED_SECTIONS} =back -=over +=over 4 =item SEE ALSO @@ -9424,18 +12172,19 @@ B<-output>, B<-sections>, B<-ranges> =head2 Pod::Text - Convert POD data to formatted ASCII text -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -alt, indent, loose, sentence, width +alt, indent, loose, quotes, sentence, width =item DIAGNOSTICS -Bizarre space in item, Can't open %s for reading: %s, Unknown escape: %s, -Unknown sequence: %s, Unmatched =back +Bizarre space in item, Can't open %s for reading: %s, Invalid quote +specification "%s", %s:%d: Unknown command paragraph "%s", Unknown escape: +%s, Unknown sequence: %s, Unmatched =back =item RESTRICTIONS @@ -9449,7 +12198,24 @@ Unknown sequence: %s, Unmatched =back =head2 Pod::Text::Color - Convert POD data to formatted color ASCII text -=over +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item BUGS + +=item SEE ALSO + +=item AUTHOR + +=back + +=head2 Pod::Text::Overstrike - Convert POD data to formatted overstrike +text + +=over 4 =item SYNOPSIS @@ -9466,7 +12232,7 @@ Unknown sequence: %s, Unmatched =back =head2 Pod::Text::Termcap, Pod::Text::Color - Convert POD data to ASCII text with format escapes -=over +=over 4 =item SYNOPSIS @@ -9481,7 +12247,7 @@ text with format escapes =head2 Pod::Usage, pod2usage() - print a usage message from embedded pod documentation -=over +=over 4 =item SYNOPSIS @@ -9494,7 +12260,7 @@ C<-pathlist> =item EXAMPLES -=over +=over 4 =item Recommended Use @@ -9510,17 +12276,29 @@ C<-pathlist> =head2 SDBM_File - Tied access to sdbm files -=over +=over 4 =item SYNOPSIS =item DESCRIPTION +C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR> + +=item DIAGNOSTICS + +=over 4 + +=item C<sdbm store returned -1, errno 22, key "..." at ...> + +=back + +=item BUGS AND WARNINGS + =back =head2 Safe - Compile and execute code in restricted compartments -=over +=over 4 =item SYNOPSIS @@ -9530,7 +12308,7 @@ a new namespace, an operator mask =item WARNING -=over +=over 4 =item RECENT CHANGES @@ -9553,7 +12331,7 @@ Memory, CPU, Snooping, Signals, State Changes =head2 Search::Dict, look - search for key in dictionary file -=over +=over 4 =item SYNOPSIS @@ -9563,7 +12341,7 @@ Memory, CPU, Snooping, Signals, State Changes =head2 SelectSaver - save and restore selected file handle -=over +=over 4 =item SYNOPSIS @@ -9573,13 +12351,13 @@ Memory, CPU, Snooping, Signals, State Changes =head2 SelfLoader - load functions only on demand -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item The __DATA__ token @@ -9601,12 +12379,18 @@ Memory, CPU, Snooping, Signals, State Changes =head2 Shell - run shell commands transparently within perl -=over +=over 4 =item SYNOPSIS =item DESCRIPTION +=over 4 + +=item OBJECT ORIENTED SYNTAX + +=back + =item AUTHOR =back @@ -9614,7 +12398,7 @@ Memory, CPU, Snooping, Signals, State Changes =head2 Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa - load the C socket.h defines and structure manipulators -=over +=over 4 =item SYNOPSIS @@ -9630,7 +12414,7 @@ pack_sockaddr_un PATH, unpack_sockaddr_un SOCKADDR_UN =head2 Symbol - manipulate Perl symbols and their names -=over +=over 4 =item SYNOPSIS @@ -9640,7 +12424,7 @@ pack_sockaddr_un PATH, unpack_sockaddr_un SOCKADDR_UN =head2 Sys::Hostname - Try every conceivable way to get hostname -=over +=over 4 =item SYNOPSIS @@ -9653,7 +12437,7 @@ pack_sockaddr_un PATH, unpack_sockaddr_un SOCKADDR_UN =head2 Syslog, Sys::Syslog, openlog, closelog, setlogmask, syslog - Perl interface to the UNIX syslog(3) calls -=over +=over 4 =item SYNOPSIS @@ -9674,7 +12458,7 @@ closelog =head2 Syslog::Syslog, Sys::Syslog, openlog, closelog, setlogmask, syslog - Perl interface to the UNIX syslog(3) calls -=over +=over 4 =item SYNOPSIS @@ -9694,7 +12478,7 @@ closelog =head2 Term::ANSIColor - Color screen output using ANSI escape sequences -=over +=over 4 =item SYNOPSIS @@ -9702,19 +12486,21 @@ closelog =item DIAGNOSTICS -Invalid attribute name %s, Identifier %s used only once: possible typo, No -comma allowed after filehandle, Bareword %s not allowed while "strict subs" -in use +Invalid attribute name %s, Name "%s" used only once: possible typo, No +comma allowed after filehandle, Bareword "%s" not allowed while "strict +subs" in use =item RESTRICTIONS +=item NOTES + =item AUTHORS =back =head2 Term::Cap - Perl termcap interface -=over +=over 4 =item SYNOPSIS @@ -9726,7 +12512,7 @@ in use =head2 Term::Complete - Perl word completion module -=over +=over 4 =item SYNOPSIS @@ -9745,7 +12531,7 @@ E<lt>tabE<gt>, ^D, ^U, E<lt>delE<gt>, E<lt>bsE<gt> =head2 Term::ReadLine - Perl interface to various C<readline> packages. If no real package is found, substitutes stubs instead of basic functions. -=over +=over 4 =item SYNOPSIS @@ -9768,7 +12554,7 @@ C<tkRunning>, C<ornaments>, C<newTTY> =head2 Test - provides a simple framework for writing test scripts -=over +=over 4 =item SYNOPSIS @@ -9790,13 +12576,13 @@ NORMAL TESTS, SKIPPED TESTS, TODO TESTS =head2 Test::Harness - run perl standard test scripts with statistics -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item The test script output @@ -9823,7 +12609,7 @@ C<All tests successful.\nFiles=%d, Tests=%d, %s>, C<FAILED tests =head2 Text::Abbrev, abbrev - create an abbreviation table from a list -=over +=over 4 =item SYNOPSIS @@ -9836,7 +12622,7 @@ C<All tests successful.\nFiles=%d, Tests=%d, %s>, C<FAILED tests =head2 Text::ParseWords - parse text into an array of tokens or array of arrays -=over +=over 4 =item SYNOPSIS @@ -9844,12 +12630,6 @@ arrays =item EXAMPLES -0a simple word, 1multiple spaces are skipped because of our $delim, 2use of -quotes to include a space in a word, 3use of a backslash to include a space -in a word, 4use of a backslash to remove the special meaning of a -double-quote, 5another simple word (note the lack of effect of the -backslashed double-quote) - =item AUTHORS =back @@ -9857,7 +12637,7 @@ backslashed double-quote) =head2 Text::Soundex - Implementation of the Soundex Algorithm as Described by Knuth -=over +=over 4 =item SYNOPSIS @@ -9874,7 +12654,7 @@ by Knuth =head2 Text::Tabs -- expand and unexpand tabs per the unix expand(1) and unexpand(1) -=over +=over 4 =item SYNOPSIS @@ -9888,7 +12668,7 @@ unexpand(1) =head2 Text::Wrap - line wrapping to form simple paragraphs -=over +=over 4 =item SYNOPSIS @@ -9903,7 +12683,9 @@ unexpand(1) =head2 Thread - manipulate threads in Perl (EXPERIMENTAL, subject to change) -=over +=over 4 + +=item CAVEAT =item SYNOPSIS @@ -9927,7 +12709,7 @@ join, eval, detach, equal, tid =head2 Thread::Queue - thread-safe queues -=over +=over 4 =item SYNOPSIS @@ -9943,7 +12725,7 @@ new, enqueue LIST, dequeue, dequeue_nb, pending =head2 Thread::Semaphore - thread-safe semaphores -=over +=over 4 =item SYNOPSIS @@ -9957,7 +12739,7 @@ new, new NUMBER, down, down NUMBER, up, up NUMBER =head2 Thread::Signal - Start a thread which runs signal handlers reliably -=over +=over 4 =item SYNOPSIS @@ -9969,7 +12751,7 @@ new, new NUMBER, down, down NUMBER, up, up NUMBER =head2 Thread::Specific - thread-specific keys -=over +=over 4 =item SYNOPSIS @@ -9979,11 +12761,11 @@ new, new NUMBER, down, down NUMBER, up, up NUMBER =head2 Tie::Array - base class for tied arrays -=over +=over 4 -=item SYNOPSIS +=item SYNOPSIS -=item DESCRIPTION +=item DESCRIPTION TIEARRAY classname, LIST, STORE this, index, value, FETCH this, index, FETCHSIZE this, STORESIZE this, count, EXTEND this, count, EXISTS this, @@ -9992,14 +12774,14 @@ SHIFT this, UNSHIFT this, LIST, SPLICE this, offset, length, LIST =item CAVEATS -=item AUTHOR +=item AUTHOR =back =head2 Tie::Handle, Tie::StdHandle - base class definitions for tied handles -=over +=over 4 =item SYNOPSIS @@ -10012,11 +12794,13 @@ EOF this, TELL this, SEEK this, offset, whence, DESTROY this =item MORE INFORMATION +=item COMPATIBILITY + =back =head2 Tie::Hash, Tie::StdHash - base class definitions for tied hashes -=over +=over 4 =item SYNOPSIS @@ -10033,7 +12817,7 @@ this, NEXTKEY this, lastkey, EXISTS this, key, DELETE this, key, CLEAR this =head2 Tie::RefHash - use references as hash keys -=over +=over 4 =item SYNOPSIS @@ -10052,7 +12836,7 @@ this, NEXTKEY this, lastkey, EXISTS this, key, DELETE this, key, CLEAR this =head2 Tie::Scalar, Tie::StdScalar - base class definitions for tied scalars -=over +=over 4 =item SYNOPSIS @@ -10066,7 +12850,7 @@ TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this =head2 Tie::SubstrHash - Fixed-table-size, fixed-key-length hashing -=over +=over 4 =item SYNOPSIS @@ -10078,7 +12862,7 @@ TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this =head2 Time::Local - efficiently compute time from local and GMT time -=over +=over 4 =item SYNOPSIS @@ -10093,7 +12877,7 @@ TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this =head2 Time::gmtime - by-name interface to Perl's built-in gmtime() function -=over +=over 4 =item SYNOPSIS @@ -10108,7 +12892,7 @@ function =head2 Time::localtime - by-name interface to Perl's built-in localtime() function -=over +=over 4 =item SYNOPSIS @@ -10122,7 +12906,7 @@ function =head2 Time::tm - internal object used by Time::gmtime and Time::localtime -=over +=over 4 =item SYNOPSIS @@ -10134,7 +12918,7 @@ function =head2 UNIVERSAL - base class for ALL classes (blessed references) -=over +=over 4 =item SYNOPSIS @@ -10148,7 +12932,7 @@ VAL, TYPE ), UNIVERSAL::can ( VAL, METHOD ) =head2 User::grent - by-name interface to Perl's built-in getgr*() functions -=over +=over 4 =item SYNOPSIS @@ -10163,13 +12947,13 @@ functions =head2 User::pwent - by-name interface to Perl's built-in getpw*() functions -=over +=over 4 =item SYNOPSIS =item DESCRIPTION -=over +=over 4 =item System Specifics @@ -10185,9 +12969,40 @@ March 18th, 2000 =back +=head2 Win32 - Interfaces to some Win32 API Functions + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Alphabetical Listing of Win32 Functions + +Win32::AbortSystemShutdown(MACHINE), Win32::BuildNumber(), +Win32::CopyFile(FROM, TO, OVERWRITE), Win32::DomainName(), +Win32::ExpandEnvironmentStrings(STRING), Win32::FormatMessage(ERRORCODE), +Win32::FsType(), Win32::FreeLibrary(HANDLE), Win32::GetArchName(), +Win32::GetChipName(), Win32::GetCwd(), Win32::GetFullPathName(FILENAME), +Win32::GetLastError(), Win32::GetLongPathName(PATHNAME), +Win32::GetNextAvailDrive(), Win32::GetOSVersion(), +Win32::GetShortPathName(PATHNAME), Win32::GetProcAddress(INSTANCE, +PROCNAME), Win32::GetTickCount(), Win32::InitiateSystemShutdown, +Win32::IsWinNT(), Win32::IsWin95(), Win32::LoadLibrary(LIBNAME), +Win32::LoginName(), Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, +SIDTYPE), Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE), +Win32::MsgBox(MESSAGE [, FLAGS [, TITLE]]), Win32::NodeName(), +Win32::RegisterServer(LIBRARYNAME), Win32::SetCwd(NEWDIRECTORY), +Win32::SetLastError(ERROR), Win32::Sleep(TIME), Win32::Spawn(COMMAND, ARGS, +PID), Win32::UnregisterServer(LIBRARYNAME) + +=back + +=back + =head2 XSLoader - Dynamically load C libraries into Perl code -=over +=over 4 =item SYNOPSIS @@ -10202,7 +13017,7 @@ March 18th, 2000 Here should be listed all the extra programs' documentation, but they don't all have manual pages yet: -=over +=over 4 =item a2p diff --git a/contrib/perl5/pod/perltodo.pod b/contrib/perl5/pod/perltodo.pod index f22d4737f811..f38ba88bf363 100644 --- a/contrib/perl5/pod/perltodo.pod +++ b/contrib/perl5/pod/perltodo.pod @@ -85,7 +85,7 @@ We need regression/sanity tests for suidperl This value may or may not be accurate, but it certainly is eye-catching. For some things perl5 is faster than perl4, but often -the reliability and extensability have come at a cost of speed. The +the reliability and extensibility have come at a cost of speed. The benchmark suite that Gisle released earlier has been hailed as both a fantastic solution and as a source of entirely meaningless figures. Do we need to test "real applications"? Can you do so? Anyone have @@ -111,10 +111,6 @@ problem for free. =head1 Perl Language -=head2 our ($var) - -Declare global variables (lexically or otherwise). - =head2 64-bit Perl Verify complete 64 bit support so that the value of sysseek, or C<-s>, or @@ -161,7 +157,7 @@ Sarathy, I believe, did the work. Here's what he has to say: Yeah, I hope to implement it someday too. The points that were raised in TPC2 were all to do with calling DESTROY() methods, but -I think we can accomodate that by extending bless() to stash +I think we can accommodate that by extending bless() to stash extra information for objects so we track their lifetime accurately for those that want their DESTROY() to be predictable (this will be a speed hit, naturally, and will therefore be optional, naturally. :) @@ -532,14 +528,6 @@ Kurt Starsinic is working on h2ph. mjd has fixed bugs in a2p in the past. a2p apparently doesn't work on nawk and gawk extensions. Graham Barr has an Include module that does h2ph work at runtime. -=head2 POD Converters - -Brad's PodParser code needs to become part of the core, and the Pod::* -and pod2* programs rewritten to use this standard parser. Currently -the converters take different options, some behave in different -fashions, and some are more picky than others in terms of the POD -files they accept. - =head2 pod2html A short-term fix: pod2html generates absolute HTML links. Make it @@ -863,7 +851,7 @@ See Time::HiRes. =head2 autocroak? -This is the Fatal.pm module, so any builtin that that does +This is the Fatal.pm module, so any builtin that does not return success automatically die()s. If you're feeling brave, tie this in with the unified exceptions scheme. diff --git a/contrib/perl5/pod/perltoot.pod b/contrib/perl5/pod/perltoot.pod index 31a7c76353bd..38cc1f3e6597 100644 --- a/contrib/perl5/pod/perltoot.pod +++ b/contrib/perl5/pod/perltoot.pod @@ -425,6 +425,10 @@ this could be done: Notice how there's no memory to deallocate in the destructor? That's something that Perl takes care of for you all by itself. +Alternatively, you could use the Class::Data::Inheritable module from +CPAN. + + =head2 Accessing Class Data It turns out that this is not really a good way to go about handling @@ -1700,7 +1704,7 @@ as with any other local(). It would be nice to combine Alias with something like Class::Struct or Class::MethodMaker. -=head2 NOTES +=head1 NOTES =head2 Object Terminology @@ -1727,7 +1731,7 @@ as a class or object method is by usage only. You could accidentally call a class method (one expecting a string argument) on an object (one expecting a reference), or vice versa. -Z<>From the C++ perspective, all methods in Perl are virtual. +From the C++ perspective, all methods in Perl are virtual. This, by the way, is why they are never checked for function prototypes in the argument list as regular builtin and user-defined functions can be. @@ -1750,6 +1754,16 @@ L<perltie>, and L<overload>. +L<perlboot> is a kinder, gentler introduction to object-oriented +programming. + +L<perltootc> provides more detail on class data. + +Some modules which might prove interesting are Class::Accessor, +Class::Class, Class::Contract, Class::Data::Inheritable, +Class::MethodMaker and Tie::SecureHash + + =head1 AUTHOR AND COPYRIGHT Copyright (c) 1997, 1998 Tom Christiansen diff --git a/contrib/perl5/pod/perltootc.pod b/contrib/perl5/pod/perltootc.pod index 64f8233fdbcd..d2d881c99901 100644 --- a/contrib/perl5/pod/perltootc.pod +++ b/contrib/perl5/pod/perltootc.pod @@ -12,7 +12,7 @@ the class itself. Here are a few examples where class attributes might come in handy: -=over +=over 4 =item * @@ -74,6 +74,15 @@ you can elect to permit access to them from anywhere in the entire file scope, or you can limit direct data access exclusively to the methods implementing those attributes. +=head1 Class Data in a Can + +One of the easiest ways to solve a hard problem is to let someone else +do it for you! In this case, Class::Data::Inheritable (available on a +CPAN near you) offers a canned solution to the class data problem +using closures. So before you wade into this document, consider +having a look at that module. + + =head1 Class Data as Package Variables Because a class in Perl is really just a package, using package variables @@ -184,7 +193,7 @@ to which beginning Perl programmers attempt to put symbolic references, we have much better approaches, like nested hashes or hashes of arrays. But there's nothing wrong with using symbolic references to manipulate something that is meaningful only from the perspective of the package -symbol symbol table, like method names or package variables. In other +symbol table, like method names or package variables. In other words, when you want to refer to the symbol table, use symbol references. Clustering all the class attributes in one place has several advantages. @@ -1302,7 +1311,8 @@ would just confuse the examples. L<perltoot>, L<perlobj>, L<perlmod>, and L<perlbot>. -The Tie::SecureHash module from CPAN is worth checking out. +The Tie::SecureHash and Class::Data::Inheritable modules from CPAN are +worth checking out. =head1 AUTHOR AND COPYRIGHT @@ -1334,4 +1344,4 @@ object-oriented languages enforce. =head1 HISTORY -Last edit: Fri May 21 15:47:56 MDT 1999 +Last edit: Sun Feb 4 20:50:28 EST 2001 diff --git a/contrib/perl5/pod/perltrap.pod b/contrib/perl5/pod/perltrap.pod index 261a20fb03e4..753e721fcbf0 100644 --- a/contrib/perl5/pod/perltrap.pod +++ b/contrib/perl5/pod/perltrap.pod @@ -4,10 +4,11 @@ perltrap - Perl traps for the unwary =head1 DESCRIPTION -The biggest trap of all is forgetting to use the B<-w> switch; see -L<perlrun>. The second biggest trap is not making your entire program -runnable under C<use strict>. The third biggest trap is not reading -the list of changes in this version of Perl; see L<perldelta>. +The biggest trap of all is forgetting to C<use warnings> or use the B<-w> +switch; see L<perllexwarn> and L<perlrun>. The second biggest trap is not +making your entire program runnable under C<use strict>. The third biggest +trap is not reading the list of changes in this version of Perl; see +L<perldelta>. =head2 Awk Traps @@ -116,7 +117,7 @@ The C<next>, C<exit>, and C<continue> keywords work differently. The following variables work differently: Awk Perl - ARGC $#ARGV or scalar @ARGV + ARGC scalar @ARGV (compare with $#ARGV) ARGV[0] $0 FILENAME $ARGV FNR $. - something @@ -172,12 +173,6 @@ Variables begin with "$", "@" or "%" in Perl. =item * -C<printf()> does not implement the "*" format for interpolating -field widths, but it's trivial to use interpolation of double-quoted -strings to achieve the same effect. - -=item * - Comments begin with "#", not "/*". =item * @@ -193,7 +188,7 @@ ends up in C<$0>. =item * System calls such as link(), unlink(), rename(), etc. return nonzero for -success, not 0. +success, not 0. (system(), however, returns zero for success.) =item * @@ -284,8 +279,8 @@ parentheses on function calls, you won't ever get them confused. You cannot discern from mere inspection which builtins are unary operators (like chop() and chdir()) and which are list operators (like print() and unlink()). -(User-defined subroutines can be B<only> list operators, never -unary ones.) See L<perlop>. +(Unless prototyped, user-defined subroutines can B<only> be list +operators, never unary ones.) See L<perlop> and L<perlsub>. =item * @@ -392,7 +387,7 @@ Everything else. =back If you find an example of a conversion trap that is not listed here, -please submit it to Bill Middleton <F<wjm@best.com>> for inclusion. +please submit it to <F<perlbug@perl.org>> for inclusion. Also note that at least some of these can be caught with the C<use warnings> pragma or the B<-w> switch. @@ -473,7 +468,7 @@ You can't do a C<goto> into a block that is optimized away. Darn. } # perl4 prints: Here I is! - # perl5 dumps core (SEGV) + # perl5 errors: Can't "goto" into the middle of a foreach loop =item * Discontinuance @@ -592,6 +587,12 @@ Some error messages will be different. =item * Discontinuance +In Perl 4, if in list context the delimiters to the first argument of +C<split()> were C<??>, the result would be placed in C<@_> as well as +being returned. Perl 5 has more respect for your subroutine arguments. + +=item * Discontinuance + Some bugs may have been inadvertently removed. :-) =back @@ -638,7 +639,7 @@ Better parsing in perl 5 String interpolation of the C<$#array> construct differs when braces are to used around the name. - @ = (1..3); + @a = (1..3); print "${#a}"; # perl4 prints: 2 @@ -788,7 +789,19 @@ variable is localized subsequent to the assignment Assigning C<undef> to a glob has no effect in Perl 5. In Perl 4 it undefines the associated scalar (but may have other side effects -including SEGVs). +including SEGVs). Perl 5 will also warn if C<undef> is assigned to a +typeglob. (Note that assigning C<undef> to a typeglob is different +than calling the C<undef> function on a typeglob (C<undef *foo>), which +has quite a few effects. + + $foo = "bar"; + *foo = undef; + print $foo; + + # perl4 prints: + # perl4 warns: "Use of uninitialized variable" if using -w + # perl5 prints: bar + # perl5 warns: "Undefined value assigned to typeglob" if using -w =item * (Scalar String) @@ -922,26 +935,25 @@ scalar context to its arguments. =item * (list, builtin) -C<sprintf()> funkiness (array argument converted to scalar array count) -This test could be added to t/op/sprintf.t +C<sprintf()> is prototyped as ($;@), so its first argument is given scalar +context. Thus, if passed an array, it will probably not do what you want, +unlike Perl 4: @z = ('%s%s', 'foo', 'bar'); $x = sprintf(@z); - if ($x eq 'foobar') {print "ok 2\n";} else {print "not ok 2 '$x'\n";} + print $x; - # perl4 prints: ok 2 - # perl5 prints: not ok 2 + # perl4 prints: foobar + # perl5 prints: 3 -C<printf()> works fine, though: +C<printf()> works the same as it did in Perl 4, though: + @z = ('%s%s', 'foo', 'bar'); printf STDOUT (@z); - print "\n"; # perl4 prints: foobar # perl5 prints: foobar -Probably a bug. - =back =head2 Precedence Traps @@ -1013,7 +1025,7 @@ Otherwise, perl5 leaves the statement as its default precedence: open(FOO || die); # perl4 opens or dies - # perl5 errors: Precedence problem: open FOO should be open(FOO) + # perl5 opens FOO, dying only if 'FOO' is false, i.e. never =item * Precedence @@ -1089,7 +1101,7 @@ state of the searched string is lost) } sub doit{local($_) = shift; print "Got $_ "} - # perl4 prints: blah blah blah + # perl4 prints: Got blah Got blah Got blah Got blah # perl5 prints: infinite loop blah... =item * Regular Expression @@ -1103,13 +1115,21 @@ the very first time in any such closure. For instance, if you say my($left,$right) = @_; return sub { $_[0] =~ /$left stuff $right/o; }; } + $good = build_match('foo','bar'); + $bad = build_match('baz','blarch'); + print $good->('foo stuff bar') ? "ok\n" : "not ok\n"; + print $bad->('baz stuff blarch') ? "ok\n" : "not ok\n"; + print $bad->('foo stuff bar') ? "not ok\n" : "ok\n"; + +For most builds of Perl5, this will print: +ok +not ok +not ok build_match() will always return a sub which matches the contents of $left and $right as they were the I<first> time that build_match() was called, not as they are in the current call. -This is probably a bug, and may change in future versions of Perl. - =item * Regular Expression If no parentheses are used in a match, Perl4 sets C<$+> to @@ -1207,8 +1227,8 @@ calls if a subroutine by that name is defined before the compiler sees them. $SIG{'TERM'} = SeeYa; print "SIGTERM is now $SIG{'TERM'}\n"; - # perl4 prints: SIGTERM is main'SeeYa - # perl5 prints: SIGTERM is now main::1 + # perl4 prints: SIGTERM is now main'SeeYa + # perl5 prints: SIGTERM is now main::1 (and warns "Hasta la vista, baby!") Use B<-w> to catch this one @@ -1217,10 +1237,11 @@ Use B<-w> to catch this one reverse is no longer allowed as the name of a sort subroutine. sub reverse{ print "yup "; $a <=> $b } - print sort reverse a,b,c; + print sort reverse (2,1,3); - # perl4 prints: yup yup yup yup abc - # perl5 prints: abc + # perl4 prints: yup yup 123 + # perl5 prints: 123 + # perl5 warns (if using -w): Ambiguous call resolved as CORE::reverse() =item * warn() won't let you specify a filehandle. @@ -1302,7 +1323,8 @@ within certain expressions, statements, contexts, or whatever. print "To: someone@somewhere.com\n"; # perl4 prints: To:someone@somewhere.com - # perl5 errors : In string, @somewhere now must be written as \@somewhere + # perl < 5.6.1, error : In string, @somewhere now must be written as \@somewhere + # perl >= 5.6.1, warning : Possible unintended interpolation of @somewhere in string =item * Interpolation @@ -1336,14 +1358,15 @@ Note that you can C<use strict;> to ward off such trappiness under perl5. =item * Interpolation -The construct "this is $$x" used to interpolate the pid at that -point, but now apparently tries to dereference $x. C<$$> by itself still -works fine, however. +The construct "this is $$x" used to interpolate the pid at that point, but +now tries to dereference $x. C<$$> by itself still works fine, however. + $s = "a reference"; + $x = *s; print "this is $$x\n"; # perl4 prints: this is XXXx (XXX is the current pid) - # perl5 prints: this is + # perl5 prints: this is a reference =item * Interpolation @@ -1408,14 +1431,14 @@ You also have to be careful about array references. Similarly, watch out for: - $foo = "array"; + $foo = "baz"; print "\$$foo{bar}\n"; - # perl4 prints: $array{bar} + # perl4 prints: $baz{bar} # perl5 prints: $ -Perl 5 is looking for C<$array{bar}> which doesn't exist, but perl 4 is -happy just to expand $foo to "array" by itself. Watch out for this +Perl 5 is looking for C<$foo{bar}> which doesn't exist, but perl 4 is +happy just to expand $foo to "baz" by itself. Watch out for this especially in C<eval>'s. =item * Interpolation @@ -1502,7 +1525,7 @@ Same behavior if you replace C<do> with C<require>. =item * C<split> on empty string with LIMIT specified - $string = ''; + $string = ''; @list = split(/foo/, $string, 2) Perl4 returns a one element list containing the empty string but Perl5 diff --git a/contrib/perl5/pod/perlunicode.pod b/contrib/perl5/pod/perlunicode.pod index 5333ac495c08..5b0fe2faaf26 100644 --- a/contrib/perl5/pod/perlunicode.pod +++ b/contrib/perl5/pod/perlunicode.pod @@ -1,16 +1,18 @@ =head1 NAME -perlunicode - Unicode support in Perl +perlunicode - Unicode support in Perl (EXPERIMENTAL, subject to change) =head1 DESCRIPTION =head2 Important Caveat -WARNING: The implementation of Unicode support in Perl is incomplete. + WARNING: As of the 5.6.1 release, the implementation of Unicode + support in Perl is incomplete, and continues to be highly experimental. -The following areas need further work. +The following areas need further work. They are being rapidly addressed +in the 5.7.x development branch. -=over +=over 4 =item Input and Output Disciplines @@ -114,13 +116,7 @@ will typically occur directly within the literal strings as UTF-8 characters, but you can also specify a particular character with an extension of the C<\x> notation. UTF-8 characters are specified by putting the hexadecimal code within curlies after the C<\x>. For instance, -a Unicode smiley face is C<\x{263A}>. A character in the Latin-1 range -(128..255) should be written C<\x{ab}> rather than C<\xab>, since the -former will turn into a two-byte UTF-8 code, while the latter will -continue to be interpreted as generating a 8-bit byte rather than a -character. In fact, if the C<use warnings> pragma of the C<-w> switch -is turned on, it will produce a warning -that you might be generating invalid UTF-8. +a Unicode smiley face is C<\x{263A}>. =item * @@ -163,20 +159,10 @@ C<(?:\PM\pM*)>. =item * -The C<tr///> operator translates characters instead of bytes. It can also -be forced to translate between 8-bit codes and UTF-8. For instance, if you -know your input in Latin-1, you can say: - - while (<>) { - tr/\0-\xff//CU; # latin1 char to utf8 - ... - } - -Similarly you could translate your output with - - tr/\0-\x{ff}//UC; # utf8 to latin1 char - -No, C<s///> doesn't take /U or /C (yet?). +The C<tr///> operator translates characters instead of bytes. Note +that the C<tr///CU> functionality has been removed, as the interface +was a mistake. For similar functionality see pack('U0', ...) and +pack('C0', ...). =item * @@ -214,6 +200,18 @@ byte-oriented C<chr()> and C<ord()> under utf8. =item * +The bit string operators C<& | ^ ~> can operate on character data. +However, for backward compatibility reasons (bit string operations +when the characters all are less than 256 in ordinal value) one cannot +mix C<~> (the bit complement) and characters both less than 256 and +equal or greater than 256. Most importantly, the DeMorgan's laws +(C<~($x|$y) eq ~$x&~$y>, C<~($x&$y) eq ~$x|~$y>) won't hold. +Another way to look at this is that the complement cannot return +B<both> the 8-bit (byte) wide bit complement, and the full character +wide bit complement. + +=item * + And finally, C<scalar reverse()> reverses by character rather than by byte. =back diff --git a/contrib/perl5/pod/perlvar.pod b/contrib/perl5/pod/perlvar.pod index e6b6b92f5ecf..765ff0482502 100644 --- a/contrib/perl5/pod/perlvar.pod +++ b/contrib/perl5/pod/perlvar.pod @@ -174,6 +174,8 @@ example: (Mnemonic: be positive and forward looking.) This variable is read-only and dynamically scoped to the current BLOCK. +=item @LAST_MATCH_END + =item @+ This array holds the offsets of the ends of the last successful @@ -191,17 +193,22 @@ examples given for the C<@-> variable. =item $* -Set to 1 to do multi-line matching within a string, 0 to tell Perl -that it can assume that strings contain a single line, for the purpose -of optimizing pattern matches. Pattern matches on strings containing -multiple newlines can produce confusing results when C<$*> is 0. Default -is 0. (Mnemonic: * matches multiple things.) This variable -influences the interpretation of only C<^> and C<$>. A literal newline can -be searched for even when C<$* == 0>. +Set to a non-zero integer value to do multi-line matching within a +string, 0 (or undefined) to tell Perl that it can assume that strings +contain a single line, for the purpose of optimizing pattern matches. +Pattern matches on strings containing multiple newlines can produce +confusing results when C<$*> is 0 or undefined. Default is undefined. +(Mnemonic: * matches multiple things.) This variable influences the +interpretation of only C<^> and C<$>. A literal newline can be searched +for even when C<$* == 0>. Use of C<$*> is deprecated in modern Perl, supplanted by the C</s> and C</m> modifiers on pattern matching. +Assigning a non-numerical value to C<$*> triggers a warning (and makes +C<$*> act if C<$* == 0>), while assigning a numerical value to C<$*> +makes that an implicit C<int> is applied on the value. + =item input_line_number HANDLE EXPR =item $INPUT_LINE_NUMBER @@ -412,6 +419,8 @@ channel. Used with formats. (Mnemonic: lines_on_page - lines_printed.) +=item @LAST_MATCH_START + =item @- $-[0] is the offset of the start of the last successful match. @@ -439,17 +448,17 @@ After a match against some variable $var: =over 5 -=item C<$`> is the same as C<substr($var, 0, $-[0]>) +=item C<$`> is the same as C<substr($var, 0, $-[0])> -=item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0]>) +=item C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])> -=item C<$'> is the same as C<substr($var, $+[0]>) +=item C<$'> is the same as C<substr($var, $+[0])> =item C<$1> is the same as C<substr($var, $-[1], $+[1] - $-[1])> =item C<$2> is the same as C<substr($var, $-[2], $+[2] - $-[2])> -=item C<$3> is the same as C<substr $var, $-[3], $+[3] - $-[3]>) +=item C<$3> is the same as C<substr $var, $-[3], $+[3] - $-[3])> =back @@ -819,10 +828,10 @@ Then $^M = 'a' x (1 << 16); -would allocate a 64K buffer for use when in emergency. See the +would allocate a 64K buffer for use in an emergency. See the F<INSTALL> file in the Perl distribution for information on how to enable this option. To discourage casual use of this advanced -feature, there is no L<English> long name for this variable. +feature, there is no L<English|English> long name for this variable. =item $OSNAME @@ -925,7 +934,7 @@ This can be used to determine whether the Perl interpreter executing a script is in the right range of versions. (Mnemonic: use ^V for Version Control.) Example: - warn "No "our" declarations!\n" if $^V and $^V lt v5.6.0; + warn "No \"our\" declarations!\n" if $^V and $^V lt v5.6.0; See the documentation of C<use VERSION> and C<require VERSION> for a convenient way to fail if the running Perl interpreter is too old. diff --git a/contrib/perl5/pod/perlxs.pod b/contrib/perl5/pod/perlxs.pod index 3c0927e28d14..541f75e535f4 100644 --- a/contrib/perl5/pod/perlxs.pod +++ b/contrib/perl5/pod/perlxs.pod @@ -66,14 +66,15 @@ for the library being linked. A file in XS format starts with a C language section which goes until the first C<MODULE =Z<>> directive. Other XS directives and XSUB definitions may follow this line. The "language" used in this part of the file -is usually referred to as the XS language. +is usually referred to as the XS language. B<xsubpp> recognizes and +skips POD (see L<perlpod>) in both the C and XS language sections, which +allows the XS file to contain embedded documentation. See L<perlxstut> for a tutorial on the whole extension creation process. Note: For some extensions, Dave Beazley's SWIG system may provide a -significantly more convenient mechanism for creating the extension glue -code. See L<http://www.swig.org> for more -information. +significantly more convenient mechanism for creating the extension +glue code. See http://www.swig.org/ for more information. =head2 On The Road @@ -167,21 +168,37 @@ argument and returns a single value. sin(x) double x -When using parameters with C pointer types, as in +Optionally, one can merge the description of types and the list of +argument names, rewriting this as - double string_to_double(char *s); + double + sin(double x) + +This makes this XSUB look similar to an ANSI C declaration. An optional +semicolon is allowed after the argument list, as in + + double + sin(double x); + +Parameters with C pointer types can have different semantic: C functions +with similar declarations -there may be two ways to describe this argument to B<xsubpp>: + bool string_looks_as_a_number(char *s); + bool make_char_uppercase(char *c); + +are used in absolutely incompatible manner. Parameters to these functions +could be described B<xsubpp> like this: char * s - char &s + char &c Both these XS declarations correspond to the C<char*> C type, but they have -different semantics. It is convenient to think that the indirection operator +different semantics, see L<"The & Unary Operator">. + +It is convenient to think that the indirection operator C<*> should be considered as a part of the type and the address operator C<&> -should be considered part of the variable. See L<"The Typemap"> and -L<"The & Unary Operator"> for more info about handling qualifiers and unary -operators in C types. +should be considered part of the variable. See L<"The Typemap"> +for more info about handling qualifiers and unary operators in C types. The function name and the return type must be placed on separate lines and should be flush left-adjusted. @@ -192,9 +209,9 @@ separate lines and should be flush left-adjusted. double x sin(x) double x -The function body may be indented or left-adjusted. The following example -shows a function with its body left-adjusted. Most examples in this -document will indent the body for better readability. +The rest of the function description may be indented or left-adjusted. The +following example shows a function with its body left-adjusted. Most +examples in this document will indent the body for better readability. CORRECT @@ -261,16 +278,14 @@ mercy of this heuristics unless you use C<SV *> as return value.) =head2 The MODULE Keyword -The MODULE keyword is used to start the XS code and to -specify the package of the functions which are being -defined. All text preceding the first MODULE keyword is -considered C code and is passed through to the output -untouched. Every XS module will have a bootstrap function -which is used to hook the XSUBs into Perl. The package name -of this bootstrap function will match the value of the last -MODULE statement in the XS source files. The value of -MODULE should always remain constant within the same XS -file, though this is not required. +The MODULE keyword is used to start the XS code and to specify the package +of the functions which are being defined. All text preceding the first +MODULE keyword is considered C code and is passed through to the output with +POD stripped, but otherwise untouched. Every XS module will have a +bootstrap function which is used to hook the XSUBs into Perl. The package +name of this bootstrap function will match the value of the last MODULE +statement in the XS source files. The value of MODULE should always remain +constant within the same XS file, though this is not required. The following example will start the XS code and will place all functions in a package named RPC. @@ -365,6 +380,31 @@ Likewise, C<SETMAGIC: ENABLE> can be used to reenable it for the remainder of the OUTPUT section. See L<perlguts> for more details about 'set' magic. +=head2 The NO_OUTPUT Keyword + +The NO_OUTPUT can be placed as the first token of the XSUB. This keyword +indicates that while the C subroutine we provide an interface to has +a non-C<void> return type, the return value of this C subroutine should not +be returned from the generated Perl subroutine. + +With this keyword present L<The RETVAL Variable> is created, and in the +generated call to the subroutine this variable is assigned to, but the value +of this variable is not going to be used in the auto-generated code. + +This keyword makes sense only if C<RETVAL> is going to be accessed by the +user-supplied code. It is especially useful to make a function interface +more Perl-like, especially when the C return value is just an error condition +indicator. For example, + + NO_OUTPUT int + delete_file(char *name) + POST_CALL: + if (RETVAL != 0) + croak("Error %d while deleting file '%s'", RETVAL, name); + +Here the generated XS function returns nothing on success, and will die() +with a meaningful error message on error. + =head2 The CODE: Keyword This keyword is used in more complicated XSUBs which require @@ -534,7 +574,7 @@ the parameters in the correct order for that function. =head2 The PREINIT: Keyword The PREINIT: keyword allows extra variables to be declared immediately -before or after the declartions of the parameters from the INPUT: section +before or after the declarations of the parameters from the INPUT: section are emitted. If a variable is declared inside a CODE: section it will follow any typemap @@ -714,6 +754,91 @@ thus C<host> is initialized on the declaration line, and our assignment C<h = host> is not performed too early. Otherwise one would need to have the assignment C<h = host> in a CODE: or INIT: section.) +=head2 The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords + +In the list of parameters for an XSUB, one can precede parameter names +by the C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT> keywords. +C<IN> keyword is the default, the other keywords indicate how the Perl +interface should differ from the C interface. + +Parameters preceded by C<OUTLIST>/C<IN_OUTLIST>/C<OUT>/C<IN_OUT> +keywords are considered to be used by the C subroutine I<via +pointers>. C<OUTLIST>/C<OUT> keywords indicate that the C subroutine +does not inspect the memory pointed by this parameter, but will write +through this pointer to provide additional return values. + +Parameters preceded by C<OUTLIST> keyword do not appear in the usage +signature of the generated Perl function. + +Parameters preceded by C<IN_OUTLIST>/C<IN_OUT>/C<OUT> I<do> appear as +parameters to the Perl function. With the exception of +C<OUT>-parameters, these parameters are converted to the corresponding +C type, then pointers to these data are given as arguments to the C +function. It is expected that the C function will write through these +pointers. + +The return list of the generated Perl function consists of the C return value +from the function (unless the XSUB is of C<void> return type or +C<The NO_OUTPUT Keyword> was used) followed by all the C<OUTLIST> +and C<IN_OUTLIST> parameters (in the order of appearance). On the +return from the XSUB the C<IN_OUT>/C<OUT> Perl parameter will be +modified to have the values written by the C function. + +For example, an XSUB + + void + day_month(OUTLIST day, IN unix_time, OUTLIST month) + int day + int unix_time + int month + +should be used from Perl as + + my ($day, $month) = day_month(time); + +The C signature of the corresponding function should be + + void day_month(int *day, int unix_time, int *month); + +The C<IN>/C<OUTLIST>/C<IN_OUTLIST>/C<IN_OUT>/C<OUT> keywords can be +mixed with ANSI-style declarations, as in + + void + day_month(OUTLIST int day, int unix_time, OUTLIST int month) + +(here the optional C<IN> keyword is omitted). + +The C<IN_OUT> parameters are identical with parameters introduced with +L<The & Unary Operator> and put into the C<OUTPUT:> section (see +L<The OUTPUT: Keyword>). The C<IN_OUTLIST> parameters are very similar, +the only difference being that the value C function writes through the +pointer would not modify the Perl parameter, but is put in the output +list. + +The C<OUTLIST>/C<OUT> parameter differ from C<IN_OUTLIST>/C<IN_OUT> +parameters only by the the initial value of the Perl parameter not +being read (and not being given to the C function - which gets some +garbage instead). For example, the same C function as above can be +interfaced with as + + void day_month(OUT int day, int unix_time, OUT int month); + +or + + void + day_month(day, unix_time, month) + int &day = NO_INIT + int unix_time + int &month = NO_INIT + OUTPUT: + day + month + +However, the generated Perl function is called in very C-ish style: + + my ($day, $month); + day_month($day, time, $month); + =head2 Variable-length Parameter Lists XSUBs can have variable-length parameter lists by specifying an ellipsis @@ -928,14 +1053,14 @@ rewrite this example as: OUTPUT: RETVAL -In fact, one can put this check into a CLEANUP: section as well. Together +In fact, one can put this check into a POST_CALL: section as well. Together with PREINIT: simplifications, this leads to: int rpcb_gettime(host) char *host time_t timep; - CLEANUP: + POST_CALL: if (RETVAL == 0) XSRETURN_UNDEF; @@ -956,6 +1081,16 @@ any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB. The code specified for the cleanup block will be added as the last statements in the XSUB. +=head2 The POST_CALL: Keyword + +This keyword can be used when an XSUB requires special procedures +executed after the C subroutine call is performed. When the POST_CALL: +keyword is used it must precede OUTPUT: and CLEANUP: blocks which are +present in the XSUB. + +The POST_CALL: block does not make a lot of sense when the C subroutine +call is supplied by user by providing either CODE: or PPCODE: section. + =head2 The BOOT: Keyword The BOOT: keyword is used to add code to the extension's bootstrap @@ -1233,13 +1368,19 @@ C<&> through, so the function call looks like C<rpcb_gettime(host, &timep)>. OUTPUT: timep -=head2 Inserting Comments and C Preprocessor Directives +=head2 Inserting POD, Comments and C Preprocessor Directives -C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, -CODE:, PPCODE:, and CLEANUP: blocks, as well as outside the functions. -Comments are allowed anywhere after the MODULE keyword. The compiler -will pass the preprocessor directives through untouched and will remove -the commented lines. +C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:, +PPCODE:, POST_CALL:, and CLEANUP: blocks, as well as outside the functions. +Comments are allowed anywhere after the MODULE keyword. The compiler will +pass the preprocessor directives through untouched and will remove the +commented lines. POD documentation is allowed at any point, both in the +C and XS language sections. POD must be terminated with a C<=cut> command; +C<xsubpp> will exit with an error if it does not. It is very unlikely that +human generated C code will be mistaken for POD, as most indenting styles +result in whitespace in front of any line starting with C<=>. Machine +generated XS files may fall into this trap unless care is taken to +ensure that a space breaks the sequence "\n=". Comments can be added to XSUBs by placing a C<#> as the first non-whitespace of a line. Care should be taken to avoid making the @@ -1391,7 +1532,7 @@ of failure. They may be candidates to return undef or an empty list in case of failure. If the failure may be detected without a call to the C function, you may want to use an INIT: section to report the failure. For failures detectable after the C -function returns one may want to use a CLEANUP: section to process the +function returns one may want to use a POST_CALL: section to process the failure. In more complicated cases use CODE: or PPCODE: sections. If many functions use the same failure indication based on the return value, @@ -1499,7 +1640,7 @@ getnetconfigent() XSUB and an object created by a normal Perl subroutine. The typemap is a collection of code fragments which are used by the B<xsubpp> compiler to map C function parameters and values to Perl values. The -typemap file may consist of three sections labeled C<TYPEMAP>, C<INPUT>, and +typemap file may consist of three sections labelled C<TYPEMAP>, C<INPUT>, and C<OUTPUT>. An unlabelled initial section is assumed to be a C<TYPEMAP> section. The INPUT section tells the compiler how to translate Perl values @@ -1510,10 +1651,10 @@ OUTPUT code fragments should be used to map a given C type to a Perl value. The section labels C<TYPEMAP>, C<INPUT>, or C<OUTPUT> must begin in the first column on a line by themselves, and must be in uppercase. -The default typemap in the C<ext> directory of the Perl source contains many -useful types which can be used by Perl extensions. Some extensions define -additional typemaps which they keep in their own directory. These -additional typemaps may reference INPUT and OUTPUT maps in the main +The default typemap in the C<lib/ExtUtils> directory of the Perl source +contains many useful types which can be used by Perl extensions. Some +extensions define additional typemaps which they keep in their own directory. +These additional typemaps may reference INPUT and OUTPUT maps in the main typemap. The B<xsubpp> compiler will allow the extension's own typemap to override any mappings which are in the default typemap. @@ -1636,4 +1777,4 @@ This document covers features supported by C<xsubpp> 1.935. Originally written by Dean Roehrich <F<roehrich@cray.com>>. -Maintained since 1996 by The Perl Porters <F<perlbug@perl.com>>. +Maintained since 1996 by The Perl Porters <F<perlbug@perl.org>>. diff --git a/contrib/perl5/pod/perlxstut.pod b/contrib/perl5/pod/perlxstut.pod index d79f4b989ad3..f06e16632690 100644 --- a/contrib/perl5/pod/perlxstut.pod +++ b/contrib/perl5/pod/perlxstut.pod @@ -5,8 +5,8 @@ perlXStut - Tutorial for writing XSUBs =head1 DESCRIPTION This tutorial will educate the reader on the steps involved in creating -a Perl extension. The reader is assumed to have access to L<perlguts> and -L<perlxs>. +a Perl extension. The reader is assumed to have access to L<perlguts>, +L<perlapi> and L<perlxs>. This tutorial starts with very simple examples and becomes more complex, with each new example adding new features. Certain concepts may not be @@ -187,7 +187,8 @@ been deleted): Manifying ./blib/man3/Mytest.3 % -You can safely ignore the line about "prototyping behavior". +You can safely ignore the line about "prototyping behavior" - it is +explained in the section "The PROTOTYPES: Keyword" in L<perlxs>. If you are on a Win32 system, and the build process fails with linker errors for functions in the C library, check if your Perl is configured @@ -476,7 +477,7 @@ section on the argument stack. In general, it's not a good idea to write extensions that modify their input parameters, as in Example 3. Instead, you should probably return multiple values in an array and let the caller handle them (we'll do this in a later -example). However, in order to better accomodate calling pre-existing C +example). However, in order to better accommodate calling pre-existing C routines, which often do modify their input parameters, this behavior is tolerated. @@ -681,7 +682,8 @@ the meaning of these elements, pay attention to the line which reads Anything before this line is plain C code which describes which headers to include, and defines some convenience functions. No translations are -performed on this part, it goes into the generated output C file as is. +performed on this part, apart from having embedded POD documentation +skipped over (see L<perlpod>) it goes into the generated output C file as is. Anything after this line is the description of XSUB functions. These descriptions are translated by B<xsubpp> into C code which @@ -1056,9 +1058,143 @@ the stack is I<always> large enough to take one return value. =back -=head2 EXAMPLE 6 (Coming Soon) +=head2 EXAMPLE 6 -Passing in and returning references to arrays and/or hashes +In this example, we will accept a reference to an array as an input +parameter, and return a reference to an array of hashes. This will +demonstrate manipulation of complex Perl data types from an XSUB. + +This extension is somewhat contrived. It is based on the code in +the previous example. It calls the statfs function multiple times, +accepting a reference to an array of filenames as input, and returning +a reference to an array of hashes containing the data for each of the +filesystems. + +Return to the Mytest directory and add the following code to the end of +Mytest.xs: + + SV * + multi_statfs(paths) + SV * paths + INIT: + AV * results; + I32 numpaths = 0; + int i, n; + struct statfs buf; + + if ((!SvROK(paths)) + || (SvTYPE(SvRV(paths)) != SVt_PVAV) + || ((numpaths = av_len((AV *)SvRV(paths))) < 0)) + { + XSRETURN_UNDEF; + } + results = (AV *)sv_2mortal((SV *)newAV()); + CODE: + for (n = 0; n <= numpaths; n++) { + HV * rh; + STRLEN l; + char * fn = SvPV(*av_fetch((AV *)SvRV(paths), n, 0), l); + + i = statfs(fn, &buf); + if (i != 0) { + av_push(results, newSVnv(errno)); + continue; + } + + rh = (HV *)sv_2mortal((SV *)newHV()); + + hv_store(rh, "f_bavail", 8, newSVnv(buf.f_bavail), 0); + hv_store(rh, "f_bfree", 7, newSVnv(buf.f_bfree), 0); + hv_store(rh, "f_blocks", 8, newSVnv(buf.f_blocks), 0); + hv_store(rh, "f_bsize", 7, newSVnv(buf.f_bsize), 0); + hv_store(rh, "f_ffree", 7, newSVnv(buf.f_ffree), 0); + hv_store(rh, "f_files", 7, newSVnv(buf.f_files), 0); + hv_store(rh, "f_type", 6, newSVnv(buf.f_type), 0); + + av_push(results, newRV((SV *)rh)); + } + RETVAL = newRV((SV *)results); + OUTPUT: + RETVAL + +And add the following code to test.pl, while incrementing the "1..11" +string in the BEGIN block to "1..13": + + $results = Mytest::multi_statfs([ '/', '/blech' ]); + print ((ref $results->[0]) ? "ok 12\n" : "not ok 12\n"); + print ((! ref $results->[1]) ? "ok 13\n" : "not ok 13\n"); + +=head2 New Things in this Example + +There are a number of new concepts introduced here, described below: + +=over 4 + +=item * + +This function does not use a typemap. Instead, we declare it as accepting +one SV* (scalar) parameter, and returning an SV* value, and we take care of +populating these scalars within the code. Because we are only returning +one value, we don't need a C<PPCODE:> directive - instead, we use C<CODE:> +and C<OUTPUT:> directives. + +=item * + +When dealing with references, it is important to handle them with caution. +The C<INIT:> block first checks that +C<SvROK> returns true, which indicates that paths is a valid reference. It +then verifies that the object referenced by paths is an array, using C<SvRV> +to dereference paths, and C<SvTYPE> to discover its type. As an added test, +it checks that the array referenced by paths is non-empty, using the C<av_len> +function (which returns -1 if the array is empty). The XSRETURN_UNDEF macro +is used to abort the XSUB and return the undefined value whenever all three of +these conditions are not met. + +=item * + +We manipulate several arrays in this XSUB. Note that an array is represented +internally by an AV* pointer. The functions and macros for manipulating +arrays are similar to the functions in Perl: C<av_len> returns the highest +index in an AV*, much like $#array; C<av_fetch> fetches a single scalar value +from an array, given its index; C<av_push> pushes a scalar value onto the +end of the array, automatically extending the array as necessary. + +Specifically, we read pathnames one at a time from the input array, and +store the results in an output array (results) in the same order. If +statfs fails, the element pushed onto the return array is the value of +errno after the failure. If statfs succeeds, though, the value pushed +onto the return array is a reference to a hash containing some of the +information in the statfs structure. + +As with the return stack, it would be possible (and a small performance win) +to pre-extend the return array before pushing data into it, since we know +how many elements we will return: + + av_extend(results, numpaths); + +=item * + +We are performing only one hash operation in this function, which is storing +a new scalar under a key using C<hv_store>. A hash is represented by an HV* +pointer. Like arrays, the functions for manipulating hashes from an XSUB +mirror the functionality available from Perl. See L<perlguts> and L<perlapi> +for details. + +=item * + +To create a reference, we use the C<newRV> function. Note that you can +cast an AV* or an HV* to type SV* in this case (and many others). This +allows you to take references to arrays, hashes and scalars with the same +function. Conversely, the C<SvRV> function always returns an SV*, which may +need to be be cast to the appropriate type if it is something other than a +scalar (check with C<SvTYPE>). + +=item * + +At this point, xsubpp is doing very little work - the differences between +Mytest.xs and Mytest.c are minimal. + +=back =head2 EXAMPLE 7 (Coming Soon) @@ -1112,7 +1248,7 @@ Some systems may have installed Perl version 5 as "perl5". =head1 See also -For more information, consult L<perlguts>, L<perlxs>, L<perlmod>, +For more information, consult L<perlguts>, L<perlapi>, L<perlxs>, L<perlmod>, and L<perlpod>. =head1 Author diff --git a/contrib/perl5/pod/pod2latex.PL b/contrib/perl5/pod/pod2latex.PL index 71115f3f2144..3d3cfb65bcdd 100644 --- a/contrib/perl5/pod/pod2latex.PL +++ b/contrib/perl5/pod/pod2latex.PL @@ -34,676 +34,314 @@ $Config{startperl} # In the following, perl variables are not expanded during extraction. print OUT <<'!NO!SUBS!'; -# -# pod2latex, version 1.1 -# by Taro Kawagish (kawagish@imslab.co.jp), Jan 11, 1995. -# -# pod2latex filters Perl pod documents to LaTeX documents. -# -# What pod2latex does: -# 1. Pod file 'perl_doc_entry.pod' is filtered to 'perl_doc_entry.tex'. -# 2. Indented paragraphs are translated into -# '\begin{verbatim} ... \end{verbatim}'. -# 3. '=head1 heading' command is translated into '\section{heading}' -# 4. '=head2 heading' command is translated into '\subsection*{heading}' -# 5. '=over N' command is translated into -# '\begin{itemize}' if following =item starts with *, -# '\begin{enumerate}' if following =item starts with 1., -# '\begin{description}' if else. -# (indentation level N is ignored.) -# 6. '=item * heading' command is translated into '\item heading', -# '=item 1. heading' command is translated into '\item heading', -# '=item heading' command(other) is translated into '\item[heading]'. -# 7. '=back' command is translated into -# '\end{itemize}' if started with '\begin{itemize}', -# '\end{enumerate}' if started with '\begin{enumerate}', -# '\end{description}' if started with '\begin{description}'. -# 8. other paragraphs are translated into strings with TeX special characters -# escaped. -# 9. In heading text, and other paragraphs, the following translation of pod -# quotes are done, and then TeX special characters are escaped after that. -# I<text> to {\em text\/}, -# B<text> to {\bf text}, -# S<text> to text1, -# where text1 is a string with blank characters replaced with ~, -# C<text> to {\tt text2}, -# where text2 is a string with TeX special characters escaped to -# obtain a literal printout, -# E<text> (HTML escape) to TeX escaped string, -# L<text> to referencing string as is done by pod2man, -# F<file> to {\em file\/}, -# Z<> to a null string, -# 10. those headings are indexed: -# '=head1 heading' => \section{heading}\index{heading} -# '=head2 heading' => \subsection*{heading}\index{heading} -# only when heading does not match frequent patterns such as -# DESCRIPTION, DIAGNOSTICS,... -# '=item heading' => \item{heading}\index{heading} -# -# Usage: -# pod2latex perl_doc_entry.pod -# this will write to a file 'perl_doc_entry.tex'. -# -# To LaTeX: -# The following commands need to be defined in the preamble of the LaTeX -# document: -# \def\C++{{\rm C\kern-.05em\raise.3ex\hbox{\footnotesize ++}}} -# \def\underscore{\leavevmode\kern.04em\vbox{\hrule width 0.4em height 0.3pt}} -# and \parindent should be set zero: -# \setlength{\parindent}{0pt} -# -# Note: -# This script was written modifing pod2man. -# -# Bug: -# If HTML escapes E<text> other than E<amp>,E<lt>,E<gt>,E<quot> are used -# in C<>, translation will produce wrong character strings. -# Translation of HTML escapes of various European accents might be wrong. - - -# TeX special characters. -##$tt_ables = "!@*()-=+|;:'\"`,./?<>"; -$backslash_escapables = "#\$%&{}_"; -$backslash_escapables2 = "#\$%&{}"; # except _ -##$nonverbables = "^\\~"; -##$bracketesc = "[]"; -##@tex_verb_fences = unpack("aaaaaaaaa","|#@!*+?:;"); - -@head1_freq_patterns # =head1 patterns which need not be index'ed - = ("AUTHOR","Author","BUGS","DATE","DESCRIPTION","DIAGNOSTICS", - "ENVIRONMENT","EXAMPLES","FILES","INTRODUCTION","NAME","NOTE", - "SEE ALSO","SYNOPSIS","WARNING"); - -$indent = 0; - -# parse the pods, produce LaTeX. - -use Pod::Plainer; -open(POD,"-|") or Pod::Plainer -> new() -> parse_from_file($ARGV[0]), exit; - -($pod=$ARGV[0]) =~ s/\.pod$//; -open(LATEX,">$pod.tex"); -&do_hdr(); - -$cutting = 1; -$begun = ""; -$/ = ""; # record separator is blank lines -while (<POD>) { - if ($cutting) { - next unless /^=/; - $cutting = 0; - } - if ($begun) { - if (/^=end\s+$begun/) { - $begun = ""; - } - elsif ($begun =~ /^(tex|latex)$/) { - print LATEX $_; - } - next; - } - chop; - length || (print LATEX "\n") && next; - - # translate indented lines as a verabatim paragraph - if (/^\s/) { - @lines = split(/\n/); - print LATEX "\\begin{verbatim}\n"; - for (@lines) { - 1 while s - {^( [^\t]* ) \t ( \t* ) } - { $1 . ' ' x (8 - (length($1)%8) + 8*(length($2))) }ex; - print LATEX $_,"\n"; - } - print LATEX "\\end{verbatim}\n"; - next; - } - if (/^=for\s+(\S+)\s*/s) { - if ($1 eq "tex" or $1 eq "latex") { - print LATEX $',"\n"; - } else { - # ignore unknown for - } - next; - } - elsif (/^=begin\s+(\S+)\s*/s) { - $begun = $1; - if ($1 eq "tex" or $1 eq "latex") { - print LATEX $'."\n"; - } - next; - } +# pod2latex conversion program + +use Pod::LaTeX; +use Pod::Find qw/ pod_find /; +use Pod::Usage; +use Getopt::Long; +use File::Basename; + +# Read command line arguments + +my %options = ( + "help" => 0, + "man" => 0, + "sections" => [], + "full" => 0, + "out" => undef, + "verbose" => 0, + "modify" => 0, + ); + +GetOptions(\%options, + "help", + "man", + "verbose", + "full", + "sections=s@", + "out=s", + "modify", + ) || pod2usage(2); + +pod2usage(1) if ($options{help}); +pod2usage(-verbose => 2) if ($options{man}); + + +# Read all the files from the command line +my @files = @ARGV; + +# Now find which ones are real pods and convert +# directories to their contents. + +# Extract the pods from each arg since some of them might +# be directories +# This is not as efficient as using pod_find to search through +# everything at once but it allows us to preserve the order +# supplied by the user + +my @pods; +foreach my $arg (@files) { + my %pods = pod_find($arg); + push(@pods, sort keys %pods); +} - # preserve '=item' line with pod quotes as they are. - if (/^=item/) { - ($bareitem = $_) =~ s/^=item\s*//; - } +# Abort if nothing to do +if ($#pods == -1) { + warn "None of the supplied Pod files actually exist\n"; + exit; +} - # check for things that'll hosed our noremap scheme; affects $_ - &init_noremap(); - - # expand strings "func()" as pod quotes. - if (!/^=item/) { - # first hide pod escapes. - # escaped strings are mapped into the ones with the MSB's on. - s/([A-Z]<[^<>]*>)/noremap($1)/ge; - - # func() is a reference to a perl function - s{\b([:\w]+\(\))}{I<$1>}g; - # func(n) is a reference to a man page - s{(\w+)(\([^\s,\051]+\))}{I<$1>$2}g; - # convert simple variable references -# s/([\$\@%][\w:]+)/C<$1>/g; -# s/\$[\w:]+\[[0-9]+\]/C<$&>/g; - - if (m{ ([\-\w]+\([^\051]*?[\@\$,][^\051]*?\)) - }x && $` !~ /([LCI]<[^<>]*|-)$/ && !/^=\w/) - { - warn "``$1'' should be a [LCI]<$1> ref"; - } - while (/(-[a-zA-Z])\b/g && $` !~ /[\w\-]$/) { - warn "``$1'' should be [CB]<$1> ref"; - } - - # put back pod quotes so we get the inside of <> processed; - $_ = &clear_noremap($_); - } - # process TeX special characters - - # First hide HTML quotes E<> since they can be included in C<>. - s/(E<[^<>]+>)/noremap($1)/ge; - - # Then hide C<> type literal quotes. - # String inside of C<> will later be expanded into {\tt ..} strings - # with TeX special characters escaped as needed. - s/(C<[^<>]*>)/&noremap($1)/ge; - - # Next escape TeX special characters including other pod quotes B< >,... - # - # NOTE: s/re/&func($str)/e evaluates $str just once in perl5. - # (in perl4 evaluation takes place twice before getting passed to func().) - - # - hyphen => --- - s/(\S+)(\s+)-+(\s+)(\S+)/"$1".&noremap(" --- ")."$4"/ge; - # '-', '--', "-" => '{\tt -}', '{\tt --}', "{\tt -}" -## s/("|')(\s*)(-+)(\s*)\1/&noremap("$1$2\{\\tt $3\}$4$1")/ge; -## changed Wed Jan 25 15:26:39 JST 1995 - # '-', '--', "-" => '$-$', '$--$', "$-$" - s/(\s+)(['"])(-+)([^'"\-]*)\2(\s+|[,.])/"$1$2".&noremap("\$$3\$")."$4$2$5"/ge; - s/(\s+)(['"])([^'"\-]*)(-+)(\s*)\2(\s+|[,.])/"$1$2$3".&noremap("\$$4\$")."$5$2$6"/ge; - # (--|-) => ($--$|$-$) - s/(\s+)\((-+)([=@%\$\+\\\|\w]*)(-*)([=@%\$\+\\\|\w]*)\)(\s+|[,.])/"$1\(".&noremap("\$$2\$")."$3".&noremap("\$$4\$")."$5\)$6"/ge; - # numeral - => $-$ - s/(\(|[0-9]+|\s+)-(\s*\(?\s*[0-9]+)/&noremap("$1\$-\$$2")/ge; - # -- in quotes => two separate - - s/B<([^<>]*)--([^<>]*)>/&noremap("B<$1\{\\tt --\}$2>")/ge; - - # backslash escapable characters except _. - s/([$backslash_escapables2])/&noremap("\\$1")/ge; - s/_/&noremap("\\underscore{}")/ge; # a litle thicker than \_. - # quote TeX special characters |, ^, ~, \. - s/\|/&noremap("\$|\$")/ge; - s/\^/&noremap("\$\\hat{\\hspace{0.4em}}\$")/ge; - s/\~/&noremap("\$\\tilde{\\hspace{0.4em}}\$")/ge; - s/\\/&noremap("\$\\backslash{}\$")/ge; - # quote [ and ] to be used in \item[] - s/([\[\]])/&noremap("{\\tt $1}")/ge; - # characters need to be treated differently in TeX - # keep * if an item heading - s/^(=item[ \t]+)[*]((.|\n)*)/"$1" . &noremap("*") . "$2"/ge; - s/[*]/&noremap("\$\\ast\$")/ge; # other * - - # hide other pod quotes. - s/([ABD-Z]<[^<>]*>)/&noremap($1)/ge; - - # escape < and > as math strings, - # now that we are done with hiding pod <> quotes. - s/</&noremap("\$<\$")/ge; - s/>/&noremap("\$>\$")/ge; - - # put it back so we get the <> processed again; - $_ = &clear_noremap($_); - - - # Expand pod quotes recursively: - # (1) type face directives [BIFS]<[^<>]*> to appropriate TeX commands, - # (2) L<[^<>]*> to reference strings, - # (3) C<[^<>]*> to TeX literal quotes, - # (4) HTML quotes E<> inside of C<> quotes. - - # Hide E<> again since they can be included in C<>. - s/(E<[^<>]+>)/noremap($1)/ge; - - $maxnest = 10; - while ($maxnest-- && /[A-Z]</) { - - # bold and italic quotes - s/B<([^<>]*)>/"{\\bf $1}"/eg; - s#I<([^<>]*)>#"{\\em $1\\/}"#eg; - - # files and filelike refs in italics - s#F<([^<>]*)>#"{\\em $1\\/}"#eg; - - # no break quote -- usually we want C<> for this - s/S<([^<>]*)>/&nobreak($1)/eg; - - # LREF: a manpage(3f) - s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:the {\\em $1\\/}$2 manpage:g; - - # LREF: an =item on another manpage - s{ - L<([^/]+)/([:\w]+(\(\))?)> - } {the C<$2> entry in the I<$1> manpage}gx; - - # LREF: an =item on this manpage - s{ - ((?:L</([:\w]+(\(\))?)> - (,?\s+(and\s+)?)?)+) - } { &internal_lrefs($1) }gex; - - # LREF: a =head2 (head1?), maybe on a manpage, maybe right here - # the "func" can disambiguate - s{ - L<(?:([a-zA-Z]\S+?) /)?"?(.*?)"?> - }{ - do { - $1 # if no $1, assume it means on this page. - ? "the section on I<$2> in the I<$1> manpage" - : "the section on I<$2>" - } - }gex; - - s/X<([^<>]*)>/\\index{$1}/g; - - s/Z<>/\\&/g; # the "don't format me" thing - - # comes last because not subject to reprocessing - s{ - C<([^<>]*)> - }{ - do { - ($str = $1) =~ tr/\200-\377/\000-\177/; #normalize hidden stuff - # expand HTML escapes if any; - # WARNING: if HTML escapes other than E<amp>,E<lt>,E<gt>, - # E<quot> are in C<>, they will not be printed correctly. - $str = &expand_HTML_escapes($str); - $strverb = &alltt($str); # Tex verbatim escape of a string. - &noremap("$strverb"); - } - }gex; - -# if ( /C<([^<>]*)/ ) { -# $str = $1; -# if ($str !~ /\|/) { # if includes | -# s/C<([^<>]*)>/&noremap("\\verb|$str|")/eg; -# } else { -# print STDERR "found \| in C<.*> at paragraph $.\n"; -# # find a character not contained in $str to use it as a -# # separator of the \verb -# ($chars = $str) =~ s/(\W)/\\$1/g; -# ## ($chars = $str) =~ s/([\$<>,\|"'\-^{}()*+?\\])/\\$1/g; -# @fence = grep(!/[ $chars]/,@tex_verb_fences); -# s/C<([^<>]*)>/&noremap("\\verb$fence[0]$str$fence[0]")/eg; -# } -# } - } +# If $options{'out'} is set we are processing to a single output file +my $multi_documents; +if (exists $options{'out'} && defined $options{'out'}) { + $multi_documents = 0; +} else { + $multi_documents = 1; +} + +# If the output file is not specified it is assumed that +# a single output file is required per input file using +# a .tex extension rather than any exisiting extension + +if ($multi_documents) { + + # Case where we just generate one input per output + + foreach my $pod (@pods) { + + if (-f $pod) { + + my $output = $pod; + $output = basename($output, '.pm', '.pod','.pl') . '.tex'; + # Create a new parser object + my $parser = new Pod::LaTeX( + AddPreamble => $options{'full'}, + AddPostamble => $options{'full'}, + MakeIndex => $options{'full'}, + TableOfContents => $options{'full'}, + ReplaceNAMEwithSection => $options{'modify'}, + UniqueLabels => $options{'modify'}, + ); - # process each pod command - if (s/^=//) { # if a command - s/\n/ /g; - ($cmd, $rest) = split(' ', $_, 2); - $rest =~ s/^\s*//; - $rest =~ s/\s*$//; - - if (defined $rest) { - &escapes; - } - - $rest = &clear_noremap($rest); - $rest = &expand_HTML_escapes($rest); - - if ($cmd eq 'cut') { - $cutting = 1; - $lastcmd = 'cut'; - } - elsif ($cmd eq 'head1') { # heading type 1 - $rest =~ s/^\s*//; $rest =~ s/\s*$//; - print LATEX "\n\\subsection*{$rest}"; - # put index entry - ($index = $rest) =~ s/^(An?\s+|The\s+)//i; # remove 'A' and 'The' - # index only those heads not matching the frequent patterns. - foreach $pat (@head1_freq_patterns) { - if ($index =~ /^$pat/) { - goto freqpatt; - } - } - print LATEX "%\n\\index{$index}\n" if ($index); - freqpatt: - $lastcmd = 'head1'; - } - elsif ($cmd eq 'head2') { # heading type 2 - $rest =~ s/^\s*//; $rest =~ s/\s*$//; - print LATEX "\n\\subsubsection*{$rest}"; - # put index entry - ($index = $rest) =~ s/^(An?\s+|The\s+)//i; # remove 'A' and 'The' - $index =~ s/^Example\s*[1-9][0-9]*\s*:\s*//; # remove 'Example :' - print LATEX "%\n\\index{$index}\n" if ($index); - $lastcmd = 'head2'; - } - elsif ($cmd eq 'over') { # 1 level within a listing environment - push(@indent,$indent); - $indent = $rest + 0; - $lastcmd = 'over'; - } - elsif ($cmd eq 'back') { # 1 level out of a listing environment - $indent = pop(@indent); - warn "Unmatched =back\n" unless defined $indent; - $listingcmd = pop(@listingcmd); - print LATEX "\n\\end{$listingcmd}\n" if ($listingcmd); - $lastcmd = 'back'; - } - elsif ($cmd eq 'item') { # an item paragraph starts - if ($lastcmd eq 'over') { # if we have just entered listing env - # see what type of list environment we are in. - if ($rest =~ /^[0-9]\.?/) { # if numeral heading - $listingcmd = 'enumerate'; - } elsif ($rest =~ /^\*\s*/) { # if * heading - $listingcmd = 'itemize'; - } elsif ($rest =~ /^[^*]/) { # if other headings - $listingcmd = 'description'; - } else { - warn "unknown list type for item $rest"; - } - print LATEX "\n\\begin{$listingcmd}\n"; - push(@listingcmd,$listingcmd); - } elsif ( !@listingcmd ) { - warn "Illegal '=item' command without preceding 'over':"; - warn "=item $bareitem"; - } - - if ($listingcmd eq 'enumerate') { - $rest =~ s/^[0-9]+\.?\s*//; # remove numeral heading - print LATEX "\n\\item"; - print LATEX "{\\bf $rest}" if $rest; - } elsif ($listingcmd eq 'itemize') { - $rest =~ s/^\*\s*//; # remove * heading - print LATEX "\n\\item"; - print LATEX "{\\bf $rest}" if $rest; - } else { # description item - print LATEX "\n\\item[$rest]"; - } - $lastcmd = 'item'; - $rightafter_item = 'yes'; - - # check if the item heading is short or long. - ($itemhead = $rest) =~ s/{\\bf (\S*)}/$1/g; - if (length($itemhead) < 4) { - $itemshort = "yes"; - } else { - $itemshort = "no"; - } - # write index entry - if ($pod =~ "perldiag") { # skip 'perldiag.pod' - goto noindex; - } - # strip out the item of pod quotes and get a plain text entry - $bareitem =~ s/\n/ /g; # remove newlines - $bareitem =~ s/\s*$//; # remove trailing space - $bareitem =~ s/[A-Z]<([^<>]*)>/$1/g; # remove <> quotes - ($index = $bareitem) =~ s/^\*\s+//; # remove leading '*' - $index =~ s/^(An?\s+|The\s+)//i; # remove 'A' and 'The' - $index =~ s/^\s*[1-9][0-9]*\s*[.]\s*$//; # remove numeral only - $index =~ s/^\s*\w\s*$//; # remove 1 char only's - # quote ", @ and ! with " to be used in makeindex. - $index =~ s/"/""/g; # quote " - $index =~ s/@/"@/g; # quote @ - $index =~ s/!/"!/g; # quote ! - ($rest2=$rest) =~ s/^\*\s+//; # remove * - $rest2 =~ s/"/""/g; # quote " - $rest2 =~ s/@/"@/g; # quote @ - $rest2 =~ s/!/"!/g; # quote ! - if ($pod =~ "(perlfunc|perlvar)") { # when doc is perlfunc,perlvar - # take only the 1st word of item heading - $index =~ s/^([^{}\s]*)({.*})?([^{}\s]*)\s+.*/\1\2\3/; - $rest2 =~ s/^([^{}\s]*)({.*})?([^{}\s]*)\s+.*/\1\2\3/; - } - if ($index =~ /[A-Za-z\$@%]/) { - # write \index{plain_text_entry@TeX_string_entry} - print LATEX "%\n\\index{$index\@$rest2}%\n"; - } - noindex: - ; - } - elsif ($cmd eq 'pod') { - ; # recognise the pod directive, as no op (hs) - } - elsif ($cmd eq 'pod') { - ; # recognise the pod directive, as no op (hs) - } - else { - warn "Unrecognized directive: $cmd\n"; - } + # Select sections if supplied + $parser->select(@{ $options{'sections'}}) + if @{$options{'sections'}}; + + # Derive the input file from the output file + $parser->parse_from_file($pod, $output); + + print "Written output to $output\n" if $options{'verbose'}; + + } else { + warn "File $pod not found\n"; } - else { # if not command - &escapes; - $_ = &clear_noremap($_); - $_ = &expand_HTML_escapes($_); - - # if the present paragraphs follows an =item declaration, - # put a line break. - if ($lastcmd eq 'item' && - $rightafter_item eq 'yes' && $itemshort eq "no") { - print LATEX "\\hfil\\\\"; - $rightafter_item = 'no'; - } - print LATEX "\n",$_; + + } +} else { + + # Case where we want everything to be in a single document + + # Need to open the output file ourselves + my $output = $options{'out'}; + $output .= '.tex' unless $output =~ /\.tex$/; + + # Use auto-vivified file handle in perl 5.6 + use Symbol; + my $outfh = gensym; + open ($outfh, ">$output") || die "Could not open output file: $!\n"; + + # Flag to indicate whether we have converted at least one file + # indicates how many files have been converted + my $converted = 0; + + # Loop over the input files + foreach my $pod (@pods) { + + if (-f $pod) { + + warn "Converting $pod\n" if $options{'verbose'}; + + # Open the file (need the handle) + # Use auto-vivified handle in perl 5.6 + my $podfh = gensym; + open ($podfh, "<$pod") || die "Could not open pod file $pod: $!\n"; + + # if this is the first file to be converted we may want to add + # a preamble (controlled by command line option) + if ($converted == 0 && $options{'full'}) { + $preamble = 1; + } else { + $preamble = 0; + } + + # if this is the last file to be converted may want to add + # a postamble (controlled by command line option) + # relies on a previous pass to check existence of all pods we + # are converting. + my $postamble = ( ($converted == $#pods && $options{'full'}) ? 1 : 0 ); + + # Open parser object + # May want to start with a preamble for the first one and + # end with an index for the last + my $parser = new Pod::LaTeX( + MakeIndex => $options{'full'}, + TableOfContents => $preamble, + ReplaceNAMEwithSection => $options{'modify'}, + UniqueLabels => $options{'modify'}, + StartWithNewPage => $options{'full'}, + AddPreamble => $preamble, + AddPostamble => $postamble, + ); + + # Store the file name for error messages + # This is a kluge that breaks the data hiding of the object + $parser->{_INFILE} = $pod; + + # Select sections if supplied + $parser->select(@{ $options{'sections'}}) + if @{$options{'sections'}}; + + # Parse it + $parser->parse_from_filehandle($podfh, $outfh); + + # We have converted at least one file + $converted++; + + } else { + warn "File $pod not found\n"; } -} -print LATEX "\n"; -close(POD); -close(LATEX); + } + # Should unlink the file if we didn't convert anything! + # dont check for return status of unlink + # since there is not a lot to be done if the unlink failed + # and the program does not rely upon it. + unlink "$output" unless $converted; -######################################################################### + # If verbose + warn "Converted $converted files\n" if $options{'verbose'}; -sub do_hdr { - print LATEX "% LaTeX document produced by pod2latex from \"$pod.pod\".\n"; - print LATEX "% The followings need be defined in the preamble of this document:\n"; - print LATEX "%\\def\\C++{{\\rm C\\kern-.05em\\raise.3ex\\hbox{\\footnotesize ++}}}\n"; - print LATEX "%\\def\\underscore{\\leavevmode\\kern.04em\\vbox{\\hrule width 0.4em height 0.3pt}}\n"; - print LATEX "%\\setlength{\\parindent}{0pt}\n"; - print LATEX "\n"; - $podq = &escape_tex_specials("\U$pod\E"); - print LATEX "\\section{$podq}%\n"; - print LATEX "\\index{$podq}"; - print LATEX "\n"; } -sub nobreak { - my $string = shift; - $string =~ s/ +/~/g; # TeX no line break - $string; -} +exit; -sub noremap { - local($thing_to_hide) = shift; - $thing_to_hide =~ tr/\000-\177/\200-\377/; - return $thing_to_hide; -} +__END__ -sub init_noremap { - # escape high bit characters in input stream - s/([\200-\377])/"E<".ord($1).">"/ge; -} +=head1 NAME -sub clear_noremap { - local($tmp) = shift; - $tmp =~ tr/\200-\377/\000-\177/; - return $tmp; -} +pod2latex - convert pod documentation to latex format -sub expand_HTML_escapes { - local($s) = $_[0]; - $s =~ s { E<((\d+)|([A-Za-z]+))> } - { - do { - defined($2) - ? do { chr($2) } - : - exists $HTML_Escapes{$3} - ? do { $HTML_Escapes{$3} } - : do { - warn "Unknown escape: $& in $_"; - "E<$1>"; - } - } - }egx; - return $s; -} +=head1 SYNOPSIS -sub escapes { - # make C++ into \C++, which is to be defined as - # \def\C++{{\rm C\kern-.05em\raise.3ex\hbox{\footnotesize ++}}} - s/\bC\+\+/\\C++{}/g; -} + pod2latex *.pm -# Translate a string into a TeX \tt string to obtain a verbatim print out. -# TeX special characters are escaped by \. -# This can be used inside of LaTeX command arguments. -# We don't use LaTeX \verb since it doesn't work inside of command arguments. -sub alltt { - local($str) = shift; - # other chars than #,\,$,%,&,{,},_,\,^,~ ([ and ] included). - $str =~ s/([^${backslash_escapables}\\\^\~]+)/&noremap("$&")/eg; - # chars #,\,$,%,&,{,} => \# , ... - $str =~ s/([$backslash_escapables2])/&noremap("\\$&")/eg; - # chars _,\,^,~ => \char`\_ , ... - $str =~ s/_/&noremap("\\char`\\_")/eg; - $str =~ s/\\/&noremap("\\char`\\\\")/ge; - $str =~ s/\^/\\char`\\^/g; - $str =~ s/\~/\\char`\\~/g; - - $str =~ tr/\200-\377/\000-\177/; # put back - $str = "{\\tt ".$str."}"; # make it a \tt string - return $str; -} + pod2latex -out mytex.tex *.pod -sub escape_tex_specials { - local($str) = shift; - # other chars than #,\,$,%,&,{,}, _,\,^,~ ([ and ] included). - # backslash escapable characters #,\,$,%,&,{,} except _. - $str =~ s/([$backslash_escapables2])/&noremap("\\$1")/ge; - $str =~ s/_/&noremap("\\underscore{}")/ge; # \_ is too thin. - # quote TeX special characters |, ^, ~, \. - $str =~ s/\|/&noremap("\$|\$")/ge; - $str =~ s/\^/&noremap("\$\\hat{\\hspace{0.4em}}\$")/ge; - $str =~ s/\~/&noremap("\$\\tilde{\\hspace{0.4em}}\$")/ge; - $str =~ s/\\/&noremap("\$\\backslash{}\$")/ge; - # characters need to be treated differently in TeX - # * - $str =~ s/[*]/&noremap("\$\\ast\$")/ge; - # escape < and > as math string, - $str =~ s/</&noremap("\$<\$")/ge; - $str =~ s/>/&noremap("\$>\$")/ge; - $str =~ tr/\200-\377/\000-\177/; # put back - return $str; -} + pod2latex -full -sections 'DESCRIPTION|NAME' SomeDir -sub internal_lrefs { - local($_) = shift; - - s{L</([^>]+)>}{$1}g; - my(@items) = split( /(?:,?\s+(?:and\s+)?)/ ); - my $retstr = "the "; - my $i; - for ($i = 0; $i <= $#items; $i++) { - $retstr .= "C<$items[$i]>"; - $retstr .= ", " if @items > 2 && $i != $#items; - $retstr .= " and " if $i+2 == @items; - } - $retstr .= " entr" . ( @items > 1 ? "ies" : "y" ) - . " elsewhere in this document"; +=head1 DESCRIPTION - return $retstr; -} +C<pod2latex> is a program to convert POD format documentation +(L<perlpod>) into latex. It can process multiple input documents at a +time and either generate a latex file per input document or a single +combined output file. + +=head1 OPTIONS AND ARGUMENTS + +This section describes the supported command line options. Minium +matching is supported. + +=over 4 + +=item B<-out> + +Name of the output file to be used. If there are multiple input pods +it is assumed that the intention is to write all translated output +into a single file. C<.tex> is appended if not present. If the +argument is not supplied, a single document will be created for each +input file. + +=item B<-full> + +Creates a complete C<latex> file that can be processed immediately +(unless C<=for/=begin> directives are used that rely on extra packages). +Table of contents and index generation commands are included in the +wrapper C<latex> code. + +=item B<-sections> + +Specify pod sections to include (or remove if negated) in the +translation. See L<Pod::Select/"SECTION SPECIFICATIONS"> for the +format to use for I<section-spec>. This option may be given multiple +times on the command line.This is identical to the similar option in +the C<podselect()> command. + +=item B<-modify> + +This option causes the output C<latex> to be slightly +modified from the input pod such that when a C<=head1 NAME> +is encountered a section is created containing the actual +pod name (rather than B<NAME>) and all subsequent C<=head1> +directives are treated as subsections. This has the advantage +that the description of a module will be in its own section +which is helpful for including module descriptions in documentation. +Also forces C<latex> label and index entries to be prefixed by the +name of the module. + +=item B<-help> + +Print a brief help message and exit. + +=item B<-man> + +Print the manual page and exit. + +=item B<-verbose> + +Print information messages as each document is processed. + +=back + +=head1 BUGS + +Known bugs are: + +=over 4 + +=item * + +Cross references between documents are not resolved when multiple +pod documents are converted into a single output C<latex> file. + +=item * + +Functions and variables are not automatically recognized +and they will therefore not be marked up in any special way +unless instructed by an explicit pod command. + +=back + +=head1 SEE ALSO + +L<Pod::LaTeX> + +=head1 AUTHOR + +Tim Jenness E<lt>t.jenness@jach.hawaii.eduE<gt> + +This program is free software; you can redistribute it +and/or modify it under the same terms as Perl itself. + +Copyright (C) 2000 Tim Jenness. + +=cut -# map of HTML escapes to TeX escapes. -BEGIN { -%HTML_Escapes = ( - 'amp' => '&', # ampersand - 'lt' => '<', # left chevron, less-than - 'gt' => '>', # right chevron, greater-than - 'quot' => '"', # double quote - - "Aacute" => "\\'{A}", # capital A, acute accent - "aacute" => "\\'{a}", # small a, acute accent - "Acirc" => "\\^{A}", # capital A, circumflex accent - "acirc" => "\\^{a}", # small a, circumflex accent - "AElig" => '\\AE', # capital AE diphthong (ligature) - "aelig" => '\\ae', # small ae diphthong (ligature) - "Agrave" => "\\`{A}", # capital A, grave accent - "agrave" => "\\`{a}", # small a, grave accent - "Aring" => '\\u{A}', # capital A, ring - "aring" => '\\u{a}', # small a, ring - "Atilde" => '\\~{A}', # capital A, tilde - "atilde" => '\\~{a}', # small a, tilde - "Auml" => '\\"{A}', # capital A, dieresis or umlaut mark - "auml" => '\\"{a}', # small a, dieresis or umlaut mark - "Ccedil" => '\\c{C}', # capital C, cedilla - "ccedil" => '\\c{c}', # small c, cedilla - "Eacute" => "\\'{E}", # capital E, acute accent - "eacute" => "\\'{e}", # small e, acute accent - "Ecirc" => "\\^{E}", # capital E, circumflex accent - "ecirc" => "\\^{e}", # small e, circumflex accent - "Egrave" => "\\`{E}", # capital E, grave accent - "egrave" => "\\`{e}", # small e, grave accent - "ETH" => '\\OE', # capital Eth, Icelandic - "eth" => '\\oe', # small eth, Icelandic - "Euml" => '\\"{E}', # capital E, dieresis or umlaut mark - "euml" => '\\"{e}', # small e, dieresis or umlaut mark - "Iacute" => "\\'{I}", # capital I, acute accent - "iacute" => "\\'{i}", # small i, acute accent - "Icirc" => "\\^{I}", # capital I, circumflex accent - "icirc" => "\\^{i}", # small i, circumflex accent - "Igrave" => "\\`{I}", # capital I, grave accent - "igrave" => "\\`{i}", # small i, grave accent - "Iuml" => '\\"{I}', # capital I, dieresis or umlaut mark - "iuml" => '\\"{i}', # small i, dieresis or umlaut mark - "Ntilde" => '\\~{N}', # capital N, tilde - "ntilde" => '\\~{n}', # small n, tilde - "Oacute" => "\\'{O}", # capital O, acute accent - "oacute" => "\\'{o}", # small o, acute accent - "Ocirc" => "\\^{O}", # capital O, circumflex accent - "ocirc" => "\\^{o}", # small o, circumflex accent - "Ograve" => "\\`{O}", # capital O, grave accent - "ograve" => "\\`{o}", # small o, grave accent - "Oslash" => "\\O", # capital O, slash - "oslash" => "\\o", # small o, slash - "Otilde" => "\\~{O}", # capital O, tilde - "otilde" => "\\~{o}", # small o, tilde - "Ouml" => '\\"{O}', # capital O, dieresis or umlaut mark - "ouml" => '\\"{o}', # small o, dieresis or umlaut mark - "szlig" => '\\ss{}', # small sharp s, German (sz ligature) - "THORN" => '\\L', # capital THORN, Icelandic - "thorn" => '\\l',, # small thorn, Icelandic - "Uacute" => "\\'{U}", # capital U, acute accent - "uacute" => "\\'{u}", # small u, acute accent - "Ucirc" => "\\^{U}", # capital U, circumflex accent - "ucirc" => "\\^{u}", # small u, circumflex accent - "Ugrave" => "\\`{U}", # capital U, grave accent - "ugrave" => "\\`{u}", # small u, grave accent - "Uuml" => '\\"{U}', # capital U, dieresis or umlaut mark - "uuml" => '\\"{u}', # small u, dieresis or umlaut mark - "Yacute" => "\\'{Y}", # capital Y, acute accent - "yacute" => "\\'{y}", # small y, acute accent - "yuml" => '\\"{y}', # small y, dieresis or umlaut mark -); -} !NO!SUBS! close OUT or die "Can't close $file: $!"; diff --git a/contrib/perl5/pod/pod2man.PL b/contrib/perl5/pod/pod2man.PL index bf35cff4ccbd..f320a3c295e8 100644 --- a/contrib/perl5/pod/pod2man.PL +++ b/contrib/perl5/pod/pod2man.PL @@ -36,7 +36,7 @@ $Config{startperl} print OUT <<'!NO!SUBS!'; # pod2man -- Convert POD data to formatted *roff input. -# $Id: pod2man.PL,v 1.2 2000/03/16 21:08:23 eagle Exp $ +# $Id: pod2man.PL,v 1.4 2000/11/19 05:47:46 eagle Exp $ # # Copyright 1999, 2000 by Russ Allbery <rra@stanford.edu> # @@ -63,7 +63,8 @@ my %options; Getopt::Long::config ('bundling_override'); GetOptions (\%options, 'section|s=s', 'release|r=s', 'center|c=s', 'date|d=s', 'fixed=s', 'fixedbold=s', 'fixeditalic=s', - 'fixedbolditalic=s', 'official|o', 'lax|l', 'help|h') or exit 1; + 'fixedbolditalic=s', 'official|o', 'quotes|q=s', 'lax|l', + 'help|h') or exit 1; pod2usage (0) if $options{help}; # Official sets --center, but don't override things explicitly set. @@ -71,10 +72,15 @@ if ($options{official} && !defined $options{center}) { $options{center} = 'Perl Programmers Reference Guide'; } -# Initialize and run the formatter. +# Initialize and run the formatter, pulling a pair of input and output off +# at a time. my $parser = Pod::Man->new (%options); -$parser->parse_from_file (@ARGV); - +my @files; +do { + @files = splice (@ARGV, 0, 2); + $parser->parse_from_file (@files); +} while (@ARGV); + __END__ =head1 NAME @@ -86,8 +92,8 @@ pod2man - Convert POD data to formatted *roff input pod2man [B<--section>=I<manext>] [B<--release>=I<version>] [B<--center>=I<string>] [B<--date>=I<string>] [B<--fixed>=I<font>] [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>] -[B<--fixedbolditalic>=I<font>] [B<--official>] [B<--lax>] [I<input> -[I<output>]] +[B<--fixedbolditalic>=I<font>] [B<--official>] [B<--lax>] +[B<--quotes>=I<quotes>] [I<input> [I<output>] ...] pod2man B<--help> @@ -100,7 +106,10 @@ terminal using nroff(1), normally via man(1), or printing using troff(1). I<input> is the file to read for POD source (the POD can be embedded in code). If I<input> isn't given, it defaults to STDIN. I<output>, if given, is the file to which to write the formatted output. If I<output> isn't -given, the formatted output is written to STDOUT. +given, the formatted output is written to STDOUT. Several POD files can be +processed in the same B<pod2man> invocation (saving module load and compile +times) by providing multiple pairs of I<input> and I<output> files on the +command line. B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can be used to set the headers and footers to use; if not given, Pod::Man will @@ -173,6 +182,19 @@ POD checking functionality is not yet implemented in Pod::Man. Set the default header to indicate that this page is part of the standard Perl release, if B<--center> is not also given. +=item B<-q> I<quotes>, B<--quotes>=I<quotes> + +Sets the quote marks used to surround CE<lt>> text to I<quotes>. If +I<quotes> is a single character, it is used as both the left and right +quote; if I<quotes> is two characters, the first character is used as the +left quote and the second as the right quoted; and if I<quotes> is four +characters, the first two are used as the left quote and the second two as +the right quote. + +I<quotes> may also be set to the special value C<none>, in which case no +quote marks are added around CE<lt>> text (but the font is still changed for +troff output). + =item B<-r>, B<--release> Set the centered footer. By default, this is the version of Perl you run diff --git a/contrib/perl5/pod/pod2text.PL b/contrib/perl5/pod/pod2text.PL index c5460aef30e4..7b5727decc0b 100644 --- a/contrib/perl5/pod/pod2text.PL +++ b/contrib/perl5/pod/pod2text.PL @@ -75,7 +75,8 @@ my %options; $options{sentence} = 0; Getopt::Long::config ('bundling'); GetOptions (\%options, 'alt|a', 'color|c', 'help|h', 'indent|i=i', - 'loose|l', 'sentence|s', 'termcap|t', 'width|w=i') or exit 1; + 'loose|l', 'overstrike|o', 'quotes|q=s', 'sentence|s', + 'termcap|t', 'width|w=i') or exit 1; pod2usage (1) if $options{help}; # Figure out what formatter we're going to use. -c overrides -t. @@ -88,8 +89,11 @@ if ($options{color}) { } elsif ($options{termcap}) { $formatter = 'Pod::Text::Termcap'; require Pod::Text::Termcap; +} elsif ($options{overstrike}) { + $formatter = 'Pod::Text::Overstrike'; + require Pod::Text::Overstrike; } -delete @options{'color', 'termcap'}; +delete @options{'color', 'termcap', 'overstrike'}; # Initialize and run the formatter. my $parser = $formatter->new (%options); @@ -103,7 +107,8 @@ pod2text - Convert POD data to formatted ASCII text =head1 SYNOPSIS -pod2text [B<-aclst>] [B<-i> I<indent>] [B<-w> I<width>] [I<input> [I<output>]] +pod2text [B<-aclost>] [B<-i> I<indent>] [B<-q> I<quotes>] [B<-w> I<width>] +[I<input> [I<output>]] pod2text B<-h> @@ -148,6 +153,25 @@ printed after C<=head1>, although one is still printed after C<=head2>, because this is the expected formatting for manual pages; if you're formatting arbitrary text documents, using this option is recommended. +=item B<-o>, B<--overstrike> + +Format the output with overstruck printing. Bold text is rendered as +character, backspace, character. Italics and file names are rendered as +underscore, backspace, character. Many pagers, such as B<less>, know how +to convert this to bold or underlined text. + +=item B<-q> I<quotes>, B<--quotes>=I<quotes> + +Sets the quote marks used to surround CE<lt>> text to I<quotes>. If +I<quotes> is a single character, it is used as both the left and right +quote; if I<quotes> is two characters, the first character is used as the +left quote and the second as the right quoted; and if I<quotes> is four +characters, the first two are used as the left quote and the second two as +the right quote. + +I<quotes> may also be set to the special value C<none>, in which case no +quote marks are added around CE<lt>> text. + =item B<-s>, B<--sentence> Assume each sentence ends with two spaces and try to preserve that spacing. diff --git a/contrib/perl5/pod/pod2usage.PL b/contrib/perl5/pod/pod2usage.PL index e0f70b2ca4fa..1c1296a19f3b 100644 --- a/contrib/perl5/pod/pod2usage.PL +++ b/contrib/perl5/pod/pod2usage.PL @@ -39,7 +39,7 @@ print OUT <<'!NO!SUBS!'; ############################################################################# # pod2usage -- command to print usage messages from embedded pod docs # -# Copyright (c) 1996-1999 by Bradford Appleton. All rights reserved. +# Copyright (c) 1996-2000 by Bradford Appleton. All rights reserved. # This file is part of "PodParser". PodParser is free software; # you can redistribute it and/or modify it under the same terms # as Perl itself. diff --git a/contrib/perl5/pod/podchecker.PL b/contrib/perl5/pod/podchecker.PL index a7f96434ca68..20d5e94c2e02 100644 --- a/contrib/perl5/pod/podchecker.PL +++ b/contrib/perl5/pod/podchecker.PL @@ -39,7 +39,7 @@ print OUT <<'!NO!SUBS!'; ############################################################################# # podchecker -- command to invoke the podchecker function in Pod::Checker # -# Copyright (c) 1998-1999 by Bradford Appleton. All rights reserved. +# Copyright (c) 1998-2000 by Bradford Appleton. All rights reserved. # This file is part of "PodParser". PodParser is free software; # you can redistribute it and/or modify it under the same terms # as Perl itself. @@ -70,7 +70,9 @@ Print the manual page and exit. =item B<-warnings> B<-nowarnings> -Turn on/off printing of warnings. +Turn on/off printing of warnings. Repeating B<-warnings> increases the +warning level, i.e. more warnings are printed. Currently increasing to +level two causes flagging of unescaped "E<lt>,E<gt>" characters. =item I<file> @@ -85,6 +87,8 @@ syntax errors in the POD documentation and will print any errors it find to STDERR. At the end, it will print a status message indicating the number of errors found. +Directories are ignored, an appropriate warning message is printed. + B<podchecker> invokes the B<podchecker()> function exported by B<Pod::Checker> Please see L<Pod::Checker/podchecker()> for more details. @@ -124,24 +128,34 @@ use Pod::Usage; use Getopt::Long; ## Define options -my %options = ( - "help" => 0, - "man" => 0, - "warnings" => 1, -); +my %options; ## Parse options -GetOptions(\%options, "help", "man", "warnings!") || pod2usage(2); +GetOptions(\%options, qw(help man warnings+ nowarnings)) || pod2usage(2); pod2usage(1) if ($options{help}); pod2usage(-verbose => 2) if ($options{man}); +if($options{nowarnings}) { + $options{warnings} = 0; +} +elsif(!defined $options{warnings}) { + $options{warnings} = 1; # default is warnings on +} + ## Dont default to STDIN if connected to a terminal pod2usage(2) if ((@ARGV == 0) && (-t STDIN)); ## Invoke podchecker() my $status = 0; -@ARGV = ("<&STDIN") unless(@ARGV); +@ARGV = qw(-) unless(@ARGV); for (@ARGV) { + if($_ eq '-') { + $_ = "<&STDIN"; + } + elsif(-d) { + warn "podchecker: Warning: Ignoring directory '$_'\n"; + next; + } my $s = podchecker($_, undef, '-warnings' => $options{warnings}); if($s > 0) { # errors occurred diff --git a/contrib/perl5/pod/podselect.PL b/contrib/perl5/pod/podselect.PL index f2ba80a73b59..b6b8c9b9e430 100644 --- a/contrib/perl5/pod/podselect.PL +++ b/contrib/perl5/pod/podselect.PL @@ -39,7 +39,7 @@ print OUT <<'!NO!SUBS!'; ############################################################################# # podselect -- command to invoke the podselect function in Pod::Select # -# Copyright (c) 1996-1999 by Bradford Appleton. All rights reserved. +# Copyright (c) 1996-2000 by Bradford Appleton. All rights reserved. # This file is part of "PodParser". PodParser is free software; # you can redistribute it and/or modify it under the same terms # as Perl itself. diff --git a/contrib/perl5/pod/roffitall b/contrib/perl5/pod/roffitall index 018c0b3475b1..396da6fae235 100644 --- a/contrib/perl5/pod/roffitall +++ b/contrib/perl5/pod/roffitall @@ -27,70 +27,82 @@ case "$1" in ;; esac +# NEEDS TO BE BUILT BASED ON Makefile (or Makefile.SH, should such happen) toroff=` echo \ - $mandir/perl.1 \ - $mandir/perldata.1 \ - $mandir/perlsyn.1 \ - $mandir/perlop.1 \ - $mandir/perlre.1 \ - $mandir/perlrun.1 \ - $mandir/perlfunc.1 \ - $mandir/perlvar.1 \ - $mandir/perlsub.1 \ - $mandir/perlopentut.1 \ - $mandir/perlmod.1 \ - $mandir/perlmodlib.1 \ - $mandir/perlmodinstall.1 \ - $mandir/perlfork.1 \ - $mandir/perlform.1 \ - $mandir/perllocale.1 \ - $mandir/perlref.1 \ - $mandir/perlreftut.1 \ - $mandir/perldsc.1 \ - $mandir/perllol.1 \ - $mandir/perlboot.1 \ - $mandir/perltoot.1 \ - $mandir/perlobj.1 \ - $mandir/perltie.1 \ - $mandir/perlbot.1 \ - $mandir/perlipc.1 \ - $mandir/perlthrtut.1 \ - $mandir/perldebguts.1 \ - $mandir/perldebug.1 \ - $mandir/perlnumber.1 \ - $mandir/perldiag.1 \ - $mandir/perlsec.1 \ - $mandir/perltrap.1 \ - $mandir/perlport.1 \ - $mandir/perlstyle.1 \ - $mandir/perlpod.1 \ - $mandir/perlbook.1 \ - $mandir/perlembed.1 \ - $mandir/perlapio.1 \ - $mandir/perlxs.1 \ - $mandir/perlxstut.1 \ - $mandir/perlguts.1 \ - $mandir/perlcall.1 \ - $mandir/perlcompile.1 \ - $mandir/perltodo.1 \ - $mandir/perlapi.1 \ - $mandir/perlintern.1 \ - $mandir/perlhack.1 \ - $mandir/perlhist.1 \ - $mandir/perldelta.1 \ - $mandir/perl5004delta.1 \ - $mandir/perl5005delta.1 \ - $mandir/perlfaq.1 \ - $mandir/perlfaq1.1 \ - $mandir/perlfaq2.1 \ - $mandir/perlfaq3.1 \ - $mandir/perlfaq4.1 \ - $mandir/perlfaq5.1 \ - $mandir/perlfaq6.1 \ - $mandir/perlfaq7.1 \ - $mandir/perlfaq8.1 \ - $mandir/perlfaq9.1 \ + $mandir/perl.1 \ + $mandir/perl5004delta.1 \ + $mandir/perl5005delta.1 \ + $mandir/perl56delta.1 \ + $mandir/perlapi.1 \ + $mandir/perlapio.1 \ + $mandir/perlbook.1 \ + $mandir/perlboot.1 \ + $mandir/perlbot.1 \ + $mandir/perlcall.1 \ + $mandir/perlcompile.1 \ + $mandir/perldata.1 \ + $mandir/perldbmfilter.1 \ + $mandir/perldebguts.1 \ + $mandir/perldebug.1 \ + $mandir/perldelta.1 \ + $mandir/perldiag.1 \ + $mandir/perldsc.1 \ + $mandir/perlembed.1 \ + $mandir/perlfaq.1 \ + $mandir/perlfaq1.1 \ + $mandir/perlfaq2.1 \ + $mandir/perlfaq3.1 \ + $mandir/perlfaq4.1 \ + $mandir/perlfaq5.1 \ + $mandir/perlfaq6.1 \ + $mandir/perlfaq7.1 \ + $mandir/perlfaq8.1 \ + $mandir/perlfaq9.1 \ + $mandir/perlfilter.1 \ + $mandir/perlfork.1 \ + $mandir/perlform.1 \ + $mandir/perlfunc.1 \ + $mandir/perlguts.1 \ + $mandir/perlhack.1 \ + $mandir/perlhist.1 \ + $mandir/perlintern.1 \ + $mandir/perlipc.1 \ + $mandir/perllexwarn.1 \ + $mandir/perllocale.1 \ + $mandir/perllol.1 \ + $mandir/perlmod.1 \ + $mandir/perlmodinstall.1 \ + $mandir/perlmodlib.1 \ + $mandir/perlnewmod.1 \ + $mandir/perlnumber.1 \ + $mandir/perlobj.1 \ + $mandir/perlop.1 \ + $mandir/perlopentut.1 \ + $mandir/perlpod.1 \ + $mandir/perlport.1 \ + $mandir/perlre.1 \ + $mandir/perlref.1 \ + $mandir/perlreftut.1 \ + $mandir/perlrequick.1 \ + $mandir/perlretut.1 \ + $mandir/perlrun.1 \ + $mandir/perlsec.1 \ + $mandir/perlstyle.1 \ + $mandir/perlsub.1 \ + $mandir/perlsyn.1 \ + $mandir/perlthrtut.1 \ + $mandir/perltie.1 \ + $mandir/perltoc.1 \ + $mandir/perltodo.1 \ + $mandir/perltoot.1 \ + $mandir/perltootc.1 \ + $mandir/perltrap.1 \ + $mandir/perlunicode.1 \ + $mandir/perlutil.1 \ + $mandir/perlvar.1 \ + $mandir/perlxs.1 \ + $mandir/perlxstut.1 \ \ $mandir/a2p.1 \ $mandir/c2ph.1 \ |