File: maxima_40.html

package info (click to toggle)
maxima 5.10.0-6
links: PTS
area: main
in suites: etch, etch-m68k
size: 44,268 kB
ctags: 17,987
sloc: lisp: 152,894; fortran: 14,667; perl: 14,204; tcl: 10,103; sh: 3,376; makefile: 2,202; ansic: 471; awk: 7
file content (2093 lines) | stat: -rw-r--r-- 87,919 bytes
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Created on September, 20 2006 by texi2html 1.76 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
            Karl Berry  <karl@freefriends.org>
            Olaf Bachmann <obachman@mathematik.uni-kl.de>
            and many others.
Maintained by: Many creative people <dev@texi2html.cvshome.org>
Send bugs and suggestions to <users@texi2html.cvshome.org>

-->
<head>
<title>Maxima Manual: 40. Function Definition</title>

<meta name="description" content="Maxima Manual: 40. Function Definition">
<meta name="keywords" content="Maxima Manual: 40. Function Definition">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.76">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
body
{
    color: black;
    background: white; 
    margin-left: 8%;
    margin-right: 13%;
}

h1
{
    margin-left: +8%;
    font-size: 150%;
    font-family: sans-serif
}

h2
{
    font-size: 125%;
    font-family: sans-serif
}

h3
{
    font-size: 100%;
    font-family: sans-serif
}

h2,h3,h4,h5,h6 { margin-left: +4%; }

div.textbox
{
    border: solid;
    border-width: thin;
    /* width: 100%; */
    padding-top: 1em;
    padding-bottom: 1em;
    padding-left: 2em;
    padding-right: 2em
}

div.titlebox
{
    border: none;
    padding-top: 1em;
    padding-bottom: 1em;
    padding-left: 2em;
    padding-right: 2em;
    background: rgb(200,255,255);
    font-family: sans-serif
}

div.synopsisbox
{
    border: none;
    padding-top: 1em;
    padding-bottom: 1em;
    padding-left: 2em;
    padding-right: 2em;
     background: rgb(255,220,255);
    /*background: rgb(200,255,255); */
    /* font-family: fixed */
}

pre.example
{
    border: none;
    padding-top: 1em;
    padding-bottom: 1em;
    padding-left: 1em;
    padding-right: 1em;
    background: rgb(247,242,180); /* kind of sandy */
    /* background: rgb(200,255,255); */ /* sky blue */
    font-family: "Lucida Console", monospace
}

div.spacerbox
{
    border: none;
    padding-top: 2em;
    padding-bottom: 2em
}

div.image
{
    margin: 0;
    padding: 1em;
    text-align: center;
}
-->
</style>

<link rel="icon" href="http://maxima.sourceforge.net/favicon.ico"/>
</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">

<a name="Function-Definition"></a>
<a name="SEC155"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="maxima_39.html#SEC154" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC156" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="maxima_39.html#SEC148" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="maxima.html#SEC_Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="maxima_41.html#SEC162" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="maxima.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="maxima_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="maxima_72.html#SEC264" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="maxima_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h1 class="chapter"> 40. Function Definition </h1>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#SEC156">40.1 Introduction to Function Definition</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">  
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC157">40.2 Function</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">                    
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC160">40.3 Macros</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">                      
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC161">40.4 Definitions for Function Definition</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">  
</td></tr>
</table>

<hr size="6">
<a name="Introduction-to-Function-Definition"></a>
<a name="SEC156"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC155" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC157" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#SEC155" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC155" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="maxima_41.html#SEC162" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="maxima.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="maxima_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="maxima_72.html#SEC264" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="maxima_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 40.1 Introduction to Function Definition </h2>

<hr size="6">
<a name="Function"></a>
<a name="SEC157"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC156" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC158" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#SEC155" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC155" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="maxima_41.html#SEC162" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="maxima.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="maxima_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="maxima_72.html#SEC264" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="maxima_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 40.2 Function </h2>
<hr size="6">
<a name="SEC158"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC157" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC159" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#SEC155" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC157" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="maxima_41.html#SEC162" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="maxima.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="maxima_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="maxima_72.html#SEC264" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="maxima_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection"> 40.2.1 Ordinary functions </h3>

<p>To define a function in Maxima you use the := operator.
E.g.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">f(x) := sin(x)
</pre></td></tr></table>

<p>defines a function <code>f</code>.
Anonmyous functions may also be created using <code>lambda</code>.
For example
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">lambda ([i, j], ...)
</pre></td></tr></table>

<p>can be used instead of <code>f</code>
where
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">f(i,j) := block ([], ...);
map (lambda ([i], i+1), l)
</pre></td></tr></table>

