[Home] [Prev] [Next] [Index]

14.3 Text Input-Output

14.3 Text Input-Output

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

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

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

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

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

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

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

8
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;

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

10
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.3.1 File Management

1
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:

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

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

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

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

6
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

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

2
procedure SET_INPUT(FILE : in FILE_TYPE);

3
Operates on a file of mode IN_FILE. Sets the current default input file to FILE.

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

5
procedure SET_OUTPUT(FILE : in FILE_TYPE);

6
Operates on a file of mode OUT_FILE. Sets the current default output file to FILE.

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

8
function STANDARD_INPUT return FILE_TYPE;

9
Returns the standard input file (see 14.3).

10
function STANDARD_OUTPUT return FILE_TYPE;

11
Returns the standard output file (see 14.3).

12
function CURRENT_INPUT return FILE_TYPE;

13
Returns the current default input file.

14
function CURRENT_OUTPUT return FILE_TYPE;

15
Returns the current default output file.

Note:

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

17
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

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

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

3
procedure SET_LINE_LENGTH(FILE : in FILE_TYPE; TO : in COUNT);
procedure SET_LINE_LENGTH(TO : in COUNT);

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

5
The exception USE_ERROR is raised if the specified line length is inappropriate for the associated external file.

6
procedure SET_PAGE_LENGTH(FILE : in FILE_TYPE; TO : in COUNT);
procedure SET_PAGE_LENGTH(TO : in COUNT);

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

8
The exception USE_ERROR is raised if the specified page length is inappropriate for the associated external file.

9
function LINE_LENGTH(FILE : in FILE_TYPE) return COUNT;
function LINE_LENGTH return COUNT;

10
Returns the maximum line length currently set for the specified output file, or zero if the line length is unbounded.

11
function PAGE_LENGTH(FILE : in FILE_TYPE) return COUNT;
function PAGE_LENGTH COUNT;

12
Returns the maximum page length currently set for the specified output file, or zero if the page length is unbounded.

13
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

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

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

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

4
For a SPACING greater than one, the above actions are performed SPACING times.

5
The exception MODE_ERROR is raised if the mode is not OUT_FILE.

6
procedure SKIP_LINE(FILE : in FILE_TYPE;
               SPACING : in POSITIVE_COUNT := 1);
procedure SKIP_LINE(SPACING : in POSITIVE_COUNT := 1);

7
Operates on a file of mode IN_FILE.

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

9
For a SPACING greater than one, the above actions are performed SPACING times.

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

11
function END_OF_LINE(FILE : in FILE_TYPE) return BOOLEAN;
function END_OF_LINE return BOOLEAN;

12
Operates on a file of mode IN_FILE. Returns TRUE if a line terminator or a file terminator is next; otherwise returns FALSE.

13
The exception MODE_ERROR is raised if the mode is not IN_FILE.

14
procedure NEW_PAGE(FILE : in FILE_TYPE);
procedure NEW_PAGE;

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

16
The exception MODE_ERROR is raised if the mode is not OUT_FILE.

17
procedure SKIP_PAGE(FILE: in FILE_TYPE);
procedure SKIP_PAGE;

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

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

20
function END_OF_PAGE(FILE : in FILE_TYPE) return BOOLEAN;
function END_OF_PAGE return BOOLEAN;

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

22
The exception MODE_ERROR is raised if the mode is not IN_FILE.

23
function END_OF_FILE(FILE : in FILE_TYPE) return BOOLEAN;
function END_OF_FILE return BOOLEAN;

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

25
The exception MODE_ERROR is raised if the mode is not IN_FILE.

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

27
procedure SET_COL(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
procedure SET_COL(TO : in POSITIVE_COUNT);

28
If the file mode is OUT_FILE:

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

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

31
If the file mode is IN_FILE:

32
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.3.5). (Short lines will be skipped until a line is reached that has a character at the specified column position.)

33
The exception END_ERROR is raised if an attempt is made to read a file terminator.

34
procedure SET_LINE(FILE : in FILE_TYPE; TO : in POSITIVE_COUNT);
procedure SET_LINE(TO : in POSITIVE_COUNT);

35
If the file mode is OUT_FILE:

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

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

38
If the mode is IN_FILE:

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

40
The exception END_ERROR is raised if an attempt is made to read a file terminator.

41
function COL(FILE : in FILE_TYPE) return POSITIVE_COUNT;
function COL return POSITIVE_COUNT;

42
Returns the current column number.

43
The exception LAYOUT_ERROR is raised if this number exceeds COUNT'LAST.

44
function LINE(FILE : in FILE_TYPE) return POSITIVE_COUNT;
function LINE return POSITIVE_COUNT;

45
Returns the current line number.

46
The exception LAYOUT_ERROR is raised if this number exceeds COUNT'LAST.

47
function PAGE(FILE : in FILE_TYPE) return POSITIVE_COUNT;
function PAGE return POSITIVE_COUNT;

48
Returns the current page number.

49
The exception LAYOUT_ERROR is raised if this number exceeds COUNT'LAST.

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

Note:

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

52
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

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

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

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

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

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

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

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

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

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

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

11
Examples:

12
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

13
Example of overridden width parameter:

PUT(ITEM => -23, WIDTH => 2); -- "-23"

14
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

*
get procedure 14.3.7

*
get procedure 14.3.8

*
get procedure 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

*
put procedure 14.3.7

*
put procedure 14.3.8

*
put procedure 14.3.9

*
skipping 14.3.7

*
skipping 14.3.8

*
skipping 14.3.9

*
status_error exception 14.4

*
width 14.3.5

*
width 14.3.7

*
width 14.3.9



[Home] [Prev] [Next] [Index]

documentation@rational.com
Copyright © 1993-2000, Rational Software Corporation. All rights reserved.