Perhaps my personal favorite recommendation for learning to program Ruby like a Rubyist, Eloquent Ruby is a book I recommend frequently to this day. That said, it was released in 2011 and things have changed a bit since then.
This series will focus on reading over Eloquent Ruby, noting things that may have changed or been updated since 2011 (around Ruby 1.9.2) to today (2024 — Ruby 3.3.x).
Chapter 18. Execute Around with a Block
The focus of this chapter is how we start using block functions to wrap our code and transport around values. Sound abstract? Don't worry, we'll get into the examples soon which will make it a lot clearer, and once you see it you'll see it fairly frequently in Ruby programs.
It's no exaggeration to say you'll find block functions everywhere in Ruby, and this is just another way they're used.
Add a Little Logging
Suppose that, as the book mentions, we had a way to store and perform actions against a document like so:
class SomeApplication
def do_something
doc = Document.load("resume.txt")
# Do something interesting with the document
doc.save
end
end
Chances are in a production app we'd want some sort of logging so we'd be able to tell what's happening, as well as debugger information for development. It might look something like this, which may look familiar to you from other languages:
class SomeApplication
def initialize(logger)
@logger = logger
end
def do_something
begin
@logger.debug "Starting Document load"
@doc = Document.load("resume.txt")
@logger.debug "Completed Document load"
rescue
@logger.error "Load failed!"
end
# Do something interesting with the document
begin
@logger.debug "Starting Document save"
@doc.save
@logger.debug "Completed Document save"
rescue
@logger.error "Save failed!"
raise
end
end
end
But as the book mentions we're only really doing two things with a lot of logging around them. Every action is going to add more and more, and it could become difficult to manage. Going with previous parts of the book we might be tempted to pull things out into named methods to simplify a bit:
class SomeApplication
def initialize(logger)
@logger = logger
end
def do_something
@doc = load_with_logging("resume.txt")
# Do something interesting with the document
save_with_logging(@doc)
end
def load_with_logging(file)
@logger.debug "Starting Document load"
doc = Document.load(file)
@logger.debug "Completed Document load"
doc
rescue
@logger.debug "Load failed!"
end
def save_with_logging(doc)
@logger.debug "Starting Document save"
doc.save
@logger.debug "Completed Document save"
rescue
@logger.error "Save failed!"
raise
end
end
...but even that has its drawbacks and only really moves things around. What if there were a better way? Well in Ruby blocks give us a great way to clearly and concisely perform a series of actions around another one, like so:
class SomeApplication
def initialize(logger)
@logger = logger
end
def do_something
with_logging "load" do
@doc = Document.load("resume.txt")
end
# Do something interesting with the document
with_logging "save" do
@doc.save
end
end
def with_logging(description)
@logger.debug "Starting #{description}"
yield
@logger.debug "Complete #{description}"
rescue
@logger.error "#{description} failed!"
end
end
The new with_logging function allows us to call the original code within the block function, but also wraps the idea of logging around it. That lets us get rid of all the logging lines and cleans up our code quite a bit in the process. Even better is that we're only adding a few lines to get all that logging.
As the book mentions this isn't limited to the above code. Because we wrote it in a generic way we could very easily use it for something completely different:
class SomeApplication
def do_something_silly
with_logging "Compute miles in a light year" do
186_000 * 60 * 60 * 24 * 365
end
end
end
That's a lot of the power of block functions, and really functions in general, is we can express the idea of actions more succinctly and more generically than we might with classes. Can you imagine a Loggable module that you'd have to include and conform to an interface to work with? Perhaps in Java, but in Ruby we have a few more tricks to play
When It Absolutely Must Happen
Are we limited to doing actions around something? Not really, we could even get before and after:
def log_before(description)
@logger.debug "Starting #{description}"
yield
end
def log_after(description)
yield
@logger.debug "Done #{description}"
end
The general idea, as the book mentions, is that using blocks allows us to call back to the original code from anywhere inside the method. If you want a quick challenge try and create a method to time something that uses a block function and see where you get. Later in the book it does have an example of this.
Setting Up Objects with an Initialization Block
One idiom in Ruby that can be interesting to see for the first few times is initialization blocks:
class Document
attr_accessor :title, :author, :content
def initialize(title:, author:, content: "")
@title = title
@author = author
@content = content
yield self if block_given?
end
end
Since we're yielding the original class using self we have full access to it inside the block:
new_doc = Document.new(title: "US Constitution", author: "Madison") do |doc|
doc.content << "We the people"
doc.content << "In order to form a more perfect union"
doc.content << "provide for the common defense"
end
Often times people will do this to allow more dynamic configuration of a class on initialization, but it also has a lovely side effect of wrapping it so anything happening inside the block stays in the block unless you happen to manipulate something outside of it.
Dragging Your Scope along with the Block
The book has this habit of progressively explaining a concept through a series of logical steps, of which looking at any step in isolation may yield some weird code. If you find that happening keep reading and see where the book is going with it, as more often than not it is going somewhere with this.
In this particular case the book introduces us to the idea of passing an object into a block function and yielding it back to the block:
class SomeApplication
def initialize(logger)
@logger = logger
end
def do_something
with_logging "load", nil do
@doc = Document.load("resume.txt")
end
# Do something interesting with the document
with_logging "save", @doc do |the_object|
the_object.save
end
end
def with_logging(description, the_object)
@logger.debug "Starting #{description}"
yield(the_object)
@logger.debug "Complete #{description}"
rescue
@logger.error "#{description} failed!"
end
end
As the book mentions it misses the point as any code outside the block is still visible inside the block, which is called closure. The opposite way? Outside can't see inside unless you mutate something on the outside.
The book goes on to mention there's nothing wrong with yielding an argument back to the block, in fact it's rather common as it demonstrates in this code example:
def with_database_connection(connection_info)
connection = Database.new(connection_info)
yield connection
ensure
connection.close
end
In these cases inside of the block function we're in a specific context, the context of a database connection. There are others in Ruby, like the context of an open file, web connection, or several other things.
Carrying the Answers Back
Where blocks really get useful is when you start saving the return value of a block. Take this example code from the book:
def do_something_silly
with_logging "Compute miles in a light year" do
186_000 * 60 * 60 * 24 * 365
end
end
In this case not only are we executing around, but we're also returning the original value:
def with_logging(description)
@logger.debug "Starting #{description}"
return_value = yield
@logger.debug "Completed #{description}"
return_value
rescue
@logger.error "#{description} failed!"
raise
end
The book itself doesn't go here, but a common usecase for this I have handy is timing:
def timed(&block_function)
start_time = Time.now
return_value = block_function.call
end_time = Time.now
puts "Took #{end_time - start_time} to execute"
return_value
end
...and I've gotten a lot of mileage out of it while doing rudimentary debugging. Granted flame graphs and profilers are more useful for heavy lifting, but sometimes I want something drop-dead simple instead and this scratches that itch very well.
Staying Out of Trouble
The book mentions, as it often correctly does, that naming is important. Consider the following:
execute_between_logging_statements "update" do
employee.load
employee.status = :retired
employee.save
end
...as compared to a more generic version:
with_logging "update" do
employee.load
employee.status = :retired
employee.save
end
The latter is clearer and more immediately communicates the intent.
In the Wild
Remember when the yield self bit and the database connection were mentioned earlier as one of a large number of examples in Ruby? File is one of those examples:
# No access to the file
File.open("/etc/passwd") do |f|
# Able to access the file
end
# File is closed
...as are CSV and several other core classes. It's a common idiom, and one to be familiar with.
Speaking of yield self a lot of gem files do the same:
require_relative "lib/rake/version"
Gem::Specification.new do |s|
s.name = "rake"
s.version = Rake::VERSION
s.authors = ["Hiroshi SHIBATA", "Eric Hodel", "Jim Weirich"]
s.email = ["hsbt@ruby-lang.org", "drbrain@segment7.net", ""]
s.summary = "Rake is a Make-like program implemented in Ruby"
s.description = <<~DESCRIPTION
Rake is a Make-like program implemented in Ruby. Tasks and dependencies are
specified in standard Ruby syntax.
# ...
DESCRIPTION
# More below
end
Do note this is an updated version from the one the book mentioned from Rake as it was at the time this article was written.
The other example the book uses is going to look very familiar to the above timing function:
module ActiveRecord
class Migration
# Takes a message argument and outputs it as is.
# A second boolean argument can be passed to specify whether to indent or not.
def say(message, subitem = false)
write "#{subitem ? " ->" : "--"} #{message}"
end
# Outputs text along with how long it took to run its block.
# If the block returns an integer it assumes it is the number of rows affected.
def say_with_time(message)
say(message)
result = nil
time_elapsed = ActiveSupport::Benchmark.realtime { result = yield }
say "%.4fs" % time_elapsed, :subitem
say("#{result} rows", :subitem) if result.is_a?(Integer)
result
end
end
end
The ActiveSupport::Benchmark.realtime { result = yield } is doing just the same thing.
Wrapping Up
Once you see it you can't unsee it. A lot of Ruby uses the idea of wrapping behavior using block functions, and frequently when writing libraries and utilities I'm going to be writing several of these types of methods myself. Whether that's timing, wrapping contexts, doing things before or after, or any number of other tasks this is going to be a frequent tool you use in Ruby.
Top comments (0)