Ada Reference Manual (Ada 2022)

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.