Wala shell

Advanced PHP File Manager

Server IP: 127.0.0.1 | PHP Version: 8.3.30 | Domains Hosted: 54

Name	Size	Last Modified
📁 ..	-	2026-04-05 19:18
📄 AnyDBM_File.pm package AnyDBM_File; use warnings; use strict; use 5.006_001; our $VERSION = '1.01'; our @ISA = qw(NDBM_File DB_File GDBM_File SDBM_File ODBM_File) unless @ISA; my $mod; for $mod (@ISA) { if (eval "require $mod") { @ISA = ($mod); # if we leave @ISA alone, warnings abound return 1; } } die "No DBM package was successfully found or installed"; __END__ =head1 NAME AnyDBM_File - provide framework for multiple DBMs NDBM_File, DB_File, GDBM_File, SDBM_File, ODBM_File - various DBM implementations =head1 SYNOPSIS use AnyDBM_File; =head1 DESCRIPTION This module is a "pure virtual base class"--it has nothing of its own. It's just there to inherit from one of the various DBM packages. It prefers ndbm for compatibility reasons with Perl 4, then Berkeley DB (See L<DB_File>), GDBM, SDBM (which is always there--it comes with Perl), and finally ODBM. This way old programs that used to use NDBM via dbmopen() can still do so, but new ones can reorder @ISA: BEGIN { @AnyDBM_File::ISA = qw(DB_File GDBM_File NDBM_File) } use AnyDBM_File; Having multiple DBM implementations makes it trivial to copy database formats: use Fcntl; use NDBM_File; use DB_File; tie %newhash, 'DB_File', $new_filename, O_CREAT\|O_RDWR; tie %oldhash, 'NDBM_File', $old_filename, 1, 0; %newhash = %oldhash; =head2 DBM Comparisons Here's a partial table of features the different packages offer: odbm ndbm sdbm gdbm bsd-db ---- ---- ---- ---- ------ Linkage comes w/ perl yes yes yes yes yes Src comes w/ perl no no yes no no Comes w/ many unix os yes yes[0] no no no Builds ok on !unix ? ? yes yes ? Code Size ? ? small big big Database Size ? ? small big? ok[1] Speed ? ? slow ok fast FTPable no no yes yes yes Easy to build N/A N/A yes yes ok[2] Size limits 1k 4k 1k[3] none none Byte-order independent no no no no yes Licensing restrictions ? ? no yes no =over 4 =item [0] on mixed universe machines, may be in the bsd compat library, which is often shunned. =item [1] Can be trimmed if you compile for one access method. =item [2] See L<DB_File>. Requires symbolic links. =item [3] By default, but can be redefined. =back =head1 SEE ALSO dbm(3), ndbm(3), DB_File(3), L<perldbmfilter> =cut	2.56 KB	2025-07-28 03:53
📄 AutoLoader.pm package AutoLoader; use strict; use 5.006_001; our($VERSION, $AUTOLOAD); my $is_dosish; my $is_epoc; my $is_vms; my $is_macos; BEGIN { $is_dosish = $^O eq 'dos' \|\| $^O eq 'os2' \|\| $^O eq 'MSWin32' \|\| $^O eq 'NetWare'; $is_epoc = $^O eq 'epoc'; $is_vms = $^O eq 'VMS'; $is_macos = $^O eq 'MacOS'; $VERSION = '5.74'; } AUTOLOAD { my $sub = $AUTOLOAD; autoload_sub($sub); goto &$sub; } sub autoload_sub { my $sub = shift; my $filename = AutoLoader::find_filename( $sub ); my $save = $@; local $!; # Do not munge the value. eval { local $SIG{__DIE__}; require $filename }; if ($@) { if (substr($sub,-9) eq '::DESTROY') { no strict 'refs'; $sub = sub {}; $@ = undef; } elsif ($@ =~ /^Can't locate/) { # The load might just have failed because the filename was too # long for some old SVR3 systems which treat long names as errors. # If we can successfully truncate a long name then it's worth a go. # There is a slight risk that we could pick up the wrong file here # but autosplit should have warned about that when splitting. if ($filename =~ s/(\w{12,})\.al$/substr($1,0,11).".al"/e){ eval { local $SIG{__DIE__}; require $filename }; } } if ($@){ $@ =~ s/ at .\n//; my $error = $@; require Carp; Carp::croak($error); } } $@ = $save; return 1; } sub find_filename { my $sub = shift; my $filename; # Braces used to preserve $1 et al. { # Try to find the autoloaded file from the package-qualified # name of the sub. e.g., if the sub needed is # Getopt::Long::GetOptions(), then $INC{Getopt/Long.pm} is # something like '/usr/lib/perl5/Getopt/Long.pm', and the # autoload file is '/usr/lib/perl5/auto/Getopt/Long/GetOptions.al'. # # However, if @INC is a relative path, this might not work. If, # for example, @INC = ('lib'), then $INC{Getopt/Long.pm} is # 'lib/Getopt/Long.pm', and we want to require # 'auto/Getopt/Long/GetOptions.al' (without the leading 'lib'). # In this case, we simple prepend the 'auto/' and let the # C<require> take care of the searching for us. my ($pkg,$func) = ($sub =~ /(.)::([^:]+)$/); $pkg =~ s#::#/#g; if (defined($filename = $INC{"$pkg.pm"})) { if ($is_macos) { $pkg =~ tr#/#:#; $filename = undef unless $filename =~ s#^(.)$pkg\.pm\z#$1auto:$pkg:$func.al#s; } else { $filename = undef unless $filename =~ s#^(.)$pkg\.pm\z#$1auto/$pkg/$func.al#s; } # if the file exists, then make sure that it is a # a fully anchored path (i.e either '/usr/lib/auto/foo/bar.al', # or './lib/auto/foo/bar.al'. This avoids C<require> searching # (and failing) to find the 'lib/auto/foo/bar.al' because it # looked for 'lib/lib/auto/foo/bar.al', given @INC = ('lib'). if (defined $filename and -r $filename) { unless ($filename =~ m\|^/\|s) { if ($is_dosish) { unless ($filename =~ m{^([a-z]:)?[\\/]}is) { if ($^O ne 'NetWare') { $filename = "./$filename"; } else { $filename = "$filename"; } } } elsif ($is_epoc) { unless ($filename =~ m{^([a-z?]:)?[\\/]}is) { $filename = "./$filename"; } } elsif ($is_vms) { # XXX todo by VMSmiths $filename = "./$filename"; } elsif (!$is_macos) { $filename = "./$filename"; } } } else { $filename = undef; } } unless (defined $filename) { # let C<require> do the searching $filename = "auto/$sub.al"; $filename =~ s#::#/#g; } } return $filename; } sub import { my $pkg = shift; my $callpkg = caller; # # Export symbols, but not by accident of inheritance. # if ($pkg eq 'AutoLoader') { if ( @_ and $_[0] =~ /^&?AUTOLOAD$/ ) { no strict 'refs'; { $callpkg . '::AUTOLOAD' } = \&AUTOLOAD; } } # # Try to find the autosplit index file. Eg., if the call package # is POSIX, then $INC{POSIX.pm} is something like # '/usr/local/lib/perl5/POSIX.pm', and the autosplit index file is in # '/usr/local/lib/perl5/auto/POSIX/autosplit.ix', so we require that. # # However, if @INC is a relative path, this might not work. If, # for example, @INC = ('lib'), then # $INC{POSIX.pm} is 'lib/POSIX.pm', and we want to require # 'auto/POSIX/autosplit.ix' (without the leading 'lib'). # (my $calldir = $callpkg) =~ s#::#/#g; my $path = $INC{$calldir . '.pm'}; if (defined($path)) { # Try absolute path name, but only eval it if the # transformation from module path to autosplit.ix path # succeeded! my $replaced_okay; if ($is_macos) { (my $malldir = $calldir) =~ tr#/#:#; $replaced_okay = ($path =~ s#^(.)$malldir\.pm\z#$1auto:$malldir:autosplit.ix#s); } else { $replaced_okay = ($path =~ s#^(.)$calldir\.pm\z#$1auto/$calldir/autosplit.ix#); } eval { require $path; } if $replaced_okay; # If that failed, try relative path with normal @INC searching. if (!$replaced_okay or $@) { $path ="auto/$calldir/autosplit.ix"; eval { require $path; }; } if ($@) { my $error = $@; require Carp; Carp::carp($error); } } } sub unimport { my $callpkg = caller; no strict 'refs'; for my $exported (qw( AUTOLOAD )) { my $symname = $callpkg . '::' . $exported; undef { $symname } if \&{ $symname } == \&{ $exported }; { $symname } = \&{ $symname }; } } 1; __END__ =head1 NAME AutoLoader - load subroutines only on demand =head1 SYNOPSIS package Foo; use AutoLoader 'AUTOLOAD'; # import the default AUTOLOAD subroutine package Bar; use AutoLoader; # don't import AUTOLOAD, define our own sub AUTOLOAD { ... $AutoLoader::AUTOLOAD = "..."; goto &AutoLoader::AUTOLOAD; } =head1 DESCRIPTION The B<AutoLoader> module works with the B<AutoSplit> module and the C<__END__> token to defer the loading of some subroutines until they are used rather than loading them all at once. To use B<AutoLoader>, the author of a module has to place the definitions of subroutines to be autoloaded after an C<__END__> token. (See L<perldata>.) The B<AutoSplit> module can then be run manually to extract the definitions into individual files F<auto/funcname.al>. B<AutoLoader> implements an AUTOLOAD subroutine. When an undefined subroutine in is called in a client module of B<AutoLoader>, B<AutoLoader>'s AUTOLOAD subroutine attempts to locate the subroutine in a file with a name related to the location of the file from which the client module was read. As an example, if F<POSIX.pm> is located in F</usr/local/lib/perl5/POSIX.pm>, B<AutoLoader> will look for perl subroutines B<POSIX> in F</usr/local/lib/perl5/auto/POSIX/.al>, where the C<.al> file has the same name as the subroutine, sans package. If such a file exists, AUTOLOAD will read and evaluate it, thus (presumably) defining the needed subroutine. AUTOLOAD will then C<goto> the newly defined subroutine. Once this process completes for a given function, it is defined, so future calls to the subroutine will bypass the AUTOLOAD mechanism. =head2 Subroutine Stubs In order for object method lookup and/or prototype checking to operate correctly even when methods have not yet been defined it is necessary to "forward declare" each subroutine (as in C<sub NAME;>). See L<perlsub/"SYNOPSIS">. Such forward declaration creates "subroutine stubs", which are place holders with no code. The AutoSplit and B<AutoLoader> modules automate the creation of forward declarations. The AutoSplit module creates an 'index' file containing forward declarations of all the AutoSplit subroutines. When the AutoLoader module is 'use'd it loads these declarations into its callers package. Because of this mechanism it is important that B<AutoLoader> is always C<use>d and not C<require>d. =head2 Using B<AutoLoader>'s AUTOLOAD Subroutine In order to use B<AutoLoader>'s AUTOLOAD subroutine you I<must> explicitly import it: use AutoLoader 'AUTOLOAD'; =head2 Overriding B<AutoLoader>'s AUTOLOAD Subroutine Some modules, mainly extensions, provide their own AUTOLOAD subroutines. They typically need to check for some special cases (such as constants) and then fallback to B<AutoLoader>'s AUTOLOAD for the rest. Such modules should I<not> import B<AutoLoader>'s AUTOLOAD subroutine. Instead, they should define their own AUTOLOAD subroutines along these lines: use AutoLoader; use Carp; sub AUTOLOAD { my $sub = $AUTOLOAD; (my $constname = $sub) =~ s/.:://; my $val = constant($constname, @_ ? $_[0] : 0); if ($! != 0) { if ($! =~ /Invalid/ \|\| $!{EINVAL}) { $AutoLoader::AUTOLOAD = $sub; goto &AutoLoader::AUTOLOAD; } else { croak "Your vendor has not defined constant $constname"; } } *$sub = sub { $val }; # same as: eval "sub $sub { $val }"; goto &$sub; } If any module's own AUTOLOAD subroutine has no need to fallback to the AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit subroutines), then that module should not use B<AutoLoader> at all. =head2 Package Lexicals Package lexicals declared with C<my> in the main block of a package using B<AutoLoader> will not be visible to auto-loaded subroutines, due to the fact that the given scope ends at the C<__END__> marker. A module using such variables as package globals will not work properly under the B<AutoLoader>. The C<vars> pragma (see L<perlmod/"vars">) may be used in such situations as an alternative to explicitly qualifying all globals with the package namespace. Variables pre-declared with this pragma will be visible to any autoloaded routines (but will not be invisible outside the package, unfortunately). =head2 Not Using AutoLoader You can stop using AutoLoader by simply no AutoLoader; =head2 B<AutoLoader> vs. B<SelfLoader> The B<AutoLoader> is similar in purpose to B<SelfLoader>: both delay the loading of subroutines. B<SelfLoader> uses the C<__DATA__> marker rather than C<__END__>. While this avoids the use of a hierarchy of disk files and the associated open/close for each routine loaded, B<SelfLoader> suffers a startup speed disadvantage in the one-time parsing of the lines after C<__DATA__>, after which routines are cached. B<SelfLoader> can also handle multiple packages in a file. B<AutoLoader> only reads code as it is requested, and in many cases should be faster, but requires a mechanism like B<AutoSplit> be used to create the individual files. L<ExtUtils::MakeMaker> will invoke B<AutoSplit> automatically if B<AutoLoader> is used in a module source file. =head2 Forcing AutoLoader to Load a Function Sometimes, it can be necessary or useful to make sure that a certain function is fully loaded by AutoLoader. This is the case, for example, when you need to wrap a function to inject debugging code. It is also helpful to force early loading of code before forking to make use of copy-on-write as much as possible. Starting with AutoLoader 5.73, you can call the C<AutoLoader::autoload_sub> function with the fully-qualified name of the function to load from its F<.al> file. The behaviour is exactly the same as if you called the function, triggering the regular C<AUTOLOAD> mechanism, but it does not actually execute the autoloaded function. =head1 CAVEATS AutoLoaders prior to Perl 5.002 had a slightly different interface. Any old modules which use B<AutoLoader> should be changed to the new calling style. Typically this just means changing a require to a use, adding the explicit C<'AUTOLOAD'> import if needed, and removing B<AutoLoader> from C<@ISA>. On systems with restrictions on file name length, the file corresponding to a subroutine may have a shorter name that the routine itself. This can lead to conflicting file names. The I<AutoSplit> package warns of these potential conflicts when used to split a module. AutoLoader may fail to find the autosplit files (or even find the wrong ones) in cases where C<@INC> contains relative paths, B<and> the program does C<chdir>. =head1 SEE ALSO L<SelfLoader> - an autoloader that doesn't use external files. =head1 AUTHOR C<AutoLoader> is maintained by the perl5-porters. Please direct any questions to the canonical mailing list. Anything that is applicable to the CPAN release can be sent to its maintainer, though. Author and Maintainer: The Perl5-Porters <perl5-porters@perl.org> Maintainer of the CPAN release: Steffen Mueller <smueller@cpan.org> =head1 COPYRIGHT AND LICENSE This package has been part of the perl core since the first release of perl5. It has been released separately to CPAN so older installations can benefit from bug fixes. This package has the same copyright and license as the perl core: Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2011, 2012, 2013 by Larry Wall and others All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" which comes with this Kit. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details. You should have received a copy of the Artistic License with this Kit, in the file named "Artistic". If not, I'll be glad to provide one. You should also have received a copy of the GNU General Public License along with this program in the file named "Copying". If not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA or visit their web page on the internet at http://www.gnu.org/copyleft/gpl.html. For those of you that choose to use the GNU General Public License, my interpretation of the GNU General Public License is that no Perl script falls under the terms of the GPL unless you explicitly put said script under the terms of the GPL yourself. Furthermore, any object code linked with perl does not automatically fall under the terms of the GPL, provided such object code only adds definitions of subroutines and variables, and does not otherwise impair the resulting interpreter from executing any standard Perl script. I consider linking in C subroutines in this manner to be the moral equivalent of defining subroutines in the Perl language itself. You may sell such an object file as proprietary provided that you provide or offer to provide the Perl source, as specified by the GNU General Public License. (This is merely an alternate way of specifying input to the program.) You may also sell a binary produced by the dumping of a running Perl script that belongs to you, provided that you provide or offer to provide the Perl source as specified by the GPL. (The fact that a Perl interpreter and your code are in the same binary file is, in this case, a form of mere aggregation.) This is my interpretation of the GPL. If you still have concerns or difficulties understanding my intent, feel free to contact me. Of course, the Artistic License spells all this out for your protection, so you may prefer to use that. =cut	15.43 KB	2025-07-28 03:54
📁 B	-	2026-03-21 15:55
📄 CORE.pod =head1 NAME CORE - Namespace for Perl's core routines =head1 SYNOPSIS BEGIN { CORE::GLOBAL::hex = sub { 1; }; } print hex("0x50"),"\n"; # prints 1 print CORE::hex("0x50"),"\n"; # prints 80 CORE::say "yes"; # prints yes BEGIN { shove = \&CORE::push; } shove @array, 1,2,3; # pushes on to @array =head1 DESCRIPTION The C<CORE> namespace gives access to the original built-in functions of Perl. The C<CORE> package is built into Perl, and therefore you do not need to use or require a hypothetical "CORE" module prior to accessing routines in this namespace. A list of the built-in functions in Perl can be found in L<perlfunc>. For all Perl keywords, a C<CORE::> prefix will force the built-in function to be used, even if it has been overridden or would normally require the L<feature> pragma. Despite appearances, this has nothing to do with the CORE package, but is part of Perl's syntax. For many Perl functions, the CORE package contains real subroutines. This feature is new in Perl 5.16. You can take references to these and make aliases. However, some can only be called as barewords; i.e., you cannot use ampersand syntax (C<&foo>) or call them through references. See the C<shove> example above. These subroutines exist for all keywords except the following: C<__DATA__>, C<__END__>, C<and>, C<cmp>, C<default>, C<do>, C<dump>, C<else>, C<elsif>, C<eq>, C<eval>, C<for>, C<foreach>, C<format>, C<ge>, C<given>, C<goto>, C<grep>, C<gt>, C<if>, C<last>, C<le>, C<local>, C<lt>, C<m>, C<map>, C<my>, C<ne>, C<next>, C<no>, C<or>, C<our>, C<package>, C<print>, C<printf>, C<q>, C<qq>, C<qr>, C<qw>, C<qx>, C<redo>, C<require>, C<return>, C<s>, C<say>, C<sort>, C<state>, C<sub>, C<tr>, C<unless>, C<until>, C<use>, C<when>, C<while>, C<x>, C<xor>, C<y> Calling with ampersand syntax and through references does not work for the following functions, as they have special syntax that cannot always be translated into a simple list (e.g., C<eof> vs C<eof()>): C<chdir>, C<chomp>, C<chop>, C<defined>, C<delete>, C<eof>, C<exec>, C<exists>, C<lstat>, C<split>, C<stat>, C<system>, C<truncate>, C<unlink> =head1 OVERRIDING CORE FUNCTIONS To override a Perl built-in routine with your own version, you need to import it at compile-time. This can be conveniently achieved with the C<subs> pragma. This will affect only the package in which you've imported the said subroutine: use subs 'chdir'; sub chdir { ... } chdir $somewhere; To override a built-in globally (that is, in all namespaces), you need to import your function into the C<CORE::GLOBAL> pseudo-namespace at compile time: BEGIN { *CORE::GLOBAL::hex = sub { # ... your code here }; } The new routine will be called whenever a built-in function is called without a qualifying package: print hex("0x50"),"\n"; # prints 1 In both cases, if you want access to the original, unaltered routine, use the C<CORE::> prefix: print CORE::hex("0x50"),"\n"; # prints 80 =head1 AUTHOR This documentation provided by Tels <nospam-abuse@bloodgate.com> 2007. =head1 SEE ALSO L<perlsub>, L<perlfunc>. =cut	3.11 KB	2025-07-28 03:53
📁 Class	-	2026-03-21 15:44
📁 File	-	2026-03-21 15:44
📄 FileHandle.pm package FileHandle; use 5.006; use strict; our($VERSION, @ISA, @EXPORT, @EXPORT_OK); $VERSION = "2.03"; require IO::File; @ISA = qw(IO::File); @EXPORT = qw(_IOFBF _IOLBF _IONBF); @EXPORT_OK = qw( pipe autoflush output_field_separator output_record_separator input_record_separator input_line_number format_page_number format_lines_per_page format_lines_left format_name format_top_name format_line_break_characters format_formfeed print printf getline getlines ); # # Everything we're willing to export, we must first import. # IO::Handle->import( grep { !defined(&$_) } @EXPORT, @EXPORT_OK ); # # Some people call "FileHandle::function", so all the functions # that were in the old FileHandle class must be imported, too. # { no strict 'refs'; my %import = ( 'IO::Handle' => [qw(DESTROY new_from_fd fdopen close fileno getc ungetc gets eof flush error clearerr setbuf setvbuf _open_mode_string)], 'IO::Seekable' => [qw(seek tell getpos setpos)], 'IO::File' => [qw(new new_tmpfile open)] ); for my $pkg (keys %import) { for my $func (@{$import{$pkg}}) { my $c = {"${pkg}::$func"}{CODE} or die "${pkg}::$func missing"; $func = $c; } } } # # Specialized importer for Fcntl magic. # sub import { my $pkg = shift; my $callpkg = caller; require Exporter; Exporter::export($pkg, $callpkg, @_); # # If the Fcntl extension is available, # export its constants. # eval { require Fcntl; Exporter::export('Fcntl', $callpkg); }; } ################################################ # This is the only exported function we define; # the rest come from other classes. # sub pipe { my $r = IO::Handle->new; my $w = IO::Handle->new; CORE::pipe($r, $w) or return undef; ($r, $w); } # Rebless standard file handles bless STDIN{IO}, "FileHandle" if ref STDIN{IO} eq "IO::Handle"; bless STDOUT{IO}, "FileHandle" if ref STDOUT{IO} eq "IO::Handle"; bless STDERR{IO}, "FileHandle" if ref STDERR{IO} eq "IO::Handle"; 1; __END__ =head1 NAME FileHandle - supply object methods for filehandles =head1 SYNOPSIS use FileHandle; $fh = FileHandle->new; if ($fh->open("< file")) { print <$fh>; $fh->close; } $fh = FileHandle->new("> FOO"); if (defined $fh) { print $fh "bar\n"; $fh->close; } $fh = FileHandle->new("file", "r"); if (defined $fh) { print <$fh>; undef $fh; # automatically closes the file } $fh = FileHandle->new("file", O_WRONLY\|O_APPEND); if (defined $fh) { print $fh "corge\n"; undef $fh; # automatically closes the file } $pos = $fh->getpos; $fh->setpos($pos); $fh->setvbuf($buffer_var, _IOLBF, 1024); ($readfh, $writefh) = FileHandle::pipe; autoflush STDOUT 1; =head1 DESCRIPTION NOTE: This class is now a front-end to the IO::* classes. C<FileHandle::new> creates a C<FileHandle>, which is a reference to a newly created symbol (see the C<Symbol> package). If it receives any parameters, they are passed to C<FileHandle::open>; if the open fails, the C<FileHandle> object is destroyed. Otherwise, it is returned to the caller. C<FileHandle::new_from_fd> creates a C<FileHandle> like C<new> does. It requires two parameters, which are passed to C<FileHandle::fdopen>; if the fdopen fails, the C<FileHandle> object is destroyed. Otherwise, it is returned to the caller. C<FileHandle::open> accepts one parameter or two. With one parameter, it is just a front end for the built-in C<open> function. With two parameters, the first parameter is a filename that may include whitespace or other special characters, and the second parameter is the open mode, optionally followed by a file permission value. If C<FileHandle::open> receives a Perl mode string (">", "+<", etc.) or a POSIX fopen() mode string ("w", "r+", etc.), it uses the basic Perl C<open> operator. If C<FileHandle::open> is given a numeric mode, it passes that mode and the optional permissions value to the Perl C<sysopen> operator. For convenience, C<FileHandle::import> tries to import the O_XXX constants from the Fcntl module. If dynamic loading is not available, this may fail, but the rest of FileHandle will still work. C<FileHandle::fdopen> is like C<open> except that its first parameter is not a filename but rather a file handle name, a FileHandle object, or a file descriptor number. If the C functions fgetpos() and fsetpos() are available, then C<FileHandle::getpos> returns an opaque value that represents the current position of the FileHandle, and C<FileHandle::setpos> uses that value to return to a previously visited position. If the C function setvbuf() is available, then C<FileHandle::setvbuf> sets the buffering policy for the FileHandle. The calling sequence for the Perl function is the same as its C counterpart, including the macros C<_IOFBF>, C<_IOLBF>, and C<_IONBF>, except that the buffer parameter specifies a scalar variable to use as a buffer. WARNING: A variable used as a buffer by C<FileHandle::setvbuf> must not be modified in any way until the FileHandle is closed or until C<FileHandle::setvbuf> is called again, or memory corruption may result! See L<perlfunc> for complete descriptions of each of the following supported C<FileHandle> methods, which are just front ends for the corresponding built-in functions: close fileno getc gets eof clearerr seek tell See L<perlvar> for complete descriptions of each of the following supported C<FileHandle> methods: autoflush output_field_separator output_record_separator input_record_separator input_line_number format_page_number format_lines_per_page format_lines_left format_name format_top_name format_line_break_characters format_formfeed Furthermore, for doing normal I/O you might need these: =over 4 =item $fh->print See L<perlfunc/print>. =item $fh->printf See L<perlfunc/printf>. =item $fh->getline This works like <$fh> described in L<perlop/"I/O Operators"> except that it's more readable and can be safely called in a list context but still returns just one line. =item $fh->getlines This works like <$fh> when called in a list context to read all the remaining lines in a file, except that it's more readable. It will also croak() if accidentally called in a scalar context. =back There are many other functions available since FileHandle is descended from IO::File, IO::Seekable, and IO::Handle. Please see those respective pages for documentation on more functions. =head1 SEE ALSO The B<IO> extension, L<perlfunc>, L<perlop/"I/O Operators">. =cut	6.63 KB	2025-07-28 03:54
📁 Getopt	-	2026-03-21 15:55
📁 IPC	-	2026-03-21 15:44
📄 Internals.pod =head1 NAME Internals - Reserved special namespace for internals related functions =head1 SYNOPSIS $is_ro= Internals::SvREADONLY($x) $refcnt= Internals::SvREFCNT($x) hv_clear_placeholders(%hash); =head1 DESCRIPTION The Internals namespace is used by the core Perl development team to expose certain low level internals routines for testing and other purposes. In theory these routines were not and are not intended to be used outside of the perl core, and are subject to change and removal at any time. In practice people have come to depend on these over the years, despite being historically undocumented, so we will provide some level of forward compatibility for some time. Nevertheless you can assume that any routine documented here is experimental or deprecated and you should find alternatives to their use. =head2 FUNCTIONS =over 4 =item SvREFCNT(THING [, $value]) Historically Perl has been a refcounted language. This means that each variable tracks how many things reference it, and when the variable is no longer referenced it will automatically free itself. In theory Perl code should not have to care about this, and in a future version Perl might change to some other strategy, although in practice this is unlikely. This function allows one to violate the abstraction of variables and get or set the refcount of a variable, and in generally is really only useful in code that is testing refcount behavior. NOTE You are strongly discouraged from using this function in non-test code and especially discouraged from using the set form of this function. The results of doing so may result in segmentation faults or other undefined behavior. =item SvREADONLY(THING, [, $value]) Set or get whether a variable is readonly or not. Exactly what the readonly flag means depend on the type of the variable affected and the version of perl used. You are strongly discouraged from using this function directly. It is used by various core modules, like C<Hash::Util>, and the C<constant> pragma to implement higher-level behavior which should be used instead. See the core implementation for the exact meaning of the readonly flag for each internal variable type. =item hv_clear_placeholders(%hash) Clear any placeholders from a locked hash. Should not be used directly. You should use the wrapper functions provided by Hash::Util instead. As of 5.25 also available as C< Hash::Util::_clear_placeholders(%hash) > =back =head1 AUTHOR Perl core development team. =head1 SEE ALSO L<perlguts> L<Hash::Util> L<constant> universal.c =cut	2.51 KB	2025-07-28 03:53
📁 Math	-	2026-03-21 15:55
📄 PerlIO.pm package PerlIO; our $VERSION = '1.11'; # Map layer name to package that defines it our %alias; sub import { my $class = shift; while (@_) { my $layer = shift; if (exists $alias{$layer}) { $layer = $alias{$layer} } else { $layer = "${class}::$layer"; } eval { require $layer =~ s{::}{/}gr . '.pm' }; warn $@ if $@; } } sub F_UTF8 () { 0x8000 } 1; __END__ =head1 NAME PerlIO - On demand loader for PerlIO layers and root of PerlIO::* name space =head1 SYNOPSIS # support platform-native and CRLF text files open(my $fh, "<:crlf", "my.txt") or die "open failed: $!"; # append UTF-8 encoded text open(my $fh, ">>:encoding(UTF-8)", "some.log") or die "open failed: $!"; # portably open a binary file for reading open(my $fh, "<", "his.jpg") or die "open failed: $!"; binmode($fh) or die "binmode failed: $!"; Shell: PERLIO=:perlio perl .... =head1 DESCRIPTION When an undefined layer 'foo' is encountered in an C<open> or C<binmode> layer specification then C code performs the equivalent of: use PerlIO 'foo'; The Perl code in PerlIO.pm then attempts to locate a layer by doing require PerlIO::foo; Otherwise the C<PerlIO> package is a place holder for additional PerlIO related functions. =head2 Layers Generally speaking, PerlIO layers (previously sometimes referred to as "disciplines") are an ordered stack applied to a filehandle (specified as a space- or colon-separated list, conventionally written with a leading colon). Each layer performs some operation on any input or output, except when bypassed such as with C<sysread> or C<syswrite>. Read operations go through the stack in the order they are set (left to right), and write operations in the reverse order. There are also layers which actually just set flags on lower layers, or layers that modify the current stack but don't persist on the stack themselves; these are referred to as pseudo-layers. When opening a handle, it will be opened with any layers specified explicitly in the open() call (or the platform defaults, if specified as a colon with no following layers). If layers are not explicitly specified, the handle will be opened with the layers specified by the L<${^OPEN}\|perlvar/"${^OPEN}"> variable (usually set by using the L<open> pragma for a lexical scope, or the C<-C> command-line switch or C<PERL_UNICODE> environment variable for the main program scope). If layers are not specified in the open() call or C<${^OPEN}> variable, the handle will be opened with the default layer stack configured for that architecture; see L</"Defaults and how to override them">. Some layers will automatically insert required lower level layers if not present; for example C<:perlio> will insert C<:unix> below itself for low level IO, and C<:encoding> will insert the platform defaults for buffered IO. The C<binmode> function can be called on an opened handle to push additional layers onto the stack, which may also modify the existing layers. C<binmode> called with no layers will remove or unset any existing layers which transform the byte stream, making the handle suitable for binary data. The following layers are currently defined: =over 4 =item :unix Lowest level layer which provides basic PerlIO operations in terms of UNIX/POSIX numeric file descriptor calls (open(), read(), write(), lseek(), close()). It is used even on non-Unix architectures, and most other layers operate on top of it. =item :stdio Layer which calls C<fread>, C<fwrite> and C<fseek>/C<ftell> etc. Note that as this is "real" stdio it will ignore any layers beneath it and go straight to the operating system via the C library as usual. This layer implements both low level IO and buffering, but is rarely used on modern architectures. =item :perlio A from scratch implementation of buffering for PerlIO. Provides fast access to the buffer for C<sv_gets> which implements Perl's readline/E<lt>E<gt> and in general attempts to minimize data copying. C<:perlio> will insert a C<:unix> layer below itself to do low level IO. =item :crlf A layer that implements DOS/Windows like CRLF line endings. On read converts pairs of CR,LF to a single "\n" newline character. On write converts each "\n" to a CR,LF pair. Note that this layer will silently refuse to be pushed on top of itself. It currently does I<not> mimic MS-DOS as far as treating of Control-Z as being an end-of-file marker. On DOS/Windows like architectures where this layer is part of the defaults, it also acts like the C<:perlio> layer, and removing the CRLF translation (such as with C<:raw>) will only unset the CRLF translation flag. Since Perl 5.14, you can also apply another C<:crlf> layer later, such as when the CRLF translation must occur after an encoding layer. On other architectures, it is a mundane CRLF translation layer and can be added and removed normally. # translate CRLF after encoding on Perl 5.14 or newer binmode $fh, ":raw:encoding(UTF-16LE):crlf" or die "binmode failed: $!"; =item :utf8 Pseudo-layer that declares that the stream accepts Perl's I<internal> upgraded encoding of characters, which is approximately UTF-8 on ASCII machines, but UTF-EBCDIC on EBCDIC machines. This allows any character Perl can represent to be read from or written to the stream. This layer (which actually sets a flag on the preceding layer, and is implicitly set by any C<:encoding> layer) does not translate or validate byte sequences. It instead indicates that the byte stream will have been arranged by other layers to be provided in Perl's internal upgraded encoding, which Perl code (and correctly written XS code) will interpret as decoded Unicode characters. B<CAUTION>: Do not use this layer to translate from UTF-8 bytes, as invalid UTF-8 or binary data will result in malformed Perl strings. It is unlikely to produce invalid UTF-8 when used for output, though it will instead produce UTF-EBCDIC on EBCDIC systems. The C<:encoding(UTF-8)> layer (hyphen is significant) is preferred as it will ensure translation between valid UTF-8 bytes and valid Unicode characters. =item :bytes This is the inverse of the C<:utf8> pseudo-layer. It turns off the flag on the layer below so that data read from it is considered to be Perl's internal downgraded encoding, thus interpreted as the native single-byte encoding of Latin-1 or EBCDIC. Likewise on output Perl will warn if a "wide" character (a codepoint not in the range 0..255) is written to a such a stream. This is very dangerous to push on a handle using an C<:encoding> layer, as such a layer assumes to be working with Perl's internal upgraded encoding, so you will likely get a mangled result. Instead use C<:raw> or C<:pop> to remove encoding layers. =item :raw The C<:raw> pseudo-layer is I<defined> as being identical to calling C<binmode($fh)> - the stream is made suitable for passing binary data, i.e. each byte is passed as-is. The stream will still be buffered (but this was not always true before Perl 5.14). In Perl 5.6 and some books the C<:raw> layer is documented as the inverse of the C<:crlf> layer. That is no longer the case - other layers which would alter the binary nature of the stream are also disabled. If you want UNIX line endings on a platform that normally does CRLF translation, but still want UTF-8 or encoding defaults, the appropriate thing to do is to add C<:perlio> to the PERLIO environment variable, or open the handle explicitly with that layer, to replace the platform default of C<:crlf>. The implementation of C<:raw> is as a pseudo-layer which when "pushed" pops itself and then any layers which would modify the binary data stream. (Undoing C<:utf8> and C<:crlf> may be implemented by clearing flags rather than popping layers but that is an implementation detail.) As a consequence of the fact that C<:raw> normally pops layers, it usually only makes sense to have it as the only or first element in a layer specification. When used as the first element it provides a known base on which to build e.g. open(my $fh,">:raw:encoding(UTF-8)",...) or die "open failed: $!"; will construct a "binary" stream regardless of the platform defaults, but then enable UTF-8 translation. =item :pop A pseudo-layer that removes the top-most layer. Gives Perl code a way to manipulate the layer stack. Note that C<:pop> only works on real layers and will not undo the effects of pseudo-layers or flags like C<:utf8>. An example of a possible use might be: open(my $fh,...) or die "open failed: $!"; ... binmode($fh,":encoding(...)") or die "binmode failed: $!"; # next chunk is encoded ... binmode($fh,":pop") or die "binmode failed: $!"; # back to un-encoded A more elegant (and safer) interface is needed. =item :win32 On Win32 platforms this I<experimental> layer uses the native "handle" IO rather than the unix-like numeric file descriptor layer. Known to be buggy as of Perl 5.8.2. =back =head2 Custom Layers It is possible to write custom layers in addition to the above builtin ones, both in C/XS and Perl, as a module named C<< PerlIO::<layer name> >>. Some custom layers come with the Perl distribution. =over 4 =item :encoding Use C<:encoding(ENCODING)> to transparently do character set and encoding transformations, for example from Shift-JIS to Unicode. Note that an C<:encoding> also enables C<:utf8>. See L<PerlIO::encoding> for more information. =item :mmap A layer which implements "reading" of files by using C<mmap()> to make a (whole) file appear in the process's address space, and then using that as PerlIO's "buffer". This I<may> be faster in certain circumstances for large files, and may result in less physical memory use when multiple processes are reading the same file. Files which are not C<mmap()>-able revert to behaving like the C<:perlio> layer. Writes also behave like the C<:perlio> layer, as C<mmap()> for write needs extra house-keeping (to extend the file) which negates any advantage. The C<:mmap> layer will not exist if the platform does not support C<mmap()>. See L<PerlIO::mmap> for more information. =item :via C<:via(MODULE)> allows a transformation to be applied by an arbitrary Perl module, for example compression / decompression, encryption / decryption. See L<PerlIO::via> for more information. =item :scalar A layer implementing "in memory" files using scalar variables, automatically used in place of the platform defaults for IO when opening such a handle. As such, the scalar is expected to act like a file, only containing or storing bytes. See L<PerlIO::scalar> for more information. =back =head2 Alternatives to raw To get a binary stream an alternate method is to use: open(my $fh,"<","whatever") or die "open failed: $!"; binmode($fh) or die "binmode failed: $!"; This has the advantage of being backward compatible with older versions of Perl that did not use PerlIO or where C<:raw> was buggy (as it was before Perl 5.14). To get an unbuffered stream specify an unbuffered layer (e.g. C<:unix>) in the open call: open(my $fh,"<:unix",$path) or die "open failed: $!"; =head2 Defaults and how to override them If the platform is MS-DOS like and normally does CRLF to "\n" translation for text files then the default layers are: :unix:crlf Otherwise if C<Configure> found out how to do "fast" IO using the system's stdio (not common on modern architectures), then the default layers are: :stdio Otherwise the default layers are :unix:perlio Note that the "default stack" depends on the operating system and on the Perl version, and both the compile-time and runtime configurations of Perl. The default can be overridden by setting the environment variable PERLIO to a space or colon separated list of layers, however this cannot be used to set layers that require loading modules like C<:encoding>. This can be used to see the effect of/bugs in the various layers e.g. cd .../perl/t PERLIO=:stdio ./perl harness PERLIO=:perlio ./perl harness For the various values of PERLIO see L<perlrun/PERLIO>. The following table summarizes the default layers on UNIX-like and DOS-like platforms and depending on the setting of C<$ENV{PERLIO}>: PERLIO UNIX-like DOS-like ------ --------- -------- unset / "" :unix:perlio / :stdio [1] :unix:crlf :stdio :stdio :stdio :perlio :unix:perlio :unix:perlio # [1] ":stdio" if Configure found out how to do "fast stdio" (depends # on the stdio implementation) and in Perl 5.8, else ":unix:perlio" =head2 Querying the layers of filehandles The following returns the B<names> of the PerlIO layers on a filehandle. my @layers = PerlIO::get_layers($fh); # Or FH, *FH, "FH". The layers are returned in the order an open() or binmode() call would use them, and without colons. By default the layers from the input side of the filehandle are returned; to get the output side, use the optional C<output> argument: my @layers = PerlIO::get_layers($fh, output => 1); (Usually the layers are identical on either side of a filehandle but for example with sockets there may be differences.) There is no set_layers(), nor does get_layers() return a tied array mirroring the stack, or anything fancy like that. This is not accidental or unintentional. The PerlIO layer stack is a bit more complicated than just a stack (see for example the behaviour of C<:raw>). You are supposed to use open() and binmode() to manipulate the stack. B<Implementation details follow, please close your eyes.> The arguments to layers are by default returned in parentheses after the name of the layer, and certain layers (like C<:utf8>) are not real layers but instead flags on real layers; to get all of these returned separately, use the optional C<details> argument: my @layer_and_args_and_flags = PerlIO::get_layers($fh, details => 1); The result will be up to be three times the number of layers: the first element will be a name, the second element the arguments (unspecified arguments will be C<undef>), the third element the flags, the fourth element a name again, and so forth. B<You may open your eyes now.> =head1 AUTHOR Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt> =head1 SEE ALSO L<perlfunc/"binmode">, L<perlfunc/"open">, L<perlunicode>, L<perliol>, L<Encode> =cut	14.1 KB	2025-07-28 03:53
📄 SelectSaver.pm package SelectSaver; our $VERSION = '1.02'; =head1 NAME SelectSaver - save and restore selected file handle =head1 SYNOPSIS use SelectSaver; { my $saver = SelectSaver->new(FILEHANDLE); # FILEHANDLE is selected } # previous handle is selected { my $saver = SelectSaver->new; # new handle may be selected, or not } # previous handle is selected =head1 DESCRIPTION A C<SelectSaver> object contains a reference to the file handle that was selected when it was created. If its C<new> method gets an extra parameter, then that parameter is selected; otherwise, the selected file handle remains unchanged. When a C<SelectSaver> is destroyed, it re-selects the file handle that was selected when it was created. =cut require 5.000; use Carp; use Symbol; sub new { @_ >= 1 && @_ <= 2 or croak 'usage: SelectSaver->new( [FILEHANDLE] )'; my $fh = select; my $self = bless \$fh, $_[0]; select qualify($_[1], caller) if @_ > 1; $self; } sub DESTROY { my $self = $_[0]; select $$self; } 1;	1.05 KB	2025-07-28 03:54
📄 Symbol.pm package Symbol; =head1 NAME Symbol - manipulate Perl symbols and their names =head1 SYNOPSIS use Symbol; $sym = gensym; open($sym, '<', "filename"); $_ = <$sym>; # etc. ungensym $sym; # no effect # replace FOO{IO} handle but not $FOO, %FOO, etc. FOO = geniosym; print qualify("x"), "\n"; # "main::x" print qualify("x", "FOO"), "\n"; # "FOO::x" print qualify("BAR::x"), "\n"; # "BAR::x" print qualify("BAR::x", "FOO"), "\n"; # "BAR::x" print qualify("STDOUT", "FOO"), "\n"; # "main::STDOUT" (global) print qualify(\x), "\n"; # returns \x print qualify(\x, "FOO"), "\n"; # returns \x use strict refs; print { qualify_to_ref $fh } "foo!\n"; $ref = qualify_to_ref $name, $pkg; use Symbol qw(delete_package); delete_package('Foo::Bar'); print "deleted\n" unless exists $Foo::{'Bar::'}; =head1 DESCRIPTION C<Symbol::gensym> creates an anonymous glob and returns a reference to it. Such a glob reference can be used as a file or directory handle. For backward compatibility with older implementations that didn't support anonymous globs, C<Symbol::ungensym> is also provided. But it doesn't do anything. C<Symbol::geniosym> creates an anonymous IO handle. This can be assigned into an existing glob without affecting the non-IO portions of the glob. C<Symbol::qualify> turns unqualified symbol names into qualified variable names (e.g. "myvar" -E<gt> "MyPackage::myvar"). If it is given a second parameter, C<qualify> uses it as the default package; otherwise, it uses the package of its caller. Regardless, global variable names (e.g. "STDOUT", "ENV", "SIG") are always qualified with "main::". Qualification applies only to symbol names (strings). References are left unchanged under the assumption that they are glob references, which are qualified by their nature. C<Symbol::qualify_to_ref> is just like C<Symbol::qualify> except that it returns a glob ref rather than a symbol name, so you can use the result even if C<use strict 'refs'> is in effect. C<Symbol::delete_package> wipes out a whole package namespace. Note this routine is not exported by default--you may want to import it explicitly. =head1 BUGS C<Symbol::delete_package> is a bit too powerful. It undefines every symbol that lives in the specified package. Since perl, for performance reasons, does not perform a symbol table lookup each time a function is called or a global variable is accessed, some code that has already been loaded and that makes use of symbols in package C<Foo> may stop working after you delete C<Foo>, even if you reload the C<Foo> module afterwards. =cut BEGIN { require 5.005; } require Exporter; @ISA = qw(Exporter); @EXPORT = qw(gensym ungensym qualify qualify_to_ref); @EXPORT_OK = qw(delete_package geniosym); $VERSION = '1.08'; my $genpkg = "Symbol::"; my $genseq = 0; my %global = map {$_ => 1} qw(ARGV ARGVOUT ENV INC SIG STDERR STDIN STDOUT); # # Note that we never _copy_ the glob; we just make a ref to it. # If we did copy it, then SVf_FAKE would be set on the copy, and # glob-specific behaviors (e.g. C<$ref = \&func>) wouldn't work. # sub gensym () { my $name = "GEN" . $genseq++; my $ref = \{$genpkg . $name}; delete $$genpkg{$name}; $ref; } sub geniosym () { my $sym = gensym(); # force the IO slot to be filled select(select $sym); $sym{IO}; } sub ungensym ($) {} sub qualify ($;$) { my ($name) = @_; if (!ref($name) && index($name, '::') == -1 && index($name, "'") == -1) { my $pkg; # Global names: special character, "^xyz", or other. if ($name =~ /^(([^a-z])\|(\^[a-z_]+))\z/i \|\| $global{$name}) { # RGS 2001-11-05 : translate leading ^X to control-char $name =~ s/^\^([a-z_])/'qq(\c'.$1.')'/eei; $pkg = "main"; } else { $pkg = (@_ > 1) ? $_[1] : caller; } $name = $pkg . "::" . $name; } $name; } sub qualify_to_ref ($;$) { return \{ qualify $_[0], @_ > 1 ? $_[1] : caller }; } # # of Safe.pm lineage # sub delete_package ($) { my $pkg = shift; # expand to full symbol table name if needed unless ($pkg =~ /^main::.::$/) { $pkg = "main$pkg" if $pkg =~ /^::/; $pkg = "main::$pkg" unless $pkg =~ /^main::/; $pkg .= '::' unless $pkg =~ /::$/; } my($stem, $leaf) = $pkg =~ m/(.::)(\w+::)$/; my $stem_symtab = {$stem}{HASH}; return unless defined $stem_symtab and exists $stem_symtab->{$leaf}; # free all the symbols in the package my $leaf_symtab = {$stem_symtab->{$leaf}}{HASH}; foreach my $name (keys %$leaf_symtab) { undef *{$pkg . $name}; } # delete the symbol table %$leaf_symtab = (); delete $stem_symtab->{$leaf}; } 1;	4.69 KB	2025-07-28 03:54
📁 Tie	-	2026-03-21 15:44
📄 UNIVERSAL.pm package UNIVERSAL; our $VERSION = '1.13'; # UNIVERSAL should not contain any extra subs/methods beyond those # that it exists to define. The existence of import() below is a historical # accident that can't be fixed without breaking code. # Make sure that even though the import method is called, it doesn't do # anything unless called on UNIVERSAL. sub import { return unless $_[0] eq __PACKAGE__; return unless @_ > 1; require Carp; Carp::croak("UNIVERSAL does not export anything"); } 1; __END__ =head1 NAME UNIVERSAL - base class for ALL classes (blessed references) =head1 SYNOPSIS $is_io = $fd->isa("IO::Handle"); $is_io = Class->isa("IO::Handle"); $does_log = $obj->DOES("Logger"); $does_log = Class->DOES("Logger"); $sub = $obj->can("print"); $sub = Class->can("print"); $sub = eval { $ref->can("fandango") }; $ver = $obj->VERSION; # but never do this! $is_io = UNIVERSAL::isa($fd, "IO::Handle"); $sub = UNIVERSAL::can($obj, "print"); =head1 DESCRIPTION C<UNIVERSAL> is the base class from which all blessed references inherit. See L<perlobj>. C<UNIVERSAL> provides the following methods: =over 4 =item C<< $obj->isa( TYPE ) >> =item C<< CLASS->isa( TYPE ) >> =item C<< eval { VAL->isa( TYPE ) } >> Where =over 4 =item C<TYPE> is a package name =item C<$obj> is a blessed reference or a package name =item C<CLASS> is a package name =item C<VAL> is any of the above or an unblessed reference =back When used as an instance or class method (C<< $obj->isa( TYPE ) >>), C<isa> returns I<true> if $obj is blessed into package C<TYPE> or inherits from package C<TYPE>. When used as a class method (C<< CLASS->isa( TYPE ) >>, sometimes referred to as a static method), C<isa> returns I<true> if C<CLASS> inherits from (or is itself) the name of the package C<TYPE> or inherits from package C<TYPE>. If you're not sure what you have (the C<VAL> case), wrap the method call in an C<eval> block to catch the exception if C<VAL> is undefined. If you want to be sure that you're calling C<isa> as a method, not a class, check the invocand with C<blessed> from L<Scalar::Util> first: use Scalar::Util 'blessed'; if ( blessed( $obj ) && $obj->isa("Some::Class") ) { ... } =item C<< $obj->DOES( ROLE ) >> =item C<< CLASS->DOES( ROLE ) >> C<DOES> checks if the object or class performs the role C<ROLE>. A role is a named group of specific behavior (often methods of particular names and signatures), similar to a class, but not necessarily a complete class by itself. For example, logging or serialization may be roles. C<DOES> and C<isa> are similar, in that if either is true, you know that the object or class on which you call the method can perform specific behavior. However, C<DOES> is different from C<isa> in that it does not care I<how> the invocand performs the operations, merely that it does. (C<isa> of course mandates an inheritance relationship. Other relationships include aggregation, delegation, and mocking.) By default, classes in Perl only perform the C<UNIVERSAL> role, as well as the role of all classes in their inheritance. In other words, by default C<DOES> responds identically to C<isa>. There is a relationship between roles and classes, as each class implies the existence of a role of the same name. There is also a relationship between inheritance and roles, in that a subclass that inherits from an ancestor class implicitly performs any roles its parent performs. Thus you can use C<DOES> in place of C<isa> safely, as it will return true in all places where C<isa> will return true (provided that any overridden C<DOES> I<and> C<isa> methods behave appropriately). =item C<< $obj->can( METHOD ) >> =item C<< CLASS->can( METHOD ) >> =item C<< eval { VAL->can( METHOD ) } >> C<can> checks if the object or class has a method called C<METHOD>. If it does, then it returns a reference to the sub. If it does not, then it returns I<undef>. This includes methods inherited or imported by C<$obj>, C<CLASS>, or C<VAL>. C<can> cannot know whether an object will be able to provide a method through AUTOLOAD (unless the object's class has overridden C<can> appropriately), so a return value of I<undef> does not necessarily mean the object will not be able to handle the method call. To get around this some module authors use a forward declaration (see L<perlsub>) for methods they will handle via AUTOLOAD. For such 'dummy' subs, C<can> will still return a code reference, which, when called, will fall through to the AUTOLOAD. If no suitable AUTOLOAD is provided, calling the coderef will cause an error. You may call C<can> as a class (static) method or an object method. Again, the same rule about having a valid invocand applies -- use an C<eval> block or C<blessed> if you need to be extra paranoid. =item C<VERSION ( [ REQUIRE ] )> C<VERSION> will return the value of the variable C<$VERSION> in the package the object is blessed into. If C<REQUIRE> is given then it will do a comparison and die if the package version is not greater than or equal to C<REQUIRE>, or if either C<$VERSION> or C<REQUIRE> is not a "lax" version number (as defined by the L<version> module). The return from C<VERSION> will actually be the stringified version object using the package C<$VERSION> scalar, which is guaranteed to be equivalent but may not be precisely the contents of the C<$VERSION> scalar. If you want the actual contents of C<$VERSION>, use C<$CLASS::VERSION> instead. C<VERSION> can be called as either a class (static) method or an object method. =back =head1 WARNINGS B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and C<isa> uses a very similar method and cache-ing strategy. This may cause strange effects if the Perl code dynamically changes @ISA in any package. You may add other methods to the UNIVERSAL class via Perl or XS code. You do not need to C<use UNIVERSAL> to make these methods available to your program (and you should not do so). =head1 EXPORTS None. Previous versions of this documentation suggested using C<isa> as a function to determine the type of a reference: $yes = UNIVERSAL::isa($h, "HASH"); $yes = UNIVERSAL::isa("Foo", "Bar"); The problem is that this code would I<never> call an overridden C<isa> method in any class. Instead, use C<reftype> from L<Scalar::Util> for the first case: use Scalar::Util 'reftype'; $yes = reftype( $h ) eq "HASH"; and the method form of C<isa> for the second: $yes = Foo->isa("Bar"); =cut	6.44 KB	2025-07-28 03:53
📁 URI	-	2025-02-27 15:06
📄 URI.pm package URI; use strict; use warnings; our $VERSION = '5.09'; our ($ABS_REMOTE_LEADING_DOTS, $ABS_ALLOW_RELATIVE_SCHEME, $DEFAULT_QUERY_FORM_DELIMITER); my %implements; # mapping from scheme to implementor class # Some "official" character classes our $reserved = q(;/?:@&=+$,[]); our $mark = q(-_.!~'()); #'; emacs our $unreserved = "A-Za-z0-9\Q$mark\E"; our $uric = quotemeta($reserved) . $unreserved . "%"; our $scheme_re = '[a-zA-Z][a-zA-Z0-9.+\-]'; use Carp (); use URI::Escape (); use overload ('""' => sub { ${$_[0]} }, '==' => sub { _obj_eq(@_) }, '!=' => sub { !_obj_eq(@_) }, fallback => 1, ); # Check if two objects are the same object sub _obj_eq { return overload::StrVal($_[0]) eq overload::StrVal($_[1]); } sub new { my($class, $uri, $scheme) = @_; $uri = defined ($uri) ? "$uri" : ""; # stringify # Get rid of potential wrapping $uri =~ s/^<(?:URL:)?(.)>$/$1/; # $uri =~ s/^"(.)"$/$1/; $uri =~ s/^\s+//; $uri =~ s/\s+$//; my $impclass; if ($uri =~ m/^($scheme_re):/so) { $scheme = $1; } else { if (($impclass = ref($scheme))) { $scheme = $scheme->scheme; } elsif ($scheme && $scheme =~ m/^($scheme_re)(?::\|$)/o) { $scheme = $1; } } $impclass \|\|= implementor($scheme) \|\| do { require URI::_foreign; $impclass = 'URI::_foreign'; }; return $impclass->_init($uri, $scheme); } sub new_abs { my($class, $uri, $base) = @_; $uri = $class->new($uri, $base); $uri->abs($base); } sub _init { my $class = shift; my($str, $scheme) = @_; # find all funny characters and encode the bytes. $str = $class->_uric_escape($str); $str = "$scheme:$str" unless $str =~ /^$scheme_re:/o \|\| $class->_no_scheme_ok; my $self = bless \$str, $class; $self; } sub _uric_escape { my($class, $str) = @_; $str =~ s([^$uric\#]) URI::Escape::escape_char($1) ego; utf8::downgrade($str); return $str; } my %require_attempted; sub implementor { my($scheme, $impclass) = @_; if (!$scheme \|\| $scheme !~ /\A$scheme_re\z/o) { require URI::_generic; return "URI::_generic"; } $scheme = lc($scheme); if ($impclass) { # Set the implementor class for a given scheme my $old = $implements{$scheme}; $impclass->_init_implementor($scheme); $implements{$scheme} = $impclass; return $old; } my $ic = $implements{$scheme}; return $ic if $ic; # scheme not yet known, look for internal or # preloaded (with 'use') implementation $ic = "URI::$scheme"; # default location # turn scheme into a valid perl identifier by a simple transformation... $ic =~ s/\+/_P/g; $ic =~ s/\./_O/g; $ic =~ s/\-/_/g; no strict 'refs'; # check we actually have one for the scheme: unless (@{"${ic}::ISA"}) { if (not exists $require_attempted{$ic}) { # Try to load it my $_old_error = $@; eval "require $ic"; die $@ if $@ && $@ !~ /Can\'t locate.in \@INC/; $@ = $_old_error; } return undef unless @{"${ic}::ISA"}; } $ic->_init_implementor($scheme); $implements{$scheme} = $ic; $ic; } sub _init_implementor { my($class, $scheme) = @_; # Remember that one implementor class may actually # serve to implement several URI schemes. } sub clone { my $self = shift; my $other = $$self; bless \$other, ref $self; } sub TO_JSON { ${$_[0]} } sub _no_scheme_ok { 0 } sub _scheme { my $self = shift; unless (@_) { return undef unless $$self =~ /^($scheme_re):/o; return $1; } my $old; my $new = shift; if (defined($new) && length($new)) { Carp::croak("Bad scheme '$new'") unless $new =~ /^$scheme_re$/o; $old = $1 if $$self =~ s/^($scheme_re)://o; my $newself = URI->new("$new:$$self"); $$self = $$newself; bless $self, ref($newself); } else { if ($self->_no_scheme_ok) { $old = $1 if $$self =~ s/^($scheme_re)://o; Carp::carp("Oops, opaque part now look like scheme") if $^W && $$self =~ m/^$scheme_re:/o } else { $old = $1 if $$self =~ m/^($scheme_re):/o; } } return $old; } sub scheme { my $scheme = shift->_scheme(@_); return undef unless defined $scheme; lc($scheme); } sub has_recognized_scheme { my $self = shift; return ref($self) !~ /^URI::_(?:foreign\|generic)\z/; } sub opaque { my $self = shift; unless (@_) { $$self =~ /^(?:$scheme_re:)?([^\#])/o or die; return $1; } $$self =~ /^($scheme_re:)? # optional scheme ([^\#]) # opaque (\#.)? # optional fragment $/sx or die; my $old_scheme = $1; my $old_opaque = $2; my $old_frag = $3; my $new_opaque = shift; $new_opaque = "" unless defined $new_opaque; $new_opaque =~ s/([^$uric])/ URI::Escape::escape_char($1)/ego; utf8::downgrade($new_opaque); $$self = defined($old_scheme) ? $old_scheme : ""; $$self .= $new_opaque; $$self .= $old_frag if defined $old_frag; $old_opaque; } sub path { goto &opaque } # alias sub fragment { my $self = shift; unless (@_) { return undef unless $$self =~ /\#(.)/s; return $1; } my $old; $old = $1 if $$self =~ s/\#(.)//s; my $new_frag = shift; if (defined $new_frag) { $new_frag =~ s/([^$uric])/ URI::Escape::escape_char($1) /ego; utf8::downgrade($new_frag); $$self .= "#$new_frag"; } $old; } sub as_string { my $self = shift; $$self; } sub as_iri { my $self = shift; my $str = $$self; if ($str =~ s/%([89a-fA-F][0-9a-fA-F])/chr(hex($1))/eg) { # All this crap because the more obvious: # # Encode::decode("UTF-8", $str, sub { sprintf "%%%02X", shift }) # # doesn't work before Encode 2.39. Wait for a standard release # to bundle that version. require Encode; my $enc = Encode::find_encoding("UTF-8"); my $u = ""; while (length $str) { $u .= $enc->decode($str, Encode::FB_QUIET()); if (length $str) { # escape next char $u .= URI::Escape::escape_char(substr($str, 0, 1, "")); } } $str = $u; } return $str; } sub canonical { # Make sure scheme is lowercased, that we don't escape unreserved chars, # and that we use upcase escape sequences. my $self = shift; my $scheme = $self->_scheme \|\| ""; my $uc_scheme = $scheme =~ /[A-Z]/; my $esc = $$self =~ /%[a-fA-F0-9]{2}/; return $self unless $uc_scheme \|\| $esc; my $other = $self->clone; if ($uc_scheme) { $other->_scheme(lc $scheme); } if ($esc) { $$other =~ s{%([0-9a-fA-F]{2})} { my $a = chr(hex($1)); $a =~ /^[$unreserved]\z/o ? $a : "%\U$1" }ge; } return $other; } # Compare two URIs, subclasses will provide a more correct implementation sub eq { my($self, $other) = @_; $self = URI->new($self, $other) unless ref $self; $other = URI->new($other, $self) unless ref $other; ref($self) eq ref($other) && # same class $self->canonical->as_string eq $other->canonical->as_string; } # generic-URI transformation methods sub abs { $_[0]; } sub rel { $_[0]; } sub secure { 0 } # help out Storable sub STORABLE_freeze { my($self, $cloning) = @_; return $$self; } sub STORABLE_thaw { my($self, $cloning, $str) = @_; $$self = $str; } 1; __END__ =head1 NAME URI - Uniform Resource Identifiers (absolute and relative) =head1 SYNOPSIS use URI (); $u1 = URI->new("http://www.example.com"); $u2 = URI->new("foo", "http"); $u3 = $u2->abs($u1); $u4 = $u3->clone; $u5 = URI->new("HTTP://WWW.example.com:80")->canonical; $str = $u->as_string; $str = "$u"; $scheme = $u->scheme; $opaque = $u->opaque; $path = $u->path; $frag = $u->fragment; $u->scheme("ftp"); $u->host("ftp.example.com"); $u->path("cpan/"); =head1 DESCRIPTION This module implements the C<URI> class. Objects of this class represent "Uniform Resource Identifier references" as specified in RFC 2396 (and updated by RFC 2732). A Uniform Resource Identifier is a compact string of characters that identifies an abstract or physical resource. A Uniform Resource Identifier can be further classified as either a Uniform Resource Locator (URL) or a Uniform Resource Name (URN). The distinction between URL and URN does not matter to the C<URI> class interface. A "URI-reference" is a URI that may have additional information attached in the form of a fragment identifier. An absolute URI reference consists of three parts: a I<scheme>, a I<scheme-specific part> and a I<fragment> identifier. A subset of URI references share a common syntax for hierarchical namespaces. For these, the scheme-specific part is further broken down into I<authority>, I<path> and I<query> components. These URIs can also take the form of relative URI references, where the scheme (and usually also the authority) component is missing, but implied by the context of the URI reference. The three forms of URI reference syntax are summarized as follows: <scheme>:<scheme-specific-part>#<fragment> <scheme>://<authority><path>?<query>#<fragment> <path>?<query>#<fragment> The components into which a URI reference can be divided depend on the I<scheme>. The C<URI> class provides methods to get and set the individual components. The methods available for a specific C<URI> object depend on the scheme. =head1 CONSTRUCTORS The following methods construct new C<URI> objects: =over 4 =item $uri = URI->new( $str ) =item $uri = URI->new( $str, $scheme ) Constructs a new URI object. The string representation of a URI is given as argument, together with an optional scheme specification. Common URI wrappers like "" and <>, as well as leading and trailing white space, are automatically removed from the $str argument before it is processed further. The constructor determines the scheme, maps this to an appropriate URI subclass, constructs a new object of that class and returns it. If the scheme isn't one of those that URI recognizes, you still get an URI object back that you can access the generic methods on. The C<< $uri->has_recognized_scheme >> method can be used to test for this. The $scheme argument is only used when $str is a relative URI. It can be either a simple string that denotes the scheme, a string containing an absolute URI reference, or an absolute C<URI> object. If no $scheme is specified for a relative URI $str, then $str is simply treated as a generic URI (no scheme-specific methods available). The set of characters available for building URI references is restricted (see L<URI::Escape>). Characters outside this set are automatically escaped by the URI constructor. =item $uri = URI->new_abs( $str, $base_uri ) Constructs a new absolute URI object. The $str argument can denote a relative or absolute URI. If relative, then it is absolutized using $base_uri as base. The $base_uri must be an absolute URI. =item $uri = URI::file->new( $filename ) =item $uri = URI::file->new( $filename, $os ) Constructs a new I<file> URI from a file name. See L<URI::file>. =item $uri = URI::file->new_abs( $filename ) =item $uri = URI::file->new_abs( $filename, $os ) Constructs a new absolute I<file> URI from a file name. See L<URI::file>. =item $uri = URI::file->cwd Returns the current working directory as a I<file> URI. See L<URI::file>. =item $uri->clone Returns a copy of the $uri. =back =head1 COMMON METHODS The methods described in this section are available for all C<URI> objects. Methods that give access to components of a URI always return the old value of the component. The value returned is C<undef> if the component was not present. There is generally a difference between a component that is empty (represented as C<"">) and a component that is missing (represented as C<undef>). If an accessor method is given an argument, it updates the corresponding component in addition to returning the old value of the component. Passing an undefined argument removes the component (if possible). The description of each accessor method indicates whether the component is passed as an escaped (percent-encoded) or an unescaped string. A component that can be further divided into sub-parts are usually passed escaped, as unescaping might change its semantics. The common methods available for all URI are: =over 4 =item $uri->scheme =item $uri->scheme( $new_scheme ) Sets and returns the scheme part of the $uri. If the $uri is relative, then $uri->scheme returns C<undef>. If called with an argument, it updates the scheme of $uri, possibly changing the class of $uri, and returns the old scheme value. The method croaks if the new scheme name is illegal; a scheme name must begin with a letter and must consist of only US-ASCII letters, numbers, and a few special marks: ".", "+", "-". This restriction effectively means that the scheme must be passed unescaped. Passing an undefined argument to the scheme method makes the URI relative (if possible). Letter case does not matter for scheme names. The string returned by $uri->scheme is always lowercase. If you want the scheme just as it was written in the URI in its original case, you can use the $uri->_scheme method instead. =item $uri->has_recognized_scheme Returns TRUE if the URI scheme is one that URI recognizes. It will also be TRUE for relative URLs where a recognized scheme was provided to the constructor, even if C<< $uri->scheme >> returns C<undef> for these. =item $uri->opaque =item $uri->opaque( $new_opaque ) Sets and returns the scheme-specific part of the $uri (everything between the scheme and the fragment) as an escaped string. =item $uri->path =item $uri->path( $new_path ) Sets and returns the same value as $uri->opaque unless the URI supports the generic syntax for hierarchical namespaces. In that case the generic method is overridden to set and return the part of the URI between the I<host name> and the I<fragment>. =item $uri->fragment =item $uri->fragment( $new_frag ) Returns the fragment identifier of a URI reference as an escaped string. =item $uri->as_string Returns a URI object to a plain ASCII string. URI objects are also converted to plain strings automatically by overloading. This means that $uri objects can be used as plain strings in most Perl constructs. =item $uri->as_iri Returns a Unicode string representing the URI. Escaped UTF-8 sequences representing non-ASCII characters are turned into their corresponding Unicode code point. =item $uri->canonical Returns a normalized version of the URI. The rules for normalization are scheme-dependent. They usually involve lowercasing the scheme and Internet host name components, removing the explicit port specification if it matches the default port, uppercasing all escape sequences, and unescaping octets that can be better represented as plain characters. For efficiency reasons, if the $uri is already in normalized form, then a reference to it is returned instead of a copy. =item $uri->eq( $other_uri ) =item URI::eq( $first_uri, $other_uri ) Tests whether two URI references are equal. URI references that normalize to the same string are considered equal. The method can also be used as a plain function which can also test two string arguments. If you need to test whether two C<URI> object references denote the same object, use the '==' operator. =item $uri->abs( $base_uri ) Returns an absolute URI reference. If $uri is already absolute, then a reference to it is simply returned. If the $uri is relative, then a new absolute URI is constructed by combining the $uri and the $base_uri, and returned. =item $uri->rel( $base_uri ) Returns a relative URI reference if it is possible to make one that denotes the same resource relative to $base_uri. If not, then $uri is simply returned. =item $uri->secure Returns a TRUE value if the URI is considered to point to a resource on a secure channel, such as an SSL or TLS encrypted one. =back =head1 GENERIC METHODS The following methods are available to schemes that use the common/generic syntax for hierarchical namespaces. The descriptions of schemes below indicate which these are. Unrecognized schemes are assumed to support the generic syntax, and therefore the following methods: =over 4 =item $uri->authority =item $uri->authority( $new_authority ) Sets and returns the escaped authority component of the $uri. =item $uri->path =item $uri->path( $new_path ) Sets and returns the escaped path component of the $uri (the part between the host name and the query or fragment). The path can never be undefined, but it can be the empty string. =item $uri->path_query =item $uri->path_query( $new_path_query ) Sets and returns the escaped path and query components as a single entity. The path and the query are separated by a "?" character, but the query can itself contain "?". =item $uri->path_segments =item $uri->path_segments( $segment, ... ) Sets and returns the path. In a scalar context, it returns the same value as $uri->path. In a list context, it returns the unescaped path segments that make up the path. Path segments that have parameters are returned as an anonymous array. The first element is the unescaped path segment proper; subsequent elements are escaped parameter strings. Such an anonymous array uses overloading so it can be treated as a string too, but this string does not include the parameters. Note that absolute paths have the empty string as their first I<path_segment>, i.e. the I<path> C</foo/bar> have 3 I<path_segments>; "", "foo" and "bar". =item $uri->query =item $uri->query( $new_query ) Sets and returns the escaped query component of the $uri. =item $uri->query_form =item $uri->query_form( $key1 => $val1, $key2 => $val2, ... ) =item $uri->query_form( $key1 => $val1, $key2 => $val2, ..., $delim ) =item $uri->query_form( \@key_value_pairs ) =item $uri->query_form( \@key_value_pairs, $delim ) =item $uri->query_form( \%hash ) =item $uri->query_form( \%hash, $delim ) Sets and returns query components that use the I<application/x-www-form-urlencoded> format. Key/value pairs are separated by "&", and the key is separated from the value by a "=" character. The form can be set either by passing separate key/value pairs, or via an array or hash reference. Passing an empty array or an empty hash removes the query component, whereas passing no arguments at all leaves the component unchanged. The order of keys is undefined if a hash reference is passed. The old value is always returned as a list of separate key/value pairs. Assigning this list to a hash is unwise as the keys returned might repeat. The values passed when setting the form can be plain strings or references to arrays of strings. Passing an array of values has the same effect as passing the key repeatedly with one value at a time. All the following statements have the same effect: $uri->query_form(foo => 1, foo => 2); $uri->query_form(foo => [1, 2]); $uri->query_form([ foo => 1, foo => 2 ]); $uri->query_form([ foo => [1, 2] ]); $uri->query_form({ foo => [1, 2] }); The $delim parameter can be passed as ";" to force the key/value pairs to be delimited by ";" instead of "&" in the query string. This practice is often recommended for URLs embedded in HTML or XML documents as this avoids the trouble of escaping the "&" character. You might also set the $URI::DEFAULT_QUERY_FORM_DELIMITER variable to ";" for the same global effect. The C<URI::QueryParam> module can be loaded to add further methods to manipulate the form of a URI. See L<URI::QueryParam> for details. =item $uri->query_keywords =item $uri->query_keywords( $keywords, ... ) =item $uri->query_keywords( \@keywords ) Sets and returns query components that use the keywords separated by "+" format. The keywords can be set either by passing separate keywords directly or by passing a reference to an array of keywords. Passing an empty array removes the query component, whereas passing no arguments at all leaves the component unchanged. The old value is always returned as a list of separate words. =back =head1 SERVER METHODS For schemes where the I<authority> component denotes an Internet host, the following methods are available in addition to the generic methods. =over 4 =item $uri->userinfo =item $uri->userinfo( $new_userinfo ) Sets and returns the escaped userinfo part of the authority component. For some schemes this is a user name and a password separated by a colon. This practice is not recommended. Embedding passwords in clear text (such as URI) has proven to be a security risk in almost every case where it has been used. =item $uri->host =item $uri->host( $new_host ) Sets and returns the unescaped hostname. If the $new_host string ends with a colon and a number, then this number also sets the port. For IPv6 addresses the brackets around the raw address is removed in the return value from $uri->host. When setting the host attribute to an IPv6 address you can use a raw address or one enclosed in brackets. The address needs to be enclosed in brackets if you want to pass in a new port value as well. =item $uri->ihost Returns the host in Unicode form. Any IDNA A-labels are turned into U-labels. =item $uri->port =item $uri->port( $new_port ) Sets and returns the port. The port is a simple integer that should be greater than 0. If a port is not specified explicitly in the URI, then the URI scheme's default port is returned. If you don't want the default port substituted, then you can use the $uri->_port method instead. =item $uri->host_port =item $uri->host_port( $new_host_port ) Sets and returns the host and port as a single unit. The returned value includes a port, even if it matches the default port. The host part and the port part are separated by a colon: ":". For IPv6 addresses the bracketing is preserved; thus URI->new("http://[::1]/")->host_port returns "[::1]:80". Contrast this with $uri->host which will remove the brackets. =item $uri->default_port Returns the default port of the URI scheme to which $uri belongs. For I<http> this is the number 80, for I<ftp> this is the number 21, etc. The default port for a scheme can not be changed. =back =head1 SCHEME-SPECIFIC SUPPORT Scheme-specific support is provided for the following URI schemes. For C<URI> objects that do not belong to one of these, you can only use the common and generic methods. =over 4 =item B<data>: The I<data> URI scheme is specified in RFC 2397. It allows inclusion of small data items as "immediate" data, as if it had been included externally. C<URI> objects belonging to the data scheme support the common methods and two new methods to access their scheme-specific components: $uri->media_type and $uri->data. See L<URI::data> for details. =item B<file>: An old specification of the I<file> URI scheme is found in RFC 1738. A new RFC 2396 based specification in not available yet, but file URI references are in common use. C<URI> objects belonging to the file scheme support the common and generic methods. In addition, they provide two methods for mapping file URIs back to local file names; $uri->file and $uri->dir. See L<URI::file> for details. =item B<ftp>: An old specification of the I<ftp> URI scheme is found in RFC 1738. A new RFC 2396 based specification in not available yet, but ftp URI references are in common use. C<URI> objects belonging to the ftp scheme support the common, generic and server methods. In addition, they provide two methods for accessing the userinfo sub-components: $uri->user and $uri->password. =item B<gopher>: The I<gopher> URI scheme is specified in <draft-murali-url-gopher-1996-12-04> and will hopefully be available as a RFC 2396 based specification. C<URI> objects belonging to the gopher scheme support the common, generic and server methods. In addition, they support some methods for accessing gopher-specific path components: $uri->gopher_type, $uri->selector, $uri->search, $uri->string. =item B<http>: The I<http> URI scheme is specified in RFC 2616. The scheme is used to reference resources hosted by HTTP servers. C<URI> objects belonging to the http scheme support the common, generic and server methods. =item B<https>: The I<https> URI scheme is a Netscape invention which is commonly implemented. The scheme is used to reference HTTP servers through SSL connections. Its syntax is the same as http, but the default port is different. =item B<ldap>: The I<ldap> URI scheme is specified in RFC 2255. LDAP is the Lightweight Directory Access Protocol. An ldap URI describes an LDAP search operation to perform to retrieve information from an LDAP directory. C<URI> objects belonging to the ldap scheme support the common, generic and server methods as well as ldap-specific methods: $uri->dn, $uri->attributes, $uri->scope, $uri->filter, $uri->extensions. See L<URI::ldap> for details. =item B<ldapi>: Like the I<ldap> URI scheme, but uses a UNIX domain socket. The server methods are not supported, and the local socket path is available as $uri->un_path. The I<ldapi> scheme is used by the OpenLDAP package. There is no real specification for it, but it is mentioned in various OpenLDAP manual pages. =item B<ldaps>: Like the I<ldap> URI scheme, but uses an SSL connection. This scheme is deprecated, as the preferred way is to use the I<start_tls> mechanism. =item B<mailto>: The I<mailto> URI scheme is specified in RFC 2368. The scheme was originally used to designate the Internet mailing address of an individual or service. It has (in RFC 2368) been extended to allow setting of other mail header fields and the message body. C<URI> objects belonging to the mailto scheme support the common methods and the generic query methods. In addition, they support the following mailto-specific methods: $uri->to, $uri->headers. Note that the "foo@example.com" part of a mailto is I<not> the C<userinfo> and C<host> but instead the C<path>. This allows a mailto URI to contain multiple comma separated email addresses. =item B<mms>: The I<mms> URL specification can be found at L<http://sdp.ppona.com/>. C<URI> objects belonging to the mms scheme support the common, generic, and server methods, with the exception of userinfo and query-related sub-components. =item B<news>: The I<news>, I<nntp> and I<snews> URI schemes are specified in <draft-gilman-news-url-01> and will hopefully be available as an RFC 2396 based specification soon. (Update: as of April 2010, they are in L<RFC 5538\|https://tools.ietf.org/html/rfc5538>. C<URI> objects belonging to the news scheme support the common, generic and server methods. In addition, they provide some methods to access the path: $uri->group and $uri->message. =item B<nntp>: See I<news> scheme. =item B<nntps>: See I<news> scheme and L<RFC 5538\|https://tools.ietf.org/html/rfc5538>. =item B<pop>: The I<pop> URI scheme is specified in RFC 2384. The scheme is used to reference a POP3 mailbox. C<URI> objects belonging to the pop scheme support the common, generic and server methods. In addition, they provide two methods to access the userinfo components: $uri->user and $uri->auth =item B<rlogin>: An old specification of the I<rlogin> URI scheme is found in RFC 1738. C<URI> objects belonging to the rlogin scheme support the common, generic and server methods. =item B<rtsp>: The I<rtsp> URL specification can be found in section 3.2 of RFC 2326. C<URI> objects belonging to the rtsp scheme support the common, generic, and server methods, with the exception of userinfo and query-related sub-components. =item B<rtspu>: The I<rtspu> URI scheme is used to talk to RTSP servers over UDP instead of TCP. The syntax is the same as rtsp. =item B<rsync>: Information about rsync is available from L<http://rsync.samba.org/>. C<URI> objects belonging to the rsync scheme support the common, generic and server methods. In addition, they provide methods to access the userinfo sub-components: $uri->user and $uri->password. =item B<sip>: The I<sip> URI specification is described in sections 19.1 and 25 of RFC 3261. C<URI> objects belonging to the sip scheme support the common, generic, and server methods with the exception of path related sub-components. In addition, they provide two methods to get and set I<sip> parameters: $uri->params_form and $uri->params. =item B<sips>: See I<sip> scheme. Its syntax is the same as sip, but the default port is different. =item B<snews>: See I<news> scheme. Its syntax is the same as news, but the default port is different. =item B<telnet>: An old specification of the I<telnet> URI scheme is found in RFC 1738. C<URI> objects belonging to the telnet scheme support the common, generic and server methods. =item B<tn3270>: These URIs are used like I<telnet> URIs but for connections to IBM mainframes. C<URI> objects belonging to the tn3270 scheme support the common, generic and server methods. =item B<ssh>: Information about ssh is available at L<http://www.openssh.com/>. C<URI> objects belonging to the ssh scheme support the common, generic and server methods. In addition, they provide methods to access the userinfo sub-components: $uri->user and $uri->password. =item B<sftp>: C<URI> objects belonging to the sftp scheme support the common, generic and server methods. In addition, they provide methods to access the userinfo sub-components: $uri->user and $uri->password. =item B<urn>: The syntax of Uniform Resource Names is specified in RFC 2141. C<URI> objects belonging to the urn scheme provide the common methods, and also the methods $uri->nid and $uri->nss, which return the Namespace Identifier and the Namespace-Specific String respectively. The Namespace Identifier basically works like the Scheme identifier of URIs, and further divides the URN namespace. Namespace Identifier assignments are maintained at L<http://www.iana.org/assignments/urn-namespaces>. Letter case is not significant for the Namespace Identifier. It is always returned in lower case by the $uri->nid method. The $uri->_nid method can be used if you want it in its original case. =item B<urn>:B<isbn>: The C<urn:isbn:> namespace contains International Standard Book Numbers (ISBNs) and is described in RFC 3187. A C<URI> object belonging to this namespace has the following extra methods (if the Business::ISBN module is available): $uri->isbn, $uri->isbn_publisher_code, $uri->isbn_group_code (formerly isbn_country_code, which is still supported by issues a deprecation warning), $uri->isbn_as_ean. =item B<urn>:B<oid>: The C<urn:oid:> namespace contains Object Identifiers (OIDs) and is described in RFC 3061. An object identifier consists of sequences of digits separated by dots. A C<URI> object belonging to this namespace has an additional method called $uri->oid that can be used to get/set the oid value. In a list context, oid numbers are returned as separate elements. =back =head1 CONFIGURATION VARIABLES The following configuration variables influence how the class and its methods behave: =over 4 =item $URI::ABS_ALLOW_RELATIVE_SCHEME Some older parsers used to allow the scheme name to be present in the relative URL if it was the same as the base URL scheme. RFC 2396 says that this should be avoided, but you can enable this old behaviour by setting the $URI::ABS_ALLOW_RELATIVE_SCHEME variable to a TRUE value. The difference is demonstrated by the following examples: URI->new("http:foo")->abs("http://host/a/b") ==> "http:foo" local $URI::ABS_ALLOW_RELATIVE_SCHEME = 1; URI->new("http:foo")->abs("http://host/a/b") ==> "http:/host/a/foo" =item $URI::ABS_REMOTE_LEADING_DOTS You can also have the abs() method ignore excess ".." segments in the relative URI by setting $URI::ABS_REMOTE_LEADING_DOTS to a TRUE value. The difference is demonstrated by the following examples: URI->new("../../../foo")->abs("http://host/a/b") ==> "http://host/../../foo" local $URI::ABS_REMOTE_LEADING_DOTS = 1; URI->new("../../../foo")->abs("http://host/a/b") ==> "http://host/foo" =item $URI::DEFAULT_QUERY_FORM_DELIMITER This value can be set to ";" to have the query form C<key=value> pairs delimited by ";" instead of "&" which is the default. =back =head1 BUGS There are some things that are not quite right: =over =item Using regexp variables like $1 directly as arguments to the URI accessor methods does not work too well with current perl implementations. I would argue that this is actually a bug in perl. The workaround is to quote them. Example: /(...)/ \|\| die; $u->query("$1"); =item * The escaping (percent encoding) of chars in the 128 .. 255 range passed to the URI constructor or when setting URI parts using the accessor methods depend on the state of the internal UTF8 flag (see utf8::is_utf8) of the string passed. If the UTF8 flag is set the UTF-8 encoded version of the character is percent encoded. If the UTF8 flag isn't set the Latin-1 version (byte) of the character is percent encoded. This basically exposes the internal encoding of Perl strings. =back =head1 PARSING URIs WITH REGEXP As an alternative to this module, the following (official) regular expression can be used to decode a URI: my($scheme, $authority, $path, $query, $fragment) = $uri =~ m\|(?:([^:/?#]+):)?(?://([^/?#]))?([^?#])(?:\?([^#]))?(?:#(.))?\|; The C<URI::Split> module provides the function uri_split() as a readable alternative. =head1 SEE ALSO L<URI::file>, L<URI::WithBase>, L<URI::QueryParam>, L<URI::Escape>, L<URI::Split>, L<URI::Heuristic> RFC 2396: "Uniform Resource Identifiers (URI): Generic Syntax", Berners-Lee, Fielding, Masinter, August 1998. L<http://www.iana.org/assignments/uri-schemes> L<http://www.iana.org/assignments/urn-namespaces> L<http://www.w3.org/Addressing/> =head1 COPYRIGHT Copyright 1995-2009 Gisle Aas. Copyright 1995 Martijn Koster. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 AUTHORS / ACKNOWLEDGMENTS This module is based on the C<URI::URL> module, which in turn was (distantly) based on the C<wwwurl.pl> code in the libwww-perl for perl4 developed by Roy Fielding, as part of the Arcadia project at the University of California, Irvine, with contributions from Brooks Cutter. C<URI::URL> was developed by Gisle Aas, Tim Bunce, Roy Fielding and Martijn Koster with input from other people on the libwww-perl mailing list. C<URI> and related subclasses was developed by Gisle Aas. =cut	34.13 KB	2021-03-03 15:16
📄 XSLoader.pm # Generated from XSLoader_pm.PL (resolved %Config::Config value) # This file is unique for every OS package XSLoader; $VERSION = "0.30"; # remember to update version in POD! #use strict; package DynaLoader; # No prizes for guessing why we don't say 'bootstrap DynaLoader;' here. # NOTE: All dl_.xs (including dl_none.xs) define a dl_error() XSUB boot_DynaLoader('DynaLoader') if defined(&boot_DynaLoader) && !defined(&dl_error); package XSLoader; sub load { package DynaLoader; my ($caller, $modlibname) = caller(); my $module = $caller; if (@_) { $module = $_[0]; } else { $_[0] = $module; } # work with static linking too my $boots = "$module\::bootstrap"; goto &$boots if defined &$boots; goto \&XSLoader::bootstrap_inherit unless $module and defined &dl_load_file; my @modparts = split(/::/,$module); my $modfname = $modparts[-1]; my $modfname_orig = $modfname; # For .bs file search my $modpname = join('/',@modparts); my $c = () = split(/::/,$caller,-1); $modlibname =~ s,[\\/][^\\/]+$,, while $c--; # Q&D basename # Does this look like a relative path? if ($modlibname !~ m{^/}) { # Someone may have a #line directive that changes the file name, or # may be calling XSLoader::load from inside a string eval. We cer- # tainly do not want to go loading some code that is not in @INC, # as it could be untrusted. # # We could just fall back to DynaLoader here, but then the rest of # this function would go untested in the perl core, since all @INC # paths are relative during testing. That would be a time bomb # waiting to happen, since bugs could be introduced into the code. # # So look through @INC to see if $modlibname is in it. A rela- # tive $modlibname is not a common occurrence, so this block is # not hot code. FOUND: { for (@INC) { if ($_ eq $modlibname) { last FOUND; } } # Not found. Fall back to DynaLoader. goto \&XSLoader::bootstrap_inherit; } } my $file = "$modlibname/auto/$modpname/$modfname.so"; # print STDERR "XSLoader::load for $module ($file)\n" if $dl_debug; # N.B. The .bs file does not following the naming convention used # by mod2fname, so use the unedited version of the name. my $bs = "$modlibname/auto/$modpname/$modfname_orig.bs"; # This calls DynaLoader::bootstrap, which will load the .bs file if present goto \&XSLoader::bootstrap_inherit if not -f $file or -s $bs; my $bootname = "boot_$module"; $bootname =~ s/\W/_/g; @DynaLoader::dl_require_symbols = ($bootname); my $boot_symbol_ref; # Many dynamic extension loading problems will appear to come from # this section of code: XYZ failed at line 123 of DynaLoader.pm. # Often these errors are actually occurring in the initialisation # C code of the extension XS file. Perl reports the error as being # in this perl code simply because this was the last perl code # it executed. my $libref = dl_load_file($file, 0) or do { require Carp; Carp::croak("Can't load '$file' for module $module: " . dl_error()); }; push(@DynaLoader::dl_librefs,$libref); # record loaded object $boot_symbol_ref = dl_find_symbol($libref, $bootname) or do { require Carp; Carp::croak("Can't find '$bootname' symbol in $file\n"); }; push(@DynaLoader::dl_modules, $module); # record loaded module boot: my $xs = dl_install_xsub($boots, $boot_symbol_ref, $file); # See comment block above push(@DynaLoader::dl_shared_objects, $file); # record files loaded return &$xs(@_); } sub bootstrap_inherit { require DynaLoader; goto \&DynaLoader::bootstrap_inherit; } 1; __END__ =head1 NAME XSLoader - Dynamically load C libraries into Perl code =head1 VERSION Version 0.30 =head1 SYNOPSIS package YourPackage; require XSLoader; XSLoader::load(__PACKAGE__, $VERSION); =head1 DESCRIPTION This module defines a standard I<simplified> interface to the dynamic linking mechanisms available on many platforms. Its primary purpose is to implement cheap automatic dynamic loading of Perl modules. For a more complicated interface, see L<DynaLoader>. Many (most) features of C<DynaLoader> are not implemented in C<XSLoader>, like for example the C<dl_load_flags>, not honored by C<XSLoader>. =head2 Migration from C<DynaLoader> A typical module using L<DynaLoader\|DynaLoader> starts like this: package YourPackage; require DynaLoader; our @ISA = qw( OnePackage OtherPackage DynaLoader ); our $VERSION = '0.01'; __PACKAGE__->bootstrap($VERSION); Change this to package YourPackage; use XSLoader; our @ISA = qw( OnePackage OtherPackage ); our $VERSION = '0.01'; XSLoader::load(__PACKAGE__, $VERSION); In other words: replace C<require DynaLoader> by C<use XSLoader>, remove C<DynaLoader> from C<@ISA>, change C<bootstrap> by C<XSLoader::load>. Do not forget to quote the name of your package on the C<XSLoader::load> line, and add comma (C<,>) before the arguments (C<$VERSION> above). Of course, if C<@ISA> contained only C<DynaLoader>, there is no need to have the C<@ISA> assignment at all; moreover, if instead of C<our> one uses the more backward-compatible use vars qw($VERSION @ISA); one can remove this reference to C<@ISA> together with the C<@ISA> assignment. If no C<$VERSION> was specified on the C<bootstrap> line, the last line becomes XSLoader::load(__PACKAGE__); in which case it can be further simplified to XSLoader::load(); as C<load> will use C<caller> to determine the package. =head2 Backward compatible boilerplate If you want to have your cake and eat it too, you need a more complicated boilerplate. package YourPackage; our @ISA = qw( OnePackage OtherPackage ); our $VERSION = '0.01'; eval { require XSLoader; XSLoader::load(__PACKAGE__, $VERSION); 1; } or do { require DynaLoader; push @ISA, 'DynaLoader'; __PACKAGE__->bootstrap($VERSION); }; The parentheses about C<XSLoader::load()> arguments are needed since we replaced C<use XSLoader> by C<require>, so the compiler does not know that a function C<XSLoader::load()> is present. This boilerplate uses the low-overhead C<XSLoader> if present; if used with an antique Perl which has no C<XSLoader>, it falls back to using C<DynaLoader>. =head1 Order of initialization: early load() I<Skip this section if the XSUB functions are supposed to be called from other modules only; read it only if you call your XSUBs from the code in your module, or have a C<BOOT:> section in your XS file (see L<perlxs/"The BOOT: Keyword">). What is described here is equally applicable to the L<DynaLoader\|DynaLoader> interface.> A sufficiently complicated module using XS would have both Perl code (defined in F<YourPackage.pm>) and XS code (defined in F<YourPackage.xs>). If this Perl code makes calls into this XS code, and/or this XS code makes calls to the Perl code, one should be careful with the order of initialization. The call to C<XSLoader::load()> (or C<bootstrap()>) calls the module's bootstrap code. For modules build by F<xsubpp> (nearly all modules) this has three side effects: =over =item A sanity check is done to ensure that the versions of the F<.pm> and the (compiled) F<.xs> parts are compatible. If C<$VERSION> was specified, this is used for the check. If not specified, it defaults to C<$XS_VERSION // $VERSION> (in the module's namespace) =item * the XSUBs are made accessible from Perl =item * if a C<BOOT:> section was present in the F<.xs> file, the code there is called. =back Consequently, if the code in the F<.pm> file makes calls to these XSUBs, it is convenient to have XSUBs installed before the Perl code is defined; for example, this makes prototypes for XSUBs visible to this Perl code. Alternatively, if the C<BOOT:> section makes calls to Perl functions (or uses Perl variables) defined in the F<.pm> file, they must be defined prior to the call to C<XSLoader::load()> (or C<bootstrap()>). The first situation being much more frequent, it makes sense to rewrite the boilerplate as package YourPackage; use XSLoader; our ($VERSION, @ISA); BEGIN { @ISA = qw( OnePackage OtherPackage ); $VERSION = '0.01'; # Put Perl code used in the BOOT: section here XSLoader::load(__PACKAGE__, $VERSION); } # Put Perl code making calls into XSUBs here =head2 The most hairy case If the interdependence of your C<BOOT:> section and Perl code is more complicated than this (e.g., the C<BOOT:> section makes calls to Perl functions which make calls to XSUBs with prototypes), get rid of the C<BOOT:> section altogether. Replace it with a function C<onBOOT()>, and call it like this: package YourPackage; use XSLoader; our ($VERSION, @ISA); BEGIN { @ISA = qw( OnePackage OtherPackage ); $VERSION = '0.01'; XSLoader::load(__PACKAGE__, $VERSION); } # Put Perl code used in onBOOT() function here; calls to XSUBs are # prototype-checked. onBOOT; # Put Perl initialization code assuming that XS is initialized here =head1 DIAGNOSTICS =over =item C<Can't find '%s' symbol in %s> B<(F)> The bootstrap symbol could not be found in the extension module. =item C<Can't load '%s' for module %s: %s> B<(F)> The loading or initialisation of the extension module failed. The detailed error follows. =item C<Undefined symbols present after loading %s: %s> B<(W)> As the message says, some symbols stay undefined although the extension module was correctly loaded and initialised. The list of undefined symbols follows. =back =head1 LIMITATIONS To reduce the overhead as much as possible, only one possible location is checked to find the extension DLL (this location is where C<make install> would put the DLL). If not found, the search for the DLL is transparently delegated to C<DynaLoader>, which looks for the DLL along the C<@INC> list. In particular, this is applicable to the structure of C<@INC> used for testing not-yet-installed extensions. This means that running uninstalled extensions may have much more overhead than running the same extensions after C<make install>. =head1 KNOWN BUGS The new simpler way to call C<XSLoader::load()> with no arguments at all does not work on Perl 5.8.4 and 5.8.5. =head1 BUGS Please report any bugs or feature requests via the perlbug(1) utility. =head1 SEE ALSO L<DynaLoader> =head1 AUTHORS Ilya Zakharevich originally extracted C<XSLoader> from C<DynaLoader>. CPAN version is currently maintained by SE<eacute>bastien Aperghis-Tramoni E<lt>sebastien@aperghis.netE<gt>. Previous maintainer was Michael G Schwern <schwern@pobox.com>. =head1 COPYRIGHT & LICENSE Copyright (C) 1990-2011 by Larry Wall and others. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut	10.99 KB	2025-07-28 03:53
📄 _charnames.pm # !!!!!!! INTERNAL PERL USE ONLY !!!!!!! # This helper module is for internal use by core Perl only. This module is # subject to change or removal at any time without notice. Don't use it # directly. Use the public <charnames> module instead. package _charnames; use strict; use warnings; our $VERSION = '1.48'; use unicore::Name; # mktables-generated algorithmically-defined names use bytes (); # for $bytes::hint_bits use re "/aa"; # Everything in here should be ASCII $Carp::Internal{ (__PACKAGE__) } = 1; # Translate between Unicode character names and their code points. This is a # submodule of package <charnames>, used to allow \N{...} to be autoloaded, # but it was decided not to autoload the various functions in charnames; the # splitting allows this behavior. # # The official names with their code points are stored in a table in # lib/unicore/Name.pl which is read in as a large string (almost 3/4 Mb in # Unicode 6.0). Each code point sequence appears on a line by itself, with # its corresponding name occupying the next line in the string. (Some of the # CJK and the Hangul syllable names are instead determined algorithmically via # subroutines stored instead in lib/unicore/Name.pm). Because of the large # size of this table, it isn't converted into hashes for faster lookup. # # But, user defined aliases are stored in their own hashes, as are Perl # extensions to the official names. These are checked first before looking at # the official table. # # Basically, the table is grepped for the input code point (viacode()) or # name (the other functions), and the corresponding value on the next or # previous line is returned. The grepping is done by turning the input into a # regular expression. Thus, the same table does double duty, used by both # name and code point lookup. (If we were to have hashes, we would need two, # one for each lookup direction.) # # For loose name matching, the logical thing would be to have a table # with all the ignorable characters squeezed out, and then grep it with the # similiarly-squeezed input name. (And this is in fact how the lookups are # done with the small Perl extension hashes.) But since we need to be able to # go from code point to official name, the original table would still need to # exist. Due to the large size of the table, it was decided to not read # another very large string into memory for a second table. Instead, the # regular expression of the input name is modified to have optional spaces and # dashes between characters. For example, in strict matching, the regular # expression would be: # qr/^DIGIT ONE$/m # Under loose matching, the blank would be squeezed out, and the re would be: # qr/^D[- ]?I[- ]?G[- ]?I[- ]?T[- ]?O[- ]?N[- ]?E$/m # which matches a blank or dash between any characters in the official table. # # This is also how script lookup is done. Basically the re looks like # qr/ (?:LATIN\|GREEK\|CYRILLIC) (?:SMALL )?LETTER $name/ # where $name is the loose or strict regex for the remainder of the name. # The hashes are stored as utf8 strings. This makes it easier to deal with # sequences. I (khw) also tried making Name.pl utf8, but it slowed things # down by a factor of 7. I then tried making Name.pl store the utf8 # equivalents but not calling them utf8. That led to similar speed as leaving # it alone, but since that is harder for a human to parse, I left it as-is. my %system_aliases = ( 'SINGLE-SHIFT 2' => chr utf8::unicode_to_native(0x8E), 'SINGLE-SHIFT 3' => chr utf8::unicode_to_native(0x8F), 'PRIVATE USE 1' => chr utf8::unicode_to_native(0x91), 'PRIVATE USE 2' => chr utf8::unicode_to_native(0x92), ); # These are the aliases above that differ under :loose and :full matching # because the :full versions have blanks or hyphens in them. #my %loose_system_aliases = ( #); #my %deprecated_aliases; #$deprecated_aliases{'BELL'} = chr utf8::unicode_to_native(0x07) if $^V lt v5.17.0; #my %loose_deprecated_aliases = ( #); # These are special cased in :loose matching, differing only in a medial # hyphen my $HANGUL_JUNGSEONG_O_E_utf8 = chr 0x1180; my $HANGUL_JUNGSEONG_OE_utf8 = chr 0x116C; my $txt; # The table of official character names my %full_names_cache; # Holds already-looked-up names, so don't have to # re-look them up again. The previous versions of charnames had scoping # bugs. For example if we use script A in one scope and find and cache # what Z resolves to, we can't use that cache in a different scope that # uses script B instead of A, as Z might be an entirely different letter # there; or there might be different aliases in effect in different # scopes, or :short may be in effect or not effect in different scopes, # or various combinations thereof. This was solved in this version # mostly by moving things to %^H. But some things couldn't be moved # there. One of them was the cache of runtime looked-up names, in part # because %^H is read-only at runtime. I (khw) don't know why the cache # was run-time only in the previous versions: perhaps oversight; perhaps # that compile time looking doesn't happen in a loop so didn't think it # was worthwhile; perhaps not wanting to make the cache too large. But # I decided to make it compile time as well; this could easily be # changed. # Anyway, this hash is not scoped, and is added to at runtime. It # doesn't have scoping problems because the data in it is restricted to # official names, which are always invariant, and we only set it and # look at it at during :full lookups, so is unaffected by any other # scoped options. I put this in to maintain parity with the older # version. If desired, a %short_names cache could also be made, as well # as one for each script, say in %script_names_cache, with each key # being a hash for a script named in a 'use charnames' statement. I # decided not to do that for now, just because it's added complication, # and because I'm just trying to maintain parity, not extend it. # Like %full_names_cache, but for use when :loose is in effect. There needs # to be two caches because :loose may not be in effect for a scope, and a # loose name could inappropriately be returned when only exact matching is # called for. my %loose_names_cache; # Designed so that test decimal first, and then hex. Leading zeros # imply non-decimal, as do non-[0-9] my $decimal_qr = qr/^[1-9]\d$/; # Returns the hex number in $1. my $hex_qr = qr/^(?:[Uu]\+\|0[xX])?([[:xdigit:]]+)$/; sub croak { require Carp; goto &Carp::croak; } # croak sub carp { require Carp; goto &Carp::carp; } # carp sub populate_txt() { return if $txt; $txt = do "unicore/Name.pl"; Internals::SvREADONLY($txt, 1); } sub alias (@) # Set up a single alias { my @errors; my $nbsp = chr utf8::unicode_to_native(0xA0); my $alias = ref $_[0] ? $_[0] : { @_ }; foreach my $name (sort keys %$alias) { # Sort only because it helps having # deterministic output for # t/lib/charnames/alias my $value = $alias->{$name}; next unless defined $value; # Omit if screwed up. # Is slightly slower to just after this statement see if it is # decimal, since we already know it is after having converted from # hex, but makes the code easier to maintain, and is called # infrequently, only at compile-time if ($value !~ $decimal_qr && $value =~ $hex_qr) { my $temp = CORE::hex $1; $temp = utf8::unicode_to_native($temp) if $value =~ /^[Uu]\+/; $value = $temp; } if ($value =~ $decimal_qr) { no warnings qw(non_unicode surrogate nonchar); # Allow any of these $^H{charnames_ord_aliases}{$name} = chr $value; # Use a canonical form. $^H{charnames_inverse_ords}{sprintf("%05X", $value)} = $name; } else { my $ok_portion = ""; $ok_portion = $1 if $name =~ / ^ ( \p{_Perl_Charname_Begin} \p{_Perl_Charname_Continue} ) /x; # If the name was fully correct, the above should have matched all of # it. if (length $ok_portion < length $name) { my $first_bad = substr($name, length($ok_portion), 1); push @errors, "Invalid character in charnames alias definition; " . "marked by <-- HERE in '$ok_portion$first_bad<-- HERE " . substr($name, length($ok_portion) + 1) . "'"; } else { if ($name =~ / ( .* \s ) ( \s* ) $ /x) { push @errors, "charnames alias definitions may not contain " . "trailing white-space; marked by <-- HERE in " . "'$1 <-- HERE " . $2 . "'"; next; } # Use '+' instead of '' in this regex, because any trailing # blanks have already been found if ($name =~ / ( .? \s{2} ) ( .+ ) /x) { push @errors, "charnames alias definitions may not contain a " . "sequence of multiple spaces; marked by <-- HERE " . "in '$1 <-- HERE " . $2 . "'"; next; } $^H{charnames_name_aliases}{$name} = $value; } } } # We find and output all errors from this :alias definition, rather than # failing on the first one, so fewer runs are needed to get it to compile if (@errors) { croak join "\n", @errors; } return; } # alias sub not_legal_use_bytes_msg { my ($name, $utf8) = @_; my $return; if (length($utf8) == 1) { $return = sprintf("Character 0x%04x with name '%s' is", ord $utf8, $name); } else { $return = sprintf("String with name '%s' (and ordinals %s) contains character(s)", $name, join(" ", map { sprintf "0x%04X", ord $_ } split(//, $utf8))); } return $return . " above 0xFF with 'use bytes' in effect"; } sub alias_file ($) # Reads a file containing alias definitions { require File::Spec; my ($arg, $file) = @_; if (-f $arg && File::Spec->file_name_is_absolute ($arg)) { $file = $arg; } elsif ($arg =~ m/ ^ \p{_Perl_IDStart} \p{_Perl_IDCont}* $/x) { $file = "unicore/${arg}_alias.pl"; } else { croak "Charnames alias file names can only have identifier characters"; } if (my @alias = do $file) { @alias == 1 && !defined $alias[0] and croak "$file cannot be used as alias file for charnames"; @alias % 2 and croak "$file did not return a (valid) list of alias pairs"; alias (@alias); return (1); } 0; } # alias_file # For use when don't import anything. This structure must be kept in # sync with the one that import() fills up. my %dummy_H = ( charnames_stringified_names => "", charnames_stringified_ords => "", charnames_scripts => "", charnames_full => 1, charnames_loose => 0, charnames_short => 0, ); sub lookup_name ($$$;$) { my ($name, $wants_ord, $runtime, $regex_loose) = @_; $regex_loose //= 0; # Lookup the name or sequence $name in the tables. If $wants_ord is false, # returns the string equivalent of $name; if true, returns the ordinal value # instead, but in this case $name must not be a sequence; otherwise undef is # returned and a warning raised. $runtime is 0 if compiletime, otherwise # gives the number of stack frames to go back to get the application caller # info. # If $name is not found, returns undef in runtime with no warning; and in # compiletime, the Unicode replacement character, with a warning. # It looks first in the aliases, then in the large table of official Unicode # names. my $result; # The string result my $save_input; if ($runtime && ! $regex_loose) { my $hints_ref = (caller($runtime))[10]; # If we didn't import anything (which happens with 'use charnames ()', # substitute a dummy structure. $hints_ref = \%dummy_H if ! defined $hints_ref \|\| (! defined $hints_ref->{charnames_full} && ! defined $hints_ref->{charnames_loose}); # At runtime, but currently not at compile time, %^H gets # stringified, so un-stringify back to the original data structures. # These get thrown away by perl before the next invocation # Also fill in the hash with the non-stringified data. # N.B. New fields must be also added to %dummy_H %{$^H{charnames_name_aliases}} = split ',', $hints_ref->{charnames_stringified_names}; %{$^H{charnames_ord_aliases}} = split ',', $hints_ref->{charnames_stringified_ords}; $^H{charnames_scripts} = $hints_ref->{charnames_scripts}; $^H{charnames_full} = $hints_ref->{charnames_full}; $^H{charnames_loose} = $hints_ref->{charnames_loose}; $^H{charnames_short} = $hints_ref->{charnames_short}; } my $loose = $regex_loose \|\| $^H{charnames_loose}; my $lookup_name; # Input name suitably modified for grepping for in the # table # User alias should be checked first or else can't override ours, and if we # were to add any, could conflict with theirs. if (! $regex_loose && exists $^H{charnames_ord_aliases}{$name}) { $result = $^H{charnames_ord_aliases}{$name}; } elsif (! $regex_loose && exists $^H{charnames_name_aliases}{$name}) { $name = $^H{charnames_name_aliases}{$name}; $save_input = $lookup_name = $name; # Cache the result for any error # message # The aliases are documented to not match loosely, so change loose match # into full. if ($loose) { $loose = 0; $^H{charnames_full} = 1; } } else { # Here, not a user alias. That means that loose matching may be in # effect; will have to modify the input name. $lookup_name = $name; if ($loose) { $lookup_name = uc $lookup_name; # Squeeze out all underscores $lookup_name =~ s/_//g; # Remove all medial hyphens $lookup_name =~ s/ (?<= \S ) - (?= \S )//gx; # Squeeze out all spaces $lookup_name =~ s/\s//g; } # Here, $lookup_name has been modified as necessary for looking in the # hashes. Check the system alias files next. Most of these aliases are # the same for both strict and loose matching. To save space, the ones # which differ are in their own separate hash, which is checked if loose # matching is selected and the regular match fails. To save time, the # loose hashes could be expanded to include all aliases, and there would # only have to be one check. But if someone specifies :loose, they are # interested in convenience over speed, and the time for this second check # is miniscule compared to the rest of the routine. if (exists $system_aliases{$lookup_name}) { $result = $system_aliases{$lookup_name}; } # There are currently no entries in this hash, so don't waste time looking # for them. But the code is retained for the unlikely possibility that # some will be added in the future. # elsif ($loose && exists $loose_system_aliases{$lookup_name}) { # $result = $loose_system_aliases{$lookup_name}; # } # if (exists $deprecated_aliases{$lookup_name}) { # require warnings; # warnings::warnif('deprecated', # "Unicode character name \"$name\" is deprecated, use \"" # . viacode(ord $deprecated_aliases{$lookup_name}) # . "\" instead"); # $result = $deprecated_aliases{$lookup_name}; # } # There are currently no entries in this hash, so don't waste time looking # for them. But the code is retained for the unlikely possibility that # some will be added in the future. # elsif ($loose && exists $loose_deprecated_aliases{$lookup_name}) { # require warnings; # warnings::warnif('deprecated', # "Unicode character name \"$name\" is deprecated, use \"" # . viacode(ord $loose_deprecated_aliases{$lookup_name}) # . "\" instead"); # $result = $loose_deprecated_aliases{$lookup_name}; # } } my @off; # Offsets into table of pattern match begin and end # If haven't found it yet... if (! defined $result) { # See if has looked this input up earlier. if (! $loose && $^H{charnames_full} && exists $full_names_cache{$name}) { $result = $full_names_cache{$name}; } elsif ($loose && exists $loose_names_cache{$name}) { $result = $loose_names_cache{$name}; } else { # Here, must do a look-up # If full or loose matching succeeded, points to where to cache the # result my $cache_ref; ## Suck in the code/name list as a big string. ## Entries look like: ## "00052\nLATIN CAPITAL LETTER R\n\n" # or # "0052 0303\nLATIN CAPITAL LETTER R WITH TILDE\n\n" populate_txt() unless $txt; ## @off will hold the index into the code/name string of the start and ## end of the name as we find it. ## If :loose, look for a loose match; if :full, look for the name ## exactly # First, see if the name is one which is algorithmically determinable. # The subroutine is included in Name.pl. The table contained in # $txt doesn't contain these. Experiments show that checking # for these before checking for the regular names has no # noticeable impact on performance for the regular names, but # the other way around slows down finding these immensely. # Algorithmically determinables are not placed in the cache because # that uses up memory, and finding these again is fast. if ( ($loose \|\| $^H{charnames_full}) && (defined (my $ord = charnames::name_to_code_point_special($lookup_name, $loose)))) { $result = chr $ord; } else { # Not algorithmically determinable; look up in the table. The name # will be turned into a regex, so quote any meta characters. $lookup_name = quotemeta $lookup_name; if ($loose) { # For loose matches, $lookup_name has already squeezed out the # non-essential characters. We have to add in code to make the # squeezed version match the non-squeezed equivalent in the table. # The only remaining hyphens are ones that start or end a word in # the original. They have been quoted in $lookup_name so they look # like "\-". Change all other characters except the backslash # quotes for any metacharacters, and the final character, so that # e.g., COLON gets transformed into: /C[- ]?O[- ]?L[- ]?O[- ]?N/ $lookup_name =~ s/ (?! \\ -) # Don't do this to the \- sequence ( [^-\\] ) # Nor the "-" within that sequence, # nor the "\" that quotes metachars, # but otherwise put the char into $1 (?=.) # And don't do it for the final char /$1\[- \]?/gx; # And add an optional blank or # '-' after each $1 char # Those remaining hyphens were originally at the beginning or end of # a word, so they can match either a blank before or after, but not # both. (Keep in mind that they have been quoted, so are a '\-' # sequence) $lookup_name =~ s/\\ -/(?:- \| -)/xg; } # Do the lookup in the full table if asked for, and if succeeds # save the offsets and set where to cache the result. if (($loose \|\| $^H{charnames_full}) && $txt =~ /^$lookup_name$/m) { @off = ($-[0], $+[0]); $cache_ref = ($loose) ? \%loose_names_cache : \%full_names_cache; } elsif ($regex_loose) { # Currently don't allow :short when this is set return; } else { # Here, didn't look for, or didn't find the name. # If :short is allowed, see if input is like "greek:Sigma". # Keep in mind that $lookup_name has had the metas quoted. my $scripts_trie = ""; my $name_has_uppercase; if (($^H{charnames_short}) && $lookup_name =~ /^ (?: \\ \s)* # Quoted space (.+?) # $1 = the script (?: \\ \s)* \\ : # Quoted colon (?: \\ \s)* (.+?) # $2 = the name (?: \\ \s)* $ /xs) { # Even in non-loose matching, the script traditionally has been # case insensitive $scripts_trie = "\U$1"; $lookup_name = $2; # Use original name to find its input casing, but ignore the # script part of that to make the determination. $save_input = $name if ! defined $save_input; $name =~ s/.?://; $name_has_uppercase = $name =~ /[[:upper:]]/; } else { # Otherwise look in allowed scripts $scripts_trie = $^H{charnames_scripts}; # Use original name to find its input casing $name_has_uppercase = $name =~ /[[:upper:]]/; } my $case = $name_has_uppercase ? "CAPITAL" : "SMALL"; return if (! $scripts_trie \|\| $txt !~ /^ (?: $scripts_trie ) \ (?:$case\ )? LETTER \ \U$lookup_name $/xm); # Here have found the input name in the table. @off = ($-[0], $+[0]); } # Here, the input name has been found; we haven't set up the output, # but we know where in the string # the name starts. The string is set up so that for single characters # (and not named sequences), the name is on a line by itself, and the # previous line contains precisely 5 hex digits for its code point. # Named sequences won't have the 7th preceding character be a \n. # (Actually, for the very first entry in the table this isn't strictly # true: subtracting 7 will yield -1, and the substr below will # therefore yield the very last character in the table, which should # also be a \n, so the statement works anyway.) if (substr($txt, $off[0] - 7, 1) eq "\n") { $result = chr CORE::hex substr($txt, $off[0] - 6, 5); # Handle the single loose matching special case, in which two names # differ only by a single medial hyphen. If the original had a # hyphen (or more) in the right place, then it is that one. $result = $HANGUL_JUNGSEONG_O_E_utf8 if $loose && $result eq $HANGUL_JUNGSEONG_OE_utf8 && $name =~ m/O \s - [-\s]* E/ix; # Note that this wouldn't work if there were a 2nd # OE in the name } else { # Here, is a named sequence. Need to go looking for the beginning, # which is just after the \n from the previous entry in the table. # The +1 skips past that newline, or, if the rindex() fails, to put # us to an offset of zero. my $charstart = rindex($txt, "\n", $off[0] - 7) + 1; $result = pack("W*", map { CORE::hex } split " ", substr($txt, $charstart, $off[0] - $charstart - 1)); } } # Cache the input so as to not have to search the large table # again, but only if it came from the one search that we cache. # (Haven't bothered with the pain of sorting out scoping issues for the # scripts searches.) $cache_ref->{$name} = $result if defined $cache_ref; } } # Here, have the result character. If the return is to be an ord, must be # any single character. if ($wants_ord) { return ord($result) if length $result == 1; } elsif (! utf8::is_utf8($result)) { # Here isn't UTF-8. That's OK if it is all ASCII, or we are being called # at compile time where we know we can guarantee that Unicode rules are # correctly imposed on the result, or under 'bytes' where we don't want # those rules. But otherwise we have to make it UTF8 to guarantee Unicode # rules on the returned string. return $result if ! $runtime \|\| (caller $runtime)[8] & $bytes::hint_bits \|\| $result !~ /[[:^ascii:]]/; utf8::upgrade($result); return $result; } else { # Here, wants string output. If utf8 is acceptable, just return what # we've got; otherwise attempt to convert it to non-utf8 and return that. my $in_bytes = ! $regex_loose # \p{name=} doesn't currently care if # in bytes or not && (($runtime) ? (caller $runtime)[8] & $bytes::hint_bits : $^H & $bytes::hint_bits); return $result if (! $in_bytes \|\| utf8::downgrade($result, 1)) # The 1 arg # means don't die on failure } # Here, there is an error: either there are too many characters, or the # result string needs to be non-utf8, and at least one character requires # utf8. Prefer any official name over the input one for the error message. if (@off) { $name = substr($txt, $off[0], $off[1] - $off[0]) if @off; } else { $name = (defined $save_input) ? $save_input : $_[0]; } if ($wants_ord) { # Only way to get here in this case is if result too long. Message # assumes that our only caller that requires single char result is # vianame. carp "charnames::vianame() doesn't handle named sequences ($name). Use charnames::string_vianame() instead"; return; } # Only other possible failure here is from use bytes. if ($runtime) { carp not_legal_use_bytes_msg($name, $result); return; } else { croak not_legal_use_bytes_msg($name, $result); } } # lookup_name sub charnames { # For \N{...}. Looks up the character name and returns the string # representation of it. # The first 0 arg means wants a string returned; the second that we are in # compile time return lookup_name($_[0], 0, 0); } sub _loose_regcomp_lookup { # For use only by regcomp.c to compile \p{name=...} # khw thinks it best to not do :short matching, and only official names. # But that is only a guess, and if demand warrants, could be changed return lookup_name($_[0], 0, 1, 1 # Always use :loose matching ); } sub _get_names_info { # For use only by regcomp.c to compile \p{name=/.../} populate_txt() unless $txt; return ( \$txt, \@charnames::code_points_ending_in_code_point ); } sub import { shift; ## ignore class name if (not @_) { carp("'use charnames' needs explicit imports list"); } $^H{charnames} = \&charnames ; $^H{charnames_ord_aliases} = {}; $^H{charnames_name_aliases} = {}; $^H{charnames_inverse_ords} = {}; # New fields must be added to %dummy_H, and the code in lookup_name() # that copies fields from the runtime structure ## ## fill %h keys with our @_ args. ## my ($promote, %h, @args) = (0); while (my $arg = shift) { if ($arg eq ":alias") { @_ or croak ":alias needs an argument in charnames"; my $alias = shift; if (ref $alias) { ref $alias eq "HASH" or croak "Only HASH reference supported as argument to :alias"; alias ($alias); $promote = 1; next; } if ($alias =~ m{:(\w+)$}) { $1 eq "full" \|\| $1 eq "loose" \|\| $1 eq "short" and croak ":alias cannot use existing pragma :$1 (reversed order?)"; alias_file ($1) and $promote = 1; next; } alias_file ($alias) and $promote = 1; next; } if (substr($arg, 0, 1) eq ':' and ! ($arg eq ":full" \|\| $arg eq ":short" \|\| $arg eq ":loose")) { warn "unsupported special '$arg' in charnames"; next; } push @args, $arg; } @args == 0 && $promote and @args = (":full"); @h{@args} = (1) x @args; # Don't leave these undefined as are tested for in lookup_names $^H{charnames_full} = delete $h{':full'} \|\| 0; $^H{charnames_loose} = delete $h{':loose'} \|\| 0; $^H{charnames_short} = delete $h{':short'} \|\| 0; my @scripts = map { uc quotemeta } keys %h; ## ## If utf8? warnings are enabled, and some scripts were given, ## see if at least we can find one letter from each script. ## if (warnings::enabled('utf8') && @scripts) { populate_txt() unless $txt; for my $script (@scripts) { if (not $txt =~ m/^$script (?:CAPITAL \|SMALL )?LETTER /m) { warnings::warn('utf8', "No such script: '$script'"); $script = quotemeta $script; # Escape it, for use in the re. } } } # %^H gets stringified, so serialize it ourselves so can extract the # real data back later. $^H{charnames_stringified_ords} = join ",", %{$^H{charnames_ord_aliases}}; $^H{charnames_stringified_names} = join ",", %{$^H{charnames_name_aliases}}; $^H{charnames_stringified_inverse_ords} = join ",", %{$^H{charnames_inverse_ords}}; # Modify the input script names for loose name matching if that is also # specified, similar to the way the base character name is prepared. They # don't (currently, and hopefully never will) have dashes. These go into a # regex, and have already been uppercased and quotemeta'd. Squeeze out all # input underscores, blanks, and dashes. Then convert so will match a blank # between any characters. if ($^H{charnames_loose}) { for (my $i = 0; $i < @scripts; $i++) { $scripts[$i] =~ s/[_ -]//g; $scripts[$i] =~ s/ ( [^\\] ) (?= . ) /$1\\ ?/gx; } } $^H{charnames_scripts} = join "\|", @scripts; # Stringifiy them as a trie } # import # Cache of already looked-up values. This is set to only contain # official values, and user aliases can't override them, so scoping is # not an issue. my %viacode; my $no_name_code_points_re = join "\|", map { sprintf("%05X", utf8::unicode_to_native($_)) } 0x80, 0x81, 0x84, 0x99; $no_name_code_points_re = qr/$no_name_code_points_re/; sub viacode { # Returns the name of the code point argument if (@_ != 1) { carp "charnames::viacode() expects one argument"; return; } my $arg = shift; # This is derived from Unicode::UCD, where it is nearly the same as the # function _getcode(), but here it makes sure that even a hex argument # has the proper number of leading zeros, which is critical in # matching against $txt below # Must check if decimal first; see comments at that definition my $hex; if ($arg =~ $decimal_qr) { $hex = sprintf "%05X", $arg; } elsif ($arg =~ $hex_qr) { $hex = CORE::hex $1; $hex = utf8::unicode_to_native($hex) if $arg =~ /^[Uu]\+/; # Below is the line that differs from the _getcode() source $hex = sprintf "%05X", $hex; } else { carp("unexpected arg \"$arg\" to charnames::viacode()"); return; } return $viacode{$hex} if exists $viacode{$hex}; my $return; # If the code point is above the max in the table, there's no point # looking through it. Checking the length first is slightly faster if (length($hex) <= 5 \|\| CORE::hex($hex) <= 0x10FFFF) { populate_txt() unless $txt; # See if the name is algorithmically determinable. my $algorithmic = charnames::code_point_to_name_special(CORE::hex $hex); if (defined $algorithmic) { $viacode{$hex} = $algorithmic; return $algorithmic; } # Return the official name, if exists. It's unclear to me (khw) at # this juncture if it is better to return a user-defined override, so # leaving it as is for now. if ($txt =~ m/^$hex\n/m) { # The name starts with the next character and goes up to the # next new-line. Using capturing parentheses above instead of # @+ more than doubles the execution time in Perl 5.13 $return = substr($txt, $+[0], index($txt, "\n", $+[0]) - $+[0]); # If not one of these 4 code points, return what we've found. if ($hex !~ / ^ $no_name_code_points_re $ /x) { $viacode{$hex} = $return; return $return; } # For backwards compatibility, we don't return the official name of # the 4 code points if there are user-defined aliases for them -- so # continue looking. } } # See if there is a user name for it, before giving up completely. # First get the scoped aliases, give up if have none. my $H_ref = (caller(1))[10]; return if ! defined $return && (! defined $H_ref \|\| ! exists $H_ref->{charnames_stringified_inverse_ords}); my %code_point_aliases; if (defined $H_ref->{charnames_stringified_inverse_ords}) { %code_point_aliases = split ',', $H_ref->{charnames_stringified_inverse_ords}; return $code_point_aliases{$hex} if exists $code_point_aliases{$hex}; } # Here there is no user-defined alias, return any official one. return $return if defined $return; if (CORE::hex($hex) > 0x10FFFF && warnings::enabled('non_unicode')) { carp "Unicode characters only allocated up to U+10FFFF (you asked for U+$hex)"; } return; } # viacode 1; # ex: set ts=8 sts=2 sw=2 et:	33.35 KB	2025-07-28 03:53
📄 base.pm use 5.008; package base; use strict 'vars'; our $VERSION = '2.27'; $VERSION =~ tr/_//d; # simplest way to avoid indexing of the package: no package statement sub base::__inc::unhook { @INC = grep !(ref eq 'CODE' && $_ == $_[0]), @INC } # instance is blessed array of coderefs to be removed from @INC at scope exit sub base::__inc::scope_guard::DESTROY { base::__inc::unhook $_ for @{$_[0]} } # constant.pm is slow sub SUCCESS () { 1 } sub PUBLIC () { 20 } sub PRIVATE () { 21 } sub INHERITED () { 22 } sub PROTECTED () { 23 } my $Fattr = \%fields::attr; sub has_fields { my($base) = shift; my $fglob = ${"$base\::"}{FIELDS}; return( ($fglob && 'GLOB' eq ref($fglob) && $fglob{HASH}) ? 1 : 0 ); } sub has_attr { my($proto) = shift; my($class) = ref $proto \|\| $proto; return exists $Fattr->{$class}; } sub get_attr { $Fattr->{$_[0]} = [1] unless $Fattr->{$_[0]}; return $Fattr->{$_[0]}; } if ($] < 5.009) { get_fields = sub { # Shut up a possible typo warning. () = \%{$_[0].'::FIELDS'}; my $f = \%{$_[0].'::FIELDS'}; # should be centralized in fields? perhaps # fields::mk_FIELDS_be_OK. Peh. As long as %{ $package . '::FIELDS' } # is used here anyway, it doesn't matter. bless $f, 'pseudohash' if (ref($f) ne 'pseudohash'); return $f; } } else { get_fields = sub { # Shut up a possible typo warning. () = \%{$_[0].'::FIELDS'}; return \%{$_[0].'::FIELDS'}; } } if ($] < 5.008) { _module_to_filename = sub { (my $fn = $_[0]) =~ s!::!/!g; $fn .= '.pm'; return $fn; } } else { _module_to_filename = sub { (my $fn = $_[0]) =~ s!::!/!g; $fn .= '.pm'; utf8::encode($fn); return $fn; } } sub import { my $class = shift; return SUCCESS unless @_; # List of base classes from which we will inherit %FIELDS. my $fields_base; my $inheritor = caller(0); my @bases; foreach my $base (@_) { if ( $inheritor eq $base ) { warn "Class '$inheritor' tried to inherit from itself\n"; } next if grep $_->isa($base), ($inheritor, @bases); # Following blocks help isolate $SIG{__DIE__} and @INC changes { my $sigdie; { local $SIG{__DIE__}; my $fn = _module_to_filename($base); my $dot_hidden; eval { my $guard; if ($INC[-1] eq '.' && %{"$base\::"}) { # So: the package already exists => this an optional load # And: there is a dot at the end of @INC => we want to hide it # However: we only want to hide it during our own* require() # (i.e. without affecting nested require()s). # So we add a hook to @INC whose job is to hide the dot, but which # first checks checks the callstack depth, because within nested # require()s the callstack is deeper. # Since CORE::GLOBAL::require makes it unknowable in advance what # the exact relevant callstack depth will be, we have to record it # inside a hook. So we put another hook just for that at the front # of @INC, where it's guaranteed to run -- immediately. # The dot-hiding hook does its job by sitting directly in front of # the dot and removing itself from @INC when reached. This causes # the dot to move up one index in @INC, causing the loop inside # pp_require() to skip it. # Loaded coded may disturb this precise arrangement, but that's OK # because the hook is inert by that time. It is only active during # the top-level require(), when @INC is in our control. The only # possible gotcha is if other hooks already in @INC modify @INC in # some way during that initial require(). # Note that this jiggery hookery works just fine recursively: if # a module loaded via base.pm uses base.pm itself, there will be # one pair of hooks in @INC per base::import call frame, but the # pairs from different nestings do not interfere with each other. my $lvl; unshift @INC, sub { return if defined $lvl; 1 while defined caller ++$lvl; () }; splice @INC, -1, 0, sub { return if defined caller $lvl; ++$dot_hidden, &base::__inc::unhook; () }; $guard = bless [ @INC[0,-2] ], 'base::__inc::scope_guard'; } require $fn }; if ($dot_hidden && (my @fn = grep -e && !( -d _ \|\| -b _ ), $fn.'c', $fn)) { require Carp; Carp::croak(<<ERROR); Base class package "$base" is not empty but "$fn[0]" exists in the current directory. To help avoid security issues, base.pm now refuses to load optional modules from the current working directory when it is the last entry in \@INC. If your software worked on previous versions of Perl, the best solution is to use FindBin to detect the path properly and to add that path to \@INC. As a last resort, you can re-enable looking in the current working directory by adding "use lib '.'" to your code. ERROR } # Only ignore "Can't locate" errors from our eval require. # Other fatal errors (syntax etc) must be reported. # # changing the check here is fragile - if the check # here isn't catching every error you want, you should # probably be using parent.pm, which doesn't try to # guess whether require is needed or failed, # see [perl #118561] die if $@ && $@ !~ /^Can't locate \Q$fn\E .? at . line [0-9]+(?:, <[^>]> (?:line\|chunk) [0-9]+)?\.\n\z/s \|\| $@ =~ /Compilation failed in require at . line [0-9]+(?:, <[^>]> (?:line\|chunk) [0-9]+)?\.\n\z/; unless (%{"$base\::"}) { require Carp; local $" = " "; Carp::croak(<<ERROR); Base class package "$base" is empty. (Perhaps you need to 'use' the module which defines that package first, or make that module available in \@INC (\@INC contains: @INC). ERROR } $sigdie = $SIG{__DIE__} \|\| undef; } # Make sure a global $SIG{__DIE__} makes it out of the localization. $SIG{__DIE__} = $sigdie if defined $sigdie; } push @bases, $base; if ( has_fields($base) \|\| has_attr($base) ) { # No multiple fields inheritance suck* if ($fields_base) { require Carp; Carp::croak("Can't multiply inherit fields"); } else { $fields_base = $base; } } } # Save this until the end so it's all or nothing if the above loop croaks. push @{"$inheritor\::ISA"}, @bases; if( defined $fields_base ) { inherit_fields($inheritor, $fields_base); } } sub inherit_fields { my($derived, $base) = @_; return SUCCESS unless $base; my $battr = get_attr($base); my $dattr = get_attr($derived); my $dfields = get_fields($derived); my $bfields = get_fields($base); $dattr->[0] = @$battr; if( keys %$dfields ) { warn <<"END"; $derived is inheriting from $base but already has its own fields! This will cause problems. Be sure you use base BEFORE declaring fields. END } # Iterate through the base's fields adding all the non-private # ones to the derived class. Hang on to the original attribute # (Public, Private, etc...) and add Inherited. # This is all too complicated to do efficiently with add_fields(). while (my($k,$v) = each %$bfields) { my $fno; if ($fno = $dfields->{$k} and $fno != $v) { require Carp; Carp::croak ("Inherited fields can't override existing fields"); } if( $battr->[$v] & PRIVATE ) { $dattr->[$v] = PRIVATE \| INHERITED; } else { $dattr->[$v] = INHERITED \| $battr->[$v]; $dfields->{$k} = $v; } } foreach my $idx (1..$#{$battr}) { next if defined $dattr->[$idx]; $dattr->[$idx] = $battr->[$idx] & INHERITED; } } 1; __END__ =head1 NAME base - Establish an ISA relationship with base classes at compile time =head1 SYNOPSIS package Baz; use base qw(Foo Bar); =head1 DESCRIPTION Unless you are using the C<fields> pragma, consider this module discouraged in favor of the lighter-weight C<parent>. Allows you to both load one or more modules, while setting up inheritance from those modules at the same time. Roughly similar in effect to package Baz; BEGIN { require Foo; require Bar; push @ISA, qw(Foo Bar); } When C<base> tries to C<require> a module, it will not die if it cannot find the module's file, but will die on any other error. After all this, should your base class be empty, containing no symbols, C<base> will die. This is useful for inheriting from classes in the same file as yourself but where the filename does not match the base module name, like so: # in Bar.pm package Foo; sub exclaim { "I can have such a thing?!" } package Bar; use base "Foo"; There is no F<Foo.pm>, but because C<Foo> defines a symbol (the C<exclaim> subroutine), C<base> will not die when the C<require> fails to load F<Foo.pm>. C<base> will also initialize the fields if one of the base classes has it. Multiple inheritance of fields is B<NOT> supported, if two or more base classes each have inheritable fields the 'base' pragma will croak. See L<fields> for a description of this feature. The base class' C<import> method is B<not> called. =head1 DIAGNOSTICS =over 4 =item Base class package "%s" is empty. base.pm was unable to require the base package, because it was not found in your path. =item Class 'Foo' tried to inherit from itself Attempting to inherit from yourself generates a warning. package Foo; use base 'Foo'; =back =head1 HISTORY This module was introduced with Perl 5.004_04. =head1 CAVEATS Due to the limitations of the implementation, you must use base I<before> you declare any of your own fields. =head1 SEE ALSO L<fields> =cut	10.7 KB	2025-07-28 03:54
📄 bytes.pm package bytes; our $VERSION = '1.07'; $bytes::hint_bits = 0x00000008; sub import { $^H \|= $bytes::hint_bits; } sub unimport { $^H &= ~$bytes::hint_bits; } sub AUTOLOAD { require "bytes_heavy.pl"; goto &$AUTOLOAD if defined &$AUTOLOAD; require Carp; Carp::croak("Undefined subroutine $AUTOLOAD called"); } sub length (_); sub chr (_); sub ord (_); sub substr ($$;$$); sub index ($$;$); sub rindex ($$;$); 1; __END__ =head1 NAME bytes - Perl pragma to expose the individual bytes of characters =head1 NOTICE Because the bytes pragma breaks encapsulation (i.e. it exposes the innards of how the perl executable currently happens to store a string), the byte values that result are in an unspecified encoding. B<Use of this module for anything other than debugging purposes is strongly discouraged.> If you feel that the functions here within might be useful for your application, this possibly indicates a mismatch between your mental model of Perl Unicode and the current reality. In that case, you may wish to read some of the perl Unicode documentation: L<perluniintro>, L<perlunitut>, L<perlunifaq> and L<perlunicode>. =head1 SYNOPSIS use bytes; ... chr(...); # or bytes::chr ... index(...); # or bytes::index ... length(...); # or bytes::length ... ord(...); # or bytes::ord ... rindex(...); # or bytes::rindex ... substr(...); # or bytes::substr no bytes; =head1 DESCRIPTION Perl's characters are stored internally as sequences of one or more bytes. This pragma allows for the examination of the individual bytes that together comprise a character. Originally the pragma was designed for the loftier goal of helping incorporate Unicode into Perl, but the approach that used it was found to be defective, and the one remaining legitimate use is for debugging when you need to non-destructively examine characters' individual bytes. Just insert this pragma temporarily, and remove it after the debugging is finished. The original usage can be accomplished by explicit (rather than this pragma's implicit) encoding using the L<Encode> module: use Encode qw/encode/; my $utf8_byte_string = encode "UTF8", $string; my $latin1_byte_string = encode "Latin1", $string; Or, if performance is needed and you are only interested in the UTF-8 representation: utf8::encode(my $utf8_byte_string = $string); C<no bytes> can be used to reverse the effect of C<use bytes> within the current lexical scope. As an example, when Perl sees C<$x = chr(400)>, it encodes the character in UTF-8 and stores it in C<$x>. Then it is marked as character data, so, for instance, C<length $x> returns C<1>. However, in the scope of the C<bytes> pragma, C<$x> is treated as a series of bytes - the bytes that make up the UTF8 encoding - and C<length $x> returns C<2>: $x = chr(400); print "Length is ", length $x, "\n"; # "Length is 1" printf "Contents are %vd\n", $x; # "Contents are 400" { use bytes; # or "require bytes; bytes::length()" print "Length is ", length $x, "\n"; # "Length is 2" printf "Contents are %vd\n", $x; # "Contents are 198.144 (on # ASCII platforms)" } C<chr()>, C<ord()>, C<substr()>, C<index()> and C<rindex()> behave similarly. For more on the implications, see L<perluniintro> and L<perlunicode>. C<bytes::length()> is admittedly handy if you need to know the B<byte length> of a Perl scalar. But a more modern way is: use Encode 'encode'; length(encode('UTF-8', $scalar)) =head1 LIMITATIONS C<bytes::substr()> does not work as an I<lvalue()>. =head1 SEE ALSO L<perluniintro>, L<perlunicode>, L<utf8>, L<Encode> =cut	3.65 KB	2025-07-28 03:53
📄 bytes_heavy.pl package bytes; sub length (_) { BEGIN { bytes::import() } return CORE::length($_[0]); } sub substr ($$;$$) { BEGIN { bytes::import() } return @_ == 2 ? CORE::substr($_[0], $_[1]) : @_ == 3 ? CORE::substr($_[0], $_[1], $_[2]) : CORE::substr($_[0], $_[1], $_[2], $_[3]) ; } sub ord (_) { BEGIN { bytes::import() } return CORE::ord($_[0]); } sub chr (_) { BEGIN { bytes::import() } return CORE::chr($_[0]); } sub index ($$;$) { BEGIN { bytes::import() } return @_ == 2 ? CORE::index($_[0], $_[1]) : CORE::index($_[0], $_[1], $_[2]) ; } sub rindex ($$;$) { BEGIN { bytes::import() } return @_ == 2 ? CORE::rindex($_[0], $_[1]) : CORE::rindex($_[0], $_[1], $_[2]) ; } 1;	758 B	2025-07-28 03:53
📄 charnames.pm package charnames; use strict; use warnings; our $VERSION = '1.48'; use unicore::Name; # mktables-generated algorithmically-defined names use _charnames (); # The submodule for this where most of the work gets done use bytes (); # for $bytes::hint_bits use re "/aa"; # Everything in here should be ASCII # Translate between Unicode character names and their code points. # This is a wrapper around the submodule C<_charnames>. This design allows # C<_charnames> to be autoloaded to enable use of \N{...}, but requires this # module to be explicitly requested for the functions API. $Carp::Internal{ (__PACKAGE__) } = 1; sub import { shift; ## ignore class name _charnames->import(@_); } # Cache of already looked-up values. This is set to only contain # official values, and user aliases can't override them, so scoping is # not an issue. my %viacode; sub viacode { return _charnames::viacode(@_); } sub vianame { if (@_ != 1) { _charnames::carp "charnames::vianame() expects one name argument"; return () } # Looks up the character name and returns its ordinal if # found, undef otherwise. my $arg = shift; return () unless length $arg; if ($arg =~ /^U\+([0-9a-fA-F]+)$/) { # khw claims that this is poor interface design. The function should # return either a an ord or a chr for all inputs; not be bipolar. But # can't change it because of backward compatibility. New code can use # string_vianame() instead. my $ord = CORE::hex $1; return pack("U", $ord) if $ord <= 255 \|\| ! ((caller 0)[8] & $bytes::hint_bits); _charnames::carp _charnames::not_legal_use_bytes_msg($arg, chr $ord); return; } # The first 1 arg means wants an ord returned; the second that we are in # runtime, and this is the first level routine called from the user return _charnames::lookup_name($arg, 1, 1); } # vianame sub string_vianame { # Looks up the character name and returns its string representation if # found, undef otherwise. if (@_ != 1) { _charnames::carp "charnames::string_vianame() expects one name argument"; return; } my $arg = shift; return () unless length $arg; if ($arg =~ /^U\+([0-9a-fA-F]+)$/) { my $ord = CORE::hex $1; return pack("U", $ord) if $ord <= 255 \|\| ! ((caller 0)[8] & $bytes::hint_bits); _charnames::carp _charnames::not_legal_use_bytes_msg($arg, chr $ord); return; } # The 0 arg means wants a string returned; the 1 arg means that we are in # runtime, and this is the first level routine called from the user return _charnames::lookup_name($arg, 0, 1); } # string_vianame 1; __END__ =encoding utf8 =head1 NAME charnames - access to Unicode character names and named character sequences; also define character names =head1 SYNOPSIS use charnames ':full'; print "\N{GREEK SMALL LETTER SIGMA} is called sigma.\n"; print "\N{LATIN CAPITAL LETTER E WITH VERTICAL LINE BELOW}", " is an officially named sequence of two Unicode characters\n"; use charnames ':loose'; print "\N{Greek small-letter sigma}", "can be used to ignore case, underscores, most blanks," "and when you aren't sure if the official name has hyphens\n"; use charnames ':short'; print "\N{greek:Sigma} is an upper-case sigma.\n"; use charnames qw(cyrillic greek); print "\N{sigma} is Greek sigma, and \N{be} is Cyrillic b.\n"; use utf8; use charnames ":full", ":alias" => { e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE", mychar => 0xE8000, # Private use area "自転車に乗る人" => "BICYCLIST" }; print "\N{e_ACUTE} is a small letter e with an acute.\n"; print "\N{mychar} allows me to name private use characters.\n"; print "And I can create synonyms in other languages,", " such as \N{自転車に乗る人} for "BICYCLIST (U+1F6B4)\n"; use charnames (); print charnames::viacode(0x1234); # prints "ETHIOPIC SYLLABLE SEE" printf "%04X", charnames::vianame("GOTHIC LETTER AHSA"); # prints # "10330" print charnames::vianame("LATIN CAPITAL LETTER A"); # prints 65 on # ASCII platforms; # 193 on EBCDIC print charnames::string_vianame("LATIN CAPITAL LETTER A"); # prints "A" =head1 DESCRIPTION Pragma C<use charnames> is used to gain access to the names of the Unicode characters and named character sequences, and to allow you to define your own character and character sequence names. All forms of the pragma enable use of the following 3 functions: =over =item * L</charnames::string_vianame(I<name>)> for run-time lookup of a either a character name or a named character sequence, returning its string representation =item * L</charnames::vianame(I<name>)> for run-time lookup of a character name (but not a named character sequence) to get its ordinal value (code point) =item * L</charnames::viacode(I<code>)> for run-time lookup of a code point to get its Unicode name. =back Starting in Perl v5.16, any occurrence of C<\N{I<CHARNAME>}> sequences in a double-quotish string automatically loads this module with arguments C<:full> and C<:short> (described below) if it hasn't already been loaded with different arguments, in order to compile the named Unicode character into position in the string. Prior to v5.16, an explicit S<C<use charnames>> was required to enable this usage. (However, prior to v5.16, the form C<S<"use charnames ();">> did not enable C<\N{I<CHARNAME>}>.) Note that C<\N{U+I<...>}>, where the I<...> is a hexadecimal number, also inserts a character into a string. The character it inserts is the one whose Unicode code point (ordinal value) is equal to the number. For example, C<"\N{U+263a}"> is the Unicode (white background, black foreground) smiley face equivalent to C<"\N{WHITE SMILING FACE}">. Also note, C<\N{I<...>}> can mean a regex quantifier instead of a character name, when the I<...> is a number (or comma separated pair of numbers (see L<perlreref/QUANTIFIERS>), and is not related to this pragma. The C<charnames> pragma supports arguments C<:full>, C<:loose>, C<:short>, script names and L<customized aliases\|/CUSTOM ALIASES>. If C<:full> is present, for expansion of C<\N{I<CHARNAME>}>, the string I<CHARNAME> is first looked up in the list of standard Unicode character names. C<:loose> is a variant of C<:full> which allows I<CHARNAME> to be less precisely specified. Details are in L</LOOSE MATCHES>. If C<:short> is present, and I<CHARNAME> has the form C<I<SCRIPT>:I<CNAME>>, then I<CNAME> is looked up as a letter in script I<SCRIPT>, as described in the next paragraph. Or, if C<use charnames> is used with script name arguments, then for C<\N{I<CHARNAME>}> the name I<CHARNAME> is looked up as a letter in the given scripts (in the specified order). Customized aliases can override these, and are explained in L</CUSTOM ALIASES>. For lookup of I<CHARNAME> inside a given script I<SCRIPTNAME>, this pragma looks in the table of standard Unicode names for the names SCRIPTNAME CAPITAL LETTER CHARNAME SCRIPTNAME SMALL LETTER CHARNAME SCRIPTNAME LETTER CHARNAME If I<CHARNAME> is all lowercase, then the C<CAPITAL> variant is ignored, otherwise the C<SMALL> variant is ignored, and both I<CHARNAME> and I<SCRIPTNAME> are converted to all uppercase for look-up. Other than that, both of them follow L<loose\|/LOOSE MATCHES> rules if C<:loose> is also specified; strict otherwise. Note that C<\N{...}> is compile-time; it's a special form of string constant used inside double-quotish strings; this means that you cannot use variables inside the C<\N{...}>. If you want similar run-time functionality, use L<charnames::string_vianame()\|/charnames::string_vianame(I<name>)>. Note, starting in Perl 5.18, the name C<BELL> refers to the Unicode character U+1F514, instead of the traditional U+0007. For the latter, use C<ALERT> or C<BEL>. It is a syntax error to use C<\N{NAME}> where C<NAME> is unknown. For C<\N{NAME}>, it is a fatal error if C<use bytes> is in effect and the input name is that of a character that won't fit into a byte (i.e., whose ordinal is above 255). Otherwise, any string that includes a C<\N{I<charname>}> or C<S<\N{U+I<code point>}>> will automatically have Unicode rules (see L<perlunicode/Byte and Character Semantics>). =head1 LOOSE MATCHES By specifying C<:loose>, Unicode's L<loose character name matching\|http://www.unicode.org/reports/tr44#Matching_Rules> rules are selected instead of the strict exact match used otherwise. That means that I<CHARNAME> doesn't have to be so precisely specified. Upper/lower case doesn't matter (except with scripts as mentioned above), nor do any underscores, and the only hyphens that matter are those at the beginning or end of a word in the name (with one exception: the hyphen in U+1180 C<HANGUL JUNGSEONG O-E> does matter). Also, blanks not adjacent to hyphens don't matter. The official Unicode names are quite variable as to where they use hyphens versus spaces to separate word-like units, and this option allows you to not have to care as much. The reason non-medial hyphens matter is because of cases like U+0F60 C<TIBETAN LETTER -A> versus U+0F68 C<TIBETAN LETTER A>. The hyphen here is significant, as is the space before it, and so both must be included. C<:loose> slows down look-ups by a factor of 2 to 3 versus C<:full>, but the trade-off may be worth it to you. Each individual look-up takes very little time, and the results are cached, so the speed difference would become a factor only in programs that do look-ups of many different spellings, and probably only when those look-ups are through C<vianame()> and C<string_vianame()>, since C<\N{...}> look-ups are done at compile time. =head1 ALIASES Starting in Unicode 6.1 and Perl v5.16, Unicode defines many abbreviations and names that were formerly Perl extensions, and some additional ones that Perl did not previously accept. The list is getting too long to reproduce here, but you can get the complete list from the Unicode web site: L<http://www.unicode.org/Public/UNIDATA/NameAliases.txt>. Earlier versions of Perl accepted almost all the 6.1 names. These were most extensively documented in the v5.14 version of this pod: L<http://perldoc.perl.org/5.14.0/charnames.html#ALIASES>. =head1 CUSTOM ALIASES You can add customized aliases to standard (C<:full>) Unicode naming conventions. The aliases override any standard definitions, so, if you're twisted enough, you can change C<"\N{LATIN CAPITAL LETTER A}"> to mean C<"B">, etc. Aliases must begin with a character that is alphabetic. After that, each may contain any combination of word (C<\w>) characters, SPACE (U+0020), HYPHEN-MINUS (U+002D), LEFT PARENTHESIS (U+0028), and RIGHT PARENTHESIS (U+0029). These last two should never have been allowed in names, and are retained for backwards compatibility only, and may be deprecated and removed in future releases of Perl, so don't use them for new names. (More precisely, the first character of a name you specify must be something that matches all of C<\p{ID_Start}>, C<\p{Alphabetic}>, and C<\p{Gc=Letter}>. This makes sure it is what any reasonable person would view as an alphabetic character. And, the continuation characters that match C<\w> must also match C<\p{ID_Continue}>.) Starting with Perl v5.18, any Unicode characters meeting the above criteria may be used; prior to that only Latin1-range characters were acceptable. An alias can map to either an official Unicode character name (not a loose matched name) or to a numeric code point (ordinal). The latter is useful for assigning names to code points in Unicode private use areas such as U+E800 through U+F8FF. A numeric code point must be a non-negative integer, or a string beginning with C<"U+"> or C<"0x"> with the remainder considered to be a hexadecimal integer. A literal numeric constant must be unsigned; it will be interpreted as hex if it has a leading zero or contains non-decimal hex digits; otherwise it will be interpreted as decimal. If it begins with C<"U+">, it is interpreted as the Unicode code point; otherwise it is interpreted as native. (Only code points below 256 can differ between Unicode and native.) Thus C<U+41> is always the Latin letter "A"; but C<0x41> can be "NO-BREAK SPACE" on EBCDIC platforms. Aliases are added either by the use of anonymous hashes: use charnames ":alias" => { e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE", mychar1 => 0xE8000, }; my $str = "\N{e_ACUTE}"; or by using a file containing aliases: use charnames ":alias" => "pro"; This will try to read C<"unicore/pro_alias.pl"> from the C<@INC> path. This file should return a list in plain perl: ( A_GRAVE => "LATIN CAPITAL LETTER A WITH GRAVE", A_CIRCUM => "LATIN CAPITAL LETTER A WITH CIRCUMFLEX", A_DIAERES => "LATIN CAPITAL LETTER A WITH DIAERESIS", A_TILDE => "LATIN CAPITAL LETTER A WITH TILDE", A_BREVE => "LATIN CAPITAL LETTER A WITH BREVE", A_RING => "LATIN CAPITAL LETTER A WITH RING ABOVE", A_MACRON => "LATIN CAPITAL LETTER A WITH MACRON", mychar2 => "U+E8001", ); Both these methods insert C<":full"> automatically as the first argument (if no other argument is given), and you can give the C<":full"> explicitly as well, like use charnames ":full", ":alias" => "pro"; C<":loose"> has no effect with these. Input names must match exactly, using C<":full"> rules. Also, both these methods currently allow only single characters to be named. To name a sequence of characters, use a L<custom translator\|/CUSTOM TRANSLATORS> (described below). =head1 charnames::string_vianame(I<name>) This is a runtime equivalent to C<\N{...}>. I<name> can be any expression that evaluates to a name accepted by C<\N{...}> under the L<C<:full> option\|/DESCRIPTION> to C<charnames>. In addition, any other options for the controlling C<"use charnames"> in the same scope apply, like C<:loose> or any L<script list, C<:short> option\|/DESCRIPTION>, or L<custom aliases\|/CUSTOM ALIASES> you may have defined. The only differences are due to the fact that C<string_vianame> is run-time and C<\N{}> is compile time. You can't interpolate inside a C<\N{}>, (so C<\N{$variable}> doesn't work); and if the input name is unknown, C<string_vianame> returns C<undef> instead of it being a syntax error. =head1 charnames::vianame(I<name>) This is similar to C<string_vianame>. The main difference is that under most circumstances, C<vianame> returns an ordinal code point, whereas C<string_vianame> returns a string. For example, printf "U+%04X", charnames::vianame("FOUR TEARDROP-SPOKED ASTERISK"); prints "U+2722". This leads to the other two differences. Since a single code point is returned, the function can't handle named character sequences, as these are composed of multiple characters (it returns C<undef> for these. And, the code point can be that of any character, even ones that aren't legal under the C<S<use bytes>> pragma, See L</BUGS> for the circumstances in which the behavior differs from that described above. =head1 charnames::viacode(I<code>) Returns the full name of the character indicated by the numeric code. For example, print charnames::viacode(0x2722); prints "FOUR TEARDROP-SPOKED ASTERISK". The name returned is the "best" (defined below) official name or alias for the code point, if available; otherwise your custom alias for it, if defined; otherwise C<undef>. This means that your alias will only be returned for code points that don't have an official Unicode name (nor alias) such as private use code points. If you define more than one name for the code point, it is indeterminate which one will be returned. As mentioned, the function returns C<undef> if no name is known for the code point. In Unicode the proper name for these is the empty string, which C<undef> stringifies to. (If you ask for a code point past the legal Unicode maximum of U+10FFFF that you haven't assigned an alias to, you get C<undef> plus a warning.) The input number must be a non-negative integer, or a string beginning with C<"U+"> or C<"0x"> with the remainder considered to be a hexadecimal integer. A literal numeric constant must be unsigned; it will be interpreted as hex if it has a leading zero or contains non-decimal hex digits; otherwise it will be interpreted as decimal. If it begins with C<"U+">, it is interpreted as the Unicode code point; otherwise it is interpreted as native. (Only code points below 256 can differ between Unicode and native.) Thus C<U+41> is always the Latin letter "A"; but C<0x41> can be "NO-BREAK SPACE" on EBCDIC platforms. As mentioned above under L</ALIASES>, Unicode 6.1 defines extra names (synonyms or aliases) for some code points, most of which were already available as Perl extensions. All these are accepted by C<\N{...}> and the other functions in this module, but C<viacode> has to choose which one name to return for a given input code point, so it returns the "best" name. To understand how this works, it is helpful to know more about the Unicode name properties. All code points actually have only a single name, which (starting in Unicode 2.0) can never change once a character has been assigned to the code point. But mistakes have been made in assigning names, for example sometimes a clerical error was made during the publishing of the Standard which caused words to be misspelled, and there was no way to correct those. The Name_Alias property was eventually created to handle these situations. If a name was wrong, a corrected synonym would be published for it, using Name_Alias. C<viacode> will return that corrected synonym as the "best" name for a code point. (It is even possible, though it hasn't happened yet, that the correction itself will need to be corrected, and so another Name_Alias can be created for that code point; C<viacode> will return the most recent correction.) The Unicode name for each of the control characters (such as LINE FEED) is the empty string. However almost all had names assigned by other standards, such as the ASCII Standard, or were in common use. C<viacode> returns these names as the "best" ones available. Unicode 6.1 has created Name_Aliases for each of them, including alternate names, like NEW LINE. C<viacode> uses the original name, "LINE FEED" in preference to the alternate. Similarly the name returned for U+FEFF is "ZERO WIDTH NO-BREAK SPACE", not "BYTE ORDER MARK". Until Unicode 6.1, the 4 control characters U+0080, U+0081, U+0084, and U+0099 did not have names nor aliases. To preserve backwards compatibility, any alias you define for these code points will be returned by this function, in preference to the official name. Some code points also have abbreviated names, such as "LF" or "NL". C<viacode> never returns these. Because a name correction may be added in future Unicode releases, the name that C<viacode> returns may change as a result. This is a rare event, but it does happen. =head1 CUSTOM TRANSLATORS The mechanism of translation of C<\N{...}> escapes is general and not hardwired into F<charnames.pm>. A module can install custom translations (inside the scope which C<use>s the module) with the following magic incantation: sub import { shift; $^H{charnames} = \&translator; } Here translator() is a subroutine which takes I<CHARNAME> as an argument, and returns text to insert into the string instead of the C<\N{I<CHARNAME>}> escape. This is the only way you can create a custom named sequence of code points. Since the text to insert should be different in C<bytes> mode and out of it, the function should check the current state of C<bytes>-flag as in: use bytes (); # for $bytes::hint_bits sub translator { if ($^H & $bytes::hint_bits) { return bytes_translator(@_); } else { return utf8_translator(@_); } } See L</CUSTOM ALIASES> above for restrictions on I<CHARNAME>. Of course, C<vianame>, C<viacode>, and C<string_vianame> would need to be overridden as well. =head1 BUGS vianame() normally returns an ordinal code point, but when the input name is of the form C<U+...>, it returns a chr instead. In this case, if C<use bytes> is in effect and the character won't fit into a byte, it returns C<undef> and raises a warning. Since evaluation of the translation function (see L</CUSTOM TRANSLATORS>) happens in the middle of compilation (of a string literal), the translation function should not do any C<eval>s or C<require>s. This restriction should be lifted (but is low priority) in a future version of Perl. =cut # ex: set ts=8 sts=2 sw=2 et:	20.44 KB	2025-07-28 03:53
📄 feature.pm # -- buffer-read-only: t -- # !!!!!!! DO NOT EDIT THIS FILE !!!!!!! # This file is built by regen/feature.pl. # Any changes made here will be lost! package feature; our $VERSION = '1.58'; our %feature = ( fc => 'feature_fc', isa => 'feature_isa', say => 'feature_say', state => 'feature_state', switch => 'feature_switch', bitwise => 'feature_bitwise', indirect => 'feature_indirect', evalbytes => 'feature_evalbytes', signatures => 'feature_signatures', current_sub => 'feature___SUB__', refaliasing => 'feature_refaliasing', postderef_qq => 'feature_postderef_qq', unicode_eval => 'feature_unieval', declared_refs => 'feature_myref', unicode_strings => 'feature_unicode', ); our %feature_bundle = ( "5.10" => [qw(indirect say state switch)], "5.11" => [qw(indirect say state switch unicode_strings)], "5.15" => [qw(current_sub evalbytes fc indirect say state switch unicode_eval unicode_strings)], "5.23" => [qw(current_sub evalbytes fc indirect postderef_qq say state switch unicode_eval unicode_strings)], "5.27" => [qw(bitwise current_sub evalbytes fc indirect postderef_qq say state switch unicode_eval unicode_strings)], "all" => [qw(bitwise current_sub declared_refs evalbytes fc indirect isa postderef_qq refaliasing say signatures state switch unicode_eval unicode_strings)], "default" => [qw(indirect)], ); $feature_bundle{"5.12"} = $feature_bundle{"5.11"}; $feature_bundle{"5.13"} = $feature_bundle{"5.11"}; $feature_bundle{"5.14"} = $feature_bundle{"5.11"}; $feature_bundle{"5.16"} = $feature_bundle{"5.15"}; $feature_bundle{"5.17"} = $feature_bundle{"5.15"}; $feature_bundle{"5.18"} = $feature_bundle{"5.15"}; $feature_bundle{"5.19"} = $feature_bundle{"5.15"}; $feature_bundle{"5.20"} = $feature_bundle{"5.15"}; $feature_bundle{"5.21"} = $feature_bundle{"5.15"}; $feature_bundle{"5.22"} = $feature_bundle{"5.15"}; $feature_bundle{"5.24"} = $feature_bundle{"5.23"}; $feature_bundle{"5.25"} = $feature_bundle{"5.23"}; $feature_bundle{"5.26"} = $feature_bundle{"5.23"}; $feature_bundle{"5.28"} = $feature_bundle{"5.27"}; $feature_bundle{"5.29"} = $feature_bundle{"5.27"}; $feature_bundle{"5.30"} = $feature_bundle{"5.27"}; $feature_bundle{"5.31"} = $feature_bundle{"5.27"}; $feature_bundle{"5.32"} = $feature_bundle{"5.27"}; $feature_bundle{"5.9.5"} = $feature_bundle{"5.10"}; my %noops = ( postderef => 1, lexical_subs => 1, ); my %removed = ( array_base => 1, ); our $hint_shift = 26; our $hint_mask = 0x1c000000; our @hint_bundles = qw( default 5.10 5.11 5.15 5.23 5.27 ); # This gets set (for now) in $^H as well as in %^H, # for runtime speed of the uc/lc/ucfirst/lcfirst functions. # See HINT_UNI_8_BIT in perl.h. our $hint_uni8bit = 0x00000800; # TODO: # - think about versioned features (use feature switch => 2) =head1 NAME feature - Perl pragma to enable new features =head1 SYNOPSIS use feature qw(say switch); given ($foo) { when (1) { say "\$foo == 1" } when ([2,3]) { say "\$foo == 2 \|\| \$foo == 3" } when (/^a[bc]d$/) { say "\$foo eq 'abd' \|\| \$foo eq 'acd'" } when ($_ > 100) { say "\$foo > 100" } default { say "None of the above" } } use feature ':5.10'; # loads all features available in perl 5.10 use v5.10; # implicitly loads :5.10 feature bundle =head1 DESCRIPTION It is usually impossible to add new syntax to Perl without breaking some existing programs. This pragma provides a way to minimize that risk. New syntactic constructs, or new semantic meanings to older constructs, can be enabled by C<use feature 'foo'>, and will be parsed only when the appropriate feature pragma is in scope. (Nevertheless, the C<CORE::> prefix provides access to all Perl keywords, regardless of this pragma.) =head2 Lexical effect Like other pragmas (C<use strict>, for example), features have a lexical effect. C<use feature qw(foo)> will only make the feature "foo" available from that point to the end of the enclosing block. { use feature 'say'; say "say is available here"; } print "But not here.\n"; =head2 C<no feature> Features can also be turned off by using C<no feature "foo">. This too has lexical effect. use feature 'say'; say "say is available here"; { no feature 'say'; print "But not here.\n"; } say "Yet it is here."; C<no feature> with no features specified will reset to the default group. To disable I<all> features (an unusual request!) use C<no feature ':all'>. =head1 AVAILABLE FEATURES =head2 The 'say' feature C<use feature 'say'> tells the compiler to enable the Perl 6 style C<say> function. See L<perlfunc/say> for details. This feature is available starting with Perl 5.10. =head2 The 'state' feature C<use feature 'state'> tells the compiler to enable C<state> variables. See L<perlsub/"Persistent Private Variables"> for details. This feature is available starting with Perl 5.10. =head2 The 'switch' feature B<WARNING>: Because the L<smartmatch operator\|perlop/"Smartmatch Operator"> is experimental, Perl will warn when you use this feature, unless you have explicitly disabled the warning: no warnings "experimental::smartmatch"; C<use feature 'switch'> tells the compiler to enable the Perl 6 given/when construct. See L<perlsyn/"Switch Statements"> for details. This feature is available starting with Perl 5.10. =head2 The 'unicode_strings' feature C<use feature 'unicode_strings'> tells the compiler to use Unicode rules in all string operations executed within its scope (unless they are also within the scope of either C<use locale> or C<use bytes>). The same applies to all regular expressions compiled within the scope, even if executed outside it. It does not change the internal representation of strings, but only how they are interpreted. C<no feature 'unicode_strings'> tells the compiler to use the traditional Perl rules wherein the native character set rules is used unless it is clear to Perl that Unicode is desired. This can lead to some surprises when the behavior suddenly changes. (See L<perlunicode/The "Unicode Bug"> for details.) For this reason, if you are potentially using Unicode in your program, the C<use feature 'unicode_strings'> subpragma is B<strongly> recommended. This feature is available starting with Perl 5.12; was almost fully implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>; was extended further in Perl 5.26 to cover L<the range operator\|perlop/Range Operators>; and was extended again in Perl 5.28 to cover L<special-cased whitespace splitting\|perlfunc/split>. =head2 The 'unicode_eval' and 'evalbytes' features Together, these two features are intended to replace the legacy string C<eval> function, which behaves problematically in some instances. They are available starting with Perl 5.16, and are enabled by default by a S<C<use 5.16>> or higher declaration. C<unicode_eval> changes the behavior of plain string C<eval> to work more consistently, especially in the Unicode world. Certain (mis)behaviors couldn't be changed without breaking some things that had come to rely on them, so the feature can be enabled and disabled. Details are at L<perlfunc/Under the "unicode_eval" feature>. C<evalbytes> is like string C<eval>, but operating on a byte stream that is not UTF-8 encoded. Details are at L<perlfunc/evalbytes EXPR>. Without a S<C<use feature 'evalbytes'>> nor a S<C<use v5.16>> (or higher) declaration in the current scope, you can still access it by instead writing C<CORE::evalbytes>. =head2 The 'current_sub' feature This provides the C<__SUB__> token that returns a reference to the current subroutine or C<undef> outside of a subroutine. This feature is available starting with Perl 5.16. =head2 The 'array_base' feature This feature supported the legacy C<$[> variable. See L<perlvar/$[>. It was on by default but disabled under C<use v5.16> (see L</IMPLICIT LOADING>, below) and unavailable since perl 5.30. This feature is available under this name starting with Perl 5.16. In previous versions, it was simply on all the time, and this pragma knew nothing about it. =head2 The 'fc' feature C<use feature 'fc'> tells the compiler to enable the C<fc> function, which implements Unicode casefolding. See L<perlfunc/fc> for details. This feature is available from Perl 5.16 onwards. =head2 The 'lexical_subs' feature In Perl versions prior to 5.26, this feature enabled declaration of subroutines via C<my sub foo>, C<state sub foo> and C<our sub foo> syntax. See L<perlsub/Lexical Subroutines> for details. This feature is available from Perl 5.18 onwards. From Perl 5.18 to 5.24, it was classed as experimental, and Perl emitted a warning for its usage, except when explicitly disabled: no warnings "experimental::lexical_subs"; As of Perl 5.26, use of this feature no longer triggers a warning, though the C<experimental::lexical_subs> warning category still exists (for compatibility with code that disables it). In addition, this syntax is not only no longer experimental, but it is enabled for all Perl code, regardless of what feature declarations are in scope. =head2 The 'postderef' and 'postderef_qq' features The 'postderef_qq' feature extends the applicability of L<postfix dereference syntax\|perlref/Postfix Dereference Syntax> so that postfix array and scalar dereference are available in double-quotish interpolations. For example, it makes the following two statements equivalent: my $s = "[@{ $h->{a} }]"; my $s = "[$h->{a}->@]"; This feature is available from Perl 5.20 onwards. In Perl 5.20 and 5.22, it was classed as experimental, and Perl emitted a warning for its usage, except when explicitly disabled: no warnings "experimental::postderef"; As of Perl 5.24, use of this feature no longer triggers a warning, though the C<experimental::postderef> warning category still exists (for compatibility with code that disables it). The 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable postfix dereference syntax outside double-quotish interpolations. In those versions, using it triggered the C<experimental::postderef> warning in the same way as the 'postderef_qq' feature did. As of Perl 5.24, this syntax is not only no longer experimental, but it is enabled for all Perl code, regardless of what feature declarations are in scope. =head2 The 'signatures' feature B<WARNING>: This feature is still experimental and the implementation may change in future versions of Perl. For this reason, Perl will warn when you use the feature, unless you have explicitly disabled the warning: no warnings "experimental::signatures"; This enables unpacking of subroutine arguments into lexical variables by syntax such as sub foo ($left, $right) { return $left + $right; } See L<perlsub/Signatures> for details. This feature is available from Perl 5.20 onwards. =head2 The 'refaliasing' feature B<WARNING>: This feature is still experimental and the implementation may change in future versions of Perl. For this reason, Perl will warn when you use the feature, unless you have explicitly disabled the warning: no warnings "experimental::refaliasing"; This enables aliasing via assignment to references: \$a = \$b; # $a and $b now point to the same scalar \@a = \@b; # to the same array \%a = \%b; \&a = \&b; foreach \%hash (@array_of_hash_refs) { ... } See L<perlref/Assigning to References> for details. This feature is available from Perl 5.22 onwards. =head2 The 'bitwise' feature This makes the four standard bitwise operators (C<& \| ^ ~>) treat their operands consistently as numbers, and introduces four new dotted operators (C<&. \|. ^. ~.>) that treat their operands consistently as strings. The same applies to the assignment variants (C<&= \|= ^= &.= \|.= ^.=>). See L<perlop/Bitwise String Operators> for details. This feature is available from Perl 5.22 onwards. Starting in Perl 5.28, C<use v5.28> will enable the feature. Before 5.28, it was still experimental and would emit a warning in the "experimental::bitwise" category. =head2 The 'declared_refs' feature B<WARNING>: This feature is still experimental and the implementation may change in future versions of Perl. For this reason, Perl will warn when you use the feature, unless you have explicitly disabled the warning: no warnings "experimental::declared_refs"; This allows a reference to a variable to be declared with C<my>, C<state>, our C<our>, or localized with C<local>. It is intended mainly for use in conjunction with the "refaliasing" feature. See L<perlref/Declaring a Reference to a Variable> for examples. This feature is available from Perl 5.26 onwards. =head2 The 'isa' feature This allows the use of the C<isa> infix operator, which tests whether the scalar given by the left operand is an object of the class given by the right operand. See L<perlop/Class Instance Operator> for more details. This feature is available from Perl 5.32 onwards. =head2 The 'indirect' feature This feature allows the use of L<indirect object syntax\|perlobj/Indirect Object Syntax> for method calls, e.g. C<new Foo 1, 2;>. It is enabled by default, but can be turned off to disallow indirect object syntax. This feature is available under this name from Perl 5.32 onwards. In previous versions, it was simply on all the time. To disallow (or warn on) indirect object syntax on older Perls, see the L<indirect> CPAN module. =head1 FEATURE BUNDLES It's possible to load multiple features together, using a I<feature bundle>. The name of a feature bundle is prefixed with a colon, to distinguish it from an actual feature. use feature ":5.10"; The following feature bundles are available: bundle features included --------- ----------------- :default indirect :5.10 say state switch indirect :5.12 say state switch unicode_strings indirect :5.14 say state switch unicode_strings indirect :5.16 say state switch unicode_strings unicode_eval evalbytes current_sub fc indirect :5.18 say state switch unicode_strings unicode_eval evalbytes current_sub fc indirect :5.20 say state switch unicode_strings unicode_eval evalbytes current_sub fc indirect :5.22 say state switch unicode_strings unicode_eval evalbytes current_sub fc indirect :5.24 say state switch unicode_strings unicode_eval evalbytes current_sub fc postderef_qq indirect :5.26 say state switch unicode_strings unicode_eval evalbytes current_sub fc postderef_qq indirect :5.28 say state switch unicode_strings unicode_eval evalbytes current_sub fc postderef_qq bitwise indirect :5.30 say state switch unicode_strings unicode_eval evalbytes current_sub fc postderef_qq bitwise indirect :5.32 say state switch unicode_strings unicode_eval evalbytes current_sub fc postderef_qq bitwise indirect The C<:default> bundle represents the feature set that is enabled before any C<use feature> or C<no feature> declaration. Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has no effect. Feature bundles are guaranteed to be the same for all sub-versions. use feature ":5.14.0"; # same as ":5.14" use feature ":5.14.1"; # same as ":5.14" =head1 IMPLICIT LOADING Instead of loading feature bundles by name, it is easier to let Perl do implicit loading of a feature bundle for you. There are two ways to load the C<feature> pragma implicitly: =over 4 =item By using the C<-E> switch on the Perl command-line instead of C<-e>. That will enable the feature bundle for that version of Perl in the main compilation unit (that is, the one-liner that follows C<-E>). =item * By explicitly requiring a minimum Perl version number for your program, with the C<use VERSION> construct. That is, use v5.10.0; will do an implicit no feature ':all'; use feature ':5.10'; and so on. Note how the trailing sub-version is automatically stripped from the version. But to avoid portability warnings (see L<perlfunc/use>), you may prefer: use 5.010; with the same effect. If the required version is older than Perl 5.10, the ":default" feature bundle is automatically loaded instead. Unlike C<use feature ":5.12">, saying C<use v5.12> (or any higher version) also does the equivalent of C<use strict>; see L<perlfunc/use> for details. =back =cut sub import { shift; if (!@_) { croak("No features specified"); } __common(1, @_); } sub unimport { shift; # A bare C<no feature> should reset to the default bundle if (!@_) { $^H &= ~($hint_uni8bit\|$hint_mask); return; } __common(0, @_); } sub __common { my $import = shift; my $bundle_number = $^H & $hint_mask; my $features = $bundle_number != $hint_mask && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]}; if ($features) { # Features are enabled implicitly via bundle hints. # Delete any keys that may be left over from last time. delete @^H{ values(%feature) }; $^H \|= $hint_mask; for (@$features) { $^H{$feature{$_}} = 1; $^H \|= $hint_uni8bit if $_ eq 'unicode_strings'; } } while (@_) { my $name = shift; if (substr($name, 0, 1) eq ":") { my $v = substr($name, 1); if (!exists $feature_bundle{$v}) { $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/; if (!exists $feature_bundle{$v}) { unknown_feature_bundle(substr($name, 1)); } } unshift @_, @{$feature_bundle{$v}}; next; } if (!exists $feature{$name}) { if (exists $noops{$name}) { next; } if (!$import && exists $removed{$name}) { next; } unknown_feature($name); } if ($import) { $^H{$feature{$name}} = 1; $^H \|= $hint_uni8bit if $name eq 'unicode_strings'; } else { delete $^H{$feature{$name}}; $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings'; } } } sub unknown_feature { my $feature = shift; croak(sprintf('Feature "%s" is not supported by Perl %vd', $feature, $^V)); } sub unknown_feature_bundle { my $feature = shift; croak(sprintf('Feature bundle "%s" is not supported by Perl %vd', $feature, $^V)); } sub croak { require Carp; Carp::croak(@_); } 1; # ex: set ro:	18.56 KB	2025-07-28 03:53
📄 if.pm package if; $VERSION = '0.0608'; sub work { my $method = shift() ? 'import' : 'unimport'; unless (@_ >= 2) { my $type = ($method eq 'import') ? 'use' : 'no'; die "Too few arguments to '$type if' (some code returning an empty list in list context?)" } return unless shift; # CONDITION my $p = $_[0]; # PACKAGE (my $file = "$p.pm") =~ s!::!/!g; require $file; # Works even if $_[0] is a keyword (like open) my $m = $p->can($method); goto &$m if $m; } sub import { shift; unshift @_, 1; goto &work } sub unimport { shift; unshift @_, 0; goto &work } 1; __END__ =head1 NAME if - C<use> a Perl module if a condition holds =head1 SYNOPSIS use if CONDITION, "MODULE", ARGUMENTS; no if CONDITION, "MODULE", ARGUMENTS; =head1 DESCRIPTION =head2 C<use if> The C<if> module is used to conditionally load another module. The construct: use if CONDITION, "MODULE", ARGUMENTS; ... will load C<MODULE> only if C<CONDITION> evaluates to true; it has no effect if C<CONDITION> evaluates to false. (The module name, assuming it contains at least one C<::>, must be quoted when C<'use strict "subs";'> is in effect.) If the CONDITION does evaluate to true, then the above line has the same effect as: use MODULE ARGUMENTS; For example, the F<Unicode::UCD> module's F<charinfo> function will use two functions from F<Unicode::Normalize> only if a certain condition is met: use if defined &DynaLoader::boot_DynaLoader, "Unicode::Normalize" => qw(getCombinClass NFD); Suppose you wanted C<ARGUMENTS> to be an empty list, I<i.e.>, to have the effect of: use MODULE (); You can't do this with the C<if> pragma; however, you can achieve exactly this effect, at compile time, with: BEGIN { require MODULE if CONDITION } =head2 C<no if> The C<no if> construct is mainly used to deactivate categories of warnings when those categories would produce superfluous output under specified versions of F<perl>. For example, the C<redundant> category of warnings was introduced in Perl-5.22. This warning flags certain instances of superfluous arguments to C<printf> and C<sprintf>. But if your code was running warnings-free on earlier versions of F<perl> and you don't care about C<redundant> warnings in more recent versions, you can call: use warnings; no if $] >= 5.022, q\|warnings\|, qw(redundant); my $test = { fmt => "%s", args => [ qw( x y ) ] }; my $result = sprintf $test->{fmt}, @{$test->{args}}; The C<no if> construct assumes that a module or pragma has correctly implemented an C<unimport()> method -- but most modules and pragmata have not. That explains why the C<no if> construct is of limited applicability. =head1 BUGS The current implementation does not allow specification of the required version of the module. =head1 SEE ALSO L<Module::Requires> can be used to conditionally load one or modules, with constraints based on the version of the module. Unlike C<if> though, L<Module::Requires> is not a core module. L<Module::Load::Conditional> provides a number of functions you can use to query what modules are available, and then load one or more of them at runtime. The L<provide> module from CPAN can be used to select one of several possible modules to load based on the version of Perl that is running. =head1 AUTHOR Ilya Zakharevich L<mailto:ilyaz@cpan.org>. =head1 COPYRIGHT AND LICENCE This software is copyright (c) 2002 by Ilya Zakharevich. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut	3.53 KB	2025-07-28 03:54
📄 integer.pm package integer; our $VERSION = '1.01'; =head1 NAME integer - Perl pragma to use integer arithmetic instead of floating point =head1 SYNOPSIS use integer; $x = 10/3; # $x is now 3, not 3.33333333333333333 =head1 DESCRIPTION This tells the compiler to use integer operations from here to the end of the enclosing BLOCK. On many machines, this doesn't matter a great deal for most computations, but on those without floating point hardware, it can make a big difference in performance. Note that this only affects how most of the arithmetic and relational B<operators> handle their operands and results, and B<not> how all numbers everywhere are treated. Specifically, C<use integer;> has the effect that before computing the results of the arithmetic operators (+, -, , /, %, +=, -=, =, /=, %=, and unary minus), the comparison operators (<, <=, >, >=, ==, !=, <=>), and the bitwise operators (\|, &, ^, <<, >>, \|=, &=, ^=, <<=, >>=), the operands have their fractional portions truncated (or floored), and the result will have its fractional portion truncated as well. In addition, the range of operands and results is restricted to that of familiar two's complement integers, i.e., -(231) .. (231-1) on 32-bit architectures, and -(263) .. (263-1) on 64-bit architectures. For example, this code use integer; $x = 5.8; $y = 2.5; $z = 2.7; $a = 2*31 - 1; # Largest positive integer on 32-bit machines $, = ", "; print $x, -$x, $x+$y, $x-$y, $x/$y, $x$y, $y==$z, $a, $a+1; will print: 5.8, -5, 7, 3, 2, 10, 1, 2147483647, -2147483648 Note that $x is still printed as having its true non-integer value of 5.8 since it wasn't operated on. And note too the wrap-around from the largest positive integer to the largest negative one. Also, arguments passed to functions and the values returned by them are B<not> affected by C<use integer;>. E.g., srand(1.5); $, = ", "; print sin(.5), cos(.5), atan2(1,2), sqrt(2), rand(10); will give the same result with or without C<use integer;> The power operator C<> is also not affected, so that 2 .5 is always the square root of 2. Now, it so happens that the pre- and post- increment and decrement operators, ++ and --, are not affected by C<use integer;> either. Some may rightly consider this to be a bug -- but at least it's a long-standing one. Finally, C<use integer;> also has an additional affect on the bitwise operators. Normally, the operands and results are treated as B<unsigned> integers, but with C<use integer;> the operands and results are B<signed>. This means, among other things, that ~0 is -1, and -2 & -5 is -6. Internally, native integer arithmetic (as provided by your C compiler) is used. This means that Perl's own semantics for arithmetic operations may not be preserved. One common source of trouble is the modulus of negative numbers, which Perl does one way, but your hardware may do another. % perl -le 'print (4 % -3)' -2 % perl -Minteger -le 'print (4 % -3)' 1 See L<perlmodlib/"Pragmatic Modules">, L<perlop/"Integer Arithmetic"> =cut $integer::hint_bits = 0x1; sub import { $^H \|= $integer::hint_bits; } sub unimport { $^H &= ~$integer::hint_bits; } 1;	3.18 KB	2025-07-28 03:53
📁 overload	-	2026-03-21 15:44
📄 overload.pm package overload; our $VERSION = '1.31'; %ops = ( with_assign => "+ - * / % ** << >> x .", assign => "+= -= = /= %= = <<= >>= x= .=", num_comparison => "< <= > >= == !=", '3way_comparison' => "<=> cmp", str_comparison => "lt le gt ge eq ne", binary => '& &= \| \|= ^ ^= &. &.= \|. \|.= ^. ^.=', unary => "neg ! ~ ~.", mutators => '++ --', func => "atan2 cos sin exp abs log sqrt int", conversion => 'bool "" 0+ qr', iterators => '<>', filetest => "-X", dereferencing => '${} @{} %{} &{} {}', matching => '~~', special => 'nomethod fallback =', ); my %ops_seen; @ops_seen{ map split(/ /), values %ops } = (); sub nil {} sub OVERLOAD { $package = shift; my %arg = @_; my $sub; {$package . "::(("} = \&nil; # Make it findable via fetchmethod. for (keys %arg) { if ($_ eq 'fallback') { for my $sym ({$package . "::()"}) { $sym = \&nil; # Make it findable via fetchmethod. $$sym = $arg{$_}; } } else { warnings::warnif("overload arg '$_' is invalid") unless exists $ops_seen{$_}; $sub = $arg{$_}; if (not ref $sub) { $ {$package . "::(" . $_} = $sub; $sub = \&nil; } #print STDERR "Setting '$ {'package'}::\cO$_' to \\&'$sub'.\n"; {$package . "::(" . $_} = \&{ $sub }; } } } sub import { $package = (caller())[0]; # {$package . "::OVERLOAD"} = \&OVERLOAD; shift; $package->overload::OVERLOAD(@_); } sub unimport { $package = (caller())[0]; shift; {$package . "::(("} = \&nil; for (@_) { warnings::warnif("overload arg '$_' is invalid") unless exists $ops_seen{$_}; delete $ {$package . "::"}{$_ eq 'fallback' ? '()' : "(" .$_}; } } sub Overloaded { my $package = shift; $package = ref $package if ref $package; mycan ($package, '()') \|\| mycan ($package, '(('); } sub ov_method { my $globref = shift; return undef unless $globref; my $sub = \&{$globref}; no overloading; return $sub if $sub != \&nil; return shift->can($ {$globref}); } sub OverloadedStringify { my $package = shift; $package = ref $package if ref $package; #$package->can('(""') ov_method mycan($package, '(""'), $package or ov_method mycan($package, '(0+'), $package or ov_method mycan($package, '(bool'), $package or ov_method mycan($package, '(nomethod'), $package; } sub Method { my $package = shift; if(ref $package) { local $@; local $!; require Scalar::Util; $package = Scalar::Util::blessed($package); return undef if !defined $package; } #my $meth = $package->can('(' . shift); ov_method mycan($package, '(' . shift), $package; #return $meth if $meth ne \&nil; #return $ {{$meth}}; } sub AddrRef { no overloading; "$_[0]"; } StrVal = AddrRef; sub mycan { # Real can would leave stubs. my ($package, $meth) = @_; local $@; local $!; require mro; my $mro = mro::get_linear_isa($package); foreach my $p (@$mro) { my $fqmeth = $p . q{::} . $meth; return \{$fqmeth} if defined &{$fqmeth}; } return undef; } %constants = ( 'integer' => 0x1000, # HINT_NEW_INTEGER 'float' => 0x2000, # HINT_NEW_FLOAT 'binary' => 0x4000, # HINT_NEW_BINARY 'q' => 0x8000, # HINT_NEW_STRING 'qr' => 0x10000, # HINT_NEW_RE ); use warnings::register; sub constant { # Arguments: what, sub while (@_) { if (@_ == 1) { warnings::warnif ("Odd number of arguments for overload::constant"); last; } elsif (!exists $constants {$_ [0]}) { warnings::warnif ("'$_[0]' is not an overloadable type"); } elsif (!ref $_ [1] \|\| "$_[1]" !~ /(^\|=)CODE$0x[0-9a-f]+$$/) { # Can't use C<ref $_[1] eq "CODE"> above as code references can be # blessed, and C<ref> would return the package the ref is blessed into. if (warnings::enabled) { $_ [1] = "undef" unless defined $_ [1]; warnings::warn ("'$_[1]' is not a code reference"); } } else { $^H{$_[0]} = $_[1]; $^H \|= $constants{$_[0]}; } shift, shift; } } sub remove_constant { # Arguments: what, sub while (@_) { delete $^H{$_[0]}; $^H &= ~ $constants{$_[0]}; shift, shift; } } 1; __END__ =head1 NAME overload - Package for overloading Perl operations =head1 SYNOPSIS package SomeThing; use overload '+' => \&myadd, '-' => \&mysub; # etc ... package main; $a = SomeThing->new( 57 ); $b = 5 + $a; ... if (overload::Overloaded $b) {...} ... $strval = overload::StrVal $b; =head1 DESCRIPTION This pragma allows overloading of Perl's operators for a class. To overload built-in functions, see L<perlsub/Overriding Built-in Functions> instead. =head2 Fundamentals =head3 Declaration Arguments of the C<use overload> directive are (key, value) pairs. For the full set of legal keys, see L</Overloadable Operations> below. Operator implementations (the values) can be subroutines, references to subroutines, or anonymous subroutines - in other words, anything legal inside a C<&{ ... }> call. Values specified as strings are interpreted as method names. Thus package Number; use overload "-" => "minus", "=" => \&muas, '""' => sub { ...; }; declares that subtraction is to be implemented by method C<minus()> in the class C<Number> (or one of its base classes), and that the function C<Number::muas()> is to be used for the assignment form of multiplication, C<=>. It also defines an anonymous subroutine to implement stringification: this is called whenever an object blessed into the package C<Number> is used in a string context (this subroutine might, for example, return the number as a Roman numeral). =head3 Calling Conventions and Magic Autogeneration The following sample implementation of C<minus()> (which assumes that C<Number> objects are simply blessed references to scalars) illustrates the calling conventions: package Number; sub minus { my ($self, $other, $swap) = @_; my $result = $$self - $other; # * $result = -$result if $swap; ref $result ? $result : bless \$result; } # * may recurse once - see table below Three arguments are passed to all subroutines specified in the C<use overload> directive (with exceptions - see below, particularly L</nomethod>). The first of these is the operand providing the overloaded operator implementation - in this case, the object whose C<minus()> method is being called. The second argument is the other operand, or C<undef> in the case of a unary operator. The third argument is set to TRUE if (and only if) the two operands have been swapped. Perl may do this to ensure that the first argument (C<$self>) is an object implementing the overloaded operation, in line with general object calling conventions. For example, if C<$x> and C<$y> are C<Number>s: operation \| generates a call to ============\|====================== $x - $y \| minus($x, $y, '') $x - 7 \| minus($x, 7, '') 7 - $x \| minus($x, 7, 1) Perl may also use C<minus()> to implement other operators which have not been specified in the C<use overload> directive, according to the rules for L</Magic Autogeneration> described later. For example, the C<use overload> above declared no subroutine for any of the operators C<-->, C<neg> (the overload key for unary minus), or C<-=>. Thus operation \| generates a call to ============\|====================== -$x \| minus($x, 0, 1) $x-- \| minus($x, 1, undef) $x -= 3 \| minus($x, 3, undef) Note the C<undef>s: where autogeneration results in the method for a standard operator which does not change either of its operands, such as C<->, being used to implement an operator which changes the operand ("mutators": here, C<--> and C<-=>), Perl passes undef as the third argument. This still evaluates as FALSE, consistent with the fact that the operands have not been swapped, but gives the subroutine a chance to alter its behaviour in these cases. In all the above examples, C<minus()> is required only to return the result of the subtraction: Perl takes care of the assignment to $x. In fact, such methods should I<not> modify their operands, even if C<undef> is passed as the third argument (see L</Overloadable Operations>). The same is not true of implementations of C<++> and C<-->: these are expected to modify their operand. An appropriate implementation of C<--> might look like use overload '--' => "decr", # ... sub decr { --${$_[0]}; } If the "bitwise" feature is enabled (see L<feature>), a fifth TRUE argument is passed to subroutines handling C<&>, C<\|>, C<^> and C<~>. This indicates that the caller is expecting numeric behaviour. The fourth argument will be C<undef>, as that position (C<$_[3]>) is reserved for use by L</nomethod>. =head3 Mathemagic, Mutators, and Copy Constructors The term 'mathemagic' describes the overloaded implementation of mathematical operators. Mathemagical operations raise an issue. Consider the code: $a = $b; --$a; If C<$a> and C<$b> are scalars then after these statements $a == $b - 1 An object, however, is a reference to blessed data, so if C<$a> and C<$b> are objects then the assignment C<$a = $b> copies only the reference, leaving C<$a> and C<$b> referring to the same object data. One might therefore expect the operation C<--$a> to decrement C<$b> as well as C<$a>. However, this would not be consistent with how we expect the mathematical operators to work. Perl resolves this dilemma by transparently calling a copy constructor before calling a method defined to implement a mutator (C<-->, C<+=>, and so on.). In the above example, when Perl reaches the decrement statement, it makes a copy of the object data in C<$a> and assigns to C<$a> a reference to the copied data. Only then does it call C<decr()>, which alters the copied data, leaving C<$b> unchanged. Thus the object metaphor is preserved as far as possible, while mathemagical operations still work according to the arithmetic metaphor. Note: the preceding paragraph describes what happens when Perl autogenerates the copy constructor for an object based on a scalar. For other cases, see L</Copy Constructor>. =head2 Overloadable Operations The complete list of keys that can be specified in the C<use overload> directive are given, separated by spaces, in the values of the hash C<%overload::ops>: with_assign => '+ - * / % ** << >> x .', assign => '+= -= = /= %= = <<= >>= x= .=', num_comparison => '< <= > >= == !=', '3way_comparison'=> '<=> cmp', str_comparison => 'lt le gt ge eq ne', binary => '& &= \| \|= ^ ^= &. &.= \|. \|.= ^. ^.=', unary => 'neg ! ~ ~.', mutators => '++ --', func => 'atan2 cos sin exp abs log sqrt int', conversion => 'bool "" 0+ qr', iterators => '<>', filetest => '-X', dereferencing => '${} @{} %{} &{} {}', matching => '~~', special => 'nomethod fallback =' Most of the overloadable operators map one-to-one to these keys. Exceptions, including additional overloadable operations not apparent from this hash, are included in the notes which follow. This list is subject to growth over time. A warning is issued if an attempt is made to register an operator not found above. =over 5 =item * C<not> The operator C<not> is not a valid key for C<use overload>. However, if the operator C<!> is overloaded then the same implementation will be used for C<not> (since the two operators differ only in precedence). =item * C<neg> The key C<neg> is used for unary minus to disambiguate it from binary C<->. =item * C<++>, C<--> Assuming they are to behave analogously to Perl's C<++> and C<-->, overloaded implementations of these operators are required to mutate their operands. No distinction is made between prefix and postfix forms of the increment and decrement operators: these differ only in the point at which Perl calls the associated subroutine when evaluating an expression. =item * I<Assignments> += -= = /= %= = <<= >>= x= .= &= \|= ^= &.= \|.= ^.= Simple assignment is not overloadable (the C<'='> key is used for the L</Copy Constructor>). Perl does have a way to make assignments to an object do whatever you want, but this involves using tie(), not overload - see L<perlfunc/tie> and the L</COOKBOOK> examples below. The subroutine for the assignment variant of an operator is required only to return the result of the operation. It is permitted to change the value of its operand (this is safe because Perl calls the copy constructor first), but this is optional since Perl assigns the returned value to the left-hand operand anyway. An object that overloads an assignment operator does so only in respect of assignments to that object. In other words, Perl never calls the corresponding methods with the third argument (the "swap" argument) set to TRUE. For example, the operation $a = $b cannot lead to C<$b>'s implementation of C<=> being called, even if C<$a> is a scalar. (It can, however, generate a call to C<$b>'s method for C<>). =item * I<Non-mutators with a mutator variant> + - * / % ** << >> x . & \| ^ &. \|. ^. As described L<above\|"Calling Conventions and Magic Autogeneration">, Perl may call methods for operators like C<+> and C<&> in the course of implementing missing operations like C<++>, C<+=>, and C<&=>. While these methods may detect this usage by testing the definedness of the third argument, they should in all cases avoid changing their operands. This is because Perl does not call the copy constructor before invoking these methods. =item * C<int> Traditionally, the Perl function C<int> rounds to 0 (see L<perlfunc/int>), and so for floating-point-like types one should follow the same semantic. =item * I<String, numeric, boolean, and regexp conversions> "" 0+ bool These conversions are invoked according to context as necessary. For example, the subroutine for C<'""'> (stringify) may be used where the overloaded object is passed as an argument to C<print>, and that for C<'bool'> where it is tested in the condition of a flow control statement (like C<while>) or the ternary C<?:> operation. Of course, in contexts like, for example, C<$obj + 1>, Perl will invoke C<$obj>'s implementation of C<+> rather than (in this example) converting C<$obj> to a number using the numify method C<'0+'> (an exception to this is when no method has been provided for C<'+'> and L</fallback> is set to TRUE). The subroutines for C<'""'>, C<'0+'>, and C<'bool'> can return any arbitrary Perl value. If the corresponding operation for this value is overloaded too, the operation will be called again with this value. As a special case if the overload returns the object itself then it will be used directly. An overloaded conversion returning the object is probably a bug, because you're likely to get something that looks like C<YourPackage=HASH(0x8172b34)>. qr The subroutine for C<'qr'> is used wherever the object is interpolated into or used as a regexp, including when it appears on the RHS of a C<=~> or C<!~> operator. C<qr> must return a compiled regexp, or a ref to a compiled regexp (such as C<qr//> returns), and any further overloading on the return value will be ignored. =item * I<Iteration> If C<E<lt>E<gt>> is overloaded then the same implementation is used for both the I<read-filehandle> syntax C<E<lt>$varE<gt>> and I<globbing> syntax C<E<lt>${var}E<gt>>. =item * I<File tests> The key C<'-X'> is used to specify a subroutine to handle all the filetest operators (C<-f>, C<-x>, and so on: see L<perlfunc/-X> for the full list); it is not possible to overload any filetest operator individually. To distinguish them, the letter following the '-' is passed as the second argument (that is, in the slot that for binary operators is used to pass the second operand). Calling an overloaded filetest operator does not affect the stat value associated with the special filehandle C<_>. It still refers to the result of the last C<stat>, C<lstat> or unoverloaded filetest. This overload was introduced in Perl 5.12. =item * I<Matching> The key C<"~~"> allows you to override the smart matching logic used by the C<~~> operator and the switch construct (C<given>/C<when>). See L<perlsyn/Switch Statements> and L<feature>. Unusually, the overloaded implementation of the smart match operator does not get full control of the smart match behaviour. In particular, in the following code: package Foo; use overload '~~' => 'match'; my $obj = Foo->new(); $obj ~~ [ 1,2,3 ]; the smart match does I<not> invoke the method call like this: $obj->match([1,2,3],0); rather, the smart match distributive rule takes precedence, so $obj is smart matched against each array element in turn until a match is found, so you may see between one and three of these calls instead: $obj->match(1,0); $obj->match(2,0); $obj->match(3,0); Consult the match table in L<perlop/"Smartmatch Operator"> for details of when overloading is invoked. =item * I<Dereferencing> ${} @{} %{} &{} {} If these operators are not explicitly overloaded then they work in the normal way, yielding the underlying scalar, array, or whatever stores the object data (or the appropriate error message if the dereference operator doesn't match it). Defining a catch-all C<'nomethod'> (see L<below\|/nomethod>) makes no difference to this as the catch-all function will not be called to implement a missing dereference operator. If a dereference operator is overloaded then it must return a I<reference> of the appropriate type (for example, the subroutine for key C<'${}'> should return a reference to a scalar, not a scalar), or another object which overloads the operator: that is, the subroutine only determines what is dereferenced and the actual dereferencing is left to Perl. As a special case, if the subroutine returns the object itself then it will not be called again - avoiding infinite recursion. =item I<Special> nomethod fallback = See L</Special Keys for C<use overload>>. =back =head2 Magic Autogeneration If a method for an operation is not found then Perl tries to autogenerate a substitute implementation from the operations that have been defined. Note: the behaviour described in this section can be disabled by setting C<fallback> to FALSE (see L</fallback>). In the following tables, numbers indicate priority. For example, the table below states that, if no implementation for C<'!'> has been defined then Perl will implement it using C<'bool'> (that is, by inverting the value returned by the method for C<'bool'>); if boolean conversion is also unimplemented then Perl will use C<'0+'> or, failing that, C<'""'>. operator \| can be autogenerated from \| \| 0+ "" bool . x =========\|========================== 0+ \| 1 2 "" \| 1 2 bool \| 1 2 int \| 1 2 3 ! \| 2 3 1 qr \| 2 1 3 . \| 2 1 3 x \| 2 1 3 .= \| 3 2 4 1 x= \| 3 2 4 1 <> \| 2 1 3 -X \| 2 1 3 Note: The iterator (C<'E<lt>E<gt>'>) and file test (C<'-X'>) operators work as normal: if the operand is not a blessed glob or IO reference then it is converted to a string (using the method for C<'""'>, C<'0+'>, or C<'bool'>) to be interpreted as a glob or filename. operator \| can be autogenerated from \| \| < <=> neg -= - =========\|========================== neg \| 1 -= \| 1 -- \| 1 2 abs \| a1 a2 b1 b2 [] < \| 1 <= \| 1 > \| 1 >= \| 1 == \| 1 != \| 1 one from [a1, a2] and one from [b1, b2] Just as numeric comparisons can be autogenerated from the method for C<< '<=>' >>, string comparisons can be autogenerated from that for C<'cmp'>: operators \| can be autogenerated from ====================\|=========================== lt gt le ge eq ne \| cmp Similarly, autogeneration for keys C<'+='> and C<'++'> is analogous to C<'-='> and C<'--'> above: operator \| can be autogenerated from \| \| += + =========\|========================== += \| 1 ++ \| 1 2 And other assignment variations are analogous to C<'+='> and C<'-='> (and similar to C<'.='> and C<'x='> above): operator \|\| = /= %= = <<= >>= &= ^= \|= &.= ^.= \|.= -------------------\|\|------------------------------------------- autogenerated from \|\| / % ** << >> & ^ \| &. ^. \|. Note also that the copy constructor (key C<'='>) may be autogenerated, but only for objects based on scalars. See L</Copy Constructor>. =head3 Minimal Set of Overloaded Operations Since some operations can be automatically generated from others, there is a minimal set of operations that need to be overloaded in order to have the complete set of overloaded operations at one's disposal. Of course, the autogenerated operations may not do exactly what the user expects. The minimal set is: + - * / % ** << >> x <=> cmp & \| ^ ~ &. \|. ^. ~. atan2 cos sin exp log sqrt int "" 0+ bool ~~ Of the conversions, only one of string, boolean or numeric is needed because each can be generated from either of the other two. =head2 Special Keys for C<use overload> =head3 C<nomethod> The C<'nomethod'> key is used to specify a catch-all function to be called for any operator that is not individually overloaded. The specified function will be passed four parameters. The first three arguments coincide with those that would have been passed to the corresponding method if it had been defined. The fourth argument is the C<use overload> key for that missing method. If the "bitwise" feature is enabled (see L<feature>), a fifth TRUE argument is passed to subroutines handling C<&>, C<\|>, C<^> and C<~> to indicate that the caller is expecting numeric behaviour. For example, if C<$a> is an object blessed into a package declaring use overload 'nomethod' => 'catch_all', # ... then the operation 3 + $a could (unless a method is specifically declared for the key C<'+'>) result in a call catch_all($a, 3, 1, '+') See L</How Perl Chooses an Operator Implementation>. =head3 C<fallback> The value assigned to the key C<'fallback'> tells Perl how hard it should try to find an alternative way to implement a missing operator. =over =item * defined, but FALSE use overload "fallback" => 0, # ... ; This disables L</Magic Autogeneration>. =item * C<undef> In the default case where no value is explicitly assigned to C<fallback>, magic autogeneration is enabled. =item * TRUE The same as for C<undef>, but if a missing operator cannot be autogenerated then, instead of issuing an error message, Perl is allowed to revert to what it would have done for that operator if there had been no C<use overload> directive. Note: in most cases, particularly the L</Copy Constructor>, this is unlikely to be appropriate behaviour. =back See L</How Perl Chooses an Operator Implementation>. =head3 Copy Constructor As mentioned L<above\|"Mathemagic, Mutators, and Copy Constructors">, this operation is called when a mutator is applied to a reference that shares its object with some other reference. For example, if C<$b> is mathemagical, and C<'++'> is overloaded with C<'incr'>, and C<'='> is overloaded with C<'clone'>, then the code $a = $b; # ... (other code which does not modify $a or $b) ... ++$b; would be executed in a manner equivalent to $a = $b; # ... $b = $b->clone(undef, ""); $b->incr(undef, ""); Note: =over =item * The subroutine for C<'='> does not overload the Perl assignment operator: it is used only to allow mutators to work as described here. (See L</Assignments> above.) =item * As for other operations, the subroutine implementing '=' is passed three arguments, though the last two are always C<undef> and C<''>. =item * The copy constructor is called only before a call to a function declared to implement a mutator, for example, if C<++$b;> in the code above is effected via a method declared for key C<'++'> (or 'nomethod', passed C<'++'> as the fourth argument) or, by autogeneration, C<'+='>. It is not called if the increment operation is effected by a call to the method for C<'+'> since, in the equivalent code, $a = $b; $b = $b + 1; the data referred to by C<$a> is unchanged by the assignment to C<$b> of a reference to new object data. =item * The copy constructor is not called if Perl determines that it is unnecessary because there is no other reference to the data being modified. =item * If C<'fallback'> is undefined or TRUE then a copy constructor can be autogenerated, but only for objects based on scalars. In other cases it needs to be defined explicitly. Where an object's data is stored as, for example, an array of scalars, the following might be appropriate: use overload '=' => sub { bless [ @{$_[0]} ] }, # ... =item * If C<'fallback'> is TRUE and no copy constructor is defined then, for objects not based on scalars, Perl may silently fall back on simple assignment - that is, assignment of the object reference. In effect, this disables the copy constructor mechanism since no new copy of the object data is created. This is almost certainly not what you want. (It is, however, consistent: for example, Perl's fallback for the C<++> operator is to increment the reference itself.) =back =head2 How Perl Chooses an Operator Implementation Which is checked first, C<nomethod> or C<fallback>? If the two operands of an operator are of different types and both overload the operator, which implementation is used? The following are the precedence rules: =over =item 1. If the first operand has declared a subroutine to overload the operator then use that implementation. =item 2. Otherwise, if fallback is TRUE or undefined for the first operand then see if the L<rules for autogeneration\|"Magic Autogeneration"> allows another of its operators to be used instead. =item 3. Unless the operator is an assignment (C<+=>, C<-=>, etc.), repeat step (1) in respect of the second operand. =item 4. Repeat Step (2) in respect of the second operand. =item 5. If the first operand has a "nomethod" method then use that. =item 6. If the second operand has a "nomethod" method then use that. =item 7. If C<fallback> is TRUE for both operands then perform the usual operation for the operator, treating the operands as numbers, strings, or booleans as appropriate for the operator (see note). =item 8. Nothing worked - die. =back Where there is only one operand (or only one operand with overloading) the checks in respect of the other operand above are skipped. There are exceptions to the above rules for dereference operations (which, if Step 1 fails, always fall back to the normal, built-in implementations - see Dereferencing), and for C<~~> (which has its own set of rules - see C<Matching> under L</Overloadable Operations> above). Note on Step 7: some operators have a different semantic depending on the type of their operands. As there is no way to instruct Perl to treat the operands as, e.g., numbers instead of strings, the result here may not be what you expect. See L</BUGS AND PITFALLS>. =head2 Losing Overloading The restriction for the comparison operation is that even if, for example, C<cmp> should return a blessed reference, the autogenerated C<lt> function will produce only a standard logical value based on the numerical value of the result of C<cmp>. In particular, a working numeric conversion is needed in this case (possibly expressed in terms of other conversions). Similarly, C<.=> and C<x=> operators lose their mathemagical properties if the string conversion substitution is applied. When you chop() a mathemagical object it is promoted to a string and its mathemagical properties are lost. The same can happen with other operations as well. =head2 Inheritance and Overloading Overloading respects inheritance via the @ISA hierarchy. Inheritance interacts with overloading in two ways. =over =item Method names in the C<use overload> directive If C<value> in use overload key => value; is a string, it is interpreted as a method name - which may (in the usual way) be inherited from another class. =item Overloading of an operation is inherited by derived classes Any class derived from an overloaded class is also overloaded and inherits its operator implementations. If the same operator is overloaded in more than one ancestor then the implementation is determined by the usual inheritance rules. For example, if C<A> inherits from C<B> and C<C> (in that order), C<B> overloads C<+> with C<\&D::plus_sub>, and C<C> overloads C<+> by C<"plus_meth">, then the subroutine C<D::plus_sub> will be called to implement operation C<+> for an object in package C<A>. =back Note that in Perl version prior to 5.18 inheritance of the C<fallback> key was not governed by the above rules. The value of C<fallback> in the first overloaded ancestor was used. This was fixed in 5.18 to follow the usual rules of inheritance. =head2 Run-time Overloading Since all C<use> directives are executed at compile-time, the only way to change overloading during run-time is to eval 'use overload "+" => \&addmethod'; You can also use eval 'no overload "+", "--", "<="'; though the use of these constructs during run-time is questionable. =head2 Public Functions Package C<overload.pm> provides the following public functions: =over 5 =item overload::StrVal(arg) Gives the string value of C<arg> as in the absence of stringify overloading. If you are using this to get the address of a reference (useful for checking if two references point to the same thing) then you may be better off using C<Scalar::Util::refaddr()>, which is faster. =item overload::Overloaded(arg) Returns true if C<arg> is subject to overloading of some operations. =item overload::Method(obj,op) Returns C<undef> or a reference to the method that implements C<op>. =back =head2 Overloading Constants For some applications, the Perl parser mangles constants too much. It is possible to hook into this process via C<overload::constant()> and C<overload::remove_constant()> functions. These functions take a hash as an argument. The recognized keys of this hash are: =over 8 =item integer to overload integer constants, =item float to overload floating point constants, =item binary to overload octal and hexadecimal constants, =item q to overload C<q>-quoted strings, constant pieces of C<qq>- and C<qx>-quoted strings and here-documents, =item qr to overload constant pieces of regular expressions. =back The corresponding values are references to functions which take three arguments: the first one is the I<initial> string form of the constant, the second one is how Perl interprets this constant, the third one is how the constant is used. Note that the initial string form does not contain string delimiters, and has backslashes in backslash-delimiter combinations stripped (thus the value of delimiter is not relevant for processing of this string). The return value of this function is how this constant is going to be interpreted by Perl. The third argument is undefined unless for overloaded C<q>- and C<qr>- constants, it is C<q> in single-quote context (comes from strings, regular expressions, and single-quote HERE documents), it is C<tr> for arguments of C<tr>/C<y> operators, it is C<s> for right-hand side of C<s>-operator, and it is C<qq> otherwise. Since an expression C<"ab$cd,,"> is just a shortcut for C<'ab' . $cd . ',,'>, it is expected that overloaded constant strings are equipped with reasonable overloaded catenation operator, otherwise absurd results will result. Similarly, negative numbers are considered as negations of positive constants. Note that it is probably meaningless to call the functions overload::constant() and overload::remove_constant() from anywhere but import() and unimport() methods. From these methods they may be called as sub import { shift; return unless @_; die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant'; overload::constant integer => sub {Math::BigInt->new(shift)}; } =head1 IMPLEMENTATION What follows is subject to change RSN. The table of methods for all operations is cached in magic for the symbol table hash for the package. The cache is invalidated during processing of C<use overload>, C<no overload>, new function definitions, and changes in @ISA. (Every SVish thing has a magic queue, and magic is an entry in that queue. This is how a single variable may participate in multiple forms of magic simultaneously. For instance, environment variables regularly have two forms at once: their %ENV magic and their taint magic. However, the magic which implements overloading is applied to the stashes, which are rarely used directly, thus should not slow down Perl.) If a package uses overload, it carries a special flag. This flag is also set when new functions are defined or @ISA is modified. There will be a slight speed penalty on the very first operation thereafter that supports overloading, while the overload tables are updated. If there is no overloading present, the flag is turned off. Thus the only speed penalty thereafter is the checking of this flag. It is expected that arguments to methods that are not explicitly supposed to be changed are constant (but this is not enforced). =head1 COOKBOOK Please add examples to what follows! =head2 Two-face Scalars Put this in F<two_face.pm> in your Perl library directory: package two_face; # Scalars with separate string and # numeric values. sub new { my $p = shift; bless [@_], $p } use overload '""' => \&str, '0+' => \&num, fallback => 1; sub num {shift->[1]} sub str {shift->[0]} Use it as follows: require two_face; my $seven = two_face->new("vii", 7); printf "seven=$seven, seven=%d, eight=%d\n", $seven, $seven+1; print "seven contains 'i'\n" if $seven =~ /i/; (The second line creates a scalar which has both a string value, and a numeric value.) This prints: seven=vii, seven=7, eight=8 seven contains 'i' =head2 Two-face References Suppose you want to create an object which is accessible as both an array reference and a hash reference. package two_refs; use overload '%{}' => \&gethash, '@{}' => sub { $ {shift()} }; sub new { my $p = shift; bless \ [@_], $p; } sub gethash { my %h; my $self = shift; tie %h, ref $self, $self; \%h; } sub TIEHASH { my $p = shift; bless \ shift, $p } my %fields; my $i = 0; $fields{$_} = $i++ foreach qw{zero one two three}; sub STORE { my $self = ${shift()}; my $key = $fields{shift()}; defined $key or die "Out of band access"; $$self->[$key] = shift; } sub FETCH { my $self = ${shift()}; my $key = $fields{shift()}; defined $key or die "Out of band access"; $$self->[$key]; } Now one can access an object using both the array and hash syntax: my $bar = two_refs->new(3,4,5,6); $bar->[2] = 11; $bar->{two} == 11 or die 'bad hash fetch'; Note several important features of this example. First of all, the I<actual> type of $bar is a scalar reference, and we do not overload the scalar dereference. Thus we can get the I<actual> non-overloaded contents of $bar by just using C<$$bar> (what we do in functions which overload dereference). Similarly, the object returned by the TIEHASH() method is a scalar reference. Second, we create a new tied hash each time the hash syntax is used. This allows us not to worry about a possibility of a reference loop, which would lead to a memory leak. Both these problems can be cured. Say, if we want to overload hash dereference on a reference to an object which is I<implemented> as a hash itself, the only problem one has to circumvent is how to access this I<actual> hash (as opposed to the I<virtual> hash exhibited by the overloaded dereference operator). Here is one possible fetching routine: sub access_hash { my ($self, $key) = (shift, shift); my $class = ref $self; bless $self, 'overload::dummy'; # Disable overloading of %{} my $out = $self->{$key}; bless $self, $class; # Restore overloading $out; } To remove creation of the tied hash on each access, one may an extra level of indirection which allows a non-circular structure of references: package two_refs1; use overload '%{}' => sub { ${shift()}->[1] }, '@{}' => sub { ${shift()}->[0] }; sub new { my $p = shift; my $a = [@_]; my %h; tie %h, $p, $a; bless \ [$a, \%h], $p; } sub gethash { my %h; my $self = shift; tie %h, ref $self, $self; \%h; } sub TIEHASH { my $p = shift; bless \ shift, $p } my %fields; my $i = 0; $fields{$_} = $i++ foreach qw{zero one two three}; sub STORE { my $a = ${shift()}; my $key = $fields{shift()}; defined $key or die "Out of band access"; $a->[$key] = shift; } sub FETCH { my $a = ${shift()}; my $key = $fields{shift()}; defined $key or die "Out of band access"; $a->[$key]; } Now if $baz is overloaded like this, then C<$baz> is a reference to a reference to the intermediate array, which keeps a reference to an actual array, and the access hash. The tie()ing object for the access hash is a reference to a reference to the actual array, so =over =item * There are no loops of references. =item * Both "objects" which are blessed into the class C<two_refs1> are references to a reference to an array, thus references to a I<scalar>. Thus the accessor expression C<$$foo-E<gt>[$ind]> involves no overloaded operations. =back =head2 Symbolic Calculator Put this in F<symbolic.pm> in your Perl library directory: package symbolic; # Primitive symbolic calculator use overload nomethod => \&wrap; sub new { shift; bless ['n', @_] } sub wrap { my ($obj, $other, $inv, $meth) = @_; ($obj, $other) = ($other, $obj) if $inv; bless [$meth, $obj, $other]; } This module is very unusual as overloaded modules go: it does not provide any usual overloaded operators, instead it provides an implementation for L</C<nomethod>>. In this example the C<nomethod> subroutine returns an object which encapsulates operations done over the objects: C<< symbolic->new(3) >> contains C<['n', 3]>, C<< 2 + symbolic->new(3) >> contains C<['+', 2, ['n', 3]]>. Here is an example of the script which "calculates" the side of circumscribed octagon using the above package: require symbolic; my $iter = 1; # 2($iter+2) = 8 my $side = symbolic->new(1); my $cnt = $iter; while ($cnt--) { $side = (sqrt(1 + $side2) - 1)/$side; } print "OK\n"; The value of $side is ['/', ['-', ['sqrt', ['+', 1, ['', ['n', 1], 2]], undef], 1], ['n', 1]] Note that while we obtained this value using a nice little script, there is no simple way to I<use> this value. In fact this value may be inspected in debugger (see L<perldebug>), but only if C<bareStringify> B<O>ption is set, and not via C<p> command. If one attempts to print this value, then the overloaded operator C<""> will be called, which will call C<nomethod> operator. The result of this operator will be stringified again, but this result is again of type C<symbolic>, which will lead to an infinite loop. Add a pretty-printer method to the module F<symbolic.pm>: sub pretty { my ($meth, $a, $b) = @{+shift}; $a = 'u' unless defined $a; $b = 'u' unless defined $b; $a = $a->pretty if ref $a; $b = $b->pretty if ref $b; "[$meth $a $b]"; } Now one can finish the script by print "side = ", $side->pretty, "\n"; The method C<pretty> is doing object-to-string conversion, so it is natural to overload the operator C<""> using this method. However, inside such a method it is not necessary to pretty-print the I<components> $a and $b of an object. In the above subroutine C<"[$meth $a $b]"> is a catenation of some strings and components $a and $b. If these components use overloading, the catenation operator will look for an overloaded operator C<.>; if not present, it will look for an overloaded operator C<"">. Thus it is enough to use use overload nomethod => \&wrap, '""' => \&str; sub str { my ($meth, $a, $b) = @{+shift}; $a = 'u' unless defined $a; $b = 'u' unless defined $b; "[$meth $a $b]"; } Now one can change the last line of the script to print "side = $side\n"; which outputs side = [/ [- [sqrt [+ 1 [ [n 1 u] 2]] u] 1] [n 1 u]] and one can inspect the value in debugger using all the possible methods. Something is still amiss: consider the loop variable $cnt of the script. It was a number, not an object. We cannot make this value of type C<symbolic>, since then the loop will not terminate. Indeed, to terminate the cycle, the $cnt should become false. However, the operator C<bool> for checking falsity is overloaded (this time via overloaded C<"">), and returns a long string, thus any object of type C<symbolic> is true. To overcome this, we need a way to compare an object to 0. In fact, it is easier to write a numeric conversion routine. Here is the text of F<symbolic.pm> with such a routine added (and slightly modified str()): package symbolic; # Primitive symbolic calculator use overload nomethod => \&wrap, '""' => \&str, '0+' => \&num; sub new { shift; bless ['n', @_] } sub wrap { my ($obj, $other, $inv, $meth) = @_; ($obj, $other) = ($other, $obj) if $inv; bless [$meth, $obj, $other]; } sub str { my ($meth, $a, $b) = @{+shift}; $a = 'u' unless defined $a; if (defined $b) { "[$meth $a $b]"; } else { "[$meth $a]"; } } my %subr = ( n => sub {$_[0]}, sqrt => sub {sqrt $_[0]}, '-' => sub {shift() - shift()}, '+' => sub {shift() + shift()}, '/' => sub {shift() / shift()}, '' => sub {shift() shift()}, '' => sub {shift() shift()}, ); sub num { my ($meth, $a, $b) = @{+shift}; my $subr = $subr{$meth} or die "Do not know how to ($meth) in symbolic"; $a = $a->num if ref $a eq __PACKAGE__; $b = $b->num if ref $b eq __PACKAGE__; $subr->($a,$b); } All the work of numeric conversion is done in %subr and num(). Of course, %subr is not complete, it contains only operators used in the example below. Here is the extra-credit question: why do we need an explicit recursion in num()? (Answer is at the end of this section.) Use this module like this: require symbolic; my $iter = symbolic->new(2); # 16-gon my $side = symbolic->new(1); my $cnt = $iter; while ($cnt) { $cnt = $cnt - 1; # Mutator '--' not implemented $side = (sqrt(1 + $side*2) - 1)/$side; } printf "%s=%f\n", $side, $side; printf "pi=%f\n", $side(2($iter+2)); It prints (without so many line breaks) [/ [- [sqrt [+ 1 [ [/ [- [sqrt [+ 1 [ [n 1] 2]]] 1] [n 1]] 2]]] 1] [/ [- [sqrt [+ 1 [ [n 1] 2]]] 1] [n 1]]]=0.198912 pi=3.182598 The above module is very primitive. It does not implement mutator methods (C<++>, C<-=> and so on), does not do deep copying (not required without mutators!), and implements only those arithmetic operations which are used in the example. To implement most arithmetic operations is easy; one should just use the tables of operations, and change the code which fills %subr to my %subr = ( 'n' => sub {$_[0]} ); foreach my $op (split " ", $overload::ops{with_assign}) { $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}"; } my @bins = qw(binary 3way_comparison num_comparison str_comparison); foreach my $op (split " ", "@overload::ops{ @bins }") { $subr{$op} = eval "sub {shift() $op shift()}"; } foreach my $op (split " ", "@overload::ops{qw(unary func)}") { print "defining '$op'\n"; $subr{$op} = eval "sub {$op shift()}"; } Since subroutines implementing assignment operators are not required to modify their operands (see L</Overloadable Operations> above), we do not need anything special to make C<+=> and friends work, besides adding these operators to %subr and defining a copy constructor (needed since Perl has no way to know that the implementation of C<'+='> does not mutate the argument - see L</Copy Constructor>). To implement a copy constructor, add C<< '=' => \&cpy >> to C<use overload> line, and code (this code assumes that mutators change things one level deep only, so recursive copying is not needed): sub cpy { my $self = shift; bless [@$self], ref $self; } To make C<++> and C<--> work, we need to implement actual mutators, either directly, or in C<nomethod>. We continue to do things inside C<nomethod>, thus add if ($meth eq '++' or $meth eq '--') { @$obj = ($meth, (bless [@$obj]), 1); # Avoid circular reference return $obj; } after the first line of wrap(). This is not a most effective implementation, one may consider sub inc { $_[0] = bless ['++', shift, 1]; } instead. As a final remark, note that one can fill %subr by my %subr = ( 'n' => sub {$_[0]} ); foreach my $op (split " ", $overload::ops{with_assign}) { $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}"; } my @bins = qw(binary 3way_comparison num_comparison str_comparison); foreach my $op (split " ", "@overload::ops{ @bins }") { $subr{$op} = eval "sub {shift() $op shift()}"; } foreach my $op (split " ", "@overload::ops{qw(unary func)}") { $subr{$op} = eval "sub {$op shift()}"; } $subr{'++'} = $subr{'+'}; $subr{'--'} = $subr{'-'}; This finishes implementation of a primitive symbolic calculator in 50 lines of Perl code. Since the numeric values of subexpressions are not cached, the calculator is very slow. Here is the answer for the exercise: In the case of str(), we need no explicit recursion since the overloaded C<.>-operator will fall back to an existing overloaded operator C<"">. Overloaded arithmetic operators I<do not> fall back to numeric conversion if C<fallback> is not explicitly requested. Thus without an explicit recursion num() would convert C<['+', $a, $b]> to C<$a + $b>, which would just rebuild the argument of num(). If you wonder why defaults for conversion are different for str() and num(), note how easy it was to write the symbolic calculator. This simplicity is due to an appropriate choice of defaults. One extra note: due to the explicit recursion num() is more fragile than sym(): we need to explicitly check for the type of $a and $b. If components $a and $b happen to be of some related type, this may lead to problems. =head2 I<Really> Symbolic Calculator One may wonder why we call the above calculator symbolic. The reason is that the actual calculation of the value of expression is postponed until the value is I<used>. To see it in action, add a method sub STORE { my $obj = shift; $#$obj = 1; @$obj->[0,1] = ('=', shift); } to the package C<symbolic>. After this change one can do my $a = symbolic->new(3); my $b = symbolic->new(4); my $c = sqrt($a2 + $b2); and the numeric value of $c becomes 5. However, after calling $a->STORE(12); $b->STORE(5); the numeric value of $c becomes 13. There is no doubt now that the module symbolic provides a I<symbolic> calculator indeed. To hide the rough edges under the hood, provide a tie()d interface to the package C<symbolic>. Add methods sub TIESCALAR { my $pack = shift; $pack->new(@_) } sub FETCH { shift } sub nop { } # Around a bug (the bug, fixed in Perl 5.14, is described in L<"BUGS">). One can use this new interface as tie $a, 'symbolic', 3; tie $b, 'symbolic', 4; $a->nop; $b->nop; # Around a bug my $c = sqrt($a2 + $b2); Now numeric value of $c is 5. After C<$a = 12; $b = 5> the numeric value of $c becomes 13. To insulate the user of the module add a method sub vars { my $p = shift; tie($_, $p), $_->nop foreach @_; } Now my ($a, $b); symbolic->vars($a, $b); my $c = sqrt($a2 + $b2); $a = 3; $b = 4; printf "c5 %s=%f\n", $c, $c; $a = 12; $b = 5; printf "c13 %s=%f\n", $c, $c; shows that the numeric value of $c follows changes to the values of $a and $b. =head1 AUTHOR Ilya Zakharevich E<lt>F<ilya@math.mps.ohio-state.edu>E<gt>. =head1 SEE ALSO The C<overloading> pragma can be used to enable or disable overloaded operations within a lexical scope - see L<overloading>. =head1 DIAGNOSTICS When Perl is run with the B<-Do> switch or its equivalent, overloading induces diagnostic messages. Using the C<m> command of Perl debugger (see L<perldebug>) one can deduce which operations are overloaded (and which ancestor triggers this overloading). Say, if C<eq> is overloaded, then the method C<(eq> is shown by debugger. The method C<()> corresponds to the C<fallback> key (in fact a presence of this method shows that this package has overloading enabled, and it is what is used by the C<Overloaded> function of module C<overload>). The module might issue the following warnings: =over 4 =item Odd number of arguments for overload::constant (W) The call to overload::constant contained an odd number of arguments. The arguments should come in pairs. =item '%s' is not an overloadable type (W) You tried to overload a constant type the overload package is unaware of. =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 overload arg '%s' is invalid (W) C<use overload> was passed an argument it did not recognize. Did you mistype an operator? =back =head1 BUGS AND PITFALLS =over =item * A pitfall when fallback is TRUE and Perl resorts to a built-in implementation of an operator is that some operators have more than one semantic, for example C<\|>: use overload '0+' => sub { $_[0]->{n}; }, fallback => 1; my $x = bless { n => 4 }, "main"; my $y = bless { n => 8 }, "main"; print $x \| $y, "\n"; You might expect this to output "12". In fact, it prints "<": the ASCII result of treating "\|" as a bitwise string operator - that is, the result of treating the operands as the strings "4" and "8" rather than numbers. The fact that numify (C<0+>) is implemented but stringify (C<"">) isn't makes no difference since the latter is simply autogenerated from the former. The only way to change this is to provide your own subroutine for C<'\|'>. =item * Magic autogeneration increases the potential for inadvertently creating self-referential structures. Currently Perl will not free self-referential structures until cycles are explicitly broken. For example, use overload '+' => 'add'; sub add { bless [ \$_[0], \$_[1] ] }; is asking for trouble, since $obj += $y; will effectively become $obj = add($obj, $y, undef); with the same result as $obj = [\$obj, \$foo]; Even if no I<explicit> assignment-variants of operators are present in the script, they may be generated by the optimizer. For example, "obj = $obj\n" may be optimized to my $tmp = 'obj = ' . $obj; $tmp .= "\n"; =item * The symbol table is filled with names looking like line-noise. =item * This bug was fixed in Perl 5.18, but may still trip you up if you are using older versions: For the purpose of inheritance every overloaded package behaves as if C<fallback> is present (possibly undefined). This may create interesting effects if some package is not overloaded, but inherits from two overloaded packages. =item * Before Perl 5.14, the relation between overloading and tie()ing was broken. Overloading was triggered or not based on the I<previous> class of the tie()d variable. This happened because the presence of overloading was checked too early, before any tie()d access was attempted. If the class of the value FETCH()ed from the tied variable does not change, a simple workaround for code that is to run on older Perl versions is to access the value (via C<() = $foo> or some such) immediately after tie()ing, so that after this call the I<previous> class coincides with the current one. =item * Barewords are not covered by overloaded string constants. =item * The range operator C<..> cannot be overloaded. =back =cut	52.05 KB	2025-07-28 03:54
📄 overloading.pm package overloading; use warnings; our $VERSION = '0.02'; my $HINT_NO_AMAGIC = 0x01000000; # see perl.h require 5.010001; sub _ops_to_nums { require overload::numbers; map { exists $overload::numbers::names{"($_"} ? $overload::numbers::names{"($_"} : do { require Carp; Carp::croak("'$_' is not a valid overload") } } @_; } sub import { my ( $class, @ops ) = @_; if ( @ops ) { if ( $^H{overloading} ) { vec($^H{overloading} , $_, 1) = 0 for _ops_to_nums(@ops); } if ( $^H{overloading} !~ /[^\0]/ ) { delete $^H{overloading}; $^H &= ~$HINT_NO_AMAGIC; } } else { delete $^H{overloading}; $^H &= ~$HINT_NO_AMAGIC; } } sub unimport { my ( $class, @ops ) = @_; if ( exists $^H{overloading} or not $^H & $HINT_NO_AMAGIC ) { if ( @ops ) { vec($^H{overloading} \|\|= '', $_, 1) = 1 for _ops_to_nums(@ops); } else { delete $^H{overloading}; } } $^H \|= $HINT_NO_AMAGIC; } 1; __END__ =head1 NAME overloading - perl pragma to lexically control overloading =head1 SYNOPSIS { no overloading; my $str = "$object"; # doesn't call stringification overload } # it's lexical, so this stringifies: warn "$object"; # it can be enabled per op no overloading qw(""); warn "$object"; # and also reenabled use overloading; =head1 DESCRIPTION This pragma allows you to lexically disable or enable overloading. =over 6 =item C<no overloading> Disables overloading entirely in the current lexical scope. =item C<no overloading @ops> Disables only specific overloads in the current lexical scope. =item C<use overloading> Reenables overloading in the current lexical scope. =item C<use overloading @ops> Reenables overloading only for specific ops in the current lexical scope. =back =cut	1.77 KB	2025-07-28 03:54
📁 pod	-	2026-03-21 15:44
📄 strict.pm package strict; $strict::VERSION = "1.11"; my ( %bitmask, %explicit_bitmask ); BEGIN { # Verify that we're called correctly so that strictures will work. # Can't use Carp, since Carp uses us! # see also warnings.pm. die sprintf "Incorrect use of pragma '%s' at %s line %d.\n", __PACKAGE__, +(caller)[1,2] if __FILE__ !~ ( '(?x) \b '.__PACKAGE__.' \.pmc? \z' ) && __FILE__ =~ ( '(?x) \b (?i:'.__PACKAGE__.') \.pmc? \z' ); %bitmask = ( refs => 0x00000002, subs => 0x00000200, vars => 0x00000400, ); %explicit_bitmask = ( refs => 0x00000020, subs => 0x00000040, vars => 0x00000080, ); my $bits = 0; $bits \|= $_ for values %bitmask; my $inline_all_bits = $bits; all_bits = sub () { $inline_all_bits }; $bits = 0; $bits \|= $_ for values %explicit_bitmask; my $inline_all_explicit_bits = $bits; all_explicit_bits = sub () { $inline_all_explicit_bits }; } sub bits { my $bits = 0; my @wrong; foreach my $s (@_) { if (exists $bitmask{$s}) { $^H \|= $explicit_bitmask{$s}; $bits \|= $bitmask{$s}; } else { push @wrong, $s; } } if (@wrong) { require Carp; Carp::croak("Unknown 'strict' tag(s) '@wrong'"); } $bits; } sub import { shift; $^H \|= @_ ? &bits : all_bits \| all_explicit_bits; } sub unimport { shift; if (@_) { $^H &= ~&bits; } else { $^H &= ~all_bits; $^H \|= all_explicit_bits; } } 1; __END__ =head1 NAME strict - Perl pragma to restrict unsafe constructs =head1 SYNOPSIS use strict; use strict "vars"; use strict "refs"; use strict "subs"; use strict; no strict "vars"; =head1 DESCRIPTION The C<strict> pragma disables certain Perl expressions that could behave unexpectedly or are difficult to debug, turning them into errors. The effect of this pragma is limited to the current file or scope block. If no import list is supplied, all possible restrictions are assumed. (This is the safest mode to operate in, but is sometimes too strict for casual programming.) Currently, there are three possible things to be strict about: "subs", "vars", and "refs". =over 6 =item C<strict refs> This generates a runtime error if you use symbolic references (see L<perlref>). use strict 'refs'; $ref = \$foo; print $$ref; # ok $ref = "foo"; print $$ref; # runtime error; normally ok $file = "STDOUT"; print $file "Hi!"; # error; note: no comma after $file There is one exception to this rule: $bar = \&{'foo'}; &$bar; is allowed so that C<goto &$AUTOLOAD> would not break under stricture. =item C<strict vars> This generates a compile-time error if you access a variable that was neither explicitly declared (using any of C<my>, C<our>, C<state>, or C<use vars>) nor fully qualified. (Because this is to avoid variable suicide problems and subtle dynamic scoping issues, a merely C<local> variable isn't good enough.) See L<perlfunc/my>, L<perlfunc/our>, L<perlfunc/state>, L<perlfunc/local>, and L<vars>. use strict 'vars'; $X::foo = 1; # ok, fully qualified my $foo = 10; # ok, my() var local $baz = 9; # blows up, $baz not declared before package Cinna; our $bar; # Declares $bar in current package $bar = 'HgS'; # ok, global declared via pragma The local() generated a compile-time error because you just touched a global name without fully qualifying it. Because of their special use by sort(), the variables $a and $b are exempted from this check. =item C<strict subs> This disables the poetry optimization, generating a compile-time error if you try to use a bareword identifier that's not a subroutine, unless it is a simple identifier (no colons) and that it appears in curly braces or on the left hand side of the C<< => >> symbol. use strict 'subs'; $SIG{PIPE} = Plumber; # blows up $SIG{PIPE} = "Plumber"; # fine: quoted string is always ok $SIG{PIPE} = \&Plumber; # preferred form =back See L<perlmodlib/Pragmatic Modules>. =head1 HISTORY C<strict 'subs'>, with Perl 5.6.1, erroneously permitted to use an unquoted compound identifier (e.g. C<Foo::Bar>) as a hash key (before C<< => >> or inside curlies), but without forcing it always to a literal string. Starting with Perl 5.8.1 strict is strict about its restrictions: if unknown restrictions are used, the strict pragma will abort with Unknown 'strict' tag(s) '...' As of version 1.04 (Perl 5.10), strict verifies that it is used as "strict" to avoid the dreaded Strict trap on case insensitive file systems. =cut	4.63 KB	2025-07-28 03:53
📄 subs.pm package subs; our $VERSION = '1.03'; =head1 NAME subs - Perl pragma to predeclare subroutine names =head1 SYNOPSIS use subs qw(frob); frob 3..10; =head1 DESCRIPTION This will predeclare all the subroutines whose names are in the list, allowing you to use them without parentheses (as list operators) even before they're declared. Unlike pragmas that affect the C<$^H> hints variable, the C<use vars> and C<use subs> declarations are not lexically scoped to the block they appear in: they affect the entire package in which they appear. It is not possible to rescind these declarations with C<no vars> or C<no subs>. See L<perlmodlib/Pragmatic Modules> and L<strict/strict subs>. =cut require 5.000; sub import { my $callpack = caller; my $pack = shift; my @imports = @_; foreach my $sym (@imports) { *{"${callpack}::$sym"} = \&{"${callpack}::$sym"}; } }; 1;	901 B	2025-07-28 03:54
📁 unicore	-	2026-03-21 15:44
📄 utf8.pm package utf8; $utf8::hint_bits = 0x00800000; our $VERSION = '1.22'; sub import { $^H \|= $utf8::hint_bits; } sub unimport { $^H &= ~$utf8::hint_bits; } sub AUTOLOAD { goto &$AUTOLOAD if defined &$AUTOLOAD; require Carp; Carp::croak("Undefined subroutine $AUTOLOAD called"); } 1; __END__ =head1 NAME utf8 - Perl pragma to enable/disable UTF-8 (or UTF-EBCDIC) in source code =head1 SYNOPSIS use utf8; no utf8; # Convert the internal representation of a Perl scalar to/from UTF-8. $num_octets = utf8::upgrade($string); $success = utf8::downgrade($string[, $fail_ok]); # Change each character of a Perl scalar to/from a series of # characters that represent the UTF-8 bytes of each original character. utf8::encode($string); # "\x{100}" becomes "\xc4\x80" utf8::decode($string); # "\xc4\x80" becomes "\x{100}" # Convert a code point from the platform native character set to # Unicode, and vice-versa. $unicode = utf8::native_to_unicode(ord('A')); # returns 65 on both # ASCII and EBCDIC # platforms $native = utf8::unicode_to_native(65); # returns 65 on ASCII # platforms; 193 on # EBCDIC $flag = utf8::is_utf8($string); # since Perl 5.8.1 $flag = utf8::valid($string); =head1 DESCRIPTION The C<use utf8> pragma tells the Perl parser to allow UTF-8 in the program text in the current lexical scope. The C<no utf8> pragma tells Perl to switch back to treating the source text as literal bytes in the current lexical scope. (On EBCDIC platforms, technically it is allowing UTF-EBCDIC, and not UTF-8, but this distinction is academic, so in this document the term UTF-8 is used to mean both). B<Do not use this pragma for anything else than telling Perl that your script is written in UTF-8.> The utility functions described below are directly usable without C<use utf8;>. Because it is not possible to reliably tell UTF-8 from native 8 bit encodings, you need either a Byte Order Mark at the beginning of your source code, or C<use utf8;>, to instruct perl. When UTF-8 becomes the standard source format, this pragma will effectively become a no-op. See also the effects of the C<-C> switch and its cousin, the C<PERL_UNICODE> environment variable, in L<perlrun>. Enabling the C<utf8> pragma has the following effect: =over 4 =item * Bytes in the source text that are not in the ASCII character set will be treated as being part of a literal UTF-8 sequence. This includes most literals such as identifier names, string constants, and constant regular expression patterns. =back Note that if you have non-ASCII, non-UTF-8 bytes in your script (for example embedded Latin-1 in your string literals), C<use utf8> will be unhappy. If you want to have such bytes under C<use utf8>, you can disable this pragma until the end the block (or file, if at top level) by C<no utf8;>. =head2 Utility functions The following functions are defined in the C<utf8::> package by the Perl core. You do not need to say C<use utf8> to use these and in fact you should not say that unless you really want to have UTF-8 source code. =over 4 =item * C<$num_octets = utf8::upgrade($string)> (Since Perl v5.8.0) Converts in-place the internal representation of the string from an octet sequence in the native encoding (Latin-1 or EBCDIC) to UTF-8. The logical character sequence itself is unchanged. If I<$string> is already upgraded, then this is a no-op. Returns the number of octets necessary to represent the string as UTF-8. If your code needs to be compatible with versions of perl without C<use feature 'unicode_strings';>, you can force Unicode semantics on a given string: # force unicode semantics for $string without the # "unicode_strings" feature utf8::upgrade($string); For example: # without explicit or implicit use feature 'unicode_strings' my $x = "\xDF"; # LATIN SMALL LETTER SHARP S $x =~ /ss/i; # won't match my $y = uc($x); # won't convert utf8::upgrade($x); $x =~ /ss/i; # matches my $z = uc($x); # converts to "SS" B<Note that this function does not handle arbitrary encodings>; use L<Encode> instead. =item * C<$success = utf8::downgrade($string[, $fail_ok])> (Since Perl v5.8.0) Converts in-place the internal representation of the string from UTF-8 to the equivalent octet sequence in the native encoding (Latin-1 or EBCDIC). The logical character sequence itself is unchanged. If I<$string> is already stored as native 8 bit, then this is a no-op. Can be used to make sure that the UTF-8 flag is off, e.g. when you want to make sure that the substr() or length() function works with the usually faster byte algorithm. Fails if the original UTF-8 sequence cannot be represented in the native 8 bit encoding. On failure dies or, if the value of I<$fail_ok> is true, returns false. Returns true on success. If your code expects an octet sequence this can be used to validate that you've received one: # throw an exception if not representable as octets utf8::downgrade($string) # or do your own error handling utf8::downgrade($string, 1) or die "string must be octets"; B<Note that this function does not handle arbitrary encodings>; use L<Encode> instead. =item * C<utf8::encode($string)> (Since Perl v5.8.0) Converts in-place the character sequence to the corresponding octet sequence in Perl's extended UTF-8. That is, every (possibly wide) character gets replaced with a sequence of one or more characters that represent the individual UTF-8 bytes of the character. The UTF8 flag is turned off. Returns nothing. my $x = "\x{100}"; # $x contains one character, with ord 0x100 utf8::encode($x); # $x contains two characters, with ords (on # ASCII platforms) 0xc4 and 0x80. On EBCDIC # 1047, this would instead be 0x8C and 0x41. Similar to: use Encode; $x = Encode::encode("utf8", $x); B<Note that this function does not handle arbitrary encodings>; use L<Encode> instead. =item * C<$success = utf8::decode($string)> (Since Perl v5.8.0) Attempts to convert in-place the octet sequence encoded in Perl's extended UTF-8 to the corresponding character sequence. That is, it replaces each sequence of characters in the string whose ords represent a valid (extended) UTF-8 byte sequence, with the corresponding single character. The UTF-8 flag is turned on only if the source string contains multiple-byte UTF-8 characters. If I<$string> is invalid as extended UTF-8, returns false; otherwise returns true. my $x = "\xc4\x80"; # $x contains two characters, with ords # 0xc4 and 0x80 utf8::decode($x); # On ASCII platforms, $x contains one char, # with ord 0x100. Since these bytes aren't # legal UTF-EBCDIC, on EBCDIC platforms, $x is # unchanged and the function returns FALSE. B<Note that this function does not handle arbitrary encodings>; use L<Encode> instead. =item * C<$unicode = utf8::native_to_unicode($code_point)> (Since Perl v5.8.0) This takes an unsigned integer (which represents the ordinal number of a character (or a code point) on the platform the program is being run on) and returns its Unicode equivalent value. Since ASCII platforms natively use the Unicode code points, this function returns its input on them. On EBCDIC platforms it converts from EBCDIC to Unicode. A meaningless value will currently be returned if the input is not an unsigned integer. Since Perl v5.22.0, calls to this function are optimized out on ASCII platforms, so there is no performance hit in using it there. =item * C<$native = utf8::unicode_to_native($code_point)> (Since Perl v5.8.0) This is the inverse of C<utf8::native_to_unicode()>, converting the other direction. Again, on ASCII platforms, this returns its input, but on EBCDIC platforms it will find the native platform code point, given any Unicode one. A meaningless value will currently be returned if the input is not an unsigned integer. Since Perl v5.22.0, calls to this function are optimized out on ASCII platforms, so there is no performance hit in using it there. =item * C<$flag = utf8::is_utf8($string)> (Since Perl 5.8.1) Test whether I<$string> is marked internally as encoded in UTF-8. Functionally the same as C<Encode::is_utf8($string)>. Typically only necessary for debugging and testing, if you need to dump the internals of an SV, L<Devel::Peek's\|Devel::Peek> Dump() provides more detail in a compact form. If you still think you need this outside of debugging, testing or dealing with filenames, you should probably read L<perlunitut> and L<perlunifaq/What is "the UTF8 flag"?>. Don't use this flag as a marker to distinguish character and binary data: that should be decided for each variable when you write your code. To force unicode semantics in code portable to perl 5.8 and 5.10, call C<utf8::upgrade($string)> unconditionally. =item * C<$flag = utf8::valid($string)> [INTERNAL] Test whether I<$string> is in a consistent state regarding UTF-8. Will return true if it is well-formed Perl extended UTF-8 and has the UTF-8 flag on B<or> if I<$string> is held as bytes (both these states are 'consistent'). The main reason for this routine is to allow Perl's test suite to check that operations have left strings in a consistent state. =back C<utf8::encode> is like C<utf8::upgrade>, but the UTF8 flag is cleared. See L<perlunicode>, and the C API functions C<L<sv_utf8_upgrade\|perlapi/sv_utf8_upgrade>>, C<L<perlapi/sv_utf8_downgrade>>, C<L<perlapi/sv_utf8_encode>>, and C<L<perlapi/sv_utf8_decode>>, which are wrapped by the Perl functions C<utf8::upgrade>, C<utf8::downgrade>, C<utf8::encode> and C<utf8::decode>. Also, the functions C<utf8::is_utf8>, C<utf8::valid>, C<utf8::encode>, C<utf8::decode>, C<utf8::upgrade>, and C<utf8::downgrade> are actually internal, and thus always available, without a C<require utf8> statement. =head1 BUGS Some filesystems may not support UTF-8 file names, or they may be supported incompatibly with Perl. Therefore UTF-8 names that are visible to the filesystem, such as module names may not work. =head1 SEE ALSO L<perlunitut>, L<perluniintro>, L<perlrun>, L<bytes>, L<perlunicode> =cut	10.18 KB	2025-07-28 03:53
📄 vars.pm package vars; use 5.006; our $VERSION = '1.05'; use warnings::register; use strict qw(vars subs); sub import { my $callpack = caller; my (undef, @imports) = @_; my ($sym, $ch); foreach (@imports) { if (($ch, $sym) = /^([\$\@\%\\&])(.+)/) { if ($sym =~ /\W/) { # time for a more-detailed check-up if ($sym =~ /^\w+[[{].[]}]$/) { require Carp; Carp::croak("Can't declare individual elements of hash or array"); } elsif (warnings::enabled() and length($sym) == 1 and $sym !~ tr/a-zA-Z//) { warnings::warn("No need to declare built-in vars"); } elsif (($^H & strict::bits('vars'))) { require Carp; Carp::croak("'$_' is not a valid variable name under strict vars"); } } $sym = "${callpack}::$sym" unless $sym =~ /::/; $sym = ( $ch eq "\$" ? \$$sym : $ch eq "\@" ? \@$sym : $ch eq "\%" ? \%$sym : $ch eq "\" ? \*$sym : $ch eq "\&" ? \&$sym : do { require Carp; Carp::croak("'$_' is not a valid variable name"); }); } else { require Carp; Carp::croak("'$_' is not a valid variable name"); } } }; 1; __END__ =head1 NAME vars - Perl pragma to predeclare global variable names =head1 SYNOPSIS use vars qw($frob @mung %seen); =head1 DESCRIPTION NOTE: For use with variables in the current package for a single scope, the functionality provided by this pragma has been superseded by C<our> declarations, available in Perl v5.6.0 or later, and use of this pragma is discouraged. See L<perlfunc/our>. This pragma will predeclare all the variables whose names are in the list, allowing you to use them under C<use strict>, and disabling any typo warnings for them. Unlike pragmas that affect the C<$^H> hints variable, the C<use vars> and C<use subs> declarations are not lexically scoped to the block they appear in: they affect the entire package in which they appear. It is not possible to rescind these declarations with C<no vars> or C<no subs>. Packages such as the B<AutoLoader> and B<SelfLoader> that delay loading of subroutines within packages can create problems with package lexicals defined using C<my()>. While the B<vars> pragma cannot duplicate the effect of package lexicals (total transparency outside of the package), it can act as an acceptable substitute by pre-declaring global symbols, ensuring their availability to the later-loaded routines. See L<perlmodlib/Pragmatic Modules>. =cut	2.4 KB	2025-07-28 03:54
📁 vendor_perl	-	2026-03-21 15:45
📁 warnings	-	2026-03-21 15:44
📄 warnings.pm # -- buffer-read-only: t -- # !!!!!!! DO NOT EDIT THIS FILE !!!!!!! # This file is built by regen/warnings.pl. # Any changes made here will be lost! package warnings; our $VERSION = "1.47"; # Verify that we're called correctly so that warnings will work. # Can't use Carp, since Carp uses us! # String regexps because constant folding = smaller optree = less memory vs regexp literal # see also strict.pm. die sprintf "Incorrect use of pragma '%s' at %s line %d.\n", __PACKAGE__, +(caller)[1,2] if __FILE__ !~ ( '(?x) \b '.__PACKAGE__.' \.pmc? \z' ) && __FILE__ =~ ( '(?x) \b (?i:'.__PACKAGE__.') \.pmc? \z' ); our %Offsets = ( # Warnings Categories added in Perl 5.008 'all' => 0, 'closure' => 2, 'deprecated' => 4, 'exiting' => 6, 'glob' => 8, 'io' => 10, 'closed' => 12, 'exec' => 14, 'layer' => 16, 'newline' => 18, 'pipe' => 20, 'unopened' => 22, 'misc' => 24, 'numeric' => 26, 'once' => 28, 'overflow' => 30, 'pack' => 32, 'portable' => 34, 'recursion' => 36, 'redefine' => 38, 'regexp' => 40, 'severe' => 42, 'debugging' => 44, 'inplace' => 46, 'internal' => 48, 'malloc' => 50, 'signal' => 52, 'substr' => 54, 'syntax' => 56, 'ambiguous' => 58, 'bareword' => 60, 'digit' => 62, 'parenthesis' => 64, 'precedence' => 66, 'printf' => 68, 'prototype' => 70, 'qw' => 72, 'reserved' => 74, 'semicolon' => 76, 'taint' => 78, 'threads' => 80, 'uninitialized' => 82, 'unpack' => 84, 'untie' => 86, 'utf8' => 88, 'void' => 90, # Warnings Categories added in Perl 5.011 'imprecision' => 92, 'illegalproto' => 94, # Warnings Categories added in Perl 5.013 'non_unicode' => 96, 'nonchar' => 98, 'surrogate' => 100, # Warnings Categories added in Perl 5.017 'experimental' => 102, 'experimental::lexical_subs' => 104, 'experimental::regex_sets' => 106, 'experimental::smartmatch' => 108, # Warnings Categories added in Perl 5.019 'experimental::postderef' => 110, 'experimental::signatures' => 112, 'syscalls' => 114, # Warnings Categories added in Perl 5.021 'experimental::bitwise' => 116, 'experimental::const_attr' => 118, 'experimental::re_strict' => 120, 'experimental::refaliasing' => 122, 'experimental::win32_perlio' => 124, 'locale' => 126, 'missing' => 128, 'redundant' => 130, # Warnings Categories added in Perl 5.025 'experimental::declared_refs' => 132, # Warnings Categories added in Perl 5.027 'experimental::alpha_assertions' => 134, 'experimental::script_run' => 136, 'shadow' => 138, # Warnings Categories added in Perl 5.029 'experimental::private_use' => 140, 'experimental::uniprop_wildcards' => 142, 'experimental::vlb' => 144, # Warnings Categories added in Perl 5.031 'experimental::isa' => 146, ); our %Bits = ( 'all' => "\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55\x55", # [0..75] 'ambiguous' => "\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [29] 'bareword' => "\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [30] 'closed' => "\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [6] 'closure' => "\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [1] 'debugging' => "\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [22] 'deprecated' => "\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [2] 'digit' => "\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [31] 'exec' => "\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [7] 'exiting' => "\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [3] 'experimental' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x55\x51\x15\x50\x51\x05", # [51..56,58..62,66..68,70..73] 'experimental::alpha_assertions' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00", # [67] 'experimental::bitwise' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00", # [58] 'experimental::const_attr' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00", # [59] 'experimental::declared_refs' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00", # [66] 'experimental::isa' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04", # [73] 'experimental::lexical_subs' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00", # [52] 'experimental::postderef' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00", # [55] 'experimental::private_use' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00", # [70] 'experimental::re_strict' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00", # [60] 'experimental::refaliasing' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00", # [61] 'experimental::regex_sets' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00", # [53] 'experimental::script_run' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00", # [68] 'experimental::signatures' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00", # [56] 'experimental::smartmatch' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00", # [54] 'experimental::uniprop_wildcards' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00", # [71] 'experimental::vlb' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01", # [72] 'experimental::win32_perlio' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00", # [62] 'glob' => "\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [4] 'illegalproto' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00", # [47] 'imprecision' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00", # [46] 'inplace' => "\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [23] 'internal' => "\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [24] 'io' => "\x00\x54\x55\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00", # [5..11,57] 'layer' => "\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [8] 'locale' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00", # [63] 'malloc' => "\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [25] 'misc' => "\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [12] 'missing' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00", # [64] 'newline' => "\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [9] 'non_unicode' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00", # [48] 'nonchar' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00", # [49] 'numeric' => "\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [13] 'once' => "\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [14] 'overflow' => "\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [15] 'pack' => "\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [16] 'parenthesis' => "\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [32] 'pipe' => "\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [10] 'portable' => "\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [17] 'precedence' => "\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [33] 'printf' => "\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [34] 'prototype' => "\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [35] 'qw' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [36] 'recursion' => "\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [18] 'redefine' => "\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [19] 'redundant' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00", # [65] 'regexp' => "\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [20] 'reserved' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [37] 'semicolon' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [38] 'severe' => "\x00\x00\x00\x00\x00\x54\x05\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [21..25] 'shadow' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00", # [69] 'signal' => "\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [26] 'substr' => "\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [27] 'surrogate' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00", # [50] 'syntax' => "\x00\x00\x00\x00\x00\x00\x00\x55\x55\x15\x00\x40\x00\x00\x00\x00\x00\x00\x00", # [28..38,47] 'syscalls' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00", # [57] 'taint' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [39] 'threads' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00", # [40] 'uninitialized' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00", # [41] 'unopened' => "\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [11] 'unpack' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x10\x00\x00\x00\x00\x00\x00\x00\x00", # [42] 'untie' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x40\x00\x00\x00\x00\x00\x00\x00\x00", # [43] 'utf8' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x15\x00\x00\x00\x00\x00\x00", # [44,48..50] 'void' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00", # [45] ); our %DeadBits = ( 'all' => "\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa\xaa", # [0..75] 'ambiguous' => "\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [29] 'bareword' => "\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [30] 'closed' => "\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [6] 'closure' => "\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [1] 'debugging' => "\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [22] 'deprecated' => "\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [2] 'digit' => "\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [31] 'exec' => "\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [7] 'exiting' => "\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [3] 'experimental' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\xaa\xa2\x2a\xa0\xa2\x0a", # [51..56,58..62,66..68,70..73] 'experimental::alpha_assertions' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00", # [67] 'experimental::bitwise' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00", # [58] 'experimental::const_attr' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00", # [59] 'experimental::declared_refs' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00", # [66] 'experimental::isa' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08", # [73] 'experimental::lexical_subs' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00", # [52] 'experimental::postderef' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00", # [55] 'experimental::private_use' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00", # [70] 'experimental::re_strict' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00", # [60] 'experimental::refaliasing' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00", # [61] 'experimental::regex_sets' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00", # [53] 'experimental::script_run' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00", # [68] 'experimental::signatures' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00", # [56] 'experimental::smartmatch' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00", # [54] 'experimental::uniprop_wildcards' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00", # [71] 'experimental::vlb' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02", # [72] 'experimental::win32_perlio' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00", # [62] 'glob' => "\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [4] 'illegalproto' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00", # [47] 'imprecision' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00", # [46] 'inplace' => "\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [23] 'internal' => "\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [24] 'io' => "\x00\xa8\xaa\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00", # [5..11,57] 'layer' => "\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [8] 'locale' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00", # [63] 'malloc' => "\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [25] 'misc' => "\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [12] 'missing' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00", # [64] 'newline' => "\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [9] 'non_unicode' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00", # [48] 'nonchar' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00", # [49] 'numeric' => "\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [13] 'once' => "\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [14] 'overflow' => "\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [15] 'pack' => "\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [16] 'parenthesis' => "\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [32] 'pipe' => "\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [10] 'portable' => "\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [17] 'precedence' => "\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [33] 'printf' => "\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [34] 'prototype' => "\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [35] 'qw' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [36] 'recursion' => "\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [18] 'redefine' => "\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [19] 'redundant' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00", # [65] 'regexp' => "\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [20] 'reserved' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [37] 'semicolon' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [38] 'severe' => "\x00\x00\x00\x00\x00\xa8\x0a\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [21..25] 'shadow' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00", # [69] 'signal' => "\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [26] 'substr' => "\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [27] 'surrogate' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00", # [50] 'syntax' => "\x00\x00\x00\x00\x00\x00\x00\xaa\xaa\x2a\x00\x80\x00\x00\x00\x00\x00\x00\x00", # [28..38,47] 'syscalls' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00", # [57] 'taint' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [39] 'threads' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00", # [40] 'uninitialized' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x00", # [41] 'unopened' => "\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", # [11] 'unpack' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20\x00\x00\x00\x00\x00\x00\x00\x00", # [42] 'untie' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x80\x00\x00\x00\x00\x00\x00\x00\x00", # [43] 'utf8' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x2a\x00\x00\x00\x00\x00\x00", # [44,48..50] 'void' => "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00", # [45] ); # These are used by various things, including our own tests our $NONE = "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"; our $DEFAULT = "\x10\x01\x00\x00\x00\x50\x04\x00\x00\x00\x00\x00\x00\x55\x51\x55\x50\x51\x05", # [2,4,22,23,25,52..56,58..63,66..68,70..73] our $LAST_BIT = 148 ; our $BYTES = 19 ; sub Croaker { require Carp; # this initializes %CarpInternal local $Carp::CarpInternal{'warnings'}; delete $Carp::CarpInternal{'warnings'}; Carp::croak(@_); } sub _expand_bits { my $bits = shift; my $want_len = ($LAST_BIT + 7) >> 3; my $len = length($bits); if ($len != $want_len) { if ($bits eq "") { $bits = "\x00" x $want_len; } elsif ($len > $want_len) { substr $bits, $want_len, $len-$want_len, ""; } else { my $a = vec($bits, $Offsets{all} >> 1, 2); $a \|= $a << 2; $a \|= $a << 4; $bits .= chr($a) x ($want_len - $len); } } return $bits; } sub _bits { my $mask = shift ; my $catmask ; my $fatal = 0 ; my $no_fatal = 0 ; $mask = _expand_bits($mask); foreach my $word ( @_ ) { if ($word eq 'FATAL') { $fatal = 1; $no_fatal = 0; } elsif ($word eq 'NONFATAL') { $fatal = 0; $no_fatal = 1; } elsif ($catmask = $Bits{$word}) { $mask \|= $catmask ; $mask \|= $DeadBits{$word} if $fatal ; $mask = ~(~$mask \| $DeadBits{$word}) if $no_fatal ; } else { Croaker("Unknown warnings category '$word'")} } return $mask ; } sub bits { # called from B::Deparse.pm push @_, 'all' unless @_ ; return _bits("", @_) ; } sub import { shift; my $mask = ${^WARNING_BITS} // ($^W ? $Bits{all} : $DEFAULT) ; # append 'all' when implied (empty import list or after a lone # "FATAL" or "NONFATAL") push @_, 'all' if !@_ \|\| (@_==1 && ($_[0] eq 'FATAL' \|\| $_[0] eq 'NONFATAL')); ${^WARNING_BITS} = _bits($mask, @_); } sub unimport { shift; my $catmask ; my $mask = ${^WARNING_BITS} // ($^W ? $Bits{all} : $DEFAULT) ; # append 'all' when implied (empty import list or after a lone "FATAL") push @_, 'all' if !@_ \|\| @_==1 && $_[0] eq 'FATAL'; $mask = _expand_bits($mask); foreach my $word ( @_ ) { if ($word eq 'FATAL') { next; } elsif ($catmask = $Bits{$word}) { $mask = ~(~$mask \| $catmask \| $DeadBits{$word}); } else { Croaker("Unknown warnings category '$word'")} } ${^WARNING_BITS} = $mask ; } my %builtin_type; @builtin_type{qw(SCALAR ARRAY HASH CODE REF GLOB LVALUE Regexp)} = (); sub LEVEL () { 8 }; sub MESSAGE () { 4 }; sub FATAL () { 2 }; sub NORMAL () { 1 }; sub __chk { my $category ; my $offset ; my $isobj = 0 ; my $wanted = shift; my $has_message = $wanted & MESSAGE; my $has_level = $wanted & LEVEL ; if ($has_level) { if (@_ != ($has_message ? 3 : 2)) { my $sub = (caller 1)[3]; my $syntax = $has_message ? "category, level, 'message'" : 'category, level'; Croaker("Usage: $sub($syntax)"); } } elsif (not @_ == 1 \|\| @_ == ($has_message ? 2 : 0)) { my $sub = (caller 1)[3]; my $syntax = $has_message ? "[category,] 'message'" : '[category]'; Croaker("Usage: $sub($syntax)"); } my $message = pop if $has_message; if (@_) { # check the category supplied. $category = shift ; if (my $type = ref $category) { Croaker("not an object") if exists $builtin_type{$type}; $category = $type; $isobj = 1 ; } $offset = $Offsets{$category}; Croaker("Unknown warnings category '$category'") unless defined $offset; } else { $category = (caller(1))[0] ; $offset = $Offsets{$category}; Croaker("package '$category' not registered for warnings") unless defined $offset ; } my $i; if ($isobj) { my $pkg; $i = 2; while (do { { package DB; $pkg = (caller($i++))[0] } } ) { last unless @DB::args && $DB::args[0] =~ /^$category=/ ; } $i -= 2 ; } elsif ($has_level) { $i = 2 + shift; } else { $i = _error_loc(); # see where Carp will allocate the error } # Default to 0 if caller returns nothing. Default to $DEFAULT if it # explicitly returns undef. my(@callers_bitmask) = (caller($i))[9] ; my $callers_bitmask = @callers_bitmask ? $callers_bitmask[0] // $DEFAULT : 0 ; length($callers_bitmask) > ($offset >> 3) or $offset = $Offsets{all}; my @results; foreach my $type (FATAL, NORMAL) { next unless $wanted & $type; push @results, vec($callers_bitmask, $offset + $type - 1, 1); } # &enabled and &fatal_enabled return $results[0] unless $has_message; # &warnif, and the category is neither enabled as warning nor as fatal return if ($wanted & (NORMAL \| FATAL \| MESSAGE)) == (NORMAL \| FATAL \| MESSAGE) && !($results[0] \|\| $results[1]); # If we have an explicit level, bypass Carp. if ($has_level and @callers_bitmask) { # logic copied from util.c:mess_sv my $stuff = " at " . join " line ", (caller $i)[1,2]; $stuff .= sprintf ", <%s> %s %d", *${^LAST_FH}{NAME}, ($/ eq "\n" ? "line" : "chunk"), $. if $. && ${^LAST_FH}; die "$message$stuff.\n" if $results[0]; return warn "$message$stuff.\n"; } require Carp; Carp::croak($message) if $results[0]; # will always get here for &warn. will only get here for &warnif if the # category is enabled Carp::carp($message); } sub _mkMask { my ($bit) = @_; my $mask = ""; vec($mask, $bit, 1) = 1; return $mask; } sub register_categories { my @names = @_; for my $name (@names) { if (! defined $Bits{$name}) { $Offsets{$name} = $LAST_BIT; $Bits{$name} = _mkMask($LAST_BIT++); $DeadBits{$name} = _mkMask($LAST_BIT++); if (length($Bits{$name}) > length($Bits{all})) { $Bits{all} .= "\x55"; $DeadBits{all} .= "\xaa"; } } } } sub _error_loc { require Carp; goto &Carp::short_error_loc; # don't introduce another stack frame } sub enabled { return __chk(NORMAL, @_); } sub fatal_enabled { return __chk(FATAL, @_); } sub warn { return __chk(FATAL \| MESSAGE, @_); } sub warnif { return __chk(NORMAL \| FATAL \| MESSAGE, @_); } sub enabled_at_level { return __chk(NORMAL \| LEVEL, @_); } sub fatal_enabled_at_level { return __chk(FATAL \| LEVEL, @_); } sub warn_at_level { return __chk(FATAL \| MESSAGE \| LEVEL, @_); } sub warnif_at_level { return __chk(NORMAL \| FATAL \| MESSAGE \| LEVEL, @_); } # These are not part of any public interface, so we can delete them to save # space. delete @warnings::{qw(NORMAL FATAL MESSAGE LEVEL)}; 1; __END__ =head1 NAME warnings - Perl pragma to control optional warnings =head1 SYNOPSIS use warnings; no warnings; use warnings "all"; no warnings "all"; use warnings::register; if (warnings::enabled()) { warnings::warn("some warning"); } if (warnings::enabled("void")) { warnings::warn("void", "some warning"); } if (warnings::enabled($object)) { warnings::warn($object, "some warning"); } warnings::warnif("some warning"); warnings::warnif("void", "some warning"); warnings::warnif($object, "some warning"); =head1 DESCRIPTION The C<warnings> pragma gives control over which warnings are enabled in which parts of a Perl program. It's a more flexible alternative for both the command line flag B<-w> and the equivalent Perl variable, C<$^W>. This pragma works just like the C<strict> pragma. This means that the scope of the warning pragma is limited to the 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. By default, optional warnings are disabled, so any legacy code that doesn't attempt to control the warnings will work unchanged. All warnings are enabled in a block by either of these: use warnings; use warnings 'all'; Similarly all warnings are disabled in a block by either of these: no warnings; no warnings 'all'; For example, consider the code below: use warnings; my @a; { no warnings; my $b = @a[0]; } 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 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 Before the introduction of lexical warnings, Perl had two classes of warnings: mandatory and optional. As its name suggests, if your code tripped a mandatory warning, you would get a warning whether you wanted it or not. For example, the code below would always produce an C<"isn't numeric"> warning about the "2:". my $a = "2:" + 3; With the introduction of lexical warnings, mandatory warnings now become I<default> warnings. The difference is that although the previously mandatory warnings are still enabled by default, they can then be subsequently enabled or disabled with the lexical warning pragma. For example, in the code below, an C<"isn't numeric"> warning will only be reported for the C<$a> variable. my $a = "2:" + 3; no warnings; my $b = "2:" + 3; Note that neither the B<-w> flag or the C<$^W> can be used to disable/enable default warnings. They are still mandatory in this case. =head2 What's wrong with B<-w> and C<$^W> Although very useful, the big problem with using B<-w> on the command line to enable warnings is that it is all or nothing. Take the typical scenario when you are writing a Perl program. Parts of the code you will write yourself, but it's very likely that you will make use of pre-written Perl modules. If you use the B<-w> flag in this case, you end up enabling warnings in pieces of code that you haven't written. Similarly, using C<$^W> to either disable or enable blocks of code is fundamentally flawed. For a start, say you want to disable warnings in a block of code. You might expect this to be enough to do the trick: { local ($^W) = 0; my $a =+ 2; my $b; chop $b; } When this code is run with the B<-w> flag, a warning will be produced for the C<$a> line: C<"Reversed += operator">. The problem is that Perl has both compile-time and run-time warnings. To disable compile-time warnings you need to rewrite the code like this: { BEGIN { $^W = 0 } my $a =+ 2; my $b; chop $b; } And note that unlike the first example, this will permanently set C<$^W> since it cannot both run during compile-time and be localized to a run-time block. 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 the first will not. sub doit { my $b; chop $b; } doit(); { local ($^W) = 1; doit() } This is a side-effect of C<$^W> being dynamically scoped. Lexical warnings get around these limitations by allowing finer control over where warnings can or can't be tripped. =head2 Controlling Warnings from the Command Line There are three Command Line flags that can be used to control when warnings are (or aren't) produced: =over 5 =item B<-w> X<-w> This is the existing flag. If the lexical warnings pragma is B<not> used in any of you code, or any of the modules that you use, this flag will enable warnings everywhere. See L</Backward Compatibility> for details of how this flag interacts with lexical warnings. =item B<-W> X<-W> If the B<-W> flag is used on the command line, it will enable all warnings throughout the program regardless of whether warnings were disabled locally using C<no warnings> or C<$^W =0>. This includes all files that get included via C<use>, C<require> or C<do>. Think of it as the Perl equivalent of the "lint" command. =item B<-X> X<-X> Does the exact opposite to the B<-W> flag, i.e. it disables all warnings. =back =head2 Backward Compatibility If you are used to working with a version of Perl prior to the introduction of lexically scoped warnings, or have code that uses both lexical warnings and C<$^W>, this section will describe how they interact. How Lexical Warnings interact with B<-w>/C<$^W>: =over 5 =item 1. If none of the three command line flags (B<-w>, B<-W> or B<-X>) that control warnings is used and neither C<$^W> nor the C<warnings> pragma are used, then default warnings will be enabled and optional warnings disabled. This means that legacy code that doesn't attempt to control the warnings will work unchanged. =item 2. The B<-w> flag just sets the global C<$^W> variable as in 5.005. This means that any legacy code that currently relies on manipulating C<$^W> to control warning behavior will still work as is. =item 3. Apart from now being a boolean, the C<$^W> variable operates in exactly the same horrible uncontrolled global way, except that it cannot disable/enable default warnings. =item 4. If a piece of code is under the control of the C<warnings> pragma, both the C<$^W> variable and the B<-w> flag will be ignored for the scope of the lexical warning. =item 5. The only way to override a lexical warnings setting is with the B<-W> or B<-X> command line flags. =back 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. =head2 Category Hierarchy X<warning, categories> A hierarchy of "categories" have been defined to allow groups of warnings to be enabled/disabled in isolation. The current hierarchy is: all -+ \| +- closure \| +- deprecated \| +- exiting \| +- experimental --+ \| \| \| +- experimental::alpha_assertions \| \| \| +- experimental::bitwise \| \| \| +- experimental::const_attr \| \| \| +- experimental::declared_refs \| \| \| +- experimental::isa \| \| \| +- experimental::lexical_subs \| \| \| +- experimental::postderef \| \| \| +- experimental::private_use \| \| \| +- experimental::re_strict \| \| \| +- experimental::refaliasing \| \| \| +- experimental::regex_sets \| \| \| +- experimental::script_run \| \| \| +- experimental::signatures \| \| \| +- experimental::smartmatch \| \| \| +- experimental::uniprop_wildcards \| \| \| +- experimental::vlb \| \| \| +- experimental::win32_perlio \| +- glob \| +- imprecision \| +- io ------------+ \| \| \| +- closed \| \| \| +- exec \| \| \| +- layer \| \| \| +- newline \| \| \| +- pipe \| \| \| +- syscalls \| \| \| +- unopened \| +- locale \| +- misc \| +- missing \| +- numeric \| +- once \| +- overflow \| +- pack \| +- portable \| +- recursion \| +- redefine \| +- redundant \| +- regexp \| +- severe --------+ \| \| \| +- debugging \| \| \| +- inplace \| \| \| +- internal \| \| \| +- malloc \| +- shadow \| +- signal \| +- substr \| +- syntax --------+ \| \| \| +- ambiguous \| \| \| +- bareword \| \| \| +- digit \| \| \| +- illegalproto \| \| \| +- parenthesis \| \| \| +- precedence \| \| \| +- printf \| \| \| +- prototype \| \| \| +- qw \| \| \| +- reserved \| \| \| +- semicolon \| +- taint \| +- threads \| +- uninitialized \| +- unpack \| +- untie \| +- utf8 ----------+ \| \| \| +- non_unicode \| \| \| +- nonchar \| \| \| +- surrogate \| +- void Just like the "strict" pragma any of these categories can be combined use warnings qw(void redefine); no warnings qw(io syntax untie); Also like the "strict" pragma, if there is more than one instance of the C<warnings> pragma in a given scope the cumulative effect is additive. use warnings qw(void); # only "void" warnings enabled ... use warnings qw(io); # only "void" & "io" warnings enabled ... no warnings qw(void); # only "io" warnings enabled To determine which category a specific warning has been assigned to see L<perldiag>. Note: Before Perl 5.8.0, the lexical warnings category "deprecated" was a sub-category of the "syntax" category. It is now a top-level category in its own right. Note: Before 5.21.0, the "missing" lexical warnings category was internally defined to be the same as the "uninitialized" category. It is now a top-level category in its own right. =head2 Fatal Warnings X<warning, fatal> The presence of the word "FATAL" in the category list will escalate warnings in those categories into fatal errors in that lexical scope. B<NOTE:> FATAL warnings should be used with care, particularly C<< FATAL => 'all' >>. Libraries using L<warnings::warn\|/FUNCTIONS> for custom warning categories generally don't expect L<warnings::warn\|/FUNCTIONS> to be fatal and can wind up in an unexpected state as a result. For XS modules issuing categorized warnings, such unanticipated exceptions could also expose memory leak bugs. Moreover, the Perl interpreter itself has had serious bugs involving fatalized warnings. For a summary of resolved and unresolved problems as of January 2015, please see L<this perl5-porters post\|http://www.nntp.perl.org/group/perl.perl5.porters/2015/01/msg225235.html>. While some developers find fatalizing some warnings to be a useful defensive programming technique, using C<< FATAL => 'all' >> to fatalize all possible warning categories -- including custom ones -- is particularly risky. Therefore, the use of C<< FATAL => 'all' >> is L<discouraged\|perlpolicy/discouraged>. The L<strictures\|strictures/VERSION-2> module on CPAN offers one example of a warnings subset that the module's authors believe is relatively safe to fatalize. B<NOTE:> users of FATAL warnings, especially those using C<< FATAL => 'all' >>, should be fully aware that they are risking future portability of their programs by doing so. Perl makes absolutely no commitments to not introduce new warnings or warnings categories in the future; indeed, we explicitly reserve the right to do so. Code that may not warn now may warn in a future release of Perl if the Perl5 development team deems it in the best interests of the community to do so. Should code using FATAL warnings break due to the introduction of a new warning we will NOT consider it an incompatible change. Users of FATAL warnings should take special caution during upgrades to check to see if their code triggers any new warnings and should pay particular attention to the fine print of the documentation of the features they use to ensure they do not exploit features that are documented as risky, deprecated, or unspecified, or where the documentation says "so don't do that", or anything with the same sense and spirit. Use of such features in combination with FATAL warnings is ENTIRELY AT THE USER'S RISK. The following documentation describes how to use FATAL warnings but the perl5 porters strongly recommend that you understand the risks before doing so, especially for library code intended for use by others, as there is no way for downstream users to change the choice of fatal categories. 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; time; { use warnings FATAL => qw(void); length "abc"; } 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 when it encounters the warning. To explicitly turn off a "FATAL" warning you just disable the warning it is associated with. So, for example, to disable the "void" warning in the example above, either of these will do the trick: no warnings qw(void); no warnings FATAL => qw(void); If you want to downgrade a warning that has been escalated into a fatal error back to a normal warning, you can use the "NONFATAL" keyword. For example, the code below will promote all warnings into fatal errors, except for those in the "syntax" category. use warnings FATAL => 'all', NONFATAL => 'syntax'; As of Perl 5.20, instead of C<< use warnings FATAL => 'all'; >> you can use: use v5.20; # Perl 5.20 or greater is required for the following use warnings 'FATAL'; # short form of "use warnings FATAL => 'all';" If you want your program to be compatible with versions of Perl before 5.20, you must use C<< use warnings FATAL => 'all'; >> instead. (In previous versions of Perl, the behavior of the statements C<< use warnings 'FATAL'; >>, C<< use warnings 'NONFATAL'; >> and C<< no warnings 'FATAL'; >> was unspecified; they did not behave as if they included the C<< => 'all' >> portion. As of 5.20, they do.) =head2 Reporting Warnings from a Module X<warning, reporting> X<warning, registering> 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 to a calling module has enabled warnings via the C<warnings> pragma. Consider the module C<MyMod::Abc> below. package MyMod::Abc; use warnings::register; sub open { my $path = shift; if ($path !~ m#^/#) { warnings::warn("changing relative path to /var/abc") if warnings::enabled(); $path = "/var/abc/$path"; } } 1; The call to C<warnings::register> will create a new warnings category 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'; ... abc::open("../fred.txt"); It is also possible to test whether the pre-defined warnings categories are set in the calling module with the C<warnings::enabled> function. Consider this snippet of code: package MyMod::Abc; sub open { if (warnings::enabled("deprecated")) { warnings::warn("deprecated", "open is deprecated, use new instead"); } new(@_); } sub new ... 1; The function C<open> has been deprecated, so code has been included to display a warning message whenever the calling module has (at least) the "deprecated" warnings category enabled. Something like this, say. use warnings 'deprecated'; use MyMod::Abc; ... MyMod::Abc::open($filename); 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::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 = Original->new(); $a->doit(1); my $b = Derived->new(); $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. When registering new categories of warning, you can supply more names to warnings::register like this: package MyModule; use warnings::register qw(format precision); ... warnings::warnif('MyModule::format', '...'); =head1 FUNCTIONS Note: The functions with names ending in C<_at_level> were added in Perl 5.28. =over 4 =item use warnings::register Creates a new warnings category with the same name as the package where the call to the pragma is used. =item warnings::enabled() Use the warnings category with the same name as the current package. Return TRUE if that warnings category is enabled in the calling module. Otherwise returns FALSE. =item warnings::enabled($category) Return TRUE if the warnings category, C<$category>, is enabled in the calling module. Otherwise returns FALSE. =item warnings::enabled($object) Use the name of the class for the object reference, C<$object>, as the warnings category. Return TRUE if that warnings category is enabled in the first scope where the object is used. Otherwise returns FALSE. =item warnings::enabled_at_level($category, $level) Like C<warnings::enabled>, but $level specifies the exact call frame, 0 being the immediate caller. =item warnings::fatal_enabled() Return TRUE if the warnings category with the same name as the current package has been set to FATAL in the calling module. Otherwise returns FALSE. =item warnings::fatal_enabled($category) Return TRUE if the warnings category C<$category> has been set to FATAL in the calling module. Otherwise returns FALSE. =item warnings::fatal_enabled($object) Use the name of the class for the object reference, C<$object>, as the warnings category. Return TRUE if that warnings category has been set to FATAL in the first scope where the object is used. Otherwise returns FALSE. =item warnings::fatal_enabled_at_level($category, $level) Like C<warnings::fatal_enabled>, but $level specifies the exact call frame, 0 being the immediate caller. =item warnings::warn($message) Print C<$message> to STDERR. Use the warnings category with the same name as the current package. If that warnings category has been set to "FATAL" in the calling module then die. Otherwise return. =item warnings::warn($category, $message) Print C<$message> to STDERR. If the warnings category, C<$category>, has been set to "FATAL" in the calling module then die. Otherwise return. =item warnings::warn($object, $message) Print C<$message> to STDERR. Use the name of the class for the object reference, C<$object>, as the warnings category. If that warnings category has been set to "FATAL" in the scope where C<$object> is first used then die. Otherwise return. =item warnings::warn_at_level($category, $level, $message) Like C<warnings::warn>, but $level specifies the exact call frame, 0 being the immediate caller. =item warnings::warnif($message) Equivalent to: if (warnings::enabled()) { warnings::warn($message) } =item warnings::warnif($category, $message) Equivalent to: if (warnings::enabled($category)) { warnings::warn($category, $message) } =item warnings::warnif($object, $message) Equivalent to: if (warnings::enabled($object)) { warnings::warn($object, $message) } =item warnings::warnif_at_level($category, $level, $message) Like C<warnings::warnif>, but $level specifies the exact call frame, 0 being the immediate caller. =item warnings::register_categories(@names) This registers warning categories for the given names and is primarily for use by the warnings::register pragma. =back See also L<perlmodlib/Pragmatic Modules> and L<perldiag>. =cut # ex: set ro:	49.35 KB	2025-07-28 03:53

Edit File:

Terminal