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 clim-listener system is defined both by McCLIM's central system.lisp and
the ASDF-ized version in mcclim.asd. It can be loaded in the same manner as
the rest of McCLIM.

For ASDF users, the following should work:

 * (asdf:operate 'asdf:load-op :clim-listener)

Once loaded, you can run the listener using:
 * (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 using CMUCL 18e and recent versions of SBCL. It is
known to work well on these platforms. It has also been reported to work on
OpenMCL, Lispworks, and clisp. It has not been tested on ACL and will
require a small amount of work due to the number of implementation-specific
features used (MOP, pathnames, run-program, environment variables, etc).



Usage
-----

After starting the listener, a typical lisp prompt will be displayed, with the
package name preceding the prompt. You may type lisp forms or commands to this
prompt. The , (comma) character starts a command, every other input will be
treated by the listener as a form to be evaluated.

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
if I have clobbered your readtable.



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.
