LispWorks® User Guide Version 5.1 Copyright and Trademarks LispWorks User Guide Version 5.1 March 2008 Copyright © 2008 by LispWorks Ltd. All Rights Reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of LispWorks Ltd. The information in this publication is provided for information only, is subject to change without notice, and should not be construed as a commitment by LispWorks Ltd. LispWorks Ltd assumes no responsibility or liability for any errors or inaccuracies that may appear in this publication. The software described in this book is furnished under license and may only be used or copied in accordance with the terms of that license. LispWorks and KnowledgeWorks are registered trademarks of LispWorks Ltd. Adobe and PostScript are registered trademarks of Adobe Systems Incorporated. Other brand or product names are the registered trade- marks or trademarks of their respective holders. The code for walker.lisp and compute-combination-points is excerpted with permission from PCL, Copyright © 1985, 1986, 1987, 1988 Xerox Corporation. The XP Pretty Printer bears the following copyright notice, which applies to the parts of LispWorks derived therefrom: Copyright © 1989 by the Massachusetts Institute of Technology, Cambridge, Massachusetts. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, pro- vided that this copyright and permission notice appear in all copies and supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representa- tion about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty. M.I.T. disclaims all war- ranties with regard to this software, including all implied warranties of merchantability and fitness. In no event shall M.I.T. be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of con- tract, negligence or other tortious action, arising out of or in connection with the use or performance of this software. LispWorks contains part of ICU software obtained from http://source.icu-project.org and which bears the following copyright and permis- sion notice: ICU License - ICU 1.8.1 and later COPYRIGHT AND PERMISSION NOTICE Copyright © 1995-2006 International Business Machines Corporation and others. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Soft- ware"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIM- ITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder. All trademarks and registered trademarks men- tioned herein are the property of their respective owners. US Government Restricted Rights The LispWorks Software is a commercial computer software program developed at private expense and is provided with restricted rights. The LispWorks Software may not be used, reproduced, or disclosed by the Government except as set forth in the accompanying End User License Agreement and as provided in DFARS 227.7202-1(a), 227.7202-3(a) (1995), FAR 12.212(a)(1995), FAR 52.227-19, and/or FAR 52.227-14 Alt III, as applicable. Rights reserved under the copyright laws of the United States. Address Telephone Fax LispWorks Ltd From North America: 877 759 8839 From North America: 305 468 5262 St. John’s Innovation Centre Cowley Road (toll-free) From elsewhere: +44 870 2206189 Cambridge CB4 0WS From elsewhere: +44 1223 421860 England www.lispworks.com Contents 1 Introduction 1 About this manual 1 The LispWorks manuals 3 Other documentation 4 Notation and conventions 5 2 Starting LispWorks 7 The usual way to start LispWorks 7 Passing arguments to LispWorks 7 Other command line options 9 Starting the Common LispWorks Graphical IDE 9 Using LispWorks with SLIME 9 Quitting LispWorks 10 3 The Listener 11 First use of the listener 11 Standard listener commands 12 The listener prompt 14 iii 4 The Debugger 15 Entering the REPL debugger 16 Simple use of the REPL debugger 17 The stack in the debugger 18 REPL debugger commands 18 Debugger control variables 27 5 The REPL Inspector 31 Describe 31 Inspect 32 Inspection modes 34 6 The Trace Facility 41 Simple tracing 41 Tracing options 43 Example 50 Tracing methods 51 Trace variables 51 7 The Advice Facility 55 Combining the advice 57 Removing advice 58 Advice for macros and methods 59 Examples 61 Advice functions and macros 64 8 Dspecs: Tools for Handling Definitions 65 Dspecs 65 Forms of dspecs 66 Dspec namespaces 67 Types of relations between definitions 70 Details of system dspec classes and aliases 73 Subfunction dspecs 75 Tracking definitions 76 Finding locations 77 Users of location information 78 iv 9 Action Lists 81 Defining and undefining action lists 82 Exception handling variables 84 Other variables 85 Diagnostic utilities 85 Examples 86 Standard Action Lists 87 10 The Compiler 89 Compiling a function 90 Compiling a source file 91 How the compiler works 91 Compiler control 92 Declare, proclaim, and declaim 96 Optimizing your code 98 Compiler parameters affecting LispWorks 103 11 Storage Management 105 Introduction 105 Generations and segments 106 Memory Management in 32-bit LispWorks 106 Memory Management in 64-bit LispWorks 114 Common Memory Management Features 118 Assisting the Garbage Collector 120 12 The Profiler 123 What the profiler does 123 Setting up the profiler 124 Running the profiler 125 Profiler output 127 Interpretation of profiling results 129 Profiling pitfalls 129 Profiling and garbage collection 130 13 Customization of LispWorks 131 Introduction 131 Configuration and initialization files 132 v Saving a LispWorks image 133 Load and open your files on startup 135 Customizing the editor 135 Finding source code 137 Specifying the initial working directory 137 Using ! for :redo 137 Customizing LispWorks for use with your own code 138 Structure printing 138 Configuring the printer 139 14 LispWorks as a dynamic library 141 Introduction 141 Creating a dynamic library 142 Initialization of the dynamic library 143 Relocation 144 Multiprocessing in a dynamic library 145 Unloading a dynamic library 145 15 The Metaobject Protocol 147 Metaobject features incompatible with AMOP 147 Common problems when using the MOP 150 Implementation of virtual slots 151 16 Multiprocessing 159 Introduction to processes 159 The process programming interface 160 Locks 165 Timers 166 Native threads and foreign code 167 Example 168 17 Common Defsystem 171 Introduction 171 Defining a system 172 18 The Parser Generator 179 Introduction 179 vi Grammar rules 179 Functions defined by defparser 181 Error handling 182 Interface to lexical analyzer 182 Example 183 19 Dynamic Data Exchange 187 Introduction 187 Client interface 189 Server interface 195 20 Common SQL 201 Introduction 201 Initialization 204 Functional interface 212 Object oriented interface 220 Symbolic SQL syntax 224 Working with date fields 231 SQL I/O recording 233 Error handling in Common SQL 233 Using MySQL 235 Using Oracle 240 Oracle LOB interface 241 21 User Defined Streams 251 Introduction 251 An illustrative example of user defined streams 251 22 Socket Stream SSL interface 261 Creating a stream with SSL 261 SSL-CTX and SSL objects 262 OpenSSL interface 262 Socket Stream SSL keyword arguments 266 Attaching SSL to an existing socket-stream 269 Using SSL objects directly 269 Initialization 270 Obtaining and installing the OpenSSL library 271 vii Errors in SSL 272 23 Internationalization 273 Introduction 273 Character and String types 273 String accessors 276 String Construction 276 External Formats 279 External Formats and File Streams 280 External Formats and the Foreign Language Interface 283 24 LispWorks’ Operating Environment 285 The Operating System 285 Site Name 285 The Lisp Image 286 The Command Line 286 Address Space and Image Size 289 Startup relocation 289 Exit status 294 Creating a new executable with code preloaded 294 Universal binaries on Mac OS X 295 User Preferences 295 Accessing the Windows registry 296 The home directory 298 Special Folders 298 25 64-bit LispWorks 301 Introduction 301 Heap size 302 Architectural constants 303 Speed 303 Memory Management 303 Float types 303 External libraries 304 Index 305 viii 1 1 Introduction 1.1 About this manual This manual describes the features and tools available in LispWorks, and how to use them. The first group of chapters in this book describes some of the central program- ming tools and features in LispWorks: • Chapter 2, “Starting LispWorks” describes how to start LispWorks and supply command line arguments.