flume-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jonathan Hsieh <...@cloudera.com>
Subject Re: Flumes DSL syntax
Date Sat, 10 Sep 2011 20:22:08 GMT
Jeff,

Thanks for digging into this.  I'm at the point where this syntax "feels
natural" to me so I'd love you hear you opinion on how to improve the
documentation to make it easier to learn and understand.

I could see how we could improve in the manual be being more explicit than
the terse syntax info.   What do you think that make sense for he usage
warnings?

Thanks,
Jon.

On Thu, Sep 8, 2011 at 2:14 PM, Jeff Hansen <dscheffy@gmail.com> wrote:

> 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
>



-- 
// Jonathan Hsieh (shay)
// Software Engineer, Cloudera
// jon@cloudera.com

Mime
View raw message