RPL(n)  Perl Module

NAME
	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.

SYNOPSIS

	use RPL ;

	my($code,$myprogstr) ;
	$myprogstr = "[ 1 1 + PRINT ]" ;
	($code,$myprogstr) = Parse($myprogstr) ;

	my $stack = [] ;
	my $vars = {} ;
	my($errnum,$errmesg) ;
	($errnum,$errmesg) = Execute($code,$stack,$vars) ;

DESCRIPTION

	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).

Parsing

	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.

Executing

	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.

Syntax and Types

	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.

Data structures

	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).
	


AUTHOR

	Yann Landrin-Schweitzer <yann.landrin-schweitzer@inria.fr>

	Dev questions/suggestions and bug reports should be sent to <varkhancd@multimania.com>

BUGS

	Innumerable. For the others, you tell me...

TODO

	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.

SEE ALSO

	HPemu: a terminal-based emulator of the HP48S/G calculator interface, written
		using the RPL module. Actually, 10-odd lines of code as a wrapper...