Introducing: parse library

[samiam95124]

Introducing: parse library

The parse library, used by pc, is a general purpose parsing engine meant for spaced parameter files and lines. This means it is oriented towards command line oriented strings and files of the form:

command parameter, parameter, ...

ie, just like a command shell like bash or similar does. The idea is that each program running in a CLI environment must usually process its own command line, but may also parse a configuration file as well, with a series of commands in it. pc uses it to process it's command line, and also any .ins or instruction files it may encounter.

Parse is not a full language processor like yacc/lex or similar. It actually does need that capability for Pascaline files, but that is why it includes a scanner module.

Overview

Parse is just a very good general purpose parse facillity. It can use as input any file, a string, or the command file (commands to the program). It can be used as a line oriented parser, a full file oriented parser, or any combination thereof. It can stack multiple files (like an "include" type facility), as well as mark any number of positions within the line and return to those (backtrack).

The basic calls in parse are:

chkchr() - Return the next character at the current parse position.
getchr() - Advance to the next character.
skpspc() - Skip any spaces.
endlin() - Check end of line reached.

These calls are logical, so that reading past the end of line will return an infinite series of spaces.

These basic calls don't advance past the end of the current line, so there are calls that do:

getchrl() - Advance to the next character, including over multiple lines/files.
skpspcl() - Skip spaces, including over multiple lines/files.
endfil() - Check end of file reached.

These calls are also logical. Reading past the end of file will either go back to the next nested file or return an infinite series of spaces. At the end of file both the end of line and the end of file are true.

Adding inputs

openstr() - Adds a new parsing level with a given string.
openfil() - Adds a new parsing level with a given file by name.
opencommand() - Adds a new parsing level with the command file.

Using these calls, program strings, external files or the command line file can all be added, and nested to any level.

Look ahead

Parse can mark any number of positions within the current line (it cannot mark over files yet).

pushpos() - Save the current line position.
poppos() - Return the parser to the next nested position.
dmppos() - Dispose of the last level of position but stay at the current position.

Parse objects

Parse can parse a number of objects in the parse stream.

chklab() - Check the next item to parse is a label start, that is, in '_', 'a'-'z'.
parlab() - Parse and return a label.
chknum() - Check the next item to parse is a number, including hex, octal and binary.
parnum() - Parse number.
chkstr() - Check the next item to parse is a string.
parstr() - Parse string.
parwrd() - Parse space delimited word.

Error processing

prterr() - Prints an error string with diagnostics about the file or string in active parse, with line and character numbers.

Tracing

trclin() - Enables tracing of each line read.