# Ada Programming/Libraries/Ada.Streams/Example

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

## 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 'c' is for "car," 't' is for "truck," 'b' is for "bicycle."
* Next it comes the vehicle speed, represented as an integer number encoded as "<len> i <value>" where
** <value> is the speed value, expressed as a number in base 10 with <len> digits
** <len> is the length of the <value> 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'Class'Input that will work as follows
** it reads the first octet (by using Character'Read) and uses it to determine the type of vehicle
** it creates the object corresponding to the required vehicle type
** it calls Abstract_Vehicle'Class'Read 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'Class'Output 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'Write
** it calls Abstract_Vehicle'Class'Write 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'Read and Int'Write that will read and write variables of type Int encoded in the format "<len> i <value>" 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'Class'Input function described we cannot use a case 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 3.9 Tagged Types and Type Extensions (Annotated)).
* 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 Ada.Tags.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 begin in the package body, see 7.2 Package Bodies (Annotated)) by writing the tag of the defined vehicle in the suitable position of that array.

## Implementation
### 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 Read and Write that serialize integer values according to the format described above. The package specs are quite simple
The new type is Int and the procedure assigned to attributes Read and Write are, respectively, Parse and Read. Also the body is quite simple
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.
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
Note the behavior of Input_Vehicle, the function that will play the role of class-wide input.
* First it reads the character associated to the next vehicle in the stream by using the stream-related function Character'Read.
* Successively it uses the character read to find the tags of the object to be created
* It creates the object by calling the specialized version of Generic_Dispatching_Constructor
* 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.

### Non-Abstract Vehicles
#### 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
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
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.
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
The body of Vehicles.Bicycles

## See also
### Wikibook

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

### Ada 2005 Reference Manual

* 3.9 Tagged Types and Type Extensions (Annotated)
* 7.2 Package Bodies (Annotated)
* 13.13.1 The Package Streams (Annotated)
* 13.13.2 Stream-Oriented Attributes (Annotated)