# Ada Programming/Packages


Ada encourages the division of code into separate modules called
*packages*. Each package can contain any combination of items.

Some of the benefits of using packages are:

-   package contents are placed in a separate namespace, preventing
    naming collisions,
-   implementation details of the package can be hidden from the
    programmer (information hiding),
-   object orientation requires defining a type and its primitive
    subprograms within a package, and
-   packages that are library units can be separately compiled.

Some of the more common package usages are:

-   a group of related subprograms along with their shared data, with
    the data not visible outside the package,
-   one or more data types along with subprograms for manipulating those
    data types, and
-   a generic package that can be instantiated under varying conditions.

The following is a quote from the current Ada Reference Manual


## Separate compilation

Note: The following chapters deal with packages on *library level*. This
is the most common use, since packages are the basic code structuring
means in Ada. However, Ada being a block oriented language, packages can
be declared at any level in any declarative region. In this case, the
normal visibility rules apply, also for the package body.

Package specifications and bodies on library level are compilation
units, so can be separately compiled. Ada has nothing to say about how
and where compilation units are stored. This is implementation
dependent. (Most implementations indeed store compilation units in files
of their own; name suffixes vary, GNAT uses `.ads` and `.adb`,
APEX `.1.ada` and
`.2.ada`.) The package body can itself be divided into multiple parts by
specifying that subprogram implementations or bodies of nested packages
are **separate**. These are then further compilation units.

