Module Interface TextRider

SUMMARY: MODULE | CLASS | TYPE | PROC | VAR | CONST | DETAIL: TYPE | PROC | VAR | CONST

# TextRider

### Import List

        Channel
        CharClass
        LRealStr
        Msg
        Object
        Object

Class List
ErrorContext | This record is exported, so that extensions of Channel can access the error descriptions by extending ErrorContextDesc.
Reader |
Scanner |
Writer |

Class Summary: ErrorContext [Detail]
      +---Msg.Context
           |
           +--TextRider.ErrorContext
This record is exported, so that extensions of Channel can access the error descriptions by extending ErrorContextDesc.
Inherited Fields
From Msg.Context: id
Method Summary
GetTemplate(Msg, VAR LString) Returns a template string for the message msg.
Inherited Methods
From Msg.Context: GetTemplate

Class Summary: Reader [Detail]
      +--TextRider.Reader
Field Summary
base-: Channel The channel on which this reader is operating.
byteReader-: Reader Binary reader underneath this text reader.
eol-: ARRAY n OF CHAR Character sequence of the end of line marker.
eolLen-: INTEGER Number of characters in eol.
opt-: SET Current reader options.
res: Msg
Constructor Summary
ConnectReader(Channel): Reader
InitReader(Reader, Channel)
Method Summary
Available(): LONGINT
ClearError()
Eol(): BOOLEAN Return TRUE if the character at the current position is the system-dependent end-of-line character sequence or the last character has been read.
Pos(): LONGINT
ReadBool(VAR BOOLEAN)
ReadChar(VAR CHAR) Read a character.
ReadHex(VAR LONGINT)
ReadIdentifier(VAR ARRAY OF CHAR)
ReadInt(VAR INTEGER) As Reader.ReadLInt.
ReadLInt(VAR LONGINT) Returns the long integer constant lint at the current position according to the format: ``IntConst = [whitespace] ["+"|"-"] digit {digit}`'.
ReadLReal(VAR LONGREAL) Returns the long real constant lreal at the current position according to the format ``LongRealConst = [whitespace] ["+" | "-"] digit {digit} ["." {digit} [exponent]]`' where ``exponent = ("E" | "D") ("+" | "-") digit {digit}`'.
ReadLine(VAR ARRAY OF CHAR) Reads characters until an end of line character is encountered, or the array s is full.
ReadLn()
ReadReal(VAR REAL) As Reader.ReadLReal.
ReadSInt(VAR SHORTINT) As Reader.ReadLInt.
ReadSet(VAR SET) Read a set described in Oberon-2 set notation into s.
ReadString(VAR ARRAY OF CHAR) Reads an Oberon-2 string literal.
SetEol(ARRAY OF CHAR, INTEGER) Sets new end of line marker.
SetOpts(SET) Set the reader options r.opt.
SetPos(LONGINT)

Class Summary: Scanner [Detail]
      +--TextRider.Scanner
Field Summary
base-: Channel
bool-: BOOLEAN Boolean from channel.
char-: CHAR Char from channel.
int-: LONGINT Integer from channel.
lines-: LONGINT Total of scanned eol markers.
opt-: SET Current scanner options.
pos-: LONGINT Position of current token in the channel.
r-: Reader Text reader underneath this scanner.
real-: LONGREAL Real from channel.
res: Msg
set-: SET Set from channel.
string-: String String from channel.
type-: INTEGER Type of the most recently scanned token.
Constructor Summary
ConnectScanner(Channel): Scanner
InitScanner(Scanner, Channel)
Method Summary
Available(): LONGINT
ClearError()
Pos(): LONGINT Return position of the look-ahead character.
Scan()
SetEol(ARRAY OF CHAR, INTEGER)
SetOpts(SET)
SetPos(LONGINT)

Class Summary: Writer [Detail]
      +--TextRider.Writer
