\ opg-docs 97.11.04 Wil Baden
\ Docs for OPG.  Reformatted for
\ Quartus Forth 99.3.5 NAB.

needs tools-ext

0 [IF] COMMENT Wil Baden  97-11-04
Comments 97-11-04

  Rev: 97-11-04  Allow multi-line 
  formulas.
  Rev: 97-12-06
  No `.` needed for floating point
  literal.
  Rev: 98-06-10  Simplify MACRO.

This is a implementation of Formula 
Translation.  It will translate 
Fortran-style assignments 
`varname=expr` and expressions 
`expr` to Forth.

There is just one end-user word 
`LET`.  The formula is terminated by 
`:`.  End-of-line can be used in console 
entry with most systems.

It can be used compiling or 
interpreting.  It is not state-smart.

An operand between {braces} will be 
treated as normal Forth.

The resulting translations are the 
natural expansions.
`
  LET a-b-c-d:
  a F@  b F@  F-  c F@  F-  d F@  F- 

  LET a*b-c*d:
  a F@  b F@  F*  c F@  d F@  F*  F-  
  
  LET (a-b)*(c-d):
  a F@  b F@  F-  c F@  d F@  F-  F* 
  
  LET x = -1:
  -1.E x F!
  
  LET x = (-b - SQRT(b*{FDUP}-4*a*c)) / (2*a): 
  b F@  FNEGATE  b F@  FDUP F*  4.E a F@  F*  c F@  F*  F-  FSQRT F-  
  2.E a F@  F*  F/  x F!  
`
If a function doesn't begin with `F` it 
will first look for it with `F` prefixed.

All numbers are floating point.  
Variables begin with a letter, 
continue with letters and digits, and 
are not followed by a left 
parenthesis mark.  Function-calls 
have the same form but are followed 
by a left parenthesis mark.  

The operators are:  `+`   `-`   `*`   `/`
`**` or `^`

Assignments are made with `=`.  
Multiple arguments of a function are
separated by commas.

Spaces are deleted before 
translation.

Variable `DEBUG` on will show code
being translated.

Let me know of any problems, 
please.

Thanks to Julian V. Noble for 
inspiration and guidance.  This 
program uses Julian's concept but 
not his implementation.  Thanks 
also to Marcel Hendrix for his ideas
for extending the system.

Examples of Use

Operator Precedence goes through 
the expression putting out operands
as it reaches them and saving 
operators.  Operators are put out when an operator of less or equal 
precedence is reached.  Thus higher 
precedence is performed before 
lower precedence.
`
FVARIABLE a  FVARIABLE b  FVARIABLE c  FVARIABLE x  FVARIABLE w

: test0   CR  LET b+c:  FE.
  CR  LET b-c:  FE.
  CR  LET 10000000*(b-c)/(b+c):  FE. 
;

LET b = 3:
LET c = 4:
test0

: test1   LET a = b*c-3.17e-5/TANH(w)+ABS(x):  CR  LET a: F. ;

LET w = 1.e-3:  LET x = -2.5:  CR CR  test1

FVARIABLE HALFPI
LET HALF PI = 2*ATAN(1):
LET HALF PI + {FDUP}: F.

FVARIABLE disc   ( Used for discriminant )

: quadraticroot   ( F: a b c -- r1 r2 )
  c F!  b F!  a F!   \ Pickup coefficients.
  LET disc = SQRT(b*b-4*a*c):  \ Set discriminant.
  LET (-b+disc)/(2*a), (-b-disc)/(2*a):  \ Put values on f-stack.
;

( Solve x*x-3*x+2 )
  LET quadratic root (1,-3, 2) : F. F.
( Find goldenratio )
 LET MAX(quadra ticroot (1,-1,-1)) : F. 

( You can also write ) 1.E -1.E -1.E quadraticroot FMAX F.

: factorial   ( n -- )( F: -- r )
  LET w = 1:  LET x = 1: 
  0 ?DO  LET w = w * x:  LET x = x + 1:  LOOP
  LET w: 
;
( Another way )
: factorial   ( n -- )( F: -- r )
   LET w = 1:  0 ?DO  LET w = w * { I 1+ S>D D>F }:  LOOP  LET w:
;
6 factorial F.  ( or ) LET factorial({6}): F.
`
The program uses Tool Belt words.  
These are included with the 
distributed source.
END COMMENT [THEN]
