[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15. The Ada-to-XML converter gnat2xml

The gnat2xml tool is an ASIS-based utility that converts Ada source code into XML.

15.1 Switches for gnat2xml  
15.2 Other Programs  
15.3 Structure of the XML  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15.1 Switches for gnat2xml

gnat2xml takes Ada source code as input, and produces XML that conforms to the schema.

Usage:

 
gnat2xml [options] filenames [-files filename] [-cargs gcc_switches]

options:
 
-h
--help -- generate usage information and quit, ignoring all other options
--version -- print version and quit, ignoring all other options

-P `file' -- indicates the name of the project file that describes
      the set of sources to be processed. The exact set of argument
      sources depends on other options specified, see below.

-U -- if a project file is specified and no argument source is explicitly
      specified, process all the units of the closure of the argument project.
      Otherwise this option has no effect.

-U main_unit -- if a project file is specified and no argument source
      is explicitly specified (either directly or by means of `-files'
      option), process the closure of units rooted at main_unit.
      Otherwise this option has no effect.

-Xname=value -- indicates that external variable name in
      the argument project has the value value. Has no effect if no
      project is specified as tool argument.

--incremental -- incremental processing on a per-file basis. Source files are
      only processed if they have been modified, or if files they depend
      on have been modified. This is similar to the way gnatmake/gprbuild
      only compiles files that need to be recompiled.

-jn -- In `--incremental' mode, use n gnat2xml
      processes to perform XML generation in parallel. If n is 0, then
      the maximum number of parallel tree creations is the number of core
      processors on the platform.

--output-dir=dir -- generate one .xml file for each Ada source file, in
      directory `dir'. (Default is to generate the XML to standard
      output.)

-I <include-dir>
    directories to search for dependencies
    You can also set the ADA_INCLUDE_PATH environment variable for this.

--compact -- debugging version, with interspersed source, and a more
      compact representation of "sloc". This version does not conform
      to any schema.

-files=filename - the name of a text file containing a list
                  of Ada source files to process

-q -- quiet
-v -- verbose

-cargs ... -- options to pass to gcc

If a project file is specified and no argument source is explicitly specified, and no `-U' is specified, then the set of processed sources is all the immediate units of the argument project.

Example:

 
gnat2xml -v -output-dir=xml-files *.ad[sb]

The above will create *.xml files in the `xml-files' subdirectory. For example, if there is an Ada package Mumble.Dumble, whose spec and body source code lives in mumble-dumble.ads and mumble-dumble.adb, the above will produce xml-files/mumble-dumble.ads.xml and xml-files/mumble-dumble.adb.xml.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15.2 Other Programs

The distribution includes two other programs that are related to gnat2xml:

gnat2xsd is the schema generator, which generates the schema to standard output, based on the structure of Ada as encoded by ASIS. You don't need to run gnat2xsd in order to use gnat2xml. To generate the schema, type:

 
gnat2xsd > ada-schema.xsd

gnat2xml generates XML files that will validate against `ada-schema.xsd'.

xml2gnat is a back-translator that translates the XML back into Ada source code. The Ada generated by xml2gnat has identical semantics to the original Ada code passed to gnat2xml. It is not textually identical, however -- for example, no attempt is made to preserve the original indentation.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

15.3 Structure of the XML

The primary documentation for the structure of the XML generated by gnat2xml is the schema (see gnat2xsd above). The following documentation gives additional details needed to understand the schema and therefore the XML.

The elements listed under Defining Occurrences, Usage Occurrences, and Other Elements represent the syntactic structure of the Ada program. Element names are given in lower case, with the corresponding element type Capitalized_Like_This. The element and element type names are derived directly from the ASIS enumeration type Flat_Element_Kinds, declared in Asis.Extensions.Flat_Kinds, with the leading "An_" or "A_" removed. For example, the ASIS enumeration literal An_Assignment_Statement corresponds to the XML element assignment_statement of XML type Assignment_Statement.

To understand the details of the schema and the corresponding XML, it is necessary to understand the ASIS standard, as well as the GNAT-specific extension to ASIS.

A defining occurrence is an identifier (or character literal or operator symbol) declared by a declaration. A usage occurrence is an identifier (or ...) that references such a declared entity. For example, in:

 
type T is range 1..10;
X, Y : constant T := 1;

The first "T" is the defining occurrence of a type. The "X" is the defining occurrence of a constant, as is the "Y", and the second "T" is a usage occurrence referring to the defining occurrence of T.

Each element has a 'sloc' (source location), and subelements for each syntactic subtree, reflecting the Ada grammar as implemented by ASIS. The types of subelements are as defined in the ASIS standard. For example, for the right-hand side of an assignment_statement we have the following comment in asis-statements.ads:

 
------------------------------------------------------------------------------
--  18.3  function Assignment_Expression
------------------------------------------------------------------------------

   function Assignment_Expression
     (Statement : Asis.Statement)
      return      Asis.Expression;

------------------------------------------------------------------------------
...
--  Returns the expression from the right hand side of the assignment.
...
--  Returns Element_Kinds:
--       An_Expression

The corresponding sub-element of type Assignment_Statement is:

 
<xsd:element name="assignment_expression_q" type="Expression_Class"/>

where Expression_Class is defined by an xsd:choice of all the various kinds of expression.

The 'sloc' of each element indicates the starting and ending line and column numbers. Column numbers are character counts; that is, a tab counts as 1, not as however many spaces it might expand to.

Subelements of type Element have names ending in "_q" (for ASIS "Query"), and those of type Element_List end in "_ql" ("Query returning List").

Some subelements are "Boolean". For example, Private_Type_Definition has has_abstract_q and has_limited_q, to indicate whether those keywords are present, as in type T is abstract limited private;. False is represented by a Nil_Element. True is represented by an element type specific to that query (for example, Abstract and Limited).

The root of the tree is a Compilation_Unit, with attributes:

Defining occurrences have these attributes:

Usage occurrences have these attributes:

In summary, def_name and ref_name are as in the source code of the declaration, possibly overloaded, whereas def and ref are unique-ified.

Literal elements have this attribute:

Elements that can syntactically represent names and expressions (which includes usage occurrences, plus function calls and so forth) have this attribute:

Pragma elements have this attribute:

Defining occurrences of formal parameters and generic formal objects have this attribute:

All elements other than Not_An_Element have this attribute:

The "kind" part of the "def" and "ref" attributes is taken from the ASIS enumeration type Flat_Declaration_Kinds, declared in Asis.Extensions.Flat_Kinds, with the leading "An_" or "A_" removed, and any trailing "_Declaration" or "_Specification" removed. Thus, the possible kinds are as follows:

 
ordinary_type
task_type
protected_type
incomplete_type
tagged_incomplete_type
private_type
private_extension
subtype
variable
constant
deferred_constant
single_task
single_protected
integer_number
real_number
enumeration_literal
discriminant
component
loop_parameter
generalized_iterator
element_iterator
procedure
function
parameter
procedure_body
function_body
return_variable
return_constant
null_procedure
expression_function
package
package_body
object_renaming
exception_renaming
package_renaming
procedure_renaming
function_renaming
generic_package_renaming
generic_procedure_renaming
generic_function_renaming
task_body
protected_body
entry
entry_body
entry_index
procedure_body_stub
function_body_stub
package_body_stub
task_body_stub
protected_body_stub
exception
choice_parameter
generic_procedure
generic_function
generic_package
package_instantiation
procedure_instantiation
function_instantiation
formal_object
formal_type
formal_incomplete_type
formal_procedure
formal_function
formal_package
formal_package_declaration_with_box


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by GNAT Mailserver on April, 17 2014 using texi2html