Update, November 2026: Nothing has changed here: including a module still doesn’t bring its singleton methods along, and modules still can’t inherit from one another, as I proposed in The Case for Module Inheritance.

David Heinemeier Hansson, the well known creator of Rails, recently gave a little pep-talk for the use of ActiveSupport::Concern, making an argument that they were sufficient to satisfy the practical needs of DCI’s theory.

What he fails to explain is what Concerns really are. Truth be told, Concerns are essentially an extension of Ruby’s Module class to more fully support multiple inheritance. Whether out of indifference, simple oversight or perhaps a bit of decorum to save Matz’s sensitivities, who has a well known distaste for multiple inheritance, DHH never mentions this simple fact. Concerns are a way for Rails developers to include Modules with the same degree of functionality as inheriting from a superclass.

To say that Concerns are like DCI Roles, is akin to saying C structs are like OOP Objects. Yea, there’s a similarity there, but it’s vastly missing the point.

Update, November 2026: Refinements arrived in Ruby 2.0, and since Ruby 2.1 using also works inside a class or module body, so the second downside below no longer applies.

Well, after a ridiculously long discussion about refinements, it’s finally become clear what Matz is up to. It would have helped if he had mentioned from the start that he’s patterning them directly off of Smalltalk wrappers and CLOS method combinations. Instead we get this “official” spec. Hardly. It was only thanks to Charles Nutter’s careful analysis that I was able to get a clear picture. Oh, the time and data that could have been saved!

So allow me to save you all the trouble and explain refinements in a very simple phrase: macros des méthodes. In plain English, they are macros that act on method invocations. For example,

module M
  def self.string(object)
    object.to_s
  end
end

module Q
  refine String do
    def to_s
      "Every string is #{super}!"
    end
  end
end

using Q

M.string("okay") #=> "okay"

Notice, the M.string method is not affected by the refinement of String#to_s even though it uses #to_s in its definition. However, if we use #to_s explicitly in the scope of the refinement’s use we get:

"okay".to_s #=> "Every string is okay!"

Even though that is exactly what the definition of M.string is, it produces the refined result instead. Since the call was explicit the refinement interceded.

That’s really the crux of refinements. Most of the remaining questions pertain to the order in which multiple refinements interact, but it is all pretty much as one would intuit it to be, so we won’t go into detail in that regard.

Now I thought it might be helpful to take an extreme example of what one could do with refinements and see if it leads us to anything interesting.

Let’s take just a bare class.

class Person
end

Now let’s create two refinements defining two different roles a person might take.

module Buyer
  refine Person do
    attr :stuff, :money
    def initialize(money, *stuff)
      @money = money.to_f
      @stuff = stuff
    end
    def buy(product, cost)
      @stuff.push product
      @money -= cost
    end
  end
end

module Seller
  refine Person do
    attr :stuff, :money
    def initialize(money, *stuff)
      @money = money.to_f
      @stuff = stuff
    end
    def sell(product, cost)
      @stuff.delete product
      @money += cost
    end
  end
end

Now let’s define an activity in which persons interact as each of these roles.

using Seller
using Buyer

class SalesTransaction
  def self.make(buyer, seller, product, cost)
    buyer.buy(product, cost)
    seller.sell(product, cost)
  end
end

Interesting? Person has no built-in behavior, and yet we’ve managed to use the class to model a sales transaction and give each person state of what they own and how much money they have. And an outside interface can’t find this state out unless it knows what role to apply!

You might recognize the pattern of this example. It is DCI. Does this mean refinements are a perfect fit for DCI-based designs? Might we see a whole new paradigm in Ruby architecture built around the DCI? That’s a good question. At first glance it certainly seems to be possible. But we should note a few obvious downsides.

1. Both refinements required an #initialize method to ensure the instance variables are initialized. So refinements of this kind would have to be compatible in this respect in order to be used together.
2. The context, in this case SalesTransaction, has to exist in its own file so only the appropriate refinements apply. There is no way to define contexts that use different refinements in the same file because refinements are applied on a per-file basis. Although, some level of cleverness could be played if certain contexts simply add additional refinements on top of those used earlier in the file.
3. While it remains to be seen, it is unlikely that an entire system written in this fashion will be very fast. Nor is it entirely certain that it would be very comprehensible, but perhaps that has more to do with DCI than refinements.

