.TH CEXPR 1carl CARL
.SH NAME
cexpr \- desk calculator with cmusic-compatable arithmetic functions
.SH SYNOPSIS
.B cexpr 
[
.B -e
]
[
.B expression
] ... [ < input ] > output
.sp
The -e flag suppresses the ?? quotation of undigestable expressions.
.SH DESCRIPTION
.B cexpr 
is a desk calculator which uses 
the same expression evaluator as does
.I cmusic(1carl).
It is thus useful for doing interactive calculations analogously
to the way those calculations will be interpreted by 
.I cmusic
(but see BUGS below).
.PP
.B cexpr 
first looks for any expressions on its command line.
If there are any, it evaluates them in turn.
If there are none, it reads its standard input for expressions.
Multiple expressions (blank-separated) are allowed on either the command line
or the standard input.  The standard input format can consist of
(possibly several) lines of (possibly multiple, blank separated) expressions.
When reading the standard input,
.B cexpr
is terminated with [CTRL]-D.
.SH Usage in Text Editors
.B cexpr 
can be invoked from your favorite text editor, passing one or more lines
with expressions on them to cexpr and capturing the result in their place.
For instance, in 
.I vi(1), 
if the cursor is on a line of expressions, the command
.RS .5i
:.!cexpr[RETURN]
.RE
will send the line to 
.B cexpr,
and replace the line with the results 
.B cexpr
produces.
.SH EXPRESSION TYPES
The following is derived from the current documentation about allowed
expressions in 
.I cmusic.
Please refer to current documentation about the capabilities of 
.I cmusic,
since
.B cexpr
tracks its capabilities.
.PP
Expressions may contain several types of operands and operators.  Some
operands and operators are available only in cmusic (these are
indicated in the description below).  The current list of expressions
is as follows:
.PP
NOTE: Expressions must not include blank spaces.
.SH OPERANDS:
.IP numbers		
Numbers may have three bases; all are of type float
whether they include a decimal point or not.
.RS .5i
.IP decimal
Any string of digits, which either includes a decimal
point, or which does not include a decimal point.
.IP hexadecimal
If a number does not include a decimal point and starts
with the characters 0x, then base 16 is interpreted.
.IP octal
If a number does not include a decimal point and
starts with the digit 0, base 8 will be interpreted.
.RE
.SH OPERATORS:
.IP PARENTHESES
Parentheses must balance, and may be used freely to establish
operator precedence.  Function arguments should be enclosed in
parentheses.
.IP UNOPS 
The following are unary operators available in expressions in order
precedence, with the first set of operators done before anything in the
second set.  Unary operations are done before binary operations, and
binary operations are done before post operations.
.RS .5i
.IP -
Unary minus, as in -3*5
.IP sin,cos,atan,ln,exp,floor,abs,sqrt,rand
These are the standard trigonometric functions sine, cosine, 
and arctangent, from the UNIX math library, as well as the 
natural logarithm, exponential, floor, absolute value, and 
square root functions.  Rand is a function which returns a 
random value between 0 and its (positive) argument.
.RE
.PP
BINOPS 
.PP
The precedence is as shown below: ^ and % are done before * and /,
and * and / are done before + and -.
.RS .5i
.nf
^,%
    (3^.5 means 3 to the .5 power; 397%17 means 397 modulo 17)
*,/
    (5*79.2 means 5 times 79.2; 9/5 means 9 divided by 5 (float result))
+,-
    (3+3 means 3 plus 3, 3-8 means 3 minus 8)
.fi
.RE
.PP
POSTOPS 
.PP
Post operators are done last. They general modify the resulting value
of the expression which preceeds them.
.RS .5i
.IP Hz  
converts frequency to increment; example: 100Hz = 100 * funclength / srate
(uses default funclength and prevailing srate) (cmusic only)
.IP sec 
converts period (time in sec) to increment;
example: 2sec = funclength / (2 * srate)
(uses default funclength and prevailing srate) (cmusic only)
.IP S   
converts samples to seconds at the current sampling rate;
example: 100000S = 6.103516 at 16K sampling rate.  (cmusic only)
.IP dB  
converts dB (logarithmic) to linear scale;
example: -6dB = 10^(-6/20) = 0.5 (approx.)
.IP K   
converts K to units;
example: 8K = 8 * 1024 = 8192
.IP k   
converts k to units;
example: 8k = 8 * 1000 = 8000
.IP Deg 
converts degrees to radians;
example: 180Deg = (180 / 360) * TWOPI = 3.14159
.IP MM  
converts metronome marks to seconds per beat;
example: 120MM = 60/120 = .5 seconds per beat.  (Now available in cexpr
as well as cmusic.)
.IP IS  
computes the sum of the first N inverse terms;
i.e., 3invs = 1 + 1/2 + 1/3. 0IS = 0 by definition. (cmusic only)
.SH DIAGNOSTICS
When
.B cexpr
encounters an error in an expression, it inserts the text of the
undecipherable expression in the output stream of evaluated expressions,
enclosed in question marks.
.B cexpr
takes one flag, 
.B -e
which suppresses this ?? quotation.
.SH BUGS
The expression evaluator is not identical to that used in
.I cmusic,
but is the version from 
.B frmlib(3carl).
.PP
The field scanning mechanism uses 
.B gets(3)
which doesn't know about comma-separated fields, so these show up
as errors.
.SH SEE ALSO
cmusic(1carl), expr(3carl).
.SH AUTHOR
.I cmusic(1carl)
was written by F. R. Moore, 
.B cexpr
was hacked together by Gareth Loy.
