API's that Suck

May 21, 2009

An API, not matter how cool you think it is, is not a DSL

Filed under: Uncategorized — Grauenwolf @ 9:58 pm

A DSL or Domain Specific Language, is a way to represent some domain-specific concept. For example, I’m looking for a DSL that can be used to describe date equations such as “the 2nd business day after the last business day of the month”. This information will find itself in various configuration files and database tables.

Unfortunately, all the recommendations I’ve been getting are for so-called “Internal DSLs”. The problem with that is they are not “domain-specific”, they are “language-specific”. You can’t use a Ruby’s Chronic from .NET or T-SQL without building a full Ruby parser. Nor can you use Java’s JODA Time or Perl’s Date::Manip. There are all API’s, not languages.

That isn’t to say there isn’t a DSL hidden in each of these. They all have some sort of meta-language describing how to format strings that you pass to their Parse methods . Unfortunately they are mostly undocumented. Chronic says it “Parses a string containing a natural language date or time”, but you are left to guessing what exactly that means from the examples.

Therefore I am moved to propose this definition for a DSL:

A Domain Specific Language is documentation on to how to parse a set of text or symbols in a consistent and repeatable fashion.

Let us turn back to JODA Time. Can you determine how to parse “Days d = Days.daysBetween(startDate, endDate);” from the JODA docs? Of course not, you also have to look up the language spec for Java. Java is the real language here, not JODA Time.

Turning to Date::Manip, we see that it has a parse complex date patterns such as “2nd day of every month [in 1997]".

0:0:0:1*2,4,6:0:0 every day at at 2:00, 4:00, and 6:00
0:0:0:2*12-13:0,30:0 every other day at 12:00, 12:30, 13:00, and 13:30
0:1:0*-1:0:0:0 the last day of every month *1990-1995:
12:0:1:0:0:0 Dec 1 in 1990 through 1995

It then goes on to explain exactly how to parse it (I will refer you to the documentation for details, start with the ParseRecur section for the actual DSL descriptions). I don’t know anything about Perl, but I don’t think I’ll have any problem porting this to .NET or T-SQL. It is a little unfriendly, more like an AST than an end-user language. But then again, so are Regular Expressions and they are clearly useful.


1 Comment »

  1. Look at the “chained iteratation” example for this codeproject article. It sounds like it might, at the very least, help in a conceptual way if you can’t/don’t want to use the code as it is.


    Comment by Ian MacLean — May 22, 2009 @ 12:26 pm

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

Blog at WordPress.com.

%d bloggers like this: