============================= -*- Mode: view -*- ============================== =============================================================================== +----------------------------------+ | | | Guy L. Steele Jr. | | | | C O M M O N | | | | ## ###### #### ##### | | ## ## ## ## ## ## | | ## ## ## ## ## | | ## ## ## ##### | | ## ## ## ## | | ## ## ## ## ## | | ###### ###### #### ## | | | | +-----------------+ | | | Text Version by | | | | | | | | Eli Barzilay: | | | | | | | | Maze is Life! | | | | | | | | eli@barzilay.org| | | | 11/9/95| | | +-----------------+ | | | | THE LANGUAGE | | ------------- | | SECOND EDITION | | | +----------------------------------+ This is a text version of the book, it was made manually and therefore should not suffer from automatic conversions limitations - it should all be readable, including mathematical equations which were written to be understood and not to be printed. There are no fonts notations, its all simple text (which could be read or searched) - there are probably places where understanding is harder due to this - it isn't a replacement for the textbook. Use Emacs for best results (and for fun) - there are very uniform patterns that you can use - like functions headers, chapter/section headers, implementation notes, figures, X3J13 votes etc. This file is too big for some editors, splitting it should not be much trouble. Bugs, comments & requests are welcome - eli@barzilay.org. Eli Barzilay: Maze is Life! =============================================================================== C o m m o n L i s p T h e L a n g u a g e Second Edition Guy L. Steele Jr. -- Thinking Machines Corporation with contributions by Scott E. Fahlman -- Carnegie-Mellon University Richard P. Gabriel -- Lucid, Inc., Stanford University David A. Moon -- Symbolics, Incorporated Daniel L. Weinreb -- Symbolics, Incorporated and with contributions to the second edition by Kent M. Pitman -- Symbolics, Incorporated Richard C. Waters -- Massachusetts Institute of Technology Jon L White -- Lucid, Inc. copyright 1984, 1989 Guy L. Steele Jr. All rights reserved. To be published by Digital Press. Would it be wonderful if, under the pressure of all these difficulties, the Convention should have been forced into some deviations from that artificial structure and regular symmetry which an abstract view of the subject might lead an ingenious theorist to bestow on a constitution planned in his closet or in his imagination? -- James Madison, The Federalist No. 37, January 11, 1788 =============================================================================== <#### Preface (Second Edition) ####> <#### Acknowledgments (Second Edition) ####> <#### Acknowledgments (First Edition) ####> 1. <#### Introduction ####> 1.1. <### Purpose ###> 1.2. <### Notational Conventions ###> 1.2.1. <## Decimal Numbers ##> 1.2.2. <## Nil, False, and the Empty List ##> 1.2.3. <## Evaluation, Expansion, and Equivalence ##> 1.2.4. <## Errors ##> 1.2.5. <## Descriptions of Functions and Other Entities ##> 1.2.6. <## The Lisp Reader ##> 1.2.7. <## Overview of Syntax ##> 2. <#### Data Types ####> 2.1. <### Numbers ###> 2.1.1. <## Integers ##> 2.1.2. <## Ratios ##> 2.1.3. <## Floating-Point Numbers ##> 2.1.4. <## Complex Numbers ##> 2.2. <### Characters ###> 2.2.1. <## Standard Characters ##> 2.2.2. <## Line Divisions ##> 2.2.3. <## Non-standard Characters ##> 2.2.4. <## Character Attributes ##> 2.2.5. <## String Characters ##> 2.3. <### Symbols ###> 2.4. <### Lists and Conses ###> 2.5. <### Arrays ###> 2.5.1. <## Vectors ##> 2.5.2. <## Strings ##> 2.5.3. <## Bit-Vectors ##> 2.6. <### Hash Tables ###> 2.7. <### Readtables ###> 2.8. <### Packages ###> 2.9. <### Pathnames ###> 2.10. <### Streams ###> 2.11. <### Random-States ###> 2.12. <### Structures ###> 2.13. <### Functions ###> 2.14. <### Unreadable Data Objects ###> 2.15. <### Overlap, Inclusion, and Disjointness of Types ###> 3. <#### Scope and Extent ####> 4. <#### Type Specifiers ####> 4.1. <### Type Specifier Symbols ###> 4.2. <### Type Specifier Lists ###> 4.3. <### Predicating Type Specifiers ###> 4.4. <### Type Specifiers That Combine ###> 4.5. <### Type Specifiers That Specialize ###> 4.6. <### Type Specifiers That Abbreviate ###> 4.7. <### Defining New Type Specifiers ###> 4.8. <### Type Conversion Function ###> 4.9. <### Determining the Type of an Object ###> 4.10. <### Type Upgrading ###> 5. <#### Program Structure ####> 5.1. <### Forms ###> 5.1.1. <## Self-Evaluating Forms ##> 5.1.2. <## Variables ##> 5.1.3. <## Special Forms ##> 5.1.4. <## Macros ##> 5.1.5. <## Function Calls ##> 5.2. <### Functions ###> 5.2.1. <## Named Functions ##> 5.2.2. <## Lambda-Expressions ##> 5.3. <### Top-Level Forms ###> 5.3.1. <## Defining Named Functions ##> 5.3.2. <## Declaring Global Variables and Named Constants ##> 5.3.3. <## Control of Time of Evaluation ##> 6. <#### Predicates ####> 6.1. <### Logical Values ###> 6.2. <### Data Type Predicates ###> 6.2.1. <## General Type Predicates ##> 6.2.2. <## Specific Data Type Predicates ##> 6.3. <### Equality Predicates ###> 6.3. <### Logical Operators ###> 7. <#### Control Structure ####> 7.1. <### Constants and Variables ###> 7.1.1. <## Reference ##> 7.1.2. <## Assignment ##> 7.2. <### Generalized Variables ###> 7.3. <### Function Invocation ###> 7.4. <### Simple Sequencing ###> 7.5. <### Establishing New Variable Bindings ###> 7.6. <### Conditionals ###> 7.7. <### Blocks and Exits ###> 7.8. <### Iteration ###> 7.8.1. <## Indefinite Iteration ##> 7.8.2. <## General Iteration ##> 7.8.3. <## Simple Iteration Constructs ##> 7.8.4. <## Mapping ##> 7.8.5. <## The "Program Feature" ##> 7.9. <### Structure Traversal and Side Effects ###> 7.10. <### Multiple Values ###> 7.10.1. <## Constructs for Handling Multiple Values ##> 7.10.2. <## Rules Governing the Passing of Multiple Values ##> 7.11. <### Dynamic Non-Local Exits ###> 8. <#### Macros ####> 8.1. <### Macro Definition ###> 8.2. <### Macro Expansion ###> 8.3. <### Destructuring ###> 8.4. <### Compiler Macros ###> 8.5. <### Environments ###> 9. <#### Declarations ####> 9.1. <### Declaration Syntax ###> 9.2. <### Declaration Specifiers ###> 9.3. <### Type Declaration for Forms ###> 10. <#### Symbols ####> 10.1. <### The Property List ###> 10.2. <### The Print Name ###> 10.3. <### Creating Symbols ###> 11. <#### Packages ####> 11.1. <### Consistency Rules ###> 11.2. <### Package Names ###> 11.3. <### Translating Strings to Symbols ###> 11.4. <### Exporting and Importing Symbols ###> 11.5. <### Name Conflicts ###> 11.6. <### Built-in Packages ###> 11.7. <### Package System Functions and Variables ###> 11.8. <### Modules ###> 11.9. <### An Example ###> 12. <#### Numbers ####> 12.1. <### Precision, Contagion, and Coercion ###> 12.2. <### Predicates on Numbers ###> 12.3. <### Comparisons on Numbers ###> 12.4. <### Arithmetic Operations ###> 12.5. <### Irrational and Transcendental Functions ###> 12.5.1. <## Exponential and Logarithmic Functions ##> 12.5.2. <## Trigonometric and Related Functions ##> 12.5.3. <## Branch Cuts, Principal Values, and Boundary Conditions in the Complex Plane ##> 12.6. <### Type Conversions and Component Extractions on Numbers ###> 12.7. <### Logical Operations on Numbers ###> 12.8. <### Byte Manipulation Functions ###> 12.9. <### Random Numbers ###> 12.10. <### Implementation Parameters ###> 13. <#### Characters ####> 13.1. <### Character Attributes ###> 13.2. <### Predicates on Characters ###> 13.3. <### Character Construction and Selection ###> 13.4. <### Character Conversions ###> 13.5. <### Character Control-Bit Functions ###> 14. <#### Sequences ####> 14.1. <### Simple Sequence Functions ###> 14.2. <### Concatenating, Mapping, and Reducing Sequences ###> 14.3. <### Modifying Sequences ###> 14.4. <### Searching Sequences for Items ###> 14.5. <### Sorting and Merging ###> 15. <#### Lists ####> 15.1. <### Conses ###> 15.2. <### Lists ###> 15.3. <### Alteration of List Structure ###> 15.4. <### Substitution of Expressions ###> 15.5. <### Using Lists as Sets ###> 15.6. <### Association Lists ###> 16. <#### Hash Tables ####> 16.1. <### Hash Table Functions ###> 16.2. <### Primitive Hash Function ###> 17. <#### Arrays ####> 17.1. <### Array Creation ###> 17.2. <### Array Access ###> 17.3. <### Array Information ###> 17.4. <### Functions on Arrays of Bits ###> 17.5. <### Fill Pointers ###> 17.6. <### Changing the Dimensions of an Array ###> 18. <#### Strings ####> 18.1. <### String Access ###> 18.2. <### String Comparison ###> 18.3. <### String Construction and Manipulation ###> 19. <#### Structures ####> 19.1. <### Introduction to Structures ###> 19.2. <### How to Use Defstruct ###> 19.3. <### Using the Automatically Defined Constructor Function ###> 19.4. <### Defstruct Slot-Options ###> 19.5. <### Defstruct Options ###> 19.6. <### By-Position Constructor Functions ###> 19.7. <### Structures of Explicitly Specified Representational Type ###> 19.7.1. <## Unnamed Structures ##> 19.7.2. <## Named Structures ##> 19.7.3. <## Other Aspects of Explicitly Specified Structures ##> 20. <#### The Evaluator ####> 20.1. <### Run-Time Evaluation of Forms ###> 20.2. <### The Top-Level Loop ###> 21. <#### Streams ####> 21.1. <### Standard Streams ###> 21.2. <### Creating New Streams ###> 21.3. <### Operations on Streams ###> 22. <#### Input/Output ####> 22.1. <### Printed Representation of Lisp Objects ###> 22.1.1. <## What the Read Function Accepts ##> 22.1.2. <## Parsing of Numbers and Symbols ##> 22.1.3. <## Macro Characters ##> 22.1.4. <## Standard Dispatching Macro Character Syntax ##> 22.1.5. <## The Readtable ##> 22.1.6. <## What the Print Function Produces ##> 22.2. <### Input Functions ###> 22.2.1. <## Input from Character Streams ##> 22.2.2. <## Input from Binary Streams ##> 22.3. <### Output Functions ###> 22.3.1. <## Output to Character Streams ##> 22.3.2. <## Output to Binary Streams ##> 22.3.3. <## Formatted Output to Character Streams ##> 22.4. <### Querying the User ###> 23. <#### File System Interface ####> 23.1. <### File Names ###> 23.1.1. <## Pathnames ##> 23.1.2. <## Case Conventions ##> 23.1.3. <## Structured Directories ##> 23.1.4. <## Extended Wildcards ##> 23.1.5. <## Logical Pathnames ##> 23.1.5.1. <# Syntax of Logical Pathname Namestrings #> 23.1.5.2. <# Parsing of Logical Pathname Namestrings #> 23.1.5.3. <# Using Logical Pathnames #> 23.1.5.4. <# Examples of the Use of Logical Pathnames #> 23.1.5.5. <# Discussion of Logical Pathnames #> 23.1.6. <## Pathname Functions ##> 23.2. <### Opening and Closing Files ###> 23.3. <### Renaming, Deleting, and Other File Operations ###> 23.4. <### Loading Files ###> 23.5. <### Accessing Directories ###> 24. <#### Errors ####> 24.1. <### General Error-Signaling Functions ###> 24.2. <### Specialized Error-Signaling Forms and Macros ###> 24.3. <### Special Forms for Exhaustive Case Analysis ###> 25. <#### Miscellaneous Features ####> 25.1. <### The Compiler ###> 25.1.1. <## Compiler Diagnostics ##> 25.1.2. <## Compiled Functions ##> 25.1.3. <## Compilation Environment ##> 25.1.4. <## Similarity of Constants ##> 25.2. <### Documentation ###> 25.3. <### Debugging Tools ###> 25.4. <### Environment Inquiries ###> 25.4.1. <## Time Functions ##> 25.4.2. <## Other Environment Inquiries ##> 25.5. <### Identity Function ###> 26. <#### Loop ####> 26.1. <### Introduction ###> 26.2. <### How the Loop Facility Works ###> 26.3. <### Parsing Loop Clauses ###> 26.3.1. <## Order of Execution ##> 26.3.2. <## Kinds of Loop Clauses ##> 26.3.3. <## Loop Syntax ##> 26.4. <### User Extensibility ###> 26.5. <### Loop Constructs ###> 26.6. <### Iteration Control ###> 26.7. <### End-Test Control ###> 26.8. <### Value Accumulation ###> 26.9. <### Variable Initializations ###> 26.10. <### Conditional Execution ###> 26.11. <### Unconditional Execution ###> 26.12. <### Miscellaneous Features ###> 26.12.1. <## Data Types ##> 26.12.2. <## Destructuring ##> 27. <#### Pretty Printing ####> 27.1. <### Introduction ###> 27.2. <### Pretty Printing Control Variables ###> 27.3. <### Dynamic Control of the Arrangement of Output ###> 27.4. <### Format Directive Interface ###> 27.5. <### Compiling Format Control Strings ###> 27.6. <### Pretty Printing Dispatch Tables ###> 28. <#### Common Lisp Object System ####> 28.1. <### Programmer Interface Concepts ###> 28.1.1. <## Error Terminology ##> 28.1.2. <## Classes ##> 28.1.2.1. <# Defining Classes #> 28.1.2.2. <# Creating Instances of Classes #> 28.1.2.3. <# Slots #> 28.1.2.4. <# Accessing Slots #> 28.1.3. <## Inheritance ##> 28.1.3.1. <# Inheritance of Methods #> 28.1.3.2. <# Inheritance of Slots and Slot Options #> 28.1.3.3. <# Inheritance of Class Options #> 28.1.3.4. <# Examples #> 28.1.4. <## Integrating Types and Classes ##> 28.1.5. <## Determining the Class Precedence List ##> 28.1.5.1. <# Topological Sorting #> 28.1.5.2. <# Examples #> 28.1.6. <## Generic Functions and Methods ##> 28.1.6.1. <# Introduction to Generic Functions #> 28.1.6.2. <# Introduction to Methods #> 28.1.6.3. <# Agreement on Parameter Specializers and Qualifiers #> 28.1.6.4. <# Congruent Lambda-Lists for All Methods of a Generic Function #> 28.1.6.5. <# Keyword Arguments in Generic Functions and Methods #> 28.1.7. <## Method Selection and Combination ##> 28.1.7.1. <# Determining the Effective Method #> 28.1.7.2. <# Standard Method Combination #> 28.1.7.3. <# Declarative Method Combination #> 28.1.7.4. <# Built-in Method Combination Types #> 28.1.8. <## Meta-objects ##> 28.1.8.1. <# Metaclasses #> 28.1.8.2. <# Standard Metaclasses #> 28.1.8.3. <# Standard Meta-objects #> 28.1.9. <## Object Creation and Initialization ##> 28.1.9.1. <# Initialization Arguments #> 28.1.9.2. <# Declaring the Validity of Initialization Arguments #> 28.1.9.3. <# Defaulting of Initialization Arguments #> 28.1.9.4. <# Rules for Initialization Arguments #> 28.1.9.5. <# Shared-Initialize #> 28.1.9.6. <# Initialize-Instance #> 28.1.9.7. <# Definitions of Make-Instance and Initialize-Instance #> 28.1.10. <## Redefining Classes ##> 28.1.10.1. <# Modifying the Structure of Instances #> 28.1.10.2. <# Initializing Newly Added Local Slots #> 28.1.10.3. <# Customizing Class Redefinition #> 28.1.10.4. <# Extensions #> 28.1.11. <## Changing the Class of an Instance ##> 28.1.11.1. <# Modifying the Structure of an Instance #> 28.1.11.2. <# Initializing Newly Added Local Slots #> 28.1.11.3. <# Customizing the Change of Class of an Instance #> 28.1.12. <## Reinitializing an Instance ##> 28.1.12.1. <# Customizing Reinitialization #> 28.2. <### Functions in the Programmer Interface ###> 29. <#### Conditions ####> 29.1. <### Introduction ###> 29.2. <### Changes in Terminology ###> 29.3. <### Survey of Concepts ###> 29.3.1. <## Signaling Errors ##> 29.3.2. <## Trapping Errors ##> 29.3.3. <## Handling Conditions ##> 29.3.4. <## Object-Oriented Basis of Condition Handling ##> 29.3.5. <## Restarts ##> 29.3.6. <## Anonymous Restarts ##> 29.3.7. <## Named Restarts ##> 29.3.8. <## Restart Functions ##> 29.3.9. <## Comparison of Restarts and Catch/Throw ##> 29.3.10. <## Generalized Restarts ##> 29.3.11. <## Interactive Condition Handling ##> 29.3.12. <## Serious Conditions ##> 29.3.13. <## Non-Serious Conditions ##> 29.3.14. <## Condition Types ##> 29.3.15. <## Signaling Conditions ##> 29.3.16. <## Resignaling Conditions ##> 29.3.17. <## Condition Handlers ##> 29.3.18. <## Printing Conditions ##> 29.4. <### Program Interface to the Condition System ###> 29.4.1. <## Signaling Conditions ##> 29.4.2. <## Assertions ##> 29.4.3. <## Exhaustive Case Analysis ##> 29.4.4. <## Handling Conditions ##> 29.4.5. <## Defining Conditions ##> 29.4.6. <## Creating Conditions ##> 29.4.7. <## Establishing Restarts ##> 29.4.8. <## Finding and Manipulating Restarts ##> 29.4.9. <## Warnings ##> 29.4.10. <## Restart Functions ##> 29.4.11. <## Debugging Utilities ##> 29.5. <### Predefined Condition Types ###> Appendix A. <#### Series ####> A.1. <### Introduction ###> A.2. <### Series Functions ###> A.2.1. <## Scanners ##> A.2.2. <## Mapping ##> A.2.3. <## Truncation and Other Simple Transducers ##> A.2.4. <## Conditional and Other Complex Transducers ##> A.2.5. <## Collectors ##> A.2.6. <## Alteration of Series ##> A.3. <### Optimization ###> A.3.1. <## Basic Restrictions ##> A.3.2. <## Constraint Cycles ##> A.3.3. <## Defining New Series Functions ##> A.3.4. <## Declarations ##> A.4. <### Primitives ###> Appendix B. <#### Generators and Gatherers ####> B.1. <### Introduction ###> B.2. <### Generators ###> B.3. <### Gatherers ###> B.4. <### Discussion ###> Appendix C. <#### Backquote ####> <#### References ####> <#### Index of X3J13 Votes ####> =============================================================================== <#### Preface (Second Edition) ####> Common Lisp has succeeded. Since publication of the first edition of this book in 1984, many implementors have used it as a de facto standard for Lisp implementation. As a result, it is now much easier to port large Lisp programs from one implementation to another. Common Lisp has proved to be a useful and stable platform for rapid prototyping and systems delivery in artificial intelligence and other areas. With experience gained in using Common Lisp for so many applications, implementors found no shortage of opportunities for innovation. One of the important characteristics of Lisp is its good support for experimental extension of the language; while Common Lisp has been stable, it has not stagnated. The 1984 definition of Common Lisp was imperfect and incomplete. In some cases this was inadvertent: some odd boundary situation was overlooked and its consequences not specified, or different passages in were conflict, or some property of Lisp was so well-known and traditionally relied upon that I forgot to write it down. In other cases the informal committee that was defining Common Lisp could not settle on a solution, and therefore agreed to leave some important aspect of the language unspecified rather than choose a less than satisfactory definition. An example is error handling; 1984 Common Lisp had plenty of ways to signal errors but no way for a program to trap or process them. Over the next year I collected reports of errors in the book and gaps in the language. In December 1985, a group of implementors and users met in Boston to discuss the state of Common Lisp. I prepared two lists for this meeting, one of errata and clarifications that I thought would be relatively uncontroversial (boy, was I wrong!) and one of more substantial changes I thought should be considered and perhaps voted upon. Others also brought proposals to discuss. It became clear to everyone that there was now enough interest in Common Lisp, and dependence on its stability, that a more formal mechanism was needed for managing changes to the language. This realization led to the formation of X3J13, a subcommittee of ANSI committee X3, to produce a formal American National Standard for Common Lisp. That process is nearing completion. X3J13 has completed the bulk of its technical work in rectifying the 1984 definition and codifying extensions to that definition that have received widespread use and approval. A draft standard is now being prepared; it will probably be available in 1990. There will then be a period (required by ANSI) for public review. X3J13 must then consider the comments it receives and respond appropriately. If the comments result in substantial changes to the draft standard, multiple public review periods may be required before the draft can be approved as an American National Standard. Fortunately, X3J13 has done an outstanding job of documenting its work. For every change that came to a formal vote, a document was prepared that described the problem to be solved and one or more solutions. For each solution there is a detailed proposal for changing the language; a rationale; test cases that distinguish the proposal from the status quo or from other proposals for solving that problem; discussions of current practice, cost to implementors, cost to users, cost of not adopting the proposal, benefits of adoption, aesthetic criteria; and any relevant informal discussion that may have preceded creation of the formal proposal. All of these proposal documents were made available on-line as well as in paper form. By my count, by June 1989 some 186 such proposals were approved as language changes. (This count does not include many proposals that came before the committee but were rejected.) The purpose of this second edition is to bridge the gap between the first edition and the forthcoming ANSI standard for Common Lisp. Because of the requirement for formal public review, it will be some time yet before the ANSI standard is final. This book in no way resembles the forthcoming standard (which is being written independently by Kathy Chapman of Digital Equipment Corporation with assistance from the X3J13 Drafting Subcommittee). I have incorporated into this second edition a great deal of material based on the votes of X3J13, in order to give the reader a picture of where the language is heading. My purpose here is not simply to quote the X3J13 documents verbatim but to paraphrase them and relate them to the structure of the first edition. A single vote by X3J13 may be discussed in many parts of this book, and a single passage of this book may be affected by many of the votes. I wish to be very clear: this book is not an official document of X3J13, though it is based on publicly available material produced by X3J13. In no way does this book constitute a definitive description of the forthcoming ANSI standard. The committee's decisions have been remarkably stable (it has rescinded earlier decisions only two or three times), and I do not expect radical changes in direction. Nevertheless, it is quite probable that the draft standard will be substantively revised in response to editorial review or public comment. I have therefore reported here on the actions of X3J13 not to inscribe them in stone, but to make clear how the language of the first edition is likely to change. I have tried to be careful in my wording to avoid saying "the language has been changed" and to state simply that "X3J13 voted at such- and-so time to make the following change." Until the day when an official ANSI Common Lisp standard emerges, it is likely that the 1984 definition of Common Lisp will continue to be used widely. This book has been designed to be used as a reference both to the 1984 definition and to the language as modified by the actions of X3J13. It contains the entire text of the first edition of "Common Lisp: The Language", with corrections and minor editorial changes; however, more than half of the material in this edition is new. All new material is identified by solid lines in the left margin. Dotted lines in the left margin indicate material from the first edition that applies to the 1984 definition but that has been modified by a vote of X3J13. Modifications to these outmoded passages are explained by preceding or following text (which will have a solid line in the margin). In summary: * To use the 1984 language definition, read all material that does not have a solid line in the margin. * To use the updated language definition, read everything, but be wary of material with a dotted line in the margin. At the end of the book is an index of the X3J13 votes, ordered by the committee's internal code names (included to ease cross-reference to the X3J13 documents, which may be useful during the public review periods). References to this list of votes appear as numbers in angle brackets; thus "<14>" refers to the vote on issue number 14, whereas "[14]" refers to reference 14 in the bibliography. I have kept changes to the wording of the first-edition material to a minimum. Obvious spelling and typographical errors have been corrected, and the entire text has been edited to a uniform style of spelling and punctuation. (Note in particular that the first edition used the spelling "signalling" but this edition, in deference to the style decision of the X3J13 Drafting Subcommittee, uses "signaling.") A few minor changes were made to accommodate typographical or layout constraints. (For example, the word "also" has been deleted from the first sentence of chapter 1, partly to make that paragraph look better and partly to allow a better page break at the bottom of page 2.) In a very few cases the first edition contained substantive errors that I could not in good conscience correct silently; these have been flagged by paragraphs beginning with the phrase "Notice of correction". The chapter and section numbering of this edition matches that of the first edition, with the exception that a new section 7.9 has been interpolated. Four new chapters (26--29) describe substantial changes approved by X3J13: an extended loop macro, a pretty printer interface, the Common Lisp Object System, and the Common Lisp Condition System. X3J13, in the course of its work, formed a subcommittee to study whether additional means of iteration should be standardized for use in Common Lisp, for a great deal of existing practice in this area was not included in the first edition because of lack of agreement in 1984. The X3J13 Iteration Subcommittee produced reports on three possible facilities. One (loop) was approved for inclusion in the forthcoming draft standard and is described in chapter 26. X3J13 expressed interest in the other two approaches (series and generators), but the consensus as of January 1989 was that these other approaches were not yet sufficiently mature or in sufficiently widespread use to warrant inclusion in the draft Common Lisp standard at that time. However, the subcommittee was directed to continue work on these approaches and X3J13 is open to the possibility of standardizing them at a later date. Please note that I do not wish the prejudge the question of whether X3J13 will ever choose to make the other two proposals the subject of standardization. Nevertheless, I have chosen to include them in the second edition, in cooperation with Dr. Richard C. Waters, as appendices A and B, in order to make these ideas available to the Lisp community. In my judgement these proposals address an area of language design not otherwise covered by Common Lisp and are likely to have practical value even if they are never adopted as part of a formal standard. Some new material in this book has nothing to do with the work of X3J13. In many places I have added explanations, clarifications, new examples, warnings, and tips on writing portable code. Appendix C contains a piece of code that may help in understanding the backquote syntax. This second edition, unlike the first edition, also includes a few diagrams to pep up the text. However, there are absolutely no new jokes, and very few outright lies. =============================================================================== <#### Acknowledgments (Second Edition) ####> First and foremost, I must thank the many people in the Lisp community who have worked so hard to specify, implement, and use Common Lisp. Some of these have volunteered many hours of effort as members of ANSI committee X3J13. Others have made presentations or proposals to X3J13, and yet others have sent suggestions and corrections to the first edition directly to me. This book builds on their efforts as well as mine. An early draft of this book was made available to all members of X3J13 for their criticism. I have also worked with the many public documents that have been written during the course of the committee's work (which is not over yet). It is my hope that this book is an accurate reflection of the committee's actions as of October 1989. Nevertheless, any errors or inconsistencies are my responsibility. The fact that I have made a draft available to certain persons, received feedback from them, or thanked them in these acknowledgments does not necessarily imply that any one of them or any of the institutions with which they are affiliated endorse this book or anything of its contents. Digital Press and I gave permission to X3J13 to use any or all parts of the first edition in the production of an ANSI Common Lisp standard. Conversely, in writing this book I have worked with publicly available documents produced by X3J13 in the course of its work, and in some cases as a courtesy have obtained the consent of the authors of those documents to quote them extensively. This common ancestry will result in similarities between this book and the emerging ANSI Common Lisp standard (that is the purpose, after all). Nevertheless, this second edition has no official connection whatsoever with X3J13 or ANSI, nor is it endorsed by either of those institutions. The following persons have been members of X3J13 or involved in its activities at one time or another: Jim Allard, Dave Andre, Jim Antonisse, William Arbaugh, John Aspinall, Bob Balzer, Gerald Barber, Richard Barber, Kim Barrett, David Bartley, Roger Bate, Alan Bawden, Michael Beckerle, Paul Beiser, Eric Benson, Daniel Bobrow, Mary Boelk, Skona Brittain, Gary Brown, Tom Bucken, Robert Buckley, Gary Byers, Dan Carnese, Bob Cassels, Jerome Chailloux, Kathy Chapman, Thomas Christaller, Will Clinger, Peter Coffee, John Cugini, Pavel Curtis, Doug Cutting, Christopher Dabrowski, Jeff Dalton, Linda DeMichiel, Fred Discenzo, Jerry Duggan, Patrick Dussud, Susan Ennis, Scott Fahlman, Jogn Fitch, John Foderaro, Richard Gabriel, Steven Gadol, Nick Gall, Oscar Garcia, Robert Giansiracusa, Brad Goldstein, David Gray, Richard Greenblatt, George Hadden, Steve Haflich, Dave Henderson, Carl Hewitt, Carl Hoffman, Cheng Hu, Masayuki Ida, Takayasu Ito, Sonya Keene, James Kempf, Gregory Jennings, Robert Kerns, Gregor Kiczales, Kerry Kimbrough, Dieter Kolb, Timothy Koschmann, Ed Krall, Fritz Kunze, Aaron Larson, Joachim Laubsch, Kevin Layer, Michael Levin, Ray Lim, Thom Linden, David Loeffler, Sandra Loosemore, Barry Margolin, Larry Masinter, David Matthews, Robert Mathis, John McCarthy, Chris McConnell, Rob McLachlan, Jay Mendelsohn, Martin Mikelsons, Tracey Miles, Richard Mlyarnik, David Moon, Jarl Nilsson, Leo Noordhulsen, Ronald Ohlander, Julian Padget, Jeff Peck, Jan Pedersen, Bob Pellegrino, Crispin Perdue, Dan Pierson, Kent Pitman, Dexter Pratt, Christian Quiennec, B. Raghavan, Douglas Rand, Jonathan Rees, Chris Richardson, Jeff Rininger, Walter van Roggen, Jeffrey Rosenking, Don Sakahara, William Scherlis, David Slater, James Smith, Alan Snyder, Angela Sodan, Richard Soley, S. Sridhar, Bill St. Clair, Philip Stanhope, Guy Steele, Herbert Stoyan, Hiroshi Torii, Dave Touretzky, Paul Tucker, Rick Tucker, Thomas Turba, David Unietis, Mary Van Deusen, Ellen Waldrum, Richard Waters, Allen Wechsler, Mark Wegman, Jon L White, Skef Wholey, Alexis Wieland, Martin Yonke, Bill York, Taiichi Yuasa, Gail Zacharias, and Jan Zubkoff. I must express particular gratitude and appreciation to a number of people for their exceptional efforts: Larry Masinter, chairman of the X3J13 Cleanup Subcommittee, developed the standard format for documenting all proposals to be voted upon. The result has been an outstanding technical and historical record of all the actions taken by X3J13 to rectify and improve Common Lisp. Sandra Loosemore, chairwoman of the X3J13 Compiler Subcommittee, produced many proposals for clarifying the semantics of the compilation process. She has been a diligent stickler for detail and has helped to clarify many parts of Common Lisp left vague in the first edition. Jon L White, chairman of the X3J13 Iteration Subcommittee, supervised the consideration of several controversial proposals, one of which (loop) was eventually adopted by X3J13. Thom Linden, chairman of the X3J13 Character Subcommittee, led a team in grappling with the difficult problem of accommodating various character sets in Common Lisp. One result is that Common Lisp will be more attractive for international use. Kent Pitman, chairman of the X3J13 Error Handling Subcommittee, plugged the biggest outstanding hole in Common Lisp as described by the first edition. Kathy Chapman, chairwoman of the X3J13 Drafting Subcommittee, and principal author of the draft standard, has not only written a great deal of text but also insisted on coherent and consistent terminology and pushed the rest of the committee forward when necessary. Robert Mathis, chairman of X3J13, has kept administrative matters flowing smoothly during technical controversies. Mary Van Deusen, secretary of X3J13, kept excellent minutes that were a tremendous aid to me in tracing the history of a number of complex discussions. Jan Zubkoff, X3J13 meeting and mailing organizer, knows what's going on, as always. She is a master of organization and of physical arrangements. Moreover, she once again pulled me out of the fire at the last minute. Dick Gabriel, international representative for X3J13, has kept information flowing smoothly between Europe, Japan, and the United States. He provided a great deal of the energy and drive for the completion of the Common Lisp Object System specification. He has also provided me with a great deal of valuable advice and has been on call for last-minute consultation at all hours during the final stages of preparation for this book. David Moon has consistently been a source of reason, expert knowledge, and careful scrutiny. He has read the first edition and the X3J13 proposals perhaps more carefully than anyone else. David Moon, Jon L White, Gregor Kiczales, Robert Mathis, Mary Boelk provided extensive feedback on an early draft of this book. I thank them as well as the many others who commented in one way or another on the draft. I wish to thank the authors of large proposals to X3J13 that have made material available for more or less wholesale inclusion in this book as distinct chapters. This material was produced primarily for the use of X3J13 in its work. It has been included here on a non-exclusive basis with the consent of the authors. The author of the chapter on loop (Jon L White) notes that the chapter is based on documentation written at Lucid, Inc., by Molly M. Miller, Sonia Orin Lyris, and Kris Dinkel. Glenn Burke, Scott Fahlman, Colin Meldrum, David Moon, Cris Perdue, and Dick Waters contributed to the design of the loop macro. The authors of the Common Lisp Object System specification (Daniel G. Bobrow, Linda G. DeMichiel, Richard P. Gabriel, Sonya E. Keene, Gregor Kiczales, and David A. Moon) wish to thank Patrick Dussud, Kenneth Kahn, Jim Kempf, Larry Masinter, Mark Stefik, Daniel L. Weinreb, and Jon L White for their contributions. The author of the chapter on Conditions (Kent M. Pitman) notes that there is a paper [38] containing background information about the design of the condition system, which is based on the condition system of the Symbolics Lisp Machines [49]. The members of the X3J13 Error Handling Subcommittee were Andy Daniels and Kent Pitman. Richard Mlynarik and David A. Moon made major design contributions. Useful comments, questions, suggestions, and criticisms were provided by Paul Anagnostopoulos, Alan Bawden, William Chiles, Pavel Curtis, Mary Fontana, Dick Gabriel, Dick King, Susan Lander, David D. Loeffler, Ken Olum, David C. Plummer, Alan Snyder, Eric Weaver, and Daniel L. Weinreb. The Condition System was designed specifically to accommodate the needs of Common Lisp. The design is, however, most directly based on the "New Error System" (NES) developed at Symbolics by David L. Andre, Bernard S. Greenberg, Mike McMahon, David A. Moon, and Daniel L. Weinreb. The NES was in turn based on experiences with the original Lisp Machine error system (developed at MIT), which was found to be inadequate for the needs of the modern Lisp Machine environments. Many aspects of the NES were inspired by the (PL/I) condition system used by the Honeywell Multics operating system. Henry Lieberman provided conceptual guidance and encouragement in the design of the NES. A reimplementation of the NES for non-Symbolics Lisp Machine dialects (MIT, LMI, and TI) was done at MIT by Richard M. Stallman. During the process of that reimplementation, some conceptual changes were made which have significantly influenced the Common Lisp Condition System. As for the smaller but no less important proposals, Larry Masinter deserves recognition as an author of over half of them. He has worked indefatigably to write up proposals and to polish drafts by other authors. Kent Pitman, David Moon, and Sandra Loosemore have also been notably prolific, as well as Jon L White, Dan Pierson, Walter van Roggen, Skona Brittain, Scott Fahlman, and myself. Other authors of proposals include David Andre, John Aspinall, Kim Barrett, Eric Benson, Daniel Bobrow, Bob Cassels, Kathy Chapman, WIlliam Clinger, Pavel Curtis, Doug Cutting, Jeff Dalton, Linda DiMichiel, Richard Gabriel, Steven Haflich, Sonya Keene, James Kempf, Gregor Kiczales, Dieter Kolb, Barry Margolin, Chris McConnell, Jeff Peck, Jan Pedersen, Crispin Perdue, Jonathan Rees, Don Sakahara, David Touretzky, Richard Waters, and Gail Zacharias. I am grateful to Donald E. Knuth and his colleagues for producing the TeX text formatting system [28], which was used to produce and typeset the manuscript. Knuth did an especially good job of publishing the program for TeX [29]; I had to consult the code about eight times while debugging particularly complicated macros. Thanks to the extensive indexing and cross- references, in each case it took me less than five minutes to find the relevant fragment of that 500-page program. I also owe a debt to Leslie Lamport, author of the LaTeX macro package [30] for TeX, within which I implemented the document style for this book. Blue Sky Research sells and supports Textures, an implementation of TeX for Apple Macintosh computers; Gayla Groom and Barry Smith of Blue Sky Research provided excellent technical support when I needed it. Other software tools that were invaluable in preparing this book were QuicKeys (sold by CE Software, Inc.), which provides keyboard macros; Gofer (sold by Microlytics, Inc.), which performs rapid text searches in multiple files; Symantec Utilities for Macintosh (sold by Symantec Corporation), which saved me from more than one disk crash; and the PostScript language and compatible fonts (sold by Adobe Systems Incorporated). Some of this software (such as LaTeX) I obtained for free and some I bought, but all have proved to be useful tools of excellent quality. I am grateful to these developers for creating them. Electronic mail has been indispensible to the writing of this book, as well to as the work of X3J13. (It is a humbling experience to publish a book and then for the next five years to receive at least one electronic mail message a week, if not twenty, pointing out some mistake or defect.) Kudos to those develop and maintain the Internet, which arose from the Arpanet and other networks. Chase Duffy, George Horesta, and Will Buddenhagen of Digital Press have given me much encouragement and support. David Ford designed the book and provided specifications that I could code into TeX. Alice Cheyer and Kate Schmit edited the copy for style and puzzled over the more obscure jokes with great patience. Marilyn Rowland created the index; Tim Evans and I did some polishing. Laura Fillmore and her colleagues at Editorial, Inc., have tirelessly and meticulously checked one draft after another and has kept the paperwork flowing smoothly during the last hectic weeks of proofreading, page makeup, and typesetting. Thinking Machines Corporation has supported all my work with X3J13. I thank all my colleagues there for their encouragement and help. Others who provided indispensible encouragement and support include Guy and Nalora Steele; David Steele; Cordon and Ruth Kerns; David, Patricia, Tavis, Jacob, Nicholas, and Daniel Auwerda; Donald and Denise Kerns; and David, Joyce, and Christine Kerns. Most of the writing of this book took place between 10 P.M. and 3 A.M. (I'm not as young as I used to be). I am grateful to Barbara, Julia, Peter, and Matthew for putting up with it, and for their love. Guy L. Steele Jr. Lexington, Massachusetts All Saints' Day, 1989 =============================================================================== <#### Acknowledgments (First Edition) ####> Common Lisp was designed by a diverse group of people affiliated with many institutions. Contributors to the design and implementation of Common Lisp and to the polishing of this book are hereby gratefully acknowledged: Paul Anagnostopoulos Digital Equipment Corporation Dan Aronson Carnegie-Mellon University Alan Bawden Massachusetts Institute of Technology Eric Benson University of Utah, Stanford University, and Symbolics, Incorporated Jon Bentley Carnegie-Mellon University and Bell Laboratories Jerry Boetje Digital Equipment Corporation Gary Brooks Texas Instruments Rodney A. Brooks Stanford University Gary L. Brown Digital Equipment Corporation Richard L. Bryan Symbolics, Incorporated Glenn S. Burke Massachusetts Institute of Technology Howard I. Cannon Symbolics, Incorporated George J. Carrette Massachusetts Institute of Technology Robert Cassels Symbolics, Incorporated Monica Cellio Carnegie-Mellon University David Dill Carnegie-Mellon University Scott E. Fahlman Carnegie-Mellon University Richard J. Fateman University of California, Berkeley Neal Feinberg Carnegie-Mellon University Ron Fischer Rutgers University John Foderaro University of California, Berkeley Steve Ford Texas Instruments Richard P. Gabriel Stanford University and Lawrence Livermore National Laboratory Joseph Ginder Carnegie-Mellon University and Perq Systems Corp. Bernard S. Greenberg Symbolics, Incorporated Richard Greenblatt Lisp Machines Incorporated (LMI) Martin L. Griss University of Utah and Hewlett-Packard Incorporated Steven Handerson Carnegie-Mellon University Charles L. Hedrick Rutgers University Gail Kaiser Carnegie-Mellon University Earl A. Killian Lawrence Livermore National Laboratory Steve Krueger Texas Instruments John L. Kulp Symbolics, Incorporated Jim Large Carnegie-Mellon University Rob Maclachlan Carnegie-Mellon University William Maddox Carnegie-Mellon University Larry M. Masinter Xerox Corporation, Palo Alto Research Center John McCarthy Stanford University Michael E. McMahon Symbolics, Incorporated Brian Milnes Carnegie-Mellon University David A. Moon Symbolics, Incorporated Beryl Morrison Digital Equipment Corporation Don Morrison University of Utah Dan Pierson Digital Equipment Corporation Kent M. Pitman Massachusetts Institute of Technology Jonathan Rees Yale University Walter van Roggen Digital Equipment Corporation Susan Rosenbaum Texas Instruments William L. Scherlis Carnegie-Mellon University Lee Schumacher Carnegie-Mellon University Richard M. Stallman Massachusetts Institute of Technology Barbara K. Steele Carnegie-Mellon University Guy L. Steele Jr. Carnegie-Mellon University and Tartan Laboratories Incorporated Peter Szolovits Massachusetts Institute of Technology William vanMelle Xerox Corporation, Palo Alto Research Center Ellen Waldrum Texas Instruments Allan C. Wechsler Symbolics, Incorporated Daniel L. Weinreb Symbolics, Incorporated Jon L White Xerox Corporation, Palo Alto Research Center Skef Wholey Carnegie-Mellon University Richard Zippel Massachusetts Institute of Technology Leonard Zubkoff Carnegie-Mellon University and Tartan Laboratories Incorporated Some contributions were relatively small; others involved enormous expenditures of effort and great dedication. A few of the contributors served more as worthy adversaries than as benefactors (and do not necessarily endorse the final design reported here), but their pointed criticisms were just as important to the polishing of Common Lisp as all the positively phrased suggestions. All of the people named above were helpful in one way or another, and I am grateful for the interest and spirit of cooperation that allowed most decisions to be made by consensus after due discussion. Considerable encouragement and moral support were also provided by: Norma Abel Digital Equipment Corporation Roger Bate Texas Instruments Harvey Cragon Texas Instruments Dennis Duncan Digital Equipment Corporation Sam Fuller Digital Equipment Corporation A. Nico Habermann Carnegie-Mellon University Berthold K. P. Horn Massachusetts Institute of Technology Gene Kromer Texas Instruments Gene Matthews Texas Instruments Allan Newell Carnegie-Mellon University Dana Scott Carnegie-Mellon University Harry Tennant Texas Instruments Patrick H. Winston Massachusetts Institute of Technology Lowell Wood Lawrence Livermore National Laboratory William A. Wulf Carnegie-Mellon University and Tartan Laboratories Incorporated I am very grateful to each of them. Jan Zubkoff of Carnegie-Mellon University provided a great deal of organization, secretarial support, and unfailing good cheer in the face of adversity. The development of Common Lisp would most probably not have been possible without the electronic message system provided by the ARPANET. Design decisions were made on several hundred distinct points, for the most part by consensus, and by simple majority vote when necessary. Except for two one-day face-to-face meetings, all of the language design and discussion was done through the ARPANET message system, which permitted effortless dissemination of messages to dozens of people, and several interchanges per day. The message system also provided automatic archiving of the entire discussion, which has proved invaluable in the preparation of this reference manual. Over the course of thirty months, approximately 3000 messages were sent (an average of three per day), ranging in length from one line to twenty pages. Assuming 5000 characters per printed page of text, the entire discussion totaled about 1100 pages. It would have been substantially more difficult to have conducted this discussion by any other means, and would have required much more time. The ideas in Common Lisp have come from many sources and been polished by much discussion. I am responsible for the form of this book, and for any errors or inconsistencies that may remain; but the credit for the design and support of Common Lisp lies with the individuals named above, each of whom has made significant contributions. The organization and content of this book were inspired in large part by the "MacLISP Reference Manual" by David A. Moon and others [33], and by the "LISP Machine Manual" (fourth edition) by Daniel Weinreb and David Moon [55], which in turn acknowledges the efforts of Richard Stallman, Mike McMahon, Alan Bawden, Glenn Burke, and "many people too numerous to list." I thank Phyllis Keenan, Chase Duffy, Virginia Anderson, John Osborn, and Jonathan Baker of Digital Press for their help in preparing this book for publication. Jane Blake did an admirable job of copy-editing. James Gibson and Katherine Downs of Waldman Graphics were most cooperative in typesetting this book from my on-line manuscript files. I am grateful to Carnegie-Mellon University and to Tartan Laboratories Incorporated for supporting me in the writing of this book over the last three years. Part of the work on this book was done in conjunction with the Carnegie- Mellon University Spice Project, an effort to construct an advanced scientific software development environment for personal computers. The Spice Project is supported by the Defense Advanced Research Projects Agency, Department of Defense, ARPA Order 3597, monitored by the Air Force Avionics Laboratory under contract F33615-78-C-1551. The views and conclusions contained in this book are those of the author and should not be interpreted as representing the official policies, either expressed or implied, of the Defense Advanced Research Projects Agency or the U.S. Government. Most of the writing of this book took place between midnight and 5 A.M. I am grateful to Barbara, Julia, and Peter for putting up with it, and for their love. Guy L. Steele Jr. Pittsburgh, Pennsylvania March 1984 =============================================================================== 1. <#### Introduction ####> Common Lisp is a new dialect of Lisp, a successor to MacLisp [33,37], influenced strongly by Zetalisp [55,34] and to some extent by Scheme [46] and Interlisp [50]. ------------------------------------------------------------------------------- 1.1. <### Purpose ###> Common Lisp is intended to meet these goals: __Commonality__ Common Lisp originated in an attempt to focus the work of several implementation groups, each of which was constructing successor implementations of MacLisp for different computers. These implementations had begun to diverge because of the differences in the implementation environments: microcoded personal computers (Zetalisp, Spice Lisp), commercial timeshared computers (NIL--the "New Implementation of Lisp"), and supercomputers (S-1 Lisp). While the differences among the several implementation environments of necessity will continue to force certain incompatibilities among the implementations, Common Lisp serves as a common dialect to which each implementation makes any necessary extensions. __Portability__ Common Lisp intentionally excludes features that cannot be implemented easily on a broad class of machines. On the one hand, features that are difficult or expensive to implement on hardware without special microcode are avoided or provided in a more abstract and efficiently implementable form. (Examples of this are the invisible forwarding pointers and locatives of Zetalisp. Some of the problems that they solve are addressed in different ways in Common Lisp.) On the other hand, features that are useful only on certain "ordinary" or "commercial" processors are avoided or made optional. (An example of this is the type declaration facility, which is useful in some implementations and completely ignored in others. Type declarations are completely optional and for correct programs affect only efficiency, not semantics.) Common Lisp is designed to make it easy to write programs that depend as little as possible on machine-specific characteristics, such as word length, while allowing some variety of implementation techniques. __Consistency__ Most Lisp implementations are internally inconsistent in that by default the interpreter and compiler may assign different semantics to correct programs. This semantic difference stems primarily from the fact that the interpreter assumes all variables to be dynamically scoped, whereas the compiler assumes all variables to be local unless explicitly directed otherwise. This difference has been the usual practice in Lisp for the sake of convenience and efficiency but can lead to very subtle bugs. The definition of Common Lisp avoids such anomalies by explicitly requiring the interpreter and compiler to impose identical semantics on correct programs so far as possible. __Expressiveness__ Common Lisp culls what experience has shown to be the most useful and understandable constructs from not only MacLisp but also Interlisp, other Lisp dialects, and other programming languages. Constructs judged to be awkward or less useful have been excluded. (An example is the store construct of MacLisp.) __Compatibility__ Unless there is a good reason to the contrary, Common Lisp strives to be compatible with Lisp Machine Lisp, MacLisp, and Interlisp, roughly in that order. __Efficiency__ Common Lisp has a number of features designed to facilitate the production of high-quality compiled code in those implementations whose developers care to invest effort in an optimizing compiler. One implementation of Common Lisp, namely S-1 Lisp, already has a compiler that produces code for numerical computations that is competitive in execution speed to that produced by a Fortran compiler [11]. The S-1 Lisp compiler extends the work done in MacLisp to produce extremely efficient numerical code [19]. __Power__ Common Lisp is a descendant of MacLisp, which has traditionally placed emphasis on providing system-building tools. Such tools may in turn be used to build the user-level packages such as Interlisp provides; these packages are not, however, part of the Common Lisp core specification. It is expected such packages will be built on top of the Common Lisp core. __Stability__ It is intended that Common Lisp will change only slowly and with due deliberation. The various dialects that are supersets of Common Lisp may serve as laboratories within which to test language extensions, but such extensions will be added to Common Lisp only after careful examination and experimentation. The goals of Common Lisp are thus very close to those of Standard Lisp [51] and Portable Standard Lisp [51]. Common Lisp differs from Standard Lisp primarily in incorporating more features, including a richer and more complicated set of data types and more complex control structures. This book is intended to be a language specification rather than an implementation specification (although implementation notes are scattered throughout the text). It defines a set of standard language concepts and constructs that may be used for communication of data structures and algorithms in the Common Lisp dialect. This set of concepts and constructs is sometimes referred to as the "core Common Lisp language" because it contains conceptually necessary or important features. It is not necessarily implementationally minimal. While many features could be defined in terms of others by writing Lisp code, and indeed may be implemented that way, it was felt that these features should be conceptually primitive so that there might be agreement among all users as to their usage. (For example, bignums and rational numbers could be implemented as Lisp code given operations on fixnums. However, it is important to the conceptual integrity of the language that they be regarded by the user as primitive, and they are useful enough to warrant a standard definition.) For the most part, this book defines a programming language, not a programming environment. A few interfaces are defined for invoking such standard programming tools as a compiler, an editor, a program trace facility, and a debugger, but very little is said about their nature or operation. It is expected that one or more extensive programming environments will be built using Common Lisp as a foundation, and will be documented separately. There are now many implementations of Common Lisp, some programmed by | research groups in universities and some by companies that sell them | commercially, and a number of useful programming environments have indeed grown| up around these implementations. What is more, all the goals stated above have| been achieved, most notably that of portability. Moving large bodies of Lisp | code from one computer to another is now routine. | ------------------------------------------------------------------------------- 1.2. <### Notational Conventions ###> A number of special notational conventions are used throughout this book for the sake of conciseness. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1.2.1. <## Decimal Numbers ##> All numbers in this book are in decimal notation unless there is an explicit indication to the contrary. (Decimal notation is normally taken for granted, of course. Unfortunately, for certain other dialects of Lisp, MacLisp in particular, the default notation for numbers is octal (base 8) rather than decimal, and so the use of decimal notation for describing Common Lisp is, taken in its historical context, a bit unusual!) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1.2.2. <## Nil, False, and the Empty List ##> In Common Lisp, as in most Lisp dialects, the symbol nil is used to represent both the empty list and the "false" value for Boolean tests. An empty list may, of course, also be written (); this normally denotes the same object as nil. (It is possible, by extremely perverse manipulation of the package system, to cause the sequence of letters nil to be recognized not as the symbol that represents the empty list but as another symbol with the same name. This obscure possibility will be ignored in this book.) These two notations may be used interchangeably as far as the Lisp system is concerned. However, as a matter of style, this book uses the notation "()" when it is desirable to emphasize the use of an empty list, and uses the notation "nil" when it is desirable to emphasize the use of the Boolean "false". The notation 'nil (note the explicit quotation mark) is used to emphasize the use of a symbol. For example: (defun three () 3) ;Emphasize empty parameter list (append '() '()) ==> () ;Emphasize use of empty lists (not nil) ==> t ;Emphasize use as Boolean "false" (get 'nil 'color) ;Emphasize use as a symbol Any data object other than nil is construed to be Boolean "not false", that is, "true". The symbol t is conventionally used to mean "true" when no other value is more appropriate. When a function is said to "return false" or to "be false" in some circumstance, this means that it returns nil. However, when a function is said to "return true" or to "be true" in some circumstance, this means that it returns some value other than nil, but not necessarily t. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1.2.3. <## Evaluation, Expansion, and Equivalence ##> Execution of code in Lisp is called evaluation because executing a piece of code normally results in a data object called the "value" produced by the code. The symbol "==>" is used in examples to indicate evaluation. For example, (+ 4 5) ==> 9 means "the result of evaluating the code (+ 4 5) is (or would be, or would have been) 9." The symbol --> is used in examples to indicate macro expansion. For example, (push x v) --> (setf v (cons x v)) means "the result of expanding the macro-call form (push x v) is (setf v (cons x v))." This implies that the two pieces of code do the same thing; the second piece of code is the definition of what the first does. The symbol == is used in examples to indicate code equivalence. For example, (gcd x (gcd y z)) == (gcd (gcd x y) z) means "the value and effects of evaluating the form (gcd x (gcd y z)) are always the same as the value and effects of (gcd (gcd x y) z) for any values of the variables x, y, and z." This implies that the two pieces of code do the same thing; however, neither directly defines the other in the way macro expansion does. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1.2.4. <## Errors ##> When this book specifies that it "is an error" for some situation to occur, this means that: * No valid Common Lisp program should cause this situation to occur. * If this situation occurs, the effects and results are completely undefined as far as adherence to the Common Lisp specification is concerned. * No Common Lisp implementation is required to detect such an error. Of course, implementors are encouraged to provide for detection of such errors wherever reasonable. This is not to say that some particular implementation might not define the effects and results for such a situation; the point is that no program conforming to the Common Lisp specification may correctly depend on such effects or results. On the other hand, if it is specified in this book that in some situation "an error is signaled," this means that: * If this situation occurs, an error will be signaled (see error and cerror). * Valid Common Lisp programs may rely on the fact that an error will be signaled. * Every Common Lisp implementation is required to detect such an error. In places where it is stated that so-and-so "must" or "must not" or "may not" be the case, then it "is an error" if the stated requirement is not met. For example, if an argument "must be a symbol," then it "is an error" if the argument is not a symbol. In all cases where an error is to be signaled, the word "signaled" is always used explicitly in this book. X3J13 has adopted a more elaborate terminology for errors, and has made some | effort to specify the type of error to be signaled in situations where | signaling is appropriate. This effort was not complete as of September 1989, | and I have made little attempt to incorporate the new error terminology or | error type specifications in this book. However, the new terminology is | described and used in the specification of the Common Lisp Object System | appearing in chapter 28; this gives the flavor of how erroneous situations will| be described, and appropriate actions prescribed, in the forthcoming ANSI | Common Lisp standard. | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1.2.5. <## Descriptions of Functions and Other Entities ##> Functions, variables, named constants, special forms, and macros are described using a distinctive typographical format. Table 1-1 illustrates the manner in which Common Lisp functions are documented. The first line specifies the name of the function, the manner in which it accepts arguments, and the fact that it is a function. If the function takes many arguments, then the names of the arguments may spill across two or three lines. The paragraphs following this standard header explain the definition and uses of the function and often present examples or related functions. Sometimes two or more related functions are explained in a single combined description. In this situation the headers for all the functions appear together, followed by the combined description. In general, actual code (including actual names of functions) appears in this typeface: (cons a b). Names that stand for pieces of code (metavariables) are written in italics. In a function description, the names of the parameters appear in italics for expository purposes. The word &optional in the list of parameters indicates that all arguments past that point are optional; the default values for the parameters are described in the text. Parameter lists may also contain &rest, indicating that an indefinite number of arguments may appear, or &key, indicating that keyword arguments are accepted. (The &optional &rest &key syntax is actually used in Common Lisp function definitions for these purposes.) ............................................................................... Table 1-1: Sample Function Description ---------<<>> sample-function sample-function arg1 arg2 &optional arg3 arg4 The function sample-function adds together arg1 and arg2, and then multiplies the result by arg3. If arg3 is not provided or is nil, the multiplication isn't done. sample-function then returns a list whose first element is this result and whose second element is arg4 (which defaults to the symbol foo). For example: (sample-function 3 4) ==> (7 foo) (sample-function 1 2 2 'bar) ==> (6 bar) In general, (sample-function x y) == (list (+ x y) 'foo). ............................................................................... Table 1-2: Sample Variable Description ---------<<>> *sample-variable* *sample-variable* The variable *sample-variable* specifies how many times the special form sample-special-form should iterate. The value should always be a non-negative integer or nil (which means iterate indefinitely many times). The initial value is 0 (meaning no iterations). ............................................................................... Table 1-3: Sample Constant Description ---------<<>> sample-constant sample-constant The named constant sample-constant has as its value the height of the terminal screen in furlongs times the base-2 logarithm of the implementation's total disk capacity in bytes, as a floating-point number. ............................................................................... Table 1-2 illustrates the manner in which a global variable is documented. The first line specifies the name of the variable and the fact that it is a variable. Purely as a matter of convention, all global variables used by Common Lisp have names beginning and ending with an asterisk. Table 1-3 illustrates the manner in which a named constant is documented. The first line specifies the name of the constant and the fact that it is a constant. (A constant is just like a global variable, except that it is an error ever to alter its value or to bind it to a new value.) ............................................................................... Table 1-4: Sample Special Form Description ---------<<>> sample-special-form sample-special-form [name] ({var}*) {form}+ This evaluates each form in sequence as an implicit progn, and does this as many times as specified by the global variable *sample-variable*. Each variable var is bound and initialized to 43 before the first iteration, and unbound after the last iteration. The name name, if supplied, may be used in a return-from form to exit from the loop prematurely. If the loop ends normally, sample-special-form returns nil. For example: (setq *sample-variable* 3) (sample-special-form () form1 form2) This evaluates form1, form2, form1, form2, form1, form2 in that order. ............................................................................... Table 1-5: Sample Macro Description ---------<<>> sample-macro sample-macro var [[declaration* | doc-string]] {tag | statement}* This evaluates the statements as a prog body, with the variable var bound to 43. (sample-macro x (return (+ x x))) ==> 86 (sample-macro var . body) --> (prog ((var 43)) . body) ............................................................................... Tables 1-4 and 1-5 illustrate the documentation of special forms and macros, which are closely related in purpose. These are very different from functions. Functions are called according to a single, specific, consistent syntax; the &optional/&rest/&key syntax specifies how the function uses its arguments internally but does not affect the syntax of a call. In contrast, each special form or macro can have its own idiosyncratic syntax. It is by special forms and macros that the syntax of Common Lisp is defined and extended. In the description of a special form or macro, an italicized word names a corresponding part of the form that invokes the special form or macro. Parentheses stand for themselves and should be written as such when invoking the special form or macro. Brackets, braces, stars, plus signs, and vertical bars are metasyntactic marks. Brackets, [ and ], indicate that what they enclose is optional (may appear zero times or one time in that place); the square brackets should not be written in code. Braces, { and }, simply parenthesize what they enclose but may be followed by a star, *, or a plus sign, +; a star indicates that what the braces enclose may appear any number of times (including zero, that is, not at all), whereas a plus sign indicates that what the braces enclose may appear any non-zero number of times (that is, must appear at least once). Within braces or brackets, a vertical bar, |, separates mutually exclusive choices. In summary, the notation {x}* means zero or more occurrences of x, the notation {x}+ means one or more occurrences of x, and the notation [x] means zero or one occurrence of x. These notations are also used for syntactic descriptions expressed as BNF-like productions, as in table 22-2. Double brackets, [[ and ]], indicate that any number of the alternatives | enclosed may be used, and those used may occur in any order, but each | alternative may be used at most once unless followed by a star. For example, | p [[ x | {y}* | z ]] q | means that at most one x, any number of y's, and at most one z may appear | between the mandatory occurrences of p and q, and those that appear may be in | any order. | | A downward arrow, /, indicates a form of syntactic indirection that helps to | make [[ ]] notation more readable. If X is some non-terminal symbol occurring | on the left-hand side of some BNF production, then the right-hand side of that | production is to be textually substituted for any occurrence of X/. Thus the | two fragments | p [[ xyz-mixture/ ]] q | xyz-mixture ::= x | {y}* | z | are together equivalent to the previous example. | In the last example in table 1-5, notice the use of dot notation. The dot appearing in the expression (sample-macro var . body) means that the name body stands for a list of forms, not just a single form, at the end of a list. This notation is often used in examples. In the heading line in table 1-5, notice the use of [[ ]] notation to | indicate that any number of declarations may appear but at most one | documentation string (which may appear before, after, or somewhere in the | middle of any declarations). | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1.2.6. <## The Lisp Reader ##> The term "Lisp reader" refers not to you, the reader of this book, nor to some person reading Lisp code, but specifically to a Lisp procedure, namely the function read, which reads characters from an input stream and interprets them by parsing as representations of Lisp objects. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1.2.7. <## Overview of Syntax ##> Certain characters are used in special ways in the syntax of Common Lisp. The complete syntax is explained in detail in chapter 22, but a quick summary here may be useful: " ( " A left parenthesis begins a list of items. The list may contain any number of items, including zero. Lists may be nested. For example, (cons (car x) (cdr y)) is a list of three things, of which the last two are themselves lists. " ) " A right parenthesis ends a list of items. " ' " An acute accent (also called single quote or apostrophe) followed by an expression form is an abbreviation for (quote form). Thus 'foo means (quote foo) and '(cons 'a 'b) means (quote (cons (quote a) (quote b))). " ; " Semicolon is the comment character. It and all characters up to the end of the line are discarded. " " " Double quotes surround character strings: "This is a thirty-nine-character string." " \ " Backslash is an escape character. It causes the next character to be treated as a letter rather than for its usual syntactic purpose. For example, A\(B denotes a symbol whose name consists of the three characters A, (, and B. Similarly, "\"" denotes a character string containing one character, a double quote, because the first and third double quotes serve to delimit the string, and the second double quote serves as the contents of the string. The backslash causes the second double quote to be taken literally and prevents it from being interpreted as the terminating delimiter of the string. " | " Vertical bars are used in pairs to surround the name (or part of the name) of a symbol that has many special characters in it. It is roughly equivalent to putting a backslash in front of every character so surrounded. For example, |A(B)|, A|(|B|)|, and A\(B\) all mean the symbol whose name consists of the four characters A, (, B, ). " # " The number sign signals the beginning of a complicated syntactic structure. The next character designates the precise syntax to follow. For example, #o105 means 105[8] (105 in octal notation); #x105 means 105[16] (105 in hexadecimal notation); #b1011 means 1011[2] (1011 in binary notation); #\L denotes a character object for the character L; and #(a b c) denotes a vector of three elements a, b, and c. A particularly important case is that #'fn means (function fn), in a manner analogous to 'form meaning (quote form). " ` " Grave accent ("backquote") signals that the next expression is a template that may contain commas. The backquote syntax represents a program that will construct a data structure according to the template. " , " Commas are used within the backquote syntax. " : " Colon is used to indicate which package a symbol belongs to. For example, network:reset denotes the symbol named reset in the package named network. A leading colon indicates a keyword, a symbol that always evaluates to itself. The colon character is not actually part of the print name of the symbol. This is all explained in chapter 11; until you read that, just keep in mind that a symbol notated with a leading colon is in effect a constant that evaluates to itself. __Notice of correction.__ | In the first edition, the characters "," and ":" at the left margin above | were inadvertently omitted. | Brackets, braces, question mark, and exclamation point (that is, [, ], {, }, ?, and !) are not used for any purpose in standard Common Lisp syntax. These characters are explicitly reserved to the user, primarily for use as macro characters for user-defined lexical syntax extensions (see section 22.3). All code in this book is written using lowercase letters. Common Lisp is : generally insensitive to the case in which code is written. Internally, names : of symbols are ordinarily converted to and stored in uppercase form. There are: ways to force case conversion on output if desired; see *print-case*. In this : book, wherever an interactive exchange between a user and the Lisp system is : shown, the input is exhibited with lowercase letters and the output with : uppercase letters. X3J13 voted in June 1989 <150> to introduce readtable-case. Certain settings| allow the names of symbols to be case-sensitive. The default behavior, | however, is as described in the previous paragraph. In any event, only | uppercase letters appear in the internal print names of symbols naming the | standard Common Lisp facilities described in this book. =============================================================================== 2. <#### Data Types ####> Common Lisp provides a variety of types of data objects. It is important to note that in Lisp it is data objects that are typed, not variables. Any variable can have any Lisp object as its value. (It is possible to make an explicit declaration that a variable will in fact take on one of only a limited set of values. However, such a declaration may always be omitted, and the program will still run correctly. Such a declaration merely constitutes advice from the user that may be useful in gaining efficiency. See declare.) In Common Lisp, a data type is a (possibly infinite) set of Lisp objects. Many Lisp objects belong to more than one such set, and so it doesn't always make sense to ask what is the type of an object; instead, one usually asks only whether an object belongs to a given type. The predicate typep may be used to ask whether an object belongs to a given type, and the function type-of returns a type to which a given object belongs. The data types defined in Common Lisp are arranged into a hierarchy (actually a partial order) defined by the subset relationship. Certain sets of objects, such as the set of numbers or the set of strings, are interesting enough to deserve labels. Symbols are used for most such labels (here, and throughout this book, the word "symbol" refers to atomic symbols, one kind of Lisp object, elsewhere known as literal atoms). See chapter 4 for a complete description of type specifiers. The set of all objects is specified by the symbol t. The empty data type, which contains no objects, is denoted by nil. A type called common encompasses all the data objects required by the Common : Lisp language. A Common Lisp implementation is free to provide other data : types that are not subtypes of common. : X3J13 voted in March 1989 <17> to remove the type common (and the predicate | commonp) from the language, on the grounds that it has not proved to be useful | in practice and that it could be difficult to redefine in the face of other | changes to the Common Lisp type system (such as the introduction of CLOS | classes). | The following categories of Common Lisp objects are of particular interest: numbers, characters, symbols, lists, arrays, structures, and functions. There are others as well. Some of these categories have many subdivisions. There are also standard types defined to be the union of two or more of these categories. The categories listed above, while they are data types, are neither more nor less "real" than other data types; they simply constitute a particularly useful slice across the type hierarchy for expository purposes. Here are brief descriptions of various Common Lisp data types. The remaining sections of this chapter go into more detail and also describe notations for objects of each type. Descriptions of Lisp functions that operate on data objects of each type appear in later chapters. * Numbers are provided in various forms and representations. Common Lisp provides a true integer data type: any integer, positive or negative, has in principle a representation as a Common Lisp data object, subject only to total memory limitations (rather than machine word width). A true rational data type is provided: the quotient of two integers, if not an integer, is a ratio. Floating-point numbers of various ranges and precisions are also provided, as well as Cartesian complex numbers. * Characters represent printed glyphs such as letters or text formatting operations. Strings are one-dimensional arrays of characters. Common Lisp provides for a rich character set, including ways to represent characters of various type styles. * Symbols (sometimes called atomic symbols for emphasis or clarity) are named data objects. Lisp provides machinery for locating a symbol object, given its name (in the form of a string). Symbols have property lists, which in effect allow symbols to be treated as record structures with an extensible set of named components, each of which may be any Lisp object. Symbols also serve to name functions and variables within programs. * Lists are sequences represented in the form of linked cells called conses. There is a special object (the symbol nil) that is the empty list. All other lists are built recursively by adding a new element to the front of an existing list. This is done by creating a new cons, which is an object having two components called the car and the cdr. The car may hold anything, and the cdr is made to point to the previously existing list. (Conses may actually be used completely generally as two-element record structures, but their most important use is to represent lists.) * Arrays are dimensioned collections of objects. An array can have any non- negative number of dimensions and is indexed by a sequence of integers. A general array can have any Lisp object as a component; other types of arrays are specialized for efficiency and can hold only certain types of Lisp objects. It is possible for two arrays, possibly with differing dimension information, to share the same set of elements (such that modifying one array modifies the other also) by causing one to be displaced to the other. One- dimensional arrays of any kind are called vectors. One-dimensional arrays of characters are called strings. One-dimensional arrays of bits (that is, of integers whose values are 0 or 1) are called bit-vectors. * Hash tables provide an efficient way of mapping any Lisp object (a key) to an associated object. * Readtables are used to control the built-in expression parser read. * Packages are collections of symbols that serve as name spaces. The parser recognizes symbols by looking up character sequences in the current package. * Pathnames represent names of files in a fairly implementation-independent manner. They are used to interface to the external file system. * Streams represent sources or sinks of data, typically characters or bytes. They are used to perform I/O, as well as for internal purposes such as parsing strings. * Random-states are data structures used to encapsulate the state of the built- in random-number generator. * Structures are user-defined record structures, objects that have named components. The defstruct facility is used to define new structure types. Some Common Lisp implementations may choose to implement certain system- supplied data types, such as bignums, readtables, streams, hash tables, and pathnames, as structures, but this fact will be invisible to the user. * Functions are objects that can be invoked as procedures; these may take : arguments and return values. (All Lisp procedures can be construed to return: values and therefore every procedure is a function.) Such objects include : compiled-functions (compiled code objects). Some functions are represented : as a list whose car is a particular symbol such as lambda. Symbols may also : be used as functions. : X3J13 voted in June 1988 <90> to specify that symbols are not of type | function, but are automatically coerced to functions in certain situations (see| section 2.13). | X3J13 voted in June 1988 <30> to adopt the Common Lisp Condition System, | thereby introducing a new category of data objects: | | * Conditions are objects used to affect control flow in certain conventional | ways by means of signals and handlers that intercept those signals. In | particular, errors are signaled by raising particular conditions, and errors | may be trapped by establishing handlers for those conditions. | X3J13 voted in June 1988 <12> to adopt the Common Lisp Object System, thereby| introducing additional categories of data objects: | | * Classes determine the structure and behavior of other objects, their | instances. Every Common Lisp data object belongs to some class. (In some | ways the CLOS class system is a generalization of the system of type | specifiers of the first edition of this book, but the class system augments | the type system rather than supplanting it.) | | * Methods are chunks of code that operate on arguments satisfying a particular | pattern of classes. Methods are not functions; they are not invoked directly| on arguments but instead are bundled into generic functions. | | * Generic functions are functions that contain, among other information, a set | of methods. When invoked, a generic function executes a subset of its | methods. The subset chosen for execution depends in a specific way on the | classes or identities of the arguments to which it is applied. | These categories are not always mutually exclusive. The required relationships among the various data types are explained in more detail in section 2.15. ------------------------------------------------------------------------------- 2.1. <### Numbers ###> Several kinds of numbers are defined in Common Lisp. They are divided into integers; ratios; floating-point numbers, with names provided for up to four different floating-point representations; and complex numbers. X3J13 voted in March 1989 <151> to add the type real. | | The number data type encompasses all kinds of numbers. For convenience, | there are names for some subclasses of numbers as well. Integers and ratios | are of type rational. Rational numbers and floating-point numbers are of type | real. Real numbers and complex numbers are of type number. | | Although the names of these types were chosen with the terminology of | mathematics in mind, the correspondences are not always exact. Integers and | ratios model the corresponding mathematical concepts directly. Numbers of type| float may be used to approximate real numbers, both rational and irrational. | The real type includes all Common Lisp numbers that represent mathematical real| numbers, though there are mathematical real numbers (irrational numbers) that | do not have an exact Common Lisp representation. Only real numbers may be | ordered using the <, >, <=, and >= functions. | | . . . . . . . . . . . . . . . . . . . . | Compatibility note: The Fortran 77 standard defines the term real datum to mean| "a processor approximation to the value of a real number." In practice the | Fortran basic real type is the floating-point data type that Common Lisp | calls single-float. The Fortran double precision type is Common Lisp's | double-float. The Pascal real data type is an "implementation-defined subset| of the real numbers." In practice this is usually a floating-point type, | often what Common Lisp calls double-float. | A translation of an algorithm written in Fortran or Pascal that uses real | data usually will use some appropriate precision of Common Lisp's float type.| Some algorithms may gain accuracy or flexibility by using Common Lisp's | rational or real type instead. | . . . . . . . . . . . . . . . . . . . . | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2.1.1. <## Integers ##> The integer data type is intended to represent mathematical integers. Unlike most programming languages, Common Lisp in principle imposes no limit on the magnitude of an integer; storage is automatically allocated as necessary to represent large integers. In every Common Lisp implementation there is a range of integers that are represented more efficiently than others; each such integer is called a fixnum, and an integer that is not a fixnum is called a bignum. Common Lisp is designed to hide this distinction as much as possible; the distinction between fixnums and bignums is visible to the user in only a few places where the fficiency of representation is important. Exactly which integers are fixnums is implementation-dependent; typically they will be those integers in the range (-2^n) to ((2^n) - 1), inclusive, for some n not less than 15. See most-positive-fixnum and most-negative-fixnum. X3J13 voted in January 1989 <76> to specify that fixnum must be a supertype | of the type (signed-byte 16), and additionally that the value of | array-dimension-limit must be a fixnum (implying that the implementor should | choose the range of fixnums to be large enough to accommodate the largest size | of array to be supported). | | . . . . . . . . . . . . . . . . . . . . | Rationale: This specification allows programmers to declare variables in | portable code to be of type fixnum for efficiency. Fixnums are guaranteed to| encompass at least the set of 16-bit signed integers (compare this to the | data type short int in the C programming language). In addition, any valid | array index must be a fixnum, and therefore variables used to hold array | indices (such as a dotimes variable) may be declared fixnum in portable code.| . . . . . . . . . . . . . . . . . . . . | Integers are ordinarily written in decimal notation, as a sequence of decimal digits, optionally preceded by a sign and optionally followed by a decimal point. For example: 0 ; Zero -0 ; This always means the same as 0 +6 ; The first perfect number 28 ; The second perfect number 1024. ; Two to the tenth power -1 ; e^(pi*i) 15511210043330985984000000. ; 25 factorial (25!), probably a bignum . . . . . . . . . . . . . . . . . . . . Compatibility note: MacLisp and Lisp Machine Lisp normally assume that integers are written in octal (radix-8) notation unless a decimal point is present. Interlisp assumes integers are written in decimal notation and uses a trailing Q to indicate octal radix; however, a decimal point, even in trailing position, always indicates a floating-point number. This is of course consistent with Fortran. Ada does not permit trailing decimal points but instead requires them to be embedded. In Common Lisp, integers written as described above are always construed to be in decimal notation, whether or not the decimal point is present; allowing the decimal point to be present permits compatibility with MacLisp. . . . . . . . . . . . . . . . . . . . . Integers may be notated in radices other than ten. The notation #nnrddddd or #nnRddddd means the integer in radix-nn notation denoted by the digits ddddd. More precisely, one may write #, a non-empty sequence of decimal digits representing an unsigned decimal integer n, r (or R), an optional sign, and a sequence of radix-n digits, to indicate an integer written in radix n (which must be between 2 and 36, inclusive). Only legal digits for the specified radix may be used; for example, an octal number may contain only the digits 0 through 7. For digits above 9, letters of the alphabet of either case may be used in order. Binary, octal, and hexadecimal radices are useful enough to warrant the special abbreviations #b for #2r, #o for #8r, and #x for #16r. For example: #2r11010101 ; Another way of writing 213 decimal #b11010101 ; Ditto #b+11010101 ; Ditto #o325 ; Ditto, in octal radix #xD5 ; Ditto, in hexadecimal radix #16r+D5 ; Ditto #o-300 ; Decimal -192, written in base 8 #3r-21010 ; Same thing in base 3 #25R-7H ; Same thing in base 25 #xACCEDED ; 181202413, in hexadecimal radix - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2.1.2. <## Ratios ##> A ratio is a number representing the mathematical ratio of two integers. Integers and ratios collectively constitute the type rational. The canonical representation of a rational number is as an integer if its value is integral, and otherwise as the ratio of two integers, the numerator and denominator, whose greatest common divisor is 1, and of which the denominator is positive (and in fact greater than 1, or else the value would be integral). A ratio is notated with / as a separator, thus: 3/5. It is possible to notate ratios in non-canonical (unreduced) forms, such as 4/6, but the Lisp function prin1 always prints the canonical form for a ratio. If any computation produces a result that is a ratio of two integers such that the denominator evenly divides the numerator, then the result is immediately converted to the equivalent integer. This is called the rule of rational canonicalization. Rational numbers may be written as the possibly signed quotient of decimal numerals: an optional sign followed by two non-empty sequences of digits separated by a /. This syntax may be described as follows: ratio ::= [sign] {digit}+ / {digit}+ The second sequence may not consist entirely of zeros. For example: 2/3 ; This is in canonical form 4/6 ; A non-canonical form for the same number -17/23 ; A not very interesting ratio -30517578125/32768 ; This is (-5/2)^15 10/5 ; The canonical form for this is 2 To notate rational numbers in radices other than ten, one uses the same radix specifiers (one of #nnR, #O, #B, or #X) as for integers. For example: #o-101/75 ; Octal notation for -65/61 #3r120/21 ; Ternary notation for 15/7 #Xbc/ad ; Hexadecimal notation for 188/173 #xFADED/FACADE ; Hexadecimal notation for 1027565/16435934 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2.1.3. <## Floating-Point Numbers ##> Common Lisp allows an implementation to provide one or more kinds of floating-point number, which collectively make up the type float. Now a floating-point number is a (mathematical) rational number of the form s * f * b^(ep), where s is +1 or -1, the sign; b is an integer greater than 1, the base or radix of the representation; p is a positive integer, the precision (in base-b digits) of the floating-point number; f is a positive integer between b^(p-1) and (b^p)-1 (inclusive), the significand; and e is an integer, the exponent. The value of p and the range of e depends on the implementation and on the type of floating-point number within that implementation. In addition, there is a floating-point zero; depending on the implementation, there may also be a "minus zero." If there is no minus zero, then 0.0 and -0.0 are both interpreted as simply a floating-point zero. . . . . . . . . . . . . . . . . . . . . Implementation note: The form of the above description should not be construed to require the internal representation to be in sign-magnitude form. Two's- complement and other representations are also acceptable. Note that the radix of the internal representation may be other than 2, as on the IBM 360 and 370, which use radix 16; see float-radix. . . . . . . . . . . . . . . . . . . . . Floating-point numbers may be provided in a variety of precisions and sizes, depending on the implementation. High-quality floating-point software tends to depend critically on the precise nature of the floating-point arithmetic and so may not always be completely portable. As an aid in writing programs that are moderately portable, however, certain definitions are made here: * A short floating-point number (type short-float) is of the representation of smallest fixed precision provided by an implementation. * A long floating-point number (type long-float) is of the representation of the largest fixed precision provided by an implementation. * Intermediate between short and long formats are two others, arbitrarily called single and double (types single-float and double-float). The precise definition of these categories is implementation-dependent. However, the rough intent is that short floating-point numbers be precise to at least four decimal places (but also have a space-efficient representation); single floating-point numbers, to at least seven decimal places; and double floating-point numbers, to at least fourteen decimal places. It is suggested that the precision (measured in bits, computed as p * (log2 b) and the exponent size (also measured in bits, computed as the base-2 logarithm of 1 plus the maximum exponent value) be at least as great as the values in table 2-1. ............................................................................... Table 2-1: Recommended Minimum Floating-Point Precision and Exponent Size Format Minimum Precision Minimum Exponent Size ---------------------------------------------------- Short 13 bits 5 bits Single 24 bits 8 bits Double 50 bits 8 bits Long 50 bits 8 bits ---------------------------------------------------- ............................................................................... Floating-point numbers are written in either decimal fraction or computerized scientific notation: an optional sign, then a non-empty sequence of digits with an embedded decimal point, then an optional decimal exponent specification. If there is no exponent specifier, then the decimal point is required, and there must be digits after it. The exponent specifier consists of an exponent marker, an optional sign, and a non-empty sequence of digits. For preciseness, here is a modified-BNF description of floating-point notation. floating-point-number ::= [sign] {digit}* decimal-point {digit}+ [exponent] | [sign] {digit}+ [decimal-point {digit}*] exponent sign ::= + | - decimal-point ::= . digit ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 exponent ::= exponent-marker [sign] {digit}+ exponent-marker ::= e | s | f | d | l | E | S | F | D | L If no exponent specifier is present, or if the exponent marker e (or E) is used, then the precise format to be used is not specified. When such a representation is read and converted to an internal floating-point data object, the format specified by the variable *read-default-float-format* is used; the initial value of this variable is single-float. The letters s, f, d, and l (or their respective uppercase equivalents) explicitly specify the use of short, single, double, and long format, respectively. Examples of floating-point numbers: 0.0 ; Floating-point zero in default format 0E0 ; Also floating-point zero in default format -.0 ; This may be a zero or a minus zero, ; depending on the implementation 0. ; The integer zero, not a floating-point zero! 0.0s0 ; A floating-point zero in short format 0s0 ; Also a floating-point zero in short format 3.1415926535897932384d0 ; A double-format approximation to pi 6.02E+23 ; Avogadro's number, in default format 602E+21 ; Also Avogadro's number, in default format 3.010299957f-1 ; log10(2), in single format -0.000000001s9 ; e^(pi*i) in short format, the hard way __Notice of correction.__ | The first edition unfortunately listed an incorrect value (3.1010299957f-1) | for the base-10 logarithm of 2. | The internal format used for an external representation depends only on the exponent marker and not on the number of decimal digits in the external representation. While Common Lisp provides terminology and notation sufficient to accommodate four distinct floating-point formats, not all implementations will have the means to support that many distinct formats. An implementation is therefore permitted to provide fewer than four distinct internal floating-point formats, in which case at least one of them will be "shared" by more than one of the external format names short, single, double, and long according to the following rules: * If one internal format is provided, then it is considered to be single, but serves also as short, double, and long. The data types short-float, single- float, double-float, and long-float are considered to be identical. An expression such as (eql 1.0s0 1.0d0) will be true in such an implementation because the two numbers 1.0s0 and 1.0d0 will be converted into the same internal format and therefore be considered to have the same data type, despite the differing external syntax. Similarly, (typep 1.0L0 'short-float) will be true in such an implementation. For output purposes all floating-point numbers are assumed to be of single format and thus will print using the exponent letter E or F. * If two internal formats are provided, then either of two correspondences may be used, depending on which is the more appropriate: - One format is short; the other is single and serves also as double and long. The data types single-float, double-float, and long-float are considered to be identical, but short-float is distinct. An expression such as (eql 1.0s0 1.0d0) will be false, but (eql 1.0f0 1.0d0) will be true. Similarly, (typep 1.0L0 'short-float) will be false, but (typep 1.0L0 'single-float) will be true. For output purposes all floating-point numbers are assumed to be of short or single format. - One format is single and serves also as short; the other is double and serves also as long. The data types short-float and single-float are considered to be identical, and the data types double-float and long-float are considered to be identical. An expression such as (eql 1.0s0 1.0d0) will be false, as will (eql 1.0f0 1.0d0); but (eql 1.0d0 1.0L0) will be true. Similarly, (typep 1.0L0 'short-float) will be false, but (typep 1.0L0 'double-float) will be true. For output purposes all floating-point numbers are assumed to be of single or double format. * If three internal formats are provided, then either of two correspondences may be used, depending on which is the more appropriate: - One format is short; another format is single; and the third format is double and serves also as long. Similar constraints apply. - One format is single and serves also as short; another is double; and the third format is long. . . . . . . . . . . . . . . . . . . . . Implementation note: It is recommended that an implementation provide as many distinct floating-point formats as feasible, using table 2-1 as a guideline. Ideally, short-format floating-point numbers should have an "immediate" representation that does not require heap allocation; single-format floating-point numbers should approximate IEEE proposed standard single- format floating-point numbers; and double-format floating-point numbers should approximate IEEE proposed standard double-format floating-point numbers [23,17,16]. . . . . . . . . . . . . . . . . . . . . - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2.1.4. <## Complex Numbers ##> Complex numbers (type complex) are represented in Cartesian form, with a real part and an imaginary part, each of which is a non-complex number (integer, ratio, or floating-point number). It should be emphasized that the parts of a complex number are not necessarily floating-point numbers; in this, Common Lisp is like PL/I and differs from Fortran. However, both parts must be of the same type: either both are rational, or both are of the same floating-point format. Complex numbers may be notated by writing the characters #C followed by a list of the real and imaginary parts. If the two parts as notated are not of the same type, then they are converted according to the rules of floating-point contagion as described in chapter 12. (Indeed, #C(a b) is equivalent to #,(complex a b); see the description of the function complex.) For example: #C(3.0s1 2.0s-1) ; Real and imaginary parts are short format #C(5 -3) ; A Gaussian integer #C(5/3 7.0) ; Will be converted internally to #C(1.66666 7.0) #C(0 1) ; The imaginary unit, that is, i The type of a specific complex number is indicated by a list of the word complex and the type of the components; for example, a specialized representation for complex numbers with short floating-point parts would be of type (complex short-float). The type complex encompasses all complex representations. A complex number of type (complex rational), that is, one whose components are rational, can never have a zero imaginary part. If the result of a computation would be a complex rational with a zero imaginary part, the result is immediately converted to a non-complex rational number by taking the real part. This is called the rule of complex canonicalization. This rule does not apply to floating-point complex numbers; #C(5.0 0.0) and 5.0 are different. ------------------------------------------------------------------------------- 2.2. <### Characters ###> Characters are represented as data objects of type character. There are two subtypes of interest, called standard-char and string-char. : X3J13 voted in March 1989 <11> to remove the type string-char. | A character object can be notated by writing #\ followed by the character itself. For example, #\g means the character object for a lowercase g. This works well enough for printing characters. Non-printing characters have names, and can be notated by writing #\ and then the name; for example, #\Space (or #\SPACE or #\space or #\sPaCE) means the space character. The syntax for character names after #\ is the same as that for symbols. However, only character names that are known to the particular implementation may be used. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2.2.1. <## Standard Characters ##> Common Lisp defines a standard character set (subtype standard-char) for two purposes. Common Lisp programs that are written in the standard character set can be read by any Common Lisp implementation; and Common Lisp programs that use only standard characters as data objects are most likely to be portable. The Common Lisp character set consists of a space character #\Space, a newline character #\Newline, and the following ninety-four non-blank printing characters or their equivalents: ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ` a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~ The Common Lisp standard character set is apparently equivalent to the ninety-five standard ASCII printing characters plus a newline character. Nevertheless, Common Lisp is designed to be relatively independent of the ASCII character encoding. For example, the collating sequence is not specified except to say that digits must be properly ordered, the uppercase letters must be properly ordered, and the lowercase letters must be properly ordered (see char< for a precise specification). Other character encodings, particularly EBCDIC, should be easily accommodated (with a suitable mapping of printing characters). Of the ninety-four non-blank printing characters, the following are used in only limited ways in the syntax of Common Lisp programs: [ ] { } ? ! ^ _ ~ $ % All of these characters except ! and _ are used within format strings as : formatting directives. Except for this, [, ], {, }, ?, and ! are not used in : Common Lisp and are reserved to the user for syntactic extensions; ^ and _ are : not yet used in Common Lisp but are part of the syntax of reserved tokens and : are reserved to implementors; ~ is not yet used in Common Lisp and is reserved : to implementors; and $ and % are normally regarded as alphabetic characters but: are not used in the names of any standard Common Lisp functions, variables, or : other entities. : X3J13 voted in June 1989 <139> to add a format directive ~_ (see chapter 27).| The following characters are called semi-standard: #\Backspace #\Tab #\Linefeed #\Page #\Return #\Rubout Not all implementations of Common Lisp need to support them; but those implementations that use the standard ASCII character set should support them, treating them as corresponding respectively to the ASCII characters BS (octal code 010), HT (011), LF (012), FF (014), CR (015), and DEL (177). These characters are not members of the subtype standard-char unless synonymous with one of the standard characters specified above. For example, in a given implementation it might be sensible for the implementor to define #\Linefeed or #\Return to be synonymous with #\Newline, or #\Tab to be synonymous with #\Space. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2.2.2. <## Line Divisions ##> The treatment of line divisions is one of the most difficult issues in designing portable software, simply because there is so little agreement among operating systems. Some use a single character to delimit lines; the recommended ASCII character for this purpose is the line feed character LF (also called the new line character, NL), but some systems use the carriage return character CR. Much more common is the two-character sequence CR followed by LF. Frequently line divisions have no representation as a character but are implicit in the structuring of a file into records, each record containing a line of text. A deck of punched cards has this structure, for example. Common Lisp provides an abstract interface by requiring that there be a single character, #\Newline, that within the language serves as a line delimiter. (The language C has a similar requirement.) An implementation of Common Lisp must translate between this internal single-character representation and whatever external representation(s) may be used. . . . . . . . . . . . . . . . . . . . . Implementation note: How the character called #\Newline is represented internally is not specified here, but it is strongly suggested that the ASCII LF character be used in Common Lisp implementations that use the ASCII character encoding. The ASCII CR character is a workable, but in most cases inferior, alternative. . . . . . . . . . . . . . . . . . . . . When the first edition was written it was not yet clear that UNIX would become so widely accepted. The decision to represent the line delimiter as a single character has proved to be a good one. The requirement that a line division be represented as a single character has certain consequences. A character string written in the middle of a program in such a way as to span more than one line must contain exactly one character to represent each line division. Consider this code fragment: (setq a-string "This string contains forty-two characters.") Between g and c there must be exactly one character, #\Newline; a two-character sequence, such as #\Return and then #\Newline, is not acceptable, nor is the absence of a character. The same is true between s and f. When the character #\Newline is written to an output file, the Common Lisp implementation must take the appropriate action to produce a line division. This might involve writing out a record or translating #\Newline to a CR/LF sequence. . . . . . . . . . . . . . . . . . . . . Implementation note: If an implementation uses the ASCII character encoding, uses the CR/LF sequence externally to delimit lines, uses LF to represent #\Newline internally, and supports #\Return as a data object corresponding to the ASCII character CR, the question arises as to what action to take when the program writes out #\Return followed by #\Newline. It should first be noted that #\Return is not a standard Common Lisp character, and the action to be taken when #\Return is written out is therefore not defined by the Common Lisp language. A plausible approach is to buffer the #\Return character and suppress it if and only if the next character is #\Newline (the net effect is to generate a CR/LF sequence). Another plausible approach is simply to ignore the difficulty and declare that writing #\Return and then #\Newline results in the sequence CR/CR/LF in the output. . . . . . . . . . . . . . . . . . . . . - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2.2.3. <## Non-standard Characters ##> Any implementation may provide additional characters, whether printing characters or named characters. Some plausible examples: #\pi #\alpha #\Break #\Home-Up #\Escape The use of such characters may render Common Lisp programs non-portable. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - : 2.2.4. <## Character Attributes ##> : : Every object of type character has three attributes: code, bits, and font. : The code attribute is intended to distinguish among the printed glyphs and : formatting functions for characters; it is a numerical encoding of the : character proper. The bits attribute allows extra flags to be associated with : a character. The font attribute permits a specification of the style of the : glyphs (such as italics). Each of these attributes may be understood to be a : non-negative integer. : : The font attribute may be notated in unsigned decimal notation between the # : and the \. For example, #3\a means the letter a in font 3. This might mean : the same thing as #\alpha if font 3 were used to represent Greek letters. Note: that not all Common Lisp implementations provide for non-zero font attributes; : see char-font-limit. : : The bits attribute may be notated by preceding the name of the character by : the names or initials of the bits, separated by hyphens. The character itself : may be written instead of the name, preceded if necessary by \. For example: : : #\Control-Meta-Return #\Meta-Control-Q : #\Hyper-Space #\Meta-a : #\Control-A #\Meta-Hyper-\: : #\C-M-Return #\Hyper-\pi : : Note that not all Common Lisp implementations provide for non-zero bits : attributes; see char-bits-limit. : X3J13 voted in March 1989 <11> to replace the notion of bits and font | attributes with that of implementation-defined attributes. | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2.2.5. <## String Characters ##> Any character whose bits and font attributes are zero may be contained in : strings. All such characters together constitute a subtype of the characters; : this subtype is called string-char. : X3J13 voted in March 1989 <11> to eliminate the type string-char. Two new | subtypes of character are base-character, defined to be equivalent to the | result of the function call | (upgraded-array-element-type 'standard-char) | and extended-character, defined to be equivalent to the type specifier | (and character (not base-character)) | | An implementation may support additional subtypes of character that may or | may not be supertypes of base-character. In addition, an implementation may | define base-character to be equivalent to character. The choice of any base | characters that are not standard characters is implementation-defined. Only | base characters can be elements of a base string. No upper bound is specified | for the number of distinct characters of type base-character -- that is | implementation-dependent -- but the lower bound is 96, the number of standard | Common Lisp characters. | ------------------------------------------------------------------------------- 2.3. <### Symbols ###> Symbols are Lisp data objects that serve several purposes and have several interesting characteristics. Every object of type symbol has a name, called its print name. Given a symbol, one can obtain its name in the form of a string. Conversely, given the name of a symbol as a string, one can obtain the symbol itself. (More precisely, symbols are organized into packages, and all the symbols in a package are uniquely identified by name. See chapter 11.) Symbols have a component called the property list, or plist. By convention this is always a list whose even-numbered components (calling the first component zero) are symbols, here functioning as property names, and whose odd-numbered components are associated property values. Functions are provided for manipulating this property list; in effect, these allow a symbol to be treated as an extensible record structure. Symbols are also used to represent certain kinds of variables in Lisp programs, and there are functions for dealing with the values associated with symbols in this role. A symbol can be notated simply by writing its name. If its name is not empty, and if the name consists only of uppercase alphabetic, numeric, or certain pseudo-alphabetic special characters (but not delimiter characters such as parentheses or space), and if the name of the symbol cannot be mistaken for a number, then the symbol can be notated by the sequence of characters in its name. Any uppercase letters that appear in the (internal) name may be written in either case in the external notation (more on this below). For example: FROBBOZ ; The symbol whose name is FROBBOZ frobboz ; Another way to notate the same symbol fRObBoz ; Yet another way to notate it unwind-protect ; A symbol with a - in its name +$ ; The symbol named +$ 1+ ; The symbol named 1+ +1 ; This is the integer 1, not a symbol pascal_style ; This symbol has an underscore in its name b^2-4*a*c ; This is a single symbol! ; It has several special characters in its name file.rel.43 ; This symbol has periods in its name /usr/games/zork ; This symbol has slashes in its name In addition to letters and numbers, the following characters are normally considered to be alphabetic for the purposes of notating symbols: + - * / @ $ % ^ & _ = < > ~ . Some of these characters have conventional purposes for naming things; for example, symbols that name special variables generally have names beginning and ending with *. The last character listed above, the period, is considered alphabetic provided that a token does not consist entirely of periods. A single period standing by itself is used in the notation of conses and dotted lists; a token consisting of two or more periods is syntactically illegal. (The period also serves as the decimal point in the notation of numbers.) The following characters are also alphabetic by default but are explicitly reserved to the user for definition as reader macro characters (see section 22.1.3) or any other desired purpose and therefore should not be used routinely in names of symbols: ? ! [ ] { } A symbol may have uppercase letters, lowercase letters, or both in its print name. However, the Lisp reader normally converts lowercase letters to the corresponding uppercase letters when reading symbols. The net effect is that most of the time case makes no difference when notating symbols. Case does make a difference internally and when printing a symbol. Internally the symbols that name all standard Common Lisp functions, variables, and keywords have uppercase names; their names appear in lowercase in this book for readability. Typing such names with lowercase letters works because the function read will convert lowercase letters to the equivalent uppercase letters. X3J13 voted in June 1989 <150> to introduce readtable-case, which controls | whether read will alter the case of letters read as part of the name of a | symbol. | If a symbol cannot be simply notated by the characters of its name because the (internal) name contains special characters or lowercase letters, then there are two "escape" conventions for notating them. Writing a \ character before any character causes the character to be treated itself as an ordinary character for use in a symbol name; in particular, it suppresses internal conversion of lowercase letters to their uppercase equivalents. If any character in a notation is preceded by \, then that notation can never be interpreted as a number. For example: \( ; The symbol whose name is ( \+1 ; The symbol whose name is +1 +\1 ; Also the symbol whose name is +1 \frobboz ; The symbol whose name is fROBBOZ 3.14159265\s0 ; The symbol whose name is 3.14159265s0 3.14159265\S0 ; A different symbol, whose name is 3.14159265S0 3.14159265s0 ; A short-format floating-point approximation to pi APL\\360 ; The symbol whose name is APL\360 apl\\360 ; Also the symbol whose name is APL\360 \(b^2\)\ -\ 4*a*c ; The name is (B^2) - 4*A*C; ; it has parentheses and two spaces in it \(\b^2\)\ -\ 4*\a*\c ; The name is (b^2) - 4*a*c; ; the letters are explicitly lowercase It may be tedious to insert a \ before every delimiter character in the name of a symbol if there are many of them. An alternative convention is to surround the name of a symbol with vertical bars; these cause every character between them to be taken as part of the symbol's name, as if \ had been written before each one, excepting only | itself and \, which must nevertheless be preceded by \. For example: |"| ; The same as writing \" |(b^2) - 4*a*c| ; The name is (b^2) - 4*a*c |frobboz| ; The name is frobboz, not FROBBOZ |APL\360| ; The name is APL360, because the \ quotes the 3 |APL\\360| ; The name is APL\360 |apl\\360| ; The name is apl\360 |\|\|| ; Same as \|\|: the name is || |(B^2) - 4*A*C| ; The name is (B^2) - 4*A*C; ; it has parentheses and two spaces in it |(b^2) - 4*a*c| ; The name is (b^2) - 4*a*c ------------------------------------------------------------------------------- 2.4. <### Lists and Conses ###> A cons is a record structure containing two components called the car and the cdr. Conses are used primarily to represent lists. A list is recursively defined to be either the empty list or a cons whose cdr component is a list. A list is therefore a chain of conses linked by their cdr components and terminated by nil, the empty list. The car components of the conses are called the elements of the list. For each element of the list there is a cons. The empty list has no elements at all. A list is notated by writing the elements of the list in order, separated by blank space (space, tab, or return characters) and surrounded by parentheses. (a b c) ; A list of three symbols (2.0s0 (a 1) #\*) ; A list of three things: a short floating-point ; number, another list, and a character object The empty list nil therefore can be written as (), because it is a list with no elements. A dotted list is one whose last cons does not have nil for its cdr, rather some other data object (which is also not a cons, or the first-mentioned cons would not be the last cons of the list). Such a list is called "dotted" because of the special notation used for it: the elements of the list are written between parentheses as before, but after the last element and before the right parenthesis are written a dot (surrounded by blank space) and then the cdr of the last cons. As a special case, a single cons is notated by writing the car and the cdr between parentheses and separated by a space- surrounded dot. For example: (a . 4) ; A cons whose car is a symbol ; and whose cdr is an integer (a b c . d) ; A dotted list with three elements whose last cons ; has the symbol d in its cdr . . . . . . . . . . . . . . . . . . . . Compatibility note: In MacLisp, the dot in dotted-list notation need not be surrounded by white space or other delimiters. The dot is required to be delimited in Common Lisp, as in Lisp Machine Lisp. . . . . . . . . . . . . . . . . . . . . It is legitimate to write something like (a b . (c d)); this means the same as (a b c d). The standard Lisp output routines will never print a list in the first form, however; they will avoid dot notation wherever possible. Often the term list is used to refer either to true lists or to dotted lists. When the distinction is important, the term "true list" will be used to refer to a list terminated by nil. Most functions advertised to operate on lists expect to be given true lists. Throughout this book, unless otherwise specified, it is an error to pass a dotted list to a function that is specified to require a list as an argument. . . . . . . . . . . . . . . . . . . . . Implementation note: Implementors are encouraged to use the equivalent of the predicate endp wherever it is necessary to test for the end of a list. Whenever feasible, this test should explicitly signal an error if a list is found to be terminated by a non-nil atom. However, such an explicit error signal is not required, because some such tests occur in important loops where efficiency is important. In such cases, the predicate atom may be used to test for the end of the list, quietly treating any non-nil list- terminating atom as if it were nil. . . . . . . . . . . . . . . . . . . . . Sometimes the term tree is used to refer to some cons and all the other conses transitively accessible to it through car and cdr links until non-conses are reached; these non-conses are called the leaves of the tree. Lists, dotted lists, and trees are not mutually exclusive data types; they are simply useful points of view about structures of conses. There are yet other terms, such as association list. None of these are true Lisp data types. Conses are a data type, and nil is the sole object of type null. The Lisp data type list is taken to mean the union of the cons and null data types, and therefore encompasses both true lists and dotted lists. ------------------------------------------------------------------------------- 2.5. <### Arrays ###> An array is an object with components arranged according to a Cartesian coordinate system. In general, these components may be any Lisp data objects. The number of dimensions of an array is called its rank (this terminology is borrowed from APL); the rank is a non-negative integer. Likewise, each dimension is itself a non-negative integer. The total number of elements in the array is the product of all the dimensions. An implementation of Common Lisp may impose a limit on the rank of an array, but this limit may not be smaller than 7. Therefore, any Common Lisp program may assume the use of arrays of rank 7 or less. (A program may determine the actual limit on array ranks for a given implementation by examining the constant array-rank-limit.) It is permissible for a dimension to be zero. In this case, the array has no elements, and any attempt to access an element is in error. However, other properties of the array, such as the dimensions themselves, may be used. If the rank is zero, then there are no dimensions, and the product of the dimensions is then by definition 1. A zero-rank array therefore has a single element. An array element is specified by a sequence of indices. The length of the sequence must equal the rank of the array. Each index must be a non-negative integer strictly less than the corresponding array dimension. Array indexing is therefore zero-origin, not one-origin as in (the default case of) Fortran. As an example, suppose that the variable foo names a 3-by-5 array. Then the first index may be 0, 1, or 2, and the second index may be 0, 1, 2, 3, or 4. One may refer to array elements using the function aref; for example, (aref foo 2 1) refers to element (2, 1) of the array. Note that aref takes a variable number of arguments: an array, and as many indices as the array has dimensions. A zero-rank array has no dimensions, and therefore aref would take such an array and no indices, and return the sole element of the array. In general, arrays can be multidimensional, can share their contents with other array objects, and can have their size altered dynamically (either enlarging or shrinking) after creation. A one-dimensional array may also have a fill pointer. Multidimensional arrays store their components in row-major order; that is, internally a multidimensional array is stored as a one-dimensional array, with the multidimensional index sets ordered lexicographically, last index varying fastest. This is important in two situations: (1) when arrays with different dimensions share their contents, and (2) when accessing very large arrays in a virtual-memory implementation. (The first situation is a matter of semantics; the second, a matter of efficiency.) An array that is not displaced to another array, has no fill pointer, and is not to have its size adjusted dynamically after creation is called a simple array. The user may provide declarations that certain arrays will be simple. Some implementations can handle simple arrays in an especially efficient manner; for example, simple arrays may have a more compact representation than non-simple arrays. X3J13 voted in June 1989 <3> to clarify that if one or more of the | :adjustable, :fill-pointer, and :displaced-to arguments is true when make-array| is called, then whether the resulting array is simple is unspecified; but if | all three arguments are false, then the resulting array is guaranteed to be | simple. | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2.5.1. <## Vectors ##> One-dimensional arrays are called vectors in Common Lisp and constitute the type vector (which is therefore a subtype of array). Vectors and lists are collectively considered to be sequences. They differ in that any component of a one-dimensional array can be accessed in constant time, whereas the average component access time for a list is linear in the length of the list; on the other hand, adding a new element to the front of a list takes constant time, whereas the same operation on an array takes time linear in the length of the array. A general vector (a one-dimensional array that can have any data object as an element but that has no additional paraphernalia) can be notated by notating the components in order, separated by whitespace and surrounded by "#(" and ")". For example: #(a b c) ; A vector of length 3 #() ; An empty vector #(2 3 5 7 11 13 17 19 23 29 31 37 41 43 47) ; A vector containing the primes below 50 Note that when the function read parses this syntax, it always constructs a simple general vector. . . . . . . . . . . . . . . . . . . . . Rationale: Many people have suggested that brackets be used to notate vectors, as [a b c] instead of #(a b c). This notation would be shorter, perhaps more readable, and certainly in accord with cultural conventions in other parts of computer science and mathematics. However, to preserve the usefulness of the user-definable macro-character feature of the function read, it is necessary to leave some characters to the user for this purpose. Experience in MacLisp has shown that users, especially implementors of languages for use in artificial intelligence research, often want to define special kinds of brackets. Therefore Common Lisp avoids using brackets and braces for any syntactic purpose. . . . . . . . . . . . . . . . . . . . . Implementations may provide certain specialized representations of arrays for efficiency in the case where all the components are of the same specialized (typically numeric) type. All implementations provide specialized arrays for the cases when the components are characters (or rather, a special subset of the characters); the one-dimensional instances of this specialization are called strings. All implementations are also required to provide specialized arrays of bits, that is, arrays of type (array bit); the one-dimensional instances of this specialization are called bit-vectors. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2.5.2. <## Strings ##> A string is simply a vector of characters. More precisely, a string is a : specialized vector whose elements are of type string-char. : X3J13 voted in March 1989 <11> to eliminate the type string-char and to | redefine the type string to be the union of one or more specialized vector | types, the types of whose elements are subtypes of the type character. | Subtypes of string include simple-string, base-string, and simple-base-string. | | base-string == (vector base-character) | simple-base-string == (simple-array base-character (*)) | | An implementation may support other string subtypes as well. All Common Lisp| functions that operate on strings treat all strings uniformly; note, however, | that it is an error to attempt to insert an extended character into a base | string. | The type string is therefore a subtype of the type vector. A string can be written as the sequence of characters contained in the string, preceded and followed by a " (double quote) character. Any " or \ character in the sequence must additionally have a \ character before it. For example: "Foo" ; A string with three characters in it "" ; An empty string "\"APL\\360?\" he cried." ; A string with twenty characters "|x| = |-x|" ; A ten-character string Notice that any vertical bar | in a string need not be preceded by a \. Similarly, any double quote in the name of a symbol written using vertical-bar notation need not be preceded by a \. The double-quote and vertical-bar notations are similar but distinct: double quotes indicate a character string containing the sequence of characters, whereas vertical bars indicate a symbol whose name is the contained sequence of characters. The characters contained by the double quotes, taken from left to right, occupy locations within the string with increasing indices. The leftmost character is string element number 0, the next one is element number 1, the next one is element number 2, and so on. Note that the function prin1 will print any character vector (not just a simple one) using this syntax, but the function read will always construct a simple string when it reads this syntax. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 2.5.3. <## Bit-Vectors ##> A bit-vector can be written as the sequence of bits contained in the string, preceded by #*; any delimiter character, such as whitespace, will terminate the bit-vector syntax. For example: #*10110 ; A five-bit bit-vector; bit 0 is a 1 #* ; An empty bit-vector The bits notated following the #*, taken from left to right, occupy locations within the bit-vector with increasing indices. The leftmost notated bit is bit-vector element number 0, the next one is element number 1, and so on. The function prin1 will print any bit-vector (not just a simple one) using this syntax, but the function read will always construct a simple bit-vector when it reads this syntax. ------------------------------------------------------------------------------- 2.6. <### Hash Tables ###> Hash tables provide an efficient way of mapping any Lisp object (a key) to an associated object. They are provided as primitives of Common Lisp because some implementations may need to use internal storage management strategies that would make it very difficult for the user to implement hash tables in a portable fashion. Hash tables are described in chapter 16. ------------------------------------------------------------------------------- 2.7. <### Readtables ###> A readtable is a data structure that maps characters into syntax types for the Lisp expression parser. In particular, a readtable indicates for each character with syntax macro character what its macro definition is. This is a mechanism by which the user may reprogram the parser to a limited but useful extent. See section 22.1.5. ------------------------------------------------------------------------------- 2.8. <### Packages ###> Packages are collections of symbols that serve as name spaces. The parser recognizes symbols by looking up character sequences in the current package. Packages can be used to hide names internal to a module from other code. Mechanisms are provided for exporting symbols from a given package to the primary "user" package. See chapter 11. ------------------------------------------------------------------------------- 2.9. <### Pathnames ###> Pathnames are the means by which a Common Lisp program can interface to an external file system in a reasonably implementation-independent manner. See section 23.1.1. ------------------------------------------------------------------------------- 2.10. <### Streams ###> A stream is a source or sink of data, typically characters or bytes. Nearly all functions that perform I/O do so with respect to a specified stream. The function open takes a pathname and returns a stream connected to the file specified by the pathname. There are a number of standard streams that are used by default for various purposes. See chapter 21. X3J13 voted in January 1989 <167> to introduce subtypes of type stream: | broadcast-stream, concatenated-stream, echo-stream, synonym-stream, | string-stream, file-stream, and two-way-stream are disjoint subtypes of stream.| Note particularly that a synonym stream is always and only of type | synonym-stream, regardless of the type of the stream for which it is a synonym.| ------------------------------------------------------------------------------- 2.11. <### Random-States ###> An object of type random-state is used to encapsulate state information used by the pseudo-random number generator. For more information about random-state objects, see section 12.9. ------------------------------------------------------------------------------- 2.12. <### Structures ###> Structures are instances of user-defined data types that have a fixed number of named components. They are analogous to records in Pascal. Structures are declared using the defstruct construct; defstruct automatically defines access and constructor functions for the new data type. Different structures may print out in different ways; the definition of a structure type may specify a print procedure to use for objects of that type (see the :print-function option to defstruct). The default notation for structures is #S(structure-name slot-name-1 slot-value-1 slot-name-2 slot-value-2 ...) where #S indicates structure syntax, structure-name is the name (a symbol) of the structure type, each slot-name is the name (also a symbol) of a component, and each corresponding slot-value is the representation of the Lisp object in that slot. ------------------------------------------------------------------------------- : 2.13. <### Functions ###> : : A function is anything that may be correctly given to the funcall or apply : function, and is to be executed as code when arguments are supplied. : : A compiled-function is a compiled code object. : : A lambda-expression (a list whose car is the symbol lambda) may serve as a : function. Depending on the implementation, it may be possible for other lists : to serve as functions. For example, an implementation might choose to : represent a "lexical closure" as a list whose car contains some special marker.: : A symbol may serve as a function; an attempt to invoke a symbol as a function: causes the contents of the symbol's function cell to be used. : See symbol-function and defun. : : The result of evaluating a function special form will always be a function. : X3J13 voted in June 1988 <90> to revise these specifications. The type | function is to be disjoint from cons and symbol, and so a list whose car is | lambda is not, properly speaking, of type function, nor is any symbol. | However, standard Common Lisp functions that accept functional arguments will | accept a symbol or a list whose car is lambda and automatically coerce it to be| a function; such standard functions include funcall, apply, and mapcar. Such | functions do not, however, accept a lambda-expression as a functional argument;| therefore one may not write | (mapcar '(lambda (x y) (sqrt (* x y))) p q) | but instead one must write something like | (mapcar #'(lambda (x y) (sqrt (* x y))) p q) | | This change makes it impermissible to represent a lexical closure as a list | whose car is some special marker. | | The value of a function special form will always be of type function. | ------------------------------------------------------------------------------- 2.14. <### Unreadable Data Objects ###> Some objects may print in implementation-dependent ways. Such objects cannot necessarily be reliably reconstructed from a printed representation, and so they are usually printed in a format informative to the user but not acceptable to the read function: #. The Lisp reader will signal an error on encountering #<. As a hypothetical example, an implementation might print # for an implementation-specific "internal stack pointer" data type whose printed representation includes the name of the type, some information about the stack slot pointed to, and the machine address (in octal) of the stack slot. See print-unreadable-object, a macro that prints an object using #< syntax. | ------------------------------------------------------------------------------- 2.15. <### Overlap, Inclusion, and Disjointness of Types ###> The Common Lisp data type hierarchy is tangled and purposely left somewhat open-ended so that implementors may experiment with new data types as extensions to the language. This section explicitly states all the defined relationships between types, including subtype/supertype relationships, disjointness, and exhaustive partitioning. The user of Common Lisp should not depend on any relationships not explicitly stated here. For example, it is not valid to assume that because a number is not complex and not rational that it must be a float, because implementations are permitted to provide yet other kinds of numbers. First we need some terminology. If x is a supertype of y, then any object of type y is also of type x, and y is said to be a subtype of x. If types x and y are disjoint, then no object (in any implementation) may be both of type x and of type y. Types a1 through an are an exhaustive union of type x if each aj is a subtype of x, and any object of type x is necessarily of at least one of the types aj; a1 through an are furthermore an exhaustive partition if they are also pairwise disjoint. * The type t is a supertype of every type whatsoever. Every object is of type t. * The type nil is a subtype of every type whatsoever. No object is of type nil. * The types cons, symbol, array, number, and character are pairwise disjoint. : * X3J13 voted in June 1988 <41> to extend the preceding paragraph as follows. | - The types cons, symbol, array, number, character, hash-table, readtable, | package, pathname, stream, random-state, and any single other type created by| defstruct or defclass are pairwise disjoint. | | The wording of the first edition was intended to allow implementors to use | the defstruct facility to define the built-in types hash-table, readtable, | package, pathname, stream, random-state. The change still permits this | implementation strategy but forbids these built-in types from including, or | being included in, other types (in the sense of the defstruct :include | option). X3J13 voted in June 1988 <90> to specify that the type function is disjoint | from the types cons, symbol, array, number, and character. The type | compiled-function is a subtype of function; implementations are free to | define other subtypes of function. * The types rational, float, and complex are pairwise disjoint subtypes of : number. : X3J13 voted in March 1989 <151> to rewrite the preceding item as follows. | | * The types real and complex are pairwise disjoint subtypes of number. | | . . . . . . . . . . . . . . . . . . . . | Rationale: It might be thought that real and complex should form an exhaustive | partition of the type number. This is purposely avoided here in order to | permit compatible experimentation with extensions to the Common Lisp number | system. | . . . . . . . . . . . . . . . . . . . . | | * The types rational and float are pairwise disjoint subtypes of real. | | . . . . . . . . . . . . . . . . . . . . Rationale: It might be thought that rational and float should form an | exhaustive partition of the type real. This is purposely avoided here in | order to permit compatible experimentation with extensions to the Common Lisp| number system. | . . . . . . . . . . . . . . . . . . . . | * The types integer and ratio are disjoint subtypes of rational. . . . . . . . . . . . . . . . . . . . . Rationale: It might be thought that integer and ratio should form an exhaustive partition of the type rational. This is purposely avoided here in order to permit compatible experimentation with extensions to the Common Lisp rational number system. . . . . . . . . . . . . . . . . . . . . * The types fixnum and bignum are disjoint subtypes of integer. : : . . . . . . . . . . . . . . . . . . . . : Rationale: It might be thought that fixnum and bignum should form an exhaustive: partition of the type integer. This is purposely avoided here in order to : permit compatible experimentation with extensions to the Common Lisp integer : number system, such as the idea of adding explicit representations of : infinity or of positive and negative infinity. : . . . . . . . . . . . . . . . . . . . . : X3J13 voted in January 1989 <76> to specify that the types fixnum and bignum | do in fact form an exhaustive partition of the type integer; more precisely, | they voted to specify that the type bignum is by definition equivalent to | (and integer (not fixnum)). This is consistent with the first edition text in | section 2.1.1. | | I interpret this to mean that implementators could still experiment with such| extensions as adding explicit representations of infinity, but such infinities | would necessarily be of type bignum. | * The types short-float, single-float, double-float, and long-float are subtypes of float. Any two of them must be either disjoint or identical; if identical, then any other types between them in the above ordering must also be identical to them (for example, if single-float and long-float are identical types, then double-float must be identical to them also). * The type null is a subtype of symbol; the only object of type null is nil. * The types cons and null form an exhaustive partition of the type list. * The type standard-char is a subtype of string-char; string-char is a subtype : of character. : X3J13 voted in March 1989 <11> to remove the type string-char. The preceding| item is replaced by the following. | | * The type standard-char is a subtype of base-character. The types | base-character and extended-character form an exhaustive partition of | character. | * The type string is a subtype of vector, for string means : (vector string-char). : X3J13 voted in March 1989 <11> to remove the type string-char. The preceding| item is replaced by the following. | | * The type string is a subtype of vector; it is the union of all types | (vector c) such that c is a subtype of character. | * The type bit-vector is a subtype of vector, for bit-vector means (vector bit). * The types (vector t), string, and bit-vector are disjoint. * The type vector is a subtype of array; for all types x, the type (vector x) is the same as the type (array x (*)). * The type simple-array is a subtype of array. * The types simple-vector, simple-string, and simple-bit-vector are disjoint : subtypes of simple-array, for they respectively mean (simple-array t (*)), : ;;(simple-array string-char (*)), and (simple-array bit (*)). : X3J13 voted in March 1989 <11> to remove the type string-char. The preceding| item is replaced by the following. | | * The types simple-vector, simple-string, and simple-bit-vector are disjoint | subtypes of simple-array, for they mean (simple-array t (*)), the union of | all types (simple-array c (*)) such that c is a subtype of character, and | (simple-array bit (*)), respectively. | * The type simple-vector is a subtype of vector and indeed is a subtype of (vector t). * The type simple-string is a subtype of string. (Note that although string is a subtype of vector, simple-string is not a subtype of simple-vector.) . . . . . . . . . . . . . . . . . . . . Rationale: The hypothetical name simple-general-vector would have been more accurate than simple-vector, but in this instance euphony and user convenience were deemed more important to the design of Common Lisp than a rigid symmetry. . . . . . . . . . . . . . . . . . . . . * The type simple-bit-vector is a subtype of bit-vector. (Note that although bit-vector is a subtype of vector, simple-bit-vector is not a subtype of simple-vector.) * The types vector and list are disjoint subtypes of sequence. * The types random-state, readtable, package, pathname, stream, and hash-table are pairwise disjoint. X3J13 voted in June 1988 <41> to make random-state, readtable, package, | pathname, stream, and hash-table pairwise disjoint from a number of other types| as well; see note above. | X3J13 voted in January 1989 <167> to introduce subtypes of type stream. | | * The types two-way-stream, echo-stream, broadcast-stream, file-stream, | synonym-stream, string-stream, and concatenated-stream are disjoint subtypes | of stream. | * Any two types created by defstruct are disjoint unless one is a supertype of the other by virtue of the :include option. * An exhaustive union for the type common is formed by the types cons, symbol, : (array x) where x is either t or a subtype of common, string, fixnum, bignum,: ratio, short-float, single-float, double-float, long-float, (complex x) where: x is a subtype of common, standard-char, hash-table, readtable, package, : pathname, stream, random-state, and all types created by the user via : defstruct. An implementation may not unilaterally add subtypes to common; : however, future revisions to the Common Lisp standard may extend the : definition of the common data type. Note that a type such as number or array: may or may not be a subtype of common, depending on whether or not the given : implementation has extended the set of objects of that type. : X3J13 voted in March 1989 <17> to remove the type common from the language. | =============================================================================== 3. <#### Scope and Extent ####> In describing various features of the Common Lisp language, the notions of scope and extent are frequently useful. These notions arise when some object or construct must be referred to from some distant part of a program. Scope refers to the spatial or textual region of the program within which references may occur. Extent refers to the interval of time during which references may occur. As a simple example, consider this program: (defun copy-cell (x) (cons (car x) (cdr x))) The scope of the parameter named x is the body of the defun form. There is no way to refer to this parameter from any other place but within the body of the defun. Similarly, the extent of the parameter x (for any particular call to copy-cell) is the interval from the time the function is invoked to the time it is exited. (In the general case, the extent of a parameter may last beyond the time of function exit, but that cannot occur in this simple case.) Within Common Lisp, a referenceable entity is established by the execution of some language construct, and the scope and extent of the entity are described relative to the construct and the time (during execution of the construct) at which the entity is established. For the purposes of this discussion, the term "entity" refers not only to Common Lisp data objects, such as symbols and conses, but also to variable bindings (both ordinary and special), catchers, and go targets. It is important to distinguish between an entity and a name for the entity. In a function definition such as (defun foo (x y) (* x (+ y 1))) there is a single name, x, used to refer to the first parameter of the procedure whenever it is invoked; however, a new binding is established on every invocation. A binding is a particular parameter instance. The value of a reference to the name x depends not only on the scope within which it occurs (the one in the body of foo in the example occurs in the scope of the function definition's parameters) but also on the particular binding or instance involved. (In this case, it depends on the invocation during which the reference is made). More complicated examples appear at the end of this chapter. There are a few kinds of scope and extent that are particularly useful in describing Common Lisp: * Lexical scope. Here references to the established entity can occur only within certain program portions that are lexically (that is, textually) contained within the establishing construct. Typically the construct will have a part designated the body, and the scope of all entities established will be (or include) the body. Example: the names of parameters to a function normally are lexically scoped. * Indefinite scope. References may occur anywhere, in any program. * Dynamic extent. References may occur at any time in the interval between establishment of the entity and the explicit disestablishment of the entity. As a rule, the entity is disestablished when execution of the establishing construct completes or is otherwise terminated. Therefore entities with dynamic extent obey a stack-like discipline, paralleling the nested executions of their establishing constructs. Example: the with-open-file construct opens a connection to a file and creates a stream object to represent the connection. The stream object has indefinite extent, but the connection to the open file has dynamic extent: when control exits the with-open-file construct, either normally or abnormally, the stream is automatically closed. Example: the binding of a "special" variable has dynamic extent. * Indefinite extent. The entity continues to exist as long as the possibility of reference remains. (An implementation is free to destroy the entity if it can prove that reference to it is no longer possible. Garbage collection strategies implicitly employ such proofs.) Example: most Common Lisp data objects have indefinite extent. Example: the bindings of lexically scoped parameters of a function have indefinite extent. (By contrast, in Algol the bindings of lexically scoped parameters of a procedure have dynamic extent.) The function definition (defun compose (f g) #'(lambda (x) (funcall f (funcall g x)))) when given two arguments, immediately returns a function as its value. The parameter bindings for f and g do not disappear because the returned function, when called, could still refer to those bindings. Therefore (funcall (compose #'sqrt #'abs) -9.0) produces the value 3.0. (An analogous procedure would not necessarily work correctly in typical Algol implementations or, for that matter, in most Lisp dialects.) In addition to the above terms, it is convenient to define dynamic scope to mean indefinite scope and dynamic extent. Thus we speak of "special" variables as having dynamic scope, or being dynamically scoped, because they have indefinite scope and dynamic extent: a special variable can be referred to anywhere as long as its binding is currently in effect. The term "dynamic scope" is a misnomer. Nevertheless it is both traditional | and useful. | The above definitions do not take into account the possibility of shadowing. Remote reference of entities is accomplished by using names of one kind or another. If two entities have the same name, then the second may shadow the first, in which case an occurrence of the name will refer to the second and cannot refer to the first. In the case of lexical scope, if two constructs that establish entities with the same name are textually nested, then references within the inner construct refer to the entity established by the inner one; the inner one shadows the outer one. Outside the inner construct but inside the outer one, references refer to the entity established by the outer construct. For example: (defun test (x z) (let ((z (* x 2))) (print z)) z) The binding of the variable z by the let construct shadows the parameter binding for the function test. The reference to the variable z in the print form refers to the let binding. The reference to z at the end of the function refers to the parameter named z. In the case of dynamic extent, if the time intervals of two entities overlap, then one interval will necessarily be nested within the other one. This is a property of the design of Common Lisp. . . . . . . . . . . . . . . . . . . . . Implementation note: Behind the assertion that dynamic extents nest properly is the assumption that there is only a single program or process. Common Lisp does not address the problems of multiprogramming (timesharing) or multiprocessing (more than one active processor) within a single Lisp environment. The documentation for implementations that extend Common Lisp for multiprogramming or multiprocessing should be very clear on what modifications are induced by such extensions to the rules of extent and scope. Implementors should note that Common Lisp has been carefully designed to allow special variables to be implemented using either the "deep binding" technique or the "shallow binding" technique, but the two techniques have different semantic and performance implications for multiprogramming and multiprocessing. . . . . . . . . . . . . . . . . . . . . A reference by name to an entity with dynamic extent will always refer to the entity of that name that has been most recently established that has not yet been disestablished. For example: (defun fun1 (x) (catch 'trap (+ 3 (fun2 x)))) (defun fun2 (y) (catch 'trap (* 5 (fun3 y)))) (defun fun3 (z) (throw 'trap z)) Consider the call (fun1 7). The result will be 10. At the time the throw is executed, there are two outstanding catchers with the name trap: one established within procedure fun1, and the other within procedure fun2. The latter is the more recent, and so the value 7 is returned from the catch form in fun2. Viewed from within fun3, the catch in fun2 shadows the one in fun1. Had fun2 been defined as (defun fun2 (y) (catch 'snare (* 5 (fun3 y)))) then the two catchers would have different names, and therefore the one in fun1 would not be shadowed. The result would then have been 7. As a rule, this book simply speaks of the scope or extent of an entity; the possibility of shadowing is left implicit. The important scope and extent rules in Common Lisp follow: * Variable bindings normally have lexical scope and indefinite extent. * Variable bindings for which there is a dynamic-extent declaration also have | lexical scope and indefinite extent, but objects that are the values of such | bindings may have dynamic extent. (The declaration is the programmer's | guarantee that the program will behave correctly even if certain of the data | objects have only dynamic extent rather than the usual indefinite extent.) | | * Bindings of variable names to symbol macros by symbol-macrolet have lexical | scope and indefinite extent. | * Variable bindings that are declared to be special have dynamic scope (indefinite scope and dynamic extent). * Bindings of function names established, for example, by flet and labels have | lexical scope and indefinite extent. | | * Bindings of function names for which there is a dynamic-extent declaration | also have lexical scope and indefinite extent, but function objects that are | the values of such bindings may have dynamic extent. | | * Bindings of function names to macros as established by macrolet have lexical | scope and indefinite extent. | | * Condition handlers and restarts have dynamic scope (see chapter 29). | * A catcher established by a catch or unwind-protect special form has dynamic scope. * An exit point established by a block construct has lexical scope and dynamic extent. (Such exit points are also established by do, prog, and other iteration constructs.) * The go targets established by a tagbody, named by the tags in the tagbody, and referred to by go have lexical scope and dynamic extent. (Such go targets may also appear as tags in the bodies of do, prog, and other iteration constructs.) * Named constants such as nil and pi have indefinite scope and indefinite extent. The rules of lexical scoping imply that lambda-expressions appearing in the function construct will, in general, result in "closures" over those non-special variables visible to the lambda-expression. That is, the function represented by a lambda-expression may refer to any lexically apparent non-special variable and get the correct value, even if the construct that established the binding has been exited in the course of execution. The compose example shown earlier in this chapter provides one illustration of this. The rules also imply that special variable bindings are not "closed over" as they may be in certain other dialects of Lisp. Constructs that use lexical scope effectively generate a new name for each established entity on each execution. Therefore dynamic shadowing cannot occur (though lexical shadowing may). This is of particular importance when dynamic extent is involved. For example: (defun contorted-example (f g x) (if (= x 0) (funcall f) (block here (+ 5 (contorted-example g #'(lambda () (return-from here 4)) (- x 1)))))) Consider the call (contorted-example nil nil 2). This produces the result 4. During the course of execution, there are three calls on contorted-example, interleaved with two establishments of blocks: (contorted-example nil nil 2) (block here1 ...) (contorted-example nil #'(lambda () (return-from here1 4)) 1) (block here2 ...) (contorted-example #'(lambda () (return-from here1 4)) #'(lambda () (return-from here2 4)) 0) (funcall f) ; where f ==> #'(lambda () (return-from here1 4)) (return-from here1 4) At the time the funcall is executed there are two block exit points outstanding, each apparently named here. In the trace above, these exit points are distinguished for expository purposes by subscripts. The return-from form executed as a result of the funcall operation refers to the outer outstanding exit point (here1), not the inner one (here2). This is a consequence of the rules of lexical scoping: it refers to that exit point textually visible at the point of execution of the function construct (here abbreviated by the #' syntax) that resulted in creation of the function object actually invoked by the funcall. If, in this example, one were to change the form (funcall f) to (funcall g), then the value of the call (contorted-example nil nil 2) would be 9. The value would change because the funcall would cause the execution of (return-from here2 4), thereby causing a return from the inner exit point (here2). When that occurs, the value 4 is returned from the middle invocation of contorted-example, 5 is added to that to get 9, and that value is returned from the outer block and the outermost call to contorted-example. The point is that the choice of exit point returned from has nothing to do with its being innermost or outermost; rather, it depends on the lexical scoping information that is effectively packaged up with a lambda-expression when the function construct is executed. This function contorted-example works only because the function named by f is invoked during the extent of the exit point. Block exit points are like non-special variable bindings in having lexical scope, but they differ in having dynamic extent rather than indefinite extent. Once the flow of execution has left the block construct, the exit point is disestablished. For example: (defun illegal-example () (let ((y (block here #'(lambda (z) (return-from here z))))) (if (numberp y) y (funcall y 5)))) One might expect the call (illegal-example) to produce 5 by the following incorrect reasoning: the let statement binds the variable y to the value of the block construct; this value is a function resulting from the lambda-expression. Because y is not a number, it is invoked on the value 5. The return-from should then return this value from the exit point named here, thereby exiting from the block again and giving y the value 5 which, being a number, is then returned as the value of the call to illegal-example. The argument fails only because exit points are defined in Common Lisp to have dynamic extent. The argument is correct up to the execution of the return-from. The execution of the return-from is an error, however, not because it cannot refer to the exit point, but because it does correctly refer to an exit point and that exit point has been disestablished. =============================================================================== 4. <#### Type Specifiers ####> In Common Lisp, types are named by Lisp objects, specifically symbols and lists, called type specifiers. Symbols name predefined classes of objects, whereas lists usually indicate combinations or specializations of simpler types. Symbols or lists may also be abbreviations for types that could be specified in other ways. ------------------------------------------------------------------------------- 4.1. <### Type Specifier Symbols ###> The type symbols defined by the system include those shown in table 4-1. In addition, when a structure type is defined using defstruct, the name of the structure type becomes a valid type symbol. __Notice of correction.__ | In the first edition, the type specifiers signed-byte and unsigned-byte were | inadvertently omitted from table 4-1. | X3J13 voted in March 1989 <17> to eliminate the type common; this fact is | indicated by the brackets around the common type specifier in the table. | | X3J13 voted in March 1989 <11> to eliminate the type string-char; this fact | is indicated by the brackets around the string-char type specifier in the | table. | | X3J13 voted in March 1989 <11> to add the type extended-character and the | type base-character. | | X3J13 voted in March 1989 <151> to add the type specifier real. | | X3J13 votes have also implicitly added many other type specifiers as names of| classes (see chapter 28) or of conditions (see chapter 29). | ............................................................................... Table 4-1: Standard Type Specifier Symbols array fixnum package simple-string atom float pathname simple-vector bignum function random-state single-float bit hash-table ratio standard-char bit-vector integer rational stream character keyword readtable string [common] list sequence [string-char] compiled-function long-float short-float symbol complex nil signed-byte t cons null simple-array unsigned-byte double-float number simple-bit-vector vector X3J13 voted in March 1989 <17> to remove the type common. | X3J13 voted in March 1989 <11> to remove the type string-char. | X3J13 voted in March 1989 <11> to add base-character and extended-character. | X3J13 voted in March 1989 <151> to add the type real. | ............................................................................... ------------------------------------------------------------------------------- 4.2. <### Type Specifier Lists ###> If a type specifier is a list, the car of the list is a symbol, and the rest of the list is subsidiary type information. In many cases a subsidiary item may be unspecified. The unspecified subsidiary item is indicated by writing *. For example, to completely specify a vector type, one must mention the type of the elements and the length of the vector, as for example (vector double-float 100) To leave the length unspecified, one would write (vector double-float *) To leave the element type unspecified, one would write (vector * 100) One may also leave both length and element type unspecified: | (vector * *) | Suppose that two type specifiers are the same except that the first has a * where the second has a more explicit specification. Then the second denotes a subtype of the type denoted by the first. As a convenience, if a list has one or more unspecified items at the end, such items may simply be dropped rather than writing an explicit * for each one. If dropping all occurrences of * results in a singleton list, then the parentheses may be dropped as well (the list may be replaced by the symbol in its car). For example, (vector double-float *) may be abbreviated to (vector double-float), and (vector * *) may be abbreviated to (vector) and then to simply vector. ------------------------------------------------------------------------------- 4.3. <### Predicating Type Specifiers ###> A type specifier list (satisfies predicate-name) denotes the set of all objects that satisfy the predicate named by predicate-name, which must be a symbol whose global function definition is a one-argument predicate. (A name is required; lambda-expressions are disallowed in order to avoid scoping problems.) For example, the type (satisfies numberp) is the same as the type number. The call (typep x '(satisfies p)) results in applying p to x and returning t if the result is true and nil if the result is false. As an example, the type string-char could be defined as : (deftype string-char () : '(and character (satisfies string-char-p))) : See deftype. : X3J13 voted in March 1989 <17> to remove the type string-char and the | function string-char-p from the language. | It is not a good idea for a predicate appearing in a satisfies type specifier to cause any side effects when invoked. ------------------------------------------------------------------------------- 4.4. <### Type Specifiers That Combine ###> The following type specifier lists define a type in terms of other types or objects. (member object1 object2 ...) This denotes the set containing precisely those objects named. An object is of this type if and only if it is eql to one of the specified objects. . . . . . . . . . . . . . . . . . . . . Compatibility note: This is roughly equivalent to the Interlisp DECL package's memq. . . . . . . . . . . . . . . . . . . . . (eql object) | X3J13 voted in June 1988 <12> to add the eql type specifier. It may be used | as a parameter specializer for CLOS methods (see section 28.1.6.2 and | find-method). It denotes the set of the one object named; an object is of | this type if and only if it is eql to object. While (eql object) denotes the| same type as (member object), only (eql object) may be used as a CLOS | parameter specializer. | (not type) This denotes the set of all those objects that are not of the specified type. (and type1 type2 ...) This denotes the intersection of the specified types. . . . . . . . . . . . . . . . . . . . . Compatibility note: This is roughly equivalent to the Interlisp DECL package's allof. . . . . . . . . . . . . . . . . . . . . When typep processes an and type specifier, it always tests each of the component types in order from left to right and stops processing as soon as one component of the intersection has been found to which the object in question does not belong. In this respect an and type specifier is similar to an executable and form. The purpose of this similarity is to allow a satisfies type specifier to depend on filtering by previous type specifiers. For example, suppose there were a function primep that takes an integer and says whether it is prime. Suppose also that it is an error to give any object other than an integer to primep. Then the type specifier (and integer (satisfies primep)) is guaranteed never to result in an error because the function primep will not be invoked unless the object in question has already been determined to be an integer. (or type1 type2 ...) This denotes the union of the specified types. For example, the type list by definition is the same as (or null cons). Also, the value returned by the function position is always of type (or null (integer 0 *)) (either nil or a non-negative integer). . . . . . . . . . . . . . . . . . . . . Compatibility note: This is roughly equivalent to the Interlisp DECL package's oneof. . . . . . . . . . . . . . . . . . . . . As for and, when typep processes an or type specifier, it always tests each of the component types in order from left to right and stops processing as soon as one component of the union has been found to which the object in question belongs. ------------------------------------------------------------------------------- 4.5. <### Type Specifiers That Specialize ###> Some type specifier lists denote specializations of data types named by symbols. These specializations may be reflected by more efficient representations in the underlying implementation. As an example, consider the type (array short-float). Implementation A may choose to provide a specialized representation for arrays of short floating-point numbers, and implementation B may choose not to. If you should want to create an array for the express purpose of holding only short-float objects, you may optionally specify to make-array the element type short-float. This does not require make-array to create an object of type (array short-float); it merely permits it. The request is construed to mean "Produce the most specialized array representation capable of holding short-floats that the implementation can provide." Implementation A will then produce a specialized array of type (array short-float), and implementation B will produce an ordinary array of type (array t). If one were then to ask whether the array were actually of type (array short-float), implementation A would say "yes," but implementation B would say "no." This is a property of make-array and similar functions: what you ask for is not necessarily what you get. Types can therefore be used for two different purposes: declaration and : discrimination. Declaring to make-array that elements will always be of type : short-float permits optimization. Similarly, declaring that a variable takes : on values of type (array short-float) amounts to saying that the variable will : take on values that might be produced by specifying element type short-float to: make-array. On the other hand, if the predicate typep is used to test whether : an object is of type (array short-float), only objects actually of that : specialized type can satisfy the test; in implementation B no object can pass : that test. : X3J13 voted in January 1989 <8> to eliminate the differing treatment of types| when used "for discrimination" rather than "for declaration" on the grounds | that implementors have not treated the distinction consistently and (which is | more important) users have found the distinction confusing. | | As a consequence of this change, the behavior of typep and subtypep on array | and complex type specifiers must be modified. See the descriptions of those | functions. In particular, under their new behavior, implementation B would say| "yes," agreeing with implementation A, in the discussion above. | | Note that the distinction between declaration and discrimination remains | useful, if only so that we may remark that the specialized (list) form of the | function type specifier may still be used only for declaration and not for | discrimination. | X3J13 voted in June 1988 <90> to clarify that while the specialized form of | the function type specifier (a list of the symbol function possibly followed by| argument and value type specifiers) may be used only for declaration, the | symbol form (simply the name function) may be used for discrimination. | The valid list-format names for data types are as follows: (array element-type dimensions) This denotes the set of specialized arrays whose elements are all members of the type element-type and whose dimensions match dimensions. For declaration purposes, this type encompasses those arrays that can result by specifying element-type as the element type to the function make-array; this may be different from what the type means for discrimination purposes. element-type must be a valid type specifier or unspecified. dimensions may be a non-negative integer, which is the number of dimensions, or it may be a list of non-negative integers representing the length of each dimension (any dimension may be unspecified instead), or it may be unspecified. For example: (array integer 3) ; Three-dimensional arrays of integers (array integer (* * *)) ; Three-dimensional arrays of integers (array * (4 5 6)) ; 4-by-5-by-6 arrays (array character (3 *)) ; Two-dimensional arrays of characters ; that have exactly three rows (array short-float ()) ; Zero-rank arrays of short-format ; floating-point numbers Note that (array t) is a proper subset of (array *). The reason is that (array t) is the set of arrays that can hold any Common Lisp object (the elements are of type t, which includes all objects). On the other hand, (array *) is the set of all arrays whatsoever, including, for example, arrays that can hold only characters. Now (array character) is not a subset of (array t); the two sets are in fact disjoint because (array character) is not the set of all arrays that can hold characters but rather the set of arrays that are specialized to hold precisely characters and no other objects. To test whether an array foo can hold a character, one should not use (typep foo '(array character)) but rather (subtypep 'character (array-element-type foo)) See array-element-type. X3J13 voted in January 1989 <8> to change typep and subtypep so that the | specialized array type specifier means the same thing for discrimination as | for declaration: it encompasses those arrays that can result by specifying | element-type as the element type to the function make-array. Under this | interpretation (array character) might be the same type as (array t) | (although it also might not be the same). See upgraded-array-element-type. | However, | (typep foo '(array character)) | is still not a legitimate test of whether the array foo can hold a character;| one must still say | (subtypep 'character (array-element-type foo)) | to determine that question. | X3J13 also voted in January 1989 <43> to specify that within the lexical | scope of an array type declaration, it is an error for an array element, when| referenced, not to be of the exact declared element type. A compiler may, | for example, treat every reference to an element of a declared array as if | the reference were surrounded by a the form mentioning the declared array | element type (not the upgraded array element type). Thus | (defun snarf-hex-digits (the-array) | (declare (type (array (unsigned-byte 4) 1) the-array)) | (do ((j (- (length array) 1) (- j 1)) | (val 0 (logior (ash val 4) | (aref the-array j)))) | ((< j 0) val))) | may be treated as | (defun snarf-hex-digits (the-array) | (declare (type (array (unsigned-byte 4) 1) the-array)) | (do ((j (- (length array) 1) (- j 1)) | (val 0 (logior (ash val 4) | (the (unsigned-byte 4) | (aref the-array j))))) | ((< j 0) val))) | The declaration amounts to a promise by the user that the aref will never | produce a value outside the interval 0 to 15, even if in that particular | implementation the array element type (unsigned-byte 4) is upgraded to, say, | (unsigned-byte 8). If such upgrading does occur, then values outside that | range may in fact be stored in the-array, as long as the code in | snarf-hex-digits never sees them. | As a general rule, a compiler would be justified in transforming | (aref (the (array elt-type ...) a) ...) | into | (the elt-type (aref (the (array elt-type ...) a) ...) | It may also make inferences involving more complex functions, such as | position or find. For example, find applied to an array always returns | either nil or an object whose type is the element type of the array. | (simple-array element-type dimensions) This is equivalent to (array element-type dimensions) except that it additionally specifies that objects of the type are simple arrays (see section 2.5). (vector element-type size) This denotes the set of specialized one-dimensional arrays whose elements are all of type element-type and whose lengths match size. This is entirely equivalent to (array element-type (size)). For example: (vector double-float) ; Vectors of double-format ; floating-point numbers (vector * 5) ; Vectors of length 5 (vector t 5) ; General vectors of length 5 (vector (mod 32) *) ; Vectors of integers between 0 and 31 The specialized types (vector string-char) and (vector bit) are so useful : that they have the special names string and bit-vector. Every implementation: of Common Lisp must provide distinct representations for these as distinct : specialized data types. : X3J13 voted in March 1989 <11> to eliminate the type string-char and to | redefine the type string to be the union of one or more specialized vector | types, the types of whose elements are subtypes of the type character. | (simple-vector size) This is the same as (vector t size) except that it additionally specifies that its elements are simple general vectors. (complex type) Every element of this type is a complex number whose real part and imaginary part are each of type type. For declaration purposes, this type encompasses those complex numbers that can result by giving numbers of the specified type to the function complex; this may be different from what the type means for discrimination purposes. As an example, Gaussian integers might be described as (complex integer), even in implementations where giving two integers to the function complex results in an object of type (complex rational). X3J13 voted in January 1989 <8> to change typep and subtypep so that the | specialized complex type specifier means the same thing for discrimination | purposes as for declaration purposes. See upgraded-complex-part-type. | (function (arg1-type arg2-type ...) value-type) This type may be used only for declaration and not for discrimination; typep will signal an error if it encounters a specifier of this form. Every element of this type is a function that accepts arguments at least of the types specified by the argj-type forms and returns a value that is a member of the types specified by the value-type form. The &optional, &rest, and &key markers may appear in the list of argument types. The value-type may be a values type specifier in order to indicate the types of multiple values. X3J13 voted in January 1989 <93> to specify that the arg-type that follows a | &rest marker indicates the type of each actual argument that would be | gathered into the list for a &rest parameter, and not the type of the &rest | parameter itself (which is always list). Thus one might declare the function| gcd to be of type (function (&rest integer) integer), or the function aref to| be of type (function (array fixnum) t). | X3J13 voted in March 1988 <92> to specify that, in a function type specifier,| an argument type specifier following &key must be a list of two items, a | keyword and a type specifier. The keyword must be a valid keyword-name | symbol that may be supplied in the actual arguments of a call to the | function, and the type specifier indicates the permitted type of the | corresponding argument value. (The keyword-name symbol is typically a | keyword, but another X3J13 vote <105> allows it to be any symbol.) | Furthermore, if &allow-other-keys is not present, the set of keyword-names | mentioned in the function type specifier may be assumed to be exhaustive; for| example, a compiler would be justified in issuing a warning for a function | call using a keyword argument name not mentioned in the type declaration for | the function being called. If &allow-other-keys is present in the function | type specifier, other keyword arguments may be supplied when calling a | function of the indicated type, and if supplied such arguments may possibly | be used. | As an example, the function cons is of type (function (t t) cons), because it: can accept any two arguments and always returns a cons. The function cons is: also of type (function (float string) list), because it can certainly accept : a floating-point number and a string (among other things), and its result is : always of type list (in fact a cons is never null, but that does not matter : for this type declaration). The function truncate is of type (function : (number number) (values number number)), as well as of type (function : (integer (mod 8)) integer). : X3J13 voted in January 1989 <91> to alter the meaning of the function type | specifier when used in type and ftype declarations. While the preceding | formulation may be theoretically elegant, they have found that it is not | useful to compiler implementors and that it is not the interpretation that | users expect. X3J13 prescribed instead the following interpretation of | declarations. | A declaration specifier of the form | (ftype (function (arg1-type arg2-type ... argn-type) value-type) fname) | implies that any function call of the form | (fname arg1 arg2 ...) | within the scope of the declaration can be treated as if it were rewritten to| use the-forms in the following manner: | (the value-type | (fname (the arg1-type arg1) | (the arg2-type arg2) | ... | (the argn-type argn))) | That is, it is an error for any of the actual arguments not to be of its | specified type arg-type or for the result not to be of the specified type | value-type. (In particular, if any argument is not of its specified type, | then the result is not guaranteed to be of the specified type -- if indeed a | result is returned at all.) | Similarly, a declaration specifier of the form | (type (function (arg1-type arg2-type ... argn-type) value-type) var) | is interpreted to mean that any reference to the variable var will find that | its value is a function, and that it is an error to call this function with | any actual argument not of its specified type arg-type. Also, it is an error| for the result not to be of the specified type value-type. For example, a | function call of the form | (funcall var arg1 arg2 ...) | could be rewritten to use the-forms as well. If any argument is not of its | specified type, then the result is not guaranteed to be of the specified type| -- if indeed a result is returned at all. | Thus, a type or ftype declaration specifier describes type requirements | imposed on calls to a function as opposed to requirements imposed on the | definition of the function. This is analogous to the treatment of type | declarations of variables as imposing type requirements on references to | variables, rather than on the contents of variables. See the vote of X3J13 | on type declaration specifiers in general, discussed in section 9.2. | In the same manner as for variable type declarations in general, if two or | more of these declarations apply to the same function call (which can occur | if declaration scopes are suitably nested), then they all apply; in effect, | the types for each argument or result are intersected. For example, the code| fragment | (locally (declare (ftype (function (biped) digit) | butcher-fudge)) | (locally (declare (ftype (function (featherless) opposable) | butcher-fudge)) | (butcher-fudge sam))) | may be regarded as equivalent to | (the opposable | (the digit (butcher-fudge (the featherless | (the biped sam))))) | or to | (the (and opposable digit) | (butcher-fudge (the (and featherless biped) sam))) | That is, sam had better be both featherless and a biped, and the result of | butcher-fudge had better be both opposable and a digit; otherwise the code is| in error. Therefore a compiler may generate code that relies on these type | assumptions, for example. | (values value1-type value2-type ...) This type specifier is extremely restricted: it may be used only as the value-type in a function type specifier or in a the special form. It is used to specify individual types when multiple values are involved. The &optional, &rest, and &key markers may appear in the value-type list; they thereby indicate the parameter list of a function that, when given to multiple-value-call along with the values, would be suitable for receiving those values. ------------------------------------------------------------------------------- 4.6. <### Type Specifiers That Abbreviate ###> The following type specifiers are, for the most part, abbreviations for other type specifiers that would be far too verbose to write out explicitly (using, for example, member). (integer low high) Denotes the integers between low and high. The limits low and high must each be an integer, a list of an integer, or unspecified. An integer is an inclusive limit, a list of an integer is an exclusive limit, and * means that a limit does not exist and so effectively denotes minus or plus infinity, respectively. The type fixnum is simply a name for (integer smallest largest) for implementation-dependent values of smallest and largest (see most-negative-fixnum and most-positive-fixnum). The type (integer 0 1) is so useful that it has the special name bit. (mod n) Denotes the set of non-negative integers less than n. This is equivalent to (integer 0 n-1) or to (integer 0 (n)). (signed-byte s) Denotes the set of integers that can be represented in two's-complement form in a byte of s bits. This is equivalent to (integer -2^(s-1) 2^(s-1)-1). Simply signed-byte or (signed-byte *) is the same as integer. (unsigned-byte s) Denotes the set of non-negative integers that can be represented in a byte of s bits. This is equivalent to (mod 2^s), that is, (integer 0 2^s-1). Simply unsigned-byte or (unsigned-byte *) is the same as (integer 0 *), the set of non-negative integers. (rational low high) Denotes the rationals between low and high. The limits low and high must each be a rational, a list of a rational, or unspecified. A rational is an inclusive limit, a list of a rational is an exclusive limit, and * means that a limit does not exist and so effectively denotes minus or plus infinity, respectively. (float low high) Denotes the set of floating-point numbers between low and high. The limits low and high must each be a floating-point number, a list of a floating-point number, or unspecified; a floating-point number is an inclusive limit, a list of a floating-point number is an exclusive limit, and * means that a limit does not exist and so effectively denotes minus or plus infinity, respectively. In a similar manner, one may use: (short-float low high) (single-float low high) (double-float low high) (long-float low high) In this case, if a limit is a floating-point number (or a list of one), it must be one of the appropriate format. X3J13 voted in March 1989 <151> to add a list form of the real type specifier| to denote an interval of real numbers. | | (real low high) | Denotes the real numbers between low and high. The limits low and high must | each be a real, a list of a real, or unspecified. A real is an inclusive | limit, a list of a real is an exclusive limit, and * means that a limit does | not exist and so effectively denotes minus or plus infinity, respectively. | (string size) : Means the same as (array string-char (size)): the set of strings of the : indicated size. : : (simple-string size) : Means the same as (simple-array string-char (size)): the set of simple : strings of the indicated size. : X3J13 voted in March 1989 <11> to eliminate the type string-char and to | redefine the type string to be the union of one or more specialized vector | types, the types of whose elements are subtypes of the type character. | Similarly, the type simple-string is redefined to be the union of one or more | specialized simple vector types, the types of whose elements are subtypes of | the type character. | | (base-string size) | Means the same as (vector base-character size): the set of base strings of | the indicated size. | | (simple-base-string size) | Means the same as (simple-array base-character (size)): the set of simple | base strings of the indicated size. | (bit-vector size) Means the same as (array bit (size)): the set of bit-vectors of the indicated size. (simple-bit-vector size) This means the same as (simple-array bit (size)): the set of bit-vectors of the indicated size. ------------------------------------------------------------------------------- 4.7. <### Defining New Type Specifiers ###> New type specifiers can come into existence in two ways. First, defining a new structure type with defstruct automatically causes the name of the structure to be a new type specifier symbol. Second, the deftype special form can be used to define new type-specifier abbreviations. ---------<<>> deftype deftype name lambda-list [[ {declaration}* | doc-string ]] {form}* This is very similar to a defmacro form: name is the symbol that identifies the type specifier being defined, lambda-list is a lambda-list (and may contain &optional and &rest markers), and the forms constitute the body of the expander function. If we view a type specifier list as a list containing the type specifier name and some argument forms, the argument forms (unevaluated) are bound to the corresponding parameters in lambda-list. Then the body forms are evaluated as an implicit progn, and the value of the last form is interpreted as a new type specifier for which the original specifier was an abbreviation. The name is returned as the value of the deftype form. deftype differs from defmacro in that if no initform is specified for an &optional parameter, the default value is *, not nil. If the optional documentation string doc-string is present, then it is attached to the name as a documentation string of type type; see documentation. Here are some examples of the use of deftype: (deftype mod (n) `(integer 0 (,n))) (deftype list () '(or null cons)) (deftype square-matrix (&optional type size) "SQUARE-MATRIX includes all square two-dimensional arrays." `(array ,type (,size ,size))) (square-matrix short-float 7) ; means (array short-float (7 7)) (square-matrix bit) ; means (array bit (* *)) If the type name defined by deftype is used simply as a type specifier symbol, it is interpreted as a type specifier list with no argument forms. Thus, in the example above, square-matrix would mean (array * (* *)), the set of two-dimensional arrays. This would unfortunately fail to convey the constraint that the two dimensions be the same; (square-matrix bit) has the same problem. A better definition is (defun equidimensional (a) (or (< (array-rank a) 2) (apply #'= (array-dimensions a)))) (deftype square-matrix (&optional type size) `(and (array ,type (,size ,size)) (satisfies equidimensional))) X3J13 voted in March 1988 <78> to specify that the body of the expander | function defined by deftype is implicitly enclosed in a block construct whose | name is the same as the name of the defined type. Therefore return-from may be| used to exit from the function. | X3J13 voted in March 1989 <50> to clarify that, while defining forms normally| appear at top level, it is meaningful to place them in non-top-level contexts; | deftype must define the expander function within the enclosing lexical | environment, not within the global environment. ------------------------------------------------------------------------------- 4.8. <### Type Conversion Function ###> The following function may be used to convert an object to an equivalent object of another type. ---------<<>> coerce coerce object result-type The result-type must be a type specifier; the object is converted to an "equivalent" object of the specified type. If the coercion cannot be performed, then an error is signaled. In particular, (coerce x 'nil) always signals an error. If object is already of the specified type, as determined by typep, then it is simply returned. It is not generally possible to convert any object to be of any type whatsoever; only certain conversions are permitted: * Any sequence type may be converted to any other sequence type, provided the new sequence can contain all actual elements of the old sequence (it is an error if it cannot). If the result-type is specified as simply array, for example, then (array t) is assumed. A specialized type such as string or (vector (complex short-float)) may be specified; of course, the result may be of either that type or some more general type, as determined by the implementation. Elements of the new sequence will be eql to corresponding elements of the old sequence. If the sequence is already of the specified type, it may be returned without copying it; in this, (coerce sequence type) differs from (concatenate type sequence), for the latter is required to copy the argument sequence. In particular, if one specifies sequence, then the argument may simply be returned if it already is a sequence. (coerce '(a b c) 'vector) ==> #(a b c) X3J13 voted in June 1989 <158> to specify that coerce should signal an error | if the new sequence type specifies the number of elements and the old sequence | has a different length. | X3J13 voted in March 1989 <11> to specify that if the result-type is string | then it is understood to mean (vector character), and simple-string is | understood to mean (simple-array character (*)). | * Some strings, symbols, and integers may be converted to characters. If : object is a string of length 1, then the sole element of the string is : returned. If object is a symbol whose print name is of length 1, then the : sole element of the print name is returned. If object is an integer n, then : (int-char n) is returned. See character. : (coerce "a" 'character) ==> #\a : X3J13 voted in March 1989 <11> to eliminate int-char from Common Lisp. | Presumably this eliminates the possibility of coercing an integer to a | character, although the vote did not address this question directly. | * Any non-complex number can be converted to a short-float, single-float, double-float, or long-float. If simply float is specified, and object is not already a float of some kind, then the object is converted to a single-float. (coerce 0 'short-float) ==> 0.0S0 (coerce 3.5L0 'float) ==> 3.5L0 (coerce 7/2 'float) ==> 3.5 * Any number can be converted to a complex number. If the number is not already complex, then a zero imaginary part is provided by coercing the integer zero to the type of the given real part. (If the given real part is rational, however, then the rule of canonical representation for complex rationals will result in the immediate re-conversion of the result from type complex back to type rational.) (coerce 4.5s0 'complex) ==> #C(4.5S0 0.0S0) (coerce 7/2 'complex) ==> 7/2 (coerce #C(7/2 0) '(complex double-float)) ==> #C(3.5D0 0.0D0) * Any object may be coerced to type t. (coerce x 't) == (identity x) == x X3J13 voted in June 1988 <90> to allow coercion of certain objects to the | type function: | | * A symbol or lambda-expression can be converted to a function. A symbol is | coerced to type function as if by applying symbol-function to the symbol; an | error is signaled if the predicate fboundp is not true of the symbol or if | the symbol names a macro or special form. A list x whose car is the symbol | lambda is coerced to a function as if by execution of (eval `#',x), that is, | of (eval (list 'function x)). | Coercions from floating-point numbers to rationals and from ratios to integers are purposely not provided because of rounding problems. The functions rational, rationalize, floor, ceiling, truncate, and round may be used for such purposes. Similarly, coercions from characters to integers are purposely not provided; char-code or char-int may be used explicitly to perform such conversions. ------------------------------------------------------------------------------- 4.9. <### Determining the Type of an Object ###> The following function may be used to obtain a type specifier describing the type of a given object. ---------<<>> type-of type-of object (type-of object) returns an implementation-dependent result: some type of : which the object is a member. Implementors are encouraged to arrange for : type-of to return the most specific type that can be conveniently computed and : is likely to be useful to the user. If the argument is a user-defined named : structure created by defstruct, then type-of will return the type name of that : structure. Because the result is implementation-dependent, it is usually : better to use type-of primarily for debugging purposes; however, in a few : situations portable code requires the use of type-of, such as when the result : is to be given to the coerce or map function. On the other hand, often the : typep function or the typecase construct is more appropriate than type-of. : . . . . . . . . . . . . . . . . . . . . Compatibility note: In MacLisp the function type-of is called typep, and anomalously so, for it is not a predicate. . . . . . . . . . . . . . . . . . . . . Many have observed (and rightly so) that this specification is totally wimpy | and therefore nearly useless. X3J13 voted in June 1989 <179> to place the | following constraints on type-of: | | * Let x be an object such that (typep x type) is true and type is one of the | following: | array float package sequence | bit-vector function pathname short-float | character hash-table random-state single-float | complex integer ratio stream | condition long-float rational string | cons null readtable symbol | double-float number restart vector | Then (subtypep (type-of x) type)) must return the values t and t; that is, | type-of applied to x must return either type itself or a subtype of type that| subtypep can recognize in that implementation. | | * For any object x, (subtypep (type-of x) (class-of x)) must produce the values| t and t. | | * For every object x, (typep x (type-of x)) must be true. (This implies that | type-of can never return nil, for no object is of type nil.) | | * type-of never returns t and never uses a satisfies, and, or, not, or values | type specifier in its result. | | * For objects of CLOS metaclass structure-class or of standard-class, type-of | returns the proper name of the class returned by class-of if it has a proper | name, and otherwise returns the class itself. In particular, for any object | created by a defstruct constructor function, where the defstruct had the name| name and no :type option, type-of will return name. | | As an example, (type-of "acetylcholinesterase") may return string or | simple-string or (simple-string 20), but not array or simple-vector. As | another example, it is permitted for (type-of 1729) to return integer or fixnum| (if it is indeed a fixnum) or (signed-byte 16) or (integer 1729 1729) or | (integer 1685 1750) or even (mod 1730), but not rational or number, because | (typep (+ (expt 9 3) (expt 10 3)) 'integer) | is true, integer is in the list of types mentioned above, and | (subtypep (type-of (+ (expt 1 3) (expt 12 3))) 'integer) | would be false if type-of were to return rational or number. | ------------------------------------------------------------------------------- 4.10. <### Type Upgrading ###> | | X3J13 voted in January 1989 <8> to add new functions by which a program can | determine, in a given Common Lisp implementation, how that implementation will | upgrade a type when constructing an array specialized to contain elements of | that type, or a complex number specialized to contain parts of that type. | | ---------<<>> upgraded-array-element-type | upgraded-array-element-type type | | A type specifier is returned, indicating the element type of the most | specialized array representation capable of holding items of the specified | argument type. The result is necessarily a supertype of the given type. | Furthermore, if a type A is a subtype of type B, then | (upgraded-array-element-type A) is a subtype of | (upgraded-array-element-type B). | | The manner in which an array element type is upgraded depends only on the | element type as such and not on any other property of the array such as size, | rank, adjustability, presence or absence of a fill pointer, or displacement. | | . . . . . . . . . . . . . . . . . . . . | Rationale: If upgrading were allowed to depend on any of these properties, all | of which can be referred to, directly or indirectly, in the language of type | specifiers, then it would not be possible to displace an array in a | consistent and dependable manner to another array created with the same | :element-type argument but differing in one of these properties. | . . . . . . . . . . . . . . . . . . . . | | Note that upgraded-array-element-type could be defined as | (defun upgraded-array-element-type (type) | (array-element-type (make-array 0 :element-type type))) | but this definition has the disadvantage of allocating an array and then | immediately discarding it. The clever implementor surely can conjure up a more| practical approach. | | ---------<<>> upgraded-complex-part-type | upgraded-complex-part-type type | | A type specifier is returned, indicating the element type of the most | specialized complex number representation capable of having parts of the | specified argument type. The result is necessarily a supertype of the given | type. Furthermore, if a type A is a subtype of type B, then | (upgraded-complex-part-type A) is a subtype of (upgraded-complex-part-type B). | =============================================================================== 5. <#### Program Structure ####> In chapter 2 the syntax was sketched for notating data objects in Common Lisp. The same syntax is used for notating programs because all Common Lisp programs have a representation as Common Lisp data objects. Lisp programs are organized as forms and functions. Forms are evaluated (relative to some context) to produce values and side effects. Functions are invoked by applying them to arguments. The most important kind of form performs a function call; conversely, a function performs computation by evaluating forms. In this chapter, forms are discussed first and then functions. Finally, certain "top level" special forms are discussed; the most important of these is defun, whose purpose is to define a named function. ------------------------------------------------------------------------------- 5.1. <### Forms ###> The standard unit of interaction with a Common Lisp implementation is the form, which is simply a data object meant to be evaluated as a program to produce one or more values (which are also data objects). One may request evaluation of any data object, but only certain ones are meaningful. For instance, symbols and lists are meaningful forms, while arrays normally are not. Examples of meaningful forms are 3, whose value is 3, and (+ 3 4), whose value is 7. We write 3 ==> 3 and (+ 3 4) ==> 7 to indicate these facts. (==> means "evaluates to.") Meaningful forms may be divided into three categories: self-evaluating forms, such as numbers; symbols, which stand for variables; and lists. The lists in turn may be divided into three categories: special forms, macro calls, and function calls. Any Common Lisp data object not explicitly defined here to be a valid form is: not a valid form. It is an error to evaluate anything but a valid form. : : . . . . . . . . . . . . . . . . . . . . : Implementation note: An implementation is free to make implementation-dependent: extensions to the evaluator but is strongly encouraged to signal an error on : any attempt to evaluate anything but a valid form or an object for which a : meaningful evaluation extension has been purposely defined. : . . . . . . . . . . . . . . . . . . . . : X3J13 voted in October 1988 <72> to specify that all standard Common Lisp | data objects other than symbols and lists (including defstruct structures | defined without the :type option) are self-evaluating. | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.1. <## Self-Evaluating Forms ##> All numbers, characters, strings, and bit-vectors are self-evaluating forms. When such an object is evaluated, that object (or possibly a copy in the case of numbers or characters) is returned as the value of the form. The empty list (), which is also the false value nil, is also a self-evaluating form: the value of nil is nil. Keywords (symbols written with a leading colon) also evaluate to themselves: the value of :start is :start. X3J13 voted in January 1989 <36> to clarify that it is an error to | destructively modify any object that appears as a constant in executable code, | whether as a self-evaluating form or within a quote special form. | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.2. <## Variables ##> Symbols are used as names of variables in Common Lisp programs. When a symbol is evaluated as a form, the value of the variable it names is produced. For example, after doing (setq items 3), which assigns the value 3 to the variable named items, then items ==> 3. Variables can be assigned to, as by setq, or bound, as by let. Any program construct that binds a variable effectively saves the old value of the variable and causes it to have a new value, and on exit from the construct the old value is reinstated. There are actually two kinds of variables in Common Lisp, called lexical (or static) variables and special (or dynamic) variables. At any given time either or both kinds of variable with the same name may have a current value. Which of the two kinds of variable is referred to when a symbol is evaluated depends on the context of the evaluation. The general rule is that if the symbol occurs textually within a program construct that creates a binding for a variable of the same name, then the reference is to the variable specified by the binding; if no such program construct textually contains the reference, then it is taken to refer to the special variable of that name. The distinction between the two kinds of variable is one of scope and extent. A lexically bound variable can be referred to only by forms occurring at any place textually within the program construct that binds the variable. A dynamically bound (special) variable can be referred to at any time from the time the binding is made until the time evaluation of the construct that binds the variable terminates. Therefore lexical binding of variables imposes a spatial limitation on occurrences of references (but no temporal limitation, for the binding continues to exist as long as the possibility of reference remains). Conversely, dynamic binding of variables imposes a temporal limitation on occurrences of references (but no spatial limitation). For more information on scope and extent, see chapter <3>. The value a special variable has when there are currently no bindings of that variable is called the global value of the (special) variable. A global value can be given to a variable only by assignment, because a value given by binding is by definition not global. It is possible for a special variable to have no value at all, in which case it is said to be unbound. By default, every global variable is unbound unless and until explicitly assigned a value, except for those global variables defined in this book or by the implementation already to have values when the Lisp system is first started. It is also possible to establish a binding of a special variable and then cause that binding to be valueless by using the function makunbound. In this situation the variable is also said to be "unbound," although this is a misnomer; precisely speaking, it is bound but valueless. It is an error to refer to a variable that is unbound. X3J13 voted in June 1989 <180> to specify more precisely the effects of | referring to an unbound variable. | | Reading an unbound variable or an undefined function must be detected in the | highest safety setting (see the safety quality of the optimize declaration | specifier) but the effect is undefined in any other safety setting. That is, | reading an unbound variable should signal an error and reading an undefined | function should signal an error. ("Reading a function" includes both | references to the function using the function special form, such as f in | (function f), and references to the function in a call, such as f in (f x y).) | | For the case of inline functions (in implementations where they are | supported), a permitted point of view is that performing the inlining | constitutes the read of the function, so that an fboundp check need not be done| at execution time. Put another way, the effect of the application of | fmakunbound to a function name on potentially inlined references to that | function is undefined. | | When an unbound variable is detected an error of type unbound-variable is | signaled, and the name slot of the unbound-variable condition is initialized to| the name of the offending variable. | | When an undefined function is detected an error of type undefined-function is| signaled, and the name slot of the undefined-function condition is initialized | to the name of the offending function. | | The condition type unbound-slot, which inherits from cell-error, has an | additional slot instance, which can be initialized using the :instance keyword | to make-condition. The function unbound-slot-instance accesses this slot. | | The type of error signaled by the default primary method for the CLOS | slot-unbound generic function is unbound-slot. The instance slot of the | unbound-slot condition is initialized to the offending instance and the name | slot is initialized to the name of the offending variable. | Certain global variables are reserved as "named constants." They have a global value and may not be bound or assigned to. For example, the symbols t and nil are reserved. One may not assign a value to t or nil, and one may not bind t or nil. The global value of t is always t, and the global value of nil is always nil. Constant symbols defined by defconstant also become reserved and may not be further assigned to or bound (although they may be redefined, if necessary, by using defconstant again). Keyword symbols, which are notated with a leading colon, are reserved and may never be assigned to or bound; a keyword always evaluates to itself. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.3. <## Special Forms ##> If a list is to be evaluated as a form, the first step is to examine the first element of the list. If the first element is one of the symbols appearing in table 5-1, then the list is called a special form. (This use of the word "special" is unrelated to its use in the phrase "special variable.") Special forms are generally environment and control constructs. Every special form has its own idiosyncratic syntax. An example is the if special form: (if p (+ x 4) 5) in Common Lisp means what "if p then x+4 else 5" means in Algol. The evaluation of a special form normally produces a value or values, but the evaluation may instead call for a non-local exit; see return-from, go, and throw. The set of special forms is fixed in Common Lisp; no way is provided for the user to define more. The user can create new syntactic constructs, however, by defining macros. The set of special forms in Common Lisp is purposely kept very small because any program-analyzing program must have special knowledge about every type of special form. Such a program needs no special knowledge about macros because it is simple to expand the macro and operate on the resulting expansion. (This is not to say that many such programs, particularly compilers, will not have such special knowledge. A compiler may be able to produce much better code if it recognizes such constructs as typecase and multiple-value-bind and gives them customized treatment.) ............................................................................... Table 5-1: Names of All Common Lisp Special Forms block if progv catch labels quote [compiler-let] let return-from declare let* setq eval-when macrolet tagbody flet multiple-value-call the function multiple-value-prog1 throw go progn unwind-protect X3J13 voted in June 1989 <25> to remove compiler-let from the language. | X3J13 voted in June 1988 <12> to add the special forms generic-flet, | generic-labels, symbol-macrolet, and with-added-methods. | X3J13 voted in March 1989 <113> to make locally a special form rather than a | macro. | X3J13 voted in March 1989 <111> to add the special form load-time-eval. | ............................................................................... An implementation is free to implement as a macro any construct described herein as a special form. Conversely, an implementation is free to implement as a special form any construct described herein as a macro if an equivalent macro definition is also provided. The practical consequence is that the predicates macro-function and special-form-p may both be true of the same symbol. It is recommended that a program-analyzing program process a form that is a list whose car is a symbol as follows: 1. If the program has particular knowledge about the symbol, process the form using special-purpose code. All of the symbols listed in table 5-1 should fall into this category. 2. Otherwise, if macro-function is true of the symbol, apply either macroexpand or macroexpand-1, as appropriate, to the entire form and then start over. 3. Otherwise, assume it is a function call. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.4. <## Macros ##> If a form is a list and the first element is not the name of a special form, it may be the name of a macro; if so, the form is said to be a macro call. A macro is essentially a function from forms to forms that will, given a call to that macro, compute a new form to be evaluated in place of the macro call. (This computation is sometimes referred to as macro expansion.) For example, the macro named return will take a form such as (return x) and from that form compute a new form (return-from nil x). We say that the old form expands into the new form. The new form is then evaluated in place of the original form; the value of the new form is returned as the value of the original form. X3J13 voted in January 1989 <67> to clarify that macro calls, and subforms of| macro calls, need not be proper lists, but that use of dotted forms requires | the macro definition to use ". var" or "&rest var" in order to match them | properly. It is then the responsibility of the macro definition to recognize | and appropriately handle such dotted forms or subforms. | There are a number of standard macros in Common Lisp, and the user can define more by using defmacro. Macros provided by a Common Lisp implementation as described herein may expand into code that is not portable among differing implementations. That is, a macro call may be implementation-independent because the macro is defined in this book, but the expansion need not be. . . . . . . . . . . . . . . . . . . . . Implementation note: Implementors are encouraged to implement the macros defined in this book, as far as is possible, in such a way that the expansion will not contain any implementation-dependent special forms, nor contain as forms data objects that are not considered to be forms in Common Lisp. The purpose of this restriction is to ensure that the expansion can be processed by a program-analyzing program in an implementation-independent manner. There is no problem with a macro expansion containing calls to implementation-dependent functions. This restriction is not a requirement of Common Lisp; it is recognized that certain complex macros may be able to expand into significantly more efficient code in certain implementations by using implementation-dependent special forms in the macro expansion. . . . . . . . . . . . . . . . . . . . . - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.1.5. <## Function Calls ##> If a list is to be evaluated as a form and the first element is not a symbol that names a special form or macro, then the list is assumed to be a function call. The first element of the list is taken to name a function. Any and all remaining elements of the list are forms to be evaluated; one value is obtained from each form, and these values become the arguments to the function. The function is then applied to the arguments. The functional computation normally produces a value, but it may instead call for a non-local exit; see throw. A function that does return may produce no value or several values; see values. If and when the function returns, whatever values it returns become the values of the function-call form. For example, consider the evaluation of the form (+ 3 (* 4 5)). The symbol + names the addition function, not a special form or macro. Therefore the two forms 3 and (* 4 5) are evaluated to produce arguments. The form 3 evaluates to 3, and the form (* 4 5) is a function call (to the multiplication function). Therefore the forms 4 and 5 are evaluated, producing arguments 4 and 5 for the multiplication. The multiplication function calculates the number 20 and returns it. The values 3 and 20 are then given as arguments to the addition function, which calculates and returns the number 23. Therefore we say (+ 3 (* 4 5)) ==> 23. X3J13 voted in October 1988 <86> to clarify that while the arguments in a | function call are always evaluated in strict left-to-right order, whether the | function to be called is determined before or after argument evaluation is | unspecified. Programs are in error that rely on a particular order of | evaluation of the first element of a function call relative to the argument | forms. ------------------------------------------------------------------------------- 5.2. <### Functions ###> There are two ways to indicate a function to be used in a function-call form. One is to use a symbol that names the function. This use of symbols to name functions is completely independent of their use in naming special and lexical variables. The other way is to use a lambda-expression, which is a list whose first element is the symbol lambda. A lambda-expression is not a form; it cannot be meaningfully evaluated. Lambda-expressions and symbols, when used in programs as names of functions, can appear only as the first element of a function-call form, or as the second element of the function special form. Note that symbols and lambda-expressions are treated as names of functions in these two contexts. This should be distinguished from the treatment of symbols and lambda-expressions as function objects, that is, objects that satisfy the predicate functionp, as when giving such an object to apply or funcall to be invoked. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.2.1. <## Named Functions ##> A name can be given to a function in one of two ways. A global name can be given to a function by using the defun construct. A local name can be given to a function by using the flet or labels special form. When a function is named, a lambda-expression is effectively associated with that name along with information about the entities that are lexically apparent at that point. If a symbol appears as the first element of a function-call form, then it refers to the definition established by the innermost flet or labels construct that textually contains the reference, or to the global definition (if any) if there is no such containing construct. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.2.2. <## Lambda-Expressions ##> A lambda-expression is a list with the following syntax: (lambda lambda-list . body) The first element must be the symbol lambda. The second element must be a list. It is called the lambda-list, and specifies names for the parameters of the function. When the function denoted by the lambda-expression is applied to arguments, the arguments are matched with the parameters specified by the lambda-list. The body may then refer to the arguments by using the parameter names. The body consists of any number of forms (possibly zero). These forms are evaluated in sequence, and the results of the last form only are returned as the results of the application (the value nil is returned if there are zero forms in the body). The complete syntax of a lambda-expression is: (lambda ( {var}* [&optional {var | (var [initform [svar]])}*] [&rest var] [&key {var | ({var | (keyword var)} [initform [svar]])}* [&allow-other-keys]] [&aux {var | (var [initform])}*] ) [[ {declaration}* | documentation-string ]] {form}*) Each element of a lambda-list is either a parameter specifier or a lambda-list keyword; lambda-list keywords begin with &. (Note that lambda-list keywords are not keywords in the usual sense; they do not belong to the keyword package. They are ordinary symbols each of whose names begins with an ampersand. This terminology is unfortunately confusing but is retained for historical reasons.) In all cases a var or svar must be a symbol, the name of a variable; each : keyword must be a keyword symbol, such as :start. An initform may be any form.: X3J13 voted in March 1988 <105> to allow a keyword in the preceding | specification of a lambda-list to be any symbol whatsoever, not just a keyword | symbol in the keyword package. See below. | A lambda-list has five parts, any or all of which may be empty: * Specifiers for the required parameters. These are all the parameter specifiers up to the first lambda-list keyword; if there is no such lambda-list keyword, then all the specifiers are for required parameters. * Specifiers for optional parameters. If the lambda-list keyword &optional is present, the optional parameter specifiers are those following the lambda-list keyword &optional up to the next lambda-list keyword or the end of the list. * A specifier for a rest parameter. The lambda-list keyword &rest, if present, must be followed by a single rest parameter specifier, which in turn must be followed by another lambda-list keyword or the end of the lambda-list. * Specifiers for keyword parameters. If the lambda-list keyword &key is present, all specifiers up to the next lambda-list keyword or the end of the list are keyword parameter specifiers. The keyword parameter specifiers may optionally be followed by the lambda-list keyword &allow-other-keys. * Specifiers for aux variables. These are not really parameters. If the lambda-list keyword &key is present, all specifiers after it are auxiliary variable specifiers. When the function represented by the lambda-expression is applied to arguments, the arguments and parameters are processed in order from left to right. In the simplest case, only required parameters are present in the lambda-list; each is specified simply by a name var for the parameter variable. When the function is applied, there must be exactly as many arguments as there are parameters, and each parameter is bound to one argument. Here, and in general, the parameter is bound as a lexical variable unless a declaration has been made that it should be a special binding; see defvar, proclaim, and declare. In the more general case, if there are n required parameters (n may be zero), there must be at least n arguments, and the required parameters are bound to the first n arguments. The other parameters are then processed using any remaining arguments. If optional parameters are specified, then each one is processed as follows. If any unprocessed arguments remain, then the parameter variable var is bound to the next remaining argument, just as for a required parameter. If no arguments remain, however, then the initform part of the parameter specifier is evaluated, and the parameter variable is bound to the resulting value (or to nil if no initform appears in the parameter specifier). If another variable name svar appears in the specifier, it is bound to true if an argument was available, and to false if no argument remained (and therefore initform had to be evaluated). The variable svar is called a supplied-p parameter; it is bound not to an argument but to a value indicating whether or not an argument had been supplied for another parameter. After all optional parameter specifiers have been processed, then there may or may not be a rest parameter. If there is a rest parameter, it is bound to a list of all as-yet-unprocessed arguments. (If no unprocessed arguments remain, the rest parameter is bound to the empty list.) If there is no rest parameter and there are no keyword parameters, then there should be no unprocessed arguments (it is an error if there are). X3J13 voted in January 1989 <155> to clarify that if a function has a rest | parameter and is called using apply, then the list to which the rest parameter | is bound is permitted, but not required, to share top-level list structure with| the list that was the last argument to apply. Programmers should be careful | about performing side effects on the top-level list structure of a rest | parameter. | | This was the result of a rather long discussion within X3J13 and the wider | Lisp community. To set it in its historical context, I must remark that in | Lisp Machine Lisp the list to which a rest parameter was bound had only dynamic| extent; this in conjunction with the technique of "cdr-coding" permitted a | clever stack-allocation technique with very low overhead. However, the early | designers of Common Lisp, after a great deal of debate, concluded that it was | dangerous for cons cells to have dynamic extent; as an example, the "obvious" | definition of the function list | (defun list (&rest x) x) | could fail catastrophically. Therefore the first edition simply implied that | the list for a rest parameter, like all other lists, would have indefinite | extent. This still left open the flip side of the question, namely, Is the | list for a rest parameter guaranteed fresh? This is the question addressed by | the X3J13 vote. If it is always freshly consed, then it is permissible to | destroy it, for example by giving it to nconc. However, the requirement always| to cons fresh lists could impose an unacceptable overhead in many | implementations. The clarification approved by X3J13 specifies that the | programmer may not rely on the list being fresh; if the function was called | using apply, there is no way to know where the list came from. | Next, any keyword parameters are processed. For this purpose the same arguments are processed that would be made into a list for a rest parameter. (Indeed, it is permitted to specify both &rest and &key. In this case the remaining arguments are used for both purposes; that is, all remaining arguments are made into a list for the &rest parameter and are also processed for the &key parameters. This is the only situation in which an argument is used in the processing of more than one parameter specifier.) If &key is specified, there must remain an even number of arguments; these are considered as pairs, the first argument in each pair being interpreted as a keyword name and the second as the corresponding value. It is an error for the first object of each pair to be anything but a : keyword. : : . . . . . . . . . . . . . . . . . . . . : Rationale: This last restriction is imposed so that a compiler may issue : warnings about certain malformed calls to functions that take keyword : arguments. It must be remembered that the arguments in a function call that : evaluate to keywords are just like any other arguments and may be any : evaluable forms. A compiler could not, without additional context, issue a : warning about the call : (fill seq item x y) : because in principle the variable x might have as its value a keyword such as: :start. However, a compiler would be justified in issuing a warning about : the call : (fill seq item 0 10) : because the constant 0 is definitely not a keyword. Similarly, if in the : first case the variable x had been declared to be of type integer, then type : analysis could enable the compiler to justify a warning. : . . . . . . . . . . . . . . . . . . . . : X3J13 voted in March 1988 <105> to allow a keyword in a lambda-list to be any| symbol whatsoever, not just a keyword symbol in the keyword package. If, after| &key, a variable appears alone or within only one set of parentheses (possibly | with an initform and a svar), then the behavior is as before: a keyword symbol | with the same name as the variable is used as the keyword-name when matching | arguments to parameter specifiers. Only a parameter specifier of the form | ((keyword var) ...) can cause the keyword-name not to be a keyword symbol, by | specifying a symbol not in the keyword package as the keyword. For example: | | (defun wager (&key ((secret password) nil) amount) | (format nil "You ~A $~D" | (if (eq password 'joe-sent-me) "win" "lose") | amount)) | | (wager :amount 100) ==> "You lose $100" | (wager :amount 100 'secret 'joe-sent-me) ==> "You win $100" | | The secret word could be made even more secret in this example by placing it | in some other obscure package, so that one would have to write | (wager :amount 100 'obscure:secret 'joe-sent-me) ==> "You win $100" | to win anything. | In each keyword parameter specifier must be a name var for the parameter variable. If an explicit keyword is specified, then that is the keyword name for the parameter. Otherwise the name var serves to indicate the keyword name, in that a keyword with the same name (in the keyword package) is used as the keyword. Thus (defun foo (&key radix (type 'integer)) ...) means exactly the same as (defun foo (&key ((:radix radix)) ((:type type) 'integer)) ...) The keyword parameter specifiers are, like all parameter specifiers, effectively processed from left to right. For each keyword parameter specifier, if there is an argument pair whose keyword name matches that specifier's keyword name (that is, the names are eq), then the parameter variable for that specifier is bound to the second item (the value) of that argument pair. If more than one such argument pair matches, it is not an error; the leftmost argument pair is used. If no such argument pair exists, then the initform for that specifier is evaluated and the parameter variable is bound to that value (or to nil if no initform was specified). The variable svar is treated as for ordinary optional parameters: it is bound to true if there was a matching argument pair, and to false otherwise. It is an error if an argument pair has a keyword name not matched by any parameter specifier, unless at least one of the following two conditions is met: * &allow-other-keys was specified in the lambda-list. * Somewhere among the keyword argument pairs is a pair whose keyword is :allow-other-keys and whose value is not nil. If either condition obtains, then it is not an error for an argument pair to match no parameter specified, and the argument pair is simply ignored (but such an argument pair is accessible through the &rest parameter if one was specified). The purpose of these mechanisms is to allow sharing of argument lists among several functions and to allow either the caller or the called function to specify that such sharing may be taking place. After all parameter specifiers have been processed, the auxiliary variable specifiers (those following the lambda-list keyword &aux) are processed from left to right. For each one, the initform is evaluated and the variable var bound to that value (or to nil if no initform was specified). Nothing can be done with &aux variables that cannot be done with the special form let*: (lambda (x y &aux (a (car x)) (b 2) c) ...) == (lambda (x y) (let* ((a (car x)) (b 2) c) ...)) Which to use is purely a matter of style. Whenever any initform is evaluated for any parameter specifier, that form may refer to any parameter variable to the left of the specifier in which the initform appears, including any supplied-p variables, and may rely on the fact that no other parameter variable has yet been bound (including its own parameter variable). Once the lambda-list has been processed, the forms in the body of the lambda-expression are executed. These forms may refer to the arguments to the function by using the names of the parameters. On exit from the function, either by a normal return of the function's value(s) or by a non-local exit, the parameter bindings, whether lexical or special, are no longer in effect. (The bindings are not necessarily permanently discarded, for a lexical binding can later be reinstated if a "closure" over that binding was created, perhaps by using function, and saved before the exit occurred.) Examples of &optional and &rest parameters: ((lambda (a b) (+ a (* b 3))) 4 5) ==> 19 ((lambda (a &optional (b 2)) (+ a (* b 3))) 4 5) ==> 19 ((lambda (a &optional (b 2)) (+ a (* b 3))) 4) ==> 10 ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x))) ==> (2 nil 3 nil nil) ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x)) 6) ==> (6 t 3 nil nil) ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x)) 6 3) ==> (6 t 3 t nil) ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x)) 6 3 8) ==> (6 t 3 t (8)) ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x)) 6 3 8 9 10 11) ==> (6 t 3 t (8 9 10 11)) Examples of &key parameters: ((lambda (a b &key c d) (list a b c d)) 1 2) ==> (1 2 nil nil) ((lambda (a b &key c d) (list a b c d)) 1 2 :c 6) ==> (1 2 6 nil) ((lambda (a b &key c d) (list a b c d)) 1 2 :d 8) ==> (1 2 nil 8) ((lambda (a b &key c d) (list a b c d)) 1 2 :c 6 :d 8) ==> (1 2 6 8) ((lambda (a b &key c d) (list a b c d)) 1 2 :d 8 :c 6) ==> (1 2 6 8) ((lambda (a b &key c d) (list a b c d)) :a 1 :d 8 :c 6) ==> (:a 1 6 8) ((lambda (a b &key c d) (list a b c d)) :a :b :c :d) ==> (:a :b :d nil) Examples of mixtures: ((lambda (a &optional (b 3) &rest x &key c (d a)) (list a b c d x)) 1) ==> (1 3 nil 1 ()) ((lambda (a &optional (b 3) &rest x &key c (d a)) (list a b c d x)) 1 2) ==> (1 2 nil 1 ()) ((lambda (a &optional (b 3) &rest x &key c (d a)) (list a b c d x)) :c 7) ==> (:c 7 nil :c ()) ((lambda (a &optional (b 3) &rest x &key c (d a)) (list a b c d x)) 1 6 :c 7) ==> (1 6 7 1 (:c 7)) ((lambda (a &optional (b 3) &rest x &key c (d a)) (list a b c d x)) 1 6 :d 8) ==> (1 6 nil 8 (:d 8)) ((lambda (a &optional (b 3) &rest x &key c (d a)) (list a b c d x)) 1 6 :d 8 :c 9 :d 10) ==> (1 6 9 8 (:d 8 :c 9 :d 10)) All lambda-list keywords are permitted, but not terribly useful, in lambda-expressions appearing explicitly as the first element of a function-call form. They are extremely useful, however, in functions given global names by defun. All symbols whose names begin with & are conventionally reserved for use as lambda-list keywords and should not be used as variable names. Implementations of Common Lisp are free to provide additional lambda-list keywords. ---------<<>> lambda-list-keywords lambda-list-keywords The value of lambda-list-keywords is a list of all the lambda-list keywords used in the implementation, including the additional ones used only by defmacro. This list must contain at least the symbols &optional, &rest, &key, &allow-other-keys, &aux, &body, &whole, and &environment. As an example of the use of &allow-other-keys and :allow-other-keys, consider a function that takes two keyword arguments of its own and also accepts additional keyword arguments to be passed to make-array: (defun array-of-strings (str dims &rest keyword-pairs &key (start 0) end &allow-other-keys) (apply #'make-array dims :initial-element (subseq str start end) :allow-other-keys t keyword-pairs)) This function takes a string and dimensioning information and returns an array of the specified dimensions, each of whose elements is the specified string. However, :start and :end keyword arguments may be used in the usual manner (see chapter 14) to specify that a substring of the given string should be used. In addition, the presence of &allow-other-keys in the lambda-list indicates that the caller may specify additional keyword arguments; the &rest argument provides access to them. These additional keyword arguments are fed to make-array. Now, make-array normally does not allow the keywords :start and :end to be used, and it would be an error to specify such keyword arguments to make-array. However, the presence in the call to make-array of the keyword argument :allow-other-keys with a non-nil value causes any extraneous keyword arguments, including :start and :end, to be acceptable and ignored. ---------<<>> lambda-parameters-limit lambda-parameters-limit The value of lambda-parameters-limit is a positive integer that is the upper exclusive bound on the number of distinct parameter names that may appear in a single lambda-list. This bound depends on the implementation but will not be smaller than 50. Implementors are encouraged to make this limit as large as practicable without sacrificing performance. See call-arguments-limit. ------------------------------------------------------------------------------- 5.3. <### Top-Level Forms ###> The standard way for the user to interact with a Common Lisp implementation is via a read-eval-print loop: the system repeatedly reads a form from some input source (such as a keyboard or a disk file), evaluates it, and then prints the value(s) to some output sink (such as a display screen or another disk file). Any form (evaluable data object) is acceptable; however, certain special forms are specifically designed to be convenient for use as top-level forms, rather than as forms embedded within other forms in the way that (+ 3 4) is embedded within (if p (+ 3 4) 6). These top-level special forms may be used to define globally named functions, to define macros, to make declarations, and to define global values for special variables. It is not illegal to use these forms at other than top level, but whether it : is meaningful to do so depends on context. Compilers, for example, may not : recognize these forms properly in other than top-level contexts. (As a special: case, however, if a progn form appears at top level, then all forms within that: progn are considered by the compiler to be top-level forms.) : X3J13 voted in March 1989 <50> to clarify that, while defining forms normally| appear at top level, it is meaningful to place them in non-top-level contexts. | All defining forms that create functional objects from code appearing as | argument forms must ensure that such argument forms refer to the enclosing | lexical environment. Compilers must handle defining forms properly in all | situations, not just top-level contexts. However, certain compile-time side | effects of these defining forms are performed only when the defining forms | occur at top level (see section 25.1). | . . . . . . . . . . . . . . . . . . . . Compatibility note: In MacLisp, a top-level progn is considered to contain top-level forms only if the first form is (quote compile). This odd marker is unnecessary in Common Lisp. . . . . . . . . . . . . . . . . . . . . Macros are usually defined by using the special form defmacro. This facility is fairly complicated; it is described in chapter 8. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.3.1. <## Defining Named Functions ##> The defun special form is the usual means of defining named functions. ---------<<>> defun defun name lambda-list [[ {declaration}* | doc-string ]] form* Evaluating a defun form causes the symbol name to be a global name for the function specified by the lambda-expression (lambda lambda-list {declaration | doc-string}* {form}*) defined in the lexical environment in which the defun form was executed. Because defun forms normally appear at top level, this is normally the null lexical environment. X3J13 voted in March 1989 <50> to clarify that, while defining forms normally| appear at top level, it is meaningful to place them in non-top-level contexts; | defun must define the function within the enclosing lexical environment, not | within the null lexical environment. | X3J13 voted in March 1989 <89> to extend defun to accept any function-name (a| symbol or a list whose car is setf -- see section 7.1) as a name. Thus one may| write | (defun (setf cadr) ...) | to define a setf expansion function for cadr (although it may be much more | convenient to use defsetf or define-modify-macro). | If the optional documentation string doc-string is present, then it is attached to the name as a documentation string of type function; see documentation. If doc-string is not followed by a declaration, it may be present only if at least one form is also specified, as it is otherwise taken to be a form. It is an error if more than one doc-string is present. The forms constitute the body of the defined function; they are executed as an implicit progn. The body of the defined function is implicitly enclosed in a block construct whose name is the same as the name of the function. Therefore return-from may be used to exit from the function. Other implementation-dependent bookkeeping actions may be taken as well by defun. The name is returned as the value of the defun form. For example: (defun discriminant (a b c) (declare (number a b c)) "Compute the discriminant for a quadratic equation. Given a, b, and c, the value b^2-4*a*c is calculated. The quadratic equation a*x^2+b*x+c=0 has real, multiple, or complex roots depending on whether this calculated value is positive, zero, or negative, respectively." (- (* b b) (* 4 a c))) ==> discriminant and now (discriminant 1 2/3 -2) ==> 76/9 The documentation string in this example neglects to mention that the | coefficients a, b, and c must be real for the discrimination criterion to hold.| Here is an improved version: | "Compute the discriminant for a quadratic equation. | Given a, b, and c, the value b^2-4*a*c is calculated. | If the coefficients a, b, and c are all real (that is, | not complex), then the quadratic equation a*x^2+b*x+c=0 | has real, multiple, or complex roots depending on | whether this calculated value is positive, zero, or | negative, respectively." | It is permissible to use defun to redefine a function, to install a corrected version of an incorrect definition, for example. It is permissible to redefine a macro as a function. It is an error to attempt to redefine the name of a special form (see table 5-1) as a function. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.3.2. <## Declaring Global Variables and Named Constants ##> The defvar and defparameter special forms are the usual means of specifying globally defined variables. The defconstant special form is used for defining named constants. ---------<<>> defvar defvar name [initial-value [documentation]] ---------<<>> defparameter defparameter name initial-value [documentation] ---------<<>> defconstant defconstant name initial-value [documentation] defvar is the recommended way to declare the use of a special variable in a program. (defvar variable) proclaims variable to be special (see proclaim), and may perform other system-dependent bookkeeping actions. X3J13 voted in June 1987 <61> to clarify that if no initial-value form is | provided, defvar does not change the value of the variable; if no initial-value| form is provided and the variable has no value, defvar does not give it a | value. | If a second argument form is supplied, (defvar variable initial-value) then variable is initialized to the result of evaluating the form initial-value unless it already has a value. The initial-value form is not evaluated unless it is used; this fact is useful if evaluation of the initial-value form does something expensive like creating a large data structure. X3J13 voted in June 1987 <60> to clarify that evaluation of the initial-value| and the initialization of the variable occur, if at all, at the time the defvar| form is executed, and that the initial-value form is evaluated if and only if | the variable does not already have a value. | The initialization is performed by assignment and thus assigns a global value to the variable unless there are currently special bindings of that variable. Normally there should not be any such special bindings. defvar also provides a good place to put a comment describing the meaning of the variable, whereas an ordinary special proclamation offers the temptation to declare several variables at once and not have room to describe them all. (defvar *visible-windows* 0 "Number of windows at least partially visible on the screen") defparameter is similar to defvar, but defparameter requires an initial-value form, always evaluates the form, and assigns the result to the variable. The semantic distinction is that defvar is intended to declare a variable changed by the program, whereas defparameter is intended to declare a variable that is normally constant but can be changed (possibly at run time), where such a change is considered a change to the program. defparameter therefore does not indicate that the quantity never changes; in particular, it does not license the compiler to build assumptions about the value into programs being compiled. defconstant is like defparameter but does assert that the value of the variable name is fixed and does license the compiler to build assumptions about the value into programs being compiled. (However, if the compiler chooses to replace references to the name of the constant by the value of the constant in code to be compiled, perhaps in order to allow further optimization, the compiler must take care that such "copies" appear to be eql to the object that is the actual value of the constant. For example, the compiler may freely make copies of numbers but must exercise care when the value is a list.) It is an error if there are any special bindings of the variable at the time the defconstant form is executed (but implementations may or may not check for this). Once a name has been declared by defconstant to be constant, any further assignment to or binding of that special variable is an error. This is the case for such system-supplied constants as t and most-positive-fixnum. A compiler may also choose to issue warnings about bindings of the lexical variable of the same name. X3J13 voted in January 1989 <48> to clarify the preceding paragraph by | specifying that it is an error to rebind constant symbols as either lexical or | special variables. Consequently, a valid reference to a symbol declared with | defconstant always refers to its global value. (Unfortunately, this violates | the principle of referential transparency, for one cannot always choose names | for lexical variables without regard to surrounding context.) | For any of these constructs, the documentation should be a string. The string is attached to the name of the variable, parameter, or constant under the variable documentation type; see the documentation function. X3J13 voted in March 1988 <59> to clarify that the documentation-string is | not evaluated but must appear as a literal string when the defvar, | defparameter, or defconstant form is evaluated. | | For example, the form | (defvar *avoid-registers* nil "Compilation control switch #43") | is legitimate, but | (defvar *avoid-registers* nil | (format nil "Compilation control switch #~D" | (incf *compiler-switch-number*))) | is erroneous because the call to format is not a literal string. | | (On the other hand, the form | (defvar *avoid-registers* nil | #.(format nil "Compilation control switch #~D" | (incf *compiler-switch-number*))) | might be used to accomplish the same purpose, because the call to format is | evaluated at read time; when the defvar form is evaluated, only the result of | the call to format, a string, appears in the defvar form.) | These constructs are normally used only as top-level forms. The value returned by each of these constructs is the name declared. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 5.3.3. <## Control of Time of Evaluation ##> The eval-when special form allows pieces of code to be executed only at : compile time, only at load time, or when interpreted but not compiled. Its : uses are relatively esoteric. : : ---------<<>> eval-when : eval-when ({situation}*) {form}* : : The body of an eval-when form is processed as an implicit progn, but only in : the situations listed. Each situation must be a symbol, either compile, load, : or eval. : : eval specifies that the interpreter should process the body. compile : specifies that the compiler should evaluate the body at compile time in the : compilation context. load specifies that the compiler should arrange to : evaluate the forms in the body when the compiled file containing the eval-when : form is loaded. : : The eval-when construct may be more precisely understood in terms of a model : of how the compiler processes forms in a file to be compiled. Successive forms: are read from the file using the function read. These top-level forms are : normally processed in what we shall call not-compile-time mode. There is : another mode called compile-time-too mode. The eval-when special form controls: which of these two modes to use. : : Every form is processed as follows: : : * If the form is an eval-when form: : : - If the situation load is specified: : . If the situation compile is specified, or if the current processing mode : is compile-time-too and the situation eval is specified, then process : each of the forms in the body in compile-time-too mode. : . Otherwise, process each of the forms in the body in not-compile-time : mode. : : - If the situation load is not specified: : . If the situation compile is specified, or if the current processing mode : is compile-time-too and the situation eval is specified, then evaluate : each of the forms in the body in the compiler's executing environment. : . Otherwise, ignore the eval-when form entirely. : : * If the form is not an eval-when form, then do two things. First, if the : current processing mode is compile-time-too mode, evaluate the form in the : compiler's executing environment. Second, perform normal compiler processing: of the form (compiling functions defined by defun forms, and so on). : : One example of the use of eval-when is that if the compiler is to be able to : properly read a file that uses user-defined reader macro characters, it is : necessary to write : (eval-when (compile load eval) : (set-macro-character #\$ #'(lambda (stream char) : (declare (ignore char)) : (list 'dollar (read stream))))) : This causes the call to set-macro-character to be executed in the compiler's : execution environment, thereby modifying its reader syntax table. : X3J13 voted in March 1989 <73> to completely redesign the eval-when construct| to solve some problems concerning its treatment in other than top-level | contexts. The new definition is upward compatible with the old definition, but| the old keywords are deprecated. | | ---------<<>> eval-when | eval-when ({situation}*) {form}* | | The body of an eval-when form is processed as an implicit progn, but only in | the situations listed. Each situation must be a symbol, either | :compile-toplevel, :load-toplevel, or :execute. | | The use of :compile-toplevel and :load-toplevel controls whether and when | processing occurs for top-level forms. The use of :execute controls whether | processing occurs for non-top-level forms. | | The eval-when construct may be more precisely understood in terms of a model | of how the file compiler, compile-file, processes forms in a file to be | compiled. | | Successive forms are read from the file by the file compiler using read. | These top-level forms are normally processed in what we call "not-compile-time"| mode. There is one other mode, called "compile-time-too" mode, which can come | into play for top-level forms. The eval-when special form is used to annotate | a program in a way that allows the program doing the processing to select the | appropriate mode. | | Processing of top-level forms in the file compiler works as follows: | | * If the form is a macro call, it is expanded and the result is processed as a | top-level form in the same processing mode (compile-time-too or | not-compile-time). | | * If the form is a progn (or locally <113>) form, each of its body forms is | sequentially processed as top-level forms in the same processing mode. | | * If the form is a compiler-let, macrolet, or symbol-macrolet, the file | compiler makes the appropriate bindings and recursively processes the body | forms as an implicit top-level progn with those bindings in effect, in the | same processing mode. | | * If the form is an eval-when form, it is handled according to the following | table: | | LT CT EX CTTM Action | --------------------------------------------------------------------- | yes yes -- -- process body in compile-time-too mode | yes no yes yes process body in compile-time-too mode | yes no -- no process body in not-compile-time mode | yes no no -- process body in not-compile-time mode | no yes -- -- evaluate body | no no yes yes evaluate body | no no -- no do nothing | no no no -- do nothing | --------------------------------------------------------------------- | | In the preceding table the column LT asks whether :load-toplevel is one of | the situations specified in the eval-when form; CT similarly refers to | :compile-toplevel and EX to :execute. The column CTTM asks whether the | eval-when form was encountered while in compile-time-too mode. The phrase | "process body" means to process the body as an implicit top-level progn in the | indicated mode, and "evaluate body" means to evaluate the body forms | sequentially as an implicit progn in the dynamic execution context of the | compiler and in the lexical environment in which the eval-when appears. | | * Otherwise, the form is a top-level form that is not one of the special cases.| If in compile-time-too mode, the compiler first evaluates the form and then | performs normal compiler processing on it. If in not-compile-time mode, only| normal compiler processing is performed (see section 25.1). Any subforms are| treated as non-top-level forms. | | Note that top-level forms are guaranteed to be processed in the order in | which they textually appear in the file, and that each top-level form read by | the compiler is processed before the next is read. However, the order of | processing (including, in particular, macro expansion) of subforms that are not| top-level forms is unspecified. | | For an eval-when form that is not a top-level form in the file compiler (that| is, either in the interpreter, in compile, or in the file compiler but not at | top level), if the :execute situation is specified, its body is treated as an | implicit progn. Otherwise, the body is ignored and the eval-when form has the | value nil. | | For the sake of backward compatibility, a situation may also be compile, | load, or eval. Within a top-level eval-when form these have the same meaning | as :compile-toplevel, :load-toplevel, and :execute, respectively; but their | effect is undefined when used in an eval-when form that is not at top level. | | The following effects are logical consequences of the preceding | specification: | | * It is never the case that the execution of a single eval-when | expression will execute the body code more than once. | | * The old keyword eval was a misnomer because execution of the body need not be| done by eval. For example, when the function definition | (defun foo () (eval-when (:execute) (print 'foo))) | is compiled the call to print should be compiled, not evaluated at compile | time. | | * Macros intended for use in top-level forms should arrange for all | side-effects to be done by the forms in the macro expansion. The | macro-expander itself should not perform the side-effects. | (defmacro foo () | (really-foo) ; Wrong | `(really-foo)) | | (defmacro foo () | `(eval-when (:compile-toplevel | :load-toplevel :execute) ; Right | (really-foo))) | Adherence to this convention will mean that such macros will behave | intuitively when called in non-top-level positions. | | * Placing a variable binding around an eval-when reliably captures the binding | because the "compile-time-too" mode cannot occur (because the eval-when could| not be a top-level form). For example, | (let ((x 3)) | (eval-when (:compile-toplevel :load-toplevel :execute) | (print x))) | will print 3 at execution (that is, load) time and will not print anything at| compile time. This is important so that expansions of defun and defmacro can| be done in terms of eval-when and can correctly capture the lexical | environment. For example, an implementation might expand a defun form such | as | (defun bar (x) (defun foo () (+ x 3))) | into | (progn (eval-when (:compile-toplevel) | (compiler::notice-function 'bar '(x))) | (eval-when (:load-toplevel :execute) | (setf (symbol-function 'bar) | #'(lambda (x) | (progn (eval-when (:compile-toplevel) | (compiler::notice-function 'foo | '())) | (eval-when (:load-toplevel :execute) | (setf (symbol-function 'foo) | #'(lambda () (+ x 3))))))))) | which by the preceding rules would be treated the same as | (progn (eval-when (:compile-toplevel) | (compiler::notice-function 'bar '(x))) | (eval-when (:load-toplevel :execute) | (setf (symbol-function 'bar) | #'(lambda (x) | (progn (eval-when (:load-toplevel :execute) | (setf (symbol-function 'foo) | #'(lambda () (+ x 3))))))))) | | Here are some additional examples. | | (let ((x 1)) | (eval-when (:execute :load-toplevel :compile-toplevel) | (setf (symbol-function 'foo1) #'(lambda () x)))) | | The eval-when in the preceding expression is not at top level, so only the | :execute keyword is considered. At compile time, this has no effect. At load | time (if the let is at top level), or at execution time (if the let is embedded| in some other form which does not execute until later), this sets | (symbol-function 'foo1) to a function that returns 1. | | (eval-when (:execute :load-toplevel :compile-toplevel) | (let ((x 2)) | (eval-when (:execute :load-toplevel :compile-toplevel) | (setf (symbol-function 'foo2) #'(lambda () x))))) | | If the preceding expression occurs at the top level of a file to be compiled,| it has both a compile time and a load-time effect of setting (symbol-function | 'foo2) to a function that returns 2. | | (eval-when (:execute :load-toplevel :compile-toplevel) | (setf (symbol-function 'foo3) #'(lambda () 3))) | | If the preceding expression occurs at the top level of a file to be compiled,| it has both a compile time and a load-time effect of setting the function cell | of foo3 to a function that returns 3. | | (eval-when (:compile-toplevel) | (eval-when (:compile-toplevel) | (print 'foo4))) | | The preceding expression always does nothing; it simply returns nil. | | (eval-when (:compile-toplevel) | (eval-when (:execute) | (print 'foo5))) | | If the preceding form occurs at the top level of a file to be compiled, foo5 | is printed at compile time. If this form occurs in a non-top-level position, | nothing is printed at compile time. Regardless of context, nothing is ever | printed at load time or execution time. | | (eval-when (:execute :load-toplevel) | (eval-when (:compile-toplevel) | (print 'foo6))) | | If the preceding form occurs at the top level of a file to be compiled, foo6 | is printed at compile time. If this form occurs in a non-top-level position, | nothing is printed at compile time. Regardless of context, nothing is ever | printed at load time or execution time. | =============================================================================== 6. <#### Predicates ####> A predicate is a function that tests for some condition involving its arguments and returns nil if the condition is false, or some non-nil value if the condition is true. One may think of a predicate as producing a Boolean value, where nil stands for false and anything else stands for true. Conditional control structures such as cond, if, when, and unless test such Boolean values. We say that a predicate is true when it returns a non-nil value, and it is false when it returns nil; that is, it is true or false according to whether the condition being tested is true or false. By convention, the names of predicates usually end in the letter p (which stands for "predicate"). Common Lisp uses a uniform convention in hyphenating names of predicates. If the name of the predicate is formed by adding a p to an existing name, such as the name of a data type, a hyphen is placed before the final p if and only if there is a hyphen in the existing name. For example, number begets numberp but standard-char begets standard-char-p. On the other hand, if the name of a predicate is formed by adding a prefixing qualifier to the front of an existing predicate name, the two names are joined with a hyphen and the presence or absence of a hyphen before the final p is not changed. For example, the predicate string-lessp has no hyphen before the p because it is the string version of lessp (a MacLisp function that has been renamed < in Common Lisp). The name string-less-p would incorrectly imply that it is a predicate that tests for a kind of object called a string-less, and the name stringlessp would connote a predicate that tests whether something has no strings (is "stringless")! The control structures that test Boolean values only test for whether or not the value is nil, which is considered to be false. Any other value is considered to be true. Often a predicate will return nil if it "fails" and some useful value if it "succeeds"; such a function can be used not only as a test but also for the useful value provided in case of success. An example is member. If no better non-nil value is available for the purpose of indicating success, by convention the symbol t is used as the "standard" true value. ------------------------------------------------------------------------------- 6.1. <### Logical Values ###> The names nil and t are constants in Common Lisp. Although they are symbols like any other symbols, and appear to be treated as variables when evaluated, it is not permitted to modify their values. See defconstant. ---------<<>> nil nil The value of nil is always nil. This object represents the logical false value and also the empty list. It can also be written (). ---------<<>> t t The value of t is always t. ------------------------------------------------------------------------------- 6.2. <### Data Type Predicates ###> Perhaps the most important predicates in Lisp are those that deal with data types; that is, given a data object one can determine whether or not it belongs to a given type, or one can compare two type specifiers. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6.2.1. <## General Type Predicates ##> If a data type is viewed as the set of all objects belonging to the type, then the typep function is a set membership test, while subtypep is a subset test. ---------<<>> typep typep object type typep is a predicate that is true if object is of type type, and is false otherwise. Note that an object can be "of" more than one type, since one type can include another. The type may be any of the type specifiers mentioned in chapter 4 except that it may not be or contain a type specifier list whose first element is function or values. A specifier of the form (satisfies fn) is handled simply by applying the function fn to object (see funcall); the object is considered to be of the specified type if the result is not nil. X3J13 voted in January 1989 <8> to change typep to give specialized array and| complex type specifiers the same meaning for purposes of type discrimination as| they have for declaration purposes. Of course, this also applies to such type | specifiers as vector and simple-array (see section 4.5). Thus | (typep foo '(array bignum)) | in the first edition asked the question, Is foo an array specialized to hold | bignums? but under the new interpretation asks the question, Could the array | foo have resulted from giving bignum as the :element-type argument to | make-array? | ---------<<>> subtypep subtypep type1 type2 The arguments must be type specifiers that are acceptable to typep. The two type specifiers are compared; this predicate is true if type1 is definitely a (not necessarily proper) subtype of type2. If the result is nil, however, then type1 may or may not be a subtype of type2 (sometimes it is impossible to tell, especially when satisfies type specifiers are involved). A second returned value indicates the certainty of the result; if it is true, then the first value is an accurate indication of the subtype relationship. Thus there are three possible result combinations: t t type1 is definitely a subtype of type2 nil t type1 is definitely not a subtype of type2 nil nil subtypep could not determine the relationship X3J13 voted in January 1989 <171> to place certain requirements upon the | implementation of subtypep, for it noted that implementations in many cases | simply "give up" and return the two values nil and nil when in fact it would | have been possible to determine the relationship between the given types. The | requirements are as follows, where it is understood that a type specifier s | involves a type specifier u if either s contains an occurrence of u directly or| s contains a type specifier w defined by deftype whose expansion involves u. | | * subtypep is not permitted to return a second value of nil unless one or both | of its arguments involves satisfies, and, or, not, or member. | | * subtypep should signal an error when one or both of its arguments involves | values or the list form of the function type specifier. | | * subtypep must always return the two values t and t in the case where its | arguments, after expansion of specifiers defined by deftype, are equal. | | In addition, X3J13 voted to clarify that in some cases the relationships | between types as reflected by subtypep may be implementation-specific. For | example, in an implementation supporting only one type of floating-point | number, (subtypep 'float 'long-float) would return t and t, since the two types| would be identical. | | Note that satisfies is an exception because relationships between types | involving satisfies are undecidable in general, but (as X3J13 noted) and, or, | not, and member are merely very messy to deal with. In all likelihood these | will not be addressed unless and until someone is willing to write a careful | specification that covers all the cases for the processing of these type | specifiers by subtypep. The requirements stated above were easy to state and | probably suffice for most cases of interest. | X3J13 voted in January 1989 <8> to change subtypep to give specialized array | and complex type specifiers the same meaning for purposes of type | discrimination as they have for declaration purposes. Of course, this also | applies to such type specifiers as vector and simple-array (see section 4.5). | | If A and B are type specifiers (other than *, which technically is not a type| specifier anyway), then (array A) and (array B) represent the same type in a | given implementation if and only if they denote arrays of the same specialized | representation in that implementation; otherwise they are disjoint. To put it | another way, they represent the same type if and only if | (upgraded-array-element-type 'A) and (upgraded-array-element-type 'B) are the | same type. Therefore | (subtypep '(array A) '(array B)) | is true if and only if (upgraded-array-element-type 'A) is the same type as | (upgraded-array-element-type 'B). | | The complex type specifier is treated in a similar but subtly different | manner. If A and B are two type specifiers (but not *, which technically is | not a type specifier anyway), then (complex A) and (complex B) represent the | same type in a given implementation if and only if they refer to complex | numbers of the same specialized representation in that implementation; | otherwise they are disjoint. Note, however, that there is no function called | make-complex that allows one to specify a particular element type (then to be | upgraded); instead, one must describe specialized complex numbers in terms of | the actual types of the parts from which they were constructed. There is no | number of type (or rather, representation) float as such; there are only | numbers of type single-float, numbers of type double-float, and so on. | Therefore we want (complex single-float) to be a subtype of (complex float). | | The rule, then, is that (complex A) and (complex B) represent the same type | (and otherwise are disjoint) in a given implementation if and only if either | the type A is a subtype of B, or (upgraded-complex-part-type 'A) and | (upgraded-complex-part-type 'B) are the same type. In the latter case | (complex A) and (complex B) in fact refer to the same specialized | representation. Therefore | (subtypep '(complex A) '(complex B)) | is true if and only if the results of (upgraded-complex-part-type 'A) and | (upgraded-complex-part-type 'B) are the same type. | | Under this interpretation | (subtypep '(complex single-float) '(complex float)) | must be true in all implementations; but | (subtypep '(array single-float) '(array float)) | is true only in implementations that do not have a specialized array | representation for single-float elements distinct from that for float elements | in general. | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 6.2.2. <## Specific Data Type Predicates ##> The following predicates test for individual data types. ---------<<>> null null object null is true if its argument is (), and otherwise is false. This is the same operation performed by the function not; however, not is normally used to invert a Boolean value, whereas null is normally used to test for an empty list. The programmer can therefore express intent by the choice of function name. (null x) == (typep x 'null) == (eq x '()) ---------<<>> symbolp symbolp object symbolp is true if its argument is a symbol, and otherwise is false. (symbolp x) == (typep x 'symbol) . . . . . . . . . . . . . . . . . . . . Compatibility note: The Interlisp equivalent of symbolp is called litatom. . . . . . . . . . . . . . . . . . . . . ---------<<>> atom atom object The predicate atom is true if its argument is not a cons, and otherwise is false. Note that (atom '()) is true, because () == nil. (atom x) == (typep x 'atom) == (not (typep x 'cons)) . . . . . . . . . . . . . . . . . . . . Compatibility note: In some Lisp dialects, notably Interlisp, only symbols and numbers are considered to be atoms; arrays and strings are considered to be neither atoms nor lists (conses). . . . . . . . . . . . . . . . . . . . . ---------<<>> consp consp object The predicate consp is true if its argument is a cons, and otherwise is false. Note that the empty list is not a cons, so (consp '()) == (consp 'nil) ==> nil. (consp x) == (typep x 'cons) == (not (typep x 'atom)) . . . . . . . . . . . . . . . . . . . . Compatibility note: Some Lisp implementations call this function pairp or listp. The name pairp was rejected for Common Lisp because it emphasizes too strongly the dotted-pair notion rather than the usual usage of conses in lists. On the other hand, listp too strongly implies that the cons is in fact part of a list, which after all it might not be; moreover, () is a list, though not a cons. The name consp seems to be the appropriate compromise. . . . . . . . . . . . . . . . . . . . . ---------<<>> listp listp object listp is true if its argument is a cons or the empty list (), and otherwise is false. It does not check for whether the list is a "true list" (one terminated by nil) or a "dotted list" (one terminated by a non-null atom). (listp x) == (typep x 'list) == (typep x '(or cons null)) ---------<<>> numberp numberp object numberp is true if its argument is any kind of number, and otherwise is false. (numberp x) == (typep x 'number) ---------<<>> integerp integerp object integerp is true if its argument is an integer, and otherwise is false. (integerp x) == (typep x 'integer) . . . . . . . . . . . . . . . . . . . . Compatibility note: In MacLisp this is called fixp. Users have been confused as to whether this meant integerp or fixnump, and so the name integerp has been adopted here. . . . . . . . . . . . . . . . . . . . . ---------<<>> rationalp rationalp object rationalp is true if its argument is a rational number (a ratio or an integer), and otherwise is false. (rationalp x) == (typep x 'rational) ---------<<>> floatp floatp object floatp is true if its argument is a floating-point number, and otherwise is false. (floatp x) == (typep x 'float) ---------<<>> realp | realp object | | X3J13 voted in March 1989 <151> to add the function realp. realp is true if | its argument is a real number, and otherwise is false. | | (realp x) == (typep x 'real) | ---------<<>> complexp complexp object complexp is true if its argument is a complex number, and otherwise is false. (complexp x) == (typep x 'complex) ---------<<>> characterp characterp object characterp is true if its argument is a character, and otherwise is false. (characterp x) == (typep x 'character) ---------<<>> stringp stringp object stringp is true if its argument is a string, and otherwise is false. (stringp x) == (typep x 'string) ---------<<>> bit-vector-p bit-vector-p object bit-vector-p is true if its argument is a bit-vector, and otherwise is false. (bit-vector-p x) == (typep x 'bit-vector) ---------<<>> vectorp vectorp object vectorp is true if its argument is a vector, and otherwise is false. (vectorp x) == (typep x 'vector) ---------<<>> simple-vector-p simple-vector-p object vectorp is true if its argument is a simple general vector, and otherwise is false. (simple-vector-p x) == (typep x 'simple-vector) ---------<<>> simple-string-p simple-string-p object simple-string-p is true if its argument is a simple string, and otherwise is false. (simple-string-p x) == (typep x 'simple-string) ---------<<>> simple-bit-vector-p simple-bit-vector-p object simple-bit-vector-p is true if its argument is a simple bit-vector, and otherwise is false. (simple-bit-vector-p x) == (typep x 'simple-bit-vector) ---------<<>> arrayp arrayp object arrayp is true if its argument is an array, and otherwise is false. (arrayp x) == (typep x 'array) ---------<<>> packagep packagep object packagep is true if its argument is a package, and otherwise is false. (packagep x) == (typep x 'package) ---------<<>> functionp functionp object functionp is true if its argument is suitable for applying to arguments, : using for example the funcall or apply function. Otherwise functionp is false.: : functionp is always true of symbols, lists whose car is the symbol lambda, : any value returned by the function special form, and any values returned by the: function compile when the first argument is nil. : X3J13 voted in June 1988 <90> to define | | (functionp x) == (typep x 'function) | Because the vote also specifies that types cons and symbol are disjoint from | the type function, this is an incompatible change; now functionp is in fact | always false of symbols and lists. | ---------<<>> compiled-function-p compiled-function-p object compiled-function-p is true if its argument is any compiled code object, and otherwise is false. (compiled-function-p x) == (typep x 'compiled-function) ---------<<>> commonp : commonp object : : commonp is true if its argument is any standard Common Lisp data type, and : otherwise is false. : : (commonp x) == (typep x 'common) : X3J13 voted in March 1989 <17> to remove the predicate commonp (and the type | common) from the language. | See also standard-char-p, string-char-p, streamp, random-state-p, readtablep, hash-table-p, and pathnamep. ------------------------------------------------------------------------------- 6.3. <### Equality Predicates ###> Common Lisp provides a spectrum of predicates for testing for equality of two objects: eq (the most specific), eql, equal, and equalp (the most general). eq and equal have the meanings traditional in Lisp. eql was added because it is frequently needed, and equalp was added primarily in order to have a version of equal that would ignore type differences when comparing numbers and case differences when comparing characters. If two objects satisfy any one of these equality predicates, then they also satisfy all those that are more general. ---------<<>> eq eq x y (eq x y) is true if and only if x and y are the same identical object. (Implementationally, x and y are usually eq if and only if they address the same identical memory location.) It should be noted that things that print the same are not necessarily eq to each other. Symbols with the same print name usually are eq to each other because of the use of the intern function. However, numbers with the same value need not be eq, and two similar lists are usually not eq. For example: (eq 'a 'b) is false. (eq 'a 'a) is true. (eq 3 3) might be true or false, depending on the implementation. (eq 3 3.0) is false. (eq 3.0 3.0) might be true or false, depending on the implementation. (eq #c(3 -4) #c(3 -4)) might be true or false, depending on the implementation. (eq #c(3 -4.0) #c(3 -4)) is false. (eq (cons 'a 'b) (cons 'a 'c)) is false. (eq (cons 'a 'b) (cons 'a 'b)) is false. (eq '(a . b) '(a . b)) might be true or false. (progn (setq x (cons 'a 'b)) (eq x x)) is true. (progn (setq x '(a . b)) (eq x x)) is true. (eq #\A #\A) might be true or false, depending on the implementation. (eq "Foo" "Foo") might be true or false. (eq "Foo" (copy-seq "Foo")) is false. (eq "FOO" "foo") is false. In Common Lisp, unlike some other Lisp dialects, the implementation is permitted to make "copies" of characters and numbers at any time. (This permission is granted because it allows tremendous performance improvements in many common situations.) The net effect is that Common Lisp makes no guarantee that eq will be true even when both its arguments are "the same thing" if that thing is a character or number. For example: (let ((x 5)) (eq x x)) might be true or false. The predicate eql is the same as eq, except that if the arguments are characters or numbers of the same type then their values are compared. Thus eql tells whether two objects are conceptually the same, whereas eq tells whether two objects are implementationally identical. It is for this reason that eql, not eq, is the default comparison predicate for the sequence functions defined in chapter 14. . . . . . . . . . . . . . . . . . . . . Implementation note: eq simply compares the two given pointers, so any kind of object that is represented in an "immediate" fashion will indeed have like- valued instances satisfy eq. In some implementations, for example, fixnums and characters happen to "work." However, no program should depend on this, as other implementations of Common Lisp might not use an immediate representation for these data types. . . . . . . . . . . . . . . . . . . . . An additional problem with eq is that the implementation is permitted to : "collapse" constants (or portions thereof) appearing in code to be compiled if : they are equal. An object is considered to be a constant in code to be : compiled if it is a self-evaluating form or is contained in a quote form. This: is why (eq "Foo" "Foo") might be true or false; in interpreted code it would : normally be false, because reading in the form (eq "Foo" "Foo") would construct: distinct strings for the two arguments to eq, but the compiler might choose to : use the same identical string or two distinct copies as the two arguments in : the call to eq. Similarly, (eq '(a . b) '(a . b)) might be true or false, : depending on whether the constant conses appearing in the quote forms were : collapsed by the compiler. However, (eq (cons 'a 'b) (cons 'a 'b)) is always : false, because every distinct call to the cons function necessarily produces a : new and distinct cons. : X3J13 voted in March 1989 <147> to clarify that eval and compile are not | permitted either to copy or to coalesce ("collapse") constants (see eq) | appearing in the code they process; the resulting program behavior must refer | to objects that are eql to the corresponding objects in the source code. Only | the compile-file/load process is permitted to copy or coalesce constants (see | section 25.1). | ---------<<>> eql eql x y The eql predicate is true if its arguments are eq, or if they are numbers of the same type with the same value, or if they are character objects that represent the same character. For example: (eql 'a 'b) is false. (eql 'a 'a) is true. (eql 3 3) is true. (eql 3 3.0) is false. (eql 3.0 3.0) is true. (eql #c(3 -4) #c(3 -4)) is true. (eql #c(3 -4.0) #c(3 -4)) is false. (eql (cons 'a 'b) (cons 'a 'c)) is false. (eql (cons 'a 'b) (cons 'a 'b)) is false. (eql '(a . b) '(a . b)) might be true or false. (progn (setq x (cons 'a 'b)) (eql x x)) is true. (progn (setq x '(a . b)) (eql x x)) is true. (eql #\A #\A) is true. (eql "Foo" "Foo") might be true or false. (eql "Foo" (copy-seq "Foo")) is false. (eql "FOO" "foo") is false. Normally (eql 1.0s0 1.0d0) would be false, under the assumption that 1.0s0 and 1.0d0 are of distinct data types. However, implementations that do not provide four distinct floating-point formats are permitted to "collapse" the four formats into some smaller number of them; in such an implementation (eql 1.0s0 1.0d0) might be true. The predicate = will compare the values of two numbers even if the numbers are of different types. If an implementation supports positive and negative zeros as distinct values (as in the IEEE proposed standard floating-point format), then (eql 0.0 -0.0) will be false. Otherwise, when the syntax -0.0 is read it will be interpreted as the value 0.0, and so (eql 0.0 -0.0) will be true. The predicate = differs from eql in that (= 0.0 -0.0) will always be true, because = compares the mathematical values of its operands, whereas eql compares the representational values, so to speak. Two complex numbers are considered to be eql if their real parts are eql and their imaginary parts are eql. For example, (eql #C(4 5) #C(4 5)) is true and (eql #C(4 5) #C(4.0 5.0)) is false. Note that while (eql #C(5.0 0.0) 5.0) is false, (eql #C(5 0) 5) is true. In the case of (eql #C(5.0 0.0) 5.0) the two arguments are of different types and so cannot satisfy eql; that's all there is to it. In the case of (eql #C(5 0) 5), however, #C(5 0) is not a complex number but is always automatically reduced by the rule of complex canonicalization to the integer 5, just as the apparent ratio 20/4 is always simplified to 5. The case of (eql "Foo" "Foo") is discussed above in the description of eq. While eql compares the values of numbers and characters, it does not compare the contents of strings. To compare the characters of two strings, one should use equal, equalp, string=, or string-equal. . . . . . . . . . . . . . . . . . . . . Compatibility note: The Common Lisp function eql is similar to the Interlisp function eqp. However, eql considers 3 and 3.0 to be different, whereas eqp considers them to be the same; eqp behaves like the Common Lisp = function, not like eql, when both arguments are numbers. . . . . . . . . . . . . . . . . . . . . ---------<<>> equal equal x y The equal predicate is true if its arguments are structurally similar (isomorphic) objects. A rough rule of thumb is that two objects are equal if and only if their printed representations are the same. Numbers and characters are compared as for eql. Symbols are compared as for eq. This method of comparing symbols can violate the rule of thumb for equal and printed representations, but only in the infrequently occurring case of two distinct symbols with the same print name. Certain objects that have components are equal if they are of the same type and corresponding components are equal. This test is implemented in a recursive manner and may fail to terminate for circular structures. For conses, equal is defined recursively as the two car's being equal and the two cdr's being equal. Two arrays are equal only if they are eq, with one exception: strings and bit-vectors are compared element-by-element. If either argument has a fill pointer, the fill pointer limits the number of elements examined by equal. Uppercase and lowercase letters in strings are considered by equal to be distinct. (In contrast, equalp ignores case distinctions in strings.) . . . . . . . . . . . . . . . . . . . . Compatibility note: In Lisp Machine Lisp, equal ignores the difference between uppercase and lowercase letters in strings. This violates the rule of thumb about printed representations, however, which is very useful, especially to novices. It is also inconsistent with the treatment of single characters, which in Lisp Machine Lisp are represented as fixnums. . . . . . . . . . . . . . . . . . . . . Two pathname objects are equal if and only if all the corresponding components (host, device, and so on) are equivalent. (Whether or not uppercase and lowercase letters are considered equivalent in strings appearing in components depends on the file name conventions of the file system.) Pathnames that are equal should be functionally equivalent. X3J13 voted in June 1989 <71> to clarify that equal never recursively | descends any structure or data type other than the ones explicitly described | above: conses, bit-vectors, strings, and pathnames. Numbers and characters are| compared as if by eql, and all other data objects are compared as if by eq. | (equal 'a 'b) is false. (equal 'a 'a) is true. (equal 3 3) is true. (equal 3 3.0) is false. (equal 3.0 3.0) is true. (equal #c(3 -4) #c(3 -4)) is true. (equal #c(3 -4.0) #c(3 -4)) is false. (equal (cons 'a 'b) (cons 'a 'c)) is false. (equal (cons 'a 'b) (cons 'a 'b)) is true. (equal '(a . b) '(a . b)) is true. (progn (setq x (cons 'a 'b)) (equal x x)) is true. (progn (setq x '(a . b)) (equal x x)) is true. (equal #\A #\A) is true. (equal "Foo" "Foo") is true. (equal "Foo" (copy-seq "Foo")) is true. (equal "FOO" "foo") is false. To compare a tree of conses using eql (or any other desired predicate) on the leaves, use tree-equal. ---------<<>> equalp equalp x y Two objects are equalp if they are equal; if they are characters and satisfy char-equal, which ignores alphabetic case and certain other attributes of characters; if they are numbers and have the same numerical value, even if they are of different types; or if they have components that are all equalp. Objects that have components are equalp if they are of the same type and corresponding components are equalp. This test is implemented in a recursive manner and may fail to terminate for circular structures. For conses, equalp is defined recursively as the two car's being equalp and the two cdr's being equalp. Two arrays are equalp if and only if they have the same number of dimensions, the dimensions match, and the corresponding components are equalp. The specializations need not match; for example, a string and a general array that happens to contain the same characters will be equalp (though definitely not equal). If either argument has a fill pointer, the fill pointer limits the number of elements examined by equalp. Because equalp performs element-by-element comparisons of strings and ignores the alphabetic case of characters, case distinctions are therefore also ignored when equalp compares strings. Two symbols can be equalp only if they are eq, that is, the same identical object. X3J13 voted in June 1989 <71> to specify that equalp compares components of | hash tables (see below), and to clarify that otherwise equalp never recursively| descends any structure or data type other than the ones explicitly described | above: conses, arrays (including bit-vectors and strings), and pathnames. | Numbers are compared for numerical equality (see =), characters are compared as| if by char-equal, and all other data objects are compared as if by eq. | | Two hash tables are considered the same by equalp if and only if they satisfy| a four-part test: | | * They must be of the same kind; that is, equivalent :test arguments were given| to make-hash-table when the two hash tables were created. | | * They must have the same number of entries (see hash-table-count). | | * For every entry (key1, value1) in one hash table there must be a | corresponding entry (key2, value2) in the other, such that key1 and key2 are | considered to be the same by the :test function associated with the hash | tables. | | * For every entry (key1, value1) in one hash table and its corresponding entry | (key2, value2) in the other, such that key1 and key2 are the same, equalp | must be true of value1 and value2. | | The four parts of this test are carried out in the order shown, and if some | part of the test fails, equalp returns nil and the other parts of the test are | not attempted. | | If equalp must compare two structures and the defstruct definition for one | used the :type option and the other did not, then equalp returns nil. | | If equalp must compare two structures and neither defstruct definition used | the :type option, then equalp returns t if and only if the structures have the | same type (that is, the same defstruct name) and the values of all | corresponding slots (slots having the same name) are equalp. | | As part of the X3J13 discussion of this issue the following observations were| made. Object equality is not a concept for which there is a uniquely | determined correct algorithm. The appropriateness of an equality predicate can| be judged only in the context of the needs of some particular program. | Although these functions take any type of argument and their names sound very | generic, equal and equalp are not appropriate for every application. Any | decision to use or not use them should be determined by what they are | documented to do rather than by any abstract characterization of their | function. If neither equal nor equalp is found to be appropriate in a | particular situation, programmers are encouraged to create another operator | that is appropriate rather than blame equal or equalp for "doing the wrong | thing." | Note that one consequence of the vote to change the rules of floating-point | contagion <37> (described in section 12.1) is to make equalp a true equivalence| relation on numbers. | (equalp 'a 'b) is false. (equalp 'a 'a) is true. (equalp 3 3) is true. (equalp 3 3.0) is true. (equalp 3.0 3.0) is true. (equalp #c(3 -4) #c(3 -4)) is true. (equalp #c(3 -4.0) #c(3 -4)) is true. (equalp (cons 'a 'b) (cons 'a 'c)) is false. (equalp (cons 'a 'b) (cons 'a 'b)) is true. (equalp '(a . b) '(a . b)) is true. (progn (setq x (cons 'a 'b)) (equalp x x)) is true. (progn (setq x '(a . b)) (equalp x x)) is true. (equalp #\A #\A) is true. (equalp "Foo" "Foo") is true. (equalp "Foo" (copy-seq "Foo")) is true. (equalp "FOO" "foo") is true. ------------------------------------------------------------------------------- 6.3. <### Logical Operators ###> Common Lisp provides three operators on Boolean values: and, or, and not. Of these, and and or are also control structures because their arguments are evaluated conditionally. The function not necessarily examines its single argument, and so is a simple function. ---------<<>> not not x not returns t if x is nil, and otherwise returns nil. It therefore inverts its argument considered as a Boolean value. null is the same as not; both functions are included for the sake of clarity. As a matter of style, it is customary to use null to check whether something is the empty list and to use not to invert the sense of a logical value. ---------<<>> and and {form}* (and form1 form2 ... ) evaluates each form, one at a time, from left to right. If any form evaluates to nil, the value nil is immediately returned without evaluating the remaining forms. If every form but the last evaluates to a non-nil value, and returns whatever the last form returns. Therefore in general and can be used both for logical operations, where nil stands for false and non-nil values stand for true, and as a conditional expression. An example follows. (if (and (>= n 0) (< n (length a-simple-vector)) (eq (elt a-simple-vector n) 'foo)) (princ "Foo!")) The above expression prints "Foo!" if element n of a-simple-vector is the symbol foo, provided also that n is indeed a valid index for a-simple-vector. Because and guarantees left-to-right testing of its parts, elt is not called if n is out of range. To put it another way, the and special form does short-circuit Boolean evaluation, like the "and then" operator in Ada and what in some Pascal-like languages is called "cand" (for "conditional and"); the Lisp and special form is unlike the Pascal or Ada and operator, which always evaluates both arguments. In the previous example writing (and (>= n 0) (< n (length a-simple-vector)) (eq (elt a-simple-vector n) 'foo) (princ "Foo!")) would accomplish the same thing. The difference is purely stylistic. Some programmers never use expressions containing side effects within and, preferring to use if or when for that purpose. From the general definition, one can deduce that (and x) == x. Also, (and) evaluates to t, which is an identity for this operation. One can define and in terms of cond in this way: (and x y z ... w) == (cond ((not x) nil) ((not y) nil) ((not z) nil) ... (t w)) See if and when, which are sometimes stylistically more appropriate than and for conditional purposes. If it is necessary to test whether a predicate is true of all elements of a list or vector (element 0 and element 1 and element 2 and ...), then the function every may be useful. ---------<<>> or or {form}* (or form1 form2 ... ) evaluates each form, one at a time, from left to right. If any form other than the last evaluates to something other than nil, or immediately returns that non-nil value without evaluating the remaining forms. If every form but the last evaluates to nil, or returns whatever evaluation of the last of the forms returns. Therefore in general or can be used both for logical operations, where nil stands for false and non-nil values stand for true, and as a conditional expression. To put it another way, the or special form does short-circuit Boolean evaluation, like the "or else" operator in Ada and what in some Pascal-like languages is called "cor" (for "conditional or"); the Lisp or special form is unlike the Pascal or Ada or operator, which always evaluates both arguments. From the general definition, one can deduce that (or x) == x. Also, (or) evaluates to nil, which is the identity for this operation. One can define or in terms of cond in this way: (or x y z ... w) == (cond (x) (y) (z) ... (t w)) See if and unless, which are sometimes stylistically more appropriate than or for conditional purposes. If it is necessary to test whether a predicate is true of one or more elements of a list or vector (element 0 or element 1 or element 2 or ...), then the function some may be useful. =============================================================================== 7. <#### Control Structure ####> Common Lisp provides a variety of special structures for organizing programs. Some have to do with flow of control (control structures), while others control access to variables (environment structures). Some of these features are implemented as special forms; others are implemented as macros, which typically expand into complex program fragments expressed in terms of special forms or other macros. Function application is the primary method for construction of Lisp programs. Operations are written as the application of a function to its arguments. Usually, Lisp programs are written as a large collection of small functions, each of which implements a simple operation. These functions operate by calling one another, and so larger operations are defined in terms of smaller ones. Lisp functions may call upon themselves recursively, either directly or indirectly. Locally defined functions (flet, labels) and macros (macrolet) are quite | versatile. The new symbol macro facility allows even more syntactic | flexibility. | While the Lisp language is more applicative in style than statement-oriented, it nevertheless provides many operations that produce side effects and consequently requires constructs for controlling the sequencing of side effects. The construct progn, which is roughly equivalent to an Algol begin-end block with all its semicolons, executes a number of forms sequentially, discarding the values of all but the last. Many Lisp control constructs include sequencing implicitly, in which case they are said to provide an "implicit progn." Other sequencing constructs include prog1 and prog2. For looping, Common Lisp provides the general iteration facility do as well as a variety of special-purpose iteration facilities for iterating or mapping over various data structures. Common Lisp provides the simple one-way conditionals when and unless, the simple two-way conditional if, and the more general multi-way conditionals such as cond and case. The choice of which form to use in any particular situation is a matter of taste and style. Constructs for performing non-local exits with various scoping disciplines are provided: block, return, return-from, catch, and throw. The multiple-value constructs provide an efficient way for a function to return more than one value; see values. ------------------------------------------------------------------------------- 7.1. <### Constants and Variables ###> Because some Lisp data objects are used to represent programs, one cannot always notate a constant data object in a program simply by writing the notation for the object unadorned; it would be ambiguous whether a constant object or a program fragment was intended. The quote special form resolves this ambiguity. There are two kinds of variables in Common Lisp, in effect: ordinary variables and function names. There are some similarities between the two kinds, and in a few cases there are similar functions for dealing with them, for example boundp and fboundp. However, for the most part the two kinds of variables are used for very different purposes: one to name defined functions, macros, and special forms, and the other to name data objects. X3J13 voted in March 1989 <89> to introduce the concept of a function-name, | which may be either a symbol or a two-element list whose first element is the | symbol setf and whose second element is a symbol. The primary purpose of this | is to allow setf expander functions to be CLOS generic functions with | user-defined methods. Many places in Common Lisp that used to require a symbol| for a function name are changed to allow 2-lists as well; for example, defun is| changed so that one may write (defun (setf foo) ...), and the function special | form is changed to accept any function-name. See also fdefinition. | | By convention, any function named (setf f) should return its first argument | as its only value, in order to preserve the specification that setf returns its| newvalue. See setf. | | Implementations are free to extend the syntax of function-names to include | lists beginning with additional symbols other than setf or lambda. | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7.1.1. <## Reference ##> The value of an ordinary variable may be obtained simply by writing the name of the variable as a form to be executed. Whether this is treated as the name of a special variable or a lexical variable is determined by the presence or absence of an applicable special declaration; see chapter 9. The following functions and special forms allow reference to the values of constants and variables in other ways. ---------<<>> quote quote object (quote x) simply returns x. The object is not evaluated and may be any Lisp object whatsoever. This construct allows any Lisp object to be written as a constant value in a program. For example: (setq a 43) (list a (cons a 3)) ==> (43 (43 . 3)) (list (quote a) (quote (cons a 3))) ==> (a (cons a 3)) Since quote forms are so frequently useful but somewhat cumbersome to type, a standard abbreviation is defined for them: any form f preceded by a single quote ( ' ) character is assumed to have (quote ) wrapped around it to make (quote f). For example: (setq x '(the magic quote hack)) is normally interpreted by read to mean (setq x (quote (the magic quote hack))) See section 22.1.3. X3J13 voted in January 1989 <36> to clarify that it is an error to | destructively modify any object that appears as a constant in executable code, | whether within a quote special form or as a self-evaluating form. | | See section 25.1 for a discussion of how quoted constants are treated by the | compiler. | X3J13 voted in March 1989 <147> to clarify that eval and compile are not | permitted either to copy or to coalesce ("collapse") constants (see eq) | appearing in the code they process; the resulting program behavior must refer | to objects that are eql to the corresponding objects in the source code. | Moreover, the constraints introduced by the votes on issues <34> and <32> on | what kinds of objects may appear as constants apply only to compile-file (see | section 25.1). | ---------<<>> function function fn The value of function is always the functional interpretation of fn; fn is interpreted as if it had appeared in the functional position of a function invocation. In particular, if fn is a symbol, the functional definition associated with that symbol is returned; see symbol-function. If fn is a lambda-expression, then a "lexical closure" is returned, that is, a function that when invoked will execute the body of the lambda-expression in such a way as to observe the rules of lexical scoping properly. X3J13 voted in June 1988 <90> to specify that the result of a function | special form is always of type function. This implies that a form (function | fn) may be interpreted as (the (function fn)). | | It is an error to use the function special form on a symbol that does not | denote a function in the lexical or global environment in which the special | form appears. Specifically, it is an error to use the function special form on| a symbol that denotes a macro or special form. Some implementations may choose| not to signal this error for performance reasons, but implementations are | forbidden to extend the semantics of function in this respect; that is, an | implementation is not allowed to define the failure to signal an error to be a | "useful" behavior. | X3J13 voted in March 1989 <89> to extend function to accept any function-name| (a symbol or a list whose car is setf -- see section 7.1) as well as | lambda-expressions. Thus one may write (function (setf cadr)) to refer to the | setf expansion function for cadr. | For example: (defun adder (x) (function (lambda (y) (+ x y)))) The result of (adder 3) is a function that will add 3 to its argument: (setq add3 (adder 3)) (funcall add3 5) ==> 8 This works because function creates a closure of the inner lambda-expression that is able to refer to the value 3 of the variable x even after control has returned from the function adder. More generally, a lexical closure in effect retains the ability to refer to lexically visible bindings, not just values. Consider this code: (defun two-funs (x) (list (function (lambda () x)) (function (lambda (y) (setq x y))))) (setq funs (two-funs 6)) (funcall (car funs)) ==> 6 (funcall (cadr funs) 43) ==> 43 (funcall (car funs)) ==> 43 The function two-funs returns a list of two functions, each of which refers to the binding of the variable x created on entry to the function two-funs when it was called with argument 6. This binding has the value 6 initially, but setq can alter a binding. The lexical closure created for the first lambda-expression does not "snapshot" the value 6 for x when the closure is created. The second function can be used to alter the binding (to 43, in the example), and this altered value then becomes accessible to the first function. In situations where a closure of a lambda-expression over the same set of bindings may be produced more than once, the various resulting closures may or may not be eq, at the discretion of the implementation. For example: (let ((x 5) (funs '())) (dotimes (j 10) (push #'(lambda (z) (if (null z) (setq x 0) (+ x z))) funs)) funs) The result of the above expression is a list of ten closures. Each logically requires only the binding of x. It is the same binding in each case, so the ten closures may or may not be the same identical (eq) object. On the other hand, the result of the expression (let ((funs '())) (dotimes (j 10) (let ((x 5)) (push (function (lambda (z) (if (null z) (setq x 0) (+ x z)))) funs))) funs) is also a list of ten closures. However, in this case no two of the closures may be eq, because each closure is over a distinct binding of x, and these bindings can be behaviorally distinguished because of the use of setq. The question of distinguishable behavior is important; the result of the simpler expression (let ((funs '())) (dotimes (j 10) (let ((x 5)) (push (function (lambda (z) (+ x z))) funs))) funs) is a list of ten closures that may be pairwise eq. Although one might think that a different binding of x is involved for each closure (which is indeed the case), the bindings cannot be distinguished because their values are identical and immutable, there being no occurrence of setq on x. A compiler would therefore be justified in transforming the expression to (let ((funs '())) (dotimes (j 10) (push (function (lambda (z) (+ 5 z))) funs)) funs) where clearly the closures may be the same after all. The general rule, then, is that the implementation is free to have two distinct evaluations of the same function form produce identical (eq) closures if it can prove that the two conceptually distinct resulting closures must in fact be behaviorally identical with respect to invocation. This is merely a permitted optimization; a perfectly valid implementation might simply cause every distinct evaluation of a function form to produce a new closure object not eq to any other. Frequently a compiler can deduce that a closure in fact does not need to close over any variable bindings. For example, in the code fragment (mapcar (function (lambda (x) (+ x 2))) y) the function (lambda (x) (+ x 2)) contains no references to any outside entity. In this important special case, the same "closure" may be used as the value for all evaluations of the function special form. Indeed, this value need not be a closure object at all; it may be a simple compiled function containing no environment information. This example is simply a special case of the foregoing discussion and is included as a hint to implementors familiar with previous methods of implementing Lisp. The distinction between closures and other kinds of functions is somewhat pointless, actually, as Common Lisp defines no particular representation for closures and no way to distinguish between closures and non-closure functions. All that matters is that the rules of lexical scoping be obeyed. Since function forms are so frequently useful but somewhat cumbersome to type, a standard abbreviation is defined for them: any form f preceded by #' (# followed by an apostrophe) is assumed to have (function ) wrapped around it to make (function f). For example, (remove-if #'numberp '(1 a b 3)) is normally interpreted by read to mean (remove-if (function numberp) '(1 a b 3)) See section 22.1.4. ---------<<>> symbol-value symbol-value symbol symbol-value returns the current value of the dynamic (special) variable named by symbol. An error occurs if the symbol has no value; see boundp and makunbound. Note that constant symbols are really variables that cannot be changed, and so symbol-value may be used to get the value of a named constant. In particular, symbol-value of a keyword will return that keyword. symbol-value cannot access the value of a lexical variable. This function is particularly useful for implementing interpreters for languages embedded in Lisp. The corresponding assignment primitive is set; alternatively, symbol-value may be used with setf. ---------<<>> symbol-function symbol-function symbol symbol-function returns the current global function definition named by symbol. An error is signalled if the symbol has no function definition; see fboundp. Note that the definition may be a function or may be an object representing a special form or macro. In the latter case, however, it is an error to attempt to invoke the object as a function. If it is desired to process macros, special forms, and functions equally well, as when writing an interpreter, it is best first to test the symbol with macro-function and special-form-p and then to invoke the functional value only if these two tests both yield false. This function is particularly useful for implementing interpreters for languages embedded in Lisp. symbol-function cannot access the value of a lexical function name produced by flet or labels; it can access only the global function value. The global function definition of a symbol may be altered by using setf with symbol-function. Performing this operation causes the symbol to have only the specified definition as its global function definition; any previous definition, whether as a macro or as a function, is lost. It is an error to attempt to redefine the name of a special form (see table 5-1). X3J13 voted in June 1988 <90> to clarify the behavior of symbol-function in | the light of the redefinition of the type function. | | * It is permissible to call symbol-function on any symbol for which fboundp | returns true. Note that fboundp must return true for a symbol naming a macro| or a special form. | | * If fboundp returns true for a symbol but the symbol denotes a macro or | special form, then the value returned by symbol-function is not well-defined | but symbol-function will not signal an error. | | * When symbol-function is used with setf the new value must be of type | function. It is an error to set the symbol-function of a symbol to a symbol,| a list, or the value returned by symbol-function on the name of a macro or a | special form. | ---------<<>> fdefinition | fdefinition function-name | | X3J13 voted in March 1989 <89> to add the function fdefinition to the | language. It is exactly like symbol-function except that its argument may be | any function-name (a symbol or a list whose car is setf -- see section 7.1); it| returns the current global function definition named by the argument | function-name. One may use fdefinition with setf to change the current global | function definition associated with a function-name. | ---------<<>> boundp boundp symbol boundp is true if the dynamic (special) variable named by symbol has a value; otherwise, it returns nil. See also set and makunbound. ---------<<>> fboundp fboundp symbol fboundp is true if the symbol has a global function definition. Note that fboundp is true when the symbol names a special form or macro. macro-function and special-form-p may be used to test for these cases. X3J13 voted in June 1988 <90> to emphasize that, despite the tightening of | the definition of the type function, fboundp must return true when the argument| names a special form or macro. | See also symbol-function and fmakunbound. X3J13 voted in March 1989 <89> to extend fboundp to accept any function-name | (a symbol or a list whose car is setf -- see section 7.1). Thus one may write | (fboundp '(setf cadr)) to determine whether a setf expansion function has been | globally defined for cadr. | ---------<<>> special-form-p special-form-p symbol The function special-form-p takes a symbol. If the symbol globally names a special form, then a non-nil value is returned; otherwise nil is returned. A returned non-nil value is typically a function of implementation-dependent nature that can be used to interpret (evaluate) the special form. It is possible for both special-form-p and macro-function to be true of a symbol. This is possible because an implementation is permitted to implement any macro also as a special form for speed. On the other hand, the macro definition must be available for use by programs that understand only the standard special forms listed in table 5-1. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7.1.2. <## Assignment ##> The following facilities allow the value of a variable (more specifically, the value associated with the current binding of the variable) to be altered. Such alteration is different from establishing a new binding. Constructs for establishing new bindings of variables are described in section 7.5. ---------<<>> setq setq {var form}* The special form (setq var1 form1 var2 form2 ...) is the "simple variable assignment statement" of Lisp. First form1 is evaluated and the result is stored in the variable var1, then form2 is evaluated and the result stored in var2, and so forth. The variables are represented as symbols, of course, and are interpreted as referring to static or dynamic instances according to the usual rules. Therefore setq may be used for assignment of both lexical and special variables. setq returns the last value assigned, that is, the result of the evaluation of its last argument. As a boundary case, the form (setq) is legal and returns nil. There must be an even number of argument forms. For example, in (setq x (+ 3 2 1) y (cons x nil)) x is set to 6, y is set to (6), and the setq returns (6). Note that the first assignment is performed before the second form is evaluated, allowing that form to use the new value of x. See also the description of setf, the Common Lisp "general assignment statement" that is capable of assigning to variables, array elements, and other locations. Some programmers choose to avoid setq as a matter of style, always using setf| for any kind of structure modification. Others use setq with simple variable | names and setf with all other generalized variables. | X3J13 voted in March 1989 <173> to specify that if any var refers not to an | ordinary variable but to a binding made by symbol-macrolet, then that var is | handled as if setf had been used instead of setq. | ---------<<>> psetq psetq {var form}* A psetq form is just like a setq form, except that the assignments happen in parallel. First all of the forms are evaluated, and then the variables are set to the resulting values. The value of the psetq form is nil. For example: (setq a 1) (setq b 2) (psetq a b b a) a ==> 2 b ==> 1 In this example, the values of a and b are exchanged by using parallel assignment. (If several variables are to be assigned in parallel in the context of a loop, the do construct may be appropriate.) See also the description of psetf, the Common Lisp "general parallel assignment statement" that is capable of assigning to variables, array elements, and other locations. X3J13 voted in March 1989 <173> to specify that if any var refers not to an | ordinary variable but to a binding made by symbol-macrolet, then that var is | handled as if psetf had been used instead of psetq. | ---------<<>> set set symbol value set allows alteration of the value of a dynamic (special) variable. set causes the dynamic variable named by symbol to take on value as its value. X3J13 voted in January 1989 <7> to clarify that the value may be any Lisp | datum whatsoever. | Only the value of the current dynamic binding is altered; if there are no bindings in effect, the most global value is altered. For example, (set (if (eq a b) 'c 'd) 'foo) will either set c to foo or set d to foo, depending on the outcome of the test (eq a b). set returns value as its result. set cannot alter the value of a local (lexically bound) variable. The special form setq is usually used for altering the values of variables (lexical or dynamic) in programs. set is particularly useful for implementing interpreters for languages embedded in Lisp. See also progv, a construct that performs binding rather than assignment of dynamic variables. ---------<<>> makunbound makunbound symbol ---------<<>> fmakunbound fmakunbound symbol makunbound causes the dynamic (special) variable named by symbol to become unbound (have no value). fmakunbound does the analogous thing for the global function definition named by symbol. For example: (setq a 1) a ==> 1 (makunbound 'a) a ==> causes an error (defun foo (x) (+ x 1)) (foo 4) ==> 5 (fmakunbound 'foo) (foo 4) ==> causes an error Both functions return symbol as the result value. X3J13 voted in March 1989 <89> to extend fmakunbound to accept any | function-name (a symbol or a list whose car is setf -- see section 7.1). Thus | one may write (fmakunbound '(setf cadr)) to remove any global definition of a | setf expansion function for cadr. | ------------------------------------------------------------------------------- 7.2. <### Generalized Variables ###> In Lisp, a variable can remember one piece of data, that is, one Lisp object. The main operations on a variable are to recover that object and to alter the variable to remember a new object; these operations are often called access and update operations. The concept of variables named by symbols can be generalized to any storage location that can remember one piece of data, no matter how that location is named. Examples of such storage locations are the car and cdr of a cons, elements of an array, and components of a structure. For each kind of generalized variable, typically there are two functions that implement the conceptual access and update operations. For a variable, merely mentioning the name of the variable accesses it, while the setq special form can be used to update it. The function car accesses the car of a cons, and the function rplaca updates it. The function symbol-value accesses the dynamic value of a variable named by a given symbol, and the function set updates it. Rather than thinking about two distinct functions that respectively access and update a storage location somehow deduced from their arguments, we can instead simply think of a call to the access function with given arguments as a name for the storage location. Thus, just as x may be considered a name for a storage location (a variable), so (car x) is a name for the car of some cons (which is in turn named by x). Now, rather than having to remember two functions for each kind of generalized variable (having to remember, for example, that rplaca corresponds to car), we adopt a uniform syntax for updating storage locations named in this way, using the setf macro. This is analogous to the way we use the setq special form to convert the name of a variable (which is also a form that accesses it) into a form that updates it. The uniformity of this approach is illustrated in the following table. Access Function Update Function Update Using setf ------------------------------------------------------------------------- x (setq x datum) (setf x datum) (car x) (rplaca x datum) (setf (car x) datum) (symbol-value x) (set x datum) (setf (symbol-value x) datum) ------------------------------------------------------------------------- setf is actually a macro that examines an access form and produces a call to the corresponding update function. Given the existence of setf in Common Lisp, it is not necessary to have setq, rplaca, and set; they are redundant. They are retained in Common Lisp because of their historical importance in Lisp. However, most other update functions (such as putprop, the update function for get) have been eliminated from Common Lisp in the expectation that setf will be uniformly used in their place. ---------<<>> setf setf {place newvalue}* (setf place newvalue) takes a form place that when evaluated accesses a data object in some location and "inverts" it to produce a corresponding form to update the location. A call to the setf macro therefore expands into an update form that stores the result of evaluating the form newvalue into the place referred to by the access form. If more than one place-newvalue pair is specified, the pairs are processed sequentially; that is, (setf place1 newvalue1 place2 newvalue2 ... placen newvaluen) is precisely equivalent to (progn (setf place1 newvalue1) (setf place2 newvalue2) ... (setf placen newvaluen)) For consistency, it is legal to write (setf), which simply returns nil. The form place may be any one of the following: * The name of a variable (either lexical or dynamic). * A function call form whose first element is the name of any one of the following functions: aref car svref nth cdr get elt caar getf symbol-value rest cadr gethash symbol-function first cdar documentation symbol-plist second cddr fill-pointer macro-function third caaar caaaar cdaaar fourth caadr caaadr cdaadr fifth cadar caadar cdadar sixth caddr caaddr cdaddr seventh cdaar cadaar cddaar eighth cdadr cadadr cddadr ninth cddar caddar cdddar tenth cdddr cadddr cddddr X3J13 voted in March 1988 <6> to add row-major-aref to this list. | X3J13 voted in June 1989 <49> to add compiler-macro-function to this list. | X3J13 voted in March 1989 <89> to clarify that this rule applies only when | the function name refers to a global function definition and not to a locally| defined function or macro. | * A function call form whose first element is the name of a selector function constructed by defstruct. X3J13 voted in March 1989 <89> to clarify that this rule applies only when | the function name refers to a global function definition and not to a locally| defined function or macro. | * A function call form whose first element is the name of any one of the following functions, provided that the new value is of the specified type so that it can be used to replace the specified "location" (which is in each of these cases not truly a generalized variable): Function Name Required Type : ----------------------------- : char string-char : schar string-char : bit bit : sbit bit : subseq sequence : ----------------------------- : X3J13 voted in March 1989 <11> to eliminate the type string-char and to | redefine string to be the union of one or more specialized vector types, the | types of whose elements are subtypes of the type character. In the preceding| table, the type string-char should be replaced by some such phrase as "the | element-type of the argument vector." | X3J13 voted in March 1989 <89> to clarify that this rule applies only when | the function name refers to a global function definition and not to a locally| defined function or macro. | In the case of subseq, the replacement value must be a sequence whose elements may be contained by the sequence argument to subseq. (Note that this is not so stringent as to require that the replacement value be a sequence of the same type as the sequence of which the subsequence is specified.) If the length of the replacement value does not equal the length of the subsequence to be replaced, then the shorter length determines the number of elements to be stored, as for the function replace. * A function call form whose first element is the name of any one of the following functions, provided that the specified argument to that function is in turn a place form; in this case the new place has stored back into it the result of applying the specified "update" function (which is in each of these cases not a true update function): Function Name Argument That Is a place Update Function Used ------------------------------------------------------------------- char-bit first set-char-bit ldb second dpb mask-field second deposit-field ------------------------------------------------------------------- X3J13 voted in March 1989 <11> to eliminate char-bit and set-char-bit. | X3J13 voted in March 1989 <89> to clarify that this rule applies only when | the function name refers to a global function definition and not to a locally| defined function or macro. | * A the type declaration form, in which case the declaration is transferred to the newvalue form, and the resulting setf form is analyzed. For example, (setf (the integer (cadr x)) (+ y 3)) is processed as if it were (setf (cadr x) (the integer (+ y 3))) * A call to apply where the first argument form is of the form #'name, that is, (function name), where name is the name of a function, calls to which are recognized as places by setf. Suppose that the use of setf with apply looks like this: (setf (apply #'name x1 x2 ... xn rest) x0) The setf method for the function name must be such that (setf (name z1 z2 ... zm) z0) expands into a store form (storefn zi1 zi2 ... zik zm) That is, it must expand into a function call such that all arguments but the last may be any permutation or subset of the new value z0 and the arguments of the access form, but the last argument of the storing call must be the same as the last argument of the access call. See define-setf-method for more details on accessing and storing forms. Given this, the setf-of-apply form shown above expands into (apply #'storefn xi1 xi2 ... xik rest) As an example, suppose that the variable indexes contains a list of subscripts for a multidimensional array foo whose rank is not known until run time. One may access the indicated element of the array by writing (apply #'aref foo indexes) and one may alter the value of the indicated element to that of newvalue by writing (setf (apply #'aref foo indexes) newvalue) X3J13 voted in March 1989 <89> to clarify that this rule applies only when | the function name apply refers to the global function definition and not to a| locally defined function or macro named apply. | * A macro call, in which case setf expands the macro call and then analyzes the resulting form. X3J13 voted in March 1989 <89> to clarify that this step uses macroexpand-1, | not macroexpand. This allows the chance to apply any of the rules preceding | this one to any of the intermediate expansions. | * Any form for which a defsetf or define-setf-method declaration has been made. X3J13 voted in March 1989 <89> to clarify that this rule applies only when | the function name in the form refers to a global function definition and not | to a locally defined function or macro. | X3J13 voted in March 1989 <89> to add one more rule to the preceding list, | coming after all those listed above: | | * Any other list whose first element is a symbol (call it f). In this case, | the call to setf expands into a call to the function named by the list | (setf f) (see section 7.1). The first argument is the new value and the | remaining arguments are the values of the remaining elements of place. This | expansion occurs regardless of whether either f or (setf f) is defined as a | function locally, globally, or not at all. For example, | (setf (f arg1 arg2 ...) newvalue) | expands into a form with the same effect and value as | (let ((#:temp1 arg1) ; Force correct order of evaluation | (#:temp2 arg2) | ... | (#:temp0 newvalue)) | (funcall (function (setf f)) | #:temp0 | #:temp1 | #:temp2 ...)) | | By convention, any function named (setf f) should return its first argument | as its only value, in order to preserve the specification that setf returns | its newvalue. | X3J13 voted in March 1989 <173> to add this case as well: | | * A variable reference that refers to a symbol macro definition made by | symbol-macrolet, in which case setf expands the reference and then analyzes | the resulting form. | setf carefully arranges to preserve the usual left-to-right order in which the various subforms are evaluated. On the other hand, the exact expansion for any particular form is not guaranteed and may even be implementation-dependent; all that is guaranteed is that the expansion of a setf form will be an update form that works for that particular implementation, and that the left-to-right evaluation of subforms is preserved. The ultimate result of evaluating a setf form is the value of newvalue. Therefore (setf (car x) y) does not expand into precisely (rplaca x y), but into something more like (let ((G1 x) (G2 y)) (rplaca G1 G2) G2) the precise expansion being implementation-dependent. The user can define new setf expansions by using defsetf. X3J13 voted in June 1989 <159> to extend the specification of setf to allow a| place whose setf method has more than one store variable (see | define-setf-method). In such a case as many values are accepted from the | newvalue form as there are store variables; extra values are ignored and | missing values default to nil, as is usual in situations involving multiple | values. | A proposal was submitted to X3J13 in September 1989 to add a setf method for | values so that one could in fact write, for example, | (setf (values quotient remainder) | (truncate linewidth tabstop)) | but unless this proposal is accepted users will have to define a setf method | for values themselves (not a difficult task). | ---------<<>> psetf psetf {place newvalue}* psetf is like setf except that if more than one place-newvalue pair is specified, then the assignments of new values to places are done in parallel. More precisely, all subforms that are to be evaluated are evaluated from left to right; after all evaluations have been performed, all of the assignments are performed in an unpredictable order. (The unpredictability matters only if more than one place form refers to the same place.) psetf always returns nil. X3J13 voted in June 1989 <159> to extend the specification of psetf to allow | a place whose setf method has more than one store variable (see | define-setf-method). In such a case as many values are accepted from the | newvalue form as there are store variables; extra values are ignored and | missing values default to nil, as is usual in situations involving multiple | values. | ---------<<>> shiftf shiftf {place}+ newvalue Each place form may be any form acceptable as a generalized variable to setf. In the form (shiftf place1 place2 ... placen newvalue), the values in place1 through placen are accessed and saved, and newvalue is evaluated, for a total of n+1 values in all. Values 2 through n+1 are then stored into place1 through placen, and value 1 (the original value of place1) is returned. It is as if all the places form a shift register; the newvalue is shifted in from the right, all values shift over to the left one place, and the value shifted out of place1 is returned. For example: (setq x (list 'a 'b 'c)) ==> (a b c) (shiftf (cadr x) 'z) ==> b and now x ==> (a z c) (shiftf (cadr x) (cddr x) 'q) ==> z and now x ==> (a (c) . q) The effect of (shiftf place1 place2 ... placen newvalue) is equivalent to (let ((var1 place1) (var2 place2) ... (varn placen)) (setf place1 var2) (setf place2 var3) ... (setf placen newvalue) var1) except that the latter would evaluate any subforms of each place twice, whereas shiftf takes care to evaluate them only once. For example: (setq n 0) (setq x '(a b c d)) (shiftf (nth (setq n (+ n 1)) x) 'z) ==> b and now x ==> (a z c d) but (setq n 0) (setq x '(a b c d)) (prog1 (nth (setq n (+ n 1)) x) (setf (nth (setq n (+ n 1)) x) 'z)) ==> b and now x ==> (a b z d) Moreover, for certain place forms shiftf may be significantly more efficient than the prog1 version. X3J13 voted in June 1989 <159> to extend the specification of shiftf to allow| a place whose setf method has more than one store variable (see | define-setf-method). In such a case as many values are accepted from the | newvalue form as there are store variables; extra values are ignored and | missing values default to nil, as is usual in situations involving multiple | values. | . . . . . . . . . . . . . . . . . . . . Rationale: shiftf and rotatef have been included in Common Lisp as generalizations of two-argument versions formerly called swapf and exchf. The two-argument versions have been found to be very useful, but the names were easily confused. The generalization to many argument forms and the change of names were both inspired by the work of Suzuki [47], which indicates that use of these primitives can make certain complex pointer- manipulation programs clearer and easier to prove correct. . . . . . . . . . . . . . . . . . . . . ---------<<>> rotatef rotatef {place}* Each place form may be any form acceptable as a generalized variable to setf. In the form (rotatef place1 place2 ... placen), the values in place1 through placen are accessed and saved. Values 2 through n and value 1 are then stored into place1 through placen. It is as if all the places form an end-around shift register that is rotated one place to the left, with the value of place1 being shifted around the end to placen. Note that (rotatef place1 place2) exchanges the contents of place1 and place2. The effect of (rotatef place1 place2 ... placen) is roughly equivalent to (psetf place1 place2 place2 place3 ... placen place1) except that the latter would evaluate any subforms of each place twice, whereas rotatef takes care to evaluate them only once. Moreover, for certain place forms rotatef may be significantly more efficient. rotatef always returns nil. X3J13 voted in June 1989 <159> to extend the specification of rotatef to | allow a place whose setf method has more than one store variable (see | define-setf-method). In such a case as many values are accepted from the | newvalue form as there are store variables; extra values are ignored and | missing values default to nil, as is usual in situations involving multiple | values. | Other macros that manipulate generalized variables include getf, remf, incf, decf, push, pop, assert, ctypecase, and ccase. Macros that manipulate generalized variables must guarantee the "obvious" semantics: subforms of generalized-variable references are evaluated exactly as many times as they appear in the source program, and they are evaluated in exactly the same order as they appear in the source program. In generalized-variable references such as shiftf, incf, push, and setf of ldb, the generalized variables are both read and written in the same reference. Preserving the source program order of evaluation and the number of evaluations is particularly important. As an example of these semantic rules, in the generalized-variable reference (setf reference value) the value form must be evaluated after all the subforms of the reference because the value form appears to the right of them. The expansion of these macros must consist of code that follows these rules or has the same effect as such code. This is accomplished by introducing temporary variables bound to the subforms of the reference. As an optimization in the implementation, temporary variables may be eliminated whenever it can be proved that removing them has no effect on the semantics of the program. For example, a constant need never be saved in a temporary variable. A variable, or for that matter any form that does not have side effects, need not be saved in a temporary variable if it can be proved that its value will not change within the scope of the generalized-variable reference. Common Lisp provides built-in facilities to take care of these semantic complications and optimizations. Since the required semantics can be guaranteed by these facilities, the user does not have to worry about writing correct code for them, especially in complex cases. Even experts can become confused and make mistakes while writing this sort of code. X3J13 voted in March 1988 <146> to clarify the preceding discussion about the| order of evaluation of subforms in calls to setf and related macros. The | general intent is clear: evaluation proceeds from left to right whenever | possible. However, the left-to-right rule does not remove the obligation on | writers of macros and define-setf-method to work to ensure left-to-right order | of evaluation. | | Let it be emphasized that, in the following discussion, a form is something | whose syntactic use is such that it will be evaluated. A subform means a form | that is nested inside another form, not merely any Lisp object nested inside a | form regardless of syntactic context. | | The evaluation ordering of subforms within a generalized variable reference | is determined by the order specified by the second value returned by | get-setf-method. For all predefined generalized variable references (getf, | ldb), this order of evaluation is exactly left-to-right. When a generalized | variable reference is derived from a macro expansion, this rule is applied | after the macro is expanded to find the appropriate generalized variable | reference. | | This is intended to make it clear that if the user writes a defmacro or | define-setf-method macro that doesn't preserve left-to-right evaluation order, | the order specified in the user's code holds. For example, given | (defmacro wrong-order (x y) `(getf ,y ,x)) | then | (push value (wrong-order place1 place2)) | will evaluate place2 first and then place1 because that is the order they are | evaluated in the macro expansion. | | For the macros that manipulate generalized variables (push, pushnew, getf, | remf, incf, decf, shiftf, rotatef, psetf, setf, pop, and those defined with | define-modify-macro) the subforms of the macro call are evaluated exactly once | in left-to-right order, with the subforms of the generalized variable | references evaluated in the order specified above. | | Each of push, pushnew, getf, remf, incf, decf, shiftf, rotatef, psetf, and | pop evaluates all subforms before modifying any of the generalized variable | locations. Moreover, setf itself, in the case when a call on it has more than | two arguments, performs its operation on each pair in sequence. That is, in | (setf place1 value1 place2 value2 ...) | the subforms of place1 and value1 are evaluated, the location specified by | place1 is modified to contain the value returned by value1, and then the rest | of the setf form is processed in a like manner. | | For the macros check-type, ctypecase, and ccase, subforms of the generalized | variable reference are evaluated once per test of a generalized variable, but | they may be evaluated again if the type check fails (in the case of check-type)| or if none of the cases holds (in ctypecase or ccase). | | For the macro assert, the order of evaluation of the generalized variable | references is not specified. | Another reason for building in these functions is that the appropriate optimizations will differ from implementation to implementation. In some implementations most of the optimization is performed by the compiler, while in others a simpler compiler is used and most of the optimization is performed in the macros. The cost of binding a temporary variable relative to the cost of other Lisp operations may differ greatly between one implementation and another, and some implementations may find it best never to remove temporary variables except in the simplest cases. A good example of the issues involved can be seen in the following generalized-variable reference: (incf (ldb byte-field variable)) This ought to expand into something like (setq variable (dpb (1+ (ldb byte-field variable)) byte-field variable)) In this expansion example we have ignored the further complexity of returning the correct value, which is the incremented byte, not the new value of variable. Note that the variable byte-field is evaluated twice, and the variable variable is referred to three times: once as the location in which to store a value, and twice during the computation of that value. Now consider this expression: (incf (ldb (aref byte-fields (incf i)) (aref (determine-words-array) i))) It ought to expand into something like this: (let ((temp1 (aref byte-fields (incf i))) (temp2 (determine-words-array))) (setf (aref temp2 i) (dpb (1+ (ldb temp1 (aref temp2 i))) temp1 (aref temp2 i)))) Again we have ignored the complexity of returning the correct value. What is important here is that the expressions (incf i) and (determine-words-array) must not be duplicated because each may have a side effect or be affected by side effects. X3J13 voted in January 1989 <160> to specify more precisely the order of | evaluation of subforms when setf is used with an access function that itself | takes a place as an argument, for example, ldb, mask-field, and getf. (The | vote also discussed the function char-bit, but another vote <11> removed that | function from the language.) The setf methods for such accessors produce | expansions that effectively require explicit calls to get-setf-method. | | The code produced as the macro expansion of a setf form that itself admits a | generalized variable as an argument must essentially do the following major | steps: | | * It evaluates the value-producing subforms, in left-to-right order, and binds | the temporary variables to them; this is called binding the temporaries. | | * It reads the value from the generalized variable, using the supplied | accessing form, to get the old value; this is called doing the access. Note | that this is done after all the evaluations of the preceding step, including | any side effects they may have. | | * It binds the store variable to a new value, and then installs this new value | into the generalized variable using the supplied storing form; this is called| doing the store. | | Doing the access for a generalized variable reference is not part of the | series of evaluations that must be done in left-to-right order. | | The place-specifier forms ldb, mask-field, and getf admit (other) place | specifiers as arguments. During the setf expansion of these forms, it is | necessary to call get-setf-method to determine how the inner, nested | generalized variable must be treated. | | In a form such as | (setf (ldb byte-spec place-form) newvalue-form) | the place referred to by the place-form must always be both accessed and | updated; note that the update is to the generalized variable specified by | place-form, not to any object of type integer. | | Thus this call to setf should generate code to do the following: | | * Evaluate byte-spec and bind into a temporary | | * Bind the temporaries for place-form | | * Evaluate newvalue-form and bind into the store variable | | * Do the access to place-form | | * Do the store into place-form with the given bit-field of the accessed integer| replaced with the value in the store variable | | If the evaluation of newvalue-form alters what is found in the given place --| such as setting a different bit-field of the integer -- then the change of the | bit-field denoted by byte-spec will be to that altered integer, because the | access step must be done after the newvalue-form evaluation. Nevertheless, the| evaluations required for binding the temporaries are done before the evaluation| of the newvalue-form, thereby preserving the required left-to-right evaluation | order. | | The treatment of mask-field is similar to that of ldb. | | In a form such as: | (setf (getf place-form ind-form) newvalue-form) | the place referred to by the place-form must always be both accessed and | updated; note that the update is to the generalized variable specified by | place-form, not necessarily to the particular list which is the property list | in question. | | Thus this call to setf should generate code to do the following: | | * Bind the temporaries for place-form | | * Evaluate ind-form and bind into a temporary | | * Evaluate the newvalue-form and bind into the store variable | | * Do the access to place-form | | * Do the store into place-form with a possibly new property list obtained by | combining the results of the evaluations and the access | | If the evaluation of newvalue-form alters what is found in the given place --| such as setting a different named property in the list -- then the change of | the property denoted by ind-form will be to that altered list, because the | access step is done after the newvalue-form evaluation. Nevertheless, the | evaluations required for binding the temporaries are done before the evaluation| of the newvalue-form, thereby preserving the required left-to-right evaluation | order. | | Note that the phrase "possibly new property list" treats the implementation | of property lists as a "black box"; it can mean that the former property list | is somehow destructively re-used, or it can mean partial or full copying of it.| A side effect may or may not occur; therefore setf must proceed as if the | resultant property list were a different copy needing to be stored back into | the generalized variable. | The Common Lisp facilities provided to deal with these semantic issues include: * Built-in macros such as setf and push that follow the semantic rules. * The define-modify-macro macro, which allows new generalized-variable manipulating macros (of a certain restricted kind) to be defined easily. It takes care of the semantic rules automatically. * The defsetf macro, which allows new types of generalized-variable references to be defined easily. It takes care of the semantic rules automatically. * The define-setf-method macro and the get-setf-method function, which provide access to the internal mechanisms when it is necessary to define a complicated new type of generalized-variable reference or generalized-variable-manipulating macro. Also important are the changes that allow lexical environments to be used in | appropriate ways in setf methods. | ---------<<>> define-modify-macro define-modify-macro name lambda-list function [doc-string] This macro defines a read-modify-write macro named name. An example of such a macro is incf. The first subform of the macro will be a generalized-variable reference. The function is literally the function to apply to the old contents of the generalized-variable to get the new contents; it is not evaluated. lambda-list describes the remaining arguments for the function; these arguments come from the remaining subforms of the macro after the generalized-variable reference. lambda-list may contain &optional and &rest markers. (The &key marker is not permitted here; &rest suffices for the purposes of define-modify-macro.) doc-string is documentation for the macro name being defined. The expansion of a define-modify-macro is equivalent to the following, except that it generates code that follows the semantic rules outlined above. (defmacro name (reference . lambda-list) doc-string `(setf ,reference (function ,reference ,arg1 ,arg2 ...))) where arg1, arg2, ..., are the parameters appearing in lambda-list; appropriate provision is made for a &rest parameter. As an example, incf could have been defined by: (define-modify-macro incf (&optional (delta 1)) +) An example of a possibly useful macro not predefined in Common Lisp is (define-modify-macro unionf (other-set &rest keywords) union) X3J13 voted in March 1988 <96> to specify that define-modify-macro creates | macros that take &environment arguments and perform the equivalent of correctly| passing such lexical environments to get-setf-method in order to correctly | maintain lexical references. | ---------<<>> defsetf defsetf access-fn { update-fn [doc-string] | lambda-list (store-variable) [[ {declaration}* | doc-string ]] {form}* } This defines how to setf a generalized-variable reference of the form (access-fn ...). The value of a generalized-variable reference can always be obtained simply by evaluating it, so access-fn should be the name of a function or a macro. The user of defsetf provides a description of how to store into the generalized-variable reference and return the value that was stored (because setf is defined to return this value). The implementation of defsetf takes care of ensuring that subforms of the reference are evaluated exactly once and in the proper left-to-right order. In order to do this, defsetf requires that access-fn be a function or a macro that evaluates its arguments, behaving like a function. Furthermore, a setf of a call on access-fn will also evaluate all of access-fn's arguments; it cannot treat any of them specially. This means that defsetf cannot be used to describe how to store into a generalized variable that is a byte, such as (ldb field reference). To handle situations that do not fit the restrictions imposed by defsetf, use define-setf-method, which gives the user additional control at the cost of increased complexity. A defsetf declaration may take one of two forms. The simple form is (defsetf access-fn update-fn {doc-string}*) The update-fn must name a function (or macro) that takes one more argument than access-fn takes. When setf is given a place that is a call on access-fn, it expands into a call on update-fn that is given all the arguments to access-fn and also, as its last argument, the new value (which must be returned by update-fn as its value). For example, the effect of (defsetf symbol-value set) is built into the Common Lisp system. This causes the expansion (setf (symbol-value foo) fu) --> (set foo fu) for example. Note that (defsetf car rplaca) would be incorrect because rplaca does not return its last argument. The complex form of defsetf looks like (defsetf access-fn lambda-list (store-variable) . body) and resembles defmacro. The body must compute the expansion of a setf of a call on access-fn. The lambda-list describes the arguments of access-fn. &optional, &rest, and &key markers are permitted in lambda-list. Optional arguments may have defaults and "supplied-p" flags. The store-variable describes the value to be stored into the generalized-variable reference. . . . . . . . . . . . . . . . . . . . . Rationale: The store-variable is enclosed in parentheses to provide for an extension to multiple store variables that would receive multiple values from the second subform of setf. The rules given below for coding setf methods discuss the proper handling of multiple store variables to allow for the possibility that this extension may be incorporated into Common Lisp in the future. . . . . . . . . . . . . . . . . . . . . The body forms can be written as if the variables in the lambda-list were bound to subforms of the call on access-fn and the store-variable were bound to the second subform of setf. However, this is not actually the case. During the evaluation of the body forms, these variables are bound to names of temporary variables, generated as if by gensym or gentemp, that will be bound by the expansion of setf to the values of those subforms. This binding permits the body forms to be written without regard for order-of-evaluation issues. defsetf arranges for the temporary variables to be optimized out of the final result in cases where that is possible. In other words, an attempt is made by defsetf to generate the best code possible in a particular implementation. Note that the code generated by the body forms must include provision for returning the correct value (the value of store-variable). This is handled by the body forms rather than by defsetf because in many cases this value can be returned at no extra cost, by calling a function that simultaneously stores into the generalized variable and returns the correct value. An example of the use of the complex form of defsetf: (defsetf subseq (sequence start &optional end) (new-sequence) `(progn (replace ,sequence ,new-sequence :start1 ,start :end1 ,end) ,new-sequence)) X3J13 voted in March 1988 <78> to specify that the body of the expander | function defined by the complex form of defsetf is implicitly enclosed in a | block construct whose name is the same as the name of the access-fn. Therefore| return-from may be used to exit from the function. | X3J13 voted in March 1989 <50> to clarify that, while defining forms normally| appear at top level, it is meaningful to place them in non-top-level contexts; | the complex form of defsetf must define the expander function within the | enclosing lexical environment, not within the global environment. | The underlying theory by which setf and related macros arrange to conform to the semantic rules given above is that from any generalized-variable reference one may derive its "setf method," which describes how to store into that reference and which subforms of it are evaluated. . . . . . . . . . . . . . . . . . . . . Compatibility note: To avoid confusion, it should be noted that the use of the word "method" here in connection with setf has nothing to do with its use in Lisp Machine Lisp in connection with message-passing and the Lisp Machine Lisp "flavor system." And of course it also has nothing to do with the methods in the Common Lisp | Object System <12>. | . . . . . . . . . . . . . . . . . . . . Given knowledge of the subforms of the reference, it is possible to avoid evaluating them multiple times or in the wrong order. A setf method for a given access form can be expressed as five values: * A list of temporary variables * A list of value forms (subforms of the given form) to whose values the temporary variables are to be bound * A second list of temporary variables, called store variables * A storing form * An accessing form The temporary variables will be bound to the values of the value forms as if by let*; that is, the value forms will be evaluated in the order given and may refer to the values of earlier value forms by using the corresponding variables. The store variables are to be bound to the values of the newvalue form, that is, the values to be stored into the generalized variable. In almost all cases only a single value is to be stored, and there is only one store variable. The storing form and the accessing form may contain references to the temporary variables (and also, in the case of the storing form, to the store variables). The accessing form returns the value of the generalized variable. The storing form modifies the value of the generalized variable and guarantees to return the values of the store variables as its values; these are the correct values for setf to return. (Again, in most cases there is a single store variable and thus a single value to be returned.) The value returned by the accessing form is, of course, affected by execution of the storing form, but either of these forms may be evaluated any number of times and therefore should be free of side effects (other than the storing action of the storing form). The temporary variables and the store variables are generated names, as if by gensym or gentemp, so that there is never any problem of name clashes among them, or between them and other variables in the program. This is necessary to make the special forms that do more than one setf in parallel work properly; these are psetf, shiftf, and rotatef. Computation of the setf method must always create new variable names; it may not return the same ones every time. Some examples of setf methods for particular forms: * For a variable x: () () (g0001) (setq x g0001) x * For (car exp): (g0002) (exp) (g0003) (progn (rplaca g0002 g0003) g0003) (car g0002) * For (subseq seq s e): (g0004 g0005 g0006) (seq s e) (g0007) (progn (replace g0004 g0007 :start1 g0005 :end1 g0006) g0007) (subseq g0004 g0005 g0006) ---------<<>> define-setf-method define-setf-method access-fn lambda-list [[ {declaration}* | doc-string ]] {form}* This defines how to setf a generalized-variable reference that is of the form (access-fn...). The value of a generalized-variable reference can always be obtained simply by evaluating it, so access-fn should be the name of a function or a macro. The lambda-list describes the subforms of the generalized-variable reference, as with defmacro. The result of evaluating the forms in the body must be five values representing the setf method, as described above. Note that define-setf-method differs from the complex form of defsetf in that while the body is being executed the variables in lambda-list are bound to parts of the generalized-variable reference, not to temporary variables that will be bound to the values of such parts. In addition, define-setf-method does not have defsetf's restriction that access-fn must be a function or a function-like macro; an arbitrary defmacro destructuring pattern is permitted in lambda-list. By definition there are no good small examples of define-setf-method because the easy cases can all be handled by defsetf. A typical use is to define the setf method for ldb: ;;; SETF method for the form (LDB bytespec int). : ;;; Recall that the int form must itself be suitable for SETF. : (define-setf-method ldb (bytespec int) : (multiple-value-bind (temps vals stores : store-form access-form) : (get-setf-method int) ;Get SETF method for int : (let ((btemp (gensym)) ;Temp var for byte specifier : (store (gensym)) ;Temp var for byte to store : (stemp (first stores))) ;Temp var for int to store : ;; Return the SETF method for LDB as five values. : (values (cons btemp temps) ;Temporary variables : (cons bytespec vals) ;Value forms : (list store) ;Store variables : `(let ((,stemp (dpb ,store ,btemp ,access-form))) : ,store-form : ,store) ;Storing form : `(ldb ,btemp ,access-form) ;Accessing form : )))) : X3J13 voted in March 1988 <96> to specify that the &environment lambda-list | keyword may appear in the lambda-list in the same manner as for defmacro in | order to obtain the lexical environment of the call to the setf macro. The | preceding example should be modified to take advantage of this new feature. | The setf method must accept an &environment parameter, which will receive the | lexical environment of the call to setf; this environment must then be given to| get-setf-method in order that it may correctly use any locally bound setf | method that might be applicable to the place form that appears as the second | argument to ldb in the call to setf. | | ;;; SETF method for the form (LDB bytespec int). | ;;; Recall that the int form must itself be suitable for SETF. | ;;; Note the use of an &environment parameter to receive the | ;;; lexical environment of the call for use with GET-SETF-METHOD. | (define-setf-method ldb (bytespec int &environment env) | (multiple-value-bind (temps vals stores | store-form access-form) | (get-setf-method int env) ;Get SETF method for int | (let ((btemp (gensym)) ;Temp var for byte specifier | (store (gensym)) ;Temp var for byte to store | (stemp (first stores))) ;Temp var for int to store | ;; Return the SETF method for LDB as five values. | (values (cons btemp temps) ;Temporary variables | (cons bytespec vals) ;Value forms | (list store) ;Store variables | `(let ((,stemp (dpb ,store ,btemp ,access-form))) | ,store-form | ,store) ;Storing form | `(ldb ,btemp ,access-form) ;Accessing form | )))) | X3J13 voted in March 1988 <78> to specify that the body of the expander | function defined by define-setf-method is implicitly enclosed in a block | construct whose name is the same as the name of the access-fn. Therefore | return-from may be used to exit from the function. | X3J13 voted in March 1989 <50> to clarify that, while defining forms normally| appear at top level, it is meaningful to place them in non-top-level contexts; | define-setf-method must define the expander function within the enclosing | lexical environment, not within the global environment. | ---------<<>> get-setf-method : get-setf-method form : : get-setf-method returns five values constituting the setf method for form. : The form must be a generalized-variable reference. get-setf-method takes care : of error-checking and macro expansion and guarantees to return exactly one : store variable. : : As an example, an extremely simplified version of setf, allowing no more and : no fewer than two subforms, containing no optimization to remove unnecessary : variables, and not allowing storing of multiple values, could be defined by: : : (defmacro setf (reference value) : (multiple-value-bind (vars vals stores store-form access-form) : (get-setf-method reference) : (declare (ignore access-form)) : `(let* ,(mapcar #'list : (append vars stores) : (append vals (list value))) : ,store-form))) : X3J13 voted in March 1988 <96> to add an optional environment argument to | get-setf-method. The revised definition and example are as follows. | | ---------<<>> get-setf-method | get-setf-method form &optional env | | get-setf-method returns five values constituting the setf method for form. | The form must be a generalized-variable reference. The env must be an | environment of the sort obtained through the &environment lambda-list keyword; | if env is nil or omitted, the null lexical environment is assumed. | get-setf-method takes care of error checking and macro expansion and guarantees| to return exactly one store variable. | | As an example, an extremely simplified version of setf, allowing no more and | no fewer than two subforms, containing no optimization to remove unnecessary | variables, and not allowing storing of multiple values, could be defined by: | | (defmacro setf (reference value &environment env) | (multiple-value-bind (vars vals stores store-form access-form) | (get-setf-method reference env) ; Note use of environment | (declare (ignore access-form)) | `(let* ,(mapcar #'list | (append vars stores) | (append vals (list value))) | ,store-form))) | ---------<<>> get-setf-method-multiple-value : get-setf-method-multiple-value form : : get-setf-method-multiple-value returns five values constituting the setf : method for form. The form must be a generalized-variable reference. This is : the same as get-setf-method except that it does not check the number of store : variables; use this in cases that allow storing multiple values into a : generalized variable. There are no such cases in standard Common Lisp, but : this function is provided to allow for possible extensions. : X3J13 voted in March 1988 <96> to add an optional environment argument to | get-setf-method. The revised definition is as follows. | | ---------<<>> get-setf-method-multiple-value | get-setf-method-multiple-value form &optional env | | get-setf-method-multiple-value returns five values constituting the setf | method for form. The form must be a generalized-variable reference. The env | must be an environment of the sort obtained through the &environment | lambda-list keyword; if env is nil or omitted, the null lexical environment is | assumed. | | This is the same as get-setf-method except that it does not check the number | of store variables; use this in cases that allow storing multiple values into a| generalized variable. There are no such cases in standard Common Lisp, but | this function is provided to allow for possible extensions. | X3J13 voted in March 1988 <96> to clarify that a setf method for a functional| name is applicable only when the global binding of that name is lexically | visible. If such a name has a local binding introduced by flet, labels, or | macrolet, then global definitions of setf methods for that name do not apply | and are not visible. All of the standard Common Lisp macros that modify a setf| place (for example, incf, decf, pop, and rotatef) obey this convention. | ------------------------------------------------------------------------------- 7.3. <### Function Invocation ###> The most primitive form for function invocation in Lisp of course has no name; any list that has no other interpretation as a macro call or special form is taken to be a function call. Other constructs are provided for less common but nevertheless frequently useful situations. ---------<<>> apply apply function arg &rest more-args This applies function to a list of arguments. The function may be a compiled-code object, or a lambda-expression, or a : symbol; in the latter case the global functional value of that symbol is used : (but it is illegal for the symbol to be the name of a macro or special form). : X3J13 voted in June 1988 <90> to allow the function to be only of type symbol| or function; a lambda-expression is no longer acceptable as a functional | argument. One must use the function special form or the abbreviation #' before| a lambda-expression that appears as an explicit argument form. | The arguments for the function consist of the last argument to apply appended to the end of a list of all the other arguments to apply but the function itself; it is as if all the arguments to apply except the function were given to list* to create the argument list. For example: (setq f '+) (apply f '(1 2)) ==> 3 (setq f #'-) (apply f '(1 2)) ==> -1 (apply #'max 3 5 '(2 7 3)) ==> 7 (apply 'cons '((+ 2 3) 4)) ==> ((+ 2 3) . 4) not (5 . 4) (apply #'+ '()) ==> 0 Note that if the function takes keyword arguments, the keywords as well as the corresponding values must appear in the argument list: (apply #'(lambda (&key a b) (list a b)) '(:b 3)) ==> (nil 3) This can be very useful in conjunction with the &allow-other-keys feature: (defun foo (size &rest keys &key double &allow-other-keys) (let ((v (apply #'make-array size :allow-other-keys t keys))) (if double (concatenate (type-of v) v v) v))) (foo 4 :initial-contents '(a b c d) :double t) ==> #(a b c d a b c d) ---------<<>> funcall funcall fn &rest arguments (funcall fn a1 a2 ... an) applies the function fn to the arguments a1, a2, ..., an. The fn may not be a special form or a macro; this would not be meaningful. X3J13 voted in June 1988 <90> to allow the fn to be only of type symbol or | function; a lambda-expression is no longer acceptable as a functional argument.| One must use the function special form or the abbreviation #' before a | lambda-expression that appears as an explicit argument form. | For example: (cons 1 2) ==> (1 . 2) (setq cons (symbol-function '+)) (funcall cons 1 2) ==> 3 The difference between funcall and an ordinary function call is that the function is obtained by ordinary Lisp evaluation rather than by the special interpretation of the function position that normally occurs. . . . . . . . . . . . . . . . . . . . . Compatibility note: The Common Lisp function funcall corresponds roughly to the Interlisp primitive apply*. . . . . . . . . . . . . . . . . . . . . ---------<<>> call-arguments-limit call-arguments-limit The value of call-arguments-limit is a positive integer that is the upper exclusive bound on the number of arguments that may be passed to a function. This bound depends on the implementation but will not be smaller than 50. (Implementors are encouraged to make this limit as large as practicable without sacrificing performance.) The value of call-arguments-limit must be at least as great as that of lambda-parameters-limit. See also multiple-values-limit. ------------------------------------------------------------------------------- 7.4. <### Simple Sequencing ###> Each of the constructs in this section simply evaluates all the argument forms in order. They differ only in what results are returned. ---------<<>> progn progn {form}* The progn construct takes a number of forms and evaluates them sequentially, in order, from left to right. The values of all the forms but the last are discarded; whatever the last form returns is returned by the progn form. One says that all the forms but the last are evaluated for effect, because their execution is useful only for the side effects caused, but the last form is executed for value. progn is the primitive control structure construct for "compound statements," such as begin-end blocks in Algol-like languages. Many Lisp constructs are "implicit progn" forms: as part of their syntax each allows many forms to be written that are to be evaluated sequentially, discarding the results of all forms but the last and returning the results of the last form. If the last form of the progn returns multiple values, then those multiple values are returned by the progn form. If there are no forms for the progn, then the result is nil. These rules generally hold for implicit progn forms as well. ---------<<>> prog1 prog1 first {form}* prog1 is similar to progn, but it returns the value of its first form. All the argument forms are executed sequentially; the value of the first form is saved while all the others are executed and is then returned. prog1 is most commonly used to evaluate an expression with side effects and to return a value that must be computed before the side effects happen. For example: (prog1 (car x) (rplaca x 'foo)) alters the car of x to be foo and returns the old car of x. prog1 always returns a single value, even if the first form tries to return multiple values. As a consequence, (prog1 x) and (progn x) may behave differently if x can produce multiple values. See multiple-value-prog1. A point of style: although prog1 can be used to force exactly a single value to be returned, it is conventional to use the function values for this purpose. ---------<<>> prog2 prog2 first second {form}* prog2 is similar to prog1, but it returns the value of its second form. All the argument forms are executed sequentially; the value of the second form is saved while all the other forms are executed and is then returned. prog2 is provided mostly for historical compatibility. (prog2 a b c ... z) == (progn a (prog1 b c ... z)) Occasionally it is desirable to perform one side effect, then a value-producing operation, then another side effect. In such a peculiar case, prog2 is fairly perspicuous. For example: (prog2 (open-a-file) (process-the-file) (close-the-file)) ; value is that of process-the-file prog2, like prog1, always returns a single value, even if the second form tries to return multiple values. As a consequence of this, (prog2 x y) and (progn x y) may behave differently if y can produce multiple values. ------------------------------------------------------------------------------- 7.5. <### Establishing New Variable Bindings ###> During the invocation of a function represented by a lambda-expression (or a closure of a lambda-expression, as produced by function), new bindings are established for the variables that are the parameters of the lambda-expression. These bindings initially have values determined by the parameter-binding protocol discussed in section 5.2.2. The following constructs may also be used to establish bindings of variables, both ordinary and functional. ---------<<>> let let ({var | (var value)}*) {declaration}* {form}* A let form can be used to execute a series of forms with specified variables bound to specified values. More precisely, the form (let ((var1 value1) (var2 value2) ... (varm valuem)) declaration1 declaration2 ... declarationp body1 body2 ... bodyn) first evaluates the expressions value1, value2, and so on, in that order, saving the resulting values. Then all of the variables varj are bound to the corresponding values in parallel; each binding will be a lexical binding unless there is a special declaration to the contrary. The expressions bodyk are then evaluated in order; the values of all but the last are discarded (that is, the body of a let form is an implicit progn). The let form returns what evaluating bodyn produces (if the body is empty, which is fairly useless, let returns nil as its value). The bindings of the variables have lexical scope and indefinite extent. Instead of a list (varj valuej), one may write simply varj. In this case varj is initialized to nil. As a matter of style, it is recommended that varj be written only when that variable will be stored into (such as by setq) before its first use. If it is important that the initial value be nil rather than some undefined value, then it is clearer to write out (varj nil) if the initial value is intended to mean "false," or (varj '()) if the initial value is intended to be an empty list. Note that the code (let (x) (declare (integer x)) (setq x (gcd y z)) ...) is incorrect; although x is indeed set before it is used, and is set to a value of the declared type integer, nevertheless x momentarily takes on the value nil in violation of the type declaration. Declarations may appear at the beginning of the body of a let. See declare. See also destructuring-bind. | X3J13 voted in January 1989 <182> to regularize the binding formats for do, | do*, let, let*, prog, prog*, and compiler-let. The new syntactic definition | for let makes the value optional: | | ---------<<>> let | let ({var | (var [value])}*) {declaration}* {form}* | | This changes let to allow a list (var) to appear, meaning the same as simply | var. | ---------<<>> let* let* ({var | (var value)}*) {declaration}* {form}* let* is similar to let, but the bindings of variables are performed sequentially rather than in parallel. This allows the expression for the value of a variable to refer to variables previously bound in the let* form. More precisely, the form (let* ((var1 value1) (var2 value2) ... (varm valuem)) declaration1 declaration2 ... declarationp body1 body2 ... bodyn) first evaluates the expression value1, then binds the variable var1 to that value; then it evaluates value2 and binds var2; and so on. The expressions bodyj are then evaluated in order; the values of all but the last are discarded (that is, the body of a let* form is an implicit progn). The let* form returns the results of evaluating bodyn (if the body is empty, which is fairly useless, let* returns nil as its value). The bindings of the variables have lexical scope and indefinite extent. Instead of a list (varj valuej), one may write simply varj. In this case varj is initialized to nil. As a matter of style, it is recommended that varj be written only when that variable will be stored into (such as by setq) before its first use. If it is important that the initial value be nil rather than some undefined value, then it is clearer to write out (varj nil) if the initial value is intended to mean "false," or (varj '()) if the initial value is intended to be an empty list. Declarations may appear at the beginning of the body of a let*. See declare. X3J13 voted in January 1989 <182> to regularize the binding formats for do, | do*, let, let*, prog, prog*, and compiler-let. The new syntactic definition | for let* makes the value optional: | | ---------<<>> let* | let* ({var | (var [value])}*) {declaration}* {form}* | | This changes let* to allow a list (var) to appear, meaning the same as simply| var. | ---------<<>> compiler-let : compiler-let ({var | (var value)}*) {form}* : : When executed by the Lisp interpreter, compiler-let behaves exactly like let : with all the variable bindings implicitly declared special. When the compiler : processes this form, however, no code is compiled for the bindings; instead, : the processing of the body by the compiler (including, in particular, the : expansion of any macro calls within the body) is done with the special : variables bound to the indicated values in the execution context of the : compiler. This is primarily useful for communication among complicated macros.: : Declarations may not appear at the beginning of the body of a compiler-let. : : . . . . . . . . . . . . . . . . . . . . : Rationale: Because of the unorthodox handling by compiler-let of its variable : bindings, it would be complicated and confusing to permit declarations that : apparently referred to the variables bound by compiler-let. Disallowing : declarations eliminates the problem. : . . . . . . . . . . . . . . . . . . . . : : X3J13 voted in January 1989 <182> to regularize the binding formats for do, : do*, let, let*, prog, prog*, and compiler-let. The new syntactic definition : for compiler-let makes the value optional: : : ---------<<>> compiler-let : compiler-let ({var | (var [value])}*) {form}* : : This changes compiler-let to allow a list (var) to appear, meaning the same : as simply var. : X3J13 voted in June 1989 <25> to remove compiler-let from the language. Many| uses of compiler-let can be replaced with more portable code that uses macrolet| or symbol-macrolet. | ---------<<>> progv progv symbols values {form}* progv is a special form that allows binding one or more dynamic variables whose names may be determined at run time. The sequence of forms (an implicit progn) is evaluated with the dynamic variables whose names are in the list symbols bound to corresponding values from the list values. (If too few values are supplied, the remaining symbols are bound and then made to have no value; see makunbound. If too many values are supplied, the excess values are ignored.) The results of the progv form are those of the last form. The bindings of the dynamic variables are undone on exit from the progv form. The lists of symbols and values are computed quantities; this is what makes progv different from, for example, let, where the variable names are stated explicitly in the program text. progv is particularly useful for writing interpreters for languages embedded in Lisp; it provides a handle on the mechanism for binding dynamic variables. ---------<<>> flet flet ({(name lambda-list [[ {declaration}* | doc-string ]] {form}*)}*) {form}* ---------<<>> labels labels ({(name lambda-list [[ {declaration}* | doc-string ]] {form}*)}*) {form}* ---------<<>> macrolet macrolet ({(name varlist [[ {declaration}* | doc-string ]] {form}*)}*) {form}* flet may be used to define locally named functions. Within the body of the flet form, function names matching those defined by the flet refer to the locally defined functions rather than to the global function definitions of the same name. Any number of functions may be simultaneously defined. Each definition is similar in format to a defun form: first a name, then a parameter list (which may contain &optional, &rest, or &key parameters), then optional declarations and documentation string, and finally a body. (flet ((safesqrt (x) (sqrt (abs x)))) ;; The safesqrt function is used in two places. (safesqrt (apply #'+ (map 'list #'safesqrt longlist)))) The labels construct is identical in form to the flet construct. These constructs differ in that the scope of the defined function names for flet encompasses only the body, whereas for labels it encompasses the function definitions themselves. That is, labels can be used to define mutually recursive functions, but flet cannot. This distinction is useful. Using flet one can locally redefine a global function name, and the new definition can refer to the global definition; the same construction using labels would not have that effect. (defun integer-power (n k) ;A highly "bummed" integer (declare (integer n)) ; exponentiation routine (declare (type (integer 0 *) k)) (labels ((expt0 (x k a) (declare (integer x a) (type (integer 0 *) k)) (cond ((zerop k) a) ((evenp k) (expt1 (* x x) (floor k 2) a)) (t (expt0 (* x x) (floor k 2) (* x a))))) (expt1 (x k a) (declare (integer x a) (type (integer 1 *) k)) (cond ((evenp k) (expt1 (* x x) (floor k 2) a)) (t (expt0 (* x x) (floor k 2) (* x a)))))) (expt0 n k 1))) macrolet is similar in form to flet but defines local macros, using the same format used by defmacro. The names established by macrolet as names for macros are lexically scoped. I have observed that, while most Common Lisp users pronounce macrolet to | rhyme with "silhouette," a small but vocal minority pronounce it to rhyme with | "Chevrolet." A very few extremists furthermore adjust their pronunciation of | flet similarly: they say "flay." Hey, hey! Tres outre. | Macros often must be expanded at "compile time" (more generally, at a time before the program itself is executed), and so the run-time values of variables are not available to macros defined by macrolet. The precise rule is that the macro-expansion functions defined by macrolet : are defined in the global environment; lexically scoped entities that would : ordinarily be lexically apparent are not visible within the expansion : functions. : X3J13 voted in March 1989 <50> to retract the previous sentence and specify | that the macro-expansion functions created by macrolet are defined in the | lexical environment in which the macrolet form appears, not in the null lexical| environment. Declarations, macrolet definitions, and symbol-macrolet | definitions affect code within the expansion functions in a macrolet, but the | consequences are undefined if such code attempts to refer to any local variable| or function bindings that are visible in that lexical environment. | However, lexically scoped entities are visible within the body of the macrolet form and are visible to the code that is the expansion of a macro call. The following example should make this clear: ;;; Example of scoping in macrolet. (defun foo (x flag) (macrolet ((fudge (z) ;; The parameters x and flag are not accessible ;; at this point; a reference to flag would be to ;; the global variable of that name. `(if flag (* ,z ,z) ,z))) ;; The parameters x and flag are accessible here. (+ x (fudge x) (fudge (+ x 1))))) The body of the macrolet becomes (+ x (if flag (* x x) x) (if flag (* (+ x 1) (+ x 1)) (+ x 1))) after macro expansion. The occurrences of x and flag legitimately refer to the parameters of the function foo because those parameters are visible at the site of the macro call which produced the expansion. X3J13 voted in March 1988 <78> to specify that the body of each function or | expander function defined by flet, labels, or macrolet is implicitly enclosed | in a block construct whose name is the same as the name of the function. | Therefore return-from may be used to exit from the function. | X3J13 voted in March 1989 <89> to extend flet and labels to accept any | function-name (a symbol or a list whose car is setf -- see section 7.1) as a | name for a function to be locally defined. In this way one can create local | definitions for setf expansion functions. (X3J13 explicitly declined to extend| macrolet in the same manner.) | X3J13 voted in March 1988 <77> to change flet, labels, and macrolet to allow | declarations to appear before the body. The new descriptions are therefore as | follows: | | ---------<<>> flet | flet ({(name lambda-list | [[ {declaration}* | doc-string ]] {form}*)}*) | {declaration}* {form}* | ---------<<>> labels | labels ({(name lambda-list | [[ {declaration}* | doc-string ]] {form}*)}*) | {declaration}* {form}* | ---------<<>> macrolet | macrolet ({(name varlist | [[ {declaration}* | doc-string ]] {form}*)}*) | {declaration}* {form}* | | These are now syntactically more similar to such other binding forms as let. | | For flet and labels, the bodies of the locally defined functions are part of | the scope of pervasive declarations appearing before the main body. (This is | consistent with the treatment of initialization forms in let.) For macrolet, | however, the bodies of the locally defined macro expander functions are not | included in the scope of pervasive declarations appearing before the main body.| (This is consistent with the rule, stated below, that the bodies of macro | expander functions are in the global environment, not the local lexical | environment.) Here is an example: | | (flet ((stretch (x) (* x *stretch-factor*)) | (chop (x) (- x *chop-margin*))) | (declare (inline stretch chop)) ; Illegal in original Common Lisp | (if (> x *chop-margin*) (stretch (chop x)) (chop (stretch x)))) | | X3J13 voted to permit declarations of the sort noted above. | ---------<<>> symbol-macrolet | symbol-macrolet ({(var expansion)}*) | {declaration}* {form}* | | X3J13 voted in June 1988 <12> to adopt the Common Lisp Object System. Part | of this proposal is a general mechanism, symbol-macrolet, for treating certain | variable names as if they were parameterless macro calls. This facility may be| useful independent of CLOS. X3J13 voted in March 1989 <173> to modify the | definition of symbol-macrolet substantially and also voted <172> to allow | declarations before the body of symbol-macrolet but with peculiar treatment of | special and type declarations. | | The forms are executed as an implicit progn in a lexical environment that | causes every reference to any defined var to be replaced by the corresponding | expansion. It is as if the reference to the var were a parameterless macro | call; the expansion is evaluated or otherwise processed in place of the | reference (in particular, the expansion form is itself subject to further | expansion -- this is one of the changes <173> from the original definition in | the CLOS proposal). Note, however, that the names of such symbol macros occupy| the name space of variables, not the name space of functions; just as one may | have a function (or macro, or special form) and a variable with the same name | without interference, so one may have an ordinary macro (or function, or | special form) and a symbol macro with the same name. The use of | symbol-macrolet can therefore be shadowed by let or other constructs that bind | variables; symbol-macrolet does not substitute for all occurrences of a var as | a variable but only for those occurrences that would be construed as references| in the scope of a lexical binding of var as a variable. For example: | | (symbol-macrolet ((pollyanna 'goody)) | (list pollyanna (let ((pollyanna 'two-shoes)) pollyanna))) | ==> (goody two-shoes), not (goody goody) | | One might think that 'goody simply replaces all occurrences of pollyanna, and| so the value of the let would be goody; but this is not so. A little | reflection shows that under this incorrect interpretation the body in expanded | form would be | (list 'goody (let (('goody 'two-shoes)) 'goody)) | which is syntactically malformed. The correct expanded form is | (list 'goody (let ((pollyanna 'two-shoes)) pollyanna)) | because the rebinding of pollyanna by the let form shadows the symbol macro | definition. | | The expansion for each var is not evaluated at binding time but only after it| has replaced a reference to the var. The setf macro allows a symbol macro to | be used as a place, in which case its expansion is used; moreover, setq of a | variable that is really a symbol macro will be treated as if setf had been | used. The values of the last form are returned, or nil if there is no value. | | See macroexpand and macroexpand-1; they will expand symbol macros as well as | ordinary macros. | | Certain declarations before the body are handled in a peculiar manner; see | section 9.1. | ------------------------------------------------------------------------------- 7.6. <### Conditionals ###> The traditional conditional construct in Lisp is cond. However, if is much simpler and is directly comparable to conditional constructs in other programming languages, so it is considered to be primitive in Common Lisp and is described first. Common Lisp also provides the dispatching constructs case and typecase, which are often more convenient than cond. ---------<<>> if if test then [else] The if special form corresponds to the if-then-else construct found in most algebraic programming languages. First the form test is evaluated. If the result is not nil, then the form then is selected; otherwise the form else is selected. Whichever form is selected is then evaluated, and if returns whatever is returned by evaluation of the selected form. (if test then else) == (cond (test then) (t else)) but if is considered more readable in some situations. The else form may be omitted, in which case if the value of test is nil then nothing is done and the value of the if form is nil. If the value of the if form is important in this situation, then the and construct may be stylistically preferable, depending on the context. If the value is not important, but only the effect, then the when construct may be stylistically preferable. ---------<<>> when when test {form}* (when test form1 form2 ... ) first evaluates test. If the result is nil, then no form is evaluated, and nil is returned. Otherwise the forms constitute an implicit progn and are evaluated sequentially from left to right, and the value of the last one is returned. (when p a b c) == (and p (progn a b c)) (when p a b c) == (cond (p a b c)) (when p a b c) == (if p (progn a b c) nil) (when p a b c) == (unless (not p) a b c) As a matter of style, when is normally used to conditionally produce some side effects, and the value of the when form is normally not used. If the value is relevant, then it may be stylistically more appropriate to use and or if. ---------<<>> unless unless test {form}* (unless test form1 form2 ... ) first evaluates test. If the result is not nil, then the forms are not evaluated, and nil is returned. Otherwise the forms constitute an implicit progn and are evaluated sequentially from left to right, and the value of the last one is returned. (unless p a b c) == (cond ((not p) a b c)) (unless p a b c) == (if p nil (progn a b c)) (unless p a b c) == (when (not p) a b c) As a matter of style, unless is normally used to conditionally produce some side effects, and the value of the unless form is normally not used. If the value is relevant, then it may be stylistically more appropriate to use if. ---------<<>> cond cond {(test {form}*)}* A cond form has a number (possibly zero) of clauses, which are lists of forms. Each clause consists of a test followed by zero or more consequents. For example: (cond (test-1 consequent-1-1 consequent-1-2 ...) (test-2) (test-3 consequent-3-1 ...) ... ) The first clause whose test evaluates to non-nil is selected; all other clauses are ignored, and the consequents of the selected clause are evaluated in order (as an implicit progn). More specifically, cond processes its clauses in order from left to right. For each clause, the test is evaluated. If the result is nil, cond advances to the next clause. Otherwise, the cdr of the clause is treated as a list of forms, or consequents; these forms are evaluated in order from left to right, as an implicit progn. After evaluating the consequents, cond returns without inspecting any remaining clauses. The cond special form returns the results of evaluating the last of the selected consequents; if there were no consequents in the selected clause, then the single (and necessarily non-null) value of the test is returned. If cond runs out of clauses (every test produced nil, and therefore no clause was selected), the value of the cond form is nil. If it is desired to select the last clause unconditionally if all others fail, the standard convention is to use t for the test. As a matter of style, it is desirable to write a last clause (t nil) if the value of the cond form is to be used for something. Similarly, it is in questionable taste to let the last clause of a cond be a "singleton clause"; an explicit t should be provided. (Note moreover that (cond ... (x)) may behave differently from (cond ... (t x)) if x might produce multiple values; the former always returns a single value, whereas the latter returns whatever values x returns. However, as a matter of style it is preferable to obtain this behavior by writing (cond ... (t (values x))), using the values function explicitly to indicate the discarding of any excess values.) For example: (setq z (cond (a 'foo) (b 'bar))) ; Possibly confusing (setq z (cond (a 'foo) (b 'bar) (t nil))) ; Better (cond (a b) (c d) (e)) ; Possibly confusing (cond (a b) (c d) (t e)) ; Better (cond (a b) (c d) (t (values e))) ; Better (if one value needed) (cond (a b) (c)) ; Possibly confusing (cond (a b) (t c)) ; Better (if a b c) ; Also better A Lisp cond form may be compared to a continued if-then-else as found in many algebraic programming languages: (cond (p ...) if p then ... (q ...) roughly else if q then ... (r ...) corresponds else if r then ... ... to ... (t ...)) else ... ---------<<>> case case keyform {({({key}*) | key} {form}*)}* case is a conditional that chooses one of its clauses to execute by comparing a value to various constants, which are typically keyword symbols, integers, or characters (but may be any objects). Its form is as follows: (case keyform (keylist-1 consequent-1-1 consequent-1-2 ...) (keylist-2 consequent-2-1 ...) (keylist-3 consequent-3-1 ...) ...) Structurally case is much like cond, and it behaves like cond in selecting one clause and then executing all consequents of that clause. However, case differs in the mechanism of clause selection. The first thing case does is to evaluate the form keyform to produce an object called the key object. Then case considers each of the clauses in turn. If key is in the keylist (that is, is eql to any item in the keylist) of a clause, the consequents of that clause are evaluated as an implicit progn; case returns what was returned by the last consequent (or nil if there are no consequents in that clause). If no clause is satisfied, case returns nil. The keys in the keylists are not evaluated; literal key values must appear in the keylists. It is an error for the same key to appear in more than one clause; a consequence is that the order of the clauses does not affect the behavior of the case construct. Instead of a keylist, one may write one of the symbols t and otherwise. A clause with such a symbol always succeeds and must be the last clause (this is an exception to the order-independence of clauses). See also ecase and ccase, each of which provides an implicit otherwise clause to signal an error if no clause is satisfied. If there is only one key for a clause, then that key may be written in place of a list of that key, provided that no ambiguity results. Such a "singleton key" may not be nil (which is confusable with (), a list of no keys), t, otherwise, or a cons. . . . . . . . . . . . . . . . . . . . . Compatibility note: The Lisp Machine Lisp caseq construct uses eq for the comparison. In Lisp Machine Lisp caseq therefore works for fixnums but not bignums. The MacLisp caseq construct simply prohibits the use of bignums; indeed, it permits only fixnums and symbols as clause keys. In the interest of hiding the fixnum-bignum distinction, and for general language consistency, case uses eql in Common Lisp. The Interlisp selectq construct is similar to case. . . . . . . . . . . . . . . . . . . . . ---------<<>> typecase typecase keyform {(type {form}*)}* typecase is a conditional that chooses one of its clauses by examining the type of an object. Its form is as follows: (typecase keyform (type-1 consequent-1-1 consequent-1-2 ...) (type-2 consequent-2-1 ...) (type-3 consequent-3-1 ...) ...) Structurally typecase is much like cond or case, and it behaves like them in selecting one clause and then executing all consequents of that clause. It differs in the mechanism of clause selection. The first thing typecase does is to evaluate the form keyform to produce an object called the key object. Then typecase considers each of the clauses in turn. The type that appears in each clause is a type specifier; it is not evaluated but is a literal type specifier. The first clause for which the key is of that clause's specified type is selected, the consequents of this clause are evaluated as an implicit progn, and typecase returns what was returned by the last consequent (or nil if there are no consequents in that clause). If no clause is satisfied, typecase returns nil. As for case, the symbol t or otherwise may be written for type to indicate that the clause should always be selected. See also etypecase and ctypecase, each of which provides an implicit otherwise clause to signal an error if no clause is satisfied. It is permissible for more than one clause to specify a given type, particularly if one is a subtype of another; the earliest applicable clause is chosen. Thus for typecase, unlike case, the order of the clauses may affect the behavior of the construct. For example: (typecase an-object (string ...) ; This clause handles strings ((array t) ...) ; This clause handles general arrays ((array bit) ...) ; This clause handles bit arrays (array ...) ; This handles all other arrays ((or list number) ...) ; This handles lists and numbers (t ...)) ; This handles all other objects A Common Lisp compiler may choose to issue a warning if a clause cannot be selected because it is completely shadowed by earlier clauses. ------------------------------------------------------------------------------- 7.7. <### Blocks and Exits ###> The block and return-from constructs provide a structured lexical non-local exit facility. At any point lexically within a block construct, a return-from with the same name may be used to perform an immediate transfer of control that exits from the block. In the most common cases this mechanism is more efficient than the dynamic non-local exit facility provided by catch and throw, described in section 7.11. ---------<<>> block block name {form}* The block construct executes each form from left to right, returning whatever is returned by the last form. If, however, a return or return-from form that specifies the same name is executed during the execution of some form, then the results specified by the return or return-from are immediately returned as the value of the block construct, and execution proceeds as if the block had terminated normally. In this, block differs from progn; the progn construct has nothing to do with return. The name is not evaluated; it must be a symbol. The scope of the name is lexical; only a return or return-from textually contained in some form can exit from the block. The extent of the name is dynamic. Therefore it is only possible to exit from a given run-time incarnation of a block once, either normally or by explicit return. The defun form implicitly puts a block around the body of the function defined; the block has the same name as the function. Therefore one may use return-from to return prematurely from a function defined by defun. The lexical scoping of the block name is fully general and has consequences that may be surprising to users and implementors of other Lisp systems. For example, the return-from in the following example actually does work in Common Lisp as one might expect: (block loser (catch 'stuff (mapcar #'(lambda (x) (if (numberp x) (hairyfun x) (return-from loser nil))) items))) Depending on the situation, a return in Common Lisp may not be simple. A return can break up catchers if necessary to get to the block in question. It is possible for a "closure" created by function for a lambda-expression to refer to a block name as long as the name is lexically apparent. ---------<<>> return-from return-from name [result] return-from is used to return from a block or from such constructs as do and prog that implicitly establish a block. The name is not evaluated and must be a symbol. A block construct with the same name must lexically enclose the occurrence of return-from; whatever the evaluation of result produces is immediately returned from the block. (If the result form is omitted, it defaults to nil. As a matter of style, this form ought to be used to indicate that the particular value returned doesn't matter.) The return-from form itself never returns and cannot have a value; it causes results to be returned from a block construct. If the evaluation of result produces multiple values, those multiple values are returned by the construct exited. ---------<<>> return return [result] (return form) is identical in meaning to (return-from nil form); it returns from a block named nil. Blocks established implicitly by iteration constructs such as do are named nil, so that return will exit properly from such a construct. ------------------------------------------------------------------------------- 7.8. <### Iteration ###> Common Lisp provides a number of iteration constructs. The loop construct provides a trivial iteration facility; it is little more than a progn with a branch from the bottom back to the top. The do and do* constructs provide a general iteration facility for controlling the variation of several variables on each cycle. For specialized iterations over the elements of a list or n consecutive integers, dolist and dotimes are provided. The tagbody construct is the most general, permitting arbitrary go statements within it. (The traditional prog construct is a synthesis of tagbody, block, and let.) Most of the iteration constructs permit statically defined non-local exits (see return-from and return). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7.8.1. <## Indefinite Iteration ##> The loop construct is the simplest iteration facility. It controls no variables, and simply executes its body repeatedly. ---------<<>> loop loop {form}* Each form is evaluated in turn from left to right. When the last form has been evaluated, then the first form is evaluated again, and so on, in a never-ending cycle. The loop construct never returns a value. Its execution must be terminated explicitly, using return or throw, for example. loop, like most iteration constructs, establishes an implicit block named nil. Thus return may be used to exit from a loop with specified results. A loop construct has this meaning only if every form is non-atomic (a list). : The case where some form is atomic is reserved for future extensions. : : . . . . . . . . . . . . . . . . . . . . : Implementation note: There have been several proposals for a powerful iteration: mechanism to be called loop. One version is provided in Lisp Machine Lisp. : Implementors are encouraged to experiment with extensions to the loop syntax,: but users should be advised that in all likelihood some specific set of : extensions to loop will be adopted in a future revision of Common Lisp. : . . . . . . . . . . . . . . . . . . . . : X3J13 voted in January 1989 <151> to include just such an extension of loop. | See chapter 26. | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7.8.2. <## General Iteration ##> In contrast to loop, do and do* provide a powerful and general mechanism for repetitively recalculating many variables. ---------<<>> do do ({(var [init [step]])}*) (end-test {result}*) {declaration}* {tag | statement}* ---------<<>> do* do* ({(var [init [step]])}*) (end-test {result}*) {declaration}* {tag | statement}* The do special form provides a generalized iteration facility, with an arbitrary number of "index variables." These variables are bound within the iteration and stepped in parallel in specified ways. They may be used both to generate successive values of interest (such as successive integers) or to accumulate results. When an end condition is met, the iteration terminates with a specified value. In general, a do loop looks like this: (do ((var1 init1 step1) (var2 init2 step2) ... (varn initn stepn)) (end-test . result) {declaration}* . tagbody) A do* loop looks exactly the same except that the name do is replaced by do*. The first item in the form is a list of zero or more index-variable specifiers. Each index-variable specifier is a list of the name of a variable var, an initial value init, and a stepping form step. If init is omitted, it defaults to nil. If step is omitted, the var is not changed by the do construct between repetitions (though code within the do is free to alter the value of the variable by using setq). An index-variable specifier can also be just the name of a variable. In this case, the variable has an initial value of nil and is not changed between repetitions. As a matter of style, it is recommended that an unadorned variable name be written only when that variable will be stored into (such as by setq) before its first use. If it is important that the initial value be nil rather than some undefined value, then it is clearer to write out (varj nil) if the initial value is intended to mean "false," or (varj '()) if the initial value is intended to be an empty list. X3J13 voted in January 1989 <182> to regularize the binding formats for do, | do*, let, let*, prog, prog*, and compiler-let. In the case of do and do* the | first edition was inconsistent; the formal syntax fails to reflect the fact | that a simple variable name may appear, as described in the preceding | paragraph. The definitions should read | | ---------<<>> do | do ({var | (var [init [step]])}*) | (end-test {result}*) | {declaration}* {tag | statement}* | ---------<<>> do* | do* ({var | (var [init [step]])}*) | (end-test {result}*) | {declaration}* {tag | statement}* | | for consistency with the reading of the first edition and the X3J13 vote. | Before the first iteration, all the init forms are evaluated, and each var is bound to the value of its respective init. This is a binding, not an assignment; when the loop terminates, the old values of those variables will be restored. For do, all of the init forms are evaluated before any var is bound; hence all the init forms may refer to the old bindings of all the variables (that is, to the values visible before beginning execution of the do construct). For do*, the first init form is evaluated, then the first var is bound to that value, then the second init form is evaluated, then the second var is bound, and so on; in general, the initj form can refer to the new binding vark if k The constructs dolist and dotimes execute a body of code once for each value taken by a single variable. They are expressible in terms of do, but capture very common patterns of use. Both dolist and dotimes perform a body of statements repeatedly. On each iteration a specified variable is bound to an element of interest that the body may examine. dolist examines successive elements of a list, and dotimes examines integers from 0 to n-1 for some specified positive integer n. The value of any of these constructs may be specified by an optional result form, which if omitted defaults to the value nil. The return statement may be used to return immediately from a dolist or dotimes form, discarding any following iterations that might have been performed; in effect, a block named nil surrounds the construct. The body of the loop is implicitly a tagbody construct; it may contain tags to serve as the targets of go statements. Declarations may appear before the body of the loop. ---------<<>> dolist dolist (var listform [resultform]) {declaration}* {tag | statement}* dolist provides straightforward iteration over the elements of a list. First dolist evaluates the form listform, which should produce a list. It then executes the body once for each element in the list, in order, with the variable var bound to the element. Then resultform (a single form, not an implicit progn) is evaluated, and the result is the value of the dolist form. (When the resultform is evaluated, the control variable var is still bound and has the value nil.) If resultform is omitted, the result is nil. (dolist (x '(a b c d)) (prin1 x) (princ " ")) ==> nil after printing "a b c d " (note the trailing space) An explicit return statement may be used to terminate the loop and return a specified value. X3J13 voted in January 1989 <121> to restrict user side effects; see | section 7.9 | ---------<<>> dotimes dotimes (var countform [resultform]) {declaration}* {tag | statement}* dotimes provides straightforward iteration over a sequence of integers. The expression (dotimes (var countform resultform) . progbody) evaluates the form countform, which should produce an integer. It then performs progbody once for each integer from zero (inclusive) to count (exclusive), in order, with the variable var bound to the integer; if the value of countform is zero or negative, then the progbody is performed zero times. Finally, resultform (a single form, not an implicit progn) is evaluated, and the result is the value of the dotimes form. (When the resultform is evaluated, the control variable var is still bound and has as its value the number of times the body was executed.) If resultform is omitted, the result is nil. An explicit return statement may be used to terminate the loop and return a specified value. Here is an example of the use of dotimes in processing strings: ;;; True if the specified subsequence of the string is a ;;; palindrome (reads the same forwards and backwards). (defun palindromep (string &optional (start 0) (end (length string))) (dotimes (k (floor (- end start) 2) t) (unless (char-equal (char string (+ start k)) (char string (- end k 1))) (return nil)))) (palindromep "Able was I ere I saw Elba") ==> t (palindromep "A man, a plan, a canal--Panama!") ==> nil (remove-if-not #'alpha-char-p ; Remove punctuation "A man, a plan, a canal--Panama!") ==> "AmanaplanacanalPanama" (palindromep (remove-if-not #'alpha-char-p "A man, a plan, a canal--Panama!")) ==> t (palindromep (remove-if-not #'alpha-char-p "Unremarkable was I ere I saw Elba Kramer, nu?")) ==> t (palindromep (remove-if-not #'alpha-char-p "A man, a plan, a cat, a ham, a yak, a yam, a hat, a canal--Panama!")) ==> t (palindromep (remove-if-not #'alpha-char-p "Ja-da, ja-da, ja-da ja-da jing jing jing")) ==> nil Altering the value of var in the body of the loop (by using setq, for example) will have unpredictable, possibly implementation-dependent results. A Common Lisp compiler may choose to issue a warning if such a variable appears in a setq. . . . . . . . . . . . . . . . . . . . . Compatibility note: The dotimes construct is the closest thing in Common Lisp to the Interlisp rptq construct. . . . . . . . . . . . . . . . . . . . . See also do-symbols, do-external-symbols, and do-all-symbols. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7.8.4. <## Mapping ##> Mapping is a type of iteration in which a function is successively applied to pieces of one or more sequences. The result of the iteration is a sequence containing the respective results of the function applications. There are several options for the way in which the pieces of the list are chosen and for what is done with the results returned by the applications of the function. The function map may be used to map over any kind of sequence. The following functions operate only on lists. ---------<<>> mapcar mapcar function list &rest more-lists ---------<<>> maplist maplist function list &rest more-lists ---------<<>> mapc mapc function list &rest more-lists ---------<<>> mapl mapl function list &rest more-lists ---------<<>> mapcan mapcan function list &rest more-lists ---------<<>> mapcon mapcon function list &rest more-lists For each of these mapping functions, the first argument is a function and the rest must be lists. The function must take as many arguments as there are lists. mapcar operates on successive elements of the lists. First the function is applied to the car of each list, then to the cadr of each list, and so on. (Ideally all the lists are the same length; if not, the iteration terminates when the shortest list runs out, and excess elements in other lists are ignored.) The value returned by mapcar is a list of the results of the successive calls to the function. For example: (mapcar #'abs '(3 -4 2 -5 -6)) ==> (3 4 2 5 6) (mapcar #'cons '(a b c) '(1 2 3)) ==> ((a . 1) (b . 2) (c . 3)) maplist is like mapcar except that the function is applied to the lists and successive cdr's of those lists rather than to successive elements of the lists. For example: (maplist #'(lambda (x) (cons 'foo x)) '(a b c d)) ==> ((foo a b c d) (foo b c d) (foo c d) (foo d)) (maplist #'(lambda (x) (if (member (car x) (cdr x)) 0 1)) '(a b a c d b c)) ==> (0 0 1 0 1 1 1) ; An entry is 1 if the corresponding element of the input ; list was the last instance of that element in the input list. mapl and mapc are like maplist and mapcar, respectively, except that they do not accumulate the results of calling the function. . . . . . . . . . . . . . . . . . . . . Compatibility note: In all Lisp systems since Lisp 1.5, mapl has been called map. In the chapter on sequences it is explained why this was a bad choice. Here the name map is used for the far more useful generic sequence mapper, in closer accordance with the computer science literature, especially the growing body of papers on functional programming. Note that this remark, predating the design of the Common Lisp Object System,| uses the term "generic" in a generic sense and not necessarily in the | technical sense used by CLOS (see chapter 2). | . . . . . . . . . . . . . . . . . . . . These functions are used when the function is being called merely for its side effects rather than for its returned values. The value returned by mapl or mapc is the second argument, that is, the first sequence argument. mapcan and mapcon are like mapcar and maplist, respectively, except that they combine the results of the function using nconc instead of list. That is, (mapcon f x1 ... xn) == (apply #'nconc (maplist f x1 ... xn)) and similarly for the relationship between mapcan and mapcar. Conceptually, these functions allow the mapped function to return a variable number of items to be put into the output list. This is particularly useful for effectively returning zero or one item: (mapcan #'(lambda (x) (and (numberp x) (list x))) '(a 1 b c 3 4 d 5)) ==> (1 3 4 5) In this case the function serves as a filter; this is a standard Lisp idiom using mapcan. (The function remove-if-not might have been useful in this particular context, however.) Remember that nconc is a destructive operation, and therefore so are mapcan and mapcon; the lists returned by the function are altered in order to concatenate them. Sometimes a do or a straightforward recursion is preferable to a mapping operation; however, the mapping functions should be used wherever they naturally apply because this increases the clarity of the code. The functional argument to a mapping function must be acceptable to apply; it cannot be a macro or the name of a special form. Of course, there is nothing wrong with using a function that has &optional and &rest parameters as the functional argument. X3J13 voted in June 1988 <90> to allow the function to be only of type symbol| or function; a lambda-expression is no longer acceptable as a functional | argument. One must use the function special form or the abbreviation #' before| a lambda-expression that appears as an explicit argument form. | X3J13 voted in January 1989 <121> to restrict user side effects; see | section 7.9. | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7.8.5. <## The "Program Feature" ##> Lisp implementations since Lisp 1.5 have had what was originally called "the program feature," as if it were impossible to write programs without it! The prog construct allows one to write in an Algol-like or Fortran-like statement-oriented style, using go statements that can refer to tags in the body of the prog. Modern Lisp programming style tends to use prog rather infrequently. The various iteration constructs, such as do, have bodies with the characteristics of a prog. (However, the ability to use go statements within iteration constructs is very seldom called upon in practice.) Three distinct operations are performed by prog: it binds local variables, it permits use of the return statement, and it permits use of the go statement. In Common Lisp, these three operations have been separated into three distinct constructs: let, block, and tagbody. These three constructs may be used independently as building blocks for other types of constructs. ---------<<>> tagbody tagbody {tag | statement}* The part of a tagbody after the variable list is called the body. An item in the body may be a symbol or an integer, in which case it is called a tag, or an item in the body may be a list, in which case it is called a statement. Each element of the body is processed from left to right. A tag is ignored; a statement is evaluated, and its results are discarded. If the end of the body is reached, the tagbody returns nil. If (go tag) is evaluated, control jumps to the part of the body labelled with the tag. . . . . . . . . . . . . . . . . . . . . Compatibility note: The "computed go" feature of MacLisp is not supported. The syntax of a computed go is idiosyncratic, and the feature is not supported by Lisp Machine Lisp, NIL (New Implementation of Lisp), or Interlisp. The computed go has been infrequently used in MacLisp anyway and is easily simulated with no loss of efficiency by using a case statement each of whose clauses performs a (non-computed) go. . . . . . . . . . . . . . . . . . . . . The scope of the tags established by a tagbody is lexical, and the extent is dynamic. Once a tagbody construct has been exited, it is no longer legal to go to a tag in its body. It is permissible for a go to jump to a tagbody that is not the innermost tagbody construct containing that go; the tags established by a tagbody will only shadow other tags of like name. The lexical scoping of the go targets named by tags is fully general and has consequences that may be surprising to users and implementors of other Lisp systems. For example, the go in the following example actually does work in Common Lisp as one might expect: (tagbody (catch 'stuff (mapcar #'(lambda (x) (if (numberp x) (hairyfun x) (go lose))) items)) (return) lose (error "I lost big!")) Depending on the situation, a go in Common Lisp does not necessarily correspond to a simple machine "jump" instruction. A go can break up catchers if necessary to get to the target. It is possible for a "closure" created by function for a lambda-expression to refer to a go target as long as the tag is lexically apparent. See chapter 3 for an elaborate example of this. There are some holes in this specification (and that of go) that leave some | room for interpretation. For example, there is no explicit prohibition against| the same tag appearing more than once in the same tagbody body. Every | implementation I know of will complain in the compiler, if not in the | interpreter, if there is a go to such a duplicated tag; but some implementors | take the position that duplicate tags are permitted provided there is no go to | such a tag. ("If a tree falls in the forest, and there is no one there to hear| it, then no one needs to yell `Timber!'") Also, some implementations allow | objects other than symbols, integers, and lists in the body and typically | ignore them. Consequently, some programmers use redundant tags such as --- for| formatting purposes, and strings as comments: | | (defun dining-philosopher (j) | (tagbody --- | think (unless (hungry) (go think)) | --- | "Can't eat without chopsticks." | (snatch (chopstick j)) | (snatch (chopstick (mod (+ j 1) 5))) | --- | eat (when (hungry) | (mapc #'gobble-down | '(twice-cooked-pork kung-pao-chi-ding | wu-dip-har orange-flavor-beef | two-side-yellow-noodles twinkies)) | (go eat)) | --- | "Can't think with my neighbors' stomachs rumbling." | (relinquish (chopstick j)) | (relinquish (chopstick (mod (+ j 1) 5))) | --- | (if (happy) (go think) | (become insurance-salesman)))) | | In certain implementations of Common Lisp they get away with it. Others | abhor what they view as an abuse of unintended ambiguity in the language | specification. For maximum portability, I advise users to steer clear of these| issues. Similarly, it is best to avoid using nil as a tag, even though it is a| symbol, because a few implementations treat nil as a list to be executed. To | be extra careful, avoid calling from within a tagbody a macro whose expansion | might not be a non-nil list; wrap such a call in (progn ...), or rewrite the | macro to return (progn ...) if possible. | ---------<<>> prog prog ({var | (var [init])}*) {declaration}* {tag | statement}* ---------<<>> prog* prog* ({var | (var [init])}*) {declaration}* {tag | statement}* The prog construct is a synthesis of let, block, and tagbody, allowing bound variables and the use of return and go within a single construct. A typical prog construct looks like this: (prog (var1 var2 (var3 init3) var4 (var5 init5)) {declaration}* statement1 tag1 statement2 statement3 statement4 tag2 statement5 ... ) The list after the keyword prog is a set of specifications for binding var1, var2, etc., which are temporary variables bound locally to the prog. This list is processed exactly as the list in a let statement: first all the init forms are evaluated from left to right (where nil is used for any omitted init form), and then the variables are all bound in parallel to the respective results. Any declaration appearing in the prog is used as if appearing at the top of the let body. The body of the prog is executed as if it were a tagbody construct; the go statement may be used to transfer control to a tag. A prog implicitly establishes a block named nil around the entire prog construct, so that return may be used at any time to exit from the prog construct. Here is a fine example of what can be done with prog: (defun king-of-confusion (w) "Take a cons of two lists and make a list of conses. Think of this function as being like a zipper." (prog (x y z) ; Initialize x, y, z to nil (setq y (car w) z (cdr w)) loop (cond ((null y) (return x)) ((null z) (go err))) rejoin (setq x (cons (cons (car y) (car z)) x)) (setq y (cdr y) z (cdr z)) (go loop) err (cerror "Will self-pair extraneous items" "Mismatch - gleep! S" y) (setq z y) (go rejoin))) which is accomplished somewhat more perspicuously by (defun prince-of-clarity (w) "Take a cons of two lists and make a list of conses. Think of this function as being like a zipper." (do ((y (car w) (cdr y)) (z (cdr w) (cdr z)) (x '() (cons (cons (car y) (car z)) x))) ((null y) x) (when (null z) (cerror "Will self-pair extraneous items" "Mismatch - gleep! S" y) (setq z y)))) The prog construct may be explained in terms of the simpler constructs block, let, and tagbody as follows: (prog variable-list {declaration}* . body) == (block nil (let variable-list {declaration}* (tagbody . body))) The prog* special form is almost the same as prog. The only difference is that the binding and initialization of the temporary variables is done sequentially, so that the init form for each one can use the values of previous ones. Therefore prog* is to prog as let* is to let. For example, (prog* ((y z) (x (car y))) (return x)) returns the car of the value of z. I haven't seen prog used very much in the last several years. Apparently | splitting it into functional constituents (let, block, tagbody) has been a | success. Common Lisp programmers now tend to use whichever specific construct | is appropriate. | ---------<<>> go go tag The (go tag) special form is used to do a "go to" within a tagbody construct. The tag must be a symbol or an integer; the tag is not evaluated. go transfers control to the point in the body labelled by a tag eql to the one given. If there is no such tag in the body, the bodies of lexically containing tagbody constructs (if any) are examined as well. It is an error if there is no matching tag lexically visible to the point of the go. The go form does not ever return a value. As a matter of style, it is recommended that the user think twice before using a go. Most purposes of go can be accomplished with one of the iteration primitives, nested conditional forms, or return-from. If the use of go seems to be unavoidable, perhaps the control structure implemented by go should be packaged as a macro definition. ------------------------------------------------------------------------------- 7.9. <### Structure Traversal and Side Effects ###> | | X3J13 voted in January 1989 <121> to restrict side effects during the course | of a built-in operation that can execute user-supplied code while traversing a | data structure. | | Consider the following example: | | (let ((x '(apples peaches pumpkin pie))) | (dolist (z x) | (when (eq z 'peaches) | (setf (cddr x) '(mango kumquat))) | (format t " S " (car z)))) | | Depending on the details of the implementation of dolist, this bit of code | could easily print | apples peaches mango kumquat | (which is perhaps what was intended), but it might as easily print | apples peaches pumpkin pie | | Here is a plausible implementation of dolist that produces the first result: | (defmacro dolist ((var listform &optional (resultform ''nil)) | &body body) | (let ((tailvar (gensym "DOLIST"))) | `(do ((,tailvar ,listform (cdr ,tailvar))) | ((null ,tailvar) ,resultform) | (let ((,var (car ,tailvar))) ,@body)))) | But here is a plausible implementation of dolist that produces the second | result: | (defmacro dolist ((var listform &optional (resultform ''nil)) | &body body) | (let ((tailvar (gensym "DOLIST"))) | `(do ((,tailvar ,listform)) | ((null ,tailvar) ,resultform) | (let ((,var (pop ,tailvar))) ,@body)))) | | The X3J13 recognizes and legitimizes varying implementation practices: in | general it is an error for code executed during a "structure-traversing" | operation to destructively modify the structure in a way that might affect the | ongoing traversal operation. The committee identified in particular the | following special cases. | | For list traversal operations, the cdr chain may not be destructively | modified. | | For array traversal operations, the array may not be adjusted (see | adjust-array) and its fill pointer, if any, may not be modified. | | For hash table operations (such as with-hash-table-iterator and maphash), new| entries may not be added or deleted, except that the very entry being processed| by user code may be changed or deleted. | | For package symbol operations (for example, with-package-iterator and | do-symbols), new symbols may not be interned in, nor symbols uninterned from, | the packages being traversed or any packages they use, except that the very | symbol being processed by user code may be uninterned. | | X3J13 noted that this vote is intended to clarify restrictions on the use of | structure traversal operations that are not themselves inherently destructive; | for example, it applies to map and dolist. Destructive operators such as | delete require even more complicated restrictions and are addressed by a | separate proposal. | | The X3J13 vote did not specify a complete list of the operations to which | these restrictions apply. Table 7-1 shows what I believe to be a complete list| of operations that traverse structures and take user code as a body (in the | case of macros) or as a functional argument (in the case of functions). | | In addition, note that user code should not modify list structure that might | be undergoing interpretation by the evaluator, whether explicitly invoked via | eval or implicitly invoked, for example as in the case of a hook function (a | defstruct print function, the value of *evalhook* or *applyhook*, etc.) that | happens to be a closure of interpreted code. Similarly, defstruct print | functions and other hooks should not perform side effects on data structures | being printed or being processed by format, or on a string given to | make-string-input-stream. You get the idea; be sensible. | | Note that an operation such as mapcar or dolist traverses not only cdr | pointers (in order to chase down the list) but also car pointers (in order to | obtain the elements themselves). The restriction against modification appears | to apply to all these pointers. | ............................................................................... Table 7-1: Structure Traversal Operations Subject to Side Effect Restrictions | adjoin maphash reduce | assoc mapl remove | assoc-if maplist remove-duplicates | assoc-if-not member remove-if | count member-if remove-if-not | count-if member-if-not search | count-if-not merge set-difference | delete mismatch set-exclusive-or | delete-duplicates nintersection some | delete-if notany sort | delete-if-not notevery stable-sort | do-all-symbols nset-difference sublis | do-external-symbols nset-exclusive-or subsetp | do-symbols nsublis subst | dolist nsubst subst-if | eval nsubst-if subst-if-not | every nsubst-if-not substitute | find nsubstitute substitute-if | find-if nsubstitute-if substitute-if-not | find-if-not nsubstitute-if-not tree-equal | intersection nunion union | certain loop clauses position with-hash-table-iterator | map position-if with-input-from-string | mapc position-if-not with-output-to-string | mapcan rassoc with-package-iterator | mapcar rassoc-if | mapcon rassoc-if-not | ............................................................................... ------------------------------------------------------------------------------- 7.10. <### Multiple Values ###> Ordinarily the result of calling a Lisp function is a single Lisp object. Sometimes, however, it is convenient for a function to compute several objects and return them. Common Lisp provides a mechanism for handling multiple values directly. This mechanism is cleaner and more efficient than the usual tricks involving returning a list of results or stashing results in global variables. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7.10.1. <## Constructs for Handling Multiple Values ##> Normally multiple values are not used. Special forms are required both to produce multiple values and to receive them. If the caller of a function does not request multiple values, but the called function produces multiple values, then the first value is given to the caller and all others are discarded; if the called function produces zero values, then the caller gets nil as a value. The primary primitive for producing multiple values is values, which takes any number of arguments and returns that many values. If the last form in the body of a function is a values with three arguments, then a call to that function will return three values. Other special forms also produce multiple values, but they can be described in terms of values. Some built-in Common Lisp functions, such as floor, return multiple values; those that do are so documented. The special forms and macros for receiving multiple values are as follows: multiple-value-list multiple-value-call multiple-value-prog1 multiple-value-bind multiple-value-setq These specify a form to evaluate and an indication of where to put the values returned by that form. ---------<<>> values values &rest args All of the arguments are returned, in order, as values. For example: (defun polar (x y) (values (sqrt (+ (* x x) (* y y))) (atan y x))) (multiple-value-bind (r theta) (polar 3.0 4.0) (vector r theta)) ==> #(5.0 0.9272952) The expression (values) returns zero values. This is the standard idiom for returning no values from a function. Sometimes it is desirable to indicate explicitly that a function will return exactly one value. For example, the function (defun foo (x y) (floor (+ x y) y)) will return two values because floor returns two values. It may be that the second value makes no sense, or that for efficiency reasons it is desired not to compute the second value. The values function is the standard idiom for indicating that only one value is to be returned, as shown in the following example. (defun foo (x y) (values (floor (+ x y) y))) This works because values returns exactly one value for each of its argument forms; as for any function call, if any argument form to values produces more than one value, all but the first are discarded. There is absolutely no way in Common Lisp for a caller to distinguish between returning a single value in the ordinary manner and returning exactly one "multiple value." For example, the values returned by the expressions (+ 1 2) and (values (+ 1 2)) are identical in every respect: the single value 3. ---------<<>> multiple-values-limit multiple-values-limit The value of multiple-values-limit is a positive integer that is the upper exclusive bound on the number of values that may be returned from a function. This bound depends on the implementation but will not be smaller than 20. (Implementors are encouraged to make this limit as large as practicable without sacrificing performance.) See lambda-parameters-limit and call-arguments-limit. ---------<<>> values-list values-list list All of the elements of list are returned as multiple values. For example: (values-list (list a b c)) == (values a b c) In general, (values-list list) == (apply #'values list) but values-list may be clearer or more efficient. ---------<<>> multiple-value-list multiple-value-list form multiple-value-list evaluates form and returns a list of the multiple values it returned. For example: (multiple-value-list (floor -3 4)) ==> (-1 1) multiple-value-list and values-list are therefore inverses of each other. ---------<<>> multiple-value-call multiple-value-call function {form}* multiple-value-call first evaluates function to obtain a function and then evaluates all of the forms. All the values of the forms are gathered together (not just one value from each) and are all given as arguments to the function. The result of multiple-value-call is whatever is returned by the function. For example: (+ (floor 5 3) (floor 19 4)) == (+ 1 4) ==> 5 (multiple-value-call #'+ (floor 5 3) (floor 19 4)) == (+ 1 2 4 3) ==> 10 (multiple-value-list form) == (multiple-value-call #'list form) ---------<<>> multiple-value-prog1 multiple-value-prog1 form {form}* multiple-value-prog1 evaluates the first form and saves all the values produced by that form. It then evaluates the other forms from left to right, discarding their values. The values produced by the first form are returned by multiple-value-prog1. See prog1, which always returns a single value. ---------<<>> multiple-value-bind multiple-value-bind ({var}*) values-form {declaration}* {form}* The values-form is evaluated, and each of the variables var is bound to the respective value returned by that form. If there are more variables than values returned, extra values of nil are given to the remaining variables. If there are more values than variables, the excess values are simply discarded. The variables are bound to the values over the execution of the forms, which make up an implicit progn. For example: (multiple-value-bind (x) (floor 5 3) (list x)) ==> (1) (multiple-value-bind (x y) (floor 5 3) (list x y)) ==> (1 2) (multiple-value-bind (x y z) (floor 5 3) (list x y z)) ==> (1 2 nil) ---------<<>> multiple-value-setq multiple-value-setq variables form The variables must be a list of variables. The form is evaluated, and the variables are set (not bound) to the values returned by that form. If there are more variables than values returned, extra values of nil are assigned to the remaining variables. If there are more values than variables, the excess values are simply discarded. . . . . . . . . . . . . . . . . . . . . Compatibility note: In Lisp Machine Lisp this is called multiple-value. The added clarity of the name multiple-value-setq in Common Lisp was deemed worth the incompatibility with Lisp Machine Lisp. . . . . . . . . . . . . . . . . . . . . multiple-value-setq always returns a single value, which is the first value returned by form, or nil if form produces zero values. X3J13 voted in March 1989 <173> to specify that if any var refers not to an | ordinary variable but to a binding made by symbol-macrolet, then that var is | handled as if setq were used to assign the appropriate value to it. | ---------<<>> nth-value | nth-value n form | | X3J13 voted in January 1989 <123> to add a new macro named nth-value. The | argument forms n and form are both evaluated. The value of n must be a | non-negative integer, and the form may produce any number of values. The | integer n is used as a zero-based index into the list of values. Value n of | the form is returned as the single value of the nth-value form; nil is returned| if the form produces no more than n values. | | As an example, mod could be defined as | (defun mod (number divisor) | (nth-value 1 (floor number divisor))) | Value number 1 is the second value returned by floor, the first value being | value number 0. | | One could define nth-value simply as | (defmacro nth-value (n form) | `(nth ,n (multiple-value-list ,form))) | but the clever implementor will doubtless find an implementation technique for | nth-value that avoids constructing an intermediate list of all the values of | the form. | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 7.10.2. <## Rules Governing the Passing of Multiple Values ##> It is often the case that the value of a special form or macro call is defined to be the value of one of its subforms. For example, the value of a cond is the value of the last form in the selected clause. In most such cases, if the subform produces multiple values, then the original form will also produce all of those values. This passing back of multiple values of course has no effect unless eventually one of the special forms for receiving multiple values is reached. To be explicit, multiple values can result from a special form under precisely these circumstances: * Evaluation and application - eval returns multiple values if the form given it to evaluate produces multiple values. - apply, funcall, and multiple-value-call pass back multiple values from the function applied or called. * Implicit progn contexts - The special form progn passes back multiple values resulting from evaluation of the last subform. Other situations referred to as "implicit progn," where several forms are evaluated and the results of all but the last form are discarded, also pass back multiple values from the last form. T