Change 25748: [PATCH] POD index entries with X<>
[email protected] (Rafael Garcia-Suarez) Thu, 13 Oct 2005 04:58:55 -0700
| Newsgroups | perl.perlfaq.workers,perl.perl5.changes |
|---|---|
| Message-ID | <[email protected]> |
Change 25748 by rgs@bloom on 2005/10/13 11:20:23 Subject: [PATCH] POD index entries with X<> From: Ivan Tubert-Brohman <[email protected]> Date: Wed, 12 Oct 2005 19:20:18 -0400 Message-ID: <[email protected]> Affected files ... ... //depot/perl/pod/perldata.pod#54 edit ... //depot/perl/pod/perldebug.pod#57 edit ... //depot/perl/pod/perldsc.pod#14 edit ... //depot/perl/pod/perlfaq5.pod#62 edit ... //depot/perl/pod/perlfaq6.pod#52 edit ... //depot/perl/pod/perlform.pod#13 edit ... //depot/perl/pod/perlfunc.pod#497 edit ... //depot/perl/pod/perllexwarn.pod#27 edit ... //depot/perl/pod/perlmod.pod#38 edit ... //depot/perl/pod/perlobj.pod#30 edit ... //depot/perl/pod/perlop.pod#132 edit ... //depot/perl/pod/perlpod.pod#21 edit ... //depot/perl/pod/perlre.pod#91 edit ... //depot/perl/pod/perlref.pod#28 edit ... //depot/perl/pod/perlrun.pod#140 edit ... //depot/perl/pod/perlsub.pod#59 edit ... //depot/perl/pod/perlsyn.pod#50 edit ... //depot/perl/pod/perltie.pod#42 edit Differences ... ==== //depot/perl/pod/perldata.pod#54 (text) ==== Index: perl/pod/perldata.pod --- perl/pod/perldata.pod#53~24493~ Tue May 17 08:55:38 2005 +++ perl/pod/perldata.pod Thu Oct 13 04:20:23 2005 @@ -5,6 +5,7 @@ =head1 DESCRIPTION =head2 Variable names +X<variable, name> X<variable name> X<data type> X<type> Perl has three built-in data types: scalars, arrays of scalars, and associative arrays of scalars, known as "hashes". A scalar is a @@ -27,6 +28,7 @@ for a simple identifier, an expression that produces a reference to the value at runtime. This is described in more detail below and in L<perlref>. +X<identifier> Perl also has its own built-in variables whose names don't follow these rules. They have strange names so they don't accidentally @@ -36,11 +38,13 @@ In addition, several special variables that provide windows into the inner working of Perl have names containing punctuation characters and control characters. These are documented in L<perlvar>. +X<variable, built-in> Scalar values are always named with '$', even when referring to a scalar that is part of an array or a hash. The '$' symbol works semantically like the English word "the" in that it indicates a single value is expected. +X<scalar> $days # the simple scalar value "days" $days[28] # the 29th element of array @days @@ -50,12 +54,14 @@ Entire arrays (and slices of arrays and hashes) are denoted by '@', which works much like the word "these" or "those" does in English, in that it indicates multiple values are expected. +X<array> @days # ($days[0], $days[1],... $days[n]) @days[3,4,5] # same as ($days[3],$days[4],$days[5]) @days{'a','c'} # same as ($days{'a'},$days{'c'}) Entire hashes are denoted by '%': +X<hash> %days # (key1, val1, key2, val2 ...) @@ -72,6 +78,7 @@ 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. +X<namespace> Because variable references always start with '$', '@', or '%', the "reserved" words aren't in fact reserved with respect to variable @@ -83,6 +90,8 @@ from conflict with future reserved words. Case I<is> significant--"FOO", "Foo", and "foo" are all different names. Names that start with a letter or underscore may also contain digits and underscores. +X<identifier, case sensitivity> +X<case> It is possible to replace such an alphanumeric name with an expression that returns a reference to the appropriate type. For a description @@ -96,6 +105,7 @@ id.) =head2 Context +X<context> X<scalar context> X<list context> The interpretation of operations and values in Perl sometimes depends on the requirements of the context around the operation or value. @@ -148,6 +158,7 @@ context. =head2 Scalar values +X<scalar> X<number> X<string> X<reference> All data in Perl is a scalar, an array of scalars, or a hash of scalars. A scalar may contain one single value in any of three @@ -172,6 +183,7 @@ the null string or the number 0 (or its string equivalent, "0"). The Boolean context is just a special kind of scalar context where no conversion to a string or a number is ever performed. +X<boolean> X<bool> X<true> X<false> X<truth> There are actually two varieties of null strings (sometimes referred to as "empty" strings), a defined one and an undefined one. The @@ -186,6 +198,7 @@ use the defined() operator to determine whether a scalar value is defined (this has no meaning on arrays or hashes), and the undef() operator to produce an undefined value. +X<defined> X<undefined> X<undef> X<null> X<string, null> To find out whether a given string is a valid non-zero number, it's sometimes enough to test it against both numeric 0 and also lexical @@ -220,6 +233,7 @@ an array that was previously shortened does not recover values that were in those elements. (It used to do so in Perl 4, but we had to break this to make sure destructors were called when expected.) +X<$#> X<array, length> You can also gain some minuscule measure of efficiency by pre-extending an array that is going to get big. You can also extend an array @@ -235,6 +249,7 @@ the last value, like the C comma operator, nor of built-in functions, which return whatever they feel like returning.) The following is always true: +X<array, length> scalar(@whatever) == $#whatever - $[ + 1; @@ -242,6 +257,7 @@ 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 assume that +X<$[> scalar(@whatever) == $#whatever + 1; @@ -262,6 +278,7 @@ 10,000 of your items. This isn't supposed to happen. If a tied hash is evaluated in scalar context, a fatal error will result, since this bucket usage information is currently not available for tied hashes. +X<hash, scalar context> X<hash, bucket> X<bucket> You can preallocate space for a hash by assigning to the keys() function. This rounds up the allocated buckets to the next power of two: @@ -269,6 +286,7 @@ keys(%users) = 1000; # allocate 1024 buckets =head2 Scalar value constructors +X<scalar, literal> X<scalar, constant> Numeric literals are specified in any of the following floating point or integer formats: @@ -287,6 +305,7 @@ between digits for legibility. You could, for example, group binary digits by threes (as for a Unix-style mode argument such as 0b110_100_100) or by fours (to represent nibbles, as in 0b1010_0110) or in other groups. +X<number, literal> String literals are usually delimited by either single or double quotes. They work much like quotes in the standard Unix shells: @@ -295,6 +314,7 @@ C<\\>). The usual C-style backslash rules apply for making characters such as newline, tab, etc., as well as some more exotic forms. See L<perlop/"Quote and Quote-like Operators"> for a list. +X<string, literal> Hexadecimal, octal, or binary, representations in string literals (e.g. '0xff') are not automatically converted to their integer @@ -310,6 +330,7 @@ names beginning with $ or @, followed by an optional bracketed expression as a subscript.) The following code segment prints out "The price is $Z<>100." +X<interpolation> $Price = '$100'; # not interpolated print "The price is $Price.\n"; # interpolated @@ -322,6 +343,7 @@ this when interpolating a variable into a string to separate the variable name from a following double-colon or an apostrophe, since these would be otherwise treated as a package separator: +X<interpolation> $who = "Larry"; print PASSWD "${who}::0:0:Superuser:/:/bin/perl\n"; @@ -341,6 +363,7 @@ equivalent to C<$version{2}++>, not to C<$version{'2.0'}++>. =head3 Version Strings +X<version string> X<vstring> X<v-string> B<Note:> Version Strings (v-strings) have been deprecated. They will be removed in some future release after Perl 5.8.1. The marginal @@ -375,6 +398,8 @@ be v-strings always. =head3 Special Literals +X<special literal> X<__END__> X<__DATA__> X<END> X<DATA> +X<end> X<data> X<^D> X<^Z> The special literals __FILE__, __LINE__, and __PACKAGE__ represent the current filename, line number, and package name at that @@ -382,6 +407,7 @@ will not be interpolated into strings. If there is no current package (due to an empty C<package;> directive), __PACKAGE__ is the undefined value. +X<__FILE__> X<__LINE__> X<__PACKAGE__> X<line> X<file> X<package> The two control characters ^D and ^Z, and the tokens __END__ and __DATA__ may be used to indicate the logical end of the script before the actual @@ -404,6 +430,7 @@ __DATA__ (or __END__) token has not yet been seen. =head3 Barewords +X<bareword> A word that has no other interpretation in the grammar will be treated as if it were a quoted string. These are known as @@ -422,6 +449,7 @@ by saying C<no strict 'subs'>. =head3 Array Joining Delimiter +X<array, interpolation> X<interpolation, array> X<$"> Arrays and slices are interpolated into double-quoted strings by joining the elements with the delimiter specified in the C<$"> @@ -448,6 +476,7 @@ L<perlop/Quote and Quote-like Operators>. =head2 List value constructors +X<list> List values are denoted by separating individual values by commas (and enclosing the list in parentheses where precedence requires it): @@ -660,6 +689,7 @@ print "Darwin's First Name is ", $scientists{"Darwin"}, "\n"; =head2 Slices +X<slice> X<array, slice> X<hash, slice> A common way to access an array or a hash is one scalar element at a time. You can also subscript a list to get a single element from it. @@ -736,6 +766,7 @@ scalar) or a plural one (a list). =head2 Typeglobs and Filehandles +X<typeglob> X<filehandle> X<*> Perl uses an internal type called a I<typeglob> to hold an entire symbol table entry. The type prefix of a typeglob is a C<*>, because ==== //depot/perl/pod/perldebug.pod#57 (text) ==== Index: perl/pod/perldebug.pod --- perl/pod/perldebug.pod#56~25253~ Mon Aug 1 01:13:10 2005 +++ perl/pod/perldebug.pod Thu Oct 13 04:20:23 2005 @@ -1,4 +1,5 @@ =head1 NAME +X<debug> X<debugger> perldebug - Perl debugging @@ -19,6 +20,7 @@ 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: +X<-d> $ perl -d -e 42 @@ -59,6 +61,7 @@ =over 12 =item h +X<debugger command, h> Prints out a summary help message @@ -80,6 +83,7 @@ =item p expr +X<debugger command, p> Same as C<print {$DB::OUT} expr> in the current package. In particular, because this is just Perl's own C<print> function, this means that nested @@ -89,6 +93,7 @@ where STDOUT may be redirected to. =item x [maxdepth] expr +X<debugger command, x> Evaluates its expression in list context and dumps out the result in a pretty-printed fashion. Nested data structures are printed out @@ -104,6 +109,7 @@ temporarily set to I<N>. =item V [pkg [vars]] +X<debugger command, V> Display all (or some) variables in package (defaulting to C<main>) using a data pretty-printer (hashes show their keys and values so @@ -118,10 +124,12 @@ This is similar to calling the C<x> command on each applicable var. =item X [vars] +X<debugger command, X> Same as C<V currentpackage [vars]>. =item y [level [vars]] +X<debugger command, y> Display all (or some) lexical variables (mnemonic: C<mY> variables) in the current scope or I<level> scopes higher. You can limit the @@ -132,16 +140,19 @@ controlled by the same options. =item T +X<debugger command, T> X<backtrace> X<stack, backtrace> Produce a stack backtrace. See below for details on its output. =item s [expr] +X<debugger command, s> X<step> Single step. Executes until the beginning of another statement, descending into subroutine calls. If an expression is supplied that includes function calls, it too will be single-stepped. =item n [expr] +X<debugger command, n> Next. Executes over subroutine calls, until the beginning of the next statement. If an expression is supplied that includes @@ -149,6 +160,7 @@ each statement. =item r +X<debugger command, r> Continue until the return from the current subroutine. Dump the return value if the C<PrintRet> option is set (default). @@ -158,11 +170,13 @@ Repeat last C<n> or C<s> command. =item c [line|sub] +X<debugger command, c> Continue, optionally inserting a one-time-only breakpoint at the specified line or subroutine. =item l +X<debugger command, l> List next window of lines. @@ -184,19 +198,23 @@ be a variable that contains a code reference. =item - +X<debugger command, -> List previous window of lines. =item v [line] +X<debugger command, v> View a few lines of code around the current line. =item . +X<debugger command, .> Return the internal debugger pointer to the line last executed, and print out that line. =item f filename +X<debugger command, f> Switch to viewing a different file or C<eval> statement. If I<filename> is not a full pathname found in the values of %INC, it is considered @@ -219,27 +237,35 @@ The search is case-insensitive by default. =item L [abw] +X<debugger command, L> List (default all) actions, breakpoints and watch expressions =item S [[!]regex] +X<debugger command, S> List subroutine names [not] matching the regex. =item t +X<debugger command, t> Toggle trace mode (see also the C<AutoTrace> option). =item t expr +X<debugger command, t> Trace through execution of C<expr>. See L<perldebguts/"Frame Listing Output Examples"> for examples. =item b +X<breakpoint> +X<debugger command, b> Sets breakpoint on current line =item b [line] [condition] +X<breakpoint> +X<debugger command, b> Set a breakpoint before the given line. If a condition is specified, it's evaluated each time the statement is reached: a @@ -252,34 +278,47 @@ b 33 /pattern/i =item b subname [condition] +X<breakpoint> +X<debugger command, b> Set a breakpoint before the first line of the named subroutine. I<subname> may be a variable containing a code reference (in this case I<condition> is not supported). =item b postpone subname [condition] +X<breakpoint> +X<debugger command, b> Set a breakpoint at first line of subroutine after it is compiled. =item b load filename +X<breakpoint> +X<debugger command, b> Set a breakpoint before the first executed line of the I<filename>, which should be a full pathname found amongst the %INC values. =item b compile subname +X<breakpoint> +X<debugger command, b> Sets a breakpoint before the first statement executed after the specified subroutine is compiled. =item B line +X<breakpoint> +X<debugger command, B> Delete a breakpoint from the specified I<line>. =item B * +X<breakpoint> +X<debugger command, B> Delete all installed breakpoints. =item a [line] command +X<debugger command, a> Set an action to be done before the line is executed. If I<line> is omitted, set an action on the line about to be executed. @@ -297,39 +336,48 @@ a 53 print "DB FOUND $foo\n" =item A line +X<debugger command, A> Delete an action from the specified line. =item A * +X<debugger command, A> Delete all installed actions. =item w expr +X<debugger command, w> Add a global watch-expression. We hope you know what one of these is, because they're supposed to be obvious. =item W expr +X<debugger command, W> Delete watch-expression =item W * +X<debugger command, W> Delete all watch-expressions. =item o +X<debugger command, o> Display all options =item o booloption ... +X<debugger command, o> Set each listed Boolean option to the value C<1>. =item o anyoption? ... +X<debugger command, o> Print out the value of one or more options. =item o option=value ... +X<debugger command, o> Set the value of one or more options. If the value has internal whitespace, it should be quoted. For example, you could set C<o @@ -350,28 +398,34 @@ for a list of these. =item < ? +X<< debugger command, < >> List out all pre-prompt Perl command actions. =item < [ command ] +X<< debugger command, < >> Set an action (Perl command) to happen before every debugger prompt. A multi-line command may be entered by backslashing the newlines. =item < * +X<< debugger command, < >> Delete all pre-prompt Perl command actions. =item << command +X<< debugger command, << >> Add an action (Perl command) to happen before every debugger prompt. A multi-line command may be entered by backwhacking the newlines. =item > ? +X<< debugger command, > >> List out post-prompt Perl command actions. =item > command +X<< debugger 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 multi-line @@ -379,16 +433,19 @@ couldn't've guessed this by now). =item > * +X<< debugger command, > >> Delete all post-prompt Perl command actions. =item >> command +X<<< debugger 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 multi-line command may be entered by backslashing the newlines. =item { ? +X<debugger command, {> List out pre-prompt debugger commands. @@ -403,28 +460,34 @@ C<do { ... }>. =item { * +X<debugger command, {> Delete all pre-prompt debugger commands. =item {{ command +X<debugger command, {{> Add an action (debugger command) to happen before every debugger prompt. A multi-line command may be entered, if you can guess how: see above. =item ! number +X<debugger command, !> Redo a previous command (defaults to the previous command). =item ! -number +X<debugger command, !> Redo number'th previous command. =item ! pattern +X<debugger command, !> Redo last command that started with pattern. See C<o recallCommand>, too. =item !! cmd +X<debugger command, !!> Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See C<o shellBang>, also. Note that the user's current shell (well, @@ -433,16 +496,20 @@ information. =item source file +X<debugger command, source> Read and execute debugger commands from I<file>. I<file> may itself contain C<source> commands. =item H -number +X<debugger command, H> Display last n commands. Only commands longer than one character are listed. If I<number> is omitted, list them all. =item q or ^D +X<debugger command, q> +X<debugger command, ^D> Quit. ("quit" doesn't work for this, unless you've made an alias) This is the only supported way to exit the debugger, though typing @@ -453,6 +520,7 @@ if you want to step through global destruction. =item R +X<debugger command, R> Restart the debugger by C<exec()>ing a new session. We try to maintain your history across this, but internal settings and command-line options @@ -463,14 +531,17 @@ options B<-w>, B<-I>, and B<-e>. =item |dbcmd +X<debugger command, |> Run the debugger command, piping DB::OUT into your current pager. =item ||dbcmd +X<debugger command, ||> Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well. =item = [alias value] +X<debugger command, => Define a command alias, like @@ -485,17 +556,20 @@ Perl debugger, use a leading semicolon, too. =item m expr +X<debugger command, m> List which methods may be called on the result of the evaluated expression. The expression may evaluated to a reference to a blessed object, or to a package name. =item M +X<debugger command, M> Displays all loaded modules and their versions =item man [manpage] +X<debugger command, man> Despite its name, this calls your system's default documentation viewer on the given page, or on the viewer itself if I<manpage> is @@ -528,11 +602,14 @@ =over 12 =item C<recallCommand>, C<ShellBang> +X<debugger option, recallCommand> +X<debugger option, ShellBang> The characters used to recall command or spawn shell. By default, both are set to C<!>, which is unfortunate. =item C<pager> +X<debugger option, pager> Program to use for output of pager-piped commands (those beginning with a C<|> character.) By default, C<$ENV{PAGER}> will be used. @@ -542,10 +619,13 @@ will not be readable when sent through the pager. =item C<tkRunning> +X<debugger option, tkRunning> Run Tk while prompting (with ReadLine). =item C<signalLevel>, C<warnLevel>, C<dieLevel> +X<debugger option, signalLevel> X<debugger option, warnLevel> +X<debugger option, dieLevel> Level of verbosity. By default, the debugger leaves your exceptions and warnings alone, because altering them can break correctly running @@ -566,11 +646,13 @@ destroy any program that takes its exception handling seriously. =item C<AutoTrace> +X<debugger option, AutoTrace> Trace mode (similar to C<t> command, but can be put into C<PERLDB_OPTS>). =item C<LineInfo> +X<debugger option, LineInfo> File or pipe to print line number info to. If it is a pipe (say, C<|visual_perl_db>), then a short message is used. This is the @@ -579,14 +661,17 @@ debugger. =item C<inhibit_exit> +X<debugger option, inhibit_exit> If 0, allows I<stepping off> the end of the script. =item C<PrintRet> +X<debugger option, PrintRet> Print return value after C<r> command if set (default). =item C<ornaments> +X<debugger option, ornaments> Affects screen appearance of the command line (see L<Term::ReadLine>). There is currently no way to disable these, which can render @@ -594,6 +679,7 @@ This is considered a bug. =item C<frame> +X<debugger option, frame> Affects the printing of messages upon entry and exit from subroutines. If C<frame & 2> is false, messages are printed on entry only. (Printing @@ -608,11 +694,13 @@ next option: =item C<maxTraceLen> +X<debugger option, maxTraceLen> Length to truncate the argument list when the C<frame> option's bit 4 is set. =item C<windowSize> +X<debugger option, windowSize> Change the size of code list window (default is 10 lines). @@ -624,36 +712,45 @@ =over 12 =item C<arrayDepth>, C<hashDepth> +X<debugger option, arrayDepth> X<debugger option, hashDepth> Print only first N elements ('' for all). =item C<dumpDepth> +X<debugger option, dumpDepth> Limit recursion depth to N levels when dumping structures. Negative values are interpreted as infinity. Default: infinity. =item C<compactDump>, C<veryCompact> +X<debugger option, compactDump> X<debugger option, veryCompact> Change the style of array and hash output. If C<compactDump>, short array may be printed on one line. =item C<globPrint> +X<debugger option, globPrint> Whether to print contents of globs. =item C<DumpDBFiles> +X<debugger option, DumpDBFiles> Dump arrays holding debugged files. =item C<DumpPackages> +X<debugger option, DumpPackages> Dump symbol tables of packages. =item C<DumpReused> +X<debugger option, DumpReused> Dump contents of "reused" addresses. =item C<quote>, C<HighBit>, C<undefPrint> +X<debugger option, quote> X<debugger option, HighBit> +X<debugger option, undefPrint> Change the style of string dump. The default value for C<quote> is C<auto>; one can enable double-quotish or single-quotish format @@ -661,6 +758,7 @@ with their high bit set are printed verbatim. =item C<UsageOnly> +X<debugger option, UsageOnly> Rudimentary per-package memory usage dump. Calculates total size of strings found in variables in the package. This does not @@ -685,10 +783,12 @@ =over 12 =item C<TTY> +X<debugger option, TTY> The TTY to use for debugging I/O. =item C<noTTY> +X<debugger option, noTTY> If set, the debugger goes into C<NonStop> mode and will not connect to a TTY. If interrupted (or if control goes to the debugger via explicit setting of @@ -705,11 +805,13 @@ possible. =item C<ReadLine> +X<debugger option, ReadLine> If false, readline support in the debugger is disabled in order to debug applications that themselves use ReadLine. =item C<NonStop> +X<debugger option, NonStop> If set, the debugger goes into non-interactive mode until interrupted, or programmatically by setting $DB::signal or $DB::single. @@ -792,6 +894,7 @@ commands typed into the debugger. =item Stack backtrace +X<backtrace> X<stack, backtrace> Here's an example of what a stack backtrace via C<T> command might look like: @@ -968,6 +1071,7 @@ your Perl as a C programmer might. =head2 The Perl Profiler +X<profile> X<profiling> X<profiler> If you wish to supply an alternative debugger for Perl to run, just invoke your script with a colon and a package argument given to the @@ -984,6 +1088,8 @@ interpret the information in that profile. =head1 Debugging regular expressions +X<regular expression, debugging> +X<regex, debugging> X<regexp, debugging> C<use re 'debug'> enables you to see the gory details of how the Perl regular expression engine works. In order to understand this typically @@ -994,6 +1100,7 @@ L<perldebguts/"Debugging regular expressions">. =head1 Debugging memory usage +X<memory usage> Perl contains internal support for reporting its own memory usage, but this is a fairly advanced concept that requires some understanding ==== //depot/perl/pod/perldsc.pod#14 (text) ==== Index: perl/pod/perldsc.pod --- perl/pod/perldsc.pod#13~12954~ Mon Nov 12 06:50:44 2001 +++ perl/pod/perldsc.pod Thu Oct 13 04:20:23 2005 @@ -1,4 +1,5 @@ =head1 NAME +X<data structure> X<complex data structure> X<struct> perldsc - Perl Data Structures Cookbook @@ -68,6 +69,7 @@ these types of data structures. =head1 REFERENCES +X<reference> X<dereference> X<dereferencing> X<pointer> The most important thing to understand about all data structures in Perl -- including multidimensional arrays--is that even though they might @@ -75,6 +77,7 @@ 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. +X<multidimensional array> X<array, multidimensional> You can't use a reference to an array or hash in quite the same way that you would a real array or hash. For C or C++ programmers unused to @@ -174,6 +177,7 @@ memory. In Perl, you'll want to use the array constructor C<[]> or the hash constructor C<{}> instead. Here's the right way to do the preceding broken code fragments: +X<[]> X<{}> for $i (1..10) { @array = somefunc($i); @@ -248,9 +252,11 @@ =head1 CAVEAT ON PRECEDENCE +X<dereference, precedence> X<dereferencing, precedence> Speaking of things like C<@{$AoA[$i]}>, the following are actually the same thing: +X<< -> >> $aref->[2][2] # clear $$aref[2][2] # confusing @@ -298,6 +304,10 @@ print $aref->[2][2] =head1 DEBUGGING +X<data structure, debugging> X<complex data structure, debugging> +X<AoA, debugging> X<HoA, debugging> X<AoH, debugging> X<HoH, debugging> +X<array of arrays, debugging> X<hash of arrays, debugging> +X<array of hashes, debugging> X<hash of hashes, debugging> Before version 5.002, the standard Perl debugger didn't do a very nice job of printing out complex data structures. With 5.002 or above, the @@ -331,6 +341,7 @@ types of data structures. =head1 ARRAYS OF ARRAYS +X<array of arrays> X<AoA> =head2 Declaration of an ARRAY OF ARRAYS @@ -387,6 +398,7 @@ } =head1 HASHES OF ARRAYS +X<hash of arrays> X<HoA> =head2 Declaration of a HASH OF ARRAYS @@ -465,6 +477,7 @@ } =head1 ARRAYS OF HASHES +X<array of hashes> X<AoH> =head2 Declaration of an ARRAY OF HASHES @@ -555,6 +568,7 @@ } =head1 HASHES OF HASHES +X<hass of hashes> X<HoH> =head2 Declaration of a HASH OF HASHES @@ -673,6 +687,7 @@ =head1 MORE ELABORATE RECORDS +X<record> X<structure> X<struct> =head2 Declaration of MORE ELABORATE RECORDS ==== //depot/perl/pod/perlfaq5.pod#62 (text) ==== Index: perl/pod/perlfaq5.pod --- perl/pod/perlfaq5.pod#61~25301~ Wed Aug 17 08:57:09 2005 +++ perl/pod/perlfaq5.pod Thu Oct 13 04:20:23 2005 @@ -8,6 +8,7 @@ formats, and footers. =head2 How do I flush/unbuffer an output filehandle? Why must I do this? +X<flush> X<buffer> X<unbuffer> X<autoflush> Perl does not support truly unbuffered output (except insofar as you can C<syswrite(OUT, $char, 1)>), although it @@ -61,11 +62,13 @@ $sock->autoflush(); =head2 How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file? +X<file, editing> Use the Tie::File module, which is included in the standard distribution since Perl 5.8.0. =head2 How do I count the number of lines in a file? +X<file, counting lines> X<lines> X<line> One fairly efficient way is to count newlines in the file. The following program uses a feature of tr///, as documented in L<perlop>. @@ -82,6 +85,7 @@ This assumes no funny games with newline translations. =head2 How can I use Perl's C<-i> option from within a program? +X<-i> X<in-place> C<-i> sets the value of Perl's C<$^I> variable, which in turn affects the behavior of C<< <> >>; see L<perlrun> for more details. By @@ -107,6 +111,7 @@ C<.c.orig> file. =head2 How can I copy a file? +X<copy> X<file, copy> (contributed by brian d foy) @@ -123,6 +128,7 @@ to the destination file as you read the original. =head2 How do I make a temporary file name? +X<file, temporary> If you don't need to know the name of the file, you can use C<open()> with C<undef> in place of the file name. The C<open()> function @@ -175,6 +181,7 @@ } =head2 How can I manipulate fixed-record-length files? +X<fixed-length> X<file, fixed-length records> The most efficient way is using L<pack()|perlfunc/"pack"> and L<unpack()|perlfunc/"unpack">. This is faster than using @@ -206,6 +213,7 @@ with global variables and using symbolic references. =head2 How can I make a filehandle local to a subroutine? How do I pass filehandles between subroutines? How do I make an array of filehandles? +X<filehandle, local> X<filehandle, passing> X<filehandle, reference> As of perl5.6, open() autovivifies file and directory handles as references if you pass it an uninitialized scalar variable. @@ -234,6 +242,7 @@ check out the Symbol or IO::Handle modules. =head2 How can I use a filehandle indirectly? +X<filehandle, indirect> An indirect filehandle is using something other than a symbol in a place that a filehandle is expected. Here are ways @@ -329,15 +338,18 @@ game doesn't help you at all here. =head2 How can I set up a footer format to be used with write()? +X<footer> There's no builtin way to do this, but L<perlform> has a couple of techniques to make it possible for the intrepid hacker. =head2 How can I write() into a string? +X<write, into a string> See L<perlform/"Accessing Formatting Internals"> for an swrite() function. =head2 How can I output my numbers with commas added? +X<number, commify> (contributed by brian d foy and Benjamin Goldberg) @@ -373,6 +385,7 @@ )/$1,/xg; =head2 How can I translate tildes (~) in a filename? +X<tilde> X<tilde expansion> Use the <> (glob()) operator, documented in L<perlfunc>. Older versions of Perl require that you have a shell installed that groks @@ -395,6 +408,7 @@ }ex; =head2 How come when I open a file read-write it wipes it out? +X<clobber> X<read-write> X<clobbering> X<truncate> X<truncating> Because you're using something like this, which truncates the file and I<then> gives you read-write access: @@ -468,6 +482,7 @@ See also the new L<perlopentut> if you have it (new for 5.6). =head2 Why do I sometimes get an "Argument list too long" when I use E<lt>*E<gt>? +X<argument list too long> The C<< <> >> operator performs a globbing operation (see above). In Perl versions earlier than v5.6.0, the internal glob() operator forks @@ -481,6 +496,7 @@ one that doesn't use the shell to do globbing. =head2 Is there a leak/bug in glob()? +X<glob> Due to the current implementation on some operating systems, when you use the glob() function or its angle-bracket alias in a scalar @@ -488,6 +504,7 @@ best therefore to use glob() only in list context. =head2 How can I open a file with a leading ">" or trailing blanks? +X<filename, special characters> (contributed by Brian McCauley) @@ -504,6 +521,7 @@ open FILE, ">", ">file"; # filename is ">file" =head2 How can I reliably rename a file? +X<rename> X<mv> X<move> X<file, rename> X<ren> If your operating system supports a proper mv(1) utility or its functional equivalent, this works: @@ -519,6 +537,7 @@ Newer versions of File::Copy export a move() function. =head2 How can I lock a file? +X<lock> X<file, lock> X<flock> Perl's builtin flock() function (see L<perlfunc> for details) will call flock(2) if that exists, fcntl(2) if it doesn't (on perl version 5.004 and @@ -566,6 +585,7 @@ =back =head2 Why can't I just open(FH, "E<gt>file.lock")? +X<lock, lockfile race condition> A common bit of code B<NOT TO USE> is this: @@ -585,6 +605,7 @@ these tend to involve busy-wait, which is also subdesirable. =head2 I still don't get locking. I just want to increment the number in the file. How can I do this? +X<counter> X<file, counter> Didn't anyone ever tell you web-page hit counters were useless? They don't count number of hits, they're a waste of time, and they serve @@ -609,6 +630,7 @@ If the count doesn't impress your friends, then the code might. :-) =head2 All I want to do is append a small amount of text to the end of a file. Do I still have to use locking? +X<append> X<file, append> If you are on a system that correctly implements flock() and you use the example appending code from "perldoc -f flock" everything will be OK @@ -637,6 +659,7 @@ systems where this probability is reduced to zero. =head2 How do I randomly update a binary file? +X<file, binary patch> If you're just trying to patch a binary, in many cases something as simple as this works: @@ -660,6 +683,7 @@ Don't forget them or you'll be quite sorry. =head2 How do I get a file's timestamp in perl? +X<timestamp> X<file, timestamp> If you want to retrieve the time at which the file was last read, written, or had its meta-data (owner, etc) changed, @@ -693,6 +717,7 @@ for details. =head2 How do I set a file's timestamp in perl? +X<timestamp> X<file, timestamp> You use the utime() function documented in L<perlfunc/utime>. By way of example, here's a little program that copies the @@ -718,6 +743,7 @@ the filesystems, not of utime(). =head2 How do I print to more than one file at once? +X<print, to multiple files> To connect one filehandle to several output filehandles, you can use the IO::Tee or Tie::FileHandle::Multiplex modules. @@ -728,6 +754,7 @@ for $fh (FH1, FH2, FH3) { print $fh "whatever\n" } =head2 How can I read in an entire file all at once? +X<slurp> X<file, slurping> You can use the File::Slurp module to do it in one step. @@ -781,6 +808,7 @@ and reads that many bytes into the buffer $var. =head2 How can I read in a file by paragraphs? +X<file, reading by paragraphs> Use the C<$/> variable (see L<perlvar> for details). You can either set it to C<""> to eliminate empty paragraphs (C<"abc\n\n\n\ndef">, @@ -791,6 +819,7 @@ S<C<"fred\n \nstuff\n\n">> is one paragraph, but C<"fred\n\nstuff\n\n"> is two. =head2 How can I read a single character from a file? From the keyboard? +X<getc> X<file, reading one character at a time> You can use the builtin C<getc()> function for most filehandles, but it won't (easily) work on a terminal device. For STDIN, either use @@ -922,6 +951,7 @@ pipes, and tty devices work, but I<not> files. =head2 How do I do a C<tail -f> in perl? +X<tail> First try @@ -950,6 +980,7 @@ There's also a File::Tail module from CPAN. =head2 How do I dup() a filehandle in Perl? +X<dup> If you check L<perlfunc/open>, you'll see that several of the ways to call open() should do the trick. For example: @@ -970,6 +1001,7 @@ Error checking, as always, has been left as an exercise for the reader. =head2 How do I close a file descriptor by number? +X<file, closing file descriptors> This should rarely be necessary, as the Perl close() function is to be used for things that Perl opened itself, even if it was a dup of a @@ -989,6 +1021,7 @@ } =head2 Why can't I use "C:\temp\foo" in DOS paths? Why doesn't `C:\temp\foo.exe` work? +X<filename, DOS issues> Whoops! You just put a tab and a formfeed into that filename! Remember that within double quoted strings ("like\this"), the @@ -1005,6 +1038,7 @@ are more portable, too. =head2 Why doesn't glob("*.*") get all the files? +X<glob> Because even on non-Unix ports, Perl's glob function follows standard Unix globbing semantics. You'll need C<glob("*")> to get all (non-hidden) @@ -1027,6 +1061,7 @@ the permissions of the file govern whether you're allowed to. =head2 How do I select a random line from a file? +X<file, selecting a random line> Here's an algorithm from the Camel Book: ==== //depot/perl/pod/perlfaq6.pod#52 (text) ==== Index: perl/pod/perlfaq6.pod --- perl/pod/perlfaq6.pod#51~25301~ Wed Aug 17 08:57:09 2005 +++ perl/pod/perlfaq6.pod Thu Oct 13 04:20:23 2005 @@ -13,6 +13,8 @@ a number/whole/integer/float", to be precise). =head2 How can I hope to use regular expressions without creating illegible and unmaintainable code? +X<regex, legibility> X<regexp, legibility> +X<regular expression, legibility> X</x> Three techniques can make regular expressions maintainable and understandable. @@ -69,6 +71,7 @@ =back =head2 I'm having trouble matching over more than one line. What's wrong? +X<regex, multiline> X<regexp, multiline> X<regular expression, multiline> Either you don't have more than one line in the string you're looking at (probably), or else you aren't using the correct modifier(s) on @@ -121,6 +124,7 @@ } =head2 How can I pull out lines between two patterns that are themselves on different lines? +X<..> You can use Perl's somewhat exotic C<..> operator (documented in L<perlop>): @@ -146,6 +150,8 @@ } =head2 I put a regular expression into $/ but it didn't work. What's wrong? +X<$/, regexes in> X<$INPUT_RECORD_SEPARATOR, regexes in> +X<$RS, regexes in> Up to Perl 5.8.0, $/ has to be a string. This may change in 5.10, but don't get your hopes up. Until then, you can use these examples @@ -189,6 +195,8 @@ =head2 How do I substitute case insensitively on the LHS while preserving case on the RHS? +X<replace, case preserving> X<substitute, case preserving> +X<substitution, case preserving> X<s, case preserving> Here's a lovely Perlish solution by Larry Rosler. It exploits properties of bitwise xor on ASCII strings. @@ -278,6 +286,7 @@ } =head2 How can I make C<\w> match national character sets? +X<\w> Put C<use locale;> in your script. The \w character class is taken from the current locale. @@ -285,6 +294,7 @@ See L<perllocale> for details. =head2 How can I match a locale-smart version of C</[a-zA-Z]/>? +X<alpha> You can use the POSIX character class syntax C</[[:alpha:]]/> documented in L<perlre>. @@ -296,6 +306,7 @@ the digits and the underscore, or C</[\W\d_]/>. =head2 How can I quote a variable to use in a regex? +X<regex, escaping> X<regexp, escaping> X<regular expression, escaping> The Perl parser will expand $variable and @variable references in regular expressions unless the delimiter is a single quote. Remember, @@ -326,6 +337,7 @@ regular character, so that C<P.> matches a C<P> followed by a dot. =head2 What is C</o> really for? +X</o> Using a variable in a regular expression match forces a re-evaluation (and perhaps recompilation) each time the regular expression is @@ -414,6 +426,8 @@ s#/\*[^*]*\*+([^/*][^*]*\*+)*/|//[^\n]*|("(\\.|[^"\\])*"|'(\\.|[^'\\])*'|.[^/"'\\]*)#defined $2 ? $2 : ""#gse; =head2 Can I use Perl regular expressions to match balanced text? +X<regex, matching balanced test> X<regexp, matching balanced test> +X<regular expression, matching balanced test> Historically, Perl regular expressions were not capable of matching balanced text. As of more recent versions of perl including 5.6.1 @@ -442,6 +456,7 @@ but they are undocumented. =head2 What does it mean that regexes are greedy? How can I get around it? +X<greedy> X<greediness> Most people mean that greedy regexes match as much as they can. Technically speaking, it's actually the quantifiers (C<?>, C<*>, C<+>, @@ -462,6 +477,7 @@ playing hot potato. =head2 How do I process each word on each line? +X<word> Use the split function: @@ -513,10 +529,13 @@ sort a hash (optionally by value instead of key)?". =head2 How can I do approximate matching? +X<match, approximate> X<matching, approximate> See the module String::Approx available from CPAN. =head2 How do I efficiently match many regular expressions at once? +X<regex, efficiency> X<regexp, efficiency> +X<regular expression, efficiency> ( contributed by brian d foy ) @@ -572,6 +591,7 @@ expressions, you can tune them for individual situations. =head2 Why don't word-boundary searches with C<\b> work for me? +X<\b> (contributed by brian d foy) @@ -629,6 +649,7 @@ =head2 Why does using $&, $`, or $' slow my program down? +X<$MATCH> X<$&> X<$POSTMATCH> X<$'> X<$PREMATCH> X<$`> (contributed by Anno Siegel) @@ -649,6 +670,7 @@ string copying. =head2 What good is C<\G> in a regular expression? +X<\G> You use the C<\G> anchor to start the next match on the same string where the last match left off. The regular @@ -742,6 +764,7 @@ pattern. =head2 Are Perl regexes DFAs or NFAs? Are they POSIX compliant? +X<DFA> X<NFA> X<POSIX> While it's true that Perl's regular expressions resemble the DFAs (deterministic finite automata) of the egrep(1) program, they are in @@ -755,6 +778,7 @@ L<perlfaq2>). =head2 What's wrong with using grep in a void context? +X<grep> The problem is that grep builds a return list, regardless of the context. This means you're making Perl go to the trouble of building a list that @@ -767,6 +791,8 @@ context, no lists are constructed. =head2 How can I match strings with multibyte characters? +X<regex, and multibyte characters> X<regexp, and multibyte characters> +X<regular expression, and multibyte characters> Starting from Perl 5.6 Perl has had some level of multibyte character support. Perl 5.8 or later is recommended. Supported multibyte ==== //depot/perl/pod/perlform.pod#13 (text) ==== Index: perl/pod/perlform.pod --- perl/pod/perlform.pod#12~22161~ Fri Jan 16 05:29:26 2004 +++ perl/pod/perlform.pod Thu Oct 13 04:20:23 2005 @@ -1,4 +1,5 @@ =head1 NAME +X<format> X<report> X<chart> perlform - Perl formats @@ -12,6 +13,7 @@ to execute; see their entries in L<perlfunc>. Fortunately, the layout is much more legible, more like BASIC's PRINT USING statement. Think of it as a poor man's nroff(1). +X<nroff> Formats, like packages and subroutines, are declared rather than executed, so they may occur at any point in your program. (Usually it's @@ -54,6 +56,9 @@ Field definitions are made up from a set of characters, for starting and extending a field to its desired width. This is the complete set of characters for field definitions: +X<format, picture line> +X<@> X<^> X<< < >> X<< | >> X<< > >> X<#> X<0> X<.> X<...> +X<@*> X<^*> X<~> X<~~> @ start of regular field ^ start of special field @@ -77,6 +82,7 @@ =head2 Text Fields +X<format, text field> The length of the field is supplied by padding out the field with multiple "E<lt>", "E<gt>", or "|" characters to specify a non-numeric field with, @@ -97,6 +103,7 @@ =head2 Numeric Fields +X<#> X<format, numeric field> Using "#" as a padding character specifies a numeric field, with right justification. An optional "." defines the position of the @@ -116,6 +123,7 @@ =head2 The Field @* for Variable Width Multi-Line Text +X<@*> The field "@*" can be used for printing multi-line, nontruncated values; it should (but need not) appear by itself on a line. A final @@ -123,6 +131,7 @@ =head2 The Field ^* for Variable Width One-line-at-a-time Text +X<^*> Like "@*", this is a variable width field. The value supplied must be a scalar variable. Perl puts the first line (up to the first "\n") of the @@ -145,6 +154,7 @@ =head2 Specifying Values +X<format, specifying values> The values are specified on the following format line in the same order as the picture fields. The expressions providing the values must be @@ -163,6 +173,7 @@ =head2 Using Fill Mode +X<format, fill mode> On text fields the caret enables a kind of fill mode. Instead of an arbitrary expression, the value supplied must be a scalar variable @@ -184,6 +195,7 @@ =head2 Suppressing Lines Where All Fields Are Void +X<format, suppressing lines> Using caret fields can produce lines where all fields are blank. You can suppress such lines by putting a "~" (tilde) character anywhere in the @@ -191,6 +203,7 @@ =head2 Repeating Format Lines +X<format, repeating lines> If you put two contiguous tilde characters "~~" anywhere into a line, the line will be repeated until all the fields on the line are exhausted, @@ -202,6 +215,7 @@ =head2 Top of Form Processing +X<format, top of form> X<top> X<header> Top-of-form processing is by default handled by a format with the same name as the current filehandle with "_TOP" concatenated to it. @@ -256,6 +270,8 @@ yourself. =head2 Format Variables +X<format variables> +X<format, variables> The current format name is stored in the variable C<$~> (C<$FORMAT_NAME>), and the current top of form format name is in C<$^> (C<$FORMAT_TOP_NAME>). @@ -365,6 +381,7 @@ } =head2 Footers +X<format, footer> X<footer> While $FORMAT_TOP_NAME contains the name of the current header format, there is no corresponding mechanism to automatically do the same thing @@ -381,6 +398,7 @@ however you like. Not very convenient, but doable. =head2 Accessing Formatting Internals +X<format, internals> For low-level access to the formatting mechanism. you may use formline() and access C<$^A> (the $ACCUMULATOR variable) directly. ==== //depot/perl/pod/perlfunc.pod#497 (text) ==== Index: perl/pod/perlfunc.pod --- perl/pod/perlfunc.pod#496~25691~ Tue Oct 4 09:24:28 2005 +++ perl/pod/perlfunc.pod Thu Oct 13 04:20:23 2005 @@ -1,4 +1,5 @@ =head1 NAME +X<function> perlfunc - Perl builtin functions @@ -68,6 +69,7 @@ last value in the list. Some operators return a count of successful operations. In general, they do what you want, unless you want consistency. +X<context> A named array in scalar context is quite different from what would at first glance appear to be a list in scalar context. You can't get a list @@ -85,6 +87,7 @@ variable on failure. Other functions do not, except accidentally. =head2 Perl Functions by Category +X<function> Here are Perl's functions (including things that look like functions, like some keywords and named operators) @@ -94,33 +97,40 @@ =over 4 =item Functions for SCALARs or strings +X<scalar> X<string> X<character> C<chomp>, C<chop>, C<chr>, C<crypt>, C<hex>, C<index>, C<lc>, C<lcfirst>, C<length>, C<oct>, C<ord>, C<pack>, C<q/STRING/>, C<qq/STRING/>, C<reverse>, C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y///> =item Regular expressions and pattern matching +X<regular expression> X<regex> X<regexp> C<m//>, C<pos>, C<quotemeta>, C<s///>, C<split>, C<study>, C<qr//> =item Numeric functions +X<numeric> X<number> X<trigonometric> X<trigonometry> C<abs>, C<atan2>, C<cos>, C<exp>, C<hex>, C<int>, C<log>, C<oct>, C<rand>, C<sin>, C<sqrt>, C<srand> =item Functions for real @ARRAYs +X<array> C<pop>, C<push>, C<shift>, C<splice>, C<unshift> =item Functions for list data +X<list> C<grep>, C<join>, C<map>, C<qw/STRING/>, C<reverse>, C<sort>, C<unpack> =item Functions for real %HASHes +X<hash> C<delete>, C<each>, C<exists>, C<keys>, C<values> =item Input and output functions +X<I/O> X<input> X<output> X<dbm> C<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>, C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>, @@ -133,6 +143,7 @@ C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec> =item Functions for filehandles, files, or directories +X<file> X<filehandle> X<directory> X<pipe> X<link> X<symlink> C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>, C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>, @@ -140,6 +151,7 @@ C<umask>, C<unlink>, C<utime> =item Keywords related to the control flow of your Perl program +X<control flow> C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>, C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray> @@ -154,38 +166,45 @@ C<scalar>, C<undef>, C<wantarray> =item Functions for processes and process groups +X<process> X<pid> X<process id> C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>, C<pipe>, C<qx/STRING/>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>, C<times>, C<wait>, C<waitpid> =item Keywords related to perl modules +X<module> C<do>, C<import>, C<no>, C<package>, C<require>, C<use> =item Keywords related to classes and object-orientedness +X<object> X<class> X<package> C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>, C<untie>, C<use> =item Low-level socket functions +X<socket> X<sock> C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>, C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>, C<socket>, C<socketpair> =item System V interprocess communication functions +X<IPC> X<System V> X<semaphore> X<shared memory> X<memory> X<message> C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>, C<shmctl>, C<shmget>, C<shmread>, C<shmwrite> =item Fetching user and group info +X<user> X<group> X<password> X<uid> X<gid> X<passwd> X</etc/passwd> C<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>, C<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>, C<getpwuid>, C<setgrent>, C<setpwent> =item Fetching network info +X<network> X<protocol> X<host> X<hostname> X<IP> X<address> X<service> C<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>, C<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>, @@ -194,10 +213,12 @@ C<setnetent>, C<setprotoent>, C<setservent> =item Time-related functions +X<time> X<date> C<gmtime>, C<localtime>, C<time>, C<times> =item Functions new in perl5 +X<perl5> C<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>, C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<our>, C<prototype>, @@ -214,6 +235,7 @@ =back =head2 Portability +X<portability> X<Unix> X<portable> Perl was born in Unix and can therefore access all common Unix system calls. In non-Unix environments, the functionality of some @@ -247,6 +269,8 @@ =over 8 =item -X FILEHANDLE +X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p> +X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C> =item -X EXPR @@ -261,8 +285,6 @@ names, precedence is the same as any other named unary operator, and the argument may be parenthesized like any other unary operator. The operator may be any of: -X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p> -X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C> -r File is readable by effective uid/gid. -w File is writable by effective uid/gid. @@ -373,6 +395,7 @@ operator, no special magic will happen.) =item abs VALUE +X<abs> X<absolute> =item abs @@ -380,6 +403,7 @@ If VALUE is omitted, uses C<$_>. =item accept NEWSOCKET,GENERICSOCKET +X<accept> Accepts an incoming socket connect, just as the accept(2) system call does. Returns the packed address if it succeeded, false otherwise. @@ -390,6 +414,9 @@ value of $^F. See L<perlvar/$^F>. =item alarm SECONDS +X<alarm> +X<SIGALRM> +X<timer> =item alarm @@ -438,6 +465,7 @@ For more information see L<perlipc>. =item atan2 Y,X +X<atan2> X<arctangent> X<tan> X<tangent> Returns the arctangent of Y/X in the range -PI to PI. @@ -449,6 +477,7 @@ Note that atan2(0, 0) is not well-defined. =item bind SOCKET,NAME +X<bind> Binds a network address to a socket, just as the bind system call does. Returns true if it succeeded, false otherwise. NAME should be a @@ -456,6 +485,7 @@ L<perlipc/"Sockets: Client/Server Communication">. =item binmode FILEHANDLE, LAYER +X<binmode> X<binary> X<text> X<DOS> X<Windows> =item binmode FILEHANDLE @@ -542,6 +572,7 @@ line-termination sequences. =item bless REF,CLASSNAME +X<bless> =item bless REF @@ -562,6 +593,7 @@ See L<perlmod/"Perl Modules">. =item caller EXPR +X<caller> X<call stack> X<stack> X<stack trace> =item caller @@ -604,6 +636,8 @@ previous time C<caller> was called. =item chdir EXPR +X<chdir> +X<cd> =item chdir FILEHANDLE @@ -623,6 +657,7 @@ passing handles produces a fatal error at run time. =item chmod LIST +X<chmod> X<permission> X<mode> Changes the permissions of a list of files. The first element of the list must be the numerical mode, which should probably be an octal @@ -654,6 +689,7 @@ # This is identical to the chmod 0755 of the above example. =item chomp VARIABLE +X<chomp> X<INPUT_RECORD_SEPARATOR> X<$/> X<newline> X<eol> =item chomp( LIST ) @@ -699,6 +735,7 @@ as C<chomp($a, $b)>. =item chop VARIABLE +X<chop> =item chop( LIST ) @@ -720,6 +757,7 @@ See also L</chomp>. =item chown LIST +X<chown> X<owner> X<user> X<group> Changes the owner (and group) of a list of files. The first two elements of the list must be the I<numeric> uid and gid, in that @@ -757,6 +795,7 @@ $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED); =item chr NUMBER +X<chr> X<character> X<ASCII> X<Unicode> =item chr @@ -780,6 +819,7 @@ See L<perlunicode> and L<encoding> for more about Unicode. =item chroot FILENAME +X<chroot> X<root> =item chroot @@ -791,6 +831,7 @@ omitted, does a C<chroot> to C<$_>. =item close FILEHANDLE +X<close> =item close @@ -833,11 +874,13 @@ filehandle, usually the real filehandle name. =item closedir DIRHANDLE +X<closedir> Closes a directory opened by C<opendir> and returns the success of that system call. =item connect SOCKET,NAME +X<connect> Attempts to connect to a remote socket, just as the connect system call does. Returns true if it succeeded, false otherwise. NAME should be a @@ -845,6 +888,7 @@ L<perlipc/"Sockets: Client/Server Communication">. =item continue BLOCK +X<continue> C<continue> is actually a flow control statement rather than a function. If there is a C<continue> BLOCK attached to a BLOCK (typically in a C<while> or @@ -874,6 +918,7 @@ to check the condition at the top of the loop. =item cos EXPR +X<cos> X<cosine> X<acos> X<arccosine> =item cos @@ -886,6 +931,8 @@ sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) } =item crypt PLAINTEXT,SALT +X<crypt> X<digest> X<hash> X<salt> X<plaintext> X<password> +X<decrypt> X<cryptography> X<passwd> Creates a digest string exactly like the crypt(3) function in the C library (assuming that you actually have a version there that has not @@ -963,12 +1010,14 @@ C<Wide character in crypt>. =item dbmclose HASH +X<dbmclose> [This function has been largely superseded by the C<untie> function.] Breaks the binding between a DBM file and a hash. =item dbmopen HASH,DBNAME,MASK +X<dbmopen> X<dbm> X<ndbm> X<sdbm> X<gdbm> [This function has been largely superseded by the C<tie> function.] @@ -1011,6 +1060,7 @@ or die "Can't open netscape history file: $!"; =item defined EXPR +X<defined> X<undef> X<undefined> =item defined @@ -1074,6 +1124,7 @@ See also L</undef>, L</exists>, L</ref>. =item delete EXPR +X<delete> Given an expression that specifies a hash element, array element, hash slice, or array slice, deletes the specified element(s) from the hash or array. @@ -1138,6 +1189,7 @@ delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices]; =item die LIST +X<die> X<throw> X<exception> X<raise> X<$@> X<abort> Outside an C<eval>, prints the value of LIST to C<STDERR> and exits with the current value of C<$!> (errno). If C<$!> is C<0>, @@ -1229,6 +1281,7 @@ behavior may be fixed in a future release. =item do BLOCK +X<do> X<block> Not really a function. Returns the value of the last command in the sequence of commands indicated by BLOCK. When modified by the C<while> or @@ -1241,10 +1294,12 @@ See L<perlsyn> for alternative strategies. =item do SUBROUTINE(LIST) +X<do> This form of subroutine call is deprecated. See L<perlsub>. =item do EXPR +X<do> Uses the value of EXPR as a filename and executes the contents of the file as a Perl script. @@ -1288,6 +1343,7 @@ } =item dump LABEL +X<dump> X<core> X<undump> =item dump @@ -1320,6 +1376,7 @@ make your program I<appear> to run faster. =item each HASH +X<each> X<hash, iterator> When called in list context, returns a 2-element list consisting of the key and value for the next element of a hash, so that you can iterate over @@ -1359,6 +1416,9 @@ See also C<keys>, C<values> and C<sort>. =item eof FILEHANDLE +X<eof> +X<end of file> +X<end-of-file> =item eof () @@ -1409,6 +1469,7 @@ there was an error. =item eval EXPR +X<eval> X<try> X<catch> X<evaluate> X<parse> X<execute> =item eval BLOCK @@ -1527,6 +1588,7 @@ need to worry about this unless you are writing a Perl debugger. =item exec LIST +X<exec> X<execute> =item exec PROGRAM LIST @@ -1602,6 +1664,7 @@ any C<DESTROY> methods in your objects. =item exists EXPR +X<exists> X<autovivification> Given an expression that specifies a hash element or array element, returns true if the specified element in the hash or array has ever @@ -1662,6 +1725,7 @@ exists &sub(); # Error =item exit EXPR +X<exit> X<terminate> X<abort> =item exit @@ -1689,6 +1753,7 @@ See L<perlmod> for details. =item exp EXPR +X<exp> X<exponential> X<antilog> X<antilogarithm> X<e> =item exp @@ -1696,6 +1761,7 @@ If EXPR is omitted, gives C<exp($_)>. =item fcntl FILEHANDLE,FUNCTION,SCALAR +X<fcntl> Implements the fcntl(2) function. You'll probably have to say @@ -1732,6 +1798,7 @@ or die "Can't set flags for the socket: $!\n"; =item fileno FILEHANDLE +X<fileno> Returns the file descriptor for a filehandle, or undefined if the filehandle is not open. This is mainly useful for constructing @@ -1751,6 +1818,7 @@ =item flock FILEHANDLE,OPERATION +X<flock> X<lock> X<locking> Calls flock(2), or an emulation of it, on FILEHANDLE. Returns true for success, false on failure. Produces a fatal error if used on a @@ -1828,6 +1896,7 @@ See also L<DB_File> for other flock() examples. =item fork +X<fork> X<child> X<parent> Does a fork(2) system call to create a new process running the same program at the same point. It returns the child pid to the @@ -1856,6 +1925,7 @@ You should reopen those to F</dev/null> if it's any issue. =item format +X<format> Declare a picture format for use by the C<write> function. For example: @@ -1873,6 +1943,7 @@ See L<perlform> for many details and examples. =item formline PICTURE,LIST +X<formline> This is an internal function used by C<format>s, though you may call it, too. It formats (see L<perlform>) a list of values according to the @@ -1892,6 +1963,7 @@ C<formline> always returns true. See L<perlform> for other examples. =item getc FILEHANDLE +X<getc> X<getchar> =item getc @@ -1928,6 +2000,7 @@ L<perlmodlib/CPAN>. =item getlogin +X<getlogin> X<login> This implements the C library function of the same name, which on most systems returns the current login from F</etc/utmp>, if any. If null, @@ -1939,6 +2012,7 @@ secure as C<getpwuid>. =item getpeername SOCKET +X<getpeername> X<peer> Returns the packed sockaddr address of other end of the SOCKET connection. @@ -1949,6 +2023,7 @@ $herstraddr = inet_ntoa($iaddr); =item getpgrp PID +X<getpgrp> X<group> Returns the current process group for the specified PID. Use a PID of C<0> to get the current process group for the @@ -1958,6 +2033,7 @@ does not accept a PID argument, so only C<PID==0> is truly portable. =item getppid +X<getppid> X<parent> X<pid> Returns the process id of the parent process. @@ -1969,12 +2045,19 @@ C<Linux::Pid>. =item getpriority WHICH,WHO +X<getpriority> X<priority> X<nice> Returns the current priority for a process, a process group, or a user. (See L<getpriority(2)>.) Will raise a fatal exception if used on a machine that doesn't implement getpriority(2). =item getpwnam NAME +X<getpwnam> X<getgrnam> X<gethostbyname> X<getnetbyname> X<getprotobyname> +X<getpwuid> X<getgrgid> X<getservbyname> X<gethostbyaddr> X<getnetbyaddr> +X<getprotobynumber> X<getservbyport> X<getpwent> X<getgrent> X<gethostent> +X<getnetent> X<getprotoent> X<getservent> X<setpwent> X<setgrent> X<sethostent> +X<setnetent> X<setprotoent> X<setservent> X<endpwent> X<endgrent> X<endhostent> +X<endnetent> X<endprotoent> X<endservent> =item getgrnam NAME @@ -2128,6 +2211,7 @@ a C<User::pwent> object. =item getsockname SOCKET +X<getsockname> Returns the packed sockaddr address of this end of the SOCKET connection, in case you don't know the address because you have several different @@ -2141,6 +2225,7 @@ inet_ntoa($myaddr); =item getsockopt SOCKET,LEVEL,OPTNAME +X<getsockopt> Queries the option named OPTNAME associated with SOCKET at a given LEVEL. Options may exist at multiple protocol levels depending on the socket @@ -2172,6 +2257,7 @@ =item glob EXPR +X<glob> X<wildcard> X<filename, expansion> X<expand> =item glob @@ -2187,6 +2273,7 @@ C<File::Glob> extension. See L<File::Glob> for details. =item gmtime EXPR +X<gmtime> X<UTC> X<Greenwich> =item gmtime @@ -2236,6 +2323,7 @@ See L<perlport/gmtime> for portability concerns. =item goto LABEL +X<goto> X<jump> X<jmp> =item goto EXPR @@ -2277,6 +2365,7 @@ reference. =item grep BLOCK LIST +X<grep> =item grep EXPR,LIST @@ -2311,6 +2400,7 @@ See also L</map> for a list composed of the results of the BLOCK or EXPR. =item hex EXPR +X<hex> X<hexadecimal> =item hex @@ -2327,6 +2417,7 @@ L</sprintf>, or L</unpack>. =item import LIST +X<import> There is no builtin C<import> function. It is just an ordinary method (subroutine) defined (or inherited) by modules that wish to export @@ -2334,6 +2425,7 @@ for the package used. See also L</use>, L<perlmod>, and L<Exporter>. =item index STR,SUBSTR,POSITION +X<index> X<indexOf> X<InStr> =item index STR,SUBSTR @@ -2348,6 +2440,7 @@ is not found, C<index> returns one less than the base, ordinarily C<-1>. =item int EXPR +X<int> X<integer> X<truncate> X<trunc> =item int @@ -2361,6 +2454,7 @@ functions will serve you better than will int(). =item ioctl FILEHANDLE,FUNCTION,SCALAR +X<ioctl> Implements the ioctl(2) function. You'll probably first have to say @@ -2397,6 +2491,7 @@ about improper numeric conversions. =item join EXPR,LIST +X<join> Joins the separate strings of LIST into a single string with fields separated by the value of EXPR, and returns that new string. Example: @@ -2407,6 +2502,7 @@ first argument. Compare L</split>. =item keys HASH +X<keys> X<key> Returns a list consisting of all the keys of the named hash. (In scalar context, returns the number of keys.) @@ -2465,6 +2561,7 @@ See also C<each>, C<values> and C<sort>. =item kill SIGNAL, LIST +X<kill> X<signal> Sends a signal to a list of processes. Returns the number of processes successfully signaled (which is not necessarily the @@ -2487,6 +2584,7 @@ See L<perlipc/"Signals"> for more details. =item last LABEL +X<last> X<break> =item last @@ -2512,6 +2610,7 @@ C<redo> work. =item lc EXPR +X<lc> X<lowercase> =item lc @@ -2523,6 +2622,7 @@ If EXPR is omitted, uses C<$_>. =item lcfirst EXPR +X<lcfirst> X<lowercase> =item lcfirst @@ -2535,6 +2635,7 @@ If EXPR is omitted, uses C<$_>. =item length EXPR +X<length> X<size> =item length @@ -2548,17 +2649,20 @@ in bytes, use C<do { use bytes; length(EXPR) }>, see L<bytes>. =item link OLDFILE,NEWFILE +X<link> Creates a new filename linked to the old filename. Returns true for success, false otherwise. =item listen SOCKET,QUEUESIZE +X<listen> Does the same thing that the listen system call does. Returns true if it succeeded, false otherwise. See the example in L<perlipc/"Sockets: Client/Server Communication">. =item local EXPR +X<local> You really probably want to be using C<my> instead, because C<local> isn't what most people think of as "local". See @@ -2570,6 +2674,7 @@ for details, including issues with tied arrays and hashes. =item localtime EXPR +X<localtime> =item localtime @@ -2637,6 +2742,7 @@ See L<perlport/localtime> for portability concerns. =item lock THING +X<lock> This function places an advisory lock on a shared variable, or referenced object contained in I<THING> until the lock goes out of scope. @@ -2647,6 +2753,7 @@ keyword.) See L<threads>. =item log EXPR +X<log> X<logarithm> X<e> X<ln> X<base> =item log @@ -2663,6 +2770,7 @@ See also L</exp> for the inverse operation. =item lstat EXPR +X<lstat> =item lstat @@ -2679,6 +2787,7 @@ The match operator. See L<perlop>. =item map BLOCK LIST +X<map> =item map EXPR,LIST @@ -2738,6 +2847,7 @@ and you get list of anonymous hashes each with only 1 entry. =item mkdir FILENAME,MASK +X<mkdir> X<md> X<directory, create> =item mkdir FILENAME @@ -2762,6 +2872,7 @@ everyone happy. =item msgctl ID,CMD,ARG +X<msgctl> Calls the System V IPC function msgctl(2). You'll probably have to say @@ -2774,12 +2885,14 @@ L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::Semaphore> documentation. =item msgget KEY,FLAGS +X<msgget> Calls the System V IPC function msgget(2). Returns the message queue id, or the undefined value if there is an error. See also L<perlipc/"SysV IPC"> and C<IPC::SysV> and C<IPC::Msg> documentation. =item msgrcv ID,VAR,SIZE,TYPE,FLAGS +X<msgrcv> Calls the System V IPC function msgrcv to receive a message from message queue ID into variable VAR with a maximum message size of @@ -2791,6 +2904,7 @@ C<IPC::SysV::Msg> documentation. =item msgsnd ID,MSG,FLAGS +X<msgsnd> Calls the System V IPC function msgsnd to send the message MSG to the message queue ID. MSG must begin with the native long integer message @@ -2801,6 +2915,7 @@ and C<IPC::SysV::Msg> documentation. =item my EXPR +X<my> =item my TYPE EXPR @@ -2820,6 +2935,7 @@ L<attributes>, and L<Attribute::Handlers>. =item next LABEL +X<next> X<continue> =item next @@ -2846,6 +2962,7 @@ C<redo> work. =item no Module VERSION LIST +X<no> =item no Module VERSION @@ -2856,6 +2973,7 @@ See the C<use> function, of which C<no> is the opposite. =item oct EXPR +X<oct> X<octal> X<hex> X<hexadecimal> X<binary> X<bin> =item oct @@ -2880,6 +2998,7 @@ conversion assumes base 10.) =item open FILEHANDLE,EXPR +X<open> X<pipe> X<file, open> X<fopen> =item open FILEHANDLE,MODE,EXPR @@ -3249,6 +3368,7 @@ See L</seek> for some details about mixing reading and writing. =item opendir DIRHANDLE,EXPR +X<opendir> Opens a directory named EXPR for processing by C<readdir>, C<telldir>, C<seekdir>, C<rewinddir>, and C<closedir>. Returns true if successful. @@ -3259,6 +3379,7 @@ DIRHANDLEs have their own namespace separate from FILEHANDLEs. =item ord EXPR +X<ord> X<encoding> =item ord @@ -3270,6 +3391,7 @@ See L<perlunicode> and L<encoding> for more about Unicode. =item our EXPR +X<our> X<global> =item our EXPR TYPE @@ -3364,6 +3486,7 @@ subject to change. =item pack TEMPLATE,LIST +X<pack> Takes a LIST of values and converts it into a string using the rules given by the TEMPLATE. The resulting string is the concatenation of @@ -3883,6 +4006,7 @@ The same template may generally also be used in unpack(). =item package NAMESPACE +X<package> X<module> X<namespace> =item package @@ -3912,6 +4036,7 @@ and classes. See L<perlsub> for other scoping issues. =item pipe READHANDLE,WRITEHANDLE +X<pipe> Opens a pair of connected pipes like the corresponding system call. Note that if you set up a loop of piped processes, deadlock can occur @@ -3927,6 +4052,7 @@ See L<perlvar/$^F>. =item pop ARRAY +X<pop> X<stack> =item pop @@ -3941,6 +4067,7 @@ array in subroutines, just like C<shift>. =item pos SCALAR +X<pos> X<match, position> =item pos @@ -3956,6 +4083,7 @@ L<perlop>. =item print FILEHANDLE LIST +X<print> =item print LIST @@ -3990,6 +4118,7 @@ print { $OK ? STDOUT : STDERR } "stuff\n"; =item printf FILEHANDLE FORMAT, LIST +X<printf> =item printf FORMAT, LIST @@ -4005,6 +4134,7 @@ error prone. =item prototype FUNCTION +X<prototype> Returns the prototype of a function as a string (or C<undef> if the function has no prototype). FUNCTION is a reference to, or the name of, @@ -4018,6 +4148,7 @@ prototype is returned. =item push ARRAY,LIST +X<push>, X<stack> Treats ARRAY as a stack, and pushes the values of LIST onto the end of ARRAY. The length of ARRAY increases by the length of @@ -4043,6 +4174,7 @@ Generalized quotes. See L<perlop/"Regexp Quote-Like Operators">. =item quotemeta EXPR +X<quotemeta> X<metacharacter> =item quotemeta @@ -4056,6 +4188,7 @@ If EXPR is omitted, uses C<$_>. =item rand EXPR +X<rand> X<random> =item rand @@ -4078,6 +4211,7 @@ with the wrong number of RANDBITS.) =item read FILEHANDLE,SCALAR,LENGTH,OFFSET +X<read> =item read FILEHANDLE,SCALAR,LENGTH @@ -4107,6 +4241,7 @@ in that case pretty much any characters can be read. =item readdir DIRHANDLE +X<readdir> Returns the next directory entry for a directory opened by C<opendir>. If used in list context, returns all the rest of the entries in the @@ -4122,6 +4257,7 @@ closedir DIR; =item readline EXPR +X<readline> X<gets> X<fgets> Reads from the filehandle whose typeglob is contained in EXPR. In scalar context, each call reads and returns the next line, until end-of-file is @@ -4157,6 +4293,7 @@ } =item readlink EXPR +X<readlink> =item readlink @@ -4166,6 +4303,7 @@ omitted, uses C<$_>. =item readpipe EXPR +X<readpipe> EXPR is executed as a system command. The collected standard output of the command is returned. @@ -4177,6 +4315,7 @@ operator is discussed in more detail in L<perlop/"I/O Operators">. =item recv SOCKET,SCALAR,LENGTH,FLAGS +X<recv> Receives a message on a socket. Attempts to receive LENGTH characters of data into variable SCALAR from the specified SOCKET filehandle. @@ -4196,6 +4335,7 @@ in that case pretty much any characters can be read. =item redo LABEL +X<redo> =item redo @@ -4234,6 +4374,7 @@ C<redo> work. =item ref EXPR +X<ref> X<reference> =item ref @@ -4264,6 +4405,7 @@ See also L<perlref>. =item rename OLDNAME,NEWNAME +X<rename> X<move> X<mv> X<ren> Changes the name of a file; an existing file NEWNAME will be clobbered. Returns true for success, false otherwise. @@ -4276,6 +4418,7 @@ rename(2) manpage or equivalent system documentation for details. =item require VERSION +X<require> =item require EXPR @@ -4432,6 +4575,7 @@ For a yet-more-powerful import facility, see L</use> and L<perlmod>. =item reset EXPR +X<reset> =item reset @@ -4455,6 +4599,7 @@ See L</my>. =item return EXPR +X<return> =item return @@ -4470,6 +4615,7 @@ evaluated.) =item reverse LIST +X<reverse> X<rev> X<invert> In list context, returns a list value consisting of the elements of LIST in the opposite order. In scalar context, concatenates the @@ -4492,11 +4638,13 @@ %by_name = reverse %by_address; # Invert the hash =item rewinddir DIRHANDLE +X<rewinddir> Sets the current position to the beginning of the directory for the C<readdir> routine on DIRHANDLE. =item rindex STR,SUBSTR,POSITION +X<rindex> =item rindex STR,SUBSTR @@ -4505,6 +4653,7 @@ last occurrence at or before that position. =item rmdir FILENAME +X<rmdir> X<rd> X<directory, remove> =item rmdir @@ -4517,6 +4666,7 @@ The substitution operator. See L<perlop>. =item scalar EXPR +X<scalar> X<context> Forces EXPR to be interpreted in scalar context and returns the value of EXPR. @@ -4546,6 +4696,7 @@ See L<perlop> for more details on unary operators and the comma operator. =item seek FILEHANDLE,POSITION,WHENCE +X<seek> X<fseek> X<filehandle, position> Sets FILEHANDLE's position, just like the C<fseek> call of C<stdio>. FILEHANDLE may be an expression whose value gives the name of the @@ -4592,6 +4743,7 @@ } =item seekdir DIRHANDLE,POS +X<seekdir> Sets the current position for the C<readdir> routine on DIRHANDLE. POS must be a value returned by C<telldir>. C<seekdir> also has the same caveats @@ -4599,6 +4751,7 @@ routine. =item select FILEHANDLE +X<select> X<filehandle, default> =item select @@ -4627,6 +4780,7 @@ STDERR->autoflush(1); =item select RBITS,WBITS,EBITS,TIMEOUT +X<select> This calls the select(2) system call with the bit masks specified, which can be constructed using C<fileno> and C<vec>, along these lines: @@ -4688,6 +4842,7 @@ then only on POSIX systems. You have to use C<sysread> instead. =item semctl ID,SEMNUM,CMD,ARG +X<semctl> Calls the System V IPC function C<semctl>. You'll probably have to say @@ -4703,6 +4858,7 @@ documentation. =item semget KEY,NSEMS,FLAGS +X<semget> Calls the System V IPC function semget. Returns the semaphore id, or the undefined value if there is an error. See also @@ -4710,6 +4866,7 @@ documentation. =item semop KEY,OPSTRING +X<semop> Calls the System V IPC function semop to perform semaphore operations such as signalling and waiting. OPSTRING must be a packed array of @@ -4727,6 +4884,7 @@ documentation. =item send SOCKET,MSG,FLAGS,TO +X<send> =item send SOCKET,MSG,FLAGS @@ -4747,6 +4905,7 @@ in that case pretty much any characters can be sent. =item setpgrp PID,PGRP +X<setpgrp> X<group> Sets the current process group for the specified PID, C<0> for the current process. Will produce a fatal error if used on a machine that doesn't @@ -4756,18 +4915,21 @@ C<POSIX::setsid()>. =item setpriority WHICH,WHO,PRIORITY +X<setpriority> X<priority> X<nice> X<renice> Sets the current priority for a process, a process group, or a user. (See setpriority(2).) Will produce a fatal error if used on a machine that doesn't implement setpriority(2). =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL +X<setsockopt> Sets the socket option requested. Returns undefined if there is an error. OPTVAL may be specified as C<undef> if you don't want to pass an argument. =item shift ARRAY +X<shift> =item shift @@ -4784,6 +4946,7 @@ right end. =item shmctl ID,CMD,ARG +X<shmctl> Calls the System V IPC function shmctl. You'll probably have to say @@ -4796,12 +4959,15 @@ See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation. =item shmget KEY,SIZE,FLAGS +X<shmget> Calls the System V IPC function shmget. Returns the shared memory segment id, or the undefined value if there is an error. See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation. =item shmread ID,VAR,POS,SIZE +X<shmread> +X<shmwrite> =item shmwrite ID,STRING,POS,SIZE @@ -4815,6 +4981,7 @@ C<IPC::SysV> documentation, and the C<IPC::Shareable> module from CPAN. =item shutdown SOCKET,HOW +X<shutdown> Shuts down a socket connection in the manner indicated by HOW, which has the same interpretation as in the system call of the same name. @@ -4830,6 +4997,7 @@ processes. =item sin EXPR +X<sin> X<sine> X<asin> X<arcsine> =item sin @@ -4842,6 +5010,7 @@ sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) } =item sleep EXPR +X<sleep> X<pause> =item sleep @@ -4866,6 +5035,7 @@ See also the POSIX module's C<pause> function. =item socket SOCKET,DOMAIN,TYPE,PROTOCOL +X<socket> Opens a socket of the specified kind and attaches it to filehandle SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for @@ -4878,6 +5048,7 @@ value of $^F. See L<perlvar/$^F>. =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL +X<socketpair> Creates an unnamed pair of sockets in the specified domain, of the specified type. DOMAIN, TYPE, and PROTOCOL are specified the same as @@ -4901,6 +5072,7 @@ sockets but not socketpair. =item sort SUBNAME LIST +X<sort> X<qsort> X<quicksort> X<mergesort> =item sort BLOCK LIST @@ -5071,6 +5243,7 @@ @result = sort { $a <=> $b } grep { $_ == $_ } @input; =item splice ARRAY,OFFSET,LENGTH,LIST +X<splice> =item splice ARRAY,OFFSET,LENGTH @@ -5113,6 +5286,7 @@ if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... } =item split /PATTERN/,EXPR,LIMIT +X<split> =item split /PATTERN/,EXPR @@ -5227,6 +5401,7 @@ # @fields is (1, 'A', 2, undef, 3) =item sprintf FORMAT, LIST +X<sprintf> Returns a string formatted by the usual C<printf> conventions of the C library function C<sprintf>. See below for more details @@ -5363,6 +5538,7 @@ effect as the C<-> flag: left-justification. =item precision, or maximum width +X<precision> You can specify a precision (for numeric conversions) or a maximum width (for string conversions) by specifying a C<.> followed by a number. @@ -5500,6 +5676,7 @@ See L<perllocale>. =item sqrt EXPR +X<sqrt> X<root> X<square root> =item sqrt @@ -5511,6 +5688,7 @@ print sqrt(-2); # prints 1.4142135623731i =item srand EXPR +X<srand> X<seed> X<randseed> =item srand @@ -5572,6 +5750,7 @@ one-third of the time. So don't do that. =item stat FILEHANDLE +X<stat> X<file, status> =item stat EXPR @@ -5702,6 +5881,7 @@ instead of the target file behind the link, use the C<lstat> function. =item study SCALAR +X<study> =item study @@ -5761,6 +5941,7 @@ } =item sub NAME BLOCK +X<sub> =item sub NAME (PROTO) BLOCK @@ -5778,6 +5959,7 @@ information about attributes. =item substr EXPR,OFFSET,LENGTH,REPLACEMENT +X<substr> X<substring> X<mid> X<left> X<right> =item substr EXPR,OFFSET,LENGTH @@ -5831,6 +6013,7 @@ unspecified. =item symlink OLDFILE,NEWFILE +X<symlink> X<link> X<symbolic link> X<link, symbolic> Creates a new filename symbolically linked to the old filename. Returns C<1> for success, C<0> otherwise. On systems that don't support @@ -5840,6 +6023,7 @@ $symlink_exists = eval { symlink("",""); 1 }; =item syscall NUMBER, LIST +X<syscall> X<system call> Calls the system call specified as the first element of the list, passing the remaining elements as arguments to the system call. If @@ -5874,6 +6058,7 @@ problem by using C<pipe> instead. =item sysopen FILEHANDLE,FILENAME,MODE +X<sysopen> =item sysopen FILEHANDLE,FILENAME,MODE,PERMS @@ -5892,6 +6077,7 @@ Some of the most common values are C<O_RDONLY> for opening the file in read-only mode, C<O_WRONLY> for opening the file in write-only mode, and C<O_RDWR> for opening the file in read-write mode. +X<O_RDONLY> X<O_RDWR> X<O_WRONLY> For historical reasons, some values work on almost every system supported by perl: zero means read-only, one means write-only, and two @@ -5905,6 +6091,7 @@ the PERMS argument to C<sysopen>, Perl uses the octal value C<0666>. These permission values need to be in octal, and are modified by your process's current C<umask>. +X<O_CREAT> In many systems the C<O_EXCL> flag is available for opening files in exclusive mode. This is B<not> locking: exclusiveness means here that @@ -5913,10 +6100,12 @@ is set as well. Setting C<O_CREAT|O_EXCL> prevents the file from being opened if it is a symbolic link. It does not protect against symbolic links in the file's path. +X<O_EXCL> Sometimes you may want to truncate an already-existing file. This can be done using the C<O_TRUNC> flag. The behavior of C<O_TRUNC> with C<O_RDONLY> is undefined. +X<O_TRUNC> You should seldom if ever use C<0644> as argument to C<sysopen>, because that takes away the user's option to have a more permissive umask. @@ -5932,6 +6121,7 @@ See L<perlopentut> for a kinder, gentler explanation of opening files. =item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET +X<sysread> =item sysread FILEHANDLE,SCALAR,LENGTH @@ -5963,6 +6153,7 @@ See L</binmode>, L</open>, and the C<open> pragma, L<open>. =item sysseek FILEHANDLE,POSITION,WHENCE +X<sysseek> X<lseek> Sets FILEHANDLE's system position in bytes using the system call lseek(2). FILEHANDLE may be an expression whose value gives the name @@ -5994,6 +6185,7 @@ the new position. =item system LIST +X<system> X<shell> =item system PROGRAM LIST @@ -6059,6 +6251,7 @@ See L<perlop/"`STRING`"> and L</exec> for details. =item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET +X<syswrite> =item syswrite FILEHANDLE,SCALAR,LENGTH @@ -6087,6 +6280,7 @@ See L</binmode>, L</open>, and the C<open> pragma, L<open>. =item tell FILEHANDLE +X<tell> =item tell @@ -6111,6 +6305,7 @@ Those functions ignore the buffering, while tell() does not. =item telldir DIRHANDLE +X<telldir> Returns the current position of the C<readdir> routines on DIRHANDLE. Value may be given to C<seekdir> to access a particular location in a @@ -6118,6 +6313,7 @@ compaction as the corresponding system library routine. =item tie VARIABLE,CLASSNAME,LIST +X<tie> This function binds a variable to a package class that will provide the implementation for the variable. VARIABLE is the name of the variable @@ -6209,6 +6405,7 @@ For further details see L<perltie>, L<"tied VARIABLE">. =item tied VARIABLE +X<tied> Returns a reference to the object underlying VARIABLE (the same value that was originally returned by the C<tie> call that bound the variable @@ -6216,6 +6413,7 @@ package. =item time +X<time> X<epoch> Returns the number of non-leap seconds since whatever time the system considers to be the epoch, suitable for feeding to C<gmtime> and @@ -6230,6 +6428,7 @@ See L<perlfaq8> for details. =item times +X<times> Returns a four-element list giving the user and system times, in seconds, for this process and the children of this process. @@ -6243,6 +6442,7 @@ The transliteration operator. Same as C<y///>. See L<perlop>. =item truncate FILEHANDLE,LENGTH +X<truncate> =item truncate EXPR,LENGTH @@ -6255,6 +6455,7 @@ file. =item uc EXPR +X<uc> X<uppercase> X<toupper> =item uc @@ -6268,6 +6469,7 @@ If EXPR is omitted, uses C<$_>. =item ucfirst EXPR +X<ucfirst> X<uppercase> =item ucfirst @@ -6280,6 +6482,7 @@ If EXPR is omitted, uses C<$_>. =item umask EXPR +X<umask> =item umask @@ -6317,6 +6520,7 @@ string of octal digits. See also L</oct>, if all you have is a string. =item undef EXPR +X<undef> X<undefine> =item undef @@ -6343,6 +6547,7 @@ Note that this is a unary operator, not a list operator. =item unlink LIST +X<unlink> X<delete> X<remove> X<rm> =item unlink @@ -6361,6 +6566,7 @@ If LIST is omitted, uses C<$_>. =item unpack TEMPLATE,EXPR +X<unpack> =item unpack TEMPLATE @@ -6421,11 +6627,13 @@ See L</pack> for more examples and notes. =item untie VARIABLE +X<untie> Breaks the binding between a variable and a package. (See C<tie>.) Has no effect if the variable is not tied. =item unshift ARRAY,LIST +X<unshift> Does the opposite of a C<shift>. Or the opposite of a C<push>, depending on how you look at it. Prepends list to the front of the @@ -6438,6 +6646,7 @@ reverse. =item use Module VERSION LIST +X<use> X<module> X<import> =item use Module VERSION @@ -6536,6 +6745,7 @@ functionality from the command-line. =item utime LIST +X<utime> Changes the access and modification times on each file of a list of files. The first two elements of the list must be the NUMERICAL access @@ -6570,6 +6780,7 @@ uninitialized warning. =item values HASH +X<values> Returns a list consisting of all the values of the named hash. (In a scalar context, returns the number of values.) @@ -6594,6 +6805,7 @@ See also C<keys>, C<each>, and C<sort>. =item vec EXPR,OFFSET,BITS +X<vec> X<bit> X<bit vector> Treats the string in EXPR as a bit vector made up of elements of width BITS, and returns the value of the element specified by OFFSET @@ -6834,6 +7046,7 @@ vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001 =item wait +X<wait> Behaves like the wait(2) system call on your system: it waits for a child process to terminate and returns the pid of the deceased process, or @@ -6843,6 +7056,7 @@ being automatically reaped, as described in L<perlipc>. =item waitpid PID,FLAGS +X<waitpid> Waits for a particular child process to terminate and returns the pid of the deceased process, or C<-1> if there is no such child process. On some @@ -6867,6 +7081,7 @@ and for other examples. =item wantarray +X<wantarray> X<context> Returns true if the context of the currently executing subroutine or C<eval> is looking for a list value. Returns false if the context is @@ -6884,6 +7099,7 @@ This function should have been named wantlist() instead. =item warn LIST +X<warn> X<warning> X<STDERR> Produces a message on STDERR just like C<die>, but doesn't exit or throw an exception. @@ -6927,6 +7143,7 @@ carp() and cluck() functions. =item write FILEHANDLE +X<write> =item write EXPR ==== //depot/perl/pod/perllexwarn.pod#27 (text) ==== Index: perl/pod/perllexwarn.pod --- perl/pod/perllexwarn.pod#26~24205~ Fri Apr 8 05:18:42 2005 +++ perl/pod/perllexwarn.pod Thu Oct 13 04:20:23 2005 @@ -1,4 +1,5 @@ =head1 NAME +X<warning, lexical> X<warnings> X<warning> perllexwarn - Perl Lexical Warnings @@ -130,6 +131,7 @@ =over 5 =item B<-w> +X<-w> This is the existing flag. If the lexical warnings pragma is B<not> used in any of you code, or any of the modules that you use, this flag @@ -137,6 +139,7 @@ details of how this flag interacts with lexical warnings. =item B<-W> +X<-W> If the B<-W> flag is used on the command line, it will enable all warnings throughout the program regardless of whether warnings were disabled @@ -145,6 +148,7 @@ Think of it as the Perl equivalent of the "lint" command. =item B<-X> +X<-X> Does the exact opposite to the B<-W> flag, i.e. it disables all warnings. @@ -199,6 +203,7 @@ code (using a C<local $^W=0>) if it really wants to, but not vice-versa. =head2 Category Hierarchy +X<warning, categories> A hierarchy of "categories" have been defined to allow groups of warnings to be enabled/disabled in isolation. @@ -322,6 +327,7 @@ =head2 Fatal Warnings +X<warning, fatal> The presence of the word "FATAL" in the category list will escalate any warnings detected from the categories specified in the lexical scope @@ -366,6 +372,7 @@ use warnings FATAL => 'all', NONFATAL => 'syntax'; =head2 Reporting Warnings from a Module +X<warning, reporting> X<warning, registering> The C<warnings> pragma provides a number of functions that are useful for module authors. These are used when you want to report a module-specific ==== //depot/perl/pod/perlmod.pod#38 (text) ==== Index: perl/pod/perlmod.pod --- perl/pod/perlmod.pod#37~24822~ Mon Jun 13 05:49:18 2005 +++ perl/pod/perlmod.pod Thu Oct 13 04:20:23 2005 @@ -5,6 +5,7 @@ =head1 DESCRIPTION =head2 Packages +X<package> X<namespace> X<variable, global> X<global variable> X<global> Perl provides a mechanism for alternative namespaces to protect packages from stomping on each other's variables. In fact, there's @@ -38,6 +39,7 @@ C<"This is $owner's house">, you'll be accessing C<$owner::s>; that is, the $s variable in package C<owner>, which is probably not what you meant. Use braces to disambiguate, as in C<"This is ${owner}'s house">. +X<::> X<'> Packages may themselves contain package separators, as in C<$OUTER::INNER::var>. This implies nothing about the order of @@ -57,6 +59,7 @@ have a package called C<m>, C<s>, or C<y>, then you can't use the qualified form of an identifier because it would be instead interpreted as a pattern match, a substitution, or a transliteration. +X<variable, punctuation> Variables beginning with underscore used to be forced into package main, but we decided it was more useful for package writers to be able @@ -83,6 +86,7 @@ and L<perlref> regarding closures. =head2 Symbol Tables +X<symbol table> X<stash> X<%::> X<%main::> X<typeglob> X<glob> X<alias> The symbol table for a package happens to be stored in the hash of that name with two colons appended. The main symbol table's name is thus @@ -179,6 +183,7 @@ explicitly. Another use of symbol tables is for making "constant" scalars. +X<constant> X<scalar, constant> *PI = \3.14159265358979; @@ -254,6 +259,7 @@ (see L<perlobj>). =head2 BEGIN, CHECK, INIT and END +X<BEGIN> X<CHECK> X<INIT> X<END> Four specially named code blocks are executed at the beginning and at the end of a running Perl program. These are the C<BEGIN>, C<CHECK>, C<INIT>, and @@ -299,6 +305,7 @@ going to pass to C<exit()>. You can modify C<$?> to change the exit value of the program. Beware of changing C<$?> by accident (e.g. by running something via C<system>). +X<$?> C<CHECK> and C<INIT> code blocks are useful to catch the transition between the compilation phase and the execution phase of the main program. @@ -348,6 +355,7 @@ __END__ =head2 Perl Classes +X<class> X<@ISA> There is no special class syntax in Perl, but a package may act as a class if it provides subroutines to act as methods. Such a @@ -358,6 +366,7 @@ For more on this, see L<perltoot> and L<perlobj>. =head2 Perl Modules +X<module> A module is just a set of related functions in a library file, i.e., a Perl package with the same name as the file. It is specifically @@ -529,6 +538,9 @@ autoloading, the user can say just C<use POSIX> to get it all. =head2 Making your module threadsafe +X<threadsafe> X<thread safe> +X<module, threadsafe> X<module, thread safe> +X<CLONE> X<CLONE_SKIP> X<thread> X<threads> X<ithread> Since 5.6.0, Perl has had support for a new type of threads called interpreter threads (ithreads). These threads can be used explicitly ==== //depot/perl/pod/perlobj.pod#30 (text) ==== Index: perl/pod/perlobj.pod --- perl/pod/perlobj.pod#29~24909~ Mon Jun 20 04:45:02 2005 +++ perl/pod/perlobj.pod Thu Oct 13 04:20:23 2005 @@ -1,4 +1,5 @@ =head1 NAME +X<object> X<OOP> perlobj - Perl objects @@ -34,6 +35,7 @@ We'll cover these points now in more depth. =head2 An Object is Simply a Reference +X<object> X<bless> X<constructor> X<new> Unlike say C++, Perl doesn't provide any special syntax for constructors. A constructor is merely a subroutine that returns a @@ -139,6 +141,7 @@ operated on the object and not on the reference. =head2 A Class is Simply a Package +X<class> X<package> X<@ISA> X<inheritance> Unlike say C++, Perl doesn't provide any special syntax for class definitions. You use a package as a class by putting method @@ -156,6 +159,7 @@ last base class. Several commonly used methods are automatically supplied in the UNIVERSAL class; see L<"Default UNIVERSAL methods"> for more details. +X<UNIVERSAL> X<base class> X<class, base> If a missing method is found in a base class, it is cached in the current class for efficiency. Changing @ISA or defining new @@ -167,10 +171,12 @@ AUTOLOAD is found, this method is called on behalf of the missing method, setting the package global $AUTOLOAD to be the fully qualified name of the method that was intended to be called. +X<AUTOLOAD> If none of that works, Perl finally gives up and complains. If you want to stop the AUTOLOAD inheritance say simply +X<AUTOLOAD> sub AUTOLOAD; @@ -184,6 +190,7 @@ The only problem with this is that you can't sure that you aren't using a piece of the hash that isn't already used. A reasonable workaround is to prepend your fieldname in the hash with the package name. +X<inheritance, method> X<inheritance, data> sub bump { my $self = shift; @@ -191,6 +198,7 @@ } =head2 A Method is Simply a Subroutine +X<method> Unlike say C++, Perl doesn't provide any special syntax for method definition. (It does provide a little syntax for method invocation @@ -228,6 +236,7 @@ } =head2 Method Invocation +X<invocation> X<method> X<arrow> X<< -> >> For various historical and other reasons, Perl offers two equivalent ways to write a method call. The simpler and more common way is to use @@ -268,6 +277,7 @@ As a special case of the above, you may use the C<SUPER> pseudo-class to tell Perl to start looking for the method in the packages named in the current class's C<@ISA> list. +X<SUPER> package MyCritter; use base 'Critter'; # sets @MyCritter::ISA = ('Critter'); @@ -282,6 +292,7 @@ C<SUPER> pseudo-class can only currently be used as a modifier to a method name, but not in any of the other ways that class names are normally used, eg: +X<SUPER> something->SUPER::method(...); # OK SUPER::method(...); # WRONG @@ -298,6 +309,7 @@ my $fred = (reverse "rettirC")->find(reverse "derF"); =head2 Indirect Object Syntax +X<indirect object syntax> X<invocation, indirect> X<indirect> The other way to invoke a method is by using the so-called "indirect object" notation. This syntax was available in Perl 4 long before @@ -363,6 +375,7 @@ familiar with it. =head2 Default UNIVERSAL methods +X<UNIVERSAL> The C<UNIVERSAL> package automatically contains the following methods that are inherited by all other classes: @@ -370,6 +383,7 @@ =over 4 =item isa(CLASS) +X<isa> C<isa> returns I<true> if its object is blessed into a subclass of C<CLASS> @@ -379,6 +393,7 @@ If you need to determine whether you've received a valid invocant, use the C<blessed> function from L<Scalar::Util>: +X<invocant> X<blessed> if (blessed($ref) && $ref->isa( 'Some::Class')) { # ... @@ -388,6 +403,7 @@ blessed into, or C<undef>. =item can(METHOD) +X<can> C<can> checks to see if its object has a method called C<METHOD>, if it does then a reference to the sub is returned, if it does not then @@ -398,6 +414,7 @@ The same caveats for calling C<UNIVERSAL::isa> directly apply here, too. =item VERSION( [NEED] ) +X<VERSION> C<VERSION> returns the version number of the class (package). If the NEED argument is given then it will check that the current version (as @@ -421,6 +438,7 @@ available to your program (and you should not do so). =head2 Destructors +X<destructor> X<DESTROY> When the last reference to an object goes away, the object is automatically destroyed. (This may even be after you exit, if you've @@ -453,6 +471,8 @@ with it for the next six months or so. =head2 Two-Phased Garbage Collection +X<garbage collection> X<GC> X<circular reference> +X<reference, circular> X<DESTROY> X<destructor> For most purposes, Perl uses a fast and simple, reference-based garbage collection system. That means there's an extra ==== //depot/perl/pod/perlop.pod#132 (text) ==== Index: perl/pod/perlop.pod --- perl/pod/perlop.pod#131~25299~ Wed Aug 17 05:33:18 2005 +++ perl/pod/perlop.pod Thu Oct 13 04:20:23 2005 @@ -1,10 +1,12 @@ =head1 NAME +X<operator> perlop - Perl operators and precedence =head1 DESCRIPTION -=head2 Operator Precedence and Associativity +=head2 Operator Precedence and Associativity +X<operator, precedence> X<precedence> X<associativity> Operator precedence and associativity work in Perl more or less like they do in mathematics. @@ -58,6 +60,7 @@ Many operators can be overloaded for objects. See L<overload>. =head2 Terms and List Operators (Leftward) +X<list operator> X<operator, list> X<term> A TERM has the highest precedence in Perl. They include variables, quote and quote-like operators, any expression in parentheses, @@ -119,6 +122,7 @@ as well as L<"I/O Operators">. =head2 The Arrow Operator +X<arrow> X<dereference> X<< -> >> "C<< -> >>" is an infix dereference operator, just as it is in C and C++. If the right side is either a C<[...]>, C<{...}>, or a @@ -134,6 +138,7 @@ or a class name (that is, a package name). See L<perlobj>. =head2 Auto-increment and Auto-decrement +X<increment> X<auto-increment> X<++> X<decrement> X<auto-decrement> X<--> "++" and "--" work as in C. That is, if placed before a variable, they increment or decrement the variable by one before returning the @@ -175,6 +180,7 @@ The auto-decrement operator is not magical. =head2 Exponentiation +X<**> X<exponentiation> X<power> Binary "**" is the exponentiation operator. It binds even more tightly than unary minus, so -2**4 is -(2**4), not (-2)**4. (This is @@ -182,9 +188,11 @@ internally.) =head2 Symbolic Unary Operators +X<unary operator> X<operator, unary> Unary "!" performs logical negation, i.e., "not". See also C<not> for a lower precedence version of this. +X<!> Unary "-" performs arithmetic negation if the operand is numeric. If the operand is an identifier, a string consisting of a minus sign @@ -192,6 +200,7 @@ starts with a plus or minus, a string starting with the opposite sign is returned. One effect of these rules is that -bareword is equivalent to the string "-bareword". +X<-> X<negation, arithmetic> Unary "~" performs bitwise negation, i.e., 1's complement. For example, C<0666 & ~027> is 0640. (See also L<Integer Arithmetic> and @@ -199,18 +208,22 @@ platform-dependent: ~0 is 32 bits wide on a 32-bit platform, but 64 bits wide on a 64-bit platform, so if you are expecting a certain bit width, remember to use the & operator to mask off the excess bits. +X<~> X<negation, binary> Unary "+" has no effect whatsoever, even on strings. It is useful syntactically for separating a function name from a parenthesized expression that would otherwise be interpreted as the complete list of function arguments. (See examples above under L<Terms and List Operators (Leftward)>.) +X<+> Unary "\" creates a reference to whatever follows it. See L<perlreftut> and L<perlref>. Do not confuse this behavior with the behavior of backslash within a string, although both forms do convey the notion of protecting the next thing from interpolation. +X<\> X<reference> X<backslash> =head2 Binding Operators +X<binding> X<operator, binding> X<=~> X<!~> Binary "=~" binds a scalar expression to a pattern match. Certain operations search or modify the string $_ by default. This operator makes that kind @@ -230,10 +243,13 @@ the logical sense. =head2 Multiplicative Operators +X<operator, multiplicative> Binary "*" multiplies two numbers. +X<*> Binary "/" divides two numbers. +X</> X<slash> Binary "%" computes the modulus of two numbers. Given integer operands C<$a> and C<$b>: If C<$b> is positive, then C<$a % $b> is @@ -245,6 +261,7 @@ to the modulus operator as implemented by your C compiler. This operator is not as well defined for negative operands, but it will execute faster. +X<%> X<remainder> X<modulus> X<mod> Binary "x" is the repetition operator. In scalar context or if the left operand is not enclosed in parentheses, it returns a string consisting @@ -253,6 +270,7 @@ parentheses or is a list formed by C<qw/STRING/>, it repeats the list. If the right operand is zero or negative, it returns an empty string or an empty list, depending on the context. +X<x> print '-' x 80; # print row of dashes @@ -263,14 +281,22 @@ =head2 Additive Operators +X<operator, additive> Binary "+" returns the sum of two numbers. +X<+> Binary "-" returns the difference of two numbers. +X<-> Binary "." concatenates two strings. +X<string, concatenation> X<concatenation> +X<cat> X<concat> X<concatenate> X<.> =head2 Shift Operators +X<shift operator> X<operator, shift> X<<< << >>> +X<<< >> >>> X<right shift> X<left shift> X<bitwise shift> +X<shl> X<shr> X<shift, right> X<shift, left> Binary "<<" returns the value of its left argument shifted left by the number of bits specified by the right argument. Arguments should be @@ -293,6 +319,7 @@ of bits is also undefined. =head2 Named Unary Operators +X<operator, named unary> The various named unary operators are treated as functions with one argument, with optional parentheses. @@ -324,42 +351,55 @@ treated like named unary operators, but they don't follow this functional parenthesis rule. That means, for example, that C<-f($file).".bak"> is equivalent to C<-f "$file.bak">. +X<-X> X<filetest> X<operator, filetest> See also L<"Terms and List Operators (Leftward)">. =head2 Relational Operators +X<relational operator> X<operator, relational> Binary "<" returns true if the left argument is numerically less than the right argument. +X<< < >> Binary ">" returns true if the left argument is numerically greater than the right argument. +X<< > >> Binary "<=" returns true if the left argument is numerically less than or equal to the right argument. +X<< <= >> Binary ">=" returns true if the left argument is numerically greater than or equal to the right argument. +X<< >= >> Binary "lt" returns true if the left argument is stringwise less than the right argument. +X<< lt >> Binary "gt" returns true if the left argument is stringwise greater than the right argument. +X<< gt >> Binary "le" returns true if the left argument is stringwise less than or equal to the right argument. +X<< le >> Binary "ge" returns true if the left argument is stringwise greater than or equal to the right argument. +X<< ge >> =head2 Equality Operators +X<equality> X<equal> X<equals> X<operator, equality> Binary "==" returns true if the left argument is numerically equal to the right argument. +X<==> Binary "!=" returns true if the left argument is numerically not equal to the right argument. +X<!=> Binary "<=>" returns -1, 0, or 1 depending on whether the left argument is numerically less than, equal to, or greater than the right @@ -368,24 +408,29 @@ "<=" or ">=" anything (even NaN), so those 5 return false. NaN != NaN returns true, as does NaN != anything else. If your platform doesn't support NaNs then NaN is just a string with numeric value 0. +X<< <=> >> X<spaceship> perl -le '$a = "NaN"; print "No NaN support here" if $a == $a' perl -le '$a = "NaN"; print "NaN support here" if $a != $a' Binary "eq" returns true if the left argument is stringwise equal to the right argument. +X<eq> Binary "ne" returns true if the left argument is stringwise not equal to the right argument. +X<ne> Binary "cmp" returns -1, 0, or 1 depending on whether the left argument is stringwise less than, equal to, or greater than the right argument. +X<cmp> "lt", "le", "ge", "gt" and "cmp" use the collation (sort) order specified by the current locale if C<use locale> is in effect. See L<perllocale>. =head2 Bitwise And +X<operator, bitwise, and> X<bitwise and> X<&> Binary "&" returns its operands ANDed together bit by bit. (See also L<Integer Arithmetic> and L<Bitwise String Operators>.) @@ -396,6 +441,8 @@ print "Even\n" if ($x & 1) == 0; =head2 Bitwise Or and Exclusive Or +X<operator, bitwise, or> X<bitwise or> X<|> X<operator, bitwise, xor> +X<bitwise xor> X<^> Binary "|" returns its operands ORed together bit by bit. (See also L<Integer Arithmetic> and L<Bitwise String Operators>.) @@ -409,6 +456,7 @@ print "false\n" if (8 | 2) != 10; =head2 C-style Logical And +X<&&> X<logical and> X<operator, logical, and> Binary "&&" performs a short-circuit logical AND operation. That is, if the left operand is false, the right operand is not even evaluated. @@ -416,6 +464,7 @@ is evaluated. =head2 C-style Logical Or +X<||> X<operator, logical, or> Binary "||" performs a short-circuit logical OR operation. That is, if the left operand is true, the right operand is not even evaluated. @@ -423,6 +472,7 @@ is evaluated. =head2 C-style Logical Defined-Or +X<//> X<operator, logical, defined-or> Although it has no direct equivalent in C, Perl's C<//> operator is related to its C-style or. In fact, it's exactly the same as C<||>, except that it @@ -464,6 +514,7 @@ Using "or" for assignment is unlikely to do what you want; see below. =head2 Range Operators +X<operator, range> X<range> X<..> X<...> Binary ".." is the range operator, which is really two different operators depending on the context. In list context, it returns a @@ -595,6 +646,7 @@ @list = (2.18 .. 3.14); # same as @list = (2 .. 3); =head2 Conditional Operator +X<operator, conditional> X<operator, ternary> X<ternary> X<?:> Ternary "?:" is the conditional operator, just as in C. It works much like an if-then-else. If the argument before the ? is true, the @@ -634,6 +686,9 @@ $a += ($a % 2) ? 10 : 2; =head2 Assignment Operators +X<assignment> X<operator, assignment> X<=> X<**=> X<+=> X<*=> X<&=> +X<<< <<= >>> X<&&=> X<-=> X</=> X<|=> X<<< >>= >>> X<||=> X<.=> +X<%=> X<^=> X<x=> "=" is the ordinary assignment operator. @@ -679,6 +734,7 @@ side of the assignment. =head2 Comma Operator +X<comma> X<operator, comma> X<,> Binary "," is the comma operator. In scalar context it evaluates its left argument, throws that value away, then evaluates its right @@ -714,6 +770,7 @@ login( $username => $password ); =head2 List Operators (Rightward) +X<operator, list, rightward> X<list operator> On the right side of a list operator, it has very low precedence, such that it controls all comma-separated expressions found there. @@ -727,11 +784,13 @@ See also discussion of list operators in L<Terms and List Operators (Leftward)>. =head2 Logical Not +X<operator, logical, not> X<not> Unary "not" returns the logical negation of the expression to its right. It's the equivalent of "!" except for the very low precedence. =head2 Logical And +X<operator, logical, and> X<and> Binary "and" returns the logical conjunction of the two surrounding expressions. It's equivalent to && except for the very low @@ -739,6 +798,9 @@ expression is evaluated only if the left expression is true. =head2 Logical or, Defined or, and Exclusive Or +X<operator, logical, or> X<operator, logical, xor> X<operator, logical, err> +X<operator, logical, defined or> X<operator, logical, exclusive or> +X<or> X<xor> X<err> Binary "or" returns the logical disjunction of the two surrounding expressions. It's equivalent to || except for the very low precedence. @@ -772,6 +834,8 @@ It cannot short circuit, of course. =head2 C Operators Missing From Perl +X<operator, missing from perl> X<&> X<*> +X<typecasting> X<(TYPE)> Here is what C has that Perl doesn't: @@ -793,6 +857,10 @@ =back =head2 Quote and Quote-like Operators +X<operator, quote> X<operator, quote-like> X<q> X<qq> X<qx> X<qw> X<m> +X<qr> X<s> X<tr> X<'> X<''> X<"> X<""> X<//> X<`> X<``> X<<< << >>> +X<escape sequence> X<escape> + While we usually think of quotes as literal values, in Perl they function as operators, providing various kinds of interpolating and @@ -843,6 +911,7 @@ The following escape sequences are available in constructs that interpolate and in transliterations. +X<\t> X<\n> X<\r> X<\f> X<\b> X<\a> X<\e> X<\x> X<\0> X<\c> X<\N> \t tab (HT, TAB) \n newline (NL) @@ -862,6 +931,7 @@ The following escape sequences are available in constructs that interpolate but not in transliterations. +X<\l> X<\u> X<\L> X<\U> X<\E> X<\Q> \l lowercase next char \u uppercase next char @@ -890,6 +960,8 @@ and although they often accept just C<"\012">, they seldom tolerate just C<"\015">. If you get in the habit of using C<"\n"> for networking, you may be burned some day. +X<newline> X<line terminator> X<eol> X<end of line> +X<\n> X<\r> X<\r\n> For constructs that do interpolate, variables beginning with "C<$>" or "C<@>" are interpolated. Subscripted variables such as C<$a[3]> or @@ -919,6 +991,7 @@ variables when used within double quotes. =head2 Regexp Quote-Like Operators +X<operator, regexp> Here are the quote-like operators that apply to pattern matching and related activities. @@ -926,6 +999,7 @@ =over 8 =item ?PATTERN? +X<?> This is just like the C</pattern/> search, except that it matches only once between calls to the reset() operator. This is a useful @@ -946,6 +1020,9 @@ around the year 2168. =item m/PATTERN/cgimosx +X<m> X<operator, match> +X<regexp, options> X<regexp> X<regex, options> X<regex> +X</c> X</i> X</m> X</o> X</s> X</x> =item /PATTERN/cgimosx @@ -1127,6 +1204,7 @@ MiXeD line-noise. That's all! =item q/STRING/ +X<q> X<quote, double> X<'> X<''> =item C<'STRING'> @@ -1139,6 +1217,7 @@ $baz = '\n'; # a two-character string =item qq/STRING/ +X<qq> X<quote, double> X<"> X<""> =item "STRING" @@ -1150,6 +1229,7 @@ $baz = "\n"; # a one-character string =item qr/STRING/imosx +X<qr> X</i> X</m> X</o> X</s> X</x> This operator quotes (and possibly compiles) its I<STRING> as a regular expression. I<STRING> is interpolated the same way as I<PATTERN> @@ -1207,6 +1287,7 @@ for a detailed look at the semantics of regular expressions. =item qx/STRING/ +X<qx> X<`> X<``> X<backtick> =item `STRING` @@ -1288,6 +1369,7 @@ See L<"I/O Operators"> for more discussion. =item qw/STRING/ +X<qw> X<quote, list> X<quote, words> Evaluates to a list of the words extracted out of STRING, using embedded whitespace as the word delimiters. It can be understood as being roughly @@ -1316,6 +1398,8 @@ produces warnings if the STRING contains the "," or the "#" character. =item s/PATTERN/REPLACEMENT/egimosx +X<substitute> X<substitution> X<replace> X<regexp, replace> +X<regexp, substitute> X</e> X</g> X</i> X</m> X</o> X</s> X</x> Searches a string for a pattern, and if found, replaces that pattern with the replacement text and returns the number of substitutions @@ -1423,6 +1507,7 @@ 1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e; =item tr/SEARCHLIST/REPLACEMENTLIST/cds +X<tr> X<y> X<transliterate> X</c> X</d> X</s> =item y/SEARCHLIST/REPLACEMENTLIST/cds @@ -1512,6 +1597,7 @@ eval "tr/$oldlist/$newlist/, 1" or die $@; =item <<EOF +X<here-doc> X<heredoc> X<here-document> X<<< << >>> A line-oriented form of quoting is based on the shell "here-document" syntax. Following a C<< << >> you specify a string to terminate @@ -1606,6 +1692,7 @@ =back =head2 Gory details of parsing quoted constructs +X<quote, gory details> When presented with something that might have several different interpretations, Perl uses the B<DWIM> (that's "Do What I Mean") @@ -1686,6 +1773,7 @@ used in parsing. =item Interpolation +X<interpolation> The next step is interpolation in the text obtained, which is now delimiter-independent. There are four different cases. @@ -1799,6 +1887,7 @@ which are processed further. =item Interpolation of regular expressions +X<regexp, interpolation> Previous steps were performed during the compilation of Perl code, but this one happens at run time--although it may be optimized to @@ -1837,6 +1926,7 @@ switch documented in L<perlrun/"Command Switches">. =item Optimization of regular expressions +X<regexp, optimization> This step is listed for completeness only. Since it does not change semantics, details of this step are not documented and are subject @@ -1849,6 +1939,8 @@ =back =head2 I/O Operators +X<operator, i/o> X<operator, io> X<io> X<while> X<filehandle> +X<< <> >> X<@ARGV> There are several I/O operators you should know about. @@ -1868,6 +1960,7 @@ backslash. The generalized form of backticks is C<qx//>. (Because backticks always undergo shell expansion as well, see L<perlsec> for security concerns.) +X<qx> X<`> X<``> X<backtick> X<glob> In scalar context, evaluating a filehandle in angle brackets yields the next line from that file (the newline, if any, included), or @@ -1921,6 +2014,7 @@ rather than global.) Additional filehandles may be created with the open() function, amongst others. See L<perlopentut> and L<perlfunc/open> for details on this. +X<stdin> X<stdout> X<sterr> If a <FILEHANDLE> is used in a context that is looking for a list, a list comprising all input lines is returned, one line per @@ -2066,6 +2160,7 @@ @files = glob($files[$i]); =head2 Constant Folding +X<constant folding> X<folding> Like C, Perl does a certain amount of expression evaluation at compile time whenever it determines that all arguments to an @@ -2088,6 +2183,7 @@ represents so that the interpreter won't have to. =head2 No-ops +X<no-op> X<nop> Perl doesn't officially have a no-op operator, but the bare constants C<0> and C<1> are special-cased to not produce a warning in a void @@ -2096,6 +2192,7 @@ 1 while foo(); =head2 Bitwise String Operators +X<operator, bitwise, string> Bitstrings of any size may be manipulated by the bitwise operators (C<~ | & ^>). @@ -2130,6 +2227,7 @@ in a bit vector. =head2 Integer Arithmetic +X<integer> By default, Perl assumes that it must do most of its arithmetic in floating point. But by saying @@ -2158,6 +2256,7 @@ machines. =head2 Floating-point Arithmetic +X<floating-point> X<floating point> X<float> X<real> While C<use integer> provides integer-only arithmetic, there is no analogous mechanism to provide automatic rounding or truncation to a @@ -2200,6 +2299,7 @@ need yourself. =head2 Bigger Numbers +X<number, arbitrary precision> The standard Math::BigInt and Math::BigFloat modules provide variable-precision arithmetic and overloaded operators, although ==== //depot/perl/pod/perlpod.pod#21 (text) ==== Index: perl/pod/perlpod.pod --- perl/pod/perlpod.pod#20~21137~ Tue Sep 9 02:50:13 2003 +++ perl/pod/perlpod.pod Thu Oct 13 04:20:23 2005 @@ -4,6 +4,7 @@ like "perldoc perlpod". =head1 NAME +X<POD> X<plain old documentation> perlpod - the Plain Old Documentation format @@ -22,6 +23,7 @@ =head2 Ordinary Paragraph +X<POD, ordinary paragraph> Most paragraphs in your documentation will be ordinary blocks of text, like this one. You can simply type in your text without @@ -37,6 +39,7 @@ =head2 Verbatim Paragraph +X<POD, verbatim paragraph> X<verbatim> Verbatim paragraphs are usually used for presenting a codeblock or other text which does not require any special parsing or formatting, @@ -51,6 +54,7 @@ =head2 Command Paragraph +X<POD, command> A command paragraph is used for special treatment of whole chunks of text, usually as headings or parts of lists. @@ -78,6 +82,8 @@ =over =item C<=head1 I<Heading Text>> +X<=head1> X<=head2> X<=head3> X<=head4> +X<head1> X<head2> X<head3> X<head4> =item C<=head2 I<Heading Text>> @@ -102,6 +108,7 @@ "L<Formatting Codes|/"Formatting Codes">" section, below. =item C<=over I<indentlevel>> +X<=over> X<=item> X<=back> X<over> X<item> X<back> =item C<=item I<stuff...>> @@ -157,6 +164,7 @@ =back =item C<=cut> +X<=cut> X<cut> To end a Pod block, use a blank line, then a line beginning with "=cut", and a blank @@ -165,6 +173,7 @@ is not technically necessary, but many older Pod processors require it.) =item C<=pod> +X<=pod> X<pod> The "=pod" command by itself doesn't do much of anything, but it signals to Perl (and Pod formatters) that a Pod block starts here. A @@ -191,6 +200,7 @@ =cut =item C<=begin I<formatname>> +X<=begin> X<=end> X<=for> X<begin> X<end> X<for> =item C<=end I<formatname>> @@ -270,6 +280,7 @@ be for formatting as a footnote). =item C<=encoding I<encodingname>> +X<=encoding> X<encoding> This command is used for declaring the encoding of a document. Most users won't need this; but if your encoding isn't US-ASCII or Latin-1, @@ -321,6 +332,8 @@ =head2 Formatting Codes +X<POD, formatting code> X<formatting code> +X<POD, interior sequence> X<interior sequence> In ordinary paragraphs and in some command paragraphs, various formatting codes (a.k.a. "interior sequences") can be used: @@ -332,11 +345,13 @@ =over =item C<IE<lt>textE<gt>> -- italic text +X<I> X<< IZ<><> >> X<POD, formatting code, italic> X<italic> Used for emphasis ("C<be IE<lt>careful!E<gt>>") and parameters ("C<redo IE<lt>LABELE<gt>>") =item C<BE<lt>textE<gt>> -- bold text +X<B> X<< BZ<><> >> X<POD, formatting code, bold> X<bold> Used for switches ("C<perl's BE<lt>-nE<gt> switch>"), programs ("C<some systems provide a BE<lt>chfnE<gt> for that>"), @@ -344,12 +359,14 @@ ("C<and that feature is known as BE<lt>autovivificationE<gt>>"). =item C<CE<lt>codeE<gt>> -- code text +X<C> X<< CZ<><> >> X<POD, formatting code, code> X<code> Renders code in a typewriter font, or gives some other indication that this represents program text ("C<CE<lt>gmtime($^T)E<gt>>") or some other form of computerese ("C<CE<lt>drwxr-xr-xE<gt>>"). =item C<LE<lt>nameE<gt>> -- a hyperlink +X<L> X<< LZ<><> >> X<POD, formatting code, hyperlink> X<hyperlink> There are various syntaxes, listed below. In the syntaxes given, C<text>, C<name>, and C<section> cannot contain the characters @@ -435,6 +452,7 @@ =back =item C<EE<lt>escapeE<gt>> -- a character escape +X<E> X<< EZ<><> >> X<POD, formatting code, escape> X<escape> Very similar to HTML/XML C<&I<foo>;> "entity references": @@ -487,21 +505,26 @@ =back =item C<FE<lt>filenameE<gt>> -- used for filenames +X<F> X<< FZ<><> >> X<POD, formatting code, filename> X<filename> Typically displayed in italics. Example: "C<FE<lt>.cshrcE<gt>>" =item C<SE<lt>textE<gt>> -- text contains non-breaking spaces +X<S> X<< SZ<><> >> X<POD, formatting code, non-breaking space> +X<non-breaking space> This means that the words in I<text> should not be broken across lines. Example: S<C<SE<lt>$x ? $y : $zE<gt>>>. =item C<XE<lt>topic nameE<gt>> -- an index entry +X<X> X<< XZ<><> >> X<POD, formatting code, index entry> X<index entry> This is ignored by most formatters, but some may use it for building indexes. It always renders as empty-string. Example: C<XE<lt>absolutizing relative URLsE<gt>> =item C<ZE<lt>E<gt>> -- a null (zero-effect) formatting code +X<Z> X<< ZZ<><> >> X<POD, formatting code, null> X<null> This is rarely used. It's one way to get around using an EE<lt>...E<gt> code sometimes. For example, instead of @@ -538,6 +561,7 @@ whitespace right after the opening delimiter and whitespace right before the closing delimiter!> For example, the following will do the trick: +X<POD, formatting code, escaping with multiple brackets> C<< $a <=> $b >> @@ -547,6 +571,7 @@ '<' of the opening delimiter, and immediately precedes the first '>' of the closing delimiter. (The whitespace is ignored.) So the following will also work: +X<POD, formatting code, escaping with multiple brackets> C<<< $a <=> $b >>> C<<<< $a <=> $b >>>> @@ -576,6 +601,7 @@ Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later. =head2 The Intent +X<POD, intent of> The intent is simplicity of use, not power of expression. Paragraphs look like paragraphs (block format), so that they stand out @@ -595,6 +621,7 @@ =head2 Embedding Pods in Perl Modules +X<POD, embedding> You can embed Pod documentation in your Perl modules and scripts. Start your documentation with an empty line, a "=head1" command at the @@ -618,6 +645,7 @@ =over =item * +X<podchecker> X<POD, validating> The B<podchecker> command is provided for checking Pod syntax for errors and warnings. For example, it checks for completely blank lines in ==== //depot/perl/pod/perlre.pod#91 (text) ==== Index: perl/pod/perlre.pod --- perl/pod/perlre.pod#90~24686~ Fri Jun 3 01:04:25 2005 +++ perl/pod/perlre.pod Thu Oct 13 04:20:23 2005 @@ -1,4 +1,5 @@ =head1 NAME +X<regular expression> X<regex> X<regexp> perlre - Perl regular expressions @@ -24,6 +25,8 @@ =over 4 =item i +X</i> X<regex, case-insensitive> X<regexp, case-insensitive> +X<regular expression, case-insensitive> Do case-insensitive pattern matching. @@ -31,12 +34,15 @@ locale. See L<perllocale>. =item m +X</m> X<regex, multiline> X<regexp, multiline> X<regular expression, multiline> Treat string as multiple lines. That is, change "^" and "$" from matching the start or end of the string to matching the start or end of any line anywhere within the string. =item s +X</s> X<regex, single-line> X<regexp, single-line> +X<regular expression, single-line> Treat string as single line. That is, change "." to match any character whatsoever, even a newline, which normally it would not match. @@ -46,6 +52,7 @@ and just before newlines within the string. =item x +X</x> Extend your pattern's legibility by permitting whitespace and comments. @@ -70,6 +77,7 @@ pattern delimiter in the comment--perl has no way of knowing you did not intend to close the pattern early. See the C-comment deletion code in L<perlop>. +X</x> =head2 Regular Expressions @@ -81,6 +89,9 @@ In particular the following metacharacters have their standard I<egrep>-ish meanings: +X<metacharacter> +X<\> X<^> X<.> X<$> X<|> X<(> X<()> X<[> X<[]> + \ Quote the next metacharacter ^ Match the beginning of the line @@ -100,12 +111,15 @@ cost of a little more overhead, you can do this by using the /m modifier on the pattern match operator. (Older programs did this by setting C<$*>, but this practice has been removed in perl 5.9.) +X<^> X<$> X</m> To simplify multi-line substitutions, the "." character never matches a newline unless you use the C</s> modifier, which in effect tells Perl to pretend the string is a single line--even if it isn't. +X<.> X</s> The following standard quantifiers are recognized: +X<metacharacter> X<quantifier> X<*> X<+> X<?> X<{n}> X<{n,}> X<{n,m}> * Match 0 or more times + Match 1 or more times @@ -129,6 +143,8 @@ allowing the rest of the pattern to match. If you want it to match the minimum number of times possible, follow the quantifier with a "?". Note that the meanings don't change, just the "greediness": +X<metacharacter> X<greedy> X<greedyness> +X<?> X<*?> X<+?> X<??> X<{n}?> X<{n,}?> X<{n,m}?> *? Match 0 or more times +? Match 1 or more times @@ -139,6 +155,8 @@ Because patterns are processed as double quoted strings, the following also work: +X<\t> X<\n> X<\r> X<\f> X<\a> X<\l> X<\u> X<\L> X<\U> X<\E> X<\Q> +X<\0> X<\c> X<\N> X<\x> \t tab (HT, TAB) \n newline (LF, NL) @@ -168,6 +186,9 @@ You'll need to write something like C<m/\Quser\E\@\Qhost/>. In addition, Perl defines the following: +X<metacharacter> +X<\w> X<\W> X<\s> X<\S> X<\d> X<\D> X<\X> X<\p> X<\P> X<\C> +X<word> X<whitespace> \w Match a "word" character (alphanumeric plus "_") \W Match a non-"word" character @@ -196,13 +217,18 @@ "\x{2028}, and "\x{2029}", see L<perlunicode> for more details about C<\pP>, C<\PP>, and C<\X>, and L<perluniintro> about Unicode in general. You can define your own C<\p> and C<\P> properties, see L<perlunicode>. +X<\w> X<\W> X<word> The POSIX character class syntax +X<character class> [:class:] is also available. The available classes and their backslash equivalents (if available) are as follows: +X<character class> +X<alpha> X<alnum> X<ascii> X<blank> X<cntrl> X<digit> X<graph> +X<lower> X<print> X<punct> X<space> X<upper> X<word> X<xdigit> alpha alnum @@ -246,6 +272,7 @@ The following equivalences to Unicode \p{} constructs and equivalent backslash character classes (if available), will hold: +X<character class> X<\p> X<\p{}> [:...:] \p{...} backslash @@ -276,6 +303,7 @@ =over 4 =item cntrl +X<cntrl> Any control character. Usually characters that don't produce output as such but instead control the terminal somehow: for example newline and @@ -285,18 +313,22 @@ the ord() value of 127 (C<DEL>). =item graph +X<graph> Any alphanumeric or punctuation (special) character. =item print +X<print> Any alphanumeric or punctuation (special) character or the space character. =item punct +X<punct> Any punctuation (special) character. =item xdigit +X<xdigit> Any hexadecimal digit. Though this may feel silly ([0-9A-Fa-f] would work just fine) it is included for completeness. @@ -305,6 +337,7 @@ You can negate the [::] character classes by prefixing the class name with a '^'. This is a Perl extension. For example: +X<character class, negation> POSIX traditional Unicode @@ -318,6 +351,10 @@ use them will cause an error. Perl defines the following zero-width assertions: +X<zero-width assertion> X<assertion> X<regex, zero-width assertion> +X<regexp, zero-width assertion> +X<regular expression, zero-width assertion> +X<\b> X<\B> X<\A> X<\Z> X<\z> X<\G> \b Match a word boundary \B Match a non-(word boundary) @@ -338,6 +375,7 @@ "^" and "$" will match at every internal line boundary. To match the actual end of the string and not ignore an optional trailing newline, use C<\z>. +X<\b> X<\A> X<\Z> X<\z> X</m> The C<\G> assertion can be used to chain global matches (using C<m//g>), as described in L<perlop/"Regexp Quote-Like Operators">. @@ -350,6 +388,7 @@ is permitted to use it elsewhere, as in C</(?<=\G..)./g>, some such uses (C</.\G/g>, for example) currently cause problems, and it is recommended that you avoid such usage for now. +X<\G> The bracketing construct C<( ... )> creates capture buffers. To refer to the digit'th buffer use \<digit> within the @@ -358,6 +397,8 @@ the match. See the warning below about \1 vs $1 for details.) Referring back to another part of the match is called a I<backreference>. +X<regex, capture buffer> X<regexp, capture buffer> +X<regular expression, capture buffer> X<backreference> There is no limit to the number of captured substrings that you may use. However Perl also uses \10, \11, etc. as aliases for \010, @@ -393,11 +434,15 @@ the most-recently closed group (submatch). C<$^N> can be used in extended patterns (see below), for example to assign a submatch to a variable. +X<$+> X<$^N> X<$&> X<$`> X<$'> The numbered match variables ($1, $2, $3, etc.) and the related punctuation set (C<$+>, C<$&>, C<$`>, C<$'>, and C<$^N>) are all dynamically scoped until the end of the enclosing block or until the next successful match, whichever comes first. (See L<perlsyn/"Compound Statements">.) +X<$+> X<$^N> X<$&> X<$`> X<$'> +X<$1> X<$2> X<$3> X<$4> X<$5> X<$6> X<$7> X<$8> X<$9> + B<NOTE>: failed matches in Perl do not reset the match variables, which makes it easier to write code that tests for a series of more @@ -416,6 +461,7 @@ them), once you've used them once, use them at will, because you've already paid the price. As of 5.005, C<$&> is not so costly as the other two. +X<$&> X<$`> X<$'> Backslashed metacharacters in Perl are alphanumeric, such as C<\b>, C<\w>, C<\n>. Unlike some other regular expression languages, there @@ -463,6 +509,7 @@ =over 10 =item C<(?#text)> +X<(?#)> A comment. The text is ignored. If the C</x> modifier enables whitespace formatting, a simple C<#> will suffice. Note that Perl closes @@ -470,6 +517,7 @@ C<)> in the comment. =item C<(?imsx-imsx)> +X<(?)> One or more embedded pattern-match modifiers, to be turned on (or turned off, if preceded by C<->) for the remainder of the pattern or @@ -497,6 +545,7 @@ group. =item C<(?:pattern)> +X<(?:)> =item C<(?imsx-imsx:pattern)> @@ -522,11 +571,13 @@ /(?:(?s-i)more.*than).*million/i =item C<(?=pattern)> +X<(?=)> X<look-ahead, positive> X<lookahead, positive> A zero-width positive look-ahead assertion. For example, C</\w+(?=\t)/> matches a word followed by a tab, without including the tab in C<$&>. =item C<(?!pattern)> +X<(?!)> X<look-ahead, negative> X<lookahead, negative> A zero-width negative look-ahead assertion. For example C</foo(?!bar)/> matches any occurrence of "foo" that isn't followed by "bar". Note @@ -546,18 +597,21 @@ For look-behind see below. =item C<(?<=pattern)> +X<(?<=)> X<look-behind, positive> X<lookbehind, positive> A zero-width positive look-behind assertion. For example, C</(?<=\t)\w+/> matches a word that follows a tab, without including the tab in C<$&>. Works only for fixed-width look-behind. =item C<(?<!pattern)> +X<(?<!)> X<look-behind, negative> X<lookbehind, negative> A zero-width negative look-behind assertion. For example C</(?<!bar)foo/> matches any occurrence of "foo" that does not follow "bar". Works only for fixed-width look-behind. =item C<(?{ code })> +X<(?{})> X<regex, code in> X<regexp, code in> X<regular expression, code in> B<WARNING>: This extended regular expression feature is considered highly experimental, and may be changed or deleted without notice. @@ -632,6 +686,9 @@ compartment. See L<perlsec> for details about both these mechanisms. =item C<(??{ code })> +X<(??{})> +X<regex, postponed> X<regexp, postponed> X<regular expression, postponed> +X<regex, recursive> X<regexp, recursive> X<regular expression, recursive> B<WARNING>: This extended regular expression feature is considered highly experimental, and may be changed or deleted without notice. @@ -659,6 +716,7 @@ }x; =item C<< (?>pattern) >> +X<backtrack> X<backtracking> B<WARNING>: This extended regular expression feature is considered highly experimental, and may be changed or deleted without notice. @@ -752,6 +810,7 @@ the above specification of comments. =item C<(?(condition)yes-pattern|no-pattern)> +X<(?()> =item C<(?(condition)yes-pattern)> @@ -775,6 +834,7 @@ =back =head2 Backtracking +X<backtrack> X<backtracking> NOTE: This section presents an abstract approximation of regular expression behavior. For a more rigorous (and complicated) view of @@ -981,6 +1041,7 @@ following match, see L<C<< (?>pattern) >>>. =head2 Version 8 Regular Expressions +X<regular expression, version 8> X<regex, version 8> X<regexp, version 8> In case you're not familiar with the "regular" Version 8 regex routines, here are the pattern-matching rules not described above. ==== //depot/perl/pod/perlref.pod#28 (text) ==== Index: perl/pod/perlref.pod --- perl/pod/perlref.pod#27~24686~ Fri Jun 3 01:04:25 2005 +++ perl/pod/perlref.pod Thu Oct 13 04:20:23 2005 @@ -1,4 +1,5 @@ =head1 NAME +X<reference> X<pointer> X<data structure> X<structure> X<struct> perlref - Perl references and nested data structures @@ -34,12 +35,15 @@ The C<*glob> notation is something of a symbolic reference. (Symbolic references are sometimes called "soft references", but please don't call them that; references are confusing enough without useless synonyms.) +X<reference, symbolic> X<reference, soft> +X<symbolic reference> X<soft reference> In contrast, hard references are more like hard links in a Unix file system: They are used to access an underlying object without concern for what its (other) name is. When the word "reference" is used without an adjective, as in the following paragraph, it is usually talking about a hard reference. +X<reference, hard> X<hard reference> References are easy to use in Perl. There is just one overriding principle: Perl does no implicit referencing or dereferencing. When a @@ -48,12 +52,14 @@ tell it explicitly to do so, by dereferencing it. =head2 Making References +X<reference, creation> X<referencing> References can be created in several ways. =over 4 =item 1. +X<\> X<backslash> By using the backslash operator on a variable, subroutine, or value. (This works much like the & (address-of) operator in C.) @@ -75,6 +81,8 @@ you can still use type globs and globrefs as though they were IO handles. =item 2. +X<array, anonymous> X<[> X<[]> X<square bracket> +X<bracket, square> X<arrayref> X<array reference> X<reference, array> A reference to an anonymous array can be created using square brackets: @@ -100,6 +108,8 @@ strings rather than full-fledged scalars). =item 3. +X<hash, anonymous> X<{> X<{}> X<curly bracket> +X<bracket, curly> X<brace> X<hashref> X<hash reference> X<reference, hash> A reference to an anonymous hash can be created using curly brackets: @@ -140,6 +150,8 @@ the expression to mean either the HASH reference, or the BLOCK. =item 4. +X<subroutine, anonymous> X<subroutine, reference> X<reference, subroutine> +X<scope, lexical> X<closure> X<lexical> X<lexical scope> A reference to an anonymous subroutine can be created by using C<sub> without a subname: @@ -196,6 +208,7 @@ that most Perl programmers need trouble themselves about to begin with. =item 5. +X<constructor> X<new> References are often returned by special subroutines called constructors. Perl objects are just references to a special type of object that happens to know @@ -220,12 +233,14 @@ -borderwidth => 2) =item 6. +X<autovivification> References of the appropriate type can spring into existence if you 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. +X<*foo{THING}> X<*> A reference can be created by using a special syntax, lovingly known as the *foo{THING} syntax. *foo{THING} returns a reference to the THING @@ -281,6 +296,7 @@ =back =head2 Using References +X<reference, use> X<dereferencing> X<dereference> That's it for creating references. By now you're probably dying to know how to use references to get back to your long-lost data. There @@ -312,6 +328,7 @@ print $$$$refrefref; =item 2. +X<${}> X<@{}> X<%{}> Anywhere you'd put an identifier (or chain of identifiers) as part of a variable or subroutine name, you can replace the identifier with a @@ -348,6 +365,7 @@ it's presumably referencing. That would be case 3. =item 3. +X<autovivification> X<< -> >> X<arrow> Subroutine calls and lookups of individual array elements arise often enough that it gets cumbersome to use method 2. As a form of @@ -385,6 +403,7 @@ to grow its arrays on demand. Perl does. =item 4. +X<encapsulation> If a reference happens to be a reference to an object, then there are probably methods to access the things referred to, and you should probably @@ -401,6 +420,7 @@ integer representing its storage location in memory. The only useful thing to be done with this is to compare two references numerically to see whether they refer to the same location. +X<reference, numeric context> if ($ref1 == $ref2) { # cheap numeric compare of references print "refs 1 and 2 refer to the same thing\n"; @@ -411,6 +431,7 @@ as the numeric address expressed in hex. The ref() operator returns just the type of thing the reference is pointing to, without the address. See L<perlfunc/ref> for details and examples of its use. +X<reference, string context> The bless() operator may be used to associate the object a reference points to with a package functioning as an object class. See L<perlobj>. @@ -433,6 +454,8 @@ print "That yields @{[$n + 5]} widgets\n"; =head2 Symbolic references +X<reference, symbolic> X<reference, soft> +X<symbolic reference> X<soft reference> We said that references spring into existence as necessary if they are undefined, but we didn't say what happens if a value used as a @@ -536,11 +559,14 @@ string is effectively quoted. =head2 Pseudo-hashes: Using an array as a hash +X<pseudo-hash> X<pseudo hash> X<pseudohash> Pseudo-hashes have been removed from Perl. The 'fields' pragma remains available. =head2 Function Templates +X<scope, lexical> X<closure> X<lexical> X<lexical scope> +X<subroutine, nested> X<sub, nested> X<subroutine, local> X<sub, local> As explained above, an anonymous function with access to the lexical variables visible when that function was compiled, creates a closure. It @@ -616,6 +642,7 @@ function, something not normally supported in Perl. =head1 WARNING +X<reference, string context> X<reference, use as hash key> You may not (usefully) use a reference as the key to a hash. It will be converted into a string: ==== //depot/perl/pod/perlrun.pod#140 (text) ==== Index: perl/pod/perlrun.pod --- perl/pod/perlrun.pod#139~25745~ Thu Oct 13 01:14:32 2005 +++ perl/pod/perlrun.pod Thu Oct 13 04:20:23 2005 @@ -110,6 +110,7 @@ C<exit(0)> is provided to indicate successful completion. =head2 #! and quoting on non-Unix systems +X<hashbang> X<#!> Unix's #! technique can be simulated on other systems: @@ -206,6 +207,7 @@ There is no general solution to all of this. It's just a mess. =head2 Location of Perl +X<perl, location of interpreter> It may seem obvious to say, but Perl is useful only when users can easily find it. When possible, it's good for both F</usr/bin/perl> @@ -227,6 +229,7 @@ use 5.005_54; =head2 Command Switches +X<perl, command switches> X<command switches> As with all standard commands, a single-character switch may be clustered with the following switch, if any. @@ -238,6 +241,7 @@ =over 5 =item B<-0>[I<octal/hexadecimal>] +X<-0> X<$/> specifies the input record separator (C<$/>) as an octal or hexadecimal number. If there are no digits, the null character is the @@ -257,6 +261,7 @@ consists of hexadecimal digits.) =item B<-A[I<module>][=I<assertions>]> +X<-A> Activates the assertions given after the equal sign as a comma-separated list of assertion names or regular expressions. If no assertion name @@ -269,6 +274,7 @@ See L<assertions> and L<assertions::activate>. =item B<-a> +X<-a> X<autosplit> turns on autosplit mode when used with a B<-n> or B<-p>. An implicit split command to the @F array is done as the first thing inside the @@ -286,6 +292,7 @@ An alternate delimiter may be specified using B<-F>. =item B<-C [I<number/list>]> +X<-C> The C<-C> flag controls some Unicode of the Perl Unicode features. @@ -341,6 +348,7 @@ switch was therefore "recycled".) =item B<-c> +X<-c> causes Perl to check the syntax of the program and then exit without executing it. Actually, it I<will> execute C<BEGIN>, C<CHECK>, and @@ -349,6 +357,7 @@ be skipped. =item B<-d> +X<-d> X<-dt> =item B<-dt> @@ -357,6 +366,7 @@ will be used in the code being debugged. =item B<-d:>I<foo[=bar,baz]> +X<-d> X<-dt> =item B<-dt:>I<foo[=bar,baz]> @@ -371,6 +381,7 @@ See L<perldebug>. =item B<-D>I<letters> +X<-D> X<DEBUGGING> X<-DDEBUGGING> =item B<-D>I<number> @@ -430,6 +441,7 @@ See L<perldebug> for details and variations. =item B<-e> I<commandline> +X<-e> may be used to enter one line of program. If B<-e> is given, Perl will not look for a filename in the argument list. Multiple B<-e> @@ -437,6 +449,7 @@ to use semicolons where you would in a normal program. =item B<-f> +X<-f> Disable executing F<$Config{siteperl}/sitecustomize.pl> at startup. @@ -448,16 +461,19 @@ modules in non-standard locations. =item B<-F>I<pattern> +X<-F> specifies the pattern to split on if B<-a> is also in effect. The pattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be put in single quotes. You can't use literal whitespace in the pattern. =item B<-h> +X<-h> prints a summary of the options. =item B<-i>[I<extension>] +X<-i> X<in-place> specifies that files processed by the C<E<lt>E<gt>> construct are to be edited in-place. It does this by renaming the input file, opening the @@ -569,6 +585,7 @@ proceeds from STDIN to STDOUT as might be expected. =item B<-I>I<directory> +X<-I> X<@INC> Directories specified by B<-I> are prepended to the search path for modules (C<@INC>), and also tells the C preprocessor where to search for @@ -576,6 +593,7 @@ searches /usr/include and /usr/lib/perl. =item B<-l>[I<octnum>] +X<-l> X<$/> X<$\> enables automatic line-ending processing. It has two separate effects. First, it automatically chomps C<$/> (the input record @@ -596,6 +614,7 @@ This sets C<$\> to newline and then sets C<$/> to the null character. =item B<-m>[B<->]I<module> +X<-m> X<-M> =item B<-M>[B<->]I<module> @@ -625,6 +644,7 @@ could happen for example if Foo inherits from Exporter.) =item B<-n> +X<-n> causes Perl to assume the following loop around your program, which makes it iterate over filename arguments somewhat like B<sed -n> or @@ -653,6 +673,7 @@ the implicit program loop, just as in B<awk>. =item B<-p> +X<-p> causes Perl to assume the following loop around your program, which makes it iterate over filename arguments somewhat like B<sed>: @@ -675,6 +696,7 @@ the implicit loop, just as in B<awk>. =item B<-P> +X<-P> B<NOTE: Use of -P is strongly discouraged because of its inherent problems, including poor portability.> @@ -740,6 +762,7 @@ =back =item B<-s> +X<-s> enables rudimentary switch parsing for switches on the command line after the program name but before any filename arguments (or before @@ -757,6 +780,7 @@ warnings enabled you may get a lot of spurious "used only once" warnings. =item B<-S> +X<-S> makes Perl use the PATH environment variable to search for the program (unless the name of the program contains directory separators). @@ -809,6 +833,7 @@ program will be searched for strictly on the PATH. =item B<-t> +X<-t> Like B<-T>, but taint checks will issue warnings rather than fatal errors. These warnings can be controlled normally with C<no warnings @@ -820,6 +845,7 @@ always use the real B<-T>. =item B<-T> +X<-T> forces "taint" checks to be turned on so you can test them. Ordinarily these checks are done only when running setuid or setgid. It's a @@ -832,6 +858,7 @@ that construct. =item B<-u> +X<-u> This obsolete switch causes Perl to dump core after compiling your program. You can then in theory take this core dump and turn it @@ -848,6 +875,7 @@ for details. =item B<-U> +X<-U> allows Perl to do unsafe operations. Currently the only "unsafe" operations are the unlinking of directories while running as superuser, @@ -857,10 +885,12 @@ taint-check warnings. =item B<-v> +X<-v> prints the version and patchlevel of your perl executable. =item B<-V> +X<-V> prints summary of the major perl configuration values and the current values of @INC. @@ -906,6 +936,7 @@ building_on 'linux' '5' '1' '9' now =item B<-w> +X<-w> prints warnings about dubious constructs, such as variable names that are mentioned only once and scalar variables that are used @@ -923,16 +954,19 @@ of warnings; see L<warnings> or L<perllexwarn>. =item B<-W> +X<-W> Enables all warnings regardless of C<no warnings> or C<$^W>. See L<perllexwarn>. =item B<-X> +X<-X> Disables all warnings regardless of C<use warnings> or C<$^W>. See L<perllexwarn>. =item B<-x> +X<-x> =item B<-x> I<directory> @@ -950,23 +984,28 @@ =back =head1 ENVIRONMENT +X<perl, environment variables> =over 12 =item HOME +X<HOME> Used if chdir has no argument. =item LOGDIR +X<LOGDIR> Used if chdir has no argument and HOME is not set. =item PATH +X<PATH> Used in executing subprocesses, and in finding the program if B<-S> is used. =item PERL5LIB +X<PERL5LIB> A list of directories in which to look for Perl library files before looking in the standard library and the current @@ -983,6 +1022,7 @@ use lib "/my/directory"; =item PERL5OPT +X<PERL5OPT> Command-line options (switches). Switches in this variable are taken as if they were on every Perl command line. Only the B<-[CDIMUdmtwA]> @@ -992,6 +1032,7 @@ enabled, and any subsequent options ignored. =item PERLIO +X<PERLIO> A space (or colon) separated list of PerlIO layers. If perl is built to use PerlIO system for IO (the default) these layers effect perl's IO. @@ -1014,12 +1055,14 @@ =over 8 =item :bytes +X<:bytes> A pseudolayer that turns I<off> the C<:utf8> flag for the layer below. Unlikely to be useful on its own in the global PERLIO environment variable. You perhaps were thinking of C<:crlf:bytes> or C<:perlio:bytes>. =item :crlf +X<:crlf> A layer which does CRLF to "\n" translation distinguishing "text" and "binary" files in the manner of MS-DOS and similar operating systems. @@ -1027,23 +1070,27 @@ as being an end-of-file marker.) =item :mmap +X<:mmap> A layer which implements "reading" of files by using C<mmap()> to make (whole) file appear in the process's address space, and then using that as PerlIO's "buffer". =item :perlio +X<:perlio> This is a re-implementation of "stdio-like" buffering written as a PerlIO "layer". As such it will call whatever layer is below it for its operations (typically C<:unix>). =item :pop +X<:pop> An experimental pseudolayer that removes the topmost layer. Use with the same care as is reserved for nitroglycerin. =item :raw +X<:raw> A pseudolayer that manipulates other layers. Applying the C<:raw> layer is equivalent to calling C<binmode($fh)>. It makes the stream @@ -1055,6 +1102,7 @@ binary nature of the stream are also removed or disabled. =item :stdio +X<:stdio> This layer provides PerlIO interface by wrapping system's ANSI C "stdio" library calls. The layer provides both buffering and IO. @@ -1063,10 +1111,12 @@ to do that. =item :unix +X<:unix> Low level layer which calls C<read>, C<write> and C<lseek> etc. =item :utf8 +X<:utf8> A pseudolayer that turns on a flag on the layer below to tell perl that output should be in utf8 and that input should be regarded as @@ -1075,6 +1125,7 @@ use C<:bytes> layer.) =item :win32 +X<:win32> On Win32 platforms this I<experimental> layer uses native "handle" IO rather than unix-like numeric file descriptor layer. Known to be @@ -1102,6 +1153,7 @@ the default under Win32. =item PERLIO_DEBUG +X<PERLIO_DEBUG> If set to the name of a file or device then certain operations of PerlIO sub-system will be logged to that file (opened as append). Typical uses @@ -1118,23 +1170,27 @@ with B<-T>. =item PERLLIB +X<PERLLIB> A list of directories in which to look for Perl library files before looking in the standard library and the current directory. If PERL5LIB is defined, PERLLIB is not used. =item PERL5DB +X<PERL5DB> The command used to load the debugger code. The default is: BEGIN { require 'perl5db.pl' } =item PERL5DB_THREADED +X<PERL5DB_THREADED> If set to a true value, indicates to the debugger that the code being debugged uses threads. =item PERL5SHELL (specific to the Win32 port) +X<PERL5SHELL> May be set to an alternative shell that perl must use internally for executing "backtick" commands or system(). Default is C<cmd.exe /x/d/c> @@ -1150,6 +1206,7 @@ look in COMSPEC to find a shell fit for interactive use). =item PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port) +X<PERL_ALLOW_NON_IFS_LSP> Set to 1 to allow the use of non-IFS compatible LSP's. Perl normally searches for an IFS-compatible LSP because this is required @@ -1164,6 +1221,7 @@ requiring IFS compatibility to work). =item PERL_DEBUG_MSTATS +X<PERL_DEBUG_MSTATS> Relevant only if perl is compiled with the malloc included with the perl distribution (that is, if C<perl -V:d_mymalloc> is 'define'). @@ -1172,12 +1230,14 @@ after compilation. =item PERL_DESTRUCT_LEVEL +X<PERL_DESTRUCT_LEVEL> Relevant only if your perl executable was built with B<-DDEBUGGING>, this controls the behavior of global destruction of objects and other references. See L<perlhack/PERL_DESTRUCT_LEVEL> for more information. =item PERL_DL_NONLAZY +X<PERL_DL_NONLAZY> Set to one to have perl resolve B<all> undefined symbols when it loads a dynamic library. The default behaviour is to resolve symbols when @@ -1186,11 +1246,13 @@ names even if the test suite doesn't call it. =item PERL_ENCODING +X<PERL_ENCODING> If using the C<encoding> pragma without an explicit encoding name, the PERL_ENCODING environment variable is consulted for an encoding name. =item PERL_HASH_SEED +X<PERL_HASH_SEED> (Since Perl 5.8.1.) Used to randomise Perl's internal hash function. To emulate the pre-5.8.1 behaviour, set to an integer (zero means @@ -1216,6 +1278,7 @@ L</PERL_HASH_SEED_DEBUG> for more information. =item PERL_HASH_SEED_DEBUG +X<PERL_HASH_SEED_DEBUG> (Since Perl 5.8.1.) Set to one to display (to STDERR) the value of the hash seed at the beginning of execution. This, combined with @@ -1229,6 +1292,7 @@ See also hash_seed() of L<Hash::Util>. =item PERL_ROOT (specific to the VMS port) +X<PERL_ROOT> A translation concealed rooted logical name that contains perl and the logical device for the @INC path on VMS only. Other logical names that @@ -1237,6 +1301,7 @@ L<perlvms> and in F<README.vms> in the Perl source distribution. =item PERL_SIGNALS +X<PERL_SIGNALS> In Perls 5.8.1 and later. If set to C<unsafe> the pre-Perl-5.8.0 signals behaviour (immediate but unsafe) is restored. If set to @@ -1244,6 +1309,7 @@ See L<perlipc/"Deferred Signals (Safe Signals)">. =item PERL_UNICODE +X<PERL_UNICODE> Equivalent to the B<-C> command-line switch. Note that this is not a boolean variable-- setting this to C<"1"> is not the right way to @@ -1253,6 +1319,7 @@ switch for more information. =item SYS$LOGIN (specific to the VMS port) +X<SYS$LOGIN> Used if chdir has no argument and HOME and LOGDIR are not set. ==== //depot/perl/pod/perlsub.pod#59 (text) ==== Index: perl/pod/perlsub.pod --- perl/pod/perlsub.pod#58~23496~ Fri Nov 12 12:47:19 2004 +++ perl/pod/perlsub.pod Thu Oct 13 04:20:23 2005 @@ -1,10 +1,12 @@ =head1 NAME +X<subroutine> X<function> perlsub - Perl subroutines =head1 SYNOPSIS To declare subroutines: +X<subroutine, declaration> X<sub> sub NAME; # A "forward" declaration. sub NAME(PROTO); # ditto, but with prototypes @@ -17,6 +19,7 @@ sub NAME(PROTO) : ATTRS BLOCK # with prototypes and attributes To define an anonymous subroutine at runtime: +X<subroutine, anonymous> $subref = sub BLOCK; # no proto $subref = sub (PROTO) BLOCK; # with proto @@ -24,10 +27,12 @@ $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes To import subroutines: +X<import> use MODULE qw(NAME1 NAME2 NAME3); To call subroutines: +X<subroutine, call> X<call> NAME(LIST); # & is optional with parentheses. NAME LIST; # Parentheses optional if predeclared/imported. @@ -52,6 +57,7 @@ contain as many or as few scalar elements as you'd like. (Often a function without an explicit return statement is called a subroutine, but there's really no difference from Perl's perspective.) +X<subroutine, parameter> X<parameter> Any arguments passed in show up in the array C<@_>. Therefore, if you called a function with two arguments, those would be stored in @@ -65,6 +71,7 @@ created the element whether or not the element was assigned to.) Assigning to the whole array C<@_> removes that aliasing, and does not update any arguments. +X<subroutine, argument> X<argument> X<@_> The return value of a subroutine is the value of the last expression evaluated by that sub, or the empty list in the case of an empty sub. @@ -76,6 +83,7 @@ value in scalar context, or nothing in void context. If you return one or more aggregates (arrays and hashes), these will be flattened together into one large indistinguishable list. +X<subroutine, return value> X<return value> X<return> Perl does not have named formal parameters. In practice all you do is assign to a C<my()> list of these. Variables that aren't @@ -84,6 +92,7 @@ and L<"Temporary Values via local()">. To create protected environments for a set of functions in a separate package (and probably a separate file), see L<perlmod/"Packages">. +X<formal parameter> X<parameter, formal> Example: @@ -130,6 +139,7 @@ of turning call-by-reference into call-by-value. Otherwise a function is free to do in-place modifications of C<@_> and change its caller's values. +X<call-by-reference> X<call-by-value> upcase_in($v1, $v2); # this changes $v1 and $v2 sub upcase_in { @@ -139,6 +149,7 @@ You aren't allowed to modify constants in this way, of course. If an argument were actually literal and you tried to change it, you'd take a (presumably fatal) exception. For example, this won't work: +X<call-by-reference> X<call-by-value> upcase_in("frederick"); @@ -182,12 +193,14 @@ reference using the C<&$subref()> or C<&{$subref}()> constructs, although the C<< $subref->() >> notation solves that problem. See L<perlref> for more about all that. +X<&> Subroutines may be called recursively. If a subroutine is called using the C<&> form, the argument list is optional, and if omitted, no C<@_> array is set up for the subroutine: the C<@_> array at the time of the call is visible to subroutine instead. This is an efficiency mechanism that new users may wish to avoid. +X<recursion> &foo(1,2,3); # pass three arguments foo(1,2,3); # the same @@ -202,6 +215,7 @@ disables any prototype checking on arguments you do provide. This is partly for historical reasons, and partly for having a convenient way to cheat if you know what you're doing. See L<Prototypes> below. +X<&> Subroutines whose names are in all upper case are reserved to the Perl core, as are modules whose names are in all lower case. A subroutine in @@ -216,6 +230,8 @@ L<perlmod/"BEGIN, CHECK, INIT and END"> =head2 Private Variables via my() +X<my> X<variable, lexical> X<lexical> X<lexical variable> X<scope, lexical> +X<lexical scope> X<attributes, my> Synopsis: @@ -243,6 +259,7 @@ world, including any called subroutines. This is true if it's the same subroutine called from itself or elsewhere--every call gets its own copy. +X<local> This doesn't mean that a C<my> variable declared in a statically enclosing lexical scope would be invisible. Only dynamic scopes @@ -256,6 +273,7 @@ An C<eval()>, however, can see lexical variables of the scope it is being evaluated in, so long as the names aren't hidden by declarations within the C<eval()> itself. See L<perlref>. +X<eval, scope of> The parameter list to my() may be assigned to if desired, which allows you to initialize your variables. (If no initializer is given for a @@ -338,6 +356,7 @@ prefixed with the keyword C<my>, or if there is already a lexical by that name in scope, then a new lexical is created instead. Thus in the loop +X<foreach> X<for> for my $i (1, 2, 3) { some_function(); @@ -345,6 +364,7 @@ the scope of $i extends to the end of the loop, but not beyond it, rendering the value of $i inaccessible within C<some_function()>. +X<foreach> X<for> Some users may wish to encourage the use of lexically scoped variables. As an aid to catching implicit uses to package variables, @@ -409,6 +429,7 @@ this. =head2 Persistent Private Variables +X<static> X<variable, persistent> X<variable, static> X<closure> Just because a lexical variable is lexically (also called statically) scoped to its enclosing block, C<eval>, or C<do> FILE, this doesn't mean that @@ -465,6 +486,8 @@ to create private variables that the whole module can see. =head2 Temporary Values via local() +X<local> X<scope, dynamic> X<dynamic scope> X<variable, local> +X<variable, temporary> B<WARNING>: In general, you should be using C<my> instead of C<local>, because it's faster and safer. Exceptions to this include the global punctuation @@ -520,6 +543,7 @@ variables outside the loop. =head3 Grammatical note on local() +X<local, context> A C<local> is simply a modifier on an lvalue expression. When you assign to a C<local>ized variable, the C<local> doesn't change whether its list is viewed @@ -535,6 +559,7 @@ supplies a scalar context. =head3 Localization of special variables +X<local, special variable> If you localize a special variable, you'll be giving a new value to it, but its magic won't go away. That means that all side-effects related @@ -570,8 +595,10 @@ or hashes (localising individual elements is still okay). See L<perl58delta/"Localising Tied Arrays and Hashes Is Broken"> for more details. +X<local, tie> =head3 Localization of globs +X<local, glob> X<glob> The construct @@ -593,6 +620,7 @@ with C<my $_>), which avoids completely this problem. =head3 Localization of elements of composite types +X<local, composite type element> X<local, array element> X<local, hash element> It's also worth taking a moment to explain what happens when you C<local>ize a member of a composite type (i.e. an array or hash element). @@ -635,6 +663,7 @@ types is subject to change in future. =head2 Lvalue subroutines +X<lvalue> X<subroutine, lvalue> B<WARNING>: Lvalue subroutines are still experimental and the implementation may change in future versions of Perl. @@ -704,6 +733,7 @@ =back =head2 Passing Symbol Table Entries (typeglobs) +X<typeglob> X<*> B<WARNING>: The mechanism described in this section was originally the only way to simulate pass-by-reference in older versions of @@ -746,6 +776,7 @@ L<perldata/"Typeglobs and Filehandles">. =head2 When to Still Use local() +X<local> X<variable, local> Despite the existence of C<my>, there are still three places where the C<local> operator still shines. In fact, in these three places, you @@ -823,6 +854,7 @@ =back =head2 Pass by Reference +X<pass by reference> X<pass-by-reference> X<reference> If you want to pass more than one array or hash into a function--or return them from it--and have them maintain their integrity, then @@ -936,6 +968,7 @@ } =head2 Prototypes +X<prototype> X<subroutine, prototype> Perl supports a very limited kind of compile-time argument checking using function prototyping. If you declare @@ -1036,6 +1069,7 @@ The interesting thing about C<&> is that you can generate new syntax with it, provided it's in the initial position: +X<&> sub try (&@) { my($try,$catch) = @_; @@ -1060,6 +1094,7 @@ is this sounding a little Lispish? (Never mind.)))) And here's a reimplementation of the Perl C<grep> operator: +X<grep> sub mygrep (&@) { my $code = shift; @@ -1113,6 +1148,7 @@ to make the world a better place. =head2 Constant Functions +X<constant> Functions with a prototype of C<()> are potential candidates for inlining. If the result after optimization and constant folding @@ -1168,6 +1204,7 @@ } =head2 Overriding Built-in Functions +X<built-in> X<override> X<CORE> X<CORE::GLOBAL> Many built-in functions may be overridden, though this should be tried only occasionally and for good reason. Typically this might be @@ -1290,6 +1327,7 @@ Finally, some built-ins (e.g. C<exists> or C<grep>) can't be overridden. =head2 Autoloading +X<autoloading> X<AUTOLOAD> If you call a subroutine that is undefined, you would ordinarily get an immediate, fatal error complaining that the subroutine doesn't @@ -1341,6 +1379,7 @@ functions to Perl code in L<perlxs>. =head2 Subroutine Attributes +X<attribute> X<subroutine, attribute> X<attrs> A subroutine declaration or definition may have a list of attributes associated with it. If such an attribute list is present, it is ==== //depot/perl/pod/perlsyn.pod#50 (text) ==== Index: perl/pod/perlsyn.pod --- perl/pod/perlsyn.pod#49~24903~ Mon Jun 20 02:20:40 2005 +++ perl/pod/perlsyn.pod Thu Oct 13 04:20:23 2005 @@ -1,4 +1,5 @@ =head1 NAME +X<syntax> perlsyn - Perl syntax @@ -27,6 +28,7 @@ see L<perltrap> for information about how they differ. =head2 Declarations +X<declaration> X<undef> X<undefined> X<uninitialized> The only things you need to declare in Perl are report formats and subroutines (and sometimes not even subroutines). A variable holds @@ -63,6 +65,7 @@ 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 without defining it by saying C<sub name>, thus: +X<subroutine, declaration> sub myname; $me = myname $0 or die "can't get myname"; @@ -84,12 +87,14 @@ has both compile-time and run-time effects. =head2 Comments +X<comment> X<#> Text from a C<"#"> character until the end of the line is a comment, and is ignored. Exceptions include C<"#"> inside a string or regular expression. =head2 Simple Statements +X<statement> X<semicolon> X<expression> X<;> The only kind of simple statement is an expression evaluated for its side effects. Every simple statement must be terminated with a @@ -102,6 +107,7 @@ as the last item in a statement. =head2 Truth and Falsehood +X<truth> X<falsehood> X<true> X<false> X<!> X<not> X<negation> X<0> The number 0, the strings C<'0'> and C<''>, the empty list C<()>, and C<undef> are all false in a boolean context. All other values are true. @@ -110,6 +116,8 @@ is treated as 0. =head2 Statement Modifiers +X<statement modifier> X<modifier> X<if> X<unless> X<while> +X<until> X<foreach> X<for> Any simple statement may optionally be followed by a I<SINGLE> modifier, just before the terminating semicolon (or block ending). The possible @@ -160,6 +168,7 @@ loop labels. Sorry. You can always put another block inside of it (for C<next>) or around it (for C<last>) to do that sort of thing. For C<next>, just double the braces: +X<next> X<last> X<redo> do {{ next if $x == $y; @@ -167,6 +176,7 @@ }} until $x++ > $z; For C<last>, you have to be more elaborate: +X<last> LOOP: { do { @@ -181,8 +191,11 @@ previously assigned value, or possibly anything else. Don't rely on it. Future versions of perl might do something different from the version of perl you try it out on. Here be dragons. +X<my> =head2 Compound Statements +X<statement, compound> X<block> X<bracket, curly> X<curly bracket> X<brace> +X<{> X<}> X<if> X<unless> X<while> X<until> X<foreach> X<for> X<continue> In Perl, a sequence of statements that defines a scope is called a block. Sometimes a block is delimited by the file containing it (in the case @@ -242,6 +255,7 @@ the C<next> statement. =head2 Loop Control +X<loop control> X<loop, control> X<next> X<last> X<redo> X<continue> The C<next> command starts the next iteration of the loop: @@ -323,6 +337,7 @@ available. Replace any occurrence of C<if BLOCK> by C<if (do BLOCK)>. =head2 For Loops +X<for> X<foreach> Perl's C-style C<for> loop works like the corresponding C<while> loop; that means that this: @@ -344,12 +359,14 @@ in the initialization section of the C<for>, the lexical scope of those variables is exactly the C<for> loop (the body of the loop and the control sections). +X<my> Besides the normal array index looping, C<for> can lend itself to many other interesting applications. Here's one that avoids the problem you get into if you explicitly test for end-of-file on an interactive file descriptor causing your program to appear to hang. +X<eof> X<end-of-file> X<end of file> $on_a_tty = -t STDIN && -t STDOUT; sub prompt { print "yes? " if $on_a_tty } @@ -360,12 +377,14 @@ Using C<readline> (or the operator form, C<< <EXPR> >>) as the conditional of a C<for> loop is shorthand for the following. This behaviour is the same as a C<while> loop conditional. +X<readline> X<< <> >> for ( prompt(); defined( $_ = <STDIN> ); prompt() ) { # do something } =head2 Foreach Loops +X<for> X<foreach> The C<foreach> loop iterates over a normal list value and sets the variable VAR to be each element of the list in turn. If the variable @@ -376,21 +395,25 @@ that variable instead of the global one, but it's still localized to the loop. This implicit localisation occurs I<only> in a C<foreach> loop. +X<my> X<local> The C<foreach> keyword is actually a synonym for the C<for> keyword, so you can use C<foreach> for readability or C<for> for brevity. (Or because the Bourne shell is more familiar to you than I<csh>, so writing C<for> comes more naturally.) If VAR is omitted, C<$_> is set to each value. +X<$_> If any element of LIST is an lvalue, you can modify it by modifying VAR inside the loop. Conversely, if any element of LIST is NOT an lvalue, any attempt to modify that element will fail. In other words, the C<foreach> loop index variable is an implicit alias for each item in the list that you're looping over. +X<alias> If any part of LIST is an array, C<foreach> will get very confused if you add or remove elements within the loop body, for example with C<splice>. So don't do that. +X<splice> C<foreach> probably won't do what you expect if VAR is a tied or other special variable. Don't do that either. @@ -444,6 +467,7 @@ equivalent C<for> loop. =head2 Basic BLOCKs and Switch Statements +X<switch> X<block> X<case> A BLOCK by itself (labeled or not) is semantically equivalent to a loop that executes once. Thus you can use any of the loop control @@ -591,6 +615,7 @@ instead of synthesizing a C<switch> statement. =head2 Goto +X<goto> Although not for the faint of heart, Perl does support a C<goto> statement. There are three forms: C<goto>-LABEL, C<goto>-EXPR, and @@ -626,6 +651,7 @@ C<eval{}> and die() for exception processing can also be a prudent approach. =head2 PODs: Embedded Documentation +X<POD> X<documentation> Perl has a mechanism for intermixing documentation with source code. While it's expecting the beginning of a new statement, if the compiler @@ -673,6 +699,7 @@ of code. =head2 Plain Old Comments (Not!) +X<comment> X<line> X<#> X<preprocessor> X<eval> Perl can process line directives, much like the C preprocessor. Using this, one can control Perl's idea of filenames and line numbers in ==== //depot/perl/pod/perltie.pod#42 (text) ==== Index: perl/pod/perltie.pod --- perl/pod/perltie.pod#41~23410~ Thu Oct 21 08:51:32 2004 +++ perl/pod/perltie.pod Thu Oct 13 04:20:23 2005 @@ -1,4 +1,5 @@ =head1 NAME +X<tie> perltie - how to hide an object class in a simple variable @@ -46,6 +47,7 @@ for you--you need to do that explicitly yourself. =head2 Tying Scalars +X<scalar, tying> A class implementing a tied scalar should define the following methods: TIESCALAR, FETCH, STORE, and possibly UNTIE and/or DESTROY. @@ -74,6 +76,7 @@ =over 4 =item TIESCALAR classname, LIST +X<TIESCALAR> This is the constructor for the class. That means it is expected to return a blessed reference to a new scalar @@ -102,6 +105,7 @@ variable C<$^W> to see whether to emit a bit of noise anyway. =item FETCH this +X<FETCH> This method will be triggered every time the tied variable is accessed (read). It takes no arguments beyond its self reference, which is the @@ -126,6 +130,7 @@ probably the right thing to do. =item STORE this, value +X<STORE> This method will be triggered every time the tied variable is set (assigned). Beyond its self reference, it also expects one (and only one) @@ -159,12 +164,14 @@ } =item UNTIE this +X<UNTIE> This method will be triggered when the C<untie> occurs. This can be useful if the class needs to know when no further calls will be made. (Except DESTROY of course.) See L<The C<untie> Gotcha> below for more details. =item DESTROY this +X<DESTROY> This method will be triggered when the tied variable needs to be destructed. As with other object classes, such a method is seldom necessary, because Perl @@ -185,6 +192,7 @@ TIESCALAR classes are certainly possible. =head2 Tying Arrays +X<array, tying> A class implementing a tied ordinary array should define the following methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps UNTIE and/or DESTROY. @@ -220,6 +228,7 @@ =over 4 =item TIEARRAY classname, LIST +X<TIEARRAY> This is the constructor for the class. That means it is expected to return a blessed reference through which the new array (probably an @@ -246,6 +255,7 @@ } =item FETCH this, index +X<FETCH> This method will be triggered every time an individual element the tied array is accessed (read). It takes one argument beyond its self reference: the @@ -270,6 +280,7 @@ to keep them at simply one tie type per class. =item STORE this, index, value +X<STORE> This method will be triggered every time an element in the tied array is set (written). It takes two arguments beyond its self reference: the index at @@ -294,6 +305,7 @@ Negative indexes are treated the same as with FETCH. =item FETCHSIZE this +X<FETCHSIZE> Returns the total number of items in the tied array associated with object I<this>. (Equivalent to C<scalar(@array)>). For example: @@ -304,6 +316,7 @@ } =item STORESIZE this, count +X<STORESIZE> Sets the total number of items in the tied array associated with object I<this> to be I<count>. If this makes the array larger then @@ -329,6 +342,7 @@ } =item EXTEND this, count +X<EXTEND> Informative call that array is likely to grow to have I<count> entries. Can be used to optimize allocation. This method need do nothing. @@ -344,6 +358,7 @@ } =item EXISTS this, key +X<EXISTS> Verify that the element at index I<key> exists in the tied array I<this>. @@ -359,6 +374,7 @@ } =item DELETE this, key +X<DELETE> Delete the element at index I<key> from the tied array I<this>. @@ -371,6 +387,7 @@ } =item CLEAR this +X<CLEAR> Clear (remove, delete, ...) all values from the tied array associated with object I<this>. For example: @@ -381,6 +398,7 @@ } =item PUSH this, LIST +X<PUSH> Append elements of I<LIST> to the array. For example: @@ -393,6 +411,7 @@ } =item POP this +X<POP> Remove last element of the array and return it. For example: @@ -402,6 +421,7 @@ } =item SHIFT this +X<SHIFT> Remove the first element of the array (shifting other elements down) and return it. For example: @@ -412,6 +432,7 @@ } =item UNSHIFT this, LIST +X<UNSHIFT> Insert LIST elements at the beginning of the array, moving existing elements up to make room. For example: @@ -427,6 +448,7 @@ } =item SPLICE this, offset, length, LIST +X<SPLICE> Perform the equivalent of C<splice> on the array. @@ -454,10 +476,12 @@ } =item UNTIE this +X<UNTIE> Will be called when C<untie> happens. (See L<The C<untie> Gotcha> below.) =item DESTROY this +X<DESTROY> This method will be triggered when the tied variable needs to be destructed. As with the scalar tie class, this is almost never needed in a @@ -467,6 +491,7 @@ =back =head2 Tying Hashes +X<hash, tying> Hashes were the first Perl data type to be tied (see dbmopen()). A class implementing a tied hash should define the following methods: TIEHASH is @@ -552,6 +577,7 @@ =over 4 =item TIEHASH classname, LIST +X<TIEHASH> This is the constructor for the class. That means it is expected to return a blessed reference through which the new object (probably but not @@ -592,6 +618,7 @@ have been testing the wrong file. =item FETCH this, key +X<FETCH> This method will be triggered every time an element in the tied hash is accessed (read). It takes one argument beyond its self reference: the key @@ -624,6 +651,7 @@ not that concerned. =item STORE this, key, value +X<STORE> This method will be triggered every time an element in the tied hash is set (written). It takes two arguments beyond its self reference: the index at @@ -671,6 +699,7 @@ } =item DELETE this, key +X<DELETE> This method is triggered when we remove an element from the hash, typically by using the delete() function. Again, we'll @@ -697,6 +726,7 @@ the caller whether the file was successfully deleted. =item CLEAR this +X<CLEAR> This method is triggered when the whole hash is to be cleared, usually by assigning the empty list to it. @@ -717,6 +747,7 @@ } =item EXISTS this, key +X<EXISTS> This method is triggered when the user uses the exists() function on a particular hash. In our example, we'll look at the C<{LIST}> @@ -730,6 +761,7 @@ } =item FIRSTKEY this +X<FIRSTKEY> This method will be triggered when the user is going to iterate through the hash, such as via a keys() or each() @@ -743,6 +775,7 @@ } =item NEXTKEY this, lastkey +X<NEXTKEY> This method gets triggered during a keys() or each() iteration. It has a second argument which is the last key that had been accessed. This is @@ -759,6 +792,7 @@ } =item SCALAR this +X<SCALAR> This is called when the hash is evaluated in scalar context. In order to mimic the behaviour of untied hashes, this method should return a @@ -784,10 +818,12 @@ } =item UNTIE this +X<UNTIE> This is called when C<untie> occurs. See L<The C<untie> Gotcha> below. =item DESTROY this +X<DESTROY> This method is triggered when a tied hash is about to go out of scope. You don't really need it unless you're trying to add debugging @@ -812,6 +848,7 @@ untie(%HIST); =head2 Tying FileHandles +X<filehandle, tying> This is partially implemented now. @@ -839,6 +876,7 @@ =over 4 =item TIEHANDLE classname, LIST +X<TIEHANDLE> This is the constructor for the class. That means it is expected to return a blessed reference of some sort. The reference can be used to @@ -847,6 +885,7 @@ sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift } =item WRITE this, LIST +X<WRITE> This method will be called when the handle is written to via the C<syswrite> function. @@ -858,6 +897,7 @@ } =item PRINT this, LIST +X<PRINT> This method will be triggered every time the tied handle is printed to with the C<print()> function. @@ -867,6 +907,7 @@ sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ } =item PRINTF this, LIST +X<PRINTF> This method will be triggered every time the tied handle is printed to with the C<printf()> function. @@ -880,6 +921,7 @@ } =item READ this, LIST +X<READ> This method will be called when the handle is read from via the C<read> or C<sysread> functions. @@ -894,6 +936,7 @@ } =item READLINE this +X<READLINE> This method will be called when the handle is read from via <HANDLE>. The method should return undef when there is no more data. @@ -901,12 +944,14 @@ sub READLINE { $r = shift; "READLINE called $$r times\n"; } =item GETC this +X<GETC> This method will be called when the C<getc> function is called. sub GETC { print "Don't GETC, Get Perl"; return "a"; } =item CLOSE this +X<CLOSE> This method will be called when the handle is closed via the C<close> function. @@ -914,12 +959,14 @@ sub CLOSE { print "CLOSE called.\n" } =item UNTIE this +X<UNTIE> As with the other types of ties, this method will be called when C<untie> happens. It may be appropriate to "auto CLOSE" when this occurs. See L<The C<untie> Gotcha> below. =item DESTROY this +X<DESTROY> As with the other types of ties, this method will be called when the tied handle is about to be destroyed. This is useful for debugging and @@ -938,11 +985,13 @@ print <FOO>; =head2 UNTIE this +X<UNTIE> You can define for all tie types an UNTIE method that will be called at untie(). See L<The C<untie> Gotcha> below. =head2 The C<untie> Gotcha +X<untie> If you intend making use of the object returned from either tie() or tied(), and if the tie's target class defines a destructor, there is a End of Patch.