On this page:
The Basics, Scripts and the Result File hy, Creating a Script, Running a Script, The Echo Mode, The PROMPT Command, A First Example.
A script is a collection of input lines that Hypatia reads from a file.
With a few differences, these are lines just as you would enter them directly.
There are two restrictions to scripts:
- Scripts cannot be nested -- that is, a script cannot call another script (nor can it call itself).
- Scripts cannot contain loop commands (DO or REPEAT) -- they can contain GOTO loops, though.
A script can be called in a DO or REPEAT loop -- this is an important feature, and scripts will show their full potential in the context of loops.
There are a few commands that only make sense in a script, for instance the PROMPT command, IF ... THEN conditions, or the ENDLOOP command -- we'll come to them later.
Within a script calculation results are not written to hy, except when a calculation line uses accumulation mode.
To uphold this principle, the command $ is not allowed in a script. $ & and $ && are calculation lines, though, and write the value of $ to hy in accumulation mode.
When a script has performed one or more calculations, the last calculation result gets written to hy at the end of the script (unless this has already happened because the last calculation line had used accumulation mode).
When a script runs in a loop, this happens at each pass of the loop.
If the last calculation line in a script uses silent mode, hy does not get updated at the end of the script.
(Remember, only calculation lines have results, a variable assignment command $myvar = ... does not count as a calculation.)
In buffer mode results get written to the result buffer instead of hy, which is considerably faster -- see page The Result Buffer in chapter "Results".
You have to create a script file with an editor. You can, but do not have to, use Hypatia's EDIT filename command.
Like all of Hypatia's files script files must be located in Hypatia's program folder.
The name of the file is the name of the script. The name must not contain spaces or any of the characters ? * ( ) \ / | > <, and must not begin with $ or @.
No file extension is assumed, but you can use any you want.
For better readability a script can have empty lines, and lines can be indented with spaces or tabs.
For comments in a script, see page Comments later in this chapter.
Because Hypatia only reads from a script file and does not write to it, you can keep it open in the editor while you work on it.
If the working of your script depends on certain settings (like angle mode, integer bias, or zero threshold) then it is a good idea to include the respective commands at the beginning of the script.
(If your script will run in a loop, do this in I1: lines -- they will be explained on page Loop Index, Start and End Lines in chapter "Loops".)
The command to execute, or run, a script is:
RUN filename
There is a short version of this command: an underscore character immediately followed by the file name (no space in between):
_filename
When you use the RUN command the output to the screen is more verbose than with the underscore version.
How to run a script in a loop will be discussed in the next chapter, Loops.
The commands ECHO ON and ECHO OFF turn echo mode on or off (off is default).
ECHO on its own displays the current state of the echo mode, on or off.
With echo mode on, the lines in the script are displayed as they are processed, this is mostly meant to help with debugging.
In most cases scripts will use variables.
Any variable that already exists before the script is called can be used by the script, but Hypatia allows you to enter values of variables while the script gets executed.
This is done with the PROMPT command, which prompts the user to enter a value which will be assigned to a variable:
PROMPT $variable comment
The user can enter a number, or a calculation -- the result will be assigned to the variable, but it will not update $ and will not be written to hy.
The variable can be one that already exists, or it can be a new one, in which case it will be created when a value is entered.
If an empty line is entered, an existing variable retains its value. A variable that does not yet exist will not be created, though -- this will probably result in an error later in the script.
Optionally a comment can be added after the variable name, to explain what value should be entered.
The comment will be displayed in lower case characters, with the first character being in upper case.
Let us write a simple script to see how this works.
The body mass index is calculated from a person's height and weight: weight in kg divided by the square of height in m.
With the variables $kg and $cm for weight and height we have to divide the height by 100 to convert it to m -- the formula (in RPN) then is $kg $cm 100 / SQ /
(You remember: RPN expressions are processed from left to right:
The first operator / divides $cm by 100 which returns the height in m, then the operator SQ squares that value, and finally the next operator / divides $kg by that result.)
Since we hardly need the body mass index with 13 digits after the decimal point, let's round the result to just one: $kg $cm 100 / SQ / 1 ROUND
Now we can create our script, let's call it bmi:
? EDIT bmi
In the editor window that opens enter the following lines:
PROMPT $cm enter height in cm:
PROMPT $kg enter weight in kg:
$kg $cm 100 / SQ / 1 ROUND
Save the file, close the editor, and from now on you can use this script -- for example:
? _bmi
Enter height in cm:
? $cm = 172
Enter weight in kg:
? $kg = 64
= 21.6
In case you are in the US and want to use pounds, feet and inches, we'll deal with that later in this chapter.