<h1id="title-non-xs"><ahref="index.html">The Common Lisp Cookbook</a>– Functions</h1>
<!-- Announcement we can keep for 1 month or more. I remove it and re-add it from time to time. -->
<pclass="announce">
📹 <ahref="https://www.udemy.com/course/common-lisp-programming/?couponCode=6926D599AA-LISP4ALL">NEW! Learn Lisp in videos and support our contributors with this 40% discount.</a>
</p>
<pclass="announce-neutral">
📕 <ahref="index.html#download-in-epub">Get the EPUB and PDF</a>
<p>Note that <code>(values)</code> with no values returns… no values at all.</p>
<p><strong>multiple-value-list</strong></p>
<p>While we are at it: <ahref="http://www.lispworks.com/documentation/HyperSpec/Body/m_mult_1.htm">multiple-value-list</a> turns multiple values to a list:</p>
<h2id="calling-functions-programmatically-funcall-and-apply">Calling functions programmatically: <code>funcall</code> and <code>apply</code></h2>
<p><code>funcall</code> is to be used with a known number of arguments, when <code>apply</code>
can be used on a list, for example from <code>&rest</code>:</p>
<pre><codeclass="language-lisp">(funcall #'+ 1 2)
(apply #'+ '(1 2))
</code></pre>
<h3id="referencing-functions-by-name-single-quote--or-sharpsign-quote-">Referencing functions by name: single quote <code>'</code> or sharpsign-quote <code>#'</code>?</h3>
<p>In the example above, we used <code>#'</code>, but a single quote also works, and
we can encounter it in the wild. Which one to use?</p>
<p>It is generally safer to use <code>#'</code>, because it respects lexical scope. Observe:</p>
<pre><codeclass="language-lisp">(defun foo (x)
(* x 100))
(flet ((foo (x) (1+ x)))
(funcall #'foo 1))
;; => 2, as expected
;;
;; But:
(flet ((foo (x) (1+ x)))
(funcall 'foo 1))
;; => 100
</code></pre>
<p><code>#'</code> is actually the shorthand for <code>(function …)</code>:</p>
<pre><codeclass="language-lisp">(function +)
;; #<FUNCTION +>
(flet ((foo (x) (1+ x)))
(print (function foo))
(funcall (function foo) 1))
;; #<FUNCTION (FLET FOO) {1001C0ACFB}>
;; 2
</code></pre>
<p>Using <code>function</code> or the <code>#'</code> shorthand allows us to refer to local
functions. If we pass instead a symbol to <code>funcall</code>, what is
called is always the function named by that symbol in the <em>global environment</em>.</p>
<h2id="higher-order-functions-functions-that-return-functions">Higher order functions: functions that return functions</h2>
<p>Writing functions that return functions is simple enough:</p>
<pre><codeclass="language-lisp">(defun adder (n)
(lambda (x) (+ x n)))
;; ADDER
</code></pre>
<p>Here we have defined the function <code>adder</code> which returns an <em>object</em> of <em>type</em><ahref="http://www.lispworks.com/documentation/HyperSpec/Body/t_fn.htm"><code>function</code></a>.</p>
<p>To call the resulting function, we must use <code>funcall</code> or <code>apply</code>:</p>
<p>Trying to call it right away leads to an illegal function call:</p>
<pre><codeclass="language-lisp">((adder 3) 5)
In: (ADDER 3) 5
((ADDER 3) 5)
Error: Illegal function call.
</code></pre>
<p>Indeed, CL has different <em>namespaces</em> for functions and variables, i.e. the same <em>name</em> can refer to different things depending on its position in a form that’s evaluated.</p>
<pre><codeclass="language-lisp">;; The symbol foo is bound to nothing:
<p>To simplify a bit, you can think of each symbol in CL having (at least) two “cells” in which information is stored. One cell - sometimes referred to as its <em>value cell</em> - can hold a value that is <em>bound</em> to this symbol, and you can use <ahref="http://www.lispworks.com/documentation/HyperSpec/Body/f_boundp.htm"><code>boundp</code></a> to test whether the symbol is bound to a value (in the global environment). You can access the value cell of a symbol with <ahref="http://www.lispworks.com/documentation/HyperSpec/Body/f_symb_5.htm"><code>symbol-value</code></a>.</p>
<p>The other cell - sometimes referred to as its <em>function cell</em> - can hold the definition of the symbol’s (global) function binding. In this case, the symbol is said to be <em>fbound</em> to this definition. You can use <ahref="http://www.lispworks.com/documentation/HyperSpec/Body/f_fbound.htm"><code>fboundp</code></a> to test whether a symbol is fbound. You can access the function cell of a symbol (in the global environment) with <ahref="http://www.lispworks.com/documentation/HyperSpec/Body/f_symb_1.htm"><code>symbol-function</code></a>.</p>
<p>Now, if a <em>symbol</em> is evaluated, it is treated as a <em>variable</em> in that its value cell is returned (just <code>foo</code>). If a <em>compound form</em>, i.e. a <em>cons</em>, is evaluated and its <em>car</em> is a symbol, then the function cell of this symbol is used (as in <code>(foo 3)</code>).</p>
<p>In Common Lisp, as opposed to Scheme, it is <em>not</em> possible that the car of the compound form to be evaluated is an arbitrary form. If it is not a symbol, it <em>must</em> be a <em>lambda expression</em>, which looks like <code>(lambda </code><em>lambda-list</em><em>form*</em><code>)</code>.</p>
<p>This explains the error message we got above - <code>(adder 3)</code> is neither a symbol nor a lambda expression.</p>
<p>If we want to be able to use the symbol <code>*my-fun*</code> in the car of a compound form, we have to explicitly store something in its <em>function cell</em> (which is normally done for us by the macro <ahref="http://www.lispworks.com/documentation/HyperSpec/Body/m_defun.htm"><code>defun</code></a>):</p>
<pre><codeclass="language-lisp">;;; continued from above
(format t "current name is now ~a~&" new-value))
(setf (hello) "Alice")
;; hello Alice
;; current name is now Alice
;; NIL
</code></pre>
<p><aname="curry"></a></p>
<h2id="currying">Currying</h2>
<h3id="concept">Concept</h3>
<p>A related concept is that of <em><ahref="https://en.wikipedia.org/wiki/Currying">currying</a></em> which you might be familiar with if you’re coming from a functional language. After we’ve read the last section that’s rather easy to implement:</p>
