Formula Version 0.30
		           Keith Packard
			 keithp@keithp.com

Formula is a system for working with simple numeric formula.  Formula
provides a simple programming language and run-time system which
automatically generates dialog boxes for providing formula parameters and
displaying formula results.

Install:

You ned to install both "MathLib.prc" and "formula.prc".  MathLib was
written by Rick Huebner (http://www.probe.net/~rhuebner/mathlib.html) and
provides a shared library of mathematical functions used by Formula.

Usage:

Enter a Formula program into Memo Pad making sure that it starts with a name
in double quotes (e.g. "Mortgage").  Formula looks for any Memo Pad entries
in this format to compile.

Switch to formula and select 'Compile' from the menu.  Any Memo Pad entries
starting with a name in double quotes will be listed.  Select the
appropriate program and hit 'Ok'.

All of the compiled programs are available in the pull-down where the
catagory menu is found in other applications, the upper right corner
of the screen.  Any of the non-private functions can be selected using
the other pull-down.

Enter the required values and hit 'go'.  The resulting values will
be displayed.  Tap the screen to abort execution.

Language:

	<program>: <externs>
	
	<extern>:
		Name = Number ;
		
		define [private] Name ["label"] <outputs> <inputs>
		{
			local <decls> ;
	
			<statments>
		}
	
		declare Name  <outputs> <inputs> ;
	
	<outputs>:
		( <decls> )
		*

'*' means that the outputs are the same as the inputs; i.e. use the
same values for input and output.
	
	<inputs>:
		( <decls> )
	
	<decls>: 
		<decl> [ , <decl> ... ]
	
	<decl>: 
		Name [?] ["label"]

A '?' indicates that this value is optional; i.e. may be left unset.  Using
an unset value generates a run-time exception.
	
	<statement>:
		while ( <expr> ) <statement>
		if ( <expr> ) <statement> [ else <statement> ]
		do <statement> while ( <expr> );
		for ( [<expr>] ; [<expr>] ; [<expr>] ) <statement>
		return ;
		break ;
		continue ;
		<expr> ;
		;
		{ <statements> }

	<expr>: Name
		Name ++
		Name --
		++ Name
		-- Name
		? Name				Was this parameter set?
		Number
		( <expr> )
		<expr> + <expr>
		<expr> - <expr>
		<expr> * <expr>
		<expr> / <expr>
		<expr> // <expr>		integer division
		<expr> % <expr>                 remainder (sigh)
		<expr> ^ <expr>                 exponentiation
		<expr> < <expr>
		<expr> <= <expr>
		<expr> == <expr>
		<expr> != <expr>
		<expr> >= <expr>
		<expr> > <expr>
		<expr> && <expr>                boolean and
		<expr> || <expr>                boolean or
		<expr> & <expr>                 bitwise and
		<expr> ^^ <expr>                bitwise xor
		<expr> | <expr>                 bitwise or
		~ <expr>			bitwise not
		! <expr>			boolean not
		- <expr>
		Name ( [<expr>] )
		<expr> = <expr>
		<expr> += <expr>
		<expr> -= <expr>
		<expr> *= <expr>
		<expr> /= <expr>
		<expr> //= <expr>		integer division
		<expr> %= <expr>
		<expr> &= <expr>
		<expr> |= <expr>
		<expr> ^= <expr>		exponentiation
		<expr> ^^= <expr>		bitwise xor
		<expr> , <expr>

This language is a bit different from the usual; it allows functions
to return more than one value, in fact it allows any expression
to produce more than one value.  The ',' operator doesn't simply execute
the expressions and discard all but the last value, all values are saved
and the result assigned to a list of names, e.g.:

	a,b = 1,2;

assigns 1 to 'a' and 2 to 'b'.  This makes it very easy to create functions
which produce more than one value.

To return values from functions, assign them to the output variables
(like Pascal):

	define fact (f) (i)
	{
		if (i)
			f = i * fact(i-1);
		else
			f = 1;
	}

Labels provide a way to annotate the user interface with more descriptive
terms, while still allowing reasonable variable names within the functions.

Builtin functions:

	log(v)		log base e(v)
	exp(v)		e^v
	sin(v)		v in radians
	cos(v)
	tan(v)
	asin(v)
	acos(v)
	atan(v)
	random()	returns random value 0 <= random() <= 1
	srandom(v)	sets random seed, 0 <= v <= 1
	floor(v)	round v towards negative infinity
	ceil(v)		round v towards positive infinity
	frexp(v)	returns two values m, e such that m * 2^e == v
	ldexp(m,e)	returns m * 2^e

Things left to do:

	Arrays.  I haven't found any need for them yet, but I'm sure
someone will.

	Strings.  Always useful.

The Legal Stuff

Copyright © 2000 Keith Packard

Permission to use, copy, modify, distribute, and sell this software and its
documentation for any purpose is hereby granted without fee, provided that
the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation, and that the name of Keith Packard not be used in
advertising or publicity pertaining to distribution of the software without
specific, written prior permission.  Keith Packard makes no
representations about the suitability of this software for any purpose.  It
is provided "as is" without express or implied warranty.

KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.

Keith Packard
keithp@keithp.com
http://keithp.com/pilot/formula