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).
A script can be called in a loop, though -- 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.
You can have empty lines in your script, they will be ignored. For comments in a script, see the page after the next.
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 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 it is an important feature that you can 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 only be assigned to the variable, 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.
Body mass index is calculated from 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 /
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.