<p>would return a list with 1 added to each term.
</p>
<p>You may also define a function with a variable number of arguments,
by having a final argument which is assigned to a list of the extra
arguments:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) f ([u]) := u;
(%o1)                      f([u]) := u
(%i2) f (1, 2, 3, 4);
(%o2)                     [1, 2, 3, 4]
(%i3) f (a, b, [u]) := [a, b, u];
(%o3)               f(a, b, [u]) := [a, b, u]
(%i4) f (1, 2, 3, 4, 5, 6);
(%o4)                 [1, 2, [3, 4, 5, 6]]
</pre></td></tr></table>
<p>The right hand side of a function is an expression.  Thus
if you want a sequence of expressions, you do
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">f(x) := (expr1, expr2, ...., exprn);
</pre></td></tr></table>
<p>and the value of <var>exprn</var> is what is returned by the function.
</p>
<p>If you wish to make a <code>return</code> from some expression inside the
function then you must use <code>block</code> and <code>return</code>.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">block ([], expr1, ..., if (a &gt; 10) then return(a), ..., exprn)
</pre></td></tr></table>
<p>is itself an expression, and so could take the place of the
right hand side of a function definition.  Here it may happen
that the return happens earlier than the last expression.
</p>
<p>The first <code>[]</code> in the block, may contain a list of variables and
variable assignments, such as <code>[a: 3, b, c: []]</code>, which would cause the
three variables <code>a</code>,<code>b</code>,and <code>c</code> to not refer to their
global values, but rather have these special values for as long as the
code executes inside the <code>block</code>, or inside functions called from
inside the <code>block</code>.  This is called <i>dynamic</i> binding, since the
variables last from the start of the block to the time it exits.  Once
you return from the <code>block</code>, or throw out of it, the old values (if
any) of the variables will be restored.   It is certainly a good idea
to protect your variables in this way.   Note that the assignments
in the block variables, are done in parallel.   This means, that if
you had used <code>c: a</code> in the above, the value of <code>c</code> would
have been the value of <code>a</code> at the time you just entered the block,
but before <code>a</code> was bound.   Thus doing something like
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">block ([a: a], expr1, ... a: a+3, ..., exprn)
</pre></td></tr></table>
<p>will protect the external value of <code>a</code> from being altered, but
would let you access what that value was.   Thus the right hand
side of the assignments, is evaluated in the entering context, before
any binding occurs.
Using just <code>block ([x], ...</code> would cause the <code>x</code> to have itself
as value, just as if it would have if you entered a fresh <b>Maxima</b>
session.
</p>
<p>The actual arguments to a function are treated in exactly same way as
the variables in a block.  Thus in
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">f(x) := (expr1, ..., exprn);
</pre></td></tr></table>
<p>and
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">f(1);
</pre></td></tr></table>
<p>we would have a similar context for evaluation of the expressions
as if we had done
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">block ([x: 1], expr1, ..., exprn)
</pre></td></tr></table>
<p>Inside functions, when the right hand side of a definition,
may be computed at runtime, it is useful to use <code>define</code> and
possibly <code>buildq</code>.  
</p>
<hr size="6">
<a name="SEC159"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC158" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC160" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#SEC155" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC157" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="maxima_41.html#SEC162" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="maxima.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="maxima_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="maxima_72.html#SEC264" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="maxima_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h3 class="subsection"> 40.2.2 Array functions </h3>

<p>An array function stores the function value the first time it is called with a given argument,
and returns the stored value, without recomputing it, when that same argument is given.
Such a function is often called a <i>memoizing function</i>.
</p>
<p>Array function names are appended to the global list <code>arrays</code>
(not the global list <code>functions</code>).
<code>arrayinfo</code> returns the list of arguments for which there are stored values,
and <code>listarray</code> returns the stored values. 
<code>dispfun</code> and <code>fundef</code> return the array function definition.
</p>
<p><code>arraymake</code> constructs an array function call,
analogous to <code>funmake</code> for ordinary functions.
<code>arrayapply</code> applies an array function to its arguments,
analogous to <code>apply</code> for ordinary functions.
There is nothing exactly analogous to <code>map</code> for array functions,
although <code>map(lambda([<var>x</var>], <var>a</var>[<var>x</var>]), <var>L</var>)</code> or
<code>makelist(<var>a</var>[<var>x</var>], <var>x</var>, <var>L</var>)</code>, where <var>L</var> is a list,
are not too far off the mark.
</p>
<p><code>remarray</code> removes an array function definition (including any stored function values),
analogous to <code>remfunction</code> for ordinary functions.
</p>
<p><code>kill(<var>a</var>[<var>x</var>])</code> removes the value of the array function <var>a</var>
stored for the argument <var>x</var>;
the next time <var>a</var> is called with argument <var>x</var>,
the function value is recomputed.
However, there is no way to remove all of the stored values at once,
except for <code>kill(<var>a</var>)</code> or <code>remarray(<var>a</var>)</code>,
which also remove the function definition.
</p>
<hr size="6">
<a name="Macros"></a>
<a name="SEC160"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC159" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC161" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#SEC155" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC155" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="maxima_41.html#SEC162" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="maxima.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="maxima_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="maxima_72.html#SEC264" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="maxima_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 40.3 Macros </h2>

<dl>
<dt><u>Function:</u> <b>buildq</b><i> (<var>L</var>, <var>expr</var>)</i>
<a name="IDX1287"></a>
</dt>
<dd><p>Substitutes variables named by the list <var>L</var> into the expression <var>expr</var>,
in parallel,
without evaluating <var>expr</var>.
The resulting expression is simplified,
but not evaluated,
after <code>buildq</code> carries out the substitution.
</p>
<p>The elements of <var>L</var> are symbols or assignment expressions <code><var>symbol</var>: <var>value</var></code>,
evaluated in parallel.
That is, the binding of a variable on the right-hand side of an assignment
is the binding of that variable in the context from which <code>buildq</code> was called,
not the binding of that variable in the variable list <var>L</var>.
If some variable in <var>L</var> is not given an explicit assignment,
its binding in <code>buildq</code> is the same as in the context from which <code>buildq</code> was called.
</p>
<p>Then the variables named by <var>L</var> are substituted into <var>expr</var> in parallel.
That is, the substitution for every variable is determined before any substitution is made,
so the substitution for one variable has no effect on any other.
</p>
<p>If any variable <var>x</var> appears as <code>splice (<var>x</var>)</code> in <var>expr</var>,
then <var>x</var> must be bound to a list,
and the list is spliced (interpolated) into <var>expr</var> instead of substituted.
</p>
<p>Any variables in <var>expr</var> not appearing in <var>L</var> are carried into the result verbatim,
even if they have bindings in the context from which <code>buildq</code> was called.
</p>
<p>Examples
</p>
<p><code>a</code> is explicitly bound to <code>x</code>,
while <code>b</code> has the same binding (namely 29) as in the calling context,
and <code>c</code> is carried through verbatim.
The resulting expression is not evaluated until the explicit evaluation <code>''%</code>.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) (a: 17, b: 29, c: 1729)$
(%i2) buildq ([a: x, b], a + b + c);
(%o2)                      x + c + 29
(%i3) ''%;
(%o3)                       x + 1758
</pre></td></tr></table>
<p><code>e</code> is bound to a list, which appears as such in the arguments of <code>foo</code>,
and interpolated into the arguments of <code>bar</code>.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) buildq ([e: [a, b, c]], foo (x, e, y));
(%o1)                 foo(x, [a, b, c], y)
(%i2) buildq ([e: [a, b, c]], bar (x, splice (e), y));
(%o2)                  bar(x, a, b, c, y)
</pre></td></tr></table>
<p>The result is simplified after substitution.
If simplification were applied before substitution, these two results would be the same.
</p><table><tr><td>&nbsp;</td><td><pre class="example">(%i1) buildq ([e: [a, b, c]], splice (e) + splice (e));
(%o1)                    2 c + 2 b + 2 a
(%i2) buildq ([e: [a, b, c]], 2 * splice (e));
(%o2)                        2 a b c
</pre></td></tr></table>
<p>The variables in <var>L</var> are bound in parallel; if bound sequentially,
the first result would be <code>foo (b, b)</code>.
Substitutions are carried out in parallel;
compare the second result with the result of <code>subst</code>,
which carries out substitutions sequentially.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) buildq ([a: b, b: a], foo (a, b));
(%o1)                       foo(b, a)
(%i2) buildq ([u: v, v: w, w: x, x: y, y: z, z: u], bar (u, v, w, x, y, z));
(%o2)                 bar(v, w, x, y, z, u)
(%i3) subst ([u=v, v=w, w=x, x=y, y=z, z=u], bar (u, v, w, x, y, z));
(%o3)                 bar(u, u, u, u, u, u)
</pre></td></tr></table>
<p>Construct a list of equations with some variables or expressions on the left-hand side
and their values on the right-hand side.
<code>macroexpand</code> shows the expression returned by <code>show_values</code>.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) show_values ([L]) ::= buildq ([L], map (&quot;=&quot;, 'L, L));
(%o1)   show_values([L]) ::= buildq([L], map(&quot;=&quot;, 'L, L))
(%i2) (a: 17, b: 29, c: 1729)$
(%i3) show_values (a, b, c - a - b);
(%o3)          [a = 17, b = 29, c - b - a = 1683]
(%i4) macroexpand (show_values (a, b, c - a - b));
(%o4)    map(=, '([a, b, c - b - a]), [a, b, c - b - a])
</pre></td></tr></table>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>macroexpand</b><i> (<var>expr</var>)</i>
<a name="IDX1288"></a>
</dt>
<dd><p>Returns the macro expansion of <var>expr</var> without evaluating it,
when <code>expr</code> is a macro function call.
Otherwise, <code>macroexpand</code> returns <var>expr</var>.
</p>
<p>If the expansion of <var>expr</var> yields another macro function call,
that macro function call is also expanded.
</p>
<p><code>macroexpand</code> quotes its argument.
However, if the expansion of a macro function call has side effects,
those side effects are executed.
</p>
<p>See also <code>::=</code>, <code>macros</code>, and <code>macroexpand1</code>.
</p>
<p>Examples
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) g (x) ::= x / 99;
                                    x
(%o1)                      g(x) ::= --
                                    99
(%i2) h (x) ::= buildq ([x], g (x - a));
(%o2)            h(x) ::= buildq([x], g(x - a))
(%i3) a: 1234;
(%o3)                         1234
(%i4) macroexpand (h (y));
                              y - a
(%o4)                         -----
                               99
(%i5) h (y);
                            y - 1234
(%o5)                       --------
                               99
</pre></td></tr></table>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>macroexpand1</b><i> (<var>expr</var>)</i>
<a name="IDX1289"></a>
</dt>
<dd><p>Returns the macro expansion of <var>expr</var> without evaluating it,
when <code>expr</code> is a macro function call.
Otherwise, <code>macroexpand1</code> returns <var>expr</var>.
</p>
<p><code>macroexpand1</code> quotes its argument.
However, if the expansion of a macro function call has side effects,
those side effects are executed.
</p>
<p>If the expansion of <var>expr</var> yields another macro function call,
that macro function call is not expanded.
</p>
<p>See also <code>::=</code>, <code>macros</code>, and <code>macroexpand</code>.
</p>
<p>Examples
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) g (x) ::= x / 99;
                                    x
(%o1)                      g(x) ::= --
                                    99
(%i2) h (x) ::= buildq ([x], g (x - a));
(%o2)            h(x) ::= buildq([x], g(x - a))
(%i3) a: 1234;
(%o3)                         1234
(%i4) macroexpand1 (h (y));
(%o4)                       g(y - a)
(%i5) h (y);
                            y - 1234
(%o5)                       --------
                               99
</pre></td></tr></table>
</dd></dl>

<dl>
<dt><u>Global variable:</u> <b>macros</b>
<a name="IDX1290"></a>
</dt>
<dd><p>Default value: <code>[]</code>
</p>
<p><code>macros</code> is the list of user-defined macro functions.
The macro function definition operator <code>::=</code> puts a new macro function onto this list,
and <code>kill</code>, <code>remove</code>, and <code>remfunction</code> remove macro functions from the list.
</p>
<p>See also <code>infolists</code>.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>splice</b><i> (<var>a</var>)</i>
<a name="IDX1291"></a>
</dt>
<dd><p>Splices (interpolates) the list named by the atom <var>a</var> into an expression,
but only if <code>splice</code> appears within <code>buildq</code>;
otherwise, <code>splice</code> is treated as an undefined function.
If appearing within <code>buildq</code> as <var>a</var> alone (without <code>splice</code>),
<var>a</var> is substituted (not interpolated) as a list into the result.
The argument of <code>splice</code> can only be an atom;
it cannot be a literal list or an expression which yields a list.
</p>
<p>Typically <code>splice</code> supplies the arguments for a function or operator.
For a function <code>f</code>, the expression <code>f (splice (<var>a</var>))</code> within <code>buildq</code>
expands to <code>f (<var>a</var>[1], <var>a</var>[2], <var>a</var>[3], ...)</code>.
For an operator <code>o</code>, the expression <code>&quot;o&quot; (splice (<var>a</var>)</code> within <code>buildq</code>
expands to <code>&quot;o&quot; (<var>a</var>[1], <var>a</var>[2], <var>a</var>[3], ...)</code>,
where <code>o</code> may be any type of operator (typically one which takes multiple arguments).
Note that the operator must be enclosed in double quotes <code>&quot;</code>.
</p>
<p>Examples
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) buildq ([x: [1, %pi, z - y]], foo (splice (x)) / length (x));
                       foo(1, %pi, z - y)
(%o1)                -----------------------
                     length([1, %pi, z - y])
(%i2) buildq ([x: [1, %pi]], &quot;/&quot; (splice (x)));
                                1
(%o2)                          ---
                               %pi
(%i3) matchfix (&quot;&lt;&gt;&quot;, &quot;&lt;&gt;&quot;);
(%o3)                          &lt;&gt;
(%i4) buildq ([x: [1, %pi, z - y]], &quot;&lt;&gt;&quot; (splice (x)));
(%o4)                   &lt;&gt;1, %pi, z - y&lt;&gt;
</pre></td></tr></table>
</dd></dl>


<hr size="6">
<a name="Definitions-for-Function-Definition"></a>
<a name="SEC161"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC160" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="maxima_41.html#SEC162" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#SEC155" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="#SEC155" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="maxima_41.html#SEC162" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="maxima.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="maxima_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="maxima_72.html#SEC264" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="maxima_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 40.4 Definitions for Function Definition </h2>

<dl>
<dt><u>Function:</u> <b>apply</b><i> (<var>F</var>, [<var>x_1</var>, ..., <var>x_n</var>])</i>
<a name="IDX1292"></a>
</dt>
<dd><p>Constructs and evaluates an expression <code><var>F</var>(<var>arg_1</var>, ..., <var>arg_n</var>)</code>.
</p>
<p><code>apply</code> does not attempt to distinguish array functions from ordinary functions;
when <var>F</var> is the name of an array function,
<code>apply</code> evaluates <code><var>F</var>(...)</code>
(that is, a function call with parentheses instead of square brackets).
<code>arrayapply</code> evaluates a function call with square brackets in this case.
</p>
<p>Examples:
</p>
<p><code>apply</code> evaluates its arguments.
In this example, <code>min</code> is applied to the value of <code>L</code>.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) L : [1, 5, -10.2, 4, 3];
(%o1)                 [1, 5, - 10.2, 4, 3]
(%i2) apply (min, L);
(%o2)                        - 10.2
</pre></td></tr></table>
<p><code>apply</code> evaluates arguments, even if the function <var>F</var> quotes them.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) F (x) := x / 1729;
                                   x
(%o1)                     F(x) := ----
                                  1729
(%i2) fname : F;
(%o2)                           F
(%i3) dispfun (F);
                                   x
(%t3)                     F(x) := ----
                                  1729

(%o3)                         [%t3]
(%i4) dispfun (fname);
fname is not the name of a user function.
 -- an error.  Quitting.  To debug this try debugmode(true);
(%i5) apply (dispfun, [fname]);
                                   x
(%t5)                     F(x) := ----
                                  1729

(%o5)                         [%t5]
</pre></td></tr></table>
<p><code>apply</code> evaluates the function name <var>F</var>.
Single quote <code>'</code> defeats evaluation.
<code>demoivre</code> is the name of a global variable and also a function.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) demoivre;
(%o1)                         false
(%i2) demoivre (exp (%i * x));
(%o2)                  %i sin(x) + cos(x)
(%i3) apply (demoivre, [exp (%i * x)]);
demoivre evaluates to false
Improper name or value in functional position.
 -- an error.  Quitting.  To debug this try debugmode(true);
