Ada Programming/Libraries/Ada.Streams/Example

This page gives a (fairly complex) example of usage of class-wide stream related attributes ', ', ', and '.

The problem
The problem we will consider is the following: suppose that two hosts communicate over a TCP connection, exchanging information about vehicles. Each vehicle is characterized by its type (a car, a truck, a bicycle, and so on), its maximum speed (in km/h, represented by an integer number) and a set of further parameters that depend on the vehicle type. For example, a car could have a parameter "number of passengers," while a truck could have a parameter "maximum load" (an integer number of kg). For the sake of simplicity we will suppose that every parameter is represented by an integer number.

The protocol used to communicate vehicle data over the wire is text-based and it is as follows


 * The first octet is a character that denotes the vehicle type. For example  is for "car,"  is for "truck,"  is for "bicycle."
 * Next it comes the vehicle speed, represented as an integer number encoded as "&lt;len&gt; i &lt;value&gt;" where
 * &lt;value&gt; is the speed value, expressed as a number in base 10 with &lt;len&gt; digits
 * &lt;len&gt; is the length of the &lt;value&gt; field, expressed as a number in base 10. This field can have trailing spaces For example, the integer 256 would be encoded as "3i256".
 * The speed value is followed by the list of vehicle-specific parameter, encoded with the same format of the speed field.

We would like to use the features of Ada streams to read and write vehicle information from and to any "medium" (e.g., a network link, a file, a buffer in memory) and we would like to use the object-oriented features of Ada in order to simplify the introduction of a new type of vehicle.

The solution
This is a sketch of the proposed solution


 * We will create a hierarchy of objects to represent the vehicle types. More precisely, we will represent each vehicle as a descendant of an abstract type (Abstract_Vehicle)
 * Reading from a stream will be done via function Abstract_Vehicle'' that will work as follows
 * it reads the first octet (by using Character') and uses it to determine the type of vehicle
 * it creates the object corresponding to the required vehicle type
 * it calls Abstract_Vehicle'' by giving to it the newly created object in order to read it from the stream
 * Writing to a stream will be done via procedure Abstract_Vehicle'' that will work as follows
 * it checks the object tag and uses it to determine the first character to be written to the stream
 * it writes the first character to the stream by using Character'
 * it calls Abstract_Vehicle'' to write the object description to the stream
 * We will derive a new type Int from Integer and we will define for it new procedures Int' and Int' that will read and write variables of type Int encoded in the format "&lt;len&gt; i &lt;value&gt;" described above
 * In order to allow for the introduction of new vehicle types (maybe by dynamically loading a library at runtime), at the step 2 of the Abstract_Vehicle'' function described we cannot use a  on the character read in order to determine the type of the object to be created.  We will instead use the generic dispatching constructor provided by Ada (see ).
 * Since the generic dispatching constructor requires the tag of the object to be created, we must be able to determine the tag that corresponds to a given character. We will achieve this by keeping an array of .Tag indexed by character.  A package defining a new vehicle will "register" itself in the initialization part of the package (that is, the sequence of statements that follows the  in the package body, see ) by writing the tag of the defined vehicle in the suitable position of that array.

Streamable types
The first package that we are going to analyze is a package that defines a new integer type in order to assign to it attributes and  that serialize integer values according to the format described above. The package specs are quite simple

;             Streamable_Types ;      Int    Integer; Print (Stream :   .Root_Stream_Type';                       Item   : Int); Parse (Stream :   .Root_Stream_Type';                       Item   :  Int); Int' Parse; Int' Print; Parsing_Error : ; Streamable_Types;

The new type is Int and the procedure assigned to attributes and  are, respectively, Parse and Read. Also the body is quite simple

;      Streamable_Types Streams; Print (Stream :   Root_Stream_Type'Class;                       Item   : Int) Value   : String := Strings.Fixed.Trim (Int'Image (Item), Strings.Left); Len     : String := Integer'Image (Value'Length); Complete : String := Len & 'i' & Value; Buffer  : Stream_Element_Array (Stream_Element_Offset (Complete'First) .. Stream_Element_Offset (Complete'Last)); I Buffer'Range Buffer (I) := Stream_Element (Character'Pos (Complete (Integer (I)))); ;        Stream.Write (Buffer); Print; ---     -- Parse -- ---      Parse (Stream :    Root_Stream_Type'Class;                       Item   :  Int) Buffer : Stream_Element_Array (1 .. 1); Last  : Stream_Element_Offset; Zero  :  Stream_Element := Stream_Element (Character'Pos ('0')); Nine  :  Stream_Element := Stream_Element (Character'Pos ('9')); Space :  Stream_Element := Stream_Element (Character'Pos (' ')); Skip_Spaces Stream.Read (Buffer, Last); Buffer (1) /= Space; ;         Skip_Spaces; Read_Length (Len : Integer) (Buffer (1) Zero .. Nine) Parsing_Error; ;           Len := 0; Len := Len * 10 + Integer (Buffer (1) - Zero); Stream.Read (Buffer, Last); (Buffer (1) in Zero .. Nine); ;         Read_Length; Read_Value (Item : Int;                               Len  :   Integer) Item := 0; I 1 .. Len Stream.Read (Buffer, Last); (Buffer (1) Zero .. Nine) Parsing_Error; ;              Item := 10 * Item + Int (Buffer (1) - Zero); ;         Read_Value; Len : Integer := 0; Skip_Spaces; Read_Length (Len); Character'Val (Integer (Buffer (1))) /= 'i'             Parsing_Error; ;        Read_Value(Item, Len); Parse; Streamable_Types;

