-- mode: ruby --

Note: this file is also the library test suite. Run rake test to

verify the code is passing.

Ruby doesn't have keyword arguments, but it fakes them pretty well.

def explain(options={}) "the #{options[:the]} says #{options[:says]}" end

explain the: "pig", says: "oink" # => "the pig says oink" explain the: "frog", says: "ribbit" # => "the frog says ribbit"

Which is fine, but it isn't as declarative (and therefore not as

self-documenting) as proper keyword arguments.

Also, when using keywords to construct English-like DSLs, as we are

above, we often would like to assign different names to the

parameters which are passed by keyword.

def explain2(options={}) animal = options[:the] sound = options[:says] "the #{animal} says #{sound}" end

And then there's defaulting for missing paramters...

def explain3(options={}) animal = options.fetch(:the) { "cow" } sound = options.fetch(:says){ "moo" } "the #{animal} says #{sound}" end

explain3 # => "the cow says moo"

Of course, it might be nice to offer a positional-argument version

as well.

def explain4(*args) options = args.last.is_a?(Hash) ? args.pop : {} animal = args[0] || options.fetch(:the) { "cow" } sound = args[1] || options.fetch(:says){ "moo" } "the #{animal} says #{sound}" end

explain4 "horse", "neigh" # => "the horse says neigh" explain4 "duck", says: "quack" # => "the duck says quack" explain4 the: "donkey", :says => "hee-haw" # => "the donkey says hee-haw"

Once we've written all this parameter-munging machinery, we then

repeat it in the method's documentation. (Assuming we document it at

all). This seems a bit un-DRY.

Let's see if we can improve on the situation.

require 'keyword_params'

class BarnYard extend KeywordParams

keyword(:the) { "cow" } keyword(:says) { "moo" } def explain(animal, sound) "the #{animal} says #{sound}" end end

b = BarnYard.new

b.explain "horse", "neigh" # => "the horse says neigh" b.explain "duck", says: "quack" # => "the duck says quack" b.explain the: "donkey", :says => "hee-haw" # => "the donkey says hee-haw" b.explain the: "cat" # => "the cat says moo" b.explain # => "the cow says moo"

Improvement? Well, I'll leave that for you to judge. Certainly

specifying part of the method's signature above the method

definition proper has a nasty "old-style C" feel to it. But I feel

like it's a lot more self-documenting than doing the keyword

processing inside the method.