A.16.1 The Package Directories.Hierarchical_File_Names
The library package Directories.Hierarchical_File_Names
is an optional package providing operations for file name construction
and decomposition for targets with hierarchical file naming.
Static Semantics
If provided, the library
package Directories.Hierarchical_File_Names has the following declaration:
package Ada.Directories.Hierarchical_File_Names
with Nonblocking, Global =>
in out synchronized is
function Is_Simple_Name (Name :
in String)
return Boolean;
function Is_Root_Directory_Name (Name :
in String)
return Boolean;
function Is_Parent_Directory_Name (Name :
in String)
return Boolean;
function Is_Current_Directory_Name (Name :
in String)
return Boolean;
function Is_Full_Name (Name :
in String)
return Boolean;
function Is_Relative_Name (Name :
in String)
return Boolean;
function Simple_Name (Name :
in String)
return String
renames Ada.Directories.Simple_Name;
function Containing_Directory (Name :
in String)
return String
renames Ada.Directories.Containing_Directory;
function Initial_Directory (Name :
in String)
return String;
function Relative_Name (Name :
in String)
return String;
function Compose (Directory :
in String := "";
Relative_Name :
in String;
Extension :
in String := "")
return String;
end Ada.Directories.Hierarchical_File_Names;
In addition to the operations provided in package
Directories.Hierarchical_File_Names, the operations in package Directories
can be used with hierarchical file names. In particular, functions Full_Name,
Base_Name, and Extension provide additional capabilities for hierarchical
file names.
function Is_Simple_Name (Name : in String) return Boolean;
Returns True if Name is a simple name, and returns
False otherwise.
function Is_Root_Directory_Name (Name : in String) return Boolean;
Returns True if Name is syntactically a root (a
directory that cannot be decomposed further), and returns False otherwise.
function Is_Parent_Directory_Name (Name : in String) return Boolean;
Returns True if Name can be used to indicate symbolically
the parent directory of any directory, and returns False otherwise.
function Is_Current_Directory_Name (Name : in String) return Boolean;
Returns True if Name can be used to indicate symbolically
the directory itself for any directory, and returns False otherwise.
function Is_Full_Name (Name : in String) return Boolean;
Returns True if the leftmost directory part of
Name is a root, and returns False otherwise.
function Is_Relative_Name (Name : in String) return Boolean;
Returns True if Name allows the identification
of an external file (including directories and special files) but is
not a full name, and returns False otherwise.
function Initial_Directory (Name : in String) return String;
Returns the leftmost directory part in Name. That
is, it returns a root directory name (for a full name), or one of a parent
directory name, a current directory name, or a simple name (for a relative
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 Relative_Name (Name : in String) return String;
Returns the entire file name except the Initial_Directory
portion. 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), or if Name has a single part (this includes
if any of Is_Simple_Name, Is_Root_Directory_Name, Is_Parent_Directory_Name,
or Is_Current_Directory_Name are True).
function Compose (Directory : in String := "";
Relative_Name : in String;
Extension : in String := "") return String;
Returns the name of the external file with the
specified Directory, Relative_Name, and Extension. The exception Name_Error
is propagated if the string given as Directory is not the null string
and does not allow the identification of a directory, or if Is_Relative_Name
(Relative_Name) is False, or if the string given as Extension is not
the null string and is not a possible extension, or if Extension is not
the null string and Simple_Name (Relative_Name) is not a base name.
The result of Compose is a full name if Is_Full_Name
(Directory) is True; result is a relative name otherwise.
Implementation Advice
Directories.Hierarchical_File_Names should be provided
for systems with hierarchical file naming, and should not be provided
on other systems.
NOTE 1 These operations operate on
file names, not external files. The files identified by these operations
do not necessarily exist. Name_Error is raised only as specified or if
the file name is malformed and cannot possibly identify a file. The result
of these operations depends only on their parameters.
NOTE 2 Containing_Directory raises
Use_Error if Name does not have a containing directory, including when
any of Is_Simple_Name, Is_Root_Directory_Name, Is_Parent_Directory_Name,
or Is_Current_Directory_Name are True.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
