[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
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 |
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] | [ ? ] |
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] | [ ? ] |
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:
package P.Q.R is ...
,
unit_full_name="P.Q.R"
. Same for separate (P.Q) package R is ...
.
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:
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.
null
for
declarations of things other than objects.
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:
"
---> "
). 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:
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] | [ ? ] |