RPN Script and VAR : introduction to String Source

RPN-Enh Programation

You can perform some programation with RPNE, it's called "scripts".
Please note that RPNenh propose you a program object in a user friendly interface, this page does not deals with program, it explain the String source scripts. scripts are strings and are stored into files (in windows).
All scripts are available in VAR menu.

Scripts files

Each scripts are stored into "script_xxxx" file in the same folder as RPNE, (xxxx is the name of the script).
These file are ASCII plain text and can be edited with any text editor.

Syntax

Script syntax is specific, we have to consider two differents things : how data are stored and what are the keywords.

Data : number can be stored directly, but other type needs to be translated (serialized)
Keywords : All RPNE functions are supported, and I've added some structure keywords like FOR and IF

Function related to scripts and VARs

Storing an object to a variable

STO store an object into a variable. the variable name is a string.

exemple.

123
"aaa"
STO

please note : that a file script_aaa is created and contains now 123

You can store any kind of object into a variable.

Restoring an object from a variable

Go into your VAR menu and hit `aaa` the content of aaa is restored onto the stack
You can also use `Exec` which do the same	"aaa" `Exec` gives 123	Please note that `Exec` is not the same as `RCL`, see further for details

Serialization

You have to understand that RPNE handle data internaly as best as possible to provide you serveral type of object (complex, matrix, hexa, poly...) but when you need to save it into your hard drive you cannot just write a matrix as you display it...
Data are transformed to be easyly readable. This transformation is called "serialization".
So I created a serialisation mechanism to write and read any kind of data from/to a file (even list of matrix of mixed complex and string...)

These functions are low level functions and are also internaly used into STO, Exec and other functions...

`Serialize`	transform an objet (any type) into a string. internaly used to write data into a file.	example : `[ 1 2 ]`is serialized as `"\7 2 \1 1 \1 2` `"hi!"` is serialized as `\4 3 3 $hi!` `{ 1 2 "hi" }` is serialized as `\6 3 \1 1 \1 2 \4 2 2 $hi`
`unSerialize`	perform the reversal, read a string and create the corresponding objet. internaly used to read variable from VAR	`"\6 2 555 444` gives `{ 555 444 }` 6 is the type for list. 2 is the number of item. there are cariage returns between each items

As you see serialized objets look very strange.
but in fact this syntax allow some relax, for number and string you can use classic notation.
for example :

instead of...	...you can write
\1 123	123
\4 2 2 $hi	"hi"

See here about how serialized objects are made : in fact that not so hard, it's just based on object type (type and how many object it contains).

For example, instead of \6 3 \1 1 \1 2 \4 2 2 $hi, you can just write \6 3 1 2 "hi" which means (object type 6 : list of 3 items : 1, 2 and "hi")

Serialization extensions

I've extend the concept of serialization, as it was just used to read variable, It can now perform RPN operation.
And finally, it can execute scripts.

String Source

A String Source Script is a serialised object.

How to execute a Script

you can execute a script by hiting the corresponding key in VAR (if you have stored it into a variable, see STO)
you can execute directly it from the stack, by the function unSerialize. in case you did not store it into a variable.

How to obtain/create a script

You can manually type it into a text editor, and save your file as "script_abc"
You can use the QLE notation, which allow you to type simple script directly from RPNE

Quick List Entry method (QLE)

This is an alternative solution. see here for an example
This is a quick way to create small scripts easily.
The idea is to type your program in a list. for example, make the list { 1 + } and to use list->script to create the serialised script "1 /! +". (note in hp this corresponds to << 1 + >>)
Example : I want to make a script that read a number from the stack and compute the sum sqr number from 1 to this number :

in hp style	in QLE	QLE converted with `List->script`
<< 0 SWAP 1 SWAP FOR i i SQR + NEXT >>	{ 0 swap 1 SWAP for index sqr + next } you can see how similar to hp is it...	0 \! SWAP 1 \! SWAP \@ FOR \@ INDEX \! Sqr \! + \@ NEXT

That mean you can type program in almost a near way you used to do in hp calculator, you just need to convert it into script with List->script

What to do now ?

You can execute the script by using unSerialize (Exec works only in stored variable). Please don't forget to place a number in the stack before...

As script are stings, if you use "STO", you will store the string (it will serialize your script), see below...

Storing program scripts

You have now your script (a string), how to store it into VAR menu (file) for later usage ?

You cannot use STO, as script are string (you can use STO for program because program are not string).
If you use STO, you script will be stored as string.. and when you will hit his name in VAR, nothing will be executed, you will get this string on the stack, that's all !
you must use STOScript function, this function does not perform any serialization, in this way it will be executed.

As a workaround, you can also copy and past directly the contents into the file.

Operation on scripts

As comparaison with hp calcs, here are all possible operations for programs

I want to...	on a hp	on RPNE
I want to run a stored program. (the name is "hi")	go to VAR, hit `hi`	go to VAR, hit `hi`
I want to run a stored program. (the name is "hi") without going into VAR	`'hi'` `EVAL`	`"hi"` `Exec`
I want to get the content of the program into the stack	`'hi'` `RCL`	`"hi"` `RCL`
I want to execute a program from the stack	`EVAL`	`unSerialize` (for script) `run`(for program)

IMPORTANT, please note that in RPNE, there are no ALG type, you have to use string for name ("hi" instead of 'hi')

Script related Keyword

Here is a reminder of Script related Keywords

`STO`	Serialize an object and store it into a variable (file)
`Exec`	Restore and unSerialize the VAR. (this is used to read a file and to execute a script)
`RCL`	Restore without unSerialize, finaly it's just like a `FileRead`, only usefull on scripts
`List->script`	convert a list into a script (a string)
`Serialize`	this operation convert any objet into a string. this is a low level operation.
`unSerialize`	this operation convert back string into object. this also compute scripts.

RCL and Exec is not the same !

If you want to go deeper in scripting, see now to understand the syntax of Scripts

---UNDER CONSTRUCTION ---
Last change : 27th of october 2003.