This is gcl.info, produced by makeinfo version 6.7 from gcl.texi.

This is a Texinfo GNU Common Lisp Manual based on the draft ANSI
standard for Common Lisp.

   Copyright 1994 William F. Schelter

INFO-DIR-SECTION GNU Common Lisp
START-INFO-DIR-ENTRY
* gcl: (gcl.info). GNU Common Lisp Manual
END-INFO-DIR-ENTRY


File: gcl.info,  Node: Top,  Next: Introduction (Introduction),  Prev: (dir),  Up: (dir)

* Menu:

* Introduction (Introduction)::
* Syntax::
* Evaluation and Compilation::
* Types and Classes::
* Data and Control Flow::
* Iteration::
* Objects::
* Structures::
* Conditions::
* Symbols::
* Packages::
* Numbers (Numbers)::
* Characters::
* Conses::
* Arrays::
* Strings::
* Sequences::
* Hash Tables::
* Filenames::
* Files::
* Streams::
* Printer::
* Reader::
* System Construction::
* Environment::
* Glossary (Glossary)::
* Appendix::

 -- The Detailed Node Listing --

Introduction

* Scope::
* Organization of the Document::
* Referenced Publications::
* Definitions::
* Conformance::
* Language Extensions::
* Language Subsets::
* Deprecated Language Features::
* Symbols in the COMMON-LISP Package::

Scope, Purpose, and History

* Scope and Purpose::
* History::

Definitions

* Notational Conventions::
* Error Terminology::
* Sections Not Formally Part Of This Standard::
* Interpreting Dictionary Entries::

Notational Conventions

* Font Key::
* Modified BNF Syntax::
* Splicing in Modified BNF Syntax::
* Indirection in Modified BNF Syntax::
* Additional Uses for Indirect Definitions in Modified BNF Syntax::
* Special Symbols::
* Objects with Multiple Notations::
* Case in Symbols::
* Numbers (Objects with Multiple Notations)::
* Use of the Dot Character::
* NIL::
* Designators::
* Nonsense Words::

Interpreting Dictionary Entries

* The "Affected By" Section of a Dictionary Entry::
* The "Arguments" Section of a Dictionary Entry::
* The "Arguments and Values" Section of a Dictionary Entry::
* The "Binding Types Affected" Section of a Dictionary Entry::
* The "Class Precedence List" Section of a Dictionary Entry::
* Dictionary Entries for Type Specifiers::
* The "Compound Type Specifier Kind" Section of a Dictionary Entry::
* The "Compound Type Specifier Syntax" Section of a Dictionary Entry::
* The "Compound Type Specifier Arguments" Section of a Dictionary Entry::
* The "Compound Type Specifier Description" Section of a Dictionary Entry::
* The "Constant Value" Section of a Dictionary Entry::
* The "Description" Section of a Dictionary Entry::
* The "Examples" Section of a Dictionary Entry::
* The "Exceptional Situations" Section of a Dictionary Entry::
* The "Initial Value" Section of a Dictionary Entry::
* The "Argument Precedence Order" Section of a Dictionary Entry::
* The "Method Signature" Section of a Dictionary Entry::
* The "Name" Section of a Dictionary Entry::
* The "Notes" Section of a Dictionary Entry::
* The "Pronunciation" Section of a Dictionary Entry::
* The "See Also" Section of a Dictionary Entry::
* The "Side Effects" Section of a Dictionary Entry::
* The "Supertypes" Section of a Dictionary Entry::
* The "Syntax" Section of a Dictionary Entry::
* Special "Syntax" Notations for Overloaded Operators::
* Naming Conventions for Rest Parameters::
* Requiring Non-Null Rest Parameters in The "Syntax" Section::
* Return values in The "Syntax" Section::
* No Arguments or Values in The "Syntax" Section::
* Unconditional Transfer of Control in The "Syntax" Section::
* The "Valid Context" Section of a Dictionary Entry::
* The "Value Type" Section of a Dictionary Entry::

Conformance

* Conforming Implementations::
* Conforming Programs::

Conforming Implementations

* Required Language Features::
* Documentation of Implementation-Dependent Features::
* Documentation of Extensions::
* Treatment of Exceptional Situations::
* Resolution of Apparent Conflicts in Exceptional Situations::
* Examples of Resolution of Apparent Conflict in Exceptional Situations::
* Conformance Statement::

Conforming Programs

* Use of Implementation-Defined Language Features::
* Use of Read-Time Conditionals::

Deprecated Language Features

* Deprecated Functions::
* Deprecated Argument Conventions::
* Deprecated Variables::
* Deprecated Reader Syntax::

Syntax

* Character Syntax::
* Reader Algorithm::
* Interpretation of Tokens::
* Standard Macro Characters::

Character Syntax

* Readtables::
* Variables that affect the Lisp Reader::
* Standard Characters::
* Character Syntax Types::

Readtables

* The Current Readtable::
* The Standard Readtable::
* The Initial Readtable::

Character Syntax Types

* Constituent Characters::
* Constituent Traits::
* Invalid Characters::
* Macro Characters::
* Multiple Escape Characters::
* Examples of Multiple Escape Characters::
* Single Escape Character::
* Examples of Single Escape Characters::
* Whitespace Characters::
* Examples of Whitespace Characters::

Interpretation of Tokens

* Numbers as Tokens::
* Constructing Numbers from Tokens::
* The Consing Dot::
* Symbols as Tokens::
* Valid Patterns for Tokens::
* Package System Consistency Rules::

Numbers as Tokens

* Potential Numbers as Tokens::
* Escape Characters and Potential Numbers::
* Examples of Potential Numbers::

Constructing Numbers from Tokens

* Syntax of a Rational::
* Syntax of an Integer::
* Syntax of a Ratio::
* Syntax of a Float::
* Syntax of a Complex::

Standard Macro Characters

* Left-Parenthesis::
* Right-Parenthesis::
* Single-Quote::
* Semicolon::
* Double-Quote::
* Backquote::
* Comma::
* Sharpsign::
* Re-Reading Abbreviated Expressions::

Single-Quote

* Examples of Single-Quote::

Semicolon

* Examples of Semicolon::
* Notes about Style for Semicolon::
* Use of Single Semicolon::
* Use of Double Semicolon::
* Use of Triple Semicolon::
* Use of Quadruple Semicolon::
* Examples of Style for Semicolon::

Backquote

* Notes about Backquote::

Sharpsign

* Sharpsign Backslash::
* Sharpsign Single-Quote::
* Sharpsign Left-Parenthesis::
* Sharpsign Asterisk::
* Examples of Sharpsign Asterisk::
* Sharpsign Colon::
* Sharpsign Dot::
* Sharpsign B::
* Sharpsign O::
* Sharpsign X::
* Sharpsign R::
* Sharpsign C::
* Sharpsign A::
* Sharpsign S::
* Sharpsign P::
* Sharpsign Equal-Sign::
* Sharpsign Sharpsign::
* Sharpsign Plus::
* Sharpsign Minus::
* Sharpsign Vertical-Bar::
* Examples of Sharpsign Vertical-Bar::
* Notes about Style for Sharpsign Vertical-Bar::
* Sharpsign Less-Than-Sign::
* Sharpsign Whitespace::
* Sharpsign Right-Parenthesis::

Evaluation and Compilation

* Evaluation::
* Compilation::
* Declarations::
* Lambda Lists::
* Error Checking in Function Calls::
* Traversal Rules and Side Effects::
* Destructive Operations::
* Evaluation and Compilation Dictionary::

Evaluation

* Introduction to Environments::
* The Evaluation Model::
* Lambda Expressions::
* Closures and Lexical Binding::
* Shadowing::
* Extent::
* Return Values::

Introduction to Environments

* The Global Environment::
* Dynamic Environments::
* Lexical Environments::
* The Null Lexical Environment::
* Environment Objects::

The Evaluation Model

* Form Evaluation::
* Symbols as Forms::
* Lexical Variables::
* Dynamic Variables::
* Constant Variables::
* Symbols Naming Both Lexical and Dynamic Variables::
* Conses as Forms::
* Special Forms::
* Macro Forms::
* Function Forms::
* Lambda Forms::
* Self-Evaluating Objects::
* Examples of Self-Evaluating Objects::

Compilation

* Compiler Terminology::
* Compilation Semantics::
* File Compilation::
* Literal Objects in Compiled Files::
* Exceptional Situations in the Compiler::

Compilation Semantics

* Compiler Macros::
* Purpose of Compiler Macros::
* Naming of Compiler Macros::
* When Compiler Macros Are Used::
* Notes about the Implementation of Compiler Macros::
* Minimal Compilation::
* Semantic Constraints::

File Compilation

* Processing of Top Level Forms::
* Processing of Defining Macros::
* Constraints on Macros and Compiler Macros::

Literal Objects in Compiled Files

* Externalizable Objects::
* Similarity of Literal Objects::
* Similarity of Aggregate Objects::
* Definition of Similarity::
* Extensions to Similarity Rules::
* Additional Constraints on Externalizable Objects::

Declarations

* Minimal Declaration Processing Requirements::
* Declaration Specifiers::
* Declaration Identifiers::
* Declaration Scope::

Declaration Identifiers

* Shorthand notation for Type Declarations::

Declaration Scope

* Examples of Declaration Scope::

Lambda Lists

* Ordinary Lambda Lists::
* Generic Function Lambda Lists::
* Specialized Lambda Lists::
* Macro Lambda Lists::
* Destructuring Lambda Lists::
* Boa Lambda Lists::
* Defsetf Lambda Lists::
* Deftype Lambda Lists::
* Define-modify-macro Lambda Lists::
* Define-method-combination Arguments Lambda Lists::
* Syntactic Interaction of Documentation Strings and Declarations::

Ordinary Lambda Lists

* Specifiers for the required parameters::
* Specifiers for optional parameters::
* A specifier for a rest parameter::
* Specifiers for keyword parameters::
* Suppressing Keyword Argument Checking::
* Examples of Suppressing Keyword Argument Checking::
* Specifiers for &aux variables::
* Examples of Ordinary Lambda Lists::

Macro Lambda Lists

* Destructuring by Lambda Lists::
* Data-directed Destructuring by Lambda Lists::
* Examples of Data-directed Destructuring by Lambda Lists::
* Lambda-list-directed Destructuring by Lambda Lists::

Error Checking in Function Calls

* Argument Mismatch Detection::

Argument Mismatch Detection

* Safe and Unsafe Calls::
* Error Detection Time in Safe Calls::
* Too Few Arguments::
* Too Many Arguments::
* Unrecognized Keyword Arguments::
* Invalid Keyword Arguments::
* Odd Number of Keyword Arguments::
* Destructuring Mismatch::
* Errors When Calling a Next Method::

Destructive Operations

* Modification of Literal Objects::
* Transfer of Control during a Destructive Operation::

Transfer of Control during a Destructive Operation

* Examples of Transfer of Control during a Destructive Operation::

Evaluation and Compilation Dictionary

* lambda (Symbol)::
* lambda::
* compile::
* eval::
* eval-when::
* load-time-value::
* quote::
* compiler-macro-function::
* define-compiler-macro::
* defmacro::
* macro-function::
* macroexpand::
* define-symbol-macro::
* symbol-macrolet::
* *macroexpand-hook*::
* proclaim::
* declaim::
* declare::
* ignore::
* dynamic-extent::
* type::
* inline::
* ftype::
* declaration::
* optimize::
* special::
* locally::
* the::
* special-operator-p::
* constantp::

Types and Classes

* Introduction (Types and Classes)::
* Types::
* Classes::
* Types and Classes Dictionary::

Types

* Data Type Definition::
* Type Relationships::
* Type Specifiers::

Classes

* Introduction to Classes::
* Defining Classes::
* Creating Instances of Classes::
* Inheritance::
* Determining the Class Precedence List::
* Redefining Classes::
* Integrating Types and Classes::

Introduction to Classes

* Standard Metaclasses::

Inheritance

* Examples of Inheritance::
* Inheritance of Class Options::

Determining the Class Precedence List

* Topological Sorting::
* Examples of Class Precedence List Determination::

Redefining Classes

* Modifying the Structure of Instances::
* Initializing Newly Added Local Slots (Redefining Classes)::
* Customizing Class Redefinition::

Types and Classes Dictionary

* nil (Type)::
* boolean::
* function (System Class)::
* compiled-function::
* generic-function::
* standard-generic-function::
* class::
* built-in-class::
* structure-class::
* standard-class::
* method::
* standard-method::
* structure-object::
* standard-object::
* method-combination::
* t (System Class)::
* satisfies::
* member (Type Specifier)::
* not (Type Specifier)::
* and (Type Specifier)::
* or (Type Specifier)::
* values (Type Specifier)::
* eql (Type Specifier)::
* coerce::
* deftype::
* subtypep::
* type-of::
* typep::
* type-error::
* type-error-datum::
* simple-type-error::

Data and Control Flow

* Generalized Reference::
* Transfer of Control to an Exit Point::
* Data and Control Flow Dictionary::

Generalized Reference

* Overview of Places and Generalized Reference::
* Kinds of Places::
* Treatment of Other Macros Based on SETF::

Overview of Places and Generalized Reference

* Evaluation of Subforms to Places::
* Examples of Evaluation of Subforms to Places::
* Setf Expansions::
* Examples of Setf Expansions::

Kinds of Places

* Variable Names as Places::
* Function Call Forms as Places::
* VALUES Forms as Places::
* THE Forms as Places::
* APPLY Forms as Places::
* Setf Expansions and Places::
* Macro Forms as Places::
* Symbol Macros as Places::
* Other Compound Forms as Places::

Data and Control Flow Dictionary

* apply::
* defun::
* fdefinition::
* fboundp::
* fmakunbound::
* flet::
* funcall::
* function (Special Operator)::
* function-lambda-expression::
* functionp::
* compiled-function-p::
* call-arguments-limit::
* lambda-list-keywords::
* lambda-parameters-limit::
* defconstant::
* defparameter::
* destructuring-bind::
* let::
* progv::
* setq::
* psetq::
* block::
* catch::
* go::
* return-from::
* return::
* tagbody::
* throw::
* unwind-protect::
* nil::
* not::
* t::
* eq::
* eql::
* equal::
* equalp::
* identity::
* complement::
* constantly::
* every::
* and::
* cond::
* if::
* or::
* when::
* case::
* typecase::
* multiple-value-bind::
* multiple-value-call::
* multiple-value-list::
* multiple-value-prog1::
* multiple-value-setq::
* values::
* values-list::
* multiple-values-limit::
* nth-value::
* prog::
* prog1::
* progn::
* define-modify-macro::
* defsetf::
* define-setf-expander::
* get-setf-expansion::
* setf::
* shiftf::
* rotatef::
* control-error::
* program-error::
* undefined-function::

Iteration

* The LOOP Facility::
* Iteration Dictionary::

The LOOP Facility

* Overview of the Loop Facility::
* Variable Initialization and Stepping Clauses::
* Value Accumulation Clauses::
* Termination Test Clauses::
* Unconditional Execution Clauses::
* Conditional Execution Clauses::
* Miscellaneous Clauses::
* Examples of Miscellaneous Loop Features::
* Notes about Loop::

Overview of the Loop Facility

* Simple vs Extended Loop::
* Simple Loop::
* Extended Loop::
* Loop Keywords::
* Parsing Loop Clauses::
* Expanding Loop Forms::
* Summary of Loop Clauses::
* Summary of Variable Initialization and Stepping Clauses::
* Summary of Value Accumulation Clauses::
* Summary of Termination Test Clauses::
* Summary of Unconditional Execution Clauses::
* Summary of Conditional Execution Clauses::
* Summary of Miscellaneous Clauses::
* Order of Execution::
* Destructuring::
* Restrictions on Side-Effects::

Variable Initialization and Stepping Clauses

* Iteration Control::
* The for-as-arithmetic subclause::
* Examples of for-as-arithmetic subclause::
* The for-as-in-list subclause::
* Examples of for-as-in-list subclause::
* The for-as-on-list subclause::
* Examples of for-as-on-list subclause::
* The for-as-equals-then subclause::
* Examples of for-as-equals-then subclause::
* The for-as-across subclause::
* Examples of for-as-across subclause::
* The for-as-hash subclause::
* The for-as-package subclause::
* Examples of for-as-package subclause::
* Local Variable Initializations::
* Examples of WITH clause::

Value Accumulation Clauses

* Examples of COLLECT clause::
* Examples of APPEND and NCONC clauses::
* Examples of COUNT clause::
* Examples of MAXIMIZE and MINIMIZE clauses::
* Examples of SUM clause::

Termination Test Clauses

* Examples of REPEAT clause::
* Examples of ALWAYS::
* Examples of WHILE and UNTIL clauses::

Unconditional Execution Clauses

* Examples of unconditional execution::

Conditional Execution Clauses

* Examples of WHEN clause::

Miscellaneous Clauses

* Control Transfer Clauses::
* Examples of NAMED clause::
* Initial and Final Execution::

Examples of Miscellaneous Loop Features

* Examples of clause grouping::

Iteration Dictionary

* do::
* dotimes::
* dolist::
* loop::
* loop-finish::

Objects

* Object Creation and Initialization::
* Changing the Class of an Instance::
* Reinitializing an Instance::
* Meta-Objects::
* Slots::
* Generic Functions and Methods::
* Objects Dictionary::

Object Creation and Initialization

* Initialization Arguments::
* Declaring the Validity of Initialization Arguments::
* Defaulting of Initialization Arguments::
* Rules for Initialization Arguments::
* Shared-Initialize::
* Initialize-Instance::
* Definitions of Make-Instance and Initialize-Instance::

Changing the Class of an Instance

* Modifying the Structure of the Instance::
* Initializing Newly Added Local Slots (Changing the Class of an Instance)::
* Customizing the Change of Class of an Instance::

Reinitializing an Instance

* Customizing Reinitialization::

Meta-Objects

* Standard Meta-objects::

Slots

* Introduction to Slots::
* Accessing Slots::
* Inheritance of Slots and Slot Options::

Generic Functions and Methods

* Introduction to Generic Functions::
* Introduction to Methods::
* Agreement on Parameter Specializers and Qualifiers::
* Congruent Lambda-lists for all Methods of a Generic Function::
* Keyword Arguments in Generic Functions and Methods::
* Method Selection and Combination::
* Inheritance of Methods::

Keyword Arguments in Generic Functions and Methods

* Examples of Keyword Arguments in Generic Functions and Methods::

Method Selection and Combination

* Determining the Effective Method::
* Selecting the Applicable Methods::
* Sorting the Applicable Methods by Precedence Order::
* Applying method combination to the sorted list of applicable methods::
* Standard Method Combination::
* Declarative Method Combination::
* Built-in Method Combination Types::

Objects Dictionary

* function-keywords::
* ensure-generic-function::
* allocate-instance::
* reinitialize-instance::
* shared-initialize::
* update-instance-for-different-class::
* update-instance-for-redefined-class::
* change-class::
* slot-boundp::
* slot-exists-p::
* slot-makunbound::
* slot-missing::
* slot-unbound::
* slot-value::
* method-qualifiers::
* no-applicable-method::
* no-next-method::
* remove-method::
* make-instance::
* make-instances-obsolete::
* make-load-form::
* make-load-form-saving-slots::
* with-accessors::
* with-slots::
* defclass::
* defgeneric::
* defmethod::
* find-class::
* next-method-p::
* call-method::
* call-next-method::
* compute-applicable-methods::
* define-method-combination::
* find-method::
* add-method::
* initialize-instance::
* class-name::
* (setf class-name)::
* class-of::
* unbound-slot::
* unbound-slot-instance::

Structures

* Structures Dictionary::

Structures Dictionary

* defstruct::
* copy-structure::

Conditions

* Condition System Concepts::
* Conditions Dictionary::

Condition System Concepts

* Condition Types::
* Creating Conditions::
* Printing Conditions::
* Signaling and Handling Conditions::
* Assertions::
* Notes about the Condition System`s Background::

Condition Types

* Serious Conditions::

Creating Conditions

* Condition Designators::

Printing Conditions

* Recommended Style in Condition Reporting::
* Capitalization and Punctuation in Condition Reports::
* Leading and Trailing Newlines in Condition Reports::
* Embedded Newlines in Condition Reports::
* Note about Tabs in Condition Reports::
* Mentioning Containing Function in Condition Reports::

Signaling and Handling Conditions

* Signaling::
* Resignaling a Condition::
* Restarts::
* Interactive Use of Restarts::
* Interfaces to Restarts::
* Restart Tests::
* Associating a Restart with a Condition::

Conditions Dictionary

* condition::
* warning::
* style-warning::
* serious-condition::
* error (Condition Type)::
* cell-error::
* cell-error-name::
* parse-error::
* storage-condition::
* assert::
* error::
* cerror::
* check-type::
* simple-error::
* invalid-method-error::
* method-combination-error::
* signal::
* simple-condition::
* simple-condition-format-control::
* warn::
* simple-warning::
* invoke-debugger::
* break::
* *debugger-hook*::
* *break-on-signals*::
* handler-bind::
* handler-case::
* ignore-errors::
* define-condition::
* make-condition::
* restart::
* compute-restarts::
* find-restart::
* invoke-restart::
* invoke-restart-interactively::
* restart-bind::
* restart-case::
* restart-name::
* with-condition-restarts::
* with-simple-restart::
* abort (Restart)::
* continue::
* muffle-warning::
* store-value::
* use-value::
* abort (Function)::

Symbols

* Symbol Concepts::
* Symbols Dictionary::

Symbols Dictionary

* symbol::
* keyword::
* symbolp::
* keywordp::
* make-symbol::
* copy-symbol::
* gensym::
* *gensym-counter*::
* gentemp::
* symbol-function::
* symbol-name::
* symbol-package::
* symbol-plist::
* symbol-value::
* get::
* remprop::
* boundp::
* makunbound::
* set::
* unbound-variable::

Packages

* Package Concepts::
* Packages Dictionary::

Package Concepts

* Introduction to Packages::
* Standardized Packages::

Introduction to Packages

* Package Names and Nicknames::
* Symbols in a Package::
* Internal and External Symbols::
* Package Inheritance::
* Accessibility of Symbols in a Package::
* Locating a Symbol in a Package::
* Prevention of Name Conflicts in Packages::

Standardized Packages

* The COMMON-LISP Package::
* Constraints on the COMMON-LISP Package for Conforming Implementations::
* Constraints on the COMMON-LISP Package for Conforming Programs::
* Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs::
* The COMMON-LISP-USER Package::
* The KEYWORD Package::
* Interning a Symbol in the KEYWORD Package::
* Notes about The KEYWORD Package::
* Implementation-Defined Packages::

Packages Dictionary

* package::
* export::
* find-symbol::
* find-package::
* find-all-symbols::
* import::
* list-all-packages::
* rename-package::
* shadow::
* shadowing-import::
* delete-package::
* make-package::
* with-package-iterator::
* unexport::
* unintern::
* in-package::
* unuse-package::
* use-package::
* defpackage::
* do-symbols::
* intern::
* package-name::
* package-nicknames::
* package-shadowing-symbols::
* package-use-list::
* package-used-by-list::
* packagep::
* *package*::
* package-error::
* package-error-package::

Numbers

* Number Concepts::
* Numbers Dictionary::

Number Concepts

* Numeric Operations::
* Implementation-Dependent Numeric Constants::
* Rational Computations::
* Floating-point Computations::
* Complex Computations::
* Interval Designators::
* Random-State Operations::

Numeric Operations

* Associativity and Commutativity in Numeric Operations::
* Examples of Associativity and Commutativity in Numeric Operations::
* Contagion in Numeric Operations::
* Viewing Integers as Bits and Bytes::
* Logical Operations on Integers::
* Byte Operations on Integers::

Rational Computations

* Rule of Unbounded Rational Precision::
* Rule of Canonical Representation for Rationals::
* Rule of Float Substitutability::

Floating-point Computations

* Rule of Float and Rational Contagion::
* Examples of Rule of Float and Rational Contagion::
* Rule of Float Approximation::
* Rule of Float Underflow and Overflow::
* Rule of Float Precision Contagion::

Complex Computations

* Rule of Complex Substitutability::
* Rule of Complex Contagion::
* Rule of Canonical Representation for Complex Rationals::
* Examples of Rule of Canonical Representation for Complex Rationals::
* Principal Values and Branch Cuts::

Numbers Dictionary

* number::
* complex (System Class)::
* real::
* float (System Class)::
* short-float::
* rational (System Class)::
* ratio::
* integer::
* signed-byte::
* unsigned-byte::
* mod (System Class)::
* bit (System Class)::
* fixnum::
* bignum::
* =::
* max::
* minusp::
* zerop::
* floor::
* sin::
* asin::
* pi::
* sinh::
* *::
* +::
* -::
* /::
* 1+::
* abs::
* evenp::
* exp::
* gcd::
* incf::
* lcm::
* log::
* mod (Function)::
* signum::
* sqrt::
* random-state::
* make-random-state::
* random::
* random-state-p::
* *random-state*::
* numberp::
* cis::
* complex::
* complexp::
* conjugate::
* phase::
* realpart::
* upgraded-complex-part-type::
* realp::
* numerator::
* rational (Function)::
* rationalp::
* ash::
* integer-length::
* integerp::
* parse-integer::
* boole::
* boole-1::
* logand::
* logbitp::
* logcount::
* logtest::
* byte::
* deposit-field::
* dpb::
* ldb::
* ldb-test::
* mask-field::
* most-positive-fixnum::
* decode-float::
* float::
* floatp::
* most-positive-short-float::
* short-float-epsilon::
* arithmetic-error::
* arithmetic-error-operands::
* division-by-zero::
* floating-point-invalid-operation::
* floating-point-inexact::
* floating-point-overflow::
* floating-point-underflow::

Characters

* Character Concepts::
* Characters Dictionary::

Character Concepts

* Introduction to Characters::
* Introduction to Scripts and Repertoires::
* Character Attributes::
* Character Categories::
* Identity of Characters::
* Ordering of Characters::
* Character Names::
* Treatment of Newline during Input and Output::
* Character Encodings::
* Documentation of Implementation-Defined Scripts::

Introduction to Scripts and Repertoires

* Character Scripts::
* Character Repertoires::

Character Categories

* Graphic Characters::
* Alphabetic Characters::
* Characters With Case::
* Uppercase Characters::
* Lowercase Characters::
* Corresponding Characters in the Other Case::
* Case of Implementation-Defined Characters::
* Numeric Characters::
* Alphanumeric Characters::
* Digits in a Radix::

Characters Dictionary

* character (System Class)::
* base-char::
* standard-char::
* extended-char::
* char=::
* character::
* characterp::
* alpha-char-p::
* alphanumericp::
* digit-char::
* digit-char-p::
* graphic-char-p::
* standard-char-p::
* char-upcase::
* upper-case-p::
* char-code::
* char-int::
* code-char::
* char-code-limit::
* char-name::
* name-char::

Conses

* Cons Concepts::
* Conses Dictionary::

Cons Concepts

* Conses as Trees::
* Conses as Lists::

Conses as Trees

* General Restrictions on Parameters that must be Trees::

Conses as Lists

* Lists as Association Lists::
* Lists as Sets::
* General Restrictions on Parameters that must be Lists::

Conses Dictionary

* list (System Class)::
* null (System Class)::
* cons (System Class)::
* atom (Type)::
* cons::
* consp::
* atom::
* rplaca::
* car::
* copy-tree::
* sublis::
* subst::
* tree-equal::
* copy-list::
* list (Function)::
* list-length::
* listp::
* make-list::
* push::
* pop::
* first::
* nth::
* endp::
* null::
* nconc::
* append::
* revappend::
* butlast::
* last::
* ldiff::
* nthcdr::
* rest::
* member (Function)::
* mapc::
* acons::
* assoc::
* copy-alist::
* pairlis::
* rassoc::
* get-properties::
* getf::
* remf::
* intersection::
* adjoin::
* pushnew::
* set-difference::
* set-exclusive-or::
* subsetp::
* union::

Arrays

* Array Concepts::
* Arrays Dictionary::

Array Concepts

* Array Elements::
* Specialized Arrays::

Array Elements

* Array Indices::
* Array Dimensions::
* Implementation Limits on Individual Array Dimensions::
* Array Rank::
* Vectors::
* Fill Pointers::
* Multidimensional Arrays::
* Storage Layout for Multidimensional Arrays::
* Implementation Limits on Array Rank::

Specialized Arrays

* Array Upgrading::
* Required Kinds of Specialized Arrays::

Arrays Dictionary

* array::
* simple-array::
* vector (System Class)::
* simple-vector::
* bit-vector::
* simple-bit-vector::
* make-array::
* adjust-array::
* adjustable-array-p::
* aref::
* array-dimension::
* array-dimensions::
* array-element-type::
* array-has-fill-pointer-p::
* array-displacement::
* array-in-bounds-p::
* array-rank::
* array-row-major-index::
* array-total-size::
* arrayp::
* fill-pointer::
* row-major-aref::
* upgraded-array-element-type::
* array-dimension-limit::
* array-rank-limit::
* array-total-size-limit::
* simple-vector-p::
* svref::
* vector::
* vector-pop::
* vector-push::
* vectorp::
* bit (Array)::
* bit-and::
* bit-vector-p::
* simple-bit-vector-p::

Strings

* String Concepts::
* Strings Dictionary::

String Concepts

* Implications of Strings Being Arrays::
* Subtypes of STRING::

Strings Dictionary

* string (System Class)::
* base-string::
* simple-string::
* simple-base-string::
* simple-string-p::
* char::
* string::
* string-upcase::
* string-trim::
* string=::
* stringp::
* make-string::

Sequences

* Sequence Concepts::
* Rules about Test Functions::
* Sequences Dictionary::

Sequence Concepts

* General Restrictions on Parameters that must be Sequences::

Rules about Test Functions

* Satisfying a Two-Argument Test::
* Satisfying a One-Argument Test::

Satisfying a Two-Argument Test

* Examples of Satisfying a Two-Argument Test::

Satisfying a One-Argument Test

* Examples of Satisfying a One-Argument Test::

Sequences Dictionary

* sequence::
* copy-seq::
* elt::
* fill::
* make-sequence::
* subseq::
* map::
* map-into::
* reduce::
* count::
* length::
* reverse::
* sort::
* find::
* position::
* search::
* mismatch::
* replace::
* substitute::
* concatenate::
* merge::
* remove::
* remove-duplicates::

Hash Tables

* Hash Table Concepts::
* Hash Tables Dictionary::

Hash Table Concepts

* Hash-Table Operations::
* Modifying Hash Table Keys::

Modifying Hash Table Keys

* Visible Modification of Objects with respect to EQ and EQL::
* Visible Modification of Objects with respect to EQUAL::
* Visible Modification of Conses with respect to EQUAL::
* Visible Modification of Bit Vectors and Strings with respect to EQUAL::
* Visible Modification of Objects with respect to EQUALP::
* Visible Modification of Structures with respect to EQUALP::
* Visible Modification of Arrays with respect to EQUALP::
* Visible Modification of Hash Tables with respect to EQUALP::
* Visible Modifications by Language Extensions::

Hash Tables Dictionary

* hash-table::
* make-hash-table::
* hash-table-p::
* hash-table-count::
* hash-table-rehash-size::
* hash-table-rehash-threshold::
* hash-table-size::
* hash-table-test::
* gethash::
* remhash::
* maphash::
* with-hash-table-iterator::
* clrhash::
* sxhash::

Filenames

* Overview of Filenames::
* Pathnames::
* Logical Pathnames::
* Filenames Dictionary::

Overview of Filenames

* Namestrings as Filenames::
* Pathnames as Filenames::
* Parsing Namestrings Into Pathnames::

Pathnames

* Pathname Components::
* Interpreting Pathname Component Values::
* Merging Pathnames::

Pathname Components

* The Pathname Host Component::
* The Pathname Device Component::
* The Pathname Directory Component::
* The Pathname Name Component::
* The Pathname Type Component::
* The Pathname Version Component::

Interpreting Pathname Component Values

* Strings in Component Values::
* Special Characters in Pathname Components::
* Case in Pathname Components::
* Local Case in Pathname Components::
* Common Case in Pathname Components::
* Special Pathname Component Values::
* NIL as a Component Value::
* ->WILD as a Component Value::
* ->UNSPECIFIC as a Component Value::
* Relation between component values NIL and ->UNSPECIFIC::
* Restrictions on Wildcard Pathnames::
* Restrictions on Examining Pathname Components::
* Restrictions on Examining a Pathname Host Component::
* Restrictions on Examining a Pathname Device Component::
* Restrictions on Examining a Pathname Directory Component::
* Directory Components in Non-Hierarchical File Systems::
* Restrictions on Examining a Pathname Name Component::
* Restrictions on Examining a Pathname Type Component::
* Restrictions on Examining a Pathname Version Component::
* Notes about the Pathname Version Component::
* Restrictions on Constructing Pathnames::

Merging Pathnames

* Examples of Merging Pathnames::

Logical Pathnames

* Syntax of Logical Pathname Namestrings::
* Logical Pathname Components::

Syntax of Logical Pathname Namestrings

* Additional Information about Parsing Logical Pathname Namestrings::
* The Host part of a Logical Pathname Namestring::
* The Device part of a Logical Pathname Namestring::
* The Directory part of a Logical Pathname Namestring::
* The Type part of a Logical Pathname Namestring::
* The Version part of a Logical Pathname Namestring::
* Wildcard Words in a Logical Pathname Namestring::
* Lowercase Letters in a Logical Pathname Namestring::
* Other Syntax in a Logical Pathname Namestring::

Logical Pathname Components

* Unspecific Components of a Logical Pathname::
* Null Strings as Components of a Logical Pathname::

Filenames Dictionary

* pathname (System Class)::
* logical-pathname (System Class)::
* pathname::
* make-pathname::
* pathnamep::
* pathname-host::
* load-logical-pathname-translations::
* logical-pathname-translations::
* logical-pathname::
* *default-pathname-defaults*::
* namestring::
* parse-namestring::
* wild-pathname-p::
* pathname-match-p::
* translate-logical-pathname::
* translate-pathname::
* merge-pathnames::

Files

* File System Concepts::
* Files Dictionary::

File System Concepts

* Coercion of Streams to Pathnames::
* File Operations on Open and Closed Streams::
* Truenames::

Truenames

* Examples of Truenames::

Files Dictionary

* directory::
* probe-file::
* ensure-directories-exist::
* truename::
* file-author::
* file-write-date::
* rename-file::
* delete-file::
* file-error::
* file-error-pathname::

Streams

* Stream Concepts::
* Streams Dictionary::

Stream Concepts

* Introduction to Streams::
* Stream Variables::
* Stream Arguments to Standardized Functions::
* Restrictions on Composite Streams::

Introduction to Streams

* Abstract Classifications of Streams (Introduction to Streams)::
* Input::
* Open and Closed Streams::
* Interactive Streams::
* Abstract Classifications of Streams::
* File Streams::
* Other Subclasses of Stream::

Streams Dictionary

* stream::
* broadcast-stream::
* concatenated-stream::
* echo-stream::
* file-stream::
* string-stream::
* synonym-stream::
* two-way-stream::
* input-stream-p::
* interactive-stream-p::
* open-stream-p::
* stream-element-type::
* streamp::
* read-byte::
* write-byte::
* peek-char::
* read-char::
* read-char-no-hang::
* terpri::
* unread-char::
* write-char::
* read-line::
* write-string::
* read-sequence::
* write-sequence::
* file-length::
* file-position::
* file-string-length::
* open::
* stream-external-format::
* with-open-file::
* close::
* with-open-stream::
* listen::
* clear-input::
* finish-output::
* y-or-n-p::
* make-synonym-stream::
* synonym-stream-symbol::
* broadcast-stream-streams::
* make-broadcast-stream::
* make-two-way-stream::
* two-way-stream-input-stream::
* echo-stream-input-stream::
* make-echo-stream::
* concatenated-stream-streams::
* make-concatenated-stream::
* get-output-stream-string::
* make-string-input-stream::
* make-string-output-stream::
* with-input-from-string::
* with-output-to-string::
* *debug-io*::
* *terminal-io*::
* stream-error::
* stream-error-stream::
* end-of-file::

Printer

* The Lisp Printer::
* The Lisp Pretty Printer::
* Formatted Output::
* Printer Dictionary::

The Lisp Printer

* Overview of The Lisp Printer::
* Printer Dispatching::
* Default Print-Object Methods::
* Examples of Printer Behavior::

Overview of The Lisp Printer

* Multiple Possible Textual Representations::
* Printer Escaping::

Default Print-Object Methods

* Printing Numbers::
* Printing Integers::
* Printing Ratios::
* Printing Floats::
* Printing Complexes::
* Note about Printing Numbers::
* Printing Characters::
* Printing Symbols::
* Package Prefixes for Symbols::
* Effect of Readtable Case on the Lisp Printer::
* Examples of Effect of Readtable Case on the Lisp Printer::
* Printing Strings::
* Printing Lists and Conses::
* Printing Bit Vectors::
* Printing Other Vectors::
* Printing Other Arrays::
* Examples of Printing Arrays::
* Printing Random States::
* Printing Pathnames::
* Printing Structures::
* Printing Other Objects::

The Lisp Pretty Printer

* Pretty Printer Concepts::
* Examples of using the Pretty Printer::
* Notes about the Pretty Printer`s Background::

