X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlop.pod;h=4781b7fbbea26ea0d52ada404c650f4efa9ee11a;hb=a3cb178b0bad32fa8be934503d051b96a3cb1fea;hp=a8f34c0e57e41524565c168d616066c592c74358;hpb=a034a98d8bfd0fd904012bd5227ce209aaaa0b26;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlop.pod b/pod/perlop.pod index a8f34c0..4781b7f 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -8,7 +8,7 @@ Perl operators have the following associativity and precedence, listed from highest precedence to lowest. Note that all operators borrowed from C keep the same precedence relationship with each other, even where C's precedence is slightly screwy. (This makes learning -Perl easier for C folks.) With very few exceptions, these all +Perl easier for C folks.) With very few exceptions, these all operate on scalar values only, not array values. left terms and list operators (leftward) @@ -16,7 +16,7 @@ operate on scalar values only, not array values. nonassoc ++ -- right ** right ! ~ \ and unary + and - - left =~ !~ + left =~ !~ left * / % x left + - . left << >> @@ -27,7 +27,7 @@ operate on scalar values only, not array values. left | ^ left && left || - nonassoc .. + nonassoc .. ... right ?: right = += -= *= etc. left , => @@ -42,7 +42,7 @@ In the following sections, these operators are covered in precedence order. =head2 Terms and List Operators (Leftward) -Any TERM is of highest precedence of Perl. These includes variables, +A TERM has the highest precedence in Perl. They includes variables, quote and quote-like operators, any expression in parentheses, and any function whose arguments are parenthesized. Actually, there aren't really functions in this sense, just list operators and unary @@ -56,7 +56,7 @@ just like a normal function call. In the absence of parentheses, the precedence of list operators such as C, C, or C is either very high or very low depending on -whether you look at the left side of operator or the right side of it. +whether you are looking at the left side or the right side of the operator. For example, in @ary = (1, 3, sort 4, 2); @@ -81,14 +81,14 @@ Also note that print ($foo & 255) + 1, "\n"; -probably doesn't do what you expect at first glance. See +probably doesn't do what you expect at first glance. See L for more discussion of this. Also parsed as terms are the C and C constructs, as -well as subroutine and method calls, and the anonymous +well as subroutine and method calls, and the anonymous constructors C<[]> and C<{}>. -See also L toward the end of this section, +See also L toward the end of this section, as well as L<"I/O Operators">. =head2 The Arrow Operator @@ -110,7 +110,7 @@ See L. increment or decrement the variable before returning the value, and if placed after, increment or decrement the variable after returning the value. -The auto-increment operator has a little extra built-in magic to it. If +The auto-increment operator has a little extra builtin magic to it. If you increment a variable that is numeric, or that has ever been used in a numeric context, you get a normal increment. If, however, the variable has been used in only string contexts since it was set, and @@ -145,7 +145,7 @@ is returned. One effect of these rules is that C<-bareword> is equivalent to C<"-bareword">. Unary "~" performs bitwise negation, i.e., 1's complement. -(See also L.) +(See also L and L.) Unary "+" has no effect whatsoever, even on strings. It is useful syntactically for separating a function name from a parenthesized expression @@ -162,14 +162,13 @@ thing from interpretation. Binary "=~" binds a scalar expression to a pattern match. Certain operations search or modify the string $_ by default. This operator makes that kind of operation work on some other string. The right argument is a search -pattern, substitution, or translation. The left argument is what is -supposed to be searched, substituted, or translated instead of the default +pattern, substitution, or transliteration. The left argument is what is +supposed to be searched, substituted, or transliterated instead of the default $_. The return value indicates the success of the operation. (If the right argument is an expression rather than a search pattern, -substitution, or translation, it is interpreted as a search pattern at run -time. This is less efficient than an explicit search, because the pattern -must be compiled every time the expression is evaluated--unless you've -used C.) +substitution, or transliteration, it is interpreted as a search pattern at run +time. This can be is less efficient than an explicit search, because the +pattern must be compiled every time the expression is evaluated. Binary "!~" is just like "=~" except the return value is negated in the logical sense. @@ -180,7 +179,12 @@ Binary "*" multiplies two numbers. Binary "/" divides two numbers. -Binary "%" computes the modulus of the two numbers. +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 +C<$a> minus the largest multiple of C<$b> that is not greater than +C<$a>. If C<$b> is negative, then C<$a % $b> is C<$a> minus the +smallest multiple of C<$b> that is not less than C<$a> (i.e. the +result will be less than or equal to zero). Binary "x" is the repetition operator. In a scalar context, it returns a string consisting of the left operand repeated the number of @@ -296,15 +300,15 @@ by the current locale if C is in effect. See L. =head2 Bitwise And Binary "&" returns its operators ANDed together bit by bit. -(See also L.) +(See also L and L.) =head2 Bitwise Or and Exclusive Or Binary "|" returns its operators ORed together bit by bit. -(See also L.) +(See also L and L.) Binary "^" returns its operators XORed together bit by bit. -(See also L.) +(See also L and L.) =head2 C-style Logical And @@ -348,12 +352,12 @@ operators depending on the context. In a list context, it returns an array of values counting (by ones) from the left value to the right value. This is useful for writing C loops and for doing slice operations on arrays. Be aware that under the current implementation, -a temporary array is created, so you'll burn a lot of memory if you +a temporary array is created, so you'll burn a lot of memory if you write something like this: for (1 .. 1_000_000) { # code - } + } In a scalar context, ".." returns a boolean value. The operator is bistable, like a flip-flop, and emulates the line-range (comma) operator @@ -388,7 +392,7 @@ As a scalar operator: As a list operator: for (101 .. 200) { print; } # print $_ 100 times - @foo = @foo[$[ .. $#foo]; # an expensive no-op + @foo = @foo[0 .. $#foo]; # an expensive no-op @foo = @foo[$#foo-4 .. $#foo]; # slice last 5 items The range operator (in a list context) makes use of the magical @@ -417,11 +421,11 @@ like an if-then-else. If the argument before the ? is true, the argument before the : is returned, otherwise the argument after the : is returned. For example: - printf "I have %d dog%s.\n", $n, + printf "I have %d dog%s.\n", $n, ($n == 1) ? '' : "s"; Scalar or list context propagates downward into the 2nd -or 3rd argument, whichever is selected. +or 3rd argument, whichever is selected. $a = $ok ? $b : $c; # get a scalar @a = $ok ? @b : @c; # get an array @@ -447,8 +451,8 @@ is equivalent to $a = $a + 2; although without duplicating any side effects that dereferencing the lvalue -might trigger, such as from tie(). Other assignment operators work similarly. -The following are recognized: +might trigger, such as from tie(). Other assignment operators work similarly. +The following are recognized: **= += *= &= <<= &&= -= /= |= >>= ||= @@ -534,12 +538,12 @@ Address-of operator. (But see the "\" operator for taking a reference.) =item unary * -Dereference-address operator. (Perl's prefix dereferencing +Dereference-address operator. (Perl's prefix dereferencing operators are typed: $, @, %, and &.) =item (TYPE) -Type casting operator. +Type casting operator. =back @@ -551,20 +555,30 @@ pattern matching capabilities. Perl provides customary quote characters for these behaviors, but also provides a way for you to choose your quote character for any of them. In the following table, a C<{}> represents any pair of delimiters you choose. Non-bracketing delimiters use -the same character fore and aft, but the 4 sorts of brackets +the same character fore and aft, but the 4 sorts of brackets (round, angle, square, curly) will all nest. - Customary Generic Meaning Interpolates - '' q{} Literal no - "" qq{} Literal yes - `` qx{} Command yes - qw{} Word list no - // m{} Pattern match yes - s{}{} Substitution yes - tr{}{} Translation no + Customary Generic Meaning Interpolates + '' q{} Literal no + "" qq{} Literal yes + `` qx{} Command yes + qw{} Word list no + // m{} Pattern match yes + s{}{} Substitution yes + tr{}{} Transliteration no (but see below) + +Note that there can be whitespace between the operator and the quoting +characters, except when C<#> is being used as the quoting character. +C is parsed as being the string C, while C is the +operator C followed by a comment. Its argument will be taken from the +next line. This allows you to write: -For constructs that do interpolation, variables beginning with "C<$>" or "C<@>" -are interpolated, as are the following sequences: + s {foo} # Replace foo + {bar} # with bar. + +For constructs that do interpolation, variables beginning with "C<$>" +or "C<@>" are interpolated, as are the following sequences. Within +a transliteration, the first ten of these sequences may be used. \t tab (HT, TAB) \n newline (LF, NL) @@ -576,6 +590,7 @@ are interpolated, as are the following sequences: \033 octal char \x1b hex char \c[ control char + \l lowercase next char \u uppercase next char \L lowercase till \E @@ -615,9 +630,9 @@ patterns local to the current package are reset. This usage is vaguely deprecated, and may be removed in some future version of Perl. -=item m/PATTERN/gimosx +=item m/PATTERN/cgimosx -=item /PATTERN/gimosx +=item /PATTERN/cgimosx Searches a string for a pattern match, and in a scalar context returns true (1) or false (''). If no string is specified via the C<=~> or @@ -630,6 +645,7 @@ when C is in effect. Options are: + c Do not reset search position on a failed match when /g is in effect. g Match globally, i.e., find all occurrences. i Do case-insensitive pattern matching. m Treat string as multiple lines. @@ -640,7 +656,8 @@ Options are: If "/" is the delimiter then the initial C is optional. With the C you can use any pair of non-alphanumeric, non-whitespace characters as delimiters. This is particularly useful for matching Unix path names -that contain "/", to avoid LTS (leaning toothpick syndrome). +that contain "/", to avoid LTS (leaning toothpick syndrome). If "?" is +the delimiter, then the match-only-once rule of C applies. PATTERN may contain variables, which will be interpolated (and the pattern recompiled) every time the pattern search is evaluated. (Note @@ -653,7 +670,7 @@ C constitutes a promise that you won't change the variables in the pattern. If you change them, Perl won't even notice. If the PATTERN evaluates to a null string, the last -successfully executed regular expression is used instead. +successfully matched regular expression is used instead. If used in a context that requires a list value, a pattern match returns a list consisting of the subexpressions matched by the parentheses in the @@ -692,35 +709,93 @@ If there are no parentheses, it returns a list of all the matched strings, as if there were parentheses around the whole pattern. In a scalar context, C iterates through the string, returning TRUE -each time it matches, and FALSE when it eventually runs out of -matches. (In other words, it remembers where it left off last time and -restarts the search at that point. You can actually find the current -match position of a string using the pos() function--see L.) -If you modify the string in any way, the match position is reset to the -beginning. Examples: +each time it matches, and FALSE when it eventually runs out of matches. +(In other words, it remembers where it left off last time and restarts +the search at that point. You can actually find the current match +position of a string or set it using the pos() function; see +L.) A failed match normally resets the search position to +the beginning of the string, but you can avoid that by adding the C +modifier (e.g. C). Modifying the target string also resets the +search position. + +You can intermix C matches with C, where C<\G> is a +zero-width assertion that matches the exact position where the previous +C, if any, left off. The C<\G> assertion is not supported without +the C modifier; currently, without C, C<\G> behaves just like +C<\A>, but that's accidental and may change in the future. + +Examples: # list context ($one,$five,$fifteen) = (`uptime` =~ /(\d+\.\d+)/g); # scalar context $/ = ""; $* = 1; # $* deprecated in modern perls - while ($paragraph = <>) { + while (defined($paragraph = <>)) { while ($paragraph =~ /[a-z]['")]*[.!?]+['")]*\s/g) { $sentences++; } } print "$sentences\n"; + # using m//gc with \G + $_ = "ppooqppqq"; + while ($i++ < 2) { + print "1: '"; + print $1 while /(o)/gc; print "', pos=", pos, "\n"; + print "2: '"; + print $1 if /\G(q)/gc; print "', pos=", pos, "\n"; + print "3: '"; + print $1 while /(p)/gc; print "', pos=", pos, "\n"; + } + +The last example should print: + + 1: 'oo', pos=4 + 2: 'q', pos=5 + 3: 'pp', pos=7 + 1: '', pos=7 + 2: 'q', pos=8 + 3: '', pos=8 + +A useful idiom for C-like scanners is C. You can +combine several regexps like this to process a string part-by-part, +doing different actions depending on which regexp matched. Each +regexp tries to match where the previous one leaves off. + + $_ = <<'EOL'; + $url = new URI::URL "http://www/"; die if $url eq "xXx"; + EOL + LOOP: + { + print(" digits"), redo LOOP if /\G\d+\b[,.;]?\s*/gc; + print(" lowercase"), redo LOOP if /\G[a-z]+\b[,.;]?\s*/gc; + print(" UPPERCASE"), redo LOOP if /\G[A-Z]+\b[,.;]?\s*/gc; + print(" Capitalized"), redo LOOP if /\G[A-Z][a-z]+\b[,.;]?\s*/gc; + print(" MiXeD"), redo LOOP if /\G[A-Za-z]+\b[,.;]?\s*/gc; + print(" alphanumeric"), redo LOOP if /\G[A-Za-z0-9]+\b[,.;]?\s*/gc; + print(" line-noise"), redo LOOP if /\G[^A-Za-z0-9]+/gc; + print ". That's all!\n"; + } + +Here is the output (split into several lines): + + line-noise lowercase line-noise lowercase UPPERCASE line-noise + UPPERCASE line-noise lowercase line-noise lowercase line-noise + lowercase lowercase line-noise lowercase lowercase line-noise + MiXeD line-noise. That's all! + =item q/STRING/ =item C<'STRING'> -A single-quoted, literal string. Backslashes are ignored, unless -followed by the delimiter or another backslash, in which case the -delimiter or backslash is interpolated. +A single-quoted, literal string. A backslash represents a backslash +unless followed by the delimiter or another backslash, in which case +the delimiter or backslash is interpolated. $foo = q!I said, "You said, 'She said it.'"!; $bar = q('This is it.'); + $baz = '\n'; # a two-character string =item qq/STRING/ @@ -731,6 +806,7 @@ A double-quoted, interpolated string. $_ .= qq (*** The previous line contains the naughty word "$1".\n) if /(tcl|rexx|python)/; # :-) + $baz = "\n"; # a one-character string =item qx/STRING/ @@ -744,7 +820,25 @@ with $/ or $INPUT_RECORD_SEPARATOR). $today = qx{ date }; -See L for more discussion. +Note that how the string gets evaluated is entirely subject to the +command interpreter on your system. On most platforms, you will have +to protect shell metacharacters if you want them treated literally. +On some platforms (notably DOS-like ones), the shell may not be +capable of dealing with multiline commands, so putting newlines in +the string may not get you what you want. You may be able to evaluate +multiple commands in a single line by separating them with the command +separator character, if your shell supports that (e.g. C<;> on many Unix +shells; C<&> on the Windows NT C shell). + +Beware that some command shells may place restrictions on the length +of the command line. You must ensure your strings don't exceed this +limit after any necessary interpolations. See the platform-specific +release notes for more details about your particular environment. + +Also realize that using this operator frequently leads to unportable +programs. + +See L<"I/O Operators"> for more discussion. =item qw/STRING/ @@ -758,6 +852,11 @@ Some frequently seen examples: use POSIX qw( setlocale localeconv ) @EXPORT = qw( foo bar baz ); +A common mistake is to try to separate the words with comma or to put +comments into a multi-line qw-string. For this reason the C<-w> +switch produce warnings if the STRING contains the "," or the "#" +character. + =item s/PATTERN/REPLACEMENT/egimosx Searches a string for a pattern, and if found, replaces that pattern @@ -793,7 +892,7 @@ Options are: Any non-alphanumeric, non-whitespace delimiter may replace the slashes. If single quotes are used, no interpretation is done on the replacement string (the C modifier overrides this, however). Unlike -Perl 4, Perl 5 treats back-ticks as normal delimiters; the replacement +Perl 4, Perl 5 treats backticks as normal delimiters; the replacement text is not evaluated as a command. If the PATTERN is delimited by bracketing quotes, the REPLACEMENT has its own pair of quotes, which may or may not be bracketing quotes, e.g., @@ -838,7 +937,7 @@ Examples: s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields -Note the use of $ instead of \ in the last example. Unlike +Note the use of $ instead of \ in the last example. Unlike B, we use the \EIE form in only the left hand side. Anywhere else it's $EIE. @@ -857,16 +956,18 @@ to occur. Here are two common cases: =item y/SEARCHLIST/REPLACEMENTLIST/cds -Translates all occurrences of the characters found in the search list +Transliterates all occurrences of the characters found in the search list with the corresponding character in the replacement list. It returns the number of characters replaced or deleted. If no string is -specified via the =~ or !~ operator, the $_ string is translated. (The -string specified with =~ must be a scalar variable, an array element, -or an assignment to one of those, i.e., an lvalue.) For B devotees, -C is provided as a synonym for C. If the SEARCHLIST is -delimited by bracketing quotes, the REPLACEMENTLIST has its own pair of -quotes, which may or may not be bracketing quotes, e.g., C -or C. +specified via the =~ or !~ operator, the $_ string is transliterated. (The +string specified with =~ must be a scalar variable, an array element, a +hash element, or an assignment to one of those, i.e., an lvalue.) +A character range may be specified with a hyphen, so C +does the same replacement as C. +For B devotees, C is provided as a synonym for C. If the +SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has +its own pair of quotes, which may or may not be bracketing quotes, +e.g., C or C. Options: @@ -880,7 +981,7 @@ by SEARCHLIST not found in REPLACEMENTLIST are deleted. (Note that this is slightly more flexible than the behavior of some B programs, which delete anything they find in the SEARCHLIST, period.) If the C modifier is specified, sequences of characters that were -translated to the same character are squashed down to a single instance of the +transliterated to the same character are squashed down to a single instance of the character. If the C modifier is used, the REPLACEMENTLIST is always interpreted @@ -909,13 +1010,13 @@ Examples: tr [\200-\377] [\000-\177]; # delete 8th bit -If multiple translations are given for a character, only the first one is used: +If multiple transliterations are given for a character, only the first one is used: tr/AAA/XYZ/ -will translate any A to X. +will transliterate any A to X. -Note that because the translation table is built at compile time, neither +Note that because the transliteration table is built at compile time, neither the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote interpolation. That means that if you want to use variables, you must use an eval(): @@ -929,8 +1030,8 @@ an eval(): =head2 I/O Operators -There are several I/O operators you should know about. -A string is enclosed by back-ticks (grave accents) first undergoes +There are several I/O operators you should know about. +A string is enclosed by backticks (grave accents) first undergoes variable substitution just like a double quoted string. It is then interpreted as a command, and the output of that command is the value of the pseudo-literal, like in a shell. In a scalar context, a single @@ -943,20 +1044,20 @@ of C<$?>). Unlike in B, no translation is done on the return data--newlines remain newlines. Unlike in any of the shells, single quotes do not hide variable names in the command from interpretation. To pass a $ through to the shell you need to hide it with a backslash. -The generalized form of back-ticks is C. (Because back-ticks -always undergo shell expansion as well, see L for +The generalized form of backticks is C. (Because backticks +always undergo shell expansion as well, see L for security concerns.) Evaluating a filehandle in angle brackets yields the next line from -that file (newline included, so it's never false until end of file, at -which time an undefined value is returned). Ordinarily you must assign -that value to a variable, but there is one situation where an automatic -assignment happens. I the input symbol is the only -thing inside the conditional of a C loop, the value is -automatically assigned to the variable C<$_>. The assigned value is -then tested to see if it is defined. (This may seem like an odd thing -to you, but you'll use the construct in almost every Perl script you -write.) Anyway, the following lines are equivalent to each other: +that file (newline, if any, included), or C at end of file. +Ordinarily you must assign that value to a variable, but there is one +situation where an automatic assignment happens. I the +input symbol is the only thing inside the conditional of a C or +C loop, the value is automatically assigned to the variable +C<$_>. The assigned value is then tested to see if it is defined. +(This may seem like an odd thing to you, but you'll use the construct +in almost every Perl script you write.) Anyway, the following lines +are equivalent to each other: while (defined($_ = )) { print; } while () { print; } @@ -989,7 +1090,7 @@ of filenames. The loop is equivalent to the following Perl-like pseudo code: - unshift(@ARGV, '-') if $#ARGV < $[; + unshift(@ARGV, '-') unless @ARGV; while ($ARGV = shift) { open(ARGV, $ARGV); while () { @@ -1009,7 +1110,7 @@ continue as if the input were one big happy file. (But see example under eof() for how to reset line numbers on each file.) If you want to set @ARGV to your own list of files, go right ahead. If -you want to pass switches into your script, you can use one of the +you want to pass switches into your script, you can use one of the Getopts modules or put a loop on the front like this: while ($_ = $ARGV[0], /^-/) { @@ -1066,7 +1167,7 @@ machine.) Of course, the shortest way to do the above is: Because globbing invokes a shell, it's often faster to call readdir() yourself and do your own grep() on the filenames. Furthermore, due to its current -implementation of using a shell, the glob() routine may get "Arg list too +implementation of using a shell, the glob() routine may get "Arg list too long" errors (unless you've installed tcsh(1L) as F). A glob evaluates its (embedded) argument only when it is starting a new @@ -1084,7 +1185,7 @@ than $file = ; because the latter will alternate between returning a filename and -returning FALSE. +returning FALSE. It you're trying to do variable interpolation, it's definitely better to use the glob() function, because the older notation can cause people @@ -1105,17 +1206,45 @@ compile time. You can say 'Now is the time for all' . "\n" . 'good men to come to.' -and this all reduces to one string internally. Likewise, if +and this all reduces to one string internally. Likewise, if you say foreach $file (@filenames) { if (-s $file > 5 + 100 * 2**16) { ... } - } + } -the compiler will pre-compute the number that +the compiler will precompute the number that expression represents so that the interpreter won't have to. +=head2 Bitwise String Operators + +Bitstrings of any size may be manipulated by the bitwise operators +(C<~ | & ^>). + +If the operands to a binary bitwise op are strings of different sizes, +B and B ops will act as if the shorter operand had additional +zero bits on the right, while the B op will act as if the longer +operand were truncated to the length of the shorter. + + # ASCII-based examples + print "j p \n" ^ " a h"; # prints "JAPH\n" + print "JA" | " ph\n"; # prints "japh\n" + print "japh\nJunk" & '_____'; # prints "JAPH\n"; + print 'p N$' ^ " E bitwise operation. You may explicitly show which type of +operation you intend by using C<""> or C<0+>, as in the examples below. + + $foo = 150 | 105 ; # yields 255 (0x96 | 0x69 is 0xFF) + $foo = '150' | 105 ; # yields 255 + $foo = 150 | '105'; # yields 255 + $foo = '150' | '105'; # yields string '155' (under ASCII) + + $baz = 0+$foo & 0+$bar; # both ops explicitly numeric + $biz = "$foo" ^ "$bar"; # both ops explicitly stringy =head2 Integer Arithmetic @@ -1126,15 +1255,36 @@ floating point. But by saying you may tell the compiler that it's okay to use integer operations from here to the end of the enclosing BLOCK. An inner BLOCK may -countermand this by saying +countermand this by saying no integer; which lasts until the end of that BLOCK. The bitwise operators ("&", "|", "^", "~", "<<", and ">>") always -produce integral results. However, C still has meaning +produce integral results. (But see also L.) +However, C still has meaning for them. By default, their results are interpreted as unsigned integers. However, if C is in effect, their results are interpreted as signed integers. For example, C<~0> usually evaluates to a large integral value. However, C is -1. + +=head2 Floating-point Arithmetic + +While C provides integer-only arithmetic, there is no +similar ways to provide rounding or truncation at a certain number of +decimal places. For rounding to a certain number of digits, sprintf() +or printf() is usually the easiest route. + +The POSIX module (part of the standard perl distribution) implements +ceil(), floor(), and a number of other mathematical and trigonometric +functions. The Math::Complex module (part of the standard perl +distribution) defines a number of mathematical functions that can also +work on real numbers. Math::Complex not as efficient as POSIX, but +POSIX can't work with complex numbers. + +Rounding in financial applications can have serious implications, and +the rounding method used should be specified precisely. In these +cases, it probably pays not to trust whichever system rounding is +being used by Perl, but to instead implement the rounding function you +need yourself.