Forem: Brandon Weaver

Noah Gibbs: Mentor, Friend, Ally

Brandon Weaver — Fri, 27 Dec 2024 04:33:30 +0000

Content Warning: Death of a Ruby community member

I woke up this morning to receive the news, among others, that Noah Gibbs had passed away. It was a sudden and unexpected loss, and one that I feel deeply. Let me tell you about the man who was Noah Gibbs, and what he meant not only to me, but to an entire generation of Ruby developers.

You Are Welcome Here

I grew up in a world where I was often told to be quiet, to keep to myself, to not bother others and to just be normal. I lived a life of silence and isolation that took years to escape from, even with the help of several friends I met in the Ruby community.

I was alone.

When I was first invited to speak at Southeast Ruby I felt like I was finally accepted, that I had finally managed to be recognized for the things I loved and cared about, and I went there with a good amount of fear that maybe they'd see what everyone else did growing up, and maybe I would not be welcome.

Enter a teddybear of a man, Noah, warm and talking to everyone, who checked in on me as a new speaker and who took a legitimate interest in what I had to say. He was kind, patient, always smiling and always trying to draw out that next idea with an insightful question or a quick quip.

A man I felt had shared some of that deep loneliness, and could understand. A man who chose to turn that into a welcome for anyone who came through those doors.

Everyone is Welcome Here

Over the next several years I got to know Noah better. What he had given to me in that first meeting, that welcome, was something he did for everyone. He would always be there in any corner and any group asking questions.

If you knew no one at a conference you knew Noah, and he'd make sure of it every time.

Noah was a friend to everyone.

A Wise Mentor

But Noah never stopped at a welcome, no, he was a guide and a mentor for generations of Ruby engineers, myself included. He would always make time to answer questions, to talk people through tough career decisions, and to just make sure they were ok.

He always had time for folks who were in need.

He would even take time to walk through his book and provide discounts for those who could not afford it, if not outright give free copies, to help people level up and grow.

A Kind Man

Noah lived a life of teaching, mentorship, and welcome. He was a kind man, he was loved, and he made a difference in an entire generation of Ruby programmers who came to find acceptance through the community in no small part from his contributions to it.

A Man I Hope to Be One Day

The highest praise I can give is that Noah is the type of man I want to become in the future. A kind man who always has time for others, who supports those in need, who encourages and builds communities, and who always welcomes.

Noah was a good man, and I will dearly miss him.

If you have a story about Noah, please share it here:

https://bsky.app/profile/nateberkopec.bsky.social/post/3leai2fxcx22p

Let's Read - Eloquent Ruby - Ch 22 – Method Missing Delegation

Brandon Weaver — Fri, 04 Oct 2024 06:18:55 +0000

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 22. Use method_missing for Delegation

Y'know after reading that intro paragraph in the book I'm questioning whether or not I want to pursue management again, but then again a lot of my job nowadays is writing Documents (heh) and delegating work to others and trying to distill context into where in the world we're going next and why we should be doing it.

The book uses that aside to lead into the idea of delegation in programming, which is to give a task to another object to either do the entire task or a part of it for you. Frequently you'll find this used for wrappers in Ruby that change maybe a few things about an original object but otherwise send everything along as-is.

The Promise and Pain of Delegation

We're back with the idea of our Document class, except this time we want to wrap it with an idea that the content should be locked down after a certain time limit as the contents are especially sensitive:

class SuperSecretDocument
  def initialize(original_document:, time_limit_seconds:)
    @original_document = original_document
    @time_limit_seconds = time_limit_seconds
    @create_time = Time.now
  end

  def time_expired?
    Time.now - @create_time >= @time_limit_in_seconds
  end

  def check_for_expiration
    raise "Document no longer available" if time_expired?
  end

  def content
    check_for_expiration
    @original_document.content
  end

  def title
    check_for_expiration
    @original_document.title
  end

  def author
    check_for_expiration
    @original_document.author
  end

  # and so on...
end

original_instructions = get_instructions
instructions = SuperSecretDocument.new(
  original_document: original_instructions,
  time_limit_in_seconds: 5
)

We keep a reference to the original document, but for a lot of you your DRY sense is going to be going off right about now. It seems like we're doing the same thing fairly frequently no?

That's where delegation comes in.

The Trouble with Old-Fashioned Delegation

Right now this doesn't seem so bad, but what if we added a few more methods?:

class SuperSecretDocument
  def initialize(original_document:, time_limit_seconds:)
    @original_document = original_document
    @time_limit_seconds = time_limit_seconds
    @create_time = Time.now
  end

  def time_expired?
    Time.now - @create_time >= @time_limit_in_seconds
  end

  def check_for_expiration
    raise "Document no longer available" if time_expired?
  end

  # content, title, and author methods omitted
  # to keep from adding more scrolling...

  # And some new methods...

  def page_layout
    check_for_expiration
    @original_document.page_layout
  end

  def page_size
    check_for_expiration
    @original_document.page_size
  end

  # and so on...
end

...or maybe 10 or 20 more? At what point does this start becoming unmaintainable? Sure, we're forwarding things to the original document, but in a fairly cumbersome way.

The method_missing Method to the Rescue

This is where method_missing can come in handy:

class SuperSecretDocument
  def initialize(original_document:, time_limit_seconds:)
    @original_document = original_document
    @time_limit_seconds = time_limit_seconds
    @create_time = Time.now
  end

  def time_expired?
    Time.now - @create_time >= @time_limit_in_seconds
  end

  def check_for_expiration
    raise "Document no longer available" if time_expired?
  end

  def method_missing(name, *args)
    check_for_expiration
    @original_document.send(name, *args)
  end
end

Now any method which we don't know about automatically goes right on to the base object. We can even test it like so:

string = "Good morning, Mr. Phelps"
secret_string = SuperSecretDocument.new(
  original_document: string,
  time_limit_in_seconds: 5
)

puts secret_string.length # Works fine
sleep 6
puts secret_string.length # Raises exception

More Discriminating Delegation

But sending everything, like mentioned in previous chapters, can be dangerous so we probably want a limiter around that. Frequently, as the book mentions, method_missing will have a list or allowed methods or perhaps a pattern they need to follow to be considered valid:

class SuperSecretDocument
  DELEGATED_METHODS = %i[content words]

  def method_missing(name, *args)
    check_for_exipration

    return super unless DELEGATED_METHODS.include?(name)

    @original_document.send(name, *args)
  end
end

The nice thing in this case about forwarding to the original document is that if we happen to have a method get through that we did not intend it's going to fail as that method doesn't exist on the underlying object either.

That said allow lists are the way to go. You want to limit how much method_missing actually catches and deals with as the more limited it is the more you can guarantee it's not going to surprise you down the line. Really that's a good rule for a lot of programming: limit things to predictable outcomes whenever possible, and if not test and monitor the heck out of the thing.

Staying Out of Trouble

The problem here is that while some classes do have the method somewhere up the chain, like to_s is present all the way up in BasicObject:

original_instructions = get_instructions
instructions = SuperSecretDocument.new(
  original_document: original_instructions,
  time_limit_in_seconds: 5
)

puts instructions.to_s
#<SuperSecretDocument:0x123456789>

If we wanted to get around that we'd have to inherit from BasicObject to hack around it, or define our own to_s method closer to home:

class SuperSecretDocument < BasicObject
  # ...
end

The book mentions you have to patch Ruby 1.8 to get this behavior, but nowadays 1.8 is (hopefully) long gone and has been for years. If you're still on it you have my condolences.

In the Wild

As with a lot of things in Ruby there's always a built in tool or gem to do something that seems really handy. In this case we have SimpleDelegator which does exactly that:

require 'delegate'

class DocumentWrapper < SimpleDelegator
  def initialize(real_doc)
    super(real_doc)
  end
end

text = "The Hare was once boasting of his speed..."
real_doc = Document.new(title: "Hare & Tortise", author: "Aesop", content: text)

wrapper_doc = DocumentWrapper.new(real_doc)

puts wrapper_doc.title
# STDOUT: Hare & Tortise
puts wrapper_doc.author
# STDOUT: Aesop
puts wrapper_doc.content
# STDOUT: The Hare was once boasting of his speed...

Any method we don't explicitly overwrite is going right to the underlying object. This has been very useful for me in the past when refactoring where I need to emulate a new contract with old code and change only a few methods on a base object before removing it completely later. Bonus points when using it with feature flagging too.

The other example the book gives us is Rails where it would previously lazy load attributes for objects using method_missing, but that's changed a while ago to where the methods are defined immediately, albeit still dynamically based on the columns of the class.

Wrapping Up

Seriously, delegation is fantastic for refactoring things. Go and read the docs for Forwardable and SimpleDelegator some time. I've gotten a ton of mileage out of them, and they're perhaps the single most useful way to use method_missing directly in Ruby.

The next chapter continues on the exploration of method_missing with building flexible APIs.

Let's Read - Eloquent Ruby - Ch 21 – Method Missing

Brandon Weaver — Fri, 04 Oct 2024 05:02:03 +0000

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 21. Use method_missing for Flexible Error Handling

