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? Thanks, Jeff
