@database "PCalc"
@author "J. Tierney"
@(c) "Copyright © 1995 - 1996 J. Tierney"
@$VER: PCalc.guide 1.0 (27.4.96)
@node MAIN "PCalc Documentation"

PCalc  v1.16
© 1995 - 1996  J. Tierney

@{"Introduction  " link INTRO}  Description and features.
@{"Legalities    " link SMEG}  Copyright, disclaimer and distribution notes.
@{"Requirements  " link NEEDS}  There's only one.
@{"Installation  " link INSTALL}  Nothing to it, really.

@{"Usage         " link USE}  Command line options.
@{"Numeric Data  " link NUMS}  Supported number formats.
@{"Operators     " link OPRS}  What PCalc can do with/to those numbers.

@{"Notes         " link DOREMI}  Things to be aware of.
@{"Error Messages" link UHOH}  PCalc's vocabulary.

@{"The Past      " link ONCEUPONATIME}  Program history.
@{"The Future    " link PLANS}  Comming soon.  ...Or not.
@{"Thanks To...  " link GRACIAS}  Credit where credit is due.
@{"The Author    " link SMEGHEAD}  That'd be me.
@endnode

@node INTRO "Welcome to PCalc"

  PCalc (Programmer's Calculator) is a CLI-based calculator that operates on
32 bit numbers.  It accepts input in four numbering systems, decimal, hex,
binary, and ASCII, and displays output in all four formats.
  I wrote it both as a learning experience, and because I wasn't satisfied
with Eval.  I consider it my kitchen sink program, as I've added, and continue
to add, every useful feature I can think of except for the kitchen sink.
...And if I find there's any way a sink relates to 32 bit numbers then I'll
add that, too.  :-)


Features:
  - Input data as decimal, hexadecimal, binary, or ASCII.

  - Output is displayed in decimal, hexadecimal, binary, and ASCII format.

  - 29 operators.  Arithmatic, logical, boolean, character...

  - Multiple operations in an expression; e.g.  PCalc 2 + (5 * 4) ^ 3

  - Many operators may be invoked in more than one way.  For example, "|" and
   "OR" both perform a logical OR.

  - Tested with Enforcer and MungWall.
@endnode

@node SMEG "PCalc:  Legal Issues"

@{u}@{b}Copyright Info:@{ub}@{uu}
  PCalc, copyright © 1995 - 1996 Jody J. Tiereny.  All rights reserved.
...with an option on the lefts, too.

  PCalc is FreeWare.


@{u}@{b}Disclaimer:@{ub}@{uu}
  No warranties, expressed or implied.  Use this program at your own risk.
Although much effort has been, and continues to be, put into this program to
ensure safe and stabe operation, I take no responsibility for any damages
and/or losses incurred through the use/misuse of this program.

  However, I will take credit for anything you like about the program.  :-)


@{u}@{b}Distribution:@{ub}@{uu}
  PCalc may be freely distributed in it's original form so long as no fee,
beyond a nominal copying charge to cover time and media, which is not to
exceed $4 US, is attatched.

  PCalc may not be included with any commercial product without written
permission from the author.

  Special permission is granted to include PCalc in public domain collections
such as Fred Fish's disks and CDs, and the Aminet CDs.  A copy of the disk,
while not mandatory, would be appreciated.
@endnode

@node NEEDS "PCalc:  Requirements"

@{u}@{b}Required:@{ub}@{uu}
  - Workbench 2.0 or above.
@endnode

@node INSTALL "PCalc:  Installation"

@{b}@{u}Installation:@{ub}@{uu}
  PCalc consists of one file, by no small coincidence named "PCalc", which may
be placed anywhere you see fit.  "C:", or somewhere in your search path, would
do nicely.
@endnode

@node USE "PCalc:  Usage"

@{b}CLI Arguments:@{ub}
  Format:  [ND=NODEC] [NH=NOHEX] [NB=NOBIN] [NC=NOCHAR] <expression>

  Template: ND=NODEC/S, NH=NOHEX/S, NB=NOBIN/S, NC=NOCHAR/S, EXPRESSION/A/F

@{b}Function:@{ub}
  - NODEC  - Don't display the output in decimal format.
  - NOHEX  - Don't display the output in hexadecimal format.
  - NOBIN  - Don't display the output in binary format.
  - NOCHAR - Don't display the output in ASCII format.

    Note:  Switches _must_ come before <expression>.

  - EXPRESSION - (Keyword optional)  <expression> may contain numeric data and
              operators.  Spaces and capitalization are optional.