(%i4) apply ('demoivre, [exp (%i * x)]);
(%o4)                  %i sin(x) + cos(x)
</pre></td></tr></table>
</dd></dl>


<dl>
<dt><u>Function:</u> <b>block</b><i> ([<var>v_1</var>, ..., <var>v_m</var>], <var>expr_1</var>, ..., <var>expr_n</var>)</i>
<a name="IDX1293"></a>
</dt>
<dt><u>Function:</u> <b>block</b><i> (<var>expr_1</var>, ..., <var>expr_n</var>)</i>
<a name="IDX1294"></a>
</dt>
<dd><p><code>block</code> evaluates <var>expr_1</var>, ..., <var>expr_n</var> in sequence
and returns the value of the last expression evaluated.
The sequence can be modified by the <code>go</code>, <code>throw</code>, and <code>return</code> functions.
The last expression is <var>expr_n</var> unless <code>return</code> or an expression containing <code>throw</code>
is evaluated.
Some variables <var>v_1</var>, ..., <var>v_m</var> can be declared local to the block;
these are distinguished from global variables of the same names.
If no variables are declared local then the list may be omitted.
Within the block,
any variable other than <var>v_1</var>, ..., <var>v_m</var> is a global variable.
</p>
<p><code>block</code> saves the current values of the variables <var>v_1</var>, ..., <var>v_m</var> (if any)
upon entry to the block,
then unbinds the variables so that they evaluate to themselves.
The local variables may be bound to arbitrary values within the block but when the
block is exited the saved values are restored,
and the values assigned within the block are lost.
</p>
<p><code>block</code> may appear within another <code>block</code>.
Local variables are established each time a new <code>block</code> is evaluated.
Local variables appear to be global to any enclosed blocks.
If a variable is non-local in a block,
its value is the value most recently assigned by an enclosing block, if any,
otherwise, it is the value of the variable in the global environment.
This policy may coincide with the usual understanding of &quot;dynamic scope&quot;.
</p>
<p>If it is desired to save and restore other local properties
besides <code>value</code>, for example <code>array</code> (except for complete arrays),
<code>function</code>, <code>dependencies</code>, <code>atvalue</code>, <code>matchdeclare</code>, <code>atomgrad</code>, <code>constant</code>, and
<code>nonscalar</code> then the function <code>local</code> should be used inside of the block
with arguments being the names of the variables.
</p>
<p>The value of the block is the value of the last statement or the
value of the argument to the function <code>return</code> which may be used to exit
explicitly from the block. The function <code>go</code> may be used to transfer
control to the statement of the block that is tagged with the argument
to <code>go</code>.  To tag a statement, precede it by an atomic argument as
another statement in the block.  For example:
<code>block ([x], x:1, loop, x: x+1, ..., go(loop), ...)</code>.  The argument to <code>go</code> must
be the name of a tag appearing within the block.  One cannot use <code>go</code> to
transfer to a tag in a block other than the one containing the <code>go</code>.
</p>
<p>Blocks typically appear on the right side of a function definition
but can be used in other places as well.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>break</b><i> (<var>expr_1</var>, ..., <var>expr_n</var>)</i>
<a name="IDX1295"></a>
</dt>
<dd><p>Evaluates and prints <var>expr_1</var>, ..., <var>expr_n</var> and then
causes a Maxima break at which point the user can examine and change
his environment.  Upon typing <code>exit;</code> the computation resumes.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>catch</b><i> (<var>expr_1</var>, ..., <var>expr_n</var>)</i>
<a name="IDX1296"></a>
</dt>
<dd><p>Evaluates <var>expr_1</var>, ..., <var>expr_n</var> one by one; if any
leads to the evaluation of an expression of the
form <code>throw (arg)</code>, then the value of the <code>catch</code> is the value of
<code>throw (arg)</code>, and no further expressions are evaluated.
This &quot;non-local return&quot; thus goes through any depth of
nesting to the nearest enclosing <code>catch</code>.
If there is no <code>catch</code> enclosing a <code>throw</code>, an error message is printed.
</p>
<p>If the evaluation of the arguments does not lead to the evaluation of any <code>throw</code>
then the value of <code>catch</code> is the value of <var>expr_n</var>.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) lambda ([x], if x &lt; 0 then throw(x) else f(x))$
(%i2) g(l) := catch (map (''%, l))$
(%i3) g ([1, 2, 3, 7]);
(%o3)               [f(1), f(2), f(3), f(7)]
(%i4) g ([1, 2, -3, 7]);
(%o4)                          - 3
</pre></td></tr></table>
<p>The function <code>g</code> returns a list of <code>f</code> of each element of <code>l</code> if <code>l</code>
consists only of non-negative numbers; otherwise, <code>g</code> &quot;catches&quot; the
first negative element of <code>l</code> and &quot;throws&quot; it up.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>compfile</b><i> (<var>filename</var>, <var>f_1</var>, ..., <var>f_n</var>)</i>
<a name="IDX1297"></a>
</dt>
<dd><p>Translates Maxima functions <var>f_1</var>, ..., <var>f_n</var> into Lisp 
and writes the translated code into the file <var>filename</var>.
</p>
<p>The Lisp translations are not evaluated, nor is the output file processed by the Lisp compiler.
<code>translate</code> creates and evaluates Lisp translations.
<code>compile_file</code> translates Maxima into Lisp, and then executes the Lisp compiler. 
</p>
<p>See also <code>translate</code>, <code>translate_file</code>, and <code>compile_file</code>.
</p>
</dd></dl>


