246 lines
12 KiB
HTML
246 lines
12 KiB
HTML
|
<!DOCTYPE HTML PUBLIC "-//W3O//DTD W3 HTML 2.0//EN">
|
||
|
|
<!Converted with LaTeX2HTML 0.6.5 (Tue Nov 15 1994) by Nikos Drakos (nikos@cbl.leeds.ac.uk), CBLU, University of Leeds >
|
||
|
|
<HEAD>
|
||
|
|
<TITLE> 1.2.5. Descriptions of Functions and Other Entities</TITLE>
|
||
|
|
</HEAD>
|
||
|
|
<BODY>
|
||
|
|
<meta name="description" value=" Descriptions of Functions and Other Entities">
|
||
|
|
<meta name="keywords" value="clm">
|
||
|
|
<meta name="resource-type" value="document">
|
||
|
|
<meta name="distribution" value="global">
|
||
|
|
<P>
|
||
|
|
<b>Common Lisp the Language, 2nd Edition</b>
|
||
|
|
<BR> <HR><A NAME=tex2html1632 HREF="node13.html"><IMG ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME=tex2html1630 HREF="node7.html"><IMG ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME=tex2html1624 HREF="node11.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME=tex2html1634 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME=tex2html1635 HREF="index.html"><IMG ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
|
||
|
|
<B> Next:</B> <A NAME=tex2html1633 HREF="node13.html"> The Lisp Reader</A>
|
||
|
|
<B>Up:</B> <A NAME=tex2html1631 HREF="node7.html"> Notational Conventions</A>
|
||
|
|
<B> Previous:</B> <A NAME=tex2html1625 HREF="node11.html"> Errors</A>
|
||
|
|
<HR> <P>
|
||
|
|
<H2><A NAME=SECTION00525000000000000000> 1.2.5. Descriptions of Functions and Other Entities</A></H2>
|
||
|
|
<P>
|
||
|
|
<A NAME=FUNCTIONHEADERNOTATIONSECTION>Functions,</A>
|
||
|
|
variables, named constants, special forms, and macros are described
|
||
|
|
using a distinctive typographical format.
|
||
|
|
Table <A HREF="node12.html#SampleFunctionDescription">1-1</A> illustrates the manner
|
||
|
|
in which Common Lisp functions are documented.
|
||
|
|
The first line specifies the name of the function,
|
||
|
|
the manner in which it accepts arguments,
|
||
|
|
and the fact that it is a function.
|
||
|
|
If the function takes many arguments, then the names of the arguments
|
||
|
|
may spill across two or three lines.
|
||
|
|
The paragraphs following this standard header
|
||
|
|
explain the definition and uses of the function and often
|
||
|
|
present examples or related functions.
|
||
|
|
<P>
|
||
|
|
Sometimes two or more related functions are explained in a single
|
||
|
|
combined description. In this situation the headers for all the
|
||
|
|
functions appear together, followed by the combined description.
|
||
|
|
<P>
|
||
|
|
In general, actual code (including actual names of functions)
|
||
|
|
appears in this typeface: <tt>(cons a b)</tt>.
|
||
|
|
Names that stand for pieces of code (metavariables) are written in
|
||
|
|
<i>italics</i>. In a function description, the names of the parameters appear
|
||
|
|
in italics for expository purposes. The word <tt>&optional</tt> in the
|
||
|
|
list of parameters indicates that all arguments past that point are
|
||
|
|
optional; the default values for the parameters are described in the
|
||
|
|
text. Parameter lists may also contain <tt>&rest</tt>, indicating that an
|
||
|
|
indefinite number of arguments may appear, or <tt>&key</tt>, indicating
|
||
|
|
that keyword arguments are accepted.
|
||
|
|
(The <tt>&optional</tt>/<tt>&rest</tt>/<tt>&key</tt>
|
||
|
|
syntax is actually used in Common Lisp function definitions for these purposes.)
|
||
|
|
<P>
|
||
|
|
<pre><A NAME=SampleFunctionDescription> </A>
|
||
|
|
----------------------------------------------------------------
|
||
|
|
Table 1-1: Sample Function Description
|
||
|
|
|
||
|
|
<b>[Function]</b>
|
||
|
|
sample-function <i>arg1</i> <i>arg2</i> &optional <i>arg3</i> <i>arg4</i>
|
||
|
|
|
||
|
|
The function sample-function adds together <i>arg1</i> and <i>arg2</i>,
|
||
|
|
and then multiplies the result by <i>arg3</i>. If <i>arg3</i> is not
|
||
|
|
provided or is nil, the multiplication isn't done.
|
||
|
|
sample-function then returns a list whose first element is
|
||
|
|
this result and whose section element is <i>arg4</i> (which
|
||
|
|
defaults to the symbol foo). For example:
|
||
|
|
|
||
|
|
(sample-function 3 4) => (7 foo)
|
||
|
|
(sample-function 1 2 2 'bar) => (6 bar)
|
||
|
|
|
||
|
|
In general, (sample-function <i>x</i> <i>y</i>) == (list (+ <i>x</i> <i>y</i>) 'foo).
|
||
|
|
|
||
|
|
----------------------------------------------------------------
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
<pre><A NAME=SampleVariableDescription> </A>
|
||
|
|
----------------------------------------------------------------
|
||
|
|
Table 1-2: Sample Variable Description
|
||
|
|
|
||
|
|
<b>[Variable]</b>
|
||
|
|
*sample-variable*
|
||
|
|
|
||
|
|
The variable *sample-variable* specifies how many times the
|
||
|
|
special form sample-special-form should iterate. The value
|
||
|
|
should always be a non-negative integer or nil (which means
|
||
|
|
iterate indefinitely many times). The initial value is 0
|
||
|
|
(meaning no iterations).
|
||
|
|
|
||
|
|
----------------------------------------------------------------
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
<pre><A NAME=SampleConstantDescription> </A>
|
||
|
|
----------------------------------------------------------------
|
||
|
|
Table 1-3: Sample Constant Description
|
||
|
|
|
||
|
|
<b>[Constant]</b>
|
||
|
|
sample-constant
|
||
|
|
|
||
|
|
The named constant sample-constant has as its value the
|
||
|
|
height of the terminal screen in furlongs times the base-2
|
||
|
|
logarithm of the implementation's total disk capacity in
|
||
|
|
bytes, as a floating-point number.
|
||
|
|
|
||
|
|
----------------------------------------------------------------
|
||
|
|
</pre>
|
||
|
|
<P>
|
||
|
|
Table <A HREF="node12.html#SampleVariableDescription">1-2</A> illustrates the manner in
|
||
|
|
which a global variable is documented. The first line specifies the
|
||
|
|
name of the variable and the fact that it is a variable.
|
||
|
|
Purely as a matter of convention, all global variables used
|
||
|
|
by Common Lisp have names beginning and ending with an asterisk.
|
||
|
|
<P>
|
||
|
|
Table <A HREF="node12.html#SampleConstantDescription">1-3</A> illustrates the manner in
|
||
|
|
which a named constant is documented. The first line specifies the
|
||
|
|
name of the constant and the fact that it is a constant.
|
||
|
|
(A constant is just like a global variable, except that it is
|
||
|
|
an error ever to alter its value or to bind it to a new value.)
|
||
|
|
<P>
|
||
|
|
<pre><A NAME=SampleSpecialFormDescription> </A>
|
||
|
|
----------------------------------------------------------------
|
||
|
|
Table 1-4: Sample Special Form Description
|
||
|
|
|
||
|
|
<b>[Special Form]</b>
|
||
|
|
sample-special-form [<i>name</i>] ({<i>var</i>}*) {<i>form</i>}+
|
||
|
|
|
||
|
|
This evaluates each form in sequence as an implicit progn,
|
||
|
|
and does this as many times as specified by the global
|
||
|
|
variable *sample-variable*. Each variable <i>var</i> is
|
||
|
|
bound and initialized to 43 before the first iteration, and
|
||
|
|
unbound after the last iteration. The name <i>name</i>, if
|
||
|
|
supplied, may be used in a return-from form to exit from the
|
||
|
|
loop prematurely. If the loop ends normally,
|
||
|
|
sample-special-form returns nil. For example:
|
||
|
|
|
||
|
|
(setq *sample-variable* 3)
|
||
|
|
(sample-special-form () <i>form1</i> <i>form2</i>)
|
||
|
|
|
||
|
|
This evaluates <i>form1</i>, <i>form2</i>, <i>form1</i>, <i>form2</i>, <i>form1</i>, <i>form2</i>,
|
||
|
|
in that order.
|
||
|
|
|
||
|
|
----------------------------------------------------------------
|
||
|
|
</pre>
|
||
|
|
<p>
|
||
|
|
<pre><A NAME=SampleMacroDescription> </A>
|
||
|
|
----------------------------------------------------------------
|
||
|
|
Table 1-5: Sample Macro Description
|
||
|
|
|
||
|
|
<b>[Macro]</b>
|
||
|
|
sample-macro <i>var</i> <b>[[</b> <i>declaration</i>* | <i>doc-string</i> <b>]]</b> {<i>tag</i> | <i>statement</i>}*
|
||
|
|
|
||
|
|
This evaluates the statements as a prog body, with the
|
||
|
|
variable <i>var</i> bound to 43.
|
||
|
|
|
||
|
|
(sample-macro x (return (+ x x))) => 86
|
||
|
|
(sample-macro <i>var</i> . <i>body</i>) -> (prog ((<i>var</i> 43)) . <i>body</i>)
|
||
|
|
----------------------------------------------------------------
|
||
|
|
</pre>
|
||
|
|
<P>
|
||
|
|
Tables <A HREF="node12.html#SampleSpecialFormDescription">1-4</A>
|
||
|
|
and <A HREF="node12.html#SampleMacroDescription">1-5</A> illustrate the documentation
|
||
|
|
of special forms and macros, which are closely related in purpose.
|
||
|
|
These are very different from functions.
|
||
|
|
Functions are called according to a single, specific, consistent syntax;
|
||
|
|
the <tt>&optional</tt>/<tt>&rest</tt>/<tt>&key</tt> syntax specifies how the function uses its arguments
|
||
|
|
internally but does not affect the syntax of a call.
|
||
|
|
In contrast, each special form or macro can have its own idiosyncratic syntax.
|
||
|
|
It is by special forms and macros that the syntax of Common Lisp is defined
|
||
|
|
and extended.
|
||
|
|
<P>
|
||
|
|
In the description of a special form or macro, an italicized word names a
|
||
|
|
corresponding part of the form that invokes the special form or macro.
|
||
|
|
Parentheses stand for themselves and should be
|
||
|
|
written as such when invoking the special form or macro.
|
||
|
|
Brackets, braces, stars, plus signs, and vertical bars are metasyntactic
|
||
|
|
marks.
|
||
|
|
Brackets,
|
||
|
|
[ and ], indicate that what they enclose is optional
|
||
|
|
(may appear zero times or one time in that place); the square
|
||
|
|
brackets should not be written in code.
|
||
|
|
Braces, { and }, simply parenthesize what they enclose
|
||
|
|
but may be followed by a star, *, or a plus sign, +;
|
||
|
|
a star indicates that what the braces enclose may appear any number of times
|
||
|
|
(including zero, that is, not at all), whereas a plus sign indicates
|
||
|
|
that what the braces enclose may appear any non-zero number of times
|
||
|
|
(that is, must appear at least once). Within braces or brackets,
|
||
|
|
a vertical bar, <b>|</b>, separates mutually exclusive choices.
|
||
|
|
In summary, the notation {<i>x</i>}* means zero or more occurrences
|
||
|
|
of <i>x</i>, the notation {<i>x</i>}+ means one or more occurrences
|
||
|
|
of <i>x</i>, and the notation [<i>x</i>] means zero or one occurrence
|
||
|
|
of <i>x</i>. These notations are also used for syntactic
|
||
|
|
descriptions expressed as BNF-like productions, as
|
||
|
|
in table <A HREF="node189.html#NUMBERSYNTAXTABLE">22-2</A>.
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
Double brackets, <b>[[</b> and <b>]]</b>, indicate that any number of the
|
||
|
|
alternatives enclosed may be used, and those used
|
||
|
|
may occur in any order, but each
|
||
|
|
alternative may be used at most once unless followed by a star.
|
||
|
|
For example,
|
||
|
|
<PRE><TT> <i>p</i> <b>[[</b>x | {y}* | z<b>]]</b> <i>q</i>
|
||
|
|
<P>
|
||
|
|
</TT></PRE>
|
||
|
|
means that
|
||
|
|
at most one <i>x</i>, any number of <i>y</i>'s, and at most one <i>z</i>
|
||
|
|
may appear between the mandatory occurrences of <i>p</i>
|
||
|
|
and <i>q</i>, and those that appear may be in any order.
|
||
|
|
<P>
|
||
|
|
A downward arrow, <IMG SRC="gif/downarrow.gif" ALT="?" ALIGN=bottom>, indicates a form of syntactic indirection
|
||
|
|
that helps to make <br><b>[[</b> <b>]]</b> notation more readable. If <i>X</i> is
|
||
|
|
some non-terminal symbol occurring on the left-hand side of some BNF
|
||
|
|
production, then the right-hand
|
||
|
|
side of that production is to be textually substituted for any occurrence
|
||
|
|
of <IMG SRC="gif/downarrow.gif" ALT="?" ALIGN=bottom><i>X</i>. Thus the two fragments
|
||
|
|
<PRE>
|
||
|
|
<i>p</i> <b>[[</b><IMG SRC="gif/downarrow.gif" ALT="?" ALIGN=bottom>xyz-mixture<b>]]</b> <i>q</i>
|
||
|
|
<i>xyz-mixture</i> ::= <i>x</i> | {y}* | <i>z</i>
|
||
|
|
</PRE>
|
||
|
|
are together equivalent to the previous example.
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<P>
|
||
|
|
<hr>
|
||
|
|
<b>HTML Note:</b> In the WWW version of this book, we have
|
||
|
|
substituted a question mark (?) for the downward arrow (<IMG
|
||
|
|
SRC="gif/downarrow.gif" ALT="?" ALIGN=bottom>).
|
||
|
|
<hr>
|
||
|
|
<P>
|
||
|
|
In the last example in table <A HREF="node12.html#SampleMacroDescription">1-5</A>, notice the
|
||
|
|
use of dot notation. The dot appearing in the expression
|
||
|
|
<tt>(sample-macro <i>var</i> . <i>body</i>)</tt> means that the name <i>body</i> stands
|
||
|
|
for a list of forms, not just a single form, at the end of a list. This
|
||
|
|
notation is often used in examples.
|
||
|
|
<P>
|
||
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
||
|
|
In the heading line in table <A HREF="node12.html#SampleMacroDescription">1-5</A>, notice the
|
||
|
|
use of <b>[[ ]]</b> notation to indicate that any number of declarations
|
||
|
|
may appear but at most one documentation string (which may appear before,
|
||
|
|
after, or somewhere in the middle of any declarations).
|
||
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
||
|
|
<BR> <HR><A NAME=tex2html1632 HREF="node13.html"><IMG ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME=tex2html1630 HREF="node7.html"><IMG ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME=tex2html1624 HREF="node11.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME=tex2html1634 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME=tex2html1635 HREF="index.html"><IMG ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
|
||
|
|
<B> Next:</B> <A NAME=tex2html1633 HREF="node13.html"> The Lisp Reader</A>
|
||
|
|
<B>Up:</B> <A NAME=tex2html1631 HREF="node7.html"> Notational Conventions</A>
|
||
|
|
<B> Previous:</B> <A NAME=tex2html1625 HREF="node11.html"> Errors</A>
|
||
|
|
<HR> <P>
|
||
|
|
<HR>
|
||
|
|
<P><ADDRESS>
|
||
|
|
AI.Repository@cs.cmu.edu
|
||
|
|
</ADDRESS>
|
||
|
|
</BODY>
|