flume-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Hansen <dsche...@gmail.com>
Subject Flumes DSL syntax
Date Thu, 08 Sep 2011 21:14:19 GMT
I think I finally get the syntax for the most part -- but it took
finding and skimming through a book on ANTLR to figure it out.  The
pertinent information is in FlumeDeploy.g

It seems to me that the syntax is relatively straight forward once you
get that sinks, sources and decorators are all just functions and they
all follow the same lexical pattern as functions.  Unfortunately the
"function" syntax is the one all important pattern that's missing from
the documentation (or if it's there it's hidden behind a jedi master
saying "these are not the specs you are looking for").

The key is explaining that function calls follow a syntax slightly
more like that of Ruby or Python than that of Java in that the
parentheses for arguments are optional -- except that they aren't
exactly optional because they're required if you actually want to pass
any arguments to the function.

Then it's just a matter of explaining that arguments are themselves
either functions or literals (string, numeric, boolean).  Further,
required arguments always come first and they may be followed by
optional arguments which (much like in ruby and python) can be passed
in as named arguments where argName=argValue -- this allows you to
skip over arguments you don't want to override if they happen to come
before arguments you do want to override.

Personally I'd avoid explaining any of this optionality with square
brackets, because square brackets are significant characters that show
up elsewhere (fan-out sources). In some cases it's relatively clear to
me that brackets indicate an argument is optional -- for instance
functionName(arg1[,arg2]*) is clear to me, but "Usage:
functionName[(arg1,arg2)]" in an error message telling me I've done
something wrong just makes me think, crap, did I need to put brackets
in there?

Does anybody else think that kind of explanation would have been
helpful when you were starting out?


View raw message