
	 PopCALC - Programmers Calculator, Version 1.00
	     Copyright (c) 1994 by Omega Point, Inc.


INTRODUCTION

PopCALC is a TSR integer calculator using C operator/expression syntax.
In addition to C operator set, it includes ROTATE operator for assembler
programmers and a special Right-Assignement operator usefull for concise 
expressions. The integers may have word size 1,2,4 bytes and may be
treated as signed and unsigned. Output radix may be set to Decimal,
Hex and Binary, and input expressions may have mixed radix numbers.
PopCALC allows multiple complex expressions separated by semicolon,
and it has 26 variables labeled with letters A through Z. The expression
editor has insert and overtype mode, and supports Cursor, Del, Backspace,
Home, End, Tab, Back-Tab editing keys. It also has Ctl-Left, Ctl-Right
arrow commands, which skip from one to another expression and evaluate
them. Any computed result may be passed on to the interrupted foreground
application in C or ASM format. Calculator window may be moved to any 
place on the screen. Command line switches have access to any of 
PopCALC-s internal settings/modes.

With all these features, PopCALC occupies only 6.6K of RAM while in
resident mode and has 10K EXE file. The small TSR size (for a C program)
is due to elimination of startup code (command line parser)  and data
(signon screens) done automatically by CodeRunneR (tm). Additionally,
CodeRunneR's library is optimized for interactive pop-up application.


INVOKING CALCULATOR WINDOW

Once loaded, PopCALC is always a single key away. If your computer has
new style keyboard, press Right-Alt key to bring-up the calculator.
On older style keyboards, press Alt-SPACE. To return back to the
foreground application, press <Esc>, or Right-Alt. The state of the
PopCALC is preserved between invocations.


MOVING CALCULATOR WINDOW

You can move the calculator window (line) Up or Down using arrow keys.
If the video adapter supports more then 25 lines, the window will
reach any line on the screen.


UNLOADING PopCALC FROM MEMORY

PopCALC may be unloaded from memory by pressing Alt-X while in the
calculator window. The unload should be requested only if PopCALC is
the last TSR loaded. Although CodeRunneR has a function to check for this,
it was not used in this program, to save space. Therefore, PopCALC will
always unload, possibly deactivating other TSR-s loaded after PopCALC.


EXPRESSION ENTRY & EDITING

Expressions are entered in a conventional way (a la typical editor). Use
regular cursor keys to move around. <Home> key moves first to the beginning
of the expression, unless already there in which case it moves to the
beginning of line. Likewise, <End> moves to the end of expression, then
to the end of line. <Tab> and <Back-Tab> cycle between the four points of
<Home>,<End> keys. <Del> deletes current character, <Backspace> deletes
previous character.

<Ins> toggles between insert and overtype modes. In default mode PopCALC
comes up in overtype mode (underline cursor). The insert mode has full
blinking block cursor. The mode persists between calculator pop-ups.


NUMBER ENTRY

Numbers may be entered in Decimal, Hex and Binary radix. Sign + or - may
precede the digits. Numbers are internally kept as 32-bit integers.

