!standard 4.10(0) 18-06-06 AI12-0020-1/03 !standard 3.5(27.1/2) !standard 3.5(55.1/5) !standard 3.5(55.2/5) !standard 3.5(55.3/5) !standard 3.5(55.4/5) !standard 13.13.1(9) !standard 13.13.1(11) !class Amendment 12-02-14 !status work item 12-02-14 !status received 11-10-13 !priority Medium !difficulty Medium !subject 'Image for all types !summary Define T'Put_Image for all types, and redefine T'Image, T'Wide_Image, and T'Wide_Wide_Image in terms of it. (This provides a default image for objects of all types.) !problem Ada only provides 'Image for scalar types. However, for debugging in particular, an easy way to view an object of any type is useful. !proposal T'Image is defined for all non-abstract types (including class-wide types). Ditto for T'Wide_Image and T'Wide_Wide_Image. All of these are defined in terms of T'Put_Image, a stream-like attribute with the specification: S'Put_Image (Arg : T; Stream : access Counted_Stream'Class); Like streams, this routine can be specified for any type to give a user-defined image for that type. Also like streams, this routine is inherited by derived types (although it is always available, unlike stream attributes). Default implementation: For scalars - unchanged. For access types - Integer value displayed as a hex digits in square brackets, except null displayed as "NULL". Number of hex digits determined by size of access type. For example, "[FF0012AC]". For task types - Undiscriminated: "(TASK )" Discriminated: "(TASK with D1 => 123, D2 => 456)" For protected types - Nothing special. Same as any record type. Protected_Obj'Image is a protected function (this matters, for example, for locking). For all other composite types: Named aggregate syntax is used; only white space is a single blank after "," and both before and after "=>". This can result in double blanks in some cases, as in "(Field => 123)" where the second blank comes from the image of the component value. For all record types: Record component names in upper case (same as existing rule for 'Image of enumeration values). Record component ordering follows positional aggregate rules. For type extensions: By default we treat a type extension the same as any other record type. This may involve (in corner cases) having multiple components with the same component name, but that's ok because the order disambiguates. However, if an ancestor type has a user-defined Put_Image attribute, we use extension aggregate syntax, as in "( with C1 => 123, C2 => 4.5)" . It would have been more regular to always use extension-aggregate syntax but the result would be less readable, especially for deep hierarchies. For class-wide types, the image obtained from the specific type is prefixed with the Wide_Wide_Expanded_Name of the tag and a "'", yielding qualified expression syntax, as in "My_Pkg.My_Tagged_Type'(ABC => True, DEF => 123.45)" For array types: Array index names generated via image. Null arrays displayed as "(1 .. 0 => <>)" or "(1 .. 0 => (1 .. 10 => <>))" Null records displayed as "(NULL RECORD)". There is no special treatment for string types. !wording We are going to define Image and related attributes for (almost) all types and objects, so we begin by deleting the existing definitions which are specific to scalars. Delete 3.5(27.1/2 - 37.a/2, 55.1/5-55.4/4) In 3.5(37.12, 38, and 39), replace the three occurrences of "over all values of the subtype S" with "over all values of the subtype S, assuming a default implementation of S'Put_Image". In 3.5(43/3 and 55/3), replace the two occurrences of "(or corresponds to the result of S'Image for a value of the type)" with "(or corresponds to the result of S'Image for a value of the type, assuming a default implementation of S'Put_Image)". ==== Add a new subclause 4.10 Images For every subtype S of a non-universal type T, the following type-related operational attributes are defined: S'Put_Image S'Put_Image denotes a procedure with the following specification: S'Put_Image (Arg : T; Stream : access Counted_Stream'Class); The default implementation of S'Put_Image writes out (using Wide_Wide_String'Write and or Wide_Wide_String'Output) an image of the value of Arg; that is, a Wide_Wide_String representing the value in display form. This is described in more detail later in this section. The Put_Image attribute may be specified for any specific type T either via an attribute_definition_clause or via an aspect_specification specifying the Put_Image aspect of the type. AARM Note: In contrast, the Image, Wide_Image, and Wide_Wide_Image attributes and their associated aspects may not be specified. The behavior of any of these attributes is defined in terms of calls to the corresponding Put_Image procedure, so changes in their behavior may be accomplished via a Put_Image specification. S'Wide_Wide_Image S'Wide_Wide_Image denotes a function with the following specification: function S'Wide_Wide_Image (Arg : S'Base) return Wide_Wide_String The implementation of S'Wide_Wide_Image calls S'Put_Image (which will typically write a sequence of Wide_Wide_Character values out to a stream) and then returns the result of reading the contents of that stream; the lower bound of that result is 1. More specifically, it is equivalent to function T'Wide_Wide_Image (Arg : T) return Wide_Wide_String is Local_Stream : aliased Ada.Streams.Counted_Streams.Unbounded.Unbounded_Stream; -- see 13.13.1 Elements_Per_Char : constant := Wide_Wide_Character'Stream_Size / Stream_Element'Size; -- typically 4 begin T'Put_Image (Arg, Local_Stream'Access); return Result : Wide_Wide_String (1 .. (Element_Count (Local_Stream) + (Elements_Per_Char - 1)) / Elements_Per_Char) do Wide_Wide_String'Read (Result, Local_Stream'Access); end return; end; except that if the value of T'Max_Image_Elements (see below) is not -1 then the variable Local_Stream is instead declared as Local_Stream : aliased Ada.Streams.Counted_Streams.Unbounded.Unbounded_Stream (Max_Elements => T'Max_Image_Elements); -- see 13.13.1 . S'Wide_Image S'Wide_Image denotes a function with the following specification: function S'Wide_Image (Arg : T) return Wide_String The function returns an image of the value of Arg as a Wide_String. The lower bound of the result is one. The image has the same sequence of graphic characters as defined for S'Wide_Wide_Image if all the graphic characters are defined in Wide_Character; otherwise, the sequence of characters is implementation defined (but no shorter than that of S'Wide_Wide_Image for the same value of Arg). S'Image S'Image denotes a function with the following specification: function S'Image(Arg : S'Base) return String The function returns an image of the value of Arg as a String. The lower bound of the result is one. The image has the same sequence of graphic characters as that defined for S'Wide_Wide_Image if all the graphic characters are defined in Character; otherwise, the sequence of characters is implementation defined (but no shorter than that of S'Wide_Wide_Image for the same value of Arg). S'Max_Image_Elements S'Max_Image_Elements yields the value of T's Max_Image_Elements aspect. The type of both the aspect and the attribute is Ada.Streams.Stream_Offset. The Max_Image_Elements attribute may be specified for any type type T either via an attribute_definition_clause, via an an aspect_specification specifying the Put_Image aspect of the type, or (in the case of a derived type) via inheritance. If specified, the aspect_definition shall be a static expression in the range -1 .. Ada.Streams.Stream_Element_Offset'Last. If no value for the aspect is specified, then value of the aspect is determined by any Default_Max_Image_Elements pragmas (described below) which are applicable to the compilation unit in which T's full declaration occurs, if any such pragmas exist. If no value for the aspect is specified and no such pragma exists, then the value of the aspect is -1. Pragma Default_Max_Image_Elements is a configuration pragma which takes a single argument, a static expression of type Ada.Streams.Stream_Offset in the range -1 .. Ada.Streams.Stream_Element_Offset'Last. Pragma Default_Max_Image_Elements shall not be used other than as a configuration pragma. If more than one Default_Max_Image_Elements pragma applies to a given compilation unit, then they shall all specify equal (static) Stream_Element_Offset values. The behavior of the default implementation of S'Put_Image depends on the class of T. For an elementary type, the implementation is equivalent to procedure Put_Image (Arg : Scalar_Type; Stream : access Counted_Stream'Class) is begin Wide_Wide_String'Write (, Stream) end; where the Wide_Wide_String value written out to the stream is defined as follows: AARM Discussion: In earlier versions of Ada, Image and related attributes were defined only for scalar types. The definition of these attributes is now textually very different, but it is intended that there should be no change in the behavior of existing programs as a result of these changes. End AARM Discussion. For an integer type, the image written out is the corresponding decimal literal, without underlines, leading zeros, exponent, or trailing spaces, but with a single leading character that is either a minus sign or a space. For an enumeration type, the image written out is either the corresponding identifier in upper case or the corresponding character literal (including the two apostrophes); neither leading nor trailing spaces are included. For a nongraphic character (a value of a character type that has no enumeration literal associated with it), the value is a corresponding language-defined name in upper case (for example, the image of the nongraphic character identified as nul is “NUL” — the quotes are not part of the image). For a floating point type, the image written out is a decimal real literal best approximating the value (rounded away from zero if halfway between) with a single leading character that is either a minus sign or a space, a single digit (that is nonzero unless the value is zero), a decimal point, S'Digits–1 (see 3.5.8) digits after the decimal point (but one if S'Digits is one), an upper case E, the sign of the exponent (either + or –), and two or more digits (with leading zeros if necessary) representing the exponent. If S'Signed_Zeros is True, then the leading character is a minus sign for a negatively signed zero. For a fixed point type, the image written out is a decimal real literal best approximating the value (rounded away from zero if halfway between) with a single leading character that is either a minus sign or a space, one or more digits before the decimal point (with no redundant leading zeros), a decimal point, and S'Aft (see 3.5.10) digits after the decimal point. For an access type (named or anonymous), the image written out depends on whether the value is null. If it is null, then the image is "NULL". Otherwise the image is a sequence of uppercase hexadecimal digits representing the value enclosed in square brackets, as in "[FF0012AC]". The number of hexadecimal digits will be the same for all non-null values of any one access type. [In general, the default implementation of T'Put_Image for a composite type will involve some sequence of calls to Wide_Wide_String'Write and calls to the Put_Image procedures of component types and, in the case of an array type, index types. The Wide_Wide_String'Write calls may pass in either literal values (e.g., "(", ")", "'(", " => ", or ", "), or other things (such as component names for record values, task_id images for tasks, or the Wide_Wide_Expanded_Name of the tag in the class-wide case).] For an array type T, the default implementation of T'Put_Image generates an image based on (named, not positional) array aggregate syntax using calls to the Put_Image procedures of the index type(s) and the element type to generate images for values of those type. This might generate an image such as "( 1 => ( 1 => ( 123 => True, 124 => False), 2 => ( 123 => False, 124 => False)), 2 => ( 1 => ( 123 => True, 124 => True), 2 => ( 123 => True, 124 => False)))" . The case of a null array is handled specially, using ranges for index bounds and "<>" as a syntactic component-value placeholder. This might generate an image such as "( 1 .. 3 => ( 1 .. 0 => ( 1 .. 5 => <>))), where the use of "<>" (among other things) indicates that the array argument is a null array. The the order in which components are written for a composite type is the same canonical order in which, for example, components of a composite type T are written out by the default implementation of T'Write. [This is also the order that is used in determining the meaning of a positional aggregate of type T.] For a class-wide type, the default implementation of T'Put_Image generates an image based on qualified expression syntax. Wide_Wide_String'Write is called with Wide_Wide_Expanded_Name of Arg'Tag. Next the literal "'(" is written out. Then Corresponding_Specific_Type'Put_Image is called. [At the implementation level this will typically require a dispatching call.] Finally a right parenthesis is written. This might generate an image such as "SOME_PACKAGE.SOME_TAGGED_TYPE'(COMPONENT_1 => 123, COMPONENT_2 => 456)" . For a (specific) type extension, the default implementation of T'Put_Image depends on whether there exists a non-interface ancestor of T (other than T itself) for which the Put_Image aspect has been [explicitly] specified. If so, then T'Put image will generate an image based on extension aggregate syntax where the ancestor type of the extension aggregate is the nearest ancestor type whose Put_Aspect has been specified. [This might generate an image such as "(This Text Was User-Generated with C1 => 123, C2 => 456)" where the "This Text was User-Generated" portion of the text was generated by the call to the user-specified Put_Image routine.] If no such ancestor exists, then the default implementation of T'Put_Image is the same as described below for an untagged record type. For an untagged record type, a specific tagged record type other than a type extension which meets the criteria described in the previous paragraph, or a protected type, the default implementation of T'Put_Image generates an image based on (named, not positional) record aggregate syntax. Component names are displayed in upper case, following the rules for the image of an enumeration value. Component values are displayed via calls to the component type's Put_Image procedure. This might generate an image such as "(FOO => ( 1 => 'c', 2 => 'a', 3 => 't'), BAR => TRUE)". The image written out for a record having no components (including any interface type) is "(NULL RECORD)". In the case of a protected type T, a call to the default implementation of T'Put_Image begins only one protected (readonly) action. [AARM Implementation Note: The expected, but not required, implementation model for generating the image of a protected record involves the compiler producing a "helper" protected function which T'Put_Image would call. The result type of this function might be a null record; it is only a function because it does not need a write-lock, not because it returns a meaningful result.] [TBH - Note that the assertion in the following example should succeed: type T1 (D1, D2 : Positive) is record ... end record; -- untagged type T2 (D : Positive) is new T1 (D1 => D, D2 => D); X : T2 (D => 123) := ... ; pragma Assert (X'Image /= T1(X)'Image);] For an undiscriminated task type, the default implementation of T'Put_Image generates an image of the form "(TASK )" where is the result obtained by calling Ada.Task_Identification.Image with the id of the given task. For a discriminated task type, the default implementation of T'Put_Image also includes discriminant values, as in "(TASK with D1 => 123, D2 => 456)". For a prefix X that denotes an object of a non-universal type T, the following attributes are defined: X'Wide_Wide_Image X'Wide_Wide_Image denotes the result of calling function S'Wide_Wide_Image with Arg being X, where S is the nominal subtype of X. X'Wide_Image X'Wide_Image denotes the result of calling function S'Wide_Image with Arg being X, where S is the nominal subtype of X. X'Image X'Image denotes the result of calling function S'Image with Arg being X, where S is the nominal subtype of X. ==== Add after 13.13.1(9) (the end of the static semantics section): The following related units are also declared. package Ada.Streams.Counted_Streams is type Counted_Stream is abstract new Root_Stream_Type with private; function Element_Count (Stream : Counted_Stream) return Stream_Element_Count is abstract; end Ada.Streams.Counted_Streams; package Ada.Streams.Counted_Streams.Unbounded is type Unbounded_Stream is new Counted_Stream with private with Default_Initial_Condition => Element_Count (Unbounded_Stream) = 0; overriding procedure Read ( Stream : in out Unbounded_Stream; Item : out Stream_Element_Array; Last : out Stream_Element_Offset) with Post => Element_Count (Stream) = Element_Count (Stream)'Old - Item (Item'First .. Last)'Length; overriding procedure Write ( Stream : in out Unbounded_Stream; Item : in Stream_Element_Array) with Post => Element_Count (Stream) = Element_Count (Stream)'Old + Item'Length; overriding function Element_Count (Stream : Unbounded_Stream) return Stream_Element_Count; end Ada.Streams.Counted_Streams.Unbounded; package Ada.Streams.Counted_Streams.Bounded is -- same as Unbounded except for the discriminant type Bounded_Stream (Max_Elements : Stream_Element_Count) is new Counted_Stream with private with Default_Initial_Condition => Element_Count (Unbounded_Stream) = 0; overriding procedure Read ( Stream : in out Bounded_Stream; Item : out Stream_Element_Array; Last : out Stream_Element_Offset) with Post => Element_Count (Stream) = Element_Count (Stream)'Old - Item (Item'First .. Last)'Length; overriding procedure Write ( Stream : in out Bounded_Stream; Item : in Stream_Element_Array) with Pre => Element_Count (Stream) + Item'Length <= Stream.Max_Elements or else (raise Constraint_Error) with Post => Element_Count (Stream) = Element_Count (Stream)'Old + Item'Length; overriding function Element_Count (Stream : Bounded_Stream) return Stream_Element_Count with Post => Element_Count'Result <= Stream.Max_Elements; end Ada.Streams.Counted_Streams.Bounded; The Element_Count functions return the number of stream elements that are available for reading in the given stream. ==== Add after 13.13.1(9.1/1): Implementation Advice Bounded_Stream objects should be implemented without implicit pointers or dynamic allocation. !discussion This change does introduce an obscure incompatibility having to do with implicit dereferencing when the prefix of an Image (or Wide_Image, or Wide_Wide_Image) attribute is an object of an access-to-scalar type. Consider the following example: type Int_Ref is access Integer; Ptr : Int_Ref := new Integer'(123); Ptr_Image : String := Ptr'Image; pragma Assert (Ptr_Image = Ptr.all'Image); With the current language definition, the assertion should succeed. See the words "(after any implicit dereference)" in 3.5(55.1/5); this wording was added as part of AI12-0124. With the proposed changes, the program remains legal but the assertion will now fail because Ptr_Image will be initialized with the image of an access value, as opposed to the image of an integer value. Clients of the GNAT and Janus Ada compilers will be unaffected by this incompatibility because these compilers do not currently accept the above (legal) example; it seems likely that this is true of other Ada implementations, but this has not been confirmed. --- In some obscure cases, the image of a record value may include multiple components with the same name. For example package Pkg is type T1 is tagged private; private type T1 is tagged record Foo : Integer := 123; end record; end; type T2 is new T1 with record Foo : Integer := 456; end record; X2 : T2; pragma Assert (X2'Image = "(FOO => 123, FOO => 456)"); In cases like this, the ordering of the component values prevents ambiguity. --- A derived type which defines new discriminants behaves as one would expect (i.e., consistently with the rules for record aggregates and for streaming). For example, the assertion in the following example will succeed: type T1 (D1, D2 : Integer) is record F : Integer := 123; end record; type T2 (D3 : Integer) is new T1 (D1 => D3, D2 => D3); X : T2 (456); pragma Assert (X'Image = "(D3 => 456, F => 123)"); ---- If a protected type T has protected subcomponents, then the default implementation of T'Put_Image will probably violate the no-potentially-blocking-ops-during-a-protected-action rule. Do we want any sort of legality rules relating to this? In evaluating any possible rules relating to this scenario, keep in mind the case of a protected type declared in the body of a generic unit with a subcomponent of a formal limited private type whose corresponding actual type, for some particular instance of the generic, is a protected type. ---- The default implementation of Put_Image for a Scalar type is equivalent to procedure Put_Image ( : Scalar_Type; Stream : access Counted_Stream'Class) is Wide_Wide_Image : constant Wide_String := ; begin Wide_Wide_String'Write (Wide_Wide_Image, Stream) end Put_Image; For a record type having components C1, C2, and C3 (in that order, as given by the component ordering rules for a positional record aggregate), the default implementation of Put is equivalent to procedure Put_Image ( : Record_Type; Stream : access Counted_Stream'Class) is begin Wide_Wide_String'Write ("(", Stream); Wide_Wide_String'Write ("C1 => ", Stream); .C1'Put (Stream) Wide_Wide_String'Write (", C2 => ", Stream); .C2'Put (Stream) Wide_Wide_String'Write (", C3 => ", Stream); .C3'Put (Stream) Wide_Wide_String'Write (")", Stream); end Put_Image; A variant part introduces a corresponding case statement. The default implementation of Put for a one-dimensional array type is equivalent to procedure Put ( : Array_Type; Stream : access Counted_Stream'Class) is begin Wide_Wide_String'Write ("(", Stream); if 'Length = 0 then 'First'Put (Stream); Wide_Wide_String'Write (" .. ", Stream); 'Last'Put (Stream); Wide_Wide_String'Write (" => <>", Stream); else for Idx in 'Range loop Idx'Put (Stream); Wide_Wide_String'Write (" => ", Stream); (Idx)'Put (Stream); if Idx /= 'Last then Wide_Wide_String'Write (", ", Stream); end if; end if; end loop; Wide_Wide_String'Write (")", Stream); end; Other types are handled similarly; just calls to Wide_Wide_String'Write mixed with Put_Image calls for components. Note that the implementation of T'Class'Put_Image will involve a dispatching call to the Put_Image of the corresponding specific type (after writing out the Wide_Wide_Expanded_Name of the tag and a "'"), so that requires a new entry in the dispatch table for each tagged type. !ACATS test ** TBD. !appendix From: Gregory D Moncreaff Sent: Thursday, October 13, 2011 6:59 PM Having worked with other language technologies, specifically C# and Java, I was wondering if any consideration was being given to the idea of providing some form of default rendering of record types via an attribute? Typically one would expect it to report all components (recursively) of record using the type primitive existing image attributes. Access types would not be traversed to avoid recursion. Only the valid components of a discriminated record would be reported. Ideal format would be of something that could itself be used as a record assignment by components. Optionally providing the ability of overriding this attribute would be nice, but not necessary. Special care would need to be taken if String's had special ASCII characters within them by concatenating the quotable portions of the string with the specials. Does this seem reasonable? **************************************************************** From: Randy Brukardt Sent: Thursday, October 13, 2011 9:16 PM ... >I was wondering if any consideration was being given to the idea of >providing some form of default rendering of record types via an >attribute? Yes, of course. We've considered a number of additional forms of 'Image and 'Value. We never got any consensus on whether they are important enough. >Typically one would expect it to report all components (recursively) of >record using the type primitive existing image attributes. In what format?? (Aggregates, presumably.) Why only records, why not arrays? >Access types would not be traversed to avoid recursion. Only the valid >components of a discriminated record would be reported. What gets output for a non-null access type parameter. Whatever it is, it wouldn't mean the same thing in an aggregate, which is bad. >Ideal format would be of something that could itself be used as a >record assignment by components. What is this? An aggregate I can imagine, I don't even know what "record assignment by components" means (I imagine a series of assignment statements when I read that, but I can't imagine how you could use that as an 'Image). >Optionally providing the ability of overriding this attribute would be >nice, but not necessary. We've discussed this idea in the past, too. We also considered *only* providing this (see below for why). >Special care would need to be taken if String's had special ASCII >characters within them by concatenating the quotable portions of the >string with the specials. A String is just an array in Ada, there is nothing special about it. And what about components that are other arrays (arrays of integer, arrays of float, arrays of record)? Task components? Protected type components? >Does this seem reasonable? Not particularly, for some of the reasons given above. As a built-in attribute, the compiler would have to generate it for all types (whether it is used or not, since it can't know whether some other package will use it). And given the recursive definition you are giving, it would become very, very large for a lot of types (even stopping on access types). Imagine a record containing a matrix component, for one example. For a compiler (like Janus/Ada) that is designed to make small size code, this would be a problem. (At least it would not have any runtime impact unless used.) I do think there might be something worth doing for 'Image (I don't think we rejected it for technical reasons as much as importance). But an automatically recursing 'Image isn't it, IMHO. **************************************************************** From: Simon Wright Sent: Friday, October 14, 2011 2:23 AM > I was wondering if any consideration was being given to the idea of providing > some form of default rendering of record types via an attribute? Gregory might find the ASIS-based Auto_Text_IO useful - http://www.sigada.org/WG/asiswg/ASIS_Clients.html#Leake **************************************************************** From: Steve Baird Sent: Thursday, January 25, 2018 7:24 PM I'd like to get a consensus on intent before attempting wording. For statements in the list below, I'd like confirmation. For questions, I'd like answers. 1) Image is to be defined for all types (including limited types) and can be overridden in pretty much the same way that streaming attributes can be overridden (but see #8 below). Unlike streaming attributes, there are no availability issues - 'Image is always available. 2) For scalar types, behavior is unchanged (except in the user-defined case). In all (non-user-defined) cases, you get no line-breaking or any sort of formatting. [We are avoiding pretty-printer wars as much as possible.] 3) For task and access types, the string is implementation dependent. For example, the image for any value of such a type might be "<>". Or it might be something more useful. As mentioned earlier, users can override. 3) For untagged records, we use named-notation aggregate syntax (order of fields follows positional aggregate rules) type T is record Xx, Yy, Zz : Some_Type; end record; Obj : T := ... ; pragma Assert (Obj'Image = "(Xx => " & Obj.Xx'Image & ", Yy => " & Obj.Yy'Image & ", Zz => " & Obj.Zz'Image & ")" Ditto for specific tagged records; in particular, the tag value is not mentioned at all in that case. Nothing special for protected records. In the no-components case, image is "(null record)". 4) What do we do for class-wide? It seems like we need to mention the tag or the name of the specific type or something like that. Perhaps using qualified expression syntax, with Ada.Tags.External_Name (Obj'Tag) as the qualifier? Record aggregate syntax is used (as opposed to extension aggregate syntax). [It is ok if this displays two components with the same name; ordering resolves the ambiguity in this corner case.] There is also the issue of distributed overhead, similar to the case of a user who declares a tagged type and never uses its streaming operations; can we ignore this concern? 5) What about arrays? It would be very verbose to use named notation syntax, as in "(1 => 123, 2 => 456, 3 => 789, ..., 9999 => 0)" but we have to get the bounds in there somehow. Perhaps display it sort of like a record, as in "(First(1) => 1, Last(1) => 3, First(2) => 1, Last(2) => 2, " & "((1, 2), (3, 4), (5, 6)))" Do we want to do anything different in the case where the first named subtype is constrained? One might argue that there is no need to display bounds in that case. But then what happens with an aggregate or a slice which doesn't have the bounds of the first named subtype? There is also a question about null arrays, both single- and multi-dimensional. Perhaps these might be displayed as "(First => 1, Last => 0, ())" "(First(1) => 1, Last(1) => 3, First(2) => 1, Last(2) => 0," & " ((), (), ())" "(First(1) => 1, Last(1) => 0, First(2) => 1, Last(2) => 3," & " ()" Do we want to do anything special for the image of a string type and use some variant of string-literal syntax? Probably, although string-type is the wrong thing to test for because that would allow something like type Element is ('A', 'B', None_Of_The_Above); type I_Am_A_String_Type is array (1 .. 10) of Element; and we don't want to use string-literal syntax for some values of a given type and not for others. A big advantage of using verbose named-notation syntax is that it would then be more natural to use range notation in the case where consecutive elements have the same image (with the usual permissions to avoid having to invoke the Image function twice if arguments are known to be equal). So we might see "(1 => 123, 2 .. 999 => 0, 1000 => 456)" Named-notation syntax is probably the way to go, even though (as noted earlier) it can lead to a lot of redundant text in some cases. If we do that, then we'd need consistent syntax for the null array case (single- and multi-dimensional). 6) Some images begin with leading blanks and some don't (that's already true, so we have to deal with both cases). Do we want to take any steps to avoid ugly double-blanks? For example, would the image of a record with two integers look like "(X => 123, Y => 456)" or like "(X => 123, Y => 456)" -- note the two additional spaces ? See the Assert pragma in item #3 above. 7) What about compatibility issues? Given a bunch of overloaded parameterless functions named Foo, could there be a situation where we currently accept Foo'Image but it would become ambiguous with the new rules? I think the answer is no, and there is no problem here. Nonetheless, it seems worth mentioning. 8) The same relationship between 'Image, 'Wide_Image, and 'Wide_Wide_Image holds for any type as holds today. Only 'Wide_Wide_Image is user-specifiable and the others follow suit as usual. If a mention of "user-specified Image attribute" or somesuch in this discussion appears to violate this rule, that is a case of preferring clarity over precision - to repeat: Image cannot be specified, Wide_Wide_Image can be specified, and specifying Wide_Wide_Image changes the behavior of Wide_Image and Image. 9) Inheritance of user-specified Image attributes follows the same rules as for streaming attributes. 10) Evaluation of an Image attribute never yields a static string if the attribute is user-defined. For a scalar type, at least, this means that we probably want to prohibit package Pkg is type T is range 1 .. 10; private function WWI (X : T) return Wide_Wide_String; for T'Wide_Wide_Image use WWI; end Pkg; because clients outside would have to look into the private part to see that T'Image(5) is not a static string. **************************************************************** From: Randy Brukardt Sent: Thursday, January 25, 2018 8:02 PM ... > 3) For task and access types, the string is implementation > dependent. For example, the image for any value of such > a type might be "<>". Or it might be something more useful. > As mentioned earlier, users can override. You have two #3s here. :-) For a task, one could imagine using the task id somehow. (At least, that was my first thought.) Not completely useful (especially for 'Value), but it would clearly allow telling tasks apart and would be useful for debugging. For access values, one could mandate using the image of the associated Integer_Address in, say square brackets. (That would be familiar to anyone used to an Intel assembler.) One of the main purposes of the predefined version is debugging, and allowing the image to be nothing is not useful for debugging. So perhaps it is better to specify something, even if that something isn't enough to use in 'Value. > 3) For untagged records, we use named-notation aggregate syntax > (order of fields follows positional aggregate rules) > > type T is record Xx, Yy, Zz : Some_Type; end record; > Obj : T := ... ; > > pragma Assert (Obj'Image = > "(Xx => " & Obj.Xx'Image > & ", Yy => " & Obj.Yy'Image > & ", Zz => " & Obj.Zz'Image > & ")" > > Ditto for specific tagged records; in particular, the > tag value is not mentioned at all in that case. Nothing > special for protected records. > > In the no-components case, image is "(null record)". One needs to specify the case of the component names in this aggregate. I'd expect the assertion to fail, because those names will probably be all UPPER CASE or all lower case -- but never mixed case. (Most likely, copy the enumeration rule.) For the purposes of 'Value, some types would have to be disallowed as there may not be unique UPPER CASE versions of the ids. But leave that worry to the author of 'Value. > 4) What do we do for class-wide? It seems like we need to > mention the tag or the name of the specific type or > something like that. Perhaps using qualified expression > syntax, with Ada.Tags.External_Name (Obj'Tag) as the > qualifier? Record aggregate syntax is used (as opposed to > extension aggregate syntax). [It is ok if this displays > two components with the same name; ordering resolves > the ambiguity in this corner case.] The qualified expression syntax seems fine. One would want to be able to have a 'Value for it, at least if the components are all distinct. (That obviously doesn't matter for 'Image). > There is also the issue of distributed overhead, similar > to the case of a user who declares a tagged type and never > uses its streaming operations; can we ignore this concern? Yes. All good compilers ... sorry Tuck. Janus/Ada removes unused subprograms at link-time, even if they occur in tags. (Yes, there is a way to write a shared generic such that we have to turn off this optimization, but I've never seen such a generic written by anyone -- including me -- to date.) So this is possible, and this "dead code" overhead can be made zero if it is an actual concern. This can be a real problem for tagged types (we implemented this to make the "hello world" CLAW program more reasonably sized; I believe it changes a 1.5M executable into a 0.5M executable, so this isn't trivial). > 5) What about arrays? It would be very verbose to use > named notation syntax, as in > > "(1 => 123, 2 => 456, 3 => 789, ..., 9999 => 0)" > > but we have to get the bounds in there somehow. > Perhaps display it sort of like a record, as in > > "(First(1) => 1, Last(1) => 3, First(2) => 1, Last(2) => 2, " > & "((1, 2), (3, 4), (5, 6)))" > > Do we want to do anything different in the case where the > first named subtype is constrained? One might argue > that there is no need to display bounds in that case. > But then what happens with an aggregate or a slice which > doesn't have the bounds of the first named subtype? > > There is also a question about null arrays, both > single- and multi-dimensional. Perhaps these might > be displayed as > > "(First => 1, Last => 0, ())" > > "(First(1) => 1, Last(1) => 3, First(2) => 1, Last(2) => 0," > & " ((), (), ())" > > "(First(1) => 1, Last(1) => 0, First(2) => 1, Last(2) => 3," > & " ()" > > > Do we want to do anything special for the image of > a string type and use some variant of string-literal > syntax? Probably, although string-type is the wrong > thing to test for because that would allow something > like > type Element is ('A', 'B', None_Of_The_Above); > type I_Am_A_String_Type is array (1 .. 10) of Element; > and we don't want to use string-literal syntax for some > values of a given type and not for others. > > A big advantage of using verbose named-notation > syntax is that it would then be more natural to use range > notation in the case where consecutive elements have > the same image (with the usual permissions to avoid > having to invoke the Image function twice if arguments > are known to be equal). > > So we might see > "(1 => 123, 2 .. 999 => 0, 1000 => 456)" > > Named-notation syntax is probably the way to go, even though > (as noted earlier) it can lead to a lot of redundant text in > some cases. If we do that, then we'd need consistent syntax > for the null array case (single- and multi-dimensional). You seem to have answered your own question here. And I tend to agree. 'Image of large data structures is never going to be very useful (what do you do with 20 pages of output), so it probably makes sense to just use the syntax that provides the most information and least chance of getting it wrong. > 6) Some images begin with leading blanks and some don't (that's > already true, so we have to deal with both cases). Do we want > to take any steps to avoid ugly double-blanks? For example, > would the image of a record with two integers look like > "(X => 123, Y => 456)" > or like > "(X => 123, Y => 456)" -- note the two additional spaces > ? See the Assert pragma in item #3 above. Not sure here. It would be a pain to try to eliminate the leading blanks for numeric 'Image, so I probably would say leave the extra blanks. (Or maybe, skip putting a blank after "=>", as it will still be syntactically correct either way.) One can always user-define it if you need it perfect. > 7) What about compatibility issues? > > Given a bunch of overloaded parameterless functions named > Foo, could there be a situation where we currently accept > Foo'Image > but it would become ambiguous with the new rules? > I think the answer is no, and there is no problem here. > Nonetheless, it seems worth mentioning. Attribute prefixes have to resolved sans context (with the exception of 'Access and any others with special rules). So it would have to be ambiguous now if Foo is overloaded with no parameters. ... > 10) Evaluation of an Image attribute never yields a > static string if the attribute is user-defined. > For a scalar type, at least, this means that we > probably want to prohibit > > package Pkg is > type T is range 1 .. 10; > private > function WWI (X : T) return Wide_Wide_String; > for T'Wide_Wide_Image use WWI; > end Pkg; > > because clients outside would have to look into the > private part to see that T'Image(5) is not a static string. Luckily, string attributes are never static -- see 4.9(7) -- and we didn't change that in part because we knew this AI was coming -- so this is a lot of worry about nothing. **************************************************************** From: Raphaël Amiard Sent: Friday, January 25, 2018 8:23 AM I agree wholeheartedly with this proposal, and Randy's suggestions, FWIW. >... > >3) For task and access types, the string is implementation > dependent. For example, the image for any value of such > a type might be "<>". Or it might be something more useful. > As mentioned earlier, users can override. I wonder: In my opinion we want to make a lot of that implementation dependent (I mean it's good if there are some guide lines, but that's it). I don't think we want users to start relying on the output of 'Image as some kind of interchange format, so we should be clear on that in any way. I'm also wondering, and I know we discussed it live but I don't see any mention of that in your mail Steve: What about 'Value ? I think we said that 'Value won't be implemented for complex types, but it would be better to state it clearly I guess. If we don't implement 'Value, I would lean forward making most of the rules you mention implementation dependent (for example the one about named parameters in arrays), with the ARM just giving advice/guidelines/how do we call that again **************************************************************** From: Steve Baird Sent: Friday, January 25, 2018 11:49 AM > ... >> 3) For task and access types, the string is implementation >> dependent. For example, the image for any value of such >> a type might be "<>". Or it might be something more useful. >> As mentioned earlier, users can override. > > You have two #3s here. :-) > > For a task, one could imagine using the task id somehow. (At least, > that was my first thought.) Not completely useful (especially for > 'Value), but it would clearly allow telling tasks apart and would be useful > for debugging. I agree, Task_Identification.Image of the task id is what we want for tasks. Note that no changes involving 'Value are proposed in this AI. As Raphael points out, it would probably be good to mention this explicitly (i.e., to talk about what we are not talking about). I've omitted in this reply all of your subsequent 'Value-related comments. > For access values, one could mandate using the image of the associated > Integer_Address in, say square brackets. (That would be familiar to > anyone used to an Intel assembler.) Fair enough, although if we are going to require something then I'd rather see the address displayed in hex. >> 3) For untagged records, we use named-notation aggregate syntax >> (order of fields follows positional aggregate rules) >> >> type T is record Xx, Yy, Zz : Some_Type; end record; >> Obj : T := ... ; >> >> pragma Assert (Obj'Image = >> "(Xx => " & Obj.Xx'Image >> & ", Yy => " & Obj.Yy'Image >> & ", Zz => " & Obj.Zz'Image >> & ")" >> >> Ditto for specific tagged records; in particular, the >> tag value is not mentioned at all in that case. Nothing >> special for protected records. >> >> In the no-components case, image is "(null record)". > > One needs to specify the case of the component names in this > aggregate. I'd expect the assertion to fail, because those names will > probably be all UPPER CASE or all lower case -- but never mixed case. > (Most likely, copy the enumeration rule.) Good point. I agree - upper case. We certainly don't want the case that was used in the declaration(s) of the type to have any effect on the runtime behavior of a program. >> 5) What about arrays? It would be very verbose to use ... >> Named-notation syntax is probably the way to go, even though >> (as noted earlier) it can lead to a lot of redundant text in >> some cases. If we do that, then we'd need consistent syntax >> for the null array case (single- and multi-dimensional). > > You seem to have answered your own question here. And I tend to agree. > 'Image of large data structures is never going to be very useful (what > do you do with 20 pages of output), so it probably makes sense to just > use the syntax that provides the most information and least chance of > getting it wrong. It's worth noting that when we display an index value, we of course use the Image attribute of the index type. >> 6) Some images begin with leading blanks and some don't (that's >> already true, so we have to deal with both cases). Do we want >> to take any steps to avoid ugly double-blanks? For example, >> would the image of a record with two integers look like >> "(X => 123, Y => 456)" >> or like >> "(X => 123, Y => 456)" -- note the two additional spaces >> ? See the Assert pragma in item #3 above. > > Not sure here. It would be a pain to try to eliminate the leading > blanks for numeric 'Image, so I probably would say leave the extra > blanks. (Or maybe, skip putting a blank after "=>", as it will still > be syntactically correct either way.) One can always user-define it if you > need it perfect. Changing the behavior of numeric 'Image would be grossly incompatible; that seems out of the question to me. I was thinking more about looking for a leading space on a component image and conditionally preceding it with either a "=> " or a "=>" when generating the image of an enclosing composite object. === I was thinking some more about the Image/Wide_Image/Wide_Wide_Image rules. 90% of the time, all that anyone is interested in is the Image attribute and it is somewhat clunky to have to specify the Wide_Wide_Image aspect (or even mention Wide_Wide_String at all). But we want to retain consistency between the 3 image attributes; we don't want, for example, to allow users to explicitly specify Image and Wide_Image aspects for one type. I originally proposed one solution: only Wide_Wide_Image is specifiable. How about, instead, allowing any *one* of the three aspects Image, Wide_Image, Wide_Wide_Image to be specified? Whatever aspect is specified determines the behavior of all three attributes. [Alternatively, we could say that only Image is specifiable but the specified value can be a function returning any of the three predefined string types; there are advantages to this approach - we don't have to worry about defining what happens in a case like type T1 is ... with Wide_Image => ... ; type T2 is new T1 with Image => ... ; ]. **************************************************************** From: Steve Baird Sent: Friday, January 25, 2018 2:11 PM More thoughts on this. > It's worth noting that when we display an index value, we of course > use the Image attribute of the index type. "the Image attribute" => "the appropriate image attribute". If we are in the middle of generating, say, a Wide_Wide_String as part of evaluating Some_Array'Wide_Wide_Image, then we want to use Index_Type'Wide_Wide_Image (as opposed to Index_Type'Image). > I agree, Task_Identification.Image of the task id is what we want for > tasks. Discriminated task types should display the discriminant values somehow. Perhaps extension-aggregate-ish syntax? Something like (task with D1 => This, D2 => that) and then, for consistency, undiscriminated image is (task ) . Or perhaps we drop the word "task", but then the parens look odd in the undiscriminated task case. Do we drop them? > Nothing special for protected records. Presumably Some_Protected_Object'Image behaves like a call to a protected function with respect to locking. > Named-notation syntax is probably the way to go... > If we do that, then we'd need consistent syntax > for the null array case (single- and multi-dimensional). If we define syntax for null array aggregates, then we should use whatever is agreed upon. Otherwise, how about "(1 .. 0 => <>)" "(1 .. 3 => (1 .. 0 => <>))" "(1 .. 0 => (1 .. 3 => <>))" ? Or perhaps "()" instead of "<>". ==== It needs to be explicitly stated that Some_Object'Image is defined when the object is of a non-numeric type. **************************************************************** From: Randy Brukardt Sent: Friday, January 25, 2018 2:56 PM > I'm also wondering, and I know we discussed it live but I don't see any > mention of that in your mail Steve: What about 'Value ? I think we said that >'Value won't >be implemented for complex types, but it would be better to > state it clearly I guess. We decided only to consider 'Value separately. (And assigned that AI to Tucker.) We didn't decide yes or no on that. > If we don't implement 'Value, I would lean forward making most of the rules > you mention implementation dependent (for example the one about named > parameters in arrays), with the ARM just giving advice/guidelines/how do we > call that again That's undecided at this time. But my preference would be to leave the possibility open for the future, even if we decide not to do it this time. Therefore, I would prefer to lock down the formats for as much as possible. If we made them implementation-dependent, then we could never implement 'Value (nor could a user write their own portable 'Value). **************************************************************** From: Randy Brukardt Sent: Friday, January 25, 2018 3:06 PM ... > Note that no changes involving 'Value are proposed in this AI. > As Raphael points out, it would probably be good to mention this > explicitly (i.e., to talk about what we are not talking about). > > I've omitted in this reply all of your subsequent 'Value-related > comments. My point of mentioning 'Value in my comments is that I want the possibility of implementing that preserved as much as possible. So, if there is a syntax that would work for 'Value, and one that would not work for 'Value, I strongly lean toward the one that would allow 'Value. Note that "allowing 'Value" is the same as "allowing users to write a portable 'Value-like subprogram". I agree that whether or not we support 'Value this time (or ever) is not relevant to this AI. I think that is fair game to talk about whether or not the suggested format could support 'Value (or similar user-written routines). > > For access values, one could mandate using the image of the > > associated Integer_Address in, say square brackets. (That would be > > familiar to anyone used to an Intel assembler.) > > Fair enough, although if we are going to require something then I'd > rather see the address displayed in hex. The only issue with that is that we don't have a hex image routine anywhere. Integer_Address'Image is well-defined. ... > >> 6) Some images begin with leading blanks and some don't (that's > >> already true, so we have to deal with both cases). Do we want > >> to take any steps to avoid ugly double-blanks? For example, > >> would the image of a record with two integers look like > >> "(X => 123, Y => 456)" > >> or like > >> "(X => 123, Y => 456)" -- note the two additional spaces > >> ? See the Assert pragma in item #3 above. > > > > Not sure here. It would be a pain to try to eliminate the leading > > blanks for numeric 'Image, so I probably would say leave the extra > > blanks. (Or maybe, skip putting a blank after "=>", as it will still > > be syntactically correct either way.) One can always user-define it > > if you need it perfect. > > Changing the behavior of numeric 'Image would be grossly incompatible; > that seems out of the question to me. I agree, but I was not suggesting that. > I was thinking more about looking for a leading space on a component > image and conditionally preceding it with either a "=> " or a "=>" > when generating the image of an enclosing composite object. I think that is too much work, especially as it is value-dependent for Integer'Image. My suggestion was simply to always generate "=>" (with no trailing space), as that is lexically and syntactically correct, and it avoids the double spacing. Otherwise, just don't worry about that -- this is mainly for debugging anyway, perfection not required. > === > > I was thinking some more about the > Image/Wide_Image/Wide_Wide_Image rules. > > 90% of the time, all that anyone is interested in is the Image > attribute and it is somewhat clunky to have to specify the > Wide_Wide_Image aspect (or even mention Wide_Wide_String at all). > > But we want to retain consistency between the 3 image attributes; we > don't want, for example, to allow users to explicitly specify Image > and Wide_Image aspects for one type. > > I originally proposed one solution: only Wide_Wide_Image is > specifiable. > > How about, instead, allowing any *one* of the three aspects Image, > Wide_Image, Wide_Wide_Image to be specified? > Whatever aspect is specified determines the behavior of all three > attributes. [Alternatively, we could say that only Image is > specifiable but the specified value can be a function returning any of > the three predefined string types; there are advantages to this > approach - we don't have to worry about defining what happens in a > case like > type T1 is ... with Wide_Image => ... ; > type T2 is new T1 with Image => ... ; ]. Whatever the rule is, it can allow specifying only one. In this latter Bairdian case, I'd expect the second one to totally override all three. I'll leave the exact rule to you. **************************************************************** From: Steve Baird Sent: Friday, January 25, 2018 3:29 PM > So, if there is a syntax > that would work for 'Value, and one that would not work for 'Value, I > strongly lean toward the one that would allow 'Value. I agree. >>> For access values, one could mandate using the image of the >>> associated Integer_Address in, say square brackets. (That would be >>> familiar to anyone used to an Intel assembler.) >>> >> >> Fair enough, although if we are going to require something then I'd >> rather see the address displayed in hex. > > The only issue with that is that we don't have a hex image routine anywhere. > Integer_Address'Image is well-defined. Requiring (as opposed to allowing) something that isn't very useful would be bad. I'd rather leave it implementation dependent than to require decimal-format display for addresses. My first choice is requiring hex. > My suggestion was simply to always generate "=>" (with no trailing > space), as that is lexically and syntactically correct, and it avoids > the double spacing. Otherwise, just don't worry about that -- this is > mainly for debugging anyway, perfection not required. In a situation where one space would be ideal, I'd rather see two spaces than none. So I'd rather unconditionally generate "=> " instead of "=>" if those are the only two choices. Note that there is a similar issue with index values in array aggregates (and these can appear in at least 3 different contexts - after a left paren, a comma, or a ".."). > Whatever the rule is, it can allow specifying only one. In this latter > Bairdian case, I'd expect the second one to totally override all three. Agreed. **************************************************************** From: Randy Brukardt Sent: Friday, January 25, 2018 9:51 PM ... > >>> For access values, one could mandate using the image of the > >>> associated Integer_Address in, say square brackets. (That would be > >>> familiar to anyone used to an Intel assembler.) > >>> > >> > >> Fair enough, although if we are going to require something then I'd > >> rather see the address displayed in hex. > > > > The only issue with that is that we don't have a hex image routine > > anywhere. Integer_Address'Image is well-defined. > > > > Requiring (as opposed to allowing) something that isn't very useful > would be bad. On modern 32-bit machines, neither is very useful. Data point: When Janus/Ada got ported to 32-bit machines, no 32-bit hex value routine was available and someone took the lazy way out when programming the symbol table dump. The decimal numbers, as you say, aren't very useful. No one can memorize a ten-digit number, so looking for the values by hand is impossible, especially as they all look similar. And searching is not fun, simply because there is a lot of chance of error in typing a 10 digit number. So we changed to hex. And guess what? The effect is the same: looking for values by hand isn't possible in general, because memorizing an 8 digit number isn't substantially easier than 10. And typing an 8-digit hex number for searching is nearly as hard as a 10 digit decimal number (needing to use both numbers and letters rather than just the number pad). This gets even worse on modern OSes using address-space randomization, because the first few hex digits vary more than they used to. And also for 64-bit machines, where the number of digits is way too many to do anything with when reading (in either format). I gave up on both last winter and reprogrammed the routine to show the symbol record unit/id pair instead. This is usually a pair of 2 digit numbers (in test programs, anyway, they'd be longer in a full-sized program but luckily one rarely has to debug those without a smaller reproducer). That's much easier to look for manually (plus it gives some information about where to look), and easier to search for with a program (as it's shorter). The downside is that it requires dereferencing the pointer to be displayed, so a corrupt pointer can crash the dump -- but a corrupt pointer is a critical bug and the failing dump shows precisely where to look (wherever the dump stops), so that's hardly an issue for this use. Ergo, I'd expect most serious use of access Image to replace it with an user-defined version. For one-off debugging, what it is hardly matters (so long as values that are different can be recognized). Aside: should the image of a null access value be "null" or "[00000000]" (if hex) or "[ 0]" (if 'Image)?? **************************************************************** From: Jean-Pierre Rosen Sent: Saturday, January 27, 2018 1:28 AM > The only issue with that is that we don't have a hex image routine > anywhere. Integer_Address'Image is well-defined. If the (hex) image uses based notation, it can be fed back to 'Value **************************************************************** From: Tucker Taft Sent: Saturday, January 27, 2018 11:29 AM > ... > Discriminated task types should display the discriminant values somehow. > Perhaps extension-aggregate-ish syntax? Something like > > (task with D1 => This, D2 => that) > > and then, for consistency, undiscriminated image is > > (task ) . > > Or perhaps we drop the word "task", but then the parens look odd in > the undiscriminated task case. Do we drop them? I like the word "task" being there, and always using parentheses for composite types. > Nothing special for protected records. I would think you would have "(protected with disc1 => X, disc2 => Y, comp1 => Z, ...)" to be consistent with tasks, and to make it clear that this is not your normal record. > Presumably Some_Protected_Object'Image behaves like a call to a > protected function with respect to locking. > >> Named-notation syntax is probably the way to go... >> If we do that, then we'd need consistent syntax >> for the null array case (single- and multi-dimensional). > > If we define syntax for null array aggregates, then we should use > whatever is agreed upon. Otherwise, how about > > "(1 .. 0 => <>)" > > "(1 .. 3 => (1 .. 0 => <>))" > > "(1 .. 0 => (1 .. 3 => <>))" > ? Or perhaps "()" instead of "<>". "<>" seems better than "()" given the general Ada allergy to empty parentheses. **************************************************************** From: Steve Baird Sent: Wednesday, February 28, 2018 8:03 PM I still don't have real RM wording for this one, but here is a more detailed outline than what we had before for this AI, incorporating feedback from the last meeting and subsequent discussions with Bob and Tuck. [This is the !proposal section of version /02 of the AI - Editor.] First, a summary of what we plan for the default (as opposed to user-specified) implementations of T'Image for a possibly-nonscalar type T. Much of this has already been discussed, but there is some new stuff (e.g., the treatment of type extensions). The completely new stuff that has not previously been discussed on the ARG list is the discussion of the Put attribute in the second part of this message. Feedback, as always, is most welcome. **************************************************************** From: Tucker Taft Sent: Thursday, March 1, 2018 6:52 AM I preferred the proposal to include the words "task ..." or "protected ..." in the 'Image for such types. You wrote: For task types - Undiscriminated: "()" Discriminated: "(D1 => 123, D2 => 456, )" For protected types - Nothing special. Same as any record type. Protected_Obj'Image is a protected function (this matters, for example, for locking). Earlier I had seen a proposal of approximately: (task ) -- no discriminants (task with D1 => 123, D2 => 456) and for protected types, the analogous thing: (protected ) -- no discriminants or private components (protected with D1 => ... , C1 => ...) -- discriminants and/or components I think these have a nice symmetry, and will reduce confusion with other aggregates. Clearly protected objects have some kind of identity (typically some sort of internal semaphore ID), and that is something that would be of interest. Just dumping the value of the private components would be losing significant information. **************************************************************** From: Randy Brukardt Sent: Thursday, March 1, 2018 9:37 PM > Earlier I had seen a proposal of approximately: > > (task ) -- no discriminants > > (task with D1 => 123, D2 => 456) I think you made that proposal, so I'm pretty sure you saw it. ;-) But I agree with this, especially as a task id might just be a small integer which would make no sense without context. > and for protected types, the analogous thing: > > (protected ) -- no discriminants or private components > (protected with D1 => ... , C1 => ...) -- discriminants and/or components I agree with the "protected" part, but there is no such thing as a ; protected types are just records with a predefined blob used by the task supervisor. One could use the address if someone insisted on an , but this doesn't seem different than any other record type in that in some cases you might need to display the identity. In that case, you should dump the address as well as the image. So I don't think there should be any here. In the case of tasks, most of them have no other components so the task id is needed to even get an idea of the type. That's unlikely for protected objects. If we'd prefer consistency, I'd rather drop the id from the tasks rather than force a non-existent thing into the protected case. > I think these have a nice symmetry, and will reduce confusion with > other aggregates. > > Clearly protected objects have some kind of identity (typically some > sort of internal semaphore ID), and that is something that would be of > interest. Just dumping the value of the private components would be > losing significant information. I strongly disagree with this: Janus/Ada exposes none of this stuff even to the rest of the compiler. The compiler just sees a private type of a particular size. We'd have to define new task supervisor operations specifically for this purpose if we needed to expose something else -- but the "something else" doesn't even exist. The address of the protected object serves to identify it in any case that is needed. I'd be surprised if other compilers differed on this. These guys - particularly because they have discriminants - are much more like a record with some special operations when accessed than a task (which is an active structure). Perhaps there is some mutex that the underlying OS gives an Id to, but that has nothing to do with Ada. The idea of a Task_Id is well-defined in Ada; there's an entire section in the Standard talking about it. And that defines an Image function. That's what would appear in 'Image. Imagining a whole new mechanism (one that is nonexistent in at least some compilers) just for Image is waaaay over the top. **************************************************************** From: Tucker Taft Sent: Thursday, March 1, 2018 10:06 PM Perhaps we should always just include its address. Clearly two otherwise identical protected objects are still fundamentally distinct, since they each have their own specific lock. That is all I was trying to accomplish with the protected ID. *************************************************************** From: Randy Brukardt Sent: Thursday, March 1, 2018 11:24 PM OK, I guess, but isn't that fundamentally true of any limited type? You've often made the point that the object identity of a limited object is an important part of its abstraction. I was just wondering why protected objects ought to be special in this way. *************************************************************** From: Tucker Taft Sent: Friday, March 2, 2018 2:55 AM I agree this is true of all "immutably limited" types. But the large majority of immutably limited types are that because they contain a task or a protected object, so adding such an identifier to a protected object seemed to solve most of the problem. I wouldn't be averse to a more general solution, but I don't have a proposal for that. *************************************************************** From: Steve Baird Sent: Wednesday, March 28, 2018 6:57 PM Still no wording. Here are the results of some discussions I've had with Randy and Tuck since the summary I sent out a month ago. This includes both decisions (tentatively) made and questions raised. ==== 1) For a task type T, T'Image yields "(task )" or, if discriminants are involved, "(task with D1 => 123, D2 => 456)" 2) For a protected type, there is nothing analogous to the task stuff (because there is nothing analogous to a task_id for protected types). Protected types just get displayed like any other record. 3) The default implementation of Put for a protected type would be implemented as something like procedure Put (X : T; S : access Counted_Stream'Class) is Ignored : constant Dummy_Type := X. (S); begin null; end; where is an anonymous compiler-generated protected function. The idea here is to write out to the stream a consistent snapshot of the state of the protected record, using only one protected action to access all components. The definition given in the RM only needs to say that the default implementation of T'Image where T is a protected type involves calling a protected function. One could imagine making this protected function visible (perhaps via some new attribute), but let's wait until there is some demand for this. 4) Recall that in this new scheme [Wide_[Wide_]]Image is not a user-specifiable attribute. Instead, a new attribute (tentatively named Put) can be specified and Image and friends are defined in terms of Put. Do we want to name this new attribute "Put" or "Put_Image" ? 5) In the absence of a user-specified Put operation, should new discriminants for a derived untagged type have an effect on the image? Presumably yes (at least that's how the streaming attributes work). So the assertion in this example should succeed: type T1 (D1, D2 : Positive) is record ... end record; -- untagged type T2 (D : Positive) is new T1 (D1 => D, D2 => D); X : T2 (D => 123) := ... ; pragma Assert (X'Image /= T1(X)'Image); *************************************************************** From: Steve Baird Sent: Monday, May 28, 2018 5:04 PM Here is a first attempt at !wording for this AI. [This is version /03 of the AI - Editor.] There is also a small !discussion section, but it discusses only a few corner cases; it is by no means complete. For example, the !discussion section lacks a rationale for why the Put_Image attribute/aspect was introduced and why Put_Image is user-specifiable but [Wide_[Wide_]]Image is not. Undoubtedly several rough spots remain (although Randy already caught several for me in his preliminary review), but hopefully this can at least give us a preliminary version to work with. One question I have is whether the level of precision of the description of the default implementations of the T'Put_Image for a composite type T is acceptable. For example, for a record type we pretty much just say that we display components in the canonical order using positional aggregate syntax, displaying component names in upper case and calling each component type's Put_Image procedure to display component values. Then we give an example and that's about it. Given this approach, it is not clear whether these examples belong in normal RM text (which is how I have presented them) or as examples presented separately in an "Examples" section. Take a look at the proposed presentation and see what you think. As always, feedback is appreciated. *************************************************************** From: Randy Brukardt Sent: Wednesday, June 6, 2018 7:35 PM > Here is a first attempt at !wording for this AI. For the record, here's a few editorial-ish things that I did when posting this: (1) You didn't give a !summary or a !proposal. It seemed useful to have the short overview of the default images for each kind of type, so I left that (hopefully I found all of the changes), following a couple introductory paragraphs. The rest was dropped. (2) I moved the example "Put_Image" implementations into the !discussion; they seemed valuable and shouldn't get lost. (Fixing the names, of course, and also fixing the component names in the record case (they were all "C1").) (3) I changed the wording instructions to start with a capital letter. That is "Delete 3.5(...", not "delete 3.5(...". Added a few missing commas into those, too. The paragraph references should mention AARM paragraphs separately, but I didn't fix that yet. (4) "new section 4.10 named "Images":" should say "Add a new subclause 4.10 Images" "Section" is ISO-speak for an entire printed document; 4 is a "clause" and 4.10 (and smaller subdivisions) are "subclauses". (5) "append to the end of the static semantics section of 13.13.1:" We need to give the paragraph number where this happens here. So I replaced this with: "Add after 13.13.1(9) (the end of the static semantics section):" Similarly for the next reference (should be to 13.13.1(9.1/1)). (6) For a discriminated task type, the default implementation of T'Put_Image also includes discriminant values, as in "(TASK with D1 => 123, D2 => 456)" . We aren't even allowed to use a hanging period like this in AI text, much less in the RM. But we don't need the extra indentation anyway, as the example should be in the example font. So this would read better as For a discriminated task type, the default implementation of T'Put_Image also includes discriminant values, as in "(TASK with D1 => 123, D2 => 456)". We're hoping that the editor remembers to mark these examples in the example font, but that's pretty likely (I know him well :-). I reformatted the other examples to match, similar reasoning applies. (7) overriding procedure Read ( Stream : in out Unbounded_Stream; Item : out Stream_Element_Array; Last : out Stream_Element_Offset) The recommended formatting of overriding indicators has them on a separate line from the rest of the subprogram declaration, much like "generic". The RM is supposed to follow this recommended formatting, regardless of what you normally do in your own code. I fixed all of these declarations. =================================== And here are a few minor comments: (C1) except that if the value of T'Max_Image_Elements (see below) is not -1 then the variable Local_Stream is instead declared as Local_Stream : aliased Ada.Streams.Counted_Streams.Unbounded.Unbounded_Stream (Max_Elements => T'Max_Image_Elements); Isn't this case supposed to use the Bounded form of the stream? The Unbounded form doesn't even have a discriminant. I'd guess that "Un" should be deleted from the above text (twice). (C2) Pragma Default_Max_Image_Elements is a configuration pragma which takes a single argument, a static expression of type Ada.Streams.Stream_Offset in the range -1 .. Ada.Streams.Stream_Element_Offset'Last. Pragma Default_Max_Image_Elements shall not be used other than as a configuration pragma. If more than one Default_Max_Image_Elements pragma applies to a given compilation unit, then they shall all specify equal (static) Stream_Element_Offset values. I'm not sure that we can use such a short definition of a pragma. All pragmas that I can think of give a syntax definition; even List and Page do that. So I think we need to define the "form" of this pragma, with a Syntax portion. (Ugh, I know.) (C3) You probably ought to add a paragraph to the discussion describing the model and use of Bounded_Stream. I know why it's there ('cause you told me), but it doesn't seem to be mentioned anywhere in the AI. (C4) You deleted all of the AARM notes along with the original definition of Wide_Wide_Image, but you didn't put them back into the discussion of the default images of the various types. That seems like (relatively) important information about topics like Negative Zeros and rounding is getting lost. The Impldef information for Wide_Image and Image definitely has to move (so the annex M.1 listing doesn't lose them). A similar thought applies to 55.b/5. (C5) Under the image of arrays, you have: This might generate an image such as "( 1 => ( 1 => ( 123 => True, 124 => False), 2 => ( 123 => False, 124 => False)), 2 => ( 1 => ( 123 => True, 124 => True), 2 => ( 123 => True, 124 => False)))" This is too long for a line in the RM. It will get folded somehow, and that would probably give an incorrect interpretation of the actual result. (I see this e-mail editor folded it!) I don't know what the appropriate answer is here, but this can't be in the RM as written; we need an alternative that fits in one line or additional wording to explain the extra line breaks. (C6) For a prefix X that denotes an object of a non-universal type T, the following attributes are defined: This is wrong, unless you mean to disallow using 'Image on a universal integer object. And if you meant to do that, you need to explain why and explain the (significant) incompatibility in the !discussion section. Moreover, you've reintroduced the object bug fixed in AI12-0225-1. We don't want X to have to denote an object! Otherwise, this should read: For a prefix X of a type other than universal_real or universal_fixed, the following attributes are defined: Perhaps you need to make a similar change to Put_Image; there's no problem defining it for the (dynamic) universal_integer type (that is the largest signed integer type). You can't *redefine* that attribute, but that shouldn't matter. (C7) We've previously discussed in passing the need for Ada to have "marshalling" streams. (Claw has had those since 1999 - we needed them to pack/unpack binary clipboard and registry contents - items that have to be read/written in a single operation.) You're actually adding them sort of by the back door. I have to wonder if they ought to have a bit more visibility and if the names are right -- these packages fulfill an important need having nothing to do with Image. We have a "Clear" operation to discard the contents - that seems useful in more general usage, even if Put_Image will never need it. We also had an initial size discriminant for the unbounded form. Not as sure if that's useful, or if there should be some Reserve_Capacity operation for the unbounded form. (We did it that way for the containers.) (C99) "If a protected type T has protected subcomponents, then the default implementation of T'Put_Image will probably violate the no-potentially-blocking-ops-during-a-protected-action rule. Do we want any sort of legality rules relating to this? In evaluating any possible rules relating to this scenario, keep in mind the case of a protected type declared in the body of a generic unit with a subcomponent of a formal limited private type whose corresponding actual type, for some particular instance of the generic, is a protected type." I guess it couldn't be a Steve Baird AI without at least one such case. *Everyone* is worried about taking the image of a protected object declared in a generic body with a component of a formal limited private type. Happens every other day! ;-) ***************************************************************