Sather Home Page

Section 8.10.3.6:
TEXT_FILE

class TEXT_FILE < $FILES

Inheritance map $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 :-


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.
Produced with Amaya