Field Summary
base-: Channel The channel on which this writer is operating.
byteWriter-: Writer Binary writer underneath this text writer.
opt-: SET Current writer options.
res: Msg
Constructor Summary
ConnectWriter(Channel): Writer
InitWriter(Writer, Channel)
Method Summary
ClearError()
Pos(): LONGINT
SetEol(ARRAY OF CHAR, INTEGER) Sets new end of line marker.
SetOpts(SET) Set the writer options w.opt.
SetPos(LONGINT)
WriteBool(BOOLEAN)
WriteChar(CHAR)
WriteHex(LONGINT, LONGINT)
WriteInt(INTEGER, LONGINT)
WriteLInt(LONGINT, LONGINT)
WriteLReal(LONGREAL, LONGINT, LONGINT) Writes the value lreal in the format produced by LRealStr.RealToFloat.
WriteLRealEng(VAR LONGREAL, LONGINT, LONGINT) Writes the value lreal in the format produced by LRealStr.RealToEng.
WriteLRealFix(VAR LONGREAL, LONGINT, LONGINT) Writes the value lreal in the format produced by LRealStr.RealToFixed.
WriteLn() Write a newline.
WriteObject(Object)
WriteReal(REAL, LONGINT, LONGINT) As Writer.WriteLReal.
WriteRealEng(REAL, LONGINT, LONGINT) As Writer.WriteLRealEng.
WriteRealFix(REAL, LONGINT, LONGINT) As Writer.WriteLRealFix.
WriteSInt(SHORTINT, LONGINT)
WriteSet(SET) Write s in Oberon-2 set notation.
WriteString(ARRAY OF CHAR)

Type Summary
String = ARRAY n OF CHAR

Constant Summary
bool
char
defReaderOptions Default reader options.
defScannerOptions Default scanner options: interpret boolean, set, and string values, and signed integer values.
defWriterOptions Default writer options.
done
error
ident
int
interpretBools When set the Scanner returns truth values of the strings TRUE and FALSE.
interpretSets When set the Scanner returns a set value of the string set representation.
interpretStrings When set the Scanner returns a complete string contained within open and closing quotes.
invalid
invalidFormat
line
maxLengthEol Maximum length of an end of line character sequence.
noBuffering When set output is not buffered.
real
returnCtrlChars When set the Reader or Scanner returns EOL & TAB characters.
set
string
tab
undefined
useSignedNumbers When set the Scanner returns a complete signed number.
valueOutOfRange

Class Detail: ErrorContext

Method Detail

### GetTemplate

    PROCEDURE (context: ErrorContext) GetTemplate(msg: Msg;
                          VAR templ: LString)

> Returns a template string for the message msg. The string may contain attribute references. Instead of the reference ``${foo}`', the procedure Msg.GetText will insert the textual representation of the attribute with the name ``foo`'. The special reference ``${MSG_CONTEXT}`' is replaced by the value of context.id, and ``${MSG_CODE}`' with msg.code.

> The default implementation returns this string:

> >     MSG_CONTEXT: ${MSG_CONTEXT}
> >     MSG_CODE: ${MSG_CODE}
> >     attribute_name: ${attribute_name}

> The last line is repeated for every attribute name. The lines are separated by CharClass.eol.

> Pre-condition: msg is not NIL.

> [Description inherited from GetTemplate]

> Redefines: GetTemplate

Class Detail: Reader

Field Detail

### base

    FIELD base-: Channel

> The channel on which this reader is operating.

### byteReader

    FIELD byteReader-: Reader

> Binary reader underneath this text reader. This field should only be used by extensions of this type.

### eol

    FIELD eol-: ARRAY n OF CHAR

> Character sequence of the end of line marker. All characters have a code less than ``20X`'. The end of line marker may contain the character ``0X`', which means its length must be stored in a separate field. The eol marker cannot be empty, and it is required to contain control characters with an ASCII code in ``00X..1FX`'.

### eolLen

    FIELD eolLen-: INTEGER

> Number of characters in eol. ``-1`' means auto detect, which is the default.

### opt

    FIELD opt-: SET

> Current reader options.

### res

    FIELD res: Msg

Constructor Detail

### ConnectReader

    PROCEDURE ConnectReader(ch: Channel): Reader

### InitReader

    PROCEDURE InitReader(r: Reader;
                         ch: Channel)

Method Detail

### Available

    PROCEDURE (r: Reader) Available(): LONGINT

