From e071e13068a92c367a87f529926997657c309ce3 Mon Sep 17 00:00:00 2001 From: drbrain Date: Tue, 15 Jan 2013 06:55:43 +0000 Subject: * doc/syntax/control_expressions.rdoc: Added description of control expressions in ruby. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38827 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- doc/syntax/control_expressions.rdoc | 399 ++++++++++++++++++++++++++++++++++++ 1 file changed, 399 insertions(+) create mode 100644 doc/syntax/control_expressions.rdoc (limited to 'doc') diff --git a/doc/syntax/control_expressions.rdoc b/doc/syntax/control_expressions.rdoc new file mode 100644 index 0000000000..8523aea794 --- /dev/null +++ b/doc/syntax/control_expressions.rdoc @@ -0,0 +1,399 @@ += 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 1 is not equal to 0. +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, a = +0.zero?. + +Since the test is true it then executes the "then" expression, p +a. 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 "12345" is compared with /^1/ by +calling /^1/ === "12345" 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 /^1/ === "2" +returns +false+, then "2" === "2" 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 a < 10 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 a +> 10 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] + -- cgit v1.2.3