<dl>
<dt><u>Function:</u> <b>compile</b><i> (<var>f_1</var>, ..., <var>f_n</var>)</i>
<a name="IDX1298"></a>
</dt>
<dt><u>Function:</u> <b>compile</b><i> (functions)</i>
<a name="IDX1299"></a>
</dt>
<dt><u>Function:</u> <b>compile</b><i> (all)</i>
<a name="IDX1300"></a>
</dt>
<dd><p>Translates Maxima functions <var>f_1</var>, ..., <var>f_n</var> into Lisp, evaluates the Lisp translations,
and calls the Lisp function <code>COMPILE</code> on each translated function.
<code>compile</code> returns a list of the names of the compiled functions.
</p>
<p><code>compile (all)</code> or <code>compile (functions)</code> compiles all user-defined functions.
</p>
<p><code>compile</code> quotes its arguments; 
the quote-quote operator <code>''</code> defeats quotation.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>define</b><i> (<var>f</var>(<var>x_1</var>, ..., <var>x_n</var>), <var>expr</var>)</i>
<a name="IDX1301"></a>
</dt>
<dd><p>Defines a function named <var>f</var> with arguments <var>x_1</var>, ..., <var>x_n</var> and function body <var>expr</var>.
</p>
<p><code>define</code> quotes its first argument in most cases,
and evaluates its second argument unless explicitly quoted.
However, if the first argument is an expression of the form
<code>ev (<var>expr</var>)</code>, <code>funmake (<var>expr</var>)</code>, or <code>arraymake (<var>expr</var>)</code>,
the first argument is evaluated;
this allows for the function name to be computed, as well as the body.
</p>
<p><code>define</code> is similar to the function definition operator <code>:=</code>, but when
<code>define</code> appears inside a function, the definition is created using the value
of <code>expr</code> at execution time rather than at the
time of definition of the function which contains it.
</p>
<p>All function definitions appear in the same namespace;
defining a function <code>f</code> within another function <code>g</code>
does not limit the scope of <code>f</code> to <code>g</code>.
</p>
<p><code>define</code> defines array functions (called with arguments in square brackets <code>[ ]</code>)
as well as ordinary functions.
</p>
<p>Examples:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) foo: 2^bar;
                               bar
(%o1)                         2
(%i2) g(x) := (f_1 (y) :=   foo*x*y,
               f_2 (y) := ''foo*x*y,
       define (f_3 (y),     foo*x*y),
       define (f_4 (y),   ''foo*x*y));
                                             bar
(%o2) g(x) := (f_1(y) := foo x y, f_2(y) := 2    x y, 
                                                        bar
               define(f_3(y), foo x y), define(f_4(y), 2    x y))
(%i3) functions;
(%o3)                        [g(x)]
(%i4) g(a);
                                    bar
(%o4)                  f_4(y) := a 2    y
(%i5) functions;
(%o5)        [g(x), f_1(y), f_2(y), f_3(y), f_4(y)]
(%i6) dispfun (f_1, f_2, f_3, f_4);
(%t6)                   f_1(y) := foo x y

                                  bar
(%t7)                  f_2(y) := 2    x y

                                    bar
(%t8)                  f_3(y) := a 2    y

                                    bar
(%t9)                  f_4(y) := a 2    y

(%o9)                         done
</pre></td></tr></table></dd></dl>

<dl>
<dt><u>Function:</u> <b>define_variable</b><i> (<var>name</var>, <var>default_value</var>, <var>mode</var>)</i>
<a name="IDX1302"></a>
</dt>
<dd><p>Introduces a global variable into the Maxima environment.
<code>define_variable</code> is useful in user-written packages, which are often translated or compiled.
</p>
<p><code>define_variable</code> carries out the following steps:
</p>
<ol>
<li>
<code>mode_declare (<var>name</var>, <var>mode</var>)</code> declares the mode of <var>name</var> to the translator.
See <code>mode_declare</code> for a list of the possible modes.

</li><li>
If the variable is unbound, <var>default_value</var> is assigned to <var>name</var>.

</li><li>
<code>declare (<var>name</var>, special)</code> declares it special.

</li><li>
Associates <var>name</var> with a test function
to ensure that <var>name</var> is only assigned values of the declared mode.
</li></ol>



<p>The <code>value_check</code> property can be assigned to any variable which has been defined
via <code>define_variable</code> with a mode other than <code>any</code>.
The <code>value_check</code> property is a lambda expression or the name of a function of one variable,
which is called when an attempt is made to assign a value to the variable.
The argument of the <code>value_check</code> function is the would-be assigned value.
</p>
<p><code>define_variable</code> evaluates <code>default_value</code>, and quotes <code>name</code> and <code>mode</code>.
<code>define_variable</code> returns the current value of <code>name</code>,
which is <code>default_value</code> if <code>name</code> was unbound before,
and otherwise it is the previous value of <code>name</code>.
</p>
<p>Examples:
</p>
<p><code>foo</code> is a Boolean variable, with the initial value <code>true</code>.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) define_variable (foo, true, boolean);
(%o1)                         true
(%i2) foo;
(%o2)                         true
(%i3) foo: false;
(%o3)                         false
(%i4) foo: %pi;
Error: foo was declared mode boolean, has value: %pi
 -- an error.  Quitting.  To debug this try debugmode(true);
(%i5) foo;
(%o5)                         false
</pre></td></tr></table>
<p><code>bar</code> is an integer variable, which must be prime.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) define_variable (bar, 2, integer);
(%o1)                           2
(%i2) qput (bar, prime_test, value_check);
(%o2)                      prime_test
(%i3) prime_test (y) := if not primep(y) then error (y, &quot;is not prime.&quot;);
(%o3) prime_test(y) := if not primep(y)

                                   then error(y, &quot;is not prime.&quot;)
(%i4) bar: 1439;
(%o4)                         1439
(%i5) bar: 1440;
1440 is not prime.
#0: prime_test(y=1440)
 -- an error.  Quitting.  To debug this try debugmode(true);