### ClearError

    PROCEDURE (r: Reader) ClearError()

### Eol

    PROCEDURE (r: Reader) Eol(): BOOLEAN

> Return TRUE if the character at the current position is the system-dependent end-of-line character sequence or the last character has been read. If ``r.res # done`', then result is TRUE.

### Pos

    PROCEDURE (r: Reader) Pos(): LONGINT

### ReadBool

    PROCEDURE (r: Reader) ReadBool(VAR bool: BOOLEAN)

> Pre-condition: ``input=[whitespace] ["TRUE"|"FALSE"]`'

> Post-condition: ``bool=TRUE`' iff input equals ``TRUE`' and ``bool=FALSE`' iff input equals ``FALSE`'. Result is undefined otherwise.

### ReadChar

    PROCEDURE (r: Reader) ReadChar(VAR ch: CHAR)

> Read a character. Note: No new characters will be read if an error has occurred.

### ReadHex

    PROCEDURE (r: Reader) ReadHex(VAR lint: LONGINT)

### ReadIdentifier

    PROCEDURE (r: Reader) ReadIdentifier(VAR s: ARRAY OF CHAR)

> Pre-condition: ``input = [whitespace] letter {letter | digit}`'

### ReadInt

    PROCEDURE (r: Reader) ReadInt(VAR int: INTEGER)

> As Reader.ReadLInt.

### ReadLInt

    PROCEDURE (r: Reader) ReadLInt(VAR lint: LONGINT)

> Returns the long integer constant lint at the current position according to the format: ``IntConst = [whitespace] ["+"|"-"] digit {digit}`'.

### ReadLReal

    PROCEDURE (r: Reader) ReadLReal(VAR lreal: LONGREAL)

> Returns the long real constant lreal at the current position according to the format ``LongRealConst = [whitespace] ["+" | "-"] digit {digit} ["." {digit} [exponent]]`' where ``exponent = ("E" | "D") ("+" | "-") digit {digit}`'.

> Note: Because of implementation restrictions, a real representation with more than 1023 characters causes an invalidFormat error.

### ReadLine

    PROCEDURE (r: Reader) ReadLine(VAR s: ARRAY OF CHAR)

> Reads characters until an end of line character is encountered, or the array s is full. Caution: If reading multiple lines of input and an integer, real, etc. has just been read, the channel may be positioned at a eol character and this method will return an empty string.

### ReadLn

    PROCEDURE (r: Reader) ReadLn()

### ReadReal

    PROCEDURE (r: Reader) ReadReal(VAR real: REAL)

> As Reader.ReadLReal.

### ReadSInt

    PROCEDURE (r: Reader) ReadSInt(VAR sint: SHORTINT)

> As Reader.ReadLInt.

### ReadSet

    PROCEDURE (r: Reader) ReadSet(VAR s: SET)

> Read a set described in Oberon-2 set notation into s.

### ReadString

    PROCEDURE (r: Reader) ReadString(VAR s: ARRAY OF CHAR)

> Reads an Oberon-2 string literal. Illegal chars terminate with invalidFormat.

> Pre-condition: ``input = [whitespace] '"' {char} '"' | [whitespace] "'" {char} "'"`'.

### SetEol

    PROCEDURE (r: Reader) SetEol(marker: ARRAY OF CHAR;
                     markerLen: INTEGER)

> Sets new end of line marker. If the passed string marker does not fit into the field r.eol, or it does contain a character greater or equal to space (``` '), then r.res is set to invalidFormat.

