Eval 3.20

Copyright © 1994, 2002/2004 Juan M. Aguirregabiria. All rights reserved.
Eval can be freely used and distributed, but you cannot sell it.

To contact the author:<wtpagagj@lg.ehu.eus>
See also http://tp.lc.ehu.eus/jma.html

Eval is a mathematical expression evaluator written in Java.
It should work on any computer system supporting Java 1.3 or higher (see Installing Eval).
It is useful for quick computations on the command line, and more complex calculations in a script or batch file.

Index

Installing Eval
Using Eval
Exiting Eval
Graphics shell
Expressions ( Assignments, Operators, Functions, Control functions)
BNF description of the compiler
Error list
External functions
Acknowledgments
Bugs, suggestions, ...

Installing Eval

Eval distribution contains the following files:

The Java archive file eval.jar that contains the executable code.
The HTML file eval.html and the image eval.jpeg that contain the documentation (which you can see or print in your favorite web browser) and is displayed in the right panel of the main window, when evaluating ? or after using F1.
Optionally you may want to load also the file external.txt to the installation directory and rand.java to a subdirectory called rand.

To install the program just copy these files to any directory in your system. To uninstall the program, just delete all these files.

Notice that you need java 1.3 (or better) to run Eval. You can get a free distribution of the Java Runtime Environment from Sun: http://java.sun.com/j2se/

Using Eval

Eval must be run from its installation directory by means of one of the following commands (of course, you can use a DOS batch file or a Unix shell script to automatically change to the right directory and issue the command):

java -classpath eval.jar eval.eval
Starts the graphics shell described below. This is the easiest way to use the program.

java -classpath eval.jar eval.eval ?
This documentation will be open in a web browser window.

java -classpath eval.jar eval.eval expression
The expression will be evaluated and its value returned. Useful to use in scripts and batch files.

java -classpath eval.jar eval.eval -
Start Eval in the command line mode. The user will be prompted (>>) to enter expressions, which will be evaluated and displayed. Using a line with a single ? will open the help screen.
Enter a blank line to end the session.

