View source for An arbitrary-precision calculator

= PAL Tutorial - An arbitrary-precision calculator =

In release 0.7.x, only the PROSE Assembly Language (PAL) is available, and then only a subset of those instructions. So be aware, it's very low-level programming at this time. To learn more about the PROSE Programming Language, visit http://prose.sourceforge.net.

It is suggested you begin with the following articles before attempting this tutorial.

:* [[Main Page|Introduction to PROSE]]
:* [[Quick start guide]]
:* [[Running your first program]]
:* [[Short tour of PAL]]

A full list of available tutorials for the PROSE Assembly Language can be found on the [[PAL tutorials|tutorials index page]].

This tutorial works through an example PAL program that implements a simple arbitrary-precision calculator.

== Objectives ==

The objective is to write a PAL program that will allow for simple two-operand calculations on integers, floating-point numbers and rational numbers.  This will demonstrate the use of variables and functions as well as basic integration with the [http://gmplib.org GNU MP] (Multi-Precision) library.  Note that this is based on GMP 4.3.2.

The program will understand the following commands supplied on the standard input:

<pre>
    M+N             adds two numbers M and N and displays the result
    M*N             multiplies two numbers M and N and displays the result
    M-N             subtracts two numbers M and N and displays the result
    M/N             divides two numbers M and N and displays the result
    M~N             divides two numbers M and N and displays the result
                        (when the number type is rational)
    int             set number type to integer
    flt             set number type to floating-point
    rat             set number type to rational
    help            displays this help page
    debug           toggles debug mode ON and OFF
    quit            exits this program
</pre>

Integers, floating-point numbers and rational numbers will all take the form accepted by the GNU MP library.  Floating-point numbers at this time have a default precision set to at least 64 bits.  Rational numbers are represented by <code>X/Y</code> where <code>/</code> separates the numerator from the denominator.  Because of this, the <code>~</code> symbol will be used by the program for requesting a division operation with rational numbers.

== Step 1 - Displaying a title ==

The first step is to display a title when the program is launched.  This should be straightforward if you have followed previous tutorials:

<pre>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Simple arbitrary-precision calculator
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
._init
func/def	[main],     &[.main]
func/def	[title],    &[.func_title]
local/rtn

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% main()
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.main
func/call	NULL, [title]
func/rtn

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% title()
%
% Display title of program to stderr
%
% Arguments:
%	None
%
% Returns:
%	None
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.func_title
attr/mod	![.prose.sys.io], [psStreamError], [
pscalc: a simple arbitrary-precision calculator
Type 'help' for a list of commands or 'quit' to exit
]
func/rtn
</pre>

== Step 2 - Accepting basic commands ==

The <code>help</code> and <code>quit</code> commands should be easy to implement.  We need a function which we'll call <code>getcmd()</code> that reads the next command from standard input and strips the trailing newline character.  This demonstrates returning a value from a function, and introduces us to the concept of the encoded attribute value (or <code>XVALUE</code>).  Here is the function code:

<pre>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% getcmd()
%
% Gets next command from stdin (stripping newline character)
%
% Arguments:
%	None
%
% Returns:
%	String, or empty string if input is exhausted
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.func_getcmd
reg/load	P15, ![.prose.sys.io]

% Display command prompt to stderr
attr/mod	P15, [psStreamError], [> ]

% Collect input
attr/copy	P0, P15, [psStreamIn]
reg/jmpeq	&[.getcmd_null], P0, NULL

% Strip trailing newline character
reg/load	A, (P0)
op/decr
error/jmp	&[.no_strip], ![.prose.error.sys.OutOfRange]
reg/load	P2, (P0, A)
op/shr		P2, P2, #24
reg/jmpneq	&[.no_strip], P2, #10
reg/save	P0, (A)
func/rtn	P0

.no_strip
error/clr
func/rtn	P0

.getcmd_null
func/rtn	[]
</pre>

The only difference in the above code from previous tutorials is that a string is being passed to the <code>func/rtn</code> instruction.  This necessitates an additional argument to the corresponding <code>func/def</code> instruction which we insert into the <code>._init</code> section.  We'll re-write that section now to pre-load some attribute definitions into registers <code>P0</code> and <code>P1</code>:

<pre>
._init
attr/load	P0, [psString], P1, [psIndex]

%
% Function definitions
%
func/def	[main],     &[.main]
func/def	[title],    &[.func_title]
func/def	[getcmd],   &[.func_getcmd],	P0
local/rtn
</pre>

Here the <code>psString</code> attribute is being passed to the 3rd argument of <code>func/def</code>.  This identifies the type of data that the function will return.  If omitted, or <code>NULL</code>, then the function cannot return a value.  Function return values can only be a variable type, i.e. a type that can be assigned to a program variable.  We discuss variable types later on in this tutorial.

When the <code>getcmd()</code> function is called, it will return the next line from standard input.  All functions that return values will return them as ''encoded attribute values''.  This is data that is encoded for a specific attribute type, in this case <code>psString</code>.  It will be saved into a register as the type <code>PSUNIT_TYPE_XVALUE</code>.  When the <code>func/rtn</code> instruction is used with a value, that value can be provided in the correct encoding (in which case it is simply returned as-is), or if not it will be re-encoded automatically by the PROSE engine before the return completes.  This re-encoding will usually take place via a byte string representation, because all variable types can be represented in byte string format.

This concept is worth demonstrating.  Before continuing, try calling the <code>getcmd()</code> function and dumping the result, e.g. after a call to <code>title()</code> but before the <code>main()</code> function returns:

<pre>
func/call	P0, [getcmd]
reg/dump	P0
obj/dump	P0
</pre>

Notice the first argument to <code>func/call</code>.  In previous tutorials this has been <code>NULL</code>.  By providing a register you are specifying where the return value should be stored.  Executing our program at this stage and typing the <code>quit</code> command should produce the following output:

<pre>
pscalc: a simple arbitrary-precision calculator
Type 'help' for a list of commands or 'quit' to exit
&gt; quit
register: P0
type: PSUNIT_TYPE_XVALUE (0x15)
psString

quit
</pre>

The <code>reg/dump</code> instruction informs us that register <code>P0</code> contains an encoded attribute value.  The value is encoded according to the <code>psString</code> syntax.  Essentially this is a value detached from an object attribute, but which could be attached at a later time.  The value reported by <code>obj/dump</code> is <code>'quit'</code> as expected, because this is the command you typed.

Remove the three lines added above and let's add proper support for the <code>help</code> and <code>quit</code> commands.

We'll use a data segment to map commands to an appropriate code label that can handle the command.  This data segment can appear anywhere in the code, but we can put it ahead of the <code>.main</code> section:

<pre>
%
% Mapping of code labels to commands
%
~cmdlist
EQUP { &[.quit] }; EQUS { [] }
EQUP { &[.quit] }; EQUS { [quit] }
EQUP { &[.help] }; EQUS { [help] }
</pre>

We want empty input or the <code>quit</code> command to be routed to the <code>.quit</code> label, while the <code>help</code> command should be routed to the <code>.help</code> label.  This requires a loop in the <code>main()</code> function after the title has been displayed:

<pre>
.main
func/call	NULL, [title]

.loop
%
% Fetch command from stdin
%
func/call	P0, [getcmd]

%
% Test for one of the known commands
%
reg/load	P1, ( &[~cmdlist] )

.cmdloop
reg/load	P2, (P1)
reg/jmpeq	&[.cmdloop_end], P2, NULL
reg/load	P3, (P1)
reg/jmpneq	&[.cmdloop], P0, P3
reg/clr		P1
local/jmp	P2

.cmdloop_end
% No known command, just ignore and loop for now ...
reg/clr		P0, P1
local/jmp	&[.loop]
</pre>

This uses the <code>reg/load</code> instruction in one of its indirect addressing modes, in order to iterate the values within a data segment.  This is described in the <code>reg_load_segment(5)</code> man page.

The <code>.quit</code> and <code>.help</code> sections can follow immediately on:

<pre>
.quit
% Exit program
reg/clr		P0
func/rtn

.help
% Display help message
reg/clr		P0
attr/mod	![.prose.sys.io], [psStreamError], [
M+N		adds two numbers M and N and displays the result
M*N		multiplies two numbers M and N and displays the result
M-N		subtracts two numbers M and N and displays the result
M/N		divides two numbers M and N and displays the result
M~N		divides two numbers M and N and displays the result
			(when the number type is rational)
int		set number type to integer
flt		set number type to floating-point
rat		set number type to rational
help		displays this help page
debug		toggles debug mode ON and OFF
quit		exits this program
]
local/jmp	&[.loop]
</pre>

Notice we're choosing to display informational messages to <code>psStreamError</code> (the standard error stream).  This is to keep the standard output clear for the mathematical results so that commands can be piped into the program and results extracted easily by an external command.

== Step 3 - Switching number types ==

This calculator will support integers, floating-points and rationals.  These are specified by the attribute types <code>psInteger</code>, <code>psFloat</code> and <code>psRational</code>.  The calculator will accept the commands <code>int</code>, <code>flt</code> and <code>rat</code> to switch between these types.  We'll use a global variable to store the current number type.

Program variables in PAL are objects in the nexus, and as any other object in the nexus they are defined using classes and attributes.  Typically a variable has the <code>psVariable</code> class as well as one other variable-type class, and a variable-type attribute containing the value.  The variable-type classes and variable-type attributes are named identically and are listed in the <code>ps_attributes(5)</code> and <code>ps_classes(5)</code> man pages.  Those which we will be using are:

:* <code>psFloat</code> - GMP floating-point number
:* <code>psIndex</code> - raw index (32-bit unsigned integer)
:* <code>psInteger</code> - GMP integer
:* <code>psRational</code> - GMP rational number
:* <code>psString</code> - string data

Ordinary object create commands could be used for creating program variables, e.g. <code>obj/def</code>, <code>class/add</code>, <code>attr/add</code> and <code>obj/commit</code>.  However, for convenience, the PAL instruction set comes with some short-cut instructions for creating variables:

:* <code>var/local</code> - create a local variable
:* <code>var/static</code> - create a static variable
:* <code>var/global</code> - create a global variable
:* <code>var/def</code> - create a variable in an arbitrary location

These will assign the correct classes and attributes to the object and commit it to the nexus.  The only difference between the above instructions is the location in which the variable object is created.  A ''local'' variable will be created underneath the instance container of the running function, and therefore each function instance will have its own value.  A ''static'' variable will be created directly underneath the running function object, and as a result each function instance will share the same value.  A ''global'' variable will be created underneath the module root, and therefore has module-level scope.  This is described fully in the <code>var/def(5)</code> man page.

To create the <code>numtype</code> global variable, add the following instruction after the title has been displayed but before entering the main loop:

<pre>
var/global	NULL, [psString], [numtype], [psInteger]
</pre>

This creates a variable at the module level called <code>numtype</code> that will contain a <code>psString</code> value (i.e. a byte string).  The initial value contains the text <code>'psInteger'</code> because we want this variable to define the current number type to use in calculations.  It will default to integers.  The first argument is <code>NULL</code> meaning that we don't need a pointer to the new variable object at this time.  We can use the <code>var/addr</code> instruction later on to obtain it.

If you are interested in seeing the structure of the new variable object, rather than discarding the pointer with a <code>NULL</code> keyword, store it in a register and then use <code>obj/dump</code> on it.  The register contains a pointer to a node (<code>PSUNIT_TYPE_NODE</code>) and therefore <code>obj/dump</code> will display the classes and attributes assigned to that node.  For example:

<pre>
var/global	PUSH, [psString], [numtype], [psInteger]
obj/dump	PULL
</pre>

would display the following output when the program is run:

<pre>
pscalc: a simple arbitrary-precision calculator
Type 'help' for a list of commands or 'quit' to exit
.prose.code.default.numtype:objectClass=psVariable
.prose.code.default.numtype:objectClass=psContainer
.prose.code.default.numtype:objectClass=top
.prose.code.default.numtype:objectClass=psString
.prose.code.default.numtype:pn=[numtype]
.prose.code.default.numtype:psString=[psInteger]
&gt;
</pre>

This tells you that it's a variable (<code>psVariable</code>) that it's a string (<code>psString</code>) and the value of the string (<code>'psInteger'</code>).

We will write a function called <code>settype()</code> that takes the name of the attribute type to set as a string (one of <code>psInteger</code>, <code>psFloat</code> or <code>psRational</code>) and which will set the global <code>numtype</code> variable and report the new number type to the standard error stream.  It will require a definition in the <code>._init</code> section like this:

<pre>
func/def	[settype],  &[.func_settype],	NULL, P0, [type]
</pre>

The 3rd argument is <code>NULL</code> as this function will not return a value.  The 4th and 5th arguments define the first parameter accepted by the function, by type and name.  The 4th argument is the register <code>P0</code> which we set earlier to contain the <code>psString</code> attribute definition and specifies that the parameter is a string type, and the 5th argument is <code>type</code> meaning that when the function is invoked the value passed into this parameter position will be assigned a local variable with this name.

Now comes the function itself, which can be appended to the end of the program code:

<pre>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% settype()
%
% Sets global number type
%
% Arguments:
%	type = name of attribute type to set: psInteger, psFloat or psRational
%
% Returns:
%	None
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.func_settype
var/addr	P0, [type]
attr/copy	P0, P0, [psString]
reg/copy	P2, P0
var/addr	P1, [numtype]
attr/mod	P1, [psString], P0
reg/copy	P2, [Number type: ], P2, [\n]
attr/mod	![.prose.sys.io], [psStreamError], P2
func/rtn
</pre>

Because the function definition identified one formal parameter (a string variable called <code>'type'</code>) then when the function is called a single argument will be expected.  That argument will be re-encoded to a string type (if required) and a local variable called <code>type</code> will be automatically created underneath the instance container, in exactly the same way as if the <code>var/local</code> instruction had been used.

The <code>var/addr</code> instruction works in a similar way to <code>func/addr</code> in that it uses a search path algorithm to identify the named variable.  In the above example, <code>var/addr P0, [type]</code> will look for a variable object called <code>type</code> and store a pointer to that node in the <code>P0</code> register.  First a local variable will be tested for with that name, then a static variable and finally a global variable.  If a variable of that name cannot be found, a runtime error will be generated.

Then we use the <code>attr/copy</code> instruction to get a copy of the <code>psString</code> attribute value assigned to the variable object.  This will yield a <code>PSUNIT_TYPE_STRING</code>.  Alternatively, we could have used <code>attr/xcopy</code> if we wanted a <code>PSUNIT_TYPE_XVALUE</code>.  Following this instruction, register <code>P0</code> holds the value of the first argument passed to the function.

If you were to insert a <code>reg/dump P0</code> after the <code>var/addr</code> and again after the <code>attr/copy</code> you would see the difference between the two instructions.  The output would look like this:

<pre>
register: P0
type: PSUNIT_TYPE_NODE (0x01)
.prose.code.default.settype._i0#0.var.type

register: P0
type: PSUNIT_TYPE_STRING (0x04)
psFloat
</pre>

Now we take the value from the local <code>type</code> variable and use it to overwrite the value in the global <code>numtype</code> variable.  Then we report the action to <code>psStreamError</code>.

Finally, to complete this step, we need to plumb in the <code>int</code>, <code>flt</code> and <code>rat</code> commands.  To do this, add the commands to the <code>cmdlist</code> data segment like this:

<pre>
EQUP { &[.int] }; EQUS { [int] }
EQUP { &[.flt] }; EQUS { [flt] }
EQUP { &[.rat] }; EQUS { [rat] }
</pre>

and add corresponding <code>.int</code>, <code>.flt</code> and <code>.rat</code> sections that each call <code>settype()</code> with the appropriate argument, this code can be inserted immediately before the <code>.quit</code> label:

<pre>
.int
% Set number type to integer
reg/clr		P0
func/call	NULL, [settype], [psInteger]
local/jmp	&[.loop]

.flt
% Set number type to floating-point
reg/clr		P0
func/call	NULL, [settype], [psFloat]
local/jmp	&[.loop]

.rat
% Set number type to rational
reg/clr		P0
func/call	NULL, [settype], [psRational]
local/jmp	&[.loop]
</pre>

You will now be able to launch the calculator and run the new commands, although they won't do much for you at this time:

<pre>
pscalc: a simple arbitrary-precision calculator
Type 'help' for a list of commands or 'quit' to exit
> int
Number type: psInteger
> flt
Number type: psFloat
> rat
Number type: psRational
> quit
</pre>

== Resources from this tutorial ==

:* [[Source code: pscalc.pal]]

== Further reading ==

See the other tutorials available for the PROSE Assembly Language on the [[PAL tutorials|tutorials index page]].

PROSE is released with detailed manual pages that describe how PAL operates, and how each instruction is used. These manual pages can be read using the <code>man</code> command, for example <code>man pal_intro</code> or <code>man pal_commands</code>, or from the [[Main Page#Project links|project links]] on the main page of this wiki.