This is Info file asis_ug.info, produced by Makeinfo version 1.68 from the input file asis_ug.texi.  File: asis_ug.info, Node: Top, Next: About This Guide, Prev: (dir), Up: (dir) ASIS-for-GNAT User's Guide ************************** ASIS-for-GNAT User's Guide (C) Copyright 2000, Ada Core Technologies, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. ASIS-for-GNAT User's Guide * Menu: * About This Guide:: * Introduction:: * Getting Started:: * ASIS Overview:: * ASIS Context:: * ASIS Interpreter asistant:: * ASIS Application Templates:: * ASIS Tutorials:: * How to Build Efficient ASIS Applications:: * Processing an Ada Library by an ASIS-Based Tool:: * Compiling Binding and Linking Applications with ASIS-for-GNAT:: * ASIS-for-GNAT Warnings:: * File Naming Conventions and Applications Name Space:: -- The Detailed Node Listing -- About This Guide * What This Guide Contains:: * What You Should Know Before Reading This Guide:: * Related Information:: Introduction * What Is ASIS?:: * ASIS Scope What Kind of Tools Can Be Built with ASIS?:: Getting Started * The Problem:: * An ASIS Application Which Solves the Problem:: * Required Sequence of Calls:: * Building the Executable for an ASIS application:: * Generating Trees for Input:: * Running an ASIS Application:: ASIS Overview * Main ASIS Abstractions:: * ASIS Package Hierarchy:: * Structural and Semantic Queries:: * ASIS Error Handling Policy:: * Dynamic Validity Checking of the ASIS Queries:: * ASIS Iterator:: * How to Navigate through the Asis Specification:: ASIS Context * ASIS Context and Tree Files:: * Creating Tree Files for Use by ASIS:: * Creating Trees for Data Decomposition Annex:: * Different Ways to Define an ASIS Context in ASIS-for-GNAT:: * Consistency Problem:: * Inconsistent versions of ASIS and GNAT:: * Consistency of a set of tree and source files:: * Processing Several Contexts at a Time:: ASIS Interpreter `asistant' * asistant introduction:: * asistant commands:: * asistant variables:: * Browsing an ASIS tree:: * Example:: ASIS Application Templates ASIS Tutorials How to Build Efficient ASIS Applications * Tree Swapping as a Possible Cause of Poor Application Performance:: * Queries That Can Cause Tree Swapping:: * How to Avoid Unnecessary Tree Swapping:: * Using gnatmake to Create Tree Files:: Processing an Ada Library by an ASIS-Based Tool Compiling, Building and Linking Applications with ASIS-for-GNAT ASIS-for-GNAT Warnings File Naming Conventions and Application's Name Space  File: asis_ug.info, Node: About This Guide, Next: Introduction, Prev: Top, Up: Top About This Guide **************** This guide has two aims. The first one is to introduce you to the Ada Semantic Interface Specification (ASIS) and show you how you can build various useful tools on top of ASIS. The second is to describe the ASIS implementation for the GNAT Ada 95 compiler. * Menu: * What This Guide Contains:: * What You Should Know Before Reading This Guide:: * Related Information::  File: asis_ug.info, Node: What This Guide Contains, Next: What You Should Know Before Reading This Guide, Up: Top What This Guide Contains ======================== This guide contains the following chapters: * *Note Introduction::, contains the general definition of ASIS and gives some examples of tools which can be built on top of ASIS; * *Note Getting Started::, contains a short guided tour through the development and use of ASIS-for-GNAT-based tools; * *Note ASIS Overview:: gives the general overview of the ASIS definition to help an ASIS newcomer to navigate through ASIS (readers already familiar with ASIS can just skip this section); * *Note ASIS Context:: explains what is the meaning of ASIS Context in the case of ASIS-for-GNAT and what should be done to prepare a set of Ada components to be processed by an ASIS application; * *Note ASIS Application Templates:: describes a set of Ada source components provided by the ASIS-for-GNAT distribution that may be used as a basis for developing simple ASIS applications; * *Note ASIS Tutorials:: describes some examples included in the ASIS-for-GNAT distribution that comprise a hands-on tutorial to get some initial experience with ASIS; * *Note How to Build Efficient ASIS Applications:: describes the problem of tree swapping as a possible source of a poor productivity of ASIS applications and explains how to avoid unnecessary tree swappings; * *Note Processing an Ada Library by an ASIS-Based Tool:: touches the specific issues of processing Ada programs which use the pre-compiled Ada libraries by an ASIS tool; * *Note Compiling Binding and Linking Applications with ASIS-for-GNAT:: explains how to compile an ASIS application with ASIS-for-GNAT and how to create an executable for it; * *Note File Naming Conventions and Applications Name Space:: explains which names can and cannot be used as names of an ASIS application components.  File: asis_ug.info, Node: What You Should Know Before Reading This Guide, Next: Related Information, Prev: What This Guide Contains, Up: About This Guide What You Should Know Before Reading This Guide ============================================== This User's Guide assumes that you are familiar with Ada 95 and that you have some basic experience in Ada programming with GNAT. This User's Guide also assumes that you have ASIS-for-GNAT properly installed for your GNAT compiler, and that you are familiar with the structure of the ASIS-for-GNAT distribution (if not, see the top README file from the distribution, section 2) This guide does not assume that you have any knowledge or experience in ASIS. If you indeed do not, you will learn some basic things about ASIS when reading this Guide, doing exercises, playing with examples and referring to the ASIS definition if needed.  File: asis_ug.info, Node: Related Information, Prev: What You Should Know Before Reading This Guide, Up: About This Guide Related Information =================== To get to know more about GNAT, refer to the GNAT User's Guide. Refer to ASIS-for-GNAT Installation Guide to learn how to install the ASIS implementation for your GNAT compiler. The ASIS 95 definition now exists as ISO/IEC International Standard 15291. To get more information about ASIS, visit the ASIS Working Group Web Pages (http://www.acm.org/sigada/wg/asiswg). To read this Guide you will hardly need GNAT or ASIS-for-GNAT Reference Manual.  File: asis_ug.info, Node: Introduction, Next: Getting Started, Prev: About This Guide, Up: Top Introduction ************ * Menu: * What Is ASIS?:: * ASIS Scope What Kind of Tools Can Be Built with ASIS?::  File: asis_ug.info, Node: What Is ASIS?, Next: ASIS Scope What Kind of Tools Can Be Built with ASIS?, Up: Introduction What Is ASIS? ============= The Ada Semantic Interface Specification (ASIS) is an interface between an Ada environment (as defined by ISO/IEC 8652:1995) and any tool requiring information from it. An Ada environment includes valuable semantic and syntactic information. ASIS is an open and published callable interface which gives CASE tool and application developers access to this information. ASIS has been designed to be independent of underlying Ada environment implementations, thus supporting portability of software engineering tools while relieving tool developers from needing to understand the complexities of an Ada environment's proprietary internal representation. Technically, ASIS is a hierarchy of the Ada package specifications. These packages define a set of Ada private types which implement basic notions needed to describe an Ada program. Operations for these types, called ASIS queries, give you statically determinable information about Ada compilation units in your environment. You may use ASIS as a third-part Ada library to implement a number of useful program analysis tools.  File: asis_ug.info, Node: ASIS Scope What Kind of Tools Can Be Built with ASIS?, Prev: What Is ASIS?, Up: Introduction ASIS Scope: What Kind of Tools Can Be Built with ASIS? ====================================================== The following ASIS properties define the ASIS scope: bullet ASIS is a read-only interface; bullet ASIS provides only statically-determinable information about Ada programs; bullet ASIS provides all the syntax and the basic semantic information from/about Ada programs. If some semantic property of a program cannot be directly queried by means of ASIS queries, an ASIS application can compute the needed piece of information itself from the information available through ASIS queries; bullet Even though containing some implementation dependencies, ASIS provides information from/about Ada program in high-level terms which are well-conformed with RM 95 and which are Ada/ASIS-implementation-independent in their very nature. Examples of tools that benefit from the ASIS interface include, but are not limited by: automated code monitors, browsers, call tree tools, code reformators, coding standards compliance tools, correctness verifiers, debuggers, dependency tree analysis tools, design tools, document generators, metrics tools, quality assessment tools, reverse engineering tools, re-engineering tools, style checkers, test tools, timing estimators, and translators.  File: asis_ug.info, Node: Getting Started, Next: ASIS Overview, Prev: Introduction, Up: Top Getting Started *************** In this section we go through the ASIS application development and usage cycle in a very simplified way: we take a sample problem to be solved with an ASIS application, then we present the code of the ASIS application which gives the solution for our problem, then we show how to compile it and build the executable for it with ASIS-for-GNAT and how to prepare an ASIS Context to be processed by the program, and finally we show the output produced by our program when it is applied to itself. * Menu: * The Problem:: * An ASIS Application Which Solves the Problem:: * Required Sequence of Calls:: * Building the Executable for an ASIS application:: * Generating Trees for Input:: * Running an ASIS Application::  File: asis_ug.info, Node: The Problem, Next: An ASIS Application Which Solves the Problem, Up: Getting Started The Problem =========== Suppose our goal is to process some set of Ada compilation units, and for every unit to print its full expanded Ada name, whether this unit is a spec, a body or a subunit, and whether this unit is a user-defined unit, a predefined unit as defined by RM 95 or an implementation-specific unit (such as a part of a Run-Time Library).  File: asis_ug.info, Node: An ASIS Application Which Solves the Problem, Next: Required Sequence of Calls, Prev: The Problem, Up: Getting Started An ASIS Application Which Solves the Problem ============================================ with Ada.Wide_Text_IO; use Ada.Wide_Text_IO; with Ada.Characters.Handling; use Ada.Characters.Handling; -- ASIS-specific context clauses: with Asis; with Asis.Implementation; with Asis.Ada_Environments; with Asis.Compilation_Units; with Asis.Exceptions; with Asis.Errors; procedure Example1 is My_Context : Asis.Context; -- ASIS Context is an abstraction of an Ada environment, it -- defines a set of ASIS Compilation Units available through -- ASIS queries begin -- first, by initializing an ASIS implementation, we make it -- ready for work Asis.Implementation.Initialize; -- then we define our Context by making association with -- "physical" environment: Asis.Ada_Environments.Associate (My_Context, "My Asis Context", "-CA"); -- See ASIS-for-GNAT Reference Manual for the description of the -- parameters of the Associate query, see also chapter -- "ASIS Context" for the description of different kinds of -- ASIS Context in case of ASIS-for-GNAT -- by opening a Context we make it ready for processing by ASIS -- queries Asis.Ada_Environments.Open (My_Context); Processing_Units: declare Next_Unit : Asis.Compilation_Unit; -- ASIS Compilation_Unit is the abstraction to represent Ada -- compilation units as described in RM 95 All_Units : Asis.Compilation_Unit_List := -- ASIS list are one-dimensional unconstrained arrays. -- Therefore, when declaring an object of an ASIS list type, -- we have to provide either a constraint or explicit -- initialization expression: Asis.Compilation_Units.Compilation_Units (My_Context); -- Compilation_Units query gives you a list of all the units -- contained in an ASIS Context begin Put_Line ("A Context contains the following compilation units:"); New_Line; for I in All_Units'Range loop Next_Unit := All_Units (I); Put (" "); -- to get a unit name, we just need a Unit_Full_Name -- query. ASIS uses Wide_String as a string type, -- therefore we convert the result into String to use -- Ada.Text_IO Put (Asis.Compilation_Units.Unit_Full_Name (Next_Unit)); -- to get more info about a unit, we ask about its class -- and about its origin case Asis.Compilation_Units.Unit_Kind (Next_Unit) is when Asis.A_Library_Unit_Body => Put (" (body)"); when Asis.A_Subunit => Put (" (subunit)"); when others => Put (" (spec)"); end case; case Asis.Compilation_Units.Unit_Origin (Next_Unit) is when Asis.An_Application_Unit => Put_Line (" - user-defined unit"); when Asis.An_Implementation_Unit => Put_Line (" - implementation-specific unit"); when Asis.A_Predefined_Unit => Put_Line (" - Ada predefined unit"); when Asis.Not_An_Origin => Put_Line (" - unit does not actually exist in a Context"); end case; end loop; end Processing_Units; -- Cleaning up: we have to close out Context, to break its -- association with the external environment and to finalize -- our ASIS implementation to release all the resources used: Asis.Ada_Environments.Close (My_Context); Asis.Ada_Environments.Dissociate (My_Context); Asis.Implementation.Finalize; exception when Asis.Exceptions.ASIS_Inappropriate_Context | Asis.Exceptions.ASIS_Inappropriate_Compilation_Unit | Asis.Exceptions.ASIS_Failed => -- we check not for all the ASIS-defined exceptions, but only -- those of them which can actually be raised in our ASIS -- application. -- -- If an ASIS exception is raised, we output the ASIS error -- status and the ASIS diagnosis string: Put_Line ("ASIS exception is raised:"); Put_Line ("ASIS diagnosis is:"); Put_Line (Asis.Implementation.Diagnosis); Put ("ASIS error status is: "); Put_Line (Asis.Errors.Error_Kinds'Wide_Image (Asis.Implementation.Status)); end Example1;  File: asis_ug.info, Node: Required Sequence of Calls, Next: Building the Executable for an ASIS application, Prev: An ASIS Application Which Solves the Problem, Up: Getting Started Required Sequence of Calls ========================== An ASIS application must use the following sequence of calls: 1. `Asis.Implementation.Initialize (...);' This call initializes the ASIS implementation internal data structures and prepares the ASIS implementation for work. For most of the ASIS queries, it is erroneous to call them if an ASIS implementation is not initialized. 2. `Asis.Ada_Environments.Associate (...);' This call is the only means to define a value of a variable of the ASIS limited private type Context. This value is some specific association of the ASIS Context with the "external world". The way of making this association and the meaning of the corresponding parameters of the Associate query are implementation-specific, but as soon as this association has been made and a Context variable is opened, the ASIS Context designated by this variable may be considered to be a set of ASIS Compilation Units available through the ASIS queries. 3. `Asis.Ada_Environments.Open (...);' Opening an ASIS Context variable makes the corresponding Context accessible for all ASIS queries. After opening the Context, an ASIS application can start obtaining ASIS Compilation Units from it, further analyze Compilation Units by decomposing them into ASIS Elements etc. ASIS relies on the content of a Context being frozen as long as the Context remains open. It is erroneous to change through some non-ASIS program any data structures used by an ASIS implementation to define and implement this Context while the Context is open. 4. `Asis.Ada_Environments.Close (...);' After closing the Context it is impossible to retrieve any information from it. All the values of the ASIS objects of Compilation_Unit, Element and Line types obtained when this Context was open become obsolete, and it is erroneous to use them after the Context was closed. The content of this Context need not be frozen while the Context remains closed. Note that a closed Context keeps its association with the "external world" and it may be opened again with the same association. Note also that the content (that is, the corresponding set of ASIS Compilation Units) of the Context may be different from what was in the Context before, because the "external world" may have changed while the Context remained closed. 5. `Asis.Ada_Environments.Dissociate (...);' This query breaks the association between the corresponding ASIS Context and the "external world", and the corresponding Context variable becomes undefined. 6. `Asis.Implementation.Finalize (...);' This releases all the resources used by an ASIS implementation. An application can perform these steps in a loop. It may initialize and finalize an ASIS implementation several times, it may associate and dissociate the same Context several times while an ASIS implementation remains initialized, and it may open and close the same Context several times while the Context keeps its association with the "external world". An application can have several ASIS Contexts opened at a time (the upper limit is implementation-specific), and for each open Context, an application can process several Compilation Units obtained from this Context at a time (the upper limit is also implementation-specific). ASIS-for-GNAT does not impose any special limitations on the number of ASIS Contexts and on the number of the ASIS Compilation Units processed at a time, as long as an ASIS application is within the general resource limitations of the underlying system.  File: asis_ug.info, Node: Building the Executable for an ASIS application, Next: Generating Trees for Input, Prev: Required Sequence of Calls, Up: Getting Started Building the Executable for an ASIS application =============================================== The rest of this section assumes that you have ASIS-for-GNAT properly installed as an Ada library. To get the executable for the ASIS application from subsection 1.2 (assuming that it is located in your current directory as the Ada source file named example1.adb), you have to call gnatmake as: `gnatmake example1[.adb] -largs -lasis' For more details concerning compiling ASIS applications and building executables for them with ASIS-for-GNAT see chapter *Note Compiling Binding and Linking Applications with ASIS-for-GNAT::.  File: asis_ug.info, Node: Generating Trees for Input, Next: Running an ASIS Application, Prev: Building the Executable for an ASIS application, Up: Getting Started Generating Trees for Input ========================== To get information from an Ada environment being processed, ASIS-for-GNAT processes so-called tree files. A tree file is generated by GNAT, and it contains a snapshot of a compiler's internal data structures. For more details see section *Note ASIS Context and Tree Files:: of this Guide To create a tree file for a unit contained in some source file, you should compile this file with '-gnatc -gnatt' compiler options. If we want to apply the application described in section *Note An ASIS Application Which Solves the Problem:: to itself, we have to compile the source of this application with a command `gcc -c -gnatc -gnatt example1.adb' and as a result, we will get the tree file named example1.adt in the current directory. For more explanation how to generate and how to deal with tree files see chapters *Note ASIS Context:: and *Note ASIS Tutorials::.  File: asis_ug.info, Node: Running an ASIS Application, Prev: Generating Trees for Input, Up: Getting Started Running an ASIS Application =========================== To complete our example, let's execute our ASIS application. If you have followed all the steps described in chapter *Note Getting Started::, now you should have in your current directory the executable `example1' and the tree file `example1.atd'. (Note that a tree file contains information about a unit it was created for and about all the units upon which this unit depends semantically). If we run our application, it will process an ASIS Context defined by one tree file `example1.adt' (for more details about defining an ASIS context see chapter *Note ASIS Context:: ASIS-for-GNAT Reference Manual). The result will be: A Context contains the following compilation units: Standard (spec) - Ada predefined unit Example1 (body) - user-defined unit Ada.Text_IO (spec) - Ada predefined unit Ada (spec) - Ada predefined unit Ada.IO_Exceptions (spec) - Ada predefined unit Ada.Streams (spec) - Ada predefined unit System (spec) - Ada predefined unit System.File_Control_Block (spec) - Ada predefined unit System.Parameters (spec) - Ada predefined unit Ada.Characters.Handling (spec) - Ada predefined unit Ada.Characters (spec) - Ada predefined unit Asis (spec) - user-defined unit A4G.A_Types (spec) - user-defined unit A4G (spec) - user-defined unit Ada.Characters.Latin_1 (spec) - Ada predefined unit A4G.Int_Knds (spec) - user-defined unit Types (spec) - user-defined unit Unchecked_Deallocation (spec) - Ada predefined unit Asis.Implementation (spec) - user-defined unit Asis.Errors (spec) - user-defined unit Asis.Ada_Environments (spec) - user-defined unit Asis.Compilation_Units (spec) - user-defined unit Asis.Ada_Environments.Containers (spec) - user-defined unit Asis.Exceptions (spec) - user-defined unit In the current implementation, ASIS implementation components are considered user-defined, not implementation-specific, units. Note also, that some components of the GNAT Run-Time Library may be implicitly "withed" by some Ada units, and therefore they may be presented by a tree file, that is why you can see System.File_Control_Block in the list above.  File: asis_ug.info, Node: ASIS Overview, Next: ASIS Context, Prev: Getting Started, Up: Top ASIS Overview ************* This chapter contains a short overview of the ASIS definition as given in the ISO/IEC 15291:1999 ASIS Standard. This overview is aimed at helping an ASIS newcomer to find needed information in the ASIS definition and to navigate himself in it. For more details look into the ASIS definition itself. To get some initial experience with ASIS, go through the ASIS Tutorials (see *Note ASIS Tutorials::). * Menu: * Main ASIS Abstractions:: * ASIS Package Hierarchy:: * Structural and Semantic Queries:: * ASIS Error Handling Policy:: * Dynamic Validity Checking of the ASIS Queries:: * ASIS Iterator:: * How to Navigate through the Asis Specification::  File: asis_ug.info, Node: Main ASIS Abstractions, Next: ASIS Package Hierarchy, Up: ASIS Overview Main ASIS Abstractions ====================== ASIS is based on the three main abstractions used to describe Ada programs: Context an ASIS Context is a logical handle to an Ada environment, as defined in RM 95 Chapter 10. To avoid the language-lawyer difficulties when trying to understand the formal relation between an ASIS Context and an Ada environment, an ASIS application developer may view an ASIS Context as a way to define a set of compilation units available through the ASIS queries. Compilation Unit an ASIS Compilation Unit is a logical handle to an Ada compilation unit. It reflects practically one-to-one all the properties of compilation units defined by RM 95, and it also reflects some properties of "physical objects" treated by an underlying Ada implementation as compilation units (such as time of last update, the name of some object treated as containing the source text for a unit). An ASIS Compilation Unit provides the black-box view of a compilation unit, considering a unit as a whole. It may be decomposed and analyzed as a white-box by means of ASIS Elements. Element an ASIS Element is a logical handle to syntax components of ASIS Compilation Units (both explicit and implicit). Some ASIS components use additional abstractions needed for specific pieces of functionality provided by these components: Container an ASIS Container (defined and used by the Asis.Ada_Environments.Containers package) provides means for structuring the content of an ASIS Context by grouping ASIS Compilation units into Containers. Line an ASIS Line (defined and used by the Asis.Text package) is the abstraction of a line in an Ada source text. An ASIS Line has a length, a string image and a number. Span an ASIS Span (defined and used by the Asis.Text package) defines the location of an Element, a Compilation Unit or a whole compilation in the corresponding source text. Id An ASIS Id (defined and used by the Asis.Ids package) provides a way to store some "image" of an ASIS Element outside an ASIS application. An application may create an Id value from an Element value and store it in a file. After that, the same or another application may read this Id value in and try to convert it back into the corresponding Element value.  File: asis_ug.info, Node: ASIS Package Hierarchy, Next: Structural and Semantic Queries, Prev: Main ASIS Abstractions, Up: ASIS Overview ASIS Package Hierarchy ====================== ASIS is defined as a hierarchy of Ada package specifications. Below is the short description of this hierarchy. Asis - this is the top package of the hierarchy. It defines the main ASIS abstractions - Context, Compilation_Unit and Element - as Ada private types. It also contains a set of enumeration types that define the classification hierarchy for ASIS Elements (which closely reflects the Ada syntax defined in RM 95) and classification of ASIS Compilation Units. This package does not contain any queries; Asis.Implementation - contains subprograms that control an ASIS implementation: initializing and finalizing it, retrieving and resetting the diagnosis information. Its child package Asis.Implementation.Permissions contains boolean queries which tells you how ASIS implementation-specific features are implemented in your ASIS implementation; Asis.Ada_Environments - contains queries that deal with an ASIS Context: associating and dissociating, opening and closing a Context; Asis.Compilation_Units - contains queries that work with ASIS Compilation Units: obtaining units from a Context, getting semantic dependencies between Units and black-box Unit properties; Asis.Compilation_Units.Relations - contains queries that return integrated semantic dependencies among ASIS Compilation Units, e.g. all the Units needed by a given Unit to be included in a partition; Asis.Elements - contains queries working on Elements and implementing general Element properties: gateway queries from ASIS Compilation Units to ASIS Elements, queries defining the position of an Element in the Element classification hierarchy, queries which define for a given Element its Enclosing Compilation Unit and its Enclosing Element. It also contains queries that work on pragmas; Asis.Declarations, Asis.Definitions, Asis.Statements, Asis.Expressions and ASIS.Clauses - each of these packages contains queries working on Elements of the corresponding kind - that is, representing Ada declarations, definitions, statements, expressions and clauses respectively; Asis.Text - contains queries returning information about the source representation of ASIS Compilation Units and ASIS Elements; Asis.Exceptions - defines ASIS exceptions; Asis.Errors - defines possible ASIS error statuses.  File: asis_ug.info, Node: Structural and Semantic Queries, Next: ASIS Error Handling Policy, Prev: ASIS Package Hierarchy, Up: ASIS Overview Structural and Semantic Queries =============================== Queries working on Elements and returning Elements or Element Lists are divided into structural and semantic queries. Each structural query (except Enclosing_Element) implements one step of the parent-to-child decomposition of an Ada program according to the ASIS Element classification hierarchy. Asis.Elements.Enclosing_Element query implements the reverse child-to-parent step. (For implicit Elements obtained as results of semantic queries, Enclosing Element may not correspond to what could be expected from the Ada syntax and semantics as defined in RM 95, in this case the documentation of a semantic query also defines the effect of Enclosing_Element applied to its result). A semantic query for a given Element returns the Element representing some semantic property of the first - e.g. type declaration for an expression as expression's type, a defining identifier as a definition for a simple name etc. For example, if we have Element El representing an assignment statement: X := A + B; then we can get the structural components of this assignment statements by applying the appropriate structural queries: El_Var := Asis.Statements.Assignment_Variable_Name (El); -- X El_Expr := Asis.Statements.Assignment_Expression (El); -- A + B And then we can analyze semantic properties of the variable name represented by El_Var and of the expression represented by El_Expr by means of appropriate semantic queries: El_Var_Def := Asis.Expressions.Corresponding_Name_Definition (El_Var); El_Expt_Type := Asis.Expressions.Corresponding_Expression_Type (El_Expr); As the result, El_Var_Def will be of A_Defining_Identifier kind and will represent the defining occurrence of X, while El_Expt_Type of a kind An_Ordinary_Type_Declaration will represent the declaration of the type of the expression A + B. If we apply Asis.Elements.Enclosing_Element to El_Var or to El_Expr, we will get back to the Element representing the assignment statement. An important thing about classifying queries working on Elements as structural and semantic is that all the structural queries cannot go outside one ASIS Compilation Unit, but for semantic queries it is quite usual that the argument of a query is in one ASIS Compilation Unit, but the result of this query is in another ASIS Compilation Unit.  File: asis_ug.info, Node: ASIS Error Handling Policy, Next: Dynamic Validity Checking of the ASIS Queries, Prev: Structural and Semantic Queries, Up: ASIS Overview ASIS Error Handling Policy ========================== Only ASIS-defined exceptions (and the Ada predefined Storage_Error exception) are allowed to propagate outside the ASIS queries. ASIS exceptions are defined in the Asis.Exceptions package. When an ASIS exception is raised, ASIS sets the Error Status (the possible ASIS error conditions are defined as the values of the Asis.Errors.Error_Kinds type) and forms the Diagnosis string. An application can query the current value of the ASIS Error Status by Asis.Implementation.Status query, and the current content of the Diagnosis string by Asis.Implementation.Diagnosis query. An application can reset the Error Status and Diagnosis by Asis.Implementation.Set_Status procedure.  File: asis_ug.info, Node: Dynamic Validity Checking of the ASIS Queries, Next: ASIS Iterator, Prev: ASIS Error Handling Policy, Up: ASIS Overview Dynamic Validity Checking of the ASIS Queries ============================================= ASIS has just one type (Element) for all kinds of Ada syntax constructs, and just one type (Compilation_Unit) for all kinds of Ada compilation units. However, many of the queries working on Elements and Compilation Units can be applied only to specific kinds of Elements and Compilation units respectively. (For example, it does not make sense and is illegal to query Assignment_Variable_Name for an Element of An_Ordinary_Type_Declaration kind). ASIS is a dynamic validity checking interface. If a query working on Elements has a list of appropriate Element kinds in its documentation, this means that this query can work only on Elements of the kinds from this list. Such a query should raise Asis.Exceptions.ASIS_Inappropriate_Element exception with Asis.Errors.Value_Error error status set when called for any Element with a kind not from the list of the appropriate Element kinds. If a query working on Compilation Units has a list of appropriate unit kinds in its documentation, then this query can work only on Compilation Units of the kinds from this list. Such a query should raise Asis.Exceptions.ASIS_Inappropriate_Compilation_Unit with Asis.Errors.Value_Error error status set when called for any Compilation_Unit with a kind not from the list of the appropriate unit kinds. If a query has a list of expected Element kinds or expected Compilation Unit kinds in its documentation, this query does not raise any exception when called with any argument, but it produces a meaningful result only when called with an argument with the kind from this list. For example, if Asis.Elements.Statement_Kind query is called for an argument of A_Declaration kind, it just returns Not_A_Statement, but without raising any exception.  File: asis_ug.info, Node: ASIS Iterator, Next: How to Navigate through the Asis Specification, Prev: Dynamic Validity Checking of the ASIS Queries, Up: ASIS Overview ASIS Iterator ============= ASIS provides a powerful mechanism to traverse an Ada code, the generic procedure Asis.Iterator.Traverse_Element. This procedure makes top-down left-to-right (or depth-first) traversal of the ASIS tree (that is, of the syntax structure of the Ada code represented by the hierarchy of ASIS Elements). In the course of this traversal, it applies to each Element the formal Pre_Operation procedure when visiting this element for the first time, and the formal Post_Operation procedure when leaving this Element. By providing his own instantiations for Pre_- and Post_Operation, the user gains the ability to automatically process all ASIS Elements found in a given ASIS tree. For example, suppose we have an assignment statement: X := F (Y); When called for an Element representing this statement, a Traverse_Element instantiation does the following (below Pre_Op and Post_Op stand for actual procedures provided for formal Pre_Operation and Post_Operation, and numbers indicate the sequence of calls to Pre_Op and Post_Op during traversal): (1 Pre_Op) X := F (Y) (10 Post_Op) | | ----------------------------------- | | (2 Pre_Op) X (3 Post_Op) | | (4 Pre_Op) F(Y) (9 Post_Op) | | --------------------------- | | (5 Pre_Op) F (6 Post_Op) (7 Pre_Op) Y (8 Post_Op) To see in more detail how Traverse_Element may be used for fast-and-easy development of a number of useful ASiS applications, see ASIS tutorials provided as a part of ASIS-for-GNAT distribution (Section 4).  File: asis_ug.info, Node: How to Navigate through the Asis Specification, Prev: ASIS Iterator, Up: ASIS Overview How to Navigate through the Asis Specification ============================================== The following hints and tips may be useful when looking for some specific information in the ASIS definition: 1. Use the short overview of the ASIS packages given in section *Note ASIS Package Hierarchy:: to limit your browsing to a smaller set of ASIS packages (e.g. if you are interested in what can be done with Compilation_Units - look only in Asis.Compilation_Units, if you are looking for queries which can be used to decompose and analyze declarations, limit your search to Asis.Declarations). 2. Inside Asis packages working with particular kinds of Elements (Asis.Declarations, Asis.Definitions, Asis.Statements, Asis.Expressions and ASIS.Clauses) queries are ordered according to the order of the description of the corresponding constructions in RM 95 (e.g., package Asis.Statements starts from a query retrieving labels and ends with the query decomposing a code statement). 3. The names of all the semantic queries (and only ones) start from Corresponding_... or Implicit_... 4. Use comment sentinels given in the specification of the ASIS packages. A sentinel of the form "-|ER" (from "Element Reference") introduces a new element kind, and it is followed by a group of sentinels of the form "-|CR" (from "Child Reference") which list queries yielding the child Elements for the Element just introduced.  File: asis_ug.info, Node: ASIS Context, Next: ASIS Interpreter asistant, Prev: ASIS Overview, Up: Top ASIS Context ************ * Menu: * ASIS Context and Tree Files:: * Creating Tree Files for Use by ASIS:: * Different Ways to Define an ASIS Context in ASIS-for-GNAT:: * Consistency Problem:: * Processing Several Contexts at a Time::  File: asis_ug.info, Node: ASIS Context and Tree Files, Next: Creating Tree Files for Use by ASIS, Up: ASIS Context ASIS Context and Tree Files =========================== From an ASIS application viewpoint we may view an ASIS Context as a set of ASIS Compilation Units accessible through the ASIS queries. The common ASIS implementation technique is to base an implementation of an ASIS Context on some persistent data structures created by the underlying Ada compiler when compiling Ada compilation units maintained by this compiler. An ASIS Context can only contain compilable (that is, legal) compilation units. In case of ASIS-for-GNAT, an ASIS implementation is based on tree output files, or, simply, tree files. When called with the special option (-gnatt), GNAT creates and outputs a tree file in case if no error was detected during the compilation. The tree file is a kind of the snapshot of the compiler internal data structures (basically, of the Abstract Syntax Tree (AST)) in the very end of the successful compilation. ASIS then inputs tree files and recreates in its internal data structures just the same picture as the compiler had in the end of the corresponding successful compilation. An important consequence of the GNAT source-based compilation model is that AST contains full information not only about the unit being compiled, but also about all the units upon which this unit depends semantically. Therefore, having read a tree file, ASIS can in general provide information about more than one unit. By processing a tree file information can be provided about the unit for which this tree was created and about all the units upon which it depends semantically. However, to process several units, ASIS sometimes has to change the tree being processed (in particular, it is the case when an application switches between units which do not semantically depend on each other). Therefore, in the course of an ASIS application, ASIS may read different tree files and it may read the same tree file more then once. The name of a tree file is obtained from the name of the source file being compiled by replacing its suffix with '`.adt''. For example, the tree file for `foo.adb' is named `foo.adt'.  File: asis_ug.info, Node: Creating Tree Files for Use by ASIS, Next: Different Ways to Define an ASIS Context in ASIS-for-GNAT, Prev: ASIS Context and Tree Files, Up: ASIS Context Creating Tree Files for Use by ASIS =================================== * Menu: * Creating Trees for Data Decomposition Annex:: Neither GNAT nor `gnatmake' will create tree files automatically when you are working with your Ada program. It is the responsibility of a user of an ASIS application to create a set of tree files which would correctly reflect the set of the Ada components to be processed by ASIS/ASIS applications, as well as to maintain the consistency of the trees and the related source files. To create a tree file for a certain source file, the corresponding source file must be compiled with -gnatc -gnatt flags: gcc -c -gnatc -gnatt foo.adb will produce foo.adt, provided that foo.adb contains the source of a legal Ada compilation unit. -gnatt generates a tree file, and -gnatc turns off tree expansion. ASIS needs tree files created without tree expansion, whereas to create an object file, GNAT needs expanded AST. Therefore it is impossible to produce tree files together with producing object files. The following things are important to remember when generating and dealing with tree files: 1. ASIS-for-GNAT is distributed for a particular version of GNAT. All the trees to be processed by an ASIS application should be generated by this specific version of the compiler. 2. When creating a tree file for ASIS, use two options -gnatc and -gnatt separately, do not combine them into a single -gnatct or -gnattc option or it will result in a generation of a bogus object file. 3. The tree file is not created if an error has been detected during the compilation. 4. Opposite to object files, a tree file may be generated for any legal Ada compilation unit, including a library package declaration requiring a body and a subunit. 5. A set of tree files processed by ASIS (ASIS application) may be inconsistent, for example two tree files may have been created with the different versions of the source of the same unit. This will lead to inconsistencies in the corresponding ASIS Context. See section *Note Consistency Problem:: for more details. 6. Do not move tree, object and source files among directories in the underlying file system! It may confuse ASIS, and it may detect inconsistency between tree and source files when opening a Context or you may get wrong results when asking about the source or object file for a given ASIS Compilation Unit. 7. When calling `gcc' or `gnatmake' to create tree files, all file and directory names containing relative path information should start from "./" or "../" (".\" and "..\" respectively in Windows NT/95). That is, to create a tree file for the source file `foo.adb' located in the inner directory named "inner", you should call gcc as: >gcc -c -gnatc -gnatt .\inner\foo.adb but not as >gcc -c -gnatc -gnatt inner\foo.ads otherwise ASIS will get confused. 8. When reading in a tree file, ASIS checks that this tree file was created with '-gnatc' option, and it does not accept trees created without '-gnatc'. 9. Tree and ALI files. If called to create a tree, GNAT does not destroy an ALI file if the ALI file already exists for the unit being compiled and if this ALI file is up-to-date. Moreover, GNAT may use some information from the existing ALI file to put it into the tree file. So if you would like to have both object and tree files for your program, first create object files and then - tree files. 10. There is only one extension for tree files - .adt, whereas the standard GNAT name convention for the Ada source files uses two different extensions for a spec (.ads) and for a body (.adb). This means that if you first compile the body for the tree: >gcc -c -gnatc -gnatt foo.adb and then - compile the corresponding spec for the tree: >gcc -c -gnatc -gnatt foo.ads then the tree file `foo.adt' will be created twice - first for the body, and then - for the spec, the tree for the spec will override the tree for the body, and the information about the body will be lost for ASIS. If you first create the tree for a spec, and then for a body, the second tree will also override the first one, but no information will be lost for ASIS, because the tree for a body contains full information about the corresponding spec. To avoid losing information when creating trees for a set of Ada sources, use the following rules: - if a set of Ada components to process makes up a complete partition, use `gnatmake' (see section *Note Using gnatmake to Create Tree Files:: for more details); - otherwise first create trees for specs, and then - for bodies: >gcc -c -gnatc -gnatt *.ads >gcc -c -gnatc -gnatt *.adb 11. Reading tree files is a time-consuming operation. Try to minimize the number of tree files to be processed by your application and to avoid unnecessary tree swappings. (See chapter *Note How to Build Efficient ASIS Applications:: for some tips). Note that between opening and closing a Context, an ASIS application should not change its working directory (or restore it before making an ASIS call), otherwise application behavior may be erroneous.  File: asis_ug.info, Node: Creating Trees for Data Decomposition Annex, Up: Creating Tree Files for Use by ASIS Creating Trees for Data Decomposition Annex ------------------------------------------- Using the ASIS Data Decomposition Annex (DDA) does not require anything special to be done by an ASIS user, except one thing. The implementation of the ASIS DDA is based on some special annotation added by the compiler to the trees used by ASIS. An ASIS user should be aware of the fact, that trees created for subunits does not have this special annotation, therefore ASIS DDA queries do not work correctly on trees created for subunits (and these queries may not work correctly if a set of tree files making up a Context contain a tree created for a subunit). So, when working with ASIS DDA, a user should avoid creating separate trees for subunits. Actually, it is not a limitation - to create a tree for a subunit, a user should also have the source of the parent body around. If in this situation a user creates the tree for the parent body, it will contain the full information (including DDA-specific annotation) for all the subunits which are around. From the other side, a tree created for a single subunit has to contain information about the parent body, so it is about of the same size as the tree for the parent body. The best way to create trees when using ASIS DDA is to use gnatmake - it will never create separate trees for subunits.