Glossary
Allegro CL 3.0 for Windows printed documentation in PDF format
All the printed documentation for Allegro CL 3.0 for Windows is available in this pdf file and is readable with an Adobe Acrobat Reader. Please Note:
• There are links in each Table of Contents page. Clicking on a chapter or section (but not heading) title causes a jump to the associated page.
• There are no links in any index in this edition.
• Many pictures do not appear. An apparent incompatibility in the picture format results in their not appearing in the PDF file (you see blank space instead)
• If you choose ‘Bookmarks and Page’ from the View menu, you will see bookmarks for each chapter of each manual. Clicking on a bookmark will cause the associated page to be displayed (usually, the first page of the chapter).
• The pagination (<chapter>-<number>) used in the printed documents does not correspond to the pagination used in the pdf file (where all pages are numbered in order from the beginning). To find a page listed PT-2-2, go to the beginning of Chapter 2 in the Programming Tools manual (using the Acrobat Bookmarks). Go to page 2 of that chapter.
Copyright and Conditions of Use
Copyright 1996, Franz Inc. All Rights Reserved.
The PDF hypertext markup that implements the hypertext features of the Allegro CL 3.0.1 for Windows User Guide pages collectively the User Guide, is the property of Franz Inc.
Distribution of the User Guide as a hypertext PDF document on the Internet does not constitute consent to any use of the underlying hypertext PDF markup for redistribution of any kind, commercial or otherwise, either via the Internet or using some other form of dis- tribution, in hypertext or otherwise.
Permission to copy, distribute, display, and transmit the User Guide is granted provided that copies are not made or distributed or displayed or transmitted for direct commercial
advantage, that notice is given that copying, distribution, display, and/or transmission is by permission of Franz Inc., and that any copy made is COMPLETE and UNMODIFIED, including this copyright notice and its date.
Permissions related to performance and to creation of derivative works are expressly NOT granted.
Permission to make partial copies is expressly NOT granted, EXCEPT that limited per- mission is granted to transmit and display a partial copy of the User Guide for the ordinary purpose of direct viewing by a human being in the usual manner that PDF browsers permit the viewing of such a complete document, provided that no recopying, redistribution, redis- play, or retransmission is made of any such partial copy.
Permission to make modified copies is expressly NOT granted.
Permission to add or replace any links or any graphical images to any of these pages is expressly NOT granted.
Permission to use any of the included graphical (GIF) images in any document other than the User Guide is expressly NOT granted.
Restricted Rights Legend
Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in (i) FAR 52.227-14 Alt III, (ii) FAR 52.227-19, (iii) DFARS 252.7013(c)(1)(ii), or (iv) the accompanying license Agreement, as applicable. For purposes of the FAR, the Software shall be deemed to be ``unpublished'' and licensed with disclosure prohibitions, rights reserved under the copyright laws of the United States. Franz Inc., 1995 University Ave., Berkeley, CA 94704.'
Warranty disclaimer
THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. IN NO EVENT WILL FRANZ INC. BE LIABLE FOR DIRECT, INDIRECT, SPE- CIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY INACCURACY OR ERROR IN THIS DOCUMENT, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Glossary
PREFACE
There are two volumes of bound documentation for Allegro CL for Windows. This is vol- ume 1. Each volume contains several manuals. There is also a Read This First document, which not bound in with the rest of the documentation.
Here is a brief description of the documentation:
1. Read This First. This document is supplied loose. It contains information that was not put in the bound documentation.
Volume 1
2. Getting Started. This document describes how to install Allegro CL for Windows on your system and it gives information about running the product.
3. Common Lisp Introduction. This document is an introduction to the Common Lisp language and the Allegro CL for Windows implementation of it.
4. Interface Builder. The Interface Builder allows you to build an interface to your application interactively. It is described in this manual.
5. Foreign Function Interface. Allegro CL for Windows supports calling applications written in languages other than Lisp. This document describes the interface.
Volume 2
6. Programming Tools. This document describes the user interface to Allegro CL for Windows. In particular, it describes the Toploop window, the editor, the debugging facilities, etc.
7. General Index. An index to all documents in Volumes 1 and 2.
Professional version only
The Professional version of Allegro CL provides the facility to create standalone applica- tions. User who purchase the Professional version also receive the following document:
Professional supplement. This document describes features available in the Pro- fessional version (but not in the standard version), including how to create stan- dalone applications.
Each individual manual has a table of contents at the beginning and an index at the end.
The General Index manual, in volume 3, is an index for all manuals in Volumes 1 and 2.
Debugge
Allegro CL for Windows
Getting Started
version 3.0
October, 1995
Copyright and other notices:
This is revision 0 of this manual. This manual has Franz Inc. document number D-U-00- PC0-03-51017-3-0.
Copyright1992-1995 by Franz Inc. 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, by photocopying or recording, or otherwise, without the prior and explicit written permission of Franz incorporated.
Restricted rights legend: Use, duplication, and disclosure by the United States Government are subject to Restricted Rights for Commercial Software developed at private expense as specified in DOD FAR 52.227-7013 (c) (1) (ii).
Allegro CL is a registered trademarks of Franz Inc.
Allegro CL for Windows is a trademark of Franz Inc.
Windows, Windows 95, MS Windows, MS-DOS, and DOS are trademarks of Microsoft.
Franz Inc.
1995 University Avenue Berkeley, CA 94704 U.S.A.
Debugge
Contents
1 Introduction 1 2 Installation 2
Installing Win32s (Windows 3.1 or Windows for Workgroups users only) 2 Allegro CL 3.0 for Windows installation 3
Reinstallation 4 Uninstall Program 5
Filename length restriction (Windows 3.1 only) 5 Professional and standard versions 5
3 Documentation 6
Volume 1 6 Volume 2 6
Professional supplement (Professional version only) 7 The Online Manual 7
Other documents for starting out 8 Pictures in the documentation 8 Change bars 9
4 When Allegro CL starts up 10 5 Features of Microsoft Windows 12
A window 12 Menus 13
Keyboard equivalents to menu items 13 Interrupting 14
What to do if the system hangs 14 The two Enter keys 15
Dialog boxes 15
6 Getting information and patches 16
The World Wide Web page 16 What is a patch 16
Getting patches 16
Where to put patch files 17 When patches are loaded 17
Creating an image with patches loaded 17
How do you know what patches are loaded in an image 18 What if a patch needs to be updated? 18
7 Example files 20
Where examples are located 20
8 Anomalies and things to note 23
Professional and standard versions are incompatible! 25 Version 2.0 fsl and img files cannot be used by version 3.0 25 Do not use 2.0 patches including FAQ patches 25
9 Support 26
Index 27
Debugge
1 Introduction
Welcome to Allegro CL for Windows. This is the introductory document which will get you started with the system and direct you to the other documents and help facilities which describe how to use it. This manual is divided into the following sections:
1. Introduction. The section you are now reading.
2. Installation. This section describes how to install Allegro CL for Windows.
3. Documentation. This sections describes the documentation for Allegro CL for Windows. This section contains a description of the notation used in Allegro CL for Windows documentation.
4. When Allegro CL starts up. This section briefly describes the features on the screen and refers you to more complete documentation.
5. Features of the Microsoft Windows. Allegro CL for Windows is designed to run under various versions of the Microsoft Windows. In this section we discuss which versions and we mention certain features of MS Windows that help you when running Allegro CL for Windows.
6. Sources of information and patches. Franz Inc. maintains a World Wide Web page from which a product FAQ, patches, and other useful things can obtained.
Its URL and other sources of information are described in this section.
7. Example files. A number of example files are included with the Allegro CL for Windows distribution. These are described in this section.
8. Anomalies and things to note. This section describes behavior of Allegro CL for Windows which may be unexpected or unusual.
9. Support. This section briefly introduces product support. See the Read This First document for more information on product support.
You should have received a Read This First document with the Allegro CL for Windows distribution. Please be sure to scan this document before installing or using Allegro CL for Windows. It may contain important information which could not be included in the bound documents.
2 Installation
Allegro CL 3.0 for Windows will run under Windows 95, Windows NT 3.51, or Win- dows 3.1 or Windows for Workgroups with the Win32s upgrade supplied with the dis- tribution.
The software is distributed on a CD. The CD contains both Allegro CL for Windows and Win32s.
Installing Win32s (Windows 3.1 or Windows for Workgroups users only)
If you are running Windows 95 or Windows NT, you do not need to install Win32s. If you are running Windows 3.1, you must install Win32s before installing Allegro CL for Win- dows. You may have a version of Win32s already installed on your machine. If it is earlier than the version supplied with the distribution, we strongly recommend upgrading because it includes many additional features (over earlier versions) which are used by Allegro CL for Windows. To install Win32s, do the following:
1. Switch to the Program Manager, making it the active program.
2. Put the CD in your CD Drive. We assume the CD drive is device D in this document. Replace D with the correct letter if necessary.
3. Choose Run from the Program Manager File Menu.
4. In the dialog that appears, enter d:\win32s\setup.exe 5. Answer dialog questions when necessary.
The Win32s installation includes the optional installation of FreeCell, a solitaire game that requires Win32s in order to run, and can thus be used as a check to ensure Win32s is installed properly.
If the system detects that the same or a later version of Win32s is installed, it will inform you and you should abort the installation of Win32s.
The Read This First document gives the exact version number of Win32s distributed with Allegro CL.
Debugge
Allegro CL 3.0 for Windows installation
There are two versions of Allegro CL for Windows: the Professional version and the stan- dard version. The box should say which version you have received. Both are installed the same way (the differences between the two versions is described at the end of this section).
To install, do the following:
1. Choose a directory on a filesystem that has 15 Megabytes free. The directory should be empty. We assume you choosec:\allegro. Note that the directory name must follow the 8.3 name limitation (no more than 8 letters for the name, no more than 3 for the extension) even if you are running Windows 95 or Windows NT. (Users of those products will not again run into this limitation.) 2. Insert the distribution CD into the CD drive. We assume the CD drive is device
D. Replace D with the correct letter if necessary.
3. Run the programd:\allegro\setup.exe. If you are running Windows 95, choose Run from the menu displayed by clicking on Start and enter d:\allegro\setup.exe in the dialog that appears. If you are using Windows 3.1, choose Run from the Program Manager File menu and enter d:\allegro\setup.exe in the dialog that appears.
4. Note the serial number on the CD jewel case (box). You are asked for this serial number, your name, and your organization soon after the installation process begins. Enter the serial number exactly as it appears on the jewel case.
5. Enter the directory for installation or accept the defaultc:\allegro. When you are asked where to install Allegro CL, you are offered the default location c:\allegro. Either click on OK to accept this location or enter a different location. The location must follow the 8.3 filename limitation even if that limitation does not otherwise apply to your machine. Whatever directory you choose must have 15 Megabytes of free space.
Note: this is the same default as that specified for Allegro CL for Windows 2.0. If you have Allegro CL for Windows 2.0 already installed and wish both ver- sions to be available, choose a directory other than the directory where Allegro CL 2.0 for Windows is installed.
Once the directory is specified, the installation runs to completion, after which a new Program folder (on Windows 95) or a new Program Group (for Windows 3.1) has been cre- ated. The folder or group is called Allegro CL 3.0 for Windows.
Three program items are installed by the Professional version (Allegro CL 3.0, Allegro CL Runtime, and Uninstall), two by the standard version (Allegro CL and Uninstall). We show the folders for the Professional and standard versions next. If you are running Win- dows 3.1, you will see a Program Group (icons in a box titled Allegro CL 3.0). The icons are similar to those in the Windows 95 folders. (Many Windows 95 users may close the pro- gram folder window and start Allegro CL from the Programs choice of the Start menu. It is not necessary to have the folder displayed.)
Here is the program folder for the Professional version:
And here is the program folder for the standard version:
You can now run Allegro CL for Windows. In Windows 95, either click on the Start but- ton, selecting Programs, selecting Allegro CL 3.0 for Windows, and selecting Allegro CL or start the program from the program folder. In Windows 3.1, start Allegro CL by double- clicking on the Allegro CL icon in the Allegro CL 3.0 for Windows program group.
Reinstallation
You can re-install Allegro CL for Windows by following the same instructions. (It is not necessary to reinstall Win32s before reinstalling Allegro CL.) All files in the distribution will be overwritten by files on the disks with the same names. You may want to clear the directories where Allegro CL for Windows is stored (by using the Uninstall program, for example) but this is not necessary.
Debugge
Uninstall Program
Following the Windows paradigm, an Uninstall program is included with Allegro CL 3.0 for Windows. If invoked, it will ask at least twice if you are sure about uninstalling. If you confirm that you are, all installed programs will be removed. The directories created as part of the installation will also be removed if they are empty (that is if the only files in them are associated with the distribution).
Filename length restriction (Windows 3.1 only)
Windows 3.1 has a 64 character limit on the length of pathnames of files. The longest path in the Allegro CL for Windows distribution is 33 characters long; for example:
c:\allegro\ext\comtab\emacsctb.lsp
uses 33 characters including c:\allegro\. If you choose a directory name significantly longer that c:\allegro, so that the limit is exceeded for some files, those files will not be installed.
Professional and standard versions
There are two versions of Allegro CL for Windows: Professional and standard. The ver- sions are incompatible: compiled Lisp (fsl) and image (img) files generated by one cannot be used by the other.
The Professional version contains everything the standard versions does plus:
• Support for interprocess communication (fsl\socket.fsl, sockaux.dll).
• Certain Common Control widgets (fsl\grid*.fsl).
• The runtime generator.
• Access to certain source code (for Common graphics, the Interface Builder, and the Grapher). Getting source code requires an additional license (but no additional charge for Professional version customers). You will find a Source Code License among the distribution material. Fill it out and return it along with the Registration Card and the sources will be sent to you on a diskette.
The extra products available to Professional version customers can be purchased indi- vidually by standard version customers. Please contact Franz Inc. for more information.
3 Documentation
Nine documents comprise the documentation set for Allegro CL for Windows. Several of these documents are bound together. They are:
1. Read This First. This document is supplied separate from the bound manuals. It contains information that was (because of printing schedules) not put in the bound documentation.
Volume 1
2. Getting Started. This is the document you are reading now. It describes how to install Allegro CL for Windows on your system and it gives information about running the product.
3. Common Lisp Introduction. This document is an introduction to the Common Lisp language.
4. Interface Builder. The Interface Builder can be used to build an interface to your application.
5. Foreign Function Interface. Allegro CL for Windows supports calling applications written in languages other than Lisp. This document describes the interface.
Volume 2
6. Programming Tools. This document describes the programmer interface and the functions and variables associated with the programming interface (the editor, debugger, inspector, etc.)
7. General Index. This document contains an index to the five printed and bound manuals listed above.
Debugge
Professional supplement (Professional version only)
If you purchased the Professional version of Allegro CL for Windows, you will also have the following manual:
Professional supplement. The manual describes features available in the Profes- sional but not in the standard version of Allegro CL for Windows 3.0. Among these are the Runtime Generator, which allows you to create customized applica- tions that run independently of Allegro CL for Windows; the Winsock interface;
and Grid widgets.
The Online Manual
Descriptions of Common Lisp (including CLOS), Common Graphics, and many Allegro CL extensions can be found in the Online Manual. The Online Manual follows the usual WinHelp format. Bring up the manual by choosing Manual Contents from the Help menu.
The Online Manual is arranged into chapters, with the functionality associated with each chapter described within it. Choosing Manual Contents brings up the contents of the Online Manual, and you can use standard WinHelp tools to navigate about the document at that point. On the Contents page, you will find links to Common Lisp Contents, Common Graphics Contents, CLOS Contents, the Release Notes, a description of the Online Manual, and some other immediately useful entries.
You can produce a WinHelp word list for the Online Manual by clicking on Search, clicking on the Find tab in the dialog that appears, clicking on the Next button, and clicking on the Finish button. This takes a while the first time you do it (since an index file must be
created and stored) but it is worth doing because the additional search capability greatly enhances the usefulness of the Online Manual.
The Manual Entry choice allows you to go directly to a single entry. It brings up the documentation for the symbol nearest the text cursor. If there is no such symbol, or if the nearest symbol is not documented in the Online Manual, a message to that effect is printed in the status bar and the Online Manual does not come up.
Note that certain things, like format directives, are not named by symbols, so there is no way to go directly to their descriptions using Manual Entry. But because they are after the entry forformat, you can go to that entry and then page down or search to find the specific description of interest, or you can the new WinHelp search facilities.
Besides the entries on the main contents, an entry which is likely to be of particular interest to many users is Programming environment. This entry (it is the last item in the Lisp Contents entry) provides information on garbage collection, and other details of the implementation.
The Online Manual is sometimes referred to as Online Help.
Other documents for starting out
All users should look at the Programming Tools manual since this document describes how to use Allegro CL for Windows. Users new to Lisp may wish to look at the Common Lisp Introduction. Experienced Lisp users need not consult that document.
The Interface Builder is a very useful tool for constructing Graphical User Interfaces to Allegro CL for Windows applications. The Interface Builder manual tells how to use it.
Pictures in the documentation
There are many pictures derived from screen shots in the documentation. In some cases, we have converted the color and grayscale images to black and white. On your machine, the corresponding images will be in color or grayscale. For the same reason, those images do not use 3D effects.
Most of the images were created on a Windows 95 machine. Users of Windows 3.1 will often see dialogs and other features quite different from what is illustrated. (Some images were created on a Windows 3.1 machine, so Windows 95 users will see something differ- ent.)
Note too that the contents of windows, menus, and dialogs often reflect details of your
Debugge tures were made. Do not expect to see exactly what is illustrated. Instead, the pictures serve
as a guide to what you will see.
Change bars
Change bars (a black line to the left of the text -- this paragraph has a change bar) are some- times used to indicate new features or significantly changed functionality. The change is with respect to the 2.0 version of the manual. Where the functionality is the same, change bars are not typically used even if the text is rewritten.
4 When Allegro CL starts up
When you start Allegro CL for Windows, the screen will look something like this:
We have identified certain of the features:
• The Menu Bar. The standard Allegro CL menus are displayed. The contents of the menus are often self-explanatory. See section 2.5 The menubar in Programming Tools for more information.
• The Toolbar. Each button on the toolbar, when clicked on, either changes the state of Lisp or initiates some action. When the cursor is over a toolbar button, a description of what clicking on the button does is printed in the status bar. The toolbar can be hidden (and redisplayed) with the F12 key. See section 2.6 The toolbar in Programming Tools for more information.
Menu Bar Tool Bar
Initial Toploop Window Status Bar
Debugge
• The Toploop Window. Interaction with Lisp can go on through the Toploop window. See chapter 2 in Programming Tools for more information.
• The Status Bar. Information of interest is printed in the status bar by the system.
What is printed often depends on the location of the mouse, or on what you are typing. (Thus, when the mouse is over a button in the toolbar, the status bar displays what clicking on the button will do; and when you are entering a form in a Text Edit window -- like the Toploop Window -- the argument list of the operator in the form is displayed in the status bar.) The status bar can be hidden (and redisplayed) with the F11 key. Note that the status bar is always above any subwindow of*lisp-main-window*. Some windows are large enough that the status bar covers part of them. That is when the F11 key is particularly useful.
See section 2.7 The status bar in Programming Tools for more information.
5 Features of Microsoft Windows
You may already be familiar with the information in this section, particularly if you have used MicroSoft Windows for some time. Newcomers to Microsoft Windows may wish to review this section for shortcuts and hints when running Allegro CL for Windows. The illustrations and features are from a Windows 95 machine.
A window
Illustrated below is the Toploop window (which appears when you start Allegro CL for Windows) with some of its features identified:
These are all standard Windows features so we will not discuss them at length. When you press the left mouse button in the Program icon, a menu is displayed allowing you to minimize or close the window (along with other options). Clicking on the Close box or choosing Close from the Program icon menu is the same as Close in the File menu.
You can expand the window to cover the screen by clicking the Maximize button and make it smaller or into an icon by clicking the Minimize button.
Click above or below the bubble in the scroll bars to scroll the window in the desired direction. Windows can have horizontal as well as vertical scroll bars.
Program icon Window title Title bar Minimize button
Maximize button Close button (left to right)
Vertical scroll bar
Debugge
Menus
A good deal of input is done with menus. Whenever a program is running, the menu bar along the top of the screen contains menus appropriate for the program. These menus often have the same names but different items depending on what program is being run. In our documentation, we name menus with a capitalized word in no special font, usually fol- lowed by ‘menu’ -- thus the File menu and the Tools menu. Items (also called choices) in a menu are named with their title in Times Bold, thus the Exit item in the File menu.
Keyboard equivalents to menu items
The following illustration shows the File menu from the Allegro CL menu bar:
Note that each menu and most of the menu items have an underlined letter. This letter indicates how to display and choose from the menu without using the mouse. Hold the Alt key down and press the underlined letter in the menu title (‘F’ in the case of the File menu).
Keep the Alt key pressed. Press the letter underlined in the selection you want (‘S’ for Save and ‘A’ for Save As, for example). The result is the same as selecting the choice from the menu with the mouse.
Note that some choices have a key combination to the right of the choice. Pressing this key combination at any time is equivalent to selecting the menu item with the mouse. For example, the key combination Control-S (Crtl+S in the menu) is equivalent to selecting Save.
Note that not all items have keyboard equivalents using the Control key. A few menus and menu items do not have underlined letters indicating an Alt key shortcut (although all the ones illustrated do).
Interrupting
If Lisp seems not to respond, you can interrupt it by pressing the Break key (sometimes labeled Break and Pause). Keep the key pressed for several seconds. It may take Lisp sev- eral additional seconds to respond. When it does, it will display a Restarts dialog box sim- ilar to the following:
You typically choose Abort although you might choose Enter Debugger to see if you can determine why Lisp seemed to be hung (e.g. if it was in an infinite loop that does not process Windows events1). In any case, you once again have control. (There is also an Invoke Selected Restart button, but there are typically only two restarts that correspond to the other two buttons when computation is interrupted.)
What to do if the system hangs
Pressing Break as described just above is the best solution. If that does not work, you can press the combination Ctrl-Alt-Delete which may kill the Lisp process. That is pretty dras- tic since your work will be lost so only use it as a last resort when pressing Break has clearly failed. (If you are running Windows NT or Windows 95, Ctrl-Alt-Del has a less drastic effect, but you may still not be able to regain control without killing the task.)
1. See the description ofcg:process-pending-events in the Online Help. You should put calls to this function in cpu-intensive loops to ensure you can break out of them
Debugge
The two Enter keys
On most PC keyboards, there are two keys named ‘Enter’. One, next to the alphabetical keys, is typically named ‘Enter↵’ while the other, usually next to the numeric keypad, is simply named ‘Enter’. These two keys have different codes. In most circumstances, they can be used interchangeably but in some cases they cannot, including the following:
• In a Text Edit window, Enter ↵ is a carriage return while Enter calls for the current Lisp expression to be evaluated. This distinction is particularly important when text is selected (i.e. highlighted). Hitting Enter↵ replaces the highlighted text with a carriage return while Enter causes the text to be evaluated in the Toploop window.
Dialog boxes
Lisp (like many Windows applications) does some communication via dialog boxes. A Restarts dialog box is displayed when an error occurs, for example -- see the illustration under Interrupting above. Note that when a dialog box appears, it often controls the screen and you must choose one of its boxes (Invoke Selected Restart, Abort and Enter Debug- ger in the illustration above) before continuing with Lisp.
6 Getting information and patches
The World Wide Web page
Franz Inc. maintains a World Wide Web page. Its URL is http://www.franz.com
The page contains information about Allegro CL for Windows and other Franz Inc. prod- ucts. Of particular interest to users of Allegro CL for Windows is the ability to access the Allegro CL for Windows FAQ and patches.
The FAQ (Frequently Asked Questions) is a document written in question and answer format. It is updated regularly, often with answers to questions that the Franz Inc. support staff notices are common. Hints and tips (about optimizing code, for example) are also pro- vided. We recommend that users visit the WWW page from time to time and examine or download the current version of the FAQ.
What is a patch
A patch is a file (typically a .fsl file) that, when loaded into Allegro CL, fixes some problem or bug, or (more rarely) adds some feature. Patches are typically produced in response to a report of a bug (that is not trivial and does not have a simple workaround). Note that some features cannot be patched.
Getting patches
Patches are available via the Franz Inc. World Wide Web page. Access the page (whose URL address is given above) and follow directions to Allegro CL 3.0 for Windows patches.
You can download patches from the WWW page.
Debugge
Where to put patch files
Patch files should be in the UPDATE\ subdirectory of the Allegro CL distribution directory (the directory you specified when you installed Allegro CL for Windows). When you install Allegro CL for Windows, an empty UPDATE\ subdirectory is created. Thus, if you installed Allegro CL in the default location, which is C:\ALLEGRO, the update directory is C:\ALLEGRO\UPDATE.
All patches should be placed in this directory. When Allegro CL starts up, the patches in this directory are read into the image.
When patches are loaded
Patches are loaded when Allegro CL starts up. At that time, all patch files found in the UPDATE\ subdirectory are read into the Lisp image. At the same time a record of what patches are loaded is printed in the banner in the toploop window. Note that saved images do not typically load patches (see the Online Manual entry on save-image for more information).
Creating an image with patches loaded
You may find it desirable to create an image (withsave-image) that has all the patches loaded. When saving images, though, keep in mind that the whole environment is saved, including any changes introduced by the automatic loading of the startup files, prefs.lsp and startup.lsp. This means the saved image might have more changes than those introduced by the patches, and it is possible that the interaction between the startup files and the patches could cause Lisp to be in an inconsistent state, leading to mysterious failures. These failures would be hard to debug because suppressing the loading of startup files (a typical thing to do in the face of unexplained behavior) would not be possible because the files are already in the image.
Still, it is desirable to create such images. However, you must do it by hand. Here are the steps. We assume the Allegro CL distribution is in C:\ALLEGRO.
1. You should not read any startup files when creating an image with the patches.
There are four possible startup files, all located in the C:\ALLEGRO directory:
startup.lsp. startup.fsl, prefs.lsp, and prefs.fsl. Move all such files that exist to a different directory or change their names temporarily. Lisp will now start up without reading any startup file.
2. Start Allegro CL in the usual way. Do not type anything to the Toploop window or choose anything from any menu.
3. Choose Save Image... from the submenu displayed by choosing Images from the File menu.
4. Supply an image name when asked for one. The name should have the extension .img. Do not overwrite allegro.img or (if you have the Professional version) runtime.img, the image files created when you installed Allegro CL for Windows.
5. The Lisp will appear to restart. At this point, the image file has been created and you can exit from Lisp.
6. Restore any files moved in step 1 to their original location or name.
You may wish to create an icon in the Allegro CL for Windows program group for the saved image. See the Online Manual entry onsave-image for information on creating such an icon, and other ways to initiate a saved image. (The quick and dirty way is to start Allegro CL, choose Load Image... from the submenu displayed by choosing Images from the File menu, and specify your .img file to the dialog that appears.)
Note. An image including patches created as described above will not load fur- ther patches. If you receive more patches, put them in the UPDATE\ subdirectory and create a new image with patches loaded as described above, starting with the original Allegro CL image.
How do you know what patches are loaded in an image
Each patch file from Franz Inc. pushes its description ontoacl:*patches* when it is loaded. To see what patches are loaded, pretty-print the value ofacl:*patches*:
(pprint acl:*patches*)
Brief information on what patches are being loaded is printed in the banner when Alle- gro CL starts up.
What if a patch needs to be updated?
Sometimes a patch file introduces new problems as well as fixing old ones. In that case, a new patch file (with a later number) is created and the original patch file is replaced with a stub file. For this reason, please observe the following rules:
Debugge
• Always grab all patches that are available (including ones you have grabbed before). This will overwrite existing patch files, but that is what is wanted.
• Always start with the original image when creating a saved image with all patches loaded. The original image is the image created when Allegro CL is installed. Load all available patches and create a new saved image containing all patches.
7 Example files
Allegro CL for Windows is distributed with numerous examples of Lisp code, illustrating the Common Lisp language and the extensions supplied with Allegro CL for Windows. In this section, we provide a brief guide to these examples.
Where examples are located
All examples are in the ex directory included with the distribution. The following diagram shows the various subdirectories of ex:
ex
ext
lang
cg
comtab
txted topl
dialogs events other
pnt
pnit ffi16
runtime ffi32
stred
misc socket
dde metafile structed
ole mci
Debugge The examples are grouped according to category. The names are fairly descriptive. Here
is some more information on the directories.
The ext directory
This directory contains four subdirectories, with examples of comtabs, the text and structure editors, and the Toploop, in the obvious directories.
The lang directory
This directory contains examples from the manual Lisp Introductory Guide.
The cg directory
This directory contains subdirectories containing programs illustrating particular features of Common Graphics. The subdirectories have names that describe their contents. pnt is an abbreviation for paint.
The ffi16 and ffi32 directories
These directories contain examples illustrating the foreign function interface.
One is for 16-bit DLL’s, which only work in Win32s, and the other is for 32-bit DLL’s, which run under both Win32s and Windows NT. See the Foreign Func- tion Interface manual.
The runtime directory
This directory contains examples used to build runtime images. The runtime gen- erator is only distributed with the Professional version of Allegro CL for Win- dows, but the examples are in every distribution. See the Runtime Generator manual in the Professional supplement if you purchased the Professional version.
The structed directory
The structure editor is no longer part of Allegro CL for Windows. The source files for the structure editor are in this directory and can be loaded into Lisp to provide the functionality available in earlier releases. This is unsupported.
The dde directory
Examples and information on DDE can be found in this directory.
The socket directory
Code and instructions to establish interprocess communication (TCP) using win- sock.dll can be found in this directory. These examples will only work if you have
the Professional version of Allegro CL 3.0 for Windows or have purchased the Socket module.
The metafile directory
This directory contains a source file (with comments) for Windows Metafile sup- port. This code provided by a Allegro CL 3.0 for Windows customer is included as a service and is not supported.
The mci directory
This directory contains unsupported source code for a multimedia interface to Allegro CL 3.0 for Windows.
The ole directory
This directory contains an unsupported source code for an OLE interface to Alle- gro CL 3.0 for Windows.
Note that example files within lang are cumulative: that is, later (by number) files depend on code in earlier files. You should compile and load earlier files to be sure the later files will work.
Two text files appear in the ex directory: compiler.txt and hints.txt. They contain useful information about compiler optimization and using Allegro CL for Windows.
Debugge
8 Anomalies and things to note
In this chapter, we describe features of Allegro CL for Windows which may be different than you might expect. In each case, the behavior is what is intended (see also the Read This First document).
• There is a 32K limit on the size of files that can be edited by the text editor (and thus on the size of Lisp source files that can be opened). If you try to open a larger file, the following error will be signaled:
If you have a file open and add text so the 32K limit is reached, the system will not accept additional text (but will not signal an error). (32K is typically between 500 and 1000 lines of text, depending on the average number of characters per line.) Large files should be broken up into smaller pieces if you wish to use the text editor on them. Note, however, thatload andcompile-file are not affected by the 32K limit.
• The Lisp image will grow as necessary, but only to the limit specified in the allegro.ini file included in the distribution (it is located in the directory where the distribution disks were installed -- typically c:\allegro\). Here are the default contents of the file:
The maximum heap size is specified by the HeapSize line. The initial value is 16.00 (indicating 16 Megabytes). You may increase this value to allow for larger images, if desired. The other parameters control the behavior of the garbage col- lector and typically do not need to be changed by users. See the entry on Storage Use under the topic Programming environment the Online Manual.
• If you initiate stepping with the macrostep in a Toploop window, a Stepper window appears (as you would expect). You cannot type to the Toploop window until stepping has completed, however. This is because the Toploop window is evaluating the form with step and you must wait until that form completes before new input is accepted. See chapter 8 of the Programming Tools Introduction for more information on Stepper windows.
• Common Lisp is for the most part case-insensitive. Except within strings (i.e.
characters surrounded by " marks), uppercase and lowercase letters will read the same. Thus, enteringcar,CAR,Car, orcaR all denote the symbolCAR. The system typically prints in the case specified by the variable*print-case*.
The initial value of that variable is:upcase, so initially the system prints in uppercase. In the documentation, we typically use lowercase, since we believe it is more readable. If you keep in mind that, outside of strings, for most purposes, there is no difference between upper and lowercase, the mixture of upper and lower should not be confusing.
Debugge
Professional and standard versions are incompatible!
Compiled Lisp (fsl) files generated by the Professional version cannot be read into the stan- dard version and fsl files generated by the standard version cannot be read into the Profes- sional Version.
Image (img) files generated by the Professional version cannot loaded into the standard version (with load-image) and cannot be invoked with the standard version lisp.exe. Image files generated by the standard version cannot be loaded into the Professional version (with load-image) and cannot be invoked by the Professional version lisp.exe.
Version 2.0 fsl and img files cannot be used by version 3.0
Compiled Lisp (fsl) files generated by the Allegro CL version 2.0 (or 1.0) cannot be read into Allegro CL 3.0 nor can 2.0 or 1.0 image files (img) be loaded into Allegro CL version 3.0.
Do not use 2.0 patches including FAQ patches
Some patches (in some cases enhancements) for Allegro CL version 2.0 were distributed in source form, either in the FAQ document or obtained directly from Franz Inc. Do not use these source patches in version 3.0. In most cases the functionality is already present. If it is not, please contact Franz Inc. for information on whether the source patch can be used.
9 Support
Support is available for Allegro CL for Windows. In order to get support, you must first register your purchase with Franz Inc. Instructions for registering your purchase and infor- mation on support are included in the Allegro CL for Windows distribution. See the section Support in the Read This First document for more information. If you have misplaced the Read This First document, please write to us at the address below for information on reg- istration and support. Support for Professional version customers is also described in the Professional supplement.
Franz Inc.
Allegro CL for Windows Support 1995 University Ave.
Berkeley, CA 94704 USA
510-548-3600 info@franz.com
Debugge
Index
A
Allegro CL for Windows anomalies 23 case-insensitive 24 documentation 6 FAQ 16
image size 24 installation 2
maximum image size 24 patches 16
Professional version 3, 4, 7, 18, 21, 25 screen on startup 10
Standard version 3, 4, 25 support 26
things to note 23 WWW page 16
allegro.ini (initialization file) 24
Alt key (used for selecting menu items) 13 anomalies in Allegro CL for Windows 23
B
Break key
interrupting Lisp 14 breaking into Lisp 14 bug fixes (see patches) 16
C
c:\allegro (default installation directory) 3 case-insensitivity 24
cg (directory of examples) 21 Close box 12
Common Graphics example directory 21
D
dde (directory of examples) 21 dialog boxes
discussed 15
used with Allegro CL for Windows 15 difference between two Enter keys 15 documentation of Allegro CL for Windows 6
E
Editor
size limit 23 Enter key 15
two Enter keys described 15 example files 20
examples
cg directory 21 dde directory 21 ext directory 21 ffi directory 21
files supplied with Allegro CL for Windows 20 lang directory 21
metafile directory 22 runtime directory 21 structed directory 21 ext (directory of examples) 21
F
FAQ (Frequently Asked Questions document for Allegro CL for Windows) 16 ffi (directory of examples) 21
filename length restriction 5 foreign function interface
directory of examples 21
Foreign Function Interface (manual) 6 Franz Inc. (address and phone number) 26
G
General Index (manual) 6 Getting Started (manual) 6
Debugge
H
hangs 14
HeapSize (initialization parameter) 24 how to install 2
I
image size how to set 24 maximum 24
information about Allegro CL for Windows 16 Inside Programming Tools (manual) 6 installation 2
filename length restriction 5
how to install Allegro CL for Windows 3 reinstallation 4
Interface Builder Manual (manual) 6 interrupting Lisp 14
L
lang (directory of examples) 21 Lisp
interrupting 14 things to note 23
M
manuals 6
change bars 9
Common Lisp Introduction 6 Foreign Function Interface 6 General Index 6
Getting Started 6
Inside Programming Tools 6 Interface Builder Manual 6 Online Manual 7
pictures in 8
Professional supplement 7 Read This First 6
Runtime Generator (in Professional supplement) 7
maximize button (in a window) 12 menu bar 10
menu items
selecting with Alt key 13 menus
Allegro CL for Windows menus 13 keyboard equivalents 13
selecting items with Alt key 13 metafile (directory of examples) 22 MicroSoft Windows (operating system) 12 minimize button (in a window) 12
MS Windows (operating system) 12
N
no response, what to do 14
O
Online Manual 7
P
patches (fixes to Allegro CL) 16
always grab all available patches 19 creating an image with patches loaded 17 do not use patches from release 2.0 25 how to get 16
replacing patches that are defective 18 saved images do not load patches 17 telling what patches have been loaded 18 updating patches 18
what they are 16
when they are loaded 17 where to put patch files 17
process-pending-events (function, common-graphics package) should be called within cpu-intensive loops 14
Professional supplement manual 7
Professional version of Allegro CL for Windows 3, 4, 7, 18, 21, 25 incompatible with Standard version) 25
program icon (in a window, left clicking displays a menu) 12
Debugge
R
Read This First (manual) 6 reinstallation 4
runtime (directory of examples) 21 Runtime Generator
directory of examples 21
Runtime Generator (manual, part of Professional supplement) 7
S
scroll bar (in a window) 12 serial number 3
Standard version of Allegro CL for Windows 3, 4, 5, 25 incompatible with Professional version) 25
status bar 11 step (macro)
and stepper window 24 structed (directory of examples) 21 support (availability of) 26
system hanging (what to do) 14
T
Text Editor
32K file size limit 23 size limit 23
32K size limit for text editor files 23 toolbar 10
Toploop Window 11
U
Uninstall (program for uninstalling Allegro CL for Windows) 5
W
what to do if system hangs 14
Win32s (upgrade to MS Windows 3.1, needed for ALLegro CL) 2 installing 2
window
typical Allegro CL for Windows window illustrated 12 Windows 3.1 (Allegro CL for Windows and) 2
Windows 95 (Allegro CL for Windows and) 2
Windows for Workgroups (Allegro CL for Windows and) 2 Windows NT (Allegro CL for Windows and) 2
Windows operating system features described 12 World Wide Web page 16
URL address (http://www.franz.com) 16 WWW page 16
Debugge
Allegro CL for Windows
Lisp Introductory Guide
version 3.0
October, 1995
Copyright and other notices:
This is revision 1 of this manual. This manual has Franz Inc. document number D-U-00- PC0-03-51017-3-1.
Copyright1992-1995 by Franz Inc. 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, by photocopying or recording, or otherwise, without the prior and explicit written permission of Franz incorporated.
Restricted rights legend: Use, duplication, and disclosure by the United States Government are subject to Restricted Rights for Commercial Software developed at private expense as specified in DOD FAR 52.227-7013 (c) (1) (ii).
Allegro CL is a registered trademark of Franz Inc.
Allegro CL for Windows is a trademark of Franz Inc.
Windows, MS Windows, MS-DOS, and DOS are trademarks of Microsoft.
Franz Inc.
1995 University Avenue Berkeley, CA 94704 U.S.A.
Index
Contents
Preface
1 Introduction
1.1 Getting started 1-2
2 Basic data manipulation
2.1 Defining lists 2-1
2.2 Adding to and removing from lists 2-3 2.3 Introduction to defining functions 2-3 2.4 Inserting comments 2-5
2.5 The super parenthesis 2-5
3 Arithmetic
3.1 Performing calculations 3-1 3.2 Testing numbers 3-4
4 List manipulation
4.1 Extracting elements 4-1 4.2 Substituting elements 4-4 4.3 Combining lists 4-4
5 Introducing input and output
5.1 print and read 5-1 5.2 eval 5-3
5.3 Printing special characters 5-4 5.4 Derivatives of print 5-5
6 Binding and scope
6.1 Free and bound variables 6-1 6.2 Scope 6-3
7 Conditionals
7.1 Testing symbols 7-1 7.2 Logical operators 7-3 7.3 Conditional testing 7-3
8 Iteration and recursion
8.1 Introduction 8-1 8.2 Iteration 8-1 8.3 Recursion 8-5
9 Data structures
9.1 Association lists 9-1 9.2 Property lists 9-2 9.3 Arrays 9-5
9.4 Data abstraction 9-6
10 Lambda
10.1 mapcar 10-1 10.2 apply 10-2 10.3 Filtering 10-3
10.4 Functions as arguments 10-4 10.5 Optional arguments 10-5
11 Macros 12 List storage
12.1 How lists are stored 12-1 12.2 How lists are modified 12-4 12.3 Garbage collection 12-9 12.4 equal, eql and = 12-9
Index
13 An Introduction to CLOS
13.1 Generic functions 13-1 13.2 Classes 13-2
13.3 Slots and a better example 13-3 13.4 Class inheritance 13-6
13.5 Method combination 13-8 13.6 Other method types 13-9
13.7 Shared slots and initialize-instance 13-11 13.8 Beyond scratching the surface... 13-12
14 Errors
14.1 Typical error messages 14-1 14.2 User-defined error messages 14-5
14.3 ‘Attempt to set non-special free variable’ warning 14-6
Appendix A Glossary
Index
[This page intentionally left blank.]
Glossary
PREFACE
This manual Common Lisp Introduction, provides an introduction to Common Lisp as a programming language. Users who are unfamiliar with Common Lisp can learn about pro- gramming in Common Lisp from this manual. Note, however, that this manual does not describe how to use Allegro CL for Windows, in the sense of describing the user interface.
Users familiar with Common Lisp but new to Allegro CL for Windows would do better to start with the Programming Tools, which is in volume 2 of the printed documentation.
We are less formal in this manual than in other manuals. We do not concern ourselves particularly with packages and we often provide abbreviate definitions of functions, leaving out, for example, keyword and/or optional arguments not needed to explain the point we are making. Users interested in formal definitions of Lisp functions, variables, macros, etc.
should refer to the Online Manual, where all Common Lisp functions, Allegro CL exten- sions of standard Common lisp functions, CLOS and MOP, and Common Graphics are described. The Online Manual is further described at the end of this preface.
The format for defining functions and other objects is also different in this manual than in the Reference Guides. Here is a typical function definition:
zerop tests whether a number is zero.zerop is clearer and more efficient than the equivalent(= number 0).
The object being described is indented but on the left. The description is in Helvetica type font on the right. Most of the rest of the text is in Times Roman (the same as this para- graph). Examples and code samples are inCourier.
There are online code examples supplied with the Allegro CL for Windows distribution.
They are in the ex\lang\ directory read off the distribution disks (typically in the allegro\
directory if you followed the default installation instructions). You can try out those exam- ples as you read the text. In general, the example filename reflects the chapter from which the examples are drawn. Note that the examples are cumulative -- that is, examples from later (by number) files may depend on definitions in earlier files.
We have tried to provide in this manual enough information for a user new to Lisp to start programming in Lisp. You may, however, want to supplement this manual with other books about programming in Lisp. There are many on the market. A good general introduc- tion is Lisp by Patrick Winston and Berthold Horn (make sure you use the 3rd or later edi-
tion). A widely admired book introducing CLOS is Object-Oriented Programming in Common Lisp by Sonya Keene. Both of these books are published by Addison-Wesley of Reading Massachusetts and should be available from any good bookstore selling computer- related books.
The Online Manual
Most of the Common Lisp language, including CLOS, is described in the Online Manual.
There is no printed documentation for general Lisp functionality other than the manual you are now reading. The Online Manual is brought up by choosing either Manual Entry or Manual Contents from the Help menu:
The Online Manual is organized into chapters, and in each chapter, the relevant func- tionality is defined. If you choose Manual Entry, it will open to the definition of the sym- bol nearest the text cursor if there is one. If there is no such symbol, that fact will be reported in the status bar and the Online Manual will not be displayed. If the nearest symbol does not have a definition in the Online Manual, again that fact will be reported in the Status Bar and the Online Manual will not be displayed. To see the contents of the Online Manual, choose Manual Contents.
Introduction
Chapter 1 Introduction
This guide is designed to introduce Allegro CL for Windows to those who are familiar with conventional programming languages and techniques but have no experience with Lisp. It is not intended to provide an in-depth understanding of Allegro CL for Windows but should give a sound introduction to the language and concepts of symbolic programming.
Lisp (the name is derived from LISt Processing) provides all the features of a general- purpose language but the original objective was to create a language which uses human expressions and which closely resembles human thinking and reasoning. In time, many
‘dialects’ have evolved, but efforts have been made to combine the best features from these, resulting in the definition of an industry standard known as Common Lisp. Allegro CL for Windows adheres strictly to this standard while offering many additional enhancements including powerful graphics capabilities and an integrated programming environment.
Many of the early criticisms of Lisp concerning speed, size, and complexity have been successfully addressed as the language has developed and it is hoped that you will find Allegro CL for Windows a powerful, efficient and flexible development tool for all appli- cations.
Please note that unless otherwise stated, all comments made about Lisp will refer to both Common Lisp and Allegro CL for Windows.
1.1 Getting started
Lisp is a language which demands precise syntax, since it makes no distinction when stor- ing between data and program. It uses terminology which may be familiar, totally new, or have different meanings in conventional languages. Other publications about the language introduce words or phrases which serve only to add to the confusion. We have therefore striven to keep these to a minimum throughout the text, but we have included the more common ones in a glossary in the appendix.
Most programs are called functions and there are many useful functions provided by Lisp. To call a function, a typical format would be:
(fn a1 a2 ... an)
wherefn is the function name anda1 ...an are the arguments.
Consider this simple example:
(+ 3 2 5)
where + is the function of addition and 3, 2, and 5 are the arguments. 10 is the value returned.
Unlike conventional mathematical notation, the function (in this case, addition) appears first. It is also possible to combine functions but it is important to remember that Lisp always evaluates the arguments before applying the function. Using another simple mathematical example, we can subtract two numbers and divide the result as a single oper- ation:
(/ (- 28 4) 2)
In this example, the argument(- 28 4) is evaluated first and the returned value is then divided by 2. Note that the argument(- 28 4) is in itself a function call and therefore follows the function syntax format.
This is how the Top Loop window should appear on the screen. (You will see an actual date and time, of course, but they were determined after this manual went to the printers.)
Introduction
So far we have used mathematical examples, but Lisp’s greatest strength lies in its abil- ity to manipulate symbolic data which has no mathematical context. This will become clear in the following chapter. It will be helpful if you try out the examples as we go along. You can read the example files into a text edit window. You can evaluate the forms in the exam- ples by placing the cursor at the beginning of the form and pressing Alt-Enter (equivalently, pressing the Enter key next the numeric keypad). You can also type the examples in directly. In that case, input may be followed by a carriage return, that is, the Enter key next the alphabetic keyboard, thus allowing you to lay out your programs to make them easier to read. Lisp will not try to execute until it sees a complete form and then the form will be evaluated.
[This page intentionally left blank.]
Basic datamanipulation
Chapter 2 Basic data manipulation
In Lisp there are three basic types of data which are known as symbols, numbers, and lists.
• Symbols are named data objects. For example,dog,cat andman are symbols.
They may also be functions and variables used within programs and have some other features which are explained later.
• Numbers fall into four categories: Integers, Floating-point, Ratios and Complex.
13, -56.2, 22/7 and #C(0 2) are examples of each of these categories of numbers:
#C(0 2) is the square root of -4, namely 0 + 2i.
• A list is a series of elements enclosed in parentheses. Each element may be a symbol, number or another list, thus nested structures can be constructed to represent complex data.(dog bites man) is a list of three elements.
In Lisp, an item of data can be evaluated to yield a value. In this context, such an item is referred to as a form. As we shall see later, Lisp programs are simply collections of forms to be evaluated. Some forms in the following examples may be preceded by a quote mark (’) which indicates that the form is not to be evaluated; it is a literal expression. The quote mark will be discussed later in more detail, as willsetf which also appears below.
2.1 Defining lists
Let us assume that we wish to create a list of things that we like. Remembering that the ele- ments must be enclosed in parentheses, our list could be:
(lasagne claret ferraris mozart summer)
In order to refer to this list without typing it out in full each time, a name can be given to it such aslikes and this assignment would be done as follows:
(setf likes
’(lasagne claret ferraris mozart summer)) to which Lisp would respond:
(LASAGNE CLARET FERRARIS MOZART SUMMER)
likes now has the list as its value, and the list is returned as the value of thesetf form. In this example, we are not primarily interested in the returned value, but in the assignment which took place. The assignment is described as a side effect of the evaluation.
Note: Many forms, especially mathematical ones, have no side effects and are eval- uated simply to return a value. However, side effects should always be borne in mind, as unexpected ones can cause bugs.
The contents of any expression are displayed by typing its name. For instance, likes
would return:
(LASAGNE CLARET FERRARIS MOZART SUMMER)
In a similar way, we can assign the things we dislike to another list calleddislikes, and display the contents as follows:
(setf dislikes
’(taxation cocktails skiing rain (hairy spiders) work))
→ (TAXATION COCKTAILS SKIING RAIN (HAIRY SPIDERS) WORK) dislikes
→ (TAXATION COCKTAILS SKIING RAIN (HAIRY SPIDERS) WORK)
In this example, we not only have a list of individual elements we dislike, but we also have a list as an element of the list, namely(hairy spiders). All the elements are top- level elements whilehairy andspiders are second level elements.
Basic datamanipulation
2.2 Adding to and removing from lists
Having defined our lists, we may wish to add or remove elements. If, for example,skiing has been assigned to the wrong list, it must be removed fromdislikes and added to likes. Lisp provides some built-in functions which allow us to do this.
cons Thecons function adds an item to the front of a list. It takes two arguments: the second argument must be a list, but the first may be any element.
(setf likes (cons ’skiing likes))
→ (SKIING LASAGNE CLARET FERRARIS MOZART SUMMER)
skiing is added to the elements stored inlikes and the result is assigned back to likes.
remove The functionremove deletes an item from a list. Likecons, it accepts two arguments, the second of which must be a list.
(setf dislikes (remove ’skiing dislikes))
→ (TAXATION COCKTAILS RAIN (HAIRY SPIDERS) WORK)
skiing is deleted from the elements stored indislikes and the result is assigned back todislikes.
Note: In both these examples the functionscons andremove do not affect the original lists: they create temporary lists. In order to make these changes perma- nent,setf is used to assign the temporary lists to the original ones.
2.3 Introduction to defining functions
In order to define a function, Lisp needs to know three things:
1. The name of the function.
2. The number of arguments it needs.
3. The task the function is to perform.
To combine the two steps in our previous example, we can write a simple function to which we will give the namenewlikes. This is the name that will be used each time we wish to call this function.
defun This macro lets you define your own functions.
(defun newlikes (name)
(setf likes (cons name likes))
(setf dislikes (remove name dislikes)))
→ NEWLIKES
In the above example, the three requirements are met as follows:
1. The name of the function isnewlikes.
2. There is one argument, the variablename.
3. The function takes the value of the variable name, adds it to the list likes and removes it from the listdislikes.
Note: Even though thedefun form is defining a function, it is still evaluated and, in this case, returns the name of the function,newlikes.
If we now wish to call our function to transfer cocktails fromdislikes tolikes, we do so in this way:
(newlikes ’cocktails)
→ (TAXATION RAIN (HAIRY SPIDERS) WORK)
newlikes returns the modified listdislikes since this is the value returned by the last form within the function.
newlikes now joins the built-in functions1 (cons,remove,+,/, etc.) and becomes another function we can call at any time. It is in every way the equal of these functions.
Unlike some other programming languages, there is nothing special or “magic” about built- in functions.
Basic datamanipulation
2.4 Inserting comments
In any programming environment, meaningful comments are invaluable to the program- mer: they make the code easier to understand and therefore easier to modify or debug. The start of a comment in Lisp is indicated by a semicolon, and all text following it to the end of the line is ignored.
(defun newlikes (name)
;add name to start of likes (setf likes (cons name likes)) ;delete name from dislikes
(setf dislikes (remove name dislikes)))
→ NEWLIKES
Throughout this guide we have tried to make the examples self-explanatory and com- ments are therefore only given to clarify particular points. However, we recommend that you include as many comments as necessary to make your own code easier to understand.
Remember that although you know exactly what a program does when you write it, you will probably have forgotten in six months’ time when you look at it again.
2.5 The super parenthesis
The above functionnewlikes requires three parentheses at the end to terminate the func- tion correctly. This is made easy for you with the automatic flashing of parentheses which match. However, as you begin to write more complex functions, you could require five or more concluding parentheses. Rather than relying on the flashing of matching parentheses, you can finish with a single ‘super-bracket’: a right-hand square bracket (]). This instructs Lisp to terminate all matching parentheses. You may wish to try this on some of the exam- ples.
[This page intentionally left blank.]
![TraditionalMLCalgorithmsmainlytacklethebatchMLCproblem,wheretheinputdataarepresentedinabatch[24,28].Nevertheless,inmanyMLCapplicationssuchase-mailcategorization[22],multi-labelexamplesarriveasastream.Onlineanalysisistherefore dimensionreducermotivatedbyma](data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==)