Pretty Printer Concepts

* Dynamic Control of the Arrangement of Output::
* Format Directive Interface::
* Compiling Format Strings::
* Pretty Print Dispatch Tables::
* Pretty Printer Margins::

Formatted Output

* FORMAT Basic Output::
* FORMAT Radix Control::
* FORMAT Floating-Point Printers::
* FORMAT Printer Operations::
* FORMAT Pretty Printer Operations::
* FORMAT Layout Control::
* FORMAT Control-Flow Operations::
* FORMAT Miscellaneous Operations::
* FORMAT Miscellaneous Pseudo-Operations::
* Additional Information about FORMAT Operations::
* Examples of FORMAT::
* Notes about FORMAT::

FORMAT Basic Output

* Tilde C-> Character::
* Tilde Percent-> Newline::
* Tilde Ampersand-> Fresh-Line::
* Tilde Vertical-Bar-> Page::
* Tilde Tilde-> Tilde::

FORMAT Radix Control

* Tilde R-> Radix::
* Tilde D-> Decimal::
* Tilde B-> Binary::
* Tilde O-> Octal::
* Tilde X-> Hexadecimal::

FORMAT Floating-Point Printers

* Tilde F-> Fixed-Format Floating-Point::
* Tilde E-> Exponential Floating-Point::
* Tilde G-> General Floating-Point::
* Tilde Dollarsign-> Monetary Floating-Point::

FORMAT Printer Operations

* Tilde A-> Aesthetic::
* Tilde S-> Standard::
* Tilde W-> Write::

FORMAT Pretty Printer Operations

* Tilde Underscore-> Conditional Newline::
* Tilde Less-Than-Sign-> Logical Block::
* Tilde I-> Indent::
* Tilde Slash-> Call Function::

FORMAT Layout Control

* Tilde T-> Tabulate::
* Tilde Less-Than-Sign-> Justification::
* Tilde Greater-Than-Sign-> End of Justification::

FORMAT Control-Flow Operations

* Tilde Asterisk-> Go-To::
* Tilde Left-Bracket-> Conditional Expression::
* Tilde Right-Bracket-> End of Conditional Expression::
* Tilde Left-Brace-> Iteration::
* Tilde Right-Brace-> End of Iteration::
* Tilde Question-Mark-> Recursive Processing::

FORMAT Miscellaneous Operations

* Tilde Left-Paren-> Case Conversion::
* Tilde Right-Paren-> End of Case Conversion::
* Tilde P-> Plural::

FORMAT Miscellaneous Pseudo-Operations

* Tilde Semicolon-> Clause Separator::
* Tilde Circumflex-> Escape Upward::
* Tilde Newline-> Ignored Newline::

Additional Information about FORMAT Operations

* Nesting of FORMAT Operations::
* Missing and Additional FORMAT Arguments::
* Additional FORMAT Parameters::
* Undefined FORMAT Modifier Combinations::

Printer Dictionary

* copy-pprint-dispatch::
* formatter::
* pprint-dispatch::
* pprint-exit-if-list-exhausted::
* pprint-fill::
* pprint-indent::
* pprint-logical-block::
* pprint-newline::
* pprint-pop::
* pprint-tab::
* print-object::
* print-unreadable-object::
* set-pprint-dispatch::
* write::
* write-to-string::
* *print-array*::
* *print-base*::
* *print-case*::
* *print-circle*::
* *print-escape*::
* *print-gensym*::
* *print-level*::
* *print-lines*::
* *print-miser-width*::
* *print-pprint-dispatch*::
* *print-pretty*::
* *print-readably*::
* *print-right-margin*::
* print-not-readable::
* print-not-readable-object::
* format::

Reader

* Reader Concepts::
* Reader Dictionary::

Reader Concepts

* Dynamic Control of the Lisp Reader::
* Effect of Readtable Case on the Lisp Reader::
* Argument Conventions of Some Reader Functions::

Effect of Readtable Case on the Lisp Reader

* Examples of Effect of Readtable Case on the Lisp Reader::

Argument Conventions of Some Reader Functions

* The EOF-ERROR-P argument::
* The RECURSIVE-P argument::

Reader Dictionary

* readtable::
* copy-readtable::
* make-dispatch-macro-character::
* read::
* read-delimited-list::
* read-from-string::
* readtable-case::
* readtablep::
* set-dispatch-macro-character::
* set-macro-character::
* set-syntax-from-char::
* with-standard-io-syntax::
* *read-base*::
* *read-default-float-format*::
* *read-eval*::
* *read-suppress*::
* *readtable*::
* reader-error::

System Construction

* System Construction Concepts::
* System Construction Dictionary::

System Construction Concepts

* Loading::
* Features::

Features

* Feature Expressions::
* Examples of Feature Expressions::

System Construction Dictionary

* compile-file::
* compile-file-pathname::
* load::
* with-compilation-unit::
* *features*::
* *compile-file-pathname*::
* *load-pathname*::
* *compile-print*::
* *load-print*::
* *modules*::
* provide::

Environment

* The External Environment::
* Environment Dictionary::

The External Environment

* Top level loop::
* Debugging Utilities::
* Environment Inquiry::
* Time::

Time

* Decoded Time::
* Universal Time::
* Internal Time::
* Seconds::

Environment Dictionary

* decode-universal-time::
* encode-universal-time::
* get-universal-time::
* sleep::
* apropos::
* describe::
* describe-object::
* trace::
* step::
* time::
* internal-time-units-per-second::
* get-internal-real-time::
* get-internal-run-time::
* disassemble::
* documentation::
* room::
* ed::
* inspect::
* dribble::
* -::
* +::
* *::
* /::
* lisp-implementation-type::
* short-site-name::
* machine-instance::
* machine-type::
* machine-version::
* software-type::
* user-homedir-pathname::

Glossary

* Glossary::

Appendix

* Removed Language Features::

Removed Language Features

* Requirements for removed and deprecated features::
* Removed Types::
* Removed Operators::
* Removed Argument Conventions::
* Removed Variables::
* Removed Reader Syntax::
* Packages No Longer Required::


File: gcl.info,  Node: Introduction (Introduction),  Next: Syntax,  Prev: Top,  Up: Top

1 Introduction
**************

* Menu:

* Scope::
* Organization of the Document::
* Referenced Publications::
* Definitions::
* Conformance::
* Language Extensions::
* Language Subsets::
* Deprecated Language Features::
* Symbols in the COMMON-LISP Package::


File: gcl.info,  Node: Scope,  Next: Organization of the Document,  Prev: Introduction (Introduction),  Up: Introduction (Introduction)

1.1 Scope, Purpose, and History
===============================

* Menu:

* Scope and Purpose::
* History::


File: gcl.info,  Node: Scope and Purpose,  Next: History,  Prev: Scope,  Up: Scope

1.1.1 Scope and Purpose
-----------------------

The specification set forth in this document is designed to promote the
portability of Common Lisp programs among a variety of data processing
systems.  It is a language specification aimed at an audience of
implementors and knowledgeable programmers.  It is neither a tutorial
nor an implementation guide.


File: gcl.info,  Node: History,  Prev: Scope and Purpose,  Up: Scope

1.1.2 History
-------------

Lisp is a family of languages with a long history.  Early key ideas in
Lisp were developed by John McCarthy during the 1956 Dartmouth Summer
Research Project on Artificial Intelligence.  McCarthy's motivation was
to develop an algebraic list processing language for artificial
intelligence work.  Implementation efforts for early dialects of Lisp
were undertaken on the IBM~704, the IBM~7090, the Digital Equipment
Corporation (DEC) PDP-1, the DEC~PDP-6, and the PDP-10.  The primary
dialect of Lisp between 1960 and 1965 was Lisp~1.5.  By the early 1970's
there were two predominant dialects of Lisp, both arising from these
early efforts: MacLisp and Interlisp.  For further information about
very early Lisp dialects, see The Anatomy of Lisp or Lisp 1.5
Programmer's Manual.

   MacLisp improved on the Lisp~1.5 notion of special variables and
error handling.  MacLisp also introduced the concept of functions that
could take a variable number of arguments, macros, arrays, non-local
dynamic exits, fast arithmetic, the first good Lisp compiler, and an
emphasis on execution speed.  By the end of the 1970's, MacLisp was in
use at over 50 sites.  For further information about Maclisp, see
Maclisp Reference Manual, Revision~0 or The Revised Maclisp Manual.

   Interlisp introduced many ideas into Lisp programming environments
and methodology.  One of the Interlisp ideas that influenced Common Lisp
was an iteration construct implemented by Warren Teitelman that inspired
the loop macro used both on the Lisp Machines and in MacLisp, and now in
Common Lisp.  For further information about Interlisp, see Interlisp
Reference Manual.

   Although the first implementations of Lisp were on the IBM~704 and
the IBM~7090, later work focussed on the DEC PDP-6 and, later, PDP-10
computers, the latter being the mainstay of Lisp and artificial
intelligence work at such places as Massachusetts Institute of
Technology (MIT), Stanford University, and Carnegie Mellon University
(CMU) from the mid-1960's through much of the 1970's.  The PDP-10
computer and its predecessor the PDP-6 computer were, by design,
especially well-suited to Lisp because they had 36-bit words and 18-bit
addresses.  This architecture allowed a cons cell to be stored in one
word; single instructions could extract the car and cdr parts.  The
PDP-6 and PDP-10 had fast, powerful stack instructions that enabled fast
function calling.  But the limitations of the PDP-10 were evident by
1973: it supported a small number of researchers using Lisp, and the
small, 18-bit address space (2^18 = 262,144 words) limited the size of a
single program.  One response to the address space problem was the Lisp
Machine, a special-purpose computer designed to run Lisp programs.  The
other response was to use general-purpose computers with address spaces
larger than 18~bits, such as the DEC VAX and the S-1~Mark~IIA. For
further information about S-1 Common Lisp, see S-1 Common Lisp
Implementation.

   The Lisp machine concept was developed in the late 1960's.  In the
early 1970's, Peter Deutsch, working with Daniel Bobrow, implemented a
Lisp on the Alto, a single-user minicomputer, using microcode to
interpret a byte-code implementation language.  Shortly thereafter,
Richard Greenblatt began work on a different hardware and instruction
set design at MIT. Although the Alto was not a total success as a Lisp
machine, a dialect of Interlisp known as Interlisp-D became available on
the D-series machines manufactured by Xerox--the Dorado, Dandelion,
Dandetiger, and Dove (or Daybreak).  An upward-compatible extension of
MacLisp called Lisp Machine Lisp became available on the early MIT Lisp
Machines.  Commercial Lisp machines from Xerox, Lisp Machines (LMI), and
Symbolics were on the market by 1981.  For further information about
Lisp Machine Lisp, see Lisp Machine Manual.

   During the late 1970's, Lisp Machine Lisp began to expand towards a
much fuller language.  Sophisticated lambda lists, setf, multiple
values, and structures like those in Common Lisp are the results of
early experimentation with programming styles by the Lisp Machine group.
Jonl White and others migrated these features to MacLisp.  Around 1980,
Scott Fahlman and others at CMU began work on a Lisp to run on the
Scientific Personal Integrated Computing Environment (SPICE)
workstation.  One of the goals of the project was to design a simpler
dialect than Lisp Machine Lisp.

   The Macsyma group at MIT began a project during the late 1970's
called the New Implementation of Lisp (NIL) for the VAX, which was
headed by White.  One of the stated goals of the NIL project was to fix
many of the historic, but annoying, problems with Lisp while retaining
significant compatibility with MacLisp.  At about the same time, a
research group at Stanford University and Lawrence Livermore National
Laboratory headed by Richard P. Gabriel began the design of a Lisp to
run on the S-1~Mark~IIA supercomputer.  S-1~Lisp, never completely
functional, was the test bed for adapting advanced compiler techniques
to Lisp implementation.  Eventually the S-1 and NIL groups collaborated.
For further information about the NIL project, see NIL--A Perspective.

   The first effort towards Lisp standardization was made in 1969, when
Anthony Hearn and Martin Griss at the University of Utah defined
Standard Lisp--a subset of Lisp~1.5 and other dialects--to transport
REDUCE, a symbolic algebra system.  During the 1970's, the Utah group
implemented first a retargetable optimizing compiler for Standard Lisp,
and then an extended implementation known as Portable Standard Lisp
(PSL). By the mid 1980's, PSL ran on about a dozen kinds of computers.
For further information about Standard Lisp, see Standard LISP Report.

   PSL and Franz Lisp--a MacLisp-like dialect for Unix machines--were
the first examples of widely available Lisp dialects on multiple
hardware platforms.

   One of the most important developments in Lisp occurred during the
second half of the 1970's: Scheme.  Scheme, designed by Gerald J.
Sussman and Guy L. Steele Jr., is a simple dialect of Lisp whose design
brought to Lisp some of the ideas from programming language semantics
developed in the 1960's.  Sussman was one of the prime innovators behind
many other advances in Lisp technology from the late 1960's through the
1970's.  The major contributions of Scheme were lexical scoping, lexical
closures, first-class continuations, and simplified syntax (no
separation of value cells and function cells).  Some of these
contributions made a large impact on the design of Common Lisp.  For
further information about Scheme, see IEEE Standard for the Scheme
Programming Language or Revised^3 Report on the Algorithmic Language
Scheme.

   In the late 1970's object-oriented programming concepts started to
make a strong impact on Lisp.  At MIT, certain ideas from Smalltalk made
their way into several widely used programming systems.  Flavors, an
object-oriented programming system with multiple inheritance, was
developed at MIT for the Lisp machine community by Howard Cannon and
others.  At Xerox, the experience with Smalltalk and Knowledge
Representation Language (KRL) led to the development of Lisp Object
Oriented Programming System (LOOPS) and later Common LOOPS. For further
information on Smalltalk, see Smalltalk-80: The Language and its
Implementation.  For further information on Flavors, see Flavors: A
Non-Hierarchical Approach to Object-Oriented Programming.

   These systems influenced the design of the Common Lisp Object System
(CLOS). CLOS was developed specifically for this standardization effort,
and was separately written up in Common Lisp Object System
Specification.  However, minor details of its design have changed
slightly since that publication, and that paper should not be taken as
an authoritative reference to the semantics of the object system as
described in this document.

   In 1980 Symbolics and LMI were developing Lisp Machine Lisp;
stock-hardware implementation groups were developing NIL, Franz Lisp,
and PSL; Xerox was developing Interlisp; and the SPICE project at CMU
was developing a MacLisp-like dialect of Lisp called SpiceLisp.

   In April 1981, after a DARPA-sponsored meeting concerning the
splintered Lisp community, Symbolics, the SPICE project, the NIL
project, and the S-1~Lisp project joined together to define Common Lisp.
Initially spearheaded by White and Gabriel, the driving force behind
this grassroots effort was provided by Fahlman, Daniel Weinreb, David
Moon, Steele, and Gabriel.  Common Lisp was designed as a description of
a family of languages.  The primary influences on Common Lisp were Lisp
Machine Lisp, MacLisp, NIL, S-1~Lisp, Spice Lisp, and Scheme.  Common
Lisp: The Language is a description of that design.  Its semantics were
intentionally underspecified in places where it was felt that a tight
specification would overly constrain Common Lisp research and use.

   In 1986 X3J13 was formed as a technical working group to produce a
draft for an ANSI Common Lisp standard.  Because of the acceptance of
Common Lisp, the goals of this group differed from those of the original
designers.  These new goals included stricter standardization for
portability, an object-oriented programming system, a condition system,
iteration facilities, and a way to handle large character sets.  To
accommodate those goals, a new language specification, this document,
was developed.


File: gcl.info,  Node: Organization of the Document,  Next: Referenced Publications,  Prev: Scope,  Up: Introduction (Introduction)

1.2 Organization of the Document
================================

This is a reference document, not a tutorial document.  Where possible
and convenient, the order of presentation has been chosen so that the
more primitive topics precede those that build upon them; however,
linear readability has not been a priority.

   This document is divided into chapters by topic.  Any given chapter
might contain conceptual material, dictionary entries, or both.

   Defined names within the dictionary portion of a chapter are grouped
in a way that brings related topics into physical proximity.  Many such
groupings were possible, and no deep significance should be inferred
from the particular grouping that was chosen.  To see defined names
grouped alphabetically, consult the index.  For a complete list of
defined names, see *note Symbols in the COMMON-LISP Package::.

   In order to compensate for the sometimes-unordered portions of this
document, a glossary has been provided; see *note Glossary::.  The
glossary provides connectivity by providing easy access to definitions
of terms, and in some cases by providing examples or cross references to
additional conceptual material.

   For information about notational conventions used in this document,
see *note Definitions::.

   For information about conformance, see *note Conformance::.

   For information about extensions and subsets, see *note Language
Extensions:: and *note Language Subsets::.

   For information about how programs in the language are parsed by the
Lisp reader, see *note Syntax::.

   For information about how programs in the language are compiled and
executed, see *note Evaluation and Compilation::.

   For information about data types, see *note Types and Classes::.  Not
all types and classes are defined in this chapter; many are defined in
chapter corresponding to their topic-for example, the numeric types are
defined in *note Numbers (Numbers)::.  For a complete list of
standardized types, see Figure~4-2.

   For information about general purpose control and data flow, see
*note Data and Control Flow:: or *note Iteration::.


File: gcl.info,  Node: Referenced Publications,  Next: Definitions,  Prev: Organization of the Document,  Up: Introduction (Introduction)

1.3 Referenced Publications
===========================

*
     The Anatomy of Lisp, John Allen, McGraw-Hill, Inc., 1978.

*
     The Art of Computer Programming, Volume 3, Donald E. Knuth,
     Addison-Wesley Company (Reading, MA), 1973.

*
     The Art of the Metaobject Protocol, Kiczales et al., MIT Press
     (Cambridge, MA), 1991.

*
     Common Lisp Object System Specification, D. Bobrow, L. DiMichiel,
     R.P. Gabriel, S. Keene, G. Kiczales, D. Moon, SIGPLAN Notices V23,
     September, 1988.

*
     Common Lisp: The Language, Guy L. Steele Jr., Digital Press
     (Burlington, MA), 1984.

*
     Common Lisp: The Language, Second Edition, Guy L. Steele Jr.,
     Digital Press (Bedford, MA), 1990.

*
     Exceptional Situations in Lisp, Kent M. Pitman, Proceedings of the
     First European Conference on the Practical Application of LISP\/
     (EUROPAL '90), Churchill College, Cambridge, England, March 27-29,
     1990.

*
     Flavors: A Non-Hierarchical Approach to Object-Oriented
     Programming, Howard I. Cannon, 1982.

*
     IEEE Standard for Binary Floating-Point Arithmetic, ANSI/IEEE Std
     754-1985, Institute of Electrical and Electronics Engineers, Inc.
     (New York), 1985.

*
     IEEE Standard for the Scheme Programming Language, IEEE Std
     1178-1990, Institute of Electrical and Electronic Engineers, Inc.
     (New York), 1991.

*
     Interlisp Reference Manual, Third Revision, Teitelman, Warren, et
     al, Xerox Palo Alto Research Center (Palo Alto, CA), 1978.

*
     ISO 6937/2, Information processing--Coded character sets for text
     communication--Part 2: Latin alphabetic and non-alphabetic graphic
     characters, ISO, 1983.

*
     Lisp 1.5 Programmer's Manual, John McCarthy, MIT Press (Cambridge,
     MA), August, 1962.

*
     Lisp Machine Manual, D.L. Weinreb and D.A. Moon, Artificial
     Intelligence Laboratory, MIT (Cambridge, MA), July, 1981.

*
     Maclisp Reference Manual, Revision~0, David A. Moon, Project MAC
     (Laboratory for Computer Science), MIT (Cambridge, MA), March,
     1974.

*
     NIL--A Perspective, JonL White, Macsyma User's Conference, 1979.

*
     Performance and Evaluation of Lisp Programs, Richard P. Gabriel,
     MIT Press (Cambridge, MA), 1985.

*
     Principal Values and Branch Cuts in Complex APL, Paul Penfield Jr.,
     APL 81 Conference Proceedings, ACM SIGAPL (San Francisco, September
     1981), 248-256.  Proceedings published as APL Quote Quad 12, 1
     (September 1981).

*
     The Revised Maclisp Manual, Kent M. Pitman, Technical Report 295,
     Laboratory for Computer Science, MIT (Cambridge, MA), May 1983.

*
     Revised^3 Report on the Algorithmic Language Scheme, Jonathan Rees
     and William Clinger (editors), SIGPLAN Notices V21, #12, December,
     1986.

*
     S-1 Common Lisp Implementation, R.A. Brooks, R.P. Gabriel, and G.L.
     Steele, Conference Record of the 1982 ACM Symposium on Lisp and
     Functional Programming, 108-113, 1982.

*
     Smalltalk-80: The Language and its Implementation, A. Goldberg and
     D. Robson, Addison-Wesley, 1983.

*
     Standard LISP Report, J.B. Marti, A.C. Hearn, M.L. Griss, and C.
     Griss, SIGPLAN Notices V14, #10, October, 1979.

*
     Webster's Third New International Dictionary the English Language,
     Unabridged, Merriam Webster (Springfield, MA), 1986.

*
     XP: A Common Lisp Pretty Printing System, R.C. Waters, Memo 1102a,
     Artificial Intelligence Laboratory, MIT (Cambridge, MA), September
     1989.


File: gcl.info,  Node: Definitions,  Next: Conformance,  Prev: Referenced Publications,  Up: Introduction (Introduction)

1.4 Definitions
===============

This section contains notational conventions and definitions of terms
used in this manual.

* Menu:

* Notational Conventions::
* Error Terminology::
* Sections Not Formally Part Of This Standard::
* Interpreting Dictionary Entries::


File: gcl.info,  Node: Notational Conventions,  Next: Error Terminology,  Prev: Definitions,  Up: Definitions

1.4.1 Notational Conventions
----------------------------

The following notational conventions are used throughout this document.

* Menu:

* Font Key::
* Modified BNF Syntax::
* Splicing in Modified BNF Syntax::
* Indirection in Modified BNF Syntax::
* Additional Uses for Indirect Definitions in Modified BNF Syntax::
* Special Symbols::
* Objects with Multiple Notations::
* Case in Symbols::
* Numbers (Objects with Multiple Notations)::
* Use of the Dot Character::
* NIL::
* Designators::
* Nonsense Words::


File: gcl.info,  Node: Font Key,  Next: Modified BNF Syntax,  Prev: Notational Conventions,  Up: Notational Conventions

1.4.1.1 Font Key
................

Fonts are used in this document to convey information.

name
     Denotes a formal term whose meaning is defined in the Glossary.
     When this font is used, the Glossary definition takes precedence
     over normal English usage.

     Sometimes a glossary term appears subscripted, as in
     "whitespace_2."  Such a notation selects one particular Glossary
     definition out of several, in this case the second.  The subscript
     notation for Glossary terms is generally used where the context
     might be insufficient to disambiguate among the available
     definitions.

name

     Denotes the introduction of a formal term locally to the current
     text.  There is still a corresponding glossary entry, and is
     formally equivalent to a use of "name," but the hope is that making
     such uses conspicuous will save the reader a trip to the glossary
     in some cases.

name
     Denotes a symbol in the COMMON-LISP package.  For information about
     case conventions, see *note Case in Symbols::.

name
     Denotes a sample name or piece of code that a programmer might
     write in Common Lisp.

     This font is also used for certain standardized names that are not
     names of external symbols of the COMMON-LISP package, such as
     keywords_1, package names, and loop keywords.

name
     Denotes the name of a parameter or value.

     In some situations the notation "<<name>>" (i.e., the same font,
     but with surrounding "angle brackets") is used instead in order to
     provide better visual separation from surrounding characters.
     These "angle brackets" are metasyntactic, and never actually appear
     in program input or output.


File: gcl.info,  Node: Modified BNF Syntax,  Next: Splicing in Modified BNF Syntax,  Prev: Font Key,  Up: Notational Conventions

1.4.1.2 Modified BNF Syntax
...........................

This specification uses an extended Backus Normal Form (BNF) to describe
the syntax of Common Lisp macro forms and special forms.  This section
discusses the syntax of BNF expressions.


