Edit ``CMUCL Hints''

A collection of miscellaneous hints and tips for *(CMUCL) users - some also apply to the *(CMUCL) spin-off, *(SBCL).

<h3>Informative top-level prompt</h3>
<pre>
Courtesy of Paul Foley:

FWIW, I like to add

(in-package "COMMON-LISP")
  
  (defvar *last-package* nil)
  (defvar *cached-prompt*)
  
  (defun tpl-prompt ()
    (unless (eq *last-package* *package*)
      (setf *cached-prompt*
        (concatenate 'string (or (first (package-nicknames *package*))
                                 (package-name *package*))
                             "> "))
      (setf *last-package* *package*))
    *cached-prompt*)

(setf *prompt* #'tpl-prompt)

to my lisp.core, so I get a "USER> " prompt that changes as I change
  packages instead of the horrible default "* " prompt.
</pre>

Correct package name for CMUCL 19a changes
<pre>
(in-package "LISP")
</pre>

To achieve the same effect in SBCL, use:

<pre>
(defvar *last-package* nil)
(defvar *cached-prompt* nil)
  
(defun package-prompt (stream)
  (unless (eq *last-package* *package*)
    (setf *cached-prompt*
	  (concatenate 'string (or (first (package-nicknames *package*))
				   (package-name *package*))
		       "> "))
    (setf *last-package* *package*))
  (terpri)
  (princ *cached-prompt* stream))