> A marker length ``markerLen=-1`' enables auto detection of the end-of-line convention used by the channel. The channel is required to use one of the following eol markers:

> LF | used by Unix
> CR | used by MacOS
> CR/LF | used by MS-DOS and Windows

> Enabling auto detection introduces a (small) inconsistency: if the first line of the channel ends with a CR, then skipping over the complete eol marker of this line is not done at once iff the next character is a LF. All reading procedures except for Reader.ReadChar will automatically skip the spurious LF.

> Example: Input is ``line1CRLFline2`'. The first Reader.ReadLine leaves the reading position between CR and LF, and a second Reader.ReadLine skips automagically the LF and returns ``line2`'. But if the second operation is a Reader.ReadChar, it will return LF, not ``l`'.

> The reason for this is that Reader.ReadChar is the only operation that can look at parts of an multi-byte end-of-line marker, while such a marker is an atomic entity for all other read operations if the channel is read sequentially.

> Pre-condition: (r.Res() = done) & ((markerLen = -1) OR (1 <= markerLen < LEN (marker))) & (markerLen <= maxLengthEol) & (for all i: marker[i] < 20X)

### SetOpts

    PROCEDURE (r: Reader) SetOpts(opts: SET)

> Set the reader options r.opt.

### SetPos

    PROCEDURE (r: Reader) SetPos(newPos: LONGINT)

Class Detail: Scanner

Field Detail

### base

    FIELD base-: Channel

### bool

    FIELD bool-: BOOLEAN

> Boolean from channel.

### char

    FIELD char-: CHAR

> Char from channel.

### int

    FIELD int-: LONGINT

> Integer from channel.

### lines

    FIELD lines-: LONGINT

> Total of scanned eol markers. Counting starts at zero.

### opt

    FIELD opt-: SET

> Current scanner options.

### pos

    FIELD pos-: LONGINT

> Position of current token in the channel.

### r

    FIELD r-: Reader

> Text reader underneath this scanner. This field should only be used by extensions of this type.

### real

    FIELD real-: LONGREAL

> Real from channel.

### res

    FIELD res: Msg

### set

    FIELD set-: SET

> Set from channel.

### string

    FIELD string-: String

> String from channel.

### type

    FIELD type-: INTEGER

> Type of the most recently scanned token. One of char, string, int, real, bool, set, tab, line, ident, error, or invalid. Please note that depending on the scanner options, some input data is reported under different types.

Constructor Detail

### ConnectScanner

    PROCEDURE ConnectScanner(ch: Channel): Scanner

### InitScanner

    PROCEDURE InitScanner(s: Scanner;
                          ch: Channel)

Method Detail

### Available

    PROCEDURE (s: Scanner) Available(): LONGINT

### ClearError

    PROCEDURE (s: Scanner) ClearError()

### Pos

    PROCEDURE (s: Scanner) Pos(): LONGINT

> Return position of the look-ahead character.

### Scan

    PROCEDURE (s: Scanner) Scan()

### SetEol

    PROCEDURE (s: Scanner) SetEol(marker: ARRAY OF CHAR;
                     markerLen: INTEGER)

### SetOpts

    PROCEDURE (s: Scanner) SetOpts(opts: SET)

### SetPos

    PROCEDURE (s: Scanner) SetPos(pos: LONGINT)

Class Detail: Writer

Field Detail

### base

    FIELD base-: Channel

> The channel on which this writer is operating.

### byteWriter

    FIELD byteWriter-: Writer

> Binary writer underneath this text writer. This field should only be used by extensions of this type.

### opt

    FIELD opt-: SET

> Current writer options.

### res

    FIELD res: Msg

Constructor Detail

### ConnectWriter

    PROCEDURE ConnectWriter(ch: Channel): Writer

### InitWriter

    PROCEDURE InitWriter(w: Writer;
                         ch: Channel)

Method Detail

### ClearError

    PROCEDURE (w: Writer) ClearError()

### Pos

    PROCEDURE (w: Writer) Pos(): LONGINT

### SetEol

    PROCEDURE (w: Writer) SetEol(marker: ARRAY OF CHAR;
                     markerLen: INTEGER)

> Sets new end of line marker. If the passed string marker does not fit into the writer's field ``w.eol`', then w.res is set to invalidFormat. The empty marker is permitted. The default value for newly created writer is CharClass.systemEol.

> Pre-condition: (w.res = done) & (0 <= markerLen < LEN (marker)) & (markerLen <= maxLengthEol)

### SetOpts

    PROCEDURE (w: Writer) SetOpts(opts: SET)

> Set the writer options w.opt.

### SetPos

    PROCEDURE (w: Writer) SetPos(newPos: LONGINT)

### WriteBool

    PROCEDURE (w: Writer) WriteBool(bool: BOOLEAN)

