# Section 8.10.3.8:
TEXT_FILE_CURSOR

###### class TEXT_FILE_CURSOR < $FILE_CURSORS(CHAR,STR}

#### Formal Types

types
SAME = TEXT_FILE_CURSOR ;
TEXT_FILE_CURSOR = seq of CHAR

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 of which $FILE_CURSORS{CHAR,STR} is a sub-type:-

- 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
- flush
- error : BOOL
- error_message : STR
- clear

The following 'output' routines are required to be implemented for this class in accordance with the specifications given in the abstract class $FILE_CURSORS{CHAR,STR} :-

- plus(elem : CHAR)
- plus(elem : CHAR) : SAME
- plus(str : STR)
- plus(str : STR) : SAME

#### retract

This feature retracts the cursor by one character position, making the new current position one less than previously.

retract | : SAME

##### Formal Signature

retract(self : SAME) res : SAME

##### Pre-condition

pre position(self~) > 0

##### Post-condition

post position(self) + 1 = position(self~)

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

#### skip_to

This variant of skipping searches for the first occurrence of the given character in the file forward from the current cursor position.

skip_to | (
| ch : CHAR
| )

##### Formal Signature

skip_to(self : SAME, ch : CHAR)

##### Pre-condition

pre readable(self)

##### Post-condition

post (position(self) > len self)
or ((self(position(self)) = ch)
and (position(self) >= position(self~)))

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

post (position(self) > len self)
or ((self(position(self) - 1) = ch)
and (position(self) > position(self~)))

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

post true
post (position(self) > len self)
or let lmark = LIBCHARS.Line_Mark(LIBCHARS.default()) in
let position(self) be st
let start = position(self) - len lmark in
let test = self(start, ..., position(self)) in
(test = lmark)

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 ((res = self(position(self~)))
and (position(self) = position(self~) + 1))

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 ((position(self) > len self) and (res = self(position(self~), ..., len self)))
or let lmark = LIBCHARS.Line_Mark(LIBCHARS.default()) in
let position(self) be st
(let start = position(self) in
let test = self(start, ..., (start + len lmark)) in
((test = lmark)
or (self(position(self)) = ch))
and (res = self(position(self~), ..., (position(self) - 1))))

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 or to the end of the file, 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 ((position(self) > len self) and (res = self(position(self~), ..., len self)))
or let lmark = LIBCHARS.Line_Mark(LIBCHARS.default()) in
let position(self) be st
(let start = position(self) in
let test = self(start, ..., (start + len lmark)) in
(test = lmark)
and (res = self(position(self~), ..., (position(self) - 1))))

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

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

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