---------------------- Programming in MathPad

-- The basic MathPad language is intended to be mathematical rather than
procedural. Equations can be written and evaluated in a natural way that does
not really require any programming. There are however some handy numerical
algorithms that do require some procedural operations.

-- MathPad does not have all the handy features of a programming language like C
or Pascal but it does have all the essential elements needed to do programming.

-- The assignment operator.
-- It is very important to understand the difference between = and :=. The =
statement gives a definition and does not perform any calculation. It is
analogous to a function definition in C or Pascal.

-- MathPad makes two passes over the text. The first pass saves all the
definitions. The second pass evaluates statements in order.

  a:7.00;    -- look at definition of "a" and perform calculation.
  a = b+2    -- define "a" (on pass 1)
  b = 5      -- define "b" (on pass 1)

-- The := operator replaces any definition of the left hand variable with the
calculated value of the right hand side.

  c:?;       -- there is no definition for "c"
  c:= b+2:;  -- perform calculation. save result in "c"
  c:7.00;    -- access the saved value. no calculation performed
  b:=10:;    -- change value of "b"
  a:12.00;   -- calculate "a" using new value of "b"
  c:7.00;    -- value of "c" does not change

-- Normally the destination of := is a symbol that does not have any =
definition. It is sometimes useful to have an = definition calculate an initial
value but remember that once := is used the definition will be erased.
-- Since := is sequential and = is not, it is possible (but not recommended) to
write things that look rather confusing.

  d:=d+1:
  d = 3
  d:4.00

-- Entire arrays can be assigned if they are finite (and there is enough
memory). Individual array elements can be assigned in limited cases. A single
numeric value can be assigned to an element of an array that has previously been
initialized by assignment.

 A := {{1,2,3,4},{5,6,7,8}}:
 A[1,2] := 0:
 A:{{1.00,0.00,3.00,4.00},{5.00,6.00,7.00,8.00}}

-- Some symbols are not allowed as := destinations. Array definitions with
explicit indexes can not be assigned to. Also special symbols such as the plot
variable X or sum() variables can not be assigned to.

   B[i]=i
-- B:=3:   -- is not allowed


---------- The comma operator
-- MathPad's functional approach deals with expressions and does not use blocks
containing sequences of statements. However, the comma operator can be used to
perform a sequence of operations. Parenthesis group the sequence into a single
expression.
-- The first purpose of the comma operator is to separate conditional "when"
clauses. The result will be the value corresponding to first condition in the
list that evaluates true.

  select(s) = a when s=1, b when s=2, c when s=3
  select(1):12.00;  select(2):10.00;

-- The meaning of the comma operator is extended to allow any expression (not
just when clauses). The result will be the first item in the list with a true
"when" clause or the first expression that evaluates to a known value.
Evaluation of an assignment performs the side effect only and does not result in
a known value. This allows a sequence of assignments to be done simply by
separating them with commas.

  b:=b+1, c:=b, a:13.00
  b:11.00;  c:11.00

-- The double comma operator
-- In cases involving assignments it is sometimes desirable to have evaluation
of a sequence continue even if a true when clause is encountered. For the double
comma, each expression is evaluated regardless of when clauses or known results.
The result of a double comma list is the last expression in the list. Single and
double commas can be mixed in the same list.

  absb(x) = b:=x,
           b:=-b when b<0,,  -- continue even if b<0
           b                 -- return value of b

---------- Iteration
-- The 'while' operator can be used to evaluate an expression repeatedly. The
while keyword follows the expression but the condition is checked before each
evaluation.

  factorial(n) = i:=1,
                 m:=1,  -- set up before starting loop
                 (i:=i+1,m:=m*i) while i<n, -- does nothing if n<=1
                 m      -- return final value for m

  factorial(1):1.00;  i:1.00;  m:1.00
  factorial(2):2.00;  i:2.00;  m:2.00

-- Nested while loops are fine but remember that all := variables are global so
don't try using 'i' as the index for both an inner and outer loop.

-- sum(), plot and table can also be used to perform iteration. The following
examples all evaluate dostuff() n times while stepping its parameter from 1 to
n. dostuff() can be any expression and can contain anything including :=.

  dostuff(x) = (ct:=1,1) when x=1,
               ct:=ct+x, ct
  n=5

  sum(dostuff(x),x,1,n):35.00;  -- Note: sum() will stop on unknown

  Xmin=1; Xmax=n; Xsteps=n
  plot dostuff(X)

  Nmin=1; Nmax=n; Nsteps=n
  table dostuff(N)
       1.00
       3.00
       6.00
      10.00
      15.00

-- Both plot and table evaluate their expression extra times at the 1st value in
order to determine array dimensions. To work properly dostuff() must reset its
initial state based on its parameter.
-- Using plot with expressions that have side effects can be tricky. If the plot
expression is an {x,y} array it gets evaluated twice per plotted point (once for
the x coord, once for the y coord). It is best to generate values based on the
independent variable rather than based on only on previous values.


---------- Debugging
-- It may be helpful to create a debugging function to save values during
evaluation. The following routines will save a sequence of up to nmax values in
the array dbgdata.

  startdbg(nmax) = dbgdata:= 0/0[:nmax],-- initialize array
                   ndbg:=0

  dbg(val) = ndbg:=ndbg+1,
             dbgdata[ndbg]:=val 


-- try looking at the values of the "ct" global during dostuff() summation.

  startdbg(10):
  sum((dbg(ct),dostuff(x)),x,1,n):35.00;

  ndbg:5.00;      -- 5 values were saved

  table dbgdata[:ndbg]
      15.00
       1.00
       3.00
       6.00
      10.00