perlpod Perl plain old documentation
perlbook Perl book information
- perlembed Perl how to embed perl in your C or C++ app
+ perlembed Perl how to embed perl in your C or C++ application
perlapio Perl internal IO abstraction interface
perlxs Perl XS application programming interface
perlxstut Perl XS tutorial
returned as being a list with only one element. Any other items that
were returned will not exist by the time control returns from the
I<perl_call_*> function. The section I<Returning a list in a scalar
-context> shows an example of this behaviour.
+context> shows an example of this behavior.
=head2 G_ARRAY
=back
-See I<Using G_EVAL> for details of using G_EVAL.
+See I<Using G_EVAL> for details on using G_EVAL.
=head2 G_KEEPERR
pushed onto the stack. In this case we are pushing a string and an
integer.
-See the L<perlguts/"XSUBs and the Argument Stack"> for details
+See L<perlguts/"XSUBs and the Argument Stack"> for details
on how the XPUSH macros work.
=item 6.
I<perl_call_pv> call.
If you are making use of the Perl stack pointer in your code you must
-always refresh the your local copy using SPAGAIN whenever you make use
+always refresh the local copy using SPAGAIN whenever you make use
of the I<perl_call_*> functions or any other Perl internal function.
=item 4.
Value 1 = 3
In this case the main point to note is that only the last item in the
-list returned from the subroutine, I<Adder> actually made it back to
+list is returned from the subroutine, I<AddSubtract> actually made it back to
I<call_AddSubScalar>.
...
event handler --> perl_call --> perl
|
- event handler <-- perl_call --<--+
+ event handler <-- perl_call <----+
...
event handler --> perl_call --> perl
|
- event handler <-- perl_call --<--+
+ event handler <-- perl_call <----+
...
event handler --> perl_call --> perl
|
- event handler <-- perl_call --<--+
+ event handler <-- perl_call <----+
In this case the flow of control can consist of only the repeated
sequence
event handler --> perl_call --> perl
-for the practically the complete duration of the program. This means
+for practically the complete duration of the program. This means
that control may I<never> drop back to the surrounding scope in Perl at
the extreme left.
Here's a line
or two.
THIS
- and here another.
+ and here's another.
THAT
Just don't forget that you have to put a semicolon on the end
assigns the value of variable bar to variable foo. Note that the value
of an actual array in a scalar context is the length of the array; the
-following assigns to $foo the value 3:
+following assigns the value 3 to $foo:
@foo = ('cc', '-E', $bar);
$foo = @foo; # $foo gets 3
-You may have an optional comma before the closing parenthesis of an
+You may have an optional comma before the closing parenthesis of a
list literal, so that you can say:
@foo = (
array had been interpolated at that point.
A list value may also be subscripted like a normal array. You must
-put the list in parentheses to avoid ambiguity. Examples:
+put the list in parentheses to avoid ambiguity. For example:
# Stat returns list value.
$time = (stat($file))[8];
there isn't a current block. Note that an "if" or "else" block doesn't
count as a "loopish" block, as doesn't a block given to sort(). You can
usually double the curlies to get the same effect though, because the inner
-curlies will be considered a block that loops once. See L<perlfunc/last>.
+curlies will be considered a block that loops once. See L<perlfunc/next>.
=item Can't "redo" outside a block
there isn't a current block. Note that an "if" or "else" block doesn't
count as a "loopish" block, as doesn't a block given to sort(). You can
usually double the curlies to get the same effect though, because the inner
-curlies will be considered a block that loops once. See L<perlfunc/last>.
+curlies will be considered a block that loops once. See L<perlfunc/redo>.
=item Can't bless non-reference value
=item Can't break at that line
-(S) A warning intended for while running within the debugger, indicating
+(S) A warning intended to only be printed while running within the debugger, indicating
the line number specified wasn't the location of a statement that could
be stopped at.
=item No command into which to pipe on command line
(F) An error peculiar to VMS. Perl handles its own command line redirection,
-and found a '|' at the end of the command line, so it doesn't know whither you
+and found a '|' at the end of the command line, so it doesn't know where you
want to pipe the output from this command.
=item No DB::DB routine defined
(F) An error peculiar to VMS. Perl handles its own command line redirection,
and found a lone 'E<gt>' at the end of the command line, so it doesn't know
-whither you wanted to redirect stdout.
+where you wanted to redirect stdout.
=item No output file after E<gt> or E<gt>E<gt> on command line
=item Script is not setuid/setgid in suidperl
-(F) Oddly, the suidperl program was invoked on a script with its setuid
-or setgid bit not set. This doesn't make much sense.
+(F) Oddly, the suidperl program was invoked on a script without a setuid
+or setgid bit set. This doesn't make much sense.
=item Search pattern not terminated
=item seek() on unopened file
(W) You tried to use the seek() function on a filehandle that was either
-never opened or has been closed since.
+never opened or has since been closed.
=item select not implemented
=item Stat on unopened file E<lt>%sE<gt>
(W) You tried to use the stat() function (or an equivalent file test)
-on a filehandle that was either never opened or has been closed since.
+on a filehandle that was either never opened or has since been closed.
=item Statement unlikely to be reached
=item tell() on unopened file
(W) You tried to use the tell() function on a filehandle that was either
-never opened or has been closed since.
+never opened or has since been closed.
=item Test on unopened file E<lt>%sE<gt>
(W) A file operation was attempted on a filename, and that operation
failed, PROBABLY because the filename contained a newline, PROBABLY
-because you forgot to chop() or chomp() it off. See L<perlfunc/chop>.
+because you forgot to chop() or chomp() it off. See L<perlfunc/chomp>.
=item Unsupported directory function "%s" called
Perl has a mechanism to help you generate simple reports and charts. To
facilitate this, Perl helps you code up your output page
close to how it will look when it's printed. It can keep
-track of things like how many lines on a page, what page you're on, when to
+track of things like how many lines are on a page, what page you're on, when to
print page headers, etc. Keywords are borrowed from FORTRAN:
format() to declare and write() to execute; see their entries in
L<perlfunc>. Fortunately, the layout is much more legible, more like
.
If name is omitted, format "STDOUT" is defined. FORMLIST consists of
-a sequence of lines, each of which may be of one of three types:
+a sequence of lines, each of which may be one of three types:
=over 4
by checking $FORMAT_LINES_LEFT before each write() and print the footer
yourself if necessary.
-Here's another strategy; open a pipe to yourself, using C<open(MESELF, "|-")>
-(see L<perlfunc/open()>) and always write() to MESELF instead of
+Here's another strategy; open a pipe to yourself, using C<open(MYSELF, "|-")>
+(see L<perlfunc/open()>) and always write() to MYSELF instead of
STDOUT. Have your child process massage its STDIN to rearrange
headers and footers however you like. Not very convenient, but doable.
Furthermore, when called from within the DB package, caller returns more
detailed information: it sets the list variable @DB::args to be the
-arguments with which that subroutine was invoked.
+arguments with which the subroutine was invoked.
=item chdir EXPR
does nothing but return the value of C<$x>. (Case 4 is preferred for
purely visual reasons, but it also has the advantage of compiling at
compile-time instead of at run-time.) Case 5 is a place where
-normally you I<WOULD> like to use double quotes, except that in that
+normally you I<WOULD> like to use double quotes, except that in this
particular situation, you can just use symbolic references instead, as
in case 6.
There is no built-in import() function. It is merely an ordinary
method (subroutine) defined (or inherited) by modules that wish to export
names to another module. The use() function calls the import() method
-for the package used. See also L</use>, L<perlmod>, and L<Exporter>.
+for the package used. See also L</use()>, L<perlmod>, and L<Exporter>.
=item index STR,SUBSTR,POSITION
of the filehandle. The values for WHENCE are 0 to set the file pointer to
POSITION, 1 to set the it to current plus POSITION, and 2 to set it to EOF
plus offset. You may use the values SEEK_SET, SEEK_CUR, and SEEK_END for
-this from POSIX module. Returns 1 upon success, 0 otherwise.
+this from the POSIX module. Returns 1 upon success, 0 otherwise.
On some systems you have to do a seek whenever you switch between reading
and writing. Amongst other things, this may have the effect of calling
An OFFSET may be specified to write the data from some part of the
string other than the beginning. A negative OFFSET specifies writing
-from that many bytes counting backwards from the end of the string.
+that many bytes counting backwards from the end of the string.
=item tell FILEHANDLE
=item undef
-Undefines the value of EXPR, which must be an lvalue. Use on only a
-scalar value, an entire array or hash, or a subroutine name (using
+Undefines the value of EXPR, which must be an lvalue. Use only on a
+scalar value, an entire array, an entire hash, 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 the EXPR, in which case
Writes a formatted record (possibly multi-line) to the specified file,
using the format associated with that file. By default the format for
-a file is the one having the same name is the filehandle, but the
+a file is the one having the same name as the filehandle, but the
format for the current output channel (see the select() function) may be set
explicitly by assigning the name of the format to the C<$~> variable.
overridden, and multiple instances of the same type of magic can be
associated with an SV.
-The C<name> and C<namlem> arguments are used to associate a string with
-the magic, typically the name of a variable. C<namlem> is stored in the
-C<mg_len> field and if C<name> is non-null and C<namlem> >= 0 a malloc'd
+The C<name> and C<namlen> arguments are used to associate a string with
+the magic, typically the name of a variable. C<namlen> is stored in the
+C<mg_len> field and if C<name> is non-null and C<namlen> >= 0 a malloc'd
copy of the name is stored in C<mg_ptr> field.
The sv_magic function uses C<how> to determine which, if any, predefined
effect, though the first is more efficient because it does the symbol
table lookups at compile time:
- local(*main::foo) = *main::bar; local($main::{'foo'}) =
- $main::{'bar'};
+ local(*main::foo) = *main::bar;
+ local($main::{'foo'}) = $main::{'bar'};
You can use this to print out all the variables in a package, for
instance. Here is F<dumpvar.pl> from the Perl library:
=head2 Extension Modules
-Extension modules are written in C (or a mix of Perl and C) and get
+Extension modules are written in C (or a mix of Perl and C) and may be
+statically linked or in general are
dynamically loaded into Perl if and when you need them. Supported
extension modules include the Socket, Fcntl, and POSIX modules.
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, because the referenced object itself knows that
-it has been blessed, and its reference to it could have been returned
+it has been blessed, and the reference to it could have been returned
directly, like this:
sub new {
other postfix dereference in the language. The left side of -E<gt> is not so
limited, because it's an infix operator, not a postfix operator.
-That means that below, A and B are equivalent to each other, and C and D
-are equivalent, but AB and CD are different:
+That means that in the following, A and B are equivalent to each other, and
+C and D are equivalent, but A/B and C/D are different:
A: method $obref->{"fieldname"}
B: (method $obref)->{"fieldname"}
=head2 Terms and List Operators (Leftward)
-Any TERM is of highest precedence of Perl. These includes variables,
+A TERM has the highest precedence in Perl. They includes variables,
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
In the absence of parentheses, the precedence of list operators such as
C<print>, C<sort>, or C<chmod> is either very high or very low depending on
-whether you look at the left side of operator or the right side of it.
+whether you are looking at the left side or the right side of the operator.
For example, in
@ary = (1, 3, sort 4, 2);
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,
+string specified with =~ must be a scalar variable, an array element, a
+hash element,
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
to integral values less than 65536.
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
-causing the pattern to fail. If you want it to match the minimum number
-of times possible, follow the quantifier with a "?" after any of them.
-Note that the meanings don't change, just the "gravity":
+many times as possible while still allowing the rest of the pattern to match.
+If you want to match the minimum number of times possible, follow the
+quantifier with a "?". Note that the meanings don't change, just the
+"gravity":
*? Match 0 or more times
+? Match 1 or more times
everything in Perl is an object, but we usually reserve the word for
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 contains merely the name of a file.
The C<*glob> notation is a kind of symbolic reference. Hard references
as a scalar. It doesn't magically start being an array or a hash
unless you tell it so explicitly by dereferencing it.
-References can be constructed several ways.
+References can be constructed in several ways.
=over 4
=item 1.
By using the backslash operator on a variable, subroutine, or value.
-(This works much like the & (address-of) operator works in C.) Note
+(This works much like the & (address-of) operator in C.) Note
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
$arrayref = [1, 2, ['a', 'b', 'c']];
Here we've constructed a reference to an anonymous array of three elements
-whose final element is itself reference to another anonymous array of three
+whose final element is itself a reference to another anonymous array of three
elements. (The multidimensional syntax described later can be used to
access this. For example, after the above, C<$arrayref-E<gt>[2][1]> would have
the value "b".)
In human terms, it's a funny way of passing arguments to a subroutine when
you define it as well as when you call it. It's useful for setting up
little bits of code to run later, such as callbacks. You can even
-do object-oriented stuff with it, though Perl provides a different
-mechanism to do that already--see L<perlobj>.
+do object-oriented stuff with it, though Perl already provides a different
+mechanism to do that--see L<perlobj>.
You can also think of closure as a way to write a subroutine template without
using eval. (In fact, in version 5.000, eval was the I<only> way to get
scans for the first line starting with #! and containing the word
"perl", and starts there instead. This is useful for running a script
embedded in a larger message. (In this case you would indicate the end
-of the script using the __END__ token.)
+of the script using the C<__END__> token.)
The #! line is always examined for switches as the line is being
parsed. Thus, if you're on a machine that allows only one argument
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
-subroutine (prototyped to take one scalar parameter) without defining it by saying just:
+subroutine without defining it by just saying:
- sub myname ($);
+ sub myname;
$me = myname $0 or die "can't get myname";
-Note that it functions as a list operator though, not as a unary
-operator, so be careful to use C<or> instead of C<||> there.
+Though note that it functions as a list operator, not as a unary
+operator, so be sure to use C<or> instead of C<||> in this case.
Subroutines declarations can also be loaded up with the C<require> statement
or both loaded and imported into your namespace with a C<use> statement.
use English;
-allows you to refer to special variables (like $RS) as
-though they were in B<awk>; see L<perlvar> for details.
+allows you to refer to special variables (like $/ ($RS)) with their
+B<awk> equivalent; see L<perlvar> for details.
=item *
=item *
Reading an input line does not split it for you. You get to split it
-yourself to an array. And the split() operator has different
-arguments.
+to an array yourself. And the split() operator has different
+arguments than B<awk>'s.
=item *
Note that warning messages are not collected in this variable. You can,
however, set up a routine to process warnings by setting C<$SIG{__WARN__}>
-below.
+as described below.
=item $PROCESS_ID
=head2 The NO_INIT Keyword
The NO_INIT keyword is used to indicate that a function
-parameter is being used as only an output value. The B<xsubpp>
+parameter is being used only as an output value. The B<xsubpp>
compiler will normally generate code to read the values of
all function parameters from the argument stack and assign
them to C variables upon entry to the function. NO_INIT
before the function terminates.
The following example shows a variation of the rpcb_gettime() function.
-This function uses the timep variable as only an output variable and does
+This function uses the timep variable only as an output variable and does
not care about its initial contents.
bool_t
projects / p5sagit/p5-mst-13.2.git / commitdiff