Ask Ruby what object is receiving calls at the top level:

self        # => main
self.class  # => Object

That main is a particular object. It isn’t the Object class, and it isn’t a module representing our script. Yet a plain method definition here lands in Object:

def greeting
  'hello'
end

method(:greeting).owner == Object
# => true

Object.private_instance_methods(false).include?(:greeting)
# => true

Object.new.send(:greeting)
# => "hello"

The method is private, but objects inheriting from Object can still call it internally. A helper defined for the script has become an inherited method available far beyond the script’s apparent boundary.

That is the behavior I want to question. Defining a top-level helper is perfectly reasonable Ruby. It also has a wider effect than someone writing an application-specific script might expect.

The receiver and the definition target

Current Ruby supports dynamic top-level definitions too. On Ruby 3.4, this works:

define_method(:dynamic_greeting) { 'dynamic hello' }
Object.new.send(:dynamic_greeting)
# => "dynamic hello"

The interesting distinction is where such definitions belong, rather than whether a particular helper exists. main is still the receiver while Object receives the new instance method.

A small declaration helper makes that difference visible:

module Declarations
  def field(name)
    declared_on = self
    define_method(name) { declared_on }
  end
end

class Record
  extend Declarations
  field :declaration_context
end

Record.new.declaration_context == Record
# => true

In the class body, the object receiving field is the class that gets the new instance method. Now try the same declaration at the top level:

top = self
extend Declarations
field :top_context

Object.new.send(:top_context).equal?(top)
# => true

top.equal?(Object)
# => false

We captured main, while the method was defined on Object. Nothing mysterious happened once the rules were understood. But a reusable DSL cannot assume its declaration receiver and definition target are identical in these two contexts.

That is what I mean by the proxy problem: the top level offers conveniences for working with another definition context, while remaining a distinct object with its own identity. It isn’t a general-purpose module namespace.

Give the script a namespace

My preferred alternative is to make the script’s top level a self-extended module. Written explicitly in ordinary Ruby, that looks like this:

module MAIN
  extend self

  def namespaced_greeting
    'hello from MAIN'
  end

  define_method(:namespaced_dynamic) { 'dynamic MAIN' }
end

MAIN.namespaced_greeting
# => "hello from MAIN"

The definitions now belong to a module we can inspect and use deliberately. They don’t become methods on every ordinary object merely because we wrote a helper for our script. If a class does need the behavior, inclusion can make that choice explicit:

class Consumer
  include MAIN
end

Consumer.new.namespaced_greeting
# => "hello from MAIN"

This doesn’t abolish the distinction between module and instance calls. A method called through MAIN receives MAIN as self; the same method included in Consumer receives a consumer instance. Shared state and receiver assumptions still require thought. The benefit is an explicit boundary for the definitions.

A loader can choose this policy today

We don’t need a language change to give one application’s scripts a module context. A small loader can create it, install its declaration interface, and evaluate a trusted script there:

module SettingsDSL
  def option(name, default)
    define_method(name) { default }
  end
end

module ScriptLoader
  def self.load(source, filename = 'settings.rb')
    context = Module.new
    context.extend(context)
    context.extend(SettingsDSL)
    context.module_eval(source, filename, 1)
    context
  end
end

Here is a script and the resulting interface:

settings = ScriptLoader.load(<<~RUBY)
  option :port, 8080
  def label
    "demo"
  end
RUBY

settings.port   # => 8080
settings.label  # => "demo"

The string form of module_eval evaluates these definitions in the new module. Extending that module with itself makes its instance methods callable through the module object as well. The filename and line number help identify errors in the evaluated source. Each load creates a separate context, so another script can define its own port without replacing this one.

This gives the application a namespace policy, not a security sandbox. The evaluated Ruby can still access files, globals, and other objects. Nor does it make require automatically load additional scripts into the same context. A real loader must decide how imports and shared definitions work. Those are part of the design rather than details a wrapper can wish away.

