=for Pod::Functions get context of the current subroutine call
-Returns the context of the current subroutine call. In scalar context,
-returns the caller's package name if there I<is> a caller (that is, if
+Returns the context of the current pure perl subroutine call. In scalar
+context, returns the caller's package name if there I<is> a caller (that is, if
we're in a subroutine or C<eval> or C<require>) and the undefined value
-otherwise. In list context, returns
+otherwise. caller never returns XS subs and they are skipped. The next pure
+perl sub will appear instead of the XS sub in caller's return values. In list
+context, caller returns
# 0 1 2
($package, $filename, $line) = caller;
the entire process group specified. That
means you usually want to use positive not negative signals.
-If SIGNAL is either the number 0 or the string C<ZERO> (or C<SIGZZERO>),
+If SIGNAL is either the number 0 or the string C<ZERO> (or C<SIGZERO>),
no signal is sent to
the process, but C<kill> checks whether it's I<possible> to send a signal to it
(that means, to be brief, that the process is owned by the same user, or we are
considered a symbolic reference, so C<use strict "refs"> should I<not> be
in effect.)
-If EXPR is omitted, the global (package) scalar variable of the same
-name as the FILEHANDLE contains the filename. (Note that lexical
-variables--those declared with C<my> or C<state>--will not work for this
-purpose; so if you're using C<my> or C<state>, specify EXPR in your
-call to open.)
-
If three (or more) arguments are specified, the open mode (including
optional encoding) in the second argument are distinct from the filename in
the third. If MODE is C<< < >> or nothing, the file is opened for input.
modules that can help with that problem)) always check
the return value from opening a file.
+The filehandle will be closed when its reference count reaches zero.
+If it is a lexically scoped variable declared with C<my>, that usually
+means the end of the enclosing scope. However, this automatic close
+does not check for errors, so it is better to explicitly close
+filehandles, especially those used for writing:
+
+ close($handle)
+ || warn "close failed: $!";
+
+An older style is to use a bareword as the filehandle, as
+
+ open(FH, "<", "input.txt")
+ or die "cannot open < input.txt: $!";
+
+Then you can use C<FH> as the filehandle, in C<< close FH >> and C<<
+<FH> >> and so on. Note that it's a global variable, so this form is
+not recommended in new code.
+
+As a shortcut a one-argument call takes the filename from the global
+scalar variable of the same name as the filehandle:
+
+ $ARTICLE = 100;
+ open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";
+
+Here C<$ARTICLE> must be a global (package) scalar variable - not one
+declared with C<my> or C<state>.
+
As a special case the three-argument form with a read/write mode and the third
argument being C<undef>:
General examples:
- $ARTICLE = 100;
- open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";
- while (<ARTICLE>) {...
-
open(LOG, ">>/usr/spool/news/twitlog"); # (log is reserved)
# if the open fails, output is discarded
seek(HANDLE, 0, 0);
print "File contains: ", <HANDLE>;
-Using the constructor from the C<IO::Handle> package (or one of its
-subclasses, such as C<IO::File> or C<IO::Socket>), you can generate anonymous
-filehandles that have the scope of the variables used to hold them, then
-automatically (but silently) close once their reference counts become
-zero, typically at scope exit:
-
- use IO::File;
- #...
- sub read_myfile_munged {
- my $ALL = shift;
- # or just leave it undef to autoviv
- my $handle = IO::File->new;
- open($handle, "<", "myfile") or die "myfile: $!";
- $first = <$handle>
- or return (); # Automatically closed here.
- mung($first) or die "mung failed"; # Or here.
- return (first, <$handle>) if $ALL; # Or here.
- return $first; # Or here.
- }
-
-B<WARNING:> The previous example has a bug because the automatic
-close that happens when the refcount on C<handle> reaches zero does not
-properly detect and report failures. I<Always> close the handle
-yourself and inspect the return value.
-
- close($handle)
- || warn "close failed: $!";
-
See L</seek> for some details about mixing reading and writing.
Portability issues: L<perlport/open>.
=for Pod::Functions find out the type of thing being referenced
Returns a non-empty string if EXPR is a reference, the empty
-string otherwise. If EXPR
-is not specified, C<$_> will be used. The value returned depends on the
-type of thing the reference is a reference to.
+string otherwise. If EXPR is not specified, C<$_> will be used. The
+value returned depends on the type of thing the reference is a reference to.
+
Builtin types include:
SCALAR
VSTRING
Regexp
-If the referenced object has been blessed into a package, then that package
-name is returned instead. You can think of C<ref> as a C<typeof> operator.
+You can think of C<ref> as a C<typeof> operator.
if (ref($r) eq "HASH") {
print "r is a reference to a hash.\n";
The result C<Regexp> indicates that the argument is a regular expression
resulting from C<qr//>.
+If the referenced object has been blessed into a package, then that package
+name is returned instead. But don't use that, as it's now considered
+"bad practice". For one reason, an object could be using a class called
+C<Regexp> or C<IO>, or even C<HASH>. Also, C<ref> doesn't take into account
+subclasses, like C<isa> does.
+
+Instead, use C<blessed> (in the L<Scalar::Util> module) for boolean
+checks, C<isa> for specific class checks and C<reftype> (also from
+L<Scalar::Util>) for type checks. (See L<perlobj> for details and a
+C<blessed/isa> example.)
+
See also L<perlref>.
=item rename OLDNAME,NEWNAME
hasn't already been included. The file is included via the do-FILE
mechanism, which is essentially just a variety of C<eval> with the
caveat that lexical variables in the invoking script will be invisible
-to the included code. Has semantics similar to the following subroutine:
+to the included code. If it were implemented in pure Perl, it
+would have semantics similar to the following:
+
+ use Carp 'croak';
+ use version;
sub require {
my ($filename) = @_;
+ if ( my $version = eval { version->parse($filename) } ) {
+ if ( $version > $^V ) {
+ my $vn = $version->normal;
+ croak "Perl $vn required--this is only $^V, stopped";
+ }
+ return 1;
+ }
if (exists $INC{$filename}) {
return 1 if $INC{$filename};
- die "Compilation failed in require";
+ croak "Compilation failed in require";
}
my ($realfilename,$result);
ITER: {
$realfilename = "$prefix/$filename";
if (-f $realfilename) {
$INC{$filename} = $realfilename;
- $result = do $realfilename;
+ my $caller = caller;
+ my $do_as_caller = eval qq{
+ package $caller;
+ sub { do \$_[0] }
+ };
+ $result = $do_as_caller->($realfilename);
last ITER;
}
}
- die "Can't find $filename in \@INC";
+ croak "Can't locate $filename in \@INC";
}
if ($@) {
$INC{$filename} = undef;
- die $@;
+ croak $@;
} elsif (!$result) {
delete $INC{$filename};
- die "$filename did not return true value";
+ croak "$filename did not return true value";
} else {
+ $! = 0;
return $result;
}
}
https://perl5.git.perl.org / perl5.git / blobdiff