### WriteChar

    PROCEDURE (w: Writer) WriteChar(ch: CHAR)

### WriteHex

    PROCEDURE (w: Writer) WriteHex(lint: LONGINT;
                       d: LONGINT)

### WriteInt

    PROCEDURE (w: Writer) WriteInt(int: INTEGER;
                       n: LONGINT)

### WriteLInt

    PROCEDURE (w: Writer) WriteLInt(lint: LONGINT;
                        n: LONGINT)

### WriteLReal

    PROCEDURE (w: Writer) WriteLReal(lreal: LONGREAL;
                         n: LONGINT;
                         k: LONGINT)

> Writes the value lreal in the format produced by LRealStr.RealToFloat.

### WriteLRealEng

    PROCEDURE (w: Writer) WriteLRealEng(VAR lreal: LONGREAL;
                            n: LONGINT;
                            k: LONGINT)

> Writes the value lreal in the format produced by LRealStr.RealToEng.

### WriteLRealFix

    PROCEDURE (w: Writer) WriteLRealFix(VAR lreal: LONGREAL;
                            n: LONGINT;
                            k: LONGINT)

> Writes the value lreal in the format produced by LRealStr.RealToFixed.

### WriteLn

    PROCEDURE (w: Writer) WriteLn()

> Write a newline.

### WriteObject

    PROCEDURE (w: Writer) WriteObject(obj: Object)

### WriteReal

    PROCEDURE (w: Writer) WriteReal(real: REAL;
                        n: LONGINT;
                        k: LONGINT)

> As Writer.WriteLReal.

### WriteRealEng

    PROCEDURE (w: Writer) WriteRealEng(real: REAL;
                           n: LONGINT;
                           k: LONGINT)

> As Writer.WriteLRealEng.

### WriteRealFix

    PROCEDURE (w: Writer) WriteRealFix(real: REAL;
                           n: LONGINT;
                           k: LONGINT)

> As Writer.WriteLRealFix.

### WriteSInt

    PROCEDURE (w: Writer) WriteSInt(sint: SHORTINT;
                        n: LONGINT)

### WriteSet

    PROCEDURE (w: Writer) WriteSet(s: SET)

> Write s in Oberon-2 set notation.

### WriteString

    PROCEDURE (w: Writer) WriteString(s: ARRAY OF CHAR)

Type Detail

### String

    TYPE String = ARRAY n OF CHAR

Constant Detail

### bool

    CONST bool

### char

    CONST char

### defReaderOptions

    CONST defReaderOptions

> Default reader options.

### defScannerOptions

    CONST defScannerOptions

> Default scanner options: interpret boolean, set, and string values, and signed integer values.

### defWriterOptions

    CONST defWriterOptions

> Default writer options.

### done

    CONST done

### error

    CONST error

### ident

    CONST ident

### int

    CONST int

### interpretBools

    CONST interpretBools

> When set the Scanner returns truth values of the strings TRUE and FALSE. Otherwise it returns them as strings.

### interpretSets

    CONST interpretSets

> When set the Scanner returns a set value of the string set representation. Otherwise it returns the brace, comma, and numbers individually.

### interpretStrings

    CONST interpretStrings

> When set the Scanner returns a complete string contained within open and closing quotes. Otherwise it returns the quote characters and string contents as separate tokens.

### invalid

    CONST invalid

### invalidFormat

    CONST invalidFormat

### line

    CONST line

### maxLengthEol

    CONST maxLengthEol

> Maximum length of an end of line character sequence. This value is system dependent, and always larger or equal to 2.

### noBuffering

    CONST noBuffering

> When set output is not buffered. This allows interactive output prompts to appear as soon as they are written.

### real

    CONST real

### returnCtrlChars

    CONST returnCtrlChars

> When set the Reader or Scanner returns EOL & TAB characters. Otherwise they are treated like whitespace.

### set

    CONST set

### string

    CONST string

### tab

    CONST tab

### undefined

    CONST undefined

### useSignedNumbers

    CONST useSignedNumbers

> When set the Scanner returns a complete signed number. Otherwise it returns the sign characters and the number tokens separately.

### valueOutOfRange

    CONST valueOutOfRange