File: gcl.info,  Node: Splicing in Modified BNF Syntax,  Next: Indirection in Modified BNF Syntax,  Prev: Modified BNF Syntax,  Up: Notational Conventions

1.4.1.3 Splicing in Modified BNF Syntax
.......................................

The primary extension used is the following:

                                 [[O]]

   An expression of this form appears whenever a list of elements is to
be spliced into a larger structure and the elements can appear in any
order.  The symbol O represents a description of the syntax of some
number of syntactic elements to be spliced; that description must be of
the form

                            O_1 | ... | O_l

where each O_i can be of the form S or of the form S* or of the form
S^1.

   The expression [[O]] means that a list of the form

                      (O_{i_1}... O_{i_j}) 1<= j

is spliced into the enclosing expression, such that if n != m and 1<=
n,m<= j, then either O_{i_n}!= O_{i_m} or O_{i_n} = O_{i_m} = Q_k, where
for some 1<= k <= n, O_k is of the form Q_k*.

   Furthermore, for each O_{i_n} that is of the form Q_k^1, that element
is required to appear somewhere in the list to be spliced.

   For example, the expression

   (x [[A | B* | C]] y)

means that at most one A, any number of B's, and at most one C can occur
in any order.  It is a description of any of these:

      (x y)
      (x B A C y)
      (x A B B B B B C y)
      (x C B A B B B y)

but not any of these:

      (x B B A A C C y)
      (x C B C y)

In the first case, both A and C appear too often, and in the second case
C appears too often.

   The notation [[O_1 | O_2 | ...]]^+ adds the additional restriction
that at least one item from among the possible choices must be used.
For example:

   (x [[A | B* | C]]^+ y)

means that at most one A, any number of B's, and at most one C can occur
in any order, but that in any case at least one of these options must be
selected.  It is a description of any of these:

      (x B y)
      (x B A C y)
      (x A B B B B B C y)
      (x C B A B B B y)

but not any of these:

      (x y)
      (x B B A A C C y)
      (x C B C y)

In the first case, no item was used; in the second case, both A and C
appear too often; and in the third case C appears too often.

   Also, the expression:

   (x [[A^1 | B^1 | C]] y)

can generate exactly these and no others:

      (x A B C y)
      (x A C B y)
      (x A B y)
      (x B A C y)
      (x B C A y)
      (x B A y)
      (x C A B y)
      (x C B A y)


File: gcl.info,  Node: Indirection in Modified BNF Syntax,  Next: Additional Uses for Indirect Definitions in Modified BNF Syntax,  Prev: Splicing in Modified BNF Syntax,  Up: Notational Conventions

1.4.1.4 Indirection in Modified BNF Syntax
..........................................

An indirection extension is introduced in order to make this new syntax
more readable:

                                  !O

If O is a non-terminal symbol, the right-hand side of its definition is
substituted for the entire expression !O. For example, the following BNF
is equivalent to the BNF in the previous example:

   (x [[!O]] y)

   O ::=A | B* | C


File: gcl.info,  Node: Additional Uses for Indirect Definitions in Modified BNF Syntax,  Next: Special Symbols,  Prev: Indirection in Modified BNF Syntax,  Up: Notational Conventions

1.4.1.5 Additional Uses for Indirect Definitions in Modified BNF Syntax
.......................................................................

In some cases, an auxiliary definition in the BNF might appear to be
unused within the BNF, but might still be useful elsewhere.  For
example, consider the following definitions:

   'case' keyform {!normal-clause}* [!otherwise-clause] => {result}*

   'ccase' keyplace {!normal-clause}* => {result}*

   'ecase' keyform {!normal-clause}* => {result}*

   normal-clause ::=(keys {form}*)

   otherwise-clause ::=({otherwise | t} {form}*)

   clause ::=normal-clause | otherwise-clause

   Here the term "clause" might appear to be "dead" in that it is not
used in the BNF. However, the purpose of the BNF is not just to guide
parsing, but also to define useful terms for reference in the
descriptive text which follows.  As such, the term "clause" might appear
in text that follows, as shorthand for "normal-clause or
otherwise-clause."


File: gcl.info,  Node: Special Symbols,  Next: Objects with Multiple Notations,  Prev: Additional Uses for Indirect Definitions in Modified BNF Syntax,  Up: Notational Conventions

1.4.1.6 Special Symbols
.......................

The special symbols described here are used as a notational convenience
within this document, and are part of neither the Common Lisp language
nor its environment.

=>
     This indicates evaluation.  For example:

           (+ 4 5) =>  9

     This means that the result of evaluating the form (+ 4 5) is 9.

     If a form returns multiple values, those values might be shown
     separated by spaces, line breaks, or commas.  For example:

           (truncate 7 5)
          =>  1 2
           (truncate 7 5)
          =>  1
             2
           (truncate 7 5)
          =>  1, 2

     Each of the above three examples is equivalent, and specifies that
     (truncate 7 5) returns two values, which are 1 and 2.

     Some conforming implementations actually type an arrow (or some
     other indicator) before showing return values, while others do not.

