perl -V:man.dir
If the directories were F</usr/local/man/man1> and F</usr/local/man/man3>,
-you would only need to add F</usr/local/man> to your MANPATH. If
+you would need to add only F</usr/local/man> to your MANPATH. If
they are different, you'll have to add both stems.
If that doesn't work for some reason, you can still use the
=item * Subroutine definitions may now be autoloaded
In fact, the AUTOLOAD mechanism also allows you to define any arbitrary
-semantics for undefined subroutine calls. It's not just for autoloading.
+semantics for undefined subroutine calls. It's not for just autoloading.
=item * Regular expression enhancements
Perl is at the mercy of your machine's definitions of various
operations such as type casting, atof() and sprintf(). The latter
-can even trigger a coredump when passed ludicrous input values.
+can even trigger a core dump when passed ludicrous input values.
If your stdio requires a seek or eof between reads and writes on a
particular stream, so does Perl. (This doesn't apply to sysread()
=item B<PerlIO_clearerr(f)>
-This corresponds to clearerr(), i.e. clears 'eof' and 'error'
+This corresponds to clearerr(), i.e., clears 'eof' and 'error'
flags for the "stream".
=item B<PerlIO_flush(f)>
=item B<PerlIO_tmpfile()>
-This corresponds to tmpfile(), i.e. returns an anonymous
+This corresponds to tmpfile(), i.e., returns an anonymous
PerlIO which will automatically be deleted when closed.
=back
=item B<PerlIO_setlinebuf(f)>
This corresponds to setlinebuf(). Use is deprecated pending
-further discussion. (Perl core I<only> uses it when "dumping"
+further discussion. (Perl core uses it I<only> when "dumping"
is has nothing to do with $| auto-flush.)
=back
In addition to user API above there is an "implementation" interface
which allows perl to get at internals of PerlIO.
The following calls correspond to the various FILE_xxx macros determined
-by Configure. This section is really only of interest to those
+by Configure. This section is really of interest to only those
concerned with detailed perl-core behaviour or implementing a
PerlIO mapping.
=item B<PerlIO_fast_gets(f)>
Implementation has all the interfaces required to
-allow perls fast code to handle <FILE> mechanism.
+allow perl's fast code to handle <FILE> mechanism.
PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
PerlIO_canset_cnt(f) && \
=item B<PerlIO_set_ptrcnt(f,p,c)>
Set pointer into buffer, and a count of bytes still in the
-buffer. Should only be used to set
+buffer. Should be used only to set
pointer to within range implied by previous calls
to C<PerlIO_get_ptr> and C<PerlIO_get_cnt>.
=item B<PerlIO_set_cnt(f,c)>
Obscure - set count of bytes in the buffer. Deprecated.
-Currently only used in doio.c to force count < -1 to -1.
+Currently used in only doio.c to force count < -1 to -1.
Perhaps should be PerlIO_set_empty or similar.
This call may actually do nothing if "count" is deduced from pointer
and a "limit".
=item 7
-IO syntax is certainly less noisy, but it is also prone to ambiguities which
+IO syntax is certainly less noisy, but it is also prone to ambiguities that
can cause difficult-to-find bugs. Allow people to use the sure-thing OO
syntax, even if you don't like it.
method. Let the method look in the object for a reference to the data. The
alternative is to force the method to go hunting for the data ("Is it in my
class, or in a subclass? Which subclass?"), and this can be inconvenient
-and will lead to hackery. It is better to just let the object tell the
+and will lead to hackery. It is better just to let the object tell the
method where that data is located.
package Bar;
=head1 DESCRIPTION
The purpose of this document is to show you how to call Perl subroutines
-directly from C, i.e. how to write I<callbacks>.
+directly from C, i.e., how to write I<callbacks>.
Apart from discussing the C interface provided by Perl for writing
callbacks the document uses a series of examples to show how the
The classic example of where callbacks are used is when writing an
event driven program like for an X windows application. In this case
you register functions to be called whenever specific events occur,
-e.g. a mouse button is pressed, the cursor moves into a window or a
+e.g., a mouse button is pressed, the cursor moves into a window or a
menu item is selected.
=back
The key function is I<perl_call_sv>. All the other functions are
fairly simple wrappers which make it easier to call Perl subroutines in
special cases. At the end of the day they will all call I<perl_call_sv>
-to actually invoke the Perl subroutine.
+to invoke the Perl subroutine.
All the I<perl_call_*> functions have a C<flags> parameter which is
used to pass a bit mask of options to Perl. This bit mask operates
The function, I<perl_call_pv>, is similar to I<perl_call_sv> except it
expects its first parameter to be a C char* which identifies the Perl
-subroutine you want to call, e.g. C<perl_call_pv("fred", 0)>. If the
+subroutine you want to call, e.g., C<perl_call_pv("fred", 0)>. If the
subroutine you want to call is in another package, just include the
-package name in the string, e.g. C<"pkg::fred">.
+package name in the string, e.g., C<"pkg::fred">.
=item B<perl_call_method>
context to the Perl subroutine by using either G_SCALAR or G_ARRAY.
If you do not set this flag then it is I<very> important that you make
-sure that any temporaries (i.e. parameters passed to the Perl
+sure that any temporaries (i.e., parameters passed to the Perl
subroutine and values returned from the subroutine) are disposed of
yourself. The section I<Returning a Scalar> gives details of how to
-explicitly dispose of these temporaries and the section I<Using Perl to
+dispose of these temporaries explicitly and the section I<Using Perl to
dispose of temporaries> discusses the specific circumstances where you
can ignore the problem and let Perl deal with it for you.
=head2 G_EVAL
It is possible for the Perl subroutine you are calling to terminate
-abnormally, e.g. by calling I<die> explicitly or by not actually
+abnormally, e.g., by calling I<die> explicitly or by not actually
existing. By default, when either of these of events occurs, the
process will terminate immediately. If though, you want to trap this
type of event, specify the G_EVAL flag. It will put an I<eval { }>
Perl provides many macros to assist in accessing the Perl stack.
Wherever possible, these macros should always be used when interfacing
-to Perl internals. Hopefully this should make the code less vulnerable
+to Perl internals. We hope this should make the code less vulnerable
to any changes made to Perl in the future.
Another point worth noting is that in the first series of examples I
=item 3.
We aren't interested in anything returned from I<PrintUID>, so
-G_DISCARD is specified. Even if I<PrintUID> was changed to actually
+G_DISCARD is specified. Even if I<PrintUID> was changed to
return some value(s), having specified G_DISCARD will mean that they
will be wiped by the time control returns from I<perl_call_pv>.
The exception to this rule is if you are calling a Perl subroutine
directly from an XSUB function. In this case it is not necessary to
-explicitly use the C<dSP> macro - it will be declared for you
+use the C<dSP> macro explicitly - it will be declared for you
automatically.
=item 3.
Any parameters to be pushed onto the stack should be bracketed by the
C<PUSHMARK> and C<PUTBACK> macros. The purpose of these two macros, in
-this context, is to automatically count the number of parameters you
-are pushing. Then whenever Perl is creating the C<@_> array for the
+this context, is to count the number of parameters you are
+pushing automatically. Then whenever Perl is creating the C<@_> array for the
subroutine, it knows how big to make it.
The C<PUSHMARK> macro tells Perl to make a mental note of the current
=item 4.
-The only flag specified this time is G_DISCARD. Since we are passing 2
+The only flag specified this time is G_DISCARD. Because we are passing 2
parameters to the Perl subroutine this time, we have not specified
G_NOARGS.
Now for an example of dealing with the items returned from a Perl
subroutine.
-Here is a Perl subroutine, I<Adder>, which takes 2 integer parameters
+Here is a Perl subroutine, I<Adder>, that takes 2 integer parameters
and simply returns their sum.
sub Adder
$a + $b ;
}
-Since we are now concerned with the return value from I<Adder>, the C
+Because we are now concerned with the return value from I<Adder>, the C
function required to call it is now a bit more complex.
static void
will be one. If someone modified I<Adder> to return a list and we
didn't check for that possibility and take appropriate action the Perl
stack would end up in an inconsistent state. That is something you
-I<really> don't want to ever happen.
+I<really> don't want to happen ever.
=item 5.
Note that the stack is popped using C<POPs> in the block where
C<SvTRUE(GvSV(errgv))> is true. This is necessary because whenever a
I<perl_call_*> function invoked with G_EVAL|G_SCALAR returns an error,
-the top of the stack holds the value I<undef>. Since we want the
+the top of the stack holds the value I<undef>. Because we want the
program to continue after detecting this error, it is essential that
the stack is tidied up by removing the I<undef>.
This example will fail to recognize that an error occurred inside the
C<eval {}>. Here's why: the call_Subtract code got executed while perl
-was cleaning up temporaries when exiting the eval block, and since
+was cleaning up temporaries when exiting the eval block, and because
call_Subtract is implemented with I<perl_call_pv> using the G_EVAL
flag, it promptly reset C<$@>. This results in the failure of the
outermost test for C<$@>, and thereby the failure of the error trap.
perl_call_pv(name, G_DISCARD|G_NOARGS) ;
That is fine as far as it goes. The thing is, the Perl subroutine
-can be specified only as a string. For Perl 4 this was adequate,
+can be specified as only a string. For Perl 4 this was adequate,
but Perl 5 allows references to subroutines and anonymous subroutines.
This is where I<perl_call_sv> is useful.
PUSHMARK(sp) ;
perl_call_sv(name, G_DISCARD|G_NOARGS) ;
-Since we are using an SV to call I<fred> the following can all be used
+Because we are using an SV to call I<fred> the following can all be used
CallSubSV("fred") ;
CallSubSV(\&fred) ;
You should note that if it is necessary to store the SV (C<name> in the
example above) which corresponds to the Perl subroutine so that it can
-be used later in the program, it not enough to just store a copy of the
+be used later in the program, it not enough just to store a copy of the
pointer to the SV. Say the code above had been like this
static SV * rememberSub ;
The variable C<$ref> may have referred to the subroutine C<fred>
whenever the call to C<SaveSub1> was made but by the time
-C<CallSavedSub1> gets called it now holds the number C<47>. Since we
+C<CallSavedSub1> gets called it now holds the number C<47>. Because we
saved only a pointer to the original SV in C<SaveSub1>, any changes to
C<$ref> will be tracked by the pointer C<rememberSub>. This means that
whenever C<CallSavedSub1> gets called, it will attempt to execute the
PUSHMARK(sp) ;
perl_call_sv(keepSub, G_DISCARD|G_NOARGS) ;
-In order to avoid creating a new SV every time C<SaveSub2> is called,
+To avoid creating a new SV every time C<SaveSub2> is called,
the function first checks to see if it has been called before. If not,
then space for a new SV is allocated and the reference to the Perl
subroutine, C<name> is copied to the variable C<keepSub> in one
}
}
-It just implements a very simple class to manage an array. Apart from
+It implements just a very simple class to manage an array. Apart from
the constructor, C<new>, it declares methods, one static and one
-virtual. The static method, C<PrintID>, simply prints out the class
+virtual. The static method, C<PrintID>, prints out simply the class
name and a version number. The virtual method, C<Display>, prints out a
single element of the array. Here is an all Perl example of using it.
=head2 Using Perl to dispose of temporaries
In the examples given to date, any temporaries created in the callback
-(i.e. parameters passed on the stack to the I<perl_call_*> function or
+(i.e., parameters passed on the stack to the I<perl_call_*> function or
values returned via the stack) have been freed by one of these methods
=over 5
So what is the big problem? Well, if you are expecting Perl to tidy up
those temporaries for you, you might be in for a long wait. For Perl
-to actually dispose of your temporaries, control must drop back to the
+to dispose of your temporaries, control must drop back to the
enclosing scope at some stage. In the event driven scenario that may
never happen. This means that as time goes on, your program will
create more and more temporaries, none of which will ever be freed. As
So here is the bottom line - if you are sure that control will revert
back to the enclosing Perl scope fairly quickly after the end of your
-callback, then it isn't absolutely necessary to explicitly dispose of
+callback, then it isn't absolutely necessary to dispose explicitly of
any temporaries you may have created. Mind you, if you are at all
uncertain about what to do, it doesn't do any harm to tidy up anyway.
The mapping between the C callback and the Perl equivalent is stored in
the global variable C<callback>.
-This will be adequate if you ever need to have only 1 callback
+This will be adequate if you ever need to have only one callback
registered at any time. An example could be an error handler like the
code sketched out above. Remember though, repeated calls to
C<register_fatal> will replace the previously registered callback
and containing letters, underscores, and digits. In some cases, it
may be a chain of identifiers, separated by C<::> (or by C<'>, but
that's deprecated); all but the last are interpreted as names of
-packages, in order to locate the namespace in which to look
+packages, to locate the namespace in which to look
up the final identifier (see L<perlmod/Packages> for details).
It's possible to substitute for a simple identifier an expression
which produces a reference to the value at runtime; this is
means that C<$foo[1]> is a part of @foo, not a part of $foo. This may
seem a bit weird, but that's okay, because it is weird.
-Since variable and array references always start with '$', '@', or '%',
+Because variable and array references always start with '$', '@', or '%',
the "reserved" words aren't in fact reserved with respect to variable
names. (They ARE reserved with respect to labels and filehandles,
however, which don't have an initial special character. You can't have
that returns a reference to an object of that type. For a description
of this, see L<perlref>.
-Names that start with a digit may only contain more digits. Names
+Names that start with a digit may contain only more digits. Names
which do not start with a letter, underscore, or digit are limited to
-one character, e.g. C<$%> or C<$$>. (Most of these one character names
+one character, e.g., C<$%> or C<$$>. (Most of these one character names
have a predefined significance to Perl. For instance, C<$$> is the
current process id.)
The length of an array is a scalar value. You may find the length of
array @days by evaluating C<$#days>, as in B<csh>. (Actually, it's not
-the length of the array, it's the subscript of the last element, since
+the length of the array, it's the subscript of the last element, because
there is (ordinarily) a 0th element.) Assigning to C<$#days> changes the
length of the array. Shortening an array by this method destroys
intervening values. Lengthening an array that was previously shortened
Version 5 of Perl changed the semantics of C<$[>: files that don't set
the value of C<$[> no longer need to worry about whether another
file changed its value. (In other words, use of C<$[> is deprecated.)
-So in general you can just assume that
+So in general you can assume that
scalar(@whatever) == $#whatever + 1;
true if and only if the hash contains any key/value pairs. (If there
are any key/value pairs, the value returned is a string consisting of
the number of used buckets and the number of allocated buckets, separated
-by a slash. This is pretty much only useful to find out whether Perl's
+by a slash. This is pretty much useful only to find out whether Perl's
(compiled in) hashing algorithm is performing poorly on your data set.
For example, you stick 10,000 things in a hash, but evaluating %HASH in
scalar context reveals "1/16", which means only one out of sixteen buckets
newline, tab, etc., as well as some more exotic forms. See
L<perlop/Quote and Quotelike Operators> for a list.
-You can also embed newlines directly in your strings, i.e. they can end
+You can also embed newlines directly in your strings, i.e., they can end
on a different line than they begin. This is nice, but if you forget
your trailing quote, the error will not be reported until Perl finds
another line containing the quote character, which may be much further
Note that a
single-quoted string must be separated from a preceding word by a
-space, since single quote is a valid (though deprecated) character in
+space, because single quote is a valid (though deprecated) character in
a variable name (see L<perlmod/Packages>).
Two special literals are __LINE__ and __FILE__, which represent the
current line number and filename at that point in your program. They
-may only be used as separate tokens; they will not be interpolated into
+may be used only as separate tokens; they will not be interpolated into
strings. In addition, the token __END__ may be used to indicate the
logical end of the script before the actual end of file. Any following
text is ignored, but may be read via the DATA filehandle. (The DATA
-filehandle may read data only from the main script, but not from any
+filehandle may read data from only the main script, but not from any
required file or evaluated string.) The two control characters ^D and
^Z are synonyms for __END__ (or __DATA__ in a module; see L<SelfLoader> for
details on __DATA__).
$time = (stat($file))[8];
# SYNTAX ERROR HERE.
- $time = stat($file)[8]; # OOPS, FORGOT PARENS
+ $time = stat($file)[8]; # OOPS, FORGOT PARENTHESES
# Find a hex digit.
$hexdigit = ('a','b','c','d','e','f')[$digit-10];
$x = (($foo,$bar) = f()); # set $x to f()'s return count
This is very handy when you want to do a list assignment in a Boolean
-context, since most list functions return a null list when finished,
+context, because most list functions return a null list when finished,
which when assigned produces a 0, which is interpreted as FALSE.
The final element may be an array or a hash:
If you invoke Perl with the B<-d> switch, your script runs under the
Perl source debugger. This works like an interactive Perl
environment, prompting for debugger commands that let you examine
-source code, set breakpoints, get stack backtraces, change the values of
+source code, set breakpoints, get stack back-traces, change the values of
variables, etc. This is so convenient that you often fire up
the debugger all by itself just to test out Perl constructs
interactively to see what they do. For example:
=item p expr
Same as C<print {$DB::OUT} expr> in the current package. In particular,
-since this is just Perl's own B<print> function, this means that nested
+because this is just Perl's own B<print> function, this means that nested
data structures and objects are not dumped, unlike with the C<x> command.
=item x expr
-Evals its expression in list context and dumps out the result
+Evaluates its expression in list context and dumps out the result
in a pretty-printed fashion. Nested data structures are printed out
recursively, unlike the C<print> function.
=item T
-Produce a stack backtrace. See below for details on its output.
+Produce a stack back-trace. See below for details on its output.
=item s [expr]
Set a breakpoint. If line is omitted, sets a breakpoint on the line
that is about to be executed. If a condition is specified, it's
evaluated each time the statement is reached and a breakpoint is taken
-only if the condition is true. Breakpoints may only be set on lines
+only if the condition is true. Breakpoints may be set on only lines
that begin an executable statement. Conditions don't use B<if>:
b 237 $x > 30
affects printing messages on entry and exit from subroutines. If
C<frame & 2> is false, messages are printed on entry only. (Printing
-on exit may be useful if interdispersed with other messages.)
+on exit may be useful if inter-dispersed with other messages.)
If C<frame & 4>, arguments to functions are printed as well as the
context and caller info.
=item E<lt> [ command ]
Set an action (Perl command) to happen before every debugger prompt.
-A multiline command may be entered by backslashing the newlines. If
+A multi-line command may be entered by backslashing the newlines. If
C<command> is missing, resets the list of actions.
=item E<lt>E<lt> command
Add an action (Perl command) to happen before every debugger prompt.
-A multiline command may be entered by backslashing the newlines.
+A multi-line command may be entered by backslashing the newlines.
=item E<gt> command
Set an action (Perl command) to happen after the prompt when you've
-just given a command to return to executing the script. A multiline
+just given a command to return to executing the script. A multi-line
command may be entered by backslashing the newlines. If C<command> is
missing, resets the list of actions.
=item E<gt>E<gt> command
Adds an action (Perl command) to happen after the prompt when you've
-just given a command to return to executing the script. A multiline
+just given a command to return to executing the script. A multi-line
command may be entered by backslashing the newlines.
=item { [ command ]
Set an action (debugger command) to happen before every debugger prompt.
-A multiline command may be entered by backslashing the newlines. If
+A multi-line command may be entered by backslashing the newlines. If
C<command> is missing, resets the list of actions.
=item {{ command
Add an action (debugger command) to happen before every debugger prompt.
-A multiline command may be entered by backslashing the newlines.
+A multi-line command may be entered by backslashing the newlines.
=item ! number
DB<<17>>
where that number is the command number, which you'd use to access with
-the built-in B<csh>-like history mechanism, e.g. C<!17> would repeat
+the built-in B<csh>-like history mechanism, e.g., C<!17> would repeat
command number 17. The number of angle brackets indicates the depth of
the debugger. You could get more than one set of brackets, for example, if
you'd already at a breakpoint and then printed out the result of a
Note that this business of escaping a newline is specific to interactive
commands typed into the debugger.
-Here's an example of what a stack backtrace might look like:
+Here's an example of what a stack back-trace might look like:
$ = main::infested called from file `Ambulation.pm' line 10
@ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
=item *
-When an exection of the application reaches a place that can have a
+When execution the application reaches a place that can have a
breakpoint, a call to C<DB::DB()> is performed if any one of
variables $DB::trace, $DB::single, $DB::signal is true. (Note that
these variables are not C<local>izable.) This feature is disabled when
=item *
-When an exection of the application reaches a subroutine call, a call
+When execution of the application reaches a subroutine call, a call
to C<&DB::sub>(I<args>) is performed instead, with C<$DB::sub> being
the name of the called subroutine. (Unless the subroutine is compiled
in the package C<DB>.)
that were not compiled by Perl, such as C or C++ extensions.
If you alter your @_ arguments in a subroutine (such as with B<shift>
-or B<pop>, the stack backtrace will not show the original values.
+or B<pop>, the stack back-trace will not show the original values.
Some subroutines are called without creating a call frame. This may
-confuse backtrace C<T> and output of C<fE<gt>=4>.
+confuse back-trace C<T> and output of C<fE<gt>=4>.
=item % may only be used in unpack
-(F) You can't pack a string by supplying a checksum, since the
+(F) You can't pack a string by supplying a checksum, because the
checksumming process loses information, and you can't go the other
way. See L<perlfunc/unpack>.
(W) You've run afoul of the rule that says that any list operator followed
by parentheses turns into a function, with all the list operators arguments
-found inside the parens. See L<perlop/Terms and List Operators (Leftward)>.
+found inside the parentheses. See L<perlop/Terms and List Operators (Leftward)>.
=item %s argument is not a HASH element
(W)(S) You said something that may not be interpreted the way
you thought. Normally it's pretty easy to disambiguate it by supplying
-a missing quote, operator, paren pair or declaration.
+a missing quote, operator, parenthesis pair or declaration.
=item Args must match #! line
except that there's this itty bitty problem called there isn't a
current block. Note that an "if" or "else" block doesn't count as a
"loopish" block. You can usually double the curlies to get the same
-effect though, since the inner curlies will be considered a block
+effect though, because the inner curlies will be considered a block
that loops once. See L<perlfunc/last>.
=item Can't "next" outside a block
(F) A "next" statement was executed to reiterate the current block, but
there isn't a current block. Note that an "if" or "else" block doesn't
count as a "loopish" block. You can usually double the curlies to get
-the same effect though, since the inner curlies will be considered a block
+the same effect though, because the inner curlies will be considered a block
that loops once. See L<perlfunc/last>.
=item Can't "redo" outside a block
(F) A "redo" statement was executed to restart the current block, but
there isn't a current block. Note that an "if" or "else" block doesn't
count as a "loopish" block. You can usually double the curlies to get
-the same effect though, since the inner curlies will be considered a block
+the same effect though, because the inner curlies will be considered a block
that loops once. See L<perlfunc/last>.
=item Can't bless non-reference value
(S) The creation of the new file failed for the indicated reason.
-=item Can't do inplace edit without backup
+=item Can't do in-place edit without backup
(F) You're on a system such as MSDOS that gets confused if you try reading
from a deleted (but still opened) file. You have to say B<-i>C<.bak>, or some
=item Can't find string terminator %s anywhere before EOF
(F) Perl strings can stretch over multiple lines. This message means that
-the closing delimiter was omitted. Since bracketed quotes count nesting
+the closing delimiter was omitted. Because bracketed quotes count nesting
levels, the following is missing its final parenthesis:
print q(The character '(' starts a side comment.)
it, instead of the filespec, to the access checking routine. It will try to
retrieve the filespec using the device name and FID present in the stat buffer,
but this works only if you haven't made a subsequent call to the CRTL stat()
-routine, since the device name is overwritten with each call. If this warning
+routine, because the device name is overwritten with each call. If this warning
appears, the name lookup failed, and the access checking routine gave up and
returned FALSE, just to be conservative. (Note: The access checking routine
knows about the Perl C<stat> operator and file tests, so you shouldn't ever
(F) The deeply magical "goto subroutine" call can only replace one subroutine
call for another. It can't manufacture one out of whole cloth. In general
-you should only be calling it out of an AUTOLOAD routine anyway. See
+you should be calling it out of only an AUTOLOAD routine anyway. See
L<perlfunc/goto>.
=item Can't localize a reference
=item Can't modify %s in %s
(F) You aren't allowed to assign to the item indicated, or otherwise try to
-change it, such as with an autoincrement.
+change it, such as with an auto-increment.
=item Can't modify non-existent substring
(P) The internal routine that does assignment to a substr() was handed
a NULL.
-=item Can't msgrcv to readonly var
+=item Can't msgrcv to read-only var
-(F) The target of a msgrcv must be modifiable in order to be used as a receive
+(F) The target of a msgrcv must be modifiable to be used as a receive
buffer.
=item Can't open %s: %s
=item Can't take log of %g
-(F) Logarithms are only defined on positive real numbers.
+(F) Logarithms are defined on only positive real numbers.
=item Can't take sqrt of %g
(W) In an ordinary expression, backslash is a unary operator that creates
a reference to its argument. The use of backslash to indicate a backreference
-to a matched substring is only valid as part of a regular expression pattern.
+to a matched substring is valid only as part of a regular expression pattern.
Trying to do this in ordinary Perl code produces a value that prints
out looking like SCALAR(0xdecaf). Use the $1 form instead.
=item Can't use global %s in "my"
(F) You tried to declare a magical variable as a lexical variable. This is
-not allowed, because the magic can only be tied to one location (namely
+not allowed, because the magic can be tied to only one location (namely
the global variable) and it would be incredibly confusing to have
variables in your program that looked like magical variables but
weren't.
(F) The write routine failed for some reason while trying to process
a B<-e> switch. Maybe your /tmp partition is full, or clobbered.
-=item Can't x= to readonly value
+=item Can't x= to read-only value
(F) You tried to repeat a constant value (often the undefined value) with
an assignment operator, which implies modifying the value itself.
(W) You probably said %hash{$key} when you meant $hash{$key} or @hash{@keys}.
On the other hand, maybe you just meant %hash and got carried away.
-=item Do you need to predeclare %s?
+=item Do you need to pre-declare %s?
(S) This is an educated guess made in conjunction with the message "%s
found where operator expected". It often means a subroutine or module
=item Error converting file specification %s
-(F) An error peculiar to VMS. Since Perl may have to deal with file
+(F) An error peculiar to VMS. Because Perl may have to deal with file
specifications in either VMS or Unix syntax, it converts them to a
single form when it must operate on them directly. Either you've
passed an invalid file specification to Perl, or you've found a
You need to do an open() or a socket() call, or call a constructor from
the FileHandle package.
-=item Filehandle %s opened only for input
+=item Filehandle %s opened for only input
(W) You tried to write on a read-only filehandle. If you
intended it to be a read-write filehandle, you needed to open it with
"+E<lt>" or "+E<gt>" or "+E<gt>E<gt>" instead of with "E<lt>" or nothing. If
-you only intended to write the file, use "E<gt>" or "E<gt>E<gt>". See
+you intended only to write the file, use "E<gt>" or "E<gt>E<gt>". See
L<perlfunc/open>.
-=item Filehandle only opened for input
+=item Filehandle opened for only input
(W) You tried to write on a read-only filehandle. If you
intended it to be a read-write filehandle, you needed to open it with
"+E<lt>" or "+E<gt>" or "+E<gt>E<gt>" instead of with "E<lt>" or nothing. If
-you only intended to write the file, use "E<gt>" or "E<gt>E<gt>". See
+you intended only to write the file, use "E<gt>" or "E<gt>E<gt>". See
L<perlfunc/open>.
=item Final $ should be \$ or $name
(W) A warning peculiar to VMS. A logical name was encountered when preparing
to iterate over %ENV which violates the syntactic rules governing logical
-names. Since it cannot be translated normally, it is skipped, and will not
-appear in %ENV. This may be a benign occurence, as some software packages
+names. Because it cannot be translated normally, it is skipped, and will not
+appear in %ENV. This may be a benign occurrence, as some software packages
might directly modify logical name tables and introduce non-standard names,
or it may indicate that a logical name table has been corrupted.
=item Internal inconsistency in tracking vforks
(S) A warning peculiar to VMS. Perl keeps track of the number
-of times you've called C<fork> and C<exec>, in order to determine
+of times you've called C<fork> and C<exec>, to determine
whether the current call to C<exec> should affect the current
script or a subprocess (see L<perlvms/exec>). Somehow, this count
has become scrambled, so Perl is making a guess and treating
=item Modification of a read-only value attempted
(F) You tried, directly or indirectly, to change the value of a
-constant. You didn't, of course, try "2 = 1", since the compiler
+constant. You didn't, of course, try "2 = 1", because the compiler
catches that. But an easy way to do the same thing is:
sub mod { $_[0] = 1 }
=item nested *?+ in regexp
-(F) You can't quantify a quantifier without intervening parens. So
+(F) You can't quantify a quantifier without intervening parentheses. So
things like ** or +* or ?* are illegal.
Note, however, that the minimal matching quantifiers, *?, +? and ?? appear
=item No dbm on this machine
(P) This is counted as an internal error, because every machine should
-supply dbm nowadays, since Perl comes with SDBM. See L<SDBM_File>.
+supply dbm nowadays, because Perl comes with SDBM. See L<SDBM_File>.
=item No DBsub routine
=item Null filename used
-(F) You can't require the null filename, especially since on many machines
+(F) You can't require the null filename, especially because on many machines
that means the current directory! See L<perlfunc/require>.
=item Null picture in formline
=item NULL regexp argument
-(P) The internal pattern matching routines blew it bigtime.
+(P) The internal pattern matching routines blew it big time.
=item NULL regexp parameter
=item Odd number of elements in hash list
(S) You specified an odd number of elements to a hash list, which is odd,
-since hash lists come in key/value pairs.
+because hash lists come in key/value pairs.
=item Offset outside string
=item panic: leave_scope clearsv
-(P) A writable lexical variable became readonly somehow within the scope.
+(P) A writable lexical variable became read-only somehow within the scope.
=item panic: leave_scope inconsistency
(P) The lexer got into a bad state while processing a case modifier.
-=item Parens missing around "%s" list
+=item Pareneses missing around "%s" list
(W) You said something like
=item Possible attempt to put comments in qw() list
-(W) You probably wrote somthing like this:
+(W) You probably wrote something like this:
qw( a # a comment
b # another comment
=item Possible attempt to separate words with commas
-(W) You probably wrote somthing like this:
+(W) You probably wrote something like this:
qw( a, b, c );
because of the strict regularization of Perl 5's grammar into unary and
list operators. (The old open was a little of both.) You must put
-parens around the filehandle, or use the new "or" operator instead of "||".
+parentheses around the filehandle, or use the new "or" operator instead of "||".
=item print on closed filehandle %s
=item Prototype mismatch: (%s) vs (%s)
-(S) The subroutine being defined had a predeclared (forward) declaration
+(S) The subroutine being defined had a pre-declared (forward) declaration
with a different function prototype.
=item Read on closed filehandle E<lt>%sE<gt>
The difference is that C<$foo[&bar]> always behaves like a scalar, both when
assigning to it and when evaluating its argument, while C<@foo[&bar]> behaves
like a list when you assign to it, and provides a list context to its
-subscript, which can do weird things if you're only expecting one subscript.
+subscript, which can do weird things if you're expecting only one subscript.
On the other hand, if you were actually hoping to treat the array
-element as a list, you need to look into how references work, since
+element as a list, you need to look into how references work, because
Perl will not magically convert between scalars and lists for you. See
L<perlref>.
=item Sequence (?#... not terminated
(F) A regular expression comment must be terminated by a closing
-parenthesis. Embedded parens aren't allowed. See L<perlre>.
+parenthesis. Embedded parentheses aren't allowed. See L<perlre>.
=item Sequence (?%s...) not implemented
(P) The substitution was looping infinitely. (Obviously, a
substitution shouldn't iterate more times than there are characters of
input, which is what happened.) See the discussion of substitution in
-L<perlop/"Quote and Quotelike Operators">.
+L<perlop/"Quote and Quote-like Operators">.
=item Substitution pattern not terminated
error giving more information. (Sometimes it helps to turn on B<-w>.)
The error message itself often tells you where it was in the line when
it decided to give up. Sometimes the actual error is several tokens
-before this, since Perl is good at understanding random input.
+before this, because Perl is good at understanding random input.
Occasionally the line number may be misleading, and once in a blue moon
the only way to figure out what's triggering the error is to call
C<perl -c> repeatedly, chopping away half the program each time to see
=item That use of $[ is unsupported
(F) Assignment to C<$[> is now strictly circumscribed, and interpreted as
-a compiler directive. You may only say one of
+a compiler directive. You may say only one of
$[ = 0;
$[ = 1;
=item Too many args to syscall
-(F) Perl only supports a maximum of 14 args to syscall().
+(F) Perl supports a maximum of only 14 args to syscall().
=item Too many arguments for %s
=item umask: argument is missing initial 0
-(W) A umask of 222 is incorrect. It should be 0222, since octal literals
+(W) A umask of 222 is incorrect. It should be 0222, because octal literals
always start with 0 in Perl, as in C.
=item Unable to create sub named "%s"
=item Unknown BYTEORDER
-(F) There are no byteswapping functions for a machine with this byte order.
+(F) There are no byte-swapping functions for a machine with this byte order.
=item unmatched () in regexp
(F) Unbackslashed parentheses must always be balanced in regular
expressions. If you're a vi user, the % key is valuable for finding
-the matching paren. See L<perlre>.
+the matching parenthesis. See L<perlre>.
=item Unmatched right bracket
=item Use of $* is deprecated
-(D) This variable magically turned on multiline pattern matching, both for
+(D) This variable magically turned on multi-line pattern matching, both for
you and for any luckless subroutine that you happen to call. You should
use the new C<//m> and C<//s> modifiers now to do that without the dangerous
action-at-a-distance effects of C<$*>.
=item Use of %s in printf format not supported
-(F) You attempted to use a feature of printf that is accessible only
-from C. This usually means there's a better way to do it in Perl.
+(F) You attempted to use a feature of printf that is accessible from
+only C. This usually means there's a better way to do it in Perl.
=item Use of %s is deprecated
=item Warning: unable to close filehandle %s properly.
(S) The implicit close() done by an open() got an error indication on the
-close(). This usually indicates your filesystem ran out of disk space.
+close(). This usually indicates your file system ran out of disk space.
-=item Warning: Use of "%s" without parens is ambiguous
+=item Warning: Use of "%s" without parentheses is ambiguous
(S) You wrote a unary operator followed by something that looks like a
binary operator that could also have been interpreted as a term or
rand(+5);
-So put in parens to say what you really mean.
+So put in parentheses to say what you really mean.
=item Write on closed filehandle
=item YOU HAVEN'T DISABLED SET-ID SCRIPTS IN THE KERNEL YET!
-(F) And you probably never will, since you probably don't have the
+(F) And you probably never will, because you probably don't have the
sources to your kernel, and your vendor probably doesn't give a rip
about what you want. Your best bet is to use the wrapsuid script in
the eg directory to put a setuid C wrapper around your script.
=item \1 better written as $1
(W) Outside of patterns, backreferences live on as variables. The use
-of backslashes is grandfathered on the righthand side of a
+of backslashes is grandfathered on the right-hand side of a
substitution, but stylistically it's better to use the variable form
because other Perl programmers will expect it, and it works better
if there are more than 9 backreferences.
Alas, however simple this may appear, underneath it's a much more
elaborate construct than meets the eye!
-How do you print it out? Why can't you just say C<print @LoL>? How do
+How do you print it out? Why can't you say just C<print @LoL>? How do
you sort it? How can you pass it to a function or get one of these back
from a function? Is is an object? Can you save it to disk to read
back later? How do you access whole rows or columns of that matrix? Do
implementation, it's really more due to a lack of existing documentation with
examples designed for the beginner.
-This document is meant to be a detailed but understandable treatment of
-the many different sorts of data structures you might want to develop. It should
-also serve as a cookbook of examples. That way, when you need to create one of these
-complex data structures, you can just pinch, pilfer, or purloin
-a drop-in example from here.
+This document is meant to be a detailed but understandable treatment of the
+many different sorts of data structures you might want to develop. It
+should also serve as a cookbook of examples. That way, when you need to
+create one of these complex data structures, you can just pinch, pilfer, or
+purloin a drop-in example from here.
Let's look at each of these possible constructs in detail. There are separate
documents on each of the following:
The most important thing to understand about all data structures in Perl
-- including multidimensional arrays--is that even though they might
appear otherwise, Perl C<@ARRAY>s and C<%HASH>es are all internally
-one-dimensional. They can only hold scalar values (meaning a string,
+one-dimensional. They can hold only scalar values (meaning a string,
number, or a reference). They cannot directly contain other arrays or
hashes, but instead contain I<references> to other arrays or hashes.
-You can't use a reference to a array or hash in quite the same way that
-you would a real array or hash. For C or C++ programmers unused to distinguishing
-between arrays and pointers to the same, this can be confusing. If so,
-just think of it as the difference between a structure and a pointer to a
-structure.
+You can't use a reference to a array or hash in quite the same way that you
+would a real array or hash. For C or C++ programmers unused to
+distinguishing between arrays and pointers to the same, this can be
+confusing. If so, just think of it as the difference between a structure
+and a pointer to a structure.
You can (and should) read more about references in the perlref(1) man
page. Briefly, references are rather like pointers that know what they
$hash{string}[7] # hash of arrays
$hash{string}{'another string'} # hash of hashes
-Now, because the top level only contains references, if you try to print
+Now, because the top level contains only references, if you try to print
out your array in with a simple print() function, you'll get something
that doesn't look very nice, like this:
$LoL[$i] = \@list; # WRONG!
}
-So, just what's the big problem with that? It looks right, doesn't it?
+So, what's the big problem with that? It looks right, doesn't it?
After all, I just told you that you need an array of references, so by
golly, you've made me one!
they're disturbingly more apt to mean that it's "annoying",
"difficult", or both? :-)
-So just remember to always use the array or hash constructors with C<[]>
+So just remember always to use the array or hash constructors with C<[]>
or C<{}>, and you'll be fine, although it's not always optimally
efficient.
my $listref = [
[ "fred", "barney", "pebbles", "bambam", "dino", ],
[ "homer", "bart", "marge", "maggie", ],
- [ "george", "jane", "alroy", "judy", ],
+ [ "george", "jane", "elroy", "judy", ],
];
print $listref[2][2];
The compiler would immediately flag that as an error I<at compile time>,
because you were accidentally accessing C<@listref>, an undeclared
-variable, and it would thereby remind you to instead write:
+variable, and it would thereby remind you to write instead:
print $listref->[2][2]
2 ARRAY(0x13b540)
0 'george'
1 'jane'
- 2 'alroy'
+ 2 'elroy'
3 'judy'
There's also a lower-case B<x> command which is nearly the same.
# reading from file
# this is most easily done by having the file itself be
# in the raw data format as shown above. perl is happy
- # to parse complex datastructures if declared as data, so
+ # to parse complex data structures if declared as data, so
# sometimes it's easiest to do that
# here's a piece by piece build up
hashes) to a dbm file. The first problem is that all but GDBM and
Berkeley DB have size limitations, but beyond that, you also have problems
with how references are to be represented on disk. One experimental
-module that does attempt to partially address this need is the MLDBM
+module that does partially attempt to address this need is the MLDBM
module. Check your nearest CPAN site as described in L<perlmod> for
source code to MLDBM.
=item B<Use a UNIX program from Perl?>
-Read about backquotes and about C<system> and C<exec> in L<perlfunc>.
+Read about back-quotes and about C<system> and C<exec> in L<perlfunc>.
=item B<Use Perl from Perl?>
Note that we do not use the C<env> pointer here or in any of the
following examples.
-Normally handed to C<perl_parse> as it's final argument,
+Normally handed to C<perl_parse> as its final argument,
we hand it a B<NULL> instead, in which case the current environment
is used.
char match(char *string, char *pattern);
-Given a string and a pattern (e.g. "m/clasp/" or "/\b\w*\b/", which in
+Given a string and a pattern (e.g., "m/clasp/" or "/\b\w*\b/", which in
your program might be represented as C<"/\\b\\w*\\b/">),
returns 1 if the string matches the pattern and 0 otherwise.
int substitute(char *string[], char *pattern);
-Given a pointer to a string and an "=~" operation (e.g. "s/bob/robert/g" or
+Given a pointer to a string and an "=~" operation (e.g., "s/bob/robert/g" or
"tr[A-Z][a-z]"), modifies the string according to the operation,
returning the number of substitutions made.
Once you've understood those, embedding Perl in C is easy.
-Since C has no built-in function for integer exponentiation, let's
+Because C has no built-in function for integer exponentiation, let's
make Perl's ** operator available to it (this is less useful than it
-sounds, since Perl implements ** with C's I<pow()> function). First
+sounds, because Perl implements ** with C's I<pow()> function). First
I'll create a stub exponentiation function in I<power.pl>:
sub expo {
part; leave that to the I<xsubpp> and extension authors. If your
extension is dynamically loaded, DynaLoader creates I<Module::bootstrap()>
for you on the fly. In fact, if you have a working DynaLoader then there
-is rarely any need to statically link in any other extensions.
+is rarely any need to link in any other extensions statically.
Once you have this code, slap it into the second argument of I<perl_parse()>:
=head1 MORAL
You can sometimes I<write faster code> in C, but
-you can always I<write code faster> in Perl. Since you can use
+you can always I<write code faster> in Perl. Because you can use
each from the other, combine them as you wish.
=head1 NOTES
-Since the values line may contain arbitrary expressions (for at fields,
+Because the values line may contain arbitrary expressions (for at fields,
not caret fields), you can farm out more sophisticated processing
to other functions, like sprintf() or one of your own. For example:
operator. A unary operator generally provides a scalar context to its
argument, while a list operator may provide either scalar and list
contexts for its arguments. If it does both, the scalar arguments will
-be first, and the list argument will follow. (Note that there can only
-ever be one list argument.) For instance, splice() has three scalar
+be first, and the list argument will follow. (Note that there can ever
+be only one list argument.) For instance, splice() has three scalar
arguments followed by a list.
In the syntax descriptions that follow, list operators that expect a
Any function in the list below may be used either with or without
parentheses around its arguments. (The syntax descriptions omit the
-parens.) If you use the parens, the simple (but occasionally
+parentheses.) If you use the parentheses, the simple (but occasionally
surprising) rule is this: It I<LOOKS> like a function, therefore it I<IS> a
function, and precedence doesn't matter. Otherwise it's a list
operator or unary operator, and precedence does matter. And whitespace
read, write or execute the file. Also note that, for the superuser,
C<-r>, C<-R>, C<-w> and C<-W> always return 1, and C<-x> and C<-X> return
1 if any execute bit is set in the mode. Scripts run by the superuser may
-thus need to do a stat() in order to determine the actual mode of the
+thus need to do a stat() to determine the actual mode of the
file, or temporarily set the uid to something else.
Example:
This function tells the referenced object (passed as REF) that it is now
an object in the CLASSNAME package--or the current package if no CLASSNAME
is specified, which is often the case. It returns the reference for
-convenience, since a bless() is often the last thing in a constructor.
+convenience, because a bless() is often the last thing in a constructor.
Always use the two-argument version if the function doing the blessing
might be inherited by a derived class. See L<perlobj> for more about the
blessing (and blessings) of objects.
Closes the file or pipe associated with the file handle, returning TRUE
only if stdio successfully flushes buffers and closes the system file
descriptor. You don't have to close FILEHANDLE if you are immediately
-going to do another open() on it, since open() will close it for you. (See
+going to do another open() on it, because open() will close it for you. (See
open().) However, an explicit close on an input file resets the line
counter ($.), while the implicit close done by open() does not. Also,
closing a pipe will wait for the process executing on the pipe to
print "ok\n";
}
-Of course, typing in your own password to whoever asks you
+Of course, typing in your own password to whomever asks you
for it is unwise.
=item dbmclose ASSOC_ARRAY
looks like one). DBNAME is the name of the database (without the F<.dir>
or F<.pag> extension if any). If the database does not exist, it is
created with protection specified by MODE (as modified by the umask()).
-If your system only supports the older DBM functions, you may perform only
+If your system supports only the older DBM functions, you may perform only
one dbmopen() in your program. In older versions of Perl, if your system
had neither DBM nor ndbm, calling dbmopen() produced a fatal error; it now
falls back to sdbm(3).
matched something that happened to be 0 characters long. This is all
very above-board and honest. When a function returns an undefined value,
it's an admission that it couldn't give you an honest answer. So
-you should only use defined() when you're questioning the integrity
+you should use defined() only when you're questioning the integrity
of what you're trying to do. At other times, a simple comparison to
0 or "" is what you want.
Outside of an eval(), prints the value of LIST to C<STDERR> and exits with
the current value of C<$!> (errno). If C<$!> is 0, exits with the value of
-C<($? E<gt>E<gt> 8)> (backtick `command` status). If C<($? E<gt>E<gt> 8)> is 0,
+C<($? E<gt>E<gt> 8)> (back-tick `command` status). If C<($? E<gt>E<gt> 8)> is 0,
exits with 255. Inside an eval(), the error message is stuffed into C<$@>,
and the eval() is terminated with the undefined value; this makes die()
the way to raise an exception.
current filename for error messages, and searches all the B<-I>
libraries if the file isn't in the current directory (see also the @INC
array in L<perlvar/Predefined Names>). It's the same, however, in that it does
-reparse the file every time you call it, so you probably don't want to
+re-parse the file every time you call it, so you probably don't want to
do this inside a loop.
Note that inclusion of library modules is better done with the
When called in a list context, returns a 2-element array consisting
of the key and value for the next element of an associative array,
so that you can iterate over it. When called in a scalar context,
-returns the key only for the next element in the associative array.
+returns the key for only the next element in the associative array.
Entries are returned in an apparently random order. When the array is
entirely read, a null array is returned in list context (which when
assigned produces a FALSE (0) value), and C<undef> is returned in a
An C<eof> without an argument uses the last file read as argument.
Empty parentheses () may be used to indicate
-the pseudofile formed of the files listed on the command line, i.e.
+the pseudo file formed of the files listed on the command line, i.e.,
C<eof()> is reasonable to use inside a while (E<lt>E<gt>) loop to detect the end
of only the last file. Use C<eof(ARGV)> or eof without the parentheses to
test I<EACH> file in a while (E<lt>E<gt>) loop. Examples:
string. If EXPR is omitted, evaluates $_. The final semicolon, if
any, may be omitted from the expression.
-Note that, since eval() traps otherwise-fatal errors, it is useful for
+Note that, because eval() traps otherwise-fatal errors, it is useful for
determining whether a particular feature (such as socket() or symlink())
is implemented. It is also Perl's exception trapping mechanism, where
the die operator is used to raise exceptions.
print "Defined\n" if defined $array{$key};
print "True\n" if $array{$key};
-A hash element can only be TRUE if it's defined, and defined if
+A hash element can be TRUE only if it's defined, and defined if
it exists, but the reverse doesn't necessarily hold true.
Note that the EXPR can be arbitrarily complicated as long as the final
fatal error if used on a machine that doesn't implement either flock(2) or
fcntl(2). The fcntl(2) system call will be automatically used if flock(2)
is missing from your system. This makes flock() the portable file locking
-strategy, although it will only lock entire files, not records. Note also
+strategy, although it will lock only entire files, not records. Note also
that some versions of flock() cannot lock things over the network; you
would need to use the more system-specific fcntl() for that.
You may therefore need to use multiple formlines to implement a single
record format, just like the format compiler.
-Be careful if you put double quotes around the picture, since an "C<@>"
+Be careful if you put double quotes around the picture, because an "C<@>"
character may be taken to mean the beginning of an array name.
formline() always returns TRUE. See L<perlform> for other examples.
system "stty -cbreak </dev/tty >/dev/tty 2>&1";
}
else {
- system "stty", 'icanon', 'eol', '^@'; # ascii null
+ system "stty", 'icanon', 'eol', '^@'; # ASCII null
}
print "\n";
=item gmtime EXPR
Converts a time as returned by the time function to a 9-element array
-with the time localized for the standard Greenwich timezone.
+with the time localized for the standard Greenwich time zone.
Typically used as follows:
@foo = grep {!/^#/} @bar; # weed out comments
-Note that, since $_ is a reference into the list value, it can be used
+Note that, because $_ is a reference into the list value, it can be used
to modify the elements of the array. While this is useful and
supported, it can cause bizarre results if the LIST is not a named
array.
A local modifies the listed variables to be local to the enclosing block,
subroutine, C<eval{}> or C<do>. If more than one value is listed, the
-list must be placed in parens. See L<perlsub/"Temporary Values via
+list must be placed in parentheses. See L<perlsub/"Temporary Values via
local()"> for details.
But you really probably want to be using my() instead, because local() isn't
=item localtime EXPR
Converts a time as returned by the time function to a 9-element array
-with the time analyzed for the local timezone. Typically used as
+with the time analyzed for the local time zone. Typically used as
follows:
($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
In a scalar context, prints out the ctime(3) value:
- $now_string = localtime; # e.g. "Thu Oct 13 04:54:34 1994"
+ $now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
Also see the F<timelocal.pl> library, and the strftime(3) function available
via the POSIX module.
A "my" declares the listed variables to be local (lexically) to the
enclosing block, subroutine, C<eval>, or C<do/require/use>'d file. If
-more than one value is listed, the list must be placed in parens. See
+more than one value is listed, the list must be placed in parentheses. See
L<perlsub/"Private Variables via my()"> for details.
=item next LABEL
open(FILEHANDLE, "<&=$fd")
-If you open a pipe on the command "-", i.e. either "|-" or "-|", then
+If you open a pipe on the command "-", i.e., either "|-" or "-|", then
there is an implicit fork done, and the return value of open is the pid
of the child within the parent process, and 0 within the child
process. (Use C<defined($pid)> to determine whether the open was successful.)
}
The filename that is passed to open will have leading and trailing
-whitespace deleted. In order to open a file with arbitrary weird
+whitespace deleted. To open a file with arbitrary weird
characters in it, it's necessary to protect any leading and trailing
whitespace thusly:
both use IEEE floating point arithmetic (as the endian-ness of the memory
representation is not part of the IEEE spec). Note that Perl uses doubles
internally for all numeric calculation, and converting from double into
-float and thence back to double again will lose precision (i.e.
+float and thence back to double again will lose precision (i.e.,
C<unpack("f", pack("f", $foo)>) will not in general equal $foo).
Examples:
of the package declaration is from the declaration itself through the end of
the enclosing block (the same scope as the local() operator). All further
unqualified dynamic identifiers will be in this namespace. A package
-statement only affects dynamic variables--including those you've used
+statement affects only dynamic variables--including those you've used
local() on--but I<not> lexical variables created with my(). Typically it
would be the first declaration in a file to be included by the C<require>
or C<use> operator. You can switch into a package in more than one place;
-it merely influences which symbol table is used by the compiler for the
+it influences merely which symbol table is used by the compiler for the
rest of that block. You can refer to variables and filehandles in other
packages by prefixing the identifier with the package name and a double
colon: C<$Package::Variable>. If the package name is null, the C<main>
the variable contains the name of or a reference to the filehandle, thus introducing one
level of indirection. (NOTE: If FILEHANDLE is a variable and the next
token is a term, it may be misinterpreted as an operator unless you
-interpose a + or put parens around the arguments.) If FILEHANDLE is
+interpose a + or put parentheses around the arguments.) If FILEHANDLE is
omitted, prints by default to standard output (or to the last selected
output channel--see L</select>). If LIST is also omitted, prints $_ to
STDOUT. To set the default output channel to something other than
evaluated in a list context. Also be careful not to follow the print
keyword with a left parenthesis unless you want the corresponding right
parenthesis to terminate the arguments to the print--interpose a + or
-put parens around all the arguments.
+put parentheses around all the arguments.
Note that if you're storing FILEHANDLES in an array or other expression,
you will have to use a block returning its value instead:
=item prototype FUNCTION
Returns the prototype of a function as a string (or C<undef> if the
-function has no prototype). FUNCTION is a reference to the the
+function has no prototype). FUNCTION is a reference to the
function whose prototype you want to retrieve.
=item push ARRAY,LIST
a scalar context or a null list in a list context.
If you're planning to filetest the return values out of a readdir(), you'd
-better prepend the directory in question. Otherwise, since we didn't
+better prepend the directory in question. Otherwise, because we didn't
chdir() there, it would have been testing the wrong file.
opendir(DIR, $some_dir) || die "can't opendir $some_dir: $!";
=item rename OLDNAME,NEWNAME
Changes the name of a file. Returns 1 for success, 0 otherwise. Will
-not work across filesystem boundaries.
+not work across file system boundaries.
=item require EXPR
expression is interpreted as a list of single characters (hyphens
allowed for ranges). All variables and arrays beginning with one of
those letters are reset to their pristine state. If the expression is
-omitted, one-match searches (?pattern?) are reset to match again. Only
-resets variables or searches in the current package. Always returns
+omitted, one-match searches (?pattern?) are reset to match again. Resets
+only variables or searches in the current package. Always returns
1. Examples:
reset 'X'; # reset all X variables
reset 'a-z'; # reset lower case variables
reset; # just reset ?? searches
-Resetting "A-Z" is not recommended since you'll wipe out your
-ARGV and ENV arrays. Only resets package variables--lexical variables
+Resetting "A-Z" is not recommended because you'll wipe out your
+ARGV and ENV arrays. Resets only package variables--lexical variables
are unaffected, but they clean themselves up on scope exit anyway,
so you'll probably want to use them instead. See L</my>.
seek() to reset things. First the simple trick listed above to clear the
filepointer. The seek() doesn't change the current position, but it
I<does> clear the end-of-file condition on the handle, so that the next
-C<E<lt>FILEE<gt>> makes Perl try again to read something. Hopefully.
+C<E<lt>FILEE<gt>> makes Perl try again to read something. We hope.
If that doesn't work (some stdios are particularly cantankerous), then
you may need something more like this:
=item select RBITS,WBITS,EBITS,TIMEOUT
-This calls the select(2) system call with the bitmasks specified, which
+This calls the select(2) system call with the bit masks specified, which
can be constructed using fileno() and vec(), along these lines:
$rin = $win = $ein = '';
Most systems do not both to return anything useful in $timeleft, so
calling select() in a scalar context just returns $nfound.
-Any of the bitmasks can also be undef. The timeout, if specified, is
+Any of the bit masks can also be undef. The timeout, if specified, is
in seconds, which may be fractional. Note: not all implementations are
capable of returning the $timeleft. If not, they always return
$timeleft equal to the supplied $timeout.
Sets the current process group for the specified PID, 0 for the current
process. Will produce a fatal error if used on a machine that doesn't
-implement setpgrp(2). If the arguments are ommitted, it defaults to
+implement setpgrp(2). If the arguments are omitted, it defaults to
0,0. Note that the POSIX version of setpgrp() does not accept any
arguments, so only setpgrp 0,0 is portable.
Causes the script to sleep for EXPR seconds, or forever if no EXPR.
May be interrupted by sending the process a SIGALRM. Returns the
number of seconds actually slept. You probably cannot mix alarm() and
-sleep() calls, since sleep() is often implemented using alarm().
+sleep() calls, because sleep() is often implemented using 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
@sortedclass = sort byage @class;
# this sorts the %age associative arrays by value
- # instead of key using an inline function
+ # instead of key using an in-line function
@eldest = sort { $age{$b} <=> $age{$a} } keys %age;
sub backwards { $b cmp $a; }
produces the output 'h:i:t:h:e:r:e'.
-The LIMIT parameter can be used to partially split a line
+The LIMIT parameter can be used to split a line partially
($login, $passwd, $remainder) = split(/:/, $_, 3);
=item srand EXPR
Sets the random number seed for the C<rand> operator. If EXPR is omitted,
-uses a semirandom value based on the current time and process ID, among
+uses a semi-random value based on the current time and process ID, among
other things. Of course, you'd need something much more random than that for
-cryptographic purposes, since it's easy to guess the current time.
+cryptographic purposes, because it's easy to guess the current time.
Checksumming the compressed output of rapidly changing operating system
status programs is the usual method. Examples are posted regularly to
the comp.security.unix newsgroup.
mode file mode (type and permissions)
nlink number of (hard) links to the file
uid numeric user ID of file's owner
- gid numer group ID of file's owner
+ gid numeric group ID of file's owner
rdev the device identifier (special files only)
size total size of file, in bytes
atime last access time since the epoch
mtime last modify time since the epoch
ctime inode change time (NOT creation type!) since the epoch
- blksize preferred blocksize for file system I/O
+ blksize preferred block size for file system I/O
blocks actual number of blocks allocated
(The epoch was at 00:00 January 1, 1970 GMT.)
print "$file is executable NFS file\n";
}
-(This only works on machines for which the device number is negative under NFS.)
+(This works on machines only for which the device number is negative under NFS.)
=item study SCALAR
This may or may not save time, depending on the nature and number of
patterns you are searching on, and on the distribution of character
frequencies in the string to be searched--you probably want to compare
-runtimes with and without it to see which runs faster. Those loops
+run times with and without it to see which runs faster. Those loops
which scan for many short constant strings (including the constant
parts of more complex patterns) will benefit most. You may have only
one study active at a time--if you study a different scalar the first
@ARGV = @files;
undef $/;
eval $search; # this screams
- $/ = "\n"; # put back to normal input delim
+ $/ = "\n"; # put back to normal input delimiter
foreach $file (sort keys(%seen)) {
print $file, "\n";
}
require 'syscall.ph'; # may need to run h2ph
syscall(&SYS_write, fileno(STDOUT), "hi there\n", 9);
-Note that Perl only supports passing of up to 14 arguments to your system call,
+Note that Perl supports passing of up to only 14 arguments to your system call,
which in practice should usually suffice.
=item sysopen FILEHANDLE,FILENAME,MODE
arguments. The return value is the exit status of the program as
returned by the wait() call. To get the actual exit value divide by
256. See also L</exec>. This is I<NOT> what you want to use to capture
-the output from a command, for that you should merely use backticks, as
+the output from a command, for that you should use merely back-ticks, as
described in L<perlop/"`STRING`">.
=item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
=item umask
Sets the umask for the process and returns the old one. If EXPR is
-omitted, merely returns current umask.
+omitted, returns merely the current umask.
=item undef EXPR
=item undef
-Undefines the value of EXPR, which must be an lvalue. Use only on a
+Undefines the value of EXPR, which must be an lvalue. Use on only a
scalar value, an entire array, or a subroutine name (using "&"). (Using undef()
will probably not do what you expect on most predefined variables or
DBM list values, so don't do that.) Always returns the undefined value. You can omit
Unpack does the reverse of pack: it takes a string representing a
structure and expands it out into a list value, returning the array
-value. (In a scalar context, it merely returns the first value
+value. (In a scalar context, it returns merely the first value
produced.) The TEMPLATE has the same format as in the pack function.
Here's a subroutine that does substring:
use strict qw(subs vars refs);
use subs qw(afunc blurfl);
-These pseudomodules import semantics into the current block scope, unlike
+These pseudo-modules import semantics into the current block scope, unlike
ordinary modules, which import symbols into the current package (which are
effective through the end of the file).
There's a corresponding "no" command that unimports meanings imported
-by use, i.e. it calls C<unimport Module LIST> instead of C<import>.
+by use, i.e., it calls C<unimport Module LIST> instead of C<import>.
no integer;
no strict 'refs';
=item vec EXPR,OFFSET,BITS
Treats the string in EXPR as a vector of unsigned integers, and
-returns the value of the bitfield specified by OFFSET. BITS specifies
+returns the value of the bit field specified by OFFSET. BITS specifies
the number of bits that are reserved for each entry in the bit
vector. This must be a power of two from 1 to 32. vec() may also be
-assigned to, in which case parens are needed to give the expression
+assigned to, in which case parentheses are needed to give the expression
the correct precedence as in
vec($image, $max_x * $x + $y, 8) = 3;
waitpid(-1,&WNOHANG);
then you can do a non-blocking wait for any process. Non-blocking wait
-is only available on machines supporting either the waitpid(2) or
+is available on machines supporting either the waitpid(2) or
wait4(2) system calls. However, waiting for a particular pid with
FLAGS of 0 is implemented everywhere. (Perl emulates the system call
by remembering the status values of processes that have exited but have
however, that Perl allows arbitrary strings of data that may both contain
NULs and not be terminated by a NUL.
-If you simply want to know if the scalar value is TRUE, you can use:
+If you want to know simply if the scalar value is TRUE, you can use:
SvTRUE(SV*)
=head2 What's Really Stored in an SV?
Recall that the usual method of determining the type of scalar you have is
-to use C<Sv*OK> macros. Since a scalar can be both a number and a string,
+to use C<Sv*OK> macros. Because a scalar can be both a number and a string,
usually these macros will always return TRUE and calling the C<Sv*V>
macros will do the appropriate conversion of string to integer/double or
integer/double to string.
These will tell you if you truly have an integer, double, or string pointer
stored in your SV. The "p" stands for private.
-In general, though, it's best to just use the C<Sv*V> macros.
+In general, though, it's best just to use the C<Sv*V> macros.
=head2 Working with AVs
-There are two ways to create and load an AV. The first method just creates
+There are two ways to create and load an AV. The first method creates just
an empty AV:
AV* newAV();
part of a store operation.
Remember that C<hv_store> and C<hv_fetch> return C<SV**>s and not just
-C<SV*>. In order to access the scalar value, you must first dereference
+C<SV*>. To access the scalar value, you must first dereference
the return value. However, you should check to make sure that the return
value is not NULL before dereferencing it.
SvROK(SV*)
-To actually discover what the reference refers to, you must use the following
+To discover what the reference actually refers to, you must use the following
macro and then check the value returned.
SvTYPE(SvRV(SV*))
"Identifier <varname> used only once: possible typo" warning.
0x04 Issues a "Had to create <varname> unexpectedly" warning if
the variable didn't actually exist. This is useful if
- you expected the variable to already exist and want to propagate
+ you expected the variable to exist already and want to propagate
this warning back to the user.
If the C<varname> argument does not contain a package specifier, it is
the RETVAL and OUTPUT directives. However, there are some cases where the
argument stack is not already long enough to handle all the return values.
An example is the POSIX tzname() call, which takes no arguments, but returns
-two, the local timezone's standard and summer time abbreviations.
+two, the local time zone's standard and summer time abbreviations.
To handle this situation, the PPCODE directive is used and the stack is
extended using the macro:
=item C<SAVEFREESV(SV *sv)>
-The refcount of C<sv> would be decremented at the end of
+The reference count of C<sv> would be decremented at the end of
I<pseudo-block>. This is similar to C<sv_2mortal>, which should (?) be
used instead.
a mortal SV, the third creates a mortal copy of an existing SV (possibly
destroying it in the process).
-The mortal routines are not just for SVs -- AVs and HVs can be made mortal
+The mortal routines are not for just SVs -- AVs and HVs can be made mortal
by passing their address (and casting them to C<SV*>) to the C<sv_2mortal> or
C<sv_mortalcopy> routines.
The current kinds of Magic Virtual Tables are:
- mg_type MGVTBL Type of magicalness
+ mg_type MGVTBL Type of magic
------- ------ -------------------
\0 vtbl_sv Regexp???
A vtbl_amagic Operator Overloading
=head1 Memory Allocation
It is strongly suggested that you use the version of malloc that is distributed
-with Perl. It keeps pools of various sizes of unallocated memory in order to
-more quickly satisfy allocation requests.
+with Perl. It keeps pools of various sizes of unallocated memory to
+satisfy allocation requests more quickly.
However, on some platforms, it may cause spurious malloc or free errors.
New(x, pointer, number, type);
Newc(x, pointer, number, type, cast);
Newz(x, pointer, number, type);
-These three macros are used to initially allocate memory. The first argument
+These three macros are used to allocate memory initially. The first argument
C<x> was a "magic cookie" that was used to keep track of who called the macro,
to help when debugging memory problems. However, the current code makes no
use of this feature (Larry has switched to using a run-time memory checker),
Creates a new AV and populates it with a list of SVs. The SVs are copied
into the array, so they may be freed after the call to av_make. The new AV
-will have a refcount of 1.
+will have a reference count of 1.
AV* av_make _((I32 size, SV** svp));
=item newAV
-Creates a new AV. The refcount is set to 1.
+Creates a new AV. The reference count is set to 1.
AV* newAV _((void));
=item newHV
-Creates a new HV. The refcount is set to 1.
+Creates a new HV. The reference count is set to 1.
HV* newHV _((void));
=item newRV
-Creates an RV wrapper for an SV. The refcount for the original SV is
+Creates an RV wrapper for an SV. The reference count for the original SV is
incremented.
SV* newRV _((SV* ref));
=item newSV
Creates a new SV. The C<len> parameter indicates the number of bytes of
-pre-allocated string space the SV should have. The refcount for the new SV
+pre-allocated string space the SV should have. The reference count for the new SV
is set to 1.
SV* newSV _((STRLEN len));
=item newSViv
-Creates a new SV and copies an integer into it. The refcount for the SV is
+Creates a new SV and copies an integer into it. The reference count for the SV is
set to 1.
SV* newSViv _((IV i));
=item newSVnv
-Creates a new SV and copies a double into it. The refcount for the SV is
+Creates a new SV and copies a double into it. The reference count for the SV is
set to 1.
SV* newSVnv _((NV i));
=item newSVpv
-Creates a new SV and copies a string into it. The refcount for the SV is
+Creates a new SV and copies a string into it. The reference count for the SV is
set to 1. If C<len> is zero then Perl will compute the length.
SV* newSVpv _((char* s, STRLEN len));
Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
it will be upgraded to one. If C<classname> is non-null then the new SV will
be blessed in the specified package. The new SV is returned and its
-refcount is 1.
+reference count is 1.
SV* newSVrv _((SV* rv, char* classname));
=item SPAGAIN
-Refetch the stack pointer. Used after a callback. See L<perlcall>.
+Re-fetch the stack pointer. Used after a callback. See L<perlcall>.
SPAGAIN;
=item sv_bless
Blesses an SV into a specified package. The SV must be an RV. The package
-must be designated by its stash (see C<gv_stashpv()>). The refcount of the
+must be designated by its stash (see C<gv_stashpv()>). The reference count of the
SV is unaffected.
SV* sv_bless _((SV* sv, HV* stash));
=item sv_dec
-Autodecrement of the value in the SV.
+Auto-decrement of the value in the SV.
void sv_dec _((SV* sv));
=item sv_dec
-Autodecrement of the value in the SV.
+Auto-decrement of the value in the SV.
void sv_dec _((SV* sv));
=item sv_inc
-Autoincrement of the value in the SV.
+Auto increment of the value in the SV.
void sv_inc _((SV* sv));
=item sv_newmortal
-Creates a new SV which is mortal. The refcount of the SV is set to 1.
+Creates a new SV which is mortal. The reference count of the SV is set to 1.
SV* sv_newmortal _((void));
=item SvREFCNT
-Returns the value of the object's refcount.
+Returns the value of the object's reference count.
int SvREFCNT (SV* sv);
=item SvREFCNT_dec
-Decrements the refcount of the given SV.
+Decrements the reference count of the given SV.
void SvREFCNT_dec (SV* sv)
=item SvREFCNT_inc
-Increments the refcount of the given SV.
+Increments the reference count of the given SV.
void SvREFCNT_inc (SV* sv)
argument will be upgraded to an RV. That RV will be modified to point to
the new SV. The C<classname> argument indicates the package for the
blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
-will be returned and will have a refcount of 1.
+will be returned and will have a reference count of 1.
SV* sv_setref_iv _((SV *rv, char *classname, IV iv));
argument will be upgraded to an RV. That RV will be modified to point to
the new SV. The C<classname> argument indicates the package for the
blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
-will be returned and will have a refcount of 1.
+will be returned and will have a reference count of 1.
SV* sv_setref_nv _((SV *rv, char *classname, double nv));
the new SV. If the C<pv> argument is NULL then C<sv_undef> will be placed
into the SV. The C<classname> argument indicates the package for the
blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
-will be returned and will have a refcount of 1.
+will be returned and will have a reference count of 1.
SV* sv_setref_pv _((SV *rv, char *classname, void* pv));
an RV. That RV will be modified to point to the new SV. The C<classname>
argument indicates the package for the blessing. Set C<classname> to
C<Nullch> to avoid the blessing. The new SV will be returned and will have
-a refcount of 1.
+a reference count of 1.
SV* sv_setref_pvn _((SV *rv, char *classname, char* pv, I32 n));
=item sv_unref
-Unsets the RV status of the SV, and decrements the refcount of whatever was
+Unsets the RV status of the SV, and decrements the reference count of whatever was
being referenced by the RV. This can almost be thought of as a reversal of
C<newSVrv>. See C<SvROK_off>.
Now you should be very careful that the outer bracket type
is a round one, that is, parentheses. That's because you're assigning to
-an @list, so you need parens. If you wanted there I<not> to be an @LoL,
+an @list, so you need parentheses. If you wanted there I<not> to be an @LoL,
but rather just a reference to it, you could do something more like this:
# assign a reference to list of list references
push @$ref_to_LoL, [ split ];
}
-Actually, if you were using strict, you'd not only have to declare $ref_to_LoL as
-you had to declare @LoL, but you'd I<also> having to initialize it to a
-reference to an empty list. (This was a bug in 5.001m that's been fixed
-for the 5.002 release.)
+Actually, if you were using strict, you'd have to declare not only
+$ref_to_LoL as you had to declare @LoL, but you'd I<also> having to
+initialize it to a reference to an empty list. (This was a bug in 5.001m
+that's been fixed for the 5.002 release.)
my $ref_to_LoL = [];
while (<>) {
}
Ok, now you can add new rows. What about adding new columns? If you're
-just dealing with matrices, it's often easiest to use simple assignment:
+dealing with just matrices, it's often easiest to use simple assignment:
for $x (1 .. 10) {
for $y (1 .. 10) {
there or not: it'll gladly create them for you, setting
intervening elements to C<undef> as need be.
-If you just wanted to append to a row, you'd have
+If you wanted just to append to a row, you'd have
to do something a bit funnier looking:
# add new columns to an existing row
push @{ $LoL[0] }, "wilma", "betty";
-Notice that I I<couldn't> just say:
+Notice that I I<couldn't> say just:
push $LoL[0], "wilma", "betty"; # WRONG!
=head1 Access and Printing
Now it's time to print your data structure out. How
-are you going to do that? Well, if you only want one
+are you going to do that? Well, if you want only one
of the elements, it's trivial:
print $LoL[0][0];
If you want to print the whole thing, though, you can't
-just say
+say
print @LoL; # WRONG
-because you'll just get references listed, and perl will never
+because you'll get just references listed, and perl will never
automatically dereference things for you. Instead, you have to
roll yourself a loop or two. This prints the whole structure,
using the shell-style for() construct to loop across the outer
}
}
-Hm... that's still a bit ugly. How about this:
+Hmm... that's still a bit ugly. How about this:
for $i ( 0 .. $#LoL ) {
$aref = $LoL[$i];
but as you might well imagine, this is pretty rough on the reader.
Ah, but what if you wanted a I<two-dimensional slice>, such as having
-$x run from 4..8 and $y run from 7 to 12? Hm... here's the simple way:
+$x run from 4..8 and $y run from 7 to 12? Hmm... here's the simple way:
@newLoL = ();
for ($startx = $x = 4; $x <= 8; $x++) {
given namespace. The scope of the package declaration is from the
declaration itself through the end of the enclosing block (the same scope
as the local() operator). All further unqualified dynamic identifiers
-will be in this namespace. A package statement only affects dynamic
+will be in this namespace. A package statement affects only dynamic
variables--including those you've used local() on--but I<not> lexical
variables created with my(). Typically it would be the first declaration
in a file to be included by the C<require> or C<use> operator. You can
-switch into a package in more than one place; it merely influences which
+switch into a package in more than one place; it influences merely which
symbol table is used by the compiler for the rest of that block. You can
refer to variables and filehandles in other packages by prefixing the
identifier with the package name and a double colon:
causes variables, subroutines and file handles accessible via the
identifier C<richard> to also be accessible via the identifier C<dick>. If
-you only want to alias a particular variable or subroutine, you can
+you want to alias only a particular variable or subroutine, you can
assign a reference instead:
*dick = \$richard;
return \%nhash;
}
-On return, the reference wil overwrite the hash slot in the
+On return, the reference will overwrite the hash slot in the
symbol table specified by the *some_hash typeglob. This
is a somewhat tricky way of passing around references cheaply
when you won't want to have to remember to dereference variables
Inside an C<END> subroutine C<$?> contains the value that the script is
going to pass to C<exit()>. You can modify C<$?> to change the exit
-value of the script. Beware of changing C<$?> by accident (eg, by
+value of the script. Beware of changing C<$?> by accident (e.g.,, by
running something via C<system>).
Note that when you use the B<-n> and B<-p> switches to Perl, C<BEGIN>
the module. It is the responsibility of the F<.pm> file to load (or
arrange to autoload) any additional functionality. The POSIX module
happens to do both dynamic loading and autoloading, but the user can
-just say C<use POSIX> to get it all.
+say just C<use POSIX> to get it all.
For more information on writing extension modules, see L<perlxs>
and L<perlguts>.
The module and its user have a contract, part of which is common law,
and part of which is "written". Part of the common law contract is
that a module doesn't pollute any namespace it wasn't asked to. The
-written contract for the module (AKA documentation) may make other
+written contract for the module (A.K.A. documentation) may make other
provisions. But then you know when you C<use RedefineTheWorld> that
you're redefining the world and willing to take the consequences.
=head1 THE PERL MODULE LIBRARY
-A number of modules are included the the Perl distribution. These are
+A number of modules are included the Perl distribution. These are
described below, and all end in F<.pm>. You may also discover files in
the library directory that end in either F<.pl> or F<.ph>. These are old
libraries supplied so that old programs that use them still run. The
=head2 Pragmatic Modules
They work somewhat like pragmas in that they tend to affect the compilation of
-your program, and thus will usually only work well when used within a
+your program, and thus will usually work well only when used within a
C<use>, or C<no>. Most of these are locally scoped, so an inner BLOCK
may countermand any of these by saying:
which lasts until the end of that BLOCK.
-Unlike the pragrmas that effect the C<$^H> hints variable, the C<use
+Unlike the pragmas that effect the C<$^H> hints variable, the C<use
vars> and C<use subs> declarations are not BLOCK-scoped. They allow
you to pre-declare a variables or subroutines within a particular
<I>file</I> rather than just a block. Such declarations are effective
=item subs
-predeclare sub names
+pre-declare sub names
=item vars
-predeclare global variable names
+pre-declare global variable names
=back
extension modules include the Socket, Fcntl, and POSIX modules.
Many popular C extension modules do not come bundled (at least, not
-completely) due to their size, volatility, or simply lack of time for
+completely) due to their sizes, volatility, or simply lack of time for
adequate testing and configuration across the multitude of platforms on
which Perl was beta-tested. You are encouraged to look for them in
archie(1L), the Perl FAQ or Meta-FAQ, the WWW page, and even with their
Use blessed references. Use the two argument form of bless to bless
into the class name given as the first parameter of the constructor,
-e.g.:
+e.g.,:
sub new {
my $class = shift;
$no_caps_here function scope my() or local() variables
Function and method names seem to work best as all lowercase.
-E.g., C<$obj-E<gt>as_string()>.
+e.g.,, C<$obj-E<gt>as_string()>.
You can use a leading underscore to indicate that a variable or
function should not be used outside the package that defined it.
Generally anything not exported is still accessible from outside the
module using the ModuleName::item_name (or C<$blessed_ref-E<gt>method>)
syntax. By convention you can use a leading underscore on names to
-informally indicate that they are 'internal' and not for public use.
+indicate informally that they are 'internal' and not for public use.
(It is actually possible to get private functions by saying:
C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
-directly as a method, since a method must have a name in the symbol
+directly as a method, because a method must have a name in the symbol
table.)
As a general rule, if the module is trying to be object oriented
possible. Avoid any risk of ambiguity. Always try to use two or
more whole words. Generally the name should reflect what is special
about what the module does rather than how it does it. Please use
-nested module names to informally group or categorise a module.
-A module should have a very good reason not to have a nested name.
+nested module names to group informally or categorize a module.
+There should be a very good reason for a module not to have a nested name.
Module names should begin with a capital letter.
Having 57 modules all called Sort will not make life easy for anyone
=item Adding a Copyright Notice.
-How you choose to licence your work is a personal decision.
+How you choose to license your work is a personal decision.
The general mechanism is to assert your Copyright and then make
a declaration of how others may copy/use/modify your work.
Artistic). Larry has good reasons for NOT just using the GNU GPL.
My personal recommendation, out of respect for Larry, Perl and the
-perl community at large is to simply state something like:
+perl community at large is to state something simply like:
Copyright (c) 1995 Your Name. All rights reserved.
This program is free software; you can redistribute it and/or
To be fully compatible with the Exporter and MakeMaker modules you
should store your module's version number in a non-my package
variable called $VERSION. This should be a valid floating point
-number with at least two digits after the decimal (ie hundredths,
+number with at least two digits after the decimal (i.e., hundredths,
e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
See Exporter.pm in Perl5.001m or later for details.
distribution.
If possible you should place the module into a major ftp archive and
-include details of it's location in your announcement.
+include details of its location in your announcement.
Some notes about ftp archives: Please use a long descriptive file
name which includes the version number. Most incoming directories
The C<{}> constructs a reference to an anonymous hash containing no
key/value pairs. The bless() takes that reference and tells the object
it references that it's now a Critter, and returns the reference.
-This is for convenience, since the referenced object itself knows that
+This is for convenience, because the referenced object itself knows that
it has been blessed, and its reference to it could have been returned
directly, like this:
Within the class package, the methods will typically deal with the
reference as an ordinary reference. Outside the class package,
the reference is generally treated as an opaque value that may
-only be accessed through the class's methods.
+be accessed only through the class's methods.
A constructor may re-bless a referenced object currently belonging to
another class, but then the new class is responsible for all cleanup
-later. The previous blessing is forgotten, as an object may only
-belong to one class at a time. (Although of course it's free to
+later. The previous blessing is forgotten, as an object may belong
+to only one class at a time. (Although of course it's free to
inherit methods from many classes.)
A clarification: Perl objects are blessed. References are not. Objects
know which package they belong to. References do not. The bless()
-function simply uses the reference in order to find the object. Consider
+function uses the reference to find the object. Consider
the following example:
$a = {};
=head2 A Class is Simply a Package
Unlike say C++, Perl doesn't provide any special syntax for class
-definitions. You just use a package as a class by putting method
+definitions. You use a package as a class by putting method
definitions into the class.
There is a special array within each package called @ISA which says
more details.) If that doesn't work, Perl finally gives up and
complains.
-Perl classes only do method inheritance. Data inheritance is left
+Perl classes do only method inheritance. Data inheritance is left
up to the class itself. By and large, this is not a problem in Perl,
because most classes model the attributes of their object using
an anonymous hash, which serves as its own little namespace to be
A class method expects a class name as the first argument. It
provides functionality for the class as a whole, not for any individual
object belonging to the class. Constructors are typically class
-methods. Many class methods simply ignore their first argument, since
+methods. Many class methods simply ignore their first argument, because
they already know what package they're in, and don't care what package
-they were invoked via. (These aren't necessarily the same, since
+they were invoked via. (These aren't necessarily the same, because
class methods follow the inheritance tree just like ordinary instance
methods.) Another typical use for class methods is to look up an
object by name:
operators: "If it looks like a function, it is a function". (Presuming
for the moment that you think two words in a row can look like a
function name. C++ programmers seem to think so with some regularity,
-especially when the first word is "new".) Thus, the parens of
+especially when the first word is "new".) Thus, the parentheses of
new Critter ('Barney', 1.5, 70)
$fred = MyCritter::find("Critter", "Fred");
MyCritter::display($fred, 'Height', 'Weight');
-Note however, that this does not do any inheritance. If you merely
-wish to specify that Perl should I<START> looking for a method in a
+Note however, that this does not do any inheritance. If you wish
+merely to specify that Perl should I<START> looking for a method in a
particular package, use an ordinary method call, but qualify the method
name with the package like this:
$fred->MyCritter::display('Height', 'Weight');
If you're trying to control where the method search begins I<and> you're
-executing in the class itself, then you may use the SUPER pseudoclass,
+executing in the class itself, then you may use the SUPER pseudo class,
which says to start looking in your base class's @ISA list without having
-to explicitly name it:
+to name it explicitly:
$self->SUPER::display('Height', 'Weight');
-Please note that the C<SUPER::> construct is I<only> meaningful within the
+Please note that the C<SUPER::> construct is meaningful I<only> within the
class.
Sometimes you want to call a method when you don't know the method name
and you can do any extra cleanup you need to do.
Perl doesn't do nested destruction for you. If your constructor
-reblessed a reference from one of your base classes, your DESTROY may
-need to call DESTROY for any base classes that need it. But this only
-applies to reblessed objects--an object reference that is merely
+re-blessed a reference from one of your base classes, your DESTROY may
+need to call DESTROY for any base classes that need it. But this applies
+to only re-blessed objects--an object reference that is merely
I<CONTAINED> in the current object will be freed and destroyed
automatically when the current object is freed.
=head2 Summary
-That's about all there is to it. Now you just need to go off and buy a
+That's about all there is to it. Now you need just to go off and buy a
book about object-oriented design methodology, and bang your forehead
with it for the next six months or so.
exits), then a rather costly but complete mark-and-sweep style of garbage
collection is performed, and everything allocated by that thread gets
destroyed. This is essential to support Perl as an embedded or a
-multithreadable language. For example, this program demonstrates Perl's
+multi-threadable language. For example, this program demonstrates Perl's
two-phased garbage collection:
#!/usr/bin/perl
Objects are always destructed, even when regular refs aren't and in fact
are destructed in a separate pass before ordinary refs just to try to
prevent object destructors from using refs that have been themselves
-destructed. Plain refs are only garbage collected if the destruct level
+destructed. Plain refs are only garbage-collected if the destruct level
is greater than 0. You can test the higher levels of global destruction
by setting the PERL_DESTRUCT_LEVEL environment variable, presuming
C<-DDEBUGGING> was enabled during perl build time.
=head2 Terms and List Operators (Leftward)
Any TERM is of highest precedence of Perl. These includes variables,
-quote and quotelike operators, any expression in parentheses,
+quote and quote-like operators, any expression in parentheses,
and any function whose arguments are parenthesized. Actually, there
aren't really functions in this sense, just list operators and unary
operators behaving as functions because you put parentheses around
the commas on the left are evaluated after. In other words, list
operators tend to gobble up all the arguments that follow them, and
then act like a simple TERM with regard to the preceding expression.
-Note that you have to be careful with parens:
+Note that you have to be careful with parentheses:
# These evaluate exit before doing the print:
print($foo, exit); # Obviously not what you want.
well as subroutine and method calls, and the anonymous
constructors C<[]> and C<{}>.
-See also L<Quote and Quotelike Operators> toward the end of this section,
+See also L<Quote and Quote-Like Operators> toward the end of this section,
as well as L<"I/O Operators">.
=head2 The Arrow Operator
(a blessed reference) or a class name (that is, a package name).
See L<perlobj>.
-=head2 Autoincrement and Autodecrement
+=head2 Auto-increment and Auto-decrement
"++" and "--" work as in C. That is, if placed before a variable, they
increment or decrement the variable before returning the value, and if
placed after, increment or decrement the variable after returning the value.
-The autoincrement operator has a little extra built-in magic to it. If
+The auto-increment operator has a little extra built-in magic to it. If
you increment a variable that is numeric, or that has ever been used in
a numeric context, you get a normal increment. If, however, the
-variable has only been used in string contexts since it was set, and
+variable has been used in only string contexts since it was set, and
has a value that is not null and matches the pattern
C</^[a-zA-Z]*[0-9]*$/>, the increment is done as a string, preserving each
character within its range, with carry:
print ++($foo = 'Az'); # prints 'Ba'
print ++($foo = 'zz'); # prints 'aaa'
-The autodecrement operator is not magical.
+The auto-decrement operator is not magical.
=head2 Exponentiation
=head2 Symbolic Unary Operators
-Unary "!" performs logical negation, i.e. "not". See also C<not> for a lower
+Unary "!" performs logical negation, i.e., "not". See also C<not> for a lower
precedence version of this.
Unary "-" performs arithmetic negation if the operand is numeric. If
is returned. One effect of these rules is that C<-bareword> is equivalent
to C<"-bareword">.
-Unary "~" performs bitwise negation, i.e. 1's complement.
+Unary "~" performs bitwise negation, i.e., 1's complement.
(See also L<Integer Arithmetic>.)
Unary "+" has no effect whatsoever, even on strings. It is useful
$_. The return value indicates the success of the operation. (If the
right argument is an expression rather than a search pattern,
substitution, or translation, it is interpreted as a search pattern at run
-time. This is less efficient than an explicit search, since the pattern
+time. This is less efficient than an explicit search, because the pattern
must be compiled every time the expression is evaluated--unless you've
used C</o>.)
Binary "x" is the repetition operator. In a scalar context, it
returns a string consisting of the left operand repeated the number of
times specified by the right operand. In a list context, if the left
-operand is a list in parens, it repeats the list.
+operand is a list in parentheses, it repeats the list.
print '-' x 80; # print row of dashes
@foo = @foo[$#foo-4 .. $#foo]; # slice last 5 items
The range operator (in a list context) makes use of the magical
-autoincrement algorithm if the operands are strings. You
+auto-increment algorithm if the operands are strings. You
can say
@alphabet = ('A' .. 'Z');
Binary "and" returns the logical conjunction of the two surrounding
expressions. It's equivalent to && except for the very low
-precedence. This means that it short-circuits: i.e. the right
+precedence. This means that it short-circuits: i.e., the right
expression is evaluated only if the left expression is true.
=head2 Logical or and Exclusive Or
Binary "or" returns the logical disjunction of the two surrounding
expressions. It's equivalent to || except for the very low
-precedence. This means that it short-circuits: i.e. the right
+precedence. This means that it short-circuits: i.e., the right
expression is evaluated only if the left expression is false.
Binary "xor" returns the exclusive-OR of the two surrounding expressions.
=back
-=head2 Quote and Quotelike Operators
+=head2 Quote and Quote-like Operators
While we usually think of quotes as literal values, in Perl they
function as operators, providing various kinds of interpolating and
interpolate a variable literally.
Apart from the above, there are no multiple levels of interpolation. In
-particular, contrary to the expectations of shell programmers, backquotes
+particular, contrary to the expectations of shell programmers, back-quotes
do I<NOT> interpolate within double quotes, nor do single quotes impede
evaluation of variables when used within double quotes.
-=head2 Regexp Quotelike Operators
+=head2 Regexp Quote-Like Operators
-Here are the quotelike operators that apply to pattern
+Here are the quote-like operators that apply to pattern
matching and related activities.
=over 8
This is just like the C</pattern/> search, except that it matches only
once between calls to the reset() operator. This is a useful
-optimization when you only want to see the first occurrence of
+optimization when you want to see only the first occurrence of
something in each file of a set of files, for instance. Only C<??>
patterns local to the current package are reset.
Options are:
- g Match globally, i.e. find all occurrences.
+ g Match globally, i.e., find all occurrences.
i Do case-insensitive pattern matching.
m Treat string as multiple lines.
- o Only compile pattern once.
+ o Compile pattern only once.
s Treat string as single line.
x Use extended regular expressions.
If used in a context that requires a list value, a pattern match returns a
list consisting of the subexpressions matched by the parentheses in the
-pattern, i.e. (C<$1>, $2, $3...). (Note that here $1 etc. are also set, and
+pattern, i.e., (C<$1>, $2, $3...). (Note that here $1 etc. are also set, and
that this differs from Perl 4's behavior.) If the match fails, a null
array is returned. If the match succeeds, but there were no parentheses,
a list value of (1) is returned.
This last example splits $foo into the first two words and the
remainder of the line, and assigns those three fields to $F1, $F2 and
-$Etc. The conditional is true if any variables were assigned, i.e. if
+$Etc. The conditional is true if any variables were assigned, i.e., if
the pattern matched.
The C</g> modifier specifies global pattern matching--that is, matching
If no string is specified via the C<=~> or C<!~> operator, the C<$_>
variable is searched and modified. (The string specified with C<=~> must
be a scalar variable, an array element, a hash element, or an assignment
-to one of those, i.e. an lvalue.)
+to one of those, i.e., an lvalue.)
If the delimiter chosen is single quote, no variable interpolation is
done on either the PATTERN or the REPLACEMENT. Otherwise, if the
PATTERN contains a $ that looks like a variable rather than an
end-of-string test, the variable will be interpolated into the pattern
-at run-time. If you only want the pattern compiled once the first time
+at run-time. If you want the pattern compiled only once the first time
the variable is interpolated, use the C</o> option. If the pattern
evaluates to a null string, the last successfully executed regular
expression is used instead. See L<perlre> for further explanation on these.
Options are:
e Evaluate the right side as an expression.
- g Replace globally, i.e. all occurrences.
+ g Replace globally, i.e., all occurrences.
i Do case-insensitive pattern matching.
m Treat string as multiple lines.
- o Only compile pattern once.
+ o Compile pattern only once.
s Treat string as single line.
x Use extended regular expressions.
Any non-alphanumeric, non-whitespace delimiter may replace the
slashes. If single quotes are used, no interpretation is done on the
replacement string (the C</e> modifier overrides this, however). Unlike
-Perl 4, Perl 5 treats backticks as normal delimiters; the replacement
+Perl 4, Perl 5 treats back-ticks as normal delimiters; the replacement
text is not evaluated as a command. If the
PATTERN is delimited by bracketing quotes, the REPLACEMENT has its own
-pair of quotes, which may or may not be bracketing quotes, e.g.
+pair of quotes, which may or may not be bracketing quotes, e.g.,
C<s(foo)(bar)> or C<sE<lt>fooE<gt>/bar/>. A C</e> will cause the
replacement portion to be interpreter as a full-fledged Perl expression
and eval()ed right then and there. It is, however, syntax checked at
s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields
Note the use of $ instead of \ in the last example. Unlike
-B<sed>, we only use the \E<lt>I<digit>E<gt> form in the left hand side.
+B<sed>, we use the \E<lt>I<digit>E<gt> form in only the left hand side.
Anywhere else it's $E<lt>I<digit>E<gt>.
-Occasionally, you can't just use a C</g> to get all the changes
+Occasionally, you can't use just a C</g> to get all the changes
to occur. Here are two common cases:
# put commas in the right places in an integer
the number of characters replaced or deleted. If no string is
specified via the =~ or !~ operator, the $_ string is translated. (The
string specified with =~ must be a scalar variable, an array element,
-or an assignment to one of those, i.e. an lvalue.) For B<sed> devotees,
+or an assignment to one of those, i.e., an lvalue.) For B<sed> devotees,
C<y> is provided as a synonym for C<tr>. If the SEARCHLIST is
delimited by bracketing quotes, the REPLACEMENTLIST has its own pair of
-quotes, which may or may not be bracketing quotes, e.g. C<tr[A-Z][a-z]>
+quotes, which may or may not be bracketing quotes, e.g., C<tr[A-Z][a-z]>
or C<tr(+-*/)/ABCD/>.
Options:
=head2 I/O Operators
There are several I/O operators you should know about.
-A string is enclosed by backticks (grave accents) first undergoes
+A string is enclosed by back-ticks (grave accents) first undergoes
variable substitution just like a double quoted string. It is then
interpreted as a command, and the output of that command is the value
of the pseudo-literal, like in a shell. In a scalar context, a single
data--newlines remain newlines. Unlike in any of the shells, single
quotes do not hide variable names in the command from interpretation.
To pass a $ through to the shell you need to hide it with a backslash.
-The generalized form of backticks is C<qx//>. (Because backticks
+The generalized form of back-ticks is C<qx//>. (Because back-ticks
always undergo shell expansion as well, see L<perlsec> for
security concerns.)
except that it isn't so cumbersome to say, and will actually work. It
really does shift array @ARGV and put the current filename into variable
-$ARGV. It also uses filehandle I<ARGV> internally--E<lt>E<gt> is just a synonym
-for E<lt>ARGVE<gt>, which is magical. (The pseudo code above doesn't work
-because it treats E<lt>ARGVE<gt> as non-magical.)
+$ARGV. It also uses filehandle I<ARGV> internally--E<lt>E<gt> is just a
+synonym for E<lt>ARGVE<gt>, which is magical. (The pseudo code above
+doesn't work because it treats E<lt>ARGVE<gt> as non-magical.)
You can modify @ARGV before the first E<lt>E<gt> as long as the array ends up
containing the list of filenames you really want. Line numbers (C<$.>)
haven't set @ARGV, will input from STDIN.
If the string inside the angle brackets is a reference to a scalar
-variable (e.g. E<lt>$fooE<gt>), then that variable contains the name of the
+variable (e.g., E<lt>$fooE<gt>), then that variable contains the name of the
filehandle to input from, or a reference to the same. For example:
$fh = \*STDIN;
chmod 0644, <*.c>;
Because globbing invokes a shell, it's often faster to call readdir() yourself
-and just do your own grep() on the filenames. Furthermore, due to its current
+and do your own grep() on the filenames. Furthermore, due to its current
implementation of using a shell, the glob() routine may get "Arg list too
long" errors (unless you've installed tcsh(1L) as F</bin/csh>).
-A glob only evaluates its (embedded) argument when it is starting a new
+A glob evaluates its (embedded) argument only when it is starting a new
list. All values must be read before it will start over. In a list
context this isn't important, because you automatically get them all
anyway. In a scalar context, however, the operator returns the next value
produce integral results. However, C<use integer> still has meaning
for them. By default, their results are interpreted as unsigned
integers. However, if C<use integer> is in effect, their results are
-interpeted as signed integers. For example, C<~0> usually evaluates
+interpreted as signed integers. For example, C<~0> usually evaluates
to a large integral value. However, C<use integer; ~0> is -1.
S<text> text contains non-breaking spaces
C<code> literal code
L<name> A link (cross reference) to name
- L<name> manpage
- L<name/ident> item in manpage
- L<name/"sec"> section in other manpage
- L<"sec"> section in this manpage
+ L<name> manual page
+ L<name/ident> item in manual page
+ L<name/"sec"> section in other manual page
+ L<"sec"> section in this manual page
(the quotes are optional)
L</"sec"> ditto
F<file> Used for filenames
visually, and so that I could run them through fmt easily to reformat
them (that's F7 in my version of B<vi>). I wanted the translator (and not
me) to worry about whether " or ' is a left quote or a right quote
-within filled text, and I wanted it to leave the quotes alone dammit in
+within filled text, and I wanted it to leave the quotes alone, dammit, in
verbatim mode, so I could slurp in a working program, shift it over 4
spaces, and have it print out, er, verbatim. And presumably in a
constant width font.
=head1 DESCRIPTION
This page describes the syntax of regular expressions in Perl. For a
-description of how to actually I<use> regular expressions in matching
+description of how to I<use> regular expressions in matching
operations, plus various examples of the same, see C<m//> and C<s///> in
L<perlop>.
=item m
Treat string as multiple lines. That is, change "^" and "$" from matching
-only at the very start or end of the string to the start or end of any
+at only the very start or end of the string to the start or end of any
line anywhere within the string,
=item s
the regular expression parser to ignore whitespace that is neither
backslashed nor within a character class. You can use this to break up
your regular expression into (slightly) more readable parts. The C<#>
-character is also treated as a metacharacter introducing a comment,
+character is also treated as a meta-character introducing a comment,
just as in ordinary Perl code. This also means that if you want real
whitespace or C<#> characters in the pattern that you'll have to either
escape them or encode them using octal or hex escapes. Taken together,
In particular the following metacharacters have their standard I<egrep>-ish
meanings:
- \ Quote the next metacharacter
+ \ Quote the next meta-character
^ Match the beginning of the line
. Match any character (except newline)
$ Match the end of the line (or before newline at the end)
() Grouping
[] Character class
-By default, the "^" character is guaranteed to match only at the
-beginning of the string, the "$" character only at the end (or before the
+By default, the "^" character is guaranteed to match at only the
+beginning of the string, the "$" character at only the end (or before the
newline at the end) and Perl does certain optimizations with the
assumption that the string contains only one line. Embedded newlines
will not be matched by "^" or "$". You may, however, wish to treat a
modifier to C<{1,}>, and the "?" modifier to C<{0,1}>. n and m are limited
to integral values less than 65536.
-By default, a quantified subpattern is "greedy", that is, it will match as
+By default, a quantified sub-pattern is "greedy", that is, it will match as
many times as possible without causing the rest of the pattern not to match.
The standard quantifiers are all "greedy", in that they match as many
occurrences as possible (given a particular starting location) without
{n,}? Match at least n times
{n,m}? Match at least n but not more than m times
-Since patterns are processed as double quoted strings, the following
+Because patterns are processed as double quoted strings, the following
also work:
\t tab (HT, TAB)
\b Match a word boundary
\B Match a non-(word boundary)
- \A Match only at beginning of string
- \Z Match only at end of string (or before newline at the end)
+ \A Match at only beginning of string
+ \Z Match at only end of string (or before newline at the end)
\G Match only where previous m//g left off
A word boundary (C<\b>) is defined as a spot between two characters that
WARNING below.) The scope of $E<lt>digitE<gt> (and C<$`>, C<$&>, and C<$'>)
extends to the end of the enclosing BLOCK or eval string, or to the next
successful pattern match, whichever comes first. If you want to use
-parentheses to delimit a subpattern (e.g. a set of alternatives) without
+parentheses to delimit a subpattern (e.g., a set of alternatives) without
saving it as a subpattern, follow the ( with a ?:.
You may have as many parentheses as you wish. If you have more
than 9 substrings, the variables $10, $11, ... refer to the
corresponding substring. Within the pattern, \10, \11, etc. refer back
-to substrings if there have been at least that many left parens before
+to substrings if there have been at least that many left parentheses before
the backreference. Otherwise (for backward compatibility) \10 is the
same as \010, a backspace, and \11 the same as \011, a tab. And so
on. (\1 through \9 are always backreferences.)
alphanumeric, such as C<\b>, C<\w>, C<\n>. Unlike some other regular expression
languages, there are no backslashed symbols that aren't alphanumeric.
So anything that looks like \\, \(, \), \E<lt>, \E<gt>, \{, or \} is always
-interpreted as a literal character, not a metacharacter. This makes it
+interpreted as a literal character, not a meta-character. This makes it
simple to quote a string that you want to use for a pattern but that
-you are afraid might contain metacharacters. Simply quote all the
+you are afraid might contain metacharacters. Quote simply all the
non-alphanumeric characters:
$pattern =~ s/(\W)/\\$1/g;
/$unquoted\Q$quoted\E$unquoted/
Perl 5 defines a consistent extension syntax for regular expressions.
-The syntax is a pair of parens with a question mark as the first thing
-within the parens (this was a syntax error in Perl 4). The character
+The syntax is a pair of parentheses with a question mark as the first thing
+within the parentheses (this was a syntax error in Perl 4). The character
after the question mark gives the function of the extension. Several
extensions are already supported:
One or more embedded pattern-match modifiers. This is particularly
useful for patterns that are specified in a table somewhere, some of
which want to be case sensitive, and some of which don't. The case
-insensitive ones merely need to include C<(?i)> at the front of the
+insensitive ones need to include merely C<(?i)> at the front of the
pattern. For example:
$pattern = "foobar";
regular expression is merely a set of assertions that gives a definition
of success. There may be 0, 1, or several different ways that the
definition might succeed against a particular string. And if there are
-multiple ways it might succeed, you need to understand backtracking in
-order to know which variety of success you will achieve.
+multiple ways it might succeed, you need to understand backtracking to know which variety of success you will achieve.
When using lookahead assertions and negations, this can all get even
-tricker. Imagine you'd like to find a sequence of nondigits not
+tricker. Imagine you'd like to find a sequence of non-digits not
followed by "123". You might try to write that as
$_ = "ABC123";
3: got AB
4: got ABC
-You might have expected test 3 to fail because it just seems to a more
+You might have expected test 3 to fail because it seems to a more
general purpose version of test 1. The important difference between
them is that test 3 contains a quantifier (C<\D*>) and so can use
backtracking, whereas test 1 will not. What's happening is
that you've asked "Is it true that at the start of $x, following 0 or more
-nondigits, you have something that's not 123?" If the pattern matcher had
+non-digits, you have something that's not 123?" If the pattern matcher had
let C<\D*> expand to "ABC", this would have caused the whole pattern to
fail.
The search engine will initially match C<\D*> with "ABC". Then it will
Well now,
the pattern really, I<really> wants to succeed, so it uses the
-standard regexp backoff-and-retry and lets C<\D*> expand to just "AB" this
+standard regexp back-off-and-retry and lets C<\D*> expand to just "AB" this
time. Now there's indeed something following "AB" that is not
"123". It's in fact "C123", which suffices.
In case you're not familiar with the "regular" Version 8 regexp
routines, here are the pattern-matching rules not described above.
-Any single character matches itself, unless it is a I<metacharacter>
+Any single character matches itself, unless it is a I<meta-character>
with a special meaning described here or above. You can cause
characters which normally function as metacharacters to be interpreted
-literally by prefixing them with a "\" (e.g. "\." matches a ".", not any
+literally by prefixing them with a "\" (e.g., "\." matches a ".", not any
character; "\\" matches a "\"). A series of characters matches that
series of characters in the target string, so the pattern C<blurfl>
would match "blurfl" in the target string.
range, so that C<a-z> represents all the characters between "a" and "z",
inclusive.
-Characters may be specified using a metacharacter syntax much like that
+Characters may be specified using a meta-character syntax much like that
used in C: "\n" matches a newline, "\t" a tab, "\r" a carriage return,
"\f" a form feed, etc. More generally, \I<nnn>, where I<nnn> is a string
of octal digits, matches the character whose ASCII value is I<nnn>.
Similarly, \xI<nn>, where I<nn> are hexadecimal digits, matches the
character whose ASCII value is I<nn>. The expression \cI<x> matches the
-ASCII character control-I<x>. Finally, the "." metacharacter matches any
+ASCII character control-I<x>. Finally, the "." meta-character matches any
character except "\n" (unless you use C</s>).
You can specify a series of alternatives for a pattern using "|" to
square brackets, so if you write C<[fee|fie|foe]> you're really only
matching C<[feio|]>.
-Within a pattern, you may designate subpatterns for later reference by
+Within a pattern, you may designate sub-patterns for later reference by
enclosing them in parentheses, and you may refer back to the I<n>th
-subpattern later in the pattern using the metacharacter \I<n>.
-Subpatterns are numbered based on the left to right order of their
+sub-pattern later in the pattern using the meta-character \I<n>.
+Sub-patterns are numbered based on the left to right order of their
opening parenthesis. Note that a backreference matches whatever
-actually matched the subpattern in the string being examined, not the
-rules for that subpattern. Therefore, C<(0|0x)\d*\s\1\d*> will
-match "0x1234 0x4321",but not "0x1234 01234", since subpattern 1
+actually matched the sub-pattern in the string being examined, not the
+rules for that sub-pattern. Therefore, C<(0|0x)\d*\s\1\d*> will
+match "0x1234 0x4321",but not "0x1234 01234", because sub-pattern 1
actually matched "0x", even though the rule C<0|0x> could
potentially match the leading 0 in the second number.
difficult to do when you wanted to refer to a variable rather than a
symbol table entry. Perl 5 not only makes it easier to use symbolic
references to variables, but lets you have "hard" references to any piece
-of data. Any scalar may hold a hard reference. Since arrays and hashes
+of data. Any scalar may hold a hard reference. Because arrays and hashes
contain scalars, you can now easily build arrays of arrays, arrays of
hashes, hashes of arrays, arrays of hashes of functions, and so on.
A symbolic reference contains the name of a variable, just as a
-symbolic link in the filesystem merely contains the name of a file.
+symbolic link in the filesystem contains merely the name of a file.
The C<*glob> notation is a kind of symbolic reference. Hard references
are more like hard links in the file system: merely another way
at getting at the same underlying object, irrespective of its name.
By using the backslash operator on a variable, subroutine, or value.
(This works much like the & (address-of) operator works in C.) Note
-that this typically creates I<ANOTHER> reference to a variable, since
+that this typically creates I<ANOTHER> reference to a variable, because
there's already a reference to the variable in the symbol table. But
the symbol table reference might go away, and you'll still have the
reference that the backslash returned. Here are some examples:
scope by the time the anonymous subroutine runs. That's what closure
is all about.
-This only applies to lexical variables, by the way. Dynamic variables
+This applies to only lexical variables, by the way. Dynamic variables
continue to work as they have always worked. Closure is not something
that most Perl programmers need trouble themselves about to begin with.
=item 6.
References of the appropriate type can spring into existence if you
-dereference them in a context that assumes they exist. Since we haven't
+dereference them in a context that assumes they exist. Because we haven't
talked about dereferencing yet, we can't show you any examples yet.
=item 7.
Because of being able to omit the curlies for the simple case of C<$$x>,
people often make the mistake of viewing the dereferencing symbols as
proper operators, and wonder about their precedence. If they were,
-though, you could use parens instead of braces. That's not the case.
+though, you could use parentheses instead of braces. That's not the case.
Consider the difference below; case 0 is a short-hand version of case 1,
I<NOT> case 2:
The bless() operator may be used to associate a reference with a package
functioning as an object class. See L<perlobj>.
-A typeglob may be dereferenced the same way a reference can, since
+A typeglob may be dereferenced the same way a reference can, because
the dereference syntax always indicates the kind of reference desired.
So C<${*foo}> and C<${\$foo}> both indicate the same scalar variable.
$array{ "aaa" }{ "bbb" }{ "ccc" }
-you can just write
+you can write just
$array{ aaa }{ bbb }{ ccc }
$array{ shift @_ }
The B<-w> switch will warn you if it interprets a reserved word as a string.
-But it will no longer warn you about using lowercase words, since the
+But it will no longer warn you about using lowercase words, because the
string is effectively quoted.
=head1 WARNING
=item 3.
-Passed in implicitly via standard input. This only works if there are
+Passed in implicitly via standard input. This works only if there are
no filename arguments--to pass arguments to a STDIN script you
must explicitly specify a "-" for the script name.
of the script using the __END__ token.)
As of Perl 5, the #! line is always examined for switches as the line is
-being parsed. Thus, if you're on a machine that only allows one argument
+being parsed. Thus, if you're on a machine that allows only one argument
with the #! line, or worse, doesn't even recognize the #! line, you still
can get consistent switch behavior regardless of how Perl was invoked,
even if B<-x> was used to find the beginning of the script.
find . -name '*.bak' -print0 | perl -n0e unlink
The special value 00 will cause Perl to slurp files in paragraph mode.
-The value 0777 will cause Perl to slurp files whole since there is no
+The value 0777 will cause Perl to slurp files whole because there is no
legal character with that value.
=item B<-a>
causes Perl to check the syntax of the script and then exit without
executing it. Actually, it I<will> execute C<BEGIN>, C<END>, and C<use> blocks,
-since these are considered as occurring outside the execution of
+because these are considered as occurring outside the execution of
your program.
=item B<-d>
=item B<-D>I<list>
sets debugging flags. To watch how it executes your script, use
-B<-D14>. (This only works if debugging is compiled into your
+B<-D14>. (This works only if debugging is compiled into your
Perl.) Another nice value is B<-D1024>, which lists your compiled
syntax tree. And B<-D512> displays compiled regular expressions. As an
-alternative specify a list of letters instead of numbers (e.g. B<-D14> is
+alternative specify a list of letters instead of numbers (e.g., B<-D14> is
equivalent to B<-Dtls>):
1 p Tokenizing and Parsing
=item B<-P>
causes your script to be run through the C preprocessor before
-compilation by Perl. (Since both comments and cpp directives begin
+compilation by Perl. (Because both comments and cpp directives begin
with the # character, you should avoid starting comments with any words
recognized by the C preprocessor such as "if", "else" or "define".)
lines and ignores them because the variable $running_under_some_shell
is never true. A better construct than C<$*> would be C<${1+"$@"}>, which
handles embedded spaces and such in the filenames, but doesn't work if
-the script is being interpreted by csh. In order to start up sh rather
+the script is being interpreted by csh. To start up sh rather
than csh, some systems may have to replace the #! line with a line
containing just a colon, which will be politely ignored by Perl. Other
systems can't control that, and need a totally devious construct that
prints warnings about variable names that are mentioned only once, and
scalar variables that are used before being set. Also warns about
redefined subroutines, and references to undefined filehandles or
-filehandles opened readonly that you are attempting to write on. Also
+filehandles opened read-only that you are attempting to write on. Also
warns you if you use values as a number that doesn't look like numbers, using
an array as though it were a scalar, if
your subroutines recurse more than 100 deep, and innumerable other things.
contains the string "perl". Any meaningful switches on that line will
be applied (but only one group of switches, as with normal #!
processing). If a directory name is specified, Perl will switch to
-that directory before running the script. The B<-x> switch only
-controls the the disposal of leading garbage. The script must be
+that directory before running the script. The B<-x> switch controls
+only the disposal of leading garbage. The script must be
terminated with C<__END__> if there is trailing garbage to be ignored (the
script can process any or all of the trailing garbage via the DATA
filehandle if desired).
mode>, when it detects its program running with differing real and effective
user or group IDs. The setuid bit in Unix permissions is mode 04000, the
setgid bit mode 02000; either or both may be set. You can also enable taint
-mode explicitly by using the the B<-T> command line flag. This flag is
+mode explicitly by using the B<-T> command line flag. This flag is
I<strongly> suggested for server programs and any program run on behalf of
someone else, such as a CGI script.
else outside your program--at least, not by accident. All command-line
arguments, environment variables, and file input are marked as "tainted".
Tainted data may not be used directly or indirectly in any command that
-invokes a subshell, nor in any command that modifies files, directories,
+invokes a sub-shell, nor in any command that modifies files, directories,
or processes. Any variable set within an expression that has previously
referenced a tainted value itself becomes tainted, even if it is logically
impossible for the tainted value to influence the variable. Because
approach is used that if any tainted value has been accessed within the
same expression, the whole expression is considered tainted.
-But testing for taintedness only gets you so far. Sometimes you just have
+But testing for taintedness gets you only so far. Sometimes you have just
to clear your data's taintedness. The only way to bypass the tainting
-mechanism is by referencing subpatterns from a regular expression match.
+mechanism is by referencing sub-patterns from a regular expression match.
Perl presumes that if you reference a substring using $1, $2, etc., that
you knew what you were doing when you wrote the pattern. That means using
a bit of thought--don't just blindly untaint anything, or you defeat the
die "Bad data in $data"; # log this somewhere
}
-This is fairly secure since C</\w+/> doesn't normally match shell
+This is fairly secure because C</\w+/> doesn't normally match shell
metacharacters, nor are dot, dash, or at going to mean something special
to the shell. Use of C</.+/> would have been insecure in theory because
it lets everything through, but Perl doesn't check for that. The lesson
Perl does not call the shell to expand wild cards when you pass B<system>
and B<exec> explicit parameter lists instead of strings with possible shell
wildcards in them. Unfortunately, the B<open>, B<glob>, and
-backtick functions provide no such alternate calling convention, so more
+back-tick functions provide no such alternate calling convention, so more
subterfuge will be required.
Perl provides a reasonably safe way to open a file or pipe from a setuid
originals or known safe values. Then the child process, which no longer
has any special permissions, does the B<open> or other system call.
Finally, the child passes the data it managed to access back to the
-parent. Since the file or pipe was opened in the child while running
+parent. Because the file or pipe was opened in the child while running
under less privilege than the parent, it's not apt to be tricked into
doing something it shouldn't.
-Here's a way to do backticks reasonably safely. Notice how the B<exec> is
+Here's a way to do back-ticks reasonably safely. Notice how the B<exec> is
not called with a string that the shell could expand. This is by far the
best way to call something that might be subjected to shell escapes: just
never call the shell at all. By the time we get to the B<exec>, tainting
=item *
-Space before the opening curly of a multiline BLOCK.
+Space before the opening curly of a multi-line BLOCK.
=item *
=item *
-No space between function name and its opening paren.
+No space between function name and its opening parenthesis.
=item *
=item *
-Space after last paren matching on current line.
+Space after last parenthesis matching on current line.
=item *
$verbose && print "Starting analysis\n";
-since the main point isn't whether the user typed B<-v> or not.
+because the main point isn't whether the user typed B<-v> or not.
Similarly, just because an operator lets you assume default arguments
doesn't mean that you have to make use of the defaults. The defaults
Even if you aren't in doubt, consider the mental welfare of the person
who has to maintain the code after you, and who will probably put
-parens in the wrong place.
+parentheses in the wrong place.
=item *
reserves lowercase module names for "pragma" modules like C<integer> and
C<strict>. Other modules should begin with a capital letter and use mixed
case, but probably without underscores due to limitations in primitive
-filesystems' representations of module names as files that must fit into a
+file systems' representations of module names as files that must fit into a
few sparse bites.
=item *
=item *
Use the new "and" and "or" operators to avoid having to parenthesize
-list operators so much, and to reduce the incidence of punctuational
+list operators so much, and to reduce the incidence of punctuation
operators like C<&&> and C<||>. Call your subroutines as if they were
-functions or list operators to avoid excessive ampersands and parens.
+functions or list operators to avoid excessive ampersands and parentheses.
=item *
To call subroutines:
- NAME(LIST); # & is optional with parens.
- NAME LIST; # Parens optional if predeclared/imported.
+ NAME(LIST); # & is optional with parentheses.
+ NAME LIST; # Parentheses optional if pre-declared/imported.
&NAME; # Passes current @_ to subroutine.
=head1 DESCRIPTION
}
This also has the effect of turning call-by-reference into call-by-value,
-since the assignment copies the values. Otherwise a function is free to
+because the assignment copies the values. Otherwise a function is free to
do in-place modifications of @_ and change its caller's values.
upcase_in($v1, $v2); # this changes $v1 and $v2
made @b an empty list. See L</"Pass by Reference"> for alternatives.
A subroutine may be called using the "&" prefix. The "&" is optional in
-Perl 5, and so are the parens if the subroutine has been predeclared.
+Perl 5, and so are the parentheses if the subroutine has been pre-declared.
(Note, however, that the "&" is I<NOT> optional when you're just naming
the subroutine, such as when it's used as an argument to defined() or
undef(). Nor is it optional when you want to do an indirect subroutine
enclosing block, conditional (C<if/unless/elsif/else>), loop
(C<for/foreach/while/until/continue>), subroutine, C<eval>, or
C<do/require/use>'d file. If more than one value is listed, the list
-must be placed in parens. All listed elements must be legal lvalues.
+must be placed in parentheses. All listed elements must be legal lvalues.
Only alphanumeric identifiers may be lexically scoped--magical
builtins like $/ must currently be localized with "local" instead.
my ($foo) = <STDIN>;
my @FOO = <STDIN>;
-both supply a list context to the righthand side, while
+both supply a list context to the right-hand side, while
my $foo = <STDIN>;
-supplies a scalar context. But the following only declares one variable:
+supplies a scalar context. But the following declares only one variable:
my $foo, $bar = 1;
modifiers appended to simple statements. Such modifiers are not
control structures and have no effect on scoping.)
-The C<foreach> loop defaults to dynamically scoping its index variable
+The C<foreach> loop defaults to scoping its index variable dynamically
(in the manner of C<local>; see below). However, if the index
variable is prefixed with the keyword "my", then it is lexically
scoped instead. Thus in the loop
That will print out 20 and 10.
-You may declare "my" variables at the outer most scope of a file to
-totally hide any such identifiers from the outside world. This is similar
+You may declare "my" variables at the outermost scope of a file to
+hide any such identifiers totally from the outside world. This is similar
to C's static variables at the file level. To do this with a subroutine
requires the use of a closure (anonymous function). If a block (such as
an eval(), function, or C<package>) wants to create a private subroutine
&$secret_sub();
As long as the reference is never returned by any function within the
-module, no outside module can see the subroutine, since its name is not in
+module, no outside module can see the subroutine, because its name is not in
any package's symbol table. Remember that it's not I<REALLY> called
$some_pack::secret_version or anything; it's just $secret_version,
unqualified and unqualifiable.
via C<require> or C<use>, then this is probably just fine. If it's
all in the main program, you'll need to arrange for the my()
to be executed early, either by putting the whole block above
-your pain program, or more likely, merely placing a BEGIN
+your pain program, or more likely, placing merely a BEGIN
sub around it to make sure it gets executed before your program
starts to run:
scoping is done with "my", which works more like C's auto declarations.
If more than one variable is given to local(), they must be placed in
-parens. All listed elements must be legal lvalues. This operator works
+parentheses. All listed elements must be legal lvalues. This operator works
by saving the current values of those variables in its argument list on a
hidden stack and restoring them upon exiting the block, subroutine or
eval. This means that called subroutines can also reference the local
local($foo) = <STDIN>;
local @FOO = <STDIN>;
-both supply a list context to the righthand side, while
+both supply a list context to the right-hand side, while
local $foo = <STDIN>;
but rather the name of it, so that the subroutine can modify the global
copy of it rather than working with a local copy. In perl you can
refer to all objects of a particular name by prefixing the name
-with a star: C<*foo>. This is often known as a "typeglob", since the
+with a star: C<*foo>. This is often known as a "typeglob", because the
star on the front can be thought of as a wildcard match for all the
funny prefix characters on variables and subroutines and such.
an array. It will certainly be faster to pass the typeglob (or reference).
Even if you don't want to modify an array, this mechanism is useful for
-passing multiple arrays in a single LIST, since normally the LIST
+passing multiple arrays in a single LIST, because normally the LIST
mechanism will merge all the array values so that you can't extract out
the individual arrays. For more on typeglobs, see
L<perldata/"Typeglobs and FileHandles">.
return grep { $seen{$_} == @_ } keys %seen;
}
-So far, we're just using the normal list return mechanism.
+So far, we're using just the normal list return mechanism.
What happens if you want to pass or return a hash? Well,
-if you're only using one of them, or you don't mind them
+if you're using only one of them, or you don't mind them
concatenating, then the normal calling convention is ok, although
a little expensive.
or
(%a, %b) = func(%c, %d);
-That syntax simply won't work. It just sets @a or %a and clears the @b or
+That syntax simply won't work. It sets just @a or %a and clears the @b or
%b. Plus the function didn't get passed into two separate arrays or
hashes: it got one long list in @_, as always.
Here we're using the typeglobs to do symbol table aliasing. It's
a tad subtle, though, and also won't work if you're using my()
-variables, since only globals (well, and local()s) are in the symbol table.
+variables, because only globals (well, and local()s) are in the symbol table.
=head2 Prototypes
then mypush() takes arguments exactly like push() does. The declaration
of the function to be called must be visible at compile time. The prototype
-only affects the interpretation of new-style calls to the function, where
+affects only the interpretation of new-style calls to the function, where
new-style is defined as not using the C<&> character. In other words,
if you call it like a builtin function, then it behaves like a builtin
function. If you call it like an old-fashioned subroutine, then it
like C<\&foo> or on indirect subroutine calls like C<&{$subref}>.
Method calls are not influenced by prototypes either, because the
-function to be called is indeterminate at compile time, since it depends
+function to be called is indeterminate at compile time, because it depends
on inheritance.
-Since the intent is primarily to let you define subroutines that work
+Because the intent is primarily to let you define subroutines that work
like builtin commands, here are the prototypes for some other functions
that parse almost exactly like the corresponding builtins.
Note how the last three examples above are treated specially by the parser.
mygrep() is parsed as a true list operator, myrand() is parsed as a
true unary operator with unary precedence the same as rand(), and
-mytime() is truly argumentless, just like time(). That is, if you
+mytime() is truly without arguments, just like time(). That is, if you
say
mytime +2;
issues having to do with the visibility of @_. I'm ignoring that
question for the moment. (But note that if we make @_ lexically
scoped, those anonymous subroutines can act like closures... (Gee,
-is this sounding a little Lispish? (Nevermind.))))
+is this sounding a little Lispish? (Never mind.))))
And here's a reimplementation of grep:
Then you've just supplied an automatic scalar() in front of their
argument, which can be more than a bit surprising. The old @foo
which used to hold one thing doesn't get passed in. Instead,
-the func() now gets passed in 1, that is, the number of elments
+the func() now gets passed in 1, that is, the number of elements
in @foo. And the split() gets called in a scalar context and
starts scribbling on your @_ parameter list.
-This is all very powerful, of course, and should only be used in moderation
+This is all very powerful, of course, and should be used only in moderation
to make the world a better place.
=head2 Overriding Builtin Functions
-Many builtin functions may be overridden, though this should only be
-tried occasionally and for good reason. Typically this might be
+Many builtin functions may be overridden, though this should be tried
+only occasionally and for good reason. Typically this might be
done by a package attempting to emulate missing builtin functionality
on a non-Unix system.
-Overriding may only be done by importing the name from a
+Overriding may be done only by importing the name from a
module--ordinary predeclaration isn't good enough. However, the
-C<subs> pragma (compiler directive) lets you, in effect, predeclare subs
+C<subs> pragma (compiler directive) lets you, in effect, pre-declare subs
via the import syntax, and these names may then override the builtin ones:
use subs 'chdir', 'chroot', 'chmod', 'chown';
sub chdir { ... }
Library modules should not in general export builtin names like "open"
-or "chdir" as part of their default @EXPORT list, since these may
+or "chdir" as part of their default @EXPORT list, because these may
sneak into someone else's namespace and change the semantics unexpectedly.
Instead, if the module adds the name to the @EXPORT_OK list, then it's
possible for a user to import the name explicitly, but not implicitly.
who('am', 'i');
ls('-l');
-In fact, if you preclare the functions you want to call that way, you don't
+In fact, if you pre-declare the functions you want to call that way, you don't
even need the parentheses:
use subs qw(date who ls);
the beginning or the end of the script. However, if you're using
lexically-scoped private variables created with my(), you'll have to make sure
your format or subroutine definition is within the same block scope
-as the my if you expect to to be able to access those private variables.
+as the my if you expect to be able to access those private variables.
Declaring a subroutine allows a subroutine name to be used as if it were a
list operator from that point forward in the program. You can declare a
side effects. Every simple statement must be terminated with a
semicolon, unless it is the final statement in a block, in which case
the semicolon is optional. (A semicolon is still encouraged there if the
-block takes up more than one line, since you may eventually add another line.)
+block takes up more than one line, because you may eventually add another line.)
Note that there are some operators like C<eval {}> and C<do {}> that look
like compound statements, but aren't (they're just TERMs in an expression),
and thus need an explicit termination if used as the last item in a statement.
} until $line eq ".\n";
See L<perlfunc/do>. Note also that the loop control
-statements described later will I<NOT> work in this construct, since
+statements described later will I<NOT> work in this construct, because
modifiers don't take loop labels. Sorry. You can always wrap
another block around it to do that sort of thing.
open(FOO) ? 'hi mom' : die "Can't open $FOO: $!";
# a bit exotic, that last one
-The C<if> statement is straightforward. Since BLOCKs are always
+The C<if> statement is straightforward. Because BLOCKs are always
bounded by curly brackets, there is never any ambiguity about which
C<if> an C<else> goes with. If you use C<unless> in place of C<if>,
the sense of the test is reversed.
See how much easier this is? It's cleaner, safer, and faster. It's
cleaner because it's less noisy. It's safer because if code gets added
between the inner and outer loops later on, the new code won't be
-accidentally executed, the C<next> explicitly iterates the other loop
+accidentally executed. The C<next> explicitly iterates the other loop
rather than merely terminating the inner one. And it's faster because
Perl executes a C<foreach> statement more rapidly than it would the
equivalent C<for> loop.
.........
}
-Note that pod translators should only look at paragraphs beginning
+Note that pod translators should look at only paragraphs beginning
with a pod directive (it makes parsing easier), whereas the compiler
actually knows to look for pod escapes even in the middle of a
paragraph. This means that the following secret stuff will be
=head1 DESCRIPTION
Prior to release 5.0 of Perl, a programmer could use dbmopen()
-to magically connect an on-disk database in the standard Unix dbm(3x)
-format to a %HASH in their program. However, their Perl was either
+to connect an on-disk database in the standard Unix dbm(3x)
+format magically to a %HASH in their program. However, their Perl was either
built with one particular dbm library or another, but not both, and
you couldn't extend this mechanism to other packages or types of variables.
returned by the "new" method is also returned by the tie() function,
which would be useful if you wanted to access other methods in
C<CLASSNAME>. (You don't actually have to return a reference to a right
-"type" (e.g. HASH or C<CLASSNAME>) so long as it's a properly blessed
+"type" (e.g., HASH or C<CLASSNAME>) so long as it's a properly blessed
object.) You can also retrieve a reference to the underlying object
using the tied() function.
This method will be triggered every time the tied variable is accessed
(read). It takes no arguments beyond its self reference, which is the
-object representing the scalar we're dealing with. Since in this case
-we're just using a SCALAR ref for the tied scalar object, a simple $$self
+object representing the scalar we're dealing with. Because in this case
+we're using just a SCALAR ref for the tied scalar object, a simple $$self
allows the method to get at the real value stored there. In our example
below, that real value is the process ID to which we've tied our variable.
=item DESTROY this
This method will be triggered when the tied variable needs to be destructed.
-As with other object classes, such a method is seldom necessary, since Perl
+As with other object classes, such a method is seldom necessary, because Perl
deallocates its moribund object's memory for you automatically--this isn't
C++, you know. We'll use a DESTROY method here for debugging purposes only.
=back
That's about all there is to it. Actually, it's more than all there
-is to it, since we've done a few nice things here for the sake
+is to it, because we've done a few nice things here for the sake
of completeness, robustness, and general aesthetics. Simpler
TIESCALAR classes are certainly possible.
for all accesses, even though the constructors differ in names (TIESCALAR
vs TIEARRAY). While in theory you could have the same class servicing
several tied types, in practice this becomes cumbersome, and it's easiest
-to simply keep them at one tie type per class.
+to keep them at simply one tie type per class.
=item STORE this, index, value
functions to iterate over all the keys. And DESTROY is called when the
tied variable is garbage collected.
-If this seems like a lot, then feel free to merely inherit
-from the standard Tie::Hash module for most of your methods, redefining only
+If this seems like a lot, then feel free to inherit from
+merely the standard Tie::Hash module for most of your methods, redefining only
the interesting ones. See L<Tie::Hash> for details.
Remember that Perl distinguishes between a key not existing in the hash,
C<defined()> functions.
Here's an example of a somewhat interesting tied hash class: it gives you
-a hash representing a particular user's dotfiles. You index into the hash
-with the name of the file (minus the dot) and you get back that dotfile's
+a hash representing a particular user's dot files. You index into the hash
+with the name of the file (minus the dot) and you get back that dot file's
contents. For example:
use DotFiles;
$dot{login} =~ /MANPATH/ ||
$dot{cshrc} =~ /MANPATH/ )
{
- print "you seem to set your manpath\n";
+ print "you seem to set your MANPATH\n";
}
Or here's another sample of using our tied class:
=item HOME
-where those dotfiles live
+where those dot files live
=item CLOBBER
=item LIST
-the hash of dotfile names and content mappings
+the hash of dot file names and content mappings
=back
my $DEBUG = 0;
sub debug { $DEBUG = @_ ? shift : 1 }
-For our example, we want to able to emit debugging info to help in tracing
+For our example, we want to be able to emit debugging info to help in tracing
during development. We keep also one convenience function around
internally to help print out warnings; whowasi() returns the function name
that calls it.
It's probably worth mentioning that if you're going to filetest the
return values out of a readdir, you'd better prepend the directory
-in question. Otherwise, since we didn't chdir() there, it would
+in question. Otherwise, because we didn't chdir() there, it would
have been testing the wrong file.
=item FETCH this, key
It was easy to write by having it call the Unix cat(1) command, but it
would probably be more portable to open the file manually (and somewhat
-more efficient). Of course, since dot files are a Unixy concept, we're
+more efficient). Of course, because dot files are a Unixy concept, we're
not that concerned.
=item STORE this, key, value
This method is triggered when the whole hash is to be cleared, usually by
assigning the empty list to it.
-In our example, that would remove all the user's dotfiles! It's such a
+In our example, that would remove all the user's dot files! It's such a
dangerous thing that they'll have to set CLOBBER to something higher than
1 to make it happen.
sub CLEAR {
carp &whowasi if $DEBUG;
my $self = shift;
- croak "@{[&whowasi]}: won't remove all dotfiles for $self->{USER}"
+ croak "@{[&whowasi]}: won't remove all dot files for $self->{USER}"
unless $self->{CLOBBER} > 1;
my $dot;
foreach $dot ( keys %{$self->{LIST}}) {
useful if you're carrying about ordering or calling the iterator from more
than one sequence, or not really storing things in a hash anywhere.
-For our example, we're using a real hash so we'll just do the simple
-thing, but we'll have to indirect through the LIST field.
+For our example, we're using a real hash so we'll do just the simple
+thing, but we'll have to go through the LIST field indirectly.
sub NEXTKEY {
carp &whowasi if $DEBUG;
hashes) to a dbm file. The first problem is that all but GDBM and
Berkeley DB have size limitations, but beyond that, you also have problems
with how references are to be represented on disk. One experimental
-module that does attempt to partially address this need is the MLDBM
+module that does attempt to address this need partially is the MLDBM
module. Check your nearest CPAN site as described in L<perlmod> for
source code to MLDBM.
=head1 DESCRIPTION
This page provides a brief table of contents for the rest of the Perl
-documentation set. It is meant to be be quickly scanned or grepped
+documentation set. It is meant to be scanned quickly or grepped
through to locate the proper section you're looking for.
=head1 BASIC DOCUMENTATION
=item The Arrow Operator
-=item Autoincrement and Autodecrement
+=item Auto-increment and Auto-decrement
=item Exponentiation
unary &, unary *, (TYPE)
-=item Quote and Quotelike Operators
+=item Quote and Quote-like Operators
-=item Regexp Quotelike Operators
+=item Regexp Quote-like Operators
?PATTERN?, m/PATTERN/gimosx, /PATTERN/gimosx, q/STRING/, C<'STRING'>,
-=head2 sigtrap - Perl pragma to enable stack backtrace on unexpected
+=head2 sigtrap - Perl pragma to enable stack back-trace on unexpected
signals
=item SYNOPSIS
-=head2 subs - Perl pragma to predeclare sub names
+=head2 subs - Perl pragma to pre-declare sub names
=item SYNOPSIS
-=head2 vars - Perl pragma to predeclare global variable names
+=head2 vars - Perl pragma to pre-declare global variable names
=item SYNOPSIS
guess_name, init_main, init_dirscan, init_others, find_perl
-=item Methods to actually produce chunks of text for the Makefile
+=item Methods to produce chunks of text for the Makefile
post_initialize, const_config, constants, const_loadlibs, const_cccmd,
=head1 AUXILIARY DOCUMENTATION
-Here should be listed all the extra program's docs, but they don't all
-have man pages yet:
+Here should be listed all the extra program's documentation, but they don't all
+have manual pages yet:
=item a2p
=item *
The concatenation operator is ".", not the null string. (Using the
-null string would render C</pat/ /pat/> unparsable, since the third slash
-would be interpreted as a division operator--the tokener is in fact
+null string would render C</pat/ /pat/> unparsable, because the third slash
+would be interpreted as a division operator--the tokenizer is in fact
slightly context sensitive for operators like "/", "?", and "E<gt>".
And in fact, "." itself can be the beginning of a number.)
=item *
-The backtick operator does variable interpolation without regard to
+The back-tick operator does variable interpolation without regard to
the presence of single quotes in the command.
=item *
-The backtick operator does no translation of the return value, unlike B<csh>.
+The back-tick operator does no translation of the return value, unlike B<csh>.
=item *
Shells (especially B<csh>) do several levels of substitution on each
-command line. Perl does substitution only in certain constructs
-such as double quotes, backticks, angle brackets, and search patterns.
+command line. Perl does substitution in only certain constructs
+such as double quotes, back-ticks, angle brackets, and search patterns.
=item *
=item *
Avoid barewords if you can, especially all lower-case ones.
-You can't tell just by looking at it whether a bareword is
+You can't tell by just looking at it whether a bareword is
a function or a string. By using quotes on strings and
-parens on function calls, you won't ever get them confused.
+parentheses on function calls, you won't ever get them confused.
=item *
You cannot discern from mere inspection which built-ins
are unary operators (like chop() and chdir())
and which are list operators (like print() and unlink()).
-(User-defined subroutines can B<only> be list operators, never
+(User-defined subroutines can be B<only> list operators, never
unary ones.) See L<perlop>.
=item *
=item *
The E<lt>FHE<gt> construct is not the name of the filehandle, it is a readline
-operation on that handle. The data read is only assigned to $_ if the
+operation on that handle. The data read is assigned to $_ only if the
file read is the sole condition in a while loop:
while (<FH>) { }
=item * Deprecation
Double-colon is now a valid package separator in a variable name. Thus these
-behave differently in perl4 vs. perl5, since the packages don't exist.
+behave differently in perl4 vs. perl5, because the packages don't exist.
$a=1;$b=2;$c=3;$var=4;
print "$a::$b::$c ";
=item * Numerical
-This specific item has been deleted. It demonstrated how the autoincrement
+This specific item has been deleted. It demonstrated how the auto-increment
operator would not catch when a number went over the signed int limit. Fixed
-in 5.003_04. But always be wary when using large ints. If in doubt:
+in 5.003_04. But always be wary when using large integers. If in doubt:
use Math::BigInt;
Variable suicide behavior is more consistent under Perl 5.
Perl5 exhibits the same behavior for associative arrays and scalars,
-that perl4 exhibits only for scalars.
+that perl4 exhibits for only scalars.
$aGlobal{ "aKey" } = "global value";
print "MAIN:", $aGlobal{"aKey"}, "\n";
open FOO || die;
-is now incorrect. You need parens around the filehandle.
-Otherwise, perl5 leaves the statement as it's default precedence:
+is now incorrect. You need parentheses around the filehandle.
+Otherwise, perl5 leaves the statement as its default precedence:
open(FOO || die);
=item * Regular Expression
-C<s`lhs`rhs`> (using backticks) is now a normal substitution, with no
-backtick expansion
+C<s`lhs`rhs`> (using back-ticks) is now a normal substitution, with no
+back-tick expansion
$string = "";
$string =~ s`^`hostname`;
=item * (SysV)
Under SysV OS's, C<seek()> on a file opened to append C<E<gt>E<gt>> now does
-the right thing w.r.t. the fopen() man page. e.g. - When a file is opened
+the right thing w.r.t. the fopen() man page. e.g., - When a file is opened
for append, it is impossible to overwrite information already in
the file.
=head2 Predefined Names
The following names have special meaning to Perl. Most of the
-punctuational names have reasonable mnemonics, or analogues in one of
+punctuation names have reasonable mnemonics, or analogues in one of
the shells. Nevertheless, if you wish to use the long variable names,
you just need to say
The default input and pattern-searching space. The following pairs are
equivalent:
- while (<>) {...} # only equivalent in while!
+ while (<>) {...} # equivalent in only while!
while ($_ = <>) {...}
/^Subject:/
=item $E<lt>I<digit>E<gt>
-Contains the subpattern from the corresponding set of parentheses in
+Contains the sub-pattern from the corresponding set of parentheses in
the last pattern matched, not counting patterns matched in nested
blocks that have been exited already. (Mnemonic: like \digit.)
These variables are all read-only.
=item $*
-Set to 1 to do multiline matching within a string, 0 to tell Perl
+Set to 1 to do multi-line matching within a string, 0 to tell Perl
that it can assume that strings contain a single line, for the purpose
of optimizing pattern matches. Pattern matches on strings containing
multiple newlines can produce confusing results when "C<$*>" is 0. Default
is 0. (Mnemonic: * matches multiple things.) Note that this variable
-only influences the interpretation of "C<^>" and "C<$>". A literal newline can
+influences the interpretation of only "C<^>" and "C<$>". A literal newline can
be searched for even when C<$* == 0>.
Use of "C<$*>" is deprecated in Perl 5.
The current input line number for the last file handle from
which you read (or performed a C<seek> or C<tell> on). An
-explicit close on a filehandle resets the line number. Since
+explicit close on a filehandle resets the line number. Because
"C<E<lt>E<gt>>" never does an explicit close, line numbers increase
across ARGV files (but see examples under eof()). Localizing C<$.> has
the effect of also localizing Perl's notion of "the last read
If set to nonzero, forces a flush after every write or print on the
currently selected output channel. Default is 0 (regardless of whether
-the channel is actually buffered by the system or not; C<$|> only tells
-you whether you've asked Perl to explicitly flush after each write).
+the channel is actually buffered by the system or not; C<$|> tells you
+only whether you've asked Perl explicitly to flush after each write).
Note that STDOUT will typically be line buffered if output is to the
terminal and block buffered otherwise. Setting this variable is useful
primarily when you are outputting to a pipe, such as when you are running
=item $,
The output field separator for the print operator. Ordinarily the
-print operator simply prints out the comma separated fields you
-specify. In order to get behavior more like B<awk>, set this variable
+print operator simply prints out the comma-separated fields you
+specify. To get behavior more like B<awk>, set this variable
as you would set B<awk>'s OFS variable to specify what is printed
between fields. (Mnemonic: what is printed when there is a , in your
print statement.)
=item $\
The output record separator for the print operator. Ordinarily the
-print operator simply prints out the comma separated fields you
-specify, with no trailing newline or record separator assumed. In
-order to get behavior more like B<awk>, set this variable as you would
+print operator simply prints out the comma-separated fields you
+specify, with no trailing newline or record separator assumed.
+To get behavior more like B<awk>, set this variable as you would
set B<awk>'s ORS variable to specify what is printed at the end of the
print. (Mnemonic: you set "C<$\>" instead of adding \n at the end of the
print. Also, it's just like C<$/>, but it's what you get "back" from
=item $^L
-What formats output to perform a formfeed. Default is \f.
+What formats output to perform a form feed. Default is \f.
=item $ACCUMULATOR
=item $?
-The status returned by the last pipe close, backtick (C<``>) command,
+The status returned by the last pipe close, back-tick (C<``>) command,
or system() operator. Note that this is the status word returned by
the wait() system call, so the exit value of the subprocess is actually
(C<$? E<gt>E<gt> 8>). Thus on many systems, C<$? & 255> gives which signal,
value of "C<$!>" to be anything in particular unless you've gotten a
specific error return indicating a system error.) If used in a string
context, yields the corresponding system error string. You can assign
-to "C<$!>" in order to set I<errno> if, for instance, you want "C<$!>" to return the
+to "C<$!>" to set I<errno> if, for instance, you want "C<$!>" to return the
string for error I<n>, or you want to set the exit value for the die()
operator. (Mnemonic: What just went bang?)
More specific information about the last system error than that
provided by C<$!>, if available. (If not, it's just C<$!> again, except under
OS/2.)
-At the moment, this differs from C<$!> only under VMS and OS/2, where it
+At the moment, this differs from C<$!> under only VMS and OS/2, where it
provides the VMS status value from the last system error, and OS/2 error
code of the last call to OS/2 API which was not directed via CRT. The
caveats mentioned in the description of C<$!> apply here, too.
($<,$>) = ($>,$<); # swap real and effective uid
(Mnemonic: it's the uid you went I<TO>, if you're running setuid.) Note:
-"C<$E<lt>>" and "C<$E<gt>>" can only be swapped on machines supporting setreuid().
+"C<$E<lt>>" and "C<$E<gt>>" can be swapped on only machines supporting setreuid().
=item $REAL_GROUP_ID
used to I<GROUP> things. The effective gid is the group that's I<RIGHT> for
you, if you're running setgid.)
-Note: "C<$E<lt>>", "C<$E<gt>>", "C<$(>" and "C<$)>" can only be set on machines
+Note: "C<$E<lt>>", "C<$E<gt>>", "C<$(>" and "C<$)>" can be set on only machines
that support the corresponding I<set[re][ug]id()> routine. "C<$(>" and "C<$)>"
-can only be swapped on machines supporting setregid(). Because Perl doesn't
+can be swapped on only machines supporting setregid(). Because Perl doesn't
currently use initgroups(), you can't set your group vector to multiple groups.
=item $PROGRAM_NAME
The array @ARGV contains the command line arguments intended for the
script. Note that C<$#ARGV> is the generally number of arguments minus
-one, since C<$ARGV[0]> is the first argument, I<NOT> the command name. See
+one, because C<$ARGV[0]> is the first argument, I<NOT> the command name. See
"C<$0>" for the command name.
=item @INC
initially consists of the arguments to any B<-I> command line switches,
followed by the default Perl library, probably F</usr/local/lib/perl>,
followed by ".", to represent the current directory. If you need to
-modify this at runtime, you should use the C<use lib> pragma in order
-to also get the machine-dependent library properly loaded:
+modify this at runtime, you should use the C<use lib> pragma
+to get the machine-dependent library properly loaded also:
use lib '/mypath/libdir/';
use SomeMod;
$SIG{'INT'} = 'DEFAULT'; # restore default action
$SIG{'QUIT'} = 'IGNORE'; # ignore SIGQUIT
-The %SIG array only contains values for the signals actually set within
+The %SIG array contains values for only the signals actually set within
the Perl script. Here are some other examples:
$SIG{PIPE} = Plumber; # SCARY!!
=head2 Returning Undef And Empty Lists
-Occasionally the programmer will want to simply return
+Occasionally the programmer will want to return simply
C<undef> or an empty list if a function fails rather than a
separate status value. The rpcb_gettime() function offers
just this situation. If the function succeeds we would like
The REQUIRE: keyword is used to indicate the minimum version of the
B<xsubpp> compiler needed to compile the XS module. An XS module which
-contains the following statement will only compile with B<xsubpp> version
+contains the following statement will compile with only B<xsubpp> version
1.922 or greater:
REQUIRE: 1.922
=head2 The VERSIONCHECK: Keyword
The VERSIONCHECK: keyword corresponds to B<xsubpp>'s C<-versioncheck> and
-C<-noversioncheck> options. This keyword overrides the commandline
+C<-noversioncheck> options. This keyword overrides the command line
options. Version checking is enabled by default. When version checking is
enabled the XS module will attempt to verify that its version matches the
version of the PM module.
=head2 The PROTOTYPES: Keyword
The PROTOTYPES: keyword corresponds to B<xsubpp>'s C<-prototypes> and
-C<-noprototypes> options. This keyword overrides the commandline options.
+C<-noprototypes> options. This keyword overrides the command-line options.
Prototypes are enabled by default. When prototypes are enabled XSUBs will
be given Perl prototypes. This keyword may be used multiple times in an XS
module to enable and disable prototypes for different parts of the module.
This tutorial starts with very simple examples and becomes more complex,
with each new example adding new features. Certain concepts may not be
-completely explained until later in the tutorial in order to slowly ease
-the reader into building extensions.
+completely explained until later in the tutorial to ease the
+reader slowly into building extensions.
=head2 VERSION CAVEAT
=head2 DYNAMIC VERSUS STATIC
It is commonly thought that if a system does not have the capability to
-dynamically load a library, you cannot build XSUBs. This is incorrect.
+load a library dynamically, you cannot build XSUBs. This is incorrect.
You I<can> build them, but you must link the XSUB's subroutines with the
rest of Perl, creating a new executable. This situation is similar to
Perl 4.
Now perform the same steps as before, generating a Makefile from the
Makefile.PL file, and running make.
-In order to test that our extension works, we now need to look at the
+To test that our extension works, we now need to look at the
file test.pl. This file is set up to imitate the same kind of testing
structure that Perl itself has. Within the test script, you perform a
number of tests to confirm the behavior of the extension, printing "ok"
=head2 WARNING
In general, it's not a good idea to write extensions that modify their input
-parameters, as in Example 3. However, in order to better accommodate calling
+parameters, as in Example 3. However, to accommodate better calling
pre-existing C routines, which often do modify their input parameters,
this behavior is tolerated. The next example will show how to do this.
print &Mytest2::foo(1, 2, "0.0") == 7 ? "ok 3\n" : "not ok 3\n";
print abs(&Mytest2::foo(0, 0, "-3.4") - 0.6) <= 0.01 ? "ok 4\n" : "not ok 4\n";
-(When dealing with floating-point comparisons, it is often useful to not check
+(When dealing with floating-point comparisons, it is often useful not to check
for equality, but rather the difference being below a certain epsilon factor,
0.01 in this case)
The .pm file has exported the name TESTVAL in the @EXPORT array. This
could lead to name clashes. A good rule of thumb is that if the #define
-is only going to be used by the C routines themselves, and not by the user,
+is going to be used by only the C routines themselves, and not by the user,
they should be removed from the @EXPORT array. Alternately, if you don't
mind using the "fully qualified name" of a variable, you could remove most
or all of the items in the @EXPORT array.
=back
We've also told Perl about the library that we built in the mylib
-subdirectory. That required only the addition of the MYEXTLIB variable
+subdirectory. That required the addition of only the MYEXTLIB variable
to the WriteMakefile call and the replacement of the postamble subroutine
to cd into the subdirectory and run make. The Makefile.PL for the
library is a bit more complicated, but not excessively so. Again we
replaced the postamble subroutine to insert our own code. This code
-simply specified that the library to be created here was a static
+specified simply that the library to be created here was a static
archive (as opposed to a dynamically loadable library) and provided the
commands to build it.
to assist in making the interface between Perl and your extension simpler
or easier to understand. These routines should live in the .pm file.
Whether they are automatically loaded when the extension itself is loaded
-or only loaded when called depends on where in the .pm file the subroutine
+or loaded only when called depends on where in the .pm file the subroutine
definition is placed.
=head2 DOCUMENTING YOUR EXTENSION
projects / p5sagit/p5-mst-13.2.git / commitdiff