(%i6) bar;
(%o6)                         1439
</pre></td></tr></table>
<p><code>baz_quux</code> is a variable which cannot be assigned a value.
The mode <code>any_check</code> is like <code>any</code>, 
but <code>any_check</code> enables the <code>value_check</code> mechanism, and <code>any</code> does not.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) define_variable (baz_quux, 'baz_quux, any_check);
(%o1)                       baz_quux
(%i2) F: lambda ([y], if y # 'baz_quux then error (&quot;Cannot assign to `baz_quux'.&quot;));
(%o2) lambda([y], if y # 'baz_quux

                        then error(Cannot assign to `baz_quux'.))
(%i3) qput (baz_quux, ''F, value_check);
(%o3) lambda([y], if y # 'baz_quux

                        then error(Cannot assign to `baz_quux'.))
(%i4) baz_quux: 'baz_quux;
(%o4)                       baz_quux
(%i5) baz_quux: sqrt(2);
Cannot assign to `baz_quux'.
#0: lambda([y],if y # 'baz_quux then error(&quot;Cannot assign to `baz_quux'.&quot;))(y=sqrt(2))
 -- an error.  Quitting.  To debug this try debugmode(true);
(%i6) baz_quux;
(%o6)                       baz_quux
</pre></td></tr></table>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>dispfun</b><i> (<var>f_1</var>, ..., <var>f_n</var>)</i>
<a name="IDX1303"></a>
</dt>
<dt><u>Function:</u> <b>dispfun</b><i> (all)</i>
<a name="IDX1304"></a>
</dt>
<dd><p>Displays the definition of the user-defined functions <var>f_1</var>, ..., <var>f_n</var>.
Each argument may be the name of a macro (defined with <code>::=</code>),
an ordinary function (defined with <code>:=</code> or <code>define</code>),
an array function (defined with <code>:=</code> or <code>define</code>,
but enclosing arguments in square brackets <code>[ ]</code>),
a subscripted function, (defined with <code>:=</code> or <code>define</code>,
but enclosing some arguments in square brackets and others in parentheses <code>( )</code>)
one of a family of subscripted functions selected by a particular subscript value,
or a subscripted function defined with a constant subscript.
</p>
<p><code>dispfun (all)</code> displays all user-defined functions as
given by the <code>functions</code>, <code>arrays</code>, and <code>macros</code> lists,
omitting subscripted functions defined with constant subscripts.
</p>
<p><code>dispfun</code> creates an intermediate expression label
(<code>%t1</code>, <code>%t2</code>, etc.)
for each displayed function, and assigns the function definition to the label.
In contrast, <code>fundef</code> returns the function definition.
</p>
<p><code>dispfun</code> quotes its arguments; 
the quote-quote operator <code>''</code> defeats quotation.
<code>dispfun</code> returns the list of intermediate expression labels corresponding to the displayed functions.
</p>
<p>Examples:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) m(x, y) ::= x^(-y);
                                     - y
(%o1)                   m(x, y) ::= x
(%i2) f(x, y) :=  x^(-y);
                                     - y
(%o2)                    f(x, y) := x
(%i3) g[x, y] :=  x^(-y);
                                    - y
(%o3)                     g     := x
                           x, y
(%i4) h[x](y) :=  x^(-y);
                                    - y
(%o4)                     h (y) := x
                           x
(%i5) i[8](y) :=  8^(-y);
                                    - y
(%o5)                     i (y) := 8
                           8
(%i6) dispfun (m, f, g, h, h[5], h[10], i[8]);
                                     - y
(%t6)                   m(x, y) ::= x

                                     - y
(%t7)                    f(x, y) := x

                                    - y
(%t8)                     g     := x
                           x, y

                                    - y
(%t9)                     h (y) := x
                           x

                                    1
(%t10)                     h (y) := --
                            5        y
                                    5

                                     1
(%t11)                    h  (y) := ---
                           10         y
                                    10

                                    - y
(%t12)                    i (y) := 8
                           8

(%o12)       [%t6, %t7, %t8, %t9, %t10, %t11, %t12]
(%i12) ''%;
                     - y              - y            - y
(%o12) [m(x, y) ::= x   , f(x, y) := x   , g     := x   , 
                                            x, y
                  - y           1              1             - y
        h (y) := x   , h (y) := --, h  (y) := ---, i (y) := 8   ]
         x              5        y   10         y   8
                                5             10
</pre></td></tr></table>
</dd></dl>

<dl>
<dt><u>System variable:</u> <b>functions</b>
<a name="IDX1305"></a>
</dt>
<dd><p>Default value: <code>[]</code>
</p>
<p><code>functions</code> is the list of ordinary Maxima functions
in the current session.
An ordinary function is a function constructed by
<code>define</code> or <code>:=</code> and called with parentheses <code>()</code>.
A function may be defined at the Maxima prompt
or in a Maxima file loaded by <code>load</code> or <code>batch</code>.
</p>
<p>Array functions (called with square brackets, e.g., <code>F[x]</code>)
and subscripted functions (called with square brackets and parentheses, e.g., <code>F[x](y)</code>)
are listed by the global variable <code>arrays</code>, and not by <code>functions</code>.
</p>
<p>Lisp functions are not kept on any list.
</p>
<p>Examples:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) F_1 (x) := x - 100;
(%o1)                   F_1(x) := x - 100
(%i2) F_2 (x, y) := x / y;
                                      x
(%o2)                    F_2(x, y) := -
                                      y
(%i3) define (F_3 (x), sqrt (x));
(%o3)                   F_3(x) := sqrt(x)
(%i4) G_1 [x] := x - 100;
(%o4)                    G_1  := x - 100
                            x
(%i5) G_2 [x, y] := x / y;
                                     x
(%o5)                     G_2     := -
                             x, y    y
(%i6) define (G_3 [x], sqrt (x));
(%o6)                    G_3  := sqrt(x)
                            x
(%i7) H_1 [x] (y) := x^y;
                                      y
(%o7)                     H_1 (y) := x
                             x
(%i8) functions;
(%o8)              [F_1(x), F_2(x, y), F_3(x)]
(%i9) arrays;
(%o9)                 [G_1, G_2, G_3, H_1]
</pre></td></tr></table>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>fundef</b><i> (<var>f</var>)</i>
<a name="IDX1306"></a>
</dt>
<dd><p>Returns the definition of the function <var>f</var>.
</p>
<p>The argument may be the name of a macro (defined with <code>::=</code>),
an ordinary function (defined with <code>:=</code> or <code>define</code>),
an array function (defined with <code>:=</code> or <code>define</code>,
but enclosing arguments in square brackets <code>[ ]</code>),
a subscripted function, (defined with <code>:=</code> or <code>define</code>,
but enclosing some arguments in square brackets and others in parentheses <code>( )</code>)
one of a family of subscripted functions selected by a particular subscript value,
or a subscripted function defined with a constant subscript.
</p>
<p><code>fundef</code> quotes its argument;
the quote-quote operator <code>''</code> defeats quotation.
</p>
<p><code>fundef (<var>f</var>)</code> returns the definition of <var>f</var>.
In contrast, <code>dispfun (<var>f</var>)</code> creates an intermediate expression label
and assigns the definition to the label.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>funmake</b><i> (<var>F</var>, [<var>arg_1</var>, ..., <var>arg_n</var>])</i>
<a name="IDX1307"></a>
</dt>
<dd><p>Returns an expression <code><var>F</var>(<var>arg_1</var>, ..., <var>arg_n</var>)</code>.
The return value is simplified, but not evaluated,
so the function <var>F</var> is not called, even if it exists.
</p>
<p><code>funmake</code> does not attempt to distinguish array functions from ordinary functions;
when <var>F</var> is the name of an array function,
<code>funmake</code> returns <code><var>F</var>(...)</code>
(that is, a function call with parentheses instead of square brackets).
<code>arraymake</code> returns a function call with square brackets in this case.
</p>
<p><code>funmake</code> evaluates its arguments.
</p>
<p>Examples:
</p>
<p><code>funmake</code> applied to an ordinary Maxima function.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) F (x, y) := y^2 - x^2;
                                   2    2
(%o1)                  F(x, y) := y  - x
(%i2) funmake (F, [a + 1, b + 1]);
(%o2)                    F(a + 1, b + 1)
(%i3) ''%;
                              2          2
(%o3)                  (b + 1)  - (a + 1)
</pre></td></tr></table>
<p><code>funmake</code> applied to a macro.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) G (x) ::= (x - 1)/2;
                                  x - 1
(%o1)                    G(x) ::= -----
                                    2
(%i2) funmake (G, [u]);
(%o2)                         G(u)
(%i3) ''%;
                              u - 1
(%o3)                         -----
                                2
</pre></td></tr></table>
<p><code>funmake</code> applied to a subscripted function.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) H [a] (x) := (x - 1)^a;
                                        a
(%o1)                   H (x) := (x - 1)
                         a
(%i2) funmake (H [n], [%e]);
                                       n
(%o2)               lambda([x], (x - 1) )(%e)
(%i3) ''%;
                                    n
(%o3)                       (%e - 1)
(%i4) funmake ('(H [n]), [%e]);
(%o4)                        H (%e)
                              n
(%i5) ''%;
                                    n
(%o5)                       (%e - 1)
</pre></td></tr></table>
<p><code>funmake</code> applied to a symbol which is not a defined function of any kind.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) funmake (A, [u]);
(%o1)                         A(u)
(%i2) ''%;
(%o2)                         A(u)
</pre></td></tr></table>
<p><code>funmake</code> evaluates its arguments, but not the return value.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) det(a,b,c) := b^2 -4*a*c;
                                    2
(%o1)              det(a, b, c) := b  - 4 a c
(%i2) (x : 8, y : 10, z : 12);
(%o2)                          12
(%i3) f : det;
(%o3)                          det
(%i4) funmake (f, [x, y, z]);
(%o4)                    det(8, 10, 12)
(%i5) ''%;
(%o5)                         - 284
</pre></td></tr></table>
<p>Maxima simplifies <code>funmake</code>'s return value.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) funmake (sin, [%pi / 2]);
(%o1)                           1
</pre></td></tr></table>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>lambda</b><i> ([<var>x_1</var>, ..., <var>x_m</var>], <var>expr_1</var>, ..., <var>expr_n</var>)</i>
<a name="IDX1308"></a>
</dt>
<dt><u>Function:</u> <b>lambda</b><i> ([[<var>L</var>]], <var>expr_1</var>, ..., <var>expr_n</var>)</i>
<a name="IDX1309"></a>
</dt>
<dt><u>Function:</u> <b>lambda</b><i> ([<var>x_1</var>, ..., <var>x_m</var>, [<var>L</var>]], <var>expr_1</var>, ..., <var>expr_n</var>)</i>
<a name="IDX1310"></a>
</dt>
<dd><p>Defines and returns a lambda expression (that is, an anonymous function).
The function may have required arguments <var>x_1</var>, ..., <var>x_m</var>
and/or optional arguments <var>L</var>, which appear within the function body as a list.
The return value of the function is <var>expr_n</var>.
A lambda expression can be assigned to a variable and evaluated like an ordinary function.
A lambda expression may appear in some contexts in which a function name is expected.
</p>
<p>When the function is evaluated,
unbound local variables <var>x_1</var>, ..., <var>x_m</var> are created.
<code>lambda</code> may appear within <code>block</code> or another <code>lambda</code>;
local variables are established each time another <code>block</code> or <code>lambda</code> is evaluated.
Local variables appear to be global to any enclosed <code>block</code> or <code>lambda</code>.
If a variable is not local,
its value is the value most recently assigned in an enclosing <code>block</code> or <code>lambda</code>, if any,
otherwise, it is the value of the variable in the global environment.
This policy may coincide with the usual understanding of &quot;dynamic scope&quot;.
</p>
<p>After local variables are established,
<var>expr_1</var> through <var>expr_n</var> are evaluated in turn.
The special variable <code>%%</code>, representing the value of the preceding expression,
is recognized.
<code>throw</code> and <code>catch</code> may also appear in the list of expressions.
</p>
<p><code>return</code> cannot appear in a lambda expression unless enclosed by <code>block</code>,
in which case <code>return</code> defines the return value of the block and not of the
lambda expression,
unless the block happens to be <var>expr_n</var>.
Likewise, <code>go</code> cannot appear in a lambda expression unless enclosed by <code>block</code>.
</p>
<p><code>lambda</code> quotes its arguments; 
the quote-quote operator <code>''</code> defeats quotation.
</p>
<p>Examples:
</p>
<ul>
<li>
A lambda expression can be assigned to a variable and evaluated like an ordinary function.
</li></ul>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) f: lambda ([x], x^2);
                                      2
(%o1)                    lambda([x], x )
(%i2) f(a);
                                2
(%o2)                          a
</pre></td></tr></table><ul>
<li>
A lambda expression may appear in contexts in which a function evaluation is expected.
</li></ul>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i3) lambda ([x], x^2) (a);
                                2
(%o3)                          a
(%i4) apply (lambda ([x], x^2), [a]);
                                2
(%o4)                          a
(%i5) map (lambda ([x], x^2), [a, b, c, d, e]);
                        2   2   2   2   2
