home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam    

Book HomePerl in a NutshellSearch this book

5.2. Perl Functions in Alphabetical Order

delete

delete $hash{key}
delete @hash{@keys}
Deletes the specified key or keys and associated values from the specified hash. (It doesn't delete a file. See unlink for that.) Deleting from $ENV{} modifies the environment. Deleting from a hash that is bound to a (writable) DBM file deletes the entry from the DBM file.

For normal hashes, the delete function returns the value (not the key) that was deleted, but this behavior is not guaranteed for tied hashes, such as those bound to DBM files. To test whether a hash element has been deleted, use exists.

eval

eval string
eval {block}
Evaluates the expression or code in its argument at runtime as a separate Perl program within the context of the larger script. Any variable settings remain afterward, as do any subroutine or format definitions. The code of the eval is treated as a block, so any locally scoped variables declared within the eval last only until the eval is done. (See also local and my.) The value returned from an eval is the value of the last expression evaluated. Like subroutines, you may also use the return function to return a value and exit the eval.

With eval string, the contents of string are compiled and executed at runtime. For example:

$a = 3, $b = 4;
$c = '$a * $b';
print (eval "$c"); # Prints 12

The string form of eval is useful for executing strings produced at runtime from standard or other dynamic input sources. If the string produces an error, either from syntax or at runtime, the eval exits with the undefined value and places the error in $@. If string is omitted, the operator evaluates $_.

The block form of eval is used in Perl programs to handle runtime errors (exceptions). The code in block is compiled only once during the compilation of the main program. If there is a syntax error in the block, it will produce an error at compile time. If the code in block produces a runtime error (or if a die statement is encountered), the eval exits, and the error is placed in $@. For example, the following code can be used to trap a divide-by-zero error at runtime:

eval {
      $a = 10; $b = 0;
      $c = $a / $b;     # Causes runtime error
                        # Trapped by eval
     };
print $@;               # Prints "Illegal division by 0 at
                        # try.pl line 3"

As with any code in a block, a final semicolon is not required.

open

open filehandle, filename

open filehandle, mode, filename

open filehandle, mode, expr, list (new in 5.8)

open filehandle, mode, reference (new in 5.8)
Opens the file given by filename and associates it with filehandle. If filehandle is omitted, the scalar variable of the same name as the filehandle must contain the filename. (And you must also be careful to use or die after the statement rather than || die, because the precedence of || is higher than list operators such as open.)

If filename is preceded by either < or nothing, the file is opened for input (read-only). If filename is preceded by >, the file is opened for output. If the file doesn't exist, it will be created; if the file exists, it will be overwritten with output using >. Preceding the filename with >> opens an output file for appending. For both read and write access, use a + before < or >.

If you choose to use the three-or-more-arguments form of open, you can use separate mode and filename arguments, such as open($fh, $mode, $filename), in which $moderepresents an open mode or pipe. For example:

my $mode = '+<';
my $filename = 'whatever.txt';
open(FH, $mode, $filename)
    or die("can't open $filename: $!");

As covered in Chapter 4, "The Perl Language", you can build Perl 5.8 and newer with PerlIO support, which offers additional features for your system's I/O (STDIO). This allows you to do neat things, such as specify utf-8 as your default encoding for all of your I/O, or set your default line endings with 'crlf'. In addition, you can select piping to or extracting information from an external program with '|-' and '-|', respectively. For example:

my $prog = "webster overworked";
open($fh, '-|', $prog)
    or die("can't open pipe to '$prog': $!");

or, similarly:

my @prog_info = qw(/usr/contrib/bin/webster overworked);
open($fh, '-|', @prog_info)
    or die(...);

A filehandle may also be attached to a process by using a piped command. If the filename begins with |, the filename is interpreted as a command to which output is to be piped. If the filename ends with a |, the filename is interpreted as a command that pipes input to you. You may not have an open command that pipes both in and out.

Any pipe command containing shell metacharacters is passed to the shell for execution; otherwise, it is executed directly by Perl. The filename - refers to STDIN, and > refers to STDOUT. open returns nonzero upon success, the undefined value otherwise. If the open involved a pipe, the return value happens to be the process ID of the subprocess.

pack

pack template, list
Takes a list of values and packs it into a binary structure, returning the string containing the structure. templateis a sequence of characters that give the order and type of values, as follows:

Character

Meaning

@

Null-fill to absolute position.

(

Start of a ( ) group.

a

An ASCII string, will be null padded.

A

An ASCII string, will be space padded.

b

A bit string, low-to-high order (such as vec( )).

B

A bit string, high-to-low order.

c

A signed char value.

C

An unsigned char value.

d

A double-precision float in the native format.

D

A long double-precision float in the native format. Long doubles are avai able only if your system supports long double values and if Perl has been compiled to support these values. Causes a fatal error otherwise. New in 5.8.

f

A single-precision float in the native format.

F

A floating-point value in the native format, i.e., a Perl internal floating-point value (NV). New in 5.8.

h

A hexadecimal string, low nybble first.

H

A hexadecimal string, high nybble first.

i

A signed integer value.

I

An unsigned integer value.

l

A signed long value.

j

A signed integer value, i.e., a Perl internal integer (IV). New in 5.8.

J

An unsigned integer value, i.e., a Perl internal unsigned integer (UV). New in 5.8.

L

An unsigned long value.

n

A short in "network" (big-endian) order.

N

A long in "network" (big-endian) order.

p

A pointer to a string.

P

A pointer to a structure (fixed-length string).

q

A signed quad (64-bit) value. New in 5.8.

Q

An unsigned quad value. Quads are available only if your system supports 64-bit integer values and if Perl has been compiled to support these values. Causes a fatal error otherwise. New in 5.8.

s

A signed short value.

S

An unsigned short value.

v

A short in "VAX" (little-endian) order.

V

A long in "VAX" (little-endian) order.

u

A uuencoded string.

U

A Unicode character number. Encodes to UTF-8 internally (or UTF-EBCDIC in EBCDIC platforms). New in 5.8.

w

A BER compressed integer.

x

A null byte.

X

Back up a byte.

Z

A null terminated (ASCII) string. Will be null padded. New in 5.8.

Each character may optionally be followed by a number that gives a repeat count. Together the character and the repeat count make a field specifier. Field specifiers may be separated by whitespace, which will be ignored. With all types except a and A, the pack function will gobble up that many values from the list. Specifying * for the repeat count means to use however many items are left. The a and A types gobble just one value, but pack it as a string of length count, padding with nulls or spaces as necessary. (When unpacking, A strips trailing spaces and nulls, but a does not.) Real numbers (floats and doubles) are in the native machine format only; due to the multiplicity of floating formats, and the lack of a standard network representation, no facility for interchange has been made.

Generally, the same template may also be used in the unpack function. If you want to join variable length fields with a delimiter, use the join function.

printf

printf [filehandle] format, list
Prints a formatted string of the elements in list to filehandle or, if omitted, the currently selected output filehandle. This is similar to the C library's printf and fprintf functions, except that the * field width specifier is not supported. The function is exactly equivalent to:

print filehandle sprintf(format, list);

printf and sprintf use the same format syntax, but sprintf returns only a string; it doesn't print to a filehandle. The format string contains text with embedded field specifiers into which the elements of list are substituted in order, one per field. Field specifiers follow the form:

%m.nx

A percent sign begins each field, and x is the type of field. The optional m gives the minimum field width for appropriate field types (negative m left-justifies). The .n gives the precision for a specific field type, such as the number of digits after a decimal point for floating-point numbers, the maximum length for a string, and the minimum length for an integer.

Field specifiers (x) may be the following:

Code

Meaning

%

Percent sign

c

Character

d

Decimal integer

e

Exponential format floating-point number

E

Exponential format floating-point number with uppercase E

f

Fixed-point format floating-point number

g

Floating-point number, in either exponential or fixed decimal notation

G

Like g with uppercase E (if applicable)

ld

Long decimal integer

lo

Long octal integer

lu

Long unsigned decimal integer

lx

Long hexadecimal integer

o

Octal integer

s

String

u

Unsigned decimal integer

x

Hexadecimal integer

X

Hexadecimal integer with uppercase letters

p

The Perl value's address in hexadecimal

n

Special value that stores the number of characters output so far into the next variable in the parameter list

select

select rbits, wbits, ebits, timeout
The four-argument select operator is totally unrelated to the previously described select operator. This operator is for discovering which (if any) of your file descriptors are ready to do input or output, or to report an exceptional condition. It calls the select(2) system call with the bitmasks you've specified, which you can construct using fileno and vec, like this:

$rbits = $wbits = $ebits = "";
vec($rbits, fileno(STDIN), 1) = 1;
vec($wbits, fileno(STDOUT), 1) = 1;
$ein = $rin | $win;

The select call blocks until one or more file descriptors is ready for reading, writing, or reporting an error condition. timeout is given in seconds and tells select how long to wait.

sort

sort [code] list
Sorts a list and returns the sorted list value. By default (without a code argument), it sorts in standard string comparison order (undefined values sorting before defined null strings, which sort before everything else). code, if given, may be the name of a subroutine or a code block (anonymous subroutine) that defines its own comparison mechanism for sorting elements of list. The routine must return to the sort function an integer less than, equal to, or greater than 0, depending on how the elements of the list will be ordered. (The handy <=> and cmp operators can be used to perform three-way numeric and string comparisons.)

The normal calling code for subroutines is bypassed, with the following effects: the subroutine may not be a recursive subroutine, and the two elements to be compared are passed into the subroutine as $a and $b, not via @_. The variables $a and $b are passed by reference, so don't modify them in the subroutine.

Do not declare $a and $b as lexical variables (with my). They are package globals (though they're exempt from the usual restrictions on globals when you're using use strict). However, you do need to make sure your sort routine is in the same package, or else you must qualify $a and $b with the package name of the caller.

In versions preceding 5.005, Perl's sort is implemented in terms of C's qsort(3) function. Some qsort(3) versions will dump core if your sort subroutine provides inconsistent ordering of values. As of 5.005, however, this is no longer true.

use

use Module list
use version
use Module version list
If the first argument is a number, it is treated as a version number. If the version of Perl is less than version, an error message is printed and Perl exits. This provides a way to check the Perl version at compilation time instead of waiting for runtime.

If version appears between Module and list, then use calls the version method in class Module with version as an argument.

Otherwise, use imports some semantics into the current package from the named Module, generally by aliasing certain subroutine or variable names into your package. It is exactly equivalent to the following:

BEGIN { require Module; import Module list; }

The BEGIN forces the require and import to happen at compile time. The require makes sure that the module is loaded into memory if it hasn't been yet. The import is not a built-in function—it's just an ordinary static method call into the package named by Module that tells the module to import the list of features back into the current package. The module can implement its import method any way it likes, though most modules just choose to derive their import method via inheritance from the Exporter class defined in the Exporter module.

If you don't want your namespace altered, explicitly supply an empty list:

use Module ( );

This is exactly equivalent to the following:

BEGIN { require Module; }

Because this is a wide-open interface, pragmas (compiler directives) are also implemented this way. (See Chapter 8, "Standard Modules" for descriptions of the currently implemented pragmas.) These pseudomodules typically import semantics into the current block scope, unlike ordinary modules, which import symbols into the current package. (The latter are effective through the end of the file.)

There's a corresponding declaration, no, that "unimports" any meanings originally imported by use but have since become less important:

no integer;
no strict 'refs';
values

values %hash
Returns a list consisting of all the values of the named hash. The values are returned in an apparently random order, but it is the same order that the keys or each function would produce on the same hash. To sort the hash by its values, see the example under keys. Note that using values on a hash bound to a very large DBM file will produce a very large list, causing you to have a very large process, and leaving you in a bind. You might prefer to use the each function, which will iterate over the hash entries one by one without reading them all into a single list.

vec

vec string, offset, bits
Treats a string as a vector of unsigned integers and returns the value of the element specified by offset and bits. The function may also be assigned to, which causes the element to be modified. The purpose of the function is to provide compact storage of lists of small integers. The integers may be very small—vectors can hold numbers that are as small as one bit, resulting in a bitstring.

The offset specifies the number of elements to skip over to find the one you want. bits is the number of bits per element in the vector, so each element can contain an unsigned integer in the range 0..(2**bits)-1. bits must be one of 1, 2, 4, 8, 16, or 32. As many elements as possible are packed into each byte, and the ordering is such that vec($vectorstring,0,1) is guaranteed to go into the lowest bit of the first byte of the string. To find the position of the byte in which an element will be placed, you have to multiply the offset by the number of elements per byte. When bits is 1, there are eight elements per byte. When bits is 2, there are four elements per byte. When bits is 4, there are two elements (called nybbles) per byte. And so on.

Regardless of whether your system is big-endian or little-endian, vec($foo, 0, 8) always refers to the first byte of string $foo. See select for examples of bitmaps generated with vec.

Vectors created with vec can also be manipulated with the logical operators |, &, ^, and ~, which will assume a bit vector operation is desired when the operands are strings. A bit vector (bits == 1) can be translated to or from a string of 1s and 0s by supplying a b* template to unpack or pack. Similarly, a vector of nybbles (bits == 4) can be translated with an h* template.

write

write filehandle
Writes a formatted record (possibly multiline) to the specified filehandle, using the format associated with that filehandle (see Section 4.11, "Unicode"). By default, the format for a filehandle is the one having the same name as the filehandle.

If filehandle is unspecified, output goes to the current default output filehandle, which starts as STDOUT but may be changed by the select operator. If the filehandle is an expression, then the expression is evaluated to determine the actual filehandle at runtime.

Note that write is not the opposite of read. Use print for simple string output. If you want to bypass standard I/O, see syswrite.



Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.







??????????????@Mail.ru