Introduce an "idl"-like format description for analyzer summaries.

Introduce an "idl"-like format description for analyzer summaries.

Not yet used.  This is mostly copied from experiments done earlier in
the year, and is therefore incomplete; I plan to refine this in the
process of fleshing out the implementation and tests.

R=scheglov@google.com

Committed: https://github.com/dart-lang/sdk/commit/fc1f07fe2ee04640917751607ceaea6b031d9a1d

[Paul Berry, 2015-10-20 00:00:12]

paulberry@google.com changed reviewers:
+ brianwilkerson@google.com, scheglov@google.com

[scheglov, 2015-10-20 00:20:22]

LGTM

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
File pkg/analyzer/tool/summary/idl.dart (right):

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:59: class Flag {
Is it an enumeration, a bitfield or both?

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:314: * Offset of the "import" keyword.  Zero
for implicit imports.
AFAIK we use -1 for synthetic elements.
It is possible to have a non-synthetic import at zero.

[Paul Berry, 2015-10-20 15:54:09]

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
File pkg/analyzer/tool/summary/idl.dart (right):

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:59: class Flag {
On 2015/10/20 00:20:22, scheglov wrote:
> Is it an enumeration, a bitfield or both?

Kind of a mishmash of both.  I guess it's not very clean.  I'll make a follow-up
CL to try to make things clearer.

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:314: * Offset of the "import" keyword.  Zero
for implicit imports.
On 2015/10/20 00:20:22, scheglov wrote:
> AFAIK we use -1 for synthetic elements.
> It is possible to have a non-synthetic import at zero.

Acknowledged.  That's why I have an "IMPLICIT" flag below--to allow these cases
to be distinguished.

I've added a comment to clarify.

[Paul Berry, 2015-10-20 16:09:47]

Committed patchset #1 (id:1) manually as
fc1f07fe2ee04640917751607ceaea6b031d9a1d (presubmit successful).

[Brian Wilkerson, 2015-10-20 18:07:15]

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
File pkg/analyzer/tool/summary/idl.dart (right):

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:119: * Index into
[LibraryElement.dependencies] indicating which imported library
"LibraryElement" --> "UnlinkedLibrary"?

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:120: * declares the entity being referred to.
It isn't clear whether indexes like this one are zero based or one based. There
are places where an index is described as being "... or zero if ...", which
implies that zero isn't a valid index, but there are also places where you
explicitly state "A one based index ...".

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:124: @Flag('CLASS', 0, 'Indicates that the
thing being referred to is a class')
Does "class" here include "enum", or should that be a separate flag?

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:130: int flags;
Another possibility here would be to declare 'bool' valued fields and leave it
up to the code generator to decide how / whether to compact those fields. For
example:

/**
 * Indicates that the thing being referred to is a class.
 */
bool isClass;

/**
 * Indicates that the thing being referred to is a typedef
 */
bool isTypedef;

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:156: * a supertype.
Or if the class is `Object` and hence has no supertype?

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:213: * Values listed in the enum declaration.
Presumably in declaration order? (It isn't clear which lists preserve lexical
order and which don't. Perhaps they all do, in which cases a general statement
to that effect would help.)

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:271: * parameters, and setters have a single
parameter.
Do getters have an empty list, or `null`?

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:294: * Relative URI used to reference the
exported library.
I assume that "Relative URI" (here and below) really means "the URI that appears
in source code". ("Absolute" and "relative" have meanings in URI-speak.)

[Paul Berry, 2015-10-20 18:46:20]

Thanks, Brian.  I'll address your issues in follow-up CLs.

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
File pkg/analyzer/tool/summary/idl.dart (right):

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:119: * Index into
[LibraryElement.dependencies] indicating which imported library
On 2015/10/20 18:07:14, Brian Wilkerson wrote:
> "LibraryElement" --> "UnlinkedLibrary"?

Whoops, thanks.  I forgot to update this when I made my final decision on
nomenclature.

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:120: * declares the entity being referred to.
On 2015/10/20 18:07:14, Brian Wilkerson wrote:
> It isn't clear whether indexes like this one are zero based or one based.
There
> are places where an index is described as being "... or zero if ...", which
> implies that zero isn't a valid index, but there are also places where you
> explicitly state "A one based index ...".

You're right, this isn't particularly clear.  In a future CL I will experiment
with alternatives.

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:124: @Flag('CLASS', 0, 'Indicates that the
thing being referred to is a class')
On 2015/10/20 18:07:14, Brian Wilkerson wrote:
> Does "class" here include "enum", or should that be a separate flag?

It includes enum.

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:130: int flags;
On 2015/10/20 18:07:14, Brian Wilkerson wrote:
> Another possibility here would be to declare 'bool' valued fields and leave it
> up to the code generator to decide how / whether to compact those fields. For
> example:
> 
> /**
>  * Indicates that the thing being referred to is a class.
>  */
> bool isClass;
> 
> /**
>  * Indicates that the thing being referred to is a typedef
>  */
> bool isTypedef;

I like this idea.  I will experiment with this in a future CL.

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:156: * a supertype.
On 2015/10/20 18:07:14, Brian Wilkerson wrote:
> Or if the class is `Object` and hence has no supertype?

Correct.

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:213: * Values listed in the enum declaration.
On 2015/10/20 18:07:14, Brian Wilkerson wrote:
> Presumably in declaration order? (It isn't clear which lists preserve lexical
> order and which don't. Perhaps they all do, in which cases a general statement
> to that effect would help.)

Yes, this one has to be in declaration order because the enum value is inferred
from the order.

As to the general question of how declarations are sorted, I don't know.  I'll
give it some thought.

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:271: * parameters, and setters have a single
parameter.
On 2015/10/20 18:07:14, Brian Wilkerson wrote:
> Do getters have an empty list, or `null`?

In keeping with protobuf semantics, I'm planning to have the code generation
logic treat null as equivalent to the empty list.  I'll clarify this in the
comments.

https://codereview.chromium.org/1410383004/diff/1/pkg/analyzer/tool/summary/i...
pkg/analyzer/tool/summary/idl.dart:294: * Relative URI used to reference the
exported library.
On 2015/10/20 18:07:14, Brian Wilkerson wrote:
> I assume that "Relative URI" (here and below) really means "the URI that
appears
> in source code". ("Absolute" and "relative" have meanings in URI-speak.)

Correct.