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

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 2

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 3

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.

Answer 4

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 5

The difference between a DSL and an API to me is that a DSL could be at least understood (and verified) if not written as a sub-language of Ruby by someone in that domain.

For example, you could have financial analysts writing rules for a stock trading application in a Ruby DSL and they would never have to know they were using Ruby.

Answer 6

They are, in fact, the same thing. DSLs are generally implemented via the normal language mechanisms in Ruby, so technically they're all APIs.

However, for people to recognize something as a DSL, it usually ends up adding what look like declarative statements to existing classes. Something like the validators and relationship declarations in ActiveRecord.

class Foo << ActiveRecord::Base
  validates_uniqueness_of :name
  validates_numericality_of :number, :integer_only => true

end

looks like a DSL, while the following doesn't:

class Foo <<ActiveRecord::BAse
  def validate
    unless unique? name
      errors.add(:name, "must be unique")
    end

    unless number.to_s.match?(/^[-]?\d$/)
      errors.add(:number, "must be an integer")
    end
  end
end

They're both going to be implemented by normal Ruby code. It's just that one looks like you've got cool new language constructs, while the other seems rather pedestrian (and overly verbose, etc. etc.)