The runnable namespace examples check the definition targets, captured receivers, explicit inclusion, and separate loader contexts on Ruby 3.4.9. They can be run in their own process with:

ruby namespaces.rb

Changing Ruby’s default would be a larger decision

The explicit module is a working technique. Making it the language’s default top level is a proposal with compatibility costs. Existing scripts expect top-level methods to become private Object methods. Replacing that rule would change lookup and could break code that relies on it.

A default MAIN would also need a clear identity: one module per file, per application, or per loader? Where should constants go? What would a required file share with its caller? Those questions need answers before an appealing snippet becomes a coherent language design.

I still like the direction. A script’s helpers ought to have an obvious home, and an application’s DSL ought to be able to choose its reach. A self-extended module provides that home today when we use it explicitly. Whether Ruby should make that the default is the more interesting argument than whether we can add one more convenience method to main.

Update, November 2026: Both issues have since been dealt with. Since Ruby 2.3, autoload goes through Kernel#require, so overrides like RubyGems’ work with it, and Ruby 2.0 took care of the thread safety problem. Autoload wasn’t removed after all: Matz withdrew the proposal in 2019, and Rails’ Zeitwerk loader is built on it.

Ruby has a very cool feature called autoload. With autoload, any undefined constant can automatically trigger the loading of a library file. Effectively this gives Ruby a convenient means of lazy loading. For example, let’s say some of our app’s executable scripts ultimately use the ANSI library, but others do not. We can use autoload to only load the ANSI library when it is needed.

autoload :ANSI, 'ansi'

This says to require "ansi" the first time an undefined ANSI constant is encountered.

As wonderful as autoload seems, it has two glaring issues: 1) It doesn’t use standard Kernel#require and 2) It is not thread safe.

For the first, this means that any overriding of #require will not be supported by autoload. Of course such a thing is very rare, but it does occur. For instance the Roll library is all about overriding #require. Also RubyGems overrides #require, and in fact one can cause a bug to occur when using autoload because of it. Here’s a very simple example.

On the second case the issue seems much more complicated, and a solution seems so unlikely that Matz has called for #autoload to be removed from Ruby by v3.0.0. That’s a long way off but just the same it doesn’t bode well for autoload.

Now that Matz has effectively declared #autoload a code smell, I wonder if developers will take heed and stop using it? I have my doubts –it’s just too damn convenient. I just wish it would use Kernel#require so I could use it along with Rolls.

Update, November 2026: Ruby never made @ a hash, but Ruby 2.6’s to_h with a block does shorten the serialization loop below: instance_variables.to_h { |v| [v, instance_variable_get(v)] }. Facets had something close as Kernel#instance; it’s now the separate instance gem.

What are instance variables? If we think of them as a single unit we note that they represent an object state, which as a data structure is really nothing more than a hash. Indeed, it is quite feasible to forgo the use of instance variables altogether save one, to serve as the object’s state.

class Example
  def self.attr_reader(name)
    define_method(name){ @state[name.to_sym] }
  end

  def self.attr_writer(name)
    define_method("#{name}="){ |v| @state[name.to_sym] = v }
  end

  def self.attr_accessor(name)
    attr_reader(name)
    attr_writer(name)
  end

  def initialize
    @state = {}
  end
end

So if instance variables are essentially a hash, why is it that we cannot work with them as such? In other words, why not have @ just represent a syntax sugar for a special hash (even if it’s not a standard Ruby Hash instance under the hood, it can behave as if it were). With such a change, handling instance variables immediately becomes much easier and intuitive since we can apply all our knowledge of hashes.

Some neat capabilities immediately become apparent. Looking up an instance variable given a variable name can be done with:

@[name]

Assigning an instance variable likewise can be done with:

@[name] = value

No longer would the long-winded instance_variable_get and instance_variable_set be needed.

Let’s take a more complex example. Have you ever wanted to reproduce the name and values of an object instance variable? It’s not uncommon really. Any type of object serialization is going to need such a routine – YAML, Marshal, etc. To do this presently requires some verbose code:

hash = {}
instance_variables.each do |var|
  hash[var] = instance_variable_get(var)
end
hash

But with @ sugar we can simply use:

hash = @.to_h

Or if we just want to iterate over them:

