-- RPilot: Rob's PILOT Version 1.4.2 --
-- Copyright 1998,2002 Rob Linwood (rcl211@nyu.edu) --
-- WWW: http://rpilot.sourceforge.net/ --
Intro::
RPilot is an interpreter for the PILOT programming language. PILOT,
the Programmed Inquiry, Learning, Or Teaching language, was originally
designed to be used by teachers as an aid in instruction. PILOT is
easy to learn, and most people should be able to in a very short amount
of time. PILOT was first developed in 1962, and was standardized by
the IEEE in 1991. RPilot probably isn't completely standard, but it
is very close. It also adds a few extensions not found in standard
PILOT interpretors, such as rudimentry debugging and the ability to
call other programs. RPilot was written in 100% ANSI standard C, and
should be easily portable to any platform with a standard C compiler.
Programming::
PILOT programs consist of a series of statements, which are either
labels or function calls. PILOT statements all end with a newline, and
the lines themselves may be no longer than 127 characters long. PILOT
is case insensitive when it comes to label and variable names, $name,
$NaMe, and $NAME all refer to the same variable. Speaking of variables,
PILOT has only two different types: string, and numeric.
Variables::
String variables consist of a list of characters which can be up to
127 bytes long. Numeric variables are equivilent to C's int. They
can be any number in the range of -2,147,483,648 to 2,147,483,648
(with 32 bit rpilot) or -32,768 to 32,768 (with 16 bit DOS rpilot).
Variables are referenced by their names, which can be up to 10
characters in length, and consist of a type designator followed by
any non-whitespace characters. When I say "type designator", I mean
that all string variables have a "$" as their first character, and all
numerics use "#". Thus, $count refers to a string, and #count to
a number. This leads to another point: a string variable and a
numeric one can have the same name, so both $count and #count could
exist at the same time. They are independent of each other, however.
PILOT also implements labels, which are used just like in any other
language, and are declared in the following way:
*labelname
This would define a label called "labelname". All label definitions
start with an asterisk (the "*"), and follow that with the label name.
Label names, like variable names, are case insensitive.
PILOT statements that do not declare labels have the following syntax:
<command>[conditional] : [arguments]
<command> is any of RPilot's internal commands, which I will cover
shortly. [conditional] is an optional conditional expression which
determines whether the statement will be executed. This is different
from more contemporary languages which use "if" clauses and the like, in
that the "if" clause is implemented in every function, in a way.
[arguments] is an optional list of arguments to be passed to the function.
Some functions require arguments; others don't.
Commands::
Commands in RPilot are exactly one character long. This may seem
a little wierd, but that's the way things are. Even if you are a
PILOT expert, you will find it beneficial to read ALL of the command
descriptions, to learn the nuances of RPilot. On to the commands:
R ::
The "R" (Remark) command flags the rest of the line as a comment,
and therefore the interpreter ignores it. This is a good way to
add reminders to yourself about what you have typed. Example:
R: This is a comment
A ::
The "A" (Accept) command takes input from the user. It can
take the name of a string or numeric variable as an argument, in
which case it will store the input into the given variable. If
no arguments are given, it stores input into the string variable
"$answer". Examples:
R: The next line gets a string from the user and puts it in
: "$answer"
A:
R: This gets a number and stores it in "#group"
A: #group
Note that you can only name one variable for each A command
T ::
The "T" (Type) command is used to display information. If any
arguments are given, it displays the string, substituting
variables as needed. With no arguments, it prints a blank line.
Examples:
R: The next line prints the contents of the variables "$name",
: "$rank", and "#serialnum"
T: Name: $name Rank: $rank Serial Number: #serialnum
T: Note that instead of using the same command over and over
T: again, as I have just done, you can skip the command name
T: and just use the colon, as I have done in a few examples,
: like this.
: It saves time, and makes things look nicer.
J ::
The "J" (Jump) command is like GOTO in BASIC and other languages.
It causes the interpreter to jump to the label given to it as
an argument. When giving a label name, do not add on the
initial "*". Example:
R: The next line causes a jump to the label "done"
J: done
U ::
The "U" (Use) command is used to implement a sort of primitive
subroutine. It causes the interpreter to jump to the given
label, just like J, but first it pushes to current file offset
onto a stack. When the E command is reached, that value is
popped off and jumped to. This is like GOSUB in BASIC.
Example:
U: sub
T: Back from the sub!
J: done
*sub
T: Now we're in the sub.
R: We'll look at the "E" command next
E:
*done
E ::
The "E" (End) command is used with U to return from subroutines.
If no subroutines were called, E ends the program. Example:
T: The next line ends this program
E:
T: This is never executed
Also note the example for the U command.
M ::
The "M" (Match) command is used to handle user input. It
compares a given list of strings to the last string which was
used to hold input from the A command. This also is very wierd,
and it would probably help to check some of the example programs.
If RPilot finds a match, it sets the variable "#matched" to 1,
and the variable "#which" to the position of the matched string
in the argument list. Example:
T: What is your favorite flavor of ice cream?
A: $icecream
R: The next line checks to see if "vanilla" or "mint" were
: entered during the last A command
M: vanilla mint
If $icecream = "vanilla" then #which would equal 1. If the answer
was "mint", then #which would equal 2. In either case, #matched
would be set to 1. If neither matched what the user typed, then
#matched would be set to 0, and so would #which
C ::
The "C" (Compute) command sets variables. The argument string
contains a variable name followed by an equal sign ("="),
followed by a value to assign tot he variable. For numerics,
this is a mathematical expression which can contain one or more
terms, and variables as well as constants. See the section on
math for more info on expressions. For strings, it is a list
of strings and variables which will be copied into the given
variable. For example:
R: This causes "#number" to be incremented by 5
C: #number = 5 + #number
R: This copies the contents of "$firstname" and "$lastname"
: to the variable "$fullname"
C: $fullname = $firstname $lastname
Y ::
The "Y" (Yes) command works like T, except that it only prints
if the variable "#matched" equals 1. This is usually used in
conjunction with M. Example:
A:
M: Herbert Floyd
Y: You typed "Herbert" or "Floyd"
N: You entered some other name.
N ::
The "N" (No) command is just the opposite of Y, it only prints
if "#matched" equals 0. For an example, see above.
That's it for the standard PILOT. Next we take a look at RPilot's
extensions.
X ::
The "X" (eXecute) command runs a line of PILOT code which you
pass to it. The argument(s) are either a constant string,
(ie, "T: Hello!"), or a string variable. Try the following:
A:
X: $answer
It will wait for you to input a string, and then will try to run
it. If you were to type "T: Boo!", that command would take
place, and "Boo!" would be displayed
S ::
The "S" (Shell) command allows you to execute other programs.
This gives you access to the operating system and all other
programs on the user's machine. For example:
S: dir
OR
S: /bin/ls
will display a list of files, depending on what operating system
you are running.
The return code of the program which you ran is stored in the
variable `#retcode'. If a program runs succesfully, this should
be zero. If not, it usually means that something went wrong.
D ::
The "D" (Debug) command is used as a way to quickly and easily
get a list of all variables and labels. It takes a string as an
argument, and checks for two characters. If it sees an "l" or
an "L" (case is unimportant), it will dump a list of all labels
and their offsets. If it sees a "v" or a "V", it will do a
variable dump, listing all variables and their values. This is
useful when something goes wrong, and you need to check
everything at once. Example:
D: Lv
Lists all labels, followed by all variables
G ::
The "G" (Generate) command is used to generate random numbers,
and place them in a variable. It takes three arguments, first
a numeric variable, then two numbers. It randomly creates a
number between the second and third arguments, and places it
in the variable specified by the first. Example:
G: #rand 23 56
This generates a number between 23 and 56, and stores it in #rand
This is especially useful when making things that require random
values, such as games. (See the example programs for a few games
that use G)
Math::
RPilot supports the following mathematical operators (math ops):
Standard:
+ :: Adds two things together
- :: Subtracts one number from another
* :: Multiplies two numbers
/ :: Divides one number by another
RPilot Extensions:
% :: Gets the modulo (remainder after division) of two numbers
& :: Gets the bitwise AND of two numbers
| :: Bitwise OR of two numbers
^ :: Bitwise XOR of two numbers
I'm not sure how useful all the bitwise operators are, but they
were easy enough to add, so why not? RPilot works all expressions
from left to right, and currently ignores operator precedence.
Conditionals::
RPilot statements can contain "conditional expressions" (condexs),
which are evaluated and checked to see if they are true. If so,
the rest of the statement is run. They are placed after the command,
such as in this example:
J(#answer > 45): menu1
In this case, the condex is "(#answer > 45)" The J (Jump) will only
take place if the value of "#answer" is more than 45. If not, RPilot
goes on to the next line. RPilot understands the following
"relational operators" (relat ops):
= :: True if two numbers are equal
< :: True if the first number is less than the second
> :: True if the first is greater than the second
<> :: True if the two numbers are not equal
<= :: True if the first is less than or equal to the second
>= :: True if the first is greater than or equal to the second
Of course, you are free to use all the math ops in a condex, such as:
T(#score + 10 >= 50): You made it by at least 10 points!
Note, however, that you can have only one relational operator per
condex.
In addition to standard condexs, there are also two other methods
of testing a condition, Y and N. If the condex of a statement is
a captial "Y", then RPilot checks to see if "#matched" is equal to
1. If so, the condition is true, and is then executed. "N" is the
opposite, and checks whether "#matched" equals 0. If so, the
statement is executed. These are ususally used after an "M" command,
for example:
A: $answer
M: 1776 1812 1968 1998
R: The following line jumps to "correct" if "#matched" equals 1.
: That would be true if "M" matched any dates listed
JY: correct
R: If "#matched" equals 0, then "N" statements are true, and are
: then executed
TN: You did not answer correctly
Special Variables::
RPilot has two special variables which you can use. They are special
because they are set by the interpreter itself, so you can use them
without assigning a value first. The two special variables are:
$prompt - This is the prompt which is printed out for an A: (Accept)
command. The default value is ">". If you run the following
program:
T: Please enter a number
C: $prompt = rpilot>
A: #number
You would see that when you are asked for a number, the
prompt is "rpilot>" rather than ">".
#rpilot - This is the version number of RPilot. For version 1.4,
it's value is 14. RPilot 1.5 would be 15, and 2.0 would
be 20.
Interactive Mode::
If RPilot is invoked with the "-i" command line switch, it will
attempt to enter an interactive mode, where you type commands in, and
have them executed immediately.
Interactive mode is not a part of the `rpilot' program, but rather
it should be written as an external PILOT program. Therefore, in
order for RPilot to use interactive mode, it needs a program to run.
It will find one in one of two ways:
1) Look for a program called "interact.p" in the current directory.
2) Run the program specified by the RPILOT_INTERACT environment
variable.
The `inter.p' file located in the examples directory is a good
program to use. Feel free to customize it by editing the source code.
Note::
I think that the best way to learn RPilot is to look through all the
example programs after reading this, and hopefully it will make more
sense. They are all fully commented, and are meant to serve as
learning aids.
Where to get RPilot::
The RPilot web site is located at http://rpilot.sourceforge.net/ All
new versions are released there first.
RPilot for DOS will (hopefully) be found at the following places:
Note that the XX stands for the version number, ie rpilot10.zip for
version 1.0.
ftp.simtel.net/pub/simtelnet/msdos/misclang/rpilotXX.zip
and it's many mirrors
RPilot for Linux will be found at
sunsite.unc.edu/pub/Linux/devel/lang/misc/rpilot-XX.tar.gz
and it's many mirrors
RPilot for OS/2 2.0 and above wil l be at
hobbes.nmsu.edu/pub/os2/dev/misc/rpos2xx.zip
and it's many mirrors
The source code will in be all of the packages, along with makefiles and
tips relevant to the particular platform. Since RPilot is portable, all
of the versions were built from the exact same source.
Also, check out my home page at http://auntfloyd.home.ml.org/ Updates
will always be available there, along with other cool stuff.
Contacting the Author::
If you find any bugs or have any questions/comments, write me at
rcl211@nyu.edu
Special Thanks to::
Ken Martwick - for sending me a bug report. So now you can run gcc-
compiled versions of RPilot.
License::
Since Linux people seem to be big on licenses and garbage like that,
here's info on RPilot's license:
**********************************************************************
RPilot: Rob's PILOT Interpreter
Copyright 1998 Rob Linwood
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
**********************************************************************
See the COPYING file for the full text.
----------
Rob Linwood (rcl211@nyu.edu)
http://homepages.nyu.edu/~rcl211/