Package: Ada.Directories

Dependencies

pragma License (Unrestricted);

with Ada.Calendar;
with Ada.Finalization;
with Ada.IO_Exceptions;

Description

AI-248

Package Ada.Directories provides portable access to tree-structured file systems and the ability to search for files.

External files may be classified as directories, special files, or ordinary files. A directory is an external file that is a container for files on the target system. A special file is an external file that cannot be created or read by a predefined Ada Input-Output package. External files that are not special files or directories are called ordinary files.

AARM Ramification: A directory is an external file, although it may not have a name on some targets. A directory is not a special file, as it can be created and read by Ada.Directories.

AARM Discussion: Devices and soft links are examples of special files on Windows and Unix.

Even if an implementation provides a package to create and read on soft links, such links are still special files.

A file name is a string identifying an external file. Similarly, a directory name is a string identifying a directory. The interpretation of file names and directory names is implementation-defined.

The full name of an external file is a full specification of the name of the file. If the external environment allows alternative specifications of the name (for example, abbreviations), the full name should not use such alternatives. A full name typically will include the names of all of directories that contain the item. The simple name of an external file is the name of the item, not including any containing directory names. Unless otherwise specified, a file name or directory name parameter to a predefined Ada input-output subprogram can be a full name, a simple name, or any other form of name supported by the implementation.