java -classpath eval.jar eval.eval <filename
The lines from filename will be read and (if they are not void and do not start by #) evaluated and returned.

Except in the first two cases the output of Eval will be directed to the standard output device and can be redirected to any output file appending to the command line > output, as usual.

Exiting Eval

In the graphics shell press Alt+F4 or use the menu File/Exit.
In the command line mode enter a blank line.

The graphics shell

The main parts of the graphics shell are displayed in the following figure:

`Expression`	You type here the mathematical expression to be evaluated
`Value`	When a complete expression is written in `Expression` its value is displayed here and can be copied with `Ctrl+R`. This feature (which has side effects, such as changing the value of variable in expressions like ...a = ...) is turned on and from for the menu Options/Continuous update.
`Evaluate` `button`	Click this or press Enter to have the current `Expression` evaluated and copied to `Results`
`Results`	List of results. You may copy (some of) them with `Ctrl+C` or send them to a external file with `Ctrl+S`
`Help window`	The documentation file. Press `F1` to get it displayed in your web browser.

The menu system has the following structure:

`Menu`	Short cut	Action
`File`
`Open`	`Ctrl+O`	Read input expressions from an external file
`Save`	`Ctrl+S`	Save the `Results` in an external file
`Save as`		Save the `Results` in an external file under a new name
`Exit`	`Alt+F4`	Quit the program
`Edit`
`Cut`	`Ctrl+X`	Copy currently selected text to the clipboard and erase it
`Copy`	`Ctrl+C`	Copy currently selected text to the clipboard
`Paste`	`Ctrl+V`	Copy text from the clipboard
`Delete`	`Delete`	Delete currently selected text
`Copy result`	`Ctrl+R`	Copy `Value` to clipboard
`Print new variables`		List variables defined in Assignments
`Look and feel`		Select the program look and feel from the following list
`...`		(Notice that in some Linux distributions the options Metal and, especially, Windows are buggy in Java 1.3)
`Options`
`Continuous update`	`F1`	Toggle On/Off the continuous update of `Value`
`Help`
`Documentation file`	`F1`	Display this documentation in your web browser

Expressions

A line may contain one or several expression separated by ,; or $. If $ or , are used the corresponding output will not be printed. If ; (or nothing) is used the result will be printed (unless printall(0) has been used; see Control functions).

Any character following a # will be ignored. This allows introducing comments in the line.

Blank lines are ignored.

An expression is formed, in a very standard way, by the following items pasted together or separated by spaces:

Assignments
Numbers: -2, 1E-12, -1.02e2, .2, etc.
Operators
Parenthesis to change precedence.
Predefined constants:
degree = pi/180
e = E = 2.71828...
pi = PI = Pi = pI = 3.14159...
They are searched after user defined variables; so do not define a variable called e!
Functions.
Control functions.
The last expression under the name last.
The last 10 expressions as ans[n] (or ansn). The index n is incremented from 0 to 9 with each expression evaluation.
User defined variables defined in Assignments.

Assignments

You can change the value of variables by using:
variable = value
where value is an arbitrary expression (even another assignment) and variable may be any predefined variable (last, ans[0], . . ., ans[9]) or any of the user defined variables. If the variable is not found it will be added to the user defined variables (they are listed by using the menu Edit/Print new variables or, in the command line mode, when the program exists if printnew(1) is used anywhere). The spaces around the = symbol are optional.

The result of an assignment statement is value and can be used in complex expressions, like the following ones:
a1 = a2 = 2
a1 = (a2 = 3)*3

Notice that if Options/Continuous update is On, undesirable side effects may happen. For instance, you type
a = 1 + 2
and the press <Enter> so that the new variable and value are stored in memory. Then erase the last two symbols, so that Expression looks as
a = 1
When this is silently evaluated to be shown in Value, the new value 1 is assigned to a!

Operators

Mathematical operators:
+ addition
- subtraction or negation
* multiplication
/ division
÷ = div integer division: x÷y = [x/y]
% = mod remainder: x%y = x/y-[x/y]
^ = pow exponentiation: x^2 = x*x
Relational operators return 1/0 for TRUE/FALSE:
< less than
<= less or equal
> greater than
>= greater or equal
== equal to
!= not equal to
Logical operators return 1/0 for TRUE/FALSE:
&& and
|| or
! not
(Only the operands necessary to establish the result are evaluated.)
Conditional operator:
c ? t:f returns t if c!= 0, f if c== 0.
It is equivalent to if(c,t,f)

Operator precedence, from lowest to highest:

?: (Conditional operator)
||
&&
== !=
< <= > >=
+ - (binary)
* / ÷ %
^
! + - (unary)

Functions

Case is ignored.

One-variable functions:
abs = fabs
acos = arccos
acosh = arccosh
asin = arcsin
asinh = arcsinh
atan = arctan (Result in [-pi/2,pi/2].
atanh = arctanh
ceil (ceil(x) = -int(-x))
chop returns 0 if abs(x) < 1e-10, otherwise returns x
cos
cosh
erf error function
erfc complementary error f.
exp
factorial (factorial(x) = x! = exp(lnGamma(x+1)))
floor = int (int(x) = E(x) = [x])
fracc (fracc(x) = x-int(x))
LambertW Branch 0 of the Lambert W function, real solution ofW(x) exp(W(x))=x for -1/e < x < infinity
LambertW1 Branch -1 of the Lambert W function, 2nd real solution ofW(x) exp(W(x))=x for -1/e < x < 0
ln = log natural logarithm
lnGamma natural logarithm of Euler Gamma function
log10 decimal logarithm
round nearest integer
sign = sgn= sign sign function
sin
single Returns the number rounded to IEEE single precision (6-7 digits and decimal exponents from -38 to 38)
sinh
sqr (sqr(x) = x*x = x^2)
sqrt square root
step Heaviside function (h(x) = 1 if x > 0, h(0) = 0.5, h(x) = 0 if x < 0).
tan
tanh
Two-variable functions:
arctan2 = atan2 (atan2(y,x) = atan(y/x), but result in ( (-pi,pi])
chop2 chop2(x,d) returns 0 if abs(x) < d, otherwise returns x
div (div(x,y) = [x/y] integer division)
hypot (hypot(x,y) = sqrt(sqr(x)+sqr(y))
mod (mod(x,y) = x % y)
pow (pow(x,y) = x^y)
random (random(x,y) = random number in (x,y). Use floor(random(a,b+1)) to select an integer from a to b.)
Three-variable functions:
random3 random3(t,x,y) returns the a random number in (x,y), just like random(x,y), but it remembers the values t,x,y, so that if the next call is done with exactly the same values it returns the same random number
Two multi-argument functions, max and min, which return, respectively, the largest and smallest of their arguments.
A special function, if, with two meanings:
if(c,t,f) returns t if c != 0, f if c == 0.
if(c,p,z,n) returns p if c > 0, z if c == 0 and n if c < 0.
if(c,t,f) is equivalent to (c) ? t : f.
Only c and the returned argument, which can be a full expression, are evaluated. This function can be seen as a simple control structure.

Control functions

The following control functions set some internal flags that control the output format:

precision(n) The output will use from 1 to n digits. Use n > 0 for sensible output. The default and maximum value is 16: higher values will give the same result as 16.

labels(n) The labels ans[n] (which are disabled if eval.eval expr has been used) will be disabled/enabled if n equals/is different from 0.

printall(n) The printing of each result will be disabled/enabled if n equals/is different from 0. By default the corresponding flag is enabled. If the program terminates in its command line mode with it disabled, the last value will be printed. This function is of not use in the graphics shell mode.

printnew(n) When the program exits from its command line mode all the new variables defined by the user in assignments will be displayed if n is non zero. In the graphics shell Edit/Print new variables must be used.

All these functions return the previous value of the corresponding flag. Their action takes place immediately.

BNF description of the expression compiler

This is the formal description of the grammar used by the expression evaluator:

expression ::= assignment | assignment ? expression : expression
assignment ::= or-expression | variable = expression
or-expression ::= and-expression {|| and-expression}
and-expression ::= equality {&& equality}
equality ::= relation | relation equality-operator relation
equality-operator ::= == | !=
relation ::= addend | addend relational-operator addend
relational-operator ::= < | > | <= | >=
addend ::= term {adding-operator term}
adding-operator ::= + | -
term ::= signed-power-factor {multiplying-operator signed-power-factor}
multiplying-operator ::= * | / | ö | %
signed-power-factor ::= power-factor | sign power-factor | ! power-factor
power-factor ::= factor | factor ^ signed-factor
signed-factor ::= factor | sign factor
factor ::= constant | variable | number | function | ( expression )
sign ::= + | -
variable ::= identifier | identifier [ integer ]
constant ::= identifier
number ::= digit {digit} . {digit} scale | digit {digit} . {digit} | digit {digit} scale | digit {digit} | . digit {digit} scale | . digit {digit}
function ::= identifier ( expression {, expression } )
identifier ::= letter {letter | digit}
integer ::= digit {digit}
letter ::= A | B | ... | Z | a | b | ... | z | _
digit ::= 0 | 1 | ... | 9
scale ::= E scale-factor | e scale-factor
scale-factor ::= digit {digit} | sign digit {digit}

Error list

Most errors can be easily understood in the context they happen. You can find in the following error list some hints to avoid them. If errors not listed below are reported, notify the author, please.

Compiler errors
Evaluation errors

Compiler errors

These errors are issued by the expression compiler when an incorrect Expression is encountered. The most probable location of the error is over the ^ sign.

`Message`	`Meaning`
`[ expected`	`ans` must be followed by `[`
`) expected`	A parenthesis is unbalanced
`] expected`	A bracket is unbalanced
`, expected`	Another argument must be provided
`Extra character(s)`	Some characters follow a complete expression. Maybe you forgot a parenthesis or an operator
`Index out of bounds`	Only `ans[0]` to `ans[9]` are available
`Invalid character`	T`he` character cannot be used in this context
`Invalid index`	It must be a constant number
`Unexpected end of expression`	Maybe an unbalanced parenthesis
`Unknown function`	Undefined or misspelled function
`Unknown identifier`	`Undefined` or misspelled variable

Evaluation errors

These errors may happen when evaluating numerical expressions.

Overflow 1/0 etc.
Invalid operation 0/0, asin(2), log(-1), etc.

External functions

The expression evaluator is able to use external functions defined by the user. The external classes must be listed in a file called external.txt and located in the installation directory where eval.jar is and from where the program must be invoked. For instance, create such a file containing the following single line:
expeval.bessel.bessel
Then using
java -classpath eval.jar eval.eval
will produce the following output before starting the graphics shell:
Loaded from expeval.bessel.bessel: BesselJ, BesselY, Besselj, Bessely, Bessel BesselK, AiryAi, AiryBi
This informs you that some Bessel functions (J_n, Y_n, j_n, y_n, I_n and K_n) and Airy functions (Ai and Bi) have been loaded and can be used.

You may easily write your own function, provided you have a Java compiler (a free compiler is available from Sun in http://java.sun.com/j2se/ where free environments are also listed; in fact, this program version has been developed by using the excellent free JBuilder 4 Foundation, JBuilder 7 Personal and JBuilder X Foundation from Borland: http://www.borland.com/downloads/)

One example, which may be used as template to write your own functions, is available with this distribution. Let us assume that you have loaded the rand.java file and installed in the rand subdirectory of the installation directory.

To compile the program use:
Unix: javac -classpath eval.jar rand/rand.java
Windows: javac -classpath eval.jar rand\rand.java
To compress the *.class files to a single file
Unix: jar cvf rand/rand.jar rand/*.class
Windows: jar cvf rand\rand.jar rand\*.class
To delete the *.class files:
Unix: rm rand/*.class
Windows: del rand\*.class
To inform Eval that the new class rand.rand must be loaded, add the following line to external.txt located in the installation directory where eval.jar is:
rand.rand
To run the graphics shell:
Unix: java -classpath eval.jar:rand/rand.jar eval.eval
Windows: java -classpath eval.jar;rand\rand.jar eval.eval
You will get the following output to indicate that two functions (rand and rand2) have been loaded:
Loaded from rand.rand: rand, rand2

To write your own functions, copy rand.java to a new directory and change its name to match that of the new directory. Then edit the file.

Acknowledgments

I am most grateful to A. Sancho who discovered a fatal bug in version 2.00.

Bugs, suggestions, ...

All comments, bug reports and suggestions to <wtpagagj@lg.ehu.eus> would be answered.