(%o5)                 [a , b , c , d , e ]
</pre></td></tr></table><ul>
<li>
Argument variables are local variables.
Other variables appear to be global variables.
Global variables are evaluated at the time the lambda expression is evaluated,
unless some special evaluation is forced by some means, such as <code>''</code>.
</li></ul>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i6) a: %pi$
(%i7) b: %e$
(%i8) g: lambda ([a], a*b);
(%o8)                   lambda([a], a b)
(%i9) b: %gamma$
(%i10) g(1/2);
                             %gamma
(%o10)                       ------
                               2
(%i11) g2: lambda ([a], a*''b);
(%o11)                lambda([a], a %gamma)
(%i12) b: %e$
(%i13) g2(1/2);
                             %gamma
(%o13)                       ------
                               2
</pre></td></tr></table><ul>
<li>
Lambda expressions may be nested.
Local variables within the outer lambda expression appear to be global to the inner expression
unless masked by local variables of the same names.
</li></ul>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i14) h: lambda ([a, b], h2: lambda ([a], a*b), h2(1/2));
                                                   1
(%o14)    lambda([a, b], h2 : lambda([a], a b), h2(-))
                                                   2
(%i15) h(%pi, %gamma);
                             %gamma
(%o15)                       ------
                               2
</pre></td></tr></table><ul>
<li>
Since <code>lambda</code> quotes its arguments, lambda expression <code>i</code> below 
does not define a &quot;multiply by <code>a</code>&quot; function.
Such a function can be defined via <code>buildq</code>, as in lambda expression <code>i2</code> below.
</li></ul>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i16) i: lambda ([a], lambda ([x], a*x));
(%o16)            lambda([a], lambda([x], a x))
(%i17) i(1/2);
(%o17)                  lambda([x], a x)
(%i18) i2: lambda([a], buildq([a: a], lambda([x], a*x)));
(%o18)    lambda([a], buildq([a : a], lambda([x], a x)))
(%i19) i2(1/2);
                                     x
(%o19)                   lambda([x], -)
                                     2
(%i20) i2(1/2)(%pi);
                               %pi
(%o20)                         ---
                                2
</pre></td></tr></table><ul>
<li>
A lambda expression may take a variable number of arguments,
which are indicated by <code>[<var>L</var>]</code> as the sole or final argument.
The arguments appear within the function body as a list.
</li></ul>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) f : lambda ([aa, bb, [cc]], aa * cc + bb);
(%o1)          lambda([aa, bb, [cc]], aa cc + bb)
(%i2) f (foo, %i, 17, 29, 256);
(%o2)       [17 foo + %i, 29 foo + %i, 256 foo + %i]
(%i3) g : lambda ([[aa]], apply (&quot;+&quot;, aa));
(%o3)             lambda([[aa]], apply(+, aa))
(%i4) g (17, 29, x, y, z, %e);
(%o4)                  z + y + x + %e + 46
</pre></td></tr></table></dd></dl>

<dl>
<dt><u>Function:</u> <b>local</b><i> (<var>v_1</var>, ..., <var>v_n</var>)</i>
<a name="IDX1311"></a>
</dt>
<dd><p>Declares the variables <var>v_1</var>, ..., <var>v_n</var> to be local with
respect to all the properties in the statement in which this function
is used.
</p>
<p><code>local</code> quotes its arguments.
<code>local</code> returns <code>done</code>.
</p>
<p><code>local</code> may only be used in <code>block</code>, in the body of function
definitions or <code>lambda</code> expressions, or in the <code>ev</code> function, and only one
occurrence is permitted in each.
</p>
<p><code>local</code> is independent of <code>context</code>.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>macroexpansion</b>
<a name="IDX1312"></a>
</dt>
<dd><p>Default value: <code>false</code>
</p>
<p><code>macroexpansion</code> controls whether the expansion (that is, the return value) of a macro function
is substituted for the macro function call.
A substitution may speed up subsequent expression evaluations,
at the cost of storing the expansion.
</p>
<dl compact="compact">
<dt> <code>false</code></dt>
<dd><p>The expansion of a macro function is not substituted for the macro function call.
</p></dd>
<dt> <code>expand</code></dt>
<dd><p>The first time a macro function call is evaluated,
the expansion is stored.
The expansion is not recomputed on subsequent calls;
any side effects (such as <code>print</code> or assignment to global variables) happen
only when the macro function call is first evaluated.
Expansion in an expression does not affect other expressions
which have the same macro function call.
</p></dd>
<dt> <code>displace</code></dt>
<dd><p>The first time a macro function call is evaluated,
the expansion is substituted for the call,
thus modifying the expression from which the macro function was called.
The expansion is not recomputed on subsequent calls;
any side effects happen only when the macro function call is first evaluated.
Expansion in an expression does not affect other expressions
which have the same macro function call.
</p></dd>
</dl>

<p>Examples
</p>
<p>When <code>macroexpansion</code> is <code>false</code>,
a macro function is called every time the calling expression is evaluated,
and the calling expression is not modified.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) f (x) := h (x) / g (x);
                                  h(x)
(%o1)                     f(x) := ----
                                  g(x)
(%i2) g (x) ::= block (print (&quot;x + 99 is equal to&quot;, x), return (x + 99));
(%o2) g(x) ::= block(print(&quot;x + 99 is equal to&quot;, x), 
                                                  return(x + 99))
(%i3) h (x) ::= block (print (&quot;x - 99 is equal to&quot;, x), return (x - 99));
(%o3) h(x) ::= block(print(&quot;x - 99 is equal to&quot;, x), 
                                                  return(x - 99))
(%i4) macroexpansion: false;
(%o4)                         false
(%i5) f (a * b);
x - 99 is equal to x 
x + 99 is equal to x 
                            a b - 99
(%o5)                       --------
                            a b + 99
(%i6) dispfun (f);
                                  h(x)
(%t6)                     f(x) := ----
                                  g(x)

(%o6)                         done
(%i7) f (a * b);
x - 99 is equal to x 
x + 99 is equal to x 
                            a b - 99
(%o7)                       --------
                            a b + 99
</pre></td></tr></table>
<p>When <code>macroexpansion</code> is <code>expand</code>,
a macro function is called once,
and the calling expression is not modified.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) f (x) := h (x) / g (x);
                                  h(x)
(%o1)                     f(x) := ----
                                  g(x)
(%i2) g (x) ::= block (print (&quot;x + 99 is equal to&quot;, x), return (x + 99));
(%o2) g(x) ::= block(print(&quot;x + 99 is equal to&quot;, x), 
                                                  return(x + 99))
(%i3) h (x) ::= block (print (&quot;x - 99 is equal to&quot;, x), return (x - 99));
(%o3) h(x) ::= block(print(&quot;x - 99 is equal to&quot;, x), 
                                                  return(x - 99))
(%i4) macroexpansion: expand;
(%o4)                        expand
(%i5) f (a * b);
x - 99 is equal to x 
x + 99 is equal to x 
                            a b - 99
(%o5)                       --------
                            a b + 99
(%i6) dispfun (f);
                                  h(x)
(%t6)                     f(x) := ----
                                  g(x)

(%o6)                         done
(%i7) f (a * b);
                            a b - 99
(%o7)                       --------
                            a b + 99
</pre></td></tr></table>
<p>When <code>macroexpansion</code> is <code>expand</code>,
a macro function is called once,
and the calling expression is modified.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">(%i1) f (x) := h (x) / g (x);
                                  h(x)
(%o1)                     f(x) := ----
                                  g(x)
(%i2) g (x) ::= block (print (&quot;x + 99 is equal to&quot;, x), return (x + 99));
(%o2) g(x) ::= block(print(&quot;x + 99 is equal to&quot;, x), 
                                                  return(x + 99))
(%i3) h (x) ::= block (print (&quot;x - 99 is equal to&quot;, x), return (x - 99));
(%o3) h(x) ::= block(print(&quot;x - 99 is equal to&quot;, x), 
                                                  return(x - 99))
(%i4) macroexpansion: displace;
(%o4)                       displace
(%i5) f (a * b);
x - 99 is equal to x 
x + 99 is equal to x 
                            a b - 99
(%o5)                       --------
                            a b + 99
(%i6) dispfun (f);
                                 x - 99
(%t6)                    f(x) := ------
                                 x + 99

(%o6)                         done
(%i7) f (a * b);
                            a b - 99
(%o7)                       --------
                            a b + 99
