This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
legalize =begin foo bar
[perl5.git] / pod / perlop.pod
index 378a74c..40ea2c8 100644 (file)
@@ -602,10 +602,10 @@ Examples:
 As a scalar operator:
 
     if (101 .. 200) { print; } # print 2nd hundred lines, short for
-                               #   if ($. == 101 .. $. == 200) ...
+                               #   if ($. == 101 .. $. == 200) { print; }
 
     next LINE if (1 .. /^$/);  # skip header lines, short for
-                               #   ... if ($. == 1 .. /^$/);
+                               #   next LINE if ($. == 1 .. /^$/);
                                # (typically in a loop labeled LINE)
 
     s/^/> / if (/^$/ .. eof());  # quote body
@@ -615,9 +615,9 @@ As a scalar operator:
         $in_header =   1  .. /^$/;
         $in_body   = /^$/ .. eof;
         if ($in_header) {
-            # ...
+            # do something
         } else { # in body
-            # ...
+            # do something else
         }
     } continue {
         close ARGV if eof;             # reset $. each file
@@ -783,10 +783,17 @@ In list context, it's just the list argument separator, and inserts
 both its arguments into the list.  These arguments are also evaluated
 from left to right.
 
-The C<< => >> operator is a synonym for the comma, but forces any word
-(consisting entirely of word characters) to its left to be interpreted
-as a string (as of 5.001).  This includes words that might otherwise be
-considered a constant or function call.
+The C<< => >> operator is a synonym for the comma except that it causes
+its left operand to be interpreted as a string if it begins with a letter
+or underscore and is composed only of letters, digits and underscores.
+This includes operands that might otherwise be interpreted as operators,
+constants, single number v-strings or function calls. If in doubt about
+this behaviour, the left operand can be quoted explicitly.
+
+Otherwise, the C<< => >> operator behaves exactly as the comma operator
+or list argument separator, according to context.
+
+For example:
 
     use constant FOO => "something";
 
@@ -800,23 +807,17 @@ It is I<NOT>:
 
     my %h = ("something", 23);
 
-If the argument on the left is not a word, it is first interpreted as
-an expression, and then the string value of that is used.
-
 The C<< => >> operator is helpful in documenting the correspondence
 between keys and values in hashes, and other paired elements in lists.
 
         %hash = ( $key => $value );
         login( $username => $password );
 
-=head2 Yada Yada Operators
-X<...> X<... operator> X<!!!> X<!!! operator> X<???> X<??? operator>
-X<yada yada operator>
+=head2 Yada Yada Operator
+X<...> X<... operator> X<yada yada operator>
 
-The yada yada operators are placeholders for code.  They parse without error,
-but when executed either throw an exception or a warning.
-
-The C<...> operator takes no arguments.  When executed, it throws an exception
+The yada yada operator (noted C<...>) is a placeholder for code.
+It parses without error, but when executed it throws an exception
 with the text C<Unimplemented>:
 
     sub foo { ... }
@@ -824,23 +825,7 @@ with the text C<Unimplemented>:
 
     Unimplemented at <file> line <line number>.
 
-The C<!!!> operator is similar, but it takes one argument, a string to use as
-the text of the exception:
-
-    sub bar { !!! "Don't call me, Ishmael!" }
-    bar();
-
-    Don't call me, Ishmael! at <file> line <line number>.
-
-The C<???> operator also takes one argument, but it emits a warning instead of
-throwing an exception:
-
-    sub baz { ??? "Who are you?  Wnat do you want?" }
-    baz();
-    say "Why are you here?";
-
-    Who are you?  What do you want? at <file> line <line number>.
-    Why are you here?
+It takes no argument.
 
 =head2 List Operators (Rightward)
 X<operator, list, rightward> X<list operator>
@@ -1167,11 +1152,13 @@ process modifiers are available:
     c  Do not reset search position on a failed match when /g is in effect.
 
 If "/" is the delimiter then the initial C<m> is optional.  With the C<m>
-you can use any pair of non-alphanumeric, non-whitespace characters
+you can use any pair of non-whitespace characters
 as delimiters.  This is particularly useful for matching path names
 that contain "/", to avoid LTS (leaning toothpick syndrome).  If "?" is
 the delimiter, then the match-only-once rule of C<?PATTERN?> applies.
 If "'" is the delimiter, no interpolation is performed on the PATTERN.
+When using a character valid in an identifier, whitespace is required
+after the C<m>.
 
 PATTERN may contain variables, which will be interpolated (and the
 pattern recompiled) every time the pattern search is evaluated, except
@@ -1309,7 +1296,7 @@ doing different actions depending on which regexp matched.  Each
 regexp tries to match where the previous one leaves off.
 
  $_ = <<'EOL';
-      $url = URI::URL->new( "http://www/" );   die if $url eq "xXx";
+      $url = URI::URL->new( "http://example.com/" ); die if $url eq "xXx";
  EOL
  LOOP:
     {
@@ -1381,13 +1368,13 @@ specific options:
     e  Evaluate the right side as an expression.
     ee  Evaluate the right side as a string then eval the result
 
-Any non-alphanumeric, non-whitespace delimiter may replace the
-slashes.  If single quotes are used, no interpretation is done on the
-replacement string (the C</e> modifier overrides this, however).  Unlike
-Perl 4, Perl 5 treats backticks as normal delimiters; the replacement
-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.,
+Any non-whitespace delimiter may replace the slashes.  Add space after
+the C<s> when using a character allowed in identifiers.  If single quotes
+are used, no interpretation is done on the replacement string (the C</e>
+modifier overrides this, however).  Unlike Perl 4, Perl 5 treats backticks
+as normal delimiters; the replacement 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.,
 C<s(foo)(bar)> or C<< s<foo>/bar/ >>.  A C</e> will cause the
 replacement portion to be treated as a full-fledged Perl expression
 and evaluated right then and there.  It is, however, syntax checked at
@@ -2196,7 +2183,7 @@ to terminate the loop, they should be tested for explicitly:
     while (($_ = <STDIN>) ne '0') { ... }
     while (<STDIN>) { last unless $_; ... }
 
-In other boolean contexts, C<< <I<filehandle>> >> without an
+In other boolean contexts, I<C<E<lt>filehandleE<gt>>> without an
 explicit C<defined> test or comparison elicit a warning if the
 C<use warnings> pragma or the B<-w>
 command-line switch (the C<$^W> variable) is in effect.
@@ -2246,6 +2233,18 @@ internally--<> is just a synonym for <ARGV>, which
 is magical.  (The pseudo code above doesn't work because it treats
 <ARGV> as non-magical.)
 
+Since the null filehandle uses the two argument form of L<perlfunc/open>
+it interprets special characters, so if you have a script like this:
+
+    while (<>) {
+        print;
+    }
+
+and call it with C<perl dangerous.pl 'rm -rfv *|'>, it actually opens a
+pipe, executes the C<rm> command and reads C<rm>'s output from that pipe.
+If you want all items in C<@ARGV> to be interpreted as file names, you
+can use the module C<ARGV::readonly> from CPAN.
+
 You can modify @ARGV before the first <> as long as the array ends up
 containing the list of filenames you really want.  Line numbers (C<$.>)
 continue as though the input were one big happy file.  See the example