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:

• Starting LispWorks describes how to start LispWorks and supply command line arguments.
• The Listener describes the read-eval-print loop (REPL) listener.
• The Debugger describes the REPL debugger.
• The REPL Inspector describes the REPL inspector.
• The Trace Facility describes the tracer.
• The Advice Facility.
• Dspecs: Tools for Handling Definitions describes the naming system for Lisp definitions, and in particular how to locate these.
• Action Lists describes how you can run code at various hook points.
• The Compiler describes the compiler optimization qualities and some ways to optimize your code.
• Code Coverage shows you how to determine and visualize which parts of your program have actually run.
• Storage Management covers the behavior (and for wizard level users, configuration) of the garbage collector.
• The Profiler describes a tool for identifying bottlenecks impeding performance of your program.

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:

• LispWorks as a dynamic library describes how LispWorks operates as a DLL, .dylib or .so.
• Java interface describes the LispWorks Java interface.
• Android interface describes the LispWorks Android interface, which allows you to include a LispWorks runtime in an Android app.
• iOS interface describes the LispWorks iOS interface, which allows you to include a LispWorks runtime in an iOS app.
• The Metaobject Protocol describes how the LispWorks MOP implementation differs from AMOP.
• Multiprocessing, including locks.
• Common Defsystem and ASDF describes how to use defsystem to combine a series of source files into a manageable project.
• The Parser Generator.
• Dynamic Data Exchange describes how to implement DDE functionality in your Microsoft Windows applications.
• Common SQL explains how to use LispWorks to communicate with databases using SQL.
• User Defined Streams provides an illustrative example showing how to define and implement your own streams.
• TCP and UDP socket communication and SSL describes the use of socket streams, including the Secure Sockets Layer (SSL).
• Internationalization: characters, strings and encodings provides an overview of using international characters.
• LispWorks' Operating Environment explains how to find information about the Operating System and how LispWorks was started.
• Miscellaneous Utilities describes miscellaneous functionality which does not belong in other chapters.
• 64-bit LispWorks outlines differences between 64-bit LispWorks and 32-bit LispWorks.
• Self-contained examples enumerates the example files which are relevant to the content of this manual and are available in the LispWorks library.

Please note that documentation for Graphics Ports is in the CAPI User Guide and Reference Manual .

Reference section

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 COMPILER package.
• 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 EXTERNAL-FORMAT package.
• The HCL Package, describes symbols available in the HCL package.
• The LINK-LOAD Package, describes symbols available in the LINK-LOAD package. It applies to LispWorks for UNIX only (not LispWorks for Linux, FreeBSD, Mac OS X or x86/x64 Solaris).
• The LISPWORKS Package, describes symbols available in the LISPWORKS package.
• 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 SYSTEM package.
• 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.

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.
• The 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
• The 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.
• The LispWorks Editor User Guide describes the keyboard commands and programming interface to the LispWorks IDE editor tool.
• The 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.
• The LispWorks Foreign Language Interface User Guide and Reference Manual explains how you can use C source code in applications developed using LispWorks.
• The 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.
• The LispWorks COM/Automation User Guide and Reference Manual describes a toolkit for using Microsoft COM and Automation in LispWorks for Windows.
• The LispWorks Objective-C and Cocoa Interface User Guide and Reference Manual describes APIs for interfacing to Objective-C and Cocoa in LispWorks for Macintosh.
• The 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.
• The 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 www.adobe.com .

The LispWorks manuals are also available in HTML format. Commands in the Help 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.

Other documentation

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 Help menu.

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:

(example-edit-file "ssl/ssl-client")

These examples are Lisp source files in your LispWorks installation under lib/7-0-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:

(sys:lispworks-file "foo/bar.lisp")