methlab

Yo dawg, I heard you liked methods.

Meth Lab is a method construction toolkit intended to ease parameter validation and a number of common "method definition patterns" seen in ruby code.

=== SYNOPSIS

A lot of times in the programming world, especially in dynamically typed languages, we see this pattern:

def foo(arg1, arg2, arg3) unless arg1.kind_of?(SomeObject) raise "Incorrect object" end

unless arg2 ... 
end

end

You get the idea. Additionally, with the use of hashes for emulating named parameters, we see a ton of this in the ruby world:

def bar(*args) args = args[0]

raise "not a hash" unless args.kind_of?(Hash)

unless args.has_key?(:some_parameter)
  raise "'some parameter' does not exist"
end

unless args[:some_parameter].kind_of?(SomeObject)
  raise "'some parameter' is not a kind of SomeObject"
end

end

Meth Lab is intended to strip your methods of this wordy, but important boilerplate, by making it ideally less wordy and slamming it right in the prototype to easily evaluate what it does. Also, it has an awesomely apropos name.

=== USAGE

So, let's do something like this:

class Awesome def_ordered(:foo, String, [Integer, :optional]) do |params| str, int = params puts "I received #{str} as a String and #{int} as an Integer!" end

def_named(:bar, :foo => String, :bar => [Integer, :required]) do |params|
  puts "I received #{params[:foo]} as a String and #{params[:bar]} as an Integer!"
end

def some_method(*args) # a hash
  params = MethLab.validate_params(:foo => String, :bar => [Integer, :required])
  raise params if params.kind_of? Exception

  puts "I received #{params[:foo]} as a String and #{params[:bar]} as an Integer!"
end

end

Which yields these opportunities:

a = Awesome.new a.foo(1, "str") # raises a.foo("str", 1) # prints the message a.foo("str") # prints the message with nil as the integer

a.bar(:foo => 1, :bar => "str") # raises a.bar(:foo => "str") # raises (:bar is required) a.bar(:bar => 1) # prints message, with nil string a.bar(:foo => "str", :bar => 1) # prints message

a.some_method(:foo => "str", :bar => 1) # prints message

See the MethLab module documentation for details.

=== FAQ

1. OMG OMG OMG OMG DUCK TYPING, you don't need this at all.

a) Then don't use it. I will offer a little opinion though: if you think duck typing can solve everything, chances are you aren't hitting a whole class of edge cases in your code. Also, punk rock is dead, get with the times and think for yourself.

1. Exceptions; how do I debug validation failures?

a) Meth Lab works hard to not raise until the last possible minute for validation failures. Generally you will see a trace like this:

(lines wrapped for sanity)

lib/methlab.rb:95:in `bar': value of argument '1' is an invalid
    type. Requires 'Integer' (ArgumentError)
        from lib/my-actual-file.rb:126

What's important to understand here is that, short of making you, the user, handle raising validation errors yourself (which would kind of defeat the point), we raise just above where your code would execute. This means that both parts of this trace are significant; the first line is the error and the method the error was raised from, but the second line is the place that the method was called.

I will not even pretend this is anything other than a "misfeature", but it is a consequence to working with a library like this.

MethLab will always raise ArgumentError, which is standard for good ruby programs.

1. Don't you solve this with blocks? Are closures an issue?

a) The short, proper answer to this is "yes". The pragmatic answer to this is "probably not". Closures are created and there is a performance impact to relying on them. I would argue that if performance is your concern, you shouldn't be using ruby at all. Meth Lab does make every effort possible to not use proc objects where possible, e.g., the check methods themselves live in the MethLab namespace and are not anonymously injected into your methods (which would be very expensive, and cause inconsistency if someone were to redefine them).

1. I don't want to use MethLab everywhere, but I'd like to use it in a specific class or module.

a) "extend MethLab" in your namespace before using the definition syntax.

1. I want to use MethLab everywhere.

a) MethLab.integrate does this. If you want it to happen at require time, set the global $METHLAB_AUTOINTEGRATE to a true value before doing so. These both pollute ::Module and ::main, so be aware of the consequences.

=== TODO

• #respond_to? checks.
• multiplexed array/hash methods.
• construction of methods that can take inline blocks (e.g., "def foo(&block)"). Proc can be used now, but it's not very "rubyish" syntax for the user.
• Better handling in Modules (def self.meth(...))
• Default values

=== THANKS

• James Tucker (raggi) and "saywatmang" for inspiration and a bit of opinion and code review.
• Eric Hodel (drbrain) for lots and lots of mentoring and generally being a standup dude.
• Params::Validate and Method::Signatures from CPAN for doing it right first. Imitation is the sincerest form of flattery and good ideas should not be kept in an ivory tower, so prematurely shut it plox.