.\" gexpr.man, by Guido Gonzato		-*- nroff -*-
.\" 7 January 2000
.\" Process this file with
.\" groff -man -Tascii gexpr.1
.\"
.TH GEXPR 1 "May 2001" "GEXPR 2.0.2"

.SH NAME
gexpr \- handy shell calculator

.SH SYNOPSIS
.B gexpr 
[ options ] \fIexpression\fP

.SH DESCRIPTION
\fBgexpr\fP is an expression parser that can be used as a simple
command-line calculator, as in \fBgexpr 'sin(pi/4)*sqrt(4)'\fP, or to add
floating point math to shell scripts. It is meant to be an alternative to
\fBbc\fP (1), being less powerful but lighter and much more intuitive. It
also provides a few nice features of its own.

If an expression is given as argument, it must be protected from the shell
using quotes as in the example above. If you fail to do so, parentheses will
be interpreted and the * character will be expanded by the shell, wreaking
havoc. Using double quotes " " is necessary if you want to use shell
variables within \fIexpression\fP.

\fBgexpr\fP supports the usual arithmetical operators \fI + - * / \fP,
the relational operators \fI < <= > >= == != \fP, and all the standard C
mathematical functions apart from \fIfrexp\fP (3) and \fImodf\fP (3), which
cannot be fully implemented since they actually return two values. In
addition, \fBgexpr\fP provides the constants defined in math.h (M_PI, etc),
the \fIfact(n)\fP function, which returns the factorial of \fIn\fP, and the
\fIrnd(n)\fP function, which returns a random number between 0 and \fIn\fP.

A nice feature of \fBgexpr\fP is the possibility of using other bases than
10. For instance, this expression is allowed:

$ gexpr "0x10 + 0b1010 + 010"
.br
34
.br
$ _



the prefix "0x" denotes numbers written in base 16, "0b" numbers in base 2,
and "0" octal numbers. 

The command "base nn" is used to display the results in a base between 2 and
16. Example:

gexpr> base 16
.br
output base is now 16
.br
gexpr> 256 * 2
.br
200
.br
gexpr> _

The command "decimals nn" (or "dec nn") specifies the number of decimal
positions. Example:

gexpr> PI
.br
3.1415926525
.br
gexpr> dec 20
.br
decimal positions now 20
.br
gexpr> PI
.br
3.14159265258979311740
.br
gexpr> _

.SH COMMANDS
.LP
.TP 8
.B base \fP
specify the output base.
.TP 8
.B dec(imals) \fP
specify the number of decimals (default: 10).
.TP 8
.B help \fP
display a list of functions, constants, and commands.
.TP 8
.B q(uit) \fP
quit the program.


.SH OPTIONS
.LP
.TP 8
.B \--help, \-h \fP
display a short help.
.TP 8
.B \--base n, -b n \fP
output results in base n.
.TP 8
.B \--no_prompt, -n \fP
don't display the gexpr> prompt.

.SH EXAMPLES
gexpr 2 + 10 / 2
.br
gexpr "sqrt(5) < log(10)"
.br
echo "sqrt(2)/2" | gexpr -n
.br
gexpr "sin($X) - tan($Y)"
.br
gexpr "$X + ($Y)*log10(${ZZ})"

This is an interesting use of \fBgexpr\fP in a shell script:

#!/bin/sh
DEC=`echo "M_PI_2" | gexpr -n`
EXA=`echo "M_PI_2" | gexpr -n -b16`
echo "Pi/2 is $DEC (or $EXA in hexa)"

Another example:

#!/bin/sh
.br
X=0
.br
while [ `gexpr "$X < 10"` = 1 ]
.br
do
.br
  X=`gexpr "$X + 0.2"`
.br
  echo $X
.br
done

.SH BUGS
It is awfully slow and its use cannot replace a "real" programming language
supporting floating point math.

Most errors are trapped but some are not, like overflows and underflows. For
example, on the Linux box it was written on \fBgexpr\fP overflows when the
result exceeds about 1.797e+308.

It would be nice to add command-line editing. This would make \fBgexpr\fP
quite bigger, though.

.SH AUTHOR
Guido Gonzato <ggonza@tin.it>

.SH "SEE ALSO"
\fBexpr\fP (1), \fBsh\fP (1), \fBbc\fP (1)