Ada Reference Manual (Ada 2022) — Legal Information

# A.16.1 The Package Directories.Hierarchical_File_Names

1/3
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

2/3
If provided, the library package Directories.Hierarchical_File_Names has the following declaration:
3/5
package Ada.Directories.Hierarchical_File_Names
with Nonblocking, Global => in out synchronized is
4/3
function Is_Simple_Name (Name : in String) return Boolean;
5/3
function Is_Root_Directory_Name (Name : in String) return Boolean;
6/3
function Is_Parent_Directory_Name (Name : in String) return Boolean;
7/3
function Is_Current_Directory_Name (Name : in String) return Boolean;
8/3
function Is_Full_Name (Name : in String) return Boolean;
9/3
function Is_Relative_Name (Name : in String) return Boolean;
10/3
function Simple_Name (Name : in String) return String
renames Ada.Directories.Simple_Name;
11/3
function Containing_Directory (Name : in String) return String
renames Ada.Directories.Containing_Directory;
12/3
function Initial_Directory (Name : in String) return String;
13/3
function Relative_Name (Name : in String) return String;
14/3
function Compose (Directory : in String := "";
Relative_Name : in String;
Extension : in String := "") return String;
15/3
end Ada.Directories.Hierarchical_File_Names;
16/3
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.
17/3
function Is_Simple_Name (Name : in String) return Boolean;
18/3
Returns True if Name is a simple name, and returns False otherwise.
19/3
function Is_Root_Directory_Name (Name : in String) return Boolean;
20/3
Returns True if Name is syntactically a root (a directory that cannot be decomposed further), and returns False otherwise.
21/3
function Is_Parent_Directory_Name (Name : in String) return Boolean;
22/3
Returns True if Name can be used to indicate symbolically the parent directory of any directory, and returns False otherwise.
23/3
function Is_Current_Directory_Name (Name : in String) return Boolean;
24/3
Returns True if Name can be used to indicate symbolically the directory itself for any directory, and returns False otherwise.
25/3
function Is_Full_Name (Name : in String) return Boolean;
26/3
Returns True if the leftmost directory part of Name is a root, and returns False otherwise.
27/3
function Is_Relative_Name (Name : in String) return Boolean;
28/3
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.
29/3
function Initial_Directory (Name : in String) return String;
30/3
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).
31/3
function Relative_Name (Name : in String) return String;
32/3
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).
33/3
function Compose (Directory : in String := "";
Relative_Name : in String;
Extension : in String := "") return String;
34/3
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.
35/3
The result of Compose is a full name if Is_Full_Name (Directory) is True; result is a relative name otherwise.

#### Implementation Advice

36/3
Directories.Hierarchical_File_Names should be provided for systems with hierarchical file naming, and should not be provided on other systems.
37/5
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.
38/3
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