PARSING
Function
Parsing contains procedures for reading formatted input files.
This module is used by the DYNAMO library in most of the cases where a formatted input file is read.
Dependencies
Module | Variables |
DEFINITIONS | DP, LINE_LENGTH, MAX_UNITS |
IO_UNITS | OUTPUT |
STATUS | ERROR |
STRING | DECODE_INTEGER, DECODE_LOGICAL, DECODE_REAL, TO_UPPER_CASE |
Public Variables
There are two public variables in this module.
Variable | Type | Purpose |
WRDLEN | Integer | The length of the currently parsed word. |
WORD | Character ( Len = LINE_LENGTH ) | The currently parsed word. |
- Whenever a line from an input file is parsed by the procedures in the module, the currently parsed word is stored
in the variable WORD and its length in WRDLEN.
Public Procedures
There are a single public function and seven public subroutines in this module.
Function | Type | Purpose |
EMPTY | Logical | Check to see whether the current input line has been fully parsed. |
Subroutine | Purpose |
GET_INTEGER | Interpret the next word on the input line as an integer. |
GET_LINE | Read in the next line from the input file and process it. |
GET_REAL | Interpret the next word on the input line as a real number. |
GET_WORD | Put the next word on the input line into WORD. |
PARSE_ERROR | Handle an error during the parsing of an input line. |
POP_UNIT | Remove a stream from the top of the input stream stack. |
PUSH_UNIT | Add a new stream number to top of the input stream stack. |
EMPTY
This function has no arguments.
- The function result is .FALSE. if there are no more words on the current command line that remain to be
parsed.
GET_INTEGER
Argument | Type | Intent | Optional | Purpose |
NUMBER | Integer | Out | No | The integer to be returned by parsing the next word
on the current input line. |
- GET_INTEGER gets the next word on the current input line using GET_WORD, and then tries to interpret it as
an integer using the function DECODE_INTEGER from the module STRING.
- If there is no word left on the input line a value of zero is returned.
GET_LINE
Argument | Type | Intent | Optional | Purpose |
END_OF_FILE | Logical | Out | Yes | A flag to indicate whether the end of the current
input file has been reached. |
Error | Meaning |
I/O Error. | There has been an error reading the next line from the current input file. |
End of file reached. | There are no more lines in the current input file and the END_OF_FILE argument
was not specified. |
- GET_LINE is the key subroutine in the module. It reads the next input line from the current input stream,
removes any comments and then splits the remainder of the line into words.
- New lines in an input file are denoted by a carriage return or by a semicolon.
- Words on an input line are delimited by blanks, commas, equals signs or by tabs.
- Strings of characters enclosed by pairs of double quotes `"' count as a single word even if they contain
blanks, etc.
- Any characters after an exclamation mark are treated by comments unless the exclamation mark is part of a
string (i.e. enclosed by double quotes).
- All characters outside of strings are converted to upper case.
- GET_LINE will continue reading lines from a file until a non-empty line is found.
- GET_LINE will generate an error if there remain unparsed words from the previous line that was read.
GET_REAL
Argument | Type | Intent | Optional | Purpose |
NUMBER | Real | Out | No | The real number to be returned by parsing the next word
on the current input line. |
- GET_REAL gets the next word on the current input line using GET_WORD, and then tries to interpret it as
a real number using the function DECODE_REAL from the module STRING.
- If there is no word left on the input line a value of zero is returned.
GET_WORD
There are no arguments for this subroutine.
- GET_WORD puts the next unprocessed word of the current input line and its length into the module variables WORD
WRDLEN.
- WRDLEN is set to zero if there is no word left on the input line.
PARSE_ERROR
Argument | Type | Intent | Optional | Purpose |
ROUTINE | Character | In | No | The name of the procedure from which PARSE_ERROR
is called. |
MESSAGE | Character | In | No | The error message to be printed. |
- PARSE_ERROR acts in exactly the same way as the subroutine ERROR from the module STATUS except that it prints
out the current input line first.
POP_UNIT
There are no arguments for this subroutine.
- POP_UNIT removes the currently active input stream from the input stream stack so that all information about the
parsing of the file connected to this stream is forgotten. Parsing will then revert to the previous file in the
stream stack if one exists or will be disabled otherwise.
- An error will occur if the words on the last input line of the stream being removed have not all been parsed.
- A call to POP_UNIT should always be accompanied by a previous call to PUSH_UNIT.
PUSH_UNIT
Argument | Type | Intent | Optional | Purpose |
STREAM | Integer | In | No | The stream number to be added to the top of stack. |
- PUSH_UNIT adds a new stream number to the top of the input stream stack and so makes the associated file
accessible for reading by the subroutine GET_LINE.
- PUSH_UNIT must be called at least once before the first call to GET_LINE because initially the stream stack
has no streams active.
- There should never be any overflow of the input stream stack as it can hold MAX_UNITS files which is the
maximum recognized by the module library (and, in particular, the function NEXT_UNIT from the module FILES).
- A call to PUSH_UNIT should always be followed by a call to POP_UNIT when processing of the current input file
has finished.
Stability
Stable.