diff options
| author | Steve Kelem <steve.kelem@xilinx.com> | 1996-12-09 13:33:11 -0800 |
|---|---|---|
| committer | Chip Salzenberg <chip@atlantic.net> | 1996-12-19 16:44:00 +1200 |
| commit | 0135f10892ed8a21c4dbd1fca21fbcc365df99dd (patch) | |
| tree | bc7b2c61d60a2a42fdc32c4f501016df042aa5b5 | |
| parent | 32e22efaa9ec59b73a208b6c532a0b435e2c6462 (diff) | |
| download | perl-0135f10892ed8a21c4dbd1fca21fbcc365df99dd.tar.gz | |
pod patches for English errors
Here are the patches for the pod files in Perl5.003, subversion 11.
The following corrections were made:
Spelling, grammar, jargon were fixed.
"It's" is the contraction of "it" and "is".
"Its" is the possessive form of "it".
only/just/simply/merely
Here's the example sentence that illustrates that "only" can be used in
almost any position in a sentence, and that each new sentence means
something different. As a writer, your goal should be to communicate your
ideas unambiguously.
She kissed him on the lips.
Sentence Meaning of "only"
a. Only she kissed him on the lips. She and no one else
b. She only kissed him on the lips. She didn't do anything else with his
lips.
c. She kissed only him on the lips. She didn't kiss anyone else on the
lips.
d. She kissed him only on the lips. not below or next to the lips
e. She kissed him on only the lips. She didn't kiss him anywhere else.
f. She kissed him on the lips only. ambiguous--the meaning could be any
of a-e, depending on vocal stress
since/because
lend/loan
which/that
i.e. & ie => i.e.,
e.g. & eg => e.g.,
in order to => to
split infinitives
outer most => outermost
doubled words (to, the, be)
to able=> to be able
I hope this helps!
p5p-msgid: <24616.850167191@castor>
| -rw-r--r-- | pod/perl.pod | 6 | ||||
| -rw-r--r-- | pod/perlapio.pod | 14 | ||||
| -rw-r--r-- | pod/perlbot.pod | 4 | ||||
| -rw-r--r-- | pod/perlcall.pod | 60 | ||||
| -rw-r--r-- | pod/perldata.pod | 26 | ||||
| -rw-r--r-- | pod/perldebug.pod | 36 | ||||
| -rw-r--r-- | pod/perldiag.pod | 112 | ||||
| -rw-r--r-- | pod/perldsc.pod | 40 | ||||
| -rw-r--r-- | pod/perlembed.pod | 16 | ||||
| -rw-r--r-- | pod/perlform.pod | 2 | ||||
| -rw-r--r-- | pod/perlfunc.pod | 124 | ||||
| -rw-r--r-- | pod/perlguts.pod | 74 | ||||
| -rw-r--r-- | pod/perllol.pod | 26 | ||||
| -rw-r--r-- | pod/perlmod.pod | 46 | ||||
| -rw-r--r-- | pod/perlobj.pod | 42 | ||||
| -rw-r--r-- | pod/perlop.pod | 84 | ||||
| -rw-r--r-- | pod/perlpod.pod | 10 | ||||
| -rw-r--r-- | pod/perlre.pod | 65 | ||||
| -rw-r--r-- | pod/perlref.pod | 18 | ||||
| -rw-r--r-- | pod/perlrun.pod | 22 | ||||
| -rw-r--r-- | pod/perlsec.pod | 16 | ||||
| -rw-r--r-- | pod/perlstyle.pod | 16 | ||||
| -rw-r--r-- | pod/perlsub.pod | 66 | ||||
| -rw-r--r-- | pod/perlsyn.pod | 12 | ||||
| -rw-r--r-- | pod/perltie.pod | 46 | ||||
| -rw-r--r-- | pod/perltoc.pod | 20 | ||||
| -rw-r--r-- | pod/perltrap.pod | 38 | ||||
| -rw-r--r-- | pod/perlvar.pod | 48 | ||||
| -rw-r--r-- | pod/perlxs.pod | 8 | ||||
| -rw-r--r-- | pod/perlxstut.pod | 20 |
30 files changed, 558 insertions, 559 deletions
diff --git a/pod/perl.pod b/pod/perl.pod index 2487a5e742..ae7e3f8c88 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -69,7 +69,7 @@ in the appropriate start-up files. To find out where these are, type: 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 @@ -191,7 +191,7 @@ to an object class which defines its access methods. =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 @@ -298,7 +298,7 @@ The B<-w> switch is not mandatory. 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() diff --git a/pod/perlapio.pod b/pod/perlapio.pod index d2fd74ab5c..ae67494ce2 100644 --- a/pod/perlapio.pod +++ b/pod/perlapio.pod @@ -128,7 +128,7 @@ the meaning of "fileno" may not match UNIX. =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)> @@ -156,7 +156,7 @@ in terms of PerlIO_seek() at some point. =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 @@ -201,7 +201,7 @@ behaviour. =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 @@ -209,7 +209,7 @@ is has nothing to do with $| auto-flush.) 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. @@ -236,7 +236,7 @@ bytes in the buffer. =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) && \ @@ -245,14 +245,14 @@ allow perls fast code to handle <FILE> mechanism. =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". diff --git a/pod/perlbot.pod b/pod/perlbot.pod index 0f7078f197..30d00558b4 100644 --- a/pod/perlbot.pod +++ b/pod/perlbot.pod @@ -57,7 +57,7 @@ See L<CLASS CONTEXT AND THE OBJECT>. =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. @@ -404,7 +404,7 @@ This problem can be solved by using the object to define the context of the 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; diff --git a/pod/perlcall.pod b/pod/perlcall.pod index ac9229fbb1..f9fe54bd6b 100644 --- a/pod/perlcall.pod +++ b/pod/perlcall.pod @@ -5,7 +5,7 @@ perlcall - Perl calling conventions from C =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 @@ -30,7 +30,7 @@ called instead. 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 @@ -61,7 +61,7 @@ subroutines. They are 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 @@ -84,9 +84,9 @@ use of I<perl_call_sv>. 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> @@ -208,10 +208,10 @@ automatically for you. Note that it is still possible to indicate a 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. @@ -254,7 +254,7 @@ belongs to C<joe>. =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 { }> @@ -408,7 +408,7 @@ Enough of the definition talk, let's have a few examples. 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 @@ -458,7 +458,7 @@ specified. =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>. @@ -529,15 +529,15 @@ have used this macro. 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 @@ -555,7 +555,7 @@ local copy, I<not> the global copy. =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. @@ -580,7 +580,7 @@ function. 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 @@ -589,7 +589,7 @@ and simply returns their sum. $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 @@ -685,7 +685,7 @@ Expecting a single value is not quite the same as knowing that there 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. @@ -998,7 +998,7 @@ refers to the C equivalent of C<$@>. 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>. @@ -1026,7 +1026,7 @@ version of the call_Subtract example above inside a destructor: 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. @@ -1064,7 +1064,7 @@ Here is a snippet of XSUB which defines I<CallSubPV>. 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. @@ -1079,7 +1079,7 @@ I<perl_call_sv> instead of I<perl_call_pv>. 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) ; @@ -1092,7 +1092,7 @@ how you can specify the Perl subroutine. 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 ; @@ -1143,7 +1143,7 @@ the version of Perl you are using) 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 @@ -1185,7 +1185,7 @@ SV. The code below shows C<SaveSub2> modified to do that 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 @@ -1247,9 +1247,9 @@ Consider the following Perl code } } -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. @@ -1346,7 +1346,7 @@ The output from that will be =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 @@ -1441,7 +1441,7 @@ the extreme left. 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 @@ -1450,7 +1450,7 @@ eventually consume all the available memory in your system - kapow! 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. @@ -1524,7 +1524,7 @@ registers, C<pcb1>, might look like this 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 diff --git a/pod/perldata.pod b/pod/perldata.pod index c1144715d8..7842039e89 100644 --- a/pod/perldata.pod +++ b/pod/perldata.pod @@ -19,7 +19,7 @@ I<identifier>, that is, a string beginning with a letter or underscore, 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 @@ -65,7 +65,7 @@ This means that $foo and @foo are two different variables. It also 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 @@ -80,9 +80,9 @@ It is possible to replace such an alphanumeric name with an expression 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.) @@ -183,7 +183,7 @@ for details on regular expressions. 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 @@ -207,7 +207,7 @@ last value, like the C comma operator.) The following is always true: 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; @@ -220,7 +220,7 @@ If you evaluate a hash in a scalar context, it returns a value which is 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 @@ -247,7 +247,7 @@ The usual Unix backslash rules apply for making characters such as 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 @@ -276,16 +276,16 @@ in the subscript will be interpreted as an expression. 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__). @@ -432,7 +432,7 @@ put the list in parentheses to avoid ambiguity. Examples: $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]; @@ -454,7 +454,7 @@ produced by the expression on the right side of the assignment: $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: diff --git a/pod/perldebug.pod b/pod/perldebug.pod index f9dd6f4ab6..b6b3550c65 100644 --- a/pod/perldebug.pod +++ b/pod/perldebug.pod @@ -11,7 +11,7 @@ First of all, have you tried using the B<-w> switch? 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: @@ -63,12 +63,12 @@ it's run through your pager, as in =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. @@ -97,7 +97,7 @@ Same as C<V currentpackage [vars]>. =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] @@ -218,7 +218,7 @@ or, with the C<O>ption C<frame=2> set, 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 @@ -332,7 +332,7 @@ affects printing of return value after C<r> command. 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. @@ -455,37 +455,37 @@ See L<"Debugger Internals"> below for more details. =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 @@ -566,7 +566,7 @@ or even 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 @@ -588,7 +588,7 @@ normally end the debugger command with a backslash. Here's an example: 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 @@ -763,7 +763,7 @@ the form C<(eval 31)> for subroutines defined inside C<eval>s. =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 @@ -772,7 +772,7 @@ C<$^D & 1 E<lt>E<lt> 30>). =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>.) @@ -824,7 +824,7 @@ You cannot get the stack frame information or otherwise debug functions 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>. diff --git a/pod/perldiag.pod b/pod/perldiag.pod index 20f4fbd585..4a36443a15 100644 --- a/pod/perldiag.pod +++ b/pod/perldiag.pod @@ -53,7 +53,7 @@ no useful value. See L<perlmod>. =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>. @@ -61,7 +61,7 @@ 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 @@ -176,7 +176,7 @@ the return value of your socket() call? See L<perlfunc/accept>. (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 @@ -336,7 +336,7 @@ exited by calling exit. 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 @@ -344,7 +344,7 @@ that loops once. See L<perlfunc/last>. (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 @@ -352,7 +352,7 @@ that loops once. See L<perlfunc/last>. (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 @@ -434,7 +434,7 @@ They must have ordinary identifiers as names. (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 @@ -510,7 +510,7 @@ for us to go to. See L<perlfunc/goto>. =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.) @@ -537,7 +537,7 @@ assumes that the stat buffer contains all the necessary information, and passes 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 @@ -558,7 +558,7 @@ mailbox buffers to be, and didn't get an answer. (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 @@ -602,16 +602,16 @@ a B<-e> switch. Maybe your /tmp partition is full, or clobbered. =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 @@ -684,7 +684,7 @@ of suidperl. =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 @@ -738,7 +738,7 @@ test the type of the reference, if need be. (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. @@ -755,7 +755,7 @@ be a defined value. This helps to de-lurk some insidious errors. =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. @@ -771,7 +771,7 @@ didn't look like an array reference, or anything else subscriptable. (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. @@ -830,7 +830,7 @@ case it indicates something else. (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 @@ -869,7 +869,7 @@ The interpreter is immediately exited. =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 @@ -912,20 +912,20 @@ PDP-11 or something? 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 @@ -1022,8 +1022,8 @@ is now heavily deprecated. (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. @@ -1084,7 +1084,7 @@ architecture. On a 32-bit architecture the largest octal literal is =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 @@ -1192,7 +1192,7 @@ the previous line just because you saw this message. =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 } @@ -1238,7 +1238,7 @@ that is less than 0. This is difficult to imagine. =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 @@ -1284,7 +1284,7 @@ right. =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 @@ -1414,7 +1414,7 @@ See L<perlform>. =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 @@ -1433,7 +1433,7 @@ supplied it an uninitialized value. See L<perlform>. =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 @@ -1442,7 +1442,7 @@ supplied it an uninitialized value. See L<perlform>. =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 @@ -1554,7 +1554,7 @@ it wasn't a block context. =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 @@ -1640,7 +1640,7 @@ was string. (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 @@ -1675,7 +1675,7 @@ the BSD version, which takes a pid. =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 @@ -1689,7 +1689,7 @@ when you should have written this: =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 ); @@ -1716,7 +1716,7 @@ is now misinterpreted as 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 @@ -1738,7 +1738,7 @@ last argument of the previous construct, for example: =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> @@ -1803,10 +1803,10 @@ an array. Generally it's better to ask for a scalar value (indicated by $). 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>. @@ -1851,7 +1851,7 @@ Check your logic flow. =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 @@ -1963,7 +1963,7 @@ by itself. (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 @@ -2001,7 +2001,7 @@ Often there will be another error message associated with the syntax 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 @@ -2036,7 +2036,7 @@ open. Check your logic. See also L<perlfunc/-X>. =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; @@ -2087,7 +2087,7 @@ into Perl yourself. =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 @@ -2122,7 +2122,7 @@ certain type. Arrays must be @NAME or C<@{EXPR}>. Hashes must be =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" @@ -2186,13 +2186,13 @@ representative, who probably put it there in the first place. =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 @@ -2263,15 +2263,15 @@ Use an explicit printf() or sprintf() instead. =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 @@ -2349,9 +2349,9 @@ into Perl yourself. =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 @@ -2368,7 +2368,7 @@ but in actual fact, you got 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 @@ -2401,7 +2401,7 @@ Use a filename instead. =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. @@ -2422,7 +2422,7 @@ See L<perlfunc/getsockopt>. =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. diff --git a/pod/perldsc.pod b/pod/perldsc.pod index 6991e7a085..ab236e5159 100644 --- a/pod/perldsc.pod +++ b/pod/perldsc.pod @@ -30,7 +30,7 @@ with three dimensions! 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 @@ -41,11 +41,11 @@ of the blame for this can be attributed to the reference-based 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: @@ -76,15 +76,15 @@ of these types of data structures. 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 @@ -102,7 +102,7 @@ multidimensional arrays work as well. $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: @@ -149,7 +149,7 @@ again and again: $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! @@ -218,7 +218,7 @@ something is "interesting", that rather than meaning "intriguing", 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. @@ -290,14 +290,14 @@ this: 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] @@ -325,7 +325,7 @@ example, given the assignment to $LoL above, here's the debugger output: 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. @@ -746,7 +746,7 @@ many different sorts: # 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 @@ -817,7 +817,7 @@ You cannot easily tie a multilevel data structure (such as a hash of 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. diff --git a/pod/perlembed.pod b/pod/perlembed.pod index 186dc88a7b..ea0e8331f2 100644 --- a/pod/perlembed.pod +++ b/pod/perlembed.pod @@ -16,7 +16,7 @@ Read L<perlcall> and L<perlxs>. =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?> @@ -142,7 +142,7 @@ I<miniperlmain.c> containing the essentials of embedding: 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. @@ -303,14 +303,14 @@ substitutions: I<match()>, I<substitute()>, and I<matches()>. 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. @@ -488,9 +488,9 @@ described in L<perlcall>. 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 { @@ -612,7 +612,7 @@ counterpart for each of the extension's XSUBs. Don't worry about this 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()>: @@ -644,7 +644,7 @@ Consult L<perlxs> and L<perlguts> for more details. =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. diff --git a/pod/perlform.pod b/pod/perlform.pod index a9ce4a7876..4fac1a69e3 100644 --- a/pod/perlform.pod +++ b/pod/perlform.pod @@ -198,7 +198,7 @@ Much better! =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: diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 35f840fa33..1ff25185d2 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -14,8 +14,8 @@ a unary operator, but merely separates the arguments of a list 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 @@ -28,7 +28,7 @@ Elements of the LIST should be separated by commas. 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 @@ -257,7 +257,7 @@ uids and gids of the user. There may be other reasons you can't actually 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: @@ -385,7 +385,7 @@ is taken as the name of the filehandle. 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. @@ -536,7 +536,7 @@ omitted, does chroot to $_. 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 @@ -603,7 +603,7 @@ their own password: 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 @@ -622,7 +622,7 @@ normal open, the first argument is I<NOT> a filehandle, even though it 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). @@ -687,7 +687,7 @@ matched "nothing". But it didn't really match nothing--rather, it 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. @@ -715,7 +715,7 @@ a hash key lookup: 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. @@ -768,7 +768,7 @@ except that it's more efficient, more concise, keeps track of the 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 @@ -813,7 +813,7 @@ Example: 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 @@ -847,7 +847,7 @@ as terminals may lose the end-of-file condition if you do. 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: @@ -889,7 +889,7 @@ error message. If there was no error, C<$@> is guaranteed to be a null 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. @@ -974,7 +974,7 @@ if the corresponding value is undefined. 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 @@ -1028,7 +1028,7 @@ OPERATION. Returns TRUE for success, FALSE on failure. Will produce a 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. @@ -1123,7 +1123,7 @@ that the C<~> and C<~~> tokens will treat the entire PICTURE as a single line. 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. @@ -1149,7 +1149,7 @@ single-characters, however. For that, try something more like: system "stty -cbreak </dev/tty >/dev/tty 2>&1"; } else { - system "stty", 'icanon', 'eol', '^@'; # ascii null + system "stty", 'icanon', 'eol', '^@'; # ASCII null } print "\n"; @@ -1317,7 +1317,7 @@ operator, except it's easier to use. =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: @@ -1372,7 +1372,7 @@ or equivalently, @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. @@ -1576,7 +1576,7 @@ it succeeded, FALSE otherwise. See example in L<perlipc/"Sockets: Client/Server 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 @@ -1586,7 +1586,7 @@ via my()"> for details. =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) = @@ -1598,7 +1598,7 @@ the range 0..6. If EXPR is omitted, does localtime(time). 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. @@ -1686,7 +1686,7 @@ an error. 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 @@ -1835,7 +1835,7 @@ parsimonious of file descriptors. For example: 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.) @@ -1881,7 +1881,7 @@ and however you leave that scope: } 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: @@ -1977,7 +1977,7 @@ point data written on one machine may not be readable on another - even if 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: @@ -2018,11 +2018,11 @@ Declares the compilation unit as being in the 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 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> @@ -2073,7 +2073,7 @@ if successful. FILEHANDLE may be a scalar variable name, in which case 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 @@ -2083,7 +2083,7 @@ subroutine that you call will have one or more of its expressions 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: @@ -2101,7 +2101,7 @@ of the list will be interpreted as the printf format. =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 @@ -2172,7 +2172,7 @@ directory. If there are no more entries, returns an undefined value in 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: $!"; @@ -2256,7 +2256,7 @@ See also L<perlref>. =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 @@ -2315,16 +2315,16 @@ variables and reset ?? searches so that they work again. The 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>. @@ -2405,7 +2405,7 @@ EOF on your read, and then sleep for a while, you might have to stick in a 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: @@ -2455,7 +2455,7 @@ methods, preferring to write the last example as: =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 = ''; @@ -2488,7 +2488,7 @@ or to block until something becomes ready just do this 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. @@ -2543,7 +2543,7 @@ See L<perlipc/"UDP: Message Passing"> for examples. 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. @@ -2613,7 +2613,7 @@ returns sine of $_. 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 @@ -2688,7 +2688,7 @@ Examples: @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; } @@ -2820,7 +2820,7 @@ characters at each point it matches that way. For example: 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); @@ -2888,9 +2888,9 @@ root of $_. =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. @@ -2919,13 +2919,13 @@ meaning of the fields: 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.) @@ -2938,7 +2938,7 @@ last stat or filetest are returned. Example: 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 @@ -2949,7 +2949,7 @@ doing many pattern matches on the string before it is next modified. 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 @@ -2994,7 +2994,7 @@ out the names of those files that contain a match: @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"; } @@ -3053,7 +3053,7 @@ like numbers. 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 @@ -3103,7 +3103,7 @@ Note that argument processing varies depending on the number of 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 @@ -3249,13 +3249,13 @@ If EXPR is omitted, uses $_. =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 @@ -3292,7 +3292,7 @@ If LIST is omitted, uses $_. 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: @@ -3391,12 +3391,12 @@ are also implemented this way. Currently implemented pragmas are: 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'; @@ -3428,10 +3428,10 @@ on the same array. See also keys(), each(), and sort(). =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; @@ -3464,7 +3464,7 @@ status is returned in C<$?>. If you say 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 diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 251d959e3a..0499401499 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -69,7 +69,7 @@ care what the length of the data is, use the global variable C<na>. Remember, 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*) @@ -155,7 +155,7 @@ call is not necessary. See the section on L<Mortality>. =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. @@ -170,11 +170,11 @@ pointer in an SV, you can use the following three macros instead: 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(); @@ -242,7 +242,7 @@ for you). The C<lval> parameter indicates whether this fetch is actually a 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. @@ -318,7 +318,7 @@ To determine if an SV is a reference, you can use the following macro: 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*)) @@ -396,7 +396,7 @@ certain extra features. Those bits are: "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 @@ -417,7 +417,7 @@ Most of the time, output from the C routine can be handled through use of 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: @@ -516,7 +516,7 @@ and back. =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. @@ -658,7 +658,7 @@ The first call creates a mortal SV, the second converts an existing SV to 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. @@ -835,7 +835,7 @@ the various routines for the various magical types begin with C<magic_>. 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 @@ -963,15 +963,15 @@ For more information, consult L<perlcall>. =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), @@ -1108,7 +1108,7 @@ Returns the highest index in the array. Returns -1 if the array is empty. 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)); @@ -1532,19 +1532,19 @@ memory is zeroed with C<memzero>. =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)); @@ -1552,28 +1552,28 @@ incremented. =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)); @@ -1583,7 +1583,7 @@ set to 1. If C<len> is zero then Perl will compute the length. 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)); @@ -1848,7 +1848,7 @@ C<SPAGAIN>. =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; @@ -1922,7 +1922,7 @@ ends. =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)); @@ -1977,13 +1977,13 @@ Set the length of the string which is in the SV. See C<SvCUR>. =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)); @@ -2016,7 +2016,7 @@ Use C<SvGROW>. =item sv_inc -Autoincrement of the value in the SV. +Auto increment of the value in the SV. void sv_inc _((SV* sv)); @@ -2124,7 +2124,7 @@ Returns a boolean indicating whether the value is an 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)); @@ -2254,19 +2254,19 @@ Returns a pointer to the string in the SV. The SV must contain a string. =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) @@ -2325,7 +2325,7 @@ Copies an integer into a new SV, optionally blessing the SV. The C<rv> 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)); @@ -2335,7 +2335,7 @@ Copies a double into a new SV, optionally blessing the SV. The C<rv> 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)); @@ -2346,7 +2346,7 @@ argument will be upgraded to an RV. That RV will be modified to point to 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)); @@ -2362,7 +2362,7 @@ string must be specified with C<n>. The C<rv> 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. +a reference count of 1. SV* sv_setref_pvn _((SV *rv, char *classname, char* pv, I32 n)); @@ -2448,7 +2448,7 @@ This is the C<undef> SV. Always refer to this as C<&sv_undef>. =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>. diff --git a/pod/perllol.pod b/pod/perllol.pod index c97aac918d..37adac7ef5 100644 --- a/pod/perllol.pod +++ b/pod/perllol.pod @@ -27,7 +27,7 @@ a declaration of the array: 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 @@ -144,10 +144,10 @@ you'd have to do something like this: 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 (<>) { @@ -155,7 +155,7 @@ for the 5.002 release.) } 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) { @@ -171,13 +171,13 @@ It doesn't matter whether those elements are already 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! @@ -187,17 +187,17 @@ to push() must be a real array, not just a reference to such. =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 @@ -231,7 +231,7 @@ sometimes is easier to take a temporary on your way through: } } -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]; @@ -266,7 +266,7 @@ That same loop could be replaced with a slice operation: 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++) { diff --git a/pod/perlmod.pod b/pod/perlmod.pod index 7cb3a4907e..e27d0f1a0f 100644 --- a/pod/perlmod.pod +++ b/pod/perlmod.pod @@ -13,11 +13,11 @@ Perl. The package statement declares the compilation unit as being in the 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: @@ -121,7 +121,7 @@ Assignment to a typeglob performs an aliasing operation, i.e., 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; @@ -143,7 +143,7 @@ thing. 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 @@ -197,7 +197,7 @@ order of definition; that is: last in, first out (LIFO). 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> @@ -299,7 +299,7 @@ the module. If so, these will be entirely transparent to the user of 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>. @@ -315,13 +315,13 @@ because it has a shotgun. 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 @@ -334,7 +334,7 @@ conversion, but it's just a mechanical process, so is far from bulletproof. =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: @@ -343,7 +343,7 @@ 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 @@ -388,11 +388,11 @@ restrict unsafe constructs =item subs -predeclare sub names +pre-declare sub names =item vars -predeclare global variable names +pre-declare global variable names =back @@ -745,7 +745,7 @@ dynamically loaded into Perl if and when you need them. Supported 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 @@ -944,7 +944,7 @@ scheme as the original author. 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; @@ -1021,7 +1021,7 @@ or nature of a variable. For example: $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. @@ -1039,11 +1039,11 @@ short or common names to reduce the risk of name clashes. 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 @@ -1056,8 +1056,8 @@ This name should be as descriptive, accurate and complete as 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 @@ -1137,7 +1137,7 @@ Copying, ToDo etc. =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. @@ -1146,7 +1146,7 @@ GPL and The Artistic License (see the files README, Copying and 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 @@ -1161,7 +1161,7 @@ Remember to include the other words in addition to the Copyright. 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. @@ -1178,7 +1178,7 @@ Usenet newsgroup. This will at least ensure very wide once-off 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 diff --git a/pod/perlobj.pod b/pod/perlobj.pod index 691ce8b9ee..aebdb72746 100644 --- a/pod/perlobj.pod +++ b/pod/perlobj.pod @@ -44,7 +44,7 @@ constructor: 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: @@ -94,17 +94,17 @@ object into: 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 = {}; @@ -118,7 +118,7 @@ operated on the object and not on the reference. =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 @@ -143,7 +143,7 @@ supplied in the UNIVERSAL class; see L<"Default UNIVERSAL methods"> for 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 @@ -163,9 +163,9 @@ the two C++ method types they most closely resemble.) 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: @@ -224,7 +224,7 @@ Indirect object method calls are parsed using the same rule as list 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) @@ -246,8 +246,8 @@ call, being sure to pass the requisite first argument explicitly: $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: @@ -255,13 +255,13 @@ 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 @@ -344,9 +344,9 @@ your class. It will automatically be called at the appropriate moment, 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. @@ -367,7 +367,7 @@ are equivalent, but AB and CD are different: =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. @@ -413,7 +413,7 @@ When an interpreter thread finally shuts down (usually when your program 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 @@ -462,7 +462,7 @@ garbage collector reaching the unreachable. 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. diff --git a/pod/perlop.pod b/pod/perlop.pod index 5645234bf4..f836576c5a 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -43,7 +43,7 @@ In the following sections, these operators are covered in precedence order. =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 @@ -66,7 +66,7 @@ the commas on the right of the sort are evaluated before the sort, but 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. @@ -88,7 +88,7 @@ Also parsed as terms are the C<do {}> and C<eval {}> constructs, as 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 @@ -104,16 +104,16 @@ containing the method name, and the left side must either be an object (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: @@ -123,7 +123,7 @@ 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 @@ -134,7 +134,7 @@ internally.) =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 @@ -144,7 +144,7 @@ starts with a plus or minus, a string starting with the opposite sign 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 @@ -167,7 +167,7 @@ supposed to be searched, substituted, or translated instead of the default $_. 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>.) @@ -185,7 +185,7 @@ Binary "%" computes the modulus of the two numbers. 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 @@ -389,7 +389,7 @@ As a list operator: @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'); @@ -506,14 +506,14 @@ It's the equivalent of "!" except for the very low precedence. 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. @@ -540,7 +540,7 @@ Type casting operator. =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 @@ -587,13 +587,13 @@ pattern from the variables. If this is not what you want, use C<\Q> to 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 @@ -602,7 +602,7 @@ matching and related activities. 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. @@ -622,10 +622,10 @@ L<perlre>. 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. @@ -649,7 +649,7 @@ successfully executed regular expression is used instead. 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. @@ -673,7 +673,7 @@ Examples: 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 @@ -759,13 +759,13 @@ made. Otherwise it returns false (specifically, the empty string). 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. @@ -773,20 +773,20 @@ 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 @@ -829,10 +829,10 @@ Examples: 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 @@ -852,10 +852,10 @@ with the corresponding character in the replacement list. It returns 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: @@ -920,7 +920,7 @@ an eval(): =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 @@ -933,7 +933,7 @@ of C<$?>). Unlike in B<csh>, no translation is done on the return 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.) @@ -989,9 +989,9 @@ is equivalent to the following Perl-like pseudo code: 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<$.>) @@ -1018,7 +1018,7 @@ this it will assume you are processing another @ARGV list, and if you 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; @@ -1055,11 +1055,11 @@ machine.) Of course, the shortest way to do the above is: 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 @@ -1126,5 +1126,5 @@ The bitwise operators ("&", "|", "^", "~", "<<", and ">>") always 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. diff --git a/pod/perlpod.pod b/pod/perlpod.pod index 3722e2c36c..dcf615daa3 100644 --- a/pod/perlpod.pod +++ b/pod/perlpod.pod @@ -94,10 +94,10 @@ here and in commands: 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 @@ -117,7 +117,7 @@ to look like paragraphs (block format), so that they stand out 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. diff --git a/pod/perlre.pod b/pod/perlre.pod index c4dbac63c6..c395250e01 100644 --- a/pod/perlre.pod +++ b/pod/perlre.pod @@ -5,7 +5,7 @@ perlre - Perl regular expressions =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>. @@ -22,7 +22,7 @@ Do case-insensitive pattern matching. =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 @@ -45,7 +45,7 @@ The C</x> modifier itself needs a little more explanation. It tells 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, @@ -63,7 +63,7 @@ See L<Version 8 Regular Expressions> for details. 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) @@ -71,8 +71,8 @@ meanings: () 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 @@ -102,7 +102,7 @@ as a regular character.) The "*" modifier is equivalent to C<{0,}>, the "+" 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 @@ -117,7 +117,7 @@ Note that the meanings don't change, just the "gravity": {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) @@ -154,8 +154,8 @@ Perl defines the following zero-width assertions: \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 @@ -175,13 +175,13 @@ outside the current pattern, this should not be relied upon. See the 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.) @@ -203,9 +203,9 @@ You will note that all backslashed metacharacters in Perl are 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; @@ -217,8 +217,8 @@ is to say /$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: @@ -268,7 +268,7 @@ easier just to say: 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"; @@ -390,11 +390,10 @@ As you see, this can be a bit tricky. It's important to realize that a 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"; @@ -421,12 +420,12 @@ This prints 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 @@ -437,7 +436,7 @@ in the hope of matching the complete regular expression. 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. @@ -477,10 +476,10 @@ it would take literally forever--or until you ran out of stack space. 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. @@ -492,13 +491,13 @@ in the list. Within a list, the "-" character is used to specify a 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 @@ -513,14 +512,14 @@ start and end. Note however that "|" is interpreted as a literal with 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. diff --git a/pod/perlref.pod b/pod/perlref.pod index 5303c3a12a..93198eafec 100644 --- a/pod/perlref.pod +++ b/pod/perlref.pod @@ -9,7 +9,7 @@ structures, because all references had to be symbolic, and even that was 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. @@ -25,7 +25,7 @@ references to objects that have been officially "blessed" into a class package.) 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. @@ -44,7 +44,7 @@ References can be constructed several ways. 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: @@ -167,7 +167,7 @@ newprint() I<despite> the fact that the "my $x" has seemingly gone out of 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. @@ -186,7 +186,7 @@ named new(), but don't have to be: =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. @@ -282,7 +282,7 @@ subscripted expressions: 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: @@ -348,7 +348,7 @@ reference is pointing to. See L<perlfunc>. 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. @@ -447,7 +447,7 @@ subscripting a hash. So now, instead of writing $array{ "aaa" }{ "bbb" }{ "ccc" } -you can just write +you can write just $array{ aaa }{ bbb }{ ccc } @@ -464,7 +464,7 @@ makes it more than a bareword: $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 diff --git a/pod/perlrun.pod b/pod/perlrun.pod index c69a03eb53..78e902a594 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -33,7 +33,7 @@ Contained in the file specified by the first filename on the command line. =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. @@ -47,7 +47,7 @@ embedded in a larger message. (In this case you would indicate the end 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. @@ -109,7 +109,7 @@ can say this: 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> @@ -133,7 +133,7 @@ An alternate delimiter may be specified using B<-F>. 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> @@ -151,10 +151,10 @@ Devel::DProf profiler. See L<perldebug>. =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 @@ -330,7 +330,7 @@ the implicit loop, just as in awk. =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".) @@ -365,7 +365,7 @@ script if necessary. After Perl locates the script, it parses the 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 @@ -419,7 +419,7 @@ Prints to STDOUT the value of the named configuration variable. 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. @@ -432,8 +432,8 @@ garbage will be discarded until the first line that starts with #! and 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). diff --git a/pod/perlsec.pod b/pod/perlsec.pod index facddedfbf..6101d798c2 100644 --- a/pod/perlsec.pod +++ b/pod/perlsec.pod @@ -17,7 +17,7 @@ Perl automatically enables a set of special security checks, called I<taint 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. @@ -33,7 +33,7 @@ You may not use data derived from outside your program to affect something 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 @@ -102,9 +102,9 @@ taintedness. Instead, the slightly more efficient and conservative 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 @@ -123,7 +123,7 @@ or a dot. 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 @@ -156,7 +156,7 @@ prevent stupid mistakes, not to remove the need for thought. 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 @@ -168,11 +168,11 @@ environment variables, umasks, current working directories, back to the 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 diff --git a/pod/perlstyle.pod b/pod/perlstyle.pod index 46c17ddae3..734b9ad032 100644 --- a/pod/perlstyle.pod +++ b/pod/perlstyle.pod @@ -32,7 +32,7 @@ Opening curly on same line as keyword, if possible, otherwise line up. =item * -Space before the opening curly of a multiline BLOCK. +Space before the opening curly of a multi-line BLOCK. =item * @@ -64,7 +64,7 @@ Uncuddled elses. =item * -No space between function name and its opening paren. +No space between function name and its opening parenthesis. =item * @@ -76,7 +76,7 @@ Long lines broken after an operator (except "and" and "or"). =item * -Space after last paren matching on current line. +Space after last parenthesis matching on current line. =item * @@ -117,7 +117,7 @@ is better than $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 @@ -135,7 +135,7 @@ schmuck bounce on the % key in B<vi>. 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 * @@ -189,7 +189,7 @@ Package names are sometimes an exception to this rule. Perl informally 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 * @@ -216,9 +216,9 @@ Don't use slash as a delimiter when your regexp has slashes or backslashes. =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 * diff --git a/pod/perlsub.pod b/pod/perlsub.pod index 1c3a3c0709..da8d00b4a2 100644 --- a/pod/perlsub.pod +++ b/pod/perlsub.pod @@ -22,8 +22,8 @@ To import subroutines: 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 @@ -105,7 +105,7 @@ Use array assignment to a local list to name your formal arguments: } 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 @@ -150,7 +150,7 @@ flat. So all you have managed to do here is stored everything in @a and 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 @@ -190,7 +190,7 @@ A "my" declares the listed variables to be confined (lexically) to the 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. @@ -226,11 +226,11 @@ change whether those variables is viewed as a scalar or an array. So 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; @@ -282,7 +282,7 @@ but not beyond it. 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 @@ -328,8 +328,8 @@ lexical of the same name is also visible: 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 @@ -341,7 +341,7 @@ variable containing an anonymous sub reference: &$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. @@ -370,7 +370,7 @@ If this function is being sourced in from a separate file 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: @@ -412,7 +412,7 @@ within that block>. A local() just gives temporary values to global 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 @@ -449,7 +449,7 @@ as a scalar or an array. So 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>; @@ -466,7 +466,7 @@ Sometimes you don't want to pass the value of an array to a subroutine 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. @@ -492,7 +492,7 @@ the equivalent reference mechanism) to push, pop or change the size of 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">. @@ -534,9 +534,9 @@ list of keys occurring in all the hashes passed to it: 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. @@ -546,7 +546,7 @@ Where people get into trouble is here: 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. @@ -581,7 +581,7 @@ It turns out that you can actually do this also: 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 @@ -591,7 +591,7 @@ As of the 5.002 release of perl, if you declare 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 @@ -600,10 +600,10 @@ this rule that prototypes have no influence on subroutine references 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. @@ -644,7 +644,7 @@ A semicolon separates mandatory arguments from optional arguments. 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; @@ -674,7 +674,7 @@ That prints "unphooey". (Yes, there are still unresolved 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: @@ -715,23 +715,23 @@ returning a list: 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'; @@ -739,7 +739,7 @@ via the import syntax, and these names may then override the builtin ones: 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. @@ -784,7 +784,7 @@ should just call system() with those arguments. All you'd do is this: 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); diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod index b0f77f4149..9cf39a3d5a 100644 --- a/pod/perlsyn.pod +++ b/pod/perlsyn.pod @@ -35,7 +35,7 @@ take effect at compile time. Typically all the declarations are put at 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 @@ -63,7 +63,7 @@ The only kind of simple statement is an expression evaluated for its 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. @@ -91,7 +91,7 @@ can write loops like: } 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. @@ -128,7 +128,7 @@ all do the same 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. @@ -322,7 +322,7 @@ do it: 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. @@ -496,7 +496,7 @@ and your documentation text freely, as in ......... } -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 diff --git a/pod/perltie.pod b/pod/perltie.pod index 7c4314188a..962a7e31d1 100644 --- a/pod/perltie.pod +++ b/pod/perltie.pod @@ -13,8 +13,8 @@ perltie - how to hide an object class in a simple variable =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. @@ -38,7 +38,7 @@ such as might be passed to the dbminit() function of C.) The object 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. @@ -105,8 +105,8 @@ variable C<$^W> to see whether to emit a bit of noise anyway. 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. @@ -160,7 +160,7 @@ argument--the new value the user is trying to assign. =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. @@ -173,7 +173,7 @@ 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. @@ -253,7 +253,7 @@ As you may have noticed, the name of the FETCH method (et al.) is the same 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 @@ -303,8 +303,8 @@ value pairs. FIRSTKEY and NEXTKEY implement the keys() and each() 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, @@ -313,8 +313,8 @@ C<undef>. The two possibilities can be tested with the C<exists()> and 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; @@ -323,7 +323,7 @@ contents. For example: $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: @@ -347,7 +347,7 @@ whose dot files this object represents =item HOME -where those dotfiles live +where those dot files live =item CLOBBER @@ -355,7 +355,7 @@ whether we should try to change or remove those dot files =item LIST -the hash of dotfile names and content mappings +the hash of dot file names and content mappings =back @@ -367,7 +367,7 @@ Here's the start of F<Dotfiles.pm>: 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. @@ -413,7 +413,7 @@ Here's the constructor: 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 @@ -445,7 +445,7 @@ Here's the fetch for our DotFiles example. 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 @@ -526,14 +526,14 @@ the caller whether the file was successfully deleted. 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}}) { @@ -574,8 +574,8 @@ second argument which is the last key that had been accessed. This is 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; @@ -680,7 +680,7 @@ You cannot easily tie a multilevel data structure (such as a hash of 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. diff --git a/pod/perltoc.pod b/pod/perltoc.pod index 7c16f94edc..2821fa363a 100644 --- a/pod/perltoc.pod +++ b/pod/perltoc.pod @@ -6,7 +6,7 @@ perltoc - perl documentation table of contents =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 @@ -144,7 +144,7 @@ HOME, LOGDIR, PATH, PERL5LIB, PERL5DB, PERLLIB =item The Arrow Operator -=item Autoincrement and Autodecrement +=item Auto-increment and Auto-decrement =item Exponentiation @@ -215,10 +215,10 @@ HOME, LOGDIR, PATH, PERL5LIB, PERL5DB, PERLLIB 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'>, @@ -1748,7 +1748,7 @@ C<overload::Method(obj,op)> -=head2 sigtrap - Perl pragma to enable stack backtrace on unexpected +=head2 sigtrap - Perl pragma to enable stack back-trace on unexpected signals =item SYNOPSIS @@ -1773,7 +1773,7 @@ C<strict refs>, C<strict vars>, C<strict subs> -=head2 subs - Perl pragma to predeclare sub names +=head2 subs - Perl pragma to pre-declare sub names =item SYNOPSIS @@ -1784,7 +1784,7 @@ C<strict refs>, C<strict vars>, C<strict subs> -=head2 vars - Perl pragma to predeclare global variable names +=head2 vars - Perl pragma to pre-declare global variable names =item SYNOPSIS @@ -2167,7 +2167,7 @@ maybe_command_in_dirs, maybe_command, perl_script 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, @@ -3157,8 +3157,8 @@ TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this =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 diff --git a/pod/perltrap.pod b/pod/perltrap.pod index e85f5c9007..1c0f7a420c 100644 --- a/pod/perltrap.pod +++ b/pod/perltrap.pod @@ -101,8 +101,8 @@ basically incompatible with C.) =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.) @@ -231,18 +231,18 @@ Sharp shell programmers should take note of the following: =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 * @@ -275,16 +275,16 @@ context than they do in a scalar one. See L<perldata> for details. =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 * @@ -296,7 +296,7 @@ you might expect to do not. =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>) { } @@ -419,7 +419,7 @@ for C<$_> itself (and C<@_>, etc.). =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 "; @@ -652,9 +652,9 @@ Formatted output and significant digits =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; @@ -795,7 +795,7 @@ The behavior is slightly different for: 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"; @@ -953,8 +953,8 @@ now works as a C programmer would expect. 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); @@ -1055,8 +1055,8 @@ Also see L<Numerical Traps> for another example of this new feature. =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`; @@ -1187,7 +1187,7 @@ on the handler _not_ being reset will have to be reworked. =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. diff --git a/pod/perlvar.pod b/pod/perlvar.pod index b0e2cf319f..42910e1c4f 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -7,7 +7,7 @@ perlvar - Perl predefined variables =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 @@ -51,7 +51,7 @@ a reference, you'll raise a run-time exception. The default input and pattern-searching space. The following pairs are equivalent: - while (<>) {...} # only equivalent in while! + while (<>) {...} # equivalent in only while! while ($_ = <>) {...} /^Subject:/ @@ -108,7 +108,7 @@ test. Note that outside of a C<while> test, this will not happen. =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. @@ -162,12 +162,12 @@ This variable is 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. @@ -182,7 +182,7 @@ 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 @@ -221,8 +221,8 @@ delimit line boundaries when quoting poetry.) 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 @@ -239,8 +239,8 @@ has no effect on input buffering. =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.) @@ -254,9 +254,9 @@ 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 @@ -379,7 +379,7 @@ poetry is a part of a line.) =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 @@ -396,7 +396,7 @@ L<perlfunc/formline()>. =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, @@ -418,7 +418,7 @@ all the usual caveats. (This means that you shouldn't depend on the 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?) @@ -429,7 +429,7 @@ 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. @@ -481,7 +481,7 @@ The effective uid of this process. Example: ($<,$>) = ($>,$<); # 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 @@ -510,9 +510,9 @@ which may be the same as the first number. (Mnemonic: parentheses are 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 @@ -637,7 +637,7 @@ contains the name of the current file when reading from E<lt>E<gt>. 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 @@ -647,8 +647,8 @@ be evaluated by the C<do EXPR>, C<require>, or C<use> constructs. It 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; @@ -684,7 +684,7 @@ signals. Example: $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!! diff --git a/pod/perlxs.pod b/pod/perlxs.pod index 6a898a5331..9108342c1f 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -560,7 +560,7 @@ the following statement. =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 @@ -631,7 +631,7 @@ other C<XSRETURN> macros. 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 @@ -664,7 +664,7 @@ terminate the code block. =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. @@ -680,7 +680,7 @@ To disable version checking: =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. diff --git a/pod/perlxstut.pod b/pod/perlxstut.pod index 0c6cf3fb22..501a34845e 100644 --- a/pod/perlxstut.pod +++ b/pod/perlxstut.pod @@ -10,8 +10,8 @@ L<perlxs>. 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 @@ -63,7 +63,7 @@ Some systems may have installed Perl version 5 as "perl5". =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. @@ -227,7 +227,7 @@ Now re-run make to rebuild our new shared library. 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" @@ -446,7 +446,7 @@ section on the argument stack. =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. @@ -577,7 +577,7 @@ and add the following lines to the end of the script: 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) @@ -607,7 +607,7 @@ C<constant> routine. 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. @@ -620,12 +620,12 @@ processed at all by h2xs. There is no good solution to this right now. =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. @@ -696,7 +696,7 @@ Sometimes you might want to provide some extra methods or subroutines 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 |