File : asis-ids.ads
------------------------------------------------------------------------------
-- --
-- ASIS-for-GNAT IMPLEMENTATION COMPONENTS --
-- --
-- A S I S . I D S --
-- --
-- S p e c --
-- --
-- --
-- This specification is adapted from the Ada Semantic Interface --
-- Specification (ASIS) definition, ISO/IEC 15291, Working Draft. In --
-- accordance with the (expected) copyright of the ASIS definition, you can --
-- freely copy and modify this specification, provided that if you --
-- redistribute a modified version, any changes that you have made are --
-- clearly indicated. --
-- --
------------------------------------------------------------------------------
-- The content of this specification is taken "as is" from ASIS 2.0.R,
-- except context clauses and the content of the private part.
-- The code is reformatted to follow the GNAT coding style rules
------------------------------------------------------------------------------
-- 21 package Asis.Ids
------------------------------------------------------------------------------
------------------------------------------------------------------------------
package Asis.Ids is
------------------------------------------------------------------------------
------------------------------------------------------------------------------
-- Asis.Ids provides support for permanent unique Element "Identifiers" (Ids).
-- An Id is an efficient way for a tool to reference an ASIS element. The Id
-- is permanent from session to session provided that the Ada compilation
-- environment is unchanged.
------------------------------------------------------------------------------
------------------------------------------------------------------------------
-- This package encapsulates a set of operations and queries that implement
-- the ASIS Id abstraction. An Id is a way of identifying a particular
-- Element, from a particular Compilation_Unit, from a particular Context.
-- Ids can be written to files. Ids can be read from files and converted into
-- an Element value with the use of a suitable open Context.
--
------------------------------------------------------------------------------
------------------------------------------------------------------------------
-- 21.1 type Id
------------------------------------------------------------------------------
-- The Ada element Id abstraction (a private type).
--
-- The Id type is a distinct abstract type representing permanent "names"
-- that correspond to specific Element values.
--
-- These names can be written to files, retrieved at a later time, and
-- converted to Element values.
------------------------------------------------------------------------------
-- ASIS Ids are a means of identifying particular Element values obtained from
-- a particular physical compilation unit. Ids are "relative names". Each Id
-- value is valid (is usable, makes sense, can be interpreted) only in the
-- context of an appropriate open ASIS Context.
--
-- Id shall be an undiscriminated private type, or, shall be derived from an
-- undiscriminated private type. It shall be declared as a new type or as a
-- subtype of an existing type.
------------------------------------------------------------------------------
type Id is private;
Nil_Id : constant Id;
function "=" (Left : in Id; Right : in Id) return Boolean is abstract;
------------------------------------------------------------------------------
-- 21.2 function Hash
------------------------------------------------------------------------------
function Hash (The_Id : in Id) return Asis.ASIS_Integer;
------------------------------------------------------------------------------
-- 21.3 function "<"
------------------------------------------------------------------------------
function "<" (Left : in Id; Right : in Id) return Boolean;
------------------------------------------------------------------------------
-- 21.4 function ">"
------------------------------------------------------------------------------
function ">" (Left : in Id; Right : in Id) return Boolean;
------------------------------------------------------------------------------
-- 21.5 function Is_Nil
------------------------------------------------------------------------------
function Is_Nil (Right : in Id) return Boolean;
------------------------------------------------------------------------------
-- Right - Specifies the Id to check
--
-- Returns True if the Id is the Nil_Id.
--
------------------------------------------------------------------------------
-- 21.6 function Is_Equal
------------------------------------------------------------------------------
function Is_Equal (Left : in Id; Right : in Id) return Boolean;
------------------------------------------------------------------------------
-- Left - Specifies the left Id to compare
-- Right - Specifies the right Id to compare
--
-- Returns True if Left and Right represent the same physical Id, from the
-- same physical compilation unit. The two Ids convert
-- to Is_Identical Elements when converted with the same open ASIS Context.
--
------------------------------------------------------------------------------
-- 21.7 function Create_Id
------------------------------------------------------------------------------
function Create_Id (Element : in Asis.Element) return Id;
------------------------------------------------------------------------------
-- Element - Specifies any Element value whose Id is desired
--
-- Returns a unique Id value corresponding to this Element, from the
-- corresponding Enclosing_Compilation_Unit and the corresponding
-- Enclosing_Context. The Id value will not be equal ("=") to the Id value
-- for any other Element value unless the two Elements are Is_Identical.
--
-- Nil_Id is returned for a Nil_Element.
--
-- All Element_Kinds are appropriate.
--
------------------------------------------------------------------------------
-- 21.8 function Create_Element
------------------------------------------------------------------------------
function Create_Element
(The_Id : in Id;
The_Context : in Asis.Context)
return Asis.Element;
------------------------------------------------------------------------------
-- The_Id - Specifies the Id to be converted to an Element
-- The_Context - Specifies the Context containing the Element with this Id
--
-- Returns the Element value corresponding to The_Id. The_Id shall
-- correspond to an Element available from a Compilation_Unit contained by
-- (referencible through) The_Context.
--
-- Raises ASIS_Inappropriate_Element if the Element value is not available
-- though The_Context. The Status is Value_Error and the Diagnosis
-- string will attempt to indicate the reason for the failure. (e.g., "Unit is
-- inconsistent", "No such unit", "Element is inconsistent (Unit
-- inconsistent)", etc.)
--
------------------------------------------------------------------------------
-- 21.9 function Debug_Image
------------------------------------------------------------------------------
function Debug_Image (The_Id : in Id) return Wide_String;
------------------------------------------------------------------------------
-- The_Id - Specifies an Id to convert
--
-- Returns a string value containing implementation-defined debug
-- information associated with the Id.
--
-- The return value uses Asis.Text.Delimiter_Image to separate the lines
-- of multi-line results. The return value does not end with
-- Asis.Text.Delimiter_Image.
--
-- These values are intended for two purposes. They are suitable for
-- inclusion in problem reports sent to the ASIS implementor. They can
-- be presumed to contain information useful when debugging the
-- implementation itself. They are also suitable for use by the ASIS
-- application when printing simple application debugging messages during
-- application development. They are intended to be, to some worthwhile
-- degree, intelligible to the user.
--
------------------------------------------------------------------------------
private
-- The content of this private part is specific fot the ASIS
-- implementation for GNAT
type Id is access String;
Nil_Id : constant Id := null;
------------------------------------------------------------------------------
end Asis.Ids