Let's Read - Eloquent Ruby - Ch 20

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 20. Use Hooks to Keep Your Program Informed

So we're now into the metaprogramming chapters. The very short version of my opinion on it is that it's very powerful potentially, yes, but it's also capable of making your programs substantially harder to reason about for very little gain. When it's needed it's really useful, but as always use your discretion here.

Waking Up to a New Subclass

The chapter starts in on the subject of hooks. What's a hook? Well a way to respond to something happening in your program like an event. One example the book leads with is inherited which is called whenever something inherits the class that defines it:

class SimpleBaseClass
  def self.inherited(new_subclass)
    puts "Hey #{new_subclass} is now a subclass of #{self}!"
  end
end

class ChildClassOne < SimpleBaseClass
end
# STDOUT: Hey ChildClassOne is now a subclass of SimpleBaseClass!

The book brings up a good point here of what one might do with such a feature. The example case it gives is a registry of subclasses like multiple document file types (txt, yaml, xml, etc.)

To demonstrate this it gives us a few examples of subclasses before it gets into the implementation of the base class:

class PlainTextReader < DocumentReader
  def self.can_read?(path)
    # Book - Regex and a potentially unclear operator. `#match?` tends
    # to be a clearer method here.
    /.*\.txt/ =~ path

    # Suggested - File provides the extname method which does a lot of
    # this work for us. Prefer to use this instead.
    File.extname(path) == '.txt'
  end

  def initialize(path)
    @path = path
  end

  def read(path)
    File.open(path) do |f|
      title = f.readline.chomp
      author = f.readline.chomp
      content = f.read.chomp

      Document.new(title:, author:, content:)
    end
  end
end

Looking at this code the book starts by pointing out the can_read? method which is used to determine if this class can handle a certain type of file. Personally I'd also be inclined to turn .txt into a constant and add a few more introspection methods about file types it supports, but that's a preference.

The book goes on to show us a few more example classes for YAML and XML:

class YAMLReader < DocumentReader
  def self.can_read?(path)
    File.extname(path) == '.yaml'
  end

  def initialize(path)
    @path = path
  end

  def read(path)
    # Omitted
  end
end

class XMLReader < DocumentReader
  def self.can_read?(path)
    File.extname(path) == '.xml'
  end

  def initialize(path)
    @path = path
  end

  def read(path)
    # Omitted
  end
end

...and then gets into the underlying base class:

class DocumentReader
  # When something inherits from this we want to "register" it
  def self.inherited(subclass)
    DocumentReader.reader_classes << subclass
  end

  class << self
    attr_reader :reader_class
  end

  @reader_classes = []

  def self.read(path)
    reader = reader_for(path)
    return nil unless reader

    reader.read(path)
  end

  def self.reader_for(path)
    reader_class = DocumentReader.reader_classes.find do |klass|
      klass.can_read?(path)
    end

    return reader_class.new(path) if reader_class
    nil
  end

  # One critical bit omitted, but stay tuned...
end

Notedly it's using a class instance variable to store all of these and uses that registry to determine how to load a file. Personally there are a few things in here that I'd look at doing:

class DocumentReader
  # This allows us to key a Hash against the supported file
  # formats instead of having to use the `can_read?` method
  # which can get slow as we add more file types.
  def self.inherited(subclass)
    subclass::SUPPORTED_EXTENTIONS.each do |ext|
      @reader_classes[ext] = subclass
    end
  end

    @reader_classes = {}

  class << self
    attr_reader :reader_classes
  end

  # ...

  def self.reader_for(path)
    # By using a Hash key we can get rid of a full search here
    extension = File.extname(path)[1..-1] # trim the dot
    reader_class = DocumentReader.reader_classes[extension]

    return unless reader_class

    reader_class.new(path)
  end
end

class XMLReader < DocumentReader
  SUPPORTED_EXTENSIONS = ['xml']
end

class YAMLReader < DocumentReader
  SUPPORTED_EXTENSIONS = ['yaml', 'yml']
end

class PlainTextReader < DocumentReader
  SUPPORTED_EXTENSIONS = ['txt']
end

Of course this is only a start and a very brief one. More likely I'd look to leverage module nesting and asking the top-level module what its constants are (classes and modules are constants too.)

I'm always a bit wary on making these types of registries, but at the same time I'm also wary of having a manual list I have to remember to update in several places too. It all comes down to making a tactical investment in metaprogramming to make your program (perhaps paradoxically) more maintainable.

Modules Want to be Heard Too

Modules also have hooks like included and extended for whenever a class does include ModuleName. The book gives us an example here:

module WritingQuality
  def self.included(klass)
    puts "Hey, I've included in #{klass}"
  end

  def number_of_cliches
    # Body of method omitted
  end
end

The book points out that the most common use of the included hook is to additionally extend class methods into whatever includes a module. The book gives us this hypothetical example of having to do both:

module UsefulInstanceMethods
  def an_instance_method; end
end

module UsefulClassMethods
  def a_class_method; end
end

class Host
  include UsefulInstanceMethods
  extend UsefulClassMethods
end

...but quickly follows with an example of what it meant here:

module UsefulMethods
  module ClassMethods
    def a_class_method; end
  end

  def self.included(host_class)
    host_class.extend(ClassMethods)
  end

  def an_instance_method; end
end

class Host
  include UsefulMethods
end

