* Expressions:: Expressions
@end menu
-@node Notational Conventions, Scheme Concepts, Overview, Overview
+@node Notational Conventions, Scheme Concepts, , Overview
@section Notational Conventions
@cindex notational conventions
@cindex conventions, notational
* Entry Format:: Entry Format
@end menu
-@node Errors, Examples, Notational Conventions, Notational Conventions
+@node Errors, Examples, , Notational Conventions
@subsection Errors
@cindex errors, notational conventions
* Storage Model:: Storage Model
@end menu
-@node Variable Bindings, Environment Concepts, Scheme Concepts, Scheme Concepts
+@node Variable Bindings, Environment Concepts, , Scheme Concepts
@subsection Variable Bindings
@cindex variable binding
@cindex binding, of variable
* Additional Notations:: Additional Notations
@end menu
-@node Whitespace, Delimiters, Lexical Conventions, Lexical Conventions
+@node Whitespace, Delimiters, , Lexical Conventions
@subsection Whitespace
@cindex whitespace, in programs (defn)
* Procedure Call Syntax:: Procedure Call Syntax
@end menu
-@node Literal Expressions, Variable References, Expressions, Expressions
+@node Literal Expressions, Variable References, , Expressions
@subsection Literal Expressions
@cindex literal expression (defn)
* Structure Definitions:: Structure Definitions
@end menu
-@node Lambda Expressions, Lexical Binding, Special Forms, Special Forms
+@node Lambda Expressions, Lexical Binding, , Special Forms
@section Lambda Expressions
@deffn {special form} lambda formals expression expression @dots{}
* Internal Definitions:: Internal Definitions
@end menu
-@node Top-Level Definitions, Internal Definitions, Definitions, Definitions
+@node Top-Level Definitions, Internal Definitions, , Definitions
@subsection Top-Level Definitions
@cindex top-level definition
@cindex definition, top-level
@end example
@end deffn
-@node Structure Definitions, , Iteration, Special Forms
+@node Structure Definitions, , Iteration, Special Forms
+@section Structure Definitions
@comment **** begin CLTL ****
@comment Altough this documentation isn't plagiarized from Common Lisp,
@comment the macro certainly is!
This section provides examples and describes the options and syntax of
-@var{define-structure}, an MIT Scheme macro which is essentially
-identical to @var{defstruct} in Common Lisp. The differences between
+@code{define-structure}, an MIT Scheme macro which is essentially
+identical to @code{defstruct} in Common Lisp. The differences between
them are summarized at the end of this section. For more information,
see Chapter 19 of Steele's Common Lisp book.
-@findex define-structure
-@cindex define-structure
+@deffn {special form+} define-structure (name structure-option @dots{}) slot-description @dots{}
+Each @var{slot-description} takes one of the following forms:
-@deffn {syntax} define-structure (name structure-option*) slot-descriptions*
-@end deffn
-
-Each @var{slot-description} is of the form (@var{slot-name}
-@var{default-init} [@var{slot-option} [@var{value}]]*).
+@example
+@var{slot-name}
+(@var{slot-name} @var{default-init} [@var{slot-option} @var{value}]*)
+@end example
@cindex keyword constructor
@cindex BOA constructor
values are only useful with a keyword constructor or BOA constructor
with argument list (see below).
-A call to @var{define-structure} defines a structure descriptor and a
+A call to @code{define-structure} defines a structure descriptor and a
set of procedures to manipulate instances of the structure. These
instances are represented as records by default but may alternately be
lists or vectors. The accessors and updaters are declared integrable
-using @var{integrate-operator}. Usually, no options are required, so a
-simple call to @var{define-structure} looks like:
+using @code{define-integrable}. Usually, no options are required, so a
+simple call to @code{define-structure} looks like:
@example
(define-structure foo a b c)
@code{foo-c}, and updaters @code{set-foo-a!}, @code{set-foo-b!}, and
@code{set-foo-c!}.
-When optional arguments are not supplied, @var{(name)} may be
+When optional arguments are not supplied, @code{(@var{name})} may be
abbreviated to @var{name}. This convention holds equally for
@var{structure-options} and @var{slot-options}. Hence, these
are equivalent:
(define-structure foo a b c)
(define-structure (foo) (a) b (c))
@end example
+
+@noindent
as are
+
@example
(define-structure (foo keyword-constructor) a b c)
(define-structure (foo (keyword-constructor)) a b c)
When specified as option values, @code{false}, @code{nil}, @code{true},
and @code{t} are treated as if the appropriate boolean constant had been
specified instead.
+@end deffn
Possible @var{slot-options} are:
-@deffn Option @code{read-only} @var{value}
-When given a value other than @code{#f}, this specifies that no
+
+@deffn {Slot Option} read-only value
+When given a @var{value} other than @code{#f}, this specifies that no
updater should be created for the slot.
@end deffn
-@deffn Option @code{type} @var{type}
+@deffn {Slot Option} type type-descriptor
This is accepted but not presently used.
@end deffn
Possible @var{structure-options} are:
+
+@deffn {Structure Option} keyword-constructor [name]
@cindex keyword constructor (defn)
-@deffn Option @code{keyword-constructor} [@var{name}]
This specifies that the constructor should parse its arguments as as a
list of keywords and values rather than by position (the default). The
keywords recognized by the constructor are exactly the names of the
@end example
@end deffn
-@deffn Option @code{type} @var{representation-type}
+@deffn {Structure Option} type representation-type
This specifies the representation type for instances of the structure,
-which are records by default. Possible values are @code{vector} and
-@code{list}. If the @code{named} option is not specified, the
-representation does not include a tag, and neither a predicate nor a
-type descriptor is generated.
+which are records by default. Possible values are the symbols
+@code{vector} and @code{list}. If the @code{named} option is not
+specified, the representation does not include a tag, and neither a
+predicate nor a type descriptor is generated.
@example
(define-structure (foo (type list)) a b)
@end example
@end deffn
-@deffn Option @code{conc-name} [@var{name}]
+@deffn {Structure Option} conc-name [name]
By default, the prefix for naming accessors and updaters is the name
of the structure followed by a hyphen. The @code{conc-name} option can
be used to specify an alternative. If @var{name} is @code{#f}, the slot
@example
@code{(define-structure (foo (conc-name moby/)) a b)}
@end example
-defines the variables @code{foo make-foo moby/a moby/b set-moby/a!
-set-moby/b! foo?}.
+
+@noindent
+defines the variables @code{foo}, @code{make-foo}, @code{moby/a},
+@code{moby/b}, @code{set-moby/a!}, @code{set-moby/b!}, and @code{foo?}.
@example
-@code{(define-structure (foo (conc-name ())) a b)}
+@code{(define-structure (foo (conc-name #f)) a b)}
@end example
-defines @code{foo make-foo a b set-a! set-b! foo?}.
+
+@noindent
+defines @code{foo}, @code{make-foo}, @code{a}, @code{b}, @code{set-a!},
+@code{set-b!}, and @code{foo?}.
@end deffn
+@deffn {Structure Option} constructor [name [argument-list]]
@cindex BOA constructor (defn)
-@deffn Option @code{constructor} [@var{name} [@var{argument-list}]]
This can be specified multiple times to build constructors with
-different argument lists, called @dfn{BOA constructor}s (By Order of
-Arguments). This facility can be extrememly useful. If @var{name} is
+different argument lists, called @dfn{BOA constructors} (By Order of
+Arguments). This facility can be extremely useful. If @var{name} is
@code{#f}, no constructor is generated. If @var{name} is unspecified,
-the constructor is named as usual. @var{argument-list} is a Scheme
+the constructor is named as usual. @var{Argument-list} is a Scheme
lambda list which may include optional and rest parameters in the usual
way. The names of the parameters must be names of defined slots.
@end example
@end deffn
-@deffn Option @code{predicate} [@var{name}]
-@var{name} specifies a new name for the predicate. If it is @code{#f},
+@deffn {Structure Option} predicate [name]
+@var{Name} specifies a new name for the predicate. If it is @code{#f},
the predicate is not generated. If @var{name} is not specified, the
predicate is named as usual.
@end deffn
-@deffn Option @code{copier} [@var{name}]
+@deffn {Structure Option} copier [name]
This specifies that a procedure should be generated to copy instances of
the structure. If @var{name} is unspecified, the copier is named by
prefixing the structure name with @code{copy-}. If @var{name} is
@code{#f}, the copier is not generated.
@end deffn
-@deffn Option @code{print-procedure} @var{expression}
+@deffn {Structure Option} print-procedure expression
The use of this option is specific to MIT Scheme. Evaluating
@var{expression} must yield a procedure of two arguments, the unparser
state and a structure instance, which is used to print instances of the
@code{unparser/standard-method}.
@end deffn
-@deffn Option @code{named} [@var{expression}]
+@deffn {Structure Option} named [expression]
This is valid only with the @code{type} option and specifies that a tag
-be included in each instance. @var{expression} is usually a variable
+be included in each instance. @var{Expression} is usually a variable
whose value is the tag, which is by default the type descriptor itself.
-@var{expression} is evaluated whenever the tag is needed and must be
-valid when the @code{define-structure} is evaluated. If
-@var{expression} returns different values from different evaluations,
-strange behavior results. For convenience, since tags may have large
-printed representations, specifying this parameter causes instances to
-print as records even though they are actually not.
+@var{Expression} is evaluated whenever the tag is needed and must be
+valid when @code{define-structure} is evaluated. If @var{expression}
+returns different values from different evaluations, strange behavior
+results. For convenience, since tags may have large printed
+representations, specifying this parameter causes instances to print
+like records even though they are not.
@end deffn
-@deffn Option @code{initial-offset} @var{offset}
-This is valid only with the @code{type} option. @var{offset} must be a
+@deffn {Structure Option} initial-offset offset
+This is valid only with the @code{type} option. @var{Offset} must be a
non-negative integer and specifies a number of slots to leave open at
the beginning of the structure before the specified slots are allocated.
+Specifying an @var{offset} of zero is equivalent to omitting the
+@code{initial-offset} option.
@end deffn
The essential differences between MIT Scheme's @code{define-structure}
and Common Lisp's @code{defstruct} are:
-@itemize @bullet
+@itemize @bullet
@item
The default constructor procedure takes positional arguments, in the
same order as specified in the definition of the structure. A keyword
@item
BOA constructors are described using Scheme lambda lists. Since there
-is nothing corresponding to &aux in Scheme lambda lists, this
+is nothing corresponding to @code{&aux} in Scheme lambda lists, this
functionality is not implemented.
@item
By default, no @code{copier} procedure is generated.
@item
-The side effect procedure corresponding to the accessor "foo" is given
-the name "set-foo!".
+The side effect procedure corresponding to the accessor @code{foo} is
+given the name @code{set-foo!}.
@item
-Keywords are just ordinary symbols -- use "foo" instead of ":foo".
+Keywords are ordinary symbols -- use @code{foo} instead of @code{:foo}.
@item
The option values @code{false}, @code{nil}, @code{true}, and @code{t}
@item
By default, named structures are tagged with a unique object of some
-kind. In Common Lisp, the structures are tagged with symbols, but that
+kind. In Common Lisp, the structures are tagged with symbols. This
depends on the Common Lisp package system to help generate unique tags;
-Scheme has no such way of generating unique symbols.
+Scheme has no such way to generate unique symbols.
@item
The @code{named} option may optionally take an argument, which is
normally the name of a variable (any expression may be used, but it is
evaluated whenever the tag name is needed). If used, structure
instances will be tagged with that variable's value. The variable must
-be defined when the defstruct is evaluated.
+be defined when @code{define-structure} is evaluated.
@item
The @code{type} option is restricted to the values @code{vector} and
@item
The @code{include} option is not implemented.
-
@end itemize
@comment **** end CLTL ****
* Fixnum and Flonum Operations:: Fixnum and Flonum Operations
@end menu
-@node Numerical types, Exactness, Numbers, Numbers
+@node Numerical types, Exactness, , Numbers
@section Numerical types
@cindex numerical types
* Flonum Operations:: Flonum Operations
@end menu
-@node Fixnum Operations, Flonum Operations, Fixnum and Flonum Operations, Fixnum and Flonum Operations
+@node Fixnum Operations, Flonum Operations, , Fixnum and Flonum Operations
@subsection Fixnum Operations
@cindex fixnum (defn)
* Character Sets:: Character Sets
@end menu
-@node External Representation of Characters, Comparison of Characters, Characters, Characters
+@node External Representation of Characters, Comparison of Characters, , Characters
@section External Representation of Characters
@cindex external representation, for character
* Byte Vectors:: Byte Vectors
@end menu
-@node Construction of Strings, Selecting String Components, Strings, Strings
+@node Construction of Strings, Selecting String Components, , Strings
@section Construction of Strings
@cindex construction, of string
* Miscellaneous List Operations:: Miscellaneous List Operations
@end menu
-@node Pairs, Construction of Lists, Lists, Lists
+@node Pairs, Construction of Lists, , Lists
@section Pairs
This section describes the simple operations that are available for
* Modifying Vectors:: Modifying Vectors
@end menu
-@node Construction of Vectors, Selecting Vector Components, Vectors, Vectors
+@node Construction of Vectors, Selecting Vector Components, , Vectors
@section Construction of Vectors
@cindex construction, of vector
* Integer Conversions of Bit Strings:: Integer Conversions of Bit Strings
@end menu
-@node Construction of Bit Strings, Selecting Bit String Components, Bit Strings, Bit Strings
+@node Construction of Bit Strings, Selecting Bit String Components, , Bit Strings
@section Construction of Bit Strings
@cindex construction, of bit string
* Weak Pairs:: Weak Pairs
@end menu
-@node Booleans, Symbols, Miscellaneous Datatypes, Miscellaneous Datatypes
+@node Booleans, Symbols, , Miscellaneous Datatypes
@section Booleans
@findex #t
* Hashing:: Hashing
@end menu
-@node Association Lists, 1D Tables, Associations, Associations
+@node Association Lists, 1D Tables, , Associations
@section Association Lists
@comment **** begin CLTL ****
* Application Hooks:: Application Hooks
@end menu
-@node Procedure Operations, Primitive Procedures, Procedures, Procedures
+@node Procedure Operations, Primitive Procedures, , Procedures
@section Procedure Operations
@deffn procedure apply procedure object object @dots{}
* Interpreter Environments:: Interpreter Environments
@end menu
-@node Environment Operations, Environment Variables, Environments, Environments
+@node Environment Operations, Environment Variables, , Environments
@section Environment Operations
Environments are first-class objects in MIT Scheme. An environment
* Port Primitives:: Port Primitives
@end menu
-@node Ports, File Ports, Input/Output, Input/Output
+@node Ports, File Ports, , Input/Output
@section Ports
@cindex port (defn)
* Output Port Primitives:: Output Port Primitives
@end menu
-@node Input Port Primitives, Output Port Primitives, Port Primitives, Port Primitives
+@node Input Port Primitives, Output Port Primitives, , Port Primitives
@subsection Input Port Primitives
@cindex input port primitives
* Directory Reader:: Directory Reader
@end menu
-@node Pathnames, Working Directory, File-System Interface, File-System Interface
+@node Pathnames, Working Directory, , File-System Interface
@section Pathnames
@comment **** begin CLTL ****
* Miscellaneous Pathnames:: Miscellaneous Pathname Functions
@end menu
-@node Filenames and Pathnames, Components of Pathnames, Pathnames, Pathnames
+@node Filenames and Pathnames, Components of Pathnames, , Pathnames
@subsection Filenames and Pathnames
Pathname objects are usually created by parsing filenames (character
@end deffn
-@node Miscellaneous Pathnames, , Operations on Pathnames, Pathnames
+@node Miscellaneous Pathnames, , Operations on Pathnames, Pathnames
@subsection Miscellaneous Pathname Functions
@cindex directory, reading
* Predefined Errors:: Predefined Errors
@end menu
-@node Simple Errors, Error Handler, Error System, Error System
+@node Simple Errors, Error Handler, , Error System
@section Simple Errors
@cindex irritants, of error (defn)
* Pictures:: Pictures (MIT 6.001 implementation only)
@end menu
-@node Opening and Closing of Graphics Devices, Coordinates for Graphics, Graphics, Graphics
+@node Opening and Closing of Graphics Devices, Coordinates for Graphics, , Graphics
@section Opening and Closing of Graphics Devices
@cindex graphics, opening and closing devices
* Custom Operations on X Graphics Devices:: Custom Operations on X Graphics Devices
@end menu
-@node X Graphics Type, Utilities for X Graphics, X Graphics, X Graphics
+@node X Graphics Type, Utilities for X Graphics, , X Graphics
@subsection X Graphics Type
@defvr {variable+} x-graphics-device-type
* Saving and Restoring Pictures:: Saving and Restoring Pictures
@end menu
-@node Construction of Pictures, Manipulating Pictures, Pictures, Pictures
+@node Construction of Pictures, Manipulating Pictures, , Pictures
@subsection Construction of Pictures
@code{make-picture} and @code{procedure->picture} are simple ways to
projects / mit-scheme.git / commitdiff