*** PIBCALC -- Interactive Desk Calculator.
*   Version:   1.1
*   Date:      March, 1985
*   Author:    Philip R. Burns
*

*** Invoking PIBCALC:
*
*   Type:
*
*      PIBCALC
*
*   in response to the MS-DOS prompt.

*** Leaving PIBCALC:
*
*   Type:
*
*      EXIT
*
*   in response to the PibCalc prompt.

*** INTRODUCTION.
*
*   PIBCALC is an interactive desk calculator designed especially for
*   Programmers.  PIBCALC tries to combine the features of the better
*   pocket calculators with the well-known expression syntax of the
*   common algorithmic programming languages.  PIBCALC offers the
*   following features:
*
*      Integer and Real Floating Point Arithmentic
*      Octal, Decimal, and Hexadecimal Bases.
*      The usual arithmetic operators.
*      Common mathematical functions.
*      User-defined variables.
*      User-defined functions.


*** COMMANDS.
*
*   EXP         Display value of expression.
*   VAR=EXP     Set variable to value of expression and display result.
*   END or EXIT Quit PIBCALC.
*   HELP        Display this documentation.
*   DEC         Set default base to decimal (default).
*   OCT         Set default base to octal.
*   HEX         Set default base to hexadecimal.
*   RAD         Use radians for trigonometric functions (default).
*   DEG         Use degrees for trigonometric functions.
*   FRAC=INT    Set number of digits to display after the decimal
*               point (default = 2).
*   DEF FNAME(V1,...,VN) = EXP   Define a user function.
*   DEL FNAME   Delete a user function definition.
*   DEL V       Delete a variable definition.
*   SHOW FUNCS  Display all user-defined functions.
*   SHOW VARS   Display all defined variables.
*   EDIT        Edit last command entered and execute edited version.
*   Just <CR>   Display current value of accumulator.


*** TYPES.
*
*   PIBCALC understands two types of numbers:  Integers and Reals.
*   Most operators and functions allow either integer or real
*   arguments.  Some require integer arguments.  Integers are
*   automatically converted to reals when necessary.
*
*   Note that at this time, Turbo Pascal 2.0 only supports 16-bit
*   integers.  Operations resulting in integer values outside the
*   16-bit range will produce bizarre results from PibCalc.

*** DISPLAYS.
*
*   Numbers are displayed according to their type.  Integers are
*   displayed in all three bases:  decimal, octal, and hex.  Reals
*   are displayed in both regular and scientific (exponential) format.


*** CONSTANTS.
*
*   Integer constants may be followed by an 'O' or 'B' (for Octal),
*   'X' (for hexadecimal), or 'D' (for decimal), to override the
*   default base.  Real constants MUST contain a decimal point, and may
*   the usual 'E' notation for exponents.  Real constants are
*   always decimal.
*
*   EXAMPLES:
*
*   3126             (Default base used)
*   734B             (Octal)
*   A16B4X           (Hex)
*   73.6             (Real)
*   19.              (Real)
*   .541E-4          (Real with exponent)


*** VARIABLES.
*
*   Any of the 26 letters 'A' through 'Z' may be used as a variable.
*   Initially all 26 are undefined.  Lower case letters are treated
*   as upper case letters.


*** THE ACCUMULATOR.
*
*   PIBCALC keeps track of the last value calculated for an expression
*   in an 'accumulator'.  The syntactic element '.' can be used to allow
*   expressions to refer to this value.


*** OPERATORS.
*
*   +         Addition.
*   -         Subtraction.
*   *         Multiplication.
*   /         Real division.
*   **        Exponentiation.
*   DIV       Integer division.
*   MOD       Integer MOD function.
*
*   + - *:    Result is an integer IFF both arguments are integers.
*   /:        Result is always real.
*   MOD, DIV: Result is always an integer.  Both operands must be
*             integers.
*   **: X**Y  is an integer IFF X is an integer and Y is an integer
*             and Y >= 0.  Otherwise the result is real.
*
*   PRECEDENCE LEVELS (1 highest, 3 lowest):
*
*     1.    **
*     2.    * / MOD DIV
*     3.    + -
*
*   Within a precedence level evaluation is always left-to-right.


*** STANDARD MATH FUNCTIONS AND CONSTANTS.
*
*   ABS(X)      SIN(X)    ASIN(X)    EXP(X)     EE
*   MIN(X,...)  COS(X)    ACOS(X)    LN(X)      PI
*   MAX(X,...)  TAN(X)    ATAN(X)    LOG10(X)
*   TRUNC(X)    COT(X)    ACOT(X)    LOG(B,X)
*   ROUND(X)    SEC(X)    ASEC(X)    SQRT(X)
*               CSC(X)    ACSC(X)
*                         ATAN2(Y,X)
*
*   ABS, MIN, MAX: Result is an integer IFF all arguments are integers.
*   TRUNC, ROUND:  Result is always an integer.
*   All others:    Result is always real.
*
*   ASIN, ATAN, ACSC: Function result Z is in range ABS(Z) <= PI/2.
*   ACOS, ACOT, ASEC: Function result Z is in range 0 <= Z <= PI.
*   ATAN2:            Function result Z is in range ABS(Z) <= PI.
*
*   ATAN2(Y,X) returns the inverse tangent of Y/X.
*
*   EE is the mathematical constant 2.71828... , the base of the natural
*   (Naperian) logarithms.  The name has two Es to avoid confusion with
*   the variable named E.