While this is certainly useful use it sparingly because it can really make a mess if you're not careful trying to hunt down where certain behavior is coming from. Very frequently you'll see this for class-level macro methods like you might find in Rails:

class SomeController < ApplicationController
  before_filter :something
end

...or for decorating methods like you might see with Sorbet:

class SomethingElse
  extend T::Sig

  sig { params(a: Numeric, b: Numeric).returns(Numeric) }
  def adds(a:, b:)
    a + b
  end
end

How do those work? Well that's a subject for a much much longer post, but one I've already written elsewhere in Decorating Ruby.

Knowing When Your Time Is Up

Anyways, back to the book. Ruby has a hook for running things at the end of a program, at_exit:

at_exit do
  puts "Have a nice day."
end

In fact we can have multiple:

at_exit do
  puts "Goodbye"
end

Why use it? A lot of times you want to clean up loose connections or other running processes to make sure you're shutting down the application safely. If you want an example try hitting ctrl + c or cmd + c when RSpec is running and notice what it does. It doesn't immediately end, it tries to wrap things up instead, and only really exits if you try to end it again.

...And a Cast of Thousands

Ah yes, the old and infamous set_trace_func. The book mentions this variant:

proc_object = proc do |event, file, line, id, binding, klass|
  puts "#{event} in #{file}/#{line} #{id} #{klass}"
end

set_trace_func(proc_object)

require 'date'

...but it has since been deprecated in favor of an OO version here:

trace = TracePoint.new do |tp|
  puts "#{tp.event} in #{tp.path}/#{tp.lineno} #{tp.method_id} #{tp.defined_class}"
end

trace.enable do
  require 'date'
end

If you were to run this code you would see something like this (and a loooot more) pip up.

b_call in (irb)/5
line in (irb)/6
call in <internal:RUBY/GEMS/core_ext/kernel_require.rb>/36 require Kernel
line in <internal:RUBY/GEMS/core_ext/kernel_require.rb>/37 require Kernel
c_call in <internal:RUBY/GEMS/core_ext/kernel_require.rb>/37 discover_gems_on_require #<Class:Gem>
c_return in <internal:RUBY/GEMS/core_ext/kernel_require.rb>/37 discover_gems_on_require #<Class:Gem>
line in <internal:RUBY/GEMS/core_ext/kernel_require.rb>/39 require Kernel
c_call in <internal:RUBY/GEMS/core_ext/kernel_require.rb>/39 synchronize Monitor
b_call in <internal:RUBY/GEMS/core_ext/kernel_require.rb>/39 require Kernel
line in <internal:RUBY/GEMS/core_ext/kernel_require.rb>/40 require Kernel
c_call in <internal:RUBY/GEMS/core_ext/kernel_require.rb>/40 path #<Class:File>
c_return in <internal:RUBY/GEMS/core_ext/kernel_require.rb>/40 path #<Class:File>
line in <internal:RUBY/GEMS/core_ext/kernel_require.rb>/42 require Kernel

TracePoint is far more useful when used in a limited context, and for debugging it can be unmatched in finding where particularly hard to trace metaprogramming has gone awry. There was even one case where I had used TracePoint recently to listen to every instance of opening a file with a certain path to see what part of an application was loading what I thought were dead fixture files somehow magically within the last month.

If you want to learn more about TracePoint there are some articles, including one I wrote a while back and should probably finish later: Exploring TracePoint.

Staying Out of Trouble

The book mentions that the key factor in using hooks safely is knowing how they work and whether or not they will be called. In the simple cases it's probably fine:

class DocumentReader; end

class PlainTextReader < DocumentReader; end
class YAMLReader < DocumentReader; end

...but then more files might get involved:

require "document_reader"

require "plaintext_reader"
require "xml_reader"
require "yaml_reader"

...and then subclasses of those, which you might or might not want to happen:

class AsianDocumentReader < DocumentReader; end
class JapaneseDocumentReader < AsianDocumentReader; end
class ChineseDocumentReader < AsianDocumentReader; end

The book suggests fixing this by having that class never be able to read anything:

class AsianDocumentReader < DocumentReader
  def self.can_read?(path)
    false
  end
end

The other issue is around at_exit if the program crashes, there's no guarantee that it happens to run. It's best effort, same with how RSpec warns us before it actually exits on an at_exit but we can still kill the program.

In the Wild

The book uses the example of Test::Unit :

require "test/unit"

class SimpleTest < Test::Unit::TestCase
  def test_addition
    assert_equal 2, 1 + 1
  end
end

How is it that given we run that script:

ruby simple_test.rb

...that we get back a full test run?

Loaded suite simple_test
Started
.
Finished in 0.000247 seconds.

1 tests, 1 assertions, 0 failures, 0 errors

That's because it (and RSpec and other similar tools) use at_exit to kick things off:

at_exit do
  unless $! || Test::Unit.run?
    exit Test::Unit::AutoRunner.run
  end
end

It starts by checking if there are any errors using $!, though you should really use the english variant $ERROR_INFO instead as it more clearly describes what's going on (and read about other globals here.)

Wrapping Up

This chapter covered a lot of hooks in Ruby, and there are even more still out there to explore. The trick is to use them sparingly and where it makes sense, rather than using them for everything. Chances are high you do not need a class registry early on, and a lot of times you can use block wrappers instead of decoration to get the effects you're after.

That said, when it's needed it's really useful. Knowing where that line is is an art form, and not one I am particularly well versed in either. Just remember the golden rule: Make sure your code is understandable.