@{b}Examples:@{ub}
  Input:   PCalc 65 + $C
  Output:  +77         -> Decimal format.
           $4D         -> Hexadecimal format.
           %1001101    -> Binary format.  Leading zeros are omitted.
           "M"         -> 32 bit number as ASCII.  Leading bytes are omitted
                          if unprintable (0-31, 128-159).  Spaces represent
                          unprintable trailing bytes.

  Input:   PCalc NB NC %11101
  Output:  +29
           $1D
@endnode

@node NUMS "PCalc:  Valid Numeric Data"

Numeric data may be entered in the following formats:
  - Decimal:  0 - 9.  Ex.:  72, 9, -1.

  - Hexadecimal: 0-9, A-F.  Preceded by "$".  Ex.:  $0F, $40, -$a9.
      Note:  It's advisable to place a <space> between a hex number and an
            operator which begins with a letter.  "$7a and 55" is fine, but
            "$72and 55" would be misinterpreted as "$72A" "nd 55" and generate
            an error.

  - Binary:  0 - 1.  Preceded by "%".  Ex.:  %1001, -%1110, %001.
      Note:  Leading zeroes are not necessary.

  - ASCII:  Up to four characters enclosed in single quotes, "'".  The value
           is the ASCII value of the characters.  Case is significant.
           Ex:  'B', 'xA', '1234'.

      Some characters may be swallowd by AmigaDOS (";" and "=", for example),
     and PCalc itself uses the "'" character.  Special character sequences are
     provided to overcome this.  These sequences begin with a backslash, "\",
     and are only valid within the quoted value.
      Note these @{u}are@{uu} case-sensitive.  Also, each sequence counts as only
     one character, so quoted values of four special characters are valid.

      Special Character Sequences (preceded by a backslash, "\"):
         a  - Apostrophe/single quote:  '
         n  - Linefeed:                 ASCII 10
         q  - Quotation mark:           "
         r  - Carriage return:          ASCII 13
         :  - Semicolon:                ;
         ,  - Less-than symbol:         <
         .  - Greater-than symbol:      >
         +  - Equal sign:               =
         \  - Backslash:                \

      Ex.:  '\q'      =  "
            'I\all'   =  I'll
            '\\'      =  \
            '\:\\a\q' =  ;\a"
@endnode

@node OPRS "PCalc:  Operators"
@next DOREMI

@{b}@{u}Operator:@{ub}@{uu}                  @{b}@{u}Description:@{ub}@{uu}
@{"<none>" link OP_CNV}                    Number conversion or implied multiplication.
@{"+" link OP_ADD}                         Addition.
@{"-" link OP_SUB}                         Subtraction or negative number.
@{"*" link OP_MUL}                         Multiplication.
@{"/" link OP_DIV}                         Division.
@{"()" link OP_PTH}                        Precedence.
@{"MOD" link OP_MOD}, @{"\ " link OP_MOD}                  Modulo (remainder).
@{"^" link OP_PWR}, @{"EXP" link OP_PWR}                   Raise to power.
@{"AND" link OP_AND}, @{"&" link OP_AND}                   Logical AND.
@{"OR" link OP_OR}, @{"|" link OP_OR}                    Logical OR.
@{"EOR" link OP_EOR}, @{"XOR" link OP_EOR}, @{"E|" link OP_EOR}, @{"X|" link OP_EOR}, @{"||" link OP_EOR}  Logical Exclusive OR.
@{"~" link OP_NOT}                         Logical NOT.
@{"ASL" link OP_ASL}                       Arithmetic shift left.
@{"ASR" link OP_ASR}                       Arithmetic shift right.
@{"LSL" link OP_LSL}                       Logical shift left.
@{"LSR" link OP_LSR}                       Logical shift right.
@{"ROL" link OP_ROL}                       Rotate left.
@{"ROR" link OP_ROR}                       Rotate right.
@{"ROXL" link OP_ROXL}                      Rotate left with X register.
@{"ROXR" link OP_ROXR}                      Rotate right with X register.
@{"EQU" link OP_EQU}, @{"=" link OP_EQU}, @{"==" link OP_EQU}              Boolean equal.
@{"NE" link OP_NE}, @{"<>" link OP_NE}                   Boolean not-equal.
@{"GTR" link OP_GTR}, @{">" link OP_GTR}                   Boolean greater than.
@{"LSS" link OP_LSS}, @{"<" link OP_LSS}                   Boolean less than.
@{"GRE" link OP_GRE}, @{">=" link OP_GRE}, @{"=>" link OP_GRE}             Boolean greater than or equal to.
@{"LSE" link OP_LSE}, @{"<=" link OP_LSE}, @{"=<" link OP_LSE}             Boolean less than or equal to.
@{"%OF" link OP_POF}                       Percent of.
@{"%?" link OP_WPO}                        What percent of.
@{"CNTR" link OP_CNTR}                      Center.

@endnode

@node OP_CNV "PCalc Operators"
@toc OPRS

Operator:  <none>
Functions:  Numeric conversion.
            Implied multiplication.
Operands:  One (conversion):  <n>
           Two (multiplication):  <n1> <n2>

@{b}Examples:@{ub}
  Input:   PCalc 65
  Output:  +65
           $41
           %1000001
           "A"

  Input:   PCalc %110001110
  Output:  +398
           $18E
           %110001110
           ""

  Input:   PCalc '\a'
  Output:  +39
           $27
           %100111
           "'"

  Input:   PCalc 4 5
  Output:  +20
           $14
           %10100
           ""
  Note:  Implied multiplication.

  Input:   PCalc 4(3 + %11 + 4)
  Output:  +40
           $28
           %101000
           "("
@endnode

@node OP_ADD "PCalc Operators"
@toc OPRS

Operator:  +
Function:  Addition.
Operands:  Two:  <n1> + <n2>

@{b}Examples:@{ub}
  Input:   PCalc 4 + 8
  Output:  +12
           $C
           %1100
           ""

  Input:   PCalc 'A' + $c
  Output:  +77
           $4D
           %1001101
           "M"

  Input:   PCalc 5 + 34 + %1100 + $FF
  Output:  +306
           $132
           %100110010
           "2"
@endnode

@node OP_SUB "PCalc Operators"
@toc OPRS

Operator:  -
Functions:  Negative number.
            Subtraction.
Operands:  One (negative number):  -<n>
           Two (subtraction):  <n1> - <n2>

@{b}Examples:@{ub}
  Input:   PCalc -15
  Output:  -15
           $FFFFFFF1
           %11111111111111111111111111110001
           "ÿÿÿñ"

  Input:   PCalc 10 - -9
  Output:  +19
           $13
           %10011
           ""

  Input:   PCalc 101 - 54
  Output:  +47
           $2F
           %101111
           "/"

  Input:   PCalc  'AbC' - $2000
  Output:  +4276803
           $414243
           %10000010100001001000011
           "ABC"

  Input:   PCalc 100 - 109
  Output:  -9
           $FFFFFFF7
           %11111111111111111111111111110111
           "ÿÿÿ÷"
@endnode

@node OP_MUL "PCalc Operators"
@toc OPRS

Operator:  *
Function:  Multiplication.
Operands:  Two:  <n1> * <n2>

@{b}Examples:@{ub}
  Input:   PCalc  $20 * 5
  Output:  +160
           $A0
           %10100000
           " "

  Input:   PCalc  542 * %111001 * 17
  Output:  +525198
           $8038E
           %10000000001110001110
           ""

  Input:   PCalc 'Smeg' * 9
  Output:  -287797089
           $EED8909F
           %11101110110110001001000010011111
           "îØ  "
@endnode

@node OP_DIV "PCalc Operators"
@toc OPRS

Operator:  /
Function:  Division.
Operands:  Two:  <n1> / <n2>

@{b}Examples:@{ub}@{uu}
  Input:   PCalc 75 / 2
  Output:  +37
           $25
           %100101
           "%"

  Input:   PCalc $32 / 4
  Output:  +12
           $C
           %1100
           ""

  Input:   PCalc  '12Ab' / 0
  Output:  Division by zero error.
@endnode

@node OP_PTH "PCalc Operators"
@toc OPRS

Operator:  ()
Function:  Change order of expression evaluation.  PCalc otherwise evaluates
          expressions from left to right.
Operands:  At least one expression:  (<exp>)

@{b}Examples:@{ub}
  Input:   PCalc 2 + 5 * 4
  Output:  +28
           $1C
           %11100
           ""
  Note:  The above expression was evaluated as:  2 + 5 = 7
                                                  7 * 4 = 28

  Input:   PCalc 2 + (5 * 4)
  Output:  +22
           $16
           %10110
           ""
  Note:  In this expression, 5 * 4 was evaluated first, and then 2 was added
         to the result of 20.

  Input:   PCalc 40 - (5 + (100/4)) + 'A'
  Output:  +75
           $4B
           %1001011
           "K"

  Input:   PCalc 2 (3 + 1)
  Output:  +8
           $8
           $1000
           ""
  Note:  Evaluated as:  3 + 1 = 4
                        2 <no operator implies multiplication> 4 = 8
@endnode

@node OP_MOD "PCalc Operators"
@toc OPRS

Operator:  \  or  MOD
Function:  Modulo division; find the remainder.
Operands:  Two:  <n1> \ <n2>

@{b}Examples:@{ub}
  Input:   PCalc 100 \ 6
  Output:  +4
           $4
           %100
           ""

  Input:   PCalc 5 MOD 2
  Output:  +1
           $1
           %1
           ""

  Input:   PCalc $32 \ (20 - %10100)
  Output:  Division by zero error.
@endnode

@node OP_PWR "PCalc Operators"
@toc OPRS

Operator:  ^  or  EXP
Function:  Raise to a power.
Operands:  Two:  <n> ^ <power>

@{b}Examples:@{ub}
  Input:   PCalc 3 ^ 3
  Output:  +27
           $1B
           %11011
           ""

  Input:   PCalc $FFFF EXP 0
  Output:  +1
           $1
           %1
           ""
  Note:  When using "EXP" and a hex number, as above, be sure to have at least
        one space after the number.  Otherwise the "E" in "EXP" will be taken
        as part of the number ($FFFFE in the above example), and an error will
        result since "XP" isn't any sort of operator PCalc recognizes
        (so far...).

  Input:   PCalc  $55 ^ 100
  Output:  +230687025
           $DC00131
           %1101110000000000000100110001
           "À 1"
@endnode

@node OP_AND "PCalc Operators"
@toc OPRS

Operator:  &  or  AND
Function:  Logical AND.
Operands:  Two:  <n1> & <n2>

@{b}Examples:@{ub}
  Input:   PCalc %1100111 & %11110
  Output:  +6
           $6
           %110
           ""

  Input:   PCalc 5464 AND $F
  Output:  +8
           $8
           %1000
           ""

  Input:   PCalc $BEEF AND 987
  Output:  +715
           $2CB
           %1011001011
           "Ë"
  Note:  When using "AND" and a hex number, as above, be sure to have at least
        one space after the number.  Otherwise the "A" in "AND" will be taken
        as part of the number ($BEEFA in the above example), and an error will
        result since "ND" isn't (currently) an operator.
@endnode

@node OP_OR "PCalc Operators"
@toc OPRS

Operator:  |  or  OR
Function:  Logical OR.
Operands:  Two:  <n1> | <n2>

@{b}Examples:@{ub}
  Input:   PCalc %1001 | %10010
  Output:  +27
           $1B
           %11011
           ""

  Input:   PCalc 'AB' OR 11
  Output:  +16715
           $414B
           %100000101001011
           "AK"

  Input:   PCalc 99 OR $80000000
  Output:  -2147483549
           $80000063
           %10000000000000000000000001100011
           "c"
@endnode

@node OP_EOR "PCalc Operators"
@toc OPRS

Operator:  ||  or  EOR  or  XOR  or  E|  or  X|
Function:  Logical Exclusive OR.
Operands:  Two:  <n1> || <n2>

@{b}Examples:@{ub}
  Input:   PCalc $F EOR %101
  Output:  +10
           $A
           %1010
           ""
  Note:  When using "EOR" or "E|" and a hex number, as above, be sure to have
        at least one space after the number.  Otherwise the "E" will be taken
        as part of the number ($FE in the above example), and a logical OR will
        be performed.

  Input:   PCalc 'a' || 'A'
  Output:  +32
           $20
           %100000
           " "

  Input:   PCalc 'xxx' X| $200020
  Output:  +5797976
           $587858
           %10110000111100001011000
           "XxX"
@endnode

@node OP_NOT "PCalc Operators"
@toc OPRS

Operator:  ~
Function:  Logical NOT.
Operands:  One:  ~<n>

@{b}Examples:@{ub}
  Input:   PCalc ~%1101
  Output:  -14
           $FFFFFFF2
           %11111111111111111111111111110010
           "ÿÿÿò"

  Input:   PCalc ~-2
  Output:  +1
           $1
           %1
           ""

  Input:   PCalc ~(5 * 4)
  Output:  -21
           $FFFFFFEB
           %11111111111111111111111111101011
           "ÿÿÿë"
@endnode

@node OP_ASL "PCalc Operators"
@toc OPRS

Operator:  ASL
Function:  Arithmetic shift left.  A zero moves into bit 0, and bit 31 is lost.
Operands:  Two:  <n> ASL <shift 0-31 bits>

@{b}Examples:@{ub}
  Input:   PCalc %11011 ASL 2
  Output:  +108
           $6C
           %1101100
           "l"

  Input:   PCalc $AF ASL 8
  Output:  +44800
           $AF00
           %1010111100000000
           "¯ "
  Note:  When using "ASL" and a hex number, as above, be sure to have at least
        one space after the number.  Otherwise the "A" in "ASL" will be taken
        as part of the number ($AFA in the above example), and an error will
        result since "SL" isn't a recognized operator.

  Input:   PCalc 'a1' ASL $10
  Output:  +1630601216
           $61310000
           %1100001001100010000000000000000
           "a1  "
@endnode

@node OP_ASR "PCalc Operators"
@toc OPRS

Operator:  ASR
Function:  Arithmetic shift right.  Bit 0 is lost, bit 31 recieves a 1 if it
           was originally set, otherwise a 0.
Operands:  Two:  <n> ASR <shift 0-31 bits>

@{b}Examples:@{ub}
  Input:   PCalc $80000001 ASR 2
  Output:  -536870912
           $E0000000
           %11100000000000000000000000000000
          "à   "
  Note:  When using "ASR" and a hex number, as above, be sure to have at least
        one space after the number.  Otherwise the "A" in "ASR" will be taken
        as part of the number.  In the above example an "Unknown operator or
        value too large" error would result as $80000001A isn't a 32 bit value.

  Input:   PCalc -16 ASR 2
  Output:  -4
           $FFFFFFFC
           %11111111111111111111111111111100
           "ÿÿÿü"

  Input:   PCalc %111000001
  Output:  +56
           $38
           %111000
           "8"
@endnode

@node OP_LSL "PCalc Operators"
@toc OPRS

Operator:  LSL
Function:  Logical shift left.  Bit 0 is cleared, and bit 31 is lost.
Operands:  Two:  <n> LSL <shift 0-31 bits>

@{b}Examples:@{ub}
  Input:   PCalc %101110 LSL 1
  Output:  +92
           $5C
           %1011100
           "\"

  Input:   PCalc 'GOne' LSL 8
  Output:  +1332634880
           $4F6E6500
           %1001111011011100110010100000000
           "One "

  Input:   PCalc $FEED LSL 2
  Output:  +261044
           $3FBB4
           %111111101110110100
           "û´"
@endnode

@node OP_LSR "PCalc Operators"
@toc OPRS

Operator:  LSR
Function:  Logical shift right.  Bit 31 is cleared, and bit 0 is dropped.
Operands:  Two:  <n> ASR <shift 0-31 bits>

@{b}Examples:@{ub}
  Input:   PCalc 'Gone' LSR $10
  Output:  +18287
           $476F
           %100011101101111
           "Go"

  Input:   PCalc %111000 LSR 3
  Output:  +7
           $7
           %111
           ""

  Input:   PCalc 240 LSR 2
  Output:  +60
           $3C
           %111100
           "<"
@endnode

@node OP_ROL "PCalc Operators"
@toc OPRS

Operator:  ROL
Function:  Rotate left.  Bit 31 is transferred to bit 0.
Operands:  Two:  <n> ROL <rotate 0-31 bits>

@{b}Examples:@{ub}
  Input:   PCalc $C0000001 ROL 1
  Output:  -2147483645
           $80000003
           %10000000000000000000000000000011
           ""

  Input:   PCalc 'slob' ROL 8
  Output:  +1819239027
           $6C6F6273
           %1101100011011110110001001110011
           "lobs"

  Input:   PCalc 256 ROL 3
  Output:  +2048
           $800
           %100000000000
           ""
@endnode

@node OP_ROR "PCalc Operators"
@toc OPRS

Operator:  ROR
Function:  Rotate right.  Bit 0 wraps around to bit 31.
Operands:  Two:  <n> ROR <rotate 0-31 bits>

@{b}Examples:@{ub}
  Input:   PCalc  %11 ROR 1
  Output:  -2147483647
           $80000001
           %10000000000000000000000000000001
           ""

  Input:   PCalc 'oaks' ROR 8
  Output:  +1936679275
           $736F616B
           %1110011011011110110000101101011
           "soak"

  Input:   PCalc 256 ROR 3
  Output:  +32
           $20
           %100000
           " "
@endnode

@node OP_ROXL "PCalc Operators"
@toc OPRS

Operator:  ROXL
Function:  Rotate left through the X register.  Bit 0 recieves the contents of
           the X register, and bit 31 is transferred to the X register.
Operands:  Two:  <n> ROXL <rotate 0-31 bits>

@{b}Examples:@{ub}
  Input:   PCalc $C0000001 ROXL 1
  Output:  -2147483646
           $80000002
           %10000000000000000000000000000010
           ""

  Input:   PCalc $C0000001 ROXL 2
  Output:  +5
           $5
           %101
           ""

  Input:   PCalc 'slob' ROXL 8
  Output:  +1819238969
           $6C6F6239
           %1101100011011110110001000111001
           "lob9"
@endnode

@node OP_ROXR "PCalc Operators"
@toc OPRS

Operator:  ROXR
Function:  Rotate right with the X register.  The X register moves into bit 31,
           and bit 0 enters the X register.
Operands:  Two:  <n> ROXR <rotate 0-31 bits>

@{b}Examples:@{ub}
  Input:   PCalc  %11 ROXR 1
  Output:  +1
           $1
           %1
           ""

  Input:   PCalc %11 ROXR 2
  Output:  -2147483648
           $80000000
           %10000000000000000000000000000000
           ""

  Input:   PCalc 'ook:' ROXR 8
  Output:  +1953460075
           $746F6F6B
           %1110100011011110110111101101011
           "took"
@endnode

@node OP_EQU "PCalc Operators"
@toc OPRS

Operator:  EQU  or  =  or  ==
Function:  Equality.  This is a boolean operator, and will return either a
           -1 (True) or a 0 (False).
Operands:  Two:  <n1> EQU <n2>

@{b}Examples:@{ub}
  Input:   PCalc "%101 = 5"
  Output:  -1
           $FFFFFFFF
           %11111111111111111111111111111111
           "ÿÿÿÿ"
  Note:  It's always a good idea to enclose any expression containing the ">",
        "<", and/or "=" symbols in quotation marks to prevent AmigaDOS from
        trying to use them.

  Input:   PCalc 4 EQU (11 MOD 6)
  Output:  +0
           $0
           %0
           ""

  Input:   PCalc $0F == 15
  Output:  -1
           $FFFFFFFF
           %11111111111111111111111111111111
           "ÿÿÿÿ"
@endnode

@node OP_NE "PCalc Operators"
@toc OPRS

Operator:  NE  or  <>
Function:  Inquality.  This is a boolean operator, and will return either a
           -1 (True) or a 0 (False).
Operands:  Two:  <n1> NE <n2>

@{b}Examples:@{ub}
  Input:   PCalc "$10 <> 10"
  Output:  -1
           $FFFFFFFF
           %11111111111111111111111111111111
           "ÿÿÿÿ"
  Note:  It's always a good idea to enclose any expression containing the ">",
        "<", and/or "=" symbols in quotation marks to prevent AmigaDOS from
        trying to use them.

  Input:   PCalc %1011 NE $B
  Output:  +0
           $0
           %0
           ""

  Input:   PCalc 4 NE (100 \ 60 / 10)
  Output:  +0
           $0
           %0
           ""
@endnode

@node OP_GTR "PCalc Operators"
@toc OPRS

Operator:  GTR  or  >
Function:  Greater than.  This is a boolean operator, and returns either -1
           (True) or 0 (False).
Operands:  Two:  <n1> GTR <n2>

@{b}Examples:@{ub}
  Input:   PCalc "7 > 9"
  Output:  +0
           $0
           %0
           ""
  Note:  It's always a good idea to enclose any expression containing the ">",
        "<", and/or "=" symbols in quotation marks to prevent AmigaDOS from
        trying to use them.

  Input:   PCalc "10 > (45 / 9)"
  Output:  -1
           $FFFFFFFF
           %11111111111111111111111111111111
           "ÿÿÿÿ"

  Input:   PCalc ((88 / 7) GTR (255 MOD 25)) * 5
  Output:  -5
           $FFFFFFFB
           %11111111111111111111111111111011
           "ÿÿÿû"
@endnode

@node OP_LSS "PCalc Operators"
@toc OPRS

Operator:  LSS  or <
Function:  Less than.  A boolean operator, this returns -1 (True) or 0 (False).
Operands:  Two:  <n1> LSS <n2>

@{b}Examples:@{ub}
  Input:   PCalc "4 < 4"
  Output:  +0
           $0
           %0
           ""
  Note:  It's always a good idea to enclose any expression containing the ">",
        "<", and/or "=" symbols in quotation marks to prevent AmigaDOS from
        trying to use them.

  Input:   PCalc 15 / 3 LSS 6
  Output:  -1
           $FFFFFFFF
           %11111111111111111111111111111111
           "ÿÿÿÿ"

  Input:   PCalc 40 * 7 LSS 256 * 3
  Output:  +0
           $0
           %0
           ""
@endnode

@node OP_GRE "PCalc Operators"
@toc OPRS

Operator:  GRE  or  >=  or  =>
Function:  Greater than or equal to.  A boolean operator, this returns -1
           (True) or 0 (False).
Operands:  Two:  <n1> GRE <n2>

@{b}Examples:@{ub}
  Input:   PCalc $10 GRE 16
  Output:  -1
           $FFFFFFFF
           %11111111111111111111111111111111
           "ÿÿÿÿ"

  Input:   PCalc "%10011 >= 22"
  Output:  +0
           $0
           %0
           ""
  Note:  It's always a good idea to enclose any expression containing the ">",
        "<", and/or "=" symbols in quotation marks to prevent AmigaDOS from
        trying to use them.

  Input:   PCalc "14 => 24"
  Output:  +0
           $0
           %0
           ""
@endnode

@node OP_LSE "PCalc Operators"
@toc OPRS

Operator:  LSE  or  <=  or  =<
Function:  Less than or equal to.  A boolean operator, this returns -1 (True)
           or 0 (False).
Operands:  Two:  <n1> LSE <n2>

@{b}Examples:@{ub}
  Input:   PCalc "10 <= $A"
  Output:  -1
           $FFFFFFFF
           %11111111111111111111111111111111
           "ÿÿÿÿ"
  Note:  It's always a good idea to enclose any expression containing the ">",
        "<", and/or "=" symbols in quotation marks to prevent AmigaDOS from
        trying to use them.

  Input:   PCalc (100 / $15) LSE ($C - %1001)
  Output:  +0
           $0
           %0
           ""

  Input:   PCalc "%100 =< 9 * 3"
  Output:  -3
           $FFFFFFFD
           %11111111111111111111111111111101
           "ÿÿÿý"
@endnode

@node OP_POF "PCalc Operators"
@toc OPRS

Operator:  %OF
Function:  Percent of.  The integer result of:  <n1> * <n2> * .01.
Operands:  Two:  <n1> %OF <n2>

@{b}Examples:@{ub}
  Input:   PCalc 25 %OF 36
  Output:  +9
           $9
           %1001
           ""

  Input:   PCalc 5 %OF 27
  Output:  +1
           $1
           %1
           ""

  Input:   PCalc 5 %OF 33
  Output:  +2
           $2
           %10
           ""
@endnode

@node OP_WPO "PCalc Operators"
@toc OPRS

Operator:  %?
Function:  What percent of.  The integer result of <n1> / <n2> * 100.
Operands:  Two:  <n> LSS <n>

@{b}Examples:@{ub}
  Input:   PCalc 9 %? 36
  Output:  +25
           $19
           %11001
           ""

  Input:   PCalc $11 %? 100
  Output:  +17
           $11
           %10001
           ""

  Input:   PCalc 287 %? 235
  Output:  +122
           $7A
           %1111010
           "z"
@endnode

@node OP_CNTR "PCalc Operators"
@toc OPRS
@next OPRS

Operator:  CNTR
Function:  Center.  Returns the number of spaces needed to center <n1> within
           <n2>.  Equivilent to the expression:  (n2 / 2) - (n1 / 2).
           For expample, if you wanted to center a 30 letter word in an 80
           column line, use "PCalc 30 CNTR 80".
Operands:  Two:  <n1> CNTR <n2>

@{b}Examples:@{ub}
  Input:   PCalc 30 CNTR 80
  Output:  +25
           $19
           %11001
           ""

  Input:   PCalc 5 CNTR 3
  Output:  -1
           $FFFFFFFF
           %11111111111111111111111111111111
           "ÿÿÿÿ"

  Input:   PCalc $10 CNTR %10000
  Output:  +0
           $0
           %0
           ""
  Note:  When using "CNTR" and a hex number, as above, be sure to have at least
        one space after the number.  Otherwise the "C" in "CNTR" will be taken
        as part of the number, "$10C" in the above example.
@endnode

@node DOREMI "PCalc:  Things to be Aware of"
@prev OPRS

@{b}Note:@{ub}
  - PCalc only deals with 32-bit integers.

  - Currently, all numbers are signed.  Any numbers greater than $7FFFFFFF
    (2,147,483,647), i.e. having bit 31 set, are treated as being negative.

  - Only parentheses have any precedence over other operators.  Otherwise
   expressions are evaluated from left to right.
   "PCalc 2 + 5 * 4" will equal 28.   "PCalc 2 + (5 * 4)" will equal 22.

  - Some characters, such as ";", """, "=", "<", and ">", may be swallowed by
   AmigaDOS.  PCalc provides alternatives, e.g. "EQU" rather than "=", "\:"
   instead of ";".  Enclosing the expression with quotation marks is another
   option.  PCalc '\:' + 2  and  PCalc "';' + 2"  will both return 61.

   Although PCalc will recognize these characters, alternatives have
   also been provided, eg. "EQU" rather than "=", "\:" instead of ";".
   See @{"Numeric Data" link NUMS} and @{"Operators" link OPRS} for more information.

  - The command line is case-insensitive.

  - Spaces within the expression are usually optional. "5  +  'o'   " and
   "5+'o'" are both valid.  However, there must be at least one space between
   a hex number and any operator begining with the letters "A" - "F".
@endnode

@node UHOH "PCalc:  I'm sorry Dave, I can't do that."

@{b}Error Messages:@{ub}
  - Bad Args.  Format:
    PCalc [ND=NODEC] [NH=NOHEX] [NB=NOBIN] [NC=NOCHAR] <expression>
    - Arguments were entered incorrectly, or no expression (which is required)
     was entered.

  -  *** Break
    - PCalc recieved a Control C.

  - Unable to allocate memory.
    - You multitasking maniac.

  - Unknown operator or value too large.
    - Either a value larger than $FFFFFFFF (4 billion & something) was entered,
     you mistyped an operator (nah, not you), or a hex number is right next to
     an operator beginning with "A"-"F".  "$75and33" would be evaluated as
     "$75A ND 3", and "ND" is a college, not an operator.

  - Unmatched quote or string value too large.
    - Quoted (ASCII) values may be up to four characters (bytes) in length
     (4 bytes = 32 bits, PCalc's limit).  Either more than four characters were
     entered, or there's an odd number of single quotes in the expression.

  - Division by zero error.
    - You know better than that.
@endnode

@node ONCEUPONATIME "PCalc:  The Early Years"

@{b}@{u}History:@{ub}@{uu}
  A long time ago, in a galaxy far, far away...

  - v1.0  - 4/15/95

  - v1.1  - 5/11/95 - First public release.
                    - Various bug fixes.

  - v1.2  - 5/30/95 - Added @{"CNTR" link OP_CNTR} and @{"%OF" link OP_POF} operators.
                    - Added ".".

  - v1.3  - 6/14/95 - Major bug fixed:  failure unless second operand was
                     a decimal number or negative.
                    - Added @{"%?" link OP_WPO} operator.

  - v1.15 - 5/9/96  - Major overhaul.  Fixed old bugs, introduced new ones, and
                     then fixed them.
                    - Added @{"character sequences" link NUMS}.
                    - Removed some old operator aliases (such as "L>" for LSR).
                     They may be back if there's a demand for them.
                    - "." is gone, and won't be back (just enclose your
                     expression in quotes).

  - v1.16 - 5/24/96 - Bug fix:  @{"%OF" link OP_POF} only worked correctly with 16-bit values.
@endnode

@node PLANS "PCalc:  The Next Generation"

@{b}Future Plans:@{ub}
  - More operators.
  - Locate any remaining bugs.  Replace them with newer, more interesting ones.
  - Octal, anyone?  No, maybe not...
  - Should the character result always display four bytes, such as:  "..A."?
  - Maybe an option to display only <n> bytes, e.g WORD, BYTE.  ...But then the
    same thing can already be done with an AND, so I guess not.
@endnode

@node GRACIAS "PCalc:  Credit Where Credit Is Due"

@{b}Many thanks to the folowing:@{ub}

  - God - Life, the universe, and everything.

  - Wouter van Oortmerssen - Amiga E.  The best programming language I've ever
                            used.

  - Matt Dillon/Aaron Digulla - DME/XDME.

  - Heinz Wrobel - HWGRCS.

  - My cat - Various programming suggestions and solutions.  "Sleep on it,"
            being one of many valuable lessons.

  - Blondie,
    Deborah Harry,
    Ramones         - Music to program by.
@endnode

@node SMEGHEAD "PCalc:  The Author"

Feel free to send comments, bug reports, suggestions, and/or gifts to:

    Jody J. Tierney
   29118 Lark Street
Elkhart, IN  46514-9579
         USA

@{b}E-Mail:@{ub}  jtierney@cyberlink-inc.com
@{b}   WWW:@{ub}  www.cyberlink-inc.com/jtierney
@endnode