home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / rpos2101.zip / RPILOT.TXT < prev    next >
Text File  |  1998-07-04  |  17KB  |  396 lines
  1.  
  2.                      -- RPilot: Rob's PILOT Version 1.01 --
  3.             -- Copyright 1998 Rob Linwood (auntfloyd@biosys.net) --
  4.                    -- WWW: http://auntfloyd.home.ml.org/ --
  5.  
  6. Intro::
  7.     RPilot is an interpreter for the PILOT programming language.  PILOT,
  8.     the Programmed Inquiry, Learning, Or Teaching language, was originally
  9.     designed to be used by teachers as an aid in instruction.  PILOT is
  10.     easy to learn, and most people should be able to in a very short amount
  11.     of time.  PILOT was first developed in 1962, and was standardized by
  12.     the IEEE in 1991.  RPilot probably isn't completely standard, but it
  13.     is very close.  It also adds a few extensions not found in standard
  14.     PILOT interpretors, such as rudimentry debugging and the ability to
  15.     call other programs.  RPilot was written in 100% ANSI standard C, and
  16.     should be easily portable to any platform with a standard C compiler.
  17.  
  18.  
  19. Programming::
  20.     PILOT programs consist of a series of statements, which are either
  21.     labels or function calls.  PILOT statements all end with a newline, and
  22.     the lines themselves may be no longer than 127 characters long.  PILOT
  23.     is case insensitive when it comes to label and variable names, $name,
  24.     $NaMe, and $NAME all refer to the same variable.  Speaking of variables,
  25.     PILOT has only two different types: string, and numeric.
  26.  
  27.     Variables::
  28.         String variables consist of a list of characters which can be up to
  29.         127 bytes long.  Numeric variables are equivilent to C's int.  They
  30.         can be any number in the range of -2,147,483,648 to 2,147,483,648
  31.         (with 32 bit rpilot) or -32,768 to 32,768 (with 16 bit DOS rpilot).
  32.         Variables are referenced by their names, which can be up to 10
  33.         characters in length, and consist of a type designator followed by
  34.         any non-whitespace characters.  When I say "type designator", I mean
  35.         that all string variables have a "$" as their first character, and all
  36.         numerics use "#".  Thus, $count refers to a string, and #count to
  37.         a number.  This leads to another point: a string variable and a
  38.         numeric one can have the same name, so both $count and #count could
  39.         exist at the same time.  They are independent of each other, however.
  40.  
  41.     PILOT also implements labels, which are used just like in any other
  42.     language, and are declared in the following way:
  43.  
  44.     *labelname
  45.  
  46.     This would define a label called "labelname".  All label definitions
  47.     start with an asterisk (the "*"), and follow that with the label name.
  48.     Label names, like variable names, are case insensitive.
  49.  
  50.     PILOT statements that do not declare labels have the following syntax:
  51.  
  52.     <command>[conditional] : [arguments]
  53.  
  54.     <command> is any of RPilot's internal commands, which I will cover
  55.     shortly.  [conditional] is an optional conditional expression which
  56.     determines whether the statement will be executed.  This is different
  57.     from more contemporary languages which use "if" clauses and the like, in
  58.     that the "if" clause is implemented in every function, in a way.
  59.     [arguments] is an optional list of arguments to be passed to the function.
  60.     Some functions require arguments; others don't.
  61.  
  62.     Commands::
  63.         Commands in RPilot are exactly one character long.  This may seem
  64.         a little wierd, but that's the way things are.  Even if you are a
  65.         PILOT expert, you will find it beneficial to read ALL of the command
  66.         descriptions, to learn the nuances of RPilot.  On to the commands:
  67.  
  68.         R ::
  69.             The "R" (Remark) command flags the rest of the line as a comment,
  70.             and therefore the interpreter ignores it.  This is a good way to
  71.             add reminders to yourself about what you have typed. Example:
  72.  
  73.             R: This is a comment
  74.  
  75.         A ::
  76.             The "A" (Accept) command takes input from the user.  It can
  77.             take the name of a string or numeric variable as an argument, in
  78.             which case it will store the input into the given variable.  If
  79.             no arguments are given, it stores input into the string variable
  80.             "$answer".  Examples:
  81.  
  82.             R: The next line gets a string from the user and puts it in
  83.              : "$answer"
  84.             A:
  85.  
  86.             R: This gets a number and stores it in "#group"
  87.             A: #group
  88.  
  89.             Note that you can only name one variable for each A command
  90.  
  91.         T ::
  92.             The "T" (Type) command is used to display information.  If any
  93.             arguments are given, it displays the string, substituting
  94.             variables as needed.  With no arguments, it prints a blank line.
  95.             Examples:
  96.  
  97.             R: The next line prints the contents of the variables "$name",
  98.              : "$rank", and "#serialnum"
  99.             T: Name: $name Rank: $rank Serial Number: #serialnum
  100.  
  101.             T: Note that instead of using the same command over and over
  102.             T: again, as I have just done, you can skip the command name
  103.             T: and just use the colon, as I have done in a few examples,
  104.              : like this.
  105.              : It saves time, and makes things look nicer.
  106.  
  107.         J ::
  108.             The "J" (Jump) command is like GOTO in BASIC and other languages.
  109.             It causes the interpreter to jump to the label given to it as
  110.             an argument.  When giving a label name, do not add on the
  111.             initial "*".  Example:
  112.  
  113.             R: The next line causes a jump to the label "done"
  114.             J: done
  115.  
  116.         U ::
  117.             The "U" (Use) command is used to implement a sort of primitive
  118.             subroutine.  It causes the interpreter to jump to the given
  119.             label, just like J, but first it pushes to current file offset
  120.             onto a stack.  When the E command is reached, that value is
  121.             popped off and jumped to.  This is like GOSUB in BASIC.
  122.             Example:
  123.  
  124.             U: sub
  125.             T: Back from the sub!
  126.             J: done
  127.  
  128.             *sub
  129.             T: Now we're in the sub.
  130.             R: We'll look at the "E" command next
  131.             E:
  132.  
  133.             *done
  134.  
  135.         E ::
  136.             The "E" (End) command is used with U to return from subroutines.
  137.             If no subroutines were called, E ends the program.  Example:
  138.  
  139.             T: The next line ends this program
  140.             E:
  141.             T: This is never executed
  142.  
  143.             Also note the example for the U command.
  144.  
  145.         M ::
  146.             The "M" (Match) command is used to handle user input.  It
  147.             compares a given list of strings to the last string which was
  148.             used to hold input from the A command.  This also is very wierd,
  149.             and it would probably help to check some of the example programs.
  150.             If RPilot finds a match, it sets the variable "#matched" to 1,
  151.             and the variable "#which" to the position of the matched string
  152.             in the argument list.  Example:
  153.  
  154.             T: What is your favorite flavor of ice cream?
  155.             A: $icecream
  156.  
  157.             R: The next line checks to see if "vanilla" or "mint" were
  158.              : entered during the last A command
  159.             M: vanilla mint
  160.  
  161.             If $icecream = "vanilla" then #which would equal 1.  If the answer
  162.             was "mint", then #which would equal 2.  In either case, #matched
  163.             would be set to 1.  If neither matched what the user typed, then
  164.             #matched would be set to 0, and so would #which
  165.  
  166.         C ::
  167.             The "C" (Compute) command sets variables.  The argument string
  168.             contains a variable name followed by an equal sign ("="),
  169.             followed by a value to assign tot he variable.  For numerics,
  170.             this is a mathematical expression which can contain one or more
  171.             terms, and variables as well as constants.  See the section on
  172.             math for more info on expressions.  For strings, it is a list
  173.             of strings and variables which will be copied into the given
  174.             variable.  For example:
  175.  
  176.             R: This causes "#number" to be incremented by 5               
  177.             C: #number  = 5 + #number
  178.  
  179.             R: This copies the contents of "$firstname" and "$lastname"
  180.              : to the variable "$fullname"
  181.             C: $fullname = $firstname $lastname
  182.  
  183.         Y ::
  184.             The "Y" (Yes) command works like T, except that it only prints
  185.             if the variable "#matched" equals 1.  This is usually used in
  186.             conjunction with M.  Example:
  187.  
  188.             A:
  189.             M: Herbert Floyd
  190.             Y: You typed "Herbert" or "Floyd"
  191.             N: You entered some other name.
  192.  
  193.         N ::
  194.             The "N" (No) command is just the opposite of Y, it only prints
  195.             if "#matched" equals 0.  For an example, see above.
  196.  
  197.         That's it for the standard PILOT.  Next we take a look at RPilot's
  198.         extensions.
  199.  
  200.         X ::
  201.             The "X" (eXecute) command runs a line of PILOT code which you
  202.             pass to it.  The argument(s) are either a constant string,
  203.             (ie, "T: Hello!"), or a string variable.  Try the following:
  204.  
  205.             A:
  206.             X: $answer
  207.  
  208.             It will wait for you to input a string, and then will try to run
  209.             it.  If you were to type "T: Boo!", that command would take
  210.             place, and "Boo!" would be displayed
  211.  
  212.         S ::
  213.             The "S" (Shell) command allows you to execute other programs.
  214.             This gives you access to the operating system and all other
  215.             programs on the user's machine.  For example:
  216.  
  217.             S: dir
  218.             OR
  219.             S: /bin/ls
  220.  
  221.             will display a list of files, depending on what operating system
  222.             you are running.
  223.  
  224.         D ::
  225.             The "D" (Debug) command is used as a way to quickly and easily
  226.             get a list of all variables and labels.  It takes a string as an
  227.             argument, and checks for two characters.  If it sees an "l" or
  228.             an "L" (case is unimportant), it will dump a list of all labels
  229.             and their offsets.  If it sees a "v"  or a "V", it will do a
  230.             variable dump, listing all variables and their values.  This is
  231.             useful when something goes wrong, and you need to check
  232.             everything at once.  Example:
  233.  
  234.             D: Lv
  235.  
  236.             Lists all labels, followed by all variables
  237.  
  238.         G ::
  239.             The "G" (Generate) command is used to generate random numbers,
  240.             and place them in a variable.  It takes three arguments, first
  241.             a numeric variable, then two numbers.  It randomly creates a
  242.             number between the second and third arguments, and places it
  243.             in the variable specified by the first.  Example:
  244.  
  245.             G: #rand 23 56
  246.  
  247.             This generates a number between 23 and 56, and stores it in #rand
  248.  
  249.             This is especially useful when making things that require random
  250.             values, such as games.  (See the example programs for a few games
  251.             that use G)
  252.  
  253.  
  254.     Math::
  255.         RPilot supports the following mathematical operators (math ops):
  256.  
  257.         Standard:
  258.         + :: Adds two things together
  259.         - :: Subtracts one number from another
  260.         * :: Multiplies two numbers
  261.         / :: Divides one number by another
  262.  
  263.         RPilot Extensions:
  264.         % :: Gets the modulo (remainder after division) of two numbers
  265.         & :: Gets the bitwise AND of two numbers
  266.         | :: Bitwise OR of two numbers
  267.         ^ :: Bitwise XOR of two numbers
  268.  
  269.         I'm not sure how useful all the bitwise operators are, but they
  270.         were easy enough to add, so why not?  RPilot works all expressions
  271.         from left to right, and currently ignores operator precedence.  If
  272.         division seems flaky, this is due to the way in which the C compiler
  273.         handles division.  Don't blame me for it.
  274.  
  275.  
  276.     Conditionals::
  277.         RPilot statements can contain "conditional expressions" (condexs),
  278.         which are evaluated and checked to see if they are true.  If so,
  279.         the rest of the statement is run.  They are placed after the command,
  280.         such as in this example:
  281.  
  282.         J(#answer > 45): menu1
  283.  
  284.         In this case, the condex is "(#answer > 45)"  The J (Jump) will only
  285.         take place if the value of "#answer" is more than 45.  If not, RPilot
  286.         goes on to the next line.  RPilot understands the following
  287.         "relational operators" (relat ops):
  288.  
  289.         =  :: True if two numbers are equal
  290.         <  :: True if the first number is less than the second
  291.         >  :: True if the first is greater than the second
  292.         <> :: True if the two numbers are not equal
  293.         <= :: True if the first is less than or equal to the second
  294.         >= :: True if the first is greater than or equal to the second
  295.  
  296.         Of course, you are free to use all the math ops in a condex, such as:
  297.  
  298.         T(#score + 10 >= 50): You made it by at least 10 points!
  299.  
  300.         Note, however, that you can have only one relat op per condex.
  301.  
  302.         In addition to standard condexs, there are also two other methods
  303.         of testing a condition, Y and N.  If the condex of a statement is
  304.         a captial "Y", then RPilot checks to see if "#matched" is equal to
  305.         1.  If so, the condition is true, and is then executed.  "N" is the
  306.         opposite, and checks whether "#matched" equals 0.  If so, the
  307.         statement is executed.  These are ususally used after an "M" command,
  308.         for example:
  309.  
  310.         A: $answer
  311.         M: 1776 1812 1968 1998
  312.         R: The following line jumps to "correct" if "#matched" equals 1.
  313.          : That would be true if "M" matched any dates listed
  314.         JY: correct
  315.         R: If "#matched" equals 0, then "N" statements are true, and are
  316.          : then executed
  317.         TN: You did not answer correctly
  318.  
  319.        
  320.     I think that the best way to learn RPilot is to look through all the
  321.     example programs after reading this, and hopefully it will make more
  322.     sense.  They are all fully commented, and are meant to serve as
  323.     learning aids.
  324.  
  325.  
  326. Where to get RPilot::
  327.  
  328.     RPilot for DOS will (hopefully) be found at the following places:
  329.     Note that the XX stands for the version number, ie rpilot10.zip for
  330.     version 1.0.
  331.  
  332.         ftp.simtel.net/pub/simtelnet/msdos/misclang/rpilotXX.zip
  333.         and it's many mirrors
  334.         
  335.     RPilot for Linux will be found at
  336.  
  337.         sunsite.unc.edu/pub/Linux/devel/lang/misc/rpilot-XX.tar.gz
  338.         and it's many mirrors
  339.  
  340.     RPilot for OS/2 2.0 and above wil l be at
  341.  
  342.         hobbes.nmsu.edu/pub/os2/dev/misc/rpos2xx.zip
  343.         and it's many mirrors
  344.  
  345.     The source code will in be all of the packages, along with makefiles and
  346.     tips relevant to the particular platform.  Since RPilot is portable, all
  347.     of the versions were built from the exact same source.
  348.  
  349.     Also, check out my home page at http://auntfloyd.home.ml.org/  Updates
  350.     will always be available there, along with other cool stuff.
  351.  
  352.  
  353. Contacting the Author::
  354.  
  355.     If you find any bugs or have any questions/comments, write me at 
  356.     auntfloyd@biosys.net
  357.  
  358.  
  359. Special Thanks to::
  360.  
  361.     Ken Martwick - for sending me a bug report.  So now you can run gcc-
  362.                    compiled versions of RPilot.
  363.  
  364.  
  365. License::
  366.     Since Linux people seem to be big on licenses and garbage like that,
  367.     here's info on RPilot's license:
  368.  
  369.     **********************************************************************
  370.     RPilot: Rob's PILOT Interpreter
  371.     Copyright 1998 Rob Linwood
  372.  
  373.     This program is free software; you can redistribute it and/or modify
  374.     it under the terms of the GNU General Public License as published by
  375.     the Free Software Foundation; either version 2 of the License, or
  376.     (at your option) any later version.
  377.  
  378.     This program is distributed in the hope that it will be useful,
  379.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  380.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  381.     GNU General Public License for more details.
  382.  
  383.     You should have received a copy of the GNU General Public License
  384.     along with this program; if not, write to the Free Software
  385.     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  386.     **********************************************************************
  387.  
  388.     Hopefully you did get a copy of the GNU General Public License, look at
  389.     the file COPYING.TXT
  390.  
  391. ----------
  392. Rob Linwood (auntfloyd@biosys.net)
  393. Newark, Delaware, USA
  394. http://auntfloyd.home.ml.org
  395.  
  396.