Package: cl-utilities Version: 1.2.4-1 Severity: minor Tags: patch The documentation for the once-only macro should be written instead of pointing to a newsgroup discussion describing it. Here is a patch that adds the relevant description: Index: Source/doc/once-only.html =================================================================== --- Source.orig/doc/once-only.html 2006-08-06 23:22:30.480823552 +0200 +++ Source/doc/once-only.html 2006-08-06 23:33:13.696039976 +0200 @@ -11,29 +11,57 @@ <p> -<p><b>once-only</b> <i>(name*) form*</i> +<p><b>once-only</b> <i>(name*) body-form*</i> <p> <p><b>Arguments and Values:</b><p> <p> <i>name</i>---a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/glo_s.html#symbol"><i>symbol</i></a></a>. <p> -<i>form</i>---a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/glo_f.html#form"><i>form</i></a></a>. <p> +<i>body-form</i>---a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/glo_f.html#form"><i>form</i></a></a>. <p> <p> <p><b>Description:</b><p> <p>Meant to be used in macro code, <b>once-only</b> guards against -multiple evaluation of its arguments in macroexpansion code. Any -concise description would be far too vague to grasp, but <a -href="http://groups.google.com/group/comp.lang.lisp/browse_frm/thread/1783554653afad7f/f6357129c8c1c002?rnum=1&_done=%2Fgroup%2Fcomp.lang.lisp%2Fbrowse_frm%2Fthread%2F1783554653afad7f%2F940b6ebd2d1757f4%3F#doc_f6357129c8c1c002">this -thread on comp.lang.lisp</a> does a decent job of explaining what -<b>once-only</b> does. - -<p><p><b>Notes:</b></p> - -<p>The description here is frustratingly non-descriptive, and I -apologize for that. If you understand <b>once-only</b> and can give a -better explanation, I would be very grateful—not to mention -completely awed. +multiple evaluation of its arguments in macroexpansion code.</p> + +<p><b>once-only</b> generates a Lisp form that evaluates each lexical +variable named by the symbols given as <i>name</i> arguments to +once-only, and evaluates the body forms in a lexical environment where +these results are bound to their respective originating symbol.</p> + +<p>That is, if the only <i>name</i> argument were the single 'alpha +symbol, the body forms would be evaluated in a lexical environment +where 'alpha is bound to the result of the evaluation of alpha in the +lexical environment of the generated Lisp form.</p> + +<p>Example:</p> + +<p>With the following 3x macro:</p> + +<pre>(defmacro 3x (x) + `(+ ,x ,x ,x))</pre> + +<p>These three forms evaluate to the same result because the form +given as <i>x</i> argument is referencially transparent (i.e. it +yields the same result each time it's evaluated):</p> + +<pre>(3x 2) === 6 +(3x (1+ 1)) === 6 +(let ((a 1)) (3x (1+ a))) === 6</pre> + +<p>But the following form has an argument that has side-effects and has different results for each of the three +times it will be evaluated:</p> + +<pre>(let ((a 1)) (3x (incf a))) === 9</pre> + +<p>The problem is solved by protecting the body of the macro with +once-only:</p> + +<pre>(defmacro 3x (x) + (once-only (x) + `(+ ,x ,x ,x))) + +(let ((a 1)) (3x (incf a))) === 6</pre> <p class="footer"><hr><a href="index.html">Manual Index</a></p> It applies to 1.2.4-1. -- System Information: Debian Release: 4.0 APT prefers testing APT policy: (990, 'testing'), (501, 'stable'), (500, 'unstable'), (500, 'stable') Architecture: i386 (i686) Shell: /bin/sh linked to /bin/bash Kernel: Linux 2.6.17-2-k7 Locale: LANG=fr_FR@euro, LC_CTYPE=fr_FR@euro (charmap=ISO-8859-15) Versions of packages cl-utilities depends on: ii common-lisp-controller 6.8 This is a Common Lisp source and c cl-utilities recommends no packages. -- no debconf information -- nowhere.man@levallois.eu.org OpenPGP 0xD9D50D8A