*** USER-DEFINED FUNCTIONS.
*
*   You may define up to twenty functions.  For example, the following
*   functions of three variables compute the two roots of the
*   quadratic equation  A*X**2 + B*X + C = 0 (if it has any real roots):
*
*   DEF ROOT1(A,B,C) = (-B + SQRT(B*B - 4*A*C)) / (2*A)
*   DEF ROOT2(A,B,C) = (-B - SQRT(B*B - 4*A*C)) / (2*A)
*
*   The following calls to these functions display the roots of
*   X**2 - 5*X + 6 = 0:
*
*   ROOT1(1,-5,6)
*   ROOT2(1,-5,6)
*
*   There are no restrictions on the expression used to define the
*   function.  Any variables which appear in the expression which do not
*   appear in the formal parameter list refer to the global variables
*   'A' through 'Z'.  User-defined functions may call each other.
*   They are evaluated interpretively.  For example, if function AA
*   calls function BB, and then BB is redefined, then later calls
*   to AA will use the NEW definition of BB.  However, user functions
*   should not call each other recursively, since an infinite loop
*   might result.
*
*   User-defined functions may have 0 to 10 formal parameters.
*
*   Function names may be 1 to 9 characters long.  They MUST start
*   with a letter, and contain only the letters and digits.  Uppercase
*   and lowercase are not distinguished in function names.
*
*   If a function is defined with the same name as a standard PIBCALC
*   function or variable name then the user function definition
*   overrides the built-in definition.


*** EXPRESSIONS.
*
*   Expressions are composed of constants, variables, function calls,
*   and the special element '.', using the operators  +, -, *, /, **,
*   MOD, and DIV, acoording to the usual algorithmic programming language
*   syntax rules.  Parentheses may be used for grouping.  The precise
*   syntax is given below in a modified Backus-Naur form.
*
*   NOTATION USED:
*
*   =            is defined to be.
*   .            end of definition.
*   '...'        Literal.
*   [...]        Optional.
*   <...>        Repeat 0 or more times.
*   |            Or.
*   (...)        Grouping.
*
*   EXP     = [SIGN] TERM < ADOP TERM >.
*   TERM    = FACTOR < MULOP FACTOR >.
*   FACTOR  = ELEMENT < '**' ELEMENT >.
*   ELEMENT = CONST | VAR | '(' EXP ')' | '.' | FUNC.
*   SIGN    = '+' | '-'.
*   ADOP    = '+' | '-'.
*   MULOP   = '*' | '/' | 'MOD' | 'DIV'.
*   CONST   = INT | REAL.
*   INT     = DECINT | OCTINT | HEXINT.
*   DECINT  = DEC <DEC> ['D'].
*   OCTINT  = OCT <OCT> ['B'|'O'].
*   HEXINT  = HEX <HEX> ['X'].
*   REAL    = DEC <DEC> '.' <DEC> [EXPON] |
*             <DEC> '.' DEC <DEC> [EXPON].
*   EXPON   = 'E' [SIGN] DEC <DEC>.
*   VAR     = LET.
*   FUNC    = FNAME [ '(' EXP < ',' EXP > ')' ].
*   FNAME   = LET < ALPHNUM >.
*   ALPHNUM = LET | DEC.
*   LET     = 'A' | ... | 'Z'.
*   DEC     = '0' | ... | '9'.
*   OCT     = '0' | ... | '7'.
*   HEX     = '0' | ... | '9' | 'A' | ... | 'F'.


*** NOTES ON HEX MODE.
*
*   When the default base is hexadecimal many ambiguities can arise.
*   For example, the letters 'A' through 'F' could be either variable
*   names or hex constants. 'DEC' could be either a command or a
*   hex constant, and '32B' could be either the octal constant (= 26 dec.)
*   or the hex constant 32B.  The rule is that ALL SUCH AMBIGUITIES
*   ARE RESOLVED IN FAVOR OF THE INTERPRETATION AS A HEX CONSTANT.
*   To override this rule a colon (:) may be used to prefix the construct.
*   For example, ':32B' always means the octal constant 32 (=26 dec.),
*   whatever the default base may be.

*** NOTES ON EDIT MODE.
*
*   When the command EDIT is entered, the last command line is re-displayed.
*   This line may then be edited using WordStar commands or the keypad
*   keys, quite similarly to the way the Turbo editor works.  A carriage
*   return ends the editing and causes PibCalc to scan and execute the
*   edited line.  This facility is particularly useful when defining
*   several similar functions, or to repair syntactic errors like
*   missing or extra parentheses in function definitions.
*
*   Note:  The INS key toggles overwrite and insert mode.
*

