123456789_123456789_123456789_123456789_123456789_

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 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
  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
  puts "a is zero"
elsif a == 1
  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.

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
  puts "a is zero"
elsif a == 1
  puts "a is one"
elsif a >= 1
  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
  # do something to a
end

The result value of an if expression is the last value executed in the expression.

Ternary if

You may also write a if-then-else expression using ? and :. This ternary if:

input_type = gets =~ /hello/i ? "greeting" : "other"

Is the same as this if expression:

input_type =
  if gets =~ /hello/i
    "greeting"
  else
    "other"
  end

While the ternary if is much shorter to write than the more verbose form, for readability it is recommended that the ternary if is only used for simple conditionals. Also, avoid using multiple ternary conditions in the same expression as this can be confusing.

unless Expression

The unless expression is the opposite of the if expression. If the value is false, the “then” expression is executed:

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
  puts "the value is a false-value"
end

Like an if expression you may use an else condition with unless:

unless true
  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” statement 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” statement, 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 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, a = 0.zero?.

Since the test is true it 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 is 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/
  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"
  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.

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
  puts "a is one or two"
when a == 3
  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.

Since Ruby 2.7, case expressions also provide a more powerful pattern matching feature via the in keyword:

case {a: 1, b: 2, c: 3}
in a: Integer => m
  "matched: #{m}"
else
  "not matched"
end
# => "matched: 1"

The pattern matching syntax is described on its own page.

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.

Like while and until, the do is optional.

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 as 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]

In Ruby 1.8, you could also use retry where you used redo. This is no longer true, now you will receive a SyntaxError when you use retry outside of a rescue block. See Exceptions for proper usage of retry.

Modifier Statements

Ruby’s grammar differentiates between statements and expressions. All expressions are statements (an expression is a type of statement), but not all statements are expressions. Some parts of the grammar accept expressions and not other types of statements, which causes code that looks similar to be parsed differently.

For example, when not used as a modifier, if, else, while, until, and begin are expressions (and also statements). However, when used as a modifier, if, else, while, until and rescue are statements but not expressions.

if true; 1 end # expression (and therefore statement)
1 if true      # statement (not expression)

Statements that are not expressions cannot be used in contexts where an expression is expected, such as method arguments.

puts( 1 if true )      #=> SyntaxError

You can wrap a statement in parentheses to create an expression.

puts((1 if true))      #=> 1

If you put a space between the method name and opening parenthesis, you do not need two sets of parentheses.

puts (1 if true)       #=> 1, because of optional parentheses for method

This is because this is parsed similar to a method call without parentheses. It is equivalent to the following code, without the creation of a local variable:

x = (1 if true)
p x

In a modifier statement, the left-hand side must be a statement and the right-hand side must be an expression.

So in a if b rescue c, because b rescue c is a statement that is not an expression, and therefore is not allowed as the right-hand side of the if modifier statement, the code is necessarily parsed as (a if b) rescue c.

This interacts with operator precedence in such a way that:

stmt if v = expr rescue x
stmt if v = expr unless x

are parsed as:

stmt if v = (expr rescue x)
(stmt if v = expr) unless x

This is because modifier rescue has higher precedence than =, and modifier if has lower precedence than =.

Flip-Flop

The flip-flop is a slightly special conditional expression. One of its typical uses is processing text from ruby one-line programs used with ruby -n or ruby -p.

The form of the flip-flop is an expression that indicates when the flip-flop turns on, .. (or ...), then an expression that indicates when the flip-flop will turn off. While the flip-flop is on it will continue to evaluate to true, and false when off.

Here is an example:

selected = []

0.upto 10 do |value|
  selected << value if value==2..value==8
end

p selected # prints [2, 3, 4, 5, 6, 7, 8]

In the above example, the ‘on’ condition is n==2. The flip-flop is initially ‘off’ (false) for 0 and 1, but becomes ‘on’ (true) for 2 and remains ‘on’ through 8. After 8 it turns off and remains ‘off’ for 9 and 10.

The flip-flop must be used inside a conditional such as !, ? :, not, if, while, unless, until etc. including the modifier forms.

When you use an inclusive range (..), the ‘off’ condition is evaluated when the ‘on’ condition changes:

selected = []

0.upto 5 do |value|
  selected << value if value==2..value==2
end

p selected # prints [2]

Here, both sides of the flip-flop are evaluated so the flip-flop turns on and off only when value equals 2. Since the flip-flop turned on in the iteration it returns true.

When you use an exclusive range (...), the ‘off’ condition is evaluated on the following iteration:

selected = []

0.upto 5 do |value|
  selected << value if value==2...value==2
end

p selected # prints [2, 3, 4, 5]

Here, the flip-flop turns on when value equals 2, but doesn’t turn off on the same iteration. The ‘off’ condition isn’t evaluated until the following iteration and value will never be two again.

throw/catch

throw and catch are used to implement non-local control flow in Ruby. They operate similarly to exceptions, allowing control to pass directly from the place where throw is called to the place where the matching catch is called. The main difference between throw/catch and the use of exceptions is that throw/catch are designed for expected non-local control flow, while exceptions are designed for exceptional control flow situations, such as handling unexpected errors.

When using throw, you provide 1-2 arguments. The first argument is the value for the matching catch. The second argument is optional (defaults to nil), and will be the value that catch returns if there is a matching throw inside the catch block. If no matching throw method is called inside a catch block, the catch method returns the return value of the block passed to it.

def a(n)
  throw :d, :a if n == 0
  b(n)
end

def b(n)
  throw :d, :b if n == 1
  c(n)
end

def c(n)
  throw :d if n == 2
end

4.times.map do |i|
  catch(:d) do
    a(i)
    :default
  end
end
# => [:a, :b, nil, :default]

If the first argument you pass to throw is not handled by a matching catch, an UncaughtThrowError exception will be raised. This is because throw/catch should only be used for expected control flow changes, so using a value that is not already expected is an error.

throw/catch are implemented as Kernel methods (Kernel#throw and Kernel#catch), not as keywords. So they are not usable directly if you are in a BasicObject context. You can use Kernel.throw and Kernel.catch in this case:

BasicObject.new.instance_exec do
  def a
    b
  end

  def b
    c
  end

  def c
    ::Kernel.throw :d, :e
  end

  result = ::Kernel.catch(:d) do
    a
  end
  result # => :e
end