DECIMAL: Max 10 digits, Max number: 4,294,967,295
HEX:	 Prefixed with 0x or 0. Max 8 digits, Max number 0xFFFFFFFF
BINARY:	 Prefixed with ` (Back-QUOTE). Max 32 digits.

Comma cannot be placed between digits.


OUTPUT RADIX

Output radix may be set using 3 Control Key commands (or the command line 
switches). The keys are:

Control D	- Set decimal radix
Control H	- Set hex radix
Control B	- Set binary radix

Following these three commands, the expression is re-evaluated and result is
displayed in the new radix.


OPERATORS

The operators follow standard C precedence rules. They are shown below,
in order of decreasing precedence, and with sub-groups having same
precedence:

-----------------------------------------
OPER    DESCRIPTION
-----------------------------------------
 (	Open parentheses (20 levels deep)
-----------------------------------------
 ~	Bitwise Complement
 -	Unary minus
 +	Unary plus
-----------------------------------------
 *	Multiply
 /	Divide
 %	Modulo
 \	Alternate symbol for modulo
-----------------------------------------
 +	Add
 -	Substract
-----------------------------------------
 <<	Shift Left
 >>	Shift Right
 [[	Rotate Left
 ]]	Rotate Right
-----------------------------------------
 &	Biwise AND
-----------------------------------------
 ^	Bitwise XOR
-----------------------------------------
 |	Bitwise OR
-----------------------------------------
 '	Right Assign (shows as ARROW)
-----------------------------------------
 )	Closed parentheses
-----------------------------------------
 ;	Statement separator
-----------------------------------------

The non standard ROTATE operators [[,]] rotate bit pattern to the left or
right, in the same manner as assembler ROL and ROR instructions. The
outcome depends on the (unsigned) word size as follows:

32-bit	X [[ 3	same as:    (X << 3) + (X >> (32-3))
16-bit	X [[ 3	same as:    (X << 3) + (X >> (16-3))
 8 bit	X [[ 3	same as:    (X << 3) + (X >> ( 8-3))


WORD SIZE COMMANDS (Ctl-C, Ctl-I, Ctl-L)

All integer computations are done modulo some power of 2 (i.e. only low
N bits of the result is kept on overflow). PopCALC provides for 3 word
sizes: Char (8-bits), Int (16-bits), Long (32-bits). These sizes are set
using commands Ctl-C, Ctl-I, Ctl-L respectively.

For most operators, the difference is only that the arguments and result
are stripped of excessive high bits. The only operators computed differently
are ROTATE operators.

NOTE: Variables are not affected by these commands. Only the variables
which are being assigned values in the current expression will have
values reduced to proper width. Variables which are used in the expression,
but not assigned value by the expression, are unchanged.


SIGNED/UNSIGNED ARITHMETIC (Ctl-S, Ctl-U)

Operators can view same numbers as signed and unsigned. The unsigned numbers
are always positive and range between 0 and M (M depends on word size).
The signed numbers have values between -M/2-1 and +M/2 (inclusive).
These boundaries are shown in the table below for different word sizes:

-----------------------------------------------------------------------
	              UNSIGNED			     SIGNED
-----------------------------------------------------------------------
Word size	  MIN	       MAX	        MIN		  MAX
-----------------------------------------------------------------------
  8 bits	   0	       255	       -128              +127
-----------------------------------------------------------------------
 16 bits	   0        65,535          -32,768           +32,767
-----------------------------------------------------------------------
 32 bits	   0  4,294,967,295   -2,147,483,648   +2,147,483,647
-----------------------------------------------------------------------

Right shift operator will fill in 1-s when in signed mode, and 0-s in
unsigned mode. Divide and Modulo operators will similarily produce
different result when in signed mode. Other operators work same, with
only the displayed result showing the different representation of the
same bit pattern. The only exceptional case is divide (or modulo) by
zero, which allways produces maximal unsigned number (or 0); such number
will show as -1 if Signed representation is used.


VARIABLES AND ASSIGNEMENT OPERATOR (')

PopCALC has 26 variables which are labeled as single letters A-Z (upper and
lower case are same). The assignement operator ' (Single QUOTE) assigns value
of the sub-expression on its left side to the varible on its right side.
For this reason it is actually DISPLAYED as an ARROW pointing to the right.
The value assigned is the current value computed up to that point in the
expression. From the precedence table, it is clear that this value includes
all the items to the right, until the first Unbalanced Open Parentheses.
MULTIPLE assignements are allowed in the same statement, leading to very
concise expressions.

Assignement Examples:

PopCALC			C Equivalent
-----------------------------------------------------------------------
125'x			x=125;
3+2'x			x=3+2;
3'x+2'y			x=3; y=3+2;
7*(3'x+2'y)'e*(1+5)'z	x=3; y=3+2; e=7*(3+2); z=7*(3+2)*(1+5);
a+1'x+b*(c-d'y)'z	x=a+1; y=c-d; z=a+1+b*(c-d);
-----------------------------------------------------------------------


STATEMENT EVALUATION (Enter key or = key)

The statements are separated with ;  (Semicolon). You can enter as many
statements as will fit on one line. When <Enter> key is pressed (or =)
the statements are evaluated orderly from left to right until the current
statement is evaluated (i.e. statement under cursor). The last result
is then displayed. In order to evaluate all entered statements, press
<End> to move to the end of line then press <Enter>.

If an ERROR is found, a Question mark is shown and the cursor is placed
on the improper statement.


SKIPPING BETWEEN EXPRESSIONS

Press Control with Left or Right cursor key. The cursor will skip from
one to another expression, evaluating on each step everything to the
right, and displaying the value of the statement under cursor.

CLEARING LINE

The line is not normally cleared following evaluation. To evaluate and
clear the line hold Shift key and press <Enter>, or press F10. The line
is not cleared if an error was found during evaluation. In that case,
the cursor is placed on the bad statement.


SENDING RESULT TO APPLICATION ( F5, F6 )

PopCALC can send current result to the foreground application as a sequence
of keystrokes. The keystrokes are sent using CodeRunneR's Tiny Scheduler,
in order not to overflow some applications keystroke buffers. The next
keystroke is sent only when application accepts the previous keystroke,
thus the input speed depends on application. The number is sent exactly
as shown in the result field for Decimal radix. For Binary and Hex radix,
the output dependes on Function key used. F5 will produce C style output,
and F6 Assembler style output.



COMMAND LINE OPTIONS

Command line options allow you to set-up calculator in the desired mode of
operation when it loads up. The options should be separated by comma or
space. Followng is the table of options:

SWITCH	Default    DESCRIPTION
-------------------------------------------------------------------
  H		   Hex radix
  D	Yes	   Decimal Radix
  B		   Binary Radix
-------------------------------------------------------------------
  S	Yes	   Signed arithmetic
  U		   Unsigned arithmetic
-------------------------------------------------------------------
  L	Yes	   Word size 32 bits (long)
  I		   Word size 16 bits (int)
  C		   Word size  8 bits (char)
-------------------------------------------------------------------
 1 to 25	   Row for PopCALC window, greater on some monitors
-------------------------------------------------------------------



		NOTES ON SOURCE CODE


The source code on the diskette contains three C files PC.C, PCID.C and
PCIC.C as well as a file CR.H which is one of CodeRunneR's header files
and PCALC.MAP file containing all of PCALC.EXE public symbols. To link
the source code into an executable file, you will also need CR.LIB
which is CodeRunneR library. Microsoft C or Turbo C may be used (inquire
about other C compilers). If you don't yet have CodeRunneR, the source
and the MAP file will still let you do some minor customizations (like
screen colors, and startup defaults). You can patch these using DEBUG.
The CodeRunneR package contains the latest PopCALC source, as well as
five other utilities (including a Floating Point calculator, ASCII/Color
chart, .. and other usefull TSR-s).

File PCID.C contains startup screens and other initialization data. It
shows CodeRunneR's compressed screen image representation.

File PCIC.C contains main() and non-TSR portion of the code. It shows how
to eliminate startup code and data, and how to switch to TSR mode. It also
shows how to setup CodeRunneR's Tiny Scheduler.

File PC.C is the TSR part of PopCALC. It demonstrates how simple it
can be to write TSR-s with CodeRunneR. The bulk of its code is the
calculator engine, and a small fraction deals with TSR aspect. Most
of the TSR related functions are done by CodeRunneR. The scheduler
used to send keystrokes to the applications is CodeRunneR's Tiny
Scheduler which allows for simple one-shot events. The reason for using
scheduler is that some applications flush keyborad before each new key.
The scheduler adds new key into the buffer only if the buffer is empty.
