|
DataMuseum.dkPresents historical artifacts from the history of: Rational R1000/400 Tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about Rational R1000/400 Tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - downloadIndex: C T
Length: 94879 (0x1729f)
Types: TextFile
Names: »CHAPTER_14«
└─⟦180fe333a⟧ Bits:30000405 8mm tape, Rational 1000, SW CATALOG, 10_20_0
└─⟦180fe333a⟧ Bits:30000537 8mm tape, Rational 1000, SW Catalog 10_20_0
└─⟦5cb1d1d7f⟧ »DATA«
└─⟦3b1ee7bd8⟧
└─⟦this⟧
14. Input-Output
Input-output is provided in the language by means of predefined packages.
The generic packages SEQUENTIAL_IO and DIRECT_IO define input-output
operations applicable to files containing elements of a given type.
Additional operations for text input-output are supplied in the package
TEXT_IO. The package IO_EXCEPTIONS defines the exceptions needed by the
above three packages. Finally, a package LOW_LEVEL_IO is provided for
direct control of peripheral devices.
References: direct_io package 14.2 14.2.4, io_exceptions package 14.5,
low_level_io package 14.6, sequential_io package 14.2 14.2.2, text_io
package 14.3
14.1 External Files and File Objects
Values input from the external environment of the program, or output to the
environment, are considered to occupy external files. An external file can
be anything external to the program that can produce a value to be read or
receive a value to be written. An external file is identified by a string
(the name). A second string (the form) gives further system-dependent
characteristics that may be associated with the file, such as the physical
organization or access rights. The conventions governing the
interpretation of such strings must be documented in Appendix F.
Input and output operations are expressed as operations on objects of some
file type, rather than directly in terms of the external files. In the
remainder of this chapter, the term file is always used to refer to a file
object; the term external file is used otherwise. The values transferred
for a given file must all be of one type.
Input-output for sequential files of values of a single element type is
defined by means of the generic package SEQUENTIAL_IO. The skeleton of
this package is given below.
with IO_EXCEPTIONS;
generic
type ELEMENT_TYPE is private;
package SEQUENTIAL_IO is
type FILE_TYPE is limited private;
type FILE_MODE is (IN_FILE, OUT_FILE);
...
procedure OPEN (FILE : in out FILE_TYPE; ...);
...
14 - 1
procedure READ (FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE);
procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE);
...
end SEQUENTIAL_IO;
In order to define sequential input-output for a given element type, an
instantiation of this generic unit, with the given type as actual
parameter, must be declared. The resulting package contains the
declaration of a file type (called FILE_TYPE) for files of such elements,
as well as the operations applicable to these files, such as the OPEN,
READ, and WRITE procedures.
14 - 2
Input-output for direct access files is likewise defined by a generic
package called DIRECT_IO. Input-output in human-readable form is defined
by the (nongeneric) package TEXT_IO.
Before input or output operations can be performed on a file, the file must
first be associated with an external file. While such an association is in
effect, the file is said to be open, and otherwise the file is said to be
closed.
The language does not define what happens to external files after the
completion of the main program (in particular, if corresponding files have
not been closed). The effect of input-output for access types is
implementation-dependent.
An open file has a current mode, which is a value of one of the enumeration
types
type FILE_MODE is (IN_FILE, INOUT_FILE, OUT_FILE); -- for DIRECT_IO
type FILE_MODE is (IN_FILE, OUT_FILE); -- for SEQUENTIAL_IO and TEXT_IO
These values correspond respectively to the cases where only reading, both
reading and writing, or only writing are to be performed. The mode of a
file can be changed.
Several file management operations are common to the three input-output
packages. These operations are described in section 14.2.1 for sequential
and direct files. Any additional effects concerning text input-output are
described in section 14.3.1.
The exceptions that can be raised by a call of an input-output subprogram
are all defined in the package IO_EXCEPTIONS; the situations in which
they can be raised are described, either following the description of the
subprogram (and in section 14.4), or in Appendix F in the case of error
situations that are implementation-dependent.
Notes:
Each instantiation of the generic packages SEQUENTIAL_IO and DIRECT_IO
declares a different type FILE_TYPE; in the case of TEXT_IO, the type
FILE_TYPE is unique.
A bidirectional device can often be modeled as two sequential files
associated with the device, one of mode IN_FILE, and one of mode OUT_FILE.
An implementation may restrict the number of files that may be associated
with a given external file. The effect of sharing an external file in this
way by several file objects is implementation-dependent.
References: create procedure 14.2.1, current index 14.2, current size
14.2, delete procedure 14.2.1, direct access 14.2, direct file procedure
14.2, direct_io package 14.1 14.2, enumeration type 3.5.1, exception 11,
file mode 14.2.3, generic instantiation 12.3, index 14.2, input file
14.2.2, io_exceptions package 14.5, open file 14.1, open procedure 14.2.1,
output file 14.2.2, read procedure 14.2.4, sequential access 14.2,
sequential file 14.2, sequential input-output 14.2.2, sequential_io package
14.2 14.2.2, string 3.6.3, text_io package 14.3, write procedure 14.2.4
14 - 3
14.2 Sequential and Direct Files
Two kinds of access to external files are defined: sequential access and
direct access. The corresponding file types and the associated operations
are provided by the generic packages SEQUENTIAL_IO and DIRECT_IO. A file
object to be used for sequential access is called a sequential file, and
one to be used for direct access is called a direct file.
For sequential access, the file is viewed as a sequence of values that are
transferred in the order of their appearance (as produced by the program or
by the environment). When the file is opened, transfer starts from the
beginning of the file.
14 - 4
For direct access, the file is viewed as a set of elements occupying
consecutive positions in linear order; a value can be transferred to or
from an element of the file at any selected position. The position of an
element is specified by its index, which is a number, greater than zero, of
the implementation-defined integer type COUNT. The first element, if any,
has index one; the index of the last element, if any, is called the
current size; the current size is zero if there are no elements. The
current size is a property of the external file.
An open direct file has a current index, which is the index that will be
used by the next read or write operation. When a direct file is opened,
the current index is set to one. The current index of a direct file is a
property of a file object, not of an external file.
All three file modes are allowed for direct files. The only allowed modes
for sequential files are the modes IN_FILE and OUT_FILE.
References: count type 14.3, file mode 14.1, in_file 14.1, out_file 14.1
14.2.1 File Management
The procedures and functions described in this section provide for the
control of external files; their declarations are repeated in each of the
three packages for sequential, direct, and text input-output. For text
input-output, the procedures CREATE, OPEN, and RESET have additional
effects described in section 14.3.1.
procedure CREATE(FILE : in out FILE_TYPE;
MODE : in FILE_MODE := DEFAULT_MODE;
NAME : in STRING := "";
FORM : in STRING := "");
Establishes a new external file, with the given name and form,
and associates this external file with the given file. The given
file is left open. The current mode of the given file is set to
the given access mode. The default access mode is the mode
OUT_FILE for sequential and text input-output; it is the mode
INOUT_FILE for direct input-output. For direct access, the size
of the created file is implementation-dependent. A null string
for NAME specifies an external file that is not accessible after
the completion of the main program (a temporary file). A null
string for FORM specifies the use of the default options of the
implementation for the external file.
The exception STATUS_ERROR is raised if the given file is already
open. The exception NAME_ERROR is raised if the string given as
NAME does not allow the identification of an external file. The
exception USE_ERROR is raised if, for the specified mode, the
environment does not support creation of an external file with
the given name (in the absence of NAME_ERROR) and form.
14 - 5
procedure OPEN(FILE : in out FILE_TYPE;
MODE : in FILE_MODE;
NAME : in STRING;
FORM : in STRING := "");
Associates the given file with an existing external file having
the given name and form, and sets the current mode of the given
file to the given mode. The given file is left open.
14 - 6
The exception STATUS_ERROR is raised if the given file is already
open. The exception NAME_ERROR is raised if the string given as
NAME does not allow the identification of an external file; in
particular, this exception is raised if no external file with the
given name exists. The exception USE_ERROR is raised if, for the
specified mode, the environment does not support opening for an
external file with the given name (in the absence of NAME_ERROR)
and form.
procedure CLOSE(FILE : in out FILE_TYPE);
Severs the association between the given file and its associated
external file. The given file is left closed.
The exception STATUS_ERROR is raised if the given file is not
open.
procedure DELETE(FILE : in out FILE_TYPE);
Deletes the external file associated with the given file. The
given file is closed, and the external file ceases to exist.
The exception STATUS_ERROR is raised if the given file is not
open. The exception USE_ERROR is raised if (as fully defined in
Appendix F) deletion of the external file is not supported by the
environment.
procedure RESET(FILE : in out FILE_TYPE; MODE : in FILE_MODE);
procedure RESET(FILE : in out FILE_TYPE);
Resets the given file so that reading from or writing to its
elements can be restarted from the beginning of the file; in
particular, for direct access this means that the current index
is set to one. If a MODE parameter is supplied, the current mode
of the given file is set to the given mode.
The exception STATUS_ERROR is raised if the file is not open.
The exception USE_ERROR is raised if the environment does not
support resetting for the external file and, also, if the
environment does not support resetting to the specified mode for
the external file.
function MODE(FILE : in FILE_TYPE) return FILE_MODE;
Returns the current mode of the given file.
The exception STATUS_ERROR is raised if the file is not open.
function NAME(FILE : in FILE_TYPE) return STRING;
14 - 7
Returns a string which uniquely identifies the external file
currently associated with the given file (and may thus be used in
an OPEN operation). If an environment allows alternative
specifications of the name (for example, abbreviations), the
string returned by the function should correspond to a full
specification of the name.
The exception STATUS_ERROR is raised if the given file is not
open.
14 - 8
function FORM(FILE : in FILE_TYPE) return STRING;
Returns the form string for the external file currently
associated with the given file. If an environment allows
alternative specifications of the form (for example,
abbreviations using default options), the string returned by the
function should correspond to a full specification (that is, it
should indicate explicitly all options selected, including
default options).
The exception STATUS_ERROR is raised if the given file is not
open.
function IS_OPEN(FILE : in FILE_TYPE) return BOOLEAN;
Returns TRUE if the file is open (that is, if it is associated
with an external file), otherwise returns FALSE.
References: current mode 14.1, current size 14.1, closed file 14.1, direct
access 14.2, external file 14.1, file 14.1, file_mode type 14.1, file_type
type 14.1, form string 14.1, inout_file 14.2.4, mode 14.1, name string
14.1, name_error exception 14.4, open file 14.1, out_file 14.1,
status_error exception 14.4, use_error exception 14.4
14.2.2 Sequential Input-Output
The operations available for sequential input and output are described in
this section. The exception STATUS_ERROR is raised if any of these
operations is attempted for a file that is not open.
procedure READ(FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE);
Operates on a file of mode IN_FILE. Reads an element from the
given file, and returns the value of this element in the ITEM
parameter.
The exception MODE_ERROR is raised if the mode is not IN_FILE.
The exception END_ERROR is raised if no more elements can be read
from the given file. The exception DATA_ERROR is raised if the
element read cannot be interpreted as a value of the type
ELEMENT_TYPE; however, an implementation is allowed to omit this
check if performing the check is too complex.
procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE);
Operates on a file of mode OUT_FILE. Writes the value of ITEM to
the given file.
14 - 9
The exception MODE_ERROR is raised if the mode is not OUT_FILE.
The exception USE_ERROR is raised if the capacity of the external
file is exceeded.
function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
Operates on a file of mode IN_FILE. Returns TRUE if no more
elements can be read from the given file; otherwise returns
FALSE.
The exception MODE_ERROR is raised if the mode is not IN_FILE.
References: data_error exception 14.4, element 14.1, element_type 14.1,
end_error exception 14.4, external file 14.1, file 14.1, file mode 14.1,
file_type 14.1, in_file 14.1, mode_error exception 14.4, out_file 14.1,
status_error exception 14.4, use_error exception 14.4
14 - 10
14.2.3 Specification of the Package Sequential_IO
with IO_EXCEPTIONS;
generic
type ELEMENT_TYPE is private;
package SEQUENTIAL_IO is
type FILE_TYPE is limited private;
type FILE_MODE is (IN_FILE, OUT_FILE);
-- File management
procedure CREATE(FILE : in out FILE_TYPE;
MODE : in FILE_MODE := OUT_FILE;
NAME : in STRING := "";
FORM : in STRING := "");
procedure OPEN (FILE : in out FILE_TYPE;
MODE : in FILE_MODE;
NAME : in STRING;
FORM : in STRING := "");
procedure CLOSE (FILE : in out FILE_TYPE);
procedure DELETE(FILE : in out FILE_TYPE);
procedure RESET (FILE : in out FILE_TYPE; MODE : in FILE_MODE);
procedure RESET (FILE : in out FILE_TYPE);
function MODE (FILE : in FILE_TYPE) return FILE_MODE;
function NAME (FILE : in FILE_TYPE) return STRING;
function FORM (FILE : in FILE_TYPE) return STRING;
function IS_OPEN(FILE : in FILE_TYPE) return BOOLEAN;
-- Input and output operations
procedure READ (FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE);
procedure WRITE (FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE);
function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
-- Exceptions
STATUS_ERROR : exception renames IO_EXCEPTIONS.STATUS_ERROR;
MODE_ERROR : exception renames IO_EXCEPTIONS.MODE_ERROR;
NAME_ERROR : exception renames IO_EXCEPTIONS.NAME_ERROR;
USE_ERROR : exception renames IO_EXCEPTIONS.USE_ERROR;
DEVICE_ERROR : exception renames IO_EXCEPTIONS.DEVICE_ERROR;
END_ERROR : exception renames IO_EXCEPTIONS.END_ERROR;
DATA_ERROR : exception renames IO_EXCEPTIONS.DATA_ERROR;
14 - 11
private
-- implementation-dependent
end SEQUENTIAL_IO;
14 - 12
References: close procedure 14.2.1, create procedure 14.2.1, data_error
exception 14.4, delete procedure 14.2.1, device_error exception 14.4,
end_error exception 14.4, end_of_file function 14.2.2, file_mode 14.1,
file_type 14.1, form function 14.2.1, in_file 14.1, io_exceptions 14.4,
is_open function 14.2.1, mode function 14.2.1, mode_error exception 14.4,
name function 14.2.1, name_error exception 14.4, open procedure 14.2.1,
out_file 14.1, read procedure 14.2.2, reset procedure 14.2.1, sequential_io
package 14.2 14.2.2, status_error exception 14.4, use_error exception 14.4,
write procedure 14.2.2,
14.2.4 Direct Input-Output
The operations available for direct input and output are described in this
section. The exception STATUS_ERROR is raised if any of these operations
is attempted for a file that is not open.
procedure READ(FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE;
FROM : in POSITIVE_COUNT);
procedure READ(FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE);
Operates on a file of mode IN_FILE or INOUT_FILE. In the case of
the first form, sets the current index of the given file to the
index value given by the parameter FROM. Then (for both forms)
returns, in the parameter ITEM, the value of the element whose
position in the given file is specified by the current index of
the file; finally, increases the current index by one.
The exception MODE_ERROR is raised if the mode of the given file
is OUT_FILE. The exception END_ERROR is raised if the index to
be used exceeds the size of the external file. The exception
DATA_ERROR is raised if the element read cannot be interpreted as
a value of the type ELEMENT_TYPE; however, an implementation is
allowed to omit this check if performing the check is too
complex.
procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE;
TO : in POSITIVE_COUNT);
procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE);
Operates on a file of mode INOUT_FILE or OUT_FILE. In the case
of the first form, sets the index of the given file to the index
value given by the parameter TO. Then (for both forms) gives the
value of the parameter ITEM to the element whose position in the
given file is specified by the current index of the file;
finally, increases the current index by one.
The exception MODE_ERROR is raised if the mode of the given file
is IN_FILE. The exception USE_ERROR is raised if the capacity of
the external file is exceeded.
14 - 13
procedure SET_INDEX(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
Operates on a file of any mode. Sets the current index of the
given file to the given index value (which may exceed the current
size of the file).
function INDEX(FILE : in FILE_TYPE) return POSITIVE_COUNT;
Operates on a file of any mode. Returns the current index of the
given file.
14 - 14
function SIZE(FILE : in FILE_TYPE) return COUNT;
Operates on a file of any mode. Returns the current size of the
external file that is associated with the given file.
function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
Operates on a file of mode IN_FILE or INOUT_FILE. Returns TRUE
if the current index exceeds the size of the external file;
otherwise returns FALSE.
The exception MODE_ERROR is raised if the mode of the given file
is OUT_FILE.
References: count type 14.2, current index 14.2, current size 14.2,
data_error exception 14.4, element 14.1, element_type 14.1, end_error
exception 14.4, external file 14.1, file 14.1, file mode 14.1, file_type
14.1, in_file 14.1, index 14.2, inout_file 14.1, mode_error exception 14.4,
open file 14.1, positive_count 14.3, status_error exception 14.4, use_error
exception 14.4
14.2.5 Specification of the Package Direct_IO
with IO_EXCEPTIONS;
generic
type ELEMENT_TYPE is private;
package DIRECT_IO is
type FILE_TYPE is limited private;
type FILE_MODE is (IN_FILE, INOUT_FILE, OUT_FILE);
type COUNT is range 0 .. IMPLEMENTATION_DEFINED;
subtype POSITIVE_COUNT is COUNT range 1 .. COUNT'LAST;
-- File management
procedure CREATE(FILE : in out FILE_TYPE;
MODE : in FILE_MODE := INOUT_FILE;
NAME : in STRING := "";
FORM : in STRING := "");
procedure OPEN (FILE : in out FILE_TYPE;
MODE : in FILE_MODE;
NAME : in STRING;
FORM : in STRING := "");
procedure CLOSE (FILE : in out FILE_TYPE);
procedure DELETE(FILE : in out FILE_TYPE);
14 - 15
procedure RESET (FILE : in out FILE_TYPE; MODE : in FILE_MODE);
procedure RESET (FILE : in out FILE_TYPE);
function MODE (FILE : in FILE_TYPE) return FILE_MODE;
function NAME (FILE : in FILE_TYPE) return STRING;
function FORM (FILE : in FILE_TYPE) return STRING;
function IS_OPEN(FILE : in FILE_TYPE) return BOOLEAN;
14 - 16
-- Input and output operations
procedure READ (FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE; FROM : POSITIVE_COUNT);
procedure READ (FILE : in FILE_TYPE; ITEM : out ELEMENT_TYPE);
procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE; TO : POSITIVE_COUNT);
procedure WRITE(FILE : in FILE_TYPE; ITEM : in ELEMENT_TYPE);
procedure SET_INDEX(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
function INDEX(FILE : in FILE_TYPE) return POSITIVE_COUNT;
function SIZE (FILE : in FILE_TYPE) return COUNT;
function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
-- Exceptions
STATUS_ERROR : exception renames IO_EXCEPTIONS.STATUS_ERROR;
MODE_ERROR : exception renames IO_EXCEPTIONS.MODE_ERROR;
NAME_ERROR : exception renames IO_EXCEPTIONS.NAME_ERROR;
USE_ERROR : exception renames IO_EXCEPTIONS.USE_ERROR;
DEVICE_ERROR : exception renames IO_EXCEPTIONS.DEVICE_ERROR;
END_ERROR : exception renames IO_EXCEPTIONS.END_ERROR;
DATA_ERROR : exception renames IO_EXCEPTIONS.DATA_ERROR;
private
-- implementation-dependent
end DIRECT_IO;
References close procedure 14.2.1, count type 14.2, create procedure
14.2.1, data_error exception 14.4, default_mode 14.2.5, delete procedure
14.2.1, device_error exception 14.4, element_type 14.2.4, end_error
exception 14.4, end_of_file function 14.2.4, file_mode 14.2.5, file_type
14.2.4, form function 14.2.1, in_file 14.2.4, index function 14.2.4,
inout_file 14.2.4 14.2.1, io_exceptions package 14.4, is_open function
14.2.1, mode function 14.2.1, mode_error exception 14.4, name function
14.2.1, name_error exception 14.4, open procedure 14.2.1, out_file 14.2.1,
read procedure 14.2.4, set_index procedure 14.2.4, size function 14.2.4,
status_error exception 14.4, use_error exception 14.4, write procedure
14.2.4 14.2.1
14.3 Text Input-Output
This section describes the package TEXT_IO, which provides facilities for
input and output in human-readable form. Each file is read or written
sequentially, as a sequence of characters grouped into lines, and as a
sequence of lines grouped into pages. The specification of the package is
given below in section 14.3.10.
14 - 17
The facilities for file management given above, in sections 14.2.1 and
14.2.2, are available for text input-output. In place of READ and WRITE,
however, there are procedures GET and PUT that input values of suitable
types from text files, and output values to them. These values are
provided to the PUT procedures, and returned by the GET procedures, in a
parameter ITEM. Several overloaded procedures of these names exist, for
different types of ITEM. These GET procedures analyze the input sequences
of characters as lexical elements (see Chapter 2) and return the
corresponding values; the PUT procedures output the given values as
appropriate lexical elements. Procedures GET and PUT are also available
that input and output individual characters treated as character values
rather than as lexical elements.
14 - 18
In addition to the procedures GET and PUT for numeric and enumeration types
of ITEM that operate on text files, analogous procedures are provided that
read from and write to a parameter of type STRING. These procedures
perform the same analysis and composition of character sequences as their
counterparts which have a file parameter.
For all GET and PUT procedures that operate on text files, and for many
other subprograms, there are forms with and without a file parameter. Each
such GET procedure operates on an input file, and each such PUT procedure
operates on an output file. If no file is specified, a default input file
or a default output file is used.
At the beginning of program execution the default input and output files
are the so-called standard input file and standard output file. These
files are open, have respectively the current modes IN_FILE and OUT_FILE,
and are associated with two implementation-defined external files.
Procedures are provided to change the current default input file and the
current default output file.
From a logical point of view, a text file is a sequence of pages, a page is
a sequence of lines, and a line is a sequence of characters; the end of a
line is marked by a line terminator; the end of a page is marked by the
combination of a line terminator immediately followed by a page terminator;
and the end of a file is marked by the combination of a line terminator
immediately followed by a page terminator and then a file terminator.
Terminators are generated during output; either by calls of procedures
provided expressly for that purpose; or implicitly as part of other
operations, for example, when a bounded line length, a bounded page length,
or both, have been specified for a file.
The actual nature of terminators is not defined by the language and hence
depends on the implementation. Although terminators are recognized or
generated by certain of the procedures that follow, they are not
necessarily implemented as characters or as sequences of characters.
Whether they are characters (and if so which ones) in any particular
implementation need not concern a user who neither explicitly outputs nor
explicitly inputs control characters. The effect of input or output of
control characters (other than horizontal tabulation) is not defined by the
language.
The characters of a line are numbered, starting from one; the number of a
character is called its column number. For a line terminator, a column
number is also defined: it is one more than the number of characters in
the line. The lines of a page, and the pages of a file, are similarly
numbered. The current column number is the column number of the next
character or line terminator to be transferred. The current line number is
the number of the current line. The current page number is the number of
the current page. These numbers are values of the subtype POSITIVE_COUNT
of the type COUNT (by convention, the value zero of the type COUNT is used
to indicate special conditions).
type COUNT is range 0 .. implementation_defined;
subtype POSITIVE_COUNT is COUNT range 1 .. COUNT'LAST;
14 - 19
For an output file, a maximum line length can be specified and a maximum
page length can be specified. If a value to be output cannot fit on the
current line, for a specified maximum line length, then a new line is
automatically started before the value is output; if, further, this new
line cannot fit on the current page, for a specified maximum page length,
then a new page is automatically started before the value is output.
Functions are provided to determine the maximum line length and the maximum
page length. When a file is opened with mode OUT_FILE, both values are
zero: by convention, this means that the line lengths and page lengths are
unbounded. (Consequently, output consists of a single line if the
subprograms for explicit control of line and page structure are not used.)
The constant UNBOUNDED is provided for this purpose.
References: count type 14.3.10, default current input file 14.3.2, default
current output file 14.3.2, external file 14.1, file 14.1, get procedure
14.3.5, in_file 14.1, out_file 14.1, put procedure 14.3.5, read 14.2.2,
sequential access 14.1, standard input file 14.3.2, standard output file
14.3.2
14 - 20
14.3.1 File Management
The only allowed file modes for text files are the modes IN_FILE and
OUT_FILE. The subprograms given in section 14.2.1 for the control of
external files, and the function END_OF_FILE given in section 14.2.2 for
sequential input-output, are also available for text files. There is also
a version of END_OF_FILE that refers to the current default input file.
For text files, the procedures have the following additional effects:
- For the procedures CREATE and OPEN: After opening a file with mode
OUT_FILE, the page length and line length are unbounded (both have the
conventional value zero). After opening a file with mode IN_FILE or
OUT_FILE, the current column, current line, and current page numbers
are set to one.
- For the procedure CLOSE: If the file has the current mode OUT_FILE,
has the effect of calling NEW_PAGE, unless the current page is already
terminated; then outputs a file terminator.
- For the procedure RESET: If the file has the current mode OUT_FILE,
has the effect of calling NEW_PAGE, unless the current page is already
terminated; then outputs a file terminator. If the new file mode is
OUT_FILE, the page and line lengths are unbounded. For all modes, the
current column, line, and page numbers are set to one.
The exception MODE_ERROR is raised by the procedure RESET upon an attempt
to change the mode of a file that is either the current default input file,
or the current default output file.
References: create procedure 14.2.1, current column number 14.3, current
default input file 14.3, current line number 14.3, current page number
14.3, end_of_file 14.3, external file 14.1, file 14.1, file mode 14.1, file
terminator 14.3, in_file 14.1, line length 14.3, mode_error exception 14.4,
open procedure 14.2.1, out_file 14.1, page length 14.3, reset procedure
14.2.1
14.3.2 Default Input and Output Files
The following subprograms provide for the control of the particular default
files that are used when a file parameter is omitted from a GET, PUT or
other operation of text input-output described below.
procedure SET_INPUT(FILE : in FILE_TYPE);
Operates on a file of mode IN_FILE. Sets the current default
input file to FILE.
The exception STATUS_ERROR is raised if the given file is not
open. The exception MODE_ERROR is raised if the mode of the
given file is not IN_FILE.
14 - 21
procedure SET_OUTPUT(FILE : in FILE_TYPE);
Operates on a file of mode OUT_FILE. Sets the current default
output file to FILE.
The exception STATUS_ERROR is raised if the given file is not
open. The exception MODE_ERROR is raised if the mode of the
given file is not OUT_FILE.
14 - 22
function STANDARD_INPUT return FILE_TYPE;
Returns the standard input file (see 14.3).
function STANDARD_OUTPUT return FILE_TYPE;
Returns the standard output file (see 14.3).
function CURRENT_INPUT return FILE_TYPE;
Returns the current default input file.
function CURRENT_OUTPUT return FILE_TYPE;
Returns the current default output file.
Note:
The standard input and the standard output files cannot be opened, closed,
reset, or deleted, because the parameter FILE of the corresponding
procedures has the mode in out.
References: current default file 14.3, default file 14.3, file_type 14.1,
get procedure 14.3.5, mode_error exception 14.4, put procedure 14.3.5,
status_error exception 14.4
14.3.3 Specification of Line and Page Lengths
The subprograms described in this section are concerned with the line and
page structure of a file of mode OUT_FILE. They operate either on the file
given as the first parameter, or, in the absence of such a file parameter,
on the current default output file. They provide for output of text with a
specified maximum line length or page length. In these cases, line and
page terminators are output implicitly and automatically when needed. When
line and page lengths are unbounded (that is, when they have the
conventional value zero), as in the case of a newly opened file, new lines
and new pages are only started when explicitly called for.
In all cases, the exception STATUS_ERROR is raised if the file to be used
is not open; the exception MODE_ERROR is raised if the mode of the file is
not OUT_FILE.
procedure SET_LINE_LENGTH(FILE : in FILE_TYPE; TO : in COUNT);
procedure SET_LINE_LENGTH(TO : in COUNT);
14 - 23
Sets the maximum line length of the specified output file to the
number of characters specified by TO. The value zero for TO
specifies an unbounded line length.
The exception USE_ERROR is raised if the specified line length is
inappropriate for the associated external file.
14 - 24
procedure SET_PAGE_LENGTH(FILE : in FILE_TYPE; TO : in COUNT);
procedure SET_PAGE_LENGTH(TO : in COUNT);
Sets the maximum page length of the specified output file to the
number of lines specified by TO. The value zero for TO specifies
an unbounded page length.
The exception USE_ERROR is raised if the specified page length is
inappropriate for the associated external file.
function LINE_LENGTH(FILE : in FILE_TYPE) return COUNT;
function LINE_LENGTH return COUNT;
Returns the maximum line length currently set for the specified
output file, or zero if the line length is unbounded.
function PAGE_LENGTH(FILE : in FILE_TYPE) return COUNT;
function PAGE_LENGTH return COUNT;
Returns the maximum page length currently set for the specified
output file, or zero if the page length is unbounded.
References: count type 14.3, current default output file 14.3, external
file 14.1, file 14.1, file_type 14.1, line 14.3, line length 14.3, line
terminator 14.3, maximum line length 14.3, maximum page length 14.3,
mode_error exception 14.4, open file 14.1, out_file 14.1, page 14.3, page
length 14.3, page terminator 14.3, status_error exception 14.4, unbounded
page length 14.3, use_error exception 14.4
14.3.4 Operations on Columns, Lines, and Pages
The subprograms described in this section provide for explicit control of
line and page structure; they operate either on the file given as the
first parameter, or, in the absence of such a file parameter, on the
appropriate (input or output) current default file. The exception
STATUS_ERROR is raised by any of these subprograms if the file to be used
is not open.
procedure NEW_LINE(FILE : in FILE_TYPE; SPACING : in POSITIVE_COUNT := 1);
procedure NEW_LINE(SPACING : in POSITIVE_COUNT := 1);
Operates on a file of mode OUT_FILE.
For a SPACING of one: Outputs a line terminator and sets the
current column number to one. Then increments the current line
number by one, except in the case that the current line number is
already greater than or equal to the maximum page length, for a
bounded page length; in that case a page terminator is output,
14 - 25
the current page number is incremented by one, and the current
line number is set to one.
For a SPACING greater than one, the above actions are performed
SPACING times.
The exception MODE_ERROR is raised if the mode is not OUT_FILE.
14 - 26
procedure SKIP_LINE(FILE : in FILE_TYPE; SPACING : in POSITIVE_COUNT := 1);
procedure SKIP_LINE(SPACING : in POSITIVE_COUNT := 1);
Operates on a file of mode IN_FILE.
For a SPACING of one: Reads and discards all characters until a
line terminator has been read, and then sets the current column
number to one. If the line terminator is not immediately
followed by a page terminator, the current line number is
incremented by one. Otherwise, if the line terminator is
immediately followed by a page terminator, then the page
terminator is skipped, the current page number is incremented by
one, and the current line number is set to one.
For a SPACING greater than one, the above actions are performed
SPACING times.
The exception MODE_ERROR is raised if the mode is not IN_FILE.
The exception END_ERROR is raised if an attempt is made to read a
file terminator.
function END_OF_LINE(FILE : in FILE_TYPE) return BOOLEAN;
function END_OF_LINE return BOOLEAN;
Operates on a file of mode IN_FILE. Returns TRUE if a line
terminator or a file terminator is next; otherwise returns
FALSE.
The exception MODE_ERROR is raised if the mode is not IN_FILE.
procedure NEW_PAGE(FILE : in FILE_TYPE);
procedure NEW_PAGE;
Operates on a file of mode OUT_FILE. Outputs a line terminator
if the current line is not terminated, or if the current page is
empty (that is, if the current column and line numbers are both
equal to one). Then outputs a page terminator, which terminates
the current page. Adds one to the current page number and sets
the current column and line numbers to one.
The exception MODE_ERROR is raised if the mode is not OUT_FILE.
procedure SKIP_PAGE(FILE: in FILE_TYPE);
procedure SKIP_PAGE;
Operates on a file of mode IN_FILE. Reads and discards all
characters and line terminators until a page terminator has been
read. Then adds one to the current page number, and sets the
current column and line numbers to one.
14 - 27
The exception MODE_ERROR is raised if the mode is not IN_FILE.
The exception END_ERROR is raised if an attempt is made to read a
file terminator.
14 - 28
function END_OF_PAGE(FILE : in FILE_TYPE) return BOOLEAN;
function END_OF_PAGE return BOOLEAN;
Operates on a file of mode IN_FILE. Returns TRUE if the
combination of a line terminator and a page terminator is next,
or if a file terminator is next; otherwise returns FALSE.
The exception MODE_ERROR is raised if the mode is not IN_FILE.
function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
function END_OF_FILE return BOOLEAN;
Operates on a file of mode IN_FILE. Returns TRUE if a file
terminator is next, or if the combination of a line, a page, and
a file terminator is next; otherwise returns FALSE.
The exception MODE_ERROR is raised if the mode is not IN_FILE.
The following subprograms provide for the control of the current position
of reading or writing in a file. In all cases, the default file is the
current output file.
procedure SET_COL(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
procedure SET_COL(TO : in POSITIVE_COUNT);
If the file mode is OUT_FILE:
If the value specified by TO is greater than the current
column number, outputs spaces, adding one to the current
column number after each space, until the current column
number equals the specified value. If the value specified
by TO is equal to the current column number, there is no
effect. If the value specified by TO is less than the
current column number, has the effect of calling NEW_LINE
(with a spacing of one), then outputs (TO - 1) spaces, and
sets the current column number to the specified value.
The exception LAYOUT_ERROR is raised if the value specified
by TO exceeds LINE_LENGTH when the line length is bounded
(that is, when it does not have the conventional value
zero).
If the file mode is IN_FILE:
Reads (and discards) individual characters, line
terminators, and page terminators, until the next character
to be read has a column number that equals the value
specified by TO; there is no effect if the current column
number already equals this value. Each transfer of a
character or terminator maintains the current column, line,
and page numbers in the same way as a GET procedure (see
14 - 29
14.3.5). (Short lines will be skipped until a line is
reached that has a character at the specified column
position.)
The exception END_ERROR is raised if an attempt is made to
read a file terminator.
14 - 30
procedure SET_LINE(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
procedure SET_LINE(TO : in POSITIVE_COUNT);
If the file mode is OUT_FILE:
If the value specified by TO is greater than the current
line number, has the effect of repeatedly calling NEW_LINE
(with a spacing of one), until the current line number
equals the specified value. If the value specified by TO is
equal to the current line number, there is no effect. If
the value specified by TO is less than the current line
number, has the effect of calling NEW_PAGE followed by a
call of NEW_LINE with a spacing equal to (TO - 1).
The exception LAYOUT_ERROR is raised if the value specified
by TO exceeds PAGE_LENGTH when the page length is bounded
(that is, when it does not have the conventional value
zero).
If the mode is IN_FILE:
Has the effect of repeatedly calling SKIP_LINE (with a
spacing of one), until the current line number equals the
value specified by TO; there is no effect if the current
line number already equals this value. (Short pages will be
skipped until a page is reached that has a line at the
specified line position.)
The exception END_ERROR is raised if an attempt is made to
read a file terminator.
function COL(FILE : in FILE_TYPE) return POSITIVE_COUNT;
function COL return POSITIVE_COUNT;
Returns the current column number.
The exception LAYOUT_ERROR is raised if this number exceeds
COUNT'LAST.
function LINE(FILE : in FILE_TYPE) return POSITIVE_COUNT;
function LINE return POSITIVE_COUNT;
Returns the current line number.
The exception LAYOUT_ERROR is raised if this number exceeds
COUNT'LAST.
function PAGE(FILE : in FILE_TYPE) return POSITIVE_COUNT;
function PAGE return POSITIVE_COUNT;
14 - 31
Returns the current page number.
The exception LAYOUT_ERROR is raised if this number exceeds
COUNT'LAST.
The column number, line number, or page number are allowed to exceed
COUNT'LAST (as a consequence of the input or output of sufficiently many
characters, lines, or pages). These events do not cause any exception to
be raised. However, a call of COL, LINE, or PAGE raises the exception
LAYOUT_ERROR if the corresponding number exceeds COUNT'LAST.
14 - 32
Note:
A page terminator is always skipped whenever the preceding line terminator
is skipped. An implementation may represent the combination of these
terminators by a single character, provided that it is properly recognized
at input.
References: current column number 14.3, current default file 14.3, current
line number 14.3, current page number 14.3, end_error exception 14.4, file
14.1, file terminator 14.3, get procedure 14.3.5, in_file 14.1,
layout_error exception 14.4, line 14.3, line number 14.3, line terminator
14.3, maximum page length 14.3, mode_error exception 14.4, open file 14.1,
page 14.3, page length 14.3, page terminator 14.3, positive count 14.3,
status_error exception 14.4
14.3.5 Get and Put Procedures
The procedures GET and PUT for items of the types CHARACTER, STRING,
numeric types, and enumeration types are described in subsequent sections.
Features of these procedures that are common to most of these types are
described in this section. The GET and PUT procedures for items of type
CHARACTER and STRING deal with individual character values; the GET and
PUT procedures for numeric and enumeration types treat the items as lexical
elements.
All procedures GET and PUT have forms with a file parameter, written first.
Where this parameter is omitted, the appropriate (input or output) current
default file is understood to be specified. Each procedure GET operates on
a file of mode IN_FILE. Each procedure PUT operates on a file of mode
OUT_FILE.
All procedures GET and PUT maintain the current column, line, and page
numbers of the specified file: the effect of each of these procedures upon
these numbers is the resultant of the effects of individual transfers of
characters and of individual output or skipping of terminators. Each
transfer of a character adds one to the current column number. Each output
of a line terminator sets the current column number to one and adds one to
the current line number. Each output of a page terminator sets the
current column and line numbers to one and adds one to the current page
number. For input, each skipping of a line terminator sets the current
column number to one and adds one to the current line number; each
skipping of a page terminator sets the current column and line numbers to
one and adds one to the current page number. Similar considerations apply
to the procedures GET_LINE, PUT_LINE, and SET_COL.
Several GET and PUT procedures, for numeric and enumeration types, have
format parameters which specify field lengths; these parameters are of the
nonnegative subtype FIELD of the type INTEGER.
Input-output of enumeration values uses the syntax of the corresponding
lexical elements. Any GET procedure for an enumeration type begins by
skipping any leading blanks, or line or page terminators; a blank being
14 - 33
defined as a space or a horizontal tabulation character. Next, characters
are input only so long as the sequence input is an initial sequence of an
identifier or of a character literal (in particular, input ceases when a
line terminator is encountered). The character or line terminator that
causes input to cease remains available for subsequent input.
For a numeric type, the GET procedures have a format parameter called
WIDTH. If the value given for this parameter is zero, the GET procedure
proceeds in the same manner as for enumeration types, but using the syntax
of numeric literals instead of that of enumeration literals. If a nonzero
value is given, then exactly WIDTH characters are input, or the characters
up to a line terminator, whichever comes first; any skipped leading blanks
are included in the count. The syntax used for numeric literals is an
extended syntax that allows a leading sign (but no intervening blanks, or
line or page terminators).
14 - 34
Any PUT procedure, for an item of a numeric or an enumeration type, outputs
the value of the item as a numeric literal, identifier, or character
literal, as appropriate. This is preceded by leading spaces if required by
the format parameters WIDTH or FORE (as described in later sections), and
then a minus sign for a negative value; for an enumeration type, the
spaces follow instead of leading. The format given for a PUT procedure is
overridden if it is insufficiently wide.
Two further cases arise for PUT procedures for numeric and enumeration
types, if the line length of the specified output file is bounded (that is,
if it does not have the conventional value zero). If the number of
characters to be output does not exceed the maximum line length, but is
such that they cannot fit on the current line, starting from the current
column, then (in effect) NEW_LINE is called (with a spacing of one) before
output of the item. Otherwise, if the number of characters exceeds the
maximum line length, then the exception LAYOUT_ERROR is raised and no
characters are output.
The exception STATUS_ERROR is raised by any of the procedures GET,
GET_LINE, PUT, and PUT_LINE if the file to be used is not open. The
exception MODE_ERROR is raised by the procedures GET and GET_LINE if the
mode of the file to be used is not IN_FILE; and by the procedures PUT and
PUT_LINE, if the mode is not OUT_FILE.
The exception END_ERROR is raised by a GET procedure if an attempt is made
to skip a file terminator. The exception DATA_ERROR is raised by a GET
procedure if the sequence finally input is not a lexical element
corresponding to the type, in particular if no characters were input; for
this test, leading blanks are ignored; for an item of a numeric type, when
a sign is input, this rule applies to the succeeding numeric literal. The
exception LAYOUT_ERROR is raised by a PUT procedure that outputs to a
parameter of type STRING, if the length of the actual string is
insufficient for the output of the item.
Examples:
In the examples, here and in sections 14.3.7 and 14.3.8, the string quotes
and the lower case letter b are not transferred: they are shown only to
reveal the layout and spaces.
N : INTEGER;
...
GET(N);
-- Characters at input Sequence input Value of N
-- bb-12535b -12535 -12535
-- bb12_535E1b 12_535E1 125350
-- bb12_535E; 12_535E (none) DATA_ERROR raised
Example of overridden width parameter:
PUT(ITEM => -23, WIDTH => 2); -- "-23"
14 - 35
References: blank 14.3.9, column number 14.3, current default file 14.3,
data_error exception 14.4, end_error exception 14.4, file 14.1, fore
14.3.8, get procedure 14.3.6 14.3.7 14.3.8 14.3.9, in_file 14.1,
layout_error exception 14.4, line number 14.1, line terminator 14.1,
maximum line length 14.3, mode 14.1, mode_error exception 14.4, new_file
procedure 14.3.4, out_file 14.1, page number 14.1, page terminator 14.1,
put procedure 14.3.6 14.3.7 14.3.8 14.3.9, skipping 14.3.7 14.3.8 14.3.9,
status_error exception 14.4, width 14.3.5 14.3.7 14.3.9
14 - 36
14.3.6 Input-Output of Characters and Strings
For an item of type CHARACTER the following procedures are provided:
procedure GET(FILE : in FILE_TYPE; ITEM : out CHARACTER);
procedure GET(ITEM : out CHARACTER);
After skipping any line terminators and any page terminators,
reads the next character from the specified input file and
returns the value of this character in the out parameter ITEM.
The exception END_ERROR is raised if an attempt is made to skip a
file terminator.
procedure PUT(FILE : in FILE_TYPE; ITEM : in CHARACTER);
procedure PUT(ITEM : in CHARACTER);
If the line length of the specified output file is bounded (that
is, does not have the conventional value zero), and the current
column number exceeds it, has the effect of calling NEW_LINE with
a spacing of one. Then, or otherwise, outputs the given
character to the file.
For an item of type STRING the following procedures are provided:
procedure GET(FILE : in FILE_TYPE; ITEM : out STRING);
procedure GET(ITEM : out STRING);
Determines the length of the given string and attempts that
number of GET operations for successive characters of the string
(in particular, no operation is performed if the string is null).
procedure PUT(FILE : in FILE_TYPE; ITEM : in STRING);
procedure PUT(ITEM : in STRING);
Determines the length of the given string and attempts that
number of PUT operations for successive characters of the string
(in particular, no operation is performed if the string is null).
procedure GET_LINE(FILE : in FILE_TYPE; ITEM : out STRING; LAST : out NATURAL);
procedure GET_LINE(ITEM : out STRING; LAST : out NATURAL);
Replaces successive characters of the specified string by
successive characters read from the specified input file.
Reading stops if the end of the line is met, in which case the
procedure SKIP_LINE is then called (in effect) with a spacing of
one; reading also stops if the end of the string is met.
Characters not replaced are left undefined.
14 - 37
If characters are read, returns in LAST the index value such that
ITEM(LAST) is the last character replaced (the index of the first
character replaced is ITEM'FIRST). If no characters are read,
returns in LAST an index value that is one less than ITEM'FIRST.
The exception END_ERROR is raised if an attempt is made to skip a
file terminator.
14 - 38
procedure PUT_LINE(FILE : in FILE_TYPE; ITEM : in STRING);
procedure PUT_LINE(ITEM : in STRING);
Calls the procedure PUT for the given string, and then the
procedure NEW_LINE with a spacing of one.
Notes:
In a literal string parameter of PUT, the enclosing string bracket
characters are not output. Each doubled string bracket character in the
enclosed string is output as a single string bracket character, as a
consequence of the rule for string literals (see 2.6).
A string read by GET or written by PUT can extend over several lines.
References: current column number 14.3, end_error exception 14.4, file
14.1, file terminator 14.3, get procedure 14.3.5, line 14.3, line length
14.3, new_line procedure 14.3.4, page terminator 14.3, put procedure
14.3.4, skipping 14.3.5
14.3.7 Input-Output for Integer Types
The following procedures are defined in the generic package INTEGER_IO.
This must be instantiated for the appropriate integer type (indicated by
NUM in the specification).
Values are output as decimal or based literals, without underline
characters or exponent, and preceded by a minus sign if negative. The
format (which includes any leading spaces and minus sign) can be specified
by an optional field width parameter. Values of widths of fields in output
formats are of the nonnegative integer subtype FIELD. Values of bases are
of the integer subtype NUMBER_BASE.
subtype NUMBER_BASE is INTEGER range 2 .. 16;
The default field width and base to be used by output procedures are
defined by the following variables that are declared in the generic package
INTEGER_IO:
DEFAULT_WIDTH : FIELD := NUM'WIDTH;
DEFAULT_BASE : NUMBER_BASE := 10;
The following procedures are provided:
procedure GET(FILE : in FILE_TYPE; ITEM : out NUM; WIDTH : in FIELD := 0);
procedure GET(ITEM : out NUM; WIDTH : in FIELD := 0);
If the value of the parameter WIDTH is zero, skips any leading
blanks, line terminators, or page terminators, then reads a plus
or a minus sign if present, then reads according to the syntax of
an integer literal (which may be a based literal). If a nonzero
14 - 39
value of WIDTH is supplied, then exactly WIDTH characters are
input, or the characters (possibly none) up to a line terminator,
whichever comes first; any skipped leading blanks are included
in the count.
Returns, in the parameter ITEM, the value of type NUM that
corresponds to the sequence input.
The exception DATA_ERROR is raised if the sequence input does not
have the required syntax or if the value obtained is not of the
subtype NUM.
14 - 40
procedure PUT(FILE : in FILE_TYPE;
ITEM : in NUM;
WIDTH : in FIELD := DEFAULT_WIDTH;
BASE : in NUMBER_BASE := DEFAULT_BASE);
procedure PUT(ITEM : in NUM;
WIDTH : in FIELD := DEFAULT_WIDTH;
BASE : in NUMBER_BASE := DEFAULT_BASE);
Outputs the value of the parameter ITEM as an integer literal,
with no underlines, no exponent, and no leading zeros (but a
single zero for the value zero), and a preceding minus sign for a
negative value.
If the resulting sequence of characters to be output has fewer
than WIDTH characters, then leading spaces are first output to
make up the difference.
Uses the syntax for decimal literal if the parameter BASE has the
value ten (either explicitly or through DEFAULT_BASE);
otherwise, uses the syntax for based literal, with any letters in
upper case.
procedure GET(FROM : in STRING; ITEM : out NUM; LAST : out POSITIVE);
Reads an integer value from the beginning of the given string,
following the same rules as the GET procedure that reads an
integer value from a file, but treating the end of the string as
a file terminator. Returns, in the parameter ITEM, the value of
type NUM that corresponds to the sequence input. Returns in LAST
the index value such that FROM(LAST) is the last character read.
The exception DATA_ERROR is raised if the sequence input does not
have the required syntax or if the value obtained is not of the
subtype NUM.
procedure PUT(TO : out STRING;
ITEM : in NUM;
BASE : in NUMBER_BASE := DEFAULT_BASE);
Outputs the value of the parameter ITEM to the given string,
following the same rule as for output to a file, using the length
of the given string as the value for WIDTH.
Examples:
package INT_IO is new INTEGER_IO(SMALL_INT); use INT_IO;
-- default format used at instantiation, DEFAULT_WIDTH = 4, DEFAULT_BASE = 10
PUT(126); -- "b126"
PUT(-126, 7); -- "bbb-126"
PUT(126, WIDTH => 13, BASE => 2); -- "bbb2#1111110#"
14 - 41
References: based literal 2.4.2, blank 14.3.5, data_error exception 14.4,
decimal literal 2.4.1, field subtype 14.3.5, file_type 14.1, get procedure
14.3.5, integer_io package 14.3.10, integer literal 2.4, layout_error
exception 14.4, line terminator 14.3, put procedure 14.3.5, skipping
14.3.5, width 14.3.5
14 - 42
14.3.8 Input-Output for Real Types
The following procedures are defined in the generic packages FLOAT_IO and
FIXED_IO, which must be instantiated for the appropriate floating point or
fixed point type respectively (indicated by NUM in the specifications).
Values are output as decimal literals without underline characters. The
format of each value output consists of a FORE field, a decimal point, an
AFT field, and (if a nonzero EXP parameter is supplied) the letter E and an
EXP field. The two possible formats thus correspond to:
FORE . AFT
and to:
FORE . AFT E EXP
without any spaces between these fields. The FORE field may include
leading spaces, and a minus sign for negative values. The AFT field
includes only decimal digits (possibly with trailing zeros). The EXP field
includes the sign (plus or minus) and the exponent (possibly with leading
zeros).
For floating point types, the default lengths of these fields are defined
by the following variables that are declared in the generic package
FLOAT_IO:
DEFAULT_FORE : FIELD := 2;
DEFAULT_AFT : FIELD := NUM'DIGITS-1;
DEFAULT_EXP : FIELD := 3;
For fixed point types, the default lengths of these fields are defined by
the following variables that are declared in the generic package FIXED_IO:
DEFAULT_FORE : FIELD := NUM'FORE;
DEFAULT_AFT : FIELD := NUM'AFT;
DEFAULT_EXP : FIELD := 0;
The following procedures are provided:
procedure GET(FILE : in FILE_TYPE; ITEM : out NUM; WIDTH : in FIELD := 0);
procedure GET(ITEM : out NUM; WIDTH : in FIELD := 0);
If the value of the parameter WIDTH is zero, skips any leading
blanks, line terminators, or page terminators, then reads a plus
or a minus sign if present, then reads according to the syntax of
a real literal (which may be a based literal). If a nonzero
value of WIDTH is supplied, then exactly WIDTH characters are
input, or the characters (possibly none) up to a line terminator,
whichever comes first; any skipped leading blanks are included
in the count.
14 - 43
Returns, in the parameter ITEM, the value of type NUM that
corresponds to the sequence input.
The exception DATA_ERROR is raised if the sequence input does not
have the required syntax or if the value obtained is not of the
subtype NUM.
14 - 44
procedure PUT(FILE : in FILE_TYPE;
ITEM : in NUM;
FORE : in FIELD := DEFAULT_FORE;
AFT : in FIELD := DEFAULT_AFT;
EXP : in FIELD := DEFAULT_EXP);
procedure PUT(ITEM : in NUM;
FORE : in FIELD := DEFAULT_FORE;
AFT : in FIELD := DEFAULT_AFT;
EXP : in FIELD := DEFAULT_EXP);
Outputs the value of the parameter ITEM as a decimal literal with
the format defined by FORE, AFT and EXP. If the value is
negative, a minus sign is included in the integer part. If EXP
has the value zero, then the integer part to be output has as
many digits as are needed to represent the integer part of the
value of ITEM, overriding FORE if necessary, or consists of the
digit zero if the value of ITEM has no integer part.
If EXP has a value greater than zero, then the integer part to be
output has a single digit, which is nonzero except for the value
0.0 of ITEM.
In both cases, however, if the integer part to be output has
fewer than FORE characters, including any minus sign, then
leading spaces are first output to make up the difference. The
number of digits of the fractional part is given by AFT, or is
one if AFT equals zero. The value is rounded; a value of
exactly one half in the last place may be rounded either up or
down.
If EXP has the value zero, there is no exponent part. If EXP has
a value greater than zero, then the exponent part to be output
has as many digits as are needed to represent the exponent part
of the value of ITEM (for which a single digit integer part is
used), and includes an initial sign (plus or minus). If the
exponent part to be output has fewer than EXP characters,
including the sign, then leading zeros precede the digits, to
make up the difference. For the value 0.0 of ITEM, the exponent
has the value zero.
procedure GET(FROM : in STRING; ITEM : out NUM; LAST : out POSITIVE);
Reads a real value from the beginning of the given string,
following the same rule as the GET procedure that reads a real
value from a file, but treating the end of the string as a file
terminator. Returns, in the parameter ITEM, the value of type
NUM that corresponds to the sequence input. Returns in LAST the
index value such that FROM(LAST) is the last character read.
The exception DATA_ERROR is raised if the sequence input does not
have the required syntax, or if the value obtained is not of the
subtype NUM.
14 - 45
procedure PUT(TO : out STRING;
ITEM : in NUM;
AFT : in FIELD := DEFAULT_AFT;
EXP : in INTEGER := DEFAULT_EXP);
Outputs the value of the parameter ITEM to the given string,
following the same rule as for output to a file, using a value
for FORE such that the sequence of characters output exactly
fills the string, including any leading spaces.
14 - 46
Examples:
package REAL_IO is new FLOAT_IO(REAL); use REAL_IO;
-- default format used at instantiation, DEFAULT_EXP = 3
X : REAL := -123.4567; -- digits 8 (see 3.5.7)
PUT(X); -- default format "-1.2345670E+02"
PUT(X, FORE => 5, AFT => 3, EXP => 2); -- "bbb-1.235E+2"
PUT(X, 5, 3, 0); -- "b-123.457"
Note:
For an item with a positive value, if output to a string exactly fills the
string without leading spaces, then output of the corresponding negative
value will raise LAYOUT_ERROR.
References: aft attribute 3.5.10, based literal 2.4.2, blank 14.3.5,
data_error exception 14.3.5, decimal literal 2.4.1, field subtype 14.3.5,
file_type 14.1, fixed_io package 14.3.10, floating_io package 14.3.10, fore
attribute 3.5.10, get procedure 14.3.5, layout_error 14.3.5, line
terminator 14.3.5, put procedure 14.3.5, real literal 2.4, skipping 14.3.5,
width 14.3.5
14.3.9 Input-Output for Enumeration Types
The following procedures are defined in the generic package ENUMERATION_IO,
which must be instantiated for the appropriate enumeration type (indicated
by ENUM in the specification).
Values are output using either upper or lower case letters for identifiers.
This is specified by the parameter SET, which is of the enumeration type
TYPE_SET.
type TYPE_SET is (LOWER_CASE, UPPER_CASE);
The format (which includes any trailing spaces) can be specified by an
optional field width parameter. The default field width and letter case
are defined by the following variables that are declared in the generic
package ENUMERATION_IO:
DEFAULT_WIDTH : FIELD := 0;
DEFAULT_SETTING : TYPE_SET := UPPER_CASE;
The following procedures are provided:
procedure GET(FILE : in FILE_TYPE; ITEM : out ENUM);
procedure GET(ITEM : out ENUM);
After skipping any leading blanks, line terminators, or page
terminators, reads an identifier according to the syntax of this
14 - 47
lexical element (lower and upper case being considered
equivalent), or a character literal according to the syntax of
this lexical element (including the apostrophes). Returns, in
the parameter ITEM, the value of type ENUM that corresponds to
the sequence input.
The exception DATA_ERROR is raised if the sequence input does not
have the required syntax, or if the identifier or character
literal does not correspond to a value of the subtype ENUM.
14 - 48
procedure PUT(FILE : in FILE_TYPE;
ITEM : in ENUM;
WIDTH : in FIELD := DEFAULT_WIDTH;
SET : in TYPE_SET := DEFAULT_SETTING);
procedure PUT(ITEM : in ENUM;
WIDTH : in FIELD := DEFAULT_WIDTH;
SET : in TYPE_SET := DEFAULT_SETTING);
Outputs the value of the parameter ITEM as an enumeration literal
(either an identifier or a character literal). The optional
parameter SET indicates whether lower case or upper case is used
for identifiers; it has no effect for character literals. If
the sequence of characters produced has fewer than WIDTH
characters, then trailing spaces are finally output to make up
the difference.
procedure GET(FROM : in STRING; ITEM : out ENUM; LAST : out POSITIVE);
Reads an enumeration value from the beginning of the given
string, following the same rule as the GET procedure that reads
an enumeration value from a file, but treating the end of the
string as a file terminator. Returns, in the parameter ITEM, the
value of type ENUM that corresponds to the sequence input.
Returns in LAST the index value such that FROM(LAST) is the last
character read.
The exception DATA_ERROR is raised if the sequence input does not
have the required syntax, or if the identifier or character
literal does not correspond to a value of the subtype ENUM.
procedure PUT(TO : out STRING;
ITEM : in ENUM;
SET : in TYPE_SET := DEFAULT_SETTING);
Outputs the value of the parameter ITEM to the given string,
following the same rule as for output to a file, using the length
of the given string as the value for WIDTH.
Although the specification of the package ENUMERATION_IO would allow
instantiation for an integer type, this is not the intended purpose of this
generic package, and the effect of such instantiations is not defined by
the language.
Notes:
There is a difference between PUT defined for characters, and for
enumeration values. Thus
TEXT_IO.PUT('A'); -- outputs the character A
14 - 49
package CHAR_IO is new TEXT_IO.ENUMERATION_IO(CHARACTER);
CHAR_IO.PUT('A'); -- outputs the character 'A', between single quotes
The type BOOLEAN is an enumeration type, hence ENUMERATION_IO can be
instantiated for this type.
References: blank 14.3.5, data_error 14.3.5, enumeration_io package
14.3.10, field subtype 14.3.5, file_type 14.1, get procedure 14.3.5, line
terminator 14.3.5, put procedure 14.3.5, skipping 14.3.5, width 14.3.5
14 - 50
14.3.10 Specification of the Package Text_IO
with IO_EXCEPTIONS;
package TEXT_IO is
type FILE_TYPE is limited private;
type FILE_MODE is (IN_FILE, OUT_FILE);
type COUNT is range 0 .. IMPLEMENTATION_DEFINED;
subtype POSITIVE_COUNT is COUNT range 1 .. COUNT'LAST;
UNBOUNDED : constant COUNT := 0; -- line and page length
subtype FIELD is INTEGER range 0 .. IMPLEMENTATION_DEFINED;
subtype NUMBER_BASE is INTEGER range 2 .. 16;
type TYPE_SET is (LOWER_CASE, UPPER_CASE);
-- File Management
procedure CREATE (FILE : in out FILE_TYPE;
MODE : in FILE_MODE := OUT_FILE;
NAME : in STRING := "";
FORM : in STRING := "");
procedure OPEN (FILE : in out FILE_TYPE;
MODE : in FILE_MODE;
NAME : in STRING;
FORM : in STRING := "");
procedure CLOSE (FILE : in out FILE_TYPE);
procedure DELETE (FILE : in out FILE_TYPE);
procedure RESET (FILE : in out FILE_TYPE; MODE : in FILE_MODE);
procedure RESET (FILE : in out FILE_TYPE);
function MODE (FILE : in FILE_TYPE) return FILE_MODE;
function NAME (FILE : in FILE_TYPE) return STRING;
function FORM (FILE : in FILE_TYPE) return STRING;
function IS_OPEN(FILE : in FILE_TYPE) return BOOLEAN;
-- Control of default input and output files
procedure SET_INPUT (FILE : in FILE_TYPE);
procedure SET_OUTPUT(FILE : in FILE_TYPE);
function STANDARD_INPUT return FILE_TYPE;
function STANDARD_OUTPUT return FILE_TYPE;
function CURRENT_INPUT return FILE_TYPE;
function CURRENT_OUTPUT return FILE_TYPE;
14 - 51
-- Specification of line and page lengths
procedure SET_LINE_LENGTH(FILE : in FILE_TYPE; TO : in COUNT);
procedure SET_LINE_LENGTH(TO : in COUNT);
procedure SET_PAGE_LENGTH(FILE : in FILE_TYPE; TO : in COUNT);
procedure SET_PAGE_LENGTH(TO : in COUNT);
function LINE_LENGTH(FILE : in FILE_TYPE) return COUNT;
function LINE_LENGTH return COUNT;
function PAGE_LENGTH(FILE : in FILE_TYPE) return COUNT;
function PAGE_LENGTH return COUNT;
-- Column, Line, and Page Control
procedure NEW_LINE (FILE : in FILE_TYPE; SPACING : in POSITIVE_COUNT := 1);
procedure NEW_LINE (SPACING : in POSITIVE_COUNT := 1);
procedure SKIP_LINE (FILE : in FILE_TYPE; SPACING : in POSITIVE_COUNT := 1);
procedure SKIP_LINE (SPACING : in POSITIVE_COUNT := 1);
function END_OF_LINE(FILE : in FILE_TYPE) return BOOLEAN;
function END_OF_LINE return BOOLEAN;
procedure NEW_PAGE (FILE : in FILE_TYPE);
procedure NEW_PAGE;
procedure SKIP_PAGE (FILE : in FILE_TYPE);
procedure SKIP_PAGE;
function END_OF_PAGE(FILE : in FILE_TYPE) return BOOLEAN;
function END_OF_PAGE return BOOLEAN;
function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
function END_OF_FILE return BOOLEAN;
procedure SET_COL (FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
procedure SET_COL (TO : in POSITIVE_COUNT);
procedure SET_LINE(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
procedure SET_LINE(TO : in POSITIVE_COUNT);
function COL (FILE : in FILE_TYPE) return POSITIVE_COUNT;
function COL return POSITIVE_COUNT;
function LINE(FILE : in FILE_TYPE) return POSITIVE_COUNT;
function LINE return POSITIVE_COUNT;
function PAGE(FILE : in FILE_TYPE) return POSITIVE_COUNT;
function PAGE return POSITIVE_COUNT;
14 - 52
-- Character Input-Output
procedure GET(FILE : in FILE_TYPE; ITEM : out CHARACTER);
procedure GET(ITEM : out CHARACTER);
procedure PUT(FILE : in FILE_TYPE; ITEM : in CHARACTER);
procedure PUT(ITEM : in CHARACTER);
-- String Input-Output
procedure GET(FILE : in FILE_TYPE; ITEM : out STRING);
procedure GET(ITEM : out STRING);
procedure PUT(FILE : in FILE_TYPE; ITEM : in STRING);
procedure PUT(ITEM : in STRING);
procedure GET_LINE(FILE : in FILE_TYPE; ITEM : out STRING; LAST : out NATURAL);
procedure GET_LINE(ITEM : out STRING; LAST : out NATURAL);
procedure PUT_LINE(FILE : in FILE_TYPE; ITEM : in STRING);
procedure PUT_LINE(ITEM : in STRING);
-- Generic package for Input-Output of Integer Types
generic
type NUM is range <>;
package INTEGER_IO is
DEFAULT_WIDTH : FIELD := NUM'WIDTH;
DEFAULT_BASE : NUMBER_BASE := 10;
procedure GET(FILE : in FILE_TYPE; ITEM : out NUM; WIDTH : in FIELD := 0);
procedure GET(ITEM : out NUM; WIDTH : in FIELD := 0);
procedure PUT(FILE : in FILE_TYPE;
ITEM : in NUM;
WIDTH : in FIELD := DEFAULT_WIDTH;
BASE : in NUMBER_BASE := DEFAULT_BASE);
procedure PUT(ITEM : in NUM;
WIDTH : in FIELD := DEFAULT_WIDTH;
BASE : in NUMBER_BASE := DEFAULT_BASE);
procedure GET(FROM : in STRING; ITEM : out NUM; LAST : out POSITIVE);
procedure PUT(TO : out STRING;
ITEM : in NUM;
BASE : in NUMBER_BASE := DEFAULT_BASE);
end INTEGER_IO;
14 - 53
-- Generic packages for Input-Output of Real Types
generic
type NUM is digits <>;
package FLOAT_IO is
DEFAULT_FORE : FIELD := 2;
DEFAULT_AFT : FIELD := NUM'DIGITS-1;
DEFAULT_EXP : FIELD := 3;
procedure GET(FILE : in FILE_TYPE; ITEM : out NUM; WIDTH : in FIELD := 0);
procedure GET(ITEM : out NUM; WIDTH : in FIELD := 0);
procedure PUT(FILE : in FILE_TYPE;
ITEM : in NUM;
FORE : in FIELD := DEFAULT_FORE;
AFT : in FIELD := DEFAULT_AFT;
EXP : in FIELD := DEFAULT_EXP);
procedure PUT(ITEM : in NUM;
FORE : in FIELD := DEFAULT_FORE;
AFT : in FIELD := DEFAULT_AFT;
EXP : in FIELD := DEFAULT_EXP);
procedure GET(FROM : in STRING; ITEM : out NUM; LAST : out POSITIVE);
procedure PUT(TO : out STRING;
ITEM : in NUM;
AFT : in FIELD := DEFAULT_AFT;
EXP : in FIELD := DEFAULT_EXP);
end FLOAT_IO;
generic
type NUM is delta <>;
package FIXED_IO is
DEFAULT_FORE : FIELD := NUM'FORE;
DEFAULT_AFT : FIELD := NUM'AFT;
DEFAULT_EXP : FIELD := 0;
procedure GET(FILE : in FILE_TYPE; ITEM : out NUM; WIDTH : in FIELD := 0);
procedure GET(ITEM : out NUM; WIDTH : in FIELD := 0);
procedure PUT(FILE : in FILE_TYPE;
ITEM : in NUM;
FORE : in FIELD := DEFAULT_FORE;
AFT : in FIELD := DEFAULT_AFT;
EXP : in FIELD := DEFAULT_EXP);
procedure PUT(ITEM : in NUM;
FORE : in FIELD := DEFAULT_FORE;
AFT : in FIELD := DEFAULT_AFT;
EXP : in FIELD := DEFAULT_EXP);
procedure GET(FROM : in STRING; ITEM : out NUM; LAST : out POSITIVE);
procedure PUT(TO : out STRING;
ITEM : in NUM;
AFT : in FIELD := DEFAULT_AFT;
14 - 54
EXP : in FIELD := DEFAULT_EXP);
end FIXED_IO;
14 - 55
-- Generic package for Input-Output of Enumeration Types
generic
type ENUM is (<>);
package ENUMERATION_IO is
DEFAULT_WIDTH : FIELD := 0;
DEFAULT_SETTING : TYPE_SET := UPPER_CASE;
procedure GET(FILE : in FILE_TYPE; ITEM : out ENUM);
procedure GET(ITEM : out ENUM);
procedure PUT(FILE : in FILE_TYPE;
ITEM : in ENUM;
WIDTH : in FIELD := DEFAULT_WIDTH;
SET : in TYPE_SET := DEFAULT_SETTING);
procedure PUT(ITEM : in ENUM;
WIDTH : in FIELD := DEFAULT_WIDTH;
SET : in TYPE_SET := DEFAULT_SETTING);
procedure GET(FROM : in STRING; ITEM : out ENUM; LAST : out POSITIVE);
procedure PUT(TO : out STRING;
ITEM : in ENUM;
SET : in TYPE_SET := DEFAULT_SETTING);
end ENUMERATION_IO;
-- Exceptions
STATUS_ERROR : exception renames IO_EXCEPTIONS.STATUS_ERROR;
MODE_ERROR : exception renames IO_EXCEPTIONS.MODE_ERROR;
NAME_ERROR : exception renames IO_EXCEPTIONS.NAME_ERROR;
USE_ERROR : exception renames IO_EXCEPTIONS.USE_ERROR;
DEVICE_ERROR : exception renames IO_EXCEPTIONS.DEVICE_ERROR;
END_ERROR : exception renames IO_EXCEPTIONS.END_ERROR;
DATA_ERROR : exception renames IO_EXCEPTIONS.DATA_ERROR;
LAYOUT_ERROR : exception renames IO_EXCEPTIONS.LAYOUT_ERROR;
private
-- implementation-dependent
end TEXT_IO;
14.4 Exceptions in Input-Output
The following exceptions can be raised by input-output operations. They
are declared in the package IO_EXCEPTIONS, defined in section 14.5; this
package is named in the context clause for each of the three input-output
packages. Only outline descriptions are given of the conditions under
which NAME_ERROR, USE_ERROR, and DEVICE_ERROR are raised; for full details
see Appendix F. If more than one error condition exists, the corresponding
exception that appears earliest in the following list is the one that is
raised.
14 - 56
The exception STATUS_ERROR is raised by an attempt to operate upon a file
that is not open, and by an attempt to open a file that is already open.
14 - 57
The exception MODE_ERROR is raised by an attempt to read from, or test for
the end of, a file whose current mode is OUT_FILE, and also by an attempt
to write to a file whose current mode is IN_FILE. In the case of TEXT_IO,
the exception MODE_ERROR is also raised by specifying a file whose current
mode is OUT_FILE in a call of SET_INPUT, SKIP_LINE, END_OF_LINE, SKIP_PAGE,
or END_OF_PAGE; and by specifying a file whose current mode is IN_FILE in
a call of SET_OUTPUT, SET_LINE_LENGTH, SET_PAGE_LENGTH, LINE_LENGTH,
PAGE_LENGTH, NEW_LINE, or NEW_PAGE.
The exception NAME_ERROR is raised by a call of CREATE or OPEN if the
string given for the parameter NAME does not allow the identification of an
external file. For example, this exception is raised if the string is
improper, or, alternatively, if either none or more than one external file
corresponds to the string.
The exception USE_ERROR is raised if an operation is attempted that is not
possible for reasons that depend on characteristics of the external file.
For example, this exception is raised by the procedure CREATE, among other
circumstances, if the given mode is OUT_FILE but the form specifies an
input only device, if the parameter FORM specifies invalid access rights,
or if an external file with the given name already exists and overwriting
is not allowed.
The exception DEVICE_ERROR is raised if an input-output operation cannot be
completed because of a malfunction of the underlying system.
The exception END_ERROR is raised by an attempt to skip (read past) the end
of a file.
The exception DATA_ERROR may be raised by the procedure READ if the element
read cannot be interpreted as a value of the required type. This exception
is also raised by a procedure GET (defined in the package TEXT_IO) if the
input character sequence fails to satisfy the required syntax, or if the
value input does not belong to the range of the required type or subtype.
The exception LAYOUT_ERROR is raised (in text input-output) by COL, LINE,
or PAGE if the value returned exceeds COUNT'LAST. The exception
LAYOUT_ERROR is also raised on output by an attempt to set column or line
numbers in excess of specified maximum line or page lengths, respectively
(excluding the unbounded cases). It is also raised by an attempt to PUT
too many characters to a string.
References: col function 14.3.4, create procedure 14.2.1, end_of_line
function 14.3.4, end_of_page function 14.3.4, external file 14.1, file
14.1, form string 14.1, get procedure 14.3.5, in_file 14.1, io_exceptions
package 14.5, line function 14.3.4, line_length function 14.3.4, name
string 14.1, new_line procedure 14.3.4, new_page procedure 14.3.4, open
procedure 14.2.1, out_file 14.1, page function 14.3.4, page_length function
14.3.4, put procedure 14.3.5, read procedure 14.2.2 14.2.3, set_input
procedure 14.3.2, set_line_length 14.3.3, set_page_length 14.3.3,
set_output 14.3.2, skip_line procedure 14.3.4, skip_page procedure 14.3.4,
text_io package 14.3
14 - 58
14.5 Specification of the Package IO_Exceptions
This package defines the exceptions needed by the packages SEQUENTIAL_IO,
DIRECT_IO, and TEXT_IO.
package IO_EXCEPTIONS is
STATUS_ERROR : exception;
MODE_ERROR : exception;
NAME_ERROR : exception;
USE_ERROR : exception;
DEVICE_ERROR : exception;
END_ERROR : exception;
DATA_ERROR : exception;
LAYOUT_ERROR : exception;
end IO_EXCEPTIONS;
14.6 Low Level Input-Output
A low level input-output operation is an operation acting on a physical
device. Such an operation is handled by using one of the (overloaded)
predefined procedures SEND_CONTROL and RECEIVE_CONTROL.
A procedure SEND_CONTROL may be used to send control information to a
physical device. A procedure RECEIVE_CONTROL may be used to monitor the
execution of an input-output operation by requesting information from the
physical device.
Such procedures are declared in the standard package LOW_LEVEL_IO and have
two parameters identifying the device and the data. However, the kinds and
formats of the control information will depend on the physical
characteristics of the machine and the device. Hence, the types of the
parameters are implementation-defined. Overloaded definitions of these
procedures should be provided for the supported devices.
The visible part of the package defining these procedures is outlined as
follows:
package LOW_LEVEL_IO is
-- declarations of the possible types for DEVICE and DATA;
-- declarations of overloaded procedures for these types:
procedure SEND_CONTROL (DEVICE : DEVICE_TYPE; DATA : in out DATA_TYPE);
procedure RECEIVE_CONTROL (DEVICE : DEVICE_TYPE; DATA : in out DATA_TYPE);
end;
The bodies of the procedures SEND_CONTROL and RECEIVE_CONTROL for various
devices can be supplied in the body of the package LOW_LEVEL_IO. These
procedure bodies may be written with code statements.
14 - 59
14.7 Example of Input-Output
The following example shows the use of some of the text input-output
facilities in a dialogue with a user at a terminal. The user is prompted
to type a color, and the program responds by giving the number of items of
that color available in stock, according to an inventory. The default
input and output files are used. For simplicity, all the requisite
instantiations are given within one subprogram; in practice, a package,
separate from the procedure, would be used.
with TEXT_IO; use TEXT_IO;
procedure DIALOGUE is
type COLOR is (WHITE, RED, ORANGE, YELLOW, GREEN, BLUE, BROWN);
package COLOR_IO is new ENUMERATION_IO(ENUM => COLOR);
package NUMBER_IO is new INTEGER_IO(INTEGER);
use COLOR_IO, NUMBER_IO;
INVENTORY : array (COLOR) of INTEGER := (20, 17, 43, 10, 28, 173, 87);
CHOICE : COLOR;
procedure ENTER_COLOR (SELECTION : out COLOR) is
begin
loop
begin
PUT("Color selected: "); -- prompts user
GET(SELECTION); -- accepts color typed, or raises exception
return;
exception
when DATA_ERROR =>
PUT("Invalid color, try again. "); -- user has typed new line
NEW_LINE(2);
-- completes execution of the block statement
end;
end loop; -- repeats the block statement until color accepted
end;
begin -- statements of DIALOGUE;
NUMBER_IO.DEFAULT_WIDTH := 5;
loop
ENTER_COLOR(CHOICE); -- user types color and new line
SET_COL(5); PUT(CHOICE); PUT(" items available:");
SET_COL(40); PUT(INVENTORY(CHOICE)); -- default width is 5
NEW_LINE;
end loop;
end DIALOGUE;
Example of an interaction (characters typed by the user are italicized):
Color selected: Black
Invalid color, try again.
14 - 60
Color selected: Blue
BLUE items available: 173
Color selected: Yellow
YELLOW items available: 10
14 - 61