-- --
-- S p e c --
-- --
--- $Revision: 1.12 $
--- --
--- Copyright (C) 1998-2001 Ada Core Technologies, Inc. --
+-- Copyright (C) 1998-2004 Ada Core Technologies, Inc. --
-- --
-- GNAT is free software; you can redistribute it and/or modify it under --
-- terms of the GNU General Public License as published by the Free Soft- --
-- however invalidate any other reasons why the executable file might be --
-- covered by the GNU Public License. --
-- --
--- GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). --
+-- GNAT was originally developed by the GNAT team at New York University. --
+-- Extensive contributions were provided by Ada Core Technologies Inc. --
-- --
------------------------------------------------------------------------------
-- can be treated as a file, using open and close routines, and a scanning
-- routine is provided for iterating through the entries in a directory.
+-- See also child package GNAT.Directory_Operations.Iteration
+
+-- Note: support on OpenVMS is limited to the support of Unix-style
+-- directory names (OpenVMS native directory format is not supported).
+-- Read individual entries for more specific notes on OpenVMS support.
+
+with Ada.Strings.Maps;
+
package GNAT.Directory_Operations is
subtype Dir_Name_Str is String;
-- '\' character. It can also include drive letters if the operating
-- system provides for this. The final '/' or '\' in a Dir_Name_Str is
-- optional when passed as a procedure or function in parameter.
+ -- On OpenVMS, only Unix style path names are supported, not VMS style,
+ -- but the directory and file names are not case sensitive.
type Dir_Type is limited private;
-- A value used to reference a directory. Conceptually this value includes
-- Create a new directory named Dir_Name. Raises Directory_Error if
-- Dir_Name cannot be created.
- procedure Remove_Dir (Dir_Name : Dir_Name_Str);
- -- Remove the directory named Dir_Name. Raises Directory_Error if Dir_Name
- -- cannot be removed.
+ procedure Remove_Dir
+ (Dir_Name : Dir_Name_Str;
+ Recursive : Boolean := False);
+ -- Remove the directory named Dir_Name. If Recursive is set to True, then
+ -- Remove_Dir removes all the subdirectories and files that are in
+ -- Dir_Name. Raises Directory_Error if Dir_Name cannot be removed.
function Get_Current_Dir return Dir_Name_Str;
-- Returns the current working directory for the execution environment.
-- Returns directory name for Path. This is similar to the UNIX dirname
-- command. Everything after the last directory separator is removed. If
-- there is no directory separator the current working directory is
- -- returned.
+ -- returned. Note that the contents of Path is case-sensitive on
+ -- systems that have case-sensitive file names (like Unix), and
+ -- non-case-sensitive on systems where the file system is also non-
+ -- case-sensitive (such as Windows, and OpenVMS).
function Base_Name
(Path : Path_Name;
- Suffix : String := "")
- return String;
- -- Any directory prefix is removed. If Suffix is non-empty and is a
- -- suffix of Path, it is removed. This is equivalent to the UNIX basename
- -- command. The following rule is always true:
+ Suffix : String := "") return String;
+ -- Any directory prefix is removed. A directory prefix is defined as
+ -- text up to and including the last directory separator character in
+ -- the input string. In addition if Path ends with the string given for
+ -- Suffix, then it is also removed. Note that Suffix here can be an
+ -- arbitrary string (it is not required to be a file extension). This
+ -- is equivalent to the UNIX basename command. The following rule is
+ -- always true:
--
-- 'Path' and 'Dir_Name (Path) & Directory_Separator & Base_Name (Path)'
-- represent the same file.
--
- -- This function is not case-sensitive on systems that have a non
- -- case-sensitive file system like Windows, OS/2 and VMS.
+ -- The comparison of Suffix is case-insensitive on systems such as Windows
+ -- and VMS where the file search is case-insensitive (e.g. on such systems,
+ -- Base_Name ("/Users/AdaCore/BB12.patch", ".Patch") returns "BB12").
function File_Extension (Path : Path_Name) return String;
- -- Return the file extension. This is the string after the last dot
- -- character in File_Name (Path). It returns the empty string if no
- -- extension is found. The returned value does contains the file
- -- extension separator (dot character).
+ -- Return the file extension. This is defined as the string after the
+ -- last dot, including the dot itself. For example, if the file name
+ -- is "file1.xyz.adq", then the returned value would be ".adq". If no
+ -- dot is present in the file name, or the last character of the file
+ -- name is a dot, then the null string is returned.
function File_Name (Path : Path_Name) return String;
-- Returns the file name and the file extension if present. It removes all
-- path information. This is equivalent to Base_Name with default Extension
-- value.
- type Path_Style is (UNIX, DOS, System_Default);
+ type Path_Style is
+ (UNIX,
+ -- Use '/' as the directory separator. The default on Unix systems
+ -- and on OpenVMS.
+
+ DOS,
+ -- Use '\' as the directory separator. The default on Windows.
+
+ System_Default);
- function Normalize_Pathname
+ function Format_Pathname
(Path : Path_Name;
- Style : Path_Style := System_Default)
- return Path_Name;
+ Style : Path_Style := System_Default) return Path_Name;
-- Removes all double directory separator and converts all '\' to '/' if
-- Style is UNIX and converts all '/' to '\' if Style is set to DOS. This
-- function will help to provide a consistent naming scheme running for
-- different environments. If style is set to System_Default the routine
-- will use the default directory separator on the running environment.
- function Expand_Path (Path : Path_Name) return Path_Name;
- -- Returns Path with environment variables (string preceded by a dollar
- -- sign) replaced by the current environment variable value. For example,
+ type Environment_Style is
+ (UNIX,
+ -- Environment variables and OpenVMS logical names use $ as prefix and
+ -- can use curly brackets as in ${HOME}/mydir. If there is no closing
+ -- curly bracket for an opening one then translation is done, so for
+ -- example ${VAR/toto is returned as ${VAR/toto.
+
+ DOS,
+ -- Environment variables uses % as prefix and suffix
+ -- (e.g. %HOME%/mydir). The name DOS refer to "DOS-like" environment.
+ -- This includes al Windows systems.
+
+ Both,
+ -- Recognize both forms described above.
+
+ System_Default);
+ -- Uses either UNIX on Unix and OpenVMS systems, or DOS on Windows and
+ -- OS/2 depending on the running environment.
+
+ function Expand_Path
+ (Path : Path_Name;
+ Mode : Environment_Style := System_Default) return Path_Name;
+ -- Returns Path with environment variables (or logical names on OpenVMS)
+ -- replaced by the current environment variable value. For example,
-- $HOME/mydir will be replaced by /home/joe/mydir if $HOME environment
- -- variable is set to /home/joe. The variable can be surrounded by the
- -- characters '{' and '}' (curly bracket) if needed as in ${HOME}/mydir.
- -- If an environment variable does not exists the variable will be replaced
- -- by the empty string. Two dollar signs are replaced by a single dollar
- -- sign. Note that a variable must start with a letter. If there is no
- -- closing curly bracket for an opening one there is no translation done,
- -- so for example ${VAR/toto is returned as ${VAR/toto.
+ -- variable is set to /home/joe and Mode is UNIX. If an environment
+ -- variable does not exists the variable will be replaced by the empty
+ -- string. Two dollar or percent signs are replaced by a single
+ -- dollar/percent sign. Note that a variable must start with a letter.
---------------
-- Iterators --
-- returned in target-OS form. Raises Directory_Error if Dir has not
-- be opened (Dir = Null_Dir).
- generic
- with procedure Action
- (Item : String;
- Index : Positive;
- Quit : in out Boolean);
- procedure Wildcard_Iterator (Path : Path_Name);
- -- Calls Action for each path matching Path. Path can include wildcards '*'
- -- and '?' and [...]. The rules are:
- --
- -- * can be replaced by any sequence of characters
- -- ? can be replaced by a single character
- -- [a-z] match one character in the range 'a' through 'z'
- -- [abc] match either character 'a', 'b' or 'c'
- --
- -- Item is the filename that has been matched. Index is set to one for the
- -- first call and is incremented by one at each call. The iterator's
- -- termination can be controlled by setting Quit to True. It is by default
- -- set to False.
- --
- -- For example, if we have the following directory structure:
- -- /boo/
- -- foo.ads
- -- /sed/
- -- foo.ads
- -- file/
- -- foo.ads
- -- /sid/
- -- foo.ads
- -- file/
- -- foo.ads
- -- /life/
- --
- -- A call with expression "/s*/file/*" will call Action for the following
- -- items:
- -- /sed/file/foo.ads
- -- /sid/file/foo.ads
-
- generic
- with procedure Action
- (Item : String;
- Index : Positive;
- Quit : in out Boolean);
- procedure Find
- (Root_Directory : Dir_Name_Str;
- File_Pattern : String);
- -- Recursively searches the directory structure rooted at Root_Directory.
- -- This provides functionality similar to the UNIX 'find' command.
- -- Action will be called for every item matching the regular expression
- -- File_Pattern (see GNAT.Regexp). Item is the full pathname to the file
- -- starting with Root_Directory that has been matched. Index is set to one
- -- for the first call and is incremented by one at each call. The iterator
- -- will pass in the value False on each call to Action. The iterator will
- -- terminate after passing the last matched path to Action or after
- -- returning from a call to Action which sets Quit to True.
- -- Raises GNAT.Regexp.Error_In_Regexp if File_Pattern is ill formed.
-
function Read_Is_Thread_Safe return Boolean;
-- Indicates if procedure Read is thread safe. On systems where the
-- target system supports this functionality, Read is thread safe,
pragma Import (C, Dir_Separator, "__gnat_dir_separator");
+ Dir_Seps : constant Ada.Strings.Maps.Character_Set :=
+ Ada.Strings.Maps.To_Set ("/\");
+ -- UNIX and DOS style directory separators.
+
end GNAT.Directory_Operations;