What separates a Ruby DSL from an ordinary API

Question

What are some defining characteristics of a Ruby DSL that separate it from just a regular API?

Answer 1

When you use an API you instantiate objects and call methods in an imperative manner. On the other hand a good DSL should be declarative, representing rules and relationships in your problem domain, not instructions to be executed. Moreover ideally DSL should be readable and modifiable by somebody who is not a programmer (which is not the case with APIs).

Also please keep in mind the distinction between internal and external DSLs.

• Internal domain specific language is embedded in a programming language (eg. Ruby). It's easy to implement, but the structure of the DSL is dependent on the parent language it is embedded in.
• External domain specific language is a separate language designed with the particular domain in mind. It gives you a greater flexibility when it comes to syntax, but you have to implement the code to interpret it. It's also more secure, as the person editing domain rules doesn't have access to all the power of the parent language.

Answer 2

DSL (domain specific language) is an over-hyped term. If you are simply using a sub-set of a language (say Ruby), how is it a different language than the original? The answer is, it isn't.

However, if you do some preprocessing of the source text to introduce new syntax or new semantics not found in the core language then you indeed have a new language, which may be domain-specific.

Answer 3

The combination of Ruby's poetry mode and operator overloading does present the possibility of having something that is at the same time legal Ruby syntax and a reasonable DSL.

And the continued aggravation that is XML does show that perhaps the simple DSL built into all those config files wasn't completely misguided..

Answer 4

Creating a DSL:

• Adding new methods to the Object class so that you can just call them as if they were built-in language constructs. (see rake)

• Creating methods on a custom object or set of objects, and then having script files run the statements in the context of a top-level object. (see capistrano)

API design:

• Creating methods on a custom object or set of objects, so the user creates an object to use the methods.

• Creating methods as class methods, so that the user prefixes the classname in front of all the methods.

• Creating methods as a mixin that users include or extend to use the methods in their custom objects.

So yes, the line is thin between them. It's trivial to turn a custom set of objects into a DSL by adding one method that runs a script file in the right context.