I am a big fan of Ruby. There are so many beautiful libraries out there and most of them are based on some kind of domain specific language. Take builder as an example:
Builder::XmlMarkup.new.person { |b| b.name("Jim"); b.phone("555-1234") }
#=> <person><name>Jim</name><phone>555-1234</phone></person>
Generating XML in this manner is pretty cool! There is no crazy XML editor in the world that gives you as much flexibility as this straight forward DSL. I think that a good DSL makes coding feel natural.
HOWTO DSL
If you did read Ruby best practicies or stuff like that, this article won’t bring anything new to you. In case you did not, you should start right away!
Anyhow, there are some simple rules behind writing a good DSL or API:
- let the user choose how to use it
- make options optional
- make use of an option hash for defaults
- make use of scoped blocks
- make use of instance_eval
- consider implementing method_missing
I am going to explain these rules for you, so that you can start writing your own cool DSL and help make programming Ruby even more fun.
the Regexp DSL
I think that regular expressions are a great tool and they are ubiquitous in Ruby. Regexps are a first class citizen in Ruby and so you get a lot of built-in power for free. There are also some decent Regexp guides on the web waiting for you:
Regular expressions are a framework of their own, embedded into lots of programming languages. The biggest problem that I have with the Regexp DSL is missing readability. Take a look at the monster that lives in the dark pit of URI::REGEXP::PATTERN:
/
([a-zA-Z][-+.a-zA-Z\d]*): (?# 1: scheme)
(?:
((?:[-_.!~*'()a-zA-Z\d;?:@&=+$,]|%[a-fA-F\d]{2})(?:[-_.!~*'()a-zA-Z\d;\/?:@&=+$,\[\]]|%[a-fA-F\d]{2})*) (?# 2: opaque)
|
(?:(?:
\/\/(?:
(?:(?:((?:[-_.!~*'()a-zA-Z\d;:&=+$,]|%[a-fA-F\d]{2})*)@)? (?# 3: userinfo)
(?:((?:(?:(?:[a-zA-Z\d](?:[-a-zA-Z\d]*[a-zA-Z\d])?)\.)*(?:[a-zA-Z](?:[-a-zA-Z\d]*[a-zA-Z\d])?)\.?|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[(?:(?:[a-fA-F\d]{1,4}:)*(?:[a-fA-F\d]{1,4}|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})|(?:(?:[a-fA-F\d]{1,4}:)*[a-fA-F\d]{1,4})?::(?:(?:[a-fA-F\d]{1,4}:)*(?:[a-fA-F\d]{1,4}|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}))?)\]))(?::(\d*))?))?(?# 4: host, 5: port)
|
((?:[-_.!~*'()a-zA-Z\d$,;:@&=+]|%[a-fA-F\d]{2})+) (?# 6: registry)
)
|
(?!\/\/)) (?# XXX: '\/\/' is the mark for hostport)
(\/(?:[-_.!~*'()a-zA-Z\d:@&=+$,]|%[a-fA-F\d]{2})*(?:;(?:[-_.!~*'()a-zA-Z\d:@&=+$,]|%[a-fA-F\d]{2})*)*(?:\/(?:[-_.!~*'()a-zA-Z\d:@&=+$,]|%[a-fA-F\d]{2})*(?:;(?:[-_.!~*'()a-zA-Z\d:@&=+$,]|%[a-fA-F\d]{2})*)*)*)? (?# 7: path)
)(?:\?((?:[-_.!~*'()a-zA-Z\d;\/?:@&=+$,\[\]]|%[a-fA-F\d]{2})*))? (?# 8: query)
)
(?:\#((?:[-_.!~*'()a-zA-Z\d;\/?:@&=+$,\[\]]|%[a-fA-F\d]{2})*))? (?# 9: fragment)
/xn
You don’t need to write such complex expressions to get to the point where you don’t understand the Regexp you wrote just 2 minutes ago. That’s why Ruby provides an extended mode that allows you to insert spaces, newlines and comments in the pattern:
def test_multiline_regex_with_comments
assert_match(%r[a # the a
n # the n
]x, 'anna')
end
This is nothing that feels natural to me… So I started working on my own regular expression DSL.
lessons learned from Rebuil
It is always a good idea to write a DSL. There is no better way of becoming a domain expert than implementing a custom language for that specific domain. The other great thing is that you get in depth knowledge of the key Ruby features that help you creating crisp APIs and neat frameworks.
The vision that I have about using Regexps is a very descriptive one. There are probably some people that would call it verbose, but there is always a tradeoff:
exp = rebuil.many.group('rebuil', :cool_name)
puts "hello #{exp.match('hello world with rebuil')[:cool_name]} world!"
#=> hello rebuil world
This code basically creates the Regexp ’.*(rebuil)’. The cool thing is that you get named groups like in Ruby 1.9 for accessing them with descriptive symbols instead of an index.
let the user choose how to use it
The first advice for creating a DSL is important if you want to make your library sexy for other developers. Since most hackers have different coding styles, they prefer different types of expressions. A good example for this are the different ways one can create Rebuil objects:
# standard approach
Rebuil::Expression.new.group('a')
# helper within object
rebuil.group('a')
# helper with a block
rebuil do |exp|
exp.group('a')
end
# helper with some starting pattern
rebuil("").group('a')
As all implemented Rebuil methods return the object instance itself, one can chain method calls for convenience.
make options optional
The rebuil method can take a string as an argument for the start of the expression. As you can see in the example above, this argument is optional.
A well designed API does not force the user to provide arguments that are not mandatory.
make use of an option hash for defaults
If you end up with a lot of optional parameters in your method signature, you should consider using an optional parameter hash as the last method argument. Using carefully picked keys for the parameters gives the impression of named parameters wich improves readablity greatly:
def some_method(man, da, tory, options={:some=>'defaults'})
...
end
make use of scoped blocks
Providing scopes is another way to improve the readability of your code. Ruby makes it easy to do scope based programming with blocks:
# no scope
exp = rebuil
exp.group('a')
exp.characters('a')
exp.many
# better with a block
rebuil do |exp|
exp.group('a')
exp.characters('a')
exp.many
end
This can be achieved by just yielding a Rebuil::Expression if a block is given.
make use of instance_eval
Blocks can also be used to reduce the code you will have to write. The scoped block example above can be rewritten with less code:
# smooth with instance_eval
rebuil do
group('a')
characters('a')
many
end
Evaluating the block in the context of the current object is as simple as passing it on to Rubies instance_eval. The only drawback is that you can’t access stuff from your current scope like member variables. But there is a way to make both solutions work, just ask the block for the number of arguments:
def rebuil(expression="", &block)
...
# block.arity returns the number of expected arguments of the block
block.arity < 1 ? re.instance_eval(&block) : block.call(re) if block_given?
...
end
consider implementing method_missing
Highly dynamic DSLs like Builder follow a different approach. They implement method_missing. The great advantage is that the user can posibly call anything on your object. The domain logic lies within your implementation of method_missing, which passes the name of the originally called method, the parameters and an optional block. Since regular expressions are deterministic, this dynamic approach does not suite Rebuil well.
With great power comes great responsibility. Always try to find the most appropriate implementation for your specific domain.
And don’t forget the sugar!