tools/gn: add "gn help grammar" with formal grammar

tools/gn: add "gn help grammar" with formal grammar

BUG=466847
Committed: https://crrev.com/922fc336f62d583b888c9fa5b5f78bf3dfd6c1e9
Cr-Commit-Position: refs/heads/master@{#322314}

[mdempsky, 2015-03-26 00:57:42]

mdempsky@chromium.org changed reviewers:
+ brettw@chromium.org

[Dirk Pranke, 2015-03-26 01:29:47]

dpranke@chromium.org changed reviewers:
+ dpranke@chromium.org

[Dirk Pranke, 2015-03-26 01:29:48]

At this stage in GN's life, I'd probably make this a wiki page rather than
embedding it into the binary, but I don't feel that strongly about it.

I would also probably say "help grammar" rather than "help syntax", under the
theory that I'd rather save "help syntax" for something less formal like the
contents of https://code.google.com/p/chromium/wiki/GNLanguage (or parts of it
and the QuickStart, at least).

I definitely would not include both this and the trailing-comma thing in the
same patch. I would make those be two different patches.

I am not a huge fan of the trailing comma thing. While I wouldn't take it out of
the language if it was there, I wouldn't add it. I've never needed this in
Python, and never seen it used in Python (and was surprised to see that it
actually works). I would consider it to be at least a style violation if not an
outright bug if someone did use it. 

Not having written any significant amount of Go, I can't pass judgement on
whether the same thing would apply there.

https://codereview.chromium.org/1015063003/diff/1/tools/gn/parser.cc
File tools/gn/parser.cc (right):

https://codereview.chromium.org/1015063003/diff/1/tools/gn/parser.cc#newcode28
tools/gn/parser.cc:28: "  Comments start at the character \"#\" and stop at the
end of the line.\n"
If you wanted to be picky, how is the "end of the line" defined?

[mdempsky, 2015-03-26 02:09:39]

On 2015/03/26 01:29:48, Dirk Pranke wrote:
> At this stage in GN's life, I'd probably make this a wiki page rather than
> embedding it into the binary, but I don't feel that strongly about it.

You know I'm not a fan of "gn help", but I'm proposing putting it here because
the "gn help" documentation seems better maintained.  The GN wiki in contrast
says GN doesn't have function calls
(https://code.google.com/p/chromium/wiki/GNLanguage#Language).

> I would also probably say "help grammar" rather than "help syntax", under the
> theory that I'd rather save "help syntax" for something less formal like the
> contents of https://code.google.com/p/chromium/wiki/GNLanguage (or parts of it
> and the QuickStart, at least).

Done.

> I definitely would not include both this and the trailing-comma thing in the
> same patch. I would make those be two different patches.

Done.

> I am not a huge fan of the trailing comma thing. While I wouldn't take it out
of
> the language if it was there, I wouldn't add it. I've never needed this in
> Python, and never seen it used in Python (and was surprised to see that it
> actually works). I would consider it to be at least a style violation if not
an
> outright bug if someone did use it. 
> 
> Not having written any significant amount of Go, I can't pass judgement on
> whether the same thing would apply there.

The main usage I see in Python and Go for allowing trailing commas is for
multiline function calls like

    Foo(
        1,
        2,
    )

analogous to multiline list expressions.

> If you wanted to be picky, how is the "end of the line" defined?

I changed it to "next newline" to be unambiguous.

[scottmg, 2015-03-26 02:17:06]

On Wed, Mar 25, 2015 at 7:09 PM, <mdempsky@chromium.org> wrote:

> On 2015/03/26 01:29:48, Dirk Pranke wrote:
>
>> At this stage in GN's life, I'd probably make this a wiki page rather than
>> embedding it into the binary, but I don't feel that strongly about it.
>>
>
> You know I'm not a fan of "gn help", but I'm proposing putting it here
> because
> the "gn help" documentation seems better maintained.  The GN wiki in
> contrast
> says GN doesn't have function calls
> (https://code.google.com/p/chromium/wiki/GNLanguage#Language).
>
>  I would also probably say "help grammar" rather than "help syntax", under
>> the
>> theory that I'd rather save "help syntax" for something less formal like
>> the
>> contents of https://code.google.com/p/chromium/wiki/GNLanguage (or parts
>> of it
>> and the QuickStart, at least).
>>
>
> Done.
>
>  I definitely would not include both this and the trailing-comma thing in
>> the
>> same patch. I would make those be two different patches.
>>
>
> Done.
>
>  I am not a huge fan of the trailing comma thing. While I wouldn't take it
>> out
>>
> of
>
>> the language if it was there, I wouldn't add it. I've never needed this in
>> Python, and never seen it used in Python (and was surprised to see that it
>> actually works). I would consider it to be at least a style violation if
>> not
>>
> an
>
>> outright bug if someone did use it.
>>
>
>  Not having written any significant amount of Go, I can't pass judgement on
>> whether the same thing would apply there.
>>
>
> The main usage I see in Python and Go for allowing trailing commas is for
> multiline function calls like
>
>     Foo(
>         1,
>         2,
>     )
>
> analogous to multiline list expressions.


gn format also needs to be updated if we decide to allow this (and decide
what the canonical format is for when trailing commas should exist.).

I don't particularly care for it, but I won't argue either way not being
particularly active in writing .gn files at the moment.


>
>
>  If you wanted to be picky, how is the "end of the line" defined?
>>
>
> I changed it to "next newline" to be unambiguous.
>
>
> https://codereview.chromium.org/1015063003/
>
> To unsubscribe from this group and stop receiving emails from it, send an
> email to chromium-reviews+unsubscribe@chromium.org.
>

To unsubscribe from this group and stop receiving emails from it, send an email
to chromium-reviews+unsubscribe@chromium.org.

[brettw, 2015-03-26 03:10:16]

LGTM.

I don't like trailing commas in function arguments in general, and this doesn't
match the way gn format formats things.

https://codereview.chromium.org/1015063003/diff/60001/tools/gn/parser.cc
File tools/gn/parser.cc (right):

https://codereview.chromium.org/1015063003/diff/60001/tools/gn/parser.cc#newc...
tools/gn/parser.cc:15: "  This help topic defines the grammar for the GN build
language.\n"
This line seems unnecessary.

[mdempsky, 2015-03-26 03:14:53]

The CQ bit was checked by mdempsky@chromium.org

[mdempsky, 2015-03-26 03:14:54]

The patchset sent to the CQ was uploaded after l-g-t-m from brettw@chromium.org
Link to the patchset: https://codereview.chromium.org/1015063003/#ps80001
(title: "Remove line requested by brettw")

[commit-bot: I haz the power, 2015-03-26 03:15:51]

CQ is trying da patch. Follow status at
 https://chromium-cq-status.appspot.com/patch-status/1015063003/80001

[commit-bot: I haz the power, 2015-03-26 04:05:01]

Committed patchset #5 (id:80001)

[commit-bot: I haz the power, 2015-03-26 04:05:41]

Patchset 5 (id:??) landed as
https://crrev.com/922fc336f62d583b888c9fa5b5f78bf3dfd6c1e9
Cr-Commit-Position: refs/heads/master@{#322314}