The body of Streamable_Types should not require any special comment. Note how the access to the stream is done by dispatching through the primitive procedures Read and Write, allowing the package above to work with any type of stream.

Abstract Vehicles
The second package we are going to analyze is Vehicles that define an abstract tagged type Abstract_Vehicle that represents the "least common denominator" of all the possible vehicles.

Ada.Streams; Ada.Tags; Streamable_Types; Vehicles Abstract_Vehicle   ; Input_Vehicle (Stream :   Ada.Streams.Root_Stream_Type'Class) Abstract_Vehicle'Class; Output_Vehicle (Stream :   Ada.Streams.Root_Stream_Type'Class;         Item   : Abstract_Vehicle'Class); Abstract_Vehicle'Class'Input Input_Vehicle; Abstract_Vehicle'Class'Output Output_Vehicle; Parameter_Record  ; Constructor (Name :   Parameter_Record) Abstract_Vehicle ;      Register_Name (Name        : Character;                               Object_Tag  : Ada.Tags.Tag); Kmh  Streamable_Types.Int; Kg   Streamable_Types.Int; Abstract_Vehicle Speed : Kmh; Weight : Kg; ;   Vehicles;

This package defines


 * Function Input_Vehicle and procedure Output_Vehicle to be used, respectively, as class-wide input and output procedures
 * Abstract constructor "Constructor" that every non-abstract type derived by Vehicle must override. This constructor will be called by Generic_Dispatching_Constructor in the body.
 * Procedure Register_Name that associates a vehicle "name" (represented by a character in this simplified case) to the corresponding type (represented by its Tag). In the typical case this procedure will be called by the package that derives from Abstract_Vehicle in the body initialization part

The body of the package is

Ada.Tags.Generic_Dispatching_Constructor; Vehicles Name_To_Tag : (Character)  Ada.Tags.Tag := ( => Ada.Tags.No_Tag); Input_Vehicle (Stream :   Ada.Streams.Root_Stream_Type'Class) Abstract_Vehicle'Class Construct_Vehicle Ada.Tags.Generic_Dispatching_Constructor (T => Abstract_Vehicle,             Parameters => Parameter_Record,              Constructor => Constructor); Param : Parameter_Record; Name : Character; Ada.Tags; Character'Read (Stream, Name); Name_To_Tag (Name) = Ada.Tags.No_Tag then Constraint_Error; ;           Result : Abstract_Vehicle'Class := Construct_Vehicle (Name_To_Tag (Name), Param'); Abstract_Vehicle'Class'Read (Stream, Result); Result; ;      Input_Vehicle; Output_Vehicle (Stream :   Ada.Streams.Root_Stream_Type'Class;         Item   : Abstract_Vehicle'Class) Ada.Tags; Name Name_To_Tag'Range Name_To_Tag (Name) = Item'Tag Character'Write (Stream, Name); Abstract_Vehicle'Class'Write (Stream, Item); ;            ;          ;          Constraint_Error; Output_Vehicle; Register_Name (Name       : Character;                               Object_Tag  : Ada.Tags.Tag) Name_To_Tag (Name) := Object_Tag; Register_Name; Vehicles;

Note the behavior of Input_Vehicle, the function that will play the role of class-wide input.


 * 1) First  it reads the character associated to the next vehicle in the stream by using the stream-related function Character'Read.
 * 2) Successively it uses the character read to find the tags of the object to be created
 * 3) It creates the object by calling the specialized version of Generic_Dispatching_Constructor
 * 4) It "fills" the newly created object by calling the class-wide Read that will take care of calling the Read associated to the newly created object