@.each do |k,v|
  ...
end

Since we have #each, then all Enumerable methods would be at our disposal.

For a public interface instance_variables could reference the internal @ instead of just the list of instance variable names. We could deprecate #instance_variable_get and #instance_variable_set altogether.

By recognizing the nature of instance variables and applying the preexisting functionality of Hash, we gain much greater capability while using fewer brain cells to do it. And that’s always a win.

Update, November 2026: Ruby 2.0 fixed the third shortcoming: a method taken from a module can now be bound to any object, BasicObject included. And Ruby 2.7’s bind_call makes the technique cheaper: Kernel.instance_method(:class).bind_call(obj). No $ notation, though.

One of the most regarded capabilities of Ruby, in contrast to many other programming languages, is its powerful meta-programming chops. While not every aspect of the language is meta-programmable, the vast majority of Ruby is. But despite its prowess, there is a serious weakness in its design: The functions on which meta-coders depend have no guarantee.

Consider the most basic reflection method of determining the class of an object, fundamental to almost any meta-programming (and some not-so-meta-programming). We can write a class that completely subverts the ability to determine an object’s class.

class Foo
  def class
    "I Confuse You!"
  end
end

Because Foo has overridden the #class method, there is no way to determine the class of an instance of Foo. Any code dependent on the #class method “contract” is going to choke.

We can be thankful that most programs will, by simple happenstance, never tread on any of these important methods. In the few cases where they might, most Ruby coders are aware enough to steer clear. Yet there are other cases not so easily handled. Consider Ruby’s relatively new BasicObject class. It has the minimal number of methods necessary to function as an object in Ruby. This is excellent for the construction of open classes akin to OpenStruct, but consequently there is no way to find out what methods are defined on such an object because there is no such methods as #methods or #instance_methods. Moreover, BasicObject is still not completely empty. It still defines __id__, __send__, instance_eval, instance_exec and a few others, without which an object simply wouldn’t be usable.

So basically Ruby has settled on a “close enough” approach to handling reflection and meta-programming. But why should we be willing to settle for any risk at all? The reasoning I have most often heard is an OOPL ideological principle arguing that no method should stand outside the realm of the inheritance chain, and thus all methods are necessarily subject to overrides. But I am not convinced for the simple reason that meta-programming is by its nature “meta”.

As an experiment, I developed a small library to take the risk out of meta-coding. The library basically works as follows:

$meta = Proc.new do |obj|
  Functor.new do |op, *a, &b|
    Kernel.instance_method(op).bind(obj).call(*a, &b)
  end
end

$meta["some string"].class #=> String

This meta-function works fairly well in most cases. However it has three shortcomings that make it essentially impractical for production use: 1) It lacks module methods; 2) It is terribly inefficient; and 3) It doesn’t work for BasicObject instances.

While my little library might be improved upon, ideally Ruby would provide a set of “meta-functions” that cannot be overridden in-class. These methods could all be defined in a special module, but used via alternate notation so as not to conflict with ordinary methods. To that end I suggest using $ on regular objects:

obj = Object.new
obj$class #=> Object

Numerous other methods would be made available through this, in general all public Kernel methods are candidates for inclusion, and some Module methods usable just for classes and modules, such as #instance_methods.

The robustness this would bring to Ruby’s meta-programming would be a great boon and should not be understated. When a single line of code can so easily cause every object in a program to fail, it’s not unreasonable to prefer some guarantees. Moreover, it makes the meta-programmer’s task much easier –he knows exactly what methods on which to depend.

Update, November 2026: Ruby never adopted anything like this. It went with warning categories instead: since Ruby 2.7, categories like :deprecated can be switched on and off, and since Ruby 2.4, Warning.warn can be overridden to handle warnings however you like. $VERBOSE still has just three settings.

Today I had to consider how best to handle omission exceptions in the context of test frameworks, and their use case to mark pending tests. In the course of doing so, I realized there are at least two reasonable levels of omission, those that are “ASAP” and those that are “NSM” (Not So Much). Whereas other frameworks used their own specially defined classes for these, e.g. Pending and Omission, my approach is to re-utilize Ruby’s own NotImplementedError. But then I had to consider how to differentiate between these priorities.

