Common LispWorks User Guide Version 5.1 Copyright and Trademarks Common LispWorks User Guide (Unix version) Version 5.1 February 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 Preface xi 1 Introduction 1 Major tools 2 2 A Short Tutorial 5 Starting the environment 6 Creating a Listener 7 Using the Debugger 9 Viewing output 11 Inspecting objects using the Inspector 12 Examining classes in the Class Browser 14 Summary 17 3 Common Features 19 Displaying tool windows 20 Setting global preferences 25 Performing editing functions 28 The history list 30 Operating on files 31 Displaying packages 32 Performing operations on selected objects 35 Using different views 37 Tracing symbols from tools 40 iii Linking tools together 41 Filtering information 42 Regexp matching 44 Completion 46 Examining a window 49 4 Getting Help 51 Online manuals in HTML format 51 Online help for editor commands 55 Browsing manuals online using Adobe Reader 55 Reporting bugs 56 5 Manipulating Graphs 57 An overview of graphs 57 Searching graphs 58 Expanding and collapsing graphs 59 Moving nodes in graphs 60 Displaying plans of graphs 61 Preferences for graphs 63 Using graphs in your programs 68 6 The Podium 69 The podium window 69 Specifying the initial tools 70 7 The Class Browser 71 Simple use of the Class Browser 72 Examining slot information 79 Examining superclasses and subclasses 81 Examining classes graphically 84 Examining generic functions and methods 88 Examining initargs 91 Examining class precedences 93 8 The Object Clipboard 97 Placing objects on the Object Clipboard 98 Browsing clipped objects 101 iv Removing objects 102 Filtering 102 Using the Object Clipboard with a Listener 103 9 The Compilation Conditions Browser 107 Introduction 107 Examining error conditions 108 Configuring the display 109 Access to other tools 113 10 The Debugger Tool 115 Description of the Debugger 117 What the Debugger tool does 122 Simple use of the Debugger tool 123 The stack in the Debugger 124 An example debugging session 124 Performing operations on the error condition 127 Performing operations on stack frames 127 Performing operations on frame variables 128 Configuring the debugger tool 129 11 The Tracer 133 Introduction 133 Tracing and Untracing functions 133 Examining the output of tracing 134 Example 135 12 The Editor 141 Displaying and editing files 143 Displaying output messages in the Editor 146 Displaying and swapping between buffers 146 Displaying Common Lisp definitions 150 Changed definitions 151 Finding definitions 154 Setting Editor preferences 155 Basic Editor commands 164 Other essential commands 169 v Cutting, copying and pasting using the clipboard 170 Cutting, copying and pasting using the kill ring 171 Searching and replacing text 174 Using Lisp-specific commands 178 Help with editing 185 13 The Function Call Browser 187 Introduction 187 Examining functions using the graph views 188 Examining functions using the text view 191 Configuring the function call browser 193 Configuring graph displays 194 Performing operations on functions 195 14 The Generic Function Browser 197 Examining information about methods 198 Examining information about combined methods 201 Configuring the Generic Function Browser 206 15 The Search Files tool 207 Introduction 207 Performing searches 209 Viewing the results 215 Configuring the Search Files tool 216 16 The Inspector 223 Inspecting the current object 223 Description of the Inspector tool 224 Filtering the display 225 Examining objects 227 Operating upon objects and items 229 Configuring the Inspector 234 Customizing the Inspector 237 Creating new inspection formats 237 17 The Symbol Browser 243 Introduction 243 vi Description of the Symbol Browser 244 Configuring the Symbol Browser 248 18 The Interface Builder 249 Description of the Interface Builder 250 Creating or loading interfaces 251 Creating an interface layout 254 Creating a menu system 258 Editing and saving code 262 Performing operations on objects 265 Performing operations on the current interface 269 Performing operations on elements 271 19 Example: Using The Interface Builder 273 Creating the basic layout 275 Specifying attribute values 277 Creating the menu system 280 Specifying callbacks in the interface definition 282 Saving the interface 284 Defining the callbacks 285 Creating a system 288 Testing the example interface 288 20 The Listener 291 The basic features of a Listener 292 Evaluating simple forms 293 Re-evaluating forms 294 Interrupting evaluation 295 The History menu 295 The Expression menu 295 The Values menu 297 The Debug menu 297 Execute mode 298 Setting Listener preferences 302 Running Editor forms in the Listener