(setf sb-int:*repl-prompt-fun* #'package-prompt)
</pre>

<h4>Using the prompt with ilisp</h4>
If you want to use the prompt above in a ilisp buffer, add the following
to you emacs startup-file (.emacs):

<pre>
(add-hook 'cmulisp-hook
          (lambda ()
            (setq comint-prompt-regexp
                  "^\$[0-9]+\\]+\\|\\*\\|[-a-zA-Z0-9]*\\[[0-9]+\\]:\\|[-A-Z0-9]*>\$ ")
            ))
</pre>

<h3>Turning off GC messages</h3>

... is as easy as setting <tt>ext:*gc-verbose*</tt> to <tt>NIL</tt>.

<h3>Behaviour of setq at top-level</h3>

When 
<pre>
(setq foo "bar")
</pre>
is entered at top-level, <tt>foo</tt> is declared special automagically.
The variable <tt>ext:*top-level-auto-declare*</tt> can be used to change this behaviour;
see <pre>(describe 'ext:*top-level-auto-declare*)</pre> for details.

<h3>Undoing a special declaration</h3>

If you find that you've accidentally created a special, you can undo it.  CMUCL keeps this information in a database you can query/modify using <tt>ext:info</tt>.
<pre>
* (setf x nil)
Warning:  Declaring X special.

NIL

;; Uh oh
* (ext:info :variable :kind 'x)
:SPECIAL
T

;; This changes X back to a lexical
* (setf (ext:info :variable :kind 'x) :global)
:GLOBAL
</pre>

This works on SBCL too, using <tt>sb-ext:info</tt>

<h3>Using the MOP</h3>

The MOP in CMUCL is based on PCL and works pretty much like AMOP describes.
There is however an oddity with it that has to do with ``wrapper'' classes,
the details of which I (dan) unfortunately can't remember (so, somebody please
edit this).  Anyway, a reasonable fix is to work in a package that shadows
a bunch of symbols from PCL instead of picking up the default versions in COMMON-LISP :

<pre>
(defpackage "MY-PACKAGE"
  (:shadowing-import-from PCL FIND-CLASS CLASS-NAME BUILT-IN-CLASS CLASS-OF)
   ... )
</pre>

<h3>Running Lisp programs from the shell prompt</h3>

Note that this works on Linux systems only (tested on Slackware 7.0 by the original poster). Depends on having a kernel compiled with the binfmt_misc module enabled, and root access to setup binfmt_misc.  Any user can run the scripts.

<pre>
From: "Vladimir V. Zolotych" <gsmith@eurocom.od.ua>
Subject: Re: echo program
Newsgroups: comp.lang.lisp
Date: Wed, 28 Feb 2001 20:19:54 +0200
Organization: DCS-EuroCom ISP

Here is the summary (Thanks to Paul Foley and
Rudolf Schlatte)

Using Slackware 7.0

The CL echo program (file ECHO.lisp)

(loop for arg in *command-line-strings* as i upfrom 0 do
      (format t "~&arg[~D] = ~S" i arg))
(terpri)

Shell script (file /usr/local/lib/batch)
#!/bin/sh
exec /usr/local/bin/lisp -batch -load $*

Settings for binfmt_misc
  # cd /proc/sys/fs/binfmt_misc/
  # echo ':CMUCL:M::FASL FILE::/usr/local/lib/batch:' >register

Running ECHO.x86f

$ echo.x86f 1 2 3
; Loading #p"/home/vlz/.cmucl-init.lisp".
; Loading #p"/home/vlz/cmucl/echo/echo.x86f".
arg[0] = "/usr/local/bin/lisp"
arg[1] = "-batch"
arg[2] = "-load"
arg[3] = "./echo.x86f"
arg[4] = "1"
arg[5] = "2"
arg[6] = "3"
$

-- 
Vladimir Zolotych                         gsmith@eurocom.od.ua
</pre>

(also see <a href="http://users.actrix.co.nz/mycroft/runlisp.html">this page</a>)

<HR>

Note that it'd be even better to use <CODE>${1+"$@"}</code> instead
of <CODE>$*</code> in the shell script to pass through all the
parameters untouched.

Explanation:

<P><CODE>$*</code> first concatenates all parameters, separating
them with space (the first character of <CODE>$IFS</code>, in fact),
and after that, splits them again according to <CODE>$IFS</code>.
My suggestion does NOT do this. This matters when some parameters
contain whitespace, such as<BR>
<CODE>/some/program -name 'Hannah Schroeter'</code><BR>

-- Hannah Schr?ter <A HREF="mailto:hannah@schlund.de"><CODE>hannah@schlund.de</code></a>, 22 May 2001

<HR>

Note that debian provides a wrapper ``cmucl-run'' with the cmucl package, which can be used with binfmt-support for binfmt_misc goodness.

<HR>
<h3>CMUCL shell scripts</h3>

This is an alternative method to the linux-specific binfmt_misc method above, which should work on all Unix platforms. It consists of using a small trampoline program which invokes the CMUCL runtime with a rewritten argv. Your shell script looks something like

<pre class=code>
   #!/usr/bin/cmucl-trampoline \
   -quiet -batch -noinit
   !#

(format t "~&Hello, world!~%")
</pre>

You need to <a href = "http://www.chez.com/emarsden/downloads/">download</a> the cmucl-trampoline program, and your image must contain a reader macro which treats <tt>#!..!#</tt> as comments (there is example lisp in the code).

Another way relies on your shell automatically interpreting executable files not marked with #! itself:
<pre class=code>
":" ; exec lisp -load "$0" -eval '(quit)'
</pre>
or, to compile it first:
<pre class=code>
":" ; exec lisp -eval "(compile-file \"$0\")" -load `basename $0 .lisp`.x86f -eval '(quit)'
</pre>

Here is what I (_(Erik Enge)) use to write Lisp shellscripts:

<pre class="code">
#!/bin/sh
# -*- mode: sh -*-

# $Id: runlisp,v 1.3 2003/04/22 02:33:53 erik Exp $
# $Source: /home/cvsd/repo/bin/runlisp,v $

# A handy script to run Lisp as shellscripts.  In the top of your
# file, put:
#
#  #!/usr/bin/env runlisp
#
# and stick runlisp (this script) somewhere in your path.  Then you
# can have regular-looking shellscripts that are written in Lisp.

# If you have another Lisp implementation and know what arguments to
# pass to it for this to work, feel free to add it and send me
# (erik@nittin.net) the patch.

if [ -f /usr/bin/sbcl ]; then
   /usr/bin/sbcl --noinform --disable-debugger --eval '(set-dispatch-macro-character #\# #\! (lambda (stream bang number) (declare (ignore bang number)) (read-line stream) t))' --load $1 --eval '(quit)'
elif [ -f /usr/bin/lisp ]; then
   /usr/bin/lisp -quiet -batch -noinit -eval '(set-dispatch-macro-character #\# #\! (lambda (stream bang number) (declare (ignore bang number)) (read-line stream) t))' -load $1 -eval '(quit)'
else
   echo "$0: could not find a Lisp I know how to call"
fi

</pre>

<hr>

<h3>CLX over ssh-forwarded displays</h3>

The standard _(CLX) function <tt>OPEN-DISPLAY</tt> doesn't correctly extract the display number from the <tt>DISPLAY</tt> environment variable. This is a problem you might run into when using CLX on an ssh-forwarded X11 session. Indeed, ssh typically sets <tt>$DISPLAY</tt> to <tt>remotehost:10</tt>, and forwards port 6010 on the remote host to port 6000 (or whatever port the local X11 server is running on) on the local host. CLX will unsuccessfully try to connect to <tt>remotehost:0</tt>.

The solution is to use the CMUCL-specific function <tt>EXT:OPEN-CLX-DISPLAY</tt> instead of <tt>XLIB:OPEN-DISPLAY</tt>. This function will parse the <tt>DISPLAY</tt> environment variable to extract the display and screen numbers.

Note that the version of CLX distributed with CMUCL includes a number of extensions to the original code. It is able to extract X11 authorization cookies from the file mentioned by the <tt>XAUTHORITY</tt> environment variable (defaulting to <tt>~/.Xauthority</tt>), and it includes hooks into CMUCL's <tt>SERVE-EVENT</tt> facility.

NB: Many people seem to find that this does not work for them, as the question of how to use CLX locally without turning off access control is a frequent question on c.l.lisp and the CMUCL mailing list.

<hr>

<h3>SERVE-EVENT example</h3>

An example of CMUCL's SERVE-EVENT facility, that allows you to handle multiple concurrent network connections and file handles, without using multithreading. The program is a port forwarder, or redirector. It redirects TCP connections to another port on another machine. Get it from <a href = "http://purl.org/net/emarsden/home/downloads/">purl.org/net/emarsden/home/downloads/</a>.

<hr>

<h3>Adding commandline switches</h3>

<p> Certain implementations such as _(CLISP) have a <tt>-c</tt> commandline switch that allows you to invoke the file compiler from the shell. CMUCL's commandline switches are user-extensible, so you can emulate this behaviour with code such as the following, in your <tt>site-init.lisp</tt> or <tt>~/.cmucl-init</tt> initialization files.

<pre>
(macrolet ((with-batch-processing (&body body)
             `(handler-case (prog1 t ,@body)
                (serious-condition (condition)
                  (format *error-output* "Error in batch processing:~%~A~%"
		          condition)
                  (finish-output *error-output*)
                  (throw 'lisp::%end-of-the-world 1))
                (:no-error (value)
                  (declare (ignore value))
                  (throw 'lisp::%end-of-the-world 0)))))

(ext:defswitch "compile"
    #'(lambda (switch)
        (with-batch-processing
          (mapc #'compile-file (ext:cmd-switch-words switch)))))

(ext:defswitch "compile-and-load"
    #'(lambda (switch) 
        (with-batch-processing
          (mapc #'(lambda (file) (compile-file file :load t))
                (ext:cmd-switch-words switch)))))

) ; macrolet
</pre>

<p> Now you can use the following to compile (and load) from the command
line:

<pre>
  lisp -compile-and-load demo.lisp demo2.lisp
</pre>

<p> If errors are encountered during processing, CMUCL is aborted, with a
return value of 1, otherwise it returns 0 (i.e. success). This can be combined with the <tt>-quiet</tt> flag (put it at the start of the
commandline) if wanted.

<p> An alternative to this form of interaction with the file compiler is to load the files and compile them from a stream, so you don't have any FASL files hanging around on disk (thus avoiding problems with binary compatibility between different CMUCL releases), yet still benefit from compiled performance. You can do this with code such as:

<pre>
(defun process-switch-demon (switch)
  (let ((files (copy-list (ext:cmd-switch-words switch))))
    (push #'(lambda ()
              (dolist (file files)
                (format *terminal-io*
                        "~&;;; Processing compiled code from ~A.~%" file)
                (with-open-file (s file)
                  (ext:compile-from-stream s))))
          *run-actions*)))

(ext:defswitch "process" #'process-switch-demon)
</pre>

<p> <i>Adapted from article <tt>87g06vubxi.fsf@orion.bln.pmsf.de</tt> posted to comp.lang.lisp by Pierre Mai, on 2001-11-30.</i>

<hr>

<h3>"Advise" facilities</h3>

In CMUCL 18e and later, use _(fwrappers); the encapsulation mechanism described below is deprecated.

from the release notes for CMUCL 17f:

<pre>
 -- The encapsulation mechanism (similar to advise facilities) has been
    revamped to work on SETF function names as well as symbols.

EXT:ENCAPSULATED-DEFINITION
       Returns whatever definition is stored for name, regardless of whether
       it is encapsulated.  Unlike FDEFINITION, this does not strip off the
       encapsulation.  This is SETF'able.
       
    EXT:ENCAPSULATE
       Replaces the definition of name with a function that binds name's
       arguments a variable named argument-list, binds name's definition to a
       variable named basic-definition, and EVAL's body in that context.  Type
       is whatever you would like to associate with this encapsulation for
       identification in case you need multiple encapsuations of the same
       name.
       
    EXT:UNENCAPSULATE
       Removes name's most recent encapsulation of the specified type.
       
    EXT:ENCAPSULATED-P
       Returns t if name has an encapsulation of the given type, otherwise
       nil.
       
    EXT:*SETF-FDEFINITION-HOOK*
       A list of functions invoked by (SETF FDEFINITION) before storing the
       new value.  Each hook function must take the function name and the
       new-value.
</pre>

<p>
<u>also see</u>: section 3.10.1 of the CMUCL Users' Manual; <code>(describe
'ext:encapsulate)</code>
</p>

<hr>

<h3>Command line editing and auto completion with CMUCL</h3>

For the rare cases when you don't use <a
href="http://sourceforge.net/projects/ilisp/">ILISP</a> but invoke
CMUCL directly from the command line:

<ol>
  <li>Get <a
href="http://utopia.knoware.nl/~hlub/uck/rlwrap/">rlwrap</a> and build
it.
  <li>Put something like
<pre>alias cmucl="rlwrap cmucl"</pre>
     into your <code>~/.bashrc</code> (or <code>~/.profile</code> or whatever).
  <li>Put <a href="http://weitz.de/files/cmucl_completions">this
file</a> into your home directory, call it <code>~/.cmucl_completions</code>.
  <li>Optionally adjust your <code>~/.inputrc</code> file (actually the
file where <code>$INPUTRC</code> points to). I added the line
<pre>TAB: complete</pre>
because rlwrap binds this key to <code>menu-complete</code>.
</ol>

Note that recent <a
href="http://cnswww.cns.cwru.edu/~chet/readline/rltop.html">readline</a>
versions include an example program rlfe that does almost the same
thing as rlwrap. I think rlwrap is nicer, though.
<p>
Update: I've slightly enhanced this hint (including a way to create better completions files) and put it <a href="http://weitz.de/completions.html">here</a>.

For those of you on Debian, <b>cle</b> that does pretty much the same thing
(but no tab-completion) is packaged on testing.

<hr>

<h3>Allegro-like REPL commands</h3>

To get top-level commands like <code>:load "foo.lisp"</code> either use Paul Foley's version at <a href="http://users.actrix.co.nz/mycroft/toplevel/">http://users.actrix.co.nz/mycroft/toplevel/</a> or Peder O. Klingenberg's
from <a href="http://heim.ifi.uio.no/~pok/download/commands.lisp">http://heim.ifi.uio.no/~pok/download/commands.lisp</a>.

Please supply your name and a summary of changes for the Recent Changes page. If you are making a minor alteration to a page you recently edited, you can avoid making another Recent Changes entry by leaving the Summary box blank
Summary of changes:
Captcha (enter the word "lisp" here):
Your name:
Check this box to fill in your name automatically next time (uses a cookie)

Please note: other readers will see your changes immediately, but external search engines will continue to see the old version for another 24 hours. Spamming this site to improve your PageRank is therefore a particularly fruitless activity.

CLiki pages can be edited by anyone at any time. Imagine a fearsomely comprehensive disclaimer of liability. Now fear, comprehensively