CVS difference for ai05s/ai05-0049-1.txt
--- ai05s/ai05-0049-1.txt 2010/02/23 04:10:50 1.4
+++ ai05s/ai05-0049-1.txt 2010/04/08 02:00:06 1.5
@@ -1,5 +1,9 @@
-!standard A.16(82/2) 10-02-22 AI05-0049-1/02
+!standard A.16(20/2) 10-04-06 AI05-0049-1/03
+!standard A.16(82/2)
+!standard A.16.1(0)
!class Amendment 07-04-10
+!status Amendment 2012 10-04-06
+!status ARG Approved 9-0-1 10-02-26
!status work item 07-04-10
!status received 07-02-28
!priority Medium
@@ -46,15 +50,6 @@
!wording
-[Editor's note: I removed "Fragments" and "Relative indicators" in an
-attempt to improve the terminology as requested. I kept "Relative_Name"
-as we need a term to be the counterpart of "Full_Name" and "Simple_Name".
-It is more typical to talk about "absolute paths" and "relative paths",
-but since these functions work both on paths and on file names (and make
-no differentiation between them), it would be confusing to use those
-terms. (To do so we'd have to abandon the entire model of the existing
-Ada.Directories; that would be too disruptive in my view.)]
-
Add after A.16(20/2) (in Ada.Directories):
type Name_Case_Kind is (Unknown, Case_Sensitive, Case_Insensitive,
@@ -71,21 +66,21 @@
file names that differ only in the case of letters are considered different
names. If file names that differ only in the case of letters are considered
the same name, then Case_Preserving is returned if the name has the case
- of the file name when a file is created; and Case_Insensitive otherwise.
- Returns Unknown if it is not known which answer is correct.
+ of the file name used when a file is created; and Case_Insensitive otherwise.
+ Returns Unknown if the file name equivalence is not known.
AARM Note: Unix, Linux, and its relatives are Case_Sensitive systems.
-Windows is a Case_Preserving system. Ancient systems like CP/M and early
-MS-DOS were Case_Insensitive systems (file names were always in UPPER CASE).
-Unknown is provided in case it is impossible to tell (such as could be the
-case for network files).
+Windows is a Case_Preserving system (unless the rarely used POSIX mode is used).
+Ancient systems like CP/M and early MS-DOS were Case_Insensitive systems
+(file names were always in UPPER CASE). Unknown is provided in case it is
+impossible to tell (such as could be the case for network files).
Add a new clause A.16.1:
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
+providing operations for file name construction and decomposition for
targets with hierarchical file naming.
Static Semantics
@@ -97,7 +92,7 @@
function Is_Simple_Name (Name : in String) return Boolean;
- function Is_Root_Directory (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;
@@ -106,96 +101,123 @@
function Is_Full_Name (Name : in String) return Boolean;
function Is_Relative_Name (Name : in String) return Boolean;
-
- function Full_Name (Name : in String) return String;
- function Simple_Name (Name : in String) return String;
+ function Simple_Name (Name : in String) return String
+ renames Ada.Directories.Simple_Name;
- function Containing_Directory (Name : in String) return String;
+ 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 Extension (Name : in String) return String;
-
- function Base_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, operations in package Directories
+can be used. In particular, functions Full_Name, Base_Name, and Extension are
+usable with hierarchical file names.
-[Editor's note: The following doesn't have the correct format for this
-wording. The reorganization is mechanical, so I didn't do it until we've
-reviewed this version.]
+ function Is_Simple_Name (Name : in String) return Boolean;
-Is_Simple_Name returns True if Name is a simple name. Is_Root_Directory returns True
-if Name is syntactically a root (a directory that cannot be decomposed further).
+ Returns True if Name is a simple name, and returns False otherwise.
-AARM Note: For Unix, "/" is the root. For Windows, "C:\" and "\\Computer\Share"
-are roots.
+ function Is_Root_Directory_Name (Name : in String) return Boolean;
-Is_Parent_Directory_Name returns True if Name indicates the parent directory of
-any directory, and False otherwise.
+ Returns True if Name is syntactically a root (a
+ directory that cannot be decomposed further), and returns False otherwise.
-AARM Note: Is_Parent_Directory_Name returns True if and only if Name is ".." for
+AARM Implementation Note: For Unix and Unix-like systems, "/" is the root. For Microsoft
+Windows, "C:\" and "\\Computer\Share" are roots.
+
+ function Is_Parent_Directory_Name (Name : in String) return Boolean;
+
+ Returns True if Name indicates the parent directory of any directory, and
+ returns False otherwise.
+
+AARM Implementation Note: Is_Parent_Directory_Name returns True if and only if Name is ".." for
both Unix and Windows.
-Is_Current_Directory_Name returns True if Name indicates the current directory for
-any directory, and False otherwise.
+ function Is_Current_Directory_Name (Name : in String) return Boolean;
-AARM Note: Is_Current_Directory_Name returns True if and only if Name is "." for
+ Returns True if Name indicates the current directory for any directory,
+ and returns False otherwise.
+
+AARM Implementation Note: Is_Current_Directory_Name returns True if and only if Name is "." for
both Unix and Windows.
+
+ 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;
-Is_Full_Name is true if the leftmost directory part of Name is a root.
-Is_Relative_Name is true if Name has proper syntax but is not a full name.
+ Returns True if Name has proper syntax but is not a full name, and
+ returns False otherwise.
-AARM Note: Relative names include simple names as a special case.
+AARM Ramification: Relative names include simple names as a special case.
-Full_Name, Simple_Name, Extension, and Base_Name work the same as they do in
-Ada.Directories.
+ function Initial_Directory (Name : in String) return String;
-Containing_Directory returns the Containing_Directory; it raises Use_Error
-if Name does not identify a containing directory (this includes if
-any of Is_Simple_Name, Is_Root_Directory, Is_Parent_Directory_Name, or
-Is_Current_Directory_Name are True).
+ Initial_Directory returns the leftmost directory part in Name.
+ Redundant[That is 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).
-Initial_Directory returns the leftmost directory part in Name. (That is
-generally a root (for a full name), or one of a parent directory name,
-a current directory name, or a simple name (for a relative name)).
+ function Relative_Name (Name : in String) return String;
-Relative_Name returns the entire name except the Initial_Directory portion;
-it raises Name_Error if Name does not identify a file name or has a
-single part (this includes if any of Is_Simple_Name, Is_Root_Directory,
-Is_Parent_Directory_Name, or Is_Current_Directory_Name are True).
+ Relative_Name 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).
-AARM Note: This might be a simple name.
+AARM Note: The result might be a simple name.
+
+ function Compose (Directory : in String := "";
+ Relative_Name : in String;
+ Extension : in String := "") return String;
-All of the above non-predicates raise Name_Error if the name cannot be
-interpreted as a file name.
+ 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
+ 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.
+
+ [Editor's note: We don't have Is_Base_Name anywhere, so I can't use
+ it in the wording. I'd prefer "Is_Base_Name (Simple_Name (Relative_Name)
+ is False".]
-Compose combines the Directory, Relative_Name, and Extension. The Relative_Name
-cannot be a full name, else Name_Error is raised.
-The Directory can be any sort of name, but Name_Error is raised if
-all six predicates would return False. The extension has to represent
-an extension (if not null), else Name_Error is raised.
+ The result of Compose is a full name if Is_Full_Name (Directory) is True;
+ result is a relative name otherwise.
-The result of Compose is a full name if Directory is a Full_Name (including
-a root directory). The result of Compose is a relative name otherwise.
+AARM Ramification: Name_Error is raised by Compose if Directory is not the
+null string, and both Is_Full_Name and Is_Relative_Name return False.
-AARM Note: A common security problem is to include a parent directory
+AARM Discussion: A common security problem is to include a parent directory
name in the middle of a file name; this is often used to navigate outside
of an intended root directory. We considered attempting to prevent that
case by having Compose detect it and raise an exception. But the extra
rules necessary were more confusing than helpful.
-We can say more about the details of these operations by adopting the notation of
-a subscript to specify how many path fragments a particular result has.
+We can say more about the details of these operations by adopting the notation
+of a subscript to specify how many path fragments a particular result has.
Then, we can abbreviate "Full Name" as "Full" and "Relative Name" as "Rel".
-In this notation, "a/b" is a Rel(2), "../c/d" is a Rel(3), and "/a/b" is
-a Full(2) [for Unix]. Rel(1) is equivalent to a simple name; thus we
+In this notation, Unix file name "a/b" is a Rel(2), "../c/d" is a Rel(3),
+and "/a/b" is a Full(2). Rel(1) is equivalent to a simple name; thus we
don't have to describe that separately.
In this notation,
@@ -214,10 +236,9 @@
Compose (Directory => Full(N), Relative_Name => Rel(M)) => Full(N+M)
Compose (Directory => Rel(N), Relative_Name => Rel(M)) => Rel(N+M)
- Name_Error is Relative_Name is a Full(M).
+ Name_Error if Relative_Name is a Full(M).
-We didn't try to write wording to reflect these rules, but this is the
-intent.
+We didn't try to write wording to reflect the details of these rules.
End AARM Notes.
Implementation Advice
@@ -225,10 +246,10 @@
Directories.Hierarchical_File_Names should be provided for systems with
hierarchical file naming, and should not be provided on other systems.
-AARM Note: This package should be provided on Microsoft Windows, Unix,
-Linux, and most Unix-like systems.
+AARM Implementation Note: This package should be provided on
+Microsoft Windows, Unix, Linux, and most Unix-like systems.
-[Editor: The following is a user note, similar to A.16(127/2).]
+[Editor: The following are user notes, the first is similar to A.16(127/2).]
NOTES: These operations operate on file names, not external files. The
files identified by these operations do not need to exist. Name_Error is
@@ -236,11 +257,16 @@
possibly identify a file. The result of these operations depends only
on their parameters.
+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.
+
+
!discussion
The generalized Compose routine provides the solution to problem (1).
-The function Is_Root_Directory provides the solution to problem (2).
+The function Is_Root_Directory_Name provides the solution to problem (2).
The function Name_Case_Equivalence provides some assistance to problem (3).
@@ -266,6 +292,173 @@
!example
+!corrigendum A.16(20/2)
+
+@dinsa
+@xcode<@b<function> Compose (Containing_Directory : @b<in> String := "";
+ Name : @b<in> String;
+ Extension : @b<in> String := "") @b<return> String;>
+@dinss
+@xcode<@b<type> Name_Case_Kind @b<is> (Unknown, Case_Sensitive, Case_Insensitive,
+ Case_Preserving);>
+
+@xcode<@b<function> Name_Case_Equivalence (Name : @b<in> String) @b<return> Name_Case_Kind;>
+
+!corrigendum A.16(82/2)
+
+@dinsa
+@xindent<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).>
+@dinss
+@xcode<@b<function> Name_Case_Equivalence (Name : @b<in> String) @b<return> Name_Case_Kind;>
+
+@xindent<Returns the file name equivalence rule for the directory containing
+Name. Raises Name_Error if Name is not a full name. Returns Case_Sensitive if
+file names that differ only in the case of letters are considered different
+names. If file names that differ only in the case of letters are considered the
+same name, then Case_Preserving is returned if the name has the case of the file
+name used when a file is created; and Case_Insensitive otherwise. Returns
+Unknown if the file name equivalence is not known.>
+
+AARM Note: Unix, Linux, and its relatives are Case_Sensitive systems.
+Windows is a Case_Preserving system (unless the rarely used POSIX mode is used).
+Ancient systems like CP/M and early MS-DOS were Case_Insensitive systems
+(file names were always in UPPER CASE). Unknown is provided in case it is
+impossible to tell (such as could be the case for network files).
+
+@corrigendum A.16.1(1)
+
+@dinsc
+
+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.
+
+@i<@s8<Static Semantics>>
+
+If provided, the library package Directories.Hierarchical_File_Names has
+the following declaration:
+
+@xcode<@b<package> Ada.Directories.Hierarchical_File_Names @b<is>
+
+ @b<function> Is_Simple_Name (Name : @b<in> String) @b<return> Boolean;
+
+ @b<function> Is_Root_Directory_Name (Name : @b<in> String) @b<return> Boolean;
+
+ @b<function> Is_Parent_Directory_Name (Name : @b<in> String) @b<return> Boolean;
+
+ @b<function> Is_Current_Directory_Name (Name : @b<in> String) @b<return> Boolean;
+
+ @b<function> Is_Full_Name (Name : @b<in> String) @b<return> Boolean;
+
+ @b<function> Is_Relative_Name (Name : @b<in> String) @b<return> Boolean;
+
+ @b<function> Simple_Name (Name : @b<in> String) @b<return> String
+ @b<renames> Ada.Directories.Simple_Name;
+
+ @b<function> Containing_Directory (Name : @b<in> String) @b<return> String
+ @b<renames> Ada.Directories.Containing_Directory;
+
+ @b<function> Initial_Directory (Name : @b<in> String) @b<return> String;
+
+ @b<function> Relative_Name (Name : @b<in> String) @b<return> String;
+
+ @b<function> Compose (Directory : @b<in> String := "";
+ Relative_Name : @b<in> String;
+ Extension : @b<in> String := "") @b<return> String;
+
+@b<end> Ada.Directories.Hierarchical_File_Names;>
+
+In addition to the operations provided in package
+Directories.Hierarchical_File_Names, operations in package Directories
+can be used. In particular, functions Full_Name, Base_Name, and Extension are
+usable with hierarchical file names.
+
+@xcode<@b<function> Is_Simple_Name (Name : @b<in> String) @b<return> Boolean;>
+
+@xindent<Returns True if Name is a simple name, and returns False otherwise.>
+
+@xcode<@b<function> Is_Root_Directory_Name (Name : @b<in> String) @b<return> Boolean;>
+
+@xindent<Returns True if Name is syntactically a root (a directory that cannot
+be decomposed further), and returns False otherwise.>
+
+@xcode<@b<function> Is_Parent_Directory_Name (Name : @b<in> String) @b<return> Boolean;>
+
+@xindent<Returns True if Name indicates the parent directory of any directory,
+and returns False otherwise.>
+
+@xcode<@b<function> Is_Current_Directory_Name (Name : @b<in> String) @b<return> Boolean;>
+
+@xindent<Returns True if Name indicates the current directory for any directory,
+and returns False otherwise.>
+
+@xindent<@b<function> Is_Full_Name (Name : @b<in> String) @b<return> Boolean;>
+
+@xindent<Returns True if the leftmost directory part of Name is a root, and
+returns False otherwise.>
+
+@xcode<@b<function> Is_Relative_Name (Name : @b<in> String) @b<return> Boolean;>
+
+@xindent<Returns True if Name has proper syntax but is not a full name, and
+returns False otherwise.>
+
+@xcode<@b<function> Initial_Directory (Name : @b<in> String) @b<return> String;>
+
+@xindent<Initial_Directory returns the leftmost directory part in Name.
+That is 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).>
+
+@xcode<@b<function> Relative_Name (Name : @b<in> String) @b<return> String;>
+
+@xindent<Relative_Name 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).>
+
+@xcode<@b<function> Compose (Directory : @b<in> String := "";
+ Relative_Name : @b<in> String;
+ Extension : @b<in> String := "") @b<return> String;>
+
+@xindent<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 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.>
+
+@xindent<The result of Compose is a full name if Is_Full_Name (Directory) is
+True; result is a relative name otherwise.>
+
+@i<@s8<Implementation Advice>>
+
+Directories.Hierarchical_File_Names should be provided for systems with
+hierarchical file naming, and should not be provided on other systems.
+
+@xindent<@s9<NOTES:@hr
+42 These operations operate on file names, not external files. The
+files identified by these operations do not need to 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.
+@hr
+43 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.>>
+
+
!ACATS test
Create an ACATS test to check that the above new facilities work.
@@ -396,22 +589,22 @@
> want to create fully portable names, then you have to parse the URL into
> simple names and use Compose to build that into a path. In your example, you
> would end up with:
->
+>
> Full_Path : constant String := Compose (Compose ("/tmp", "public"),
> "file.txt");
->
+>
> The design of the operations is intended to make it hard to abuse the
> facilities to make a seemingly portable program that is not.
-However, this contains '/', and so is still not portable. As there's no
-way to obtain the root directory, there doesn't seem to be a portable
+However, this contains '/', and so is still not portable. As there's no
+way to obtain the root directory, there doesn't seem to be a portable
way to do this.
> Sounds OK as an Amendment suggestion, but of course I have no idea when
> we'll be seriously considering them again. In the mean time, you'll just
> have to handle the exception.
-My guess is 2011 for suggestions for the next TC, and 2016 for the next
+My guess is 2011 for suggestions for the next TC, and 2016 for the next
major version.
****************************************************************
@@ -419,7 +612,7 @@
From: Pascal Obry
Sent: Wednesday, March 28, 2007 3:21 AM
->
+>
> But you're abusing the file name construction functions here. The intent is
No, this was meant to be a simple example. Of course "/tmp" is in a
Questions? Ask the ACAA Technical Agent