The Is It a DSL or an API? Ten Question Checklist

by chromatic

You can't spend more than ten minutes at RailsConf without hearing the dreaded three-letter acronym DSL. They're everywhere these days in the Rails and Ruby worlds. I think I ate one for lunch (either that, or it was a grilled portobello mushroom sandwich).

Confusingly, every example of a DSL I saw looked like something I would have called an API before my sudden immersive enlightenment.

If I'm confused about what a DSL is, you must be too. I took copious notes through the sessions on Friday and have devised a simple, ten-question test to help you determine whether a wad of code represents a DSL or an API.


2007-05-19 08:54:37
There are plenty of Rubyists sick of hearing APIs being called DSLs.

But there are some loud folks making it difficult to hear those complaints, sadly. :-/

Funny post, maybe it'll help people realize that nice function names with no parens does not equate to a new language.

2007-05-19 10:27:15
Is this a criticism of Ruby, or of its proponents? Serious question, as I'm watching from the wings and have probably missed many of the DSL claims that you've found frustrating.

As I understand the concept of a DSL, it is the creation and use of a vocabulary and/or syntax appropriate to a particular body of knowledge, class of problem, etc. (the "Domain"). It might be an extension of *any* underlying programming language, or none at all. It's not about the language itself. Yet your criticisms appear to be targeting fundamental aspects of the design of Ruby the language.

Are you perceiving Rubyists to be asserting that *because* they're using Ruby, their code is automatically a DSL? Or are they somehow claiming that Ruby itself is a DSL?

Perhaps the Rubyists are suggesting that DSLs are easier to express in Ruby, an assertion which merely boils down to opinion and preference.

If they are pointing to Rails and saying, "look, there's a DSL," they may not be totally off-base (as I understand the term). If the Domain is a certain class of web application, Rails *is* a "Language" for that purpose. I don't know that *I* would classify it as a DSL (Framework seems more appropriate), but I wouldn't begrudge others thinking of it as one. I might, though, suggest that this particular Domain (web apps) is a bit overly-broad, and that the things really worth calling DSLs require a bit more "Specific"-ness to qualify.

Perrin Harkins
2007-05-19 15:22:04

The obsession with syntax, and making otherwise normal code look like a different language by playing with the position of parentheses and using tricks like overloading is one of my least favorite aspects of the Perl community. Sad to hear that it's so popular in the Ruby community as well, although I suppose it's to be expected since the languages are so similar.

The impulse to create your own little consistent API for expressing something is a good one. Putting lipstick on it and calling it a DSL is probably not so good.

Piers Cawley
2007-05-19 15:37:20
Without wishing to put words into chromatic's mouth, the really annoying thing is that starry eyed look of wonder that the "It's a DSL! Sunshine! Puppies! Only Ruby can do this because I have no experience of any other language but Java or PHP! Oooh... method_missing! instance_eval!" crowd.

Maybe we're just old farts complaining about these young whippersnappers raving about stuff we learned about a long time ago. Maybe we should try and cut 'em some slack.

2007-05-19 16:32:55
@jonblock, what you describe in your second paragraph is the use of domain-specific language, not the creation of A Domain Specific Language!

This is just one of my criticisms of the Ruby Community post-Rails. There are plenty of noisy people who seem to have just discovered things that the wider world of programming (or at least programming in dynamic languages) have been developing for ten to twenty years.

There are plenty of clever, experienced, humble, and thoughtful programmers too... but there's a definite (but hopefully small) group of noisy people who are long on opinions but appear short on practical knowledge.

2007-05-19 17:19:00
@chromatic: More like 40 years actually. If you read the "On LISP" by Paul Graham, it states the best way to write applications in LISP, is to extend your LISP environment into a language to write that application. So, if you want to write a word processor, extend LISP to be a word processor language.

Now, someone just slapped a new name of this development technique, "Domain Specific Language", and somehow it is new, cool, and amazing. "On LISP" is over 10 years old, and LISP was one of the first programming languages (at least 40 years old).

But even then, I content you have not created a new language, until you have created a parser and interpreter. Using some of the syntax magic in Ruby to create a fancy API, is not making a new language, just like it wasn't 40 years ago when LISP introduced an extendable environment (although LISP also happens to be suited for writing parsers and interpreters).

Those who don't know LISP, are doomed to fail like it did.

2007-05-20 06:30:14
Tom, confusing rarefied appeal with failure is only appropriate if you define success in purely numeric terms.
2007-05-20 16:01:56
First, a quibble: DSL is not an acronym. It's an intialism.

But otherwise you are dead on. I prefer to call such APIs domain-specific dialects. (Or domain-specific jargon, or domain-specific slang even.)

But "language" is a bit too much.

:language != language

2007-05-20 18:15:57
I played around with Forth a while back and to me it seemed so natural for creating extensions to the language, by defining new 'words' . The washing machine example in Leo Brodie's classic Starting Forth may seem extremely simple but I think Forth truly allows you to extend the language to the point where the new words are fully able to describe the domain and manipulate it.

Although Ruby allows one to create DSL's, the meta gymnastics involved make it seem clunky when compared to Forth solutions to the same problem space, granted that Forth has its own problems.

From that book the washing machine example goes something like:


Now this is what I'd call a Domain Specific Language!

Other successful/notable 'DSLs' developed using Forth or its dialects are probably PostScript and the OpenFirmware wordset that describes the Apple etc. specific hardware.

Would you consider these two examples above 'proper' DSLs ? and what is your opinion of Forth being almost as suitable for developing domain specific extensions to a language as LISP ?

