ruby-changes:26775
From: drbrain <ko1@a...>
Date: Tue, 15 Jan 2013 15:57:10 +0900 (JST)
Subject: [ruby-changes:26775] drbrain:r38827 (trunk): * doc/syntax/control_expressions.rdoc: Added description of control
drbrain 2013-01-15 15:55:43 +0900 (Tue, 15 Jan 2013) New Revision: 38827 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=38827 Log: * doc/syntax/control_expressions.rdoc: Added description of control expressions in ruby. Added files: trunk/doc/syntax/control_expressions.rdoc Modified files: trunk/ChangeLog Index: doc/syntax/control_expressions.rdoc =================================================================== --- doc/syntax/control_expressions.rdoc (revision 0) +++ doc/syntax/control_expressions.rdoc (revision 38827) @@ -0,0 +1,399 @@ https://github.com/ruby/ruby/blob/trunk/doc/syntax/control_expressions.rdoc#L1 += Control Expressions + +Ruby has a variety of ways to control execution. All the expressions described +here return a value. + +For the tests in these control expressions, +nil+ and +false+ are false-values +and +true+ and any other object are true-values. In this document "true" will +mean "true-value" and "false" will mean "false-value". + +== +if+ Expression + +The simplest +if+ expression has two parts, a "test" expression and a "then" +expression. If the "test" expression evaluates to a true then the "then" +expression is evaluated. + +Here is a simple if statement: + + if true then + puts "the test resulted in a true-value" + end + +This will print "the test resulted in a true-value". + +The +then+ is optional: + + if true + 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. + +You may also add an +else+ expression. If the test does not evaluate to true +the +else+ expression will be executed: + + if false then + puts "the test resulted in a true-value" + else + puts "the test resulted in a false-value" + end + +This will print "the test resulted in a false-value". + +You may add an arbitrary number of extra tests to an if expression using ++elsif+. An +elsif+ executes when all tests above the +elsif+ are false. + + a = 1 + + if a == 0 then + puts "a is zero" + elsif a == 1 then + puts "a is one" + else + puts "a is some other value" + end + +This will print "a is one" as <code>1<code> is not equal to <code>0</code>. +Since +else+ is only executed when there are no matching conditions. + +Once a condition matches, either the +if+ condition or any +elsif+ condition, +the +if+ expression is complete and no further tests will be performed. + +In this example only "a is one" is printed: + + a = 1 + + if a == 0 then + puts "a is zero" + elsif a == 1 then + puts "a is one" + elsif a >= 1 then + puts "a is greater than or equal to one" + else + puts "a is some other value" + end + +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 + # do something to a + end + +The result value of an +if+ expression is the last value executed in the +expression. + +== +unless+ Expression + +The +unless+ expression is the opposite of the +if+ expression. If the value +is false the "then" expression is executed: + + unless true then + puts "the value is a false-value" + end + +This prints nothing as true is not a false-value. + +Note that the above +unless+ expression is the same as: + + if not true then + puts "the value is a false-value" + end + +Like an +if+ expression you may use an +else+ condition with +unless+: + + unless true then + puts "the value is false" + else + puts "the value is true" + end + +This prints "the value is true" from the +else+ condition. + +You may not use +elsif+ with an +unless+ expression. + +The result value of an +unless+ expression is the last value executed in the +expression. + +== Modifier +if+ and +unless+ + ++if+ and +unless+ can also be used to modify an expression. When used as a +modifier the left-hand side is the "then" expression and the right-hand side +is the "test" expression: + + a = 0 + + a += 1 if a.zero? + + p a + +This will print 1. + + a = 0 + + a += 1 unless a.zero? + + p a + +This will print 0. + +While the modifier and standard versions have both a "test" expression and a +"then" expression, they are not exact transformations of each other due to +parse order. Here is an example that shows the difference: + + p a if a = 0.zero? + +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 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. + +The same as true for +unless+. + +== +case+ Expression + +The +case+ expression can be used in two ways. + +The most common way is to compare an object against multiple patterns. The +patterns are matched using the +===+ method which is aliased to +==+ on +Object. Other classes must override it to give meaningful behavior. See +Module#=== and Regexp#=== for examples. + +Here is an example of using +case+ to compare a String against a pattern: + + case "12345" + when /^1/ then + puts "the string starts with one" + else + puts "I don't know what the string starts with" + end + +Here the string <code>"12345"</code> is compared with <code>/^1/</code> by +calling <code>/^1/ === "12345"</code> which returns +true+. Like the +if+ +expression the first +when+ that matches is executed and all other matches are +ignored. + +If no matches are found the +else+ is executed. + +The +else+ and +then+ are optional, this +case+ expression gives the same +result as the one above: + + case "12345" + when /^1/ + puts "the string starts with one" + end + +You may place multiple conditions on the same +when+: + + case "2" + when /^1/, "2" then + puts "the string starts with one or is '2'" + end + +Ruby will try each condition in turn, so first <code>/^1/ === "2"</code> +returns +false+, then <code>"2" === "2"</code> returns +true+, so "the string +starts with one or is '2'" is printed. + +The other way to use a +case+ expression is like an if-elsif expression: + + a = 2 + + case + when a == 1, a == 2 then + puts "a is one or two" + when a == 3 then + puts "a is three" + else + puts "I don't know what a is" + end + +Again, the +then+ and +else+ are optional. + +The result value of a +case+ expression is the last value executed in the +expression. + +== +while+ Loop + +The +while+ loop executes while a condition is true: + + a = 0 + + while a < 10 do + p a + a += 1 + end + + p a + +Prints the numbers 0 through 10. The condition <code>a < 10</code> is checked +before the loop is entered, then the body executes, then the condition is +checked again. When the condition results in false the loop is terminated. + +The +do+ keyword is optional. The following loop is equivalent to the loop +above: + + while a < 10 + p a + a += 1 + end + +The result of a +while+ loop is +nil+ unless +break+ is used to supply a +value. + +== +until+ Loop + +The +until+ loop executes while a condition is false: + + a = 0 + + until a > 10 do + p a + a += 1 + end + + p a + +This prints the numbers 0 through 11. Like a while loop the condition <code>a +> 10</code> is checked when entering the loop and each time the loop body +executes. If the condition is false the loop will continue to execute. + +Like a +while+ loop the +do+ is optional. + +Like a +while+ loop the result of an +until+ loop is nil unless +break+ is +used. + +== +for+ Loop + +The +for+ loop consists of +for+ followed by a variable to contain the +iteration argument followed by +in+ and the value to iterate over using #each. +The +do+ is optional: + + for value in [1, 2, 3] do + puts value + end + +Prints 1, 2 and 3. + +The +for+ loop is similar to using #each, but does not create a new variable +scope. + +The result value of a +for+ loop is the value iterated over unless +break+ is +used. + +The +for+ loop is rarely used in modern ruby programs. + +== Modifier +while+ and +until+ + +Like +if+ and +unless+, +while+ and +until+ can be used as modifiers: + + a = 0 + + a += 1 while a < 10 + + p a # prints 10 + ++until+ used as a modifier: + + a = 0 + + a += 1 until a > 10 + + p a # prints 11 + +You can use +begin+ and +end+ to create a +while+ loop that runs the body once +before the condition: + + a = 0 + + begin + a += 1 + end while a < 10 + + p a # prints 10 + +If you don't use +rescue+ or +ensure+ Ruby optimizes away any exception +handling overhead. + +== +break+ Statement + +Use +break+ to leave a block early. This will stop iterating over the items in +values+ if one of them is even: + + values.each do |value| + break if value.even? + + # ... + end + +You can also terminate from a +while+ loop using +break+: + + a = 0 + + while true do + p a + a += 1 + + break if a < 10 + end + + p a + +This prints the numbers 0 and 1. + ++break+ accepts a value that supplies the result of the expression it is +"breaking" out of: + + result = [1, 2, 3].each do |value| + break value * 2 if value.even? + end + + p result # prints 4 + +== +next+ Statement + +Use +next+ to skip the rest of the current iteration: + + result = [1, 2, 3].map do |value| + next if value.even? + + value * 2 + end + + p result # prints [2, nil, 6] + ++next+ accepts an argument that can be used the result of the current block +iteration: + + result = [1, 2, 3].map do |value| + next value if value.even? + + value * 2 + end + + p result # prints [2, 2, 6] + +== +redo+ Statement + +Use +redo+ to redo the current iteration: + + result = [] + + while result.length < 10 do + result << result.length + + redo if result.last.even? + + result << result.length + 1 + end + + p result + +This prints [0, 1, 3, 3, 5, 5, 7, 7, 9, 9, 11] + Property changes on: doc/syntax/control_expressions.rdoc ___________________________________________________________________ Added: svn:eol-style + LF Index: ChangeLog =================================================================== --- ChangeLog (revision 38826) +++ ChangeLog (revision 38827) @@ -1,3 +1,8 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Tue Jan 15 15:55:28 2013 Eric Hodel <drbrain@s...> + + * doc/syntax/control_expressions.rdoc: Added description of control + expressions in ruby. + Tue Jan 15 13:33:00 2013 Eric Hodel <drbrain@s...> * doc/syntax/methods.rdoc (Method Names): Added method names including -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/