GNAT GPL User's Guide: The Ada-to-XML converter gnat2xml

[ < ] | [ > ] |  | [ << ] | [ 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:

- unit_kind, unit_class, and unit_origin. These are strings that match the enumeration literals of types Unit_Kinds, Unit_Classes, and Unit_Origins in package Asis.

- unit_full_name is the full expanded name of the unit, starting from a root library unit. So for `package P.Q.R is ...`, `unit_full_name="P.Q.R"`. Same for `separate (P.Q) package R is ...`.

- def_name is the same as unit_full_name for library units; for subunits, it is just the simple name.

- source_file is the name of the Ada source file. For example, for the spec of `P.Q.R`, `source_file="p-q-r.ads"`. This allows one to interpret the source locations -- the "sloc" of all elements within this Compilation_Unit refers to line and column numbers within the named file.

Defining occurrences have these attributes:

- def_name is the simple name of the declared entity, as written in the Ada source code.

- def is a unique URI of the form:

  ada://kind/fully/qualified/name

  where:

  kind indicates the kind of Ada entity being declared (see below), and

  fully/qualified/name, is the fully qualified name of the Ada entity, with each of "fully", "qualified", and "name" being mangled for uniqueness. We do not document the mangling algorithm, which is subject to change; we just guarantee that the names are unique in the face of overloading.

- type is the type of the declared object, or `null` for declarations of things other than objects.

Usage occurrences have these attributes:

- ref_name is the same as the def_name of the corresponding defining occurrence. This attribute is not of much use, because of overloading; use ref for lookups, instead.

- ref is the same as the def of the corresponding defining occurrence.

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:

- lit_val is the value of the literal as written in the source text, appropriately escaped (e.g. `"` ---> `&quot;`). This applies only to numeric and string literals. Enumeration literals in Ada are not really "literals" in the usual sense; they are usage occurrences, and have ref_name and ref as described above. Note also that string literals used as operator symbols are treated as defining or usage occurrences, not as literals.

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

- type. If the element represents an expression or the name of an object, 'type' is the 'def' for the defining occurrence of the type of that expression or name. Names of other kinds of entities, such as package names and type names, do not have a type in Ada; these have type="null" in the XML.

Pragma elements have this attribute:

- pragma_name is the name of the pragma. For language-defined pragmas, the pragma name is redundant with the element kind (for example, an assert_pragma element necessarily has pragma_name="Assert"). However, all implementation-defined pragmas are lumped together in ASIS as a single element kind (for example, the GNAT-specific pragma Unreferenced is represented by an implementation_defined_pragma element with pragma_name="Unreferenced").

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

- mode indicates that the parameter is of mode 'in', 'in out', or 'out'.

All elements other than Not_An_Element have this attribute:

- checks is a comma-separated list of run-time checks that are needed for that element. The possible checks are: do_accessibility_check, do_discriminant_check,do_division_check,do_length_check, do_overflow_check,do_range_check,do_storage_check,do_tag_check.

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