package Environment is
   -- This package provides access to environment variables.
   -- Many operating systems support environment variables, including
   -- the various Unixes, Linux, MS-DOS, Windows, and Mac OS (X or later).
   -- Since environments are common, Ada needs a standard interface for them;
   -- this is a proposed standard interface to them.
   -- This version dated 2003-12-18.

   -- The environment is a set of keys and their corresponding values.
   -- It can also be accessed by position.

   -- This is a proposal for Ada 200Y.  If accepted, this would presumably
   -- go into Ada.XYZ.

   -- RATIONALE: This package includes wrappers for the common functions
   -- for environments, using similar names so that developers familiar
   -- with these calls in other languages will have an easy time
   -- understanding them.
   -- The "env" in many functions has been renamed as "Environment" because
   -- it's common for Ada functions to be written in full.
   -- Thus C's "getenv()" is Get_Environment() here.
   -- The function names could have shortened (e.g., to "Get"), but
   -- this would be extremely confusing to Ada developers, since Get
   -- and Put already having meanings in the Ada standard; it would
   -- also cause severe problems to anyone who tried a "use" clause with it.
   -- When examining previous work, I found that GNAT includes
   -- a package Ada.Command_Line.Environment
   -- (often installed as a-colien.ad[sb] in its adainclude directory).
   -- However, this package only supports two functions:
   --    function Environment_Count return Natural;
   --    function Environment_Value (Number : in Positive) return String;
   -- This is a very clumsy interface and inadequate for many tasks (which
   -- need a key); C supports getenv(), setenv(), unsetenv(), clearenv(), etc.
   -- Also, Environment_Value only returned "key=value" pair which is often
   -- awkward to work with (it's often useful to break it up).
   -- This interface uses the term "Get_Environment_Pair" instead of
   -- Get_Value to avoid confusion.  It does provide a pair interface,
   -- however, to simplify conversion of GNAT programs and putenv() users.

   -- Written by David A. Wheeler December 2003.
   -- This specification is released to the public domain.

   Cannot_Set : exception;
   -- Raised if there's a problem changing the environment.

   function Environment_Count return Natural;
   -- Returns the number of environment variables available;
   -- 0 if there are none.
   -- RATIONALE: Needed for iterators, and wraps
   -- GNAT's Ada.Command_Line.Environment function.

   function Get_Environment(Key : String; Default : String := "")
   return String;
   -- Get the value of the environment variable Key.
   -- If there is no such environment variable, return Default.
   -- In most implementations "Key" cannot include the characters "=" or NIL;
   -- other limitations are operating-system dependent.
   -- RATIONALE: Wraps C's getenv().  This could have been implemented
   -- to raise an exception if there's no environment variable
   -- named Key, but that would be inconvenient to use and cause problems
   -- if Restrictions(No_Exceptions) is used (it's expected that in such
   -- environments you might not need to change the environment, but it'd
   -- be very useful to be able to read it).
   -- One disadvantage to this approach is that it's not possible just
   -- with this call to tell the difference between an environment variable
   -- that doesn't exist and an environment variable
   -- set to a zero-length string.  However, this difference can be detected
   -- by using the Exists_In_Environment call.
   -- The Default parameter is included because it's common to use environment
   -- variables to override defaults; allowing a default greatly simplifies
   -- common use, simply try to get the environment variable and set the
   -- default to whatever value is desired if there's no environment variable.
   pragma Inline(Get_Environment);  -- Not required by the specification.

   function Exists_In_Environment(Key : String) return Boolean;
   -- Returns True if Key is set in environment, else returns False.
   -- RATIONALE: Lets people see if a variable exists, without requiring
   -- exception processing (which may be prevented by Restrictions).

   function Get_Environment_Position(Position : in Positive) return String;
   -- Get the value of the environment variable at Position.
   -- This does not include the key's name.
   -- RATIONALE: Supports iteration.

   function Get_Key_Position(Position : in Positive) return String;
   -- Get the key of environment variable at Position.
   -- RATIONALE: Supports iteration.

   function Get_Pair_Position(Position : in Positive) return String;
   -- Get the key and value of the Nth environment variable, in the form
   -- Key=Value.
   -- RATIONALE: Wraps GNAT's Ada.Command_Line.Environment
   -- function Environment_Value, simplifying transition to a standard package.

   procedure Set_Environment(Key : String; Value : String;
                             Overwrite : Boolean := True);
   -- Set the environment variable key to value.
   -- If overwrite is false, the variable is left unchanged if there is a
   -- variable with that key value already (without complaint).
   -- Raises Cannot_Set if can't set the environment
   -- (e.g., due to being out of memory).
   -- This new environment will propogate to any processes started later.
   -- THIS MAY REORDER the environment variables.  Note that
   -- many implementations will check to see if there is more than
   -- one entry with the same key name (this is never supposed to happen),
   -- and will remove all of them.
   -- RATIONALE: Wraps setenv().

   procedure Set_Environment_Pair(Pair : String);
   -- As with Set_Environment, but for a Key=Value pair.
   -- RATIONALE: Wraps putenv().

   procedure Unset_Environment(Key : String);
   -- Removes the environment variable Key.
   -- This new environment will propogate to any processes started later.
   -- THIS MAY REORDER the environment variables.
   -- RATIONALE: Wraps unsetenv().

   procedure Clear_Environment;
   -- Erases the entire environment.
   -- RATIONALE: Wraps clearenv().
   -- This procedure is often necessary when writing applications
   -- with elevated privileges (such as setuid/setgid programs in Unix).

end Environment;