sub tan { sin($_[0]) / cos($_[0]) }
-Note that atan2(0, 0) is not well-defined.
+The return value for C<atan2(0,0)> is implementation-defined; consult
+your atan2(3) manpage for more information.
=item bind SOCKET,NAME
X<bind>
If LAYER is present it is a single string, but may contain multiple
directives. The directives alter the behaviour of the file handle.
-When LAYER is present using binmode on text file makes sense.
+When LAYER is present using binmode on a text file makes sense.
If LAYER is omitted or specified as C<:raw> the filehandle is made
suitable for passing binary data. This includes turning off possible CRLF
determined.
If there is a syntax error or runtime error, or a C<die> statement is
-executed, an undefined value is returned by C<eval>, and C<$@> is set to the
+executed, C<eval> returns an undefined value in scalar context
+or an empty list in list context, and C<$@> is set to the
error message. If there was no error, C<$@> is guaranteed to be a null
string. Beware that using C<eval> neither silences perl from printing
warnings to STDERR, nor does it stuff the text of warning messages into C<$@>.
is implemented. It is also Perl's exception trapping mechanism, where
the die operator is used to raise exceptions.
+If you want to trap errors when loading an XS module, some problems with
+the binary interface (such as Perl version skew) may be fatal even with
+C<eval> unless C<$ENV{PERL_DL_NONLAZY}> is set. See L<perlrun>.
+
If the code to be executed doesn't vary, you may use the eval-BLOCK
form to trap run-time errors without incurring the penalty of
recompiling each time. The error, if any, is still returned in C<$@>.
particular situation, you can just use symbolic references instead, as
in case 6.
+The assignment to C<$@> occurs before restoration of localised variables,
+which means a temporary is required if you want to mask some but not all
+errors:
+
+ # alter $@ on nefarious repugnancy only
+ {
+ my $e;
+ {
+ local $@; # protect existing $@
+ eval { test_repugnancy() };
+ # $@ =~ /nefarious/ and die $@; # DOES NOT WORK
+ $@ =~ /nefarious/ and $e = $@;
+ }
+ die $e if defined $e
+ }
+
C<eval BLOCK> does I<not> count as a loop, so the loop control statements
C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
Given an expression that specifies a hash element or array element,
returns true if the specified element in the hash or array has ever
-been initialized, even if the corresponding value is undefined. The
-element is not autovivified if it doesn't exist.
+been initialized, even if the corresponding value is undefined.
print "Exists\n" if exists $hash{$key};
print "Defined\n" if defined $hash{$key};
Here's a mailbox appender for BSD systems.
- use Fcntl ':flock'; # import LOCK_* constants
+ use Fcntl qw(:flock SEEK_END); # import LOCK_* and SEEK_END constants
sub lock {
- flock(MBOX,LOCK_EX);
- # and, in case someone appended
- # while we were waiting...
- seek(MBOX, 0, 2);
+ my ($fh) = @_;
+ flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n";
+
+ # and, in case someone appended while we were waiting...
+ seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n";
}
sub unlock {
- flock(MBOX,LOCK_UN);
+ my ($fh) = @_;
+ flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n";
}
- open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}")
+ open(my $mbox, ">>", "/usr/spool/mail/$ENV{'USER'}")
or die "Can't open mailbox: $!";
- lock();
- print MBOX $msg,"\n\n";
- unlock();
+ lock($mbox);
+ print $mbox $msg,"\n\n";
+ unlock($mbox);
On systems that support a real flock(), locks are inherited across fork()
calls, whereas those that must resort to the more capricious fcntl()
EXPR is omitted, C<$_> is used. The C<< <*.c> >> operator is discussed in
more detail in L<perlop/"I/O Operators">.
+Note that C<glob> will split its arguments on whitespace, treating
+each segment as separate pattern. As such, C<glob('*.c *.h')> would
+match all files with a F<.c> or F<.h> extension. The expression
+C<glob('.* *')> would match all files in the current working directory.
+
Beginning with v5.6.0, this operator is implemented using the standard
-C<File::Glob> extension. See L<File::Glob> for details.
+C<File::Glob> extension. See L<File::Glob> for details, including
+C<bsd_glob> which does not treat whitespace as a pattern separator.
=item gmtime EXPR
X<gmtime> X<UTC> X<Greenwich>
=item length
Returns the length in I<characters> of the value of EXPR. If EXPR is
-omitted, returns length of C<$_>. Note that this cannot be used on
-an entire array or hash to find out how many elements these have.
-For that, use C<scalar @array> and C<scalar keys %hash> respectively.
+omitted, returns length of C<$_>. If EXPR is undefined, returns C<undef>.
+Note that this cannot be used on an entire array or hash to find out how
+many elements these have. For that, use C<scalar @array> and C<scalar keys
+%hash> respectively.
Note the I<characters>: if the EXPR is in Unicode, you will get the
number of characters, not the number of bytes. To get the length
C<$isdst> is true if the specified time occurs during Daylight Saving
Time, false otherwise.
-If EXPR is omitted, C<localtime()> uses the current time (C<localtime(time)>).
+If EXPR is omitted, C<localtime()> uses the current time (as returned
+by time(3)).
In scalar context, C<localtime()> returns the ctime(3) value:
=item m//
-The match operator. See L<perlop>.
+The match operator. See L<perlop/"Regexp Quote-Like Operators">.
=item map BLOCK LIST
X<map>
Opens the file whose filename is given by EXPR, and associates it with
FILEHANDLE.
+Simple examples to open a file for reading:
+
+ open(my $fh, '<', "input.txt") or die $!;
+
+and for writing:
+
+ open(my $fh, '>', "output.txt") or die $!;
+
(The following is a comprehensive reference to open(): for a gentler
introduction you may consider L<perlopentut>.)
that affect how the input and output are processed (see L<open> and
L<PerlIO> for more details). For example
- open(FH, "<:encoding(UTF-8)", "file")
+ open(my $fh, "<:encoding(UTF-8)", "file")
will open the UTF-8 encoded file containing Unicode characters,
see L<perluniintro>. Note that if layers are specified in the
As a special case the 3-arg form with a read/write mode and the third
argument being C<undef>:
- open(TMP, "+>", undef) or die ...
+ open(my $tmp, "+>", undef) or die ...
opens a filehandle to an anonymous temporary file. Also using "+<"
works for symmetry, but you really should consider writing something
open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)
# if the open fails, output is discarded
- open(DBASE, '+<', 'dbase.mine') # open for update
+ open(my $dbase, '+<', 'dbase.mine') # open for update
or die "Can't open 'dbase.mine' for update: $!";
- open(DBASE, '+<dbase.mine') # ditto
+ open(my $dbase, '+<dbase.mine') # ditto
or die "Can't open 'dbase.mine' for update: $!";
open(ARTICLE, '-|', "caesar <$article") # decrypt article
#...
sub read_myfile_munged {
my $ALL = shift;
- my $handle = new IO::File;
+ my $handle = IO::File->new;
open($handle, "myfile") or die "myfile: $!";
$first = <$handle>
or return (); # Automatically closed here.
reference to a new anonymous dirhandle.
DIRHANDLEs have their own namespace separate from FILEHANDLEs.
+See example at C<readdir>.
+
=item ord EXPR
X<ord> X<encoding>
C<$::sail> is equivalent to C<$main::sail> (as well as to C<$main'sail>,
still seen in older code).
-If NAMESPACE is omitted, then there is no current package, and all
-identifiers must be fully qualified or lexicals. However, you are
-strongly advised not to make use of this feature. Its use can cause
-unexpected behaviour, even crashing some versions of Perl. It is
-deprecated, and will be removed from a future release.
-
See L<perlmod/"Packages"> for more information about packages, modules,
and classes. See L<perlsub> for other scoping issues.
=item qq/STRING/
-=item qr/STRING/
-
=item qx/STRING/
=item qw/STRING/
-Generalized quotes. See L<perlop/"Regexp Quote-Like Operators">.
+Generalized quotes. See L<perlop/"Quote-Like Operators">.
+
+=item qr/STRING/
+
+Regexp-like quote. See L<perlop/"Regexp Quote-Like Operators">.
=item quotemeta EXPR
X<quotemeta> X<metacharacter>
better prepend the directory in question. Otherwise, because we didn't
C<chdir> there, it would have been testing the wrong file.
- opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!";
- @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
- closedir DIR;
+ opendir(my $dh, $some_dir) || die "can't opendir $some_dir: $!";
+ @dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh);
+ closedir $dh;
=item readline EXPR
elements of LIST and returns a string value with all characters
in the opposite order.
- print reverse <>; # line tac, last line first
+ print join(", ", reverse "world", "Hello"); # Hello, world
- undef $/; # for efficiency of <>
- print scalar reverse <>; # character tac, last line tsrif
+ print scalar reverse "dlrow ,", "olleH"; # Hello, world
Used without arguments in scalar context, reverse() reverses C<$_>.
+ $_ = "dlrow ,olleH";
+ print reverse; # No output, list context
+ print scalar reverse; # Hello, world
+
This operator is also handy for inverting a hash, although there are some
caveats. If a value is duplicated in the original hash, only one of those
can be represented as a key in the inverted hash. Also, this has to
=item s///
-The substitution operator. See L<perlop>.
+The substitution operator. See L<perlop/"Regexp Quote-Like Operators">.
=item say FILEHANDLE LIST
X<say>
disables the file descriptor in any forked copies in other
processes.
+Returns C<1> for success. In the case of error, returns C<undef> if
+the first argument is not a valid filehandle, or returns C<0> and sets
+C<$!> for any other failure.
+
=item sin EXPR
X<sin> X<sine> X<asin> X<arcsine>
=item sleep
Causes the script to sleep for EXPR seconds, or forever if no EXPR.
+Returns the number of seconds actually slept.
+
May be interrupted if the process receives a signal such as C<SIGALRM>.
-Returns the number of seconds actually slept. You probably cannot
-mix C<alarm> and C<sleep> calls, because C<sleep> is often implemented
-using C<alarm>.
+
+ eval {
+ local $SIG{ALARM} = sub { die "Alarm!\n" };
+ sleep;
+ };
+ die $@ unless $@ eq "Alarm!\n";
+
+You probably cannot mix C<alarm> and C<sleep> calls, because C<sleep>
+is often implemented using C<alarm>.
On some older systems, it may sleep up to a full second less than what
you requested, depending on how it counts seconds. Most modern systems
matching a null string) will split the value of EXPR into separate
characters at each point it matches that way. For example:
- print join(':', split(/ */, 'hi there'));
+ print join(':', split(/ */, 'hi there')), "\n";
produces the output 'h:i:t:h:e:r:e'.
of C<//> to mean "the last successful pattern match". So, for C<split>,
the following:
- print join(':', split(//, 'hi there'));
+ print join(':', split(//, 'hi there')), "\n";
produces the output 'h:i: :t:h:e:r:e'.
when LIMIT is given and is not 0), regardless of the length of the match.
For example:
- print join(':', split(//, 'hi there!', -1));
- print join(':', split(/\W/, 'hi there!', -1));
+ print join(':', split(//, 'hi there!', -1)), "\n";
+ print join(':', split(/\W/, 'hi there!', -1)), "\n";
produce the output 'h:i: :t:h:e:r:e:!:' and 'hi:there:', respectively,
both with an empty trailing field.
If you had the entire header of a normal Unix email message in $header,
you could split it up into fields and their values this way:
- $header =~ s/\n\s+/ /g; # fix continuation lines
+ $header =~ s/\n(?=\s)//g; # fix continuation lines
%hdrs = (UNIX_FROM => split /^(\S*?):\s*/m, $header);
The pattern C</PATTERN/> may be replaced with an expression to specify
one or more of:
- space prefix positive number with a space
- + prefix positive number with a plus sign
+ space prefix non-negative number with a space
+ + prefix non-negative number with a plus sign
- left-justify within the field
0 use zeros, not spaces, to right-justify
# ensure the leading "0" for any octal,
=item tr///
-The transliteration operator. Same as C<y///>. See L<perlop>.
+The transliteration operator. Same as C<y///>. See
+L<perlop/"Quote and Quote-like Operators">.
=item truncate FILEHANDLE,LENGTH
X<truncate>
Specifying VERSION as a literal of the form v5.6.1 should generally be
avoided, because it leads to misleading error messages under earlier
-versions of Perl that do not support this syntax. The equivalent numeric
-version should be used instead.
-
-Alternatively, you can use a numeric version C<use 5.006> followed by a
-v-string version like C<use v5.10.1>, to avoid the unintuitive C<use
-5.010_001>. (older perl versions fail gracefully at the first C<use>,
-later perl versions understand the v-string syntax in the second).
+versions of Perl (that is, prior to 5.6.0) that do not support this
+syntax. The equivalent numeric version should be used instead.
use v5.6.1; # compile time version check
use 5.6.1; # ditto
use 5.006_001; # ditto; preferred for backwards compatibility
- use 5.006; use 5.6.1; # ditto, for compatibility and readability
This is often useful if you need to check the current Perl version before
-C<use>ing library modules that have changed in incompatible ways from
-older versions of Perl. (We try not to do this more than we have to.)
+C<use>ing library modules that won't work with older versions of Perl.
+(We try not to do this more than we have to.)
Also, if the specified perl version is greater than or equal to 5.9.5,
C<use VERSION> will also load the C<feature> pragma and enable all
=item y///
-The transliteration operator. Same as C<tr///>. See L<perlop>.
+The transliteration operator. Same as C<tr///>. See
+L<perlop/"Quote and Quote-like Operators">.
=back
projects / p5sagit/p5-mst-13.2.git / blobdiff