* Fill out the docs on the yada to show it as a satand in for statements, not expressions

diff --git a/pod/perlop.pod b/pod/perlop.pod
index c062997..a6514bb 100644 (file)
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -816,16 +816,63 @@ between keys and values in hashes, and other paired elements in lists.
 =head2 Yada Yada Operator
 X<...> X<... operator> X<yada yada operator>
 
-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 { ... }
-    foo();
-
-    Unimplemented at <file> line <line number>.
-
-It takes no argument.
+The yada yada operator (noted C<...>) is a placeholder for code. Perl
+parses it without error, but when you try to execute a yada yada, it
+throws an exception with the text C<Unimplemented>:
+
+       sub unimplemented { ... }
+       
+       eval { unimplemented() };
+       if( $@ eq 'Unimplemented' ) {
+         print "I found the yada yada!\n";
+         }
+
+You can only use the yada yada to stand in for a complete statement.
+These examples of the yada yada work:
+
+       { ... }
+       
+       sub foo { ... }
+       
+       ...;
+       
+       eval { ... };
+       
+       sub foo {
+                       my( $self ) = shift;
+                       
+                       ...;
+                       }
+                       
+       do { my $n; ...; print 'Hurrah!' };
+
+The yada yada cannot stand in for an expression that is part of a
+larger statement since the C<...> is also the three-dot version of the
+range operator (see L<Range Operators>). These examples of the yada
+yada are still syntax errors:
+
+       print ...;
+       
+       open my($fh), '>', '/dev/passwd' or ...;
+       
+       if( $condition && ... ) { print "Hello\n" };
+
+There are some cases where Perl can't immediately tell the difference
+between an expression and a statement. For instance, the syntax for a
+block and an anonymous hash reference constructor look the same unless
+there's something in the braces that give Perl a hint. The yada yada
+is a syntax error if Perl doesn't guess that the C<{ ... }> is a
+block. In that case, it doesn't think the C<...> is the yada yada
+because it's expecting an expression instead of a statement:
+
+       my @transformed = map { ... } @input;  # syntax error
+
+You can use a C<;> inside your block to denote that the C<{ ... }> is
+a block and not a hash reference constructor. Now the yada yada works:
+
+       my @transformed = map {; ... } @input; # ; disambiguates
+
+       my @transformed = map { ...; } @input; # ; disambiguates
 
 =head2 List Operators (Rightward)
 X<operator, list, rightward> X<list operator>