@menu
* Functions and Variables for Evaluation::
@end menu

@c -----------------------------------------------------------------------------
@node Functions and Variables for Evaluation,  , Evaluation, Evaluation
@section Functions and Variables for Evaluation
@c -----------------------------------------------------------------------------

@c NEEDS EXAMPLES
@c THIS ITEM IS VERY IMPORTANT !!

@c -----------------------------------------------------------------------------
@anchor{quote}
@deffn {Operator} '
@ifinfo
@fnindex Quote operator
@end ifinfo

The single quote operator @code{'} prevents evaluation.

Applied to a symbol, the single quote prevents evaluation of the symbol.

Applied to a function call, the single quote prevents evaluation of the function
call, although the arguments of the function are still evaluated (if evaluation
is not otherwise prevented).  The result is the noun form of the function call.

Applied to a parenthesized expression, the single quote prevents evaluation of
all symbols and function calls in the expression.
@c DUNNO IF THESE EXAMPLES ARE STILL NEEDED -- COVERED BY ITEMS UNDER "Examples"
E.g., @code{'(f(x))} means do not evaluate the expression @code{f(x)}.
@code{'f(x)} (with the single quote applied to @code{f} instead of @code{f(x)})
means return the noun form of @code{f} applied to @code{[x]}.

The single quote does not prevent simplification.

When the global flag @mref{noundisp} is @code{true}, nouns display with a single
quote.  This switch is always @code{true} when displaying function definitions.

See also the quote-quote operator @mxref{quote-quote, ''} and @mrefdot{nouns}

Examples:

Applied to a symbol,
the single quote prevents evaluation of the symbol.

@c ===beg===
@c aa: 1024;
@c aa^2;
@c 'aa^2;
@c ''%;
@c ===end===
@example
(%i1) aa: 1024;
(%o1)                         1024
(%i2) aa^2;
(%o2)                        1048576
(%i3) 'aa^2;
                                 2
(%o3)                          aa
(%i4) ''%;
(%o4)                        1048576
@end example

Applied to a function call, the single quote prevents evaluation of the function
call.  The result is the noun form of the function call.

@c ===beg===
@c x0: 5;
@c x1: 7;
@c integrate (x^2, x, x0, x1);
@c 'integrate (x^2, x, x0, x1);
@c %, nouns;
@c ===end===
@example
(%i1) x0: 5;
(%o1)                           5
(%i2) x1: 7;
(%o2)                           7
(%i3) integrate (x^2, x, x0, x1);
                               218
(%o3)                          ---
                                3
(%i4) 'integrate (x^2, x, x0, x1);
@group
                             7
                            /
                            [   2
(%o4)                       I  x  dx
                            ]
                            /
                             5
@end group
(%i5) %, nouns;
                               218
(%o5)                          ---
                                3
@end example

Applied to a parenthesized expression, the single quote prevents evaluation of
all symbols and function calls in the expression.

@c ===beg===
@c aa: 1024;
@c bb: 19;
@c sqrt(aa) + bb;
@c '(sqrt(aa) + bb);
@c ''%;
@c ===end===
@example
(%i1) aa: 1024;
(%o1)                         1024
(%i2) bb: 19;
(%o2)                          19
(%i3) sqrt(aa) + bb;
(%o3)                          51
(%i4) '(sqrt(aa) + bb);
(%o4)                     bb + sqrt(aa)
(%i5) ''%;
(%o5)                          51
@end example

The single quote does not prevent simplification.

@c ===beg===
@c sin (17 * %pi) + cos (17 * %pi);
@c '(sin (17 * %pi) + cos (17 * %pi));
@c ===end===
@example
(%i1) sin (17 * %pi) + cos (17 * %pi);
(%o1)                          - 1
(%i2) '(sin (17 * %pi) + cos (17 * %pi));
(%o2)                          - 1
@end example

Maxima considers floating point operations by its in-built mathematical
functions to be a simplification.

@c ===beg===
@c sin(1.0);
@c '(sin(1.0));
@c ===end===
@example
(%i1) sin(1.0);
(%o1)                          .8414709848078965
(%i2) '(sin(1.0));
(%o2)                          .8414709848078965
@end example

When the global flag @mref{noundisp} is @code{true}, nouns display with a single
quote.

@c ===beg===
@c x:%pi;
@c bfloat(x);
@c sin(x);
@c noundisp;
@c 'bfloat(x);
@c bfloat('x);
@c sin(x);
@c sin('x);
@c noundisp : not noundisp;
@c 'bfloat(x);
@c bfloat('x);
@c sin(x);
@c sin('x);
@c ===end===
@example
(%i1) x:%pi;
(%o1)                                 %pi
(%i2) bfloat(x);
(%o2)                         3.141592653589793b0
(%i3) sin(x);
(%o3)                                  0
(%i4) noundisp;
(%o4)                                false
(%i5) 'bfloat(x);
(%o5)                             bfloat(%pi)
(%i6) bfloat('x);
(%o6)                                  x
(%i7) 'sin(x);
(%o7)                                  0
(%i8) sin('x);
(%o8)                               sin(x)
(%i9) noundisp : not noundisp;
(%o9)                                true
(%i10) 'bfloat(x);
(%o10)                           'bfloat(%pi)
(%i11) bfloat('x);
(%o11)                                 x
(%i12) 'sin(x);
(%o12)                                 0
(%i13) sin('x);
(%o13)                              sin(x)
(%i14)
@end example

@opencatbox
@category{Evaluation}
@category{Operators}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{quote-quote}
@deffn {Operator} ''
@ifinfo
@fnindex Quote-quote operator
@end ifinfo

The quote-quote operator @code{'@w{}'} (two single quote marks) modifies
evaluation in input expressions.

Applied to a general expression @var{expr}, quote-quote causes the value of
@var{expr} to be substituted for @var{expr} in the input expression.

Applied to the operator of an expression, quote-quote changes the operator from
a noun to a verb (if it is not already a verb).

The quote-quote operator is applied by the input parser; it is not stored as
part of a parsed input expression.  The quote-quote operator is always applied
as soon as it is parsed, and cannot be quoted.  Thus quote-quote causes
evaluation when evaluation is otherwise suppressed, such as in function
definitions, lambda expressions, and expressions quoted by single quote
@code{'}.

Quote-quote is recognized by @mref{batch} and @mrefdot{load}

See also @mrefcomma{ev} the single-quote operator @mxref{quote, '} and @mrefdot{nouns}

Examples:

Applied to a general expression @var{expr}, quote-quote causes the value of
@var{expr} to be substituted for @var{expr} in the input expression.

@c ===beg===
@c expand ((a + b)^3);
@c [_, ''_];
@c [%i1, ''%i1];
@c [aa : cc, bb : dd, cc : 17, dd : 29];
@c foo_1 (x) := aa - bb * x;
@c foo_1 (10);
@c ''%;
@c ''(foo_1 (10));
@c foo_2 (x) := ''aa - ''bb * x;
@c foo_2 (10);
@c [x0 : x1, x1 : x2, x2 : x3];
@c x0;
@c ''x0;
@c '' ''x0;
@c ===end===
@example
(%i1) expand ((a + b)^3);
                     3        2      2      3
(%o1)               b  + 3 a b  + 3 a  b + a
(%i2) [_, ''_];
                         3    3        2      2      3
(%o2)     [expand((b + a) ), b  + 3 a b  + 3 a  b + a ]
(%i3) [%i1, ''%i1];
                         3    3        2      2      3
(%o3)     [expand((b + a) ), b  + 3 a b  + 3 a  b + a ]
(%i4) [aa : cc, bb : dd, cc : 17, dd : 29];
(%o4)                   [cc, dd, 17, 29]
(%i5) foo_1 (x) := aa - bb * x;
(%o5)                 foo_1(x) := aa - bb x
(%i6) foo_1 (10);
(%o6)                      cc - 10 dd
(%i7) ''%;
(%o7)                         - 273
(%i8) ''(foo_1 (10));
(%o8)                         - 273
(%i9) foo_2 (x) := ''aa - ''bb * x;
(%o9)                 foo_2(x) := cc - dd x
(%i10) foo_2 (10);
(%o10)                        - 273
(%i11) [x0 : x1, x1 : x2, x2 : x3];
(%o11)                    [x1, x2, x3]
(%i12) x0;
(%o12)                         x1
(%i13) ''x0;
(%o13)                         x2
(%i14) '' ''x0;
(%o14)                         x3
@end example

Applied to the operator of an expression, quote-quote changes the operator from
a noun to a verb (if it is not already a verb).

@c ===beg===
@c declare (foo, noun);
@c foo (x) := x - 1729;
@c foo (100);
@c ''foo (100);
@c ===end===
@example
(%i1) declare (foo, noun);
(%o1)                         done
(%i2) foo (x) := x - 1729;
(%o2)                 ''foo(x) := x - 1729
(%i3) foo (100);
(%o3)                       foo(100)
(%i4) ''foo (100);
(%o4)                        - 1629
@end example

The quote-quote operator is applied by the input parser; it is not stored as
part of a parsed input expression.

@c ===beg===
@c [aa : bb, cc : dd, bb : 1234, dd : 5678];
@c aa + cc;
@c display (_, op (_), args (_));
@c ''(aa + cc);
@c display (_, op (_), args (_));
@c ===end===
@example
(%i1) [aa : bb, cc : dd, bb : 1234, dd : 5678];
(%o1)                 [bb, dd, 1234, 5678]
(%i2) aa + cc;
(%o2)                        dd + bb
(%i3) display (_, op (_), args (_));
                           _ = cc + aa

                         op(cc + aa) = +

                    args(cc + aa) = [cc, aa]

(%o3)                         done
(%i4) ''(aa + cc);
(%o4)                         6912
(%i5) display (_, op (_), args (_));
                           _ = dd + bb

                         op(dd + bb) = +

                    args(dd + bb) = [dd, bb]

(%o5)                         done
@end example

Quote-quote causes evaluation when evaluation is otherwise suppressed, such as
in function definitions, lambda expressions, and expressions quoted by single
quote @code{'}.

@c ===beg===
@c foo_1a (x) := ''(integrate (log (x), x));
@c foo_1b (x) := integrate (log (x), x);
@c dispfun (foo_1a, foo_1b);
@c integrate (log (x), x);
@c foo_2a (x) := ''%;
@c foo_2b (x) := %;
@c dispfun (foo_2a, foo_2b);
@c F : lambda ([u], diff (sin (u), u));
@c G : lambda ([u], ''(diff (sin (u), u)));
@c '(sum (a[k], k, 1, 3) + sum (b[k], k, 1, 3));
@c '(''(sum (a[k], k, 1, 3)) + ''(sum (b[k], k, 1, 3)));
@c ===end===
@example
(%i1) foo_1a (x) := ''(integrate (log (x), x));
(%o1)               foo_1a(x) := x log(x) - x
(%i2) foo_1b (x) := integrate (log (x), x);
(%o2)           foo_1b(x) := integrate(log(x), x)
(%i3) dispfun (foo_1a, foo_1b);
(%t3)               foo_1a(x) := x log(x) - x

(%t4)           foo_1b(x) := integrate(log(x), x)

(%o4)                      [%t3, %t4]
(%i5) integrate (log (x), x);
(%o5)                     x log(x) - x
(%i6) foo_2a (x) := ''%;
(%o6)               foo_2a(x) := x log(x) - x
(%i7) foo_2b (x) := %;
(%o7)                    foo_2b(x) := %
(%i8) dispfun (foo_2a, foo_2b);
(%t8)               foo_2a(x) := x log(x) - x

(%t9)                    foo_2b(x) := %

(%o9)                      [%t7, %t8]
(%i10) F : lambda ([u], diff (sin (u), u));
(%o10)             lambda([u], diff(sin(u), u))
(%i11) G : lambda ([u], ''(diff (sin (u), u)));
(%o11)                  lambda([u], cos(u))
(%i12) '(sum (a[k], k, 1, 3) + sum (b[k], k, 1, 3));
(%o12)         sum(b , k, 1, 3) + sum(a , k, 1, 3)
                    k                  k
(%i13) '(''(sum (a[k], k, 1, 3)) + ''(sum (b[k], k, 1, 3)));
(%o13)             b  + a  + b  + a  + b  + a
                    3    3    2    2    1    1
@end example

@opencatbox
@category{Evaluation}
@category{Operators}
@closecatbox
@end deffn

@c NEEDS CLARIFICATION
@c VERY IMPORTANT !!

@c -----------------------------------------------------------------------------
@anchor{ev}
@deffn {Function} ev (@var{expr}, @var{arg_1}, @dots{}, @var{arg_n})

Evaluates the expression @var{expr} in the environment specified by the
arguments @var{arg_1}, @dots{}, @var{arg_n}.  The arguments are switches
(Boolean flags), assignments, equations, and functions.  @code{ev} returns the
result (another expression) of the evaluation.

The evaluation is carried out in steps, as follows.

@enumerate
@item
First the environment is set up by scanning the arguments which may
be any or all of the following.

@itemize @bullet
@item
@mref{simp} causes @var{expr} to be simplified regardless of the setting of the
switch @code{simp} which inhibits simplification if @code{false}.
@item
@mref{noeval} suppresses the evaluation phase of @code{ev} (see step (4) below).
This is useful in conjunction with the other switches and in causing
@var{expr} to be resimplified without being reevaluated.
@item
@mref{nouns} causes the evaluation of noun forms (typically unevaluated
functions such as @code{'integrate} or @code{'diff}) in @var{expr}.
@item
@mref{expand} causes expansion.
@item
@code{expand (@var{m}, @var{n})} causes expansion, setting the values of
@mref{maxposex} and @mref{maxnegex} to @var{m} and @var{n} respectively.
@item
@mref{detout} causes any matrix inverses computed in @var{expr} to have their
determinant kept outside of the inverse rather than dividing through
each element.
@item
@mref{diff} causes all differentiations indicated in @var{expr} to be performed.
@item
@code{derivlist (@var{x}, @var{y}, @var{z}, ...)} causes only differentiations
with respect to the indicated variables.  See also @mrefdot{derivlist}
@item
@code{risch} causes integrals in @var{expr} to be evaluated using the Risch
algorithm.  See @mrefdot{risch}  The standard integration routine is invoked
when using the special symbol @mrefdot{nouns}
@item
@mref{float} causes non-integral rational numbers to be converted to floating
point.
@item
@mref{numer} causes some mathematical functions (including exponentiation)
with numerical arguments to be evaluated in floating point.  It causes
variables in @var{expr} which have been given numervals to be replaced by
their values.  It also sets the @mref{float} switch on.
@item
@mref{pred} causes predicates (expressions which evaluate to @code{true} or
@code{false}) to be evaluated.
@item
@mref{eval} causes an extra post-evaluation of @var{expr} to occur.
(See step (5) below.)
@code{eval} may occur multiple times.  For each instance of @code{eval}, the
expression is evaluated again.
@item
@code{A} where @code{A} is an atom declared to be an evaluation flag
@mref{evflag} causes @code{A} to be bound to @code{true} during the evaluation
of @var{expr}.
@item
@code{V: expression} (or alternately @code{V=expression}) causes @code{V} to be
bound to the value of @code{expression} during the evaluation of @var{expr}.
Note that if @code{V} is a Maxima option, then @code{expression} is used for
its value during the evaluation of @var{expr}.  If more than one argument to
@code{ev} is of this type then the binding is done in parallel.  If @code{V} is
a non-atomic expression then a substitution rather than a binding is performed.
@item
@code{F} where @code{F}, a function name, has been declared to be an evaluation
function @mref{evfun} causes @code{F} to be applied to @var{expr}.
@item
Any other function names, e.g. @mrefcomma{sum} cause evaluation of occurrences
of those names in @var{expr} as though they were verbs.
@item
In addition a function occurring in @var{expr} (say @code{F(x)}) may be defined
locally for the purpose of this evaluation of @var{expr} by giving
@code{F(x) := expression} as an argument to @code{ev}.
@item
If an atom not mentioned above or a subscripted variable or subscripted
expression was given as an argument, it is evaluated and if the result is an
equation or assignment then the indicated binding or substitution is performed.
If the result is a list then the members of the list are treated as if they were
additional arguments given to @code{ev}.  This permits a list of equations to be
given (e.g. @code{[X=1, Y=A**2]}) or a list of names of equations (e.g.,
@code{[%t1, %t2]} where @code{%t1} and @code{%t2} are equations) such as that
returned by @mrefdot{solve}
@end itemize

The arguments of @code{ev} may be given in any order with the exception of
substitution equations which are handled in sequence, left to right, and
evaluation functions which are composed, e.g., @code{ev (@var{expr}, ratsimp,
realpart)} is handled as @code{realpart (ratsimp (@var{expr}))}.

The @mrefcomma{simp} @mrefcomma{numer} and @mref{float} switches may also be set
locally in a block, or globally in Maxima so that they will remain in effect
until being reset.

If @var{expr} is a canonical rational expression (CRE), then the expression
returned by @code{ev} is also a CRE, provided the @code{numer} and @code{float}
switches are not both @code{true}.

@item
During step (1), a list is made of the non-subscripted variables appearing on
the left side of equations in the arguments or in the value of some arguments
if the value is an equation.  The variables (subscripted variables which do not
have associated @mref{memoizing functions} as well as non-subscripted variables) in the
expression @var{expr} are replaced by their global values, except for those
appearing in this list.  Usually, @var{expr} is just a label or @code{%} (as in
@code{%i2} in the example below), so this step simply retrieves the expression
named by the label, so that @code{ev} may work on it.

@item
If any substitutions are indicated by the arguments, they are carried out now.

@item
The resulting expression is then re-evaluated (unless one of the arguments was
@mref{noeval}) and simplified according to the arguments.  Note that any
function calls in @var{expr} will be carried out after the variables in it are
evaluated and that @code{ev(F(x))} thus may behave like @code{F(ev(x))}.

@item
For each instance of @mref{eval} in the arguments, steps (3) and (4) are
repeated.
@end enumerate

See also @mxrefcomma{quote-quote, ''} @mref{at} and @mrefdot{subst}

Examples:

@c ===beg===
@c sin(x) + cos(y) + (w+1)^2 + 'diff (sin(w), w);
@c ev (%, numer, expand, diff, x=2, y=1);
@c ===end===
@example
(%i1) sin(x) + cos(y) + (w+1)^2 + 'diff (sin(w), w);
                                     d                    2
(%o1)              cos(y) + sin(x) + -- (sin(w)) + (w + 1)
                                     dw
(%i2) ev (%, numer, expand, diff, x=2, y=1);
                               2
(%o2)                cos(w) + w  + 2 w + 2.449599732693821
@end example

An alternate top level syntax has been provided for @code{ev}, whereby one
may just type in its arguments, without the @code{ev()}.  That is, one may
write simply

@example
@var{expr}, @var{arg_1}, ..., @var{arg_n}
@end example

This is not permitted as part of another expression, e.g., in functions,
blocks, etc.

Notice the parallel binding process in the following example.

@example
(%i3) programmode: false;
(%o3)                                false
(%i4) x+y, x: a+y, y: 2;
(%o4)                              y + a + 2
(%i5) 2*x - 3*y = 3$
(%i6) -3*x + 2*y = -4$
(%i7) solve ([%o5, %o6]);
Solution

                                          1
(%t7)                               y = - -
                                          5

                                         6
(%t8)                                x = -
                                         5
(%o8)                            [[%t7, %t8]]
(%i8) %o6, %o8;
(%o8)                              - 4 = - 4
(%i9) x + 1/x > gamma (1/2);
                                   1
(%o9)                          x + - > sqrt(%pi)
                                   x
(%i10) %, numer, x=1/2;
(%o10)                      2.5 > 1.772453850905516
(%i11) %, pred;
(%o11)                               true
@end example

@opencatbox
@category{Evaluation}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{eval}
@defvr {Special symbol} eval

As an argument in a call to @code{ev (@var{expr})}, @code{eval} causes an extra
evaluation of @var{expr}.  See @mrefdot{ev}

Example:

@c ===beg===
@c [a:b,b:c,c:d,d:e];
@c a;
@c ev(a);
@c ev(a),eval;
@c a,eval,eval;
@c ===end===
@example
(%i1) [a:b,b:c,c:d,d:e];
(%o1)                            [b, c, d, e]
(%i2) a;
(%o2)                                  b
(%i3) ev(a);
(%o3)                                  c
(%i4) ev(a),eval;
(%o4)                                  e
(%i5) a,eval,eval;
(%o5)                                  e
@end example

@opencatbox
@category{Evaluation flags}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{evflag}
@defvr {Property} evflag

When a symbol @var{x} has the @code{evflag} property, the expressions
@code{ev(@var{expr}, @var{x})} and @code{@var{expr}, @var{x}} (at the
interactive prompt) are equivalent to @code{ev(@var{expr}, @var{x} = true)}.
That is, @var{x} is bound to @code{true} while @var{expr} is evaluated.

The expression @code{declare(@var{x}, evflag)} gives the @code{evflag} property
to the variable @var{x}.

The flags which have the @code{evflag} property by default are the following:
@c FOLLOWING LIST CONSTRUCTED FROM LIST UNDER (prog1 '(evflag properties) ...)
@c NEAR LINE 2649 OF mlisp.lisp AT PRESENT (2004/11).

@verbatim
   algebraic          cauchysum       demoivre
   dotscrules         %emode          %enumer
   exponentialize     exptisolate     factorflag
   float              halfangles      infeval
   isolate_wrt_times  keepfloat       letrat
   listarith          logabs          logarc 
   logexpand          lognegint       
   m1pbranch          numer_pbranch   programmode 
   radexpand          ratalgdenom     ratfac 
   ratmx              ratsimpexpons   simp 
   simpproduct        simpsum         sumexpand
   trigexpand
@end verbatim

Examples:

@c ===beg===
@c sin (1/2);
@c sin (1/2), float;
@c sin (1/2), float=true;
@c simp : false;
@c 1 + 1;
@c 1 + 1, simp;
@c simp : true;
@c sum (1/k^2, k, 1, inf);
@c sum (1/k^2, k, 1, inf), simpsum;
@c declare (aa, evflag);
@c if aa = true then YES else NO;
@c if aa = true then YES else NO, aa;
@c ===end===
@example
(%i1) sin (1/2);
                                 1
(%o1)                        sin(-)
                                 2
(%i2) sin (1/2), float;
(%o2)                   0.479425538604203
(%i3) sin (1/2), float=true;
(%o3)                   0.479425538604203
(%i4) simp : false;
(%o4)                         false
(%i5) 1 + 1;
(%o5)                         1 + 1
(%i6) 1 + 1, simp;
(%o6)                           2
(%i7) simp : true;
(%o7)                         true
(%i8) sum (1/k^2, k, 1, inf);
                            inf
                            ====
                            \     1
(%o8)                        >    --
                            /      2
                            ====  k
                            k = 1
(%i9) sum (1/k^2, k, 1, inf), simpsum;
                                 2
                              %pi
(%o9)                         ----
                               6
(%i10) declare (aa, evflag);
(%o10)                        done
(%i11) if aa = true then YES else NO;
(%o11)                         NO
(%i12) if aa = true then YES else NO, aa;
(%o12)                         YES
@end example

@opencatbox
@category{Evaluation flags}
@category{Simplification flags and variables}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{evfun}
@defvr {Property} evfun

When a function @var{F} has the @code{evfun} property, the expressions
@code{ev(@var{expr}, @var{F})} and @code{@var{expr}, @var{F}} (at the
interactive prompt) are equivalent to @code{@var{F}(ev(@var{expr}))}.

If two or more @code{evfun} functions @var{F}, @var{G}, etc., are specified,
the functions are applied in the order that they are specified.

The expression @code{declare(@var{F}, evfun)} gives the @code{evfun} property
to the function @var{F}.  The functions which have the @code{evfun} property by
default are the following:
@c FOLLOWING LIST CONSTRUCTED FROM LIST UNDER (prog1 '(evfun properties) ...)
@c NEAR LINE 2643 IN mlisp.lisp AT PRESENT (2004/11).

@verbatim
   bfloat          factor       fullratsimp
   logcontract     polarform    radcan
   ratexpand       ratsimp      rectform
   rootscontract   trigexpand   trigreduce
@end verbatim

Examples:

@c ===beg===
@c x^3 - 1;
@c x^3 - 1, factor;
@c factor (x^3 - 1);
@c cos(4 * x) / sin(x)^4;
@c cos(4 * x) / sin(x)^4, trigexpand;
@c cos(4 * x) / sin(x)^4, trigexpand, ratexpand;
@c ratexpand (trigexpand (cos(4 * x) / sin(x)^4));
@c declare ([F, G], evfun);
@c (aa : bb, bb : cc, cc : dd);
@c aa;
@c aa, F;
@c F (aa);
@c F (ev (aa));
@c aa, F, G;
@c G (F (ev (aa)));
@c ===end===
@example
(%i1) x^3 - 1;
                              3
(%o1)                        x  - 1
(%i2) x^3 - 1, factor;
                                2
(%o2)                 (x - 1) (x  + x + 1)
(%i3) factor (x^3 - 1);
                                2
(%o3)                 (x - 1) (x  + x + 1)
(%i4) cos(4 * x) / sin(x)^4;
@group
                            cos(4 x)
(%o4)                       --------
                               4
                            sin (x)
@end group
(%i5) cos(4 * x) / sin(x)^4, trigexpand;
                 4           2       2         4
              sin (x) - 6 cos (x) sin (x) + cos (x)
(%o5)         -------------------------------------
                                4
                             sin (x)
(%i6) cos(4 * x) / sin(x)^4, trigexpand, ratexpand;
                           2         4
                      6 cos (x)   cos (x)
(%o6)               - --------- + ------- + 1
                          2          4
                       sin (x)    sin (x)
(%i7) ratexpand (trigexpand (cos(4 * x) / sin(x)^4));
                           2         4
                      6 cos (x)   cos (x)
(%o7)               - --------- + ------- + 1
                          2          4
                       sin (x)    sin (x)
(%i8) declare ([F, G], evfun);
(%o8)                         done
(%i9) (aa : bb, bb : cc, cc : dd);
(%o9)                          dd
(%i10) aa;
(%o10)                         bb
(%i11) aa, F;
(%o11)                        F(cc)
(%i12) F (aa);
(%o12)                        F(bb)
(%i13) F (ev (aa));
(%o13)                        F(cc)
(%i14) aa, F, G;
(%o14)                      G(F(cc))
(%i15) G (F (ev (aa)));
(%o15)                      G(F(cc))
@end example

@opencatbox
@category{Evaluation flags}
@closecatbox
@end defvr

@c NEEDS WORK

@c -----------------------------------------------------------------------------
@anchor{infeval}
@defvr {Option variable} infeval

Enables "infinite evaluation" mode.  @mref{ev} repeatedly evaluates an
expression until it stops changing.  To prevent a variable, say @code{X}, from
being evaluated away in this mode, simply include @code{X='X} as an argument to
@code{ev}.  Of course expressions such as @code{ev (X, X=X+1, infeval)} will
generate an infinite loop.

@opencatbox
@category{Evaluation flags}
@closecatbox
@end defvr

@c NEEDS CLARIFICATION, EXAMPLES
@c NEED TO MENTION THIS IS AN evflag

@c -----------------------------------------------------------------------------
@anchor{noeval}
@defvr {Special symbol} noeval

@code{noeval} suppresses the evaluation phase of @mrefdot{ev}  This is useful in
conjunction with other switches and in causing expressions      
to be resimplified without being reevaluated.

@opencatbox
@category{Evaluation flags}
@closecatbox
@end defvr

@c NEEDS CLARIFICATION, EXAMPLES

@c -----------------------------------------------------------------------------
@anchor{nouns}
@defvr {Special symbol} nouns

@code{nouns} is an @mrefdot{evflag}  When used as an option to the @mref{ev}@w{}
command, @code{nouns} converts all "noun" forms occurring in the expression
being @code{ev}'d to "verbs", i.e., evaluates them.  See also
@mrefcomma{noun} @mrefcomma{nounify} @code{verb}, and @mrefdot{verbify}

@opencatbox
@category{Evaluation flags}
@category{Nouns and verbs}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{pred}
@defvr {Special symbol} pred

As an argument in a call to @code{ev (@var{expr})}, @code{pred} causes 
predicates (expressions which evaluate to @code{true} or @code{false}) to be 
evaluated.  See @mrefdot{ev}

Example:

@c ===beg===
@c 1<2;
@c 1<2,pred;
@c ===end===
@example
(%i1) 1<2;
(%o1)                                1 < 2
(%i2) 1<2,pred;
(%o2)                                true
@end example

@opencatbox
@category{Evaluation flags}
@closecatbox
@end defvr

