McCLIM Lisp Listener


Overview
--------

The McCLIM Listener provides an interactive toplevel with full access to the
graphical capabilities of CLIM, and a set of built-in commands intended to be
useful for lisp development and experimentation. Present features include:

 - Reading/evaluation of lisp expressions
 - Ability to run external programs, through the "Run" command or #! macro
 - Commands for inspecting CLOS classes (superclasses/subclasses, slots, etc.)
 - Navigation of the filesystem, including a directory stack
 - Launching of external programs sensitive to file type (determined by mailcap
   and mime.types files)


Installation
------------

The Listener uses ASDF for system definition. You must have ASDF loaded to build
the listener (or else compile the files manually), but need not have compiled
McCLIM using it. See http://www.cliki.net/asdf for information on ASDF.

Provided you have McCLIM and ASDF loaded into your lisp, compiling the listener
is straightforward. Assuming you are in the McCLIM directory:

 * (load "Apps/Listener/clim-listener.asd")
 * (asdf:operate 'asdf:load-op :clim-listener)

To run the listener:
 * (clim-listener:run-listener)

If you have a multithreaded lisp, you can start the listener in a separate
thread, thereby leaving your main REPL available:
 * (clim-listener:run-listener :new-process t)


Compatibility
-------------

The Listener is developed primarily on CMUCL 18e, and tested periodically on SBCL
and possibly OpenMCL. On SBCL, the SB-POSIX package is used for filesystem 
access, so you will need a fairly recent version of SBCL (minimum 0.8.2.44).

Due to variation in how implementations treat pathnames as well as nonstandard 
things like access to the MOP and the need to run programs, examine environment
variables, etc, a little work is required to get everything running smoothly on
a new CL. Most of this should be done for LispWorks. Allegro CL is untested and
will need some hacking.

Usage
-----

After starting the listener, a fairly normal lisp prompt will be displayed, with
the package name preceding the prompt. You may type lisp forms or commands to
this prompt. The listener will treat alphabetical characters as beginning a 
command name, and most other characters as the beginning of a lisp form. If for
some reason you had a special variable with a name such as FOO which would be
interpreted as a command, you can use a comma before the variable name as an 
escape character.

At the bottom of the window is a wholine which shows various things such as the
username/hostname, package, current directory (*default-pathname-defaults*), 
the depth of the directory stack (if not empty), and the current memory usage.
Some of these items will be sensitive to pointer gestures.


Commands
--------

The command "Help (with) Commands" will produce a list of available commands.

 General Commands
  - Help
  - Clear Output History - clears the screen
  - Exit
 
 Basic Lisp Commands
  - Apropos
  - Describe
  - Room
  - Trace
  - Untrace
  - Eval
  - Load File
  - Compile File
  - Compile and Load

 CLOS Commands
  - Show Class Superclasses
  - Show Class Subclasses
  - Show Class Slots
  - Show Class Generic Functions
  - Show Applicable Methods

 Filesystem Commands
  - Show Directory
  - Up Directory
  - Edit File (probably broken)
  - Show File (almost certainly broken)

 Directory Stack Commands
  - Display Directory Stack
  - Push Directory
  - Pop Directory
  - Swap Directory
  - Drop Directory

 Other Commands
  - Run (run an external program)
  - Background Run (as above, but don't wait for program to complete)


The #! Macro Character
----------------------

Although there are commands for running external programs, the #! macro
character tries to provide a nicer interface. It allows you to run external
programs as a lisp function call, and attempts to transform the arguments
in some meaningful way. Several transformations are performed:

 - Keywords are converted to options. Single character keywords are
   turned into an option with a single dash (e.g., :v becomes "-v").
   Longer keywords become an option preceded by two dashes (e.g.,
   :verbose becomes "--verbose")

 - Sequences are flattened into separate arguments

 - Wild pathnames are expanded (currently subject to brokenness in
   the DIRECTORY function of various CL environments)

My apologies to anyone doing something more useful with this macro character
which I have stepped on.


Calling Commands from Lisp
--------------------------

Calling CLIM commands from lisp is straightforward. By convention, the "pretty"
names used at the interactor map to a function name which implements the command
body by upcasing the name, replacing spaces with hyphens, and prepending "COM-" 
(e.g., Show Directory becomes COM-SHOW-DIRECTORY).


Notes
-----

There is currently no debugger integration with the listener, which is not
particularly convenient. Gilbert Baumann has modified the CMUCL debugger so
that it is capable of displaying on a CLIM stream. These modifications are
contained in the file cmucl-hacks.lisp. If you want to try this, load the
file and (setf *debug-io* *standard-output*) within the CLIM listener.