And that’s when the more general notion occurred to me of Exception Priorities.

Consider that instead of raising a warning:

warn "Don't do it, mate!"

We could use the Exception system, setting a low “warning” level priority.

raise "Don't do it, mate!", -1

All things being nominal, Ruby would see the priority of this exception is below 0, output the message to $stderr if $VERBOSE=true and then continue on. Hence it is a warning!

With this, #warn could become a simple alias for #raise with a default negative priority.

Now, if that was all there was to it, then there would be little reason to adopt the idea. But there are some really nice advantages to this approach.

With regards to warning messages, we could use the $VERBOSE setting to refine the level of warning we want to be notified about.

$VERBOSE = -1
raise "More Serious Warning!", -1
raise "Less Serious Warning!", -2

In this case we would never see the -2 level warning b/c we’ve indicated we don’t want to see those by setting $VERBOSE to a higher specific level.

Interestingly enough, we can do the same for actually raising errors! Let’s call the setting $PRIORITY for the sake of discussion.

$PRIORITY = -1
raise "More Serious Warning!", -1
raise "Less Serious Warning!", -2

Whereas before, the “More Serious Warning” would just have printed a warning message to $stderr, in this case the Exception will actually be raised, b/c we have lowered the threshold at which exceptions are to be raised.

This refinement to Ruby’s Exception system, effectively subsuming the warning system within it, makes for a much more powerful, flexible and thus useful system. Take my original use case, I can set the priority of NotImplementedError to 1 for ASAPs and 0 for NSMs, and I can go further allowing testers to set high priorities to be selectable from the command line.

Want another use case? How about a DeprecatedError that has a default priority of -1.

I am certain others will think of other use cases as well. This is one of those pliable features that tend to have far wider applicability than the originating use case.

P.S. I’ve always thought it would make more sense if $VERBOSE were called $WARN.

Update, November 2026: Still the case: raise passes only the message to initialize and sets the backtrace separately. The set_message I asked for in that issue was rejected.

You would think after all this time Ruby’s Exception class would be a rather robust and clearly comprehensible class.

raise(exception [, string [, array]])

Now let’s try something:

class MyError < Exception
  def initialize()
    super()
  end
end

>> raise MyError
MyError: MyError
	from (irb):12
	from /home/trans/.rbenv/versions/1.9.3-rc1/bin/irb:12:in `<main>'

No problem. But now let’s try to set the message and the backtrace.

>> raise MyError, "This is an error!"
ArgumentError: wrong number of arguments (1 for 0)
	from (irb):8:in `initialize'
	from (irb):13:in `exception'
	from (irb):13:in `raise'

Clearly Ruby expects any Exception’s initialize method to handle the message argument. That’s a rather strict contract for something Ruby is letting us override. But okay, let’s take that as a given. Obviously Ruby is routing the #raise call to the exception’s initializer. So then we should expect that the third array argument would be passed along too. Turns out that’s not the case.

class MyError < Exception
  def initialize(*args)
    p args
    super(*args)
  end
end