</pre></td></tr></table>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>mode_checkp</b>
<a name="IDX1313"></a>
</dt>
<dd><p>Default value: <code>true</code>
</p>
<p>When <code>mode_checkp</code> is <code>true</code>, <code>mode_declare</code> checks the modes
of bound variables.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>mode_check_errorp</b>
<a name="IDX1314"></a>
</dt>
<dd><p>Default value: <code>false</code>
</p>
<p>When <code>mode_check_errorp</code> is <code>true</code>, <code>mode_declare</code> calls
error.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>mode_check_warnp</b>
<a name="IDX1315"></a>
</dt>
<dd><p>Default value: <code>true</code>
</p>
<p>When <code>mode_check_warnp</code> is <code>true</code>, mode errors are
described.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>mode_declare</b><i> (<var>y_1</var>, <var>mode_1</var>, ..., <var>y_n</var>, <var>mode_n</var>)</i>
<a name="IDX1316"></a>
</dt>
<dd><p><code>mode_declare</code> is used to declare the modes of variables and
functions for subsequent translation or compilation of functions.
<code>mode_declare</code> is typically placed at the beginning of a function
definition, at the beginning of a Maxima script, or executed at the interactive prompt.
</p>
<p>The arguments of <code>mode_declare</code> are pairs consisting of a variable and a mode which is
one of <code>boolean</code>, <code>fixnum</code>, <code>number</code>, <code>rational</code>, or <code>float</code>.
Each variable may also
be a list of variables all of which are declared to have the same mode.
</p>
<p>If a variable is an array, and if every element of the array which is
referenced has a value then <code>array (yi, complete, dim1, dim2, ...)</code>
rather than
</p><table><tr><td>&nbsp;</td><td><pre class="example">array(yi, dim1, dim2, ...)
</pre></td></tr></table><p>should be used when first
declaring the bounds of the array.
If all the elements of the array
are of mode <code>fixnum</code> (<code>float</code>), use <code>fixnum</code> (<code>float</code>) instead of <code>complete</code>.
Also if every element of the array is of the same mode, say <code>m</code>, then
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">mode_declare (completearray (yi), m))
</pre></td></tr></table>
<p>should be used for efficient
translation.
</p>
<p>Numeric code using arrays might run faster
by declaring the expected size of the array, as in:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">mode_declare (completearray (a [10, 10]), float)
</pre></td></tr></table>
<p>for a floating point number array which is 10 x 10.
</p>
<p>One may declare the mode of the result of a function by
using <code>function (f_1, f_2, ...)</code> as an argument;
here <code>f_1</code>, <code>f_2</code>, ... are the names
of functions.  For example the expression,
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">mode_declare ([function (f_1, f_2, ...)], fixnum)
</pre></td></tr></table>
<p>declares that the values returned by <code>f_1</code>, <code>f_2</code>, ... are single-word integers.
</p>
<p><code>modedeclare</code> is a synonym for <code>mode_declare</code>.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>mode_identity</b><i> (<var>arg_1</var>, <var>arg_2</var>)</i>
<a name="IDX1317"></a>
</dt>
<dd><p>A special form used with <code>mode_declare</code> and
<code>macros</code> to declare, e.g., a list of lists of flonums, or other compound
data object.  The first argument to <code>mode_identity</code> is a primitive value
mode name as given to <code>mode_declare</code> (i.e., one of <code>float</code>, <code>fixnum</code>, <code>number</code>,
<code>list</code>, or <code>any</code>), and the second argument is an expression which is
evaluated and returned as the value of <code>mode_identity</code>.  However, if the
return value is not allowed by the mode declared in the first
argument, an error or warning is signalled.  The important thing is
that the mode of the expression as determined by the Maxima to Lisp
translator, will be that given as the first argument, independent of
anything that goes on in the second argument.
E.g., <code>x: 3.3; mode_identity (fixnum, x);</code> yields an error. <code>mode_identity (flonum, x)</code>
returns 3.3 . 
This has a number of uses, e.g., if you knew that <code>first (l)</code> returned a
number then you might write <code>mode_identity (number, first (l))</code>.  However,
a more efficient way to do it would be to define a new primitive,
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">firstnumb (x) ::= buildq ([x], mode_identity (number, x));
</pre></td></tr></table>
<p>and use <code>firstnumb</code>
every time you take the first of a list of numbers.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>transcompile</b>
<a name="IDX1318"></a>
</dt>
<dd><p>Default value: <code>true</code>
</p>
<p>When <code>transcompile</code> is <code>true</code>, <code>translate</code> and <code>translate_file</code> generate
declarations to make the translated code more suitable for compilation.
</p>
<p><code>compfile</code> sets <code>transcompile: true</code> for the duration.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>translate</b><i> (<var>f_1</var>, ..., <var>f_n</var>)</i>
<a name="IDX1319"></a>
</dt>
<dt><u>Function:</u> <b>translate</b><i> (functions)</i>
<a name="IDX1320"></a>
</dt>
<dt><u>Function:</u> <b>translate</b><i> (all)</i>
<a name="IDX1321"></a>
</dt>
<dd><p>Translates the user-defined functions
<var>f_1</var>, ..., <var>f_n</var> from the Maxima language into Lisp
and evaluates the Lisp translations.
Typically the translated functions run faster than the originals.
</p>
<p><code>translate (all)</code> or <code>translate (functions)</code> translates all user-defined functions.
</p>
<p>Functions to be translated should include a call to <code>mode_declare</code> at the
beginning when possible in order to produce more efficient code.  For
example:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">f (x_1, x_2, ...) := block ([v_1, v_2, ...],
    mode_declare (v_1, mode_1, v_2, mode_2, ...), ...)
</pre></td></tr></table>


<p>where the <var>x_1</var>, <var>x_2</var>, ...  are the parameters to the function and the
<var>v_1</var>, <var>v_2</var>, ... are the local variables.
</p>
<p>The names of translated functions
are removed from the <code>functions</code> list if <code>savedef</code> is <code>false</code> (see below)
and are added to the <code>props</code> lists.
</p>
<p>Functions should not be translated
unless they are fully debugged.
</p>
<p>Expressions are assumed simplified; if they are not, correct but non- optimal code gets
generated.  Thus, the user should not set the <code>simp</code> switch to <code>false</code>
which inhibits simplification of the expressions to be translated.
</p>
<p>The switch <code>translate</code>, if <code>true</code>, causes automatic
translation of a user's function to Lisp.
</p>
<p>Note that translated
functions may not run identically to the way they did before
translation as certain incompatabilities may exist between the Lisp
and Maxima versions.  Principally, the <code>rat</code> function with more than
one argument and the <code>ratvars</code> function should not be used if any
variables are <code>mode_declare</code>'d canonical rational expressions (CRE).
Also the <code>prederror: false</code> setting
will not translate.
</p>
<p><code>savedef</code> - if <code>true</code> will cause the Maxima version of a user
function to remain when the function is <code>translate</code>'d.  This permits the
definition to be displayed by <code>dispfun</code> and allows the function to be
edited.
</p>
<p><code>transrun</code> - if <code>false</code> will cause the interpreted version of all
functions to be run (provided they are still around) rather than the
translated version.
</p>
<p>The result returned by <code>translate</code> is a list of the names of the
functions translated.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>translate_file</b><i> (<var>maxima_filename</var>)</i>
<a name="IDX1322"></a>
</dt>
<dt><u>Function:</u> <b>translate_file</b><i> (<var>maxima_filename</var>, <var>lisp_filename</var>)</i>
<a name="IDX1323"></a>
</dt>
<dd><p>Translates a file of Maxima code into a file of Lisp code.
<code>translate_file</code> returns a list of three filenames:
the name of the Maxima file, the name of the Lisp file, and the name of file
containing additional information about the translation.
<code>translate_file</code> evaluates its arguments.
</p>
<p><code>translate_file (&quot;foo.mac&quot;); load(&quot;foo.LISP&quot;)</code> is the same as
<code>batch (&quot;foo.mac&quot;)</code> except for certain restrictions,
the use of <code>''</code> and <code>%</code>, for example.
</p>
<p><code>translate_file (<var>maxima_filename</var>)</code> translates a Maxima file <var>maxima_filename</var>
into a similarly-named Lisp file.
For example, <code>foo.mac</code> is translated into <code>foo.LISP</code>.
The Maxima filename may include a directory name or names,
in which case the Lisp output file is written
to the same directory from which the Maxima input comes.
</p>
<p><code>translate_file (<var>maxima_filename</var>, <var>lisp_filename</var>)</code> translates
a Maxima file <var>maxima_filename</var> into a Lisp file <var>lisp_filename</var>.
<code>translate_file</code> ignores the filename extension, if any, of <code>lisp_filename</code>;
the filename extension of the Lisp output file is always <code>LISP</code>.
The Lisp filename may include a directory name or names,
in which case the Lisp output file is written to the specified directory.
</p>
<p><code>translate_file</code> also writes a file of translator warning
messages of various degrees of severity.
The filename extension of this file is <code>UNLISP</code>.
This file may contain valuable information, though possibly obscure,
for tracking down bugs in translated code.
The <code>UNLISP</code> file is always written
to the same directory from which the Maxima input comes.
</p>
<p><code>translate_file</code> emits Lisp code which causes
some declarations and definitions to take effect as soon
as the Lisp code is compiled.
See <code>compile_file</code> for more on this topic.
</p>
<p>See also <code>tr_array_as_ref</code>,
<code>tr_bound_function_applyp</code>,
<code>tr_exponent</code>,
<code>tr_file_tty_messagesp</code>, 
<code>tr_float_can_branch_complex</code>,
<code>tr_function_call_default</code>, 
<code>tr_numer</code>,
<code>tr_optimize_max_loop</code>, 
<code>tr_semicompile</code>,
<code>tr_state_vars</code>, 
<code>tr_warnings_get</code>,
<code>tr_warn_bad_function_calls</code>,
<code>tr_warn_fexpr</code>, 
<code>tr_warn_meval</code>,
<code>tr_warn_mode</code>,
<code>tr_warn_undeclared</code>, 
<code>tr_warn_undefined_variable</code>,
and <code>tr_windy</code>.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>transrun</b>
<a name="IDX1324"></a>
</dt>
<dd><p>Default value: <code>true</code>
</p>
<p>When <code>transrun</code> is <code>false</code> will cause the interpreted
version of all functions to be run (provided they are still around)
rather than the translated version.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_array_as_ref</b>
<a name="IDX1325"></a>
</dt>
<dd><p>Default value: <code>true</code>
</p>
<p>If <code>translate_fast_arrays</code> is false, array references in
Lisp code emitted by <code>translate_file</code> are affected by <code>tr_array_as_ref</code>.
When <code>tr_array_as_ref</code> is <code>true</code>,
array names are evaluated,
otherwise array names appear as literal symbols in translated code.
</p>
<p><code>tr_array_as_ref</code> has no effect if <code>translate_fast_arrays</code> is <code>true</code>.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_bound_function_applyp</b>
<a name="IDX1326"></a>
</dt>
<dd><p>Default value: <code>true</code>
</p>
<p>When <code>tr_bound_function_applyp</code> is <code>true</code>, Maxima gives a warning if a bound
variable (such as a function argument) is found being used as a function.
<code>tr_bound_function_applyp</code> does not affect the code generated in such cases.
</p>
<p>For example, an expression such as <code>g (f, x) := f (x+1)</code> will trigger
the warning message.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_file_tty_messagesp</b>
<a name="IDX1327"></a>
</dt>
<dd><p>Default value: <code>false</code>
</p>
<p>When <code>tr_file_tty_messagesp</code> is <code>true</code>,
messages generated by <code>translate_file</code> during translation of a file are displayed
on the console and inserted into the UNLISP file. 
When <code>false</code>, messages about translation of the
file are only inserted into the UNLISP file.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_float_can_branch_complex</b>
<a name="IDX1328"></a>
</dt>
<dd><p>Default value: <code>true</code>
</p>
<p>Tells the Maxima-to-Lisp translator to assume that the functions 
<code>acos</code>, <code>asin</code>, <code>asec</code>, and <code>acsc</code> can return complex results.
</p>
<p>The ostensible effect of <code>tr_float_can_branch_complex</code> is the following.
However, it appears that this flag has no effect on the translator output.
</p>
<p>When it is <code>true</code> then <code>acos(x)</code> is of mode <code>any</code>
even if <code>x</code> is of mode <code>float</code> (as set by <code>mode_declare</code>).
When <code>false</code> then <code>acos(x)</code> is of mode
<code>float</code> if and only if <code>x</code> is of mode <code>float</code>.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_function_call_default</b>
<a name="IDX1329"></a>
</dt>
<dd><p>Default value: <code>general</code>
</p>
<p><code>false</code> means give up and
call <code>meval</code>, <code>expr</code> means assume Lisp fixed arg function.  <code>general</code>, the
default gives code good for <code>mexprs</code> and <code>mlexprs</code> but not <code>macros</code>.
<code>general</code> assures variable bindings are correct in compiled code.  In
<code>general</code> mode, when translating F(X), if F is a bound variable, then it
assumes that <code>apply (f, [x])</code> is meant, and translates a such, with
apropriate warning. There is no need to turn this off.  With the
default settings, no warning messages implies full compatibility of
translated and compiled code with the Maxima interpreter.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_numer</b>
<a name="IDX1330"></a>
</dt>
<dd><p>Default value: <code>false</code>
</p>
<p>When <code>tr_numer</code> is <code>true</code> numer properties are used for
atoms which have them, e.g. <code>%pi</code>.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_optimize_max_loop</b>
<a name="IDX1331"></a>
</dt>
<dd><p>Default value: 100
</p>
<p><code>tr_optimize_max_loop</code> is the maximum number of times the
macro-expansion and optimization pass of the translator will loop in
considering a form.  This is to catch macro expansion errors, and
non-terminating optimization properties.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_semicompile</b>
<a name="IDX1332"></a>
</dt>
<dd><p>Default value: <code>false</code>
</p>
<p>When <code>tr_semicompile</code> is <code>true</code>, <code>translate_file</code> and <code>compfile</code>
output forms which will be macroexpanded but not compiled into machine
code by the Lisp compiler.
</p>
</dd></dl>

