About this manual
This manual contains a user guide section (previously published separately as the
LispWorks User Guide
) and a reference section (previously the
LispWorks Reference Manual
User Guide section
The user guide section of this manual describes the main language-level features and tools available in LispWorks, and how to use them.
These chapters describe the central programming tools and features in LispWorks:
The next chapter, Customization of LispWorks, explains how to perform some commonly required customizations, such as controlling start-up appearance of LispWorks.
The remaining user guide chapters describe features of specialist interest:
Please note that documentation for Graphics Ports is in the
CAPI User Guide and Reference Manual
Most of the reference section is organized by package: each chapter contains reference material for the exported symbols in a given package. The chapters are organized alphabetically by package name.
Generally one chapter covers each package, but the
WIN32 package symbols are split into four chapters, and the last chapter contains reference material for C functions. Within each chapter, the symbols are organized alphabetically (ignoring non-alphanumeric characters that are common in Lisp symbols, such as *). The chapters are:
The CLOS Package, describes the LispWorks extensions to CLOS, the Common Lisp Object System.
The COMM Package, describes the functions providing the TCP/IP interface.
The COMMON-LISP Package, describes the LispWorks extensions to symbols in the
COMMON-LISP package. You should refer to the Common Lisp HyperSpec, supplied in HTML format with LispWorks, for full documentation about standard Common Lisp symbols.
The COMPILER Package, describes symbols available in the
The DBG Package, describes symbols available in the
DBG package, used to configure the debugging information produced by LispWorks.
The DSPEC Package, describes the symbols available in the
DSPEC package, which are used for naming and locating definitions.
The EXTERNAL-FORMAT Package, describes symbols available in the
The HCL Package, describes symbols available in the
The LINK-LOAD Package, describes symbols available in the
LINK-LOAD package. It applies to LispWorks for SPARC Solaris.
The LISPWORKS Package, describes symbols available in the
The LW-JI Package, describes symbols available in the
LW-JI package, which allows you to call to and from Java. This chapter describes the Java classes and methods available in LispWorks.
Java classes and methods describes the Java classes and methods available in LispWorks.
Android Java classes and methods describes the additional Java classes and methods available in LispWorks for Android Runtime.
The MP Package, describes symbols available in the
MP package, giving you access to the multiprocessing capabilities of LispWorks.
The PARSERGEN Package, describes symbols available in the
PARSERGEN package, the LispWorks parser generator.
The SERIAL-PORT Package documents the Serial Port API. This is implemented only in LispWorks for Windows.
The SQL Package documents symbols used in accessing LispWorks ODBC and SQL functionality.
The STREAM Package documents the symbols available in the
STREAM package that provide users with the functionality to define their own streams for use by the standard I/O functions.
The SYSTEM Package, describes symbols available in the
Miscellaneous WIN32 symbols, describes miscellaneous symbols available in the
WIN32 package. It applies only to LispWorks for Windows.
The Windows registry API, describes the Windows registry API. It applies only to LispWorks for Windows.
The DDE client interface, describes the Dynamic Data Exchange (DDE) client API. It applies only to LispWorks for Windows.
The DDE server interface, describes the Dynamic Data Exchange (DDE) server API. It applies only to LispWorks for Windows.
Dynamic library C functions, describes C functions available in LispWorks dynamic libraries.
Many of these reference chapters should be used in conjunction with corresponding chapters in the user guide section. Reference material for some aspects of LispWorks can be found in other manuals.
Conventions used for reference entries
Each entry is headed by the symbol name and type, followed by a number of fields providing further details. These fields consist of a subset of the following: "Summary", "Package", "Signature", "Method signatures", "Arguments", "Values", "Initial value", "Superclasses", "Subclasses", "Initargs", "Accessors", "Readers", "Description", "Notes", "Compatibility notes", "Examples" and "See also".
Some symbols with closely-related functionality are coalesced into a single reference entry.
Throughout, variable arguments, slots and return values are italicised. They look like-this.
Throughout, exported symbols and example code are printed
like-this. The package qualifier is usually omitted, unless the symbol is not documented in this manual.
Entries with a long "Description" section usually have as their first field a short "Summary" providing a quick overview of the symbol's purpose.
The "Package" section shows the package from which the symbol is exported.
The "Signature" section shows the arguments and return values of functions and macros, and the parameters of types.
In a Generic Function entry there may be a "Method signatures" section showing system-defined method signatures.
The "Arguments" and "Values" sections show types of the arguments and return values.
In a Variable entry, the "Initial value" section shows the initial value.
In a Class entry the "Subclasses" section of lists the external subclasses, though not subclasses of those, and the "Superclasses" section lists the external superclasses, though not superclasses of those. The "Initargs" section describes the initialization arguments of the class, though note that initargs of superclasses are also valid. There may be an "Accessors" section listing accessor functions which are both readers and writers, and/or a "Readers" section listing accessor functions which are only readers. Accessor functions access the slot with matching name.
The "Description" section contains the detail of what the symbol does, how each argument is interpreted (and its default value if applicable), and how each return value is derived. More incidental information may be shown in a "Notes" section.
A few entries have a "Compatibility notes" section describing changes in the symbol's functionality relative to other LispWorks versions.
Examples are given under the "Examples" heading. Short examples are shown directly. Longer examples are supplied as source files in your LispWorks installation directory under
examples/. The convenience function example-edit-file allows you to open these files in the LispWorks editor. The examples files are in a read-only directory and therefore you should compile them inside the IDE (by the Editor command
Compile Buffer or the toolbar button or by choosing
Buffer > Compile
from the context menu), so it does not try to write a fasl file. If you want to manipulate an example file or compile it on the disk rather than in the IDE, then you need first to copy the file elsewhere (most easily by using the Editor command
Write File or by choosing
File > Save As
from the context menu).
Finally, the "See also" section provides links to other related symbols and user guide sections.
The LispWorks manuals
The LispWorks manual set comprises the following books:
The Common Lisp HyperSpec contains the specification for Common Lisp itself.
LispWorks User Guide and Reference Manual
--this book--describes the main language-level features and tools available in LispWorks, along with an extensive reference of the functions, macros, variables and classes organized by package. Where LispWorks extends the functionality of a Common Lisp symbol, this is mentioned in The COMMON-LISP Package
LispWorks IDE User Guide
describes the LispWorks IDE, the user interface for LispWorks. This is a set of windowing tools that let you develop and test Common Lisp code more easily and quickly.
LispWorks Editor User Guide
describes the keyboard commands and programming interface to the LispWorks IDE editor tool.
CAPI User Guide and Reference Manual
describes the CAPI. This is a library of classes, functions, and macros for developing graphical user interfaces for your applications. It comprises a tutorial guide to the CAPI and an in-depth reference text.
LispWorks Foreign Language Interface User Guide and Reference Manual
explains how you can use C source code in applications developed using LispWorks.
LispWorks Delivery User Guide
describes how you can deliver working, standalone versions of your LispWorks applications for distribution to your customers.
Developing Component Software with CORBA
describes how LispWorks can interoperate with other CORBA-compliant systems.
LispWorks COM/Automation User Guide and Reference Manual
describes a toolkit for using Microsoft COM and Automation in LispWorks for Windows.
LispWorks Objective-C and Cocoa Interface User Guide and Reference Manual
describes APIs for interfacing to Objective-C and Cocoa in LispWorks for Macintosh.
KnowledgeWorks and Prolog User Guide
describes the LispWorks toolkit for building knowledge-based systems. Common Prolog is a logic programming system written in Common Lisp.
LispWorks Release Notes and Installation Guide
explains how to install LispWorks and start it running. It also contains Release Notes describing the new features in this release and any issues that could not be included in the other manuals.
The LispWorks manuals are all available in Portable Documentation Format (PDF). You can use Adobe Reader to browse the PDF documentation online or to print it. Adobe Reader is available for free download from Adobe's web site at
The LispWorks manuals are also available in HTML format. Commands in the
menu of any of the LispWorks IDE tools give you direct access to the HTML documentation, using your web browser. Details of how to use these commands can be found in the
LispWorks IDE User Guide
Please let us know if you find any mistakes in the LispWorks documentation, or if you have any suggestions for improvements.
The LispWorks manuals do not attempt to describe Lisp itself. For definitive information on Common Lisp, including CLOS, consult the American National Standard X3.226 for Common Lisp. An HTML version of this document is supplied with LispWorks and can be accessed from the
For information on CLOS, Sonya E. Keene's book
Object-Oriented Programming in Common Lisp: A Programmers' Guide
is very helpful. This book is published by Addison-Wesley.
For an account of Metaobject protocols as well as a detailed study of an implementation of CLOS see Kiczales, des Rivières and Bobrow,
The Art of the Meta-Object Protocol
, published by MIT Press, often referred to as AMOP. The LispWorks MOP mostly conforms to chapters 5 & 6 of AMOP; the differences are mentioned here in The Metaobject Protocol.
Notation and conventions
The LispWorks manuals follow the notation used in
Common Lisp: the Language (2nd Edition)
This manual often refers to example files in the LispWorks library, like this:
These examples are Lisp source files in your LispWorks installation under
lib/7-1-0-0/examples/. You can simply evaluate the given form to view the example source file.
Other references such as "... the LispWorks file
foo/bar.lisp" mean a file
bar.lisp in a subdirectory
foo of the LispWorks library directory. Evaluate this form in your LispWorks image to obtain the full path of such a file:
LispWorks User Guide and Reference Manual - 20 Sep 2017