Coca - a COmbobox CAlculator with Expression Parser

Copyright (c) 1996-2005, Hans-Peter Sulzer (hps), Berlin, Frth/Bay

PLEASE READ LICENSE.TXT. PROGRAM IS (CURRENTLY, AS LONG AS IT IS IN
BETA STATE) NOT FREEWARE (except for versions from 0.99 onwards, but
even then you must first read licence.txt, cause there are some
restrictions)!

(
 email: peter_sulzer@b.maus.de (max. 64 KByte per day from one sender!!!)
 SORRY: this address is currently not checked, don't even know, if it
 still exists.
)

Snail Mail:
Heiligenstrae 41
90762 Frth
Germany

If you write, please insert a self addressed envelope AND international
post reply coupons else I won't reply. Or include your e-mail address
and I will reply - if no SPAM of course ;-)



Short Description:

The calculator supports normal mathematical expressions in normal
mathematical infix notation (sorry, currently no support for
postfix notation as e. g. used by HP pocket calculators) including
braces and commonly used scientific functions. The normal
mathematical precedence of operators is used.


Important note:
I use another default font for the WPS: "9.WarpSans Bold". With
the normal used System font (AFAIK 12. System Proportional) the
font is to large for some buttons. You can change the default
font for the WPS with an Ini-Editor: File OS2.INI Section (called
Applications in INIMAINT) PM_SystemFonts: Add a new key with
name DefaultFont and assign the value "9.WarpSans Bold" (exactly
as written in the font palette) an append an ASCII Zero ('\0')!!!
Restart OS/2.


General:

Enter any expression (see below) into the entry field of the
combo box and press the ENTER key on your keyboard. Any expression
is also added to the listbox of the combobox, except if the
expression is already in the listbox (exactly, including spaces
and case), in which case the old expression is deleted in the
listbox and inserted as the first entry. Old expressions can
also be accessed by simply pressing the "Cursor Down" key (key
with a pointing down arrow) on your keyboard. The windows version
even pops down the listbox when pressing "Cursor Down" and you
can navigate in the listbox with "Cursor Down/Up" (if possible,
I will implement this also in the OS/2 Presentation Manager version).

New in Version 0.9 onward: Added a "virtual keyboard", so that the
calculator can now be operated fully with the mouse. This gives (at
least on OS/2 Warp 4) a rudimentary support for speech control with
VoiceType. Version 1.0 currently (2005 Mar 27) only available for
OS/2.  H I N T : You can of course click into the entry field of
the combo box to move the cursor or mark a selection, i. e. use
the standard OS/2 Presentation Manager editing facilities for
edit fields.

Per default the result is automatically copied into the clipboard.
This means you can insert the result in any program which supports
the clipboard via the key combination <SHIFT-INS>. If you don't like
the automatic insertion into the clipboard, clear the marker in
the checkbox "Autoinsert result into clipboard". Even than you
can use the clipboard: Mark the result (e. g. <ALT-SHIFT-HOME>, is
<Alt-Pos1> on German keyboards or use the mouse) and press
<CTRL-INS> (<Strg-Einfg> on German keyboards) to copy it into the
clipboard.

The history currently holds up to 40 expressions. I can increase
this if there is a need - write. Expression history and window
position/size are currently not saved when exiting the program. I
will change this in a future version. Currently it is also not
possible to resize the window, albeit the program is prepared for
this (I create all elements of the window myself and don't use
resources for this) - in a future version the window will be
resizable and the combobox will therby change its size in x and
y direction (including the height of the listbox).

If you click the "About Coca ..." button, you will find 
some interessting information ;-)


Expressions:

Consists of normal mathematical expressions, i. e. numbers, operators,
functions and variables.


Numbers:

The separator of the fractional part is the fullstop (point) (!!!),
not the comma (sorry Germans - I am German) - it would be a lot of
work to change this, as all C/C++ functions assume the fullstop.
Also I will sometimes implement functions with more than one
argument. As the separator for argument is the comma, it would
really be complicated to use the comma as fractional part
separator). Exponential form e. g. 1.321E2 for 132.1 is also
supported. In this case "e" may be upper or lower case (e or E).
In most (all?) other cases, e. g. variable names, the case is
significant (!!!). E. g. the predefined variable "pi" is only
accessible with "pi" not with "PI".

Some examples of correct numbers:

1         is 1
1.        is 1
1.7       is 1.7 (1,7 in Germany)
1.7E2     is 1.7*10^2 (i. e. 170)
-1        is -1
0.1       is 0.1 (1/10)
.1        is 0.1, i. e. an alternative form of "0.1"

Some examples of false numbers:

1,3       use the fullstop to separate the fractional part
1. 4      no spaces allowed in a number
1.7 E 2   no spaces allowed in a number
- 1       no spaces allowed between sign and number
          (but you can use 0 - 1)


Operators:

Add                 +
Subtract            -

Multipy             *
Divide              /

Power               ^

Open Bracket        (
Close Bracket       )
(Brackets may be nested to any depth - or correct, until a
stack overflow will occure ;-) The parser is working recursivly)


Variables:

The parser supports variables. To set a variable use:

