Re: ANN: Ada source code decorator

[Simon Wright <simon@pushface.org>]

Stephen Leake <stephen_leake@acm.org> writes:

> Simon Wright <simon@pushface.org> writes:
>
>> Stephen Leake <stephen_leake@acm.org> writes:

>>> The ASIS _standard_ is open-source; it consists of Ada specs giving
>>> the API.
>>>
>>> The GNAT implementation is also open-source.
>>>
>>> So what is missing?
>>
>> Something to make it clear what the actual structure is. I found it
>> very hard indeed to understand what the API was trying to tell me; 
>
> Perhaps there needs to be more user-friendly documentation of the ASIS
> structure. 

Yes. You have to understand what an API is _about_.

>> for example, a qualified name a.b.c is stored in something like
>>
>>   (a (b (c)))
>>
>> which you can understand a compiler using, 
>
> Well, yes; ASIS is designed to represent the information a compiler
> knows. So it helps to be able to think like a compiler :).
>
>> rather than
>>
>>   <name>
>>       <component>a</component>
>>       <component>b</component>
>>       <component>c</component>
>>    </name>
>
> Well, this has nothing to do with being "open source".
>
> You are arguing that the particular structure defined in the ASIS spec
> is not one you would use for your particular application. 
>
> That is certainly your choice. Everyone else will also have a
> particular choice; probably different. I suspect the choice of
> structure depends heavily on the algorithm you want to implement.

It would be completely unnatural in XML to represent the concept of a
name with components as a nested structure. For a start, the XPath
expressions involved will be unmanageable.

> So it will be very difficult to get agreement on a _standard_ XML
> representation of Ada source code. But it's probably worth trying. 

Indeed.

>> and asis2xml would _definitely_ produce the latter (I forget
>> whether it actually does at this stage).
>
> http://www.pushface.org/asis2xml/ says the structure output by
> asis2xml follows that of ASIS, so I'd be surprised if it did what you
> describe above. 

Well, it does what seemed like a good idea at the time :-) -- ie, what
worked.

> I would argue that an XML structure that is as close as possible to
> the ASIS structure would be the best one to standardize.
>
> When you (Simon Wright), as the author of asis2xml, decided to change
> the representation of a qualified name as above, what criteria were
> you using to determine the "right" structure?
>
> How would that transformation handle expressions like
>
>     Array_1 (i).Function_Pointer_2 (x, y, z).Component

It would probably be fairly close. But the argument list would be
mapped to an XML sequence, I'm sure.

> When using ASIS to implement a non-trivial source processing
> algorithm, the first step is to transform the ASIS-defined structure
> into one that is better for your algorithm; that's what auto_text_io
> does (my ASIS tool). Even if you start from an ASIS-equivalent XML
> representation, that will still be true.

Yes.

For info, the output from

   generic
   package Basis is
      type Base is abstract tagged private;
      procedure Op (B : Base) is abstract;
   private
      type Base is abstract tagged record
         V : Boolean;
      end record;
   end Basis;

was

   <asis>
   <generic_package_declaration>
   <defining_identifier>Basis</defining_identifier>
   <private_type_declaration kind="abstract_private_trait">
   <defining_identifier>Base</defining_identifier>
   <tagged_private_type_definition kind="abstract_private_trait">
   </tagged_private_type_definition>
   </private_type_declaration>
   <procedure_declaration kind="abstract_trait">
   <defining_identifier>Op</defining_identifier>
   <parameter_specification kind="ordinary_trait"
   mode="default_in_mode">
   <defining_identifier>B</defining_identifier>
   <identifier>Base</identifier>
   </parameter_specification>
   </procedure_declaration>
   <ordinary_type_declaration>
   <defining_identifier>Base</defining_identifier>
   <type_definition>
   <tagged_record_type_definition kind="abstract_trait">
   </tagged_record_type_definition>
   <record_definition>
   <component_declaration>
   <defining_identifier>V</defining_identifier>
   <component_definition kind="ordinary_trait" size="8">
   <subtype_indication>
   <identifier>Boolean</identifier>
   </subtype_indication>
   </component_definition>
   </component_declaration>
   </record_definition>
   </type_definition>
   </ordinary_type_declaration>
   </generic_package_declaration>
   </asis>

which probably makes more sense to you than to me. I can get some of
it, of course, but -- for example -- what other sorts of traits are
there and what do they actually mean?