------------------------------------------------------------------------------
--                             G N A T C O L L                              --
--                                                                          --
--                        Copyright (C) 2022, AdaCore                       --
--                                                                          --
-- This library is free software;  you can redistribute it and/or modify it --
-- under terms of the  GNU General Public License  as published by the Free --
-- Software  Foundation;  either version 3,  or (at your  option) any later --
-- version. This library is distributed in the hope that it will be useful, --
-- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- --
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            --
--                                                                          --
-- As a special exception under Section 7 of GPL version 3, you are granted --
-- additional permissions described in the GCC Runtime Library Exception,   --
-- version 3.1, as published by the Free Software Foundation.               --
--                                                                          --
-- You should have received a copy of the GNU General Public License and    --
-- a copy of the GCC Runtime Library Exception along with this program;     --
-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
-- <http://www.gnu.org/licenses/>.                                          --
--                                                                          --
------------------------------------------------------------------------------

--  Implementation of path-based file lookups (like looking for a program in
--  the ``PATH`` environment variable).

private with Ada.Containers.Vectors;

private with GNAT.OS_Lib;

with GNATCOLL.Strings; use GNATCOLL.Strings;

package GNATCOLL.File_Paths is

   Path_Separator : constant Character;
   --  Default path separator on the current platform

   type Any_Path is private;
   --  Path where to look for files, i.e. sequence of directories

   type CWD_Mode is (If_Empty, CWD_First, CWD_Last);
   --  Control how to include the current working directory (CWD) to a path.
   --
   --  ``If_Empty``: automatically append it if the path would otherwise be
   --  empty.
   --
   --  ``CWD_First``: automatically append it first in the path (i.e. files are
   --  searched in priority in the CWD).
   --
   --  ``CWD_Last``: automatically append it last in the path (i.e. files are
   --  searched in the CWD as a last tentative).

   function Create_Path
     (Directories : XString_Array;
      CWD         : CWD_Mode := CWD_First) return Any_Path;
   --  Create a path for the given ``Directories`` (first directories are
   --  looked up before the next ones). ``CWD`` controls how to include the
   --  current working directory.

   function Create_Path_From_Environ
     (Var_Name  : String;
      Separator : Character := Path_Separator;
      CWD       : CWD_Mode := CWD_First) return Any_Path;
   --  Create a path for the directories listed in the ``Var_Name`` environment
   --  variable. Each path component is separated by ``Separator``. ``CWD``
   --  controls how to include the current working directory.

   function Parse_Path
     (Path      : String;
      Separator : Character := Path_Separator;
      CWD       : CWD_Mode := CWD_First) return Any_Path;
   --  Parse a path from the ``Path`` string. Each path component is separated
   --  by ``Separator``. ``CWD`` controls how to include the current working
   --  directory.

   procedure Add_Directory (Path : in out Any_Path; Directory : String);
   --  Add ``Directory`` to the given ``Path``. This new directory takes
   --  precedence over the existing ones for file lookups.

   function Lookup (Path : Any_Path; Filename : String) return String;
   --  Look for a filed called ``Filename`` in directories referenced by
   --  ``Path`` and return its absolute file name. If the file is not found,
   --  return an empty string.

   Empty_Path : constant Any_Path;
   --  Path for which only lookups on existing absolute file names will succeed

private

   Path_Separator : constant Character := GNAT.OS_Lib.Path_Separator;

   package String_Vectors is new Ada.Containers.Vectors (Positive, XString);

   type Any_Path is record
      Directories : String_Vectors.Vector;
      --  Last directories have precedence over the first ones for file lookups
   end record;

   Empty_Path : constant Any_Path :=
     (Directories => String_Vectors.Empty_Vector);

end GNATCOLL.File_Paths;