# Section 8.10.3.6:
TEXT_FILE

###### class TEXT_FILE < $FILES

#### Formal Types

types
SAME = TEXT_FILE ;
String_Type = seq of CHAR | CHAR ;

This class implements a model of a file which contains text in any possible character encoding and repertoire.

#### External specifications

The following routines are required to be implemented for this class in accordance with the specifications given in the abstract class $FILES :-

- open_for_read(name : STR) : TEXT_FILE
- open_for_write(name : STR) : TEXT_FILE
- open_at_end(name : STR) : TEXT_FILE
- open_for_update(name : STR) : TEXT_FILE
- open_at_end_for_update(name : STR) : TEXT_FILE
- create_for_write(name : STR) : TEXT_FILE
- create_for_update(name : STR) : TEXT_FILE
- create_temp : TEXT_FILE
- is_open : BOOL
- readable : BOOL
- writable : BOOL
- append : BOOL
- update : BOOL
- position : CARD
- size : CARD
- close
- error : BOOL
- error_message : STR
- clear

#### cursor

This feature is the first variant of text file cursor creation, creating a cursor object which provides a facility for handling very large files of text in the given repertoire and encoding (for example to be used when a computer system has not enough memory available for the entire file contents).

cursor | (
| size : CARD,
| lib : LIBCHARS
| ) : TEXT_FILE_CURSOR

##### Formal Signature

cursor(self : SAME, size : CARD, lib : LIBCHARS) res : TEXT_FILE_CURSOR

##### Pre-condition

pre is_open(self)
and (size mod 4) = 0

##### Post-condition

Since the return value is not an optional type and has a potentially infinite range, the post-condition is vacuously true.

This routine creates and returns a file buffer cursor object associated with self for text in the given repertoire and encoding.

#### cursor

This feature is the second variant which creates a text file cursor object for text in the program environment repertoire and encoding which provides a facility for handling very large files of text where a computer system has not enough memory available.

cursor | (
| size : CARD
| ) : TEXT_FILE_CURSOR

##### Formal Signature

cursor(self : SAME, size : CARD) res : TEXT_FILE_CURSOR

##### Pre-condition

pre is_open(self)
and (size mod 4) = 0

##### Post-condition

Since the return value is not an optional type this is vacuously true.

This routine creates and returns a file buffer cursor object associated with self for text in the program environment repertoire and encoding.

#### plus

This is the first of two features which are provided to send text data (of any repertoire and encoding) to a file, extending the length of the file as needed.

plus | (
| item : $STR
| )

##### Formal Signature

plus1(self : SAME, item : String_Type)

##### Pre-condition

pre writable(self)
and len item > 0

##### Post-condition

post res = nil
or (let head : seq of CHAR be st len head = position(self~) in
let tail : seq of CHAR be st head ^ tail = self~ in
let loc_obj : seq of CHAR =
cases item :
(is_CHAR(item)) -> [item],
others -> item
end in
(update(self)
and (self = head ^ loc_obj ^ tail((len tail - len entity), ..., (len tail))))
or (self = self~ ^ loc_obj)

This feature appends the given item to the text file channel to which self is a connection.

#### plus

This variant of plus sends the given item to the text file and then returns self if successful. otherwise void.

plus | (
| item : $STR
| ) : SAME

##### Formal Signature

plus2(self : SAME, item : multi) res : [SAME]

##### Pre-condition

pre writable(self)

##### Post-condition

post res = nil
or (let head : seq of CHAR be st len head = position(self~) in
let tail : seq of CHAR be st head ^ tail = self~ in
let loc_obj : seq of CHAR =
cases item :
(is_CHAR(item)) -> [item],
others -> item
end in
(update(self)
and (res = head ^ loc_obj ^ tail((len tail - len entity), ..., (len tail))))
or (res = self~ ^ loc_obj)

This feature appends the given item to the file channel to which self is a connection, returning self if successful, otherwise returning void.

#### fstr

This feature is the first of a pair which retrieve the contents of the given file into a mutable buffer which is returned.

fstr | (
| lib : LIBCHARS
| ) : FSTR

##### Formal Signature

str(self : SAME, lib : LIBCHARS) res : [FSTR]

##### Pre-condition

pre readable(self)

##### Post-condition

post (res = self)
and FSTR.index_lib(res) = lib

This feature returns a buffer containing the entire contents of the text file (which could be empty) provided that it was possible to set the environment next-location-to-read point at the beginning of the file, otherwise void. The text string is in the given encoding and repertoire.

#### fstr

This feature retrieves the contents of the given file, considering it to be in the program environment repertoire and encoding, into a buffer which is returned.

fstr | : FSTR

##### Formal Signature

fstr2(self : SAME) res : [FSTR]

##### Pre-condition

pre readable(self)

##### Post-condition

post (res = self)
and FSTR.index_lib(res) = LIBCHARS.default()

This feature returns a buffer containing the entire contents of the text file (which could be empty) provided that it was possible to set the environment next-location-to-read point at the beginning of the file, otherwise void. The text string is in the program environment encoding and repertoire.

#### frunes

This feature is the first of a pair of rune text retrieval features. The entire contents of the given file is transferred to a buffer which is organised to contain a sequence of runes (see notes in the class RUNE definition) in the given repertoire and encoding. The buffer itself is returned.

frunes | (
| lib : LIBCHARS
| ) : FRUNES

##### Formal Signature

frunes(self : SAME, lib : LIBCHARS) res : [FRUNES]

##### Pre-condition

pre readable(self)

##### Post-condition

post (res = self)
and FRUNES.index_lib(res) = lib

This feature returns a buffer containing the entire contents of the text file (which could be empty) provided that it was possible to set the environment next-location-to-read point at the beginning of the file, otherwise void. The rune string is composed on the basis that it is in the given encoding and repertoire.

#### frunes

This feature retrieves the contents of the given file, considering it to be in the program environment repertoire and encoding, into a buffer which is returned.

frunes | : FRUNES

##### Formal Signature

frunes2(self : SAME) res : [FSTR]

##### Pre-condition

pre readable(self)

##### Post-condition

post (res = self)
and FRUNES.index_lib(res) = LIBCHARS.default()

This feature returns a buffer containing the entire contents of the text file (which could be empty) provided that it was possible to set the environment next-location-to-read point at the beginning of the file, otherwise void. The rune string is composed assuming that the data is in the program environment encoding and repertoire.

| Language Index |  | Library Index |  | Input/Output Index

Comments or enquiries should be made to Keith Hopper. Page last modified: Friday, 17 November 2000. |