>> raise MyError, "This is an error!", caller
["This is an error!"]
MyError: This is an error!
	from (irb):1
	from /home/trans/.rbenv/versions/1.9.3-rc1/bin/irb:12:in `<main>'

Nope. No caller in sight. So where did it go? Turns out Ruby is setting the caller via the error’s #set_backtrace method and doesn’t depend on the initializer to handle it at all. This seems rather odd, since it was keen on letting the initializer handle the message argument, and would blow-up if the class won’t take it.

So the upshot seems to be that we can’t customize an exception’s initializer and expect #raise to play along.

I actually had another point to make about how things get even worse. Unfortunately I had to take care of other chores and by the time I got back to this blog post (months later) I forgot what these “worse things” were. I think it had something to do with how #message calls #to_s rather than returning the message passed to the initializer. But as said I am not certain now.

My conclusion however is this. I was attempting to make use of an Exception class as something more than a mere container for a string message for the Assay project. That is when I ran into these oddities which made doing so quite unpleasant. To my dismay I ended up abandoning the approach. I brought some aspects of this up in an issue report.

For reference, here is the relevant Ruby source code.

Update, November 2026: Ruby 2.0 added Enumerable#lazy, which does what defer does here, and Facets has deprecated defer in its favor. Denumerable and Denumerator are still in Facets.

All Rubyists know and love Enumerable. It’s really the showcase of Ruby’s mixin system. Some Rubyists also know and appreciate lazy.rb MenTaLguY’s excellent lazy evaluation library. But did you know there is library that essentially cross-breeds the ideas of both? It’s called Denumerable and is included in Ruby Facets (require 'facets/denumerable').

According to Webster’s The term denumerable is just a synonym for enumerable. In Ruby parlance, it takes a more useful distinction of “deferred enumerable”. In other words Denumerable defers actual calculations of a chain of enumerable method calls until the results are actually needed. That’s where the “laziness” comes in. By deferring calculation Ruby is able to optimize the algorithm, in many cases greatly improving performance. It’s even possible to enumerate infinite ranges if the end result itself is finite.

To make it even more convenient there is Enumerable#defer (require 'facets/enumerable/defer') which delegates an Enumerable object through a Denumerator, just like Ruby’s core Enumerator class.

So, enough talk, right? How about an example.

a = (1..1_000_000_000).defer.select{ |i| i % 2 == 0 }.
                             map{ |i| i + 100 }.
                             take(10).to_a
=> [102, 104, 106, 108, 110, 112, 114, 116, 118, 120]

The performance gains of Denumerable cannot be understated. The above example takes 1/10000th of a second to run on my system. I wanted to provide the time it takes to run without defer, but after an hour of waiting and listening to it eat my hard drive for breakfast, I gave up.

Update, November 2026: Ruby never got a %L literal, but Ruby 2.3’s squiggly heredoc, <<~, strips leading indentation, which takes care of the help_text case. In Facets 3.0, margin was renamed trim, and margin(n) took over from tabto.

One of the great things about Ruby is the extensive collection of methods available to the core classes. Of these the String class reigns supreme with over 100 methods from which to make good use. Among these methods are those we all use almost every time a string is laid to editor, such as #strip, #+ and #«. Others are present that have more specific but important uses, such as #lines, #scan and #getbyte. There are even a few that can leave one scratching ones head a bit trying to fathom the usecase, such as #sum.

Yet, despite its wide address, there is a set of methods that have gone completely overlooked, which is really remarkable when you consider their purpose, the frequency of their utility and the code savings they provide when used. These are methods dealing with indentation.

It was many years ago when I first was introduced to these three methods by Gavin Sinclair: #tab, #tabto and #indent. Their interfaces are:

tab(n)
Aligns each line n spaces.

tabto(n)
Preserves relative tabbing in which the first non-empty line ends up
with n spaces before non-space.

indent(n, c=' ')
Indent left or right by n spaces.

So clearly useful, these were some of the first to make their way in to Ruby Facets, and they have proven invaluable to me in numerous projects ever since.

Sometime shortly there after, another related method also proved useful at times, String#margin. It is documented:

margin(n=0)
Provides a margin controlled string.

  x = %Q{
        |This
        |  is
        |    margin controlled!
        }.margin

This method is useful largely because it prevents a horrible code smell. How often have you seen some jutting HERE doc that threw all that nicely indented Ruby code to the wall.

    def help_text
      <<-HERE
Usage: foo bar
-x some option
-y another option
      HERE
    end

This all too common eye blight was the inspiration for the creation of #margin. In fact, so confident were Peter and I in this approach to remove these ugly code-squids that we conceived a %-literal to support such a construct would be an unimpeachable addition to the language itself, allowing the even more elegant notation:

x = %L|Usage: foo bar
      |-x some option
      |-y another option

Such a syntax, being built into Ruby proper, would not suffer the computational overhead of the pure Ruby implementation, or the extraneous brackets.

In all my years of coding Ruby, it seems to me, these are the clearest omissions that I have repeatedly found need. And so concluded that they really should be a part of Ruby proper. And as much as I owe Ruby’s String class for all the time saving methods it provides, in this case, as often as I’ve had copy and paste or add a dependency to ‘facets’ just to get these methods, I think the String class owes me one!