What exactly happens when Ruby doesn't find the method it's looking for? Well it goes hunting for that method of course, but it has to go all the way up its inheritance chain to try and find it first before it then falls back to the current class and starts asking if anyone knows how to handle a missing method using method_missing.

If that sounds slow that's because it is, and one must be careful when using this feature in Ruby. There are certainly ways around this which make it less of an issue such as dynamically creating what the method should have been, had it existed, but it's always going to be a bit slower than other implementations. We'll get into some more alternatives later on this one, but method_missing is still a useful tool to know.

The number one rule when using it though is to make sure to limit what it will actually work with. Define a narrow set of "valid mistakes" to prevent it from catching too many things.

Meeting Those Missing Methods

The book starts in with this example in which a user of the Document class happens to accidentally call text instead of the correct content method:

# Error: the method is content, not text!

doc = Document.new(title: "Titanic", author: "Cameron", content: "Sail, crash, sink")
puts "The text is #{doc.text}"

The book then tells us what actually happens. The short version is we get an error, certainly, but how do we get there? As mentioned earlier Ruby is going to go looking for that method in the entire inheritance chain up to BasicObject and once it does that it's going to go for round two looking for anyone who's been kind enough to implement method_missing to tell it what to do next. If it doesn't find one? Well then there's your error.

We're given this example class to experiment with that implements method_missing:

class RepeatBackToMe
  def method_missing(method_name, *args)
    puts "Hey, you just called the #{method_name} method"
    puts "With these arguments: #{args.join(' ')}"
    puts "But there ain't no such method"
  end
end

...as well as a few examples of how that might work:

repeat = RepeatBackToMe.new

repeat.hello(1, 2, 3)
# STDOUT: Hey, you just called the hello method
# STDOUT: With these arguments: 1, 2, 3
# STDOUT: But there ain't no such method

repeat.good_bye("for", "now")
# STDOUT: Hey, you just called the good_bye method
# STDOUT: With these arguments: "for", "now"
# STDOUT: But there ain't no such method

We get access to the method name as well as the arguments, and in this case the book uses those values to output some log messages to STDOUT. Do be careful though, because this might be masking errors in production, so we'd likely want to raise a NotImplementedError or similar exception after the logs to trigger any monitoring platforms we might have that something is amiss.

Note: As mentioned before the book explicitly uses simple examples for the sake of space and time. I point these out not to say the book isn't covering things, but to further your intuition as a reader of things to watch out for out in the wide world. If you're especially pedantic you could probably pick apart my counter examples as well.

Handling Document Errors

Now we're back to our classic Document class again, and we have another variant of the above method_missing but with a minor change of using HEREDOCs instead of %Q as that tends to be more common out in the wild these days:

class Document
  def method_missing(method_name, *args)
    raise <<~ERROR
        You tried to call the method #{method_name}
      on an instance of Document. There is no such method
    ERROR
  end
end

The book also mentions that we could potentially append (the a flag for File is append mode) messages to a log file as well in the background:

class Document
  def method_missing(method_name, *args)
    raise <<~ERROR
        You tried to call the method #{method_name}
      on an instance of Document. There is no such method
    ERROR

    File.open("document.error", "a") do |f|
      f.puts "Bad method called: #{method_name}"
      f.puts "with #{args.size} arguments"
    end
  end
end

...though in the wild you're probably going to use this to send messages to a logger or other service.

What's interesting is that the book mentions something that modern day Rubyists might find eerily familiar:

require "text"

class Document
  include Text

  def method_missing(missing, *args)
    candidates = methods_that_sound_like(missing.to_s)

    message = "You called an undefined method: #{missing}"

    unless candidates.empty?
      message += "\nDid you mean #{candidates.join(' or ')}?"
    end

    raise NoMethodError.new(message)
  end

  def methods_that_sound_like(name)
    missing_soundex = Soundex.soundex(name.to_s)

    public_methods.sort.select do |existing|
      existing_soundex = Soundex.soundex(existing.to_s)
      missing_soundex == existing_soundex
    end
  end
end

...which you might recognize as an earlier variant of the "Did You Mean" gem:

methosd
# => NameError: undefined local variable or method 'methosd' for main:Object
#    Did you mean?  methods
#                   method

The implementation instead uses a "string distance" algorithm called Levenshtein distance and guess where the implementation comes from? (source)

module DidYouMean
  module Levenshtein # :nodoc:
    # This code is based directly on the Text gem implementation
    # Copyright (c) 2006-2013 Paul Battley, Michael Neumann, Tim Fletcher.
  end
end

Yep, the same Text gem that the above code example references. Small world ain't it?

This feature was shipped with Ruby 2.3.x and has been with us for some time now, but also right after this book was published by a few years.

Coping with Constants

What happens if you're missing a constant instead of a method? Well as the book mentions that's where we get const_missing:

class Document
  def self.const_missing(const_name)
    raise <<~ERROR
        You tried to reference the constant #{const_name}
        There is no such constant in the Document class.
    ERROR
  end
end

As the book mentions it needs to be a class method, so do keep that in mind.

What's it used for? Autoloaders pre-Zeitwerk in Rails used it to lazy load constants. If you really want a deep dive into that I would highly recommend Xavier Noria's talk on Zeitwerk where he takes a historical journey to how we got here.

In the Wild

In the past Rails tended to use method_missing heavily, and in some cases it still does use it, but I want to call attention to a particular pattern I've seen take over a lot of the early usage of method_missing and that would be keyword arguments. In older Rails you might see something like this:

Model.find_by_name_and_version("Bob", 42.1)

...which used method_missing to see there was a find_by prefix and then use the name and version afterwards to decide what to search on. Back in the day that was awesome for the type of flexibility it gave us, I remember seeing it back in the late 2000s and thinking it was magic, but since then code has shifted towards something more like this:

Model.find_by(name: "Bob", version: 42.1)

That simple change to use keywords made finder methods much faster, but also gave us a very consistent and findable (heh) syntax that new programmers would not need to scour docs to find. If there's one big blindspot for dynamically defined methods it's that finding docs or implementations for them can be painful.

The other day, not even a month ago, I had to rifle through a ton of Devise documentation to find out where in the world it was defining some auth methods when I was trying to figure out how to properly stub them in tests.

Staying Out of Trouble

As mentioned above, and as confirmed by the book, use sparingly. As with any form of powerful magic or tool it's also very dangerous if you use it incorrectly. It intercepts all wrong methods, so you want to be careful only to intercept exactly the type of wrong you want to do something about, or you'll find some rather unpleasant oncall debugging sessions in your future.

It's still useful in a few case, but often times the explicit and slightly longer-to-write ways are better to ensure programs behave predictably. Rails does have some interesting examples here, so if you're curious I would read into those.

Wrapping Up

The book wraps up by saying that while this chapter covered error handling as a focus the next one focuses on the much more common usage which I was hinting at earlier: Delegation and dynamic definitions.

Let's Read - Eloquent Ruby - Ch 20 – Block Hooks

Brandon Weaver — Thu, 03 Oct 2024 05:33:34 +0000

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.

Let's Read - Eloquent Ruby - Ch 19 – Block Actions

Brandon Weaver — Fri, 27 Sep 2024 05:51:42 +0000

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 19. Save Blocks to Execute Later

This chapter wraps up the book's tour into block functions with the idea that we can save blocks to be used later. That may sound abstract, as the previous concepts also did, but you'll find that it's very common to see around Ruby especially for things like hooks.

Explicit Blocks

The book starts by mentioning that we can also have explicit blocks by using an argument prefixed with an &:

def run_that_block(&block_function)
  puts "About to run the block"
  block_function.call
  puts "Done running the block"
end

This may feel familiar to other & prefixes in Ruby like array.select(&:even?) because it's a similar concept meaning "convert whatever is after me to a proc/function."

As mentioned in earlier chapter reviews the idea of block_given? is an implicit check for the presence of a block, but you can just as easily check whether or not one was given in the explicit context like so:

block_function.call if block_function

The book mentions that some Ruby programmers, myself and the author included, have a very strong preference towards this explicit style of block functions. While they're most certainly clearer for non-Ruby programmers to understand, and also for folks who've been around the Gemfile a few times, they also have a feature that implicit blocks don't really have*, and that's the ability to save a reference to the block.

Note: You used to be able to capture implicit blocks in a very confusing way using Proc.new but that was rightfully removed in Ruby 3.x (bug tracker ticket), so this is more of a "technically" depending on the version of Ruby, but since 2.x has been end of life for a while it's reasonable to say you can't do it.

So why would you want to save a block function? Because you don't always want to do something right away, but you might know what you want to do right away.

The Call Back Problem

Consider the type of code you might write in a language like Java to add listeners for things like saving or loading files for our Document class. We'd probably make more classes for it, no? After all if you have a hammer everything starts looking like an AbstractSingletonProxyFactoryNailMapper (you think I'm joking?):

class DocumentSaveListener
  def on_save(doc, path)
    puts "Hey, I've been saved!"
  end
end

class DocumentLoadListener
  def on_load(doc, path)
    puts "Hey, I've been loaded!"
  end
end

...and if we were to implement that in our Document class it might look like this:

class Document
  attr_accessor :load_listener
  attr_Accessor :save_listener

  def load(path)
    @content = File.read(path)
    load_listener.on_load(self, path) if load_listener
  end

  def save(path)
    File.open(path, 'w') { |f| f.print(@contents) }
    save_listener.on_save(self, path) if save_listener
  end
end

...and the call itself might look something like this:

doc = Document.new(title: "Example", author: "Russ", content: "It was a dark...")
doc.load_listener = DocumentLoadListener.new
doc.save_listener = DocumentSaveListener.new

doc.load("example.txt")
# STDOUT: Hey, I've been loaded!
doc.save("example.txt")
# STDOUT: Hey, I've been saved!

It all feels pretty excessive for what should be a pretty simple action, no? We don't care about objects in these cases, we care about actions, and thankfully Ruby has inherited some ideas from Functional programming that allow us to work with actions (or rather functions) instead of just objects.

Now granted, as the book mentions, maybe you want some of the extra weight an object provides, or the separation it affords. Remember everything is about tradeoffs and making the right decisions for your code where it's currently at.

Banking Blocks

If, instead, we used block functions to capture what we want to do as a result of saving or loading a file it might look a little bit like this:

class Document
  def on_save(&block_function)
    @save_listener = block_function
  end

  def on_load(&block_function)
    @load_listener = block_function
  end

  def load(path)
    @content = File.read(path)
    @load_listener.call(self, path) if @load_listener
  end

  def save(path)
    File.open(path, 'w') { |f| f.print(@contents) }
    @save_listener.call(self, path) if @save_listener
  end
end

We capture two functions for what we want to do on a file being saved and on a file being loaded in instance variables, and when we actually save or load we call those functions we saved earlier.

The way we use it might look like this:

my_doc = Document.new(title: "Block based example", author: "Russ", content: "...")

my_doc.on_load do |doc|
  puts "Hey, I've been loaded!"
end

my_doc.on_save do |doc|
  puts "Hey, I've been saved!"
end

By doing so we no longer need extra objects, just a few functions and a lightweight way to save them. This allows us to describe actions we want to take eventually, rather than right now, and to do so in a minimal way that can be right in line with our code. It's also a good deal more flexible as we can change what we put in those functions wherever it happens to be without changing an underlying class or any other implementations.

Saving Code Blocks for Lazy Initialization

The book goes into another example. Let's say we wanted to lazily load the content of a document, only when we actually need it. Perhaps we could use caching like we've seen in the past:

class ArchivalDocument
  attr_reader :title, :author

  def initialize(title:, author:, path:)
    @title = title
    @author = author
    @path = path
  end

  def content
    @content ||= File.read(@path)
  end
end

...or maybe we could use block functions instead to make it more generic. Suppose that we wanted to get that content from HTTP, a socket, FTP, SSH, or who knows what else. We could make a bunch of subclasses to handle each of them, or we could use block functions:

class BlockBasedArchivalDocument
  attr_reader :title, :author

  def initialize(title:, author:, &block_function)
    @title = title
    @author = author
    @initializer_block = block_function
  end

  def content
    if @initializer_block
      @content = @initializer_block.call
      @initializer_block = nil
    end

    @content
  end
end

We've now abstracted out the idea of how we load content, and instead of the class defining it the class lets us define it at call-time to be whatever in the world we want. The book even gives us a few examples of this:

file_doc = BlockBasedArchivalDocument.new(title: "File", author: "Russ") do
  File.read("some_text.txt")
end

google_doc = BlockBasedArchivalDocument.new(title: "HTTP", author: "Russ") do
  Net::HTTP.get_response("www.google.com", "/index.html").body
end

boring_doc = BlockBasedArchivalDocument.new(title: "Silly", author: "Russ") do
  "Ya" * 100
end

Unlike the previous chapters where we used a block function in the initializer this time we're saving it for later. That's the nice thing about a proc is we can run them whenever we want to, on our own terms.

Instant Block Objects

Remember, everything in Ruby is an object, and functions are no exception. That means we can save them to a variable even without using blocks. In the book we're given this example of some default listeners which define a few lambda functions inline:

class Document
  DEFAULT_LOAD_LISTENER = -> doc, path do
    puts "Loaded: #{path}"
  end

  DEFAULT_SAVE_LISTENER = -> doc, path do
    puts "Saved: #{path}"
  end

  attr_accessor :title, :author, :content

  def initialize(title:, author:, content: "")
    @title = title
    @author = author
    @content = content

    @load_listener = DEFAULT_LOAD_LISTENER
    @save_listener = DEFAULT_SAVE_LISTENER
  end
end

The book stops here, but the code you're likely to see more in the wild might look a bit more like this:

class Document
  DEFAULT_LOAD_LISTENER = -> doc, path do
    puts "Loaded: #{path}"
  end

  DEFAULT_SAVE_LISTENER = -> doc, path do
    puts "Saved: #{path}"
  end

  attr_accessor :title, :author, :content

  def initialize(
    title:,
    author:,
    content: "",
    load_listener: DEFAULT_LOAD_LISTENR,
    save_listener: DEFAULT_SAVE_LISTENER
  )
    @title = title
    @author = author
    @content = content

    @load_listener = load_listener
    @save_listener = save_listener
  end

  def on_save(&save_action)
    @save_listener = save_action
  end

  def on_load(&load_action)
    @load_listener = load_action
  end
end

It's a very common idiom nowadays to save a default initialization value in a constant, and that doesn't just apply to functions either. Personally I've done it a lot with other types of arguments too. This gives us the option of flexibility, but the nicety of having something to fall back on that's a reasonable default.

Staying Out of Trouble

The book mentions that Proc and lambda functions are slightly different:

from_proc_new = Proc.new { puts "hello from a block" }

The short version is that lambdas are very strict about their argument arity (how many arguments they take) and Procs are not. In most every case I'm going to prefer a lambda because I prefer explicit. If you'd like a more thorough dive into this I have a post on "Understanding Ruby: Blocks, Procs, and Lambdas" that might be an interesting read.

The other problem we might find is that blocks remember the context around wherever they happened to be created:

def some_method(doc)
  big_array = Array.new(10_000_000)

  # Do something with big array

  doc.on_load do |d|
    puts "Hey, I've been loaded!"
  end
end

...which means that that ten million item Array will remain in memory because of that block function, which may not be what we want at all.

We can fix this by clearing the object first if we don't want that behavior:

def some_method(doc)
  big_array = Array.new(10_000_000)

  # Do something with big array

  # And then get rid of it:
  big_array = nil

  doc.on_load do |d|
    puts "Hey, I've been loaded!"
  end
end

That said, closures (remembering context) are really useful in general as a concept, but that's beyond the scope of this chapter and this book.

In the Wild

RSpec uses saved blocks frequently. If you've ever worked in RSpec you've used a ton of them already:

it "knows how many words it contains" do
  doc = Document.new(title: "Example", author: "Russ", content: "Hello world")
  expect(doc.word_count).to eq(2)
end

...or perhaps in Rails you want to store an action to be taken before any controller action:

class DocumentController < ActionController::Base
  before_filter do |controller|
    # Do something before each action
  end
end

...or perhaps also in Rails you want something to happen after you destroy a record:

class DocumentVersion < ActiveRecord::Base
  after_destroy do |doc_version|
    # My Document is gone!
  end
end

But the most common one that's not mentioned in the book? ActiveRecord scopes are lambdas:

class Document < ActiveRecord::Base
  scope :archived, -> { where(status: "archived") }
  scope :published, -> { where(status: "published") }
end

Really a lot of "macro methods" (methods called at the top level of a class) use block functions heavily. The book has a few more examples, but you can find them everywhere in any active Ruby codebase, especially a Rails one.

Wrapping Up

That wraps up the chapters on block functions, and up next we start diving into the magical world of metaprogramming.

If you really want to get into what block functions can do I would definitely encourage giving Haskell or another functional language a test drive to get a feel for how they work with functions. Some of those ideas translate well to Ruby, others not so much, but they're still interesting to learn.

Let's Read - Eloquent Ruby - Ch 18 – Block Wrapping

Brandon Weaver — Thu, 26 Sep 2024 07:49:52 +0000

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.

Let's Read - Eloquent Ruby - Ch 17 – Block Iterators

Brandon Weaver — Tue, 24 Sep 2024 06:16:29 +0000

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 17. Use Blocks to Iterate

Blocks, or as I prefer to call them block functions, are an exceptionally distinct part of Ruby. If you've used Javascript or languages with a more functional bend they're going to look very familiar, but if not they can be a bit of a foreign concept.

As the book mentions they're part syntax, part method, part object, and one part function that it doesn't mention. This chapter kicks into the sections on blocks which we'll be covering for the next few chapters.

A Quick Review of Code Blocks

The book opens with this code sample in two styles:

# Multiline do/end block
do_something do
  puts "Hello from inside the block"
end
# STDOUT: Hello from inside the block

# Single line bracket ({}) block
do_something { puts "Hello from inside the block" }
# STDOUT: Hello from inside the block

As the book mentions Ruby treats blocks differently than other method arguments and uses this example to demonstrate:

def do_something
  yield if block_given?
end

...in which yield calls the block and block_given? only returns true if the method was given a block. This is the very implicit style of handling blocks in Ruby, and personally I prefer the much more explicit one:

def do_something(&block_function)
  block_function.call if block_function
end

The next example the book gives makes my preference a bit clearer between the two:

# Implicit stype
def do_something_with_an_arg
  yield("Hello world") if block_given?
end

# Explicit style
def do_something(&block_function)
  block_function.call("Hello world") if block_function
end

do_something_with_an_arg do |message|
  puts "The message is #{message}"
end
# STDOUT: The message is Hello world

...but as with most things it's a matter of preference in Ruby. Personally though the question which always goes through my head is whether or not a new developer can read my code and have a decent idea of what I'm doing, and if the answer is no it gives me pause unless I have no other reasonable choice.

The book also goes on to remind us that yield returns a value like many other Ruby methods:

# Implicit style
def print_the_value_returned_by_the_block
  if block_given?
    value = yield
    puts "The block returned #{value}"
  end
end

def print_the_value_returned_by_the_block(&block_function)
  return unless block_function

  value = block_function.call
  puts "The block returned #{value}"
end

print_the_value_returned_by_the_block { 3.14159 / 4.0 }
# STDOUT: The block returned 0.7853975

Granted the explicit version also demos guard functions, which is another preference, but my goal here is to demonstrate different ways of thinking about things because chances are you'll run into code that's stylistically very different than the book or what you or I might like out there.

One Word after Another

The book mentions that the difference between the above methods and an iterator is simple: An iterator is used to iterate a collection, which means calling a function on each element of that function in sequence:

class Document
  # Implicit
  def each_word
    word_array = words
    index = 0

    while index < words.size
      yield word_array[index]
      index += 1
    end
  end

  # Explicit
  def each_word(&block_function)
    word_array = words
    index = 0

    while index < words.size
      block_function.call(word_array[index])
      index += 1
    end
  end

  # Using each instead
  def each_word(&block_function)
    # Longer version
    words.each do |word|
      block_function.call(word)
    end

    # Shorthand
    words.each(&block_function)
  end
end

Then it gives us an example of using this method:

d = Document.new(title: "Truth", author: "Gump", content: "Life is like a box of...")
d.each_word { |word| puts word }
# STDOUT: Life
# STDOUT: is
# STDOUT: like
# STDOUT: a
# STDOUT: box
# STDOUT: of
# STDOUT: ...

...ah, and then the book goes back to say you should use each explicitly like the "Using each instead" variant above. Sometimes I get ahead of myself.

As Many Iterators as You Like

As the book mentions there's no technical limit to how many iterator methods you might have. Perhaps one for words, lines, characters, or whatever else makes sense. You can name them whatever, but as the book mentions naming them something descriptive is a good idea:

class Document
  def each_character(&block_function)
    @content.chars.each(&block_function)
  end
end

Though this does raise a very amusing point in that Ruby's String does not have an each method as the matter of what to iterate over is not always clear, hence the chars.each invocation above.

Iterating over the Ethereal

The thing about iterating, as the book mentions, is that you don't need the thing you're iterating to be a collection or even to exist really. It just needs to be able to express the idea of iteration in its own unique way. The example the book uses here is times:

12.times { |x| puts "The number is #{x}" }

We're not iterating over a collection, and a number certainly doesn't have items in it, but the concept of times is that the number tells us how many times to do something so it still matches the idea of iteration.

There's also no real restriction on how you choose to iterate. The book mentions an example of iterating every consecutive two words like so:

class Document
  def each_word_pair
    word_array = words
    index = 0

    while index < (word_array.size - 1)
      yield word_array[index], word_array[index + 1]
      index += 1
    end
  end

  # Or the shorter Enumerable version:
  def each_word_pair(&block_function)
    words.each_cons(2).each(&block_function)
  end
end

At no point have we built out all of those pairs, but we do while we're iterating. each_cons with Enumerable gives us even more power here to express the same idea more succinctly.

Enumerable: Your Iterator on Steroids

So why each? Because one of the most powerful tools in Ruby, Enumerable, uses it as a foundation. If you can define each you can do a lot of other things. Let's start with each though:

class Document
  include Enumerable

  def each
    words.each { |word| yield(word) }
  end
end

...and a few examples of some Enumerable magic:

doc = Document.new(title: "Advice", author: "Harry", content: "Go ahead and make my day")

doc.include?("day")
# => true

doc.select { |word| word.start_with?("a") }
# => ["ahead", "and"]

It also gives us a few methods like each_cons, like the above code example in the previous section:

def each_word_pair
  # The book prefixes this with `words` but...
  words.each_cons(2) { |array| yield(array[0], array[1]) }

  # ...you could also do this instead if it's an Enumerable:
  each_cons(2) { |array| yield(array[0], array[1]) }
end

The sort methods, however, rely on another method called <=>, or the "rocket ship" operator and its associated Comparable module. Often times folks will implement both, but in this case if the elements returned by each have <=> defined (and String does) you get it for free.

Enumerable, as the book mentions, gives you 40+ methods for free based on a single method, each. Maybe you want to get all the Enumerable methods off of another iterator method instead? Well the book mentions that you can use Enumerator here:

doc = Document.new(title: "example", author: "russ", content: "We are all characters")
enum = Enumerator.new(doc, :each_character)

puts enum.count
pp enum.sort
# => [" ", " ", " ", "W", "a", "a", "a", "a", "c", ...]

...but you could also use enum_for instead in each of those methods:

class Document
  def each_character
    # `to_enum` is also a synonym here
    return enum_for(:each_character) unless block_given?

    chars.each { |c| yield c }
  end
end

...which lets us do this:

doc = Document.new(title: "example", author: "russ", content: "We are all characters")

doc.each_character.count
doc.each_character.sort

Personally I prefer the enum_for as a return for methods that take a block but were not given one, particularly for iterators.

Staying Out of Trouble

The book mentions the primary danger here is trusting the block passed into a method too much, as it's potentially trusting someone else's code. Perhaps they change the underlying collection or do something else bad, or as the book mentions perhaps it could even throw an exception:

doc.each_word do |word|
  raise "boom" if word == "now"
end

The book then mentions that if an exception were raised in a sensitive method like so it could do some damage:

def each_name
  name_server = open_name_server

  while name_server.has_more?
    yield name_server.read_name
  end

  name_server.close
end

So it encourages wrapping the code such that it can handle those exceptions:

def each_name
  # Get some expensive resource
  name_server = open_name_server

  while name_server.has_more?
    yield name_server.read_name
  end
# Ensure works like rescue, we can have it at the top level too
ensure
  # Close the expensive resource
  name_server.close
end

Granted this should be a general concern in programming: Assume everything could potentially fail and make your code resilient to potential failures, especially ones that could cause damage to systems.

The other example the book gives is if someone uses break in the middle, but that'll still trigger ensure:

def count_til_tuesday(doc)
  count = 0

  doc.each_word do |word|
    count += 1
    break if word == "Tuesday"
  end

  count
end

Speaking of async resources though: Use ActiveJob for those, don't do it inline, and if you don't know about idempotency, retries, exponential backoffs, or state machines those would be very good topics to read up on in general.

In the Wild

The book then goes into a few more examples in the core of Ruby that use block iterators. Dir can iterate over directories of files for instance:

puts "Contents of /etc directory:"
etc_dir = Dir.new("/etc")
etc_dir.each { |entry| puts entry }

...or the case of a DNS resolver looking up each address associated to a domain name (the IPs have probably changed by now):

require "resolv"
Resolv.each("www.google.com") { |x| puts x }
# STDOUT: 72.14.204.104
# STDOUT: 72.14.204.147
# STDOUT: 72.14.204.99
# STDOUT: 72.14.204.103

...or ObjectSpace which is a particularly powerful little tool for introspecting every live object in Ruby:

ObjectSpace.each_object(String) { |the_string| puts the_string }

Careful though, because things like "every ruby object" or even a lot of them are expensive and best left to either test or development environments. Same thing with TracePoint which is arguably more dangerous (and potentially more fun.)

Some even have infinite series:

require "prime" # mathn doesn't exist anymore

# You want to limit it, otherwise it'll keep going for a while
Prime.first(20).each { |x| puts "The next prime is #{x}" }

Point being that you're going to find iterators in a lot of places in Ruby, both in core and in any library you happen to use.

Wrapping Up

Understanding blocks, or at least being able to read them and understand what's going on, are critical to working effectively with Ruby. They're just as important as understanding functions in Javascript or other functional languages.

One thing the book tends to gloss over a bit is that blocks are indeed functions, which is why I insist on calling them block functions in several places in this chapter. If you think of them as functions you can take intuition from other languages as well as learn a lot of useful techniques from functional programming in general.

Ruby borrows a lot and learned a lot from other languages, it's well worth doing the same.

Let's Read - Eloquent Ruby - Ch 16 – Module Mixins

Brandon Weaver — Fri, 13 Sep 2024 08:31:57 +0000

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 16. Use Modules as Mixins

Modules are good for a lot more than just namespacing in Ruby. They're containers for behaviors, certainly, but what if we could also use that to share behavior across different classes? Well that's exactly what a mixin is in Ruby, and it's how we create reusable chunks of code.

Quick Aside: Hanging Indentation

The book tends to use this hanging style for some multi-line constructs:

class Document
  CLICHES = [ /play fast and loose/,
              /make no mistake/,
              /does the trick/,
              /off and running/,
              /my way or the highway/ ]
end

While this is a personal preference I tend to really dislike hanging indentation for a few reasons:

Diffs - If that variable name changes or you move the construct you now have to reindent the entire construct relative to wherever it ends up.
Left to Right - The more distance my eye has to travel to follow code the more my ADHD self loses track of things.
Two Space - Consistent indentation makes it far easier to visually group code and not lose track of ends and other bounds

Instead I prefer line-breaked normally indented constructs:

class Document
  CLICHES = [
    /play fast and loose/,
    /make no mistake/,
    /does the trick/,
    /off and running/,
    /my way or the highway/
  ]
end

To me it's just easier to read and work with later, and the only reason I know why some default to this is JetBrains IDEs like RubyMine suggesting it for some strange reason because Java is notorious for it. Anyways, one of my personal biggest annoyances in reading Ruby code, however petty it might be.

Better Books with Modules

The book starts with an example of improving the Document class further with the ability to judge the quality of the content's writing. As the book mentions cliches can generally be frowned upon, so it suggests we create a way of counting how many of them there are in a document's content:

class Document
  CLICHES = [
    /play fast and loose/,
    /make no mistake/,
    /does the trick/,
    /off and running/,
    /my way or the highway/
  ]

  def number_of_cliches
    # Rather than the `inject(0)` the `count` method would
    # make more sense here. Also `match?` is clearer than
    # `=~` is.
    #
    # If you wanted to speed this up `Regexp.union(CLICHES)`
    # as a new constant would be a fair bit faster and remove
    # an entire loop.
    CLICHES.count { |phrase| phrase.match?(content) }
  end
end

Now I do deviate from the book a bit here in using count and match?, but I believe that demonstrates that there can be methods that more clearly indicate intent while also making the code more succinct. Typically nowadays count and sum have replaced most usages of reduce and its alias inject, and are more clear to readers in general. If there's a more specific named method available you can use in general prefer that.

The book continues by suggesting that there may be an extended ebook system we need to support:

class ElectronicBok < ElectronicText
end

Do we copy and paste the behavior from Document, even if it would mostly be duplicated? The book mentions most folks first instinct is to create a base class, but in Ruby we also have a way to group similar behaviors outside of inheritance using mixins.

Mixin Modules to the Rescue

We can take that bit of potentially shared code and wrap it in a module like so:

module WritingQuality
  CLICHES = [
    /play fast and loose/,
    /make no mistake/,
    /does the trick/,
    /off and running/,
    /my way or the highway/
  ]

  def number_of_cliches
    # Rather than the `inject(0)` the `count` method would
    # make more sense here. Also `match?` is clearer than
    # `=~` is.
    CLICHES.count { |phrase| phrase.match?(content) }
  end
end

...and elsewhere in the code we can directly include it in our classes using include:

class Document
  include WritingQuality
end

class ElectronicBook < ElectronicText
  include WritingQuality
end

Giving it a test you can see we get the same results:

my_tome = Document.new(
  title: "Hackneyed",
  author: "Russ",
  content: "my way or the highway does the trick"
)

my_time.number_of_cliches
# => 2

my_ebook = ElectronicBook.new(
  title: "Hackneyed",
  author: "Russ",
  content: "my way or the highway does the trick"
)

my_ebook.number_of_cliches
# => 2

One of the reasons a lot of folks use mixins is because you can only inherit from one class, but there's no real limit on how many modules you can mixin until your RAM catches fire.

The book suggests maybe there are a few more shared behaviors that we could add:

module ProjectManagement; end
module AuthorAccountTracking; end

class ElectronicBook < ElectronicText
  include WritingQuality
  include ProjectManagement
  include AuthorAccountTracking
end

The danger, of course, is that too many modules and it can be very hard to follow what's going on in the code without opening up 5+ files on the biggest widescreen you can fit on your desk or monitor arm. Generally if you need a 48" monstrosity of an ultra wide just to read your code chances are some things might need to be simplified a bit.

Extending a Module

In all of those above cases we're mixing behavior into the instance of a class, does that mean we could also mixin behavior at a class level? We can certainly give it a try:

module Finders
  def find_by_name(name); end
  def find_by_id(doc_id); end
end

Perhaps your first instinct, if you only know include, is to do something like this:

class Document
  class << self
    include Finders
  end
end

...but as with most things Ruby also has a keyword for that idea which is a bit more succinct:

class Document
  extend Finders
end

Both of which could be called like so:

Document.find_by_name("War and Peace")

...though a lot of find_by and where style methods tend to accept several keyword arguments, very similarly to what ActiveRecord does.

So what's the difference between include and extend? You use include for internals or instances, and extend for externals, or at least that's the pneumonic I tend to use in my head to remember. Either that or I swap the two if I really blank out on it.

There's also prepend, but that's a subject for another article.

Staying Out of Trouble

For every module we mixin we're also changing the hierarchy of the inheritance chain behind it. The book uses an illustration here, but in essence it says:

Document -> WritingQuality -> Object

In a lot of cases this is transparent, but you can tell what modules a class has loaded either through ancestors or by asking it using kind_of?(ModuleNameHere). For Document the ancestry chain looks something like this:

[Document, WritingQuality, Object, Kernel, BasicObject]

include inserts modules between a class and its superclass, so if Document defined its own variant of a method it would win. prepend, conversely, puts it before the class and any methods on it come first. The book gives an example of this overriding for include here:

class Document
  include WritingQuality
end

class PoliticalBook < Document
  def number_of_cliches = 0
end

Since PoliticalBook comes first in the ancestry chain it'll return 0 any time we call that method. Whatever's higher up the chain wins, unless it doesn't respond to that method. If you happened to include multiple modules with the same behavior that contradict each other that'd mean whichever one loads first will "win" and the other will be ignored if they share method names.

In general you want to keep mixin modules short and focused, because the larger they become the more risk you run of running into each other while coding.

Wrap Up

Mixins are extremely common in Ruby, as are include and extend, with prepend being a bit rarer. Enumerable especially is a great example if you want to read and explore.

Let's Read - Eloquent Ruby - Ch 15 – Module Namespaces

Brandon Weaver — Thu, 12 Sep 2024 07:31:18 +0000

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 15. Use Modules as Name Spaces

Eventually you're going to need to organize your Ruby code. Sure, we have classes that represent objects, but how are they grouped? What do they belong to? Which team owns them? That's part of the reason why namespaces are such a popular concept, and in Ruby we have modules for that.

A Place for Your Stuff, with a Name

A module is a container, or a namespace, for Ruby code. The book demonstrates this with an example:

module Rendering
  class Font
    attr_accessor :name, :weight, :size

    def initialize(name:, weight: :normal, size: 10)
      @name = name
      @weight = weight
      @size = size
    end
  end

  class PaperSize
    attr_accessor :name, :width, :height

    def initialize(name: "US Letter", width: 8.5, height: 11.0)
      @name = name
      @width = width
      @height = height
    end
  end
end

To access them we might use Rendering::Font or Rendering::PaperSize. Perhaps we even have some constants in there too:

module Rendering
  # Classes above here

  DEFAULT_FONT = Font.new(name: 'default')
  DEFAULT_PAPER_SIZE = PaperSize.new
end

Rendering::DEFAULT_FONT

...though personally I might do this to prevent the need for worrying about load ordering:

module Rendering
  def self.default_font = Font.new(name: 'default')
  def self.default_paper_size = PaperSize.new
end

...otherwise the classes need to exist first. In this case they just need to be defined before those methods are called, probably at runtime.

You can nest them as deeply as you want:

module WordProcessor
  module Rendering
    class Font; end
  end
end

...and sometimes that can go on for quite a while for particularly large programs. Personally though if I find that I need to have a long prefix like OrgName::TeamName::ConceptName::ClassName littered all over that means that I'm using code I probably shouldn't and creating dependencies which are going to be real annoying to pay down later.

A Home for Those Utility Methods

Pretty frequently you'll also see modules used as wrappers for several little utility methods:

module WordProcessor
  def self.points_to_inches(points) = points / 72.0
  def self.inches_to_points(inches) = inches * 72.0
end

an_inch_full_of_points = WordProcessor.inches_to_points(1.0)

...though if I end up with enough of those I tend to use this little shortcut:

module WordProcessor
  extend self

  def points_to_inches(points) = points / 72.0
  def inches_to_points(inches) = inches * 72.0
end

an_inch_full_of_points = WordProcessor.inches_to_points(1.0)

Handy eh? Just don't mix and match self methods in there unless you want a bad time.

Building Modules a Little at a Time

Nothing in Ruby is ever really finished. Every class and module is open, even more so for a particularly determined programmer, and that's not always a good thing like when people monkey patch MySQL drivers.

Anyways, what that means in a more practical sense like the book mentions is that we can have things in different files like so:

# rendering/font.rb
module Rendering
  class Font; end

  DEFAULT_FONT = Font.new('default')
end

# rendering/paper_size.rb
module Rendering
  class PaperSize; end

  DEFAULT_PAPER_SIZE = PaperSize.new
end