OR=>
     The notation "OR=>" is used to denote one of several possible
     alternate results.  The example

           (char-name #\a)
          =>  NIL
          OR=> "LOWERCASE-a"
          OR=> "Small-A"
          OR=> "LA01"

     indicates that nil, "LOWERCASE-a", "Small-A", "LA01" are among the
     possible results of (char-name #\a)--each with equal preference.
     Unless explicitly specified otherwise, it should not be assumed
     that the set of possible results shown is exhaustive.  Formally,
     the above example is equivalent to

           (char-name #\a) =>  implementation-dependent

     but it is intended to provide additional information to illustrate
     some of the ways in which it is permitted for implementations to
     diverge.

NOT=>
     The notation "NOT=>" is used to denote a result which is not
     possible.  This might be used, for example, in order to emphasize a
     situation where some anticipated misconception might lead the
     reader to falsely believe that the result might be possible.  For
     example,

           (function-lambda-expression
              (funcall #'(lambda (x) #'(lambda () x)) nil))
          =>  NIL, true, NIL
          OR=> (LAMBDA () X), true, NIL
          NOT=> NIL, false, NIL
          NOT=> (LAMBDA () X), false, NIL

==
     This indicates code equivalence.  For example:

           (gcd x (gcd y z)) == (gcd (gcd x y) z)

     This means that the results and observable side-effects of
     evaluating the form (gcd x (gcd y z)) are always the same as the
     results and observable side-effects of (gcd (gcd x y) z) for any x,
     y, and z.

|> 
     Common Lisp specifies input and output with respect to a
     non-interactive stream model.  The specific details of how
     interactive input and output are mapped onto that non-interactive
     model are implementation-defined.

     For example, conforming implementations are permitted to differ in
     issues of how interactive input is terminated.  For example, the
     function read terminates when the final delimiter is typed on a
     non-interactive stream.  In some implementations, an interactive
     call to read returns as soon as the final delimiter is typed, even
     if that delimiter is not a newline.  In other implementations, a
     final newline is always required.  In still other implementations,
     there might be a command which "activates" a buffer full of input
     without the command itself being visible on the program's input
     stream.

     In the examples in this document, the notation " |> " precedes
     lines where interactive input and output occurs.  Within such a
     scenario, "|>>this notation<<|" notates user input.

     For example, the notation

           (+ 1 (print (+ (sqrt (read)) (sqrt (read)))))
           |>  |>>9 16 <<|
           |>  7
          =>  8

     shows an interaction in which "(+ 1 (print (+ (sqrt (read)) (sqrt
     (read)))))" is a form to be evaluated, "9 16 " is interactive
     input, "7" is interactive output, and "8" is the value yielded from
     the evaluation.

     The use of this notation is intended to disguise small differences
     in interactive input and output behavior between implementations.

     Sometimes, the non-interactive stream model calls for a newline.
     How that newline character is interactively entered is an
     implementation-defined detail of the user interface, but in that
     case, either the notation "<Newline>" or "[<-~]" might be used.

           (progn (format t "~&Who? ") (read-line))
           |>  Who? |>>Fred, Mary, and Sally [<-~]<<|
          =>  "Fred, Mary, and Sally", false


File: gcl.info,  Node: Objects with Multiple Notations,  Next: Case in Symbols,  Prev: Special Symbols,  Up: Notational Conventions

1.4.1.7 Objects with Multiple Notations
.......................................

Some objects in Common Lisp can be notated in more than one way.  In
such situations, the choice of which notation to use is technically
arbitrary, but conventions may exist which convey a "point of view" or
"sense of intent."


File: gcl.info,  Node: Case in Symbols,  Next: Numbers (Objects with Multiple Notations),  Prev: Objects with Multiple Notations,  Up: Notational Conventions

1.4.1.8 Case in Symbols
.......................

While case is significant in the process of interning a symbol, the Lisp
reader, by default, attempts to canonicalize the case of a symbol prior
to interning; see *note Effect of Readtable Case on the Lisp Reader::.
As such, case in symbols is not, by default, significant.  Throughout
this document, except as explicitly noted otherwise, the case in which a
symbol appears is not significant; that is, HELLO, Hello, hElLo, and
hello are all equivalent ways to denote a symbol whose name is "HELLO".

   The characters backslash and vertical-bar are used to explicitly
quote the case and other parsing-related aspects of characters.  As
such, the notations |hello| and \h\e\l\l\o are equivalent ways to refer
to a symbol whose name is "hello", and which is distinct from any symbol
whose name is "HELLO".

   The symbols that correspond to Common Lisp defined names have
uppercase names even though their names generally appear in lowercase in
this document.


File: gcl.info,  Node: Numbers (Objects with Multiple Notations),  Next: Use of the Dot Character,  Prev: Case in Symbols,  Up: Notational Conventions

1.4.1.9 Numbers
...............

Although Common Lisp provides a variety of ways for programs to
manipulate the input and output radix for rational numbers, all numbers
in this document are in decimal notation unless explicitly noted
otherwise.


File: gcl.info,  Node: Use of the Dot Character,  Next: NIL,  Prev: Numbers (Objects with Multiple Notations),  Up: Notational Conventions

1.4.1.10 Use of the Dot Character
.................................

The dot appearing by itself in an expression such as

   (item1 item2 . tail)

   means that tail represents a list of objects at the end of a list.
For example,

   (A B C . (D E F))

   is notationally equivalent to:

   (A B C D E F)

   Although dot is a valid constituent character in a symbol, no
standardized symbols contain the character dot, so a period that follows
a reference to a symbol at the end of a sentence in this document should
always be interpreted as a period and never as part of the symbol's
name.  For example, within this document, a sentence such as "This
sample sentence refers to the symbol car."  refers to a symbol whose
name is "CAR" (with three letters), and never to a four-letter symbol
"CAR."


File: gcl.info,  Node: NIL,  Next: Designators,  Prev: Use of the Dot Character,  Up: Notational Conventions

1.4.1.11 NIL
............

nil has a variety of meanings.  It is a symbol in the COMMON-LISP
package with the name "NIL", it is boolean (and generalized boolean)
false, it is the empty list, and it is the name of the empty type (a
subtype of all types).

   Within Common Lisp, nil can be notated interchangeably as either NIL
or ().  By convention, the choice of notation offers a hint as to which
of its many roles it is playing.

  For Evaluation?  Notation  Typically Implied Role       
  ________________________________________________________
  Yes              nil       use as a boolean.            
  Yes              'nil      use as a symbol.             
  Yes              '()       use as an empty list         
  No               nil       use as a symbol or boolean.  
  No               ()        use as an empty list.        

               Figure 1-1: Notations for NIL             


   Within this document only, nil is also sometimes notated as false to
emphasize its role as a boolean.

   For example:

      (print ())                          ;avoided
      (defun three nil 3)                 ;avoided
      '(nil nil)                          ;list of two symbols
      '(() ())                            ;list of empty lists
      (defun three () 3)                  ;Emphasize empty parameter list.
      (append '() '()) =>  ()              ;Emphasize use of empty lists
      (not nil) =>  true                   ;Emphasize use as Boolean false
      (get 'nil 'color)                   ;Emphasize use as a symbol

   A function is sometimes said to "be false" or "be true" in some
circumstance.  Since no function object can be the same as nil and all
function objects represent true when viewed as booleans, it would be
meaningless to say that the function was literally false and
uninteresting to say that it was literally true.  Instead, these phrases
are just traditional alternative ways of saying that the function
"returns false" or "returns true," respectively.


File: gcl.info,  Node: Designators,  Next: Nonsense Words,  Prev: NIL,  Up: Notational Conventions

1.4.1.12 Designators
....................

A designator is an object that denotes another object.

   Where a parameter of an operator is described as a designator, the
description of the operator is written in a way that assumes that the
value of the parameter is the denoted object; that is, that the
parameter is already of the denoted type.  (The specific nature of the
object denoted by a "<<type>> designator" or a "designator for a
<<type>>" can be found in the Glossary entry for "<<type>> designator.")

   For example, "nil" and "the value of *standard-output*" are
operationally indistinguishable as stream designators.  Similarly, the
symbol foo and the string "FOO" are operationally indistinguishable as
string designators.

   Except as otherwise noted, in a situation where the denoted object
might be used multiple times, it is implementation-dependent whether the
object is coerced only once or whether the coercion occurs each time the
object must be used.

   For example, mapcar receives a function designator as an argument,
and its description is written as if this were simply a function.  In
fact, it is implementation-dependent whether the function designator is
coerced right away or whether it is carried around internally in the
form that it was given as an argument and re-coerced each time it is
needed.  In most cases, conforming programs cannot detect the
distinction, but there are some pathological situations (particularly
those involving self-redefining or mutually-redefining functions) which
do conform and which can detect this difference.  The following program
is a conforming program, but might or might not have portably correct
results, depending on whether its correctness depends on one or the
other of the results:

      (defun add-some (x)
        (defun add-some (x) (+ x 2))
        (+ x 1)) =>  ADD-SOME
      (mapcar 'add-some '(1 2 3 4))
     =>  (2 3 4 5)
     OR=> (2 4 5 6)

   In a few rare situations, there may be a need in a dictionary entry
to refer to the object that was the original designator for a parameter.
Since naming the parameter would refer to the denoted object, the phrase
"the <<parameter-name>> designator" can be used to refer to the
designator which was the argument from which the value of
<<parameter-name>> was computed.


File: gcl.info,  Node: Nonsense Words,  Prev: Designators,  Up: Notational Conventions

1.4.1.13 Nonsense Words
.......................

When a word having no pre-attached semantics is required (e.g., in an
example), it is common in the Lisp community to use one of the words
"foo," "bar," "baz," and "quux."  For example, in

      (defun foo (x) (+ x 1))

   the use of the name foo is just a shorthand way of saying "please
substitute your favorite name here."

   These nonsense words have gained such prevalance of usage, that it is
commonplace for newcomers to the community to begin to wonder if there
is an attached semantics which they are overlooking--there is not.


File: gcl.info,  Node: Error Terminology,  Next: Sections Not Formally Part Of This Standard,  Prev: Notational Conventions,  Up: Definitions

1.4.2 Error Terminology
-----------------------

Situations in which errors might, should, or must be signaled are
described in the standard.  The wording used to describe such situations
is intended to have precise meaning.  The following list is a glossary
of those meanings.

Safe code

     This is code processed with the safety optimization at its highest
     setting (3).  safety is a lexical property of code.  The phrase
     "the function F should signal an error" means that if F is invoked
     from code processed with the highest safety optimization, an error
     is signaled.  It is implementation-dependent whether F or the
     calling code signals the error.

Unsafe code

     This is code processed with lower safety levels.

     Unsafe code might do error checking.  Implementations are permitted
     to treat all code as safe code all the time.

An error is signaled

     This means that an error is signaled in both safe and unsafe code.
     Conforming code may rely on the fact that the error is signaled in
     both safe and unsafe code.  Every implementation is required to
     detect the error in both safe and unsafe code.  For example, "an
     error is signaled if unexport is given a symbol not accessible in
     the current package."

     If an explicit error type is not specified, the default is error.

An error should be signaled

     This means that an error is signaled in safe code, and an error
     might be signaled in unsafe code.  Conforming code may rely on the
     fact that the error is signaled in safe code.  Every implementation
     is required to detect the error at least in safe code.  When the
     error is not signaled, the "consequences are undefined" (see
     below).  For example, "+ should signal an error of type type-error
     if any argument is not of type number."

Should be prepared to signal an error

     This is similar to "should be signaled" except that it does not
     imply that 'extra effort' has to be taken on the part of an
     operator to discover an erroneous situation if the normal action of
     that operator can be performed successfully with only 'lazy'
     checking.  An implementation is always permitted to signal an
     error, but even in safe code, it is only required to signal the
     error when failing to signal it might lead to incorrect results.
     In unsafe code, the consequences are undefined.

     For example, defining that "find should be prepared to signal an
     error of type type-error if its second argument is not a proper
     list" does not imply that an error is always signaled.  The form

           (find 'a '(a b . c))

     must either signal an error of type type-error in safe code, else
     return A.  In unsafe code, the consequences are undefined.  By
     contrast,

           (find 'd '(a b . c))

     must signal an error of type type-error in safe code.  In unsafe
     code, the consequences are undefined.  Also,

           (find 'd '#1=(a b . #1#))

     in safe code might return nil (as an implementation-defined
     extension), might never return, or might signal an error of type
     type-error.  In unsafe code, the consequences are undefined.

     Typically, the "should be prepared to signal" terminology is used
     in type checking situations where there are efficiency
     considerations that make it impractical to detect errors that are
     not relevant to the correct operation of the operator.

The consequences are unspecified

     This means that the consequences are unpredictable but harmless.
     Implementations are permitted to specify the consequences of this
     situation.  No conforming code may depend on the results or effects
     of this situation, and all conforming code is required to treat the
     results and effects of this situation as unpredictable but
     harmless.  For example, "if the second argument to
     shared-initialize specifies a name that does not correspond to any
     slots accessible in the object, the results are unspecified."

The consequences are undefined

     This means that the consequences are unpredictable.  The
     consequences may range from harmless to fatal.  No conforming code
     may depend on the results or effects.  Conforming code must treat
     the consequences as unpredictable.  In places where the words
     "must," "must not," or "may not" are used, then "the consequences
     are undefined" if the stated requirement is not met and no specific
     consequence is explicitly stated.  An implementation is permitted
     to signal an error in this case.

     For example: "Once a name has been declared by defconstant to be
     constant, any further assignment or binding of that variable has
     undefined consequences."

An error might be signaled

     This means that the situation has undefined consequences; however,
     if an error is signaled, it is of the specified type.  For example,
     "open might signal an error of type file-error."

The return values are unspecified

     This means that only the number and nature of the return values of
     a form are not specified.  However, the issue of whether or not any
     side-effects or transfer of control occurs is still well-specified.

     A program can be well-specified even if it uses a function whose
     returns values are unspecified.  For example, even if the return
     values of some function F are unspecified, an expression such as
     (length (list (F))) is still well-specified because it does not
     rely on any particular aspect of the value or values returned by F.

Implementations may be extended to cover this situation

     This means that the situation has undefined consequences; however,
     a conforming implementation is free to treat the situation in a
     more specific way.  For example, an implementation might define
     that an error is signaled, or that an error should be signaled, or
     even that a certain well-defined non-error behavior occurs.

     No conforming code may depend on the consequences of such a
     situation; all conforming code must treat the consequences of the
     situation as undefined.  Implementations are required to document
     how the situation is treated.

     For example, "implementations may be extended to define other type
     specifiers to have a corresponding class."

Implementations are free to extend the syntax

     This means that in this situation implementations are permitted to
     define unambiguous extensions to the syntax of the form being
     described.  No conforming code may depend on this extension.
     Implementations are required to document each such extension.  All
     conforming code is required to treat the syntax as meaningless.
     The standard might disallow certain extensions while allowing
     others.  For example, "no implementation is free to extend the
     syntax of defclass."

A warning might be issued

     This means that implementations are encouraged to issue a warning
     if the context is appropriate (e.g., when compiling).  However, a
     conforming implementation is not required to issue a warning.


File: gcl.info,  Node: Sections Not Formally Part Of This Standard,  Next: Interpreting Dictionary Entries,  Prev: Error Terminology,  Up: Definitions

1.4.3 Sections Not Formally Part Of This Standard
-------------------------------------------------

Front matter and back matter, such as the "Table of Contents," "Index,"
"Figures," "Credits," and "Appendix" are not considered formally part of
this standard, so that we retain the flexibility needed to update these
sections even at the last minute without fear of needing a formal vote
to change those parts of the document.  These items are quite short and
very useful, however, and it is not recommended that they be removed
even in an abridged version of this document.

   Within the concept sections, subsections whose names begin with the
words "Note" or "Notes" or "Example" or "Examples" are provided for
illustration purposes only, and are not considered part of the standard.

   An attempt has been made to place these sections last in their parent
section, so that they could be removed without disturbing the contiguous
numbering of the surrounding sections in order to produce a document of
smaller size.

   Likewise, the "Examples" and "Notes" sections in a dictionary entry
are not considered part of the standard and could be removed if
necessary.

   Nevertheless, the examples provide important clarifications and
consistency checks for the rest of the material, and such abridging is
not recommended unless absolutely unavoidable.


File: gcl.info,  Node: Interpreting Dictionary Entries,  Prev: Sections Not Formally Part Of This Standard,  Up: Definitions

1.4.4 Interpreting Dictionary Entries
-------------------------------------

The dictionary entry for each defined name is partitioned into sections.
Except as explicitly indicated otherwise below, each section is
introduced by a label identifying that section.  The omission of a
section implies that the section is either not applicable, or would
provide no interesting information.

   This section defines the significance of each potential section in a
dictionary entry.

* Menu:

* The "Affected By" Section of a Dictionary Entry::
* The "Arguments" Section of a Dictionary Entry::
* The "Arguments and Values" Section of a Dictionary Entry::
* The "Binding Types Affected" Section of a Dictionary Entry::
* The "Class Precedence List" Section of a Dictionary Entry::
* Dictionary Entries for Type Specifiers::
* The "Compound Type Specifier Kind" Section of a Dictionary Entry::
* The "Compound Type Specifier Syntax" Section of a Dictionary Entry::
* The "Compound Type Specifier Arguments" Section of a Dictionary Entry::
* The "Compound Type Specifier Description" Section of a Dictionary Entry::
* The "Constant Value" Section of a Dictionary Entry::
* The "Description" Section of a Dictionary Entry::
* The "Examples" Section of a Dictionary Entry::
* The "Exceptional Situations" Section of a Dictionary Entry::
* The "Initial Value" Section of a Dictionary Entry::
* The "Argument Precedence Order" Section of a Dictionary Entry::
* The "Method Signature" Section of a Dictionary Entry::
* The "Name" Section of a Dictionary Entry::
* The "Notes" Section of a Dictionary Entry::
* The "Pronunciation" Section of a Dictionary Entry::
* The "See Also" Section of a Dictionary Entry::
* The "Side Effects" Section of a Dictionary Entry::
* The "Supertypes" Section of a Dictionary Entry::
* The "Syntax" Section of a Dictionary Entry::
* Special "Syntax" Notations for Overloaded Operators::
* Naming Conventions for Rest Parameters::
* Requiring Non-Null Rest Parameters in The "Syntax" Section::
* Return values in The "Syntax" Section::
* No Arguments or Values in The "Syntax" Section::
* Unconditional Transfer of Control in The "Syntax" Section::
* The "Valid Context" Section of a Dictionary Entry::
* The "Value Type" Section of a Dictionary Entry::


File: gcl.info,  Node: The "Affected By" Section of a Dictionary Entry,  Next: The "Arguments" Section of a Dictionary Entry,  Prev: Interpreting Dictionary Entries,  Up: Interpreting Dictionary Entries

1.4.4.1 The "Affected By" Section of a Dictionary Entry
.......................................................

For an operator, anything that can affect the side effects of or values
returned by the operator.

   For a variable, anything that can affect the value of the variable
including functions that bind or assign it.


File: gcl.info,  Node: The "Arguments" Section of a Dictionary Entry,  Next: The "Arguments and Values" Section of a Dictionary Entry,  Prev: The "Affected By" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.2 The "Arguments" Section of a Dictionary Entry
.....................................................

This information describes the syntax information of entries such as
those for declarations and special expressions which are never evaluated
as forms, and so do not return values.


File: gcl.info,  Node: The "Arguments and Values" Section of a Dictionary Entry,  Next: The "Binding Types Affected" Section of a Dictionary Entry,  Prev: The "Arguments" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.3 The "Arguments and Values" Section of a Dictionary Entry
................................................................

An English language description of what arguments the operator accepts
and what values it returns, including information about defaults for
parameters corresponding to omittable arguments (such as optional
parameters and keyword parameters).  For special operators and macros,
their arguments are not evaluated unless it is explicitly stated in
their descriptions that they are evaluated.


File: gcl.info,  Node: The "Binding Types Affected" Section of a Dictionary Entry,  Next: The "Class Precedence List" Section of a Dictionary Entry,  Prev: The "Arguments and Values" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.4 The "Binding Types Affected" Section of a Dictionary Entry
..................................................................

This information alerts the reader to the kinds of bindings that might
potentially be affected by a declaration.  Whether in fact any
particular such binding is actually affected is dependent on additional
factors as well.  See The "Description" Section of the declaration in
question for details.


File: gcl.info,  Node: The "Class Precedence List" Section of a Dictionary Entry,  Next: Dictionary Entries for Type Specifiers,  Prev: The "Binding Types Affected" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.5 The "Class Precedence List" Section of a Dictionary Entry
.................................................................

This appears in the dictionary entry for a class, and contains an
ordered list of the classes defined by Common Lisp that must be in the
class precedence list of this class.

   It is permissible for other (implementation-defined) classes to
appear in the implementation's class precedence list for the class.

   It is permissible for either standard-object or structure-object to
appear in the implementation's class precedence list; for details, see
*note Type Relationships::.

   Except as explicitly indicated otherwise somewhere in this
specification, no additional standardized classes may appear in the
implementation's class precedence list.

   By definition of the relationship between classes and types, the
classes listed in this section are also supertypes of the type denoted
by the class.


File: gcl.info,  Node: Dictionary Entries for Type Specifiers,  Next: The "Compound Type Specifier Kind" Section of a Dictionary Entry,  Prev: The "Class Precedence List" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.6 Dictionary Entries for Type Specifiers
..............................................

The atomic type specifiers are those defined names listed in Figure~4-2.
Such dictionary entries are of kind "Class," "Condition Type," "System
Class," or "Type."  A description of how to interpret a symbol naming
one of these types or classes as an atomic type specifier is found in
The "Description" Section of such dictionary entries.

   The compound type specifiers are those defined names listed in
Figure~4-3.  Such dictionary entries are of kind "Class," "System
Class," "Type," or "Type Specifier."  A description of how to interpret
as a compound type specifier a list whose car is such a symbol is found
in the "Compound Type Specifier Kind," "Compound Type Specifier Syntax,"
"Compound Type Specifier Arguments," and "Compound Type Specifier
Description" sections of such dictionary entries.


File: gcl.info,  Node: The "Compound Type Specifier Kind" Section of a Dictionary Entry,  Next: The "Compound Type Specifier Syntax" Section of a Dictionary Entry,  Prev: Dictionary Entries for Type Specifiers,  Up: Interpreting Dictionary Entries

1.4.4.7 The "Compound Type Specifier Kind" Section of a Dictionary Entry
........................................................................

An "abbreviating" type specifier is one that describes a subtype for
which it is in principle possible to enumerate the elements, but for
which in practice it is impractical to do so.

   A "specializing" type specifier is one that describes a subtype by
restricting the type of one or more components of the type, such as
element type or complex part type.

   A "predicating" type specifier is one that describes a subtype
containing only those objects that satisfy a given predicate.

   A "combining" type specifier is one that describes a subtype in a
compositional way, using combining operations (such as "and," "or," and
"not") on other types.


File: gcl.info,  Node: The "Compound Type Specifier Syntax" Section of a Dictionary Entry,  Next: The "Compound Type Specifier Arguments" Section of a Dictionary Entry,  Prev: The "Compound Type Specifier Kind" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.8 The "Compound Type Specifier Syntax" Section of a Dictionary Entry
..........................................................................

This information about a type describes the syntax of a compound type
specifier for that type.

   Whether or not the type is acceptable as an atomic type specifier is
not represented here; see *note Dictionary Entries for Type
Specifiers::.


File: gcl.info,  Node: The "Compound Type Specifier Arguments" Section of a Dictionary Entry,  Next: The "Compound Type Specifier Description" Section of a Dictionary Entry,  Prev: The "Compound Type Specifier Syntax" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.9 The "Compound Type Specifier Arguments" Section of a Dictionary Entry
.............................................................................

This information describes type information for the structures defined
in The "Compound Type Specifier Syntax" Section.


File: gcl.info,  Node: The "Compound Type Specifier Description" Section of a Dictionary Entry,  Next: The "Constant Value" Section of a Dictionary Entry,  Prev: The "Compound Type Specifier Arguments" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.10 The "Compound Type Specifier Description" Section of a Dictionary Entry
................................................................................

This information describes the meaning of the structures defined in The
"Compound Type Specifier Syntax" Section.


File: gcl.info,  Node: The "Constant Value" Section of a Dictionary Entry,  Next: The "Description" Section of a Dictionary Entry,  Prev: The "Compound Type Specifier Description" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.11 The "Constant Value" Section of a Dictionary Entry
...........................................................

This information describes the unchanging type and value of a constant
variable.


File: gcl.info,  Node: The "Description" Section of a Dictionary Entry,  Next: The "Examples" Section of a Dictionary Entry,  Prev: The "Constant Value" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.12 The "Description" Section of a Dictionary Entry
........................................................

A summary of the operator and all intended aspects of the operator, but
does not necessarily include all the fields referenced below it ("Side
Effects," "Exceptional Situations," etc.)


File: gcl.info,  Node: The "Examples" Section of a Dictionary Entry,  Next: The "Exceptional Situations" Section of a Dictionary Entry,  Prev: The "Description" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.13 The "Examples" Section of a Dictionary Entry
.....................................................

Examples of use of the operator.  These examples are not considered part
of the standard; see *note Sections Not Formally Part Of This
Standard::.


File: gcl.info,  Node: The "Exceptional Situations" Section of a Dictionary Entry,  Next: The "Initial Value" Section of a Dictionary Entry,  Prev: The "Examples" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.14 The "Exceptional Situations" Section of a Dictionary Entry
...................................................................

Three kinds of information may appear here:

*
     Situations that are detected by the function and formally signaled.
*
     Situations that are handled by the function.
*
     Situations that may be detected by the function.

   This field does not include conditions that could be signaled by
functions passed to and called by this operator as arguments or through
dynamic variables, nor by executing subforms of this operator if it is a
macro or special operator.


File: gcl.info,  Node: The "Initial Value" Section of a Dictionary Entry,  Next: The "Argument Precedence Order" Section of a Dictionary Entry,  Prev: The "Exceptional Situations" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.15 The "Initial Value" Section of a Dictionary Entry
..........................................................

This information describes the initial value of a dynamic variable.
Since this variable might change, see type restrictions in The "Value
Type" Section.


File: gcl.info,  Node: The "Argument Precedence Order" Section of a Dictionary Entry,  Next: The "Method Signature" Section of a Dictionary Entry,  Prev: The "Initial Value" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.16 The "Argument Precedence Order" Section of a Dictionary Entry
......................................................................

This information describes the argument precedence order.  If it is
omitted, the argument precedence order is the default (left to right).


File: gcl.info,  Node: The "Method Signature" Section of a Dictionary Entry,  Next: The "Name" Section of a Dictionary Entry,  Prev: The "Argument Precedence Order" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.17 The "Method Signature" Section of a Dictionary Entry
.............................................................

The description of a generic function includes descriptions of the
methods that are defined on that generic function by the standard.  A
method signature is used to describe the parameters and parameter
specializers for each method.  Methods defined for the generic function
must be of the form described by the method signature.

   'F' (x class) (y t) &optional z &key k

This signature indicates that this method on the generic function F has
two required parameters: x, which must be a generalized instance of the
class class; and y, which can be any object (i.e., a generalized
instance of the class t).  In addition, there is an optional parameter z
and a keyword parameter k.  This signature also indicates that this
method on F is a primary method and has no qualifiers.

   For each parameter, the argument supplied must be in the intersection
of the type specified in the description of the corresponding generic
function and the type given in the signature of some method (including
not only those methods defined in this specification, but also
implementation-defined or user-defined methods in situations where the
definition of such methods is permitted).


File: gcl.info,  Node: The "Name" Section of a Dictionary Entry,  Next: The "Notes" Section of a Dictionary Entry,  Prev: The "Method Signature" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.18 The "Name" Section of a Dictionary Entry
.................................................

This section introduces the dictionary entry.  It is not explicitly
labeled.  It appears preceded and followed by a horizontal bar.

   In large print at left, the defined name appears; if more than one
defined name is to be described by the entry, all such names are shown
separated by commas.

   In somewhat smaller italic print at right is an indication of what
kind of dictionary entry this is.  Possible values are:

Accessor
     This is an accessor function.

Class
     This is a class.

Condition Type
     This is a subtype of type condition.

Constant Variable
     This is a constant variable.

Declaration
     This is a declaration identifier.

Function
     This is a function.

Local Function
     This is a function that is defined only lexically within the scope
     of some other macro form.

Local Macro
     This is a macro that is defined only lexically within the scope of
     some other macro form.

Macro
     This is a macro.

Restart
     This is a restart.

Special Operator
     This is a special operator.

Standard Generic Function
     This is a standard generic function.

Symbol
     This is a symbol that is specially recognized in some particular
     situation, such as the syntax of a macro.

System Class
     This is like class, but it identifies a class that is potentially a
     built-in class.  (No class is actually required to be a built-in
     class.)

Type
     This is an atomic type specifier, and depending on information for
     each particular entry, may subject to form other type specifiers.

Type Specifier
     This is a defined name that is not an atomic type specifier, but
     that can be used in constructing valid type specifiers.

Variable
     This is a dynamic variable.


File: gcl.info,  Node: The "Notes" Section of a Dictionary Entry,  Next: The "Pronunciation" Section of a Dictionary Entry,  Prev: The "Name" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.19 The "Notes" Section of a Dictionary Entry
..................................................

Information not found elsewhere in this description which pertains to
this operator.  Among other things, this might include cross reference
information, code equivalences, stylistic hints, implementation hints,
typical uses.  This information is not considered part of the standard;
any conforming implementation or conforming program is permitted to
ignore the presence of this information.


File: gcl.info,  Node: The "Pronunciation" Section of a Dictionary Entry,  Next: The "See Also" Section of a Dictionary Entry,  Prev: The "Notes" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.20 The "Pronunciation" Section of a Dictionary Entry
..........................................................

This offers a suggested pronunciation for defined names so that people
not in verbal communication with the original designers can figure out
how to pronounce words that are not in normal English usage.  This
information is advisory only, and is not considered part of the
standard.  For brevity, it is only provided for entries with names that
are specific to Common Lisp and would not be found in Webster's Third
New International Dictionary the English Language, Unabridged.


File: gcl.info,  Node: The "See Also" Section of a Dictionary Entry,  Next: The "Side Effects" Section of a Dictionary Entry,  Prev: The "Pronunciation" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.21 The "See Also" Section of a Dictionary Entry
.....................................................

List of references to other parts of this standard that offer
information relevant to this operator.  This list is not part of the
standard.


File: gcl.info,  Node: The "Side Effects" Section of a Dictionary Entry,  Next: The "Supertypes" Section of a Dictionary Entry,  Prev: The "See Also" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.22 The "Side Effects" Section of a Dictionary Entry
.........................................................

Anything that is changed as a result of the evaluation of the form
containing this operator.


File: gcl.info,  Node: The "Supertypes" Section of a Dictionary Entry,  Next: The "Syntax" Section of a Dictionary Entry,  Prev: The "Side Effects" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.23 The "Supertypes" Section of a Dictionary Entry
.......................................................

This appears in the dictionary entry for a type, and contains a list of
the standardized types that must be supertypes of this type.

   In implementations where there is a corresponding class, the order of
the classes in the class precedence list is consistent with the order
presented in this section.


File: gcl.info,  Node: The "Syntax" Section of a Dictionary Entry,  Next: Special "Syntax" Notations for Overloaded Operators,  Prev: The "Supertypes" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.24 The "Syntax" Section of a Dictionary Entry
...................................................

This section describes how to use the defined name in code.  The
"Syntax" description for a generic function describes the lambda list of
the generic function itself, while The "Method Signatures" describe the
lambda lists of the defined methods.  The "Syntax" description for an
ordinary function, a macro, or a special operator describes its
parameters.

   For example, an operator description might say:

   'F' x y &optional z &key k

This description indicates that the function F has two required
parameters, x and y.  In addition, there is an optional parameter z and
a keyword parameter k.

   For macros and special operators, syntax is given in modified BNF
notation; see *note Modified BNF Syntax::.  For functions a lambda list
is given.  In both cases, however, the outermost parentheses are
omitted, and default value information is omitted.


File: gcl.info,  Node: Special "Syntax" Notations for Overloaded Operators,  Next: Naming Conventions for Rest Parameters,  Prev: The "Syntax" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.25 Special "Syntax" Notations for Overloaded Operators
............................................................

If two descriptions exist for the same operation but with different
numbers of arguments, then the extra arguments are to be treated as
optional.  For example, this pair of lines:

   'file-position' stream => position

   'file-position' stream position-spec => success-p

is operationally equivalent to this line:

   'file-position' stream &optional position-spec => result

and differs only in that it provides on opportunity to introduce
different names for parameter and values for each case.  The separated
(multi-line) notation is used when an operator is overloaded in such a
way that the parameters are used in different ways depending on how many
arguments are supplied (e.g., for the function /) or the return values
are different in the two cases (e.g., for the function file-position).


File: gcl.info,  Node: Naming Conventions for Rest Parameters,  Next: Requiring Non-Null Rest Parameters in The "Syntax" Section,  Prev: Special "Syntax" Notations for Overloaded Operators,  Up: Interpreting Dictionary Entries

1.4.4.26 Naming Conventions for Rest Parameters
...............................................

Within this specification, if the name of a rest parameter is chosen to
be a plural noun, use of that name in parameter font refers to the list
to which the rest parameter is bound.  Use of the singular form of that
name in parameter font refers to an element of that list.

   For example, given a syntax description such as:

   'F' &rest arguments

it is appropriate to refer either to the rest parameter named arguments
by name, or to one of its elements by speaking of "an argument," "some
argument," "each argument" etc.


File: gcl.info,  Node: Requiring Non-Null Rest Parameters in The "Syntax" Section,  Next: Return values in The "Syntax" Section,  Prev: Naming Conventions for Rest Parameters,  Up: Interpreting Dictionary Entries

1.4.4.27 Requiring Non-Null Rest Parameters in The "Syntax" Section
...................................................................

In some cases it is useful to refer to all arguments equally as a single
aggregation using a rest parameter while at the same time requiring at
least one argument.  A variety of imperative and declarative means are
available in code for expressing such a restriction, however they
generally do not manifest themselves in a lambda list.  For descriptive
purposes within this specification,

   'F' &rest arguments^+

means the same as

   'F' &rest arguments

but introduces the additional requirement that there be at least one
argument.


File: gcl.info,  Node: Return values in The "Syntax" Section,  Next: No Arguments or Values in The "Syntax" Section,  Prev: Requiring Non-Null Rest Parameters in The "Syntax" Section,  Up: Interpreting Dictionary Entries

1.4.4.28 Return values in The "Syntax" Section
..............................................

An evaluation arrow "=>" precedes a list of values to be returned.  For
example:

   'F' a b c => x

indicates that F is an operator that has three required parameters
(i.e., a, b, and c) and that returns one value (i.e., x).  If more than
one value is returned by an operator, the names of the values are
separated by commas, as in:

   'F' a b c => x, y, z


File: gcl.info,  Node: No Arguments or Values in The "Syntax" Section,  Next: Unconditional Transfer of Control in The "Syntax" Section,  Prev: Return values in The "Syntax" Section,  Up: Interpreting Dictionary Entries

1.4.4.29 No Arguments or Values in The "Syntax" Section
.......................................................

If no arguments are permitted, or no values are returned, a special
notation is used to make this more visually apparent.  For example,

   'F' <no arguments> => <no values>

   indicates that F is an operator that accepts no arguments and returns
no values.


File: gcl.info,  Node: Unconditional Transfer of Control in The "Syntax" Section,  Next: The "Valid Context" Section of a Dictionary Entry,  Prev: No Arguments or Values in The "Syntax" Section,  Up: Interpreting Dictionary Entries

1.4.4.30 Unconditional Transfer of Control in The "Syntax" Section
..................................................................

Some operators perform an unconditional transfer of control, and so
never have any return values.  Such operators are notated using a
notation such as the following:

   'F' a b c => #<NoValue>


File: gcl.info,  Node: The "Valid Context" Section of a Dictionary Entry,  Next: The "Value Type" Section of a Dictionary Entry,  Prev: Unconditional Transfer of Control in The "Syntax" Section,  Up: Interpreting Dictionary Entries

1.4.4.31 The "Valid Context" Section of a Dictionary Entry
..........................................................

This information is used by dictionary entries such as "Declarations" in
order to restrict the context in which the declaration may appear.

   A given "Declaration" might appear in a declaration (i.e., a declare
expression), a proclamation (i.e., a declaim or proclaim form), or both.


File: gcl.info,  Node: The "Value Type" Section of a Dictionary Entry,  Prev: The "Valid Context" Section of a Dictionary Entry,  Up: Interpreting Dictionary Entries

1.4.4.32 The "Value Type" Section of a Dictionary Entry
.......................................................

This information describes any type restrictions on a dynamic variable.


File: gcl.info,  Node: Conformance,  Next: Language Extensions,  Prev: Definitions,  Up: Introduction (Introduction)

1.5 Conformance
===============

This standard presents the syntax and semantics to be implemented by a
conforming implementation (and its accompanying documentation).  In
addition, it imposes requirements on conforming programs.

* Menu:

* Conforming Implementations::
* Conforming Programs::


File: gcl.info,  Node: Conforming Implementations,  Next: Conforming Programs,  Prev: Conformance,  Up: Conformance

1.5.1 Conforming Implementations
--------------------------------

A conforming implementation shall adhere to the requirements outlined in
this section.

* Menu:

* Required Language Features::
* Documentation of Implementation-Dependent Features::
* Documentation of Extensions::
* Treatment of Exceptional Situations::
* Resolution of Apparent Conflicts in Exceptional Situations::
* Examples of Resolution of Apparent Conflict in Exceptional Situations::
* Conformance Statement::


File: gcl.info,  Node: Required Language Features,  Next: Documentation of Implementation-Dependent Features,  Prev: Conforming Implementations,  Up: Conforming Implementations

1.5.1.1 Required Language Features
..................................

A conforming implementation shall accept all features (including
deprecated features) of the language specified in this standard, with
the meanings defined in this standard.

   A conforming implementation shall not require the inclusion of
substitute or additional language elements in code in order to
accomplish a feature of the language that is specified in this standard.


File: gcl.info,  Node: Documentation of Implementation-Dependent Features,  Next: Documentation of Extensions,  Prev: Required Language Features,  Up: Conforming Implementations

1.5.1.2 Documentation of Implementation-Dependent Features
..........................................................

A conforming implementation shall be accompanied by a document that
provides a definition of all implementation-defined aspects of the
language defined by this specification.

   In addition, a conforming implementation is encouraged (but not
required) to document items in this standard that are identified as
implementation-dependent, although in some cases such documentation
might simply identify the item as "undefined."


File: gcl.info,  Node: Documentation of Extensions,  Next: Treatment of Exceptional Situations,  Prev: Documentation of Implementation-Dependent Features,  Up: Conforming Implementations

1.5.1.3 Documentation of Extensions
...................................

A conforming implementation shall be accompanied by a document that
separately describes any features accepted by the implementation that
are not specified in this standard, but that do not cause any ambiguity
or contradiction when added to the language standard.  Such extensions
shall be described as being "extensions to Common Lisp as specified by
ANSI <<standard number>>."


File: gcl.info,  Node: Treatment of Exceptional Situations,  Next: Resolution of Apparent Conflicts in Exceptional Situations,  Prev: Documentation of Extensions,  Up: Conforming Implementations

1.5.1.4 Treatment of Exceptional Situations
...........................................

A conforming implementation shall treat exceptional situations in a
manner consistent with this specification.


File: gcl.info,  Node: Resolution of Apparent Conflicts in Exceptional Situations,  Next: Examples of Resolution of Apparent Conflict in Exceptional Situations,  Prev: Treatment of Exceptional Situations,  Up: Conforming Implementations

1.5.1.5 Resolution of Apparent Conflicts in Exceptional Situations
..................................................................

If more than one passage in this specification appears to apply to the
same situation but in conflicting ways, the passage that appears to
describe the situation in the most specific way (not necessarily the
passage that provides the most constrained kind of error detection)
takes precedence.


File: gcl.info,  Node: Examples of Resolution of Apparent Conflict in Exceptional Situations,  Next: Conformance Statement,  Prev: Resolution of Apparent Conflicts in Exceptional Situations,  Up: Conforming Implementations

1.5.1.6 Examples of Resolution of Apparent Conflict in Exceptional Situations
.............................................................................

Suppose that function foo is a member of a set S of functions that
operate on numbers.  Suppose that one passage states that an error must
be signaled if any function in S is ever given an argument of 17.
Suppose that an apparently conflicting passage states that the
consequences are undefined if foo receives an argument of 17.  Then the
second passage (the one specifically about foo) would dominate because
the description of the situational context is the most specific, and it
would not be required that foo signal an error on an argument of 17 even
though other functions in the set S would be required to do so.


File: gcl.info,  Node: Conformance Statement,  Prev: Examples of Resolution of Apparent Conflict in Exceptional Situations,  Up: Conforming Implementations

1.5.1.7 Conformance Statement
.............................

A conforming implementation shall produce a conformance statement as a
consequence of using the implementation, or that statement shall be
included in the accompanying documentation.  If the implementation
conforms in all respects with this standard, the conformance statement
shall be

     "<<Implementation>> conforms with the requirements of ANSI
     <<standard number>>"

   If the implementation conforms with some but not all of the
requirements of this standard, then the conformance statement shall be

     "<<Implementation>> conforms with the requirements of ANSI
     <<standard number>> with the following exceptions: <<reference to
     or complete list of the requirements of the standard with which the
     implementation does not conform>>."


File: gcl.info,  Node: Conforming Programs,  Prev: Conforming Implementations,  Up: Conformance

1.5.2 Conforming Programs
-------------------------

Code conforming with the requirements of this standard shall adhere to
the following:

1.
     Conforming code shall use only those features of the language
     syntax and semantics that are either specified in this standard or
     defined using the extension mechanisms specified in the standard.

2.
     Conforming code shall not rely on any particular interpretation of
     implementation-dependent features.

3.
     Conforming code shall not depend on the consequences of undefined
     or unspecified situations.

4.
     Conforming code does not use any constructions that are prohibited
     by the standard.

5.
     Conforming code does not depend on extensions included in an
     implementation.

* Menu:

* Use of Implementation-Defined Language Features::
* Use of Read-Time Conditionals::


File: gcl.info,  Node: Use of Implementation-Defined Language Features,  Next: Use of Read-Time Conditionals,  Prev: Conforming Programs,  Up: Conforming Programs

1.5.2.1 Use of Implementation-Defined Language Features
.......................................................

Note that conforming code may rely on particular implementation-defined
values or features.  Also note that the requirements for conforming code
and conforming implementations do not require that the results produced
by conforming code always be the same when processed by a conforming
implementation.  The results may be the same, or they may differ.

   Portable code is written using only standard characters.

   Conforming code may run in all conforming implementations, but might
have allowable implementation-defined behavior that makes it
non-portable code.  For example, the following are examples of forms
that are conforming, but that might return different values in different
implementations:

      (evenp most-positive-fixnum) =>  implementation-dependent
      (random) =>  implementation-dependent
      (> lambda-parameters-limit 93) =>  implementation-dependent
      (char-name #\A) =>  implementation-dependent


File: gcl.info,  Node: Use of Read-Time Conditionals,  Prev: Use of Implementation-Defined Language Features,  Up: Conforming Programs

1.5.2.2 Use of Read-Time Conditionals
.....................................

Use of #+ and #- does not automatically disqualify a program from being
conforming.  A program which uses #+ and #- is considered conforming if
there is no set of features in which the program would not be
conforming.  Of course, conforming programs are not necessarily working
programs.  The following program is conforming:

     (defun foo ()
       #+ACME (acme:initialize-something)
       (print 'hello-there))

   However, this program might or might not work, depending on whether
the presence of the feature ACME really implies that a function named
acme:initialize-something is present in the environment.  In effect,
using #+ or #- in a conforming program means that the variable
*features*

   becomes just one more piece of input data to that program.  Like any
other data coming into a program, the programmer is responsible for
assuring that the program does not make unwarranted assumptions on the
basis of input data.


File: gcl.info,  Node: Language Extensions,  Next: Language Subsets,  Prev: Conformance,  Up: Introduction (Introduction)

1.6 Language Extensions
=======================

A language extension is any documented implementation-defined behavior
of a defined name in this standard that varies from the behavior
described in this standard, or a documented consequence of a situation
that the standard specifies as undefined, unspecified, or extendable by
the implementation.  For example, if this standard says that "the
results are unspecified," an extension would be to specify the results.

   [Reviewer Note by Barmar: This contradicts previous definitions of
conforming code.]  If the correct behavior of a program depends on the
results provided by an extension, only implementations with the same
extension will execute the program correctly.  Note that such a program
might be non-conforming.  Also, if this standard says that "an
implementation may be extended," a conforming, but possibly
non-portable, program can be written using an extension.

   An implementation can have extensions, provided they do not alter the
behavior of conforming code and provided they are not explicitly
prohibited by this standard.

   The term "extension" refers only to extensions available upon
startup.  An implementation is free to allow or prohibit redefinition of
an extension.

   The following list contains specific guidance to implementations
concerning certain types of extensions.

Extra return values

     An implementation must return exactly the number of return values
     specified by this standard unless the standard specifically
     indicates otherwise.

Unsolicited messages

     No output can be produced by a function other than that specified
     in the standard or due to the signaling of conditions detected by
     the function.

     Unsolicited output, such as garbage collection notifications and
     autoload heralds, should not go directly to the stream that is the
     value of a stream variable defined in this standard, but can go
     indirectly to terminal I/O by using a synonym stream to
     *terminal-io*.

     Progress reports from such functions as load and compile are
     considered solicited, and are not covered by this prohibition.

Implementation of macros and special forms

     Macros and special operators defined in this standard must not be
     functions.


File: gcl.info,  Node: Language Subsets,  Next: Deprecated Language Features,  Prev: Language Extensions,  Up: Introduction (Introduction)

1.7 Language Subsets
====================

The language described in this standard contains no subsets, though
subsets are not forbidden.

   For a language to be considered a subset, it must have the property
that any valid program in that language has equivalent semantics and
will run directly (with no extralingual pre-processing, and no special
compatibility packages) in any conforming implementation of the full
language.

   A language that conforms to this requirement shall be described as
being a "subset of Common Lisp as specified by ANSI <<standard
number>>."


File: gcl.info,  Node: Deprecated Language Features,  Next: Symbols in the COMMON-LISP Package,  Prev: Language Subsets,  Up: Introduction (Introduction)

1.8 Deprecated Language Features
================================

Deprecated language features are not expected to appear in future Common
Lisp standards, but are required to be implemented for conformance with
this standard; see *note Required Language Features::.

   Conforming programs can use deprecated features; however, it is
considered good programming style to avoid them.  It is permissible for
the compiler to produce style warnings about the use of such features at
compile time, but there should be no such warnings at program execution
time.

* Menu:

* Deprecated Functions::
* Deprecated Argument Conventions::
* Deprecated Variables::
* Deprecated Reader Syntax::


File: gcl.info,  Node: Deprecated Functions,  Next: Deprecated Argument Conventions,  Prev: Deprecated Language Features,  Up: Deprecated Language Features

1.8.1 Deprecated Functions
--------------------------

The functions in Figure 1-2 are deprecated.
  assoc-if-not   nsubst-if-not       require            
  count-if-not   nsubstitute-if-not  set                
  delete-if-not  position-if-not     subst-if-not       
  find-if-not    provide             substitute-if-not  
  gentemp        rassoc-if-not                          
  member-if-not  remove-if-not                          

            Figure 1-2: Deprecated Functions           



File: gcl.info,  Node: Deprecated Argument Conventions,  Next: Deprecated Variables,  Prev: Deprecated Functions,  Up: Deprecated Language Features

1.8.2 Deprecated Argument Conventions
-------------------------------------

The ability to pass a numeric argument to gensym has been deprecated.

   The :test-not argument to the functions in Figure 1-3 are deprecated.

  adjoin             nset-difference    search            
  assoc              nset-exclusive-or  set-difference    
  count              nsublis            set-exclusive-or  
  delete             nsubst             sublis            
  delete-duplicates  nsubstitute        subsetp           
  find               nunion             subst             
  intersection       position           substitute        
  member             rassoc             tree-equal        
  mismatch           remove             union             
  nintersection      remove-duplicates                    

  Figure 1-3: Functions with Deprecated :TEST-NOT Arguments


   The use of the situation names compile, load, and eval in eval-when
is deprecated.


File: gcl.info,  Node: Deprecated Variables,  Next: Deprecated Reader Syntax,  Prev: Deprecated Argument Conventions,  Up: Deprecated Language Features

1.8.3 Deprecated Variables
--------------------------

The variable *modules* is deprecated.


File: gcl.info,  Node: Deprecated Reader Syntax,  Prev: Deprecated Variables,  Up: Deprecated Language Features

1.8.4 Deprecated Reader Syntax
------------------------------

The #S reader macro forces keyword names into the KEYWORD package; see
*note Sharpsign S::.  This feature is deprecated; in the future, keyword
names will be taken in the package they are read in, so symbols that are
actually in the KEYWORD package should be used if that is what is
desired.


File: gcl.info,  Node: Symbols in the COMMON-LISP Package,  Prev: Deprecated Language Features,  Up: Introduction (Introduction)

1.9 Symbols in the COMMON-LISP Package
======================================

The figures on the next twelve pages contain a complete enumeration of
the 978 external symbols in the COMMON-LISP package.

  &allow-other-keys            *print-miser-width*          
  &aux                         *print-pprint-dispatch*      
  &body                        *print-pretty*               
  &environment                 *print-radix*                
  &key                         *print-readably*             
  &optional                    *print-right-margin*         
  &rest                        *query-io*                   
  &whole                       *random-state*               
  *                            *read-base*                  
  **                           *read-default-float-format*  
  ***                          *read-eval*                  
  *break-on-signals*           *read-suppress*              
  *compile-file-pathname*      *readtable*                  
  *compile-file-truename*      *standard-input*             
  *compile-print*              *standard-output*            
  *compile-verbose*            *terminal-io*                
  *debug-io*                   *trace-output*               
  *debugger-hook*              +                            
  *default-pathname-defaults*  ++                           
  *error-output*               +++                          
  *features*                   -                            
  *gensym-counter*             /                            
  *load-pathname*              //                           
  *load-print*                 ///                          
  *load-truename*              /=                           
  *load-verbose*               1+                           
  *macroexpand-hook*           1-                           
  *modules*                    <                            
  *package*                    <=                           
  *print-array*                =                            
  *print-base*                 >                            
  *print-case*                 >=                           
  *print-circle*               abort                        
  *print-escape*               abs                          
  *print-gensym*               acons                        
  *print-length*               acos                         
  *print-level*                acosh                        
  *print-lines*                add-method                   

  Figure 1-4: Symbols in the COMMON-LISP package (part one of twelve).


  adjoin                      atom          boundp                    
  adjust-array                base-char     break                     
  adjustable-array-p          base-string   broadcast-stream          
  allocate-instance           bignum        broadcast-stream-streams  
  alpha-char-p                bit           built-in-class            
  alphanumericp               bit-and       butlast                   
  and                         bit-andc1     byte                      
  append                      bit-andc2     byte-position             
  apply                       bit-eqv       byte-size                 
  apropos                     bit-ior       caaaar                    
  apropos-list                bit-nand      caaadr                    
  aref                        bit-nor       caaar                     
  arithmetic-error            bit-not       caadar                    
  arithmetic-error-operands   bit-orc1      caaddr                    
  arithmetic-error-operation  bit-orc2      caadr                     
  array                       bit-vector    caar                      
  array-dimension             bit-vector-p  cadaar                    
  array-dimension-limit       bit-xor       cadadr                    
  array-dimensions            block         cadar                     
  array-displacement          boole         caddar                    
  array-element-type          boole-1       cadddr                    
  array-has-fill-pointer-p    boole-2       caddr                     
  array-in-bounds-p           boole-and     cadr                      
  array-rank                  boole-andc1   call-arguments-limit      
  array-rank-limit            boole-andc2   call-method               
  array-row-major-index       boole-c1      call-next-method          
  array-total-size            boole-c2      car                       
  array-total-size-limit      boole-clr     case                      
  arrayp                      boole-eqv     catch                     
  ash                         boole-ior     ccase                     
  asin                        boole-nand    cdaaar                    
  asinh                       boole-nor     cdaadr                    
  assert                      boole-orc1    cdaar                     
  assoc                       boole-orc2    cdadar                    
  assoc-if                    boole-set     cdaddr                    
  assoc-if-not                boole-xor     cdadr                     
  atan                        boolean       cdar                      
  atanh                       both-case-p   cddaar                    

  Figure 1-5: Symbols in the COMMON-LISP package (part two of twelve).


  cddadr             clear-input                  copy-tree                  
  cddar              clear-output                 cos                        
  cdddar             close                        cosh                       
  cddddr             clrhash                      count                      
  cdddr              code-char                    count-if                   
  cddr               coerce                       count-if-not               
  cdr                compilation-speed            ctypecase                  
  ceiling            compile                      debug                      
  cell-error         compile-file                 decf                       
  cell-error-name    compile-file-pathname        declaim                    
  cerror             compiled-function            declaration                
  change-class       compiled-function-p          declare                    
  char               compiler-macro               decode-float               
  char-code          compiler-macro-function      decode-universal-time      
  char-code-limit    complement                   defclass                   
  char-downcase      complex                      defconstant                
  char-equal         complexp                     defgeneric                 
  char-greaterp      compute-applicable-methods   define-compiler-macro      
  char-int           compute-restarts             define-condition           
  char-lessp         concatenate                  define-method-combination  
  char-name          concatenated-stream          define-modify-macro        
  char-not-equal     concatenated-stream-streams  define-setf-expander       
  char-not-greaterp  cond                         define-symbol-macro        
  char-not-lessp     condition                    defmacro                   
  char-upcase        conjugate                    defmethod                  
  char/=             cons                         defpackage                 
  char<              consp                        defparameter               
  char<=             constantly                   defsetf                    
  char=              constantp                    defstruct                  
  char>              continue                     deftype                    
  char>=             control-error                defun                      
  character          copy-alist                   defvar                     
  characterp         copy-list                    delete                     
  check-type         copy-pprint-dispatch         delete-duplicates          
  cis                copy-readtable               delete-file                
  class              copy-seq                     delete-if                  
  class-name         copy-structure               delete-if-not              
  class-of           copy-symbol                  delete-package             

    Figure 1-6: Symbols in the COMMON-LISP package (part three of twelve).  


  denominator                    eq                   
  deposit-field                  eql                  
  describe                       equal                
  describe-object                equalp               
  destructuring-bind             error                
  digit-char                     etypecase            
  digit-char-p                   eval                 
  directory                      eval-when            
  directory-namestring           evenp                
  disassemble                    every                
  division-by-zero               exp                  
  do                             export               
  do*                            expt                 
  do-all-symbols                 extended-char        
  do-external-symbols            fboundp              
  do-symbols                     fceiling             
  documentation                  fdefinition          
  dolist                         ffloor               
  dotimes                        fifth                
  double-float                   file-author          
  double-float-epsilon           file-error           
  double-float-negative-epsilon  file-error-pathname  
  dpb                            file-length          
  dribble                        file-namestring      
  dynamic-extent                 file-position        
  ecase                          file-stream          
  echo-stream                    file-string-length   
  echo-stream-input-stream       file-write-date      
  echo-stream-output-stream      fill                 
  ed                             fill-pointer         
  eighth                         find                 
  elt                            find-all-symbols     
  encode-universal-time          find-class           
  end-of-file                    find-if              
  endp                           find-if-not          
  enough-namestring              find-method          
  ensure-directories-exist       find-package         
  ensure-generic-function        find-restart         

  Figure 1-7: Symbols in the COMMON-LISP package (part four of twelve).


  find-symbol                       get-internal-run-time        
  finish-output                     get-macro-character          
  first                             get-output-stream-string     
  fixnum                            get-properties               
  flet                              get-setf-expansion           
  float                             get-universal-time           
  float-digits                      getf                         
  float-precision                   gethash                      
  float-radix                       go                           
  float-sign                        graphic-char-p               
  floating-point-inexact            handler-bind                 
  floating-point-invalid-operation  handler-case                 
  floating-point-overflow           hash-table                   
  floating-point-underflow          hash-table-count             
  floatp                            hash-table-p                 
  floor                             hash-table-rehash-size       
  fmakunbound                       hash-table-rehash-threshold  
  force-output                      hash-table-size              
  format                            hash-table-test              
  formatter                         host-namestring              
  fourth                            identity                     
  fresh-line                        if                           
  fround                            ignorable                    
  ftruncate                         ignore                       
  ftype                             ignore-errors                
  funcall                           imagpart                     
  function                          import                       
  function-keywords                 in-package                   
  function-lambda-expression        incf                         
  functionp                         initialize-instance          
  gcd                               inline                       
  generic-function                  input-stream-p               
  gensym                            inspect                      
  gentemp                           integer                      
  get                               integer-decode-float         
  get-decoded-time                  integer-length               
  get-dispatch-macro-character      integerp                     
  get-internal-real-time            interactive-stream-p         

  Figure 1-8: Symbols in the COMMON-LISP package (part five of twelve).


  intern                                  lisp-implementation-type            
  internal-time-units-per-second          lisp-implementation-version         
  intersection                            list                                
  invalid-method-error                    list*                               
  invoke-debugger                         list-all-packages                   
  invoke-restart                          list-length                         
  invoke-restart-interactively            listen                              
  isqrt                                   listp                               
  keyword                                 load                                
  keywordp                                load-logical-pathname-translations  
  labels                                  load-time-value                     
  lambda                                  locally                             
  lambda-list-keywords                    log                                 
  lambda-parameters-limit                 logand                              
  last                                    logandc1                            
  lcm                                     logandc2                            
  ldb                                     logbitp                             
  ldb-test                                logcount                            
  ldiff                                   logeqv                              
  least-negative-double-float             logical-pathname                    
  least-negative-long-float               logical-pathname-translations       
  least-negative-normalized-double-float  logior                              
  least-negative-normalized-long-float    lognand                             
  least-negative-normalized-short-float   lognor                              
  least-negative-normalized-single-float  lognot                              
  least-negative-short-float              logorc1                             
  least-negative-single-float             logorc2                             
  least-positive-double-float             logtest                             
  least-positive-long-float               logxor                              
  least-positive-normalized-double-float  long-float                          
  least-positive-normalized-long-float    long-float-epsilon                  
  least-positive-normalized-short-float   long-float-negative-epsilon         
  least-positive-normalized-single-float  long-site-name                      
  least-positive-short-float              loop                                
  least-positive-single-float             loop-finish                         
  length                                  lower-case-p                        
  let                                     machine-instance                    
  let*                                    machine-type                        

     Figure 1-9: Symbols in the COMMON-LISP package (part six of twelve).    


  machine-version                mask-field                  
  macro-function                 max                         
  macroexpand                    member                      
  macroexpand-1                  member-if                   
  macrolet                       member-if-not               
  make-array                     merge                       
  make-broadcast-stream          merge-pathnames             
  make-concatenated-stream       method                      
  make-condition                 method-combination          
  make-dispatch-macro-character  method-combination-error    
  make-echo-stream               method-qualifiers           
  make-hash-table                min                         
  make-instance                  minusp                      
  make-instances-obsolete        mismatch                    
  make-list                      mod                         
  make-load-form                 most-negative-double-float  
  make-load-form-saving-slots    most-negative-fixnum        
  make-method                    most-negative-long-float    
  make-package                   most-negative-short-float   
  make-pathname                  most-negative-single-float  
  make-random-state              most-positive-double-float  
  make-sequence                  most-positive-fixnum        
  make-string                    most-positive-long-float    
  make-string-input-stream       most-positive-short-float   
  make-string-output-stream      most-positive-single-float  
  make-symbol                    muffle-warning              
  make-synonym-stream            multiple-value-bind         
  make-two-way-stream            multiple-value-call         
  makunbound                     multiple-value-list         
  map                            multiple-value-prog1        
  map-into                       multiple-value-setq         
  mapc                           multiple-values-limit       
  mapcan                         name-char                   
  mapcar                         namestring                  
  mapcon                         nbutlast                    
  maphash                        nconc                       
  mapl                           next-method-p               
  maplist                        nil                         

  Figure 1-10: Symbols in the COMMON-LISP package (part seven of twelve).


  nintersection         package-error                  
  ninth                 package-error-package          
  no-applicable-method  package-name                   
  no-next-method        package-nicknames              
  not                   package-shadowing-symbols      
  notany                package-use-list               
  notevery              package-used-by-list           
  notinline             packagep                       
  nreconc               pairlis                        
  nreverse              parse-error                    
  nset-difference       parse-integer                  
  nset-exclusive-or     parse-namestring               
  nstring-capitalize    pathname                       
  nstring-downcase      pathname-device                
  nstring-upcase        pathname-directory             
  nsublis               pathname-host                  
  nsubst                pathname-match-p               
  nsubst-if             pathname-name                  
  nsubst-if-not         pathname-type                  
  nsubstitute           pathname-version               
  nsubstitute-if        pathnamep                      
  nsubstitute-if-not    peek-char                      
  nth                   phase                          
  nth-value             pi                             
  nthcdr                plusp                          
  null                  pop                            
  number                position                       
  numberp               position-if                    
  numerator             position-if-not                
  nunion                pprint                         
  oddp                  pprint-dispatch                
  open                  pprint-exit-if-list-exhausted  
  open-stream-p         pprint-fill                    
  optimize              pprint-indent                  
  or                    pprint-linear                  
  otherwise             pprint-logical-block           
  output-stream-p       pprint-newline                 
  package               pprint-pop                     

  Figure 1-11: Symbols in the COMMON-LISP package (part eight of twelve).


  pprint-tab                 read-char                   
  pprint-tabular             read-char-no-hang           
  prin1                      read-delimited-list         
  prin1-to-string            read-from-string            
  princ                      read-line                   
  princ-to-string            read-preserving-whitespace  
  print                      read-sequence               
  print-not-readable         reader-error                
  print-not-readable-object  readtable                   
  print-object               readtable-case              
  print-unreadable-object    readtablep                  
  probe-file                 real                        
  proclaim                   realp                       
  prog                       realpart                    
  prog*                      reduce                      
  prog1                      reinitialize-instance       
  prog2                      rem                         
  progn                      remf                        
  program-error              remhash                     
  progv                      remove                      
  provide                    remove-duplicates           
  psetf                      remove-if                   
  psetq                      remove-if-not               
  push                       remove-method               
  pushnew                    remprop                     
  quote                      rename-file                 
  random                     rename-package              
  random-state               replace                     
  random-state-p             require                     
  rassoc                     rest                        
  rassoc-if                  restart                     
  rassoc-if-not              restart-bind                
  ratio                      restart-case                
  rational                   restart-name                
  rationalize                return                      
  rationalp                  return-from                 
  read                       revappend                   
  read-byte                  reverse                     

  Figure 1-12: Symbols in the COMMON-LISP package (part nine of twelve).


  room                          simple-bit-vector                  
  rotatef                       simple-bit-vector-p                
  round                         simple-condition                   
  row-major-aref                simple-condition-format-arguments  
  rplaca                        simple-condition-format-control    
  rplacd                        simple-error                       
  safety                        simple-string                      
  satisfies                     simple-string-p                    
  sbit                          simple-type-error                  
  scale-float                   simple-vector                      
  schar                         simple-vector-p                    
  search                        simple-warning                     
  second                        sin                                
  sequence                      single-float                       
  serious-condition             single-float-epsilon               
  set                           single-float-negative-epsilon      
  set-difference                sinh                               
  set-dispatch-macro-character  sixth                              
  set-exclusive-or              sleep                              
  set-macro-character           slot-boundp                        
  set-pprint-dispatch           slot-exists-p                      
  set-syntax-from-char          slot-makunbound                    
  setf                          slot-missing                       
  setq                          slot-unbound                       
  seventh                       slot-value                         
  shadow                        software-type                      
  shadowing-import              software-version                   
  shared-initialize             some                               
  shiftf                        sort                               
  short-float                   space                              
  short-float-epsilon           special                            
  short-float-negative-epsilon  special-operator-p                 
  short-site-name               speed                              
  signal                        sqrt                               
  signed-byte                   stable-sort                        
  signum                        standard                           
  simple-array                  standard-char                      
  simple-base-string            standard-char-p                    

  Figure 1-13: Symbols in the COMMON-LISP package (part ten of twelve).


  standard-class             sublis                      
  standard-generic-function  subseq                      
  standard-method            subsetp                     
  standard-object            subst                       
  step                       subst-if                    
  storage-condition          subst-if-not                
  store-value                substitute                  
  stream                     substitute-if               
  stream-element-type        substitute-if-not           
  stream-error               subtypep                    
  stream-error-stream        svref                       
  stream-external-format     sxhash                      
  streamp                    symbol                      
  string                     symbol-function             
  string-capitalize          symbol-macrolet             
  string-downcase            symbol-name                 
  string-equal               symbol-package              
  string-greaterp            symbol-plist                
  string-left-trim           symbol-value                
  string-lessp               symbolp                     
  string-not-equal           synonym-stream              
  string-not-greaterp        synonym-stream-symbol       
  string-not-lessp           t                           
  string-right-trim          tagbody                     
  string-stream              tailp                       
  string-trim                tan                         
  string-upcase              tanh                        
  string/=                   tenth                       
  string<                    terpri                      
  string<=                   the                         
  string=                    third                       
  string>                    throw                       
  string>=                   time                        
  stringp                    trace                       
  structure                  translate-logical-pathname  
  structure-class            translate-pathname          
  structure-object           tree-equal                  
  style-warning              truename                    

  Figure 1-14: Symbols in the COMMON-LISP package (part eleven of twelve).


  truncate                             values-list               
  two-way-stream                       variable                  
  two-way-stream-input-stream          vector                    
  two-way-stream-output-stream         vector-pop                
  type                                 vector-push               
  type-error                           vector-push-extend        
  type-error-datum                     vectorp                   
  type-error-expected-type             warn                      
  type-of                              warning                   
  typecase                             when                      
  typep                                wild-pathname-p           
  unbound-slot                         with-accessors            
  unbound-slot-instance                with-compilation-unit     
  unbound-variable                     with-condition-restarts   
  undefined-function                   with-hash-table-iterator  
  unexport                             with-input-from-string    
  unintern                             with-open-file            
  union                                with-open-stream          
  unless                               with-output-to-string     
  unread-char                          with-package-iterator     
  unsigned-byte                        with-simple-restart       
  untrace                              with-slots                
  unuse-package                        with-standard-io-syntax   
  unwind-protect                       write                     
  update-instance-for-different-class  write-byte                
  update-instance-for-redefined-class  write-char                
  upgraded-array-element-type          write-line                
  upgraded-complex-part-type           write-sequence            
  upper-case-p                         write-string              
  use-package                          write-to-string           
  use-value                            y-or-n-p                  
  user-homedir-pathname                yes-or-no-p               
  values                               zerop                     

  Figure 1-15: Symbols in the COMMON-LISP package (part twelve of twelve).



File: gcl.info,  Node: Syntax,  Next: Evaluation and Compilation,  Prev: Introduction (Introduction),  Up: Top

2 Syntax
********

* Menu:

* Character Syntax::
* Reader Algorithm::
* Interpretation of Tokens::
* Standard Macro Characters::


File: gcl.info,  Node: Character Syntax,  Next: Reader Algorithm,  Prev: Syntax,  Up: Syntax

2.1 Character Syntax
====================

The Lisp reader takes characters from a stream, interprets them as a
printed representation of an object, constructs that object, and returns
it.

   The syntax described by this chapter is called the standard syntax .
Operations are provided by Common Lisp so that various aspects of the
syntax information represented by a readtable can be modified under
program control; see *note Reader::.  Except as explicitly stated
otherwise, the syntax used throughout this document is standard syntax.

* Menu:

* Readtables::
* Variables that affect the Lisp Reader::
* Standard Characters::
* Character Syntax Types::


File: gcl.info,  Node: Readtables,  Next: Variables that affect the Lisp Reader,  Prev: Character Syntax,  Up: Character Syntax

2.1.1 Readtables
----------------

Syntax information for use by the Lisp reader is embodied in an object
called a readtable .  Among other things, the readtable contains the
association between characters and syntax types.

   Figure 2-1 lists some defined names that are applicable to
readtables.

  *readtable*                    readtable-case                
  copy-readtable                 readtablep                    
  get-dispatch-macro-character   set-dispatch-macro-character  
  get-macro-character            set-macro-character           
  make-dispatch-macro-character  set-syntax-from-char          

              Figure 2-1: Readtable defined names             


* Menu:

* The Current Readtable::
* The Standard Readtable::
* The Initial Readtable::


File: gcl.info,  Node: The Current Readtable,  Next: The Standard Readtable,  Prev: Readtables,  Up: Readtables

2.1.1.1 The Current Readtable
.............................

Several readtables describing different syntaxes can exist, but at any
given time only one, called the current readtable , affects the way in
which expressions_2 are parsed into objects by the Lisp reader.  The
current readtable in a given dynamic environment is the value of
*readtable* in that environment.  To make a different readtable become
the current readtable, *readtable* can be assigned or bound.


File: gcl.info,  Node: The Standard Readtable,  Next: The Initial Readtable,  Prev: The Current Readtable,  Up: Readtables

2.1.1.2 The Standard Readtable
..............................

The standard readtable conforms to standard syntax.  The consequences
are undefined if an attempt is made to modify the standard readtable.
To achieve the effect of altering or extending standard syntax, a copy
of the standard readtable can be created; see the function
copy-readtable.

   The readtable case of the standard readtable is :upcase.


File: gcl.info,  Node: The Initial Readtable,  Prev: The Standard Readtable,  Up: Readtables

2.1.1.3 The Initial Readtable
.............................

The initial readtable is the readtable that is the current readtable at
the time when the Lisp image starts.  At that time, it conforms to
standard syntax.  The initial readtable is distinct from the standard
readtable.  It is permissible for a conforming program to modify the
initial readtable.


File: gcl.info,  Node: Variables that affect the Lisp Reader,  Next: Standard Characters,  Prev: Readtables,  Up: Character Syntax

2.1.2 Variables that affect the Lisp Reader
-------------------------------------------

The Lisp reader is influenced not only by the current readtable, but
also by various dynamic variables.  Figure 2-2 lists the variables that
influence the behavior of the Lisp reader.

  *package*    *read-default-float-format*  *readtable*  
  *read-base*  *read-suppress*                           

  Figure 2-2: Variables that influence the Lisp reader. 



File: gcl.info,  Node: Standard Characters,  Next: Character Syntax Types,  Prev: Variables that affect the Lisp Reader,  Up: Character Syntax

2.1.3 Standard Characters
-------------------------

All implementations must support a character repertoire called
standard-char; characters that are members of that repertoire are called
standard characters .

   The standard-char repertoire consists of the non-graphic character
newline, the graphic character space, and the following additional
ninety-four graphic characters or their equivalents:

  Graphic ID  Glyph  Description  Graphic ID  Glyph  Description  
  LA01        a      small a      LN01        n      small n      
  LA02        A      capital A    LN02        N      capital N    
  LB01        b      small b      LO01        o      small o      
  LB02        B      capital B    LO02        O      capital O    
  LC01        c      small c      LP01        p      small p      
  LC02        C      capital C    LP02        P      capital P    
  LD01        d      small d      LQ01        q      small q      
  LD02        D      capital D    LQ02        Q      capital Q    
  LE01        e      small e      LR01        r      small r      
  LE02        E      capital E    LR02        R      capital R    
  LF01        f      small f      LS01        s      small s      
  LF02        F      capital F    LS02        S      capital S    
  LG01        g      small g      LT01        t      small t      
  LG02        G      capital G    LT02        T      capital T    
  LH01        h      small h      LU01        u      small u      
  LH02        H      capital H    LU02        U      capital U    
  LI01        i      small i      LV01        v      small v      
  LI02        I      capital I    LV02        V      capital V    
  LJ01        j      small j      LW01        w      small w      
  LJ02        J      capital J    LW02        W      capital W    
  LK01        k      small k      LX01        x      small x      
  LK02        K      capital K    LX02        X      capital X    
  LL01        l      small l      LY01        y      small y      
  LL02        L      capital L    LY02        Y      capital Y    
  LM01        m      small m      LZ01        z      small z      
  LM02        M      capital M    LZ02        Z      capital Z    

  Figure 2-3: Standard Character Subrepertoire (Part 1 of 3: Latin Characters)


  Graphic ID  Glyph  Description  Graphic ID  Glyph  Description  
  ND01        1      digit 1      ND06        6      digit 6      
  ND02        2      digit 2      ND07        7      digit 7      
  ND03        3      digit 3      ND08        8      digit 8      
  ND04        4      digit 4      ND09        9      digit 9      
  ND05        5      digit 5      ND10        0      digit 0      

  Figure 2-4: Standard Character Subrepertoire (Part 2 of 3: Numeric Characters)


  Graphic ID  Glyph  Description                              
  SP02        !      exclamation mark                         
  SC03        $     dollar sign                              
  SP04        "      quotation mark, or double quote          
  SP05        '      apostrophe, or [single] quote            
  SP06        (      left parenthesis, or open parenthesis    
  SP07        )      right parenthesis, or close parenthesis  
  SP08        ,      comma                                    
  SP09        _      low line, or underscore                  
  SP10        -      hyphen, or minus [sign]                  
  SP11        .      full stop, period, or dot                
  SP12        /      solidus, or slash                        
  SP13        :      colon                                    
  SP14        ;      semicolon                                
  SP15        ?      question mark                            
  SA01        +      plus [sign]                              
  SA03        <      less-than [sign]                         
  SA04        =      equals [sign]                            
  SA05        >      greater-than [sign]                      
  SM01        #      number sign, or sharp[sign]              
  SM02        %      percent [sign]                           
  SM03        &      ampersand                                
  SM04        *      asterisk, or star                        
  SM05        @      commercial at, or at-sign                
  SM06        [      left [square] bracket                    
  SM07        \      reverse solidus, or backslash            
  SM08        ]      right [square] bracket                   
  SM11        {      left curly bracket, or left brace        
  SM13        |      vertical bar                             
  SM14        }      right curly bracket, or right brace      
  SD13        `      grave accent, or backquote               
  SD15        ^      circumflex accent                        
  SD19        ~      tilde                                    

  Figure 2-5: Standard Character Subrepertoire (Part 3 of 3: Special Characters)


   The graphic IDs are not used within Common Lisp, but are provided for
cross reference purposes with ISO 6937/2.  Note that the first letter of
the graphic ID categorizes the character as follows: L--Latin,
N--Numeric, S--Special.


File: gcl.info,  Node: Character Syntax Types,  Prev: Standard Characters,  Up: Character Syntax

2.1.4 Character Syntax Types
----------------------------

The Lisp reader constructs an object from the input text by interpreting
each character according to its syntax type.  The Lisp reader cannot
accept as input everything that the Lisp printer produces, and the Lisp
reader has features that are not used by the Lisp printer.  The Lisp
reader can be used as a lexical analyzer for a more general user-written
parser.

   When the Lisp reader is invoked, it reads a single character from the
input stream and dispatches according to the syntax type of that
character.  Every character that can appear in the input stream is of
one of the syntax types shown in Figure~2-6.

  constituent  macro character  single escape  
  invalid      multiple escape  whitespace_2   

  Figure 2-6: Possible Character Syntax Types 


   The syntax type of a character in a readtable determines how that
character is interpreted by the Lisp reader while that readtable is the
current readtable.  At any given time, every character has exactly one
syntax type.

   Figure~2-7 lists the syntax type of each character in standard
syntax.

  character  syntax type                 character  syntax type             
  Backspace  constituent                 0-9       constituent             
  Tab        whitespace_2                :          constituent             
  Newline    whitespace_2                ;          terminating macro char  
  Linefeed   whitespace_2                <          constituent             
  Page       whitespace_2                =          constituent             
  Return     whitespace_2                >          constituent             
  Space      whitespace_2                ?          constituent*            
  !          constituent*                @          constituent             
  "          terminating macro char      A-Z       constituent             
  #          non-terminating macro char  [          constituent*            
  $         constituent                 \          single escape           
  %          constituent                 ]          constituent*            
  &          constituent                 ^          constituent             
  '          terminating macro char      _          constituent             
  (          terminating macro char      '          terminating macro char  
  )          terminating macro char      a-z       constituent             
  *          constituent                 {          constituent*            
  +          constituent                 |          multiple escape         
  ,          terminating macro char      }          constituent*            
  -          constituent                 ~          constituent             
  .          constituent                 Rubout     constituent             
  /          constituent                 

            Figure 2-7: Character Syntax Types in Standard Syntax          


   The characters marked with an asterisk (*) are initially
constituents, but they are not used in any standard Common Lisp
notations.  These characters are explicitly reserved to the programmer.
~ is not used in Common Lisp, and reserved to implementors.  $ and % are
alphabetic_2 characters, but are not used in the names of any standard
Common Lisp defined names.

   Whitespace_2 characters serve as separators but are otherwise
ignored.  Constituent and escape characters are accumulated to make a
token, which is then interpreted as a number or symbol.  Macro
characters trigger the invocation of functions (possibly user-supplied)
that can perform arbitrary parsing actions.  Macro characters are
divided into two kinds, terminating and non-terminating, depending on
whether or not they terminate a token.  The following are descriptions
of each kind of syntax type.

* Menu:

* Constituent Characters::
* Constituent Traits::
* Invalid Characters::
* Macro Characters::
* Multiple Escape Characters::
* Examples of Multiple Escape Characters::
* Single Escape Character::
* Examples of Single Escape Characters::
* Whitespace Characters::
* Examples of Whitespace Characters::


File: gcl.info,  Node: Constituent Characters,  Next: Constituent Traits,  Prev: Character Syntax Types,  Up: Character Syntax Types

2.1.4.1 Constituent Characters
..............................

Constituent characters are used in tokens.  A token is a representation
of a number or a symbol.  Examples of constituent characters are letters
and digits.

   Letters in symbol names are sometimes converted to letters in the
opposite case when the name is read; see *note Effect of Readtable Case
on the Lisp Reader::.  Case conversion can be suppressed by the use of
single escape or multiple escape characters.


File: gcl.info,  Node: Constituent Traits,  Next: Invalid Characters,  Prev: Constituent Characters,  Up: Character Syntax Types

2.1.4.2 Constituent Traits
..........................

Every character has one or more constituent traits that define how the
character is to be interpreted by the Lisp reader when the character is
a constituent character.  These constituent traits are alphabetic_2,
digit, package marker, plus sign, minus sign, dot, decimal point, ratio
marker, exponent marker, and invalid.  Figure~2-8 shows the constituent
traits of the standard characters and of certain semi-standard
characters; no mechanism is provided for changing the constituent trait
of a character.  Any character with the alphadigit constituent trait in
that figure is a digit if the current input base is greater than that
character's digit value, otherwise the character is alphabetic_2.  Any
character quoted by a single escape is treated as an alphabetic_2
constituent, regardless of its normal syntax.

 constituent traits         constituent traits                                   
 character                  character   
 ________________________________________________________________________________
 Backspace   invalid        {           alphabetic_2                             
 Tab         invalid*       }           alphabetic_2                             
 Newline     invalid*       +           alphabetic_2, plus sign                  
 Linefeed    invalid*       -           alphabetic_2, minus sign                 
 Page        invalid*       .           alphabetic_2, dot, decimal point         
 Return      invalid*       /           alphabetic_2, ratio marker               
 Space       invalid*       A, a        alphadigit                               
 !           alphabetic_2   B, b        alphadigit                               
 "           alphabetic_2*  C, c        alphadigit                               
 #           alphabetic_2*  D, d        alphadigit, double-float exponent marker 
 $          alphabetic_2   E, e        alphadigit, float exponent marker        
 %           alphabetic_2   F, f        alphadigit, single-float exponent marker 
 &           alphabetic_2   G, g        alphadigit                               
 '           alphabetic_2*  H, h        alphadigit                               
 (           alphabetic_2*  I, i        alphadigit                               
 )           alphabetic_2*  J, j        alphadigit                               
 *           alphabetic_2   K, k        alphadigit                               
 ,           alphabetic_2*  L, l        alphadigit, long-float exponent marker   
 0-9         alphadigit     M, m        alphadigit                               
 :           package marker N, n        alphadigit                               
 ;           alphabetic_2*  O, o        alphadigit                               
 <           alphabetic_2   P, p        alphadigit                               
 =           alphabetic_2   Q, q        alphadigit                               
 >           alphabetic_2   R, r        alphadigit                               
 ?           alphabetic_2   S, s        alphadigit, short-float exponent marker  
 @           alphabetic_2   T, t        alphadigit                               
 [           alphabetic_2   U, u        alphadigit                               
 \           alphabetic_2*  V, v        alphadigit                               
 ]           alphabetic_2   W, w        alphadigit                               
 ^           alphabetic_2   X, x        alphadigit                               
 _           alphabetic_2   Y, y        alphadigit                               
 '           alphabetic_2*  Z, z        alphadigit                               
 |           alphabetic_2*  Rubout      invalid                                  
 ~           alphabetic_2   

     Figure 2-8: Constituent Traits of Standard Characters and Semi-Standard Characters

   The interpretations in this table apply only to characters whose
syntax type is constituent.  Entries marked with an asterisk (*) are
normally shadowed_2 because the indicated characters are of syntax type
whitespace_2, macro character, single escape, or multiple escape; these
constituent traits apply to them only if their syntax types are changed
to constituent.


File: gcl.info,  Node: Invalid Characters,  Next: Macro Characters,  Prev: Constituent Traits,  Up: Character Syntax Types

2.1.4.3 Invalid Characters
..........................

Characters with the constituent trait invalid cannot ever appear in a
token except under the control of a single escape character.  If an
invalid character is encountered while an object is being read, an error
of type reader-error is signaled.  If an invalid character is preceded
by a single escape character, it is treated as an alphabetic_2
constituent instead.


File: gcl.info,  Node: Macro Characters,  Next: Multiple Escape Characters,  Prev: Invalid Characters,  Up: Character Syntax Types

2.1.4.4 Macro Characters
........................

When the Lisp reader encounters a macro character on an input stream,
special parsing of subsequent characters on the input stream is
performed.

   A macro character has an associated function called a reader macro
function that implements its specialized parsing behavior.  An
association of this kind can be established or modified under control of
a conforming program by using the functions set-macro-character and
set-dispatch-macro-character.

   Upon encountering a macro character, the Lisp reader calls its reader
macro function, which parses one specially formatted object from the
input stream.  The function either returns the parsed object, or else it
returns no values to indicate that the characters scanned by the
function are being ignored (e.g., in the case of a comment).  Examples
of macro characters are backquote, single-quote, left-parenthesis, and
right-parenthesis.

   A macro character is either terminating or non-terminating.  The
difference between terminating and non-terminating macro characters lies
in what happens when such characters occur in the middle of a token.  If
a non-terminating macro character occurs in the middle of a token, the
function associated with the non-terminating macro character is not
called, and the non-terminating macro character does not terminate the
token's name; it becomes part of the name as if the macro character were
really a constituent character.  A terminating macro character
terminates any token, and its associated reader macro function is called
no matter where the character appears.  The only non-terminating macro
character in standard syntax is sharpsign.

   If a character is a dispatching macro character C_1, its reader macro
function is a function supplied by the implementation.  This function
reads decimal digit characters until a non-digit C_2 is read.  If any
digits were read, they are converted into a corresponding integer infix
parameter P; otherwise, the infix parameter P is nil.  The terminating
non-digit C_2 is a character (sometimes called a "sub-character" to
emphasize its subordinate role in the dispatching) that is looked up in
the dispatch table associated with the dispatching macro character C_1.
The reader macro function associated with the sub-character C_2 is
invoked with three arguments: the stream, the sub-character C_2, and the
infix parameter P. For more information about dispatch characters, see
the function set-dispatch-macro-character.

   For information about the macro characters that are available in
standard syntax, see *note Standard Macro Characters::.


File: gcl.info,  Node: Multiple Escape Characters,  Next: Examples of Multiple Escape Characters,  Prev: Macro Characters,  Up: Character Syntax Types

2.1.4.5 Multiple Escape Characters
..................................

A pair of multiple escape characters is used to indicate that an
enclosed sequence of characters, including possible macro characters and
whitespace_2 characters, are to be treated as alphabetic_2 characters
with case preserved.  Any single escape and multiple escape characters
that are to appear in the sequence must be preceded by a single escape
character.

   Vertical-bar is a multiple escape character in standard syntax.


File: gcl.info,  Node: Examples of Multiple Escape Characters,  Next: Single Escape Character,  Prev: Multiple Escape Characters,  Up: Character Syntax Types

2.1.4.6 Examples of Multiple Escape Characters
..............................................

      ;; The following examples assume the readtable case of *readtable*
      ;; and *print-case* are both :upcase.
      (eq 'abc 'ABC) =>  true
      (eq 'abc '|ABC|) =>  true
      (eq 'abc 'a|B|c) =>  true
      (eq 'abc '|abc|) =>  false


File: gcl.info,  Node: Single Escape Character,  Next: Examples of Single Escape Characters,  Prev: Examples of Multiple Escape Characters,  Up: Character Syntax Types

2.1.4.7 Single Escape Character
...............................

A single escape is used to indicate that the next character is to be
treated as an alphabetic_2 character with its case preserved, no matter
what the character is or which constituent traits it has.

   Slash is a single escape character in standard syntax.


File: gcl.info,  Node: Examples of Single Escape Characters,  Next: Whitespace Characters,  Prev: Single Escape Character,  Up: Character Syntax Types

2.1.4.8 Examples of Single Escape Characters
............................................

      ;; The following examples assume the readtable case of *readtable*
      ;; and *print-case* are both :upcase.
      (eq 'abc '\A\B\C) =>  true
      (eq 'abc 'a\Bc) =>  true
      (eq 'abc '\ABC) =>  true
      (eq 'abc '\abc) =>  false


File: gcl.info,  Node: Whitespace Characters,  Next: Examples of Whitespace Characters,  Prev: Examples of Single Escape Characters,  Up: Character Syntax Types

2.1.4.9 Whitespace Characters
.............................

Whitespace_2 characters are used to separate tokens.

   Space and newline are whitespace_2 characters in standard syntax.


File: gcl.info,  Node: Examples of Whitespace Characters,  Prev: Whitespace Characters,  Up: Character Syntax Types

2.1.4.10 Examples of Whitespace Characters
..........................................

      (length '(this-that)) =>  1
      (length '(this - that)) =>  3
      (length '(a
                b)) =>  2
      (+ 34) =>  34
      (+ 3 4) =>  7


File: gcl.info,  Node: Reader Algorithm,  Next: Interpretation of Tokens,  Prev: Character Syntax,  Up: Syntax

2.2 Reader Algorithm
====================

This section describes the algorithm used by the Lisp reader to parse
objects from an input character stream, including how the Lisp reader
processes macro characters.

   When dealing with tokens, the reader's basic function is to
distinguish representations of symbols from those of numbers.  When a
token is accumulated, it is assumed to represent a number if it
satisfies the syntax for numbers listed in Figure~2-9.  If it does not
represent a number, it is then assumed to be a potential number if it
satisfies the rules governing the syntax for a potential number.  If a
valid token is neither a representation of a number nor a potential
number, it represents a symbol.

   The algorithm performed by the Lisp reader is as follows:

1.
     If at end of file, end-of-file processing is performed as specified
     in read.  Otherwise, one character, x, is read from the input
     stream, and dispatched according to the syntax type of x to one of
     steps 2 to 7.

2.
     If x is an invalid character, an error of type reader-error is
     signaled.

3.
     If x is a whitespace_2 character, then it is discarded and step 1
     is re-entered.

4.
     If x is a terminating or non-terminating macro character then its
     associated reader macro function is called with two arguments, the
     input stream and x.

     The reader macro function may read characters from the input
     stream; if it does, it will see those characters following the
     macro character.  The Lisp reader may be invoked recursively from
     the reader macro function.

     The reader macro function must not have any side effects other than
     on the input stream; because of backtracking and restarting of the
     read operation, front ends to the Lisp reader (e.g., "editors" and
     "rubout handlers") may cause the reader macro function to be called
     repeatedly during the reading of a single expression in which x
     only appears once.

     The reader macro function may return zero values or one value.  If
     one value is returned, then that value is returned as the result of
     the read operation; the algorithm is done.  If zero values are
     returned, then step 1 is re-entered.

5.
     If x is a single escape character then the next character, y, is
     read, or an error of type end-of-file is signaled if at the end of
     file.  y is treated as if it is a constituent whose only
     constituent trait is alphabetic_2.  y is used to begin a token, and
     step 8 is entered.

6.
     If x is a multiple escape character then a token (initially
     containing no characters) is begun and step 9 is entered.

7.
     If x is a constituent character, then it begins a token.  After the
     token is read in, it will be interpreted either as a Lisp object or
     as being of invalid syntax.  If the token represents an object,
     that object is returned as the result of the read operation.  If
     the token is of invalid syntax, an error is signaled.  If x is a
     character with case, it might be replaced with the corresponding
     character of the opposite case, depending on the readtable case of
     the current readtable, as outlined in *note Effect of Readtable
     Case on the Lisp Reader::.  X is used to begin a token, and step 8
     is entered.

8.
     At this point a token is being accumulated, and an even number of
     multiple escape characters have been encountered.  If at end of
     file, step 10 is entered.  Otherwise, a character, y, is read, and
     one of the following actions is performed according to its syntax
     type:

     *
          If y is a constituent or non-terminating macro character:

          -
               If y is a character with case, it might be replaced with
               the corresponding character of the opposite case,
               depending on the readtable case of the current readtable,
               as outlined in *note Effect of Readtable Case on the Lisp
               Reader::.
          -
               Y is appended to the token being built.
          -
               Step 8 is repeated.

     *
          If y is a single escape character, then the next character, z,
          is read, or an error of type end-of-file is signaled if at end
          of file.  Z is treated as if it is a constituent whose only
          constituent trait is alphabetic_2.  Z is appended to the token
          being built, and step 8 is repeated.

     *
          If y is a multiple escape character, then step 9 is entered.

     *
          If y is an invalid character, an error of type reader-error is
          signaled.

     *
          If y is a terminating macro character, then it terminates the
          token.  First the character y is unread (see unread-char), and
          then step 10 is entered.

     *
          If y is a whitespace_2 character, then it terminates the
          token.  First the character y is unread if appropriate (see
          read-preserving-whitespace), and then step 10 is entered.

9.
     At this point a token is being accumulated, and an odd number of
     multiple escape characters have been encountered.  If at end of
     file, an error of type end-of-file is signaled.  Otherwise, a
     character, y, is read, and one of the following actions is
     performed according to its syntax type:

     *
          If y is a constituent, macro, or whitespace_2 character, y is
          treated as a constituent whose only constituent trait is
          alphabetic_2.  Y is appended to the token being built, and
          step 9 is repeated.

     *
          If y is a single escape character, then the next character, z,
          is read, or an error of type end-of-file is signaled if at end
          of file.  Z is treated as a constituent whose only constituent
          trait is alphabetic_2.  Z is appended to the token being
          built, and step 9 is repeated.

     *
          If y is a multiple escape character, then step 8 is entered.

     *
          If y is an invalid character, an error of type reader-error is
          signaled.

10.
     An entire token has been accumulated.  The object represented by
     the token is returned as the result of the read operation, or an
     error of type reader-error is signaled if the token is not of valid
     syntax.


File: gcl.info,  Node: Interpretation of Tokens,  Next: Standard Macro Characters,  Prev: Reader Algorithm,  Up: Syntax

2.3 Interpretation of Tokens
============================

* Menu:

* Numbers as Tokens::
* Constructing Numbers from Tokens::
* The Consing Dot::
* Symbols as Tokens::
* Valid Patterns for Tokens::
* Package System Consistency Rules::


File: gcl.info,  Node: Numbers as Tokens,  Next: Constructing Numbers from Tokens,  Prev: Interpretation of Tokens,  Up: Interpretation of Tokens

2.3.1 Numbers as Tokens
-----------------------

When a token is read, it is interpreted as a number or symbol.  The
token is interpreted as a number if it satisfies the syntax for numbers
specified in Figure 2-9.

 numeric-token ::= !integer | !ratio | !float                                              
 integer       ::= [sign] {decimal-digit}^+ decimal-point | [sign] {digit}^+               
 ratio         ::= [sign] {digit}^+ slash {digit}^+                                        
 float         ::= [sign] {decimal-digit}* decimal-point {decimal-digit}^+ [!exponent]   
                   | [sign] {decimal-digit}^+ [decimal-point {decimal-digit}*] !exponent 
 exponent      ::= exponent-marker [sign] {digit}^+                                        
 sign--a sign.
 slash--a slash
 decimal-point--a dot.
 exponent-marker--an exponent marker.
 decimal-digit--a digit in radix 10.
 digit--a digit in the current input radix.

     Figure 2-9: Syntax for Numeric Tokens

* Menu:

* Potential Numbers as Tokens::
* Escape Characters and Potential Numbers::
* Examples of Potential Numbers::


File: gcl.info,  Node: Potential Numbers as Tokens,  Next: Escape Characters and Potential Numbers,  Prev: Numbers as Tokens,  Up: Numbers as Tokens

2.3.1.1 Potential Numbers as Tokens
...................................

To allow implementors and future Common Lisp standards to extend the
syntax of numbers, a syntax for potential numbers is defined that is
more general than the syntax for numbers.  A token is a potential number
if it satisfies all of the following requirements:

1.
     The token consists entirely of digits, signs, ratio markers,
     decimal points (.), extension characters (^ or _), and number
     markers.  A number marker is a letter.  Whether a letter may be
     treated as a number marker depends on context, but no letter that
     is adjacent to another letter may ever be treated as a number
     marker.  Exponent markers are number markers.

2.
     The token contains at least one digit.  Letters may be considered
     to be digits, depending on the current input base, but only in
     tokens containing no decimal points.

3.
     The token begins with a digit, sign, decimal point, or extension
     character,

     [Reviewer Note by Barmar: This section is unnecessary because the
     first bullet already omits discussion of a colon (package marker).]
     but not a package marker.  The syntax involving a leading package
     marker followed by a potential number is not well-defined.  The
     consequences of the use of notation such as :1, :1/2, and :2^3 in a
     position where an expression appropriate for read is expected are
     unspecified.

4.
     The token does not end with a sign.

   If a potential number has number syntax, a number of the appropriate
type is constructed and returned, if the number is representable in an
implementation.  A number will not be representable in an implementation
if it is outside the boundaries set by the implementation-dependent
constants for numbers.  For example, specifying too large or too small
an exponent for a float may make the number impossible to represent in
the implementation.  A ratio with denominator zero (such as -35/000) is
not represented in any implementation.  When a token with the syntax of
a number cannot be converted to an internal number, an error of type
reader-error is signaled.  An error must not be signaled for specifying
too many significant digits for a float; a truncated or rounded value
should be produced.

   If there is an ambiguity as to whether a letter should be treated as
a digit or as a number marker, the letter is treated as a digit.


File: gcl.info,  Node: Escape Characters and Potential Numbers,  Next: Examples of Potential Numbers,  Prev: Potential Numbers as Tokens,  Up: Numbers as Tokens

2.3.1.2 Escape Characters and Potential Numbers
...............................................

A potential number cannot contain any escape characters.  An escape
character robs the following character of all syntactic qualities,
forcing it to be strictly alphabetic_2 and therefore unsuitable for use
in a potential number.  For example, all of the following
representations are interpreted as symbols, not numbers:

      \256   25\64   1.0\E6   |100|   3\.14159   |3/4|   3\/4   5||

   In each case, removing the escape character (or characters) would
cause the token to be a potential number.


File: gcl.info,  Node: Examples of Potential Numbers,  Prev: Escape Characters and Potential Numbers,  Up: Numbers as Tokens

2.3.1.3 Examples of Potential Numbers
.....................................

As examples, the tokens in Figure 2-10 are potential numbers, but they
are not actually numbers, and so are reserved tokens; a conforming
implementation is permitted, but not required, to define their meaning.

  1b5000                       777777q                1.7J  -3/4+6.7J  12/25/83  
  27^19                      3^4/5                6//7  3.1.2.6    ^-43^   
  3.141_592_653_589_793_238_4  -3.7+2.6i-6.17j+19.6k  

                     Figure 2-10: Examples of reserved tokens                   


   The tokens in Figure 2-11 are not potential numbers; they are always
treated as symbols:

  /     /5     +  1+  1-     
  foo+  ab.cd  _  ^   ^/-  

  Figure 2-11: Examples of symbols


   The tokens in Figure 2-12 are potential numbers if the current input
base is 16, but they are always treated as symbols if the current input
base is 10.

  bad-face  25-dec-83  a/b  fad_cafe  f^ 

  Figure 2-12: Examples of symbols or potential numbers



File: gcl.info,  Node: Constructing Numbers from Tokens,  Next: The Consing Dot,  Prev: Numbers as Tokens,  Up: Interpretation of Tokens

2.3.2 Constructing Numbers from Tokens
--------------------------------------

A real is constructed directly from a corresponding numeric token; see
Figure~2-9.

   A complex is notated as a #C (or #c) followed by a list of two reals;
see *note Sharpsign C::.

   The reader macros #B, #O, #X, and #R may also be useful in
controlling the input radix in which rationals are parsed; see *note
Sharpsign B::, *note Sharpsign O::, *note Sharpsign X::, and *note
Sharpsign R::.

   This section summarizes the full syntax for numbers.

* Menu:

* Syntax of a Rational::
* Syntax of an Integer::
* Syntax of a Ratio::
* Syntax of a Float::
* Syntax of a Complex::


File: gcl.info,  Node: Syntax of a Rational,  Next: Syntax of an Integer,  Prev: Constructing Numbers from Tokens,  Up: Constructing Numbers from Tokens

2.3.2.1 Syntax of a Rational
............................


File: gcl.info,  Node: Syntax of an Integer,  Next: Syntax of a Ratio,  Prev: Syntax of a Rational,  Up: Constructing Numbers from Tokens

2.3.2.2 Syntax of an Integer
............................

Integers can be written as a sequence of digits, optionally preceded by
a sign and optionally followed by a decimal point; see Figure~2-9.  When
a decimal point is used, the digits are taken to be in radix 10; when no
decimal point is used, the digits are taken to be in radix given by the
current input base.

   For information on how integers are printed, see *note Printing
Integers::.


File: gcl.info,  Node: Syntax of a Ratio,  Next: Syntax of a Float,  Prev: Syntax of an Integer,  Up: Constructing Numbers from Tokens

2.3.2.3 Syntax of a Ratio
.........................

Ratios can be written as an optional sign followed by two non-empty
sequences of digits separated by a slash; see Figure~2-9.  The second
sequence may not consist entirely of zeros.  Examples of ratios are in
Figure 2-13.

  2/3                 ;This is in canonical form                  
  4/6                 ;A non-canonical form for 2/3               
  -17/23              ;A ratio preceded by a sign                 
  -30517578125/32768  ;This is (-5/2)^15                        
  10/5                ;The canonical form for this is 2           
  #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  

                  Figure 2-13: Examples of Ratios                


   [Reviewer Note by Barmar: #o, #3r, #X, and #x mentioned above are not
in the syntax rules defined just above that.]

   For information on how ratios are printed, see *note Printing
Ratios::.


File: gcl.info,  Node: Syntax of a Float,  Next: Syntax of a Complex,  Prev: Syntax of a Ratio,  Up: Constructing Numbers from Tokens

2.3.2.4 Syntax of a Float
.........................

Floats can be 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.  If no exponent specifier is present, or
if the exponent marker e (or E) is used, then the format specified by
*read-default-float-format* is used.  See Figure~2-9.

   An implementation may provide one or more kinds of float that
collectively make up the type float.  The letters s, f, d, and l (or
their respective uppercase equivalents) explicitly specify the use of
the types short-float, single-float, double-float, and long-float,
respectively.

   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.

   Figure 2-14 contains examples of notations for floats:

  0.0       ;Floating-point zero in default format                          
  0E0       ;As input, this is also floating-point zero in default format.  
            ;As output, this would appear as 0.0.                           
  0e0       ;As input, this is also floating-point zero in default format.  
            ;As output, this would appear as 0.0.                           
  -.0       ;As input, this might be a zero or a minus zero,                
            ; depending on whether the implementation supports              
            ; a distinct minus zero.                                        
            ;As output, 0.0 is zero and -0.0 is minus zero.                 
  0.        ;On input, the integer zero--not a floating-point number!      
            ;Whether this appears as 0 or 0. on output depends              
            ;on the value of *print-radix*.                                 
  0.0s0     ;A floating-point zero in short format                          
  0s0       ;As input, this is a floating-point zero in short format.       
            ;As output, such a zero would appear as 0.0s0                   
            ; (or as 0.0 if short-float was the default format).            
  6.02E+23  ;Avogadro's number, in default format                           
  602E+21   ;Also Avogadro's number, in default format                      

               Figure 2-14: Examples of Floating-point numbers             


   For information on how floats are printed, see *note Printing
Floats::.


File: gcl.info,  Node: Syntax of a Complex,  Prev: Syntax of a Float,  Up: Constructing Numbers from Tokens

2.3.2.5 Syntax of a Complex
...........................

A complex has a Cartesian structure, with a real part and an imaginary
part each of which is a

   real.

   The parts of a complex are not necessarily floats but both parts must
be of the same type:

   [Editorial Note by KMP: This is not the same as saying they must be
the same type.  Maybe we mean they are of the same 'precision' or
'format'? 	GLS had suggestions which are not yet merged.]  either both
are rationals, or both are of the same float subtype.  When constructing
a complex, if the specified parts are not the same type, the parts are
converted to be the same type internally (i.e., the rational part is
converted to a float).  An object of type (complex rational) is
converted internally and represented thereafter as a rational if its
imaginary part is an integer whose value is 0.

   For further information, see *note Sharpsign C:: and *note Printing
Complexes::.


File: gcl.info,  Node: The Consing Dot,  Next: Symbols as Tokens,  Prev: Constructing Numbers from Tokens,  Up: Interpretation of Tokens

2.3.3 The Consing Dot
---------------------

If a token consists solely of dots (with no escape characters), then an
error of type reader-error is signaled, except in one circumstance: if
the token is a single dot and appears in a situation where dotted pair
notation permits a dot, then it is accepted as part of such syntax and
no error is signaled.  See *note Left-Parenthesis::.


File: gcl.info,  Node: Symbols as Tokens,  Next: Valid Patterns for Tokens,  Prev: The Consing Dot,  Up: Interpretation of Tokens

2.3.4 Symbols as Tokens
-----------------------

Any token that is not a potential number, does not contain a package
marker, and does not consist entirely of dots will always be interpreted
as a symbol.  Any token that is a potential number but does not fit the
number syntax is a reserved token and has an implementation-dependent
interpretation.  In all other cases, the token is construed to be the
name of a symbol.

   Examples of the printed representation of symbols are in Figure 2-15.
For presentational simplicity, these examples assume that the readtable
case of the current readtable is :upcase.

  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 hyphen 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.       
  file.rel.43     This symbol has periods in its name.             
  \(              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 possible short float approximation to \pi.     

  Figure 2-15: Examples of the printed representation of symbols (Part 1 of 2)


  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.            
                         Parentheses and two spaces in it.       
  \(\b^2\)\ -\4*\a*\c  The name is (b^2) - 4*a*c.            
                         Letters explicitly lowercase.           
  |"|                    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.                     
  |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.            
                         Parentheses and two spaces in it.       
  |(b^2) - 4*a*c|      The name is (b^2) - 4*a*c.            

  Figure 2-16: Examples of the printed representation of symbols (Part 2 of 2)


   In the process of parsing a symbol, it is implementation-dependent
which implementation-defined attributes are removed from the characters
forming a token that represents a symbol.

   When parsing the syntax for a symbol, the Lisp reader looks up the
name of that symbol in the current package.  This lookup may involve
looking in other packages whose external symbols are inherited by the
current package.  If the name is found, the corresponding symbol is
returned.  If the name is not found (that is, there is no symbol of that
name accessible in the current package), a new symbol is created and is
placed in the current package as an internal symbol.  The current
package becomes the owner (home package) of the symbol, and the symbol
becomes interned in the current package.  If the name is later read
again while this same package is current, the same symbol will be found
and returned.


File: gcl.info,  Node: Valid Patterns for Tokens,  Next: Package System Consistency Rules,  Prev: Symbols as Tokens,  Up: Interpretation of Tokens

2.3.5 Valid Patterns for Tokens
-------------------------------

The valid patterns for tokens are summarized in Figure 2-17.

  nnnnn              a number                                           
  xxxxx              a symbol in the current package                    
  :xxxxx             a symbol in the the KEYWORD package                
  ppppp:xxxxx        an external symbol in the ppppp package            
  ppppp::xxxxx       a (possibly internal) symbol in the ppppp package  
  :nnnnn             undefined                                          
  ppppp:nnnnn        undefined                                          
  ppppp::nnnnn       undefined                                          
  ::aaaaa            undefined                                          
  aaaaa:             undefined                                          
  aaaaa:aaaaa:aaaaa  undefined                                          

                 Figure 2-17: Valid patterns for tokens                


   Note that nnnnn has number syntax, neither xxxxx nor ppppp has number
syntax, and aaaaa has any syntax.

   A summary of rules concerning package markers follows.  In each case,
examples are offered to illustrate the case; for presentational
simplicity, the examples assume that the readtable case of the current
readtable is :upcase.

1.
     If there is a single package marker, and it occurs at the beginning
     of the token, then the token is interpreted as a symbol in the
     KEYWORD package.  It also sets the symbol-value of the
     newly-created symbol to that same symbol so that the symbol will
     self-evaluate.

     For example, :bar, when read, interns BAR as an external symbol in
     the KEYWORD package.

2.
     If there is a single package marker not at the beginning or end of
     the token, then it divides the token into two parts.  The first
     part specifies a package; the second part is the name of an
     external symbol available in that package.

     For example, foo:bar, when read, looks up BAR among the external
     symbols of the package named FOO.

3.
     If there are two adjacent package markers not at the beginning or
     end of the token, then they divide the token into two parts.  The
     first part specifies a package; the second part is the name of a
     symbol within that package (possibly an internal symbol).

     For example, foo::bar, when read, interns BAR in the package named
     FOO.

4.
     If the token contains no package markers, and does not have
     potential number syntax, then the entire token is the name of the
     symbol.  The symbol is looked up in the current package.

     For example, bar, when read, interns BAR in the current package.

5.
     The consequences are unspecified if any other pattern of package
     markers in a token is used.  All other uses of package markers
     within names of symbols are not defined by this standard but are
     reserved for implementation-dependent use.

   For example, assuming the readtable case of the current readtable is
:upcase, editor:buffer refers to the external symbol named BUFFER
present in the package named editor, regardless of whether there is a
symbol named BUFFER in the current package.  If there is no package
named editor, or if no symbol named BUFFER is present in editor, or if
BUFFER is not exported by editor, the reader signals a correctable
error.  If editor::buffer is seen, the effect is exactly the same as
reading buffer with the EDITOR package being the current package.


File: gcl.info,  Node: Package System Consistency Rules,  Prev: Valid Patterns for Tokens,  Up: Interpretation of Tokens

2.3.6 Package System Consistency Rules
--------------------------------------

The following rules apply to the package system as long as the value of
*package* is not changed:

Read-read consistency
     Reading the same symbol name always results in the same symbol.

Print-read consistency
     An interned symbol always prints as a sequence of characters that,
     when read back in, yields the same symbol.

     For information about how the Lisp printer treats symbols, see
     *note Printing Symbols::.

Print-print consistency
     If two interned symbols are not the same, then their printed
     representations will be different sequences of characters.

   These rules are true regardless of any implicit interning.  As long
as the current package is not changed, results are reproducible
regardless of the order of loading files or the exact history of what
symbols were typed in when.  If the value of *package* is changed and
then changed back to the previous value, consistency is maintained.  The
rules can be violated by changing the value of *package*, forcing a
change to symbols or to packages or to both by continuing from an error,
or calling one of the following functions: unintern, unexport, shadow,
shadowing-import, or unuse-package.

   An inconsistency only applies if one of the restrictions is violated
between two of the named symbols.  shadow, unexport, unintern, and
shadowing-import can only affect the consistency of symbols with the
same names (under string=) as the ones supplied as arguments.


File: gcl.info,  Node: Standard Macro Characters,  Prev: Interpretation of Tokens,  Up: Syntax

2.4 Standard Macro Characters
=============================

If the reader encounters a macro character, then its associated reader
macro function is invoked and may produce an object to be returned.
This function may read the characters following the macro character in
the stream in any syntax and return the object represented by that
syntax.

   Any character can be made to be a macro character.  The macro
characters defined initially in a conforming implementation include the
following:

* Menu:

* Left-Parenthesis::
* Right-Parenthesis::
* Single-Quote::
* Semicolon::
* Double-Quote::
* Backquote::
* Comma::
* Sharpsign::
* Re-Reading Abbreviated Expressions::


File: gcl.info,  Node: Left-Parenthesis,  Next: Right-Parenthesis,  Prev: Standard Macro Characters,  Up: Standard Macro Characters

2.4.1 Left-Parenthesis
----------------------

The left-parenthesis initiates reading of a list.  read is called
recursively to read successive objects until a right parenthesis is
found in the input stream.  A list of the objects read is returned.
Thus

      (a b c)

   is read as a list of three objects (the symbols a, b, and c).  The
right parenthesis need not immediately follow the printed representation
of the last object; whitespace_2 characters and comments may precede it.

   If no objects precede the right parenthesis, it reads as a list of
zero objects (the empty list).

   If a token that is just a dot not immediately preceded by an escape
character is read after some object then exactly one more object must
follow the dot, possibly preceded or followed by whitespace_2 or a
comment, followed by the right parenthesis:

      (a b c . d)

   This means that the cdr of the last cons in the list is not nil, but
rather the object whose representation followed the dot.  The above
example might have been the result of evaluating

      (cons 'a (cons 'b (cons 'c 'd)))

   Similarly,

      (cons 'this-one 'that-one) =>  (this-one . that-one)

   It is permissible for the object following the dot to be a list:

      (a b c d . (e f . (g))) == (a b c d e f g)

   For information on how the Lisp printer prints lists and conses, see
*note Printing Lists and Conses::.


File: gcl.info,  Node: Right-Parenthesis,  Next: Single-Quote,  Prev: Left-Parenthesis,  Up: Standard Macro Characters

2.4.2 Right-Parenthesis
-----------------------

The right-parenthesis is invalid except when used in conjunction with
the left parenthesis character.  For more information, see *note Reader
Algorithm::.


File: gcl.info,  Node: Single-Quote,  Next: Semicolon,  Prev: Right-Parenthesis,  Up: Standard Macro Characters

2.4.3 Single-Quote
------------------

Syntax: '<<exp>>

   A single-quote introduces an expression to be "quoted."  Single-quote
followed by an expression exp is treated by the Lisp reader as an
abbreviation for and is parsed identically to the expression (quote
exp).  See the special operator quote.

* Menu:

* Examples of Single-Quote::


File: gcl.info,  Node: Examples of Single-Quote,  Prev: Single-Quote,  Up: Single-Quote

2.4.3.1 Examples of Single-Quote
................................

      'foo =>  FOO
      ''foo =>  (QUOTE FOO)
      (car ''foo) =>  QUOTE


File: gcl.info,  Node: Semicolon,  Next: Double-Quote,  Prev: Single-Quote,  Up: Standard Macro Characters

2.4.4 Semicolon
---------------

Syntax: ;<<text>>

   A semicolon introduces characters that are to be ignored, such as
comments.  The semicolon and all characters up to and including the next
newline or end of file are ignored.

* Menu:

* Examples of Semicolon::
* Notes about Style for Semicolon::
* Use of Single Semicolon::
* Use of Double Semicolon::
* Use of Triple Semicolon::
* Use of Quadruple Semicolon::
* Examples of Style for Semicolon::


File: gcl.info,  Node: Examples of Semicolon,  Next: Notes about Style for Semicolon,  Prev: Semicolon,  Up: Semicolon

2.4.4.1 Examples of Semicolon
.............................

      (+ 3 ; three
         4)
     =>  7


File: gcl.info,  Node: Notes about Style for Semicolon,  Next: Use of Single Semicolon,  Prev: Examples of Semicolon,  Up: Semicolon

2.4.4.2 Notes about Style for Semicolon
.......................................

Some text editors make assumptions about desired indentation based on
the number of semicolons that begin a comment.  The following style
conventions are common, although not by any means universal.


File: gcl.info,  Node: Use of Single Semicolon,  Next: Use of Double Semicolon,  Prev: Notes about Style for Semicolon,  Up: Semicolon

2.4.4.3 Use of Single Semicolon
...............................

Comments that begin with a single semicolon are all aligned to the same
column at the right (sometimes called the "comment column").  The text
of such a comment generally applies only to the line on which it
appears.  Occasionally two or three contain a single sentence together;
this is sometimes indicated by indenting all but the first with an
additional space (after the semicolon).


File: gcl.info,  Node: Use of Double Semicolon,  Next: Use of Triple Semicolon,  Prev: Use of Single Semicolon,  Up: Semicolon

2.4.4.4 Use of Double Semicolon
...............................

Comments that begin with a double semicolon are all aligned to the same
level of indentation as a form would be at that same position in the
code.  The text of such a comment usually describes the state of the
program at the point where the comment occurs, the code which follows
the comment, or both.


File: gcl.info,  Node: Use of Triple Semicolon,  Next: Use of Quadruple Semicolon,  Prev: Use of Double Semicolon,  Up: Semicolon

2.4.4.5 Use of Triple Semicolon
...............................

Comments that begin with a triple semicolon are all aligned to the left
margin.  Usually they are used prior to a definition or set of
definitions, rather than within a definition.


File: gcl.info,  Node: Use of Quadruple Semicolon,  Next: Examples of Style for Semicolon,  Prev: Use of Triple Semicolon,  Up: Semicolon

2.4.4.6 Use of Quadruple Semicolon
..................................

Comments that begin with a quadruple semicolon are all aligned to the
left margin, and generally contain only a short piece of text that serve
as a title for the code which follows, and might be used in the header
or footer of a program that prepares code for presentation as a hardcopy
document.


File: gcl.info,  Node: Examples of Style for Semicolon,  Prev: Use of Quadruple Semicolon,  Up: Semicolon

2.4.4.7 Examples of Style for Semicolon
.......................................

     ;;;; Math Utilities

     ;;; FIB computes the the Fibonacci function in the traditional
     ;;; recursive way.

     (defun fib (n)
       (check-type n integer)
       ;; At this point we're sure we have an integer argument.
       ;; Now we can get down to some serious computation.
       (cond ((< n 0)
              ;; Hey, this is just supposed to be a simple example.
              ;; Did you really expect me to handle the general case?
              (error "FIB got ~D as an argument." n))
             ((< n 2) n)             ;fib[0]=0 and fib[1]=1
             ;; The cheap cases didn't work.
             ;; Nothing more to do but recurse.
             (t (+ (fib (- n 1))     ;The traditional formula
                   (fib (- n 2)))))) ; is fib[n-1]+fib[n-2].


File: gcl.info,  Node: Double-Quote,  Next: Backquote,  Prev: Semicolon,  Up: Standard Macro Characters

2.4.5 Double-Quote
------------------

Syntax: "<<text>>"

   The double-quote is used to begin and end a string.  When a
double-quote is encountered, characters are read from the input stream
and accumulated until another double-quote is encountered.  If a single
escape character is seen, the single escape character is discarded, the
next character is accumulated, and accumulation continues.  The
accumulated characters up to but not including the matching double-quote
are made into a simple string and returned.

   It is implementation-dependent which attributes of the accumulated
characters are removed in this process.

   Examples of the use of the double-quote character are in Figure 2-18.

  "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                

          Figure 2-18: Examples of the use of double-quote         


   Note that to place a single escape character or a double-quote into a
string, such a character must be preceded by a single escape character.
Note, too, that a multiple escape character need not be quoted by a
single escape character within a string.

   For information on how the Lisp printer prints strings, see *note
Printing Strings::.


File: gcl.info,  Node: Backquote,  Next: Comma,  Prev: Double-Quote,  Up: Standard Macro Characters

2.4.6 Backquote
---------------

The backquote introduces a template of a data structure to be built.
For example, writing

      `(cond ((numberp ,x) ,@y) (t (print ,x) ,@y))

   is roughly equivalent to writing

      (list 'cond
            (cons (list 'numberp x) y)
            (list* 't (list 'print x) y))

   Where a comma occurs in the template, the expression following the
comma is to be evaluated to produce an object to be inserted at that
point.  Assume b has the value 3, for example, then evaluating the form
denoted by `(a b ,b ,(+ b 1) b) produces the result (a b 3 4 b).

   If a comma is immediately followed by an at-sign, then the form
following the at-sign is evaluated to produce a list of objects.  These
objects are then "spliced" into place in the template.  For example, if
x has the value (a b c), then

      `(x ,x ,@x foo ,(cadr x) bar ,(cdr x) baz ,@(cdr x))
     =>  (x (a b c) a b c foo b bar (b c) baz b c)

   The backquote syntax can be summarized formally as follows.

*
     `basic is the same as 'basic, that is, (quote basic), for any
     expression basic that is not a list or a general vector.

*
     `,form is the same as form, for any form, provided that the
     representation of form does not begin with at-sign or dot.  (A
     similar caveat holds for all occurrences of a form after a comma.)

*
     `,@form has undefined consequences.

*
     `(x1 x2 x3 ... xn . atom) may be interpreted to mean

           (append [ x1 ] [ x2 ] [ x3 ] ... [ xn ] (quote atom))

     where the brackets are used to indicate a transformation of an xj
     as follows:

     -
          [form] is interpreted as (list `form), which contains a
          backquoted form that must then be further interpreted.

     -
          [,form] is interpreted as (list form).

     -
          [,@form] is interpreted as form.

*
     `(x1 x2 x3 ... xn) may be interpreted to mean the same as the
     backquoted form `(x1 x2 x3 ... xn . nil), thereby reducing it to
     the previous case.

*
     `(x1 x2 x3 ... xn . ,form) may be interpreted to mean

           (append [ x1 ] [ x2 ] [ x3 ] ... [ xn ] form)

     where the brackets indicate a transformation of an xj as described
     above.

*
     `(x1 x2 x3 ... xn . ,@form) has undefined consequences.

*
     `#(x1 x2 x3 ... xn) may be interpreted to mean (apply #'vector `(x1
     x2 x3 ... xn)).

   Anywhere ",@" may be used, the syntax ",." may be used instead to
indicate that it is permissible to operate destructively on the list
structure produced by the form following the ",." (in effect, to use
nconc instead of append).

   If the backquote syntax is nested, the innermost backquoted form
should be expanded first.  This means that if several commas occur in a
row, the leftmost one belongs to the innermost backquote.

   An implementation is free to interpret a backquoted form F_1 as any
form F_2 that, when evaluated, will produce a result that is the same
under equal as the result implied by the above definition, provided that
the side-effect behavior of the substitute form F_2 is also consistent
with the description given above.  The constructed copy of the template
might or might not share list structure with the template itself.  As an
example, the above definition implies that

      `((,a b) ,c ,@d)

   will be interpreted as if it were

      (append (list (append (list a) (list 'b) 'nil)) (list c) d 'nil)

   but it could also be legitimately interpreted to mean any of the
following:

      (append (list (append (list a) (list 'b))) (list c) d)
      (append (list (append (list a) '(b))) (list c) d)
      (list* (cons a '(b)) c d)
      (list* (cons a (list 'b)) c d)
      (append (list (cons a '(b))) (list c) d)
      (list* (cons a '(b)) c (copy-list d))

* Menu:

* Notes about Backquote::


File: gcl.info,  Node: Notes about Backquote,  Prev: Backquote,  Up: Backquote

2.4.6.1 Notes about Backquote
.............................

Since the exact manner in which the Lisp reader will parse an expression
involving the backquote reader macro is not specified, an implementation
is free to choose any representation that preserves the semantics
described.

   Often an implementation will choose a representation that facilitates
pretty printing of the expression, so that (pprint `(a ,b)) will display
`(a ,b) and not, for example, (list 'a b).  However, this is not a
requirement.

   Implementors who have no particular reason to make one choice or
another might wish to refer to IEEE Standard for the Scheme Programming
Language, which identifies a popular choice of representation for such
expressions that might provide useful to be useful compatibility for
some user communities.  There is no requirement, however, that any
conforming implementation use this particular representation.  This
information is provided merely for cross-reference purposes.


File: gcl.info,  Node: Comma,  Next: Sharpsign,  Prev: Backquote,  Up: Standard Macro Characters

2.4.7 Comma
-----------

The comma is part of the backquote syntax; see *note Backquote::.  Comma
is invalid if used other than inside the body of a backquote expression
as described above.


File: gcl.info,  Node: Sharpsign,  Next: Re-Reading Abbreviated Expressions,  Prev: Comma,  Up: Standard Macro Characters

2.4.8 Sharpsign
---------------

Sharpsign is a non-terminating dispatching macro character.  It reads an
optional sequence of digits and then one more character, and uses that
character to select a function to run as a reader macro function.

   The standard syntax includes constructs introduced by the #
character.  The syntax of these constructs is as follows: a character
that identifies the type of construct is followed by arguments in some
form.  If the character is a letter, its case is not important; #O and
#o are considered to be equivalent, for example.

   Certain # constructs allow an unsigned decimal number to appear
between the # and the character.

   The reader macros associated with the dispatching macro character #
are described later in this section and summarized in Figure 2-19.

  dispatch char  purpose                  dispatch char  purpose                
  Backspace      signals error            {              undefined*             
  Tab            signals error            }              undefined*             
  Newline        signals error            +              read-time conditional  
  Linefeed       signals error            -              read-time conditional  
  Page           signals error            .              read-time evaluation   
  Return         signals error            /              undefined              
  Space          signals error            A, a           array                  
  !              undefined*               B, b           binary rational        
  "              undefined                C, c           complex number         
  #              reference to = label     D, d           undefined              
  $             undefined                E, e           undefined              
  %              undefined                F, f           undefined              
  &              undefined                G, g           undefined              
  '              function abbreviation    H, h           undefined              
  (              simple vector            I, i           undefined              
  )              signals error            J, j           undefined              
  *              bit vector               K, k           undefined              
  ,              undefined                L, l           undefined              
  :              uninterned symbol        M, m           undefined              
  ;              undefined                N, n           undefined              
  <              signals error            O, o           octal rational         
  =              labels following object  P, p           pathname               
  >              undefined                Q, q           undefined              
  ?              undefined*               R, r           radix-n rational       
  @              undefined                S, s           structure              
  [              undefined*               T, t           undefined              
  \              character object         U, u           undefined              
  ]              undefined*               V, v           undefined              
  ^            undefined                W, w           undefined              
  _              undefined                X, x           hexadecimal rational   
  '              undefined                Y, y           undefined              
  |              balanced comment         Z, z           undefined              
  ~              undefined                Rubout         undefined              

           Figure 2-19: Standard # Dispatching Macro Character Syntax         


   The combinations marked by an asterisk (*) are explicitly reserved to
the user.  No conforming implementation defines them.

   Note also that digits do not appear in the preceding table.  This is
because the notations #0, #1, ..., #9 are reserved for another purpose
which occupies the same syntactic space.  When a digit follows a
sharpsign, it is not treated as a dispatch character.  Instead, an
unsigned integer argument is accumulated and passed as an argument to
the reader macro for the character that follows the digits.  For
example, #2A((1 2) (3 4)) is a use of #A with an argument of 2.

* Menu:

* Sharpsign Backslash::
* Sharpsign Single-Quote::
* Sharpsign Left-Parenthesis::
* Sharpsign Asterisk::
* Examples of Sharpsign Asterisk::
* Sharpsign Colon::
* Sharpsign Dot::
* Sharpsign B::
* Sharpsign O::
* Sharpsign X::
* Sharpsign R::
* Sharpsign C::
* Sharpsign A::
* Sharpsign S::
* Sharpsign P::
* Sharpsign Equal-Sign::
* Sharpsign Sharpsign::
* Sharpsign Plus::
* Sharpsign Minus::
* Sharpsign Vertical-Bar::
* Examples of Sharpsign Vertical-Bar::
* Notes about Style for Sharpsign Vertical-Bar::
* Sharpsign Less-Than-Sign::
* Sharpsign Whitespace::
* Sharpsign Right-Parenthesis::


File: gcl.info,  Node: Sharpsign Backslash,  Next: Sharpsign Single-Quote,  Prev: Sharpsign,  Up: Sharpsign

2.4.8.1 Sharpsign Backslash
...........................

Syntax: #\<<x>>

   When the token x is a single character long, this parses as the
literal character char.  Uppercase and lowercase letters are
distinguished after #\; #\A and #\a denote different character objects.
Any single character works after #\, even those that are normally
special to read, such as left-parenthesis and right-parenthesis.

   In the single character case, the x must be followed by a
non-constituent character.  After #\ is read, the reader backs up over
the slash and then reads a token, treating the initial slash as a single
escape character (whether it really is or not in the current readtable).

   When the token x is more than one character long, the x must have the
syntax of a symbol with no embedded package markers.  In this case, the
sharpsign backslash notation parses as the character whose name is
(string-upcase x); see *note Character Names::.

   For information about how the Lisp printer prints character objects,
see *note Printing Characters::.


File: gcl.info,  Node: Sharpsign Single-Quote,  Next: Sharpsign Left-Parenthesis,  Prev: Sharpsign Backslash,  Up: Sharpsign

2.4.8.2 Sharpsign Single-Quote
..............................

Any expression preceded by #' (sharpsign followed by single-quote), as
in #'expression, is treated by the Lisp reader as an abbreviation for
and parsed identically to the expression (function expression).  See
function.  For example,

     (apply #'+ l) == (apply (function +) l)


File: gcl.info,  Node: Sharpsign Left-Parenthesis,  Next: Sharpsign Asterisk,  Prev: Sharpsign Single-Quote,  Up: Sharpsign

2.4.8.3 Sharpsign Left-Parenthesis
..................................

#( and ) are used to notate a simple vector.

   If an unsigned decimal integer appears between the # and (, it
specifies explicitly the length of the vector.  The consequences are
undefined if the number of objects specified before the closing )
exceeds the unsigned decimal integer.  If the number of objects supplied
before the closing ) is less than the unsigned decimal integer but
greater than zero, the last object is used to fill all remaining
elements of the vector.

   [Editorial Note by Barmar: This should say "signals...".]  The
consequences are undefined if the unsigned decimal integer is non-zero
and number of objects supplied before the closing ) is zero.  For
example,

      #(a b c c c c)
      #6(a b c c c c)
      #6(a b c)
      #6(a b c c)

   all mean the same thing: a vector of length 6 with elements a, b, and
four occurrences of c.  Other examples follow:

      #(a b c)               ;A vector of length 3
      #(2 3 5 7 11 13 17 19 23 29 31 37 41 43 47)
                             ;A vector containing the primes below 50
      #()                    ;An empty vector

   The notation #() denotes an empty vector, as does #0().

   For information on how the Lisp printer prints vectors, see *note
Printing Strings::, *note Printing Bit Vectors::, or *note Printing
Other Vectors::.


File: gcl.info,  Node: Sharpsign Asterisk,  Next: Examples of Sharpsign Asterisk,  Prev: Sharpsign Left-Parenthesis,  Up: Sharpsign

2.4.8.4 Sharpsign Asterisk
..........................

Syntax: #*<<bits>>

   A simple bit vector is constructed containing the indicated bits (0's
and 1's), where the leftmost bit has index zero and the subsequent bits
have increasing indices.

   Syntax: #<<n>>*<<bits>>

   With an argument n, the vector to be created is of length n.  If the
number of bits is less than n but greater than zero, the last bit is
used to fill all remaining bits of the bit vector.

   The notations #* and #0* each denote an empty bit vector.

   Regardless of whether the optional numeric argument n is provided,
the token that follows the asterisk is delimited by a normal token
delimiter.  However, (unless the value of *read-suppress* is true) an
error of type reader-error is signaled if that token is not composed
entirely of 0's and 1's, or if n was supplied and the token is composed
of more than n bits, or if n is greater than one, but no bits were
specified.  Neither a single escape nor a multiple escape is permitted
in this token.

   For information on how the Lisp printer prints bit vectors, see *note
Printing Bit Vectors::.


File: gcl.info,  Node: Examples of Sharpsign Asterisk,  Next: Sharpsign Colon,  Prev: Sharpsign Asterisk,  Up: Sharpsign

2.4.8.5 Examples of Sharpsign Asterisk
......................................

For example,
       #*101111
      #6*101111
      #6*101
      #6*1011

   all mean the same thing: a vector of length 6 with elements 1, 0, 1,
1, 1, and 1.

   For example:

      #*         ;An empty bit-vector


File: gcl.info,  Node: Sharpsign Colon,  Next: Sharpsign Dot,  Prev: Examples of Sharpsign Asterisk,  Up: Sharpsign

2.4.8.6 Sharpsign Colon
.......................

Syntax: #:<<symbol-name>>

   #: introduces an uninterned symbol whose name is symbol-name.  Every
time this syntax is encountered, a distinct uninterned symbol is
created.  The symbol-name must have the syntax of a symbol with no
package prefix.

   For information on how the Lisp reader prints uninterned symbols, see
*note Printing Symbols::.


File: gcl.info,  Node: Sharpsign Dot,  Next: Sharpsign B,  Prev: Sharpsign Colon,  Up: Sharpsign

2.4.8.7 Sharpsign Dot
.....................

#.foo is read as the object resulting from the evaluation of the object
represented by foo.  The evaluation is done during the read process,
when the #. notation is encountered.  The #. syntax therefore performs a
read-time evaluation of foo.

   The normal effect of #. is inhibited when the value of *read-eval* is
false.

   In that situation, an error of type reader-error is signaled.

   For an object that does not have a convenient printed representation,
a form that computes the object can be given using the #. notation.


File: gcl.info,  Node: Sharpsign B,  Next: Sharpsign O,  Prev: Sharpsign Dot,  Up: Sharpsign

2.4.8.8 Sharpsign B
...................

#Brational reads rational in binary (radix 2).  For example,

      #B1101 == 13 ;1101_2
      #b101/11 == 5/3

   The consequences are undefined if the token immediately following the
#B does not have the syntax of a binary (i.e., radix 2) rational.


File: gcl.info,  Node: Sharpsign O,  Next: Sharpsign X,  Prev: Sharpsign B,  Up: Sharpsign

2.4.8.9 Sharpsign O
...................

#Orational reads rational in octal (radix 8).  For example,

      #o37/15 == 31/13
      #o777 == 511
      #o105 == 69 ;105_8

   The consequences are undefined if the token immediately following the
#O does not have the syntax of an octal (i.e., radix 8) rational.


File: gcl.info,  Node: Sharpsign X,  Next: Sharpsign R,  Prev: Sharpsign O,  Up: Sharpsign

2.4.8.10 Sharpsign X
....................

#Xrational reads rational in hexadecimal (radix 16).  The digits above 9
are the letters A through F (the lowercase letters a through f are also
acceptable).  For example,

      #xF00 == 3840
      #x105 == 261 ;105_16

   The consequences are undefined if the token immediately following the
#X does not have the syntax of a hexadecimal (i.e., radix 16) rational.


File: gcl.info,  Node: Sharpsign R,  Next: Sharpsign C,  Prev: Sharpsign X,  Up: Sharpsign

2.4.8.11 Sharpsign R
....................

#nR

   #radixRrational reads rational in radix radix.  radix must consist of
only digits that are interpreted as an integer in decimal radix; its
value must be between 2 and 36 (inclusive).  Only valid digits for the
specified radix may be used.

   For example, #3r102 is another way of writing 11 (decimal), and
#11R32 is another way of writing 35 (decimal).  For radices larger than
10, letters of the alphabet are used in order for the digits after 9.
No alternate # notation exists for the decimal radix since a decimal
point suffices.

   Figure 2-20 contains examples of the use of #B, #O, #X, and #R.

  #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     

        Figure 2-20: Radix Indicator Example       


   The consequences are undefined if the token immediately following the
#nR does not have the syntax of a rational in radix n.


File: gcl.info,  Node: Sharpsign C,  Next: Sharpsign A,  Prev: Sharpsign R,  Up: Sharpsign

2.4.8.12 Sharpsign C
....................

#C reads a following object, which must be a list of length two whose
elements are both reals.  These reals denote, respectively, the real and
imaginary parts of a complex number.

   If the two parts as notated are not of the same data type, then they
are converted according to the rules of floating-point contagion
described in *note Contagion in Numeric Operations::.

   #C(real imag) is equivalent to #.(complex (quote real) (quote imag)),
except that #C is not affected by *read-eval*.  See the function
complex.

   Figure 2-21 contains examples of the use of #C.

  #C(3.0s1 2.0s-1)  ;A complex with small float parts.                
  #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.                  

                  Figure 2-21: Complex Number Example                


   For further information, see *note Printing Complexes:: and *note
Syntax of a Complex::.


File: gcl.info,  Node: Sharpsign A,  Next: Sharpsign S,  Prev: Sharpsign C,  Up: Sharpsign

2.4.8.13 Sharpsign A
....................

#nA

   #nAobject constructs an n-dimensional array, using object as the
value of the :initial-contents argument to make-array.

   For example, #2A((0 1 5) (foo 2 (hot dog))) represents a 2-by-3
matrix:

      0       1       5
      foo     2       (hot dog)

   In contrast, #1A((0 1 5) (foo 2 (hot dog))) represents a vector of
length 2 whose elements are lists:

      (0 1 5) (foo 2 (hot dog))

   #0A((0 1 5) (foo 2 (hot dog))) represents a zero-dimensional array
whose sole element is a list:

      ((0 1 5) (foo 2 (hot dog)))

   #0A foo represents a zero-dimensional array whose sole element is the
symbol foo.  The notation #1A foo is not valid because foo is not a
sequence.

   If some dimension of the array whose representation is being parsed
is found to be 0, all dimensions to the right (i.e., the higher numbered
dimensions) are also considered to be 0.

   For information on how the Lisp printer prints arrays, see *note
Printing Strings::, *note Printing Bit Vectors::, *note Printing Other
Vectors::, or *note Printing Other Arrays::.


File: gcl.info,  Node: Sharpsign S,  Next: Sharpsign P,  Prev: Sharpsign A,  Up: Sharpsign

2.4.8.14 Sharpsign S
....................

#s(name slot1 value1 slot2 value2 ...) denotes a structure.  This is
valid only if name is the name of a structure type already defined by
defstruct and if the structure type has a standard constructor function.
Let cm stand for the name of this constructor function; then this syntax
is equivalent to

      #.(cm keyword1 'value1 keyword2 'value2 ...)

   where each keywordj is the result of computing

      (intern (string slotj) (find-package 'keyword))

   The net effect is that the constructor function is called with the
specified slots having the specified values.

   (This coercion feature is deprecated; in the future, keyword names
will be taken in the package they are read in, so symbols that are
actually in the KEYWORD package should be used if that is what is
desired.)

   Whatever object the constructor function returns is returned by the
#S syntax.

   For information on how the Lisp printer prints structures, see *note
Printing Structures::.


File: gcl.info,  Node: Sharpsign P,  Next: Sharpsign Equal-Sign,  Prev: Sharpsign S,  Up: Sharpsign

2.4.8.15 Sharpsign P
....................

#P reads a following object, which must be a string.

   #P<<expression>> is equivalent to #.(parse-namestring
'<<expression>>), except that #P is not affected by *read-eval*.

   For information on how the Lisp printer prints pathnames, see *note
Printing Pathnames::.


File: gcl.info,  Node: Sharpsign Equal-Sign,  Next: Sharpsign Sharpsign,  Prev: Sharpsign P,  Up: Sharpsign

2.4.8.16 Sharpsign Equal-Sign
.............................

#n=

   #n=object reads as whatever object has object as its printed
representation.  However, that object is labeled by n, a required
unsigned decimal integer, for possible reference by the syntax #n#.  The
scope of the label is the expression being read by the outermost call to
read; within this expression, the same label may not appear twice.


File: gcl.info,  Node: Sharpsign Sharpsign,  Next: Sharpsign Plus,  Prev: Sharpsign Equal-Sign,  Up: Sharpsign

2.4.8.17 Sharpsign Sharpsign
............................

#n#

   #n#, where n is a required unsigned decimal integer, provides a
reference to some object labeled by #n=; that is, #n# represents a
pointer to the same (eq) object labeled by #n=.  For example, a
structure created in the variable y by this code:

      (setq x (list 'p 'q))
      (setq y (list (list 'a 'b) x 'foo x))
      (rplacd (last y) (cdr y))

   could be represented in this way:

      ((a b) . #1=(#2=(p q) foo #2# . #1#))

   Without this notation, but with *print-length* set to 10 and
*print-circle* set to nil, the structure would print in this way:

      ((a b) (p q) foo (p q) (p q) foo (p q) (p q) foo (p q) ...)

   A reference #n# may only occur after a label #n=; forward references
are not permitted.  The reference may not appear as the labeled object
itself (that is, #n=#n#) may not be written because the object labeled
by #n= is not well defined in this case.


File: gcl.info,  Node: Sharpsign Plus,  Next: Sharpsign Minus,  Prev: Sharpsign Sharpsign,  Up: Sharpsign

2.4.8.18 Sharpsign Plus
.......................

#+ provides a read-time conditionalization facility; the syntax is
#+test expression.  If the feature expression test succeeds, then this
textual notation represents an object whose printed representation is
expression.  If the feature expression test fails, then this textual
notation is treated as whitespace_2; that is, it is as if the "#+ test
expression" did not appear and only a space appeared in its place.

   For a detailed description of success and failure in feature
expressions, see *note Feature Expressions::.

   #+ operates by first reading the feature expression and then skipping
over the form if the feature expression fails.

   While reading the test, the current package is the KEYWORD package.

   Skipping over the form is accomplished by binding *read-suppress* to
true and then calling read.

   For examples, see *note Examples of Feature Expressions::.


File: gcl.info,  Node: Sharpsign Minus,  Next: Sharpsign Vertical-Bar,  Prev: Sharpsign Plus,  Up: Sharpsign

2.4.8.19 Sharpsign Minus
........................

#- is like #+ except that it skips the expression if the test succeeds;
that is,

     #-test expression == #+(not test) expression

   For examples, see *note Examples of Feature Expressions::.


File: gcl.info,  Node: Sharpsign Vertical-Bar,  Next: Examples of Sharpsign Vertical-Bar,  Prev: Sharpsign Minus,  Up: Sharpsign

2.4.8.20 Sharpsign Vertical-Bar
...............................

#|...|# is treated as a comment by the reader.  It must be balanced with
respect to other occurrences of #| and |#, but otherwise may contain any
characters whatsoever.


File: gcl.info,  Node: Examples of Sharpsign Vertical-Bar,  Next: Notes about Style for Sharpsign Vertical-Bar,  Prev: Sharpsign Vertical-Bar,  Up: Sharpsign

2.4.8.21 Examples of Sharpsign Vertical-Bar
...........................................

The following are some examples that exploit the #|...|# notation:

     ;;; In this example, some debugging code is commented out with #|...|#
     ;;; Note that this kind of comment can occur in the middle of a line
     ;;; (because a delimiter marks where the end of the comment occurs)
     ;;; where a semicolon comment can only occur at the end of a line
     ;;; (because it comments out the rest of the line).
      (defun add3 (n) #|(format t "~&Adding 3 to ~D." n)|# (+ n 3))

     ;;; The examples that follow show issues related to #| ... |# nesting.

     ;;; In this first example, #| and |# always occur properly paired,
     ;;; so nesting works naturally.
      (defun mention-fun-fact-1a ()
        (format t "CL uses ; and #|...|# in comments."))
     =>  MENTION-FUN-FACT-1A
      (mention-fun-fact-1a)
      |>  CL uses ; and #|...|# in comments.
     =>  NIL
      #| (defun mention-fun-fact-1b ()
           (format t "CL uses ; and #|...|# in comments.")) |#
      (fboundp 'mention-fun-fact-1b) =>  NIL

     ;;; In this example, vertical-bar followed by sharpsign needed to appear
     ;;; in a string without any matching sharpsign followed by vertical-bar
     ;;; having preceded this.  To compensate, the programmer has included a
     ;;; slash separating the two characters.  In case 2a, the slash is
     ;;; unnecessary but harmless, but in case 2b, the slash is critical to
     ;;; allowing the outer #| ... |# pair match.  If the slash were not present,
     ;;; the outer comment would terminate prematurely.
      (defun mention-fun-fact-2a ()
        (format t "Don't use |\# unmatched or you'll get in trouble!"))
     =>  MENTION-FUN-FACT-2A
      (mention-fun-fact-2a)
      |>  Don't use |# unmatched or you'll get in trouble!
     =>  NIL
      #| (defun mention-fun-fact-2b ()
           (format t "Don't use |\# unmatched or you'll get in trouble!") |#
      (fboundp 'mention-fun-fact-2b) =>  NIL

     ;;; In this example, the programmer attacks the mismatch problem in a
     ;;; different way.  The sharpsign vertical bar in the comment is not needed
     ;;; for the correct parsing of the program normally (as in case 3a), but
     ;;; becomes important to avoid premature termination of a comment when such
     ;;; a program is commented out (as in case 3b).
      (defun mention-fun-fact-3a () ; #|
        (format t "Don't use |# unmatched or you'll get in trouble!"))
     =>  MENTION-FUN-FACT-3A
      (mention-fun-fact-3a)
      |>  Don't use |# unmatched or you'll get in trouble!
     =>  NIL
      #|
      (defun mention-fun-fact-3b () ; #|
        (format t "Don't use |# unmatched or you'll get in trouble!"))
      |#
      (fboundp 'mention-fun-fact-3b) =>  NIL


File: gcl.info,  Node: Notes about Style for Sharpsign Vertical-Bar,  Next: Sharpsign Less-Than-Sign,  Prev: Examples of Sharpsign Vertical-Bar,  Up: Sharpsign

2.4.8.22 Notes about Style for Sharpsign Vertical-Bar
.....................................................

Some text editors that purport to understand Lisp syntax treat any |...|
as balanced pairs that cannot nest (as if they were just balanced pairs
of the multiple escapes used in notating certain symbols).  To
compensate for this deficiency, some programmers use the notation
#||...#||...||#...||# instead of #|...#|...|#...|#.  Note that this
alternate usage is not a different reader macro; it merely exploits the
fact that the additional vertical-bars occur within the comment in a way
that tricks certain text editor into better supporting nested comments.
As such, one might sometimes see code like:

      #|| (+ #|| 3 ||# 4 5) ||#

   Such code is equivalent to:

      #| (+ #| 3 |# 4 5) |#


File: gcl.info,  Node: Sharpsign Less-Than-Sign,  Next: Sharpsign Whitespace,  Prev: Notes about Style for Sharpsign Vertical-Bar,  Up: Sharpsign

2.4.8.23 Sharpsign Less-Than-Sign
.................................

#< is not valid reader syntax.  The Lisp reader will signal an error

   of type reader-error

   on encountering #<.  This syntax is typically used in the printed
representation of objects that cannot be read back in.


File: gcl.info,  Node: Sharpsign Whitespace,  Next: Sharpsign Right-Parenthesis,  Prev: Sharpsign Less-Than-Sign,  Up: Sharpsign

2.4.8.24 Sharpsign Whitespace
.............................

# followed immediately by whitespace_1 is not valid reader syntax.  The
Lisp reader will signal an error of type reader-error if it encounters
the reader macro notation #<Newline> or #<Space>.


File: gcl.info,  Node: Sharpsign Right-Parenthesis,  Prev: Sharpsign Whitespace,  Up: Sharpsign

2.4.8.25 Sharpsign Right-Parenthesis
....................................

This is not valid reader syntax.

   The Lisp reader will signal an error

   of type reader-error

   upon encountering #).


File: gcl.info,  Node: Re-Reading Abbreviated Expressions,  Prev: Sharpsign,  Up: Standard Macro Characters

2.4.9 Re-Reading Abbreviated Expressions
----------------------------------------

Note that the Lisp reader will generally signal an error of type
reader-error when reading an expression_2 that has been abbreviated
because of length or level limits (see *print-level*, *print-length*,
and *print-lines*) due to restrictions on "..", "...", "#" followed by
whitespace_1, and "#)".


File: gcl.info,  Node: Evaluation and Compilation,  Next: Types and Classes,  Prev: Syntax,  Up: Top

3 Evaluation and Compilation
****************************

* Menu:

* Evaluation::
* Compilation::
* Declarations::
* Lambda Lists::
* Error Checking in Function Calls::
* Traversal Rules and Side Effects::
* Destructive Operations::
* Evaluation and Compilation Dictionary::


File: gcl.info,  Node: Evaluation,  Next: Compilation,  Prev: Evaluation and Compilation,  Up: Evaluation and Compilation

3.1 Evaluation
==============

Execution of code can be accomplished by a variety of means ranging from
direct interpretation of a form representing a program to invocation of
compiled code produced by a compiler.

   Evaluation is the process by which a program is executed in Common
Lisp.  The mechanism of evaluation is manifested both implicitly through
the effect of the Lisp read-eval-print loop, and explicitly through the
presence of the functions eval, compile, compile-file, and load.  Any of
these facilities might share the same execution strategy, or each might
use a different one.

   The behavior of a conforming program processed by eval and by
compile-file might differ; see *note Semantic Constraints::.

   Evaluation can be understood in terms of a model in which an
interpreter recursively traverses a form performing each step of the
computation as it goes.  This model, which describes the semantics of
Common Lisp programs, is described in *note The Evaluation Model::.

* Menu:

* Introduction to Environments::
* The Evaluation Model::
* Lambda Expressions::
* Closures and Lexical Binding::
* Shadowing::
* Extent::
* Return Values::


File: gcl.info,  Node: Introduction to Environments,  Next: The Evaluation Model,  Prev: Evaluation,  Up: Evaluation

3.1.1 Introduction to Environments
----------------------------------

A binding is an association between a name and that which the name
denotes.  Bindings are established in a lexical environment or a dynamic
environment by particular special operators.

   An environment is a set of bindings and other information used during
evaluation (e.g., to associate meanings with names).

   Bindings in an environment are partitioned into namespaces .  A
single name can simultaneously have more than one associated binding per
environment, but can have only one associated binding per namespace.

* Menu:

* The Global Environment::
* Dynamic Environments::
* Lexical Environments::
* The Null Lexical Environment::
* Environment Objects::


File: gcl.info,  Node: The Global Environment,  Next: Dynamic Environments,  Prev: Introduction to Environments,  Up: Introduction to Environments

3.1.1.1 The Global Environment
..............................

The global environment is that part of an environment that contains
bindings with both indefinite scope and indefinite extent.  The global
environment contains, among other things, the following:

*
     bindings of dynamic variables and constant variables.
*
     bindings of functions, macros, and special operators.
*

     bindings of compiler macros.

*
     bindings of type and class names
*
     information about proclamations.


File: gcl.info,  Node: Dynamic Environments,  Next: Lexical Environments,  Prev: The Global Environment,  Up: Introduction to Environments

3.1.1.2 Dynamic Environments
............................

A dynamic environment for evaluation is that part of an environment that
contains bindings whose duration is bounded by points of establishment
and disestablishment within the execution of the form that established
the binding.  A dynamic environment contains, among other things, the
following:

*
     bindings for dynamic variables.
*
     information about active catch tags.
*
     information about exit points established by unwind-protect.
*
     information about active handlers and restarts.

   The dynamic environment that is active at any given point in the
execution of a program is referred to by definite reference as "the
current dynamic environment," or sometimes as just "the dynamic
environment."

   Within a given namespace, a name is said to be bound in a dynamic
environment if there is a binding associated with its name in the
dynamic environment or, if not, there is a binding associated with its
name in the global environment.


File: gcl.info,  Node: Lexical Environments,  Next: The Null Lexical Environment,  Prev: Dynamic Environments,  Up: Introduction to Environments

3.1.1.3 Lexical Environments
............................

A lexical environment for evaluation at some position in a program is
that part of the environment that contains information having lexical
scope within the forms containing that position.  A lexical environment
contains, among other things, the following:

*
     bindings of lexical variables and symbol macros.
*
     bindings of functions and macros.  (Implicit in this is information
     about those compiler macros that are locally disabled.)
*
     bindings of block tags.
*
     bindings of go tags.
*
     information about declarations.

   The lexical environment that is active at any given position in a
program being semantically processed is referred to by definite
reference as "the current lexical environment," or sometimes as just
"the lexical environment."

   Within a given namespace, a name is said to be bound in a lexical
environment if there is a binding associated with its name in the
lexical environment or, if not, there is a binding associated with its
name in the global environment.


File: gcl.info,  Node: The Null Lexical Environment,  Next: Environment Objects,  Prev: Lexical Environments,  Up: Introduction to Environments

3.1.1.4 The Null Lexical Environment
....................................

The null lexical environment is equivalent to the global environment.

   Although in general the representation of an environment object is
implementation-dependent, nil can be used in any situation where an
environment object is called for in order to denote the null lexical
environment.


File: gcl.info,  Node: Environment Objects,  Prev: The Null Lexical Environment,  Up: Introduction to Environments

3.1.1.5 Environment Objects
...........................

Some operators make use of an object, called an environment object ,
that represents the set of lexical bindings needed to perform semantic
analysis on a form in a given lexical environment.  The set of bindings
in an environment object may be a subset of the bindings that would be
needed to actually perform an evaluation; for example, values associated
with variable names and function names in the corresponding lexical
environment might not be available in an environment object.

   The type and nature of an environment object is
implementation-dependent.  The values of environment parameters to macro
functions are examples of environment objects.

   The object nil when used as an environment object denotes the null
lexical environment; see *note The Null Lexical Environment::.


File: gcl.info,  Node: The Evaluation Model,  Next: Lambda Expressions,  Prev: Introduction to Environments,  Up: Evaluation

3.1.2 The Evaluation Model
--------------------------

A Common Lisp system evaluates forms with respect to lexical, dynamic,
and global environments.  The following sections describe the components
of the Common Lisp evaluation model.

* Menu:

* Form Evaluation::
* Symbols as Forms::
* Lexical Variables::
* Dynamic Variables::
* Constant Variables::
* Symbols Naming Both Lexical and Dynamic Variables::
* Conses as Forms::
* Special Forms::
* Macro Forms::
* Function Forms::
* Lambda Forms::
* Self-Evaluating Objects::
* Examples of Self-Evaluating Objects::


File: gcl.info,  Node: Form Evaluation,  Next: Symbols as Forms,  Prev: The Evaluation Model,  Up: The Evaluation Model

3.1.2.1 Form Evaluation
.......................

Forms fall into three categories: symbols, conses, and self-evaluating
objects.  The following sections explain these categories.


File: gcl.info,  Node: Symbols as Forms,  Next: Lexical Variables,  Prev: Form Evaluation,  Up: The Evaluation Model

3.1.2.2 Symbols as Forms
........................

If a form is a symbol, then it is either a symbol macro or a variable.

   The symbol names a symbol macro if there is a binding of the symbol
as a symbol macro in the current lexical environment

   (see define-symbol-macro and symbol-macrolet).

   If the symbol is a symbol macro, its expansion function is obtained.
The expansion function is a function of two arguments, and is invoked by
calling the macroexpand hook with the expansion function as its first
argument, the symbol as its second argument, and an environment object
(corresponding to the current lexical environment) as its third
argument.  The macroexpand hook, in turn, calls the expansion function
with the form as its first argument and the environment as its second
argument.  The value of the expansion function, which is passed through
by the macroexpand hook, is a form.  This resulting form is processed in
place of the original symbol.

   If a form is a symbol that is not a symbol macro, then it is the name
of a variable, and the value of that variable is returned.  There are
three kinds of variables: lexical variables, dynamic variables, and
constant variables.  A variable can store one object.  The main
operations on a variable are to read_1 and to write_1 its value.

   An error of type unbound-variable should be signaled if an unbound
variable is referenced.

   Non-constant variables can be assigned by using setq or bound_3 by
using let.  Figure 3-1 lists some defined names that are applicable to
assigning, binding, and defining variables.

  boundp        let                  progv         
  defconstant   let*                 psetq         
  defparameter  makunbound           set           
  defvar        multiple-value-bind  setq          
  lambda        multiple-value-setq  symbol-value  

  Figure 3-1: Some Defined Names Applicable to Variables


   The following is a description of each kind of variable.


File: gcl.info,  Node: Lexical Variables,  Next: Dynamic Variables,  Prev: Symbols as Forms,  Up: The Evaluation Model

3.1.2.3 Lexical Variables
.........................

A lexical variable is a variable that can be referenced only within the
lexical scope of the form that establishes that variable; lexical
variables have lexical scope.  Each time a form creates a lexical
binding of a variable, a fresh binding is established.

   Within the scope of a binding for a lexical variable name, uses of
that name as a variable are considered to be references to that binding
except where the variable is shadowed_2 by a form that establishes a
fresh binding for that variable name, or by a form that locally declares
the name special.

   A lexical variable always has a value.  There is no operator that
introduces a binding for a lexical variable without giving it an initial
value, nor is there any operator that can make a lexical variable be
unbound.

   Bindings of lexical variables are found in the lexical environment.


File: gcl.info,  Node: Dynamic Variables,  Next: Constant Variables,  Prev: Lexical Variables,  Up: The Evaluation Model

3.1.2.4 Dynamic Variables
.........................

A variable is a dynamic variable if one of the following conditions
hold:

*
     It is locally declared or globally proclaimed special.

*
     It occurs textually within a form that creates a dynamic binding
     for a variable of the same name, and the binding is not shadowed_2
     by a form that creates a lexical binding of the same variable name.

   A dynamic variable can be referenced at any time in any program;
there is no textual limitation on references to dynamic variables.  At
any given time, all dynamic variables with a given name refer to exactly
one binding, either in the dynamic environment or in the global
environment.

   The value part of the binding for a dynamic variable might be empty;
in this case, the dynamic variable is said to have no value, or to be
unbound.  A dynamic variable can be made unbound by using makunbound.

   The effect of binding a dynamic variable is to create a new binding
to which all references to that dynamic variable in any program refer
for the duration of the evaluation of the form that creates the dynamic
binding.

   A dynamic variable can be referenced outside the dynamic extent of a
form that binds it.  Such a variable is sometimes called a "global
variable" but is still in all respects just a dynamic variable whose
binding happens to exist in the global environment rather than in some
dynamic environment.

   A dynamic variable is unbound unless and until explicitly assigned a
value, except for those variables whose initial value is defined in this
specification or by an implementation.


File: gcl.info,  Node: Constant Variables,  Next: Symbols Naming Both Lexical and Dynamic Variables,  Prev: Dynamic Variables,  Up: The Evaluation Model

3.1.2.5 Constant Variables
..........................

Certain variables, called constant variables, are reserved as "named
constants."  The consequences are undefined if an attempt is made to
assign a value to, or create a binding for a constant variable, except
that a 'compatible' redefinition of a constant variable using
defconstant is permitted; see the macro defconstant.

   Keywords, symbols defined by Common Lisp or the implementation as
constant (such as nil, t, and pi), and symbols declared as constant
using defconstant are constant variables.


File: gcl.info,  Node: Symbols Naming Both Lexical and Dynamic Variables,  Next: Conses as Forms,  Prev: Constant Variables,  Up: The Evaluation Model

3.1.2.6 Symbols Naming Both Lexical and Dynamic Variables
.........................................................

The same symbol can name both a lexical variable and a dynamic variable,
but never in the same lexical environment.

   In the following example, the symbol x is used, at different times,
as the name of a lexical variable and as the name of a dynamic variable.

      (let ((x 1))            ;Binds a special variable X
        (declare (special x))
        (let ((x 2))          ;Binds a lexical variable X
          (+ x                ;Reads a lexical variable X
             (locally (declare (special x))
                      x))))   ;Reads a special variable X
     =>  3


File: gcl.info,  Node: Conses as Forms,  Next: Special Forms,  Prev: Symbols Naming Both Lexical and Dynamic Variables,  Up: The Evaluation Model

3.1.2.7 Conses as Forms
.......................

A cons that is used as a form is called a compound form.

   If the car of that compound form is a symbol, that symbol is the name
of an operator, and the form is either a special form, a macro form, or
a function form, depending on the function binding of the operator in
the current lexical environment.  If the operator is neither a special
operator nor a macro name, it is assumed to be a function name (even if
there is no definition for such a function).

   If the car of the compound form is not a symbol, then that car must
be a lambda expression, in which case the compound form is a lambda
form.

   How a compound form is processed depends on whether it is classified
as a special form, a macro form, a function form, or a lambda form.


File: gcl.info,  Node: Special Forms,  Next: Macro Forms,  Prev: Conses as Forms,  Up: The Evaluation Model

3.1.2.8 Special Forms
.....................

A special form is a form with special syntax, special evaluation rules,
or both, possibly manipulating the evaluation environment, control flow,
or both.  A special operator has access to the current lexical
environment and the current dynamic environment.  Each special operator
defines the manner in which its subexpressions are treated--which are
forms, which are special syntax, etc.

   Some special operators create new lexical or dynamic environments for
use during the evaluation of subforms of the special form.  For example,
block creates a new lexical environment that is the same as the one in
force at the point of evaluation of the block form with the addition of
a binding of the block name to an exit point from the block.

   The set of special operator names is fixed in Common Lisp; no way is
provided for the user to define a special operator.  Figure 3-2 lists
all of the Common Lisp symbols that have definitions as special
operators.

  block      let*                  return-from      
  catch      load-time-value       setq             
  eval-when  locally               symbol-macrolet  
  flet       macrolet              tagbody          
  function   multiple-value-call   the              
  go         multiple-value-prog1  throw            
  if         progn                 unwind-protect   
  labels     progv                                  
  let        quote                                  

      Figure 3-2: Common Lisp Special Operators    



File: gcl.info,  Node: Macro Forms,  Next: Function Forms,  Prev: Special Forms,  Up: The Evaluation Model

3.1.2.9 Macro Forms
...................

If the operator names a macro, its associated macro function is applied
to the entire form and the result of that application is used in place
of the original form.

   Specifically, a symbol names a macro in a given lexical environment
if macro-function is true of the symbol and that environment.  The
function returned by macro-function is a function of two arguments,
called the expansion function.  The expansion function is invoked by
calling the macroexpand hook with the expansion function as its first
argument, the entire macro form as its second argument, and an
environment object (corresponding to the current lexical environment) as
its third argument.  The macroexpand hook, in turn, calls the expansion
function with the form as its first argument and the environment as its
second argument.  The value of the expansion function, which is passed
through by the macroexpand hook, is a form.  The returned form is
evaluated in place of the original form.

   The consequences are undefined if a macro function destructively
modifies any part of its form argument.

   A macro name is not a function designator, and cannot be used as the
function argument to functions such as apply, funcall, or map.

   An implementation is free to implement a Common Lisp special operator
as a macro.  An implementation is free to implement any macro operator
as a special operator, but only if an equivalent definition of the macro
is also provided.

   Figure 3-3 lists some defined names that are applicable to macros.

  *macroexpand-hook*  macro-function  macroexpand-1  
  defmacro            macroexpand     macrolet       

    Figure 3-3: Defined names applicable to macros  



File: gcl.info,  Node: Function Forms,  Next: Lambda Forms,  Prev: Macro Forms,  Up: The Evaluation Model

3.1.2.10 Function Forms
.......................

If the operator is a symbol naming a function, the form represents a
function form, and the cdr of the list contains the forms which when
evaluated will supply the arguments passed to the function.

   When a function name is not defined, an error of type
undefined-function should be signaled at run time; see *note Semantic
Constraints::.

   A function form is evaluated as follows:

   The subforms in the cdr of the original form are evaluated in
left-to-right order in the current lexical and dynamic environments.
The primary value of each such evaluation becomes an argument to the
named function; any additional values returned by the subforms are
discarded.

   The functional value of the operator is retrieved from the lexical
environment, and that function is invoked with the indicated arguments.

   Although the order of evaluation of the argument subforms themselves
is strictly left-to-right, it is not specified whether the definition of
the operator in a function form is looked up before the evaluation of
the argument subforms, after the evaluation of the argument subforms, or
between the evaluation of any two argument subforms if there is more
than one such argument subform.  For example, the following might return
23 or~24.

      (defun foo (x) (+ x 3))
      (defun bar () (setf (symbol-function 'foo) #'(lambda (x) (+ x 4))))
      (foo (progn (bar) 20))

   A binding for a function name can be established in one of several
ways.  A binding for a function name in the global environment can be
established by defun, setf of fdefinition, setf of symbol-function,
ensure-generic-function, defmethod (implicitly, due to
ensure-generic-function), or defgeneric.  A binding for a function name
in the lexical environment can be established by flet or labels.

   Figure 3-4 lists some defined names that are applicable to functions.

  apply                 fdefinition  mapcan               
  call-arguments-limit  flet         mapcar               
  complement            fmakunbound  mapcon               
  constantly            funcall      mapl                 
  defgeneric            function     maplist              
  defmethod             functionp    multiple-value-call  
  defun                 labels       reduce               
  fboundp               map          symbol-function      

      Figure 3-4: Some function-related defined names    



File: gcl.info,  Node: Lambda Forms,  Next: Self-Evaluating Objects,  Prev: Function Forms,  Up: The Evaluation Model

3.1.2.11 Lambda Forms
.....................

A lambda form is similar to a function form, except that the function
name is replaced by a lambda expression.

   A lambda form is equivalent to using funcall of a lexical closure of
the lambda expression on the given arguments.  (In practice, some
compilers are more likely to produce inline code for a lambda form than
for an arbitrary named function that has been declared inline; however,
such a difference is not semantic.)

   For further information, see *note Lambda Expressions::.


File: gcl.info,  Node: Self-Evaluating Objects,  Next: Examples of Self-Evaluating Objects,  Prev: Lambda Forms,  Up: The Evaluation Model

3.1.2.12 Self-Evaluating Objects
................................

A form that is neither a symbol nor a cons is defined to be a
self-evaluating object.  Evaluating such an object yields the same
object as a result.

   Certain specific symbols and conses might also happen to be
"self-evaluating" but only as a special case of a more general set of
rules for the evaluation of symbols and conses; such objects are not
considered to be self-evaluating objects.

   The consequences are undefined if literal objects (including
self-evaluating objects) are destructively modified.


File: gcl.info,  Node: Examples of Self-Evaluating Objects,  Prev: Self-Evaluating Objects,  Up: The Evaluation Model

3.1.2.13 Examples of Self-Evaluating Objects
............................................

Numbers, pathnames, and arrays are examples of self-evaluating objects.

      3 =>  3
      #c(2/3 5/8) =>  #C(2/3 5/8)
      #p"S:[BILL]OTHELLO.TXT" =>  #P"S:[BILL]OTHELLO.TXT"
      #(a b c) =>  #(A B C)
      "fred smith" =>  "fred smith"


File: gcl.info,  Node: Lambda Expressions,  Next: Closures and Lexical Binding,  Prev: The Evaluation Model,  Up: Evaluation

3.1.3 Lambda Expressions
------------------------

In a lambda expression, the body is evaluated in a lexical environment
that is formed by adding the binding of each parameter in the lambda
list with the corresponding value from the arguments to the current
lexical environment.

   For further discussion of how bindings are established based on the
lambda list, see *note Lambda Lists::.

   The body of a lambda expression is an implicit progn; the values it
returns are returned by the lambda expression.


File: gcl.info,  Node: Closures and Lexical Binding,  Next: Shadowing,  Prev: Lambda Expressions,  Up: Evaluation

3.1.4 Closures and Lexical Binding
----------------------------------

A lexical closure is a function that can refer to and alter the values
of lexical bindings established by binding forms that textually include
the function definition.

   Consider this code, where x is not declared special:

      (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 special form coerces a lambda expression into a closure
in which the lexical environment in effect when the special form is
evaluated is captured along with the lambda expression.

   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.  This variable has the value 6 initially,
but setq can alter this binding.  The lexical closure created for the
first lambda expression does not "snapshot" the value 6 for x when the
closure is created; rather it captures the binding of x.  The second
function can be used to alter the value in the same (captured) binding
(to 43, in the example), and this altered variable binding then affects
the value returned by 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 identical, at the discretion of the
implementation.  That is, two functions that are behaviorally
indistinguishable might or might not be identical.  Two functions that
are behaviorally distinguishable are distinct.  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 form is a list of ten closures.  Each
requires only the binding of x.  It is the same binding in each case,
but the ten closure objects might or might not be identical.  On the
other hand, the result of the form

      (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
closure objects can be identical because each closure is closed over a
distinct binding of x, and these bindings can be behaviorally
distinguished because of the use of setq.

   The result of the form

      (let ((funs '()))
        (dotimes (j 10)
          (let ((x 5))
            (push (function (lambda (z) (+ x z)))
                 funs)))
        funs)

   is a list of ten closure objects that might or might not be
identical.  A different binding of x is involved for each closure, but
the bindings cannot be distinguished because their values are the same
and immutable (there being no occurrence of setq on x).  A compiler
could internally transform the form to

      (let ((funs '()))
        (dotimes (j 10)
          (push (function (lambda (z) (+ 5 z)))
                funs))
       funs)

   where the closures may be identical.

   It is possible that a closure does not close over any variable
bindings.  In the code fragment

      (mapcar (function (lambda (x) (+ x 2))) y)

   the function (lambda (x) (+ x 2)) contains no references to any
outside object.  In this case, the same closure might be returned for
all evaluations of the function form.


File: gcl.info,  Node: Shadowing,  Next: Extent,  Prev: Closures and Lexical Binding,  Up: Evaluation

3.1.5 Shadowing
---------------

If two forms that establish lexical bindings with the same name N are
textually nested, then references to N within the inner form refer to
the binding established by the inner form; the inner binding for N
shadows the outer binding for N. Outside the inner form but inside the
outer one, references to N refer to the binding established by the outer
form.  For example:

      (defun test (x z)
        (let ((z (* x 2)))
          (print z))
        z)

   The binding of the variable z by let 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 test refers to the parameter named z.

   Constructs that are lexically scoped act as if new names were
generated for each object on each execution.  Therefore, dynamic
shadowing cannot occur.  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 4.
During the course of execution, there are three calls to
contorted-example, interleaved with two blocks:

      (contorted-example nil nil 2)
        (block here_1 ...)
          (contorted-example nil #'(lambda () (return-from here_1 4)) 1)
            (block here_2 ...)
              (contorted-example #'(lambda () (return-from here_1 4))
                                 #'(lambda () (return-from here_2 4))
                                 0)
                  (funcall f)
                         where f =>  #'(lambda () (return-from here_1 4))
                      (return-from here_1 4)

   At the time the funcall is executed there are two block exit points
outstanding, each apparently named here.  The return-from form executed
as a result of the funcall operation refers to the outer outstanding
exit point (here_1), not the inner one (here_2).  It refers to that exit
point textually visible at the point of execution of function (here
abbreviated by the #' syntax) that resulted in creation of the function
object actually invoked by funcall.

   If, in this example, one were to change the (funcall f) to (funcall
g), then the value of the call (contorted-example nil nil 2) would be 9.
The value would change because funcall would cause the execution of
(return-from here_2 4), thereby causing a return from the inner exit
point (here_2).  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 environment that is packaged up with a lambda
expression when function is executed.


File: gcl.info,  Node: Extent,  Next: Return Values,  Prev: Shadowing,  Up: Evaluation

3.1.6 Extent
------------

Contorted-example works only because the function named by f is invoked
during the extent of the exit point.  Once the flow of execution has
left the block, the exit point is disestablished.  For example:

      (defun invalid-example ()
        (let ((y (block here #'(lambda (z) (return-from here z)))))
          (if (numberp y) y (funcall y 5))))

   One might expect the call (invalid-example) to produce 5 by the
following incorrect reasoning: let binds y to the value of block; 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 invalid-example.

   The argument fails only because exit points have dynamic extent.  The
argument is correct up to the execution of return-from.  The execution
of return-from should signal an error of type control-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.

   A reference by name to a dynamic exit point binding such as a catch
tag refers to the most recently established binding of that name that
has not 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 is 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 catch
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 exit points would have different names, and therefore
the one in fun1 would not be shadowed.  The result would then have been
7.


File: gcl.info,  Node: Return Values,  Prev: Extent,  Up: Evaluation

3.1.7 Return Values
-------------------

Ordinarily the result of calling a function is a single object.
Sometimes, however, it is convenient for a function to compute several
objects and return them.

   In order to receive other than exactly one value from a form, one of
several special forms or macros must be used to request those values.
If a form produces multiple values which were not requested in this way,
then the first value is given to the caller and all others are
discarded; if the form produces zero values, then the caller receives
nil as a value.

   Figure 3-5 lists some operators for receiving multiple values_2.
These operators can be used to specify one or more forms to evaluate and
where to put the values returned by those forms.

  multiple-value-bind  multiple-value-prog1  return-from  
  multiple-value-call  multiple-value-setq   throw        
  multiple-value-list  return                             

  Figure 3-5: Some operators applicable to receiving multiple values


   The function values can produce multiple values_2.  (values) returns
zero values; (values form) returns the primary value returned by form;
(values form1 form2) returns two values, the primary value of form1 and
the primary value of form2; and so on.

   See multiple-values-limit and values-list.


File: gcl.info,  Node: Compilation,  Next: Declarations,  Prev: Evaluation,  Up: Evaluation and Compilation

3.2 Compilation
===============

* Menu:

* Compiler Terminology::
* Compilation Semantics::
* File Compilation::
* Literal Objects in Compiled Files::
* Exceptional Situations in the Compiler::


File: gcl.info,  Node: Compiler Terminology,  Next: Compilation Semantics,  Prev: Compilation,  Up: Compilation

3.2.1 Compiler Terminology
--------------------------

The following terminology is used in this section.

   The compiler is a utility that translates code into an
implementation-dependent form that might be represented or executed
efficiently.  The term compiler refers to both of the functions compile
and compile-file.

   The term compiled code refers to objects representing compiled
programs, such as objects constructed by compile or by load when loading
a compiled file.

   The term implicit compilation refers to compilation performed during
evaluation.

   The term literal object refers to a quoted object or a
self-evaluating object or an object that is a substructure of such an
object.  A constant variable is not itself a literal object.

   The term coalesce is defined as follows.  Suppose A and B are two
literal constants in the source code, and that A' and B' are the
corresponding objects in the compiled code.  If A' and B' are eql but A
and B are not eql, then it is said that A and B have been coalesced by
the compiler.

   The term minimal compilation refers to actions the compiler must take
at compile time.  These actions are specified in *note Compilation
Semantics::.

   The verb process refers to performing minimal compilation,
determining the time of evaluation for a form, and possibly evaluating
that form (if required).

   The term further compilation refers to implementation-dependent
compilation beyond minimal compilation.  That is, processing does not
imply complete compilation.  Block compilation and generation of
machine-specific instructions are examples of further compilation.
Further compilation is permitted to take place at run time.

   Four different environments relevant to compilation are
distinguished: the startup environment, the compilation environment, the
evaluation environment, and the run-time environment.

   The startup environment is the environment of the Lisp image from
which the compiler was invoked.

   The compilation environment is maintained by the compiler and is used
to hold definitions and declarations to be used internally by the
compiler.  Only those parts of a definition needed for correct
compilation are saved.  The compilation environment is used as the
environment argument to macro expanders called by the compiler.  It is
unspecified whether a definition available in the compilation
environment can be used in an evaluation initiated in the startup
environment or evaluation environment.

   The evaluation environment is a run-time environment in which macro
expanders and code specified by eval-when to be evaluated are evaluated.
All evaluations initiated by the compiler take place in the evaluation
environment.

   The run-time environment is the environment in which the program
being compiled will be executed.

   The compilation environment inherits from the evaluation environment,
and the compilation environment and evaluation environment might be
identical.  The evaluation environment inherits from the startup
environment, and the startup environment and evaluation environment
might be identical.

   The term compile time refers to the duration of time that the
compiler is processing source code.  At compile time, only the
compilation environment and the evaluation environment are available.

   The term compile-time definition refers to a definition in the
compilation environment.  For example, when compiling a file, the
definition of a function might be retained in the compilation
environment if it is declared inline.  This definition might not be
available in the evaluation environment.

   The term run time refers to the duration of time that the loader is
loading compiled code or compiled code is being executed.  At run time,
only the run-time environment is available.

   The term run-time definition refers to a definition in the run-time
environment.

   The term run-time compiler refers to the function compile or implicit
compilation, for which the compilation and run-time environments are
maintained in the same Lisp image.  Note that when the run-time compiler
is used, the run-time environment and startup environment are the same.


File: gcl.info,  Node: Compilation Semantics,  Next: File Compilation,  Prev: Compiler Terminology,  Up: Compilation

3.2.2 Compilation Semantics
---------------------------

Conceptually, compilation is a process that traverses code, performs
certain kinds of syntactic and semantic analyses using information (such
as proclamations and macro definitions) present in the compilation
environment, and produces equivalent, possibly more efficient code.

* Menu:

* Compiler Macros::
* Purpose of Compiler Macros::
* Naming of Compiler Macros::
* When Compiler Macros Are Used::
* Notes about the Implementation of Compiler Macros::
* Minimal Compilation::
* Semantic Constraints::


File: gcl.info,  Node: Compiler Macros,  Next: Purpose of Compiler Macros,  Prev: Compilation Semantics,  Up: Compilation Semantics

3.2.2.1 Compiler Macros
.......................

A compiler macro can be defined for a name that also names a function or
macro.  That is, it is possible for a function name to name both a
function and a compiler macro.

   A function name names a compiler macro if compiler-macro-function is
true of the function name in the lexical environment in which it
appears.  Creating a lexical binding for the function name not only
creates a new local function or macro definition, but also shadows_2 the
compiler macro.

   The function returned by compiler-macro-function is a function of two
arguments, called the expansion function.  To expand a compiler macro,
the expansion function is invoked by calling the macroexpand hook with
the expansion function as its first argument, the entire compiler macro
form as its second argument, and the current compilation environment (or
with the current lexical environment, if the form is being processed by
something other than compile-file) as its third argument.  The
macroexpand hook, in turn, calls the expansion function with the form as
its first argument and the environment as its second argument.  The
return value from the expansion function, which is passed through by the
macroexpand hook, might either be the same form, or else a form that
can, at the discretion of the code doing the expansion, be used in place
of the original form.

  *macroexpand-hook*  compiler-macro-function  define-compiler-macro  

        Figure 3-6: Defined names applicable to compiler macros      



File: gcl.info,  Node: Purpose of Compiler Macros,  Next: Naming of Compiler Macros,  Prev: Compiler Macros,  Up: Compilation Semantics

3.2.2.2 Purpose of Compiler Macros
..................................

The purpose of the compiler macro facility is to permit selective source
code transformations as optimization advice to the compiler.  When a
compound form is being processed (as by the compiler), if the operator
names a compiler macro then the compiler macro function may be invoked
on the form, and the resulting expansion recursively processed in
preference to performing the usual processing on the original form
according to its normal interpretation as a function form or macro form.

   A compiler macro function, like a macro function, is a function of
two arguments: the entire call form and the environment.  Unlike an
ordinary macro function, a compiler macro function can decline to
provide an expansion merely by returning a value that is the same as the
original form.  The consequences are undefined if a compiler macro
function destructively modifies any part of its form argument.

   The form passed to the compiler macro function can either be a list
whose car is the function name, or a list whose car is funcall and whose
cadr is a list (function name); note that this affects destructuring of
the form argument by the compiler macro function.  define-compiler-macro
arranges for destructuring of arguments to be performed correctly for
both possible formats.

   When compile-file chooses to expand a top level form that is a
compiler macro form, the expansion is also treated as a top level form
for the purposes of eval-when processing; see *note Processing of Top
Level Forms::.


File: gcl.info,  Node: Naming of Compiler Macros,  Next: When Compiler Macros Are Used,  Prev: Purpose of Compiler Macros,  Up: Compilation Semantics

3.2.2.3 Naming of Compiler Macros
.................................

Compiler macros may be defined for function names that name macros as
well as functions.

   Compiler macro definitions are strictly global.  There is no
provision for defining local compiler macros in the way that macrolet
defines local macros.  Lexical bindings of a function name shadow any
compiler macro definition associated with the name as well as its global
function or macro definition.

   Note that the presence of a compiler macro definition does not affect
the values returned by

   functions that access function definitions (e.g., fboundp) or macro
definitions (e.g., macroexpand).  Compiler macros are global, and the
function compiler-macro-function is sufficient to resolve their
interaction with other lexical and global definitions.


File: gcl.info,  Node: When Compiler Macros Are Used,  Next: Notes about the Implementation of Compiler Macros,  Prev: Naming of Compiler Macros,  Up: Compilation Semantics

3.2.2.4 When Compiler Macros Are Used
.....................................

The presence of a compiler macro definition for a function or macro
indicates that it is desirable for the compiler to use the expansion of
the compiler macro instead of the original function form or macro form.
However, no language processor (compiler, evaluator, or other code
walker) is ever required to actually invoke compiler macro functions, or
to make use of the resulting expansion if it does invoke a compiler
macro function.

   When the compiler encounters a form during processing that represents
a call to a compiler macro name (that is not declared notinline), the
compiler might expand the compiler macro, and might use the expansion in
place of the original form.

   When eval encounters a form during processing that represents a call
to a compiler macro name (that is not declared notinline), eval might
expand the compiler macro, and might use the expansion in place of the
original form.

   There are two situations in which a compiler macro definition must
not be applied by any language processor:

*
     The global function name binding associated with the compiler macro
     is shadowed by a lexical binding of the function name.

*
     The function name has been declared or proclaimed notinline and the
     call form appears within the scope of the declaration.

   It is unspecified whether compiler macros are expanded or used in any
other situations.