<dl>
<dt><u>System variable:</u> <b>tr_state_vars</b>
<a name="IDX1333"></a>
</dt>
<dd><p>Default value:
</p><table><tr><td>&nbsp;</td><td><pre class="example">[transcompile, tr_semicompile, tr_warn_undeclared, tr_warn_meval,
tr_warn_fexpr, tr_warn_mode, tr_warn_undefined_variable,
tr_function_call_default, tr_array_as_ref,tr_numer]
</pre></td></tr></table>
<p>The list of the switches that affect the form of the
translated output.
This information is useful to system people when
trying to debug the translator.  By comparing the translated product
to what should have been produced for a given state, it is possible to
track down bugs.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>tr_warnings_get</b><i> ()</i>
<a name="IDX1334"></a>
</dt>
<dd><p>Prints a list of warnings which have been given by
the translator during the current translation.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_warn_bad_function_calls</b>
<a name="IDX1335"></a>
</dt>
<dd><p>Default value: <code>true</code>
</p>
<p>- Gives a warning when
when function calls are being made which may not be correct due to
improper declarations that were made at translate time.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_warn_fexpr</b>
<a name="IDX1336"></a>
</dt>
<dd><p>Default value: <code>compfile</code>
</p>
<p>- Gives a warning if any FEXPRs are
encountered.  FEXPRs should not normally be output in translated code,
all legitimate special program forms are translated.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_warn_meval</b>
<a name="IDX1337"></a>
</dt>
<dd><p>Default value: <code>compfile</code>
</p>
<p>- Gives a warning if the function
<code>meval</code> gets called.  If <code>meval</code> is called that indicates problems in the
translation.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_warn_mode</b>
<a name="IDX1338"></a>
</dt>
<dd><p>Default value: <code>all</code>
</p>
<p>- Gives a warning when variables are
assigned values inappropriate for their mode.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_warn_undeclared</b>
<a name="IDX1339"></a>
</dt>
<dd><p>Default value: <code>compile</code>
</p>
<p>- Determines when to send
warnings about undeclared variables to the TTY.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_warn_undefined_variable</b>
<a name="IDX1340"></a>
</dt>
<dd><p>Default value: <code>all</code>
</p>
<p>- Gives a warning when
undefined global variables are seen.
</p>
</dd></dl>

<dl>
<dt><u>Option variable:</u> <b>tr_windy</b>
<a name="IDX1341"></a>
</dt>
<dd><p>Default value: <code>true</code>
</p>
<p>- Generate helpful comments and
programming hints.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>compile_file</b><i> (<var>filename</var>)</i>
<a name="IDX1342"></a>
</dt>
<dt><u>Function:</u> <b>compile_file</b><i> (<var>filename</var>, <var>compiled_filename</var>)</i>
<a name="IDX1343"></a>
</dt>
<dt><u>Function:</u> <b>compile_file</b><i> (<var>filename</var>, <var>compiled_filename</var>, <var>lisp_filename</var>)</i>
<a name="IDX1344"></a>
</dt>
<dd><p>Translates the Maxima file <var>filename</var> into Lisp,
executes the Lisp compiler,
and, if the translation and compilation succeed, loads the compiled code into Maxima.
</p>
<p><code>compile_file</code> returns a list of the names of four files:
the original Maxima file, the Lisp translation, notes on translation, and the compiled code.
If the compilation fails,
the fourth item is <code>false</code>.
</p>
<p>Some declarations and definitions take effect as soon
as the Lisp code is compiled (without loading the compiled code).
These include functions defined with the <code>:=</code> operator,
macros define with the <code>::=</code> operator, <code>alias</code>, <code>declare</code>,
<code>define_variable</code>,  <code>mode_declare</code>,
and 
<code>infix</code>, <code>matchfix</code>,
<code>nofix</code>, <code>postfix</code>, <code>prefix</code>,
and <code>compfile</code>.
</p>
<p>Assignments and function calls are not evaluated until the compiled code is loaded.
In particular, within the Maxima file,
assignments to the translation flags (<code>tr_numer</code>, etc.) have no effect on the translation.
</p>

<p><var>filename</var> may not contain <code>:lisp</code> statements.
</p>
<p><code>compile_file</code> evaluates its arguments.
</p>
</dd></dl>

<dl>
<dt><u>Function:</u> <b>declare_translated</b><i> (<var>f_1</var>, <var>f_2</var>, ...)</i>
<a name="IDX1345"></a>
</dt>
<dd><p>When translating a file of Maxima code
to Lisp, it is important for the translator to know which functions it
sees in the file are to be called as translated or compiled functions,
and which ones are just Maxima functions or undefined.  Putting this
declaration at the top of the file, lets it know that although a symbol
does which does not yet have a Lisp function value, will have one at
call time. <code>(MFUNCTION-CALL fn arg1 arg2 ...)</code> is generated when
the translator does not know fn is going to be a Lisp function.
</p>
</dd></dl>


<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC155" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="maxima_41.html#SEC162" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="maxima.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="maxima_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="maxima_72.html#SEC264" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="maxima_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
 <font size="-1">
  This document was generated by <em>Robert Dodier</em> on <em>September, 20 2006</em> using <a href="http://texi2html.cvshome.org/"><em>texi2html 1.76</em></a>.
 </font>
 <br>

</p>
</body>
</html>