| # Section 8.10.3.8: TEXT_FILE_CURSOR |

###### class TEXT_FILE_CURSOR < $FILE_CURSORS

#### Formal Types

types
SAME = TEXT_FILE_CURSOR ;

This class implements a model of a cursor (and associated buffer) into a file whose contents is text data in some encoding.

#### External specifications

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

- position : CARD
- position(at : CARD) : SAME
- forward(cnt : CARD) : SAME
- backward(cnt : CARD) : SAME
- skip(cnt : CARD) : SAME
- size : CARD
- readable : BOOL
- writable : BOOL
- at_end : BOOL
- error : BOOL
- error_message : STR
- clear

retract : SAME

#### retract

This feature retracts the cursor by one character position (which is not in general one storage unit.

retract | : SAME

##### Formal Signature

retract(self : SAME) res : SAME

##### Pre-condition

pre let temp = position(self,0) in position(self) > position(temp)

##### Post-condition

post let temp = skip(self,1) in position(self)~ = position(temp)

This routine moves the file cursor back by one character position and returns the resulting cursor.

#### skip_to

This skip variant searches for the first occurrence of the given character in the file (if there is one).

skip_to | (
| ch : CHAR
| )

##### Formal Signature

skip_to(self : SAME, ch : CHAR)

##### Pre-condition

pre readable(self)

##### Post-condition

Note that the definition below implies that the remaining contents of the file may be anything and the post-condition must therefore be true.

post true

This feature moves the cursor forward until the next occurrence of the given character or the end of the file, whichever occurs first.

#### skip_over

This skip variant searches for the first occurrence of the given character in the file (if there is one) and then moves the cursor past it.

skip_over | (
| ch : CHAR
| )

##### Formal Signature

skip_over(self : SAME, ch : CHAR)

##### Pre-condition

pre readable(self)

##### Post-condition

Note that the definition below implies that the remaining contents of the file may be anything and the post-condition must therefore be true.

post true

This feature moves the cursor forward until after the next occurrence of the given character or the end of the file, whichever occurs first.

#### skip_line

This skip variant looks for the encoding which represents the end of line mark in the file encoding and repertoire and skips over it - or to the end of file.

skip_line |

##### Formal Signature

skip_line(self : SAME)

##### Pre-condition

pre readable(self)

##### Post-condition

Note that the definition below implies that the remaining contents of the file may be anything and the post-condition must therefore be true.

post true

This feature moves the cursor forward past the next end of line mark or to the end of the file, whichever occurs first.

#### getch

This first input routine merely returns the next character in the file (which will always be a single encoding, but may be of up to four octets).

get | : CHAR

##### Formal Signature

getch(self : SAME) res : CHAR

##### Pre-condition

pre readable(self)

##### Post-condition

post (at_end(self)
or (position(self) > position(self)~)

This feature returns a single character from the current cursor position, moving the position forward by as many octets as needed.

#### get_upto

This input feature searches for the given character in the buffer on the current text line. The contents of the buffer up to either the character or the end of the line are returned as a string.

get_upto | (
| item : CHAR
| ) : STR

##### Formal Signature

get_upto(self : SAME, item : CHAR) res : STR

##### Pre-condition

pre readable(self)

##### Post-condition

post true

This feature returns a (possibly empty) text string up to the next occurrence of ch or up to the end of the current line of text, whichever occurs first.

#### get_line

This final input feature returns the contents of the file up to but not including the next end of line mark.

get_line | : STR

##### Formal Signature

get_line(self : SAME) res : STR

##### Pre-condition

pre readable(self)

##### Post-condition

post true

This feature returns all of the character remaining on the current line of text, advancing the cursor by as many places. The string returned does not include the end of line mark.

#### plus

This first variant of plus places the value of the single character item at the current position in the file buffer. Note that this may involve up to four octets, dependent on the encoding in use.

plus | (
| item : CHAR
| )

##### Formal Signature

plus1(self : SAME, item : CHAR)

##### Pre-condition

pre writable(self)

##### Post-condition

post (position(self) > position(self)~)

This feature sets the value of item into the current file position in the file buffer associated with this cursor.

#### plus

This second variant of plus places the value of the single character at the current position in the file buffer and then returns the cursor.

plus | (
| item : CHAR
| ) : SAME

##### Formal Signature

plus2(self : SAME, item : CHAR) res : SAME

##### Pre-condition

pre writable(self)

##### Post-condition

post (position(self) > position(self)~)
and res = self

This feature makes the value of the current file position equal to item and moves the cursor forward by one.

#### plus

This is the first of the two features which are provided to send a string of text data to the file associated with this cursor. Note that the amount of storage occupied will never be less than the number of characters in the string, but may be much more, dependent on the encoding in use for the given string.

plus | (
| entity : STR
| )

##### Formal Signature

plus3(self : SAME, entity : STR)

##### Pre-condition

pre writable(self)
and (STR.size(entity) > 0)

##### Post-condition

post (position(self) >= (position(self)~ + STR.size(entity)))

This feature appends the given test string at the current position in the file buffer. The cursor position is moved forward by the storage size of the string. This action may or may not involve writing to the underlying file.

#### plus

This is the second feature provided to send a string of text data to the file associated with this cursor, extending the length of the file as needed. This variant returns the cursor itself.

plus | (
| entity : STR
| ) : SAME

##### Formal Signature

plus4(self : SAME, entity : STR) res : SAME

##### Pre-condition

pre writable(self)
and (STR.size(entity) > 0)

##### Post-condition

post (position(self) >= (position(self)~ + STR.size(entity)))
and res = self

This feature sets the file contents for the number of octets in the binary string to be the values of the binary string. The cursor position is moved forward by that number of octets. The cursor itself is then returned.

#### flush

This feature ensures that any buffer contents which has not been written to the file has been written, synchronising the program with the file store.

flush

##### Formal Signature

flush(self : SAME)

##### Pre-condition

This is vacuously true.

##### Post-condition

Any output which has been sent to the file since either it was opened or the most recent previous call of this routine, will be forced out to synchronise the file with the program.

This routine flushes the cursor buffer to the file, ensuring that file and program are synchronised.

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

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