CVS difference for ais/ai-00262.txt

Differences between 1.7 and version 1.8
Log of other versions for file ais/ai-00262.txt

--- ais/ai-00262.txt	2001/06/02 04:13:15	1.7
+++ ais/ai-00262.txt	2001/06/05 00:03:27	1.8
@@ -1,4 +1,4 @@
-!standard 10.01.02 (04)                               01-02-15  AI95-00262/01
+!standard 10.01.02 (04)                               01-06-04  AI95-00262/02
 !standard 10.01.02 (08)
 !class amendment 01-02-15
 !status work item 01-02-15
@@ -9,6 +9,9 @@
 
 !summary
 
+The context clause "private with" makes a unit available only in the private
+part of a package.
+
 !problem
 
 The private part of a package includes part of the implementation of the
@@ -37,20 +40,146 @@
 All of this bending of the design was necessary because private packages
 could not be used in the private part of a public package.
 
-
 !proposal
+
+We propose that the qualifier "private" is optionally added to with_clauses.
+A library unit mentioned in a with_clause including the "private" qualifier
+cannot be referenced in the visible part of the package. Otherwise, the
+processing of with clauses is unchanged.
+
+!wording
+
+Change 10.1.2(4):
 
-(* Either "with private", or a separate compilation scheme for private parts;
-see appendix for rough proposals of each *)
+    with_clause ::= [private] with library_unit_name {, library_unit_name}
 
+Change 10.1.2(8):
+
+If a with_clause of a given compilation_unit mentions a private child of some
+library unit, then the given compilation_unit shall be one of:
+    * the declaration of a private descendant of that library unit;
+    * the body or subunit of a (public or private) descendant of that
+      library unit; or
+    * the declaration of a public descendant of that library unit, and
+      the with_clause shall include the reserved work private.
+
+Add after 10.1.2(8):
+
+In the visible part of a package or generic package, a name shall not denote
+a library unit named only in a with_clause which includes the reserved word
+private.
+
 !discussion
 
+Private withs do not allow access to the library unit in the visible part of
+the package or generic package. This rule is necessary to preserve the purpose
+of 10.1.2(8): To prevent a private child from being visible (or even
+semantically depended-on) from outside the subsystem rooted at its
+parent. [AARM 10.1.2(8.a)] This limitation has the pleasant side effect of
+adding another capability beyond that described in the problem statement: it
+allows the declaration that a unit of any sort) will not be used in the public
+part of a package. This additional documentation can be valuable to both users
+and automated analysis tools. Some reviewers consider this capability more
+important than withing private units.
+
+Reference to private withed items in the private part is a legality rule,
+rather than a visibility rule, in order to avoid a form of Beaujolais when
+a declaration is moved from the visible part to the private part (or
+vice-versa). Since such moves are common, it is important to avoid them.
+With the legality rule, the declarations will be illegal in the public part.
+
+For example:
+
+package A is
+    function B return Integer;
+end A;
+
+function B return Integer;
+
+with A;
+private with B;
+package C is
+    use A;
+    V1 : Integer := B; -- (1)
+private
+    V2 : Integer := B; -- (2)
+end C;
+
+If we use a visibility rule saying that library subprogram B is not in scope
+in the visible part of C, then the B at (1) resolves to A.B, while (2)
+resolves to library unit B. Simply moving a declaration could silently change
+its meaning: a classic Beaujolais effect.
+
+With the legality rule as proposed, the B at (1) is illegal. If the user meant
+A.B, they can still say that.
+
+Private withs are allowed on bodies. They are equivalent to regular withs
+there. We could make them illegal on bodies, but there doesn't seem to be any
+value to doing that.
+
+Ada allows a unit to be withed multiple times in a single context clause.
+In order to handle this, we have proposed that the legality rule is written
+so that if a unit is withed by both a regular with and a private with, the
+legality rule does not apply. Alternatively, we could have made such a
+combination illegal. But that doesn't seem to buy much, and it adds an
+additional new check.
 
 !example
 
+As described in the problem statement, the low-level Win32 interface for Claw
+are defined in a series of private packages. However, Ada 95 prevents these
+packages from being accessed in the private part of the public types. The
+proposed feature eliminates that problem.
+
+The low-level interface for an image list package might look like:
+
+    package Claw.Low_Level_Image_Lists is
+        type HImage_List is new DWord;
+        type IL_Flags is new UInt;
+        ILR_DEFAULTCOLOR : constant IL_Flags := 16#0000#;
+        ILR_MONOCHROME   : constant IL_Flags := 16#0001#;
+         ...
+        type Image_Kind_Type is (Bitmap, Icon, Cursor);
+        for Image_Kind_Type use (Bitmap => 0, Icon => 1, Cursor => 2);
+
+        function Image_List_Load_Image (
+                  Name     : in Claw.Win32.LPCStr;
+                  Width    : in Claw.Int;
+                  Image_Kind : in Image_Kind_Type;
+                  Flags    : in IL_Flags) return HImage_List;
+        pragma Import (StdCall, Image_List_Load_Image,
+                  "ImageList_LoadImageA");
+
+          ...
+    end Claw.Low_Level_Image_Lists;
+
+
+The high-level interface for the image list package might look like:
+
+    private with Claw.Low_Level_Image_Lists;
+    package Claw.Image_List is
+       type Image_List_Type is tagged private;
+       procedure Load_Image (Image_List : in out Image_List_Type;
+                             Image : in String;
+			     Monochrome : in Boolean := False);
+         ...
+    private
+       type Image_List_Type is tagged record
+	Handle : Claw.Low_Level_Image_Lists.HImage_List;
+            Flags : Claw.Low_Level_Image_Lists.IL_Flags;
+              ...
+       end record;
+    end Claw.Image_List;
+
+A reference to Claw.Low_Level_Image_Lists would still be illegal in the visible
+part of Claw.Image_List.
 
 !ACATS test
 
+A C-Test should be created to check that a private child can be private withed
+into a sibling unit. A B-Test should be created to check that a private withed
+library unit cannot be named in the visible part of a package or generic
+package.
 
 !appendix
 

Questions? Ask the ACAA Technical Agent