Exception to message mapper is a Ruby library bundled with the standard Ruby library distribution since Ruby 1.1 (released in the 20th century). It was written by Keiju ISHITSUKA and apparently meant to be used internally, to simplify Ruby’s stdlib source code. But since it’s available in the stdlib, it’s also available for us. You may be wondering what this library is about. Well, guess what?.. It maps messages to exceptions!
Why would you use it
Probably you won’t use it anyway (and I understand why), but let’s imagine a
somewhat far-fetched example. When you define a custom exception it usually
doesn’t have any context. For example, ArgumentError doesn’t tell a lot on its
own. If you want to use the exception (that is, you raise it), you usually
write an accompanying message that explains why this exception is being raised.
By doing this you connect the explanation to the exception, which forms 1
logical unit. If your class often raises the same (or almost the same
exception), if the exception messages are long, they may clutter the code,
because you constantly “connect” explanations. Ever had such problems? It makes
sense to refactor the messy code. An exception to message mapper comes to the
rescue.
Say you have Validator, the ultimate validator class of the new generation
that validates everyone and everything. It’s simple, but not simple-minded. The
validator dislikes and rejects integer 0, string "password" and sneaky SQL
queries like "SELECT * FROM users;". If it sees something like that, it whines
and raises an exception. Otherwise it returns true.
class Validator
class ValidatorError < ArgumentError; end
def self.validate(datum)
case datum
when 0
raise ValidatorError, "meh, no-one uses zeros in 2014"
when "password"
if Time.now.year == 2015
raise ValidatorError, "meh, no-one uses passwords in 2015"
else
true
end
when /SELECT \* FROM .+;/i
raise ValidatorError, "cheating is not allowed"
else
true
end
end
end
As you can see there’s a problem with this class: it raises the same exception
with almost the same exception message. Let’s solve the problem by mapping a
predefined message to Validator::ValidatorError to remove duplication. No need
to reinvent the wheel, we have a handy tool in our tool belt.
Example usage
The e2mmap library implements an exception to message mapper. Behind the
scenes the implementation uses really old school Ruby with for loops
and whistles but that’s none of our concern. Firstly, require e2mmap, which
defines the Exception2MessageMapper class.
require 'e2mmap' # From stdlib.
Next, let’s define a separate module that maps messages to exceptions. It’s
worth mentioning that you can bake this straight into the Validator’s body.
class Validator
module ExceptionsForValidator
extend Exception2MessageMapper
def_exception :ValidatorError, "meh, no-one uses %s in %s", ArgumentError
end
end
Here we extended ExceptionsForValidator with e2mmap and defined a new
exception class (ValidatorError) with a message attached to it. The message is
"meh, no-one uses %s in %s". The ArgumentError argument is the superclass of
ValidatorError.
Now we can use the module in the Validator class. We also need to change the
implementation of the .validate method slightly. In places where we want to
reuse our exception message raise becomes Raise. Raise is just a method
defined on self. It accepts the next arguments: an error class to be raised,
the arguments to substitute for %s’s in the message.
class Validator
include ValidatorErrors
def self.validate(datum)
case datum
when 0 then Raise ValidatorError, "zeros", 2014
when "password"
if Time.now.year == 2015
Raise ValidatorError, "passwords", 2015
else
true
end
when /SELECT \* FROM .+;/i
raise ValidatorError, "cheating is not allowed"
else
true
end
end
end
e2mmap does not restrict you to one message. The SQL query example shows that
you still can use plain old raise with the exception defined via e2mmap and
pass an arbitrary message.
More features
If you prefer to use fail instead of raise, e2mmap includes an alias for
Raise, which is called Fail. You can also use fail (e2mmap overrides the
default fail, so I do not recommend to use it in order to avoid confusion).
If you want to use a predefined message for an existing exception, you can use
the def_e2message method (instead of def_exception).
require 'e2mmap'
class Validator
extend Exception2MessageMapper
def_e2message ArgumentError, "sorry, wrong argument"
def self.testRaise
Raise ArgumentError
# or Fail ArgumentError
# or fail ArgumentError (not recommended)
end
end
Validator.testRaise #=> ArgumentError: "sorry, wrong argument"
Where does Ruby use e2mmap internally? Well, for example, IRB heavily uses it.
Other noticeable parts of Ruby’s stdlib that use e2mmap are Matrix
and Shell.
Conclusion
I’ve never used this library myself (and never seen it being used in open source projects), and I didn’t find any mentions of this library on the internet. Hence, someone had to write about it. For additional reference you can read the source code of the library. Also, this is probably the last Ruby article of 2014.
Happy New Year!