Procedure Output_Vehicle is much simpler than Input_Vehicle since it does not need to use the Generic_Dispatching_Constructor. Just note the call to Abstract_Vehicle'Class'Write that in turn will call the Write function associated to the actual type of Item.

Finally, note that Abstract_Vehicle does not define the Read and Write attributes. Therefore, Ada will use their default implementation. For example, Abstract_Vehicle'Read will read the two Streamable_Types.Int value Speed and Weight by calling twice the procedure Streamable_Types.Int'Read. A similar remark apply to Abstract_Vehicle'Write.

Car
The first non-abstract type derived from Abstract_Vehicle that we consider represents a car. In order to make the example a bit more rich, Car will be derived from an intermediate abstract type representing an engine-based vehicle. All engine-based vehicles will have a field representing the power of the engine (still an integer value, for the sake of simplicity). The spec file is as follows

Vehicles.Engine_Based Abstract_Engine_Based   Abstract_Vehicle  ; Abstract_Engine_Based   Abstract_Vehicle Power : Streamable_Types.Int; ;   Vehicles.Engine_Based;

Note that also in this case we did not define any Read or Write procedure. Therefore, for example, Abstract_Engine_Based'Read will first call Streamable_Types.Int twice to read Speed and Weight (inherited from Abstract_Vehicle) from the stream, then it will call Streamable_Types.Int another time to read Power.

Note also that Abstract_Engine_Based does not override the abstract function Constructor of Abstract_Vehicle. This is not necessary since Abstract_Engine_Based is abstract.

The spec file of the package that defines the Car type is as follows

Vehicles.Engine_Based.Auto Ada.Streams; Car  Abstract_Engine_Based  ; Parse (Stream :   Root_Stream_Type'Class;        Item   :  Car); Car'Read Parse; Car  Abstract_Engine_Based Cilinders : Streamable_Types.Int; ;     Constructor (Param :   Parameter_Record) Car; Vehicles.Engine_Based.Auto;

No special remarks are needed about the spec file. Just note that Car defines a special Read procedure and that it overrides Construct, as required since Car is not abstract.

Vehicles.Engine_Based.Auto Parse (Stream :   Root_Stream_Type'Class;         Item   :  Car) Abstract_Engine_Based'Read (Stream, Abstract_Engine_Based (Item)); Streamable_Types.Int'Read (Stream, Item.Cilinders); Parse; Constructor (Param :   Parameter_Record) Car Result : Car; Warnings(Off, Result); Result; Constructor; Register_Name('c', Car'Tag); Vehicles.Engine_Based.Auto;

The body of Vehicles.Engine_Based.Auto is quite simple too, just note that


 * Procedure Parse (used as Car'Read) first calls Abstract_Engine_Based'Read to "fill" the part inherited from Abstract_Engine_Based, then it calls Streamable_Types.Int'Read to read the number of cylinders. Incidentally, note that this is equivalent to the default behavior, so it was not really necessary to define Parse.  We did it just to make an example.
 * Note the call to Register_Name in the body initialization part that associates the name 'c' with the tag of type Car (obtained via the attribute 'Tag). An interesting property of this solution is that the information about the "external name" 'c' of objects of type Car is knew only inside the package Vehicles.Engine_Based.Auto.

Bicycle
The spec file of Vehicles.Bicycles

Ada.Streams; Vehicles.Bicycles Ada.Streams; Bicycle  Abstract_Vehicle  ; Parse (Stream :   Root_Stream_Type'Class;        Item   :  Bicycle); Bicycle'Read Parse; Wheel_Count  Streamable_Types.Int  1 .. 3;     Bicycle   Abstract_Vehicle Wheels : Wheel_Count; ;     Constructor (Name :   Parameter_Record) Bicycle; Vehicles.Bicycles;

The body of Vehicles.Bicycles Vehicles.Bicycles Ada.Streams; Parse (Stream :   Root_Stream_Type'Class;         Item   :  Bicycle) Abstract_Vehicle'Read (Stream, Abstract_Vehicle (Item)); Wheel_Count'Read (Stream, Item.Wheels); Parse; Constructor (Name :   Parameter_Record) Bicycle Result : Bicycle; Warnings(Off, Result); Result; Constructor; Register_Name ('b', Bicycle'Tag); Vehicles.Bicycles;

Wikibook

 * Ada Programming
 * Ada Programming/Object Orientation
 * Ada Programming/Input Output
 * Ada Programming/Libraries/Ada.Streams