drbrain	2013-01-16 03:54:54 +0900 (Wed, 16 Jan 2013)

  New Revision: 38844

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=38844

  Log:
    * doc/syntax/control_expressions.rdoc:  Omit optional "then" for if and
      unless expressions.  Improved description of "a if a = 0.zero?"
      NameError.  Note that "do" for for loop is optional.

  Modified files:
    trunk/ChangeLog
    trunk/doc/syntax/control_expressions.rdoc

Index: doc/syntax/control_expressions.rdoc
===================================================================
--- doc/syntax/control_expressions.rdoc	(revision 38843)
+++ doc/syntax/control_expressions.rdoc	(revision 38844)
@@ -27,13 +27,13 @@ The +then+ is optional: https://github.com/ruby/ruby/blob/trunk/doc/syntax/control_expressions.rdoc#L27
     puts "the test resulted in a true-value"
   end
 
-This document will include the optional +then+ for all expressions.  Many
-people omit the +then+ part of the if and other expressions.
+This document will omit the optional +then+ for all expressions as that is the
+most common usage of +if+.
 
 You may also add an +else+ expression.  If the test does not evaluate to true
 the +else+ expression will be executed:
 
-  if false then
+  if false
     puts "the test resulted in a true-value"
   else
     puts "the test resulted in a false-value"
@@ -46,9 +46,9 @@ You may add an arbitrary number of extra https://github.com/ruby/ruby/blob/trunk/doc/syntax/control_expressions.rdoc#L46
 
   a = 1
 
-  if a == 0 then
+  if a == 0
     puts "a is zero"
-  elsif a == 1 then
+  elsif a == 1
     puts "a is one"
   else
     puts "a is some other value"
@@ -60,15 +60,17 @@ Since +else+ is only executed when there https://github.com/ruby/ruby/blob/trunk/doc/syntax/control_expressions.rdoc#L60
 Once a condition matches, either the +if+ condition or any +elsif+ condition,
 the +if+ expression is complete and no further tests will be performed.
 
+Like an +if+, an +elsif+ condition may be followed by a +then+.
+
 In this example only "a is one" is printed:
 
   a = 1
 
-  if a == 0 then
+  if a == 0
     puts "a is zero"
-  elsif a == 1 then
+  elsif a == 1
     puts "a is one"
-  elsif a >= 1 then
+  elsif a >= 1
     puts "a is greater than or equal to one"
   else
     puts "a is some other value"
@@ -77,7 +79,7 @@ In this example only "a is one" is print https://github.com/ruby/ruby/blob/trunk/doc/syntax/control_expressions.rdoc#L79
 The tests for +if+ and +elsif+ may have side-effects.  The most common use of
 side-effect is to cache a value into a local variable:
 
-  if a = object.some_value then
+  if a = object.some_value
     # do something to a
   end
 
@@ -89,21 +91,23 @@ expression. https://github.com/ruby/ruby/blob/trunk/doc/syntax/control_expressions.rdoc#L91
 The +unless+ expression is the opposite of the +if+ expression.  If the value
 is false the "then" expression is executed:
 
-  unless true then
+  unless true
     puts "the value is a false-value"
   end
 
 This prints nothing as true is not a false-value.
 
+You may use an optional +then+ with +unless+ just like +if+.
+
 Note that the above +unless+ expression is the same as:
 
-  if not true then
+  if not true
     puts "the value is a false-value"
   end
 
 Like an +if+ expression you may use an +else+ condition with +unless+:
 
-  unless true then
+  unless true
     puts "the value is false"
   else
     puts "the value is true"
@@ -146,17 +150,18 @@ parse order.  Here is an example that sh https://github.com/ruby/ruby/blob/trunk/doc/syntax/control_expressions.rdoc#L150
 
 This raises the NameError "undefined local variable or method `a'".
 
-When ruby parses this it first encounters +a+ as a method call in the "then"
-expression, then later sees +a+ as a local variable in the "test" expression.
+When ruby parses this expression it first encounters +a+ as a method call in
+the "then" expression, then later it sees the assignment to +a+ in the "test"
+expression and marks +a+ as a local variable.
 
 When running this line it first executes the "test" expression, <code>a =
 0.zero?</code>.
 
-Since the test is true it then executes the "then" expression, <code>p
-a</code>.  Since the +a+ in the body was recorded as a method which does not
-exist the NameError is raised.
+Since the test is true it executes the "then" expression, <code>p a</code>.
+Since the +a+ in the body was recorded as a method which does not exist the
+NameError is raised.
 
-The same as true for +unless+.
+The same is true for +unless+.
 
 == +case+ Expression
 
@@ -170,7 +175,7 @@ Module#=== and Regexp#=== for examples. https://github.com/ruby/ruby/blob/trunk/doc/syntax/control_expressions.rdoc#L175
 Here is an example of using +case+ to compare a String against a pattern:
 
   case "12345"
-  when /^1/ then
+  when /^1/
     puts "the string starts with one"
   else
     puts "I don't know what the string starts with"
@@ -194,7 +199,7 @@ result as the one above: https://github.com/ruby/ruby/blob/trunk/doc/syntax/control_expressions.rdoc#L199
 You may place multiple conditions on the same +when+:
 
   case "2"
-  when /^1/, "2" then
+  when /^1/, "2"
     puts "the string starts with one or is '2'"
   end
 
@@ -202,14 +207,23 @@ Ruby will try each condition in turn, so https://github.com/ruby/ruby/blob/trunk/doc/syntax/control_expressions.rdoc#L207
 returns +false+, then <code>"2" === "2"</code> returns +true+, so "the string
 starts with one or is '2'" is printed.
 
+You may use +then+ after the +when+ condition.  This is most frequently used
+to place the body of the +when+ on a single line.
+
+  case a
+  when 1, 2 then puts "a is one or two
+  when 3    then puts "a is three"
+  else           puts "I don't know what a is"
+  end
+
 The other way to use a +case+ expression is like an if-elsif expression:
 
   a = 2
 
   case
-  when a == 1, a == 2 then
+  when a == 1, a == 2
     puts "a is one or two"
-  when a == 3 then
+  when a == 3
     puts "a is three"
   else
     puts "I don't know what a is"
@@ -282,6 +296,8 @@ The +do+ is optional: https://github.com/ruby/ruby/blob/trunk/doc/syntax/control_expressions.rdoc#L296
 
 Prints 1, 2 and 3.
 
+Like +while+ and +until+, the +do+ is optional.
+
 The +for+ loop is similar to using #each, but does not create a new variable
 scope.
 
Index: ChangeLog
===================================================================
--- ChangeLog	(revision 38843)
+++ ChangeLog	(revision 38844)
@@ -1,3 +1,9 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1
+Wed Jan 16 03:54:28 2013  Eric Hodel  <drbrain@s...>
+
+	* doc/syntax/control_expressions.rdoc:  Omit optional "then" for if and
+	  unless expressions.  Improved description of "a if a = 0.zero?"
+	  NameError.  Note that "do" for for loop is optional.
+
 Wed Jan 16 03:28:47 2013  Eric Hodel  <drbrain@s...>
 
 	* doc/syntax/calling_methods.rdoc:  Link to defining methods.

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/