2007-05-20 22:02:56
@amr: That reminds me of Perl (or Ruby with '%w' instead of 'qw'):


On the one hand, when you reduce your embedding language to a tokenizer, you might actually end up having to create a language. On the other hand, many languages can be tokenizers.
Ivan Tikhonov
2007-05-21 03:19:53
DSL is a words for writing solution.
API is a words for kicking someone else to make work for you.
2007-05-21 03:49:02
@sean : Sean, those are user-defined executable words linked into the Forth wordset (dictionary) even though they look like arguments to the "word" being defined right after th ":" defining word.. Any arguments to 'RINSE', 'FAUCET-OPEN' etc. would be on the stack(s).
2007-05-21 06:25:28
Despite all this hype about Ruby DSLs, Ruby really doesn't have the facilities to do what has traditionally been DSLs. Better look at CommonLisp (reader Macros) for a language that supports real DSLs out of the box.

2007-05-21 10:28:51
Finally, the silliness brought to light in a way that actually gets some attention. I think unintentionally this is a pretty strong critique of the Ruby (more so Rails if not all Rails) community. The onus is on them to objectively characterize the work they do, and jumping to definitions like DSL just make it so much more unnattractive. That they've cultivated the Starbucks/Mac populace and rebranded them as software engineers is the nail in the coffin for me.
Peter Bell
2007-05-21 11:54:16
I'm gonna take different slant on this. From an "inclusive" definition, an API is just one concrete syntax that can be used to express certain types of DSLs (some grammars and use cases map better to different projections: APIs, in language DSLs, boxes and arrows, tables, database schemas, XML, custom textual languages with parsers or maps).

The big benefit to me about calling these DSLs is that you can start to take advantage of all of the interesting work being done on problems like versioning and evolving collections of non-orthogonal DSLs which is a problem API designers have had to consider (I think Ralph Johnson has a grad student working on approaches to evolvable APIs) but by bringing together people together solving the same class of problems using different concrete syntaxes.

2007-05-21 12:04:00
@amr: My bad -- that's defining RINSE to be a function ("word") that calls the listed functions in sequence? It's sort of beside the point: I was suggesting that if your language has almost no syntax, it's easy to add more "no-syntax" to it, and call that a DSL. But this shouldn't fool anyone. There are two reasons it may be easy to add constructs to a language that look like the rest of the language: first, it may have powerful means for extension (e.g. MetaOCaml); second, it may be so limited that it's trivial to add more stuff that follows the same rules (e.g. TCL).

Just for fun, here's a little forthification for your perl:

sub colon(*@) {
my ($name, @foo) = @_;
*$name = sub { &$_ for @foo };

sub a { print 'a' }
sub b { print 'b' }
sub c { print 'c' }

colon rinse, qw(a b c);

Chris Carter
2007-05-23 17:42:14
here is a manual trackback regarding the :nouns.
2007-05-25 02:17:10
chromatic, DSLs are not the talk of the town and certainly weren't at RailsConf. It's cool you attended, but I'm disappointed that all you've got for us is an off-base, sarcastic snipe. Building up then playing off these stereotypes is just plain bitchy.
2007-05-25 02:25:47
After reading your well-considered comments on Piers' article, I only wish you'd taken a second and picked 'thoughtful prose' over 'hyperbolic shitlist' for this piece as well! Cheers :-)
2007-05-25 10:14:13
@Jeremy, I almost walked out of one talk because of the presenter's attitude. I have no desire to single out anyone in public (and I'm prepared to take a lot of criticism for my vague criticism here), but I did hear plenty of over-the-top talk about DSLs and language design at RailsConf. Perhaps I just had the misfortune of being in the wrong places at the wrong time.

I do appreciate your suggestion to expand the thoughts I posted on Piers's journal, however. I'll do that; thank you.

2007-05-25 14:22:08
I'd like to flip the question around for a moment and play the Devil's Advocate. Does the inclusion of a colon or underscore automatically disqualify a piece of code from consideration as a DSL? For that matter, what about parentheses? If so, even our canonical LISP examples may be in trouble, and AppleScript may wind up being the closest thing we have to a DSL. ;)

All snarkiness and kidding aside, I'll concede that there's a general tendency to call almost any use of domain-specific language (lowercase) a DSL these days, but I've not seen any illuminating guidelines on what constitutes a DSL and what doesn't. Much of it is a matter of opinion and taste. In the end, I'm not sure it matters much anyway, but it does make for an amusing post on a Friday afternoon.

2007-06-20 10:40:29
How's perl 6 coming, chromie? ;-)


2007-06-20 11:13:38
@perlrulz, Perl 6 in the just-released Parrot 0.4.13 passes the first set of sanity tests. We'll have it parsing and using in the next couple of weeks, if all goes well at the YAPC::NA hackathon.

(On topic: Parrot is a great toolkit for building actual DSLs.)

2007-06-20 20:11:21
I was really just kidding but couldn't resist

when perl6 comes of age, I will certainly give it a shot.
already, perl is great for ruby-ish dsls (eg, jifty ddl).

Tanton Gibbs
2007-07-16 12:57:06
This brings to mind Bjorne Stroustrup's comment that "Language design is library design. Library design is language design." The two are almost inseparably related. When you create an API, you're creating the language in which the user will think about the problem. When you create a language, you're creating a library that the user can use to solve the problem. The reason they seem so related is that they are! Now, we have precise meanings for both DSLs and APIs, but lets not forget that they are basically solving the same problem.
Steve Freeman
2007-07-18 19:08:41
Has anyone noticed how much the Ruby DSLs look like COBOL? Maybe there's an upgrade path there...