mruby-catch

This mrbgem provides catch and throw functionality similar to what is available in standard Ruby. It allows for non-local exits from blocks of code.

catch

The catch method is used to establish a block that can be exited prematurely using throw.

catch(tag) do |current_tag|
  # ... code ...
  if some_condition
    throw(tag, return_value)
  end
  # ... more code ...
end

• With a tag: When catch is called with a tag (any Ruby object), it executes the block. If throw is called with the same tag from within this block (or any method called from within it), the catch block immediately exits and returns the value provided to throw.
• Block completion: If the block executes to completion without throw being called with a matching tag, the catch block returns the result of the last expression evaluated in the block.
• No tag: If catch is called without a tag, a new unique Object is created and used as the tag. This tag is passed as an argument to the block.

catch do |generated_tag|
  # generated_tag is a new Object
  throw(generated_tag, "hello")
end # => "hello"

throw

The throw method is used to initiate a non-local exit to a corresponding catch block.

throw(tag)
throw(tag, value)

• With a tag and value: throw(tag, value) jumps to the innermost active catch block that is waiting for tag. The catch block then returns value.
• With only a tag: throw(tag) is equivalent to throw(tag, nil).
• Uncaught throw: If throw is called with a tag for which there is no matching catch block in the current call stack, an UncaughtThrowError is raised.

UncaughtThrowError

This is a custom error class that inherits from ArgumentError. It is raised when throw is called for a tag that is not currently being caught. It has two attributes:

• tag: The tag that was thrown.
• value: The value that was thrown with the tag.

Example

def check_value(val)
  puts "Checking: #{val}"
  if val < 0
    throw(:negative_value, val)
  elsif val == 0
    throw(:zero_value) # value will be nil
  end
  puts "#{val} is positive"
  val * 2
end

result = catch(:negative_value) do
  puts catch(:zero_value) do
    puts check_value(10)
    puts check_value(-5) # This will throw to :negative_value
    puts check_value(0)  # This would throw to :zero_value, but it's not reached
  end
  puts "This line is skipped if :zero_value is thrown."
end

puts "Result: #{result}"

# Output:
# Checking: 10
# 10 is positive
# 20
# Checking: -5
# Result: -5

puts "--- Next example --- "

result2 = catch do |tag_a|
  catch do |tag_b|
    puts "In tag_b block"
    throw(tag_a, "Exited from A via B")
    puts "This is not printed"
  end
  puts "This is not printed either"
end
puts result2 # => Exited from A via B