diff --git a/build.gradle b/build.gradle index 4f2879ad1..4f9a55585 100644 --- a/build.gradle +++ b/build.gradle @@ -326,6 +326,7 @@ sourceSets { srcDir 'src/main/resources' include '**/*.pm' include '**/*.pl' + include '**/*.pod' include 'bin/**' include 'META-INF/services/**' } @@ -341,6 +342,7 @@ sourceSets { tasks.named('processResources', Copy) { from(sourceSets.main.resources.srcDirs) { include '**/*.pm' + include '**/*.pod' include 'bin/**' include 'META-INF/services/**' } diff --git a/dev/import-perl5/config.yaml b/dev/import-perl5/config.yaml index 3eb963bf3..e14ac0e91 100644 --- a/dev/import-perl5/config.yaml +++ b/dev/import-perl5/config.yaml @@ -683,6 +683,12 @@ imports: target: perl5_t/Test-Harness type: directory + # Perl core documentation (perlfunc.pod, perlop.pod, etc.) + # Required by jperldoc for -f (function) lookups + - source: perl5/pod + target: src/main/perl/lib/pod + type: directory + # Add more imports below as needed # Example with minimal fields: # - source: perl5/lib/SomeModule.pm diff --git a/pom.xml b/pom.xml index 9d7f38d60..c8d4a3cf5 100644 --- a/pom.xml +++ b/pom.xml @@ -80,6 +80,7 @@ **/*.pm **/*.pl + **/*.pod bin/** diff --git a/src/main/java/org/perlonjava/core/Configuration.java b/src/main/java/org/perlonjava/core/Configuration.java index 1a304bd33..45c9291e0 100644 --- a/src/main/java/org/perlonjava/core/Configuration.java +++ b/src/main/java/org/perlonjava/core/Configuration.java @@ -33,14 +33,14 @@ public final class Configuration { * Automatically populated by Gradle/Maven during build. * DO NOT EDIT MANUALLY - this value is replaced at build time. */ - public static final String gitCommitId = "93d20cfa9"; + public static final String gitCommitId = "6331b9337"; /** * Git commit date of the build (ISO format: YYYY-MM-DD). * Automatically populated by Gradle/Maven during build. * DO NOT EDIT MANUALLY - this value is replaced at build time. */ - public static final String gitCommitDate = "2026-03-27"; + public static final String gitCommitDate = "2026-03-28"; // Prevent instantiation private Configuration() { diff --git a/src/main/perl/lib/Pod/Perldoc.pm b/src/main/perl/lib/Pod/Perldoc.pm index bb6ffc83e..a0de7e086 100644 --- a/src/main/perl/lib/Pod/Perldoc.pm +++ b/src/main/perl/lib/Pod/Perldoc.pm @@ -1968,6 +1968,8 @@ sub searchfor { or ( $ret = $self->check_file("$dir/pod",$s)) or ( $ret = $self->check_file("$dir/pods","$s.pod")) or ( $ret = $self->check_file("$dir/pods",$s)) + or ( $ret = $self->check_file("$dir/Pod","$s.pod")) + or ( $ret = $self->check_file("$dir/Pod",$s)) ) { DEBUG > 1 and print " Found $ret\n"; return $ret; diff --git a/src/main/perl/lib/Pod/perl.pod b/src/main/perl/lib/Pod/perl.pod new file mode 100644 index 000000000..48033e668 --- /dev/null +++ b/src/main/perl/lib/Pod/perl.pod @@ -0,0 +1,492 @@ +=head1 NAME + +perl - The Perl 5 language interpreter + +=head1 SYNOPSIS + +B S<[ B<-sTtuUWX> ]> + S<[ B<-hv> ] [ B<-V>[:I] ]> + S<[ B<-cw> ] [ B<-d>[B][:I] ] [ B<-D>[I] ]> + S<[ B<-pna> ] [ B<-F>I ] [ B<-l>[I] ] [ B<-0>[I] ]> + S<[ B<-I>I ] [ B<-m>[B<->]I ] [ B<-M>[B<->]I<'module...'> ] [ B<-f> ]> + S<[ B<-C [I] >]> + S<[ B<-S> ]> + S<[ B<-x>[I] ]> + S<[ B<-i>[I] ]> + S<[ [B<-e>|B<-E>] I<'command'> ] [ B<--> ] [ I ] [ I ]...> + +For more information on these options, you can run C. + +=head1 GETTING HELP + +The F program gives you access to all the documentation that comes +with Perl. You can get more documentation, tutorials and community support +online at L. + +If you're new to Perl, you should start by running C, +which is a general intro for beginners and provides some background to help +you navigate the rest of Perl's extensive documentation. Run C to learn more things you can do with F. + +For ease of access, the Perl manual has been split up into several sections. + +=begin buildtoc + +# This section is parsed by Porting/pod_lib.pl for use by pod/buildtoc etc + +flag =g perluniprops perlmodlib perlapi perlintern +flag =go perltoc +flag =ro perlcn perljp perlko perltw +flag = perlvms + +path perlfaq.* cpan/perlfaq/lib/ +path perlglossary cpan/perlfaq/lib/ +path perlxs(?:tut|typemap)? dist/ExtUtils-ParseXS/lib/ +path perldoc cpan/Pod-Perldoc/ + +aux h2ph h2xs perlbug pl2pm pod2html pod2man splain xsubpp + +=end buildtoc + +=head2 Overview + + perl Perl overview (this section) + perlintro Perl introduction for beginners + perlrun Perl execution and options + perltoc Perl documentation table of contents + +=head2 Tutorials + + perlreftut Perl references short introduction + perldsc Perl data structures intro + perllol Perl data structures: arrays of arrays + + perlrequick Perl regular expressions quick start + perlretut Perl regular expressions tutorial + + perlootut Perl OO tutorial for beginners + + perlperf Perl Performance and Optimization Techniques + + perlstyle Perl style guide + + perlcheat Perl cheat sheet + perltrap Perl traps for the unwary + perldebtut Perl debugging tutorial + + perlfaq Perl frequently asked questions + perlfaq1 General Questions About Perl + perlfaq2 Obtaining and Learning about Perl + perlfaq3 Programming Tools + perlfaq4 Data Manipulation + perlfaq5 Files and Formats + perlfaq6 Regexes + perlfaq7 Perl Language Issues + perlfaq8 System Interaction + perlfaq9 Networking + +=head2 Reference Manual + + perlsyn Perl syntax: declarations, statements, comments + perldata Perl data structures + perlop Perl expressions: operators, precedence, string literals + perlsub Perl subroutines + perlfunc Perl built-in functions + perlopentut Perl open() tutorial + perlpacktut Perl pack() and unpack() tutorial + perlpod Perl plain old documentation + perlpodspec Perl plain old documentation format specification + perldocstyle Perl style guide for core docs + perlpodstyle Perl POD style guide + perldiag Perl diagnostic messages + perldeprecation Perl deprecations + perllexwarn Perl warnings and their control + perldebug Perl debugging + perlvar Perl predefined variables + perlre Perl regular expressions, the rest of the story + perlrebackslash Perl regular expression backslash sequences + perlrecharclass Perl regular expression character classes + perlreref Perl regular expressions quick reference + perlref Perl references, the rest of the story + perlform Perl formats + perlobj Perl objects + perltie Perl objects hidden behind simple variables + perldbmfilter Perl DBM filters + perlclass Perl class syntax + + perlipc Perl interprocess communication + perlfork Perl fork() information + perlnumber Perl number semantics + + perlthrtut Perl threads tutorial + + perlport Perl portability guide + perllocale Perl locale support + perluniintro Perl Unicode introduction + perlunicode Perl Unicode support + perlunicook Perl Unicode cookbook + perlunifaq Perl Unicode FAQ + perluniprops Index of Unicode properties in Perl + perlunitut Perl Unicode tutorial + perlebcdic Considerations for running Perl on EBCDIC platforms + + perlsec Perl security + perlsecpolicy Perl security report handling policy + + perlmod Perl modules: how they work + perlmodlib Perl modules: how to write and use + perlmodstyle Perl modules: how to write modules with style + perlmodinstall Perl modules: how to install from CPAN + perlnewmod Perl modules: preparing a new module for distribution + perlpragma Perl modules: writing a user pragma + + perlutil utilities packaged with the Perl distribution + + perlfilter Perl source filters + + perldtrace Perl's support for DTrace + + perlglossary Perl Glossary + +=head2 Internals and C Language Interface + + perlembed Perl ways to embed perl in your C or C++ application + perldebguts Perl debugging guts and tips + perlxstut Perl XS tutorial + perlxs Perl XS application programming interface + perlxstypemap Perl XS C/Perl type conversion tools + perlclib Interacting with standard C library functions + perlguts Perl internal functions for those doing extensions + perlcall Perl calling conventions from C + perlmroapi Perl method resolution plugin interface + perlreapi Perl regular expression plugin interface + perlreguts Perl regular expression engine internals + perlclassguts Internals of class syntax + + perlapi Perl API listing (autogenerated) + perlintern Perl internal functions (autogenerated) + perliol C API for Perl's implementation of IO in Layers + perlapio Perl internal IO abstraction interface + + perlhack Perl hackers guide + perlsource Guide to the Perl source tree + perlinterp Overview of the Perl interpreter source and how it works + perlhacktut Walk through the creation of a simple C code patch + perlhacktips Tips for Perl core C code hacking + perlpolicy Perl development policies + perlgov Perl Rules of Governance + perlgit Using git with the Perl repository + +=head2 History + + perlhist Perl history records + perldelta Perl changes since previous version + perl5438delta Perl changes in version 5.43.8 + perl5437delta Perl changes in version 5.43.7 + perl5436delta Perl changes in version 5.43.6 + perl5435delta Perl changes in version 5.43.5 + perl5434delta Perl changes in version 5.43.4 + perl5433delta Perl changes in version 5.43.3 + perl5432delta Perl changes in version 5.43.2 + perl5431delta Perl changes in version 5.43.1 + perl5430delta Perl changes in version 5.43.0 + perl5421delta Perl changes in version 5.42.1 + perl5420delta Perl changes in version 5.42.0 + perl5403delta Perl changes in version 5.40.3 + perl5402delta Perl changes in version 5.40.2 + perl5401delta Perl changes in version 5.40.1 + perl5400delta Perl changes in version 5.40.0 + perl5385delta Perl changes in version 5.38.5 + perl5384delta Perl changes in version 5.38.4 + perl5383delta Perl changes in version 5.38.3 + perl5382delta Perl changes in version 5.38.2 + perl5381delta Perl changes in version 5.38.1 + perl5380delta Perl changes in version 5.38.0 + perl5363delta Perl changes in version 5.36.3 + perl5362delta Perl changes in version 5.36.2 + perl5361delta Perl changes in version 5.36.1 + perl5360delta Perl changes in version 5.36.0 + perl5343delta Perl changes in version 5.34.3 + perl5342delta Perl changes in version 5.34.2 + perl5341delta Perl changes in version 5.34.1 + perl5340delta Perl changes in version 5.34.0 + perl5321delta Perl changes in version 5.32.1 + perl5320delta Perl changes in version 5.32.0 + perl5303delta Perl changes in version 5.30.3 + perl5302delta Perl changes in version 5.30.2 + perl5301delta Perl changes in version 5.30.1 + perl5300delta Perl changes in version 5.30.0 + perl5283delta Perl changes in version 5.28.3 + perl5282delta Perl changes in version 5.28.2 + perl5281delta Perl changes in version 5.28.1 + perl5280delta Perl changes in version 5.28.0 + perl5263delta Perl changes in version 5.26.3 + perl5262delta Perl changes in version 5.26.2 + perl5261delta Perl changes in version 5.26.1 + perl5260delta Perl changes in version 5.26.0 + perl5244delta Perl changes in version 5.24.4 + perl5243delta Perl changes in version 5.24.3 + perl5242delta Perl changes in version 5.24.2 + perl5241delta Perl changes in version 5.24.1 + perl5240delta Perl changes in version 5.24.0 + perl5224delta Perl changes in version 5.22.4 + perl5223delta Perl changes in version 5.22.3 + perl5222delta Perl changes in version 5.22.2 + perl5221delta Perl changes in version 5.22.1 + perl5220delta Perl changes in version 5.22.0 + perl5203delta Perl changes in version 5.20.3 + perl5202delta Perl changes in version 5.20.2 + perl5201delta Perl changes in version 5.20.1 + perl5200delta Perl changes in version 5.20.0 + perl5184delta Perl changes in version 5.18.4 + perl5182delta Perl changes in version 5.18.2 + perl5181delta Perl changes in version 5.18.1 + perl5180delta Perl changes in version 5.18.0 + perl5163delta Perl changes in version 5.16.3 + perl5162delta Perl changes in version 5.16.2 + perl5161delta Perl changes in version 5.16.1 + perl5160delta Perl changes in version 5.16.0 + perl5144delta Perl changes in version 5.14.4 + perl5143delta Perl changes in version 5.14.3 + perl5142delta Perl changes in version 5.14.2 + perl5141delta Perl changes in version 5.14.1 + perl5140delta Perl changes in version 5.14.0 + perl5125delta Perl changes in version 5.12.5 + perl5124delta Perl changes in version 5.12.4 + perl5123delta Perl changes in version 5.12.3 + perl5122delta Perl changes in version 5.12.2 + perl5121delta Perl changes in version 5.12.1 + perl5120delta Perl changes in version 5.12.0 + perl5101delta Perl changes in version 5.10.1 + perl5100delta Perl changes in version 5.10.0 + perl589delta Perl changes in version 5.8.9 + perl588delta Perl changes in version 5.8.8 + perl587delta Perl changes in version 5.8.7 + perl586delta Perl changes in version 5.8.6 + perl585delta Perl changes in version 5.8.5 + perl584delta Perl changes in version 5.8.4 + perl583delta Perl changes in version 5.8.3 + perl582delta Perl changes in version 5.8.2 + perl581delta Perl changes in version 5.8.1 + perl58delta Perl changes in version 5.8.0 + perl561delta Perl changes in version 5.6.1 + perl56delta Perl changes in version 5.6 + perl5005delta Perl changes in version 5.005 + perl5004delta Perl changes in version 5.004 + +=head2 Miscellaneous + + perlbook Perl book information + perlcommunity Perl community information + + perldoc Look up Perl documentation in Pod format + + perlexperiment A listing of experimental features in Perl + + perlartistic Perl Artistic License + perlgpl GNU General Public License + +=head2 Language-Specific + +=for buildtoc flag +r + + perlcn Perl for Simplified Chinese (in UTF-8) + perljp Perl for Japanese (in EUC-JP) + perlko Perl for Korean (in EUC-KR) + perltw Perl for Traditional Chinese (in Big5) + +=head2 Platform-Specific + + perlaix Perl notes for AIX + perlamiga Perl notes for AmigaOS + perlandroid Perl notes for Android + perlbs2000 Perl notes for POSIX-BC BS2000 + perlcygwin Perl notes for Cygwin + perlfreebsd Perl notes for FreeBSD + perlhaiku Perl notes for Haiku + perlhpux Perl notes for HP-UX + perlhurd Perl notes for Hurd + perlirix Perl notes for Irix + perllinux Perl notes for Linux + perlmacosx Perl notes for Mac OS X + perlopenbsd Perl notes for OpenBSD + perlos2 Perl notes for OS/2 + perlos390 Perl notes for OS/390 + perlos400 Perl notes for OS/400 + perlplan9 Perl notes for Plan 9 + perlqnx Perl notes for QNX + perlriscos Perl notes for RISC OS + perlsolaris Perl notes for Solaris + perlsynology Perl notes for Synology + perltru64 Perl notes for Tru64 + perlvms Perl notes for VMS + perlvos Perl notes for Stratus VOS + perlwin32 Perl notes for Windows + +=for buildtoc flag -r + +=head2 Stubs for Deleted Documents + + perlboot + perlbot + perlrepository + perltodo + perltooc + perltoot + +=for buildtoc __END__ + +On a Unix-like system, these documentation files will usually also be +available as manpages for use with the F program. + +Some documentation is not available as man pages, so if a +cross-reference is not found by man, try it with L. Perldoc can +also take you directly to documentation for functions (with the B<-f> +switch). See S> (or S> or +S>) for other helpful options L has to offer. + +In general, if something strange has gone wrong with your program and you're +not sure where you should look for help, try making your code comply with +B and B. These will often point out exactly +where the trouble is. + +=head1 DESCRIPTION + +Perl officially stands for Practical Extraction and Report Language, +except when it doesn't. + +Perl was originally a language optimized for scanning arbitrary +text files, extracting information from those text files, and printing +reports based on that information. It quickly became a good language +for many system management tasks. Over the years, Perl has grown into +a general-purpose programming language. It's widely used for everything +from quick "one-liners" to full-scale application development. + +The language is intended to be practical (easy to use, efficient, +complete) rather than beautiful (tiny, elegant, minimal). It combines +(in the author's opinion, anyway) some of the best features of B, +B, and B, making it familiar and easy to use for Unix users to +whip up quick solutions to annoying problems. Its general-purpose +programming facilities support procedural, functional, and +object-oriented programming paradigms, making Perl a comfortable +language for the long haul on major projects, whatever your bent. + +Perl's roots in text processing haven't been forgotten over the years. +It still boasts some of the most powerful regular expressions to be +found anywhere, and its support for Unicode text is world-class. It +handles all kinds of structured text, too, through an extensive +collection of extensions. Those libraries, collected in the CPAN, +provide ready-made solutions to an astounding array of problems. When +they haven't set the standard themselves, they steal from the best +-- just like Perl itself. + +=head1 AVAILABILITY + +Perl is available for most operating systems, including virtually +all Unix-like platforms. See L +for a listing. + +=head1 ENVIRONMENT + +See L. + +=head1 AUTHOR + +Larry Wall , with the help of oodles of other folks. + +If your Perl success stories and testimonials may be of help to others +who wish to advocate the use of Perl in their applications, +or if you wish to simply express your gratitude to Larry and the +Perl developers, please write to perl-thanks@perl.org . + +=head1 FILES + + "@INC" locations of perl libraries + +"@INC" above is a reference to the built-in variable of the same name; +see L for more information. + +=head1 SEE ALSO + +=over + +=item L + +the Perl homepage + +=item L + +Perl articles + +=item L + +the Comprehensive Perl Archive + +=item L + +the Perl Mongers + +=back + +=head1 DIAGNOSTICS + +Using the C pragma ensures that all variables are properly +declared and prevents other misuses of legacy Perl features. +These are enabled by default within the scope of +C> (or higher). + +The C pragma produces some lovely diagnostics. +It is enabled by default when you say C (or higher). +One can also use the B<-w> flag, but its use is normally discouraged, +because it gets applied to all executed Perl code, including that not under +your control. + +See L for explanations of all Perl's diagnostics. The C pragma automatically turns Perl's normally terse warnings +and errors into these longer forms. + +Compilation errors will tell you the line number of the error, with an +indication of the next token or token type that was to be examined. +(In a script passed to Perl via B<-e> switches, each +B<-e> is counted as one line.) + +Setuid scripts have additional constraints that can produce error +messages such as "Insecure dependency". See L. + +Did we mention that you should definitely consider using the B +pragma? + +=head1 BUGS + +The behavior implied by the B pragma is not mandatory. + +Perl is at the mercy of your machine's definitions of various +operations such as type casting, atof(), and floating-point +output with sprintf(). + +If your stdio requires a seek or eof between reads and writes on a +particular stream, so does Perl. (This doesn't apply to sysread() +and syswrite().) + +While none of the built-in data types have any arbitrary size limits +(apart from memory size), there are still a few arbitrary limits: a +given variable name may not be longer than 251 characters. Line numbers +displayed by diagnostics are internally stored as short integers, +so they are limited to a maximum of 65535 (higher numbers usually being +affected by wraparound). + +You may submit your bug reports (be sure to include full configuration +information as output by the myconfig program in the perl source +tree, or by C) to L. + +Perl actually stands for Pathologically Eclectic Rubbish Lister, but +don't tell anyone I said that. + +=head1 NOTES + +The Perl motto is "There's more than one way to do it." Divining +how many more is left as an exercise to the reader. + +The three principal virtues of a programmer are Laziness, +Impatience, and Hubris. See the Camel Book for why. + diff --git a/src/main/perl/lib/Pod/perl5004delta.pod b/src/main/perl/lib/Pod/perl5004delta.pod new file mode 100644 index 000000000..264483e11 --- /dev/null +++ b/src/main/perl/lib/Pod/perl5004delta.pod @@ -0,0 +1,1612 @@ +=head1 NAME + +perl5004delta - what's new for perl5.004 + +=head1 DESCRIPTION + +This document describes differences between the 5.003 release (as +documented in I, second edition--the Camel Book) and +this one. + +=head1 Supported Environments + +Perl5.004 builds out of the box on Unix, Plan 9, LynxOS, VMS, OS/2, +QNX, AmigaOS, and Windows NT. Perl runs on Windows 95 as well, but it +cannot be built there, for lack of a reasonable command interpreter. + +=head1 Core Changes + +Most importantly, many bugs were fixed, including several security +problems. See the F file in the distribution for details. + +=head2 List assignment to %ENV works + +C<%ENV = ()> and C<%ENV = @list> now work as expected (except on VMS +where it generates a fatal error). + +=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 + +There is a new Configure question that asks if you want to maintain +binary compatibility with Perl 5.003. If you choose binary +compatibility, you do not have to recompile your extensions, but you +might have symbol conflicts if you embed Perl in another application, +just as in the 5.003 release. By default, binary compatibility +is preserved at the expense of symbol table pollution. + +=head2 $PERL5OPT environment variable + +You may now put Perl options in the $PERL5OPT environment variable. +Unless Perl is running with taint checks, it will interpret this +variable as if its contents had appeared on a "#!perl" line at the +beginning of your script, except that hyphens are optional. PERL5OPT +may only be used to set the following switches: B<-[DIMUdmw]>. + +=head2 Limitations on B<-M>, B<-m>, and B<-T> options + +The C<-M> and C<-m> options are no longer allowed on the C<#!> line of +a script. If a script needs a module, it should invoke it with the +C pragma. + +The B<-T> option is also forbidden on the C<#!> line of a script, +unless it was present on the Perl command line. Due to the way C<#!> +works, this usually means that B<-T> must be in the first argument. +Thus: + + #!/usr/bin/perl -T -w + +will probably work for an executable script invoked as C, +while: + + #!/usr/bin/perl -w -T + +will probably fail under the same conditions. (Non-Unix systems will +probably not follow this rule.) But C is guaranteed +to fail, since then there is no chance of B<-T> being found on the +command line before it is found on the C<#!> line. + +=head2 More precise warnings + +If you removed the B<-w> option from your Perl 5.003 scripts because it +made Perl too verbose, we recommend that you try putting it back when +you upgrade to Perl 5.004. Each new perl version tends to remove some +undesirable warnings, while adding new warnings that may catch bugs in +your scripts. + +=head2 Deprecated: Inherited C for non-methods + +Before Perl 5.004, C functions were looked up as methods +(using the C<@ISA> hierarchy), even when the function to be autoloaded +was called as a plain function (e.g. C), not a method +(e.g. C<< Foo->bar() >> or C<< $obj->bar() >>). + +Perl 5.005 will use method lookup only for methods' Cs. +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 a non-method uses an inherited C. + +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 for non-methods from a base class named +C, execute C<*AUTOLOAD = \&BaseClass::AUTOLOAD> during startup. + +=head2 Previously deprecated %OVERLOAD is no longer usable + +Using %OVERLOAD to define overloading was deprecated in 5.003. +Overloading is now defined using the overload pragma. %OVERLOAD is +still used internally but should not be used by Perl scripts. See +L for more details. + +=head2 Subroutine arguments created only when they're modified + +In Perl 5.004, nonexistent array and hash elements used as subroutine +parameters are brought into existence only if they are actually +assigned to (via C<@_>). + +Earlier versions of Perl vary in their handling of such arguments. +Perl versions 5.002 and 5.003 always brought them into existence. +Perl versions 5.000 and 5.001 brought them into existence only if +they were not the first argument (which was almost certainly a bug). +Earlier versions of Perl never brought them into existence. + +For example, given this code: + + undef @a; undef %a; + sub show { print $_[0] }; + sub change { $_[0]++ }; + show($a[2]); + change($a{b}); + +After this code executes in Perl 5.004, $a{b} exists but $a[2] does +not. In Perl 5.002 and 5.003, both $a{b} and $a[2] would have existed +(but $a[2]'s value would have been undefined). + +=head2 Group vector changeable with C<$)> + +The C<$)> special variable has always (well, in Perl 5, at least) +reflected not only the current effective group, but also the group list +as returned by the C C function (if there is one). +However, until this release, there has not been a way to call the +C C function from Perl. + +In Perl 5.004, assigning to C<$)> is exactly symmetrical with examining +it: The first number in its string value is used as the effective gid; +if there are any numbers after the first one, they are passed to the +C C function (if there is one). + +=head2 Fixed parsing of $$, &$, etc. + +Perl versions before 5.004 misinterpreted any type marker followed by +"$" and a digit. For example, "$$0" was incorrectly taken to mean +"${$}0" instead of "${$0}". This bug is (mostly) fixed in Perl 5.004. + +However, the developers of Perl 5.004 could not fix this bug completely, +because at least two widely-used modules depend on the old meaning of +"$$0" in a string. So Perl 5.004 still interprets "$$" in the +old (broken) way inside strings; but it generates this message as a +warning. And in Perl 5.005, this special treatment will cease. + +=head2 Fixed localization of $, $&, etc. + +Perl versions before 5.004 did not always properly localize the +regex-related special variables. Perl 5.004 does localize them, as +the documentation has always said it should. This may result in $1, +$2, etc. no longer being set where existing programs use them. + +=head2 No resetting of $. on implicit close + +The documentation for Perl 5.0 has always stated that C<$.> is I +reset when an already-open file handle is reopened with no intervening +call to C. Due to a bug, perl versions 5.000 through 5.003 +I reset C<$.> under that circumstance; Perl 5.004 does not. + +=head2 C may return undef + +The C operator returns true if a subroutine is expected to +return a list, and false otherwise. In Perl 5.004, C can +also return the undefined value if a subroutine's return value will +not be used at all, which allows subroutines to avoid a time-consuming +calculation of a return value if it isn't going to be used. + +=head2 C determines value of EXPR in scalar context + +Perl (version 5) used to determine the value of EXPR inconsistently, +sometimes incorrectly using the surrounding context for the determination. +Now, the value of EXPR (before being parsed by eval) is always determined in +a scalar context. Once parsed, it is executed as before, by providing +the context that the scope surrounding the eval provided. This change +makes the behavior Perl4 compatible, besides fixing bugs resulting from +the inconsistent behavior. This program: + + @a = qw(time now is time); + print eval @a; + print '|', scalar eval @a; + +used to print something like "timenowis881399109|4", but now (and in perl4) +prints "4|4". + +=head2 Changes to tainting checks + +A bug in previous versions may have failed to detect some insecure +conditions when taint checks are turned on. (Taint checks are used +in setuid or setgid scripts, or when explicitly turned on with the +C<-T> invocation option.) Although it's unlikely, this may cause a +previously-working script to now fail, which should be construed +as a blessing since that indicates a potentially-serious security +hole was just plugged. + +The new restrictions when tainting include: + +=over 4 + +=item No glob() or <*> + +These operators may spawn the C shell (csh), which cannot be made +safe. This restriction will be lifted in a future version of Perl +when globbing is implemented without the use of an external program. + +=item No spawning if tainted $CDPATH, $ENV, $BASH_ENV + +These environment variables may alter the behavior of spawned programs +(especially shells) in ways that subvert security. So now they are +treated as dangerous, in the manner of $IFS and $PATH. + +=item No spawning if tainted $TERM doesn't look like a terminal name + +Some termcap libraries do unsafe things with $TERM. However, it would be +unnecessarily harsh to treat all $TERM values as unsafe, since only shell +metacharacters can cause trouble in $TERM. So a tainted $TERM is +considered to be safe if it contains only alphanumerics, underscores, +dashes, and colons, and unsafe if it contains other characters (including +whitespace). + +=back + +=head2 New Opcode module and revised Safe module + +A new Opcode module supports the creation, manipulation and +application of opcode masks. The revised Safe module has a new API +and is implemented using the new Opcode module. Please read the new +Opcode and Safe documentation. + +=head2 Embedding improvements + +In older versions of Perl it was not possible to create more than one +Perl interpreter instance inside a single process without leaking like a +sieve and/or crashing. The bugs that caused this behavior have all been +fixed. However, you still must take care when embedding Perl in a C +program. See the updated perlembed manpage for tips on how to manage +your interpreters. + +=head2 Internal change: FileHandle class based on IO::* classes + +File handles are now stored internally as type IO::Handle. The +FileHandle module is still supported for backwards compatibility, but +it is now merely a front end to the IO::* modules, specifically +IO::Handle, IO::Seekable, and IO::File. We suggest, but do not +require, that you use the IO::* modules in new code. + +In harmony with this change, C<*GLOB{FILEHANDLE}> is now just a +backward-compatible synonym for C<*GLOB{IO}>. + +=head2 Internal change: PerlIO abstraction interface + +It is now possible to build Perl with AT&T's sfio IO package +instead of stdio. See L for more details, and +the F file for how to use it. + +=head2 New and changed syntax + +=over 4 + +=item $coderef->(PARAMS) + +A subroutine reference may now be suffixed with an arrow and a +(possibly empty) parameter list. This syntax denotes a call of the +referenced subroutine, with the given parameters (if any). + +This new syntax follows the pattern of S{FOO} >>> and +S[$foo] >>>: You may now write S> as +S($foo) >>>. All these arrow terms may be chained; +thus, S{FOO}}($bar) >>> may now be written +S{FOO}->($bar) >>>. + +=back + +=head2 New and changed builtin constants + +=over 4 + +=item __PACKAGE__ + +The current package name at compile time, or the undefined value if +there is no current package (due to a C directive). Like +C<__FILE__> and C<__LINE__>, C<__PACKAGE__> does I interpolate +into strings. + +=back + +=head2 New and changed builtin variables + +=over 4 + +=item $^E + +Extended error message on some platforms. (Also known as +$EXTENDED_OS_ERROR if you C). + +=item $^H + +The current set of syntax checks enabled by C. See the +documentation of C for more details. Not actually new, but +newly documented. +Because it is intended for internal use by Perl core components, +there is no C long name for this variable. + +=item $^M + +By default, running out of memory 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. Suppose that your Perl were +compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc. Then + + $^M = 'a' x (1<<16); + +would allocate a 64K buffer for use when in emergency. +See the F file for information on how to enable this option. +As a disincentive to casual use of this advanced feature, +there is no C long name for this variable. + +=back + +=head2 New and changed builtin functions + +=over 4 + +=item delete on slices + +This now works. (e.g. C) + +=item flock + +is now supported on more platforms, prefers fcntl to lockf when +emulating, and always flushes before (un)locking. + +=item printf and sprintf + +Perl now implements these functions itself; it doesn't use the C +library function sprintf() any more, except for floating-point +numbers, and even then only known flags are allowed. As a result, it +is now possible to know which conversions and flags will work, and +what they will do. + +The new conversions in Perl's sprintf() are: + + %i a synonym for %d + %p a pointer (the address of the Perl value, in hexadecimal) + %n special: *stores* the number of characters output so far + into the next variable in the parameter list + +The new flags that go between the C<%> and the conversion are: + + # prefix octal with "0", hex with "0x" + h interpret integer as C type "short" or "unsigned short" + V interpret integer as Perl's standard integer type + +Also, where a number would appear in the flags, an asterisk ("*") may +be used instead, in which case Perl uses the next item in the +parameter list as the given number (that is, as the field width or +precision). If a field width obtained through "*" is negative, it has +the same effect as the '-' flag: left-justification. + +See L for a complete list of conversion and flags. + +=item keys as an lvalue + +As an lvalue, C allows you to increase the number of hash buckets +allocated for the given hash. This can gain you a measure of efficiency if +you know the hash is going to get big. (This is similar to pre-extending +an array by assigning a larger number to $#array.) If you say + + keys %hash = 200; + +then C<%hash> will have at least 200 buckets allocated for it. These +buckets will be retained even if you do C<%hash = ()>; use C if you want to free the storage while C<%hash> is still in scope. +You can't shrink the number of buckets allocated for the hash using +C in this way (but you needn't worry about doing this by accident, +as trying has no effect). + +=item my() in Control Structures + +You can now use my() (with or without the parentheses) in the control +expressions of control structures such as: + + while (defined(my $line = <>)) { + $line = lc $line; + } continue { + print $line; + } + + if ((my $answer = ) =~ /^y(es)?$/i) { + user_agrees(); + } elsif ($answer =~ /^n(o)?$/i) { + user_disagrees(); + } else { + chomp $answer; + die "`$answer' is neither `yes' nor `no'"; + } + +Also, you can declare a foreach loop control variable as lexical by +preceding it with the word "my". For example, in: + + foreach my $i (1, 2, 3) { + some_function(); + } + +$i is a lexical variable, and the scope of $i extends to the end of +the loop, but not beyond it. + +Note that you still cannot use my() on global punctuation variables +such as $_ and the like. + +=item pack() and unpack() + +A new format 'w' represents a BER compressed integer (as defined in +ASN.1). Its format is a sequence of one or more bytes, each of which +provides seven bits of the total value, with the most significant +first. Bit eight of each byte is set, except for the last byte, in +which bit eight is clear. + +If 'p' or 'P' are given undef as values, they now generate a NULL +pointer. + +Both pack() and unpack() now fail when their templates contain invalid +types. (Invalid types used to be ignored.) + +=item sysseek() + +The new sysseek() operator is a variant of seek() that sets and gets the +file's system read/write position, using the lseek(2) system call. It is +the only reliable way to seek before using sysread() or syswrite(). Its +return value is the new position, or the undefined value on failure. + +=item use VERSION + +If the first argument to C is a number, it is treated as a version +number instead of a module name. If the version of the Perl interpreter +is less than VERSION, then an error message is printed and Perl exits +immediately. Because C occurs at compile time, this check happens +immediately during the compilation process, unlike C, +which waits until runtime for the check. This is often useful if you +need to check the current Perl version before Cing library modules +which have changed in incompatible ways from older versions of Perl. +(We try not to do this more than we have to.) + +=item use Module VERSION LIST + +If the VERSION argument is present between Module and LIST, then the +C will call the VERSION method in class Module with the given +version as an argument. The default VERSION method, inherited from +the UNIVERSAL class, croaks if the given version is larger than the +value of the variable $Module::VERSION. (Note that there is not a +comma after VERSION!) + +This version-checking mechanism is similar to the one currently used +in the Exporter module, but it is faster and can be used with modules +that don't use the Exporter. It is the recommended method for new +code. + +=item prototype(FUNCTION) + +Returns the prototype of a function as a string (or C if the +function has no prototype). FUNCTION is a reference to or the name of the +function whose prototype you want to retrieve. +(Not actually new; just never documented before.) + +=item srand + +The default seed for C, which used to be C