A.10 Text Input-Output

Static Semantics

This subclause 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 subclause A.10.1.

The facilities for file management given above, in
subclauses A.8.2 and A.8.3,
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
based on lexical elements (see Clause 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. Related to character input are
procedures to look ahead at the next character without reading it, and
to read a character “immediately” without waiting for an
end-of-line to signal availability.

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.

At the beginning of program execution
a default file for program-dependent error-related text output is the
so-called standard error file. This file is open, has the current mode
Out_File, and is associated with an implementation-defined external file.
A procedure is provided to change the current default error 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
(Get) or output (Put) of control characters (other than horizontal tabulation)
is not specified 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).

For an output
file or an append 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 or Append_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.