1------------------------------------------------------------------------------
2--                                                                          --
3--                         GNAT RUN-TIME COMPONENTS                         --
4--                                                                          --
5--              A D A . E N V I R O N M E N T _ V A R I A B L E S           --
6--                                                                          --
7--                                 S p e c                                  --
8--                                                                          --
9-- This specification is derived from the Ada Reference Manual for use with --
10-- GNAT.  In accordance with the copyright of that document, you can freely --
11-- copy and modify this specification,  provided that if you redistribute a --
12-- modified version,  any changes that you have made are clearly indicated. --
13--                                                                          --
14------------------------------------------------------------------------------
15
16--  The implementation of this package is as defined in the Ada 2012 RM, but
17--  it is available in Ada 95 and Ada 2005 modes as well.
18
19package Ada.Environment_Variables is
20   pragma Preelaborate (Environment_Variables);
21
22   function Value (Name : String) return String;
23   --  If the external execution environment supports environment variables,
24   --  then Value returns the value of the environment variable with the given
25   --  name. If no environment variable with the given name exists, then
26   --  Constraint_Error is propagated. If the execution environment does not
27   --  support environment variables, then Program_Error is propagated.
28
29   function Value (Name : String; Default : String) return String;
30   --  If the external execution environment supports environment variables and
31   --  an environment variable with the given name currently exists, then Value
32   --  returns its value; otherwise, it returns Default.
33
34   function Exists (Name : String) return Boolean;
35   --  If the external execution environment supports environment variables and
36   --  an environment variable with the given name currently exists, then
37   --  Exists returns True; otherwise it returns False.
38
39   procedure Set (Name : String; Value : String);
40   --  If the external execution environment supports environment variables,
41   --  then Set first clears any existing environment variable with the given
42   --  name, and then defines a single new environment variable with the given
43   --  name and value. Otherwise Program_Error is propagated.
44   --
45   --  If implementation-defined circumstances prohibit the definition of an
46   --  environment variable with the given name and value, then exception
47   --  Constraint_Error is propagated.
48   --
49   --  It is implementation defined whether there exist values for which the
50   --  call Set (Name, Value) has the same effect as Clear (Name).
51
52   procedure Clear (Name : String);
53   --  If the external execution environment supports environment variables,
54   --  then Clear deletes all existing environment variables with the given
55   --  name. Otherwise Program_Error is propagated.
56
57   procedure Clear;
58   --  If the external execution environment supports environment variables,
59   --  then Clear deletes all existing environment variables. Otherwise
60   --  Program_Error is propagated.
61
62   procedure Iterate
63     (Process : not null access procedure (Name, Value : String));
64   --  If the external execution environment supports environment variables,
65   --  then Iterate calls the subprogram designated by Process for each
66   --  existing environment variable, passing the name and value of that
67   --  environment variable. Otherwise Program_Error is propagated.
68
69end Ada.Environment_Variables;
70