A.10.5 Operations on Columns, Lines, and Pages
Static Semantics
The subprograms described in this subclause 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 propagated 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 or Append_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, 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 propagated if the mode is not Out_File or Append_File.
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 propagated if the mode is not In_File. The exception End_Error is
propagated 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 propagated 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 or Append_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 propagated if the mode is not Out_File or Append_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.
The exception Mode_Error
is propagated if the mode is not In_File. The exception End_Error is
propagated if an attempt is made to read a file terminator.
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 propagated 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 propagated 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 or Append_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 propagated
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
A.10.6).
(Short lines will be skipped until a line is reached that has a character
at the specified column position.)
The exception
End_Error is propagated if an attempt is made to read a file terminator.
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 or Append_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, if To is greater
than 1, by a call of New_Line with a spacing equal to (To – 1).
The exception Layout_Error is propagated
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 propagated 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 propagated 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 propagated if this number exceeds Count'Last.
function Page(File : in File_Type) return Positive_Count;
function Page return Positive_Count;
Returns the current page number.
The exception Layout_Error
is propagated 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 propagated. However, a call of Col, Line, or
Page propagates the exception Layout_Error if the corresponding number
exceeds Count'Last.
NOTE A page terminator is always
skipped whenever the preceding line terminator is skipped. An implementation
can represent the combination of these terminators by a single character,
provided that it is properly recognized on input.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