AARM Discussion: The full name on Unix is a complete path to the root. For Windows, the full name includes a complete path, as well as a disk name ("C:") or network share name. For both systems, the simple name is the part of the name following the last '/' (or '\' for Windows). For example, in the name "/usr/randy/ada-directories.ads", "ada-directories.ads" is the simple name.

AARM Ramification: It is possible for a file or directory name to be neither a full name nor a simple name. For instance, the Unix name "../parent/myfile" is neither a full name nor a simple name.

The default directory is the directory that is used if a directory or file name is not a full name (that is, when the name does not fully identify all of the containing directories).

AARM Discussion: The default directory is the one maintained by the familiar "cd" command on Unix and Windows. Note that Windows maintains separate default directories for each disk drive; implementations should use the natural implementation.

A directory entry is a single item in a directory, identifying a single external file (including directories and special files).

For each function that returns a string, the lower bound of the returned value is 1.

Header

package Ada.Directories is

Exceptions

Device_Error renames Ada.IO_Exceptions.Device_Error

Name_Error renames Ada.IO_Exceptions.Name_Error

Status_Error renames Ada.IO_Exceptions.Status_Error

Use_Error renames Ada.IO_Exceptions.Use_Error

Type Summary

`Directory_Entry_Type` (limited type)
Primitive Operations:	`Full_Name`, `Get_Next_Entry`, `Kind`, `Modification_Time`, `Simple_Name`, `Size`
`File_Kind`
`File_Size`
`Filter_Type`
`Search_Type` (limited type)
Primitive Operations:	`End_Search`, `Get_Next_Entry`, `More_Entries`, `Start_Search`

Other Items:

function Current_Directory
   return String;

Returns the full directory name for the current default directory. The name returned shall be suitable for a future call to Set_Directory. The exception Use_Error is propagated if a default directory is not supported by the external environment.

procedure Set_Directory (Directory : in String);

Sets the current default directory. The exception Name_Error is propagated if the string given as Directory does not identify an existing directory. The exception Use_Error is propagated if the external environment does not support making Directory (in the absence of Name_Error) a default directory.

procedure Create_Directory (New_Directory : in String;
                            Form          : in String := "");

Creates a directory with name New_Directory. The Form parameter can be used to give system-dependent characteristics of the directory; the interpretation of the Form parameter is implementation-defined. A null string for Form specifies the use of the default options of the implementation of the new directory. The exception Name_Error is propagated if the string given as New_Directory does not allow the identification of a directory. The exception Use_Error is propagated if the external environment does not support the creation of a directory with the given name (in the absence of Name_Error) and form.

procedure Delete_Directory (Directory : in String);

Deletes an existing empty directory with name Directory. The exception Name_Error is propagated if the string given as Directory does not identify an existing directory. The exception Use_Error is propagated if the external environment does not support the deletion of the directory (or some portion of its contents) with the given name (in the absence of Name_Error).

procedure Create_Path (New_Directory : in String;
                       Form          : in String := "");

Creates zero or more directories with name New_Directory. Each non-existent directory named by New_Directory is created. For example, on a typical Unix system, Create_Path ("/usr/me/my"); would create directory "me" in directory "usr", then create directory "my" in directory "me". The Form can be used to give system-dependent characteristics of the directory; the interpretation of the Form parameter is implementation-defined. A null string for Form specifies the use of the default options of the implementation of the new directory. The exception Name_Error is propagated if the string given as New_Directory does not allow the identification of any directory. The exception Use_Error is propagated if the external environment does not support the creation of any directories with the given name (in the absence of Name_Error) and form.

procedure Delete_Tree (Directory : in String);

Deletes an existing directory with name Directory. The directory and all of its contents (possibly including other directories) are deleted. The exception Name_Error is propagated if the string given as Directory does not identify an existing directory. The exception Use_Error is propagated if the external environment does not support the deletion of the directory or some portion of its contents with the given name (in the absence of Name_Error). If Use_Error is propagated, it is unspecified if a portion of the contents of the directory are deleted.

procedure Delete_File (Name : in String);

Deletes an existing ordinary or special file with Name. The exception Name_Error is propagated if the string given as Name does not identify an existing ordinary or special external file. The exception Use_Error is propagated if the external environment does not support the deletion of the file with the given name (in the absence of Name_Error).

procedure Rename (Old_Name,
                  New_Name  : in String);

Renames an existing external file (including directories) with Old_Name to New_Name. The exception Name_Error is propagated if the string given as Old_Name does not identify an existing external file. The exception Use_Error is propagated if the external environment does not support the renaming of the file with the given name (in the absence of Name_Error). In particular, Use_Error is propagated if a file or directory already exists with New_Name.

procedure Copy_File (Source_Name,
                     Target_Name  : in String;
                     Form         : in String := "");

Copies the contents of the existing external file with Source_Name to Target_Name. The resulting external file is a duplicate of the source external file. The Form can be used to give system-dependent characteristics of the resulting external file; the interpretation of the Form parameter is implementation-defined. Exception Name_Error is propagated if the string given as Source_Name does not identify an existing external ordinary or special file or if the string given as Target_Name does not allow the identification of an external file. The exception Use_Error is propagated if the external environment does not support the creating of the file with the name given by Target_Name and form given by Form, or copying of the file with the name given by Source_Name (in the absence of Name_Error).

AARM Ramification: Name_Error is always raised if Source_Name identifies a directory. It is up to the implementation whether special files can be copied, or if Use_Error will be raised.

function Full_Name (Name : in String)
   return String;

Returns the full name corresponding to the file name specified by Name. The exception Name_Error is propagated if the string given as Name does not allow the identification of an external file (including directories and special files).

AARM Discussion: Full name means that no abbreviations are used in the returned name, and that it is a full specification of the name. Thus, for Unix and Windows, the result should be a full path which does not contain any "." or ".." directories. Typically, the default directory is used to fill in any missing information.

function Simple_Name (Name : in String)
   return String;

Returns the simple name portion of the file name specified by Name. The exception Name_Error is propagated if the string given as Name does not allow the identification of an external file (including directories and special files).

function Containing_Directory (Directory : in String)
   return String;

Returns the name of the containing directory of the external file (including directories) identified by Name. (If more than one directory can contain Name, the directory name returned is implementation- defined.)

The exception Name_Error is propagated if the string given as Name does not allow the identification of an external file. The exception Use_Error is propagated if the external file does not have a containing directory.

AARM Discussion: This is purely a string manipulation function. If Name is not given as a full name, the containing directory probably won't be one, either. For example, if Containing_Directory ("..\AARM\RM-A-8") is called on Windows, the result should be "..\AARM". Use Full_Name on the result of Containing_Directory if the full name is needed.

function Extension (Name : in String)
   return String;

Returns the extension name corresponding to Name. The extension name is a portion of a simple name (not including any separator characters), typically used to identify the file class. If the external environment does not have extension names, then the null string is returned. The exception Name_Error is propagated if the string given as Name does not allow the identification of an external file.

AARM Discussion: For Unix and Windows, the extension is the portion of the simple name following the rightmost period. For example, in the simple name "RM-A-8.html", the extension is "html".

function Base_Name (Name : in String)
   return String;

Returns the base name corresponding to Name. The base name is the remainder of a simple name after removing any extension and extension separators. The exception Name_Error is propagated if the string given as Name does not allow the identification of an external file (including directories and special files).

function Compose (Containing_Directory : in String := "";
                  Name                 : in String;
                  Extension            : in String := "")
   return String;

Returns the name of the external file with the specified Containing_Directory, Name, and Extension. If Extension is the null string, then Name is interpreted as a simple name; otherwise Name is interpreted as a base name. The exception Name_Error is propagated if the string given as Containing_Directory is not null and does not allow the identification of a directory, or if the string given as Extension is not null and is not a possible extension, or if the string given as Name is not a possible simple name (if Extension is null) or base name (if Extension is non-null).

AARM Discussion: If Name is null, Name_Error should be raised as nothing is not a possible simple name or base name.

type File_Kind is
   (Directory, Ordinary_File, Special_File);

The type File_Kind represents the kind of file represented by an external file or directory.

type File_Size is
   range 0 .. Long_Integer'Last;

The type File_Size represents the size of an external file.

function Exists (Name : in String)
   return Boolean;

Returns True if external file represented by Name exists, and False otherwise. The exception Name_Error is propagated if the string given as Name does not allow the identification of an external file (including directories and special files).

function Kind (Name : in String)
   return File_Kind;

Returns the kind of external file represented by Name. The exception Name_Error is propagated if the string given as Name does not allow the identification of an existing external file.

function Size (Name : in String)
   return File_Size;

Returns the size of the external file represented by Name. The size of an external file is the number of stream elements contained in the file. If the external file is discontiguous (not all elements exist), the result is implementation-defined. If the external file is not an ordinary file, the result is implementation-defined. The exception Name_Error is propagated if the string given as Name does not allow the identification of an existing external file. The exception Constraint_Error is propagated if the file size is not a value of type File_Size.

AARM Discussion: We allow raising Constraint_Error, so that an implementation for a system with 64-bit file sizes does not need to support full numerics on 64-bit integers just to implement this package. Of course, if 64-bit integers are available on such a system, they should be used when defining type File_Size.

function Modification_Time (Name : in String)
   return Ada.Calendar.Time;

Returns the time that the external file represented by Name was most recently modified. If the external file is not an ordinary file, the result is implementation-defined. The exception Name_Error is propagated if the string given as Name does not allow the identification of an existing external file. The exception Use_Error is propagated if the external environment does not support the reading the modification time of the file with the name given by Name (in the absence of Name_Error).

type Directory_Entry_Type is
   limited private;

The type Directory_Entry_Type represents a single item in a directory. These items can only be created by the Get_Next_Entry procedure in this package. Information about the item can be obtained from the functions declared in this package. A default initialized object of this type is invalid; objects returned from Get_Next_Entry are valid.

type Filter_Type is
   array (File_Kind) of Boolean;

The type Filter_Type specifies which directory entries are provided from a search operation. If the Directory component is True, directory entries representing directories are provided. If the Ordinary_File component is True, directory entries representing ordinary files are provided. If the Special_File component is True, directory entries representing special files are provided.

type Search_Type is
   limited private;

The type Search_Type contains the state of a directory search. A default-initialized Search_Type object has no entries available (More_Entries returns False).

procedure Start_Search (Search    : in out Search_Type;
                        Directory : in     String;
                        Pattern   : in     String;
                        Filter    : in     Filter_Type := (others => True));

Starts a search in the directory entry in the directory named by Directory for entries matching Pattern. Pattern represents a file name matching pattern. If Pattern is null, all items in the directory are matched; otherwise, the interpretation of Pattern is implementation-defined. Only items which match Filter will be returned. After a successful call on Start_Search, the object Search may have entries available, but it may have no entries available if no files or directories match Pattern and Filter. The exception Name_Error is propagated if the string given by Directory does not identify an existing directory, or if Pattern does not allow the identification of any possible external file or directory. The exception Use_Error is propagated if the external environment does not support the searching of the directory with the given name (in the absence of Name_Error).

AARM Discussion: Pattern should use the pattern matching characters commonly used on the target. For instance, on Unix and Windows, both '*' and '?' should be supported, with their conventional meaning.

procedure End_Search (Search : in out Search_Type);

Ends the search represented by Search. After a successful call on End_Search, the object Search will have no entries available.

function More_Entries (Search : in Search_Type)
   return Boolean;

Returns True if more entries are available to be returned by a call to Get_Next_Entry for the specified search object, and False otherwise.

procedure Get_Next_Entry (Search          : in out Search_Type;
                          Directory_Entry :    out Directory_Entry_Type);

Returns the next Directory_Entry for the search described by Search that matches the pattern and filter. If no further matches are available, Status_Error is raised. It is implementation-defined as to whether the results returned by this routine are altered if the contents of the directory are altered while the Search object is valid (for example, by another program). The exception Use_Error is propagated if the external environment does not support continued searching of the directory represented by Search.

function Simple_Name (Directory_Entry : in Directory_Entry_Type)
   return String;

Returns the simple external name of the external file (including directories) represented by Directory_Entry. The format of the name returned is implementation-defined. The exception Status_Error is propagated if Directory_Entry is invalid.

function Full_Name (Directory_Entry : in Directory_Entry_Type)
   return String;

Returns the full external name of the external file (including directories) represented by Directory_Entry. The format of the name returned is implementation-defined. The exception Status_Error is propagated if Directory_Entry is invalid.

function Kind (Directory_Entry : in Directory_Entry_Type)
   return File_Kind;

Returns the kind of external file represented by Directory_Entry. The exception Status_Error is propagated if Directory_Entry is invalid.

function Size (Directory_Entry : in Directory_Entry_Type)
   return File_Size;

Returns the size of the external file represented by Directory_Entry. The size of an external file is the number of stream elements contained in the file. If the external file is discontiguous (not all elements exist), the result is implementation-defined. If the external file represented by Directory_Entry is not an ordinary file, the result is implementation-defined. The exception Status_Error is propagated if Directory_Entry is invalid. The exception Constraint_Error is propagated if the file size is not a value of type File_Size.

function Modification_Time (Directory_Entry : in Directory_Entry_Type)
   return Ada.Calendar.Time;

Returns the time that the external file represented by Directory_Entry was most recently modified. If the external file represented by Directory_Entry is not an ordinary file, the result is implementation-defined. The exception Status_Error is propagated if Directory_Entry is invalid. The exception Use_Error is propagated if the external environment does not support the reading the modification time of the file represented by Directory_Entry.

private

   --  Implementation-defined ...

end Ada.Directories;