Ruby DSL Handbook (opens in new tab)

I'm the author. In fact, the first bit of advice I have in the book is: Don't. DSLs often involve metaprogramming, but they don't have to. I'm writing it to record the code practices that I have found useful in getting things right and gather advice and tips from others who have done the same. DSLs are always about communication, so my goal is to create a book that helps developers communicate the purpose of the aspects of their project through code.

Almost any problem can be meaningfully and usefully solved by introduction of a DSL. It's a remarkably flexible technique.

Ruby is a really bad language to write good DSLs in. Metaprogramming is an awkward replacement for better DSL facilities.

Maybe this book can demonstrate better techniques?

I should someday make a screencast showing how I use DSLs in my projects. I've done the "couple dozen functions" thing enough times to know it only goes so far, whenever I find myself reaching for a DSL, I'd wished I'd done it sooner.

DSLs should be looked at as syntactic sugar for object instantiation. Language methods should set the object's state or run an instance method. Object behavior goes in the object's class.

I'm looking at one of my DSLs, it's a module with a parse method that takes a file with a default argument to the common "XXXXfile" that I see used a lot for DSLs. It opens the file and module_eval's the code. I use instance and module variables to hold state in the execution context of the DSL.

If you stick to this pattern you'll find a DSL easy to manage. I use it as a replacement for instantiating objects with YAML files, which I find brittle. I hate maintaining those, but a DSL will give me just the right amount of indirection. I can express the objects exactly how I want them to be expressed, which is a big win for me.

how about: every DSL should be a thin translation layer over a clean API. Too many times I've been burned by gems that provide a DSL and there's no other way to use their functionality.

That you suffered from DSL is probably a sign that this book will be filling a gap :-)

I had /some/ bad experiences with some DSL, but most of my experiences with them were pretty good (even those who I didn't write).

This surprises me. Can you offer an example of those types of problems in some Ruby code?

Not yet. But you can signup for a 5-email crash course. It's being updated almost every day now as I add more content.