File : asis-implementation.ads


------------------------------------------------------------------------------
--                                                                          --
--                 ASIS-for-GNAT IMPLEMENTATION COMPONENTS                  --
--                                                                          --
--                  A S I S . I M P L E M E N T A T I O N                   --
--                                                                          --
--                                 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.
--  The code is reformatted to follow the GNAT coding style rules

------------------------------------------------------------------------------
--  6  package Asis.Implementation
------------------------------------------------------------------------------
------------------------------------------------------------------------------
with Asis.Errors;
package Asis.Implementation is
------------------------------------------------------------------------------
------------------------------------------------------------------------------
--  Asis.Implementation provides queries to initialize, finalize, and query the
--  error status of the ASIS Implementation.
------------------------------------------------------------------------------
------------------------------------------------------------------------------

------------------------------------------------------------------------------
--  6.1   function ASIS_Version
------------------------------------------------------------------------------

   function ASIS_Version return Wide_String;

------------------------------------------------------------------------------
--  6.2   function ASIS_Implementor
------------------------------------------------------------------------------

   function ASIS_Implementor return Wide_String;

------------------------------------------------------------------------------
--  6.3   function ASIS_Implementor_Version
------------------------------------------------------------------------------

   function ASIS_Implementor_Version return Wide_String;

------------------------------------------------------------------------------
--  6.4   function ASIS_Implementor_Information
------------------------------------------------------------------------------

   function ASIS_Implementor_Information return Wide_String;

------------------------------------------------------------------------------
--  Returns values which identify:
--
--   ASIS_Version                 - the version of the ASIS interface,
--                                  e.g., "2.1"
--   ASIS_Implementor             - the name of the implementor,
--                                  e.g., "Ada Inc."
--   ASIS_Implementor_Version     - the implementation's version,
--                                  e.g., "5.2a"
--   ASIS_Implementor_Information - implementation information,
--                                  e.g., "Copyright ..."
--
------------------------------------------------------------------------------
--  6.5   function Is_Initialized
------------------------------------------------------------------------------

   function Is_Initialized return Boolean;

------------------------------------------------------------------------------
--  Returns True if ASIS is currently initialized.
--
------------------------------------------------------------------------------
--  6.6   procedure Initialize
------------------------------------------------------------------------------

   procedure Initialize (Parameters : in Wide_String := "");

------------------------------------------------------------------------------
--  Parameters  - Specifies implementation specific parameters.
--
--  Performs any necessary initialization activities.  This shall be invoked
--  at least once before any other ASIS services are used.  Parameter values
--  are implementation dependent.  The call is ignored if ASIS is already
--  initialized. All ASIS queries and services are ready for use once this
--  call completes.
--
--  Raises ASIS_Failed if ASIS failed to initialize or if the Parameters
--  argument is invalid.  Status is Environment_Error or Parameter_Error.
--
--  --|AN Application Note:
--  --|AN
--  --|AN The ASIS implementation may be Initialized and Finalized any number
--  --|AN of times during the operation of an ASIS program. However, all
--  --|AN existing Context, Compilation_Unit and Element values become invalid
--  --|AN when ASIS Is_Finalized. Subsequent calls to ASIS queries or services
--  --|AN using such invalid Compilation_Unit or Element values will cause
--  --|AN ASIS_Inappropriate_Context to be raised.
--
------------------------------------------------------------------------------
--  6.7   function Is_Finalized
------------------------------------------------------------------------------

   function Is_Finalized return Boolean;

------------------------------------------------------------------------------
--  Returns True if ASIS is currently finalized or if ASIS has never been
--  initialized.
--
------------------------------------------------------------------------------
--  6.8   procedure Finalize
------------------------------------------------------------------------------

   procedure Finalize (Parameters : in Wide_String := "");

------------------------------------------------------------------------------
--  Parameters  - Specifies any implementation required parameter values.
--
--  Performs any necessary ASIS termination activities.  This should be invoked
--  once following the last use of other ASIS queries.  Parameter values are
--  implementation dependent. The call is ignored if ASIS is already finalized.
--  Subsequent calls to ASIS Environment, Compilation_Unit, and Element
--  queries, are erroneous while the environment Is_Finalized.
--
--  Raises ASIS_Failed if the ASIS implementation failed to finalize.  Status
--  is likely to be Internal_Error and will not be Not_An_Error.
--
-------------------------------------------------------------------------------
--  Whenever an error condition is detected, and any ASIS exception is raised,
--  an Asis.Errors.Error_Kinds value and a Diagnosis string is stored.  These
--  values can be retrieved by the Status and Diagnosis functions.  The
--  Diagnosis function will retrieve the diagnostic message describing the
--  error.
--
--  Error information always refers to the most recently recorded error.
--
--  Note that Diagnosis values are implementation dependent and may vary
--  greatly among ASIS implementations.
--
------------------------------------------------------------------------------
--  6.9   function Status
------------------------------------------------------------------------------

   function Status return Asis.Errors.Error_Kinds;

------------------------------------------------------------------------------
--  Returns the Error_Kinds value for the most recent error.
--
------------------------------------------------------------------------------
--  6.10  function Diagnosis
------------------------------------------------------------------------------

   function Diagnosis return Wide_String;

------------------------------------------------------------------------------
--  Returns a string value describing the most recent error.
--
--  Will typically return a null string if Status = Not_An_Error.
--
------------------------------------------------------------------------------
--  6.11  procedure Set_Status
------------------------------------------------------------------------------

   procedure Set_Status
     (Status    : in Asis.Errors.Error_Kinds := Asis.Errors.Not_An_Error;
      Diagnosis : in Wide_String             := "");

------------------------------------------------------------------------------
--  Status      - Specifies the new status to be recorded
--  Diagnosis   - Specifies the new diagnosis to be recorded
--
--  Sets (clears, if the defaults are used) the Status and Diagnosis
--  information.  Future calls to Status will return this Status (Not_An_Error)
--  and this Diagnosis (a null string).
--
--  Raises ASIS_Failed, with a Status of Internal_Error and a Diagnosis of
--  a null string, if the Status parameter is Not_An_Error and the Diagnosis
--  parameter is not a null string.
--
------------------------------------------------------------------------------
--
end Asis.Implementation