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

1 files changed, 57 insertions, 10 deletions

diff --git a/pod/perlop.pod b/pod/perlop.pod
index c062997e81..a6514bbe9b 100644
--- 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>