DocAda^(tm) is a productivity tool of KSCE

| | | |
About DocAda Light: Preface / Preliminary / Help / TOC / Copyright
DocAda Online at the Ada Home: Complete RM95 / Updates / News

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 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.

NOTES

(25) 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 on input.

About DocAda Light: Preface / Preliminary / Help / TOC / Copyright
DocAda Online at the Ada Home: Complete RM95 / Updates / News
| | | |