One of the biggest advantages of Ada over most other programming
languages is its well-defined system of modularization and separate
compilation. Even though Ada allows separate compilation, it maintains
the strong type checking among the various compilations by enforcing
rules of compilation order and compatibility checking. Ada compilers
determine the compilation sequence; no make file is needed. Ada uses
separate compilation (like Modula-2,
Java and
C#), and not independent
compilation (as
C/C++ does),
in which the various parts are compiled with no knowledge of the other
compilation units with which they will be combined.

A note to C/C++ users: Yes, you can use the preprocessor to emulate
separate compilation --- but it is only an emulation and the smallest
mistake leads to very hard to find bugs. It is telling that all C/C++
successor languages including D
have turned away from the independent compilation and the use of the
preprocessor.

So it\'s good to know that Ada has had separate compilation ever since
Ada-83 and is probably the most sophisticated implementation around.

## Parts of a package

A package generally consists of two parts, the specification and the
body. A package specification can be further divided in two logical
parts, the visible part and the private part. Only the visible part of
the specification is mandatory. The private part of the specification is
optional, and a package specification might not have a package
body---the package body only exists to complete any *incomplete* items
in the specification. Subprogram declarations are the most common
*incomplete* items. There must not be a package body if there is no
incomplete declaration, and there has to be a package body if there is
some incomplete declaration in the specification.

To understand the value of the three-way division, consider the case of
a package that has already been released and is in use. A change to the
visible part of the specification will require that the programmers of
all using software verify that the change does not affect the using
code. A change to the private part of the declaration will require that
all using code be recompiled but no review is normally needed. Some
changes to the private part can change the meaning of the client code
however. An example is changing a private record type into a private
access type. This change can be done with changes in the private part,
but change the semantic meaning of assignment in the clients code. A
change to the package body will only require that the file containing
the package body be recompiled, because *nothing* outside of the package
body can ever access anything within the package body (beyond the
declarations in the specification part).

A common usage of the three parts is to declare the existence of a type
and some subprograms that operate on that type in the visible part,
define the actual structure of the type (e.g. as a record) in the
private part, and provide the code to implement the subprograms in the
package body.

### The package specification --- the visible part

The visible part of a package specification describes all the subprogram
specifications, variables, types, constants etc. that are visible to
anyone who wishes to use the package.

` Public_Only_Package `\
\
`  `` Range_10 `` `` 1 .. 10;`\
\
` Public_Only_Package;`

Since Range_10 is an integer type, there are a lot of operations
declared implicitly in this package.

### The private part

The private part of a package serves two purposes:

-   To complete the deferred definition of private types and constants.
-   To export entities only visible to the children of the package.

` Package_With_Private `\
`     `\
`   `` Private_Type `` ``;`\
\
\
\
`   `` Private_Type `` `` (1 .. 10) `` Integer;`\
\
` Package_With_Private;`

Since the type is private, clients cannot make any use of it as long as
there are no operations defined in the visible part.

### The package body

The package body defines the implementation of the package. All the
subprograms defined in the specification have to be implemented in the
body. New subprograms, types and objects can be defined in the body that
are not visible to the users of the package.

` Package_With_Body `\
\
`   `` Basic_Record `` ``;`\
\
`   `` Set_A (This : `` `` Basic_Record;`\
`                    An_A : ``     Integer);`\
\
`   `` Get_A (This : Basic_Record) `` Integer;`\
\
\
\
`   `` Basic_Record `` `\
`      `` `\
`         A : Integer;`\
`      `` `` ;`\
\
`   ``  (Get_A);  -- not a standard Ada pragma`\
`   `` (Get_A);`\
`   `` (Set_A);`\
\
` Package_With_Body;`

` `` Package_With_Body `\
\
`   `` Set_A (This : `` `` Basic_Record;`\
`                    An_A : ``     Integer) `\
`   `\
`      This.A := An_A;`\
`   `` Set_A;`\
\
`   `` Get_A (This : Basic_Record) `` Integer `\
`   `\
`      `` This.A;`\
`   `` Get_A;`\
\
` Package_With_Body;`

: Only available when using GNAT.

### Two Flavors of Package

The packages above each define a type together with operations of the
type. When the type\'s composition is placed in the private part of a
package, the package then exports what is known to be an Abstract Data
Type or ADT for short. Objects of the
type are then constructed by calling one of the subprograms associated
with the respective type.

A different kind of package is the Abstract State Machine or ASM. A
package will be modeling a single item of the problem domain, such as
the motor of a car. If a program controls one car, there is typically
just one motor, or *the* motor. The public part of the package
specification only declares the operations of the module (of the motor,
say), but no type. All data of the module are hidden in the body of the
package where they act as state variables to be queried, or manipulated
by the subprograms of the package. The initialization part sets the
state variables to their initial values.

` Package_With_Body `\
\
`   `` Set_A ``An_A `` `` Integer`\
\
`   `` Get_A `` Integer`\
\
\
\
`   `` Pure_Function ``Get_A``—not a standard Ada pragma`\
\
` Package_With_Body`

` `` Package_With_Body `\
\
`   The_A`` Integer`\
\
`   `` Set_A ``An_A `` `` Integer`` `\
`   `\
`      The_A `` An_A`\
`   `` Set_A`\
\
`   `` Get_A `` Integer `\
`   `\
`      `` The_A`\
`   `` Get_A`\
\
\
\
\
`   The_A `` 0`\
\
` Package_With_Body`

(A note on construction: The package initialization part after
 corresponds to a construction subprogram
of an ADT package. However, as a state machine *is* an "object" already,
"construction" is happening during package initialization. (Here it sets
the state variable `The_A` to its initial value.) An ASM package can be
viewed as a singleton.)

## Using packages

To utilize a package it\'s needed to name it in a **with** clause,
whereas to have direct visibility of that package it\'s needed to name
it in a **use** clause.

For C++ programmers, Ada\'s **with** clause is analogous to the C++
preprocessor\'s **#include** and Ada\'s **use** is similar to the
**using namespace** statement in C++. In particular, **use** leads to
the same namespace pollution problems as **using namespace** and thus
should be used sparingly. Renaming can shorten long compound names to a
manageable length, while the **use type** clause makes a type\'s
operators visible. These features reduce the need for plain **use**.

### Standard with

The standard with clause provides visibility for the public part of a
unit to the following defined unit. The imported package can be used in
any part of the defined unit, including the body when the clause is used
in the specification.

### Private with

` `` Ada.Strings.Unbounded; `\
\
` Private_With `\
\
`   `\
\
`   `` Basic_Record `` ``;`\
\
`   `` Set_A (This : `` `` Basic_Record;`\
`                    An_A : ``     String);`\
\
`   `` Get_A (This : Basic_Record) `` String;`\
\
\
`   `\
\
`   `` Unbounded `` Ada.Strings.Unbounded;`\
\
`   `` Basic_Record `` `\
`      `` `\
`         A : Unbounded.Unbounded_String;`\
`      `` ``;`\
\
`   ``  (Get_A);`\
`   `` (Get_A);`\
`   `` (Set_A);`\
\
` Private_With;`

` `` Private_With `\
\
`   `\
\
`   `` Set_A (This : `` `` Basic_Record;`\
`                    An_A : ``     String)`\
`   `\
`   `\
`      This.A := Unbounded.To_Unbounded_String (An_A);`\
`   `` Set_A;`\
\
`   `` Get_A (This : Basic_Record) `` String `\
`   `\
`      `` Unbounded.To_String (This.A);`\
`   `` Get_A;`\
\
` Private_With;`

### Limited with

The limited with can be used to represent two mutually dependent type
(or more) located in separate packages.

` `` Departments;`\
\
` Employees `\
\
`   `` Employee `` `` ``;`\
\
`   `` Assign_Employee`\
`     (E : `` `` Employee;`\
`      D : `` Departments.Department'``);`\
\
`   `` Dept_Ptr `` `` `` Departments.Department'``;`\
\
`   `` Current_Department(E : `` Employee) `` Dept_Ptr;`\
`   ...`\
` Employees;`

` `` Employees;`\
\
` Departments `\
\
`   `` Department `` `` ``;`\
\
`   `` Choose_Manager`\
`     (Dept    : `` `` Department;`\
`      Manager : `` Employees.Employee'``);`\
`   ...`\
` Departments;`

### Making operators visible

Suppose you have a package Universe that defines some numeric type T.

` Universe`\
` P `\
`  V`` Universe``T `` 10``0`\
\
`  V `` V `` 42``0``  `\
` P`

This program fragment is illegal since the operators implicitly defined
in Universe are not directly visible.

You have four choices to make the program legal.

Use a use_package_clause. This makes **all declarations** in Universe
directly visible (provided they are not hidden because of other
homographs).

` Universe`\
`  Universe`\
` P `\
`  V`` Universe``T `` 10``0`\
\
`  V `` V `` 42``0`\
` P`

Use renaming. This is error prone since if you rename many operators,
cut and paste errors are probable.

` Universe`\
` P `\
`  `` "*" ``Left`` Right`` Universe``T`` `` Universe``T `` Universe``"*"`\
`  `` "/" ``Left`` Right`` Universe``T`` `` Universe``T `` Universe``"*"``  `\
`  V`` Universe``T `` 10``0`\
\
`  V `` V `` 42``0`\
` P`

Use qualification. This is extremely ugly and unreadable.

` Universe`\
` P `\
`  V`` Universe``T `` 10``0`\
\
`  V `` Universe``"*" ``V`` 42``0`\
` P`

Use the use_type_clause. This makes only the **operators** in Universe
directly visible.

` Universe`\
` P `\
`  V`` Universe``T `` 10``0`\
`  `` `` Universe``T`\
\
`  V `` V `` 42``0`\
` P`

There is a special beauty in the use_type_clause. Suppose you have a set
of packages like so:

` Universe`\
` Pack `\
`  `` T `` Universe``T`\
` Pack`

` Pack`\
` P `\
`  V`` Pack``T `` 10``0`\
\
`  V `` V `` 42``0``  `\
` P`

Now you\'ve got into trouble. Since Universe is not made visible, you
cannot use a use_package_clause for Universe to make the operator
directly visible, nor can you use qualification for the same reason.
Also a use_package_clause for Pack does not help, since the operator is
not defined in Pack. The effect of the above construct means that the
operator is not nameable, i.e. it cannot be renamed in a renaming
statement.

Of course you can add Universe to the context clause, but this may be
impossible due to some other reasons (e.g. coding standards); also
adding the operators to Pack may be forbidden or not feasible. So what
to do?

The solution is simple. Use the use_type_clause for Pack.T and all is
well!

` Pack`\
` P `\
`  V`` Pack``T `` 10``0`\
`  `` `` Pack``T`\
\
`  V `` V `` 42``0`\
` P`

## Package organisation

### Nested packages

A nested package is a package declared inside a package. Like a normal
package, it has a public part and a private part. From outside, items
declared in a nested package N will have visibility as usual; the
programmer may refer to these items using a full dotted name like
`P.N.X`. (But not `P.M.Y`.)

` P `\
`   D`` Integer`\
\
`   `\
`   `` N `\
`      X`` Integer`\
`   `\
`      Foo`` Integer`\
`   `` N`\
\
`   E`` Integer`\
\
`   `\
`   `` M `\
`      Y`` Integer`\
`   `\
`      Bar`` Integer`\
`   `` M`\
\
` P`

Inside a package, declarations become visible as they are introduced, in
textual order. That is, a nested package N that is declared *after* some
other declaration D can refer to this declaration D. A declaration E
following N can refer to items of N.[^1] But neither can "look ahead"
and refer to any declaration that goes after them. For example, spec `N`
above cannot refer to `M` in any way.

In the following example, a type is derived in both of the two nested
packages `Disks` and `Books`. Notice that the full declaration of parent
type `Item` appears before the two nested packages.

` `` `` `\
\
` Shelf `\
\
`   `` Elaborate_Body`\
\
`   `\
\
`   `` ID `` `` 1_000 `` 9_999`\
`   `` Item ``Identifier `` ID`` `` `` `` `` `` `\
`   `` Item_Ref `` `` `` Item`\
\
`   `` Next_ID `` ID`\
`   `\
\
\
`   `` Disks `\
\
`      `` Music `` `\
`         Jazz`\
`         Rock`\
`         Raga`\
`         Classic`\
`         Pop`\
`         Soul`\
\
`      `` Disk ``Style `` Music`` Identifier `` ID`` `` `` Item ``Identifier`\
`         `` `\
`            Artist `` Unbounded_String`\
`            Title  `` Unbounded_String`\
`         `` `\
\
`   `` Disks`\
\
\
`   `` Books `\
\
`      `` Literature `` `\
`         Play`\
`         Novel`\
`         Poem`\
`         Story`\
`         Text`\
`         Art`\
\
`      `` Book ``Kind `` Literature`` Identifier `` ID`` `` `` Item ``Identifier`\
`         `` `\
`            Authors `` Unbounded_String`\
`            Title   `` Unbounded_String`\
`            Year    `` Integer`\
`         `` `\
\
`   `` Books`\
\
`   `\
\
`   `` Put ``it`` Item_Ref`\
`   `` Get ``identifier `` ID`` `` Item_Ref`\
`   `` Search ``title `` String`` `` ID`\
\
\
\
`   `\
\
`   `` Boxes `\
`      `` Treasure``Identifier`` ID`` `` `` `\
`   `\
`      `` Treasure``Identifier`` ID`` `` `` Item``Identifier`` `` `` `\
`   `` Boxes`\
\
` Shelf`

A package may also be nested inside a subprogram. In fact, packages can
be declared in any declarative part, including those of a block.

### Child packages

Ada allows one to extend the functionality of a unit (package) with
so-called children (child packages). With certain exceptions, all the
functionality of the parent is available to a child. This means that all
public and private declarations of the parent package are visible to all
child packages.

The above example, reworked as a hierarchy of packages, looks like this.
Notice that the package
 is not needed by the
top level package `Shelf`, hence its with clause doesn\'t appear here.
(We have added a match function for searching a shelf, though):

` Shelf `\
\
`   `` Elaborate_Body`\
\
`   `` ID `` `` 1_000 `` 9_999`\
`   `` Item ``Identifier `` ID`` `` `` `` `` `` `\
`   `` Item_Ref `` `` `` Item`\
\
`   `` Next_ID `` ID`\
`   `\
\
`   `` match ``it `` Item`` Text `` String`` `` Boolean `` `\
`   `\
\
\
`   `\
\
`   `` Put ``it`` Item_Ref`\
`   `` Get ``identifier `` ID`` `` Item_Ref`\
`   `` Search ``title `` String`` `` ID`\
\
` Shelf`

The name of a child package consists of the parent unit\'s name followed
by the child package\'s identifier, separated by a period (dot)
\`\'.

` `` `` `\
\
` Shelf``Books `\
\
`   `` Literature `` `\
`      Play`\
`      Novel`\
`      Poem`\
`      Story`\
`      Text`\
`      Art`\
\
`   `` Book ``Kind `` Literature`` Identifier `` ID`` `` `` Item ``Identifier`\
`      `` `\
`         Authors `` Unbounded_String`\
`         Title   `` Unbounded_String`\
`         Year    `` Integer`\
`      `` `\
\
`   `` match``it`` Book`` text`` String`` `` Boolean`\
\
` Shelf``Books`

`Book` has two components of type `Unbounded_String`, so
 appears in a with
clause of the child package. This is unlike the nested packages case
which requires that all units needed by any one of the nested packages
be listed in the context clause of the enclosing package (see
).
Child packages thus give better control over package dependences. With
clauses are more local.

The new child package `Shelf.Disks` looks similar. The `Boxes` package
which was a nested package in the private part of the original `Shelf`
package is moved to a private child package:

` `` Shelf``Boxes `\
`    `` Treasure``Identifier`` ID`` `` `` `\
\
`    `` Treasure``Identifier`` ID`` `` `` Item``Identifier`` `` `` `\
`    `` match``it`` Treasure`` text`` String`` `` Boolean`\
` Shelf``Boxes`

The privacy of the package means that it can only be used by equally
private client units. These clients include private siblings and also
the bodies of siblings (as bodies are never public).

Child packages may be listed in context clauses just like normal
packages. A  of a child also \'withs\'
the parent.

### Subunits

A subunit is just a feature to move a body into a place of its own when
otherwise the enclosing body will become too large. It can also be used
for limiting the scope of context clauses.

The subunits allow to physically divide a package into different
compilation units without breaking the logical unity of the package.
Usually each separated subunit goes to a different file allowing
separate compilation of each subunit and independent version control
history for each one.

` `` `` Pack `\
`   `` Proc `` `\
` `` Pack`\
\
` `` Some_Unit`\
` `` ``Pack`\
` `` Proc `\
` `\
`   ...`\
` `` Proc`

## Notes

```{=html}
<references/>
```
## See also

### Wikibook

-   Ada Programming

### Wikipedia

-   Module "wikilink")

### Ada 95 Reference Manual

-   
### Ada 2005 Reference Manual

-   
Programming}}\|Packages Ada
Programming}}/Unfinished module\|Packages

es:Programación en
Ada/Paquetes

[^1]: For example, `E: Integer := D + N.X;`
