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-03-21 15:55
📁 Carp	-	2025-02-27 15:06
📄 Carp.pm package Carp; { use 5.006; } use strict; use warnings; BEGIN { # Very old versions of warnings.pm load Carp. This can go wrong due # to the circular dependency. If warnings is invoked before Carp, # then warnings starts by loading Carp, then Carp (above) tries to # invoke warnings, and gets nothing because warnings is in the process # of loading and hasn't defined its import method yet. If we were # only turning on warnings ("use warnings" above) this wouldn't be too # bad, because Carp would just gets the state of the -w switch and so # might not get some warnings that it wanted. The real problem is # that we then want to turn off Unicode warnings, but "no warnings # 'utf8'" won't be effective if we're in this circular-dependency # situation. So, if warnings.pm is an affected version, we turn # off all warnings ourselves by directly setting ${^WARNING_BITS}. # On unaffected versions, we turn off just Unicode warnings, via # the proper API. if(!defined($warnings::VERSION) \|\| eval($warnings::VERSION) < 1.06) { ${^WARNING_BITS} = ""; } else { "warnings"->unimport("utf8"); } } sub _fetch_sub { # fetch sub without autovivifying my($pack, $sub) = @_; $pack .= '::'; # only works with top-level packages return unless exists($::{$pack}); for ($::{$pack}) { return unless ref \$_ eq 'GLOB' && $_{HASH} && exists $$_{$sub}; for ($$_{$sub}) { return ref \$_ eq 'GLOB' ? $_{CODE} : undef } } } # UTF8_REGEXP_PROBLEM is a compile-time constant indicating whether Carp # must avoid applying a regular expression to an upgraded (is_utf8) # string. There are multiple problems, on different Perl versions, # that require this to be avoided. All versions prior to 5.13.8 will # load utf8_heavy.pl for the swash system, even if the regexp doesn't # use character classes. Perl 5.6 and Perls [5.11.2, 5.13.11) exhibit # specific problems when Carp is being invoked in the aftermath of a # syntax error. BEGIN { if("$]" < 5.013011) { UTF8_REGEXP_PROBLEM = sub () { 1 }; } else { UTF8_REGEXP_PROBLEM = sub () { 0 }; } } # is_utf8() is essentially the utf8::is_utf8() function, which indicates # whether a string is represented in the upgraded form (using UTF-8 # internally). As utf8::is_utf8() is only available from Perl 5.8 # onwards, extra effort is required here to make it work on Perl 5.6. BEGIN { if(defined(my $sub = _fetch_sub utf8 => 'is_utf8')) { is_utf8 = $sub; } else { # black magic for perl 5.6 is_utf8 = sub { unpack("C", "\xaa".$_[0]) != 170 }; } } # The downgrade() function defined here is to be used for attempts to # downgrade where it is acceptable to fail. It must be called with a # second argument that is a true value. BEGIN { if(defined(my $sub = _fetch_sub utf8 => 'downgrade')) { downgrade = \&{"utf8::downgrade"}; } else { downgrade = sub { my $r = ""; my $l = length($_[0]); for(my $i = 0; $i != $l; $i++) { my $o = ord(substr($_[0], $i, 1)); return if $o > 255; $r .= chr($o); } $_[0] = $r; }; } } # is_safe_printable_codepoint() indicates whether a character, specified # by integer codepoint, is OK to output literally in a trace. Generally # this is if it is a printable character in the ancestral character set # (ASCII or EBCDIC). This is used on some Perls in situations where a # regexp can't be used. BEGIN { is_safe_printable_codepoint = "$]" >= 5.007_003 ? eval(q(sub ($) { my $u = utf8::native_to_unicode($_[0]); $u >= 0x20 && $u <= 0x7e; })) : ord("A") == 65 ? sub ($) { $_[0] >= 0x20 && $_[0] <= 0x7e } : sub ($) { # Early EBCDIC # 3 EBCDIC code pages supported then; all controls but one # are the code points below SPACE. The other one is 0x5F on # POSIX-BC; FF on the other two. # FIXME: there are plenty of unprintable codepoints other # than those that this code and the comment above identifies # as "controls". $_[0] >= ord(" ") && $_[0] <= 0xff && $_[0] != (ord ("^") == 106 ? 0x5f : 0xff); } ; } sub _univ_mod_loaded { return 0 unless exists($::{"UNIVERSAL::"}); for ($::{"UNIVERSAL::"}) { return 0 unless ref \$_ eq "GLOB" && $_{HASH} && exists $$_{"$_[0]::"}; for ($$_{"$_[0]::"}) { return 0 unless ref \$_ eq "GLOB" && $_{HASH} && exists $$_{"VERSION"}; for ($$_{"VERSION"}) { return 0 unless ref \$_ eq "GLOB"; return ${$_{SCALAR}}; } } } } # _maybe_isa() is usually the UNIVERSAL::isa function. We have to avoid # the latter if the UNIVERSAL::isa module has been loaded, to avoid infi- # nite recursion; in that case _maybe_isa simply returns true. my $isa; BEGIN { if (_univ_mod_loaded('isa')) { _maybe_isa = sub { 1 } } else { # Since we have already done the check, record $isa for use below # when defining _StrVal. _maybe_isa = $isa = _fetch_sub(UNIVERSAL => "isa"); } } # We need an overload::StrVal or equivalent function, but we must avoid # loading any modules on demand, as Carp is used from __DIE__ handlers and # may be invoked after a syntax error. # We can copy recent implementations of overload::StrVal and use # overloading.pm, which is the fastest implementation, so long as # overloading is available. If it is not available, we use our own pure- # Perl StrVal. We never actually use overload::StrVal, for various rea- # sons described below. # overload versions are as follows: # undef-1.00 (up to perl 5.8.0) uses bless (avoid!) # 1.01-1.17 (perl 5.8.1 to 5.14) uses Scalar::Util # 1.18+ (perl 5.16+) uses overloading # The ancient 'bless' implementation (that inspires our pure-Perl version) # blesses unblessed references and must be avoided. Those using # Scalar::Util use refaddr, possibly the pure-Perl implementation, which # has the same blessing bug, and must be avoided. Also, Scalar::Util is # loaded on demand. Since we avoid the Scalar::Util implementations, we # end up having to implement our own overloading.pm-based version for perl # 5.10.1 to 5.14. Since it also works just as well in more recent ver- # sions, we use it there, too. BEGIN { if (eval { require "overloading.pm" }) { _StrVal = eval 'sub { no overloading; "$_[0]" }' } else { # Work around the UNIVERSAL::can/isa modules to avoid recursion. # _mycan is either UNIVERSAL::can, or, in the presence of an # override, overload::mycan. _mycan = _univ_mod_loaded('can') ? do { require "overload.pm"; _fetch_sub overload => 'mycan' } : \&UNIVERSAL::can; # _blessed is either UNIVERAL::isa(...), or, in the presence of an # override, a hideous, but fairly reliable, workaround. _blessed = $isa ? sub { &$isa($_[0], "UNIVERSAL") } : sub { my $probe = "UNIVERSAL::Carp_probe_" . rand; no strict 'refs'; local $probe = sub { "unlikely string" }; local $@; local $SIG{__DIE__} = sub{}; (eval { $_[0]->$probe } \|\| '') eq 'unlikely string' }; _StrVal = sub { my $pack = ref $_[0]; # Perl's overload mechanism uses the presence of a special # "method" named "((" or "()" to signal it is in effect. # This test seeks to see if it has been set up. "((" post- # dates overloading.pm, so we can skip it. return "$_[0]" unless _mycan($pack, "()"); # Even at this point, the invocant may not be blessed, so # check for that. return "$_[0]" if not _blessed($_[0]); bless $_[0], "Carp"; my $str = "$_[0]"; bless $_[0], $pack; $pack . substr $str, index $str, "="; } } } our $VERSION = '1.50'; $VERSION =~ tr/_//d; our $MaxEvalLen = 0; our $Verbose = 0; our $CarpLevel = 0; our $MaxArgLen = 64; # How much of each argument to print. 0 = all. our $MaxArgNums = 8; # How many arguments to print. 0 = all. our $RefArgFormatter = undef; # allow caller to format reference arguments require Exporter; our @ISA = ('Exporter'); our @EXPORT = qw(confess croak carp); our @EXPORT_OK = qw(cluck verbose longmess shortmess); our @EXPORT_FAIL = qw(verbose); # hook to enable verbose mode # The members of %Internal are packages that are internal to perl. # Carp will not report errors from within these packages if it # can. The members of %CarpInternal are internal to Perl's warning # system. Carp will not report errors from within these packages # either, and will not report calls to* these packages for carp and # croak. They replace $CarpLevel, which is deprecated. The # $Max(EvalLen\|(Arg(Len\|Nums)) variables are used to specify how the eval # text and function arguments should be formatted when printed. our %CarpInternal; our %Internal; # disable these by default, so they can live w/o require Carp $CarpInternal{Carp}++; $CarpInternal{warnings}++; $Internal{Exporter}++; $Internal{'Exporter::Heavy'}++; # if the caller specifies verbose usage ("perl -MCarp=verbose script.pl") # then the following method will be called by the Exporter which knows # to do this thanks to @EXPORT_FAIL, above. $_[1] will contain the word # 'verbose'. sub export_fail { shift; $Verbose = shift if $_[0] eq 'verbose'; @_ } sub _cgc { no strict 'refs'; return \&{"CORE::GLOBAL::caller"} if defined &{"CORE::GLOBAL::caller"}; return; } sub longmess { local($!, $^E); # Icky backwards compatibility wrapper. :-( # # The story is that the original implementation hard-coded the # number of call levels to go back, so calls to longmess were off # by one. Other code began calling longmess and expecting this # behaviour, so the replacement has to emulate that behaviour. my $cgc = _cgc(); my $call_pack = $cgc ? $cgc->() : caller(); if ( $Internal{$call_pack} or $CarpInternal{$call_pack} ) { return longmess_heavy(@_); } else { local $CarpLevel = $CarpLevel + 1; return longmess_heavy(@_); } } our @CARP_NOT; sub shortmess { local($!, $^E); my $cgc = _cgc(); # Icky backwards compatibility wrapper. :-( local @CARP_NOT = $cgc ? $cgc->() : caller(); shortmess_heavy(@_); } sub croak { die shortmess @_ } sub confess { die longmess @_ } sub carp { warn shortmess @_ } sub cluck { warn longmess @_ } BEGIN { if("$]" >= 5.015002 \|\| ("$]" >= 5.014002 && "$]" < 5.015) \|\| ("$]" >= 5.012005 && "$]" < 5.013)) { CALLER_OVERRIDE_CHECK_OK = sub () { 1 }; } else { CALLER_OVERRIDE_CHECK_OK = sub () { 0 }; } } sub caller_info { my $i = shift(@_) + 1; my %call_info; my $cgc = _cgc(); { # Some things override caller() but forget to implement the # @DB::args part of it, which we need. We check for this by # pre-populating @DB::args with a sentinel which no-one else # has the address of, so that we can detect whether @DB::args # has been properly populated. However, on earlier versions # of perl this check tickles a bug in CORE::caller() which # leaks memory. So we only check on fixed perls. @DB::args = \$i if CALLER_OVERRIDE_CHECK_OK; package DB; @call_info{ qw(pack file line sub has_args wantarray evaltext is_require) } = $cgc ? $cgc->($i) : caller($i); } unless ( defined $call_info{file} ) { return (); } my $sub_name = Carp::get_subname( \%call_info ); if ( $call_info{has_args} ) { # Guard our serialization of the stack from stack refcounting bugs # NOTE this is NOT a complete solution, we cannot 100% guard against # these bugs. However in many cases Perl is capable of detecting # them and throws an error when it does. Unfortunately serializing # the arguments on the stack is a perfect way of finding these bugs, # even when they would not affect normal program flow that did not # poke around inside the stack. Inside of Carp.pm it makes little # sense reporting these bugs, as Carp's job is to report the callers # errors, not the ones it might happen to tickle while doing so. # See: https://rt.perl.org/Public/Bug/Display.html?id=131046 # and: https://rt.perl.org/Public/Bug/Display.html?id=52610 # for more details and discussion. - Yves my @args = map { my $arg; local $@= $@; eval { $arg = $_; 1; } or do { $arg = ' argument not available anymore '; }; $arg; } @DB::args; if (CALLER_OVERRIDE_CHECK_OK && @args == 1 && ref $args[0] eq ref \$i && $args[0] == \$i ) { @args = (); # Don't let anyone see the address of $i local $@; my $where = eval { my $func = $cgc or return ''; my $gv = (_fetch_sub B => 'svref_2object' or return '') ->($func)->GV; my $package = $gv->STASH->NAME; my $subname = $gv->NAME; return unless defined $package && defined $subname; # returning CORE::GLOBAL::caller isn't useful for tracing the cause: return if $package eq 'CORE::GLOBAL' && $subname eq 'caller'; " in &${package}::$subname"; } \|\| ''; @args = " Incomplete caller override detected$where; \@DB::args were not set "; } else { my $overflow; if ( $MaxArgNums and @args > $MaxArgNums ) { # More than we want to show? $#args = $MaxArgNums - 1; $overflow = 1; } @args = map { Carp::format_arg($_) } @args; if ($overflow) { push @args, '...'; } } # Push the args onto the subroutine $sub_name .= '(' . join( ', ', @args ) . ')'; } $call_info{sub_name} = $sub_name; return wantarray() ? %call_info : \%call_info; } # Transform an argument to a function into a string. our $in_recurse; sub format_arg { my $arg = shift; if ( my $pack= ref($arg) ) { # legitimate, let's not leak it. if (!$in_recurse && _maybe_isa( $arg, 'UNIVERSAL' ) && do { local $@; local $in_recurse = 1; local $SIG{__DIE__} = sub{}; eval {$arg->can('CARP_TRACE') } }) { return $arg->CARP_TRACE(); } elsif (!$in_recurse && defined($RefArgFormatter) && do { local $@; local $in_recurse = 1; local $SIG{__DIE__} = sub{}; eval {$arg = $RefArgFormatter->($arg); 1} }) { return $arg; } else { # Argument may be blessed into a class with overloading, and so # might have an overloaded stringification. We don't want to # risk getting the overloaded stringification, so we need to # use _StrVal, our overload::StrVal()-equivalent. return _StrVal $arg; } } return "undef" if !defined($arg); downgrade($arg, 1); return $arg if !(UTF8_REGEXP_PROBLEM && is_utf8($arg)) && $arg =~ /\A-?[0-9]+(?:\.[0-9])?(?:[eE][-+]?[0-9]+)?\z/; my $suffix = ""; if ( 2 < $MaxArgLen and $MaxArgLen < length($arg) ) { substr ( $arg, $MaxArgLen - 3 ) = ""; $suffix = "..."; } if(UTF8_REGEXP_PROBLEM && is_utf8($arg)) { for(my $i = length($arg); $i--; ) { my $c = substr($arg, $i, 1); my $x = substr($arg, 0, 0); # work around bug on Perl 5.8.{1,2} if($c eq "\"" \|\| $c eq "\\" \|\| $c eq "\$" \|\| $c eq "\@") { substr $arg, $i, 0, "\\"; next; } my $o = ord($c); substr $arg, $i, 1, sprintf("\\x{%x}", $o) unless is_safe_printable_codepoint($o); } } else { $arg =~ s/([\"\\\$\@])/\\$1/g; # This is all the ASCII printables spelled-out. It is portable to all # Perl versions and platforms (such as EBCDIC). There are other more # compact ways to do this, but may not work everywhere every version. $arg =~ s/([^ !"#\$\%\&'()+,\-.\/0123456789:;<=>?\@ABCDEFGHIJKLMNOPQRSTUVWXYZ\[\\\]^_`abcdefghijklmnopqrstuvwxyz\{\|}~])/sprintf("\\x{%x}",ord($1))/eg; } downgrade($arg, 1); return "\"".$arg."\"".$suffix; } sub Regexp::CARP_TRACE { my $arg = "$_[0]"; downgrade($arg, 1); if(UTF8_REGEXP_PROBLEM && is_utf8($arg)) { for(my $i = length($arg); $i--; ) { my $o = ord(substr($arg, $i, 1)); my $x = substr($arg, 0, 0); # work around bug on Perl 5.8.{1,2} substr $arg, $i, 1, sprintf("\\x{%x}", $o) unless is_safe_printable_codepoint($o); } } else { # See comment in format_arg() about this same regex. $arg =~ s/([^ !"#\$\%\&'()+,\-.\/0123456789:;<=>?\@ABCDEFGHIJKLMNOPQRSTUVWXYZ\[\\\]^_`abcdefghijklmnopqrstuvwxyz\{\|}~])/sprintf("\\x{%x}",ord($1))/eg; } downgrade($arg, 1); my $suffix = ""; if($arg =~ /\A$\?\^?([a-z])(?:-[a-z])?:(.)$\z/s) { ($suffix, $arg) = ($1, $2); } if ( 2 < $MaxArgLen and $MaxArgLen < length($arg) ) { substr ( $arg, $MaxArgLen - 3 ) = ""; $suffix = "...".$suffix; } return "qr($arg)$suffix"; } # Takes an inheritance cache and a package and returns # an anon hash of known inheritances and anon array of # inheritances which consequences have not been figured # for. sub get_status { my $cache = shift; my $pkg = shift; $cache->{$pkg} \|\|= [ { $pkg => $pkg }, [ trusts_directly($pkg) ] ]; return @{ $cache->{$pkg} }; } # Takes the info from caller() and figures out the name of # the sub/require/eval sub get_subname { my $info = shift; if ( defined( $info->{evaltext} ) ) { my $eval = $info->{evaltext}; if ( $info->{is_require} ) { return "require $eval"; } else { $eval =~ s/([\\\'])/\\$1/g; return "eval '" . str_len_trim( $eval, $MaxEvalLen ) . "'"; } } # this can happen on older perls when the sub (or the stash containing it) # has been deleted if ( !defined( $info->{sub} ) ) { return '__ANON__::__ANON__'; } return ( $info->{sub} eq '(eval)' ) ? 'eval {...}' : $info->{sub}; } # Figures out what call (from the point of view of the caller) # the long error backtrace should start at. sub long_error_loc { my $i; my $lvl = $CarpLevel; { ++$i; my $cgc = _cgc(); my @caller = $cgc ? $cgc->($i) : caller($i); my $pkg = $caller[0]; unless ( defined($pkg) ) { # This shouldn't happen. if (%Internal) { local %Internal; $i = long_error_loc(); last; } elsif (defined $caller[2]) { # this can happen when the stash has been deleted # in that case, just assume that it's a reasonable place to # stop (the file and line data will still be intact in any # case) - the only issue is that we can't detect if the # deleted package was internal (so don't do that then) # -doy redo unless 0 > --$lvl; last; } else { return 2; } } redo if $CarpInternal{$pkg}; redo unless 0 > --$lvl; redo if $Internal{$pkg}; } return $i - 1; } sub longmess_heavy { if ( ref( $_[0] ) ) { # don't break references as exceptions return wantarray ? @_ : $_[0]; } my $i = long_error_loc(); return ret_backtrace( $i, @_ ); } BEGIN { if("$]" >= 5.017004) { # The LAST_FH constant is a reference to the variable. $Carp::{LAST_FH} = \eval '\${^LAST_FH}'; } else { eval 'LAST_FH = sub () { 0 }'; } } # Returns a full stack backtrace starting from where it is # told. sub ret_backtrace { my ( $i, @error ) = @_; my $mess; my $err = join '', @error; $i++; my $tid_msg = ''; if ( defined &threads::tid ) { my $tid = threads->tid; $tid_msg = " thread $tid" if $tid; } my %i = caller_info($i); $mess = "$err at $i{file} line $i{line}$tid_msg"; if( $. ) { # Use ${^LAST_FH} if available. if (LAST_FH) { if (${+LAST_FH}) { $mess .= sprintf ", <%s> %s %d", ${+LAST_FH}{NAME}, ($/ eq "\n" ? "line" : "chunk"), $. } } else { local $@ = ''; local $SIG{__DIE__}; eval { CORE::die; }; if($@ =~ /^Died at .(, <.?> (?:line\|chunk) \d+).$/ ) { $mess .= $1; } } } $mess .= "\.\n"; while ( my %i = caller_info( ++$i ) ) { $mess .= "\t$i{sub_name} called at $i{file} line $i{line}$tid_msg\n"; } return $mess; } sub ret_summary { my ( $i, @error ) = @_; my $err = join '', @error; $i++; my $tid_msg = ''; if ( defined &threads::tid ) { my $tid = threads->tid; $tid_msg = " thread $tid" if $tid; } my %i = caller_info($i); return "$err at $i{file} line $i{line}$tid_msg\.\n"; } sub short_error_loc { # You have to create your (hash)ref out here, rather than defaulting it # inside trusts on a lexical, as you want it to persist across calls. # (You can default it on $_[2], but that gets messy) my $cache = {}; my $i = 1; my $lvl = $CarpLevel; { my $cgc = _cgc(); my $called = $cgc ? $cgc->($i) : caller($i); $i++; my $caller = $cgc ? $cgc->($i) : caller($i); if (!defined($caller)) { my @caller = $cgc ? $cgc->($i) : caller($i); if (@caller) { # if there's no package but there is other caller info, then # the package has been deleted - treat this as a valid package # in this case redo if defined($called) && $CarpInternal{$called}; redo unless 0 > --$lvl; last; } else { return 0; } } redo if $Internal{$caller}; redo if $CarpInternal{$caller}; redo if $CarpInternal{$called}; redo if trusts( $called, $caller, $cache ); redo if trusts( $caller, $called, $cache ); redo unless 0 > --$lvl; } return $i - 1; } sub shortmess_heavy { return longmess_heavy(@_) if $Verbose; return @_ if ref( $_[0] ); # don't break references as exceptions my $i = short_error_loc(); if ($i) { ret_summary( $i, @_ ); } else { longmess_heavy(@_); } } # If a string is too long, trims it with ... sub str_len_trim { my $str = shift; my $max = shift \|\| 0; if ( 2 < $max and $max < length($str) ) { substr( $str, $max - 3 ) = '...'; } return $str; } # Takes two packages and an optional cache. Says whether the # first inherits from the second. # # Recursive versions of this have to work to avoid certain # possible endless loops, and when following long chains of # inheritance are less efficient. sub trusts { my $child = shift; my $parent = shift; my $cache = shift; my ( $known, $partial ) = get_status( $cache, $child ); # Figure out consequences until we have an answer while ( @$partial and not exists $known->{$parent} ) { my $anc = shift @$partial; next if exists $known->{$anc}; $known->{$anc}++; my ( $anc_knows, $anc_partial ) = get_status( $cache, $anc ); my @found = keys %$anc_knows; @$known{@found} = (); push @$partial, @$anc_partial; } return exists $known->{$parent}; } # Takes a package and gives a list of those trusted directly sub trusts_directly { my $class = shift; no strict 'refs'; my $stash = \%{"$class\::"}; for my $var (qw/ CARP_NOT ISA /) { # Don't try using the variable until we know it exists, # to avoid polluting the caller's namespace. if ( $stash->{$var} && ref \$stash->{$var} eq 'GLOB' && {$stash->{$var}}{ARRAY} && @{$stash->{$var}} ) { return @{$stash->{$var}} } } return; } if(!defined($warnings::VERSION) \|\| do { no warnings "numeric"; $warnings::VERSION < 1.03 }) { # Very old versions of warnings.pm import from Carp. This can go # wrong due to the circular dependency. If Carp is invoked before # warnings, then Carp starts by loading warnings, then warnings # tries to import from Carp, and gets nothing because Carp is in # the process of loading and hasn't defined its import method yet. # So we work around that by manually exporting to warnings here. no strict "refs"; {"warnings::$_"} = \&$_ foreach @EXPORT; } 1; __END__ =head1 NAME Carp - alternative warn and die for modules =head1 SYNOPSIS use Carp; # warn user (from perspective of caller) carp "string trimmed to 80 chars"; # die of errors (from perspective of caller) croak "We're outta here!"; # die of errors with stack backtrace confess "not implemented"; # cluck, longmess and shortmess not exported by default use Carp qw(cluck longmess shortmess); cluck "This is how we got here!"; # warn with stack backtrace $long_message = longmess( "message from cluck() or confess()" ); $short_message = shortmess( "message from carp() or croak()" ); =head1 DESCRIPTION The Carp routines are useful in your own modules because they act like C<die()> or C<warn()>, but with a message which is more likely to be useful to a user of your module. In the case of C<cluck()> and C<confess()>, that context is a summary of every call in the call-stack; C<longmess()> returns the contents of the error message. For a shorter message you can use C<carp()> or C<croak()> which report the error as being from where your module was called. C<shortmess()> returns the contents of this error message. There is no guarantee that that is where the error was, but it is a good educated guess. C<Carp> takes care not to clobber the status variables C<$!> and C<$^E> in the course of assembling its error messages. This means that a C<$SIG{__DIE__}> or C<$SIG{__WARN__}> handler can capture the error information held in those variables, if it is required to augment the error message, and if the code calling C<Carp> left useful values there. Of course, C<Carp> can't guarantee the latter. You can also alter the way the output and logic of C<Carp> works, by changing some global variables in the C<Carp> namespace. See the section on C<GLOBAL VARIABLES> below. Here is a more complete description of how C<carp> and C<croak> work. What they do is search the call-stack for a function call stack where they have not been told that there shouldn't be an error. If every call is marked safe, they give up and give a full stack backtrace instead. In other words they presume that the first likely looking potential suspect is guilty. Their rules for telling whether a call shouldn't generate errors work as follows: =over 4 =item 1. Any call from a package to itself is safe. =item 2. Packages claim that there won't be errors on calls to or from packages explicitly marked as safe by inclusion in C<@CARP_NOT>, or (if that array is empty) C<@ISA>. The ability to override what @ISA says is new in 5.8. =item 3. The trust in item 2 is transitive. If A trusts B, and B trusts C, then A trusts C. So if you do not override C<@ISA> with C<@CARP_NOT>, then this trust relationship is identical to, "inherits from". =item 4. Any call from an internal Perl module is safe. (Nothing keeps user modules from marking themselves as internal to Perl, but this practice is discouraged.) =item 5. Any call to Perl's warning system (eg Carp itself) is safe. (This rule is what keeps it from reporting the error at the point where you call C<carp> or C<croak>.) =item 6. C<$Carp::CarpLevel> can be set to skip a fixed number of additional call levels. Using this is not recommended because it is very difficult to get it to behave correctly. =back =head2 Forcing a Stack Trace As a debugging aid, you can force Carp to treat a croak as a confess and a carp as a cluck across I<all> modules. In other words, force a detailed stack trace to be given. This can be very helpful when trying to understand why, or from where, a warning or error is being generated. This feature is enabled by 'importing' the non-existent symbol 'verbose'. You would typically enable it by saying perl -MCarp=verbose script.pl or by including the string C<-MCarp=verbose> in the PERL5OPT environment variable. Alternately, you can set the global variable C<$Carp::Verbose> to true. See the C<GLOBAL VARIABLES> section below. =head2 Stack Trace formatting At each stack level, the subroutine's name is displayed along with its parameters. For simple scalars, this is sufficient. For complex data types, such as objects and other references, this can simply display C<'HASH(0x1ab36d8)'>. Carp gives two ways to control this. =over 4 =item 1. For objects, a method, C<CARP_TRACE>, will be called, if it exists. If this method doesn't exist, or it recurses into C<Carp>, or it otherwise throws an exception, this is skipped, and Carp moves on to the next option, otherwise checking stops and the string returned is used. It is recommended that the object's type is part of the string to make debugging easier. =item 2. For any type of reference, C<$Carp::RefArgFormatter> is checked (see below). This variable is expected to be a code reference, and the current parameter is passed in. If this function doesn't exist (the variable is undef), or it recurses into C<Carp>, or it otherwise throws an exception, this is skipped, and Carp moves on to the next option, otherwise checking stops and the string returned is used. =item 3. Otherwise, if neither C<CARP_TRACE> nor C<$Carp::RefArgFormatter> is available, stringify the value ignoring any overloading. =back =head1 GLOBAL VARIABLES =head2 $Carp::MaxEvalLen This variable determines how many characters of a string-eval are to be shown in the output. Use a value of C<0> to show all text. Defaults to C<0>. =head2 $Carp::MaxArgLen This variable determines how many characters of each argument to a function to print. Use a value of C<0> to show the full length of the argument. Defaults to C<64>. =head2 $Carp::MaxArgNums This variable determines how many arguments to each function to show. Use a false value to show all arguments to a function call. To suppress all arguments, use C<-1> or C<'0 but true'>. Defaults to C<8>. =head2 $Carp::Verbose This variable makes C<carp()> and C<croak()> generate stack backtraces just like C<cluck()> and C<confess()>. This is how C<use Carp 'verbose'> is implemented internally. Defaults to C<0>. =head2 $Carp::RefArgFormatter This variable sets a general argument formatter to display references. Plain scalars and objects that implement C<CARP_TRACE> will not go through this formatter. Calling C<Carp> from within this function is not supported. local $Carp::RefArgFormatter = sub { require Data::Dumper; Data::Dumper::Dump($_[0]); # not necessarily safe }; =head2 @CARP_NOT This variable, I<in your package>, says which packages are I<not> to be considered as the location of an error. The C<carp()> and C<cluck()> functions will skip over callers when reporting where an error occurred. NB: This variable must be in the package's symbol table, thus: # These work our @CARP_NOT; # file scope use vars qw(@CARP_NOT); # package scope @My::Package::CARP_NOT = ... ; # explicit package variable # These don't work sub xyz { ... @CARP_NOT = ... } # w/o declarations above my @CARP_NOT; # even at top-level Example of use: package My::Carping::Package; use Carp; our @CARP_NOT; sub bar { .... or _error('Wrong input') } sub _error { # temporary control of where'ness, __PACKAGE__ is implicit local @CARP_NOT = qw(My::Friendly::Caller); carp(@_) } This would make C<Carp> report the error as coming from a caller not in C<My::Carping::Package>, nor from C<My::Friendly::Caller>. Also read the L</DESCRIPTION> section above, about how C<Carp> decides where the error is reported from. Use C<@CARP_NOT>, instead of C<$Carp::CarpLevel>. Overrides C<Carp>'s use of C<@ISA>. =head2 %Carp::Internal This says what packages are internal to Perl. C<Carp> will never report an error as being from a line in a package that is internal to Perl. For example: $Carp::Internal{ (__PACKAGE__) }++; # time passes... sub foo { ... or confess("whatever") }; would give a full stack backtrace starting from the first caller outside of __PACKAGE__. (Unless that package was also internal to Perl.) =head2 %Carp::CarpInternal This says which packages are internal to Perl's warning system. For generating a full stack backtrace this is the same as being internal to Perl, the stack backtrace will not start inside packages that are listed in C<%Carp::CarpInternal>. But it is slightly different for the summary message generated by C<carp> or C<croak>. There errors will not be reported on any lines that are calling packages in C<%Carp::CarpInternal>. For example C<Carp> itself is listed in C<%Carp::CarpInternal>. Therefore the full stack backtrace from C<confess> will not start inside of C<Carp>, and the short message from calling C<croak> is not placed on the line where C<croak> was called. =head2 $Carp::CarpLevel This variable determines how many additional call frames are to be skipped that would not otherwise be when reporting where an error occurred on a call to one of C<Carp>'s functions. It is fairly easy to count these call frames on calls that generate a full stack backtrace. However it is much harder to do this accounting for calls that generate a short message. Usually people skip too many call frames. If they are lucky they skip enough that C<Carp> goes all of the way through the call stack, realizes that something is wrong, and then generates a full stack backtrace. If they are unlucky then the error is reported from somewhere misleading very high in the call stack. Therefore it is best to avoid C<$Carp::CarpLevel>. Instead use C<@CARP_NOT>, C<%Carp::Internal> and C<%Carp::CarpInternal>. Defaults to C<0>. =head1 BUGS The Carp routines don't handle exception objects currently. If called with a first argument that is a reference, they simply call die() or warn(), as appropriate. =head1 SEE ALSO L<Carp::Always>, L<Carp::Clan> =head1 CONTRIBUTING L<Carp> is maintained by the perl 5 porters as part of the core perl 5 version control repository. Please see the L<perlhack> perldoc for how to submit patches and contribute to it. =head1 AUTHOR The Carp module first appeared in Larry Wall's perl 5.000 distribution. Since then it has been modified by several of the perl 5 porters. Andrew Main (Zefram) <zefram@fysh.org> divested Carp into an independent distribution. =head1 COPYRIGHT Copyright (C) 1994-2013 Larry Wall Copyright (C) 2011, 2012, 2013 Andrew Main (Zefram) <zefram@fysh.org> =head1 LICENSE This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.	35.12 KB	2018-06-27 11:17
📁 Digest	-	2025-02-27 15:06
📄 Digest.pm package Digest; use strict; use warnings; our $VERSION = "1.19"; our %MMAP = ( "SHA-1" => [ [ "Digest::SHA", 1 ], "Digest::SHA1", [ "Digest::SHA2", 1 ] ], "SHA-224" => [ [ "Digest::SHA", 224 ] ], "SHA-256" => [ [ "Digest::SHA", 256 ], [ "Digest::SHA2", 256 ] ], "SHA-384" => [ [ "Digest::SHA", 384 ], [ "Digest::SHA2", 384 ] ], "SHA-512" => [ [ "Digest::SHA", 512 ], [ "Digest::SHA2", 512 ] ], "SHA3-224" => [ [ "Digest::SHA3", 224 ] ], "SHA3-256" => [ [ "Digest::SHA3", 256 ] ], "SHA3-384" => [ [ "Digest::SHA3", 384 ] ], "SHA3-512" => [ [ "Digest::SHA3", 512 ] ], "HMAC-MD5" => "Digest::HMAC_MD5", "HMAC-SHA-1" => "Digest::HMAC_SHA1", "CRC-16" => [ [ "Digest::CRC", type => "crc16" ] ], "CRC-32" => [ [ "Digest::CRC", type => "crc32" ] ], "CRC-CCITT" => [ [ "Digest::CRC", type => "crcccitt" ] ], "RIPEMD-160" => "Crypt::RIPEMD160", ); sub new { shift; # class ignored my $algorithm = shift; my $impl = $MMAP{$algorithm} \|\| do { $algorithm =~ s/\W+//g; "Digest::$algorithm"; }; $impl = [$impl] unless ref($impl); local $@; # don't clobber it for our caller my $err; for (@$impl) { my $class = $_; my @args; ( $class, @args ) = @$class if ref($class); no strict 'refs'; unless ( exists ${"$class\::"}{"VERSION"} ) { my $pm_file = $class . ".pm"; $pm_file =~ s{::}{/}g; eval { local @INC = @INC; pop @INC if $INC[-1] eq '.'; require $pm_file }; if ($@) { $err \|\|= $@; next; } } return $class->new( @args, @_ ); } die $err; } our $AUTOLOAD; sub AUTOLOAD { my $class = shift; my $algorithm = substr( $AUTOLOAD, rindex( $AUTOLOAD, '::' ) + 2 ); $class->new( $algorithm, @_ ); } 1; __END__ =head1 NAME Digest - Modules that calculate message digests =head1 SYNOPSIS $md5 = Digest->new("MD5"); $sha1 = Digest->new("SHA-1"); $sha256 = Digest->new("SHA-256"); $sha384 = Digest->new("SHA-384"); $sha512 = Digest->new("SHA-512"); $hmac = Digest->HMAC_MD5($key); =head1 DESCRIPTION The C<Digest::> modules calculate digests, also called "fingerprints" or "hashes", of some data, called a message. The digest is (usually) some small/fixed size string. The actual size of the digest depend of the algorithm used. The message is simply a sequence of arbitrary bytes or bits. An important property of the digest algorithms is that the digest is I<likely> to change if the message change in some way. Another property is that digest functions are one-way functions, that is it should be I<hard> to find a message that correspond to some given digest. Algorithms differ in how "likely" and how "hard", as well as how efficient they are to compute. Note that the properties of the algorithms change over time, as the algorithms are analyzed and machines grow faster. If your application for instance depends on it being "impossible" to generate the same digest for a different message it is wise to make it easy to plug in stronger algorithms as the one used grow weaker. Using the interface documented here should make it easy to change algorithms later. All C<Digest::> modules provide the same programming interface. A functional interface for simple use, as well as an object oriented interface that can handle messages of arbitrary length and which can read files directly. The digest can be delivered in three formats: =over 8 =item I<binary> This is the most compact form, but it is not well suited for printing or embedding in places that can't handle arbitrary data. =item I<hex> A twice as long string of lowercase hexadecimal digits. =item I<base64> A string of portable printable characters. This is the base64 encoded representation of the digest with any trailing padding removed. The string will be about 30% longer than the binary version. L<MIME::Base64> tells you more about this encoding. =back The functional interface is simply importable functions with the same name as the algorithm. The functions take the message as argument and return the digest. Example: use Digest::MD5 qw(md5); $digest = md5($message); There are also versions of the functions with "_hex" or "_base64" appended to the name, which returns the digest in the indicated form. =head1 OO INTERFACE The following methods are available for all C<Digest::> modules: =over 4 =item $ctx = Digest->XXX($arg,...) =item $ctx = Digest->new(XXX => $arg,...) =item $ctx = Digest::XXX->new($arg,...) The constructor returns some object that encapsulate the state of the message-digest algorithm. You can add data to the object and finally ask for the digest. The "XXX" should of course be replaced by the proper name of the digest algorithm you want to use. The two first forms are simply syntactic sugar which automatically load the right module on first use. The second form allow you to use algorithm names which contains letters which are not legal perl identifiers, e.g. "SHA-1". If no implementation for the given algorithm can be found, then an exception is raised. To know what arguments (if any) the constructor takes (the C<$args,...> above) consult the docs for the specific digest implementation. If new() is called as an instance method (i.e. $ctx->new) it will just reset the state the object to the state of a newly created object. No new object is created in this case, and the return value is the reference to the object (i.e. $ctx). =item $other_ctx = $ctx->clone The clone method creates a copy of the digest state object and returns a reference to the copy. =item $ctx->reset This is just an alias for $ctx->new. =item $ctx->add( $data ) =item $ctx->add( $chunk1, $chunk2, ... ) The string value of the $data provided as argument is appended to the message we calculate the digest for. The return value is the $ctx object itself. If more arguments are provided then they are all appended to the message, thus all these lines will have the same effect on the state of the $ctx object: $ctx->add("a"); $ctx->add("b"); $ctx->add("c"); $ctx->add("a")->add("b")->add("c"); $ctx->add("a", "b", "c"); $ctx->add("abc"); Most algorithms are only defined for strings of bytes and this method might therefore croak if the provided arguments contain chars with ordinal number above 255. =item $ctx->addfile( $io_handle ) The $io_handle is read until EOF and the content is appended to the message we calculate the digest for. The return value is the $ctx object itself. The addfile() method will croak() if it fails reading data for some reason. If it croaks it is unpredictable what the state of the $ctx object will be in. The addfile() method might have been able to read the file partially before it failed. It is probably wise to discard or reset the $ctx object if this occurs. In most cases you want to make sure that the $io_handle is in "binmode" before you pass it as argument to the addfile() method. =item $ctx->add_bits( $data, $nbits ) =item $ctx->add_bits( $bitstring ) The add_bits() method is an alternative to add() that allow partial bytes to be appended to the message. Most users can just ignore this method since typical applications involve only whole-byte data. The two argument form of add_bits() will add the first $nbits bits from $data. For the last potentially partial byte only the high order C<< $nbits % 8 >> bits are used. If $nbits is greater than C<< length($data) * 8 >>, then this method would do the same as C<< $ctx->add($data) >>. The one argument form of add_bits() takes a $bitstring of "1" and "0" chars as argument. It's a shorthand for C<< $ctx->add_bits(pack("B*", $bitstring), length($bitstring)) >>. The return value is the $ctx object itself. This example shows two calls that should have the same effect: $ctx->add_bits("111100001010"); $ctx->add_bits("\xF0\xA0", 12); Most digest algorithms are byte based and for these it is not possible to add bits that are not a multiple of 8, and the add_bits() method will croak if you try. =item $ctx->digest Return the binary digest for the message. Note that the C<digest> operation is effectively a destructive, read-once operation. Once it has been performed, the $ctx object is automatically C<reset> and can be used to calculate another digest value. Call $ctx->clone->digest if you want to calculate the digest without resetting the digest state. =item $ctx->hexdigest Same as $ctx->digest, but will return the digest in hexadecimal form. =item $ctx->b64digest Same as $ctx->digest, but will return the digest as a base64 encoded string without padding. =item $ctx->base64_padded_digest Same as $ctx->digest, but will return the digest as a base64 encoded string. =back =head1 Digest speed This table should give some indication on the relative speed of different algorithms. It is sorted by throughput based on a benchmark done with of some implementations of this API: Algorithm Size Implementation MB/s MD4 128 Digest::MD4 v1.3 165.0 MD5 128 Digest::MD5 v2.33 98.8 SHA-256 256 Digest::SHA2 v1.1.0 66.7 SHA-1 160 Digest::SHA v4.3.1 58.9 SHA-1 160 Digest::SHA1 v2.10 48.8 SHA-256 256 Digest::SHA v4.3.1 41.3 Haval-256 256 Digest::Haval256 v1.0.4 39.8 SHA-384 384 Digest::SHA2 v1.1.0 19.6 SHA-512 512 Digest::SHA2 v1.1.0 19.3 SHA-384 384 Digest::SHA v4.3.1 19.2 SHA-512 512 Digest::SHA v4.3.1 19.2 Whirlpool 512 Digest::Whirlpool v1.0.2 13.0 MD2 128 Digest::MD2 v2.03 9.5 Adler-32 32 Digest::Adler32 v0.03 1.3 CRC-16 16 Digest::CRC v0.05 1.1 CRC-32 32 Digest::CRC v0.05 1.1 MD5 128 Digest::Perl::MD5 v1.5 1.0 CRC-CCITT 16 Digest::CRC v0.05 0.8 These numbers was achieved Apr 2004 with ActivePerl-5.8.3 running under Linux on a P4 2.8 GHz CPU. The last 5 entries differ by being pure perl implementations of the algorithms, which explains why they are so slow. =head1 SEE ALSO L<Digest::Adler32>, L<Digest::CRC>, L<Digest::Haval256>, L<Digest::HMAC>, L<Digest::MD2>, L<Digest::MD4>, L<Digest::MD5>, L<Digest::SHA>, L<Digest::SHA1>, L<Digest::SHA2>, L<Digest::Whirlpool> New digest implementations should consider subclassing from L<Digest::base>. L<MIME::Base64> http://en.wikipedia.org/wiki/Cryptographic_hash_function =head1 AUTHOR Gisle Aas <gisle@aas.no> The C<Digest::> interface is based on the interface originally developed by Neil Winton for his C<MD5> module. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Copyright 1998-2006 Gisle Aas. Copyright 1995,1996 Neil Winton. =cut	10.96 KB	2020-10-13 19:59
📁 Error	-	2025-02-27 15:06
📄 Error.pm # Error.pm # # Copyright (c) 1997-8 Graham Barr <gbarr@ti.com>. All rights reserved. # This program is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # # Based on my original Error.pm, and Exceptions.pm by Peter Seibel # <peter@weblogic.com> and adapted by Jesse Glick <jglick@sig.bsh.com>. # # but modified *significantly* package Error; $Error::VERSION = '0.17029'; use strict; use warnings; use 5.004; use overload ( '""' => 'stringify', '0+' => 'value', 'bool' => sub { return 1; }, 'fallback' => 1 ); $Error::Depth = 0; # Depth to pass to caller() $Error::Debug = 0; # Generate verbose stack traces @Error::STACK = (); # Clause stack for try $Error::THROWN = undef; # last error thrown, a workaround until die $ref works my $LAST; # Last error created my %ERROR; # Last error associated with package sub _throw_Error_Simple { my $args = shift; return Error::Simple->new( $args->{'text'} ); } $Error::ObjectifyCallback = \&_throw_Error_Simple; # Exported subs are defined in Error::subs use Scalar::Util (); sub import { shift; my @tags = @_; local $Exporter::ExportLevel = $Exporter::ExportLevel + 1; @tags = grep { if ( $_ eq ':warndie' ) { Error::WarnDie->import(); 0; } else { 1; } } @tags; Error::subs->import(@tags); } # I really want to use last for the name of this method, but it is a keyword # which prevent the syntax last Error sub prior { shift; # ignore return $LAST unless @_; my $pkg = shift; return exists $ERROR{$pkg} ? $ERROR{$pkg} : undef unless ref($pkg); my $obj = $pkg; my $err = undef; if ( $obj->isa('HASH') ) { $err = $obj->{'__Error__'} if exists $obj->{'__Error__'}; } elsif ( $obj->isa('GLOB') ) { $err = ${$obj}{'__Error__'} if exists ${$obj}{'__Error__'}; } $err; } sub flush { shift; #ignore unless (@_) { $LAST = undef; return; } my $pkg = shift; return unless ref($pkg); undef $ERROR{$pkg} if defined $ERROR{$pkg}; } # Return as much information as possible about where the error # happened. The -stacktrace element only exists if $Error::DEBUG # was set when the error was created sub stacktrace { my $self = shift; return $self->{'-stacktrace'} if exists $self->{'-stacktrace'}; my $text = exists $self->{'-text'} ? $self->{'-text'} : "Died"; $text .= sprintf( " at %s line %d.\n", $self->file, $self->line ) unless ( $text =~ /\n$/s ); $text; } sub associate { my $err = shift; my $obj = shift; return unless ref($obj); if ( $obj->isa('HASH') ) { $obj->{'__Error__'} = $err; } elsif ( $obj->isa('GLOB') ) { ${$obj}{'__Error__'} = $err; } $obj = ref($obj); $ERROR{ ref($obj) } = $err; return; } sub new { my $self = shift; my ( $pkg, $file, $line ) = caller($Error::Depth); my $err = bless { '-package' => $pkg, '-file' => $file, '-line' => $line, @_ }, $self; $err->associate( $err->{'-object'} ) if ( exists $err->{'-object'} ); # To always create a stacktrace would be very inefficient, so # we only do it if $Error::Debug is set if ($Error::Debug) { require Carp; local $Carp::CarpLevel = $Error::Depth; my $text = defined( $err->{'-text'} ) ? $err->{'-text'} : "Error"; my $trace = Carp::longmess($text); # Remove try calls from the trace $trace =~ s/(\n\s+\S+__ANON__[^\n]+)?\n\s+eval[^\n]+\n\s+Error::subs::try[^\n]+(?=\n)//sog; $trace =~ s/(\n\s+\S+__ANON__[^\n]+)?\n\s+eval[^\n]+\n\s+Error::subs::run_clauses[^\n]+\n\s+Error::subs::try[^\n]+(?=\n)//sog; $err->{'-stacktrace'} = $trace; } $@ = $LAST = $ERROR{$pkg} = $err; } # Throw an error. this contains some very gory code. sub throw { my $self = shift; local $Error::Depth = $Error::Depth + 1; # if we are not rethrow-ing then create the object to throw $self = $self->new(@_) unless ref($self); die $Error::THROWN = $self; } # syntactic sugar for # # die with Error( ... ); sub with { my $self = shift; local $Error::Depth = $Error::Depth + 1; $self->new(@_); } # syntactic sugar for # # record Error( ... ) and return; sub record { my $self = shift; local $Error::Depth = $Error::Depth + 1; $self->new(@_); } # catch clause for # # try { ... } catch CLASS with { ... } sub catch { my $pkg = shift; my $code = shift; my $clauses = shift \|\| {}; my $catch = $clauses->{'catch'} \|\|= []; unshift @$catch, $pkg, $code; $clauses; } # Object query methods sub object { my $self = shift; exists $self->{'-object'} ? $self->{'-object'} : undef; } sub file { my $self = shift; exists $self->{'-file'} ? $self->{'-file'} : undef; } sub line { my $self = shift; exists $self->{'-line'} ? $self->{'-line'} : undef; } sub text { my $self = shift; exists $self->{'-text'} ? $self->{'-text'} : undef; } # overload methods sub stringify { my $self = shift; defined $self->{'-text'} ? $self->{'-text'} : "Died"; } sub value { my $self = shift; exists $self->{'-value'} ? $self->{'-value'} : undef; } package Error::Simple; $Error::Simple::VERSION = '0.17029'; @Error::Simple::ISA = qw(Error); sub new { my $self = shift; my $text = "" . shift; my $value = shift; my (@args) = (); local $Error::Depth = $Error::Depth + 1; @args = ( -file => $1, -line => $2 ) if ( $text =~ s/\s+at\s+(\S+)\s+line\s+(\d+)(?:,\s<[^>]>\s+line\s+\d+)?\.?\n?$//s ); push( @args, '-value', 0 + $value ) if defined($value); $self->SUPER::new( -text => $text, @args ); } sub stringify { my $self = shift; my $text = $self->SUPER::stringify; $text .= sprintf( " at %s line %d.\n", $self->file, $self->line ) unless ( $text =~ /\n$/s ); $text; } ########################################################################## ########################################################################## # Inspired by code from Jesse Glick <jglick@sig.bsh.com> and # Peter Seibel <peter@weblogic.com> package Error::subs; $Error::subs::VERSION = '0.17029'; use Exporter (); use vars qw(@EXPORT_OK @ISA %EXPORT_TAGS); @EXPORT_OK = qw(try with finally except otherwise); %EXPORT_TAGS = ( try => \@EXPORT_OK ); @ISA = qw(Exporter); sub run_clauses ($$$\@) { my ( $clauses, $err, $wantarray, $result ) = @_; my $code = undef; $err = $Error::ObjectifyCallback->( { 'text' => $err } ) unless ref($err); CATCH: { # catch my $catch; if ( defined( $catch = $clauses->{'catch'} ) ) { my $i = 0; CATCHLOOP: for ( ; $i < @$catch ; $i += 2 ) { my $pkg = $catch->[$i]; unless ( defined $pkg ) { #except splice( @$catch, $i, 2, $catch->[ $i + 1 ]->($err) ); $i -= 2; next CATCHLOOP; } elsif ( Scalar::Util::blessed($err) && $err->isa($pkg) ) { $code = $catch->[ $i + 1 ]; while (1) { my $more = 0; local ( $Error::THROWN, $@ ); my $ok = eval { $@ = $err; if ($wantarray) { @{$result} = $code->( $err, \$more ); } elsif ( defined($wantarray) ) { @{$result} = (); $result->[0] = $code->( $err, \$more ); } else { $code->( $err, \$more ); } 1; }; if ($ok) { next CATCHLOOP if $more; undef $err; } else { $err = $@ \|\| $Error::THROWN; $err = $Error::ObjectifyCallback->( { 'text' => $err } ) unless ref($err); } last CATCH; } } } } # otherwise my $owise; if ( defined( $owise = $clauses->{'otherwise'} ) ) { my $code = $clauses->{'otherwise'}; my $more = 0; local ( $Error::THROWN, $@ ); my $ok = eval { $@ = $err; if ($wantarray) { @{$result} = $code->( $err, \$more ); } elsif ( defined($wantarray) ) { @{$result} = (); $result->[0] = $code->( $err, \$more ); } else { $code->( $err, \$more ); } 1; }; if ($ok) { undef $err; } else { $err = $@ \|\| $Error::THROWN; $err = $Error::ObjectifyCallback->( { 'text' => $err } ) unless ref($err); } } } $err; } sub try (&;$) { my $try = shift; my $clauses = @_ ? shift : {}; my $ok = 0; my $err = undef; my @result = (); unshift @Error::STACK, $clauses; my $wantarray = wantarray(); do { local $Error::THROWN = undef; local $@ = undef; $ok = eval { if ($wantarray) { @result = $try->(); } elsif ( defined $wantarray ) { $result[0] = $try->(); } else { $try->(); } 1; }; $err = $@ \|\| $Error::THROWN unless $ok; }; shift @Error::STACK; $err = run_clauses( $clauses, $err, wantarray, @result ) unless ($ok); $clauses->{'finally'}->() if ( defined( $clauses->{'finally'} ) ); if ( defined($err) ) { if ( Scalar::Util::blessed($err) && $err->can('throw') ) { throw $err; } else { die $err; } } wantarray ? @result : $result[0]; } # Each clause adds a sub to the list of clauses. The finally clause is # always the last, and the otherwise clause is always added just before # the finally clause. # # All clauses, except the finally clause, add a sub which takes one argument # this argument will be the error being thrown. The sub will return a code ref # if that clause can handle that error, otherwise undef is returned. # # The otherwise clause adds a sub which unconditionally returns the users # code reference, this is why it is forced to be last. # # The catch clause is defined in Error.pm, as the syntax causes it to # be called as a method sub with (&;$) { @_; } sub finally (&) { my $code = shift; my $clauses = { 'finally' => $code }; $clauses; } # The except clause is a block which returns a hashref or a list of # key-value pairs, where the keys are the classes and the values are subs. sub except (&;$) { my $code = shift; my $clauses = shift \|\| {}; my $catch = $clauses->{'catch'} \|\|= []; my $sub = sub { my $ref; my (@array) = $code->( $_[0] ); if ( @array == 1 && ref( $array[0] ) ) { $ref = $array[0]; $ref = [%$ref] if ( UNIVERSAL::isa( $ref, 'HASH' ) ); } else { $ref = \@array; } @$ref; }; unshift @{$catch}, undef, $sub; $clauses; } sub otherwise (&;$) { my $code = shift; my $clauses = shift \|\| {}; if ( exists $clauses->{'otherwise'} ) { require Carp; Carp::croak("Multiple otherwise clauses"); } $clauses->{'otherwise'} = $code; $clauses; } 1; package Error::WarnDie; $Error::WarnDie::VERSION = '0.17029'; sub gen_callstack($) { my ($start) = @_; require Carp; local $Carp::CarpLevel = $start; my $trace = Carp::longmess(""); # Remove try calls from the trace $trace =~ s/(\n\s+\S+__ANON__[^\n]+)?\n\s+eval[^\n]+\n\s+Error::subs::try[^\n]+(?=\n)//sog; $trace =~ s/(\n\s+\S+__ANON__[^\n]+)?\n\s+eval[^\n]+\n\s+Error::subs::run_clauses[^\n]+\n\s+Error::subs::try[^\n]+(?=\n)//sog; my @callstack = split( m/\n/, $trace ); return @callstack; } my $old_DIE; my $old_WARN; sub DEATH { my ($e) = @_; local $SIG{__DIE__} = $old_DIE if ( defined $old_DIE ); die @_ if $^S; my ( $etype, $message, $location, @callstack ); if ( ref($e) && $e->isa("Error") ) { $etype = "exception of type " . ref($e); $message = $e->text; $location = $e->file . ":" . $e->line; @callstack = split( m/\n/, $e->stacktrace ); } else { # Don't apply subsequent layer of message formatting die $e if ( $e =~ m/^\nUnhandled perl error caught at toplevel:\n\n/ ); $etype = "perl error"; my $stackdepth = 0; while ( caller($stackdepth) =~ m/^Error(?:$\|::)/ ) { ++$stackdepth; } @callstack = gen_callstack( $stackdepth + 1 ); $message = "$e"; chomp $message; if ( $message =~ s/ at (.?) line (\d+)\.$// ) { $location = $1 . ":" . $2; } else { my @caller = caller($stackdepth); $location = $caller[1] . ":" . $caller[2]; } } shift @callstack; # Do it this way in case there are no elements; we don't print a spurious \n my $callstack = join( "", map { "$_\n" } @callstack ); die "\nUnhandled $etype caught at toplevel:\n\n $message\n\nThrown from: $location\n\nFull stack trace:\n\n$callstack\n"; } sub TAXES { my ($message) = @_; local $SIG{__WARN__} = $old_WARN if ( defined $old_WARN ); $message =~ s/ at .? line \d+\.$//; chomp $message; my @callstack = gen_callstack(1); my $location = shift @callstack; # $location already starts in a leading space $message .= $location; # Do it this way in case there are no elements; we don't print a spurious \n my $callstack = join( "", map { "$_\n" } @callstack ); warn "$message:\n$callstack"; } sub import { $old_DIE = $SIG{__DIE__}; $old_WARN = $SIG{__WARN__}; $SIG{__DIE__} = \&DEATH; $SIG{__WARN__} = \&TAXES; } 1; __END__ =pod =encoding UTF-8 =head1 NAME Error - Error/exception handling in an OO-ish way =head1 VERSION version 0.17029 =head1 SYNOPSIS use Error qw(:try); throw Error::Simple( "A simple error"); sub xyz { ... record Error::Simple("A simple error") and return; } unlink($file) or throw Error::Simple("$file: $!",$!); try { do_some_stuff(); die "error!" if $condition; throw Error::Simple "Oops!" if $other_condition; } catch Error::IO with { my $E = shift; print STDERR "File ", $E->{'-file'}, " had a problem\n"; } except { my $E = shift; my $general_handler=sub {send_message $E->{-description}}; return { UserException1 => $general_handler, UserException2 => $general_handler }; } otherwise { print STDERR "Well I don't know what to say\n"; } finally { close_the_garage_door_already(); # Should be reliable }; # Don't forget the trailing ; or you might be surprised =head1 DESCRIPTION The C<Error> package provides two interfaces. Firstly C<Error> provides a procedural interface to exception handling. Secondly C<Error> is a base class for errors/exceptions that can either be thrown, for subsequent catch, or can simply be recorded. Errors in the class C<Error> should not be thrown directly, but the user should throw errors from a sub-class of C<Error>. =head1 WARNING Using the "Error" module is B<no longer recommended> due to the black-magical nature of its syntactic sugar, which often tends to break. Its maintainers have stopped actively writing code that uses it, and discourage people from doing so. See the "SEE ALSO" section below for better recommendations. =head1 PROCEDURAL INTERFACE C<Error> exports subroutines to perform exception handling. These will be exported if the C<:try> tag is used in the C<use> line. =over 4 =item try BLOCK CLAUSES C<try> is the main subroutine called by the user. All other subroutines exported are clauses to the try subroutine. The BLOCK will be evaluated and, if no error is throw, try will return the result of the block. C<CLAUSES> are the subroutines below, which describe what to do in the event of an error being thrown within BLOCK. =item catch CLASS with BLOCK This clauses will cause all errors that satisfy C<$err-E<gt>isa(CLASS)> to be caught and handled by evaluating C<BLOCK>. C<BLOCK> will be passed two arguments. The first will be the error being thrown. The second is a reference to a scalar variable. If this variable is set by the catch block then, on return from the catch block, try will continue processing as if the catch block was never found. The error will also be available in C<$@>. To propagate the error the catch block may call C<$err-E<gt>throw> If the scalar reference by the second argument is not set, and the error is not thrown. Then the current try block will return with the result from the catch block. =item except BLOCK When C<try> is looking for a handler, if an except clause is found C<BLOCK> is evaluated. The return value from this block should be a HASHREF or a list of key-value pairs, where the keys are class names and the values are CODE references for the handler of errors of that type. =item otherwise BLOCK Catch any error by executing the code in C<BLOCK> When evaluated C<BLOCK> will be passed one argument, which will be the error being processed. The error will also be available in C<$@>. Only one otherwise block may be specified per try block =item finally BLOCK Execute the code in C<BLOCK> either after the code in the try block has successfully completed, or if the try block throws an error then C<BLOCK> will be executed after the handler has completed. If the handler throws an error then the error will be caught, the finally block will be executed and the error will be re-thrown. Only one finally block may be specified per try block =back =head1 COMPATIBILITY L<Moose> exports a keyword called C<with> which clashes with Error's. This example returns a prototype mismatch error: package MyTest; use warnings; use Moose; use Error qw(:try); (Thanks to C<maik.hentsche@amd.com> for the report.). =head1 CLASS INTERFACE =head2 CONSTRUCTORS The C<Error> object is implemented as a HASH. This HASH is initialized with the arguments that are passed to it's constructor. The elements that are used by, or are retrievable by the C<Error> class are listed below, other classes may add to these. -file -line -text -value -object If C<-file> or C<-line> are not specified in the constructor arguments then these will be initialized with the file name and line number where the constructor was called from. If the error is associated with an object then the object should be passed as the C<-object> argument. This will allow the C<Error> package to associate the error with the object. The C<Error> package remembers the last error created, and also the last error associated with a package. This could either be the last error created by a sub in that package, or the last error which passed an object blessed into that package as the C<-object> argument. =over 4 =item Error->new() See the Error::Simple documentation. =item throw ( [ ARGS ] ) Create a new C<Error> object and throw an error, which will be caught by a surrounding C<try> block, if there is one. Otherwise it will cause the program to exit. C<throw> may also be called on an existing error to re-throw it. =item with ( [ ARGS ] ) Create a new C<Error> object and returns it. This is defined for syntactic sugar, eg die with Some::Error ( ... ); =item record ( [ ARGS ] ) Create a new C<Error> object and returns it. This is defined for syntactic sugar, eg record Some::Error ( ... ) and return; =back =head2 STATIC METHODS =over 4 =item prior ( [ PACKAGE ] ) Return the last error created, or the last error associated with C<PACKAGE> =item flush ( [ PACKAGE ] ) Flush the last error created, or the last error associated with C<PACKAGE>.It is necessary to clear the error stack before exiting the package or uncaught errors generated using C<record> will be reported. $Error->flush; =back =head2 OBJECT METHODS =over 4 =item stacktrace If the variable C<$Error::Debug> was non-zero when the error was created, then C<stacktrace> returns a string created by calling C<Carp::longmess>. If the variable was zero the C<stacktrace> returns the text of the error appended with the filename and line number of where the error was created, providing the text does not end with a newline. =item object The object this error was associated with =item file The file where the constructor of this error was called from =item line The line where the constructor of this error was called from =item text The text of the error =item $err->associate($obj) Associates an error with an object to allow error propagation. I.e: $ber->encode(...) or return Error->prior($ber)->associate($ldap); =back =head2 OVERLOAD METHODS =over 4 =item stringify A method that converts the object into a string. This method may simply return the same as the C<text> method, or it may append more information. For example the file name and line number. By default this method returns the C<-text> argument that was passed to the constructor, or the string C<"Died"> if none was given. =item value A method that will return a value that can be associated with the error. For example if an error was created due to the failure of a system call, then this may return the numeric value of C<$!> at the time. By default this method returns the C<-value> argument that was passed to the constructor. =back =head1 PRE-DEFINED ERROR CLASSES =head2 Error::Simple This class can be used to hold simple error strings and values. It's constructor takes two arguments. The first is a text value, the second is a numeric value. These values are what will be returned by the overload methods. If the text value ends with C<at file line 1> as $@ strings do, then this information will be used to set the C<-file> and C<-line> arguments of the error object. This class is used internally if an eval'd block die's with an error that is a plain string. (Unless C<$Error::ObjectifyCallback> is modified) =head1 $Error::ObjectifyCallback This variable holds a reference to a subroutine that converts errors that are plain strings to objects. It is used by Error.pm to convert textual errors to objects, and can be overridden by the user. It accepts a single argument which is a hash reference to named parameters. Currently the only named parameter passed is C<'text'> which is the text of the error, but others may be available in the future. For example the following code will cause Error.pm to throw objects of the class MyError::Bar by default: sub throw_MyError_Bar { my $args = shift; my $err = MyError::Bar->new(); $err->{'MyBarText'} = $args->{'text'}; return $err; } { local $Error::ObjectifyCallback = \&throw_MyError_Bar; # Error handling here. } =head1 MESSAGE HANDLERS C<Error> also provides handlers to extend the output of the C<warn()> perl function, and to handle the printing of a thrown C<Error> that is not caught or otherwise handled. These are not installed by default, but are requested using the C<:warndie> tag in the C<use> line. use Error qw( :warndie ); These new error handlers are installed in C<$SIG{__WARN__}> and C<$SIG{__DIE__}>. If these handlers are already defined when the tag is imported, the old values are stored, and used during the new code. Thus, to arrange for custom handling of warnings and errors, you will need to perform something like the following: BEGIN { $SIG{__WARN__} = sub { print STDERR "My special warning handler: $_[0]" }; } use Error qw( :warndie ); Note that setting C<$SIG{__WARN__}> after the C<:warndie> tag has been imported will overwrite the handler that C<Error> provides. If this cannot be avoided, then the tag can be explicitly C<import>ed later use Error; $SIG{__WARN__} = ...; import Error qw( :warndie ); =head2 EXAMPLE The C<__DIE__> handler turns messages such as Can't call method "foo" on an undefined value at examples/warndie.pl line 16. into Unhandled perl error caught at toplevel: Can't call method "foo" on an undefined value Thrown from: examples/warndie.pl:16 Full stack trace: main::inner('undef') called at examples/warndie.pl line 20 main::outer('undef') called at examples/warndie.pl line 23 =head1 SEE ALSO See L<Exception::Class> for a different module providing Object-Oriented exception handling, along with a convenient syntax for declaring hierarchies for them. It doesn't provide Error's syntactic sugar of C<try { ... }>, C<catch { ... }>, etc. which may be a good thing or a bad thing based on what you want. (Because Error's syntactic sugar tends to break.) L<Error::Exception> aims to combine L<Error> and L<Exception::Class> "with correct stringification". L<TryCatch> and L<Try::Tiny> are similar in concept to Error.pm only providing a syntax that hopefully breaks less. =head1 KNOWN BUGS None, but that does not mean there are not any. =head1 AUTHORS Graham Barr <gbarr@pobox.com> The code that inspired me to write this was originally written by Peter Seibel <peter@weblogic.com> and adapted by Jesse Glick <jglick@sig.bsh.com>. C<:warndie> handlers added by Paul Evans <leonerd@leonerd.org.uk> =head1 MAINTAINER Shlomi Fish, L<http://www.shlomifish.org/> . =head1 PAST MAINTAINERS Arun Kumar U <u_arunkumar@yahoo.com> =head1 COPYRIGHT Copyright (c) 1997-8 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =for :stopwords cpan testmatrix url bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan =head1 SUPPORT =head2 Websites The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources. =over 4 =item MetaCPAN A modern, open-source CPAN search engine, useful to view POD in HTML format. L<https://metacpan.org/release/Error> =item * Search CPAN The default CPAN search engine, useful to view POD in HTML format. L<http://search.cpan.org/dist/Error> =item * RT: CPAN's Bug Tracker The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN. L<https://rt.cpan.org/Public/Dist/Display.html?Name=Error> =item * CPAN Ratings The CPAN Ratings is a website that allows community ratings and reviews of Perl modules. L<http://cpanratings.perl.org/d/Error> =item * CPANTS The CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution. L<http://cpants.cpanauthors.org/dist/Error> =item * CPAN Testers The CPAN Testers is a network of smoke testers who run automated tests on uploaded CPAN distributions. L<http://www.cpantesters.org/distro/E/Error> =item * CPAN Testers Matrix The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms. L<http://matrix.cpantesters.org/?dist=Error> =item * CPAN Testers Dependencies The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution. L<http://deps.cpantesters.org/?module=Error> =back =head2 Bugs / Feature Requests Please report any bugs or feature requests by email to C<bug-error at rt.cpan.org>, or through the web interface at L<https://rt.cpan.org/Public/Bug/Report.html?Queue=Error>. You will be automatically notified of any progress on the request by the system. =head2 Source Code The code is open to the world, and available for you to hack on. Please feel free to browse it and play with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from your repository :) L<https://github.com/shlomif/perl-error.pm> git clone git://github.com/shlomif/perl-error.pm.git =head1 AUTHOR Shlomi Fish ( http://www.shlomifish.org/ ) =head1 BUGS Please report any bugs or feature requests on the bugtracker website L<https://github.com/shlomif/perl-error.pm/issues> When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2020 by Shlomi Fish ( http://www.shlomifish.org/ ). 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	29.45 KB	2020-01-28 16:51
📁 Exporter	-	2025-02-27 15:06
📄 Exporter.pm package Exporter; require 5.006; # Be lean. #use strict; #no strict 'refs'; our $Debug = 0; our $ExportLevel = 0; our $Verbose \|\|= 0; our $VERSION = '5.74'; our (%Cache); sub as_heavy { require Exporter::Heavy; # Unfortunately, this does not work if the caller is aliased as name = \&foo # Thus the need to create a lot of identical subroutines my $c = (caller(1))[3]; $c =~ s/.:://; \&{"Exporter::Heavy::heavy_$c"}; } sub export { goto &{as_heavy()}; } sub import { my $pkg = shift; my $callpkg = caller($ExportLevel); if ($pkg eq "Exporter" and @_ and $_[0] eq "import") { {$callpkg."::import"} = \&import; return; } # We need* to treat @{"$pkg\::EXPORT_FAIL"} since Carp uses it :-( my $exports = \@{"$pkg\::EXPORT"}; # But, avoid creating things if they don't exist, which saves a couple of # hundred bytes per package processed. my $fail = ${$pkg . '::'}{EXPORT_FAIL} && \@{"$pkg\::EXPORT_FAIL"}; return export $pkg, $callpkg, @_ if $Verbose or $Debug or $fail && @$fail > 1; my $export_cache = ($Cache{$pkg} \|\|= {}); my $args = @_ or @_ = @$exports; if ($args and not %$export_cache) { s/^&//, $export_cache->{$_} = 1 foreach (@$exports, @{"$pkg\::EXPORT_OK"}); } my $heavy; # Try very hard not to use {} and hence have to enter scope on the foreach # We bomb out of the loop with last as soon as heavy is set. if ($args or $fail) { ($heavy = (/\W/ or $args and not exists $export_cache->{$_} or $fail and @$fail and $_ eq $fail->[0])) and last foreach (@_); } else { ($heavy = /\W/) and last foreach (@_); } return export $pkg, $callpkg, ($args ? @_ : ()) if $heavy; local $SIG{__WARN__} = sub {require Carp; &Carp::carp} if not $SIG{__WARN__}; # shortcut for the common case of no type character {"$callpkg\::$_"} = \&{"$pkg\::$_"} foreach @_; } # Default methods sub export_fail { my $self = shift; @_; } # Unfortunately, caller(1)[3] "does not work" if the caller is aliased as # name = \&foo. Thus the need to create a lot of identical subroutines # Otherwise we could have aliased them to export(). sub export_to_level { goto &{as_heavy()}; } sub export_tags { goto &{as_heavy()}; } sub export_ok_tags { goto &{as_heavy()}; } sub require_version { goto &{as_heavy()}; } 1; __END__ =head1 NAME Exporter - Implements default import method for modules =head1 SYNOPSIS In module F<YourModule.pm>: package YourModule; require Exporter; our @ISA = qw(Exporter); our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request or package YourModule; use Exporter 'import'; # gives you Exporter's import() method directly our @EXPORT_OK = qw(munge frobnicate); # symbols to export on request In other files which wish to use C<YourModule>: use YourModule qw(frobnicate); # import listed symbols frobnicate ($left, $right) # calls YourModule::frobnicate Take a look at L</Good Practices> for some variants you will like to use in modern Perl code. =head1 DESCRIPTION The Exporter module implements an C<import> method which allows a module to export functions and variables to its users' namespaces. Many modules use Exporter rather than implementing their own C<import> method because Exporter provides a highly flexible interface, with an implementation optimised for the common case. Perl automatically calls the C<import> method when processing a C<use> statement for a module. Modules and C<use> are documented in L<perlfunc> and L<perlmod>. Understanding the concept of modules and how the C<use> statement operates is important to understanding the Exporter. =head2 How to Export The arrays C<@EXPORT> and C<@EXPORT_OK> in a module hold lists of symbols that are going to be exported into the users name space by default, or which they can request to be exported, respectively. The symbols can represent functions, scalars, arrays, hashes, or typeglobs. The symbols must be given by full name with the exception that the ampersand in front of a function is optional, e.g. our @EXPORT = qw(afunc $scalar @array); # afunc is a function our @EXPORT_OK = qw(&bfunc %hash typeglob); # explicit prefix on &bfunc If you are only exporting function names it is recommended to omit the ampersand, as the implementation is faster this way. =head2 Selecting What to Export Do B<not> export method names! Do B<not> export anything else by default without a good reason! Exports pollute the namespace of the module user. If you must export try to use C<@EXPORT_OK> in preference to C<@EXPORT> and avoid short or common symbol names to reduce the risk of name clashes. Generally anything not exported is still accessible from outside the module using the C<YourModule::item_name> (or C<< $blessed_ref->method >>) syntax. By convention you can use a leading underscore on names to informally indicate that they are 'internal' and not for public use. (It is actually possible to get private functions by saying: my $subref = sub { ... }; $subref->(@args); # Call it as a function $obj->$subref(@args); # Use it as a method However if you use them for methods it is up to you to figure out how to make inheritance work.) As a general rule, if the module is trying to be object oriented then export nothing. If it's just a collection of functions then C<@EXPORT_OK> anything but use C<@EXPORT> with caution. For function and method names use barewords in preference to names prefixed with ampersands for the export lists. Other module design guidelines can be found in L<perlmod>. =head2 How to Import In other files which wish to use your module there are three basic ways for them to load your module and import its symbols: =over 4 =item C<use YourModule;> This imports all the symbols from YourModule's C<@EXPORT> into the namespace of the C<use> statement. =item C<use YourModule ();> This causes perl to load your module but does not import any symbols. =item C<use YourModule qw(...);> This imports only the symbols listed by the caller into their namespace. All listed symbols must be in your C<@EXPORT> or C<@EXPORT_OK>, else an error occurs. The advanced export features of Exporter are accessed like this, but with list entries that are syntactically distinct from symbol names. =back Unless you want to use its advanced features, this is probably all you need to know to use Exporter. =head1 Advanced Features =head2 Specialised Import Lists If any of the entries in an import list begins with !, : or / then the list is treated as a series of specifications which either add to or delete from the list of names to import. They are processed left to right. Specifications are in the form: [!]name This name only [!]:DEFAULT All names in @EXPORT [!]:tag All names in $EXPORT_TAGS{tag} anonymous array [!]/pattern/ All names in @EXPORT and @EXPORT_OK which match A leading ! indicates that matching names should be deleted from the list of names to import. If the first specification is a deletion it is treated as though preceded by :DEFAULT. If you just want to import extra names in addition to the default set you will still need to include :DEFAULT explicitly. e.g., F<Module.pm> defines: our @EXPORT = qw(A1 A2 A3 A4 A5); our @EXPORT_OK = qw(B1 B2 B3 B4 B5); our %EXPORT_TAGS = (T1 => [qw(A1 A2 B1 B2)], T2 => [qw(A1 A2 B3 B4)]); Note that you cannot use tags in @EXPORT or @EXPORT_OK. Names in EXPORT_TAGS must also appear in @EXPORT or @EXPORT_OK. An application using Module can say something like: use Module qw(:DEFAULT :T2 !B3 A3); Other examples include: use Socket qw(!/^[AP]F_/ !SOMAXCONN !SOL_SOCKET); use POSIX qw(:errno_h :termios_h !TCSADRAIN !/^EXIT/); Remember that most patterns (using //) will need to be anchored with a leading ^, e.g., C</^EXIT/> rather than C</EXIT/>. You can say C<BEGIN { $Exporter::Verbose=1 }> to see how the specifications are being processed and what is actually being imported into modules. =head2 Exporting Without Using Exporter's import Method Exporter has a special method, 'export_to_level' which is used in situations where you can't directly call Exporter's import method. The export_to_level method looks like: MyPackage->export_to_level( $where_to_export, $package, @what_to_export ); where C<$where_to_export> is an integer telling how far up the calling stack to export your symbols, and C<@what_to_export> is an array telling what symbols to* export (usually this is C<@_>). The C<$package> argument is currently unused. For example, suppose that you have a module, A, which already has an import function: package A; our @ISA = qw(Exporter); our @EXPORT_OK = qw($b); sub import { $A::b = 1; # not a very useful import method } and you want to Export symbol C<$A::b> back to the module that called package A. Since Exporter relies on the import method to work, via inheritance, as it stands Exporter::import() will never get called. Instead, say the following: package A; our @ISA = qw(Exporter); our @EXPORT_OK = qw($b); sub import { $A::b = 1; A->export_to_level(1, @_); } This will export the symbols one level 'above' the current package - ie: to the program or module that used package A. Note: Be careful not to modify C<@_> at all before you call export_to_level - or people using your package will get very unexplained results! =head2 Exporting Without Inheriting from Exporter By including Exporter in your C<@ISA> you inherit an Exporter's import() method but you also inherit several other helper methods which you probably don't want. To avoid this you can do: package YourModule; use Exporter qw(import); which will export Exporter's own import() method into YourModule. Everything will work as before but you won't need to include Exporter in C<@YourModule::ISA>. Note: This feature was introduced in version 5.57 of Exporter, released with perl 5.8.3. =head2 Module Version Checking The Exporter module will convert an attempt to import a number from a module into a call to C<< $module_name->VERSION($value) >>. This can be used to validate that the version of the module being used is greater than or equal to the required version. For historical reasons, Exporter supplies a C<require_version> method that simply delegates to C<VERSION>. Originally, before C<UNIVERSAL::VERSION> existed, Exporter would call C<require_version>. Since the C<UNIVERSAL::VERSION> method treats the C<$VERSION> number as a simple numeric value it will regard version 1.10 as lower than 1.9. For this reason it is strongly recommended that you use numbers with at least two decimal places, e.g., 1.09. =head2 Managing Unknown Symbols In some situations you may want to prevent certain symbols from being exported. Typically this applies to extensions which have functions or constants that may not exist on some systems. The names of any symbols that cannot be exported should be listed in the C<@EXPORT_FAIL> array. If a module attempts to import any of these symbols the Exporter will give the module an opportunity to handle the situation before generating an error. The Exporter will call an export_fail method with a list of the failed symbols: @failed_symbols = $module_name->export_fail(@failed_symbols); If the C<export_fail> method returns an empty list then no error is recorded and all the requested symbols are exported. If the returned list is not empty then an error is generated for each symbol and the export fails. The Exporter provides a default C<export_fail> method which simply returns the list unchanged. Uses for the C<export_fail> method include giving better error messages for some symbols and performing lazy architectural checks (put more symbols into C<@EXPORT_FAIL> by default and then take them out if someone actually tries to use them and an expensive check shows that they are usable on that platform). =head2 Tag Handling Utility Functions Since the symbols listed within C<%EXPORT_TAGS> must also appear in either C<@EXPORT> or C<@EXPORT_OK>, two utility functions are provided which allow you to easily add tagged sets of symbols to C<@EXPORT> or C<@EXPORT_OK>: our %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]); Exporter::export_tags('foo'); # add aa, bb and cc to @EXPORT Exporter::export_ok_tags('bar'); # add aa, cc and dd to @EXPORT_OK Any names which are not tags are added to C<@EXPORT> or C<@EXPORT_OK> unchanged but will trigger a warning (with C<-w>) to avoid misspelt tags names being silently added to C<@EXPORT> or C<@EXPORT_OK>. Future versions may make this a fatal error. =head2 Generating Combined Tags If several symbol categories exist in C<%EXPORT_TAGS>, it's usually useful to create the utility ":all" to simplify "use" statements. The simplest way to do this is: our %EXPORT_TAGS = (foo => [qw(aa bb cc)], bar => [qw(aa cc dd)]); # add all the other ":class" tags to the ":all" class, # deleting duplicates { my %seen; push @{$EXPORT_TAGS{all}}, grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach keys %EXPORT_TAGS; } F<CGI.pm> creates an ":all" tag which contains some (but not really all) of its categories. That could be done with one small change: # add some of the other ":class" tags to the ":all" class, # deleting duplicates { my %seen; push @{$EXPORT_TAGS{all}}, grep {!$seen{$_}++} @{$EXPORT_TAGS{$_}} foreach qw/html2 html3 netscape form cgi internal/; } Note that the tag names in C<%EXPORT_TAGS> don't have the leading ':'. =head2 C<AUTOLOAD>ed Constants Many modules make use of C<AUTOLOAD>ing for constant subroutines to avoid having to compile and waste memory on rarely used values (see L<perlsub> for details on constant subroutines). Calls to such constant subroutines are not optimized away at compile time because they can't be checked at compile time for constancy. Even if a prototype is available at compile time, the body of the subroutine is not (it hasn't been C<AUTOLOAD>ed yet). perl needs to examine both the C<()> prototype and the body of a subroutine at compile time to detect that it can safely replace calls to that subroutine with the constant value. A workaround for this is to call the constants once in a C<BEGIN> block: package My ; use Socket ; foo( SO_LINGER ); ## SO_LINGER NOT optimized away; called at runtime BEGIN { SO_LINGER } foo( SO_LINGER ); ## SO_LINGER optimized away at compile time. This forces the C<AUTOLOAD> for C<SO_LINGER> to take place before SO_LINGER is encountered later in C<My> package. If you are writing a package that C<AUTOLOAD>s, consider forcing an C<AUTOLOAD> for any constants explicitly imported by other packages or which are usually used when your package is C<use>d. =head1 Good Practices =head2 Declaring C<@EXPORT_OK> and Friends When using C<Exporter> with the standard C<strict> and C<warnings> pragmas, the C<our> keyword is needed to declare the package variables C<@EXPORT_OK>, C<@EXPORT>, C<@ISA>, etc. our @ISA = qw(Exporter); our @EXPORT_OK = qw(munge frobnicate); If backward compatibility for Perls B<under> 5.6 is important, one must write instead a C<use vars> statement. use vars qw(@ISA @EXPORT_OK); @ISA = qw(Exporter); @EXPORT_OK = qw(munge frobnicate); =head2 Playing Safe There are some caveats with the use of runtime statements like C<require Exporter> and the assignment to package variables, which can be very subtle for the unaware programmer. This may happen for instance with mutually recursive modules, which are affected by the time the relevant constructions are executed. The ideal (but a bit ugly) way to never have to think about that is to use C<BEGIN> blocks. So the first part of the L</SYNOPSIS> code could be rewritten as: package YourModule; use strict; use warnings; our (@ISA, @EXPORT_OK); BEGIN { require Exporter; @ISA = qw(Exporter); @EXPORT_OK = qw(munge frobnicate); # symbols to export on request } The C<BEGIN> will assure that the loading of F<Exporter.pm> and the assignments to C<@ISA> and C<@EXPORT_OK> happen immediately, leaving no room for something to get awry or just plain wrong. With respect to loading C<Exporter> and inheriting, there are alternatives with the use of modules like C<base> and C<parent>. use base qw(Exporter); # or use parent qw(Exporter); Any of these statements are nice replacements for C<BEGIN { require Exporter; @ISA = qw(Exporter); }> with the same compile-time effect. The basic difference is that C<base> code interacts with declared C<fields> while C<parent> is a streamlined version of the older C<base> code to just establish the IS-A relationship. For more details, see the documentation and code of L<base> and L<parent>. Another thorough remedy to that runtime vs. compile-time trap is to use L<Exporter::Easy>, which is a wrapper of Exporter that allows all boilerplate code at a single gulp in the use statement. use Exporter::Easy ( OK => [ qw(munge frobnicate) ], ); # @ISA setup is automatic # all assignments happen at compile time =head2 What Not to Export You have been warned already in L</Selecting What to Export> to not export: =over 4 =item * method names (because you don't need to and that's likely to not do what you want), =item * anything by default (because you don't want to surprise your users... badly) =item * anything you don't need to (because less is more) =back There's one more item to add to this list. Do B<not> export variable names. Just because C<Exporter> lets you do that, it does not mean you should. @EXPORT_OK = qw($svar @avar %hvar); # DON'T! Exporting variables is not a good idea. They can change under the hood, provoking horrible effects at-a-distance that are too hard to track and to fix. Trust me: they are not worth it. To provide the capability to set/get class-wide settings, it is best instead to provide accessors as subroutines or class methods instead. =head1 SEE ALSO C<Exporter> is definitely not the only module with symbol exporter capabilities. At CPAN, you may find a bunch of them. Some are lighter. Some provide improved APIs and features. Pick the one that fits your needs. The following is a sample list of such modules. Exporter::Easy Exporter::Lite Exporter::Renaming Exporter::Tidy Sub::Exporter / Sub::Installer Perl6::Export / Perl6::Export::Attrs =head1 LICENSE This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself. =cut	18.36 KB	2019-11-18 22:21
📁 File	-	2025-02-27 15:06
📁 Getopt	-	2025-02-27 15:06
📁 Git	-	2026-03-21 15:45
📄 Git.pm =head1 NAME Git - Perl interface to the Git version control system =cut package Git; use 5.008001; use strict; use warnings $ENV{GIT_PERL_FATAL_WARNINGS} ? qw(FATAL all) : (); BEGIN { our ($VERSION, @ISA, @EXPORT, @EXPORT_OK); # Totally unstable API. $VERSION = '0.01'; =head1 SYNOPSIS use Git; my $version = Git::command_oneline('version'); git_cmd_try { Git::command_noisy('update-server-info') } '%s failed w/ code %d'; my $repo = Git->repository (Directory => '/srv/git/cogito.git'); my @revs = $repo->command('rev-list', '--since=last monday', '--all'); my ($fh, $c) = $repo->command_output_pipe('rev-list', '--since=last monday', '--all'); my $lastrev = <$fh>; chomp $lastrev; $repo->command_close_pipe($fh, $c); my $lastrev = $repo->command_oneline( [ 'rev-list', '--all' ], STDERR => 0 ); my $sha1 = $repo->hash_and_insert_object('file.txt'); my $tempfile = tempfile(); my $size = $repo->cat_blob($sha1, $tempfile); =cut require Exporter; @ISA = qw(Exporter); @EXPORT = qw(git_cmd_try); # Methods which can be called as standalone functions as well: @EXPORT_OK = qw(command command_oneline command_noisy command_output_pipe command_input_pipe command_close_pipe command_bidi_pipe command_close_bidi_pipe version exec_path html_path hash_object git_cmd_try remote_refs prompt get_tz_offset get_record credential credential_read credential_write temp_acquire temp_is_locked temp_release temp_reset temp_path unquote_path); =head1 DESCRIPTION This module provides Perl scripts easy way to interface the Git version control system. The modules have an easy and well-tested way to call arbitrary Git commands; in the future, the interface will also provide specialized methods for doing easily operations which are not totally trivial to do over the generic command interface. While some commands can be executed outside of any context (e.g. 'version' or 'init'), most operations require a repository context, which in practice means getting an instance of the Git object using the repository() constructor. (In the future, we will also get a new_repository() constructor.) All commands called as methods of the object are then executed in the context of the repository. Part of the "repository state" is also information about path to the attached working copy (unless you work with a bare repository). You can also navigate inside of the working copy using the C<wc_chdir()> method. (Note that the repository object is self-contained and will not change working directory of your process.) TODO: In the future, we might also do my $remoterepo = $repo->remote_repository (Name => 'cogito', Branch => 'master'); $remoterepo \|\|= Git->remote_repository ('http://git.or.cz/cogito.git/'); my @refs = $remoterepo->refs(); Currently, the module merely wraps calls to external Git tools. In the future, it will provide a much faster way to interact with Git by linking directly to libgit. This should be completely opaque to the user, though (performance increase notwithstanding). =cut sub carp { require Carp; goto &Carp::carp } sub croak { require Carp; goto &Carp::croak } use Error qw(:try); } =head1 CONSTRUCTORS =over 4 =item repository ( OPTIONS ) =item repository ( DIRECTORY ) =item repository () Construct a new repository object. C<OPTIONS> are passed in a hash like fashion, using key and value pairs. Possible options are: B<Repository> - Path to the Git repository. B<WorkingCopy> - Path to the associated working copy; not strictly required as many commands will happily crunch on a bare repository. B<WorkingSubdir> - Subdirectory in the working copy to work inside. Just left undefined if you do not want to limit the scope of operations. B<Directory> - Path to the Git working directory in its usual setup. The C<.git> directory is searched in the directory and all the parent directories; if found, C<WorkingCopy> is set to the directory containing it and C<Repository> to the C<.git> directory itself. If no C<.git> directory was found, the C<Directory> is assumed to be a bare repository, C<Repository> is set to point at it and C<WorkingCopy> is left undefined. If the C<$GIT_DIR> environment variable is set, things behave as expected as well. You should not use both C<Directory> and either of C<Repository> and C<WorkingCopy> - the results of that are undefined. Alternatively, a directory path may be passed as a single scalar argument to the constructor; it is equivalent to setting only the C<Directory> option field. Calling the constructor with no options whatsoever is equivalent to calling it with C<< Directory => '.' >>. In general, if you are building a standard porcelain command, simply doing C<< Git->repository() >> should do the right thing and setup the object to reflect exactly where the user is right now. =cut sub repository { my $class = shift; my @args = @_; my %opts = (); my $self; if (defined $args[0]) { if ($#args % 2 != 1) { # Not a hash. $#args == 0 or throw Error::Simple("bad usage"); %opts = ( Directory => $args[0] ); } else { %opts = @args; } } if (not defined $opts{Repository} and not defined $opts{WorkingCopy} and not defined $opts{Directory}) { $opts{Directory} = '.'; } if (defined $opts{Directory}) { -d $opts{Directory} or throw Error::Simple("Directory not found: $opts{Directory} $!"); my $search = Git->repository(WorkingCopy => $opts{Directory}); # This rev-parse will throw an exception if we're not in a # repository, which is what we want, but it's kind of noisy. # Ideally we'd capture stderr and relay it, but doing so is # awkward without depending on it fitting in a pipe buffer. So # we just reproduce a plausible error message ourselves. my $out; try { # Note that "--is-bare-repository" must come first, as # --git-dir output could contain newlines. $out = $search->command([qw(rev-parse --is-bare-repository --absolute-git-dir)], STDERR => 0); } catch Git::Error::Command with { throw Error::Simple("fatal: not a git repository: $opts{Directory}"); }; chomp $out; my ($bare, $dir) = split /\n/, $out, 2; # We know this is an absolute path, because we used # --absolute-git-dir above. $opts{Repository} = $dir; if ($bare ne 'true') { require Cwd; # If --git-dir went ok, this shouldn't die either. my $prefix = $search->command_oneline('rev-parse', '--show-prefix'); $dir = Cwd::abs_path($opts{Directory}) . '/'; if ($prefix) { if (substr($dir, -length($prefix)) ne $prefix) { throw Error::Simple("rev-parse confused me - $dir does not have trailing $prefix"); } substr($dir, -length($prefix)) = ''; } $opts{WorkingCopy} = $dir; $opts{WorkingSubdir} = $prefix; } delete $opts{Directory}; } $self = { opts => \%opts }; bless $self, $class; } =back =head1 METHODS =over 4 =item command ( COMMAND [, ARGUMENTS... ] ) =item command ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } ) Execute the given Git C<COMMAND> (specify it without the 'git-' prefix), optionally with the specified extra C<ARGUMENTS>. The second more elaborate form can be used if you want to further adjust the command execution. Currently, only one option is supported: B<STDERR> - How to deal with the command's error output. By default (C<undef>) it is delivered to the caller's C<STDERR>. A false value (0 or '') will cause it to be thrown away. If you want to process it, you can get it in a filehandle you specify, but you must be extremely careful; if the error output is not very short and you want to read it in the same process as where you called C<command()>, you are set up for a nice deadlock! The method can be called without any instance or on a specified Git repository (in that case the command will be run in the repository context). In scalar context, it returns all the command output in a single string (verbatim). In array context, it returns an array containing lines printed to the command's stdout (without trailing newlines). In both cases, the command's stdin and stderr are the same as the caller's. =cut sub command { my ($fh, $ctx) = command_output_pipe(@_); if (not defined wantarray) { # Nothing to pepper the possible exception with. _cmd_close($ctx, $fh); } elsif (not wantarray) { local $/; my $text = <$fh>; try { _cmd_close($ctx, $fh); } catch Git::Error::Command with { # Pepper with the output: my $E = shift; $E->{'-outputref'} = \$text; throw $E; }; return $text; } else { my @lines = <$fh>; defined and chomp for @lines; try { _cmd_close($ctx, $fh); } catch Git::Error::Command with { my $E = shift; $E->{'-outputref'} = \@lines; throw $E; }; return @lines; } } =item command_oneline ( COMMAND [, ARGUMENTS... ] ) =item command_oneline ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } ) Execute the given C<COMMAND> in the same way as command() does but always return a scalar string containing the first line of the command's standard output. =cut sub command_oneline { my ($fh, $ctx) = command_output_pipe(@_); my $line = <$fh>; defined $line and chomp $line; try { _cmd_close($ctx, $fh); } catch Git::Error::Command with { # Pepper with the output: my $E = shift; $E->{'-outputref'} = \$line; throw $E; }; return $line; } =item command_output_pipe ( COMMAND [, ARGUMENTS... ] ) =item command_output_pipe ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } ) Execute the given C<COMMAND> in the same way as command() does but return a pipe filehandle from which the command output can be read. The function can return C<($pipe, $ctx)> in array context. See C<command_close_pipe()> for details. =cut sub command_output_pipe { _command_common_pipe('-\|', @_); } =item command_input_pipe ( COMMAND [, ARGUMENTS... ] ) =item command_input_pipe ( [ COMMAND, ARGUMENTS... ], { Opt => Val ... } ) Execute the given C<COMMAND> in the same way as command_output_pipe() does but return an input pipe filehandle instead; the command output is not captured. The function can return C<($pipe, $ctx)> in array context. See C<command_close_pipe()> for details. =cut sub command_input_pipe { _command_common_pipe('\|-', @_); } =item command_close_pipe ( PIPE [, CTX ] ) Close the C<PIPE> as returned from C<command__pipe()>, checking whether the command finished successfully. The optional C<CTX> argument is required if you want to see the command name in the error message, and it is the second value returned by C<command__pipe()> when called in array context. The call idiom is: my ($fh, $ctx) = $r->command_output_pipe('status'); while (<$fh>) { ... } $r->command_close_pipe($fh, $ctx); Note that you should not rely on whatever actually is in C<CTX>; currently it is simply the command name but in future the context might have more complicated structure. =cut sub command_close_pipe { my ($self, $fh, $ctx) = _maybe_self(@_); $ctx \|\|= '<unknown>'; _cmd_close($ctx, $fh); } =item command_bidi_pipe ( COMMAND [, ARGUMENTS... ] ) Execute the given C<COMMAND> in the same way as command_output_pipe() does but return both an input pipe filehandle and an output pipe filehandle. The function will return C<($pid, $pipe_in, $pipe_out, $ctx)>. See C<command_close_bidi_pipe()> for details. =cut sub command_bidi_pipe { my ($pid, $in, $out); my ($self) = _maybe_self(@_); local %ENV = %ENV; my $cwd_save = undef; if ($self) { shift; require Cwd; $cwd_save = Cwd::getcwd(); _setup_git_cmd_env($self); } require IPC::Open2; $pid = IPC::Open2::open2($in, $out, 'git', @_); chdir($cwd_save) if $cwd_save; return ($pid, $in, $out, join(' ', @_)); } =item command_close_bidi_pipe ( PID, PIPE_IN, PIPE_OUT [, CTX] ) Close the C<PIPE_IN> and C<PIPE_OUT> as returned from C<command_bidi_pipe()>, checking whether the command finished successfully. The optional C<CTX> argument is required if you want to see the command name in the error message, and it is the fourth value returned by C<command_bidi_pipe()>. The call idiom is: my ($pid, $in, $out, $ctx) = $r->command_bidi_pipe(qw(cat-file --batch-check)); print $out "000000000\n"; while (<$in>) { ... } $r->command_close_bidi_pipe($pid, $in, $out, $ctx); Note that you should not rely on whatever actually is in C<CTX>; currently it is simply the command name but in future the context might have more complicated structure. C<PIPE_IN> and C<PIPE_OUT> may be C<undef> if they have been closed prior to calling this function. This may be useful in a query-response type of commands where caller first writes a query and later reads response, eg: my ($pid, $in, $out, $ctx) = $r->command_bidi_pipe(qw(cat-file --batch-check)); print $out "000000000\n"; close $out; while (<$in>) { ... } $r->command_close_bidi_pipe($pid, $in, undef, $ctx); This idiom may prevent potential dead locks caused by data sent to the output pipe not being flushed and thus not reaching the executed command. =cut sub command_close_bidi_pipe { local $?; my ($self, $pid, $in, $out, $ctx) = _maybe_self(@_); _cmd_close($ctx, (grep { defined } ($in, $out))); waitpid $pid, 0; if ($? >> 8) { throw Git::Error::Command($ctx, $? >>8); } } =item command_noisy ( COMMAND [, ARGUMENTS... ] ) Execute the given C<COMMAND> in the same way as command() does but do not capture the command output - the standard output is not redirected and goes to the standard output of the caller application. While the method is called command_noisy(), you might want to as well use it for the most silent Git commands which you know will never pollute your stdout but you want to avoid the overhead of the pipe setup when calling them. The function returns only after the command has finished running. =cut sub command_noisy { my ($self, $cmd, @args) = _maybe_self(@_); _check_valid_cmd($cmd); my $pid = fork; if (not defined $pid) { throw Error::Simple("fork failed: $!"); } elsif ($pid == 0) { _cmd_exec($self, $cmd, @args); } if (waitpid($pid, 0) > 0 and $?>>8 != 0) { throw Git::Error::Command(join(' ', $cmd, @args), $? >> 8); } } =item version () Return the Git version in use. =cut sub version { my $verstr = command_oneline('--version'); $verstr =~ s/^git version //; $verstr; } =item exec_path () Return path to the Git sub-command executables (the same as C<git --exec-path>). Useful mostly only internally. =cut sub exec_path { command_oneline('--exec-path') } =item html_path () Return path to the Git html documentation (the same as C<git --html-path>). Useful mostly only internally. =cut sub html_path { command_oneline('--html-path') } =item get_tz_offset ( TIME ) Return the time zone offset from GMT in the form +/-HHMM where HH is the number of hours from GMT and MM is the number of minutes. This is the equivalent of what strftime("%z", ...) would provide on a GNU platform. If TIME is not supplied, the current local time is used. =cut sub get_tz_offset { # some systems don't handle or mishandle %z, so be creative. my $t = shift \|\| time; my @t = localtime($t); $t[5] += 1900; require Time::Local; my $gm = Time::Local::timegm(@t); my $sign = qw( + + - )[ $gm <=> $t ]; return sprintf("%s%02d%02d", $sign, (gmtime(abs($t - $gm)))[2,1]); } =item get_record ( FILEHANDLE, INPUT_RECORD_SEPARATOR ) Read one record from FILEHANDLE delimited by INPUT_RECORD_SEPARATOR, removing any trailing INPUT_RECORD_SEPARATOR. =cut sub get_record { my ($fh, $rs) = @_; local $/ = $rs; my $rec = <$fh>; chomp $rec if defined $rec; $rec; } =item prompt ( PROMPT , ISPASSWORD ) Query user C<PROMPT> and return answer from user. Honours GIT_ASKPASS and SSH_ASKPASS environment variables for querying the user. If no _ASKPASS variable is set or an error occurred, the terminal is tried as a fallback. If C<ISPASSWORD> is set and true, the terminal disables echo. =cut sub prompt { my ($prompt, $isPassword) = @_; my $ret; if (exists $ENV{'GIT_ASKPASS'}) { $ret = _prompt($ENV{'GIT_ASKPASS'}, $prompt); } if (!defined $ret && exists $ENV{'SSH_ASKPASS'}) { $ret = _prompt($ENV{'SSH_ASKPASS'}, $prompt); } if (!defined $ret) { print STDERR $prompt; STDERR->flush; if (defined $isPassword && $isPassword) { require Term::ReadKey; Term::ReadKey::ReadMode('noecho'); $ret = ''; while (defined(my $key = Term::ReadKey::ReadKey(0))) { last if $key =~ /[\012\015]/; # \n\r $ret .= $key; } Term::ReadKey::ReadMode('restore'); print STDERR "\n"; STDERR->flush; } else { chomp($ret = <STDIN>); } } return $ret; } sub _prompt { my ($askpass, $prompt) = @_; return unless length $askpass; $prompt =~ s/\n/ /g; my $ret; open my $fh, "-\|", $askpass, $prompt or return; $ret = <$fh>; $ret =~ s/[\015\012]//g; # strip \r\n, chomp does not work on all systems (i.e. windows) as expected close ($fh); return $ret; } =item repo_path () Return path to the git repository. Must be called on a repository instance. =cut sub repo_path { $_[0]->{opts}->{Repository} } =item wc_path () Return path to the working copy. Must be called on a repository instance. =cut sub wc_path { $_[0]->{opts}->{WorkingCopy} } =item wc_subdir () Return path to the subdirectory inside of a working copy. Must be called on a repository instance. =cut sub wc_subdir { $_[0]->{opts}->{WorkingSubdir} \|\|= '' } =item wc_chdir ( SUBDIR ) Change the working copy subdirectory to work within. The C<SUBDIR> is relative to the working copy root directory (not the current subdirectory). Must be called on a repository instance attached to a working copy and the directory must exist. =cut sub wc_chdir { my ($self, $subdir) = @_; $self->wc_path() or throw Error::Simple("bare repository"); -d $self->wc_path().'/'.$subdir or throw Error::Simple("subdir not found: $subdir $!"); # Of course we will not "hold" the subdirectory so anyone # can delete it now and we will never know. But at least we tried. $self->{opts}->{WorkingSubdir} = $subdir; } =item config ( VARIABLE ) Retrieve the configuration C<VARIABLE> in the same manner as C<config> does. In scalar context requires the variable to be set only one time (exception is thrown otherwise), in array context returns allows the variable to be set multiple times and returns all the values. =cut sub config { return _config_common({}, @_); } =item config_bool ( VARIABLE ) Retrieve the bool configuration C<VARIABLE>. The return value is usable as a boolean in perl (and C<undef> if it's not defined, of course). =cut sub config_bool { my $val = scalar _config_common({'kind' => '--bool'}, @_); # Do not rewrite this as return (defined $val && $val eq 'true') # as some callers do care what kind of falsehood they receive. if (!defined $val) { return undef; } else { return $val eq 'true'; } } =item config_path ( VARIABLE ) Retrieve the path configuration C<VARIABLE>. The return value is an expanded path or C<undef> if it's not defined. =cut sub config_path { return _config_common({'kind' => '--path'}, @_); } =item config_int ( VARIABLE ) Retrieve the integer configuration C<VARIABLE>. The return value is simple decimal number. An optional value suffix of 'k', 'm', or 'g' in the config file will cause the value to be multiplied by 1024, 1048576 (1024^2), or 1073741824 (1024^3) prior to output. It would return C<undef> if configuration variable is not defined. =cut sub config_int { return scalar _config_common({'kind' => '--int'}, @_); } =item config_regexp ( RE ) Retrieve the list of configuration key names matching the regular expression C<RE>. The return value is a list of strings matching this regex. =cut sub config_regexp { my ($self, $regex) = _maybe_self(@_); try { my @cmd = ('config', '--name-only', '--get-regexp', $regex); unshift @cmd, $self if $self; my @matches = command(@cmd); return @matches; } catch Git::Error::Command with { my $E = shift; if ($E->value() == 1) { my @matches = (); return @matches; } else { throw $E; } }; } # Common subroutine to implement bulk of what the config family of methods # do. This currently wraps command('config') so it is not so fast. sub _config_common { my ($opts) = shift @_; my ($self, $var) = _maybe_self(@_); try { my @cmd = ('config', $opts->{'kind'} ? $opts->{'kind'} : ()); unshift @cmd, $self if $self; if (wantarray) { return command(@cmd, '--get-all', $var); } else { return command_oneline(@cmd, '--get', $var); } } catch Git::Error::Command with { my $E = shift; if ($E->value() == 1) { # Key not found. return; } else { throw $E; } }; } =item get_colorbool ( NAME ) Finds if color should be used for NAMEd operation from the configuration, and returns boolean (true for "use color", false for "do not use color"). =cut sub get_colorbool { my ($self, $var) = @_; my $stdout_to_tty = (-t STDOUT) ? "true" : "false"; my $use_color = $self->command_oneline('config', '--get-colorbool', $var, $stdout_to_tty); return ($use_color eq 'true'); } =item get_color ( SLOT, COLOR ) Finds color for SLOT from the configuration, while defaulting to COLOR, and returns the ANSI color escape sequence: print $repo->get_color("color.interactive.prompt", "underline blue white"); print "some text"; print $repo->get_color("", "normal"); =cut sub get_color { my ($self, $slot, $default) = @_; my $color = $self->command_oneline('config', '--get-color', $slot, $default); if (!defined $color) { $color = ""; } return $color; } =item remote_refs ( REPOSITORY [, GROUPS [, REFGLOBS ] ] ) This function returns a hashref of refs stored in a given remote repository. The hash is in the format C<refname =\> hash>. For tags, the C<refname> entry contains the tag object while a C<refname^{}> entry gives the tagged objects. C<REPOSITORY> has the same meaning as the appropriate C<git-ls-remote> argument; either a URL or a remote name (if called on a repository instance). C<GROUPS> is an optional arrayref that can contain 'tags' to return all the tags and/or 'heads' to return all the heads. C<REFGLOB> is an optional array of strings containing a shell-like glob to further limit the refs returned in the hash; the meaning is again the same as the appropriate C<git-ls-remote> argument. This function may or may not be called on a repository instance. In the former case, remote names as defined in the repository are recognized as repository specifiers. =cut sub remote_refs { my ($self, $repo, $groups, $refglobs) = _maybe_self(@_); my @args; if (ref $groups eq 'ARRAY') { foreach (@$groups) { if ($_ eq 'heads') { push (@args, '--heads'); } elsif ($_ eq 'tags') { push (@args, '--tags'); } else { # Ignore unknown groups for future # compatibility } } } push (@args, $repo); if (ref $refglobs eq 'ARRAY') { push (@args, @$refglobs); } my @self = $self ? ($self) : (); # Ultra trickery my ($fh, $ctx) = Git::command_output_pipe(@self, 'ls-remote', @args); my %refs; while (<$fh>) { chomp; my ($hash, $ref) = split(/\t/, $_, 2); $refs{$ref} = $hash; } Git::command_close_pipe(@self, $fh, $ctx); return \%refs; } =item ident ( TYPE \| IDENTSTR ) =item ident_person ( TYPE \| IDENTSTR \| IDENTARRAY ) This suite of functions retrieves and parses ident information, as stored in the commit and tag objects or produced by C<var GIT_type_IDENT> (thus C<TYPE> can be either I<author> or I<committer>; case is insignificant). The C<ident> method retrieves the ident information from C<git var> and either returns it as a scalar string or as an array with the fields parsed. Alternatively, it can take a prepared ident string (e.g. from the commit object) and just parse it. C<ident_person> returns the person part of the ident - name and email; it can take the same arguments as C<ident> or the array returned by C<ident>. The synopsis is like: my ($name, $email, $time_tz) = ident('author'); "$name <$email>" eq ident_person('author'); "$name <$email>" eq ident_person($name); $time_tz =~ /^\d+ [+-]\d{4}$/; =cut sub ident { my ($self, $type) = _maybe_self(@_); my $identstr; if (lc $type eq lc 'committer' or lc $type eq lc 'author') { my @cmd = ('var', 'GIT_'.uc($type).'_IDENT'); unshift @cmd, $self if $self; $identstr = command_oneline(@cmd); } else { $identstr = $type; } if (wantarray) { return $identstr =~ /^(.) <(.)> (\d+ [+-]\d{4})$/; } else { return $identstr; } } sub ident_person { my ($self, @ident) = _maybe_self(@_); $#ident == 0 and @ident = $self ? $self->ident($ident[0]) : ident($ident[0]); return "$ident[0] <$ident[1]>"; } =item hash_object ( TYPE, FILENAME ) Compute the SHA1 object id of the given C<FILENAME> considering it is of the C<TYPE> object type (C<blob>, C<commit>, C<tree>). The method can be called without any instance or on a specified Git repository, it makes zero difference. The function returns the SHA1 hash. =cut # TODO: Support for passing FILEHANDLE instead of FILENAME sub hash_object { my ($self, $type, $file) = _maybe_self(@_); command_oneline('hash-object', '-t', $type, $file); } =item hash_and_insert_object ( FILENAME ) Compute the SHA1 object id of the given C<FILENAME> and add the object to the object database. The function returns the SHA1 hash. =cut # TODO: Support for passing FILEHANDLE instead of FILENAME sub hash_and_insert_object { my ($self, $filename) = @_; carp "Bad filename \"$filename\"" if $filename =~ /[\r\n]/; $self->_open_hash_and_insert_object_if_needed(); my ($in, $out) = ($self->{hash_object_in}, $self->{hash_object_out}); unless (print $out $filename, "\n") { $self->_close_hash_and_insert_object(); throw Error::Simple("out pipe went bad"); } chomp(my $hash = <$in>); unless (defined($hash)) { $self->_close_hash_and_insert_object(); throw Error::Simple("in pipe went bad"); } return $hash; } sub _open_hash_and_insert_object_if_needed { my ($self) = @_; return if defined($self->{hash_object_pid}); ($self->{hash_object_pid}, $self->{hash_object_in}, $self->{hash_object_out}, $self->{hash_object_ctx}) = $self->command_bidi_pipe(qw(hash-object -w --stdin-paths --no-filters)); } sub _close_hash_and_insert_object { my ($self) = @_; return unless defined($self->{hash_object_pid}); my @vars = map { 'hash_object_' . $_ } qw(pid in out ctx); command_close_bidi_pipe(@$self{@vars}); delete @$self{@vars}; } =item cat_blob ( SHA1, FILEHANDLE ) Prints the contents of the blob identified by C<SHA1> to C<FILEHANDLE> and returns the number of bytes printed. =cut sub cat_blob { my ($self, $sha1, $fh) = @_; $self->_open_cat_blob_if_needed(); my ($in, $out) = ($self->{cat_blob_in}, $self->{cat_blob_out}); unless (print $out $sha1, "\n") { $self->_close_cat_blob(); throw Error::Simple("out pipe went bad"); } my $description = <$in>; if ($description =~ / missing$/) { carp "$sha1 doesn't exist in the repository"; return -1; } if ($description !~ /^[0-9a-fA-F]{40}(?:[0-9a-fA-F]{24})? \S+ (\d+)$/) { carp "Unexpected result returned from git cat-file"; return -1; } my $size = $1; my $blob; my $bytesLeft = $size; while (1) { last unless $bytesLeft; my $bytesToRead = $bytesLeft < 1024 ? $bytesLeft : 1024; my $read = read($in, $blob, $bytesToRead); unless (defined($read)) { $self->_close_cat_blob(); throw Error::Simple("in pipe went bad"); } unless (print $fh $blob) { $self->_close_cat_blob(); throw Error::Simple("couldn't write to passed in filehandle"); } $bytesLeft -= $read; } # Skip past the trailing newline. my $newline; my $read = read($in, $newline, 1); unless (defined($read)) { $self->_close_cat_blob(); throw Error::Simple("in pipe went bad"); } unless ($read == 1 && $newline eq "\n") { $self->_close_cat_blob(); throw Error::Simple("didn't find newline after blob"); } return $size; } sub _open_cat_blob_if_needed { my ($self) = @_; return if defined($self->{cat_blob_pid}); ($self->{cat_blob_pid}, $self->{cat_blob_in}, $self->{cat_blob_out}, $self->{cat_blob_ctx}) = $self->command_bidi_pipe(qw(cat-file --batch)); } sub _close_cat_blob { my ($self) = @_; return unless defined($self->{cat_blob_pid}); my @vars = map { 'cat_blob_' . $_ } qw(pid in out ctx); command_close_bidi_pipe(@$self{@vars}); delete @$self{@vars}; } =item credential_read( FILEHANDLE ) Reads credential key-value pairs from C<FILEHANDLE>. Reading stops at EOF or when an empty line is encountered. Each line must be of the form C<key=value> with a non-empty key. Function returns hash with all read values. Any white space (other than new-line character) is preserved. =cut sub credential_read { my ($self, $reader) = _maybe_self(@_); my %credential; while (<$reader>) { chomp; if ($_ eq '') { last; } elsif (!/^([^=]+)=(.)$/) { throw Error::Simple("unable to parse git credential data:\n$_"); } $credential{$1} = $2; } return %credential; } =item credential_write( FILEHANDLE, CREDENTIAL_HASHREF ) Writes credential key-value pairs from hash referenced by C<CREDENTIAL_HASHREF> to C<FILEHANDLE>. Keys and values cannot contain new-lines or NUL bytes characters, and key cannot contain equal signs nor be empty (if they do Error::Simple is thrown). Any white space is preserved. If value for a key is C<undef>, it will be skipped. If C<'url'> key exists it will be written first. (All the other key-value pairs are written in sorted order but you should not depend on that). Once all lines are written, an empty line is printed. =cut sub credential_write { my ($self, $writer, $credential) = _maybe_self(@_); my ($key, $value); # Check if $credential is valid prior to writing anything while (($key, $value) = each %$credential) { if (!defined $key \|\| !length $key) { throw Error::Simple("credential key empty or undefined"); } elsif ($key =~ /[=\n\0]/) { throw Error::Simple("credential key contains invalid characters: $key"); } elsif (defined $value && $value =~ /[\n\0]/) { throw Error::Simple("credential value for key=$key contains invalid characters: $value"); } } for $key (sort { # url overwrites other fields, so it must come first return -1 if $a eq 'url'; return 1 if $b eq 'url'; return $a cmp $b; } keys %$credential) { if (defined $credential->{$key}) { print $writer $key, '=', $credential->{$key}, "\n"; } } print $writer "\n"; } sub _credential_run { my ($self, $credential, $op) = _maybe_self(@_); my ($pid, $reader, $writer, $ctx) = command_bidi_pipe('credential', $op); credential_write $writer, $credential; close $writer; if ($op eq "fill") { %$credential = credential_read $reader; } if (<$reader>) { throw Error::Simple("unexpected output from git credential $op response:\n$_\n"); } command_close_bidi_pipe($pid, $reader, undef, $ctx); } =item credential( CREDENTIAL_HASHREF [, OPERATION ] ) =item credential( CREDENTIAL_HASHREF, CODE ) Executes C<git credential> for a given set of credentials and specified operation. In both forms C<CREDENTIAL_HASHREF> needs to be a reference to a hash which stores credentials. Under certain conditions the hash can change. In the first form, C<OPERATION> can be C<'fill'>, C<'approve'> or C<'reject'>, and function will execute corresponding C<git credential> sub-command. If it's omitted C<'fill'> is assumed. In case of C<'fill'> the values stored in C<CREDENTIAL_HASHREF> will be changed to the ones returned by the C<git credential fill> command. The usual usage would look something like: my %cred = ( 'protocol' => 'https', 'host' => 'example.com', 'username' => 'bob' ); Git::credential \%cred; if (try_to_authenticate($cred{'username'}, $cred{'password'})) { Git::credential \%cred, 'approve'; ... do more stuff ... } else { Git::credential \%cred, 'reject'; } In the second form, C<CODE> needs to be a reference to a subroutine. The function will execute C<git credential fill> to fill the provided credential hash, then call C<CODE> with C<CREDENTIAL_HASHREF> as the sole argument. If C<CODE>'s return value is defined, the function will execute C<git credential approve> (if return value yields true) or C<git credential reject> (if return value is false). If the return value is undef, nothing at all is executed; this is useful, for example, if the credential could neither be verified nor rejected due to an unrelated network error. The return value is the same as what C<CODE> returns. With this form, the usage might look as follows: if (Git::credential { 'protocol' => 'https', 'host' => 'example.com', 'username' => 'bob' }, sub { my $cred = shift; return !!try_to_authenticate($cred->{'username'}, $cred->{'password'}); }) { ... do more stuff ... } =cut sub credential { my ($self, $credential, $op_or_code) = (_maybe_self(@_), 'fill'); if ('CODE' eq ref $op_or_code) { _credential_run $credential, 'fill'; my $ret = $op_or_code->($credential); if (defined $ret) { _credential_run $credential, $ret ? 'approve' : 'reject'; } return $ret; } else { _credential_run $credential, $op_or_code; } } { # %TEMP_ Lexical Context my (%TEMP_FILEMAP, %TEMP_FILES); =item temp_acquire ( NAME ) Attempts to retrieve the temporary file mapped to the string C<NAME>. If an associated temp file has not been created this session or was closed, it is created, cached, and set for autoflush and binmode. Internally locks the file mapped to C<NAME>. This lock must be released with C<temp_release()> when the temp file is no longer needed. Subsequent attempts to retrieve temporary files mapped to the same C<NAME> while still locked will cause an error. This locking mechanism provides a weak guarantee and is not threadsafe. It does provide some error checking to help prevent temp file refs writing over one another. In general, the L<File::Handle> returned should not be closed by consumers as it defeats the purpose of this caching mechanism. If you need to close the temp file handle, then you should use L<File::Temp> or another temp file faculty directly. If a handle is closed and then requested again, then a warning will issue. =cut sub temp_acquire { my $temp_fd = _temp_cache(@_); $TEMP_FILES{$temp_fd}{locked} = 1; $temp_fd; } =item temp_is_locked ( NAME ) Returns true if the internal lock created by a previous C<temp_acquire()> call with C<NAME> is still in effect. When temp_acquire is called on a C<NAME>, it internally locks the temporary file mapped to C<NAME>. That lock will not be released until C<temp_release()> is called with either the original C<NAME> or the L<File::Handle> that was returned from the original call to temp_acquire. Subsequent attempts to call C<temp_acquire()> with the same C<NAME> will fail unless there has been an intervening C<temp_release()> call for that C<NAME> (or its corresponding L<File::Handle> that was returned by the original C<temp_acquire()> call). If true is returned by C<temp_is_locked()> for a C<NAME>, an attempt to C<temp_acquire()> the same C<NAME> will cause an error unless C<temp_release> is first called on that C<NAME> (or its corresponding L<File::Handle> that was returned by the original C<temp_acquire()> call). =cut sub temp_is_locked { my ($self, $name) = _maybe_self(@_); my $temp_fd = \$TEMP_FILEMAP{$name}; defined $$temp_fd && $$temp_fd->opened && $TEMP_FILES{$$temp_fd}{locked}; } =item temp_release ( NAME ) =item temp_release ( FILEHANDLE ) Releases a lock acquired through C<temp_acquire()>. Can be called either with the C<NAME> mapping used when acquiring the temp file or with the C<FILEHANDLE> referencing a locked temp file. Warns if an attempt is made to release a file that is not locked. The temp file will be truncated before being released. This can help to reduce disk I/O where the system is smart enough to detect the truncation while data is in the output buffers. Beware that after the temp file is released and truncated, any operations on that file may fail miserably until it is re-acquired. All contents are lost between each release and acquire mapped to the same string. =cut sub temp_release { my ($self, $temp_fd, $trunc) = _maybe_self(@_); if (exists $TEMP_FILEMAP{$temp_fd}) { $temp_fd = $TEMP_FILES{$temp_fd}; } unless ($TEMP_FILES{$temp_fd}{locked}) { carp "Attempt to release temp file '", $temp_fd, "' that has not been locked"; } temp_reset($temp_fd) if $trunc and $temp_fd->opened; $TEMP_FILES{$temp_fd}{locked} = 0; undef; } sub _temp_cache { my ($self, $name) = _maybe_self(@_); my $temp_fd = \$TEMP_FILEMAP{$name}; if (defined $$temp_fd and $$temp_fd->opened) { if ($TEMP_FILES{$$temp_fd}{locked}) { throw Error::Simple("Temp file with moniker '" . $name . "' already in use"); } } else { if (defined $$temp_fd) { # then we're here because of a closed handle. carp "Temp file '", $name, "' was closed. Opening replacement."; } my $fname; my $tmpdir; if (defined $self) { $tmpdir = $self->repo_path(); } my $n = $name; $n =~ s/\W/_/g; # no strange chars require File::Temp; ($$temp_fd, $fname) = File::Temp::tempfile( "Git_${n}_XXXXXX", UNLINK => 1, DIR => $tmpdir, ) or throw Error::Simple("couldn't open new temp file"); $$temp_fd->autoflush; binmode $$temp_fd; $TEMP_FILES{$$temp_fd}{fname} = $fname; } $$temp_fd; } =item temp_reset ( FILEHANDLE ) Truncates and resets the position of the C<FILEHANDLE>. =cut sub temp_reset { my ($self, $temp_fd) = _maybe_self(@_); truncate $temp_fd, 0 or throw Error::Simple("couldn't truncate file"); sysseek($temp_fd, 0, Fcntl::SEEK_SET()) and seek($temp_fd, 0, Fcntl::SEEK_SET()) or throw Error::Simple("couldn't seek to beginning of file"); sysseek($temp_fd, 0, Fcntl::SEEK_CUR()) == 0 and tell($temp_fd) == 0 or throw Error::Simple("expected file position to be reset"); } =item temp_path ( NAME ) =item temp_path ( FILEHANDLE ) Returns the filename associated with the given tempfile. =cut sub temp_path { my ($self, $temp_fd) = _maybe_self(@_); if (exists $TEMP_FILEMAP{$temp_fd}) { $temp_fd = $TEMP_FILEMAP{$temp_fd}; } $TEMP_FILES{$temp_fd}{fname}; } sub END { unlink values %TEMP_FILEMAP if %TEMP_FILEMAP; } } # %TEMP_* Lexical Context =item prefix_lines ( PREFIX, STRING [, STRING... ]) Prefixes lines in C<STRING> with C<PREFIX>. =cut sub prefix_lines { my $prefix = shift; my $string = join("\n", @_); $string =~ s/^/$prefix/mg; return $string; } =item unquote_path ( PATH ) Unquote a quoted path containing c-escapes as returned by ls-files etc. when not using -z or when parsing the output of diff -u. =cut { my %cquote_map = ( "a" => chr(7), "b" => chr(8), "t" => chr(9), "n" => chr(10), "v" => chr(11), "f" => chr(12), "r" => chr(13), "\\" => "\\", "\042" => "\042", ); sub unquote_path { local ($_) = @_; my ($retval, $remainder); if (!/^\042(.)\042$/) { return $_; } ($_, $retval) = ($1, ""); while (/^([^\\])\\(.)$/) { $remainder = $2; $retval .= $1; for ($remainder) { if (/^([0-3][0-7][0-7])(.)$/) { $retval .= chr(oct($1)); $_ = $2; last; } if (/^([\\\042abtnvfr])(.)$/) { $retval .= $cquote_map{$1}; $_ = $2; last; } # This is malformed throw Error::Simple("invalid quoted path $_[0]"); } $_ = $remainder; } $retval .= $_; return $retval; } } =item get_comment_line_char ( ) Gets the core.commentchar configuration value. The value falls-back to '#' if core.commentchar is set to 'auto'. =cut sub get_comment_line_char { my $comment_line_char = config("core.commentchar") \|\| '#'; $comment_line_char = '#' if ($comment_line_char eq 'auto'); $comment_line_char = '#' if (length($comment_line_char) != 1); return $comment_line_char; } =item comment_lines ( STRING [, STRING... ]) Comments lines following core.commentchar configuration. =cut sub comment_lines { my $comment_line_char = get_comment_line_char; return prefix_lines("$comment_line_char ", @_); } =back =head1 ERROR HANDLING All functions are supposed to throw Perl exceptions in case of errors. See the L<Error> module on how to catch those. Most exceptions are mere L<Error::Simple> instances. However, the C<command()>, C<command_oneline()> and C<command_noisy()> functions suite can throw C<Git::Error::Command> exceptions as well: those are thrown when the external command returns an error code and contain the error code as well as access to the captured command's output. The exception class provides the usual C<stringify> and C<value> (command's exit code) methods and in addition also a C<cmd_output> method that returns either an array or a string with the captured command output (depending on the original function call context; C<command_noisy()> returns C<undef>) and $<cmdline> which returns the command and its arguments (but without proper quoting). Note that the C<command__pipe()> functions cannot throw this exception since it has no idea whether the command failed or not. You will only find out at the time you C<close> the pipe; if you want to have that automated, use C<command_close_pipe()>, which can throw the exception. =cut { package Git::Error::Command; @Git::Error::Command::ISA = qw(Error); sub new { my $self = shift; my $cmdline = '' . shift; my $value = 0 + shift; my $outputref = shift; my(@args) = (); local $Error::Depth = $Error::Depth + 1; push(@args, '-cmdline', $cmdline); push(@args, '-value', $value); push(@args, '-outputref', $outputref); $self->SUPER::new(-text => 'command returned error', @args); } sub stringify { my $self = shift; my $text = $self->SUPER::stringify; $self->cmdline() . ': ' . $text . ': ' . $self->value() . "\n"; } sub cmdline { my $self = shift; $self->{'-cmdline'}; } sub cmd_output { my $self = shift; my $ref = $self->{'-outputref'}; defined $ref or undef; if (ref $ref eq 'ARRAY') { return @$ref; } else { # SCALAR return $$ref; } } } =over 4 =item git_cmd_try { CODE } ERRMSG This magical statement will automatically catch any C<Git::Error::Command> exceptions thrown by C<CODE> and make your program die with C<ERRMSG> on its lips; the message will have %s substituted for the command line and %d for the exit status. This statement is useful mostly for producing more user-friendly error messages. In case of no exception caught the statement returns C<CODE>'s return value. Note that this is the only auto-exported function. =cut sub git_cmd_try(&$) { my ($code, $errmsg) = @_; my @result; my $err; my $array = wantarray; try { if ($array) { @result = &$code; } else { $result[0] = &$code; } } catch Git::Error::Command with { my $E = shift; $err = $errmsg; $err =~ s/\%s/$E->cmdline()/ge; $err =~ s/\%d/$E->value()/ge; # We can't croak here since Error.pm would mangle # that to Error::Simple. }; $err and croak $err; return $array ? @result : $result[0]; } =back =head1 COPYRIGHT Copyright 2006 by Petr Baudis E<lt>pasky@suse.czE<gt>. This module is free software; it may be used, copied, modified and distributed under the terms of the GNU General Public Licence, either version 2, or (at your option) any later version. =cut # Take raw method argument list and return ($obj, @args) in case # the method was called upon an instance and (undef, @args) if # it was called directly. sub _maybe_self { UNIVERSAL::isa($_[0], 'Git') ? @_ : (undef, @_); } # Check if the command id is something reasonable. sub _check_valid_cmd { my ($cmd) = @_; $cmd =~ /^[a-z0-9A-Z_-]+$/ or throw Error::Simple("bad command: $cmd"); } # Common backend for the pipe creators. sub _command_common_pipe { my $direction = shift; my ($self, @p) = _maybe_self(@_); my (%opts, $cmd, @args); if (ref $p[0]) { ($cmd, @args) = @{shift @p}; %opts = ref $p[0] ? %{$p[0]} : @p; } else { ($cmd, @args) = @p; } _check_valid_cmd($cmd); my $fh; if ($^O eq 'MSWin32') { # ActiveState Perl #defined $opts{STDERR} and # warn 'ignoring STDERR option - running w/ ActiveState'; $direction eq '-\|' or die 'input pipe for ActiveState not implemented'; # the strange construction with ACPIPE is just to # explain the tie below that we want to bind to # a handle class, not scalar. It is not known if # it is something specific to ActiveState Perl or # just a Perl quirk. tie (ACPIPE, 'Git::activestate_pipe', $cmd, @args); $fh = ACPIPE; } else { my $pid = open($fh, $direction); if (not defined $pid) { throw Error::Simple("open failed: $!"); } elsif ($pid == 0) { if ($opts{STDERR}) { open (STDERR, '>&', $opts{STDERR}) or die "dup failed: $!"; } elsif (defined $opts{STDERR}) { open (STDERR, '>', '/dev/null') or die "opening /dev/null failed: $!"; } _cmd_exec($self, $cmd, @args); } } return wantarray ? ($fh, join(' ', $cmd, @args)) : $fh; } # When already in the subprocess, set up the appropriate state # for the given repository and execute the git command. sub _cmd_exec { my ($self, @args) = @_; _setup_git_cmd_env($self); _execv_git_cmd(@args); die qq[exec "@args" failed: $!]; } # set up the appropriate state for git command sub _setup_git_cmd_env { my $self = shift; if ($self) { $self->repo_path() and $ENV{'GIT_DIR'} = $self->repo_path(); $self->repo_path() and $self->wc_path() and $ENV{'GIT_WORK_TREE'} = $self->wc_path(); $self->wc_path() and chdir($self->wc_path()); $self->wc_subdir() and chdir($self->wc_subdir()); } } # Execute the given Git command ($_[0]) with arguments ($_[1..]) # by searching for it at proper places. sub _execv_git_cmd { exec('git', @_); } sub _is_sig { my ($v, $n) = @_; # We are avoiding a "use POSIX qw(SIGPIPE SIGABRT)" in the hot # Git.pm codepath. require POSIX; no strict 'refs'; $v == {"POSIX::$n"}->(); } # Close pipe to a subprocess. sub _cmd_close { my $ctx = shift @_; foreach my $fh (@_) { if (close $fh) { # nop } elsif ($!) { # It's just close, no point in fatalities carp "error closing pipe: $!"; } elsif ($? >> 8) { # The caller should pepper this. throw Git::Error::Command($ctx, $? >> 8); } elsif ($? & 127 && _is_sig($? & 127, "SIGPIPE")) { # we might e.g. closed a live stream; the command # dying of SIGPIPE would drive us here. } elsif ($? & 127 && _is_sig($? & 127, "SIGABRT")) { die sprintf('BUG?: got SIGABRT ($? = %d, $? & 127 = %d) when closing pipe', $?, $? & 127); } elsif ($? & 127) { die sprintf('got signal ($? = %d, $? & 127 = %d) when closing pipe', $?, $? & 127); } } } sub DESTROY { my ($self) = @_; $self->_close_hash_and_insert_object(); $self->_close_cat_blob(); } # Pipe implementation for ActiveState Perl. package Git::activestate_pipe; sub TIEHANDLE { my ($class, @params) = @_; # FIXME: This is probably horrible idea and the thing will explode # at the moment you give it arguments that require some quoting, # but I have no ActiveState clue... --pasky # Let's just hope ActiveState Perl does at least the quoting # correctly. my @data = qx{git @params}; bless { i => 0, data => \@data }, $class; } sub READLINE { my $self = shift; if ($self->{i} >= scalar @{$self->{data}}) { return undef; } my $i = $self->{i}; if (wantarray) { $self->{i} = $#{$self->{'data'}} + 1; return splice(@{$self->{'data'}}, $i); } $self->{i} = $i + 1; return $self->{'data'}->[ $i ]; } sub CLOSE { my $self = shift; delete $self->{data}; delete $self->{i}; } sub EOF { my $self = shift; return ($self->{i} >= scalar @{$self->{data}}); } 1; # Famous last words	46.87 KB	2025-07-21 16:27
📁 HTTP	-	2025-02-27 15:06
📁 IO	-	2022-02-16 11:58
📁 Mail	-	2025-05-25 12:19
📁 Math	-	2025-05-25 12:29
📁 Mozilla	-	2025-02-27 15:06
📁 Net	-	2025-02-27 15:06
📁 Pod	-	2025-02-27 15:06
📁 Term	-	2025-02-27 15:06
📁 Text	-	2025-02-27 15:06
📁 Thread	-	2025-05-25 12:19
📁 Time	-	2025-02-27 15:06
📁 UUID	-	2025-05-25 12:47
📄 constant.pm package constant; use 5.008; use strict; use warnings::register; our $VERSION = '1.33'; our %declared; #======================================================================= # Some names are evil choices. my %keywords = map +($_, 1), qw{ BEGIN INIT CHECK END DESTROY AUTOLOAD }; $keywords{UNITCHECK}++ if $] > 5.009; my %forced_into_main = map +($_, 1), qw{ STDIN STDOUT STDERR ARGV ARGVOUT ENV INC SIG }; my %forbidden = (%keywords, %forced_into_main); my $normal_constant_name = qr/^_?[^\W_0-9]\w\z/; my $tolerable = qr/^[A-Za-z_]\w\z/; my $boolean = qr/^[01]?\z/; BEGIN { # We'd like to do use constant _CAN_PCS => $] > 5.009002 # but that's a bit tricky before we load the constant module :-) # By doing this, we save several run time checks for every call # to import. my $const = $] > 5.009002; my $downgrade = $] < 5.015004; # && $] >= 5.008 my $constarray = exists &_make_const; if ($const) { Internals::SvREADONLY($const, 1); Internals::SvREADONLY($downgrade, 1); $constant::{_CAN_PCS} = \$const; $constant::{_DOWNGRADE} = \$downgrade; $constant::{_CAN_PCS_FOR_ARRAY} = \$constarray; } else { no strict 'refs'; {"_CAN_PCS"} = sub () {$const}; {"_DOWNGRADE"} = sub () { $downgrade }; {"_CAN_PCS_FOR_ARRAY"} = sub () { $constarray }; } } #======================================================================= # import() - import symbols into user's namespace # # What we actually do is define a function in the caller's namespace # which returns the value. The function we create will normally # be inlined as a constant, thereby avoiding further sub calling # overhead. #======================================================================= sub import { my $class = shift; return unless @_; # Ignore 'use constant;' my $constants; my $multiple = ref $_[0]; my $caller = caller; my $flush_mro; my $symtab; if (_CAN_PCS) { no strict 'refs'; $symtab = \%{$caller . '::'}; }; if ( $multiple ) { if (ref $_[0] ne 'HASH') { require Carp; Carp::croak("Invalid reference type '".ref(shift)."' not 'HASH'"); } $constants = shift; } else { unless (defined $_[0]) { require Carp; Carp::croak("Can't use undef as constant name"); } $constants->{+shift} = undef; } foreach my $name ( keys %$constants ) { my $pkg; my $symtab = $symtab; my $orig_name = $name; if ($name =~ s/(.)(?:::\|')(?=.)//s) { $pkg = $1; if (_CAN_PCS && $pkg ne $caller) { no strict 'refs'; $symtab = \%{$pkg . '::'}; } } else { $pkg = $caller; } # Normal constant name if ($name =~ $normal_constant_name and !$forbidden{$name}) { # Everything is okay # Name forced into main, but we're not in main. Fatal. } elsif ($forced_into_main{$name} and $pkg ne 'main') { require Carp; Carp::croak("Constant name '$name' is forced into main::"); # Starts with double underscore. Fatal. } elsif ($name =~ /^__/) { require Carp; Carp::croak("Constant name '$name' begins with '__'"); # Maybe the name is tolerable } elsif ($name =~ $tolerable) { # Then we'll warn only if you've asked for warnings if (warnings::enabled()) { if ($keywords{$name}) { warnings::warn("Constant name '$name' is a Perl keyword"); } elsif ($forced_into_main{$name}) { warnings::warn("Constant name '$name' is " . "forced into package main::"); } } # Looks like a boolean # use constant FRED == fred; } elsif ($name =~ $boolean) { require Carp; if (@_) { Carp::croak("Constant name '$name' is invalid"); } else { Carp::croak("Constant name looks like boolean value"); } } else { # Must have bad characters require Carp; Carp::croak("Constant name '$name' has invalid characters"); } { no strict 'refs'; my $full_name = "${pkg}::$name"; $declared{$full_name}++; if ($multiple \|\| @_ == 1) { my $scalar = $multiple ? $constants->{$orig_name} : $_[0]; if (_DOWNGRADE) { # for 5.8 to 5.14 # Work around perl bug #31991: Sub names (actually glob # names in general) ignore the UTF8 flag. So we have to # turn it off to get the "right" symbol table entry. utf8::is_utf8 $name and utf8::encode $name; } # The constant serves to optimise this entire block out on # 5.8 and earlier. if (_CAN_PCS) { # Use a reference as a proxy for a constant subroutine. # If this is not a glob yet, it saves space. If it is # a glob, we must still create it this way to get the # right internal flags set, as constants are distinct # from subroutines created with sub(){...}. # The check in Perl_ck_rvconst knows that inlinable # constants from cv_const_sv are read only. So we have to: Internals::SvREADONLY($scalar, 1); if (!exists $symtab->{$name}) { $symtab->{$name} = \$scalar; ++$flush_mro->{$pkg}; } else { local $constant::{_dummy} = \$scalar; $full_name = \&{"_dummy"}; } } else { $full_name = sub () { $scalar }; } } elsif (@_) { my @list = @_; if (_CAN_PCS_FOR_ARRAY) { _make_const($list[$_]) for 0..$#list; _make_const(@list); if (!exists $symtab->{$name}) { $symtab->{$name} = \@list; $flush_mro->{$pkg}++; } else { local $constant::{_dummy} = \@list; $full_name = \&{"_dummy"}; } } else { $full_name = sub () { @list }; } } else { $full_name = sub () { }; } } } # Flush the cache exactly once if we make any direct symbol table changes. if (_CAN_PCS && $flush_mro) { mro::method_changed_in($_) for keys %$flush_mro; } } 1; __END__ =head1 NAME constant - Perl pragma to declare constants =head1 SYNOPSIS use constant PI => 4 atan2(1, 1); use constant DEBUG => 0; print "Pi equals ", PI, "...\n" if DEBUG; use constant { SEC => 0, MIN => 1, HOUR => 2, MDAY => 3, MON => 4, YEAR => 5, WDAY => 6, YDAY => 7, ISDST => 8, }; use constant WEEKDAYS => qw( Sunday Monday Tuesday Wednesday Thursday Friday Saturday ); print "Today is ", (WEEKDAYS)[ (localtime)[WDAY] ], ".\n"; =head1 DESCRIPTION This pragma allows you to declare constants at compile-time. When you declare a constant such as C<PI> using the method shown above, each machine your script runs upon can have as many digits of accuracy as it can use. Also, your program will be easier to read, more likely to be maintained (and maintained correctly), and far less likely to send a space probe to the wrong planet because nobody noticed the one equation in which you wrote C<3.14195>. When a constant is used in an expression, Perl replaces it with its value at compile time, and may then optimize the expression further. In particular, any code in an C<if (CONSTANT)> block will be optimized away if the constant is false. =head1 NOTES As with all C<use> directives, defining a constant happens at compile time. Thus, it's probably not correct to put a constant declaration inside of a conditional statement (like C<if ($foo) { use constant ... }>). Constants defined using this module cannot be interpolated into strings like variables. However, concatenation works just fine: print "Pi equals PI...\n"; # WRONG: does not expand "PI" print "Pi equals ".PI."...\n"; # right Even though a reference may be declared as a constant, the reference may point to data which may be changed, as this code shows. use constant ARRAY => [ 1,2,3,4 ]; print ARRAY->[1]; ARRAY->[1] = " be changed"; print ARRAY->[1]; Constants belong to the package they are defined in. To refer to a constant defined in another package, specify the full package name, as in C<Some::Package::CONSTANT>. Constants may be exported by modules, and may also be called as either class or instance methods, that is, as C<< Some::Package->CONSTANT >> or as C<< $obj->CONSTANT >> where C<$obj> is an instance of C<Some::Package>. Subclasses may define their own constants to override those in their base class. As of version 1.32 of this module, constants can be defined in packages other than the caller, by including the package name in the name of the constant: use constant "OtherPackage::FWIBBLE" => 7865; constant->import("Other::FWOBBLE",$value); # dynamically at run time The use of all caps for constant names is merely a convention, although it is recommended in order to make constants stand out and to help avoid collisions with other barewords, keywords, and subroutine names. Constant names must begin with a letter or underscore. Names beginning with a double underscore are reserved. Some poor choices for names will generate warnings, if warnings are enabled at compile time. =head2 List constants Constants may be lists of more (or less) than one value. A constant with no values evaluates to C<undef> in scalar context. Note that constants with more than one value do I<not> return their last value in scalar context as one might expect. They currently return the number of values, but B<this may change in the future>. Do not use constants with multiple values in scalar context. B<NOTE:> This implies that the expression defining the value of a constant is evaluated in list context. This may produce surprises: use constant TIMESTAMP => localtime; # WRONG! use constant TIMESTAMP => scalar localtime; # right The first line above defines C<TIMESTAMP> as a 9-element list, as returned by C<localtime()> in list context. To set it to the string returned by C<localtime()> in scalar context, an explicit C<scalar> keyword is required. List constants are lists, not arrays. To index or slice them, they must be placed in parentheses. my @workdays = WEEKDAYS[1 .. 5]; # WRONG! my @workdays = (WEEKDAYS)[1 .. 5]; # right =head2 Defining multiple constants at once Instead of writing multiple C<use constant> statements, you may define multiple constants in a single statement by giving, instead of the constant name, a reference to a hash where the keys are the names of the constants to be defined. Obviously, all constants defined using this method must have a single value. use constant { FOO => "A single value", BAR => "This", "won't", "work!", # Error! }; This is a fundamental limitation of the way hashes are constructed in Perl. The error messages produced when this happens will often be quite cryptic -- in the worst case there may be none at all, and you'll only later find that something is broken. When defining multiple constants, you cannot use the values of other constants defined in the same declaration. This is because the calling package doesn't know about any constant within that group until I<after> the C<use> statement is finished. use constant { BITMASK => 0xAFBAEBA8, NEGMASK => ~BITMASK, # Error! }; =head2 Magic constants Magical values and references can be made into constants at compile time, allowing for way cool stuff like this. (These error numbers aren't totally portable, alas.) use constant E2BIG => ($! = 7); print E2BIG, "\n"; # something like "Arg list too long" print 0+E2BIG, "\n"; # "7" You can't produce a tied constant by giving a tied scalar as the value. References to tied variables, however, can be used as constants without any problems. =head1 TECHNICAL NOTES In the current implementation, scalar constants are actually inlinable subroutines. As of version 5.004 of Perl, the appropriate scalar constant is inserted directly in place of some subroutine calls, thereby saving the overhead of a subroutine call. See L<perlsub/"Constant Functions"> for details about how and when this happens. In the rare case in which you need to discover at run time whether a particular constant has been declared via this module, you may use this function to examine the hash C<%constant::declared>. If the given constant name does not include a package name, the current package is used. sub declared ($) { use constant 1.01; # don't omit this! my $name = shift; $name =~ s/^::/main::/; my $pkg = caller; my $full_name = $name =~ /::/ ? $name : "${pkg}::$name"; $constant::declared{$full_name}; } =head1 CAVEATS List constants are not inlined unless you are using Perl v5.20 or higher. In v5.20 or higher, they are still not read-only, but that may change in future versions. It is not possible to have a subroutine or a keyword with the same name as a constant in the same package. This is probably a Good Thing. A constant with a name in the list C<STDIN STDOUT STDERR ARGV ARGVOUT ENV INC SIG> is not allowed anywhere but in package C<main::>, for technical reasons. Unlike constants in some languages, these cannot be overridden on the command line or via environment variables. You can get into trouble if you use constants in a context which automatically quotes barewords (as is true for any subroutine call). For example, you can't say C<$hash{CONSTANT}> because C<CONSTANT> will be interpreted as a string. Use C<$hash{CONSTANT()}> or C<$hash{+CONSTANT}> to prevent the bareword quoting mechanism from kicking in. Similarly, since the C<< => >> operator quotes a bareword immediately to its left, you have to say C<< CONSTANT() => 'value' >> (or simply use a comma in place of the big arrow) instead of C<< CONSTANT => 'value' >>. =head1 SEE ALSO L<Readonly> - Facility for creating read-only scalars, arrays, hashes. L<Attribute::Constant> - Make read-only variables via attribute L<Scalar::Readonly> - Perl extension to the C<SvREADONLY> scalar flag L<Hash::Util> - A selection of general-utility hash subroutines (mostly to lock/unlock keys and values) =head1 BUGS Please report any bugs or feature requests via the perlbug(1) utility. =head1 AUTHORS Tom Phoenix, E<lt>F<rootbeer@redcat.com>E<gt>, with help from many other folks. Multiple constant declarations at once added by Casey West, E<lt>F<casey@geeknest.com>E<gt>. Documentation mostly rewritten by Ilmari Karonen, E<lt>F<perl@itz.pp.sci.fi>E<gt>. This program is maintained by the Perl 5 Porters. The CPAN distribution is maintained by SE<eacute>bastien Aperghis-Tramoni E<lt>F<sebastien@aperghis.net>E<gt>. =head1 COPYRIGHT & LICENSE Copyright (C) 1997, 1999 Tom Phoenix This module is free software; you can redistribute it or modify it under the same terms as Perl itself. =cut	14.38 KB	2022-02-16 13:19
📄 newgetopt.pl # Id: newgetopt.pl,v 1.18 2001/09/21 13:34:59 jv # This library is no longer being maintained, and is included for backward # compatibility with Perl 4 programs which may require it. # It is now just a wrapper around the Getopt::Long module. # # In particular, this should not be used as an example of modern Perl # programming techniques. # # Suggested alternative: Getopt::Long { package newgetopt; # Values for $order. See GNU getopt.c for details. $REQUIRE_ORDER = 0; $PERMUTE = 1; $RETURN_IN_ORDER = 2; # Handle POSIX compliancy. if ( defined $ENV{"POSIXLY_CORRECT"} ) { $autoabbrev = 0; # no automatic abbrev of options (???) $getopt_compat = 0; # disallow '+' to start options $option_start = "(--\|-)"; $order = $REQUIRE_ORDER; $bundling = 0; $passthrough = 0; } else { $autoabbrev = 1; # automatic abbrev of options $getopt_compat = 1; # allow '+' to start options $option_start = "(--\|-\|\\+)"; $order = $PERMUTE; $bundling = 0; $passthrough = 0; } # Other configurable settings. $debug = 0; # for debugging $ignorecase = 1; # ignore case when matching options $argv_end = "--"; # don't change this! } use Getopt::Long; ################ Subroutines ################ sub NGetOpt { $Getopt::Long::debug = $newgetopt::debug if defined $newgetopt::debug; $Getopt::Long::autoabbrev = $newgetopt::autoabbrev if defined $newgetopt::autoabbrev; $Getopt::Long::getopt_compat = $newgetopt::getopt_compat if defined $newgetopt::getopt_compat; $Getopt::Long::option_start = $newgetopt::option_start if defined $newgetopt::option_start; $Getopt::Long::order = $newgetopt::order if defined $newgetopt::order; $Getopt::Long::bundling = $newgetopt::bundling if defined $newgetopt::bundling; $Getopt::Long::ignorecase = $newgetopt::ignorecase if defined $newgetopt::ignorecase; $Getopt::Long::ignorecase = $newgetopt::ignorecase if defined $newgetopt::ignorecase; $Getopt::Long::passthrough = $newgetopt::passthrough if defined $newgetopt::passthrough; &GetOptions; } ################ Package return ################ 1; ################ End of newgetopt.pl ################	2.15 KB	2010-07-09 12:26
📄 parent.pm package parent; use strict; our $VERSION = '0.238'; sub import { my $class = shift; my $inheritor = caller(0); if ( @_ and $_[0] eq '-norequire' ) { shift @_; } else { for ( my @filename = @_ ) { s{::\|'}{/}g; require "$_.pm"; # dies if the file is not found } } { no strict 'refs'; push @{"$inheritor\::ISA"}, @_; # dies if a loop is detected }; }; 1; __END__ =encoding utf8 =head1 NAME parent - Establish an ISA relationship with base classes at compile time =head1 SYNOPSIS package Baz; use parent qw(Foo Bar); =head1 DESCRIPTION Allows you to both load one or more modules, while setting up inheritance from those modules at the same time. Mostly similar in effect to package Baz; BEGIN { require Foo; require Bar; push @ISA, qw(Foo Bar); } By default, every base class needs to live in a file of its own. If you want to have a subclass and its parent class in the same file, you can tell C<parent> not to load any modules by using the C<-norequire> switch: package Foo; sub exclaim { "I CAN HAS PERL" } package DoesNotLoadFooBar; use parent -norequire, 'Foo', 'Bar'; # will not go looking for Foo.pm or Bar.pm This is equivalent to the following code: package Foo; sub exclaim { "I CAN HAS PERL" } package DoesNotLoadFooBar; push @DoesNotLoadFooBar::ISA, 'Foo', 'Bar'; This is also helpful for the case where a package lives within a differently named file: package MyHash; use Tie::Hash; use parent -norequire, 'Tie::StdHash'; This is equivalent to the following code: package MyHash; require Tie::Hash; push @ISA, 'Tie::StdHash'; If you want to load a subclass from a file that C<require> would not consider an eligible filename (that is, it does not end in either C<.pm> or C<.pmc>), use the following code: package MySecondPlugin; require './plugins/custom.plugin'; # contains Plugin::Custom use parent -norequire, 'Plugin::Custom'; =head1 HISTORY This module was forked from L<base> to remove the cruft that had accumulated in it. =head1 CAVEATS =head1 SEE ALSO =over 4 =item L<base> =item L<parent::versioned> A fork of L<parent> that provides version checking in parent class modules. =back =head1 AUTHORS AND CONTRIBUTORS Rafaël Garcia-Suarez, Bart Lateur, Max Maischein, Anno Siegel, Michael Schwern =head1 MAINTAINER Max Maischein C< corion@cpan.org > Copyright (c) 2007-2017 Max Maischein C<< <corion@cpan.org> >> Based on the idea of C<base.pm>, which was introduced with Perl 5.004_04. =head1 LICENSE This module is released under the same terms as Perl itself. =cut	2.64 KB	2020-02-07 07:43
📄 perldoc.pod =head1 NAME perldoc - Look up Perl documentation in Pod format. =head1 SYNOPSIS perldoc [-h] [-D] [-t] [-u] [-m] [-l] [-U] [-F] [-i] [-V] [-T] [-r] [-d destination_file] [-o formatname] [-M FormatterClassName] [-w formatteroption:value] [-n nroff-replacement] [-X] [-L language_code] PageName\|ModuleName\|ProgramName\|URL Examples: perldoc -f BuiltinFunction perldoc -L it -f BuiltinFunction perldoc -q FAQ Keyword perldoc -L fr -q FAQ Keyword perldoc -v PerlVariable perldoc -a PerlAPI See below for more description of the switches. =head1 DESCRIPTION B<perldoc> looks up documentation in .pod format that is embedded in the perl installation tree or in a perl script, and displays it using a variety of formatters. This is primarily used for the documentation for the perl library modules. Your system may also have man pages installed for those modules, in which case you can probably just use the man(1) command. If you are looking for a table of contents to the Perl library modules documentation, see the L<perltoc> page. =head1 OPTIONS =over 5 =item B<-h> Prints out a brief B<h>elp message. =item B<-D> B<D>escribes search for the item in B<d>etail. =item B<-t> Display docs using plain B<t>ext converter, instead of nroff. This may be faster, but it probably won't look as nice. =item B<-u> Skip the real Pod formatting, and just show the raw Pod source (B<U>nformatted) =item B<-m> I<module> Display the entire module: both code and unformatted pod documentation. This may be useful if the docs don't explain a function in the detail you need, and you'd like to inspect the code directly; perldoc will find the file for you and simply hand it off for display. =item B<-l> Display onB<l>y the file name of the module found. =item B<-U> When running as the superuser, don't attempt drop privileges for security. This option is implied with B<-F>. B<NOTE>: Please see the heading SECURITY below for more information. =item B<-F> Consider arguments as file names; no search in directories will be performed. Implies B<-U> if run as the superuser. =item B<-f> I<perlfunc> The B<-f> option followed by the name of a perl built-in function will extract the documentation of this function from L<perlfunc>. Example: perldoc -f sprintf =item B<-q> I<perlfaq-search-regexp> The B<-q> option takes a regular expression as an argument. It will search the B<q>uestion headings in perlfaq[1-9] and print the entries matching the regular expression. Example: perldoc -q shuffle =item B<-a> I<perlapifunc> The B<-a> option followed by the name of a perl api function will extract the documentation of this function from L<perlapi>. Example: perldoc -a newHV =item B<-v> I<perlvar> The B<-v> option followed by the name of a Perl predefined variable will extract the documentation of this variable from L<perlvar>. Examples: perldoc -v '$"' perldoc -v @+ perldoc -v DATA =item B<-T> This specifies that the output is not to be sent to a pager, but is to be sent directly to STDOUT. =item B<-d> I<destination-filename> This specifies that the output is to be sent neither to a pager nor to STDOUT, but is to be saved to the specified filename. Example: C<perldoc -oLaTeX -dtextwrapdocs.tex Text::Wrap> =item B<-o> I<output-formatname> This specifies that you want Perldoc to try using a Pod-formatting class for the output format that you specify. For example: C<-oman>. This is actually just a wrapper around the C<-M> switch; using C<-oI<formatname>> just looks for a loadable class by adding that format name (with different capitalizations) to the end of different classname prefixes. For example, C<-oLaTeX> currently tries all of the following classes: Pod::Perldoc::ToLaTeX Pod::Perldoc::Tolatex Pod::Perldoc::ToLatex Pod::Perldoc::ToLATEX Pod::Simple::LaTeX Pod::Simple::latex Pod::Simple::Latex Pod::Simple::LATEX Pod::LaTeX Pod::latex Pod::Latex Pod::LATEX. =item B<-M> I<module-name> This specifies the module that you want to try using for formatting the pod. The class must at least provide a C<parse_from_file> method. For example: C<perldoc -MPod::Perldoc::ToChecker>. You can specify several classes to try by joining them with commas or semicolons, as in C<-MTk::SuperPod;Tk::Pod>. =item B<-w> I<option:value> or B<-w> I<option> This specifies an option to call the formatter B<w>ith. For example, C<-w textsize:15> will call C<< $formatter->textsize(15) >> on the formatter object before it is used to format the object. For this to be valid, the formatter class must provide such a method, and the value you pass should be valid. (So if C<textsize> expects an integer, and you do C<-w textsize:big>, expect trouble.) You can use C<-w optionname> (without a value) as shorthand for C<-w optionname:I<TRUE>>. This is presumably useful in cases of on/off features like: C<-w page_numbering>. You can use an "=" instead of the ":", as in: C<-w textsize=15>. This might be more (or less) convenient, depending on what shell you use. =item B<-X> Use an index if it is present. The B<-X> option looks for an entry whose basename matches the name given on the command line in the file C<$Config{archlib}/pod.idx>. The F<pod.idx> file should contain fully qualified filenames, one per line. =item B<-L> I<language_code> This allows one to specify the I<language code> for the desired language translation. If the C<POD2::E<lt>language_codeE<gt>> package isn't installed in your system, the switch is ignored. All available translation packages are to be found under the C<POD2::> namespace. See L<POD2::IT> (or L<POD2::FR>) to see how to create new localized C<POD2::*> documentation packages and integrate them into L<Pod::Perldoc>. =item B<PageName\|ModuleName\|ProgramName\|URL> The item you want to look up. Nested modules (such as C<File::Basename>) are specified either as C<File::Basename> or C<< File/Basename >>. You may also give a descriptive name of a page, such as C<perlfunc>. For URLs, HTTP and HTTPS are the only kind currently supported. For simple names like 'foo', when the normal search fails to find a matching page, a search with the "perl" prefix is tried as well. So "perldoc intro" is enough to find/render "perlintro.pod". =item B<-n> I<some-formatter> Specify replacement for groff =item B<-r> Recursive search. =item B<-i> Ignore case. =item B<-V> Displays the version of perldoc you're running. =back =head1 SECURITY Because B<perldoc> does not run properly tainted, and is known to have security issues, when run as the superuser it will attempt to drop privileges by setting the effective and real IDs to nobody's or nouser's account, or -2 if unavailable. If it cannot relinquish its privileges, it will not run. See the C<-U> option if you do not want this behavior but B<beware> that there are significant security risks if you choose to use C<-U>. Since 3.26, using C<-F> as the superuser also implies C<-U> as opening most files and traversing directories requires privileges that are above the nobody/nogroup level. =head1 ENVIRONMENT Any switches in the C<PERLDOC> environment variable will be used before the command line arguments. Useful values for C<PERLDOC> include C<-oterm>, C<-otext>, C<-ortf>, C<-oxml>, and so on, depending on what modules you have on hand; or the formatter class may be specified exactly with C<-MPod::Perldoc::ToTerm> or the like. C<perldoc> also searches directories specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not defined) and C<PATH> environment variables. (The latter is so that embedded pods for executables, such as C<perldoc> itself, are available.) In directories where either C<Makefile.PL> or C<Build.PL> exist, C<perldoc> will add C<.> and C<lib> first to its search path, and as long as you're not the superuser will add C<blib> too. This is really helpful if you're working inside of a build directory and want to read through the docs even if you have a version of a module previously installed. C<perldoc> will use, in order of preference, the pager defined in C<PERLDOC_PAGER>, C<MANPAGER>, or C<PAGER> before trying to find a pager on its own. (C<MANPAGER> is not used if C<perldoc> was told to display plain text or unformatted pod.) When using perldoc in it's C<-m> mode (display module source code), C<perldoc> will attempt to use the pager set in C<PERLDOC_SRC_PAGER>. A useful setting for this command is your favorite editor as in C</usr/bin/nano>. (Don't judge me.) One useful value for C<PERLDOC_PAGER> is C<less -+C -E>. Having PERLDOCDEBUG set to a positive integer will make perldoc emit even more descriptive output than the C<-D> switch does; the higher the number, the more it emits. =head1 CHANGES Up to 3.14_05, the switch B<-v> was used to produce verbose messages of B<perldoc> operation, which is now enabled by B<-D>. =head1 SEE ALSO L<perlpod>, L<Pod::Perldoc> =head1 AUTHOR Current maintainer: Mark Allen C<< <mallen@cpan.org> >> Past contributors are: brian d foy C<< <bdfoy@cpan.org> >> Adriano R. Ferreira C<< <ferreira@cpan.org> >>, Sean M. Burke C<< <sburke@cpan.org> >>, Kenneth Albanowski C<< <kjahds@kjahds.com> >>, Andy Dougherty C<< <doughera@lafcol.lafayette.edu> >>, and many others. =cut	9.16 KB	2016-08-02 16:31

Edit File:

Terminal