...and then require the both of them later:

require 'rendering/font'
require 'rendering/paper_size'

Or, in the more modern days of Ruby, just use Zeitwerk:

https://github.com/fxn/zeitwerk?tab=readme-ov-file#synopsis

Treat Modules Like the Objects That They Are

Remember how everything was an object? Modules are no different, we can assign them to variables just the same as anything else:

the_module = Rendering
times_new_roman_font = the_module::Font.new("times-new-roman")

Let's take these examples from the book of four classes with two very similar groups of behavior. One to handle a printer queue and one to handle the printer itself:

class TonsOTonerPrintQueue
  def submit(print_job)
    # Send the job off for printing to this laser printer
  end

  def cancel(print_job)
    # Stop the print job on this laser printer
  end
end

class TonsOTonerAdministration
  def power_off
    # Turn this laser printer off
  end

  def start_self_test
    # Test this laser printer
  end
end

class OceansOfInkPrintQueue
  def submit(print_job)
    # Send the job off for printing to this ink jet printer
  end

  def cancel(print_job)
    # Stop the print job on this ink jet printer
  end
end

class OceansOfInkAdministration
  def power_off
    # Turn this ink jet printer off
  end

  def start_self_test
    # Test this ink jet printer
  end
end

Modules would allow us to group these two concepts into a similar interface we could easily switch between:

module TonsOToner
  class PrintQueue
    def submit(print_job)
      # Send the job off for printing to this laser printer
    end

    def cancel(print_job)
      # Stop the print job on this laser printer
    end
  end

  class Administration
    def power_off
      # Turn this laser printer off
    end

    def start_self_test
      # Test this laser printer
    end
  end
end

module OceansOfInk
    class PrintQueue
    def submit(print_job)
      # Send the job off for printing to this ink jet printer
    end

    def cancel(print_job)
      # Stop the print job on this ink jet printer
    end
  end

  class Administration
    def power_off
      # Turn this ink jet printer off
    end

    def start_self_test
      # Test this ink jet printer
    end
  end
end

...and then just like that, as the book mentions, you could switch between the two implementations:

print_module = if use_laser_printer
    TonsOToner
else
  OceansOfInk
end

admin = print_module::Administration.new

Staying Out of Trouble

One of the most common errors I see in Ruby, personally, is mixing up class and instance behaviors. In the book it mentions wrappers for methods like so:

module WordProcessor
  def self.points_to_inches(points) = points / 72.0
end

...but if you did this instead it would not work because it's an instance method:

module WordProcessor
  def points_to_inches(points) = points / 72.0
end

We'll cover those cases more in the next chapter, because they do have a use, but you should be aware of the difference.

The other danger is nesting. Sure, we have two, it's not that bad:

module Rendering
  class Font

Then another comes along as a sub-categorization that makes sense:

module Rendering
  module GlyphSet
    class Font

...and eventually you could even end up with something like this:

module Subsystem
  module Output
    module Rendering
      module GlyphSet
        class Font

So now every implementer gets to do this:

Subsystem::Output::Rendering::GlyphSet::Font

...which is fairly excessive. For each nesting ask if it's really actually necessary, and if it provides clarity.

Personally I find that if the nesting exceeds 3-4 levels it means that I probably have a few applications hiding in the same repository and some breaking up needs to happen, assuming those modules all make sense and people aren't getting carried away.

In the Wild

The book goes into DataMapper, but I might instead go into some of the larger Rails apps I've worked with in the past (10M+ LoC, 1M+ LoC, and 3M+ LoC respectively.) Two of them implement Packwerk to namespace things, and frequently something to the order of:

Layer::Owner::DomainArea::SubArea

Where:

Layer: What layer of the app it functions at, like Platform or Application or Library.
Owner: Who owns this area, typically an organization instead of a team because team is too granular and teams shift a lot more often than orgs do.
Domain Area: What functionality is in here? Is it for Payroll? Patients? Something else?
Sub Area: Classes or any other grouping. If it goes deeper than this chances are it needs to be broken down more.

But the thing to remember about modules is you can omit leading segments if you're in the context of that module. Let's say we had A::B::C::D::F that wanted to talk to A::B::C::D::E.special_method. Calling it with the full namespace is a mouthful, but look at this:

module A
  module B
    module C
      module D
        module E
          def self.special_method = 42
        end

        module F
          def self.other_method = "#{E.special_method} is the answer"
        end
      end
    end
  end
end

A::B::C::D::F.other_method
# => "42 is the answer"

Doesn't E.special_method seem pretty reasonable? The further you are away from a module the less likely you should be to ever interact with it, and if calling it is a pain of 5-6 layers in a larger application chances are you should not even know about that internal detail anyways.

Wrap Up

This chapter introduces modules as a concept of containing things, and the next chapter will show us how we use them to go even further in making shareable behaviors.

Let's Read - Eloquent Ruby - Ch 14 – Class Instance Variables