variablename=EXPR

where "EXPR" is any expression, e. g. "sin(30)" or simply 1.
The number of variables and the length of variable names are
not limited (but the length of an expression! AFAIK 1000 chars).
An expression may of course itself include variables, e. g.
"var=3*variablename" is OK. The case of variablenames is
significant (!!!). I. e. "Var" is another variable than "var".

The following variables are preset:

pi      the circle number (3.14...)
e       the base of the natural logarithm (2.71...)


Supported Functions:

Sine                    sin(x)
Cosine                  cos(x)
Tangent                 tan(x)
Arcussine               asin(x)
Arcuscosine             acos(x)
Arcustangent            atan(x)
(All goniometric functions currently assume the angle in degree
and return result in degree)

Natural Logarithm       ln(x)
Decadic Logarithm       log(x)

Square Root             sqrt(x)
    H I N T :   To calculate e. g. the third root of 8 use 8^(1/3)
                which will result in 2.

Sine Hyperbolicus       sinh(x)
Cosine Hyperbolicus     cosh(x)
Tangent Hyperbolicus    tanh(x)

Absolute Value          abs(x) // maybe usefull with variables


Some examples for correct expressions:

3*4                          12
8^(1/3)                       2 (third root of 8)
3*(2+sin(30))                 7.5
3 * ( 2 + sin (30) )          7.5
myvar=3*(2+sin(30))           sets variable "myvar" to 7.5
myvar                         7.5 (if myvar holds the value 7.5)
4*myvar                      30 (if myvar holds the value 7.5)
3+var=3*4                    15 and sets var to 12 (I'm really
                              surprised, that this works :-) ).
Warning: 3+xyz=(3*4)+abc=5*2 sets variable xyz to 22 NOT TO 12
as you may expect, i. e. the assignement operator always assigns
the rest of the expression. You can change this by using brackets:

3+(xyz=3*4)+abc=5*2          25 and sets xyz to 12


Some examples for incorrect expressions:

1/0                           Divide by zero (not defined)
3+(4*                         Missing closing bracket (parser
                              expected a token and found end
                              of expression).
var=                          An expression must follow (the
                              error message "Expecting a primary"
                              from "Coca" is wrong, you may enter
                              also a whole expression - I should
                              correct this).


Known Bugs:

When using an undefined (undeclared) variable in an expression
for the first time, you get (of course) an error message. But
after this first access, the variable is automatically defined
and its value is set to 1. The fault is in the function
"name *look(const char *p,calcdat *calc,int ins)" in file
"table.cpp" after "if (look == LookSymbol) ..." where the
function should return if the condition is true (i. e. an
error is output). This error has been detected 2005 Feb 26,
when trying to understand my program again, for porting it
to Symbian ;-) It is not so easy to correct this error, cause
I must go deep inside the parser (written 1995 or so) and
so I was lazy and documented this bug (which I have detected
shortly!) ;-)


calc.exe:
a VIO (command line) version of Coca. You can start it
interactivly with "calc" from an OS/2-command line window.
To end the calculator enter a fullstop and press enter.
Alternativly you can call it with an expression (e. g.
in batch mode) with e. g.:

calc 3*4

In this case you can use the history of the OS/2 command
line window.


Some Notes:

The program has been tested and I found that it calculates
expressions correctly and it hasn't crashed yet :-) Of course
a lot is missing yet (e. g. radio buttons to select between
degree and radian for goniometric functions), functions are
missing (e. g. inverse hyperbolic functions). The icon is ugly
(now corrected, the Coca-Icon is not perfect, but much better
than the old Calculator Icon), the window cannot be resized (this
will be changed), ...

You perhaps may help to add features. If you e. g. need a function,
just write it (in C++) and send it to me, I will include it, if
you will also tell me exactly for which values of x it is defined.
Please keep in mind that the parser currently supports only functions
with one argument. The support for functions with more than one
argument requires a fundamental change in the parser (but I already
have an idea and it will perhaps be implemented).

I'm planning to add support for hexadecimal, octal and binary
numbers. What syntax should be used? As in C (then what for
binary numbers?), special chars (e. g. '&' in front of number
for hexadecimal numbers), or something else (not letters as
these are reserved for the variables and functions).

But besides of all the above restrictions the calculator is now
surely in a usefull state, and perhaps better than many other, even
commercial calculators, because you may enter a whole expression
and you have a history - enjoy.

If you have any suggestions please feel free to write. The
following enhancements are already planned by me (in addition
to the features meantioned above):

- Saving position (and size) of the window
- Saving the history (perhaps even different histories)
- Saving the variables (arrggghhh I have to go deep inside
  the parser)
- Allow deletion of variables (arrggghhh ...)
- Adding buttons (similar to a keyboard), so that the calculator
  may be controled fully with the mouse. Means also a rudimentary
  support for speech control with VoiceType. Done with version 0.9
  which is (2005 Mar 15) available (only) for OS/2.
- Full support for VoiceType speech control (I need documentation
  and toolkits which support VoiceType development, where may I obtain
  them - for IBM VisualAge C++ Version 3.0).

[END OF FILE]

