RPL - Perl module for parsing and executing RPL programs, providing stack and variables
management routines, as well as a library of built-in primitives for flow control, list
manipulation and basic calculus.
This package provides all the basic routines to make the Perl interpreter understand
RPL programs. The parser transforms string-programs into list-programs (see the 'Syntax
and Types' entry below). The interpreter executes a list-program, modifying the stack
and namespace contexts provided (see the 'Data structures' entry later on).
RPL::Parse takes as unique argument the string representing the RPL code.
It returns a reference to an array containing the parsed program, and the - eventually -
remaining unparsed code. On error, it returns the null string, and the tail of the code
string, cut where the error was detected.
Error testing is thus just a matter of doing a < ref() eq 'ARRAY' > on the first returned
value.
RPL::Execute takes an array reference to the code to execute, a stack context and a
variable context, modified during the execution. If the execution runs without error,
(0,"") is returned. When an error occurs, the execution is aborted, an error code and an
error message are returned.
The string representation of a RPL program is a pair of square brackets "[ ]", containing
a number of:
barewords:
e.g. < HELP >, a builtin command name, or a number
strings:
e.g. < "HELLO" >, a litteral string
sublists:
e.g. < [ PRINT ] >, a list
During execution, a bareword is looked-up in the set of Built-in, then User commands,
and then dumped on the stack if it was found in none of these. This last behaviour is the
case for numbers and named constants, for which no entry exists in these commad sets, but
are known to Perl. A string is simply dumped on the stack, as is a sublist. However, a
sublist can be executed as a RPL program later, using flow-control command, or the EXEC
builtin.
When found on the stack, barewords are simple scalars, strings are refs to a scalar, and
sublists are refs to arrays.
A stack context is a reference to an array, representing a stack, top of stack at the
beginning. Many stack operations are implemented, see the Code for details...
A variable context is a reference to a hash, each entry associates a variable name and its
content. Built-ins are provided for creating/updating a variable (STOV), listing all
variables (VARS), testing is a variable exists (EXSV), and destroying a variable (DELV).
Providing a true syntax error detection and report, not just a 'well, I stopped there'.
Adding a way to trap error.
Adding a fully described list of buil-ins in this man.