Brandon Weaver — Thu, 12 Sep 2024 06:17:03 +0000

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 14. (Don't) Use Class Instance Variables

From the last article:

Speaking of, next up we have class instance variables, which admittedly I am very much not a fan of for the same reasons I just mentioned, so we'll see how that article goes.

This article does have something similar to say about class variables here:

Sadly, we will discover that class variables behave in some unfortunate ways, making them less of a solution and more of a problem.

...which I agree with, but even class instance variables I would advocate for using constants in almost every case instead, or failing that define an instance of a wrapper at the top level that can be passed downwards into your program later.

That said, I will still cover the content in this chapter as-is with only occasional quips about alternatives.

A Quick Review of Class Variables

The book starts out with an example of using class variables to capture a default paper size for a document, and in the US that'd be an A4 or letter size:

class Document
  @@default_paper_size = :a4

  def self.default_paper_size
    @@default_paper_size
  end

  def self.default_paper_size=(new_size)
    @@default_paper_size = new_size
  end

  attr_accessor :title, :author, :content
  attr_accessor :paper_size

  def initialize(title:, author:, content:)
    @title = title
    @author = author
    @content = content
    @paper_size = @@default_paper_size
  end
end

This variable isn't visible to anything except for the instance of the class, so initialize can see it but external code cannot. The book says this appears to be a good solution, but has some issues.

Quickly in the interim though personally I would write this as:

class Document
  DEFAULT_PAPER_SIZE = :a4

  # Use the constant as a default argument, allowing individual
  # overrides.
  def initialize(title:, author:, content:, paper_size: DEFAULT_PAPER_SIZE)
    # ...
  end
end

...because allowing runtime to set these can have other unintended side effects. If you really need that look into feature flags instead, or configuration management. In general everything should be private or read-only unless you have a good reason to do otherwise.

Wandering Variables

The book starts into an example of what's wrong with class variables next. Class variables are associated with a class, but which class?

In the book it starts with the current class and goes up the tree from there to superclasses to see if it finds that class variable. If it's not found you get a name error. Sounds reasonable, but it sets up an example to show a flaw with this:

class Resume < Document
  @@default_font = :arial

  def self.default_font
    @@default_font
  end

  def self.default_font=(font)
    @@default_font = font
  end

  attr_accessor :font

  def initialize
    @font = @@default_font
  end
end

When @@default_font = :arial gets run it'll search up the chain and find no other class defines it, including Document, so it's now set on Resume. If there happened to be a second class though:

class Presentation < Document
  @@default_font = :nimbus

  def self.default_font
    @@default_font
  end

  def self.default_font=(font)
    @@default_font = font
  end

  attr_accessor :font

  def initialize
    @font = @@default_font
  end
end

...Ruby will look at Presentation, then Document to see if @@default_font is defined yet. If not it now belongs to Presentation. All great, but if Document decided to do this:

class Document
  @@default_font = :times
end

..then we have an issue. Document needs to be loaded first so Document sets @@default_font, so when Presentation and Resume start in they're going to find that @@default_font was defined on Document and it sets on the Document.

That means depending on the order you load these classes in the default font might be :arial or it might be :nimbus. That's a problem.

(Also constants don't have that problem.)

The other problem is I believe the default fonts nowadays are Calibri for PowerPoint and Helvetica Neue for Keynote, but that's being a bit pedantic.

Getting Control of the Data in Your Class

The solution the book presents to this problem is to use class instance variables instead:

class Document
  @default_font = :times

  def self.default_font
    @default_font
  end

  def self.default_font=(font)
    @default_font = font
  end
end

# Don't you dare
Document.default_font = :comic_sans

To use this in the initializer you'd need to do the following:

def initialize(title:, author:, content:)
  @title = title
  @author = author
  @content = content
  @font = Document.default_font
end

The only thing special about it is that the instance variable is on the class instead. Granted though all classes are technically instances of Class, so the math checks out.

Class Instance Variables and Subclasses

To paraphrase my mother, it’s all fun and games until someone starts writing subclasses

The book asks if class instance variables behave better than class variables, and the short answer is yes:

class Presentation < Document
  # We're fancy now
  @default_font = :helvetica_neue

  class << self
    attr_accessor :default_font
  end

  def initialize(title:, author:, content:)
    @title = title
    @author = author
    @content = content
    @font = Presentation.default_font
  end
end

In the Wild

Interestingly the book uses URI as an example of using class variables with some success:

class HTTP; end
@@schemes['HTTP'] = HTTP

...but since then they've gone with a registry system using constants instead (source):

module URI
  class HTTP < Generic; end

  register_scheme 'HTTP', HTTP
end

...which is defined as (source):

module URI
  module Schemes; end
  private_constant :Schemes

  # Registers the given +klass+ as the class to be instantiated
  # when parsing a \URI with the given +scheme+:
  #
  #   URI.register_scheme('MS_SEARCH', URI::Generic) # => URI::Generic
  #   URI.scheme_list['MS_SEARCH']                   # => URI::Generic
  #
  # Note that after calling String#upcase on +scheme+, it must be a valid
  # constant name.
  def self.register_scheme(scheme, klass)
    Schemes.const_set(scheme.to_s.upcase, klass)
  end

  # Returns a hash of the defined schemes:
  #
  #   URI.scheme_list
  #   # =>
  #   {"MAILTO"=>URI::MailTo,
  #    "LDAPS"=>URI::LDAPS,
  #    "WS"=>URI::WS,
  #    "HTTP"=>URI::HTTP,
  #    "HTTPS"=>URI::HTTPS,
  #    "LDAP"=>URI::LDAP,
  #    "FILE"=>URI::File,
  #    "FTP"=>URI::FTP}
  #
  # Related: URI.register_scheme.
  def self.scheme_list
    Schemes.constants.map { |name|
      [name.to_s.upcase, Schemes.const_get(name)]
    }.to_h
  end
end

Staying Out of Trouble

Use constants or feature flags, or dependency injection failing that. It'll be far easier to test and reason about later.

Wrap Up

Ruby has a few harsh edges. This is one of them, and in previous and future articles I'm not particularly shy about mentioning others from my point of view. Class variables and class instance variables occupy a special place in that I find myself actively avoiding and disliking them, and that I have rarely if ever seen them in the wild even across 10M+ lines of code Rails apps.

If I do see them? Well there's always room for a few more constants.

Let's Read - Eloquent Ruby - Ch 13 – Singleton and Class Methods

Brandon Weaver — Wed, 11 Sep 2024 05:02:13 +0000

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 13. Get the Behavior you Need with Singleton and Class Methods

Not everything fits inside a nice box. For every rule there's counterexample, for every model of thinking there's a weakness, and the same can be said about Object Oriented programming. Some have gone to much more colorful lengths to describe this problem like in the old classic Execution in the Kingdom of Nouns.

Sometimes you need an alternative, and Ruby? It's awash with alternatives for about everything you could think of. Sometimes that's just what you need, other times it makes things incomprehensible, but the core of it is Ruby lets you choose where that line is with more fidelity than a lot of other languages.

In this case we're talking about singleton methods, a way to have a distinct set of behaviors specific to a single object.

A Stubby Puzzle

The book looks back at chapter 9 and stub, but in our example we used instance_double instead as it verifies the underlying methods exist first:

class Printer
  def available? = false
  def render(content) = "something"
end

class Document
  def words = []
end

# Warning: Will only work in the context of an RSpec test
printer_double = instance_double(Printer, available?: true, render: nil)
document_double = instance_double(Document, words: %w(Hi there))

...and as the book mentions you could have one double, two, maybe ten! But if you took a look at them you'd find out they look very similar:

[printer_double.class, document_double.class]
 => [RSpec::Mocks::InstanceVerifyingDouble, RSpec::Mocks::InstanceVerifyingDouble]

So how does that work? The answer, as the book mentions, is that each of those instances of RSpec::Mocks::InstanceVerifyingDouble has distinct singleton methods defined on them. In the case of an instance_double those do have to be methods the underlying class you're mocking uses, but think of these as interceptors which say "Hey, I heard you were looking for available?! I have it over here closer to you.":

# Only methods defined directly on this instance
printer_double.methods(false)
# => [:available?, :render]

Our Own Stubs

If we wanted to we could even make our own stubs like so:

hand_built_stub_printer = Object.new

def hand_built_stub_printer.available? = true
def hand_built_stub_printer.render(content) = nil

hand_built_stub_printer.methods(false)
# => [:available?, :render]

...or we could even make something a bit more obstinate that, as the book mentions, we won't see in real code:

uncooperative = "Don't ask my class"

def uncooperative.class = "I'm not telling"

puts uncooperative.class
# STDOUT: I'm not telling

The book also suggests an alternative syntax for our little stub variant:

hand_built_stub_printer = Object.new

class << hand_built_stub_printer
  def available? = true
  def render(content) = nil
end

Either way you end up with something similar, though honestly I've done this trick a decent amount of times as well:

fake_class = Class.new(OriginalObject) do
  def method_i_want_to_overwrite = true
end

...which uses inheritance rather than singleton methods, but that can be a matter of preference in implementation.

A Hidden, but Real Class

How's that work in Ruby? Well as the book mentions every class has its own singleton class that sits between an instance and the underlying class itself. Usually you won't notice it unless you add things to it. You can even see it by doing something like this:

hand_built_stub_printer = Object.new
singleton_class = class << hand_built_stub_printer
  self
end

puts singleton_class
# STDOUT: #<Class:#<Object:0x000000010dc5db78>>

How did we get the singleton class there? Remember everything in Ruby is an expression, including class definitions. Oddly though classes don't return their own names like methods do:

class Testing
  def a = true
end
# => :a

Class Methods: Singletons in Plain Sight

The book mentions that most programmers tend to dismiss singleton methods as interesting, but mostly useless. It highlights one particular counterexample that, as it says, "is practically impossible to build a Ruby program without." What is it? Class methods.

Consider this example from the book:

my_object = Document.new(title: "War and Peace", author: "Tolstoy", content: "All happy families...")

def my_object.explain
  puts "self is #{self}"
  puts "and its class is #{self.class}"
end

my_object.explain
# STDOUT: self is #<Document:object_id>
# STDOUT: and its class is Document

Just a refresher from before, but what if you defined a method on the class itself?:

my_object = Document

def my_object.explain
  puts "self is #{self}"
  puts "and its class is #{self.class}"
end

my_object.explain
# STDOUT: self is Document
# STDOUT: and its class is Class

But the book mentions a few more variants of this style, some of which might be familiar:

# Inline method style
def Document.explain
  puts "self is #{self}"
  puts "and its class is #{self.class}"
end

# Class Self style
class Document
  class << self
    def find_by_name(name)
      # Find a document by name
    end

    def find_by_id(id)
      # Find a document by id
    end
  end
end

class << self is the exact same idea as the above class << some_object syntax we were playing with up above. You might have also seen it in this format as well:

class Document
  def self.find_by_name(name)
    # Find a document by name
  end

  def self.find_by_id(id)
    # Find a document by id
  end
end

So which one do you use? Well for me if I have a few class methods I use self.method_name and if I have several I'd probably use class << self or another variant the book doesn't mention here for containing several functions:

module Functions
  extend self

  def map(array, &block_function)
    new_array = []
    array.each { |item| new_array << block_function.call(item) }
    new_array
  end
end

Personally I don't care for mixing and matching class and instance methods for those types of containers, so that above solution works great for many of my personal use cases.

In the Wild

As the book mentions there are class methods all over the place in Ruby, and especially in Rails. If you had this model class for instance:

class Author < ActiveRecord::Base; end

...and you wanted to know what table it was associated with in the database, you could find out by asking the class directly:

Author.table_name

....and if you've ever used scopes:

class Document < ActiveRecord::Base
  scope :content_includes, -> phrase { where("content LIKE ?", "%#{phrase}%") }
end

Those are class methods too (albeit they have slightly different behaviors):

class Document < ActiveRecord::Base
  def self.content_includes(phrase)
    where("content LIKE ?", "%#{phrase}%")
  end
end

Speaking of, where is a class method as well, among a myriad of other fun Rails methods.

The book goes into a few more examples of alternate constructors but we'll leave it there for now.

Staying Out of Trouble

One of the most common issues, as the book mentions, with class methods is getting them and instance methods confused:

class Document
  def self.create_test_document(length)
    Document.new(title: "test", author: "test", content: "test" * length) 
  end
end

If you called that method on the class you'd get what you expect:

Document.create_test_document(10_000)

But if you happened to instead call it on an instance of a document:

doc = Document.new(title: "test", author: "test", content: "test")
doc.create_test_document(10_000)
# NoMethodError!

...you'd find that you'll get an exception.

The other example it uses is what happens with self and inheritance:

class Parent
  def self.who_am_i = "The value of self is #{self}"
end

class Child < Parent; end

Parent.who_am_i
# => "The value of self is Parent"

Child.who_am_i
# => "The value of self is Child"

That's because Child is receiving the method in this case, not a Parent.

Wrap Up

As with everything, balance is needed. Singleton methods have a lot of use, but they can also be overused. If you find yourself reaching for instance variables and starting to reinvent instances it's time to make an instance. Keep them simple, to the point, and be wary of adding too much state to them.

Speaking of, next up we have class instance variables, which admittedly I am very much not a fan of for the same reasons I just mentioned, so we'll see how that article goes.

Let's Read - Eloquent Ruby - Ch 12 – Equality

Brandon Weaver — Tue, 10 Sep 2024 07:50:49 +0000

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 12. Create Classes that Understand Equality

So equality. How does it even work in Ruby? What makes two things equal? Not equal? Maybe kinda sorta equal, those cases are real fun. Well this chapter is going to take a look at a lot of those

An Identifier for your Documents

The book leads in with saying this can be a slippery slope, which is how you know we'll have a fair bit of fun with this chapter. It starts in with an example of how you might identify your documents and manage an ever-growing horde of them, and an initial solution of a DocumentIdentifier:

class DocumentIdentifier
  attr_reader :folder, :name

  def initialize(folder:, name:)
    @folder = folder
    @name = name
  end
end

It presumes a management system of unique names and folders they're contained in. So how do we use that to determine if two documents are equal then?

An Embarrassment of Equality

Ruby has a lot of methods, which one are we using today? eql?, equal?, ==? Maybe even ===, you remember that one from Javascript so it should probably be that! (It's not.)

What do each of them do? (docs are great by the way):

equal? - Compares object identity (literally same object), so we don't want that
eql? - Compare hash keys, == defaultly uses this
== - What we want to override, general equality
=== - Case equality, or inclusion operator, definitely not the same as JS

Most every time you're going to want ==, but === has a lot of fun uses we may end up covering later too.

Double Equals for Everyday Use

The current implementation coming from Object is the same as eql? meaning what we probably want to happen won't work:

first_id = DocumentIdentifier.new(folder: "secret/plans", name: "raygun.txt")
second_id = DocumentIdentifier.new(folder: "secret/plans", name: "raygun.txt")

first_id == second_id
# => false

...so we'll make our own then:

class DocumentIdentifier
  def ==(other)
    # We want them to be the same type
    return false unless other.instance_of?(self.class)

    folder == other.folder && name == other.name
  end
end

Handily nil responds to instance_of? so we don't need to check for that. We could, as the book mentions, do an equal? check for speed reasons but it likely won't happen enough to matter.

Trying it again we notice:

first_id = DocumentIdentifier.new(folder: "secret/plans", name: "raygun.txt")
second_id = DocumentIdentifier.new(folder: "secret/plans", name: "raygun.txt")

first_id == second_id
# => true

...that it works.

Broadening the Appeal of the `==` Method

The book complains that this is a very narrow definition of equality considering this line:

return false unless other.instance_of?(self.class)

Should they not be equal if they have the same properties? We could do this in a new class like DocumentPointer just to keep it separate like the book:

class DocumentPointer
  attr_reader :folder, :name

  def initialize(folder:, name:)
    @folder = folder
    @name = name
  end

  def ==(other)
    # We check the interface instead, ensuring we have the methods
    # we need.
    return false unless other.respond_to?(:folder)
    return false unless other.respond_to?(:name)

    folder == other.folder && name == other.name
  end
end

That means we could do something like this:

first_id = DocumentIdentifier.new(folder: "secret/plans", name: "raygun.txt")
first_pointer = DocumentPointer.new(folder: "secret/plans", name: "raygun.txt")

first_pointer == first_id
# => true

...as long as the pointer is on the left.

Well Behaved Equality

Speaking of which, the book leads with exactly that in this next section:

first_id = DocumentIdentifier.new(folder: "secret/plans", name: "raygun.txt")
first_pointer = DocumentPointer.new(folder: "secret/plans", name: "raygun.txt")

first_id == first_pointer
# => true

Remember that the == operator that worked is defined on a DocumentPointer and not a DocumentIdentifier, and in the opposite case we're using == from DocumentIdentifier which uses instance_of? instead of interface checks.

The general concept for this is "symmetry" in that if a == b then b == a should also be true. In the above case unless we change both operators we are left with an asymmetric relationship.

The book goes further in saying that with equality we also assume that if a == b and b == c then a == c should also be true which represents the transitive property.

Note: And now we've also basically covered Setoids from Category Theory and Set Theory. Didn't think you'd get an FP patterns tie-in in all of these did you? The only missing property here is reflexivity in which a == a.

The book goes further by introducing subclasses to really drive in the point here:

class VersionedIdentifier < DocumentIdentifier
  attr_reader :version

  def initialize(folder:, name:, version:)
    @folder = folder
    @name = name
    @version = version
  end

  def ==(other)
    case other
    when VersionedIdentifier
      other.folder == folder &&
      other.name == name &&
      other.version == version
    when DocumentIdentifier
      other.folder == folder && other.name == name
    else
      false
    end
  end
end

versioned1 = VersionedIdentifier.new(folder: "specs", name: "bfg9k", version: "V1")
versioned2 = VersionedIdentifier.new(folder: "specs", name: "bfg9k", version: "V2")
unversioned = DocumentIdentifier.new(folder: "specs", name: "bfg9k")

versioned1 == unversioned # true
unversioned == versioned2 # true
versioned1 == versioned2 # false

It laments that somehow we have a == b and b == c but alas we have a != c. It provides a few solutions such as coercion to the lesser DocumentIdentifier for our VersionedIdentifier or maybe a newly named is_same_document? method to deal with the discrepancy.

Now this all not to say a word of inequality operators and how you might order these!

Note: If you did happen to go that far you might find out what an Ord is, which is even more functional pattern goodness (or badness, up to you really.)

Triple Equals for Case Statements

For those of you coming from Javascript who think === in Ruby is a more strict equality? Well it's actually quite the opposite, it's less. It's frequently called the case equality operator, but personally I prefer the inclusion operator for reasons I'll get into in a moment.

You're already using it with those case statements above too:

case 1
when Integer # === used right here!
  true
else
  false
end
# => true

Integer === 1
# => true

You could say that 1 is included in Integer in this case. It works with any Ruby type.

But no, we're not done yet, there's a lot more here with ===. What about regex?

location = "area 51"

case location
when /area.*/
  # ...
when /roswell.*/
  # ...
else
  # ...
end

In this case you could say that a match is an inclusion, in that the string area 51 is included in what the regex is targeting.

The book stops here, but I won't, no no no. It also works with Proc:

add_5 = -> a { a + 5 }
add_5 === 5
# => 10

Oh yes, you saw that right. How do I call that inclusion? Well back to maths we go, because that'd be an inclusion in the domain of a function. I have a yarn board somewhere here.

That said please never use === directly unless you're wrapping it or putting it in a library for a very good reason. It's hidden behind enough corners that you can still get a lot of use out of it even without explicit references.

Hey, even things like grep(_v), any?/all?/none?, and a lot of pattern matching uses them too. Once you know where to look they have a habit of showing up semi-frequently.

Hash Tables and the `eql?` Method

As the book mentions earlier you're probably not going to use eql? directly much in the same manner as === was, but it sure hides behind a lot of corners just the same. In this case it's the method we use for determining Hash key equality:

hash = {}

document = Document.new(title: "cia", author: "Roswell", content: "story")
first_id = DocumentIdentifier.new(folder: "public", name: "CoverStory")

hash[first_id] = document

That works fine, but what if we have a == equivalent id? Well something like this:

second_id = DocumentIdentifier.new(folder: "public", name: "CoverStory")

the_doc_again = hash[second_id]
# => nil

Why? Well Hashes, as the book mentions, are wholly different than Arrays which index by numbers. It breaks apart all the keys it stores into buckets based on those key values based on a hash value. Usually it's a random number generated for each object, and the calculation to get it is something like:

hash_code % number_of_buckets

...to get to the right match. That means whatever those keys are had better be stable over time or we'll end up looking in the wrong place for our values. If two keys are even they should be returning the same value, no? Well that's why we have eql?.

Building a Well-Behaved Hash Key

How's that translate to Ruby? As the book mentions we have a corresponding hash method for the key and an eql? method for equality of those keys. Usually that means they have the same hash value, but it's Ruby so we can overwrite that!

Just be careful, as the book mentions, not to deviate from the idea that a.eql?(b) should behave similarly to a.hash == b.hash. How do we implement that? Well something like this:

class DocumentIdentifier
  def hash
    folder.hash ^ name.hash
  end

  def eql?(other)
    return false unless other.instance_of?(self.class)

    folder == other.folder && name == other.name
  end
end

In that example, as the book mentions, the hash method combines the two fields we want to key on in what it describes as thorough mismatching of the two numbers via XOR (^) (see, we do rarely use bitwise tricks here) and then taking a very strict view of equality otherwise by using a type check.

Staying Out of Trouble

The first rule of adding things to your code is don't. The second rule is don't write, borrow from existing code you have. The third rule is if you must break the first rule and the second be sure you actually need and use it. Same applies for equality. The more surface area of a program the more complexity can sneak in.

But the cardinal rule the book mentions? As simple as possible, no more and no less. Don't overdo it.

In the Wild

Ruby's numeric types do a ton of conversion behind the scenes in a classic "Ruby probably knows what you meant" style of things. That said do be careful to be precise where it counts because things like this do work:

1 == 1.0
# => true

The book also goes a bit off into Comparable which you can read more about here:

https://dev.to/baweaver/understanding-ruby-comparable-34ki

Wrap Up

The book wraps up by again encouraging discretion. It's possible to make equality work, but be sure it's worth the effort and that you're not over-engineering the solutions.